最佳实践与类型定义

推荐模式与主要 TypeScript 类型的摘要，便于快速参考。

最佳实践

1. 在发送消息前检查连接

if (client.state.isConnected) {
  client.sendUserTextMessage('你好');
}

2. 处理错误

try {
  await client.connect(config);
} catch (err) {
  console.error('连接失败', err);
}

3. 在需要时取消订阅事件

const off = client.on('message', handler);
off();

4. 清理时断开连接

window.addEventListener('beforeunload', () => {
  client.disconnect();
});

5. 使用 stateChange 保持 UI 响应

client.on('stateChange', updateUI);

---

核心类型：

import type {
  ConvaiClient,
  ConvaiConfig,
  ConvaiClientState,
  ChatMessage,
  IConvaiClient,
} from '@convai/web-sdk';

控制接口：

import type {
  AudioControls,
  VideoControls,
  ScreenShareControls,
} from '@convai/web-sdk';

口型同步类型：

import type {
  BlendshapeQueue,
  BlendshapeMapper,
  BlendshapeFormat,
  BlendshapeMappingConfig,
  BlendshapeNameMapping,
  OptimizedBlendshapeOutput,
} from '@convai/web-sdk';

配置接口：

interface ConvaiConfig {
  apiKey: string;                    // 必需：您的 API 密钥
  characterId: string;                // 必需：角色 ID
  endUserId?: string;                 // 可选：用于记忆和分析
  url?: string;                       // 可选：自定义 API 端点
  enableVideo?: boolean;              // 启用视频/屏幕共享（默认：false）
  startWithVideoOn?: boolean;         // 启动时开启摄像头（默认：false）
  startWithAudioOn?: boolean;         // 启动时开启麦克风（默认：false）
  ttsEnabled?: boolean;               // 启用 TTS（默认：true）
  enableLipsync?: boolean;            // 启用 blendshape（默认：false）
  blendshapeConfig?: {
    format?: 'arkit' | 'mha';         // 形变格式（默认：'mha'）
  };
  actionConfig?: {                    // 可选：角色动作
    actions: string[];
    characters: Array<{ name: string; bio: string }>;
    objects: Array<{ name: string; description: string }>;
    currentAttentionObject?: string;
  };
}

---

客户端状态管理

该 ConvaiClientState 接口可完整查看会话状态：

interface ConvaiClientState {
  isConnected: boolean;     // 已连接到角色
  isConnecting: boolean;    // 连接进行中
  isListening: boolean;     // 正在监听用户
  isThinking: boolean;      // 正在处理回复
  isSpeaking: boolean;      // 角色正在说话
  agentState: string;       // 组合状态
}

智能体状态值：

• 'disconnected' - 未连接
• 'connected' - 已连接但空闲
• 'listening' - 正在主动监听用户
• 'thinking' - 正在处理用户输入
• 'speaking' - 角色正在响应

用法：

// React
const { state } = convaiClient;
if (state.isSpeaking) {
  console.log('角色正在说话');
}

// 原生 JavaScript
client.on('stateChange', (state) => {
  console.log('状态：', state.agentState);
});

---

事件系统

SDK 使用事件驱动架构处理状态变化和消息：

可用事件：

事件	Parameters	说明
stateChange	(state: ConvaiClientState)	连接/活动状态已更改
message	(message: ChatMessage)	收到新消息
messagesChange	(messages: ChatMessage[])	消息历史已更新
connect	()	成功连接
disconnect	()	已与角色断开连接
error	(error: Error)	发生错误
botReady	()	机器人已准备好接收消息
userTranscriptionChange	(transcription: string)	用户语音转录已更新

用法：

// 订阅事件
const unsubscribe = client.on('stateChange', (state) => {
  console.log('状态已更改：', state);
});

// 取消订阅
unsubscribe();

// 或者手动
client.off('stateChange', callback);