pr-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Walkthrough

PR指南

Create a local static HTML/CSS/JavaScript walkthrough that orients a reviewer to the current branch's pull request as four separate interactive D3 views. The walkthrough should help the reviewer understand the affected code and the PR from four distinct views:

System overview view: a concise standalone code overview for the subsystem touched by the PR. It should not feel like a graph. Present it as a small set of expanded component cards that give the reviewer just enough architectural context to get their bearings before reviewing the PR. Do not mention the PR, changed files, review comments, diff links, screenshots, specs, or implementation deltas in this view.
Data flow graph: how state, data, events, requests, files, assets, or rendered output move through the changed system.
Code dependency graph: which changed components depend on each other, where the major seams are, and which files are entry points versus leaf dependencies.
User action graph: what the user does, what surface they interact with, and how that action flows through the implementation. This skill is an experiment in canvas-based PR comprehension. Do not reproduce the slideshow format. Do not put all perspectives on one graph. Generate four separate canvas views that the user can toggle between, and provide a guided tour within each view so the site teaches the PR from start to finish. Scale the walkthrough to the PR size: a small PR should feel like a compact reviewer aid, not a comprehensive architecture document. This skill is not a code-review skill. Do not generate new review findings, approve/request-changes recommendations, or exhaustive critique. Use the full codebase at the PR/head commit, the PR diff, PR description, specs changed by the PR, and existing review comments from humans or agents to produce orientation maps that help a reviewer understand the change quickly.

创建一个本地静态HTML/CSS/JavaScript指南，以四个独立的交互式D3视图帮助评审人员了解当前分支的Pull Request。该指南需从四个不同维度帮助评审人员理解受影响的代码及PR：

系统概览视图：PR涉及子系统的简洁独立代码概述。不要将其设计成图形样式，而是以一组展开的组件卡片呈现，仅为评审人员提供足够的架构背景，帮助他们在评审PR前理清思路。此视图中不得提及PR、变更文件、评审评论、差异链接、截图、规格说明或实现差异。
数据流图：状态、数据、事件、请求、文件、资源或渲染输出如何在变更后的系统中流转。
代码依赖图：变更后的组件之间存在怎样的依赖关系，主要的衔接点在哪里，以及哪些文件是入口点、哪些是末端依赖。
用户行为图：用户执行的操作、交互的界面，以及该操作如何在实现流程中传递。该技能是基于画布的PR理解实验。请勿采用幻灯片格式，也不要将所有视角整合到一张图中。生成四个可切换的独立画布视图，并在每个视图内提供引导式讲解，让站点从头至尾讲解PR内容。根据PR规模调整指南内容：小型PR应作为紧凑的评审辅助工具，而非全面的架构文档。此技能并非代码评审技能。请勿生成新的评审结论、批准/要求修改的建议或详尽的批评意见。需利用PR/头部提交时的完整代码库、PR差异、PR描述、PR变更的规格说明，以及人工或Agent已有的评审评论，生成导向图谱，帮助评审人员快速理解变更内容。

Output

输出

Create a self-contained site at:

```
.warp/pr-walkthrough/index.html
```
The site must be loadable directly from the local filesystem with a
```
file://
```
URL. Do not require a dev server, package install, bundler, or build step. Prefer one self-contained HTML file with inline CSS, inline JavaScript, and inline data. If splitting files is unavoidable, use only relative local files and avoid
```
fetch()
```
because browser restrictions can block local file reads. D3 should be loaded from a pinned official release on a reputable CDN. Use the helper script's default unless there is a concrete reason to change it:
```
https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js
```
Do not use unpinned
```
latest
```
URLs, unofficial builds, or dynamic package ranges. Do not show repeated D3 implementation disclaimers in the UI. Keep CDN/runtime details in validation logs or final caveats only when relevant. For reusable deterministic D3 rendering, prefer the helper script at
```
scripts/d3_canvas_runtime.py
```
. It emits Brandalf-aligned CSS, an inline runtime loader that defines the renderer before injecting the pinned D3 script, and a graph renderer with zoom, pan, graph switching, search, node details, fit-to-view, and guided tour controls. Use this helper rather than writing one-off D3 setup code in each generated walkthrough. The generated canvas must be treated as generated code that requires validation. Before reporting that a walkthrough is ready, run
```
scripts/validate_d3_canvas.py
```
against the generated HTML. If the canvas fails to initialize, D3 fails to load, required graphs are missing, tour controls do not work, nodes/edges do not render, or browser validation cannot be performed in an environment where it should be available, debug and regenerate before saying the walkthrough is ready. If a browser-capable environment is genuinely unavailable, report canvas rendering as unverified instead of ready.

