自动审查（Auto Review）

运行内置的结构化审查辅助工具，作为收尾检查。这是代码审查（code review），而非 Guardian 的 auto_review 自动审批路由。

当未显式指定引擎时，Codex 审查为默认模式。它通常提供最佳审查效果，应保持为常规最终收尾引擎。

适用场景：

• 用户明确请求 Codex 审查 / Claude 审查 / autoreview / 第二模型审查
• 完成非平凡的代码修改后、提交（commit）/发布（ship）前
• 在修复完成后，对本地分支或 PR 分支进行审查

审查原则（Contract）

• 将审查输出视为建议性意见，切勿盲目采纳。
• 对每一项发现，均须通过阅读真实代码路径及相邻文件予以验证。
• 若发现依赖外部行为，则需查阅对应依赖项的文档、源码或类型定义。
• 拒绝不切实际的边界情况、纯推测性风险、大范围重写，以及使代码库过度复杂的修复方案。
• 优先采用在恰当所有权边界内实施的小幅修复；除非能显著改善某类缺陷（bug class），否则不得执行重构。
• 持续迭代，直至结构化审查不再报告任何被接受/可操作的发现。
• 若因审查触发的修复改动了代码，则需重新运行聚焦测试，并再次调用结构化审查辅助工具。
• 对于安全审计抑制（suppression）类变更，须确保已接受的发现仍可审计：被抑制的发现保留在结构化输出中；活动输出中须保留不可绕过的抑制提示；聚合结果不得掩盖其他未关联的活跃风险。
• 切勿切换或覆盖用户所请求的审查引擎/模型。若审查因模型容量限制失败，请使用相同引擎/模型重试该命令数次。
• 对大型审查包请保持耐心。结构化审查在模型调用期间最长可达 30 分钟，尤其在启用 Codex 工具或网络搜索时。
• 将心跳日志行（如 review still running: ... elapsed=... pid=...）视作健康进展，而非卡死。只要心跳持续更新，即应允许辅助工具继续运行。当需要实时查看引擎原始文本输出时，可传入 --stream-engine-output 参数；Codex 和 Claude 会过滤工具/文件交互细节，其余引擎则透传原始输出。
• 切勿仅因审查静默 2–5 分钟，或仍在 30 分钟窗口期内运行而强行终止。仅在连续缺失多个预期心跳、超时 30 分钟，或子进程明显失败时才检查进程状态；优先让同一辅助命令自然完成。
• 工具在审查模式下非常有用。辅助工具默认允许只读检查工具和网络搜索，以便审查者核验依赖契约、上游文档及当前行为。
• 安全视角始终包含在内，但不应损害合法功能。仅当变更引入具体、可操作的安全风险，或移除了关键安全校验时，才报告安全问题。
• 为保障回归溯源（regression provenance），须区分以下角色：问题代码作者、问题 PR 作者、PR 合并者/提交者、当前 PR 作者、PR 日期。若无法追溯到具体被归责的 PR，则以被归责提交（blamed commit）为溯源依据：提交 SHA、日期与作者用户名。不得猜测合并者，亦不得将缺失的 PR 元数据本身作为独立发现上报。
• 若被归责 PR 由 clawsweeper[bot] 或其他自动化工具合并，请在可行前提下识别触发该操作的人类主体。优先检查时间线/评论；若受速率限制，则使用 gitcrawl/cache 或公开 PR HTML 页面。查找维护者指令，例如 @clawsweeper automerge、/landpr，或启用自动合并的标签/状态评论。报告格式为 automerge triggered by @login；若未找到，则标注触发者未知。
• 禁止在审查流程内部调用内置 codex review、嵌套审查器（nested reviewers）或审查面板（reviewer panels）。辅助工具仅构建一个审查包、调用一个选定引擎、验证一份结构化结果，并随即停止。
• 一旦辅助工具以退出码 0 结束且无任何被接受/可操作的发现，即应立即停止。切勿额外再运行一次审查，仅为获得更“干净”的收尾语句、寻求第二意见，或优化收尾措辞。
• 将辅助工具成功退出且无可操作发现视为干净审查结果，即使底层 Codex CLI 输出较为简略。
• 多审查员面板（multi-reviewer panels）仅限显式启用。仅在用户明确要求，或风险等级足以证明额外开销合理时使用；主代理仍须在修复前逐一验证所有被接受的发现。
• 若因属有意设计或无需修复而拒绝某项发现，仅当其能阐明未来审查者应知晓的真实不变量（invariant）或所有权决策时，才添加简短的内联代码注释。
• 若 gh/Gitcrawl 报错 database disk image is malformed，请先执行一次 gitcrawl doctor --json，使便携缓存完成自修复，再重试审查；除非修复失败且必须依赖实时 GitHub 数据，否则不得绕过 shim 层。
• 若 Gitcrawl 报告便携清单（portable manifest）不匹配、源/运行时数据库健康状态异常，或便携存储库（portable-store）检出陈旧，请先运行 gitcrawl doctor --json，并检查 source_db_health、runtime_db_health 和 portable_store_status 字段，再回退至实时 GitHub 查询。
• 切勿仅为执行审查而推送代码。仅当用户明确请求推送（push）/发布（ship）/更新 PR 时才推送。

