release-notes

发布说明生成器

根据以下内容生成面向用户的发布说明：$ARGUMENTS

发布说明是写给人看的，不是给机器看的。目标是传达发生了哪些变化，以及这些变化为何重要——并从受众关心的角度来说明。提交记录的是代码的演变；发布说明记录的是这些变化对用户的意义。

步骤 1：解析输入

识别用户提供的内容，并据此收集原始变更数据。

版本／标签范围（匹配 v1.2.0..v1.3.0 或 1.2..1.3）：

git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE

分支比较（匹配 main..feature 或 origin/main..HEAD）：

git log --format='%H %s' $RANGE
git log --format='%B---COMMIT_BOUNDARY---' $RANGE
git diff --stat $RANGE

PR 编号（匹配 #42、#43 等）：

gh pr view <num> --json title,body,commits,labels

原始文本：如果输入不匹配以上任何模式，则将其视为对变更的直接描述。跳过 Git 命令，根据文本进行处理。也跳过步骤 2 和 3，直接进入步骤 4。

没有参数：将当前分支与基准分支进行比较：

CURRENT_BRANCH=$(git branch --show-current)
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback: try main, master, develop
git log --format='%H %s' $DEFAULT_BRANCH..$CURRENT_BRANCH
git log --format='%B---COMMIT_BOUNDARY---' $DEFAULT_BRANCH..$CURRENT_BRANCH
git diff --stat $DEFAULT_BRANCH..$CURRENT_BRANCH

步骤 2：检测平台

确定此项目托管在哪里，以及在哪里跟踪问题。这两者可能不同——项目可能在 GitHub 上托管代码，但在 Jira 中跟踪问题。

代码托管平台

解析 Git 远程地址以检测平台：

git remote get-url origin

• github.com → GitHub，使用 gh CLI
• gitlab.com（或自定义 GitLab 域名）→ GitLab，使用 glab CLI
• 其他情况 → 仅使用 Git 模式（跳过 PR／问题查询）

问题跟踪器

扫描步骤 1 中收集的提交消息，查找引用模式：

• #123 格式的引用 → 问题由代码托管平台（GitHub 或 GitLab）跟踪
• PROJ-123 格式的引用（大写字母、连字符、数字）→ Jira。如果 Atlassian MCP 工具可用，请使用它们（mcp__claude_ai_Atlassian__getJiraIssue）
• 同一个项目中可能同时出现这两种格式，请同时检查

如果平台工具不可用或身份验证失败，请妥善回退到仅使用 Git 的模式。不要因此阻塞流程。

步骤 3：深入调查——追踪引用

这一步能将提交日志改写成真正的发布说明。提交告诉你代码“改了什么”。PR 告诉你“为什么要改”。问题告诉你“是谁提出的，以及他们遇到了什么问题”。这三者都很重要。

提取引用

扫描步骤 1 中的每条提交消息，查找：

• PR／MR 编号：#123（GitHub）、!123（GitLab）
• 问题编号：#456（GitHub／GitLab）、PROJ-789（Jira）
• 指向 PR 或问题的 URL

去重——许多提交可能引用同一个 PR。建立一份需要获取的 PR 和问题的唯一列表。

获取 PR／MR

对于每个唯一的 PR 引用：

GitHub：

gh pr view <num> --json title,body,closingIssuesReferences,labels,commits

GitLab：

glab mr view <num> --output json

仔细阅读 PR 描述——开发者会在其中说明：

• 变更的动机
• 对用户可见的影响
• 设计决策和权衡
• 截图或变更前后的对比

获取关联的问题

对于 PR 引用的问题（通过 GitHub 上的 closingIssuesReferences，或在 PR／提交文本中提及）：

GitHub：

gh issue view <num> --json title,body,labels

GitLab：

glab issue view <num> --output json

Jira： 使用 mcp__claude_ai_Atlassian__getJiraIssue，并传入问题键（例如 PROJ-789）。

