Git Commit

Git Commit with CalVer Tag

将当前仓库变更提交到 git，并按 CalVer 规则打 tag。

核心规则

• 先提交，再算版本，再打 tag。
• 版本号必须来自 calver.py，不得手动推断。
• calver.py 是本 skill 自带脚本，不属于项目仓库。
• **如果无法可靠定位 skill 的安装目录，就停止。**不要猜路径，也不要继续后续步骤。
• 只有用户明确要求时，才执行 git push 和 git push --tags。

脚本定位

calver.py 指的是 skill 自带脚本，而不是项目仓库里的同名文件。

执行时先定位 skill 的安装目录，再运行：

python3 <skill安装目录>/scripts/calver.py

如果环境不能提供安装目录，或目录无法可靠确定，立即停止并告知用户。

工作流程

1. 查看仓库状态，确认当前变更范围。
2. 只暂存并提交与当前任务相关的文件。
3. Commit Message 必须严格遵循下面的 Commit Message 规范（若用户提供了额外的说明，应当融合至该格式中）。
4. 运行 calver.py 获取下一个版本号。
5. 用该版本号创建 tag。
6. 如用户明确要求推送，再执行 git push 和 git push --tags。

Commit Message 规范

提交变更时，Commit Message 必须严格遵循以下格式约束：

<type>(<scope>): <summary>

<正文：描述本次变更的背景与动机>

Agent-Task: <原始任务描述或任务 ID>
Agent-Model: <使用的模型，如 gpt-4o、gemini-2.5-pro>
Agent-Decision: <关键设计决策及理由>
Agent-Limitation: <已知局限或后续 TODO>

• <type>：变更类型，如 feat (新功能), fix (修复), docs (文档), style (格式), refactor (重构), perf (性能), test (测试), chore (构建/工具)。
• <scope>：影响范围，可以是具体的组件、模块或 Skill 名称。
• <summary>：简短概括变更内容（必须使用简体中文）。
• Agent-Task：原始任务描述或任务 ID。
• Agent-Model：执行任务时所使用的模型名称（例如，本轮运行所使用的模型，如 gemini-3.5-flash-high 等）。
• Agent-Decision：关键技术/设计决策及其背后的合理理由。
• Agent-Limitation：任何已知的局限性、潜在风险或后续待办事项（TODO）。
• 语言约束（简体中文）：除了必要的 Conventional Commits 英文关键字（如 feat, fix 等 <type> 和 <scope>）以及英文字段名/元数据（Meta）的 Key（如 Agent-Task:）之外，<summary>、<正文> 以及各元数据字段的具体 Value 描述，必须使用简体中文进行撰写。

原子提交规范

当实现一个特性或应用户明确要求时，必须将你的工作拆分为原子提交（Atomic Commits）。每次提交都必须严格遵循以下要求：

• 单一逻辑变更：每次提交必须且仅代表一个清晰的逻辑变更（例如：独立实现一个子功能、修复一个特定的 bug、添加一组相关的测试等）。
• 可构建且可测试：每次提交都必须使代码库保持在可构建、可运行且测试能够通过的状态，绝不能提交破坏构建的半成品。
• 功能与重构分离：严禁在同一个提交中混合代码重构（Refactoring）与新功能开发/Bug修复。重构应当作为独立的提交。
• 模块解耦：严禁在同一个提交中混合对多个不相关模块的修改。不同模块的变更应当分作不同的提交。

原子提交工作流

当触发词包含“原子提交”、“分步提交”、“拆分提交”或在复杂的特性开发中，应采用以下独立触发的原子提交工作流：

1. 分析变更集：开发完成后，使用 git diff 或 git status 评估所有代码修改。
2. 划分逻辑块：将代码变更合理规划并拆分为若干个在逻辑上相互独立、先后依赖清晰的子块。
3. 分步暂存与提交：
   • 使用 git add <file> 或 git add -p 仅暂存属于当前首个逻辑块的修改，避免混入无关代码。
   • 为该块撰写符合 Commit Message 规范 的 commit message。
   • 执行提交：git commit -m "..."。
   • 验证当前状态：运行构建或测试，确保代码库处于完全可用状态。
4. 循环往复：重复步骤 3，直到所有变更块均已被独立且干净地提交。
5. CalVer 与 Tag 规则：
   • 仅在最后一个原子提交完成后，才运行 calver.py 获取最新版本号，并为该次最新提交打上 tag。
   • 前置的过渡性原子提交不需要打 tag。

整理提交历史工作流

当触发词包含“整理提交历史”、“准备开 PR”、“squash 提交”、“合并提交”、“git rebase”或用户明确要求在开 PR 前整理分支提交历史时，应采用以下独立触发的提交历史整理工作流：

1. 查看历史提交：
   • 运行 git log --oneline main..HEAD 查看当前分支相对于主干分支（如 main）的所有提交历史。
2. 分析与规划整理方案：
   • 识别提交历史中哪些属于同一逻辑变更（特别是带有 [WIP]、temp 等前缀的过渡性/临时性提交）。
   • 规划合并方案：明确定义哪些提交需要保留（pick），哪些需要合并（squash 或 fixup）。
   • 为合并后最终保留的每个 commit 规划新 Commit Message，新 Message 必须严格符合 Commit Message 规范（符合 Conventional Commits 格式，并包含 Agent-Task、Agent-Model、Agent-Decision、Agent-Limitation 尾注）。
3. 向用户呈现方案并征求确认：
   • 将整理方案（包括哪些 commit 保留、哪些合并、修改后的完整 Commit Message 预览）以清晰的形式呈现给用户。
   • 重要：必须在此步暂停，等待用户的明确确认！ 在用户没有回复并明确同意前，禁止执行任何变基操作。
4. 执行交互式变基：
   • 用户确认方案后，执行 git rebase -i main（对于 Agent 执行，如果直接交互有困难，可以通过配置非交互式变基环境变量或脚本，例如 GIT_SEQUENCE_EDITOR 或 git commit --amend 等技术手段，来实现自动化的 squash/rebase 整理）。
5. 最终验证与展示：
   • 变基整理完成后，再次运行 git log --oneline main..HEAD 展示最终的精简、规范的提交历史，确保整理结果符合预期。

CalVer 规则

• 格式：YY.WW.MICRO
• YY：ISO 年份后两位
• WW：ISO 周数
• MICRO：全局递增序号，跨年不重置

常见错误