semantic-release

semantic-release

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

使用 semantic-release v25+（Node.js），遵循 2025 年最佳实践，自动化语义化版本管理和发布管理。通过 @semantic-release/exec 插件支持所有语言（JavaScript、TypeScript、Python、Rust、Go、C++ 等）。为多仓库设置创建可共享配置，为单个项目初始化自动发布，并使用 OIDC 可信发布配置 GitHub Actions 工作流。

重要：此技能仅使用 semantic-release（Node.js），不使用 python-semantic-release，即使是 Python 项目也不例外。原因：社区规模大 23.5 倍，采用率高 100 倍以上，更具长期适用性。

何时使用此技能

以下情况请调用此技能：

• 为新项目（任何语言）设置本地发布
• 创建供整个组织使用的可共享 semantic-release 配置
• 将现有项目迁移到 2025 年的 semantic-release 模式
• 排查 semantic-release 设置或版本升级问题
• 设置 Python 项目（使用 Node.js semantic-release，而非 python-semantic-release）
• 配置 GitHub Actions（可选备份，不建议作为主要方式，因为速度较慢）
• 使用 release-plz 的 Rust 工作区（参见 Rust 参考）

为什么选择 Node.js semantic-release

22,900 个 GitHub Star —— 活跃的大型社区
每周 190 万次下载 —— 已获广泛采用
126,000 个项目正在使用 —— 经大规模实践验证
35 个以上官方插件 —— 丰富的生态系统
支持多种语言 —— 通过 @semantic-release/exec 支持任何语言

不要使用 python-semantic-release。 它的社区规模小 23.5 倍（975 对比 22,900 个 Star），采用率低约 100 倍，而且与 semantic-release 组织无关。

---

发布工作流理念：本地优先

默认方式：在本地执行发布，而非通过 GitHub Actions。

为什么要在本地发布

主要原因：GitHub Actions 速度较慢

• ⏱️ GitHub Actions：发布完成需要等待 2–5 分钟
• ⚡ 本地发布：即时反馈并更新文件
• 🔄 工作流立即延续——无需等待 CI/CD

其他优势：

• ✅ 立即同步本地文件——package.json、CHANGELOG.md 和标签会立即更新
• ✅ 无需拉取——发布后无需执行 git pull 即可继续工作
• ✅ 试运行——使用 npm run release:dry 在发布前预览更改
• ✅ 可离线使用——发布不依赖 CI/CD
• ✅ 更快迭代——立即调试发布问题，而不必查看 CI 日志

GitHub Actions：仅作可选备份

GitHub Actions 工作流仅作为可选自动化方式提供，并非主要方法：

• 如有需要，可用于保持团队工作方式一致
• 本地环境不可用时可用作备份
• 因速度较慢，不建议作为主要工作流

身份验证设置

gh auth login
# Browser authentication once
# Credentials stored in keyring
# All future releases: zero manual intervention

这是在本地使用 semantic-release 并启用 GitHub 插件功能所需的最少人工干预。

通过 mise [env] 进行多账号身份验证

对于使用多个 GitHub 账号的设置，可使用 mise [env] 按目录设置 GH_TOKEN：

# ~/your-project/.mise.toml
[env]
GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"
GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"

这会覆盖 gh CLI 的全局身份验证，确保 semantic-release 为每个目录使用正确的账号。

完整设置请参阅 mise-configuration 技能。

mise 任务检测

当 .mise.toml 中包含发布任务时，优先使用 mise run，而不是 npm run：

优先级	条件	命令
1	.mise.toml 中包含 [tasks.release:*]	mise run release:version
2	package.json 中包含 scripts.release	npm run release
3	全局 semantic-release	semantic-release --no-ci

完整的 mise 工作流示例，请参阅 Python 指南。

GitHub Actions 政策

严重警告：GitHub Actions 中不得进行测试或 lint。 完整政策请参阅 CLAUDE.md。

禁止	允许
pytest、npm test、cargo test	semantic-release
ruff、eslint、clippy、prettier	CodeQL、npm audit
mypy	部署、Dependabot

---

职责分离（4 层架构）

semantic-release 配置遵循分层、可组合的模式：

第 1 层：技能 - ${CLAUDE_PLUGIN_ROOT}/skills/semantic-release/（通用模板，系统级工具） 第 2 层：用户配置 - ~/semantic-release-config/（@username/semantic-release-config） 第 3 层：组织配置 - npm registry（@company/semantic-release-config） 第 4 层：项目配置 - 项目根目录中的 .releaserc.yml

配置优先级

