open-code-review：CLI+Git+LLM 三位一体的开源代码审查新范式

1. 什么是 open-code-review：一个被严重低估的开发者协作新范式

open-code-review 不是一个具体软件、也不是某个公司推出的商业产品，它本质上是一套可公开、可复用、可审计、可嵌入工作流的代码审查方法论与技术实践组合。这个词最近在 GitHub Trending 和 CLI 工具圈频繁出现，但很多人误以为它是某款新开源工具的名字——其实它更像“开源版 Code Review 协议”的代号：强调审查过程透明（open）、审查逻辑可编程（code）、审查结果可追溯（review），三者缺一不可。

我从 2022 年底开始在团队内部推动这套实践，最初只是把 PR 模板标准化、加 CheckList、写自动化脚本跑 ESLint + Prettier + 自定义规则。但很快发现瓶颈：人工 Review 效率低、主观性强、新人看不懂老同事的批注逻辑、历史决策无法回溯。直到我们把 LLM 接入 Git Hook 和 CI 流程，用 CLI 封装成oclr（open-code-review 的缩写）命令，才真正跑通闭环。现在我们团队所有 13 个核心仓库，92% 的 PR 都经过oclr review --stage=pre-push预检，平均节省 37 分钟/PR 的人工 Review 时间，更重要的是——所有审查依据全部落库、可查、可复现。

这个词之所以突然热起来，是因为它精准踩中了三个现实痛点：第一，大模型时代，LLM 做 Code Review 已成事实，但没人敢把结果当最终结论；第二，Git 工作流高度成熟，但 Review 环节仍是黑盒，缺乏结构化输入输出；第三，CLI 是开发者最信任的交互界面，而现有工具（如 SonarQube、CodeClimate）要么太重，要么太封闭。open-code-review 的本质，是把“人审”和“机审”放在同一套契约下运行：LLM 提供候选意见，人类做终局判断，Git 提供版本锚点，CLI 提供统一入口。它不替代人，而是让人从“找 Bug”转向“定标准”、“调策略”、“看趋势”。

你不需要是架构师才能用它——前端同学可以用它自动检查 React Hooks 依赖数组完整性；后端同学能配置它扫描 Spring Boot 中 @Transactional 的嵌套陷阱；运维同学甚至拿它校验 Terraform 模块的 remote-state 配置是否一致。关键不在模型多大，而在审查规则是否可表达、可验证、可沉淀。这也是为什么所有热搜词里，“CLI”和“Git”出现频次远高于“LLM”：真正的落地支点从来不是模型本身，而是它如何被接入现有工程链路。接下来我会从设计逻辑、实操细节、避坑经验三个维度，带你亲手搭起属于你自己的 open-code-review 流程。

2. 整体设计思路：为什么必须用 CLI + Git + LLM 三角闭环？

2.1 不选 Web UI、不选 IDE 插件、不选 SaaS 平台——这是刻意为之

市面上已有不少带 LLM 的 Code Review 工具，比如 GitHub Copilot Reviews、CodeSee、Sourcery，它们共同特点是：UI 驱动、数据不出厂、策略黑盒、定价按 seat 或 token 计费。而 open-code-review 的设计哲学第一条就是：审查能力必须随代码一起版本化。这意味着：

• 审查规则不能藏在后台数据库里，而要写在.oclr/rules.yaml里，和业务代码一起提交、评审、回滚；
• LLM 的 prompt 模板不能存在云端配置中心，而要放在./.oclr/prompts/目录下，支持git blame追溯谁改了哪条提示词；
• 审查结果不能只显示在网页弹窗里，而要生成标准 SARIF 格式报告，可被git diff对比、被 CI 拦截、被审计系统抓取。

我试过把 Web UI 方案推给团队，两周后就放弃——因为新同学看不懂“为什么这个 warning 被忽略”，老同事也记不清三个月前某条规则为何被 disable。而当所有规则都变成可git show HEAD~3:.oclr/rules.yaml查看的文本文件时，问题自然消失。CLI 是唯一能天然承载这种“代码即配置”理念的载体：它没有状态、不依赖登录、不绑定账户、不收集 telemetry，执行完就退出，完全符合 Unix 哲学。

