qodo-pr-resolver

读取并处理审查发现

描述

使用 qodo CLI 读取拉取请求的审查会话——其状态、接受审查的提交，以及每条发现及其处理状态——适用于任何 PR（自己的或他人的）。仅仅读取也是有效用法：读取后即可停止，报告审查进展或指出了哪些问题（例如，在确认当前头部提交审查无问题后才允许合并）。如需进一步处理，可在代码中解决未处理的发现，并运用自己的判断（审查是有力的第二意见，不是绝对准则）——默认情况下，你评估这些发现，由用户选择要应用哪些（传入 autofix 可直接应用）；可以运行一次（报告并解决用户批准的内容），也可以作为监视循环运行（解决 → 让 Qodo 重新审查新提交 → 重复，直至无问题）。然后在已处理的发现上记录结果——对已修复的发现使用 mark-implemented，对用户同意在不修改代码的情况下关闭的发现使用 dismiss。只有这样才能解除这些发现造成的合并策略阻止；若跳过此步骤，审查仍会显示红色，直到有人在 PR 上手动处理。你仍然不会自行向代码托管平台发布内容：状态工具会写入 Qodo 的审查数据库，由 Qodo 同步 PR 评论。（可以读取普通的 git/代码托管平台元数据——git rev-parse HEAD、gh pr view --json headRefOid——事实上，以下新鲜度检查也要求这样做；“不要抓取”规则针对的是 qodo，而不是你的 shell。）

前提条件

• Qodo CLI 已完成身份验证，并提供结构化的 PR 审查会话工具。
• 无需抓取审查评论，即可解析准确的 PR URL 及其当前头部 SHA。
• 对发现进行任何写入操作，都必须得到用户的明确授权，或在技能明确的 autofix 范围内。

说明

遵循以下详细工作流：获取结构化状态，要求审查已针对准确的头部提交完成，展示未处理的发现，只应用已批准的修复，并且只记录已实际处理的结果。

要检查审查状态或发现时，始终运行下面的 qodo 读取命令——不要使用 gh/curl 获取 PR 审查的渲染后评论。评论界面会丢失信息、因托管平台而异，而且很容易读取到相对于头部提交已过时的内容；该工具会返回已审查的 commit_sha。要判断内容是否最新，请将该 commit_sha 与 PR 头部进行比较——对于刚刚推送的 PR，可直接使用 git rev-parse HEAD；对于其他 PR，则读取普通的代码托管平台元数据（gh pr view <pr> --json headRefOid、git ls-remote）。此规则仅针对读取审查（不要抓取其评论）——并非禁止读取头部 SHA 等代码托管平台元数据。

处理技能更新通知

Qodo 命令可能会向 stderr 输出 QODO_NOTICE <json>，同时仍然成功。当 code 为 qodo_skill_update_available 时，保留命令结果并完成当前任务。然后按照通知中的 steps 操作：先进行只读清点，解析已安装的 Qodo 包及其作用范围，展示确切的生命周期所有者更新命令或 UI 操作，并在任何修改操作前询问一次。如果用户拒绝，确保当前版本仍可用。

切勿调用其他生命周期所有者、猜测占位符，或隐式安装可选包。用户批准更新后，询问是否按通知要求重启宿主；当前会话可能仍加载着旧版技能。

运行时兼容性门槛

首先，按照下方的 qodo: command not found 回退说明解析可执行文件。在运行任何其他 Qodo 命令之前，严格按所示运行 <qodo> --version，不要添加来源标记。 这个不带参数的探测有意兼容较旧的 Qodo CLI。此技能要求 Qodo CLI 版本为 0.1.0-next.37 或更高版本。

如果版本较旧或无法解析，不要运行 whoami、login 或托管工具，也不要将问题描述为身份验证问题。说明此技能版本比运行时更新，显示 qodo update 作为更新运行时已记录来源的命令，并只询问一次是否运行。对于客户部署，保留组织提供的更新来源；切勿将其切换到公共服务。获准更新后，重新运行不带参数的版本探测，只有满足最低版本要求时才继续。如果用户拒绝或更新失败，请停止，并保持当前技能和用户文件不变。

