📝 docs(agora-stt): update technical documentation based on Agora RTT Demo architecture

- update technical stack to include Agora SDK and Protocol Buffers
- add manager architecture: RtcManager, RtmManager, SttManager
- add Protocol Buffer message format definition and parsing logic
- update core function flow to support incremental subtitle updates
- add file list based on Agora RTT Demo architecture
- update integration points and E2E test requirements

📝 docs(agora-stt): add detailed implementation examples

- add RtcManager, RtmManager and SttManager code examples
- add Protocol Buffer parsing implementation example
- add incremental subtitle update mechanism example
- update token acquisition and configuration integration examples
- add version history for architecture improvements

docs/stories/005.001.story.md

@@ -86,14 +86,22 @@ High - 新功能实现，增强用户体验
 ### 技术栈和框架 [Source: architecture/tech-stack.md]
 - **前端框架**: React 19.1.0 + TypeScript
 - **UI组件库**: shadcn/ui + Tailwind CSS
-- **WebSocket**: 浏览器原生WebSocket API
-- **音频处理**: MediaRecorder API
+- **Agora SDK**: agora-rtc-sdk-ng 4.20.0 + agora-rtm 2.1.9
+- **数据序列化**: Protocol Buffers + protobufjs 7.2.5
+- **音频处理**: MediaRecorder API + WebRTC
 - **测试框架**: Vitest + Testing Library
 - **后端框架**: Hono 4.8.5 + TypeORM
 - **认证系统**: JWT Bearer Token
 - **API设计**: OpenAPI规范，RESTful风格
 
 ### 项目结构指导 [Source: architecture/source-tree.md]
+- **前端管理器位置**: `src/client/admin/components/agora-stt/managers/` (基于Agora RTT Demo架构)
+  - `RtcManager.ts` - 音视频流管理
+  - `RtmManager.ts` - 实时消息传递
+  - `SttManager.ts` - 语音转文本生命周期管理
+- **Protocol Buffer定义**: `src/client/admin/components/agora-stt/protobuf/`
+  - `SttMessage.proto` - STT消息格式定义
+  - `SttMessage.js` - 生成的解析器
 - **前端组件位置**: `src/client/admin/components/agora-stt/` (管理后台专用组件)
 - **后端路由位置**: `src/server/api/agora/` (Agora相关API路由)
 - **服务模块位置**: `src/server/modules/agora/` (Agora业务逻辑模块)
