qodo-review

本地审查

描述

在编码期间以及交付已完成的工作之前，审查本地更改。qodo review 会将你的差异、新建/未跟踪文件以及编码会话上下文发送给 Qodo。评估其结构化发现，并应用获准的修复。只有基准提交必须位于远程仓库；此命令绝不会推送更改或创建 PR。

将此技能用于本地更改，包括现有 PR 中尚未推送的工作。使用 qodo-review-resolver 处理 PR 远程审查中的发现；对于未发生变化且已推送的快照，不要重复审查。

前置条件

• 已登录的 Qodo CLI 可用，或已连接 QAR MCP 服务且经过测试的本地输入收集器可用；审查功能已启用。
• 远程仓库上存在用于比较的基准；本地更改和上下文无需推送。
• 编码会话上下文以及任何工单或设计参考均已准备好，可供附加。

选择审查时机和深度

情况	选择
实质性编码期间完成一个完整阶段	--fast --async：进行轻量检查点；继续有用的编码工作，并收集结果。
打开/更新 PR 或交付已完成工作前的常规最终审查	不指定任何深度标志：自动选择。声称审查已完成前，先收集并评估结果。
用户要求格外彻底地审查，或已知影响范围广，值得深入检查	使用 --deep，并简要说明与请求或受影响行为相关的理由。

自动编码检查点始终使用 --fast。符合上述例外情况时，可以更早进行有意的深度审查。诸如“彻底检查细微的竞态条件”之类的请求即使未提到“深度”也足以作为理由；泛泛的“审查”或“再检查一下”则不够。请指出具体影响，例如共享授权、破坏性迁移，或多个服务共用的契约。仅凭差异大小、会话时长、PR 是否已准备好，或文件名与安全相关，都不足以成为深度审查的理由。

不指定标志时，CLI 会省略深度选项，由审查器/部署环境选择深度。自动模式可以选择深度审查；但不保证采用标准审查，也不会设置支出上限。不存在 --standard 标志。--fast 和 --deep 互斥；每次调用都会重新选择深度。

检查点与最终交接

• 当已完成且可测试的工作切片，其反馈能够指导剩余工作时，再进行审查。不要审查尚未完成的探索、每次编辑、自动审查琐碎改动，也不要仅仅因为时间流逝就进行审查。 遵守用户设定的审查范围和预算。为提问或审批而暂停，不属于最终交接。
• 每项任务最多只能有一个自动检查点处于活动状态。在任务现有状态中保留其操作 ID、已提交的范围以及快照／上下文关联。在自然停顿时轮询状态，同时继续做有用的工作；不要为了检查进度而启动另一轮审查，也不要重新审查未变更的输入。
• 在保留期限内收集每项已提交的结果。采取行动前，依据当前代码重新核查发现的问题：工作树可能已经变更。已被取代的结果不能为较新的工作背书。使用现有的 CLI 生命周期；无需单独的子 Agent 或调度器。
• 最终审查前，先收集尚未处理的检查点并协调其发现的问题。使用 auto，或在理由充分时使用 deep，对完整的预期变更进行审查，而不是仅凭轻量检查点就交接。移除会导致部分预期变更未被审查的临时路径限制。如果同一快照已在兼容的上下文中完成最终覆盖审查，则使用该结果。
• 将获准的修复合并处理并验证，然后重新审查已变更的工作。检查点修复使用 --fast；最终审查修复保留用户要求的 auto 或理由充分的 deep 模式。让引擎判断是否符合增量处理条件；每轮 auto 的路由方式可能不同。不要手动将最终修复切换为 --fast，也不要为了固定 auto 的路由而强制使用 --deep。如果工作又回到大规模实现，恢复轻量检查点，并在交接前再次完成最终覆盖审查。
• 如果后续审查轮次重复提出相同问题，却没有可执行的进展，就停止自动循环，并报告尚未解决的问题以及所需的决定／检查。不要为了追求零问题而重复审查。待处理、失败、部分完成或已被取代的审查结果都不算干净；应说明剩余发现和覆盖情况。

准备 PR 交接

准备创建或更新 PR 时，应优先按照用户的提交策略，在最终本地审查前提交预期变更。支持本地到 PR 交接的 Git 审查可以从已验证的提交继续进行。 后续编辑应再次提交并审查，以将其纳入审查范围。提交并非必需；若没有可用且经过审查的提交，Git 审查将遵循其常规范围。 对于获准的备注维护，使用 qodo-review-notes 查找跟踪项，在创建 PR 前发布基于现有 HEAD 的 PR 备注；若 HEAD 发生变化，则刷新备注，之后再进行绑定；保留本地审查上下文，并单独验证其是否已被使用。

