第 2 章 · 02 CLI 参考

第 2 章 · 02 CLI 参考

本节摘要:本节是 ocr 命令行的完整参考。我们把每个子命令(review、rules、config、llm、viewer、session、version)的参数、默认值、退出行为列清,并重点讲透主命令 ocr review 的三种模式(工作区、区间、commit)、Text/JSON 两种输出、退出码语义,以及恢复中断评审的方法。读完你能为任何场景拼出正确的 ocr 命令,并为第 5 章的 CI 集成打好基础。

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

学习目标

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

1. 列出 ocr 的七个子命令及其别名、作用。
2. 说明 ocr review 的三种 diff 模式(工作区/区间/commit)及触发方式。
3. 读懂 --format json 输出的外壳结构(status/summary/comments/warnings/session_id)。
4. 用 --resume 恢复中断的区间或单 commit 评审。
5. 解释 --audience 与 --format 为何是正交的两个开关。
6. 解读 ocr review 的退出码语义。

一、命令总览

OpenCodeReview - AI-Powered Code Review CLI

Usage:
  ocr [command]

Commands:
  review, r              Start a code review
  rules                  Inspect and debug review rules
  config                 Manage configuration settings
  llm                    LLM utility commands
  viewer                 Start the WebUI session viewer
  session, sessions      List and inspect saved review sessions
  version                Show version information
​

各子命令与别名速查:

ocr 和 ocr -h 打印顶层用法。每个子命令也接受 -h / --help。

二、ocr review(主命令)

主命令。解析 Git diff,分发 per-file 子 agent,收集评审评论并打印。

概要

ocr review [flags]
ocr r      [flags]   (alias)
​

若不传任何参数,OCR 以工作区模式运行——评审当前目录所在仓库中所有 staged + unstaged + untracked 变更。

参数

⚠️ 注意:模式参数互斥——传 --from/--to,或 --commit,或都不传(工作区模式),混用会直接报错。--resume 仅支持区间或单 commit 评审,不能与 --preview 同时使用。

三种模式

工作区模式(默认)

ocr review
​

OCR 从两条 git 命令组装工作树变更:

• 通过 git diff HEAD 获取已跟踪变更(staged + unstaged 合并对比 HEAD;若为空则回退到 git diff --staged)。
• 通过 git ls-files --others --exclude-standard 获取 untracked 文件,从磁盘读取并作为整文件新增处理。

这通常是 commit 前你想要的。如需更小的范围,请选择性暂存。

区间模式

ocr review --from main --to feature-branch
​

OCR 计算 merge-base(main, feature-branch)..feature-branch,因此你只看到 feature 分支引入的 diff——而非分支切出后落到 main 上的无关变更。

Commit 模式

ocr review --commit abc123
ocr review -c abc123
​

评审 git show abc123 产生的 diff(即该 commit 引入的变更)。

💡 技巧:CI 里几乎都用区间模式(--from origin/main --to HEAD),让评审聚焦本次 PR 引入的变更。详见第 5 章。

恢复中断的评审

每次 ocr review 都会在 ~/.opencodereview/sessions/ 下保存本地会话日志。正常完成的文本输出只展示评审结果,不打印 session ID;可使用 ocr session list/show 查找已保存会话,或用 --format json 在机器可读输出中获取 session_id。如果区间或单 commit 评审被中断,先列出已保存会话,再从与当前评审目标一致的会话恢复:

ocr session list
ocr session show <session-id>
ocr review --from main --to feature-branch --resume <session-id>
ocr review --commit abc123 --resume <session-id>
​

恢复逻辑是严格的:

• 工作区评审不能恢复。
• 区间评审必须使用相同的 --from 和 --to。
• 单 commit 评审必须使用相同的 --commit。
• --preview 和 --resume 不能同时使用。

输出

Text(默认,--audience human)

评审运行时流式输出进度行,随后每条评论一个块(带 path:start-end 的暗色 Unicode 分隔头、按 100 列折行的评论正文,以及(存在时)建议替换的彩色内联 diff)。运行结束时 stdout 末尾打印一份摘要:

