名称: git-提交-消息描述: 通过分析 Git 差异自动生成 conventional commit 消息，并强制执行分级格式。分析暂存变更以生成遵循 Conventional Commits 规范的有意义的提交消息。

Git 提交消息生成器

通过分析 Git 差异自动生成 conventional commit 消息，并强制执行分级格式

目的

分析暂存的 Git 变更，并生成遵循分级 Conventional Commits 规范的简洁、有意义的提交消息。此技能检查文件修改、添加和删除，以推断变更的类型和范围，生成与变更重要性匹配的提交消息——从关键功能的详细文档到次要更新的简洁消息。

关键创新点：三级格式系统，平衡关键提交（如功能、修复、安全）的详尽性与常规变更（如文档、杂务、样式）的效率性。

技能触发时机

当 /commit-msg 命令被调用时
当从 commit-msg/prepare-commit-msg 钩子触发时（如已安装）
当用户请求提交消息建议时
当在创建提交前分析变更时

核心能力

1. 差异分析

解析 git diff --staged 输出
识别修改、添加和删除的文件
分析代码变更（添加、删除、修改）
检测跨多个文件的模式

2. 变更分类

根据变更确定提交类型：
- feat：新功能或功能
- fix：错误修复
- security：安全修复或加固
- refactor：代码重构，不改变行为
- docs：文档变更
- style：格式化、空格、代码样式
- test：添加或修改测试
- chore：构建过程、依赖项、工具
- perf：性能改进
- ci：CI/CD 配置变更
- build：构建系统变更
- revert：撤销之前的提交

3. 范围检测

从文件路径和模式推断范围：
- 目录名称（如 api、auth、ui）
- 文件名模式（如 *.test.js → tests）
- 框架约定（如 components/、services/）

4. 消息生成

格式：type(scope): description
强制执行层级限制：第 1 级摘要最多 50 字符；第 2/3 级摘要最多 72 字符（理想 50）
使用命令语气（如“添加”而非“已添加”）
关注“什么”和“为什么”，而非“如何”
提供 2-3 个替代建议

层级系统：智能格式强制执行

此技能使用三级格式系统，将消息详细程度与提交关键性匹配：

第 1 级：关键提交（feat、fix、perf、security）

要求：带影响陈述的详细文档

格式：

type(scope): 摘要行（最多 50 字符）

- 详细描述点 1
- 详细描述点 2
- 详细描述点 3

此变更[影响陈述，描述面向用户的益处或解决的风险]。

受影响文件/组件：
- path/to/file1
- path/to/file2

原因：功能、修复和性能变更直接影响用户，需要详尽文档以备将来参考和生成变更日志。

第 2 级：标准提交（refactor、test、build、ci）

要求：简要上下文和文件列表

格式：

type(scope): 摘要行（最多 72 字符）

简要解释变更内容和原因（1-2 句话）。

文件：path/to/file1, path/to/file2

原因：内部改进需要上下文以维护，但不需要详尽文档。

第 3 级：次要提交（docs、style、chore）

要求：摘要行，可选描述

格式：

type(scope): 摘要行（最多 72 字符）

[可选：如有帮助，添加额外上下文]

原因：文档和日常维护从差异中显而易见；冗长消息会增加噪音。

工作流程

1. 获取暂存变更（仅暂存，非工作树）：
   - git diff --staged --name-status
   - git diff --staged --stat
   - git diff --staged
2. 加载配置 → frameworks/shared-skills/skills/git-commit-message/config.yaml
3. 分析变更：
   - 统计修改/添加/删除的文件数
   - 使用分析模式识别主要变更类型
   - 从项目结构（config.yaml）检测范围
   - 根据提交类型确定层级（1/2/3）
   - 提取关键修改
4. 生成提交消息：
   - 应用层级适当的格式
   - 主要建议（最佳匹配）
   - 替代建议 1（不同范围/角度）
   - 替代建议 2（更广/更窄焦点）
5. 根据规则验证：
   - 检查禁止模式
   - 验证必需元素是否存在
   - 确保长度限制
6. 向用户展示，附带解释和层级信息

可选模式（如调用者支持）