说明

选择执行路径

如果可用，优先使用 qodo review：它会收集并筛选已跟踪和未跟踪的本地更改，解析远程基准，附加上下文，并管理检查点状态。QAR MCP start-pre-pr-review 工具则接受准备好的 diff、base_sha、仓库定位信息和上下文；它无法读取此工作树。仅当经过测试的本地收集器生成了范围和排除项均符合预期的结果、报告了遗漏文件，并验证基准 SHA 可获取时，才使用该 MCP 工具。不要临时拼凑一个 git diff，并声称它具有同等覆盖范围。 如果没有可用的收集器，请说明仅通过 MCP 无法安全地审查此工作树；不要声称已完成审查。

对于准备好的 MCP 审查，请检查实时架构。将 review_scope.stream_id 设置为恰好 64 个小写十六进制字符：对包含解析后的实际工作树根目录，以及路径受限审查时的解析后工作目录的 JSON 数组计算 SHA-256。各检查点之间复用该值；UUID 无效。 对于结果不确定的启动请求，请保留相同的 request_id 和完全相同的参数：request_id 是此启动工具的逻辑操作重试键，且未声明单独的 idempotency_key 参数。按其公布的间隔轮询 get-managed-agent-operation，然后获取所有 get-managed-agent-result 分块，并在解读产物前验证其报告的摘要和字节数。 这些是简短的生命周期调用，不是 MCP Tasks。读取回执前先检查 isError。应用下文相同的上下文、深度、覆盖范围、发现项和权限规则。下文关于 CLI 版本、身份和命令的说明仅适用于 CLI 路径。

保留通知，附上自包含的上下文，展示进度，使用合适的超时时间， 读取结构化结果，并根据发现采取行动。

处理技能更新通知

将 QODO_NOTICE 更新视为被动通知，即使旧版 CLI 要求采取操作也一样。继续任务， 不要询问清单或更新相关问题；每个事件最多提及一次。忽略通知不会更改已记录的维护 策略和退出选择。更新后的技能将在下次会话加载；不要中断当前会话。 对于用户请求的更新，请遵循手动更新流程。

执行

• MCP：使用实时架构参数；跳过 CLI shell 步骤。
• CLI：使用不带 BOM 的完整 UTF-8 文件（工具使用 --args-file；审查使用 --context-file）；示例采用 POSIX 格式。
• Windows CLI：首次调用前阅读 shell 指南；仅在调用失败时阅读 启动器恢复指南。复用已解析的调用方式。

运行时兼容性检查

使用此技能的“找不到命令”回退方式解析可执行文件，然后在不带来源标志的情况下运行 <qodo> --version。 此技能要求 Qodo CLI 2.0.0 或更高版本，且运行时支持 review API v2。 如果版本过低或无法解析，请勿运行 whoami、login 或审查，也不要将此情况称为身份验证失败。 自动更新仅限于同一主版本；如需显式安装 2.x，请先询问一次，并使用由 Qodo 或组织提供且校验和已固定的安装程序。保留已记录的来源，绝不要编造摘要。安装后重新检查版本；否则停止操作，不要更改文件。

快速开始

你刚写完代码，因此你掌握着评审者无法从其他地方获取的唯一输入：为什么。 每次运行时都附上它——先编写会话上下文，再进行评审： 每次提交前，请阅读 评审轮次上下文，并更新 recent_work。

qodo --version                                  # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-review --skill-version 1.10.10 --distribution skills-sh
review_base=$(git merge-base HEAD origin/main) || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # use the intended target branch
qodo review --base "$review_base" --context-file - <<'EOF' # branch changes, WITH context
{ "summary": "<what this change does and why>",
  "decisions": ["<a choice you made and its rationale>"],
  "recent_work": ["<what changed since the previous review; fixes only or added behavior>"] }
