@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

package/resource/doc/tuicallkit/flutter/workflow.md

@@ -1,331 +0,0 @@
-# Flutter TUICallKit 音视频通话应用代码生成工作流指令
-
-## 📋 指令目的
-
-为 Agent 提供实现 Flutter TUICallKit **音视频通话核心功能的代码生成蓝图**,并指导 Agent **优先使用工具实时获取的最新文档内容**,专门针对 Flutter 音视频通话应用场景。
-
----
-
-## 🛑 Agent 执行硬性限制 (Guardrails)
-
-Agent 在生成代码时必须严格遵守以下指令:
-
-### 0. 🚨 核心原则(最高优先级)
-
-- ✅ 严格按照集成文档中的示例代码生成,不擅自修改
-- ✅ 完整实现登录、单人通话、多人通话功能
-- ✅ 使用 `get_usersig` 工具生成测试账号的 UserSig
-- ✅ 使用最新版本的 `tencent_calls_uikit` 包(版本号使用 `any`)
-
-### 1. 文档驱动集成
-- 严格按照工具返回的 `llm_code_generation_instructions_md` 步骤执行
-- 遵循集成文档的最佳实践和示例代码
-
-### 2. 包导入方式
-- **配置 pubspec.yaml**: 直接编辑文件添加依赖(避免 flutter 命令找不到的问题)
-  ```yaml
-  dependencies:
-    tencent_calls_uikit: any  # ⚠️ 默认使用 any,自动获取最新版本
-  ```
-- 导入语句: `import 'package:tencent_calls_uikit/tencent_calls_uikit.dart';`
-- **⚠️ 严禁使用**: `latest`、`^latest` 等写法(Flutter 不支持,会导致安装失败)
-
-### 3. 静默执行集成
-- 所有代码编写完成后,在最后一步自动安装依赖并启动项目
-- **依赖安装方式**: 直接编辑 `pubspec.yaml` 添加 `tencent_calls_uikit: any`
-- **不使用 `flutter pub add` 命令**(避免因 flutter 命令找不到导致失败)
-- **Flutter 命令执行策略(多级降级,确保成功)**:
-  1. **第一优先级**: 尝试直接执行 `flutter pub get`
-  2. **第二优先级**: 如果失败,使用 `which flutter` 获取完整路径后执行
-  3. **第三优先级**: 如果仍失败,尝试常见路径:
-     - macOS/Linux: `$HOME/flutter/bin/flutter`
-     - macOS (Homebrew): `/opt/homebrew/bin/flutter`
-  4. **最终降级**: 如果全部失败,**引导用户手动执行**(见下方指引)
-- 启动成功后提示用户在模拟器或真机中运行应用
-
-#### 📋 手动执行降级指引
-
-**当自动执行失败时,引导用户手动执行**:
-
-```bash
-# 1. 安装依赖
-flutter pub get
-
-# 2. iOS 项目额外执行
-cd ios && pod install && cd ..
-
-# 3. 启动项目
-flutter run
-```
-
-**常见问题**: flutter 命令未找到 → 检查 PATH 环境变量; pod install 失败 → 执行 `pod repo update`
-
-### 4. 鉴权凭据配置(重要)
-- 调用 `get_usersig` 工具获取 SDKAppID、UserID、UserSig
-- 为 4 个测试账号(user001/002/003/004)生成 UserSig
-- 测试阶段可硬编码鉴权信息,但需注释标注仅用于测试
-- ⚠️ 安全警告: 告知用户生产环境必须在服务端生成 UserSig
-
-### 5. LoginPage 实现约束 🔴
-
-**⚠️ 优先检查项目中是否已存在登录页**:
-- 在实现登录页面前,**必须先检查项目中是否已存在登录页面**
-- 如果已存在登录页面,**必须询问用户是否要执行默认行为**:
-  - **选项 1**: 使用默认行为(创建新的 LoginPage,包含下拉框、3 个测试账号等)
-  - **选项 2**: 在现有登录页基础上修改(保留用户的 UI 和交互逻辑,仅添加必要的 TUICallKit 登录逻辑)
-- 如果用户选择选项 2,应该:
-  - 保留用户现有的登录页面 UI 和交互逻辑
-  - 仅在登录成功后调用 `TUICallKit.instance.login` 进行二次登录
-  - 不强制使用下拉框和 3 个测试账号
-- 如果项目中不存在登录页面,或用户选择选项 1,则按照以下默认行为实现
-
-**默认登录页面实现要求**:
-- **必须实现登录页面**,包含以下功能:
-  1. **下拉框选择 UserID**: 提供 user001、user002、user003、user004 四个选项
-  2. **显示 SDKAppID**: 从 `get_usersig` 获取并显示(只读,不可编辑)
-  3. **自动生成 UserSig**: 根据选择的 UserID 自动从预生成的 UserSig 中匹配
-  4. **登录按钮**: 调用 `TUICallKit.instance.login` 登录
-- **登录接口必须调用 `TUICallKit.instance.login`**,传入从 `get_usersig` 获取的完整凭证
-- 登录成功后自动跳转到主页面(HomePage)
-
-**LoginPage 核心实现要点**:
-
-```dart
-// 1. 定义测试账号映射表(从 get_usersig 获取)
-final Map<String, String> userSigMap = {
-  'user001': 'xxx', 'user002': 'xxx', 'user003': 'xxx', 'user004': 'xxx'
-};
-
-// 2. UI 组件
-// - SDKAppID 显示(只读 TextField)
-// - UserID 下拉框(DropdownButtonFormField,选项从 userSigMap.keys 生成)
-// - 登录按钮
-
-// 3. 登录逻辑详见集成文档
-```
-
-### 6. HomePage 实现约束 🔴
-
-**必须实现主页面**,包含以下功能:
-
-1. **显示当前登录的 UserID**
-2. **音视频通话功能**(统一用户选择):
-   - **用户列表(多选)**:显示可选用户(user002、user003、user004,排除当前登录用户)
-   - **智能判断通话类型**:
-     - 选择 **1 个用户** → 自动发起**单人通话**
-     - 选择 **多个用户** → 自动发起**多人通话**
-   - **语音通话按钮**:调用 `TUICallKit.instance.calls` 发起语音通话
-   - **视频通话按钮**:调用 `TUICallKit.instance.calls` 发起视频通话
-   - **实现方式**:使用多选框 `CheckboxListTile`,支持单选和多选
-3. **退出登录按钮**:调用 `TUICallKit.instance.logout` 退出登录
-
-**HomePage 核心实现要点**:
-
-```dart
-// 1. 显示当前登录用户(Card + ListTile)
-
-// 2. 用户选择区域(统一单人/多人通话)
-// - 用户列表: List<String> availableUsers = ['user002', 'user003', 'user004'].where((u) => u != currentUserId).toList();
-// - 多选框: CheckboxListTile(支持选择 1 个或多个用户)
-// - 选中用户: List<String> selectedUsers = [];
-
-// 3. 通话按钮区域
-// - 语音通话按钮: ElevatedButton
-// - 视频通话按钮: ElevatedButton
-
-// 4. 发起通话和退出登录逻辑详见集成文档
-```
-
-### 7. MaterialApp 配置约束 🔴
-
-**必须在 MaterialApp 中添加 TUICallKit.navigatorObserver**:
-
-```dart
-MaterialApp(
-  navigatorObservers: [TUICallKit.navigatorObserver], // ⚠️ 必须添加
-  home: const LoginPage(),
-)
-```
-
-### 8. 平台配置 🔴
-
-**Android 和 iOS 平台配置请参考集成文档**:
-- Android 混淆规则、Multidex 配置详见集成文档"步骤2：工程配置 - Android"部分
-- iOS 权限配置(相机、麦克风)详见集成文档"步骤2：工程配置 - iOS"部分
-
-**⚠️ Android 混淆配置语法检查(重要)**:
-在配置 Android 混淆规则前,**必须先检查项目使用的构建脚本类型**,根据实际情况选择正确的语法:
-
-| 构建脚本文件 | 语法类型 | 混淆配置语法 |
-|-------------|---------|-------------|
-| `android/app/build.gradle` | Groovy DSL | `minifyEnabled true` |
-| `android/app/build.gradle.kts` | Kotlin DSL | `isMinifyEnabled = true` |
-
-**检查步骤**:
-1. 查看 `android/app/` 目录下的构建脚本文件名
-2. 如果是 `build.gradle` → 使用 Groovy 语法: `minifyEnabled true`
-3. 如果是 `build.gradle.kts` → 使用 Kotlin DSL 语法: `isMinifyEnabled = true`
-
-**⚠️ iOS Podfile 平台版本配置(重要)**:
-在配置 iOS 项目时,**必须在 `ios/Podfile` 中设置最低平台版本为 iOS 14.0**:
-
-```ruby
-platform :ios, '14.0'
-```
-
-**配置位置**: 在 Podfile 文件顶部,target 配置之前添加此行
-
-### 9. Flutter 项目规范
-- 使用 Flutter >= 3.24.0、Dart >= 3.5.0 版本
-- 遵循 Flutter 官方代码风格和最佳实践
-
-### 10. 环境依赖准备
-- 确保用户已安装 Flutter SDK
-- **Flutter 命令执行遵循第 3 节的多级降级策略**
-- iOS 平台需要额外执行 `cd ios && pod install && cd ..` 安装 Pods 依赖
-- **如果自动执行失败,必须生成降级脚本供用户手动执行**
-
----
-
-## 📦 核心版本要求
-
-| 工具/平台 | 最低版本要求 |
-|----------|-------------|
-| **Flutter** | >= 3.24.0 |
-| **Dart** | >= 3.5.0 |
-
-**详细的工具版本要求(Android Studio、Gradle、JDK、Xcode 等)请参考集成文档"准备工作-环境要求"部分**
-
----
-
-## 📦 自动化执行命令
-
-Agent 代码生成完成后,按顺序自动执行:
-
-```bash
-FLUTTER_PATH=$(which flutter)  # 获取实际路径
-$FLUTTER_PATH pub get          # 获取依赖(基于已编辑的 pubspec.yaml)
-cd ios && pod install && cd .. # iOS 依赖(macOS)
-$FLUTTER_PATH run              # 启动项目
-```
-
-**依赖添加方式**: 直接编辑 `pubspec.yaml` 添加 `tencent_calls_uikit: any`,避免执行 `flutter pub add` 命令
-
-**降级策略**: `which flutter` 失败 → 尝试 `$HOME/flutter/bin/flutter` → 引导用户手动执行
-
----
-
-## 📱 真机调试引导(用户指引)
-
-### iOS 真机调试
-1. USB 连接设备,信任电脑
-2. **打开 `ios/Runner.xcworkspace`**(不是 .xcodeproj)
-3. Xcode 配置签名(Automatically manage signing + Apple ID + 修改 Bundle ID)
-4. 执行 `flutter run -d ios` 或 `flutter devices` 查看设备后指定运行
-5. 首次运行需在设备上信任开发者: 设置 → 通用 → VPN与设备管理 → 信任
-
-### Android 真机调试
-1. USB 连接设备
-2. 开启开发者模式(连点版本号 7 次) + USB 调试
-3. 设备授权 USB 调试(允许)
-4. 执行 `adb devices` 验证连接,然后 `flutter run -d android`
-
----
-
-## 🔄 完整自动化流程
-
-```mermaid
-graph TD
-    A[接收用户需求] --> B[获取 Flutter 实际路径: which flutter]
-    B --> C[检查 Flutter 环境]
-    C --> D[编辑 pubspec.yaml 添加 tencent_calls_uikit: any]
-    D --> E[配置 Android 平台: 混淆规则、Multidex]
-    E --> F[配置 iOS 平台: Info.plist 权限]
-    F --> G[配置 main.dart: 添加 navigatorObserver]
-    G --> H[调用 get_usersig 工具生成 3 个账号的 UserSig]
-    H --> I[实现 LoginPage: 下拉框选择 UserID]
-    I --> J[实现 HomePage: 单人通话和多人通话]
-    J --> K[调用 record_result 记录集成结果]
-    K --> L[使用完整路径执行: $FLUTTER_PATH pub get]
-    L --> M{iOS 平台?}
-    M -->|是| N[执行 pod install]
-    M -->|否| O[跳过 pod install]
-    N --> P[引导用户连接真机调试]
-    O --> P
-    P --> Q{选择运行方式}
-    Q -->|模拟器| R[执行: $FLUTTER_PATH run]
-    Q -->|iOS 真机| S[执行: $FLUTTER_PATH run -d ios]
-    Q -->|Android 真机| T[执行: $FLUTTER_PATH run -d android]
-    R --> U[项目启动成功]
-    S --> U
-    T --> U
-```
-
----
-
-## 📝 关键要点总结
-
-| 类别 | 要求 |
-|------|------|
-| **框架版本** | Flutter >= 3.24.0、Dart >= 3.5.0 |
-| **接入方式** | pub 包方式(编辑 `pubspec.yaml` 添加 `tencent_calls_uikit: any`) |
-| **文档优先** | ⚠️ 严格遵循集成文档中的示例代码,不得擅自修改 |
-| **静默集成** | 代码编写完成后自动安装依赖并启动项目,**必须使用 `which flutter` 获取实际路径** |
-| **凭证获取** | ⚠️ 必须使用 `get_usersig` 工具为 4 个测试账号(user001/002/003/004)生成 UserSig |
-| **登录页面** | ⚠️ 必须实现下拉框选择 UserID,自动匹配 UserSig,禁止手动输入 |
-| **主页面** | ⚠️ 必须支持统一用户列表,选择 1 个用户自动发起单人通话,选择多个用户自动发起多人通话 |
-| **安全提示** | ⚠️ 必须告知用户:客户端生成 UserSig 仅适合测试,生产环境必须在服务端生成 |
-| **结果记录** | ⚠️ 集成完成后必须调用 `record_result` 工具记录结果 |
-| **平台配置** | ⚠️ Android 和 iOS 平台配置详见集成文档"步骤2：工程配置"部分 |
-| **导航观察者** | ⚠️ 必须在 MaterialApp 中添加 `TUICallKit.navigatorObserver` |
-
----
-
-## 🎯 Agent 执行检查清单
-
-在完成代码生成后,Agent 必须确认以下所有项目:
-
-### 项目初始化
-- [ ] 已编辑 `pubspec.yaml` 添加 `tencent_calls_uikit: any` 依赖
-- [ ] 已按照集成文档配置 Android 和 iOS 平台(详见"步骤2：工程配置")
-
-### 代码生成
-- [ ] 配置 `main.dart`,添加 `TUICallKit.navigatorObserver`
-- [ ] 调用 `get_usersig` 工具生成 4 个账号的 UserSig
-- [ ] 实现 LoginPage(下拉框选择 UserID,不包含手动输入框)
-- [ ] 实现 HomePage(统一用户列表,选 1 个为单人通话,选多个为多人通话)
-
-### 最终检查
-- [ ] 调用 `record_result` 工具记录集成结果
-- [ ] 执行 `flutter pub get` 和 `pod install`(iOS)
-- [ ] 启动项目,提示用户选择设备
-- [ ] 告知用户: 生产环境必须在服务端生成 UserSig
-
----
-
-## 🔗 必须使用的工具
-
-### `get_usersig` - 获取测试鉴权信息
-获取 SDKAppID、UserID(user001/002/003/004)、UserSig。
-- LoginPage: 下拉框选择 UserID
-- HomePage: 显示可选用户列表(排除当前登录用户)
-- 禁止手动输入 SDKAppID/SecretKey/UserSig
-
-### `record_result` - 记录集成结果
-完成所有集成步骤并成功启动项目后调用
-
----
-
-## 📚 相关资源链接
-
-- **TUICallKit Flutter Pub 包**:https://pub.dev/packages/tencent_calls_uikit
-- **腾讯云实时音视频 TRTC 控制台**:https://console.cloud.tencent.com/trtc
-- **服务端生成 UserSig**:https://cloud.tencent.com/document/product/647/17275
-- **开通 TRTC 服务**:https://cloud.tencent.com/document/product/647/16788
-- **Flutter 官方文档**:https://flutter.dev/docs
-
----
-
-**适用平台**: Flutter (Android & iOS)  
-**TUICallKit 版本**: tencent_calls_uikit (最新版本)  
-**最低要求**: Flutter >= 3.24.0、Dart >= 3.5.0