CLI 命令行工具 (@habitaxx/cli)
HabitaXX 官方提供了命令行工具 @habitaxx/cli,支持通过安全设备授权流程(RFC 8628 Device Authorization Flow)连接开放平台。开发者无需将 API Key 直接暴露在配置中,即可通过终端或自动化脚本直接调用平台各项 AI 能力。
1. 安装与运行
全局安装
bash
npm install -g @habitaxx/cli免安装即用 (npx)
bash
npx @habitaxx/cli --help在本地仓库开发调试时,也可直接运行源码:
bash
node sdk/cli/bin/habitaxx.js --help环境要求:Node.js 18.17 或更高版本。
2. 设备授权登录
运行以下命令发起设备登录流程:
bash
habitaxx auth init执行流程:
- CLI 向控制面申请一次性的设备授权码(有效时长 10 分钟);
- 终端打印并在默认浏览器中自动打开授权页面(例如
https://platform.habitaxx.com/auth?code=ABCD-EFGH); - 开发者在浏览器中确认待绑定的项目、权限范围及能力标识;
- 批准后,CLI 自动获取该域专属的访问凭证,并安全存储至本地
~/.habitaxx/auth.json。
限制申请权限与能力
bash
# 仅申请指定能力标识与最小调用权限
habitaxx auth init \
--scope capabilities:read,tasks:write \
--ability imu_behavior_recognition3. 授权状态管理
bash
# 查看本地当前域的授权状态(脱敏显示)
habitaxx auth status
# 在线校验本地保存的凭据是否在网关端有效
habitaxx auth status --check
# 以脱敏的 JSON 格式输出状态(供脚本或 CI/CD 解析)
habitaxx auth status --json
# 登出并清理当前域在本地的凭据
habitaxx auth logout
# 清理本机所有域的本地凭据
habitaxx auth logout --all安全提示:
auth logout仅清理本地存储的凭据文件,若需永久作废该 API Key,请登录开放平台控制台进行吊销操作。
4. 能力调用命令
CLI 内部自动在内存中完成 API Key 到短效 Access Token 的置换,并自动携带 X-Client-Type: open_platform 请求头。
4.1 鸟类多模态识别 (habitaxx bird detect)
bash
habitaxx bird detect --file /path/to/bird.jpg支持参数:
--file <path>:必填,待检测图片的本地绝对或相对路径。--domain <origin>:可选,指定特定的网关域名。--output <file>:可选,将识别结果保存至指定 JSON 文件。
4.2 智能项圈 IMU 行为预测 (habitaxx imu predict)
bash
# 从 JSON 文件中读取时序样本预测
habitaxx imu predict --data @samples.json --top-k 5
# 指定目标设备标识
habitaxx imu predict --data @samples.json --device 001支持参数:
--data <json|@file>:必填,包含 6 轴时序数据数组的 JSON 字符串或@文件路径。--device <device_id>:可选,按特定设备逻辑单元路由。--top-k <num>:可选,返回置信度最高的前 K 种行为,默认5。
4.3 通用 API 请求 (habitaxx request)
支持通过安全网关调用开放平台的任意能力接口:
bash
# 查看开放平台可用能力清单
habitaxx request GET /capabilities
# 发起智能宠物问诊会话
habitaxx request POST /ms-ai-fast/session-records/sessions \
--data '{"module_type":1,"pet_profile_id":78,"content":"狗狗食欲不振并且嗜睡"}'
# 提交带文件的表单请求
habitaxx request POST /bird/detect \
--form file=@/path/to/bird.jpg支持参数:
--data '<json>'或--data @file.json:设置 JSON 请求体。--form 'key=value'或--form 'file=@/path':设置 Multipart 表单字段。--header 'Key: value':追加自定义 HTTP 请求头(不可覆盖认证相关的敏感请求头)。--output <file>:将响应内容直接持久化到指定本地文件。
5. 安全设计规范
- 凭证隔离:本地凭据保存于
~/.habitaxx/auth.json,目录权限为0700,文件权限为0600。 - 短效置换:长效 API Key 仅用于向网关换取 24 小时有效的短效 Access Token,Token 仅留存于进程内存中,不落盘。
- 敏感信息过滤:CLI 输出自动脱敏,禁止在 URL、命令日志或标准输出中输出原始 API Key 或完整 JWT。