发布技能

通用发布工作流程，支持任何项目类型，并支持多语言更新日志。

快速开始

只需运行 /release-skills – 它会自动检测你的项目配置。

支持的项目类型

选项

工作流程

步骤 1：检测项目配置

1. 检查是否存在 .releaserc.yml（可选配置覆盖）
   • 如果存在，检查它是否定义了发布钩子
2. 通过扫描自动检测版本文件（优先级顺序）：
   • package.json (Node.js)
   • pyproject.toml (Python)
   • Cargo.toml (Rust)
   • marketplace.json 或 .claude-plugin/marketplace.json (Claude 插件)
   • VERSION 或 version.txt (通用)
3. 使用 glob 模式扫描更新日志文件：
   • CHANGELOG*.md
   • HISTORY*.md
   • CHANGES*.md
4. 通过文件名后缀识别每个更新日志的语言
5. 显示检测到的配置

项目钩子契约：

如果 .releaserc.yml 定义了 release.hooks，则保持发布工作流程通用，并将特定于项目的打包/发布委托给这些钩子。

支持的钩子：

支持的占位符：

执行规则：

• 保持技能通用：不要将此技能中硬编码注册表/包管理器/项目布局细节。
• 如果存在 prepare_artifact，则在需要最终可发布目标状态的发布前检查之前，为每个目标运行一次。
• 将发布说明写入临时文件，并将该文件路径传递给 publish_artifact；不要将多行更新日志文本内联到 shell 命令中。
• 如果钩子不存在，则回退到默认的、与项目无关的发布工作流程。

语言检测规则：

更新日志文件遵循模式 CHANGELOG_{LANG}.md 或 CHANGELOG.{lang}.md，其中 {lang} / {LANG} 是语言或地区代码。

常见语言代码：zh (中文), ja (日文), ko (韩文), de (德文), fr (法文), es (西班牙文)。

输出示例：

检测到的项目：
  版本文件：package.json (1.2.3)
  更新日志：
    - CHANGELOG.md (en)
    - CHANGELOG.zh.md (zh)
    - CHANGELOG.ja.md (ja)

步骤 2：分析自上次标签以来的变更

LAST_TAG=$(git tag --sort=-v:refname | head -1)
git log ${LAST_TAG}..HEAD --oneline
git diff ${LAST_TAG}..HEAD --stat

按常规提交类型分类：

破坏性变更检测：

• 提交消息以 BREAKING CHANGE 开头
• 提交正文/页脚包含 BREAKING CHANGE：
• 移除了公共应用程序编程接口，重命名了导出，更改了接口

如果检测到破坏性变更，警告用户：”检测到破坏性变更。考虑主版本号升级（–major 标志）。”

步骤 3：确定版本升级

规则（按优先级顺序）：

1. 用户标志 --major/--minor/--patch → 使用指定的升级
2. 检测到破坏性变更 → 主版本号升级（1.x.x → 2.0.0）
3. 存在 feat： 提交 → 次版本号升级（1.2.x → 1.3.0）
4. 否则 → 修订版本号升级（1.2.3 → 1.2.4）

显示版本变更：1.2.3 → 1.3.0

步骤 4：生成多语言更新日志

对于每个检测到的更新日志文件：

1. 从文件名后缀识别语言
2. 检测第三方贡献者：
   • 检查合并提交：git log ${LAST_TAG}..HEAD --merges --pretty=format："%H %s"
   • 对于每个合并的拉取请求，通过 gh pr view <number> --json author --jq '.author.login' 识别拉取请求作者
   • 与仓库所有者进行比较（gh repo view --json owner --jq '.owner.login'）
   • 如果拉取请求作者 ≠ 仓库所有者 → 第三方贡献者
3. 以该语言生成内容：
   • 章节标题使用目标语言
   • 变更描述用目标语言自然书写（非翻译）
   • 日期格式：YYYY-MM-DD（通用）
   • 第三方贡献：在更新日志条目后附加贡献者归属 (by @username)
4. 插入到文件开头（保留现有内容）

章节标题翻译（内置）：

更新日志格式：

## {版本号} - {YYYY-MM-DD}

