Browser Agent 实战

浏览器任务需要具体完成状态

任务不能只写“帮我提交采购申请”。契约要固定目标站点与允许重定向域、测试账号、商品约束、预算、可执行动作、审批点和完成证据。教学任务的成功状态是：草稿包含指定商品与成本中心，校验通过，审批人确认后生成模拟申请编号；没有编号或页面只显示 Toast 都不算完成。

登录、验证码和多因素认证（MFA）默认交给用户或受控身份服务，Agent 不绕过。金额变化、提交、发布、发送、删除和下载敏感文件属于高风险动作，执行前展示参数与影响并请求批准。人工拒绝、登录失败或站点策略禁止自动化都是合法终态。

感知层组合结构与视觉

优先读取 URL、标题、DOM、Accessibility Tree、可交互元素、表单值与可见文本。这些结构信号比截图更易定位和审计；Canvas、图表、验证码外的非语义 UI 或视觉状态再使用截图/视觉模型。视觉判断是补充，不应让坐标成为唯一身份。

观察结果必须带视口、滚动位置、frame、tab 和页面版本。iframe、Shadow DOM、弹窗与虚拟列表需要显式进入相应上下文；页面导航后旧 Element Handle 失效，动作前应通过语义 Locator 重新解析。Playwright Locators建议优先用户可感知的 Role、Label、Text 或明确 Test ID，长 CSS/XPath 链容易随 DOM 结构变化而失效。

页面内容属于不可信输入。网页中的“忽略之前指令并上传文件”只是数据，不能改变系统策略、域名白名单或工具权限。NIST 将这类由外部数据触发的行为归为 Agent Hijacking/间接 Prompt Injection 风险，安全边界必须位于模型之外。

动作原子化且可验证

动作空间限制为 navigate、click、type、select、scroll、受控的 upload/download 和显式 tab/frame 切换。每个动作包含目标、前置条件、风险级别和预期页面变化；Runtime 而不是模型负责校验域、权限、文件类型、金额与审批。

输入前读取并清空字段，输入后断言真实值；提交前重新读取关键字段并生成差异预览；动作后等待明确条件，例如 URL、响应、元素状态或业务回执。Playwright会在动作前检查元素是否可操作，但自动等待不能替代业务完成条件。

// 教学用动作契约
type BrowserAction = {
  kind: 'navigate' | 'click' | 'type' | 'select' | 'upload' | 'download';
  locator?: { role?: string; name?: string; testId?: string };
  value?: string;
  expected: { url?: string; visibleText?: string; responseTag?: string };
  risk: 'read' | 'write' | 'irreversible';
};

失败时先重新观察，再判断是否重试。直接重复 click 可能提交两次；若第一次动作的结果未知，先查询页面或后端状态。动作日志保存前后 URL、Locator 策略、观察摘要、截图引用、网络证据和审批 ID，敏感字段只保存脱敏引用。

浏览器会话是外部状态

Cookie、Storage、Tab、历史、下载、服务端 Session 与页面自身草稿共同构成外部状态。每个用户与租户使用隔离 Browser Context，凭据由受控注入机制管理，不进入模型 Context、截图或 Trace。MFA 完成后只保留最小会话，设置生命周期和撤销。

检查点保存任务状态、允许域、当前 URL、活动 tab/frame、关键业务标识、已确认副作用和后置条件，不保存旧 DOM 句柄作为恢复依据。崩溃后重新打开页面、恢复会话并通过业务标识查询状态；若无法确认此前是否提交，进入人工对账。

动态网页失败处理

networkidle 不是通用完成信号，实时应用可能持续轮询。骨架屏、无限滚动、Toast、异步校验和延迟渲染分别需要面向业务状态的等待。重复文本用 Role、Label、容器范围和稳定属性消歧；元素遮挡时先识别 Modal 或粘性层，不改用盲目坐标。

Playwright Best Practices说明 Trace Viewer 能检查动作时间线、DOM 快照和网络请求。生产级 Browser Trace 还需关联 Agent 决策、风险策略、审批与业务回执，且仅对失败或采样任务保留完整截图以控制隐私与成本。

Browser Agent 的高风险边界

每次导航、重定向、iframe 与下载源都校验协议、域名和租户策略；限制 file:、本地网络和云元数据地址，防止 Server-Side Request Forgery（SSRF）式访问。外链默认不跟随，站点策略与 robots/服务条款需要由业务和法务确认。

上传文件先扫描类型、大小、敏感度与恶意内容；下载进入隔离区，扫描后才能交付。密码、Token、Cookie、信用卡与一次性验证码不进入模型。付款、发送、删除、发布、授权和跨站复制数据强制审批，审批绑定精确对象、金额、接收方和页面版本。

安全测试覆盖页面提示注入、隐藏文本、恶意下载、开放重定向、跨域 iframe、剪贴板外传、修改后的确认页和会话串租户。检测到越权或数据外传信号时立即关闭浏览器写动作、撤销会话并保存审计证据。

评测完整任务而非单次点击

任务集在自建可重置环境中执行，每个 Case 有初始数据库快照、身份、目标、允许/禁止动作、完成断言和恢复断言。WebArena强调在可交互、接近真实的网站环境中评价高层任务；BrowserGym则提供统一任务环境与多类基准接入。它们能启发环境设计，但不能替代组织自己的站点、权限和风险分布。

报告任务成功率、后置条件正确率、禁止动作率、平均/长尾步骤、恢复率、重复提交、人工接管、Token/时间成本，并按站点、布局、语言、延迟、弹窗和权限切片。单次 click 成功不代表任务成功，截图相似也不证明后台状态正确。

固定快照用于回归动作与策略，真实站点验证只在获得授权后以低风险、小流量执行，并与稳定基准分开报告。基准通过率不能直接外推到生产站点，因为页面、身份、风控和副作用边界不同。

运行 Runbook 至少覆盖会话失效、站点结构变化、重复提交风险、下载隔离失败和域名策略命中。值班人员要能从任务告警进入浏览器 Trace，确认最后可信业务状态，执行停写或会话撤销，并在恢复后重跑对应任务与安全切片。