rvis-aiui-kit 1.0.0

package/sdk/modules/face/readme.md

@@ -0,0 +1,196 @@
+# Face API
+
+Face 模块通过 `glass3.face` 暴露持续人脸识别能力。
+
+页面必须在 `onMessage` 中调用 `glass3.handleMessage(messageEvent)`，识别事件才能被关联到对应请求。
+
+## API 列表
+
+| API | 说明 |
+| --- | --- |
+| `face.startRecognize` | 开启人脸识别并持续接收结果。 |
+| `face.stopRecognize` | 停止指定的人脸识别请求。 |
+
+## `face.startRecognize`
+
+该接口没有业务参数。由于第二个位置是调用选项，注册 `onEvent` 时第一个参数传空对象：
+
+```js
+const recognition = await glass3.face.startRecognize(
+  {},
+  {
+    onEvent(eventResult) {
+      console.log('face event:', JSON.stringify(eventResult));
+    }
+  }
+);
+```
+
+不需要事件回调时也可以直接调用：
+
+```js
+const recognition = await glass3.face.startRecognize();
+```
+
+SDK 发送给 Native 的 `args` 始终为 `{}`。传入非空参数会抛出参数错误。
+
+### 返回值
+
+请求通过校验后，Promise 在收到以下任一消息时完成：
+
+- `kind: "event"` 且 `data.result.state: "started"`；
+- `kind: "response"` 且 `result.state: "started"`。
+
+```js
+{
+  requestId: '识别启动 UUID',
+  ok: true
+}
+```
+
+Promise 完成后，识别结果仍会使用同一个 requestId 持续进入 `onEvent`。response 不会作为 event 传给 `onEvent`。
+
+### 事件
+
+`onEvent` 只接收 Native 消息中的 `message.data.result`。所有下划线字段都会递归转换为驼峰。
+
+启动事件：
+
+```js
+{ ok: true, state: 'started' }
+```
+
+识别结果示例：
+
+```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
+    }
+  }
+}
+```
+
+异常事件：
+
+```js
+{
+  ok: false,
+  errorCode: 500,
+  error: 'recognition failed'
+}
+```
+
+启动前收到错误会拒绝 Promise。启动后的错误会先进入 `onEvent`，随后结束本次事件监听。
+
+原 start request 收到以下事件时，SDK 会在透传事件后清理监听：
+
+```js
+{ ok: true, state: 'stopped' }
+```
+
+Native 映射：`rokid.tools / invoke / faceRecognize / start`。
+
+## `face.stopRecognize`
+
+```js
+const result = await glass3.face.stopRecognize({
+  requestId: recognition.requestId
+});
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `startRecognize` 返回的识别启动 ID。只允许传该字段。 |
+
+SDK 会将其转换为 Native 参数：
+
+```js
+{
+  targetRequestId: recognition.requestId
+}
+```
+
+stop 调用会生成自己的独立 requestId，并等待该 stop request 的以下任一回执：
+
+- `kind: "event"` 且 `data.result.state: "stopped"`；
+- `kind: "response"` 且 `result.state: "stopped"`。
+
+SDK 会将两种消息结构统一为：
+
+```js
+{
+  requestId: '本次 stop UUID',
+  ok: true,
+  state: 'stopped'
+}
+```
+
+stop 调用和 start 的事件监听相互独立。Native 还会向原 start request 发送 `state: "stopped"`，由 start 监听自行结束。
+
+Native 映射：`rokid.tools / invoke / faceRecognize / stop`。
+
+## 完整示例
+
+```js
+import glass3 from 'rvis-aiui-kit';
+
+let recognizeRequestId = null;
+
+export default {
+  onMessage(messageEvent) {
+    glass3.handleMessage(messageEvent);
+  },
+
+  async start() {
+    const result = await glass3.face.startRecognize({}, {
+      onEvent(eventResult) {
+        console.log('face event:', JSON.stringify(eventResult));
+      }
+    });
+    recognizeRequestId = result.requestId;
+  },
+
+  stop() {
+    if (!recognizeRequestId) return;
+
+    glass3.face.stopRecognize({
+      requestId: recognizeRequestId
+    }).catch(error => {
+      if (error.code !== 'CALL_DISPOSED') {
+        console.error('stopRecognize failed:', JSON.stringify(error));
+      }
+    });
+    recognizeRequestId = null;
+  },
+
+  onUnload() {
+    this.stop();
+    glass3.dispose();
+  }
+};
+```
+
+## 错误
+
+参数错误会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。Native 事件返回 `ok: false` 时，尚未完成的 Promise 会以 `NATIVE_EVENT_ERROR` 拒绝。

package/sdk/modules/motion/index.js

@@ -0,0 +1,116 @@
+import {
+  COMPLETION_ACCEPTED,
+  COMPLETION_EVENT
+} from '../../core/constants.js';
+import {
+  snakeStringToCamelCase,
+  snakeToCamelCase
+} from '../../utils/case.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function buildStartDetectArgs(args) {
+  if (args === undefined || args === null) return {};
+
+  if (
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    Object.keys(args).length !== 0
+  ) {
+    throw createParameterError('motion.startDetect does not accept parameters');
+  }
+
+  return {};
+}
+
+function buildStopDetectArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError('motion.stopDetect requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('motion.stopDetect only supports requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+function transformMotionEventResult(result) {
+  const converted = snakeToCamelCase(result);
+  if (!converted || typeof converted !== 'object') return converted;
+
+  if (typeof converted.motionState === 'string') {
+    converted.motionState = snakeStringToCamelCase(converted.motionState);
+  }
+
+  if (typeof converted.previous === 'string') {
+    converted.previous = snakeStringToCamelCase(converted.previous);
+  }
+
+  return converted;
+}
+
+const motionStartDetect = {
+  publicModule: 'motion',
+  publicMethod: 'startDetect',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'motionDetect',
+  toolAction: 'start',
+
+  completion: COMPLETION_ACCEPTED,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  eventToolActions: ['start', 'stop'],
+  buildArgs: buildStartDetectArgs,
+  transformEventResult: transformMotionEventResult,
+  isTerminalResult(result) {
+    return Boolean(
+      result && (result.ok === false || result.state === 'stopped')
+    );
+  }
+};
+
+const motionStopDetect = {
+  publicModule: 'motion',
+  publicMethod: 'stopDetect',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'motionDetect',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  responseCompletionStates: ['stopped'],
+  buildArgs: buildStopDetectArgs,
+  transformEventResult: snakeToCamelCase,
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+export default [motionStartDetect, motionStopDetect];

package/sdk/modules/motion/readme.md

@@ -0,0 +1,148 @@
+# Motion API
+
+Motion 模块通过 `glass3.motion` 暴露运动状态检测能力。
+
+页面必须在 `onMessage` 中调用 `glass3.handleMessage(messageEvent)`，状态变化事件才能被关联到对应请求。
+
+| API | 说明 |
+| --- | --- |
+| `motion.startDetect` | 开启运动检测并持续接收状态变化。 |
+| `motion.stopDetect` | 停止指定的运动检测请求。 |
+
+## `motion.startDetect`
+
+开启运动状态检测。该接口没有业务参数，注册 `onEvent` 时第一个参数传空对象：
+
+```js
+const detection = await glass3.motion.startDetect(
+  {},
+  {
+    onEvent(eventResult) {
+      console.log('motion event:', JSON.stringify(eventResult));
+    }
+  }
+);
+```
+
+不需要事件回调时也可以直接调用：
+
+```js
+const detection = await glass3.motion.startDetect();
+```
+
+SDK 发送给 Native 的 `args` 始终为 `{}`。传入非空参数会抛出参数错误。
+
+### 返回值
+
+协议没有单独的启动确认事件，因此 Promise 在 fetch 返回 Native 已受理后完成，不等待第一个运动状态事件：
+
+```js
+{
+  requestId: '运动检测启动 UUID',
+  ok: true
+}
+```
+
+### 状态事件
+
+同一个 requestId 的状态变化会持续进入 `onEvent`。回调只接收 Native 消息中的 `message.data.result`：
+
+```js
+{
+  ok: true,
+  motionState: 'walk',
+  previous: 'still',
+  moving: true,
+  timestamp: 123456789
+}
+```
+
+运动状态包括：
+
+- `still`
+- `walk`
+- `run`
+- `headTurnLeft`
+- `headTurnRight`
+
+SDK 会递归地把事件结果中的下划线字段名转换成驼峰，例如 `motion_state` 转换为 `motionState`、`error_code` 转换为 `errorCode`。`motionState` 和 `previous` 的状态值也会转换成驼峰，例如 Native 的 `head_turn_left` 会作为 `headTurnLeft` 进入 `onEvent`。其他字符串值保持不变。
+
+Native 只在状态发生变化时上报。首个事件的 `previous` 为 `unknown`，SDK 不对事件进行去重或合并。
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `motionDetect` |
+| `toolAction` | `start` |
+
+请求协议版本为字符串 `"2.0.0"`。
+
+### 错误和监听释放
+
+- 参数不是空对象时，Promise 会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。
+- fetch 失败、响应协议不正确或 Native 未受理时，Promise 会按通用 RPC 错误规则抛出 `Glass3Error`。
+- Promise 已受理后收到 `{ ok: false }` 事件时，该结果会先进入 `onEvent`，随后 SDK 清理本次事件监听。
+- 未传 `onEvent` 时，SDK 不保留事件监听。
+- 如果原 start requestId 收到 `state: "stopped"` 终止事件，该结果会先进入 `onEvent`，随后 SDK 清理本次事件监听。
+
+## `motion.stopDetect`
+
+停止一次由 `motion.startDetect` 发起的运动检测：
+
+```js
+const result = await glass3.motion.stopDetect({
+  requestId: detection.requestId
+});
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `motion.startDetect` 返回的启动 requestId。只允许传该字段。 |
+
+SDK 会将参数转换成 Native 的 `args`：
+
+```js
+{
+  targetRequestId: detection.requestId
+}
+```
+
+stop 调用会生成自己的独立 requestId，不会复用 `targetRequestId`。
+
+### 返回值
+
+请求通过校验后，Promise 在收到 stop 自己的 requestId 对应的以下任一消息时完成：
+
+- `kind: "event"` 且 `data.result.state: "stopped"`；
+- `kind: "response"` 且 `result.state: "stopped"`。
+
+SDK 会将两种消息结构统一为：
+
+```js
+{
+  requestId: '本次 stop 调用的 UUID',
+  ok: true,
+  state: 'stopped'
+}
+```
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `motionDetect` |
+| `toolAction` | `stop` |
+
+stop 与 start 的 SDK 调用相互独立。stop 只等待自己的回执，不主动处理 start 的 Promise 或回调。
+
+### 错误
+
+- requestId 缺失、不是非空字符串或包含其他参数时，Promise 会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。
+- fetch 失败、Native 未受理或事件返回 `ok: false` 时，Promise 会按通用 RPC 错误规则抛出 `Glass3Error`。

