**OpenCodeReview：scan 原理与流程**

`ocr scan` 以**当前工作区的完整文件为审查对象，每个文件独立审查**。程序负责筛选和分批，模型分析代码、提出问题；批次结束后按需去重，最后生成项目摘要。

本文按官方 **v1.13.8 / 4236c871** 源码说明默认行为，与 [review 流程文档](ocr-review-workflow-2026-11-15.md) 使用同一版本。图中标有 **LLM** 的节点会调用模型。

**整体流程**

```mermaid
flowchart TD
    A["确定范围<br/>整个项目或 --path 指定路径"] --> B["枚举文件、读取全文并筛选"]
    B --> C["程序按固定策略分批"]
    C --> D["处理当前批次<br/>按文件匹配可复用检查点"]
    D -- "需要审查" --> E["LLM：main_task 等<br/>批内逐文件并发审查，详见下图"]
    D -- "可复用" --> R["导入已保存的问题"]
    E --> F["等待本批文件及问题处理完成"]
    R --> F
    F --> G["按需调用 LLM：DEDUP_TASK<br/>合并本批相似问题"]
    G --> H["保存完成或复用文件的检查点"]
    H --> I{"还有下一批？"}
    I -- "有，且允许继续" --> D
    I -- "没有或停止派发" --> J["按需调用 LLM：PROJECT_SUMMARY_TASK<br/>根据已收集问题生成摘要"]
    J --> K["CLI 输出问题与摘要"]
    E -. "记录模型与工具交互" .-> S["会话 JSONL"]
    H --> S
    J -. "记录摘要任务" .-> S
    S --> V["ocr viewer 展示"]
```

图示为正常执行路径；失败与提前停止见后文。没有选中文件时直接结束。

**扫描范围与分批**

默认扫描整个项目，`--path` 可指定文件或目录，多个路径用逗号分隔。Git 仓库中的候选文件包括已跟踪文件，以及未被 Git 忽略的未跟踪文件；读取的是磁盘上的当前内容。

程序按忽略配置、文件类型、路径和大小筛选，跳过二进制、敏感路径等文件。默认单文件上限 **2 MiB**，文件内容超过 `MAX_TOKENS` 的 **80%** 也会跳过；`MAX_TOKENS` 模板默认值为 **58,888**。大文件不会自动拆段审查。`--preview` 可预览筛选结果，不调用模型。

分批由 `--batch` 控制，**不调用 LLM，也不合并文件上下文**：

| 策略 | 如何分批 |
|---|---|
| `by-language`，默认 | 按小写文件扩展名归类，无扩展名的文件单独归类 |
| `by-directory` | 按项目根目录下的一级目录归类，根目录文件单独归类 |
| `none` | 每个文件独立成批 |

每类按模板默认值切成**最多 50 个文件一批**。批次依次执行，批内文件并发；因此 `none` 实际会让文件审查逐个执行。批次只是调度和去重的边界，同批文件仍各自拥有独立对话。

**每个文件如何审查**

```mermaid
flowchart TD
    A["准备文件全文与适用规则"] --> B{"是否需要规划？"}
    B -- "需要" --> C["LLM：plan_task<br/>确定审查重点"]
    B -- "跳过" --> R["构建上下文<br/>检查完整提示词大小"]
    C --> R
    R --> D["LLM：main_task<br/>审查当前文件"]

    D -- "需要关联代码" --> E["读取文件、搜索代码"]
    E -- "返回工具结果" --> D

    D -- "发现问题" --> F["code_comment<br/>提交候选问题"]
    F -- "参数有效" --> G["异步定位并收集<br/>必要时调用 LLM：re_location_task"]
    F -- "返回工具结果" --> D

    D -. "上下文过长" .-> H["LLM：memory_compression_task<br/>压缩历史对话"]
    H -. "继续审查" .-> D

    D -- "task_done 成功" --> I["本文件主审查完成"]
    I --> J["进入批次汇总<br/>等待所有文件及问题处理完成"]
    G --> J
```

