2
0
فهرست منبع

📝 docs(architecture): update SDK core architecture documentation

- 添加4项新的验收标准:音频源选择、频道管理、翻译控制和翻译流程管理
- 更新任务列表,将Task 13标记为已完成,新增Task 14-17及对应子任务
- 添加音频源选择、频道管理和翻译控制的技术实现细节
- 提供音频设备选择、频道管理和翻译控制的代码示例
- 更新变更历史,记录2025-09-29添加的新功能需求
- 更新待完成任务列表,反映最新的开发状态
yourname 2 ماه پیش
والد
کامیت
46b50817a9
1فایلهای تغییر یافته به همراه169 افزوده شده و 15 حذف شده
  1. 169 15
      docs/stories/1.1.sdk-core-architecture.md

+ 169 - 15
docs/stories/1.1.sdk-core-architecture.md

@@ -34,6 +34,10 @@
 16. **监听和处理转录结果事件**,确保实时更新显示内容
 17. **支持UMD格式打包**,配置Vite生成UMD格式的SDK包
 18. **创建UMD格式测试页面**,验证SDK在AMD环境中的使用
+19. **为UMD演示页面添加音频源选择功能**,支持麦克风、扬声器等音频设备选择
+20. **实现频道管理功能**,支持创建频道、加入频道、离开频道操作
+21. **添加翻译控制功能**,支持选择源语言和目标语言(可多项选择)
+22. **完善开始翻译和停止翻译控制**,提供完整的翻译流程管理
 
 ## Tasks / Subtasks
 
@@ -117,12 +121,40 @@
 - [x] Task 12: **支持UMD格式打包** (AC: 17)
   - [x] 更新Vite配置,添加UMD格式支持
   - [x] 验证UMD格式构建成功
-- [ ] Task 13: **创建UMD格式测试页面** (AC: 18)
-  - [ ] 在src/pages/目录下创建umd-test页面
-  - [ ] 实现基于AMD模块加载器的SDK使用示例
-  - [ ] 验证UMD格式SDK在浏览器环境中的功能
-  - [ ] 添加路由配置,支持/umd-test路径访问
-  - [ ] 编写E2E测试验证UMD格式功能
+- [x] Task 13: **创建UMD格式测试页面** (AC: 18)
+  - [x] 在src/pages/目录下创建umd-test页面
+  - [x] 实现基于AMD模块加载器的SDK使用示例
+  - [x] 验证UMD格式SDK在浏览器环境中的功能
+  - [x] 添加路由配置,支持/umd-test路径访问
+  - [x] 编写E2E测试验证UMD格式功能
+
+- [ ] Task 14: **为UMD演示页面添加音频源选择功能** (AC: 19)
+  - [ ] 在UMD测试页面中添加音频设备选择组件
+  - [ ] 实现麦克风、扬声器等音频设备枚举和选择
+  - [ ] 集成Agora RTC SDK的音频设备管理功能
+  - [ ] 添加音频设备切换和状态显示
+  - [ ] 编写音频源选择的单元测试
+
+- [ ] Task 15: **实现频道管理功能** (AC: 20)
+  - [ ] 添加频道创建、加入、离开功能
+  - [ ] 实现频道状态管理和显示
+  - [ ] 支持频道权限和用户管理
+  - [ ] 添加频道事件监听和处理
+  - [ ] 编写频道管理的E2E测试
+
+- [ ] Task 16: **添加翻译控制功能** (AC: 21)
+  - [ ] 实现源语言选择功能,支持多种语言
+  - [ ] 添加目标语言选择,支持多项选择
+  - [ ] 集成语言配置到转录和翻译流程
+  - [ ] 实现语言切换的实时更新
+  - [ ] 编写翻译控制功能的单元测试
+
+- [ ] Task 17: **完善开始翻译和停止翻译控制** (AC: 22)
+  - [ ] 实现翻译流程的完整控制
+  - [ ] 添加翻译状态管理和显示
+  - [ ] 支持翻译任务的启动、暂停、停止
+  - [ ] 集成翻译结果实时显示
+  - [ ] 编写翻译控制的E2E测试
 
 ## Dev Notes
 
@@ -189,6 +221,27 @@
 - **现有代码保持**: src/目录下的现有代码保持不变
 - **集成方式**: SDK作为独立包,主应用通过workspace引用
 
+### 音频源选择技术实现 [Source: architecture/tech-stack.md#Agora RTC SDK 4.20.0]
+
+- **音频设备枚举**: 使用Agora RTC SDK的`AgoraRTC.getDevices()`获取音频设备列表
+- **麦克风选择**: 通过`AgoraRTC.createMicrophoneAudioTrack()`创建麦克风音频轨道
+- **扬声器选择**: 使用`AgoraRTC.setPlaybackDevice()`设置播放设备
+- **设备切换**: 支持实时音频设备切换和状态同步
+
+### 频道管理技术实现 [Source: architecture/tech-stack.md#Agora RTC SDK 4.20.0]
+
+- **频道创建**: 使用Agora RTC SDK的`AgoraRTC.createClient()`创建客户端
+- **频道加入**: 通过`client.join()`方法加入频道
+- **频道离开**: 使用`client.leave()`方法离开频道
+- **用户管理**: 监听`user-published`和`user-unpublished`事件管理用户状态
+
+### 翻译控制技术实现 [Source: architecture/tech-stack.md#Agora STT 服务]
+
+- **语言配置**: 支持多种源语言和目标语言配置
+- **翻译任务**: 通过STT管理器启动多语言翻译任务
+- **实时翻译**: 监听翻译结果事件,实时显示翻译内容
+- **语言切换**: 支持动态语言切换,无需重新初始化
+
 ### SDK集成示例代码
 
 **主应用集成SDK示例**:
