AI 代码审查官 — Open Code Review

你现在运行 open-code-review 技能。目标：让 coding agent 真的能逐行审查一段 Git diff —— 当前 feature 分支跟 main 的差异、单个 commit、一个公开 PR、或本地 未提交改动 —— 并产出一份带行号锚点的 Markdown 审查报告 + 一份机器可读的 JSON 报告，能直接贴进 PR 评论或接 CI 卡控。

底层是阿里巴巴在内部跑了两年、为数万开发者识别过百万级缺陷、最近开源出来的 @alibaba-group/open-code-review （Apache-2.0、Go 写的全平台 CLI，命令入口 ocr）。它的核心不是「把 LLM 裹一层」，而是 确定性工程 + LLM agent 的混合架构：

• 工程层做硬约束：精确的文件选择（不漏文件）、智能文件分桶（相关文件捆绑成一 个 sub-agent，复审更稳）、规则模板按文件特征精准匹配、独立的位置定位 + 反思 模块（行号锚点不会漂）。
• agent 层做动态决策：场景化 prompt + 场景化工具集（从大规模生产数据里蒸馏 出的工具调用频率分布做了二次设计），只在「下一个该问什么」、「这段代码需要拉 哪些上下文」这种动态判断上花 token。

课程直接消费上游 npm 包 + 上游 ocr CLI。

这门课做什么（边界写在第一屏）

• ✅ 做：给一段 Git diff（分支对比 / 单 commit / 公开 PR / 未提交工作区）→ agent 在本地跑 ocr review → 落 ./out/review.md（--format text --audience human 输出 tee 到磁盘的进度 + 评论流，每条评论带 file:start-end 锚点）+ ./out/review.json（--format json --audience agent 的机器可读 报告，schema 见下方"产出 schema"段落）。
• ✅ agent-as-debugger：每一步「ocr 报错了怎么排查、规则要不要调、PR 拒掉哪些 CRITICAL 评论」由 user session 里的 agent（Claude Code / Cursor / Codex CLI） 自己判断。ocr 自己的 HTTP 客户端按 OCR_LLM_URL POST 到 https://api.anthropic.com/v1/messages。
• ✅ 报告真的能复跑：review.json 用 jq . 解析得动；每条 comment 的 path + start_line + end_line 都能在 diff 里搜得到、能直接贴进 PR inline-comment；existing_code / suggestion_code 给 reviewer 看「现状 vs 建议」无歧义。OCR 不输出离散的 severity 字段（README 里也没承诺）——严重程 度由 content 文本的自然语言前缀承担（最常见的是 CRITICAL: … / <topic>: … / 中性陈述）；如果你的 CI 需要硬卡红线，正确的 接法是按 content 文本里是否含 CRITICAL / HIGH 关键字来过滤（不要假设有 .severity 字段，否则永远 null）。
• ❌ 不做：替代 SAST / 运行时漏洞扫描（CVE 库匹配请用 cso 课程对应的工具）； 替代 AI agent 自身的安全体检（去看 agentguard）；替代网页性能体检（去看 agent-perf-audit）；替代「跟我解释这段代码」型通用问答（任何通用 coding agent 都能做，这门课只在「正式 PR review」这个边界上发力）。
• 🔒 关键提醒：需要一把你自己的 Anthropic API key；ocr 直接调 Anthropic 官方 Messages API，用量直接计在你自己的 Anthropic 账户上。安装步骤里会显式 export 四条 OCR_LLM_* 环境变量，确保 ocr 走的就是 Anthropic 官方 endpoint。

一句话定位：agentguard = 审查一个 agent skill 本身的安全； agent-perf-audit = 审查一个网页的性能； open-code-review = 审查一段 Git diff 的代码质量与安全（PR 级别）。 三门正交，按你的真实任务选一门。

前置条件

• Node ≥ 18（node --version 检查；用于 npm install -g @alibaba-group/open-code-review，安装期间会按你的平台拉对应预编译二进制）。
• 你自己的 Anthropic API key：到 console.anthropic.com 注册并在 API Keys 页面创建一把。
• Git：本课所有任务都基于 git diff（分支对比 / 单 commit / 工作区），任何 现代版本均可。
• 公共 demo 目标（QA 可复跑）：alibaba/open-code-review 自家公开仓库的某个 merged PR（Apache-2.0，dog-fooding 最稳）；或任何你能 git fetch 到的 OSS PR。
• CPU 即可，无 GPU 要求；课程在本机离线运行，无需 Clawvard 账户、无需 clone 任何 Clawvard 私有仓库。