在以下路径创建一个独立站点：

```
.warp/pr-walkthrough/index.html
```
该站点必须可通过本地文件系统的
```
file://
```
URL直接加载，无需开发服务器、包安装、打包工具或构建步骤。优先使用包含内联CSS、内联JavaScript和内联数据的单一独立HTML文件。若无法避免拆分文件，仅使用相对本地文件，避免使用
```
fetch()
```
，因为浏览器限制可能会阻止本地文件读取。 D3应从知名CDN的固定官方版本加载。除非有具体理由更改，否则使用辅助脚本的默认地址：
```
https://cdn.jsdelivr.net/npm/d3@7.9.0/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加载失败、缺失所需图形、讲解控件无法工作、节点/边无法渲染，或在应支持的环境中无法进行浏览器验证，请调试并重新生成，再报告指南准备就绪。若确实无法使用支持浏览器的环境，请报告画布渲染未经验证，而非已就绪。

Brand styling

品牌样式

Use the

brandalf

skill when generating or revising walkthrough visual design. Brandalf points to the hosted Warp brand source of truth; fetch and apply it before writing the HTML/CSS for the walkthrough. If the hosted brand source is unavailable, proceed with the fallback tokens below and report the caveat in the final response. Apply these Brandalf-derived defaults unless the fetched brand source says otherwise:

Use a Warp dark surface:
```
#121212
```
for the page background,
```
#1e1e1d
```
/
```
#292929
```
for panels, and
```
#faf9f6
```
or
```
#ffffff
```
for text.
Use Warp pink accent
```
#a43787
```
intentionally for active states, key links, focus rings, selected tour steps, and high-emphasis labels. Use secondary green
```
#34895c
```
, blue
```
#2e5d9e
```
, and purple
```
#754dac
```
as graph colors.
Use Matter for UI/body text with
```
DM Sans, system-ui, sans-serif
```
fallback. Use Matter Mono for code, metadata, canvas labels, coordinates, file paths, and machine-oriented snippets with
```
Roboto Mono, ui-monospace, monospace
```
fallback.
Keep copy truth-seeking, technical, concise, and verifiable. Avoid marketing superlatives and generic buzzwords.
Prefer sharp, documentation-like containers with subtle borders. Use rounded corners only where they improve readability for cards, node callouts, tooltips, and buttons. Recommended graph colors:
System overview view: yellow
```
#c0872a
```
Data flow graph: green
```
#34895c
```
Code dependency graph: blue
```
#2e5d9e
```
User action graph: purple
```
#754dac
```
Active/focus/selected node: pink
```
#a43787
```

生成或修订指南视觉设计时，请使用

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
```

Workflow

工作流程

1. Establish PR context

1. 确立PR上下文

Identify the repository root, current branch, and comparison base. Use the PR base branch if the current branch already has a GitHub PR, and record the PR URL for GitHub diff links:

bash

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

If there is no PR, infer the base branch from local repository conventions or the remote default branch:

bash

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

Then collect the review inputs:

bash

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

Estimate PR size from changed lines, changed files, and conceptual breadth before building views. Default to the smallest useful walkthrough:

