ybl2020/dsh-upgrade

dsh-upgrade

一句话：一个给 DeepSeek Harness (dsh) 用的「升级流程」技能（Skill）——让 AI agent 在升级 dsh 时，先做完整评估、交你审核、把备份做好、再动手，升级完还要拿证据证明真的成功了。

基于一次真实升级（0.1.2-rc.1 → 0.1.5-rc.1）的完整踩坑记录整理，所有结论都带实测证据。

这个技能是干啥用的

dsh 是一个 AI agent 运行环境。它可以通过 npm install -g 升级，但升级过程本身有不少隐藏陷阱：插件会在运行时才崩、原生模块会静默缺失、旧的检查方法会把成功误判成失败、会话数据格式升级后不可回退。

这个技能把「升级 dsh」这件事流程化了。装上它之后，当你说"帮我升级 dsh"，agent 会：

1. 先只读评估，产出一份《升级影响评估报告》——包括新旧版本的破坏性变更清单、你每个第三方插件和第三方技能会不会受影响、官方改了什么；
2. 把报告交给你审核，你说行才继续（未经你放行，agent 不会动手）；
3. 无条件备份你的会话数据，并附上一份回滚手册；
4. 执行升级，并排查 npm 静默跳过原生模块脚本的问题；
5. 升级后验证，用「进程 PID 变化 + 启动时间 + lsof 加载的原生模块路径」三条判据证明新进程真的跑的是新代码，再确认你的第三方插件与技能仍然可用。

核心价值：把一次"靠运气、坏了才发现"的升级，变成一次可审核、可回滚、有证据的操作。

什么时候该用它

| 场景 | 是否适用 |
|---|---|
| 准备把 dsh 升级到新版本 | ✅ 正是它的用途 |
| 担心升级会搞坏自己的第三方插件 / 技能 | ✅ 评估阶段就会逐个查 |
| 刚升级完，想确认真的成功、插件还能用 | ✅ 验证阶段可单独使用 |
| 只是想看看当前版本号 | ❌ 直接 dsh --version 即可，不需要流程 |

它解决什么问题（7 个实测坑）

| 坑 | 后果 |
|---|---|
| 第三方插件因插件 API 变更而失效，但 dsh 不强制校验 peer 依赖 | 升级时毫无报错，运行时才崩 |
| 第三方技能与第三方插件是两批完全独立的东西 | 只查插件会全漏（实测：4 个第三方插件携带 0 个技能，而用户本地有 5 个技能） |
| npm 11+ 静默跳过原生模块的 install/postinstall 脚本 | node-pty 等缺编译产物，运行时才暴露 |
| 新版 dsh web 必然要求 token，无 token 返回 401 而非 200 | 按旧写法会把成功的验证判成失败 |
| dsh --profile web --dump-config 看着像只读命令 | 实际要写 cordis.yml，在受限沙箱下直接崩 |
| 会话格式升级（如 V2→V3） | 不可降级读取，没备份就无法回滚 |
| 预发布版本 semver 规则：^0.1.2-rc.1 不匹配 0.1.5-rc.1 | 几乎所有第三方插件的 peer 都会"不满足"，容易误判为必须暂缓升级 |

升级流程长什么样

flowchart TD
subgraph P1["阶段一 · 升级前评估（只读 + 备份）"]
direction TB
A1["一 新旧版本对比 → 破坏性变更清单"]
A2["二 第三方插件影响评估"]
A3["三 第三方技能影响评估"]
A4["四 官方插件 / 技能变更汇总（仅披露）"]
A5["五 强制备份 + 回滚手册"]
A1 --> A2 --> A3 --> A4 --> A5
end

