# 猎户星空机器人 API 完整参考手册

> 本手册整合猎户星空机器人三层 API 能力（本地 APK/OPK 端 + 服务端 API + NLP 配置），按功能维度整理，供开发人员快速查阅。

---

## 一、API 能力全景

猎户星空机器人提供三层开发接入方式：

| 层级 | 接入方式 | 说明 |
|------|---------|------|
| 本地端 APK | Android 原生 SDK | 使用 Java/Kotlin 开发，直接调用 RobotOS SDK |
| 本地端 OPK | React Native 插件 | 使用 JavaScript 开发，通过 orionos-eve-core 库 |
| 服务端 API | HTTPS RESTful API | 远程控制机器人，域名 openapi.orionstar.com |
| NLP 配置 | 开发者平台配置 | 在 console.orionbase.cn 配置语音交互规则 |

---

## 二、服务端 API（远程控制）

> 基础域名：`https://openapi.orionstar.com`
> 协议：HTTPS RESTful
> 鉴权方式：Bearer Token（通过 appId + appSecret 获取）

### 2.1 鉴权

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/token` | 获取访问令牌（使用 appId + appSecret） |

### 2.2 企业信息

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/enterprise/info` | 获取企业信息 |
| GET | `/enterprise/robot/list` | 获取企业下所有机器人列表 |

### 2.3 企业 SSO 免登录

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/enterprise/sso/create` | 创建 SSO 登录链接 |
| POST | `/enterprise/sso/verify` | 验证 SSO Token |
| POST | `/enterprise/sso/logout` | 注销 SSO 会话 |

### 2.4 企业人员管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/enterprise/person/create` | 创建人员（含人脸图片） |
| POST | `/enterprise/person/update` | 更新人员信息 |
| POST | `/enterprise/person/delete` | 删除人员 |
| POST | `/enterprise/person/search` | 人脸识别搜索 |

### 2.5 企业访客邀约

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/enterprise/visitor/invite` | 创建访客邀约 |
| GET | `/enterprise/visitor/list` | 获取访客列表 |

### 2.6 机器人信息

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/robot/info` | 获取单台机器人详情（SN、在线状态、电量、位置等） |
| GET | `/robot/status` | 获取机器人实时状态 |
| GET | `/robot/list` | 获取机器人列表 |
| POST | `/robot/config/get` | 获取机器人层级配置 |
| POST | `/robot/config/set` | 设置机器人层级配置 |

### 2.7 机器人地图信息

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/robot/map/list` | 获取机器人地图列表 |
| GET | `/robot/map/info` | 获取地图详情（含位置点） |
| GET | `/robot/map/current` | 获取当前使用地图 |

### 2.8 机器人控制（12 个接口）

> 核心远程控制能力，可通过服务端直接操控机器人行为。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/robot/control/navigate` | 远程导航到指定位置点 |
| POST | `/robot/control/navigate/stop` | 停止导航 |
| POST | `/robot/control/tts` | 远程 TTS 语音播报 |
| POST | `/robot/control/tts/stop` | 停止 TTS |
| POST | `/robot/control/voice` | 远程语音指令（模拟 ASR 输入） |
| POST | `/robot/control/mode` | 切换工作模式（接待/巡逻/静默等） |
| POST | `/robot/control/sleep` | 休眠 |
| POST | `/robot/control/wakeup` | 唤醒 |
| POST | `/robot/control/reboot` | 重启 |
| POST | `/robot/control/shutdown` | 关机 |
| POST | `/robot/control/charge` | 回充 |
| POST | `/robot/control/charge/leave` | 脱离充电桩 |

### 2.9 机器人任务

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/robot/task/create` | 创建任务（招财豹/豹小递/豹厂通） |
| GET | `/robot/task/list` | 获取任务列表 |
| GET | `/robot/task/info` | 获取任务详情 |
| POST | `/robot/task/cancel` | 取消任务 |

### 2.10 QA 问答管理

#### 企业级 QA

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/qa/enterprise/create` | 创建企业级 QA |
| POST | `/qa/enterprise/update` | 更新企业级 QA |
| POST | `/qa/enterprise/delete` | 删除企业级 QA |
| GET | `/qa/enterprise/list` | 获取企业级 QA 列表 |