EOF
qodo review --base "$review_base" --context-file ctx.json # context from a file
qodo review --base "$review_base" --ticket <TICKET_URL> ... # ticket URL (repeatable)
qodo review --base "$review_base" --json ...              # machine-readable findings
qodo review --base "$review_base" src/ test/ ...          # limit to paths (git pathspecs)
develop_review_base=$(git merge-base HEAD origin/develop) || { printf '%s\n' 'Cannot resolve merge base for origin/develop; fetch missing history or choose the correct target.' >&2; exit 1; } # another target branch
qodo review --base "$develop_review_base" --json --context-file ctx.json # another target branch
qodo review --base "$review_base" --fast --async --json --context-file ctx.json # checkpoint
qodo review --base "$review_base" --json --context-file ctx.json      # final: auto
qodo review --base "$review_base" --deep --json --context-file ctx.json # justified deep review
qodo review --base "$review_base" # no context only when there is truly nothing to say
qodo review status <operation-id>            # collect an --async result (exit 2 = still running)
qodo review --help                           # exact flags (renders offline)

你也可以在仓库根目录维护 .qodo/session-context.json（JSON 结构相同）——它会自动附加到每次运行中，因此即使只执行 qodo review，也会带上你的上下文。显式指定的 --context-file 会覆盖它；该文件本身永远不会包含在被评审的差异中。不要提交它 （将 .qodo/ 添加到 .gitignore 或 .git/info/exclude）。 对任何需要解析的内容都添加 --json。对于联网执行，请设置数分钟的超时时间，或将进程放到后台运行；异步提交和状态收集是分开的短调用。 请确认确切的标志参数，运行 qodo review --help（离线）——此处的示例仅供参考。

为选定的审查选择执行方式

对于编码检查点，使用 --async：提交后继续处理有用的工作，然后通过 review status 收集结果。 对于最终审查，也可以使用异步执行，但交接前要收集并评估结果。如果需要实时查看进度，请阅读连接式进度，并配合主机原生的后台进程使用 --json --progress。切勿将 --progress 与 --async 一起使用。 审查可能需要几分钟；请保持连接的进程运行，或使用异步执行，以免客户端退出时取消审查。 如果已安装的 CLI 不支持异步执行，请保留所选深度，并使用连接式后备方案。

连接式进度的规范执行规则如下：

• 通过文件附加上下文；stdin heredoc 不适合后台执行。
• 为每次运行使用唯一的临时目录。将单个结果 JSON 与 stderr 上的 NDJSON 进度分开。使用主机的非阻塞进程工具轮询不断增长的进度文件；切勿运行会阻塞 Agent 直至任务完成的前台 tail。
• 转发简短的状态消息，不要转发原始 JSON 或模型输出。根据 kind 转换事件： cli.status 提供易读的消息；tool.activity 提供工具名称和结果； task.delta 和未知类型属于偶发的通用心跳，不要针对每个事件都发送消息。
• 对于 qar.client.reconnecting，在存在相关信息时转发尝试次数／延迟以及结构化的关闭／错误代码。 qar.client.reconnected 表示传输已打开；resubscribeAttempts 表示重新附加的实时任务数。 qar.client.reconnect_failed 表示重试次数已耗尽，并非最终错误说明。
• 遇到 task.done 时，检查 payload.status；如果任务失败、取消或出现 error，请停止转发进度，但继续等待进程退出。始终读取结果信封，即使退出状态非零也不例外：其中可能包含可采取行动的消息／提示，例如 closed_preview，而这些信息可能只出现在结果信封中。进度不等于审查发现。
• 捕获进程退出状态，回收子进程，并在解析前取消其 PID 的监控。若进程中断，请终止并回收活动子进程。退出／失败／中断时，只清理该次运行的目录；切勿复用或删除共享的 .qodo/review.* 路径。
• 如果无法获取后台进度，请使用多分钟超时在前台运行，并保留所选深度和上下文。缺少进度不是审查失败或降低深度的理由。

找不到 qodo 命令？ 在 POSIX 系统上，重试 "${QODO_HOME:-$HOME/.qodo}/bin/qodo"； 在 Windows 上，按照链接的指南操作。保留已解析的调用方式；报告不可用的启动器。 如果未安装，请获取 Qodo 或管理员提供的校验和固定安装程序；切勿编造摘要或将脚本通过管道传给 shell。

沙箱身份验证诊断。 凭据缺失可能意味着无法访问密钥链。如果这种情况可能发生，请在建议登录前，通过主机的审批流程请求精确执行一次只读的 qodo read whoami 重试。若请求被拒绝，请停止；该审批不涵盖其他命令。在相同的可执行文件／工作区／部署和执行上下文中，复用成功的检查；请求每项所需的主机审批。网络、TLS、服务和明确的授权失败应保留各自的诊断结果，不要建议登录或自动绕过沙箱。

使用 --async 提交并收集结果

