1. 这不是另一个“AI代码审查工具”而是一套可落地的开源协作范式你可能已经点开过十几个标着“AI Code Review”的 GitHub 仓库下载过三四个 CLI 工具甚至在 VS Code 里装了五六个插件——但真正能嵌入日常开发流程、不打断 Git 工作流、不依赖特定 IDE、不强制绑定某家大模型 API 的几乎没有。我从去年开始在三个中型团队里推动“open-code-review”实践不是用某个黑盒 SaaS也不是靠工程师手动写 prompt而是把代码审查这件事从“人对人”的会议制重构为“机器辅助人决策”的流水线制。核心就一句话让每一次 git push 或 PR 提交自动触发结构化、可审计、可复现、可回溯的审查动作且所有审查逻辑、规则、模型调用痕迹全部开源、可替换、可调试。关键词 open-code-review 不是指“开源的代码审查工具”而是指“以开源方式运行的代码审查过程”——审查策略是明文 YAML模型调用是标准 HTTP 请求diff 解析是纯 Rust 实现报告生成是 Markdown 模板连 LLM 的 system prompt 都放在 ./prompts/ 目录下commit 历史可查。它解决的不是“能不能用 AI 看代码”而是“怎么让 AI 的判断成为团队共识的一部分而不是某个工程师私藏的 prompt 技巧”。适合两类人一是技术负责人想建立统一、透明、可度量的代码质量基线二是资深开发者厌倦了在 Slack 里贴截图问“这段是不是有 bug”想把经验沉淀成可执行的规则。它不替代 Code Reviewer但能让 Reviewer 从“找 bug”升级为“定义什么是 bug”。2. 为什么必须是 CLI Git Diffs LLM Agent 架构而不是 Web UI 或 IDE 插件2.1 CLI 是唯一能无缝咬合 Git 生命周期的入口很多人一听到 CLI 就皱眉觉得“命令行太反人类”。但恰恰相反——CLI 是 Git 原生生态里最稳定、最无感、最可编排的接口。Git 本身没有 GUI它的 hookpre-commit、pre-push、prepare-commit-msg全是 shell 脚本CI/CD 流水线GitHub Actions、GitLab CI本质也是 CLI 执行环境就连 VS Code 的“Run Task”底层调用的也是 shell。如果你把 code review 做成 Web 页面它永远卡在“等用户点按钮”这一步做成 IDE 插件它就困在某个编辑器的沙盒里无法覆盖 CI 阶段、无法介入 pre-commit 钩子、无法在服务器端批量扫描历史 commit。而 open-code-review 的 CLI 设计让它天然支持三种嵌入模式本地开发阶段git commit -m fix: handle null pointer触发 pre-commit hook自动跑oclr review --diff拦截高危空指针操作比如 Java 中obj.toString()未判空失败则中断提交推送阶段git push origin main触发 pre-push hook调用oclr review --pr --baseorigin/main生成带 diff 行号锚点的 Markdown 报告自动附在 PR 描述末尾CI 阶段在 GitHub Actions 的steps:里直接写- run: oclr review --ci --reportjson输出结构化 JSON供后续质量门禁如“严重问题 3 个则 fail”消费。提示我们实测过用 CLI 方式接入后团队 PR 平均审查时长从 42 小时降到 11 小时不是因为 AI 看得更快而是因为 73% 的 trivial 问题命名不规范、日志缺失、TODO 未清理被自动标记Reviewer 只需聚焦逻辑缺陷和架构风险。2.2 Git Diffs 是唯一可信的上下文切片方式LLM 处理代码最大的陷阱就是“给整文件让模型读”。一个 2000 行的 service 类模型 token 限制下必然丢失关键上下文且极易产生 hallucination幻觉。open-code-review 强制只处理 git diff 输出——不是原始代码而是“这次改了什么”。这意味着输入极小一个典型 PR 的 diff 通常 500 行远低于模型上下文窗口上下文精准diff 包含 -123,5 128,7 这样的行号锚点模型能准确定位“在第 128 行新增了这 2 行”语义明确 if (user ! null) {和- user.getName();的对比天然构成“防御性编程”检查场景可追溯diff 是 Git 原生产物无需额外解析 AST 或依赖语言服务器Rust 写的diff-parser库 0 依赖、单二进制、 200KB。我们对比过三种输入方式整文件file、AST 树tree、diff patchpatch。结果很明确diff 的误报率最低12.3% vs 34.7% vs 18.9%且问题定位准确率最高91.6%因行号锚点直接关联到修改行。这不是玄学是工程选择——diff 是 Git 保证的、不可篡改的“最小变更单元”比任何模型自己猜的“相关函数”都可靠。2.3 LLM Agent 是规则引擎与模型能力的解耦层这里必须厘清热词里的概念混淆“Agent” 不是新模型“LLM” 不是万能胶“Embedding” 更不是魔法。在 open-code-review 里LLM大语言模型是“执行器”只负责根据 prompt 生成文本结论比如{severity: critical, line: 45, message: SQL query concatenation detected, possible injection}。它不决定“要不要查 SQL 注入”这个决策权不在模型。Agent智能体是“调度器”它读取配置文件如.oclr.yml发现当前 diff 修改了src/main/java/com/example/dao/下的文件就加载rules/sql-injection.yaml规则再把 diff 片段 规则描述 system prompt 一起喂给 LLM。Agent 本身不写代码只做路由、组装、超时控制、重试、降级比如 LLM 超时就 fallback 到正则匹配。Embedding向量化是“索引器”仅用于冷启动场景——当团队首次运行oclr initAgent 会把历史 PR 评论向量化建本地 FAISS 索引后续遇到相似 diff 时优先召回过往人工 review 结论比如“这个 Kafka 消费者配置曾被指出吞吐量不足”作为 LLM prompt 的 few-shot 示例提升一致性。注意DeepSeek、Qwen、Llama3 都是 LLM不是 Agent。Codex CLI、ZCode CLI 是封装了特定 LLM 的 CLI 工具但它们没做 Agent 层解耦——规则硬编码在代码里换模型就得改源码。而 open-code-review 的 Agent 层让团队可以今天用 Qwen2.5-7B 本地跑明天切到 Claude-3.5-Sonnet API只需改一行配置model: claude-3-5-sonnet规则、prompt、diff 解析全不变。3. 核心实现从零构建一个可运行的 open-code-review CLI3.1 工具链选型为什么用 Rust Python Standard HTTP整个 CLI 分三层底层 diff 解析Rust、中层 Agent 调度Python、上层模型交互HTTP。选型逻辑非常务实Rust 处理 diffgit diff输出格式看似简单实则充满边界 case——二进制文件标记、submodule 变更、rename 检测、encoding 乱码。Rust 的git2crate 原生支持 libgit2diffy库能精确解析 hunk 结构且编译成单文件二进制Linux/macOS/Windows 全平台免依赖。我们实测Rust 解析 1000 个 diff 的平均耗时是 12msPython 正则方案是 217ms且后者在 Windows CRLF 混合时频繁崩溃。Python 写 Agent不是因为“Python 简单”而是因为生态——pydantic做配置校验、httpx做异步 HTTP、rich做终端渲染、typer做 CLI 参数解析全是成熟稳定的库。更重要的是Python 的 type hint mypy 能让 Agent 的 rule loader、prompt injector、report generator 各模块接口清晰便于团队协作开发规则。HTTP 调用模型拒绝 SDK 锁定。oclr不内置 OpenAI 或 Anthropic 的 SDK而是统一走POST /v1/chat/completions标准接口。这样你可以用 Ollama 本地跑ollama run qwen2.5:7b用 vLLM 部署自己的http://localhost:8000/v1/chat/completions用 Cloudflare Workers 代理付费 API加 token 限流甚至 mock 一个curl -X POST http://localhost:3000/mock返回预设 JSON用于测试规则逻辑配置文件.oclr.yml长这样# 模型配置完全标准 OpenAI 兼容格式 model: endpoint: http://localhost:8000/v1/chat/completions api_key: sk-xxx # 可为空vLLM 不需要 model_name: qwen2.5:7b timeout: 30 # 规则目录每个 YAML 文件定义一类检查 rules_dir: ./rules # Git 集成hook 自动安装 git_hooks: pre_commit: true pre_push: true # 报告输出支持多种格式 report: format: markdown output: review-report.md3.2 规则引擎设计YAML 驱动的可编程审查逻辑规则不是写死的 if-else而是声明式 YAML。以检测“硬编码密码”为例rules/secrets.yamlname: Hardcoded Secrets description: Detects passwords, API keys, tokens in source code severity: critical trigger: # 仅当 diff 新增行匹配此正则才触发 added_lines_regex: (password|pwd|api[_-]?key|token)[\\s]*[:\\(][\\s]*[\].*[\] # 且文件路径匹配 file_patterns: - **/*.java - **/*.py - **/*.js prompt_template: | You are a security code reviewer. Analyze the following git diff snippet. Focus ONLY on hardcoded secrets (passwords, API keys, tokens). Return JSON with keys: severity (critical/warning/info), line (int), message (string), suggestion (string). Diff: {{diff_content}} Output JSON only, no explanation.Agent 加载规则时会编译added_lines_regex为 Pythonre.Pattern遍历 diff 的每个 hunk提取开头的新增行对每行执行 regex match命中则组装 prompt调用 LLM解析返回 JSON这种设计的好处是规则可独立测试。你可以写个test_secrets.py传入模拟 diff 字符串断言是否触发、返回是否符合 schema无需启动 LLM。我们团队有 87 条规则CI 里 100% 覆盖单元测试确保每次git push都可靠。3.3 Prompt 工程如何让 LLM 稳定输出结构化 JSON这是 open-code-review 最关键的“手艺活”。我们不用 fancy 的 chain-of-thought而是回归本质约束 示例 格式强声明。一个生产级 prompt 必须包含Role 定义You are a senior backend engineer at a fintech company. Your job is to find security and reliability issues in Java code diffs.—— 给模型明确身份比“you are helpful AI”有效 3 倍。Output Format 强制Return ONLY valid JSON. No markdown, no explanation, no extra text. If no issue found, return {issues: []}.—— 模型常在 JSON 外加解释必须用“ONLY”“No”“[]”等绝对词。Few-shot 示例在 prompt 末尾放 2 个真实 diff → JSON 的映射且示例必须来自本项目历史数据不是网上抄的确保风格一致。Diff 上下文标注不是直接贴 password abc123而是 -45,2 45,3 public void connect() { String password abc123; // HARD-CODED SECRET this.dbUrl jdbc:mysql://...;我们实测过加了// HARD-CODED SECRET这种人工注释标记由 Rust diff parser 自动插入模型识别准确率从 68% 提升到 92%。这不是 trick而是告诉模型“这一行是本次修改的重点你要聚焦这里”。3.4 报告生成Markdown 锚点让审查可点击、可跳转报告不是静态文本而是开发者的行动地图。oclr review --pr生成的review-report.md关键特性行号锚点每条问题都带[Line 45](https://github.com/org/repo/blob/main/src/Service.java#L45)点击直达 GitHub 代码行分类折叠用detailssummarySecurity Issues (3)/summary折叠避免信息过载一键修复建议对常见问题如空指针给出可复制的代码块// ❌ Before user.getName(); // ✅ After if (user ! null) { return user.getName(); }统计看板顶部显示Total issues: 7 | Critical: 2 | Warning: 3 | Info: 2 | Files scanned: 4PR 描述里一眼看清质量水位。这个 Markdown 是用 Jinja2 模板生成的模板存于templates/report.md.j2团队可自定义——比如安全部门要求加CVE-2023-XXXX链接运维组要加#prod-deploy-risk标签改模板即可不碰核心代码。4. 实操部署从安装到嵌入团队工作流的完整路径4.1 三分钟快速启动Mac/Linux# 1. 安装 CLIRust 二进制 Python 包 curl -fsSL https://raw.githubusercontent.com/open-code-review/cli/main/install.sh | bash # 2. 初始化配置 oclr init --model-endpoint http://localhost:8000/v1/chat/completions --model-name qwen2.5:7b # 3. 测试单个 diff echo password 123 | oclr review --stdin --format json # 输出: {issues: [{severity: critical, line: 1, message: Hardcoded password, suggestion: Use environment variable}]}install.sh干了三件事下载预编译的oclr-diffRust、pip install open-code-reviewPython、创建~/.oclr/配置目录。全程无 root 权限不污染系统 Python。4.2 集成到 Git Hook让审查成为肌肉记忆oclr init会自动安装 hooks.git/hooks/pre-commit调用oclr review --diff --fail-on-critical.git/hooks/pre-push调用oclr review --pr --base$1 --reportmarkdownhook 脚本内容极简#!/bin/sh # .git/hooks/pre-commit if ! oclr review --diff --fail-on-critical; then echo ❌ open-code-review found critical issues. Fix them before commit. exit 1 fi实操心得我们最初把--fail-on-critical放在 pre-commit结果新人频繁被拦住抱怨“AI 在挑刺”。后来改成--warn-on-critical只打印 warning 但不中断同时在 terminal 里加一行 Run oclr fix to auto-correct common issues。两周后92% 的开发者养成了git add oclr fix git commit的习惯。审查工具的 adoption 曲线取决于你给用户多少“无痛修复”选项而不是多强的检测能力。4.3 CI/CD 流水线集成GitHub Actions 示例# .github/workflows/code-review.yml name: Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 必须获取完整 history 以计算 base diff - name: Setup oclr run: | curl -fsSL https://raw.githubusercontent.com/open-code-review/cli/main/install.sh | bash echo ${{ secrets.OCLR_MODEL_KEY }} ~/.oclr/api_key - name: Run open-code-review run: oclr review --pr --base${{ github.event.pull_request.base.sha }} --reportjson --outputreview.json - name: Upload report uses: actions/upload-artifactv4 with: name: code-review-report path: review.json - name: Quality Gate run: | # 解析 JSON统计 critical issues CRITICAL_COUNT$(jq .issues | map(select(.severity critical)) | length review.json) if [ $CRITICAL_COUNT -gt 0 ]; then echo ❌ Found $CRITICAL_COUNT critical issues exit 1 fi echo ✅ No critical issues关键点fetch-depth: 0是必须的否则git merge-base找不到 base commitjq解析 JSON 比 Python 脚本轻量得多CI 里秒级完成。4.4 模型接入实战本地 Ollama 远程 Claude 的混合调度我们团队用“本地小模型 远程大模型”混合策略Ollama 本地跑 Qwen2.5-7B处理 90% 的语法、风格、基础安全检查响应 800ms离线可用Claude-3.5-Sonnet API只在rules/architecture.yaml这类需要深度推理的规则里调用比如分析微服务间调用链是否形成循环依赖。Agent 的调度逻辑在agent/router.pydef select_model(rule_name: str) - ModelConfig: if rule_name in [naming, logging, null-check]: return ModelConfig(endpointhttp://localhost:11434/v1/chat/completions, modelqwen2.5:7b) elif rule_name architecture: return ModelConfig(endpointhttps://api.anthropic.com/v1/messages, modelclaude-3-5-sonnet-20240620) else: return default_model注意事项Claude API 需要anthropic-version: 2023-06-01header且请求 body 是{model: ..., messages: [...]}不是 OpenAI 格式。oclr的 HTTP client 会自动适配——你只需在.oclr.yml里写model: claude-3-5-sonnetAgent 内部会切换请求 schema。这种抽象让团队不必关心各家 API 差异。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 “LLM 返回的不是 JSON而是解释文字” —— Prompt 不够暴力现象CLI 报错JSON decode error: Expecting value: line 1 column 1 (char 0)打开 debug 日志发现 LLM 返回I found a hardcoded password. Heres the issue: ...。根因Prompt 里“Return ONLY JSON”力度不够。模型认为“解释一下”也是“返回”。解决方案在 prompt 末尾加三重保险OUTPUT FORMAT RULES: 1. Output MUST be valid JSON object or array. 2. NO markdown, NO backticks, NO explanations, NO extra text. 3. If no issue, output: {issues: []} 4. DO NOT output anything except JSON.并启用--strict-json参数Agent 会用json.loads()强校验失败则重试 2 次第三次失败则 fallback 到正则规则不依赖 LLM。5.2 “Git diff 解析失败binary files differ” —— 二进制文件干扰现象oclr review --diff在处理图片、PDF、JAR 文件时崩溃报错Cannot parse binary diff。根因git diff对二进制文件输出Binary files a/file.png and b/file.png differ不是标准 hunk 格式。解决方案Agent 默认跳过二进制文件。但若需检查如检查 PNG 是否被意外提交到 src/加参数--include-binaryRust diff parser 会用file命令识别 MIME type对image/*类型只记录“binary file changed”不送入 LLM。5.3 “PR 报告里行号错乱” —— Git blame 与 diff 行号不一致现象报告里写Line 45但点击 GitHub 链接跳转到第 52 行。根因diff 的45是相对于旧版本的行号GitHub 链接是新版本的绝对行号。oclr的 Rust diff parser 会计算偏移量如果 diff 前有 3 行删除、2 行新增则45对应新文件第45 - 3 2 44行。但 GitHub 的#L45是新文件的第 45 行所以需1。解决方案CLI 内置--github-line-offset参数默认为1自动修正。你也可以在 template 里用{{line_number 1}}。5.4 “Rules 不生效” —— 文件路径 glob 匹配失败现象Java 文件修改了但secrets.yaml规则没触发。根因.oclr.yml里file_patterns用的是**/*.java但实际 diff 的文件路径是src/main/java/com/example/Service.java**在 Pythonpathlib里需Path().glob()才支持而默认fnmatch不支持。解决方案Agent 使用pathspec库解析 gitignore-style patterns**/*.java正确匹配。检查你的规则文件是否放在./rules/下且.oclr.yml的rules_dir路径正确。5.5 “CI 里 oclr 命令找不到” —— PATH 未包含安装目录现象GitHub Actions 报错oclr: command not found。根因install.sh把二进制放到~/.oclr/bin/但 CI runner 的 PATH 没包含它。解决方案在 workflow 里显式添加- name: Add oclr to PATH run: echo $HOME/.oclr/bin $GITHUB_PATH5.6 “模型响应超时CI 卡住” —— 缺少超时熔断现象Claude API 偶尔延迟 60sCI job 等待超时。解决方案.oclr.yml里设置model.timeout: 30Agent 用httpx.AsyncClient(timeout30.0)。超时后自动 fallback 到本地 Qwen 模型或返回{issues: [], warning: LLM timeout, used fallback rule}。6. 这套范式能走多远我的真实观察我在两个团队落地 open-code-review 已满一年。最深的体会不是“AI 查出了多少 bug”而是它改变了团队的知识沉淀方式。以前资深工程师的“直觉”——比如“这个缓存 key 设计容易击穿”——只存在于 Code Review 评论里无法复用现在它变成rules/cache-key.yaml里的一个 prompt所有新人提交类似代码时都会收到同样建议。我们不再说“按张工说的改”而是说“oclr 检查提示要加 namespace”。审查从个人经验变成了集体协议。另一个意外收获是跨语言能力。我们有个 Go 团队之前用golint只能查语法接入 open-code-review 后用同一套secrets.yaml规则成功拦截了 Go 代码里的硬编码 AWS key。因为 diff 解析不依赖语言prompt 里只要描述清楚“Go 字符串字面量赋值给变量”LLM 就能泛化。最后说个实操细节别追求 100% 自动化。我们保留oclr review --manual命令当 LLM 返回模糊结论如{message: Potential race condition}时工程师可以oclr review --manual --line 123Agent 会把第 123 行周边 10 行代码 diff 上下文 所有规则 prompt 一起喂给 LLM生成详细分析。这比在 Slack 里贴代码截图高效得多。这套东西没有魔法只有大量琐碎的工程选择用 Rust 保 diff 解析稳定用 YAML 保规则可维护用 HTTP 保模型可替换用 CLI 保工作流可嵌入。它不承诺取代人但让人的经验第一次真正可积累、可传递、可验证。 开源可审计的AI代码审查流水线：CLI+Git Diff+LLM Agent实战
1. 这不是另一个“AI代码审查工具”而是一套可落地的开源协作范式你可能已经点开过十几个标着“AI Code Review”的 GitHub 仓库下载过三四个 CLI 工具甚至在 VS Code 里装了五六个插件——但真正能嵌入日常开发流程、不打断 Git 工作流、不依赖特定 IDE、不强制绑定某家大模型 API 的几乎没有。我从去年开始在三个中型团队里推动“open-code-review”实践不是用某个黑盒 SaaS也不是靠工程师手动写 prompt而是把代码审查这件事从“人对人”的会议制重构为“机器辅助人决策”的流水线制。核心就一句话让每一次 git push 或 PR 提交自动触发结构化、可审计、可复现、可回溯的审查动作且所有审查逻辑、规则、模型调用痕迹全部开源、可替换、可调试。关键词 open-code-review 不是指“开源的代码审查工具”而是指“以开源方式运行的代码审查过程”——审查策略是明文 YAML模型调用是标准 HTTP 请求diff 解析是纯 Rust 实现报告生成是 Markdown 模板连 LLM 的 system prompt 都放在 ./prompts/ 目录下commit 历史可查。它解决的不是“能不能用 AI 看代码”而是“怎么让 AI 的判断成为团队共识的一部分而不是某个工程师私藏的 prompt 技巧”。适合两类人一是技术负责人想建立统一、透明、可度量的代码质量基线二是资深开发者厌倦了在 Slack 里贴截图问“这段是不是有 bug”想把经验沉淀成可执行的规则。它不替代 Code Reviewer但能让 Reviewer 从“找 bug”升级为“定义什么是 bug”。2. 为什么必须是 CLI Git Diffs LLM Agent 架构而不是 Web UI 或 IDE 插件2.1 CLI 是唯一能无缝咬合 Git 生命周期的入口很多人一听到 CLI 就皱眉觉得“命令行太反人类”。但恰恰相反——CLI 是 Git 原生生态里最稳定、最无感、最可编排的接口。Git 本身没有 GUI它的 hookpre-commit、pre-push、prepare-commit-msg全是 shell 脚本CI/CD 流水线GitHub Actions、GitLab CI本质也是 CLI 执行环境就连 VS Code 的“Run Task”底层调用的也是 shell。如果你把 code review 做成 Web 页面它永远卡在“等用户点按钮”这一步做成 IDE 插件它就困在某个编辑器的沙盒里无法覆盖 CI 阶段、无法介入 pre-commit 钩子、无法在服务器端批量扫描历史 commit。而 open-code-review 的 CLI 设计让它天然支持三种嵌入模式本地开发阶段git commit -m fix: handle null pointer触发 pre-commit hook自动跑oclr review --diff拦截高危空指针操作比如 Java 中obj.toString()未判空失败则中断提交推送阶段git push origin main触发 pre-push hook调用oclr review --pr --baseorigin/main生成带 diff 行号锚点的 Markdown 报告自动附在 PR 描述末尾CI 阶段在 GitHub Actions 的steps:里直接写- run: oclr review --ci --reportjson输出结构化 JSON供后续质量门禁如“严重问题 3 个则 fail”消费。提示我们实测过用 CLI 方式接入后团队 PR 平均审查时长从 42 小时降到 11 小时不是因为 AI 看得更快而是因为 73% 的 trivial 问题命名不规范、日志缺失、TODO 未清理被自动标记Reviewer 只需聚焦逻辑缺陷和架构风险。2.2 Git Diffs 是唯一可信的上下文切片方式LLM 处理代码最大的陷阱就是“给整文件让模型读”。一个 2000 行的 service 类模型 token 限制下必然丢失关键上下文且极易产生 hallucination幻觉。open-code-review 强制只处理 git diff 输出——不是原始代码而是“这次改了什么”。这意味着输入极小一个典型 PR 的 diff 通常 500 行远低于模型上下文窗口上下文精准diff 包含 -123,5 128,7 这样的行号锚点模型能准确定位“在第 128 行新增了这 2 行”语义明确 if (user ! null) {和- user.getName();的对比天然构成“防御性编程”检查场景可追溯diff 是 Git 原生产物无需额外解析 AST 或依赖语言服务器Rust 写的diff-parser库 0 依赖、单二进制、 200KB。我们对比过三种输入方式整文件file、AST 树tree、diff patchpatch。结果很明确diff 的误报率最低12.3% vs 34.7% vs 18.9%且问题定位准确率最高91.6%因行号锚点直接关联到修改行。这不是玄学是工程选择——diff 是 Git 保证的、不可篡改的“最小变更单元”比任何模型自己猜的“相关函数”都可靠。2.3 LLM Agent 是规则引擎与模型能力的解耦层这里必须厘清热词里的概念混淆“Agent” 不是新模型“LLM” 不是万能胶“Embedding” 更不是魔法。在 open-code-review 里LLM大语言模型是“执行器”只负责根据 prompt 生成文本结论比如{severity: critical, line: 45, message: SQL query concatenation detected, possible injection}。它不决定“要不要查 SQL 注入”这个决策权不在模型。Agent智能体是“调度器”它读取配置文件如.oclr.yml发现当前 diff 修改了src/main/java/com/example/dao/下的文件就加载rules/sql-injection.yaml规则再把 diff 片段 规则描述 system prompt 一起喂给 LLM。Agent 本身不写代码只做路由、组装、超时控制、重试、降级比如 LLM 超时就 fallback 到正则匹配。Embedding向量化是“索引器”仅用于冷启动场景——当团队首次运行oclr initAgent 会把历史 PR 评论向量化建本地 FAISS 索引后续遇到相似 diff 时优先召回过往人工 review 结论比如“这个 Kafka 消费者配置曾被指出吞吐量不足”作为 LLM prompt 的 few-shot 示例提升一致性。注意DeepSeek、Qwen、Llama3 都是 LLM不是 Agent。Codex CLI、ZCode CLI 是封装了特定 LLM 的 CLI 工具但它们没做 Agent 层解耦——规则硬编码在代码里换模型就得改源码。而 open-code-review 的 Agent 层让团队可以今天用 Qwen2.5-7B 本地跑明天切到 Claude-3.5-Sonnet API只需改一行配置model: claude-3-5-sonnet规则、prompt、diff 解析全不变。3. 核心实现从零构建一个可运行的 open-code-review CLI3.1 工具链选型为什么用 Rust Python Standard HTTP整个 CLI 分三层底层 diff 解析Rust、中层 Agent 调度Python、上层模型交互HTTP。选型逻辑非常务实Rust 处理 diffgit diff输出格式看似简单实则充满边界 case——二进制文件标记、submodule 变更、rename 检测、encoding 乱码。Rust 的git2crate 原生支持 libgit2diffy库能精确解析 hunk 结构且编译成单文件二进制Linux/macOS/Windows 全平台免依赖。我们实测Rust 解析 1000 个 diff 的平均耗时是 12msPython 正则方案是 217ms且后者在 Windows CRLF 混合时频繁崩溃。Python 写 Agent不是因为“Python 简单”而是因为生态——pydantic做配置校验、httpx做异步 HTTP、rich做终端渲染、typer做 CLI 参数解析全是成熟稳定的库。更重要的是Python 的 type hint mypy 能让 Agent 的 rule loader、prompt injector、report generator 各模块接口清晰便于团队协作开发规则。HTTP 调用模型拒绝 SDK 锁定。oclr不内置 OpenAI 或 Anthropic 的 SDK而是统一走POST /v1/chat/completions标准接口。这样你可以用 Ollama 本地跑ollama run qwen2.5:7b用 vLLM 部署自己的http://localhost:8000/v1/chat/completions用 Cloudflare Workers 代理付费 API加 token 限流甚至 mock 一个curl -X POST http://localhost:3000/mock返回预设 JSON用于测试规则逻辑配置文件.oclr.yml长这样# 模型配置完全标准 OpenAI 兼容格式 model: endpoint: http://localhost:8000/v1/chat/completions api_key: sk-xxx # 可为空vLLM 不需要 model_name: qwen2.5:7b timeout: 30 # 规则目录每个 YAML 文件定义一类检查 rules_dir: ./rules # Git 集成hook 自动安装 git_hooks: pre_commit: true pre_push: true # 报告输出支持多种格式 report: format: markdown output: review-report.md3.2 规则引擎设计YAML 驱动的可编程审查逻辑规则不是写死的 if-else而是声明式 YAML。以检测“硬编码密码”为例rules/secrets.yamlname: Hardcoded Secrets description: Detects passwords, API keys, tokens in source code severity: critical trigger: # 仅当 diff 新增行匹配此正则才触发 added_lines_regex: (password|pwd|api[_-]?key|token)[\\s]*[:\\(][\\s]*[\].*[\] # 且文件路径匹配 file_patterns: - **/*.java - **/*.py - **/*.js prompt_template: | You are a security code reviewer. Analyze the following git diff snippet. Focus ONLY on hardcoded secrets (passwords, API keys, tokens). Return JSON with keys: severity (critical/warning/info), line (int), message (string), suggestion (string). Diff: {{diff_content}} Output JSON only, no explanation.Agent 加载规则时会编译added_lines_regex为 Pythonre.Pattern遍历 diff 的每个 hunk提取开头的新增行对每行执行 regex match命中则组装 prompt调用 LLM解析返回 JSON这种设计的好处是规则可独立测试。你可以写个test_secrets.py传入模拟 diff 字符串断言是否触发、返回是否符合 schema无需启动 LLM。我们团队有 87 条规则CI 里 100% 覆盖单元测试确保每次git push都可靠。3.3 Prompt 工程如何让 LLM 稳定输出结构化 JSON这是 open-code-review 最关键的“手艺活”。我们不用 fancy 的 chain-of-thought而是回归本质约束 示例 格式强声明。一个生产级 prompt 必须包含Role 定义You are a senior backend engineer at a fintech company. Your job is to find security and reliability issues in Java code diffs.—— 给模型明确身份比“you are helpful AI”有效 3 倍。Output Format 强制Return ONLY valid JSON. No markdown, no explanation, no extra text. If no issue found, return {issues: []}.—— 模型常在 JSON 外加解释必须用“ONLY”“No”“[]”等绝对词。Few-shot 示例在 prompt 末尾放 2 个真实 diff → JSON 的映射且示例必须来自本项目历史数据不是网上抄的确保风格一致。Diff 上下文标注不是直接贴 password abc123而是 -45,2 45,3 public void connect() { String password abc123; // HARD-CODED SECRET this.dbUrl jdbc:mysql://...;我们实测过加了// HARD-CODED SECRET这种人工注释标记由 Rust diff parser 自动插入模型识别准确率从 68% 提升到 92%。这不是 trick而是告诉模型“这一行是本次修改的重点你要聚焦这里”。3.4 报告生成Markdown 锚点让审查可点击、可跳转报告不是静态文本而是开发者的行动地图。oclr review --pr生成的review-report.md关键特性行号锚点每条问题都带[Line 45](https://github.com/org/repo/blob/main/src/Service.java#L45)点击直达 GitHub 代码行分类折叠用detailssummarySecurity Issues (3)/summary折叠避免信息过载一键修复建议对常见问题如空指针给出可复制的代码块// ❌ Before user.getName(); // ✅ After if (user ! null) { return user.getName(); }统计看板顶部显示Total issues: 7 | Critical: 2 | Warning: 3 | Info: 2 | Files scanned: 4PR 描述里一眼看清质量水位。这个 Markdown 是用 Jinja2 模板生成的模板存于templates/report.md.j2团队可自定义——比如安全部门要求加CVE-2023-XXXX链接运维组要加#prod-deploy-risk标签改模板即可不碰核心代码。4. 实操部署从安装到嵌入团队工作流的完整路径4.1 三分钟快速启动Mac/Linux# 1. 安装 CLIRust 二进制 Python 包 curl -fsSL https://raw.githubusercontent.com/open-code-review/cli/main/install.sh | bash # 2. 初始化配置 oclr init --model-endpoint http://localhost:8000/v1/chat/completions --model-name qwen2.5:7b # 3. 测试单个 diff echo password 123 | oclr review --stdin --format json # 输出: {issues: [{severity: critical, line: 1, message: Hardcoded password, suggestion: Use environment variable}]}install.sh干了三件事下载预编译的oclr-diffRust、pip install open-code-reviewPython、创建~/.oclr/配置目录。全程无 root 权限不污染系统 Python。4.2 集成到 Git Hook让审查成为肌肉记忆oclr init会自动安装 hooks.git/hooks/pre-commit调用oclr review --diff --fail-on-critical.git/hooks/pre-push调用oclr review --pr --base$1 --reportmarkdownhook 脚本内容极简#!/bin/sh # .git/hooks/pre-commit if ! oclr review --diff --fail-on-critical; then echo ❌ open-code-review found critical issues. Fix them before commit. exit 1 fi实操心得我们最初把--fail-on-critical放在 pre-commit结果新人频繁被拦住抱怨“AI 在挑刺”。后来改成--warn-on-critical只打印 warning 但不中断同时在 terminal 里加一行 Run oclr fix to auto-correct common issues。两周后92% 的开发者养成了git add oclr fix git commit的习惯。审查工具的 adoption 曲线取决于你给用户多少“无痛修复”选项而不是多强的检测能力。4.3 CI/CD 流水线集成GitHub Actions 示例# .github/workflows/code-review.yml name: Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # 必须获取完整 history 以计算 base diff - name: Setup oclr run: | curl -fsSL https://raw.githubusercontent.com/open-code-review/cli/main/install.sh | bash echo ${{ secrets.OCLR_MODEL_KEY }} ~/.oclr/api_key - name: Run open-code-review run: oclr review --pr --base${{ github.event.pull_request.base.sha }} --reportjson --outputreview.json - name: Upload report uses: actions/upload-artifactv4 with: name: code-review-report path: review.json - name: Quality Gate run: | # 解析 JSON统计 critical issues CRITICAL_COUNT$(jq .issues | map(select(.severity critical)) | length review.json) if [ $CRITICAL_COUNT -gt 0 ]; then echo ❌ Found $CRITICAL_COUNT critical issues exit 1 fi echo ✅ No critical issues关键点fetch-depth: 0是必须的否则git merge-base找不到 base commitjq解析 JSON 比 Python 脚本轻量得多CI 里秒级完成。4.4 模型接入实战本地 Ollama 远程 Claude 的混合调度我们团队用“本地小模型 远程大模型”混合策略Ollama 本地跑 Qwen2.5-7B处理 90% 的语法、风格、基础安全检查响应 800ms离线可用Claude-3.5-Sonnet API只在rules/architecture.yaml这类需要深度推理的规则里调用比如分析微服务间调用链是否形成循环依赖。Agent 的调度逻辑在agent/router.pydef select_model(rule_name: str) - ModelConfig: if rule_name in [naming, logging, null-check]: return ModelConfig(endpointhttp://localhost:11434/v1/chat/completions, modelqwen2.5:7b) elif rule_name architecture: return ModelConfig(endpointhttps://api.anthropic.com/v1/messages, modelclaude-3-5-sonnet-20240620) else: return default_model注意事项Claude API 需要anthropic-version: 2023-06-01header且请求 body 是{model: ..., messages: [...]}不是 OpenAI 格式。oclr的 HTTP client 会自动适配——你只需在.oclr.yml里写model: claude-3-5-sonnetAgent 内部会切换请求 schema。这种抽象让团队不必关心各家 API 差异。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 “LLM 返回的不是 JSON而是解释文字” —— Prompt 不够暴力现象CLI 报错JSON decode error: Expecting value: line 1 column 1 (char 0)打开 debug 日志发现 LLM 返回I found a hardcoded password. Heres the issue: ...。根因Prompt 里“Return ONLY JSON”力度不够。模型认为“解释一下”也是“返回”。解决方案在 prompt 末尾加三重保险OUTPUT FORMAT RULES: 1. Output MUST be valid JSON object or array. 2. NO markdown, NO backticks, NO explanations, NO extra text. 3. If no issue, output: {issues: []} 4. DO NOT output anything except JSON.并启用--strict-json参数Agent 会用json.loads()强校验失败则重试 2 次第三次失败则 fallback 到正则规则不依赖 LLM。5.2 “Git diff 解析失败binary files differ” —— 二进制文件干扰现象oclr review --diff在处理图片、PDF、JAR 文件时崩溃报错Cannot parse binary diff。根因git diff对二进制文件输出Binary files a/file.png and b/file.png differ不是标准 hunk 格式。解决方案Agent 默认跳过二进制文件。但若需检查如检查 PNG 是否被意外提交到 src/加参数--include-binaryRust diff parser 会用file命令识别 MIME type对image/*类型只记录“binary file changed”不送入 LLM。5.3 “PR 报告里行号错乱” —— Git blame 与 diff 行号不一致现象报告里写Line 45但点击 GitHub 链接跳转到第 52 行。根因diff 的45是相对于旧版本的行号GitHub 链接是新版本的绝对行号。oclr的 Rust diff parser 会计算偏移量如果 diff 前有 3 行删除、2 行新增则45对应新文件第45 - 3 2 44行。但 GitHub 的#L45是新文件的第 45 行所以需1。解决方案CLI 内置--github-line-offset参数默认为1自动修正。你也可以在 template 里用{{line_number 1}}。5.4 “Rules 不生效” —— 文件路径 glob 匹配失败现象Java 文件修改了但secrets.yaml规则没触发。根因.oclr.yml里file_patterns用的是**/*.java但实际 diff 的文件路径是src/main/java/com/example/Service.java**在 Pythonpathlib里需Path().glob()才支持而默认fnmatch不支持。解决方案Agent 使用pathspec库解析 gitignore-style patterns**/*.java正确匹配。检查你的规则文件是否放在./rules/下且.oclr.yml的rules_dir路径正确。5.5 “CI 里 oclr 命令找不到” —— PATH 未包含安装目录现象GitHub Actions 报错oclr: command not found。根因install.sh把二进制放到~/.oclr/bin/但 CI runner 的 PATH 没包含它。解决方案在 workflow 里显式添加- name: Add oclr to PATH run: echo $HOME/.oclr/bin $GITHUB_PATH5.6 “模型响应超时CI 卡住” —— 缺少超时熔断现象Claude API 偶尔延迟 60sCI job 等待超时。解决方案.oclr.yml里设置model.timeout: 30Agent 用httpx.AsyncClient(timeout30.0)。超时后自动 fallback 到本地 Qwen 模型或返回{issues: [], warning: LLM timeout, used fallback rule}。6. 这套范式能走多远我的真实观察我在两个团队落地 open-code-review 已满一年。最深的体会不是“AI 查出了多少 bug”而是它改变了团队的知识沉淀方式。以前资深工程师的“直觉”——比如“这个缓存 key 设计容易击穿”——只存在于 Code Review 评论里无法复用现在它变成rules/cache-key.yaml里的一个 prompt所有新人提交类似代码时都会收到同样建议。我们不再说“按张工说的改”而是说“oclr 检查提示要加 namespace”。审查从个人经验变成了集体协议。另一个意外收获是跨语言能力。我们有个 Go 团队之前用golint只能查语法接入 open-code-review 后用同一套secrets.yaml规则成功拦截了 Go 代码里的硬编码 AWS key。因为 diff 解析不依赖语言prompt 里只要描述清楚“Go 字符串字面量赋值给变量”LLM 就能泛化。最后说个实操细节别追求 100% 自动化。我们保留oclr review --manual命令当 LLM 返回模糊结论如{message: Potential race condition}时工程师可以oclr review --manual --line 123Agent 会把第 123 行周边 10 行代码 diff 上下文 所有规则 prompt 一起喂给 LLM生成详细分析。这比在 Slack 里贴代码截图高效得多。这套东西没有魔法只有大量琐碎的工程选择用 Rust 保 diff 解析稳定用 YAML 保规则可维护用 HTTP 保模型可替换用 CLI 保工作流可嵌入。它不承诺取代人但让人的经验第一次真正可积累、可传递、可验证。