中文 commit 规范

何时用

• 准备执行 git commit 前，需要撰写 commit message 时。
• 对已有 commit message 做 review 或修改时。
• 在 PR 描述中引用 commit 列表，需要判断某条消息是否清晰时。
• 给团队新成员讲解项目提交规范时。

核心规则

1. 格式 = type(scope): 中文主题

规则： type 必须用英文关键字（feat / fix / docs / refactor / test / chore / perf），冒号后的主题用中文，且不超过 50 个字。

为什么： AI 最常见的错误有两种：一是整行全写中文（新增功能：用户登录），导致 CI 的 commit-lint 规则直接报错；二是 type 用中文近义词（特性、修复）或随意缩写（f、upd），让 git log --oneline 的过滤脚本无法识别。格式不统一还会导致自动生成 CHANGELOG 时分类错误，把 bug 修复误放进"新功能"节。

怎么做：

• type 只从以下七个中选一个：feat（新功能）、fix（缺陷修复）、docs（文档）、refactor（重构，不改行为）、test（测试）、chore（构建/工具链）、perf（性能优化）。
• scope 写在圆括号内，可省略，但存在时必须用真实模块名（见规则 5）。
• 冒号后面跟一个空格，然后是中文主题，不加句号。

2. 主题写"做了什么"，用祈使句

规则： 主题用一句祈使句描述本次变更的核心动作，不写流水账，不写"修改了一些文件"之类的废话。

为什么： AI 极容易生成这种主题：更新了登录模块的相关代码——这句话在任何 commit 上都成立，完全没有信息量。另一类错误是记流水账：修改了 auth.py，删除了多余的注释，调整了变量名，顺便加了一个空行。主题不是 diff 摘要，是对"本次提交解决了什么问题"的一句话答案。读 git log --oneline 时，好的主题应当让人一眼知道"要不要点进这个 commit 看细节"。

怎么做：

• 问自己：「这个 commit 的目的是什么？」把答案压缩成一句话。
• 动词放句首，例如：修复、新增、删除、提取、替换、禁用。
• 不带末尾句号；不用被动句（不写"被修复了"）。
• 超过 50 字说明你在一次 commit 里做了多件事，应当拆分（见规则 4）。

3. 正文只在"为什么"不显然时写

规则： commit 正文（body）用来解释动机与权衡，而不是复述 diff 的内容。若改动理由一眼即明，正文可省略。

为什么： AI 倾向于把 diff 内容逐行翻译成正文，例如：将 token_expiry < now 改为 token_expiry <= now——这完全没有价值，读者直接看 diff 就能得到这个信息。真正有用的正文是：旧逻辑在 token 恰好等于当前时间时不视为过期，导致极少数请求绕过鉴权；改为 <= 后临界情况被正确拦截。 这类信息只存在于作者脑子里，不写下来就永久丢失。

怎么做：

• 主题行与正文之间空一行（git 规范要求）。
• 正文用自然段落，每行不超过 72 字，方便 git log 展示。
• 只写"为什么这样改"和"考虑过哪些替代方案、为何放弃"，不复述 diff。
• 如果有关联的 issue 或 PR，在正文末尾用 Closes #123 / Refs #456 标注。

4. 一次只提一件事

规则： 一个 commit 只做一件逻辑上内聚的事；功能、修复、格式整理混在一起时，必须拆成多个 commit。

为什么： AI 在帮用户完成任务时容易"顺手"把格式清理、变量重命名、无关 bug 修复一并提交。这类混合 commit 带来三个具体问题：① git bisect 时无法精确定位引入 bug 的节点；② cherry-pick 到其他分支时会带入不需要的副作用；③ code review 时 reviewer 不知道应该关注功能正确性还是格式合规，两件事互相干扰。

怎么做：

• 在提交前用 git diff --staged 扫描暂存区：确认每一处修改都服务于同一个目的。
• 发现夹带了无关改动（例如顺手修了 typo），用 git add -p 把它们拆到单独的 commit。
• 格式化改动（chore: 统一缩进风格）单独提交，绝不与功能 commit 混在一起。

5. scope 用真实模块名

规则： scope 必须对应项目中真实存在的目录名、模块名或服务名；不编造模糊范围，不用 misc、various、global 之类的占位词。

为什么： AI 在不确定影响范围时会编造一个听起来合理的 scope，例如 fix(backend): …——但项目里根本没有叫 backend 的目录，实际改的是 api/auth 模块。这让基于 scope 过滤 CHANGELOG 的脚本输出混乱，也让后续维护者无法通过 git log --grep 快速锁定某模块的历史变更。

怎么做：

• 打开项目根目录，用真实的顶层目录名或模块名作为 scope，例如 auth、user、payment、db、cli。
• 若改动跨多个模块且无法归为某一个，省略 scope，不要编造一个"最近似"的假名。
• monorepo 中 scope 通常是包名，例如 @app/core，直接用包的短名：core。

正例 / 反例

第一组：主题无信息量 vs. 直击要害

# 反例 — 读者毫无所知，在任何 repo 的任何 commit 上都能贴
update code

# 反例 — 流水账，不说明做了什么，也不说明为什么
改了一堆东西，调整了登录页，还顺便修了一个 bug

# 正例 — 一眼知道改了哪个模块、解决了什么问题
fix(auth): 修复 token 过期判断用 < 导致临界失效

# 正例 — 新功能，主题完整交代了做什么、作用在哪里
feat(payment): 新增支付宝扫码支付入口

第二组：type 错误 vs. 准确选型

# 反例 — type 用中文，CI lint 直接挂
新增: 用户头像上传功能

# 反例 — type 含糊，无法区分功能还是修复
update(profile): 更新了头像上传的逻辑

# 正例 — type 精准，读者立即知道这是新功能
feat(profile): 支持上传 WebP 格式头像并自动压缩至 200 KB 以内

# 正例 — 重构不改行为，用 refactor 区分于 feat/fix
refactor(db): 将裸 SQL 查询提取为 Repository 层统一管理

第三组：带正文的完整 commit（解释 why）

fix(session): 修复并发登录时 session 互相覆盖的问题

旧实现使用用户 ID 作为 session key，同一账号在两台设备同时登录时，
后登录的设备会覆盖前一个设备的 session，导致前者被强制下线但无任何提示。

改为在 session key 中加入设备指纹（device_fingerprint），使每台设备
持有独立的 session。考虑过改用 JWT 无状态方案，但当前需要服务端主动
撤销能力，暂不切换。

Closes #412

自查清单

• type 是七个英文关键字之一：feat / fix / docs / refactor / test / chore / perf。
• 主题是中文祈使句，不超过 50 字，末尾没有句号。
• scope（若有）对应项目中真实存在的目录名或模块名，没有编造占位词。
• 本次 commit 只做一件逻辑内聚的事，格式改动和功能改动没有混在一起。
• 如果写了正文，正文解释的是"为什么"而不是逐行复述 diff 内容。
• 主题行与正文之间有且仅有一行空行（若有正文）。
• 关联的 issue 或 PR 已在正文末尾用 Closes #N / Refs #N 标注（若有）。