@tencentcloud/sdk-mcp 1.3.7 → 1.3.9

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

@@ -0,0 +1,333 @@
+# Native 语聊房 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) 语聊房 AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+*   **麦位管理**：`LiveSeatStore` (麦位数据驱动)
+*   **状态**：`LiveSeatState` / `SeatInfo` / `SeatUserInfo`
+*   **事件**：`GuestListener` / `SeatListener` (回调处理)
+
+**语聊房 vs 视频直播的核心差异**：
+| 特性 | 视频直播 | 语聊房 |
+|------|---------|-------|
+| 核心组件 | `LiveCoreView` | `LiveSeatStore` |
+| 媒体类型 | 音视频流 | 纯音频（麦位） |
+| 画面 | 视频画面 | 麦位头像 + 音浪动画 |
+| 核心概念 | 推流/拉流 | 麦位（seatList） |
+
+**功能依赖逻辑（重要）**：
+1.  **基础先行**：必须先使用本工具（`get_native_voice_uikit_integration`）完成基础语聊房（房主开播/观众进房/房间列表）。
+2.  **互动叠加**：如果用户需求包含"上麦"、"连线"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_native_voice_uikit_interaction`）。
+3.  **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤
+
+### 步骤 0: 前置准备（自动化）
+1.  **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+    *   房主: `host001`, `host002`, `host003`
+    *   观众: `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` 中添加麦克风、网络权限（语聊房不需要摄像头权限）。
+    ```xml
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    ```
+
+### 步骤 1: 获取与生成
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+*   **仅房主**：生成 `HostActivity`
+*   **仅观众**：生成 `AudienceActivity`
+*   **房主+观众**：生成 `MainActivity` (入口选择) + `HostActivity` + `AudienceActivity`
+
+### 步骤 2: 验证与交付
+执行 `./gradlew assembleDebug`，确保无误后交付。
+
+---
+
+## 🚫 代码生成约束（严格遵守）
+
+### 1. 通用代码约束
+*   **严禁修改 Import**：文档中的 import 路径经过验证，绝对不可修改。
+*   **严禁臆造 API**：如果文档没写，绝对不能自己发明方法名或参数名。
+*   **必须查阅 API 文档**：涉及数据模型字段（如 `SeatInfo`、`SeatUserInfo`），必须查看文档确认字段名（例如确认是 `userInfo.userName` 而不是 `name`）。
+
+### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
+**核心原因**：SDK 的 `LiveSeatStore.create(liveId)` 通常返回单例或复用实例。使用匿名内部类会导致监听器实例重复注册或被覆盖，引发"房主端不显示"或"仅首次生效"的 Bug。
+
+*   **唯一实例原则**：所有 Listener（如 `GuestListener`, `SeatListener`, `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. 房主连线 (`CoHostStore`)
+*   **规则**：
+    *   **最大值 30 秒**（后台硬限制）。
+*   **正确示例**：
+    ```kotlin
+    // ✅ 推荐：使用最大值
+    requestHostConnection(..., timeout = 30, ...)
+    ```
+*   **错误示例**：❌ `timeout = 60` (会导致请求失败)。
+
+### 4. 🎨 扩展功能约束（音效/弹幕/礼物/UI）
+
+#### A. 音效 (Audio Effect)
+*   **变声枚举 (`AudioChangerType`)**：
+    *   ✅ **允许**：`CHILD, LITTLE_GIRL, MAN, ETHEREAL` 等标准枚举。
+    *   ❌ **禁止**：`UNCLE, LOLI, GIRL, BOY` (这些是旧版或错误的枚举)。
+*   **混响枚举 (`AudioReverbType`)**：
+    *   ✅ **允许**：`KTV, SMALL_ROOM, METALLIC` 等。
+    *   ❌ **禁止**：`ROOM, HALL, LOW`。
+
+#### B. 麦位 UI 布局
+*   **布局要求**：麦位使用 `RecyclerView` + `GridLayoutManager` 展示，通常 4x2 或 3x3 布局。
+*   **麦位状态**：
+    *   空麦位：显示占位图标（如 `+` 号）
+    *   有人麦位：显示用户头像 + 昵称
+    *   正在说话：头像边框高亮或显示音浪动画
+    *   麦位锁定：显示锁定图标
+*   **音浪动画**：订阅 `LiveSeatState.speakingUsers` 获取正在说话的用户和音量。
+
+#### C. 弹幕与礼物布局 (Barrage & Gift)
+*   **层级要求**：弹幕列表和全屏礼物动画使用 `FrameLayout` 覆盖在麦位区域**之上**。
+*   **禁止分割**：严禁将屏幕分割为"上麦位、下弹幕"，必须是叠加模式。
+*   **键盘适配**：必须在 Manifest 中设置 `android:windowSoftInputMode="adjustNothing"` 或 `adjustPan`，**防止键盘弹起时麦位区域变形或上移**。
+
+##### 弹幕输入框 (Barrage Input)
+*   **位置**：固定在屏幕底部左侧，与功能按钮（礼物、申请上麦等）同行。
+*   **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+*   **键盘适配**：
+    *   键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+    *   **必须**在 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)
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+*   **层级**：全屏礼物动画视图必须覆盖在麦位区域**之上**，使用独立的 `FrameLayout` 容器。
+*   **布局**：约束为 `match_parent`，覆盖整个屏幕。
+*   **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**房主端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+*   **沉浸式暗黑**：语聊房页背景必须为 `Color.BLACK` 或深色渐变。
+*   **安全区域**：所有悬浮 UI 必须考虑状态栏和导航栏，严禁被刘海屏或底部导航条遮挡。
+*   **文字可读性**：深色背景上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`setShadowLayer`)。
+*   **错误提示**：统一使用 **Toast**，禁止使用模态 AlertDialog 打断用户。
+
+### 2. 通用组件规范 (Component Standards)
+*   **顶部胶囊 (Glass Capsule)**：
+    *   **样式**：**半透明黑色背景** + **全圆角** (`cornerRadius = height / 2`)。
+    *   **应用**：仅用于顶部左侧展示"房主头像+ID+在线人数"。
+*   **通用按钮 (Flat Buttons)**：
+    *   **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
+    *   **关闭按钮**：特例，使用圆形半透明背景图标。
+*   **弹出面板 (Floating Panels)**：
+    *   **样式**：仅顶部大圆角 (`topLeftRadius, topRightRadius`)。
+    *   **禁忌**：底部禁止出现非透明的实色背景块，必须保持悬浮感。
+
+### 3. 语聊房布局蓝图 (Voice Room Layout)
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如礼物/音效），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+*   **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [房主头像 | 房主昵称 | 在线人数]。
+*   **右侧 [控制区]**：横向排列 [关闭图标(X)]。
+
+#### B. 麦位区域 (Seat Area) - 核心展示区
+*   **布局方式**：使用 `RecyclerView` + `GridLayoutManager`
+*   **典型布局**：
+    *   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.createLive()` + `LiveSeatStore`
+*   **流程**：
+    1. 创建房间：`LiveListStore.createLive(roomId, roomName, ...)`
+    2. 初始化麦位：`LiveSeatStore.create(liveId)`
+    3. 房主自动上 0 号麦位
+*   **销毁**：`onDestroy` 中必须调用 `endLive()`。
+
+### 2. 观众进房 (`audience_join`)
+*   **核心**：`LiveListStore.joinLive()` + `LiveSeatStore`
+*   **流程**：
+    1. 加入房间：`LiveListStore.joinLive(liveId)`
+    2. 订阅麦位：`LiveSeatStore.create(liveId).liveSeatState.seatList`
+*   **销毁**：`onDestroy` 中必须调用 `leaveLive()`。
+
+### 3. 房间列表 (`room_list`)
+*   **核心**：`LiveListStore.fetchLiveList()` + `RecyclerView`
+*   **数据**：订阅 `liveState.liveList`。
+*   **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 上麦与麦位管理交互规范 (`co_guest`)
+
+#### A. 观众申请上麦（房主被动接收）
+*   **房主端 UI**：❌ **严禁**在底部工具栏或任何位置显示「上麦申请」列表按钮。
+*   **交互逻辑**：当收到观众上麦申请回调时，直接在屏幕中心弹出对话框（`AlertDialog`）：
+    *   **标题**：上麦申请
+    *   **内容**：收到观众 [昵称] 的上麦申请，是否接受？
+    *   **操作**：[拒绝] [接受]
+
+#### B. 麦位管理面板（房主点击麦位弹出）
+*   **展现形式**：使用底部浮层面板（`BottomSheetDialog`）。
+*   **功能列表**：
+    *   邀请上麦（空麦位）
+    *   踢下麦位（有人麦位）
+    *   禁言/解禁（有人麦位）
+    *   锁定/解锁麦位
+
+---
+
+## 📋 Agent 最终检查清单
+
+- [ ] **编译验证**：已执行 `./gradlew assembleDebug` 且结果为 SUCCESS。
+- [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `SeatInfo`/`SeatUserInfo` 字段名。
+- [ ] **超时合规**：上麦超时 5-1800s，连线超时 ≤30s。
+- [ ] **扩展合规**：音效枚举正确，弹幕布局覆盖且键盘适配。
+- [ ] **礼物合规**：房主和观众端均实现了全屏礼物动画显示。
+- [ ] **麦位合规**：正确订阅 `seatList` 和 `speakingUsers`，实现音浪动画。
+- [ ] **凭证注入**：已自动注入测试 UserSig。
+- [ ] **依赖完整**：已检查并修复 `build.gradle` 和权限。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```kotlin
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+```

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

@@ -0,0 +1,337 @@
+`LiveAudienceStore` 是 `AtomicXCore` 中专门负责管理直播间观众信息的模块。通过 `LiveAudienceStore`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/375630bef51c11f0a760525400074c32.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](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveUserInfo-class.html)</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >代表一个观众（用户）的基础信息模型。它包含了用户的唯一标识 (`userID`)、昵称 (`userName`) 和头像地址 (`avatarURL`)。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >[LiveAudienceState](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceState-class.html)</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >代表观众模块的当前状态。其核心属性 `audienceList` 是一个 `ValueListenable<List<LiveUserInfo>>`，存储了观众列表的快照；`audienceCount` 则代表当前观众总数。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >[LiveAudienceListener](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceListener-class.html)</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >代表观众动态的实时事件监听器。包含 `onAudienceJoined`（观众加入）和 `onAudienceLeft`（观众离开）两个回调，用于实现对观众列表的增量更新。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >[LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html)</td>
+
+<td rowspan="1" colSpan="1" >`class`</td>
+
+<td rowspan="1" colSpan="1" >这是与观众列表功能交互的核心管理类。通过它，您可以获取观众列表快照、执行管理操作，并通过 `addLiveAudienceListener` 来接收实时动态。</td>
+</tr>
+</table>
+
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 [快速接入](https://write.woa.com/document/197478016886185984) 集成 **AtomicXCore**，完成接入。
+
+### 步骤2：初始化并获取观众列表
+
+获取一个与当前直播间 liveId 绑定的 `LiveAudienceStore` 实例，并主动拉取一次当前的观众列表，用于首次展示。
+
+在退出直播间时可通过调用 `AudienceManager` 的 `dispose` 方法回收资源。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+class AudienceManager {
+    final String liveId;
+    late final LiveAudienceStore audienceStore;
+    late LiveAudienceListener _audienceListener;
+    late final VoidCallback _audienceListChangedListener = _onAudienceListChanged;
+    late final VoidCallback _audienceCountChangedListener = _onAudienceCountChanged;
+
+    // 对外暴露【全量】观众列表
+    List<LiveUserInfo> audienceList = [];
+    // 对外暴露观众总数
+    int audienceCount = 0;
+
+    // 状态变更回调
+    Function()? onStateChanged;
+
+    AudienceManager({required this.liveId}) {
+        // 1. 通过 liveId 获取 LiveAudienceStore 的实例
+        audienceStore = LiveAudienceStore.create(liveId);
+
+        // 2. 订阅状态和事件
+        _subscribeToAudienceState();
+        _subscribeToAudienceEvents();
+
+        // 3. 主动拉取首屏数据
+        fetchInitialAudienceList();
+    }
+
+    /// 主动获取一次观众列表快照
+    Future<void> fetchInitialAudienceList() async {
+        final result = await audienceStore.fetchAudienceList();
+        if (result.isSuccess) {
+            print("首次拉取观众列表成功");
+            // 成功后，数据会通过下面的 state 订阅通道自动更新
+        } else {
+            print("首次拉取观众列表失败: ${result.errorMessage}");
+        }
+    }
+
+    void dispose() {
+        audienceStore.liveAudienceState.audienceList.removeListener(_audienceListChangedListener);
+        audienceStore.liveAudienceState.audienceCount.removeListener(_audienceCountChangedListener);
+        audienceStore.removeLiveAudienceListener(_audienceListener);
+    }
+}
+```
+
+观众列表等 `state` 订阅将在下一步骤详细讲解。
+
+### 步骤3：监听观众列表状态与实时动态
+
+订阅 `audienceStore` 的 `liveAudienceState` 和 `LiveAudienceListener`，以接收全量列表快照和实时的观众进出事件，从而驱动 UI 更新。
+``` java
+extension AudienceManagerSubscription on AudienceManager {
+    /// 订阅 state，用于获取观众总数和列表快照
+    void _subscribeToAudienceState() {
+        // 监听观众列表变化
+        audienceStore.liveAudienceState.audienceList.addListener(_audienceListChangedListener);
+        // 监听观众人数变化
+        audienceStore.liveAudienceState.audienceCount.addListener(_audienceCountChangedListener);
+    }
+
+    void _onAudienceListChanged() {
+        // audienceList 是一个全量快照
+        audienceList = audienceStore.liveAudienceState.audienceList.value;
+        onStateChanged?.call();
+    }
+
+    void _onAudienceCountChanged() {
+        // audienceCount 是实时总数
+        audienceCount = audienceStore.liveAudienceState.audienceCount.value;
+        onStateChanged?.call();
+    }
+
+    /// 订阅 event，用于处理观众的实时进出
+    void _subscribeToAudienceEvents() {
+        _audienceListener = LiveAudienceListener(
+            onAudienceJoined: (audience) {
+                print("观众 ${audience.userName} 加入了直播间");
+                // 增量更新：在当前列表末尾添加新观众
+                if (!audienceList.any((a) => a.userID == audience.userID)) {
+                    audienceList.add(audience);
+                    onStateChanged?.call();
+                }
+            },
+            onAudienceLeft: (audience) {
+                print("观众 ${audience.userName} 离开了直播间");
+                // 增量更新：从当前列表中移除离开的观众
+                audienceList.removeWhere((a) => a.userID == audience.userID);
+                onStateChanged?.call();
+            },
+        );
+        audienceStore.addLiveAudienceListener(_audienceListener);
+    }
+}
+```
+
+### 步骤4：管理观众（踢人与设置管理员）
+
+作为主播或管理员，对直播间内的观众进行管理操作。
+
+#### 4.1 将观众踢出直播间
+
+调用 `kickUserOutOfRoom` 接口可以将指定用户请出直播间。
+``` java
+extension AudienceManagerActions on AudienceManager {
+    Future<void> kick(String userId) async {
+        final result = await audienceStore.kickUserOutOfRoom(userId);
+        if (result.isSuccess) {
+            print("成功将用户 $userId 踢出房间");
+            // 踢出成功后，您会收到 onAudienceLeft 事件
+        } else {
+            print("踢出用户 $userId 失败: ${result.errorMessage}");
+        }
+    }
+}
+```
+
+#### 4.2 设置/撤销管理员
+
+通过 `setAdministrator` 和 `revokeAdministrator` 接口可以管理用户的管理员身份。
+``` java
+extension AudienceManagerAdmin on AudienceManager {
+    /// 将用户设为管理员
+    Future<void> promoteToAdmin(String userId) async {
+        final result = await audienceStore.setAdministrator(userId);
+        if (result.isSuccess) {
+            print("成功将用户 $userId 设为管理员");
+        }
+    }
+
+    /// 撤销用户的管理员身份
+    Future<void> revokeAdmin(String userId) async {
+        final result = await audienceStore.revokeAdministrator(userId);
+        if (result.isSuccess) {
+            print("成功撤销用户 $userId 的管理员身份");
+        }
+    }
+}
+```
+
+## 功能进阶
+
+### 在弹幕区展示观众入场欢迎语
+
+当有新观众进入直播间时，弹幕/聊天区域会在本地自动显示一条欢迎消息，例如："欢迎 [用户昵称] 进入直播间"。
+
+#### 实现方式
+
+我们通过订阅 `LiveAudienceStore` 的观众加入事件（`onAudienceJoined`）来获取新观众加入的实时通知。一旦事件触发，我们便提取出新观众的昵称信息，然后立即调用 `BarrageStore` 的本地插入接口 `appendLocalTip`。
+
+在退出直播间时可通过调用 `LiveRoomManager` 的 `dispose` 方法回收资源。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+class LiveRoomManager {
+    final String liveId;
+    late LiveAudienceListener _welcomeListener;
+
+    LiveRoomManager({required this.liveId}) {
+        _setupWelcomeMessageFlow();
+    }
+
+    void _setupWelcomeMessageFlow() {
+        // 1. 获取 LiveAudienceStore 的实例
+        final audienceStore = LiveAudienceStore.create(liveId);
+
+        // 2. 获取 BarrageStore 的实例 (得益于内部机制，这会是同一个实例)
+        final barrageStore = BarrageStore.create(liveId);
+
+        // 3. 订阅观众事件
+        _welcomeListener = LiveAudienceListener(
+            onAudienceJoined: (audience) {
+                // 4. 创建一条本地提示消息
+                final welcomeTip = Barrage(
+                    messageType: BarrageType.text,
+                    textContent: "欢迎 ${audience.userName} 进入直播间！",
+                );
+
+                // 5. 调用 BarrageStore 的接口将其插入弹幕列表
+                barrageStore.appendLocalTip(welcomeTip);
+            },
+        );
+        audienceStore.addLiveAudienceListener(_welcomeListener);
+    }
+
+    void dispose() {
+        final audienceStore = LiveAudienceStore.create(liveId);
+        audienceStore.removeLiveAudienceListener(_welcomeListener);
+    }
+}
+```
+
+## API 文档
+
+关于 [LiveAudienceStore](https://tencent-rtc.github.io/TUIKit_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html) 及其相关类的所有公开接口、属性和方法的详细信息，请参考 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Flutter/index.html) 框架的官方 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" >**LiveCoreWidget**</td>
+
+<td rowspan="1" colSpan="1" >直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreWidget-class.html)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**LiveCoreController**</td>
+
+<td rowspan="1" colSpan="1" >LiveCoreWidget 的控制器：用于设置直播 ID、控制预览等操作。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_Flutter/api_view_live_live_core_widget/LiveCoreController-class.html)</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_Flutter/api_live_live_audience_store/LiveAudienceStore-class.html)</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_Flutter/api_barrage_barrage_store/api_barrage_barrage_store-library.html)</td>
+</tr>
+</table>
+
+
+## 常见问题
+
+### `LiveAudienceState` 中的在线人数（`audienceCount`）是如何更新的？时机和频率是怎样的？
+
+`audienceCount` 的更新并非总是实时的，其机制如下：
+- **主动进出房间**：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在 `LiveAudienceState` 中观察到 `audienceCount` 的变化。
+
+- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
+
+- **更新机制与频率控制：**
+
+  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
+
+  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。
+
+  - **关键点：**在"弹幕风暴"或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
+
+
+      **这对开发者意味着什么？**
+
+
+      `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。