pr-walkthrough

PR 漫游指南

创建一个本地静态 HTML/CSS/JavaScript 漫游指南，将当前分支的拉取请求呈现为四个独立的交互式 D3 视图，帮助审阅者从四个不同角度了解受影响的代码和 PR：

• 系统概览视图：简明、独立的代码概览，介绍 PR 涉及的子系统。不要将其呈现为图表，而应使用少量展开的组件卡片，为审阅者提供恰到好处的架构背景，帮助他们熟悉情况，然后开始审阅 PR。此视图中不要提及 PR、变更文件、审阅评论、差异链接、截图、规格说明或实现差异。
• 数据流图：展示状态、数据、事件、请求、文件、资源或渲染输出如何在变更后的系统中流转。
• 代码依赖关系图：展示变更后的组件之间的依赖关系、主要接口，以及哪些文件是入口点、哪些是叶子依赖项。
• 用户操作图：展示用户执行的操作、交互的界面，以及该操作如何流经实现。 这项技能是对基于画布理解 PR 的尝试。不要复刻幻灯片格式。不要把所有视角放在同一张图上。生成四个彼此独立的画布视图，供用户切换，并在每个视图中提供引导式导览，让网站从头到尾讲解 PR。根据 PR 的规模调整漫游指南：小型 PR 应像精简的审阅辅助工具，而非全面的架构文档。 这项技能不用于代码审查。不要生成新的审查发现、批准或要求修改的建议，也不要进行全面批评。请结合 PR/head commit 的完整代码库、PR 差异、PR 描述、PR 变更的规格说明，以及人工或 Agent 留下的现有审阅评论，制作帮助审阅者快速了解变更的导览图。

输出

在以下位置创建独立运行的网站：

• .warp/pr-walkthrough/index.html 该网站必须能通过 file:// URL 直接从本地文件系统加载。不得要求使用开发服务器、安装软件包、打包程序或构建步骤。 优先使用内联 CSS、内联 JavaScript 和内联数据，创建一个自包含的 HTML 文件。如果确实无法合并为单个文件，只能使用相对路径的本地文件，并避免使用 fetch()，因为浏览器限制可能会阻止读取本地文件。 D3 应从可信 CDN 加载，并使用官方固定版本。除非有明确理由，否则请使用辅助脚本的默认版本：
• https://cdn.jsdelivr.net/npm/[email protected]/dist/d3.min.js 不得使用未固定版本的 latest URL、非官方构建或动态软件包范围。不要在 UI 中反复显示 D3 实现免责声明。仅在相关时，将 CDN/运行时详细信息保留在验证日志或最终注意事项中。 如需可复用且确定性的 D3 渲染，请优先使用辅助脚本 scripts/d3_canvas_runtime.py。该脚本会生成符合 Brandalf 风格的 CSS、定义渲染器后再注入固定版本 D3 脚本的内联运行时加载器，以及支持缩放、平移、图表切换、搜索、节点详情、适配视图和导览控制的图形渲染器。请使用此辅助脚本，而不要为生成的漫游指南分别编写专用的 D3 初始化代码。 生成的画布必须视为需要验证的生成代码。报告漫游指南已就绪前，必须针对生成的 HTML 运行 scripts/validate_d3_canvas.py。如果画布无法初始化、D3 加载失败、缺少必需图表、导览控制不起作用、节点/边无法渲染，或在理应可用浏览器的环境中无法进行浏览器验证，请先排查问题并重新生成。如果确实无法使用支持浏览器的环境，请报告画布渲染未经验证，不要声称漫游指南已就绪。

品牌样式

生成或修改演练的视觉设计时，请使用 brandalf 技能。Brandalf 指向托管的 Warp 品牌事实来源；编写演练的 HTML/CSS 之前，请获取并应用该品牌规范。如果无法访问托管的品牌来源，请使用以下备用令牌，并在最终回复中说明这一限制。 除非获取的品牌来源另有说明，否则请采用以下 Brandalf 派生的默认设置：

