open-code-review

Open Code Review — 通过 ocr CLI 优先路由的 AI 评审

关键词：open-code-review · ocr review · ocr scan

OpenCodeReview (OCR) 是 Alibaba 推出的开源 AI 代码评审 CLI。它读取 Git 差异（或整个文件），并通过配置好的大模型生成 结构化、精确到行的评审评论。

此技能是 ocr 二进制文件的操作入口：它会选择能够回答用户问题的最轻量调用方式，提供业务上下文，对发现的问题进行分类，然后才应用修复。它不会重新实现人工评审判断——这部分由相邻的 code-review 技能负责。

何时使用此技能

• 用户想要自动评审工作副本中的更改、某次提交、分支范围或 PR/MR
• 用户想要扫描整个文件（无差异），以审查不熟悉的代码库或迁移前的代码库
• 用户想要将评审接入编码 Agent（Claude Code / Codex 斜杠命令）或 CI/CD
• 用户需要配置 ocr 大模型提供方或测试连接
• 用户想要按优先级对 OCR 评论分类，并选择性地自动修复

何时不使用此技能

• 以证据为先的人工评审判断（批准 / 要求更改 / 阻止的理由）→ code-review
• 拆分提交、变基、冲突解决、推送恢复 → git-workflow
• 复现或隔离正在发生的运行时故障 → debugging
• 长期覆盖率策略、CI 门禁、易出错测试套件方向 → testing-strategies
• 以测量为依据的瓶颈分析 → performance-optimization

说明

第 1 步：评审前确认先决条件

which ocr || echo "NOT INSTALLED"   # CLI present?
ocr llm test                        # LLM reachable?

如果缺少 ocr，只安装环境所需的内容：

bash scripts/install.sh --method npm         # global npm install (default)
bash scripts/install.sh --method release     # GitHub release binary (macOS/Linux)
bash scripts/install.sh --method source      # build from source with make

如果 ocr llm test 失败，用户必须配置提供方。切勿臆造或硬编码 API 密钥——停止操作并向用户索要凭据，然后选择以下一种方式：

# Interactive (recommended for humans)
ocr config provider
ocr config model

# Non-interactive (CI/scripts) — built-in provider
ocr config set provider anthropic
ocr config set providers.anthropic.api_key <api-key>
ocr config set providers.anthropic.model claude-sonnet-4-6

# Environment variables (highest priority — best for CI)
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=<api-key>
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

提供方和配置详情见参考资料/配置与规则。

第 2 步：调用前收集业务上下文

阅读提交说明、分支名称或用户陈述的意图，并提炼成一句简短的需求描述。通过 --background（-b）传入——OCR 会据此判断更改是否实现了需求，而不只是代码能否解析。

第 3 步：选择适用的最轻量调用方式

准确选择一种主要模式：

用户意图	命令
评审工作副本（已暂存 + 未暂存 + 未跟踪）	bash scripts/run-review.sh -b "context"
评审单次提交	bash scripts/run-review.sh --commit <sha> -b "context"
比较两个引用（PR / 功能分支）	bash scripts/run-review.sh --from <base> --to <head> -b "context"
试运行：查看将评审哪些文件	ocr review --preview
审查整个文件，但没有有意义的差异	bash scripts/run-scan.sh --path <dir>

包装脚本默认使用 --audience agent，该选项会隐藏进度界面，只输出最终摘要——这是 Agent（而非人类终端）读取输出时的合适模式。

# Workspace review with context
bash scripts/run-review.sh -b "Adding rate limiting to the login API"

# Branch range, JSON output for parsing, lower concurrency to dodge rate limits
bash scripts/run-review.sh --from origin/main --to feature-x --format json --concurrency 4

# Single commit; --background auto-fills from the commit message when omitted
bash scripts/run-review.sh --commit abc123

# Full-file scan of a subdirectory, capped spend, skipping generated/test files
bash scripts/run-scan.sh --path internal --exclude '**/*_test.go,**/generated/**' --max-tokens-budget 500000

评审/扫描标志参考见参考资料/输入与模式。

第 4 步：对发现的问题分类并报告

