release

发布技能

目的： 将项目从“代码已就绪”推进到“已打标签、由操作者推送，并在确切的标签 SHA 上验证通过”。

发布前验证、根据 git 历史生成变更日志、更新各软件包文件中的版本号、创建发布提交和附注标签、整理发布说明，以及推送后对确切 SHA 进行 CI 验证。本地准备工作可撤销。发布（包括 GitHub Release 页面）由 CI 负责。

约束

• 确保准备工作可撤销，发布由操作者掌控。 此技能可以创建本地发布产物、提交和附注标签，但绝不会推送、发布或触发 CI，因为这些操作会越过可撤销的本地边界。
• 要求确定性的发布前检查。 对已确认的版本运行完整发布检查，并将 --skip-checks 视为操作者明确选择降低保障的选项，因为未经测试的标签无法成为可信的发布边界。
• 将完成状态绑定到已打标签的提交。 记录标签 SHA、确切 SHA 的 CI 运行结果和核对结果，因为分支检查通过或未经验证的标签都无法证明发布产物已就绪。
• 确保发布声明有证据支撑。 仅根据选定的 git 范围和生成的产物来确定变更日志、发布说明、版本选择和审计内容，因为虚构或沿用旧内容的声明会误导双方受众。
• 拉响安灯前先咨询 pawl。 对发布证据的 WARN、FAIL 或 REFUTED 会自动修复并重新运行，因为常规拒绝表明准备工作尚未完成；只有真正阻碍发布的问题才能进入 HOLD 或使用辅助通道。

阻碍状态机

• 常规拒绝 — WARN|FAIL|REFUTED -> AUTO-REDO： 修复由当前流程负责的发布产物，或将缺陷退回给负责产出的 bead，然后重新运行发布前检查和 pawl；单纯的拒绝绝不会进入 HOLD，也不会使用辅助通道。
• 阻碍 — BREAKER -> HOLD -> ONE-HELPER： 当不可逆的远程操作、产物身份不明确或发布权限不可用导致无法安全推进时，暂停标签或发布指引，然后根据审计材料发起一次且仅一次的有限辅助咨询。
• 恢复 — HELPER-UNSTUCK -> AUTO-REDO： 退出 HOLD，应用有限的恢复措施，并重新完成本地验证、确切 SHA 证据核验、结果核对和 pawl 判定。
• 辅助升级 — HELPER-ESCALATE -> HUMAN： 停止自动化，并将辅助方提供的发布证据交给操作者。
• 直接转人工 — REFUSAL-LANE|EXPLICIT-JUDGMENT|EXHAUSTED-BUDGET -> HUMAN： 跳过辅助流程，直接交由操作者处理；这些是唯一直接转人工的状态。

---

快速开始

/release 1.7.0                # full release: changelog + bump + commit + tag
/release 1.7.0 --dry-run      # show what would happen, change nothing
/release --check               # readiness validation only (GO/NO-GO)
/release                       # suggest version from commit analysis

---

参数

参数	必需	说明
version	否	Semver 字符串（例如：1.7.0）。如果省略，则根据提交分析给出建议
--check	否	仅验证是否就绪——不生成或写入任何内容
--dry-run	否	显示生成的变更日志和版本更新内容，但不写入
--skip-checks	否	跳过发布前验证（测试、lint）
--changelog-only	否	仅更新 CHANGELOG.md——不更新版本号、不创建提交或标签

---

模式

模式	调用方式	行为
完整发布	/release [version]	发布前检查 → 变更日志 → 发布说明 → 更新版本号 → 用户审核 → 写入 → 发布提交 → 打标签 → 推送指引 → 确切 SHA 的 CI 验证。
检查	/release --check	仅进行发布前检查；报告 GO/NO-GO。可与 /validate 组合使用。不写入任何内容。
仅更新变更日志	/release X.Y.Z --changelog-only	仅更新 CHANGELOG.md——不更新版本号、不创建提交或标签。

---

工作流

完整的逐步流程请阅读 references/release-workflow-detail.md — 包括 bash 命令、检查表、预期输出、审计记录模板和示例。下方索引仅供了解流程；Agent 必须按照 release-workflow-detail.md 执行，以确保正确。