[ocr] 17 file(s) changed, reviewing 9 in /path/to/repo
[ocr] Skipping image.png — filtered by path/extension rules
[ocr]   ▶ file_read "src/foo.go"
[ocr]   ✔ file_read (12ms)
[ocr] Plan completed for src/foo.go
…

─── src/foo.go:42-47 ───
Concurrent map access without a lock — wrap with sync.RWMutex.

- m[k] = v
+ mu.Lock(); defer mu.Unlock(); m[k] = v

…
[ocr] Summary: 9 file(s) reviewed, 14 comment(s), ~21344 token(s) used (input: ~18012, output: ~3332), 1m12s elapsed
​

Text(agent,--audience agent)

评论输出相同,但通过一个内部可静默的 stdout writer 屏蔽进度行。在 CI / 流水线中交给另一个 agent 时使用。

JSON

ocr review --format json --audience agent
​

{
  "status": "success",
  "summary": {
    "files_reviewed": 9,
    "comments": 1,
    "total_tokens": 21344,
    "input_tokens": 18012,
    "output_tokens": 3332,
    "elapsed": "1m12s"
  },
  "comments": [
    {
      "path": "src/foo.go",
      "content": "Concurrent map access without a lock — wrap with sync.RWMutex.",
      "start_line": 42,
      "end_line": 47,
      "existing_code": "m[k] = v",
      "suggestion_code": "mu.Lock(); defer mu.Unlock(); m[k] = v",
      "thinking": "Looking at line 42, the map …"
    }
  ]
}
​

顶层字段:

当没有文件可评审时,JSON 模式会发一个 skipped 外壳,以便调用方区分「无变更」与「无发现」:

{
  "status": "skipped",
  "message": "No supported files changed.",
  "comments": []
}
​

退出码

⚠️ 注意:非致命警告(单个子 agent 失败、某文件超过 token 阈值等)内联打印;JSON 模式下会加入 warnings 数组。只要有成功的子 agent,聚合退出码就是 0——这是有意为之,避免一个有问题的文件拖垮整个评审。

三、ocr session(会话管理)

列出和查看保存在 ~/.opencodereview/sessions/ 下的本地评审会话日志。可用它查找 session ID、查看逐文件检查点状态,并恢复中断的区间或单 commit 评审。

ocr session <sub-command>
ocr sessions <sub-command>   (alias)

Sub-commands:
  list, ls    List recent review sessions for the current repo
  show <id>   Show one session's metadata and per-file items
​

ocr session list

ocr session list
ocr session list --limit 50
ocr session list --json
​

ocr session show

ocr session show <session-id>
ocr session show --json <session-id>
ocr session show --repo /path/to/repo <session-id>
​

💡 技巧:会话的浏览器可视化用 ocr viewer(第 4 章),ocr session 子命令适合脚本化检索。

四、ocr rules(规则自查)

规则自查。只有一个子命令:

ocr rules check [flags] <file-path>

Flags:
  --repo <path>    Git repository root (default: current dir)
  --rule <path>    Path to a custom rule JSON file
​

对给定文件路径,OCR 会:

1. 遍历四层规则链(custom → project → global → system)。
2. 取第一条匹配。
3. 打印来源层、匹配的 glob 模式,以及解析出的规则文本。