### 新功能
- 新功能描述
- 第三方贡献描述 (by @用户名)

### 修复
- 修复描述

### 文档
- 文档变更描述

仅包含有变更的章节。省略空章节。

第三方归属规则：

• 仅为非仓库所有者的贡献者添加 (by @用户名)
• 使用带 @ 前缀的 GitHub 用户名
• 放置在更新日志条目行的末尾
• 对所有语言一致应用（始终使用 (by @用户名) 格式，不翻译）

多语言示例：

英文 (CHANGELOG.md)：

## 1.3.0 - 2026-01-22

### Features
- Add user authentication module (by @contributor1)
- Support OAuth2 login

### Fixes
- Fix memory leak in connection pool

中文 (CHANGELOG.zh.md)：

## 1.3.0 - 2026-01-22

### 新功能
- 新增用户认证模块 (by @contributor1)
- 支持 OAuth2 登录

### 修复
- 修复连接池内存泄漏问题

日文 (CHANGELOG.ja.md)：

## 1.3.0 - 2026-01-22

### 新機能
- ユーザー認証モジュールを追加 (by @contributor1)
- OAuth2 ログインをサポート

### 修正
- コネクションプールのメモリリークを修正

步骤 5：按技能/模块分组变更

分析自上次标签以来的提交，并按受影响的技能/模块分组：

