--- name: git-commit description: >- 创建高质量的 git 提交：审查/暂存预期的变更，拆分为逻辑提交，并编写清晰的提交信息 （遵循 Conventional Commits 规范，支持 Emoji）。当用户要求提交代码、编写提交信息、 暂存变更或将工作拆分为多个提交时使用此技能。当用户提及【破坏性变更】关键词时， 必须按照本技能的 BREAKING CHANGE 规范使用感叹号格式编写提交信息。 优先针对 git 暂存区（staged）中的文件进行提交，只有当暂存区为空时才考虑整个工作树。 当用户提及【分门别类】关键词时，必须按照本技能的多提交拆分规范， 从文件类型、业务模块、修改类型、修改范围四个维度认真拆分多个提交。 user-invocable: true metadata: version: "0.7.0" --- # Git Commit ## 目标 仅包含预期的变更 → 逻辑拆分 → 信息描述变更内容和原因 ## 预解析任务包（快速路径） 当主代理已经完成范围分析并提供任务封包时，执行代理可以走快速路径，跳过重复扫描对话历史和无关目录。任务封包必须同时包含以下字段： ```yaml scope: [允许提交的仓库相对路径或绝对路径] exclude: [明确排除的工作区修改] groups: - type: publish scope: ai-plugins emoji: 📢 files: [本组文件列表] summary: 发布元数据 verification: [每组提交前后的最小验证命令] identityCheck: client: 客户端名称及 allowlist 结果 model: 模型名称及 allowlist 结果 trailer: 追加或不追加 Co-authored-by 的结论 ``` 快速路径的硬门槛： 1. 先用 `git status --short --branch`、`git diff --cached` 和目标组文件清单确认封包仍与工作树一致；不一致时退回完整工作流程并报告差异。 2. 只允许暂存 `scope` 和当前 `groups` 的文件，`exclude` 中的修改始终保持未暂存；禁止回退范围外文件。 3. 仍必须执行 staged diff 审查、敏感信息扫描、commitlint、最小验证、提交后 `git log -1` 与 `git status` 复核；快速路径只能省略重复发现，不能省略证据门。 4. 同一任务只解析一次远程或本地 `commit-types.ts`，后续分组复用 `type/emoji` 结果；`identityCheck` 也只按封包结论执行一次，不重复猜测。 5. 每个提交返回 commit hash、提交正文、实际文件集合和原始验证输出；最终确认没有 `commit-message.txt` 或其他临时文件残留，且不执行 `git push`。 如果封包缺少任一字段、白名单含糊或验证命令不可复现，不得使用快速路径。 ## 规则来源优先级 [CRITICAL] 生成提交信息时，按以下优先级决策，低优先级不得覆盖高优先级： 1. 用户在当前对话中的明确要求 2. 当前仓库本地 commit / commitlint 规则（如 `commitlint.config.*`、`.commitlintrc*`、`package.json` 中的 `commitlint` 字段、`commit-msg` hook） 3. 远程 raw `commit-types.ts`（首选）+ 本地 `commit-types.ts`（fallback，详见步骤 6） 4. 技能默认模板、示例与 `references/commit-message-template.md` - 若多个来源冲突，必须以更高优先级来源为准。 - 若更高优先级来源缺失或读取失败，必须停下说明，不得猜测。若来源内容完整但含义明确（如 commitlint 规则已定义 scope 列表等），直接按规则执行即可。 ## 工作流程（清单） 1. **检查暂存区与工作树状态（优先暂存区）** - `git status` - **首先检查暂存区是否有内容**：`git diff --cached --stat` - ✅ **暂存区有文件**：本次提交只针对暂存区，不要自行 `git add` 额外文件。直接跳到步骤 4 审查暂存内容。 - 📭 **暂存区为空**：才需要从工作树中选取文件进行暂存，继续步骤 2-3。 - 如果需要查看工作树的变更：`git diff` 或 `git diff --stat` 2. **决定提交边界（必要时拆分）** [见「分门别类拆分规范」] - **先锁定文件范围** [CRITICAL]： - 认真阅读用户指令，确认本次提交的**文件范围**（如"只处理涉及到的文件""只处理你改过的文件""提交 xx 目录"）。 - 将工作树中**不在范围内**的文件列出但不暂存，即使它们有未提交修改。 - **绝对禁止**对范围外的文件执行 `git checkout --`、`git restore`、`git reset` 等回退操作——你无法判断这些修改的来源和意图，回退会导致数据丢失。 - 如果范围外文件有未提交修改，在最终汇报中向用户提一句"以下文件有未提交修改但未纳入本次提交范围"，让用户自行决定如何处理。 - **先分析上下文**：认真阅读对话中用户描述的改动内容，理解本次修改的业务意图。 - **四维拆分依据**： 1. **文件类型**：配置文件 vs 源码 vs 文档 vs 测试文件 2. **业务功能模块**：不同业务模块的改动独立提交（如 `auth` vs `payment`） 3. **修改类型**：新增功能 vs 修复 Bug vs 重构 vs 格式化（不同 type 的改动分开） 4. **修改范围**：前端 vs 后端，依赖升级 vs 行为变更，生产代码 vs 测试代码 - 如果变更混合在一个文件中，计划使用补丁暂存 (`patch staging`)。 3. **仅暂存属于下一个提交的内容**（暂存区为空时才执行此步） - 对于混合变更首选补丁暂存：`git add -p` - 取消暂存块/文件：`git restore --staged -p` 或 `git restore --staged ` 4. **审查实际将要提交的内容** - `git diff --cached` - **合规性检查**： - 无密钥或令牌 - 无意外的调试日志 - 无不相关的格式化变动 - **检查通过后直接继续**：如果以上三项检查全部通过，**不要停下来询问用户"是否涉及敏感信息"**。直接继续到步骤 5。只有在检查发现可疑内容时才需要向用户确认。 5. **用 1-2 句话描述暂存的变更（在编写信息之前）** - "变更了什么？" + "为什么？" - 如果你无法清晰地描述它，那么提交可能太大或混合了；返回第 2 步。 6. **编写提交信息** - **语言选择（默认中文，按上下文切换）**： - **默认**使用中文编写提交信息。 - **例外**：如果正在向一个使用英文的开源/上游仓库提交 PR（`git log` 中最近提交均为英文），则改用英文编写。判断依据： - 检查当前分支的上游目标仓库的提交语言风格（`git log --oneline` 最近的 5-10 条记录） - 如果上游/目标仓库全部使用英文 → 改用英文 - 否则 → 保持中文（默认） - 无论中英文，summary 和 body 的语言必须保持一致。 - 使用 **Conventional Commits**（必需）： - 普通提交：` type(scope): summary` - 破坏性变更：` type(scope)!: summary`（感叹号紧跟在 `)` 之后，冒号之前） - （空行） - body （内容/原因，而非实现流水账） - footer：破坏性变更时必须包含 `BREAKING CHANGE: <说明>` 行 - **Emoji 和 Type 规范**：必须查阅并遵循 `commit-types.ts` 中的定义，按以下优先级获取： - **首选（远程 raw，确保最新）**：从 GitHub 远程获取最新定义： - `https://raw.githubusercontent.com/ruan-cat/monorepo/dev/configs-package/commitlint-config/src/commit-types.ts` - 远程文件是权威来源，优先使用以确保 type/emoji 映射是最新的。 - **次选（技能自带的本地文件）**：若远程 raw 获取失败（网络不可用/超时/HTTP 错误），再回退到本技能目录下的 `references/commit-types.ts` - 读取该文件，解析 `commitTypes` 数组，定位本次要使用的 `type`。 - 该文件是随技能一起分发的快照副本，版本可能落后于远程，但可确保离线可用。 - **禁止仅依据搜索摘要或缓存判断 emoji**——必须读取完整文件后定位 type。在继续之前，显式复述本次解析结果：`selected type`、`resolved emoji`、命中的原始片段。 - 同一任务包含多个逻辑提交时，只需在第一个分组解析一次；后续分组复用已确认的映射，并在执行记录中标明复用，不要重复读取和推断。 - 若远程和本地都获取失败 → **停止**，报告"无法获取 commit-types.ts，无法确定合法 type 与 emoji"，不得猜测或回退到旧表格。 - **推荐使用文件方式**（避免 shell 参数传递导致的编码与转义问题）： - 对于包含中文的 commit message，默认使用 `git commit -F commit-message.txt` - 创建临时提交信息文件（如 `commit-message.txt`），写入提交信息内容 - ⚠️ **此步骤只创建提交信息文件，不要在此步骤执行 `git commit`**。真正的提交执行将在步骤 9 进行。 - **不要在步骤 6 就停下来向用户展示提交信息文本后结束流程**——继续执行步骤 7→8→9 完成整个提交流程。 - 参考 `references/commit-message-template.md` 获取模板格式与 BREAKING CHANGE 示例，不要把其中内容当作 emoji/type 真值。 7. **提交信息预校验 [CRITICAL]** - 优先检查当前仓库是否存在本地 commit 规则：`commitlint.config.*`、`.commitlintrc*`、`package.json` 的 `commitlint` 字段、`commit-msg` hook。 - 如果仓库存在本地 commitlint 配置或可执行 `commitlint`，必须先对 `commit-message.txt` 做预校验，再允许进入 `git commit`。 - 推荐命令：`pnpm exec commitlint --edit commit-message.txt --strict`；若仓库使用 `npx --no-install commitlint`，按仓库现有 hook / 脚本保持一致。 - 任何 warning、error 或 rule violation 都视为阻塞，必须先修正文案，再继续。 - 若仓库要求 scope，必须使用合法 scope；若无法确定合法 scope，停止并说明原因。 - 若仓库未要求 scope，优先省略 scope，而不是臆造 scope。 8. **运行最小的相关验证** - 按下方「最小有效校验矩阵」选择本次提交前的默认最小校验。 - 验证通过后再执行步骤 9 进行提交。 - 如果验证失败，修复问题后重新执行验证。 - 如果仓库确实不存在任何有意义的自动校验，必须在最终说明中明确“未运行校验，原因是仓库无可用脚本/规则”。 9. **获取 Assisted-by / 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" - 其他模型同理 - **生成 Assisted-by** [CRITICAL]： - 直接复用上面已经获取到的客户端名称和模型名称，不新增第二套识别流程，不改变现有客户端/模型获取规则。 - 当客户端和模型都可以可靠获取时，必须追加且仅追加一条 `Assisted-by: AGENT_NAME / MODEL_VERSION` trailer；固定为**客户端/Agent 在前、模型在后**，斜杠 `/` 两侧各一个空格。 - 示例：`Assisted-by: Codex / gpt-5.6-terra`、`Assisted-by: Claude Code / deepseek-v4-flash`、`Assisted-by: WorkBuddy / MiniMax-M2.5`。 - 本步骤不额外判断“AI 是否实质参与”“是否属于 meaningful assistance”或贡献比例；只要本技能实际执行本次 commit 且两个身份字段均已取得，就生成该 trailer。 - `Assisted-by` 仅记录本次实际运行的 Agent 与 Model，不查询 GitHub 账号/邮箱，也不使用下方 Co-authored-by 的 allowlist 或 blacklist；它与 `Co-authored-by` 相互独立、可以同时存在。 - 只要客户端或模型任一项无法可靠取得，就跳过 `Assisted-by`；不得降级成单字段形式，不得写 `Unknown`，不得猜测或联网补全缺失字段。 - **必须输出检测日志**：`→ Assisted-by 检测: 客户端="{客户端名}"; 模型="{模型名}"; 结论="{Assisted-by trailer 或跳过原因}"`。 - **Co-authored-by 逐项判定**：客户端与模型必须分别判断是否在下方 allowlist 中，不得把“客户端可验证”自动扩展为“模型也可验证”。 - **必须输出检测日志**（无论结果如何）： - 格式：`→ Co-authored-by 检测: 客户端="{客户端名}" → {在/不在} allowlist; 模型="{模型名}" → {在/不在} allowlist; 结论="{结论}"` - 例如：`→ Co-authored-by 检测: 客户端="WorkBuddy" → 不在 allowlist; 模型="Deepseek-V4-Flash" → 不在 allowlist; 结论="不追加任何 trailer"` - 这样做是为了让用户明确知道检测过程，而非"Co-authored-by 神秘消失"。 - 仅允许以下四种结果： 1. 仅客户端可验证 → 只追加客户端 trailer 2. 仅模型可验证 → 只追加模型 trailer 3. 二者都可验证 → 追加两条 trailer 4. 二者都不可验证或无法识别 → 不追加任何 trailer - 如果当前会话无法可靠得到模型标识，必须视为“模型不可验证”，不得猜测。 - 当前非 allowlist 客户端（如 Codex、Gemini CLI 等）默认不写 Co-authored-by，除非下方对照表后续明确补充。 - **使用 `--trailer` 参数追加**：执行 `git commit -F commit-message.txt` 时： - 若 `Assisted-by` 条件满足，先追加一条对应的 `--trailer "Assisted-by: AGENT_NAME / MODEL_VERSION"`。 - 再按原有 Co-authored-by 判定结果，仅为已验证身份追加对应的 `--trailer`；一条身份对应一条 `Co-authored-by` trailer。 - `Assisted-by` 是否存在不受 Co-authored-by allowlist 判定影响；即使客户端或模型没有可验证 GitHub 身份，只要两项运行时身份都可靠取得，仍然可以生成 `Assisted-by`。 - **提交成功后删除临时文件**： - PowerShell：`Remove-Item -LiteralPath commit-message.txt` - POSIX Shell：`rm -- commit-message.txt` - **复核提交结果**： - `git log -1 --format=%B` - `git status --short --branch` - 若 commit 过程中出现 warning、hook 改写了文件、或最终提交信息与预期不一致，不能直接宣称完成，必须先修正。 - **🛑 不要推送**：执行完提交后，**不要执行 `git push`**。推送操作由用户自行决定并执行。 10. **重复下一个提交，直到工作树干净** ## 最小有效校验矩阵 [CRITICAL] | 变更类型 | 默认最小校验 | | :----------------- | :------------------------------------------------------- | | 仅 Markdown / 文档 | Markdown 格式化或与文档渲染链路相关的最小构建 | | 仅配置 | 对应 lint / config check / 最小 build | | 源码 | 对应模块的 test / typecheck / build 中最快且有意义的一项 | | 混合改动 | 选择覆盖主要风险面的最小组合校验 | ## 分门别类拆分提交规范 [CRITICAL] 当工作树中存在较多文件变更时，**必须**将变更拆分为独立小提交，而非全量提交。按以下决策流程执行： ```plain 分析变更文件列表 ↓ 有没有不同 type 的混合变更？ → 是 → 按 type 拆分 ↓ 否 有没有跨越多个业务模块的变更？ → 是 → 按模块拆分 ↓ 否 有没有配置/文档/测试等文件混在一起？ → 是 → 按文件类型拆分 ↓ 否 变更范围是否横跨前后端或基础设施？ → 是 → 按范围拆分 ↓ 否 所有变更都聚焦于同一职责 → 合并为一个提交 ``` ### 文件移动（rename）检测 [CRITICAL] **在按 type/模块/文件类型拆分之前，必须先过文件移动检测**。文件移动是最优先级的拆分约束，高于其他任何维度。 ```plain 检查 git status --short 中是否存在同名文件对 ↓ 同时出现 D <旧路径/文件名> 和 ?? <新路径/文件名> 且 basename 相同？ ↓ 是 这些文件必须合并为一个 rename 提交，禁止拆成删除 + 新增两个提交 ↓ 否 继续正常的 type/模块/文件类型拆分流程 ``` **检测步骤**（每次执行 git-commit 时强制执行）： 1. 运行 `git status --short`，分别收集 `D` 行（已删除）和 `??` 行（未追踪）中的文件名 basename。 2. 对 `D` 行和 `??` 行的 basename 做交叉比对。 3. 若命中（同名文件，不同父目录）：**必须**将对应的删除和新增合并为**一个** rename 提交。提交时用 `git add` 同时暂存旧路径删除和新路径新增，让 git 自动识别 rename。 4. 若已拆分为独立的删除提交 → `git reset --soft HEAD~1` 撤销，补暂存新增路径后重提交。 **识别 signal**： - `git diff --cached --stat` 中出现大量 `deletions(-)` 且 0 `insertions(+)` → 立即检查 `git status --short` 中是否有匹配的 `??` 行 - `git status --short` 输出的 `D` 和 `??` 行中，basename 相同但父目录不同 → 几乎一定是文件移动 **type 与文件类型映射参考**：配置文件→`config`，文档→`docs`，测试→`test`，依赖→`deps`，核心源码→`feat`/`fix`/`refactor` > 详细拆分示例（含 8 文件拆分方案）参见 `references/commit-splitting-example.md`。 ## 破坏性变更规范 [CRITICAL] 当用户提及**「破坏性变更」**关键词，或本次变更确实存在不向下兼容的 API/行为改动时，**必须**按以下规范编写提交信息。 ### 主动评估准则（每次提交前执行） **不要只等用户说"破坏性变更"才行动。** 在完成步骤 5 后（描述变更内容后），主动对照以下清单判断本次变更是否属于破坏性： | 判断维度 | 属于破坏性变更的情况 | 不属于破坏性变更的情况 | | :------------------ | :------------------------------------------------------------------------- | :--------------------------------------------------- | | **API 签名变更** | 函数参数数量/顺序/类型变化、删除导出的函数或类、重命名公共 API | 新增仅额外可选参数的 API、内部私有函数改名 | | **配置格式变更** | 修改配置文件的字段名/类型/结构、删除已有配置项 | 新增配置项（默认值兼容旧行为）、仅调整注释 | | **行为语义变更** | 修改已有功能的预期行为、删除功能、改变错误处理策略 | 新增功能（不影响已有行为）、修复 Bug（恢复预期行为） | | **依赖升级** | 框架/运行时大版本升级（如 Vue 2→3、Node 16→20）、peerDependencies 范围收窄 | 补丁版本升级、开发依赖升级 | | **数据结构变更** | 修改数据库 schema、修改 API 响应格式、修改缓存键结构 | 新增字段（客户端可忽略）、仅增加索引 | | **删除/重命名文件** | 删除或重命名被其他模块引用的文件、删除导出的符号 | 删除未使用的文件、内部重组不影响外部 | **决策规则**：只要以上任意一维度命中"属于破坏性变更"，就必须使用 `!` 格式。 **如果不确定**：偏向保守——标记为破坏性变更，并在 `BREAKING CHANGE:` 正文中说明"可能的影响范围"。 ### 感叹号位置（唯一正确格式） ```text type(scope)!: summary ``` - `!` 紧跟在 `)` 之后，冒号 `:` 之前 - `!` 与 `)` 之间**不留空格** - `!` 与 `:` 之间**不留空格** ### 错误示例 vs 正确示例 | 写法 | 状态 | 问题说明 | | :---------------------------------- | :--: | :----------------------------------------- | | `🦄 refactor!(scope): summary` | ❌ | 感叹号在 type 之后、scope 之前，不符合规范 | | `🦄 refactor(scope) !: summary` | ❌ | 感叹号与 `)` 之间有空格 | | `🦄 refactor(scope)! : summary` | ❌ | 感叹号与 `:` 之间有空格 | | `🦄 refactor(scope)!: summary` | ✅ | 正确——`!` 紧跟在 `)` 之后，无空格 | | `🦄 refactor!: summary`（无 scope） | ✅ | 无 scope 时 `!` 紧跟在 type 之后 | ### 完整破坏性变更提交模板 ```text type(scope)!: 简短描述破坏性变更 BREAKING CHANGE: 详细说明破坏性变更的内容、原因，以及用户需要如何迁移。 - 变更点 1 - 变更点 2 ``` ### 示例 ```text 🦄 refactor(api)!: 重构用户查询接口 BREAKING CHANGE: 函数签名从 `getUser(id)` 改为 `getUser({ id, includeDeleted? })`，需更新所有调用方。 ``` ## 提交类型（commit type）选择指南 > 本仓库在 `references/commit-types.ts`（随技能分发的快照）中定义了 18 个提交类型。 > 远程 GitHub raw 文件是权威来源，本地 `references/commit-types.ts` 作为离线 fallback。 ### 核心类型（高频使用） | type | emoji | 适用场景 | 注意 | | :--------- | :---- | :------------------------------------------------- | :--------------------------------------- | | `feat` | ✨ | 新增功能、新特性、新组件 | 有 `semver: minor`，CLI 用户可见的新能力 | | `fix` | 🐞 | 修复 Bug、修正异常行为 | 恢复预期行为，非新增功能 | | `refactor` | 🦄 | 代码重构——重写/重命名/拆分代码但**不改变外部行为** | 如果改变了行为 → 用 `feat` 或 `fix` | | `docs` | 📃 | 仅文档变更（README、JSDoc、注释、CHANGELOG） | 不包括源码注释——源码注释用 `chore` | | `test` | 🧪 | 新增/修改测试用例、测试配置 | 不包括测试工具链的升级 | | `style` | 🌈 | 代码格式化（缩进、分号、引号）、Lint 修复 | 不包括 CSS/UI 样式变更——那是 `feat` | ### 辅助类型（中频使用） | type | emoji | 适用场景 | 注意 | | :------- | :---- | :--------------------------------------------------------------------------- | :--------------------------------------------------------------- | | `config` | 🔧 | 配置文件新增/修改 | 仅限配置本身，不包括配置变更引起的代码改动 | | `build` | 🔨 | 构建系统变更（构建工具、打包配置、tsconfig） | 与 `config` 的边界：`build` 只用于"影响构建产物"的配置变更 | | `deps` | 📦 | 依赖包的新增/升级/移除 | 当依赖变更伴随代码调整时，代码部分另开提交 | | `chore` | 🐳 | **不属于以上任何类别的杂项**——如 `.gitignore`、`.editorconfig`、源码注释清理 | **兜底 type**——只有其他 type 都不匹配时才用 | | `ci` | 🐎 | CI/CD 配置文件变更（GitHub Actions、CI 脚本） | 不影响生产代码 | | `perf` | 🎈 | 性能优化 | 如果优化时重构了代码 → 用 `refactor`；优化且改变行为 → 用 `feat` | | `i18n` | 🌐 | 国际化翻译文本的新增/修改 | 不包括国际化基础设施——那算 `feat` 或 `config` | ### 特殊类型（低频使用） | type | emoji | 适用场景 | 注意 | | :---------- | :---- | :----------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | | `revert` | 🔙 | 仅用于 `git revert` 生成的提交 | 不要手动编写此 type，让 `git revert` 自动生成 | | `delete` | 🔪 | 删除已废弃的代码/文件/注释 | 删除可能被引用的东西 → 用破坏性变更 `!` | | `init` | 🎉 | 项目/模块/子包的初始化或重新初始化。如：新建 monorepo 子包、首次接入构建工具链、初始化文档站脚手架、为新目录建立基础结构和约定 | 适用于**从无到有**搭建基础设施的场景。不要用于已有项目的增量功能开发（那用 `feat`） | | `publish` | 📢 | 发布 npm 包新版本（CHANGELOG + version bump） | 仅限发布流程专用 | | `save-file` | 🤔 | **仅用于"临时保存进度，不构成有意义变更"** | 尽量避免，用有意义的 type 代替 | ### 边界类型判断流程 当不确定选哪个 type 时，按以下流程决策： ```plain 1. 这个变更是"新增"还是"修复"？ → 新增功能 → feat → 修 Bug → fix → 都不是 → 第 2 步 2. 变更是否影响用户可见行为？ → 是 → 回到第 1 步（用 feat 或 fix） → 否 → 第 3 步 3. 变更属于以下哪一类？ → 重构代码结构 → refactor → 改配置文件 → config → 改构建/打包 → build → 改文档/注释 → docs → 改测试 → test → 改 CI/CD → ci → 改依赖 → deps → 改翻译文本 → i18n → 性能优化 → perf → 格式化/Lint → style → 删除废弃文件 → delete → 版本发布（版本号同步 + CHANGELOG） → publish → 从零初始化项目/模块 → init → 都不匹配 → chore（兜底） ``` ### 类型选择禁忌 - ❌ **不要混淆 `style` 和 UI 样式**：`style` 只用于代码格式化（缩进、分号），不用于 CSS/UI 视觉效果 - ❌ **不要滥用 `chore`**：只有明确不属于其他任何 type 时才能用——`chore` 不是"我不知道用什么所以选这个" - ❌ **不要把不同类型混入一个提交**：如果改了代码又改了文档，拆成 `feat` + `docs` 两个提交 - ❌ **不要臆造不在 commit-types.ts 中的 type**：如果觉得现有 type 都不匹配，用最接近的那个，而不是发明新 type - ❌ **不要将版本发布用 `config` 代替 `publish`**：版本号同步 + CHANGELOG 更新 → 必须用 `📢 publish`，不能用 `🔧 config`。`config` 仅用于配置文件本身的修改（如新增配置项、调整配置结构），不用于"因为要发布所以改版本号"的操作 ## 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 ` | | MiniMax | 组织邮箱 | 6,703 (org followers) | `Co-authored-by: MiniMax ` | | MIMO | 组织邮箱 | 1,741 (org followers) | `Co-authored-by: MIMO ` | > **注意**：MiniMax 和 MIMO 使用的组织邮箱已在 GitHub 组织设置（`MiniMax-AI` / `XiaomiMiMo`）中公开，但可能无法在 GitHub 提交页显示模型图标（取决于 GitHub 域名验证与头像关联状态）。若各厂商后续提供官方 bot 账号或 `users.noreply.github.com` ID，再用其替换组织邮箱。 ### 无官方账号（禁止使用） 以下工具/模型目前没有经验证的官方 GitHub bot 账号或公司邮箱，**禁止使用任何冒名抢注账号**： - **AI CLI**：Codex CLI（属于 `openai` 组织）、Gemini CLI（属于 `google-gemini` 组织）均无专属 bot 账号 - **ZCode CLI**：由智谱 AI（`zai-org`）推出，无独立 GitHub bot 账号。智谱官方尚未建立任何可验证的 bot 账号（参见 [zai-org/GLM-5#75](https://github.com/zai-org/GLM-5/issues/75)，社区提议 `glm-bot` + `noreply@z.ai`，至今无官方回复） - **WorkBuddy（腾讯小龙虾）**：腾讯云 CodeBuddy 团队维护，代码托管在 `cnb.cool/CodeBuddy`，GitHub 无官方组织或 bot 账号 - **AI IDE**：VS Code、Trae、Codebuddy、Antigravity、Qoder、Kiro 均未确认官方 bot 账号 - **AI 模型**：OpenAI GPT 系列、Gemini 系列、GLM 系列（智谱）、Kimi 系列（月之暗面/MoonshotAI）均无官方归属 bot 账号 > 待各厂商官方提供可验证的 bot 账号或公司邮箱后再补充到此表中。 ### 已确认的假冒/冒名账号黑名单 [CRITICAL] 以下账号均已通过 GitHub API 验证为非官方账号，**严禁在 Co-authored-by 中使用**： | 冒充目标 | 假冒账号 | 判定依据简述 | | :----------------------------------------------- | :--------------------------- | :------------------------------------------ | | Claude Code | `anthropics-claude` | 不在 `anthropics` 组织；含加密货币诈骗项目 | | Gemini CLI | `google-gemini-cli` | 不在 `google-gemini` 组织；全是 fork 无原创 | | Codex CLI | `codex-cli` | 不属于 `openai` 组织；Codex 发布 5 天后抢注 | | VS Code | `vscode-triage-bot` | 是 Issue 分流机器人，非 VS Code 本体 | | GLM-5 | `zhipuch` | 普通个人用户，与智谱 AI 无关联 | | Trae | `Trae-AI-Admin` | 不属于任何组织；0 个公开仓库 | | Codebuddy | `CodeBuddy-Official-Account` | 不属于任何组织；无法确认为官方账号 | | 其他（Antigravity/Qoder/Kiro/MiniMax/Kimi/MIMO） | 各假冒账号 | 均不在对应组织中，0 或极少公开仓库 | > 完整黑名单（含 ID 和详细判定依据）参见 `references/co-authored-by-blacklist.md`。 ## 交付物 提供： - 最终的提交信息（包含 Emoji，按上下文选择中文或英文编写） - 每个提交的简短摘要（内容/原因） - 用于暂存/审查的命令（至少：`git diff --cached`，加上运行的任何测试） ## 参考文件 以下文件存放在本技能目录的 `references/` 下，按需查阅： | 文件 | 何时查阅 | | :---------------------------- | :--------------------------------------- | | `commit-types.ts` | emoji/type 映射的本地 fallback 数据源 | | `commit-message-template.md` | 提交信息写作模板与结构参考 | | `commit-splitting-example.md` | 拆分逻辑复杂、文件众多时需要详细拆分示例 | | `staging-priority.md` | 对暂存区处理逻辑有疑问时 | | `input-requirements.md` | 用户信息不足需要确认输入时 | | `co-authored-by-blacklist.md` | 发现未知 Co-authored-by 账号需验证时 | | `breaking-change-examples.md` | 编写复杂破坏性变更提交信息时 | | `command-reference.md` | PowerShell/POSIX 具体命令记不清时 |