Git Commit

来源说明

该技能本质上是参考 agent-toolkit/skills/commit-work 文档的纯中文翻译版本，并进行了特定改写以适应当前环境。

目标

制作易于审查且安全发布的提交：

仅包含预期的变更
提交具有逻辑范围（必要时进行拆分）
提交信息描述了变更内容和原因

需要询问的输入（如果缺失）

单个提交还是多个提交？（如果不确定：当存在不相关的变更时，默认为多个小提交。）
提交风格：必须使用 Conventional Commits，并包含 Emoji。
任何规则：最大标题长度，必需的作用域。

工作流程（清单）

检查暂存区与工作树状态（优先暂存区）
- git status
- 首先检查暂存区是否有内容：git diff --cached --stat
  - ✅ 暂存区有文件：本次提交只针对暂存区，不要自行 git add 额外文件。直接跳到步骤 4 审查暂存内容。
  - 📭 暂存区为空：才需要从工作树中选取文件进行暂存，继续步骤 2-3。
- 如果需要查看工作树的变更：git diff 或 git diff --stat
决定提交边界（必要时拆分） [见「分门别类拆分规范」]
- 先分析上下文：认真阅读对话中用户描述的改动内容，理解本次修改的业务意图。
- 四维拆分依据：
  1. 文件类型：配置文件 vs 源码 vs 文档 vs 测试文件
  2. 业务功能模块：不同业务模块的改动独立提交（如 auth vs payment）
  3. 修改类型：新增功能 vs 修复 Bug vs 重构 vs 格式化（不同 type 的改动分开）
  4. 修改范围：前端 vs 后端，依赖升级 vs 行为变更，生产代码 vs 测试代码
- 如果变更混合在一个文件中，计划使用补丁暂存 (patch staging)。
仅暂存属于下一个提交的内容（暂存区为空时才执行此步）
- 对于混合变更首选补丁暂存：git add -p
- 取消暂存块/文件：git restore --staged -p 或 git restore --staged <path>
审查实际将要提交的内容
- git diff --cached
- 合规性检查：
  - 无密钥或令牌
  - 无意外的调试日志
  - 无不相关的格式化变动
用 1-2 句话描述暂存的变更（在编写信息之前）
- "变更了什么？" + "为什么？"
- 如果你无法清晰地描述它，那么提交可能太大或混合了；返回第 2 步。
编写提交信息
- 必须使用中文编写提交信息。
- 使用 Conventional Commits（必需）：
  - 普通提交：<emoji> type(scope): summary
  - 破坏性变更：<emoji> type(scope)!: summary（感叹号紧跟在 ) 之后，冒号之前）
  - (空行)
  - body (内容/原因，而非实现流水账)
  - footer：破坏性变更时必须包含 BREAKING CHANGE: <说明> 行
- Emoji 和 Type 规范：必须查阅并遵循 commit-types.ts 中的定义。
  - 主动查阅：使用 Read 或 WebFetch 工具主动读取上述文件以获取最新的 Emoji 和 Type 列表。
- 推荐使用文件方式（解决 Windows/PowerShell 中文乱码问题）：
  - 由于 Cursor IDE 的 Shell 工具在通过 -m 参数传递中文时存在编码问题，推荐使用 -F 文件方式提交
  - 创建临时提交信息文件（如 commit-message.txt），写入提交信息内容
  - 注意：此步骤只创建文件，暂不执行提交
- 参考 references/commit-message-template.md 获取完整的模板和 Emoji 列表。
运行最小的相关验证
- 在提交之前运行仓库中最快且有意义的检查（单元测试、lint 或构建）。
- 验证通过后再执行步骤 8 进行提交。
- 如果验证失败，修复问题后重新执行验证。
获取 Co-authored-by 信息并执行提交
- 获取 AI 客户端型号：从当前对话的 system prompt 或初始化信息中查找：
  - "You are Claude Code" → 客户端 = "Claude Code"
  - "You are Cursor" → 客户端 = "Cursor"
  - "You are Gemini CLI" → 客户端 = "Gemini CLI"
  - 其他 AI IDE / CLI 同理
- 获取 AI 模型型号：从当前对话的 model 信息中查找：
  - "gpt-5.2" → 模型 = "OpenAI GPT-5.2"
  - "gpt-5.3" → 模型 = "OpenAI GPT-5.3"
  - "gpt-5.4" → 模型 = "OpenAI GPT-5.4"
  - "MiniMax-M2.5-highspeed" → 模型 = "MiniMax-M2.5"
  - "claude-opus-4-6" → 模型 = "Claude Opus 4.6"
  - "claude-sonnet-4-6" → 模型 = "Claude Sonnet 4.6"
  - 其他模型同理
