@habitaxx/cli 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# 栖界开放平台 CLI
+
+`@habitaxx/cli` 使用设备授权流程连接栖界开放平台。用户在浏览器中登录并选择项目、权限和能力，CLI 随后将该域的独立 API Key 安全保存到本机。
+
+## 安装
+
+全局安装（或本地运行）：
+
+```bash
+npm install -g @habitaxx/cli
+```
+
+本地仓库调试可直接执行：
+
+```bash
+node sdk/cli/bin/habitaxx.js --help
+```
+
+运行环境要求 Node.js 18.17 或更高版本。
+
+## 登录与设备授权
+
+```bash
+habitaxx auth init
+```
+
+命令执行步骤：
+
+1. 创建一个 10 分钟有效的设备授权请求；
+2. 自动打开浏览器引导授权：`https://platform.habitaxx.com/auth?code=XXXX-XXXX`；
+3. 等待用户在开放平台页面审批；
+4. 将该域的授权凭据安全写入本地 `~/.habitaxx/auth.json`。
+
+API Key 绝不会显示在浏览器或终端输出中。本地凭据目录权限严格限定为 `0700`，文件权限为 `0600`。
+
+精细化限制授权范围示例（按能力标识申请）：
+
+```bash
+habitaxx auth init \
+  --scope capabilities:read,tasks:write \
+  --ability <capability-key>
+```
+
+## 查看与管理授权状态
+
+```bash
+# 查看当前域授权信息
+habitaxx auth status
+
+# 在线向网关验证凭据是否有效
+habitaxx auth status --check
+
+# 以安全脱敏 JSON 输出
+habitaxx auth status --json
+
+# 退出当前域登录（删除本地凭据）
+habitaxx auth logout
+
+# 清空全部域的本地登录信息
+habitaxx auth logout --all
+```
+
+`auth logout` 仅清理本地保存的凭据，不会直接撤销开放平台远端的 API Key。若凭据遗失或弃用，请前往开放平台控制台进行吊销。
+
+## 调用平台能力
+
+CLI 自动在内存中完成 API Key 到短效 Access Token 的置换，请求网关时统一携带 Bearer Token 并注入 `X-Client-Type: open_platform` 请求头。
+
+### 1. 通用接口请求 (`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":"狗狗食欲不振并且嗜睡"}'
+
+# 鸟类多模态识别 (Multipart 表单)
+habitaxx request POST /bird/detect \
+  --form file=@/path/to/bird.jpg
+```
+
+### 2. 鸟类识别快捷命令 (`habitaxx bird detect`)
+
+```bash
+habitaxx bird detect --file /path/to/bird.jpg
+```
+
+### 3. 智能项圈 IMU 行为预测 (`habitaxx imu predict`)
+
+```bash
+# 传入样本数据进行预测
+habitaxx imu predict --data @samples.json --top-k 5
+
+# 指定设备标识进行预测
+habitaxx imu predict --data @samples.json --device 001
+```
+
+`samples.json` 数据结构示例：
+```json
+{
+  "samples": [
+    [-0.32, -0.49, -0.65, -32.21, -21.96, 1.33],
+    [-0.31, -0.48, -0.64, -31.50, -21.20, 1.25]
+  ],
+  "top_k": 5
+}
+```
+
+## 环境变量说明
+
+| 环境变量 | 默认值 | 说明 |
+| :--- | :--- | :--- |
+| `HABITAXX_PLATFORM_URL` | `https://platform.habitaxx.com` | 控制台前端页面地址 |
+| `HABITAXX_PLATFORM_API_URL` | `<platform-url>/api/v1` | 控制面后端 API 接口地址 |
+| `HABITAXX_API_BASE_URL` | `https://open-api.habitaxx.com/v1` | 开放能力网关基础路径 |
+| `HABITAXX_AUTH_FILE` | `~/.habitaxx/auth.json` | 本地凭据存储路径 |
+
+## Agent Skill 集成
+
+官方配套的 Agent Skill 提供了公网和本地两种安装接入方式：
+
+```bash
+# 方式一：公网在线安装（推荐）
+npx skills add habitaxx/skills --skill habitaxx-skill
+# 或通过 npm 在线引入
+npx skills add @habitaxx/skill
+
+# 方式二：本地仓库目录安装
+npx skills add ./sdk/habitaxx-skill
+```
+
+该 Skill 借助 CLI 统一调度平台能力，无需让 AI Agent 直接接触原始密钥凭据，确保运行安全。

