@tencentcloud/sdk-mcp 1.3.9 → 1.4.1

package/resource/doc/livekit/voice/flutter/workflow.md

@@ -1,359 +0,0 @@
-# Native 语聊房 AtomicXCore 代码生成工作流指令 (Flutter)
-
-## 🚨 核心原则（最高优先级）
-
-**Agent 必须确保生成的代码可以成功编译运行，严禁将无法构建的代码交付给用户！**
-
-### ⚠️ 强制编译验证
-
-**每次生成/修改代码后，必须执行完整构建验证**：
-
-```bash
-flutter build apk --debug
-# 或者在 iOS 环境下
-flutter build ios --debug --no-codesign
-```
-
-**禁止行为**：
-
-* ❌ 禁止只用 `flutter analyze` 检查就认为代码正确（无法检测原生依赖问题）
-* ❌ 禁止忽略 `pubspec.yaml` 版本冲突
-
-**编译错误分类与处理**：
-| 错误类型 | 示例 | 处理方式 |
-|---------|------|---------|
-| 依赖解析失败 | `Because xxx depends on yyy...` | 检查 `pubspec.yaml` 版本兼容性，执行 `flutter pub get` |
-| 依赖缺失 | `Target of URI doesn't exist` | 添加缺失库到 `dependencies` |
-| Import 缺失 | `Undefined class 'xxx'` | 添加 import 语句 |
-| 资源缺失 | `Unable to load asset` | 在 `pubspec.yaml` 的 `assets` 节点注册资源 |
-| 权限缺失 | Crash on access Mic | 检查 `AndroidManifest.xml` 和 `Info.plist` |
-
-**验证流程**：
-
-1. 执行 `flutter build apk --debug`。
-2. 如果失败 → 分析完整错误堆栈 → 修复 → 重新构建。
-3. 循环直到 `BUILD SUCCESSFUL`。
-
-**处理流程**：
-
-1. **构建成功** → 交付代码。
-2. **构建失败** → 分析错误 → **自动修复** → 重新构建。
-* ✅ **可自动修复**：依赖缺失、Import 缺失、权限配置缺失。
-* ❌ **不可修复**：SDK 内部错误、Flutter 环境配置问题（需提示用户）。
-
----
-
-## 📋 指令目的与架构
-
-为 Agent 提供实现 Native (Flutter) 语聊房 AtomicXCore 核心功能的**代码生成蓝图**。
-
-**核心架构**：
-
-* **麦位管理**：`LiveSeatStore` (麦位数据驱动)
-* **状态**：`LiveSeatState` / `SeatInfo` / `SeatUserInfo`
-* **事件**：`Listener` (回调处理)
-
-**语聊房 vs 视频直播的核心差异**：
-| 特性 | 视频直播 | 语聊房 |
-|------|---------|-------|
-| 核心组件 | `LiveCoreWidget` | `LiveSeatStore` |
-| 媒体类型 | 音视频流 | 纯音频（麦位） |
-| 画面 | 视频画面 | 麦位头像 + 音浪动画 |
-| 核心概念 | 推流/拉流 | 麦位（seatList） |
-
-**功能依赖逻辑（重要）**：
-
-1. **基础先行**：必须先使用本工具（`get_flutter_voice_uikit_integration`）完成基础语聊房（房主开播/观众进房/房间列表）。
-2. **互动叠加**：如果用户需求包含"上麦"、"连线"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_flutter_voice_uikit_interaction`）。
-3. **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
-
----
-
-## ⚙️ 自动化工作流步骤
-
-### 步骤 0: 前置准备（自动化）
-
-1. **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
-* 房主: `host001`, `host002`, `host003`
-* 观众: `user001`, `user002`, `user003`
-
-2. **环境检查**：检查 `pubspec.yaml`，若缺失以下依赖则自动添加：
-```yaml
-dependencies:
-  flutter:
-    sdk: flutter
-  atomic_x_core: ^3.6.0  # 核心库
-  permission_handler: ^11.0.0 # 权限处理
-  svgaplayer_flutter: ^2.0.0 # 礼物动画(如需)
-```
-
-3. **权限注入**（语聊房不需要摄像头权限）：
-* **Android**: 在 `android/app/src/main/AndroidManifest.xml` 添加 Record Audio 权限。
-* **iOS**: 在 `ios/Runner/Info.plist` 添加 `NSMicrophoneUsageDescription`。
-
-### 步骤 1: 获取与生成
-
-**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
-
-* **仅房主**：生成 `HostPage`
-* **仅观众**：生成 `AudiencePage`
-* **房主+观众**：生成 `MainPage` (入口选择) + `HostPage` + `AudiencePage`
-
-### 步骤 2: 验证与交付
-
-执行 `flutter build apk --debug`，确保无误后交付。
-
----
-
-## 🚫 代码生成约束（严格遵守）
-
-### 1. 通用代码约束
-
-* **严禁修改 Import**：统一使用 `import 'package:atomic_x_core/atomicxcore.dart';`。
-* **严禁臆造 API**：必须严格遵循文档中的 Store 和 Model 定义。
-* **必须查阅 API 文档**：涉及数据模型字段（如 `SeatInfo`、`SeatUserInfo`），必须查看文档确认字段名（例如确认是 `userInfo.userName` 而不是 `name`）。
-
-### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
-
-**核心原因**：Dart 的 Stream 和闭包监听如果不正确释放，会导致严重的内存泄漏或空指针异常。
-
-* **唯一实例原则**：所有 Listener（如 `GuestListener`, `SeatListener`, `BarrageListener`）**必须声明为 State 的成员变量**。
-* **严禁匿名内部类**：禁止直接在 `addListener(Listener(...))` 中写匿名对象，必须先实例化。
-* **成对原则**：在 `initState` 调用 `addListener`，则**必须**在 `dispose` 调用 `removeListener`，防止内存泄漏和监听失效。
-
-### 3. ⏱️ 超时时间限制（关键技术点）
-
-**必须严格遵守以下参数限制，优先使用文档示例中的值：**
-
-#### A. 观众上麦 (`CoGuestStore`)
-
-* **规则**：
-* 可选参数，不填则不检查超时。
-* 若填写，范围必须在 **5 - 1800 秒**之间。
-
-* **正确示例**：
-```dart
-// ✅ 推荐：跟随文档示例（如 30秒）
-guestStore.applyForSeat(seatIndex: -1, timeout: 30, extraInfo: null);
-```
-
-#### B. 房主连线 (`CoHostStore`)
-
-* **规则**：
-* **最大值 30 秒**（后台硬限制）。
-
-* **正确示例**：
-```dart
-// ✅ 推荐：使用最大值
-coHostStore.requestHostConnection(..., timeout: 30);
-```
-
-### 4. 🎨 扩展功能约束（音效/弹幕/礼物/UI）
-
-#### A. 音效 (Audio Effect)
-
-* **变声枚举 (`AudioChangerType`)**：
-* ✅ **允许**：`AudioChangerType.child`, `AudioChangerType.man` 等标准枚举。
-* ❌ **禁止**：使用整型索引（如 `1`, `2`）。
-
-#### B. 麦位 UI 布局
-
-* **布局要求**：麦位使用 `GridView` 展示，通常 4x2 或 3x3 布局。
-* **麦位状态**：
-    * 空麦位：显示占位图标（如 `+` 号）
-    * 有人麦位：显示用户头像 + 昵称
-    * 正在说话：头像边框高亮或显示音浪动画
-    * 麦位锁定：显示锁定图标
-* **音浪动画**：订阅 `LiveSeatState.speakingUsers` 获取正在说话的用户和音量。
-
-#### C. 弹幕与礼物布局 (Barrage & Gift)
-
-* **层级要求**：使用 `Stack` 组件。
-* 底层：麦位区域 (全屏)。
-* 顶层：弹幕、礼物、功能按钮 (使用 `Positioned` 定位)。
-
-* **键盘适配**：
-* `Scaffold` 属性 `resizeToAvoidBottomInset: false`，防止键盘顶起麦位区域。
-* 输入框位于 `Stack` 顶层，使用 `MediaQuery` 监听键盘高度或使用 `Positioned(bottom: 0)` 配合 `SafeArea`。
-
-##### 弹幕输入框 (Barrage Input)
-
-* **位置**：固定在屏幕底部左侧，与功能按钮（礼物、申请上麦等）同行。
-* **样式**：半透明圆角背景 + 占位文字「说点什么...」。
-* **键盘适配**：
-* 键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
-* **必须**在 `Scaffold` 设置 `resizeToAvoidBottomInset: false`。
-
-##### 弹幕显示流 (Barrage Display Flow)
-
-* **数据源**：使用 `ValueListenableBuilder` 监听 `BarrageStore.create(liveId).barrageState.messageList`。
-* **本地回显**：发送成功后**立即**调用 `appendLocalTip` 插入本地弹幕列表，无需等待服务器回调。
-* **滚动行为**：新消息到达时自动滚动到底部。
-
-##### 全屏礼物动画 (Full-screen Gift Animation)
-
-**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
-
-* **依赖**：必须引入 `svgaplayer_flutter`。
-* **层级**：全屏礼物动画视图必须覆盖在麦位区域**之上**。
-* **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**房主端和观众端**都必须播放全屏动画。严禁只在观众端播放。
-
-### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
-
-**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
-
-### 1. 全局视觉风格 (Global Aesthetics)
-
-* **沉浸式暗黑**：`Scaffold` 背景必须为 `Colors.black` 或深色渐变。
-* **安全区域**：所有悬浮 UI 必须包裹在 `SafeArea` 中。
-* **文字可读性**：深色背景上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`Shadow`)。
-* **错误提示**：统一使用 `SnackBar` 或 `FlutterToast`，禁止使用模态 Dialog 打断用户。
-
-### 2. 通用组件规范 (Component Standards)
-
-* **顶部胶囊 (Glass Capsule)**：
-* **样式**：**半透明黑色背景** + **全圆角**。
-* **应用**：仅用于顶部左侧展示"房主头像+ID+在线人数"。
-
-* **通用按钮 (Flat Buttons)**：
-* **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
-* **关闭按钮**：特例，使用圆形半透明背景图标。
-
-### 3. 语聊房布局蓝图 (Voice Room Layout)
-
-**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如礼物/音效），严禁添加对应的空按钮**
-
-#### A. 顶部栏 (Top Bar)
-
-* **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [房主头像 | 房主昵称 | 在线人数]。
-* **右侧 [控制区]**：横向排列 [关闭图标(X)]。
-
-#### B. 麦位区域 (Seat Area) - 核心展示区
-
-* **布局方式**：使用 `GridView.builder`
-* **典型布局**：
-    * 8 麦位：4x2 或 2x4
-    * 9 麦位：3x3（房主占中心或首位）
-* **麦位状态展示**：
-    * 空麦位：圆形占位 + `+` 号图标
-    * 有人麦位：用户头像 + 昵称 + 麦克风状态图标
-    * 说话中：头像边框高亮（主题色）+ 音浪动画
-    * 锁定麦位：锁定图标覆盖
-
-#### C. 底部栏 (Bottom Bar) - 根据角色动态切换
-
-* **房主模式 (Host)**：
-* **左侧**：[弹幕列表(背景透明)] + [聊天输入框]。
-* **右侧**：功能阵列 [音效] [更多(管理麦位)]。
-
-* **观众模式 (Audience)**：
-* **左侧**：[弹幕列表] + [聊天输入框]。
-* **右侧**：[礼物] [申请上麦]。
-
-* **麦上用户模式 (On-Seat Audience)**：
-* **左侧**：[弹幕列表] + [聊天输入框]。
-* **右侧**：[礼物] [音效] [下麦]。
-
-### 4. 首页布局与交互 (Home Interaction)
-
-#### A. 首页参考布局
-
-```
-┌─────────────────────────────┐
-│       AtomicXCore 语聊房     │
-│                             │
-│  房间 ID                     │
-│  ┌─────────────────────────┐│
-│  │ voice_room_001          ││  ← 输入框 (带左侧 Padding, 半透明背景)
-│  └─────────────────────────┘│
-│                             │
-│  房主开播                    │
-│  (点击即以 host001 登录)      │
-│                             │
-│  观众进房                    │
-│  (点击即以 user001 登录)      │
-│                             │
-│       [ 📋 房间列表 ]        │
-└─────────────────────────────┘
-```
-
-#### B. 隐式登录流程
-
-**首页不需要单独的登录按钮**，登录在点击功能按钮时自动完成：
-
-* 点击「房主开播」→ 使用 `host001` 登录 → 跳转房主页。
-* 点击「观众进房」→ 使用 `user001` 登录 → 跳转观众页。
-* 点击「房间列表」→ 使用 `user001` 登录 → 跳转列表页。
-
----
-
-## 🎯 功能实现细节
-
-### 1. 房主开播 (`HostPage`)
-
-* **核心**：`LiveListStore` + `LiveSeatStore`
-* **流程**：
-    1. 创建房间：`LiveListStore.createLive()`
-    2. 初始化麦位：`LiveSeatStore.create(liveId)`
-    3. 房主自动上 0 号麦位
-* **销毁**：`dispose` 中必须调用 `endLive()`。
-
-### 2. 观众进房 (`AudiencePage`)
-
-* **核心**：`LiveListStore` + `LiveSeatStore`
-* **流程**：
-    1. 加入房间：`LiveListStore.joinLive()`
-    2. 订阅麦位：`LiveSeatStore.create(liveId).liveSeatState.seatList` (ValueListenable)
-* **销毁**：`dispose` 中必须调用 `leaveLive()`。
-
-### 3. 房间列表 (`RoomListPage`)
-
-* **核心**：`LiveListStore.fetchLiveList()` + `GridView`/`ListView`
-* **数据**：订阅 `liveState.liveList` (ValueListenable)。
-* **跳转**：点击列表项跳转观众页，传递 `liveID`。
-
-### 4. 上麦与麦位管理交互规范 (`co_guest`)
-
-#### A. 观众申请上麦（房主被动接收）
-
-* **房主端 UI**：❌ **严禁**在底部工具栏或任何位置显示「上麦申请」列表按钮。
-* **交互逻辑**：当收到观众上麦申请回调（`onApplicationReceived`）时，直接在屏幕中心弹出对话框（`showDialog`）：
-* **标题**：上麦申请
-* **内容**：收到观众 [昵称] 的上麦申请，是否接受？
-* **操作**：[拒绝] [接受]
-
-#### B. 麦位管理面板（房主点击麦位弹出）
-
-* **展现形式**：使用底部浮层面板（`showModalBottomSheet`），禁止使用 Dialog。
-* **功能列表**：
-    * 邀请上麦（空麦位）
-    * 踢下麦位（有人麦位）
-    * 禁言/解禁（有人麦位）
-    * 锁定/解锁麦位
-
----
-
-## 📋 Agent 最终检查清单
-
-* [ ] **编译验证**：已执行 `flutter build apk --debug` 且结果为 SUCCESS。
-* [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `SeatInfo`/`SeatUserInfo` 字段名。
-* [ ] **超时合规**：上麦超时 5-1800s，连线超时 ≤30s。
-* [ ] **扩展合规**：音效枚举正确，弹幕布局覆盖且键盘适配。
-* [ ] **礼物合规**：房主和观众端均实现了全屏礼物动画显示。
-* [ ] **麦位合规**：正确订阅 `seatList` 和 `speakingUsers`，实现音浪动画。
-* [ ] **凭证注入**：已自动注入测试 UserSig。
-* [ ] **依赖完整**：已检查并修复 `pubspec.yaml` 和平台权限配置。
-
----
-
-## 🚨 安全提醒（代码注释模板）
-
-```dart
-/**
- * ⚠️ 测试凭证说明
- * - 当前 userSig 由开发工具自动生成，有效期 7 天
- * - ❌ 生产环境严禁在客户端生成 userSig
- * - ✅ 正式上线前必须在后端服务生成
- * - 参考: https://cloud.tencent.com/document/product/647/17275
- */
-```