@ agent-forge/plugin-浏览器-播放器
内建的 Playwright 浏览器能力插件 福吉探员 ——产品单一浏览器频道. 这个
注册涵盖常见的 Playwright 操作的十七个基本工具, 预写后, 模型可以直接调用它们; 全控主机带有一个
互动面临额外注册 browser_login 持续注册. browser_evaluate 被宣布的逃生舱门 对于一切
内建工具不覆盖. agent-forge.browser.fetch@1 是消费者插件用来通过共享加载页面的插件到插件面
在不披露 Playwright 或存储状态的情况下命名配置 .
剧作家是 从未捆绑:该套件没有Playwright依赖性. 司机决定 playwright 连接时间从
<agentDir>/browser-deps 通过 createRequire,以及 browser_setup 在首次使用时安装( i)npm install playwright --prefix <dir>,则
npx playwright install chromium浏览器 <dir>/browsers 结束 PLAYWRIGHT_BROWSERS_PATH) (中文(简体) ). 找到其他浏览器工具时
Playwright 丢失, 返回一个结构化的失败, 其消息带有两个精确的安装命令加一个指针到 browser_setup。 。 。 .
工具表面
会话和设置
| 工具 | 参数 | 页:1 |
|---|---|---|
browser_navigate | {url, waitUntil?} | 首先打开会话. |
browser_login | {url, profile?, timeoutMs?} | 仅限全控+交互. 打开一个带有命名配置文件的可见的铬窗口( Namedefault),允许用户签名,仅在交互确认后保存存储状态. 确认超时默认为300s(60s.600s);取消/超时/关闭不省事. |
browser_setup | {} | 安装 Playwright + 铬到 <agentDir>/browser-deps;短路为 alreadyInstalled。 。 。 . |
观察(也只以只读模式登记)
| 工具 | 参数 | 页:1 |
|---|---|---|
browser_snapshot | {includeDom?, includeA11y?, includeStyles?, includeScreenshot?} | a11y的证据是 Playwright aria快照(绑定于16KiB),DOM是 page.content() (范围为64KiB). 屏幕截图作为图像内容块(PNG, 16MiB抓取绑定);主机的图像常态器拥有每个工具的内置预算. 证据只包含一个字节计数标记. 样式抓取被宣告 not_supported_in_this_build;该参数用于合同相容性。 摘要和证据还报告了最新下载的文件(如果有的话). |
browser_assert_postcondition | {condition} - 一个条件或1.32(全部)的阵列 | Over url / 元素 / 文本 / 控制台 / 网络状态; 控制台和网络来自200入行的页面环缓冲. |
browser_collect_evidence | {kind: console|network|snapshot} | 原始证据堆放. |
browser_console | {level?, contains?, limit?} | 读取控制台环缓冲器. level 是逗号组合 error/warning/info/debug (单位:千美元)info 还匹配 Playwright 的 log 类型); limit 默认为50,上限为200。 回返 {total, returned:[{type,text,location?,timestamp}]}; 自动接受的对话框显示为 type: "dialog" 条目. |
browser_network | {containsUrl?, status?, method?, limit?} | 读取网络环缓冲. 回返 {total, returned:[{method,url,status,timestamp,durationMs?,sizeBytes?}]}; 期限/大小仅在请求的时间和 content-length 标题可用 . |
browser_performance | {} | 导航计时(TTFB / DOMContentLoaded / 载荷),涂料(FP/FCP),资源汇总(计数,总转移字节数,按持续时间计算最慢为5个),DOM节点计数. 唯相读取. |
browser_wait | {until: selector|navigation|networkidle|time, locator?, ms?} | selector 需求 locator (等待可见); time 需求 ms。 。 。 . ms 被夹到0.30 000(非时间类型默认为30 000)。 请求返回/有效/实际等待持续时间;超时失败地图到 browser_wait_timeout。 。 。 . |
相互作用( 从未以只读模式注册)
| 工具 | 参数 | 页:1 |
|---|---|---|
browser_locator_action | {locator: {kind: css|id|role|text|test-id, value, name?}, action, value?, key?, delay?} | 行动: click, (中文(简体) ), dblclick, (中文(简体) ), rightclick, (中文(简体) ), fill, (中文(简体) ), type, (中文(简体) ), press, (中文(简体) ), hover, (中文(简体) ), select, (中文(简体) ), check, (中文(简体) ), uncheck, (中文(简体) ), clear, (中文(简体) ), upload (单位:千美元)value = 一个绝对路径或 JSON 系列路径,通过 setInputFiles, (中文(简体) ), scroll (单位:千美元)value =: <direction>:<pixels>,比如说. down:500;将元素滚动到视图中,再由像素来轮子. 返回动作后 aria- snapshot 碎片 . |
browser_evaluate | {expression, arg?} | 逃出舱门——只有在没有内置工具覆盖操作时才使用. 运行 page.evaluate; JSON 序列化结果以 64KiB 为界(undefined 序列化为 undefined; 30s 壁点超时离开页面侧脚本自行完成. 评估期间发射的对讲机是自动接收的. |
browser_drag | {from, to, steps?} | Hover source – 鼠标下来 – 踩出 mouse.move 以几何方式向目标中心移动(Locator.hover没有 steps 选项,所以精细的移动是无轮鼠标移动; steps 默认为 8, 夹住 1. 100 ) — 鼠标上方 。 目标在按钮下行时故意不被徘徊. 当目标没有边框时跳过精制动作. |
browser_mouse | {action: move|click|dblclick|rightclick|wheel, x, y, deltaX?, deltaY?, button?} | 不需要元素的原始视图-坐标动作; wheel 是基本的页面滚动原始. |
browser_press_key | {key, delay?} | 页面级别 page.keyboard.press 带有 Playwright 密钥名称( X)Control+a, (中文(简体) ), Enter, (中文(简体) ), Meta+c) (中文(简体) ). |
browser_tabs | {action: list|new|switch|close, index?, url?} | 司机跟踪的标签集; switch 为所有后续工具重新指定当前页面. |
browser_storage | {action: get-cookies|set-cookie|clear-cookies|get-local|set-local|clear-local, name?, value?, domain?, path?, expires?, key?} | 饼干通过上下文(set-cookie 需要名称/值/域;通过页面的本地Storage. |
browser_viewport | {action: set|get, width?, height?} | set 将尺寸夹入320.7680,并在进行夹时报告所要求的值. |
所有结果都是 PluginResultV1结构化的有效载荷(主机/网络条目、性能指标、评价结果、储存和制表状态)
以证据摘要中的JSON文本(64KiB)为界。 仅读主机模式精确登记7个观察工具(snapshot, (中文(简体) ),
assert_postcondition, (中文(简体) ), collect_evidence, (中文(简体) ), console, (中文(简体) ), network, (中文(简体) ), performance, (中文(简体) ), wait); 更改浏览器或磁盘状态的每件事从不
在那里注册.
共享浏览器配置和 browser.fetch@1
browser_login 写入 <agentDir>/browser/profiles/<name>/storage-state.json (0600) 并保留上一个
抓取为 storage-state.backup.json。配置锁(.lock)通过关闭浏览器从快照加载中保持;a
第二写者返回 browser_profile_busy 10s等待之后。 10s等待。 快照被封顶在10 MiB,并通过一个
同名目录临时文件 + fsync + rename.
agent-forge.browser.fetch@1 (按 provides)是只读取的检索面:它加载命名快照
打开无头铬并返回 {version, finalUrl, title?, text, truncated} 最多为
16K个人物. 它永远不会返回 cookie, localStorage, 或认证文件 。 能力也以只读模式提供;
browser_login 没有。 共享配置是便利边界,而不是证书-同位素边界——通用
browser_storage 和页面脚本仍然可以读取已装入上下文暴露的内容.
内置对话框和下载策略
没有专用工具;驱动程序将两种政策应用到每一个打开的页面:
- 对话框 自动接受(
dialog.accept())并记录在控制台环缓冲器中作为[dialog] <type>: <message>输入,所以browser_console控制台的后置条件可以观察它们. - 下载 保存为
<agentDir>/browser-deps/downloads/(目录创建为懒惰),最近的文件名附于browser_snapshot结果。 当不知道代理代理Dir时,文件名仍然被报告,但文件没有被保存.
注射表面
createBrowserCapabilityFactoryV1(runtime) 接受任意 BrowserRuntimeV1 = {connect(): Promise<BrowserDriverV1>; setup?(); login?(); fetch?()} - 测试和中介
主机注射假药. 运出运行时间, PlaywrightBrowserRuntimeV1辅助 agentDir编号 :browserDepsDir编号 :headless,加上确定性
spawnSync编号 :resolvePlaywright编号 :loadPlaywright编号 :ensureDir 用于安装器的接合,懒惰模块负载,以及下载目录. 默认
导出 dist/entry.js 由主持人作曲 api.host.agentDir。 。 。 .
真实浏览器测试
决定性的套房从不下载或产出任何东西. 真实的端到端会话( 安装 - > 导航实例. com - > swatch - > 点击 - > 控制台)
- > 性能 - > 评估 - > 按键 - > viewport - > close) 运行时仅使用 AGENT_FORGE_BROWSER_REAL_TEST=1 和网络访问;它使用丢弃
代理目录,然后删除它.
发展
npm install --ignore-scripts # repo root, creates the workspace symlink
npm run build # plugins/browser-playwright (tsgo)
npm test # vitest; the entry fidelity test requires `npm run build` first