SuperAPI AI 工具集

autoreview

编程与开发

查看项目

更新于 11-12 07:51

技能介绍

用途

Auto Review 是一个用于代码收尾检查的结构化审查辅助工具。它在以下场景使用:用户要求 Codex/Claude 审查、autoreview 或第二模型审查;非平凡的代码编辑之后、最终提交或发布之前;修复后审查本地分支或 PR 分支。需注意这是代码审查,不是 Guardian 的 auto_review 审批路由。

主要能力

  • 默认使用 Codex 作为审查引擎(无引擎设置时),官方说明其通常给出最佳审查结果,建议保持为常规收尾引擎。
  • 支持 --engine codex、claude、droid、copilot,默认取 AUTOREVIEW_ENGINE 或 codex。
  • 将代码构建为单个审查包,调用一个选定的引擎,校验一个结构化结果后停止。
  • 默认允许只读检查工具和网页搜索,便于核对依赖契约、上游文档与当前行为。
  • 支持可选的多审查者面板(--panel / --reviewers),可为各引擎指定 --model 和 --thinking(Codex 映射为 model_reasoning_effort,接受 low/medium/high/xhigh;Claude 映射为 --effort,也接受 max)。
  • 支持 --stream-engine-output 或 AUTOREVIEW_STREAM_ENGINE_OUTPUT=1 流式显示引擎文本,同时保留结构化校验。
  • 长时间运行时向 stderr 输出心跳(如 review still running: <engine> elapsed=<seconds>s pid=<pid>),结构化审查在模型调用活跃期间最长可能耗时约 30 分钟。
  • 支持 --dry-run、--parallel-tests、--prompt、--prompt-file、--dataset、--no-tools、--no-web-search 及提交引用;除 --output、--json-output 或实时流式引擎 stderr 外只写入 stdout。
  • 当选定的审查命令退出码为 0 时打印 autoreview clean: no accepted/actionable findings reported;存在被接受/可操作的发现时以非零码退出。

使用方式

目标选择:

  • 未提交的本地改动:<autoreview-helper> --mode local(仅当补丁确实处于未暂存/已暂存/未跟踪状态时使用)。
  • 分支/PR:<autoreview-helper> --mode branch --base origin/main;若存在打开的 PR,用其实际 base:base=$(gh pr view --json baseRefName --jq .baseRefName),然后 <autoreview-helper> --mode branch --base "origin/$base"。
  • 已提交的单个变更:<autoreview-helper> --mode commit --commit HEAD。
  • 可附加上下文:<autoreview-helper> --mode branch --base origin/main --prompt-file /tmp/review-notes.md --dataset /tmp/evidence.json。
  • 并行收尾(先格式化,因格式化可能改变行位置):scripts/autoreview --parallel-tests "<focused test command>"。
  • 审查面板示例:<autoreview-helper> --reviewers codex,claude;--panel 是 Codex 加 Claude 的简写(除非 --engine 改变第一个审查者);可显式指定:<autoreview-helper> --reviewers codex,claude --model codex=gpt-5.1 --thinking codex=high --model claude=sonnet --thinking claude=max;或内联语法:<autoreview-helper> --reviewers codex:gpt-5.1:high,claude:sonnet:max。
  • 助手路径示例:.agents/skills/autoreview/scripts/autoreview --help、skills/autoreview/scripts/autoreview --help、~/.codex/skills/agent-scripts/autoreview/scripts/autoreview --help。

审查契约与限制

  • 审查输出仅供参考,绝不盲目应用;每条发现都要通过阅读真实代码路径与相邻文件核实,依赖外部行为时查阅依赖文档/源码/类型。
  • 拒绝不现实的边界情况、推测性风险、大范围重写以及会使代码库过度复杂的修复;优先在正确的所有权边界做小修复,除非能明显改善缺陷类别,否则不重构。
  • 持续进行直到结构化审查不再返回被接受/可操作的发现;若审查触发的修复改动了代码,重跑聚焦测试并重跑结构化审查助手。
  • 安全视角始终包含,但不应削弱正常功能;仅当变更产生具体、可操作的风险或移除重要安全检查时才报告安全发现。
  • 绝不切换或覆盖请求的审查引擎/模型;若遇到模型容量限制,用相同引擎/模型重试同一命令若干次。
  • 对大代码包保持耐心;不要仅因安静 2-5 分钟或仍在 30 分钟窗口内就终止审查;仅在多次缺失预期心跳、超过 30 分钟或子进程明显失败后再检查进程。
  • 不要在审查内部调用内置 codex review、嵌套审查者或审查者面板;助手只构建一个包、调用一个选定引擎、校验一个结构化结果后停止。
  • 多审查者面板仅限主动选择使用(明确要求或风险需要额外开销时),主代理仍需在修复前核实每条被接受的发现。
  • 若要拒绝某条发现为有意为之/不值得修复,仅当它解释了未来审查者应知的真实不变量或所有权决策时,才添加简短的行内注释。
  • 不要仅为审查而推送;仅在用户要求推送/发布/PR 更新时推送。
  • 若 gh/Gitcrawl 报告数据库磁盘映像损坏,先运行一次 gitcrawl doctor --json 让便携缓存修复后重试;若 Gitcrawl 报告便携清单不匹配、源/运行时 DB 健康错误或便携存储检出过期,先运行 gitcrawl doctor --json 并检查 source_db_health、runtime_db_health、portable_store_status,再回退到实时 GitHub。
  • 对于安全审计抑制变更,需验证被接受的发现仍可审计:被抑制的发现保留在结构化输出中,活动输出保留不可抑制的抑制通知,聚合发现不能隐藏无关的活动风险。
  • 回溯溯源时保持角色分离:被指责的代码作者、被指责的 PR 作者、PR 合并者/提交者、当前 PR 作者、PR/日期;若无可追溯的被指责 PR,使用被指责的提交作为溯源(commit SHA、日期、作者用户名),不要猜测合并者。若被指责的 PR 由 clawsweeper[bot] 或其他自动化合并,尽量识别人类触发者:先检查时间线/评论,若被限流则使用 gitcrawl/缓存或公开 PR HTML,寻找如 @clawsweeper automerge、/landpr 等维护者命令;报告由 @login 触发的自动合并,若未找到则说明触发未知。

最终报告

需包含:使用的审查命令、运行的测试/证明、被接受/拒绝的发现及简要原因、最终助手/审查运行给出的干净结果,或剩余发现被有意拒绝的理由。不要仅为改善最终报告措辞而再跑一次审查;若最终助手运行退出码为 0 且未产生被接受/可操作的发现,即报告该次运行结果为干净。