SuperAPI AI 工具集

walk-pr

编程与开发

查看项目

更新于 10-16 06:55

技能介绍

用途

walk-pr 用于带领用户逐步走查一个 PR 或大型 diff。它一次只处理一个子变更集(sub-changeset,简称 SC)——即一组放在一起看才合理的文件——并在每个 SC 内一次只讨论一个评审主题。它既适用于走查自己的 PR,也适用于走查他人的 PR。

读者模型

该技能假设评审者身处仓库之中,但对当前 PR 没有任何上下文。代码库已有的词汇是双方共享的基础;而 PR 新引入的词汇——新类型、新模式、新模块、新领域术语——则不是共享的,必须在下游内容使用它们之前先做明确介绍。

注意力契约

该技能的所有模式都服务于同一份契约:先给高层定位,一次只激活一个想法,深度内容(理由、代码、diff、长文本)只在评审者主动要求时才呈现。在聊天模式下,这体现为一次一个 SC、一次一个主题的纪律;在 canvas 模式下,则体现为一张可视化地图,所有文本内容都藏在点击之后。每当出现展示方式的选择时,要避免的失败模式都是“文字墙”:绝不在评审者面前堆砌超过当前想法所需的内容。

开场定位

在变更概览之前先呈现 PR 入门说明:用工作流词汇写一段问题陈述;并且仅当这些内容确实承重时,才补充概念词汇表(工作流层面的定义,而非类型签名)、组件草图或阅读提示。随后给出分类概览(承重内容与脚手架/数据分开,信号最强的排在最前);对于琐碎的 diff,这两者都可跳过。

每个子变更集:按需展开深度

每个 SC 始终可见的表面只有两句话:一句行为摘要(对用户而言发生了什么变化)和一句验证探针(如何观察到它确实生效)。其余一切——边界视图、主题、diff——都是评审者仅在需要时才展开的深度内容。

深度内部:边界优先

展开深度时,先给出边界视图:在模块边界的高度上写不超过三段短文字——新增/变更的类型、模块边缘的签名、依赖边的变化、契约变更——只写承重部分,不做清单式罗列。diff 片段是按文件、按需提供的证据,而不是默认的展示内容。之后才进入主题。

主题形态

评审主题(探针、权衡、建议)一次只呈现一个。每个主题由两条陈述句组成:先用代码库词汇具体框定关注点,再给出建议结论。不使用嵌套从句,不嵌入论证,不叙述推理过程。理由、代码摘录和备选方案放在支撑材料中(后续消息或按需探针),而不是放在标题句里。在用户回应之前不要推进。不要批量提问——“对这些问题一起说说你的想法?”正是该技能要防止的失败模式。当证据仍然支持时,面对反驳要守住立场。

分类整理,然后发布

逐主题捕获用户的回应。走查完成后,对每一个捕获项——主题回应和自由笔记一视同仁——进行三分类:

  • 已定稿的结论,将成为草稿评论;
  • 评审者提出的、你必须先回答的问题——从代码、仓库的 ADR,以及该 PR 所实现的设计文档中寻找答案(去获取该文档;设计与实现的偏差是极佳的评审素材)——因为调查常常会推翻或重塑原本要发的评论;
  • 不产生任何内容的丢弃项。

然后与评审者逐条确认拟发布的评论——批量审批表会重新制造该走查本要防止的过载——每条评论在能对应到具体代码位置时锚定到行,否则锚定到文件级或 PR 级。所有条目锁定后,使用可用的 GitHub 评审机制将它们作为单次 PR 评审发布。PR 作者是否以及如何处理这些评论,是下游 manifest 工作流的职责,不属于 /walk-pr。

--canvas 模式

加载 references/CANVAS_MODE.md。HTML 产物取代聊天成为走查界面——而且它是一张图,不是一份文档:一张持久化的 PR 系统地图,带有分步叙事、固定的评审主题、随处评论功能,以及按需抽屉中的 diff;它一次性预先生成并立即打开。用户自行控制节奏导航,并将整合后的评审包交回聊天,由上述分类整理流程接手。

输入

输入可以是 PR 编号、PR URL、diff 范围,或什么都不给(此时推断当前分支的 PR;回退到 origin/main..HEAD)。