跳到正文
Code Review
文档中心 / 扫描流程

文档中心 / 参考文档

扫描流程

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

本文按官方 v1.13.8 / 4236c871 源码说明默认行为,与 review 流程文档 使用同一版本。图中标有 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 没有完整覆盖清单,数量或成功退出都不能单独证明审查完整。

源码依据