1. 识别每个提交中更改的文件
2. 按技能/模块分组：
   • skills/<技能名称>/* → 归入该技能下
   • 根文件 (CLAUDE.md 等) → 归入”项目”
   • 一个提交中涉及多个技能 → 拆分为多个组
3. 对于每个组，识别需要更新的相关自述文件

分组示例：

baoyu-cover-image：
  - feat： add new style options
  - fix： handle transparent backgrounds
  → 自述文件更新：options table

baoyu-comic：
  - refactor： improve panel layout algorithm
  → 无需更新自述文件

project：
  - docs： update CLAUDE.md architecture section

步骤 6：分别提交每个技能/模块

对于每个技能/模块组（按变更顺序）：

1. 检查是否需要更新自述文件：
   • 扫描 README*.md 以查找提及此技能/模块的地方
   • 验证选项/标志是否正确记录
   • 如果语法更改，更新使用示例
   • 如果行为更改，更新功能描述
2. 暂存并提交：

   git add skills/<技能名称>/*
   git add README.md README.zh.md  # 如果为此技能更新了这些文件
   git commit -m "<类型>(<范围>): <有意义的描述>"
   

3. 提交消息格式：
   • 使用常规提交格式：<类型>(<范围>): <描述>
   • <类型>：feat, fix, refactor, docs, perf 等
   • <范围>：技能名称或 “project”
   • <描述>：清晰、有意义的变更描述

示例提交：

git commit -m "feat(baoyu-cover-image): add watercolor and minimalist styles"
git commit -m "fix(baoyu-comic): improve panel layout for long dialogues"
git commit -m "docs(project): update architecture documentation"

常见自述文件更新需求：

步骤 7：生成更新日志并更新版本

1. 生成多语言更新日志（如步骤 4 中所述）
2. 更新版本文件：
   • 读取版本文件 (JSON/TOML/文本)
   • 更新版本号
   • 写回文件（保留格式）

各文件类型的版本路径：

步骤 8：用户确认

在创建发布提交之前，要求用户确认：

使用 AskUserQuestion 提出两个问题：

1. 版本升级（单选）：
   • 显示基于步骤 3 分析的推荐版本
   • 选项：推荐（带标签）、其他语义化版本选项
   • 示例：1.2.3 → 1.3.0 (推荐)， 1.2.3 → 1.2.4， 1.2.3 → 2.0.0
2. 推送到远程（单选）：
   • 选项：”是，提交后推送”，”否，仅保留在本地”

确认前输出示例：

已创建的提交：
  1. feat(baoyu-cover-image)： add watercolor and minimalist styles
  2. fix(baoyu-comic)： improve panel layout for long dialogues
  3. docs(project)： update architecture documentation

更新日志预览 (en)：
  ## 1.3.0 - 2026-01-22
  ### Features
  - Add watercolor and minimalist styles to cover-image
  ### Fixes
  - Improve panel layout for long dialogues in comic

准备创建发布提交和标签。

步骤 9：创建发布提交和标签

用户确认后：

1. 暂存版本和更新日志文件：

   git add <版本文件>
   git add CHANGELOG*.md
   

2. 创建发布提交：

   git commit -m "chore: release v{版本号}"
   

3. 创建标签：

   git tag v{版本号}
   

4. 如果用户确认，则推送（步骤 8）：

   git push origin main
   git push origin v{版本号}
   

注意：不要添加 Co-Authored-By 行。这是发布提交，不是代码贡献。

发布后输出：

已创建发布 v1.3.0。

提交：
  1. feat(baoyu-cover-image)： add watercolor and minimalist styles
  2. fix(baoyu-comic)： improve panel layout for long dialogues
  3. docs(project)： update architecture documentation
  4. chore： release v1.3.0

标签：v1.3.0
状态：已推送到 origin  # 或 "仅本地 - 准备就绪后运行 git push"

配置 (.releaserc.yml)

项目根目录中的可选配置文件，用于覆盖默认值：

# .releaserc.yml - 可选配置

# 版本文件（如果未指定，则自动检测）
version:
  file: package.json
  path: $.version  # JSON 使用 JSONPath，TOML 使用点分隔路径

# 更新日志文件（如果未指定，则自动检测）
changelog:
  files:
    - path: CHANGELOG.md
      lang: en
    - path: CHANGELOG.zh.md
      lang: zh
    - path: CHANGELOG.ja.md
      lang: ja

  # 章节映射（常规提交类型 → 更新日志章节）
  # 使用 null 可在更新日志中跳过该类型
  sections:
    feat: Features
    fix: Fixes
    docs: Documentation
    refactor: Refactor
    perf: Performance
    test: Tests
    chore: null

# 提交消息格式
commit:
  message: "chore: release v{version}"

# 标签格式
tag:
  prefix: v  # 结果为 v1.0.0
  sign: false

# 要包含在发布提交中的其他文件
include:
  - README.md
  - package.json

试运行模式

当指定 --dry-run 时：

=== 试运行模式 ===

检测到的项目：
  版本文件：package.json (1.2.3)
  更新日志：CHANGELOG.md (en), CHANGELOG.zh.md (zh)

上次标签：v1.2.3
提议的版本：v1.3.0

按技能/模块分组的变更：
  baoyu-cover-image：
    - feat： add watercolor style
    - feat： add minimalist style
    → 提交：feat(baoyu-cover-image)： add watercolor and minimalist styles
    → 自述文件更新：options table

  baoyu-comic：
    - fix： panel layout for long dialogues
    → 提交：fix(baoyu-comic)： improve panel layout for long dialogues
    → 无需更新自述文件

更新日志预览 (en)：
  ## 1.3.0 - 2026-01-22
  ### Features
  - Add watercolor and minimalist styles to cover-image
  ### Fixes
  - Improve panel layout for long dialogues in comic

更新日志预览 (zh)：
  ## 1.3.0 - 2026-01-22
  ### 新功能
  - 为 cover-image 添加水彩和极简风格
  ### 修复
  - 改进 comic 长对话的面板布局

将要创建的提交：
  1. feat(baoyu-cover-image)： add watercolor and minimalist styles
  2. fix(baoyu-comic)： improve panel layout for long dialogues
  3. chore： release v1.3.0

未进行任何更改。不带 --dry-run 运行以执行。

使用示例

/release-skills              # 自动检测版本升级
/release-skills --dry-run    # 仅预览
/release-skills --minor      # 强制次版本号升级
/release-skills --patch      # 强制修订版本号升级
/release-skills --major      # 强制主版本号升级（需确认）

何时使用

当用户请求以下内容时，触发此技能：

• “release”, “发布”, “create release”, “new version”, “新版本”
• “bump version”, “update version”, “更新版本”
• “prepare release”
• “push to remote”（存在未提交的更改时）

重要提示：如果用户说”just push”或”直接 push”且存在未提交的更改，仍首先遵循上述所有步骤。