browser

name	browser
description	网页自动化：通过 CDP 执行 ARIA 观察与 ref 交互、视觉标注、截图/GIF、高级交互（hover/拖拽/键盘/下拉/滚动/上传）、诊断（控制台/网络/Cookie）、PDF 导出、标签页管理与意图级浏览。当用户提到浏览器、网页、打开网站、网页截图、表单填写、网页搜索等操作时触发此技能。不要用于原生桌面应用操作（那属于 Argus）。
tools	browser
metadata	{"category":"tools","tree_id":"ui/browser","tree_group":"ui","min_tier":"task_light","approval_type":"none","emoji":"🌐","enabled_when":"BrowserController != nil","file_access":"none","scope_check":"none","security_level":"sandboxed","policy_groups":["group:ui"],"profiles":["full"],"wizard_group":"web","sort_order":8,"exclude_from":["task_delete"],"intent_keywords":{"zh":["浏览器自动化","浏览器打开","网页","打开网站","打开官网","打开页面","访问网站","访问官网","页面点击","点击登录","点击按钮","填写表单","填一下","表单填写","网页截图","截图当前","截图这","截图页面","下载PDF","查看Cookie","控制台日志","拖拽","悬停","下拉选择","文件上传","扫码登录"],"en":["browser automation","browser open","open website","open page","visit site","navigate to","go to url","fill form","click login","click button","screenshot this","screenshot the","print pdf","cookies","console log","drag drop","hover","select option","upload file"]},"intent_priority":20,"related_tools":["browser_config","platform_login"],"scene_hint":"observe→click/fill→screenshot；前端：perf_audit→extract_styles→visual_diff；媒体：session_load→ai_browse→session_save","summary":"Control web browser via CDP (navigate, click, type, screenshot, ARIA refs)","title":"Browser","verb":"Browse","tool_description":"browser — 浏览器自动化工具，基于结构化页面理解控制浏览器。推荐工作流：observe → click_ref/fill_ref → screenshot。优先使用 ARIA ref 而非 CSS 选择器（click/type 为 CSS 回退）；需要视觉验证时调用 screenshot 或 observe；多步浏览目标使用 ai_browse。核心 action：observe（页面结构+截图）、get_content（轻量页面文本）、click_ref/fill_ref（ARIA 元素交互）、screenshot（截图）、navigate（导航）、ai_browse（多步自动浏览）。页面 action：annotate_som（编号视觉叠加）、evaluate（JS 执行，需启用）、wait_for（等待元素）、go_back/go_forward（历史导航）、get_url（当前 URL）。交互 action：hover（菜单/提示）、press_key（键盘快捷键）、select_option（下拉选择）、scroll（滚动）、drag（拖放）、upload_files（文件上传）。标签页 action：create_tab/close_tab/switch_tab/list_tabs。close_tab 仅在用户明确要求时使用。诊断与导出：get_console/get_network（调试）、cookies_get（认证检查）、print_pdf（导出）、start_gif_recording/stop_gif_recording（GIF 录制）。CrabCode 前端调试（Phase 6）：perf_audit（Core Web Vitals+Lighthouse 简化评分）、memory_snapshot（DOM 计数+JS heap）、extract_styles（递归计算样式+设计 token 汇总）、element_screenshot（按 ref 裁剪单元素）、visual_diff（基线对比）、har_export（HAR 1.2 网络导出）。媒体账号矩阵（Phase 6）：session_save/load/export/list/delete（多账号登录态），stealth_profile（反检测档位 off/basic/standard/aggressive，共 12 维）。范式升级（Phase 6）：action_cache（选择器缓存运维）、action_replay（Teach & Repeat 录制-回放-导入-导出）。如浏览器工具不可用，引导用户前往 自动化 → 浏览器管理 安装扩展。","tool_input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["navigate","get_content","observe","annotate_som","click","click_ref","type","fill_ref","screenshot","evaluate","wait_for","go_back","go_forward","get_url","ai_browse","start_gif_recording","stop_gif_recording","list_tabs","create_tab","close_tab","switch_tab","hover","press_key","select_option","scroll","drag","upload_files","get_console","get_network","cookies_get","print_pdf","perf_audit","memory_snapshot","extract_styles","element_screenshot","visual_diff","har_export","session_save","session_load","session_export","session_list","session_delete","stealth_profile","action_cache","action_replay"],"description":"浏览器操作。推荐工作流：observe → click_ref/fill_ref → screenshot。状态变更操作默认返回文本；需要视觉验证时使用 screenshot 或 observe。annotate_som 返回编号视觉叠加图，ai_browse 处理多步目标。hover/press_key/select_option/scroll/drag/upload_files 用于高级交互。get_console/get_network 用于调试。cookies_get 用于认证状态检查。print_pdf 用于导出。close_tab 仅在用户明确要求时使用。CrabCode 前端调试使用 perf_audit/memory_snapshot/extract_styles/element_screenshot/visual_diff/har_export。媒体账号矩阵使用 session_save/load/export/list/delete 与 stealth_profile。教学回放使用 action_cache/action_replay。"},"url":{"type":"string","description":"navigate 或 create_tab 的目标 URL。"},"selector":{"type":"string","description":"click、type 或 wait_for 使用的 CSS 选择器。"},"text":{"type":"string","description":"type 或 fill_ref 的输入文本。"},"script":{"type":"string","description":"evaluate 执行的 JavaScript 源码。"},"ref":{"type":"string","description":"observe 结果中的 ARIA 元素引用，例如 e1。"},"goal":{"type":"string","description":"ai_browse 的自然语言目标，例如「搜索 MacBook Pro 并总结第一个结果」。"},"target_id":{"type":"string","description":"close_tab 或 switch_tab 的标签页 target ID。"},"key":{"type":"string","description":"press_key 的键盘按键名（如 Enter、Escape、Tab、ArrowDown、Backspace、Ctrl+A）。"},"values":{"type":"array","items":{"type":"string"},"description":"select_option 的选项值列表。"},"start_ref":{"type":"string","description":"drag 操作的源元素 ARIA ref。"},"end_ref":{"type":"string","description":"drag 操作的目标元素 ARIA ref。"},"paths":{"type":"array","items":{"type":"string"},"description":"upload_files 的文件路径列表。"},"properties":{"type":"array","items":{"type":"string"},"description":"extract_styles 的 CSS 属性白名单（可选，空=设计 token 预设）。"},"max_depth":{"type":"integer","description":"extract_styles 递归深度。默认 1。"},"max_nodes":{"type":"integer","description":"extract_styles 节点总量上限。默认 100。"},"baseline_id":{"type":"string","description":"visual_diff 基线 ID。缺失则首次保存为基线。"},"threshold":{"type":"number","description":"visual_diff 每像素亮度差阈值（0-1）。默认 0.1。"},"sample_step":{"type":"integer","description":"visual_diff 采样步长。默认 2。"},"padding":{"type":"integer","description":"element_screenshot 裁剪外延像素。默认 0。"},"format":{"type":"string","enum":["jpeg","png"],"description":"element_screenshot 格式。默认 jpeg。"},"filter":{"type":"string","description":"har_export URL 子串过滤。"},"max_count":{"type":"integer","description":"har_export 条目上限。默认 200。"},"session_id":{"type":"string","description":"session_save/load/export/delete 的 slot ID。"},"session_name":{"type":"string","description":"session_save 的展示名。"},"session_tags":{"type":"array","items":{"type":"string"},"description":"session_save 的标签。"},"bundle_json":{"type":"string","description":"session_load/action_replay import 的外部 JSON 字符串。"},"stealth_profile":{"type":"string","enum":["off","basic","standard","aggressive"],"description":"stealth_profile 档位。"},"cache_op":{"type":"string","enum":["stats","clear","export"],"description":"action_cache 子操作。默认 stats。"},"replay_op":{"type":"string","enum":["record","stop","list","get","delete","replay","import","export"],"description":"action_replay 子操作。"},"recording_id":{"type":"string","description":"action_replay 的录制 ID。"},"start_url":{"type":"string","description":"action_replay record/replay 的起始 URL。"},"speed_factor":{"type":"number","description":"action_replay replay 回放速度倍率。默认 1.0。"},"stop_on_error":{"type":"boolean","description":"action_replay replay 遇错即停。默认 false。"},"skip_navigate":{"type":"boolean","description":"action_replay replay 跳过 start_url 导航。默认 false。"}},"required":["action"]}}

Browser - 浏览器自动化

本文档以 tool_executor.go:executeBrowserTool() 的实际执行路径为准，覆盖当前浏览器自动化工具支持的全部 45 个 action（31 基础 + Phase 6 新增 14）。

代码来源（单一事实源）:

• 执行入口: runner/tool_executor.go:1263 — executeBrowserTool()
• Action 定义: browserdef/browser_spec.go — 45 个 ActionSpec + ToolInputSchemaMap
• 控制器接口: browser/types_browser_controller.go — BrowserController 32 个方法
• 错误分类: runner/tool_executor.go:1240 — classifyBrowserError()
• 自动截图策略: runner/tool_executor.go:1673 — browserResultForAction() + ActionAutoVerificationImage()

能力树对齐

id:                     ui/browser
kind:                   tool
parent:                 ui
runtime.owner:          attempt_runner
runtime.enabled_when:   BrowserController != nil
routing.min_tier:       task_light
routing.exclude_from:   [task_delete]
routing.intent_priority: 20 (task_multimodal)
routing.intent_keywords: 浏览器自动化 | 网页 | 打开网站 | open website | browser automation
perms.approval_type:    none
perms.file_access:      none
policy.policy_groups:   [group:ui]
policy.profiles:        [full]
policy.wizard_group:    web
skills.bindable:        true

参考: tree_migrate.go:244-261

工具接口边界

browser 工具只接受以下顶层参数，不要传不存在的字段（如 profile、target、headers、timeout）:

参数	类型	用于哪些 action	说明
action	string	全部（必填）	浏览器动作名，45 个枚举值之一
url	string	navigate、create_tab	URL 地址
selector	string	click、type、wait_for	CSS 选择器
text	string	type、fill_ref	输入文本
script	string	evaluate	JavaScript 源码
ref	string	click_ref、fill_ref、hover、select_option、scroll、upload_files	observe 返回的 ARIA ref（如 e1）
goal	string	ai_browse	自然语言浏览目标
target_id	string	close_tab、switch_tab	标签页 target ID
key	string	press_key	键盘按键名（如 Enter、Escape、Tab、Ctrl+A）
values	string[]	select_option	下拉选项值
start_ref	string	drag	拖拽源元素 ARIA ref
end_ref	string	drag	拖拽目标元素 ARIA ref
paths	string[]	upload_files	要上传的文件路径列表

参考: browserdef/browser_spec.go:67-120 — ToolInputSchemaMap()

适用范围

适用:

• 网页导航、表单填写、按钮点击、搜索、结果核验
• 需要先看页面结构再行动的任务（observe 起手）
• 需要在浏览器里完成多步操作的任务
• 需要页面截图、SOM 标注图或操作 GIF 的任务
• 需要在多个标签页之间查看、切换、创建的任务
• 下拉框选择、文件上传、拖拽排序等高级交互
• 读取控制台日志、网络请求、Cookie 等调试信息
• 导出页面为 PDF

不适用:

• 原生桌面应用或系统设置界面 — 交给 Argus（argus 公共工具）
• 仅需抓取静态网页文本时，优先更轻量的抓取工具
• 系统级文件、窗口、键鼠控制

推荐工作流

observe → click_ref / fill_ref → screenshot（核验）

1. observe — 起手动作。获取 ARIA 树 + 元素 ref + 页面截图，理解页面结构。
2. click_ref / fill_ref — 优先用 observe 返回的 ref 做交互，比 CSS selector 更稳定。
3. wait_for — 遇到页面加载、动画、延迟渲染时，用 selector 等待目标出现。
4. screenshot / annotate_som — 关键步骤后核验结果；页面复杂或 ARIA 不直观时用 annotate_som。
5. ai_browse — 目标明确的多步浏览任务，直接给自然语言目标，内部循环执行 observe-plan-act（最多 20 步）。
6. start_gif_recording / stop_gif_recording — 只在确实需要展示操作过程时录制。

高级交互工作流

observe → hover（触发菜单）→ observe（刷新 ref）→ click_ref（选中菜单项）
observe → scroll（滚到目标）→ select_option / upload_files / drag

• hover — 触发 tooltip、下拉菜单、悬停效果后，必须重新 observe 获取新 ref。
• press_key — 键盘快捷键（Enter 提交、Escape 关闭、Tab 切换焦点）。
• select_option — 用于 <select> 下拉框，传入选项值数组。
• scroll — 目标不在可视区时先 scroll 再交互。
• drag — 拖拽排序、看板卡片移动等 DnD 场景。
• upload_files — 文件 <input type="file"> 上传。

调试工作流

get_console → 查看 JS 错误
get_network → 查看 API 请求状态
cookies_get → 检查认证状态

关键规则

• 状态变更 action 不会自动附加截图。navigate、click、type、click_ref、fill_ref、ai_browse、switch_tab 只返回文本确认。需要视觉验证时必须显式调用 observe 或 screenshot。这是因为 ActionAutoVerificationImage 对所有 action 均为 false（browser_spec.go）。
• ref 有生命周期。页面跳转、刷新、内容变化后旧 ref 失效，必须重新 observe。
• click_ref/fill_ref 优先于 click/type。CSS selector 只作为 ref 不可用时的回退方案。
• 不要假设浏览器动作会自动附加截图。intent_router 明确规定: "Do NOT assume browser actions will attach screenshots automatically."

Action 清单（45 个）

页面导航与读取

Action	必填参数	返回形态	说明
navigate	url	文本	打开网页，返回 Navigated to {url}
get_content	—	文本	优先返回 ARIA 树（## Page Content + ## Element Refs），不可用时降级为 innerText。ARIA 截断 40000 字符，innerText 截断 50000 字符
observe	—	多模态	推荐起手。返回 ## Page Structure (ARIA Accessibility Tree) 文本（截断 30000 字符）+ ## Element Refs JSON + 页面截图。截图失败时降级为纯文本
screenshot	—	多模态	返回截图元信息文本 + JPEG 图像。截图超过 512KB 时静默降级为纯文本（maxBrowserScreenshotBytes）
wait_for	selector	文本	等待 CSS selector 出现，返回 Element found: {selector}
go_back	—	文本	浏览器后退
go_forward	—	文本	浏览器前进
get_url	—	文本	返回当前页面 URL（裸字符串）

页面交互（基础）

Action	必填参数	返回形态	说明
click_ref	ref	文本	用 ARIA ref 点击，推荐。返回 Clicked element ref: {ref}
fill_ref	ref、text	文本	用 ARIA ref 填写，推荐。返回 Filled text into element ref: {ref}
click	selector	文本	CSS selector 点击，仅作回退。返回 Clicked element: {selector}
type	selector、text	文本	CSS selector 输入，仅作回退。返回 Typed text into: {selector}

页面交互（高级）

Action	必填参数	返回形态	说明
hover	ref	文本	悬停在 ARIA ref 元素上。触发 tooltip、下拉菜单、hover 样式。hover 后需重新 observe 获取新状态
press_key	key	文本	发送键盘按键。支持: Enter、Escape、Tab、ArrowDown、ArrowUp、Backspace、Delete、Space、组合键如 Ctrl+A、Ctrl+C
select_option	ref、values	文本	在 <select> 下拉框中选择选项。values 是选项值数组，单选传一个，多选传多个
scroll	ref	文本	将 ARIA ref 元素滚动到可视区域。在交互前确保目标可见
drag	start_ref、end_ref	文本	从 start_ref 拖拽到 end_ref。用于拖拽排序、看板卡片移动、文件拖放区等
upload_files	ref、paths	文本	向 <input type="file"> 元素上传文件。paths 是本地文件路径数组

高级能力

Action	必填参数	返回形态	说明
evaluate	script	文本/JSON	执行 JavaScript。需要 BrowserEvaluateEnabled=true（通过 browser-config 工具配置）。未启用时返回禁用提示
annotate_som	—	多模态	注入数字编号覆盖层截图 + SOM: N interactive elements found. 元素列表（[index] tag (role=xxx) "text"）
ai_browse	goal	文本	意图级多步浏览（observe-plan-act 循环，最多 20 步）。返回 AI Browse completed. + 结果文本。需要 AI planner 已注入

诊断与调试

Action	必填参数	返回形态	说明
get_console	—	JSON	返回页面控制台消息列表（type: log/warning/error/info/debug + text + url + lineNumber）
get_network	—	JSON	返回页面网络请求列表（url + method + status + statusText + type）
cookies_get	—	JSON	返回当前页面所有 Cookie（name/value/domain/path/expires/httpOnly/secure/sameSite）

导出

Action	必填参数	返回形态	说明
print_pdf	—	文本	将当前页面导出为 PDF，返回 PDF 字节数

录制与标签页

Action	必填参数	返回形态	说明
start_gif_recording	—	文本	开始录制，后续浏览器动作被捕获为帧
stop_gif_recording	—	多模态	停止录制，返回帧数/字节数文本 + GIF 图像
list_tabs	—	文本/JSON	返回 ## Browser Tabs + tabs JSON 数组（id/url/title/type）
create_tab	url（可选）	文本	创建新标签页，返回 Created new tab: id={id} url={url}
close_tab	target_id	文本	关闭指定标签页
switch_tab	target_id	文本	切换到指定标签页

Phase 6: CrabCode 前端调试 action

Action	必填参数	返回形态	说明
perf_audit	—	JSON 文本	注入 PerformanceObserver 采集 FCP/LCP/CLS/INP/TBT/TTFB + 导航时序 + 资源统计；附简化版 Lighthouse 评分（performance 0-100）与告警 notes。只读。
memory_snapshot	—	JSON 文本	Memory.getDOMCounters + performance.memory 输出 DOM 节点数/事件监听器数/frames/JS heap 使用/上限/百分比。DOM>1500 或 heap>70% 自动告警。
extract_styles	—	JSON 文本	按 ref 或 selector 递归采集计算样式；空 properties 自动使用 48 项设计 token 预设；max_depth/max_nodes 控制规模；自动汇总 colors/backgrounds/fonts/spacings 等独立 token。
element_screenshot	ref 或 selector	多模态	Page.captureScreenshot + bbox clip 返回单元素裁剪图；支持 padding 外延、`format=jpeg
visual_diff	baseline_id	JSON 文本	与命名基线 (in-process 存储) 对比：不存在则自动保存并返回 saved_as_baseline=true；存在则给出 similarity、diff_pixels、diff_regions（10x10 粗粒度）。ref/selector 可选；不填为全页。
har_export	—	JSON 文本	将已捕获的网络请求导出为 HAR 1.2 envelope；filter URL 子串过滤；max_count 截断（默认 200）。不含 timing 细节（需 CDP Network 事件订阅）。

Phase 6: 媒体多账号基础设施 action

Action	必填参数	返回形态	说明
session_save	session_id	文本	快照当前页面登录态（cookies + localStorage + sessionStorage + URL + viewport + UA）到命名 slot。可附 session_name、session_tags。
session_load	session_id 或 bundle_json	文本	从 slot 或外部 bundle JSON 恢复：先导航到保存 URL → 注入 storage → setCookies（可选 viewport 恢复）。
session_export	session_id	JSON 文本	导出 slot 为可迁移 JSON bundle，便于写入文件或跨机器分发。
session_list	—	JSON 文本	列出所有 slot 概要（id/name/url/tags/captured_at）。
session_delete	session_id	文本	从 registry 移除 slot。
stealth_profile	stealth_profile	文本	切换反检测档位：off（全关）/basic（5 维经典）/standard（12 维完整）/aggressive（standard + 每次导航强化）。影响 webdriver、viewport、chrome.runtime、plugins、languages、WebGL vendor/renderer、permissions.query、iframe.contentWindow、hairline、navigator.connection。

Phase 6: 范式升级 action

Action	必填参数	返回形态	说明
action_cache	cache_op（默认 stats）	JSON 文本	选择器/动作缓存运维：stats 返回命中/未命中/自愈计数+TTL+条目数；clear 清空；export 返回键值快照。
action_replay	replay_op	JSON 文本 / 文本	Teach & Repeat 生命周期：record/stop/list/get/delete/replay/import/export。record 后 ai_browse 每步自动追加到当前录制；replay 按原序执行，支持 speed_factor、stop_on_error、skip_navigate。

Phase 6 工作流建议

CrabCode 前端调试回环（详见 workflows/frontend-debug 技能）:

navigate → perf_audit（建立 web vitals 基线）
         → extract_styles（核心组件样式与 token 验证）
         → memory_snapshot（可选内存档）
         → 改码 → reload → perf_audit + visual_diff(baseline_id=X)

媒体发布回环（详见 workflows/media-publish 技能）:

session_list → session_load(id=xhs_user1) → observe → 发布动作
           ↓ 若尚未登录
  stealth_profile(aggressive) → platform_login.start → platform_login.wait
           → session_save(id=xhs_user1, name="小红书账号1", tags=[xhs])

教学与回放（配合 ai_browse）:

action_replay(op=record, recording_id=flow1, goal="发布并评论", start_url=...)
  → ai_browse(goal=...)    # 期间步骤自动记录
  → action_replay(op=stop)
  → action_replay(op=export, recording_id=flow1)  # 保存到 workspace
  # 下次直接:
  → action_replay(op=replay, recording_id=flow1, speed_factor=2.0)

返回特征

• 多模态 action: observe、screenshot、annotate_som、stop_gif_recording — 返回 __MULTIMODAL__ 编码的文本+图像混合内容
• 纯文本 action: 其余 27 个 action 均返回纯文本或 JSON
• 截图默认 JPEG，超过 512KB（maxBrowserScreenshotBytes = 512 * 1024）时静默降级为纯文本
• get_content 和 observe 对 ARIA 树有长度截断（分别 40000/30000 字符）
• get_url 返回裸 URL 字符串（无 JSON 包装）
• evaluate 返回 JSON 序列化的执行结果
• get_console、get_network、cookies_get 返回 JSON 数组

错误分类与恢复

错误由 classifyBrowserError() 分为三类（tool_executor.go:1240），加上一个可用性前置检查:

not available — 控制器未连接

BrowserController 为 nil。引导用户:

1. 访问 Gateway 浏览器扩展引导页: http://{gateway_host}:{gateway_port}/browser-extension/
2. 如持续未连接，提示用户前往用户区"自动化"标签中的"浏览器管理"页面，检查扩展状态、连接状态和配置

完整提示文本定义在 browserdef/browser_spec.go:117-128 — UnavailableMessage()

transient — 可重试

触发条件（错误消息包含）: not visible、not stable、animating、actionability timeout、not found

典型场景: 元素还在加载、动画未结束、页面尚未稳定。

恢复方式:

1. wait_for 等待目标元素
2. observe 刷新页面状态
3. 重新执行交互

错误提示示例: [Browser click error (transient — element may still be loading, try wait_for or observe first): ...]

structural — 需重新规划

触发条件: 不属于 fatal 或 transient 的所有其他错误（默认分类）

典型场景: selector 错误、ref 失效、页面结构已变、严格模式冲突。

恢复方式:

1. 重新 observe 获取最新页面结构
2. 用新的 ref 重试
3. 不要继续沿用旧 ref 或旧 selector

错误提示示例: [Browser click_ref error (structural — ref may be stale, run observe again): ...]

fatal — 中止

触发条件（错误消息包含）: websocket、connection refused、target closed、page crashed、context canceled、context deadline

典型场景: CDP 连接断开、浏览器崩溃、控制器失联、超时。

恢复方式:

• 让用户检查扩展或浏览器连接
• 恢复连接后重新开始

ai_browse is not available

当前没有配置 AI planner。改用手动工作流:

observe → click_ref / fill_ref → screenshot

evaluate is disabled

BrowserEvaluateEnabled 为 false。需要通过 browser-config 工具启用:

browser-config set browser.evaluateEnabled=true

MCP Server 工具清单（30 个）

以下工具通过 MCP 协议暴露给外部 IDE/SDK（Claude Code、Cursor、VS Code 等）:

MCP Tool	对应 Agent Action	说明
browser_navigate	navigate	导航到 URL
browser_snapshot	observe	ARIA 树快照
browser_click	click / click_ref	点击（支持 ref 或 selector）
browser_fill	fill_ref	填写（ref）
browser_type	type	输入（selector）
browser_screenshot	screenshot	截图
browser_evaluate	evaluate	JS 执行
browser_wait	wait_for	等待 selector
browser_back	go_back	后退
browser_forward	go_forward	前进
browser_get_url	get_url	获取 URL
browser_get_content	get_content	获取页面内容
browser_annotate_som	annotate_som	SOM 标注
browser_ai_browse	ai_browse	意图级浏览
browser_list_tabs	list_tabs	列出标签页
browser_create_tab	create_tab	创建标签页
browser_close_tab	close_tab	关闭标签页
browser_switch_tab	switch_tab	切换标签页
browser_start_gif_recording	start_gif_recording	开始 GIF 录制
browser_stop_gif_recording	stop_gif_recording	停止 GIF 录制
browser_hover	hover	悬停
browser_press_key	press_key	键盘按键
browser_select_option	select_option	下拉选择
browser_scroll	scroll	滚动到可视区
browser_drag	drag	拖拽
browser_upload_files	upload_files	文件上传
browser_get_console	get_console	控制台消息
browser_get_network	get_network	网络请求
browser_cookies_get	cookies_get	Cookie 读取
browser_print_pdf	print_pdf	PDF 导出

HTTP Agent Routes（高级内部 API）

以下 30 个 HTTP 端点由 agent_routes.go 注册，供内部 Agent 直接调用 PlaywrightTools:

端点	方法	说明
/agent/snapshot	POST	ARIA/AI 快照
/agent/screenshot	POST	截图
/agent/navigate	POST	导航
/agent/act	POST	12 种动作（click/fill/hover/highlight/type/pressKey/selectOption/scrollIntoView/drag/setInputFiles/evaluate/fillForm）
/agent/wait	POST	多条件等待（text/textGone/url/loadState/fn/time）
/agent/evaluate	POST	JS 执行
/agent/cookies	GET	Cookie 读取
/agent/cookies/set	POST	Cookie 设置
/agent/cookies/clear	POST	Cookie 清除
/agent/storage	GET	Storage 读取（local/session）
/agent/storage/set	POST	Storage 设置
/agent/storage/clear	POST	Storage 清除
/agent/console	GET	控制台消息
/agent/errors	GET	JS 错误
/agent/requests	GET	网络请求
/agent/trace/start	POST	CDP 性能追踪开始
/agent/trace/stop	POST	CDP 性能追踪停止
/agent/state/viewport	POST	视口尺寸
/agent/state/useragent	POST	User-Agent
/agent/state/geolocation	POST	地理位置
/agent/state/timezone	POST	时区
/agent/state/locale	POST	语言
/agent/state/colorscheme	POST	配色方案
/agent/state/headers	POST	自定义 HTTP 头
/agent/state/offline	POST	离线模式
/agent/page/close	POST	关闭页面
/agent/page/pdf	POST	PDF 导出
/agent/page/resize	POST	视口调整

配置与运行前提

必要条件

• 浏览器工具只有在 BrowserController != nil 时才可用
• evaluate 需要 BrowserEvaluateEnabled=true
• ai_browse 需要 Gateway 为控制器注入 AI planner
• 工具接口不负责切换 profile，profile 由 Gateway 配置决定

端口派生规则

端口由 Gateway 端口动态派生（config/portdefaults.go）:

端口	派生规则	默认值（gateway=19001）	回退值（gateway<=0）
Gateway	配置指定	19001	—
Bridge	gateway + 1	19002	18790
BrowserControl	gateway + 2	19003	18791
Extension Relay	BrowserControl + 1	19004	18792

Extension Relay 是 Chrome 扩展与 Gateway 之间的 WebSocket 中继，地址: ws://127.0.0.1:{relay_port}/ws

浏览器 Profile

Profile	说明	场景
crabclaw	独立隔离浏览器配置目录	默认、安全、适合通用自动化
chrome	通过扩展接管现有 Chrome 活动标签页	需要访问已登录会话时使用

扩展连接模式

• Primary: Native Messaging（chrome.runtime.connectNative()）— 强 keepalive，Service Worker 不休眠
• Fallback: WebSocket + 20s heartbeat ping — 当 native messaging 不可用时使用
• 扩展通过 chrome.debugger 连接活动标签页的 CDP
• 徽标状态: ON 已连接、... 连接中、! relay 不可达
• Token 鉴权: 扩展在获取到 relay token 后才建立 WebSocket 连接

架构总览

Chrome Extension ←[Native Messaging / WebSocket]→ Extension Relay ←[内部]→ BrowserController
       ↑                                                ↑
  content.js                                    tool_executor.go
  background.js                               executeBrowserTool()
  chrome.debugger CDP

安全边界

• evaluate 属于高风险动作，除非任务确实需要，不要默认执行自定义脚本
• 遇到登录页时，不要代替用户处理短信码、邮箱码、验证码或 2FA
• 如果页面提供二维码登录，应返回页面截图给用户，由用户自行扫码
• close_tab 只在用户明确要求关闭某个标签页时使用，不要任务结束就顺手关闭
• 浏览器工具适合网页内交互，不应用于系统级桌面控制
• 扩展接力模式可访问已登录上下文，只应在可信本地或 tailnet 环境使用
• 截图中可能包含敏感信息（登录凭据、个人数据），注意不要在日志中明文记录截图内容
• cookies_get 可能返回敏感 Cookie（session token 等），不要在日志或对话中明文暴露
• upload_files 只接受用户明确指定的文件路径，不要自动搜索或猜测文件