HubStudio OpenAPI Skill

这是一个面向 HubStudio 本地 API 的技能项目，目标是让你可以用统一方式完成：

• API 能力检索（有哪些接口、每个接口做什么）
• 请求参数校验（必填项、类型、约束）
• 自动化调用（浏览器环境、云手机、账号、分组等）
• 常见问题排查（HTTP 成功但业务失败、环境无法启动等）

项目核心定位：把 openapi.yaml 的接口能力，转成可查询、可执行、可自动化的工程化工具链。

---

项目提供的 Skill 能力

1) 全量接口查询能力

• 基于 openapi.yaml 提供 HubStudio 全量接口定义
• 当前生成命令总数：56（见 commands.generated.json）
• 覆盖业务域：
  • 浏览器环境
  • 云手机
  • 环境管理
  • 平台账号管理
  • 分组管理

你可以快速回答类似问题：

• “打开环境接口叫什么？请求体怎么写？”
• “批量开启云手机需要哪些字段？”
• “某接口返回字段 debuggingPort 是什么含义？”

---

2) 请求/响应字段解释能力

Skill 可以按接口粒度解释：

• 请求参数（query/header/body）
• 必填字段与可选字段
• 字段类型与含义
• 响应 code/msg/data 结构

这使得你可以在自动化流程里先做参数检查，再发请求，减少无效调用。

---

3) 本地 CLI 执行能力（开箱即用）

项目内置 hubstudio.js，可直接调用 HubStudio 本地 API：

node hubstudio.js help
node hubstudio.js list
node hubstudio.js browserStart 1502764609
node hubstudio.js browserStatus 1502764609
node hubstudio.js browserStop 1502764609

也支持生成命令直调：

node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609"}'

---

4) 浏览器自动化接入能力（Playwright）

项目已提供端到端示例脚本：playwright_hubstudio_baidu_demo.js，可完成：

1. 启动 HubStudio 环境
2. 获取 debuggingPort
3. 使用 Playwright 通过 CDP 连接该浏览器
4. 打开百度并搜索 HubStudio
5. 点击第一条结果并提取正文
6. 生成摘要文件并关闭环境

执行命令：

node playwright_hubstudio_baidu_demo.js

输出结果示例文件：

• summary_hubstudio_baidu_playwright.txt

---

5) ADB 连接辅助能力（云手机）

项目提供云手机 ADB 连接专项说明：ADB_CONNECTION_GUIDE.md，用于：

• 开启 ADB
• 查询连接信息
• 根据 Android 版本选择连接模式
• 验证 adb devices

---

项目文件说明

• SKILL.md：Skill 主说明（使用指引、调用建议、FAQ）
• openapi.yaml：HubStudio OpenAPI 源定义
• reference.md：从 OpenAPI 生成的本地接口参考文档
• commands.generated.json：从 OpenAPI 生成的 CLI 命令映射
• hubstudio.js：统一命令行入口（别名 + 生成命令）
• playwright_hubstudio_baidu_demo.js：Playwright 端到端自动化示例
• ADB_CONNECTION_GUIDE.md：云手机 ADB 接入指南
• OPENCLAW_AGENT_BROWSER_TUTORIAL.md：面向新手的实操教程（当前已切换为 Playwright 流程）

---

快速开始（建议流程）

1. 环境准备

# 先进入项目根目录（README 所在目录）
cd ./
node --version
openclaw --version

2. 安装依赖（如需运行 Playwright 示例）

npm init -y
npm install playwright

3. 验证 HubStudio API 可用

node hubstudio.js browserStatus 1502764609

若返回 code: 0 说明 API 可正常调用。

4. 运行示例

node playwright_hubstudio_baidu_demo.js

---

安装 HubStudio Skill 到 OpenClaw（详细步骤）

这一节专门说明：如何把当前项目作为一个 Skill 安装到 OpenClaw 并让 OpenClaw 识别。

1) 先确认 OpenClaw 已初始化

