@tencentcloud/sdk-mcp 1.3.8 → 1.3.9

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

@@ -0,0 +1,358 @@
+# Native 语聊房 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 |
+| `NSMicrophoneUsageDescription` | Info.plist 权限缺失 | 添加权限描述 |
+
+**验证循环（必须遵守）**：
+```
+执行编译 → 失败 → 分析错误 → 修复代码 → 重新执行编译 → ... → BUILD SUCCEEDED → 交付
+```
+
+---
+
+## 📋 指令目的与架构
+
+为 Agent 提供实现 Native (iOS) 语聊房 AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+*   **麦位管理**：`LiveSeatStore` (麦位数据驱动)
+*   **状态**：`LiveSeatState` / `SeatInfo` / `SeatUserInfo`
+*   **事件**：`Publisher` (Combine 订阅)
+
+**语聊房 vs 视频直播的核心差异**：
+| 特性 | 视频直播 | 语聊房 |
+|------|---------|-------|
+| 核心组件 | `LiveCoreView` | `LiveSeatStore` |
+| 媒体类型 | 音视频流 | 纯音频（麦位） |
+| 画面 | 视频画面 | 麦位头像 + 音浪动画 |
+| 核心概念 | 推流/拉流 | 麦位（seatList） |
+
+**功能依赖逻辑（重要）**：
+1.  **基础先行**：必须先使用本工具（`get_native_voice_uikit_integration`）完成基础语聊房（房主开播/观众进房/房间列表）。
+2.  **互动叠加**：如果用户需求包含"上麦"、"连线"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_native_voice_uikit_interaction`）。
+3.  **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤（必须创建为 TODO 任务）
+
+**🚨 Agent 必须将以下步骤创建为 TODO 任务列表，逐一完成并打勾：**
+
+### 步骤 1: 前置准备
+1.  **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+    *   房主: `host001`, `host002`, `host003`
+    *   观众: `user001`, `user002`, `user003`
+2.  **环境检查**：检查 `Podfile`，若缺失以下依赖则自动添加：
+    ```ruby
+    pod 'AtomicXCore'
+    ```
+3.  **权限注入**：在 `Info.plist` 中添加麦克风权限描述（语聊房不需要摄像头权限）：
+    ```xml
+    <key>NSMicrophoneUsageDescription</key>
+    <string>需要访问您的麦克风权限，开启后才能进行语音互动</string>
+    ```
+
+### 步骤 2: 代码生成
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+*   **仅房主**：生成 `HostViewController`
+*   **仅观众**：生成 `AudienceViewController`
+*   **房主+观众**：生成 `MainViewController` (入口选择) + `HostViewController` + `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 文档**：涉及数据模型字段（如 `SeatInfo`、`SeatUserInfo`），必须查看文档确认字段名（例如确认是 `userInfo.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. 房主连线 (`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. 麦位 UI 布局
+*   **布局要求**：麦位使用 `UICollectionView` + `UICollectionViewFlowLayout` 展示，通常 4x2 或 3x3 布局。
+*   **麦位状态**：
+    *   空麦位：显示占位图标（如 `+` 号）
+    *   有人麦位：显示用户头像 + 昵称
+    *   正在说话：头像边框高亮或显示音浪动画
+    *   麦位锁定：显示锁定图标
+*   **音浪动画**：订阅 `LiveSeatState.speakingUsers` 获取正在说话的用户和音量。
+
+#### C. 弹幕与礼物布局 (Barrage & Gift)
+*   **层级要求**：弹幕列表和全屏礼物动画必须使用 `UIView` 覆盖在麦位区域**之上**。
+*   **禁止分割**：严禁将屏幕分割为"上麦位、下弹幕"，必须是叠加模式。
+
+##### 弹幕输入框 (Barrage Input)
+*   **位置**：固定在屏幕底部左侧，与功能按钮（礼物、申请上麦等）同行。
+*   **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+*   **键盘适配**：
+    *   键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+    *   麦位区域约束固定为 `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)
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+*   **层级**：全屏礼物动画视图必须覆盖在麦位区域**之上**，使用独立的 `UIView` 容器。
+*   **布局**：约束为 `edges.equalToSuperview()`，覆盖整个屏幕。
+*   **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**房主端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+*   **沉浸式暗黑**：语聊房页背景必须为 `.black` 或深色渐变。
+*   **安全区域**：所有悬浮 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. 语聊房布局蓝图 (Voice Room Layout)
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如礼物/音效），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+*   **左侧 [房间信息]**：使用 **磨砂胶囊** 包裹 [房主头像 | 房主昵称 | 在线人数]。
+*   **右侧 [控制区]**：横向排列 [关闭图标(X)]。
+
+#### B. 麦位区域 (Seat Area) - 核心展示区
+*   **布局方式**：使用 `UICollectionView` + `UICollectionViewFlowLayout`
+*   **典型布局**：
+    *   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_streaming`)
+*   **核心**：`LiveListStore.shared.createLive()` + `LiveSeatStore`
+*   **流程**：
+    1. 创建房间：`LiveListStore.shared.createLive(roomId, roomName, ...)`
+    2. 初始化麦位：`LiveSeatStore.shared`
+    3. 房主自动上 0 号麦位
+*   **销毁**：`deinit` 或退出页面时必须调用 `endLive()`。
+
+### 2. 观众进房 (`audience_join`)
+*   **核心**：`LiveListStore.shared.joinLive()` + `LiveSeatStore`
+*   **流程**：
+    1. 加入房间：`LiveListStore.shared.joinLive(liveId)`
+    2. 订阅麦位：`LiveSeatStore.shared.liveSeatState.$seatList`
+*   **销毁**：`deinit` 或退出页面时必须调用 `leaveLive()`。
+
+### 3. 房间列表 (`room_list`)
+*   **核心**：`LiveListStore.shared.fetchLiveList()` + `UITableView/UICollectionView`
+*   **数据**：订阅 `liveState.liveList`。
+*   **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 上麦与麦位管理交互规范 (`co_guest`)
+
+#### A. 观众申请上麦（房主被动接收）
+*   **房主端 UI**：❌ **严禁**在底部工具栏或任何位置显示「上麦申请」列表按钮。
+*   **交互逻辑**：当收到观众上麦申请回调时，直接在屏幕中心弹出对话框（`UIAlertController`）：
+    *   **标题**：上麦申请
+    *   **内容**：收到观众 [昵称] 的上麦申请，是否接受？
+    *   **操作**：[拒绝] [接受]
+
+#### B. 麦位管理面板（房主点击麦位弹出）
+*   **展现形式**：使用底部浮层面板（`UIView` 动画升起）。
+*   **功能列表**：
+    *   邀请上麦（空麦位）
+    *   踢下麦位（有人麦位）
+    *   禁言/解禁（有人麦位）
+    *   锁定/解锁麦位
+
+---
+
+## 📋 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，已核对 `SeatInfo`/`SeatUserInfo` 字段名。
+- [ ] **超时合规**：上麦超时 5-1800s，连线超时 ≤30s。
+- [ ] **扩展合规**：音效枚举正确，弹幕布局覆盖且键盘适配。
+- [ ] **礼物合规**：房主和观众端均实现了全屏礼物动画显示。
+- [ ] **麦位合规**：正确订阅 `seatList` 和 `speakingUsers`，实现音浪动画。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```swift
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+```

