分享一个 dsh 升级流程技能：升级前评估 → 审核放行 → 升级 → 验证（附 7 个实测坑）

[ybl2020]

升级 dsh 时踩了几个坑，整理成了一个升级流程技能，分享给同样要升级的人。

这个技能做什么

把「升级 dsh」变成一个可审核、可回滚、有证据的流程，而不是一次靠运气的操作：

升级前评估 → ★用户审核放行★ → 升级 → 升级后验证

• 审核门：先只读评估，产出《升级影响评估报告》交你审核；你没放行，agent 不会动手
• 无条件备份 + 回滚手册：备份会话数据并校验数目一致，回滚手册作为报告附件交付
• 第三方插件 与 第三方技能 分别评估：两者来源不同、互不覆盖
• 官方项仅做知情披露，不逐个排查
• 证据驱动验证：PID 变化 + 启动时间 + lsof 实际加载的原生模块路径，三判据证明新进程真的在跑新代码

7 个实测坑

基于 0.1.2-rc.1 → 0.1.5-rc.1 的一次真实升级，按踩到的顺序：

1. dsh 不强制校验 peer 依赖 —— 插件 peer 不满足时升级过程毫无报错，运行时才崩。
2. 只查插件会漏掉全部第三方技能 —— 实测 4 个第三方插件携带 0 个技能，而用户本地有 5 个技能，两者是完全独立的两批东西。顺带一提，本技能的前一版自己就因版本升级而失效（写死了 401 期望、漏了 --no-open、依赖数量写死）。
3. npm 11+ 会静默跳过原生模块的 install/postinstall 脚本 —— 只打印一条 warning。node-pty 这类包会缺编译产物。本次实测靠加载器回退到 prebuilds/darwin-arm64/pty.node 才没出事，并用 pty.spawn 实测确认；koffi 则是自带平台包二进制。
4. dsh web 必然要求 token —— 无 token 请求返回 401 而不是 200，token 是内存态（launchToken，randomBytes 生成、进程内 Map 缓存、从不落盘），只在启动时随 URL 打印一次。按旧写法用 curl 判断 200 会把成功判成失败。
5. dsh --profile web --dump-config 不是只读命令 —— 它要写 ~/.dsh/profiles/<p>/cordis.yml（prepareProfile 里的 writeFileSync），在受限沙箱下直接 EPERM 崩掉。而且这个 EPERM 长得很像文件属主问题，实际是沙箱拒绝。
6. 会话格式 V2→V3 不可降级读取 —— 迁移会生成新文件并保留原文件，且是懒加载（只迁移被打开的会话）。没有备份就无法回滚。
7. 预发布版本的 semver 陷阱 —— ^0.1.2-rc.1 在数学上不匹配 0.1.5-rc.1：只有当范围里存在与目标版本同一 [major,minor,patch] 元组的预发布比较器时才可能满足。所以几乎所有把 @deepseek-ai/* 钉在 ^0.1.x-rc.y 的第三方插件都会报 peer 不满足 —— 这是常态而非例外。反过来说，peer 不满足 ≠ 不可用（dsh 不强制校验，dump-config 依然通过）。

仓库

https://github.com/ybl2020/dsh-upgrade （MIT）

SKILL.md 保持精简（流程骨架 + 审核门 + 两份交付物模板），深度细节放在 references/ 按需加载：版本对比 / 第三方插件与技能排查 / 原生模块 allow-scripts / 升级后验证。

说明

• 技能面向 agent 执行，里面的命令是给 agent 跑的
• 按 macOS + npm install -g 安装的 dsh 编写，部分步骤需要工作区外的文件写权限
• 文中的版本号与依赖数量都是本机实测值，会随版本变化，技能正文里也反复强调「不要写死数量」

欢迎指出与 DSH 实际行为不符的地方，我按实测更新。