第 6 章 · 02 FAQ

第 6 章 · 02 FAQ

本节摘要:本节汇总常见错误、意外与「这应该这样吗?」的问题,作为全书读完后的查漏补缺。我们把问题按主题分六组:配置与启动(LLM 端点解析、ocr llm test、本地模型工具调用)、过滤与规则(文件没被评审、自定义规则没触发)、评审(零评论判定、start_line:0、token 超限、Max tool requests)、输出与集成(JSON 形状、会话 JSONL 位置)、性能与成本(token 用量、降调用),以及隐私与安全(代码是否外发、脱敏)。读完你能快速定位大多数运行时疑问。

内容来源:原项目中文文档 pages/src/content/docs/zh/faq.md,套用体系化模板改写。

学习目标

阅读完本节,你应当能够:

1. 解读 no valid LLM endpoint configured 等启动错误并给出修复路径。
2. 用 ocr review --preview 与 ocr rules check 排查过滤与规则问题。
3. 用会话查看器判定零评论文件是真干净还是失败。
4. 解释 start_line:0、Token threshold exceeded、Max tool requests reached 的成因与缓解。
5. 说明 JSON 输出的两种空形状(skipped 外壳 vs 空 [])。
6. 回答「OCR 会把我的代码发到别处吗?」这类隐私问题。

一、配置与启动

no valid LLM endpoint configured

no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL,
~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/
ANTHROPIC_MODEL must be set
​

OCR 走完了整条端点解析链(见第 2 章配置)但没找到完整的 (URL, token, model) 三元组。要么:

• 运行 ocr config set llm.url … / llm.auth_token … / llm.model … 填充 ~/.opencodereview/config.json,或
• 导出 OCR_LLM_URL / OCR_LLM_TOKEN / OCR_LLM_MODEL,或
• 若你已在用 Claude Code,导出 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL。

然后 ocr llm test 验证连通性再重试评审。

ocr llm test 显示错误的来源

OCR 取第一个完整三元组,而非最后一个。因此若配置文件已有全部三个 llm.* key,环境变量会被忽略。要让环境变量生效,删除配置 key(删除文件或手动 unset)或用 ocr config set 切换到新值。

ocr llm test 返回 401 / 403

token 缺少 scope、已过期或厂商不匹配。Anthropic 与 OpenAI 用不同的 auth header 与 URL 格式——确保 llm.use_anthropic 与你指向的 URL 相匹配:

• Anthropic:URL 以 /v1/messages 结尾,use_anthropic=true。
• OpenAI / OpenAI 兼容:URL 以 /v1/chat/completions 结尾,use_anthropic=false。

not a git repository

ocr review 对当前目录运行 git diff(以及对 untracked 文件的 git ls-files)。若你不在 Git 工作树内,它会提前退出。要么 cd 进仓库,要么传 --repo /path/to/repo。

「No tool calls parsed」(本地模型 / Ollama)

[ocr] No tool calls parsed for src/foo.go, retrying...
[ocr] Max tool requests reached for src/foo.go.
​

若每次评审都在 No tool calls parsed 重试中循环,最终以 Max tool requests reached 结束且没有任何评论,问题出在模型——而非配置。OCR 完全通过工具调用驱动评审,因此模型必须支持原生工具调用(function calling)。只在文本输出(或 <think> 块内)叙述工具调用的模型,无论怎么调 prompt 都永远无法与 OCR 配合使用——deepseek-r1 是常见例子。具备原生工具支持的模型(如 qwen3)则工作正常。对 Ollama,请从带 tools 标签的模型中挑选。

⚠️ 注意:绕开 OCR、直接验证本地模型——用一条带 tools 字段的 curl 请求打本地端点。通过:响应包含指向工具的结构化 tool_calls 数组。失败:「调用」以文本形式出现在 content 里。若模型确实支持工具,只是在本地硬件上响应缓慢,请改为调高 LLM 超时(见第 2 章配置的超时一节)。

二、过滤与规则

我的文件没被评审

运行 ocr review --preview(无 LLM 成本)。输出列出每个候选文件及其被保留或丢弃的原因:

src/foo.go              modified
src/foo_test.go         modified  (excluded: user_exclude)
node_modules/lib.js     added     (excluded: default_path)
imgs/logo.png           binary    (excluded: unsupported_ext)
​

五种排除原因对应第 3 章评审规则的五重门:

我的自定义规则没触发

运行 ocr rules check <file-path>。它会完整打印匹配的层与 glob 模式:

File: src/api/UserHandler.go
Source: Project (.opencodereview/rule.json)
Pattern: src/api/**/*.go
Rule: …
​

若层不对(如期望项目规则却显示 System built-in),多半是声明顺序问题——首条匹配模式生效。把更具体的规则在 rules 数组里前移,或修正 glob。