package/bin/habitaxx.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.js'
+
+main(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  const safe = message.replace(/qj_live_[A-Za-z0-9_-]+/g, '[REDACTED_API_KEY]')
+    .replace(/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED_TOKEN]')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+  console.error(`错误：${safe}`)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@habitaxx/cli",
+  "version": "0.1.0",
+  "description": "栖界开放平台官方命令行工具",
+  "type": "module",
+  "bin": {
+    "habitaxx": "./bin/habitaxx.js"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node --check bin/habitaxx.js && node --check src/auth-store.js && node --check src/browser.js && node --check src/cli.js && node --check src/http.js"
+  },
+  "keywords": [
+    "habitaxx",
+    "qijie",
+    "cli",
+    "open-platform",
+    "ai",
+    "device-authorization"
+  ],
+  "author": "Habitaxx",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/habitaxx/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/habitaxx/cli/issues"
+  },
+  "homepage": "https://github.com/habitaxx/cli#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/auth-store.js

@@ -0,0 +1,165 @@
+import { randomUUID } from 'node:crypto'
+import { constants as fsConstants } from 'node:fs'
+import { access, chmod, lstat, mkdir, readFile, rename, rm, open } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+const FILE_VERSION = 1
+
+export function authFilePath() {
+  const override = process.env.HABITAXX_AUTH_FILE?.trim()
+  const file = override ? path.resolve(override) : path.join(os.homedir(), '.habitaxx', 'auth.json')
+  if (path.basename(path.dirname(file)) !== '.habitaxx') {
+    throw new Error('HABITAXX_AUTH_FILE 必须位于独立的 .habitaxx 目录内，避免修改其他目录权限')
+  }
+  return file
+}
+
+export function domainKey(apiBaseUrl) {
+  const url = new URL(apiBaseUrl)
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('API 地址只支持 http 或 https')
+  }
+  return url.origin
+}
+
+function emptyAuthStore(deviceId = randomUUID()) {
+  return {
+    version: FILE_VERSION,
+    device_id: deviceId,
+    current: null,
+    domains: {},
+  }
+}
+
+async function rejectSymlink(target, kind) {
+  try {
+    const stat = await lstat(target)
+    if (stat.isSymbolicLink()) throw new Error(`${kind}不能是符号链接：${target}`)
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+}
+
+export async function loadAuthStore({ allowMissing = true } = {}) {
+  const file = authFilePath()
+  await rejectSymlink(path.dirname(file), '授权目录')
+  await rejectSymlink(file, '授权文件')
+
+  let raw
+  try {
+    raw = await readFile(file, 'utf8')
+  } catch (error) {
+    if (allowMissing && error?.code === 'ENOENT') return emptyAuthStore()
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(`授权文件格式损坏，请备份后删除并重新授权：${file}`)
+  }
+  if (parsed?.version !== FILE_VERSION || typeof parsed?.domains !== 'object' || !parsed.domains || Array.isArray(parsed.domains)) {
+    throw new Error(`不支持的授权文件格式，请升级 CLI 或重新授权：${file}`)
+  }
+  for (const [domain, item] of Object.entries(parsed.domains)) {
+    if (!item || typeof item.api_key !== 'string' || !item.api_key
+        || typeof item.project_no !== 'string' || typeof item.user_id !== 'string'
+        || !Array.isArray(item.capabilities) || !Array.isArray(item.ability_keys)
+        || domainKey(item.api_base_url) !== domain) {
+      throw new Error('授权文件包含无效的域信息，请备份后重新授权')
+    }
+  }
+  if (typeof parsed.device_id !== 'string' || !parsed.device_id) parsed.device_id = randomUUID()
+  return parsed
+}
+
+export async function saveAuthStore(store) {
+  const file = authFilePath()
+  const directory = path.dirname(file)
+  await rejectSymlink(directory, '授权目录')
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await chmod(directory, 0o700)
+  await rejectSymlink(file, '授权文件')
+
+  const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`
+  let handle
+  try {
+    handle = await open(temporary, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600)
+    await handle.writeFile(`${JSON.stringify(store, null, 2)}\n`, 'utf8')
+    await handle.sync()
+    await handle.close()
+    handle = undefined
+    await rename(temporary, file)
+    await chmod(file, 0o600)
+  } finally {
+    await handle?.close().catch(() => {})
+    await rm(temporary, { force: true }).catch(() => {})
+  }
+  return file
+}
+
+// 短期文件锁只覆盖读-改-写，不在等待浏览器授权期间持有。
+export async function updateAuthStore(update) {
+  const file = authFilePath()
+  const directory = path.dirname(file)
+  await rejectSymlink(directory, '授权目录')
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await chmod(directory, 0o700)
+  const lockPath = `${file}.lock`
+  let lock
+  try {
+    lock = await open(lockPath, 'wx', 0o600)
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new Error(`其他 CLI 正在更新授权文件；稍后重试。若进程异常退出，确认没有 CLI 运行后删除 ${lockPath}`)
+    }
+    throw error
+  }
+  try {
+    const store = await loadAuthStore()
+    await update(store)
+    await saveAuthStore(store)
+    return store
+  } finally {
+    await lock.close()
+    await rm(lockPath, { force: true })
+  }
+}
+
+export function currentAuthorization(store, requestedDomain) {
+  const key = requestedDomain || store.current
+  if (!key || !store.domains[key]) {
+    throw new Error('当前域尚未授权，请先运行 habitaxx auth init')
+  }
+  return { domain: key, authorization: store.domains[key] }
+}
+
+export function publicAuthorization(domain, authorization) {
+  return {
+    domain,
+    platform_url: authorization.platform_url,
+    platform_api_url: authorization.platform_api_url,
+    api_base_url: authorization.api_base_url,
+    project_id: authorization.project_id,
+    project_no: authorization.project_no,
+    project_name: authorization.project_name,
+    user_id: authorization.user_id,
+    api_key_id: authorization.api_key_id,
+    api_key_name: authorization.api_key_name,
+    api_key_prefix: authorization.api_key_prefix,
+    capabilities: authorization.capabilities,
+    ability_keys: authorization.ability_keys,
+    authorized_at: authorization.authorized_at,
+  }
+}
+
+export async function authFileExists() {
+  try {
+    await access(authFilePath(), fsConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/browser.js

@@ -0,0 +1,14 @@
+import { spawn } from 'node:child_process'
+
+export async function openBrowser(url) {
+  const [command, args] = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['rundll32.exe', ['url.dll,FileProtocolHandler', url]]
+      : ['xdg-open', [url]]
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: true })
+    child.once('error', () => resolve(false))
+    child.once('spawn', () => { child.unref(); resolve(true) })
+  })
+}

package/src/cli.js

@@ -0,0 +1,453 @@
+import os from 'node:os'
+
+import {
+  authFileExists,
+  authFilePath,
+  currentAuthorization,
+  domainKey,
+  loadAuthStore,
+  publicAuthorization,
+  updateAuthStore,
+} from './auth-store.js'
+import { openBrowser } from './browser.js'
+import {
+  HabitaxxHttpError,
+  buildMultipart,
+  callOpenApi,
+  exchangeRuntimeToken,
+  parseDataArgument,
+  requestJson,
+  validateBaseUrl,
+} from './http.js'
+
+const VERSION = '0.1.0'
+const DEFAULT_PLATFORM_URL = 'https://platform.habitaxx.com'
+const DEFAULT_API_BASE_URL = 'https://open-api.habitaxx.com/v1'
+const DEFAULT_SCOPES = ['capabilities:read', 'tasks:write']
+
+const HELP = `栖界开放平台 CLI
+
+用法：
+  habitaxx auth init [选项]             登录并授权当前设备
+  habitaxx auth status [选项]           查看本地授权状态
+  habitaxx auth logout [选项]           删除本地授权
+  habitaxx request <方法> <路径> [选项] 通过 Runtime 调用开放 API
+  habitaxx bird detect --file <图片>    调用鸟类识别能力
+  habitaxx imu predict [选项]           调用智能项圈 IMU 行为预测能力
+
+授权选项：
+  --platform-url <url>      授权页面地址（默认 ${DEFAULT_PLATFORM_URL}）
+  --platform-api-url <url>  控制面 API 地址（默认 <platform-url>/api/v1）
+  --api-base-url <url>      开放 API 地址（默认 ${DEFAULT_API_BASE_URL}）
+  --client-name <name>      授权页显示的客户端名称
+  --device-name <name>      授权页显示的设备名称
+  --scope <scope[,scope]>   申请权限，可重复
+  --ability <key[,key]>     申请能力，可重复；不传表示全部能力
+  --no-open                 不自动打开浏览器
+
+通用授权选择：
+  --domain <origin>         使用 auth.json 中指定域，例如 https://open-api.habitaxx.com
+  --json                    输出不含秘密的 JSON
+  --check                   auth status 在线校验凭据（默认仅检查本地文件）
+  --all                     auth logout 删除全部域的本地凭据
+
+request 选项：
+  --data '<json>'           JSON 请求体；也支持 --data @payload.json
+  --form 'name=value'       multipart 字段，可重复；文件使用 name=@/path/file
+  --header 'Name: value'    自定义请求头，可重复
+  --output <file>           将响应体保存到文件
+
+imu predict 选项：
+  --data '<json>'           包含 samples 数组及可选 top_k 的数据；支持 @file.json
+  --device <device_id>      可选，按设备标识预测
+  --top-k <num>             可选，返回置信度前 K 项（默认 5）
+
+安全说明：
+  API Key 仅保存在 ~/.habitaxx/auth.json（目录 0700，文件 0600）。
+  Runtime Access Token 仅在单次命令内存中使用，不写入磁盘，也不会放进 URL。
+`
+
+function parseArgs(args, { values = [], booleans = [] } = {}) {
+  const valueOptions = new Set(values)
+  const booleanOptions = new Set(booleans)
+  const options = new Map()
+  const positionals = []
+
+  for (let index = 0; index < args.length; index += 1) {
+    const item = args[index]
+    if (item === '--') {
+      positionals.push(...args.slice(index + 1))
+      break
+    }
+    if (!item.startsWith('--')) {
+      positionals.push(item)
+      continue
+    }
+
+    const equals = item.indexOf('=')
+    const name = equals > 0 ? item.slice(0, equals) : item
+    if (booleanOptions.has(name)) {
+      if (equals > 0) throw new Error(`${name} 不接受参数值`)
+      options.set(name, true)
+      continue
+    }
+    if (!valueOptions.has(name)) throw new Error(`未知选项：${name}`)
+
+    const value = equals > 0 ? item.slice(equals + 1) : args[++index]
+    if (value === undefined || value.startsWith('--')) throw new Error(`${name} 缺少参数值`)
+    const existing = options.get(name)
+    options.set(name, existing === undefined ? value : [...asArray(existing), value])
+  }
+
+  return { options, positionals }
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [value]
+}
+
+function listOption(options, name, fallback = []) {
+  if (!options.has(name)) return fallback
+  const values = asArray(options.get(name))
+    .flatMap((value) => String(value).split(','))
+    .map((value) => value.trim())
+  if (values.some((value) => !value)) throw new Error(`${name} 不能包含空权限或空能力标识`)
+  return [...new Set(values)]
+}
+
+function stringOption(options, name, fallback) {
+  const value = options.get(name)
+  if (Array.isArray(value)) throw new Error(`${name} 只能指定一次`)
+  return value === undefined ? fallback : String(value).trim()
+}
+
+function normalizeHttpUrl(value, optionName) {
+  try {
+    return validateBaseUrl(value)
+  } catch {
+    throw new Error(`${optionName} 必须是无凭据、query、fragment 的 HTTPS 地址（仅 loopback 允许 HTTP）`)
+  }
+}
+
+function selectedDomain(options) {
+  const explicitDomain = stringOption(options, '--domain', '')
+  if (explicitDomain) return domainKey(normalizeHttpUrl(explicitDomain, '--domain'))
+  const apiBaseUrl = stringOption(options, '--api-base-url', '')
+  return apiBaseUrl ? domainKey(normalizeHttpUrl(apiBaseUrl, '--api-base-url')) : undefined
+}
+
+function sleep(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason)
+    const done = () => { signal?.removeEventListener('abort', abort); resolve() }
+    const timer = setTimeout(done, milliseconds)
+    const abort = () => { clearTimeout(timer); reject(signal.reason) }
+    signal?.addEventListener('abort', abort, { once: true })
+  })
+}
+
+async function authInit(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: [
+      '--platform-url',
+      '--platform-api-url',
+      '--api-base-url',
+      '--client-name',
+      '--device-name',
+      '--scope',
+      '--ability',
+    ],
+    booleans: ['--no-open'],
+  })
+  if (positionals.length) throw new Error(`无法识别的参数：${positionals.join(' ')}`)
+
+  const platformUrl = normalizeHttpUrl(
+    stringOption(options, '--platform-url', process.env.HABITAXX_PLATFORM_URL || DEFAULT_PLATFORM_URL),
+    '--platform-url',
+  )
+  const defaultApiUrl = `${platformUrl}/api/v1`
+  const platformApiUrl = normalizeHttpUrl(
+    stringOption(options, '--platform-api-url', process.env.HABITAXX_PLATFORM_API_URL || defaultApiUrl),
+    '--platform-api-url',
+  )
+  const apiBaseUrl = normalizeHttpUrl(
+    stringOption(options, '--api-base-url', process.env.HABITAXX_API_BASE_URL || DEFAULT_API_BASE_URL),
+    '--api-base-url',
+  )
+
+  const requestedDomain = domainKey(apiBaseUrl)
+  const existingStore = await loadAuthStore()
+  if (existingStore.domains[requestedDomain]) {
+    const existing = existingStore.domains[requestedDomain]
+    throw new Error(
+      `域 ${requestedDomain} 已存在授权（项目：${existing.project_name || existing.project_no}）。`
+      + `若需重新授权，请先运行 habitaxx auth logout --domain ${requestedDomain}。`,
+    )
+  }
+
+  const clientName = stringOption(options, '--client-name', 'Habitaxx CLI')
+  const deviceName = stringOption(options, '--device-name', os.hostname() || 'developer-device')
+  const scopes = listOption(options, '--scope', DEFAULT_SCOPES)
+  const abilities = listOption(options, '--ability', [])
+
+  const initResult = await requestJson(`${platformApiUrl}/device-auth/requests`, {
+    method: 'POST',
+    body: {
+      client_name: clientName,
+      device_name: deviceName,
+      requested_scopes: scopes,
+      requested_abilities: abilities,
+      api_base_url: apiBaseUrl,
+    },
+  })
+
+  const { device_code, user_code, verification_uri_complete, expires_in, interval = 5 } = initResult
+  console.log(`\n请在浏览器中完成设备授权：\n  ${verification_uri_complete}\n`)
+  console.log(`用户代码：${user_code}`)
+  console.log(`有效时间：${Math.floor(expires_in / 60)} 分钟\n`)
+
+  if (!options.has('--no-open')) {
+    try {
+      await openBrowser(verification_uri_complete)
+      console.log('已尝试打开默认浏览器。如未打开，请手动复制上述链接。')
+    } catch {
+      console.log('未能自动打开浏览器，请手动复制上述链接完成授权。')
+    }
+  }
+
+  console.log('等待授权中（按 Ctrl+C 可取消）...')
+  const pollUrl = `${platformApiUrl}/device-auth/tokens`
+  const pollIntervalMs = Math.max(interval, 2) * 1000
+  const deadline = Date.now() + expires_in * 1000
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs)
+    try {
+      const pollResult = await requestJson(pollUrl, {
+        method: 'POST',
+        body: { device_code },
+      })
+      if (pollResult && pollResult.api_key) {
+        const stored = {
+          domain: requestedDomain,
+          api_base_url: apiBaseUrl,
+          api_key: pollResult.api_key,
+          api_key_prefix: pollResult.api_key_prefix || `${pollResult.api_key.slice(0, 12)}...`,
+          project_id: pollResult.project_id,
+          project_no: pollResult.project_no,
+          project_name: pollResult.project_name,
+          user_id: pollResult.user_id,
+          capabilities: pollResult.capabilities || scopes,
+          ability_keys: pollResult.ability_keys || abilities,
+          authorized_at: new Date().toISOString(),
+        }
+        await updateAuthStore((store) => {
+          store.domains[requestedDomain] = stored
+          store.current = requestedDomain
+        })
+        console.log(`\n授权成功！项目：${stored.project_name}（${stored.project_no}）`)
+        console.log(`凭据已安全保存至：${authFilePath()}`)
+        return
+      }
+    } catch (err) {
+      if (err instanceof HabitaxxHttpError) {
+        if (err.code === 'AUTHORIZATION_PENDING') continue
+        if (err.code === 'SLOW_DOWN') {
+          await sleep(pollIntervalMs)
+          continue
+        }
+      }
+      throw err
+    }
+  }
+  throw new Error('授权超时，请重新执行 habitaxx auth init')
+}
+
+async function authStatus(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: ['--domain', '--api-base-url'],
+    booleans: ['--json', '--check'],
+  })
+  if (positionals.length) throw new Error(`无法识别的参数：${positionals.join(' ')}`)
+  const store = await loadAuthStore()
+  const resolved = currentAuthorization(store, selectedDomain(options))
+
+  let valid = null
+  if (options.has('--check')) {
+    try {
+      await exchangeRuntimeToken(resolved.authorization)
+      valid = true
+    } catch (err) {
+      valid = false
+      if (!options.has('--json')) {
+        console.warn(`警告：远程校验失败：${err.message}`)
+      }
+    }
+  }
+
+  const safe = publicAuthorization(resolved.authorization)
+  if (options.has('--json')) {
+    console.log(JSON.stringify({ ...safe, valid }, null, 2))
+    return
+  }
+
+  console.log(`当前域：${safe.domain}`)
+  console.log(`API 地址：${safe.api_base_url}`)
+  console.log(`项目：${safe.project_name} (${safe.project_no})`)
+  console.log(`API Key：${safe.api_key_prefix}`)
+  console.log(`权限：${safe.capabilities.length ? safe.capabilities.join(', ') : '无'}`)
+  console.log(`能力：${safe.ability_keys.length ? safe.ability_keys.join(', ') : '全部'}`)
+  console.log(`授权时间：${safe.authorized_at}`)
+  console.log(`凭据文件：${authFilePath()}`)
+  if (valid !== null) console.log(`远程校验：${valid ? '有效' : '失败'}`)
+}
+
+async function authLogout(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: ['--domain', '--api-base-url'],
+    booleans: ['--all'],
+  })
+  if (positionals.length) throw new Error(`无法识别的参数：${positionals.join(' ')}`)
+  if (!(await authFileExists())) {
+    console.log('本地没有授权信息。')
+    return
+  }
+  let removedDomain
+  await updateAuthStore((store) => {
+    if (options.has('--all')) {
+      store.domains = {}
+      store.current = null
+    } else {
+      const selected = currentAuthorization(store, selectedDomain(options))
+      removedDomain = selected.domain
+      delete store.domains[selected.domain]
+      if (store.current === selected.domain) store.current = Object.keys(store.domains)[0] || null
+    }
+  })
+  console.log(`已删除${removedDomain || '全部域'}的本地凭据。远程 API Key 未被撤销，请在开放平台中撤销。`)
+}
+
+function parseHeaders(values) {
+  const headers = {}
+  for (const value of values) {
+    const separator = value.indexOf(':')
+    if (separator <= 0) throw new Error(`无效的 --header 参数：${value}`)
+    const name = value.slice(0, separator).trim()
+    const headerValue = value.slice(separator + 1).trim()
+    if (/^(authorization|x-api-key|host|proxy-authorization|cookie)$/i.test(name)) {
+      throw new Error(`不允许通过 --header 覆盖 ${name}，认证由 CLI 安全管理`)
+    }
+    headers[name] = headerValue
+  }
+  return headers
+}
+
+async function resolveAuthorization(options) {
+  const store = await loadAuthStore()
+  return currentAuthorization(store, selectedDomain(options)).authorization
+}
+
+function printResponse(result) {
+  if (result.output) {
+    console.log(`响应已保存：${result.output}`)
+    return
+  }
+  if (typeof result.body === 'string') {
+    process.stdout.write(result.body.endsWith('\n') ? result.body : `${result.body}\n`)
+    return
+  }
+  console.log(JSON.stringify(result.body, null, 2))
+}
+
+async function requestCommand(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: ['--domain', '--api-base-url', '--data', '--form', '--header', '--output'],
+  })
+  if (positionals.length !== 2) throw new Error('用法：habitaxx request <方法> <路径> [选项]')
+  if (options.has('--data') && options.has('--form')) throw new Error('--data 与 --form 不能同时使用')
+
+  const [method, requestPath] = positionals
+  const headers = parseHeaders(options.has('--header') ? asArray(options.get('--header')) : [])
+  let body
+  if (options.has('--data')) {
+    const data = await parseDataArgument(stringOption(options, '--data', ''))
+    headers['Content-Type'] = 'application/json'
+    body = JSON.stringify(data)
+  } else if (options.has('--form')) {
+    body = await buildMultipart(asArray(options.get('--form')).map(String))
+  }
+
+  const authorization = await resolveAuthorization(options)
+  const result = await callOpenApi(authorization, requestPath, {
+    method,
+    headers,
+    body,
+    output: stringOption(options, '--output', ''),
+  })
+  printResponse(result)
+}
+
+async function birdDetect(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: ['--file', '--domain', '--api-base-url', '--output'],
+  })
+  if (positionals.length) throw new Error(`无法识别的参数：${positionals.join(' ')}`)
+  const filePath = stringOption(options, '--file', '')
+  if (!filePath) throw new Error('缺少 --file <图片路径>')
+
+  const form = await buildMultipart([`file=@${filePath}`])
+  const authorization = await resolveAuthorization(options)
+  const result = await callOpenApi(authorization, '/bird/detect', {
+    method: 'POST',
+    body: form,
+    output: stringOption(options, '--output', ''),
+  })
+  printResponse(result)
+}
+
+async function imuPredict(args) {
+  const { options, positionals } = parseArgs(args, {
+    values: ['--data', '--device', '--top-k', '--domain', '--api-base-url', '--output'],
+  })
+  if (positionals.length) throw new Error(`无法识别的参数：${positionals.join(' ')}`)
+  const rawData = stringOption(options, '--data', '')
+  if (!rawData) throw new Error('缺少 --data 参数（支持 JSON 字符串或 @文件路径）')
+
+  const payload = await parseDataArgument(rawData)
+  if (options.has('--top-k')) {
+    payload.top_k = Number(stringOption(options, '--top-k', '5'))
+  }
+
+  const deviceId = stringOption(options, '--device', '')
+  const path = deviceId ? `/imu/predict/${encodeURIComponent(deviceId)}` : '/imu/predict'
+
+  const authorization = await resolveAuthorization(options)
+  const result = await callOpenApi(authorization, path, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    output: stringOption(options, '--output', ''),
+  })
+  printResponse(result)
+}
+
+export async function main(args) {
+  if (args.includes('--help') || args.includes('-h') || !args.length || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    console.log(HELP)
+    return
+  }
+  if (args[0] === '--version' || args[0] === '-v') {
+    console.log(VERSION)
+    return
+  }
+
+  const [command, subcommand, ...rest] = args
+  if (command === 'auth' && subcommand === 'init') return authInit(rest)
+  if (command === 'auth' && subcommand === 'status') return authStatus(rest)
+  if (command === 'auth' && subcommand === 'logout') return authLogout(rest)
+  if (command === 'request') return requestCommand([subcommand, ...rest].filter((value) => value !== undefined))
+  if (command === 'bird' && subcommand === 'detect') return birdDetect(rest)
+  if (command === 'imu' && subcommand === 'predict') return imuPredict(rest)
+
+  throw new Error(`未知命令：${args.join(' ')}\n\n${HELP}`)
+}

package/src/http.js

@@ -0,0 +1,281 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+export function validateBaseUrl(value) {
+  const url = new URL(value)
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+  if (url.username || url.password || url.search || url.hash
+      || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) {
+    throw new Error('地址必须使用 HTTPS（本地 loopback 可用 HTTP），且不能含凭据、query 或 fragment')
+  }
+  return trimTrailingSlash(url.href)
+}
+
+function connectionError(error, url, method) {
+  // 只展示公开地址和已知错误码，不输出请求头、请求体或 query 中的凭据。
+  const target = new URL(url)
+  const codes = [error?.code, error?.cause?.code,
+    ...(error?.cause?.errors || []).map((item) => item?.code)]
+  const reasons = {
+    ECONNREFUSED: '连接被拒绝，请确认目标服务已启动，并检查监听地址和端口',
+    ENOTFOUND: '域名解析失败，请检查地址和 DNS',
+    EAI_AGAIN: '域名解析暂时失败，请检查网络和 DNS',
+    ETIMEDOUT: '连接超时，请检查网络、防火墙和服务状态',
+    UND_ERR_CONNECT_TIMEOUT: '连接超时，请检查网络、防火墙和服务状态',
+    UND_ERR_HEADERS_TIMEOUT: '等待响应头超时',
+    UND_ERR_BODY_TIMEOUT: '读取响应体超时',
+    ECONNRESET: '连接被重置，请检查服务或代理日志',
+    UND_ERR_SOCKET: '连接意外关闭，请检查服务或代理日志',
+    CERT_HAS_EXPIRED: 'TLS 证书已过期，请检查服务器证书',
+    DEPTH_ZERO_SELF_SIGNED_CERT: 'TLS 证书不受信任，请检查服务器证书',
+    EPERM: '当前进程无权访问目标地址，请检查系统或沙箱网络权限',
+    EACCES: '当前进程无权访问目标地址，请检查系统或沙箱网络权限',
+  }
+  const code = codes.find((value) => Object.hasOwn(reasons, value))
+  const reason = code ? `${reasons[code]}（${code}）`
+    : '连接失败，请检查网络、TLS 证书或代理；CLI 不接受 HTTP 重定向'
+  return new Error(`${method || 'GET'} ${target.origin}${target.pathname}：${reason}`, { cause: error })
+}
+
+async function boundedFetch(url, options, timeoutMs = 30000) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(options.signal?.reason)
+  if (options.signal?.aborted) abort()
+  options.signal?.addEventListener('abort', abort, { once: true })
+  const timer = setTimeout(() => controller.abort(new Error('请求超时')), timeoutMs)
+  try {
+    // 禁止重定向，尤其防止 X-API-Key 或设备凭证被带到其他域。
+    const response = await fetch(url, { ...options, redirect: 'error', signal: controller.signal })
+    // 在超时范围内读取响应体，而非只等待响应头。
+    const bytes = await response.arrayBuffer()
+    return new Response([204, 205, 304].includes(response.status) ? null : bytes, {
+      status: response.status, headers: response.headers,
+    })
+  } catch (error) {
+    if (controller.signal.aborted) {
+      if (options.signal?.aborted) throw options.signal.reason || new Error('请求已取消')
+      const target = new URL(url)
+      throw new Error(`${options.method || 'GET'} ${target.origin}${target.pathname}：请求超时（${timeoutMs / 1000} 秒）`)
+    }
+    throw connectionError(error, url, options.method)
+  } finally {
+    clearTimeout(timer)
+    options.signal?.removeEventListener('abort', abort)
+  }
+}
+
+export class HabitaxxHttpError extends Error {
+  constructor(message, { status, code, errorCode, callId, body } = {}) {
+    super(message)
+    this.name = 'HabitaxxHttpError'
+    this.status = status
+    this.code = code
+    this.errorCode = errorCode
+    this.callId = callId
+    this.body = body
+  }
+}
+
+export function trimTrailingSlash(value) {
+  return value.trim().replace(/\/+$/, '')
+}
+
+export function unwrapPayload(value) {
+  if (
+    value
+    && typeof value === 'object'
+    && Object.hasOwn(value, 'code')
+    && Object.hasOwn(value, 'message')
+    && Object.hasOwn(value, 'data')
+  ) {
+    if (value.code !== 200 && value.code !== 0) {
+      const msg = value.message || `业务请求失败（代码 ${value.code}）`
+      throw new HabitaxxHttpError(msg, {
+        status: 200,
+        code: value.code,
+        errorCode: value.error_code,
+        callId: value.call_id,
+        body: value,
+      })
+    }
+    return value.data
+  }
+  return value
+}
+
+async function responseBody(response) {
+  const contentType = response.headers.get('content-type') || ''
+  if (contentType.includes('json')) {
+    try {
+      return await response.json()
+    } catch {
+      return null
+    }
+  }
+  return response.text()
+}
+
+function errorMessage(response, body) {
+  if (body && typeof body === 'object') {
+    const message = body.message || body.detail || body.error
+    if (typeof message === 'string' && message.trim()) return message.trim()
+  }
+  if (typeof body === 'string' && body.trim()) return body.trim().slice(0, 300)
+  return `请求失败（HTTP ${response.status}）`
+}
+
+export async function requestJson(url, { method = 'GET', headers = {}, body, signal } = {}) {
+  const response = await boundedFetch(url, {
+    method,
+    headers: {
+      Accept: 'application/json',
+      'X-Client-Type': 'open_platform',
+      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      ...headers,
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal,
+  })
+  const parsed = await responseBody(response)
+  if (!response.ok) {
+    throw new HabitaxxHttpError(errorMessage(response, parsed), {
+      status: response.status,
+      code: parsed && typeof parsed === 'object' ? parsed.code : undefined,
+      errorCode: parsed && typeof parsed === 'object' ? parsed.error_code : undefined,
+      callId: parsed && typeof parsed === 'object' ? parsed.call_id : undefined,
+      body: parsed,
+    })
+  }
+  return unwrapPayload(parsed)
+}
+
+export async function exchangeRuntimeToken(authorization, { signal } = {}) {
+  const result = await requestJson(`${validateBaseUrl(authorization.api_base_url)}/auth/token`, {
+    method: 'POST',
+    headers: { 'X-API-Key': authorization.api_key },
+    body: {
+      project_no: authorization.project_no,
+      user_id: authorization.user_id,
+    },
+    signal,
+  })
+  if (!result?.access_token) throw new Error('平台未返回有效的 Runtime Access Token')
+  return result
+}
+
+function safeApiUrl(apiBaseUrl, requestPath) {
+  if (!requestPath || /^[a-z][a-z\d+.-]*:/i.test(requestPath) || requestPath.startsWith('//')) {
+    throw new Error('请求路径必须是相对开放 API 根地址的路径，例如 /bird/detect')
+  }
+  const base = new URL(`${validateBaseUrl(apiBaseUrl)}/`)
+  const target = new URL(requestPath.replace(/^\/+/, ''), base)
+  if (target.origin !== base.origin || !target.pathname.startsWith(base.pathname) || target.hash) {
+    throw new Error('请求路径不能跳出开放 API 根地址')
+  }
+  return target.href
+}
+
+export async function callOpenApi(
+  authorization,
+  requestPath,
+  { method = 'GET', headers = {}, body, output, signal } = {},
+) {
+  const url = safeApiUrl(authorization.api_base_url, requestPath)
+  const token = await exchangeRuntimeToken(authorization, { signal })
+  const response = await boundedFetch(url, {
+    method: method.toUpperCase(),
+    headers: {
+      Accept: 'application/json',
+      'X-Client-Type': 'open_platform',
+      ...headers,
+      Authorization: `Bearer ${token.access_token}`,
+    },
+    body,
+    signal,
+  }, 120000)
+
+  const parsed = await responseBody(response)
+  if (!response.ok) {
+    throw new HabitaxxHttpError(errorMessage(response, parsed), {
+      status: response.status,
+      code: parsed && typeof parsed === 'object' ? parsed.code : undefined,
+      errorCode: parsed && typeof parsed === 'object' ? parsed.error_code : undefined,
+      callId: parsed && typeof parsed === 'object' ? parsed.call_id : undefined,
+      body: parsed,
+    })
+  }
+
+  // 检查业务层错误（统一 200 返回中 code != 200）
+  if (parsed && typeof parsed === 'object' && Object.hasOwn(parsed, 'code') && parsed.code !== 200 && parsed.code !== 0) {
+    const msg = parsed.message || `业务请求失败（代码 ${parsed.code}）`
+    throw new HabitaxxHttpError(msg, {
+      status: response.status,
+      code: parsed.code,
+      errorCode: parsed.error_code,
+      callId: parsed.call_id,
+      body: parsed,
+    })
+  }
+
+  if (output) {
+    const target = path.resolve(output)
+    if (Buffer.isBuffer(parsed) || typeof parsed === 'string') {
+      await writeFile(target, parsed)
+    } else {
+      await writeFile(target, JSON.stringify(parsed, null, 2))
+    }
+    return { output: target, status: response.status }
+  }
+
+  return {
+    status: response.status,
+    contentType: response.headers.get('content-type') || '',
+    body: parsed,
+  }
+}
+
+export async function parseDataArgument(value) {
+  const raw = value.startsWith('@')
+    ? await readFile(path.resolve(value.slice(1)), 'utf8')
+    : value
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new Error('--data 必须是有效 JSON，或使用 @文件路径')
+  }
+}
+
+const FILE_CONTENT_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/vnd.microsoft.icon',
+}
+
+export async function buildMultipart(entries) {
+  const form = new FormData()
+  for (const entry of entries) {
+    const separator = entry.indexOf('=')
+    if (separator <= 0) throw new Error(`无效的 --form 参数：${entry}`)
+    const name = entry.slice(0, separator).trim()
+    const value = entry.slice(separator + 1)
+    if (!name) throw new Error(`无效的 --form 参数：${entry}`)
+    if (value.startsWith('@')) {
+      const filePath = path.resolve(value.slice(1))
+      const bytes = await readFile(filePath)
+      // 文件部分需要自己的 MIME 类型；外层 multipart boundary 仍由 fetch 生成。
+      const type = FILE_CONTENT_TYPES[path.extname(filePath).toLowerCase()] || 'application/octet-stream'
+      form.append(name, new Blob([bytes], { type }), path.basename(filePath))
+    } else {
+      form.append(name, value)
+    }
+  }
+  return form
+}