package/resource/doc/livekit/voice/uni-app/voice-audience-list.md

@@ -0,0 +1,264 @@
+`LiveAudienceState` 是 `AtomicXCore` 中专门负责管理语聊房观众信息的模块。通过 `LiveAudienceState`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100028028022/ef4d5ed8bbbf11f085a55254007c27c5.png)
+
+
+## 核心功能
+- **实时观众列表**：获取并展示当前在语聊房内的所有观众信息。
+
+- **观众人数统计**：实时获取当前语聊房的准确观众总数。
+
+- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
+
+- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
+
+- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）语聊房。
+
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 [开始直播](https://write.woa.com/document/191127271985012736) 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前语聊房 liveID 绑定的 `LiveAudienceState` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+``` typescript
+import { useLiveAudienceState } from "@/uni_modules/tuikit-atomic-x/state/LiveAudienceState";
+import { onMounted, watch } from 'vue';
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+// 通过 liveID 获取 LiveAudienceState 的实例
+const { fetchAudienceList, audienceList } = useLiveAudienceState(liveID)
+
+onMounted(() => {
+    fetchAudienceList({
+      liveID: 'xxx', // 当前语聊房的 liveID
+      success: () => {        
+        // 成功后，响应式数据会自动更新
+        console.log('首次拉取观众列表成功')
+      },
+      fail: (error) => {
+        console.log('首次拉取观众列表失败', error)
+      }
+    })
+})
+
+// 监听 audienceList 的实时变更，用于驱动 UI 变更
+watch(audienceList, (newVal, oldVal) => {
+    console.log(newVal)
+})
+
+// ... 后续代码 
+```
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅和监听 `audienceState` 的 `event` 和 `响应式数据`，用来接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
+``` typescript
+import { useLiveAudienceState } from "@/uni_modules/tuikit-atomic-x/state/LiveAudienceState";
+import { onMounted, watch } from 'vue';
+
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+//通过 liveID 获取 LiveAudienceState 的实例
+const { audienceList, audienceCount, addAudienceListener, removeAudienceListener } = useLiveAudienceState(liveID)
+
+// 监听 audienceList 的实时变更，用于驱动 UI 更新
+watch(audienceList, (newVal, oldVal) => {
+    console.log(newVal)
+})
+
+// 监听 audienceCount 的实时变更，用于驱动 UI 更新
+watch(audienceCount, (newVal, oldVal) => {
+    console.log(newVal)
+})
+
+onMounted(() => {
+    addAudienceListener( liveID, 'onAudienceJoined', 
+      { callback: (event) => {
+        const newAudience = JSON.parse(event)
+        console.log("观众 ${newAudience.userName} 加入了语聊房")
+      }
+    })
+    
+    addAudienceListener( liveID, 'onAudienceLeft',
+      { callback: (event) => {
+        const departedAudience = JSON.parse(event)
+        console.log("观众 ${departedAudience.userName} 离开了语聊房")
+      }
+    })
+})
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对语聊房内的观众进行管理操作。
+
+#### 4.1 将观众踢出语聊房
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出语聊房。
+``` typescript
+import { useLiveAudienceState } from "@/uni_modules/tuikit-atomic-x/state/LiveAudienceState";
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+//通过 liveID 获取 LiveAudienceState 的实例
+const { kickUserOutOfRoom } = useLiveAudienceState(liveID)
+
+const kickOut = () => {
+    kickUserOutOfRoom({
+      liveID: 'xxx', // 当前语聊房的 liveID
+      userID: 'xxx', // 想要踢出成员的 userID
+      success: () => {
+        console.log("成功将用户 ${userID} 踢出房间")
+        // 踢出成功后，您会收到 onAudienceLeft 事件
+      },
+      fail: (error) => {
+        console.log("将用户 ${userID} 踢出房间失败", error)
+      } 
+    })
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` typescript
+import { useLiveAudienceState } from "@/uni_modules/tuikit-atomic-x/state/LiveAudienceState";
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+//通过 liveID 获取 LiveAudienceState 的实例
+const { setAdministrator, revokeAdministrator } = useLiveAudienceState(liveID)
+
+// 将用户设为管理员
+const promoteToAdmin = () => {
+    setAdministrator({
+      liveID: 'xxx', // 当前语聊房的 liveID
+      userID: 'xxx', // 想要设为管理员的 userID 
+      success: () => {
+        console.log("成功将用户 ${userID} 设为管理员")
+      },
+      fail: (error) => {
+        console.log("将用户 ${userID} 设为管理员失败", error)
+      }
+    })
+}
+
+// 撤销用户的管理员身份
+const revokeAdmin = () => {
+    revokeAdministrator({
+      liveID: 'xxx', // 当前语聊房的 liveID
+      userID: 'xxx', // 想要撤销管理员的 userID 
+      success: () => {
+        console.log("成功将用户 ${userID} 的管理员身份撤销")
+      },
+      fail: (error) => {
+        console.log("将用户 ${userID} 设为管理员身份撤销失败", error)
+      }
+    })
+
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入语聊房时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如：“欢迎 [用户昵称] 进入语聊房”。
+
+#### 实现方式
+
+我们通过订阅 `LiveAudienceState` 的观众加入事件（ `'onAudienceJoined'` ）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageState` 的本地插入接口 `appendLocalTip`。
+``` typescript
+import { useLiveAudienceState } from "@/uni_modules/tuikit-atomic-x/state/LiveAudienceState";
+import { useBarrageState } from '@/uni_modules/tuikit-atomic-x/state/BarrageState';
+import { onMounted } from 'vue';
+
+// liveID 是语聊房的唯一标识
+const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
+
+//通过 liveID 获取 LiveAudienceState 的实例
+const { addAudienceListener, removeAudienceListener } = useLiveAudienceState(liveID)
+//通过 liveID 获取 BarrageState 的实例
+const { appendLocalTip } = useBarrageState(liveID)
+
+onMounted(() => {
+    addAudienceListener(liveID, 'onAudienceJoined', 
+      { callback: (event) => {
+        const newAudience = JSON.parse(event)
+        // 创建一条本地提示消息
+        let welcomeTip = {}   
+        welcomeTip.liveID = liveID,
+        welcomeTip.sender = { userID: 'xxx' },
+        welcomeTip.sequence = Date.now(),
+        welcomeTip.timestampInSecond = Date.now(),
+        welcomeTip.messageType = 'TEXT',
+        welcomeTip.textContent = "欢迎 ${newAudience.userName} 进入语聊房！"
+        // 调用 BarrageStore 的接口将其插入弹幕列表
+        appendLocalTip(welcomeTip)
+        console.log("观众 ${newAudience.userName} 加入了语聊房")
+       }
+    })
+})
+```
+
+## API 文档
+
+关于 [LiveAudienceState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://write.woa.com/document/192223419814899712) 框架的官方 API 文档。本文档使用到的相关 State 如下：
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**State**</td>
+
+<td rowspan="1" colSpan="1" >**功能描述**</td>
+
+<td rowspan="1" colSpan="1" >**API 文档**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >LiveAudienceState</td>
+
+<td rowspan="1" colSpan="1" >观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >BarrageState</td>
+
+<td rowspan="1" colSpan="1" >弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState)</td>
+</tr>
+</table>
+
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**：当用户主动加入或正常退出语聊房时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制：**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点：**在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
+
+
+      **这对开发者意味着什么？**
+
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。
+
+