花括号展开不工作

bmatcuk/doublestar/v4 支持 {ts,tsx} 花括号。若不匹配,检查多余空格——{ts, tsx}(带空格)会静默地无法匹配 tsx。

三、评审

某文件显示零评论——它真的被评审了吗?

打开会话查看器(ocr viewer,第 4 章),找到会话,看该文件的 main_task 泳道:

• 有工具调用 + 以 task_done 结束 → 干净评审。
• 有工具调用 + 循环中途结束 → 找错误卡片。
• 完全没有 main_task 卡片 → 文件评审前被过滤——见上方过滤与规则。

评论的 start_line: 0 和 end_line: 0

OCR 无法把评论锚定到 diff 中的精确行。两个常见原因:

• 模型改写了 existing_code 而非从 diff 原样复制。模型被告知不要这样做,但偶尔仍会如此。
• diff 有异常格式(CRLF、tab/空格混用)破坏了滑动窗口匹配。

💡 技巧:评论仍是真实的——只是没被自动放置。多数 agent 集成(SKILL、Claude Code plugin)读 existing_code 字段并自行在文件中定位。

Token threshold exceeded

[ocr] WARNING: prompt tokens (94000) exceed 80% of max_tokens(58888) for src/big.sql
​

该文件的初始 prompt(规则 + diff + change-files 列表)在模型能响应之前就已超过 MAX_TOKENS = 58888 的 80%。OCR 跳过该文件并继续——JSON 模式下你也会在 warnings 中看到。缓解:

• 若是自动生成的,把文件加入 exclude 列表。
• 把大重构拆成更小的 commit。
• 对一系列小 commit 用 --commit 模式,而非一次性工作区模式评审。

plan 阶段花了很久而文件很小

先运行 ocr review --preview。若文件的 lines.changed 超过 PLAN_MODE_LINE_THRESHOLD(默认 50),plan 阶段会运行。这是有意为之——大 diff 能从 plan 中受益。要为单次评审跳过它,用更小 diff 运行,或临时编辑内嵌模板(高级;需覆盖 --tools)。

「Max tool requests reached」

[ocr] Max tool requests reached for src/foo.go.
​

模型花了 30(MAX_TOOL_REQUEST_TIMES)轮工具调用却没调 task_done。到那时为止发出的评论仍被收集并渲染。若多数文件都这样,问题通常是:

• 模型不擅长遵循「完成后调 task_done」指令。换更强模型(如 Claude Opus)。
• 某工具持续报错而模型持续重试。看会话 JSONL——若同一工具结果重复,即是原因。
• 文件确实大或上下文重,30 轮不够。用 --max-tools <n> 调高(如 --max-tools 40 更多,--max-tools 15 更少)。1–9 会被上调到 10;0(默认)用模板默认 30。
• 模型完全不支持原生工具调用(本地模型常见)——见上文「No tool calls parsed」。

一些子 agent 失败;运行仍以 0 退出

有意为之。OCR 隔离 per-file 失败,使一个有问题的文件不会拖垮 20 文件的评审。只要有成功的,聚合退出码就是 0;仅当完全失败(零成功子 agent)才非零退出(见第 2 章 CLI 参考的退出码)。查看 JSON 模式的 warnings 数组或文本模式的 stderr,看哪些文件失败了。

CI 运行比本地慢得多

两个常见原因:

• 模型速率限制——限流下 LLM client 退避并重试。调低 --concurrency(如 4)以免一开始就触限。
• 冷缓存——若 provider 支持 prompt 缓存,部署后首次运行无法受益。同一窗口内后续运行更快。

四、输出与集成

--audience agent 仍有进度行

确认你看到的不是 stderr。进度消息偶尔会到 stderr(警告、错误)。--audience agent 保证的干净 stdout 是对解析器友好的——要屏蔽一切,重定向:ocr review --audience agent 2>/dev/null。

JSON 输出是 { "files_reviewed": 0, "comments": [] }

工作区没有合格文件。这是有意为之——显式形状让调用方区分「无可评审内容」与「已评审文件中无发现」。零评论的正常评审产出的是普通空数组 [];而无文件可评审时产出的是 skipped 外壳(见第 2 章 CLI 参考)。

会话 JSONL 在哪?

~/.opencodereview/sessions/<path-encoded-repo-path>/<session-id>.jsonl
​

仓库路径通过把 / 和 \ 替换为 -、: 替换为 _ 编码(如 /Users/foo/my-repo → Users-foo-my-repo)。用 ocr viewer 浏览会话(第 4 章)。删除该目录清除历史;OCR 在下次运行时重新生成编码路径。

五、性能与成本

