From 2077e46a8715730488a42d2d2dd526ef321b2276 Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Mon, 2 Nov 2026 22:34:49 +0800
Subject: [PATCH] Docs: plugin upgrade discipline (hot-patched plugins and
 bridge hash check)

---
 CHANGES.md |  4 ++++
 INSTALL.md | 10 ++++++++++
 2 files changed, 14 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index d33eb2f..3c9c3ad 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -144,6 +144,10 @@ deployment 相关、docs 测试的 path.sep 枚举、NTFS 语义等）。本 for
 - **Windows git 兼容性**：MSYS bash 自带的 ucrt64 构建 git 2.56 与该 Gitea 实例的 http/2
   协议交互挂起（clone 卡死）；Git for Windows 2.39 正常。worker 用的是系统 PATH 里的 git，
   不受 MSYS 那份影响，但手工在 MSYS 环境里跑长 clone 时注意。
+- **插件不自动升级**：装时锁版本。升级纪律=一次升一个、升前看 changelog、升后跑门禁+验
+  overview；带本地热补丁的插件（如 `workbuddy-to-dsh` 桥脚本）升级会盖掉补丁，升完要重打补丁
+  并核对两侧桥脚本哈希一致（不一致时 buildDiff 判 stale，桥互杀重启）；重度依赖在跑的插件
+  没有明确收益不升。详见 INSTALL.md「插件升级纪律」。
 
 ## 已知限制
 
diff --git a/INSTALL.md b/INSTALL.md
index 956508c..7c300fa 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -50,10 +50,20 @@ dsh plugin --profile superagent add dsh-llm-pi-ai
 dsh plugin --profile superagent add dsh-pocket        # 远程访问面板（PIN 登录，Tailscale 内网可用）
 dsh plugin --profile superagent add dsh-ws-deflate    # WebSocket 压缩
 dsh plugin --profile superagent add dsh-session-keepwarm  # 会话保温
+dsh plugin --profile superagent add dsh-cost-meter    # 用量成本账本
 ```
 
+若走 WorkBuddy 额度搜索/模型，另装 `workbuddy-to-dsh`（桥进程）。
+
 服务常驻（开机自启、崩溃拉起）请自行用系统机制托管 `dsh --profile superagent --no-open`；本机用的是 Windows 计划任务每分钟健康检查，属部署侧策略，不随仓库分发。
 
+### 插件升级纪律
+
+- 插件不自动升级：装时锁版本，之后一直用那个版本；升级=手动 `dsh plugin --profile superagent add <pkg>@<新版>`。
+- **一次升一个**：升级前看 changelog，升级后跑门禁（tsc/测试/build）+ 重启 + 验 overview `problems: []`，再升下一个。
+- **带本地热补丁的插件（如 `workbuddy-to-dsh` 的桥脚本本地修改）**：升级会盖掉补丁——升完必须重新打补丁，并核对两个 profile 的桥脚本哈希一致（不一致时 buildDiff 判 stale，桥进程会互杀重启）。上游合入该补丁的版本落地前，保持现版本不动。
+- 重度依赖在跑的插件（上下文管理、模型 provider、桥）没有明确收益时不升级。
+
 ## 启动与验证
 
 ```sh