@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

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

@@ -1,352 +0,0 @@
-# Native Live AtomicXCore 代码生成工作流指令 (iOS)
-
-## 🚨 核心原则（最高优先级）
-
-**Agent 必须确保生成的代码可以成功编译运行，严禁将无法编译的代码交付给用户！**
-
-### ⚠️ 强制编译验证（必须执行，不可省略）
-
-**🚫 严禁行为**：
-- ❌ 只用 `read_lints` 检查就认为代码正确
-- ❌ 用 `grep` 过滤编译输出（会导致命令被跳过）
-- ❌ 跳过编译验证直接交付代码
-
-**✅ 唯一正确的验证方式**：
-
-```bash
-# 步骤 1: 安装依赖（如需要）
-cd <项目目录> && pod install
-
-# 步骤 2: 编译验证（使用 tail 限制输出）
-cd <项目目录> && xcodebuild build \
-  -scheme <SchemeName> \
-  -workspace <WorkspaceName>.xcworkspace \
-  -destination 'generic/platform=iOS' \
-  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
-
-
-**判断标准**：
-- ✅ 输出包含 `BUILD SUCCEEDED` → 编译通过，可交付
-- ❌ 输出包含 `BUILD FAILED` 或 `error:` → 必须修复后重新编译
-
-**常见错误与修复**：
-| 错误关键字 | 原因 | 修复方式 |
-|-----------|------|---------|
-| `No such module 'xxx'` | Pod 依赖缺失 | 添加到 Podfile 后执行 `pod install` |
-| `Cannot find 'xxx' in scope` | Import 缺失 | 添加 `import xxx` |
-| `Use of unresolved identifier` | API 名称错误 | 查阅文档确认正确 API |
-| `NSCameraUsageDescription` | Info.plist 权限缺失 | 添加权限描述 |
-
-**验证循环（必须遵守）**：
-```
-执行编译 → 失败 → 分析错误 → 修复代码 → 重新执行编译 → ... → BUILD SUCCEEDED → 交付
-```
-
----
-
-## 📋 指令目的与架构
-
-为 Agent 提供实现 Native (iOS) Live AtomicXCore 核心功能的**代码生成蓝图**。
-
-**核心架构**：
-*   **容器**：`LiveCoreView` (视图层)
-*   **状态**：`Store` (数据驱动)
-*   **事件**：`Publisher` (Combine 订阅)
-
-**功能依赖逻辑（重要）**：
-1.  **基础先行**：必须先使用本工具（`get_native_live_uikit_integration`）完成基础直播（开播/观看/列表）。
-2.  **互动叠加**：如果用户需求包含"连麦"、"PK"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_native_live_uikit_interaction`）。
-3.  **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
-
----
-
-## ⚙️ 自动化工作流步骤（必须创建为 TODO 任务）
-
-**🚨 Agent 必须将以下步骤创建为 TODO 任务列表，逐一完成并打勾：**
-
-### 步骤 1: 前置准备
-1.  **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
-    *   主播: `anchor001`, `anchor002`, `anchor003`
-    *   观众: `user001`, `user002`, `user003`
-2.  **环境检查**：检查 `Podfile`，若缺失以下依赖则自动添加：
-    ```ruby
-    pod 'AtomicXCore'
-    ```
-3.  **权限注入**：在 `Info.plist` 中添加摄像头、麦克风权限描述：
-    ```xml
-    <key>NSCameraUsageDescription</key>
-    <string>需要访问您的相机权限，开启后录制的视频才会有画面</string>
-    <key>NSMicrophoneUsageDescription</key>
-    <string>需要访问您的麦克风权限，开启后录制的视频才会有声音</string>
-    ```
-
-### 步骤 2: 代码生成
-**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
-*   **仅主播**：生成 `AnchorViewController`
-*   **仅观众**：生成 `AudienceViewController`
-*   **主播+观众**：生成 `MainViewController` (入口选择) + `AnchorViewController` + `AudienceViewController`
-
-### 步骤 3: 🚨 编译验证（强制执行，不可跳过）
-**此步骤必须作为独立 TODO 任务执行，不能省略或合并！**
-
-**执行命令**：
-```bash
-cd <项目目录>/ios && pod install && \
-xcodebuild build -scheme <SchemeName> -workspace <WorkspaceName>.xcworkspace \
-  -destination 'platform=iOS Simulator,name=iPhone 16' \
-  CODE_SIGNING_ALLOWED=NO 2>&1 | tail -150
-```
-
-**判断与处理**：
-*   输出包含 **BUILD SUCCEEDED** → 进入步骤 4
-*   输出包含 **BUILD FAILED** 或 **error:** → 分析错误 → 修复代码 → **重新执行本命令**，循环直到成功
-
-### 步骤 4: 交付结果
-确认编译通过后，向用户交付代码。
-
----
-
-## 🚫 代码生成约束（严格遵守）
-
-### 1. 通用代码约束
-*   **严禁修改 Import**：文档中的 import 路径经过验证，绝对不可修改。
-*   **严禁臆造 API**：如果文档没写，绝对不能自己发明方法名或参数名。
-*   **必须查阅 API 文档**：涉及数据模型字段（如 `LiveInfo`），必须查看文档确认字段名（例如确认是 `liveOwner.userName` 而不是 `name`）。
-
-### 2. 🧩 Store 与 Publisher 管理约束（生命周期安全）
-**核心原因**：SDK 使用 Combine 的 `Publisher` 进行状态订阅。不正确的生命周期管理会导致监听失效或内存泄漏。
-
-*   **订阅管理原则**：所有 `AnyCancellable` **必须声明为 ViewController 的成员变量** `cancellableSet`。
-*   **严禁忽略返回值**：禁止不存储 `.sink {}` 返回的 `AnyCancellable`。
-*   **成对原则**：在 `viewDidLoad` 中设置订阅，订阅会随 `cancellableSet` 在 `deinit` 时自动释放。
-
-### 3. ⏱️ 超时时间限制（关键技术点）
-**必须严格遵守以下参数限制，优先使用文档示例中的值：**
-
-#### A. 观众连麦 (`CoGuestStore`)
-*   **规则**：
-    *   可选参数，不填则不检查超时。
-    *   若填写，范围必须在 **5 - 1800 秒**之间。
-*   **正确示例**：
-    ```swift
-    // ✅ 推荐：跟随文档示例（如 30秒）
-    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 30) { ... }
-    // ✅ 合法：不检查超时
-    CoGuestStore.shared.applyForSeat(seatIndex: -1, timeout: 0) { ... }
-    ```
-*   **错误示例**：❌ `timeout: 3` (太短)，❌ `timeout: 2000` (太长)。
-
-#### B. 主播连线/PK (`CoHostStore`)
-*   **规则**：
-    *   **最大值 30 秒**（后台硬限制）。
-*   **正确示例**：
-    ```swift
-    // ✅ 推荐：使用最大值
-    CoHostStore.shared.requestHostConnection(..., timeout: 30) { ... }
-    ```
-*   **错误示例**：❌ `timeout: 60` (会导致请求失败)。
-
-### 4. 🎨 扩展功能约束（美颜/音效/UI）
-
-#### A. 音效 (Audio Effect)
-*   **变声枚举 (`AudioChangerType`)**：
-    *   ✅ **允许**：`.child, .littleGirl, .man, .ethereal` 等标准枚举。
-    *   ❌ **禁止**：`.uncle, .loli, .girl, .boy` (这些是旧版或错误的枚举)。
-*   **混响枚举 (`AudioReverbType`)**：
-    *   ✅ **允许**：`.ktv, .smallRoom, .metallic` 等。
-    *   ❌ **禁止**：`.room, .hall, .low`。
-
-#### B. 美颜 (Beauty)
-*   **参数范围**：**0.0 - 9.0** (Float)。
-    *   ❌ 不是 0-1 (Float)，也不是 0-100 (Int)。
-*   **UI 映射公式**：`sliderValue / 100.0 * 9.0`。
-
-#### C. 弹幕、礼物与布局 (Barrage, Gift & UI)
-*   **层级要求**：弹幕列表和全屏礼物动画必须使用 `UIView` 覆盖在视频层 `LiveCoreView` **之上**。
-*   **禁止分割**：严禁将屏幕分割为"上视频、下弹幕"，必须是叠加模式。
-
-##### 弹幕输入框 (Barrage Input)
-*   **位置**：固定在屏幕底部左侧，与功能按钮（礼物、连麦等）同行。
-*   **样式**：半透明圆角背景 + 占位文字「说点什么...」。
-*   **键盘适配**：
-    *   键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
-    *   视频画面 `LiveCoreView` 约束固定为 `edges.equalToSuperview()`，禁止变形或上移。
-    *   **严禁**使用 `UIScrollView.contentInsetAdjustmentBehavior` 或自动调整约束。
-
-##### 弹幕显示流 (Barrage Display Flow)
-```
-发送弹幕:
-用户输入 → 点击发送/回车 → BarrageStore.sendTextMessage(text) → 本地立即插入弹幕列表
-
-接收弹幕:
-订阅 BarrageStore.barrageState.$barrageList → 收到新消息 → 插入弹幕列表 → 滚动到底部
-```
-*   **数据源**：订阅 `BarrageStore.shared.barrageState.$barrageList`。
-*   **本地回显**：发送成功后**立即**在本地弹幕列表插入，无需等待服务器回调。
-*   **滚动行为**：新消息到达时自动滚动到底部（`scrollToRow(at: lastIndex, animated: true)`）。
-*   **消息格式**：`[昵称]: [消息内容]`，昵称使用主题色，内容使用白色。
-
-*   **礼物弹幕 (Gift Barrage)**：**如果用户需要集成礼物弹幕**，`onReceiveGift` 事件触发时，**主播端和观众端**都必须在弹幕列表（Message List）中插入礼物消息。严禁仅在观众端显示礼物文本。
-
-##### 全屏礼物动画 (Full-screen Gift Animation)
-**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
-
-*   **层级**：全屏礼物动画视图必须覆盖在 `LiveCoreView` **之上**，使用独立的 `UIView` 容器。
-*   **布局**：约束为 `edges.equalToSuperview()`，覆盖整个屏幕。
-*   **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**主播端和观众端**都必须播放全屏动画。严禁只在观众端播放。
-
-### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
-
-**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
-
-### 1. 全局视觉风格 (Global Aesthetics)
-*   **沉浸式暗黑**：直播页背景必须为 `.black`，视频层 (`LiveCoreView`) 必须**全屏铺满** (`edges.equalToSuperview()`) 且位于最底层。
-*   **安全区域**：所有悬浮 UI 必须约束在 `safeAreaLayoutGuide` 内部，严禁被刘海屏或底部 Home 条遮挡。
-*   **文字可读性**：视频之上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`shadowColor = .black, offset = 0x1`)。
-*   **错误提示**：统一使用 **Toast**，禁止使用模态 Alert 打断用户。
-
-### 2. 通用组件规范 (Component Standards)
-*   **顶部胶囊 (Glass Capsule)**：
-    *   **样式**：**磨砂玻璃背景** (`UIBlurEffect.dark`) + **全圆角**。
-    *   **应用**：仅用于顶部左侧展示“主播头像+ID+热度”。
-*   **通用按钮 (Flat Buttons)**：
-    *   **样式**：**“文字 + 圆角矩形背景”**。视觉风格扁平简约，背景色为半透明黑或主题色。
-    *   **关闭按钮**：特例，使用圆形磨砂玻璃图标。
-*   **弹出面板 (Floating Panels)**：
-    *   **样式**：仅顶部大圆角 (`maskedCorners = [.layerMinXMinYCorner, .layerMaxXMinYCorner]`)。
-    *   **禁忌**：底部禁止出现非透明的实色背景块，必须保持悬浮感。
-
-### 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: .pushView)`
-*   **流程**：`LiveListStore.shared.createLive()`
-*   **销毁**：`deinit` 或退出页面时必须调用 `endLive()`。
-
-### 2. 观众观看 (`audience_streaming`)
-*   **核心**：`LiveCoreView(viewType: .playView)`
-*   **流程**：`LiveListStore.shared.joinLive()`
-*   **销毁**：`deinit` 或退出页面时必须调用 `leaveLive()`。
-
-### 3. 直播列表 (`live_list`)
-*   **核心**：`LiveListStore.shared.fetchLiveList()` + `UITableView/UICollectionView`
-*   **数据**：订阅 `liveState.liveList`。
-*   **跳转**：点击列表项跳转观众页，传递 `liveID`。
-
-### 4. 连麦与连线交互规范 (`co_guest` & `co_host`)
-
-#### A. 观众连麦（主播被动接收）
-*   **主播端 UI**：❌ **严禁**在底部工具栏或任何位置显示「连麦申请」列表按钮。
-*   **交互逻辑**：当收到观众连麦申请回调时，直接在屏幕中心弹出对话框（`UIAlertController`）：
-    *   **标题**：连麦申请
-    *   **内容**：收到观众 [昵称] 的连麦申请，是否接受？
-    *   **操作**：[拒绝] [接受]
-
-#### B. 主播连线面板（点击底部【连线】按钮弹出）
-*   **展现形式**：使用底部浮层面板（`UIView` 动画升起），禁止使用 `UIAlertController`。
-*   **UI 布局（严格对照图示）**：
-```
-┌─────────────────────────────────────┐
-│                                     │
-│  发起连线              [🚪 结束连线]  │  ← 红色文字
-│                                     │
-│  连线中 (2 人)                       │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]        PK中... ││  ← 已连线用户
-│  │ [👤] 菲林娜 [💎32]        PK中... ││
-│  └─────────────────────────────────┘│
-├─────────────────────────────────────┤
-│  其他连线用户                        │
-│  ┌─────────────────────────────────┐│
-│  │ [👤] 李子明 [💎20]      [取消邀请] ││  ← 灰黑背景按钮
-│  │ [👤] 菲林娜 [💎32]      [邀请连线] ││  ← 蓝色背景按钮
-│  │ [👤] 铁柱   [💗99]      [邀请连线] ││
-│  └─────────────────────────────────┘│
-└─────────────────────────────────────┘
-```
-
-#### C. PK 按钮交互约束
-*   **前置检查**：点击底部【PK】按钮时，必须检查当前连线状态（`CoHostStore.shared.connectedUsers.isEmpty`）。
-*   **状态处理**：
-    *   **未连线**：❌ 禁止跳转，使用 Toast 提示：`"请先发起连线"`。
-    *   **已连线**：✅ 弹出 PK 邀请面板。
-
----
-
-## 📋 Agent 最终检查清单
-
-### 🚨 必做项（缺一不可）
-- [ ] **🔴 编译验证**：已执行以下命令且输出包含 **BUILD SUCCEEDED**（此项必须在 TODO 任务中明确列出）
-  ```bash
-  xcodebuild build -scheme <项目名> -workspace <项目名>.xcworkspace -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "(error:|warning:.*\.swift|BUILD SUCCEEDED|BUILD FAILED)" | head -30
-  ```
-- [ ] **凭证注入**：已调用 `get_usersig` 生成测试凭证
-- [ ] **依赖完整**：已检查 `Podfile` 和 Info.plist 权限
-```
-
-### 代码质量检查
-- [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `LiveInfo` 字段名。
-- [ ] **超时合规**：连麦超时 5-1800s，连线超时 ≤30s。
-- [ ] **扩展合规**：音效枚举正确，美颜范围 0-9，弹幕布局覆盖且键盘适配。
-- [ ] **礼物合规**：主播和观众端均实现了全屏礼物动画显示。
-
----
-
-## 🚨 安全提醒（代码注释模板）
-
-```swift
-/**
- * ⚠️ 测试凭证说明
- * - 当前 userSig 由开发工具自动生成，有效期 7 天
- * - ❌ 生产环境严禁在客户端生成 userSig
- * - ✅ 正式上线前必须在后端服务生成
- * - 参考: https://cloud.tencent.com/document/product/647/17275
- */
-```