ai-changelog

AI 驱动的变更日志

设置一个由 AI Agent 在开发过程中维护的变更日志系统。根据项目类型选择两种形式：

• 软件项目：Agent 在 ## [Unreleased] 下编写条目；自动化流程在发布时添加版本号（CalVer 或 SemVer）。Agent 绝不编写版本号；由构建流程处理。
• 非代码项目（没有构建系统）：Agent 手动在日期标题（## YYYY-MM-DD）下添加简短条目。没有脚本，也没有版本号。参见 references/dated.md。

设置工作流

1. 检测构建系统：检查是否存在 Makefile、Justfile、package.json、Cargo.toml、pyproject.toml、go.mod。记录哪些配置文件包含 "version" 字段。

2. 检查这是否确实是一个软件项目。 如果第 1 步中没有检测到构建系统，也没有版本惯例（例如文档仓库、写作或笔记库、内容网站、研究或配置集合），则使用 Dated 模式：采用基于日期的变更日志标题，不使用版本脚本，也不集成构建流程。直接跳到 references/dated.md，忽略下方的脚本和构建步骤。否则，通过检查以下内容来检测版本方案（按可信度从高到低排列）：

   • CHANGELOG.md 标题样式：## [YYYY.M.N] 标题 → CalVer；## [X.Y.Z] 标题或提及“SemVer”的说明文字 → SemVer
   • Git 标签，运行 git tag --list | head：vX.Y.Z → SemVer；YYYY.M.N → CalVer
   • VERSION 文件内容与 ^[0-9]+\.[0-9]+\.[0-9]+ 匹配 → SemVer
   • 清单版本字段（package.json、Cargo.toml、pyproject.toml）与 X.Y.Z 匹配 → SemVer

   如果没有明确依据或依据相互矛盾，请询问用户。对于已有成熟版本历史（现有标签、清单版本、以往变更日志条目）的项目，建议使用 SemVer；对于适合自动版本管理的全新项目，建议使用 CalVer。每种方案的权衡已记录在相应的参考文件中。

3. 阅读与所选方案对应的参考文件。 文件中包含构建集成方案、CLAUDE.md 片段、GitHub Actions 模式，以及针对该方案的注意事项：

   • CalVer → references/calver.md
   • SemVer → references/semver.md
   • Dated（非代码项目）→ references/dated.md

4. 询问用户是否需要可选功能（仅适用于 CalVer/SemVer；Dated 模式下跳过）：

   • 是否在 ## [Unreleased] 上方添加固定的 ## Known Bugs 章节？（默认：是）
   • 是否集成 GitHub Actions 发布工作流？（默认：除非用户提出，否则跳过）

5. 生成或更新 CHANGELOG.md。CalVer/SemVer 使用 references/changelog-template.md；Dated 使用 references/dated.md 中的模板。如果 CHANGELOG.md 已存在，不要覆盖；应在现有条目上方插入 HTML 注释和相应结构（CalVer/SemVer 使用 ## [Unreleased]，Dated 使用今天的日期标题）。

6. 复制 scripts/version.py，从此技能复制到目标项目的 scripts/ 目录中。将其设为可执行文件（chmod +x）。Dated 模式下跳过——该模式没有脚本。

7. 应用方案参考：按照所选参考文件中的构建集成方案操作。将目标添加到现有构建系统；如果没有构建系统，则创建一个最精简的 Makefile。Dated 模式下跳过——该模式没有构建集成。

8. 更新 CLAUDE.md，加入所选方案参考中的片段。将其插入项目的开发工作流章节；如果没有该章节，则创建一个。Dated 模式下，这是唯一能确保变更日志保持最新的机制，因此务必加入该片段。添加“将同一天/同一版本内的更改合并到一条记录中（不要在更改记录中继续添加更改）。”保留片段中关于记录内容和条目长度的规则——这些规则可以避免 Agent 记录琐碎事项，或为简单更改写成长篇段落。