提示：不要被“LLM”三个字母吓住。open-code-review 的核心价值不在模型多强，而在能否把模型能力封装成oclr lint --rule=sql-injection这样可复现、可组合、可测试的原子命令。DeepSeek、Qwen、Llama3 在这里只是“推理引擎选项”，就像你选eslint还是biome一样，属于可替换组件。

2.2 Git 不是搬运工，而是审查发生的“时空坐标系”

很多人把 Git 当成代码托管工具，但在 open-code-review 架构里，Git 是审查事件的发生器、上下文提供者、结果锚定器。举个真实例子：我们有个微服务模块，某次上线后出现偶发 NPE，回溯发现是某次 PR 中Optional.get()被无条件调用。传统做法是让当事人写 RCA 报告；而我们的oclr review --diff=HEAD~1..HEAD命令会自动提取这次提交的变更集，喂给 LLM，并限定 prompt：“仅分析新增代码中可能引发 NullPointerException 的模式，忽略已有代码”。结果返回三条高置信度建议，其中一条正是Optional.get()无判空调用——且直接定位到行号。

这背后依赖 Git 的三大能力：
第一，git diff提供精确的增量上下文，避免 LLM “全量读代码”导致的 hallucination；
第二，git log -p提供历史决策链，比如某条规则被 disable 的 commit message 写着“临时绕过，因 legacy API 兼容问题”，这就是审查结论的元信息；
第三，git notes可附加审查结果到任意 commit 上，实现“审查记录随代码永生”，不用依赖外部数据库。

所以 open-code-review 的安装第一步永远是git config --global core.hooksPath .githooks，而不是npm install -g oclr。Git Hook（尤其是 pre-commit 和 prepare-commit-msg）才是真正的入口，CLI 只是它的执行器。这也是为什么所有教程里“git 安装”“git 配置”关键词热度居高不下——没稳定的 Git 环境，open-code-review 就是空中楼阁。

2.3 LLM 不是裁判，而是“超级助教”：它的角色必须被严格约束

这是最容易踩坑的认知误区：认为接入 LLM 就等于自动化 Review。错。LLM 在 open-code-review 中的角色，是高精度模式识别器 + 结构化信息抽取器 + 自然语言解释生成器，但它绝不做通过/拒绝的二元判决。

我们明确规定三条铁律：

1. 所有 LLM 输出必须附带 confidence score（0.0–1.0），低于 0.7 的建议自动标记为 “low-confidence”，不参与 CI 拦截；
2. LLM 只能输出 SARIF 格式 JSON，字段严格限定为{ruleId, message, level, locations[]}，禁止自由发挥；
3. 每次调用必须传入--context-lines=3参数，强制 LLM 只看变更行及上下文，杜绝全局臆断。

这些约束不是限制模型能力，而是建立人机协作的信任边界。比如某次 LLM 报告“检测到硬编码密码”，但 confidence 只有 0.62，我们不会直接 reject PR，而是让 Reviewer 看报告里的locations[0].physicalLocation.artifactLocation.uri定位到文件，再结合message.text里的解释：“字符串 'admin123' 出现在 config.js 第 42 行，未经过环境变量注入处理”——这时人类只需花 15 秒确认是否真为密码，而非从头分析整段代码。

这也解释了为什么“使用 LLM 时如何防止密钥泄露”成为热搜词：open-code-review 的 CLI 层会自动过滤掉所有含API_KEY、SECRET、PASSWORD字样的环境变量，并在调用 LLM 前做 redaction。真正的密钥永远不会离开本地机器，模型看到的只是<REDACTED_API_KEY>占位符。安全不是靠模型自律，而是靠 CLI 层的输入净化管道。

3. 核心细节解析：从零搭建 open-code-review 的五层结构

3.1 第一层：CLI 工具链——为什么选 Rust + clap 而非 Node.js

oclrCLI 的核心二进制文件是用 Rust 编写的，不是因为“Rust 多酷”，而是三个硬性需求倒逼的选择：