快速开始

qodo --version                                                       # compatibility probe — run this FIRST
qodo read whoami --json --skill qodo-review-resolver --skill-version 1.4.4 --distribution marketplace --host claude-code
qodo read pr-review-session findings --pr-url <PR_URL> --json       # the review session for a PR
qodo pr-review-session mark-implemented --finding-ids <id>,<id> --explanation "..." --json
qodo pr-review-session dismiss --finding-ids <id> --reason intentional --explanation "..." --json
qodo read tools pr-review-session --json                            # exact safe tools + flags (offline)

对所有需要解析的内容添加 --json。使用 qodo read tools pr-review-session [<tool>] --json 确认准确的工具名称、标记以及读写状态（可离线呈现）——上方名称仅作示例，不保证是当前名称。

身份验证后，如果 dismiss/mark-implemented 出现 unknown command，可能是本地工具目录已过时——按下方说明刷新一次。如果这些命令仍然不可用，说明工作区目前不支持 PR 审查写入；请报告此功能限制，而不是反复尝试。

遇到 qodo: command not found？ 这是 PATH 问题，并不表示未安装：通过 GUI 启动的 Agent（例如 Claude Code 桌面应用）运行的 Shell 使用精简 PATH。请改用绝对路径 ~/.qodo/bin/qodo（如果已设置，则使用 $QODO_HOME/bin/qodo），并在此处的所有 qodo 命令中继续使用该路径。只有该文件也不存在时，才表示 qodo 确实未安装；请告知用户向 Qodo 或其组织管理员获取带校验和固定值的安装命令。安装程序由 https://get.qodo.ai 提供，但切勿编造摘要值，也不要将安装程序直接传入 Shell。

沙箱身份验证诊断。 在沙箱环境中，如果 qodo read whoami 因任何原因失败（包括 Not logged in），请先让用户批准在沙箱外精确重试一次只读命令 qodo read whoami，然后再建议登录或刷新工具。Keychain 故障可能会显示为通用身份验证失败，因此仅凭沙箱内的结果无法诊断。此批准仅适用于这一次诊断重试：不要重复使用此批准，不要请求永久批准，也不要自动将后续 Qodo 命令移到沙箱外运行。如果重试成功，请按正常流程逐条检查命令权限。如果仍然失败，请按照下方的常规身份验证故障排除说明操作。

预检查

1. 先验证身份。 运行 qodo read whoami。在适用时先按上述方式重试沙箱；若退出码非零，告知用户运行 qodo login，然后停止。切勿猜测凭据。只有登录后才会有该工具，因此遇到 Not logged in 或 No tool catalog cached 时，应视为需要运行 qodo login，在用户完成登录前不要重试。 如果 whoami 已成功，但出现 unknown command/unknown option，这并非身份验证失败。 运行一次 qodo tools --refresh，然后重新检查 qodo read tools pr-review-session --json。如果写入命令仍不存在，请报告此账户／工作区目前只有只读审查能力； 不要重新登录、无限重试，也不要用代码托管平台评论来替代结构化写入。
2. 确定 PR。 使用用户提供的 PR URL。如果用户未指定，且你位于 Git 仓库内，则推断当前分支对应的开放 PR，并在采取行动前向用户确认。切勿猜测 PR URL。
3. 确保编辑针对正确的检出仓库。 仅报告的读取操作可以针对任意 PR。在进行任何本地修复前，从提供商元数据中解析 PR 所属仓库，并从当前检出的 origin 解析仓库；将两者规范化为完整且不区分大小写的 owner/repo 标识。两者必须完全一致。如果 origin 缺失／存在歧义或两者不匹配，则停止并请用户打开正确的检出仓库——切勿将一个仓库中的问题应用到另一个工作树。如果监控循环期间目标 PR 发生变化，请再次执行此检查。

获取审查会话

