SuperAPI AI 工具集

cross-review

编程与开发

查看项目

更新于 10-16 07:29

技能介绍

用途

cross-review 是一个交叉审查技能,用于让第二个模型审查另一个智能体会话的计划或已完成工作,或审查贡献者的 PR。其核心思路是:撰写工作的模型在长会话中会丢失上下文,因此审查应基于用户的要求和文件实际内容,而不是计划对自身的描述。

主要能力

  • 定位待审查的会话:从仓库根目录运行本技能的 scripts/session.mjs,用 --from 指定执行工作的运行时(在 Codex 中运行时传 claude,在 Claude Code 中运行时传 codex)。只有一个运行时的用户会得到同族审查,需传入自己的运行时并标注 same-family。
  • 支持按计划路径查找:加 --plan <path> 可找到撰写该计划的会话,即使该会话从其他目录启动。
  • 无参数时查找等待审查的会话(最后一条回复以交接行结尾的会话)。若有多个等待,会列出其 id 并以退出码 3 结束;此时应向用户展示列表、询问选择哪一个,再用 --pick <id> 重跑。
  • 支持 PR 审查:传入 PR 编号或 URL 时跳过脚本,走 PR 通道。
  • 默认搜索最近 30 天的会话,--days <n> 可扩大范围。
  • 输出会话中用户的原样提问、负责人的最后回复以及会话中出现的提交行。

使用方式

选择通道

  • 计划中通过 Topic: <slug> 行或项目 .agents/pstack.json 中 pageTopic.field 指定的 frontmatter 列表首项命名了主题时,计划只携带增量,<plans dir>/topics/<slug>.md 保存主题的当前状态。需将主题文件与计划一起阅读。
  • 根据工作状态选择审查方式:
    • Status: 为 planning 的计划:对照主题文件和用户提问审查计划,在计划中修复缺口,仅在主题文件错误陈述当前状态时修改主题文件。
    • 正在执行或已完成的计划,或无计划的会话:对照计划和用户提问审查会话的提交,仅报告发现。
    • 审查记录(如建议变更的裁决):对照其证据、权衡的替代方案、项目保留的范围历史(.agents/pstack.json 中 pageTopic.hub 指定的 hub 页面)和用户提问审查裁决,仅报告发现。
    • PR:对照其计划中的理由审查计划文件、描述和 diff,仅报告发现。

判断轮次

  • 第一轮审查覆盖全部工作。后续轮次为复审:决策日志已有早期审查(phase review 或 review-1)的行,或负责人的最后回复回应了某行。
  • 复审只检查上一轮 P0 和 P1 发现的修复以及负责人回退的编辑。其他发现最多为 P2。
  • 负责人已带理由拒绝的发现,只有在新证据下才能再次提出;否则作为分歧报告。
  • 最多两轮,因此复审时每个仍存在的 P0 或 P1 应作为分歧报告给用户,附双方立场。

审查 PR

  • 运行 gh pr view <n> --json title,body,files 和 gh pr diff <n>。
  • 无网络时(如 Codex 的只读沙箱),使用本地 ref(pr-<n> 或 refs/pull/<n>/head):git log 和 git diff $(git merge-base origin/<base> pr-<n>) pr-<n>,其中 <base> 是 PR 目标分支。离线时描述不可用,需说明审查仅覆盖计划和 diff。
  • 无本地 ref 时停止,请用户运行 git fetch origin pull/<n>/head:pr-<n>。
  • PR 在 plans 目录中没有计划文件是第一个发现。

阅读内容

  • 计划及其旁边的决策日志(<plan>.decisions.tsv),以及它们命名的每个文件、命令和提交。
  • 对于执行,读取计划、日志或会话命名的提交:git show --stat <sha>,然后逐个 diff。检出可能与其他会话共享,因此这些提交和路径之外的更改不属于审查范围。
  • 项目的智能体指令(AGENTS.md 或 CLAUDE.md),使每个发现遵循项目自身规则。

查找内容

  • 工作从未处理的提问,或处理方式与用户所述不同。
  • 没有证据的步骤、无法证伪其主张的证据,或没有其命名产物就关闭的复选框。
  • 声称已测量但文件中没有命令支持的声明。只读命令可重新计数时应重新计数。
  • 工作移除、削弱或矛盾的契约、法律或规则,以及仍依赖它的任何内容:调用方、测试、脚本、文档、CI 和生成文件。
  • 步骤会遗漏的重命名或删除。对每个旧名称运行 git grep。
  • 计划、日志、指令和文件之间的矛盾。
  • 步骤顺序导致仓库在步骤之间处于损坏状态。
  • 计划从未提及但代码可达的用例:输入、状态或路径。
  • 当廉价只读检查能解决发现时应重跑。修复或报告缺口;不要重新设计工作。

修复 planning 中的计划

  • 撰写计划的会话已停止,因此文件归你所有,直到用户回来。
  • 在计划本身修复每个缺口:缺失的用例、步骤或证据,步骤遗漏的重命名,矛盾,或破坏仓库的步骤顺序。
  • 每次更改在计划旁的决策日志追加一行,轮次为 phase review-1 或 review-2,结果以 applied: 开头。项目有辅助工具时使用它(node .agents/pstack/decisions-check.mjs append)。
  • 所有编辑保持未提交,留给负责人。
  • 绝不更改用户提问已确定的决策,或计划的结果、范围或状态。不同意时保持文件原样,并在报告中说明原因。

报告

  • 说明审查的会话或 PR 及轮次,然后给出裁决:无 P0 或 P1 剩余时为 ready,否则说明剩余数量。
  • 在 planning 通道,逐行列出每次编辑,然后列出会质疑的决策。
  • 然后最多十条编号发现,最严重的在前,针对未修复的缺口。每条说明优先级、显示它的文件与行号或命令,以及一句关于要更改什么的话。
  • 优先级定义:P0 破坏正常操作或安全(数据丢失、安全漏洞、构建或发布损坏);P1 构建错误的东西、破坏公共契约,或依赖未指定的步骤;P2 是负责人无需再次审查即可修复的真实缺口;P3 是可选的。
  • 保持在 500 词以内。没有发现时说 "no findings" 并说明检查了什么。

适用场景

  • 需要第二个模型对另一个智能体会话的计划或已完成工作进行独立审查时。
  • 需要审查贡献者 PR 的计划、描述和 diff 时。
  • 计划仍处于 planning 状态,需要直接修复缺口时。

限制

  • 除 planning 中的计划、其决策日志及其主题文件外,不编辑任何内容。
  • 绝不暂存、提交或推送,绝不在 PR 上留言或联系任何人。
  • 最多两轮审查。
  • 复审只检查上一轮 P0 和 P1 的修复及负责人回退的编辑,其他发现最多为 P2。
  • 报告保持在 500 词以内。
  • 会话搜索默认最近 30 天。
  • 离线时 PR 描述不可用,审查仅覆盖计划和 diff。
  • 检出可能与其他会话共享,提交和路径之外的更改不属于审查范围。