Browser

browser 操作的是沙盒里那个干净的 Chromium：没有你的任何登录态，也不会碰到你自己的浏览器。用来做公开网页调研、给自己写的页面截图验证、跑自动化流程。

激活条件

profy-browser 是 user_selectable: true，没有其它前置条件——不需要桌面端，云端沙盒就够。在插件面板勾选即可。

12 个 action

action	参数	说明
`navigate`	`url`、`new_tab`	打开网址
`screenshot`	`url` / `html` / `file_path`、`full_page`、`ref`、`viewport_width`、`viewport_height`、`wait_ms`	三种取源，见下
`snapshot`	可选 `selector`	无障碍树 + 元素 ref，交互前必做
`click`	`ref`（必填）、`button`、`double_click`	缺 ref 报 `'ref' is required for click action. Use snapshot first to get element refs.`
`type`	`ref`、`text`、`clear`、`submit`	逐字符输入
`fill`	`ref`、`text`	直接设值，更快
`scroll`	`direction`、`amount`、`ref`	—
`press_key`	`key`（必填）	—
`tabs`	`tab_action`（list / new / close / select）、`tab_index`	标签页管理，无需认领
`set_html`	`html`（必填）	零服务器注入 HTML
`evaluate`	`code`（必填）、可选 `url`	在页面里跑 JS 并返回结果——做状态断言用的
`go_back`	—	后退

差分快照：为什么第二次 snapshot 特别短

第一次 snapshot 返回完整无障碍树 YAML；之后每次只返回与上一次的 unified diff。稳定页面上，后续快照通常不到 100 token。这是为了让「反复观察页面」这件事在长会话里不至于烧光上下文预算。

差分状态是进程内的，按会话隔离，重启即丢——重启后的第一次 snapshot 会重新返回全量。这不是错误，是状态重建。

动作自校验：点了到底有没有反应

click / type / fill / press_key 默认带自动校验：

动作前拍一张快照
执行动作
再拍一张，比较页面有没有变化
没变化 → 等 500 毫秒重试，最多 3 次
仍然没变化 → 结果里明确标注 verified: false

这条回路的价值在于：它把「点了但没生效」从一个静默失败变成了一个显式信号。你会在工具结果里看到尝试了几次、页面变没变，而不是看到「点击成功」然后后面全错。

verified: false 不等于动作一定失败了。有些交互本来就不改变无障碍树（比如复制到剪贴板、触发一个纯后台请求）。它只说明「从可访问性视角看不出变化」，需要专家结合上下文判断。

截图的三种取源

1. 已运行的页面

browser(action="screenshot", url="http://localhost:5173")

2. 直接注入 HTML（零服务器）

browser(action="screenshot", html="<html><body><h1>Hello</h1></body></html>")

不需要起任何服务，适合快速验证生成的 HTML 片段。 3. 本地文件

browser(action="screenshot", file_path="/home/user/workspace/demo.html")

自动起一个静态服务再截图，适合有相对路径资源引用的 HTML。支持自定义视口和整页截图：

browser(action="screenshot", url="http://localhost:5173",
        viewport_width=1920, viewport_height=1080, full_page=True)

截图落在沙盒文件系统上并以路径返回，不会以 base64 塞进工具结果——那样会瞬间吃掉上下文。需要看图时由图片工具按路径读。

标准工作流

browser(action="navigate", url="https://example.com/form")
browser(action="snapshot")
# → [0] input "Name"  [1] input "Email"  [2] button "Submit" ...

browser(action="fill", ref="input[0]", text="John Doe")
browser(action="fill", ref="input[1]", text="john@example.com")
browser(action="click", ref="button[2]")
# → 自动校验：页面变了吗？

browser(action="evaluate", code="document.querySelector('.toast')?.textContent")
# → 断言提交结果，比看截图可靠

evaluate 是这里的关键一步：用断言替代肉眼看截图。截图能骗人（渲染时机、加载中状态），DOM 查询不会。

失败与对策

报错	含义	怎么办
`Error: Sandbox not available. Cannot control browser.`	没有可用沙盒	先发一条消息触发沙盒创建
`'ref' is required for click action`	跳过了 snapshot	先 `snapshot` 拿 ref
`'key' is required for press_key action`	缺键名	补上
`'html' is required for set_html action`	缺 HTML	补上
`'code' is required for evaluate action`	缺代码	补上
`Unknown browser action '...'`	action 名拼错	对照上面的 12 个
`verified: false`	三次重试后页面仍无变化	换定位方式，或用 `evaluate` 直接确认状态
需要登录才能看的内容	沙盒浏览器没有任何登录态	改用 `chrome` 插件（走你自己的浏览器）

执行路径

桌面端优先走 sidecar（Electron 内的 Playwright），云端走沙盒内 Playwright over CDP（CDP 端口 9222，noVNC 端口 6080）。两条路对模型是同一套 action，行为一致。

已知限制：设置里的「浏览器使用」面板尚未接线。 那一页的开关（启用、网址访问、浏览数据、标注截图）与「安全等级」下拉（read / click / full）目前只是组件内的本地状态，既不持久化也不影响运行时行为。改它不会改变专家能做什么。真正的隔离来自沙盒本身——那个浏览器里没有你的任何数据。

与 chrome / computer 的分工

维度	`browser`	`chrome`	`computer`
浏览器	沙盒内隔离 Chromium	你自己的 Chrome	整个桌面
登录态	无	有	取决于桌面
前提	无	桌面端 + 扩展	桌面端
确认策略	不需要（本来就隔离）	四级确认	桌面权限
标签页	自由创建	需要 `claim_tab`	—
适合	公开调研、开发自测、可并行	需要登录的站点	原生应用

选择很简单：内容公开就用 browser（更快、隔离、不碰你的数据），要登录态才升级到 chrome。

继续阅读

Chrome

带登录态的浏览器控制

Computer Use

桌面级像素操控

网站构建

截图验证在建站流程里的位置

工具全表

每个 action 的完整参数

开始使用

核心概念

使用指南

平台与账户

深入了解

激活条件

12 个 action

差分快照：为什么第二次 snapshot 特别短

动作自校验：点了到底有没有反应

截图的三种取源

标准工作流

失败与对策

执行路径

与 chrome / computer 的分工

继续阅读

Chrome

Computer Use

网站构建

工具全表

​激活条件

​12 个 action

​差分快照：为什么第二次 snapshot 特别短

​动作自校验：点了到底有没有反应

​截图的三种取源

​标准工作流

​失败与对策

​执行路径

​与 chrome / computer 的分工

​继续阅读

Chrome

Computer Use

网站构建

工具全表

激活条件

12 个 action

差分快照：为什么第二次 snapshot 特别短

动作自校验：点了到底有没有反应

截图的三种取源

标准工作流

失败与对策

执行路径

与 chrome / computer 的分工

继续阅读