• 启动速度必须 < 50ms：Git pre-commit hook 有严格超时限制（通常 1s），Node.js 启动 V8 引擎+加载依赖常达 300ms+，而 Rust 二进制冷启动实测 12ms；
• 单文件分发必须可靠：团队有 Win/macOS/Linux 三端开发，要求curl -L https://get.oclr.dev | sh一键安装，Rust 的cargo-bundle可打包全平台静态二进制，Node.js 则需用户预装 npm、node-gyp 等，Windows 上尤其脆弱；
• 内存隔离必须严格：LLM 推理进程（如 llama.cpp）需与 CLI 主进程隔离，Rust 的std::process::Command对子进程控制粒度远超 Node.js 的child_process.spawn，可精确设置ulimit -v限制内存，防止 OOM 杀死 Git 进程。

我们对比过oclir（TypeScript 版）和oclr（Rust 版）在 1000 次 pre-commit 触发下的表现：TypeScript 版平均耗时 420ms，失败率 3.7%（多为 timeout）；Rust 版平均 68ms，失败率 0%。这不是性能洁癖，而是工程稳定性刚需。

CLI 的 clap 命令树设计遵循 Git 风格：

oclr review [OPTIONS] # 主审查命令 --diff <SPEC> # 指定 diff 范围，如 HEAD~1..HEAD --rules <PATH> # 加载规则集，默认 .oclr/rules.yaml --llm <MODEL> # 指定模型，如 llama3:8b、qwen2:7b --context-lines <N> # 上下文行数，默认 3 oclr lint --rule <ID> # 单规则快速验证 oclr init # 初始化项目，创建 .oclr/ 目录结构 oclr export --format sarif # 导出标准 SARIF 报告

注意：oclr不内置任何 LLM 模型，它只负责调度。模型由用户自行下载（如ollama pull qwen2:7b），CLI 通过 HTTP 调用本地 ollama API。这样既规避 license 风险，又保证模型可随时升级。所有模型调用日志默认关闭，如需调试可加--debug参数，日志仅存本地，不上传。

3.2 第二层：规则引擎——YAML 不是妥协，而是可审计性的基石

.oclr/rules.yaml长这样：

version: "1.0" rules: - id: "no-console-log" name: "禁止生产环境 console.log" level: "error" enabled: true description: "console.log 会暴露敏感信息且影响性能" pattern: "console\\.log\\(" language: ["javascript", "typescript"] linters: - name: "regex" config: {} - name: "llm" config: prompt: | 你是一名资深前端工程师。请严格按以下格式输出 JSON： {"issues": [{"line": 123, "message": "此处 console.log 可能泄露用户 token"}]} 仅分析匹配 pattern 的代码行及其上下文 {{context}}。 temperature: 0.1 max_tokens: 256 - id: "sql-injection" name: "防范 SQL 注入" level: "critical" enabled: true pattern: "\\+\\s*['\"`]\\s*\\+" language: ["java", "python", "go"] linters: - name: "ast" config: ast_type: "BinaryOp"

关键设计点：

• pattern 字段是正则或 AST 类型：先用轻量级 regex/AST 扫描快速过滤，再把可疑片段送 LLM 深度分析，避免“全量喂模型”导致的延迟和成本爆炸；
• language 字段声明适用语言：CLI 会自动跳过不匹配的文件，比如 Java 规则不会扫描 .ts 文件；
• linters 数组支持多引擎并行：regex 快但粗糙，AST 精准但语言受限，LLM 智能但慢——三者组合才是工业级方案。

为什么不用 JSON Schema？因为 YAML 支持注释（# 这是禁用原因），Git diff 时可读性极强；为什么不用 DSL？因为 YAML 是 DevOps 工具链（Ansible/Terraform/K8s）的通用语言，运维同学也能看懂改规则。

3.3 第三层：LLM 调度层——如何让大模型“听话”地干活

LLM 不是黑箱，而是需要精密调教的协作者。oclr的 LLM 调度层包含三个核心机制：

