跳到主要内容
ZeroWorks
开始使用

浏览器

让 Agent 直接操作浏览器：导航页面、填写表单、点击按钮、提取数据与查看网络请求，都在对话里完成。

何时使用浏览器

浏览器能力适合那些没有现成接口、但确实要在网页上完成的事情：一次性任务、只有界面没有 API 的流程、或者来源接入暂时走不通但你现在就要结果。

适合用浏览器更适合用来源
一次性、不需要反复执行的任务需要定期重复执行的任务
只有网页界面、没有 API 的流程面向全团队的自动化与报表
来源接入暂时受阻，但当下就要结果需要稳定、可编程访问的服务
从网页上抓取或提取数据服务已经提供 API 或 MCP 服务器

基本流程

每一次浏览器操作都遵循同一个节奏：打开浏览器、导航到页面、读取页面结构、基于结构做交互、最后提取或核对结果。

Agent 使用 browser_tool，首次使用前应读取 ~/.zero-works/docs/browser-tools.md；用 command: "--help" 查询当前支持的命令。下面每行是一次工具调用，引用编号必须取自当前页面的快照。

  • 打开浏览器：Agent 在后台打开一个浏览器窗口，或者复用已经打开的那个。
  • 导航到页面：加载一个网址，Agent 可以前往任意站点，包括你已经登录过的那些。
  • 读取页面：Agent 抓取一份页面快照，一棵结构化的可访问性树，其中每个可交互元素（按钮、链接、输入框）都带一个引用编号。
  • 交互：拿着这些引用编号去点击按钮、填写输入框、选择下拉项、滚动页面、发送按键。
  • 提取或核对：读取结果，可以执行脚本提取数据、截图做视觉确认，或查看网络请求弄清发生了什么。
试一试

browser_tool({ command: 'open' }) browser_tool({ command: 'snapshot' }) browser_tool({ command: 'find search' }) browser_tool({ command: 'screenshot --annotated' })

能做什么

浏览器能力覆盖的是真实网页操作，而不是仅仅抓一份 HTML 文本。

  • 导航与点击：打开链接、点击按钮、展开菜单、走完一条多步流程。
  • 表单填写：在输入框里填值、选择下拉项、勾选复选框、提交表单。
  • 数据提取：从表格、列表、卡片里读出结构化数据，或直接用脚本取值。
  • 视觉核对：对需要肉眼确认的界面截图，判断渲染结果是否符合预期。
  • 网络检查：查看请求 URL、HTTP 方法、状态、资源类型与是否成功，定位数据来源；日志不包含完整请求体或响应正文。
  • 脚本执行：在页面上下文里运行脚本，处理只有页面里才有的数据。

权限

浏览器工具在所有权限模式下都可用，Explore 模式也不例外：它不会阻止 Agent 真的提交表单或点击会改变状态的操作。

需要在提交、下单、发送、删除前暂停时，直接在任务要求里写明停点。切换 Explore 或 Ask to Edit 不会替你拦住这些浏览器动作。

窗口生命周期

浏览器窗口按需创建或复用。完成操作后，根据是否要交给人继续浏览，明确选择释放、隐藏或关闭。

内置浏览器使用持久的登录分区，关闭窗口不等于退出站点账号；它也不会自动继承系统 Chrome 或 Safari 的登录。

命令实际效果
release撤掉 Agent 控制遮罩，窗口留给你继续使用
hide隐藏窗口，保留当前页面与会话状态
close销毁浏览器窗口；下次使用时重新创建
windows / focus查看窗口及归属，或把已有窗口带到前台

窗口归属与工作区

Agent 使用的窗口绑定到会话并带有工作区归属。本机会话可以复用同工作区里已经释放的窗口；远程会话仅控制自己的窗口，不接管其他手工窗口。

窗口归属用来避免误操作其他会话，不构成账号或 Cookie 隔离。内置浏览器窗口共享持久登录分区，在一个窗口登录的账号可能也会用于其他窗口。

接口发现

先在页面上打开一个列表或一条记录，让站点发出真实请求，再用 network 50 all 查看 URL、方法、状态与资源类型。查询参数可能在 URL 中；请求正文、响应结构与鉴权头不能从这份摘要中直接得到。