OCR 会返回包含 path、content、start_line/end_line（两者均为 0 表示定位失败）、可选的 suggestion_code、existing_code 和 thinking 的评论。按优先级分组：

• 高——明显的错误、安全问题、明确的失误，或依据充分且有精确建议的修复
• 中——合理但依赖上下文的问题、风格/性能建议、需要手动修复的事项
• 低——可能的误报、缺少上下文的问题、吹毛求疵的意见——除非用户要求全部列出，否则静默丢弃

按级别分组报告高优先级和中优先级问题；每项都注明 path:line。

步骤 5：有意修复并验证

• 如果用户明确要求“审查并修复”，在安全且有明确方案时，直接应用高优先级／中优先级修复
• 如果用户只要求“审查”，则在更改任何代码前先征求同意
• 对于需要人工处理的复杂修复，说明需要完成的工作，不要猜测
• 始终重新运行相关测试／构建，并在提交前向用户确认修复

步骤 6：按需将 OCR 接入 Agent 或 CI

• 安装技能：npx skills add alibaba/open-code-review --skill open-code-review
• Claude Code 插件：先运行 /plugin marketplace add alibaba/open-code-review，再运行 /plugin install open-code-review@open-code-review
• Codex 插件：运行 codex plugin marketplace add alibaba/open-code-review，然后运行 /plugins 启用
• CI/CD：ocr review --from "origin/main" --to "<commit_sha>" --format json（--to 使用提交 SHA，以便解析 fork PR）

插件和 CI 接入详情见 references/cicd-and-plugins.md。

输出格式

收到审查请求时，返回一份简洁、按优先级分组的摘要：

## Code Review Results

**Mode**: workspace | commit <sha> | <base>..<head> | scan
**Files reviewed**: N
**Issues**: X high / Y medium

### High priority
- **`path/to/file.go:42`** — what is wrong
  > Recommendation: how to fix

### Medium priority
- **`path/to/other.ts:88`** — concern + context

### Decision
- ran <command>; fixes applied | fixes proposed (awaiting approval) | route-out to <skill>

示例

示例 1：“审查我的更改”

运行 bash scripts/run-review.sh -b "<context>"（工作区模式），然后分类并报告。

示例 2：“根据 main 审查这个 PR”

运行 bash scripts/run-review.sh --from origin/main --to <branch> -b "<context>"。

示例 3：“审计这个陌生仓库中的问题”

先运行 bash scripts/run-scan.sh --preview，查看文件列表和令牌估算，然后扫描。

示例 4：“审查提交 abc123，并修复高置信度的错误”

运行 bash scripts/run-review.sh --commit abc123，仅应用高优先级发现对应的精确修复，验证后确认。

示例 5：“将 OCR 添加到我们的 GitHub Actions”

转至 references/cicd-and-plugins.md；使用 ocr review --from origin/main --to <sha> --format json。

示例 6：“帮我判断是否应批准这项有风险的迁移”

这是审查判断，而非工具使用——运行 OCR 获取参考信息，然后将决策交给 code-review。

最佳实践

1. 在承诺进行审查前，确认已安装 ocr，且 ocr llm test 已通过。
2. 尽可能传入可推断出的 --background 上下文——这能显著提高相关性。
3. 选择一种调用模式；不要针对同一问题同时运行审查和扫描。
4. 对大型 scan，先使用 --preview 估算范围和成本。
5. 面向机器处理时使用 --format json 和 --audience agent；终端中则使用文本／面向人的输出。
6. 将 OCR 评论视为证据输入，而非最终结论——直接忽略低置信度的噪声。
7. 绝不伪造或硬编码 API 密钥；停止操作并向用户索取凭据。
8. 仅在用户明确要求时，自动修复安全的高优先级／中优先级问题，并在提交前验证。
9. 将人工批准／阻止的判断交给 code-review，Git 清理交给 git-workflow，实时调试交给 debugging。

参考资料

• references/intake-and-modes.md
• references/configuration-and-rules.md
• references/cicd-and-plugins.md
• scripts/install.sh
• scripts/run-review.sh
• scripts/run-scan.sh
• OpenCodeReview GitHub 仓库
• OpenCodeReview 文档