Playwright 源码仓库中的 Issue 分诊技能：从 GitHub 报告到可复现状态的完整工作流

本篇基于 Playwright 仓库内置的 Claude 技能文件 playwright-triage/SKILL.md 展开，讲解该项目团队如何系统性地分诊（triage）一个 GitHub Issue：先按内容而非标签将报告归类为 Bug、功能请求、上游/环境问题或用法问题；对 Bug 类报告，则按"先在主干（tip-of-tree）复现、再回退到报告版本、必要时做版本二分"的路径穷尽排查，最终把复现压缩成一个符合仓库测试风格的自包含 spec，并以维护者口吻输出一份带完整测试矩阵的状态报告。读完本文，你能掌握一套可直接迁移到自己项目中的 Issue 分诊方法论，并了解 Playwright 仓库中支撑该流程的具体工具链（fixture 体系、npm run ctest、版本二分指南等）。

核心目标：给出"已验证的状态"，而不是修复

技能的开宗明义是：目标是一个清晰、经过验证的状态（a clear, verified status, not a fix）。分诊的终点是复现与状态判定，而不是直接跳到修复代码——这一点在文档"Watch out"一节被再次强调：Triage ends at a reproduction and a status; don't jump to a fix.

这一立场决定了整个工作流的设计：每个环节（归类、复现、压缩、汇报）都服务于"让读者能信任结论并跳过重复排查"，而不是急于产出补丁。

第一步：按内容而非标签给 Issue 归类

文档明确要求"judge by the content, not the label"——标签为 [Feature] 的报告常常其实是一个 Bug（某件事本应工作），而标着 [Bug] 的报告有时只是预期行为。归类结果决定后续动作：

分类	判定	对应动作
Bug	可复现的异常行为	复现它（技能的主路径，下文详述）
Feature request	功能诉求	无可复现物。先确认功能是否已存在（搜索文档/API，可能换个名字），核读报告人引用的源码，提炼出真正的设计问题
Upstream / environment	责任方确实在外部	找到真正的归属方（Node 项目、浏览器引擎、网站自身的服务器/证书配置），核实报告人引用的上游 issue，指出真正的修复路径
Question / usage	用法疑问	直接回答或指向文档

对功能请求，文档给出一个很实用的产出形态：验收测试（acceptance test）。如果诉求小而边界清晰（例如"应该大声失败而不是静默通过"），理想的交付物是一个自包含的 spec——其中断言当前行为的用例今天通过，期望的目标行为则以 fixme/注释断言的形式并列在旁边。这等于把模糊的诉求固化为可执行的验收标准。

对上游/环境问题，文档特别划清了一条边界：Playwright 家族——@playwright/mcp（其源码就在本仓库 packages/playwright-core/src/tools/mcp/ 目录下，包含 program.ts、protocol.ts、config.ts 等文件）、playwright-vscode、-python、-java、-dotnet——不算"上游"，是"我们自己"。相应地，如果 Issue 指向 @playwright/mcp、playwright-python 等，应像分诊本仓库 Issue 一样处理：检出对应仓库、用其自身的语言/工具链去复现。绝不要告诉报告人"这个问题属于另一个 Playwright 仓库，请转投"——那是内部路由细节，不是报告人的问题。

复现 Bug：穷尽之后才能说"无法复现"

复现部分的核心态度是：you're not in a hurry, so be exhaustive before giving up。如果用户提供了最小复现，先试它；如果你这边复现不出来，就去变奏报告人可能漏掉的因素：全部三个浏览器（Chromium/Firefox/WebKit）、headed/headless、若干近期版本，以及触发片段的多种变体。只有在真正穷尽探索之后才能报告"cannot reproduce"，并且必须说明自己试过什么、想要什么补充信息。

关注浏览器间的"分歧"

跨浏览器运行时要留意 divergence：只在 WebKit 上复现、或除 Firefox 外全部复现的 Bug 是很强的信号，值得在报告中先行点出。当然大量 Bug 是浏览器无关的，三个浏览器全部复现同样是好结果，而不是"无发现"。