目标选择（Pick Target）

存在本地脏工作区（dirty local work）时：

 --mode local

仅当补丁确实处于当前工作区的未暂存/已暂存/未跟踪状态时才使用此模式。--mode uncommitted 是 --mode local 的别名。对于已提交、已推送或 PR 相关的工作，请直接将辅助工具指向提交或分支差异（diff）；不要仅因辅助工具文档将“脏工作”置于首位就强制使用脏模式。干净的本地审查仅能证明本地无补丁。

分支/PR 工作：

 --mode branch --base origin/main

可选审查上下文为一等公民：

 --mode branch --base origin/main --prompt-file /tmp/review-notes.md --dataset /tmp/evidence.json

若存在已开启的 PR，请使用其实际 base：

base=$(gh pr view --json baseRefName --jq .baseRefName)
 --mode branch --base "origin/$base"

单次已提交变更：

 --mode commit --commit HEAD

或使用辅助脚本：

/Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --mode commit --commit HEAD

对已合入（landed）或已推送至 main 的工作，应使用提交审查（commit review）。在推送后，对干净的 main 与 origin/main 进行审查通常得到空 diff。对于小型提交栈，可显式逐个审查各提交，或在合并前使用 --base 审查整个分支。

并行收尾（Parallel Closeout）

若格式化可能改变行号位置，请先执行格式化。此后可并行运行测试与审查：

scripts/autoreview --parallel-tests ""

在 Windows 上，--parallel-tests 默认 shell 保留平台原生 cmd.exe 语义，与 Python 的 shell=True 行为一致。若聚焦测试命令专用于 PowerShell，请使用 --parallel-tests-shell powershell 或 --parallel-tests-shell pwsh。

权衡点：测试可能引发代码变更，导致审查结果过期。若测试或审查导致代码修改，则需重新运行受影响的测试，并重新执行审查，直至无任何被接受/可操作的发现为止。一旦该重审流程以干净状态退出，即应停止；无需再耗费一次长时间审查周期进行冗余确认。

审查面板（Review Panels）

对同一冻结审查包（frozen bundle）运行多个审查器：

 --reviewers codex,claude

--panel 是 Codex 加 Claude 的快捷写法，除非 --engine 显式更改首个审查器：

 --panel

显式设置各审查器的模型与推理/努力程度：

 --reviewers codex,claude --model codex=gpt-5.1 --thinking codex=high --model claude=sonnet --thinking claude=max

也支持内联语法：

 --reviewers codex:gpt-5.1:high,claude:sonnet:max

