rvis-aiui-kit 1.0.0

package/sdk/core/transport.js

@@ -0,0 +1,55 @@
+import {
+  RPC_SUCCESS_STATUS_MAX,
+  RPC_SUCCESS_STATUS_MIN,
+  RPC_URL
+} from './constants.js';
+import { Glass3Error } from '../utils/errors.js';
+import { redactSensitiveDataForLog } from '../utils/message.js';
+
+export class HostRpcTransport {
+  constructor(options) {
+    const transportOptions = options || {};
+    this.url = transportOptions.url || RPC_URL;
+    this.fetchImpl = transportOptions.fetchImpl || null;
+  }
+
+  send(request) {
+    const requestFetch = this.fetchImpl || fetch;
+    const requestBody = JSON.stringify(request);
+
+    console.log(
+      '[glass3] Native request 7:',
+      JSON.stringify(redactSensitiveDataForLog(request))
+    );
+
+    return requestFetch(this.url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: requestBody
+    }).then(response => {
+      if (
+        response.status < RPC_SUCCESS_STATUS_MIN ||
+        response.status > RPC_SUCCESS_STATUS_MAX
+      ) {
+        throw new Glass3Error(
+          `Host RPC transport rejected: ${response.status}`,
+          {
+            code: 'TRANSPORT_REJECTED',
+            stage: 'transport',
+            requestId: request.requestId,
+            namespace: request.namespace,
+            method: request.method
+          }
+        );
+      }
+
+      return response.json();
+    }).then(result => {
+      console.log(
+        '[glass3] Native fetch response:',
+        JSON.stringify(redactSensitiveDataForLog(result))
+      );
+      return result;
+    });
+  }
+}

package/sdk/index.js

@@ -0,0 +1,19 @@
+import API_MAP from './api-map.js';
+import { Glass3Client } from './core/client.js';
+import { createApiNamespaces } from './utils/api-builder.js';
+
+const client = new Glass3Client();
+const glass3 = createApiNamespaces(client, API_MAP);
+
+glass3.handleMessage = function handleMessage(messageEvent) {
+  return client.handleMessage(messageEvent);
+};
+
+glass3.dispose = function dispose() {
+  client.dispose();
+};
+
+export { API_MAP } from './api-map.js';
+export { Glass3Error } from './utils/errors.js';
+export { glass3 };
+export default glass3;

package/sdk/modules/audio/index.js

@@ -0,0 +1,177 @@
+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_MAX_MINUTES = 10;
+const MAX_MAX_MINUTES = 120;
+
+function createParameterError(message) {
+  return new Glass3Error(message, {
+    code: 'INVALID_PARAMS',
+    stage: 'params',
+    namespace: 'rokid.tools',
+    method: 'invoke'
+  });
+}
+
+function buildStartRecordArgs(args) {
+  if (
+    args !== undefined &&
+    args !== null &&
+    (typeof args !== 'object' || Array.isArray(args))
+  ) {
+    throw createParameterError('audio.startRecord parameters must be an object');
+  }
+
+  const input = args || {};
+  Object.keys(input).forEach(name => {
+    if (
+      name !== 'maxMinutes' &&
+      name !== 'needText' &&
+      name !== 'needMp3' &&
+      name !== 'showCard' &&
+      name !== 'upload'
+    ) {
+      throw createParameterError(`audio.startRecord does not support ${name}`);
+    }
+  });
+
+  const maxMinutes = input.maxMinutes === undefined
+    ? DEFAULT_MAX_MINUTES
+    : input.maxMinutes;
+  const needText = input.needText === undefined ? true : input.needText;
+  const needMp3 = input.needMp3 === undefined ? false : input.needMp3;
+  const showCard = input.showCard === undefined ? true : input.showCard;
+  const upload = input.upload === undefined ? false : input.upload;
+
+  if (
+    !Number.isInteger(maxMinutes) ||
+    maxMinutes <= 0 ||
+    maxMinutes > MAX_MAX_MINUTES
+  ) {
+    throw createParameterError(
+      'audio.startRecord maxMinutes must be an integer from 1 to 120'
+    );
+  }
+
+  if (typeof needText !== 'boolean') {
+    throw createParameterError('audio.startRecord needText must be a boolean');
+  }
+
+  if (typeof needMp3 !== 'boolean') {
+    throw createParameterError('audio.startRecord needMp3 must be a boolean');
+  }
+
+  if (typeof showCard !== 'boolean') {
+    throw createParameterError('audio.startRecord showCard must be a boolean');
+  }
+
+  if (typeof upload !== 'boolean') {
+    throw createParameterError('audio.startRecord upload must be a boolean');
+  }
+
+  return {
+    max_minutes: maxMinutes,
+    need_text: needText,
+    need_mp3: needMp3,
+    show_card: showCard,
+    upload
+  };
+}
+
+function buildStopRecordArgs(args) {
+  if (
+    !args ||
+    typeof args !== 'object' ||
+    Array.isArray(args) ||
+    typeof args.requestId !== 'string' ||
+    !args.requestId.trim()
+  ) {
+    throw createParameterError('audio.stopRecord requires a requestId');
+  }
+
+  const inputFields = Object.keys(args);
+  if (inputFields.length !== 1 || inputFields[0] !== 'requestId') {
+    throw createParameterError('audio.stopRecord only supports requestId');
+  }
+
+  return {
+    targetRequestId: args.requestId
+  };
+}
+
+const audioStartRecord = {
+  publicModule: 'audio',
+  publicMethod: 'startRecord',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'audioRecord',
+  toolAction: 'start',
+
+  completion: COMPLETION_READY_EVENT_STREAM,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  responseCompletionStates: ['started'],
+  buildArgs: buildStartRecordArgs,
+  transformEventResult: snakeToCamelCase,
+  isAcceptedResponseResult(result) {
+    return Boolean(
+      result &&
+      result.state === 'started' &&
+      result.ok !== false
+    );
+  },
+  isErrorResult(result) {
+    return Boolean(result && result.ok === false);
+  },
+  isStreamTerminalResult(result) {
+    return Boolean(
+      result &&
+      (
+        result.ok === false ||
+        result.state === 'finished' ||
+        result.state === 'canceled'
+      )
+    );
+  },
+  selectReadyResult(requestId, result) {
+    return {
+      requestId,
+      ok: result.ok,
+      state: result.state
+    };
+  }
+};
+
+const audioStopRecord = {
+  publicModule: 'audio',
+  publicMethod: 'stopRecord',
+
+  namespace: 'rokid.tools',
+  method: 'invoke',
+  toolName: 'audioRecord',
+  toolAction: 'stop',
+
+  completion: COMPLETION_EVENT,
+  eventNamespace: 'rokid.tools',
+  eventName: 'toolResult',
+  terminalStates: ['stopped'],
+  buildArgs: buildStopRecordArgs,
+  transformEventResult: snakeToCamelCase,
+  releaseTargetInvocation: {
+    publicModule: 'audio',
+    publicMethod: 'startRecord'
+  },
+  selectEventResult(eventData) {
+    return Object.assign(
+      { requestId: eventData.requestId },
+      snakeToCamelCase(eventData.result)
+    );
+  }
+};
+
+export default [audioStartRecord, audioStopRecord];