**1. 规划审查重点**

默认文件 **≥ 200 行**时先执行一次规划，可用 `--no-plan` 关闭。模型结合文件全文和适用规则，给出文件概述、重点位置及关注原因；提示词要求最多 5 个重点，规划阶段不调用工具。

**2. 构建上下文**

程序把以下材料填入提示词，让模型知道要查什么、依据什么判断：

| 材料 | 作用 |
|---|---|
| 当前文件路径、全文 | 确定审查对象和代码依据 |
| 审查指令、适用规则 | 明确范围和判断标准 |
| `--background` 业务背景、可用计划 | 补充业务意图和需要重点核实的位置 |

完整提示词仍需通过 **80% Token 阈值**检查，超限则该文件失败。工具返回的代码和搜索结果在对话中持续追加，上下文过长时按需压缩。

**3. 模型与工具交互**

模型通过 `file_read`、`file_find`、`code_search` 补充关联代码，通过 `code_comment` 提交问题，通过 `task_done` 结束审查。读取和搜索由程序执行，不另行调用模型；默认提示词要求问题针对当前文件。

每个文件只启动一轮主审查，轮内默认最多 **60 次模型与工具交互**。`--max-tools` 只能提高模板中的交互次数上限。scan 没有 `effort` 控制的追加审查，也没有 `review_filter_task` 事实复核阶段。

**4. 定位问题**

程序根据问题引用的代码片段，在指定文件全文中匹配行号；失败时按需调用模型辅助定位。仍未定位的问题可以保留，但行号未必可用。

此版本的 scan 未接入跨文件匹配。默认辅助定位模板读取的是 diff 字段，而 scan 的该字段为空，因此该次模型请求没有获得文件全文，定位能力存在限制。

**批次去重与项目摘要**

| 环节 | 默认何时调用 LLM | 输入与作用 | 关闭方式 |
|---|---|---|---|
| 批次去重 `DEDUP_TASK` | 本批收集到 **≥ 4 条问题**，含复用问题 | 根据路径、问题描述和引用代码合并相似问题，每组保留一条；不跨批次去重 | `--no-dedup` |
| 项目摘要 `PROJECT_SUMMARY_TASK` | 批次处理结束，且有已收集问题 | 根据问题路径与精简描述，总结重要问题、模块分布和共性风险；不修改问题列表 | `--no-summary` |

两者都不接收项目完整源码，也不调用工具。**去重检查相似性，摘要整理已有发现；它们不验证问题是否成立。** 程序只校验去重结果是否将每条输入问题恰好分配一次，避免因漏项或重复编号丢失结果。

**调用失败与提前停止**

模型请求经过适用的重试后仍失败，按下表处理。**单文件失败不会主动取消其他文件。**

| 失败环节 | 处理方式 |
|---|---|
| 规划请求 | 不使用计划，继续主审查；若文件本身已超时或取消，后续审查也会停止 |
| 主审查请求 | 当前文件失败；已提交的部分问题可能保留，但不写入该文件的完成检查点 |
| 辅助定位 | 保留问题，可能没有可用行号 |
| 上下文压缩 | 保留原上下文；仍无法降到长度限制内时停止主审查 |
| 批次去重 | 请求失败、JSON 解析失败或编号校验不通过时，保留原问题 |
| 项目摘要 | 不生成摘要，问题列表保留 |
| 额外收尾请求 | 结束当前文件执行；未声明完成则记为失败 |

主审查达到**交互次数或总 Token 预算限制**时，最多尝试一次额外收尾请求，只允许提交问题或声明结束。其他提前停止原因，如超时、连续无有效工具结果或压缩后仍超限，不触发这次收尾。

`--max-tokens-budget` 默认 **0，即不限总用量**。启用后，在文件派发和主审查请求前检查预算；预算不足会停止后续派发。已启动的任务，以及规划、去重、摘要等调用仍可能使最终用量超出设置值，因此它不是严格的费用上限。