- 转换为 Co-authored-by 格式：根据下方的「Co-authored-by 邮箱对照表」进行转换
- 使用 --trailer 参数追加：
```
# 使用文件方式提交，并追加 Co-authored-by trailer
git commit -F commit-message.txt \
  --trailer "Co-authored-by: <AI客户端> <邮箱>" \
  --trailer "Co-authored-by: <AI模型> <邮箱>"
```
  如果有多个 Co-authored-by 信息，使用多个 --trailer 参数。
- 提交成功后删除临时文件：
```
rm commit-message.txt
```
- 验证提交是否成功：
  - 运行 git status 确认工作树已干净
  - 运行 git log -1 查看最终提交信息
重复下一个提交，直到工作树干净

优先处理暂存区 [CRITICAL]

在开始任何提交流程之前，首先检查 git 暂存区（staging area / index）是否已有文件。

这是基于尊重用户意图的原则：如果用户已经手动 git add 了某些文件，说明他们明确知道要提交什么，此时不应画蛇添足地扩大提交范围。

暂存区状态	处理方式
有暂存文件	直接对暂存区内容进行提交，不自行 `git add` 任何额外文件
暂存区为空	从工作树分析所有变更，按拆分规范选取文件并暂存后再提交

检查命令：

# 检查暂存区是否有内容
git diff --cached --stat

# 有输出 → 暂存区有文件，直接进入审查流程
# 无输出 → 暂存区为空，需要从工作树选取文件

分门别类拆分提交规范 [CRITICAL]

当用户提及**「分门别类」**，或工作树中存在较多文件变更时，必须认真分析上下文，将变更拆分为若干个逻辑独立的小提交，而不是粗暴地一次性 git add . 全量提交。

为什么要拆分

每个提交都有清晰的单一职责，方便 code review 和问题追溯
出现问题时可以精准 git revert 单个提交而不影响其他变更
符合 Conventional Commits 语义：一个 type 对应一类变更

四个拆分维度

在分析本次变更时，请从以下四个维度逐一评估，发现可拆分点就独立成一个提交：

1. 按文件类型拆分

不同类型的文件通常对应不同关注点：

配置文件（*.json, *.yaml, *.toml, nitro.config.ts 等）→ config 类型
文档文件（*.md, CHANGELOG, README）→ docs 类型
测试文件（*.test.ts, *.spec.ts）→ test 类型
依赖文件（package.json, pnpm-lock.yaml）→ deps 类型
核心源码文件 → feat / fix / refactor 类型

2. 按业务功能模块拆分

不同业务模块的改动应独立提交，即使它们都是同一类型（如 feat）：

feat(auth): ... 和 feat(payment): ... 应分开
fix(users): ... 和 fix(orders): ... 应分开

3. 按修改类型拆分

不同 type 的变更必须分开提交，不能混在一起：

新增功能（feat）和修复 Bug（fix）→ 分开
功能代码（feat/fix）和格式化（style）→ 分开
业务逻辑和重构（refactor）→ 分开

4. 按修改范围拆分

前端代码 vs 后端代码
生产代码 vs 测试代码
应用代码 vs 基础设施/工具链代码

拆分决策流程

分析变更文件列表
    ↓
有没有不同 type 的混合变更？ → 是 → 按类型拆分
    ↓ 否
有没有跨越多个业务模块的变更？ → 是 → 按模块拆分
    ↓ 否
有没有配置/文档/测试等文件混在一起？ → 是 → 按文件类型拆分
    ↓ 否
变更范围是否横跨前后端或基础设施？ → 是 → 按范围拆分
    ↓ 否
所有变更都聚焦于同一职责 → 可以合并为一个提交

示例：工作树有 8 个文件的拆分方案

变更文件：
  M  src/api/users.ts          # 后端业务逻辑：新增用户查询
  M  src/api/orders.ts         # 后端业务逻辑：修复订单Bug
  M  src/components/UserList.vue # 前端组件
  M  nitro.config.ts            # 配置文件
  M  package.json               # 依赖升级
  M  pnpm-lock.yaml             # 依赖锁定文件
  M  tests/users.test.ts        # 测试文件
  M  CHANGELOG.md               # 文档

推荐拆分为 5 个提交：
  提交1: ✨ feat(users): 新增用户查询接口       ← src/api/users.ts
  提交2: 🐞 fix(orders): 修复订单数量计算错误   ← src/api/orders.ts
  提交3: ✨ feat(ui): 新增用户列表组件          ← src/components/UserList.vue
  提交4: 🧪 test(users): 补充用户查询单测       ← tests/users.test.ts
  提交5: 📦 deps: 升级依赖并更新配置            ← package.json + pnpm-lock.yaml + nitro.config.ts
  (CHANGELOG.md 通常随其他提交一起或单独 docs 提交)

破坏性变更规范 [CRITICAL]

当用户提及**「破坏性变更」**关键词，或本次变更确实存在不向下兼容的 API/行为改动时，必须按以下规范编写提交信息。

感叹号位置（唯一正确格式）

<emoji> type(scope)!: summary

! 紧跟在 ) 之后，冒号 : 之前
! 与 ) 之间不留空格
! 与 : 之间不留空格

