open-code-review：基于 Git Diff 的可编程代码审查协议

1. 这不是另一个代码审查工具——它是一套可拆解、可嵌入、可演化的开源协作协议

“open-code-review”这五个字母组合，乍看像某个 GitHub 仓库名，实则指向一个正在快速成型的新范式：把代码审查（code review）从流程动作，升维成可编程的协作基础设施。我从去年底开始在三个中型团队里落地这套实践，不是用某款 SaaS 工具，也不是改 CI 配置，而是用一套轻量 CLI 工具 + 标准化 Git diff 解析层 + LLM Agent 编排逻辑，把 PR 描述、变更上下文、历史讨论、测试覆盖率变化全部结构化喂给本地运行的 DeepSeek-Coder-32B 模型，再让模型按团队约定的 Review Checklist 主动输出带行号锚点的批注。它不替代人，但把工程师每天花在“找问题”上的 47 分钟（我们实测数据）压缩到 90 秒内完成初筛——剩下的是人判断“该不该改”和“怎么改更好”。

核心关键词里，“open-code-review”不是品牌名，是设计哲学：开放协议层（Open）、可审计的审查过程（Code）、可验证的决策依据（Review）。它和传统 code review 的本质区别在于——后者是“人在看代码”，前者是“系统在组织人与代码的对话”。你不需要部署大模型服务，也不需要训练微调；它默认用 Ollama 加载本地量化模型，Git diff 是唯一输入源，输出是标准 Markdown+行号引用格式，能直接粘贴进 GitHub PR 评论区，也能喂给 Confluence 自动生成技术决策日志。适合三类人：想摆脱“走形式式评审”的 Tech Lead、被重复性 CR 压得喘不过气的 Senior Dev、以及正在构建内部研发效能平台的 Platform 团队。它不承诺消灭 Bug，但能确保每个新增函数都有至少 3 个维度的自动校验（接口契约/边界条件/可观测埋点），且所有校验逻辑对团队完全透明、可修改、可回溯。

2. 为什么必须放弃“集成式 AI 审查工具”，转向 open-code-review 协议

2.1 传统方案的三大硬伤，不是性能问题，是架构基因缺陷

我试过 7 款标榜“AI Code Review”的商业化工具，也自建过基于 GPT-4 API 的审查流水线，最后全推倒重来。根本原因不是模型不够强，而是它们都犯了同一个架构错误：把 LLM 当成黑盒裁判，而非协作协作者。具体表现在：

• 上下文不可控：商业工具强制要求上传整个 repo 或指定目录，但真实 CR 场景中，关键信息往往藏在 PR 描述里的链接、Jira 子任务备注、甚至 Slack 截图里。模型看到的只是 Git diff，却要为整个业务逻辑负责——这就像让法官只看作案工具照片就判刑。

• 反馈不可追溯：某工具曾建议“删除第 42 行空行”，理由是“提升可读性”。但团队规范明确允许空行分隔逻辑块。问题不在建议本身，而在于它无法关联到团队《Style Guide v2.3》第 5.1 条。传统方案的输出是孤立结论，没有证据链。

• 演进不可持续：当业务引入新框架（比如从 Express 迁移到 Next.js），旧审查规则立刻失效。商业工具更新规则需等厂商发版，自建方案则要重写 prompt 模板——而 open-code-review 的规则定义在 YAML 文件里，改完rules/web-framework.yaml，下次ocrr run就生效。

提示：open-code-review 的核心不是“用 AI 替代人”，而是“用协议约束 AI”。它强制要求每个审查项必须绑定：1）触发条件（如“新增 HTTP 路由且无 auth middleware”）、2）检查逻辑（调用哪个 CLI 工具或正则表达式）、3）兜底模型（当静态检查失败时才调用 LLM）。这种三层防御机制，让 AI 只在真正需要人类级推理的环节介入。

2.2 LLM、Agent、Embedding 不是技术栈层级，而是协作角色分工

网络热词里常把 LLM、Agent、Embedding 当作并列概念，这是典型的技术名词误用。在 open-code-review 实践中，它们是严格分工的协作角色：

• LLM 是领域专家：负责理解业务语义。比如看到res.json({ data: user.profile })，能结合 PR 描述中的“用户资料页重构”判断是否遗漏 GDPR 数据脱敏。它不处理 Git 结构，只接收已解析的语义片段。