安装（一次到位）

# 1) 装 ocr（npm 包，全平台，安装期间按你的 OS/CPU 拉预编译二进制）
npm install -g @alibaba-group/open-code-review

# 2) 自检：ocr 命令在 PATH 里
ocr version
# → open-code-review v1.x.x (sha) <os>/<arch>

# 3) 显式 export 这四条，让 ocr 走 Anthropic 官方 Messages API
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=$ANTHROPIC_API_KEY    # 你自己从 console.anthropic.com 拿的 Anthropic key
export OCR_LLM_MODEL=claude-sonnet-4-6     # 或 claude-opus-4-7
export OCR_USE_ANTHROPIC=true

# 4) 连通性自检（应该看到 ✓ 200 OK）
ocr llm test

为什么要显式 export 这四条？ ocr 也会复用你 shell 里既有的 Anthropic 环境变量（README 原话："also compatible with Claude Code environment variables"）。显式 export 上面四条 OCR_LLM_* 是确保 ocr 走的就是 Anthropic 官方 endpoint，与你日常 Claude Code 的环境变量隔离。

如果你想把 key 写进配置文件而不是 env，等价命令是：

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token $ANTHROPIC_API_KEY
ocr config set llm.model claude-sonnet-4-6
ocr config set llm.use_anthropic true
# 存在 ~/.opencodereview/config.json；env 变量优先级仍高于配置文件。

三类典型场景（覆盖 popularTasks）

每条都是 ./out/ 的真实文件清单，没有 mock、没有 placeholder。

Task 1 — 审一下我当前 feature 分支的改动（vs origin/main）

最常见的用法：你刚写完一段功能，准备开 PR 前自己先扫一遍。

mkdir -p out && cd <你的 repo>

# 拿到 main 的最新版本（避免基于过期 base 算 diff）
git fetch origin main

# 跑审查 —— text 给人看，audience=human 会打进度条；tee 一份到 out/review.md 留档
ocr review --from origin/main --to HEAD --format text --audience human \
  --concurrency 4 | tee out/review.md

# 同一份事实再跑一次 JSON（给 CI / 二次脚本化用）
ocr review --from origin/main --to HEAD --format json --audience agent \
  --concurrency 4 > out/review.json

检验：

• out/review.md 每条评论必须有 file:start-end 锚点（能在你的工作区 grep 到）。
• out/review.json 用 jq '.summary' 看「文件数 / 评论数 / 耗时 / 累计 token」一栏；用 jq '.comments[] | {path, start_line, end_line, content}' 把每条 comment 摊平到关键字段；schema 见下方"产出 schema"。
• 把 markdown 直接贴 PR 描述 / review 评论里；把 JSON 接 CI 卡红线，举例（按 自然语言前缀过滤，因为 ocr 不输出离散 severity 字段）：

  jq '[.comments[] | select(.content | test("CRITICAL|HIGH"; "i"))] | length' \
    out/review.json
  # ≥ 1 → 阻断 merge
  

Task 2 — 审一个具体的 commit / 一个公开 PR

merge 之前的最后一道闸门，或者你要 review 别人的 PR。

# 单 commit
ocr review --commit <sha> --format json --audience agent > out/commit-review.json
ocr review --commit <sha> --format text --audience human | tee out/commit-review.md

# 一个公开 GitHub PR：先把 head 拿下来
git fetch origin pull/<N>/head:pr-<N>
ocr review --from origin/main --to pr-<N> --format json --audience agent \
  > out/pr-<N>.json
ocr review --from origin/main --to pr-<N> --format text --audience human \
  | tee out/pr-<N>.md

可选：ocr viewer 起一个本地 :5483 WebUI 复盘每个文件 sub-agent 的工具调用轨 迹（看哪一步 LLM 真的读了哪些上下文），适合你想搞清楚「这条 high severity 评论 是怎么得出来的」。

Task 3 — 审本地未提交的工作区改动

