@tencentcloud/sdk-mcp 1.3.7 → 1.3.9

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

@@ -0,0 +1,713 @@
+# Android TUIKit Compose 聊天应用代码生成工作流指令
+
+## 📋 指令目的
+
+为 Agent 提供实现 Android TUIKit Compose Chat **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**，专门针对 Android 即时通信聊天应用场景。
+
+
+---
+
+## 🛑 Agent 执行硬性限制 (Guardrails)
+
+Agent 在生成代码时必须严格遵守以下指令：
+
+### 0. 🔴 环境检查与配置替换 (集成前的第一步 - 最高优先级)
+**⚠️ 严格按照文档提供的配置代码进行替换**
+
+**核心原则**: 必须使用文档提供的精确配置代码替换用户项目的配置文件,确保配置的统一性和兼容性
+
+**🚨 强制性环境要求**:
+- ✅ **Android Studio**: Ladybug | 2024.2.1 及以上版本
+- ✅ **Android 系统**: Android 5.0 (API 21) 及以上版本
+- ✅ **Gradle**: 8.9 及以上版本
+- ✅ **Android Gradle Plugin**: 8.6 及以上版本
+- ✅ **JDK**: 17 及以上版本
+- ✅ **Kotlin**: 1.9.0 及以上版本
+
+### 1. 🔴 配置文件替换原则 (最高优先级)
+
+**核心要求**: 项目中的所有配置必须严格按照文档提供的代码进行替换,编译时如果出现配置冲突或依赖缺失问题时，直接把错误信息提供给 AI 进行解决。
+
+**✅ 强制执行要求**:
+1. **必须使用文档提供的精确配置代码**:
+   - 所有配置代码必须来源于集成文档中明确提供的代码块
+   - **gradle/libs.versions.toml 配置必须通过 MCP 工具从集成文档实时读取**
+   - 每个配置项必须与集成文档中的示例完全一致
+   - 禁止修改、简化或优化集成文档提供的配置代码
+
+2. **必须进行完整的配置替换**:
+   - 用户项目的配置文件必须被文档提供的配置完全替换
+   - 不得保留用户项目原有的冲突配置
+   - 确保配置的统一性和兼容性
+
+3. **配置文件替换清单**:
+   - `app/build.gradle.kts`: 必须按照文档提供的完整配置替换
+   - `AndroidManifest.xml`: 必须按照文档提供的配置替换
+   - `proguard-rules.pro`: 必须按照文档提供的配置替换
+   - `gradle/libs.versions.toml`: **必须从集成文档中读取完整配置**
+   - `settings.gradle.kts`: 必须按照文档提供的配置替换
+
+**🔍 执行验证机制**:
+在生成每个配置文件前，Agent 必须自问：
+- [ ] 我是否调用了 MCP 工具获取最新文档？
+- [ ] 我是否完整复制了文档中的配置代码？
+- [ ] 我是否避免了使用记忆中的配置？
+- [ ] 我是否确保配置与文档示例完全一致？
+
+**📋 配置替换检查清单**:
+- [ ] 是否严格按照文档提供的代码进行配置?
+- [ ] 是否避免了从 atomicx 同步任何配置文件?
+- [ ] 所有配置项是否与文档示例完全一致?
+- [ ] 是否进行了完整的配置替换而非部分修改?
+- [ ] 配置文件是否保持了统一性和兼容性?
+
+### 2. 🚨 核心页面代码来源（最高优先级）
+**这是最容易违反的约束，必须放在首位强调！**
+
+**绝对禁止行为**：
+- ❌ **严禁自己编写任何核心页面代码**（ConversationsPage、ChatPage、ContactsPage）
+- ❌ **严禁简化实现**，例如只写几十行代码的"简化版"页面
+- ❌ **严禁跳过页面代码生成**，直接让用户"参考官方示例"
+
+**强制执行要求**：
+- ✅ **必须直接使用以下官方页面文件**：
+  - `TUIKit_Android_Compose/chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ConversationsPage.kt`
+  - `TUIKit_Android_Compose/chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ChatActivity.kt`
+  - `TUIKit_Android_Compose/chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ContactsPage.kt`
+- ✅ **必须从官方 `TUIKit_Android_Compose/chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/` 目录完整复制上述文件**
+- ✅ **必须包含完整的 Activity/Composable、UI 组件树、业务逻辑**
+- ✅ **必须复制所有依赖的组件和工具类**，保持文件结构完整
+
+**验证标准**：生成的核心页面代码应与官方源码一致，功能完整
+
+### 3. 文档驱动集成
+- 必须严格按照工具返回结果中的 `llm_code_generation_instructions_md` 步骤执行
+- **必须严格按照集成文档中的示例代码生成代码**，不得擅自修改代码结构和实现方式
+- 代码生成时应完全遵循集成文档提供的最佳实践和示例，确保代码的正确性和可运行性
+
+### 4. 源码接入方式
+- TUIKit Android Compose 采用 **源码接入方式**，需要从 GitHub 克隆并拷贝核心源码文件
+- **必须将源码克隆到用户项目的同级目录下**（即 `../TUIKit_Android_Compose/`）
+- 必须按照集成文档指引，将指定的源码文件夹（`atomicx`、`chat/uikit`）拷贝到用户项目中
+- 拷贝时必须确保与用户项目已有的文件夹进行合并，避免直接覆盖
+
+### 5. 静默执行集成
+- 所有代码编写完成后，在最后一步提示用户执行 Gradle Sync 并启动项目
+- **Android 项目配置规范**：
+  1. **第一优先级**：提示用户在 Android Studio 中点击 "File > Sync Project with Gradle Files"
+  2. **第二优先级**：等待 Gradle 同步完成，如果出现错误立即分析并修复
+  3. **第三优先级**：引导用户点击 Run 按钮启动项目
+  4. **最终降级**：如果同步失败，提供详细的错误排查指引
+
+#### 📋 手动执行 Gradle 同步指引
+
+**当自动 Gradle 同步失败时，请引导用户按以下步骤操作**：
+
+**步骤 1: 在 Android Studio 中手动同步**
+- 点击菜单栏 **File** → **Sync Project with Gradle Files**
+- 或点击工具栏的 **Sync** 图标（双箭头循环图标）
+
+**步骤 2: 检查同步状态**
+- 查看底部的 **Build** 窗口，等待同步完成
+- 如果出现红色错误信息，记录完整错误日志
+
+**步骤 3: 常见错误处理**
+```bash
+# 清理项目缓存
+./gradlew clean
+
+# 重新下载依赖
+./gradlew --refresh-dependencies
+```
+
+**💡 常见问题排查**
+
+| 错误现象 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| `Project 'atomicx' not found` | settings.gradle.kts 配置错误 | 检查同级目录引用路径 |
+| `Unresolved reference: Material3` | 依赖配置缺失 | 检查 libs.versions.toml 配置 |
+| `Duplicate class found` | 依赖版本冲突 | 统一依赖版本号 |
+| `AGP version requires Java 17` | JDK 版本过低 | 升级到 JDK 17+ |
+
+**⚠️ 提示用户**：
+1. 确保 Android Studio 版本 >= Ladybug | 2024.2.1
+2. 确保 JDK 版本 >= 17
+3. 确保网络可访问 `maven.google.com` 和 `mavenCentral()`
+4. 如果在中国大陆，建议配置镜像：
+   ```kotlin
+   // 在 settings.gradle.kts 中添加
+   dependencyResolutionManagement {
+       repositories {
+           maven { url = uri("https://maven.aliyun.com/repository/google") }
+           maven { url = uri("https://maven.aliyun.com/repository/central") }
+           google()
+           mavenCentral()
+       }
+   }
+   ```
+
+### 6. 鉴权凭据配置（重要）
+- **必须调用 `get_usersig` 工具获取测试用的 SDKAppID、UserID、UserSig**
+- UserID 格式：`userXXX`（XXX 为数字），例如 `user123`
+- 测试阶段可在代码中硬编码鉴权信息，但必须在注释中明确标注仅用于测试
+- **禁止创建 `.env` 文件**用于生产环境配置
+- **⚠️ 安全警告**：必须告知用户，客户端生成 UserSig 仅适合本地测试，正式生产环境必须在服务端生成 UserSig
+
+### 7. LoginPage 实现约束 🔴
+- **必须参考 `TUIKit_Android_Compose/chat/demo/app/src/main/java/io/trtc/tuikit/chat/login/LoginPage.kt` 实现登录页面**
+- **SDKAppID、UserID、UserSig 必须直接使用 `get_usersig` 工具返回的信息**
+- **禁止在 UI 中添加 UserID 输入框**，不允许用户主动输入 UserID
+- **禁止在 UI 中添加 SDKAppID 和 UserSig 输入框**
+- **登录接口必须调用 `LoginStore.shared.login`**，传入从 `get_usersig` 获取的完整凭证
+- 登录成功后自动跳转到主页面（ConversationsPage 或 ChatActivity）
+
+### 8. chat-only 模式功能限制（⚠️ 默认约束 + 用户主动要求时的例外）
+
+**默认行为**：
+当用户选择 chat-only 模式时，Agent **默认排除**以下扩展功能：
+- **默认不集成 ConversationsPage**（会话列表页面）
+- **默认不集成 ContactsPage**（联系人页面）
+- **默认仅保留核心聊天页面**：`ChatActivity`
+
+**例外处理**：
+如果用户**明确要求**添加某些扩展功能（如"需要 ConversationsPage"、"要集成联系人"等），Agent **应该允许并执行**：
+- ✅ 在核心聊天页面基础上，额外集成用户明确要求的功能
+- ✅ 只添加用户明确要求的功能，不擅自扩展其他功能
+- ✅ 按照集成文档的规范正确集成所需页面
+
+**判断标准**：
+- 用户需求中包含明确的功能关键词（如"ConversationsPage"、"联系人"、"搜索"、"会话列表"等）
+- 用户明确说明需要某个扩展功能
+
+### 9. Import 路径约束 🔴
+- **正确的包路径必须严格按照官方示例代码中的使用方式**
+- **禁止推测任何包路径**：
+  - ❌ `io.trtc.tuikit.core.xxx`（推测的错误路径）
+  - ❌ 任何通配符 import
+- **禁止自己推测包名**，必须严格按照集成文档中的示例代码使用
+- 所有 import 语句必须使用正确的包名路径
+
+### 10. Android 项目规范
+- 使用 Android Studio >= Ladybug | 2024.2.1、JDK >= 17、Kotlin >= 1.9.0 版本
+- 遵循 Android 官方代码风格和最佳实践
+- 按照集成文档配置 Android 平台的权限和依赖
+- **必须配置 Compose 和主题系统**（强制要求）：
+
+**完整的 Activity 结构示例**：
+```kotlin
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.ui.Modifier
+import io.trtc.tuikit.atomicx.theme.LocalTheme
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            MaterialTheme {
+                Surface(
+                    modifier = Modifier.fillMaxSize(),
+                    color = LocalTheme.current.colors.background
+                ) {
+                    // 你的主页面内容
+                    HomePage()
+                }
+            }
+        }
+    }
+}
+```
+
+**⚠️ 关键要点**：
+1. **必须使用 `LocalTheme.current.colors` 获取主题颜色**
+2. **直接在 `setContent` 中使用 Compose 内容**
+3. **可选使用 `MaterialTheme` 和 `Surface` 提供背景色**
+4. **参考官方 demo 示例中的实现**
+
+**📋 官方 MainActivity 参考实现**：
+- **必须参考官方示例**：`TUIKit_Android_Compose/chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt`
+- **页面回调实现**：参考官方示例中的页面跳转和回调处理逻辑
+- **底部导航结构**：遵循官方 demo 中的导航栏设计模式
+- **事件处理机制**：复制官方示例中的点击事件和页面切换逻辑
+
+### 11. 环境依赖准备
+- 确保用户已安装 Android Studio、JDK 17+
+- **Gradle 同步遵循第 3 节的多级降级策略**
+- **如果自动同步失败，必须生成降级指引供用户手动执行**
+
+---
+
+## 🛠️ 集成模式分发 (Goals)
+
+根据用户的需求，Agent 必须选择对应的执行路径：
+
+### 1. 全量功能集成 (full-featured)
+
+**目标**: 实现类似微信的完整 IM 应用
+
+**核心页面**: 
+- `ConversationsPage` (会话列表)
+- `ChatActivity` (聊天页面)
+- `ContactsPage` (联系人)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 构建独立的聊天应用
+- 需要完整的会话管理、通讯录、群组管理功能
+- 作为移动应用的核心功能模块
+
+**MainActivity 和底部导航实现要求**（🔴 强制要求）:
+
+如果项目中没有底部导航，**必须创建 MainActivity 作为主页面**，包含以下要求：
+
+1. **必须实现底部导航栏**：
+   - 默认包含两个 Tab：**消息**（ConversationsPage）和 **联系人**（ContactsPage）
+   - 使用 Compose Navigation 或 Scaffold 的 bottomBar
+   
+2. **Tab 点击必须能跳转到真实页面**：
+   - 点击"消息" Tab → 显示 `ConversationsPage`（会话列表）
+   - 点击"联系人" Tab → 显示 `ContactsPage`（联系人列表）
+   - 使用 Compose Navigation 或状态管理实现页面切换
+   
+3. **MainActivity 实现要求**：
+   - **直接参考官方源码**：`TUIKit_Android_Compose/chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt`
+   - **完整复制官方实现逻辑**：包括页面结构、回调处理、导航逻辑等
+   - **保持与官方示例一致**：确保功能完整性和最佳实践
+
+   **🔴 官方 MainActivity 参考要求**：
+   - **强制参考**：`TUIKit_Android_Compose/chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt`
+   - **页面回调必须完整实现**：
+     - `ConversationsPage` 的 `onConversationClick` 回调 → 跳转到 `ChatActivity`
+     - `ContactsPage` 的 `onGroupClick` 和 `onContactClick` 回调 → 跳转到 `ChatSettingActivity`
+   - **回调参数传递**：严格按照官方示例传递 `conversationID`、`contactID` 等参数
+   - **Intent 启动方式**：使用官方示例中的 `Intent` 和 `putExtra` 方式
+
+4. **登录成功后跳转到 MainActivity**：
+   ```kotlin
+   // LoginPage.kt
+   LoginStore.shared.login(...) { success ->
+       if (success) {
+           val intent = Intent(context, MainActivity::class.java)
+           context.startActivity(intent)
+           (context as Activity).finish()  // 关闭登录页
+       }
+   }
+   ```
+
+5. **禁止行为**：
+   - ❌ 登录后直接跳转到单个页面（如 ConversationsPage）而没有底部导航
+   - ❌ 创建空的 MainActivity 但没有实际的页面切换逻辑
+   - ❌ 底部导航只有一个 Tab（必须至少有"消息"和"联系人"）
+
+---
+
+### 2. 仅集成聊天页面 (chat-only)
+
+**目标**: 适用于客服、问诊、详情页私聊等纯对话场景
+
+**核心页面**: 
+- `ChatActivity` (聊天页面)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 客服咨询场景（用户点击咨询按钮进入聊天页面）
+- 医疗在线问诊（患者与医生一对一沟通）
+- 订单详情页私聊（买家与卖家沟通）
+- 社交应用中的私信功能
+
+**💡 登录成功后的页面跳转（chat-only 模式指引）**:
+
+**默认行为**：如果用户没有特别说明，登录成功后直接跳转到 `ChatActivity`，打开与 `administrator` 的单聊会话。
+
+**灵活调整**：如果用户有其他诉求（如特定时机打开聊天页、指定其他会话对象），需按用户引导确认跳转时机和目标会话。
+
+**默认实现示例**：
+
+```kotlin
+// ✅ 登录成功，直接进入聊天页面
+val intent = Intent(context, ChatActivity::class.java).apply {
+    putExtra("conversationID", "c2c_administrator")  // 默认与 administrator 单聊
+}
+context.startActivity(intent)
+(context as Activity).finish()  // 关闭登录页
+```
+
+**⚠️ 关键要点**：
+1. **使用 `Intent` 传递 conversationID**（避免硬编码）
+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. ✅ **遵循文档**：按照集成文档的规范正确集成所需页面
+
+---
+
+## 📦 核心版本要求
+
+| 工具/平台 | 最低版本要求 |
+|----------|-------------|
+| **Android Studio** | Ladybug \| 2024.2.1 及以上 |
+| **Android 系统** | >= 5.0 (API 21) |
+| **Gradle** | >= 8.9 |
+| **Android Gradle Plugin** | >= 8.6 |
+| **JDK** | >= 17 |
+| **Kotlin** | >= 1.9.0 |
+
+---
+
+## 📦 安装命令示例
+Agent 执行完成代码生成后，必须引导用户按顺序执行以下步骤：
+
+**⚠️ 重要：Android 项目配置规范**
+- Android 项目配置完成后，**必须执行 Gradle Sync**
+- 不需要手动执行命令行操作
+- IDE 会自动下载依赖并构建项目
+
+### 🔴 步骤 1: 环境检查与配置文件替换（集成前必须执行 - 最高优先级）
+
+**⚠️ 在执行任何集成操作前，Agent 必须首先执行环境检查和配置文件替换**：
+
+#### 1.1 强制性环境检查
+**Agent 必须首先验证以下环境要求**：
+- ✅ **Android Studio**: Ladybug | 2024.2.1 及以上版本
+- ✅ **Android 系统**: Android 5.0 (API 21) 及以上版本  
+- ✅ **Gradle**: 8.9 及以上版本
+- ✅ **Android Gradle Plugin**: 8.6 及以上版本
+- ✅ **JDK**: 17 及以上版本
+- ✅ **Kotlin**: 1.9.0 及以上版本
+
+**如果环境不满足要求，Agent 必须**：
+1. 明确告知用户当前环境的不足
+2. 提供详细的环境升级指导
+3. 暂停集成操作直到环境满足要求
+
+#### 1.2 配置文件完整替换（强制执行）
+**Agent 必须按照以下顺序执行配置文件替换**：
+
+1. **调用 MCP 工具获取最新集成文档**
+2. **完整替换以下配置文件**：
+   - `gradle/libs.versions.toml` - **必须从集成文档实时读取**
+   - `app/build.gradle.kts` - 使用文档提供的完整配置
+   - `AndroidManifest.xml` - 使用文档提供的配置
+   - `proguard-rules.pro` - 使用文档提供的配置
+   - `settings.gradle.kts` - 使用文档提供的配置
+
+3. **执行验证检查**：
+   - [ ] 是否调用了 MCP 工具获取最新文档？
+   - [ ] 是否完整复制了文档中的配置代码？
+   - [ ] 是否避免了使用记忆中的配置？
+   - [ ] 是否确保配置与文档示例完全一致？
+
+**⚠️ 只有完成环境检查和配置文件替换后，才能继续执行后续步骤**
+
+### 🔴 步骤 2: 依赖完整性检查（第二优先级）
+
+**在完成环境检查和配置文件替换后，Agent 必须执行以下检查**：
+
+1. **自动扫描生成的代码中的所有 import 语句**：
+   - 使用 `search_content` 工具搜索所有生成的 `.kt` 文件
+   - 提取所有 `import` 语句中的包名
+   
+2. **验证依赖配置完整性**：
+   - 检查 `build.gradle.kts` 或 `build.gradle` 中的 `dependencies` 块
+   - 验证所有代码中使用的库是否都已在依赖中声明
+   
+3. **必须检查的关键依赖**：
+   - **从集成文档中读取完整的依赖配置**
+   - **严格按照 gradle/libs.versions.toml 中的版本配置**
+   - **确保所有依赖与集成文档完全一致**
+
+4. **发现缺失依赖时的处理**：
+   - **参考集成文档中的完整配置**
+   - **按照集成文档补充缺失的依赖到 gradle/libs.versions.toml**
+   - **向用户说明**添加了哪些依赖以及原因
+   - **不要等待用户确认**，直接修复
+
+**示例检查流程**：
+- Agent 扫描生成代码中的所有 import 语句
+- 对比集成文档中的依赖配置
+- 确保项目配置与集成文档完全一致
+
+### 🔴 步骤 3: Gradle 同步与编译验证
+
+**Agent 配置文件替换完成后，必须引导用户执行 Gradle 同步**：
+
+**推荐执行方式**：
+- Agent 必须明确告知用户在 Android Studio 中点击 "File > Sync Project with Gradle Files"
+- 等待 Gradle 同步完成
+- 如果出现编译错误，立即告知 Agent 错误信息
+- Agent 会根据错误信息补充缺失的依赖或修复代码
+
+**常见编译错误及处理**：
+| 错误类型 | 错误信息示例 | Agent 处理方式 |
+|---------|------------|--------------|
+| 缺失依赖 | `Unresolved reference: Material3` | 检查 libs.versions.toml 配置 |
+| 缺失模块 | `Project 'atomicx' not found` | 检查 `settings.gradle.kts` 配置 |
+| 版本冲突 | `Duplicate class found` | 检查依赖版本并统一 |
+| Import 错误 | `Unresolved reference: LoginStore` | 检查 import 路径，参考官方示例 |
+
+**降级策略**：
+- 如果 IDE 同步失败，提示用户检查网络连接
+- 如果依赖下载失败，建议配置国内镜像
+- 如果构建错误，**立即读取错误日志**，分析缺失的依赖或 import 问题
+- **不要让用户自己修复**，Agent 应主动分析并修复
+
+---
+
+## 📱 真机调试引导
+
+### Android 真机调试步骤
+
+#### 1. 硬件准备
+- 使用 USB 数据线连接 Android 设备到电脑
+- 确保设备已开启开发者选项和 USB 调试模式
+
+#### 2. 开启开发者选项
+在 Android 设备上：
+- 进入 **设置** → **关于手机**
+- 连续点击 **版本号** 7 次，直到显示"您现在是开发者"
+- 返回设置主页，进入 **开发者选项**
+- 开启 **USB 调试**
+
+#### 3. 查看已连接设备
+```bash
+# 方式 1: 使用 adb 命令
+adb devices
+
+# 输出示例：
+# List of devices attached
+# XXXXXXXX	device
+
+# 方式 2: 在 Android Studio 中查看
+# 工具栏 → Device Manager → Physical
+```
+
+#### 4. 在 Android Studio 中运行
+- 点击工具栏的 **Run** 按钮（绿色三角形）
+- 在设备选择对话框中选择已连接的 Android 设备
+- 等待应用安装并启动
+
+---
+
+## 🚀 多设备同时调试
+
+### 同时连接多个设备
+```bash
+# 查看所有设备
+adb devices
+
+# 指定某个设备运行（在 Android Studio 中选择对应设备）
+# 示例：同时运行在不同的 Android 设备上
+```
+
+---
+
+## 📊 调试建议
+
+### 日志查看
+```bash
+# Android 日志
+adb logcat | grep "TUIKit"
+
+# 启动性能分析
+# 在 Android Studio 中使用 Profiler 工具
+```
+
+### 常见问题排查
+- **设备未识别**：检查 USB 驱动和调试模式
+- **应用安装失败**：检查设备存储空间和权限
+- **网络连接问题**：确保设备网络正常
+
+---
+
+## 🔄 完整自动化流程
+
+```mermaid
+graph TD
+    A[接收用户需求] --> B[检查 Android 环境配置]
+    B --> C[进入项目父目录并克隆 TUIKit_Android_Compose]
+    C --> D[按照集成文档配置 settings.gradle.kts]
+    D --> E[按照集成文档配置 app/build.gradle.kts]
+    E --> F[按照集成文档配置 AndroidManifest.xml]
+    F --> G[按照集成文档配置 libs.versions.toml]
+    G --> H[调用 get_usersig 工具获取鉴权信息]
+    H --> I[按照集成文档实现登录逻辑]
+    I --> J[按照集成文档实现核心页面]
+    J --> K[调用 record_result 记录集成结果]
+    K --> L[引导用户执行 Gradle Sync]
+    L --> M{Sync 成功?}
+    M -->|是| N[引导用户连接真机调试]
+    M -->|否| O[提供错误排查指引]
+    N --> P[引导用户点击 Run 启动项目]
+    O --> P
+    P --> Q[项目启动成功]
+```
+
+---
+
+## 📝 关键要点总结
+
+| 类别 | 要求 |
+|------|------|
+| **框架版本** | Android Studio >= Ladybug \| 2024.2.1、JDK >= 17、Kotlin >= 1.9.0 |
+| **接入方式** | 源码接入（从 GitHub 克隆并通过本地路径引用） |
+| **文档优先** | ⚠️ 严格遵循集成文档中的示例代码，不得擅自修改 |
+| **核心页面来源** | 🚨 **严禁自己编写核心页面代码**，必须从官方 demo 目录完整复制页面文件 |
+| **页面完整性验证** | ⚠️ 核心页面代码必须包含完整的 Activity/Composable、UI 组件树、业务逻辑 |
+| **静默集成** | 代码编写完成后引导用户执行 Gradle Sync 并启动项目 |
+| **凭证获取** | ⚠️ 必须使用 `get_usersig` 工具获取测试鉴权信息 |
+| **安全提示** | ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成 |
+| **结果记录** | ⚠️ 集成完成后必须调用 `record_result` 工具记录结果 |
+| **集成模式** | 支持 full-featured（全量）和 chat-only（仅聊天）两种模式 |
+| **chat-only 限制** | ⚠️ 默认排除 ConversationsPage、ContactsPage；用户主动要求时允许集成 |
+| **Import 约束** | ⚠️ 必须严格按照官方示例代码的包路径，禁止推测任何路径 |
+
+---
+
+## 🎯 Agent 执行检查清单
+
+在完成代码生成后，Agent 必须确认以下所有项目：
+
+### MCP 工具调用验证
+- [ ] ✅ **已调用 `get_native_chat_uikit_integration` 获取最新集成文档**
+- [ ] ✅ **已从集成文档中提取所有配置代码**
+- [ ] ✅ **已调用 `get_usersig` 获取测试鉴权信息**
+- [ ] ❌ **严禁使用记忆中的任何配置代码**
+
+### 配置文件完整性验证
+- [ ] ✅ **gradle/libs.versions.toml 完全来源于集成文档**
+- [ ] ✅ **app/build.gradle.kts 完全来源于集成文档**
+- [ ] ✅ **AndroidManifest.xml 完全来源于集成文档**
+- [ ] ✅ **proguard-rules.pro 完全来源于集成文档**
+- [ ] ✅ **settings.gradle.kts 完全来源于集成文档**
+
+### 代码实现验证
+- [ ] ✅ **所有 import 路径来源于官方示例代码**
+- [ ] ✅ **所有 API 调用方式与官方示例一致**
+- [ ] ✅ **所有类名、函数名与官方示例一致**
+- [ ] ❌ **严禁推测或简化任何实现**
+
+### 项目初始化
+- [ ] 已进入用户项目的父目录
+- [ ] 已克隆 TUIKit_Android_Compose 仓库到同级目录
+- [ ] 已按照集成文档配置 `settings.gradle.kts`
+- [ ] 已按照集成文档配置 `app/build.gradle.kts`
+
+### 代码生成
+- [ ] 🔴 **已调用 `get_usersig` 工具获取 SDKAppID、UserID、UserSig**
+- [ ] 🔴 **已参考官方 LoginPage 实现登录页面**（路径：`TUIKit_Android_Compose/chat/demo/app/src/main/java/io/trtc/tuikit/chat/login/LoginPage.kt`）
+- [ ] 🔴 **登录页面不包含 UserID、SDKAppID、UserSig 输入框**
+- [ ] 已按照集成文档实现登录逻辑，自动使用 `get_usersig` 返回的凭证
+- [ ] 🔴 **已从官方 demo 目录完整复制页面文件**
+- [ ] 🔴 **核心页面包含完整的 Activity/Composable、UI 组件树、业务逻辑**
+- [ ] 🔴 **严禁自己编写简化版实现，严禁跳过页面代码生成**
+- [ ] 🔴 **所有 import 使用正确的包路径，严格按照官方示例**
+- [ ] 已按照集成文档实现页面间的导航逻辑
+
+### 集成模式
+- [ ] 已根据用户需求选择正确的集成模式（full-featured 或 chat-only）
+- [ ] full-featured 模式：已集成 ConversationsPage、ChatActivity、ContactsPage 等页面
+- [ ] full-featured 模式：已实现 MainActivity 和底部导航栏
+- [ ] chat-only 模式：已集成核心页面（ChatActivity）
+- [ ] chat-only 模式：已根据用户需求判断是否需要集成扩展功能
+  - [ ] 如果用户未主动要求，已确认不包含 ConversationsPage、ContactsPage 等页面
+  - [ ] 如果用户主动要求（如"需要 ConversationsPage"），已额外集成用户明确要求的功能
+
+### 安全与提示
+- [ ] 🔴 **已告知用户**：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig
+- [ ] 已在代码注释中标注测试配置的位置
+
+### 最终交付验证
+- [ ] ✅ **生成的代码能够直接编译运行**
+- [ ] ✅ **无需用户手动修改任何配置**
+- [ ] ✅ **所有功能与官方 demo 效果一致**
+
+### 最终检查
+- [ ] 🔴 **已调用 `record_result` 工具记录集成结果**
+- [ ] 🔴 **已引导用户执行 Gradle Sync**
+- [ ] 已引导用户连接设备或启动模拟器
+- [ ] 已引导用户点击 Run 按钮运行项目
+- [ ] 项目可以正常运行，无报错
+
+---
+
+## 🔗 必须使用的工具
+
+**⚠️ MCP 工具调用参数注意事项**：
+调用 MCP 工具时必须使用正确的参数名，避免参数错误导致调用失败：
+- ✅ **正确**: `get_native_chat_uikit_integration` 使用参数 `"framework"`
+- ❌ **错误**: 使用参数 `"platform"` 会导致调用失败
+- 在调用任何 MCP 工具前，Agent 必须先调用 `mcp_get_tool_description` 确认正确的参数名
+
+### `get_usersig` - 获取测试鉴权信息
+**用途**：获取腾讯云 IM 测试用的鉴权信息
+- `SDKAppID`: 应用标识
+- `UserID`: 用户 ID
+- `UserSig`: 用户签名
+
+**使用约束**：
+- ✅ 必须使用 `get_usersig` 工具获取测试鉴权
+- ❌ 禁止让用户手动输入或从控制台复制
+- ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成
+
+### `record_result` - 记录集成结果
+**用途**：记录集成过程和结果，用于统计和分析
+
+**调用时机**：在完成所有集成步骤并成功引导用户运行项目后调用
+
+---
+
+## 📚 相关资源链接
+
+- **TUIKit Android Compose GitHub 仓库**：https://github.com/Tencent-RTC/TUIKit_Android_Compose
+- **腾讯云即时通信 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
+- **Jetpack Compose 官方文档**：https://developer.android.com/jetpack/compose
+- **Android 官方文档**：https://developer.android.com/
+
+---
+
+**适用平台**: Android  
+**TUIKit 版本**: TUIKit Compose (基于 AtomicXCore)  
+**最低要求**: Android Studio >= Ladybug | 2024.2.1、JDK >= 17、Kotlin >= 1.9