跳到正文
Code Review
文档中心 / 扫描配置

文档中心 / 参考文档

扫描配置

本文说明独立 CLI 的 ocr scan,依据官方 v1.13.12 / f921d6a0(版本记录),核对日期:2026-11-18。

一、配置放在哪里

长期使用的模型连接放配置文件,每次扫描的范围和限额放命令中。

流程图可横向滚动查看
流程图源码
mermaid
flowchart LR
    A["用户配置 config.json<br/>模型连接、语言、提示词上限"] --> S["ocr scan"]
    B["规则文件 rule.json<br/>路径匹配、已有审查条款"] --> S
    C["命令参数<br/>范围、并发、时限、预算"] --> S
    D["环境变量<br/>备用连接、请求超时等"] --> S
    S --> R["扫描结果与会话记录"]

用户配置固定为 ~/.opencodereview/config.json(运行 OCR 的用户主目录)。不读取项目内同名配置,也没有 scan --config 或 OCR_CONFIG 入口。

二、模型连接怎么配、用哪一份

运行 ocr config provider 引导配置,或将下面示例写入用户配置,替换地址、模型和密钥:

json
{
  "provider": "my-gateway",
  "language": "zh-CN",
  "custom_providers": {
    "my-gateway": {
      "url": "https://gateway.example.com/v1",
      "protocol": "openai",
      "model": "YOUR_MODEL_ID",
      "api_key": "YOUR_API_KEY",
      "timeout_sec": 600
    }
  }
}

language 控制模型回复语言,简体中文统一使用 zh-CN。当前代码直接把值写入提示词,不强制语言代码,中文 也会被接受;配置中的值为空时使用 English。已有配置可单独修改:

bash
ocr config set language zh-CN

示例使用 OpenAI Chat Completions 接口;Responses 接口填 openai-responses,Anthropic 接口填 anthropic。协议须与服务端一致。

内置供应商用 providers,自定义供应商用 custom_providers。设置了 provider 后,不再读取旧式 llm 连接。

未指定 --provider 时,采用下图中首先找到的完整连接:

流程图可横向滚动查看
流程图源码
mermaid
flowchart TD
    A["config.json"] -->|未提供完整连接| B["OCR_LLM_* 环境变量"]
    B -->|未提供完整连接| C["ANTHROPIC_* 环境变量"]
    C -->|未提供完整连接| D["Shell 配置中的 ANTHROPIC_*"]
    D -->|仍未找到| E["报错:没有可用连接"]

传入 --provider 时直接选择该供应商配置。配置格式错误、已选供应商缺少必填项或取密钥失败时直接报错,不继续回退。

要控制什么生效方式
临时换供应商或模型用 --provider / --model;供应商模式下:--model > 供应商的 model > 顶层 model;切换到另一供应商时不沿用原顶层 model
读取密钥普通内置供应商:api_key > api_key_cmd > 对应密钥环境变量;自定义供应商没有该环境变量回退
使用 OCR 环境连接设置 OCR_LLM_URL、OCR_LLM_TOKEN、OCR_LLM_MODEL;协议取 OCR_LLM_PROTOCOL,未设则看 OCR_USE_ANTHROPIC,再默认 Anthropic
使用 Anthropic 环境连接设置 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL

环境连接的模型也可由 --model 提供。Shell 回退只读变量声明,不执行文件。

环境变量并非统一优先。 已有有效配置时,单改 OCR_LLM_MODEL 不会切换模型;临时换模型用 --model。

三、规则怎么选择

对每个文件,首次匹配到的规则生效:

流程图可横向滚动查看
流程图源码
mermaid
flowchart LR
    A["--rule 指定的 JSON"] -->|未命中| B["扫描根目录<br/>.opencodereview/rule.json"]
    B -->|未命中| C["用户主目录<br/>.opencodereview/rule.json"]
    C -->|未命中| D["程序内置规则"]

rules 保存路径模式和已有条款,可引用 .md / .txt / .markdown 文件。命中的自定义条款默认替代内置规则;在该条规则内设置 merge_system_rule: true 可合并内置规则。

include / exclude 取优先级最高且有过滤设置的一层,再追加 --exclude。Git 忽略、类型和大小筛选仍生效,用 --preview 核对待扫范围和排除提示。

规则须有可追溯来源,缺少条款时保留覆盖缺口;规则被加载,不等于每条问题已有规则引用证据。

四、常用参数怎么选

目的参数默认或用法
选择项目与范围--repo、--path扫描根目录默认当前目录;--path 相对该目录,多个路径用逗号分隔
排除文件、选择规则--exclude、--rule排除模式;已有规则 JSON 路径
调整文件任务并发--concurrency8,不是全部模型请求的统一并发上限
提供业务背景--background可选文本
先看范围--preview不调用模型,不能与 --resume 同用
续跑未完成部分--resume指定旧会话 ID;恢复条件见文末操作说明
保存结果--format、--output默认 text 到终端;支持 json、sarif

在子目录运行 scan,不会自动扫描整个仓库。 扫整个项目时,在项目根目录执行,或用 --repo 指定项目根目录。scan 读取磁盘上的当前文件,也支持非 Git 目录。

时限和 Token 限额分四种:

