admin9webs
322b7737eb
来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。 只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
341 lines
7.9 KiB
Markdown
341 lines
7.9 KiB
Markdown
# 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：
|
||
|
||
```bash
|
||
node hubstudio.js help
|
||
node hubstudio.js list
|
||
node hubstudio.js browserStart 1502764609
|
||
node hubstudio.js browserStatus 1502764609
|
||
node hubstudio.js browserStop 1502764609
|
||
```
|
||
|
||
也支持生成命令直调：
|
||
|
||
```bash
|
||
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. 生成摘要文件并关闭环境
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
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. 环境准备
|
||
|
||
```bash
|
||
# 先进入项目根目录（README 所在目录）
|
||
cd ./
|
||
node --version
|
||
openclaw --version
|
||
```
|
||
|
||
### 2. 安装依赖（如需运行 Playwright 示例）
|
||
|
||
```bash
|
||
npm init -y
|
||
npm install playwright
|
||
```
|
||
|
||
### 3. 验证 HubStudio API 可用
|
||
|
||
```bash
|
||
node hubstudio.js browserStatus 1502764609
|
||
```
|
||
|
||
若返回 `code: 0` 说明 API 可正常调用。
|
||
|
||
### 4. 运行示例
|
||
|
||
```bash
|
||
node playwright_hubstudio_baidu_demo.js
|
||
```
|
||
|
||
---
|
||
|
||
## 安装 HubStudio Skill 到 OpenClaw（详细步骤）
|
||
|
||
这一节专门说明：如何把当前项目作为一个 Skill 安装到 OpenClaw 并让 OpenClaw 识别。
|
||
|
||
### 1) 先确认 OpenClaw 已初始化
|
||
|
||
```bash
|
||
openclaw onboard --install-daemon
|
||
openclaw gateway status
|
||
```
|
||
|
||
### 2) 创建 OpenClaw 的 workspace skills 目录
|
||
|
||
```bash
|
||
mkdir -p "$HOME/.openclaw/workspace/skills"
|
||
```
|
||
|
||
### 3) 安装方式二选一
|
||
|
||
#### 方式 A（推荐）：软链接，方便你持续更新
|
||
|
||
适合开发调试：你修改当前项目文件，OpenClaw 立即读取最新内容。
|
||
|
||
```bash
|
||
ln -sfn "./" "$HOME/.openclaw/workspace/skills/hubstudio"
|
||
```
|
||
|
||
#### 方式 B：复制一份稳定版本
|
||
|
||
适合“先固定版本再使用”。
|
||
|
||
```bash
|
||
rm -rf "$HOME/.openclaw/workspace/skills/hubstudio"
|
||
cp -R "./" "$HOME/.openclaw/workspace/skills/hubstudio"
|
||
```
|
||
|
||
### 4) 让 OpenClaw 刷新技能状态
|
||
|
||
```bash
|
||
openclaw gateway restart
|
||
```
|
||
|
||
### 5) 验证 Skill 是否安装成功
|
||
|
||
```bash
|
||
openclaw skills check
|
||
openclaw skills list
|
||
openclaw skills info hubstudio-openapi
|
||
```
|
||
|
||
成功时你应看到：
|
||
|
||
- `hubstudio-openapi` 状态为 `ready`
|
||
- 来源显示为 `openclaw-workspace`
|
||
- 路径类似：`~/.openclaw/workspace/skills/hubstudio/SKILL.md`
|
||
|
||
### 6) 安装后建议做一次能力验证
|
||
|
||
```bash
|
||
cd ./
|
||
node hubstudio.js list
|
||
node hubstudio.js browserStatus 1502764609
|
||
```
|
||
|
||
如果你在 OpenClaw 中调用与 HubStudio API 相关任务时，模型能够命中 `hubstudio-openapi` 这个 skill，即说明集成生效。
|
||
|
||
---
|
||
|
||
## 响应判定规范（非常重要）
|
||
|
||
HubStudio 常见返回结构：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "Success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
判定规则：
|
||
|
||
- `HTTP 200` 不代表业务成功
|
||
- 以 `code` 为准：
|
||
- `code = 0`：成功
|
||
- `code != 0`：业务失败（参数、权限、资源状态等）
|
||
|
||
---
|
||
|
||
## 参数校验模式（团队统一建议）
|
||
|
||
`hubstudio.js` 已内置 OpenAPI 驱动的参数强校验，支持两种模式：
|
||
|
||
- `strict=true`（默认）
|
||
- 开启必填、类型、范围、格式、枚举校验
|
||
- 拒绝未知字段（如拼错字段名）
|
||
- `strict=false`
|
||
- 必填、类型、范围、格式、枚举仍然校验
|
||
- 仅放过未知字段（用于调试或灰度联调）
|
||
|
||
### 1) 默认严格模式（推荐生产）
|
||
|
||
```bash
|
||
node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609"}'
|
||
```
|
||
|
||
### 2) 临时切换宽松模式（仅用于排障）
|
||
|
||
```bash
|
||
node hubstudio.js postV1BrowserStart --strict false --body '{"containerCode":"1502764609","x":1}'
|
||
```
|
||
|
||
### 3) 通过环境变量统一设置模式
|
||
|
||
```bash
|
||
# 关闭严格模式（当前 shell 会话生效）
|
||
export HUBSTUDIO_STRICT_VALIDATION=false
|
||
node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609","x":1}'
|
||
|
||
# 恢复严格模式
|
||
export HUBSTUDIO_STRICT_VALIDATION=true
|
||
```
|
||
|
||
### 4) 校验失败返回格式（标准化）
|
||
|
||
```json
|
||
{
|
||
"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: <https://docs.openclaw.ai/start/getting-started>
|
||
- HubStudio API Docs: <https://api-docs.hubstudio.cn/>
|
||
- 项目内接口参考：`reference.md`
|