四步排查路径

1. 读完整线程，包括所有评论——缺失的复现步骤或收窄后的触发条件往往就在评论里。
2. 拉取输入：版本号、浏览器、操作系统、复现仓库/片段、Expected-vs-Actual（这就是你的"判据/oracle"）。有缺失就先假设并继续尝试，在报告中注明假设。
3. 先在 tip-of-tree（主干最新）上复现，工作目录约定为 ~/tmp/issue-<number>/：要么 clone 报告人链接的仓库，要么脚手架一个 npm install @playwright/test@next 加单项目配置的临时工程（详见 bisect-published-versions.md）。运行时设置环境变量 PLAYWRIGHT_HTML_OPEN=never 避免每次失败都弹出 HTML 报告窗口。如果在 ToT 上复现了，这就是一个 live bug——记录你测试的精确版本/sha；如果看起来像回归，就做二分（见该指南）。
4. ToT 复现不了，再试报告人给出的版本。如果老版本复现而 ToT 不复现，说明 already fixed——去找修掉它的版本/PR（cherry-pick 到旧版本可能仍有价值）。两个都复现不了，则属于信息不全或环境特定问题——如实说明你无法匹配的部分。

一个容易踩的版本坑：以 -next 结尾的版本号（如 1.62.0-next）不是 npm 上的发行版，它的语义就是"tip-of-tree"，即你已经试过的 @next 构建。本仓库根 package.json 中 "version": "1.63.0-next" 正是这个体系的体现。

交互式单步调试

需要交互式地单步推进一个测试时，技能指向仓库内置的 playwright-cli 技能。对应的工程入口在 package.json 的 scripts 中："playwright-cli": "node packages/playwright-core/lib/tools/cli-client/cli.js"，它直接驱动 packages/playwright-core/src/tools/cli-client/ 下的实现。

版本二分（Bisect）指南要点

文档引用的 bisect-published-versions.md 给出了一套跨发行版本对比的方法，值得与 triage 流程合在一起读：

