SuperAPI AI 工具集

agentic-review-handoff

编程与开发

查看项目

更新于 10-30 16:20

技能介绍

Agentic Review Handoff 是一个围绕「代码审查交接」设计的技能脚本集,核心目标是把可见的编码智能体(Fixer)与无头审查智能体(Reviewer)之间的审查—修复—复审流程标准化、可复现。

用途与路由: 技能首先要求先选路再加载参考文档。普通实现或纯提交请求不触发审查;用户只想要一份可复制的审查提示词、或明确使用 /codex:review / Grok /review 时,不应启动替代循环。仅当用户点名 Grok(含 grok00x 账户)做普通咨询或一次性审查时,走 Direct Grok 直连路径。显式要求 review-loop 自动循环、packet 或续跑请求时优先走协议。在没有实现者上下文的「复审一下」「第二双眼睛」「审计这个 diff」场景,走经典 intake。

主要能力:

  1. 自动循环(review-loop run):由脚本驱动,一轮一轮审查、修复、复审,默认预算 3 轮,PASS 时提前结束;预算耗尽输出结构化报告。每轮证据以冻结 diff 形式保存到 .review-handoff/runtime/<packet>/evidence/round-N.diff。
  2. Reviewer 选择:新运行没有默认 Reviewer,缺省 --reviewer 会以 REVIEWER_REQUIRED 失败。可显式指定产品/账户,或用 --host 让脚本读取用户保存的偏好(默认 claude,codex,grok,skipHost 为 false);偏好保存在 ${XDG_CONFIG_HOME:-~/.config}/agentic-review-handoff/config.json,可用 prefs 子命令查看、保存或重置。
  3. 超时回退:Reviewer 或咨询对端超时(默认 20 分钟,可用 REVIEW_LOOP_TIMEOUT_MS 覆盖)时,同一轮交给偏好列表中的下一个产品,在新会话中执行,并记录 fallbacks。只有超时才前进;用户停止或其他失败保持 DELIVERY_UNKNOWN。
  4. 修复完成与续跑:BLOCKED 或 concerns_require_fix 后,Fixer 修改代码并记录 fix-completion,再用 run --continue 续跑。默认 completion=pass 会把 PASS_WITH_CONCERNS 视为还需处理,可见 Fixer 修复范围内每个可执行问题后追加 Fix Completion 并复审,不向用户询问是否继续;仅 --completion=review 才把顾虑挂起在 awaiting_user_decision。
  5. 咨询(consult):可做建议性决策咨询,支持多轮续问同一会话、--web 增加搜索/抓取、--raw 发送原始文件。咨询不属于 Verdict 状态机。
  6. 证据复用:成功解析的轮次返回 evidence = { baseSha, pathFilter, digest, coveredPaths, sourceRound },相等性只比较 baseSha + pathFilter + digest;外层工作流在复用结论前必须运行 review-loop evidence 校验,不匹配或无有效身份则审查不可复用。
  7. 会话列表:sessions 子命令列出已记录的审查者与咨询会话并给出可复制的续跑命令。

使用方式(命令与安装): 脚本路径为 <skill-dir>/scripts/review-loop.mjs,常用命令包括:

  • node "$RL" run --repo "$REPO" --host=claude|codex|grok [--base <sha>] [--rounds 3]
  • node "$RL" run --repo "$REPO" --reviewer=codex|grok|claude [--reviewer-command=grok002] [--fallback=grok]
  • node "$RL" run --intake --repo "$REPO" --reviewer=...
  • node "$RL" fix-completion --repo "$REPO" --packet "$PACKET" --body-file /tmp/fix.md,随后 run --continue
  • node "$RL" consult --repo "$REPO" --host=claude --question-file /tmp/q.md
  • node "$RL" prefs、node "$RL" sessions、node "$RL" evidence、node "$RL" close 维护者同步方式为 pnpm skills:install:local -- --skill agentic-review-handoff。

只读边界与不变量: 审查与复审不得修改被审对象(源码、文档、测试、配置),不得 commit/push/rebase;但写入 .review-handoff/** 下的审查包属于协议行为,不算违规。三条不变量:使用 $repo_root/.review-handoff/ 下的绝对路径;无实现者上下文时绝不伪造 # Review Handoff(应使用 # Review Intake);H1 正文只在文件末尾追加,frontmatter 每阶段原子重写一次。首次写包前需确保 git common-dir 的 info/exclude 含 /.review-handoff/。可用全局或每包的 STOP 文件中止。

限制与注意事项: 启动失败应就地报告一次,不做 Docker/服务修复,不移动套接字、不改账户配置。Reviewer 静默不等于失败,子进程存活期间不要重试或另起 Reviewer;真正的超时不得重新提交给同一产品,只有脚本可按回退列表自动切换。--reviewer-command 只接受以产品名开头、定义在 rc 文件中的 zsh/bash 函数或 PATH 可执行文件,别名与 fish 函数无法解析。Direct Grok 路径不产生 packet 或 ledger,不宣称冻结证据或自动循环保证。测试命令与各项行为细节均源自原始资料提供的脚本与说明。