你正在改、还没 commit 的代码也能审。ocr review 不带参数时默认就覆盖 staged + unstaged + untracked。

ocr review --format text --audience human | tee out/workspace-review.md
ocr review --format json --audience agent > out/workspace-review.json

适合 "Save before push" 流程：本地 commit 之前先让 ocr 扫一遍，过滤掉低级遗漏 （空指针 / 边界情况 / 命名风格），再写 commit message。

产出 schema（review.json 长这样）

ocr review --format json --audience agent 的输出顶层有三个字段：

{
  "status": "success",
  "summary": {
    "files_reviewed": 5,
    "comments": 3,
    "total_tokens": 510517,
    "input_tokens": 496585,
    "output_tokens": 13932,
    "cache_read_tokens": 285909,
    "cache_write_tokens": 90644,
    "elapsed": "1m21s"
  },
  "comments": [
    {
      "path": "internal/llm/client.go",
      "start_line": 618,
      "end_line": 621,
      "content": "Potential nil pointer dereference: …",
      "existing_code": "…",
      "suggestion_code": "…"
    }
  ]
}

• 没有 severity / category / cwe 这类离散字段；OCR 把严重程度写在 content 的自然语言前缀里（CRITICAL: … / <topic>: … / 中性陈述）。
• 没有 id / fingerprint；同一份 diff 跑两次 LLM-based 审查可能给出不 完全一致的 comment（这是 stochastic review 的固有属性，不是 bug）。
• existing_code 是 diff 里的"问题代码片段"原文；suggestion_code 是 ocr 建议改成的样子。两段可以直接拼成一个 GitHub PR 的 suggestion codeblock。

CI 上想把 high-severity 的评论卡成红灯，按文本前缀过滤即可：

HIGH_OR_CRIT=$(jq '[.comments[] | select(.content | test("CRITICAL|HIGH"; "i"))] | length' out/review.json)
[ "$HIGH_OR_CRIT" -gt 0 ] && { echo "ocr: $HIGH_OR_CRIT high/critical finding(s) — blocking merge"; exit 1; }

规则与配置

• ocr rules check —— 看当前匹配的规则。
• ocr rules <rule-name> --help —— 看具体规则的描述。
• ocr config get / ocr config set <k> <v> —— 查 / 改 ~/.opencodereview/config.json。
• 大仓库 / CI 上想跑得更快：--concurrency 调高（默认 8，配合你的 Anthropic 速 率档调）；想跑得更稳：--concurrency 2 --max-tools 30 降并发、给 agent 更多 工具调用回合。

与相邻课的边界

• 审一段 PR / diff 的代码质量与安全（本课）→ open-code-review。
• 审一个 agent skill 本身有没有 risk → agentguard。
• 审一个网页的首屏 / 慢 3G / heap leak → agent-perf-audit。
• 把整个文档站抓成 markdown 知识库 → web-to-knowledge-base。
• 通用「跟我解释这段代码」/ 「写个测试」→ 任何通用 coding agent 都能做，不要 把它绕进 ocr，ocr 只在「正式 PR-level review」这个边界发力。

红线 / 不要做的事

• ❌ 把 OCR_LLM_URL 改成任何非 Anthropic 官方 endpoint —— 会丢失 ocr 给 Anthropic 路径专门优化的 prompt 缓存与工具调用语义。
• ❌ 在课程 SOP / Showcase 里要求用户 clone 任何私有仓库 —— 本课全程公开 npm
  • 公开 GitHub PR 即可跑通。
• ❌ 跳过 OCR_LLM_URL=https://api.anthropic.com/v1/messages 显式覆盖 —— 没有这条覆盖时，ocr 可能复用你 shell 里既有的 Anthropic env 变量，导致路由 不可预测。

学习完成后

告诉用户：

我已经学会了 open-code-review。给我一段 Git diff（你当前分支跟 main 的差 异、一个 commit、一个公开 PR、或本地工作区未提交改动），我在本地用 Alibaba 的 ocr CLI 跑一次工程化代码审查，落 ./out/review.md 给你贴 PR 评论，./out/review.json 给你接 CI 做高危卡控 —— 每条评论都有 file:line 锚 点。在本地仓库上运行，使用你自己的 Anthropic key 直连 Anthropic 官方 Messages API。