@tencentcloud/sdk-mcp 1.3.8 → 1.3.9

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

@@ -0,0 +1,359 @@
+# Native 语聊房 AtomicXCore 代码生成工作流指令 (Flutter)
+
+## 🚨 核心原则（最高优先级）
+
+**Agent 必须确保生成的代码可以成功编译运行，严禁将无法构建的代码交付给用户！**
+
+### ⚠️ 强制编译验证
+
+**每次生成/修改代码后，必须执行完整构建验证**：
+
+```bash
+flutter build apk --debug
+# 或者在 iOS 环境下
+flutter build ios --debug --no-codesign
+```
+
+**禁止行为**：
+
+* ❌ 禁止只用 `flutter analyze` 检查就认为代码正确（无法检测原生依赖问题）
+* ❌ 禁止忽略 `pubspec.yaml` 版本冲突
+
+**编译错误分类与处理**：
+| 错误类型 | 示例 | 处理方式 |
+|---------|------|---------|
+| 依赖解析失败 | `Because xxx depends on yyy...` | 检查 `pubspec.yaml` 版本兼容性，执行 `flutter pub get` |
+| 依赖缺失 | `Target of URI doesn't exist` | 添加缺失库到 `dependencies` |
+| Import 缺失 | `Undefined class 'xxx'` | 添加 import 语句 |
+| 资源缺失 | `Unable to load asset` | 在 `pubspec.yaml` 的 `assets` 节点注册资源 |
+| 权限缺失 | Crash on access Mic | 检查 `AndroidManifest.xml` 和 `Info.plist` |
+
+**验证流程**：
+
+1. 执行 `flutter build apk --debug`。
+2. 如果失败 → 分析完整错误堆栈 → 修复 → 重新构建。
+3. 循环直到 `BUILD SUCCESSFUL`。
+
+**处理流程**：
+
+1. **构建成功** → 交付代码。
+2. **构建失败** → 分析错误 → **自动修复** → 重新构建。
+* ✅ **可自动修复**：依赖缺失、Import 缺失、权限配置缺失。
+* ❌ **不可修复**：SDK 内部错误、Flutter 环境配置问题（需提示用户）。
+
+---
+
+## 📋 指令目的与架构
+
+为 Agent 提供实现 Native (Flutter) 语聊房 AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+
+* **麦位管理**：`LiveSeatStore` (麦位数据驱动)
+* **状态**：`LiveSeatState` / `SeatInfo` / `SeatUserInfo`
+* **事件**：`Listener` (回调处理)
+
+**语聊房 vs 视频直播的核心差异**：
+| 特性 | 视频直播 | 语聊房 |
+|------|---------|-------|
+| 核心组件 | `LiveCoreWidget` | `LiveSeatStore` |
+| 媒体类型 | 音视频流 | 纯音频（麦位） |
+| 画面 | 视频画面 | 麦位头像 + 音浪动画 |
+| 核心概念 | 推流/拉流 | 麦位（seatList） |
+
+**功能依赖逻辑（重要）**：
+
+1. **基础先行**：必须先使用本工具（`get_flutter_voice_uikit_integration`）完成基础语聊房（房主开播/观众进房/房间列表）。
+2. **互动叠加**：如果用户需求包含"上麦"、"连线"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_flutter_voice_uikit_interaction`）。
+3. **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤
+
+### 步骤 0: 前置准备（自动化）
+
+1. **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+* 房主: `host001`, `host002`, `host003`
+* 观众: `user001`, `user002`, `user003`
+
+2. **环境检查**：检查 `pubspec.yaml`，若缺失以下依赖则自动添加：
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  atomic_x_core: ^3.6.0  # 核心库
+  permission_handler: ^11.0.0 # 权限处理
+  svgaplayer_flutter: ^2.0.0 # 礼物动画(如需)
+```
+
+3. **权限注入**（语聊房不需要摄像头权限）：
+* **Android**: 在 `android/app/src/main/AndroidManifest.xml` 添加 Record Audio 权限。
+* **iOS**: 在 `ios/Runner/Info.plist` 添加 `NSMicrophoneUsageDescription`。
+
+### 步骤 1: 获取与生成
+
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+
+* **仅房主**：生成 `HostPage`
+* **仅观众**：生成 `AudiencePage`
+* **房主+观众**：生成 `MainPage` (入口选择) + `HostPage` + `AudiencePage`
+
+### 步骤 2: 验证与交付
+
+执行 `flutter build apk --debug`，确保无误后交付。
+
+---
+
+## 🚫 代码生成约束（严格遵守）
+
+### 1. 通用代码约束
+
+* **严禁修改 Import**：统一使用 `import 'package:atomic_x_core/atomicxcore.dart';`。
+* **严禁臆造 API**：必须严格遵循文档中的 Store 和 Model 定义。
+* **必须查阅 API 文档**：涉及数据模型字段（如 `SeatInfo`、`SeatUserInfo`），必须查看文档确认字段名（例如确认是 `userInfo.userName` 而不是 `name`）。
+
+### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
+
+**核心原因**：Dart 的 Stream 和闭包监听如果不正确释放，会导致严重的内存泄漏或空指针异常。
+
+* **唯一实例原则**：所有 Listener（如 `GuestListener`, `SeatListener`, `BarrageListener`）**必须声明为 State 的成员变量**。
+* **严禁匿名内部类**：禁止直接在 `addListener(Listener(...))` 中写匿名对象，必须先实例化。
+* **成对原则**：在 `initState` 调用 `addListener`，则**必须**在 `dispose` 调用 `removeListener`，防止内存泄漏和监听失效。
+
+### 3. ⏱️ 超时时间限制（关键技术点）
+
+**必须严格遵守以下参数限制，优先使用文档示例中的值：**
+
+#### A. 观众上麦 (`CoGuestStore`)
+
+* **规则**：
+* 可选参数，不填则不检查超时。
+* 若填写，范围必须在 **5 - 1800 秒**之间。
+
+* **正确示例**：
+```dart
+// ✅ 推荐：跟随文档示例（如 30秒）
+guestStore.applyForSeat(seatIndex: -1, timeout: 30, extraInfo: null);
+```
+
+#### B. 房主连线 (`CoHostStore`)
+
+* **规则**：
+* **最大值 30 秒**（后台硬限制）。
+
+* **正确示例**：
+```dart
+// ✅ 推荐：使用最大值
+coHostStore.requestHostConnection(..., timeout: 30);
+```
+
+### 4. 🎨 扩展功能约束（音效/弹幕/礼物/UI）
+
+#### A. 音效 (Audio Effect)
+
+* **变声枚举 (`AudioChangerType`)**：
+* ✅ **允许**：`AudioChangerType.child`, `AudioChangerType.man` 等标准枚举。
+* ❌ **禁止**：使用整型索引（如 `1`, `2`）。
+
+#### B. 麦位 UI 布局
+
+* **布局要求**：麦位使用 `GridView` 展示，通常 4x2 或 3x3 布局。
+* **麦位状态**：
+    * 空麦位：显示占位图标（如 `+` 号）
+    * 有人麦位：显示用户头像 + 昵称
+    * 正在说话：头像边框高亮或显示音浪动画
+    * 麦位锁定：显示锁定图标
+* **音浪动画**：订阅 `LiveSeatState.speakingUsers` 获取正在说话的用户和音量。
+
+#### C. 弹幕与礼物布局 (Barrage & Gift)
+
+* **层级要求**：使用 `Stack` 组件。
+* 底层：麦位区域 (全屏)。
+* 顶层：弹幕、礼物、功能按钮 (使用 `Positioned` 定位)。
+
+* **键盘适配**：
+* `Scaffold` 属性 `resizeToAvoidBottomInset: false`，防止键盘顶起麦位区域。
+* 输入框位于 `Stack` 顶层，使用 `MediaQuery` 监听键盘高度或使用 `Positioned(bottom: 0)` 配合 `SafeArea`。
+
+##### 弹幕输入框 (Barrage Input)
+
+* **位置**：固定在屏幕底部左侧，与功能按钮（礼物、申请上麦等）同行。
+* **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+* **键盘适配**：
+* 键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+* **必须**在 `Scaffold` 设置 `resizeToAvoidBottomInset: false`。
+
+##### 弹幕显示流 (Barrage Display Flow)
+
+* **数据源**：使用 `ValueListenableBuilder` 监听 `BarrageStore.create(liveId).barrageState.messageList`。
+* **本地回显**：发送成功后**立即**调用 `appendLocalTip` 插入本地弹幕列表，无需等待服务器回调。
+* **滚动行为**：新消息到达时自动滚动到底部。
+
+##### 全屏礼物动画 (Full-screen Gift Animation)
+
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+* **依赖**：必须引入 `svgaplayer_flutter`。
+* **层级**：全屏礼物动画视图必须覆盖在麦位区域**之上**。
+* **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**房主端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+
+* **沉浸式暗黑**：`Scaffold` 背景必须为 `Colors.black` 或深色渐变。
+* **安全区域**：所有悬浮 UI 必须包裹在 `SafeArea` 中。
+* **文字可读性**：深色背景上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`Shadow`)。
+* **错误提示**：统一使用 `SnackBar` 或 `FlutterToast`，禁止使用模态 Dialog 打断用户。
+
+### 2. 通用组件规范 (Component Standards)
+
+* **顶部胶囊 (Glass Capsule)**：
+* **样式**：**半透明黑色背景** + **全圆角**。
+* **应用**：仅用于顶部左侧展示"房主头像+ID+在线人数"。
+
+* **通用按钮 (Flat Buttons)**：
+* **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
+* **关闭按钮**：特例，使用圆形半透明背景图标。
+
+### 3. 语聊房布局蓝图 (Voice Room Layout)
+
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如礼物/音效），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+
+* **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [房主头像 | 房主昵称 | 在线人数]。
+* **右侧 [控制区]**：横向排列 [关闭图标(X)]。
+
+#### B. 麦位区域 (Seat Area) - 核心展示区
+
+* **布局方式**：使用 `GridView.builder`
+* **典型布局**：
+    * 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. 房主开播 (`HostPage`)
+
+* **核心**：`LiveListStore` + `LiveSeatStore`
+* **流程**：
+    1. 创建房间：`LiveListStore.createLive()`
+    2. 初始化麦位：`LiveSeatStore.create(liveId)`
+    3. 房主自动上 0 号麦位
+* **销毁**：`dispose` 中必须调用 `endLive()`。
+
+### 2. 观众进房 (`AudiencePage`)
+
+* **核心**：`LiveListStore` + `LiveSeatStore`
+* **流程**：
+    1. 加入房间：`LiveListStore.joinLive()`
+    2. 订阅麦位：`LiveSeatStore.create(liveId).liveSeatState.seatList` (ValueListenable)
+* **销毁**：`dispose` 中必须调用 `leaveLive()`。
+
+### 3. 房间列表 (`RoomListPage`)
+
+* **核心**：`LiveListStore.fetchLiveList()` + `GridView`/`ListView`
+* **数据**：订阅 `liveState.liveList` (ValueListenable)。
+* **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 上麦与麦位管理交互规范 (`co_guest`)
+
+#### A. 观众申请上麦（房主被动接收）
+
+* **房主端 UI**：❌ **严禁**在底部工具栏或任何位置显示「上麦申请」列表按钮。
+* **交互逻辑**：当收到观众上麦申请回调（`onApplicationReceived`）时，直接在屏幕中心弹出对话框（`showDialog`）：
+* **标题**：上麦申请
+* **内容**：收到观众 [昵称] 的上麦申请，是否接受？
+* **操作**：[拒绝] [接受]
+
+#### B. 麦位管理面板（房主点击麦位弹出）
+
+* **展现形式**：使用底部浮层面板（`showModalBottomSheet`），禁止使用 Dialog。
+* **功能列表**：
+    * 邀请上麦（空麦位）
+    * 踢下麦位（有人麦位）
+    * 禁言/解禁（有人麦位）
+    * 锁定/解锁麦位
+
+---
+
+## 📋 Agent 最终检查清单
+
+* [ ] **编译验证**：已执行 `flutter build apk --debug` 且结果为 SUCCESS。
+* [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `SeatInfo`/`SeatUserInfo` 字段名。
+* [ ] **超时合规**：上麦超时 5-1800s，连线超时 ≤30s。
+* [ ] **扩展合规**：音效枚举正确，弹幕布局覆盖且键盘适配。
+* [ ] **礼物合规**：房主和观众端均实现了全屏礼物动画显示。
+* [ ] **麦位合规**：正确订阅 `seatList` 和 `speakingUsers`，实现音浪动画。
+* [ ] **凭证注入**：已自动注入测试 UserSig。
+* [ ] **依赖完整**：已检查并修复 `pubspec.yaml` 和平台权限配置。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```dart
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+```

package/resource/doc/livekit/voice/ios/voice-audience-list.md

@@ -0,0 +1,335 @@
+`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过 `LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182232/5899241bb63f11f0a6c652540044a08e.png)
+
+
+## 核心功能
+- **实时观众列表**：获取并展示当前在直播间内的所有观众信息。
+
+- **观众人数统计**：实时获取当前直播间的准确观众总数。
+
+- **观众动态监听**：通过事件订阅，实时感知观众的加入和离开。
+
+- **管理员权限**：主播可以将普通观众设为管理员，或撤销其管理员身份。
+
+- **房间管理**：主播或管理员可以将任意普通观众请出（踢出）直播间。
+
+
+## 核心概念
+
+在开始集成之前，我们先通过下表了解一下 LiveAudienceStore 相关的几个核心概念：
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**核心概念**</td>
+
+<td rowspan="1" colSpan="1" >**类型**</td>
+
+<td rowspan="1" colSpan="1" >**核心职责与描述**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveUserInfo`</td>
+
+<td rowspan="1" colSpan="1" >struct</td>
+
+<td rowspan="1" colSpan="1" >代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceState`</td>
+
+<td rowspan="1" colSpan="1" >struct</td>
+
+<td rowspan="1" colSpan="1" >代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `[LiveUserInfo] `数组，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceEvent`</td>
+
+<td rowspan="1" colSpan="1" >enum</td>
+
+<td rowspan="1" colSpan="1" >代表观众动态的实时事件。分为 `.onAudienceJoined`（观众加入） 和 `.onAudienceLeft`（观众离开）两种，用于实现对观众列表的增量更新。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`LiveAudienceStore`</td>
+
+<td rowspan="1" colSpan="1" >class</td>
+
+<td rowspan="1" colSpan="1" >这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过订阅其 `liveAudienceEventPublisher` 来接收实时动态。</td>
+</tr>
+</table>
+
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 [开始直播](https://write.woa.com/document/192834898445422592) 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前直播间 liveId 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+``` swift
+import Foundation
+import AtomicXCore 
+import Combine     
+
+class AudienceManager {
+    private let liveId: String
+    private let audienceStore: LiveAudienceStore
+    private var cancellables = Set<AnyCancellable>()
+    
+    // 对外暴露【全量】观众列表的发布者，方便UI层订阅
+    let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
+    // 对外暴露观众总数的发布者
+    let audienceCountPublisher = PassthroughSubject<UInt, Never>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 1. 通过 liveId 获取 LiveAudienceStore 的实例
+        self.audienceStore = LiveAudienceStore.create(liveID: liveId)
+        
+        // 2. 订阅状态和事件
+        subscribeToAudienceState()
+        subscribeToAudienceEvents()
+        
+        // 3. 主动拉取首屏数据
+        fetchInitialAudienceList()
+    }
+
+    /// 主动获取一次观众列表快照
+    func fetchInitialAudienceList() {
+        audienceStore.fetchAudienceList { [weak self] result in
+            switch result {
+            case .success:
+                print("首次拉取观众列表成功")
+                // 成功后，数据会通过下面的 state 订阅通道自动更新
+            case .failure(let error):
+                print("首次拉取观众列表失败: \(error.localizedDescription)")
+            }
+        }
+    }
+    
+    // ... 后续代码
+}
+```
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅 `audienceStore` 的 `state` 和 `event`，以接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
+``` swift
+extension AudienceManager {
+    /// 订阅 state，用于获取观众总数和列表快照
+    private func subscribeToAudienceState() {
+        audienceStore.state
+            .subscribe()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] state in
+                // state.audienceList 是一个全量快照
+                self?.audienceListPublisher.send(state.audienceList)
+                // state.audienceCount 是实时总数
+                self?.audienceCountPublisher.send(state.audienceCount)
+            }
+            .store(in: &cancellables)
+    }
+
+    /// 订阅 event，用于处理观众的实时进出
+    private func subscribeToAudienceEvents() {
+        audienceStore.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self = self else { return }
+                
+                var currentList = self.audienceListPublisher.value
+                
+                switch event {
+                case .onAudienceJoined(let newAudience):
+                    print("观众 \(newAudience.userName) 加入了直播间")
+                    // 增量更新：在当前列表末尾添加新观众
+                    if !currentList.contains(where: { $0.userID == newAudience.userID }) {
+                        currentList.append(newAudience)
+                        self.audienceListPublisher.send(currentList)
+                    }
+                    
+                case .onAudienceLeft(let departedAudience):
+                    print("观众 \(departedAudience.userName) 离开了直播间")
+                    // 增量更新：从当前列表中移除离开的观众
+                    currentList.removeAll { $0.userID == departedAudience.userID }
+                    self.audienceListPublisher.send(currentList)
+                }
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对直播间内的观众进行管理操作。
+
+#### 4.1 将观众踢出直播间
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
+``` swift
+extension AudienceManager {
+    func kick(userId: String) {
+        audienceStore.kickUserOutOfRoom(userId: userId) { result in
+            switch result {
+            case .success:
+                print("成功将用户 \(userId) 踢出房间")
+                // 踢出成功后，您会收到 onAudienceLeft 事件
+            case .failure(let error):
+                print("踢出用户 \(userId) 失败: \(error.localizedDescription)")
+            }
+        }
+    }
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` swift
+extension AudienceManager {
+    /// 将用户设为管理员
+    func promoteToAdmin(userId: String) {
+        audienceStore.setAdministrator(userId: userId) { result in
+            if case .success = result {
+                print("成功将用户 \(userId) 设为管理员")
+            }
+        }
+    }
+
+    /// 撤销用户的管理员身份
+    func revokeAdmin(userId: String) {
+        audienceStore.revokeAdministrator(userId: userId) { result in
+            if case .success = result {
+                print("成功撤销用户 \(userId) 的管理员身份")
+            }
+        }
+    }
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如：“欢迎 [用户昵称] 进入直播间”。
+
+#### 实现方式
+
+我们通过订阅 `LiveAudienceStore` 的观众加入事件（`LiveAudienceEvent.onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
+``` swift
+import Foundation
+import AtomicXCore 
+import Combine
+
+class LiveRoomManager {
+    private let liveId: String
+    private let audienceManager: AudienceManager
+    private let barrageManager: BarrageManager // 假设您已实现了弹幕文档中的BarrageManager
+    private var cancellables = Set<AnyCancellable>()
+
+    init(liveId: String) {
+        self.liveId = liveId
+        // 初始化两个核心管理器
+        self.audienceManager = AudienceManager(liveId: liveId)
+        self.barrageManager = BarrageManager(liveId: liveId)
+
+        // 设置联动
+        setupWelcomeMessageFlow()
+    }
+
+    private func setupWelcomeMessageFlow() {
+        // 1. 获取 LiveAudienceStore 的实例
+        let audienceStore = LiveAudienceStore.create(liveID: self.liveId)
+
+        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
+        let barrageStore = BarrageStore.create(liveID: self.liveId)
+
+        // 3. 订阅观众事件
+        audienceStore.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { event in
+                // 4. 只处理观众加入事件
+                guard case .onAudienceJoined(let newAudience) = event else {
+                    return
+                }
+
+                // 5. 创建一条本地提示消息
+                var welcomeTip = Barrage()
+                welcomeTip.messageType = .text 
+                welcomeTip.textContent = "欢迎 \(newAudience.userName) 进入直播间！"
+
+                // 6. 调用 BarrageStore 的接口将其插入弹幕列表
+                barrageStore.appendLocalTip(message: welcomeTip)
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+## API 文档
+
+关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >Store/Component</td>
+
+<td rowspan="1" colSpan="1" >功能描述</td>
+
+<td rowspan="1" colSpan="1" >API 文档</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >LiveCoreView</td>
+
+<td rowspan="1" colSpan="1" >直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >LiveAudienceStore</td>
+
+<td rowspan="1" colSpan="1" >观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveaudiencestore)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >BarrageStore</td>
+
+<td rowspan="1" colSpan="1" >弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore)</td>
+</tr>
+</table>
+
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制：**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点：**在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
+
+
+      **这对开发者意味着什么？**
+
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。
+
+