HubStudio 集成指南

简介

HubStudio 通过本地 API 提供浏览器环境自动化、云手机操作、环境管理、账号管理和群组管理功能。

本技能旨在：

- 快速定位所有 HubStudio 端点
解释请求/响应字段及约束条件
提供安全的自动化调用模式
标准化 API 测试和故障排查

核心文档：

- 官方 API 文档：https://api-docs.hubstudio.cn/
完整本地生成参考：reference.md

安装

1. 安装 HubStudio 桌面端

在您的机器上安装并打开 HubStudio 客户端，然后登录。

2. 验证本地 API 服务

当前 OpenAPI 文件使用：

bash
http://127.0.0.1:6873

使用以下命令验证服务健康状态：

bash
curl -s -X POST http://127.0.0.1:6873/api/v1/browser/all-browser-status \
-H Content-Type: application/json \
-d {}

3. 安装可选工具

bash

API 调用和 JSON 检查

brew install curl jq

Python 验证脚本

python3 -m pip install --user pyyaml

配置 HubStudio

1. 登录并准备数据

1. 登录 HubStudio 客户端
确保存在浏览器环境/云手机
确认本地 API 可访问

2. 配置运行时变量（可选）

bash
export HUBSTUDIOBASEURL=http://127.0.0.1:6873
export HUBSTUDIOAUTHTOKEN=

3. 时间说明

- 浏览器环境启动通常需要 3-5 秒
云手机启动通常需要 30-90 秒
根据这些时间窗口构建重试/超时逻辑

使用 API/CLI

本项目中的 HubStudio OpenAPI 包含以下领域的 56 个操作：

- 浏览器环境
云手机
环境管理
账号管理
群组管理

Node CLI（直接执行）

本项目包含 hubstudio.js，因此可以直接执行功能：

bash
node hubstudio.js help
node hubstudio.js list
node hubstudio.js browserCreate
node hubstudio.js browserStart 1474900026
node hubstudio.js browserStatus 1474900026
node hubstudio.js browserForeground 1474900026
node hubstudio.js browserArrange
node hubstudio.js browserStop 1474900026
node hubstudio.js testAll

hubstudio.js 现在通过 commands.generated.json 中生成的命令支持所有 OpenAPI 端点。
生成的命令示例：

bash
node hubstudio.js postV1BrowserStart --body {containerCode:1474900026}

云手机 ADB 命令

bash

启用 ADB

node hubstudio.js postV1CloudMobileBatchUpdateAdb --body {mobileIds:[],enableAdb:true}

查询 ADB 连接信息

node hubstudio.js postV1CloudMobileListAdb --body {mobileIds:[]}

常用浏览器环境 API

bash

打开环境

curl -s -X POST http://127.0.0.1:6873/api/v1/browser/start \
-H Content-Type: application/json \
-d {containerCode:1474900026}

关闭环境

curl -s -X POST http://127.0.0.1:6873/api/v1/browser/stop \ -H Content-Type: application/json \ -d {containerCode:1474900026}

获取所有打开环境的状态

curl -s -X POST http://127.0.0.1:6873/api/v1/browser/all-browser-status \ -H Content-Type: application/json \ -d {}

发现完整端点详情

- 打开 reference.md 查看：

- 所有端点和方法 - 请求/响应字段描述 - 必填字段和约束条件 - 按标签分组视图

连接详情

基础 URL

来自 openapi.yaml：

bash
http://127.0.0.1:6873

响应约定

大多数端点返回：

json
{
code: 0,
msg: Success,
data: {}
}

解释：

- code = 0：成功
非零 code：业务错误（缺少字段、未找到、权限、前置条件）

自动化示例

示例 1：打开浏览器环境

bash
node hubstudio.js browserStart 1474900026

示例 2：查询运行中的浏览器环境

bash
node hubstudio.js browserStatus

示例 3：对所有 OpenAPI 端点进行冒烟测试

bash

当前冒烟测试报告（先前生成）：

cat scripts/endpointtestreport.json | jq .total, .reachable, .transportfailcount

示例 4：验证技能完整性

bash
python3 scripts/validate_completeness.py

常见问题

问题 1：API 返回 HTTP 200 但业务失败

这是许多端点的预期行为。请检查响应体中的 code 和 msg 以获取业务级别结果。

