浏览器能力统一方案
状态:待评审、未实现。本方案不改变当前工具选择、自动安装行为或业务验收门禁。
目标与边界
任务需要页面验收时,根据实际可用能力选择执行方式。原生浏览器工具、MCP 或仓库已有 Playwright 可以提供等价能力;某个工具名称不存在,不等于浏览器能力不可用。没有视觉需求的任务不探测、不启动浏览器、不安装依赖。
保持验收强度:截图生成不等于已查看,查看目标页不等于完成基准对照,mock 页面通过不等于真实接口或真机通过。继续使用现有任务、范围、检查、交接与证据机制,不建立第二套任务状态机。
真实案例中的缺口
11-02 Jackpot 迁移任务已经加载 agent_browser,但上游二进制不在 PATH;诊断建议直接运行的 pi-agent-browser-doctor 同样不在 PATH。另一方面,项目 Playwright 可执行,7 个 E2E 通过并产出截图。
业务 ui-verification 技能仍优先要求 Cursor Browser,否则指定 Playwright MCP;还将临时脚本和正式业务测试脚本混为一类禁止。这使智能体未把已有 Playwright 当作可用的对照路径。真正缺失的证据是 Hayi 与 Inchat 在一致条件下的实际对照,并不是必须安装某个命名工具。
职责划分
| 所属层 | 负责内容 |
|---|---|
| Pi 基座 | 提供通用工具清单、命令执行、任务证据目录与恢复服务;不判断浏览器品牌、750px 视口或 Figma 节点 |
| 按需浏览器能力模块(拟新增,随 Wenext-Pi 发布) | 通过独立诊断工具报告候选方式、实际缺口和证据要求;不捆绑浏览器、不重写 Playwright/MCP 协议 |
| 原生 Pi 扩展/MCP | 提供实际页面操作工具;保留各自会话、认证、截图和生命周期 |
| 业务 Rules/技能 | 指定目标与基准、视口、语言、状态、验收标准和真实设备要求,允许满足同等能力的执行方式 |
| 智能体 | 调用已选工具,查看实际输出,完成比较、修复、复查,并报告剩余外部条件 |
能力模块与 quality-web 独立。文档/设计任务可能需要浏览器而没有 Web 业务测试;业务测试可执行也不意味着必须做视觉验收。建议将实现放在 src/plugins/browser-capability/,通过 Wenext-Pi 现有原生扩展注册一个按需诊断工具 wenext_browser_capabilities。默认只注册,不执行探测、不增加生命周期门禁,因此普通目录也能使用,不要求生成 workflow.json 或另装诊断包。只读发现可在规划阶段执行,不受现有 wenext_plugin 必须已启动任务的限制。
能力与就绪状态
诊断输入来自当前任务的实际验收要求,不靠文件扩展名、路由名称或项目类型猜测。MVP 使用一次按需工具调用传递需求,无需业务仓维护新的必填配置。拟定输入为 { required: ["navigate", "viewport", "interact", "screenshot"], preferred?: "native" | "mcp" | "playwright" };输出候选、逐项状态、缺口与下一步验证操作。此 API 尚未实现。诊断工具只做本地工具发现和有界依赖检查;页面探针由智能体调用对应工具执行,再通过真实结果提升能力状态,不从清单直接生成 verified。
| 能力 | 如何验证 |
|---|---|
| 导航 | 目标页面能在实际浏览器运行环境打开;localhost 按浏览器所在环境解释 |
| 视口 | 读取实际 viewport、DPR 和截图尺寸;750×1660 只来自本业务规则 |
| 交互 | 能执行要求的点击、输入、滚动并读取动作后的状态;CLI 返回成功不等于业务生效 |
| 截图 | 生成可读取的图片,保留来源、时间、页面状态和截图参数 |
| 结构/控制台检查 | 能取得 DOM/可访问性结构或错误信息;只在验收需要时要求 |
| 视觉读取 | 当前模型能收到可解码图片;被上下文裁剪或卸载的图片不算看过 |
分别报告 discovered(发现入口)、verified(实际探针成功)、unavailable(明确失败)、unknown(未验证)。每项能力单独记录,不把一个 PATH 检查提升为“浏览器可用”。缺少设计基准、身份权限或真机是验收输入缺口,单独报告。
选择和降级
- 先读取适用业务验收要求,确认本任务是否需要浏览器。用户指定的执行方式优先;显式禁止的方式不能自动启用。
- 复用当前已验证且满足要求的会话/执行方式,避免重复开浏览器。否则优先已加载的交互工具,再检查仓库已有 Playwright;用户/仓库可调整候选优先级。
- 原生工具和 MCP 通过宿主实际工具清单发现,工具名称只匹配已知适配声明,不据此宣称全部能力。MVP 不做任意 MCP 自动理解或跨工具代理调用,智能体仍直接调用原工具。
- 仓库 Playwright 通过已有依赖、配置和受控本地探针确认;有
package.json声明但缺依赖、缺浏览器或页面启动失败,分别报告。已有配置中的设备、代理、登录方式不得因降级而丢失。 - 当前候选失败则记录原因,尝试满足同样要求的下一候选。没有候选满足要求时,仅阻塞对应验收项;独立的编码、单测等工作仍可继续。
- 检测与执行不隐式安装依赖、不通过 npx 自动下载未知版本。确实需要安装时列出具体缺项、命令与安装位置,按现有授权和准备策略处理;不增设每次都需确认的审批流程。
doctor 优先调用已安装包的解析路径。无法解析时再提供文档中的显式 npm exec --package pi-agent-browser-native@<所装版本> -- pi-agent-browser-doctor 建议,并说明可能下载;不再假设 Pi 扩展安装会把 helper 命令加进 PATH。
会话重启、工具重载、依赖/PATH/浏览器配置变化或运行失败使探测结果需要复核。缓存只复用诊断结果,不重复发送“安装/更新/启动”事实;目标 URL、视口、身份、基准或代码变化后,旧视觉验收不能自动继续有效。
证据与业务规则调整
复用任务内 research/ui-acceptance.md,记录基准、目标、执行方式、实际视口/DPR、场景、发现、图片引用和未完成项。图片与必要的临时脚本放任务外置证据目录;需要依赖解析的临时脚本显式使用仓库安装的 Playwright,不在外置目录重新安装。正式回归用例放仓库既有测试目录,纳入写入范围与代码审查。
原图保留;模型输入过大时生成缩略图或裁剪局部,并标明缩放关系。只有实际成功交付给模型且被比较的图片才能支持视觉结论。截图哈希、模型读取事实和人工/智能体结论分别记录,不用截图存在替代比较。
业务仓调整范围:
.agents/skills/domains/ui-verification/SKILL.md:将 Cursor/MCP 名称要求改成能力与证据要求,保留业务视觉标准。rules/tools-browser-navigation.md:保留视口、截图管理和交互验证;允许既有 Playwright 与受控临时脚本,避免向项目根写垃圾文件。rules/tools-design-guidelines.md、rules/workflow-iterative-fix.md:保留真实基准与 Compare → Fix → Recheck,明确截图必须实际查看。.agents/skills/games/greedy-jackpot-migration:补充源游戏/目标游戏同状态、同视口的对照路径;保持真实身份、接口和真机边界。- Pi
quality-web:后续删除其独占的 agent-browser 探针或委托按需能力诊断,避免测试准备和视觉诊断各自维护一套结论。
Figma REST 扩展只提供设计输入,不作为浏览器执行方式,也不能当作实时选中图层接口。无 Figma 链接的迁移可使用源页面作为基准。
实施顺序与验收
第一步只统一业务文档与诊断建议,明确允许现有等价执行方式;第二步实现随包按需诊断工具和候选报告,宿主仅在注册层传入 SDK 的实际工具清单与通用命令执行服务;第三步以真实 Jackpot 场景验收,再考虑是否需要更多适配器。浏览器品牌和选择逻辑全部留在模块内,不新增生命周期插件装载配置。
| 场景 | 必须满足 |
|---|---|
| 普通 README quick,无浏览器需求 | 零探测、零浏览器启动、零依赖安装 |
| 需要视觉验收,agent-browser 可用 | 实际访问、视口核对、交互与截图对照 |
| 扩展存在、二进制缺失,仓库 Playwright 可用 | 明确缺失原因,改用 Playwright 完成本地对照,无工具名阻塞 |
| 仅 MCP 可用 | 验证所需能力后使用,不要求安装 agent-browser |
| 浏览器能跑,但目标不可达或没有基准/身份 | 具体阻塞对应验收项,不报告视觉通过 |
| 大图被卸载 | 处理成可读图片后再判断,不能将文件路径当作已查看 |
| 仓库有配置/普通目录无配置 | 都能按需选择能力;不复制业务规范或固定视口到基座 |
| 恢复任务/工具变化 | 保留已有证据,重新验证已失效能力;不重复统计缓存复用为初始化 |
Jackpot 复验应在缺少 agent-browser 的条件下,使用已有 Playwright 获取 Hayi/Inchat 普通、Jackpot、RTL、全屏对照材料并实际查看。真实接口、他人身份、WebView 和译文仍分别列出待验收。收益以“本地可完成项不再错误阻塞、重复探测与准备次数减少”为准,不承诺未经测量的固定分钟数。
MVP 不新增通用浏览器自动化引擎、插件市场、服务端统计 schema 或强制视觉验收配置;专项指标后续遵循插件观测提案,记录真实探测/运行事实,不重放缓存结果。