Issue to PR

把一个 GitHub issue 处理成一个小而清晰的 PR。目标是保护本地工作区、理解问题来源、做最小相关修改，并在 PR 里留下可复查的验证证据。

目标状态

• 每次只处理一个 issue。
• 代码改动放在独立分支或 worktree 中，不直接在 main 上开发。
• PR 说明包含问题背景、用户可见变化、验证命令和 issue 关联。
• 新增或调整用户可见功能时，按 skill/add-telemetry.md 明确 telemetry 决策。
• 如果 issue 不需要代码改动，只在 issue 线程里回复，不开 PR。

1. 先读 issue

如果用户给的是原始反馈、日志或模糊需求，而不是一个已整理好的 issue，先按 skill/add-issue.md 去重并创建或补充 issue，再进入本流程。

gh issue view <issue-number> --json number,title,state,body,url,labels,comments

如果用户只给了关键词，先搜索打开中的 issue：

gh issue list --state open --search "<query>" --json number,title,url --limit 20

分类后只选一条路径：

路径	使用场景	动作
Code / PR	需要改仓库内容：站点文案、指南、安装脚本、Cloudflare Function、VitePress 配置、CI 配置等。	建分支、实现、验证、开 PR。
Thread only	问答、重复 issue、需求不明确、纯讨论或等待用户补充信息。	在 issue 下简短回复，不创建分支或 PR。

不确定时，优先在 issue 里问一个短的澄清问题，不要猜测实现。

2. 检查仓库状态

git fetch origin --prune
git status --short --branch
git branch -vv
gh issue view <issue-number>

检查这些点：

• 当前是否有未提交的用户改动，不要覆盖它们。
• issue 是否已有相关 PR、评论或结论。
• 改动涉及的是 guide/、public/scripts/、functions/、.vitepress/ 还是 GitHub Actions。
• 需要更新的文档是否和行为变化在同一个 PR 中。

3. 创建隔离分支

除非用户明确要求，不要直接在 main 上提交。

git switch -c <scope>/<issue-number>-brief-name origin/main

分支名示例：

git switch -c fix/20-path-export origin/main
git switch -c docs/trace-guide origin/main

4. 复现或确认动机

不要一上来就写代码。先判断 issue 属于哪一层：

• VitePress 页面内容：index.md、guide/、.vitepress/config.mts。
• 安装与配置脚本：public/scripts/、public/downloads/。
• 事件上报或 API：functions/api/。
• 构建与部署：.github/workflows/、wrangler.toml。

对安装脚本、上报函数、Windows/WSL 行为这类用户可见路径，尽量用本地命令或最小脚本复现问题，再动手修。

5. 设计 telemetry

每次新增功能、改变用户流程或增加失败处理，都要先问：我们上线后如何知道它是否被触达、是否成功、在哪里失败、是否值得继续改进。

按 skill/add-telemetry.md 走一遍，并选择一个明确结论：

• 新增 telemetry：增加新 event、stage、reason 或 dataset。
• 复用 telemetry：现有 event/stage 已覆盖，只需要在 PR 里说明如何观察。
• 修改 telemetry：调整现有 event 语义、字段、白名单或查询口径。
• 不需要 telemetry：仅文档、样式、纯重排等没有新增运行时行为。

默认优先复用现有 dataset：install_events、wrapper_events、update_events、cc_auth_events。不要为了“知道一下”加事件；每个事件都应该能支持排障、产品判断或下一轮改进。

6. 做最小修改

• 保持 PR 聚焦在一个 issue。
• 避免顺手重构无关页面、样式或脚本。
• 用户可见行为变化要同步更新文档。
• telemetry 变化要同步更新事件语义、字段顺序、隐私说明和 smoke 验证。
• 不提交密钥、Cloudflare token、本地配置、日志或临时文件。

7. 验证

默认本地验证：

npm ci
npm run docs:build

按改动类型补充验证：

• guide/、index.md、.vitepress/：确认 npm run docs:build 通过，并人工检查受影响页面的链接、标题和导航。
• public/scripts/install.sh：用临时目录或容器跑脚本的关键分支，确认失败路径不会误报成功。
• public/scripts/install.ps1：至少做 PowerShell 语法检查；能访问 Windows 环境时再跑安装 smoke。
• functions/api/：用最小请求验证返回状态、字段名和错误路径。
• telemetry 改动：按 skill/add-telemetry.md 做正向、负向、失败隔离和隐私检查。
• .github/workflows/：用 gh workflow view 或 PR checks 确认工作流名称和触发条件正确。

如果某项验证无法运行，在 PR 里说明原因和替代证据。

8. 创建 PR

PR 需要包含：

• 变更范围。
• 用户可见变化。
• 为什么需要这个改动。
• telemetry 决策：新增、复用、修改或不需要，并说明原因。
• issue 关联，例如 Closes #<issue-number>。
• 本地验证命令和结果摘要。
• 风险和回滚说明；文档-only 改动可写低风险。

使用 gh 创建 PR：

gh pr create --title "<short title>" --body-file <body-file>

PR body 模板：

## Summary
- 

## Telemetry
- 

## Verification
- `npm run docs:build`

Closes #<issue-number>

Thread-only 流程

不需要代码改动时，不开分支、不提交 PR。直接回复 issue：

gh issue comment <issue-number> --body "..."

回复应说明你理解到的问题、结论或需要用户补充的信息。

Checklist

• [ ] 已读 issue、评论和相关 PR。
• [ ] 已判断是 Code / PR 还是 Thread only。
• [ ] 已保护本地未提交改动。
• [ ] 已使用独立分支或 worktree。
• [ ] 已做最小相关修改。
• [ ] 用户可见行为变化已更新文档。
• [ ] 新增或调整用户可见功能时，已按 skill/add-telemetry.md 明确 telemetry 决策。
• [ ] 已运行 npm run docs:build 或说明无法运行的原因。
• [ ] PR 包含 issue 关联和验证证据。