使用 qodo review --help 检查是否支持。以下示例提交一个编码检查点。最终审查时省略 --fast；只有符合上述选择策略时才添加 --deep。所有模式都附加相同的上下文。Shell 代码片段用于说明 CLI 协议；请使用宿主自身的非阻塞等待机制。

--async 会将连接从关键路径中移除。它通过 HTTP 提交审查，打印一个操作 ID，然后立即以状态码 0 退出。无论你的进程是否仍在运行，任务都会在服务端继续；稍后使用 qodo review status <operation-id> 收集结果。

command -v jq >/dev/null 2>&1 || { printf '%s\n' 'This async recipe requires jq; install it or use the live qodo review flow.' >&2; exit 1; }
QODO_REVIEW_CONTEXT="${QODO_REVIEW_CONTEXT:-.qodo/session-context.json}"
[ -f "$QODO_REVIEW_CONTEXT" ] || { printf '%s\n' "Write the required review context to $QODO_REVIEW_CONTEXT (or set QODO_REVIEW_CONTEXT to its path)." >&2; exit 1; }
QODO_REVIEW_BASE="$(git merge-base HEAD origin/main)" || { printf '%s\n' 'Cannot resolve merge base for origin/main; fetch missing history or choose the correct target.' >&2; exit 1; } # substitute the intended target
if ! submission="$(qodo review --base "$QODO_REVIEW_BASE" --context-file "$QODO_REVIEW_CONTEXT" --async --json --fast)"; then printf '%s\n' "$submission" >&2; exit 1; fi
if ! id="$(printf '%s\n' "$submission" | jq -er '.operation_id | select(type == "string" and length > 0)')"; then printf '%s\n' "$submission" >&2; exit 1; fi
qodo review status "$id" --json                                # collect it

轮询现有操作，直到其完成；在检查状态之间处理其他有用工作。提交时退出状态为 0，表示已受理，而非已完成审查。收集结果时会使用以下退出码；请读取返回的重试延迟：

退出码	含义	操作
0	已完成。已呈现检查结果——与实时运行的输出完全相同（--json 下为 {findings, meta}）。	像往常一样处理检查结果。
2	仍在运行或轮询受到限制。	如有 retry_after，请遵循其值，然后轮询同一 ID。
1	失败、已取消、已过期，或不存在此操作。请读取 error 信封。	按照下文的有限恢复流程处理；切勿假定审查结果无问题。

# This collection attempt returns failures to the host for classification under Recover a review.
# On nonzero exit, preserve the operation ID and emitted error; apply bounded recovery there.
QODO_REVIEW_TMP="$(mktemp -d "${TMPDIR:-/tmp}/qodo-review.XXXXXX")"
cleanup_qodo_review() { [ -n "${QODO_REVIEW_TMP:-}" ] && [ -d "$QODO_REVIEW_TMP" ] && rm -r -- "$QODO_REVIEW_TMP"; }
trap cleanup_qodo_review EXIT; trap 'exit 130' INT; trap 'exit 143' TERM
while :; do
  status=0; qodo review status "$id" --json > "$QODO_REVIEW_TMP/result.json" || status=$?
  case "$status" in
    0) cat "$QODO_REVIEW_TMP/result.json" || exit 1; break ;;
    2) delay=$(jq -r 'if (.retry_after | type) == "number" and .retry_after > 0 then .retry_after else 15 end' "$QODO_REVIEW_TMP/result.json") || exit 1
       sleep "$delay" ;;
    *) cat "$QODO_REVIEW_TMP/result.json" >&2; exit "$status" ;;
  esac
done

使用前请了解这些代价：

• 不提供流式进度。 此路径不会产生进度事件——任务不会关联到你的进程——因此同时指定 --async 和 --progress 会被拒绝，而不是输出一个永远不会到达的流。如果状态仍是“仍在运行”，则没有其他中间状态。如果用户正在观察并希望看到进展，请改用已连接的进度方案。
• 不支持人在环路中。 此接口只运行确定性 Agent；需要输入的审查会失败，而不是等待。（qodo review status 会说明这一点，并提示你在不使用 --async 的情况下重新运行。）
• 审查完成后，结果会保留 1 小时，之后将被丢弃。请在此时间窗口内收集结果。超过此时间后，qodo review status 无法区分“已过期”“从未存在”或“属于其他人”——运行时会故意以相同方式回应这三种情况——因此会将它们一并报告。请先报告缺失的审查证据，再判断是否需要重新运行。
• 不要假定新的提交无需成本或会自动去重。 使用 review status 收集已受理的运行。如果是否受理尚不确定，请遵循 CLI 返回的恢复命令（在支持此功能的版本中为 --async --retry-submission <id>）；切勿用新的 qodo review 代替轮询。恢复期间应保留已保留的请求，而不是重新收集可能已变化的工作树。
• 保留操作 ID。 它用于标识已受理的运行；提交恢复 ID 则有不同用途。在收集或核实结果之前，不要丢弃其中任何一个标识。