1. 发布前检查 — 运行 scripts/ci-local-release.sh（阻断式），并检查版本、lint、测试、分支、变更日志、SBOM 和安全性。--check 模式会在此步骤后停止。
2. 确定范围 — <last-tag>..HEAD。对于非 HEAD 的发布切点，请参阅 references/release-cut-and-bump.md。
3. 读取 git 历史 — 运行 git log --oneline --no-merges <range>，并查看统计信息以消除歧义。
4. 分类和分组 — 在 CHANGELOG.md 中归为 Added / Changed / Fixed / Removed。发布说明正文根据 references/release-notes.md 使用更细致的 8 类标签。
5. 建议版本 — 有重大变更时建议 major，有新功能时建议 minor，只有修复时建议 patch。通过 AskUserQuestion 确认。
6. 生成变更日志条目 — 采用 Keep-a-Changelog 格式，使用当天日期，风格与最新的现有条目保持一致。
7. 检测并提供版本升级 — 检查通用模式（package.json、pyproject.toml 等）以及 references/release-cut-and-bump.md 中针对 AgentOps 的清单文件。
8. 用户审阅 — 显示生成的变更日志和版本差异；通过 AskUserQuestion 询问是否继续。--dry-run 会在此处停止。
9. 写入变更 — 更新 CHANGELOG.md 并编辑版本文件。
10. 生成发布说明 — 按照 references/release-notes.md 编写精选的 docs/releases/YYYY-MM-DD-v<version>-notes.md。必须在发布提交前将其暂存。
11. 写入审计记录 — 使用 scripts/resolve-release-artifacts.sh 解析 docs/releases/YYYY-MM-DD-v<version>-audit.md。格式见 workflow-detail 第 16 步。
12. 发布提交 — 暂存所有发布产物后，运行 git commit -m "Release v<version>"。
13. 打标签 — 运行 git tag -a v<version> -m "Release v<version>" 创建附注标签。
14. GitHub Release（由 CI 处理） — 不要在本地运行 gh release create；GoReleaser 是唯一的创建者。
15. 推送后验证精确 SHA 的 CI 并核对结果 — 操作者推送后，必须确认 scripts/verify-release-ci.sh v<version> 输出 GO release-ci，并且 ao reconcile --json | bash skills/release/scripts/validate-reconcile.sh "v<version>" 针对该精确的预期标签通过；仅通过精确 SHA 的 CI 验证，绝不意味着可以结束流程。
16. 发布后指引 — 显示推送命令和验证命令；不要推送。
17. 审计记录格式 — Markdown 模板见 workflow-detail。

检查点： 写入前，确认操作者已批准所显示的变更日志和版本差异；交接前，证明发布提交、附注标签、审计记录和发布说明中的版本一致；推送后，必须完成精确 SHA 的 CI 验证和结果核对，才能宣布完成。

---

边界

此技能的功能

• 发布前验证（测试、lint、工作区干净、版本、分支）
• 根据 git 历史生成变更日志
• 根据提交分类建议 Semver 版本
• 升级软件包文件中的版本字符串
• 创建发布提交和附注标签
• 为 GitHub Release 页面编写发布说明（亮点和变更日志）
• 为 CI 精选发布说明，以便发布到 GitHub Release 页面
• 提供发布后指引和精确 SHA 的 CI 验证说明
• 审计记录

此技能不做什么

• 不发布——不执行 npm publish、cargo publish、twine upload。这由 CI 处理。
• 不构建——不执行 go build、npm pack、docker build。这由 CI 处理。
• 不推送——不执行 git push 或 git push --tags。由用户决定何时推送。
• 不触发 CI——标签推送（由用户执行）会触发 CI。
• 不处理单体仓库的多版本——一个版本、一份变更日志、一个标签。这是 v2 的范围。

此技能所做的一切都在本地进行，且可撤销：

