Add cross-border-ecommerce/hubstudio-bridge

2026-07-10 16:12:04 +08:00
parent ae94191795
commit f8996395ed
1 changed files with 479 additions and 0 deletions
@@ -0,0 +1,479 @@
 ---
 name: hubstudio-bridge
 description: "HubStudio 浏览器环境 AI 自动化 — 通过 Hermes + Desktop Bridge 操控 HubStudio 浏览器环境/云手机，自然语言驱动：列出环境、启动环境、获取调试端口、对接 Playwright/Selenium。"
 version: 1.3.0
 author: Hermes Agent
 metadata:
  hermes:
    tags: [hubstudio, 浏览器环境, 云手机, browser-automation, cross-border]
    related_skills:
      - ziniao-bridge
      - bridge-cdp-agent
      - drissionpage-toolkit
    cron_compatible: true
 ---
 # HubStudio Bridge
 通过 Hermes + AtomK Desktop 连接 HubStudio Local API，用自然语言管理浏览器环境与云手机。
 **触发词：** "HubStudio" / "hubstudio" / "浏览器环境" / "云手机" / "启动环境" / "列出环境"
 ---
 ## 架构总览
 ```
 自然语言指令
    ↓
 Hermes Agent (解析意图)
    ↓
 Bridge POST /api/command  {action: "hubstudio_cdp.navigate", params: {...}}
    ↓  WS → type: "command"
 AtomK Desktop bridge-manager.ts
    ↓  messageRouter.dispatch()
    ├─ hubstudio.*         → HubstudioClient       → HubStudio API (6873)
    └─ hubstudio_cdp.*     → HubStudioCDPController → Playwright connectOverCDP
                             → HubStudio 独立 Chrome (58289)
 ```
 **前提条件：**
 - HubStudio 客户端与 AtomK Desktop 在同一台 Windows/Mac 机器
 - HubStudio 客户端已启动（Local API 模式）
 - API 凭证已配置（app_id + app_secret）
 - Desktop 已更新到包含 `hubstudio-cdp-controller.ts` 的版本
 ### ✅ CDP 中继：hubstudio_cdp.* 命令（Desktop v4.0.x+）
 Desktop 侧新增 `HubStudioCDPController`（`src/main/hubstudio-cdp-controller.ts`），
 通过 Playwright `connectOverCDP` 连接 HubStudio 独立 Chrome 实例。
 Bridge 通过 `POST /api/command` 端点（`cloud-bridge/server.py`）转发命令。
 | 命令 | 参数 | 说明 |
 |------|------|------|
 | `hubstudio_cdp.navigate` | `{envCode, url, waitUntil?, timeout?}` | 在 HubStudio Chrome 中导航 |
 | `hubstudio_cdp.evaluate` | `{envCode, expression}` | 执行 JS 并返回结果 |
 | `hubstudio_cdp.click` | `{envCode, x, y}` | 在指定坐标点击 |
 | `hubstudio_cdp.screenshot` | `{envCode, fullPage?, quality?}` | 截图（返回 base64 JPEG） |
 | `hubstudio_cdp.snapshot` | `{envCode}` | 获取页面可访问性树快照 |
 | `hubstudio_cdp.disconnect` | `{envCode}` | 断开 CDP 连接 |
 | `hubstudio_cdp.status` | — | 查看当前 CDP 连接状态 |
 **自动连接**：`hubstudio.open_env` 成功后自动调用 `hubstudioCdp.connect(containerCode, port)`，
 响应中会包含 `cdpConnected: true`。
 **自动断开**：`hubstudio.close_env` 会先断开 CDP 再关闭浏览器。
 ### ⚠️ CDP 端口可达性
 HubStudio Chrome 的 CDP 端口（如 58289）只在 Windows 本机（127.0.0.1）可达。
 Desktop 通过本机 Playwright `connectOverCDP` 连接，Bridge 通过 Desktop WS 隧道
 中转 CDP 命令。不能从 Bridge/Linux 侧直连 HubStudio CDP 端口。
 **验证端口可达性：** `scripts/hubstudio-cdp-direct-test.py` — 在 Windows 上运行。
 ---
 ## HubStudio Local API
 > 📖 完整 API 文档: `references/hubstudio-api.md`（源: api-docs.hubstudio.cn）
 > 📦 HubStudio Skill 项目: `references/hubstudio-skill-project.md`（OpenClaw 技能包, 56 条命令映射）
 ### 基础 URL
 ```
 http://127.0.0.1:6873
 ```
 ### 认证方式
 所有请求携带 Header：
 ```
 Authorization: Bearer {API_SECRET}
 Accept-Language: zh-CN
 ```
 API Secret 来自 Hubstudio 客户端设置页「API 接口」→「复制 API 密钥」
 ### Desktop 端调用
 Desktop v4.0.2 内置 `hubstudio-client.ts`（Electron 主进程，**无 CORS 限制**），支持完整的 Hubstudio API：
 ```
 hubstudio.list_envs   → POST /api/v1/env/list → 列出所有浏览器环境
 hubstudio.open_env    → POST /api/v1/browser/start → 启动环境 → debuggingPort
 hubstudio.close_env   → POST /api/v1/browser/close → 关闭环境
 hubstudio.opened_envs → POST /api/v1/browser/opened → 已打开环境列表
 hubstudio.status      → 健康检查
 ```
 ## 核心接口
 ### 1. 列出所有浏览器环境
 ```
 POST /api/v1/env/list
 Content-Type: application/json
 {"current": 1, "size": 200}
 ```
 返回示例：
 ```json
 {
  "code": 0,
  "data": {
    "records": [
      {
        "containerCode": "1502764609",
        "containerName": "环境A-亚马逊",
        "remark": "美西",
        "proxyTypeName": "socks5",
        "ipAddress": "103.136.249.48"
      }
    ],
    "total": 1
  }
 }
 ```
 ### 2. 启动浏览器环境
 ```
 POST /api/v1/browser/start
 Content-Type: application/json
 {
  "containerCode": "1502764609",
  "isHeadless": false
 }
 ```
 返回：
 ```json
 {
  "code": 0,
  "data": {
    "containerCode": "1502764609",
    "debuggingPort": "59591",
    "webdriver": "C:\\...webdriver.exe",
    "browserPath": "C:\\...chrome_130\\hubstudio",
    "statusCode": "0"
  }
 }
 ```
 ### 3. 关闭浏览器环境
 ```
 POST /api/v1/browser/close
 {"containerCode": "1502764609"}
 ```
 ### 4. 获取已打开环境
 ```
 POST /api/v1/browser/opened
 {}
 → {"code":0, "data":["1502764609","11320340"]}
 ```
 ---
 ## 操作模式
 ### 模式 A：Bridge 命令路由（Desktop v4.0.2+，推荐）
 Desktop v4.0.2 内置完整 `hubstudio-client.ts` + `bridge-message-router.ts` hubstudio.* 路由。
 Hermes → Bridge → Desktop 主进程直接调 Hubstudio Local API，**无 CORS 限制**。
 ```
 Hermes Agent
  → Bridge WS (type: "command", method: "hubstudio.list_envs")
  → Desktop bridge-manager.ts
  → messageRouter.dispatch()
  → HubstudioClient.listEnvs()
  → POST http://127.0.0.1:6873/api/v1/env/list
  → 返回 → Bridge → Hermes
 ```
 支持的命令：
 | 命令 | 参数 | 说明 |
 |------|------|------|
 | `hubstudio.status` | — | 健康检查/连接测试 |
 | `hubstudio.list_envs` | `{page?, size?}` | 列出浏览器环境 |
 | `hubstudio.open_env` | `{containerCode, isHeadless?}` | 启动环境 → debuggingPort + **自动连 CDP** |
 | `hubstudio.close_env` | `{containerCode}` | 关闭环境 + **自动断 CDP** |
 | `hubstudio.opened_envs` | — | 已打开环境列表 |
 | `hubstudio_cdp.navigate` | `{envCode, url, waitUntil?, timeout?}` | HubStudio Chrome 中导航 |
 | `hubstudio_cdp.evaluate` | `{envCode, expression}` | 执行 JS 返回结果 |
 | `hubstudio_cdp.click` | `{envCode, x, y}` | 坐标点击 |
 | `hubstudio_cdp.screenshot` | `{envCode, fullPage?, quality?}` | 截图（base64 JPEG） |
 | `hubstudio_cdp.snapshot` | `{envCode}` | 可访问性树快照 |
 | `hubstudio_cdp.disconnect` | `{envCode}` | 断开 CDP 连接 |
 | `hubstudio_cdp.status` | — | CDP 连接状态 |
 ### 模式 B：CDP evaluate（备选，有 CORS 问题）
 仅在 Bridge 命令路由不可用时使用。CDP Chrome 调 HubStudio API 会被 CORS 拦截。
 ---
 ## 典型操作场景
 ### 场景 1：列出所有环境
 **自然语言：** "列出我所有 HubStudio 浏览器环境"
 **执行：**
 ```
 GET /api/env/list
 → 解析 → 表格展示环境名称、ID、状态
 ```
 ### 场景 2：启动环境 + 获取端口
 **自然语言：** "启动 HubStudio 环境 1502764609"
 **执行：**
 ```
 POST /api/env/open {"envId": "1502764609"}
 → 获取 debuggingPort
 → Playwright connectOverCDP(port)
 → 可以继续操控该环境
 ```
 ### 场景 3：关闭环境
 **自然语言：** "关闭环境 1502764609"
 **执行：**
 ```
 POST /api/env/close {"envId": "1502764609"}
 ```
 ### 场景 4：巡检所有环境状态
 **自然语言：** "检查所有 HubStudio 环境状态"
 **执行：**
 ```
 GET /api/env/list → 遍历 → GET /api/env/status?envId=xxx
 → 汇总报告
 ```
 ---
 ## Desktop 端调用方式
 Desktop v4.0.2 内置 `hubstudio-client.ts`（Electron 主进程，无 CORS 限制）。
 Bridge 命令通过 `bridge-message-router.ts` 分发到 `HubstudioClient` 方法。
 凭证配置：Desktop Chrome Bridge 页面 → 「紫鸟 & Hubstudio API」：
 - App ID: Hubstudio 客户端设置 → API 接口 → app_id
 - App Secret: 同上 → API 密钥（RSA 私钥，~1600 字符 PEM）
 - Base URL: `http://127.0.0.1:6873`（默认，本地地址）
 存储：`~/.atomk/hubstudio.json`（Electron safeStorage 加密）。
 ## 典型操作场景
 ### 场景 1：列出所有环境
 **自然语言：** "列出我所有 Hubstudio 浏览器环境"
 **执行：**
 ```
 hubstudio.list_envs
 → POST /api/v1/env/list {current:1, size:200}
 → 表格展示环境名称、ID、状态
 ```
 ### 场景 2：启动环境 + 获取端口
 **自然语言：** "启动 HubStudio 环境 1502764609"
 **执行：**
 ```
 hubstudio.open_env {containerCode: "1502764609"}
 → POST /api/v1/browser/start
 → 获取 debuggingPort（如 58289）
 → ⚠️ 此端口仅在 Windows 本机可达，不能从 Bridge/Linux 连接
 → 在 Windows 上用 DrissionPage 直连: Chromium(addr_or_opts='127.0.0.1:58289')
 ```
 详见上方「架构限制」节和 `scripts/hubstudio-cdp-direct-test.py` 测试脚本。
 ### 场景 3：关闭环境
 **自然语言：** "关闭环境 1502764609"
 **执行：**
 ```
 hubstudio.close_env {containerCode: "1502764609"}
 → POST /api/v1/browser/close
 ```
 HubStudio root (127.0.0.1:6873) 在某些情况下 `Page.navigate` 会超时（15s）。
 这是因为 CDP Chrome 保持空白 about:blank page 时 navigate 阻塞。
 **修复**：`/cdp/send` → `Target.createTarget` 直接创建新 tab：
 ```javascript
 fetch('/cdp/send', {
  method: 'POST',
  headers: {..., 'X-Desktop-Id': '<slot>'},
  body: JSON.stringify({method: 'Target.createTarget', params: {url: 'http://127.0.0.1:6873'}})
 })
 // 返回 {targetId: "6034BA..."} — 可直接用于 evaluate
 ```
 无需后续 `/cdp/attach`，新 target 自动 attach。
 ### APP Secret 格式
 HubStudio APP Secret 是 **RSA 私钥**（PEM base64, PKCS#8 格式，~1600 字符）。
 不是普通短字符串。存储在 `.env` 文件时必须完整保留，不可截断。
 ---
 ## 与 紫鸟(ziniao) 的区别
 | | HubStudio | 紫鸟(Ziniao) |
 |------|-----------|-------------|
 | API 端口 | 6873 | 19481（默认） |
 | 认证方式 | Bearer API_SECRET | Bearer apiKey |
 | 环境标识 | containerCode | storeId |
 | 功能 | 浏览器环境 + 云手机 | 店铺浏览器 |
 | Desktop 集成 | v4.0.2 已集成 | v4.0.0 已集成 |
 | Bridge 路由 | hubstudio.* (5 methods) | ziniao.* (5 methods) |
 | API 文档 | api-docs.hubstudio.cn | 紫鸟开放平台 |
 ---
 ## Skill 注册与 Desktop 发现
 Hermes Agent 在 Bridge 服务器（Linux）上运行，Desktop 在用户本机（Windows/Mac）。Skill 文件在服务器上创建后，Desktop 看不到。
 Desktop 从两个源发现 skill：
 1. **本地已安装** — Desktop 扫描本机 `~/.hermes/skills/<category>/<name>/SKILL.md`
 2. **Gitea 注册表** — Desktop 拉取 `admin9webs/atomk-hermes-skills` 仓库
 推送 skill 到 Gitea 注册表的命令：
 ```
 PUT /api/v1/repos/admin9webs/atomk-hermes-skills/contents/skills/<category>/<name>/SKILL.md
 ```
 使用 Basic Auth，body 含 base64 编码内容 + `branch: main`。
 Gitea 注册表根路径：
 ```
 https://gitea9webs.sh3.ikuai7.com/admin9webs/atomk-hermes-skills
 ```
 > ⚠️ Desktop 必须在技能管理页面刷新注册表才能看到新推送的 skill。在 Desktop 中点击"安装"后，skill 文件写入本机 `~/.hermes/skills/`，此后出现在本地已安装列表。
 ## Bridge /api/command 端点
 Desktop 的 hubstudio.* / hubstudio_cdp.* / playwright.* / ziniao.* 命令通过 Bridge 的
 `POST /api/command` 端点转发（`cloud-bridge/server.py`）：
 ```
 Hermes → POST /api/command {action: "hubstudio_cdp.navigate", params: {...}}
       → Bridge WS → Desktop bridge-manager.ts
       → MessageRouter.dispatch({method: action, params})
       → 返回 {type: "command_response", id, ok, data}
 ```
 **认证**：Bearer token + `X-Desktop-Id` header 指定目标 Desktop。
 **请求格式**：
 ```json
 {
  "action": "hubstudio.open_env",
  "params": {"containerCode": "xxx"},
  "id": "optional-custom-id"
 }
 ```
 **响应格式**：
 ```json
 {
  "action": "hubstudio.open_env",
  "ok": true,
  "data": {"debuggingPort": "58289", "cdpConnected": true}
 }
 ```
 **端点注册**：9228 和 9229 端口都已注册。路由在 `/api/{path:.*}` wildcard 之前。
 超时：60 秒（与 proxy_handler 共用 `PROXY_DEFAULT_TIMEOUT`）。
 > 📖 安全审查报告：`references/security-review-2026-07.md`
 > 📜 Windows 直连测试脚本：`scripts/hubstudio-cdp-direct-test.py`
 ## 安全特性
 ### evaluate() 封禁
 `hubstudio_cdp.evaluate` 在 Bridge 路由层已封禁（与 `playwright.execute` 一致的安全策略）。
 任何通过 Bridge 发送的 `hubstudio_cdp.evaluate` 命令都会返回错误：
 `"hubstudio_cdp.evaluate is not available via Bridge (arbitrary JS execution risk)"`
 如需在 HubStudio Chrome 中执行 JS，必须在 Desktop 本机通过 `HubStudioCDPController.evaluate()` 内部调用。
 ### SSRF 防护
 所有导航命令（`hubstudio_cdp.navigate` / `playwright.navigate` / `ziniao.screenshot`）
 共用 `isPrivateHost()` 方法进行内网地址检测，拒绝以下目标：
 - localhost / 127.0.0.1 / 0.0.0.0 / ::1 / [::1]
 - 10.x / 172.16-31.x / 192.168.x / 169.254.x（RFC 1918 + link-local）
 - IPv4-mapped IPv6 地址（`::ffff:127.0.0.1` 等）
 ### CDP Session 管理
 `hubstudio_cdp.snapshot` 使用 `try/finally detach` 确保 CDPSession 不泄漏。
 节点数上限 5000，超出自动截断（防大型页面 OOM）。
 ### 并发安全
 `HubStudioCDPController.connect()` 使用 `pendingConnects` Map 防止同一 envCode
 的并发连接导致 Browser 对象泄漏。
 ## 操作纪律
 1. **串行操作**：多环境操作默认串行，避免资源冲突
 2. **操作间隔**：启停环境间至少间隔 2 秒
 3. **进程清理**：操作完成后关闭不需要的环境释放资源
 4. **凭证安全**：APP_SECRET 不写入日志、不暴露在 shell 命令中
 5. **推送注册表**：新增或修改 server 端 skill 后，必须同步推送到 Gitea 注册表，否则 Desktop 看不到
 6. **Windows 直连用 DrissionPage**：连接 HubStudio 独立 Chrome 时，优先用 `DrissionPage`（`pip install DrissionPage`），无需额外安装浏览器。Playwright 需要 `playwright install chromium`（下载 ~150MB），仅在 DrissionPage 不兼容时回退。
 ## 常见坑
 1. **🛑 Bridge 重启后 Desktop WS 断开，需手动重启 Desktop**：`systemctl restart cloud-bridge` 会断开所有 Desktop WS 连接。Desktop 不会自动重连（需用户手动重启 Desktop App）。重启后 slot ID 会变化（如 `desktop-mr2xlvo9` → `desktop-mr372rlv`），需重新从 `/health` 发现新 slot。
 2. **🛑 list_envs 返回空可能是凭证问题，不是代码 bug**：`hubstudioAvailable: true` 只表示 API 可达。如果 HubStudio API 返回空环境列表（`envCount: 0`），检查 Desktop Chrome Bridge 页面的 HubStudio 凭证（App ID / App Secret）是否正确。凭证存储在 Windows 本机 `~/.atomk/hubstudio.json`（Electron safeStorage 加密），不在 Bridge 服务器上。
 3. **🛑 HubStudio CDP 端口仅在 Windows 本机可达**：HubStudio Chrome 的 `debuggingPort`（如 58289）绑定在 `127.0.0.1`，Bridge（Linux）无法直连。所有 CDP 操作必须通过 Desktop 的 `HubStudioCDPController` 中转。Windows 本地测试可用：`Chromium(addr_or_opts='127.0.0.1:58289')`。
 4. **🛑 DrissionPage pip install 需 `--user`（无管理员权限时）**：`pip install --user DrissionPage` — 直接 `pip install` 在 `C:\Python310` 下可能触发 `PermissionError`。
 5. **🛑 opened_envs 返回 E010006 → 可能是零环境，不是认证错误**：`hubstudio.opened_envs` 返回 `ok: false, error: "internal_error", message: "getOpenedEnvs 失败: code=E010006"` 时，如果同时 `hubstudio.list_envs` 也返回空列表且 `hubstudio.status` 返回 `hubstudioAvailable: true, envCount: 0`，说明 HubStudio API 连接正常但账户下没有任何浏览器环境。这不是凭证问题——应先指导用户在 HubStudio 客户端创建浏览器环境，然后再重试。
 6. **🛑 hubstudio_cdp.* 命令超时 = Desktop 代码版本不匹配**：命令超时（60s 无响应）的最常见原因是 Desktop 在运行构建版 `.exe` 而非 `npm run dev` 开发模式。构建版不含最新合并的 `hubstudio-cdp-controller.ts`。解决：`npm run dev` 热加载最新代码，或 rebuild Desktop。
 7. **🛑 Desktop rebuild 触发条件**：只改 `src/main/` 下的 TypeScript 在 dev 模式无需 rebuild。只有改 `src/renderer/` 或需要分发包时才需要完整 build。
 8. **🛑 Bridge 重启不自动更新 Desktop 代码**：`systemctl restart cloud-bridge.service` 只重启 Bridge Server（使 `/api/command` 等新端点生效）。Desktop 侧的代码更新需 Desktop App 重启（dev 模式热加载）或 rebuild。
 9. **🛑 hubstudio_cdp.connect 端口校验**：`hubstudio_cdp.connect` handler 强制校验 port 为 1-65535 的数字（`typeof port !== 'number'`），字符串会被拒绝。`open_env` 返回的 `debuggingPort` 是字符串，Desktop 内部已做 `parseInt` 转换。
 11. **🛑 SOCKS5 代理延迟（中国→境外）**：HubStudio 环境使用境外 SOCKS5 代理时，`hubstudio_cdp.*` CDP 操作非常慢（30-90s）。Cloud Bridge 会话中 browser_console fetch() 的 30s 硬超时会导致所有 CDP 命令超时。`hubstudio.open_env` 等管理命令仍是快速的。解决方案：用 cron no_agent 脚本 + urllib.request(timeout=90) 执行 CDP 操作。详见 `bridge-cdp-agent` 的 `references/hubstudio-cdp-socks5.md`。
   ① Desktop 代码版本 — 确认运行的是含 `hubstudio-cdp-controller.ts` 的版本（v4.0.17+），检查 health 返回的 version 字段
   ② Bridge 代码版本 — 确认 `cloud-bridge/server.py` 含 `/api/command` 端点（`grep command_handler server.py`）
   ③ Bridge 是否重启 — `/api/command` 端点生效需 `sudo systemctl restart cloud-bridge.service`（注意：重启会导致 Desktop WS 断开）
   ④ 构建产物含 handler — `grep "hubstudio_cdp" out/main/index.js` 确认编译正确
   ⑤ Desktop DevTools Console — 搜索 `[Router]` 看 handler 是否被调用、是否有 JS 错误
   ⑥ 对比 `playwright.status`（应正常）vs `hubstudio_cdp.status`（超时）— 两者同路径，差异说明问题在 MessageRouter handler 层而非路由层
   ⑦ **🔴 bridge-manager.ts 路由守卫遗漏 `hubstudio_cdp.*` — 字符串前缀不匹配**：
      `src/main/bridge-manager.ts` L443 的路由条件只检查 `action.startsWith('hubstudio.')`（带**点**），
      但 `hubstudio_cdp.*` 命令使用**下划线**连接（`hubstudio_cdp.status`）。
      `'hubstudio_cdp.status'.startsWith('hubstudio.')` → **false** → 命令被路由守卫拦截，
      掉入 `switch(action)` 无匹配项 → 静默丢弃 → 不发送 `command_response` → Bridge 等 60s 超时 → 504。
      **修复**：在 L443 添加 `|| action.startsWith('hubstudio_cdp.')`。
      PR #14 (commit `89e8c8d`) 已在 2026-07-03 修复，合入 Desktop **v4.0.18+**。
      **诊断脚本**：`scripts/hubstudio-cdp-routing-test.py` — 一键测试三个命令并输出诊断结论。
      **诊断实录**：`references/hubstudio-cdp-routing-504-diagnosis.md` — 完整的五步诊断过程。
      **验证方式**：`hubstudio.status`✅ + `playwright.status`✅ + `hubstudio_cdp.status`❌504 = 本 bug。
   常见根因（按概率排序）：
   (a) **bridge-manager.ts 路由守卫遗漏 hubstudio_cdp 前缀**（本项 ⑦）— 源码层面 bug，Desktop dev/exe 都受影响
   (b) Desktop 运行构建版 .exe 而非最新 dev 代码 — 构建版不含 hubstudio-cdp-controller.ts
   (c) Bridge 未重启不含 /api/command 端点