整次扫描的退出规则：

- **部分文件失败**：通常仍可输出已收集结果，同时记录失败原因。
- **已派发文件全部失败，且没有复用结果**：整次扫描报错。
- **配置、文件枚举、续跑校验或会话保存失败**：命令报错；单个文件读取失败则跳过该文件。
- **派发前已无预算**：可能成功退出，但没有完成任何文件，需查看 `budget_exceeded` 和警告。

命令报错时，不输出正常的 CLI 结果报告；此前已写入的有效检查点仍可用于续跑。

**一次请求会重试几次**

重试按**一次模型请求**计算，不会从头重扫文件；主审查继续调用工具后的下一次请求另行计数。

| 失败类型或调用方式 | 重试行为 |
|---|---|
| 普通 API 的连接错误，或 HTTP `408 / 409 / 429 / 5xx` | 最多重试 **5 次**，加首次共 **6 次尝试** |
| 其他 HTTP `4xx` | 默认不重试，`retry_codes` 可扩展状态码 |
| 请求超时，或所属任务取消、超时 | 返回错误，不继续试满重试额度 |
| 流式输出已开始，随后中断或解析失败 | 不自动重新生成整段响应 |
| 非流式 Chat Completions 遇到 `io.ErrUnexpectedEOF` | 额外补发一次，补发也有重试额度；理论最多 **12 次尝试** |
| ChatGPT 订阅模式 | SDK 自动重试为 **0 次** |

重试采用退避等待，并遵循服务端提示。scan 使用这些共享请求逻辑，但此版本不输出结构化 `retry_report`。

**并发与超时**

`--concurrency N` 默认 **8**，分别控制文件审查和后台问题处理两个独立的任务池：

| 执行部分 | 并发方式 |
|---|---|
| 文件审查 | 当前批次最多同时运行 N 个文件；每个文件先规划，再主审查 |
| 后台问题定位 | 最多 N 个处理任务，可与主审查重叠 |
| 后台上下文压缩 | 在上述任务池之外，按文件对话触发 |
| 批次去重、项目摘要 | 等待前置阶段结束后调用；去重完成并保存检查点后才进入下一批 |

因此，**实际 LLM 并发可能超过 N**，源码没有统一的请求并发上限。重试依次执行，等待期间仍占用所属任务的位置。

单次请求默认超时 **300 秒**；单文件默认限时 **15 分钟**，由 `--timeout` 控制，包含规划、主审查及其重试。后台定位不随文件上下文取消，批次仍会等待它完成。模板中各任务的 `timeout` 字段未在 scan 流程中单独生效。

**续跑：哪些结果可以复用**

`--resume <会话 ID>` 复用旧 scan 的**文件检查点**：每条检查点保存文件路径、内容指纹和问题列表，问题列表可以为空；不会恢复旧模型对话。

程序依次检查：

1. **旧会话可读取**：必须是 `full_scan`，至少有一个完成或复用检查点。旧记录保存了扫描路径范围时，要求当前 `--path` 范围一致。
2. **文件内容匹配**：按“扫描模式 + 文件路径 + 文件全文”计算指纹。当前选中文件与旧检查点指纹相同，就导入结果；新增、修改、失败或没有检查点的文件重新审查。

检查点通常在**整批审查与去重结束后**写入。`review_item_done` 表示本次完成，`review_item_reused` 表示沿用旧结果；`review_item_failed` 会撤销相同指纹已有的可复用记录。中断时，当前批次尚未保存的文件可能需要重扫。

scan **不要求运行清单 `run_manifest` 或会话结束记录**，因此中断会话中已保存的有效检查点也能复用。它不校验规则、业务背景或模型是否一致，改变这些输入不会自动使旧结果失效。完整 JSONL 记录损坏会拒绝续跑，末尾未写完的一行则忽略。