--validate "<message>"：验证提交消息而不生成建议（检查格式/类型/范围/长度/禁止模式；然后报告缺失的第 1/2/3 级必需元素）。
--tier <1|2|3>：强制层级格式（覆盖自动检测）。
--interactive 或 -i：在最终输出前确认类型、范围和摘要。

输出格式

[NOTE] 建议的提交消息（基于 X 文件变更）

主要：
feat(api): 添加用户认证端点

替代：
1. feat(auth): 实现 JWT 令牌验证
2. feat: 添加用户认证系统

分析：
- 在 src/api/ 中修改了 3 个文件
- 新函数：authenticateUser、generateToken
- 主要变更：新功能（认证）
- 检测到的范围：api/auth

Conventional Commits 快速参考

类型指南：

feat：面向用户的功能或 API 添加
fix：纠正错误行为
refactor：改进代码而不改变行为
docs：README、注释、文档文件
style：仅格式化（prettier、eslint --fix）
test：测试文件或测试工具
chore：构建脚本、包更新、配置
perf：可测量的性能改进
ci：GitHub Actions、CircleCI、构建流水线

范围指南：

使用小写
具体但不局限于
匹配项目模块结构
如果变更涉及多个不相关领域，则省略

描述指南：

以动词小写开头
结尾不加句号
具体且简洁
对于 feat 和 fix，关注用户影响

边界情况

多个不相关变更：

建议分成多个提交
如强制合并，使用更广范围或省略范围

破坏性变更：

在类型/范围后添加感叹号（示例：feat(api)!: 更改认证流程）
在正文中包含 BREAKING CHANGE（由用户处理）

WIP 或实验性：

使用 chore(wip): 描述 或 feat(experimental): 描述

无有意义变更：

检测并警告：“未检测到暂存变更”
建议 git add 命令

集成点

预提交钩子：提交前触发（如已安装/配置） 斜杠命令：通过 /commit-msg 手动调用 直接技能调用：从其他技能或工具调用

最佳实践

分析上下文：查看文件路径、函数名、导入语句
优先清晰：优先使用明显描述而非巧妙表述
遵守约定：如果检测到项目现有提交模式，则遵循
避免臆测：仅描述差异中实际内容
保持简洁：首行 50 字符理想，72 字符最大

示例分析

场景 1：新 React 组件

文件：src/components/UserProfile.tsx, src/components/UserProfile.test.tsx
变更：+120 行，组件定义、props 接口、测试
消息：feat(components): 添加 UserProfile 组件

场景 2：API 中错误修复

文件：src/api/auth.ts
变更：-5 +8 行，修复令牌过期检查
消息：fix(auth): 更正令牌过期验证

场景 3：文档更新

文件：README.md, docs/api.md
变更：+45 行文档
消息：docs: 更新 API 文档和 README

场景 4：依赖项更新

文件：package.json, package-lock.json
变更：eslint、typescript 版本提升
消息：chore(deps): 更新 eslint 和 typescript

分析模式：智能类型检测

此技能使用模式匹配从差异中智能检测提交类型：

feat 检测

新文件创建（尤其在 src/、components/、api/ 中）
新函数/类导出（export function、export class）
新 API 路由（app.get、router.post 等）
新资产/技能（在 .claude/、custom-gpt/ 等中）
阈值：通常 20+ 行添加表示功能

fix 检测

测试文件变更（常表示错误重现）
新条件语句（验证修复）
错误处理添加（try、catch、throw）
输入验证（validate、sanitize、check）
提交消息提示：如“bug”、“issue”、“error”、“crash”等词

refactor 检测

平衡变更（添加和删除相似）
函数重命名/移动（相同逻辑，不同位置）
无新功能或修复
测试覆盖率不变
关键词：“extract”、“move”、“rename”、“reorganize”

docs 检测

文件模式：.md、.txt、README、CHANGELOG、/docs/
纯文档变更（无代码修改）
混合代码+文档：优先代码类型，在描述中注明文档

test 检测

文件模式：test.js、spec.ts、__tests__/、/tests/
测试框架模式：describe、it、test、expect、assert

style 检测

CSS/样式文件：.css、.scss、.sass、.less
格式化器配置：prettier、eslint
仅空格变更
关键词：“formatting”、“indent”、“whitespace”

chore 检测

