archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）

来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
2026-10-05 12:11:35 +00:00
commit 322b7737eb
@@ -0,0 +1,340 @@
+# 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`