设置限制什么默认与优先级
--timeout单个文件任务,含规划、主审查及重试15 分钟;0 不限
连接内的 timeout_sec / OCR_LLM_TIMEOUT单次模型 HTTP 请求环境变量 > 所选连接配置 > 300 秒;0 使用默认值
--max-tokens / 顶层 max_tokens每文件任务的提示词 Token 上限正数命令参数 > 用户配置 > 58888;参数 0 沿用后两者
--max-tokens-budget本次扫描累计输入与输出 Token 预算0 不限;正数启用预算检查

提示词检查使用上限的 80% 阈值;主审查单次回复默认最多 16384 Token。总预算可能被已启动任务和辅助调用超出,单文件超时也不是命令总耗时的硬上限。

concurrency、max_tokens_budget 写进 config.json 不生效,需使用命令参数。

<details> <summary>不常用设置(按需查看)</summary>

设置用途与边界
--batch默认 by-language;可选 by-directory、none,none 实际逐文件执行
--max-tools、--max-git-procs每文件工具调用轮数默认 60,只能提高;Git 并发默认 16
--no-plan、--no-dedup、--no-summary跳过规划、去重或摘要阶段
extra_body、extra_headers供应商额外请求参数与请求头;OCR_LLM_EXTRA_HEADERS 合并并覆盖同名头
retry_codes、models额外重试状态码、模型候选;前者不改重试次数,后者可能限制自定义供应商的 --model

内置单文件上限 2 MiB、每批最多 50 个文件;没有普通用户配置入口,提高 --max-tokens 不会放宽文件大小限制。effort 用于 review,scan 未接入 mcp_servers,也没有 --background-file。其他供应商、认证和遥测设置见文末配置源码。

</details>

五、配置好后怎么开始

在项目根目录执行,替换路径。示例使用 4 个文件任务并发、每任务 30 分钟、总预算 100 万 Token:

bash
# 确认版本;连接检查会实际调用模型
ocr --version
ocr llm test

# 预览不调用模型
ocr scan --path src --rule /absolute/path/to/existing-rules.json --preview

# 正式扫描,输出放在项目之外
ocr scan --path src --rule /absolute/path/to/existing-rules.json \
  --concurrency 4 --timeout 30 --max-tokens-budget 1000000 \
  --format json --output /absolute/path/outside-project/scan.json

预览与执行保持范围、规则和提示词上限一致。ocr llm test 检查当前配置的连接,不接受临时的 --provider / --model。完整扫描参数见 ocr scan --help。

六、结果和过程记录在哪里

记录保存方式用途
扫描结果--format json --output 文件路径保存问题、告警和运行统计
会话记录正式扫描自动保存到 ~/.opencodereview/sessions/<目录编码>/<会话ID>.jsonl查看对话、工具调用及文件完成 / 复用 / 失败记录
原始请求记录运行前设置 OCR_RAW_LOGGING=1,保存到 ~/.opencodereview/raw/<目录编码>/<会话ID>.jsonl排查每次 HTTP 请求与响应,默认关闭

目录编码来自扫描根目录的绝对路径;同一项目放在不同目录,记录会分开保存。预览不创建会话;scan 当前没有完整覆盖清单,原始请求记录也未关联到具体文件。

bash
ocr session list
ocr session show 'SESSION_ID'

保留代码版本、命令和配置,核对预览、完成记录及失败原因;零问题或退出成功不等于全部查完。

续跑会复用旧结果,scan 不自动校验规则、业务背景和模型变化。失败恢复、修复后重新检查及报告导出,统一见 scan / review 操作说明。

七、网页工作台如何配置

新建检查沿用上次配置,默认展开版本、范围、排除路径和业务背景;运行限额及高级设置按需展开。参数会随检查保存,执行详情用中文展示,不要求用户理解 CLI 参数名。

页面位置支持的配置交互与默认值
新建检查版本、整个项目 / 指定路径、排除模式、业务背景路径和排除模式用逗号分隔;预览先显示待查与排除原因
模型与运行限额本次模型、文件任务并发、单任务时限、总 Token 预算、请求时限模型留空沿用网站配置;并发 8、单任务 30 分钟、预算不限制、请求 10 分钟;提供常用选项与自定义值
高级检查设置每任务提示词容量、扫描组织方式 / 评审深度容量固定为 58,888,预览和执行一致;scan 默认按语言组织,review 默认标准(2 轮)
网站运行保护无输出等待、单阶段总时限默认 30 分钟无输出时停止,总时限不限制;属于网站进程保护,服务器策略可覆盖
继续未完成并发、单任务时限、预算、请求时限、网站运行保护新增执行并保留旧记录;更换模型、范围、背景、提示词容量或组织方式需新建检查

网页默认值和独立 CLI 默认值分别管理:CLI 并发为 8、任务时限为 15 分钟、请求默认 300 秒。网页明确传入配置;提示词容量保存正数,避免依赖服务器用户配置的后续变化。“不限时”和“不限制”会转换为引擎的 0,提示词容量除外。

由网站统一管理:模型地址、协议和密钥仍使用网站 AI 配置文件及安装说明;规则来自规则库中有来源依据的有效条款,页面显示覆盖缺口,不提供任意规则文件路径。结果格式、输出目录和会话编号由工作台自动管理。

暂不作为页面开关:跳过规划 / 去重 / 摘要、工具轮数、Git 子进程数、额外请求头和请求体、重试状态码、原始 HTTP 日志。它们属于执行流程或运维设置,不作为普通用户每次检查的选择。当前网站仍按已有流程关闭 scan 项目摘要;新增配置没有增加网站模型分析步骤。回复维持简体中文。

相关说明与依据