@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

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

@@ -1,353 +0,0 @@
-
-# Native Live 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 Camera/Mic | 检查 `AndroidManifest.xml` 和 `Info.plist` |
-
-**验证流程**：
-
-1. 执行 `flutter build apk --debug`。
-2. 如果失败 → 分析完整错误堆栈 → 修复 → 重新构建。
-3. 循环直到 `BUILD SUCCESSFUL`。
-
-**处理流程**：
-
-1. **构建成功** → 交付代码。
-2. **构建失败** → 分析错误 → **自动修复** → 重新构建。
-* ✅ **可自动修复**：依赖缺失、Import 缺失、权限配置缺失。
-* ❌ **不可修复**：SDK 内部错误、Flutter 环境配置问题（需提示用户）。
----
-
-## 📋 指令目的与架构
-
-为 Agent 提供实现 Native (Flutter) Live AtomicXCore 核心功能的**代码生成蓝图**。
-
-**核心架构**：
-
-* **容器**：`LiveCoreWidget` (视图层)
-* **状态**：`Store` (数据驱动)
-* **事件**：`Listener` (回调处理)
-
-**功能依赖逻辑（重要）**：
-
-1. **基础先行**：必须先使用本工具（`get_flutter_live_uikit_integration`）完成基础直播（开播/观看/列表）。
-2. **互动叠加**：如果用户需求包含"连麦"、"PK"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_flutter_live_uikit_interaction`）。
-3. **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
-
----
-
-## ⚙️ 自动化工作流步骤
-
-### 步骤 0: 前置准备（自动化）
-
-1. **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
-* 主播: `anchor001`, `anchor002`, `anchor003`
-* 观众: `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` 添加 Camera/Record Audio 权限。
-* **iOS**: 在 `ios/Runner/Info.plist` 添加 `NSCameraUsageDescription` 和 `NSMicrophoneUsageDescription`。
-### 步骤 1: 获取与生成
-
-**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
-
-* **仅主播**：生成 `AnchorPage`
-* **仅观众**：生成 `AudiencePage`
-* **主播+观众**：生成 `MainPage` (入口选择) + `AnchorPage` + `AudiencePage`
-
-### 步骤 2: 验证与交付
-
-执行 `flutter build apk --debug`，确保无误后交付。
-
----
-
-## 🚫 代码生成约束（严格遵守）
-
-### 1. 通用代码约束
-
-* **严禁修改 Import**：统一使用 `import 'package:atomic_x_core/atomicxcore.dart';`。
-* **严禁臆造 API**：必须严格遵循文档中的 Store 和 Model 定义。
-* **必须查阅 API 文档**：涉及数据模型字段（如 `LiveInfo`），必须查看文档确认字段名（例如确认是 `liveOwner.userName` 而不是 `name`）。
-
-### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
-
-**核心原因**：Dart 的 Stream 和闭包监听如果不正确释放，会导致严重的内存泄漏或空指针异常。
-
-* **唯一实例原则**：所有 Listener（如 `GiftListener`, `CoGuestListener`, `BarrageListener`）**必须声明为 State 的成员变量**。
-* **严禁匿名内部类**：禁止直接在 `addListener(Listener(...))` 中写匿名对象，必须先实例化。
-* **成对原则**：在 `initState` 调用 `addListener`，则**必须**在 `dispose` 调用 `removeListener`，防止内存泄漏和监听失效。
-
-### 3. ⏱️ 超时时间限制（关键技术点）
-
-**必须严格遵守以下参数限制，优先使用文档示例中的值：**
-
-#### A. 观众连麦 (`CoGuestStore`)
-
-* **规则**：
-* 可选参数，不填则不检查超时。
-* 若填写，范围必须在 **5 - 1800 秒**之间。
-
-* **正确示例**：
-```dart
-// ✅ 推荐：跟随文档示例（如 30秒）
-guestStore.applyForSeat(seatIndex: -1, timeout: 30, extraInfo: null);
-
-```
-#### B. 主播连线/PK (`CoHostStore`)
-
-* **规则**：
-* **最大值 30 秒**（后台硬限制）。
-
-* **正确示例**：
-```dart
-// ✅ 推荐：使用最大值
-coHostStore.requestHostConnection(..., timeout: 30);
-
-```
-### 3. 🎨 扩展功能约束（美颜/音效/UI）
-
-#### A. 音效 (Audio Effect)
-
-* **变声枚举 (`AudioChangerType`)**：
-* ✅ **允许**：`AudioChangerType.child`, `AudioChangerType.man` 等标准枚举。
-* ❌ **禁止**：使用整型索引（如 `1`, `2`）。
-#### B. 美颜 (Beauty)
-
-* **参数范围**：**0.0 - 9.0** (Double)。
-* **UI 映射公式**：`sliderValue * 9.0` (假设 Slider 为 0.0-1.0)。
-
-#### C. 弹幕、礼物与布局 (Barrage, Gift & UI)
-
-* **层级要求**：使用 `Stack` 组件。
-* 底层：`LiveCoreWidget` (全屏)。
-* 顶层：弹幕、礼物、功能按钮 (使用 `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`。
-* **层级**：全屏礼物动画视图必须覆盖在 `LiveCoreWidget` **之上**。
-* **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**主播端和观众端**都必须播放全屏动画。严禁只在观众端播放。
-
-### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
-
-**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
-
-### 1. 全局视觉风格 (Global Aesthetics)
-
-* **沉浸式暗黑**：`Scaffold` 背景必须为 `Colors.black`，`LiveCoreWidget` 必须**全屏铺满** (`Positioned.fill`) 且位于最底层。
-* **安全区域**：所有悬浮 UI 必须包裹在 `SafeArea` 中。
-* **文字可读性**：视频之上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`Shadow`)。
-* **错误提示**：统一使用 `SnackBar` 或 `FlutterToast`，禁止使用模态 Dialog 打断用户。
-
-### 2. 通用组件规范 (Component Standards)
-
-* **顶部胶囊 (Glass Capsule)**：
-* **样式**：**半透明黑色背景** + **全圆角**。
-* **应用**：仅用于顶部左侧展示"主播头像+ID+热度"。
-
-* **通用按钮 (Flat Buttons)**：
-* **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
-* **关闭按钮**：特例，使用圆形半透明背景图标。
-### 3. 直播间布局蓝图 (Live Room Layout)
-
-**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如PK/美颜），严禁添加对应的空按钮**
-
-#### A. 顶部栏 (Top Bar)
-
-* **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [主播头像 | 主播昵称]。
-* **右侧 [控制区]**：横向排列 [在线观众人数] + [关闭图标(X)]。
-
-#### B. 底部栏 (Bottom Bar) - 根据状态动态切换
-
-* **预览模式 (Preview)**：
-* 内容**向右靠拢**：[美颜] [音效] [开始直播(主按钮)]。
-
-* **直播模式 (Anchor Live)**：
-* **左侧**：[弹幕列表(背景透明)] + [聊天输入框]。
-* **右侧**：功能阵列 [美颜] [音效] [连线] [PK]。
-
-* **观众模式 (Audience Live)**：
-* **左侧**：[弹幕列表] + [聊天输入框]。
-* **右侧**：[礼物] [申请连麦]。
-### 4. 首页布局与交互 (Home Interaction)
-
-#### A. 首页参考布局
-
-```
-┌─────────────────────────────┐
-│       AtomicXCore 直播       │
-│                             │
-│  直播间 ID                   │
-│  ┌─────────────────────────┐│
-│  │ live_000001             ││  ← 输入框 (带左侧 Padding, 半透明背景)
-│  └─────────────────────────┘│
-│                             │
-│  主播开播                    │
-│  (点击即以 anchor001 登录)    │
-│                             │
-│  观众观看                    │
-│  (点击即以 user001 登录)      │
-│                             │
-│       [ 📋 直播列表 ]        │
-└─────────────────────────────┘
-
-```
-
-#### B. 隐式登录流程
-
-**首页不需要单独的登录按钮**，登录在点击功能按钮时自动完成：
-
-* 点击「主播开播」→ 使用 `anchor001` 登录 → 跳转主播页。
-* 点击「观众观看」→ 使用 `user001` 登录 → 跳转观众页。
-* 点击「直播列表」→ 使用 `user001` 登录 → 跳转列表页。
-
----
-
-## 🎯 功能实现细节
-
-### 1. 主播开播 (`AnchorPage`)
-
-* **核心**：`LiveCoreWidget` + `LiveCoreController`
-* **流程**：`LiveListStore.createLive()`
-* **销毁**：`dispose` 中必须调用 `endLive()`。
-
-### 2. 观众观看 (`AudiencePage`)
-
-* **核心**：`LiveCoreWidget` + `LiveCoreController`
-* **流程**：`LiveListStore.joinLive()`
-* **销毁**：`dispose` 中必须调用 `leaveLive()`。
-
-### 3. 直播列表 (`LiveListPage`)
-
-* **核心**：`LiveListStore.fetchLiveList()` + `GridView`/`ListView`
-* **数据**：订阅 `liveState.liveList` (ValueListenable)。
-* **跳转**：点击列表项跳转观众页，传递 `liveID`。
-
-### 4. 连麦与连线交互规范 (`co_guest` & `co_host`)
-
-#### A. 观众连麦（主播被动接收）
-
-* **主播端 UI**：❌ **严禁**在底部工具栏或任何位置显示「连麦申请」列表按钮。
-* **交互逻辑**：当收到观众连麦申请回调（`onApplicationReceived`）时，直接在屏幕中心弹出对话框（`showDialog`）：
-* **标题**：连麦申请
-* **内容**：收到观众 [昵称] 的连麦申请，是否接受？
-* **操作**：[拒绝] [接受]
-
-* **自定义视图**：Flutter 版必须实现 `LiveCoreWidget.videoWidgetBuilder` 的 `coGuestWidgetBuilder`，根据 `ViewLayer` 返回 Foreground(昵称) 或 Background(头像)。
-
-#### B. 主播连线面板（点击底部【连线】按钮弹出）
-
-* **展现形式**：使用底部浮层面板（`showModalBottomSheet`），禁止使用 Dialog。
-* **UI 布局（严格对照图示）**：
-
-```
-┌─────────────────────────────────────┐
-│                                     │
-│  发起连线              [🚪 结束连线]  │  ← 红色文字
-│                                     │
-│  连线中 (2 人)                       │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]        PK中... ││  ← 已连线用户
-│  │ [👤] 菲林娜 [💎32]        PK中... ││
-│  └─────────────────────────────────┘│
-├─────────────────────────────────────┤
-│  其他连线用户                        │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]      [取消邀请] ││  ← 灰黑背景按钮
-│  │ [👤] 菲林娜 [💎32]      [邀请连线] ││  ← 蓝色背景按钮
-│  │ [👤] 铁柱   [💗99]      [邀请连线] ││
-│  └─────────────────────────────────┘│
-└─────────────────────────────────────┘
-
-```
-
-#### C. PK 按钮交互约束
-
-* **前置检查**：点击底部【PK】按钮时，必须检查当前连线状态（`CoHostStore.connectedUsers.isEmpty()`）。
-* **状态处理**：
-* **未连线**：❌ 禁止跳转，使用 Toast 提示：`"请先发起连线"`。
-* **已连线**：✅ 弹出 PK 邀请面板。
-
-* **自定义视图**：实现 `VideoWidgetBuilder.battleWidgetBuilder` 展示 PK 对方信息和分数。
-
----
-
-## 📋 Agent 最终检查清单
-
-* [ ] **编译验证**：已执行 `flutter build apk --debug` 且结果为 SUCCESS。
-* [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `LiveInfo` 字段名。
-* [ ] **超时合规**：连麦超时 5-1800s，连线超时 ≤30s。
-* [ ] **扩展合规**：音效枚举正确，美颜范围 0-9，弹幕布局覆盖且键盘适配。
-* [ ] **礼物合规**：主播和观众端均实现了全屏礼物动画显示。
-* [ ] **凭证注入**：已自动注入测试 UserSig。
-* [ ] **依赖完整**：已检查并修复 `pubspec.yaml` 和平台权限配置。
-
----
-
-## 🚨 安全提醒（代码注释模板）
-
-```dart
-/**
- * ⚠️ 测试凭证说明
- * - 当前 userSig 由开发工具自动生成，有效期 7 天
- * - ❌ 生产环境严禁在客户端生成 userSig
- * - ✅ 正式上线前必须在后端服务生成
- * - 参考: https://cloud.tencent.com/document/product/647/17275
- */
-
-```