Tiny PR: roughly 1 changed file or under 75 changed lines. Use 2-3 nodes/cards per view, 1-2 tour steps per view, and omit screenshots/review-discussion nodes unless they materially clarify behavior.
Small PR: roughly under 250 changed lines or 1-3 changed files. Use 3-4 nodes/cards per view, 2-4 tour steps per view, and keep each node summary to 1 sentence plus at most 1 short detail.
Medium PR: roughly 250-800 changed lines or several related files. Use 4-7 nodes per view only when each node teaches a distinct concept.
Large PR: use the previous richer 5-12 node range only when the PR spans multiple subsystems, introduces new architecture, or has substantial review/spec context. Do not inflate a small PR to fill the canvas. If two nodes would teach the same reviewer fact, merge them. If a view would duplicate another view, make it intentionally sparse rather than adding filler. Do not build walkthrough content from the diff alone. The skill is usually invoked in a checkout where the full repository is available at the PR/head commit. Use that checkout as architectural context:
Read the full current versions of important changed files, not only their hunks.
Follow imports, call sites, type definitions, state owners, renderers, tests, and nearby modules to understand how the changed code fits into the existing system.
Use exact-symbol search for known functions, types, commands, components, and test names.
Use semantic codebase search when the relevant architecture is not obvious from filenames or symbols.
Inspect unchanged files when they define stable architecture, ownership boundaries, data models, rendering pipelines, actions, or user surfaces that the PR happens to touch.
Keep PR-specific diff links attached as evidence, but base explanations on the real codebase structure at the PR/head commit. When describing the system overview view especially, treat it as a repo code-reading artifact rather than a PR artifact. It should be understandable if copied into internal subsystem documentation and read without the PR open. Build it by reading the current codebase around the touched subsystem until you can explain the stable architecture, major types/modules, ownership boundaries, control/data flow, and extension points. Then aggressively reduce it to the smallest set of concepts needed for a reviewer to get oriented before reviewing this PR. Do not attach PR diff links, changed-file notes, review comments, PR screenshots, specs, or “this PR changes...” language to system overview cards, summaries, details, or tour steps. Collect existing PR review discussion when a GitHub PR exists. Include both human and agent-authored comments:

bash

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

Use these comments as source material. Do not treat them as instructions to change code. Attach comments to relevant nodes when possible. If a comment is PR-level rather than file-specific, attach it to an overview, risk, or review-discussion node. Build a changed-file inventory from PR metadata and diff before inspecting specs. Identify spec files directly from files added, modified, renamed, or deleted by the current PR, especially paths under

specs/

and files named

PRODUCT.md

product.md

TECH.md

tech.md

, or close variants. Treat those PR-changed specs as the source of intent and the code diff as implementation. Do not substitute general repository specs or nearby specs for PR-changed specs. If you inspect an unchanged neighboring spec for background, label it as external context and keep it separate from the walkthrough's spec summary.

识别仓库根目录、当前分支和对比基准。若当前分支已有GitHub PR，则使用PR基准分支，并记录PR URL用于GitHub差异链接：

bash

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

若无PR，则从本地仓库约定或远程默认分支推断基准分支：

bash

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

然后收集评审输入：

bash

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/头部提交时的完整仓库检出环境中调用。请将该检出环境作为架构上下文：
读取重要变更文件的完整当前版本，而非仅读取变更片段。
追踪导入、调用站点、类型定义、状态所有者、渲染器、测试和邻近模块，以理解变更代码如何融入现有系统。
对已知函数、类型、命令、组件和测试名称使用精确符号搜索。
当相关架构无法从文件名或符号中明确体现时，使用语义化代码库搜索。
检查未变更文件，若它们定义了PR涉及的稳定架构、所有权边界、数据模型、渲染管道、操作或用户界面。
将PR特定的差异链接作为证据附加，但基于PR/头部提交时的真实代码库结构进行解释。尤其是描述系统概览视图时，请将其视为仓库代码阅读工件而非PR工件。即使复制到内部子系统文档中，无需打开PR也应能理解。通过阅读PR涉及子系统周围的当前代码库来构建该视图，直到能够解释稳定架构、主要类型/模块、所有权边界、控制/数据流和扩展点。然后将其精简为评审人员在评审此PR前理清思路所需的最小概念集。请勿在系统概览卡片、摘要、详情或讲解步骤中附加PR差异链接、变更文件注释、评审评论、PR截图、规格说明或“此PR变更了...”相关内容。若存在GitHub PR，收集已有的PR评审讨论。包括人工和Agent撰写的评论：