找到已确认的只读接口后，可以通过 evaluate 在页面上下文中调用 fetch，复用这个内置浏览器的登录状态。credentials: "include" 会按浏览器规则携带 Cookie，但不会补出 CSRF 令牌、绕过 CORS 或扩大账号权限。

  1. 在已登录的页面里读取一条记录，运行 network 50 all；改变一次筛选或翻页，比较两次请求中的路径、查询参数和状态。
  2. 从站点文档、页面的请求构造代码或已知接口定义确认请求体与返回格式。先复现一个只读请求，检查 HTTP 状态、内容类型和一条记录，别把登录页 HTML 当成 JSON。
  3. 单次验证通过后，再按已发现的记录 ID 或分页游标分批读取；每批使用 Promise.all 或 Promise.allSettled，设置小的并发上限并在批次间等待。
  4. 遇到 429 按 Retry-After 等待并降低并发；401/403 先恢复登录或核对权限，其他错误记录到结果里，避免无限重试或把失败条目算作成功。
  5. 输出数据、来源时间和失败条目。要长期复用时再建 API 来源，并单独配置它支持的认证方式；页面 Cookie 不会自动变成来源凭据。
试一试

browser_tool({ command: 'network 50 all' }) browser_tool({ command: [ 'evaluate', "performance.getEntriesByType('resource').filter(entry => ['fetch', 'xmlhttprequest'].includes(entry.initiatorType)).map(entry => entry.name)", ], })

复用登录做单次接口验证

下面的调用在页面里安装一个同源 GET 读取函数，不会立即发送请求。确认 network 中某个 URL 是获准读取的接口后，让 Agent 把该完整 URL 作为 window.zeroWorksRead 的参数，在下一次 evaluate 中执行一次，并检查返回的 contentType 与 text。

evaluate 支持等待 Promise；这里用 command 数组保留整段表达式，避免脚本中的分号或空白被当成浏览器命令分隔符。

  • GraphQL：先确认这是查询而非 mutation，再复用实际 endpoint、query 与 variables，以 POST、Content-Type: application/json 和 JSON.stringify({ query, variables }) 发送；同时检查响应的 errors 字段。
  • XML：先读取 response.text()，再用 new DOMParser().parseFromString(text, "application/xml") 解析，检查 parsererror 后提取所需节点。
  • 批量：先单次验证，随后固定每批数量，收集每项的成功或错误；不要把所有分页和记录一次性无界并发。
试一试

browser_tool({ command: ['evaluate', `(() => { window.zeroWorksRead = async url => { const endpoint = new URL(url, location.href) if (endpoint.origin !== location.origin) throw new Error('Expected a same-origin URL') const response = await fetch(endpoint.href, { credentials: 'include' }) if (!response.ok) throw new Error('HTTP ' + response.status) return { contentType: response.headers.get('content-type'), text: await response.text(), } } return 'Ready for one verified read URL' })()`], })

示例与配方

下面几类任务适合用浏览器起步。

  • 录入后台表单：Agent 打开后台页面，按你给的数据逐项填写并在提交前停下确认。
  • 核对页面状态：打开几个关键页面截图或读数，确认线上状态是否符合预期。
  • 提取列表数据：从没有导出功能的列表页里读出结构化数据。
  • 接口探路：先看请求结构，再决定是固化来源还是继续手动操作。
  • MFA 或验证码：用 focus 显示窗口，release 交给你手动完成验证；完成后重新 snapshot 核对登录状态，再继续原任务。
  • 定向截图：snapshot 取得当前引用，再用 screenshot-region --ref @e12 --padding 8；也可用 --selector 或 x y width height 坐标框选。
  • 键盘快捷键：macOS 用 key k meta，Windows/Linux 用 key k control 打开支持该快捷键的命令面板，再快照、定位和输入。
  • 动态页面：用 wait text、wait selector 或 wait network-idle 等待内容；菜单、筛选、导航或滚动加载后重新 snapshot，失效引用不能继续复用。

远程工作区下的浏览器

浏览器随桌面端一起运行。连接远程工作区时，由远程上的 Agent 驱动你本机的浏览器，而不是在远程机器上另开一个无头浏览器。

必须有支持浏览器能力的 ZeroWorks 桌面客户端连接该工作区。只连 WebUI 或远程服务而没有桌面客户端时，调用返回 BROWSER_NO_CAPABLE_CLIENT。

本机配置 allowRemoteEvaluate 默认是 true，因此远程 browser_tool evaluate 默认允许。设为 false 后会返回 BROWSER_REMOTE_EVALUATE_BLOCKED；导航、点击、填表和截图的独立命令仍可调用。

远程 upload 当前被拒绝，错误为 BROWSER_REMOTE_UPLOAD_NOT_SUPPORTED；不能把远程文件路径当成本机路径上传。需要上传时由你在本机浏览器完成，或先把文件按正常附件流程交给会话，再确认实际可用的上传方式。

用 focus 或 open --foreground 查看本机窗口；远程 Agent 也可以返回快照和截图供你核对。