AI 增强型 Commit 提交规范（团队版）
1. 规范目标
本规范用于统一团队在提交代码时对 AI 参与信息的记录方式，目标是：
- 标识代码中 AI 参与程度
- 为后续统计分析系统提供结构化数据
- 降低开发者填写 commit 的成本（通过插件自动生成）
2. Commit 格式
统一采用以下结构：
<type>(<scope>): [ai:<tag>] <subject>
<body>
<footer>
3. AI 标记规范（必填）
[ai:full] -> 80%+ 代码由 AI 生成
[ai:part] -> 30% ~ 80% AI 参与
[ai:review] -> AI 仅用于 review / 优化
[ai:none] -> 无 AI 参与
[ai:migrate] -> 迁移代码，项目初始化时
4. 标准示例（推荐写法）
feat(user): [ai:part] add login flow
- AI生成基础表单结构
- 手动调整校验逻辑
AI-Coauthored: true
AI-Ratio: 0.65
AI-Tool: cursor
5.1 AI-Coauthored
AI-Coauthored: true | false
true：存在 AI 参与（full / part / review）false：完全人工（ai:none）
5.2 AI-Ratio
AI-Ratio: 0.00 ~ 1.00
AI-Tool: cursor | copilot | claude | gpt | other
用于标识使用的 AI 工具来源。
6. Type 规范（沿用 Conventional Commits）
feat 新功能
fix Bug 修复
refactor 重构
perf 性能优化
style 样式调整
docs 文档
test 测试
build 构建
ci CI/CD
chore 杂项
revert 回滚
7. Scope 规范（建议填写）
示例：
(user) (auth) (workflow) (api) (table) (form)
8. Body 规范（建议自动生成）
建议描述 AI 的参与方式：
- AI生成：xxx
- 人工修改：xxx
- AI辅助：xxx
9. 插件配置
可以在 VS Code 的 settings.json 中自定义提交模板默认值：
{
"aiCommitTemplate.defaultAiTag": "part",
"aiCommitTemplate.defaultAiRatio": 0.5,
"aiCommitTemplate.defaultAiTool": "cursor",
"aiCommitTemplate.defaultAiGenerated": "根据 git diff 自动生成 commit 草稿",
"aiCommitTemplate.defaultManualEdited": "待补充",
"aiCommitTemplate.defaultAiAssisted": "提交结构和措辞建议"
}
配置说明：
aiCommitTemplate.defaultAiTag：默认 AI 标记，可选 full / part / review / none / migrateaiCommitTemplate.defaultAiRatio：默认 AI-Ratio，范围 0 ~ 1aiCommitTemplate.defaultAiTool：默认 AI 工具，可选 cursor / copilot / claude / gpt / otheraiCommitTemplate.defaultAiGenerated：默认 AI 生成内容描述aiCommitTemplate.defaultManualEdited：默认人工修改内容描述aiCommitTemplate.defaultAiAssisted：默认 AI 辅助内容描述
10. 发布到线上
发布到 VS Code Marketplace 的基础流程：
npm install
npm run build
npm run package
生成 .vsix 后可以先本地安装验证：
code --install-extension tsc-ai-commit-generator-0.0.1.vsix
首次发布需要准备 Marketplace 发布账号：
- 登录 Visual Studio Marketplace publisher 管理页，创建 publisher，名称需要和
package.json 中的 publisher 一致。
- 在 Azure DevOps 创建 Personal Access Token，至少勾选 Marketplace 发布相关权限。
- 登录
vsce：
npx vsce login <publisher>
- 发布：
npx vsce publish
如果只是给团队内部使用，也可以分发 npm run package 生成的 .vsix 文件，团队成员通过 VS Code 的 Extensions: Install from VSIX... 安装。
11. AI 判定规则（插件侧实现）
9.1 核心计算逻辑
aiRatio = aiGeneratedLines / totalChangedLines
9.2 标签分类规则
if (aiRatio > 0.8) -> ai:full
else if (aiRatio > 0.3) -> ai:part
else if (aiUsed) -> ai:review
else -> ai:none
ai:migrate
9.3 AI-Coauthored 推导
AI-Coauthored = aiTag !== 'none'
12. 统计系统解析规则
10.1 数据来源
git log --pretty=format:"%H|%an|%ad|%s|%b"
10.2 字段提取规则
- AI Tag：
/\[ai:(full|part|review|none)\]/
- AI-Ratio：
/AI-Ratio:\s*(\d+(\.\d+)?)/
- AI-Coauthored：
/AI-Coauthored:\s*(true|false)/
- AI-Tool：
/AI-Tool:\s*(\w+)/
10.3 标准数据结构
type CommitRecord = {
hash: string
author: string
date: string
type: string
scope: string
aiTag: 'full' | 'part' | 'review' | 'none'
aiRatio: number
aiTool: string
}
13. 统计指标（Web Dashboard）
11.1 个人维度
- 平均 AI-Ratio
- AI 使用率（
AI-Coauthored=true）
full / part / review 分布
11.2 仓库维度
- AI 参与趋势（时间序列）
- AI vs 非 AI 提交占比
11.3 高级指标（可选）
- AI 代码 Bug 率（结合
fix / revert）
- AI 使用与开发效率关系
14. 约束与校验（必须）
12.1 commitlint 规则
^\w+\(\w+\): \[ai:(full|part|review|none)\]
必须包含：
AI-Coauthored:AI-Ratio:AI-Tool:
12.3 Hook 兜底策略
在 commit-msg 阶段：
- 无
[ai:*] -> 自动补 [ai:none]
- 无 Footer -> 自动补默认值
15. 最佳实践（团队约定）
✅ 推荐
- 使用插件自动生成 commit
- 仅在必要时手动调整 AI 标签
- 保持 AI-Ratio 数值规范（
0~1，小数）
❌ 避免
- 手动随意填写比例
- 删除 Footer 字段
- 使用非标准 AI 标签
16. 总结
本规范的核心不是“记录 commit”，而是将 AI 参与开发过程结构化为可分析数据。
通过以下三类字段完成可追踪化：
[ai:*]：快速识别参与等级AI-Ratio：量化参与程度AI-Tool：追踪工具来源
最终支持：
- 团队 AI 使用情况分析
- 工具效果评估
- 开发效率与质量洞察
