blank/docs/prd/epic-1-stt-sdk-architecture.md

STT SDK 通用架构设计

概述

本文档描述了语音转文字数据流SDK的通用TypeScript架构设计，确保SDK可以在任何TypeScript项目中使用，不依赖特定框架。

架构设计原则

1. 框架无关性

• SDK核心不依赖任何前端框架（React、Vue、Angular等）
• 提供通用的类式API接口
• 框架适配器作为可选包提供

2. 模块化设计

• 核心SDK包：@agora/stt-sdk
• React适配器：@agora/stt-sdk/react
• Vue适配器：@agora/stt-sdk/vue
• Angular适配器：@agora/stt-sdk/angular

3. 类型安全

• 完整的TypeScript类型定义
• 编译时类型检查
• 智能代码提示

核心架构

SDK 层次结构

┌─────────────────────────────────────────┐
│           应用层 (Application)           │
├─────────────────────────────────────────┤
│         框架适配器 (可选)                │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐    │
│  │ React   │ │  Vue    │ │ Angular │    │
│  │ Adapter │ │ Adapter │ │ Adapter │    │
│  └─────────┘ └─────────┘ └─────────┘    │
├─────────────────────────────────────────┤
│           核心SDK层                      │
│  ┌─────────┐ ┌─────────┐                │
│  │ SttClient│ │ RtmClient│               │
│  └─────────┘ └─────────┘                │
├─────────────────────────────────────────┤
│           管理器层                       │
│  ┌─────────┐ ┌─────────┐                │
│  │SttManager│ │RtmManager│               │
│  └─────────┘ └─────────┘                │
├─────────────────────────────────────────┤
│           服务层                         │
│  ┌─────────┐ ┌─────────┐                │
│  │ STT API │ │ RTM API │                │
│  └─────────┘ └─────────┘                │
└─────────────────────────────────────────┘

核心组件设计

1. SttSdk (主入口)

class SttSdk {
  // 单例模式，全局配置管理
  private static instance: SttSdk
  private config: SttSdkConfig

  // 管理器实例池
  private sttManagers: Map<string, SttManager>
  private rtmManagers: Map<string, RtmManager>

  // 客户端实例池
  private sttClients: Map<string, SttClient>
  private rtmClients: Map<string, RtmClient>

  // 公共方法
  initialize(config: SttSdkConfig): Promise<void>
  createSttClient(options: SttClientOptions): SttClient
  createRtmClient(options: RtmClientOptions): RtmClient
  destroy(): Promise<void>
}

2. SttClient (通用客户端)

class SttClient {
  // 状态管理
  private state: SttClientState

  // 事件系统
  private eventEmitter: EventEmitter

  // 依赖注入
  private sttManager: SttManager
  private rtmManager: RtmManager

  // 公共API
  initialize(options: SttInitOptions): Promise<void>
  startTranscription(options: StartOptions): Promise<void>
  stopTranscription(): Promise<void>

  // 事件监听
  on(event: string, callback: Function): void
  off(event: string, callback: Function): void
}

3. 事件系统设计

interface SttClientEvents {
  initialized: () => void
  transcriptionStart: () => void
  transcriptionStop: () => void
  transcriptionResult: (result: TranscriptionResult) => void
  error: (error: SttError) => void
}

interface RtmClientEvents {
  connected: () => void
  disconnected: () => void
  userListChanged: (users: ISimpleUserInfo[]) => void
  messageReceived: (message: any) => void
}

包结构设计

1. 核心包 (@agora/stt-sdk)

stt-sdk/
├── src/
│   ├── core/
│   │   ├── SttSdk.ts          # 主SDK类
│   │   ├── SttClient.ts       # STT客户端
│   │   ├── RtmClient.ts       # RTM客户端
│   │   └── EventEmitter.ts    # 事件系统
│   ├── managers/
│   │   ├── SttManager.ts      # STT管理器封装
│   │   └── RtmManager.ts      # RTM管理器封装
│   ├── types/
│   │   ├── index.ts           # 类型定义
│   │   ├── events.ts          # 事件类型
│   │   └── errors.ts          # 错误类型
│   └── utils/
│       ├── config.ts          # 配置工具
│       └── validation.ts      # 验证工具
├── dist/                      # 构建输出
├── package.json
└── README.md

2. React适配器包 (@agora/stt-sdk/react)

stt-sdk-react/
├── src/
│   ├── hooks/
│   │   ├── useSttClient.ts    # React Hook
│   │   └── useRtmClient.ts    # React Hook
│   ├── components/
│   │   ├── SttProvider.tsx    # Context Provider
│   │   └── Transcription.tsx  # 示例组件
│   └── types/
│       └── index.ts           # React特定类型
├── dist/
├── package.json
└── README.md

3. Vue适配器包 (@agora/stt-sdk/vue)

stt-sdk-vue/
├── src/
│   ├── composables/
│   │   ├── useSttClient.ts    # Vue Composable
│   │   └── useRtmClient.ts    # Vue Composable
│   ├── components/
│   │   ├── SttProvider.vue    # Provide/Inject
│   │   └── Transcription.vue  # 示例组件
│   └── types/
│       └── index.ts           # Vue特定类型
├── dist/
├── package.json
└── README.md

集成模式

1. 纯TypeScript项目

import { createSttSdk } from "@agora/stt-sdk"

const sdk = createSttSdk()
await sdk.initialize(config)

const sttClient = sdk.createSttClient(options)
sttClient.on("transcriptionResult", handleResult)
await sttClient.initialize()

2. Node.js后端项目

import { createSttSdk } from "@agora/stt-sdk"

// 可用于服务端的语音处理
const sdk = createSttSdk()
await sdk.initialize(config)

// 处理音频文件转录
const result = await processAudioFile(audioBuffer)

3. 浏览器扩展

// 在Chrome扩展中使用
const sdk = createSttSdk()
await sdk.initialize(config)

// 捕获标签页音频进行转录
chrome.tabs.captureVisibleTab((audio) => {
  // 处理音频转录
})

性能优化策略

1. 懒加载

• 按需加载SDK模块
• 动态导入大型依赖
• 减少初始包大小

2. 连接复用

• RTM连接池管理
• 避免重复建立连接
• 智能连接保持

3. 事件优化

• 事件去重机制
• 批量事件处理
• 内存泄漏防护

4. 资源管理

• 自动垃圾回收
• 连接超时处理
• 错误恢复机制

兼容性考虑

1. 浏览器支持

• 现代浏览器（Chrome 80+, Firefox 75+, Safari 13+）
• ES2018+ 特性支持
• Module 和 CommonJS 双模式

2. TypeScript版本

• TypeScript 4.0+
• 严格的类型检查
• 完整的类型定义

3. 构建工具

• Webpack 4+
• Vite 2+
• Rollup 2+
• 支持Tree Shaking

扩展性设计

1. 插件系统

interface SttPlugin {
  name: string
  install(sdk: SttSdk): void
}

// 自定义插件示例
class AnalyticsPlugin implements SttPlugin {
  install(sdk: SttSdk) {
    sdk.on("transcriptionResult", this.trackAnalytics)
  }

  private trackAnalytics(result: TranscriptionResult) {
    // 发送分析数据
  }
}

2. 自定义适配器

// 为其他框架创建适配器
class CustomFrameworkAdapter {
  static createSttClient(sdk: SttSdk, options: any) {
    // 返回框架特定的客户端实例
  }
}

这个架构设计确保了SDK的通用性、可扩展性和高性能，同时保持了与现有代码的兼容性。