**结果与 Viewer**

CLI 输出汇总后的问题；文本结果附带项目摘要，JSON 使用 `project_summary` 字段。`ocr viewer` 读取会话记录，不重新调用模型。

| 页面内容 | scan 中的含义 |
|---|---|
| **Review Comments** | 完成或复用检查点中保存的逐文件问题 |
| **Conversations** | 规划、主审查、定位、压缩，以及去重和摘要的模型对话 |
| **Session Tasks** | 此版本仅识别 review 分组任务；scan 的去重和摘要显示为特殊路径条目 |
| **Files Reviewed** | 会话中的文件条目，可能包含失败文件和去重、摘要的特殊路径 |

去重和摘要在会话中都记作 `memory_compression_task`，用路径区分：`__scan_dedup_batch_<序号>__`、`__scan_project_summary__`。看到该任务类型时，需要结合路径判断用途。

**CLI 与 Viewer 的问题数量可能不同。** 跨文件去重后，CLI 保留合并结果；文件检查点保留各文件原问题，避免续跑时因一个文件变化而丢掉另一个文件的问题。

> **判断是否查完，要看文件检查点、失败原因和预算警告。** CLI 的 `files_reviewed` 是选中文件数，Viewer 的文件数还可能包含特殊路径；此版本 scan 没有完整覆盖清单，数量或成功退出都不能单独证明审查完整。

**源码依据**

- 范围与分批：[文件枚举](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/provider.go#L100)、[文件筛选](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/agent.go#L451)、[分批策略](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/batch.go#L45)。
- 规划与审查：[scan 提示词与默认值](https://github.com/alibaba/open-code-review/blob/4236c871/internal/config/template/scan_template.json)、[逐文件执行](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/agent.go#L808)、[工具循环与收尾](https://github.com/alibaba/open-code-review/blob/4236c871/internal/llmloop/loop.go#L292)。
- 定位与压缩：[问题处理](https://github.com/alibaba/open-code-review/blob/4236c871/internal/reviewtask/tools.go#L110)、[scan 文件适配](https://github.com/alibaba/open-code-review/blob/4236c871/internal/model/scan.go#L22)、[定位提示词](https://github.com/alibaba/open-code-review/blob/4236c871/internal/diff/relocation.go#L28)、[后台压缩](https://github.com/alibaba/open-code-review/blob/4236c871/internal/llmloop/compression.go#L296)。
- 去重与摘要：[批次调度和检查点](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/agent.go#L560)、[项目摘要](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/agent.go#L920)、[问题去重](https://github.com/alibaba/open-code-review/blob/4236c871/internal/scan/agent.go#L1000)。
- 请求与重试：[普通客户端与截断补发](https://github.com/alibaba/open-code-review/blob/4236c871/internal/llm/client.go#L590)、[ChatGPT 模式例外](https://github.com/alibaba/open-code-review/blob/4236c871/internal/llm/responses_client.go#L43)、[SDK 重试判断](https://github.com/openai/openai-go/blob/v3.51.0/internal/requestconfig/requestconfig.go#L366)。
- 参数与续跑：[CLI 参数](https://github.com/alibaba/open-code-review/blob/4236c871/cmd/opencodereview/shared_flags.go#L220)、[命令退出与续跑加载](https://github.com/alibaba/open-code-review/blob/4236c871/cmd/opencodereview/scan_cmd.go#L247)、[检查点读取与校验](https://github.com/alibaba/open-code-review/blob/4236c871/internal/session/resume.go#L97)。
- 结果与展示：[CLI 输出](https://github.com/alibaba/open-code-review/blob/4236c871/cmd/opencodereview/shared.go#L824)、[Viewer 任务归类](https://github.com/alibaba/open-code-review/blob/4236c871/internal/viewer/store.go#L302)、[Viewer 问题读取](https://github.com/alibaba/open-code-review/blob/4236c871/internal/viewer/store.go#L683)。
