技能使用指南

changelog（变更日志生成器）Skill 是什么？怎样从 git 历史一键生成发布说明？

变更日志生成器Skill（changelog）能从两个标签、分支或提交之间的 git 历史自动生成结构化发布说明：按常规提交九类分组、破坏性变更置顶并附迁移提示、读取 diff 改写用户视角摘要、自动补提交与对比链接及贡献者清单。零配置按需调用，无需装运行时，支持标签对标签、单参数与零参数三种用法，还可限定 monorepo 子包路径。立即了解安装方式与实战场景，让每次发版不再手翻 git log。

变更日志生成器Skillchangelog
8 个章节 约 18 分钟阅读 AI 智能生成

变更日志生成器Skill：从两段 git 历史一键生成结构化发布说明

  • 一句话定义：这是一个把 git log 变成「人话」的技能。你只需要给出两个引用（标签、分支或提交哈希），它就会输出一份按类型分好类、带提交链接和贡献者清单的变更日志。
  • 零学习成本：遵循常规提交（Conventional Commits）规范，能识别 feat:、fix:、perf:、docs: 等前缀；即使仓库没有规范提交，也会通过读取差异来推断类别。
  • 参数极简：[from-ref] [to-ref]，两个参数、一个参数、完全不传参数三种用法都支持，不传时自动从「最近标签 → HEAD」推断范围。
  • 结果可直接发布：输出为标准的 Markdown 格式，破坏性变更排在最前并附迁移说明，末尾自动附上 GitHub 对比链接与贡献者列表。
  • 轻量可靠：该技能被设定为不直接调用模型，靠 git 命令与文件读取工具完成工作，行为确定、可复现，不产生不可控的「创作式」内容。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

这个技能的中文名是变更日志生成器Skill，英文名（也就是技能标识）是 changelog，技能 ID 为 11945。在技能市场或技能列表中检索时，中文名、英文名和这个 ID 都可以作为定位依据。

它解决什么问题？

每个团队都逃不过这几件事：发版前要写 Release Notes、要往 CHANGELOG.md 里补一段、要在 PR 描述里说明「这次到底改了什么」。手工做这件事的痛点非常集中：

  1. 翻日志成本高：git log 一屏几十条提交，标题还是 fix typo、update 这类含糊描述，要从里面捞出「用户能感知到的变化」非常耗时。
  2. 容易漏：破坏性变更（Breaking Change）藏在第 47 条提交里，忘了写进发布说明，升级的用户就会踩坑。
  3. 写法不统一：有人按模块分组，有人按时间罗列，有人干脆贴一串哈希，下次回看历史时毫无可读性。

变更日志生成器Skill 把这套流程压缩成一条命令：给它一个区间，它还你一份可以直接粘贴进发布页的结构化文档。

「一键安装」的思路与步骤

所谓「一键安装 AI 技能」，本质是把一个已经封装好的能力挂载到你的 AI 编码助手里，让它变成一句斜杠命令或一次自然语言调用。通用流程如下（具体命令、入口地址、是否需要付费等细节以官方说明为准，本文不虚构）：

  • 前提条件一：你已经在使用支持「技能（Skill）」机制或插件机制的 AI 编码助手客户端，并能访问技能市场/技能库。
  • 前提条件二：本地有可用的 git 仓库——这是该技能的原料来源，它通过 Bash(git *) 读取提交历史，通过 Read/Grep/Glob 读取仓库文件。
  • 第一步：找到技能。在技能市场中搜索中文名「变更日志生成器」或英文名「changelog」，也可以用技能 ID 11945 精确定位。
  • 第二步：安装/启用。在技能详情页点击安装或启用按钮，按其提示完成挂载（不同客户端可能叫「安装」「添加」「启用」），将技能加入你的可用技能列表。具体按钮位置与授权流程以官方说明为准。
  • 第三步：验证是否生效。在一个 git 仓库中发起一次调用，例如输入 changelog 或调用带参数的写法 changelog v1.0.0 v1.1.0。如果技能生效，你会看到它去执行 git log、git diff 一类的只读命令并返回分类好的 Markdown 文本。若只返回一句泛泛的回答、没有任何 git 命令痕迹，说明技能未被正确挂载。
  • 第四步：确认权限。该技能允许使用的工具是 Read、Grep、Glob 和 Bash(git *)——也就是说它只做只读的仓库操作，不会修改你的代码或提交。如果客户端有工具授权弹窗，按提示放行只读 git 命令即可。

