release-manager

发布管理器

自动完成整个发布周期：版本升级、变更日志、README 更新、文档同步、构建、Git 标签、GitHub 发布，以及发布到 PyPI/npm。

架构（摘要）

主 Agent 负责协调；耗时步骤（扫描文件、生成变更日志、更新文档、更新落地页）由并行子 Agent 执行，以保持上下文整洁。完整架构图、仓库同步规则和子 Agent 启动详情请参阅 references/orchestration.md。如果 Agent 工具不可用，则以内联方式运行相同逻辑。

概览

发布通常按以下顺序进行。逐步执行，每次更改前都与用户确认。**步骤 1 可以提前结束后续流程：**如果项目已经提供发布工具（.changeset、.releaserc、semantic-release、lerna.json），则交由该工具处理，并跳过步骤 2-10。

1. 发布前检查 — 工作树干净，且已与远程同步
2. 确定版本 — 分析更改并建议 semver 版本升级
3. 升级版本号 — (子 Agent) 扫描并提出版本更改建议
4. 生成变更日志 / 发布说明 — (子 Agent) 根据 Git 历史记录和 PR 生成
5. 更新 README — (子 Agent，与文档更新合并) 更新版本徽章、变更日志条目
6. 更新文档 — (子 Agent) 同步所有项目文档 6b. 更新落地页 — (子 Agent，与步骤 3-6 并行运行) 如果项目提供落地页，则更新其版本显示、下载/安装 CTA、“新增内容”和功能亮点。若没有落地页，则不执行任何操作。此步骤与文档步骤并列，不属于文档步骤的一部分。
7. 构建 — 如果项目有构建步骤，则运行
8. 提交、打标签、推送 — 创建发布提交和标签
9. GitHub 发布 — 在 GitHub 上发布并附上发布说明
10. 发布到注册表 — 发布到 PyPI 和/或 npm

前置条件

• 工作树干净（或用户已批准暂存更改）
• 本地分支已与 origin 同步（同步命令请参阅 references/orchestration.md）
• 若要发布：已配置 PyPI/npm 凭据；若要发布到 GitHub：已通过 gh CLI 进行身份验证

编辑前同步仓库（必须）

在现有仓库中创建、更新或删除文件之前，先将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，先暂存更改，再同步，然后恢复更改：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或发生变基/暂存冲突，请停止并在继续前询问用户。

---

步骤 1：发布前检查（内联）

如果检测到现有发布工具（.changeset、.releaserc、semantic-release 配置等），则交由该工具处理，而不是执行以下手动步骤 — 详见本步骤后文的“检查现有发布工具”。

确认仓库处于干净状态：

git status --porcelain
git rev-parse --abbrev-ref HEAD
git fetch origin
git status -sb

如果存在未提交的更改，询问用户是要暂存、提交还是中止。绝不要擅自丢弃工作成果。

检查现有发布工具

grep -E '"(release|version|publish)"' package.json 2>/dev/null
ls .releaserc* .changeset/ .versionrc* lerna.json 2>/dev/null

如果找到，请告知用户：“此项目使用 <tool>。我将运行其发布命令，而不是执行手动步骤。”并交由该工具处理。

---

步骤 2：确定版本（内联）

分析自上一个标签以来的更改：

git tag --sort=-creatordate | head -10
git log $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~50")..HEAD --oneline --no-merges

根据 Conventional Commits 建议版本升级：

• MAJOR — 存在任何 BREAKING: 或 !: 提交
• MINOR — 存在任何 feat: 提交（无破坏性更改）
• PATCH — 仅包含 fix:、docs:、chore:、refactor: 等提交

告知用户：“自 vX.Y.Z 以来有 N 项功能、M 个修复和 K 项破坏性更改，我建议使用 vA.B.C。请确认或调整。”如无法确定，优先选择 MINOR 而非 PATCH。

---

步骤 3–6：并行执行子 Agent

用户确认版本后，在同一轮中启动四个子 Agent（version-bumper、changelog-generator、docs-updater、landing-page-updater），并行执行。landing-page-updater 会先检查是否存在落地页；若不存在，则直接跳过。它只编辑发布说明内容，将原始版本字符串的更新留给 version-bumper，以确保二者不会修改同一行。它们完成后，可选择启动 release-reviewer 进行质量检查（它也会标记 Agent 之间的冲突）。完整的工作区设置、Agent 启动参数、结果收集、应用顺序和应用更改工作流，请参阅 references/orchestration.md。

---

步骤 7：构建（内联）

检测构建命令：

