release

Release Skill

一个轻量、能感知仓库的发布助手。首次运行时，它会检查项目和 CI 以推导发布规则，将其存储到 .omc/RELEASE_RULE.md 供后续使用，然后依据这些规则引导你完成一次发布。

用法

/oh-my-claudecode:release [version]

• version 是可选的。如果省略，该 skill 会询问。接受 patch、minor、major，或像 2.4.0 这样的显式 semver。
• 添加 --refresh 可强制重新分析仓库，即使已存在缓存的规则文件。

执行流程

步骤 0 — 加载或构建发布规则

检查 .omc/RELEASE_RULE.md 是否存在。

如果它不存在（或传入了 --refresh）： 运行下面的完整仓库分析并写入该文件。

如果它存在： 读取该文件。然后做一次快速的增量检查——扫描 .github/workflows/（或等效的 CI 目录：.circleci/、.travis.yml、Jenkinsfile、bitbucket-pipelines.yml、gitlab-ci.yml），查找任何比规则文件中 last-analyzed 时间戳更新的修改。如果相关工作流文件发生了变化，就对这些部分重新运行分析并更新该文件。报告变更内容。

---

步骤 1 — 仓库分析（首次运行或 --refresh）

检查仓库并回答以下问题。将答案写入 .omc/RELEASE_RULE.md。

1a. 版本来源

• 找出所有包含与 package.json / pyproject.toml / Cargo.toml / build.gradle / VERSION 文件等中当前版本匹配的版本字符串的文件。
• 列出每个文件以及用于查找版本的字段或正则表达式模式。
• 检测是否存在发布自动化脚本（例如 scripts/release.*、Makefile release target、bump2version、release-it、semantic-release、changesets、goreleaser）。

1b. 注册表 / 分发

• npm（package.json 带 publishConfig 或 CI 中的 npm publish）、PyPI（pyproject.toml + twine/flit）、Cargo（Cargo.toml）、Docker（Dockerfile + push 步骤）、GitHub Packages、其他。
• 是否有在 tag push 时自动发布的 CI 步骤？是哪个工作流文件和 job？

1c. 发布触发方式

• 确定是什么启动发布：tag push（v*）、手动触发（workflow_dispatch）、合并到 main/master、合并 release 分支、commit message 模式。

1d. 测试门禁

• 确定测试命令以及它在 CI 中运行的位置。
• 发布前是否要求测试通过？记录任何绕过标志。

1e. 发布说明 / 变更日志

• 是否存在 CHANGELOG.md 或 CHANGELOG.rst？
• 使用什么约定：Keep a Changelog、Conventional Commits、GitHub 自动生成、无？
• 是否有在打 tag 前提交的发布正文文件（例如 .github/release-body.md）？

1f. 首次使用者检查

• .github/workflows/（或等效位置）中是否存在发布工作流？如果不存在，标记此问题并提出为你搭建一个。
• 是否有 .gitignore 条目阻止构建产物被提交？如果没有，标记此问题。
• 是否在使用 git tag？运行 git tag --list 检查。如果不存在任何 tag，标记并解释最佳实践。

---

步骤 2 — 写入 .omc/RELEASE_RULE.md

按以下结构创建或覆盖该文件：

# Release Rules


## Version Sources


## Release Trigger


## Test Gate


## Registry / Distribution


## Release Notes Strategy


## CI Workflow Files


## First-Time Setup Gaps

---

步骤 3 — 确定版本

如果用户提供了版本参数，就使用它。否则：

1. 显示当前版本（来自主版本文件）。
2. 显示 patch、minor 和 major 分别会产生什么。
3. 询问用户使用哪一个。

验证所选版本是有效的 semver 字符串。

---

步骤 4 — 发布前检查清单

呈现一份从发布规则推导出的检查清单。至少包括：

• 本次发布预期包含的所有变更都已提交并推送
• 目标分支上的 CI 是绿色的
• 测试在本地通过（运行测试门禁命令）
• 版本号递增已应用到所有版本来源文件
• 发布说明 / 变更日志已准备好（见步骤 5）

在继续之前请用户确认，或者如果他们表示 "go ahead"，就依次执行每一步。

---

步骤 5 — 发布说明指引

帮助用户撰写优秀的发布说明。采用仓库使用的任一约定。当未检测到约定时，使用默认指引：

什么是优秀的发布说明：

• 以面向用户的变化开头，而非内部实现细节。
• 按类型分组：New Features、Bug Fixes、Breaking Changes、Deprecations、Internal / Chores。
• 对于每一项：一句话，链接到 PR 或 issue，如果是外部贡献者则注明作者。
• 破坏性变更放在最前，且必须包含迁移路径。
• 省略用户永远看不到的变化（重构、CI 调整、仅测试变更），除非它们影响构建可复现性。

示例条目格式：

### Bug Fixes
- Fix session drop on token expiry (#123) — @contributor

如果仓库使用 Conventional Commits，可根据 git log <prev-tag>..HEAD --no-merges --format="%s" 按提交类型分组生成变更日志草稿。展示给用户并让他们编辑。

---

步骤 6 — 执行发布

使用发现的规则，逐步执行：

1. 升级版本号 — 应用到每个版本源文件。
2. 运行测试 — 执行测试门禁命令。
3. 提交 — git add <version files> CHANGELOG.md 并使用 chore(release): bump version to vX.Y.Z 提交。
4. 打标签 — git tag -a vX.Y.Z -m "vX.Y.Z"（优先使用附注标签而非轻量标签）。
5. 推送 — git push origin <branch> && git push origin vX.Y.Z。
6. CI 接管 — 如果发布触发器是标签推送，提醒用户 CI 将处理其余部分（发布、创建 GitHub release）。展示预期的 CI 工作流文件。
7. 手动发布 — 如果不存在 CI 自动化，列出手动发布命令（例如 npm publish --access public、twine upload dist/*）。

---

步骤 7 — 首次设置建议

如果在步骤 1f 中发现缺口，提供具体帮助：

没有发布工作流：

你的仓库没有发布 CI 工作流。一个由 v* 标签推送触发的 GitHub Actions 工作流是最常见的最佳实践。它可以：

• 运行测试
• 发布到 npm/PyPI/等。
• 使用你的发布说明创建 GitHub Release

需要我为你的技术栈搭建 .github/workflows/release.yml 吗？

没有 git 标签：

这似乎是首次发布。Git 标签让 GitHub、npm 和其他工具能够理解你的版本历史。我们将在步骤 6 中创建你的第一个标签。

构建产物未加入 gitignore：

构建产物存在于 git 历史中或未被 gitignore。这会增大仓库体积并导致合并冲突。需要我将它们加入 .gitignore 吗？

---

步骤 8 — 验证

推送之后：

• 检查 CI 状态：gh run list --workflow=<release workflow> --limit=3（如果 gh 可用）。
• 几分钟后检查注册表（npm、PyPI）中的新版本。
• 确认已创建 GitHub Release：gh release view vX.Y.Z。

报告成功或标记任何失败。

---

备注

• 本技能不硬编码任何项目特定的版本文件或命令。一切都通过仓库检查推导。
• .omc/RELEASE_RULE.md 是本地缓存。如果你想与团队共享推导出的规则，将其提交到仓库；如果你希望它保留在本地，将其加入 .gitignore。
• 对于复杂的 monorepo 或多包工作区，本技能将检测工作区模式（npm workspaces、pnpm workspaces、Cargo workspace）并相应适配。