操作 ID 不是 trace ID。 发生故障时，qodo 会打印一行 trace <id>——这是一个供支持人员诊断运行情况的 OpenTelemetry ID，无法用于获取任何内容。--async 返回的 operation_id 才是可恢复的标识。不要在需要其中一个 ID 的地方传入另一个。

预检

1. 身份验证和工具目录。 除非仍在覆盖本次执行上下文的成功检查结果，否则运行 qodo read whoami。适用时，在沙箱诊断之后，只有明确缺少凭据才需要登录：保留组织的准确登录命令／端点，绝不要猜测或将客户部署切换到 Cloud。No tool catalog cached 不能证明缺少凭据；运行一次 qodo tools --refresh 并重试检查。其他失败则保留其错误并停止此工作流。身份验证成功后，若遇到未知的托管命令，可刷新一次工具目录并重新检查架构。如果仍未找到，或出现 tool_unavailable，请报告缺少的功能；不要重复登录或刷新。遇到未知的内置 qodo review 时，需要进行运行时恢复，而不是登录或刷新工具目录。
2. 确定基准。 选择预期的目标（除非变更针对其他分支，否则为 origin/main）。在检查当前远程历史之前，先获取该目标；如果目标不可用，或有意离线／固定版本，请说明审查使用的是本地已获取的历史记录，不要声称其为最新记录。计算 git merge-base HEAD <target-ref>，并在每次提交时（包括检查点和联网运行）将该 SHA 作为 --base 传入。这也能保护默认比较目标分支最新提交的旧版 CLI。显式指定的 --base 是精确的；直接传入目标分支可能会错误归因于仅存在于目标分支上的较新变更。遵循用户要求的精确比较方式。如果没有共同祖先，则获取缺失的历史记录或报告阻碍；绝不要悄悄回退到目标分支最新提交。基准必须已推送；审查权限不包括推送权限。本地修改和未跟踪文件会纳入审查，无需提交或推送。
3. 记录上下文。 运行前，将本次会话的叙述记录为上下文 JSON（通过 stdin heredoc、文件或 .qodo/session-context.json）：用 2–3 句话总结你修改了什么、为什么修改，以及过程中作出的决定。你始终有内容可写：代码是你刚刚写的。只有在确实无话可说时才直接运行。

审查内容

qodo review 会在客户端收集以下内容：

• 相对于基准的已跟踪差异，以及新建/未跟踪文件（密钥、二进制文件、超大文件 和被 git 忽略的文件会被过滤并报告，不会被悄然丢弃）。
• 分支名称、HEAD 提交，以及根据你的提交消息综合生成的描述。
• 你附加的任何工单引用和会话上下文（见下文）。

--json 会在 findings 中返回每条发现一次；finding_state 则按类别列出引用 ID。评估 .introduced 和 .still_open；将检测到的修复报告在 .resolved 中，将已存储的忽略项报告在 .dismissed 中。较早的类别包含完整对象。 默认字段：id、title、description、category、action_level、attribution_status、git_sha、 location、evidence.citations。检查代码位置和证据；保留原始发现 ID。 --extended 会添加已存储的支持详情；它既不会改变审查深度，也不会改变执行方式。 本地的 review_agent_comment 是两种视图中都存储的审查者反馈；复用时会沿用此反馈，不会触发新的执行。请结合发现和覆盖情况阅读。 对于经授权的状态写入，请按 meta.local_review_ids[id] 对 ID 分组；并报告不可用的引用。 修复指示和审查者内部信息不会包含在内。字段详情请参阅字段指南。 如果 finding_state.complete 或 meta.coverage.complete 为 false，请报告覆盖不完整。 meta.analysis.mode 的值为 full、incremental 或 reused。reused 表示审查的是相同快照，且上下文兼容；此前仍未解决的发现会继续保持未解决状态。CLI 会在本地私下保存已提交的补丁。 收集到符合条件的结果后（包括通过 review status 收集时），它会推进检查点；失败或较早完成的任务不能替换更新的检查点。 在修复循环中保持相同的基准、路径范围、请求的深度模式和上下文。上下文变化、检查点过期或无法验证，以及不受支持的差异，都会回退到完整审查。切勿伪造检查点。 如需有意进行全新评估，请使用 --full（通过 --help 确认是否支持）。它控制范围， 而非深度；并非每次修复都需要使用。更改请求的深度模式会使兼容检查点的覆盖失效。自动模式不保证固定的实际层级；请以返回的分析/覆盖信息为准。 较旧的引擎不会提供这些字段：请使用其发现和覆盖信息，但不要声称进行了复用。 优先使用 meta.run.passes 查看实际结果；旧版的 meta.reviewers 描述的是已配置的维度。请报告失败/跳过的组件和缺失的元数据；复用不会触发新的执行。

