@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

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

@@ -1,322 +0,0 @@
-# Native Live AtomicXCore 代码生成工作流指令 (Android)
-
-## 🚨 核心原则（最高优先级）
-
-**Agent 必须确保生成的代码可以成功编译运行，严禁将无法编译的代码交付给用户！**
-
-### ⚠️ 强制编译验证
-**每次生成/修改代码后，必须执行完整 Gradle 编译**：
-```bash
-./gradlew assembleDebug --stacktrace
-```
-
-**禁止行为**：
-- ❌ 禁止只用 `read_lints` 检查就认为代码正确
-- ❌ 禁止用 `grep` 过滤编译输出（可能遗漏关键错误）
-
-**编译错误分类与处理**：
-| 错误类型 | 示例 | 处理方式 |
-|---------|------|---------|
-| 依赖解析失败 | `Could not find xxx` | 检查仓库配置（JitPack/Maven） |
-| 依赖缺失 | `Unresolved reference` | 添加缺失依赖到 build.gradle |
-| Import 缺失 | `Unresolved reference: xxx` | 添加 import 语句 |
-| 资源缺失 | `cannot find symbol R.xxx` | 创建对应资源文件 |
-| Manifest 缺失 | `Activity not found` | 注册到 AndroidManifest.xml |
-
-**验证流程**：
-1. 执行 `./gradlew assembleDebug`（完整输出，不过滤）
-2. 如果失败 → 分析完整错误 → 修复 → 重新编译
-3. 循环直到 `BUILD SUCCESSFUL`
-```
-
-**关键点**：强调 `read_lints ≠ 完整编译验证`，Gradle 依赖/配置错误只有完整编译才能发现。
-```
-
-**处理流程**：
-1.  **编译成功 (BUILD SUCCESSFUL)** → 交付代码。
-2.  **编译失败** → 分析错误 → **自动修复** → 重新编译。
-    *   ✅ **可自动修复**：依赖缺失、Import 缺失、AndroidManifest 权限缺失。
-    *   ❌ **不可修复**：SDK 内部错误、网络环境问题（需提示用户）。
-
----
-
-## 📋 指令目的与架构
-
-为 Agent 提供实现 Native (Android) Live AtomicXCore 核心功能的**代码生成蓝图**。
-
-**核心架构**：
-*   **容器**：`LiveCoreView` (视图层)
-*   **状态**：`Store` (数据驱动)
-*   **事件**：`Listener` (回调处理)
-
-**功能依赖逻辑（重要）**：
-1.  **基础先行**：必须先使用本工具（`get_native_live_uikit_integration`）完成基础直播（开播/观看/列表）。
-2.  **互动叠加**：如果用户需求包含"连麦"、"PK"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_native_live_uikit_interaction`）。
-3.  **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
-
----
-
-## ⚙️ 自动化工作流步骤
-
-### 步骤 0: 前置准备（自动化）
-1.  **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
-    *   主播: `anchor001`, `anchor002`, `anchor003`
-    *   观众: `user001`, `user002`, `user003`
-2.  **环境检查**：检查 `build.gradle`，若缺失以下依赖则自动添加：
-    ```gradle
-    api 'io.trtc.uikit:atomicx-core:latest.release'
-    api "io.trtc.uikit:rtc_room_engine:latest.release"
-    api "com.tencent.liteav:LiteAVSDK_Professional:latest.release"
-    api "com.tencent.imsdk:imsdk-plus:latest.release"
-    ```
-3.  **权限注入**：在 `AndroidManifest.xml` 中添加摄像头、麦克风、网络权限。
-
-### 步骤 1: 获取与生成
-**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
-*   **仅主播**：生成 `AnchorActivity`
-*   **仅观众**：生成 `AudienceActivity`
-*   **主播+观众**：生成 `MainActivity` (入口选择) + `AnchorActivity` + `AudienceActivity`
-
-### 步骤 2: 验证与交付
-执行 `./gradlew assembleDebug`，确保无误后交付。
-
----
-
-## 🚫 代码生成约束（严格遵守）
-
-### 1. 通用代码约束
-*   **严禁修改 Import**：文档中的 import 路径经过验证，绝对不可修改。
-*   **严禁臆造 API**：如果文档没写，绝对不能自己发明方法名或参数名。
-*   **必须查阅 API 文档**：涉及数据模型字段（如 `LiveInfo`），必须查看文档确认字段名（例如确认是 `liveOwner.userName` 而不是 `name`）。
-
-### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
-**核心原因**：SDK 的 `Store.create(liveId)` 通常返回单例或复用实例。使用匿名内部类会导致监听器实例重复注册或被覆盖，引发"主播端不显示"或"仅首次生效"的 Bug。
-
-*   **唯一实例原则**：所有 Listener（如 `GiftListener`, `CoGuestListener`, `BarrageListener`）**必须声明为 Activity/Fragment 的成员变量**。
-*   **严禁匿名内部类**：禁止直接在 `addXXXListener(object : ...)` 中写匿名对象。
-*   **成对原则**：在 `onCreate/onStart` 调用 `addListener`，则**必须**在 `onDestroy/onStop` 调用 `removeListener`，防止内存泄漏和监听失效。
-
-### 3. ⏱️ 超时时间限制（关键技术点）
-**必须严格遵守以下参数限制，优先使用文档示例中的值：**
-
-#### A. 观众连麦 (`CoGuestStore`)
-*   **规则**：
-    *   可选参数，不填则不检查超时。
-    *   若填写，范围必须在 **5 - 1800 秒**之间。
-*   **正确示例**：
-    ```kotlin
-    // ✅ 推荐：跟随文档示例（如 30秒）
-    applyForSeat(seatIndex = -1, timeout = 30, ...)
-    // ✅ 合法：不检查超时
-    applyForSeat(seatIndex = -1, timeout = 0, ...)
-    ```
-*   **错误示例**：❌ `timeout = 3` (太短)，❌ `timeout = 2000` (太长)。
-
-#### B. 主播连线/PK (`CoHostStore`)
-*   **规则**：
-    *   **最大值 30 秒**（后台硬限制）。
-*   **正确示例**：
-    ```kotlin
-    // ✅ 推荐：使用最大值
-    requestHostConnection(..., timeout = 30, ...)
-    ```
-*   **错误示例**：❌ `timeout = 60` (会导致请求失败)。
-
-### 3. 🎨 扩展功能约束（美颜/音效/UI）
-
-#### A. 音效 (Audio Effect)
-*   **变声枚举 (`AudioChangerType`)**：
-    *   ✅ **允许**：`CHILD, LITTLE_GIRL, MAN, ETHEREAL` 等标准枚举。
-    *   ❌ **禁止**：`UNCLE, LOLI, GIRL, BOY` (这些是旧版或错误的枚举)。
-*   **混响枚举 (`AudioReverbType`)**：
-    *   ✅ **允许**：`KTV, SMALL_ROOM, METALLIC` 等。
-    *   ❌ **禁止**：`ROOM, HALL, LOW`。
-
-#### B. 美颜 (Beauty)
-*   **参数范围**：**0.0 - 9.0** (Float)。
-    *   ❌ 不是 0-1 (Float)，也不是 0-100 (Int)。
-*   **UI 映射公式**：`progress / 100.0f * 9.0f`。
-
-#### C. 弹幕、礼物与布局 (Barrage, Gift & UI)
-*   **层级要求**：弹幕列表和全屏礼物动画必须使用 `FrameLayout` 或 `RelativeLayout` 覆盖在视频层**之上**。
-*   **禁止分割**：严禁将屏幕分割为"上视频、下弹幕"，必须是叠加模式。
-*   **键盘适配**：必须在 Manifest 中设置 `android:windowSoftInputMode="adjustNothing"` 或 `adjustPan`，**防止键盘弹起时视频画面变形或上移**。
-
-##### 弹幕输入框 (Barrage Input)
-*   **位置**：固定在屏幕底部左侧，与功能按钮（礼物、连麦等）同行。
-*   **样式**：半透明圆角背景 + 占位文字「说点什么...」。
-*   **键盘适配**：
-    *   键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
-    *   视频画面 `LiveCoreView` 布局固定为 `match_parent`，禁止变形或上移。
-    *   **必须**在 Manifest 中设置 `android:windowSoftInputMode="adjustNothing"`。
-
-##### 弹幕显示流 (Barrage Display Flow)
-```
-发送弹幕:
-用户输入 → 点击发送/回车 → BarrageStore.sendTextMessage(text) → 本地立即插入弹幕列表
-
-接收弹幕:
-订阅 BarrageStore.barrageState.barrageList → 收到新消息 → 插入弹幕列表 → 滚动到底部
-```
-*   **数据源**：订阅 `BarrageStore.create(liveId).barrageState.barrageList`。
-*   **本地回显**：发送成功后**立即**在本地弹幕列表插入，无需等待服务器回调。
-*   **滚动行为**：新消息到达时自动滚动到底部（`recyclerView.scrollToPosition(adapter.itemCount - 1)`）。
-*   **消息格式**：`[昵称]: [消息内容]`，昵称使用主题色，内容使用白色。
-
-*   **礼物弹幕 (Gift Barrage)**：**如果用户需要集成礼物弹幕**，`onReceiveGift` 事件触发时，**主播端和观众端**都必须在弹幕列表（Message List）中插入礼物消息。严禁仅在观众端显示礼物文本。
-
-##### 全屏礼物动画 (Full-screen Gift Animation)
-**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
-
-*   **层级**：全屏礼物动画视图必须覆盖在 `LiveCoreView` **之上**，使用独立的 `FrameLayout` 容器。
-*   **布局**：约束为 `match_parent`，覆盖整个屏幕。
-*   **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**主播端和观众端**都必须播放全屏动画。严禁只在观众端播放。
-
-### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
-
-**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
-
-### 1. 全局视觉风格 (Global Aesthetics)
-*   **沉浸式暗黑**：直播页背景必须为 `Color.BLACK`，视频层 (`LiveCoreView`) 必须**全屏铺满** (`match_parent`) 且位于最底层。
-*   **安全区域**：所有悬浮 UI 必须考虑状态栏和导航栏，严禁被刘海屏或底部导航条遮挡。
-*   **文字可读性**：视频之上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`setShadowLayer`)。
-*   **错误提示**：统一使用 **Toast**，禁止使用模态 AlertDialog 打断用户。
-
-### 2. 通用组件规范 (Component Standards)
-*   **顶部胶囊 (Glass Capsule)**：
-    *   **样式**：**半透明黑色背景** + **全圆角** (`cornerRadius = height / 2`)。
-    *   **应用**：仅用于顶部左侧展示"主播头像+ID+热度"。
-*   **通用按钮 (Flat Buttons)**：
-    *   **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
-    *   **关闭按钮**：特例，使用圆形半透明背景图标。
-*   **弹出面板 (Floating Panels)**：
-    *   **样式**：仅顶部大圆角 (`topLeftRadius, topRightRadius`)。
-    *   **禁忌**：底部禁止出现非透明的实色背景块，必须保持悬浮感。
-
-### 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. 主播开播 (`host_streaming`)
-*   **核心**：`LiveCoreView(viewType = PUSH_VIEW)`
-*   **流程**：`LiveListStore.createLive()`
-*   **销毁**：`onDestroy` 中必须调用 `endLive()`。
-
-### 2. 观众观看 (`audience_streaming`)
-*   **核心**：`LiveCoreView(viewType = PLAY_VIEW)`
-*   **流程**：`LiveListStore.joinLive()`
-*   **销毁**：`onDestroy` 中必须调用 `leaveLive()`。
-
-### 3. 直播列表 (`live_list`)
-*   **核心**：`LiveListStore.fetchLiveList()` + `RecyclerView`
-*   **数据**：订阅 `liveState.liveList`。
-*   **跳转**：点击列表项跳转观众页，传递 `liveID`。
-
-### 4. 连麦与连线交互规范 (`co_guest` & `co_host`)
-
-#### A. 观众连麦（主播被动接收）
-*   **主播端 UI**：❌ **严禁**在底部工具栏或任何位置显示「连麦申请」列表按钮。
-*   **交互逻辑**：当收到观众连麦申请回调时，直接在屏幕中心弹出对话框（`AlertDialog`）：
-    *   **标题**：连麦申请
-    *   **内容**：收到观众 [昵称] 的连麦申请，是否接受？
-    *   **操作**：[拒绝] [接受]
-
-#### B. 主播连线面板（点击底部【连线】按钮弹出）
-*   **展现形式**：使用底部浮层面板（`BottomSheetDialog` 或自定义 `View` 动画升起），禁止使用 `AlertDialog`。
-*   **UI 布局（严格对照图示）**：
-```
-┌─────────────────────────────────────┐
-│                                     │
-│  发起连线              [🚪 结束连线]  │  ← 红色文字
-│                                     │
-│  连线中 (2 人)                       │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]        PK中... ││  ← 已连线用户
-│  │ [👤] 菲林娜 [💎32]        PK中... ││
-│  └─────────────────────────────────┘│
-├─────────────────────────────────────┤
-│  其他连线用户                        │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]      [取消邀请] ││  ← 灰黑背景按钮
-│  │ [👤] 菲林娜 [💎32]      [邀请连线] ││  ← 蓝色背景按钮
-│  │ [👤] 铁柱   [💗99]      [邀请连线] ││
-│  └─────────────────────────────────┘│
-└─────────────────────────────────────┘
-```
-
-#### C. PK 按钮交互约束
-*   **前置检查**：点击底部【PK】按钮时，必须检查当前连线状态（`CoHostStore.connectedUsers.isEmpty()`）。
-*   **状态处理**：
-    *   **未连线**：❌ 禁止跳转，使用 Toast 提示：`"请先发起连线"`。
-    *   **已连线**：✅ 弹出 PK 邀请面板。
-
----
-
-## 📋 Agent 最终检查清单
-
-- [ ] **编译验证**：已执行 `./gradlew assembleDebug` 且结果为 SUCCESS。
-- [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `LiveInfo` 字段名。
-- [ ] **超时合规**：连麦超时 5-1800s，连线超时 ≤30s。
-- [ ] **扩展合规**：音效枚举正确，美颜范围 0-9，弹幕布局覆盖且键盘适配。
-- [ ] **礼物合规**：主播和观众端均实现了全屏礼物动画显示。
-- [ ] **凭证注入**：已自动注入测试 UserSig。
-- [ ] **依赖完整**：已检查并修复 `build.gradle` 和权限。
-
----
-
-## 🚨 安全提醒（代码注释模板）
-
-```kotlin
-/**
- * ⚠️ 测试凭证说明
- * - 当前 userSig 由开发工具自动生成，有效期 7 天
- * - ❌ 生产环境严禁在客户端生成 userSig
- * - ✅ 正式上线前必须在后端服务生成
- * - 参考: https://cloud.tencent.com/document/product/647/17275
- */
-```