需要为 Pull Request 生成可交互 D3…

当用户想要一个可缩放、可切换的 PR 可视化导览（系统概览、数据流、代码依赖、用户操作）时，生成一个本地静态 HTML 站点。

适用场景

解决思路

1. 确定 PR 上下文：识别仓库根目录、当前分支和比较基线。若当前分支已有 GitHub PR，用 `gh pr view --json baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files` 获取基线分支并记录 PR URL；若无 PR，用 `git symbolic-ref --short refs/remotes/origin/HEAD` 推断默认分支。
2. 收集评审输入：运行 `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`。
3. 根据改动行数、文件数和概念广度估算 PR 规模，默认生成最小可用导览：Tiny PR（约 1 个文件或 <75 行）每视图 2-3 个节点/卡片、每视图 1-2 个导览步骤；Small PR（<250 行或 1-3 个文件）每视图 3-4 个节点、每视图 2-4 个导览步骤；Medium PR（250-800 行）每视图 4-7 个节点；Large PR 仅在跨多个子系统或引入新架构时使用 5-12 个节点。不要为填满画布而膨胀小 PR。
4. 不要仅凭 diff 构建内容：阅读重要改动文件的完整当前版本，追踪 imports、调用点、类型定义、状态所有者、渲染器、测试和邻近模块；用精确符号搜索和语义代码库搜索理解架构；检查定义稳定架构、所有权边界、数据模型、渲染管线、动作或用户界面的未改动文件。
5. 收集已有 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`。把评论作为素材而非修改代码的指令，附加到相关节点。
6. 从 PR 元数据和 diff 构建改动文件清单，识别 PR 直接新增/修改/重命名/删除的 spec 文件（如 `specs/` 下、`PRODUCT.md`、`product.md`、`TECH.md`、`tech.md` 等）。以 PR 改动的 spec 为意图来源，代码 diff 为实现。不要把通用仓库 spec 或邻近 spec 当作 PR 改动 spec。
7. 收集视觉素材：PR 正文/评论/评审/关联 issue 中的截图、mock、视频；PR 附件图片/视频；PR 改动的图片、SVG、mock 数据、设计资产；`.warp/`、测试输出目录下的本地产物；PR/spec/评论中的 Figma 链接（若有 Figma MCP 则导出相关 frame）。把外部图片下载到 `.warp/pr-walkthrough/assets/` 用相对路径引用，或嵌入为 data URI，不要热链远程图片。
8. 构建 GitHub diff 链接：每个改动文件引用、节点附件、代码片段、文件路径和依赖边都应链接回 PR diff 中的确切文件。使用格式 `<pr_url>/files#diff-<file_anchor>`，行级链接追加 `R<new_line>` 或 `L<old_line>`。`<file_anchor>` 是改动文件路径的小写十六进制 SHA-256 摘要，用确定性辅助脚本生成而非手写。
9. 在写 HTML 前构建四个视图模型，每个视图包含关注点而非所有改动文件。对每个图决定：评审者应首先理解的节点、从开始到结束教学 PR 的最佳节点序列、连接节点的边及其关系、每个节点附加的改动文件/spec/测试/视觉/评审评论、点击节点应检查什么。
10. 为每个视图设计导览：节点 ID 序列加解释文本，按刻意顺序引导评审者，而非按文件顺序任意选择。
11. 有向图必须视觉上明确方向：数据流、代码依赖、用户操作边必须用箭头明确落在目标节点边界，边标签描述从源到目标的关系。系统概览视图通常零边；若需要边说明已偏离为图，应简化。
12. 按视图角色构建内容：系统概览视图教学 PR 所触及子系统的架构，作为独立代码概览，不提及 PR、改动文件、评审评论、diff 链接、截图、spec 或实现差异，卡片标题/摘要/详情/导览步骤描述系统一般工作方式且在本 PR 外仍成立，卡片尺寸显式设置如 `width: 340`、`height: 180`、`summaryLines: 5`；数据流图强调信息/状态移动，从意图/spec 输入开始，经源/默认值/状态、布局/渲染输出，到异步资产或验证循环；代码依赖图强调所有权和依赖方向，从 spec/入口点开始，经模型/视图/命令接缝、编辑器渲染元素，到测试；用户操作图强调用户路径，从界面开始，经动作、可见反馈和错误/加载状态。
13. 把图数据内联存储在 HTML 中作为 `window.PR_WALKTHROUGH_D3_DATA` 的 JSON，不要用 `fetch()` 加载 JSON。数据结构包含 `meta`（title、prUrl、baseRef、headRef、summary）和 `graphs` 数组，每个 graph 含 id、label、color、summary、nodes、edges、tour。
14. 坐标与缩放：起始节点放左/上，导览路径尽量从左到右或从上到下，相关节点靠近，低层依赖放在调用者右/下方。系统概览视图用更少卡片、更大尺寸、段落级摘要和简单可读布局，把同级架构组件放在中心子系统概念周围的紧凑参考图中，优先 `edges: []`。小 PR 保持坐标紧凑，无需平移即可阅读。
15. 构建静态站点：必须可直接用 `file://` URL 从本地文件系统加载，不需要 dev server、包安装、打包器或构建步骤。优先单个自包含 HTML 文件（内联 CSS、JS、数据）；若必须拆分文件，只用相对本地文件并避免 `fetch()`。D3 从可信 CDN 加载固定官方版本，默认 `https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js`，不要用未固定 `latest`、非官方构建或动态版本范围。
16. 优先使用辅助脚本 `scripts/d3_canvas_runtime.py` 生成可复用的确定性 D3 渲染：它输出 Brandalf 对齐的 CSS、在注入固定 D3 脚本前定义渲染器的内联运行时加载器，以及带缩放、平移、图切换、搜索、节点详情、适应视图和导览控制的图渲染器。不要为每个生成的导览写一次性 D3 设置代码。
17. 应用 Brandalf 品牌样式：页面背景 `#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`。
18. 实现必需 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`；搜索框搜索当前图内节点标题、文件路径和附加评论文本；可点击节点打开或更新持久详情面板，并在节点出现在导览中时同步导览；边标签说明关系含义。
19. 实现键盘支持：右箭头或 `n` 下一步导览；左箭头或 `p` 上一步导览；`1` 系统概览视图；`2` 数据流图；`3` 代码依赖图；`4` 用户操作图；`+` 或 `=` 放大；`-` 缩小；`0` 重置缩放；`f` 适应视图；`/` 聚焦搜索；`Escape` 清除搜索或选择。
20. 提供稳定的标题、按钮标签、`data-graph-id`、`data-node-id`、`data-edge-id` 和 `data-tour-index` 属性，以便计算机使用 agent 可靠点击和截图。
21. 实现必需内容行为：画布上方或旁边显示 PR 标题、base/head refs 和简短意图摘要；数据中恰好包含四个视图定义 `system-overview`、`data-flow`、`code-dependency`、`user-action`；每个视图有自己的节点和导览；数据流、代码依赖、用户操作图必须有有向边；系统概览视图通常零边并使用更大卡片和可见段落文本；有向图中每条渲染边必须在目标节点有可见箭头和从源到目标的关系标签；系统概览内容必须与 PR 无关且范围紧凑，不引用 PR、改动文件、评审评论、截图、spec 或实现差异；每个导览步骤指向一个节点并解释该节点在此刻为何重要；每个节点在详情面板有解释文本，系统概览卡片还必须在画布上显示完整段落并解释稳定代码概念而非 PR 改动；每个改动文件引用链接到 GitHub PR diff URL；PR 改动的 spec 必须表示为节点或节点附件，若无则包含显式 `No PR-changed specs found` 节点或注释；已有的人类和 agent 评审评论必须附加到相关节点或在评审讨论节点中总结；视觉素材作为详情面板中的节点附件；对 tiny 和 small PR，把缺失的 spec、评审讨论和视觉表示为现有节点上的简洁详情面板注释而非独立节点，除非它们实质性改变评审者阅读 PR 的方式。
22. 使用辅助脚本输出：`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`。
23. 验证导览：打开生成的 `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`、四个视图按钮、`Previous tour step`、`Next tour step`、`Restart tour`）；确认每个视图在浏览器中渲染节点/卡片，系统概览渲染展开的段落卡片且无 PR 特定附件，所有非概览图渲染带可见箭头的有向边；确认图切换、导览导航、键盘快捷键、缩放、平移、适应视图、搜索和节点详情选择工作；确认每个图有非空导览且每个导览步骤指向存在的节点；确认每个节点有解释文本和适用的相关改动文件链接（系统概览卡片除外）；确认 PR 改动 spec 和已有 PR 评审评论已获取并表示为图或在报告中明确说明缺失/不可用；确认引用的截图、mock、Figma 导出、改动图片和视频缩略图是本地相对资产或 data URI 而非远程热链；确认站点使用 Brandalf/Warp 样式；运行 `python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .warp/pr-walkthrough/index.html --require-browser`。若验证失败或在支持浏览器的环境中无法执行，不要报告导览已就绪；修复图或报告渲染未验证。
24. 可选公开发布到 Cloudflare Pages：默认把导览产物保留在 `.warp/pr-walkthrough/` 且不纳入版本控制。若用户要求公开 URL 或可重复 CLI 发布工作流，在导览通过验证后优先使用 Cloudflare Pages Direct Upload。前置条件：用户需有 Cloudflare 账号；本地交互使用先运行一次 `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`。稳定 latest URL 部署到生产分支：`npx wrangler pages deploy .warp/pr-walkthrough --project-name warp-pr-walkthroughs --branch main --commit-dirty=true`。从 stdout 捕获部署 URL 并报告给用户。生产分支 URL 通常为 `https://warp-pr-walkthroughs.pages.dev`，分支预览 URL 通常为 `https://pr-<pr-number>-<sha>.warp-pr-walkthroughs.pages.dev`。发布注意事项：新建 Cloudflare Pages 项目可能在预览子域 TLS 完成配置前就提供生产 URL，若预览 URL 在 Chrome 中报 `ERR_SSL_VERSION_OR_CIPHER_MISMATCH`，等待重试或部署到 `--branch main` 用生产 URL 立即分享；若 wrangler 警告工作目录有未提交改动，对不应提交的生成 `.warp/` 产物传 `--commit-dirty=true`；对私有代码或敏感 PR 上下文，除非用户明确接受暴露，否则不要发布到公开 URL，改用受保护托管、Cloudflare Access 或本地 `file://` URL；PR 评论中只贴简短公开 URL，除非用户明确要求，不要提交或嵌入生成的 HTML 产物到仓库。
25. 应用定位启发式：强调评审者理解 PR 目的、设计、架构和用户影响所需的最小关注点集合；偏好更少更好的节点，100-200 行 PR 通常在所有视图共约 10-16 个节点/卡片而非 30+；用 PR/head commit 的完整代码库作为架构真相来源，diff 显示改了什么但现有代码解释改动部分的含义，系统概览视图应基于代码库探索而非 diff；系统概览在读者有足够定位后停止，不包含每个间接触及的子系统或实现依赖；节点优先用于概念、子系统、状态所有者、用户界面、重要 spec 和评审讨论热点；边优先用于因果、数据移动、调用/依赖方向和用户动作进展；导览优先用于教学顺序；弱化生成文件、机械重命名、纯格式改动和重复样板；解释每个高层关注点为何需要每个低层依赖；把行为或架构风险作为定位注释呈现，尤其在 spec、PR 描述、测试或已有评审评论中记录时；把测试连接回其验证的节点或边；若 spec 与代码分歧，把不匹配表示为节点或注释而非隐藏；不要执行全新代码评审，若在定位时注意到问题，除非已在 PR 评审讨论中，否则框定为待检查区域而非发现。
26. 最终响应报告：生成的导览路径；`file://` URL；推断的基线分支和 PR 标题或分支名；用于 diff 链接的 GitHub PR URL；是否找到并包含 PR 评审评论；D3 画布验证是否通过；若已发布，公开 Cloudflare Pages URL 及是生产 URL 还是分支预览 URL；任何重要注意事项、缺失 spec 或无法执行的验证。

适用边界 · 注意事项

• 用户只想要代码评审发现、批准/请求修改建议或详尽批评时（本技能是定位导览而非代码评审技能）。
• 用户想要幻灯片格式或把所有视角放在一张图上时（本技能要求四个独立可切换画布视图）。
• 没有支持浏览器的环境且无法验证画布渲染时，不要报告导览已就绪，应报告渲染未验证。