@tencentcloud/sdk-mcp 1.3.4 → 1.3.6

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

@@ -0,0 +1,816 @@
+# Flutter TUIKit 聊天应用代码生成工作流指令
+
+## 📋 指令目的
+
+为 Agent 提供实现 Flutter TUIKit Chat **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**,专门针对 Flutter 即时通信聊天应用场景。
+
+---
+
+## 🛑 Agent 执行硬性限制 (Guardrails)
+
+Agent 在生成代码时必须严格遵守以下指令：
+
+### 0. 🚨 核心页面代码来源（最高优先级）
+**这是最容易违反的约束，必须放在首位强调！**
+
+**绝对禁止行为**：
+- ❌ **严禁自己编写任何核心页面代码**（ConversationsPage、ChatPage、ContactsPage）
+- ❌ **严禁简化实现**，例如只写几十行代码的"简化版"页面
+- ❌ **严禁跳过页面代码生成**，直接让用户"参考官方示例"
+
+**强制执行要求**：
+- ✅ **必须直接使用以下官方页面文件**：
+  - `TUIKit_Flutter/chat/uikit/lib/conversations_page.dart`
+  - `TUIKit_Flutter/chat/uikit/lib/chat_page.dart`
+  - `TUIKit_Flutter/chat/uikit/lib/contacts_page.dart`
+- ✅ **必须从 `TUIKit_Flutter/chat/uikit/lib/` 目录完整复制上述文件**
+- ✅ **必须包含完整的 State 类、UI 组件树、业务逻辑**
+- ✅ **必须复制所有依赖的组件和工具类**，保持文件结构完整
+
+**验证标准**：生成的核心页面代码应与官方源码一致，功能完整
+
+### 1. 文档驱动集成
+- 必须严格按照工具返回结果中的 `llm_code_generation_instructions_md` 步骤执行
+- **必须严格按照集成文档中的示例代码生成代码**,不得擅自修改代码结构和实现方式
+- 代码生成时应完全遵循集成文档提供的最佳实践和示例,确保代码的正确性和可运行性
+
+### 2. 源码接入方式
+- TUIKit Flutter 采用 **源码接入方式**,需要从 GitHub 克隆并拷贝核心源码文件
+- **必须将源码克隆到用户项目的根目录下**（即 `项目根目录/TUIKit_Flutter/`）
+- 必须按照集成文档指引,将指定的源码文件夹（`atomic-x`、`chat/uikit`）拷贝到用户项目中
+- 拷贝时必须确保与用户项目已有的文件夹进行合并,避免直接覆盖
+
+### 3. 静默执行集成
+- 所有代码编写完成后,在最后一步自动安装依赖并启动项目
+- **Flutter 命令执行策略（多级降级，确保成功）**：
+  1. **第一优先级**：尝试直接执行 `flutter pub get`
+  2. **第二优先级**：如果失败，使用 `which flutter` 获取完整路径后执行
+  3. **第三优先级**：如果仍失败，尝试常见路径：
+     - macOS/Linux: `$HOME/flutter/bin/flutter`
+     - macOS (Homebrew): `/opt/homebrew/bin/flutter`
+  4. **最终降级**：如果全部失败，**引导用户手动执行**（见下方指引）
+- 启动成功后提示用户在模拟器或真机中运行应用
+
+#### 📋 手动执行依赖安装指引
+
+**当自动执行 `flutter pub get` 失败时，请引导用户按以下步骤操作**：
+
+**步骤 1: 打开终端并切换到项目目录**
+```bash
+cd /path/to/your/project  # 替换为实际项目路径
+```
+
+**步骤 2: 手动安装 Flutter 依赖**
+```bash
+flutter pub get
+```
+
+**步骤 3: (iOS 项目) 安装 CocoaPods 依赖**
+```bash
+cd ios
+pod install
+cd ..
+```
+
+**步骤 4: 验证依赖安装**
+```bash
+flutter doctor -v  # 检查 Flutter 环境
+flutter pub deps   # 查看依赖树
+```
+
+**步骤 5: 启动项目**
+```bash
+# 方式 1: 使用模拟器/真机
+flutter run
+
+# 方式 2: 指定设备
+flutter devices              # 列出可用设备
+flutter run -d <device-id>   # 指定设备运行
+```
+
+**💡 常见问题排查**
+
+| 错误现象 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| `bash: flutter: command not found` | Flutter 未添加到 PATH | 运行 `export PATH="$PATH:$HOME/flutter/bin"` 或参考 [Flutter 安装文档](https://docs.flutter.dev/get-started/install) |
+| `Error: Cannot find package` | pubspec.yaml 配置错误 | 检查依赖路径是否正确（`tuikit_atomic_x` 应指向 `TUIKit_Flutter/atomic-x`） |
+| `CocoaPods not installed` | iOS 缺少 CocoaPods | 运行 `sudo gem install cocoapods` |
+| `version solving failed` | 依赖版本冲突 | 运行 `flutter pub upgrade` 或使用 `dependency_overrides` |
+
+**⚠️ 提示用户**：
+1. 确保 Flutter 环境已正确安装（运行 `flutter doctor` 检查）
+2. 确保网络可访问 `pub.dev` 和 `github.com`
+3. 如果在中国大陆，建议配置镜像：
+   ```bash
+   export PUB_HOSTED_URL=https://pub.flutter-io.cn
+   export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
+   ```
+
+### 4. 鉴权凭据配置（重要）
+- **必须调用 `get_usersig` 工具获取测试用的 SDKAppID、UserID、UserSig**
+- UserID 格式：`userXXX`（XXX 为数字）,例如 `user123`
+- 测试阶段可在代码中硬编码鉴权信息,但必须在注释中明确标注仅用于测试
+- **禁止创建 `.env` 文件**用于生产环境配置
+- **⚠️ 安全警告**：必须告知用户,客户端生成 UserSig 仅适合本地测试,正式生产环境必须在服务端生成 UserSig
+
+### 5. LoginPage 实现约束 🔴
+- **必须参考 `TUIKit_Flutter/chat/demo/lib/login_page.dart` 实现登录页面**（注意路径前缀）
+- **SDKAppID、UserID、UserSig 必须直接使用 `get_usersig` 工具返回的信息**
+- **禁止在 UI 中添加 UserID 输入框**，不允许用户主动输入 UserID
+- **禁止在 UI 中添加 SDKAppID 和 UserSig 输入框**
+- **登录接口必须调用 `LoginStore.shared.login`**，传入从 `get_usersig` 获取的完整凭证
+- 登录成功后自动跳转到主页面（ConversationsPage 或 ChatPage）
+
+### 6. chat-only 模式功能限制（⚠️ 默认约束 + 用户主动要求时的例外）
+
+**默认行为**：
+当用户选择 chat-only 模式时，Agent **默认排除**以下扩展功能：
+- **默认不集成 ConversationsPage**（会话列表页面）
+- **默认不集成 ContactsPage**（联系人页面）
+- **默认仅保留核心聊天页面**：`ChatPage`
+
+**例外处理**：
+如果用户**明确要求**添加某些扩展功能（如"需要 ConversationsPage"、"要集成联系人"等），Agent **应该允许并执行**：
+- ✅ 在核心聊天页面基础上，额外集成用户明确要求的功能
+- ✅ 只添加用户明确要求的功能，不擅自扩展其他功能
+- ✅ 按照集成文档的规范正确集成所需页面
+
+**判断标准**：
+- 用户需求中包含明确的功能关键词（如"ConversationsPage"、"联系人"、"搜索"、"会话列表"等）
+- 用户明确说明需要某个扩展功能
+
+### 7. 包名导入约束 🔴
+- **正确的包名是 `package:tuikit_atomic_x/atomicx.dart`**
+- **禁止使用以下错误的包名**：
+  - ❌ `package:tuikit_atomic_x/tuikit_atomicx.dart`
+  - ❌ `package:tuikit_atomic_x/tuikit_atomic_x.dart`
+- **禁止自己推测包名**，必须严格按照集成文档中的示例代码使用
+- 所有 import 语句必须使用正确的包名路径
+
+### 8. Flutter 项目规范
+- 使用 Flutter >= 3.29.0、Dart >= 3.7.0、Kotlin >= 1.9 版本
+- 遵循 Flutter 官方代码风格和最佳实践
+- 按照集成文档配置 Android 和 iOS 平台的权限和依赖
+- **必须配置国际化和 LocaleProvider**（强制要求）：
+
+**完整的 Widget 树结构示例**：
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_localizations/flutter_localizations.dart';
+import 'package:provider/provider.dart';
+import 'package:tuikit_atomic_x/atomicx.dart';
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return ComponentTheme(
+      child: MultiProvider(
+        providers: [
+          ChangeNotifierProvider.value(value: LocaleProvider()),  // 注册 LocaleProvider
+        ],
+        child: Builder(
+          builder: (context) {
+            final localeProvider = Provider.of<LocaleProvider>(context);
+            
+            return MaterialApp(
+              title: 'TUIKit Flutter Demo',
+              theme: ThemeData(
+                colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
+                useMaterial3: true,
+              ),
+              localizationsDelegates: const [
+                AtomicLocalizations.delegate,          // TUIKit 国际化（必须）
+                GlobalMaterialLocalizations.delegate,   // Material 组件国际化
+                GlobalWidgetsLocalizations.delegate,    // Widget 国际化
+                GlobalCupertinoLocalizations.delegate,  // iOS 风格组件国际化
+              ],
+              supportedLocales: AtomicLocalizations.supportedLocales,  // 使用 TUIKit 支持的语言
+              locale: localeProvider.locale,  // 绑定当前语言
+              home: const LoginPage(),  // 替换为你的首页 Widget（如 HomePage、LoginScreen 等）
+            );
+          },
+        ),
+      ),
+    );
+  }
+}
+```
+
+**pubspec.yaml 必须添加依赖**：
+```yaml
+dependencies:
+  flutter_localizations:
+    sdk: flutter
+  provider: ^6.0.0  # 或最新版本
+```
+
+**Widget 树结构要求**（从外到内）：
+```
+ComponentTheme                        ← 最外层（TUIKit 主题组件）
+  └─ MultiProvider                    ← Provider 容器
+      └─ providers: [LocaleProvider]  ← 注册 LocaleProvider
+          └─ Builder                  ← 用于获取 context
+              └─ MaterialApp          ← 应用入口
+                  ├─ localizationsDelegates  ← 国际化委托
+                  │   ├─ AtomicLocalizations.delegate      （TUIKit 国际化，必须）
+                  │   ├─ GlobalMaterialLocalizations.delegate
+                  │   ├─ GlobalWidgetsLocalizations.delegate
+                  │   └─ GlobalCupertinoLocalizations.delegate
+                  ├─ supportedLocales  ← AtomicLocalizations.supportedLocales
+                  ├─ locale            ← localeProvider.locale（绑定语言）
+                  └─ home: YourHomePage   ← 首页（根据实际情况替换）
+```
+
+**⚠️ 关键要点**：
+1. **ComponentTheme 必须在最外层**（包裹 MultiProvider）
+2. **必须添加 AtomicLocalizations.delegate**（TUIKit 国际化委托）
+3. **supportedLocales 使用 `AtomicLocalizations.supportedLocales`**（而非手动指定）
+4. **使用 Builder + Provider.of 获取 LocaleProvider**（实现语言切换）
+5. **使用 `ChangeNotifierProvider.value(value: LocaleProvider())`**（单例模式）
+6. **添加 `const` 构造函数和常量 Widget**（性能优化）
+7. **`home` 参数根据实际需求调整**（见下方说明）
+
+**📱 `home` 参数使用场景**：
+
+| 场景 | 推荐的 `home` Widget | 说明 |
+|-----|-------------------|------|
+| 需要登录 | `const LoginPage()` 或 `const LoginScreen()` | 未登录用户先进入登录页 |
+| 已登录用户 | `const HomePage()` | 直接进入主页（包含 TabBar） |
+| 调试测试 | `const ChatPage(conversationID: 'test')` | 直接进入某个聊天页面 |
+| 引导页 | `const OnboardingPage()` | 首次使用显示引导 |
+
+**💡 常见实现方式**：
+
+```dart
+// 方式 1: 根据登录状态动态选择首页
+home: _isLoggedIn ? const HomePage() : const LoginPage(),
+
+// 方式 2: 使用路由守卫（推荐）
+initialRoute: '/',
+routes: {
+  '/': (context) => const SplashPage(),       // 启动页判断状态
+  '/login': (context) => const LoginPage(),   // 登录页
+  '/home': (context) => const HomePage(),     // 主页
+},
+```
+
+### 9. 环境依赖准备
+- 确保用户已安装 Flutter SDK、Android Studio 和 Xcode（macOS）
+- **Flutter 命令执行遵循第 3 节的多级降级策略**
+- iOS 平台需要额外执行 `cd ios && pod install && cd ..` 安装 Pods 依赖
+- **如果自动执行失败，必须生成降级脚本供用户手动执行**
+
+---
+
+## 🛠️ 集成模式分发 (Goals)
+
+根据用户的需求，Agent 必须选择对应的执行路径：
+
+### 1. 全量功能集成 (full-featured)
+
+**目标**: 实现类似微信的完整 IM 应用
+
+**核心页面**: 
+- `ConversationsPage` (会话列表)
+- `ChatPage` (聊天页面)
+- `ContactsPage` (联系人)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 构建独立的聊天应用
+- 需要完整的会话管理、通讯录、群组管理功能
+- 作为移动应用的核心功能模块
+
+**HomePage 和 TabBar 实现要求**（🔴 强制要求）:
+
+如果项目中没有 TabBar 导航，**必须创建 HomePage 作为主页面**，包含以下要求：
+
+1. **必须实现底部 TabBar**：
+   - 默认包含两个 Tab：**聊天**（ConversationsPage）和 **联系人**（ContactsPage）
+   - 使用 Flutter 的 `BottomNavigationBar` 或 `TabBar` 组件
+   
+2. **Tab 点击必须能跳转到真实页面**：
+   - 点击"聊天" Tab → 显示 `ConversationsPage`（会话列表）
+   - 点击"联系人" Tab → 显示 `ContactsPage`（联系人列表）
+   - 使用 `PageView`、`IndexedStack` 或路由切换实现页面切换
+   
+3. **HomePage 结构示例**：
+   ```dart
+   import 'package:flutter/material.dart';
+   import 'package:tuikit_atomic_x/atomicx.dart';
+   
+   class HomePage extends StatefulWidget {
+     @override
+     _HomePageState createState() => _HomePageState();
+   }
+   
+   class _HomePageState extends State<HomePage> {
+     int _selectedIndex = 0;
+     
+     final List<Widget> _pages = [
+       ConversationsPage(),  // 会话列表
+       ContactsPage(),       // 联系人
+     ];
+     
+     void _onItemTapped(int index) {
+       setState(() {
+         _selectedIndex = index;
+       });
+     }
+     
+     @override
+     Widget build(BuildContext context) {
+       return Scaffold(
+         body: IndexedStack(
+           index: _selectedIndex,
+           children: _pages,
+         ),
+         bottomNavigationBar: BottomNavigationBar(
+           items: [
+             BottomNavigationBarItem(
+               icon: Icon(Icons.chat_bubble_outline),
+               activeIcon: Icon(Icons.chat_bubble),
+               label: atomicLocale.chat,
+             ),
+             BottomNavigationBarItem(
+               icon: Icon(Icons.contacts_outlined),
+               activeIcon: Icon(Icons.contacts),
+               label: atomicLocale.contact,
+             ),
+           ],
+           currentIndex: _selectedIndex,
+           onTap: _onItemTapped,
+         ),
+       );
+     }
+   }
+   ```
+   
+   **⚠️ TabBar label 国际化要求**：
+   - **必须使用 `atomicLocale` 读取 Tab 标签文本**
+   - ❌ 禁止硬编码中文或英文文本（如 `'聊天'`、`'Chat'`）
+   - ✅ 正确用法：
+     - 聊天 Tab：`label: atomicLocale.chat`
+     - 联系人 Tab：`label: atomicLocale.contact`
+   - `atomicLocale` 会根据当前语言环境自动返回对应的翻译文本
+   
+   **💡 TabBar 最佳实践**：
+   - 使用 `icon` 和 `activeIcon` 区分选中/未选中状态（提升视觉体验）
+   - 使用语义化的图标：
+     - 聊天：`Icons.chat_bubble_outline` / `Icons.chat_bubble`
+     - 联系人：`Icons.contacts_outlined` / `Icons.contacts`
+   - 将 `onTap` 逻辑提取为独立方法 `_onItemTapped`（提高代码可读性）
+   - 变量名使用 `_selectedIndex` 比 `_currentIndex` 更语义化
+
+4. **登录成功后跳转到 HomePage**：
+   ```dart
+   // LoginPage.dart
+   await LoginStore.shared.login(...);
+   Navigator.pushReplacement(
+     context,
+     MaterialPageRoute(builder: (_) => HomePage()),  // 跳转到 HomePage
+   );
+   ```
+
+5. **禁止行为**：
+   - ❌ 登录后直接跳转到单个页面（如 ConversationsPage）而没有 TabBar
+   - ❌ 创建空的 HomePage 但没有实际的页面切换逻辑
+   - ❌ TabBar 只有一个 Tab（必须至少有"聊天"和"联系人"）
+
+---
+
+### 2. 仅集成聊天页面 (chat-only)
+
+**目标**: 适用于客服、问诊、详情页私聊等纯对话场景
+
+**核心页面**: 
+- `ChatPage` (聊天页面)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 客服咨询场景（用户点击咨询按钮进入聊天页面）
+- 医疗在线问诊（患者与医生一对一沟通）
+- 订单详情页私聊（买家与卖家沟通）
+- 社交应用中的私信功能
+
+**💡 登录成功后的页面跳转（chat-only 模式指引）**:
+
+**默认行为**：如果用户没有特别说明，登录成功后直接跳转到 `ChatPage`，打开与 `administrator` 的单聊会话。
+
+**灵活调整**：如果用户有其他诉求（如特定时机打开聊天页、指定其他会话对象），需按用户引导确认跳转时机和目标会话。
+
+**默认实现示例**：
+
+```dart
+// ✅ 登录成功，直接进入聊天页面
+Navigator.pushReplacement(
+  context,
+  MaterialPageRoute(
+    builder: (context) => const ChatPage(
+      conversationID: 'c2c_administrator',  // 默认与 administrator 单聊
+    ),
+  ),
+);
+```
+
+**⚠️ 关键要点**：
+1. **使用 `Navigator.pushReplacement`**（替换登录页，防止返回）
+2. **conversationID 格式**：单聊 `'c2c_<userID>'`，群聊 `'group_<groupID>'`
+3. **默认会话 ID**：`'c2c_administrator'`（可根据用户需求调整为其他 userID 或 groupID）
+4. **跳转时机**：默认在登录成功回调中立即跳转，如用户有特殊需求（如点击按钮后跳转），需按用户指引调整
+
+**🔴 默认排除功能（Agent 必须遵守）**:
+
+Agent 在生成 chat-only 模式代码时，**默认排除**以下功能和页面：
+
+1. **默认不集成 ConversationsPage（会话列表）**
+   - 默认不生成会话列表页面
+   - 默认不引入会话切换功能
+   - 聊天页面默认应该是独立的、直达的纯聊天界面
+
+2. **默认不集成 ContactsPage（联系人）**
+   - 默认不生成通讯录页面
+   - 默认不引入联系人管理功能
+
+3. **默认不集成底部导航栏（TabBar）**
+   - chat-only 模式下，用户通过外部路由/参数指定会话 ID
+   - 默认不需要页面切换功能
+
+---
+
+**⚠️ 用户主动要求时的例外处理**:
+
+如果用户在 chat-only 模式下**明确要求**添加某些扩展功能，Agent **应该允许并执行**：
+
+**触发条件**（满足任一即可）:
+- 用户明确说明："需要 ConversationsPage"、"要集成会话列表"、"添加会话切换功能"
+- 用户明确说明："需要 ContactsPage"、"要添加联系人"、"集成通讯录"
+- 用户明确提出其他扩展功能需求
+
+**Agent 执行流程**:
+1. ✅ **确认用户需求**：识别到用户主动要求添加扩展功能
+2. ✅ **允许集成**：在 chat-only 模式基础上，额外集成用户要求的页面
+3. ✅ **保持克制**：只添加用户明确要求的功能，不擅自扩展其他功能
+4. ✅ **遵循文档**：按照集成文档的规范正确集成所需页面
+
+---
+
+## 📦 核心版本要求
+
+| 工具/平台 | 最低版本要求 |
+|----------|-------------|
+| **Flutter** | >= 3.29.0 |
+| **Dart** | >= 3.7.0 |
+| **Kotlin** | >= 1.9 |
+| **Android Studio** | Ladybug \| 2024.2.1 及以上 |
+| **Android Gradle Plugin** | >= 7.3.1 |
+| **JDK** | 17 |
+| **Xcode** | >= 12.0（macOS） |
+
+---
+
+## 📦 安装命令示例
+Agent 执行完成代码生成后，必须按顺序执行以下命令：
+
+**⚠️ 重要：Flutter 命令执行规范**
+- 必须使用 `which flutter` 获取 Flutter 实际安装路径
+- 使用完整路径执行命令，避免环境变量问题
+- 确保在用户项目目录下执行
+
+```bash
+# 0. 获取 Flutter 实际路径（必须先执行）
+FLUTTER_PATH=$(which flutter)
+
+# 1. 清理项目
+$FLUTTER_PATH clean
+
+# 2. 获取依赖
+$FLUTTER_PATH pub get
+
+# 3. iOS 依赖安装（仅 macOS）
+cd ios && pod install && cd ..
+
+# 4. 运行项目（选择设备或模拟器）
+$FLUTTER_PATH run
+```
+
+**命令执行策略**：
+- 优先使用 `which flutter` 获取的完整路径
+- 如果 `which flutter` 失败，尝试常见路径：
+  - macOS/Linux: `$HOME/flutter/bin/flutter`
+  - 用户自定义路径（从环境变量 `FLUTTER_ROOT` 读取）
+- 如果所有路径都失败，提示用户检查 Flutter 安装
+
+---
+
+## 📱 真机调试引导
+
+### iOS 真机调试步骤
+
+#### 1. 硬件准备
+- 使用 USB 数据线连接 iPhone/iPad 到 Mac
+- 确保设备已解锁并信任此电脑（首次连接会弹出提示）
+
+#### 2. 配置开发者账号
+
+**⚠️ 重要：正确打开 iOS 项目**
+
+使用 Xcode 打开 iOS 项目时，**必须**打开 `Runner.xcworkspace` 文件（而非 `Runner.xcodeproj`）：
+
+```bash
+open ios/Runner.xcworkspace
+```
+
+**❌ 常见错误**：
+- 不要打开 `ios/Runner.xcodeproj`（会导致 CocoaPods 依赖无法识别）
+- 不要直接双击 `ios` 文件夹
+
+**✅ 正确做法**：
+- 在终端执行 `open ios/Runner.xcworkspace`
+- 或在 Finder 中找到 `ios/Runner.xcworkspace`，双击打开
+
+**配置签名**：
+
+在 Xcode 中：
+- 选择 **Runner** 项目 → **Signing & Capabilities**
+- 勾选 **Automatically manage signing**
+- 选择你的 **Apple ID**（Team）
+- 修改 **Bundle Identifier**（必须唯一，建议格式：`com.yourname.appname`）
+
+#### 3. 查看已连接设备
+```bash
+FLUTTER_PATH=$(which flutter)
+$FLUTTER_PATH devices
+```
+
+输出示例：
+```
+iPhone 15 Pro (mobile) • 00008110-XXXXX • ios • iOS 17.2
+```
+
+#### 4. 指定设备运行
+```bash
+# 方式 1: 使用设备 ID
+$FLUTTER_PATH run -d 00008110-XXXXX
+
+# 方式 2: 让 Flutter 自动选择已连接的 iOS 设备
+$FLUTTER_PATH run -d ios
+```
+
+#### 5. 首次运行授权
+- 真机首次运行会提示"不受信任的开发者"
+- 在 iPhone 上：**设置 → 通用 → VPN 与设备管理 → 开发者 App → 信任**
+- 再次运行 `$FLUTTER_PATH run -d ios`
+
+#### 6. 常见问题
+| 问题 | 解决方案 |
+|------|----------|
+| **签名错误** | 检查 Xcode 中的 Team 和 Bundle ID 配置 |
+| **设备未识别** | 重新拔插 USB 线，确保设备已解锁 |
+| **Pod 安装失败** | 执行 `cd ios && pod repo update && pod install && cd ..` |
+
+---
+
+### Android 真机调试步骤
+
+#### 1. 硬件准备
+- 使用 USB 数据线连接 Android 设备到电脑
+- 确保设备已充电（建议 > 50%）
+
+#### 2. 开启开发者模式
+在 Android 设备上：
+1. 进入 **设置 → 关于手机**
+2. 连续点击 **版本号** 7 次，开启开发者模式
+3. 返回 **设置 → 系统 → 开发者选项**
+4. 开启 **USB 调试**
+5. 连接电脑后，设备会弹出 **允许 USB 调试** 提示，点击 **允许**
+
+#### 3. 验证设备连接
+```bash
+# 方式 1: 使用 adb 命令
+adb devices
+
+# 输出示例：
+# List of devices attached
+# XXXXXXXX	device
+
+# 方式 2: 使用 Flutter 命令
+FLUTTER_PATH=$(which flutter)
+$FLUTTER_PATH devices
+```
+
+输出示例：
+```
+SM G9900 (mobile) • XXXXXXXX • android-arm64 • Android 13 (API 33)
+```
+
+#### 4. 指定设备运行
+```bash
+# 方式 1: 使用设备 ID
+$FLUTTER_PATH run -d XXXXXXXX
+
+# 方式 2: 让 Flutter 自动选择已连接的 Android 设备
+$FLUTTER_PATH run -d android
+```
+
+#### 5. 首次构建等待
+- 首次运行会下载 Gradle 依赖（可能需要 5-10 分钟）
+- 等待 `Installing build/app/outputs/flutter-apk/app.apk...` 完成
+- 应用会自动安装并启动
+
+#### 6. 常见问题
+| 问题 | 解决方案 |
+|------|----------|
+| **设备未授权** | 在手机上点击"允许 USB 调试"，勾选"始终允许" |
+| **adb devices 显示 unauthorized** | 重新拔插 USB 线，重新授权 |
+| **Gradle 下载慢** | 配置国内镜像（修改 `android/build.gradle`） |
+| **设备离线（offline）** | 执行 `adb kill-server && adb start-server` |
+
+---
+
+## 🚀 多设备同时调试
+
+如果同时连接了多个设备，可以使用以下命令选择：
+
+```bash
+FLUTTER_PATH=$(which flutter)
+
+# 查看所有设备
+$FLUTTER_PATH devices
+
+# 指定某个设备运行
+$FLUTTER_PATH run -d <device-id>
+
+# 示例：同时运行在 iOS 和 Android
+$FLUTTER_PATH run -d ios &
+$FLUTTER_PATH run -d android &
+```
+
+---
+
+## 📊 调试建议
+
+### 热重载（Hot Reload）
+应用运行后，修改代码保存时会自动热重载：
+- 在终端中按 `r` 键手动触发热重载
+- 按 `R` 键触发热重启（Hot Restart）
+- 按 `q` 键退出调试
+
+### 查看日志
+```bash
+# Flutter 日志
+$FLUTTER_PATH logs
+
+# Android 日志
+adb logcat | grep flutter
+
+# iOS 日志（需要 ios-deploy）
+ios-deploy --id <device-id> --debug
+```
+
+### 性能分析
+```bash
+# 启动性能分析
+$FLUTTER_PATH run --profile
+
+# 启动调试工具
+$FLUTTER_PATH pub global run devtools
+```
+
+---
+
+## 🔄 完整自动化流程
+
+```mermaid
+graph TD
+    A[接收用户需求] --> B[获取 Flutter 实际路径: which flutter]
+    B --> C[检查 Flutter 环境]
+    C --> D[进入项目父目录并克隆 TUIKit_Flutter]
+    D --> E[按照集成文档配置 pubspec.yaml]
+    E --> F[按照集成文档配置 iOS Podfile]
+    F --> G[按照集成文档配置 main.dart]
+    G --> H[调用 get_usersig 工具获取鉴权信息]
+    H --> I[按照集成文档实现登录逻辑]
+    I --> J[按照集成文档实现核心页面]
+    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.29.0、Dart >= 3.7.0、Kotlin >= 1.9 |
+| **接入方式** | 源码接入（从 GitHub 克隆并通过本地路径引用） |
+| **文档优先** | ⚠️ 严格遵循集成文档中的示例代码,不得擅自修改 |
+| **核心页面来源** | 🚨 **严禁自己编写核心页面代码**，必须从 `TUIKit_Flutter/chat/uikit/lib/` 完整复制官方页面文件 |
+| **页面完整性验证** | ⚠️ 核心页面代码必须 > 100 行，包含完整的 State 类、UI 组件树、业务逻辑 |
+| **静默集成** | 代码编写完成后自动安装依赖并启动项目，**必须使用 `which flutter` 获取实际路径** |
+| **凭证获取** | ⚠️ 必须使用 `get_usersig` 工具获取测试鉴权信息 |
+| **安全提示** | ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试,生产环境必须在服务端生成 |
+| **结果记录** | ⚠️ 集成完成后必须调用 `record_result` 工具记录结果 |
+| **集成模式** | 支持 full-featured（全量）和 chat-only（仅聊天）两种模式 |
+| **chat-only 限制** | ⚠️ 默认排除 ConversationsPage、ContactsPage、SearchPage；用户主动要求时允许集成 |
+| **包名约束** | ⚠️ 必须使用 `package:tuikit_atomic_x/atomicx.dart`，禁止推测包名 |
+
+---
+
+## 🎯 Agent 执行检查清单
+
+在完成代码生成后,Agent 必须确认以下所有项目：
+
+### 项目初始化
+- [ ] 已进入用户项目的父目录
+- [ ] 已克隆 TUIKit_Flutter 仓库到正确位置
+- [ ] 已按照集成文档配置 `pubspec.yaml`
+- [ ] 已按照集成文档配置 iOS Podfile（iOS 平台）
+
+### 代码生成
+- [ ] 已按照集成文档配置 `main.dart`
+- [ ] 🔴 **已调用 `get_usersig` 工具获取 SDKAppID、UserID、UserSig**
+- [ ] 🔴 **已参考 `TUIKit_Flutter/chat/demo/lib/login_page.dart` 实现登录页面**（注意路径前缀）
+- [ ] 🔴 **登录页面不包含 UserID、SDKAppID、UserSig 输入框**
+- [ ] 已按照集成文档实现登录逻辑，自动使用 `get_usersig` 返回的凭证
+- [ ] 🔴 **已从 `TUIKit_Flutter/chat/uikit/lib/` 完整复制官方页面文件**
+- [ ] 🔴 **核心页面代码行数 > 100 行（验证非简化版）**
+- [ ] 🔴 **核心页面包含完整的 State 类、UI 组件树、业务逻辑**
+- [ ] 🔴 **严禁自己编写简化版实现，严禁跳过页面代码生成**
+- [ ] 🔴 **所有 import 使用正确的包名 `package:tuikit_atomic_x/atomicx.dart`**
+- [ ] 已按照集成文档实现页面间的导航逻辑
+
+### 集成模式
+- [ ] 已根据用户需求选择正确的集成模式（full-featured 或 chat-only）
+- [ ] full-featured 模式：已集成 ConversationsPage、ChatPage、ContactsPage 等页面
+- [ ] chat-only 模式：已集成核心页面（ChatPage）
+- [ ] chat-only 模式：已根据用户需求判断是否需要集成扩展功能
+  - [ ] 如果用户未主动要求，已确认不包含 ConversationsPage、ContactsPage、SearchPage 等页面
+  - [ ] 如果用户主动要求（如"需要 ConversationsPage"），已额外集成用户明确要求的功能
+
+### 安全与提示
+- [ ] 🔴 **已告知用户**：当前生成的代码仅适用于本地测试,正式生产环境必须在服务端生成 UserSig
+- [ ] 已在代码注释中标注测试配置的位置
+
+### 最终检查
+- [ ] 🔴 **已调用 `record_result` 工具记录集成结果**
+- [ ] 🔴 **已使用 `which flutter` 获取 Flutter 实际路径**
+- [ ] 已执行 `$FLUTTER_PATH pub get` 安装依赖（使用完整路径）
+- [ ] 已执行 `pod install`（iOS 平台）
+- [ ] 已执行 `$FLUTTER_PATH run` 启动项目（使用完整路径）
+- [ ] 已提示用户选择设备或模拟器运行
+- [ ] 项目可以正常运行,无报错
+
+---
+
+## 🔗 必须使用的工具
+
+### `get_usersig` - 获取测试鉴权信息
+**用途**：获取腾讯云 IM 测试用的鉴权信息
+- `SDKAppID`: 应用标识
+- `UserID`: 用户 ID
+- `UserSig`: 用户签名
+
+**使用约束**：
+- ✅ 必须使用 `get_usersig` 工具获取测试鉴权
+- ❌ 禁止让用户手动输入或从控制台复制
+- ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试,生产环境必须在服务端生成
+
+### `record_result` - 记录集成结果
+**用途**：记录集成过程和结果,用于统计和分析
+
+**调用时机**：在完成所有集成步骤并成功启动项目后调用
+
+---
+
+## 📚 相关资源链接
+
+- **TUIKit Flutter GitHub 仓库**：https://github.com/Tencent-RTC/TUIKit_Flutter
+- **腾讯云即时通信 IM 控制台**：https://console.cloud.tencent.com/im
+- **服务端生成 UserSig**：https://cloud.tencent.com/document/product/269/32688
+- **开通 IM 服务**：https://cloud.tencent.com/document/product/269/36838
+- **Flutter 官方文档**：https://flutter.dev/docs
+
+---
+
+**适用平台**: Flutter (Android & iOS)  
+**TUIKit 版本**: tuikit_atomic_x (AtomicXCore 版本)  
+**最低要求**: Flutter >= 3.29.0、Dart >= 3.7.0