• 使用 Warp 深色表面：页面背景为 #121212，面板为 #1e1e1d/#292929，文本为 #faf9f6 或 #ffffff。
• 有目的地使用 Warp 粉色强调色 #a43787，用于活动状态、关键链接、焦点环、选中的演示步骤和高强调标签。使用次要色绿色 #34895c、蓝色 #2e5d9e 和紫色 #754dac 作为图表颜色。
• UI/正文使用 Matter，并以 DM Sans, system-ui, sans-serif 作为后备字体。代码、元数据、画布标签、坐标、文件路径和面向机器的片段使用 Matter Mono，并以 Roboto Mono, ui-monospace, monospace 作为后备字体。
• 文案应求真、技术性强、简洁且可验证。避免营销式夸大和空泛的流行语。
• 优先采用简洁、文档风格的容器，并使用低调的边框。仅在有助于提升卡片、节点说明框、工具提示和按钮的可读性时使用圆角。 推荐的图表颜色：
• 系统概览视图：黄色 #c0872a
• 数据流图：绿色 #34895c
• 代码依赖图：蓝色 #2e5d9e
• 用户操作图：紫色 #754dac
• 活动/焦点/选中节点：粉色 #a43787

工作流

1. 确定 PR 背景

确定仓库根目录、当前分支和比较基准。 如果当前分支已有 GitHub PR，请使用 PR 的基准分支，并记录 PR URL，以便生成 GitHub 差异链接：

gh pr view --json baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files

如果没有 PR，请根据本地仓库惯例或远程默认分支推断基准分支：

git symbolic-ref --short refs/remotes/origin/HEAD

然后收集审查所需的输入：

git --no-pager diff --stat <base>...HEAD
git --no-pager diff --name-status <base>...HEAD
git --no-pager log --oneline <base>..HEAD
git --no-pager diff <base>...HEAD

在构建视图之前，根据变更行数、变更文件数和概念覆盖范围评估 PR 的规模。默认采用尽可能精简且实用的导览：

• 极小 PR：大约 1 个变更文件或少于 75 行变更。每个视图使用 2-3 个节点/卡片，每个视图包含 1-2 个导览步骤；除非截图/审查讨论节点能实质性地阐明行为，否则不添加这些节点。
• 小型 PR：大约少于 250 行变更或 1-3 个变更文件。每个视图使用 3-4 个节点/卡片，每个视图包含 2-4 个导览步骤；每个节点的摘要限制为 1 句话，最多再补充 1 条简短细节。
• 中型 PR：大约 250-800 行变更或若干相关文件。仅当每个节点都能讲解不同概念时，才在每个视图中使用 4-7 个节点。
• 大型 PR：仅当 PR 涉及多个子系统、引入新架构，或包含大量审查/规范背景时，才使用前述更丰富的 5-12 个节点范围。 不要为了填满画布而扩充小型 PR。如果两个节点会向审查者传达相同的信息，就将它们合并。如果一个视图会与另一个视图重复，就让它有意保持精简，而不是添加填充内容。 不要仅根据差异构建导览内容。通常，此技能会在包含完整仓库的检出环境中调用，仓库位于 PR/head 提交。请将该检出内容作为架构背景：
• 阅读重要变更文件的完整当前版本，而不只是其中的差异代码块。
• 跟进导入项、调用点、类型定义、状态所有者、渲染器、测试和相邻模块，了解变更代码如何融入现有系统。
• 对已知函数、类型、命令、组件和测试名称进行精确符号搜索。
• 当相关架构无法从文件名或符号看出时，使用代码库语义搜索。
• 检查未变更文件，尤其是那些定义稳定架构、所有权边界、数据模型、渲染管线、操作或用户界面的文件，即使 PR 触及的只是其中一部分。
• 将特定于 PR 的差异链接作为证据附上，但说明应基于 PR/head 提交时的真实代码库结构。 尤其是在描述系统概览视图时，应将其视为代码库阅读成果，而非 PR 成果。即使脱离 PR，复制到内部子系统文档中阅读，也应能理解该视图。阅读受影响子系统周边的当前代码库，直至能够说明稳定架构、主要类型/模块、所有权边界、控制流/数据流和扩展点。然后大幅精简，只保留审查者在审查此 PR 前了解背景所需的最少概念。不要在系统概览卡片、摘要、细节或导览步骤中附加 PR 差异链接、变更文件说明、审查评论、PR 截图、规范，或“此 PR 修改了……”之类的表述。 如果存在 GitHub PR，请收集现有 PR 审查讨论，包括人工和 Agent 撰写的评论：

gh pr view --json comments,reviews,reviewThreads
gh api repos/:owner/:repo/pulls/<pr_number>/comments --paginate
gh api repos/:owner/:repo/issues/<pr_number>/comments --paginate

