| 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 步的清单呈现给用户，让其勾选 / 增删 / 补充。这一步很关键，原因有两个：
- 工具日志噪音大：session 里大量是探索、试错、回滚，不全是有效变更。用户知道哪些真正算"这次更新"。
- 用户有上下文：有些变更没体现在日志里（口头决定、手动操作），只有用户能补充。
呈现格式示例：
已发现以下素材（近 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"：
- 利益先行：每条先说用户能得到什么，再补充技术背景。
- 具体优于抽象：写"切换标签页快了 3 倍"，不写"优化了性能"。
- UI 路径代码化：菜单路径用
Settings → General → Advanced，命令用内联代码。
- 功能名加粗：列表里
**功能名**: 描述，方便扫读。
- Breaking 必须突出：用
⚠️ 或单独小节，并附迁移指引。
- 不夸大：不用"革命性"、"颠覆性"等无法验证的词。
- 倒序：新条目永远在顶部。
配置（可选）
项目根目录可放 .changelog.yml 锁定偏好，避免每次都选：
style: raycast
date_format: YYYY-MM-DD
version_strategy: date
language: auto
include_git: true
文件不是必需的——没有就用交互式选择 + 合理默认值。
参考文件索引
按需读取，不必一次性全读：
| 文件 | 何时读 | 内容 |
|---|
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），避免一条更新套个重模板显得空。
- 同一个功能在多个工具的日志里重复出现：去重，只写一次，取最完整的描述。
- 涉及敏感信息（密钥、内部系统名、未公开功能）：默认不写入，除非用户明确要求。
