@flrande/browserctl 0.1.0 → 0.2.0-dev.9.1

package/README-CN.md

@@ -2,1154 +2,65 @@
 
 [English](README.md) | 简体中文
 
-通用浏览器控制 CLI + daemon，采用 MCP 风格的工具路由。
+最快路径：通过 relay 扩展直接控制你已打开的 Edge/Chrome。
 
-## 这个 CLI 做什么
+## 扩展模式最简上手（推荐）
 
-`browserctl` 是 `browserd` 的 TCP 客户端。
-
-1. 解析命令行参数。
-2. 向 `browserd` 发送工具调用。
-3. 当 daemon 不可达时，自动拉起 `browserd` 并重试一次。
-
-根包也发布了以下可执行入口：
-
-- `browserctl` -> `bin/browserctl.cjs`
-- `browserd` -> `bin/browserd.cjs`
-
-## 快速开始
-
-先决条件：
+前置条件：
 
 - Node.js 22+
-- pnpm
+- npm 或 pnpm
 - PowerShell 7 (`pwsh`)
+- Edge 或 Chrome
 
-最小启动（首次体验，约 2 分钟）：
-
-```powershell
-pnpm install
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json
-```
-
-仓库完整校验（贡献代码前建议执行）：
-
-```powershell
-pnpm lint
-pnpm typecheck
-pnpm run test:all
-pnpm build
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
-
-以持久 TCP 模式启动 daemon：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-```
-
-在当前 shell 覆盖 daemon 端口：
-
-```powershell
-$env:BROWSERCTL_DAEMON_PORT = "42491"
-```
-
-## 发布流程
-
-发布前建议按以下顺序执行：
-
-```powershell
-pnpm lint
-pnpm typecheck
-pnpm run test:all
-pnpm build
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
-
-打 tag 发布：
+1. 安装已发布包：
 
 ```powershell
-$version = node -p "require('./package.json').version"
-git tag "v$version"
-git push origin "v$version"
+npm install --global @flrande/browserctl
+# 或：pnpm add --global @flrande/browserctl
 ```
 
-说明：
-
-- `publish.yml` 会先跑跨平台 verify 矩阵，再执行发布。
-- 发布作业会上传 dry-run 与 npm dist-tag 工件，便于追踪与回滚评估。
-- 手动触发（`workflow_dispatch`）支持 `dry_run` 与 `dist_tag`。
-
-## 新手先看（推荐顺序）
-
-如果你是第一次用，建议按下面顺序：
-
-1. 先跑一次“最小启动”。
-2. 先走路径 A（`managed-local`，推荐）。
-3. 只有在你要控制“已打开的浏览器”时，再走路径 B（`chrome-relay`）。
-
-### 路径 A：控制一个新启动的本地浏览器（推荐）
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo --profile managed-local https://example.com
-pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo --profile managed-local
-```
-
-可选：在 PowerShell 里自动取 `targetId` 后抓快照：
-
-```powershell
-$tabs = pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo --profile managed-local | ConvertFrom-Json
-$targetId = $tabs.data.tabs[0]
-pnpm exec tsx .\apps\browserctl\src\main.ts snapshot --json --session demo --profile managed-local $targetId
-pnpm exec tsx .\apps\browserctl\src\main.ts screenshot --json --session demo --profile managed-local $targetId
-```
-
-### 路径 B：控制你当前正在使用的 Edge/Chrome（扩展 relay）
-
-1. 先把 daemon 切到扩展 relay 模式：
+2. 用扩展 relay 模式启动 daemon：
 
 ```powershell
 $env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
 $env:BROWSERD_CHROME_RELAY_MODE = "extension"
 $env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
 $env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-```