A5 --> GATE{"★★ 审核门 ★★报告交用户审核"}
GATE -- "暂缓 / 要求先处理" --> A2
GATE -- "放行" --> P2["阶段二 · 升级npm install -g + 原生模块排查"]
P2 --> P3["阶段三 · 升级后验证七 升级是否成功　八 第三方插件与技能可用"]
P3 --> OK{"全部通过?"}
OK -- 是 --> DONE(["完成"])
OK -- 否 --> RB["按回滚手册回滚"]

核心设计

- 审核门：升级是需要签字的决策，不是纯技术动作。升级前必须产出评估报告并等用户明确放行。
- 强制备份：无条件备份（与本次是否涉及数据格式升级无关，因为回滚的常见触发原因是插件不兼容），并交付文档式回滚手册。
- 区分官方与第三方：第三方逐个查兼容性；官方只做知情披露，不逐个排查。
- 两个独立维度：第三方插件与第三方技能分别评估——它们来源不同、互不覆盖。
- 证据驱动：用「PID 变化 + 启动时间 + lsof 加载的原生模块路径」证明新进程真的跑的是新代码，而不是只看版本号。

目录结构

dsh-upgrade/
├── SKILL.md                          # 流程骨架 + 审核门 + 两份交付物模板
├── README.md
├── LICENSE
└── references/                       # 按需加载的细节
├── breaking-changes.md           # 版本对比、semver 预发布陷阱、包清单 diff
├── third-party-audit.md          # 第三方插件评估 + 第三方技能评估
├── native-modules.md             # npm 11 allow-scripts 原生模块排查
└── verification.md               # 进程换新判据、会话完整性、token/401、重启流程

主干保持精简（随技能加载），深度细节放进 references/ 按需读取，避免每次调用都吃掉大量上下文。

安装

把 dsh-upgrade/ 整个目录放到你的技能目录下即可，dsh 会自动发现：

git clone https://github.com/ybl2020/dsh-upgrade.git ~/.agents/skills/dsh-upgrade
（或复制到 ~/.dsh/skills/dsh-upgrade/）

适用环境

- macOS：命令按 macOS / zsh 编写，dsh 通过 npm install -g 安装在 /opt/homebrew/lib/node_modules
- 部分步骤（npm install -g、--dump-config、备份）需要工作区外的文件写权限
- 技能面向 agent 执行：里面的命令是给 AI agent 跑的，不是逐条手工执行的教程

注意

技能内含大量本机实测结论（版本号、依赖数量、原生模块加载路径等）。这些数字会随版本变化，请按你的实际环境核对——技能正文里也反复强调了"不要写死数量"。

License

MIT

English

一句话概括： 一个 DeepSeek Harness (dsh) 升级技能，把"升级 dsh"从一场赌博变成可审查、可回滚、有证据支撑的流程。

它做什么。 当你让 agent 升级 dsh 时，它会：

1. 先做只读评估 —— 产出一份影响报告：当前版本与目标版本之间的破坏性变更、对你每个第三方插件以及第三方技能的影响，以及对官方变更的披露；
2. 等待你的批准 —— 在你明确批准报告之前，agent 不会碰任何东西；
3. 无条件备份，并交给你一份回滚手册；
4. 升级，包括检查 npm 11 会静默跳过的原生模块安装脚本；
5. 用证据验证 —— 通过 PID 变化、启动时间以及 lsof 观测到的原生模块路径，证明新进程确实在运行新代码 —— 然后确认你的第三方插件和技能仍然可用。

已记录的坑包括：dsh 不强制 peer 依赖（插件只在运行时才崩），审计插件会漏掉每一个第三方技能（它们是相互独立的集合），npm 11 会静默跳过原生模块安装脚本，dsh web 需要 token（没有就 401），--dump-config 不是只读命令，会话格式无法向下兼容读取，以及预发布 semver 规则会让 ^0.1.2-rc.1 拒绝 0.1.5-rc.1。

技能正文用中文编写；命令和路径与语言无关。

要求： macOS + 通过 npm 全局安装的 dsh。部分步骤需要会话工作区之外的写权限。

License： MIT