open-code-review

Open Code Review

一个用于调用 open-code-review（ocr）的技能 — 一个开源 AI 代码审查命令行工具，可读取 Git diff 并生成结构化的行级审查评论。

工作流

步骤 1：收集业务上下文

分析审查目标（提交、分支或变更）以提取简洁的业务上下文。通过 --background 传入此上下文以提升审查质量。

步骤 2：运行代码审查

不要预先检查 ocr 是否已安装 — 跳过 command -v ocr 或 ocr --version 之类的探测。假定命令行工具可用并直接运行审查；这样在常见路径上可节省一次工具调用。只有当审查因 command not found 失败时，才应按照故障排查部分进行安装。

使用适当的标志运行 OCR 命令。只要可用，始终通过 --background 传入业务上下文：

ocr review --audience agent --background "business context here" [user-args]

参数处理：

• 背景上下文（推荐）：使用 --background "context" 或 -b "context" 提供业务上下文以获得更好的审查质量
• 默认（无用户参数）：审查已暂存、未暂存和未跟踪的变更（工作区模式）
• 指定提交：使用 --commit 或 -c 审查单个提交与其父提交的差异
• 分支比较：使用 --from <ref> 和 --to <ref> 审查两个引用之间的 diff
• 超时：每个审查组的有效超时 = --timeout × 审查轮数。默认 --timeout 15 且默认工作量 medium（2 轮）为 30 分钟；low/high 分别为 15/45 分钟。
• 并发：默认并发为 8 个文件工作线程；如果遇到速率限制，可通过 --concurrency <n> 降低
• 预览模式：使用 --preview 或 -p 预览将审查哪些文件，而不运行大模型
• 输出文件：使用 --output <path> 将完整结果写入文件而非 stdout。如果命令失败并提示 unknown flag: --output，不要以纯 stdout 继续审查。询问用户是否升级（npm i -g @alibaba-group/open-code-review@latest）并等待答复后再继续。用户确认且升级成功后，使用 --output 重新运行。
• 安装：如果找不到 ocr 命令，请运行 npm i -g @alibaba-group/open-code-review 进行安装

常见调用模式：

用户说	要运行的命令
"review my changes" / "review the working copy"	ocr review --audience agent -b "context"
"review this PR" / "review feature branch"	ocr review --audience agent -b "context" --from main --to <branch>
"review commit abc123"	ocr review --audience agent -b "context" --commit abc123
"what would be reviewed?"（试运行）	ocr review --preview

输出模式：

• 始终使用 --audience agent 以抑制进度 UI，仅输出最终摘要
• 防止输出被截断：对于大型审查或受限的工具环境，请传入 --output /tmp/ocr_out.txt 并通过文件读取工具完整查看该文件，而不是将 stdout 通过 tail 或 head 管道处理，这会丢弃较早的审查评论。

失败时： 如果 ocr review 以非零状态退出（例如大模型连接错误），不要盲目重试 — 请查阅下方故障排查部分找到对应的修复方法后再重新运行。

步骤 3：报告

OCR 输出中每条评论都包含结构化的 severity（critical / high / medium / low）和 category（bug / security / performance / maintainability / test / style / documentation / other）。按严重程度分组呈现结果，丢弃可能为误报或吹毛求疵的 low 严重程度条目。

第 4 步：修复

在应用修复之前，请检查用户是否请求了自动修复：

• 如果用户明确请求"审查并修复"或类似内容，则继续进行自动修复
• 如果用户仅请求"审查"而没有修复意图，则在应用任何更改之前先征求许可

在修复问题和建议时：

• 重点关注 critical、high 和 medium 严重程度的项目
• 在安全且定义明确的情况下，直接将修复应用到代码
• 对于需要人工干预的复杂修复，请清楚描述需要完成的工作
• 在提交之前，始终与用户确认修复

输出格式

OCR 输出中的每条评论包含：

• path：文件路径
• content：审查评论文本
• start_line / end_line：行范围（两者均为 0 表示定位失败）
• category：问题类别（bug、security、performance、maintainability、test、style、documentation、other）
• severity：问题严重程度（critical、high、medium、low）
• suggestion_code：可选的修复建议
• existing_code：可选的原始代码片段
• thinking：可选的 LLM 推理过程

使用以下模板按严重程度分组呈现结果：

## Code Review Results

**Files reviewed**: N
**Issues found**: X critical, Y high, Z medium

### Critical

- **`path/to/file.java:42`** [bug] — Brief description
  > Recommendation: How to fix

### High

- **`path/to/file.java:26`** [bug] — Brief description
  > Recommendation: How to fix

### Medium

- **`path/to/file.ts:88`** [performance] — Brief description
  > Recommendation: How to fix (if applicable)

如果在过滤后没有剩余 critical、high 或 medium 严重程度的问题，则说明："Review complete — no critical, high, or medium issues found in N files."

处理定位错误的评论：

当 start_line 和 end_line 均为 0 时，评论未能定位到文件中的确切位置。在这种情况下：

1. 阅读评论内容以理解问题
2. 检查评论中提到的目标文件
3. 根据评论的上下文识别相关代码段
4. 将修复或建议应用到正确的位置

自定义审查规则

如果用户需要项目特定的规则，OCR 按以下优先级顺序解析它们：