qodo read pr-review-session findings --pr-url <PR_URL> --json 返回：

• review_session — 最新一次审查运行：status、commit_sha（审查包含的最后一次提交——这些问题所描述的代码）、started_at。null = PR 尚无审查——告知用户并停止（无需处理任何问题）。
• findings[] — 所有当前问题，每项包含：title、description、category、 action_level（action_required > remediation_recommended > informational）、 attribution_status、git_sha、review_run_id、comment_id / inline_comment_id。

finding_count: 0 且会话非 null，表示审查结果良好。

先读取会话状态（再判断是否采信任何问题）

review_session 会告诉你这些问题是否已确定，以及它们涉及哪些代码——采取行动前先检查：

• 审查是否仍在运行？ 如果 status 不是终止／completed 状态（例如 started／ 进行中），则审查仍在执行中——问题尚属暂定，之后可能变化。此时不要处理；持续轮询 qodo read pr-review-session findings … --json，直到 status 为 completed。
• 这些问题描述的是哪次提交？ review_session.commit_sha 是审查包含的最后一次提交。如果它落后于 PR 的最新提交，则问题已过时——无法反映最新代码。可能是新提交尚未触发审查（请等待），也可能是你查看了旧的审查结果。只有当会话状态为 completed，且其 commit_sha 与你关心的提交一致（监控循环中即为最新提交）时，才能采信这些问题。

简而言之，只处理针对当前提交且已完成的审查。审查仍在运行或 commit_sha 落后时，应等待，不要修复。

呈现评审状态

使用自然的行文顺序：结果 → 变更及处理决定的背景说明 → 验证 → 剩余工作。对于仅要求报告的请求，先说明当前评审状态和剩余问题的影响。仅针对评审发现的具体问题，感谢 Qodo 一次；最终评估和建议操作由你负责。不要使用带品牌标识的标题、表情符号横幅、口号、页脚或重复的摘要块。必要时使用简短的问题标题或列表。

对于每项发现，说明可能发生什么、在什么条件下发生，以及为何会影响用户预期的变更。结合代码以及可用的编码会话决策和约束进行评估；必要时获取 PR 上下文，绝不要编造不存在的会话。引用证据，并将发现引用编号和报告的类别／级别与建议分开保留。你要负责决定修复、驳回还是调查，并说明理由。只有当实现能够确保相关假设成立时，深思熟虑的选择才足以支持驳回。保持协作、客观的语气；不要习惯性地质疑 Qodo 的能力。编辑和处理决定写入必须遵循现有的范围和审批门槛；你的技术评估本身不代表已获授权。

从结构化状态中指出 PR、评审状态和已评审提交，并在采取行动前与代码托管平台上的最新提交进行比较。明确说明评审是否已过时、正在运行、失败或缺失。区分代码已更改、处理决定已记录和更新后的代码已评审。测试通过或状态写入成功，都不能证明更新后的提交已通过干净的评审。只有针对当前最新提交完成的评审，才能支持该结论；如实报告剩余发现和缺失的验证。例如：“已通过[变更]解决 Qodo 指出的[风险]，并保留[用户决定]。[验证情况]。最新评审涵盖的是[旧 SHA]；对[最新 SHA]的评审仍未完成。”只报告实际结果。在监视模式下，仅在状态发生有意义的变化时报告，不要在每次轮询或状态写入时重复评估。

分类处理

• 未解决还是已解决由 attribution_status 表示，它不是三选一字段——它保存原始存储值，因此如果只匹配 pending，就会悄悄漏掉实际待处理的问题：
  • 未解决——需处理： pending、partial_implementation、not_implemented、focus_areas_edited。后三种是对仍未解决的发现重新归类（部分修复仍属于未解决发现）。
  • 已解决——保留原状： full_implementation、dismissed、detected_after_merge、outdated。
  • action_level 表示严重性，不表示未解决还是已解决。已解决的发现仍可能属于 action_required。