#### 设备级 QA

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/qa/device/create` | 创建设备级 QA |
| POST | `/qa/device/update` | 更新设备级 QA |
| POST | `/qa/device/delete` | 删除设备级 QA |
| GET | `/qa/device/list` | 获取设备级 QA 列表 |

### 2.11 统计数据

- **招财豹统计**：迎宾次数、互动时长、客流分析等
- **豹小秘统计**：接待次数、导航次数、语音交互次数等
- 共 **15 个** 统计接口

### 2.12 事件回调

| 回调类型 | 说明 |
|---------|------|
| 任务事件回调 | 任务开始/完成/失败等事件推送 |
| 预警通知回调 | 设备异常、电量低等预警推送 |

---

## 三、本地端 APK 原生开发 API

> 开发语言：Java / Kotlin
> 接入方式：引入 RobotOS SDK（AAR 包）
> 需在 Manifest 中声明权限和服务
> 通过 Server 连接、状态监听、reqId 管理调用

### 3.1 SDK 接入

- 基于 Android，引入 RobotOS SDK（AAR 包）
- 需在 Manifest 中声明权限和服务
- 通过 Server 连接、状态监听、reqId 管理调用

### 3.2 视觉能力 API（PersonApi）

| API | 说明 |
|-----|------|
| `PersonApi.detectFace()` | 人脸检测 |
| `PersonApi.registerFace()` | 人脸注册 |
| `PersonApi.recognizeFace()` | 人脸识别 |
| `PersonApi.switchCamera()` | 切换摄像头（前/后/广角） |
| `SurfaceShareApi` | 摄像头数据流共享（获取 YUV 原始数据） |

### 3.3 基础运动 API

| API | 说明 |
|-----|------|
| `RobotApi.goForward(speed)` | 前进（线速度 0~1.2 m/s） |
| `RobotApi.goBackward(speed)` | 后退（**无避障！**） |
| `RobotApi.turnLeft(angularSpeed)` | 左转（角速度 0~2.2 rad/s） |
| `RobotApi.turnRight(angularSpeed)` | 右转 |
| `RobotApi.stopMove()` | 停止运动 |
| `RobotApi.setLinearVelocity(v)` | 设置线速度 |
| `RobotApi.setAngularVelocity(w)` | 设置角速度 |
| `RobotApi.controlHead(horizontalAngle, verticalAngle)` | 控制云台头部 |

### 3.4 地图与定位 API

| API | 说明 |
|-----|------|
| `RobotApi.isRobotEstimate()` | 是否已定位 |
| `RobotApi.getPosition()` | 获取当前坐标 `{x, y, theta}` |
| `RobotApi.getMapName()` | 获取当前地图名 |
| `RobotApi.getPlace(placeName)` | 获取位置点坐标 |
| `RobotApi.getPlaceList()` | 获取所有位置点列表 |
| `RobotApi.switchMap(mapName)` | 切换地图 |
| `RobotApi.setFixedEstimate(pose)` | 固定位姿定位 `{px, py, theta}` |
| `RobotApi.getMultiFloorConfigAndCommonPose()` | 获取多楼层配置和点位 |

### 3.5 导航 API

| API | 说明 |
|-----|------|
| `RobotApi.startNavigation(destination)` | 导航到指定位置（7 种重载） |

**导航参数：**

- `destination` - 目标点名称
- `linearSpeed` - 线速度
- `angularSpeed` - 角速度
- `arrivalRange` - 到达范围
- `timeout` - 超时时间
- 支持加减速模式

**导航状态码：**

| 状态码 | 说明 |
|--------|------|
| 32730001 | 开始导航 |
| 32730004 | 避障中 |
| 32730011 | 堵死 |
| 32730009 | 定位丢失 |

**导航结果码：**

| 结果码 | 说明 |
|--------|------|
| 32610007 | 到达目的地 |
| -32620001 | 未定位 |
| -32620009 | 路径规划失败 |

### 3.6 梯控导航 API（跨楼层）

| API | 说明 |
|-----|------|
| `RobotApi.startElevatorNavigation(floorIndex, destination)` | 乘电梯导航 |

**梯控状态码：**

| 状态码 | 说明 |
|--------|------|
| 32750004 | 到达电梯门 |
| 32750005 | 进入电梯 |
| 32750009 | 离开电梯 |

### 3.7 过闸机导航 API

- 闸机路径判断与通过流程

### 3.8 基础场景 API

| 场景 | 说明 |
|------|------|
| 引领模式 | 人跟机器人走 |
| 焦点跟随 | 机器人视线追踪人脸 |
| 唤醒 | 检测到人后唤醒交互 |

### 3.9 语音 API

| 功能模块 | 说明 |
|---------|------|
| `SkillApi` | 场景管理（注册/切换/退出语音场景） |
| `SkillCallback` | 语音回调（ASR 结果、NLP 解析、唤醒事件等） |
| TTS 播放 | 普通/流式播放 |
| 拾音模式 | 单次/持续识别 |
| NLP 处理 | 意图识别结果解析 |
| 音频采集 | 原始音频流获取 |
| Text 转 MP3 | 文本转语音文件 |

### 3.10 语音大模型流式数据

**ChatStreamInterface 结构：**

| 字段 | 说明 |
|------|------|
| `sid` | 会话 ID |
| `idx` | 消息序号 |
| `content` | 文本内容 |
| `tts` | TTS 音频数据 |
| `sender` | 发送者 |
| `extra` | 扩展字段 |

- 支持流式接收和关闭控制

### 3.11 电量控制 API

| API | 说明 |
|-----|------|
| `RobotApi.getBatteryLevel()` | 获取电量（1-100） |
| `RobotApi.startCharge()` | 自动回充 |
| `RobotApi.stopCharge()` | 离桩 |
| `RobotApi.disableSystemCharge()` | 禁用系统自动充电 |

### 3.12 多机协作 API

- ESP32 模块通信
- `MultiRobotStatus` 数据结构（多机状态同步）

### 3.13 电动门控制 API

- 两种控制方式（自动/手动）
- Door1-4 独立控制
- 门状态查询

### 3.14 系统功能 API

| 功能 | 说明 |
|------|------|
| 状态监控 | 获取系统运行状态 |
| 灯效控制 | 底盘灯带/按钮灯 |
| 设备信息 | SN 号、版本号 |
| 禁用系统功能 | 关闭默认行为 |
| 休眠控制 | 控制机器人休眠/唤醒 |
| 安装 APK | 远程安装应用 |

---

## 四、本地端 OPK 插件开发 API

> 开发语言：JavaScript（React Native）
> 核心库：orionos-eve-core

### 4.1 功能组件

#### 4.1.1 导航组件 NavigationComponent

**参数：**

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `destination` | 目标位置点（**必填**） | - |
| `coordinate_deviation` | 到达范围 | 0.5m |
| 线速度 | 移动速度 | 0.1-1.2 m/s |
| 角速度 | 转弯速度 | 0.2-1.8 rad/s |
| 避障距离 | 检测障碍物距离 | - |
| 超时时间 | 导航超时 | - |

**状态事件码：** 开始导航、避障、堵死、定位丢失等

**结果事件码：** 到达、未定位、路径失败、目标不存在等

#### 4.1.2 巡逻组件 CruiseComponent

**参数：**

| 参数 | 说明 |
|------|------|
| 巡逻路线 | JSON 数组，至少 2 个点 |
| 堵死超时 | 堵死后等待超时时间 |
| 起始点 | 巡逻起始位置 |

- 支持多点循环巡逻

#### 4.1.3 头部控制 HeadTurnComponent

| 参数 | 范围 |
|------|------|
| 水平角度 | -80° ~ 80° |
| 垂直角度 | 50° ~ 95° |

#### 4.1.4 人脸识别组件（6 个）

| 组件 | 说明 |
|------|------|
| `WakeupAndPreWakeupStartCheckComponent` | 唤醒/预唤醒检测 |
| `PersonAppearComponent` | 按条件找人 |
| `PersonDisappearComponent` | 人丢失检测 |
| `RegisterComponent` | 人脸注册 |
| `RecognizeComponent` | 查询注册信息 |
| `ReceptionRegisterCameraView` | 注册预览 |

#### 4.1.5 引领追踪组件（5 个）

| 组件 | 说明 |
|------|------|
| `SoundLocalizationComponent` | 声源定位转向 |
| `FaceTrackSoundLocalizationComponent` | 人脸追踪 + 拾音 |
| `StandardFaceTrackComponent` | 自动追踪最近人脸 |
| `FaceTrackComponent` | 追踪指定人 |
| `LeadingTrackComponent` | 引领（人跟机器人走） |

#### 4.1.6 充电组件

| 组件 | 说明 |
|------|------|
| `ChargeStartComponent` | 自动回充 |
| `LeavePileComponent` | 脱离充电桩 |

#### 4.1.7 梯控组件

| 组件 | 说明 |
|------|------|
| `NavigationElevatorComponent` | 导航乘梯（跨楼层） |
| `ChargeElevatorComponent` | 充电乘梯 |

### 4.2 基础接口

#### 4.2.1 地图与位置（11 个 API）

| API | 说明 |
|-----|------|
| `RobotApi.isRobotEstimate()` | 是否已定位 |
| `RobotApi.getPosition()` | 获取当前坐标 |
| `RobotApi.getMapName()` | 获取当前地图名 |
| `RobotApi.getPlace()` | 获取位置点坐标 |
| `RobotApi.getPlaceList()` | 获取所有位置点列表 |
| `RobotApi.getPlaceListWithName()` | 按名称获取位置点列表 |
| `RobotApi.resumeSpecialPlaceTheta()` | 恢复特殊位置点角度 |
| `RobotApi.switchMap()` | 切换地图 |
| `RobotApi.setFixedEstimate()` | 固定位姿定位 |
| `locationEstimateUtil.havePlace()` | 判断位置点是否存在 |
| `locationEstimateUtil.isInPlace()` | 判断是否在某位置点范围内 |

#### 4.2.2 运动控制

| API | 说明 |
|-----|------|
| `RobotApi.motionArcWithObstacles(lineSpeed, angularSpeed)` | 弧线运动（带避障） |

- 线速度范围：-1.2 ~ 1.2 m/s
- 角速度范围：-2.2 ~ 2.2 rad/s

#### 4.2.3 电源管理（5 个 API）

| API | 说明 |
|-----|------|
| `RobotApi.getBatteryLevel()` | 获取电量百分比 |
| `RobotApi.getBatteryTimeRemaining()` | 获取剩余使用时间 |
| `RobotApi.getChargeTimeRemaining()` | 获取剩余充电时间 |
| `RobotSettingApi.isCharging()` | 是否正在充电 |
| `SettingsUtil.isCharging()` | 是否正在充电（工具类） |

#### 4.2.4 语音接口（11 个 API）

**TTS（文本转语音）：**

| API | 说明 |
|-----|------|
| `speechApi.playText()` | 播放文本语音 |
| `speechApi.playStreamText()` | 流式播放文本语音 |
| `speechApi.stopTTS()` | 停止 TTS 播放 |

**ASR（语音识别）：**

| API | 说明 |
|-----|------|
| `speechApi.setRecognizable()` | 设置是否可识别 |
| `speechApi.setRecognizeMode()` | 设置识别模式 |
| `speechApi.queryByText()` | 文本查询（模拟语音输入） |

**声源定位：**

| API | 说明 |
|-----|------|
| `speechApi.setAngleCenterRange()` | 设置拾音角度范围 |
| `speechApi.resetAngleCenterRange()` | 重置拾音角度范围 |

**音频播放：**

| API | 说明 |
|-----|------|
| `speechApi.playToneByLocalPath()` | 播放本地音频文件 |
| `speechApi.stopTone()` | 停止音频播放 |

**大模型：**

| API | 说明 |
|-----|------|
| `speechApi.closeStreamDataReceived()` | 关闭流式数据接收 |

#### 4.2.5 灯带控制（3 个 API）

| API | 说明 |
|-----|------|
| `LightApi.playEffect()` | 播放灯效 |
| `LightApi.playLightColor()` | 设置灯带颜色 |
| `LightApi.playLightAnimation()` | 播放灯带动画 |

#### 4.2.6 人脸识别（4 个 API，1.x 版本）

| API | 说明 |
|-----|------|
| `PersonManager.getAllPerson()` | 获取所有已注册人员 |
| `PersonManager.getAllPersonNum()` | 获取已注册人员数量 |
| `PersonManager.getLastPersonId()` | 获取最近识别人员 ID |
| `PersonManager.getLastPersonName()` | 获取最近识别人员姓名 |

#### 4.2.7 应用管理（9 个 API）

| API | 说明 |
|-----|------|
| `AppManager.getAppJson()` | 获取应用配置 JSON |
| `AppManager.getOpkExtraPath()` | 获取 OPK 附加资源路径 |
| `AppManager.getOpkPath()` | 获取 OPK 安装路径 |
| `AppManager.getAppConfig()` | 获取应用配置 |
| `AppManager.setConfigUpdateListener()` | 设置配置更新监听 |
| `AppManager.getAppId()` | 获取应用 ID |
| `AppManager.getAppIcon()` | 获取应用图标 |
| `AppManager.restartApp()` | 重启应用 |
| `OpenAppApi.openThirdPartyApp()` | 打开第三方应用 |

#### 4.2.8 系统信息（3 个 API）

| API | 说明 |
|-----|------|
| `SystemInfo.getRobotVersion()` | 获取机器人系统版本 |
| `SystemInfo.getDeviceSn()` | 获取设备 SN 号 |
| `SystemInfo.getVersionByROM()` | 获取 ROM 版本号 |

### 4.3 UI 组件

| 组件 | 说明 |
|------|------|
| `ExDisplay` | 大屏显示 |
| `ImageFrame` | 帧动画 |
| `BlurOverlay` | 高斯模糊 |
| `RNCameraFilterView` | 摄像头预览（含拍照） |
| `emojiPlayerModel` | 大眼睛表情 |
| `UiController.showStatusBar()` | 状态栏显示/隐藏 |

### 4.4 高级功能

| 功能 | 说明 |
|------|------|
| 语音大模型流式数据 | 接入大模型流式输出 |
| 视频通话 TRTC | 仅豹小秘 Mini 支持 |
| 定时任务 Crontab | OPK 内定时任务调度 |
| 梯控系统 | 跨楼层导航 |
| OPK 首页设置 | 自定义首页展示 |
| 多入口配置 | 多个语音/触屏入口 |
| 动态扩展组件 | 加载 dex/so 库 |

---

## 五、NLP 配置能力

### 5.1 配置入口

- 开发者平台：[console.orionbase.cn](https://console.orionbase.cn)

### 5.2 核心概念

| 概念 | 说明 | 示例 |
|------|------|------|
| Domain | 领域 | `medical`、`navigation` |
| Intent | 意图 | `guide_to`、`query_report` |
| Slot | 槽位 | `department_name`、`patient_id` |

### 5.3 配置方式

| 配置项 | 说明 |
|--------|------|
| 自定义语音指令 | 定义触发关键词和对应动作 |
| 意图识别规则 | 配置 NLU 规则匹配用户意图 |
| 多轮对话设计 | 设计多轮交互流程 |
| 第三方 NLP 插入 | 支持 Dialogflow 等外部 NLP 引擎 |
| 语音链路测试 | 在线测试语音识别和意图解析 |

### 5.4 NLP 数据流

```
语音输入 → ASR 识别 → NLP 意图解析 → 匹配 Domain & Intent → 触发对应 OPK/APK 应用
```

---

## 六、适用机型对照

| 机型 | 导航 | 人脸 | 追踪 | 回充 | TRTC | 梯控 | 屏幕 |
|------|:----:|:----:|:----:|:----:|:----:|:----:|:----:|
| 豹小秘 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | 有 |
| 豹小秘 Mini | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 有 |
| 豹小秘2 | ✅ | ✅ | ✅ | ✅ | - | - | 有 |
| 招财豹 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | 有 |
| 招财豹Pro | ✅ | ✅ | ✅ | ✅ | - | - | 有 |
| 豹小递 Max | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | 有 |
| 豹小秘 DP | 部分 | ✅ | ❌ | 部分 | ❌ | ❌ | 大屏 |
| 消毒豹 | ✅ | - | - | - | - | ✅ | - |

---

> 本手册基于猎户星空开发者文档整理，如有更新请以官方文档为准。