场景速查总表
| 场景 | 核心命令 |
|---|---|
| 场景：接入 CI 流水线 | — |
| 场景：配置模型与规则 | 配置模型：ocr config provider 选择内置 provider（如 DashScope/DeepSeek）或按自定义端点配置 → 随后 ocr config model 指定模型并自动测连通 |
| 场景：扩展审查能力 | — |
| 场景：免 Key 委托审查 | 查看可审查清单：运行 ocr delegate preview --format json，确认当前仓库哪些文件可进入委托范围 |
| 场景：审查 PR/分支变更 | 本地审查工作区改动：在仓库目录运行 ocr review，工具自动收集当前改动并产出评论 |
| 场景：审计陌生代码库 | 整库扫描：在仓库根目录运行 ocr scan，等待扫描完成并查看逐文件评论 |
场景详解
场景：接入 CI 流水线
使用场景场景索引让审查自动跑在每个 MR/PR：GitHub Actions 一步复用、GitLab/Gerrit 等加 post_review.py 回贴评论
适用情况
让 AI 审查自动跑在每次 MR/PR 上，无需人工触发，是规模化落地的标准形态
GitHub Actions：uses: alibaba/open-code-review@main，三个必填输入 llm_url / llm_auth_token / llm_model，Anthropic 协议模型需加 llm_use_anthropic
GitLab：在 .gitlab-ci.yml 中配置审查作业，结合 post_review.py 把审查结果回贴为 discussion 评论
为什么用
人工 review 无法保证每个 MR 都覆盖，CI 自动化把审查变成合并的必经环节而非可选项
回贴讨论（GitLab discussion / GitHub comment）让审查结论与代码行绑定，开发者在原处即可处理
常见坑
- 把 llm_auth_token 明文写进工作流文件而非 secrets 注入，凭据随仓库泄漏
- 布尔输入不写字符串字面量：llm_use_anthropic: true 被 YAML 解析为布尔，action 收到类型错误而静默失败
场景：配置模型与规则
使用场景场景索引首次上手必做：选 provider/模型/API Key，按项目定制规则（rule.json）、过滤路径、调并发与预算
命令速查
配置模型：ocr config provider 选择内置 provider（如 DashScope/DeepSeek）或按自定义端点配置 → 随后 ocr config model 指定模型并自动测连通设置语言：ocr config set language zh-CN，让审查评论以中文输出临时规则：单次命令加 --rule，如 ocr review --rule '禁止硬编码密钥'，不污染仓库配置验证规则：运行 ocr rules check，确认规则命中目标文件，输出与实际匹配一致后再正式审查适用情况
首次上手必做步骤：配置模型提供方与审查规则，决定审查的语言、范围与标准
ocr config provider 选择模型提供方：内置 DashScope、DeepSeek 等选项，也支持自定义端点接入任意兼容服务
ocr config model 配置具体模型，工具会自动测试连通性，失败即反馈，避免配错模型名
为什么用
审查质量的上限由模型与规则决定：不配置模型则无法运行，不配置规则则审查无差异化
项目级与全局级分层让『团队标准』与『个人偏好』共存：全局规则兜底，项目规则精确
常见坑
- 跳过 ocr config model 的连通性测试直接使用，配错模型名/端点后审查静默失败，排查成本高
- doublestar glob 写错（如用单 * 期望匹配多级目录），include/exclude 不生效，规则范围失控
场景：扩展审查能力
使用场景场景索引规则不够用？MCP 接入外部工具、自定义规则文件、--rule 临时规则、委托模式喂给任意 Agent
适用情况
内置规则不够用时提供四条扩展路径：MCP 接入、自定义规则文件、--rule ad-hoc 规则、委托模式
MCP 接入：config.json 的 mcp_servers.<name> 配置外部工具，支持 stdio（本地进程）与 remote（远程服务）两种模式，让审查过程调用外部工具能力
自定义规则文件：内置覆盖 10+ 语言，专项场景（特定框架/合规要求）可补写专属规则文件
为什么用
单一内置规则无法覆盖所有团队规范与框架特性，扩展性是工具长期可用的前提
MCP 生态让审查能联动外部工具（如安全扫描器、数据库 schema 检查），审查从『读代码』升级为『查事实』
常见坑
- 把长指令直接内联进 rule.json 的字符串值，JSON 转义与换行处理困难，且评审修改频繁改配置
- MCP 工具地址配置为不可信远程端点，审查数据可能外泄，remote 模式需确认信任边界
场景：免 Key 委托审查
使用场景场景索引没有 LLM API Key 或想用宿主 Agent 模型：ocr delegate preview/rule 输出 spec，编码 Agent 自己审
命令速查
查看可审查清单：运行 ocr delegate preview --format json，确认当前仓库哪些文件可进入委托范围获取审查规则：运行 ocr delegate rule src/main.go src/handler.go，得到针对这两个文件的规则文本嵌入插件：在 QCA / Claude Code 插件中内嵌 ocr delegate 命令，实现『宿主模型 + OCR 规则』的混合审查流适用情况
面向没有 LLM API Key 或希望复用宿主 Agent（如 QCA、Claude Code）模型能力的场景
ocr delegate preview --format json 输出当前可审查的文件清单，供委托前确认范围
ocr delegate rule src/main.go src/handler.go 输出针对指定文件的审查规则，作为委托审查的标准
为什么用
很多开发者没有直接可用的 LLM API Key，或已有宿主 Agent 的模型额度，重复付费不划算
把『规则生成』与『审查执行』分离：OCR 负责高质量规则，宿主 Agent 负责执行，各用所长
常见坑
- 把 delegate preview 当审查结果：preview 只是文件清单，真正的审查结论仍需 Agent 按规则执行
- 用宿主 Agent 直接审查而不取 delegate rule，等于放弃 OCR 沉淀的审查规则，质量回到裸模型水平
场景：审查 PR/分支变更
使用场景场景索引日常审查入口：合并基准模式审 feature 分支、单 commit 审查、GitHub PR 上自动触发
命令速查
本地审查工作区改动：在仓库目录运行 ocr review，工具自动收集当前改动并产出评论审查分支 diff：ocr review --from main --to feature-branch，无需 checkout 即可审查任意分支间的变更审查单个 commit：ocr review --commit abc123，适合对历史提交定点复核适用情况
日常审查入口：对当前工作区、分支 diff 或指定 commit 进行 AI 代码审查，是使用频率最高的场景
支持三种触发方式：ocr review（审查当前工作区改动）、ocr review --from main --to feature-branch（审查分支间 diff）、ocr review --commit abc123（审查单个 commit）
GitHub PR 自动触发：examples/github_actions/ocr-review.yml 监听 pull_request_target 的 opened/synchronize/reopened 事件，以及 issue_comment 中出现 '/open-code-review' 命令时触发
为什么用
PR 审查是代码质量的咽喉，手动逐行 review 耗时且易漏，AI 预审把高频问题挡在合并前
分支/commit 级触发让审查可以发生在合并前的任意时点，而不仅限于 CI 阶段
常见坑
- 在 GitHub Actions 中把触发权限放开给所有人（不加 MEMBER/OWNER/COLLABORATOR 限制），外部贡献者可用评论触发你的工作流消耗 token
- 忽略并发组配置导致同一 PR 多次触发并发审查，评论重复且账单翻倍
场景：审计陌生代码库
使用场景场景索引无 git 历史/无有意义 diff 时：全文件扫描，按语言/目录分束，DEDUP 去重，项目级总结
命令速查
整库扫描：在仓库根目录运行 ocr scan，等待扫描完成并查看逐文件评论限定范围：ocr scan --path internal/agent，只扫指定目录，快速聚焦目标模块分束控制规模：ocr scan --batch by-language 按语言分批，或 --batch by-directory 按目录分批，避免单批过大适用情况
面向无 git 历史或无有意义 diff 的仓库：接手遗留代码、安全审计、整体摸底时用扫描模式而非 diff 模式
ocr scan 扫描整个仓库，ocr scan --path internal/agent 可限定子目录，聚焦特定模块
--batch 支持 by-language 或 by-directory 分束：按语言或目录分批处理，控制单次扫描的规模与成本
为什么用
陌生代码库没有『变更』概念，diff 模式无从谈起，必须整库扫描建立基线
全库一次性送入模型不可行，by-language/by-directory 分束把扫描切成可管理的批次
常见坑
- 对超大仓库不做 --batch 直接全量扫描，单批输入超限导致任务失败或成本爆炸
- 忽略 DEDUP 去重，跨文件重复问题刷屏，掩盖真正的高价值发现