• 变更日志有误 → 编辑文件
• 版本号递增有误 → git reset HEAD~1
• 标签有误 → git tag -d v<version>
• 发布说明有误 → 推送前编辑 docs/releases/*-notes.md

---

通用规则

• 不要臆造——仅记录 git log 显示的内容
• 最终输出中不包含提交哈希
• 最终输出中不包含作者姓名
• 简洁——每条要点一句话，兼具技术性与可读性
• 灵活适配，不强加格式——遵循项目现有风格，而非强行套用特定格式
• 由用户确认——先展示草稿，未经确认绝不撰写
• 仅限本地——绝不推送、发布或触发远程操作
• 打标签并不代表完成——用户推送后，验证精确标签 SHA 对应的 validate.yml 运行结果为绿色，运行 ao reconcile --json，并在交接记录或发布审计说明中记录运行 ID、结论、协调的总体状态以及发布标签的发现状态。
• 面向两类受众——CHANGELOG.md 面向贡献者（文件路径、问题 ID、实现细节）。发布说明面向订阅者（通俗易懂的文字、用户可见的影响、不使用圈内术语）。绝不能将变更日志直接复制粘贴到发布说明中。

---

输出规范

• 路径：docs/releases/YYYY-MM-DD-v<version>-audit.md，配套文件为 docs/releases/YYYY-MM-DD-v<version>-notes.md，并带注释的引用为 refs/tags/v<version>。
• 文件名约定：YYYY-MM-DD-v<version>-audit.md 和 YYYY-MM-DD-v<version>-notes.md，其中 <version> 是已确认的 SemVer 版本号，不含重复的 v 前缀。
• **序列化／架构格式：**Markdown 审计文档，包含发布标题、日期、上一个标签、提交数、本地 CI 产物路径、版本号变更、发布前检查结果和远程 CI 结论；带注释的 Git 标签指向发布提交，结论记录精确 SHA、运行 ID、状态和结论。
• **验证器命令：**设置 VERSION="<version>"，然后运行 bash scripts/validate-release-audit-artifacts.sh --mode target --target-release "$VERSION" && bash scripts/verify-release-ci.sh "v$VERSION" && ao reconcile --json | bash skills/release/scripts/validate-reconcile.sh "v$VERSION"；命令成功本身并不足够，因为协调 JSON 必须指明完全匹配的预期标签、语义上处于绿色状态，且不包含中级／高级发布发现。
• **后续交接：**推送前，向操作人员提供发布提交 SHA、带注释的标签 SHA、审计／说明文件路径、回滚命令，以及精确的推送／验证命令；推送后，在结束处理前追加精确 SHA 对应的 CI 和协调证据。

质量检查清单

• 变更日志和说明仅包含所选 Git 范围内有依据的变更，遵循仓库风格，并分别满足贡献者和订阅者的需求。
• 版本文件、发布提交、带注释的标签、审计文档和说明均使用同一个已确认的 SemVer 版本号，并指向同一个发布边界。
• 交接前，本地完整发布验证和产物检查均已通过；操作人员推送后，精确标签对应的 CI 和协调检查均已通过。
• 常规拒绝仍处于 AUTO-REDO；HOLD 恰有一个助手，且仅在已声明的人工处理状态下才升级给操作人员。

示例

用户说： /release 1.7.0 Agent 执行发布前检查 → 读取 v1.6.0..HEAD Git 历史 → 对提交进行分类 → 起草 CHANGELOG.md 条目和精选发布说明 → 检测版本文件（package.json、version.go、插件清单）→ 提交草稿供审核 → 获得批准后，写入文件、创建发布提交、创建带注释的标签、打印推送指引，然后在用户推送后验证 scripts/verify-release-ci.sh v1.7.0，运行 ao reconcile --json，并记录运行 ID／结论及协调状态。

用户说： /release --check Agent 执行所有发布前检查，并输出 GO／NO-GO 摘要表。不写入任何内容。

用户说： /release（没有版本号） Agent 对提交进行分类并建议版本号（有破坏性变更则为 major，有新功能则为 minor，只有修复则为 patch），说明理由，然后请用户确认或修改。

用户说： /release 1.7.0 --dry-run Agent 展示变更日志条目和版本升级的预览，然后停止，不写入任何内容。

完整的逐步示例说明请参见 references/release-workflow-detail.md。

故障排查

问题	原因	解决方案
“No commits since last tag” 错误	工作树干净，没有新提交	提交待处理的更改或跳过发布
版本不匹配警告	package.json 和 go 中的版本不一致	发布前手动同步，或选定其中一个作为真实来源
发布前检查期间测试失败	之前未发现破坏性变更	修复测试，或使用 --skip-checks（不建议）
工作树不干净警告	存在未提交的更改	发布前提交或暂存更改
GitHub Release 页面正文为空	GoReleaser 与现有草稿冲突	CI 会在 GoReleaser 运行前删除现有发布；请勿在本地运行 gh release create
Agent 上的 ci-local-release.sh 卡在 agents-hash	~/.agents/patterns 内容过多	调用前设置 AGENTS_HUB_OVERRIDE=/tmp/empty-hub

完整的故障排查列表请参见 references/release-workflow-detail.md。

另请参阅

• security — 依赖项审计和漏洞扫描（整合 deps）

配置或审计支持 --check 模式的 CI 工作流（或使用精选说明的标签触发发布流水线）时，请从 references/gh-actions-ci-patterns.md（常规 CI）或 references/gh-actions-release-automation.md（标签触发、草稿流程、资源上传）中提取相关模式。生成精选发布说明文件或审计 CHANGELOG.md 是否存在偏差时，请将变更日志视为导览层，并使用 references/changelog-as-research-artifact.md 中关于结构化分节、破坏性变更提示以及说明与变更日志规则的内容。

参考文档

• references/release-workflow-detail.md — 完整的逐步流程
• references/release-cut-and-bump.md — 非 HEAD 截取和 AgentOps 专用升级目标
• references/release-notes.md — 精选说明格式和产品领域分类
• references/release-preflight-and-publishers.md
• references/release-cadence.md
• references/changelog-as-research-artifact.md
• references/gh-actions-ci-patterns.md
• references/gh-actions-release-automation.md
• references/release.feature — 可执行规范：--check 就绪状态、精选说明与 CHANGELOG 对账、由操作员执行标签／推送、精确 SHA 绿色验证（soc-qk4b）