需要特别说明一点：该技能的配置中标注了「禁用模型调用：true」，并指定由 Explore 代理执行、上下文为 fork。这意味着它的工作方式更接近「一段被严格编排好的脚本化流程」——按固定步骤执行 git 查询、按固定规则分类提交、按固定模板输出，而不是让模型自由发挥。对使用者来说，这是好事：结果稳定、可预期、可复核。

2. 该技能的主要功能和特点

  • 从任意两段引用之间取史料：支持标签对标签（v1.2.0 v1.3.0）、标签对 HEAD（v1.2.0）、提交对提交（abc1234 HEAD），也支持完全不传参数时自动探测「最近标签 → HEAD」；若仓库里一个标签都没有，会退化为「首个提交 → HEAD」。
  • 引用合法性校验：动手之前先用 git rev-parse --verify 验证两个引用是否存在，不合法会直接报错，避免生成一份「看似完整实则错位」的日志。
  • 按常规提交前缀自动分类：内置九级分类优先级——破坏性变更 > 功能 > 错误修复 > 性能 > 文档 > 重构 > 测试 > 构建/CI > 其他。破坏性变更永远排第一。
  • 对「不规范的提交」有兜底策略：遇到没有前缀的提交，会读取完整提交信息甚至 diff，据此推断它到底属于哪个类别；如果整个仓库都不用规范提交，就改为「按代码库区域分组」而非按类型分组。
  • 读取 diff 写「用户视角」摘要：对功能和破坏性变更这两类重要提交，它会真的去看代码差异，然后把 向UserService添加exportUsers函数 这种实现细节，改写成 添加批量导出用户数据为CSV 这种用户能看懂的一行话。这是它与「直接 dump git log」的工具有本质区别的地方。
  • 空类别自动省略：没有性能优化就不出现「### 性能」小节，不会留下一堆空标题。
  • 自动生成可点击链接：检测 origin 远程，把 git@github.com: 转成 https 形式，为每条提交生成 ${REMOTE_URL}/commit/${HASH}，并在文末附上 ${FROM_REF}...${TO_REF} 的 GitHub 对比链接；若无 GitHub 远程，则退化为纯哈希，不产生死链。
  • 版本号与日期自动推导：TO_REF 若是标签，去掉前缀 v 作为版本号；若是 HEAD，则标记为 Unreleased；日期取该引用的提交日期。
  • 贡献者自动去重汇总：git log --format="%an" | sort -u 拿到贡献者列表，附在文末。
  • 边界情况有专门处理：默认跳过合并提交（--no-merges）；支持通过路径参数把范围限制在 monorepo 的某个子包；面对 100+ 提交的大区间会自动降噪，把文档、杂务、重构这类小改动压缩成单行，把篇幅留给功能和破坏性变更。
  • 只读、安全：全部能力建立在 git 只读命令与文件读取之上，不会执行 commit、push、reset 等写操作。

3. 如何使用该技能？

第 1 步：确认调用入口。 该技能的参数提示是 [from-ref] [to-ref]，说明它期待两个引用参数。在你的 AI 助手对话中，用斜杠命令或自然语言触发它均可（具体触发写法以你所使用客户端的官方说明为准），常见的三种形态如下：

  • 两个参数：changelog v2.0.0 v2.1.0 —— 取两个标签之间的变更。
  • 一个参数：changelog v2.0.0 —— 取该标签到 HEAD 之间的变更（适合「准备发下一版」时使用）。
  • 零参数：changelog —— 自动从最近一个标签推到 HEAD；无标签则从首个提交算起。

第 2 步：让技能确定范围并收集历史。 技能内部会依次执行这类只读命令：验证引用、拉取带哈希的提交列表、拉取带作者与日期的版本、用 git diff --stat 拿统计摘要、用 git log --format="%an" | sort -u 拿贡献者。你可以把它理解成「一个资深工程师在发版前的翻阅动作」，只不过几秒钟完成。

第 3 步：等待分类与摘要。 所有提交会落入九类中的一个；被判定为功能或破坏性变更的提交，会额外读取 diff，然后被改写成一行人类可读的描述。

第 4 步：拿到 Markdown 输出。 输出形如：