@@ -222,16 +275,101 @@ sttSdk.on("transcriptionResult", (result) => {
 ```typescript
 // src/router/index.tsx 中添加sdk-test路由
 const SdkTestPage = lazy(() => import('../pages/sdk-test'))
+const UmdTestPage = lazy(() => import('../pages/umd-test'))
 
 const routerItems = [
   <Route path="/" element={<LoginPage />} />,
   <Route path="/home" element={<HomePage />} />,
   <Route path="/login" element={<LoginPage />} />,
   <Route path="/sdk-test" element={<SdkTestPage />} />, // 新增路由
+  <Route path="/umd-test" element={<UmdTestPage />} />, // 新增UMD测试路由
   <Route path="*" element={<NotFoundPage />} />,
 ]
 ```
 
+**音频源选择示例**:
+
+```typescript
+// 音频设备枚举和选择
+const getAudioDevices = async () => {
+  const devices = await AgoraRTC.getDevices()
+  const microphones = devices.filter((device) => device.kind === "audioinput")
+  const speakers = devices.filter((device) => device.kind === "audiooutput")
+
+  return { microphones, speakers }
+}
+
+// 选择麦克风设备
+const selectMicrophone = async (deviceId: string) => {
+  const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({
+    microphoneId: deviceId,
+  })
+  return audioTrack
+}
+
+// 选择扬声器设备
+const selectSpeaker = async (deviceId: string) => {
+  await AgoraRTC.setPlaybackDevice(deviceId)
+}
+```
+
+**频道管理示例**:
+
+```typescript
+// 创建和加入频道
+const joinChannel = async (channelName: string, userId: number) => {
+  const client = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" })
+
+  await client.join(appId, channelName, token, userId)
+
+  return client
+}
+
+// 离开频道
+const leaveChannel = async (client: IAgoraRTCClient) => {
+  await client.leave()
+}
+
+// 监听用户加入/离开
+client.on("user-joined", (user) => {
+  console.log("用户加入:", user.uid)
+})
+
+client.on("user-left", (user) => {
+  console.log("用户离开:", user.uid)
+})
+```
+
+**翻译控制示例**:
+
+```typescript
+// 配置多语言翻译
+const translationConfig = {
+  languages: [
+    {
+      source: "zh-CN", // 源语言
+      target: ["en-US", "ja-JP", "ko-KR"], // 目标语言(可多项)
+    },
+  ],
+}
+
+// 开始翻译
+const startTranslation = async () => {
+  await sttManager.startTranscription(translationConfig)
+}
+
+// 停止翻译
+const stopTranslation = async () => {
+  await sttManager.stopTranscription()
+}
+
+// 监听翻译结果
+sttManager.on("transcriptionResult", (result) => {
+  console.log("原文:", result.transcribe1)
+  console.log("翻译结果:", result.translate1List)
+})
+```
+
 ### 实时语音识别结果显示问题分析与修复
 
 **问题识别**:
@@ -403,6 +541,7 @@ export const testLanguages = ["zh-CN", "en-US", "ja-JP"]
 | 2025-09-26 | 2.2     | **发现功能不完整**:识别SDK缺少RtcManager集成,更新故事状态和验收标准               | Bob (SM)    |
 | 2025-09-26 | 2.3     | **识别实时语音识别结果显示缺失**:发现SDK测试页面缺少转录结果显示功能,添加相关任务 | Bob (SM)    |
 | 2025-09-26 | 2.4     | **添加UMD格式支持**:配置Vite生成UMD格式SDK包,更新故事添加UMD测试页面需求          | Bob (SM)    |
+| 2025-09-29 | 2.5     | **扩展UMD演示页面功能**:为UMD演示页面添加音频源选择、频道管理、翻译控制功能需求    | Bob (SM)    |
 
 ## Dev Agent Record
 
@@ -432,18 +571,33 @@ export const testLanguages = ["zh-CN", "en-US", "ja-JP"]
 
 ### 待完成任务
 
-12. ❌ **RtcManager集成**: 需要实现RtcManagerAdapter以支持完整的音频传输功能
+14. ❌ **音频源选择功能**: 需要为UMD演示页面添加音频设备选择功能
+
+- [ ] 实现音频设备枚举和选择
+- [ ] 集成麦克风和扬声器设备管理
+- [ ] 添加音频设备切换界面
+- [ ] 编写音频源选择的单元测试
+
+15. ❌ **频道管理功能**: 需要实现完整的频道管理功能
+
+- [ ] 添加频道创建、加入、离开功能
+- [ ] 实现频道状态显示和管理
+- [ ] 支持多用户频道管理
+- [ ] 编写频道管理的E2E测试
+
+16. ❌ **翻译控制功能**: 需要添加多语言翻译控制
 
-- [ ] 创建RtcManagerAdapter类
-- [ ] 集成到SDK测试页面
-- [ ] 扩展E2E测试验证音频传输
+- [ ] 实现源语言和目标语言选择
+- [ ] 支持多项翻译目标语言配置
+- [ ] 集成语言配置到转录流程
+- [ ] 编写翻译控制功能的单元测试
 
-13. ❌ **实时语音识别结果显示**: 需要在SDK测试页面中添加转录结果显示功能
+17. ❌ **翻译流程控制**: 需要完善开始翻译和停止翻译控制
 
-- [ ] 添加实时转录结果显示区域
-- [ ] 实现转录结果事件监听和处理
-- [ ] 集成多语言字幕显示组件
-- [ ] 扩展E2E测试验证实时结果显示
+- [ ] 实现翻译任务的完整生命周期管理
+- [ ] 添加翻译状态显示和错误处理
+- [ ] 支持翻译任务的暂停和恢复
+- [ ] 编写翻译控制的E2E测试
 
 ### File List