pr-walkthrough

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/[email protected]/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：