bash

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. Collect visual source material

2. 收集视觉素材

Look for screenshots, mocks, videos, and design artifacts that can help reviewers understand the user-facing change. Useful sources include:

The GitHub PR body, comments, reviews, and linked issue descriptions.
Images or videos attached to the PR, including GitHub-hosted images, local screenshots, Loom links, or other linked demos.
Files changed by the PR that are images, SVGs, mock data, design assets, or screenshot fixtures.
Local artifacts under
```
.warp/
```
, test output directories, or repository-specific screenshot locations.
Figma links in the PR, specs, comments, or issue text. If a Figma MCP server or other Figma access is available, use it to inspect the relevant frames and export or screenshot the mock when practical. Use visual artifacts as node attachments or detail-panel figures, not as a replacement for explaining the diff. Download or export any external image/mock needed by the static walkthrough into
```
.warp/pr-walkthrough/assets/
```
and reference it with a relative path, or embed it as a data URI when simpler. Do not hotlink remote images in the generated HTML.

寻找有助于评审人员理解用户端变更的截图、原型、视频和设计工件。有用的来源包括：

GitHub PR正文、评论、评审和关联的问题描述。
PR附加的图片或视频，包括GitHub托管的图片、本地截图、Loom链接或其他关联演示。
PR变更的图片、SVG、模拟数据、设计资源或截图 fixtures 文件。
```
.warp/
```
下的本地工件、测试输出目录或仓库特定的截图位置。
PR、规格说明、评论或问题文本中的Figma链接。若有Figma MCP服务器或其他Figma访问权限，可实际检查相关框架并在可行时导出或截图原型。将视觉工件作为节点附件或详情面板插图使用，而非替代差异解释。将静态指南所需的任何外部图片/原型下载或导出到
```
.warp/pr-walkthrough/assets/
```
，并使用相对路径引用，或在更简单时嵌入为数据URI。请勿在生成的HTML中直接链接远程图片。

3. Build GitHub diff links

3. 构建GitHub差异链接

Every changed file reference, node attachment, code excerpt, file path, and dependency edge should link back to the exact file in the GitHub PR diff when the PR URL is known. Prefer links to the PR's Files changed tab rather than branch blobs. Use this GitHub PR diff URL format:

text

<pr_url>/files#diff-<file_anchor>

For line-specific links, append the diff-side line anchor:

text

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

Where:

```
<pr_url>
```
is the canonical PR URL from
```
gh pr view --json url
```
.
```
<file_anchor>
```
is the lowercase hex SHA-256 digest of the changed file path as it appears in the PR file list or the
```
b/<path>
```
side of the diff.
```
R<new_line>
```
links to a line on the right/new side of the diff.
```
L<old_line>
```
links to a line on the left/old side of the diff. Generate anchors with a deterministic helper instead of hand-writing them.

当已知PR URL时，每个变更文件引用、节点附件、代码摘录、文件路径和依赖边都应链接回GitHub PR差异中的对应文件。优先链接到PR的Files changed标签页，而非分支 blob。使用以下GitHub PR差异URL格式：

text

<pr_url>/files#diff-<file_anchor>

针对特定行的链接，附加差异端的行锚点：

text

<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. Analyze the PR as four guided views

4. 以四个引导视图分析PR

Build four view models before writing the HTML. Each view should contain points of interest, not every changed file. For each graph, decide:

