Agent Handoff M5 发布验收：`CHANGES.md`、`npm pack`、`release:check` 与干净环境安装验证

背景

Agent Handoff 是一个本地运行的 AI 编程项目接力包生成器。到 M4 为止，项目已经具备：

• 仓库扫描；
• Node.js / Python / Go / Rust 技术栈与命令识别；
• --task 任务解析与 HANDOFF.md / TASK.md 生成；
• 敏感路径、字段与内容脱敏。

M5 对应的是发布验收，目标不再是继续堆新功能，而是把"作者本机里能跑"推进到"干净环境安装后也能稳定交付"。

本文记录 M5 当前已经完成的 4 个核心点：

1. 生成 .agent-handoff/CHANGES.md；
2. README 补齐安装、运行、参数、示例、限制、排错六部分；
3. npm pack --dry-run 与发布包白名单检查通过；
4. 新增 npm run release:check，自动校验 tarball、一致性、安装后版本号和 8 个预期输出文件。

1. M5 新增了什么

根据当前 README.md、CHANGELOG.md 与 docs/M5_ACCEPTANCE.md，M5 对应版本为 0.5.0，主要新增内容如下：

1.1 CHANGES.md

输出目录现在变成：

.agent-handoff/
├── HANDOFF.md
├── REPO_MAP.md
├── TASK.md
├── GIT_STATE.md
├── COMMANDS.md
├── CHANGES.md
├── REDACTION.md
└── manifest.json

CHANGES.md 的行为边界：

• Git 项目：列出未暂存修改、暂存区修改、未跟踪文件，并附带 diff 统计；
• 非 Git 项目：明确标注"无法确定本次修改范围"，不伪造。

1.2 README 六部分补齐

当前 README 已完整覆盖：

• 安装
• 运行
• 参数
• 示例
• 限制
• 排错

这使得新用户第一次拿到项目时，不需要再靠聊天记录猜怎么跑。

1.3 发布检查脚本 release:check

M5 后期又补上了：

npm run release:check

这不是普通 smoke test，而是一条面向发布候选包的验收脚本。

2. release:check 实际检查什么

从 scripts/release-check.js 当前实现来看，它会连续执行以下检查：

1. 检查已检入 tarball agent-handoff-<version>.tgz 是否存在；
2. 解压 tarball，检查打包白名单；
3. 逐字节比较 tarball 内文件和工作目录对应文件，防止打包后源码或文档又变动；
4. 在全新目录中 npm init -y + npm install <tarball>；
5. 安装后执行 agent-handoff --version，核对版本号；
6. 安装后真实运行一次，确认 .agent-handoff/ 下面 8 个预期文件全部生成。

核心代码思路如下：

const EXPECTED_OUTPUT_FILES = [
  'HANDOFF.md',
  'REPO_MAP.md',
  'TASK.md',
  'GIT_STATE.md',
  'COMMANDS.md',
  'CHANGES.md',
  'REDACTION.md',
  'manifest.json',
];

这一步解决的是发布期常见的几类问题：

• 白名单失控，把不该进包的文件打进去；
• tarball 快照过期，工作目录和发布包内容不一致；
• 安装后版本号和源码中的版本号不一致；
• 命令能执行，但交接包文件没有生成完整。

3. 我本地实际验证的结果

本次不是只根据 CHANGELOG 转述，我本地实际跑了 M5 的两个关键命令。

3.1 自动化测试

cd agent-handoff
npm test

当前结果：

• 85 项通过；
• 0 失败。

3.2 发布验收

cd agent-handoff
npm run release:check

本地实际输出确认：

• 目标版本：0.5.0
• tarball 打包文件数：12
• tarball 内容与工作目录一致
• 安装后版本：0.5.0
• 安装后生成 8 个预期文件
• 发布验收通过

4. M5 这一轮真正修的是哪些发布期问题

从当前 CHANGELOG.md 和审计记录可以看出，M5 后续不是一次性顺滑完成，而是补过几轮发布期修复，比较典型的有：

4.1 版本一致性

需要统一以下位置：

• package.json
• CLI VERSION
• pack-writer 中的 PACK_VERSION
• 示例接力包里的 manifest.json

否则会出现源码是一个版本、安装后又是另一个版本的情况。

4.2 CHANGES.md 统计准确性

M5 审计后修掉了两个容易忽略的问题：

• 未跟踪目录不能只折叠成一个目录名，要展开到具体文件；
• 同一文件既 staged 又 modified 时，总数按路径并集计数，不能重复累计。

4.3 tarball 与工作目录漂移

这是发布阶段最典型、也最容易漏掉的问题之一。

如果先执行 npm pack，后面又改了 README 或 CHANGELOG，但忘了重新打包，那么仓库里的源码和最终要交出去的 tarball 就已经不是同一个状态了。

release:check 的逐字节比较，就是专门拦这种问题。

5. 事实边界

当前可以确认的事实是：

• 版本号为 0.5.0；
• 本地 npm test 为 85/85 通过；
• 本地 npm run release:check 通过；
• 已检入 tarball 当前文件数为 12；
• 安装后能生成 8 个预期文件；
• 示例项目已经包含一份可复核的 .agent-handoff/ 产物。

当前不能扩大写法的地方也要明确：

• 这不等于已经正式发布到 npm 公网；
• 这不等于技术栈识别范围已经超出 Node.js / Python / Go / Rust；
• 这不等于工具可以识别一切发布问题，只能说明当前白名单、一致性、安装和输出完整性已纳入自动化验收。

6. 结论

M5 的价值不在于再增加一个对外可见的新功能，而在于把项目从"本地开发完成"推进到"具备交付条件"。

如果只补 README，不做安装后验证，交付仍然是不完整的；

如果只做 npm pack --dry-run，不核 tarball 和工作目录是否一致，发布快照仍然可能过期；

如果只看源码版本，不看安装后输出，工具仍然可能在别人机器上掉链子。

所以 M5 这一轮最重要的收口，其实是让下面这句话终于成立：

当前 Agent Handoff 的 0.5.0 发布候选包，不只是作者本机里能跑，而是经过打包、版本、一致性和干净环境安装验证后，能稳定生成完整接力包。

标签：Agent Handoff、Node.js、CLI、npm pack、release-check、项目交接、AI 编程