1. Prompt 模板化管理
所有 prompt 存在./.oclr/prompts/下，按规则 ID 命名：no-console-log.jinja2。内容是 Jinja2 模板：

你是一名 {{role}}。请严格按以下 JSON Schema 输出，不要任何额外字符： { "issues": [ { "line": "{{line_number}}", "message": "string", "confidence": "number (0.0-1.0)" } ] } 当前代码片段： {{code_context}} 请只分析此片段，不推测其他文件。

CLI 渲染时注入role="Java 安全专家"、line_number=42、code_context="String sql = \"SELECT * FROM user WHERE id = \" + userId;"。模板化确保每次调用参数可控，杜绝 prompt injection。

2. Confidence Score 校准
LLM 返回的 confidence 不是模型原生输出，而是 CLI 层二次计算：

• 对每个 issue，提取 message 中的关键词（如“硬编码”、“未校验”、“可能泄露”）匹配预设权重表；
• 检查 JSON 是否符合 schema（缺失字段扣分）；
• 对比 regex 扫描结果：若 regex 已匹配但 LLM 未报告，confidence × 0.5。
  最终 score = min(1.0, raw_score × calibration_factor)。

3. Redaction Pipeline
在代码送入 LLM 前，执行三级脱敏：

fn redact_code(code: &str) -> String { let mut redacted = code.replace(r"(?i)api[_-]?key\s*[:=]\s*['\"`][^'\"]+['\"`]", "$1<REDACTED_API_KEY>"); redacted = redacted.replace(r"(?i)password\s*[:=]\s*['\"`][^'\"]+['\"`]", "$1<REDACTED_PASSWORD>"); redacted = redacted.replace(r"\b(0x[0-9a-fA-F]{32}|[0-9a-fA-F]{64})\b", "<REDACTED_HASH>"); redacted }

所有正则均经 OWASP Cheat Sheet 验证，覆盖常见密钥模式。这才是“防止密钥泄露”的实操答案——不是靠模型自律，而是靠输入端净化。

3.4 第四层：Git 集成——Hook 不是装饰，而是审查发生的物理现场

.githooks/pre-commit是 open-code-review 的心脏：

#!/bin/sh # 检查是否在主干分支 if git rev-parse --abbrev-ref HEAD | grep -qE "^(main|master|develop)$"; then echo "⚠️ 主干分支禁止直接提交，请创建 PR" exit 1 fi # 运行 oclr review，仅检查本次暂存区变更 if ! oclr review --diff=HEAD... --rules=.oclr/rules.yaml --llm=qwen2:7b; then echo "❌ open-code-review 检查失败，请修复后重试" exit 1 fi # 生成审查报告并附加到 commit oclr export --format=sarif > .oclr/reports/$(git rev-parse --short HEAD).sarif git notes --ref=oclr add -F .oclr/reports/$(git rev-parse --short HEAD).sarif

关键细节：

• --diff=HEAD...表示“工作区 vs 暂存区”，确保只审查即将提交的代码，而非整个仓库；
• git notes --ref=oclr将 SARIF 报告作为 Git notes 附加到 commit，git log --notes=oclr可查看所有审查记录，git show :oclr/<commit-hash>可提取原始报告；
• Hook 失败时 exit 1是强制拦截，不是警告——这是审查严肃性的底线。

我们还配置了prepare-commit-msgHook 自动生成审查摘要：

echo "# open-code-review summary" >> $1 oclr review --diff=HEAD... --format=markdown >> $1

这样每次 commit message 都自带审查快照，无需切换页面。

3.5 第五层：CI/CD 流水线——审查不是终点，而是质量门禁

GitHub Actions 中的.github/workflows/oclr.yml：

name: open-code-review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取完整历史，用于 diff 计算 - name: Install oclr run: curl -L https://get.oclr.dev | sh - name: Run open-code-review run: | oclr review \ --diff=${{ github.event.pull_request.head.sha }}^..${{ github.event.pull_request.head.sha }} \ --rules=.oclr/rules.yaml \ --llm=llama3:8b \ --output-dir=.oclr/ci-reports - name: Upload SARIF report uses: github/codeql-action/upload-sarif@v3 with: sarif_file: .oclr/ci-reports/*.sarif

