---
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 端点