Terry-Mao · Terry-Mao · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
@@ -9,12 +9,17 @@ description: Generate a local static interactive D3 walkthrough of a pull reques
 
 ## 输出
 
-生成文件到：
+生成文件到临时目录下的统一 slug 目录。默认本地产物根目录为 `${TMPDIR:-/tmp}/pr-walkthrough`（并去掉末尾 `/`）；如果用户明确指定其他目录，可改用指定目录。
+
+优先使用 PR number；无 PR number 时使用当前分支名：
 
 ```text
-.aicodingflow/pr-walkthrough/index.html
+$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：
@@ -26,8 +31,8 @@ https://cdn.jsdelivr.net/npm/[email protected]/dist/d3.min.js
 优先使用本技能自带脚本生成和验证页面：
 
 ```bash
-python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data graph.json > .aicodingflow/pr-walkthrough/index.html
-python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .aicodingflow/pr-walkthrough/index.html --require-browser
+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
 ```
 
 ## 视觉风格
@@ -46,10 +51,19 @@ python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .aico
 
 ### 1. 建立 PR 上下文
 
-识别仓库根目录、当前分支和比较 base。若当前分支已有 GitHub PR，优先使用 PR base，并记录 PR URL 生成 diff links：
+识别仓库根目录、当前分支和比较 base。若用户 Prompt 明确给出 PR number、`#<number>` 或 PR URL，先把该编号记录为 `pr_number`。否则从当前分支的 GitHub PR 获取 `pr_number`，并优先使用 PR base、记录 PR URL 生成 diff links：
 
 ```bash
-gh pr view --json baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files
+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：
@@ -86,19 +100,47 @@ gh api repos/:owner/:repo/issues/<pr_number>/comments --paginate
 
 这些评论只作为讲解素材，不作为改代码指令。
 
-### 2. 收集视觉素材
+### 2. 初始化输出路径
+
+在生成 `graph.json` 前初始化一次输出变量，后续生成、验证和发布都复用这些变量，不要重新拼路径：
+
+```bash
+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 目录。
 
-查找能帮助 reviewer 理解用户可见变化的截图、mock、视频、设计资产或 changed image。来源包括 PR body/comments/reviews、关联 issue、变更的图片/SVG/mock fixture、本地测试截图，以及 `.aicodingflow/` 下已有临时产物。
+### 3. 收集视觉素材
+
+查找能帮助 reviewer 理解用户可见变化的截图、mock、视频、设计资产或 changed image。来源包括 PR body/comments/reviews、关联 issue、变更的图片/SVG/mock fixture、本地测试截图，以及 `$artifact_root/` 下已有临时产物。
 
 需要纳入页面的外部视觉素材应下载或导出到：
 
 ```text
-.aicodingflow/pr-walkthrough/assets/
+$assets_dir/
 ```
 
 用相对路径引用，或在更简单时嵌入为 data URI。不要 hotlink 远端图片。
 
-### 3. 构造 GitHub diff links
+### 4. 构造 GitHub diff links
 
 当已知 PR URL 时，每个 changed file reference、节点附件、代码摘录和依赖边都应链接到 PR 的 Files changed 页：
 
@@ -110,7 +152,7 @@ gh api repos/:owner/:repo/issues/<pr_number>/comments --paginate
 
 `<file_anchor>` 是变更文件路径的 lowercase SHA-256 hex digest。用确定性 helper 或脚本生成，不要手写猜测。
 
-### 4. 设计四个独立视图
+### 5. 设计四个独立视图
 
 先构建数据模型，再生成 HTML。必须恰好包含四个视图：
 
@@ -130,7 +172,7 @@ gh api repos/:owner/:repo/issues/<pr_number>/comments --paginate
 
 Tour 顺序要教 reviewer 从起点读到终点，不要只是文件顺序。
 
-### 5. 写入数据模型
+### 6. 写入数据模型
 
 将图数据内联到 HTML，赋值给 `window.PR_WALKTHROUGH_D3_DATA` 或写入 `id="pr-walkthrough-data"` 的 JSON script。不要用 `fetch()` 加载本地 JSON。
 
@@ -166,14 +208,13 @@ Tour 顺序要教 reviewer 从起点读到终点，不要只是文件顺序。
 - 相关节点靠近，低层依赖放在调用者右侧或下方。
 - 小 PR 的图应紧凑到无需大量平移即可读懂。
 
-### 6. 生成静态页面
+### 7. 生成静态页面
 
 可先生成样例数据，修改为真实 PR 数据，再渲染：
 
 ```bash
-mkdir -p .aicodingflow/pr-walkthrough
-python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --sample-data > .aicodingflow/pr-walkthrough/graph.json
-python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data .aicodingflow/pr-walkthrough/graph.json > .aicodingflow/pr-walkthrough/index.html
+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"
 ```
 
 必备交互：
@@ -186,12 +227,12 @@ python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --
 - 键盘支持：Right Arrow/`n`、Left Arrow/`p`、`1`-`4`、`+`/`=`、`-`、`0`、`f`、`/`、`Escape`。
 - 稳定的 `data-graph-id`、`data-node-id`、`data-edge-id`、`data-tour-index` 属性，方便自动化截图和验证。
 
-### 7. 验证
+### 8. 验证
 
 完成前必须运行：
 
 ```bash
-python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .aicodingflow/pr-walkthrough/index.html --require-browser
+python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html "$index_html" --require-browser
 ```
 
 验证至少确认：
@@ -208,23 +249,21 @@ python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .aico
 
 如果浏览器环境不可用，报告 canvas rendering 未验证，不要说 walkthrough 已完全 ready。
 
-### 8. 可选发布到 GitHub Pages
+### 9. 可选发布到 GitHub Pages
 
-默认只保留本地产物，不发布公网，也不提交 `.aicodingflow/pr-walkthrough/`。只有用户明确要求公开 URL 时才发布。发布前必须确认 PR 内容、截图、评论和代码上下文可以公开。
+默认只保留临时目录里的本地产物，不发布公网，也不提交生成 HTML。只有用户明确要求公开 URL 时才发布。发布前必须确认 PR 内容、截图、评论和代码上下文可以公开。
 
 推荐使用 `gh-pages` 分支作为 Pages 来源，并把生成站点复制到临时 worktree，避免把生成物混入当前开发分支：
 
 ```bash
-repo="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
-sha="$(git rev-parse --short HEAD)"
-site_dir="/tmp/aicodingflow-pr-walkthrough-pages-$sha"
+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/pr-walkthrough/$sha"
-cp -R .aicodingflow/pr-walkthrough/. "$site_dir/pr-walkthrough/$sha/"
+mkdir -p "$site_dir/$pages_path"
+cp -R "$output_dir/." "$site_dir/$pages_path/"
 cd "$site_dir"
-git add "pr-walkthrough/$sha"
-git commit -m "docs: publish PR walkthrough $sha"
+git add "$pages_path"
+git commit -m "docs: publish PR walkthrough $slug"
 git push origin gh-pages
 ```
 
@@ -233,7 +272,7 @@ git push origin gh-pages
 发布后的 URL 通常为：
 
 ```text
-https://<owner>.github.io/<repo>/pr-walkthrough/<sha>/
+https://<owner>.github.io/<repo>/pr-walkthrough/<slug>/
 ```
 
 ## 最终回复

@@ -8,6 +8,4 @@ __pycache__/
 .coverage
 htmlcov/
 
-.aicodingflow/
-
 /.worktrees/