## [2.1.0] - 2025-03-15

### 功能
- 添加批量用户导出为CSV下载（a1b2c3d）
- 在设置面板支持暗黑模式（e4f5g6h）

### 错误修复
- 修复webhook交付中的竞争条件导致重复事件（i7j8k9l）
- 修正计划报告时区处理（m0n1o2p）

### 性能
- 缓存用户权限查找，减少p99延迟40%（q3r4s5t）

### 内部
- 从CircleCI迁移到GitHub Actions（u6v7w8x）
- 更新依赖项（y9z0a1b）

（实际输出中，哈希会是指向对应 commit 页面的 Markdown 链接，文末还会附上「完整差异」对比链接与贡献者 @ 列表。）

第 5 步：落地使用。 技能只把结果打印到标准输出，不替你写文件。接下来你可以：复制进 CHANGELOG.md 的顶部作为新版本条目；粘贴到 GitHub Release 的发布说明框；或塞进 PR 描述里，让评审者一眼看清这次改动的全貌。

第 6 步（可选）：限定作用域。 在 monorepo 里，可以在参数中带上路径，把日志范围限制在子包内，例如 changelog v1.0.0 v2.0.0 -- packages/api，这样生成的日志不会混入其他包的改动。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
变更日志生成器Skill（changelog） 嵌入 AI 编码助手的对话式变更日志生成技能 双引用区间提取、九类自动分类、读取 diff 重写用户视角摘要、自动生成提交/对比链接与贡献者 需在支持技能机制的客户端中安装；调用只需一句带参数的命令 发版前临时生成发布说明、PR 描述补全、多仓库穿插使用 优势：零配置、临时按需调用、不怕仓库没用规范提交；不足：输出到标准输出需手动落盘，不适合强约束的 CI 卡点流程
conventional-changelog（Node.js CLI 工具链） 工程化的变更日志生成工具 基于规范提交生成 CHANGELOG.md，支持多种预设与模板 需要 Node.js 环境、装依赖、写配置文件、接入 npm script 长期维护、需要固定格式产出的正式项目 优势：可复现、易接 CI、模板可定制；不足：强依赖规范提交，历史提交不规范时内容会缺失，前期配置成本较高
git-cliff（Rust 编写的 CLI） 高性能、模板驱动的变更日志生成器 正则解析提交、Tera 模板自定义输出、支持多仓库与远程集成 需安装二进制或通过包管理器获取，需编写 cliff.toml 对输出格式有强定制需求、追求速度的大型仓库 优势：极快、模板灵活、可深度定制；不足：需要理解模板与配置语法，学习曲线偏陡
GitHub Releases 自动生成发布说明 平台内置能力 基于合并的 PR 与标签自动生成发布说明草稿 无需安装，在发布页面点按钮即可 托管在 GitHub 上、以 PR 为协作单位的项目 优势：零成本、与平台深度集成；不足：只覆盖已合并 PR，无法处理本地未推送区间，摘要粒度受 PR 标题质量影响

从对比可以看出，这个技能的差异化定位很清晰：它不追求替代 CI 里的自动化流水线，而是把「我临时想看看这段区间改了什么」这件事的门槛降到最低。无需装运行时、无需写配置文件、无需先把提交历史改造成规范格式，一句话就能拿到结果。

5. 该技能的典型应用场景与实际体验情况

场景一：发版前夜的发布经理

痛点：版本即将发布，需要一份面向用户的 Release Notes，但 git log 里有 60 多条提交，混杂着依赖升级、错别字修正和两个真正重要的破坏性变更。 使用方式：执行 changelog v2.0.0 v2.1.0，拿到分类结果后直接复制到 GitHub Release。 实际体验：破坏性变更被强制排在最前并附带迁移提示，这一点极大地降低了「漏写导致用户升级翻车」的风险。由于大区间会自动降噪，文档、杂务、重构被压缩成单行，注意力自然落在功能与修复上。

场景二：接手陌生仓库的新成员

痛点：刚到新团队，想知道上个版本到现在到底发生了什么，但提交信息是「update」「fix bug」这类黑话。 使用方式：直接执行无参数的 changelog，让它自动从最近标签推演到 HEAD。 实际体验：技能遇到无前缀提交会去读 diff 来推断类别，因此即便仓库不规范也能给出可用的分组。这相当于一份自动生成的「版本变更导读」，比逐条读 log 效率高得多。

