use-browser

name	use-browser
version	0.5.0
trigger	浏览器|打开网页|网页操作|自动填表|网页截图|点击页面|输入文本|操作我的浏览器|我的浏览器|本机 Chrome|浏览器 cookie|扩展工具|真实 tab|接管当前页面
fast_path	true
description	主浏览器技能：通过 browser_session / browser_tab / browser_page / browser_client 四个工具操作本机 Chrome（需 Ethan Browser 扩展）。嵌入本机真实 Cookie，能操作用户已登录的浏览器、接管当前 tab、做 snapshot/click/fill/screenshot/eval。支持多个浏览器同时连接，每个有自己的名字，agent 按需选择操作哪个端。当用户要求操作浏览器、网页自动化、点击输入、或需要用到本机真实 Chrome（含登录态）时触发。兜底用 agent-browser。

浏览器控制使用规则

本技能指导你用 browser_session / browser_tab / browser_page / browser_client 四个工具操作 ethan server 所在机器上的真实 Chrome（需已安装并连接 Ethan Browser 扩展）。多个浏览器可同时连接，每个有自己的名字。

适用场景

• 用户要求操作浏览器、做网页自动化：创建 session、观察页面、点击、输入、截图、执行 JS。
• 需要操作本机 Chrome 中的 tab、tab group、当前 active tab。
• 需要复用用户登录态/cookie：直接接管用户已登录的 Chrome tab（attach_current），不必重新登录。
• 多个浏览器同时连接：用户可能有多台机器都装了扩展并连到同一个 Ethan Server，每台有自己的名字，按需选择操作哪个。

不要用它替代普通网页信息检索；只需查公开网页信息时优先用 web_search / web_fetch。

三档浏览器技能的分工（重要）

系统里有三个浏览器技能，默认永远从本技能（use-browser）开始，只在明确命中下面的边界时才切换：

	use-browser（本技能，主入口）	agent-browser（隔离/兜底）	dev-browser（脚本档）
定位	日常交互首选	use-browser 不可用 or 要隔离	复杂多步/批量脚本
浏览器	本机真实 Chrome	内置独立 Chrome（隔离 profile）	沙箱 Chromium
登录态/cookie	✅ 复用用户真实 cookie	独立 profile，需自己登录	独立，需自己登录
接管当前 tab	✅ attach_current	❌ 只能自己 open	❌ 只能自己 open
交互方式	结构化 ref / 坐标，逐步操作	CLI 逐条命令	一段 JS + 完整 Playwright API
依赖	Ethan Browser 扩展 + 本机 Chrome	agent-browser CLI	dev-browser CLI
适合	点击、填表、截图、接管登录页	简单离散操作、干净登录流程	循环、条件、遍历多页、聚合结构化结果

选择规则：

1. 默认用 use-browser——只要本机装了扩展、要操作用户已登录的站，就用它。
2. 退到 agent-browser 的条件：扩展未装/未连、server 不在本机、或需要一个隔离的独立 profile（测干净登录流程、不想动用户日常 Chrome）。
3. 切到 dev-browser 的条件：任务需要循环 / 条件判断 / 遍历多页 / 把多页数据聚合成结构化结果——即"一个脚本跑完多步"。单步操作不要用它（更费 token）。

核心原则

1. session 是浏览器操作空间，一个 session 对应一个 Chrome Tab Group。
2. browser_page 默认作用于该 session 的 active tab；要换目标 tab 先用 browser_tab action=activate。
3. snapshot 生成的 ref 只对最近一次页面上下文可靠；页面 reload/navigation 后必须重新 snapshot。
4. 默认用结构化 ref 操作；只有 ref 不可用或需要 GUI 级交互时才用 mouse 坐标操作。
5. 坐标是 viewport CSS pixel，不是屏幕绝对坐标。
6. eval 权限很高，只在任务需要时使用，不要对不可信页面执行无关脚本。
7. 工具输出是 snake_case JSON；每次返回含 _hint 字段，说明本次输出的字段含义和下一步用法（如 snapshot 的 ref 格式、get 的 value 字段）。交互操作（click/fill/type/press 等）的返回还含 _step 字段，表示当前会话累计操作步数。
8. 授权是会话级的：本对话第一次调用任意 browser 工具会请求一次授权，批准后本对话后续操作（含 eval）不再询问。
9. 多浏览器客户端：多个浏览器可同时连接 Ethan Server，每个在扩展 popup 里设了自己的「本端名称」（如 work-laptop、home-mac）。当前对话的活跃客户端一旦选定，后续所有 browser 操作都路由到它。详见下方「多浏览器客户端管理」。

