@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/tools/browser.md

@@ -1,553 +0,0 @@
----
-read_when:
-  - 添加智能体控制的浏览器自动化
-  - 调试 symi 干扰你自己 Chrome 的问题
-  - 在 macOS 应用中实现浏览器设置和生命周期管理
-summary: 集成浏览器控制服务 + 操作命令
-title: 浏览器（Symi 托管）
-x-i18n:
-  generated_at: "2026-02-03T09:26:06Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: a868d040183436a1fb355130995e79782cb817b5ea298beaf1e1d2cb82e21c4c
-  source_path: tools/browser.md
-  workflow: 15
----
-
-# 浏览器（symi 托管）
-
-Symi 可以运行一个由智能体控制的**专用 Chrome/Brave/Edge/Chromium 配置文件**。
-它与你的个人浏览器隔离，通过 Gateway 网关内部的小型本地控制服务进行管理（仅限 loopback）。
-
-新手视角：
-
-- 把它想象成一个**独立的、仅供智能体使用的浏览器**。
-- `symi` 配置文件**不会**触及你的个人浏览器配置文件。
-- 智能体可以在安全的通道中**打开标签页、读取页面、点击和输入**。
-- 默认的 `chrome` 配置文件通过扩展中继使用**系统默认的 Chromium 浏览器**；切换到 `symi` 可使用隔离的托管浏览器。
-
-## 功能概览
-
-- 一个名为 **symi** 的独立浏览器配置文件（默认橙色主题）。
-- 确定性标签页控制（列出/打开/聚焦/关闭）。
-- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
-- 可选的多配置文件支持（`symi`、`work`、`remote` 等）。
-
-此浏览器**不是**你的日常浏览器。它是一个安全、隔离的界面，用于智能体自动化和验证。
-
-## 快速开始
-
-```bash
-symi browser --browser-profile symi status
-symi browser --browser-profile symi start
-symi browser --browser-profile symi open https://example.com
-symi browser --browser-profile symi snapshot
-```
-
-如果出现"Browser disabled"，请在配置中启用它（见下文）并重启 Gateway 网关。
-
-## 配置文件：`symi` 与 `chrome`
-
-- `symi`：托管的隔离浏览器（无需扩展）。
-- `chrome`：到你**系统浏览器**的扩展中继（需要将 Symi 扩展附加到标签页）。
-
-如果你希望默认使用托管模式，请设置 `browser.defaultProfile: "symi"`。
-
-## 配置
-
-浏览器设置位于 `~/.symi/symi.json`。
-
-```json5
-{
-  browser: {
-    enabled: true, // default: true
-    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
-    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
-    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
-    defaultProfile: "chrome",
-    color: "#FF4500",
-    headless: false,
-    noSandbox: false,
-    attachOnly: false,
-    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-    profiles: {
-      symi: { cdpPort: 18800, color: "#FF4500" },
-      work: { cdpPort: 18801, color: "#0066CC" },
-      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
-    },
-  },
-}
-```
-
-注意事项：
-
-- 浏览器控制服务绑定到 loopback 上的端口，该端口从 `gateway.port` 派生（默认：`18791`，即 gateway + 2）。中继使用下一个端口（`18792`）。
-- 如果你覆盖了 Gateway 网关端口（`gateway.port` 或 `SYMI_GATEWAY_PORT`），派生的浏览器端口会相应调整以保持在同一"系列"中。
-- 未设置时，`cdpUrl` 默认为中继端口。
-- `remoteCdpTimeoutMs` 适用于远程（非 loopback）CDP 可达性检查。
-- `remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 可达性检查。
-- `attachOnly: true` 表示"永不启动本地浏览器；仅在浏览器已运行时附加"。
-- `color` + 每个配置文件的 `color` 为浏览器 UI 着色，以便你能看到哪个配置文件处于活动状态。
-- 默认配置文件是 `chrome`（扩展中继）。使用 `defaultProfile: "symi"` 来使用托管浏览器。
-- 自动检测顺序：如果系统默认浏览器是基于 Chromium 的则使用它；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
-- 本地 `symi` 配置文件会自动分配 `cdpPort`/`cdpUrl` — 仅为远程 CDP 设置这些。
-
-## 使用 Brave（或其他基于 Chromium 的浏览器）
-
-如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），Symi 会自动使用它。设置 `browser.executablePath` 可覆盖自动检测：
-
-CLI 示例：
-
-```bash
-symi config set browser.executablePath "/usr/bin/google-chrome"
-```
-
-```json5
-// macOS
-{
-  browser: {
-    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
-  }
-}
-
-// Windows
-{
-  browser: {
-    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
-  }
-}
-
-// Linux
-{
-  browser: {
-    executablePath: "/usr/bin/brave-browser"
-  }
-}
-```
-
-## 本地控制与远程控制
-
-- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，可以启动本地浏览器。
-- **远程控制（节点主机）：** 在有浏览器的机器上运行节点主机；Gateway 网关将浏览器操作代理到该节点。
-- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程的基于 Chromium 的浏览器。在这种情况下，Symi 不会启动本地浏览器。
-
-远程 CDP URL 可以包含认证信息：
-
-- 查询令牌（例如 `https://provider.example?token=<token>`）
-- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
-
-Symi 在调用 `/json/*` 端点和连接 CDP WebSocket 时会保留认证信息。建议使用环境变量或密钥管理器存储令牌，而不是将其提交到配置文件中。
-
-## 节点浏览器代理（零配置默认）
-
-如果你在有浏览器的机器上运行**节点主机**，Symi 可以自动将浏览器工具调用路由到该节点，无需任何额外的浏览器配置。这是远程 Gateway 网关的默认路径。
-
-注意事项：
-
-- 节点主机通过**代理命令**暴露其本地浏览器控制服务器。
-- 配置文件来自节点自己的 `browser.profiles` 配置（与本地相同）。
-- 如果不需要可以禁用：
-  - 在节点上：`nodeHost.browserProxy.enabled=false`
-  - 在 Gateway 网关上：`gateway.nodes.browser.mode="off"`
-
-## Browserless（托管远程 CDP）
-
-[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。你可以将 Symi 浏览器配置文件指向 Browserless 区域端点，并使用你的 API 密钥进行认证。
-
-示例：
-
-```json5
-{
-  browser: {
-    enabled: true,
-    defaultProfile: "browserless",
-    remoteCdpTimeoutMs: 2000,
-    remoteCdpHandshakeTimeoutMs: 4000,
-    profiles: {
-      browserless: {
-        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
-        color: "#00AA00",
-      },
-    },
-  },
-}
-```
-
-注意事项：
-
-- 将 `<BROWSERLESS_API_KEY>` 替换为你真实的 Browserless 令牌。
-- 选择与你的 Browserless 账户匹配的区域端点（请参阅其文档）。
-
-## 安全性
-
-核心理念：
-
-- 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。
-- 将 Gateway 网关和任何节点主机保持在私有网络上（Tailscale）；避免公开暴露。
-- 将远程 CDP URL/令牌视为机密；优先使用环境变量或密钥管理器。
-
-远程 CDP 提示：
-
-- 尽可能使用 HTTPS 端点和短期令牌。
-- 避免在配置文件中直接嵌入长期令牌。
-
-## 配置文件（多浏览器）
-
-Symi 支持多个命名配置文件（路由配置）。配置文件可以是：
-
-- **symi 托管**：具有独立用户数据目录和 CDP 端口的专用基于 Chromium 的浏览器实例
-- **远程**：显式 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
-- **扩展中继**：通过本地中继 + Chrome 扩展访问你现有的 Chrome 标签页
-
-默认值：
-
-- 如果缺少 `symi` 配置文件，会自动创建。
-- `chrome` 配置文件是内置的，用于 Chrome 扩展中继（默认指向 `http://127.0.0.1:18792`）。
-- 本地 CDP 端口默认从 **18800–18899** 分配。
-- 删除配置文件会将其本地数据目录移至回收站。
-
-所有控制端点接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
-
-## Chrome 扩展中继（使用你现有的 Chrome）
-
-Symi 还可以通过本地 CDP 中继 + Chrome 扩展驱动**你现有的 Chrome 标签页**（无需单独的"symi"Chrome 实例）。
-
-完整指南：[Chrome 扩展](/tools/chrome-extension)
-
-流程：
-
-- Gateway 网关在本地运行（同一台机器）或节点主机在浏览器所在机器上运行。
-- 本地**中继服务器**在 loopback 的 `cdpUrl` 上监听（默认：`http://127.0.0.1:18792`）。
-- 你点击标签页上的 **Symi Browser Relay** 扩展图标来附加（它不会自动附加）。
-- 智能体通过选择正确的配置文件，使用普通的 `browser` 工具控制该标签页。
-
-如果 Gateway 网关在其他地方运行，请在浏览器所在机器上运行节点主机，以便 Gateway 网关可以代理浏览器操作。
-
-### 沙箱会话
-
-如果智能体会话是沙箱隔离的，`browser` 工具可能默认为 `target="sandbox"`（沙箱浏览器）。
-Chrome 扩展中继接管需要主机浏览器控制，因此要么：
-
-- 在非沙箱模式下运行会话，或者
-- 设置 `agents.defaults.sandbox.browser.allowHostControl: true` 并在调用工具时使用 `target="host"`。
-
-### 设置
-
-1. 加载扩展（开发/未打包）：
-
-```bash
-symi browser extension install
-```
-
-- Chrome → `chrome://extensions` → 启用"开发者模式"
-- "加载已解压的扩展程序" → 选择 `symi browser extension path` 打印的目录
-- 固定扩展，然后在你想要控制的标签页上点击它（徽章显示 `ON`）。
-
-2. 使用它：
-
-- CLI：`symi browser --browser-profile chrome tabs`
-- 智能体工具：`browser` 配合 `profile="chrome"`
-
-可选：如果你想要不同的名称或中继端口，创建你自己的配置文件：
-
-```bash
-symi browser create-profile \
-  --name my-chrome \
-  --driver extension \
-  --cdp-url http://127.0.0.1:18792 \
-  --color "#00AA00"
-```
-
-注意事项：
-
-- 此模式依赖 Playwright-on-CDP 进行大多数操作（截图/快照/操作）。
-- 再次点击扩展图标可分离。
-
-## 隔离保证
-
-- **专用用户数据目录**：永不触及你的个人浏览器配置文件。
-- **专用端口**：避免使用 `9222` 以防止与开发工作流冲突。
-- **确定性标签页控制**：通过 `targetId` 定位标签页，而非"最后一个标签页"。
-
-## 浏览器选择
-
-本地启动时，Symi 选择第一个可用的：
-
-1. Chrome
-2. Brave
-3. Edge
-4. Chromium
-5. Chrome Canary
-
-你可以使用 `browser.executablePath` 覆盖。
-
-平台：
-
-- macOS：检查 `/Applications` 和 `~/Applications`。
-- Linux：查找 `google-chrome`、`brave`、`microsoft-edge`、`chromium` 等。
-- Windows：检查常见安装位置。
-
-## 控制 API（可选）
-
-仅用于本地集成，Gateway 网关暴露一个小型的 loopback HTTP API：
-
-- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
-- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
-- 快照/截图：`GET /snapshot`、`POST /screenshot`
-- 操作：`POST /navigate`、`POST /act`
-- 钩子：`POST /hooks/file-chooser`、`POST /hooks/dialog`
-- 下载：`POST /download`、`POST /wait/download`
-- 调试：`GET /console`、`POST /pdf`
-- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
-- 网络：`POST /response/body`
-- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
-- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
-- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
-
-所有端点接受 `?profile=<name>`。
-
-### Playwright 要求
-
-某些功能（navigate/act/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。ARIA 快照和基本截图对于 symi 托管的 Chrome 仍然有效。对于 Chrome 扩展中继驱动程序，ARIA 快照和截图需要 Playwright。
-
-如果你看到 `Playwright is not available in this gateway build`，请安装完整的 Playwright 包（不是 `playwright-core`）并重启 Gateway 网关，或者重新安装带浏览器支持的 Symi。
-
-#### Docker Playwright 安装
-
-如果你的 Gateway 网关在 Docker 中运行，避免使用 `npx playwright`（npm 覆盖冲突）。改用捆绑的 CLI：
-
-```bash
-docker compose run --rm symi-cli \
-  node /app/node_modules/playwright-core/cli.js install chromium
-```
-
-要持久化浏览器下载，设置 `PLAYWRIGHT_BROWSERS_PATH`（例如 `/home/node/.cache/ms-playwright`）并确保 `/home/node` 通过 `SYMI_HOME_VOLUME` 或绑定挂载持久化。参见 [Docker](/install/docker)。
-
-## 工作原理（内部）
-
-高层流程：
-
-- 一个小型**控制服务器**接受 HTTP 请求。
-- 它通过 **CDP** 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。
-- 对于高级操作（点击/输入/快照/PDF），它在 CDP 之上使用 **Playwright**。
-- 当缺少 Playwright 时，仅非 Playwright 操作可用。
-
-这种设计使智能体保持在稳定、确定性的接口上，同时让你可以切换本地/远程浏览器和配置文件。
-
-## CLI 快速参考
-
-所有命令接受 `--browser-profile <name>` 以定位特定配置文件。
-所有命令也接受 `--json` 以获得机器可读的输出（稳定的负载）。
-
-基础操作：
-
-- `symi browser status`
-- `symi browser start`
-- `symi browser stop`
-- `symi browser tabs`
-- `symi browser tab`
-- `symi browser tab new`
-- `symi browser tab select 2`
-- `symi browser tab close 2`
-- `symi browser open https://example.com`
-- `symi browser focus abcd1234`
-- `symi browser close abcd1234`
-
-检查：
-
-- `symi browser screenshot`
-- `symi browser screenshot --full-page`
-- `symi browser screenshot --ref 12`
-- `symi browser screenshot --ref e12`
-- `symi browser snapshot`
-- `symi browser snapshot --format aria --limit 200`
-- `symi browser snapshot --interactive --compact --depth 6`
-- `symi browser snapshot --efficient`
-- `symi browser snapshot --labels`
-- `symi browser snapshot --selector "#main" --interactive`
-- `symi browser snapshot --frame "iframe#main" --interactive`
-- `symi browser console --level error`
-- `symi browser errors --clear`
-- `symi browser requests --filter api --clear`
-- `symi browser pdf`
-- `symi browser responsebody "**/api" --max-chars 5000`
-
-操作：
-
-- `symi browser navigate https://example.com`
-- `symi browser resize 1280 720`
-- `symi browser click 12 --double`
-- `symi browser click e12 --double`
-- `symi browser type 23 "hello" --submit`
-- `symi browser press Enter`
-- `symi browser hover 44`
-- `symi browser scrollintoview e12`
-- `symi browser drag 10 11`
-- `symi browser select 9 OptionA OptionB`
-- `symi browser download e12 /tmp/report.pdf`
-- `symi browser waitfordownload /tmp/report.pdf`
-- `symi browser upload /tmp/file.pdf`
-- `symi browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'`
-- `symi browser dialog --accept`
-- `symi browser wait --text "Done"`
-- `symi browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"`
-- `symi browser evaluate --fn '(el) => el.textContent' --ref 7`
-- `symi browser highlight e12`
-- `symi browser trace start`
-- `symi browser trace stop`
-
-状态：
-
-- `symi browser cookies`
-- `symi browser cookies set session abc123 --url "https://example.com"`
-- `symi browser cookies clear`
-- `symi browser storage local get`
-- `symi browser storage local set theme dark`
-- `symi browser storage session clear`
-- `symi browser set offline on`
-- `symi browser set headers --json '{"X-Debug":"1"}'`
-- `symi browser set credentials user pass`
-- `symi browser set credentials --clear`
-- `symi browser set geo 37.7749 -122.4194 --origin "https://example.com"`
-- `symi browser set geo --clear`
-- `symi browser set media dark`
-- `symi browser set timezone America/New_York`
-- `symi browser set locale en-US`
-- `symi browser set device "iPhone 14"`
-
-注意事项：
-
-- `upload` 和 `dialog` 是**预备**调用；在触发选择器/对话框的点击/按键之前运行它们。
-- `upload` 也可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
-- `snapshot`：
-  - `--format ai`（安装 Playwright 时的默认值）：返回带有数字 ref 的 AI 快照（`aria-ref="<n>"`）。
-  - `--format aria`：返回无障碍树（无 ref；仅供检查）。
-  - `--efficient`（或 `--mode efficient`）：紧凑角色快照预设（interactive + compact + depth + 较低的 maxChars）。
-  - 配置默认值（仅限工具/CLI）：设置 `browser.snapshotDefaults.mode: "efficient"` 以在调用者未传递模式时使用高效快照（参见 [Gateway 网关配置](/gateway/configuration#browser-symi-managed-browser)）。
-  - 角色快照选项（`--interactive`、`--compact`、`--depth`、`--selector`）强制使用带有 `ref=e12` 等 ref 的基于角色的快照。
-  - `--frame "<iframe selector>"` 将角色快照范围限定到 iframe（与 `e12` 等角色 ref 配合使用）。
-  - `--interactive` 输出一个扁平的、易于选择的交互元素列表（最适合驱动操作）。
-  - `--labels` 添加一个带有叠加 ref 标签的视口截图（打印 `MEDIA:<path>`）。
-- `click`/`type` 等需要来自 `snapshot` 的 `ref`（数字 `12` 或角色 ref `e12`）。
-  操作故意不支持 CSS 选择器。
-
-## 快照和 ref
-
-Symi 支持两种"快照"风格：
-
-- **AI 快照（数字 ref）**：`symi browser snapshot`（默认；`--format ai`）
-  - 输出：包含数字 ref 的文本快照。
-  - 操作：`symi browser click 12`、`symi browser type 23 "hello"`。
-  - 内部通过 Playwright 的 `aria-ref` 解析 ref。
-
-- **角色快照（角色 ref 如 `e12`）**：`symi browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
-  - 输出：带有 `[ref=e12]`（和可选的 `[nth=1]`）的基于角色的列表/树。
-  - 操作：`symi browser click e12`、`symi browser highlight e12`。
-  - 内部通过 `getByRole(...)`（加上重复项的 `nth()`）解析 ref。
-  - 添加 `--labels` 可包含带有叠加 `e12` 标签的视口截图。
-
-ref 行为：
-
-- ref 在**导航之间不稳定**；如果出错，重新运行 `snapshot` 并使用新的 ref。
-- 如果角色快照是使用 `--frame` 拍摄的，角色 ref 将限定在该 iframe 内，直到下一次角色快照。
-
-## 等待增强功能
-
-你可以等待的不仅仅是时间/文本：
-
-- 等待 URL（Playwright 支持通配符）：
-  - `symi browser wait --url "**/dash"`
-- 等待加载状态：
-  - `symi browser wait --load networkidle`
-- 等待 JS 断言：
-  - `symi browser wait --fn "window.ready===true"`
-- 等待选择器变得可见：
-  - `symi browser wait "#main"`
-
-这些可以组合使用：
-
-```bash
-symi browser wait "#main" \
-  --url "**/dash" \
-  --load networkidle \
-  --fn "window.ready===true" \
-  --timeout-ms 15000
-```
-
-## 调试工作流
-
-当操作失败时（例如"not visible"、"strict mode violation"、"covered"）：
-
-1. `symi browser snapshot --interactive`
-2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色 ref）
-3. 如果仍然失败：`symi browser highlight <ref>` 查看 Playwright 定位的目标
-4. 如果页面行为异常：
-   - `symi browser errors --clear`
-   - `symi browser requests --filter api --clear`
-5. 深度调试：录制 trace：
-   - `symi browser trace start`
-   - 重现问题
-   - `symi browser trace stop`（打印 `TRACE:<path>`）
-
-## JSON 输出
-
-`--json` 用于脚本和结构化工具。
-
-示例：
-
-```bash
-symi browser status --json
-symi browser snapshot --interactive --json
-symi browser requests --filter api --json
-symi browser cookies --json
-```
-
-JSON 格式的角色快照包含 `refs` 加上一个小的 `stats` 块（lines/chars/refs/interactive），以便工具可以推断负载大小和密度。
-
-## 状态和环境开关
-
-这些对于"让网站表现得像 X"的工作流很有用：
-
-- Cookies：`cookies`、`cookies set`、`cookies clear`
-- 存储：`storage local|session get|set|clear`
-- 离线：`set offline on|off`
-- 请求头：`set headers --json '{"X-Debug":"1"}'`（或 `--clear`）
-- HTTP basic 认证：`set credentials user pass`（或 `--clear`）
-- 地理位置：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
-- 媒体：`set media dark|light|no-preference|none`
-- 时区/语言环境：`set timezone ...`、`set locale ...`
-- 设备/视口：
-  - `set device "iPhone 14"`（Playwright 设备预设）
-  - `set viewport 1280 720`
-
-## 安全与隐私
-
-- symi 浏览器配置文件可能包含已登录的会话；请将其视为敏感信息。
-- `browser act kind=evaluate` / `symi browser evaluate` 和 `wait --fn` 在页面上下文中执行任意 JavaScript。提示注入可能会操纵它。如果不需要，请使用 `browser.evaluateEnabled=false` 禁用它。
-- 有关登录和反机器人注意事项（X/Twitter 等），请参阅 [浏览器登录 + X/Twitter 发帖](/tools/browser-login)。
-- 保持 Gateway 网关/节点主机私有（仅限 loopback 或 tailnet）。
-- 远程 CDP 端点功能强大；请通过隧道保护它们。
-
-## 故障排除
-
-有关 Linux 特定问题（特别是 snap Chromium），请参阅[浏览器故障排除](/tools/browser-linux-troubleshooting)。
-
-## 智能体工具 + 控制工作原理
-
-智能体获得**一个工具**用于浏览器自动化：
-
-- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
-
-映射方式：
-
-- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
-- `browser act` 使用快照 `ref` ID 来点击/输入/拖动/选择。
-- `browser screenshot` 捕获像素（整页或元素）。
-- `browser` 接受：
-  - `profile` 来选择命名的浏览器配置文件（symi、chrome 或远程 CDP）。
-  - `target`（`sandbox` | `host` | `node`）来选择浏览器所在位置。
-  - 在沙箱会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。
-  - 如果省略 `target`：沙箱会话默认为 `sandbox`，非沙箱会话默认为 `host`。
-  - 如果连接了具有浏览器能力的节点，工具可能会自动路由到该节点，除非你指定 `target="host"` 或 `target="node"`。
-
-这使智能体保持确定性并避免脆弱的选择器。