一、配置放在哪里
长期使用的模型连接放配置文件,每次扫描的范围和限额放命令中。
流程图源码
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 引导配置,或将下面示例写入用户配置,替换地址、模型和密钥:
{
"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。已有配置可单独修改:
ocr config set language zh-CN示例使用 OpenAI Chat Completions 接口;Responses 接口填 openai-responses,Anthropic 接口填 anthropic。协议须与服务端一致。
内置供应商用 providers,自定义供应商用 custom_providers。设置了 provider 后,不再读取旧式 llm 连接。
未指定 --provider 时,采用下图中首先找到的完整连接:
流程图源码
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。
三、规则怎么选择
对每个文件,首次匹配到的规则生效:
流程图源码
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 路径 |
| 调整文件任务并发 | --concurrency | 8,不是全部模型请求的统一并发上限 |
| 提供业务背景 | --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:
# 确认版本;连接检查会实际调用模型
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 当前没有完整覆盖清单,原始请求记录也未关联到具体文件。
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 项目摘要;新增配置没有增加网站模型分析步骤。回复维持简体中文。