openclaw onboard --install-daemon
openclaw gateway status

2) 创建 OpenClaw 的 workspace skills 目录

mkdir -p "$HOME/.openclaw/workspace/skills"

3) 安装方式二选一

方式 A（推荐）：软链接，方便你持续更新

适合开发调试：你修改当前项目文件，OpenClaw 立即读取最新内容。

ln -sfn "./" "$HOME/.openclaw/workspace/skills/hubstudio"

方式 B：复制一份稳定版本

适合“先固定版本再使用”。

rm -rf "$HOME/.openclaw/workspace/skills/hubstudio"
cp -R "./" "$HOME/.openclaw/workspace/skills/hubstudio"

4) 让 OpenClaw 刷新技能状态

openclaw gateway restart

5) 验证 Skill 是否安装成功

openclaw skills check
openclaw skills list
openclaw skills info hubstudio-openapi

成功时你应看到：

• hubstudio-openapi 状态为 ready
• 来源显示为 openclaw-workspace
• 路径类似：~/.openclaw/workspace/skills/hubstudio/SKILL.md

6) 安装后建议做一次能力验证

cd ./
node hubstudio.js list
node hubstudio.js browserStatus 1502764609

如果你在 OpenClaw 中调用与 HubStudio API 相关任务时，模型能够命中 hubstudio-openapi 这个 skill，即说明集成生效。

---

响应判定规范（非常重要）

HubStudio 常见返回结构：

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

判定规则：

• HTTP 200 不代表业务成功
• 以 code 为准：
  • code = 0：成功
  • code != 0：业务失败（参数、权限、资源状态等）

---

参数校验模式（团队统一建议）

hubstudio.js 已内置 OpenAPI 驱动的参数强校验，支持两种模式：

• strict=true（默认）
  • 开启必填、类型、范围、格式、枚举校验
  • 拒绝未知字段（如拼错字段名）
• strict=false
  • 必填、类型、范围、格式、枚举仍然校验
  • 仅放过未知字段（用于调试或灰度联调）

1) 默认严格模式（推荐生产）

node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609"}'

2) 临时切换宽松模式（仅用于排障）

node hubstudio.js postV1BrowserStart --strict false --body '{"containerCode":"1502764609","x":1}'

3) 通过环境变量统一设置模式

# 关闭严格模式（当前 shell 会话生效）
export HUBSTUDIO_STRICT_VALIDATION=false
node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609","x":1}'

# 恢复严格模式
export HUBSTUDIO_STRICT_VALIDATION=true

4) 校验失败返回格式（标准化）

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "command": "postV1BrowserStart",
    "fieldErrors": [
      {
        "field": "body.containerCode",
        "reason": "required field missing or empty",
        "expected": "required",
        "actualType": "missing"
      }
    ]
  }
}

5) 团队使用建议

• 日常开发与生产执行统一用默认严格模式
• 只在定位线上疑难问题时，短时使用 --strict false
• 排障结束后务必恢复严格模式，避免脏字段长期进入调用链

---

典型使用场景

• 批量管理浏览器环境（开关、状态、窗口排列）
• 云手机应用安装/启动/停止自动化
• ADB 开启与连接状态查询
• 将 HubStudio 接口能力接入 OpenClaw/脚本工作流
• 用 Playwright 基于 HubStudio 环境做网页自动化

---

常见问题

1) 接口返回 200 但任务没成功

请检查返回体中的 code 和 msg，不要只看 HTTP 状态码。

2) 启动环境失败

优先检查：

• HubStudio 客户端是否登录
• 是否开通VIP
• containerCode 是否存在且属于当前账号
• 本地服务地址是否是 http://127.0.0.1:6873 端口可能存在变动需要检查

3) 自动化脚本连接不上浏览器

请确认：

• browserStart 后返回了 debuggingPort
• 环境未提前关闭
• 本机端口未被拦截

---

参考文档

• OpenClaw Getting Started:
• HubStudio API Docs:
• 项目内接口参考：reference.md