autoship

Autoship

端到端驱动 npm 发布：changeset、修复循环、推送、CI 监控、合并 Version Packages PR、监控发布、验证 npm。

• **是：**适用于现有、基于 changesets 的 npm 包的完整发布流水线，从编写 changeset 文件到确认注册表上的新版本，并诊断发布运行为何没有进行版本更新或发布。
• **不是：**创建功能 PR（使用 pr-creator）、监控功能 PR 的评审、冲突或 CI（使用 pr-babysitter）、发布流程之外的一般构建或类型修复，或搭建新包（使用 scaffold-cli，它会在首次发布时转交给 autoship）。

发布循环

一个工作流，连续运行两次。误以为这是两个工作流，是 autoship 中大多数错误的根源。

1. 将包含待处理 .changeset/*.md 文件的提交推送到默认分支。
2. 发布工作流运行：changesets/action 检测到待处理的 changeset 后，会在 CI 中运行 changeset version，并在 changeset-release/<default-branch> 分支上创建或更新 PR（标题为“Version Packages”，预发布模式下会加上“(next)”后缀），其中包含 package.json 版本更新和 CHANGELOG.md 条目。
3. 所有检查通过后，合并该 PR。
4. 同一工作流再次运行。待处理的 changeset 已清空后，该 Action 会运行其发布脚本（changeset publish），将包发布到 npm，并默认推送 git 标签和创建 GitHub release。

本地工作到“推送 changeset 文件”为止。版本更新和发布由 CI 负责。

该 Action 有两个在用的主版本，输入名称不同：@v1 使用 publish:，@v2 使用 publish-script:。诊断版本已更新但从未发布的运行时，先查看 uses: 行。

参考文件

文件	何时阅读
references/changeset-and-commit.md	步骤 1-3：编写 changeset 文件、发现并以非交互方式运行检查、暂存发布提交
references/ci-polling.md	步骤 4 和步骤 5 的监控：Monitor 工具、提交监控脚本、失败分类、Changeset Status 检查
references/version-pr-and-publish.md	CI 全部通过后：工作流结构、查找并合并 Version Packages PR、发布运行、npm 验证、发布失败诊断
evals/evals.json	仅在修改此技能时；发布期间不会加载

意图映射

意图	步骤	备注
完整 autoship（发货 / 发布 / 发布到 npm）	1-5	默认入口。端到端完成发布，不出现中间提示
仅创建 changeset	1	暂存发布，不推送
修复检查并推送	1-3	Changeset、修复、提交，不监控 CI
仅监控 CI	4-5	Changeset 已推送
仅合并 Version Packages PR	4b-5	CI 已全部通过；满足前置条件后合并
仅修复检查	2	在发布流程中进行；不需要 changeset
诊断未发布的发布流程	只读	references/version-pr-and-publish.md（PR 等待超时检查、发布失败表）

没有 npm 发布上下文的“发布它”请求会转到 pr-creator。

安全等级

调用 autoship 即表示同意执行完整发布流程。流程中途无需暂停再次确认；应根据客观前置条件把控风险较高的步骤。

• **绿色（直接执行）：**读取 CI 和 PR 状态、npm view、待处理 changeset、package.json 脚本、git 历史和状态。
• **黄色（用一行说明，然后执行）：**编写 changeset 文件、运行 lint/type/test/format 修复工具、git add/commit/push、启动监控，以及在确认 PR 身份且所有检查通过后合并 Version Packages PR。
• **红色（必须明确确认）：**强制推送、重写历史、修改仓库设置、任何破坏性 git 操作。

工作流

复制此检查清单以跟踪进度：

Autoship progress:
- [ ] Step 1: Create changeset (default patch)
- [ ] Step 2: Fix lint, types, tests, format
- [ ] Step 3: Commit and push the changeset
- [ ] Step 4a: Watch CI on the pushed commit
- [ ] Step 4b: Find and merge the Version Packages PR
- [ ] Step 5: Watch the publish run, verify on npm

步骤 1：创建 changeset（默认 patch）

• 加载 references/changeset-and-commit.md。
• 检查待处理的 changeset 及其覆盖的包。复用覆盖所需发布范围的 changeset；仅对未覆盖的变更新增一个。只有在无关的待发布版本导致发布范围不明确时才询问。
• 默认使用 patch；仅在用户明确要求时使用 minor 或 major。
• 直接写入文件（交互式提示需要 TTY）；摘要应是面向用户的变更日志文本，并根据 git log --oneline -10 推断。
• pnpm changeset status 会验证文件：包名拼写错误会在这里报错，而不是等到 CI 时才报错。

步骤 2：修复 lint、类型、测试和格式问题

• 从 package.json 脚本（check、lint、typecheck、test、format、fix）中查找命令；对于非 Node 仓库，检查 Makefile、Cargo.toml、pyproject.toml、go.mod。
• 运行 lint、类型检查、测试和格式检查。每次修改代码后，都从第一道检查重新运行：类型修复经常会破坏 lint，而 lint 自动修复也可能导致测试失败。
• 在支持的情况下，将自动修复器限定在变更文件范围内，然后检查 git status：宽泛的 fix／format 脚本会重新格式化变更范围之外的文件（MDX 经常受影响）。只撤销本次运行引入的修复器变更，并保留同一文件中的预先存在的编辑。
• 每道检查的修复循环最多进行 5 次，每轮都报告剩余错误数；之后停止，并报告检查项、剩余错误数和最后的错误输出。

步骤 3：提交并推送 changeset

• 按明确路径暂存 changeset 文件和范围内的修复；提交前检查 git status --porcelain，排查钩子生成的文件（根目录中的 schema.gql 是已知情况）。
• 提交（chore: add <type> changeset for <package>）并推送。
• 推送的提交必须仍包含 .changeset/*.md（第一个注意事项）。

步骤 4a：监控推送提交的 CI

• 加载 references/ci-polling.md。
• 开始监控推送的 SHA。每次状态变化都会输出一行；该提交的所有运行（CI 和发布工作流）都完成后，会输出一行 TERMINAL:。首次轮询时没有变化属于正常情况；运行需要时间排队。
• 失败时，根据 gh run view <id> --log-failed 判断原因：对于偶发故障或基础设施问题，运行 gh run rerun <id> --failed（最多 3 次）；对于真实故障，修复后提交并推送，然后监控新 SHA。

步骤 4b：查找并合并 Version Packages PR

• 加载 references/version-pr-and-publish.md。
• 查找 head 为 changeset-release/<default-branch> 的开放 PR。若不存在，运行 PR 等待监控（最多 10 分钟）。
• 仅当以下三项全部满足时才合并：
  • Head 分支为 changeset-release/<default-branch>（标题通常为 “Version Packages”，但 pr-title 可以重命名标题）。绝不要合并其他 PR。
  • gh pr checks <n> --json name,bucket 显示每项检查的 bucket: pass。
  • gh pr view <n> --json mergeable 显示 MERGEABLE（若为 UNKNOWN，请等待后重新查询）。
• 宣布（“正在合并 Version Packages PR #N：@”），然后运行 gh pr merge <n> --squash --delete-branch，或使用仓库允许的合并方式。任何前置条件未满足：停止并报告，绝不要合并。

步骤 5：监控发布运行，并在 npm 上验证

• 合并会再次触发同一工作流；若没有待处理的 changeset，就会发布。
• 获取合并 SHA（gh pr view <n> --json mergeCommit --jq .mergeCommit.oid），并开始监控该 SHA。
• 失败时：读取日志，与 references/version-pr-and-publish.md 中的发布失败表进行匹配，报告后停止。绝不要盲目重试发布失败；该表中的每种原因都需要修改配置或设置。
• 成功时：npm view <package>@<version> version 必须输出已合并的版本，且 npm view <package> dist-tags 必须显示 latest 指向该版本（除非处于 pre 模式）。停止其余监控，并报告这两条命令的输出；它们是完成的凭据。

故障恢复

如果某个门禁在 5 次迭代后仍然失败，或任何合并前置条件失败，请停止并报告；绝不要绕过失败的检查，也不要在机器人 PR 中解决冲突。各阶段的诊断信息分别见：references/ci-polling.md 中的 CI 和 Changeset Status 故障，以及 references/version-pr-and-publish.md 中缺少 Version Packages PR 和发布失败的问题。

注意事项

• 绝不要在本地运行 pnpm changeset version。 它会消耗 .changeset/*.md，导致推送的提交中没有待处理的 changeset、“Changeset Status”失败，也不会打开 Version Packages PR。恢复方法是撤销版本升级，而不是重新运行 CI。
• 绝不要直接运行 pnpm publish 或 npm publish。这会绕过 changesets，跳过变更日志和标签，并导致 Version Packages PR 描述的版本已经发布，随后失败并提示“You cannot publish over the previously published versions”。
• 绝不要手动编辑 CHANGELOG.md 或 package.json 中的 version。CI 会在 Version Packages PR 中生成这两项内容；本地编辑会使机器人 PR 变为 CONFLICTING。
• changesets/action@v2 重命名了所有输入项（publish 改为 publish-script，version 改为 version-script，title 改为 pr-title，commit 改为 commit-message，branch 改为 pr-base-branch）。旧名称会被忽略，且只发出警告，因此仍使用 publish: 的 @v2 工作流会打开 Version PR，然后以绿色状态完成，却不会发布任何内容。
• 使用 node-version: 22 的 setup-node 会附带 npm 10.9.x。可信发布需要 npm 11.5.1 或更高版本，因此即使设置了 id-token: write，changeset publish 仍会失败并提示 ENEEDAUTH（pnpm 会将上传操作交给 PATH 中的 npm CLI）。请使用 Node 24，或在发布前添加 npm install -g npm@latest。
• 使用包含经典令牌的 NPM_TOKEN 密钥进行身份验证的工作流会失败并提示 ENEEDAUTH：npm 已于 2025 年 12 月 9 日撤销所有经典令牌。请改用可信发布，而不是创建新令牌；具备写入权限的细粒度令牌有效期不超过 90 天。
• 保存可信发布方设置时，npm 不会对其进行验证。如果工作流文件名与 .github/workflows/<file>.yml 的大小写或扩展名不同，只有在发布时才会报错，提示 ENEEDAUTH。
• 新建的个人仓库会阻止 Actions 打开 PR。发布运行会失败并提示“GitHub Actions is not permitted to create or approve pull requests”，也不会出现 Version PR。修复方法：依次前往 Settings、Actions、General，启用“Allow GitHub Actions to create and approve pull requests”（组织级设置可能会覆盖此设置）。红色等级：请报告问题，不要在未获请求的情况下更改设置。
• gh pr list --json headBranch 和 gh pr checks --json conclusion 使用了无效字段，会报错。请改用 headRefName 和 bucket。
• Monitor 工具的默认 timeout_ms 为 300000（5 分钟）。如果 CI 运行时间超过此值，监视会因超时而终止，看起来就像没有任何响应。监视 CI 时请传入 timeout_ms: 3600000。
• 轮询间隔至少为 30 秒。更频繁的循环会耗尽 GitHub API 速率限制（gh api rate_limit --jq .resources.core.remaining），并使发布流程中途停滞。
• git add -A 会将提交前钩子生成的产物和修复工具造成的改动一并提交到发布提交中。请明确暂存具体路径。
• 未经明确指示，major 意味着会对所有使用方造成破坏性变更。默认使用 patch。

相关技能

• scaffold-cli：使用 changesets 和 OIDC 发布功能搭建新的 TypeScript 包，然后交由 autoship 完成首次发布。
• pr-creator：打开功能 PR。Autoship 只会合并机器人打开的 Version Packages PR。
• pr-babysitter：监视功能 PR（评审、冲突、CI）。Autoship 只监视发布 CI；绝不要照看 autoship 正在处理的 Version Packages PR。