changelog-generator

name	changelog-generator
description	从 AI 编码工具（Claude Code / Codex / OpenCode / Qoder / WorkBuddy）的开发日志、项目变更计划、git 日志中提炼变更，按用户选定的品牌风格生成更新日志，并追加到项目 CHANGELOG.md 顶部。当用户说"写更新日志 / 写 changelog / 写 release notes / 整理这周做了什么 / 发布前生成变更说明 / 汇总开发日志"，或在版本发布、功能上线、周期回顾、迭代总结时需要把近期开发成果整理成对外可读的更新记录，务必使用本 skill。即使没明说"changelog"，只要意图是把散落的开发痕迹提炼成给用户看的更新说明，就应触发。
metadata	{"author":"wen.yuan"}

Changelog Generator

把散落在各 AI 编码工具里的开发痕迹、变更计划、git 提交，提炼成一份给用户看的更新日志。

设计理念

更新日志不是写给自己的技术流水账，而是写给用户的"这阵子你能用到什么"。

本 skill 基于 features.vote 对 20 款产品 changelog 的调研提炼（详见 references/）。核心理念贯穿全程：

• 用户视角优先：先说"用户能得到什么"，再说技术细节。
• 展示优于讲述：能配图就不纯文字，能用具体路径就不抽象描述。
• 每条回答 "So What"：用户读完每一条，都该知道这对自己意味着什么。
• 一致性：同一项目的所有条目遵循同一套结构。

能力概览

维度	说明
素材	自动发现 Claude Code / Codex / OpenCode / Qoder / WorkBuddy 的开发日志、Qoder plans、OpenSpec 变更提案、git 提交区间
风格	7 种品牌风格模板：Linear / Raycast / Stripe / Notion / Framer / GitHub / 标准通用。生成时可选，也可在项目配置里锁定
输出	追加到项目 CHANGELOG.md 顶部（倒序，最新在上）；文件不存在时自动创建
语言	跟随项目主语言（检测 README/文档）；检测不到时默认中文

工作流

按以下顺序执行。每一步标注了为什么——理解了原因，遇到边界情况才能灵活处理，而不是机械照搬。

第 1 步：确认范围与目标

开工前先和用户对齐三件事。这一步省不得：范围错了，后面写得再漂亮也是白费。

• 版本区间：这次更新覆盖哪个时间/版本范围？（如"本周"、"v1.2.0 到现在"、"这个迭代"）。默认从上次 changelog 条目的日期/版本之后到现在。
• 目标读者：写给谁看？终端用户、开发者、内部团队？这直接影响语气和详略。
• 强调与回避：有没有要重点突出的功能、要回避的内部细节（如未公开实验、安全敏感信息）？

如果用户在调用时已经说明了（如"整理这周的更新"），直接复用，不必重复追问。

第 2 步：扫描素材

读取 references/source-discovery.md，了解各工具日志在本机的存放位置和解析方法。然后扫描本项目相关的：

• 各 AI 编码工具的 session / rollout / 日志
• Qoder plans、OpenSpec 变更提案等计划类文档
• git 提交（按第 1 步确定的区间，如 git log <last-tag>..HEAD）

把发现的素材列成清单，标注来源 + 时间 + 摘要。注意区分"原始素材"（日志原文）和"提炼后的变更"——这一步只做发现，不做提炼。

第 3 步：与用户确认素材清单

把第 2 步的清单呈现给用户，让其勾选 / 增删 / 补充。这一步很关键，原因有两个：

1. 工具日志噪音大：session 里大量是探索、试错、回滚，不全是有效变更。用户知道哪些真正算"这次更新"。
2. 用户有上下文：有些变更没体现在日志里（口头决定、手动操作），只有用户能补充。

呈现格式示例：

已发现以下素材（近 3 天）：
[1] ✓ Claude Code  3 个 session（含导出 PDF、暗色模式相关改动）
[2] ✓ Codex        2 个 rollout（性能优化）
[3] ✓ git log      8 个 commit（v1.2.0..HEAD）
[4] ? OpenSpec     2 份提案（是否纳入？）
请确认要纳入哪些？可增删或补充说明。

第 4 步：选风格

先检查项目根目录有没有 .changelog.yml 锁定了风格（见下方"配置"）。若已锁定，直接用，只需告知用户。

若未锁定，展示 7 种风格供用户选择（见下方"风格速览"表）。用户输入编号或名字即可。

选择风格时，可以基于项目类型给一句推荐，但最终由用户决定——用户对自己产品的调性最清楚。

第 5 步：提炼变更

从第 3 步确认的素材中，提炼出用户能感知的变化，归类为：

