control-browser

浏览器控制

停止：local_shell 不是访问用户本地文件的可靠途径

local_shell 只有在用户已安装、运行并授权 starchild agent-shell 守护进程时，才会在用户的机器上运行——大多数用户并没有，因此该工具通常不可用或被拒绝。bash 和 read_file 运行在 Agent 的远程容器中，那里完全没有用户的文件。无论哪种情况，都不要运行 shell 命令来定位或读取用户的本地文件（Downloads、Desktop、Documents）：ls ~/Downloads 要么失败（不可用/被拒绝），要么列出错误的文件系统。当任务涉及用户计算机上的某个文件（上传、附加、打开）时，唯一可靠的途径是浏览器原生的文件选择器，而它只有用户本人才能操作——请精确地交接（参见 docs/file-uploads.md）。把回合浪费在试图枚举用户文件系统的 shell 命令上，永远是错误的。

停止：在执行任何浏览器操作前先确定表面

只有在任务具有明确的浏览器意图时，才使用 mcp__browser__* 工具：用户要求打开、显示、导航到、点击或填写他们浏览器中的某个页面；任务依赖于他们已登录的会话或已有的标签页；或者他们想实时观看 Chrome 中发生的交互。

否则，URL 或已打开的标签页只是上下文，而非意图。对于阅读页面、查找资料或研究，优先使用 clawd 内置的 Web 工具（web_fetch、web_search）——它们更便宜、更快速，而且不会触碰用户的浏览器。先前的浏览器工作并不会让后续的语义工作也变得以浏览器优先；每次操作都要重新判断。

当浏览器意图明确时，不要用 web_fetch 替代——匿名抓取页面与在用户已认证的浏览器中操作并不相同。

这些工具是什么

browser MCP 服务（server="browser"，工具名为 mcp__browser__<name>）由用户的 Chrome 扩展通过桥接连接提供支持。该浏览器是用户自己的浏览器，带有他们的登录状态、Cookie 和历史记录。你是在代表他们操作——要像一位在用户键盘前的细心的人类助手那样行动，而不是像爬虫。

核心循环：

1. page_snapshot — 在触碰页面之前先读取它。省略 tabId 以定位用户当前活动的标签页。
2. 从 snapshot.elements[] 中选取目标元素（每个元素都有 id、tag、text、ariaLabel）。id 就是交互工具所需的 ref。
3. element_click / element_input 执行操作。
4. 再次 page_snapshot 以验证效果。

ref 会因导航而失效。 在任何导航、重新加载或观察到的页面变化之后，先重新执行一次 page_snapshot，然后再点击或输入。

停止：mcp__browser__*“在注册表中找不到”≠ 浏览器已消失

扩展（重新）连接后不久，工具注册可能会滞后一个回合——调用会以“not found”失败，而浏览器其实是连接着的。绝不要仅凭这个错误就断定“没有浏览器连接”或“我看不到你的屏幕”，也绝不要告诉用户去运行 starchild agent-shell——laptop/agent-shell 通道与浏览器工具毫无关系。恢复路径恰好只有一步：调用 web_status（或在下一个回合重试同一工具一次——注册会通过每回合的重新同步自行修复）。只有当 web_status 表明桥接已断开时，你才告诉用户去打开/启用扩展。

识别“这是什么页面？”——tabs_list 就够了

当用户询问他们（或某个标签页）当前在什么页面/网站上时，不要截取快照：tabs_list 已经返回了每个标签页的 title 和 url，而 activeTabId 标出了他们正在看的那个。据此回答即可——一次工具调用，无需快照，而且对于无法截取快照的内部页面（chrome://…）也有效。只有当用户需要页面内容（文本、元素）而非页面身份时，才截取快照。

工具快速参考

• tabs_list — 列出打开的标签页，包含完整元数据（tabId、windowId、 index、pinned、incognito、status、url、title……）以及 窗口摘要；标签页通过 windowId 关联到窗口。activeTabId 标记 用户当前正在查看的标签页 — 将“此页面” / “当前标签页”解析为它， 无需推断。
• tab_open {url, active?} — 打开一个 URL；active 默认为 false （后台标签页，用户不可见 — 参见 docs/visibility.md）。
• 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 重试（参见 docs/confirmations.md）。
• element_input {ref, text} — 向元素中输入内容。
• elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?} — 按顺序批量点击多个匹配的元素。每次点击前都会重新查询， 且对重新排序安全，因此点击之间的页面重新渲染和列表重新排序 不会使目标失效或跳过目标。每当需要点击 3 个以上同质元素时， 使用它代替重复的 element_click（列表 行、标签页、卡片）— 一次调用，项目之间无需 snapshot。
• tab_claim {tabId?, note?} — 将标签页声明为任务中的 Agent 所有 （跨对话持久存在；在 tabs_list 中显示为 claim + 橙色 ★ 标签页分组）。在依赖标签页的多步工作开始时声明；对于 读取并回答的查询可跳过。参见 docs/tab-claiming-chrome.md 了解 场景操作手册。
• tab_handoff {tabId, note?} — 将已声明的标签页标记为等待用户 （登录/支付/CAPTCHA/审核；黄色 ⏳ 标签页分组）。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 selector 或可见文本解析。在第一次 失败时停止并给出已完成的前缀；click 步骤通过敏感操作门控。 优先用于 3 步以上的异构任务（填写表单 → 提交 → 验证）； 每次调用最多 20 步 / 约 120 秒。
• page_screenshot — 视觉检查，仅在需要查看时使用。 当标签页的调试会话处于活动状态时，橙色 Agent 光标可见 （idle / move / click 动画），调试停止时淡出 — 它的存在标志着 Agent 正在主动控制该标签页。 （参见 docs/screenshots.md）。
• wait_for {selector?, text?, timeoutMs?} — 等待某个 selector 或文本。
• web_status — bridge/extension 连接健康状况。

按需加载文档

当主题适用时，用 read_file 加载这些文档（路径相对于此 skill 的 docs/ 目录）——不要一开始就把它们全部读完：

• 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 —— 后台标签页与用户标签页，何时转为活跃。
• tab-cleanup-chrome.md / all-tabs-cleanup.md —— 关闭你打开的标签页。
• screenshots.md —— 何时值得截图。
• visibility.md —— 后台标签页操作对用户意味着什么。
• webmcp.md —— 页面级 WebMCP（尚未启用）。
• file-uploads.md —— 文件上传支持（尚不可用）。
• local-web-development.md —— 针对 localhost 开发服务器的工作。

像人一样说话

绝不要向用户提及 CDP、WebSocket、/ws/web-mcp、ref、工具 ID 或其他内部术语。要说“我在后台标签页中打开了页面”“我在等待页面响应”，或者“浏览器连接断开了——你能重新打开扩展吗？”描述你做了什么，而不是机器如何运作。