• 不要对 monorepo 源码做二分，而是从 npm 装两个版本并排对比——读 node_modules/playwright/lib/** 里的编译产物比构建/切分支更快，且"shipped JS 就是用户真正在跑的东西"。
• 在 ~/tmp/<good>/ 与 ~/tmp/<bad>/ 各装一个指定版本的 @playwright/test，不要用 npm init playwright@latest（交互式，且脚手架自带 3 个浏览器项目，一条 spec 会跑出 6 个 test run，输出混乱）；手写一个只含单 chromium 项目的最小 playwright.config.ts。
• 验证假设时直接编辑 ~/tmp/<bad>/node_modules/playwright/lib/... 里的编译 JS 重跑测试——Node 直接加载，无需构建步骤。
• 报告格式：引用坏版本 node_modules/.../lib/... 中的问题代码行（带文件路径）、对照好版本的等价代码、解释为什么这个改动会破坏用户的场景，并用就地打补丁的方式验证最小修复。

把复现压缩成自包含的 spec

大或依赖特定应用的复现，最有用的形态是压缩成单个自包含 spec，并且要按 Playwright 仓库自己测试的写法来写：一个 test(...)，使用 page 和 server 两个 fixture，并打上 issue 链接标签。关键约束：

• 禁止 test.beforeAll/afterAll，禁止 http.createServer，禁止手写 setup/teardown——fixture 已经提供了 page 和 web server；用 server.setRoute(...)、server.setRedirect(...)、server.PREFIX、server.EMPTY_PAGE 代替自建服务器。
• 用 page.setContent(...) 或 page.goto(server.PREFIX + '/...') 驱动页面。
• 只保留触发 Bug 所需的最少内容，并以会失败的那条断言收尾。

写完放进仓库的 tests/page/ 目录，用 npm run ctest 运行。在根 package.json 中可以看到该命令的实际定义：

"ctest": "playwright test --config=tests/library/playwright.config.ts --project=chromium-*"

即复用仓库自身的 tests/library/playwright.config.ts 并以 chromium 项目集运行——这保证了你的复现 spec 与官方测试跑在完全相同的 fixture/服务环境里。server fixture 的 API 可在 tests/config/testserver/index.ts 中确认：EMPTY_PAGE 指向测试服务器的 /empty.html，setRoute(path, handler) 注册任意路由，setRedirect(from, to) 基于 setRoute 实现 302 跳转。

仓库内可参照的真实范例

文档点名了三个真实的自包含测试，风格正是上述约束的示范：

• tests/page/page-network-request.spec.ts 中 should return event source：用 server.setRoute 搭 SSE 端点，无任何生命周期钩子；
• tests/page/selectors-css.spec.ts 中 should use light DOM structure for child combinator with slotted content：page.setContent 内联 shadow DOM；
• tests/page/workers.spec.ts 中 should report worker script as network request after redirect：server fixture 的路由/跳转组合，并带一个 fixme 标记的浏览器差距——这恰好呼应了技能中"divergence 是强信号"的表述。

报告：状态 + 完整证据矩阵

分诊产出的报告要求给出与 Issue 类型匹配的状态：

• Bug 类：reproduced / fixed-on-latest / cannot-reproduce / not-a-bug；
• 功能请求或上游/环境类：一个简短判定（already-possible、valid request、upstream — owned by X）。

对 Bug，报告必须包含压缩后的复现，并对**"我跑了什么"穷尽到底**——完整的浏览器 × 版本 × 变体矩阵，而不只是那一次跑通的组合，让读者能信任结论并跳过复查；浏览器特定分歧要单独点出。

报告的语言风格按 .github/workflows/bot-voice.md 执行——以"Playwright bot"身份发言的维护者口吻，而非 AI 腔。该文件给出的关键规范：

• 判定先行（Verdict first）：先平实说出发现，再用精确的版本号/commit sha（不能只写 "@next"）、PR、上游 CL、文档等证据支撑；
• 有立场："this is working as intended"、"looks like a real bug"、"already fixed in 1.62"，而不是"取决于很多因素"；
• 需要更多信息时问具体问题，一个就够；
• 对局限诚实：你是第一遍排查，不是终审；
• 守住边界：只报告发现与证据，是否接受 PR、定优先级留给人类维护者；
• 控制篇幅：头条（宣告、判定、最小复现、下一步）放上面，冗长内容收进折叠的 <details> 块。该文件甚至给出了带 SSE 最小复现代码的完整评论模板。

安全与边界注意事项

"Watch out" 一节给出两条硬约束，值得纳入任何自动化分诊流程：

1. 只运行你信任的代码——先快速扫一遍报告人链接的仓库/代码片段；如果发现 postinstall 脚本、混淆代码或莫名其妙的第三方小库，直接放弃运行并在 issue 评论中说明。
2. 分诊止于复现与状态——不要跳到修复。

这套流程对自建项目的借鉴价值

从仓库结构看，这份技能不是孤立的：它与 playwright-dev（含版本二分指南）、playwright-cli（交互式测试驱动）、playwright-devops（CI 提交失败排查）等技能共同构成 Playwright 团队的 Agent 化研发工具链，triage 是其中的"入口"环节——把外部报告转化为内部可验证的事实。其可迁移的方法论要点可归纳为：

• 状态优先于修复：分诊的产出是一份可信的状态报告，不是补丁；
• 先主干后旧版的两级复现顺序，天然区分 live bug 与 already fixed；
• 复用仓库自身 fixture 与配置（server.setRoute + npm run ctest）让复现 spec 与官方测试同构，杜绝"在我机器上能跑"的环境差异；
• 完整矩阵报告（浏览器 × 版本 × 变体）让结论免于反复质疑；
• 固定报告语体（bot-voice）保证对外沟通的一致性与边界。