SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ai-changelog

ai-changelog

编程与开发

查看项目

更新于 10-16 02:00

技能介绍

AI-Driven Changelog 用于在任意项目中搭建由 AI 代理维护的变更日志系统，适用于软件项目，也适用于非代码项目。技能会创建 CHANGELOG.md，并按项目类型选择两种形态之一。

一、用途与两种模式

软件项目：代理把条目写在 ## [Unreleased] 下；自动化在发布时打上版本号（CalVer 或 SemVer）。代理从不写版本号，版本号由构建流程负责。

非代码项目（无构建系统）：代理手工在日期标题（## 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 tag --list | head 得到的 Git 标签：vX.Y.Z → SemVer；YYYY.M.N → CalVer
  • 内容匹配 ^[0-9]+.[0-9]+.[0-9]+ 的 VERSION 文件 → SemVer
  • package.json、Cargo.toml、pyproject.toml 中匹配 X.Y.Z 的 manifest version 字段 → SemVer

如果信号缺失或相互矛盾，询问用户。对有既有版本历史的项目（已有标签、manifest 版本、先前变更日志条目）建议 SemVer；对自动版本化更优的绿地项目建议 CalVer。各方案的取舍记录在其参考文件中。

  1. 阅读与所选方案对应的参考文件，其中包含构建集成做法、CLAUDE.md 片段、GitHub Actions 模式以及该方案特有的注意事项：CalVer → references/calver.md；SemVer → references/semver.md；Dated（非代码项目）→ references/dated.md。

  2. 询问用户可选功能（仅 CalVer/SemVer，Dated 模式跳过）：是否在 ## [Unreleased] 上方固定 ## Known Bugs 区段（默认：是）；是否集成 GitHub Actions 发布工作流（默认：除非要求否则跳过）。

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

  4. 把本技能的 scripts/version.py 复制到目标项目的 scripts/ 目录，并使其可执行（chmod +x）。Dated 模式跳过——没有脚本。

  5. 应用方案参考：按所选参考文件中的构建集成做法操作，向现有构建系统添加目标，若没有则创建最小 Makefile。Dated 模式跳过——没有构建集成。

  6. 用所选方案参考中的片段更新 CLAUDE.md，插入项目的开发工作流部分，或新建一个。在 Dated 模式下，这是保持变更日志更新的唯一机制，务必确保片段落地。

  7. 验证：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 scripts 或 Makefile；Cargo.toml → Cargo.toml → Makefile 包装；pyproject.toml → pyproject.toml → Makefile 包装；go.mod → VERSION（若存在）或无 → Makefile 包装；VERSION 文件 → VERSION → Makefile 包装；无（代码项目）→ 无 → 创建最小 Makefile；无（非代码项目）→ 无 → Dated 模式，无脚本、无 Makefile。

四、脚本工作方式

scripts/version.py 子命令：version 将今天的 CalVer 打印到 stdout（仅 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 注释是代理的指令来源：CHANGELOG.md 中的 <!-- AI agents: ... --> 注释告诉未来的代理如何写条目，不能省略。Known Bugs 保持固定：打戳脚本会把 ## Known Bugs 保留在 ## [Unreleased] 上方；若添加它，代理应在此维护。SemVer 加自动 CalVer 是隐蔽陷阱：若 SemVer 项目的 Makefile 调用 python3 scripts/version.py stamp 却不带 --version，脚本会自动计算 CalVer 并写入变更日志；references/semver.md 中的配方总是传 --version，自定义集成时应保留这一约定。TOML 配置打戳只匹配首个：正则只替换第一处 version = "..." 行，即包版本，依赖版本不受影响。VERSION 文件打戳要求现有内容为 semver 形态：脚本的 VERSION 处理器仅当当前内容匹配 ^\d+.\d+.\d+ 时才重写文件，构建号、带标签前缀的版本或其他格式不会被改动。