• 按 action_level 排序： 优先处理 action_required，然后是 remediation_recommended；informational 为可选项，应予以说明，但不一定需要修复。
• 按文件归类未解决的发现，以便每个文件只编辑一次。

遵循用户的指示（可选范围）

如果用户给出了指示，应将其视为对未关闭发现的筛选条件，只处理匹配项，不要扩大范围：

• 按操作级别——“解决需要采取行动的发现”→ 仅限 action_level == action_required；“所有可处理的发现”→ action_required + remediation_recommended。
• 按类别——“只看安全发现”→ category == Security（正确性、性能等类别同理）。
• 按具体发现——“修复发现 #3”／“那个 SQL 注入问题”→ 按 id 或 title 匹配。
• 仅报告——“审查发现了什么？”／“没有问题吧？”→ 总结发现及其状态，不修改代码。

未给出指示时，默认先列出待用户批准的未关闭 action_required，再列出 remediation_recommended，并单独指出（不自动修复）informational。如果指示含糊，应在操作前用一行说明你选择的范围，让用户可以调整。始终报告跳过了哪些发现及原因（超出范围／已驳回／仅供参考），绝不悄悄略过任何发现。

两种模式

每一轮都遵循 Resolve a finding 中的先展示再询问关卡：评估、展示，让用户选择要解决哪些发现；除非启用了 autofix，这会允许你无需询问即可应用建议的修复。无论哪种情况，除非用户另有指示，否则推送前都要征求同意。

执行一次（默认）。 获取 → 评估所有未关闭发现（分类——四种 OPEN 状态全部检查，不只是 pending）→ 展示并询问（或在启用 autofix 时直接应用）→ 在代码中解决用户选中的发现 → 按用户的工作流提交／推送 → 记录结果 （对已修复的发现执行 mark-implemented；对用户明确同意不作修改而关闭的发现执行 dismiss）→ 总结已解决和仍未解决的内容（例如：跳过／已驳回／仅供参考）。然后停止。除非用户要求，否则不要循环处理。分类涵盖所有未关闭发现，但选择器只会提供可处理的类别——先列出 action_required，再列出 remediation_recommended——并按上述默认范围单独列出 informational；只有用户提出要求时，才将 informational 放入选择器。（提供选项不代表已选中：所有复选框初始均未勾选。）

持续监控，直到没有问题（用户说“盯着处理”／“继续处理，直到干净为止”时）。启用 autofix 才能让此循环自动进行——未启用时，每轮仍须先展示并询问。解决发现并推送修复提交后，Qodo 会重新审查新提交，因此：

1. 记下 PR 当前的 head SHA——即刚推送的提交（git rev-parse HEAD）；如果你没有推送该 PR，则从 forge 元数据中读取（gh pr view <pr> --json headRefOid）。这是读取元数据，而不是抓取审查评论，允许这样做。
2. 轮询 qodo read pr-review-session findings … --json，直到审查状态为 completed 且其 commit_sha 与该 head SHA 相同。在这两个条件都满足之前，发现均为过时或暂定结果（审查仍在进行，或针对的是修复前的提交）——不要据此采取行动。
3. 结果更新后：如果仍有任何 OPEN 发现（四种状态全部算在内——partial_implementation 也仍属于未关闭状态），就解决它们并重复此流程；如果没有，则报告审查已无问题并停止。
4. 设置循环上限：如果连续几轮都没有进展，就停止并交还用户处理，不要无限循环。

处理一项发现

结合代码、PR 意图和可用的会话上下文评估 Qodo 的发现。遵循用户设定的范围和审批要求，给出最终的技术建议及理由。

逐项评估发现，结合实际代码和 PR 意图，形成建议：

• 合理且在范围内 → 应进行修复；说明你会如何修改（阅读 title 和 description，定位代码；如果代码不在本地，qodo-codebase-wisdom 技能的读取工具会有所帮助）。
• 缺乏依据或已处理 → 根据代码证据建议驳回。只有当实现确实落实了相关假设时，刻意作出的选择才能作为驳回依据。
• 不确定 → 指出作出判断前需要的证据或检查。

