SDK 与开发工具参考文档
HabitaXX 开放平台为各主流编程语言提供了官方 SDK,并提供了官方命令行工具 CLI 及 AI 智能体 Skill 插件,帮助开发者快速接入平台鉴权、健康检查以及各项 AI 能力(如鸟类多模态识别、宠物 IMU 行为分析、宠物档案、智能问诊等)。
工具与生态清单
| 名称 / 工具 | 源码 / 包目录 | 文档入口 | 核心特性 |
|---|---|---|---|
| Python SDK | sdk/habitaxx-python | Python SDK API 文档 | 原生类型提示、同步与异步双客户端、全模块覆盖 |
| Node.js SDK | sdk/habitaxx-node | Node.js SDK API 文档 | TypeScript 原生、Promise / Async-Await、现代开发体验 |
| Go SDK | sdk/habitaxx-go | Go SDK API 文档 | 高性能、基于标准库、结构体强类型约束 |
| Java SDK | sdk/habitaxx-java | Java SDK API 文档 | 零第三方依赖、Java 8+ 纯标准库兼容、泛型强类型支持 |
| CLI 命令行工具 | sdk/cli | CLI 命令行工具 | 设备授权流程(RFC 8628)、凭证本地隔离存储、免写代码直调能力 |
| Agent Skill 插件 | sdk/habitaxx-skill | Agent Skill 插件 | 面向 AI 编程助手的 Skill 规范,凭证零泄露安全调度 |
统一鉴权流程
HabitaXX 开放平台采用两阶段统一认证模式:
- 获取 Access Token:开发者使用分配的
x-api-key、project_no和终端user_id向网关换取终端用户的短期 JWT(Access Token)。 - 携带 Token 调用能力:在后续请求中通过 HTTP 请求头
Authorization: Bearer <access_token>访问具体 AI 能力接口。
mermaid
sequenceDiagram
autonumber
actor Client as 客户端 (SDK / CLI)
participant Gateway as 平台网关 (/v1/auth/token)
participant Capability as AI 能力服务 (/v1/...)
Client->>Gateway: POST /v1/auth/token (x-api-key + project_no + user_id)
Gateway-->>Client: 200 OK (access_token, expires_in)
Client->>Client: 缓存并设置 Authorization: Bearer <access_token>
Client->>Capability: POST /v1/bird/detect (带图片与 Token)
Capability-->>Client: 200 OK (code=200, message="success", data=...)统一返回结构
所有 SDK 及网关接口均返回统一的封装对象(HTTP 状态码固定为 200):
成功返回
json
{
"code": 200,
"message": "success",
"data": {
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400
}
}code: 业务状态码,200表示操作成功。message: 描述提示信息。data: 业务负载,类型对应各语言 SDK 中的响应模型。
失败统一返回结构 (HTTP 200)
json
{
"code": 10002,
"error_code": "INVALID_API_KEY",
"message": "访问密钥无效或已过期",
"data": null,
"call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}code: 平台统一数字状态码。非200表示调用失败。error_code: 英文机器识别大写常量(如INVALID_API_KEY、TOKEN_EXPIRED)。message: 错误提示文案。data: 失败时固定为null。call_id: 单次请求唯一排查标识(以call_开头),与响应头X-QJ-Request-ID一致。系统故障时固定返回50001+SERVICE_BUSY(服务繁忙)。