Level 4 (Project) → overrides → Level 3 (Org) → overrides → Level 2 (User) → overrides → Defaults

---

Conventional Commits 格式

semantic-release 会分析提交消息以确定版本升级幅度：

<type>(<scope>): <subject>

版本升级规则（默认）

• feat: → MINOR 版本升级（0.1.0 → 0.2.0）
• fix: → PATCH 版本升级（0.1.0 → 0.1.1）
• BREAKING CHANGE: 或 feat!: → MAJOR 版本升级（0.1.0 → 1.0.0）
• docs:、chore:、style:、refactor:、perf:、test: → 不升级版本（默认情况下）

发布说明的可见性（重要）

警告：@semantic-release/release-notes-generator（Angular 预设）只会在发布说明中包含以下类型：

• feat: → 功能部分
• fix: → 错误修复部分
• perf: → 性能改进部分

其他类型（docs:、chore:、refactor: 等）在配置后会触发发布，但不会出现在发布说明中。

建议：对于需要在发布说明中显示的文档变更，请使用：

fix(docs): description of documentation improvement

这样可确保提交显示在“错误修复”部分，同时在语义上仍然准确（修正文档缺漏属于修复）。

Marketplace 插件配置（始终升级版本）

对于 Claude Code marketplace 插件，每次变更都需要升级版本，用户才能收到更新。

选项 A：可共享配置（如果已发布）

# .releaserc.yml
extends: "@terryli/semantic-release-config/marketplace"

选项 B：内联配置

# .releaserc.yml
plugins:
  - - "@semantic-release/commit-analyzer"
    - releaseRules:
        # Marketplace plugins require version bump for ANY change
        - { type: "docs", release: "patch" }
        - { type: "chore", release: "patch" }
        - { type: "style", release: "patch" }
        - { type: "refactor", release: "patch" }
        - { type: "test", release: "patch" }
        - { type: "build", release: "patch" }
        - { type: "ci", release: "patch" }

配置后的结果：

提交类型	发布类型
feat:	minor（默认）
fix:、perf:、revert:	patch（默认）
docs:、chore:、style:、refactor:、test:、build:、ci:	patch（已配置）

Marketplace 插件需要这样配置的原因：插件更新通过版本标签分发。如果不升级版本，即使内容已修改，运行 /plugin update 的用户也看不到任何变更。

必须：每次发布都必须递增版本号

发布前验证：运行 semantic-release 前，请确认自上次标签以来存在可发布的提交。未递增版本号的发布无效。

自主检查顺序：

1. 列出自上次标签以来的提交：将 HEAD 与最新版本标签进行比较
2. 识别提交类型：检查是否带有 feat:、fix: 或 BREAKING CHANGE: 前缀
3. 如果未找到可发布的提交 → 停止 - 不要继续发布
4. 告知用户："自上次发布以来没有可提升版本号的提交。请为可发布的变更使用 feat: 或 fix: 前缀。"

提交类型选择指南：

• 对改进现有行为的任何变更（错误修复、增强、影响使用方式的文档更正），使用 fix:
• 对新功能或重大新增内容，使用 feat:
• 仅对确实不值得发布的变更使用 chore:、docs:、refactor:

为何重要：未递增版本号的发布会造成混乱——用户无法区分不同版本，包管理器可能会缓存旧版本，变更日志条目也会失去意义。

MAJOR 版本破坏性变更确认

触发条件：提交中包含 BREAKING CHANGE: 页脚或 feat!: / fix!: 前缀。

检测到 MAJOR 变更时，此技能会运行一个分 3 个阶段的确认工作流：

1. 检测：扫描提交中的破坏性变更标记
2. 分析：并行启动 3 个子 Agent（用户影响、API 兼容性、迁移）
3. 确认：通过 AskUserQuestion 提供继续、降级或中止选项

完整详情（包括子 Agent 提示词、决策树和输出示例），请参阅 MAJOR 确认工作流。

示例

功能（MINOR）：

feat: add BigQuery data source support

错误修复（PATCH）：

fix: correct timestamp parsing for UTC offsets

破坏性变更（MAJOR）：

feat!: change API to require authentication

BREAKING CHANGE: All API calls now require API key in Authorization header.

---

文档链接

自动将文档变更纳入发布说明。添加到 .releaserc.yml：

- - "@semantic-release/exec"
  - generateNotesCmd: "node plugins/itp/skills/semantic-release/scripts/generate-doc-notes.mjs ${lastRelease.gitTag}"

可检测：ADR、设计规范、技能、插件 README。请参阅 文档发布关联。

