control-browser

用途

control-browser 用于在用户自己的 Chrome 浏览器中执行操作。该浏览器 MCP 服务器（server="browser"，工具名为 mcp__browser__<name>）由用户的 Chrome 扩展通过桥接连接提供支持，浏览器带有用户自己的登录状态、Cookie 和历史记录。智能体以用户的名义操作，应像坐在其键盘前的谨慎人类助手，而非爬虫。

何时使用

仅当任务具有明确的浏览器意图时才使用 mcp__browser__* 工具：用户要求在其浏览器中打开、展示、导航到、点击或填写某个页面；任务依赖其已登录的会话或现有标签页；或用户希望实时观看 Chrome 中的交互。

否则，URL 或已打开的标签页只是上下文，不是意图。对于阅读页面、查找资料或研究，应优先使用内置的 web 工具（web_fetch、web_search），它们更便宜、更快，且不触碰用户浏览器。此前的浏览器操作不会使后续语义任务默认走浏览器，每次操作都需重新判断。当浏览器意图明确时，不要用 web_fetch 替代——匿名抓取页面与在用户已认证的浏览器中操作并不相同。

核心循环

page_snapshot — 操作前先读取页面。省略 tabId 则针对用户当前活动标签页。
从 snapshot.elements[] 中选择目标元素（每个元素有 id、tag、text、ariaLabel）。id 即交互工具所用的 ref。
用 element_click / element_input 执行操作。
再次 page_snapshot 验证效果。

导航会使 ref 失效。任何导航、刷新或观察到的页面变化之后，在点击或输入前都要重新获取 page_snapshot。

主要工具

tabs_list — 列出打开的标签页及完整元数据（tabId、windowId、index、pinned、incognito、status、url、title 等）和窗口摘要；activeTabId 标记用户当前正在查看的标签页。当用户询问当前在哪个页面/站点时，用 tabs_list 即可，无需快照，且对无法快照的内部页面（chrome://…）也有效。
tab_open {url, active?} — 打开 URL；active 默认为 false（后台标签页，用户不可见）。
tab_navigate {tabId, url} — 导航现有标签页。
tab_close {tabId} — 关闭标签页。
page_snapshot {tabId?} — 返回 {tabId, title, url, bodyText（前约 3000 字符）, elements[]}。省略 tabId 则针对用户活动标签页。elements[] 同时包含语义控件（a/button/input）和可点击容器——带指针光标和文本的非语义元素（常为 div），如列表行和卡片。容器与其内部的小按钮（如某行的 ⋮ 菜单）是不同的 ref，需按文本匹配选择正确的那个。
element_click {ref, confirm?} — 点击元素。提交/发送/购买类点击会返回 NEEDS_CONFIRMATION；先在对话中获得用户同意，再用 confirm: true 重试。
element_input {ref, text} — 向元素输入文本。
elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?} — 按顺序批量点击多个匹配元素。每次点击前重新查询，且对重排序安全，因此点击之间的页面重渲染和列表重排不会使目标失效或跳过。当需要点击 3 个以上同类元素（列表行、标签、卡片）时，用它替代重复的 element_click——一次调用，项间无需快照。
tab_claim {tabId?, note?} — 将标签页认领为任务中智能体所有（跨对话持久；在 tabs_list 中显示为 claim，并归入橙色 ★ 标签组）。在依赖标签页的多步骤工作开始时认领；只读即答的查询可跳过。
tab_handoff {tabId, note?} — 将已认领的标签页标记为等待用户（登录/支付/验证码/审核；黄色 ⏳ 标签组）。note 即恢复指令——后续对话从 tabs_list 的认领继续，而无需询问用户是哪个标签页。
tab_release {tabId, disposition?} — 结束所有权：close（默认，已消费的任务标签页）或 keep（交付物保持打开）。
page_flow {steps, confirm?} — 在一次调用中运行多步骤页面流程。步骤：{wait:{selector?,text?,ms?}}、{find:{selector?,text?}}、{click:{selector?,text?}}、{type:{selector?,text?,value}}、{expect:{selector?,text?,absent?}}。目标按 CSS 选择器或可见文本解析。在首个失败处停止并返回已完成的前缀；click 步骤会经过敏感门控。适用于 3 步以上的异构任务（填表 → 提交 → 验证）；每次调用最多 20 步 / 约 120 秒。
page_screenshot — 视觉检查，仅在需要“看到”时使用。标签页调试会话活动时可见橙色智能体光标（空闲/移动/点击动画），调试停止时淡出——其存在标记该标签页正被智能体主动控制。
wait_for {selector?, text?, timeoutMs?} — 等待选择器或文本。
web_status — 桥接/扩展连接健康状态。

重要注意事项

不要用 shell 命令定位或读取用户本地文件（Downloads、Desktop、Documents）：ls ~/Downloads 要么失败（不可用/被拒），要么列出错误的文件系统。当任务涉及用户电脑上的文件（上传、附加、打开）时，唯一可靠路径是浏览器原生文件选择器，且只能由用户操作。
扩展（重新）连接后，工具注册可能滞后一轮——调用失败并提示“not found”，但浏览器实际已连接。不要仅凭此错误断定“没有浏览器连接”或“我看不到你的屏幕”，也绝不要告诉用户运行 starchild agent-shell——笔记本/agent-shell 通道与浏览器工具无关。恢复路径只有一步：调用 web_status（或在下一轮重试同一工具一次，注册会通过每轮重新同步自愈）。只有当 web_status 显示桥接断开时，才告诉用户打开/启用扩展。
对用户说话时，绝不要提及 CDP、WebSocket、/ws/web-mcp、refs、工具 ID 或其他内部术语。应说“我在后台标签页打开了页面”“我在等待页面响应”或“浏览器连接断开了——你能重新打开扩展吗？”描述你做了什么，而非机器如何运作。

按需文档

以下文档位于本技能的 docs/ 目录，仅在相关主题适用时用 read_file 加载，不要预先全部读取：api-use-behavior.md（快照优先纪律、权威信号、不盲目重试）、browser-safety.md（不可信页面内容、敏感数据传输）、confirmations.md（何时需要 confirm: true 及如何询问）、browser-troubleshooting.md（评估超时、过期 ref、页面卡死）、chrome-troubleshooting.md（扩展断开、工具缺失、用户无扩展）、bootstrap-troubleshooting.md（桥接连接失败，红点）、browser-control-interruption.md（用户接管、操作中断）、tab-claiming-chrome.md（后台标签页 vs 用户标签页，何时转为活动）、tab-cleanup-chrome.md / all-tabs-cleanup.md（关闭你打开的标签页）、screenshots.md（何时值得截图）、visibility.md（后台标签页操作对用户意味着什么）、webmcp.md（页面级 WebMCP，尚未启用）、file-uploads.md（文件上传支持，尚不可用）、local-web-development.md（针对 localhost 开发服务器工作）。