make-changelog

Changelog 生成器

使用 Git 历史记录，按照 Keep-a-Changelog 格式创建或更新 CHANGELOG.md。 每个版本范围启动一个 Haiku 子代理，以便并行处理并节省 Token。

步骤 1 — 评估项目状态

运行范围规划脚本，验证仓库并收集所有版本范围：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

• 退出码 2 = 不是 Git 仓库，或仓库没有提交。停止并向用户报告 stderr 中的错误消息。
• 退出码 0 = 继续。JSON 输出包含此技能将处理的所有范围。

同时检查是否已有变更日志：

ls CHANGELOG.md CHANGELOG 2>/dev/null

如果 CHANGELOG.md 存在，请读取它，以确定最后记录的版本（最新的 ## [x.y.z] 标题）。

步骤 2 — 确定范围

不存在标签： 脚本返回单个 Unreleased 范围。以全新模式继续。

存在标签，不存在 CHANGELOG.md： 全新模式 — 处理脚本返回的所有范围。

存在标签，且存在 CHANGELOG.md： 填充模式 — 使用 --since-tag 重新运行脚本，仅获取尚未涵盖的范围：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag <last_documented_tag> --output json

如果用户的意图不明确（用户说“更新变更日志”，但文件已有大量内容），请询问用户选择：

• “仅填充缺失内容” — 添加自上次记录以来的新版本／Unreleased 内容
• “从头重建” — 根据 Git 历史重新生成整个文件
• “仅更新 Unreleased” — 仅刷新 [Unreleased] 部分

步骤 3 — 规划子代理

检查步骤 1 或 2 的 JSON 输出。每个范围对象包含：

• label — 版本字符串（1.2.0 或 Unreleased）
• from_ref — 下限 Git 引用（空字符串 = 从初始提交开始）
• to_ref — 上限 Git 引用
• date — 标签日期或今天的日期
• commit_count — 范围内的提交数

跳过 commit_count == 0 的范围 — 无需启动子代理。

最多启动 12 个子代理。 如果非空范围列表超过 12 项，请询问用户是限制为最近的 12 项，还是处理全部范围（并说明这会花费更长时间）。

步骤 4 — 启动 Haiku 子代理

针对每个非空范围，在同一条消息中各启动一个 Task（并行处理）。所有子代理均使用 model: "haiku"。每个子代理都会收到以下独立提示词（替换为范围对象中的值）：

You are generating one section of a CHANGELOG.md.

Version: [label]
Date: [date]
Git command: git log [from_ref]..[to_ref] --format="%s"
(If from_ref is empty, use: git log [to_ref] --format="%s")

Categorize by user-observable impact, not by commit prefix. The conventional
commit prefix (feat:, fix:, etc.) is a hint only — a commit labelled "feat:"
that clearly corrects a bug belongs in Fixed, not Added. Use the prefix as a
starting signal and override it when the commit subject contradicts it.

Sections and classification signals:
- Added: new capabilities users can invoke (add, introduce, implement, support)
- Changed: modified behavior of existing features (update, change, refactor, improve)
- Deprecated: features explicitly flagged for future removal
- Removed: capabilities or endpoints deleted (remove, drop, delete)
- Fixed: bugs corrected, regardless of prefix (fix, resolve, patch, correct, hotfix)
- Security: vulnerability patches (security, CVE, sanitize, escape)

Skip: merge commits, CI/CD configuration changes, version-bump commits,
formatting-only changes.

Use present tense, imperative mood: "Add X", not "Added X" or "adds X".
Omit empty sections. Omit internal variable names and implementation details.

Output ONLY the markdown block, no preamble:

## [VERSION] - DATE

### Added
- ...

### Fixed
- ...

收集所有 Task 结果后，再进入步骤 5。

步骤 5 — 汇总变更日志

按从新到旧的顺序排列版本区块。完整文档结构：

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

[content from unreleased subagent, or omit section if empty]

## [1.2.0] - 2024-03-15

[content from subagent]

填充模式： 在 # Changelog 标题区块之后、首个现有 ## [ 条目之前插入新的版本章节。准确保留所有现有内容。

全新／重建模式： 写入完整文件。

步骤 6 — 写入并报告

全新模式： 写入 CHANGELOG.md。如果文件已存在，请使用 AskUserQuestion 确认覆盖。

填充模式： 使用 Edit 在正确位置插入新章节。

写入后，报告：

• 使用的模式（全新／填充／仅更新 Unreleased）
• 涵盖的版本（标签、日期、提交数 — 来自脚本输出）
• 使用的子代理数量
• 为空而跳过的范围
• 无法有把握地归类的提交（标记供用户审核）

脚本

scripts/list_ranges.py — 查询 Git 标签并计算版本范围。在步骤 1 和 2 中调用。退出码 2 = 仓库无效或为空；退出码 0 = 成功。

# All ranges (text preview)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py

# All ranges (JSON for skill use)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json

# Fill mode: only ranges newer than a specific tag
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
  --since-tag v1.2.0 --output json