当分支或 PR 改动需要跑浏览器端到端测试时，如何选驱动…

对当前分支或 PR 影响的页面运行浏览器端到端测试，并输出每个受影响路由的 Pass/Fail/Skip 汇总。

适用场景

解决思路

1. 先按驱动策略选定浏览器驱动并记录：优先使用宿主环境原生集成的浏览器控制能力（能导航本地 URL、检查渲染与交互状态、点击/填写/按键、截图、查看 console 错误）；注意单独配置的浏览器扩展或集成不算宿主原生。选定后先加载并遵循该能力自身的说明再开始浏览器操作。
2. 若没有宿主原生驱动，则回退到 agent-browser；在运行任何命令前先阅读 references/agent-browser-driver.md。
3. 不要引入第三种浏览器栈：绝不安装或替换为独立 Playwright、Puppeteer、单独配置的浏览器扩展或 MCP 等临时浏览器自动化。宿主原生浏览器内暴露的 Playwright API 仍算宿主原生，不算独立 Playwright。
4. 整个运行过程只用一个驱动。仅当宿主原生驱动在测试第一个路由之前初始化失败时，才可回退到 agent-browser；测试开始后不得混用驱动会话、元素引用、截图或认证状态。
5. 在进入第 3 步（把改动文件映射到路由）之前，先阅读本技能目录下的 references/route-and-report.md，其中包含路由映射模式、端口与服务器命令、逐页检查项、两个面向用户的提示以及汇总格式。
6. 根据参数确定测试范围：PR 号 → 运行 gh pr view [number] --json files -q '.files[].path'；current 或留空 → 运行 git diff --name-only main...HEAD；分支名 → 运行 git diff --name-only main...[branch]。同时要求这是一个有改动可测的 git 仓库。
7. 把改动文件映射到路由，构建待测 URL 列表。
8. 确定开发服务器端口：运行 scripts/resolve-port.sh，它会把端口单独打印到 stdout——优先用显式端口参数；否则用 package.json 的 dev/start 脚本中的 --port 标志；否则用 .env、.env.local 或 .env.development 中的 PORT=；否则用 3000。当用户给了 --port N，或当前上下文的项目说明已明确写出开发服务器端口时，传入显式端口。不要为了找端口去 grep 说明文件：文档、示例和排错说明里的散文式提及不可靠且容易误判，而配置文件和 .env 可信。每种模式都在需要端口的那个 shell 调用里运行该脚本，这样端口值无需跨 shell 调用保留或从散文里抄写；具体命令见参考文档。手动模式下按该端口原样使用：服务器由用户控制，不要扫描其他端口。
9. 在询问 headed/headless 之前先确认开发服务器正在运行——手动运行若没有服务器就到此为止，先问会浪费这次提问。
10. 设置可见性，然后验证根路径。可见性与是否无人值守无关：宿主原生集成浏览器保持其常规集成界面可见且不阻塞，便于用户观察进度，路由切换时不要反复抢焦点，手动和 pipeline 模式都如此；agent-browser 回退 + pipeline 模式：直接以 headless 运行，不要询问；agent-browser 回退 + 手动模式：用当前工具列表中已有的宿主阻塞式提问工具询问用户要 headed 还是 headless（按能力匹配，不要按宿主特定名称匹配）。工具出现在当前工具列表中即证明其存在；绝不要为了探测某个面向用户的提问工具是否存在而调用它。若匹配的工具已列出但未加载，使用宿主的工具发现原语加载该能力，不要去找其他宿主的工具名。仅当列表中没有此类工具或真实提问调用报错时，才退回到在宿主可见聊天界面上给出选项。绝不静默跳过该提问。随后导航到 http://localhost:<port>，捕获其渲染或交互状态，确认根路径已被服务，再开始迭代。
11. 逐个测试受影响页面：导航、检查最新状态、执行关键交互、采集证据。
12. 对需要外部交互的流程（OAuth、邮件、支付、短信、第三方 API）进行人工验证：暂停并询问。pipeline 模式不暂停——把每个此类流程记为 Skip 并写明原因后继续。
13. 处理失败：捕获错误状态和精确复现步骤，然后询问是现在修复还是跳过。pipeline 模式不询问——记录失败后继续。
14. 按参考文档给出的格式报告汇总。
15. 完成条件：运行结束时必须报告发现——要么给出汇总，其中每个受影响路由标记为 Pass、Fail 或 Skip，且每个 Skip 都带原因；要么在预检阻塞导致任何路由都无法测试时，给出阻塞项及解除条件。两者都未达到，或因无人能访问而从汇总中漏掉某个路由，正是该完成条件要防止的失败。
16. pipeline 模式（mode:pipeline）由 LFG 或其他自动化运行器调用，运行无人值守——绝不要因提问而阻塞。阅读本技能目录下的 references/pipeline-orchestration.md 并遵循它；它会覆盖端口选择（第 4 步）、开发服务器启动（第 5 步）和可见性提示（第 6 步），在启动服务器的代码块内用 --free 运行同一个端口脚本。

适用边界 · 注意事项

• 改动不涉及任何页面或路由时（没有可映射的 URL 可测）。
• 当前不是 git 仓库或没有任何改动可测时。
• 需要引入独立 Playwright、Puppeteer、单独配置的浏览器扩展或 MCP 等第三种浏览器栈时——策略明确禁止。