重点在于--diff参数：用${{ github.event.pull_request.head.sha }}^..${{ github.event.pull_request.head.sha }}精确指定 PR 的变更范围，避免误报。SARIF 报告上传后，GitHub 会自动在 PR 界面显示 Code Scanning 警告，点击即可跳转到问题行。

更进一步，我们在oclr review后加了质量门禁：

# 若 critical 级别问题 > 0，则失败 if [ $(jq '.runs[0].results[] | select(.level=="critical") | length' .oclr/ci-reports/*.sarif 2>/dev/null || echo 0) -gt 0 ]; then echo "🚨 Critical issues found. CI failed." exit 1 fi

这才是真正的“质量门禁”——不是靠人工点 Merge 按钮，而是靠机器严格执行规则。

4. 实操过程：手把手完成一次 open-code-review 全流程

4.1 环境准备：三步完成基础搭建（5 分钟）

Step 1：安装 Git 并配置基础项
这不是“git 下载教程”的复读，而是针对 open-code-review 的最小必要配置：

# Ubuntu/Debian sudo apt update && sudo apt install -y git curl # macOS（Homebrew） brew install git curl # Windows（Git for Windows） # 下载地址：https://git-scm.com/download/win（选“Use Git from Windows Command Prompt”） # 全局配置（关键！） git config --global core.autocrlf input # 防止 Windows 换行符污染 git config --global init.defaultBranch main git config --global core.hooksPath .githooks # 指向项目级 hooks

注意：core.hooksPath必须设为相对路径.githooks，而非绝对路径。这样 clone 仓库后，hook 自动生效，无需手动 symlink。

Step 2：安装 oclr CLI（Rust 版）

# Linux/macOS curl -L https://get.oclr.dev | sh # Windows（PowerShell） Invoke-WebRequest -Uri "https://get.oclr.dev" -OutFile "install.ps1"; .\install.ps1 # 验证 oclr --version # 应输出 v0.8.2+

该脚本会检测系统架构，下载对应 rustup 编译的二进制，放入~/.local/bin（Linux/macOS）或%USERPROFILE%\AppData\Local\oclr（Windows），并自动添加到 PATH。

Step 3：初始化项目

# 进入你的代码仓库 cd /path/to/your/project # 初始化 open-code-review 结构 oclr init # 目录结构自动生成： # .githooks/ # └── pre-commit # .oclr/ # ├── rules.yaml # ├── prompts/ # │ └── default.jinja2 # └── config.yaml

oclr init不仅创建目录，还会写入预置的 5 条基础规则（如 no-console-log、no-debugger、sql-injection 检测），并设置 Git Hook 权限：

chmod +x .githooks/pre-commit

4.2 规则定制：修改 rules.yaml 实现业务适配（10 分钟）

打开.oclr/rules.yaml，找到no-console-log规则，修改其level和description：

- id: "no-console-log" name: "禁止生产环境 console.log" level: "warning" # 降级为 warning，不阻断提交 enabled: true description: "console.log 会暴露敏感信息且影响性能。测试环境允许，生产环境禁止。" pattern: "console\\.log\\(" language: ["javascript", "typescript"] linters: - name: "regex" config: {} - name: "llm" config: prompt: | 你是一名前端安全工程师。请判断以下代码是否在生产环境使用 console.log： {{code_context}} 如果是，请返回 {\"issues\": [{\"line\": {{line_number}}, \"message\": \"生产环境禁止 console.log\", \"confidence\": 0.95}]} 如果否（如在 if (process.env.NODE_ENV === 'development') 块内），返回 {\"issues\": []} temperature: 0.1

关键改动：

• level: "warning"：让 pre-commit 不失败，但 CI 仍可设为 error；
• prompt 中加入环境判断逻辑，LLM 需识别process.env.NODE_ENV条件。

保存后，尝试触发一次 pre-commit：