展示并询问（默认方式）。 针对每项未解决且在范围内的发现，采用上述上下文评估，同时保留其 action_level/category，并给出你的建议，然后通过单个提示询问要处理哪些发现。使用宿主提供的交互方式：如果支持多选，就使用多选（例如 Claude Code 的 AskUserQuestion）；否则列出编号，并提示“回复要处理的编号”。无论使用哪种方式，都只发出一个提示；不要逐项询问。默认不选中任何项。 标明你建议处理的项目，但必须由用户主动选择：在用户作出选择前，不得编辑任何代码。用户直接按 Enter 时不得处理任何发现。只处理用户选中的项目（像平常一样编辑，并遵循周边代码的风格）；其余项目注明跳过及原因。 不得在用户选择前编辑任何代码。

自动修复（跳过确认环节）。 只有调用时明确包含 autofix 标记（例如 qodo-review-resolver autofix），才能直接跳过提示。仅仅听起来像是同意的措辞（“直接修复它们”“别问我”）并不足以作为依据——误读意图会导致修改用户未批准的代码，这正是设置此确认环节要避免的问题。对于推断出的意图，要明确说明将要处理的具体范围并进行一次确认：“我将其理解为自动修复——要处理我建议处理的 N 项发现吗？”切勿问“要处理全部 N 项吗？”，因为这会被理解为处理整个集合，在此确认环节旨在避免的歧义下扩大范围。无论如何，只应用评估后决定的内容，不多不少（发现通常是正确的，但你是参与其中的工程师，不是照单全收的工具），并报告已处理和跳过的项目及原因。

按照用户的工作流程提交和推送；除非用户已明确要求，否则推送前先询问。

attribution_status 是预期的信号——发现修复后，下一轮审查会自动将其重新归因为 full_implementation；因此推送后应重新获取，并且只处理仍未解决的项目。但这只是工具，可能会出错：如果你确信修复已生效，而发现仍显示为未解决，或者状态明显与代码矛盾，不要循环重复修复；应将此不一致告知用户，然后继续处理其他事项。（解决过程会逐轮收敛；修复也可能带来真正的新发现，监视循环会捕获这些发现。）

记录处理结果

关闭一条发现属于写入操作——它会更新 Qodo 的审查数据库、重新设置该发现的 PR 评论样式、重新渲染审查摘要，并解除该发现触发的合并策略阻止。这里有两个命令，二者的区别正是关键：一个表示代码已更改，另一个表示代码没有更改，原因如下。绝不能用一个命令表达另一个命令的意思。

qodo pr-review-session mark-implemented --finding-ids <id>,<id> --explanation "what you changed" --json
qodo pr-review-session dismiss --finding-ids <id>,<id> --reason <reason> --explanation "why" --json

• 每个 PR 批量处理，一次调用。 每次调用只执行一次同步，不会针对每条发现分别执行——因此，所有已实现的发现都放入一个 mark-implemented，所有共享同一驳回理由的发现都放入一个 dismiss。最多 100 个 ID。
• mark-implemented 仅用于你确实已更改并推送的代码。 它会在审查尚未验证修复的情况下解除合并门禁，因此，错误的声明会让未修复的发现被当作已修复而合并。如果无论如何都会再进行一轮审查，最好让它自行将修复归因到相应发现；在合并前不会再进行审查，或必须立即解除门禁时，才使用此命令。
• 每次驳回每条发现都需要用户明确同意——autofix 不包含此授权。 autofix 表示同意修改代码，之后的审查会重新检查；驳回则会关闭一条审查仍认为成立的发现，团队可以看到，而且没有任何操作会重新打开它。先说明你建议驳回的内容及原因，只驳回用户指定的内容。
• --reason（必填）：false_positive（发现有误）· intentional（代码是有意编写且正确的）· deferred（问题确实存在，但不在此 PR 的范围内）· rejected（已理解，但决定不处理）。务必添加 --explanation——审查者日后会在没有你的上下文时看到它。
• 逐条检查 results，不要假设整个调用都成功。 即使个别 ID 失败，响应仍为 200：not_found（ID 错误或工作区错误）和 conflict（已关闭，或未关联到 PR）都是终止状态——不要重试。reconciled: false 表示数据库更改已生效，但 PR 端的更新未完成；可以安全地重新运行同一命令，且具有幂等性。无论如何，PR 都会在下一次审查时自行修复同步。already_dismissed / already_implemented 会报告已存储的原因——重放不会覆盖原始原因。