问题正文中包含真正的背景信息——用户故事、包含复现步骤的错误报告，以及说明用户需求及原因的功能请求。这些内容对撰写贴近用户的发布说明极为宝贵。

构建上下文映射

对于每项逻辑上的变更，你现在最多有三层上下文：

• 提交——代码改了什么
• PR 描述——为什么要改，以及采用了什么方法
• 问题正文——最初的用户请求、错误报告或功能规格
• 标签——分类提示（错误、功能、重大变更、安全等）

并非每项变更都具备这三层信息。有些提交不会引用 PR；有些 PR 不会关联问题。使用现有信息即可——即使比提交消息多深入一层，也能大幅提升发布说明的质量。

大型版本的扩展处理

对于提交较多的版本（50 个以上），重点查询不同的 PR——大多数提交都对应少数几个 PR。如果 PR 太多，无法逐一获取，请优先处理：

1. 带有 breaking、security 或 feature 标签的 PR
2. 关闭了议题的 PR（其中包含面向用户的背景信息）
3. 描述最长的 PR（可供参考的背景信息更多）

步骤 4：了解项目

动笔之前，先了解这些说明面向哪些读者。快速浏览代码库：

1. 项目类型：查看 package.json、Cargo.toml、pyproject.toml、go.mod 或 README.md，判断项目属于库、CLI 工具、Web 应用、API、框架还是插件
2. 受众：库 → 开发者/API 使用者。CLI → 终端用户。Web 应用 → 终端用户。API → 集成者
3. 现有变更日志：检查是否有 CHANGELOG.md、CHANGES.md 或 HISTORY.md。如果有，请阅读最新条目并沿用其惯例（标题样式、条目格式、语气）

这些背景信息会影响后续每一步的决定——库的说明可以直接提及 API 变更，而面向终端用户的应用则应说明带来的效果，而非实现细节。

步骤 5：分析并筛选

这是核心转换过程——将代码变更转化为面向用户的信息。请使用步骤 3 中整理的完整背景信息，而不仅仅依赖提交说明。

过滤无关变更

跳过不会影响用户的变更：

• CI/CD 配置变更（除非会影响用户依赖的发布/部署行为）
• Linter/Formatter 配置、空白字符修复
• 不改变行为的内部重构
• 依赖版本更新（除非修复了用户可见的错误或安全问题）
• 仅涉及测试的变更

合并相关提交

多个提交若共同实现一个功能或修复，应合并为一个条目。请留意：

• 提及相同 PR 或议题编号的提交
• 连续提交涉及相同文件且说明相关的情况
• 初始实现之后的“fixup”或“address review”提交

识别破坏性变更

检查以下信号——破坏性变更绝不能被忽略：

• 提交正文中出现 BREAKING CHANGE: 或 BREAKING:
• Conventional Commits 中类型后带有 !（例如 feat!:）
• 删除公开 API、更改函数签名、重命名配置选项
• 需要用户采取操作的数据库迁移
• 默认行为变更
• PR 上的 breaking、breaking-change 等标签

结合完整背景信息转换措辞

深入了解背景信息的价值就在这里。不要只改写提交说明，应利用更丰富的上下文：

• 议题包含错误报告？ 从用户体验的角度描述修复：“玩家报告称，加入带有自定义模组的服务器时游戏会崩溃” → “修复加入模组服务器时发生的崩溃”
• PR 描述说明了对用户的影响？ 优先采用这种表述，而非提交标题
• 议题包含带有使用场景的功能请求？ 说明用户现在可以做什么，而不是实现了什么
• 标签指明类别？ 可据此进行分组（错误、功能、安全等）
• 没有更深入的背景信息？ 则像之前一样，基于提交说明进行改写

转换示例：

• 提交：“修复 UserService.getProfile() 中的空指针” / 议题：“点击个人资料时应用会崩溃” → “修复查看用户个人资料时发生的崩溃”
• 提交：“为产品查询添加 Redis 缓存” / PR：“大型商品目录的商品搜索耗时超过 3 秒” → “加快商品搜索速度——即使商品目录很大，结果现在也能即时加载”
• 提交：“将 lodash 从 4.17.20 升级到 4.17.21” → “修复 lodash 依赖中的安全漏洞”（如果属于安全修复），否则跳过

