pr-walkthrough
为当前分支或 GitHub PR 生成一个本地静态 HTML 讲解页，帮助 reviewer 快速理解 PR 涉及的系统、数据流、代码依赖和用户路径。此技能不是代码评审技能，不生成新的 review finding、approval 或 request-changes 结论。
输出
生成文件到临时目录下的统一 slug 目录。默认本地产物根目录为 ${TMPDIR:-/tmp}/pr-walkthrough（并去掉末尾 /）；如果用户明确指定其他目录，可改用指定目录。
优先使用 PR number；无 PR number 时使用当前分支名：
$output_dir/graph.json
$output_dir/index.html
<short-sha> 是生成 walkthrough 时的 head commit 短 SHA。<sanitized-branch> 使用小写字母、数字和 -，把 /、空格和其他分隔符归一为 -。本地目录名和 GitHub Pages 路径必须使用同一个 slug。PR 更新后再次调用会因 short SHA 变化生成新目录；只有用户明确要求更新同一路径时才覆盖旧目录。不要把生成产物写入仓库目录，除非用户明确要求。
站点必须可以直接用 file:// 打开，不要求 dev server、打包器、安装依赖或构建步骤。优先生成单个自包含 HTML 文件，内联 CSS、JavaScript 和图数据；如果必须拆分资源，只使用相对路径，并避免用 fetch() 读取本地数据。
D3 使用固定版本的官方 CDN：
https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js
优先使用本技能自带脚本生成和验证页面：
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data "$graph_json" > "$index_html"
python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html "$index_html" --require-browser
视觉风格
不要套用任何公司视觉规范、专属字体、专属色或外部视觉规范技能。使用脚本内置的中性文档/工具界面样式即可。可以为四个视图使用不同的功能色，但颜色只表达信息类型，不表达品牌。
推荐视图颜色：
- System overview view:
#b7791f - Data flow graph:
#0f7b5f - Code dependency graph:
#2563eb - User action graph:
#7c3aed - Active/focus/selected node:
#2563eb
工作流
1. 建立 PR 上下文
识别仓库根目录、当前分支和比较 base。若用户 Prompt 明确给出 PR number、#<number> 或 PR URL，先把该编号记录为 pr_number。否则从当前分支的 GitHub PR 获取 pr_number，并优先使用 PR base、记录 PR URL 生成 diff links：
pr_number="${pr_number:-}" # 用户 Prompt 已明确给出 PR 编号时，先由执行者设置这个变量。
if [ -z "$pr_number" ]; then
pr_number="$(gh pr view --json number --jq '.number // empty' 2>/dev/null || true)"
fi
if [ -n "$pr_number" ]; then
gh pr view "$pr_number" --json number,baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files
else
gh pr view --json number,baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files
fi
若没有 PR，从远端默认分支或仓库约定推断 base：
git symbolic-ref --short refs/remotes/origin/HEAD
收集 review 输入：
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
根据 changed lines、changed files 和概念跨度估算 PR 大小，默认生成最小有用讲解：
- Tiny PR: 约 1 个文件或 75 行以内。每个视图 2-3 个节点/卡片，1-2 个 tour steps。
- Small PR: 250 行以内或 1-3 个文件。每个视图 3-4 个节点，2-4 个 tour steps。
- Medium PR: 250-800 行或多个相关文件。每个视图 4-7 个节点。
- Large PR: 只有跨多个子系统、有新架构或有大量 spec/review 上下文时，才使用 5-12 个节点。
不要只读 diff。要读取关键变更文件的当前完整版本，并沿 imports、call sites、types、state owners、renderers、tests 和相邻模块理解系统边界。System overview 尤其要作为稳定的代码阅读产物，而不是 PR 变更列表。
如果存在 GitHub PR，收集已有评论和 review discussion：
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
这些评论只作为讲解素材，不作为改代码指令。
2. 初始化输出路径
在生成 graph.json 前初始化一次输出变量，后续生成、验证和发布都复用这些变量，不要重新拼路径：
sha="$(git rev-parse --short HEAD)"
tmp_root="${TMPDIR:-/tmp}"
tmp_root="${tmp_root%/}"
artifact_root="${PR_WALKTHROUGH_ARTIFACT_ROOT:-$tmp_root/pr-walkthrough}"
if [ -n "${pr_number:-}" ]; then
slug="pr-walkthrough-pr-$pr_number-$sha"
else
branch="$(git branch --show-current)"
branch_slug="$(printf '%s' "$branch" | tr '[:upper:]' '[:lower:]' | sed 's#[^a-z0-9][^a-z0-9]*#-#g; s#^-##; s#-$##')"
slug="pr-walkthrough-branch-$branch_slug-$sha"
fi
output_dir="$artifact_root/$slug"
graph_json="$output_dir/graph.json"
index_html="$output_dir/index.html"
assets_dir="$output_dir/assets"
pages_path="pr-walkthrough/$slug"
mkdir -p "$output_dir"
如果用户明确要求覆盖固定路径，可以复用已有 slug；否则每次 PR head commit 变化都生成新的 slug 目录。
3. 收集视觉素材
查找能帮助 reviewer 理解用户可见变化的截图、mock、视频、设计资产或 changed image。来源包括 PR body/comments/reviews、关联 issue、变更的图片/SVG/mock fixture、本地测试截图，以及 $artifact_root/ 下已有临时产物。
需要纳入页面的外部视觉素材应下载或导出到：
$assets_dir/
用相对路径引用，或在更简单时嵌入为 data URI。不要 hotlink 远端图片。
4. 构造 GitHub diff links
当已知 PR URL 时，每个 changed file reference、节点附件、代码摘录和依赖边都应链接到 PR 的 Files changed 页：
<pr_url>/files#diff-<file_anchor>
<pr_url>/files#diff-<file_anchor>R<new_line>
<pr_url>/files#diff-<file_anchor>L<old_line>
<file_anchor> 是变更文件路径的 lowercase SHA-256 hex digest。用确定性 helper 或脚本生成，不要手写猜测。
5. 设计四个独立视图
先构建数据模型，再生成 HTML。必须恰好包含四个视图：
system-overview: 受影响子系统的稳定架构概览。不要提 PR、changed files、diff links、review comments、screenshots、specs 或实现 delta。通常edges: []，用较大的卡片和可读段落说明。data-flow: 状态、数据、事件、请求、文件、资产或渲染输出如何流动。code-dependency: 变更组件之间的依赖方向、入口点、边界和 leaf dependencies。user-action: 用户从哪个 surface 开始，触发什么动作，看到什么反馈。
每个视图都需要自己的 nodes、edges 和 guided tour。除 system-overview 外，其他视图必须有有向边、箭头和描述 source-to-target 关系的 edge label。
每个节点回答：
- reviewer 需要先理解什么？
- 此节点在这个视图中解释哪个概念？
- 哪些文件、spec、测试、视觉素材或已有评论能作为证据？
- 点击后 detail panel 应该展示什么？
Tour 顺序要教 reviewer 从起点读到终点，不要只是文件顺序。
6. 写入数据模型
将图数据内联到 HTML，赋值给 window.PR_WALKTHROUGH_D3_DATA 或写入 id="pr-walkthrough-data" 的 JSON script。不要用 fetch() 加载本地 JSON。
数据形状：
{
"meta": {
"title": "PR title",
"prUrl": "https://github.com/owner/repo/pull/123",
"baseRef": "main",
"headRef": "feature-branch",
"summary": "What the PR is trying to accomplish."
},
"graphs": [
{
"id": "system-overview",
"label": "System overview",
"color": "#b7791f",
"summary": "Concise component overview for the affected subsystem.",
"nodes": [],
"edges": [],
"tour": []
}
]
}
坐标建议：
- 起点放在左侧或上方。
- Tour 路径尽量从左到右或从上到下。
- 相关节点靠近，低层依赖放在调用者右侧或下方。
- 小 PR 的图应紧凑到无需大量平移即可读懂。
7. 生成静态页面
可先生成样例数据，修改为真实 PR 数据，再渲染：
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --sample-data > "$graph_json"
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data "$graph_json" > "$index_html"
必备交互：
- 单个 D3 SVG canvas，支持 zoom、pan、fit-to-view 和 reset zoom。
- 四个 view toggles:
System overview,Data flow graph,Code dependency graph,User action graph。 - Tour controls:
Previous tour step,Next tour step,Restart tour和 step indicator。 - Search input 可搜索 active graph 的 node titles、file paths 和 comments。
- 点击节点更新 detail panel，并在可能时同步到对应 tour step。
- 键盘支持：Right Arrow/
n、Left Arrow/p、1-4、+/=、-、0、f、/、Escape。 - 稳定的
data-graph-id、data-node-id、data-edge-id、data-tour-index属性，方便自动化截图和验证。
8. 验证
完成前必须运行：
python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html "$index_html" --require-browser
验证至少确认：
- D3 使用固定版本 URL，未使用
latest。 - 页面不用
fetch()读取本地数据。 - 图数据恰好包含
system-overview、data-flow、code-dependency、user-action。 - 必备控件存在。
- 每个视图都有节点和 tour。
- 非 overview 图都有有向边和箭头。
- System overview 是 PR-agnostic 的架构概览，不带 PR 附件。
- PR-changed specs 和已有 PR review comments 被纳入或明确报告为不存在/不可用。
- 视觉素材是本地相对路径或 data URI。
如果浏览器环境不可用，报告 canvas rendering 未验证，不要说 walkthrough 已完全 ready。
9. 可选发布到 GitHub Pages
默认只保留临时目录里的本地产物，不发布公网，也不提交生成 HTML。只有用户明确要求公开 URL 时才发布。发布前必须确认 PR 内容、截图、评论和代码上下文可以公开。
推荐使用 gh-pages 分支作为 Pages 来源，并把生成站点复制到临时 worktree，避免把生成物混入当前开发分支：
site_dir="/tmp/aicodingflow-pr-walkthrough-pages-$slug"
git fetch origin gh-pages || true
git worktree add "$site_dir" gh-pages
mkdir -p "$site_dir/$pages_path"
cp -R "$output_dir/." "$site_dir/$pages_path/"
cd "$site_dir"
git add "$pages_path"
git commit -m "docs: publish PR walkthrough $slug"
git push origin gh-pages
如果仓库尚未启用 GitHub Pages，先让用户在仓库设置里选择 gh-pages 分支作为 Pages source，或在有权限时使用 GitHub API/CLI 配置 Pages。不要在未征得用户同意时更改仓库 Pages 设置。
发布后的 URL 通常为：
https://<owner>.github.io/<repo>/pr-walkthrough/<slug>/
最终回复
报告：
- 生成的 walkthrough 路径。
file://URL。- 使用的 base branch、PR title 或 branch name。
- 用于 diff links 的 GitHub PR URL。
- 是否找到并纳入 PR review comments。
- D3 canvas validation 是否通过。
- 若发布，报告 GitHub Pages URL。
- 重要 caveats、缺失 specs 或无法完成的验证。
Source: Terry-Mao/AICodingFlow — distributed by TomeVault.