-
-2. 打开 `edge://extensions` 或 `chrome://extensions`，开启“开发人员模式”，加载已解压扩展目录 `extensions/chrome-relay`。
-3. 打开扩展弹窗，把 `Bridge URL` 设为 `ws://127.0.0.1:9223/bridge`，并填写相同 token（`relay-secret`），点击 Save，再点 Reconnect。
-4. 用下面命令确认连接：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-```
-
-期望信号：`status.data.status.connected = true`。
-
-### 快速故障检查
-
-命令失败时，先跑：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
+browserctl daemon-stop --json
+browserctl daemon-start --json
 ```
 
-如果 relay 状态仍是 `connected: false`，回到扩展弹窗再点一次 Reconnect。
-
-## 扩展阅读/控制接口
+3. 加载扩展：
 
-CLI 已增加以下浏览器阅读/控制命令：
-
-```text
-dom-query <targetId> <selector>
-dom-query-all <targetId> <selector>
-element-screenshot <targetId> <selector>
-a11y-snapshot <targetId> [selector]
-network-wait-for <targetId> <urlPattern> [--method <METHOD>] [--status <CODE>] [--timeout-ms <ms>] [--poll-ms <ms>]
-cookie-get <targetId> [name]
-cookie-set <targetId> <name> <value> [url]
-cookie-clear <targetId> [name]
-storage-get <targetId> <local|session> <key>
-storage-set <targetId> <local|session> <key> <value>
-frame-list <targetId>
-frame-snapshot <targetId> <frameId>
-```
+1. 打开 `edge://extensions` 或 `chrome://extensions`。
+2. 开启开发者模式。
+3. 选择“加载已解压的扩展程序”，目录为 `extensions/chrome-relay`。
+4. 在扩展弹窗中设置：
+- `Bridge URL`: `ws://127.0.0.1:9223/bridge`
+- `Token`: `relay-secret`
+5. 点击 `Save`，再点击 `Reconnect`。
 
-示例：
+4. 连接验证与首个命令：
 
 ```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts dom-query --json --session demo $targetId "article h1"
-pnpm exec tsx .\apps\browserctl\src\main.ts element-screenshot --json --session demo $targetId "#main"
-pnpm exec tsx .\apps\browserctl\src\main.ts network-wait-for --json --session demo $targetId "/api/items" --method GET --status 200 --timeout-ms 15000
-pnpm exec tsx .\apps\browserctl\src\main.ts cookie-get --json --session demo $targetId
-pnpm exec tsx .\apps\browserctl\src\main.ts storage-set --json --session demo $targetId local theme dark
-pnpm exec tsx .\apps\browserctl\src\main.ts frame-list --json --session demo $targetId
-```
-
-## 全局命令模型
-
-语法：
-
-```text
-browserctl [--json] <command> [command-options] [positionals]
-```
-
-由命令上下文处理的全局参数：
-
-- `--session <id>`：会话命名空间，默认 `cli:local`
-- `--profile <driverKey>`：驱动键覆盖（`managed`、`managed-local`、`chrome-relay`、`remote-cdp`）
-- `--token <authToken>`：认证 token 覆盖
-- `--browser <preset>`：启动浏览器预设（`chromium`、`chrome`、`edge`）
-
-说明：
-
-- `--json` 会被全局消费并控制输出信封格式。
-- 未知 flag 不做严格选项 schema 校验，可能被当作位置参数。
-- `--browser` 仅影响 daemon 启动。若 daemon 已运行，不会热更新现有进程。
-
-## 核心概念
-
-## 会话命名空间（`--session`）
-
-会话命名空间就是 daemon 会话存储中的 `sessionId`。
-
-1. daemon 会按 session 维护状态，例如当前 `profile`（驱动键）和当前 `targetId`。
-2. 默认值是 `cli:local`，可通过 `--session <id>` 覆盖。
-3. 不同 session ID 会隔离控制上下文，互不覆盖。
-4. 这是上下文隔离，不是安全隔离。
-5. 会话状态在内存中，daemon 重启后会清空。
-
-## 认证 token（`--token`、`BROWSERD_AUTH_TOKEN`）
-
-认证 token 是用于请求鉴权的共享密钥字符串。
-
-1. daemon 设置 `BROWSERD_AUTH_TOKEN` 后，每次工具调用都必须带匹配的 `authToken`。
-2. CLI 会从 `--token` 或 `BROWSERCTL_AUTH_TOKEN` 转发 token。
-3. 缺失或不匹配会返回 `E_PERMISSION: Invalid auth token.`。
-4. token 负责“鉴权”；可执行范围由 `BROWSERD_AUTH_SCOPES` 单独限制。
-
-## 浏览器预设（`--browser`）
-
-浏览器预设用于控制 managed-local 启动时的 channel 选择。
-
-1. `chromium`：`browserName=chromium`，不覆盖 channel。
-2. `chrome`：`browserName=chromium`，`channel=chrome`。
-3. `edge`：`browserName=chromium`，`channel=msedge`。
-4. 预设不影响 `chrome-relay` 和 `remote-cdp`。
-5. 预设只在 daemon 启动时生效；daemon 已运行时需重启 daemon 才会切换。
-
-## 退出码与输出
-
-退出码：
-
-- `0`：成功
-- `1`：命令执行错误
-- `2`：参数错误或未知命令
-
-成功信封（`--json`）：
-
-```json
-{
-  "ok": true,
-  "command": "status",
-  "data": {
-    "kind": "browserd",
-    "ready": true
-  }
-}
+browserctl status --json --session relay --profile chrome-relay
+browserctl tab-open --json --session relay --profile chrome-relay https://example.com
 ```
 