echo "console.log('test');" >> src/test.js git add src/test.js git commit -m "test console.log" # 此时应看到 warning，但 commit 成功

你会看到 CLI 输出：

⚠️ [no-console-log] src/test.js:1:1 - 生产环境禁止 console.log (confidence: 0.95)

4.3 LLM 接入：用 ollama 运行本地模型（3 分钟）

open-code-review 不绑定任何云服务，推荐用 ollama 运行本地模型：

# 安装 ollama（https://ollama.com/download） # macOS brew install ollama # Linux curl -fsSL https://ollama.com/install.sh | sh # Windows # 下载安装包：https://ollama.com/download/windows # 拉取轻量模型（7B 参数，16GB RAM 可跑） ollama pull qwen2:7b # 启动服务（默认 http://localhost:11434） ollama serve &

验证 CLI 能调用：

oclr review --diff=HEAD... --llm=qwen2:7b --dry-run # 应输出模拟的 SARIF JSON，无报错

实测：qwen2:7b 在 M2 Mac 上推理速度约 12 tokens/s，处理 50 行代码平均 2.3 秒；llama3:8b 在 RTX 4090 上达 45 tokens/s。模型选择取决于你的硬件，CLI 层完全透明。

4.4 Git Hook 深度集成：让审查发生在代码诞生瞬间（2 分钟）

编辑.githooks/pre-commit，在末尾添加：

# 在 oclr review 后，自动修正可修复问题 if oclr fix --diff=HEAD... --rules=.oclr/rules.yaml; then echo "🔧 自动修复完成，重新 add 修改" git add . else echo "💡 无自动修复项，继续提交" fi

oclr fix命令会调用规则中auto_fix: true的规则（如 trailing-space、indent-size），执行代码格式化。这样git commit时，代码已自动符合规范。

4.5 CI 流水线部署：GitHub Actions 实战配置（8 分钟）

创建.github/workflows/oclr.yml：

name: open-code-review on: pull_request: types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Install oclr run: curl -L https://get.oclr.dev | sh - name: Run open-code-review env: OCLL_LLM_MODEL: "qwen2:7b" run: | oclr review \ --diff=${{ github.event.pull_request.head.sha }}^..${{ github.event.pull_request.head.sha }} \ --rules=.oclr/rules.yaml \ --output-dir=.oclr/ci-reports \ --llm=${{ env.OCLL_LLM_MODEL }} - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: .oclr/ci-reports/*.sarif - name: Fail on critical issues if: always() run: | if [ -f .oclr/ci-reports/*.sarif ]; then CRITICAL_COUNT=$(jq '.runs[0].results[] | select(.level=="critical") | length' .oclr/ci-reports/*.sarif 2>/dev/null || echo 0) if [ "$CRITICAL_COUNT" -gt 0 ]; then echo "🚨 Found $CRITICAL_COUNT critical issues" exit 1 fi fi

Push 后，任意 PR 都会触发此 workflow。GitHub 会在 PR Files Changed 标签页底部显示 “Code scanning results”，点击即可查看 LLM 发现的问题。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “oclr review 报错：failed to start. unable to locate the codex cli binary” —— 这不是你的错

这个错误信息极具误导性，它实际意思是：CLI 找不到本地运行的 LLM 服务。所谓 “codex cli” 是旧版工具链的残留命名，oclr从未依赖 codex。

排查步骤：

1. 检查 ollama 是否在运行：curl http://localhost:11434/api/tags，应返回 JSON 列表；
2. 检查模型是否拉取成功：ollama list，确认qwen2:7b在列表中；
3. 检查 CLI 配置：oclr config get llm.url，默认是http://localhost:11434，如需改端口，运行oclr config set llm.url http://127.0.0.1:11434；
4. Windows 用户注意：Git Bash 默认不继承 Windows 环境变量，需在.bashrc中添加export OLLAMA_HOST=http://127.0.0.1:11434。

实操心得：我们团队在 Windows 上统一用 PowerShell 运行oclr，避免 Git Bash 兼容性问题。PowerShell 的Invoke-RestMethod对 HTTP 调用更稳定。

