字huozi.app

HTTP API 参考

huozi 的所有公开 HTTP 端点。OAuth 元数据按 RFC 8414 / RFC 9728 标准化;MCP 端点是标准 JSON-RPC over HTTP。Cloud 用 cloud.huozi.app,Edge 部署替换为你自己的 worker 域名 —— 端点路径完全一致。

下文示例都用 https://cloud.huozi.app 作为 base。Edge 用户把它换成你自己的 worker URL(比如 https://myco.workers.dev)即可。

OAuth 自动发现 (.well-known)

GET /.well-known/oauth-protected-resource

RFC 9728 protected resource metadata。声明 /mcp 是受 OAuth 保护的资源,客户端遇到 401 时跟着 WWW-Authenticate 到这里发现授权服务器。

curl https://cloud.huozi.app/.well-known/oauth-protected-resource

# →
{
  "resource": "https://cloud.huozi.app/mcp",
  "authorization_servers": ["https://cloud.huozi.app"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://cloud.huozi.app/start"
}

GET /.well-known/oauth-authorization-server

RFC 8414 authorization server metadata。客户端从这里读到所有 OAuth 端点(包括 device flow)和支持的 grant types。

curl https://cloud.huozi.app/.well-known/oauth-authorization-server

# →
{
  "issuer": "https://cloud.huozi.app",
  "authorization_endpoint": "https://cloud.huozi.app/oauth/authorize",
  "token_endpoint": "https://cloud.huozi.app/oauth/token",
  "registration_endpoint": "https://cloud.huozi.app/oauth/register",
  "device_authorization_endpoint": "https://cloud.huozi.app/auth/device-code",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"],
  "service_documentation": "https://cloud.huozi.app/start"
}

Device flow (RFC 8628)

POST /auth/device-code

Device flow 起点。Agent 调它拿一对 device_code(自己用)和 user_code(给人看)。

字段类型说明
client_name可选 string ≤ 80 字符在 connection 列表里显示用,比如 "Hermes on laptop"。
agent_kind可选 string ≤ 32 字符枚举:claude-code | cursor | hermes | openclaw | codex | cowork | desktop | generic。仅做归类标签,不影响功能。
curl -sS -X POST https://cloud.huozi.app/auth/device-code \
  -H "content-type: application/json" \
  -d '{"client_name":"Hermes on laptop","agent_kind":"hermes"}'

# →
{
  "device_code": "<48 hex chars>",
  "user_code": "ABCD-1234",
  "verification_url": "https://cloud.huozi.app/device",
  "verification_url_complete": "https://cloud.huozi.app/device?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

POST /auth/token

轮询端点。每 interval 秒(默认 5 秒)调一次直到拿到 api_key 或终态错误。

curl -sS -X POST https://cloud.huozi.app/auth/token \
  -H "content-type: application/json" \
  -d '{"device_code":"<from /auth/device-code>"}'

# Pending:    202  {"error": "authorization_pending"}
# Expired:    400  {"error": "expired_token"}
# Denied:     400  {"error": "access_denied"}
# Authorized: 200  {
#   "api_key": "hz_<slug>_<32 hex>",
#   "key_id": "k_<16 hex>",
#   "workspace": { "id": "ws_<slug>", "slug": "<slug>" }
# }

标准 OAuth token 端点

POST /oauth/token

RFC 8252 + RFC 8628 共用的 token 端点。接受 application/json 或 application/x-www-form-urlencoded。三种 grant_type:

grant_type用途返回
authorization_codeRFC 8252 PKCE auth code 兑换为 access_token + refresh_token{access_token, token_type:Bearer, expires_in:3600, refresh_token, scope}
refresh_token用 refresh_token 轮换出新的 access_token{access_token, token_type:Bearer, expires_in:3600, refresh_token, scope}
urn:ietf:params:oauth:grant-type:device_codeRFC 8628 device code 兑换 token(form-encoded 标准接口){access_token, token_type:Bearer, scope}
# Device flow via standard OAuth shape
curl -sS -X POST https://cloud.huozi.app/oauth/token \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "device_code=<from /auth/device-code>"

# → {"access_token":"hz_...","token_type":"Bearer","scope":"mcp"}

MCP 端点

POST /mcp

MCP JSON-RPC 2.0 over HTTP(streamable-http transport)。所有 16 个 huozi_* 工具都通过这里调。要求 Authorization: Bearer <token>。无 token 返回 401 + WWW-Authenticate 触发 OAuth 自动发现。

curl -sS -X POST https://cloud.huozi.app/mcp \
  -H "Authorization: Bearer hz_<your_key>" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "huozi_whoami",
      "arguments": {}
    }
  }'

Agent 可读规范

GET /llms.txt

按 llmstxt.org 约定的纯文本安装协议。chat-mode Agent 用 WebFetch 拿这份,自己跑 device flow。Cache 5 分钟,内容按 request host 模板生成 —— Edge 部署自动用自己的 worker 域名。

curl https://cloud.huozi.app/llms.txt

GET /llms.txt?for=<agent_kind>

把 Step 4 过滤到只剩这一个 host 的 snippet,doc 缩到 ~70%,小 context 模型友好。kind 同上面 agent_kind 枚举。

更多