注意：@semantic-release/exec 插件使用 Lodash 模板（${var}）。这与 bash 默认语法（${VAR:-default}）和子 shell 语法（$(cmd)）冲突。首选解决方法：如果任务运行器已经处理发布后的步骤，请完全移除 successCmd。请参阅故障排除：Lodash 模板冲突。

---

快速开始

前提条件

检查	命令	解决方法
gh CLI 已通过身份验证	gh auth status	gh auth login
目录使用 GH_TOKEN	gh api user --jq '.login'	请参阅身份验证
Git 远程地址为 HTTPS	git remote get-url origin	git-ssh-to-https
全局安装 semantic-release	command -v semantic-release	请参阅故障排除

初始化项目

./scripts/init-project.mjs --project   # Initialize current project
./scripts/init-project.mjs --user      # Create user-level shareable config
./scripts/init-project.mjs --help      # See all options

运行发布

优先级	条件	命令
1	.mise.toml 中有发布任务	mise run release:version / mise run release:full
2	package.json 中有脚本	npm run release:dry（预览）/ npm run release
3	全局 CLI	semantic-release --no-ci

完整的 4 阶段流程请参阅本地发布工作流。

Python 项目

semantic-release 负责版本管理。有关发布到 PyPI 的信息，请参阅 pypi-doppler skill。

版本模式（importlib.metadata - 切勿硬编码）：

from importlib.metadata import PackageNotFoundError, version
try:
    __version__ = version("your-package-name")
except PackageNotFoundError:
    __version__ = "0.0.0+dev"

完整设置（包括 Rust+Python 混合项目）请参阅 Python 项目指南。

GitHub Actions（可选）

不建议将其作为主要方式（会延迟 2-5 分钟）。依次进入 Repository Settings → Actions → Workflow permissions → 启用“Read and write permissions”。

---

参考文档

类别	参考文档	描述
设置	身份验证	HTTPS 优先的设置、多账户模式
工作流	本地发布工作流	4 阶段流程（PREFLIGHT → RELEASE → POSTFLIGHT）
语言	Python 项目	Python + Rust+Python 混合模式
	Rust 项目	release-plz、cargo-rdme README 单一事实来源（SSoT）
配置	版本对齐	Git 标签作为单一事实来源（SSoT）、清单模式
	Monorepo 支持	使用 Pants + mise 的多语言 Monorepo、pnpm/npm 工作区
高级	MAJOR 版本确认	破坏性变更分析工作流
	文档发布链接	在发布说明中自动链接 ADR/规范
帮助	故障排除	汇总所有常见问题
	演进日志	Skill 变更历史

跨 Skill 参考：

• mise-tasks skill：polyglot-affected - 完整的 Pants + mise 集成指南
• mise-tasks skill：bootstrap-monorepo - 自动化多语言 Monorepo 设置
• pypi-doppler skill - 使用 Doppler 在本地发布到 PyPI

---

变更后检查清单

修改此 Skill（semantic-release）后：

1. SKILL.md 与参考文档保持一致
2. 在“参考文档”表格中记录新增的参考文档
3. references/ 中所有引用的文件均存在
4. 将变更追加到 evolution-log.md
5. 使用 bun scripts/validate-plugins.mjs 验证
6. 运行 npm run release:dry，确认没有回归问题

---

故障排查

问题	原因	解决方案
未创建发布	自上次标记以来没有可发布的提交	为会触发版本升级的提交使用 feat: 或 fix: 前缀
版本升级不正确	提交类型不匹配	检查约定式提交格式和 releaseRules
未创建 GitHub 发布	缺少 GH_TOKEN 或权限	检查是否已设置令牌且具有 repo 范围
未更新 CHANGELOG	缺少变更日志插件	将 @semantic-release/changelog 添加到插件数组
“身份验证失败”	HTTPS 与 SSH 远程地址不匹配	转换为 HTTPS：git-ssh-to-https
未找到 semantic-release	未全局安装	npm install -g semantic-release
Gatekeeper 在 macOS 上阻止操作	Node 文件未签名	请参阅故障排查
dry-run 未显示更改	HEAD 已发布	运行发布前先创建新提交
多账户令牌冲突	目录使用了错误的 GH_TOKEN	使用 mise 配置按目录设置的 [env] 令牌

执行后反思

此技能执行完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要采用变通方法？ — 如果你不得不临时调整（使用不同的标志、增加步骤），请更新此 SKILL.md，以便下次调用时不必采用相同的变通方法。

仅在问题真实且可复现时才更新，不要根据推测更新。