给 DSH plugin 锁版本与回滚：DeepSeek Harness 插件升级策略怎么定

DSH plugin 要不要锁版本，本质是问「要可复现还是要自动跟新」——两者不可兼得。 锁定的收益是出问题时能说清上次跑的是哪一版、回滚有确定落点，代价是升级要主动做，并且要成组记录版本。本文给三种锁定方案、回滚三步验证与自动更新决策表。

为什么 DSH plugin 要锁版本：三条真实代价

一句话结论：不锁版本的代价集中在三处——不可复现、难回滚、以及「半夜升级」造成的连锁故障。

1. 不可复现：今天跑通、明天失败，而你说不清变了什么。DSH plugin 是独立发布的包，自动跟随最新就等于把上游节奏接进你的环境。
2. 难回滚：没有明确的「上一版是哪一版」，回滚只能靠猜与逐个试。
3. 连锁影响：插件之间可能有版本要求，某个体自动升上去可能触发另一批插件的兼容问题；本体（DeepSeek Harness）升级同样会影响插件兼容。
4. 代价对比要看清：锁定不是没有成本——你会暂时停在旧版，需要靠显式升级节奏补回来。

方案 A：安装时钉版本（最小改动）

一句话结论：从「装最新」改成「装到指定版本」，再避免后续自动升级——改动最小、见效最快。

1. 安装时写全版本号（@ 后接版本）：

dsh plugin add <插件包名>@<版本>
# 预期：安装输出里显示的版本与你指定的一致

2. 立即验证：

dsh plugin            # 预期：清单中该插件显示为你钉的版本

3. 避免自动升级把它拉新：检查你使用的入口是否开启了自动更新；如果开启了，按第 5 节的决策表决定是否关闭。
4. 记录到你的环境档案：包名 + 版本 + 日期，三列即可；这是回滚时的唯一凭据。

方案 B：清单化 + 定期批量升级（团队推荐）

一句话结论：把插件清单写成文件、升级当显式动作执行——在保持可复现的同时，不会因为锁定而长期停旧。

1. 维护一份清单（示例）：

# dsh-plugins.txt
<插件包名>@<版本>
<插件包名>@<版本>

2. 安装/升级脚本读清单执行，这样每台机器、每次重建都得到同一组版本：

set -euo pipefail
while read -r pkg; do
  [ -n "$pkg" ] && dsh plugin add "$pkg"
done < dsh-plugins.txt
dsh plugin        # 输出归档，作为本次状态快照

3. 升级是「改清单 + 重跑 + 记录」：改哪几个、为什么改、验证结果，写一行备注。
4. 成组升级，别只升一个：把有依赖关系的插件放在同一次升级里一起改。
5. 插件候选先用 DSH Plugin Hub 敲定——看清它最近更新的版本与说明，再决定要不要进清单。

方案 C：镜像 / 分发包承载（多机锁死）

一句话结论：把插件版本锁在镜像或分发包里，机器只消费分发物——这是多机环境下最不容易漂的一种锁法。

1. 在镜像构建阶段装清单里的插件（写法见 DeepSeek Harness 容器化安装 方案 C）。
2. 打上版本标签，分发路径写进文档；升级 = 发布新标签。
3. 旧标签保留，回滚就是切回旧标签——比在机器上逐个改版本快得多。
4. 注意数据与程序分离：插件清单锁在镜像里，但用户自己的配置与会话在数据目录里，升级镜像不应该动数据。

DSH plugin 回滚：三种做法与三步验证

一句话结论：回滚不是「删掉重装」，而是「装回上一个已知可用版本并验证」——有清单时改一行就行。

1. 做法一（清单驱动，最快）：把清单里对应行改回上一版，重跑安装脚本。
2. 做法二（单点回滚）：直接对该插件安装指定旧版本（<包名>@<旧版本>），适合只坏一个插件的场景。
3. 做法三（整组回滚）：切回上一份镜像标签或上一份清单快照，适合「多个插件同时出问题」的场景。
4. 验证三步：① 清单显示版本正确；② 重启实际入口（dsh web 或 CLI 会话）让改动生效；③ 实际调用一次该插件的核心功能——只看「装上了」不算验证通过。
5. 回滚后留记录：把「哪一版坏了、回滚到哪一版」写进备注，避免下次再踩。
6. 坏在兼容性就走另一篇：如果是插件与新版本本体不兼容（而不是你锁错了版本），按插件版本回滚与降级的流程处理。

DeepSeek Harness 要不要关掉自动更新：决策表

一句话结论：要可复现就关自动更新、改显式升级；要永远最新就保留，但必须记录版本。

1. 判断标准：问一句「如果它今晚自动升级并出故障，我明天能多快恢复？」——答不上来就关。
2. 关掉之后别忘升级：设定一个显式节奏（例如跟随本体升级时一起做），避免长期停在旧版错过修复。

DSH plugin 排查注意事项

一句话结论：锁版本相关的排查只有两条主线——「装的是不是我要的那版」与「出问题能不能回到上一版」；先把这两条做扎实，再谈优化。

1. 每次变更后立刻记录清单（包名 + 版本），这是所有回滚能力的前提。
2. 升级后必须验证功能，而不是只看安装成功。
3. 插件依赖成组考虑，避免单点锁定导致另一插件无法升级。
4. 区分「本体版本」与「插件版本」：两者都会影响兼容性，排查时别只看一边（本体侧见 CI 里更新 DeepSeek Harness 与 DSH plugin）。
5. 多机环境优先用分发物锁，比逐机改版本可靠（见 多台机器统一更新 DeepSeek Harness）。
6. 修复状态如实：本文方案基于官方 CLI 的插件子命令说明与 npm 的版本固定机制；dsh plugin 的具体参数名与是否内置自动更新开关，请以你机器上 dsh plugin --help 的输出为准——不同版本可能有差异。

清单里每个 DSH plugin 的版本，都可以对照 DSH Plugin Hub 的已安装列表复核一次——这是回滚前最快的一次状态确认。

版本号怎么理解、rc 版怎么选，见版本选择与锁定指定版本安装。

来源：apps/cli/README.md、docs/user/develop/basic/publish.md、npm Docs · package.json。