多浏览器客户端管理

多个浏览器（如办公电脑、家用电脑）可同时连接 Ethan Server。每个浏览器在扩展 popup 的「本端名称」字段里设置自己的名字，留空则服务端自动分配 browser-N。

工具：browser_client

action	作用	关键返回字段
list	列出所有已连接的浏览器客户端	clients（含 name/connected）、active（当前对话的活跃客户端）
use	设置当前对话使用哪个客户端（name 必填）	ok、active
status	查看当前活跃客户端 + 全部已连接客户端	active、clients

选择规则

1. 只有一个客户端连接 → 自动选中，无需手动 use。
2. 多个客户端连接且未设活跃 → 任何 browser 操作会返回错误，提示「当前有 N 个浏览器客户端已连接: ...。请先用 browser_client(action='use', name='客户端名称') 选择一个」。
3. 用户在消息里指明了浏览器（如「用 work-laptop 打开...」「在 home-mac 上...」）→ 直接 browser_client(action='use', name='work-laptop')，不必再问。
4. 不确定用哪个 → 用 browser_client(action='list') 列出已连接客户端，然后问用户「检测到 N 个浏览器已连接：work-laptop、home-mac。你想操作哪个？」，不要自行猜测。

活跃客户端是会话级的：设一次后整个对话都生效，不同对话可以绑不同的浏览器。

常见流程

# 不确定有几个浏览器连着 → 先查
browser_client(action="list")

# 只有一个 → 自动选中，直接开干（先检查可复用的 session）
browser_session(action="list")
# 若 list 结果有 status="available" 的 session（标题/URL 匹配任务目标）→ 复用
browser_session(action="attach", session="已有的session_id")
# 若无可复用的 → 在后台新建
browser_session(action="create", url="https://example.com", background=true)

# 多个且用户没指明 → 问用户后再选
browser_client(action="use", name="work-laptop")
browser_session(action="list")  # 先查已有 session
browser_session(action="create", url="https://example.com", background=true)

# 用户消息里已指明 → 直接选
# 用户：「用 home-mac 打开 youtube」
browser_client(action="use", name="home-mac")
browser_session(action="list")  # 先查已有 session
browser_session(action="create", url="https://www.youtube.com", background=true)

客户端断连

活跃客户端断连后，再次操作浏览器会报「客户端 'xxx' 未连接」。此时：

1. browser_client(action="list") 看还有哪些在线
2. 若只剩一个，自动选中；若仍有多个，问用户换哪个

步骤预算

任务开始前先估算预期步数，在任务说明里写出来（如"预计 8 步完成"）。每次交互操作返回的 _step 字段是当前累计步数：

• 步数 ≥ 20：进入收尾模式——只做必要的剩余步骤，不再探索新路径。
• 步数 ≥ 30：立即停止，输出中间结论报告（已完成什么、剩余什么、建议下一步），不再继续操作。

复杂任务（登录+多步流程）预算可放宽到 40，但须在任务开始时明确说明。

失败重试策略

同一元素/操作连续失败的处理路径：

1. 第 1 次失败：重新 snapshot，用新 ref 重试。
2. 第 2 次失败：换策略——用 selector 缩小 snapshot 范围、或换 eval 方式操作，再试一次。
3. 第 3 次失败：停止重试，上报 blocker：说明目标、已尝试方法、失败原因，让用户介入。

绝不对同一操作重试超过 3 次。

截图原则

截图（screenshot）开销大，严格限制使用：

• 任务最终验证时截一次：需要向用户展示结果、或验证关键操作是否生效时。
• 真正无法用 snapshot 判断的视觉问题：如样式渲染、图片加载、动画状态。
• 其他情况用 snapshot 或 get 替代，不要用截图观察页面状态。

AX 树不稳定的兜底路径

当 ref not found 或元素定位失败时，按顺序尝试：

1. click_selector / fill_selector — 用 CSS/XPath/text 直接定位 + CDP mouse 真实点击（不依赖 snapshot，绕过 ref 失效和 covered-by 拦截）
2. selector 缩小 snapshot 区域重新取 ref（如 selector="#form"）
3. get action="html" 读取目标区域 HTML，从中找稳定 selector
4. click_vlm — 截图发给多模态 LLM 识别坐标后点击（终极 fallback，适用于 Canvas/图片按钮/Semi-UI 自定义组件等 AX 树不可靠的场景）
5. eval 直接操作 DOM（document.querySelector(...).click()，但对 React 组件可能无效）
6. 以上都失败则上报 blocker

