---

name: chroma-release description: Chroma 的发布一体化流程（SemVer 决策、生成 changelog、同步 CLI 版本、打 git tag、发布 GitHub Release）。当被要求进行新版本发布、更新 CHANGELOG.md、升级 ca CLI 版本号、创建 tag 或发布 GitHub Release 时使用。

Chroma 发布流程

概览

通过对比 HEAD 与最新 tag，确定下一版 SemVer，生成符合仓库格式的 changelog 段落，同步 ca CLI 版本号，并通过 gh 发布 git tag 与 GitHub Release。

工作流（从 HEAD 发布）

0) 前置条件

• 确保功能/修复改动已提交。release 脚本要求工作区干净。
• Tag 格式为纯 X.Y.Z（不带 v）。
• Release notes 从 notes 文件读取，文件内不包含版本标题。

1) 收集变更用于 AI 分析

运行变更收集脚本：

./.codex/skills/chroma-release/scripts/collect_changes.py

如果需要指定基准 tag：

./.codex/skills/chroma-release/scripts/collect_changes.py --since-tag 0.1.1

利用输出检查：

• 上次 tag 到 HEAD 的提交摘要
• 变更文件与 diff 统计

2) 决定下一版本（SemVer）

基于 diff 与提交上下文决定下一版本号。

判定参考：

• Breaking change：删除/重命名 public API，修改函数签名，改变默认行为，或不兼容的 CLI flag 变更。
• Feature：向后兼容的新增功能。
• Fix：仅包含向后兼容的 bug 修复。

SemVer 对应：

• MAJOR：破坏性变更（若已到 1.0.0+）
• MINOR：新增功能
• PATCH：修复

1.0 前版本处理（当前状态）：

• 0.y.z 下的破坏性变更按 minor 处理（y+1）。
• 功能新增按风险决定 y+1 或 z+1；默认用户可见新增走 minor，低风险修复走 patch。

若破坏性判断不明确，优先检查 Sources/Chroma 与 public 声明 diff 再决策。

3) 生成 changelog notes（AI）

生成与 CHANGELOG.md 现有格式一致的 notes 文件。notes 不得包含版本标题。示例：

### Added
- ...

### Changed
- ...

### Fixed
- ...

根据上次 tag 与 HEAD 的 diff 填充段落，只保留有内容的分组。

4) 应用版本 + changelog，提交、打 tag、发布（脚本化）

用选定版本和 notes 文件执行发布脚本：

./.codex/skills/chroma-release/scripts/release.py \
  --version 0.1.1 \
  --notes-file /path/to/release-notes.md \
  --date 2026-01-04

行为：

• 更新 Sources/Ca/CaCommand.swift 里的版本常量
• 在 ## [Unreleased] 之后插入 ## [X.Y.Z] - YYYY-MM-DD 段落
• 提交信息为 Release X.Y.Z
• 创建 git tag X.Y.Z
• 使用同一 notes 文件通过 gh release create 发布 GitHub Release

可选参数：

• --skip-commit / --skip-tag / --skip-release
• --allow-dirty（不建议）

5) 校验

./.codex/skills/chroma-release/scripts/release_check.py --version 0.1.1 --require-clean --require-tag

资源

scripts/

• collect_changes.py：收集上次 tag 到 HEAD 的提交与 diff 摘要。
• release.py：应用 changelog 与 CLI 版本，提交、打 tag、发布。
• release_check.py：强校验版本一致性与 tag 是否存在。