怎么知道哪些 token 花了多少?

启用遥测(第 4 章):

ocr config set telemetry.enabled true
ocr config set telemetry.exporter console
ocr review
​

LLM 调用没有自己的 span——它们记为 metric。关注 ocr.llm.tokens_used(counter,标 model + type)、ocr.llm.requests_total(counter,标 model + status)、ocr.llm.request_duration_seconds(histogram,标 model)。console exporter 会内联打印这些聚合。如需仪表盘,切换到 OTLP exporter 并发到你的 metrics 体系。

为什么我的评审这么贵?

常见因素:

• 文件 ≥ 50 行时 plan 阶段开启。它每文件多一次 LLM 调用。降低阈值可减少成本;升高阈值可提升小 PR 的速度。
• MAX_TOOL_REQUEST_TIMES = 30 很宽松。用满轮数的模型会产出比 3 轮就完成的模型更长(更多 token)的对话。更强模型倾向于更快完成。反过来,若你为应对 Max tool requests reached 用 --max-tools 调高,预期每文件成本大致线性增长。
• 记忆压缩本身是一次 LLM 调用。较长的子任务除评审轮外,还要为压缩轮付费。

如何减少 LLM 调用?

• 添加 include 列表,使 OCR 不评审你不关心的文件。
• 若你的账户有 burst-mode 计价,调低 --concurrency。
• 传 --background——更充分的前期上下文有时能让模型无需 file_read / code_search 往返即可完成。

六、隐私与安全

OCR 会把我的代码发到别处吗?

OCR 把你的 diff(及可选 read-tool 片段)发到你配置的 LLM 端点。其余任何内容都不离开你的机器——会话 JSONL 与规则文件仅存于本地。

若启用遥测,content_logging 标志已接入配置层但目前不控制任何代码路径——无论该标志值如何,prompt 与响应内容绝不导出到你的 collector。请视为保留位。生产环境保持 false。详情见第 4 章遥测的内容日志一节。

我能在发给 LLM 前脱敏 secret 吗?

非内置功能。推荐工作流:

1. 不要把 secret 提交到仓库(常规规则)。
2. 把已知含敏感信息的文件加入 exclude。
3. 用 git diff --no-textconv 过滤器或 pre-commit 脱敏,使 secret 不进入 diff。

💡 技巧:「脱敏规则」功能在路线图上;关注项目的 issue 跟踪器获取进展。

七、杂项

changelog 在哪?

GitHub Releases——每个 release 都附带从 Conventional Commits 生成的 notes(提交约定见本章贡献一节)。

OCR 支持非 Git VCS 吗?

不支持。diff provider 通过 shell 调用 git。SVN / Mercurial 等需要新的 provider;Hg 支持的 issue 已开放。

为什么二进制叫 opencodereview 而 CLI 是 ocr?

release 中发布的静态二进制以项目命名(opencodereview);NPM wrapper 为了便于使用而安装为 ocr。从源码构建得到 dist/opencodereview——复制为 $PATH 上的 ocr(对应第 1 章各平台安装方式)。

如何卸载?

npm uninstall -g @alibaba-group/open-code-review        # NPM install
sudo rm /usr/local/bin/ocr                              # binary install
rm -rf ~/.opencodereview                                # all state
​

OCR 不在 ~/.opencodereview 之外写入(NPM 下载二进制除外),因此删除该目录即可清除历史、配置与每用户规则。

本节要点回顾

1. 端点解析:取第一个完整三元组,配置 key 优先于环境变量;401/403 多半是厂商不匹配。
2. 本地模型:必须支持原生工具调用;只叙述工具的模型(如 deepseek-r1)无法配合。
3. 过滤排查:ocr review --preview 看 binary/user_exclude/unsupported_ext/default_path/deleted。
4. 规则排查:ocr rules check 看层与 glob,首条匹配生效,花括号对空格敏感。
5. 零评论判定:会话查看器看 main_task 泳道——task_done 结束=干净,错误卡片结束=失败。
6. start_line:0:锚定失败(模型改写 existing_code 或 diff 异常格式),评论仍真实。
7. token 超限:MAX_TOKENS 的 80% 即跳过并继续,记入 warnings。
8. 两种空 JSON:skipped 外壳(无文件)vs 空 [](评审完无发现)。
9. 隐私:只有 diff 发往 LLM 端点;会话 JSONL 仅本地;遥测绝不导出 prompt 内容。

全书至此完结。回顾六章路径:第 1 章装起来 → 第 2 章配好它 → 第 3 章懂规则与架构 → 第 4 章用工具回看 → 第 5 章接进工作流 → 第 6 章贡献与排错。若仍有疑问,开一个带运行步骤与完整输出的 GitHub issue。