@vivix-ai/ivi-frontend-sdk 0.2.2

package/README.md

@@ -0,0 +1,561 @@
+# IVI Frontend SDK
+
+用于前端应用集成 IVI 实时能力的 TypeScript SDK，包含：
+
+- 基于 `@vivix/ivi-sdk-ts` 的 runtime 协调层
+- 面向舞台渲染的 React 组件与 hooks
+
+## 安装依赖
+
+当前包尚未发布到 npm，通过 **GitLab 仓库地址**直接安装：
+
+```bash
+# npm
+npm install git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+
+# pnpm
+pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+
+# yarn
+yarn add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+```
+
+> **推荐使用 `#main` 分支。** `dev` 分支可能引入尚未稳定的新特性，不保证向后兼容；`main` 分支仅包含经过验证的变更。如需锁定到更精确的版本，可替换为具体 tag 或 commit hash。
+
+安装后 `package.json` 中会出现类似条目：
+
+```json
+{
+  "dependencies": {
+    "@vivix/ivi-frontend-sdk": "git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main"
+  }
+}
+```
+
+**更新到最新版本**：
+
+```bash
+# npm（Git 依赖建议显式指定分支、tag 或 commit）
+npm install git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+
+# pnpm
+pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+
+# 若 lockfile 固定了旧 commit，可重新安装或删除 lock 中该依赖条目后 install
+npm install
+```
+
+### `dist` 与 Git 直装
+
+`package.json` 的 `main` / `module` / `types` / `exports` 均指向 `dist/`，且 npm 包通过 `"files": ["dist"]` 发布。从 **Git 引用安装**（如 `git+https://…#dev`）时，npm 只会打包 `files` 所列内容；因此 **`dist/` 已纳入版本库**，克隆默认分支即可得到可运行、可解析类型的产物。
+
+**协作约定**：修改 `src/` 后必须在本地执行 `npm run build`（或 `pnpm run build`），并将**与本次源码变更对应的一次完整 `dist/` 输出**一并提交：可与功能改动放在**同一提交**，或在必要时单独提交，提交信息示例：`chore: 重新构建 dist`。禁止只改源码而不更新 `dist/`，避免仓库内源码与产物不一致。
+
+### Peer Dependencies
+
+React 为可选 peer dependency，仅使用 React 组件时需要：
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0"
+}
+```
+
+如果只使用 runtime 能力、不接入 React 组件与 hooks，可忽略本文中的 React 用法部分。
+
+## 包导出与导入方式
+
+当前仅支持单一主入口：
+
+| 入口 | 路径 | 说明 |
+|------|------|------|
+| 主入口 | `@vivix/ivi-frontend-sdk` | 导出 runtime 能力、`IviFrontendSdk`、以及当前公开的 React API：`IVIStageView`、`IVITrackSlot`、`useManagedIviRuntime`、`useIviStageView` |
+
+**导入示例**：
+
+```ts
+// 底层 client 由 @vivix/ivi-sdk-ts 提供
+import { IviClient } from "@vivix/ivi-sdk-ts";
+
+// 本包主入口
+import {
+  IviRuntimeCoordinator,
+  IviRuntimeDispatcher,
+  IviFrontendSdk,
+  IVIStageView,
+  IVITrackSlot,
+  useManagedIviRuntime,
+  useIviStageView
+} from "@vivix/ivi-frontend-sdk";
+```
+
+> 当前包没有 `@vivix/ivi-frontend-sdk/core` / `@vivix/ivi-frontend-sdk/react` 子入口；底层 WebSocket client、事件解析与协议类型请直接从 `@vivix/ivi-sdk-ts` 导入。
+
+---
+
+## 快速开始
+
+### 1）创建 client + runtime
+
+```ts
+import { IviClient } from "@vivix/ivi-sdk-ts";
+import { IviRuntimeCoordinator } from "@vivix/ivi-frontend-sdk";
+
+const client = new IviClient({
+  url: "wss://your-domain/v1/realtime",
+  sessionId: "sess_xxx",
+  onParseError: (error, raw) => {
+    console.error("parse error", error, raw);
+  }
+});
+
+const runtime = new IviRuntimeCoordinator(client, {
+  syncStageOnSessionCreated: true,    // 默认 true，session 建立后自动同步 stage
+  onSessionEnded: (event) => {
+    console.log("session ended", event);
+  }
+});
+
+await runtime.start();
+```
+
+**使用自定义 WebSocket 运行时**（Node.js / 自定义环境）：
+
+```ts
+import WebSocket from "ws"; // Node.js 环境
+import { IviClient } from "@vivix/ivi-sdk-ts";
+import { IviRuntimeCoordinator } from "@vivix/ivi-frontend-sdk";
+
+const client = new IviClient({
+  url: "wss://your-domain/v1/realtime",
+  sessionId: "sess_xxx",
+  socketFactory: (url, protocols) => new WebSocket(url, protocols),
+  onParseError: (error, raw) => {
+    console.error("parse error", error, raw);
+  }
+});
+
+const runtime = new IviRuntimeCoordinator(client);
+await runtime.start();
+```
+
+`IviClientConfig` 关键配置：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `protocols` | `string \| string[]` | WebSocket 子协议 |
+| `sessionId` | `string` | 会话 ID，连接时自动追加到 URL query `session_id=<id>` |
+| `socketFactory` | `(url, protocols?) => WebSocket` | 自定义 Socket 工厂，用于替换默认 WebSocket 构造 |
+| `onParseError` | `(error, rawMessage) => void` | 事件解析失败回调 |
+| `onLog` | `(entry) => void` | `IviClient` 链路日志回调，包含发送、WebSocket 状态和重连链路 |
+| `reconnect` | `IviClientReconnectOptions` | 自动重连配置；默认启用，指数退避 |
+| `sendWaitTimeoutMs` | `number` | 发送时等待连接恢复的超时，默认 `30000` ms，`<=0` 表示无限等待 |
+
+### 2）订阅状态与事件
+
+```ts
+const unlistenState = runtime.onStateChange((state) => {
+  console.log(state.status, state.stage, state.tracks.size, state.sources.size);
+});
+
+const unlistenEvent = runtime.onEvent((event, state) => {
+  console.log("event:", event.type, "runtime:", state.status);
+});
+
+// 业务结束时
+unlistenState();
+unlistenEvent();
+runtime.stop();
+```
+
+### 3）发送用户文本并触发模型回复
+
+```ts
+const result = await runtime.sendUserTextAndTriggerStreamResponse({
+  streamId: "stream_001",
+  text: "你好",
+  callbacks: {
+    onConversationItemAdded: (event) => console.log("item added"),
+    onConversationItemDone: (event) => console.log("item done"),
+    onConversationItemReady: ({ itemId }) => console.log("item ready:", itemId),
+    onStreamResponseCreated: (event) => console.log("response created")
+  }
+});
+console.log("完成:", result.itemId, result.streamId);
+```
+
+### 4）上报 source 播放完成
+
+```ts
+runtime.sendSessionSourcePlaybackCompleted("source_001", "track_001");
+```
+
+### 5）runtime 状态字段
+
+`IviRuntimeState` 包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | `"idle" \| "connecting" \| "syncing" \| "running" \| "stopped"` | 生命周期状态 |
+| `session` | `IviRealtimeSession \| null` | 当前会话 |
+| `stage` | `IviStage \| null` | 当前 stage（slot → track 映射） |
+| `tracks` | `Map<string, IviTrack>` | 所有 track |
+| `sources` | `Map<string, IviRuntimeSource>` | 所有 source（含 `status: created \| ready \| failed`） |
+| `conversationItems` | `Map<string, IviRuntimeConversationItem>` | 对话条目映射 |
+| `conversations` | `IviRuntimeConversationItem[]` | 对话有序列表 |
+
+---
+
+## React 接入
+
+### 方式 A：传入外部 runtime
+
+```tsx
+import { IviClient } from "@vivix/ivi-sdk-ts";
+import { IviRuntimeCoordinator, IVIStageView, IVITrackSlot, useIviStageView } from "@vivix/ivi-frontend-sdk";
+
+// 初始化 runtime（参考上方 Core 用法）
+const client = new IviClient({ url: "wss://your-domain/v1/realtime", sessionId: "sess_xxx" });
+const runtime = new IviRuntimeCoordinator(client);
+await runtime.start();
+
+function StageDebug() {
+  const { slotBindings } = useIviStageView();
+  return <pre>{slotBindings.map((x) => `${x.slot} → ${x.trackId} → ${x.sourceId ?? "null"}`).join("\n")}</pre>;
+}
+
+export function StagePage() {
+  return (
+    <IVIStageView runtime={runtime}>
+      {({ slotBindings }) => (
+        <div>
+          {slotBindings.map((binding) => (
+            <IVITrackSlot key={binding.slot} slot={binding.slot} />
+          ))}
+          <StageDebug />
+        </div>
+      )}
+    </IVIStageView>
+  );
+}
+```
+
+### 方式 B：使用 `useManagedIviRuntime` 管理 runtime
+
+```tsx
+import { IVIStageView, IVITrackSlot, useManagedIviRuntime } from "@vivix/ivi-frontend-sdk";
+
+export function AutoStagePage({ sessionId }: { sessionId: string }) {
+  const runtime = useManagedIviRuntime({
+    clientConfig: {
+      url: "https://your-domain.com/v1/realtime",
+      sessionId
+    },
+    onLog: (entry) => {
+      // 统一收集 client / runtime / TRTC 的 IVI 链路日志
+      console.log(entry.tag, entry.message, entry.data);
+    },
+    onRuntimeInitError: (err) => console.error("runtime init failed", err)
+  });
+
+  return (
+    <IVIStageView runtime={runtime} onRuntimeEvent={(event) => console.log("event:", event.type)}>
+      <IVITrackSlot slot="main" showVolumeControl showSubtitle />
+    </IVIStageView>
+  );
+}
+```
+
+`useManagedIviRuntime` 的地址规则：
+
+1. 使用 `clientConfig.url`
+2. 若 `clientConfig.url` 为 `https://` / `http://`，内部会自动确保为 `wss://` / `ws://`
+3. 若 `clientConfig.sessionId` 为空，则不创建 runtime
+4. 若 `clientConfig.url` 为空，会通过 `onRuntimeInitError` 抛出初始化错误；若未提供回调，则直接抛错
+
+连接时自动追加 query：`?session_id=<sessionId>`。
+
+---
+
+## React Hooks
+
+### `useManagedIviRuntime`
+
+```ts
+function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordinator | null;
+```
+
+负责根据 `clientConfig` 创建并管理一个 `IviRuntimeCoordinator`。该 hook 会处理：
+
+- `IviClient` / `IviRuntimeCoordinator` 的创建
+- `autoStart` 为 `true` 时自动调用 `runtime.start()`
+- 卸载时自动 `runtime.stop()`
+- 初始化错误通过 `onRuntimeInitError` 上抛
+- 通过 `onLog` 统一收集 `IviClient`、runtime 状态变更、TRTC 管理器等 IVI 链路日志
+
+`IviManagedRuntimeConfig` 关键字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `clientConfig` | `IviClientConfig` | — | `IviClient` 配置；其中 `url` 用于建立连接，`sessionId` 用于决定是否创建 runtime |
+| `autoStart` | `boolean` | `true` | 是否自动启动 runtime |
+| `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 `IviRuntimeCoordinator` |
+| `onRuntimeInitError` | `(error) => void` | — | 初始化或启动失败回调 |
+| `onLog` | `(entry) => void` | — | 统一日志回调，覆盖 `[IVI-SEND]`、`[IVI-WS]`、`[IVI-RECONNECT]`、`[IVI-EVT]`、`[IVI-STATE]`、`[IVI-TRTC]` |
+
+`onLog` 的统一入参格式：
+
+```ts
+interface IviManagedRuntimeLogEntry {
+  level: "info" | "warn" | "error";
+  source: "client" | "runtime";
+  tag: string;          // 例如 "[IVI-WS]"、"[IVI-STATE]"
+  message: string;      // 带 tag 的可读日志
+  args: unknown[];      // 接近原 console 调用的参数
+  data?: unknown;       // 结构化数据
+}
+```
+
+### `useIviStageView`
+
+```ts
+function useIviStageView(): IviStageViewContextValue;
+```
+
+读取最近 `IVIStageView` 提供的 Context，必须在 `IVIStageView` 子树内使用。
+
+返回值 `IviStageViewContextValue`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `runtime` | `IviRuntimeCoordinator \| null` | 当前 runtime 实例 |
+| `state` | `IviRuntimeState` | 实时状态快照 |
+| `slotTrackMap` | `Map<string, string>` | slot → trackId 映射 |
+| `slotBindings` | `IviStageSlotBinding[]` | 完整绑定信息数组 |
+
+```tsx
+function MyOverlay() {
+  const { state, slotBindings } = useIviStageView();
+  return <div>{state.conversations.length} 条对话 | {slotBindings.length} 个绑定</div>;
+}
+```
+
+以下 hooks 为 `IVITrackSlot` 内部实现，当前不属于公开导出 API。
+
+### `useVolumeMemory`
+
+```ts
+function useVolumeMemory(mediaType: IviMediaVolumeType | null): [number, (v: number) => void];
+```
+
+按媒体类型（`"trtc" | "video" | "hls"`）在 `localStorage` 中持久化音量（0–100）。`mediaType` 为 `null` 时不持久化。
+
+### `useApplyVolumeToSlot`
+
+```ts
+function useApplyVolumeToSlot(
+  containerRef: RefObject<HTMLElement | null>,
+  volume: number,
+  enabled: boolean,
+  activeSourceId?: string | null
+): void;
+```
+
+将音量同步应用到容器内带 `data-ivi-slot-role="active"` 属性的 `<video>` / `<audio>` 元素，通过 `MutationObserver` 监听异步插入的媒体（如 TRTC 远端流）。
+
+---
+
+## React 组件
+
+当前公开导出的 React 组件只有 `IVIStageView` 与 `IVITrackSlot`；当前公开导出的 React hooks 只有 `useManagedIviRuntime` 与 `useIviStageView`。
+
+### `IVIStageView`
+
+顶层舞台容器，负责消费 `runtime` 并通过 Context 注入状态。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `children` | `ReactNode \| (ctx) => ReactNode` | — | 子节点或 render-prop |
+| `runtime` | `IviRuntimeCoordinator \| null` | — | 要消费的 runtime，由业务方或 `useManagedIviRuntime` 提供 |
+| `onBindingsChange` | `(bindings) => void` | — | slot 绑定变化回调 |
+| `onRuntimeEvent` | `(event) => void` | — | runtime 事件回调 |
+| `className` / `style` | — | — | 容器样式 |
+
+### `IVITrackSlot`
+
+按 slot 或 trackId 绑定，自动根据 source 类型渲染对应媒体播放器。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `slot` | `string` | — | 通过 slot 名称绑定（与 stage composition 对应） |
+| `trackId` | `string` | — | 直接绑定 trackId |
+| `emptyFallback` | `ReactNode` | — | 无 source 时的兜底内容 |
+| `renderTrtc` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义 TRTC 渲染 |
+| `renderMedia` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义非 TRTC 媒体渲染 |
+| `fitStrategy` | `"contain" \| "cover" \| "auto"` | — | 媒体适配策略 |
+| `adaptToSourceSize` | `boolean` | — | 是否根据 source 尺寸自适应 |
+| `background` | `IviTrackSlotBackground` | `"black"` | 媒体空白区域（letterbox/pillarbox）背景模式 |
+| `showVolumeControl` | `boolean` | — | 是否显示音量控制浮层 |
+| `volumeControlProps` | — | — | 音量控制自定义配置 |
+| `showSubtitle` | `boolean` | — | 是否显示字幕浮层 |
+| `subtitleProps` | — | — | 字幕自定义配置 |
+| `trtcPlayerProps` | — | — | TRTC 播放器自定义配置 |
+| `videoProps` / `imageProps` | — | — | 透传给原生 `<video>` / `<img>` |
+| `className` / `style` | — | — | 容器样式 |
+
+`IviTrackSlotBackground` 支持的值：`"black"` | `"white"` | `"transparent"` | `{ color: string }` | `"blur"` | `{ blur: "live" | "static" }`
+
+`IviTrackSlotRenderContext`：
+
+```ts
+interface IviTrackSlotRenderContext {
+  slot: string;
+  track: IviTrack;
+  source: IviRuntimeSource;
+  isPreloading?: boolean;
+}
+```
+
+以下组件为 `IVITrackSlot` 依赖的内部实现，当前不属于公开导出 API。
+
+### `IVITrtcPlayer`
+
+TRTC 远端流播放器，自动以 audience 身份入会并订阅远端流。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `trtc` | TRTC 实例 | TRTC SDK 实例 |
+| `sourceId` | `string` | source ID |
+| `runtime` | `IviRuntimeCoordinator` | runtime 实例 |
+| `loadingFallback` | `ReactNode` | 加载中兜底 |
+| `errorFallback` | `ReactNode` | 错误兜底 |
+| `muted` | `boolean` | 是否静音 |
+| `className` / `style` | — | 容器样式 |
+
+### `IVIHlsVideo`
+
+HLS 流播放器（基于 `hls.js`），用于 `.m3u8` 地址播放。辅助函数 `isM3u8Url(url)` 可判断 URL 是否为 m3u8。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | HLS 播放地址 |
+| `videoProps` | — | 透传给 `<video>` |
+| `style` | — | 样式 |
+| `aggressivePreload` | `boolean` | 激进预加载模式 |
+| `paused` | `boolean` | 是否暂停 |
+
+> 隐藏原生控件（包括进度条）：SDK 未提供单独隐藏进度条的开关，HTML5 `<video>` 也不支持只隐藏 timeline。可通过 `videoProps.controls = false` 关闭整套原生控件，适用于 `IVIHlsVideo` 与 `IVITrackSlot`：
+>
+> ```tsx
+> <IVIHlsVideo url={url} videoProps={{ controls: false }} />
+> <IVITrackSlot slot="main" videoProps={{ controls: false }} />
+> ```
+>
+> 若需“保留播放/音量，仅隐藏进度条”，请在上层自行渲染自定义控制栏。
+
+### `IVIVolumeControl`
+
+音量控制浮层组件。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `volume` | `number` | 当前音量 0–100 |
+| `onVolumeChange` | `(volume: number) => void` | 音量变化回调 |
+| `renderSpeakerIcon` | `(volume: number) => ReactNode` | 自定义喇叭图标 |
+| `colors` | `IVIVolumeControlColors` | 颜色配置 |
+| `className` / `style` | — | 样式 |
+
+### `IVISubtitleOverlay`
+
+字幕浮层组件，展示对话条目流式字幕。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `conversations` | `IviRuntimeConversationItem[]` | — | 会话条目列表 |
+| `maxVisible` | `number` | `2` | 同时可见的最大条目数 |
+| `dismissAfterMs` | `number` | `5000` | 条目完成后自动消失毫秒数 |
+| `subtitleStyle` | `IVISubtitleOverlayStyle` | — | 样式配置 |
+| `className` / `style` | — | — | 样式 |
+
+---
+
+## 主动发送事件（IviClient 便捷方法）
+
+`IviClient` 内置以下发送方法（自动补齐 `event_id`）：
+
+| 方法 | 说明 |
+|------|------|
+| `sendSessionStageGet()` | 请求当前 stage |
+| `sendSessionTracksList()` | 请求 track 列表 |
+| `sendSessionSourcesList()` | 请求 source 列表 |
+| `sendSessionStreamsList()` | 请求 stream 列表 |
+| `sendSessionSourcePlaybackCompleted(sourceId, trackId?)` | 上报 source 播放完成 |
+| `sendConversationList()` | 请求对话列表 |
+| `sendConversationItemCreate(item)` | 创建对话条目 |
+| `sendConversationUserText(text, itemId?)` | 发送用户文本，返回 `Promise<string>`，resolve 为最终 itemId |
+| `sendResponseCreate(streamId?, response?)` | 触发模型回复；`streamId` 可选，省略时使用 session 级配置 |
+| `sendResponseCreateByItemId(itemId, streamId?, response?)` | 基于条目 ID 触发模型回复 |
+
+---
+
+## 已解析事件范围
+
+`parseIviEvent` 已支持并有测试覆盖：
+
+- `session.created`、`session.updated`、`session.ended`
+- `session.stream.*`、`session.streams.list.response`
+- `response.*`
+- `response.output_text.*`
+- `response.output_audio_transcript.*`
+- `session.stage.updated`、`session.stage.get.response`
+- `session.track.*`、`session.tracks.list.response`
+- `session.source.*`、`session.sources.list.response`
+- `session.character.*`、`session.characters.list.response`
+- `session.environment.*`、`session.environments.list.response`
+- `session.object.*`、`session.objects.list.response`
+- `conversation.list.response`
+- `conversation.item.added`、`conversation.item.done`
+- `error`
+
+未识别类型会降级为 `UnknownIviEvent`，避免解析阶段直接中断。
+
+## 语义约束
+
+- `session`：一次 IVI 体验的最外层作用域；
+- `stage`：展示编排层，维护 `slot → track`；
+- `track`：展示播控通道，维护 active/next source 引用；
+- `source`：可被 track 播放的媒体资产（含 playback 信息）；
+- `stream`：实时推理通道，属于生成层概念，不等价于展示层 track。
+
+## 当前已知边界
+
+- 底层 `IviClient` 默认启用自动重连，并支持发送时等待连接恢复；但当前不内置应用层心跳；
+- 不内置事件去重缓存；
+- 不提供 Web Component 入口；
+- 对外以 TypeScript/React API 为主。
+
+## 本地开发
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run test
+```
+
+### 版本提升与打 tag
+
+仓库提供版本提升脚本，执行前要求工作区干净：
+
+```bash
+npm run release:version -- 0.2.2
+```
+
+脚本会同步更新 `package.json` / `package-lock.json`，提交：
+
+```text
+chore: update package version to 0.2.2
+```
+
+并创建 tag：`v0.2.2`。