pr-tour

PR 导览

从头到尾阅读差异的审查者，会按字母顺序阅读—— 这是 Git 打印的顺序，而不是最能说明问题的顺序。标注代码由 AI 编写，并不会让人们读得更仔细；改变他们首先阅读的内容才是关键。此技能会调整顺序：先看原因，再看重要文件，最后看噪声。

导览会引导注意力，但绝不做判断。它不会给出合并结论或安全结论，而且“已折叠”表示阅读价值低，绝不表示“已检查”。它以相同内容服务于人类（HTML）和 Agent（JSON）——对抗性审查者可以从高严重性事项开始查看。

脚本位于与此文件同级的 scripts/ 中（Node ≥ 18、零依赖、已登录 gh）。如果你是通过 HTTP 获取此文件，请使用 curl -sSL 将 scripts/*.mjs 和 references/config.md 获取为原始文本。

工作流程

0. 从干净状态开始。 在全新会话中运行审阅流程，绝不要在编写差异的会话中运行。作者无法指出自己的盲点。
1. 计算。 运行 node scripts/tour.mjs <pr-number>（在仓库外添加 --repo owner/name；PR 尚不存在时添加 --git main...feat/x；规格说明或审阅约定位于其他位置时添加 --spec <path>；要更改输出文件夹时添加 --out <dir>）。它会写入 .pr-review/tour-<n>.json——<n> 是 PR 编号，或 --git 模式下的分支名称——其中包含 FACT 项目、逐文件分类、阅读顺序，以及从找到的所有来源中提取的作者原文，并按重要性从高到低排列：规格说明（位于 docs/、specs/、.scratch/ 或 contracts/ 中，且文件名包含分支名称的 markdown 文件）、PR 描述、关联的问题和提交中的 #123 引用、提交消息、标题。意图状态为 spec、described、title only 或 UNKNOWN。最后，它会折叠噪声内容：锁定文件、重命名、格式调整和生成文件（ORM 快照、压缩包、大型机器生成的 JSON、带有生成标头的文件；完整列表见 references/config.md）。噪声文件绝不会列为 ASK WHY 文件。它会打印噪声行数。 空差异会在此处报错并停止。
2. 阅读差异，按阅读顺序进行（gh pr diff <n> 或 git diff），包括噪声内容——快速浏览即可；噪声只是为人类折叠显示，不代表你可以不读。在不检出代码的情况下，阅读 PR 头部版本的周边源代码（其他人可能共用此工作区）：运行 git fetch origin <head>，然后运行 git show "origin/<head>:<path>"（需加引号：zsh 会将 :a 和 :s 解析为修饰符）。其他涉及相同代码的未关闭 PR 也可以纳入审查范围：导致其他未关闭 PR 出问题的改动属于中等严重性问题。
3. 将 WHY 写入 .pr-review/tour-<n>.notes.json。完整格式、示例和严重性标准见 references/notes.md。简而言之：
   • attention——此处可选，但在 pr-triage 调用你时必须填写：PR 需要多少关注（critical / high / medium / low）、发生了什么、原因，以及触发这一判断的代码行。它会作为徽章显示在审阅流程顶部。
   • whatItDoes——用一到两句话说明差异实际上做了什么；显示为模型的解读，绝不代表作者的意图。
   • why、points、shape、diagrams、chapters——作者给出的理由（引用原文）、包含关键词链接的 3–5 行概述、1–3 个结构视图、在流程或结构发生变化时提供 0–2 个 Mermaid 图，以及按章节分组的逐步讲解。全部可选；见参考文档。
   • explains——意图映射：逐字引用作者所说的 PR 改动内容，并列出实现这些内容的代码文件。不要列出没有任何说明对应内容的文件——门禁会将它们列为 ASK WHY，而这份清单是审阅流程中最有用的部分。
   • claims——作者作出的、可核查的承诺（例如 “no change to guest checkout”），逐字引用，并逐条指向需要检查的代码行。
   • items——最多八条 LOOK HERE 指示，每条包含 severity、file、line、该行的逐字 code 片段、title、why。措辞应指出要检查什么，绝不能直接下结论。跳过 CI 已能发现的问题。
   • fileNotes——每个非噪声文件都要写：一个加粗的要点，然后列出 2–5 条项目符号。
4. 门禁检查。 运行 node scripts/annotate.mjs <tour.json> <notes.json>。如果引用并非作者原文、指示所指行不包含对应的 code、意图映射中包含噪声文件、条目超过八条，或出现判定性措辞，它都会拒绝。随后，它会生成未解释文件和未匹配引用，并重新计算阅读顺序。修正 notes，切勿修改检查逻辑；可以安全地重复运行。
5. 渲染。 运行 node scripts/render.mjs <tour.json>，会在其旁边写入 .html：单个文件中包含查看器和数据，无需服务器，可安全发布为 CI 工件。报告前先查看它——如果有浏览器，就在浏览器中查看（若 file:// 受阻，可使用 python3 -m http.server -d .pr-review 提供文件夹服务），否则至少确认 JSON 中的 WHY 面板文本无误。
6. 在聊天中报告：HTML 路径、意图状态、未解释文件、带有 file:line 的高严重性条目，以及噪声行数。

硬性规则

• 指出问题，不作判断。 不要说“LGTM”“看起来安全”“批准”“可利用”“没有问题”或“无需审查”。门禁会拒绝这些常见说法；不要换个说法来表达同样的意思。
• 绝不臆测意图。 只有作者的话才代表作者的意图。你的总结放在 whatItDoes 中，并标明这是你的总结。不要牵强引用来解释某个文件，只为让 ASK WHY 列表看起来没有问题——未作解释的文件就是一项发现，而不是失败。
• 事实来自脚本。 不要把 FACT 项目改述成自己的话，也不要将其驳回——如果某项 FACT 在上下文中无害，请在某条审查项或文件备注中说明原因，由审查者自行判断。
• 只读。 绝不要评论、批准或修改 PR，也不要编辑代码。输出内容为 .pr-review/ 中的两个文件。

巡查无法判断的内容

• 代码是否能运行。 运行它；巡查不会运行代码。
• 漏洞。 它会询问缺失的安全决策，不是扫描器——请在 CI 中运行真正的扫描器（Trivy、opengrep）。
• 并非无害的噪声。 锁文件可能包含恶意软件包；“仅格式调整”的文件是通过启发式方法检测的。折叠的文件只需点击一次即可查看，并会列出折叠原因。
• 差异之外的测试。 “没有名称相同的已更改测试”并不意味着没有测试覆盖该文件。

面向读取 JSON 的 Agent

intent.status 和 unexplained[] 展示了整体情况：作者说了什么，以及哪些已更改文件没有得到作者所说内容的解释。explains[] 将引用对应到文件；unmatched[] 列出没有匹配更改的引用。items[] 包含所有指示项：source（fact = 脚本，model = 已核对行号，map = 未解释文件）、severity、file、line、side、text、why。order[] 给出阅读顺序，并为每个位置说明 why；files[] 包含各个差异块。请从 severity: "high" 开始。intent.status: "UNKNOWN" 表示没有可供审查对照的规范——请明确说明，而不要猜测规范内容。架构说明见： references/config.md。

完成标准

• tour-<n>.json 已通过 annotate.mjs 检查，且 tour-<n>.html 已存在。
• 每条 LOOK HERE 指示项都指向差异中的实际行，且每项声明都是逐字引用。
• 聊天报告列出意图状态、未解释的文件以及高优先级项。

意图搜索顺序和新会话规则改编自 Matt Pocock 的 code-review 技能（MIT）。

最后验证时间：2026-09-25，使用 Claude Code（随 dmoka/skills #1 发布）