package/sdk/modules/audio/readme.md

@@ -0,0 +1,136 @@
+# Audio Recording API
+
+Audio 模块通过 `glass3.audio` 暴露眼镜麦克风录音能力。录音是长任务，页面必须将 `onMessage(messageEvent)` 转发给 `glass3.handleMessage(messageEvent)`。
+
+## API 列表
+
+| API | 说明 |
+| --- | --- |
+| `audio.startRecord` | 开始录音，等待 Native 的 started response。 |
+| `audio.stopRecord` | 停止指定录音，等待 stop requestId 的 stopped event。 |
+
+## `audio.startRecord`
+
+```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 UI。 |
+| `upload` | `boolean` | `false` | 是否将录音结果上传云端。 |
+
+SDK 将参数转换成 Native 的 `max_minutes`、`need_text`、`need_mp3`、`show_card` 和 `upload`。默认只转写文本，纯文本模式不落音频文件。Native 使用 16kHz / 16bit / 单声道共享采集通道，录音可与执法记录并存；`needMp3: true` 时音频按 AAC/MP4 编码并使用 `.mp3` 后缀。
+
+`showCard: true` 时，录音期间眼镜端由 Native 显示录音小框。录音任务会监听离线语音指令“结束录音”。
+
+start 只等待同一 requestId 的 `kind: "response"`，并要求 `result.state: "started"`。started event 不会结束 Promise。返回值为：
+
+```js
+{
+  requestId: '录音 start UUID',
+  ok: true,
+  state: 'started'
+}
+```
+
+start 完成后，自动结束、用户离线指令结束和异步失败仍通过原 start requestId 进入 `onEvent`。事件结果字段会递归转换成驼峰。
+
+maxMinutes 到点：
+
+```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
+}
+```
+
+`fileUrl` 仅在 `upload: true` 且上传成功时出现。
+
+用户在眼镜端说“结束录音”：
+
+```js
+{
+  ok: true,
+  finished: true,
+  state: 'finished',
+  reason: 'offline_command',
+  durationMs: 5140,
+  text: '整段转写文本',
+  filePath: '/path/to/tool_audio.mp3'
+}
+```
+
+start 成功后 2 秒内采不到声音时，Native 清理录音并异步返回：
+
+```js
+{ ok: false, error: 'mic_busy' }
+```
+
+`needText: true` 但 ASR 不可用时，本次录音作废并返回：
+
+```js
+{ ok: false, error: 'asr_unavailable' }
+```
+
+失败事件会先进入 `onEvent`，随后 SDK 清理该 start 的事件监听。
+
+Native 映射：`rokid.tools / invoke / audioRecord / start`。
+
+## `audio.stopRecord`
+
+```js
+const result = await glass3.audio.stopRecord({
+  requestId: recording.requestId
+});
+```
+
+只接受 start 返回的非空 `requestId`。SDK 将其转换为 `{ targetRequestId }`，并为 stop 生成独立 requestId。
+
+stop 的 Promise 只等待归属 stop requestId 的唯一 `state: "stopped"` event，不等待原 start requestId 的事件。完成结果直接包含成果：
+
+```js
+{
+  requestId: '本次 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
+}
+```
+
+stop 成功后 SDK 会释放原 start 的事件监听。
+
+Native 映射：`rokid.tools / invoke / audioRecord / stop`。
+
+## 生命周期
+
+页面卸载时应清除计时器、尽力调用 `audio.stopRecord({ requestId })`，再调用 `glass3.dispose()`。