rvis-aiui-kit 1.0.0

package/sdk/modules/notification/readme.md

@@ -0,0 +1,175 @@
+# Notification API
+
+Notification 模块通过 `glass3.notification` 显示 Native 消息通知。
+
+```js
+import glass3 from 'rvis-aiui-kit';
+```
+
+以上路径适用于 `pages` 下的一级页面，其他目录层级需要相应调整相对路径。
+
+| API | 说明 |
+| --- | --- |
+| `notification.show` | 显示一条 Native 消息通知。 |
+| `notification.hide` | 隐藏指定的消息通知。 |
+
+## `notification.show`
+
+```js
+const result = await glass3.notification.show({
+  text: '思考中',
+  level: 'active',
+  position: 'topCenter',
+  durationMs: 8000,
+  animation: 'thinking',
+  resident: true
+});
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `string` | 条件必填 | 无 | 通知标题。保留首尾空白，允许显式传空字符串。 |
+| `text` | `string` | 条件必填 | 无 | 通知正文。保留首尾空白，允许显式传空字符串。 |
+| `level` | `string` | 否 | `active` | 通知级别。 |
+| `position` | `string` | 否 | Native 默认值 | 通知显示位置。 |
+| `durationMs` | `number` | 否 | Native 默认值 | 显示时长，必须是大于 `0` 的整数；`0` 没有特殊含义。 |
+| `animation` | `string` | 否 | `idle` | 通知使用的表情动效。JS 调用方可不传，SDK 会向 Native 补充 `idle`。 |
+| `resident` | `boolean` | 否 | Native 默认值 | 是否常驻显示。传 `true` 时通知不会自动隐藏。 |
+
+`title` 和 `text` 至少需要提供一个字符串字段。SDK 会原样传递字符串（包括空字符串和纯空白字符串），用于创建无文案的常驻通知；未提供这两个字段时仍会抛出参数错误。
+
+`level` 为 `active` 或 `critical` 时原样传递；未提供时默认 `active`。传入其他值时，SDK 打印 warning 并按 `active` 处理，不抛出参数错误。
+
+`position` 可选值：
+
+- `topLeft`
+- `topCenter`
+- `topRight`
+- `bottomLeft`
+- `bottomCenter`
+- `bottomRight`
+
+`animation` 可选值：
+
+| 值 | 中文描述 |
+| --- | --- |
+| `idle` | 自然呼吸 |
+| `blink` | 轻微眨眼 |
+| `thinking` | 思考中 |
+| `calm` | 平静状态 |
+| `nod` | 点头 |
+| `bow` | 鞠躬 |
+| `salute` | 敬礼 |
+| `photo` | 拍照动作与快门反馈 |
+| `face` | 人脸识别动作 |
+| `scan` | 扫码动作与扫描光束 |
+| `success` | 工具完成动作 |
+| `listening` | 用户说话时产生水波纹 |
+| `speaking` | 眨眼与星光，表示乐奇正在说话 |
+| `enter` | 传送圈打开，球体进场 |
+| `exit` | 球体进入传送圈并退场 |
+
+未提供 `position`、`durationMs` 或 `resident` 时，SDK 不会补充这些字段。SDK 始终会补充默认的 `level: "active"` 和 `animation: "idle"`。
+
+### 返回值
+
+Promise 在 fetch 已受理且收到成功的 `toolResult` 事件后完成：
+
+```js
+{
+  requestId: '本次通知 UUID',
+  ok: true
+}
+```
+
+Native 返回的实际 `durationMs` 当前不会包含在公开返回值中。
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `showNotification` |
+| `toolAction` | `start` |
+
+请求协议版本为字符串 `"2.0.0"`。
+
+### 页面接入
+
+页面需要把宿主消息交给 SDK，否则等待结果的 Promise 不会完成：
+
+```js
+import glass3 from 'rvis-aiui-kit';
+
+export default {
+  onMessage(messageEvent) {
+    glass3.handleMessage(messageEvent);
+  },
+
+  onUnload() {
+    glass3.dispose();
+  }
+};
+```
+
+### 错误
+
+不支持的字段、无效的 `position` / `animation`、无效时长或非布尔类型的 `resident` 会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。非法 `level` 仅打印 warning 并回退到 `active`。Native 返回 `ok: false` 时，Promise 会以 `NATIVE_EVENT_ERROR` 拒绝。
+
+## `notification.hide`
+
+隐藏一次由 `notification.show` 显示的通知：
+
+```js
+const hiddenResult = await glass3.notification.hide({
+  requestId: result.requestId
+});
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `requestId` | `string` | 是 | `notification.show` 返回的通知 requestId。只允许传该字段。 |
+
+无论目标通知是否常驻，SDK 都会将参数转换成相同的 Native `args`：
+
+```js
+{
+  targetRequestId: result.requestId
+}
+```
+
+hide 调用会生成自己的独立 requestId，不会复用目标通知的 requestId。
+
+### 返回值
+
+Promise 在 fetch 已受理且收到 hide 调用自身 requestId 对应的成功 `toolResult` 后完成：
+
+```js
+{
+  requestId: '本次 hide 调用的 UUID',
+  ok: true
+}
+```
+
+当前 Native 协议没有约定必须匹配的状态字符串，因此 SDK 使用 `result.ok === true` 作为隐藏完成条件。
+
+### Native 映射
+
+| 字段 | 值 |
+| --- | --- |
+| `namespace` | `rokid.tools` |
+| `method` | `invoke` |
+| `toolName` | `showNotification` |
+| `toolAction` | `stop` |
+
+请求协议版本为字符串 `"2.0.0"`。
+
+### 错误
+
+- requestId 缺失、不是非空字符串或包含其他字段时，Promise 会抛出错误码为 `INVALID_PARAMS` 的 `Glass3Error`。
+- fetch 失败、响应协议不正确、Native 未受理或事件返回 `ok: false` 时，Promise 会按通用 RPC 错误规则抛出 `Glass3Error`。

