用途：当 deepseek-harness 的某个变更破坏了仓库外部可感知的接口时，在引入该破坏的变更中同步撰写升级指南，说明读者从版本 vT 升级到下一版本需要做什么，不要推迟到发布准备阶段。
适用范围：仅针对升级后可被外部观察到的破坏，包括 dsh 命令、标志和 profile 名称；cordis.yml、patch、overlay 与 settings 键或其可接受取值；持久化用户数据（会话日志、SQLite 存储、用户数据目录）；TypeScript 与 Python SDK 导出、JSON-RPC、HTTP 与 ACP 消息；已发布包名与入口点。稳定前的内部 API 若所有消费者在同一变更中一并更新，则无需指南。Session 格式变更仍遵循类型确认，其指南只写读者操作并链接该记录。
位置与结构：路径为 docs/upgrade-guide/v<version>/<item>/guide.md，<version> 取撰写时根 package.json 的 version 字段（如 v0.1.7-rc.2），描述从该版本到下一版本的升级；<item> 为变更面的 kebab-case 名称。每个条目目录只含 guide.md、对应 guide.zh.md 与配对记录 guide.i18n.yaml，无索引、无附件。
维护：根版本未变时，当前版本目录描述 vT 到 master 的增量；后续变更触及已覆盖的面时需同步更新，破坏被回退时删除指南。版本号提升后旧目录冻结，新破坏写入新版本目录，不得跨多个发布撰写。
格式与校验：从模板开始。verify-upgrade-guides 要求 frontmatter 恰好含 kind: upgrade-guide 和一句说明破坏点的 description；guide.md 仅一个 # 标题，随后按序恰好含 ## Change 与 ## Migration（中文对应 ## 变更 与 ## 迁移）；guide.md 含 frontmatter 不超过 500 词。Change 说明该面的新旧行为及受影响者；Migration 列出有序步骤，指明确切文件、键、命令或符号，并说明如何确认迁移成功。超过 500 词的内容应外置：链接源码或符号、把理由移入 Agent Note、将重复机械步骤转为脚本或 dsh 命令。遵循 dsh-prose-standard，按双语配对规则在同一次变更中写中文版本，并用 pnpm run verify-translation-pairing --write docs/upgrade-guide/v<version>/<item>/guide.md 记录配对。
验证命令：pnpm run verify-upgrade-guides；pnpm run verify-translation-pairing docs/upgrade-guide/v<version>/<item>/guide.md；pnpm run verify-md-links。