• New / Added：新功能、新能力
• Improved：优化、体验提升（已有功能的增强）
• Fixed：bug 修复
• Breaking：破坏性变更（必须单独突出 + 给迁移指引）

提炼时读 references/writing-rules.md。重点是翻译：把技术实现（"重构了状态管理"）翻译成用户价值（"切换页面更快了"）。不是每条技术改动都要写——只写用户能感知的。

第 6 步：按风格生成 + 追加到 CHANGELOG.md

读取 references/templates.md 中对应风格的模板，套用第 5 步提炼的变更，生成一条更新日志。

然后追加到项目的 CHANGELOG.md：

• 文件不存在：用 assets/changelog-skeleton.md 的骨架创建，把新条目放在顶部。
• 文件已存在：把新条目插入到顶部标题（通常是 # Changelog）之后、第一条已有条目之前。保持原有内容不动，只做插入。

追加前把完整生成内容展示给用户过目；用户确认后再写入文件（写文件是改动项目，确认一下成本低、收益高）。

---

风格速览

7 种风格一览。详细模板、字段说明和完整示例见 references/templates.md——生成时务必读取对应风格的完整定义，不要凭这张速览表直接写。

#	风格	一句话特征	最适合
1	Linear	丰富叙述 + 截图位 + 分类子标题（Fixes/Improvements）	面向终端用户的 SaaS、想讲好产品故事
2	Raycast	✨💎🐞 Emoji 分类 + semver 版本号 + 命令名代码化	开发者工具、桌面应用、想突出设计质感
3	Stripe	极简索引 + [产品域] 前缀 + 整条即链接	API / 基础设施、高频更新、技术用户
4	Notion	对话式语气 + UI 路径代码化（Settings → X）+ 利益导向	SaaS、消费级、重产品教育
5	Framer	Added / Improved / Fixed 三段式 + 单段概述	设计工具、创意产品、小版本更新
6	GitHub	标题索引 + 发布类型标签（Release/Improvement/Retired）+ 作者署名	开源项目、大规模分类日志
7	标准通用	调研提炼的最大公约数：Emoji 分类 + 版本日期 + 四段式	通用、不确定时的稳妥默认

选风格时，若用户没明确偏好，可根据项目类型推荐：开发者工具 → Raycast/GitHub；SaaS → Linear/Notion；API 服务 → Stripe；不确定 → 标准通用。

---

关键原则（贯穿全流程）

完整版见 references/writing-rules.md，这里列出最核心的几条，因为它们决定了日志"像不像专业产品的 changelog"：

1. 利益先行：每条先说用户能得到什么，再补充技术背景。
2. 具体优于抽象：写"切换标签页快了 3 倍"，不写"优化了性能"。
3. UI 路径代码化：菜单路径用 Settings → General → Advanced，命令用内联代码。
4. 功能名加粗：列表里 **功能名**: 描述，方便扫读。
5. Breaking 必须突出：用 ⚠️ 或单独小节，并附迁移指引。
6. 不夸大：不用"革命性"、"颠覆性"等无法验证的词。
7. 倒序：新条目永远在顶部。

---

配置（可选）

项目根目录可放 .changelog.yml 锁定偏好，避免每次都选：

# .changelog.yml
style: raycast            # 锁定风格：linear/raycast/stripe/notion/framer/github/standard
date_format: YYYY-MM-DD   # 日期格式，默认 YYYY-MM-DD
version_strategy: date    # 版本标识策略：date(日期) / semver(跟随 git tag) / manual(每次手填)
language: auto            # auto(跟随项目) / zh / en
include_git: true         # 是否纳入 git log

文件不是必需的——没有就用交互式选择 + 合理默认值。

---

参考文件索引

按需读取，不必一次性全读：

文件	何时读	内容
references/templates.md	第 6 步生成时	7 种风格的完整模板 + 字段说明 + 示例
references/source-discovery.md	第 2 步扫描时	各工具日志路径、解析方法、发现命令
references/writing-rules.md	第 5、6 步	10 条写作规则 + 配置维度 + 追加规则
assets/changelog-skeleton.md	首次创建 CHANGELOG.md 时	文件骨架

边界情况备忘

• 没有找到任何工具日志：可能项目用了没覆盖到的工具。直接问用户"这期间主要改了什么"，基于用户口述 + git log 生成。
• 素材很少（如只有 1 个 commit）：照样生成，但用更简洁的风格（Stripe / Framer），避免一条更新套个重模板显得空。
• 同一个功能在多个工具的日志里重复出现：去重，只写一次，取最完整的描述。
• 涉及敏感信息（密钥、内部系统名、未公开功能）：默认不写入，除非用户明确要求。