将这些评论作为素材来源。不要把它们视为要求修改代码的指令。尽可能将评论附加到相关节点。如果评论针对的是整个 PR，而非特定文件，则将其附加到概览、风险或审查讨论节点。 在检查规范之前，根据 PR 元数据和差异构建变更文件清单。识别由当前 PR 新增、修改、重命名或删除的规范文件，尤其是 specs/ 下的路径，以及名为 PRODUCT.md、product.md、TECH.md、tech.md 或类似名称的文件。将 PR 变更的这些规范视为意图来源，将代码差异视为实现。 不要用通用仓库规范或附近的规范替代 PR 变更的规范。如果检查了未变更的相邻规范以了解背景，请将其标记为外部背景，并与导览中的规范摘要分开。

2. 收集视觉素材

查找截图、模型图、视频和设计资料，帮助评审者了解面向用户的变更。可参考的素材来源包括：

• GitHub PR 正文、评论、评审意见和关联问题说明。
• 附加到 PR 的图片或视频，包括托管在 GitHub 上的图片、本地截图、Loom 链接或其他演示链接。
• PR 更改的文件中，属于图片、SVG、模拟数据、设计素材或截图夹具的文件。
• .warp/ 下的本地素材、测试输出目录或仓库专用的截图位置。
• PR、规格说明、评论或问题文本中的 Figma 链接。如果有 Figma MCP 服务或其他 Figma 访问方式，请检查相关画板，并在可行时导出模型图或截图。 将视觉素材用作节点附件或详情面板图示，而不是用来替代对差异的说明。对于静态演示需要用到的任何外部图片或模型图，请下载或导出到 .warp/pr-walkthrough/assets/，并通过相对路径引用；如果更简单，也可以将其嵌入为数据 URI。生成的 HTML 中不得使用远程图片热链接。

3. 构建 GitHub 差异链接

每个更改文件引用、节点附件、代码摘录、文件路径和依赖关系边，都应链接回 GitHub PR 差异中的确切文件（前提是已知 PR URL）。优先链接到 PR 的 Files changed 标签页，而不是分支文件页面。 使用以下 GitHub PR 差异 URL 格式：

<pr_url>/files#diff-<file_anchor>

对于特定行的链接，请附加差异侧的行锚点：

<pr_url>/files#diff-<file_anchor>R<new_line>
<pr_url>/files#diff-<file_anchor>L<old_line>

其中：

• <pr_url> 是通过 gh pr view --json url 获取的规范 PR URL。
• <file_anchor> 是更改文件路径（按 PR 文件列表或差异中的 b/<path> 一侧）计算得到的小写十六进制 SHA-256 摘要。
• R<new_line> 链接到差异右侧／新增侧的行。
• L<old_line> 链接到差异左侧／旧侧的行。 请使用确定性的辅助程序生成锚点，而不要手动编写。

4. 将 PR 分析为四种引导视图

在编写 HTML 之前，先构建四个视图模型。每个视图都应包含关注点，而非每个变更文件。 对于每张图，请确定：

• 审阅者首先应了解哪个节点？
• 哪些节点顺序能从头到尾最好地讲清这个 PR？
• 对于图视图，哪些边连接这些节点？每条边说明什么关系？
• 哪些变更文件、规范、测试、视觉内容和现有审阅评论与各节点关联？
• 审阅者点击该节点时应检查什么？ 定稿之前，请根据 PR/头部提交中的实际源文件核对每个重要节点。对于系统概览视图，请先检查现有的所属模块和相邻的未变更模块，再通过差异确定要研究哪个子系统。对于其他图，请利用差异关联证据，并描述 PR 特有的路径。 每个视图都需要一段导览：包含节点 ID 序列和说明文字。导览应按审慎设计的顺序引导审阅者，而不应只是按任意文件顺序选择节点。 有向图必须通过视觉效果明确表示方向。数据流、代码依赖和用户操作的边必须显示箭头，且箭头应清晰地落在目标节点边界上，而不是消失在节点下方。边标签应描述从源节点到目标节点的关系方向。系统概览视图通常应没有边；如果觉得必须添加边，该视图可能又偏向图的范畴，应当简化。 请按以下角色设计视图：
• 系统概览视图：以独立代码概览的形式，讲解 PR 涉及的子系统架构。不要将其组织为 PR 变更清单、差异摘要、实现路径、依赖图、审阅清单或完整的子系统文档。对于此视图，不要附加 PR 差异链接、变更文件注释、审阅评论、PR 截图或规范/议题意图。对于小型 PR，优先使用 2-3 个稳定的组件概念；对于较大的 PR，仅在每张卡片都不可或缺时才使用 4-7 个。每张卡片的视觉尺寸应大于图节点，并应在画布中展示一段简短文字，而不只是标签。这段文字应定义组件及其对理解系统的意义，同时严格限定在审阅者审阅 PR 前建立基本认知所需的范围内。卡片标题、摘要、详情和导览步骤应描述系统的一般工作方式，且在 PR 之外仍然成立。适用时请明确设置卡片尺寸，例如 width: 340、height: 180 和 summaryLines: 5，以保持卡片简洁。
• 数据流图：着重说明信息或状态如何流动。从意图/规范输入开始，接着是来源/默认值/状态，然后是布局/渲染输出，最后是异步资源或验证循环。
• 代码依赖图：着重说明所有权和依赖方向。从规范/入口点开始，接着是模型/视图/命令的衔接处，然后是编辑器渲染元素，最后是测试。
• 用户操作图：着重呈现用户路径。从界面开始，接着是操作，然后是可见反馈和错误/加载状态。 对于非概览图，小型 PR 通常使用 3-5 个节点；较大的 PR 可使用 5-12 个节点。同一个概念可以出现在多个图中，但应使用各图专属的坐标和说明文字，并避免在不同视图中重复相同的解释。

