git-commit · diff
git:20260521.e45f6b3 to git:20260915.ddfa54c
20 added, 27 removed. Audit A to A.
---
name: git-commit
- description: 当用户明确要求提交、打标签、发版、推送 git 变更，执行“原子提交”（分步/拆分提交），或要求“整理提交历史”（squash 提交、准备开 PR、合并或变基提交历史）时使用；适用于使用 CalVer 管理版本号的仓库。
+ description: 在 CalVer 仓库中执行用户明确要求的提交、打标签、推送或提交历史整理。普通开发和准备 PR 不自动触发提交或历史改写。
---
# Git Commit with CalVer Tag
将当前仓库变更提交到 git，并按 CalVer 规则打 tag。
## 核心规则
- - **先提交，再算版本，再打 tag。**
+ - 仅执行用户已授权的操作。修改本 skill、普通开发或准备 PR，不构成提交或改写历史的授权。
+ - 已授权提交且仓库采用提交后打 CalVer tag 的约定时，**先提交，再算版本，再打 tag**；用户明确只要 commit 时不打 tag。
- **版本号必须来自 `calver.py`，不得手动推断。**
- **`calver.py` 是本 skill 自带脚本，不属于项目仓库。**
- - **如果无法可靠定位 skill 的安装目录，就停止。**不要猜路径，也不要继续后续步骤。
+ - 需要打 tag 时定位本 skill 的真实安装目录；脚本不可用则停止版本计算和打 tag，说明缺口。仍可完成不依赖该脚本且已授权的工作。
- **只有用户明确要求时，才执行 `git push` 和 `git push --tags`。**
## 脚本定位
`calver.py` 指的是 skill 自带脚本，而不是项目仓库里的同名文件。
执行时先定位 skill 的安装目录，再运行：
```bash
python3 <skill安装目录>/scripts/calver.py
```
- 如果环境不能提供安装目录，或目录无法可靠确定，立即停止并告知用户。
+ 通过本 SKILL.md 的实际路径解析安装目录和符号链接；无法可靠定位时，不猜测版本号，只停止依赖该脚本的步骤。
## 工作流程
1. 查看仓库状态，确认当前变更范围。
2. 只暂存并提交与当前任务相关的文件。
3. Commit Message 必须严格遵循下面的 **Commit Message 规范**（若用户提供了额外的说明，应当融合至该格式中）。
- 4. 运行 `calver.py` 获取下一个版本号。
- 5. 用该版本号创建 tag。
+ 4. 本次包含打 tag 时，运行 `calver.py` 获取下一个版本号。
+ 5. 本次包含打 tag 时，用该版本号创建 tag。
6. 如用户明确要求推送，再执行 `git push` 和 `git push --tags`。
## Commit Message 规范
提交变更时，Commit Message 必须严格遵循以下格式约束：
```text
<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）**。每次提交都必须严格遵循以下要求：
+ 仅在用户已授权提交时，按独立、可验证的逻辑边界组织**原子提交（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，直到所有变更块均已被独立且干净地提交。
+ - 按受影响范围验证。可复用同一代码状态的有效结果；不因提交数量重复全量构建。验证中间提交时使用其实际文件树，不能以包含后续未提交改动的工作树测试代替。
+ 4. **循环往复**：重复步骤 3，直到本次授权范围内的变更块均已提交。
5. **CalVer 与 Tag 规则**：
- - **仅在最后一个原子提交**完成后，才运行 `calver.py` 获取最新版本号，并为该次最新提交打上 tag。
+ - 本次包含打 tag 时，**仅在最后一个原子提交**完成后，才运行 `calver.py` 获取最新版本号，并为该次最新提交打上 tag。
- 前置的过渡性原子提交**不需要**打 tag。
## 整理提交历史工作流
- 当触发词包含“整理提交历史”、“准备开 PR”、“squash 提交”、“合并提交”、“git rebase”或用户明确要求在开 PR 前整理分支提交历史时，应采用以下独立触发的提交历史整理工作流：
+ 仅在用户明确要求 squash、合并提交或 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` 展示最终的精简、规范的提交历史，确保整理结果符合预期。
+ 1. 读取分支、工作树和上游状态，确定实际基线 `<base>` 与待整理的提交范围；不要假定主干叫 `main`。保护无关改动并保存原 HEAD，便于恢复。
+ 2. 规划保留、合并的提交及其消息，遵循上面的 Commit Message 规范。
+ 3. 用户已明确授权范围内的本地历史整理可直接执行，不重复索要确认。共享/已发布历史的改写或超出已授权范围时，先展示具体方案并取得相应授权；已有明确授权继续有效。
+ 4. 在该范围内执行 `git rebase -i <base>`，必要时用非交互的 `GIT_SEQUENCE_EDITOR`。历史整理不自动授权强制推送。
+ 5. 检查最终提交历史和文件树；纯 squash 若文件树未变，可复用原验证结果；冲突解决改变代码时验证受影响部分。完成已授权目标后结束，不自动追加整理或优化。
## CalVer 规则
- 格式：`YY.WW.MICRO`
- `YY`：ISO 年份后两位
- `WW`：ISO 周数
- `MICRO`：全局递增序号，跨年不重置
## 常见错误
| 错误做法 | 正确做法 |
|---|---|
| 在项目仓库里找 `scripts/calver.py` | 在 skill 安装目录里执行脚本 |
- | 找不到路径就手动算版本号 | 直接停止 |
- | 用户没明确要求就 push | 先只提交和打 tag |
+ | 找不到路径就手动算版本号 | 停止计算版本和打 tag，报告原因 |
+ | 用户没明确要求就 push | 仅完成已授权的本地 commit/tag |
| 把无关文件一起提交 | 只提交当前任务相关文件 |