Selector 直接操作（不依赖 snapshot）

当 snapshot 截断、ref 失效、或 covered-by 拦截时，用 selector 操作绕过：

# CSS selector 点击
browser_page(action="click_selector", session=SID, selector=".radio-M-plus")

# XPath 点击
browser_page(action="click_selector", session=SID, xpath="//button[text()='提交']")

# 按文本点击（取第 nth 个匹配）
browser_page(action="click_selector", session=SID, text="字节范", nth=0)

# 填输入框（兼容 React）
browser_page(action="fill_selector", session=SID, selector="#search-input", text="关键词")

# 悬停
browser_page(action="hover_selector", session=SID, selector=".dropdown-trigger")

# 等待元素出现（轮询，默认 10s 超时）
browser_page(action="wait_for_element", session=SID, selector=".result-item", timeout=15000)

# 按文本滚动定位
browser_page(action="scroll_to_text", session=SID, text="绩效总结")

# 提取页面内容
browser_page(action="extract_content", session=SID, selector=".main-content")

# 查找元素列表
browser_page(action="find_elements", session=SID, selector="button.btn-primary")

# 获取元素属性
browser_page(action="find_attributes", session=SID, selector="a.download", attributes=["href", "title"])

# 检查元素是否存在
browser_page(action="check_exist", session=SID, selector=".loading-spinner")

# 输入+回车（搜索框场景）
browser_page(action="input_enter", session=SID, selector="#search-box", text="查询内容")

# 边滚动边查找元素
browser_page(action="scroll_find", session=SID, selector=".lazy-loaded-item", scroll_times=5)

优势：不依赖 snapshot ref，不会因截断或 covered-by 失败。底层用 eval 获取坐标 + CDP mouse 真实点击（不是 eval .click()），对 React/Semi-UI 组件有效。

VLM 视觉点击

当 AX 树和 selector 都不可靠时（Canvas 应用、图片按钮、自定义组件），用 VLM 视觉点击：

browser_page(action="click_vlm", session=SID, prompt="字节范 M+ 按钮")

流程：截图 → 发给多模态 LLM 识别坐标 → CDP mouse 点击。需要当前模型支持视觉（如 claude-sonnet、gpt-4o）。

推荐任务流程

打开新页面并操作

browser_session(action="create", url="https://www.example.com", title="任务")

记录返回的 session_id，后续操作用它：

browser_page(action="snapshot", session=SID, interactive=true, compact=true, depth=3, format="text")
browser_page(action="click", session=SID, ref="e1")
browser_page(action="fill", session=SID, ref="e2", text="hello")

任务结束：对话结束时系统会弹确认卡片让用户选择 close（关闭 tab group）或 keep（保留 tab）。

• 保留的 session 下次对话可通过 list + attach 复用（status="available"）。
• 默认 keep_alive=false 的 session 会弹确认；keep_alive=true 的自动保留。

# 创建时标记保留（帮个忙、页面用户还要看）
browser_session(action="create", url="...", keep_alive=true, background=true)

# 也可显式 release/close
browser_session(action="release", session=SID)   # 保留 tab，放掉控制权
browser_session(action="close", session=SID)      # 关闭整个 tab group

Session 复用（操作前必做）

每次需要操作浏览器时，先 list 检查是否有可复用的 session：

browser_session(action="list")
# 返回 sessions 列表，每个有 status 字段：
#   "owned" = 当前对话已绑定的
#   "available" = 之前保留的，可通过 attach 复用

如果找到 status="available" 且标题/URL 匹配当前任务目标的 session：

browser_session(action="attach", session=SID)  # 获取控制权
browser_page(action="snapshot", session=SID, ...)  # 直接操作

如果 attach 失败或无可复用 session，再新建：

browser_session(action="create", url="...", background=true)  # 后台新建，不抢焦点

何时设 keep_alive=true：用户说「帮我看下这个页面」「打开这个链接我等会看」等只需一次性操作、但页面本身用户还要继续浏览的场景。 何时不设（默认 false）：Agent 自己打开的工作页面（填表单、抓数据、自动填报等），任务做完就没用了。

接管当前 Chrome tab

用户已在 Chrome 打开目标页面时：

browser_session(action="attach_current", title="任务")

多 tab 操作

browser_tab(action="open", session=SID, url="https://example.com")
browser_tab(action="list", session=SID)
browser_tab(action="activate", session=SID, tab=TAB_ID)
browser_tab(action="close", session=SID, tab=TAB_ID)

Tab 整理（批量分组/移出/排序/清理）