5. 创建画布数据模型

将图数据以内联 JSON 的形式存储在 HTML 中，并赋值给 window.PR_WALKTHROUGH_D3_DATA。不要使用 fetch() 加载 JSON。 使用以下结构：

{
  "meta": {
    "title": "PR title",
    "prUrl": "https://github.com/owner/repo/pull/123",
    "baseRef": "master",
    "headRef": "feature-branch",
    "summary": "What the PR is trying to accomplish."
  },
  "graphs": [
    {
      "id": "system-overview",
      "label": "System overview",
      "color": "#c0872a",
      "summary": "Concise component overview for the affected subsystem.",
      "nodes": [],
      "edges": [],
      "tour": []
    },
    {
      "id": "data-flow",
      "label": "Data flow graph",
      "color": "#34895c",
      "summary": "How state and rendered output move through the change.",
      "nodes": [
        {
          "id": "intent",
          "title": "Intent",
          "kind": "overview",
          "x": 0,
          "y": 0,
          "summary": "The change this PR is trying to make understandable.",
          "details": ["Concise evidence-grounded explanation."],
          "files": [{ "path": "specs/example/product.md", "url": "<github_diff_url>" }],
          "comments": [{ "author": "reviewer", "body": "Existing review discussion.", "url": "<comment_url>" }],
          "links": [{ "label": "PR", "url": "<pr_url>" }]
        }
      ],
      "edges": [
        { "source": "intent", "target": "surface", "label": "default flows into" }
      ],
      "tour": [
        { "nodeId": "intent", "title": "Start with intent", "body": "Teach why this point matters." }
      ]
    }
  ]
}

坐标和缩放指南：

• 将起始节点放在偏左或偏上的位置。
• 在实际可行时，让导览路径从左到右或从上到下展开。
• 让相关节点彼此足够靠近，以便清晰显示导览步骤和边。
• 将低层级依赖放在调用方的更右侧或下方。
• 对于系统概览视图，将图节点替换为展开的参考卡片。使用更少的卡片、更大的卡片尺寸、段落长度的摘要，以及简单易读的布局。将同级架构组件紧凑地排布在中央子系统概念周围，而不是 PR 意图周围。此视图中不要包含 PR 证据、变更文件链接、评审评论、截图、规格说明或 PR 特定节点。优先使用 edges: []。
• 对于较小的 PR，保持图坐标紧凑，确保无需平移即可清晰查看每个视图。优先使用简短的从左到右链路，而非宽泛的关系图。

6. 构建静态网站

网站必须同时支持人类用户和浏览器自动化 Agent。 必需的 UI 行为：

• 一个由 D3 zoom 驱动、可缩放和平移的 SVG 画布，用于呈现当前激活的图。
• 可见的视图切换项：System overview、Data flow graph、Code dependency graph 和 User action graph。
• 可见的导览控件：Previous tour step、Next tour step、Restart tour，以及类似 Step 2 / 7 的指示器。
• 搜索输入框，用于搜索当前图中的节点标题、文件路径和附加的评论文本。
• 可点击的节点，点击后打开或更新持久显示的详情面板；如果该节点出现在导览中，还要同步导览至该节点。
• 表示关系含义的边标签。
• 键盘支持：
  • Right Arrow 或 n：进入下一导览步骤。
  • Left Arrow 或 p：返回上一步导览。
  • 1：切换至系统概览视图。
  • 2：切换至数据流图。
  • 3：切换至代码依赖图。
  • 4：切换至用户操作图。
  • + 或 =：放大。
  • -：缩小。
  • 0：重置缩放。
  • f：适配视图。
  • /：聚焦搜索框。
  • Escape：清除搜索内容或选择。
