dsh-upgrade-audit

English | 简体中文

dsh-upgrade-audit

审计两个 DSH 版本之间所有可被仓库外部使用者观察到的变更，并生成用户期望的报告集。此问题的固定表述为：相较于 from，to 是否包含更多变更或回退？——“更多变更”指对外可见的破坏性变更（移除导出项、重命名线路错误代码、拒绝读取某种数据格式）；“回退”指在此时间段内通过一次回退，有意撤销了 from 中存在的行为。两者都需要证据：提交消息和子 Agent 摘要都只是说法，只有在阅读两个版本的代码树（源文件或已发布的软件包）后得出的结论才算证据。

外部兼容性 = 仓库外部使用者可以观察到的一切：npm 软件包的公共 API（导出项、类型、签名、依赖项范围）、dsh CLI（命令、标志、配置档、配置键）、线路协议（SDK JSON-RPC、远程网关/BFF、ACP、钩子）、磁盘上的会话数据（JSONL 日志、SQLite 存储及其版本保护）、模型可见界面（工具名称/架构、系统提示词输出），以及 Python SDK 的预期行为。内部重构仅作为背景，不属于发现项——请汇总并计数。

注意：报告语言遵循用户使用的语言（见下文“输出约定”）；按照历史惯例，examples/ 下现有的示例报告为英文。

阶段 0 — 解析输入并选择模式

输入：两个版本标识符（接受 0.1.2-alpha.2、dsh-v0.1.2-alpha.2、dist-tag alpha/latest/next）。按具体程度从高到低选择分析模式：

1. 上下文路径 — 用户在消息中指定了 deepseek-harness 检出目录。验证：根目录下的 package.json、packages/ 和 AGENTS.md 均存在。
2. DSH_SOURCE_PATH 环境变量 — 以相同方式验证。（可选的 DSH_NPM_REGISTRY 可覆盖 npm 注册表。）
3. CWD 启发式判断 — 当前目录本身就是 deepseek-harness 检出目录（同样根据上述标记判断）。
4. npm 模式 — 以上情况均不符合时（第三方仓库的默认路径）：下载两个版本已发布的软件包进行分析。

源码模式审计 git 标签；npm 模式审计已发布的制品。审计核心（界面分析、分类、验证、报告）共用；只有制品准备和部分证据来源有所不同。选择 npm 模式前，请了解其限制：npm 版本集 ≠ git 标签集（例如，0.1.2-alpha.1 有标签，但从未发布——制品准备脚本会以已发布版本列表退出，因此应向用户说明这一差异，而不是悄悄替换版本对）；CLI 依赖闭包不包含所有可发布的软件包（SQLite 持久化后端不是 CLI 依赖；脚本会将其作为补充软件包安装）。

输出约定

所有内容都放在一个目录中：tmp/<fromNorm>-to-<toNorm>/（规范化规则：去掉 dsh-v，去掉预发布版本段中的点 — dsh-v0.1.2-alpha.1 → 0.1.2alpha1）。Source 模式会在检出目录中创建该目录（已被 git 忽略）；npm 模式会在当前项目中创建。如果目标目录已存在，很可能是之前手动制作的报告 — 请先停止并询问；不要覆盖。

产物	Source 模式	npm 模式
commits.txt、reverts.txt	来自 git；reverts 已合并到 CHANGELOG 中	来自 GitHub 比较增强信息（私有仓库则没有）
files.txt、diffstat.txt、完整 .diff	git 树差异	manifest-diff.txt（逐包清单差异）+ 已发布的软件包树 a/、b/
CHANGELOG.md	按类型分类，必须包含 Reverts 部分	有增强信息时生成；否则省略并明确说明
UPGRADE-ADAPTATION.md	审计报告（两种模式使用相同骨架）	相同；标题记录模式和版本来源

报告语言遵循用户使用的语言（examples/ 中的现有报告为英文，属于历史惯例 — 并非强制）。

阶段 1 — 准备两棵代码树

Source 模式 — 先验证纯净状态；如果合并基点不是 from 本身，就表示基线漂移：停止并报告，绝不要与不断变化的基线进行差异比较：

git merge-base <from> <to>   # must equal <from>'s commit
node <skill-dir>/scripts/gen-artifacts.mjs <from> <to> tmp/<pair>

npm 模式：

node <skill-dir>/scripts/materialize-npm.mjs <from> <to> tmp/<pair>