[ -f package.json ] && grep -q '"build"' package.json && echo "npm run build"
[ -f Makefile ] && grep -q '^build:' Makefile && echo "make build"
[ -f Cargo.toml ] && echo "cargo build --release"
[ -f pyproject.toml ] && echo "python -m build"

运行前询问用户。如果构建失败，则停止并协助调试，绝不要在构建失败的情况下继续。如果没有构建步骤，则跳过并告知用户。

---

步骤 8：提交、打标签、推送（内联）

暂存已更改的文件（版本更新、更新日志、README、文档）并提交：

git add <specific files that were changed>
git commit -m "chore(release): vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"

推送前确认（参阅验收标准）：

git push origin <branch>
git push origin vX.Y.Z

---

步骤 9：GitHub 发布（内联）

如果有 gh CLI，且仓库位于 GitHub 上：

gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes-file CHANGELOG.md \
  --latest

如果存在构建产物路径（.tar.gz、.zip、二进制文件、.skill 文件），请将其附加到命令末尾。将发布 URL 提供给用户。

---

步骤 10：发布到软件包注册表（内联）

如果项目会发布到 PyPI 和/或 npm，请阅读 references/publishing.md，了解完整工作流（前置要求、构建、验证、上传、发布后验证）。

---

预期输出

成功发布后，Agent 会输出以下预期内容：

Release v2.4.0 complete.

Version bumped: pyproject.toml, package.json (1.3.1 → 2.4.0)
Changelog: CHANGELOG.md updated (8 commits: 3 features, 4 fixes, 1 breaking change)
Git tag: v2.4.0 (annotated) pushed to origin
GitHub release: https://github.com/owner/repo/releases/tag/v2.4.0
Published: PyPI — https://pypi.org/project/mypackage/2.4.0/

Post-release reminders:
- [ ] Announce on Discord
- [ ] Monitor for install issues (pip install mypackage==2.4.0)

边缘情况

• 没有符合规范的提交 — 无法自动建议版本更新。显示原始提交列表，并请用户明确确认语义化版本更新。
• 未配置远程仓库 — git remote 没有返回结果。跳过推送和 GitHub 发布；仅提供创建本地标签的选项。
• 版本已发布 — PyPI/npm 上已存在目标版本（通过 pip index versions 或 npm view 检测）。中止发布步骤，并询问是再次更新版本还是跳过发布。
• 缺少构建产物 — 对于需要构建产物的项目，在 Step 7 成功之前拒绝发布。

验收标准

• 所有检测到的文件中的版本字符串均已一致更新（例如 pyproject.toml、package.json、__version__）
• CHANGELOG.md 已为发布版本添加新条目
• 已创建带注释的 git 标签并推送到 origin
• 如果有 gh，则已创建包含说明的 GitHub 发布
• 每次执行破坏性操作或会对外产生影响的操作（推送、发布、GitHub 发布）前，都会询问用户确认
• 完成后提供发布后检查清单

步骤完成报告

每个主要步骤完成后，输出状态报告。完整模板和各步骤的变体见 references/step-reports.md。简版：

◆ [Step Name] (step N of M — context)
··································································
  Check 1:    √ pass
  Check 2:    × fail — reason
  Criteria:   √ N/M met
  ____________________________
  Result:     PASS | FAIL | PARTIAL

发布后检查清单

提醒用户完成以下常见后续事项：

• 宣布发布消息（博客、社交媒体、Discord、Slack）
• 如果项目采用此约定，则将版本更新为下一个开发版本（例如 X.Y.Z-dev）
• 如果存在 GitHub 里程碑，则将其关闭
• 留意问题反馈
• 验证软件包可正常安装（pip install pkg==X.Y.Z、npm install [email protected]）

提示

• 破坏性操作或会对外产生影响的操作需经过确认：参阅验收标准
• 对于 monorepo，分别处理每个软件包的版本
• 遵循现有的 CHANGELOG 格式——只添加新条目，不要重新排版
• 如果发布过程中出现问题，协助用户回滚：在本地和远程删除标签，并还原提交

参考文件

• references/orchestration.md — 架构、仓库同步规则、并行子 Agent 工作流
• references/step-reports.md — 完整的步骤完成报告模板
• references/publishing.md — PyPI / npm 发布工作流
• agents/version-bumper.md — 用于更改版本字符串的子 Agent 提示词
• agents/changelog-generator.md — 用于生成变更日志的子 Agent 提示词
• agents/docs-updater.md — 用于更新文档的子 Agent 提示词
• agents/landing-page-updater.md — 用于更新落地页的子 Agent 提示词（如果不存在则跳过）
• agents/release-reviewer.md — 用于独立质量审查的子 Agent 提示词