chrome-browser-validation git:20261030.ef8191bA

Immutable. This exact content never changes and is served at /api/v1/blob/2e388d3dd57275e1.

---
name: chrome-browser-validation
description: 使用官方 @Chrome 插件连接用户现有 Chrome，进行网页调试、交互测试和视觉验收。跨项目适用于开发完成后的浏览器验证及现有网页问题复现；代码静态检查和单元测试不受此浏览器选择约束。
---

# Chrome 浏览器验收

这是用户的全局浏览器验收偏好。默认自动应用；仅当用户明确要求其他方式时，按其当前要求覆盖。

## 连接现有 Chrome

- 使用官方 [@Chrome 插件](plugin://browser@openai-bundled?browserFamily=chrome)，复用用户现有 Chrome 会话、登录状态及目标服务。
- 按下节发现并初始化当前官方浏览器运行时，阅读其返回的操作文档，再获取浏览器与标签页清单。确认连接类型为 Chrome 扩展，而非内置浏览器或自行启动的会话。
- 按目标 URL、标题和用户指定标签页选择页面；优先复用已有相关标签页。需要新页面时，通过同一 Chrome 扩展连接创建，并遵循运行时的会话命名要求。不改动无关标签页。
- 不启动独立 Playwright、无头 Chrome、独立调试端口、Docker 浏览器夹具，不用 AppleScript、原生桌面控制或其他浏览器替代验收。插件运行时提供的 Playwright 风格定位器可以使用；它不等于自行启动 Playwright 浏览器。
- 只有完成下节适用检查，确认需要用户操作时，才报告具体障碍和最小修复步骤。不要把工具未发现或运行时初始化错误直接归因为用户未连接插件；不静默降级到其他验收环境。可继续不依赖浏览器的代码检查。
- 不读取、导出或搬用 Cookie、登录 Token 或浏览器用户数据目录。需要登录时由用户手动操作。

## 运行时发现与连接诊断

插件已安装、Chrome 扩展已启用、当前会话可以通信是三个不同状态。用户展示 Browser 设置页或表示已开启时，接受其提供的状态信息并检查下一层，不重复要求开启同一开关。

1. 搜索当前工具目录中的 `browser`、`chrome`、`node_repl`、`cua_repl`。没有独立 Chrome 工具名，不代表没有浏览器能力；官方客户端可能通过通用 REPL 暴露。
2. 优先读取当前插件的启动说明。若未注入说明，检查已安装官方 Browser/Chrome 插件的元数据与文档，定位当前客户端入口；不凭记忆写死用户名、缓存版本或浏览器 ID。不要扫描浏览器用户数据来寻找接口。
3. 使用说明指定的 REPL 初始化。对于导出 `setupBrowserRuntime()` 的 `scripts/browser-client.mjs`，在受支持的 `node_repl` 中导入已确认的绝对路径，并显式保存返回值，例如 `var agent = await browserRuntime.setupBrowserRuntime()`。它返回客户端对象，不能假定它自动设置 `globalThis.agent`；普通 shell Node 不具备该 REPL 的浏览器服务。已有有效 `agent` 时直接复用，不重复初始化或重置会话。
4. 按当前 API 文档枚举连接；上述客户端使用 `await agent.browsers.list()`。选择返回结果中 `type: extension` 且 `family: chrome` 的实际 ID，再读取所选浏览器的操作文档和标签页。先做列出标签页等轻量只读调用；成功响应才是通信可用的证据。不得以设置截图代替通信验证，也不得因初始化变量缺失而要求重装插件。
5. 轻量调用失败时，按当前插件故障文档进行有限重试。若当前文档规定等待两秒并重试一次，则照做；仍失败才使用官方只读诊断检查 Chrome 进程、扩展启用状态和 native host。仅使用已确认插件提供的诊断入口，不自行解析或导出浏览器配置、Cookie、Token。不要自行安装或修复 native host，也不要绕过拒绝或企业策略。
6. 根据证据报告所在层和下一步；初始化方式或 API 用法错误由 Agent 先修正。运行时入口确实不可用时说明“当前会话未提供可用运行时”，不要声称“你的插件未开启”。只有诊断指向扩展禁用、宿主缺失或通信持续失败时，才按官方文档请求用户对应操作；无新证据不循环要求连接、重启或重装。

更新本技能时至少核对这些场景：没有 Chrome 专用工具但存在 `node_repl`；初始化函数只返回对象；用户已展示启用状态；只有内置浏览器连接；扩展明确拒绝访问。前两种应继续发现和初始化，后三种应分别补充通信验证、报告目标连接缺失、尊重拒绝，均不得自动换用其他浏览器。

## 在真实页面验收

1. 根据本次改动确定关键显示、交互和异常场景，打开或刷新实际目标页面；本地网页优先复用现有 HTTP 开发服务。
2. 依据最新页面状态操作真实控件；每组操作后重新读取状态。只能使用当前运行时文档中支持的接口，不猜测工具能力。
3. 通过页面状态和截图验证结果，不能仅凭点击成功、数据存在、编译通过或测试通过宣称视觉验收完成。地图、Canvas、WebGL 等内容必须检查实际画面。
4. 使用插件支持的页面、控制台或网络诊断检查相关错误；若这些能力不可用，说明未检查项，不另开独立浏览器绕过。
5. 提供关键结果截图和简短结论，明确区分已验证、失败及未验证项目。浏览器连接受阻时，不复用旧截图充当本次验收证据。

本技能不额外授权提交、付款、发送消息或其他具有外部影响的操作；按用户本次任务授权范围执行。