错误示例 vs 正确示例

写法	状态	问题说明
`🦄 refactor!(scope): summary`	❌	感叹号在 type 之后、scope 之前，不符合规范
`🦄 refactor(scope) !: summary`	❌	感叹号与 `)` 之间有空格
`🦄 refactor(scope)! : summary`	❌	感叹号与 `:` 之间有空格
`🦄 refactor(scope)!: summary`	✅	正确——`!` 紧跟在 `)` 之后，无空格
`🦄 refactor!: summary`（无 scope）	✅	无 scope 时 `!` 紧跟在 type 之后

完整破坏性变更提交模板

<emoji> type(scope)!: 简短描述破坏性变更

BREAKING CHANGE: 详细说明破坏性变更的内容、原因，以及用户需要如何迁移。

- 变更点 1
- 变更点 2

示例

🦄 refactor(nitro-api-development)!: 从 11comm 项目提取技能并重构为通用版本

BREAKING CHANGE: 删除了 reference.md 和 templates.md，替换为 references/ 和 templates/ 子目录结构。

- 移除 reference.md
- 移除 templates.md
- 新增 references/ 子目录（含 7 个专项文档）
- 新增 templates/ 子目录（含 2 个可复用 TypeScript 文件）

Co-authored-by 邮箱对照表

注意：GitHub 识别 Co-authored-by 主要依赖邮箱是否能归属到 GitHub 账号。下面统一改为对应账号的 users.noreply.github.com 邮箱，避免继续使用无法在 GitHub 内归属到用户名的厂商域名邮箱。

AI & IDE 开发工具

工具名称	Co-authored-by 格式
VS Code	`Co-authored-by: VSCode <62039782+vscode-triage-bot@users.noreply.github.com>`
Cursor	`Co-authored-by: Cursor <199161495+cursoragent@users.noreply.github.com>`
Trae	`Co-authored-by: Trae <192575406+Trae-AI-Admin@users.noreply.github.com>`
Codebuddy	`Co-authored-by: Codebuddy <214620440+CodeBuddy-Official-Account@users.noreply.github.com>`
Antigravity	`Co-authored-by: Antigravity <256725992+antigravity-ai@users.noreply.github.com>`
Qoder	`Co-authored-by: Qoder <215799558+Qoder-AI@users.noreply.github.com>`
Kiro	`Co-authored-by: Kiro <201607104+kiro-ai@users.noreply.github.com>`

AI CLI 命令行工具

工具名称	Co-authored-by 格式
Claude Code	`Co-authored-by: Claude-Code <237456255+anthropics-claude@users.noreply.github.com>`
Gemini CLI	`Co-authored-by: Gemini-CLI <229672533+google-gemini-cli@users.noreply.github.com>`
Codex CLI	`Co-authored-by: Codex-CLI <208188539+codex-cli@users.noreply.github.com>`

AI 大模型系列

模型系列	Co-authored-by 格式
Claude Opus 4.6	`Co-authored-by: Claude-Opus-4.6 <237456255+anthropics-claude@users.noreply.github.com>`
Claude Sonnet 4.5	`Co-authored-by: Claude-Sonnet-4.5 <237456255+anthropics-claude@users.noreply.github.com>`
Claude Sonnet 4.6	`Co-authored-by: Claude-Sonnet-4.6 <237456255+anthropics-claude@users.noreply.github.com>`
Claude Haiku 4.5	`Co-authored-by: Claude-Haiku-4.5 <237456255+anthropics-claude@users.noreply.github.com>`
OpenAI GPT-4.5	`Co-authored-by: OpenAI-GPT-4.5 <208188539+codex-cli@users.noreply.github.com>`
OpenAI GPT-5.2	`Co-authored-by: OpenAI-GPT-5.2 <208188539+codex-cli@users.noreply.github.com>`
OpenAI GPT-5.3	`Co-authored-by: OpenAI-GPT-5.3 <208188539+codex-cli@users.noreply.github.com>`
OpenAI GPT-5.4	`Co-authored-by: OpenAI-GPT-5.4 <208188539+codex-cli@users.noreply.github.com>`
Gemini 3 Pro	`Co-authored-by: Gemini-3-Pro <229672533+google-gemini-cli@users.noreply.github.com>`
Gemini 2.5 Flash	`Co-authored-by: Gemini-2.5-Flash <229672533+google-gemini-cli@users.noreply.github.com>`
MiniMax M2.5	`Co-authored-by: MiniMax-M2.5 <239562665+MiniMax-OpenPlatform@users.noreply.github.com>`
GLM-5	`Co-authored-by: GLM-5 <178361551+zhipuch@users.noreply.github.com>`

交付物

提供：

最终的提交信息（包含 Emoji，中文编写）
每个提交的简短摘要（内容/原因）
用于暂存/审查的命令（至少：git diff --cached，加上运行的任何测试）

git-commit