SKILL：DSH 升级的坑

⚠️ 注意：本技能沉淀自特定版本区间（0.1.7-rc.2 → 0.2.1-rc.5）。 版本号、插件名、路径都可能已过时，加载后先核对当前版本再套用，不要无脑照搬。

快速判断（30 秒）

• 升级后某个插件报错 / 消失 / 设置项空白 ⇒ 看 §3；
• 请求还没走到模型就被拒：401 或 431 ⇒ 直接跳 §4（方向别搞错）；
• 升级"完成了"，但你说不出哪里不对 ⇒ 跑 §5 冒烟清单；
• 准备升级，还在犹豫要不要备份 ⇒ 看 §2，先备份再动手。

核心原则

升级不是一个动作，是一组断言。 "应用能打开"不是升级成功的证据；能打开的只是一个进程。 真正的判据是：版本对上、插件齐、纪律仍被注入、关键命令仍可用。

1. 版本是锁步的（lockstep）

DSH 桌面应用的版本号 == 它内置的框架版本号。

• 别去比对两个"看起来不一样"的版本串——它们本来就该一样；
• 也别拿应用版本去比全局 CLI 版本，那是两个安装，可以不同步。

验证：应用关于页的版本 == dsh --version 输出的版本（至少同一 0.2.1-rc.N 段位）。 两者不一致时，先确认自己跑的是哪个 dsh：where dsh / command -v dsh。

2. 升级前必须做的三件事

1. 备份整个 ~/.dsh（至少覆盖 .credentials.yaml、profiles/、skills/、sessions/ 的索引）； 备份目录带时间戳，例如 ~/.dsh/.install-backup-YYYYMMDD-HHMMSS。
2. 导出插件清单与版本。升级后要逐条核对谁掉了、谁降级了。
3. 记录纪律文件与技能目录的哈希（AGENTS.md + skills/）。 升级后用它判断"内容被改写了"还是"引擎没加载"——这两种表现完全不同，混在一起就很难查。

3. 插件兼容性预算（硬规则）

被迫卸载的插件数 ≤ 插件总数的一半。

• 超过一半，说明这次升级和你的用法根本不兼容 ⇒ 应当回退，而不是硬扛着删。
• 每删一个都要记录：哪个插件、什么报错、有没有替代方案、能否等上游适配。
• 不允许"先删了再说"——删完你就再也描述不清当时坏在哪了。

插件安装走桌面 CLI，装完热生效，一般不用重启应用； 若新装的插件没出现，先确认装到了哪个 profile（~/.dsh/profiles/<name>/）， 再确认它是否被写进该 profile 的 cordis.patch.yml。

4. 401 / 431 不是模型的问题

这两种状态码都发生在请求到达模型之前，改 prompt / 换模型都是白费。

排查顺序：

1. 数一下请求头体积——是不是有插件在往每个请求里塞累积状态（历史、上下文快照、cookie 罐）；
2. 查凭据是否真的被读到（配置文件在 ≠ 被加载了）；
3. 装一个 header 守卫插件，把头体积截到安全线以下，别让它随会话长度线性增长。

一句话：这是头部膨胀，不是上下文太长。

5. 升级后冒烟清单（缺一不可）

1. dsh --version == 应用版本；
2. 插件列表逐条对上 §2 导出的清单（数量 + 名字 + 版本）；
3. AGENTS.md 仍然被注入——要运行态证据（新的会话转储里出现一条 role=user 的注入）， 不是"文件还在磁盘上"；
4. 随便挑一个技能的触发词，确认能被按需加载；
5. 跑一次你最常用的命令，确认不是"能启动但功能残缺"。

第 3 条最容易被跳过，也最贵：纪律悄悄失效时，你不会立刻发现， 而是在几周后奇怪"为什么它又开始乱改了"。

反模式

• ❌ 把"应用能打开"当成升级成功；
• ❌ 插件挂了就删，不记录是哪个、为什么、能不能等；
• ❌ 401/431 时去改 prompt、换模型、清上下文（方向完全错了）；
• ❌ 升级后不验证注入，只验证文件存在；
• ❌ 拿全局 CLI 版本和应用版本互相比对，然后误判"升级没成功"。

边界

• 能证明：版本是否对齐、插件是否齐全、纪律是否仍被注入、常用命令是否仍可用；
• 不能证明：新版本的行为回归（那是 change-verification-with-evidence 的事）；
• 需要人工裁决：插件超过一半不兼容时，是回退还是换方案——这个决定不该由 AI 单独做。

一句话

升级 = 一组断言，不是一个按钮。 数清楚"谁变了"，比说一句"升好了"有用得多。

实战案例与复盘

• 2026-11-04 全局 CLI 从 0.1.7-rc.2 升到 0.2.1-rc.5： 用桌面 CLI 安装、热生效；装上 dsh-auth-cookie-guard@1.0.6 压住头体积。 升级前备份到 ~/.dsh/.install-backup-<时间戳>，升级后按 §5 逐条核对。
• 431 的现场量级：头部约 40 KB 时先出现 401、约 70 KB 时出现 431 —— 这组数字是定位"是不是头在膨胀"的起点，不是精确阈值。
• 插件的 API key 不在插件设置里：在 ~/.dsh/.credentials.yaml 的 refs: 段， 写入后即时生效、不用重启。找错地方会浪费很久。