doocs/md 仓库的 AI Agent Git 提交规范：基于 Conventional Commits 的 git-commit Skill 实践指南
项目地址: https://gitcode.com/doocs/md 导读
本指南以 doocs/md 仓库中 .agents/skills/git-commit/SKILL.md 为核心，系统讲解 AI Agent（Claude Code、Cursor、OpenCode 等）在本仓库执行 git commit 时应遵循的规范化流程：从 diff 分析、提交类型判定、特性分支创建，到 Conventional Commits 消息生成与安全提交。读完本文，你将掌握在 doocs/md 这类多端（Web / VS Code / uTools / API / 核心渲染引擎）pnpm monorepo 中，产出语义清晰、类型正确、符合项目规范的提交消息的完整实操方法与底层约束。
一、Skill 机制与定位：Agent 如何发现并使用 git-commit
doocs/md 在 .agents/skills/ 目录下维护了一套可复用的 AI Agent 工作流（Skill），作为各 Agent 工具链的规范来源（canonical）。其中 git-commit Skill 专门负责"以 Conventional Commits 规范创建标准化、语义化的 git 提交"，触发场景包括用户要求"commit changes""create a git commit"或提及 /commit。
Skill 的能力清单（来自 SKILL.md 的 front-matter description 字段）包括：
- 自动识别类型与作用域——根据变更内容推断
type与scope； - 必要时自动创建特性分支——当前分支为
main/master时不直接提交； - 基于 diff 生成 Conventional Commit 消息；
- 支持交互式覆盖——可选地让用户指定 type/scope/description；
- 智能文件暂存——按逻辑分组暂存变更。
根据 AGENTS.md 的说明，这些 Skill 通过 git 符号链接暴露给 Claude Code（.claude/skills/<name>），在 Cursor 或 Claude Code 中可手动调用 /git-commit，OpenCode 则通过 skill 工具调用。这意味着本文描述的流程同时是人类开发者与各类 AI 编程助手共用的提交规范。
二、Conventional Commits 格式与提交类型
2.1 提交消息格式
SKILL.md 规定的标准格式如下：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
<type>：变更类型（必填）；[optional scope]：可选的影响范围（如feat(editor)）；<description>：一句话变更摘要（现在时、祈使语气、不超过 72 字符）；body与footer：可选，用于补充说明、关联 Issue（如Closes #123、Refs #456）。
该格式与 CONTRIBUTING.md 的"提交规范"一节完全一致，是项目提交信息的唯一权威约定。
2.2 提交类型对照表
SKILL.md 定义了 11 种标准提交类型，与 CONTRIBUTING.md 中的类型表一一对应：
| 类型 | 用途 |
|---|---|
feat | 新功能 |
fix | Bug 修复 |
docs | 仅文档变更 |
style | 格式化/风格（无逻辑变化） |
refactor | 代码重构（非新功能亦非修复） |
perf | 性能优化 |
test | 新增/更新测试 |
build | 构建系统或依赖变更 |
ci | CI/配置变更 |
chore | 维护/杂项 |
revert | 撤销某次提交 |
从仓库实际提交记录看（如 chore(deps): bump wrangler, vue, AWS SDK, and related packages (#1966)），项目主分支的提交消息严格遵循该格式，且带括号作用域（deps）与 PR 编号引用。
三、破坏性变更（Breaking Changes）的两种标注方式
当变更会破坏既有 API 或行为时，SKILL.md 给出两种标准标注法：
方式一：类型/作用域后加感叹号
feat!: remove deprecated endpoint
方式二：在 footer 中使用 BREAKING CHANGE:
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key behavior changed
两种方式都会被 Conventional Commits 规范识别为破坏性变更，在生成 changelog 与版本号（major bump）时发挥关键作用。doocs/md 的 CHANGELOG（CHANGELOG.md）正是基于这类提交语义维护的。
四、宿主 Shell 差异：不要假设运行环境是 Bash
SKILL.md 特别强调了一个 Agent 常踩的坑：不要假设宿主终端是 Bash。例如 Windows 上的 Cursor 使用 PowerShell，其中 &&、$(cat <<'EOF')、POSIX 的 [ -z ... ] 等语法会直接失败。
因此推荐策略是：
- 优先使用分离的 git 调用，而不是把命令用
&&串联成一行； - 若必须串联：PowerShell 使用
;（或分开调用），Bash/zsh 才使用&&； - 同一命令在 Bash 与 PowerShell 下写法不同时，文档会分别给出示例。
这一点在后续所有命令行示例中都有体现：git diff、git commit -m 这类单命令在任何 shell 下都安全；只有多行 body 的提交才需要区分 shell（详见下文第五节的命令对比）。
五、完整提交流程（Workflow）逐步拆解
5.1 第 1 步：分析 diff，判定类型与描述
首先检查暂存区与工作区状态，确定本次变更的内容：
# 若已有文件被暂存，查看暂存区 diff
git diff --staged
# 若未暂存任何文件，查看工作区 diff
git diff
# 同时确认整体状态
git status --porcelain
根据 diff 内容确定提交类型与一句简短描述（第 2 步分支命名需要用到描述）。
5.2 第 2 步：确保在特性分支上开发
规则：禁止直接在 main/master 分支上提交。提交前先检查当前分支：
git branch --show-current
若处于 main/master，必须先创建特性分支。分支命名规则遵循 CONTRIBUTING.md 中记录的前缀约定：feat/、fix/、docs/；其他提交类型则直接用 <type>/ 作为前缀：
| 提交类型 | 分支前缀 | 示例 |
|---|---|---|
feat | feat/ | feat/custom-shortcuts |
fix | fix/ | fix/upload-timeout |
docs | docs/ | docs/contributing-guide |
| 其他类型 | <type>/ | chore/add-create-pr-skill |
<kebab-case-description> 部分的约束：
- 全小写，单词用连字符分隔；
- 从提交描述派生（去掉 scope、冠词与标点）；
- 保持简短（2～5 个词），例如
add create pr skill→add-create-pr-skill。
# 示例：一个与"添加 create-pr skill"相关的 chore 提交
git checkout -b chore/add-create-pr-skill
若用户明确要求直接在默认分支上提交，Agent 必须先与用户确认再执行。
5.3 第 3 步：按逻辑暂存文件（如需要）
若尚未暂存，或希望按逻辑分组暂存变更：
# 暂存指定文件
git add path/to/file1 path/to/file2
# 按模式暂存
git add *.test.*
git add src/components/*
两个硬性约束：
- 禁止运行
git add -p——它是交互式命令，Agent 无法完成，必须使用显式路径暂存； - 绝不允许提交密钥（
.env、credentials.json、私钥等）。
5.4 第 4 步：生成提交消息
基于 diff 分析确定三要素：
- Type：这是什么类型的变更？
- Scope：影响哪个区域/模块？（如
editor、api、core、deps） - Description：一行变更摘要（现在时、祈使语气、< 72 字符）
5.5 第 5 步：执行提交
单行提交（任何 shell 通用）：
git commit -m "<type>[scope]: <description>"
多行提交（含 body/footer），需区分 shell：
# Bash / zsh 使用 heredoc
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>
<optional body>
<optional footer>
EOF
)"
# PowerShell 使用 here-string
git commit -m @"
<type>[scope]: <description>
<optional body>
<optional footer>
"@
提示：doocs/md 要求提交信息与 PR 标题一律使用英文（见 AGENTS.md 与 CONTRIBUTING.md），因此 description 部分不要写中文。
六、最佳实践与 Git 安全协议
6.1 提交消息最佳实践
- 每次提交只包含一个逻辑变更（原子提交）；
- 使用现在时：
add而非added； - 使用祈使语气：
fix bug而非fixes bug； - 引用 Issue：
Closes #123、Refs #456； - description 控制在 72 字符以内。
6.2 Git 安全协议（不可逾越的红线）
SKILL.md 对 Agent 的行为做了如下硬性约束：
- 绝不修改 git config；
- 未经用户明确要求，绝不执行破坏性命令（
--force、hard reset）； - 绝不跳过 hooks（
--no-verify），除非用户明确要求； - 绝不 force push 到 main/master；
- 若因 hooks 失败导致提交未完成，创建新的提交修复，而不是 amend。
这些约束与项目 CI/钩子机制紧密相关：根 package.json 配置了 simple-git-hooks 的 pre-commit 钩子，运行 npx lint-staged，而 lint-staged 对所有文件执行 eslint --fix。
七、项目专属规则：doocs/md 的提交约定落地
7.1 提交语言与 CI 检查
SKILL.md 的 "Project Notes" 一节专门给出了 doocs/md 的两条落地规则：
- 提交消息与 PR 标题必须使用英文（依据 AGENTS.md 与 CONTRIBUTING.md）；
- 分支命名遵循
feat/、fix/、docs/，其他类型用<type>/前缀；绝不在main/master上提交，先创建分支（第 2 步）。
7.2 Pre-commit 钩子的连带影响
项目通过 lint-staged 在 pre-commit 阶段对所有文件执行 eslint --fix（见根 package.json 的 simple-git-hooks 与 lint-staged 配置）。这带来一个实际工作流影响：
- 若 hook 自动修改了文件（格式化修复），不要 amend，而是修复后创建新提交；
- 因为提交消息和分支命名都要求英文，Agent 生成的描述应直接使用英文现在时祈使句，避免二次改写。
7.3 与 create-pr Skill 的衔接
git-commit 与同目录下的 .agents/skills/create-pr/SKILL.md 构成完整的"提交 → 开 PR"流水线：提交规范保证每个 commit 语义清晰，create-pr 则基于这些提交汇总 PR 内容，并依据 .github/pull_request_template.md 填写 Summary、Type of Change、Test Procedure 与 Checklist；只有 PR 真正修复了某个 Issue 时，才额外添加 ## Related Issue（如 Closes #123），且禁止使用 #XXXX 占位符。
八、速查清单：给 Agent 与开发者的最后检查表
提交前对照以下要点逐项确认：
- 已用
git diff --staged/git diff确认变更内容； - 不在
main/master上直接提交，分支名符合<type>/<kebab-case-description>； - 未暂存
.env、密钥等敏感文件； - 提交类型从
feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert中选择； - description 为英文、现在时、祈使语气、≤ 72 字符；
- 有破坏性变更时使用
!或BREAKING CHANGE:footer； - 未运行
--no-verify、未修改 git config、未对 main/master force push； - hook 失败时新建提交而非 amend。
将这张清单与 .agents/skills/git-commit/SKILL.md 结合使用，无论是由 AI Agent 自动执行，还是开发者手动提交，都能保证 doocs/md 的 git 历史保持干净、语义一致、可追溯。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