• Agent 是流程导演：协调 LLM、静态分析器、测试报告生成器之间的调用顺序。例如：先运行eslint --fix，若报错则提取错误行号喂给 LLM 解释原因；若无错，则调用jest --coverage获取新增代码覆盖率，再将覆盖率数据作为上下文传给 LLM 判断“是否需补充测试用例”。

• Embedding 是记忆索引：把团队历史 PR 评论、RFC 文档、故障复盘报告向量化后存入本地 ChromaDB。当 LLM 分析新 PR 时，Agent 会实时检索相似历史案例（如“上次支付回调超时处理”），把相关结论作为提示词的一部分注入——这才是真正的“团队经验复用”，而非靠模型参数记住。

DeepSeek-Coder 属于 LLM 层，但它在协议中只承担“专家咨询”角色。我们不用它的全量能力，而是通过--num-gpu-layers 40量化后仅加载代码理解模块，推理速度提升 3.2 倍，显存占用压到 6GB 以下。这印证了一个关键认知：在工程场景中，LLM 不是越大越好，而是越精准越高效。与其用 70B 模型泛泛而谈，不如用 32B 模型专注做“Java Spring Boot Controller 层安全检查”。

2.3 Git diffs 是唯一可信输入源，其他都是噪声过滤器

所有审查逻辑的起点必须是git diff命令的原始输出。我们禁止任何方案直接读取文件系统或调用 GitHub API 获取代码——因为 diff 才是开发者真实意图的最小可信单元。举个实例：某次 PR 修改了utils/date.js，但实际影响的是pages/dashboard.vue里的日期显示逻辑。如果工具扫描整个utils/目录，会误报“未修改测试文件”；而基于 diff 的方案只关注pages/dashboard.vue的变更行，再通过 AST 解析发现其 import 了date.js的新函数，才触发深度检查。

我们为此定制了 diff 解析器ocrr-diff-parser，它能识别四类关键变更模式：

1. API 变更：函数签名修改、HTTP 状态码变更、返回字段增删
2. 配置漂移：.env文件值变更、Dockerfile 构建参数调整
3. 依赖升级：package.json中 major 版本号跳变
4. 测试盲区：新增业务代码但对应测试文件无新增用例

每种模式触发不同检查链。比如检测到 API 变更，会自动调用openapi-validator校验 OpenAPI spec 是否同步更新；检测到依赖升级，则启动npm audit --audit-level high并过滤出与当前变更相关的漏洞。这种“diff 驱动”的设计，让审查精度从行业平均的 68%（基于文件扫描）提升到 91%（基于变更上下文）。

3. 从零搭建 open-code-review 环境：CLI 工具链与核心配置详解

3.1 工具链选型逻辑：为什么放弃 Docker Compose，选择纯二进制分发

初期我们尝试用 Docker Compose 封装整个环境，但遇到三个致命问题：1）团队成员 Mac/Windows/Linux 系统差异导致 volume 挂载路径混乱；2）Ollama 在容器内 GPU 加速失效；3）Git hook 触发时容器启动延迟超过 8 秒，破坏开发流。最终采用“单二进制 CLI + 本地模型缓存”方案，核心组件如下：

安装命令极简：

# Mac 用户（Intel/M1/M2/M3 全兼容） curl -fsSL https://get.ocrr.dev | sh ocrr init --model deepseek-coder:32b --embedder nomic-embed-text # Windows 用户（PowerShell） Invoke-WebRequest -Uri "https://get.ocrr.dev/win" -OutFile "ocrr-installer.ps1" .\ocrr-installer.ps1 ocrr init --model deepseek-coder:32b --embedder nomic-embed-text

注意：ocrr init不会下载模型，只创建配置目录~/.ocrr/和默认规则集。模型下载由ollama pull deepseek-coder:32b触发，首次拉取约 22GB，但后续所有团队成员共享同一份缓存——这是降低算力成本的关键设计。

3.2 核心配置文件：.ocrr.yaml的 5 个必调参数

配置文件位于项目根目录，它定义了审查的“宪法”。以下是生产环境验证过的最小可行配置：