• 稳定的标题、按钮标签、data-graph-id、data-node-id、data-edge-id 和 data-tour-index 属性，以便计算机操作 Agent 能够可靠地点击浏览并捕获屏幕截图。 必需的内容行为：
• 在画布上方或旁边显示 PR 标题、base/head refs 和简短的意图摘要。
• 数据中恰好包含四个视图定义：system-overview、data-flow、code-dependency 和 user-action。
• 每个视图都必须有自己的节点和导览。数据流图、代码依赖图和用户操作图必须包含有向边。系统概览视图通常应不包含边，并使用较大的卡片和可见的段落文本，使其呈现为概览，而不是图。
• 有向图中的每条已渲染边都必须在目标节点处显示可见的箭头，并带有表示从源到目标关系的标签。
• 系统概览内容必须与 PR 无关，且范围严格受限。它应仅介绍评审 PR 所需的应用架构，帮助评审者了解背景；不得提及 PR、变更文件、评审评论、屏幕截图、规格或实现差异。PR 特有的证据和注释应放在数据流图、代码依赖图或用户操作图中。
• 每个导览步骤都必须指向一个节点，并说明该节点在讲解到此处时的重要性。
• 每个节点都必须在详情面板中包含说明文本。系统概览卡片还必须在画布上显示完整段落，并说明稳定的代码概念，而非 PR 变更。
• 每个变更文件引用都应链接到 GitHub PR 差异 URL。
• PR 中变更的规格必须表示为节点或节点附件。如果 PR 未变更任何规格，则加入明确的「未发现 PR 变更的规格」节点或说明。
• 现有的人类和 Agent 评审评论必须附加到相关节点，或汇总到评审讨论节点中。
• 可视化资料应作为节点附件显示在详情面板中。
• 对于极小和小型 PR，应将缺失的规格、评审讨论和视觉资料作为现有节点详情面板中的简短说明，而不是独立节点，除非这些内容会实质性地改变评审者对 PR 的理解方式。
• 使用符合 Brandalf 风格的 Warp 样式：深色 #121212 表面、灰白色文本、Matter/Matter Mono 字体、粉色活动强调色，以及品牌调色板中的图表颜色。 使用辅助工具输出：

python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --css
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --runtime
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data graph.json > .warp/pr-walkthrough/index.html

7. 验证演示

完成前：

1. 打开生成的 index.html 路径，或打印准确的 file:// URL。
2. 验证 HTML 不需要网络访问，唯一例外是明确记录并固定版本的官方 D3 CDN 运行时。
3. 确认 D3 使用具体的固定版本 URL，且未引用 latest 软件包。
4. 确认未使用 fetch() 加载本地 JSON/数据。
5. 确认图表数据仅包含所需的图表 ID：system-overview、data-flow、code-dependency 和 user-action。
6. 确认存在所有必需控件：Fit to view、Reset zoom、System overview、Data flow graph、Code dependency graph、User action graph、Previous tour step、Next tour step 和 Restart tour。
7. 确认浏览器中每个视图都能渲染节点/卡片；确认系统概览会渲染展开的段落卡片，且不包含 PR 特定附件；确认所有非概览图表都能渲染带有可见箭头的有向边。
8. 确认图表切换、导览导航、键盘快捷键、缩放、平移、适配视图、搜索和节点详情选择均可正常使用。
9. 确认每个图表都有非空导览，且每个导览步骤都指向现有节点。
10. 确认每个节点都有说明文字，并在适用时提供相关的变更文件链接；系统概览卡片除外，它们不应包含 PR 差异链接、变更文件注释、评审评论、截图、规格或实现差异。
11. 确认已获取 PR 变更的规格和现有 PR 评审评论，并已在图表中呈现，或明确报告其不存在/不可用。
12. 确认演示引用的截图、模拟图、Figma 导出文件、变更图片和视频缩略图均为本地相对路径资源或数据 URI，而非远程热链接。
13. 确认网站采用 Brandalf/Warp 样式。
14. 运行可复用的验证器：

python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .warp/pr-walkthrough/index.html --require-browser