@@ -119,20 +127,53 @@ const AGORA_SERVER_CONFIG = {
 };
 ```
 
-### 核心功能流程
-1. **初始化阶段**: 组件挂载，准备Agora配置
-2. **Token获取**: 调用后端API动态获取Agora Token
-3. **加入频道**: 使用动态Token调用Agora STT API加入语音转文字频道
-4. **WebSocket连接**: 建立WebSocket连接接收实时转录结果
-5. **麦克风激活**: 申请浏览器麦克风权限并开始录制
-6. **实时转录**: 发送音频流，接收并显示转录结果
-7. **Token刷新**: 监听Token过期，自动刷新Token
-8. **离开频道**: 清理资源，关闭连接
+### 核心功能流程 [基于Agora RTT Demo架构]
+1. **初始化阶段**: 组件挂载，初始化三个管理器（RtcManager、RtmManager、SttManager）
+2. **获取分布式锁**: 通过RtmManager确保只有一个转录会话
+3. **Token获取**: 调用后端API动态获取Agora Token和配置常量
+4. **启动转录任务**: 使用SttManager调用Agora STT API启动转录
+5. **音频采集传输**: RtcManager处理音频流通过WebRTC传输到Agora STT服务
+6. **Protocol Buffer数据接收**: 接收Agora STT服务返回的Protocol Buffer格式数据
+7. **数据解析处理**: 使用protobufjs解析数据，区分transcribe/translate类型
+8. **增量式字幕更新**: 实时更新转录结果，支持临时/最终结果区分
+9. **多语言翻译处理**: 同时处理多种语言的翻译结果
+10. **Token刷新和会话管理**: 监听Token过期，自动刷新和会话状态管理
+11. **资源清理**: 离开频道，释放分布式锁，清理所有资源
+
+### Protocol Buffer消息格式 [基于Agora RTT Demo]
+```protobuf
+message Text {
+  int32 vendor = 1;           // 供应商标识
+  int32 version = 2;          // 协议版本
+  int64 uid = 4;              // 用户ID
+  string data_type = 13;      // 数据类型: transcribe/translate
+  repeated Word words = 10;   // 词汇列表
+  repeated Translation trans = 14; // 翻译结果
+  string culture = 15;        // 语言文化标识
+  int64 text_ts = 16;         // 文本时间戳
+}
+
+message Word {
+  string text = 1;            // 词汇文本
+  int32 start_ms = 2;         // 开始时间(毫秒)
+  bool is_final = 4;          // 是否为最终结果
+  double confidence = 5;      // 置信度
+}
+
+message Translation {
+  bool is_final = 1;          // 是否为最终翻译
+  string lang = 2;            // 目标语言
+  repeated string texts = 3;  // 翻译文本
+}
+```
 
 ### 技术约束和要求
 - **兼容性**: 支持Chrome、Edge等现代浏览器
 - **HTTPS要求**: 生产环境需要HTTPS协议
 - **性能要求**: 转录延迟<2秒，准确率>90%
+- **数据格式**: 使用Protocol Buffer替代JSON，提高传输效率
+- **实时性**: 支持增量更新和最终结果标记
+- **多语言**: 支持多种语言的识别和翻译
 - **用户体验**: 响应式设计，支持移动端
 - **安全性**: Token动态生成，敏感配置服务器端存储
 - **认证要求**: 所有API端点需要JWT认证保护
@@ -140,10 +181,13 @@ const AGORA_SERVER_CONFIG = {
 ### 集成点
 - **现有UI系统**: 集成到shadcn/ui组件库
 - **认证系统**: 使用现有JWT认证机制
-- **状态管理**: 与现有React状态管理集成
-- **错误处理**: 统一错误处理机制
+- **状态管理**: 与现有React状态管理集成，采用增量更新模式
+- **错误处理**: 统一错误处理机制，借鉴Agora RTT Demo的完整错误处理
 - **API路由架构**: 遵循现有Hono + OpenAPI路由模式
 - **配置管理**: 使用环境变量和服务器端配置
+- **数据格式**: 集成Protocol Buffer序列化/反序列化
+- **管理器架构**: 采用RtcManager + RtmManager + SttManager分离架构
+- **实时通信**: 集成WebRTC和RTM实时通信能力
 
 ### E2E测试要求
 - **前端测试文件位置**: `tests/e2e/specs/admin/agora-stt.spec.ts`
@@ -171,26 +215,88 @@ const AGORA_SERVER_CONFIG = {
 - **核心组件**: 转录控制按钮、实时转录文本显示、音频波形可视化
 - **动画规范**: 状态切换300ms ease-out，音频波形实时更新
 
-### 前端组件Token集成详细说明 [Source: docs/agora实时语音转录翻译参考文档.md]
-前端组件需要修改以支持统一通过Token API获取配置常量，主要变更包括：
+### 前端组件架构和集成详细说明 [基于Agora RTT Demo实现方式]
+
+#### 1. 管理器架构实现
+采用Agora RTT Demo的三管理器架构：
+
+```typescript
+// src/client/admin/components/agora-stt/managers/RtcManager.ts
+export class RtcManager extends AGEventEmitter<RtcEvents> {
+  // 音视频流管理，处理音频采集和WebRTC传输
+}
+
+// src/client/admin/components/agora-stt/managers/RtmManager.ts
+export class RtmManager extends AGEventEmitter<RtmEvents> {
+  // 实时消息传递，处理分布式锁和会话状态
+  async acquireLock(): Promise<void> { /* 获取分布式锁 */ }
+  async releaseLock(): Promise<void> { /* 释放分布式锁 */ }
+}
+
+// src/client/admin/components/agora-stt/managers/SttManager.ts
+export class SttManager extends AGEventEmitter<STTEvents> {
+  // 语音转文本生命周期管理
+  async startTranscription(options: STTManagerStartOptions): Promise<void> {
+    // 获取分布式锁
+    await this.rtmManager.acquireLock();
+
+    // 获取Token和配置
+    const { token, config } = await fetchAgoraConfigAndToken('rtc');
+
+    // 启动转录任务
+    const res = await apiSTTStartTranscription({
+      uid: this.userId,
+      channel: this.channel,
+      languages: options.languages,
+      token,
+    });
+  }
+}
+```
 
-1. **移除getGlobalConfig依赖**
-   - 删除AGORA_CONFIG中的getGlobalConfig调用
-   - 配置常量统一通过Token API返回
+#### 2. Protocol Buffer数据解析
+```typescript
+// src/client/admin/components/agora-stt/protobuf/parser.ts
+export class Parser extends AGEventEmitter<ParserEvents> {
+  praseData(data: any) {
+    const textstream = protoRoot.Agora.SpeechToText.lookup("Text").decode(data);
+    if (!textstream) {
+      return console.warn("Prase data failed.");
+    }
+    this.emit("textstreamReceived", textstream);
+  }
+}
+```
 
-2. **实现配置和Token统一获取函数**
+#### 3. 增量式字幕更新机制
+```typescript
+// 基于Agora RTT Demo的字幕处理逻辑
+case "transcribe": {
+  let textStr: string = ""
+  let isFinal = false
+  words.forEach((word: any) => {
+    textStr += word.text
+    if (word.isFinal) {
+      isFinal = true
+    }
+  })
+
+  // 查找未完成的字幕记录，支持增量更新
+  const st = state.sttSubtitles.findLast((el) => {
+    return el.uid == textstream.uid && !el.isFinal
+  })
+
+  // 更新或创建字幕记录
+}
+```
+
+#### 4. 配置和Token统一获取函数
 ```typescript
 // 使用项目现有的API客户端配置获取Token和配置
 import { hc } from 'hono/client';