What is the first node a reviewer should understand?
What sequence of nodes teaches the PR best from start to finish?
For graph views, what edges connect those nodes, and what relationship does each edge explain?
Which changed files, specs, tests, visuals, and existing review comments attach to each node?
What should the reviewer inspect if they click that node? Before finalizing content, cross-check each important node against the actual source files at the PR/head commit. For the system overview view, inspect the existing owning module and adjacent unchanged modules first, then use the diff only to identify which subsystem to study. For the other graphs, use the diff to attach evidence and describe the PR-specific path. Each view needs a tour: a sequence of node IDs and explanatory text. The tour should guide the reviewer in a deliberate order. It should not merely select nodes in arbitrary file order. Directed graphs must make direction visually explicit. Data-flow, code-dependency, and user-action edges must render with arrowheads that visibly land at the target node boundary rather than disappearing underneath the node. Edge labels should describe the relationship direction from source to target. The system overview view should normally have zero edges; if an edge feels necessary, the view is probably drifting back into graph territory and should be simplified. Use these view roles:
System overview view: teach the architecture of the subsystem the PR happens to touch as a standalone code overview. Do not structure it as a PR change list, diff summary, implementation path, dependency graph, reviewer checklist, or comprehensive subsystem documentation. Do not attach PR diff links, changed-file annotations, review comments, PR screenshots, or spec/issue intent to this view. For small PRs, prefer 2-3 stable component concepts; for larger PRs, use up to 4-7 only when every card is necessary. Each card should be visually larger than graph nodes and should expose a short paragraph in the canvas, not just a label. The paragraph should define the component and why it matters for orientation, while staying strictly limited to the context needed for a reviewer to get their bearings before reviewing the PR. Card titles, summaries, details, and tour steps should describe how the system works in general and should remain true outside this PR. Set card dimensions explicitly when useful, for example
```
width: 340
```
,
```
height: 180
```
, and
```
summaryLines: 5
```
for concise cards.
Data flow graph: emphasize how information or state moves. Start with intent/spec input, then source/defaults/state, then layout/render output, then async asset or validation loops.
Code dependency graph: emphasize ownership and dependency direction. Start with specs/entry points, then model/view/command seams, then editor rendering elements, then tests.
User action graph: emphasize the user path. Start with the surface, then the action, then visible feedback and error/loading states. A useful non-overview graph usually has 3-5 nodes for small PRs and 5-12 nodes only for larger PRs. It is okay for the same conceptual point to appear in multiple graphs with graph-specific coordinates and graph-specific explanatory text, but avoid repeating the same explanation across views.

在编写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. Create the canvas data model

5. 创建画布数据模型

Store graph data inline in the HTML as JSON assigned to

window.PR_WALKTHROUGH_D3_DATA

. Do not load JSON with

fetch()

. Use this shape:

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." }
      ]
    }
  ]
}

Coordinate and scale guidance:

Put start nodes toward the left/top.
Put the tour path left-to-right or top-to-bottom where practical.
Keep related nodes close enough that the tour step and edges are visually obvious.
Keep lower-level dependencies farther right/down from their callers.
For the system overview view, change the scale from graph nodes to expanded reference cards. Use fewer cards, larger card dimensions, paragraph-length summaries, and a simple readable layout. Place peer architectural components in a compact reference map around the central subsystem concept, not around the PR intent. Do not include PR evidence, changed-file links, review comments, screenshots, specs, or PR-specific nodes in this view. Prefer
```
edges: []
```
.
For small PRs, keep graph coordinates compact enough that each view is readable without panning. Prefer a short left-to-right chain over a broad map.

将图形数据以内联JSON形式存储在HTML中，赋值给

window.PR_WALKTHROUGH_D3_DATA

。请勿使用

fetch()

加载JSON。使用以下结构：

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. Build the static site

6. 构建静态站点

The site must work for both humans and browser automation agents. Required UI behavior:

One zoomable, pannable SVG canvas powered by D3 zoom that renders the currently active graph.

Visible view toggles:

System overview

Data flow graph