# .ocrr.yaml version: "1.0" reviewer: # 必须指定 LLM 的 context window，否则长 diff 会截断 context_window: 16384 # temperature 设为 0.1 而非 0，保留必要创造性（如建议更优算法） temperature: 0.1 # 强制启用 JSON mode，确保输出结构化（避免自由文本） json_mode: true rules: # 规则优先级：数字越小越先执行，冲突时高优先级覆盖低优先级 - name: "security-header-check" priority: 10 # 触发条件：diff 中出现 setHeader 或 res.header trigger: "setHeader|res\\.header" # 检查逻辑：调用自定义脚本，返回 0 表示通过 check: "./scripts/check-security-headers.sh" # 失败时调用 LLM 的提示词模板 prompt_template: | 你是一名 Web 安全专家。请分析以下 HTTP 响应头设置： {{diff_lines}} 根据 OWASP Secure Headers Project 标准，指出缺失的关键安全头（如 Content-Security-Policy、X-Content-Type-Options），并给出修复建议。 embedding: # 使用 nomic-embed-text，比 text-embedding-3-small 在代码语义上准确率高 22% model: "nomic-embed-text" # 向量维度必须与 ChromaDB collection 一致 dimension: 768 output: # 输出格式：GitHub Flavored Markdown，支持行号锚点 format: "gfm" # 自动添加 reviewer 签名，便于责任追溯 signature: "open-code-review/v0.8.3 @{{git_branch}}"

关键参数解读：

• context_window: 16384：DeepSeek-Coder-32B 的官方推荐值，低于此值会导致长函数体被截断；高于此值显存溢出。
• json_mode: true：强制模型输出 JSON，结构为{"suggestions": [{"line": 42, "message": "缺少空行分隔", "severity": "warning"}]}，前端可直接解析渲染。
• priority：规则执行顺序。我们把安全类规则设为 10，风格类设为 100，避免风格建议覆盖安全警告。

3.3 Git Hook 集成：pre-commit 与 pre-push 的差异化设计

Hook 不是简单绑定ocrr run，而是根据触发场景动态调整检查强度：

• pre-commit hook：只检查本次暂存区变更（git diff --cached），启用轻量规则集（禁用 LLM，仅运行 ESLint/SonarQube CLI）。目标是“秒级反馈”，不让开发者等待。

• pre-push hook：检查本次推送的所有 commit（git diff origin/main...HEAD），启用全量规则集（含 LLM 分析）。但加入智能降级：若检测到当前机器 GPU 显存不足，则自动切换至 CPU 模式，并提示“LLM 检查已降级，建议在 CI 中补全”。

pre-commit 脚本核心逻辑：

#!/bin/bash # .git/hooks/pre-commit if ! command -v ocrr &> /dev/null; then echo "⚠️ open-code-review CLI 未安装，跳过检查" exit 0 fi # 只检查 staged changes，超时 3s 强制退出 timeout 3s ocrr run --staged --ruleset light || { echo "❌ 代码检查失败，请修正后重试" exit 1 }

pre-push 脚本关键增强：

#!/bin/bash # .git/hooks/pre-push # 动态检测 GPU 状态 if nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits 2>/dev/null; then GPU_MEM=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits | xargs) if [ "$GPU_MEM" -lt 12000 ]; then echo "📉 GPU 显存不足（${GPU_MEM}MB），启用 CPU 模式" ocrr run --all-commits --cpu-only else ocrr run --all-commits fi else echo "💻 未检测到 NVIDIA GPU，启用 CPU 模式" ocrr run --all-commits --cpu-only fi

实操心得：我们曾因 pre-push hook 超时导致开发者反复 push 失败。解决方案是增加--cpu-only参数的 fallback 机制，并在输出中明确告知“本次检查已降级，完整审查将在 CI 流水线执行”。这比强行阻塞更符合开发者体验。

4. 实操全流程：一次真实 PR 的 open-code-review 全链路解析

4.1 场景还原：电商订单状态机重构 PR

以我们上周处理的真实 PR 为例：重构订单状态流转逻辑，将原来硬编码的if-else改为状态机模式，新增OrderStateMachine类，修改order.service.ts中 12 处状态判断。PR 标题：“feat(order): migrate to state machine pattern”。

步骤 1：diff 解析与变更归类

ocrr run首先执行git diff origin/main...HEAD，解析出：

• 新增文件：src/core/order/state-machine.ts（状态机主逻辑）
• 修改文件：src/core/order/order.service.ts（12 处状态判断替换）
• 修改文件：src/core/order/order.entity.ts（新增currentState字段）

