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

决定提交边界（必要时拆分） [见「分门别类拆分规范」]

• 先分析上下文：认真阅读对话中用户描述的改动内容，理解本次修改的业务意图。

• 四维拆分依据：

• 文件类型：配置文件 vs 源码 vs 文档 vs 测试文件

• 业务功能模块：不同业务模块的改动独立提交（如 auth vs payment ）

• 修改类型：新增功能 vs 修复 Bug vs 重构 vs 格式化（不同 type 的改动分开）

• 修改范围：前端 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 信息中查找：

• "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 邮箱对照表」进行转换

• ⚠️ 重要原则：若在对照表中找不到该客户端或模型对应的已验证 GitHub 账号，必须跳过，不得填写任何 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 API（https://api.github.com/user/:id

• /users/:login/orgs ）验证，确认账号归属可信。

• 若某工具或模型不在此表中，禁止编造或猜测账号，直接跳过 Co-authored-by。

已验证的 Co-authored-by 账号

工具名称 GitHub 账号 / 邮箱类型 关注者数 / 验证来源 Co-authored-by 格式

Cursor cursoragent 1,856 Co-authored-by: Cursor <199161495+cursoragent@users.noreply.github.com>

Claude Code 公司邮箱 官方文档 Co-authored-by: Claude <noreply@anthropic.com>

无官方账号（禁止使用）

以下工具/模型目前没有经验证的官方 GitHub bot 账号或公司邮箱，禁止使用任何冒名抢注账号：

• AI CLI：Codex CLI（属于 openai 组织）、Gemini CLI（属于 google-gemini 组织）均无专属 bot 账号

• AI IDE：VS Code、Trae、Codebuddy、Antigravity、Qoder、Kiro 均未确认官方 bot 账号

• AI 模型：OpenAI GPT 系列、Gemini 系列、MiniMax 系列、GLM 系列均无官方归属账号

待各厂商官方提供可验证的 bot 账号或公司邮箱后再补充到此表中。

已确认的假冒/冒名账号黑名单 [CRITICAL]

以下账号均已通过 GitHub API 验证为非官方账号，严禁在 Co-authored-by 中使用。 即使 AI 模型"记住"了这些账号，也绝对不能使用。

冒充目标 假冒账号 ID 判定为假冒的依据

Claude Code anthropics-claude

237456255 不属于 anthropics 组织；仓库包含 Solana 加密货币诈骗项目（clabs ）；仅 2 个关注者。注意：Claude Code 有官方邮箱 noreply@anthropic.com ，请使用该邮箱而非此假冒账号

Gemini CLI google-gemini-cli

229672533 不属于 google-gemini 组织；仓库全部是 fork（无原创内容）；仅 5 个关注者

Codex CLI codex-cli

208188539 不属于 openai 组织；OpenAI 发布 Codex（2025-04-13）后 5 天抢注；0 个公开仓库、仅 2 个关注者

VS Code vscode-triage-bot

62039782 这是 VS Code 仓库的 Issue 分流机器人，不代表 VS Code IDE 本体，用于 Co-authored-by 会产生语义误导

GLM-5 zhipuch

178361551 普通个人用户，与智谱 AI / GLM 无任何关联

Trae Trae-AI-Admin

192575406 不属于任何组织；0 个公开仓库；无法确认为 Trae 官方账号

Codebuddy CodeBuddy-Official-Account

214620440 不属于任何组织；无法确认为 Codebuddy 官方账号

Antigravity antigravity-ai

256725992 仅 1 个关注者；0 个公开仓库；2026-01-23 才创建；无法确认为官方账号

Qoder Qoder-AI

215799558 不属于任何组织；仅 8 个关注者；无法确认为官方账号

Kiro kiro-ai

201607104 0 个关注者；0 个公开仓库；无法确认为官方账号

MiniMax MiniMax-OpenPlatform

239562665 不属于任何组织；无法确认为 MiniMax 官方账号

为什么要维护黑名单？ AI 模型在生成 Co-authored-by 时，可能会从训练数据或互联网上"回忆"起这些账号并自动填入。明确列出黑名单可以防止这种行为，避免你的 GitHub 仓库贡献者列表中出现无关甚至恶意的第三方。

交付物

提供：

• 最终的提交信息（包含 Emoji，中文编写）

• 每个提交的简短摘要（内容/原因）

• 用于暂存/审查的命令（至少：git diff --cached ，加上运行的任何测试）