@tencentcloud/sdk-mcp 1.3.7 → 1.3.9

package/resource/doc/livekit/voice/uni-app/workflow.md

@@ -0,0 +1,369 @@
+# Native 语聊房 AtomicXCore 代码生成工作流指令 (uni-app)
+
+## 🚨 核心原则（最高优先级）
+
+**Agent 必须确保生成的代码可以成功编译运行，严禁将无法构建的代码交付给用户！**
+
+### ⚠️ 强制编译验证
+
+**每次生成/修改代码后，必须执行完整构建验证**：
+
+```bash
+# H5 平台验证
+npm run dev:h5
+# 或 APP 平台验证
+npm run build:app
+```
+
+**禁止行为**：
+
+* ❌ 禁止只用 IDE 代码检查就认为代码正确
+* ❌ 禁止忽略 `package.json` 版本冲突
+
+**编译错误分类与处理**：
+| 错误类型 | 示例 | 处理方式 |
+|---------|------|---------|
+| 依赖解析失败 | `Cannot find module 'xxx'` | 检查 `package.json` 并执行 `npm install` |
+| 依赖缺失 | `Module not found` | 添加缺失库到 `dependencies` |
+| Import 缺失 | `xxx is not defined` | 添加 import 语句 |
+| 组件未注册 | `Unknown component` | 在 `pages.json` 注册或使用 `easycom` |
+| 权限缺失 | 麦克风访问失败 | 检查 `manifest.json` 权限配置 |
+
+**验证流程**：
+
+1. 执行 `npm run dev:h5` 或 `npm run build:app`。
+2. 如果失败 → 分析完整错误堆栈 → 修复 → 重新构建。
+3. 循环直到构建成功。
+
+**处理流程**：
+
+1. **构建成功** → 交付代码。
+2. **构建失败** → 分析错误 → **自动修复** → 重新构建。
+* ✅ **可自动修复**：依赖缺失、Import 缺失、权限配置缺失。
+* ❌ **不可修复**：SDK 内部错误、uni-app 环境配置问题（需提示用户）。
+
+---
+
+## 📋 指令目的与架构
+
+为 Agent 提供实现 uni-app 语聊房 AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+
+* **麦位管理**：`LiveSeatStore` (麦位数据驱动)
+* **状态**：`LiveSeatState` / `SeatInfo` / `SeatUserInfo`
+* **事件**：`Listener` (回调处理)
+
+**语聊房 vs 视频直播的核心差异**：
+| 特性 | 视频直播 | 语聊房 |
+|------|---------|-------|
+| 核心组件 | `LiveCoreView` | `LiveSeatStore` |
+| 媒体类型 | 音视频流 | 纯音频（麦位） |
+| 画面 | 视频画面 | 麦位头像 + 音浪动画 |
+| 核心概念 | 推流/拉流 | 麦位（seatList） |
+
+**功能依赖逻辑（重要）**：
+
+1. **基础先行**：必须先使用本工具（`get_uniapp_voice_uikit_integration`）完成基础语聊房（房主开播/观众进房/房间列表）。
+2. **互动叠加**：如果用户需求包含"上麦"、"连线"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_uniapp_voice_uikit_interaction`）。
+3. **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤
+
+### 步骤 0: 前置准备（自动化）
+
+1. **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+* 房主: `host001`, `host002`, `host003`
+* 观众: `user001`, `user002`, `user003`
+
+2. **环境检查**：检查 `package.json`，若缺失以下依赖则自动添加：
+```json
+{
+  "dependencies": {
+    "@tencentcloud/trtc-uikit-core": "latest"
+  }
+}
+```
+
+3. **权限注入**（语聊房不需要摄像头权限）：
+* **manifest.json**: 配置麦克风权限。
+```json
+{
+  "app-plus": {
+    "distribute": {
+      "android": {
+        "permissions": ["<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>"]
+      },
+      "ios": {
+        "NSMicrophoneUsageDescription": "需要使用麦克风进行语音互动"
+      }
+    }
+  }
+}
+```
+
+### 步骤 1: 获取与生成
+
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+
+* **仅房主**：生成 `host.vue`
+* **仅观众**：生成 `audience.vue`
+* **房主+观众**：生成 `index.vue` (入口选择) + `host.vue` + `audience.vue`
+
+### 步骤 2: 验证与交付
+
+执行 `npm run dev:h5` 或 `npm run build:app`，确保无误后交付。
+
+---
+
+## 🚫 代码生成约束（严格遵守）
+
+### 1. 通用代码约束
+
+* **严禁修改 Import**：统一使用 `import { LiveSeatStore, LiveListStore } from '@tencentcloud/trtc-uikit-core';`。
+* **严禁臆造 API**：必须严格遵循文档中的 Store 和 Model 定义。
+* **必须查阅 API 文档**：涉及数据模型字段（如 `SeatInfo`、`SeatUserInfo`），必须查看文档确认字段名（例如确认是 `userInfo.userName` 而不是 `name`）。
+
+### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
+
+**核心原因**：Vue 的响应式系统如果不正确管理监听器，会导致内存泄漏或状态不同步。
+
+* **唯一实例原则**：所有 Listener **必须声明为组件的 data 或 ref 属性**。
+* **严禁匿名内部类**：禁止直接在 `addListener(new Listener(...))` 中写匿名对象，必须先实例化。
+* **成对原则**：在 `onMounted` 调用 `addListener`，则**必须**在 `onUnmounted` 调用 `removeListener`，防止内存泄漏和监听失效。
+
+### 3. ⏱️ 超时时间限制（关键技术点）
+
+**必须严格遵守以下参数限制，优先使用文档示例中的值：**
+
+#### A. 观众上麦 (`CoGuestStore`)
+
+* **规则**：
+* 可选参数，不填则不检查超时。
+* 若填写，范围必须在 **5 - 1800 秒**之间。
+
+* **正确示例**：
+```javascript
+// ✅ 推荐：跟随文档示例（如 30秒）
+guestStore.applyForSeat({ seatIndex: -1, timeout: 30, extraInfo: null });
+```
+
+#### B. 房主连线 (`CoHostStore`)
+
+* **规则**：
+* **最大值 30 秒**（后台硬限制）。
+
+* **正确示例**：
+```javascript
+// ✅ 推荐：使用最大值
+coHostStore.requestHostConnection({ ..., timeout: 30 });
+```
+
+### 4. 🎨 扩展功能约束（音效/弹幕/礼物/UI）
+
+#### A. 音效 (Audio Effect)
+
+* **变声枚举 (`AudioChangerType`)**：
+* ✅ **允许**：`AudioChangerType.CHILD`, `AudioChangerType.MAN` 等标准枚举。
+* ❌ **禁止**：使用整型索引（如 `1`, `2`）。
+
+#### B. 麦位 UI 布局
+
+* **布局要求**：麦位使用 `v-for` + `view` 组件展示，通常 4x2 或 3x3 布局。
+* **麦位状态**：
+    * 空麦位：显示占位图标（如 `+` 号）
+    * 有人麦位：显示用户头像 + 昵称
+    * 正在说话：头像边框高亮或显示音浪动画
+    * 麦位锁定：显示锁定图标
+* **音浪动画**：订阅 `LiveSeatState.speakingUsers` 获取正在说话的用户和音量。
+
+#### C. 弹幕与礼物布局 (Barrage & Gift)
+
+* **层级要求**：使用绝对定位实现层叠。
+* 底层：麦位区域 (全屏)。
+* 顶层：弹幕、礼物、功能按钮 (使用 `position: absolute` 定位)。
+
+* **键盘适配**：
+* 页面配置 `"navigationStyle": "custom"` 和 `"app-plus": { "softinputMode": "adjustNothing" }`，防止键盘顶起麦位区域。
+
+##### 弹幕输入框 (Barrage Input)
+
+* **位置**：固定在屏幕底部左侧，与功能按钮（礼物、申请上麦等）同行。
+* **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+* **键盘适配**：
+* 键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+
+##### 弹幕显示流 (Barrage Display Flow)
+
+* **数据源**：使用 `watch` 监听 `BarrageStore.create(liveId).barrageState.messageList`。
+* **本地回显**：发送成功后**立即**调用 `appendLocalTip` 插入本地弹幕列表，无需等待服务器回调。
+* **滚动行为**：新消息到达时自动滚动到底部。
+
+##### 全屏礼物动画 (Full-screen Gift Animation)
+
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+* **层级**：全屏礼物动画视图必须覆盖在麦位区域**之上**。
+* **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**房主端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+
+* **沉浸式暗黑**：页面背景必须为 `#000000` 或深色渐变。
+* **安全区域**：所有悬浮 UI 必须考虑 `safe-area-inset-*` CSS 变量。
+* **文字可读性**：深色背景上的白色文字（如弹幕、ID）必须添加**文字阴影** (`text-shadow`)。
+* **错误提示**：统一使用 `uni.showToast`，禁止使用模态 Dialog 打断用户。
+
+### 2. 通用组件规范 (Component Standards)
+
+* **顶部胶囊 (Glass Capsule)**：
+* **样式**：**半透明黑色背景** + **全圆角**。
+* **应用**：仅用于顶部左侧展示"房主头像+ID+在线人数"。
+
+* **通用按钮 (Flat Buttons)**：
+* **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
+* **关闭按钮**：特例，使用圆形半透明背景图标。
+
+### 3. 语聊房布局蓝图 (Voice Room Layout)
+
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如礼物/音效），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+
+* **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [房主头像 | 房主昵称 | 在线人数]。
+* **右侧 [控制区]**：横向排列 [关闭图标(X)]。
+
+#### B. 麦位区域 (Seat Area) - 核心展示区
+
+* **布局方式**：使用 `display: grid` 或 `flex` + `v-for`
+* **典型布局**：
+    * 8 麦位：4x2 或 2x4
+    * 9 麦位：3x3（房主占中心或首位）
+* **麦位状态展示**：
+    * 空麦位：圆形占位 + `+` 号图标
+    * 有人麦位：用户头像 + 昵称 + 麦克风状态图标
+    * 说话中：头像边框高亮（主题色）+ 音浪动画
+    * 锁定麦位：锁定图标覆盖
+
+#### C. 底部栏 (Bottom Bar) - 根据角色动态切换
+
+* **房主模式 (Host)**：
+* **左侧**：[弹幕列表(背景透明)] + [聊天输入框]。
+* **右侧**：功能阵列 [音效] [更多(管理麦位)]。
+
+* **观众模式 (Audience)**：
+* **左侧**：[弹幕列表] + [聊天输入框]。
+* **右侧**：[礼物] [申请上麦]。
+
+* **麦上用户模式 (On-Seat Audience)**：
+* **左侧**：[弹幕列表] + [聊天输入框]。
+* **右侧**：[礼物] [音效] [下麦]。
+
+### 4. 首页布局与交互 (Home Interaction)
+
+#### A. 首页参考布局
+
+```
+┌─────────────────────────────┐
+│       AtomicXCore 语聊房     │
+│                             │
+│  房间 ID                     │
+│  ┌─────────────────────────┐│
+│  │ voice_room_001          ││  ← 输入框 (带左侧 Padding, 半透明背景)
+│  └─────────────────────────┘│
+│                             │
+│  房主开播                    │
+│  (点击即以 host001 登录)      │
+│                             │
+│  观众进房                    │
+│  (点击即以 user001 登录)      │
+│                             │
+│       [ 📋 房间列表 ]        │
+└─────────────────────────────┘
+```
+
+#### B. 隐式登录流程
+
+**首页不需要单独的登录按钮**，登录在点击功能按钮时自动完成：
+
+* 点击「房主开播」→ 使用 `host001` 登录 → 跳转房主页。
+* 点击「观众进房」→ 使用 `user001` 登录 → 跳转观众页。
+* 点击「房间列表」→ 使用 `user001` 登录 → 跳转列表页。
+
+---
+
+## 🎯 功能实现细节
+
+### 1. 房主开播 (`host.vue`)
+
+* **核心**：`LiveListStore` + `LiveSeatStore`
+* **流程**：
+    1. 创建房间：`LiveListStore.createLive()`
+    2. 初始化麦位：`LiveSeatStore.create(liveId)`
+    3. 房主自动上 0 号麦位
+* **销毁**：`onUnmounted` 中必须调用 `endLive()`。
+
+### 2. 观众进房 (`audience.vue`)
+
+* **核心**：`LiveListStore` + `LiveSeatStore`
+* **流程**：
+    1. 加入房间：`LiveListStore.joinLive()`
+    2. 订阅麦位：`watch` 监听 `LiveSeatStore.create(liveId).liveSeatState.seatList`
+* **销毁**：`onUnmounted` 中必须调用 `leaveLive()`。
+
+### 3. 房间列表 (`room-list.vue`)
+
+* **核心**：`LiveListStore.fetchLiveList()` + `v-for` 列表
+* **数据**：`watch` 监听 `liveState.liveList`。
+* **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 上麦与麦位管理交互规范 (`co_guest`)
+
+#### A. 观众申请上麦（房主被动接收）
+
+* **房主端 UI**：❌ **严禁**在底部工具栏或任何位置显示「上麦申请」列表按钮。
+* **交互逻辑**：当收到观众上麦申请回调（`onApplicationReceived`）时，直接弹出确认对话框（`uni.showModal`）：
+* **标题**：上麦申请
+* **内容**：收到观众 [昵称] 的上麦申请，是否接受？
+* **操作**：[拒绝] [接受]
+
+#### B. 麦位管理面板（房主点击麦位弹出）
+
+* **展现形式**：使用底部弹出层（`uni-popup` 或自定义底部面板），禁止使用 Dialog。
+* **功能列表**：
+    * 邀请上麦（空麦位）
+    * 踢下麦位（有人麦位）
+    * 禁言/解禁（有人麦位）
+    * 锁定/解锁麦位
+
+---
+
+## 📋 Agent 最终检查清单
+
+* [ ] **编译验证**：已执行 `npm run dev:h5` 或 `npm run build:app` 且构建成功。
+* [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `SeatInfo`/`SeatUserInfo` 字段名。
+* [ ] **超时合规**：上麦超时 5-1800s，连线超时 ≤30s。
+* [ ] **扩展合规**：音效枚举正确，弹幕布局覆盖且键盘适配。
+* [ ] **礼物合规**：房主和观众端均实现了全屏礼物动画显示。
+* [ ] **麦位合规**：正确 `watch` 监听 `seatList` 和 `speakingUsers`，实现音浪动画。
+* [ ] **凭证注入**：已自动注入测试 UserSig。
+* [ ] **依赖完整**：已检查并修复 `package.json` 和平台权限配置。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```javascript
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+```