问题 2：环境打开失败

检查：

1. containerCode 是否正确
环境在当前账号/工作空间中是否存在
HubStudio 客户端已登录且本地服务正在运行

问题 3：为什么某些端点测试因缺少参数而失败？

端点冒烟测试首先测试可达性。因必需参数/资源导致的业务失败是正常的，除非提供了严格的案例数据。

问题 4：如何找到必填字段？

使用 reference.md。每个端点列出：

- 必需参数
请求体必填字段
类型和约束详情

高级用法

1. OpenClaw 集成

在 OpenClaw 工作流中，直接使用结构化负载调用 HubStudio 端点：

bash

示例：打开环境

openclaw hubstudio call --path /api/v1/browser/start \
--method POST \
--body {containerCode:1474900026}

2. 重试策略

- 浏览器环境 API：重试 1-2 次，间隔 2-3 秒
云手机 API：重试 2-4 次，间隔 5-10 秒

3. 批量操作

对于批量任务，遍历 ID 并记录每个项目的结果，容忍部分失败。

4. 验证循环

1. 更新 openapi.yaml 中的数据
重新生成 reference.md
运行 python3 scripts/validatecompleteness.py
运行端点冒烟测试并检查 scripts/endpointtest_report.json

ADB 连接技能

当用户要求通过 ADB 连接云手机时使用此功能。

- Android 12 / Android 15：直接 adb connect 模式
Android 13 / Android 14 / Android 15A：SSH 隧道 + adb connect localhost: 模式
完整指南和命令模板：ADBCONNECTION_GUIDE.md

执行规则：

1. 确保云手机已开机
通过 postV1CloudMobileBatchUpdateAdb 启用 ADB
通过 postV1CloudMobileListAdb 查询 ADB 信息
根据 Android 版本选择直接或隧道工作流
使用 adb devices 验证

资源

- HubStudio API 文档：https://api-docs.hubstudio.cn/
完整生成的 API

hubstudio-openapiHubStudio开放接口

hubstudio-openapi

HubStudio Integration Guide

Table of Contents

Introduction

Installation

1. Install HubStudio Desktop

2. Verify Local API Service

3. Install Optional Tooling

Configure HubStudio

1. Login and Prepare Data

2. Configure Runtime Variables (Optional)

3. Timing Notes

Using API/CLI

Recommended Call Pattern

Node CLI (Direct Execution)

Cloud Phone ADB Commands

Common Browser Environment APIs

Discover Full Endpoint Details

Connection Details

Base URL

Response Convention

Automation Examples

Example 1: Open Browser Environment

Example 2: Query Running Browser Environments

Example 3: Smoke Test All OpenAPI Endpoints

Example 4: Validate Skill Completeness

FAQ

Q1: API Returns HTTP 200 But Business Failure

Q2: Environment Open Failed

Q3: Why Some Endpoint Tests Fail with Missing Parameters?

Q4: How to Find Required Fields?

Advanced Usage

1. OpenClaw Integration

2. Retry Strategy

3. Batch Operations

4. Validation Loop

ADB Connection Skill

Resources

HubStudio 集成指南

目录

简介

安装

1. 安装 HubStudio 桌面端

2. 验证本地 API 服务

3. 安装可选工具

API 调用和 JSON 检查

Python 验证脚本

配置 HubStudio

1. 登录并准备数据

2. 配置运行时变量（可选）

3. 时间说明

使用 API/CLI

推荐调用模式

Node CLI（直接执行）

云手机 ADB 命令

启用 ADB

查询 ADB 连接信息

常用浏览器环境 API

打开环境

关闭环境

获取所有打开环境的状态

发现完整端点详情

连接详情

基础 URL

响应约定

自动化示例

示例 1：打开浏览器环境

示例 2：查询运行中的浏览器环境

示例 3：对所有 OpenAPI 端点进行冒烟测试

当前冒烟测试报告（先前生成）：

示例 4：验证技能完整性

常见问题

问题 1：API 返回 HTTP 200 但业务失败

问题 2：环境打开失败

问题 3：为什么某些端点测试因缺少参数而失败？

问题 4：如何找到必填字段？

高级用法

1. OpenClaw 集成

示例：打开环境