diff --git a/skills/cross-border-ecommerce/hubstudio-bridge/SKILL.md b/skills/cross-border-ecommerce/hubstudio-bridge/SKILL.md new file mode 100644 index 0000000..198dbf1 --- /dev/null +++ b/skills/cross-border-ecommerce/hubstudio-bridge/SKILL.md @@ -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': ''}, + 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///SKILL.md` +2. **Gitea 注册表** — Desktop 拉取 `admin9webs/atomk-hermes-skills` 仓库 + +推送 skill 到 Gitea 注册表的命令： +``` +PUT /api/v1/repos/admin9webs/atomk-hermes-skills/contents/skills///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 端点