SuperAPI AI 工具集

post-review-loop

编程与开发

查看项目

更新于 10-16 06:57

技能介绍

用途

Post-Review Loop 是一个面向代码变更的“实现后审查循环”工作流。它在代码实现已经存在之后进行事后审查,重点发现那些通过真实接口、状态、控制流、测试、文档或模块边界才变得可见的问题。该技能以显式 Codex 工作流的形式模拟 Pi 的 post-review-loop;由于 Codex 无法持有隐藏的扩展状态或注入后续提示,因此将循环状态保存在对话中(用于一次性工作)或可见的账本中(用于多轮或恢复的循环)。

主要能力

模式

从自然语言中解释用户请求的模式:

  • oneshot 或无模式:审查实现一次,可选地应用安全修复,验证并报告。
  • review-only:审查一次,不编辑文件。
  • start:创建持久循环账本并运行第一阶段。
  • continue 或 resume:读取账本并运行下一阶段。
  • status:报告当前生命周期、阶段、未解决的分桶、验证和下一步动作,不更改文件。
  • report 或 stop:渲染最终或当前报告。如果已经在工作,则在当前阶段后停止。
  • cancel:立即停止,如果存在账本则留下简短的取消说明。

默认审查范围是未提交的变更。如果用户指定了分支、提交范围、功能、文件列表或实现目标,则使用该范围。

账本

仅对 start、continue、resume、status、report 或无法在一轮内完成的工作使用显式账本。优先使用目标仓库根目录下的 reviews/post-review-loop.md,除非仓库已有更好的审查状态约定。

账本结构包含:生命周期(active | paused | finalizing | complete | cancelled)、范围、阶段(post-review | impl-review | impl | final-report)、迭代次数/上限、是否 review-only、基线;以及“审查了什么”“Bucket I - 安全范围内修复”“Bucket II - 需要决策”“已应用的代码变更”“验证”“阶段日志”等表格与章节。账本被视为权威来源:如果不在账本中,就没有发生。保持简洁,不要变成对话记录。

审查视角

在实现存在之后进行审查。在决定之前检查真实文件和差异:

  • 对于未提交的变更,检查 git status --short、git diff、git diff --staged 以及相关的未跟踪文件。
  • 对于分支、提交范围或指定范围,检查该目标及附近的接口、测试和文档。
  • 区分由变更引入的问题与仅仅被变更暴露出来的既有债务。
  • 干净的审查是有效的。不要编造发现。

将有意义的问题归类为恰好一个设计信号:简单的局部错误;验证或不变式缺口;所有权/边界不清;类型或模式模型薄弱;状态、生命周期、并发或顺序风险;过度抽象、抽象不足或重复逻辑;脆弱的集成或契约不匹配。

优先根因发现而非表面修饰。拒绝推测性偏好、宽泛的未来防护、微小辅助函数提取、命名修饰、孤立去重或日志美化,除非它们揭示了更广泛的边界、不变式、所有权、模式、生命周期、抽象或集成问题。

分桶

  • Bucket I 是自动修复轨道。仅当问题具体、安全、在范围内、有实质用处且现在可根因修复时使用。除非用户要求 review-only,否则自动应用 Bucket I 修复。
  • Bucket II 是决策轨道。当真正的改进需要产品、领域、架构、发布、兼容性、变更量或风险判断时使用。未经用户明确批准,不要实现 Bucket II。
  • Keep As-Is 用于在检查后拒绝的有意义关切,因为证据薄弱、当前结构值得保留,或变更会是过度纠正。

当安全的 Bucket I 修复暴露出可能的更广泛重新设计时,在适当情况下应用安全修复,并将更广泛的选项记录为 Bucket II,包含选项、权衡、建议以及为什么需要批准。当聚焦修复明显足够时,不要制造更广泛的选项。

阶段循环

持久循环使用以下阶段顺序:

post-review -> impl-review -> impl -> post-review -> ... -> final-report