9. 验证：

   • CalVer：uv run scripts/version.py version 应输出今天的 CalVer；然后运行 uv run scripts/version.py stamp --dry-run 预览版本标记
   • SemVer：uv run scripts/version.py stamp --version <current-version> --dry-run --changelog-only 预览版本标记，但不修改权威版本来源
   • Dated：确认 CHANGELOG.md 中有今天的日期标题，且 CLAUDE.md 片段已就位；无需运行任何命令

项目检测

检测指标，以及要标记的内容和集成方式：

• Makefile——标记项目中存在的所有配置文件；添加 make 目标
• Justfile——标记相同的配置文件；添加 just 配方
• package.json——标记 package.json；添加 npm 脚本，或添加 Makefile
• Cargo.toml——标记 Cargo.toml；添加 Makefile 封装
• pyproject.toml——标记 pyproject.toml；添加 Makefile 封装
• go.mod——如果存在，则标记 VERSION；否则不标记任何内容；添加 Makefile 封装
• VERSION 文件——标记 VERSION；添加 Makefile 封装
• 无构建系统的代码项目——不标记任何内容；创建一个最简 Makefile
• 无构建系统的非代码项目——日期模式：不添加脚本或 Makefile

脚本工作原理

scripts/version.py 子命令：

• version：将今天的 CalVer 输出到标准输出（仅限 CalVer 项目）
• stamp：将 ## [Unreleased] 替换为 ## [VERSION] - DATE，重新插入一个新的 ## [Unreleased]，并将版本标记到自动发现的配置文件中（package.json、Cargo.toml、pyproject.toml、tauri.conf.json、VERSION）

标志：--version X.Y.Z（SemVer 必需；CalVer 可选覆盖），--dry-run、--changelog-only、--no-changelog。

该脚本与版本方案无关。不提供 --version 时，会自动计算 CalVer；提供 --version 时，会标记你给出的任意字符串。校验由构建系统负责，因此 SemVer 配方始终会传入 --version，并在调用脚本前拒绝格式错误的输入。有关为何采用这种拆分方式，请参阅 references/semver.md。

通过 uv run scripts/version.py stamp 或 python3 scripts/version.py stamp 运行（无外部依赖）。

注意事项

• 绝不要覆盖现有的变更日志历史。 如果 CHANGELOG.md 已存在且包含内容，应将 [Unreleased] 结构合并到其中，而不是替换整个文件。
• 空的 Unreleased 部分：如果 [Unreleased] 没有内容，标记操作不会执行。这可以避免生成空版本条目。
• 在 CalVer 的 CI 中设置 fetch-depth: 0：CalVer 使用 git rev-list --count HEAD。浅克隆会导致提交计数错误。
• 变更日志不是提交日志。 两条规则能让它保持实用，且必须同时出现在 HTML 注释和 CLAUDE.md 片段中：只记录读者可见的变更（其余内容由 Git 历史记录）；除非变更确实复杂，否则每条记录保持一行。缺少这两条规则时，Agent 会记录格式调整，并把一行修复写成一段话。
• HTML 注释是 Agent 的指示来源。 CHANGELOG.md 中的 `` 注释会告诉未来的 Agent 如何编写条目。不要省略它。
• Known Bugs 始终置顶。 标记脚本会将 ## Known Bugs 保留在 ## [Unreleased] 上方。如果添加了该部分，Agent 应在此处维护它。
• SemVer + 自动 CalVer = 悄无声息的陷阱。 如果 SemVer 项目中的 Makefile 在没有 --version 的情况下调用 python3 scripts/version.py stamp，脚本会自动计算 CalVer 并将其写入变更日志。references/semver.md 中的配方始终会传入 --version；任何自定义集成都必须保留这一约定。
• TOML 配置文件标记只匹配第一处。 正则表达式只会替换第一行 version = "..."，也就是软件包版本。依赖项版本不会受影响。
• 标记 VERSION 文件要求其现有内容符合 SemVer 格式。 脚本的 VERSION 处理逻辑只有在文件当前内容匹配 ^\d+\.\d+\.\d+ 时才会重写文件。构建号、带标签前缀的版本或其他格式都会保持不变。