支持 Commit Message Review（提交信息评审）

[hwbest]

背景与动机

Android 官方贡献指南在 Submit Patches - Commit your change
(https://source.android.com/docs/setup/contribute/submit-patches#commit-your-change) 中，明确引用了一篇关于如何写好 Git Commit Message 的博客作为规范：
▎ To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message
▎ (https://chris.beams.io/posts/git-commit/).

这篇文章提出了写好 commit message 的 7 条规则，其中前 6 条大多是格式规范（如标题不超过 50 字符、使用祈使语气、正文每行不超过 72字符等），但第 7 条是核心：
▎ Use the body to explain what and why vs. how

这条规则强调的是：commit message 的正文应该解释"做了什么"以及"为什么这么做"，而不是"怎么做的"。

正如文章所说：
▎ "A diff will tell you what changed, but only the commit message can properly tell you why."
▎
▎ （diff 能告诉你代码变了什么，但只有 commit message 能告诉你为什么变。）

现状

目前 ocr 在处理 commit 时，只是把 commit message 作为评审的 background 上下文 注入，而不是作为独立的评审对象：

// review_cmd.go
if opts.commit != "" && opts.background == "" {
if msg, err := getCommitMessage(cc.RepoDir, opts.commit); err == nil && msg != "" {
opts.background = msg // 仅作为上下文，不被 review
}
}

这意味着，即使开发者的 commit message 写得很差（比如没有解释动机、只有"fix bug"这样的标题），ocr 也不会对其进行任何质量检查。

脚本能检查什么，不能检查什么？

根据 chris.beams.io (https://chris.beams.io/posts/git-commit/) 的 7 条规则：

┌──────────────────────────────┬───────────────────────────┐
│ 规则 │ 能否用脚本检查 │
├──────────────────────────────┼───────────────────────────┤
│ 标题与正文用空行分开 │ ✅ 简单判断 │
├──────────────────────────────┼───────────────────────────┤
│ 标题不超过 50 字符 │ ✅ 计数即可 │
├──────────────────────────────┼───────────────────────────┤
│ 标题首字母大写 │ ✅ 正则判断 │
├──────────────────────────────┼───────────────────────────┤
│ 标题末尾不加句号 │ ✅ 正则判断 │
├──────────────────────────────┼───────────────────────────┤
│ 标题使用祈使语气 │ ⚠️ 部分可用正则，但有歧义 │
├──────────────────────────────┼───────────────────────────┤
│ 正文每行不超过 72 字符 │ ✅ 计数即可 │
├──────────────────────────────┼───────────────────────────┤
│ 正文解释"为什么"而非"怎么做" │ ❌ 需要理解和推理 │
└──────────────────────────────┴───────────────────────────┘

第 7 条是脚本无法覆盖的。 判断一段 commit message
是否充分解释了"为什么"，需要理解代码变更的动机、对比旧方案的缺陷、以及交代设计决策的背景——这正是 LLM 擅长的推理任务。

为什么这件事需要 LLM 来做？

文章里举了一个 Bitcoin 项目的真实例子，关于 serialize.h 的异常处理重构：

不好的写法（仅仅描述"怎么改"）：

▎ Changed exception handling in serialize.h. Refactored to throw specific exceptions.

好的写法（解释了"为什么改"）：

▎ Simplify serialize.h's exception handling
▎
▎ The exception classes didn't provide any info about what they were throwing at / why they were throwing it. Replace generic
▎ exceptions with specific ones, which allows us to catch them more precisely. Also prune unreachable routines and replace internal
▎ state juggling with direct throws.

好的 message 让读者不用读代码就能理解：旧的问题是什么、新方案解决了什么、为什么旧方案不好。
这种"解释动机和上下文"的能力，纯脚本无法判断。

再比如文章中提到的标题语气测试：

▎ 写完标题后，试着把它放进这个句子里：
▎ "If applied, this commit will [ your subject line here ]."
▎
▎ ❌ 不通顺："If applied, this commit will fixed bug with Y."
▎ ✅ 通顺："If applied, this commit will refactor subsystem X for readability."

这种语义层面是否"通顺"和"符合直觉"，脚本很难准确判断，但 LLM 可以。

期望的用法

希望 ocr 能支持对 commit message 本身的 review。review 时，应将 commit message 内容 和对应的 diff 内容 一起发给 LLM，让模型既能检查
message 本身的质量，也能 cross-reference 验证 message 是否准确描述了代码变更。

关于配置方式，这里提供几种可能的实现方向，供维护者参考：

---

方案 A：使用特殊 path 前缀（个人推荐，改动最小）

利用 path 字段本身承载"匹配目标"的语义，用特殊前缀标识非文件类对象，无需引入新字段：

{
"rules": [
{
"path": "@commit-message",
"rule": "rules/commit-message-review.md"
},
{
"path": "**/*.kt",
"rule": "rules/kotlin.md"
}
]
}

• @ 前缀明确表示这不是文件路径匹配，而是一个元数据对象
• 解析逻辑中优先判断前缀，再执行常规的 glob 匹配

好处：零 schema 变更，老配置完全兼容，新增功能几乎没有学习成本。

---

方案 B：在 rule.json entry 中增加 target 字段

{
"rules": [
{
"target": "commit-message",
"rule": "rules/commit-message-review.md"
},
{
"path": "**/*.kt",
"rule": "rules/kotlin.md"
}
]
}

• target: "file"（默认）→ 基于 path glob 匹配文件
• target: "commit-message" → 作用于 commit message

好处是语义更明确，但缺点是需要扩展 schema，增加配置复杂度。

---

方案 C：命令行新增 flag

适合临时/个人使用，不改动 rule.json：

ocr review --from HEAD^ --to HEAD --commit-message-rule ./rules/commit-msg.md

---

个人更倾向方案 A。现有 path 字段已经足够表达"匹配什么"这层语义，没必要为了类型区分再引入一个新字段。@commit-message
这种约定式前缀在保持配置最小化的同时，也能清晰传达意图。

推荐的规则内容示例

rules/commit-message-review.md 可以聚焦在脚本无法检查的推理类问题上：

Commit Message 评审要点

1. 标题应使用祈使语气

• 好的标题应该能填入这个句子："If applied, this commit will "
• ❌ 不合适："Fixed bug with Y" / "Changing behavior of X" / "Sweet new API methods."
• ✅ 合适："Refactor subsystem X for readability" / "Remove deprecated methods."

2. 正文必须解释"为什么"

• 不要只描述代码改动的 mechanics（diff 本身已经展示了这些）。
• 应该说明：改动的动机是什么？旧方案有什么问题？为什么选择这个方案而不是其他？
• ❌ 差的正文："Changed the synchronous DAO methods to suspend functions."
• ✅ 好的正文："Blocking IO in UserRepository was causing ANRs on the main thread. Switching to suspend functions allows callers to
  manage concurrency explicitly while keeping the data layer framework-agnostic."

3. 如果改动了现有逻辑，应解释旧方案的缺陷

• 特别是 refactor 或删除代码时，需要交代被替换逻辑的局限性。
• 示例："Variables were triggering unnecessary errors immediately. Rather than silencing the side effects, this change removes
  unreachable routines and replaces internal state juggling with direct throws."

一个具体的 Android 场景例子

假设开发者的 commit message 如下：

Update UserRepository to use coroutines

Changed the synchronous DAO methods to suspend functions.

如果用上述规则进行 LLM review（同时提供 diff content），应该给出类似这样的反馈：

▎ Commit Message Review 结果：
▎ 1. 标题语气和长度基本合规 ✅
▎ 2. 正文只描述了"怎么改"，没有解释"为什么改"。 建议补充：
▎ - 旧的同步调用是否导致了主线程阻塞（ANR）？
▎ - 为什么选择 suspend 函数而不是返回 Flow？对于简单的 CRUD 操作，suspend 是否是更合适的选择？
▎ - 这次改动对现有调用方有什么影响？

总结

Commit message 的质量直接影响代码的可维护性和团队协作效率。格式类的规范可以通过脚本 / linter
解决，但**语义质量（是否解释了动机、上下文和权衡）**必须由人或有推理能力的模型来判断。

这与 ocr 的核心定位高度契合。

需要特别说明的是：本文中引用 How to Write a Git Commit Message (https://chris.beams.io/posts/git-commit/) 只是为了举例说明 commit
message review 的价值和需求场景，并不意味着 ocr 应该内置这套规范。不同团队、不同项目对 commit message
的要求可能完全不同（有的团队遵循 Conventional Commits，有的看重 issue tracker 关联，有的要求中英文双语）。因此强烈建议：

• 不要硬编码任何 commit message 规则
• 开放配置入口，让用户通过自定义 .md 文件来定义自己团队的 commit message 评审标准，正如现有规则系统已经支持的其他语言/文件 review一样

希望维护者能考虑支持 commit message review 的功能。

感谢！

[lizhengfeng101]

@hwbest 感谢你的想法，我个人建议是如果要做这个功能的话，最好把commit msg 的评审和代码的评审区分开。主要是几个原因：

• 工作区模式下的评审是没有commit 概念的，其次 range 模式下可能存在大量 commit，这种情况下和代码本身的评审耦合在一起，以当前大模型注意力机制来讲，我觉得对效果的副作用可能会更大。
• 变相引导用户使用变基，这容易造成风险。
• 用户行为不一定希望它捆绑在代码评审上，如果通过复杂二级参数来控制，不如提供一个单独的能力，例如 review msg 之类的。

[hwbest]

@lizhengfeng101 感谢回复！仔细想了一下，完全同意您的观点——commit message review 和代码 review 耦合在一起确实会带来您提到的那些问题（工作区模式没有commit 概念、range 模式下大量 commit 与代码评审耦合会分散模型注意力、变相引导用户使用变基容易造成风险等），这个功能并不是 ocr核心路径上必须的。

目前我们内部已经有其他更轻量的方式可以解决这个问题，分享一下实际方案：

1. 格式类检查：交给脚本/Linter

• 用 Python 脚本检查标题长度、是否空行分隔、是否包含 issue ID 等硬性规范
• 这部分不需要 LLM，执行快、成本低、可放在 CI 中阻断不合规提交

2. 推理/语义类检查：独立调用 LLM，同时传入 commit message + 对应 diff content

• message 和 diff 一起给模型，才能验证 message 里的"为什么"是否准确解释了代码变更
• range 模式下逐个 commit 单独检查即可

3. 生成阶段就介入

• 我们在内部工具链里通过 slash command（如 /commit）让开发者在写代码时就生成符合团队规范的 commit message
• command 的 system prompt 里直接注入团队的私有规范（如必须解释 Why、关联 ticket 等）
• 一个小细节：生成 commit message 的模型和后面检查它的模型尽量不用同一个，避免"自己写自己判"的偏差

---

总结： 您的"独立能力优于隐性绑定"的判断是对的。这个QA可以先关闭了，我们内部通过轻量脚本 + LLM 分层处理即可，不再期望 ocr内置。

再次感谢！

[lizhengfeng101]

@lizhengfeng101 感谢回复！仔细想了一下，完全同意您的观点——commit message review 和代码 review 耦合在一起确实会带来您提到的那些问题（工作区模式没有commit 概念、range 模式下大量 commit 与代码评审耦合会分散模型注意力、变相引导用户使用变基容易造成风险等），这个功能并不是 ocr核心路径上必须的。

目前我们内部已经有其他更轻量的方式可以解决这个问题，分享一下实际方案：

1. 格式类检查：交给脚本/Linter

• 用 Python 脚本检查标题长度、是否空行分隔、是否包含 issue ID 等硬性规范

• 这部分不需要 LLM，执行快、成本低、可放在 CI 中阻断不合规提交

2. 推理/语义类检查：独立调用 LLM，同时传入 commit message + 对应 diff content

• message 和 diff 一起给模型，才能验证 message 里的"为什么"是否准确解释了代码变更

• range 模式下逐个 commit 单独检查即可

3. 生成阶段就介入

• 我们在内部工具链里通过 slash command（如 /commit）让开发者在写代码时就生成符合团队规范的 commit message

• command 的 system prompt 里直接注入团队的私有规范（如必须解释 Why、关联 ticket 等）

• 一个小细节：生成 commit message 的模型和后面检查它的模型尽量不用同一个，避免"自己写自己判"的偏差

---

总结： 您的"独立能力优于隐性绑定"的判断是对的。这个QA可以先关闭了，我们内部通过轻量脚本 + LLM 分层处理即可，不再期望 ocr内置。

再次感谢！

@hwbest 感谢理解， ocr 愿意内置类似的能力，只是不建议耦合，关于独立提供这个模块能力，具体的行为还需要讨论和设计，也欢迎您进一步交流