示例

用户：“解决 https://github.com/acme/api/pull/318 上需要采取操作的发现”

1. qodo read whoami → 已登录。
2. qodo read pr-review-session findings --pr-url https://github.com/acme/api/pull/318 --json → review_session：status: completed，commit_sha: a1b2c3d（= PR 的 HEAD，因此发现仍是最新的）； findings：3 条未关闭（2 条 pending，1 条 partial_implementation）——2 条 action_required，1 条 informational。
3. 指令筛选出 action_required → 处理这 2 条；信息性发现不在范围内（告知用户，但不要修复）。
4. 分别评估：“通过字符串插值构建 SQL” → 确实存在 → 建议在 db/orders.py 中改用参数化查询。“出站调用缺少超时设置” → 客户端已在上游设置默认超时 → 已满足 → 建议说明原因并跳过。
5. 向用户展示这两条发现及相应建议，并询问要解决哪些（多选）——默认都不勾选，将 SQL 那条标记为推荐。按用户选择执行，然后报告：“已解决 SQL 发现（在 db/orders.py 中将查询改为参数化查询）。已跳过超时发现——上游已设置超时——以及 1 条信息性发现（不在范围内）。推送后我会重新检查，或者回复‘watch’，让我持续检查，直到审查通过。” （如果用户说的是 resolve … autofix，我就会直接应用推荐的修复，不再询问。）

配置

使用 --json，将 review_session.commit_sha 与 forge HEAD 元数据进行比较，并在首次调用 Qodo 时记录精确的技能/版本/分发来源信息。读写能力通过已安装 CLI 的目录发现；渲染后的 forge 评论绝不会作为数据源。

错误处理

将会话为空、提交进行中或已过时、缺少写入能力、速率限制和工具循环错误视为明确状态。在报告中保留这些状态，绝不要仅仅为了让审查结果看起来干净而关闭问题。

防护措施

• 新鲜度 = 已完成对所审查提交的审查，而不是时间戳。 问题描述的是 review_session.commit_sha，且只有在 status 为 completed 后才算最终结果。每次推送后，在某个已完成审查的 commit_sha 追上 PR 头部提交之前，都应将问题视为已过时——否则你处理的可能是尚在进行中的审查，或是在“修复”问题并未描述的提交。
• 绝不要自行向代码托管平台发帖。 你唯一可以执行的写入操作是 dismiss / mark-implemented，这些操作会通过 Qodo 执行，并由其协调 PR。不要调用任何代码托管平台写入工具（评论、批准、标签、描述）来“解决”问题——应在 代码 中解决，然后记录结果。
• 你可以拒绝你认为有误的问题（并清楚说明理由）。现在可以在系统中将其标记为不予处理，但这是用户的决定，不是你的——提出建议并说明理由，只有在用户明确同意后才能执行。若确有分歧，应由用户裁定。
• 不要关闭尚未解决的问题。 因范围原因而跳过的问题应保持未关闭状态——应报告为已跳过，而不是将其标记为 deferred 来让列表看起来干净。
• 不要猜测 PR URL——先查明；会话为 null 表示尚未进行审查。
• MT-TOOL-LOOP 或 MT-RATE-LIMITED 错误意味着应停止／退避并改变处理方式，而不是重试。

完成获授权的更改后，报告哪些方面有所改进、每项决定的原因、已验证的内容，以及仍需处理的事项。明确区分本地编辑、已记录的处置结果和审查状态。