chinese-commitlisted

# 中文 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 字，