一、自动提交消息Hook的设计
在Git commit时自动生成符合规范的提交消息，统一团队的提交格式
提交消息Hook的核心设计理念是"自动化约定优于手动记忆"。在团队协作中，统一的提交格式不仅能提升代码评审效率，还能自动生成变更日志和版本发布说明。本Hook通过在Git工作流的关键节点插入自动处理逻辑，实现从"人写消息"到"AI辅助生成消息"的转变。
核心设计原则：
1. 非侵入式 —— Hook仅增强提交流程，不阻止正常开发操作
2. 可配置化 —— 团队可根据项目需求定制消息格式和规则
3. 渐进式采用 —— 支持从松散格式逐步过渡到严格规范
设计架构： 自动提交消息Hook由三个核心组件构成 —— diff分析器、消息生成器、格式校验器。diff分析器负责解析暂存区变更，消息生成器根据Conventional Commits规范构建提交消息，格式校验器确保最终消息符合项目要求。
二、Git diff自动获取和解析
获取当前暂存区（staged）的diff内容，分析变更的代码文件和类型，统计变更行数（新增/删除），检测新文件和删除文件
2.1 获取暂存区diff
Hook通过调用 git diff --cached 命令获取当前暂存区的变更内容。该命令仅返回已通过 git add 暂存的变更，不包含未跟踪或未暂存的修改，确保提交消息只反映即将提交的内容。
# 获取暂存区diff并解析
git diff --cached --stat # 获取文件级别的变更统计
git diff --cached # 获取完整的变更详情
git diff --cached --name-status # 仅获取文件名和变更类型
2.2 解析变更类型和范围
对diff输出进行逐行解析，提取以下关键信息：
- 新增文件：通过
diff --git a/dev/null b/ 匹配新文件
- 删除文件：通过
diff --git a/ b/dev/null 匹配被删除的文件
- 修改文件：非新增/删除的变更文件
- 行数统计：通过
@@ 块头信息和 +/新增行 -/删除行 前缀统计
- 文件扩展名：推断变更涉及的技术栈和模块
# diff解析示例输出
M src/components/Button.tsx (+15, -3)
A src/hooks/useAuth.ts (+120, -0)
D src/utils/legacy.js (+0, -45)
R100 src/old.ts → src/new.ts (rename, +0, -0)
变更总结: 4 files changed, 135 insertions(+), 48 deletions(-)
优化建议： 对于大型diff（超过500行），建议仅提取文件级变更摘要作为提交消息的上下文，避免将完整diff内容塞入提交消息。hook可增加文件大小检测阈值。
三、Conventional Commits生成Hook（after:tool/git_*）
识别变更类型：feat（新功能）/fix（修复）/refactor（重构）/docs（文档）/test（测试）/chore（杂项），自动推导Scope范围（影响的模块/组件），检测Breaking Change（API变更/配置变更），生成完整的提交消息
3.1 变更类型自动检测
基于解析后的diff内容，Hook通过启发式规则自动推断变更类型：
| 变更类型 |
检测规则 |
示例 |
feat |
新增功能模块、API接口、组件 |
新增文件包含路由或组件定义 |
fix |
修改逻辑判断、异常处理、Bug修复 |
变更包含条件判断或错误处理代码 |
refactor |
代码结构重组，无新增功能 |
大规模变更但不涉及新API |
docs |
仅变更md/文档类文件 |
变更文件均为 *.md 或文档目录 |
test |
仅变更测试文件 |
变更文件均在 __tests__ 或以 *.test.* 结尾 |
chore |
构建配置、依赖管理、CI/CD |
变更 package.json、配置类文件 |
3.2 Scope范围自动推导
Scope表示变更影响的模块或组件范围。Hook通过文件路径中的目录结构自动推导scope：
# 文件路径到scope的映射规则
src/components/Button.tsx → scope: components
src/hooks/useData.ts → scope: hooks
src/api/user.ts → scope: api
src/utils/format.ts → scope: utils
docs/installation.md → scope: docs
packages/core/src/index.ts → scope: core
3.3 Breaking Change检测
Breaking Change是影响向后兼容性的关键变更。Hook通过以下模式自动检测：
- API函数签名变更（参数删除或重命名）
- 配置文件格式或字段变更
- 数据库schema变更
- 移除公开接口或组件
- 环境变量或依赖的重大版本升级
Breaking Change标记： 一旦检测到Breaking Change，Hook会自动在提交消息中追加 BREAKING CHANGE: 脚注，并生成具体的变更影响说明。
3.4 完整提交消息生成示例
# Hook自动生成的提交消息示例
feat(api): 添加用户认证接口
- 实现JWT token签发和验证
- 添加refresh token机制
- 集成OAuth2.0第三方登录
Closes #123, #124
BREAKING CHANGE: 认证接口从 /v1/auth 迁移到 /v2/auth，
旧版token将在30天后停止服务
四、Commit Message校验Hook（before:tool/git_commit）
验证即将提交的消息是否符合Conventional Commits格式，不符合时给出修改建议，阻止不合规的提交，提供交互式修正提示
4.1 校验规则
在Git提交操作之前（before:tool/git_commit），Hook自动拦截并对提交消息进行格式校验。校验规则包括：
- 格式检查：消息是否符合
类型(scope): 描述 的基本格式
- 类型白名单：是否使用预定义的合法类型（feat/fix/refactor/docs/test/chore等）
- 描述长度：第一行不超过72个字符
- 空消息预防：不允许空的提交消息
- 脚注格式：如果包含BREAKING CHANGE，需提供具体说明
# 校验失败示例
$ git commit -m "fix bug"
# Hook拦截输出:
# [ERROR] 提交消息格式不符合Conventional Commits规范
# 期望格式: ():
# 建议: fix(core): 修复用户登录时的空指针异常
# 是否继续提交？(y/n/t=编辑):
4.2 交互式修正提示
当校验失败时，Hook提供多级交互选择：
- y —— 忽略警告，强制提交（用于特殊情况）
- n —— 取消本次提交
- t —— 调用交互式编辑器修改提交消息
实现技巧： 使用 prepare-commit-msg hook自动添加前缀信息，配合 commit-msg hook进行最终校验。前者负责生成，后者负责验证，职责分离。
五、Commit日志记录Hook（after:tool/git_commit）
记录每次提交的信息到日志，格式化的提交历史可视化，提交统计和趋势分析
5.1 提交日志记录机制
在每次提交成功后（after:tool/git_commit），Hook将本次提交的关键信息追加到项目日志文件（如 CHANGELOG.md 或 .git-commit-log）中。记录的信息包括：
- 提交哈希（commit hash）
- 提交时间和作者
- 提交消息全文
- 变更文件列表和统计
- 关联的Issue编号
5.2 格式化提交历史可视化
Hook自动维护一个结构化的提交日志文件，按版本或时间线组织，便于团队回顾和发布管理：
# 自动生成的CHANGELOG示例
## v2.1.0 (2026-05-08)
### Features
- feat(api): 添加用户认证接口 (#123)
- feat(ui): 新增暗黑模式支持 (#125)
### Bug Fixes
- fix(core): 修复并发请求时的竞态条件 (#120)
- fix(types): 修正TypeScript类型定义导出 (#119)
### Documentation
- docs(readme): 更新安装说明和FAQ
### Breaking Changes
- refactor(api): 重构路由结构，旧版/v1/* 路径已废弃
5.3 提交统计和趋势分析
基于累积的提交日志，Hook可以生成统计报表，帮助团队了解项目健康状况：
提交频率统计
按日/周/月统计提交次数，识别活跃期和瓶颈期
类型分布分析
feat/fix/refactor各类型占比，评估项目稳定性
模块变更热力图
各模块/组件的变更频率分析，发现热点模块
最佳实践总结：
1. 自动提交消息Hook应作为团队工程效率基础设施的一部分，纳入项目初始化模板
2. 推荐结合 commitlint + husky 实现本地校验，配合 CI/CD 流水线进行二次校验
3. 定期审查提交日志统计，及时发现工程过程中的异常（如大量fix类型提交表明代码质量需关注）
4. Hook配置应纳入版本管理，确保所有团队成员使用一致的规则