$ ocr rules check src/main/java/com/example/Foo.java
File: src/main/java/com/example/Foo.java
Source: System built-in
Pattern: **/*.java
Rule:
────────────────────────────────────────
<contents of internal/config/rules/rule_docs/java.md>
────────────────────────────────────────
​

可用于排查「为什么我的自定义规则没触发?」——完整的优先级说明见第 3 章评审规则一节。

五、ocr config(配置管理)

将 key 持久化到 ~/.opencodereview/config.json,并提供交互式配置 TUI。四个子命令:

ocr config set <key> <value>
ocr config unset custom_providers.<name>   Delete a custom provider
ocr config provider                        Interactive provider setup
ocr config model                           Interactive model selection
​

• set——非交互式写入单个配置值。
• unset——删除一个自定义 provider。仅支持 custom_providers.<name>。若删除的是当前启用的 provider,则 provider 和 model 被清空(运行 ocr config provider 重新选择)。
• provider——启动交互式 provider 配置 TUI(无额外参数;非交互式请用 ocr config set provider <name>)。
• model——启动交互式 model 选择 TUI(无额外参数;非交互式请用 ocr config set model <name>)。

完整的 key 参考、schema 与示例见本章配置一节。

六、ocr llm(LLM 工具)

LLM 工具命令。两个子命令:

ocr llm <sub-command>

Sub-commands:
  test         Send a test conversation to the configured LLM model
  providers    List all built-in LLM providers
​

ocr llm test

ocr llm test
​

以与 ocr review 完全相同的方式解析 LLM 端点,发送一条预置 chat 请求,并打印:

Source: <which strategy was used>
URL:    <endpoint URL>
Model:  <effective model>
<the model's reply>
✓ Connection test successful
​

非零退出意味着端点未完整配置,或请求失败(网络 / 鉴权 / 模型错误)。错误信息会指明具体是哪一种。

ocr llm providers

ocr llm providers
​

以三列表格列出每个内置 LLM provider:

Built-in providers:
  NAME        PROTOCOL    BASE URL
  ----        --------    --------
  anthropic   anthropic   https://api.anthropic.com
  …
​

随后是一条提示,可用 ocr config provider 交互式配置,或用 ocr config set provider <name> 非交互式配置。

七、ocr viewer 与 ocr version

ocr viewer

ocr viewer [flags]

Flags:
  --addr <address>   listen address (default: localhost:5483)

Examples:
  ocr viewer                     # start on default port
  ocr viewer --addr :3000        # bind to all interfaces on port 3000
​

启动一个内嵌 HTTP 服务器,读取 ~/.opencodereview/sessions/...,并以浏览器友好的 UI 渲染历史评审会话。完整导览见第 4 章会话查看器一节。

ocr version

ocr version
ocr --version
ocr -V
​

打印构建时写入的版本信息、短 Git commit(存在时)、平台(<GOOS>/<GOARCH>)、构建日期(存在时),以及 GitHub URL。

八、提示与注意

• --audience agent 并不隐含 --format json。两者控制不同的事——屏蔽 UI vs 结构化载荷。需要二者兼得时组合使用。
• --background 是提升评审质量最有效的参数之一——从其他 agent 调用时,始终传入需求 / PR 描述。
• 某文件 diff 单独超过 MAX_TOKENS 的 80%(默认 58888)时,会在调用 LLM 前被丢弃。这会记录日志但不会使运行失败。
• 当某文件变更行数低于 PLAN_MODE_LINE_THRESHOLD(50)时,plan 阶段会被自动跳过。

本节要点回顾

1. 七子命令:review、rules、config、llm、viewer、session、version,各有别名。
2. 三模式:工作区(默认)、区间(--from/--to)、commit(--commit),互斥。
3. --format vs --audience:正交两开关——JSON 载荷 vs 屏蔽进度行,CI 里常用 --format json --audience agent。
4. JSON 外壳:status/summary/comments/warnings/session_id,无文件时发 skipped 外壳。
5. 恢复评审:--resume <session-id> 仅支持区间/单 commit,且参数必须与原运行一致。
6. 退出码:0 = 完成(可能零评论/有警告),1 = 致命错误;单子 agent 失败是警告而非失败。
7. --background:提升质量最有效的参数之一,从 agent 调用时务必传入需求/PR 描述。
8. --audience agent 不等于 --format json:需要干净 stdout 的机器可读输出时,二者组合使用。

CLI 讲完了。接下来进入第 3 章核心——评审规则与架构,理解 OCR 凭什么知道哪里有缺陷,以及它从 diff 到评论的端到端流水线如何运作。