package/sdk/modules/notification/index.js

@@ -0,0 +1,192 @@
+import { COMPLETION_EVENT } from '../../core/constants.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+const ALLOWED_FIELDS = [
+  'title',
+  'text',
+  'level',
+  'position',
+  'durationMs',
+  'animation',
+  'resident'
+];
+
+const LEVELS = ['active', 'critical'];
+
+const POSITIONS = [
+  'topLeft',
+  'topCenter',
+  'topRight',
+  'bottomLeft',
+  'bottomCenter',
+  'bottomRight'
+];
+
+const ANIMATIONS = [
+  'idle',
+  'blink',
+  'thinking',
+  'calm',
+  'nod',
+  'bow',
+  'salute',
+  'photo',
+  'face',
+  'scan',
+  'success',
+  'listening',
+  'speaking',
+  'enter',
+  'exit'
+];
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function normalizeText(input, name) {
+  if (input[name] === undefined) return '';
+  if (typeof input[name] !== 'string') {
+    throw createParameterError(`notification.show ${name} must be a string`);
+  }
+  return input[name];
+}
+
+function buildNotificationArgs(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    throw createParameterError('notification.show parameters must be an object');
+  }
+
+  const inputFields = Object.keys(args);
+  inputFields.forEach(name => {
+    if (ALLOWED_FIELDS.indexOf(name) === -1) {
+      throw createParameterError(`notification.show does not support ${name}`);
+    }
+  });
+
+  const title = normalizeText(args, 'title');
+  const text = normalizeText(args, 'text');
+  const hasTitle = args.title !== undefined;
+  const hasText = args.text !== undefined;
+  if (!hasTitle && !hasText) {
+    throw createParameterError(
+      'notification.show requires title or text'
+    );
+  }
+
+  let level = args.level === undefined ? 'active' : args.level;
+  if (LEVELS.indexOf(level) === -1) {
+    console.warn('[glass3] notification.show unsupported level; using active:', level);
+    level = 'active';
+  }
+
+  if (
+    args.position !== undefined &&
+    POSITIONS.indexOf(args.position) === -1
+  ) {
+    throw createParameterError('notification.show position is invalid');
+  }
+
+  if (
+    args.durationMs !== undefined &&
+    (!Number.isInteger(args.durationMs) || args.durationMs <= 0)
+  ) {
+    throw createParameterError(
+      'notification.show durationMs must be a positive integer'
+    );
+  }
+
+  const animation = args.animation === undefined ? 'idle' : args.animation;
+  if (ANIMATIONS.indexOf(animation) === -1) {
+    throw createParameterError(
+      `notification.show animation must be one of: ${ANIMATIONS.join(', ')}`
+    );
+  }
+
+  if (
+    args.resident !== undefined &&
+    typeof args.resident !== 'boolean'
+  ) {
+    throw createParameterError('notification.show resident must be a boolean');
+  }
+
+  const nativeArgs = { level, animation };
+  if (hasTitle) nativeArgs.title = title;
+  if (hasText) nativeArgs.text = text;
+  if (args.position !== undefined) nativeArgs.position = args.position;
+  if (args.durationMs !== undefined) nativeArgs.durationMs = args.durationMs;
+  if (args.resident !== undefined) nativeArgs.resident = args.resident;
+
+  return nativeArgs;
+}
+
+function buildHideNotificationArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError('notification.hide requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('notification.hide only supports requestId');
+  }
+
+  return { targetRequestId: args.requestId };
+}
+
+function selectEventResult(eventData) {
+  return {
+    requestId: eventData.requestId,
+    ok: eventData.result.ok
+  };
+}
+
+const notificationShow = {
+  publicModule: 'notification',
+  publicMethod: 'show',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'showNotification',
+  toolAction: 'start',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  isTerminalResult(result) {
+    return result.ok === true;
+  },
+  buildArgs: buildNotificationArgs,
+  selectEventResult
+};
+
+const notificationHide = {
+  publicModule: 'notification',
+  publicMethod: 'hide',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'showNotification',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  isTerminalResult(result) {
+    return result.ok === true;
+  },
+  buildArgs: buildHideNotificationArgs,
+  selectEventResult
+};
+
+export default [notificationShow, notificationHide];