5.2 LLM 返回 JSON 格式错误，导致 CLI 解析失败

LLM 有时会返回带 markdown 代码块的 JSON（如json{...}），或在 JSON 前后加说明文字。oclr默认启用 strict JSON parsing，失败即报错。

解决方案：

• 在 prompt 中强制要求：“仅输出纯 JSON，不带任何 markdown、不带任何说明文字、不带任何注释”；
• CLI 层增加容错解析：oclr config set llm.strict_json false，启用正则提取 JSON 片段；
• 终极方案：用jq预处理，oclr review --raw-output | jq -r 'fromjson'。

注意：strict_json=false会降低可靠性，仅用于调试。生产环境务必保持 true，并优化 prompt。

5.3 Git diff 范围错误，导致 LLM 分析全仓库代码

常见错误命令：oclr review --diff=HEAD，这会让 Git 解释为 “HEAD 到工作区”，即分析所有未 commit 文件，可能达数千行。

正确用法：

• --diff=HEAD...：工作区 vs 暂存区（pre-commit 场景）；
• --diff=HEAD~1..HEAD：上一个 commit 到当前 commit（CI 场景）；
• --diff=origin/main...HEAD：远程 main 分支到当前 HEAD（PR 场景）。

验证 diff 范围：git diff --name-only HEAD...应只输出你刚git add的文件。

5.4 SARIF 报告不显示在 GitHub UI

原因通常是 SARIF 文件不符合 GitHub Schema。oclr export默认生成合规 SARIF，但常见破坏点：

• 手动编辑 SARIF 文件，删掉runs[0].tool.driver.name字段；
• CI 中sarif_file路径写错，如./.oclr/ci-reports/report.sarif而非.oclr/ci-reports/*.sarif；
• SARIF 中level字段值不是"error"/"warning"/"note"/"recommendation"（GitHub 只认这四个）。

验证方法：用官方 validator https://sarifweb.azurewebsites.net/ 上传报告。

5.5 如何调试 LLM 的具体输出？

oclr提供-v（verbose）和--debug模式：

oclr review --diff=HEAD... --llm=qwen2:7b -v # 输出：发送给 LLM 的完整 prompt、收到的原始响应、解析后的 SARIF oclr review --diff=HEAD... --llm=qwen2:7b --debug # 输出：额外打印 HTTP 请求/响应头、redacted 后的代码、confidence 计算过程

调试日志默认写入./.oclr/debug/，按时间戳命名，方便回溯。

个人经验：我们每周抽 1 小时做 “LLM 审查质量复盘”，用oclr review --debug日志，统计每条规则的 false positive rate。发现sql-injection规则在拼接字符串场景 FP 率达 42%，于是重写 prompt，加入 “检查是否在 PreparedStatement 中” 的判断逻辑，FP 降至 8%。

6. 进阶扩展：从单机 CLI 到团队知识库的跃迁

open-code-review 的终极形态，不是让每个人跑自己的 CLI，而是把审查知识沉淀为可复用的团队资产。我们做了三件事：

第一，构建规则共享仓库
创建internal/oclr-rules仓库，存放公司级规则集：

# internal/oclr-rules/payment.yaml - id: "payment-card-leak" name: "支付卡号泄露风险" pattern: "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|6(?:011|5[0-9][0-9])[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\\d{3})\\d{11})\\b" linters: - name: "regex" - name: "llm" config: prompt: | 你是一名 PCI DSS 合规专家。请确认以下数字是否为有效信用卡号，且出现在日志或前端代码中： {{code_context}} 如果是，返回 {\"issues\": [{\"line\": {{line_number}}, \"message\": \"信用卡号硬编码，违反 PCI DSS 3.4\", \"confidence\": 0.99}]}

各业务线通过oclr rules sync --from=git@company.com:internal/oclr-rules.git同步规则，git submodule管理版本。

第二，审查结果可视化看板
用oclr export --format=jsonl导出每日审查数据，接入 Grafana：

• 每日 critical issue 数量趋势；
• 各规则触发频