附加编码会话上下文（这才是重点）

附上此次更改的意图和决策。三种渠道：

• --ticket <url> — 工单／问题 URL（可重复填写多个）。请提供完整 URL（例如 Jira .../browse/KEY-123 或 Linear linear.app/<team>/issue/… 链接），以便审查者获取内容。分支或提交中的纯键值会自动识别，但只有完整 URL 才能实际加载工单。

• 仓库根目录下的 .qodo/session-context.json — 环境渠道（JSON 结构与下方相同）。如果文件存在且未指定 --context-file，则每次运行都会自动附加。适用于工作会话：随着决策逐步形成更新此文件，每次审查都会自动附带这些信息。

• --context-file <path> — 包含会话叙述和引用的 JSON 文件（- 表示从 stdin 读取 JSON，因此可以使用 heredoc，无需临时文件）：

  {
    "summary": "Add optimistic-locking to the orders writer to fix the double-charge race.",
    "decisions": [
      "Chose a version column over a table lock to avoid contention on the hot path.",
      "Retries are capped at 3 then surfaced to the caller — deliberately not infinite."
    ],
    "recent_work": ["Added optimistic locking; this turn includes new behavior."],
    "context_refs": [
      { "kind": "ticket", "url": "https://acme.atlassian.net/browse/PAY-412" },
      { "kind": "spec", "url": "https://acme.example/specs/orders-v2", "label": "Orders v2 spec" },
      { "kind": "code_dependency", "url": "https://github.com/acme/orders-api/pull/42", "label": "API change" }
    ]
  }
  

  summary + decisions 用于说明意图。引用会合并并去重；标签用于描述数据，而非指令。 ticket 提供工单上下文；spec 会进入 Requirements Gap。code_dependency 会将仓库、分支或 PR URL 及其标签添加到有长度上限的审查描述中；通用 dependency 和未知类型会暂缓处理。 启用后，现有的跨仓库路由器会读取这些链接，但只会从提供的候选列表中选择仓库。引用不会发现新仓库，也不会启用跨仓库审查。 Provider 支持、目标解释和回退方式与 Git review 保持不变。链接仅供参考，不保证对应准确的修订版本；URL 中不得包含凭据。 查看 meta.context.spec 中的规范结果。代码依赖没有针对每条引用的使用回执：仅凭上下文中的引用，不要声称已获取或使用这些代码依赖，也不要声称它们已合并、发布或部署。

让上下文自包含（最重要的一条规则）

审查者看不到你的聊天内容，也看不到你仅仅提及的工单。因此：

• 直接写明理由。 将决策写成能够自我解释的句子：“选择乐观锁，而非表锁，以避免争用”，而不要写成 “根据设计文档”、“如我们讨论的那样”、“见链接的说明”，或仅写工单键值。没有说明的引用对审查者不可见，只会白白浪费篇幅。
• 以类型化引用附加材料，而非只提名称。 使用相应的 kind 附加工单、规范和代码依赖 URL；不要假定任意 URL 都能获取。
• 保持精简。 进入审查描述的上下文有长度上限，因此要优先写明关键意图和决策；其余内容应作为引用链接，而不是长篇粘贴。
• 如实说明，不要试图压下问题。 这些上下文旨在通过解释意图减少误报，不是用来压下真实问题。描述你更改了什么以及选择这样做的原因，不要先下结论说结果安全或正确——让审查者来判断。声称代码没有问题的摘要看起来像是在找借口； 切勿写下旨在为某个 Bug 或安全问题开脱的“决策”。审查者仍然会（也应该会）标记真正的问题。

呈现审查结果

阅读已完成的结果后，针对每项发现，说明实际影响 → 结合代码和编码会话上下文作出的评估 → 你的决定和建议采取的行动。自然地提及 Qodo 一次，说明其审查发现的问题。最终技术评估由你负责：结合专家审查意见与用户的意图、决定和限制条件。