Code dependency graph

, and

User action graph

Visible tour controls:

Previous tour step

Next tour step

Restart tour

, and an indicator such as

Step 2 / 7

Search input for node titles, file paths, and attached comment text within the active graph.
Clickable nodes that open or update a persistent detail panel and sync the tour to that node when it appears in the tour.
Edge labels for relationship meanings.
Keyboard support:
- Right Arrow or
```
n
```
  : next tour step.
- Left Arrow or
```
p
```
  : previous tour step.
- ```
1
```
  : system overview view.
- ```
2
```
  : data flow graph.
- ```
3
```
  : code dependency graph.
- ```
4
```
  : user action graph.
- ```
+
```
  or
```
=
```
  : zoom in.
- ```
-
```
  : zoom out.
- ```
0
```
  : reset zoom.
- ```
f
```
  : fit to view.
- ```
/
```
  : focus search.
- ```
Escape
```
  : clear search or selection.
Stable headings, button labels,
```
data-graph-id
```
,
```
data-node-id
```
,
```
data-edge-id
```
, and
```
data-tour-index
```
attributes so a computer-use agent can click through and capture screenshots reliably. Required content behavior:
Show the PR title, base/head refs, and short intent summary above or beside the canvas.
Include exactly four view definitions in data:
```
system-overview
```
,
```
data-flow
```
,
```
code-dependency
```
, and
```
user-action
```
.
Each view must have its own nodes and tour. Data-flow, code-dependency, and user-action graphs must have directed edges. The system overview view should normally have zero edges and use larger cards with visible paragraph text so it reads as an overview, not as a graph.
Every rendered edge in a directed graph must use a visible arrowhead at its target node and a relationship label that reads source-to-target.
System overview content must be PR-agnostic and tightly scoped. It should educate the reviewer about only the app architecture needed to get oriented for reviewing the PR, without referencing the PR, changed files, review comments, screenshots, specs, or implementation deltas. Put PR-specific evidence and annotations in the data-flow, code-dependency, or user-action graphs instead.
Each tour step must point at a node and explain why that node matters at that point in the walkthrough.
Each node must have explanatory text in the detail panel. System overview cards must also show a full paragraph on the canvas itself and explain stable code concepts rather than PR changes.
Each changed-file reference should link to the GitHub PR diff URL.
PR-changed specs must be represented as nodes or node attachments. If the PR changes no specs, include an explicit "No PR-changed specs found" node or note.
Existing human and agent review comments must be attached to relevant nodes or summarized in a review-discussion node.
Visual artifacts should appear as node attachments in the detail panel.
For tiny and small PRs, represent missing specs, review discussion, and visuals as terse detail-panel notes on an existing node instead of standalone nodes, unless they materially change how the reviewer should read the PR.
Use Brandalf-aligned Warp styling: dark
```
#121212
```
surfaces, off-white text, Matter/Matter Mono typography, pink active accents, and graph colors from the brand palette. Use helper output:

bash

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

该站点必须同时适用于人类和浏览器自动化Agent。所需UI行为：

一个由D3缩放功能驱动的可缩放、可平移SVG画布，渲染当前激活的图形。

可见的视图切换按钮：

System overview

、

Data flow graph

、

Code dependency graph

和

User action graph

。

可见的讲解控件：
```
Previous tour step
```
、
```
Next tour step
```
、
```
Restart tour
```
，以及如
```
Step 2 / 7
```
的指示器。
搜索输入框，可搜索当前图形中的节点标题、文件路径和附加评论文本。
可点击的节点，用于打开或更新持久化详情面板，当节点出现在讲解流程中时同步讲解进度。
用于说明关系含义的边标签。
键盘支持：
- 右键箭头或
```
n
```
  ：下一个讲解步骤。
- 左键箭头或
```
p
```
  ：上一个讲解步骤。
- ```
1
```
  ：切换到系统概览视图。
- ```
2
```
  ：切换到数据流图。