核心原则：整理 ≠ 关闭。 用户要求"整理 tab"时，目标是把散乱的标签归类分组，而不是关掉它们。

绝对禁止

• ❌ 不要关闭已创建的 tab group（session） —— 分组是整理的最终产出，不是临时容器。创建的分组必须保留给用户
• ❌ 不要关闭用户正在浏览的有内容的标签 —— 除非明确属于下面"可以关闭"的类别
• ❌ 不要用 browser_page(action="eval") 调用 chrome.tabs.* / chrome.tabGroups.* API —— 内容脚本无权调用这些扩展 API，必定失败。标签管理只通过 browser_tab 和 browser_session 工具完成
• ❌ 不要绕弯路 —— 不要 find_tools、不要找其他技能/脚本，直接用 browser_tab + browser_session
• ❌ 不要创建"临时 session"整理完后关掉 —— session 就是 Chrome Tab Group，创建即分组，整理完保持打开

可以关闭的标签（清理规则）

只有以下类型的标签可以关闭：

1. 完全重复的标签：URL 完全相同的多个 tab，只保留一个
2. 明显无用的空白页：如 chrome://newtab、空白的搜索引擎首页（百度/Google 首页但没有搜索内容）
3. 用户明确要求关闭的标签

其他所有标签都应保留并归入合适的分组。

正确操作流程

# 1. 获取所有 tab（包括已分组和未分组的）
browser_tab(action="list")        # 已有 session 管理的 tab
browser_tab(action="user_list")   # 未分组的 tab

# 2. 根据 URL/title 语义分类，规划分组方案（在脑中完成，不要调工具）

# 3. 创建分组（session = Chrome Tab Group，创建后永久保留）
browser_session(action="create", title="分组名", color="blue")

# 4. 批量归入（用 attach_batch 一次性操作，效率最高）
browser_tab(action="attach_batch", session=SID, tabs=[TAB_ID1, TAB_ID2, TAB_ID3])

# 5. 仅关闭重复/无用 tab（严格按清理规则）
browser_tab(action="close", session=SID, tab=TAB_ID)

# 6. 微调：移动 tab 位置、在分组间转移
browser_tab(action="move", session=SID, tab=TAB_ID, index=0)
browser_tab(action="detach", session=SID, tab=TAB_ID)  # 移出分组

效率要求

• 用 attach_batch 批量操作，不要一个个 tab 逐个 attach
• 先规划再执行：看完所有 tab 后一次性规划分组方案，然后按组批量操作
• 分组颜色搭配合理，不同类别用不同颜色区分

分组建议策略

根据 tab 的 URL 和标题自动推断类别，常见分组：

• 工作文档（飞书/Google Docs/Notion 等）
• 代码相关（GitHub/GitLab/代码平台）
• 监控数据（Grafana/APM/数据看板）
• 沟通协作（邮件/IM/会议）
• 学习参考（技术博客/文档/Stack Overflow）
• 生活娱乐（购物/视频/社交）

不必强行覆盖所有类别，根据实际 tab 内容灵活分组。

更新 Session（分组颜色/标题）

# 修改分组颜色和标题
browser_session(action="update", session=SID, title="工作", color="blue")

支持的颜色：grey、blue、red、yellow、green、pink、purple、cyan、orange。

Snapshot 策略

不要默认 dump 大页面。优先小窗口观察：

browser_page(action="snapshot", session=SID, interactive=true, compact=true, depth=3, format="text")

常用选项：

• interactive=true：只看交互元素，推荐默认。
• compact=true：压缩空结构节点。
• depth=<n>：限制树深度。
• selector="#main"：限定 DOM 子树。
• cursor=true：补充 cursor:pointer / onclick / tabindex 元素。
• urls=true：需要链接 href 时开启。
• format="text"：适合阅读；默认 json 适合解析。

输出过大时按顺序收缩：开 interactive、开 compact、降低 depth、用 selector 限定区域。

Snapshot 分页（大页面必读）

snapshot 完整内容会落盘到 /tmp/ethan-snapshots/ 下，prompt 里只带首段约 10000 字。返回 JSON 含以下分页字段：

• snapshot_path：完整 snapshot 的文件路径
• total_chars：完整内容总字符数
• chunk_offset：当前段的起始偏移（首段为 0）
• chunk_length：当前段的实际长度
• has_more：是否还有后续内容

has_more=true 时，当前 snapshot 字段只是首段，目标元素可能不在里面。用 snapshot_read 翻页读取后续内容：

browser_page(action="snapshot_read", path=SNAPSHOT_PATH, offset=CHUNK_LENGTH)