变更日志生成器 是做什么的?
从 Git 历史自动生成对人类友好的变更日志。遵循 Keep a Changelog 格式,将提交信息润色为用户友好的语言,并可选择创建 GitHub Release。
输入解析
主要输入是一个 Git 引用范围。按以下方式解析参数(如果提供):
- 包含
...或..-> Git 引用范围(例如v1.0.0...v1.1.0) - 匹配单个标签/引用 -> 从该引用到 HEAD
- 匹配 GitHub URL 或
#\d+模式 -> PR(仅提取该 PR 的变更)。对于单个 PR 输入:读取 PR 差异和描述,分类变更,使用 PR 标题作为条目。跳过版本标题。询问用户是否要将这些条目追加到现有变更日志版本中,还是创建一个新的版本。 - 无参数 -> 询问:“变更日志应覆盖哪个范围?您可以提供 Git 引用范围(例如 v1.0.0...v1.1.0)、一个标签(该标签以来的变更)或一个 PR 编号。”
处理流程
digraph changelog {
rankdir=TB;
"解析输入" [shape=box];
"阶段1:收集" [shape=box];
"阶段2:分类" [shape=box];
"阶段3:润色" [shape=box];
"阶段4:审核" [shape=box];
"已批准?" [shape=diamond];
"阶段5:输出" [shape=box];
"解析输入" -> "阶段1:收集";
"阶段1:收集" -> "阶段2:分类";
"阶段2:分类" -> "阶段3:润色";
"阶段3:润色" -> "阶段4:审核";
"阶段4:审核" -> "已批准?";
"已批准?" -> "阶段3:润色" [label="修订"];
"已批准?" -> "阶段5:输出" [label="是"];
}
请勿跳过阶段。 以自然的节奏提问。如果用户一次性回答多个问题,接受捆绑的答案并跳过相关问题。
如果用户说“随便选默认值”或类似的话,请选择合理的默认值,说明您的选择,并请求一次性确认。
阶段1:收集
步骤1 - 收集提交和PR
在两个引用之间运行 git log 以收集所有提交。如果仓库使用 PR,还要在范围内使用 gh pr list --state merged 检查已合并的 PR。
对于每个提交/PR,提取:
- 提交消息(主题 + 正文)
- 变更的文件(用于确定范围)
- PR 标题和描述(如果可用)
- 任何约定式提交类型前缀(feat、fix、chore 等)
步骤2 - 读取更广泛的产品上下文
如果存在,请读取:README、package.json(或等效文件)。目标:了解产品是什么,以便编写用户友好的描述。
如果未找到任何内容,请询问:“您能简单描述一下这个产品吗?我需要一些上下文来编写用户友好的变更日志条目。”
步骤3 - 检测现有格式
检查仓库是否已存在 CHANGELOG.md。如果存在:
- 检测格式(Keep a Changelog、自定义等)
- 检测是否使用 emoji 标签(例如用于“新增”、“Bug 修复”、“破坏性变更”的 emoji)或纯文本类别
- 匹配现有风格
如果没有现有变更日志:
- 默认使用 Keep a Changelog 格式
- 询问:“未找到现有变更日志。您更喜欢 emoji 标签(例如用于新增、Bug 修复)还是纯文本类别(Added、Fixed 等)?”
阶段2:分类
将所有变更分类到 Keep a Changelog 类别中。破坏性变更 将获得一个专门的章节,置于顶部:
- 破坏性变更 - 任何破坏现有行为、API 或需要用户采取行动升级的变更。为每个变更包含迁移说明。从
feat!:,fix!:,BREAKING CHANGE:脚注或差异中移除/重命名的 API 中检测。 - 新增 - 新功能
- 变更 - 对现有功能的更改
- 废弃 - 将被移除的功能
- 移除 - 已移除的功能
- 修复 - 错误修复
- 安全 - 漏洞修复
分类规则:
- 如果提交遵循约定式提交(
feat:、fix:等),使用类型进行分类 - 如果不是,分析差异和提交消息以确定类别
- 跳过仅限内部的变更(重构、测试添加、CI 更改、依赖项升级),除非它们影响用户可见的行为
- 当不确定某个变更是否对用户可见时,包含它并让用户在审核中移除
- 对于包含 50 个以上提交的范围,将相关变更分组为更高层次的条目(例如,不要列出 12 个单独的 API 修复,而是写“改进了多个端点的 API 错误处理”)。呈现分组版本并让用户展开任何组以获取详细信息。
呈现分类列表:
“以下是我在此范围中找到的内容:”
新增 (3)
- 功能 A
- 功能 B
- 功能 C
修复 (2)
- Bug 修复 A
- Bug 修复 B
“需要添加、删除或重新分类任何内容吗?”
在用户确认之前 不要 继续。
阶段3:润色
将每个条目重写为人类友好的语言:
- 以用户收益开头,而非实现细节
- “报告加载速度提升 3 倍” 而非 “优化了报告模块的 SQL 查询执行计划”
- “您现在可以将报告导出为 PDF” 而非 “向报告服务添加了 PDF 导出功能”
- 每个条目保持一行(复杂变更最多两行)
- 在可用时包含 PR/问题引用(例如
(#123))
版本标题
格式:## [版本] - YYYY-MM-DD
如果范围的上限是一个版本标签(例如 v1.2.0),则将其用作版本。如果上限是 HEAD 或分支名称,请询问:“此变更日志应使用哪个版本号?”
使用范围内最新提交的日期,采用 ISO 格式(YYYY-MM-DD)。
技术附录
生成用户友好的变更日志后,请询问:
“是否还需要我生成一个包含实现细节的技术附录?(对面向开发者的文档很有用)”
如果是,则生成一个更详细的章节,包含技术细节、破坏性变更迁移指南和 API 变更。
编写规则
- 永远不要在生成的内容中使用 em-dashes。不要使用“---”字符。请使用逗号、冒号、句点或括号代替。
- 默认使用用户友好的语言(没有行话,没有内部功能名称)
- 每个条目一行,复杂变更最多两行
- 一致的动词时态(过去时:“添加了”、“修复了”、“移除了”)
- 在可用时包含 PR/问题引用
阶段4:审核
呈现完整的变更日志条目:
“这是变更日志:”
## [1.2.0] - 2026-04-11 ### 新增 - 您现在可以将报告导出为 PDF (#123) ### 修复 - 仪表板在页面加载时不再闪烁 (#456)“需要任何更改吗?”
等待批准。只有在用户确认后才进入输出阶段。
阶段5:输出
CHANGELOG.md
检测仓库根目录下已存在的 CHANGELOG.md。如果找到,读取整个文件,确定插入点(在第一个 ## [ 行之前),向用户呈现建议的插入点,并在写入前确认。如果未找到,则使用标准标题创建一个:
# 变更日志
本项目的所有显著变更都将在此文件中记录。
格式基于 [Keep a Changelog](https://keepachangelog.com/)。
始终在写入前确认:
“我将把这段内容前置到
CHANGELOG.md中。可以继续吗?”
GitHub Release
保存变更日志后,请询问:
“是否还需要我使用此变更日志创建一个 GitHub Release?”
如果是,使用 gh release create <tag> --notes "<changelog content>" 创建 Release。如果 gh 不可用,通知用户并跳过。
错误处理
gh不可用 -> 通知用户,跳过 PR 丰富化和 GitHub Release,仅依赖 git log- 无效的引用/标签 -> 要求用户验证
- 范围内没有提交 -> 告知用户,要求验证范围
- 没有产品上下文 -> 要求用户描述产品
- 非约定式提交 -> 回退到差异分析进行分类
此技能不做的事情
- 管理版本策略(语义化版本决策由用户决定)
- 发布到包注册表
- 生成博客文章或新闻通讯(请使用
/blog-post或/newsletter) - 处理分支策略或发布工作流