-import type { AgoraRoutes } from '@/server/api'; // 需要创建AgoraRoutes类型
-
-// 创建Agora客户端，使用现有的axiosFetch适配器
-const agoraClient = hc<AgoraRoutes>('/', {
-  fetch: axiosFetch, // 使用项目现有的axiosFetch适配器
-}).api.v1.agora;
+import type { AgoraRoutes } from '@/server/api';
 
 const fetchAgoraConfigAndToken = async (type: 'rtc' | 'rtm', channel?: string, userId?: string) => {
-  // 使用项目标准的API客户端调用方式
   const response = await agoraClient.token.$get({
     query: { type, channel, userId }
   });
@@ -201,7 +307,6 @@ const fetchAgoraConfigAndToken = async (type: 'rtc' | 'rtm', channel?: string, u
 
   const data = await response.json();
 
-  // 现在API返回包含Token和配置常量的完整响应
   return {
     token: data.data.token,
     config: {
@@ -214,16 +319,12 @@ const fetchAgoraConfigAndToken = async (type: 'rtc' | 'rtm', channel?: string, u
 };
 ```
 
-3. **修改组件初始化流程**
-   - 在加入频道前先获取Token和配置
-   - 使用API返回的配置常量替代getGlobalConfig
-   - 处理Token过期自动刷新
-   - 更新错误处理机制
-
-4. **Token和配置刷新机制**
-   - 监听Token过期时间
-   - 在过期前自动刷新Token和配置
-   - 处理刷新过程中的连接状态
+#### 5. 组件初始化流程优化
+- 初始化三个管理器（RtcManager、RtmManager、SttManager）
+- 采用分布式锁机制确保会话唯一性
+- 集成Protocol Buffer数据解析
+- 实现增量式字幕更新
+- 支持多语言翻译处理
 
 ### 安全考虑
 #### 认证与授权
@@ -349,6 +450,7 @@ test('Token API返回配置常量', async () => {
 | 2025-09-23 | 1.4 | 发现缺少E2E测试文件，状态回退为In Development | Bob (SM) |
 | 2025-09-23 | 1.5 | 补充Token动态获取后端路由和前端集成需求 | Bob (SM) |
 | 2025-09-23 | 1.6 | 优化：Agora前端常量统一通过Token API返回，便于调试和统一管理 | Bob (SM) |
+| 2025-09-23 | 1.7 | **架构改进**：基于Agora RTT Demo实现方式，集成管理器架构和Protocol Buffer | Bob (SM) |
 
 ## Dev Agent Record
 
@@ -374,21 +476,43 @@ test('Token API返回配置常量', async () => {
 - ⚠️ E2E测试文件待创建 - 需要创建完整的端到端测试
 - ⚠️ 前端组件需要修改以支持统一通过Token API获取配置常量
 - ⚠️ 需要实现后端Token生成路由，并扩展响应包含配置常量
+- 🔄 **架构改进**: 基于Agora RTT Demo实现方式，需要重构为管理器架构
+- 🔄 **数据格式优化**: 需要集成Protocol Buffer替代JSON格式
+- 🔄 **性能优化**: 需要实现增量式字幕更新和分布式锁机制
 
-### File List
-- `src/client/admin/components/agora-stt/AgoraSTTComponent.tsx` - 主组件文件（已存在，需要修改）
+### File List [基于Agora RTT Demo架构]
+
+#### 前端管理器文件（新增）
+- `src/client/admin/components/agora-stt/managers/RtcManager.ts` - 音视频流管理（待创建）
+- `src/client/admin/components/agora-stt/managers/RtmManager.ts` - 实时消息传递（待创建）
+- `src/client/admin/components/agora-stt/managers/SttManager.ts` - 语音转文本生命周期管理（待创建）
+- `src/client/admin/components/agora-stt/managers/events.ts` - 事件管理器基类（待创建）
+
+#### Protocol Buffer相关文件（新增）
+- `src/client/admin/components/agora-stt/protobuf/SttMessage.proto` - STT消息格式定义（待创建）
+- `src/client/admin/components/agora-stt/protobuf/SttMessage.js` - 生成的解析器（待创建）
+- `src/client/admin/components/agora-stt/protobuf/parser.ts` - Protocol Buffer解析器（待创建）
+
+#### 现有文件（需要重构）
+- `src/client/admin/components/agora-stt/AgoraSTTComponent.tsx` - 主组件文件（已存在，需要重构为管理器架构）
 - `src/client/admin/components/agora-stt/__tests__/AgoraSTTComponent.test.tsx` - 组件测试（已存在，需要更新）
-- `src/client/types/agora-stt.ts` - 类型定义（已存在，需要扩展）
+- `src/client/types/agora-stt.ts` - 类型定义（已存在，需要扩展Protocol Buffer类型）
 - `src/client/utils/agora-stt.ts` - 工具函数（已存在，需要更新）
 - `src/client/hooks/useAgoraSTT.ts` - 自定义Hook（已存在，需要更新）
 - `src/client/admin/components/agora-stt/index.ts` - 组件导出文件（已存在）
+
+#### 后端文件
 - `src/server/api/agora/token/get.ts` - Token生成路由（待创建）
 - `src/server/modules/agora/agora-token.service.ts` - Token生成服务（待创建）
 - `src/server/types/agora.ts` - 后端类型定义（待创建）
 - `src/server/api/agora/__tests__/agora-token.integration.test.ts` - Token路由集成测试（待创建）
 - `src/server/api/index.ts` - 需要导出AgoraRoutes类型（需要更新）
 - `src/client/api.ts` - 需要添加Agora客户端导出（需要更新）
+
+#### 测试文件
 - `tests/e2e/specs/admin/agora-stt.spec.ts` - E2E测试文件（待创建）
+- `src/client/admin/components/agora-stt/managers/__tests__/` - 管理器单元测试（待创建）
+- `src/client/admin/components/agora-stt/protobuf/__tests__/` - Protocol Buffer解析测试（待创建）
 
 ## QA Results