rvis-aiui-kit 1.1.0 → 1.1.1

package/README.md

@@ -1,22 +1,719 @@
 # rvis-aiui-kit
 
-RVIS AIUI components and the Glass3 extension SDK.
+面向 Rokid AIUI / JSUI 应用的组件库与 Glass3 扩展 SDK。包内包含 7 个 Ink UI 组件、9 组 Host RPC 能力，以及一个 Rokid OpenAPI HTTPS/SSE 客户端。
 
-## SDK
+## 文档导航
 
-```js
-import glass3 from 'rvis-aiui-kit';
+- [安装与运行环境](#安装与运行环境)
+- [快速接入](#快速接入)
+- [Glass3 SDK API](#glass3-sdk-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)
+  - [OpenAPI](#openapi)
+- [错误处理](#错误处理)
+- [页面卸载与资源清理](#页面卸载与资源清理)
+- [组件 API](#组件-api)
+  - [Image](#image)
+  - [List](#list)
+  - [Markdown](#markdown)
+  - [Model List](#model-list)
+  - [Paragraph](#paragraph)
+  - [Status Bar](#status-bar)
+  - [Table](#table)
+
+## 安装与运行环境
+
+```sh
+npm install rvis-aiui-kit
 ```
 
-## Components
+`rvis-aiui-kit` 运行在 AIUI Ink 页面环境中，SDK 依赖宿主提供的 `wx`、Host RPC 和设备能力，不能直接在普通浏览器或 Node.js 中运行。
+
+包提供以下入口：
+
+| 入口 | 内容 |
+| --- | --- |
+| `rvis-aiui-kit` | 默认导出 `glass3`，并命名导出 `glass3`、`API_MAP`、`Glass3Error` |
+| `rvis-aiui-kit/sdk` | 与包根入口相同 |
+| `rvis-aiui-kit/api-map` | Host RPC API 映射 |
+| `rvis-aiui-kit/<component>` | Ink 组件注册路径 |
+
+## 快速接入
 
-```json
+### 1. 注册组件
+
+在 `.ink` 页面的 `<script def>` 中配置 `usingComponents`：
+
+```html
+<script def>
 {
+  "navigationBarTitleText": "巡检",
+  "description": "显示巡检结果并提供 Glass3 设备能力。",
+  "schema": {
+    "data": {
+      "type": "object",
+      "properties": {}
+    }
+  },
   "usingComponents": {
-    "rvis-markdown": "rvis-aiui-kit/markdown",
-    "rvis-list": "rvis-aiui-kit/list"
+    "rvis-status-bar": "rvis-aiui-kit/status-bar",
+    "rvis-paragraph": "rvis-aiui-kit/paragraph",
+    "rvis-table": "rvis-aiui-kit/table"
+  }
+}
+</script>
+```
+
+### 2. 引入 SDK 并转发 Host 消息
+
+```html
+<script setup>
+import glass3 from 'rvis-aiui-kit';
+
+export default {
+  data: {
+    resultText: '准备就绪'
+  },
+
+  onMessage(messageEvent) {
+    // Host RPC 的 Promise 和流式 onEvent 都依赖这一步。
+    glass3.handleMessage(messageEvent);
+  },
+
+  async takePhoto() {
+    try {
+      const photo = await glass3.camera.takePhoto();
+      this.setData({
+        resultText: `照片尺寸：${photo.width} × ${photo.height}`
+      });
+    } catch (error) {
+      this.setData({ resultText: `${error.code}: ${error.message}` });
+    }
+  },
+
+  onUnload() {
+    // 先停止页面启动的长任务，再释放 SDK 本地监听和等待中的请求。
+    glass3.dispose();
+  }
+};
+</script>
+
+<page>
+  <view class="page">
+    <rvis-status-bar title="巡检"></rvis-status-bar>
+    <view class="content">
+      <rvis-paragraph text="{{ resultText }}" width="424px"></rvis-paragraph>
+    </view>
+  </view>
+</page>
+
+<style>
+.page {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 480px;
+  height: 640px;
+  background-color: #000000;
+}
+
+.content {
+  position: absolute;
+  top: 40px;
+  left: 28px;
+  width: 424px;
+}
+</style>
+```
+
+> `glass3.openapi` 不依赖 Host RPC 消息转发，但页面卸载时仍应调用 `glass3.dispose()`，关闭未完成的 SSE 请求。
+
+## Glass3 SDK API
+
+### 导入
+
+```js
+import glass3, {
+  glass3 as namedGlass3,
+  API_MAP,
+  Glass3Error
+} from 'rvis-aiui-kit';
+```
+
+- `glass3`：默认客户端单例及全部公开模块；
+- `API_MAP`：公开 JavaScript API 到 Host RPC 的映射；
+- `Glass3Error`：统一 SDK 错误类型。
+
+### 通用调用约定
+
+- 每个业务方法都返回 Promise；Promise 完成的时点以各 API 说明为准。
+- 长任务通过第二个参数 `{ onEvent(result) {} }` 持续返回事件。
+- Native response 不进入 `onEvent`，`onEvent` 只接收匹配的 event result。
+- `start*`、`observe`、`register` 等返回的 `requestId` 是对应 stop/unregister 调用的目标 ID，必须保存。
+- stop/unregister 自己会生成新的 `requestId`，其返回值中的 ID 不是原任务 ID。
+- 除明确记录的字段外，大多数参数按闭合对象校验，不要传未记录字段或 `snake_case` 字段。
+- Native 下划线字段通常会递归转换为驼峰字段，具体以对应 API 为准。
+
+### API 总览
+
+| 模块 | 方法 | 用途 |
+| --- | --- | --- |
+| `deviceContext` | `get(options?)` | 获取设备上下文原子快照 |
+| `deviceContext` | `observe(options?, callOptions?)` | 订阅设备上下文快照和变化 |
+| `deviceContext` | `stopObserve({ requestId })` | 停止设备上下文订阅 |
+| `screen` | `turnOff()` / `turnOn()` | 息屏 / 亮屏 |
+| `notification` | `show(options)` / `hide({ requestId })` | 显示 / 隐藏原生通知 |
+| `tts` | `speak(options, callOptions?)` / `stop({ requestId })` | TTS 播报 / 停止 |
+| `offlineCommand` | `register(options, callOptions?)` / `unregister({ requestId })` | 注册 / 注销离线指令 |
+| `audio` | `startRecord(options?, callOptions?)` / `stopRecord({ requestId })` | 录音、转写、保存或上传 |
+| `camera` | `startPreview(options?)` / `stopPreview({ requestId })` | 相机预览 |
+| `camera` | `takePhoto(options?)` | 拍照 |
+| `camera` | `startTakeVideo(options?, callOptions?)` / `stopTakeVideo({ requestId })` | 分段录像 |
+| `face` | `startRecognize({}, callOptions?)` / `stopRecognize({ requestId })` | 持续人脸识别 |
+| `motion` | `startDetect({}, callOptions?)` / `stopDetect({ requestId })` | 持续运动状态检测 |
+| `openapi` | `setConfig(options)` / `visionExtract(params, callOptions?)` | 配置并调用 Rokid OpenAPI 图片识别 |
+
+客户端级方法：
+
+| 方法 | 返回值 | 说明 |
+| --- | --- | --- |
+| `glass3.handleMessage(messageEvent)` | 匹配结果或 `null` | 将 Page 收到的 Host 消息交给 SDK |
+| `glass3.dispose()` | `undefined` | 释放监听，以 `CALL_DISPOSED` 结束等待中的 RPC，并关闭未完成的 OpenAPI 请求 |
+
+### Device Context
+
+```js
+const context = await glass3.deviceContext.get({
+  domains: ['environment', 'power', 'network', 'interaction']
+});
+
+const observer = await glass3.deviceContext.observe(
+  { domains: ['power', 'network'] },
+  {
+    onEvent(result) {
+      if (result.eventType === 'snapshot') {
+        // result.snapshot
+      } else if (result.eventType === 'changed') {
+        // 按 epoch、baseRevision 合并 patch
+      } else if (result.eventType === 'invalidated') {
+        // 清除旧账号/环境上下文并重新加载
+      }
+    }
+  }
+);
+
+await glass3.deviceContext.stopObserve({ requestId: observer.requestId });
+```
+
+`domains` 可选值：`identity`、`software`、`account`、`environment`、`power`、`network`、`interaction`。省略参数或传 `{}` 表示全部；显式传入时必须是非空数组。
+
+`get()` 等待 `snapshot` 事件后完成，返回 `{ requestId, ok, eventType: 'snapshot', snapshot }`。`observe()` 在订阅启动后返回 `{ requestId, ok, state: 'started' }`；首个业务事件为 `snapshot`，后续为 `changed` 或 `invalidated`。SDK 不自动合并 patch。
+
+### Screen
+
+```js
+const offResult = await glass3.screen.turnOff();
+const onResult = await glass3.screen.turnOn();
+```
+
+返回 `{ requestId, ok, changed, screen: 'off' | 'on' }`。`changed: false` 表示调用前已经处于目标状态，仍属于成功。
+
+普通电源键行为由 Host 管理时，不要在按键回调中调用这两个方法。系统亮屏/息屏通过 Page 收到的原始 `rokid.device / screenStateChanged` 消息通知；先转发给 `glass3.handleMessage()`，再读取 `messageEvent.data.data.state`。
+
+### Notification
+
+```js
+const notice = await glass3.notification.show({
+  text: '思考中',
+  level: 'active',
+  position: 'topCenter',
+  durationMs: 8000,
+  animation: 'thinking',
+  resident: true
+});
+
+await glass3.notification.hide({ requestId: notice.requestId });
+```
+
+| 字段 | 类型 | 必填/默认值 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 与 `text` 至少一个 | 标题，可显式传空字符串 |
+| `text` | `string` | 与 `title` 至少一个 | 正文，可显式传空字符串 |
+| `level` | `string` | `'active'` | `active` 或 `critical`；非法值警告后回退到 `active` |
+| `position` | `string` | Native 默认值 | `topLeft`、`topCenter`、`topRight`、`bottomLeft`、`bottomCenter`、`bottomRight` |
+| `durationMs` | `number` | Native 默认值 | 大于 0 的整数，单位毫秒 |
+| `animation` | `string` | `'idle'` | 通知动效 |
+| `resident` | `boolean` | Native 默认值 | 是否常驻 |
+
+`animation` 可选值：`idle`、`blink`、`thinking`、`calm`、`nod`、`bow`、`salute`、`photo`、`face`、`scan`、`success`、`listening`、`speaking`、`enter`、`exit`。
+
+`show()` 和 `hide()` 都返回 `{ requestId, ok: true }`。Native 通知优先级高于息屏状态；若息屏后不应保留通知，应先调用 `hide()`。
+
+### TTS
+
+```js
+const playback = await glass3.tts.speak(
+  { text: '你好，这是一段播报。', queueMode: 'flush' },
+  {
+    onEvent(result) {
+      // state: started | finished | canceled
+    }
   }
+);
+
+await glass3.tts.stop({ requestId: playback.requestId });
+```
+
+`speak()` 在请求被 Native 接受后返回 `{ requestId, ok: true }`，不等待播放结束。`stop()` 返回 `{ requestId, ok: true, state: 'stopped' }`。
+
+### Offline Command
+
+```js
+const registration = await glass3.offlineCommand.register(
+  {
+    language: 'ZH_CN',
+    commands: [
+      {
+        id: 'next_step',
+        phrases: [
+          { text: '下一步', pinyin: 'xia yi bu' },
+          { text: '继续', pinyin: 'ji xu' }
+        ]
+      }
+    ]
+  },
+  {
+    onEvent(result) {
+      if (result.commandId === 'next_step') {
+        // 处理命中
+      }
+    }
+  }
+);
+
+await glass3.offlineCommand.unregister({
+  requestId: registration.requestId
+});
+```
+
+`commands` 必须是非空数组；每项包含非空 `id` 和非空 `phrases`。每个 phrase 必须提供非空 `text`，应用开发时同时提供非空 `pinyin`。命中事件通过注册调用的 `onEvent` 返回 `{ ok, commandId, phrase, timestamp }`，不要用 `onVoiceWakeup` 接收 SDK 离线指令。
+
+### Audio
+
+```js
+const recording = await glass3.audio.startRecord(
+  {
+    maxMinutes: 10,
+    needText: true,
+    needMp3: false,
+    showCard: true,
+    upload: false
+  },
+  {
+    onEvent(result) {
+      // finished、canceled 或异步错误
+    }
+  }
+);
+
+const audioResult = await glass3.audio.stopRecord({
+  requestId: recording.requestId
+});
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `maxMinutes` | `number` | `10` | 1～120 的整数 |
+| `needText` | `boolean` | `true` | 返回整段 ASR 文本 |
+| `needMp3` | `boolean` | `false` | 保留并返回音频文件 |
+| `showCard` | `boolean` | `true` | 显示 Native 录音卡片 |
+| `upload` | `boolean` | `false` | 上传结果；成功时返回 `fileUrl` |
+
+`startRecord()` 返回 `{ requestId, ok, state: 'started' }`。结束结果包含 `state`、`reason`、`durationMs`，并按选项提供 `text`、`filePath`、`fileUrl`、`sizeBytes`、`sampleRate`。`stopRecord()` 直接返回停止状态和录音成果。
+
+### Camera
+
+#### 预览
+
+```js
+const preview = await glass3.camera.startPreview();
+await glass3.camera.stopPreview({ requestId: preview.requestId });
+```
+
+默认预览参数：
+
+```js
+{
+  left: 0,
+  top: 40,
+  width: 168,
+  height: 104,
+  cornerRadius: 2,
+  outline: true
 }
 ```
 
-Available component exports: `rvis-aiui-kit/image`, `rvis-aiui-kit/list`, `rvis-aiui-kit/markdown`, `rvis-aiui-kit/model-list`, `rvis-aiui-kit/paragraph`, `rvis-aiui-kit/status-bar`, `rvis-aiui-kit/table`.
+自定义区域时，`left`、`top`、`width`、`height`、`cornerRadius` 必须一起提供；`outline` 可以单独设置。启动返回 `{ requestId, ok, state: 'started' }`，停止返回 `{ requestId, ok, state: 'cancel' }`。
+
+#### 拍照
+
+```js
+const photo = await glass3.camera.takePhoto({
+  returnBase64: true,
+  upload: false,
+  timeout: 5000
+});
+```
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `returnBase64` | `boolean` | `true` | 返回 `photoMime` 和 `photoBase64` |
+| `upload` | `boolean` | `false` | 上传照片 |
+| `timeout` | `number` | `5000` | JS 等待超时，正整数毫秒，不发送给 Native |
+
+结果包含 `{ requestId, ok, photoSize, filePath, width, height }`，并按选项提供 `photoMime`、`photoBase64`、`fileUrl`、`inspectionResultId` 或 `uploadError`。超时抛出 `CALL_TIMEOUT`；这只会停止 JS 等待，不保证 Native 操作已取消。
+
+#### 录像
+
+```js
+const video = await glass3.camera.startTakeVideo(
+  { enableAudio: true, segmentMinutes: 20 },
+  {
+    onEvent(result) {
+      // started、分段文件、canceled 或失败事件
+    }
+  }
+);
+
+await glass3.camera.stopTakeVideo({ requestId: video.requestId });
+```
+
+`enableAudio` 默认 `true`；`segmentMinutes` 默认 `20`，必须是正整数。分段事件包含 `filePath`、`startTime`、`endTime`、`hasMore`。`hasMore: false` 是最后一段。
+
+### Face
+
+```js
+const recognition = await glass3.face.startRecognize({}, {
+  onEvent(result) {
+    // personId、personName、similarity、faceModel 等
+  }
+});
+
+await glass3.face.stopRecognize({ requestId: recognition.requestId });
+```
+
+`startRecognize()` 不接收业务参数；需要传 `onEvent` 时，第一个参数必须是空对象。启动返回 `{ requestId, ok: true }`，停止返回 `{ requestId, ok: true, state: 'stopped' }`。
+
+### Motion
+
+```js
+const detection = await glass3.motion.startDetect({}, {
+  onEvent(result) {
+    // { ok, motionState, previous, moving, timestamp }
+  }
+});
+
+await glass3.motion.stopDetect({ requestId: detection.requestId });
+```
+
+`motionState` 可选值：`still`、`walk`、`run`、`headTurnLeft`、`headTurnRight`。Native 仅在状态变化时上报；首个事件的 `previous` 为 `unknown`。
+
+### 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' },
+      { name: 'suggestion', title: '修改建议', type: 'string' }
+    ]
+  },
+  {
+    onEvent(event) {
+      // type: start | snapshot | discard | result | error
+    }
+  }
+);
+```
+
+配置：
+
+| 字段 | 类型 | 必填/默认值 | 说明 |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | 必填 | Rokid OpenAPI AK |
+| `baseUrl` | `string` | `https://api.rokid.com` | 测试环境使用 `https://api-test.rokid.com` |
+
+`visionExtract()` 参数：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `image` | `string` | 必填；纯 Base64 或 Data URL，原图最大 10MB |
+| `prompt` | `string` | 必填；最长 8192 字符 |
+| `uiType` | `string` | 必填；`text` 或 `table` |
+| `fields` | `array` | `table` 必填 1～8 项；`text` 时省略或传空数组 |
+
+`fields[]` 包含稳定的英文 `name`、展示名 `title`，以及 `string`、`number` 或 `boolean` 类型。Promise 在收到 `[DONE]` 后返回最终 `result`；`result.success === false` 属于已完成的业务失败，仍然 resolve。HTTP、网络、SSE、协议、超时及 `event:error` 会 reject。
+
+不要把 API Key 放入页面渲染数据或日志。SDK 日志会脱敏 `apiKey`、`Authorization` 和图片 Base64。
+
+## 错误处理
+
+```js
+import glass3, { Glass3Error } from 'rvis-aiui-kit';
+
+try {
+  await glass3.camera.takePhoto({ timeout: 5000 });
+} catch (error) {
+  if (error instanceof Glass3Error) {
+    console.error(error.code, error.stage, error.requestId);
+  }
+}
+```
+
+`Glass3Error` 提供 `name`、`message`、`code`、`stage`、`requestId`、`namespace`、`method`、`details` 和 `cause`。
+
+常见错误码：
+
+| 错误码 | 说明 |
+| --- | --- |
+| `INVALID_PARAMS` | 参数缺失、类型或枚举错误、存在未支持字段 |
+| `TRANSPORT_REJECTED` | Host RPC 传输层返回非成功状态 |
+| `NATIVE_REQUEST_ERROR` | 请求发送或响应阶段异常 |
+| `NATIVE_REQUEST_NOT_ACCEPTED` | Native 响应未通过协议校验或未受理 |
+| `NATIVE_EVENT_ERROR` | 匹配的 Native event 返回失败 |
+| `CALL_TIMEOUT` | JS 等待超时 |
+| `CALL_DISPOSED` | 请求等待期间调用了 `glass3.dispose()` |
+| `OPENAPI_NOT_CONFIGURED` | OpenAPI 尚未配置 |
+| `OPENAPI_HTTP_ERROR` | OpenAPI 返回非成功 HTTP 状态 |
+| `OPENAPI_STREAM_ERROR` | SSE 连接或传输失败 |
+| `OPENAPI_PROTOCOL_ERROR` | SSE 结果或结束帧不符合协议 |
+| `OPENAPI_SERVICE_ERROR` | OpenAPI 返回 `event:error` |
+
+Native 也可能返回自己的错误码。恢复逻辑应判断 `error.code`，不要匹配 `message` 文本。
+
+## 页面卸载与资源清理
+
+以下长任务应保存启动 `requestId`，并在页面卸载前调用对应 stop/unregister：
+
+- `deviceContext.observe()`；
+- `tts.speak()`；
+- `offlineCommand.register()`；
+- `audio.startRecord()`；
+- `camera.startPreview()`；
+- `camera.startTakeVideo()`；
+- `face.startRecognize()`；
+- `motion.startDetect()`。
+
+最后调用 `glass3.dispose()`。`dispose()` 只清理 SDK 本地监听、等待中的 Promise 和 OpenAPI SSE，不等价于所有 Native 长任务的业务 stop 操作。
+
+## 组件 API
+
+所有组件都通过 `rvis-aiui-kit/<组件名>` 注册。数组或对象类属性使用 JSON 字符串传递，调用方需要先执行 `JSON.stringify()`。
+
+### Image
+
+注册路径：`rvis-aiui-kit/image`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `src` | `String` | `''` | 网络地址、本地路径或 Base64 Data URL |
+| `width` | `String` | `'168px'` | 图片宽度 |
+| `height` | `String` | `'104px'` | 图片高度 |
+| `objectFit` | `String` | `'fill'` | `contain`、`cover` 或 `fill` |
+
+组件固定使用 `2px` 圆角。默认尺寸与 `glass3.camera.startPreview()` 的默认预览区域一致。
+
+```html
+<rvis-image src="{{ imageSrc }}" objectFit="cover"></rvis-image>
+```
+
+Base64 拍照结果可转换为 Data URL：
+
+```js
+const imageSrc = `data:${photo.photoMime || 'image/jpeg'};base64,${photo.photoBase64}`;
+```
+
+### List
+
+注册路径：`rvis-aiui-kit/list`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `String` | `''` | 列表标题 |
+| `description` | `String` | `''` | 标题后的补充说明 |
+| `items` | `String` | `'[]'` | Item 数组序列化后的 JSON 字符串 |
+
+Item 结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `String` | 是 | 稳定且唯一的列表项 ID |
+| `text` | `String` | 是 | 列表项文案 |
+| `completed` | `Boolean` | 是 | 是否显示完成标记 |
+
+```js
+data: {
+  items: JSON.stringify([
+    { id: 'camera', text: '检查相机', completed: true },
+    { id: 'network', text: '检查网络', completed: false }
+  ])
+}
+```
+
+```html
+<rvis-list title="检查清单" items="{{ items }}"></rvis-list>
+```
+
+组件不提供事件或插槽。动态隐藏时保持组件挂载，并使用定位将其移出屏幕；不要用 `ink:if` 反复卸载，也不要用 `display` 隐藏。
+
+### Markdown
+
+注册路径：`rvis-aiui-kit/markdown`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `content` | `String` | `''` | 原始 Markdown 字符串 |
+
+```html
+<rvis-markdown content="{{ markdownContent }}"></rvis-markdown>
+```
+
+支持范围：
+
+- 独占一行的 Markdown 图片；
+- 普通段落与段内 `**粗体**`；
+- 管道表格；
+- `1. 内容` 形式的编号列表。
+
+不支持标题、嵌套列表、斜体、代码、公式、HTML 和可点击链接。组件宽度为 `424px`，不内置滚动容器；长内容应由页面放入 `scroll-view`。当前版本针对完整文档展示，不保证逐 token 流式更新时布局稳定。
+
+### Model List
+
+注册路径：`rvis-aiui-kit/model-list`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `items` | `String` | `'[]'` | Item 数组序列化后的 JSON 字符串 |
+| `selectedId` | `String` | `''` | 当前选中项 ID |
+| `showIndex` | `Boolean` | `true` | 是否显示序号 |
+| `visible` | `Boolean` | `true` | 是否显示在屏幕内 |
+
+Item 结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `String` | 是 | 唯一 ID |
+| `title` | `String` | 是 | 标题 |
+| `description` | `String` | 否 | 右侧说明 |
+| `indexText` | `String` | 否 | 自定义序号 |
+
+```html
+<rvis-model-list
+  items="{{ modelItems }}"
+  selectedId="{{ selectedModelId }}"
+  visible="{{ showModelList }}"
+  style="position: fixed; top: 0; left: 0; right: 0; bottom: 0; z-index: 1000;"
+></rvis-model-list>
+```
+
+组件不提供选择事件，页面通过设备按键或业务逻辑更新 `selectedId`。调用方必须按示例为组件宿主设置全屏固定定位，否则自定义组件宿主可能裁剪遮罩。
+
+### Paragraph
+
+注册路径：`rvis-aiui-kit/paragraph`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `text` | `String` | `''` | 普通段落文本 |
+| `width` | `String` | `'380px'` | 段落宽度 |
+| `segments` | `String` | `'[]'` | `{ text, bold }` 数组序列化后的 JSON 字符串；非空时优先于 `text` |
+
+```js
+data: {
+  segments: JSON.stringify([
+    { text: '状态：' },
+    { text: '正常', bold: true }
+  ])
+}
+```
+
+```html
+<rvis-paragraph text="{{ text }}" width="424px" segments="{{ segments }}"></rvis-paragraph>
+```
+
+### Status Bar
+
+注册路径：`rvis-aiui-kit/status-bar`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `String` | `''` | 左侧应用标题 |
+
+```html
+<rvis-status-bar title="应用名称"></rvis-status-bar>
+```
+
+组件尺寸固定为 `480px × 20px`，显示应用标题、本地日期时间和实时电量。页面应将其放在全屏绘制区域的 `(0, 0)`。组件自动管理时钟和 `power` 订阅，但 Page 必须把 `onMessage` 转发给共享的 `glass3` 实例。
+
+### Table
+
+注册路径：`rvis-aiui-kit/table`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `header` | `String` | `''` | 表格标题；空白时不渲染标题区 |
+| `column` | `String` | `'[]'` | Column 数组序列化后的 JSON 字符串 |
+| `data` | `String` | `'[]'` | 数据数组序列化后的 JSON 字符串 |
+| `direction` | `String` | `'horizontal'` | `horizontal` 或 `vertical` |
+| `compact` | `Boolean` | `false` | 横向表格是否使用紧凑内边距 |
+| `columnWidths` | `String` | `''` | 横向列宽，例如 `'120px 156px 144px'`；空值表示等分 |
+
+Column 结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `String` | 是 | 字段标题 |
+| `dataIndex` | `String` | 是 | 数据字段名 |
+| `align` | `String` | 否 | `left`、`center` 或 `right` |
+
+每条数据应提供稳定且唯一的 `key`。
+
+```js
+data: {
+  columns: JSON.stringify([
+    { title: '名称', dataIndex: 'name' },
+    { title: '状态', dataIndex: 'status', align: 'right' }
+  ]),
+  rows: JSON.stringify([
+    { key: 'camera', name: '相机', status: '正常' }
+  ])
+}
+```
+
+```html
+<rvis-table
+  header="设备状态"
+  column="{{ columns }}"
+  data="{{ rows }}"
+  direction="horizontal"
+></rvis-table>
+```
+
+表格宽度为 `424px`。放在纵向 Flex 容器中时，父容器应设置 `align-items: flex-start`。