@xnng/browser-relay 1.6.0

package/docs/README.zh-CN.md

@@ -0,0 +1,421 @@
+> 本包是 [reliefeai/browser-relay](https://github.com/reliefeai/browser-relay) 的 xnng 维护分支，以 `@xnng/browser-relay` 发布，增加任务分组及收起分组的后台操作修复，保留上游 MIT 许可。
+
+<p align="center">
+  <img src="../extension/icons/icon128.png" width="96" height="96" alt="Browser Relay logo">
+</p>
+
+<h1 align="center">Browser Relay</h1>
+
+<p align="center">
+  让 AI Agent 和你共用同一个 Chrome 浏览器。
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Agent-Skill%20%2B%20CLI-blue" alt="Agent Skill 与 CLI">
+  <img src="https://img.shields.io/badge/远程-多机器控制-7c3aed" alt="远程多机器控制">
+  <img src="https://img.shields.io/badge/开源-MIT-green" alt="MIT 开源">
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a>
+  ·
+  <a href="#快速开始">快速开始</a>
+  ·
+  <a href="#agent-友好">Agent Skill</a>
+  ·
+  <a href="#cli">CLI</a>
+  ·
+  <a href="#远程控制remote-relay">远程</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/reliefeai/browser-relay/blob/main/docs/assets/browser-relay-mobile-to-office.mp4">
+    <img src="https://raw.githubusercontent.com/reliefeai/browser-relay/main/docs/assets/browser-relay-mobile-to-office.gif" width="960" alt="Browser Relay 示意流程：手机上的 Agent 通过 Skill 和 CLI 操作办公室电脑现有 Chrome 中的 mock 内网页面">
+  </a>
+</p>
+
+<p align="center"><sub>示意流程使用 mock 数据，不含真实凭据。点击动画可查看 MP4 版本。</sub></p>
+
+Browser Relay 通过面向 Agent 的 **Skill + CLI**，让 AI Agent 加入你每天正在使用的 Chrome。它不会创建空白的自动化浏览器，不需要反复把另一个浏览器窗口拉到前台，也不用重新登录。你和 Agent 共用同一个日常浏览器——既可以在本机，也可以跨多台机器。
+
+它特别适合这些任务：人在外面用手机上的 Agent 操作电脑浏览器；在家里让 Agent 使用公司电脑上已有内网、SSO 和设备信任的 Chrome；或者让一个 Agent 根据登录态和网络环境，在多台机器的浏览器之间工作。
+
+## 真实 Chrome,而非临时配置
+
+大多数浏览器自动化会开一个全新的空白浏览器配置。这适合测试,但对需要操作你**已登录**的 Web 应用的 Agent 毫无用处 —— SaaS 后台、管理面板、内网工具、文档、私有会话,这些页面在无头浏览器或全新配置里根本没有登录态。
+
+Browser Relay 补的就是这一层(也是很多人在找的 OpenClaw Browser Relay 替代方案):
+
+- **就是你自己的 Chrome 会话** —— Cookie、localStorage、扩展、登录状态,原样共用。
+- **不弹自动化浏览器** —— 不开额外窗口、不在背后建标签;普通导航复用已附加的标签页。
+- **本地或远程** —— 一个 Agent 可以操作本机或多台远程机器上的浏览器；浏览器通过出站连接接入，不暴露公网浏览器端口。
+- **面向 Agent** —— 安装自带 Skill 后，Claude Code、Codex、Cursor、Windsurf 等 Agent 会知道何时、如何调用可检查的 CLI。
+- **本地优先边界** —— 默认只监听 `127.0.0.1`。
+
+## 来源说明
+
+源代码整理自 [chengyixu/openclaw-browser-relay](https://github.com/chengyixu/openclaw-browser-relay),自动附加标签页的逻辑参考了 [blakesabatinelli/openclaw-chrome-relay](https://github.com/blakesabatinelli/openclaw-chrome-relay)。移除了 OpenClaw 专属的网关握手、token 鉴权和平台绑定,整理为通用的本地浏览器桥。
+
+## 工作方式
+
+```text
+本地
+  AI Agent ──Skill + CLI──▶ Relay 服务器 (Node, 127.0.0.1)
+                                        │ WebSocket
+                                        ▼
+                                 Chrome 扩展 ──chrome.debugger / CDP──▶ 你的 Chrome 标签页
+
+远程（Remote Relay）
+  AI Agent ──HTTPS──▶ 公网 Relay 服务 (relay.linso.ai) ◀──WSS── Chrome 扩展 ──▶ 你的 Chrome 标签页
+```
+
+**本地模式**是默认:Agent 连本机 `127.0.0.1` 上的 relay 服务器,由它把 Chrome DevTools Protocol 命令转发给扩展。
+
+**远程模式**不暴露任何东西。打开 Remote Relay 后,扩展会主动**出站**连到公网 Relay 服务;远程的 CLI 连到同一个服务,由它顺着这条已有连接把每条命令下发到你的浏览器 —— 没有开放端口,网络上也没有本地服务。命令由扩展用 `chrome.debugger` 自己执行,所以远程控制不依赖本地 relay。可以用默认的托管服务,也可以一键部署到 Cloudflare 自建(见下文)。
+
+## 快速开始
+
+使用分四步。需要桌面版 Chrome 和 Node.js/npm；Chrome 扩展需要从安装目录手动加载。
+
+### 1. 安装
+
+```bash
+npm install -g @xnng/browser-relay
+```
+
+安装程序会尝试注册用户级后台服务。如果当前环境没有可用的服务管理器，下面的验证步骤会给出明确的前台启动命令，而不是抛出堆栈。
+
+### 2. 安装 Chrome 扩展
+
+先获取扩展目录:
+
+```bash
+browser-relay path
+```
+
+然后打开 `chrome://extensions`,打开右上角开发者模式,点击 `Load unpacked`,选择 `browser-relay path` 输出的 `extension` 目录。
+
+### 3. 验证浏览器连接
+
+先运行一次完整的只读诊断，再列出已连接标签页：
+
+```bash
+browser-relay doctor
+browser-relay tabs
+```
+
+`doctor` 应显示 relay 健康且扩展已连接；`tabs` 应至少输出一条标签页 ID、标题和 URL：
+
+```text
+t_A7k2Pm9QxL    Example Domain    https://example.com/
+```
+
+如果 `doctor` 提示服务管理器不可用，请在另一个终端以前台方式启动并保持运行：
+
+```bash
+browser-relay
+```
+
+然后重试 `browser-relay doctor`。如果 relay 已健康但仍没有标签页，重新加载 unpacked 扩展，再运行 `browser-relay tabs`。`doctor` 不会安装、重启或改动任何内容；自动化场景可加 `--json`。
+
+<details>
+<summary>后台服务、升级与平台说明</summary>
+
+全局安装在 macOS 使用 launchd、Linux 使用 systemd-user、Windows 使用当前用户的任务计划程序，登录后自动启动。Windows 任务只复用当前已登录用户的交互令牌并以最低权限运行，不保存密码、不主动提权，也不使用 SYSTEM；公司设备策略仍可能禁止标准用户注册任务。
+
+`browser-relay install` 会安全刷新带 Browser Relay 所有权标记的服务定义、启动服务并校验 HTTP 与版本。nvm 升级或 `doctor` 建议时再运行即可；它拒绝覆盖同名但不属于 Browser Relay 的 Windows 任务。若受管环境没有可用服务管理器，仍可用 `browser-relay` 前台运行。
+
+升级使用 `browser-relay update`：它会全局安装 `@xnng/browser-relay@latest`、尝试刷新服务并输出状态检查；扩展会在下一次 relay 重连时自动重载（约 30 秒内）。
+
+</details>
+
+### 4. 安装 Agent Skill 并完成第一个任务
+
+Browser Relay 自带 Agent Skill。显式选择目标 Agent，安装过程就不会弹出交互式选择器：
+
+```bash
+browser-relay skill install --agent codex
+
+# Claude Code，或一次安装给两者：
+browser-relay skill install --agent claude-code
+browser-relay skill install --agent codex claude-code
+```
+
+命令会以无交互模式调用标准 `skills` CLI，并逐个读取目标 `SKILL.md` 做内容校验。使用标准 `~/.agents/skills` 目录的 Agent 可传 `--agent universal`；用 `browser-relay skill path` 查看包内 Skill 目录；无参数的 `browser-relay skill` 默认输出安装到所有 Agent 的命令（`--agent "*"`），只打印提示，不执行安装。安装后 Agent 就能操作你自己的浏览器，而不用另开自动化浏览器。
+
+第一次先给 Agent 一个只读的小任务：
+
+```text
+使用 Browser Relay 告诉我当前 Chrome 标签页的标题和 URL，不要导航。
+```
+
+Agent 能正确回答，就证明整条链路已经打通：Agent Skill → CLI → relay → 扩展 → 你正在使用的 Chrome 标签页。
+
+如果 Browser Relay 确实解决了你的工作流，给仓库一个 Star 可以帮助其他 Agent 开发者发现它。
+
+## Agent 友好
+
+Browser Relay 专门为 Agent 工作流做了设计,不只是给底层脚本用:
+
+- 自带 Skill,告诉 Agent 何时用 Browser Relay 以及如何安全交互。
+- 页面快照会标注链接、按钮、输入框等交互元素,方便 Agent 先理解页面再行动。
+- 操作落在已附加的真实标签页上,让浏览器上下文保持可见、可预期。
+- 稳定 CSS 等待让 Agent 等元素进入 DOM 或变为可见，不再依赖猜测性的固定 sleep。
+- Console 和 Network 捕获会记录 `console.*`、页面异常、日志以及请求/响应,便于诊断真实页面行为。
+
+## CLI
+
+**1.5.0** 新增完整内容读取、标签会话归属与交接；
+详见[发布说明与升级步骤](releases/v1.5.0.md)、[实现与验收记录](browser-use-parity.md)。开发推送不自动发布 npm，发布须手动指定版本与渠道。
+
+1.5 还包括持久 JavaScript 会话、可访问性元素引用、差量快照和批量动作。
+先用 `browser-relay observe --tab <id>` 获取页面状态，再用
+`browser-relay actions --tab <id> --file actions.json` 一次执行已确定的步骤。
+动作在插件内连续运行，同一标签页串行，支持查看任务及取消后续动作。
+
+`browser-relay exec --file workflow.js` 可运行脚本；MCP 的 `browser_exec`
+会在多次调用间保留变量与标签句柄。MCP 截图直接返回图片。坐标点击、拖拽和悬停
+支持截图坐标映射；需要可见标签页的操作会明确返回 `needs_foreground`。
+插件弹窗提供“取消当前任务”。本地脚本是拥有 Agent 系统权限的可信代码，独立进程
+用于超时与重置，不是安全沙箱；远端浏览器只接收浏览器动作。
+
+参阅 [运行时与 SDK](../skills/browser-relay/references/runtime.md)、
+[Codex 能力对比和实测](browser-use-comparison.md)。
+
+CLI 是首选接口。能执行 shell 的 Agent 用它比手写 `curl` JSON 更快、更少转义:
+
+```bash
+browser-relay tabs
+browser-relay console --tab t_A7k2Pm9QxL --limit 50
+browser-relay network --tab t_A7k2Pm9QxL --type response --status 500
+browser-relay snapshot --tab t_A7k2Pm9QxL --max-length 20000
+browser-relay wait 'button[type=submit]' --state visible --timeout 10000 --tab t_A7k2Pm9QxL
+browser-relay click 'button[type=submit]' --tab t_A7k2Pm9QxL
+browser-relay type 'hello world' --selector 'input[name=q]' --clear --submit
+browser-relay key Control+L
+browser-relay scroll down --amount 1000
+browser-relay screenshot /tmp/page.png --full-page
+browser-relay eval 'document.title'
+```
+
+长文本或多行 JavaScript 从 stdin 读取,避免 shell 转义:
+
+```bash
+printf 'hello\nworld' | browser-relay type --selector textarea --stdin
+browser-relay eval --stdin < script.js
+```
+
+所有浏览器命令都支持 `--json`(输出原始 API 响应)和 `--tab <id>`(指定标签页)。用 `--json` 时失败命令会输出结构化错误 JSON 并以非 0 退出。
+
+### 远程控制（Remote Relay）
+
+要从**另一台机器**(CI、远程 agent、不同网络)控制这个浏览器,在扩展 Options 页面打开 **Remote Relay**。浏览器会主动连到公网 Relay 服务(默认是托管的 `relay.linso.ai`)——不开放任何公网端口,也不暴露本地服务。
+
+打开后会生成一个保密的 **Device ID**——请像密码一样保管,在任何地方传给同样的 CLI 命令即可:
+
+```bash
+browser-relay tabs --remote-device-id br-xxxx
+browser-relay eval "location.href" --remote-device-id br-xxxx
+
+# 存个别名,以后不用重复贴长 id(remote ls / rm 管理):
+browser-relay remote add mymac br-xxxx
+browser-relay tabs --remote mymac
+```
+
+保存的远程 Device ID 属于凭据。POSIX 系统会将其写入
+`~/.browser-relay/remotes.json`，并强制目录为 `0700`、文件为 `0600`；旧版本创建的宽权限也会在再次写入时自动收紧。
+`browser-relay remote ls`（包括 `--json`）只返回 `(redacted)`，不会输出保存的 capability 或其中任何字符。
+
+**自建你自己的 Relay 服务** —— 一键把 `hub/` 里的 Worker 部署到你自己的 Cloudflare 账号:
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/reliefeai/browser-relay/tree/main/hub)
+
+按钮第一次会让你把 Cloudflare 连上 GitHub(Workers Builds)。想用命令行?`git clone` 后 `cd hub && npx wrangler deploy`。两种方式都会给你一个 `…workers.dev` 地址,填到 Options 页面的 *公网 Relay 服务* 字段即可。
+
+`remote-device-id` 是一个 capability —— Remote Relay 开着时,拿到它的人就能控制这个浏览器。设计见 `docs/remote-control-hub.md`。
+
+### CLI 参考
+
+```bash
+browser-relay            # 前台运行 relay server
+browser-relay start      # 启动后台服务
+browser-relay stop       # 停止后台服务
+browser-relay restart    # 重启后台服务
+browser-relay fix        # 重启并清理失效会话（标签页连不上时用）
+browser-relay update     # 更新全局 npm 包并刷新后台服务
+browser-relay status     # 查看服务状态和 HTTP 健康检查
+browser-relay doctor     # 执行完整的只读安装诊断
+browser-relay logs       # 持续查看当前平台的服务日志
+browser-relay path       # 输出 Chrome 扩展目录
+browser-relay skill install --agent codex # 安装/更新并校验 Agent Skill
+browser-relay skill path                  # 输出包内 Skill 目录
+browser-relay install    # 注册后台服务
+browser-relay uninstall  # 卸载后台服务
+
+browser-relay tabs       # 列出已附加标签页
+browser-relay console    # 输出 console 和页面错误记录
+browser-relay network    # 输出网络请求、响应和失败事件
+browser-relay snapshot   # 输出页面结构化文本
+browser-relay wait       # 等待 CSS 元素进入 DOM 或变为可见
+browser-relay click      # 按 CSS selector 点击元素
+browser-relay type       # 输入文本
+browser-relay key        # 按键或快捷键
+browser-relay scroll     # 滚动页面
+browser-relay screenshot # 保存 PNG 截图
+browser-relay eval       # 在页面内执行 JavaScript
+browser-relay download   # 输出元素 src/href
+browser-relay download-start # 启动 Chrome 下载
+browser-relay downloads      # 列出 Chrome 下载和事件
+browser-relay remote     # 管理远程别名（add / ls / rm）
+browser-relay api-help   # 查看浏览器操作命令示例
+```
+
+## MCP
+
+安装 npm 包后直接用 `browser-relay-mcp`:
+
+```json
+{
+  "mcpServers": {
+    "browser": {
+      "command": "browser-relay-mcp",
+      "env": {
+        "BROWSER_RELAY_URL": "http://127.0.0.1:18795"
+      }
+    }
+  }
+}
+```
+
+MCP server 提供 `browser_tabs`、`browser_snapshot`、`browser_wait`、`browser_click`、`browser_type`、`browser_key`、`browser_screenshot` 等高层工具。
+
+## HTTP API
+
+HTTP API 是给代码和自定义工具集成用的稳定接口。交互式 Agent 操作优先用上面的 CLI。
+
+HTTP、CLI `--json` 和 MCP 工具错误都使用结构化错误格式:
+
+```json
+{ "ok": false, "code": "invalid_request", "error": "url is required", "message": "url is required", "status": 400, "retryable": false }
+```
+
+```bash
+curl http://127.0.0.1:18795/api/tabs
+curl "http://127.0.0.1:18795/api/snapshot?tabId=t_A7k2Pm9QxL"
+
+curl -X POST http://127.0.0.1:18795/api/wait \
+  -H "Content-Type: application/json" \
+  -d '{"tabId":"t_A7k2Pm9QxL","selector":"button.submit","state":"visible","timeoutMs":10000}'
+
+curl "http://127.0.0.1:18795/api/console?tabId=t_A7k2Pm9QxL&limit=50"
+curl "http://127.0.0.1:18795/api/network?tabId=t_A7k2Pm9QxL&type=response&status=500"
+
+curl -X POST http://127.0.0.1:18795/api/click \
+  -H "Content-Type: application/json" \
+  -d '{"tabId":"t_A7k2Pm9QxL","selector":"button.submit"}'
+```
+
+| Endpoint | Method | 说明 |
+| --- | --- | --- |
+| `/` | GET/HEAD | 健康检查 |
+| `/api/debug` | GET | 服务状态和诊断信息 |
+| `/api/tabs` | GET | 列出已附加标签页 |
+| `/api/console` | GET | 读取 console 和页面错误记录 |
+| `/api/console/clear` | POST | 清理 console 记录 |
+| `/api/network` | GET | 读取已捕获的 Network 请求、响应和失败事件（敏感 header 已脱敏） |
+| `/api/network/clear` | POST | 清理已捕获的网络事件 |
+| `/api/navigate` | POST | 导航已附加标签页 |
+| `/api/snapshot` | GET | 获取页面文本快照或 HTML |
+| `/api/wait` | POST | 等待 CSS 元素进入 DOM 或变为可见 |
+| `/api/click` | POST | 按 CSS selector 点击元素 |
+| `/api/type` | POST | 输入文本 |
+| `/api/key` | POST | 按键或键盘快捷键 |
+| `/api/scroll` | POST | 滚动页面 |
+| `/api/screenshot` | GET/POST | 获取 PNG 截图；full-page 会返回截图策略和尺寸元数据 |
+| `/api/eval` | POST | 执行页面内 JavaScript |
+| `/api/download` | POST | 获取元素 URL |
+| `/api/download/start` | POST | 从 URL 启动真实 Chrome 下载 |
+| `/api/downloads` | GET | 列出 Chrome 下载和最近下载事件 |
+| `/api/downloads/clear` | POST | 清理已捕获的下载事件 |
+
+真实 Chrome 下载需要扩展的 `downloads` 权限。从旧版本升级后,需在 `chrome://extensions` 里重新加载 unpacked 扩展。
+
+这些接口远程同样可用:带 `--remote-device-id` 的 CLI 会把它们经公网 Relay 服务发到浏览器。
+
+## 配置
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `BROWSER_RELAY_URL` | `http://127.0.0.1:18795` | CLI 浏览器命令和 MCP 使用的 relay 地址 |
+| `BROWSER_RELAY_HOST` | `127.0.0.1` | HTTP 和 WebSocket 监听地址 |
+| `BROWSER_RELAY_PORT` | `18795` | HTTP 和 WebSocket 端口 |
+| `BROWSER_RELAY_REMOTE_DEVICE_ID` | — | 未传 `--remote-device-id` 时使用的远程 Device ID(或别名) |
+| `BROWSER_RELAY_REMOTE_HOST` | `https://relay.linso.ai` | 远程命令使用的公网 Relay 服务地址 |
+
+Chrome 扩展端口可以在扩展 Options 页面修改。
+
+后台服务与日志位置：
+
+```text
+macOS 服务: ~/Library/LaunchAgents/org.browser-relay.service.plist
+Linux 服务: ~/.config/systemd/user/browser-relay.service
+Windows 任务: BrowserRelay
+Windows 定义: %LOCALAPPDATA%\BrowserRelay\task.xml
+
+macOS 日志: /tmp/browser-relay.log, /tmp/browser-relay.error.log
+Linux 日志: journalctl --user -u browser-relay
+Windows 日志: %LOCALAPPDATA%\BrowserRelay\logs\browser-relay.log
+              %LOCALAPPDATA%\BrowserRelay\logs\browser-relay.error.log
+```
+
+Windows 上，`uninstall` 只移除 Browser Relay 任务及生成的 XML 定义，诊断日志会保留；它也绝不会为了释放 `18795` 端口而结束不属于 Browser Relay 的进程。
+
+### 隐藏「已开始调试此浏览器」顶部提示
+
+只要扩展附加了 debugger,Chrome 就会在页面顶部强制显示一条
+`"Browser Relay" 已开始调试此浏览器` 的提示条。任何扩展 API 都无法去掉它 ——
+这是 Chrome 内置的防滥用安全提示。
+
+两种处理方式:
+
+- **自动(默认):** 扩展会在标签页闲置 10 分钟后 soft-detach,提示条在你不用时
+  自动消失,下一次命令再自动 re-attach。无需配置。
+- **彻底去掉:** 用 `--silent-debugger-extension-api` 参数启动 Chrome,它会抑制
+  debugger 扩展 API 的这条提示。必须先完全退出 Chrome(`open --args` 只在冷启动时
+  才会传入参数):
+
+  ```bash
+  # macOS
+  osascript -e 'quit app "Google Chrome"'
+  open -a "Google Chrome" --args --silent-debugger-extension-api
+  ```
+
+  想长期生效,就始终这样启动 Chrome(比如做个 shell 别名或 `.command` 启动器)——
+  直接点 Dock 图标不会带上这个参数。
+
+  代价:这会削弱一层安全防护 —— 之后**任何**拥有 `debugger` 权限的扩展都能静默
+  附加而不再提示。个人自用、清楚它关掉了什么的前提下可以接受。
+
+## 本地开发
+
+发布配置与手动触发方式见 [npm OIDC 发布流程](publishing.md)。
+
+```bash
+npm install
+npm start
+npm run mcp
+npm test
+```
+
+开发时在 `chrome://extensions` 中选择仓库里的 `extension/` 目录作为 unpacked extension。
+
+## 安全说明
+
+- Chrome 扩展使用 `debugger` 权限,只安装你信任的版本。
+- 默认只监听 `127.0.0.1`,不要把 relay server 暴露到公网。
+- Remote Relay 从不开放端口:浏览器主动出站连公网 Relay 服务,它只在内存里保存 Device ID 的哈希。Device ID 请像密码一样保管;Remote Relay 开着时,拿到它的人就能控制浏览器。
+- Browser Relay 会让 Agent 访问你的真实浏览器状态,因此启用的 Agent 应被视为可信本地软件。
+
+## License
+
+MIT