archive: 紫鸟/HubStudio 文档快照（3889 篇 Markdown）
来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。 只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
This commit is contained in:
admin9webs committed
commit
322b7737eb
3976 files changed
+695714
No files matched your search
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: hubstudio-openapi
|
||||
description: HubStudio OpenAPI skill for full endpoint lookup, request/response field explanation, and parameter constraint checking. Use when querying HubStudio API interfaces, validating request payloads, or building automation against openapi.yaml.
|
||||
---
|
||||
|
||||
# HubStudio Integration Guide
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#introduction)
|
||||
2. [Installation](#installation)
|
||||
3. [Configure HubStudio](#configure-hubstudio)
|
||||
4. [Using API/CLI](#using-apicli)
|
||||
5. [Connection Details](#connection-details)
|
||||
6. [Automation Examples](#automation-examples)
|
||||
7. [FAQ](#faq)
|
||||
8. [Advanced Usage](#advanced-usage)
|
||||
9. [ADB Connection Skill](#adb-connection-skill)
|
||||
10. [Resources](#resources)
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
HubStudio provides browser environment automation, cloud phone operations, environment management, account management, and group management through local APIs.
|
||||
|
||||
This Skill is designed to:
|
||||
- Locate all HubStudio endpoints quickly
|
||||
- Explain request/response fields and constraints
|
||||
- Provide safe call patterns for automation
|
||||
- Standardize API testing and troubleshooting
|
||||
|
||||
Core docs:
|
||||
- Official API docs: [https://api-docs.hubstudio.cn/](https://api-docs.hubstudio.cn/)
|
||||
- Full local generated reference: [reference.md](reference.md)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Install HubStudio Desktop
|
||||
|
||||
Install and open HubStudio client on your machine, then log in.
|
||||
|
||||
### 2. Verify Local API Service
|
||||
|
||||
The current OpenAPI file uses:
|
||||
|
||||
```bash
|
||||
http://127.0.0.1:6873
|
||||
```
|
||||
|
||||
Verify service health with:
|
||||
|
||||
```bash
|
||||
curl -s -X POST "http://127.0.0.1:6873/api/v1/browser/all-browser-status" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
### 3. Install Optional Tooling
|
||||
|
||||
```bash
|
||||
# API calls and JSON inspection
|
||||
brew install curl jq
|
||||
|
||||
# Python validation scripts
|
||||
python3 -m pip install --user pyyaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configure HubStudio
|
||||
|
||||
### 1. Login and Prepare Data
|
||||
|
||||
1. Login to HubStudio client
|
||||
2. Ensure browser environments/cloud phones exist
|
||||
3. Confirm local API is reachable
|
||||
|
||||
### 2. Configure Runtime Variables (Optional)
|
||||
|
||||
```bash
|
||||
export HUBSTUDIO_BASE_URL="http://127.0.0.1:6873"
|
||||
export HUBSTUDIO_AUTH_TOKEN="<your-token-if-needed>"
|
||||
```
|
||||
|
||||
### 3. Timing Notes
|
||||
|
||||
- Browser environment startup typically takes **3-5 seconds**
|
||||
- Cloud phone startup typically takes **30-90 seconds**
|
||||
- Build retry/timeout logic based on those windows
|
||||
|
||||
---
|
||||
|
||||
## Using API/CLI
|
||||
|
||||
HubStudio OpenAPI in this project contains 56 operations across these domains:
|
||||
- Browser Environment
|
||||
- Cloud Phone
|
||||
- Environment Management
|
||||
- Account Management
|
||||
- Group Management
|
||||
|
||||
### Recommended Call Pattern
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$HUBSTUDIO_BASE_URL/<endpoint>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '<json-body>'
|
||||
```
|
||||
|
||||
### Node CLI (Direct Execution)
|
||||
|
||||
This project includes `hubstudio.js`, so you can execute capabilities directly:
|
||||
|
||||
```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` now supports all OpenAPI endpoints via generated commands in `commands.generated.json`.
|
||||
Example generated command:
|
||||
|
||||
```bash
|
||||
node hubstudio.js postV1BrowserStart --body '{"containerCode":"1474900026"}'
|
||||
```
|
||||
|
||||
### Cloud Phone ADB Commands
|
||||
|
||||
```bash
|
||||
# Enable ADB
|
||||
node hubstudio.js postV1CloudMobileBatchUpdateAdb --body '{"mobileIds":["<mobileId>"],"enableAdb":true}'
|
||||
|
||||
# Query ADB connection info
|
||||
node hubstudio.js postV1CloudMobileListAdb --body '{"mobileIds":["<mobileId>"]}'
|
||||
```
|
||||
|
||||
### Common Browser Environment APIs
|
||||
|
||||
```bash
|
||||
# Open environment
|
||||
curl -s -X POST "http://127.0.0.1:6873/api/v1/browser/start" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"containerCode":"1474900026"}'
|
||||
|
||||
# Close environment
|
||||
curl -s -X POST "http://127.0.0.1:6873/api/v1/browser/stop" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"containerCode":"1474900026"}'
|
||||
|
||||
# Get all open environment status
|
||||
curl -s -X POST "http://127.0.0.1:6873/api/v1/browser/all-browser-status" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
### Discover Full Endpoint Details
|
||||
|
||||
- Open [reference.md](reference.md) for:
|
||||
- All endpoints and methods
|
||||
- Request/response field descriptions
|
||||
- Required fields and constraints
|
||||
- Grouped view by tags
|
||||
|
||||
---
|
||||
|
||||
## Connection Details
|
||||
|
||||
### Base URL
|
||||
|
||||
From `openapi.yaml`:
|
||||
|
||||
```bash
|
||||
http://127.0.0.1:6873
|
||||
```
|
||||
|
||||
### Response Convention
|
||||
|
||||
Most endpoints return:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
- `code = 0`: success
|
||||
- non-zero code: business error (missing field, not found, permission, precondition)
|
||||
|
||||
---
|
||||
|
||||
## Automation Examples
|
||||
|
||||
### Example 1: Open Browser Environment
|
||||
|
||||
```bash
|
||||
node hubstudio.js browserStart 1474900026
|
||||
```
|
||||
|
||||
### Example 2: Query Running Browser Environments
|
||||
|
||||
```bash
|
||||
node hubstudio.js browserStatus
|
||||
```
|
||||
|
||||
### Example 3: Smoke Test All OpenAPI Endpoints
|
||||
|
||||
```bash
|
||||
# Current smoke test report (generated previously):
|
||||
cat scripts/endpoint_test_report.json | jq '.total, .reachable, .transport_fail_count'
|
||||
```
|
||||
|
||||
### Example 4: Validate Skill Completeness
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_completeness.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q1: API Returns HTTP 200 But Business Failure
|
||||
|
||||
This is expected for many endpoints. Check response body `code` and `msg` for business-level result.
|
||||
|
||||
### Q2: Environment Open Failed
|
||||
|
||||
Check:
|
||||
1. `containerCode` is correct
|
||||
2. Environment exists in current account/workspace
|
||||
3. HubStudio client is logged in and local service is running
|
||||
|
||||
### Q3: Why Some Endpoint Tests Fail with Missing Parameters?
|
||||
|
||||
Endpoint smoke tests are designed for reachability first. Business failures due to required params/resources are normal unless strict case data is provided.
|
||||
|
||||
### Q4: How to Find Required Fields?
|
||||
|
||||
Use [reference.md](reference.md). Each endpoint lists:
|
||||
- Required parameters
|
||||
- Request body required fields
|
||||
- Type and constraint details
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### 1. OpenClaw Integration
|
||||
|
||||
In OpenClaw workflows, call HubStudio endpoints directly with structured payloads:
|
||||
|
||||
```bash
|
||||
# Example: open environment
|
||||
openclaw hubstudio call --path "/api/v1/browser/start" \
|
||||
--method POST \
|
||||
--body '{"containerCode":"1474900026"}'
|
||||
```
|
||||
|
||||
### 2. Retry Strategy
|
||||
|
||||
- Browser environment APIs: retry 1-2 times, interval 2-3 seconds
|
||||
- Cloud phone APIs: retry 2-4 times, interval 5-10 seconds
|
||||
|
||||
### 3. Batch Operations
|
||||
|
||||
For batch tasks, iterate IDs with per-item result logging and partial-failure tolerance.
|
||||
|
||||
### 4. Validation Loop
|
||||
|
||||
1. Update data in `openapi.yaml`
|
||||
2. Re-generate `reference.md`
|
||||
3. Run `python3 scripts/validate_completeness.py`
|
||||
4. Run endpoint smoke tests and inspect `scripts/endpoint_test_report.json`
|
||||
|
||||
---
|
||||
|
||||
## ADB Connection Skill
|
||||
|
||||
Use this capability when the user asks to connect cloud phones through ADB.
|
||||
|
||||
- Android 12 / Android 15: direct `adb connect <ip:port>` mode
|
||||
- Android 13 / Android 14 / Android 15A: SSH tunnel + `adb connect localhost:<port>` mode
|
||||
- Full guide and command templates: [ADB_CONNECTION_GUIDE.md](ADB_CONNECTION_GUIDE.md)
|
||||
|
||||
Execution rule:
|
||||
1. Ensure cloud phone is powered on
|
||||
2. Enable ADB via `postV1CloudMobileBatchUpdateAdb`
|
||||
3. Query ADB info via `postV1CloudMobileListAdb`
|
||||
4. Choose direct or tunnel workflow by Android version
|
||||
5. Validate with `adb devices`
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- HubStudio API Docs: [https://api-docs.hubstudio.cn/](https://api-docs.hubstudio.cn/)
|
||||
- Full Generated API Reference: [reference.md](reference.md)
|
||||
- ADB workflow details: [ADB_CONNECTION_GUIDE.md](ADB_CONNECTION_GUIDE.md)
|
||||
- Completeness Checker: `scripts/validate_completeness.py`
|
||||
- Endpoint Smoke Test Report: `scripts/endpoint_test_report.json`
|
||||
Reference in new issue
Block a user