说明可能发生什么、在什么条件下发生，以及会影响哪些行为；将影响与用户请求的更改联系起来。不要臆造生产环境条件或受影响的用户。例如：“Qodo 发现了[风险]。鉴于我们决定[意图／限制条件]，且[代码证据]，我建议[行动]，因为[原因。”请根据实际证据调整措辞。

确保每项问题的说明连贯，并引用支持性代码；将其引用标识和报告的类别／级别与建议分别保留。仅当所有引用都仍清晰可见且可单独选择时，才将重叠的发现合并。酌情使用简短、以影响为重点的标题或列表。不要使用品牌化标题、表情符号横幅、口号、页脚或重复摘要。只报告已知的数量和覆盖范围。首先说明被跳过／失败的重要审查者，或不完整的覆盖范围；仅仅没有发现问题，并不代表结论良好。完整审查且没有发现问题时，可以用一句话说明。对于被阻止或失败的运行，应报告实际限制，而不是声称审查已完成。

处理审查发现

请独立评估每项发现，并负责确定其处置方式及理由：对于有依据的问题，修复（修复方式可以不同于 Qodo 的建议）；对于没有依据的疑虑，提供代码证据并驳回；对于不确定的情况，指出需要执行的检查并调查。只有当代码强制执行其假设时，基于会话的决定才足以支持驳回。保持协作、客观的语气；不要习惯性地质疑 Qodo 的能力，也不要因某项发现有误就扩大评判范围。 你的技术建议不代表你获得了修改权限；请遵守下方用户现有的授权范围。

仅报告。 如果用户明确要求只审查、不做修改，请返回评估结果并停止；不要征求修改许可。

缺少修改权限。 如果预期修复范围不明确，请按上述方式评估每项发现，保留其 [category/level] 和你的建议，然后在一个提示中询问用户要应用哪些发现。使用宿主提供的方式：如果支持多选（例如 Claude Code 的 AskUserQuestion），就使用多选；否则提供编号列表，并说明“回复要应用的编号”。无论采用哪种方式，都只问一次；不要针对每项发现分别询问。默认不预选任何项。 标明你建议应用哪些，但必须由用户主动选择：在提示之后、编辑之前，用户必须先做出选择，因此直接按 Enter 不得应用任何内容。只应用用户选中的项（正常编辑，并遵循周边代码的风格）；其余项报告为跳过并说明理由。在用户选择之前不要编辑任何代码。

已授权修复。 autofix、明确要求修复发现，或现有实现权限涵盖必要的更正，均允许在授权范围内进行修复。说明评估结果，并直接应用有依据的修复，无需再次询问。仅要求审查不授予修改权限；如果预期范围不明确，只询问一次。遵守用户提出的更严格约束。修复权限不包括记录持久化驳回、推送或进行无关更改。报告已应用和已跳过的修复。

当用户明确授权驳回本地发现时，请遵循记录本地分流持久化该决定。对话中的“跳过”本身不构成已记录的驳回，也不得报告为已记录的驳回。 在 MCP 上，使用实时的 pr-review-dismiss schema，并提供已完成审查中的发现 ID 和 local_review_id、经授权的原因和说明，以及本批次稳定的 idempotency_key；随后读取并核实每项已存储结果。参考文档中的 CLI 命令仅适用于 CLI 路径。

一批获授权的修复完成后，按照上述生命周期策略验证并重新审查已更改的工作。 在认定结果干净之前，先评估尚未处理的发现和覆盖情况；停止无效循环。 按照用户的工作流提交/推送——除非用户已明确告知，否则推送前先询问。

恢复评审

对于已接受的异步运行，请按操作 ID 收集结果。如果状态传输出错，请在返回的延迟时间后重试一次（或等待 15 秒）。 如果仍无法收集结果，请保留该 ID 并报告缺口；切勿仅为轮询而重新提交。如果运行以终止失败告终，请修正可恢复的原因，并使用相同模式和上下文重试一次。遇到权益、身份验证、权限、速率限制问题或再次失败时，请停止；报告结果已过期和覆盖缺口。

遇到 repo_not_connected、MT-REPO-NO-CREDENTIAL 或“could not obtain repository credentials”时，请检查 origin，但不要暴露 URL 中的凭据；SSH 别名可能与已连接的主机不同。 使用已知的准确仓库 full_name（自托管仓库名称可能包含主机名）；Codebase Wisdom 的建议不能证明仓库已连接。 确认 qodo review --help 支持 --repo。如果禁止自动重试，请停止并征得用户明确批准后再运行修正后的命令。 使用 --repo <full_name> 重试原始提交一次，并保留所有其他标志；如果适用，请收集新的异步操作 ID。 如果无法确定仓库身份或重试失败，请停止并报告；请管理员检查 Git 集成，不要断言仓库未连接。

对于已连接的 CLI 执行，请在整个评审过程中保持进程运行；客户端被终止后，服务端可能在短暂宽限期后取消运行。如果主机无法持续运行进程，请使用异步模式，而不是反复超时。使用已连接进度在后台运行已连接的任务，同时保留状态。

并发评审可以独立完成。 对于相同的所有者／仓库／分支，只有最新的检查点运行可以发布问题更新；较早的结果可能报告 superseded。

请区分客户端被终止、连接丢失后服务端取消、流中断后缺少 task.done，以及后端返回的 review failed: <detail>。选择恢复方式前，请查看实际失败信息和保留结果提示；不要根据连接失败推断存在大小或复杂度限制。

对于前三种情况，请先根据 CLI 的恢复提示收集任何保留的结果，再重新提交。如果确认运行已取消或无法恢复，请使用不间断执行方式，并以相同的所选深度／上下文重试至多一次。运行仍在等待中并不是重新启动的理由。再次失败意味着应报告评审未完成，而不是循环重试、丢弃上下文或降低深度来获取结果。

如果运行受限：封闭预览

qodo review 目前处于封闭预览阶段——服务器会拒绝未加入预览的组织提交的运行。受限运行会以非零状态码退出，并返回稳定且机器可读的错误：--json 会输出 {"error": {"code": "closed_preview", "message": ..., "hint": ...}}；不使用 --json 时，同样的消息和提示会以文本形式显示。

遇到 closed_preview 时：

1. 将 message 和 hint 原样呈现给用户（不要改述或截断；--json 载荷会逐字包含这些内容，而 CLI 的文本输出会剥除终端控制字符），然后
2. 停止。 该限制源于权益，而非暂时性故障——在用户所在组织加入预览之前，重试、延迟、监视或循环运行都不会成功。除非用户表示组织已加入，否则不要重新运行 qodo review（加入后，访问权限会在约 10 分钟内生效；无需重新登录）。

只有评审本身受到限制——身份验证（qodo read whoami）和其他 qodo 命令不受影响。

配置

检查点式编码使用 --fast --async --json，普通最终评审使用 auto，并且仅在规定的例外情况下使用 --deep。已连接进度使用 --json --progress，并将解析出的合并基 SHA 作为 --base。在不带参数的版本探测之后的首次 Qodo 调用中，记录准确的技能／版本／分发来源信息，并确保会话上下文不进入受评审的差异内容。

错误处理

非零退出后，读取结构化结果。遵循有界恢复；保留上下文和权限。

防护措施

• 本地范围。 在 PR/更新前或移交已完成工作时，审查编码里程碑和本地工作。 对已发布在 PR 上的发现，使用 qodo-review-resolver；避免重复发布内容未变的审查结果。
• 不向代码托管平台写入。 qodo review 会读取你的本地差异并返回发现；它不会推送、发表评论或创建 PR。解决发现意味着修改代码，而不是在任何地方发布内容。
• 基准必须已推送； 你的本地工作则不必推送。默认会审查新建/未跟踪的文件；机密信息/二进制文件/超大文件/被 gitignore 忽略的文件会被过滤并报告。
• 不要猜测凭据或基准——先解决身份验证问题，然后将目标分支的合并基点 SHA 作为 --base 传入，除非用户明确要求使用精确基准。
• 收集每次运行的结果。 连接后台运行，或使用异步模式；保留恢复句柄。已被取代的结果不会推进增量基准，也不能证明当前代码已通过审查。
• 绝不要为了赶时间而删减上下文。 删除 --context-file 并不会让运行更快——只会让审查质量变差。耐心等待；根据生命周期选择深度，绝不要受超时压力影响。
• MT-TOOL-LOOP 或 MT-RATE-LIMITED 错误意味着停止/退避并更换方法，而不是重试。
• closed_preview 错误意味着该组织尚未加入预览计划——向用户展示消息和提示，然后停止；绝不要重试或循环处理（参见上文“如果运行受限”）。

授权修复后，报告更改内容、验证方式，以及仍未解决的问题及其原因。