rvis-aiui-kit 1.1.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rvis-aiui-kit",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "RVIS AIUI components and Glass3 extension SDK.",
   "type": "module",
   "main": "./sdk/index.js",

package/sdk/README.md

@@ -1,8 +1,8 @@
 # Glass3 扩展 SDK API 文档
 
-本文档汇总 `sdk/` 目录当前公开的 JavaScript API。公开接口以
-[`api-map.js`](./api-map.js) 为准；各模块的 `readme.md` 提供更完整的 Native
-协议、事件时序与返回示例。
+本文档汇总 `sdk/` 目录当前公开的 JavaScript API。Host RPC 接口以
+[`api-map.js`](./api-map.js) 为准；`glass3.openapi` 是独立的 HTTPS/SSE 客户端。
+各模块的 `readme.md` 提供更完整的协议、事件时序与返回示例。
 
 > 适用范围：项目内的 Host RPC 扩展能力。若 `glass3` 已提供对应能力，应优先使用
 > 本 SDK；只有 SDK 未覆盖的能力才使用基础 AIUI 运行时 API。
@@ -13,6 +13,7 @@
 - [API 总览](#api-总览)
 - [通用调用约定](#通用调用约定)
 - [Device Context 设备上下文](#device-context-设备上下文)
+- [Status Bar 原生状态栏](#status-bar-原生状态栏)
 - [Screen 屏幕控制](#screen-屏幕控制)
 - [Notification 原生通知](#notification-原生通知)
 - [TTS 语音播报](#tts-语音播报)
@@ -21,6 +22,7 @@
 - [Camera 相机](#camera-相机)
 - [Face 人脸识别](#face-人脸识别)
 - [Motion 运动状态检测](#motion-运动状态检测)
+- [OpenAPI](#openapi)
 - [错误处理](#错误处理)
 - [页面卸载清理](#页面卸载清理)
 - [Native 映射](#native-映射)
@@ -64,6 +66,8 @@ import glass3, {
 
 | 模块 | 方法 | 用途 |
 | --- | --- | --- |
+| `statusBar` | `setTitle({ title })` | 设置或清理当前 AIX 页面的状态栏标题。 |
+| `statusBar` | `setVisible({ visible })` | 显示或重新隐藏 Native 状态栏。 |
 | `deviceContext` | `get(options?)` | 一次性获取设备上下文原子快照。 |
 | `deviceContext` | `observe(options?, callOptions?)` | 订阅设备上下文快照和增量变化。 |
 | `deviceContext` | `stopObserve({ requestId })` | 停止指定的设备上下文订阅。 |
@@ -86,6 +90,8 @@ import glass3, {
 | `face` | `stopRecognize({ requestId })` | 停止指定人脸识别。 |
 | `motion` | `startDetect({}, callOptions?)` | 开始持续运动状态检测。 |
 | `motion` | `stopDetect({ requestId })` | 停止指定运动检测。 |
+| `openapi` | `setConfig({ baseUrl?, apiKey })` | 配置全局 OpenAPI 客户端。 |
+| `openapi` | `visionExtract(params, callOptions?)` | 通过 POST SSE 识别图片。 |
 
 客户端级方法：
 
@@ -215,6 +221,25 @@ const result = await glass3.deviceContext.stopObserve({
 
 详见 [`modules/device-context/readme.md`](./modules/device-context/readme.md)。
 
+## Status Bar 原生状态栏
+
+状态栏是 Host 管理的系统 UI，可在屏幕顶部显示标题、时间、网络和电量。该能力只在
+通过 `OPEN_AIX_INK` 外部入口打开的 AIX 页面中注册，页面创建后默认隐藏。
+
+建议先设置标题，再显示：
+
+```js
+await glass3.statusBar.setTitle({ title: '设备巡检' });
+const result = await glass3.statusBar.setVisible({ visible: true });
+// { updated: true, visible: true }
+```
+
+`title` 必须是字符串；空字符串或全空白字符串用于清理标题。`visible` 必须是
+Boolean。两个方法直接解析 Host RPC HTTP response body，不依赖 `onMessage`，并有
+5 秒本地等待上限。
+
+详见 [`modules/status-bar/readme.md`](./modules/status-bar/readme.md)。
+
 ## Screen 屏幕控制
 
 ### `glass3.screen.turnOff()`
@@ -851,6 +876,36 @@ const result = await glass3.motion.stopDetect({
 
 详见 [`modules/motion/readme.md`](./modules/motion/readme.md)。
 
+## OpenAPI
+
+`glass3.openapi` 是全局 HTTPS/SSE 客户端，不经过 Host RPC：
+
+```js
+glass3.openapi.setConfig({
+  apiKey: '<AK>'
+});
+
+const result = await glass3.openapi.visionExtract(
+  {
+    image: 'data:image/jpeg;base64,...',
+    prompt: '图中有什么安全隐患',
+    uiType: 'table',
+    fields: [
+      { name: 'hazard', title: '隐患', type: 'string' }
+    ]
+  },
+  {
+    onEvent(event) {
+      console.log(event.type, JSON.stringify(event.data));
+    }
+  }
+);
+```
+
+`baseUrl` 默认是 `https://api.rokid.com`；测试环境需要显式配置。
+Promise 在收到 `[DONE]` 后返回最终 `result`。`glass3.dispose()` 会关闭并拒绝尚未
+完成的 OpenAPI 请求。详见 [`modules/openapi/readme.md`](./modules/openapi/readme.md)。
+
 ## 错误处理
 
 所有 SDK 错误都使用 `Glass3Error`：
@@ -889,6 +944,11 @@ try {
 | `NATIVE_EVENT_ERROR` | 匹配的 Native event 返回失败。 |
 | `CALL_TIMEOUT` | JS 等待超时；当前用于 `camera.takePhoto()`。 |
 | `CALL_DISPOSED` | 调用尚未完成时执行了 `glass3.dispose()`。 |
+| `OPENAPI_NOT_CONFIGURED` | 调用 OpenAPI 前没有执行 `setConfig()`。 |
+| `OPENAPI_HTTP_ERROR` | OpenAPI 返回非成功 HTTP 状态。 |
+| `OPENAPI_STREAM_ERROR` | SSE 连接或传输失败。 |
+| `OPENAPI_PROTOCOL_ERROR` | SSE 未按约定返回结果或结束标记。 |
+| `OPENAPI_SERVICE_ERROR` | OpenAPI 返回 `event:error`。 |
 | `GLASS3_ERROR` | 未提供更具体错误码时的默认值。 |
 
 Native 也可能直接返回自己的错误码。需要恢复策略时，应按 `error.code` 判断，不要
@@ -948,8 +1008,8 @@ export default {
 
 ## Native 映射
 
-所有业务调用使用 RPC `version: "2.0.0"`、`namespace: "rokid.tools"`、
-`method: "invoke"`。
+除 `statusBar` 外的 Host RPC 业务调用使用 `version: "2.0.0"`、
+`namespace: "rokid.tools"`、`method: "invoke"`。
 
 | JavaScript API | `toolName` | `toolAction` |
 | --- | --- | --- |
@@ -976,12 +1036,16 @@ export default {
 | `motion.startDetect` | `motionDetect` | `start` |
 | `motion.stopDetect` | `motionDetect` | `stop` |
 
+`statusBar.setTitle` 和 `statusBar.setVisible` 使用 `namespace: "rokid.statusBar"`，
+Native method 分别为 `setTitle` 和 `setVisible`，业务参数直接放在 `params` 中。
+
 业务代码应调用公开 JavaScript API，不要直接依赖这张 Native 映射表发 RPC。
 
 ## 详细文档与 Demo
 
 ### 模块文档
 
+- [Status Bar](./modules/status-bar/readme.md)
 - [Device Context](./modules/device-context/readme.md)
 - [Screen](./modules/screen/readme.md)
 - [Notification](./modules/notification/readme.md)
@@ -994,6 +1058,7 @@ export default {
 
 ### 示例页面
 
+- [Status Bar Demo](../pages/sdk-demo/status-bar/index.ink)
 - [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)

package/sdk/api-map.js

@@ -6,11 +6,13 @@ import motion from './modules/motion/index.js';
 import notification from './modules/notification/index.js';
 import offlineCommand from './modules/offline-command/index.js';
 import screen from './modules/screen/index.js';
+import statusBar from './modules/status-bar/index.js';
 import tts from './modules/tts/index.js';
 
 // This map is the only mapping between the public JavaScript API and Host RPC.
 // Public names are never inferred from the native namespace or method strings.
 export const API_MAP = [].concat(
+  statusBar,
   deviceContext,
   notification,
   screen,

package/sdk/core/client.js

@@ -43,12 +43,14 @@ export class Glass3Client {
       requestId,
       namespace: definition.namespace,
       method: definition.method,
-      params: {
-        toolName: definition.toolName,
-        toolAction: definition.toolAction,
-        args: nativeArgs,
-        extra: {}
-      }
+      params: typeof definition.buildRequestParams === 'function'
+        ? definition.buildRequestParams(nativeArgs)
+        : {
+            toolName: definition.toolName,
+            toolAction: definition.toolAction,
+            args: nativeArgs,
+            extra: {}
+          }
     };
 
     if (definition.completion === COMPLETION_EVENT) {
@@ -59,7 +61,12 @@ export class Glass3Client {
       return this.invokeUntilReadyEventStream(definition, request, callOptions);
     }
 
-    return this.invokeUntilAccepted(definition, request, callOptions);
+    return this.invokeUntilAccepted(
+      definition,
+      request,
+      callOptions,
+      timeoutMs
+    );
   }
 
   sendRequest(definition, request) {
@@ -104,7 +111,7 @@ export class Glass3Client {
     return true;
   }
 
-  invokeUntilAccepted(definition, request, callOptions) {
+  invokeUntilAccepted(definition, request, callOptions, timeoutMs) {
     if (typeof callOptions.onEvent === 'function') {
       this.activeInvocations.set(request.requestId, {
         requestId: request.requestId,
@@ -113,13 +120,37 @@ export class Glass3Client {
       });
     }
 
-    return this.sendRequest(definition, request).then(response => {
+    let timeoutId = null;
+    const responsePromise = this.sendRequest(definition, request);
+
+    if (timeoutMs !== undefined) {
+      timeoutId = setTimeout(() => {
+        this.rejectPendingResponse(request.requestId, new Glass3Error(
+          `Glass3 call timed out after ${timeoutMs}ms: ${definition.publicModule}.${definition.publicMethod}`,
+          {
+            code: 'CALL_TIMEOUT',
+            stage: 'timeout',
+            requestId: request.requestId,
+            namespace: definition.namespace,
+            method: definition.method,
+            details: { timeout: timeoutMs }
+          }
+        ));
+      }, timeoutMs);
+    }
+
+    return responsePromise.then(response => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
       this.validateAcceptedResponse(definition, request.requestId, response);
+      if (typeof definition.selectAcceptedResult === 'function') {
+        return definition.selectAcceptedResult(response);
+      }
       return {
         requestId: response.requestId,
         ok: response.ok
       };
     }).catch(error => {
+      if (timeoutId !== null) clearTimeout(timeoutId);
       this.activeInvocations.delete(request.requestId);
       throw this.normalizeInvocationError(error, definition, request.requestId);
     });
@@ -235,22 +266,28 @@ export class Glass3Client {
           acceptedResult.toolName === definition.toolName &&
           acceptedResult.toolAction === definition.toolAction
         );
-    const validResponse = response &&
+    const validChannel = !definition.responseChannel || (
+      response && response.channel === definition.responseChannel
+    );
+    const validEnvelope = response &&
+      validChannel &&
       response.version === RPC_VERSION &&
       response.kind === 'response' &&
-      response.requestId === requestId &&
-      response.ok === true &&
-      validAcceptedResult;
+      response.requestId === requestId;
+    const validResponse = validEnvelope &&
+      response.ok === true && validAcceptedResult;
 
     if (validResponse) return;
 
-    const nativeError = response && response.error;
+    const nativeError = validEnvelope && response.ok === false
+      ? response.error
+      : null;
     throw new Glass3Error(
       nativeError && nativeError.message
         ? nativeError.message
         : `Native request was not accepted: ${definition.publicModule}.${definition.publicMethod}`,
       {
-        code: nativeError && nativeError.code
+        code: nativeError && nativeError.code !== undefined
           ? nativeError.code
           : 'NATIVE_REQUEST_NOT_ACCEPTED',
         stage: 'response',

package/sdk/core/constants.js

@@ -1,6 +1,7 @@
 export const RPC_URL = 'https://ink-host-rpc.invalid/rpc';
 export const RPC_ORIGIN = 'rokid://host-rpc';
 export const RPC_VERSION = '2.0.0';
+export const RPC_CHANNEL = 'rokid.host.rpc';
 
 export const RPC_SUCCESS_STATUS_MIN = 200;
 export const RPC_SUCCESS_STATUS_MAX = 299;

package/sdk/core/transport.js

@@ -22,10 +22,20 @@ export class HostRpcTransport {
       JSON.stringify(redactSensitiveDataForLog(request))
     );
 
-    return requestFetch(this.url, {
+    return Promise.resolve().then(() => requestFetch(this.url, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: requestBody
+    })).catch(error => {
+      if (error instanceof Glass3Error) throw error;
+      throw new Glass3Error('Host RPC transport failed', {
+        code: 'TRANSPORT_ERROR',
+        stage: 'transport',
+        requestId: request.requestId,
+        namespace: request.namespace,
+        method: request.method,
+        cause: error
+      });
     }).then(response => {
       if (
         response.status < RPC_SUCCESS_STATUS_MIN ||
@@ -43,7 +53,16 @@ export class HostRpcTransport {
         );
       }
 
-      return response.json();
+      return Promise.resolve().then(() => response.json()).catch(error => {
+        throw new Glass3Error('Host RPC response is not valid JSON', {
+          code: 'TRANSPORT_INVALID_RESPONSE',
+          stage: 'transport',
+          requestId: request.requestId,
+          namespace: request.namespace,
+          method: request.method,
+          cause: error
+        });
+      });
     }).then(result => {
       console.log(
         '[glass3] Native fetch response:',

package/sdk/index.js

@@ -1,16 +1,20 @@
 import API_MAP from './api-map.js';
 import { Glass3Client } from './core/client.js';
+import openapi, { openApiClient } from './modules/openapi/index.js';
 import { createApiNamespaces } from './utils/api-builder.js';
 
 const client = new Glass3Client();
 const glass3 = createApiNamespaces(client, API_MAP);
 
+glass3.openapi = openapi;
+
 glass3.handleMessage = function handleMessage(messageEvent) {
   return client.handleMessage(messageEvent);
 };
 
 glass3.dispose = function dispose() {
   client.dispose();
+  openApiClient.dispose();
 };
 
 export { API_MAP } from './api-map.js';