Codex 将 --thinking 映射至 model_reasoning_effort，接受值为 low、medium、high 或 xhigh；Claude 将 --thinking 映射至 --effort，额外支持 max。不支持真正推理调节能力的引擎将忽略 --thinking 参数。

上下文效率（Context Efficiency）

直接运行辅助工具，确保目标选择、引擎选取、结构化验证与退出状态全部统一于单一执行路径。若输出过于嘈杂，可在辅助工具返回后对其已完成输出进行摘要；切勿另派其他代理或审查器重复执行审查。

辅助工具（Helper）

OpenClaw 仓库本地辅助工具：

.agents/skills/autoreview/scripts/autoreview --help

agent-scripts 检出目录下的辅助工具：

skills/autoreview/scripts/autoreview --help

在原生 Windows 环境下，通过 Python 调用无扩展名的 Python 辅助脚本：

python skillsautoreviewscriptsautoreview --help

冒烟测试（smoke harness）基于共享 Python 实现提供了轻量级 Shell 封装：

skills/autoreview/scripts/test-review-harness --fixture benign --engine codex

skillsautoreviewscriptstest-review-harness.ps1 -Fixture benign -Engine codex

来自 agent-scripts 的全局辅助工具：

~/.codex/skills/agent-scripts/autoreview/scripts/autoreview --help

若从 agent-scripts 安装，路径为：

/Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --help

该辅助工具具备以下特性：

• 优先选择本地脏变更
• 接受 --mode uncommitted 作为 --mode local 的别名
• 否则，若 gh pr view 可用，则使用当前 PR 的 base
• 否则，对非 main 分支默认使用 origin/main
• 支持 --engine codex、claude、droid 和 copilot；默认为环境变量 AUTOREVIEW_ENGINE 或 codex；未设值时 Codex 应保持为默认引擎
• 仅从绝对 PATH 条目解析裸命名单词（如 git、gh、reviewer、PowerShell shell 命令），绝不从被审查的检出目录中解析；显式的相对路径参数（如 --*-bin）则从被审查仓库根目录解析
• 对已提交的工作（尤其是合入后的干净 main），请使用 --mode commit --commit
• 对 PR/分支工作，应保持 --mode auto 或显式指定 --mode branch；提交后切勿强制使用 --mode local
• 除显式指定 --output、--json-output 或启用实时流式引擎 stderr 外，仅向 stdout 写入输出
• 支持 --dry-run、--parallel-tests、--parallel-tests-shell、--prompt、--prompt-file、--dataset、--no-tools、--no-web-search 及提交引用（commit refs）
• 支持 --stream-engine-output 或环境变量 AUTOREVIEW_STREAM_ENGINE_OUTPUT=1，以在保持结构化验证的前提下实时显示引擎文本；Codex 与 Claude 隐藏工具/文件事件细节，仅输出紧凑的活动摘要，并在每轮（turn）结束时报告用量
• 支持通过 --panel / --reviewers 启用可选审查面板，并支持按引擎分别配置 --model 和 --thinking
• 默认允许只读工具与网络搜索（前提是所选 CLI 支持）；禁止在 prompt 中嵌套审查；Codex 通过 codex exec 执行，运行于只读 sandbox 中并生成结构化输出
• 在等待所选审查引擎响应的长周期内，若未开启流式输出且近期未见紧凑的 Codex 活动日志，则每隔一段时间向 stderr 打印 review still running: elapsed=s pid=
• 当所选审查命令以退出码 0 成功结束时，打印 autoreview clean: no accepted/actionable findings reported
• 当存在被接受/可操作的发现时，以非零退出码退出

最终报告（Final Report）

报告中应包含：

• 所使用的审查命令
• 运行的测试/验证项
• 被接受/被拒绝的发现及其简要理由
• 最终辅助工具/审查运行所得的干净审查结果，或对剩余发现被有意识拒绝的说明

切勿仅为优化最终报告措辞而额外运行一次审查。若最终辅助工具运行以退出码 0 结束且未报告任何被接受/可操作的发现，则如实报告该次运行即为干净审查结果。