如果验证失败，或无法在支持浏览器的环境中执行验证，请勿报告演示已就绪；应修复图表，或报告渲染尚未验证。

8. 使用 Cloudflare Pages 进行可选的公开发布

默认情况下，将演示文件保存在 .warp/pr-walkthrough/ 下，并排除在版本控制之外。如果用户要求可公开访问的 URL 或可重复使用的 CLI 发布工作流，请优先在演示通过验证后使用 Cloudflare Pages Direct Upload。 前提条件：

• 用户需要拥有 Cloudflare 账户。
• 如需在本地交互式使用，请运行一次 Wrangler 登录命令：

npx wrangler login

• 除非项目已存在，否则请创建一次 Pages 项目：

npx wrangler pages project create warp-pr-walkthroughs --production-branch main

使用生成的演示目录作为上传根目录：

npx wrangler pages deploy .warp/pr-walkthrough \
  --project-name warp-pr-walkthroughs \
  --branch pr-<pr-number>-$(git rev-parse --short HEAD) \
  --commit-dirty=true

如需稳定的“最新演示” URL，请改为部署到生产分支：

npx wrangler pages deploy .warp/pr-walkthrough \
  --project-name warp-pr-walkthroughs \
  --branch main \
  --commit-dirty=true

Wrangler 会打印部署 URL；对于非生产分支上传，还会打印部署别名 URL。请从标准输出中获取 URL 并告知用户。生产分支 URL 通常为：

https://warp-pr-walkthroughs.pages.dev

分支预览 URL 通常采用以下格式：

https://pr-<pr-number>-<sha>.warp-pr-walkthroughs.pages.dev

重要的发布注意事项：

• 新建的 Cloudflare Pages 项目可能会在预览子域名的 TLS 配置完成之前提供生产 URL。如果 Chrome 中的预览 URL 因 ERR_SSL_VERSION_OR_CIPHER_MISMATCH 而无法使用，请稍后重试，或使用 --branch main 部署，并立即分享生产 URL。
• 如果 wrangler 警告工作目录中有未提交的更改，请为不应提交的生成 .warp/ 文件传入 --commit-dirty=true。
• 对于私有代码或敏感 PR 上下文，除非用户明确接受公开暴露，否则请勿发布到公开 URL。请改用受保护的托管服务、Cloudflare Access 或本地 file:// URL。
• 在 PR 评论中仅发布简短的公开 URL；除非用户明确要求，否则不要将生成的 HTML 文件提交到代码库或嵌入其中。

导览启发式原则

决定要突出哪些内容时：

• 突出评审者理解 PR 目的、设计、架构和用户影响所需的最少关键点。
• 节点宜少而精。100–200 行的 PR 通常应生成简洁的导览，在所有视图中总计约包含 10–16 个节点／卡片，而不是 30 多个。
• 以 PR／头部提交中的完整代码库作为架构事实的依据。差异展示了哪些内容发生了变化，而现有代码则说明了这些变更部分的含义。系统概览视图应基于代码库探索，而不是基于差异。
• 对于系统概览，读者掌握足够信息来评审 PR 后就应停止；不要纳入所有间接涉及的子系统或每项实现依赖。
• 节点优先用于表示概念、子系统、状态所有者、用户界面、重要规范和评审讨论热点。
• 边优先用于表示因果关系、数据流动、调用／依赖方向和用户操作进程。
• 通过导览安排讲解顺序。图表可以展示关系，但导览应引导读者理解。
• 降低对生成文件、机械式重命名、纯格式变更和重复样板代码的强调。
• 说明每个高层要点为何需要各项底层依赖。
• 将行为或架构风险作为导览说明呈现，尤其是规范、PR 描述、测试或现有评审评论中记录的风险。
• 将测试关联到其验证的节点或边。
• 如果规范与代码不一致，应将差异表示为节点或注释，而不是将其隐藏。
• 不要尝试进行全新的代码评审。如果在引导评审者时发现了问题，应将其描述为需要检查的方面，而不是结论，除非 PR 评审讨论中已经提及。

最终回复

报告：

• 生成的导览路径。
• file:// URL。
• 推断出的基础分支和 PR 标题或分支名称。
• 用于差异链接的 GitHub PR URL。
• 是否找到并纳入了 PR 评审评论。
• D3 画布验证是否通过。
• 如果已发布，提供公开的 Cloudflare Pages URL，并说明它是生产环境 URL 还是分支预览 URL。
• 任何重要注意事项、缺失的规范，或无法执行的验证。