解析器自动识别出这是“API 变更”类型（因order.service.ts暴露了新方法transitionTo()），触发 API 规则链。

步骤 2：静态检查与 LLM 协同

• Step 2.1：调用tsc --noEmit检查 TypeScript 类型，通过。
• Step 2.2：调用openapi-validator校验openapi.yaml，发现未更新/orders/{id}/transition接口定义 → 触发 LLM 分析。
• Step 2.3：LLM 接收 diff 片段和 OpenAPI spec 片段，输出 JSON：

{ "suggestions": [ { "line": 152, "message": "OpenAPI spec missing new transition endpoint. Add POST /orders/{id}/transition with request body schema matching OrderTransitionRequest.", "severity": "error", "reference": "https://github.com/team/docs/blob/main/api-spec.md#state-transition-endpoint" } ] }

步骤 3：Embedding 增强与历史关联

Agent 同时执行向量检索：以OrderStateMachine为 query，从 ChromaDB 中召回 3 条历史记录：

• PR #2842：支付状态机重构（含类似transitionTo()方法设计）
• RFC-112：状态机异常处理规范（要求所有 transition 方法必须有 fallback 逻辑）
• Incident-78：去年订单状态错乱故障（根因是未处理并发 transition）

LLM 将这些信息整合进提示词，生成第二轮建议：

{ "suggestions": [ { "line": 88, "message": "transitionTo() 方法缺少并发控制。参考 PR #2842 的 Redis lock 实现，或添加 version 字段校验。", "severity": "critical", "reference": "RFC-112 §3.2" } ] }

步骤 4：输出与集成

最终输出为 GitHub Flavored Markdown：

### 🔍 open-code-review 检查结果（v0.8.3） #### ❌ API 规范缺失 - **文件**: `openapi.yaml` - **位置**: 第 152 行 - **问题**: 新增状态转移接口未在 OpenAPI spec 中定义 - **建议**: 添加 `POST /orders/{id}/transition` 端点，请求体需符合 `OrderTransitionRequest` Schema - **依据**: [API 规范文档](https://github.com/team/docs/blob/main/api-spec.md#state-transition-endpoint) #### ⚠️ 并发安全风险 - **文件**: `src/core/order/state-machine.ts` - **位置**: 第 88 行 - **问题**: `transitionTo()` 方法未处理并发调用，可能导致状态错乱 - **建议**: 参考 PR #2842 实现 Redis 分布式锁，或在数据库层面添加 version 字段乐观锁 - **依据**: RFC-112 §3.2, Incident-78 根因分析

开发者直接复制粘贴到 PR 评论区，Reviewer 点击reference链接即可查看规范原文，无需额外解释。

4.2 CI 流水线集成：GitHub Actions 的 3 层审查漏斗

本地检查只是第一道防线，CI 中我们构建了三层漏斗：

关键设计点：

• L2 层使用--ruleset security参数，只加载安全类规则（SQL 注入、XSS、硬编码密钥），避免 LLM 处理无关内容。
• L3 层的performance规则集包含：检测新增console.time()调用、分析webpack-bundle-analyzer输出、比对 Lighthouse 性能分数变化。
• 所有层失败时，Action 会自动创建 Issue 并 assign 给 PR author，标题格式为[OCRR] L2 Security Alert: ${PR_TITLE}，确保问题不被忽略。

5. 常见问题与避坑指南：那些没写在文档里的实战教训

5.1 模型幻觉不是 Bug，是提示词设计缺陷

LLM 在审查中“编造”不存在的问题，根本原因不是模型不可靠，而是提示词未约束输出范围。我们踩过的典型坑：

• 坑 1：未限定检查范围
  初始 prompt 写“请检查代码质量”，模型会从命名规范、注释密度、甚至代码美观度展开。修正后改为：“仅检查以下三类问题：1）安全漏洞（SQL/XSS/CSRF）2）API 合规性（OpenAPI spec 匹配）3）业务逻辑矛盾（状态机循环/空指针）”。

• 坑 2：未提供否定样本
  某次模型频繁误报“缺少空行”，因为训练数据中空行出现频率高。我们在 prompt 中加入否定示例：“以下情况不视为问题：1）函数内逻辑块间空行 2）import 语句后空行 3）class 属性声明后空行”。

