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 分析
运行变更收集脚本：
bash
./.codex/skills/chroma-release/scripts/collect_changes.py
如果需要指定基准 tag：
bash
./.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 不得包含版本标题。示例：
markdown
### Added - ... ### Changed - ... ### Fixed - ...
根据上次 tag 与 HEAD 的 diff 填充段落，只保留有内容的分组。
4) 应用版本 + changelog，提交、打 tag、发布（脚本化）
用选定版本和 notes 文件执行发布脚本：
bash
./.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) 校验
bash
./.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 是否存在。