-失败信封（`--json`，写到 stderr）：
-
-```json
-{
-  "ok": false,
-  "error": {
-    "message": "E_PERMISSION: Invalid auth token.",
-    "exitCode": 1
-  }
-}
-```
-
-## 环境变量
-
-### CLI（`browserctl`）
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `BROWSERCTL_DAEMON_PORT` | `41337` | daemon 请求使用的 TCP 端口。 |
-| `BROWSERCTL_DAEMON_STARTUP_TIMEOUT_MS` | `10000` | daemon 就绪最长等待时间。 |
-| `BROWSERCTL_DAEMON_REQUEST_TIMEOUT_MS` | `5000` | 单次请求 socket 超时。 |
-| `BROWSERCTL_BROWSER` | 未设置 | daemon 启动时的默认浏览器预设（`chromium`、`chrome`、`edge`）。 |
-| `BROWSERCTL_AUTH_TOKEN` | 未设置 | 请求默认认证 token。 |
-
-优先级：
-
-- token：`--token` > `BROWSERCTL_AUTH_TOKEN`
-- browser preset：`--browser` > `BROWSERCTL_BROWSER`
-
-### Daemon（`browserd`）
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `BROWSERD_TRANSPORT` | `stdio` | CLI 拉起 daemon 时会使用 `tcp`。 |
-| `BROWSERD_STDIO_PROTOCOL` | `mcp` | `legacy` 表示 JSON-line 兼容模式。 |
-| `BROWSERD_HOST` | `127.0.0.1` | transport=tcp 时的监听 host。 |
-| `BROWSERD_PORT` | `41337` | transport=tcp 时的监听端口。 |
-| `BROWSERD_DEFAULT_DRIVER` | 启用 managed-local 时为 `managed-local`，否则为 `managed` | 若不可用会回退到 `managed`。 |
-| `BROWSERD_MANAGED_LOCAL_ENABLED` | `true` | 设为 false 可取消注册 `managed-local`。 |
-| `BROWSERD_MANAGED_LOCAL_BROWSER` | `chromium` | `chromium`、`firefox`、`webkit`。 |
-| `BROWSERD_MANAGED_LOCAL_HEADLESS` | `true` | 支持 `1/0`、`true/false`、`yes/no`、`on/off`。 |
-| `BROWSERD_MANAGED_LOCAL_CHANNEL` | 未设置 | 可选 channel 覆盖。 |
-| `BROWSERD_MANAGED_LOCAL_EXECUTABLE_PATH` | 未设置 | 可选可执行文件路径。 |
-| `BROWSERD_MANAGED_LOCAL_LAUNCH_TIMEOUT_MS` | 未设置 | 非负整数。 |
-| `BROWSERD_MANAGED_LOCAL_ARGS` | 未设置（`[]`） | 逗号分隔启动参数。 |
-| `BROWSERD_CHROME_RELAY_URL` | `http://127.0.0.1:9223` | `chrome-relay` 端点。 |
-| `BROWSERD_CHROME_RELAY_MODE` | `cdp` | `chrome-relay` 模式：`cdp` 或 `extension`。 |
-| `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN` | 未设置 | 当 `BROWSERD_CHROME_RELAY_MODE=extension` 时必填。 |
-| `BROWSERD_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS` | `5000` | 扩展 bridge RPC 超时（毫秒）。 |
-| `BROWSERD_REMOTE_CDP_URL` | `http://127.0.0.1:9222/devtools/browser/default` | `remote-cdp` 端点。 |
-| `BROWSERD_AUTH_TOKEN` | 未设置 | 当 `BROWSERD_TRANSPORT=tcp` 时必填；设置后每个工具调用都必须提供匹配的 `authToken`。 |
-| `BROWSERD_AUTH_SCOPES` | `read,act,upload,download` | 允许的作用域。 |
-| `BROWSERD_UPLOAD_ROOT` | 未设置 | 上传路径白名单根目录。 |
-| `BROWSERD_DOWNLOAD_ROOT` | 未设置 | 下载路径白名单根目录。 |
-
-## 运行默认值与驱动说明
-
-默认运行行为：
-
-- 默认启用并选择 `managed-local` 作为默认驱动。
-- `managed`、`chrome-relay`、`remote-cdp` 始终注册。
-- `BROWSERD_DEFAULT_DRIVER` 可强制默认驱动键。
-- 若配置的默认驱动不可用，会回退到 `managed`。
-- 默认远端端点：
-  - `BROWSERD_CHROME_RELAY_URL=http://127.0.0.1:9223`
-  - `BROWSERD_REMOTE_CDP_URL=http://127.0.0.1:9222/devtools/browser/default`
-
-`managed-local` 说明：
-
-- 浏览器懒启动（首次需要浏览器上下文时）。
-- 可选启动控制：
-  - `BROWSERD_MANAGED_LOCAL_BROWSER`（`chromium|firefox|webkit`，默认 `chromium`）
-  - `BROWSERD_MANAGED_LOCAL_HEADLESS`（默认 `true`）
-  - `BROWSERD_MANAGED_LOCAL_CHANNEL`
-  - `BROWSERD_MANAGED_LOCAL_EXECUTABLE_PATH`
-  - `BROWSERD_MANAGED_LOCAL_LAUNCH_TIMEOUT_MS`
-  - `BROWSERD_MANAGED_LOCAL_ARGS`（逗号分隔）
-
-`chrome-relay` 说明：
-
-- 使用 `BROWSERD_CHROME_RELAY_URL`（默认 `http://127.0.0.1:9223`）。
-- 默认模式是 `BROWSERD_CHROME_RELAY_MODE=cdp`，支持 `ws(s)` 或 `http(s)` URL。
-- 当为 `http(s)` 时，运行时会尝试 `/json/version` 并优先使用 `webSocketDebuggerUrl`。
-- `BROWSERD_CHROME_RELAY_MODE=extension` 会在 `BROWSERD_CHROME_RELAY_URL` 启动本地扩展 bridge。
-- 扩展模式下，请把 `extensions/chrome-relay` 以“加载已解压的扩展程序”方式安装，并在弹窗里设置 Bridge URL（默认 `ws://127.0.0.1:9223/bridge`）。
-- 扩展模式必须设置 `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN`，并在扩展弹窗配置同一个 token。
-- 扩展模式已支持通过 bridge 回传 console 与 network 遥测（可用时包含 response body）。
-- 在 `--profile chrome-relay` 下发生连接错误时，CLI 会附加引导排查信息。
-
-示例：
+## 30 秒排查
 
 ```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session cli:relay --profile chrome-relay
-```
-
-`remote-cdp` 说明：
-
-- 使用 `BROWSERD_REMOTE_CDP_URL`（默认 `http://127.0.0.1:9222/devtools/browser/default`）。
-- 直接通过 CDP 连接到配置 URL。
-
-示例：
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "remote-cdp"
-$env:BROWSERD_REMOTE_CDP_URL = "http://127.0.0.1:9222/devtools/browser/default"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session cli:remote --profile remote-cdp
-```
-
-## 驱动模式与使用方式
-
-驱动对比：
-
-| 驱动 | 本质 | 适用场景 | 前置要求 | 常见状态字段 |
-| --- | --- | --- | --- | --- |
-| `managed` | 内存中的托管 stub 驱动 | 合同测试、确定性本地校验 | 无 | `status.kind = managed` |
-| `managed-local` | Playwright 启动的本地真实浏览器 | 默认本地自动化 | 本地浏览器运行时；可选 channel/executable 配置 | `status.kind = managed-local` |
-| `chrome-relay` | 通过 relay 端点（`ws/http`）连接 CDP | attach 工作流、扩展 relay 工作流 | 可访问的 relay 端点（`BROWSERD_CHROME_RELAY_URL`） | `status.kind = chrome-relay` |
-| `remote-cdp` | 直接连接远端/本地浏览器 CDP 端点 | 已有浏览器/CDP 基础设施 | 可访问的 CDP 端点（`BROWSERD_REMOTE_CDP_URL`） | `status.kind = remote-cdp` |
-
-如何选择驱动：
-
-1. 单次命令：传 `--profile <driverKey>`。
-2. 会话级别：`profile-use <driverKey> --session <id>`。
-3. daemon 默认值：设置 `BROWSERD_DEFAULT_DRIVER`。
-
-### 使用 `managed`（stub）
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "managed"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo --profile managed https://example.com
-```
-
-### 使用 `managed-local`（本地真实浏览器）
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "managed-local"
-$env:BROWSERD_MANAGED_LOCAL_HEADLESS = "false"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-```
-
-### 使用 `chrome-relay`
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session relay --profile chrome-relay https://example.com
-```
-
-如果连接失败，CLI 会附加 relay 引导信息（扩展激活、端点检查、URL 检查）。
-
-扩展模式示例：
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "chrome-relay"
-$env:BROWSERD_CHROME_RELAY_MODE = "extension"
-$env:BROWSERD_CHROME_RELAY_URL = "http://127.0.0.1:9223"
-$env:BROWSERD_CHROME_RELAY_EXTENSION_TOKEN = "relay-secret"
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session relay --profile chrome-relay
-```
-
-扩展安装（Chrome/Edge）：
-
-1. 打开 `chrome://extensions` 或 `edge://extensions`。
-2. 打开开发者模式。
-3. 点击“加载已解压的扩展程序”，选择 `extensions/chrome-relay`。
-4. 打开扩展弹窗，填写 Bridge URL 与同一个 token，然后点击 Save/Reconnect。
-
-### 使用 `remote-cdp`
-
-```powershell
-$env:BROWSERD_DEFAULT_DRIVER = "remote-cdp"
-$env:BROWSERD_REMOTE_CDP_URL = "http://127.0.0.1:9222/devtools/browser/default"
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session remote --profile remote-cdp
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session remote --profile remote-cdp https://example.com
-```
-
-推荐切换模式：
-
-1. 每个驱动使用独立 session（如 `session:local`、`session:relay`、`session:remote`）。
-2. 自动化脚本里优先显式传 `--profile`，避免 session 历史状态产生隐式切换。
-
-## 认证与路径约束
-
-- `BROWSERD_TRANSPORT=tcp` 必须设置 `BROWSERD_AUTH_TOKEN`。
-- 若设置 `BROWSERD_AUTH_TOKEN`，每个工具调用都必须提供匹配的 `authToken`。
-- `BROWSERD_AUTH_SCOPES` 是 `read`、`act`、`upload`、`download` 的逗号分隔白名单。
-- 未设置 `BROWSERD_UPLOAD_ROOT` 时，`browser.upload.arm` 会被拒绝。
-- 未设置 `BROWSERD_DOWNLOAD_ROOT` 时，`browser.download.wait` 会被拒绝。
-- `BROWSERD_UPLOAD_ROOT` 将 `upload-arm` 文件路径限制在该根目录下。
-- `BROWSERD_DOWNLOAD_ROOT` 将 `download-wait` 输出路径限制在该根目录下。
-- `download-wait` 支持可选位置参数 `path`。
-- 若设置了 `BROWSERD_DOWNLOAD_ROOT`，且请求路径与驱动返回路径都不存在，`download-wait` 会返回内部错误。
-
-## 驱动与会话行为
-
-已注册驱动：
-
-- `managed`
-- `managed-local`（除非被禁用）
-- `chrome-relay`
-- `remote-cdp`
-
-会话存储行为：
-
-1. 传入 `--profile` 会覆盖本次调用驱动，并更新 session profile。
-2. 不传 `--profile` 时，daemon 先看 session profile，再回退默认驱动。
-3. `tab-open` 会把 session target 更新为新开目标。
-
-## Edge 与浏览器预设
-
-`--browser` 或 `BROWSERCTL_BROWSER` 的映射：
-
-- `edge` -> `chromium + channel=msedge`
-- `chrome` -> `chromium + channel=chrome`
-- `chromium` -> `chromium`（不覆盖 channel）
-
-示例：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json
-```
-
-## 命令参考（含 JSON 示例）
-
-下面所有示例都使用：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts
-```
-
-## `daemon-start`
-
-用途：确保 daemon 运行；若未运行则启动。
-
-语法：
-
-```text
-daemon-start [--json] [--token <authToken>] [--browser <chromium|chrome|edge>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-start --json --browser edge
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "daemon-start",
-  "data": {
-    "running": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `daemon-status`
-
-用途：检查 daemon 是否可达。
-
-语法：
-
-```text
-daemon-status [--json] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-status --json
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "daemon-status",
-  "data": {
-    "running": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `daemon-stop`
-
-用途：基于 PID 文件停止 daemon。
-
-语法：
-
-```text
-daemon-stop [--json]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts daemon-stop --json
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "daemon-stop",
-  "data": {
-    "stopped": true,
-    "port": 41337,
-    "pid": 24680
-  }
-}
-```
-
-## `status`
-
-用途：获取 browserd 状态和当前驱动状态。
-
-语法：
-
-```text
-status [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts status --json --session demo --profile managed-local
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "status",
-  "data": {
-    "kind": "browserd",
-    "ready": true,
-    "driver": "managed-local",
-    "drivers": [
-      "chrome-relay",
-      "managed",
-      "managed-local",
-      "remote-cdp"
-    ],
-    "status": {
-      "kind": "managed-local",
-      "connected": false,
-      "launched": false,
-      "browserName": "chromium",
-      "headless": true
-    }
-  }
-}
-```
-
-## `tabs`
-
-用途：列出当前驱动/上下文下的 target ID 列表。
-
-语法：
-
-```text
-tabs [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tabs --json --session demo
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "tabs",
-  "data": {
-    "driver": "managed-local",
-    "tabs": [
-      "target:managed-local:profile:managed-local:default:1"
-    ]
-  }
-}
-```
-
-## `profile-list`
-
-用途：列出当前驱动可见 profile 列表。
-
-语法：
-
-```text
-profile-list [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts profile-list --json --profile managed-local
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "profile-list",
-  "data": {
-    "driver": "managed-local",
-    "profiles": [
-      "profile:managed-local:default"
-    ]
-  }
-}
-```
-
-## `profile-use`
-
-用途：把 session 绑定到某个驱动键。
-
-语法：
-
-```text
-profile-use <driverKey> [--json] [--session <id>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts profile-use --json --session demo chrome-relay
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "profile-use",
-  "data": {
-    "profile": "chrome-relay"
-  }
-}
-```
-
-## `tab-open`
-
-用途：新建标签页并导航到 URL。
-
-语法：
-
-```text
-tab-open <url> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-open --json --session demo https://example.com
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "tab-open",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2"
-  }
-}
-```
-
-## `tab-focus`
-
-用途：聚焦已有目标页。
-
-语法：
-
-```text
-tab-focus <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-focus --json --session demo target:managed-local:profile:managed-local:default:2
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "tab-focus",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2",
-    "focused": true
-  }
-}
-```
-
-## `tab-close`
-
-用途：关闭已有目标页。
-
-语法：
-
-```text
-tab-close <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts tab-close --json --session demo target:managed-local:profile:managed-local:default:2
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "tab-close",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:2",
-    "closed": true
-  }
-}
-```
-
-## `snapshot`
-
-用途：抓取目标页快照（可包含 URL/标题/HTML/请求摘要）。
-
-语法：
-
-```text
-snapshot <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts snapshot --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "snapshot",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "snapshot": {
-      "kind": "managed-local",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "hasTarget": true,
-      "url": "https://example.com/",
-      "title": "Example Domain",
-      "html": "<!doctype html>...",
-      "requestSummaries": []
-    }
-  }
-}
-```
-
-## `screenshot`
-
-用途：抓取目标页截图（PNG base64 载荷）。
-
-语法：
-
-```text
-screenshot <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts screenshot --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "screenshot",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "screenshot": {
-      "kind": "managed-local",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "hasTarget": true,
-      "mimeType": "image/png",
-      "encoding": "base64",
-      "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
-    }
-  }
-}
-```
-
-## `act`
-
-用途：按动作类型对目标页执行操作。
-
-语法：
-
-```text
-act <actionType> <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-当前 CLI 的关键行为：
-
-- CLI 只发送 `action.type`。
-- 不发送 `action.payload`。
-- 需要 payload 的动作可能在 `data.result` 中返回 `ok: false`。
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts act --json --session demo click target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "act",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "result": {
-      "actionType": "click",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "targetKnown": true,
-      "ok": false,
-      "executed": false,
-      "error": "action.payload.selector is required for click action."
-    }
-  }
-}
-```
-
-## `upload-arm`
-
-用途：为目标页预置上传文件。
-
-语法：
-
-```text
-upload-arm <targetId> <file1> [file2 ...] [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts upload-arm --json --session demo target:managed-local:profile:managed-local:default:1 .\fixtures\a.txt .\fixtures\b.txt
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "upload-arm",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "armed": true,
-    "files": [
-      "C:\\repo\\fixtures\\a.txt",
-      "C:\\repo\\fixtures\\b.txt"
-    ]
-  }
-}
-```
-
-## `dialog-arm`
-
-用途：为目标页预置对话框处理。
-
-语法：
-
-```text
-dialog-arm <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts dialog-arm --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "dialog-arm",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "armed": true
-  }
-}
-```
-
-## `download-trigger`
-
-用途：触发目标页下载流程。
-
-语法：
-
-```text
-download-trigger <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts download-trigger --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "download-trigger",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "triggered": true
-  }
-}
-```
-
-## `download-wait`
-
-用途：等待并返回下载元数据。
-
-语法：
-
-```text
-download-wait <targetId> [path] [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts download-wait --json --session demo target:managed-local:profile:managed-local:default:1 .\downloads\artifact.bin
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "download-wait",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "download": {
-      "path": "C:\\repo\\downloads\\artifact.bin",
-      "profile": "profile:managed-local:default",
-      "targetId": "target:managed-local:profile:managed-local:default:1",
-      "uploadFiles": [
-        "C:\\repo\\fixtures\\a.txt"
-      ],
-      "dialogArmedCount": 1,
-      "triggerCount": 1
-    }
-  }
-}
-```
-
-## `console-list`
-
-用途：读取目标页控制台遥测条目。
-
-语法：
-
-```text
-console-list <targetId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts console-list --json --session demo target:managed-local:profile:managed-local:default:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "console-list",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "entries": [
-      {
-        "type": "warning",
-        "text": "Example warning",
-        "timestamp": "2026-02-23T10:00:00.000Z",
-        "location": {
-          "url": "https://example.com",
-          "lineNumber": 12,
-          "columnNumber": 4
-        }
-      }
-    ]
-  }
-}
-```
-
-## `response-body`
-
-用途：按 request ID 读取已捕获的网络响应体。
-
-语法：
-
-```text
-response-body <targetId> <requestId> [--json] [--session <id>] [--profile <driverKey>] [--token <authToken>]
-```
-
-示例命令：
-
-```powershell
-pnpm exec tsx .\apps\browserctl\src\main.ts response-body --json --session demo target:managed-local:profile:managed-local:default:1 request:managed-local:profile%3Amanaged-local%3Adefault:target%3Amanaged-local%3Aprofile%3Amanaged-local%3Adefault%3A1:1
-```
-
-示例 JSON 输出：
-
-```json
-{
-  "ok": true,
-  "command": "response-body",
-  "data": {
-    "driver": "managed-local",
-    "targetId": "target:managed-local:profile:managed-local:default:1",
-    "requestId": "request:managed-local:profile%3Amanaged-local%3Adefault:target%3Amanaged-local%3Aprofile%3Amanaged-local%3Adefault%3A1:1",
-    "body": "{\"ok\":true}",
-    "encoding": "utf8"
-  }
-}
+browserctl daemon-status --json
+Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9223/browserctl/relay/status" -TimeoutSec 3
 ```
 
-## Relay 故障排查
-
-当 relay 配置下出现连接类错误（`ECONNREFUSED`、超时、`ENOTFOUND` 等）时，CLI 会附加引导：
-
-1. 扩展 relay 方案请先设置 `BROWSERD_CHROME_RELAY_MODE=extension`。
-2. 从 `extensions/chrome-relay` 加载扩展并保持激活。
-3. 确认扩展弹窗 Bridge URL 与 `BROWSERD_CHROME_RELAY_URL` 一致（`ws://<host>:<port>/bridge`）。
-4. CDP relay 方案请确认浏览器远程调试端点已启动。
-5. 确认 `BROWSERD_CHROME_RELAY_URL` 配置正确。
+若 `connected` 为 `false`，重新打开扩展弹窗并点击 `Reconnect`。
 
-## 示例负载准确性说明
-
-- 以上 JSON 示例与当前命令/返回结构一致，用于代表典型返回。
-- 实际运行值会受驱动、浏览器状态和环境策略影响。
-- `snapshot.html`、`screenshot.imageBase64` 与遥测字段可能很大，示例中做了省略。
-
-## Smoke 流程
-
-运行 smoke 流程：
-
-```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\smoke.ps1
-```
+## 完整文档
 
-Smoke 流程行为：
+- [Full User Guide (English)](docs/user-guide.md)
+- [完整使用文档（中文）](docs/user-guide-cn.md)
+- [Chrome Relay Extension README (English)](extensions/chrome-relay/README.md)
+- [Chrome Relay 扩展文档（中文）](extensions/chrome-relay/README-CN.md)
 
-1. 启动 `browserd`。
-2. 执行 `browserctl status --json`。
-3. 等待 daemon 通过 TCP 可达。
-4. 若响应包含错误或 `ok` 为 `false` 则失败。