阶段规则:

  • post-review:审查当前差异和附近架构。不编辑代码。记录 Bucket I 候选和 Bucket II 决策。
  • impl-review:针对真实代码路径和测试重新验证每个可操作的 Bucket I 项。不编辑代码。将安全项标记为已接受;拒绝、降级或将不确定项移至 Bucket II。
  • impl:紧密实现已接受的 Bucket I 修复。将已修复项标记为已应用,记录代码变更并验证。

每个阶段后的门控:

  • 在 review-only 中,审查报告后停止。
  • 如果范围/上下文不足,停止并说明需要范围或上下文。
  • 如果验证阻碍安全继续,停止并说明验证失败仍然存在。
  • post-review 后,仅当存在 Bucket I 候选且未达到迭代上限时继续。如果只剩 Bucket II,停止等待决策。
  • impl-review 后,仅当存在已接受的 Bucket I 工作且未达到迭代上限时继续。
  • impl 后,仅当至少应用了一个 Bucket I 修复时才继续到另一个 post-review。
  • 当没有已接受/可操作的 Bucket I 发现剩余时,干净地停止。

持久循环默认迭代上限为 5,除非用户给出其他限制。

Git 与验证

不要推送。除非用户明确要求此技能管理带提交的持久循环,或单独要求提交,否则不要创建提交。

当请求提交时:

  • 在循环开始时记录起始 HEAD。如果审查脏工作,仅暂存并提交与审查目标相关的变更;必要时使用部分块;保持无关工作不动。
  • 使用普通的项目提交信息。不要提及检查点、循环、自动化或内部 ID。
  • 在结束时,仅提交循环应用的编辑。如果相关编辑已经提交或没有循环编辑,不要创建重复提交。

在编辑后从仓库现有工作流运行聚焦验证。如果没有运行验证,说明原因。如果验证失败,修复由循环引起的失败,或清楚报告无关/既有失败。

输出

对于 oneshot、review-only 和最终报告,输出以下章节:

  • What I Reviewed:1-3 句简短说明。在有用时区分审查的文件与编辑的文件。

  • Applied / Resolved:列出已应用的 Bucket I 项,包含设计信号、根因、修复、文件和验证。如果没有应用自动更改,写“No automatic changes were applied.”。对于 review-only,将具体 Bucket I 发现列为 [recommended but not applied] 并说明 review-only 模式是未编辑的原因。

  • Needs Decision / Bucket II:列出决策、选项、建议、权衡以及为什么需要许可。如果没有未解决的 Bucket II 决策,写“No unresolved Bucket II decisions remain.”。

  • Keep As-Is:有意义但被拒绝的发现及原因,或省略微小的非发现。

  • Validation:命令和结果,或跳过原因。

  • Verdict:以下之一:No meaningful improvement identified;Applied straightforward design improvements;Applied improvements; decision needed for remaining tradeoff;Decision needed before refactor;Validation failure remains。

对于 status,保持响应更短:生命周期、阶段、迭代、Bucket I 已应用/可操作计数、Bucket II 未解决计数、最新验证结果和下一步动作。

使用方式

通过自然语言指定模式(oneshot、review-only、start、continue/resume、status、report/stop、cancel)来调用。默认审查未提交的变更,也可指定分支、提交范围、功能、文件列表或实现目标。持久循环会在目标仓库根目录创建 reviews/post-review-loop.md 账本(除非仓库已有更好的约定),并按照 post-review -> impl-review -> impl -> post-review 的顺序推进,默认迭代上限为 5。

适用场景

  • 代码实现完成后的事后审查。
  • 需要多轮、可恢复的审查循环。
  • 需要区分可自动修复的安全问题与需要人工决策的架构/产品问题。
  • 需要显式记录审查状态、验证结果和阶段进展的场景。

限制

  • 不推送代码。
  • 除非用户明确要求,否则不创建提交。
  • 未经用户明确批准,不实现 Bucket II 项。
  • 干净的审查是有效的,不应编造发现。
  • 默认迭代上限为 5,除非用户另行指定。
  • 关于收费、价格、平台支持等具体信息暂未提供。