package/sdk/modules/offline-command/index.js

@@ -0,0 +1,265 @@
+import {
+  COMPLETION_EVENT,
+  COMPLETION_READY_EVENT_STREAM
+} from '../../core/constants.js';
+import { snakeToCamelCase } from '../../utils/case.js';
+import { Glass3Error } from '../../utils/errors.js';
+
+const DEFAULT_LANGUAGE = 'ZH_CN';
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function validatePhrase(phrase, commandIndex, phraseIndex) {
+  if (!phrase || typeof phrase !== 'object' || Array.isArray(phrase)) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}].phrases[${phraseIndex}] must be an object`
+    );
+  }
+
+  const fields = Object.keys(phrase);
+  fields.forEach(name => {
+    if (name !== 'text' && name !== 'pinyin') {
+      throw createParameterError(
+        `offlineCommand.register phrase does not support ${name}`
+      );
+    }
+  });
+
+  if (typeof phrase.text !== 'string' || !phrase.text.trim()) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}].phrases[${phraseIndex}].text must be a non-empty string`
+    );
+  }
+
+  if (
+    phrase.pinyin !== undefined &&
+    (typeof phrase.pinyin !== 'string' || !phrase.pinyin.trim())
+  ) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}].phrases[${phraseIndex}].pinyin must be a non-empty string`
+    );
+  }
+
+  const nativePhrase = { text: phrase.text };
+  if (phrase.pinyin !== undefined) {
+    nativePhrase.pinyin = phrase.pinyin;
+  }
+  return nativePhrase;
+}
+
+function validateCommand(command, commandIndex) {
+  if (!command || typeof command !== 'object' || Array.isArray(command)) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}] must be an object`
+    );
+  }
+
+  const fields = Object.keys(command);
+  fields.forEach(name => {
+    if (name !== 'id' && name !== 'phrases') {
+      throw createParameterError(
+        `offlineCommand.register command does not support ${name}`
+      );
+    }
+  });
+
+  if (typeof command.id !== 'string' || !command.id.trim()) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}].id must be a non-empty string`
+    );
+  }
+
+  if (!Array.isArray(command.phrases) || command.phrases.length === 0) {
+    throw createParameterError(
+      `offlineCommand.register commands[${commandIndex}].phrases must be a non-empty array`
+    );
+  }
+
+  return {
+    id: command.id,
+    phrases: command.phrases.map((phrase, phraseIndex) => (
+      validatePhrase(phrase, commandIndex, phraseIndex)
+    ))
+  };
+}
+
+function buildRegisterArgs(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    throw createParameterError(
+      'offlineCommand.register parameters must be an object'
+    );
+  }
+
+  const fields = Object.keys(args);
+  fields.forEach(name => {
+    if (name !== 'language' && name !== 'commands') {
+      throw createParameterError(
+        `offlineCommand.register does not support ${name}`
+      );
+    }
+  });
+
+  const language = args.language === undefined
+    ? DEFAULT_LANGUAGE
+    : args.language;
+  if (typeof language !== 'string' || !language.trim()) {
+    throw createParameterError(
+      'offlineCommand.register language must be a non-empty string'
+    );
+  }
+
+  if (!Array.isArray(args.commands) || args.commands.length === 0) {
+    throw createParameterError(
+      'offlineCommand.register commands must be a non-empty array'
+    );
+  }
+
+  return {
+    language,
+    commands: args.commands.map(validateCommand)
+  };
+}
+
+function buildUnregisterArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError(
+      'offlineCommand.unregister requires a requestId'
+    );
+  }
+
+  const fields = Object.keys(args);
+  if (fields.length !== 1 || fields[0] !== 'requestId') {
+    throw createParameterError(
+      'offlineCommand.unregister only supports requestId'
+    );
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+function selectRegisterResponseResult(response) {
+  return Object.assign(
+    { ok: response.ok },
+    snakeToCamelCase(response.result)
+  );
+}
+
+function selectRegisterReadyResult(requestId, result) {
+  const readyResult = {
+    requestId,
+    ok: result.ok !== false,
+    state: result.state
+  };
+
+  if (result.commandCount !== undefined) {
+    readyResult.commandCount = result.commandCount;
+  }
+  if (result.phraseCount !== undefined) {
+    readyResult.phraseCount = result.phraseCount;
+  }
+  return readyResult;
+}
+
+function isAcceptedOrStateResponseResult(
+  result,
+  requestId,
+  toolAction,
+  state
+) {
+  if (!result || typeof result !== 'object') return false;
+  if (result.state === state) return true;
+
+  return result.accepted === true &&
+    result.requestId === requestId &&
+    result.toolName === 'offlineCommand' &&
+    result.toolAction === toolAction;
+}
+
+const offlineCommandRegister = {
+  publicModule: 'offlineCommand',
+  publicMethod: 'register',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'offlineCommand',
+  toolAction: 'start',
+
+  completion: COMPLETION_READY_EVENT_STREAM,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  responseCompletionStates: ['started'],
+  buildArgs: buildRegisterArgs,
+  transformEventResult: snakeToCamelCase,
+  selectResponseResult: selectRegisterResponseResult,
+  isAcceptedResponseResult(result, requestId) {
+    return isAcceptedOrStateResponseResult(
+      result,
+      requestId,
+      'start',
+      'started'
+    );
+  },
+  isErrorResult(result) {
+    return Boolean(result && result.ok === false);
+  },
+  isReadyResult(result) {
+    return Boolean(result && result.ok === true && result.state === 'started');
+  },
+  isStreamTerminalResult(result) {
+    return Boolean(result && result.state === 'canceled');
+  },
+  selectReadyResult: selectRegisterReadyResult
+};
+
+const offlineCommandUnregister = {
+  publicModule: 'offlineCommand',
+  publicMethod: 'unregister',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'offlineCommand',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  responseCompletionStates: ['stopped'],
+  buildArgs: buildUnregisterArgs,
+  transformEventResult: snakeToCamelCase,
+  isAcceptedResponseResult(result, requestId) {
+    return isAcceptedOrStateResponseResult(
+      result,
+      requestId,
+      'stop',
+      'stopped'
+    );
+  },
+  releaseTargetInvocation: {
+    publicModule: 'offlineCommand',
+    publicMethod: 'register'
+  },
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+export default [offlineCommandRegister, offlineCommandUnregister];

package/sdk/modules/offline-command/readme.md

@@ -0,0 +1,143 @@
+# Offline Command API
+
+Offline Command 模块通过 `glass3.offlineCommand` 注册和注销页面持有的离线语音指令批次。
+
+页面必须将 `onMessage(messageEvent)` 转发给 `glass3.handleMessage(messageEvent)`，命中和终止事件才能关联到对应注册请求。
+
+## API 列表
+
+| API | 说明 |
+| --- | --- |
+| `offlineCommand.register` | 注册一批离线指令，并持续接收命中事件。 |
+| `offlineCommand.unregister` | 注销指定的离线指令批次。 |
+
+## `offlineCommand.register`
+
+```js
+const registration = await glass3.offlineCommand.register(
+  {
+    commands: [
+      {
+        id: 'next_step',
+        phrases: [
+          { text: '下一步', pinyin: 'xia yi bu' },
+          { text: '继续', pinyin: 'ji xu' }
+        ]
+      }
+    ]
+  },
+  {
+    onEvent(result) {
+      console.log('offline command event:', JSON.stringify(result));
+    }
+  }
+);
+```
+
+### 参数
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `language` | `string` | 否 | `ZH_CN` | 传给 Native 的语言标识。SDK 不限制枚举值。 |
+| `commands` | `array` | 是 | - | 非空的指令数组。 |
+
+每个 command 包含：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | 是 | 非空业务指令 ID。 |
+| `phrases` | `array` | 是 | 非空的触发短语数组。 |
+
+每个 phrase 包含：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `string` | 是 | 非空触发文本。 |
+| `pinyin` | `string` | 否 | 非空拼音文本；省略时不会传给 Native。 |
+
+SDK 校验对象、数组和字段类型，但不限制语言枚举、数组数量、字符串长度、重复 command ID 或重复 phrase。参数是闭集，不接受 snake_case 或未记录字段。
+
+开发规则：每个 phrase 都必须填写非空 `pinyin`，不要因为 SDK 允许省略而省略拼音。SDK 注册的离线指令必须通过 `register` 第二个参数中的 `onEvent` 接收，以 `result.commandId` 区分命中；不能使用 `onVoiceWakeup` / `onVoiceWakeUp` 或 `event.keyword` 监听。后者属于宿主唤醒词事件，不是 SDK 离线指令命中通道。
+
+下行映射为 `rokid.tools / invoke / offlineCommand / start`。未传 `language` 时，Native `args.language` 为 `ZH_CN`。
+
+### 注册完成
+
+started 可能通过 response 或 event 到达，两者到达顺序不固定。SDK 记录先到的 started，并在同一请求的 response 已受理后完成 Promise；普通 `accepted` response 本身不会结束 Promise。
+
+JS 返回值全部使用驼峰字段：
+
+```js
+{
+  requestId: 'cmd-1',
+  ok: true,
+  state: 'started',
+  commandCount: 1,
+  phraseCount: 2
+}
+```
+
+如果 started 消息没有携带数量，对应 `commandCount` 或 `phraseCount` 字段不会出现在返回值中。
+
+### 命中事件
+
+同一个 start requestId 可以多次进入 `onEvent`：
+
+```js
+{
+  ok: true,
+  commandId: 'next_step',
+  phrase: '下一步',
+  timestamp: 1785403248395
+}
+```
+
+Native 下划线字段会递归转换为驼峰。
+
+### 页面关闭
+
+AIX 页面关闭时，Native 在原 start requestId 上发送唯一终态事件：
+
+```js
+{
+  ok: true,
+  state: 'canceled',
+  reason: 'owner_release'
+}
+```
+
+该结果进入 `onEvent` 后，SDK 清理本次注册监听。
+
+## `offlineCommand.unregister`
+
+```js
+const result = await glass3.offlineCommand.unregister({
+  requestId: registration.requestId
+});
+```
+
+JS 侧只接受 register 返回的非空 `requestId`。SDK 为 unregister 生成独立 requestId，并将参数转换为：
+
+```js
+{
+  targetRequestId: registration.requestId
+}
+```
+
+下行映射为 `rokid.tools / invoke / offlineCommand / stop`。
+
+stopped 可能通过 response 或 event 到达，两者到达顺序不固定。SDK 记录先到的 stopped，并在 response 已受理后完成 Promise：
+
+```js
+{
+  requestId: 'cmd-2',
+  ok: true,
+  state: 'stopped'
+}
+```
+
+unregister 成功后，SDK 会释放目标 register 的事件监听。Native 不需要向原 start requestId 补发 stopped event。
+
+## 生命周期
+
+页面应保存 register 返回的 `requestId`。示例使用系统默认退出行为，在 `onUnload()` 中发起 unregister，不等待 stopped 结果，然后立即调用 `glass3.dispose()`；Native 的 `owner_release` 事件作为页面直接关闭时的终态兜底。

package/sdk/modules/screen/index.js

@@ -0,0 +1,64 @@
+import { COMPLETION_EVENT } from '../../core/constants.js';
+import { 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 buildScreenArgs(powerState, publicMethod) {
+  return args => {
+    if (args !== undefined && args !== null) {
+      if (
+        typeof args !== 'object' ||
+        Array.isArray(args) ||
+        Object.keys(args).length !== 0
+      ) {
+        throw createParameterError(
+          `screen.${publicMethod} does not accept parameters`
+        );
+      }
+    }
+
+    return { state: powerState };
+  };
+}
+
+function selectEventResult(eventData) {
+  return Object.assign(
+    { requestId: eventData.requestId },
+    snakeToCamelCase(eventData.result)
+  );
+}
+
+function createScreenDefinition(publicMethod, powerState) {
+  return {
+    publicModule: 'screen',
+    publicMethod,
+
+    namespace: 'rokid.tools',
+    method: 'invoke',
+    toolName: 'screenOff',
+    toolAction: 'start',
+
+    completion: COMPLETION_EVENT,
+    eventNamespace: 'rokid.tools',
+    eventName: 'toolResult',
+    buildArgs: buildScreenArgs(powerState, publicMethod),
+    transformEventResult: snakeToCamelCase,
+    isTerminalResult(result) {
+      return Boolean(result && result.screen === powerState);
+    },
+    selectEventResult
+  };
+}
+
+export default [
+  createScreenDefinition('turnOff', 'off'),
+  createScreenDefinition('turnOn', 'on')
+];