- ```
3
```
  ：切换到代码依赖图。
- ```
4
```
  ：切换到用户行为图。
- ```
+
```
  或
```
=
```
  ：放大。
- ```
-
```
  ：缩小。
- ```
0
```
  ：重置缩放。
- ```
f
```
  ：适配视图。
- ```
/
```
  ：聚焦搜索框。
- ```
Escape
```
  ：清除搜索或选中状态。
稳定的标题、按钮标签、
```
data-graph-id
```
、
```
data-node-id
```
、
```
data-edge-id
```
和
```
data-tour-index
```
属性，以便自动化Agent可靠地点击并捕获截图。所需内容行为：
在画布上方或旁边显示PR标题、基准/头部分支和简短意图摘要。
数据中必须包含四个视图定义：
```
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字体、粉色激活强调色，以及品牌调色板中的图形颜色。使用辅助脚本输出：

bash

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. Validate the walkthrough

7. 验证指南

Before finishing:

Open the generated
```
index.html
```
path or print the exact
```
file://
```
URL.
Verify the HTML does not require network access except for the explicitly documented, pinned official D3 CDN runtime.
Confirm D3 uses a concrete pinned URL and no
```
latest
```
package reference.
Confirm
```
fetch()
```
is not used for local JSON/data loading.
Confirm graph data includes exactly the required graph IDs:
```
system-overview
```
,
```
data-flow
```
,
```
code-dependency
```
, and
```
user-action
```
.

Confirm all required controls are present:

Fit to view

Reset zoom

System overview

Data flow graph

Code dependency graph

User action graph

Previous tour step

Next tour step

, and

Restart tour

Confirm each view renders nodes/cards in a browser, confirm the system overview renders expanded paragraph cards with no PR-specific attachments, and confirm all non-overview graphs render directed edges with visible arrowheads.
Confirm graph switching, tour navigation, keyboard shortcuts, zoom, pan, fit-to-view, search, and node detail selection work.
Confirm every graph has a non-empty tour and every tour step points to an existing node.
Confirm every node has explanatory text and relevant changed-file links where applicable, except system overview cards, which should not include PR diff links, changed-file annotations, review comments, screenshots, specs, or implementation deltas.
Confirm PR-changed specs and existing PR review comments were fetched and either represented in the graphs or explicitly reported as absent/unavailable.
Confirm screenshots, mocks, Figma exports, changed images, and video thumbnails referenced by the walkthrough are local relative assets or data URIs, not remote hotlinks.
Confirm the site uses Brandalf/Warp styling.
Run the reusable validator:

bash

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

Do not report the walkthrough as ready if validation fails or cannot be performed in a browser-capable environment; fix the graph or report rendering as unverified.

完成前：

打开生成的
```
index.html
```
路径或打印精确的
```
file://
```
URL。
验证HTML除了明确记录的固定官方D3 CDN运行时外，无需网络访问。
确认D3使用具体的固定URL，而非
```
latest
```
包引用。
确认未使用
```
fetch()
```
加载本地JSON/数据。
确认图形数据包含所需的图形ID：
```
system-overview
```
、
```
data-flow
```
、
```
code-dependency
```
和
```
user-action
```
。

确认所有所需控件都存在：

Fit to view

、

Reset zoom

、

System overview

、

Data flow graph

、

Code dependency graph

、

User action graph

、

Previous tour step

、

Next tour step

和

Restart tour

。

确认每个视图在浏览器中渲染节点/卡片，系统概览视图渲染带有段落文本的展开卡片且无PR特定附件，所有非概览图形渲染带有可见箭头的有向边。
确认图形切换、讲解导航、键盘快捷键、缩放、平移、适配视图、搜索和节点详情选择功能正常。
确认每个图形都有非空的讲解流程，且每个讲解步骤都指向现有节点。
确认每个节点都有解释文本和相关的变更文件链接（适用时），系统概览卡片除外，它不应包含PR差异链接、变更文件注释、评审评论、截图、规格说明或实现差异。
确认已获取PR变更的规格说明和已有PR评审评论，并已在图形中表示或明确报告为缺失/不可用。
确认指南引用的截图、原型、Figma导出文件、变更图片和视频缩略图是本地相对资源或数据URI，而非远程直接链接。
确认站点使用Brandalf/Warp样式。
运行可复用验证器：

bash

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

若验证失败或无法在支持浏览器的环境中执行，请修复图形或报告渲染未经验证，不要报告指南已就绪。

Orientation heuristics

导向启发式规则

When deciding what to highlight:

Emphasize the smallest set of points of interest reviewers need to understand the PR's purpose, design, architecture, and user impact.
Prefer fewer, better nodes. A 100-200 line PR should normally produce a compact walkthrough with about 10-16 total nodes/cards across all views, not 30+.
Use the full codebase at the PR/head commit as the source of architecture truth. Diffs show what changed, but existing code explains what the changed pieces mean. The system overview view should be based on codebase exploration, not on the diff.
For the system overview, stop after the reader has enough bearings to review the PR; do not include every subsystem touched indirectly or every implementation dependency.
Prefer nodes for concepts, subsystems, state owners, user surfaces, important specs, and review-discussion hotspots.
Prefer edges for cause/effect, data movement, call/dependency direction, and user-action progression.
Prefer the tour for teaching order. The graph can show relationships, but the tour should guide comprehension.
De-emphasize generated files, mechanical renames, formatting-only changes, and repetitive boilerplate.
Explain why each high-level point needs each lower-level dependency.
Surface behavioral or architectural risks as orientation notes, especially when they are documented in specs, PR description, tests, or existing review comments.
Connect tests back to the node or edge they validate.
If specs and code diverge, represent the mismatch as a node or annotation instead of hiding it.
Do not attempt to perform a fresh code review. If you notice something while orienting the reviewer, frame it as an area to inspect rather than a finding unless it is already present in PR review discussion.

决定突出显示内容时：

强调评审人员理解PR目的、设计、架构和用户影响所需的最小关注点集合。
优先使用更少、更优质的节点。100-200行的PR通常应生成紧凑的指南，所有视图总计约10-16个节点/卡片，而非30+个。
将PR/头部提交时的完整代码库作为架构事实的来源。差异显示变更内容，但现有代码解释变更部分的含义。系统概览视图应基于代码库探索，而非差异。
对于系统概览，在读者获得足够导向以评审PR后停止；不要包含间接涉及的每个子系统或每个实现依赖。
优先为概念、子系统、状态所有者、用户界面、重要规格说明和评审讨论热点设置节点。
优先为因果关系、数据流转、调用/依赖方向和用户行为进程设置边。
优先使用讲解流程控制教学顺序。图形可显示关系，但讲解流程应引导理解。
弱化生成文件、机械重命名、仅格式变更和重复样板代码。
解释每个高级点需要每个低级依赖的原因。
将行为或架构风险作为导向注释呈现，尤其是当它们在规格说明、PR描述、测试或已有评审评论中有记录时。
将测试与其验证的节点或边关联起来。
若规格说明与代码不一致，将这种不匹配表示为节点或注释，而非隐藏。
请勿尝试进行全新的代码评审。若在为评审人员导向时发现问题，请将其表述为需要检查的区域，而非结论，除非它已在PR评审讨论中存在。

Final response

最终响应

Report:

The generated walkthrough path.
The
```
file://
```
URL.
The inferred base branch and PR title or branch name.
The GitHub PR URL used for diff links.
Whether PR review comments were found and included.
Whether D3 canvas validation passed.
Any important caveats, missing specs, or validation that could not be performed.

报告：

生成的指南路径。
```
file://
```
URL。
推断的基准分支和PR标题或分支名称。
用于差异链接的GitHub PR URL。
是否找到并包含PR评审评论。
D3画布验证是否通过。
任何重要的说明、缺失的规格说明或无法执行的验证。