脚本会针对注册表解析两个版本（缺失时 → 以退出码 1 退出并列出已发布版本 — 将缺失情况告知用户），使用 --ignore-scripts 将 @deepseek-ai/dsh 的依赖闭包以及 SQLite 补充软件包安装到 a/ 和 b/，为每个 @deepseek-ai/* 软件包根据各自的清单差异生成 manifest-diff.txt，并从公开的 GitHub 仓库获取增强信息（commits.txt、reverts.txt）— 因此即使没有源代码检出，也能检测 revert。

根据统计输出确定侦察规模：≤40 个非合并提交 → 内联运行侦察范围检查清单；40–250 个 → 合并 3–4 个 facade；更多 → 使用全部六个 facade。比较密度时，打开前一对的 commits.txt — 即按时间顺序紧邻当前版本对之前的版本对，绝不要只查看 tmp/ 中最新的目录。

阶段 2 — 先确定共享事实

只运行一次并提供给每个子 Agent，避免他们分别重新推导：

• 格式保护检查 — Source 模式读取两个标签上的 SESSION_FORMAT_VERSION（packages/core/session/src/types.ts）以及 SQLite 的 SCHEMA_VERSION（packages/session/session-persistence-sqlite/src/schema.ts）；npm 模式从 dsh-session 和补充软件包已发布的 lib/*.js 中 grep 同名常量。保护检查值若跳变且没有迁移路径 = 严重数据损坏；将其放在报告开头。
• Revert 列表 — Source 模式：git log --grep='[Rr]evert' <from>..<to>；npm 模式：增强后的 reverts.txt（缺失时 → 无法检测 revert 意图；明确说明这一点，并仅执行从 from 到 to 的差异审计）。
• Python SDK — Source 模式：比较 python/；npm 模式：不属于 npm 产物范围，简要说明一句即可。

阶段 3 — 并行扫描各 facade

在一个并行批次中，为每个 facade 分配一个只读侦察 Agent；每个 Agent 都应携带阶段 2 的共享事实，以及 references/audit-playbook.md 中的输出约定：各部分依次为 REMOVED（第一部分 — 候选破坏性变更/reverts）、CHANGED（变更前 → 变更后）、ADDED、RENAMED；每条都要注明软件包/路径、符号或字段，以及影响范围类别（SDK 使用者 / CLI 用户 / 配置作者 / 会话数据 / 模型可见 / 协议对端 / Web UI / npm 安装程序）；最后以一行结论收尾。各 facade 在每种模式下的目标路径列表见 playbook。

Phase 4 — 发布前验证

Recon 输出只是线索，而非结论。请亲自重新验证每条 REMOVED、revert 和 wire 相关说法：源代码模式下，使用 git show <tag>:<path> / git ls-tree 对比两个标签；npm 模式下，读取两个已发布的目录树（a/node_modules/... 与 b/node_modules/...）。这一步有个切实的教训：某个 Recon Agent 曾把 alpha.1 中已经存在的包报告为“在 alpha.2 中新增”。凡是无法验证的内容，要么标记为 [INFERENCE]，要么删除。

Phase 5 — 编写 UPGRADE-ADAPTATION.md

按照 references/audit-playbook.md 中的骨架编写：标题（版本范围、统计数据、模式与来源、源代码模式纯度说明）、结论（直接回答对比问题）、§1 回退、按对使用者的影响排序的破坏性变更部分（先列出移除项，每项注明受影响对象，并附上 适配： 行）、确认未变（兼容性仍然成立的部分与破坏性变更同样重要）、边界签名表 [API surface | from | to | changed?]，以及编号迁移检查清单。完整示例见 examples/0.1.2alpha1-to-0.1.2alpha2/（一次真实的源代码模式审计）。聊天回复遵循用户使用的语言。

防护措施

• 只读：源代码模式不会触碰 tmp/<pair>/ 以外的内容；npm 模式只会写入自身的 tmp/<pair>/，并在该目录中使用 --ignore-scripts 安装——绝不把 dsh 包安装到宿主项目的 node_modules。
• 优先采用树级事实（已发布文件、双标签读取）；不要相信从日志中推断出的叙述。
• 将内部无关变动（测试、说明、i18n、样式）汇总为一个数量，不要逐项列出。
• npm 模式要如实记录其局限：没有 enrichment → 没有 git 历史；CLI tarball 仅包含 lib/（通过各 bundle 包的 cordis.patch.yml + manifest 审计配置组合）；Python SDK 不在范围内。
• 不要对 20 个提交的范围进行全面展开；也不要内联 500 个提交的范围。误判规模是审计过时或流于表面的主要原因。

与 plugin-upgrade 的关系

此技能会生成宿主版本兼容性证据（报告 + 边界签名表）；plugin-upgrade 会使用这些证据（版本变更卡片）来执行单个插件的迁移。审计结果可直接填入卡片的“实地记录”；向 plugin-upgrade 添加卡片时，请引用此技能的报告目录，而不要凭记忆复述。