1. --rule <path> 标志（最高）
2. <repo>/.opencodereview/rule.json
3. ~/.opencodereview/rule.json
4. 内置系统默认值（最低）

默认情况下，第一个匹配的用户规则会替换内置系统规则。当匹配的系统规则和用户规则都应包含时，在规则条目上设置 merge_system_rule: true。

规则文件格式：

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "All new methods must validate required parameters for null",
      "merge_system_rule": true
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks and missing closing tags"
    }
  ]
}

要在审查之前预览适用于某个文件的规则：

ocr rules check src/main/java/com/example/Foo.java

高级审查选项

除上述常用标志外，ocr review 还提供几组控制项。运行 ocr review --help 可获取完整列表。

范围限定

• --exclude '<patterns>' — 逗号分隔的 gitignore 风格模式（例如 --exclude '**/generated/*,**/testdata/*'），与 rule.json 中的 excludes 合并。
• --background-file <path> — 从 Markdown 文件读取审查上下文。优先于 --background。

输出

• --format text|json|sarif — text（默认）供人阅读；json 用于机器可读的发现结果；sarif 用于代码扫描集成，例如 GitHub Code Scanning。

模型

• --provider <name> / --model <name> — 仅覆盖本次运行所配置的 provider/model（例如，用不同的模型重新检查某个 diff；由用户指定模型名称，ocr llm providers 会列出内置模型）。

预算

• --max-tokens <n> — 每组提示词的上限；默认为所配置的值或模板默认值（200000）。
• --max-tokens-budget <n> — 限制本次运行的输入 + 输出 token 总量。在每一轮 LLM 之前检查：已超出预算的组会获得最后一轮提交发现结果的机会，不再派发更多组，部分结果仍会发布，被跳过的文件会报告为 failed(budget)。
• --no-filter — 保留所有审查评论并跳过 LLM 后置过滤调用。

注意事项

• 必须先配置大模型 —— 如果无法连接到大模型，ocr review 会直接报错失败。如果遇到这种情况，请参阅下面的疑难解答部分。
• 工作目录很重要 —— ocr review 会针对当前目录下的 Git 仓库进行操作。若要从其他位置运行，请使用 --repo /path/to/repo。
• 未跟踪的文件会在工作区模式下被审查 —— 直接运行 ocr review 会包含已暂存、未暂存以及未跟踪的更改。如果你想要更小的范围，请选择性地暂存。
• 大型 diff 可能会触及 token 上限 —— MAX_TOKENS 设置提示词预算（审查模板中为 200000；ocr scan 使用 58888）；对话上下文会被压缩以保持在该提示词预算之内。模型输出由 MAX_COMPLETION_TOKENS（16384）单独限制。如果某个文件仅 diff 就超过 MAX_TOKENS 的约 80%，则会在调用大模型之前被跳过。
• 计划阶段会在两个阈值中的任意一个触发 —— 当某个分组中最大的变更文件达到 PLAN_MODE_LINE_THRESHOLD（默认 50），或该分组包含 2 个及以上文件且其变更行数合计达到 PLAN_MODE_GROUP_LINE_THRESHOLD（默认 100）时，该分组会在主审查之前运行额外的风险分析阶段。这会增加延迟，但能提升质量。
• 不要传入 --audience human —— 它会输出进度 UI，污染输出结果。请始终使用 --audience agent。
• 评论语言遵循配置 —— language 配置控制审查评论的语言，默认为 English，并接受任意语言名称（例如 English 或 中文）。
• 避免输出被截断 —— 大型审查任务会产生冗长的输出。切勿将命令输出通过管道传给 tail 或 head，因为这会丢弃前面部分的审查评论。请使用 --output <path> 并完整读取；在较旧的 CLI 上，请遵循上文 输出文件 的指引。
• 恢复被中断的审查 —— 失败或被中断的范围/提交审查，可以使用相同的 --from/--to 或 --commit 目标，通过 ocr review --resume <id> 继续（失败时 id 会以 retry with: --resume <id> 的形式打印，也可以用 ocr session list 找到它）。不支持工作区恢复。

验证

审查完成后，通过检查以下内容来确认成功：

1. 命令以退出码 0 退出
2. 已生成评论（或出现“No comments generated”消息）
3. 警告（如有）显示在 stderr 中

如果发生错误，请检查 stderr 中的警告，以了解哪些文件失败以及失败原因。

疑难解答

ocr: command not found

安装 CLI：

npm install -g @alibaba-group/open-code-review

unknown flag: --output

该 CLI 版本低于 v1.10.0。不要用纯 stdout 继续审查。询问用户是否要升级（npm i -g @alibaba-group/open-code-review@latest），并在继续之前等待答复。在用户确认且升级成功后，使用 --output 重新运行。

ocr review 因大模型连接错误而失败

提示用户配置大模型提供方。

交互式设置（推荐）：

ocr config provider

手动设置（备选）：

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token <api-key>
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

使用 ocr llm test 验证连通性。在此停止，并要求用户提供凭据 —— 切勿编造或硬编码 API 密钥。

参考

• 完整文档：https://github.com/alibaba/open-code-review
• NPM 包：https://www.npmjs.com/package/@alibaba-group/open-code-review
• Issue 跟踪器：https://github.com/alibaba/open-code-review/issues