第 6 步：撰写说明

发布说明应采用简短的叙述性文字——用几段话讲述本次发布的内容。不要写成项目符号列表，也不要写成分类变更日志。原始提交/PR 列表已经存在；这项技能的目的是产出不同的内容：一份供人阅读的摘要，让读者能在 30 秒内了解有哪些变化，以及这些变化为何重要。

结构

按主题将相关变更归纳成简短段落。自然的行文顺序如下：

1. 先介绍重要功能——有哪些令人期待的新内容。以加粗的版本号开篇，直接说明最重要的新增内容，并解释这些功能能为用户带来什么。
2. 基础设施或性能改进——如果有影响用户体验的后端变更（例如查询更快、可扩展性更好），将它们融入一段中。
3. 较小的改进和 UX 变更——导航改进、新视图、提升使用体验的新增内容。
4. 错误修复——以一段总结可靠性改进和错误修复的内容收尾。无需逐一列出每项修复，可按主题归纳（例如“修复了多个可靠性问题”“修复了若干 UI 错误”），并具体指出最值得关注的修复。

并非每次发布都需要包含这四个部分。小型补丁版本可能只需一段。重大版本可能需要五到六段。根据内容决定结构。

语气

• 使用现在时，对话式但不随意——像一位认真负责的同事向产品使用者介绍本次发布
• 使用“你”直接称呼读者（例如“你现在可以导入店铺商品了”）
• 如果受众熟悉技术术语，就可以使用——不要刻意简化，但也不要使用内部行话
• 简洁明了。每段应有 2 到 4 句话。全文应能在一分钟内读完

破坏性变更

如果此次发布包含破坏性变更，应将其放在最前面。在说明变更内容以及用户需要采取的操作时，直截了当。只有这里适合使用简短的项目符号列表——破坏性变更必须一目了然。

示例

以下是优秀的叙述式发布说明示例：

**v0.5.0** introduces Shop Actions, a new module component type that lets you
create automated actions triggered by shop purchases — opening up new
possibilities for your in-game economy. You can now also react to player
inventory changes through hook events, enabling modules for loot tracking,
item-based triggers, and more.

On the infrastructure side, events are now stored in ClickHouse, which means
faster queries and better scalability as your player count grows. If you're
migrating from CSMM, you can now import your shop listings directly.

This release also fixes several reliability issues — database connection pool
exhaustion that could occur around midnight, cronjob failures under high load,
and a handful of UI bugs including the version number incorrectly showing as
"0.0.0".

注意：不要使用项目符号列表、分类标题或“新增/修复/变更”之类的分类方式。只需清楚地叙述，让用户读完就能理解。

应避免的内容

• 项目符号列表和分类变更日志：原始变更日志已经存在——不要换一种格式重新制作。此技能的价值在于将内容转化为叙述
• 提交记录堆砌：逐字列出每条提交记录，会违背初衷
• 含糊的总结：“修复了各种错误并进行了改进”对读者毫无帮助
• 仅限内部的变更：用户不关心 CI 流水线配置或依赖版本更新
• 行话与受众不匹配：不要对终端用户说“中间件重构”——要告诉他们哪些内容变快了或得到了修复
• 将破坏性变更藏在后面：如果某项变更会导致现有用法失效，就要放在最前面

输出

直接在对话中提供发布说明。除非用户明确要求，否则不要写入文件；如果用户要求写入文件，请询问他们希望写到哪里（CHANGELOG.md、RELEASE_NOTES.md 等）。

写入 GitHub 发布页面或文件时，请按以下结构组织：

1. 顶部为叙述性摘要
2. 分隔线（---）
3. 下方为完整的原始变更日志——直接显示，不要放在可折叠/剧透标签中。否则读者可能会错过。