rvis-aiui-kit 1.0.0

package/sdk/README.md

@@ -0,0 +1,1013 @@
+# Glass3 扩展 SDK API 文档
+
+本文档汇总 `sdk/` 目录当前公开的 JavaScript API。公开接口以
+[`api-map.js`](./api-map.js) 为准；各模块的 `readme.md` 提供更完整的 Native
+协议、事件时序与返回示例。
+
+> 适用范围：项目内的 Host RPC 扩展能力。若 `glass3` 已提供对应能力，应优先使用
+> 本 SDK；只有 SDK 未覆盖的能力才使用基础 AIUI 运行时 API。
+
+## 目录
+
+- [快速接入](#快速接入)
+- [API 总览](#api-总览)
+- [通用调用约定](#通用调用约定)
+- [Device Context 设备上下文](#device-context-设备上下文)
+- [Screen 屏幕控制](#screen-屏幕控制)
+- [Notification 原生通知](#notification-原生通知)
+- [TTS 语音播报](#tts-语音播报)
+- [Offline Command 离线语音指令](#offline-command-离线语音指令)
+- [Audio 录音与转写](#audio-录音与转写)
+- [Camera 相机](#camera-相机)
+- [Face 人脸识别](#face-人脸识别)
+- [Motion 运动状态检测](#motion-运动状态检测)
+- [错误处理](#错误处理)
+- [页面卸载清理](#页面卸载清理)
+- [Native 映射](#native-映射)
+- [详细文档与 Demo](#详细文档与-demo)
+
+## 快速接入
+
+根据页面所在层级调整导入路径：
+
+```js
+import glass3 from 'rvis-aiui-kit';
+
+export default {
+  onMessage(messageEvent) {
+    // 必须转发。依赖 Host event 的 Promise 和 onEvent 才能正常工作。
+    glass3.handleMessage(messageEvent);
+  },
+
+  onUnload() {
+    // 先停止仍在运行的长任务，再释放本地监听和未完成调用。
+    glass3.dispose();
+  }
+};
+```
+
+SDK 还提供命名导出：
+
+```js
+import glass3, {
+  glass3 as namedGlass3,
+  API_MAP,
+  Glass3Error
+} from 'rvis-aiui-kit';
+```
+
+- `glass3`：默认客户端实例及全部公开模块。
+- `API_MAP`：公开 JavaScript API 到 Host RPC 的权威映射。
+- `Glass3Error`：SDK 错误类型。
+
+## API 总览
+
+| 模块 | 方法 | 用途 |
+| --- | --- | --- |
+| `deviceContext` | `get(options?)` | 一次性获取设备上下文原子快照。 |
+| `deviceContext` | `observe(options?, callOptions?)` | 订阅设备上下文快照和增量变化。 |
+| `deviceContext` | `stopObserve({ requestId })` | 停止指定的设备上下文订阅。 |
+| `screen` | `turnOff()` | 关闭屏幕并等待 Native 确认。 |
+| `screen` | `turnOn()` | 点亮屏幕并等待 Native 确认。 |
+| `notification` | `show(options)` | 显示 Host 管理的原生通知。 |
+| `notification` | `hide({ requestId })` | 隐藏指定通知。 |
+| `tts` | `speak(options, callOptions?)` | 开始 TTS 播报。 |
+| `tts` | `stop({ requestId })` | 停止指定 TTS。 |
+| `offlineCommand` | `register(options, callOptions?)` | 注册一批离线语音指令。 |
+| `offlineCommand` | `unregister({ requestId })` | 注销指定指令批次。 |
+| `audio` | `startRecord(options?, callOptions?)` | 开始录音，可转写、保存或上传。 |
+| `audio` | `stopRecord({ requestId })` | 停止指定录音并返回结果。 |
+| `camera` | `startPreview(options?)` | 开启相机预览。 |
+| `camera` | `stopPreview({ requestId })` | 关闭指定预览。 |
+| `camera` | `takePhoto(options?)` | 拍照并等待照片结果。 |
+| `camera` | `startTakeVideo(options?, callOptions?)` | 开始分段录像。 |
+| `camera` | `stopTakeVideo({ requestId })` | 停止指定录像。 |
+| `face` | `startRecognize({}, callOptions?)` | 开始持续人脸识别。 |
+| `face` | `stopRecognize({ requestId })` | 停止指定人脸识别。 |
+| `motion` | `startDetect({}, callOptions?)` | 开始持续运动状态检测。 |
+| `motion` | `stopDetect({ requestId })` | 停止指定运动检测。 |
+
+客户端级方法：
+
+| 方法 | 返回值 | 说明 |
+| --- | --- | --- |
+| `glass3.handleMessage(messageEvent)` | 匹配结果或 `null` | 将页面收到的 Host 消息交给 SDK。 |
+| `glass3.dispose()` | `undefined` | 清理监听，并以 `CALL_DISPOSED` 结束仍在等待的调用。 |
+
+## 通用调用约定
+
+### Promise 与 `onEvent`
+
+- 每个业务方法都返回 Promise。
+- Promise 完成表示该方法定义的“就绪”或“终态”已到达，不一定表示整个长任务结束。
+- `onEvent` 用于接收同一启动请求后续产生的流式事件。
+- Native response 不会进入 `onEvent`；`onEvent` 只接收匹配的 event result。
+- Native 返回的下划线字段通常会递归转换为驼峰字段，具体以各 API 说明为准。
+
+```js
+const task = await glass3.face.startRecognize({}, {
+  onEvent(result) {
+    console.log('face event:', JSON.stringify(result));
+  }
+});
+```
+
+### `requestId`
+
+- 每次调用都有独立的 `requestId`。
+- `start*` 返回的 `requestId` 是后续 `stop*` 的目标 ID，必须保存。
+- `stop*` 自身会创建新的 `requestId`；返回值中的 ID 是 stop 调用的 ID，不是 start ID。
+- 除文档明确允许的字段外，参数均按闭合对象校验，不要添加未记录字段或使用
+  `snake_case` 字段。
+
+### Host 消息转发
+
+使用通知、屏幕、拍照，以及任何带事件或等待 Native 终态的 API 时，都必须转发
+`onMessage`：
+
+```js
+onMessage(messageEvent) {
+  glass3.handleMessage(messageEvent);
+}
+```
+
+不转发时，部分请求虽然已被 Native 接收，但 Promise 不会完成，`onEvent` 也不会触发。
+
+## Device Context 设备上下文
+
+### `glass3.deviceContext.get(options?)`
+
+一次性获取所选 domain 的原子快照：
+
+```js
+const result = await glass3.deviceContext.get({
+  domains: ['environment', 'power', 'network', 'interaction']
+});
+
+console.log(JSON.stringify(result.snapshot));
+```
+
+可选 domain 为 `identity`、`software`、`account`、`environment`、`power`、
+`network` 和 `interaction`。省略参数或传 `{}` 表示全部；显式传入时必须是非空数组。
+
+Promise 等到最终 snapshot 事件后完成：
+
+```js
+{
+  requestId: 'get request UUID',
+  ok: true,
+  eventType: 'snapshot',
+  snapshot: {
+    schemaVersion: '1.0',
+    epoch: 'system-server-process-uuid',
+    revision: 12,
+    capturedAtElapsedMs: 368219,
+    power: { available: true, levelPercent: 76, charging: false },
+    network: { effectiveRoute: 'glass_direct', online: true },
+    interaction: { screenState: 'on' }
+  }
+}
+```
+
+### `glass3.deviceContext.observe(options?, callOptions?)`
+
+```js
+const observer = await glass3.deviceContext.observe(
+  { domains: ['account', 'environment', 'power', 'network'] },
+  {
+    onEvent(event) {
+      if (event.eventType === 'snapshot') {
+        initializeContext(event.snapshot);
+      } else if (event.eventType === 'changed') {
+        applyContextPatch(event);
+      } else if (event.eventType === 'invalidated') {
+        clearAccountContext();
+        reloadScene();
+      }
+    }
+  }
+);
+```
+
+started response 到达后返回：
+
+```js
+{ requestId: 'observe request UUID', ok: true, state: 'started' }
+```
+
+首个业务事件固定为 `snapshot`，之后仅在状态实际变化时产生 `changed`。SDK 不自动
+合并 patch；调用方应验证事件的 `epoch` 与 `baseRevision` 后再更新当前快照。
+
+`invalidated` 表示账号或环境隔离边界已经变化。该事件进入回调后订阅监听会释放；
+调用方必须清除旧账号上下文并重载 Scene。
+
+### `glass3.deviceContext.stopObserve({ requestId })`
+
+```js
+const result = await glass3.deviceContext.stopObserve({
+  requestId: observer.requestId
+});
+// { requestId: 'stop request UUID', ok: true, state: 'stopped' }
+```
+
+可选字段保持缺省语义。例如 `phone_relay` 路由没有 `online` 时，不能将其解释为
+`false`。枚举值保持 Native 协议原值，不转换 `logged_in`、`glass_direct` 等字符串。
+
+详见 [`modules/device-context/readme.md`](./modules/device-context/readme.md)。
+
+## Screen 屏幕控制
+
+### `glass3.screen.turnOff()`
+
+关闭屏幕，不接收参数。
+
+```js
+const result = await glass3.screen.turnOff();
+```
+
+### `glass3.screen.turnOn()`
+
+点亮屏幕，不接收参数。
+
+```js
+const result = await glass3.screen.turnOn();
+```
+
+两个方法的返回结构相同：
+
+```js
+{
+  requestId: 'screen request UUID',
+  ok: true,
+  changed: true,
+  screen: 'off' // turnOn 时为 'on'
+}
+```
+
+- `changed: false` 表示调用前已经处于目标状态，仍属于成功。
+- accepted response 仅表示已受理；匹配的成功 `toolResult` 才会完成 Promise。
+- 普通电源键的睡眠/唤醒由 Host 管理时，不要在
+  `RokidActionSingleClick` 中调用这些 API，也不要拦截默认行为。
+
+### 系统屏幕状态事件
+
+系统发起的亮屏/息屏通过原始 Host RPC 事件通知页面，不是独立的 `glass3` 订阅 API：
+
+```js
+onMessage(messageEvent) {
+  glass3.handleMessage(messageEvent);
+
+  const message = messageEvent && messageEvent.data;
+  if (
+    message &&
+    message.namespace === 'rokid.device' &&
+    message.event === 'screenStateChanged'
+  ) {
+    const isScreenOn = message.data.state === 'on';
+  }
+}
+```
+
+`data.state` 为 `on` 或 `off`。页面可在加载时默认按亮屏处理，此后以该事件作为
+Host 管理的屏幕状态来源。
+
+> Native notification 的显示优先级高于息屏状态。若息屏后不应保留通知，应先
+> `notification.hide()`，再 `screen.turnOff()`。
+
+详见 [`modules/screen/readme.md`](./modules/screen/readme.md)。
+
+## Notification 原生通知
+
+### `glass3.notification.show(options)`
+
+显示 Host 管理的原生通知。`title` 与 `text` 至少显式提供一个；允许传空字符串。
+
+```js
+const notification = await glass3.notification.show({
+  text: '思考中',
+  level: 'active',
+  position: 'topCenter',
+  durationMs: 8000,
+  animation: 'thinking',
+  resident: true
+});
+```
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `string` | 条件必填 | 无 | 标题，保留首尾空白。 |
+| `text` | `string` | 条件必填 | 无 | 正文，保留首尾空白。 |
+| `level` | `string` | 否 | `active` | 只允许 `active` 或 `critical`。 |
+| `position` | `string` | 否 | Native 默认值 | 见下方位置枚举。 |
+| `durationMs` | `number` | 否 | Native 默认值 | 大于 0 的整数，单位毫秒。 |
+| `animation` | `string` | 否 | `idle` | 见下方动效枚举。 |
+| `resident` | `boolean` | 否 | Native 默认值 | `true` 时不自动隐藏。 |
+
+位置枚举：
+
+```text
+topLeft, topCenter, topRight,
+bottomLeft, bottomCenter, bottomRight
+```
+
+动效枚举：
+
+```text
+idle, blink, thinking, calm, nod, bow, salute,
+photo, face, scan, success, listening, speaking, enter, exit
+```
+
+返回值：
+
+```js
+{ requestId: 'notification UUID', ok: true }
+```
+
+### `glass3.notification.hide({ requestId })`
+
+隐藏 `show()` 创建的通知。
+
+```js
+const result = await glass3.notification.hide({
+  requestId: notification.requestId
+});
+// { requestId: 'hide request UUID', ok: true }
+```
+
+详见 [`modules/notification/readme.md`](./modules/notification/readme.md)。
+
+## TTS 语音播报
+
+### `glass3.tts.speak(options, callOptions?)`
+
+```js
+const playback = await glass3.tts.speak(
+  {
+    text: '你好，这是一段播报。',
+    queueMode: 'flush'
+  },
+  {
+    onEvent(result) {
+      // { ok: true, state: 'started' | 'finished' | 'canceled' }
+    }
+  }
+);
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | 播报文本；当前 SDK 直接透传，不做本地校验。 |
+| `queueMode` | `string` | 否 | 播放队列策略，例如 `flush`；当前 SDK 直接透传。 |
+
+accepted response 到达后 Promise 即完成，不等待播放结束：
+
+```js
+{ requestId: 'tts start UUID', ok: true }
+```
+
+`onEvent` 常见状态为 `started`、`finished`、`canceled`。收到 `finished` 或
+`canceled` 后，SDK 会清理该播放的事件监听。
+
+### `glass3.tts.stop({ requestId })`
+
+```js
+const result = await glass3.tts.stop({
+  requestId: playback.requestId
+});
+// { requestId: 'tts stop UUID', ok: true, state: 'stopped' }
+```
+
+`stop()` 只等待自己的停止结果；原 `speak()` 仍可能通过其 `onEvent` 收到
+`canceled`。
+
+详见 [`modules/tts/readme.md`](./modules/tts/readme.md)。
+
+## Offline Command 离线语音指令
+
+### `glass3.offlineCommand.register(options, callOptions?)`
+
+```js
+const registration = await glass3.offlineCommand.register(
+  {
+    language: 'ZH_CN',
+    commands: [
+      {
+        id: 'next_step',
+        phrases: [
+          { text: '下一步', pinyin: 'xia yi bu' },
+          { text: '继续' }
+        ]
+      }
+    ]
+  },
+  {
+    onEvent(result) {
+      // 命中：{ ok: true, commandId, phrase, timestamp }
+    }
+  }
+);
+```
+
+顶层参数：
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `language` | `string` | 否 | `ZH_CN` | 非空语言标识，SDK 不限制枚举。 |
+| `commands` | `array` | 是 | 无 | 非空指令数组。 |
+
+`commands[]`：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | 是 | 非空业务指令 ID。 |
+| `phrases` | `array` | 是 | 非空触发短语数组。 |
+
+`phrases[]`：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | 非空触发文本。 |
+| `pinyin` | `string` | 否 | 非空拼音；省略时不发送给 Native。 |
+
+注册需要同时观察“请求已受理”和 `started`，两者顺序不固定。返回值：
+
+```js
+{
+  requestId: 'offline command start UUID',
+  ok: true,
+  state: 'started',
+  commandCount: 1, // Native 未返回时省略
+  phraseCount: 2   // Native 未返回时省略
+}
+```
+
+同一注册可多次触发 `onEvent`：
+
+```js
+{
+  ok: true,
+  commandId: 'next_step',
+  phrase: '下一步',
+  timestamp: 1785403248395
+}
+```
+
+页面被释放时可能收到终态：
+
+```js
+{ ok: true, state: 'canceled', reason: 'owner_release' }
+```
+
+### `glass3.offlineCommand.unregister({ requestId })`
+
+```js
+const result = await glass3.offlineCommand.unregister({
+  requestId: registration.requestId
+});
+// { requestId: 'unregister UUID', ok: true, state: 'stopped' }
+```
+
+注销成功后 SDK 会释放目标 register 的事件监听。
+
+详见
+[`modules/offline-command/readme.md`](./modules/offline-command/readme.md)。
+
+## Audio 录音与转写
+
+### `glass3.audio.startRecord(options?, callOptions?)`
+
+```js
+const recording = await glass3.audio.startRecord(
+  {
+    maxMinutes: 10,
+    needText: true,
+    needMp3: false,
+    showCard: true,
+    upload: false
+  },
+  {
+    onEvent(result) {
+      console.log('audio event:', JSON.stringify(result));
+    }
+  }
+);
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `maxMinutes` | `number` | `10` | 1～120 的整数。 |
+| `needText` | `boolean` | `true` | 返回整段 ASR 转写 `text`。 |
+| `needMp3` | `boolean` | `false` | 保留并返回音频文件。 |
+| `showCard` | `boolean` | `true` | 显示 Native 录音卡片。 |
+| `upload` | `boolean` | `false` | 上传录音结果；成功时返回 `fileUrl`。 |
+
+只有同一 requestId 的 `response.result.state === 'started'` 才会完成 start Promise；
+started event 本身不会完成 Promise：
+
+```js
+{ requestId: 'audio start UUID', ok: true, state: 'started' }
+```
+
+录音结束结果继续进入 start 的 `onEvent`：
+
+```js
+{
+  ok: true,
+  finished: true,
+  state: 'finished',
+  reason: 'max_duration',
+  durationMs: 600000,
+  text: '整段转写文本',
+  filePath: '/path/to/tool_audio.mp3',
+  fileUrl: 'https://example.com/tool_audio.mp3',
+  sizeBytes: 165164,
+  sampleRate: 16000
+}
+```
+
+用户通过离线指令“结束录音”完成录音时，同样通过原 start 的 `onEvent` 返回正常完成结果：
+
+```js
+{
+  ok: true,
+  finished: true,
+  state: 'finished',
+  reason: 'offline_command',
+  durationMs: 5140,
+  text: '整段转写文本',
+  filePath: '/path/to/tool_audio.mp3'
+}
+```
+
+常见异步失败：
+
+```js
+{ ok: false, error: 'mic_busy' }
+{ ok: false, error: 'asr_unavailable' }
+```
+
+### `glass3.audio.stopRecord({ requestId })`
+
+```js
+const result = await glass3.audio.stopRecord({
+  requestId: recording.requestId
+});
+```
+
+stop Promise 只等待 stop 自己 requestId 的 `stopped` event，并直接返回录音成果：
+
+```js
+{
+  requestId: 'audio stop UUID',
+  ok: true,
+  state: 'stopped',
+  durationMs: 5140,
+  text: '整段转写文本',
+  filePath: '/path/to/tool_audio.mp3',
+  fileUrl: 'https://example.com/tool_audio.mp3',
+  sizeBytes: 165164,
+  sampleRate: 16000
+}
+```
+
+详见 [`modules/audio/readme.md`](./modules/audio/readme.md)。
+
+## Camera 相机
+
+### `glass3.camera.startPreview(options?)`
+
+建议不传参数，使用 SDK 默认的顶部预览区域：
+
+```js
+const preview = await glass3.camera.startPreview();
+```
+
+默认参数：
+
+```js
+{
+  left: 0,
+  top: 40,
+  width: 168,
+  height: 103,
+  cornerRadius: 2,
+  outline: true
+}
+```
+
+自定义区域：
+
+```js
+const preview = await glass3.camera.startPreview({
+  left: 40,
+  top: 150,
+  width: 240,
+  height: 180,
+  cornerRadius: 16,
+  outline: false
+});
+```
+
+| 字段 | 类型 | 约束 |
+| --- | --- | --- |
+| `left` | `number` | 有限、非负。 |
+| `top` | `number` | 有限、非负。自定义普通预览建议 `top >= 150`。 |
+| `width` | `number` | 有限且大于 0。 |
+| `height` | `number` | 有限且大于 0。 |
+| `cornerRadius` | `number` | 有限、非负。 |
+| `outline` | `boolean` | 是否以线框呈现，默认 `true`。 |
+
+只要提供任意一个区域字段，就必须同时提供 `left`、`top`、`width`、`height`、
+`cornerRadius`。`outline` 可单独设置。
+
+Promise 在匹配的 started response 或 event 后完成：
+
+```js
+{ requestId: 'preview start UUID', ok: true, state: 'started' }
+```
+
+### `glass3.camera.stopPreview({ requestId })`
+
+```js
+const result = await glass3.camera.stopPreview({
+  requestId: preview.requestId
+});
+// { requestId: 'preview stop UUID', ok: true, state: 'cancel' }
+```
+
+### `glass3.camera.takePhoto(options?)`
+
+```js
+const photo = await glass3.camera.takePhoto({
+  returnBase64: false,
+  upload: true,
+  timeout: 8000
+});
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `returnBase64` | `boolean` | `true` | 返回 JPEG Base64。 |
+| `upload` | `boolean` | `false` | 上传照片。 |
+| `timeout` | `number` | `5000` | JS 等待超时，正整数毫秒；不发送给 Native。 |
+
+accepted response 不会完成 Promise；只有匹配的成功照片 event 才会完成。结果示例：
+
+```js
+{
+  requestId: 'photo UUID',
+  ok: true,
+  photoSize: 41056,
+  filePath: '/storage/emulated/0/.../tool_photo_xxx.jpg',
+  width: 1080,
+  height: 720,
+  photoMime: 'image/jpeg',
+  photoBase64: '...',
+  fileUrl: 'https://...',
+  inspectionResultId: 42,
+  uploadError: 'no_session'
+}
+```
+
+- `photoMime`、`photoBase64` 仅在 `returnBase64: true` 时出现。
+- `fileUrl`、`inspectionResultId` 仅在上传成功时出现。
+- 上传失败不一定使拍照失败，可能通过 `uploadError` 返回。
+- 超时抛出 `CALL_TIMEOUT`；超时只停止 JS 等待，不保证 Native 拍照已取消。
+
+### `glass3.camera.startTakeVideo(options?, callOptions?)`
+
+```js
+const recording = await glass3.camera.startTakeVideo(
+  {
+    enableAudio: true,
+    segmentMinutes: 20
+  },
+  {
+    onEvent(result) {
+      console.log('video event:', JSON.stringify(result));
+    }
+  }
+);
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `enableAudio` | `boolean` | `true` | 是否录音。 |
+| `segmentMinutes` | `number` | `20` | 正整数，录像分段时长。 |
+
+启动完成返回：
+
+```js
+{ requestId: 'video start UUID', ok: true }
+```
+
+常见事件：
+
+```js
+{ ok: true, state: 'started' }
+
+{
+  ok: true,
+  filePath: '/storage/emulated/0/Pictures/example.mp4',
+  startTime: 1784543000000,
+  endTime: 1784544200000,
+  hasMore: true
+}
+
+{ ok: true, state: 'canceled' }
+{ ok: false, errorCode: 500, error: 'recording failed' }
+```
+
+`hasMore: false` 表示最后一段；`canceled` 表示被系统停止。两者都会使 SDK 在
+事件回调后清理录像流监听。
+
+### `glass3.camera.stopTakeVideo({ requestId })`
+
+```js
+const result = await glass3.camera.stopTakeVideo({
+  requestId: recording.requestId
+});
+// { requestId: 'video stop UUID', ok: true, state: 'finished' }
+```
+
+stop 与 start 的监听独立；调用 stop 不会主动清理 start 的监听，start 仍需接收
+最后一段或终止事件。
+
+详见 [`modules/camera/readme.md`](./modules/camera/readme.md)。
+
+## Face 人脸识别
+
+### `glass3.face.startRecognize({}, callOptions?)`
+
+接口没有业务参数。需要传第二个调用选项时，第一个参数必须是空对象：
+
+```js
+const recognition = await glass3.face.startRecognize({}, {
+  onEvent(result) {
+    console.log('face event:', JSON.stringify(result));
+  }
+});
+```
+
+也可省略所有参数：
+
+```js
+const recognition = await glass3.face.startRecognize();
+```
+
+started response 或 event 到达后返回：
+
+```js
+{ requestId: 'face start UUID', ok: true }
+```
+
+识别事件示例：
+
+```js
+{
+  label: '330…1234|张三|职工',
+  labelParts: ['330…1234', '张三', '职工'],
+  personId: '330…1234',
+  personIdCard: '330…1234',
+  personName: '张三',
+  personType: '职工',
+  similarity: 0.97,
+  regScore: 97,
+  trackId: 3,
+  sdkFrameId: 1024,
+  faceModel: {
+    frameWidth: 1080,
+    frameHeight: 1440,
+    frameId: 1024,
+    trackId: 3,
+    faceScore: 0.99,
+    iqaScore: 0.8,
+    rect: { left: 100, top: 200, right: 300, bottom: 400 }
+  }
+}
+```
+
+### `glass3.face.stopRecognize({ requestId })`
+
+```js
+const result = await glass3.face.stopRecognize({
+  requestId: recognition.requestId
+});
+// { requestId: 'face stop UUID', ok: true, state: 'stopped' }
+```
+
+原 start request 收到 `state: 'stopped'` 后，其监听会自行清理。
+
+详见 [`modules/face/readme.md`](./modules/face/readme.md)。
+
+## Motion 运动状态检测
+
+### `glass3.motion.startDetect({}, callOptions?)`
+
+接口没有业务参数。需要 `onEvent` 时，第一个参数传空对象：
+
+```js
+const detection = await glass3.motion.startDetect({}, {
+  onEvent(result) {
+    console.log('motion event:', JSON.stringify(result));
+  }
+});
+```
+
+协议没有单独启动确认事件，fetch 返回 Native 已受理后 Promise 即完成：
+
+```js
+{ requestId: 'motion start UUID', ok: true }
+```
+
+Native 仅在状态变化时上报：
+
+```js
+{
+  ok: true,
+  motionState: 'walk',
+  previous: 'still',
+  moving: true,
+  timestamp: 123456789
+}
+```
+
+状态枚举：
+
+```text
+still, walk, run, headTurnLeft, headTurnRight
+```
+
+首个事件的 `previous` 为 `unknown`。SDK 不对事件去重或合并。
+
+### `glass3.motion.stopDetect({ requestId })`
+
+```js
+const result = await glass3.motion.stopDetect({
+  requestId: detection.requestId
+});
+// { requestId: 'motion stop UUID', ok: true, state: 'stopped' }
+```
+
+详见 [`modules/motion/readme.md`](./modules/motion/readme.md)。
+
+## 错误处理
+
+所有 SDK 错误都使用 `Glass3Error`：
+
+```js
+try {
+  await glass3.camera.takePhoto({ timeout: 5000 });
+} catch (error) {
+  if (error instanceof Glass3Error) {
+    console.error(error.code, error.stage, error.requestId);
+  }
+}
+```
+
+`Glass3Error` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | 固定为 `Glass3Error`。 |
+| `message` | 可读错误信息。 |
+| `code` | 程序判断使用的错误码。 |
+| `stage` | 失败阶段，例如 `params`、`response`、`event`、`timeout`、`dispose`。 |
+| `requestId` | 已生成请求时对应的调用 ID。 |
+| `namespace` / `method` | Host RPC 上下文。 |
+| `details` | Native 响应、事件或补充详情。 |
+| `cause` | 底层原始错误。 |
+
+常见错误码：
+
+| 错误码 | 说明 |
+| --- | --- |
+| `INVALID_PARAMS` | 参数缺失、类型错误、枚举无效或出现未支持字段。 |
+| `TRANSPORT_REJECTED` | Host RPC 传输层返回非成功状态。 |
+| `NATIVE_REQUEST_ERROR` | 请求发送或响应阶段异常的统一错误。 |
+| `NATIVE_REQUEST_NOT_ACCEPTED` | Native 响应未通过协议校验或未受理。 |
+| `NATIVE_EVENT_ERROR` | 匹配的 Native event 返回失败。 |
+| `CALL_TIMEOUT` | JS 等待超时；当前用于 `camera.takePhoto()`。 |
+| `CALL_DISPOSED` | 调用尚未完成时执行了 `glass3.dispose()`。 |
+| `GLASS3_ERROR` | 未提供更具体错误码时的默认值。 |
+
+Native 也可能直接返回自己的错误码。需要恢复策略时，应按 `error.code` 判断，不要
+只匹配 `message` 文本。
+
+## 页面卸载清理
+
+页面应保存所有长任务的 start requestId，并在卸载前尽力停止：
+
+```js
+let recognitionRequestId = null;
+
+export default {
+  onMessage(messageEvent) {
+    glass3.handleMessage(messageEvent);
+  },
+
+  async startRecognition() {
+    const result = await glass3.face.startRecognize({}, {
+      onEvent(eventResult) {
+        console.log(JSON.stringify(eventResult));
+      }
+    });
+    recognitionRequestId = result.requestId;
+  },
+
+  onUnload() {
+    if (recognitionRequestId) {
+      glass3.face.stopRecognize({
+        requestId: recognitionRequestId
+      }).catch(error => {
+        if (error.code !== 'CALL_DISPOSED') {
+          console.error(JSON.stringify(error));
+        }
+      });
+      recognitionRequestId = null;
+    }
+
+    glass3.dispose();
+  }
+};
+```
+
+需要主动停止或注销的长任务包括：
+
+- `deviceContext.observe()`
+- `tts.speak()`
+- `offlineCommand.register()`
+- `audio.startRecord()`
+- `camera.startPreview()`
+- `camera.startTakeVideo()`
+- `face.startRecognize()`
+- `motion.startDetect()`
+
+`dispose()` 只负责 SDK 本地监听和等待中的 Promise，不等价于所有 Native 长任务的
+业务 stop 操作。
+
+## Native 映射
+
+所有业务调用使用 RPC `version: "2.0.0"`、`namespace: "rokid.tools"`、
+`method: "invoke"`。
+
+| JavaScript API | `toolName` | `toolAction` |
+| --- | --- | --- |
+| `deviceContext.get` | `getDeviceContext` | `start` |
+| `deviceContext.observe` | `observeDeviceContext` | `start` |
+| `deviceContext.stopObserve` | `observeDeviceContext` | `stop` |
+| `notification.show` | `showNotification` | `start` |
+| `notification.hide` | `showNotification` | `stop` |
+| `screen.turnOff` | `screenOff` | `start` |
+| `screen.turnOn` | `screenOff` | `start` |
+| `tts.speak` | `tts` | `start` |
+| `tts.stop` | `tts` | `stop` |
+| `offlineCommand.register` | `offlineCommand` | `start` |
+| `offlineCommand.unregister` | `offlineCommand` | `stop` |
+| `audio.startRecord` | `audioRecord` | `start` |
+| `audio.stopRecord` | `audioRecord` | `stop` |
+| `camera.startPreview` | `cameraPreview` | `start` |
+| `camera.stopPreview` | `cameraPreview` | `stop` |
+| `camera.takePhoto` | `takePhoto` | `start` |
+| `camera.startTakeVideo` | `lawEnforcementRecord` | `start` |
+| `camera.stopTakeVideo` | `lawEnforcementRecord` | `stop` |
+| `face.startRecognize` | `faceRecognize` | `start` |
+| `face.stopRecognize` | `faceRecognize` | `stop` |
+| `motion.startDetect` | `motionDetect` | `start` |
+| `motion.stopDetect` | `motionDetect` | `stop` |
+
+业务代码应调用公开 JavaScript API，不要直接依赖这张 Native 映射表发 RPC。
+
+## 详细文档与 Demo
+
+### 模块文档
+
+- [Device Context](./modules/device-context/readme.md)
+- [Screen](./modules/screen/readme.md)
+- [Notification](./modules/notification/readme.md)
+- [TTS](./modules/tts/readme.md)
+- [Offline Command](./modules/offline-command/readme.md)
+- [Audio](./modules/audio/readme.md)
+- [Camera](./modules/camera/readme.md)
+- [Face](./modules/face/readme.md)
+- [Motion](./modules/motion/readme.md)
+
+### 示例页面
+
+- [Device Context Demo](../pages/sdk-demo/device-context/index.ink)
+- [Screen Demo](../pages/sdk-demo/screen/index.ink)
+- [Notification Demo Suite](../pages/sdk-demo/notification/index.ink)
+  - [文案与默认值](../pages/sdk-demo/notification/content/index.ink)
+  - [通知级别](../pages/sdk-demo/notification/levels/index.ink)
+  - [显示位置](../pages/sdk-demo/notification/positions/index.ink)
+  - [显示时长](../pages/sdk-demo/notification/duration/index.ink)
+  - [通知动效](../pages/sdk-demo/notification/animation/index.ink)
+  - [常驻与隐藏](../pages/sdk-demo/notification/resident/index.ink)
+- [TTS Demo](../pages/sdk-demo/tts/index.ink)
+- [Offline Command Demo](../pages/sdk-demo/offline-command/index.ink)
+- [Audio Record Demo](../pages/sdk-demo/audio-record/index.ink)
+- [Camera Preview Demo](../pages/sdk-demo/camera/index.ink)
+- [Camera Photo Demo](../pages/sdk-demo/camera-photo/index.ink)
+- [Camera Video Demo](../pages/sdk-demo/camera-video/index.ink)
+- [Face Recognize Demo](../pages/sdk-demo/face-recognize/index.ink)
+- [Motion Detect Demo](../pages/sdk-demo/motion-detect/index.ink)