依赖文件：package.json、requirements.txt、Gemfile
锁定文件：package-lock.json、yarn.lock
配置文件：.gitignore、.env
关键词：“dependency”、“deps”、“upgrade”、“bump”

配置

项目特定配置从 config.yaml 加载：

范围映射：将目录模式映射到范围名称（如 frameworks/claude-code-kit/** → claude-kit）
层级规则：定义哪些提交类型需要哪些层级格式
禁止模式：阻止通用消息或助手/工具归属的提交
分析模式：为您的代码库自定义类型检测逻辑
验证模式：strict（阻止）、warning（警告）或 disabled（禁用）

禁止模式（验证）

此技能自动阻止包含这些模式的提交：

通用/模糊消息

[FAIL] “更新文件” → [OK] “docs: 更新 API 参考”
[FAIL] “修复内容” → [OK] “fix(auth): 更正令牌验证”
[FAIL] “更改代码” → [OK] “refactor(utils): 简化日期格式化”

助手/工具归属（按仓库策略）

[FAIL] “由 Claude Code 生成”
[FAIL] “Co-Authored-By: Claude noreply@anthropic.com”
[FAIL] 提交消息中任何助手/工具归属

进行中标记

[WARNING] “WIP: 功能”（警告 - 合并前应压缩）
[WARNING] “temp: 快速修复”（警告 - 应压缩）

缺失类型

[FAIL] 无类型前缀的提交（feat、fix、docs 等）

错误处理

无暂存变更：运行 git status 并指导用户使用 git add 文件
仅二进制文件：注意提交消息应提及文件类型
合并冲突：检测并建议 chore: 解决合并冲突
Git 不可用：优雅失败，附带有用错误消息
检测到禁止模式：显示错误并示例，阻止提交（严格模式）
缺失必需元素：根据层级要求列出缺失项
长度超出：显示字符数并建议缩短

与仓库集成

此技能与 AI-Agents 仓库标准集成：

CLAUDE.md 参考：提交前强制使用此技能
config.yaml：项目特定范围映射和规则
预提交钩子：Git 提交前自动触发
CONTRIBUTING.md：贡献者提交指南

提交消息模板

assets/template-commit-message.md — 复制粘贴模板和好/坏示例。

使用它来标准化 type(scope): summary 消息，并保持历史自动化友好。

安全敏感提交

assets/template-security-commits.md — 处理安全敏感变更的指南。

关键部分

预提交安全检查清单 — 秘密检测、禁止模式
安全相关提交类型 — 安全修复、增强、配置
意外秘密提交 — 立即响应、轮换、历史清理
敏感文件模式 — .gitignore 模板、永远不应提交的文件
审计追踪要求 — 安全提交的 CVE、CVSS、CWE 元数据

该做 / 避免

好的：该做

每次提交前运行秘密扫描
如暴露，立即轮换秘密
为凭据使用环境变量
用 CVE/CVSS 文档化安全修复
认证变更要求安全团队审查
更新 .gitignore 以包含秘密模式

不好的：避免

“临时”提交秘密
在测试中使用硬编码凭据
在示例文件中存储真实凭据
假设删除的秘密安全
完成秘密扫描前提交
对安全修复使用通用提交消息

反模式

反模式	问题	修复
“稍后添加秘密”	秘密意外提交	从一开始使用环境变量
测试中秘密	仓库中真实凭据	使用模拟/测试凭据
强制推送以隐藏	历史仍可恢复	轮换 + 文档化
模糊安全提交	无审计追踪	包含 CVE/CVSS
无预提交扫描	秘密触及远程	安装 gitleaks 钩子

可选：AI/自动化

注意：AI 建议应保留人类意图。

提交消息建议 — 从差异分析草稿
类型检测 — 基于模式的提交类型推断
范围检测 — 从更改路径自动检测

有限声明

AI 生成消息需人工审查和修改
自动化类型检测可能缺失上下文
安全提交始终需人类判断

版本：2.1.1 最后更新：2026-01-26 仓库：AI-Agents（文档仓库） Conventional Commits 规范：https://www.conventionalcommits.org/

名称: git-提交-消息 描述: 通过分析 Git 差异自动生成 conventional commit 消息，并强制执行分级格式。分析暂存变更以生成遵循 Conventional Commits 规范的有意义的提交消息。