场景三：维护 monorepo 的子包负责人

痛点：整个仓库共享历史，但只想看自己负责的 packages/api 的改动，直接看全量日志会被其他包的提交淹没。 使用方式：changelog v1.0.0 v2.0.0 -- packages/api。 实际体验：范围被限定在路径内，输出干净。需要注意的是，路径限定依赖技能正确解析你附加的参数，建议第一次使用时先用小范围验证结果是否符合预期。

场景四：写 PR 描述却不知道怎么写「变更概要」

痛点：改了七八个提交，PR 描述却只有一个标题，评审者看不明白。 使用方式：用 changelog <目标分支基点> HEAD 生成一段摘要，粘进 PR 描述。 实际体验：由于摘要按「用户能感知到的变化」措辞而非实现细节，评审阅读成本显著下降。

整体上手难度与注意事项：上手难度很低——会写 git 标签名就会用它。效果的稳定性得益于「禁用模型调用」的设定：流程是固定编排的，同样的区间多次运行结果应当一致，便于复核。有两点值得注意：其一，输出只打印到标准输出，落盘需要你手动完成；其二，分类质量高度依赖提交信息与 diff 的可读性，如果单个提交塞了十几个不相关改动，摘要难免被简化。

6. 该技能能为用户带来的价值

时间维度：一份手工整理的、覆盖几十条提交的发布说明，通常要 20 到 40 分钟，而且往往在发版最紧张的时刻进行。技能把这段时间压缩到一次命令调用的量级，节省的不只是编写时间，还有「从零开始翻日志」的认知负担。

质量维度：破坏性变更强制置顶、空类别自动省略、每条附短哈希可回溯、文末附对比链接与贡献者——这些是「人」经常偷懒但「流程」不会偷懒的部分。发布说明的质量不再取决于当晚谁值班。

门槛维度：不需要 Node.js、不需要装 CLI、不需要写 cliff.toml 之类的配置、不需要先把历史提交改造成规范格式。对小型团队、个人项目、以及「只是临时想看看」的场景来说，这种零配置的按需调用是它最大的价值。

长期价值：变更日志从「发版时的负担」变成「顺手就能产出的副产物」后，团队更容易养成持续记录的习惯。半年后回看某个版本改了什么，不必再去考古式地读提交历史——这本身就是可维护性的一部分。

7. 常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认生效？

在支持技能机制的 AI 编码助手中，到技能市场搜索中文名「变更日志生成器」、英文名「changelog」或技能 ID 11945，按提示安装/启用即可。具体的按钮位置、命令与授权流程以官方说明为准。验证方式：在一个 git 仓库里执行一次带两个标签的调用，如果你看到程序去跑了只读 git 命令并返回分类好的 Markdown，就说明生效了。

Q2：它是收费的吗？会消耗很多模型调用额度吗？

费用取决于你所使用的客户端与技能市场的定价策略，以官方说明为准，本文不对价格做任何承诺。就技能自身配置而言，它标注了「禁用模型调用：true」，工作方式偏向固定流程编排而非模型自由生成，因此不构成一个反复调用大模型的消耗大户。

Q3：我的仓库提交信息完全不规范，一个 feat: 都没有，还能用吗？

可以。技能对无前缀提交有专门的兜底逻辑：读取完整提交信息，必要时读取 diff 来推断类别；如果整个仓库都没有规范提交，它会切换成「按代码库区域分组」。只是分组精度和摘要质量会低于规范提交的仓库。

Q4：它会不会改动我的代码或提交记录？

不会。该技能允许使用的工具仅为 Read、Grep、Glob 与 Bash(git *)，执行的都是查询类 git 命令（log、diff、show、rev-parse、describe 等），输出只打印到标准输出，不会写文件、不会提交、不会推送。

Q5：和 conventional-changelog、git-cliff 这些工具相比该怎么选？

如果你的项目已经有成熟的 CI 流水线，且需要每次都自动把条目写进 CHANGELOG.md，那么配置固定的 CLI 工具更合适；如果你想要的是「临时、随手、零配置地问一句『这段区间改了什么』」，或者仓库历史不够规范又不想先做改造，那么这个技能更顺手。两者并不冲突——很多团队正是用它先产出草稿，人工润色后再落入正式文件。