外观
第 25 章 Research Brief：浏览器自动化 Agent
读者问题
Agent 要验证一个用户可见路径时，为什么“页面能打开”“接口返回成功”或“模型说已经点击”都不足以成为端到端（End-to-End，E2E）证据？它怎样把浏览器会话、定位、前快照、主动作、后快照与验收范围组织成可审查链条？
研究范围与非范围
本章讨论浏览器自动化作为受控外部能力时的证据与边界，重点是：
- 远程浏览器控制、定位、动作、读取与断言各自能证明什么；
- 浏览器层的可操作性（actionability）与任务层成功之间的差异；
- 让 E2E 证据可以按同一目标与动作关联、复查和交接的本书模型；
- 登录态、敏感数据、环境隔离、网络不确定性和高风险动作的停止条件。
本章不比较浏览器工具的功能清单，不安装或运行 Playwright、Selenium、WebDriver、CDP、真实浏览器、登录系统或网站；也不证明任意页面、元素、用户路径、无障碍属性、测试套件或截图已经通过。
可核验事实与可用来源
| 本地键 | 可归因陈述 | 一手来源 | 写作日核验与允许范围 |
|---|---|---|---|
| CH25-REF-01 | WebDriver 是用于远程检查和控制用户代理的、平台与语言无关的 wire protocol，主要面向从独立控制进程自动化浏览器的测试。 | W3C WebDriver | 2026-07-16 实际读取。仅作协议实例；不外推为所有 Agent 的工具接口或安全模型。 |
| CH25-REF-02 | Playwright 对部分动作在执行前进行 actionability 检查；条件未在超时内满足时动作失败。 | Playwright Auto-waiting | 2026-07-16 实际读取。仅限 Playwright 当前文档；不把动作前条件写成业务成功或跨工具保证。 |
| CH25-REF-03 | Playwright 的 Web-first 异步断言会重新获取元素并检查，直到条件满足或超时。 | Playwright Assertions | 2026-07-16 实际读取。仅限产品断言行为；不把断言通过写成全部业务或安全验收。 |
| CH25-REF-04 | Playwright 建议优先使用面向用户的属性或显式测试契约定位元素，且 Locator 每次用于动作时会重新定位当前 DOM 元素。 | Playwright Locators | 2026-07-16 实际读取。仅限 Locator 语义；不保证任何站点可定位、稳定或可访问。 |
| CH25-REF-05 | Chrome DevTools Protocol（CDP）以 domain、command 和 event 组织对 Chromium、Chrome 等 Blink 浏览器的检查、调试和性能分析能力，最新协议会变化且没有向后兼容保证。 | Chrome DevTools Protocol | 2026-07-16 实际读取。仅作 Chromium 特有协议实例；不推导权限、稳定 API 或跨浏览器兼容。 |
来源观点与本书工程扩展
| 内容 | 分类 | 边界 |
|---|---|---|
| WebDriver、CDP、Playwright 的协议或产品行为 | 来源明确表达 | 使用各自 URL 和范围，不把一个工具的字段、等待或会话语义外推到另一个工具。 |
| 浏览器会话、定位器、快照、动作和观察的职责拆分 | 本书工程扩展 | 是用于审查 Harness 的语言，不是标准协议或 SDK 对象。 |
| “前快照 → 主动作 → 后快照 → 判定” | 本书 E2E 证据模型 / 项目规则 | 其目的是避免只加载页面或只看 API；它不是 Playwright、WebDriver 或 CDP 的强制流程。 |
示例中的 observed、blocked、needs_evidence | 纯内存教学结果 | 不代表真实浏览器、用户体验、授权、外部效果或任务验收。 |
计划图示
图示回答：一次浏览器 E2E 主动作需要哪些可审查证据，才能从“动作已发送”走到“当前用户可见状态已观察”？
- 边界：浏览器工具只产生或读取候选证据；质量门只输出本书的受限判断。
- 关键节点：任务范围、前快照、定位/动作、后快照、证据链判定、独立验收或恢复。
- 关键分支：未定位、未派发、效果未知、后快照缺失或状态不匹配均不得报告 E2E 完成。
计划示例
实现纯内存函数 assessBrowserE2EEvidence，输入为调用方注入的主动作、前后快照和 Evidence Contract。它要求主动作是 click、在两份不同快照之间派发，并仅将明确观察到的预期状态返回为 observed。
示例不会启动浏览器、读取 DOM、发送 HTTP 请求、访问 Cookie、截屏、登录、点击真实页面或等待真实时间。它验证的是教学证据对象的完整性，不是 UI。
风险、依赖与待核验
- 会话与数据风险： 已登录浏览器可能含有个人信息、Cookie、令牌、下载文件或生产权限；浏览器工具不是授权替代品。依赖第 12、14 章的环境和审批边界。
- 错误归因风险： 定位到元素、动作无异常、网络响应成功、DOM 状态变化与业务目标完成是不同断言。依赖第 15、17、18 章分别处理观察、验收和恢复。
- 协议漂移风险： Playwright 与 CDP 是动态资料；以后使用版本、参数、浏览器支持或执行记录前，必须在写作日重读官方资料。
TODO(verify)：真实网站的登录流程、跨标签页、文件下载、视觉回归、网络模拟、移动设备与无障碍检查，需要指定环境后用相应工具实际执行和保留结果。TODO(verify)：若将浏览器连接到生产账户或用户浏览器，需要补充数据处理、授权、审计与事故响应要求；本章不提供合规结论。
Research Brief 完成检查
- [x] 读者问题、范围、非范围、风险和相邻章节责任已明确。
- [x] 仅使用官方文档或 W3C 标准；动态资料注明写作日核验与重查条件。
- [x] 来源事实、本书 E2E 证据模型和纯内存示例已经分层。
- [x] 未复制来源长段、未声称运行真实浏览器或用户路径。