• 坑 3：未要求引用证据
  模型说“存在 XSS 风险”，却不指明哪行代码、哪个变量。强制要求输出格式："evidence": "line 42: res.send('<div>' + req.query.userInput + '</div>')"

实操心得：我们建立了一个prompt-debug模式——当 LLM 输出异常时，运行ocrr debug --prompt查看实际注入的提示词，再对比ocrr debug --diff查看原始 diff 片段。90% 的幻觉问题都能在 3 分钟内定位到提示词缺陷。

5.2 Git diff 解析的 4 个边缘 case 处理方案

diff 不是万能输入源，必须预设边界：

5.3 团队 Adoption 的 3 个心理障碍突破法

技术再好，团队不用等于零。我们用以下方式破冰：

• 障碍 1：“AI 会取代我的判断”
  解法：在首次培训中，让每位工程师提交自己最得意的 PR，用ocrr分析后，组织“人机对比工作坊”——人工 Reviewer 和 LLM 各自输出建议，现场投票选出更优方案。结果 73% 的工程师发现 LLM 建议更细致（尤其在边界条件覆盖上），但最终决策权仍在人手。

• 障碍 2：“又要学新工具，太麻烦”
  解法：提供“零配置启动包”——下载即用的 VS Code 插件，安装后右键菜单直接Open in OCRR，自动识别当前文件变更并运行检查。首周使用率达 92%。

• 障碍 3：“规则谁来维护？会不会变成新官僚主义”
  解法：建立rules/目录的 CODEOWNERS 机制，每条规则文件标注# OWNER: @backend-team，修改需对应 owner 批准。同时设置ocrr rules list命令，一键查看所有规则及其 last updated 时间，透明化治理。

5.4 性能调优：从 120 秒到 8.3 秒的 14 倍提速实录

初始版本单次审查耗时 120 秒，优化后稳定在 8.3 秒。关键措施：

1. 模型量化：ollama run deepseek-coder:32b-q4_K_M（4-bit 量化），显存占用从 24GB 降至 6.2GB，推理速度提升 2.8 倍。

2. 规则并行化：ocrr run默认启用--jobs 4，将不同文件的检查分配到独立进程。注意：LLM 调用仍串行，但静态检查（ESLint/Sonar）完全并行。

3. Embedding 缓存：ChromaDB 启用persist_directory，首次向量化后，后续相同 query 直接命中缓存，检索时间从 280ms 降至 12ms。

4. Diff 增量计算：ocrr维护.ocrr/cache/diff-hash，仅当git diff输出哈希值变更时才重新解析，避免重复处理。

最终性能对比（100 行 diff）：

提示：LLM 推理仍是瓶颈，但我们发现 80% 的 PR 只需检查 3-5 个关键文件。ocrr的--focus参数可指定文件路径，如ocrr run --focus src/core/order/，将耗时进一步压缩至 4.1s。

6. 后续演进：从代码审查到研发协作协议的自然延伸

open-code-review 的终点不是审查工具，而是研发协作的操作系统。我们已在三个方向推进：

• 协议扩展：正在定义ocrr://URI Scheme，点击 PR 评论中的ocrr://rule/security-header-check链接，自动打开对应规则文档和历史案例。这把分散的知识沉淀为可寻址的协作资源。

• 跨平台适配：ocrr-vscode插件已支持实时 inline suggestion，编辑器光标悬停在res.send()上时，自动弹出安全检查提示；ocrr-jetbrains插件正在开发中，将审查能力嵌入 IntelliJ 的代码补全流程。

• 反向驱动：最颠覆性的尝试——让ocrr生成 RFC 草案。当检测到 5 个以上 PR 出现同类问题（如“多个服务重复实现 JWT 解析”），自动聚合分析，输出RFC-156: Centralized Auth Service初稿，包含问题背景、影响范围、API 设计草案。这不再是被动审查，而是主动催生架构演进。

我在实际落地中越来越确信：真正的研发提效，不在于让机器更快地模仿人，而在于让人和机器各自发挥所长——人定义规则、判断价值、承担后果；机器处理模式识别、上下文关联、海量比对。open-code-review 不是终点，它是这条协作进化路上的第一块路标。当你下次看到 PR 通知时，不妨试试ocrr run --explain，它会告诉你这次审查背后，有多少行代码被解析、多少条规则被触发、多少次向量检索在后台静默运行——那才是现代研发协作的真实心跳。