@tencentcloud/sdk-mcp 1.6.8 → 1.7.0

package/resource/knowledge/livekit/best-practice/common/audience-leave-live.md

@@ -0,0 +1,81 @@
+---
+title: 语聊房观众离房与麦位状态说明
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [语聊房, 观众, 上麦, 下麦, leaveLive, leaveSeat, 退出, 麦位, 重新上麦, VoiceRoom]
+version_range: ">=2.0.0"
+---
+
+# 语聊房观众离房与麦位状态说明
+
+## 1. 核心结论
+
+- 语聊房观众在麦上调用 `leaveLive` 退出后，会自动下麦。
+- 退出后再进房，**不在麦上**，需要重新上麦。
+- 上麦方式取决于 `seatMode`：
+  - `seatMode = FREE`：直接调用 `takeSeat` 即可上麦。
+  - `seatMode = APPLY`：需调用 `applyForSeat` 发起上麦申请，房主/管理员同意后才上麦。
+- `leaveLive` **不需要**先调用 `leaveSeat`，退出会自动下麦。
+- 三端（Android/iOS/Flutter）行为一致。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `leaveLive` | 退出语聊房 | 退出房间，自动下麦 |
+| `leaveSeat` | 主动下麦 | 主动下麦时使用；`leaveLive` 退出时会自动下麦，无需先调用 |
+| `takeSeat` | 自由上麦（`seatMode = FREE`） | 自由模式下重新进房后直接调用上麦 |
+| `applyForSeat` | 申请上麦（`seatMode = APPLY`） | 申请模式下需发起申请，房主/管理员审批通过后上麦 |
+| `seatMode` | 麦位模式 | `FREE`：自由上麦；`APPLY`：需申请审批 |
+| 麦位状态 | 是否在麦上 | `leaveLive` 后清空，重新进房需重新上麦 |
+
+## 3. 机制/时序
+
+观众在麦上调用 `leaveLive` -> 自动下麦（无需先 `leaveSeat`）-> 退出房间 -> 重新进房 -> 麦位状态为空，不在麦上 -> 根据 `seatMode` 选择上麦方式：
+
+- `seatMode = FREE`：调用 `takeSeat(seatIndex)` 直接上麦。
+- `seatMode = APPLY`：调用 `applyForSeat(seatIndex)` 发起申请，等待房主/管理员审批。
+
+## 4. 标准用法
+
+```javascript
+// 三端 API 一致，仅语言风格略有差异（Android Kotlin / iOS Swift / Flutter Dart）
+// 1. 直接退出语聊房（会自动下麦，无需先 leaveSeat）
+liveListStore.leaveLive();
+
+// 2. 重新进房后，根据 seatMode 选择上麦方式
+// seatMode = FREE 时：直接上麦
+liveSeatStore.takeSeat(seatIndex);
+
+// seatMode = APPLY 时：申请上麦（需房主/管理员同意）
+liveSeatStore.applyForSeat(seatIndex);
+```
+
+## 5. 结果判定
+
+- `leaveLive` 后，当前用户自动下麦。
+- 重新进房后，`LiveSeatStore.seatList` 中不含该用户。
+- `seatMode = FREE`：调用 `takeSeat` 成功后回到麦上。
+- `seatMode = APPLY`：调用 `applyForSeat` 后等待审批，审批通过后回到麦上。
+
+## 6. 常见误区
+
+- 误区 1：退出前先调用 `leaveSeat`（不需要，`leaveLive` 会自动下麦）。
+- 误区 2：认为重新进房后还在麦上（需要重新上麦）。
+- 误区 3：担心 `leaveLive` 未下麦导致麦位残留（自动下麦，无残留）。
+- 误区 4：`seatMode = APPLY` 时直接调用 `takeSeat`（应使用 `applyForSeat`，否则会报错或无效）。
+
+## 7. 问题定义（检索辅助，极简）
+
+语聊房观众在麦上退出房间后是否自动下麦、重新进房是否还在麦上、`leaveLive` 是否需要先 `leaveSeat`、不同 `seatMode`（FREE/APPLY）下如何重新上麦（`takeSeat` vs `applyForSeat`）。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 语聊房退出后会下麦吗？
+- 重新进房还要上麦吗？
+- `leaveLive` 之前要调用 `leaveSeat` 吗？
+- 语聊房观众退出房间麦位会清空吗？
+- 进房后怎么重新上麦？
+- `seatMode = APPLY` 时怎么上麦？
+- `takeSeat` 和 `applyForSeat` 什么时候用？

package/resource/knowledge/livekit/best-practice/common/voice-room-no-audio-troubleshoot.md

@@ -0,0 +1,100 @@
+---
+title: 语聊房观众听不到主播说话排查指南
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [语聊房, 听不到声音, 没声音, 排查, LiveSeatStore, DeviceStore, takeSeat, openLocalMicrophone, unmuteMicrophone, LoginStore, joinLive, seatList, microphoneStatus, LiveSeatState, DeviceState]
+version_range: ">=2.0.0"
+---
+
+# 语聊房观众听不到主播说话排查指南
+
+## 1. 核心结论
+
+- 观众听不到主播说话时，按「主播侧 → 观众侧」顺序排查，从房间/上麦/麦克风/静音/登录/进房逐层检查状态。
+- 主播侧：确认主播在麦上（`seatList`）、麦克风已打开（`DeviceStore.microphoneStatus`）、未静音（`userInfo.microphoneStatus`）。
+- 观众侧：确认已登录（`loginStatus == LOGIN`）、已进房（`currentLive`）、手机音量正常、主播 `microphoneStatus` 正常。
+- 三端（Android/iOS/Flutter）API 与状态结构一致，排查流程通用。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `LiveSeatStore` | 麦位管理 | 提供 `seatList`，查看其中是否有主播信息判断主播是否在麦上 |
+| `LiveSeatStore.seatList` | 麦位列表 | 查看其中是否有主播信息；主播 item 的 `userInfo.microphoneStatus` 判断是否静音 |
+| `takeSeat` | 上麦 | 主播不在麦上时调用 |
+| `DeviceStore` | 设备管理 | 提供 `DeviceState`，查看 `microphoneStatus` 判断麦克风是否打开 |
+| `DeviceState.microphoneStatus` | 麦克风开关状态 | 判断主播是否打开麦克风 |
+| `openLocalMicrophone` | 打开麦克风 | 麦克风关闭时调用 |
+| `unmuteMicrophone` | 恢复发布音频 | 主播静音时调用 |
+| `LoginStore` | 登录管理 | 提供 `loginState.loginStatus`，`LOGIN` 表示已登录 |
+| `LiveListStore` | 直播间管理 | 提供 `LiveListState.currentLive`，判断是否进房成功 |
+| `joinLive` | 进入房间 | 观众未进房时调用 |
+
+## 3. 机制/时序
+
+### 主播侧排查（按序）
+
+1. 是否在麦上：查看 `LiveSeatStore.seatList` 是否含主播信息，否则调用 `takeSeat` 上麦。
+2. 麦克风是否打开：查看 `DeviceState.microphoneStatus`，关闭则调用 `openLocalMicrophone`。
+3. 是否静音：查看 `seatList` 主播 item 的 `userInfo.microphoneStatus`，关闭则调用 `unmuteMicrophone`。
+
+### 观众侧排查（按序）
+
+1. 是否已登录：查看 `loginState.loginStatus` 是否为 `LOGIN`。
+2. 是否进房成功：查看 `LiveListState.currentLive` 是否为当前直播间，否则调用 `joinLive` 进房。
+3. 手机音量是否正常：确认系统音量可听到声音。
+
+## 4. 标准用法
+
+按以下流程逐项排查，确认状态后对应处理：
+
+```text
+观众听不到主播说话
+│
+├── 主播侧排查
+│   ├── 1. 是否在麦上？  → 否 → takeSeat 上麦
+│   │      查看 LiveSeatStore.seatList
+│   ├── 2. 麦克风是否打开？ → 否 → openLocalMicrophone
+│   │      查看 DeviceState.microphoneStatus
+│   └── 3. 是否静音？ → 是 → unmuteMicrophone
+│          查看 seatList 主播 userInfo.microphoneStatus
+│
+└── 观众侧排查
+    ├── 1. 是否已登录？ → 否 → 登录
+    │      查看 loginState.loginStatus == LOGIN
+    ├── 2. 是否进房？ → 否 → joinLive 进房
+    │      查看 LiveListState.currentLive
+    └── 3. 手机音量正常？ → 否 → 调整音量
+```
+
+## 5. 结果判定
+
+- 主播 `LiveSeatStore.seatList` 含主播信息：在麦上，可推流。
+- `DeviceState.microphoneStatus` 打开：麦克风已采集。
+- `userInfo.microphoneStatus` 打开：未静音，音频正常发布。
+- 观众 `loginStatus == LOGIN`：已登录。
+- `LiveListState.currentLive` 为当前直播间：已进房。
+- 以上全部满足后观众仍听不到声音：检查手机音量或联系开发人员。
+
+## 6. 常见误区
+
+- 误区 1：只排查观众侧，忽略主播侧的上麦/麦克风/静音状态。
+- 误区 2：混淆 `DeviceState.microphoneStatus`（设备开关）与 `userInfo.microphoneStatus`（是否静音）——前者是本地设备采集，后者是远端状态。
+- 误区 3：主播未上麦就推流（上麦是推流前提）。
+- 误区 4：观众未进房（`currentLive` 不对）就认为主播无声。
+- 误区 5：跳过登录状态检查，直接排查音频链路。
+
+## 7. 问题定义（检索辅助，极简）
+
+语聊房观众听不到主播说话时，如何按主播侧（上麦/麦克风/静音）和观众侧（登录/进房/音量）逐层排查并定位问题。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 语聊房观众听不到主播声音怎么办？
+- 语聊房麦克风没声音怎么排查？
+- 主播在麦上但观众听不到声音？
+- `microphoneStatus` 怎么看主播是否静音？
+- 语聊房进房后没声音？
+- 语聊房如何判断主播是否上麦？
+- 观众听不到声音先排查什么？

package/resource/knowledge/livekit/best-practice/common/voice-room-seat-list-change.md

@@ -0,0 +1,65 @@
+---
+title: 语聊房麦位麦克风状态同步说明
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [语聊房, 麦位, 麦克风状态, 开麦, 关麦, userMicrophoneStatus, SeatListChanged, muteMicrophone, unmuteMicrophone, closeMicrophone, openMicrophone, 同步]
+version_range: ">=2.0.0"
+---
+
+# 语聊房麦位麦克风状态同步说明
+
+## 1. 核心结论
+
+- 主播侧和观众侧通过 **`SeatListChanged`** 监听麦位上麦克风状态（`userMicrophoneStatus`）变化。
+- `userMicrophoneStatus` 取值：`0` 开麦，`1` 关麦（自己关麦，自己可打开），`2` 关麦（管理员操作关麦，自己打不开）。
+- `userMicrophoneStatus` 状态只能由**主播或上麦后的观众**通过 `mute/unmute` 或 `close/open` 相关 API 触发改变。
+- 观众侧仅监听状态，**不需要**主动调用 `mute/unmute` 或 `close/open` 去修改 `userMicrophoneStatus`。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `userMicrophoneStatus` | 麦位麦克风开关状态 | `0` 开麦；`1` 关麦（自己关麦，自己可打开）；`2` 关麦（管理员操作关麦，自己打不开） |
+| `SeatListChanged` | 麦位列表变更 | 主播侧和观众侧通过它监听 `userMicrophoneStatus` 变化，SDK 自动同步 |
+| `muteMicrophone` / `unmuteMicrophone` | 静音 / 取消静音 | 主播或上麦观众调用，触发 `userMicrophoneStatus` 变化 |
+| `closeMicrophone` / `openMicrophone` | 关闭 / 打开麦克风 | 主播或上麦观众调用，触发 `userMicrophoneStatus` 变化 |
+| 观众侧 | 只读状态 | 仅监听状态，不主动调用 `mute/unmute` 或 `close/open` |
+
+## 3. 机制/时序
+
+主播或上麦观众调用 `mute/unmute` 或 `close/open` 相关 API -> 触发 `userMicrophoneStatus` 变化 -> SDK 触发 `SeatListChanged`，自动同步到各端 -> 主播侧和观众侧都通过 `SeatListChanged` 收到更新后的麦位状态。
+
+`userMicrophoneStatus` 的改变只能由主播或上麦观众通过 `mute/unmute` 或 `close/open` API 触发；观众侧仅监听状态，不主动修改。
+
+## 4. 标准用法
+
+主播侧和观众侧监听 `SeatListChanged`，根据 `userMicrophoneStatus` 更新 UI 即可。
+主播或上麦后的观众通过 `mute/unmute` 或 `close/open` API 改变麦克风状态，SDK 自动同步到各端。
+
+## 5. 结果判定
+
+- 主播或上麦后的观众调用 `mute/unmute` 或 `close/open` 后，各端 `SeatListChanged` 中 `userMicrophoneStatus` 同步更新。
+- `userMicrophoneStatus = 0`：开麦。
+- `userMicrophoneStatus = 1`：关麦（自己关麦，自己可重新打开）。
+- `userMicrophoneStatus = 2`：关麦（管理员操作关麦，自己打不开）。
+- 观众侧无需主动调用 `mute/unmute` 或 `close/open`，状态由 SDK 自动同步。
+
+## 6. 常见误区
+
+- 误区 1：观众调用 `mute/unmute` 或 `close/open` 去操作 `userMicrophoneStatus`（不需要，状态由 SDK 自动同步，观众侧只读）。
+- 误区 2：认为 `userMicrophoneStatus = 1` 和 `2` 含义相同（`1` 是自己关麦可自行打开，`2` 是管理员关麦自己打不开）。
+- 误区 3：认为 `userMicrophoneStatus` 可以由观众端主动改变（只能由主播或上麦观众通过 `mute/unmute` 或 `close/open` 触发）。
+
+## 7. 问题定义（检索辅助，极简）
+
+语聊房麦位麦克风状态（`userMicrophoneStatus`）各取值含义、如何通过 `SeatListChanged` 同步到主播侧和观众侧，以及哪些角色通过哪些 API 能改变该状态。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 语聊房观众看不到主播开麦状态怎么办？
+- `userMicrophoneStatus` 0/1/2 分别代表什么？
+- `SeatListChanged` 麦位麦克风状态怎么同步？
+- 谁可以改变 `userMicrophoneStatus`？
+- 观众要调用 `muteMicrophone` 更新开麦状态吗？
+- 管理员关麦后用户能自己打开吗？

package/resource/knowledge/livekit/best-practice/flutter/voice-room-anchor-start.md

@@ -0,0 +1,126 @@
+---
+title: 语聊房房主创建房间并开播推流（Flutter）
+product: live
+frameworks: [flutter]
+scope: platform_specific
+tags: [语聊房, 房主, 开播, 推流, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, TakeSeatMode, Flutter, AtomicXCore]
+version_range: ">=2.0.0"
+---
+
+# 语聊房房主创建房间并开播推流（Flutter）
+
+## 1. 核心结论
+
+- 语聊房开播流程：构造 `LiveInfo`（含 `liveID`、`seatTemplate`、`seatMode`、`keepOwnerOnSeat`），调用 `createLive` 创建房间；成功后调用 `openLocalMicrophone` 采集音频并发布推流，房间内用户即可听到主播声音。
+- `liveID` 必填；`keepOwnerOnSeat` 设为 `true` 时主播进房后自动上麦（上麦是推流的前提，只有上麦的用户才能在房间内推音频流）。
+- `seatTemplate` 设为语聊房模板 `AudioSalon(n)`，n 为套餐支持的最大麦位数或小于该值的麦位数。
+- `seatMode` 设置上麦模式（如 `TakeSeatMode.apply` 申请上麦）。
+- `muteMicrophone` 暂停发布本机音频流；`unmuteMicrophone` 恢复发布本机音频流。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `LiveInfo` | 房间信息 | Dart 构造器 `LiveInfo({liveID, liveName, seatTemplate, seatMode, keepOwnerOnSeat})` |
+| `liveID` | 房间 ID | `createLive` 必填参数 |
+| `liveName` | 房间名称 | 创建房间的展示名称 |
+| `seatTemplate` | 麦位布局模板 | 语聊房使用 `AudioSalon(n)`，n ≤ 套餐最大麦位数 |
+| `seatMode` | 上麦模式 | 如 `TakeSeatMode.apply` 申请上麦 |
+| `keepOwnerOnSeat` | 房主自动上麦 | 设为 `true`，主播进房后自动上麦 |
+| `createLive(liveInfo)` | 创建房间（开播） | 传入 `LiveInfo`，返回 `Future<result>` 异步处理 |
+| `result.isSuccess` | 是否成功 | `true` 为创建成功 |
+| `result.message` | 错误信息 | 失败时返回错误描述 |
+| `openLocalMicrophone` | 采集音频并发布 | 打开本地麦克风，发布音频流到房间 |
+| `muteMicrophone` | 暂停发布音频 | 已打开麦克风时，暂停发布本地音频流 |
+| `unmuteMicrophone` | 恢复发布音频 | 已打开麦克风时，恢复发布本地音频流 |
+
+## 3. 机制/时序
+
+构造 `LiveInfo`（`liveID` 必填，`seatTemplate=AudioSalon(n)`，`seatMode` 按需设置，`keepOwnerOnSeat=true`） -> `await createLive(liveInfo)` -> `result.isSuccess` 为 `true`，房主默认自动上麦 -> 调用 `openLocalMicrophone` 采集并发布音频 -> 房间内用户听到主播声音。
+
+上麦是推流的前提：`keepOwnerOnSeat=true` 保证房主上麦后才能推音频流。`muteMicrophone` / `unmuteMicrophone` 用于推流过程中的暂停/恢复。
+
+## 4. 标准用法
+
+1. 构造 `LiveInfo`：设置 `liveID`、`seatTemplate`、`seatMode`、`keepOwnerOnSeat`。
+2. `await _liveListStore.createLive(liveInfo)` 发起开播。
+3. 判断 `result.isSuccess`，成功后调用 `openLocalMicrophone` 采集并发布推流。
+4. 需要暂停/恢复推流时调用 `muteMicrophone` / `unmuteMicrophone`。
+
+```dart
+class _YourAnchorPageState extends State<YourAnchorPage> {
+  // ... 其他代码 ...
+  final String _liveID = "test_voice_room_001";
+
+  @override
+  void initState() {
+    super.initState();
+    // ... 其他代码 ...
+
+    // 开始语聊
+    _startLive();
+  }
+
+  Future<void> _startLive() async {
+    // 1. 准备 LiveInfo 对象
+    final liveInfo = LiveInfo(
+      // 2. 设置房间 id
+      liveID: _liveID,
+      // 3. 设置房间名称
+      liveName: "test 语聊房",
+      // 4. 设置语聊房布局模板（传入 9 即代表有 9 个麦位）
+      seatTemplate: AudioSalon(9),
+      // 5. 设置上麦模式，例如申请上麦
+      seatMode: TakeSeatMode.apply,
+      // 6. 设置主播开播后自动上麦
+      keepOwnerOnSeat: true,
+    );
+
+    // 7. 调用 createLive 开始直播
+    final result = await _liveListStore.createLive(liveInfo);
+
+    if (result.isSuccess) {
+      debugPrint("Response startLive onSuccess");
+      // 8. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+      _liveSeatStore.openLocalMicrophone();
+    } else {
+      debugPrint("Response startLive onError: ${result.message}");
+    }
+  }
+}
+```
+
+## 5. 结果判定
+
+- `result.isSuccess == true`：房间创建成功，房主默认自动上麦。
+- `openLocalMicrophone` 后：房间内用户能听到主播声音。
+- `muteMicrophone` 后：本机音频暂停发布；`unmuteMicrophone` 后恢复。
+- `keepOwnerOnSeat` 未设 `true`：主播未自动上麦，无法推流。
+- `result.isSuccess == false`：开播失败，`result.message` 为错误描述。
+
+## 6. 常见误区
+
+- 误区 1：跳过 `createLive` 直接调用 `openLocalMicrophone`（未创建房间无法推流）。
+- 误区 2：`keepOwnerOnSeat` 未设 `true`，主播未上麦，推流不生效。
+- 误区 3：`seatTemplate` 未设置或 n 超过套餐最大麦位数。
+- 误区 4：混淆 `muteMicrophone`（暂停发布音频流）与关闭麦克风（停止采集）。
+- 误区 5：`liveID` 重复使用（必须全局唯一，否则创建失败）。
+- 误区 6：`AudioSalon(9)` 是构造器形式（非枚举），`seatMode` 用 `TakeSeatMode.apply`（Dart 枚举小写）。
+
+## 7. 问题定义（检索辅助，极简）
+
+Flutter 语聊房房主需要按正确顺序创建房间并开播推流，了解 `createLive`、`openLocalMicrophone`、`muteMicrophone`、`unmuteMicrophone` 的调用时机与参数含义。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Flutter 语聊房房主怎么开播？
+- Flutter `createLive` 和 `openLocalMicrophone` 的调用顺序是什么？
+- Flutter 主播怎么上麦推流？
+- `keepOwnerOnSeat` 参数有什么作用？
+- `seatTemplate` 怎么设置语聊房 `AudioSalon` 模板？
+- Flutter `muteMicrophone` 和 `unmuteMicrophone` 区别是什么？
+- 语聊房创建房间后如何推音频流？
+
+## 9. 参考来源（可选）
+
+- LiveKit Flutter 文档：`https://cloud.tencent.com/document/product/647/127694`

package/resource/knowledge/livekit/best-practice/ios/voice-room-anchor-start.md

@@ -0,0 +1,130 @@
+---
+title: 语聊房房主创建房间并开播推流（iOS）
+product: live
+frameworks: [ios]
+scope: platform_specific
+tags: [语聊房, 房主, 开播, 推流, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, iOS, Swift, AtomicXCore]
+version_range: ">=2.0.0"
+---
+
+# 语聊房房主创建房间并开播推流（iOS）
+
+## 1. 核心结论
+
+- 语聊房开播流程：构造 `LiveInfo`（含 `liveID`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode`），调用 `createLive` 创建房间；成功后调用 `openLocalMicrophone` 采集音频并发布推流，房间内用户即可听到主播声音。
+- `liveID` 必填；`keepOwnerOnSeat` 设为 `true` 时主播进房后自动上麦（上麦是推流的前提，只有上麦的用户才能在房间内推音频流）。
+- `seatTemplate` 设为语聊房模板 `SeatLayoutTemplate.AudioSalon(seatCount: n)`，n 为套餐支持的最大麦位数或小于该值的麦位数。
+- `seatMode` 设置上麦模式（如 `.apply` 申请上麦）。
+- `muteMicrophone` 暂停发布本机音频流；`unmuteMicrophone` 恢复发布本机音频流。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `LiveInfo` | 房间信息 | 包含 `liveID`、`liveName`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode` 等参数 |
+| `liveID` | 房间 ID | `createLive` 必填参数 |
+| `liveName` | 房间名称 | 创建房间的展示名称 |
+| `seatTemplate` | 麦位布局模板 | 语聊房使用 `SeatLayoutTemplate.AudioSalon(seatCount: n)`，n ≤ 套餐最大麦位数 |
+| `keepOwnerOnSeat` | 房主自动上麦 | 设为 `true`，主播进房后自动上麦 |
+| `seatMode` | 上麦模式 | 如 `.apply` 申请上麦 |
+| `createLive(liveInfo)` | 创建房间（开播） | 传入 `LiveInfo`，返回 `Result` 异步处理 |
+| `openLocalMicrophone` | 采集音频并发布 | 打开本地麦克风，发布音频流到房间 |
+| `muteMicrophone` | 暂停发布音频 | 已打开麦克风时，暂停发布本地音频流 |
+| `unmuteMicrophone` | 恢复发布音频 | 已打开麦克风时，恢复发布本地音频流 |
+
+## 3. 机制/时序
+
+构造 `LiveInfo`（`liveID` 必填，`seatTemplate=AudioSalon(n)`，`keepOwnerOnSeat=true`，`seatMode` 按需设置） -> 调用 `createLive` 创建房间 -> `case .success` 回调触发，房主默认自动上麦 -> 调用 `openLocalMicrophone` 采集并发布音频 -> 房间内用户听到主播声音。
+
+上麦是推流的前提：`keepOwnerOnSeat=true` 保证房主上麦后才能推音频流。`muteMicrophone` / `unmuteMicrophone` 用于推流过程中的暂停/恢复。
+
+## 4. 标准用法
+
+1. 构造 `LiveInfo`：设置 `liveID`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode`。
+2. 调用 `createLive(liveInfo)`，在 `switch result` 中处理成功/失败。
+3. `case .success` 后调用 `openLocalMicrophone` 采集音频并发布推流。
+4. 需要暂停/恢复推流时调用 `muteMicrophone` / `unmuteMicrophone`。
+
+```swift
+import UIKit
+import AtomicXCore
+
+class YourAnchorViewController: UIViewController {
+    // ... 其他代码 ...
+    private let liveID = "test_voice_room_001"
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // ... 其他代码 ...
+
+        // 开始语聊
+        startLive()
+    }
+
+    private func startLive() {
+        // 1. 准备 LiveInfo 对象
+        var liveInfo = LiveInfo()
+
+        // 2. 设置房间 id
+        liveInfo.liveID = liveID
+        // 3. 设置房间名称
+        liveInfo.liveName = "test 语聊房"
+        // 4. 设置语聊房布局模板（传入 9 即代表有 9 个麦位）
+        liveInfo.seatTemplate = SeatLayoutTemplate.AudioSalon(seatCount: 9)
+
+        // 5. 设置主播开播后自动上麦
+        liveInfo.keepOwnerOnSeat = true
+
+        // 6. 设置上麦模式，例如申请上麦
+        liveInfo.seatMode = .apply
+
+        // 7. 调用 createLive 开始直播
+        liveListStore.createLive(liveInfo) { [weak self] result in
+            guard let self = self else { return }
+            switch result {
+            case .success(let liveInfo):
+                print("Response startLive onSuccess")
+                // 8. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+                liveSeatStore.openLocalMicrophone(completion: nil)
+            case .failure(let errorInfo):
+                print("Response startLive onError: \(errorInfo.message)")
+            }
+        }
+    }
+}
+```
+
+## 5. 结果判定
+
+- `case .success` 回调触发：房间创建成功，房主默认自动上麦。
+- `openLocalMicrophone` 后：房间内用户能听到主播声音。
+- `muteMicrophone` 后：本机音频暂停发布；`unmuteMicrophone` 后恢复。
+- `keepOwnerOnSeat` 未设 `true`：主播未自动上麦，无法推流。
+- `case .failure(let errorInfo)` 回调触发：开播失败，`errorInfo.message` 为错误描述。
+
+## 6. 常见误区
+
+- 误区 1：跳过 `createLive` 直接调用 `openLocalMicrophone`（未创建房间无法推流）。
+- 误区 2：`keepOwnerOnSeat` 未设 `true`，主播未上麦，推流不生效。
+- 误区 3：`seatTemplate` 未设置或 `seatCount` 超过套餐最大麦位数。
+- 误区 4：混淆 `muteMicrophone`（暂停发布音频流）与关闭麦克风（停止采集）。
+- 误区 5：`liveID` 重复使用（必须全局唯一，否则创建失败）。
+- 误区 6：忘记 `[weak self]`（避免循环引用导致内存泄漏），且 `switch result` 的 `success`/`failure` 两个分支都需处理。
+
+## 7. 问题定义（检索辅助，极简）
+
+iOS 语聊房房主需要按正确顺序创建房间并开播推流，了解 `createLive`、`openLocalMicrophone`、`muteMicrophone`、`unmuteMicrophone` 的调用时机与参数含义。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- iOS 语聊房房主怎么开播？
+- iOS `createLive` 和 `openLocalMicrophone` 的调用顺序是什么？
+- iOS 主播怎么上麦推流？
+- `keepOwnerOnSeat` 参数有什么作用？
+- `seatTemplate` 怎么设置语聊房 `AudioSalon` 模板？
+- iOS `muteMicrophone` 和 `unmuteMicrophone` 区别是什么？
+- 语聊房创建房间后如何推音频流？
+
+## 9. 参考来源（可选）
+
+- LiveKit iOS 文档：`https://cloud.tencent.com/document/product/647/124969`

package/resource/knowledge/push/config/react-native.md

@@ -164,3 +164,4 @@ p8 证书：p8 证书没有到期日期，因此您无需担心证书过期。
 【荣耀】
 
 【Google FCM】
+

package/resource/knowledge/push/config/unity.md

@@ -158,3 +158,4 @@ p8 证书：p8 证书没有到期日期，因此您无需担心证书过期。
 【荣耀】
 
 【Google FCM】
+

package/resource/knowledge/push/config/unreal-engine.md

@@ -158,3 +158,4 @@ p8 证书：p8 证书没有到期日期，因此您无需担心证书过期。
 【荣耀】
 
 【Google FCM】
+

package/resource/knowledge/push/integration/android.md

@@ -2,7 +2,7 @@
 
 ## 前提条件
 
-请确认已开通 Push 服务并按需完成 **Android 厂商配置**（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / Google FCM），获取到了下列信息：
+请确认已 开通 Push 服务 并按需完成 **Android 厂商配置**（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / Google FCM），获取到了下列信息：
 
 |**资源**|**获取位置**|**用途**|
 |---------|---------|---------|
@@ -19,7 +19,7 @@
 
 ## AI 集成
 
-通过 npx 安装 [@tencent-rtc/trtc-push-skill](https://www.npmjs.com/package/@tencent-rtc/trtc-push-skill/v/1.0.1#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87) 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，你可以直接向 AI 输入“集成 Android 离线推送”“帮我集成 Android TIMPush”等需求，AI 将根据项目类型引导你完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。
+通过 npx 安装 [@tencent-rtc/trtc-push-skill](https://www.npmjs.com/package/@tencent-rtc/trtc-push-skill/v/1.0.1#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87) 到本地 AI IDE 中，辅助完成 TIMPush 离线推送集成。安装后，您可以直接向 AI 输入“集成 Android 离线推送”“帮我集成 Android TIMPush”等需求，AI 将根据项目类型引导您完成环境检测、厂商通道配置、凭据填写、代码接入和验证等步骤。
 
 > **注意：**
 > 使用 Push Skill AI 集成不是全自动流程，依然需要开发者在厂商配置控制台、腾讯云控制台等配置 Push 相关信息。具体的配置方法请参考下文相关章节。
@@ -27,11 +27,11 @@
 
 ## 集成 TIMPush
 
-如果你想手动集成，请按下述操作步骤依次完成放置配置文件、配置 Gradle、补充 Manifest 与混淆。
+如果您想手动集成，请按下述操作步骤依次完成放置配置文件、配置 Gradle、补充 Manifest 与混淆。
 
 ### 下载并添加 TIMPush 配置文件
 
-下载后，将该文件添加到应用模块的 `assets` 目录。推荐存储路径：`app/src/main/assets/timpush-configs.json`，其中 app 是你项目的应用模块，可替换成实际名称。如果工程中没有 `assets` 目录，请在 `src/main/` 下手动创建。
+下载后，将该文件添加到应用模块的 `assets` 目录。推荐存储路径：`app/src/main/assets/timpush-configs.json`，其中 app 是您项目的应用模块，可替换成实际名称。如果工程中没有 `assets` 目录，请在 `src/main/` 下手动创建。
 
 > **注意：**
 > TIMPush 注册推送时会读取该文件中的厂商证书配置，不要放在 MainActivity 同级目录、工程根目录或 res 目录。如果文件缺失或放错目录，SDK 无法获得对应厂商通道配置，可能导致注册或收消息失败。
@@ -46,7 +46,7 @@
 |荣耀|`mcs-services.json`|在荣耀开发者服务平台下载。修改项目、应用信息或开发服务设置后，需要重新下载。|
 |Google FCM|`google-services.json`|在 Firebase 控制台下载。|
 
-推荐放置路径如下（与应用模块的 `build.gradle` / `build.gradle.kts` 同级），其中 app 是你项目的应用模块，可替换成实际名称：
+推荐放置路径如下（与应用模块的 `build.gradle` / `build.gradle.kts` 同级），其中 app 是您项目的应用模块，可替换成实际名称：
 ``` text
 app/mcs-services.json            # 荣耀
 app/google-services.json         # Google FCM
@@ -129,7 +129,7 @@ dependencyResolutionManagement {
 
 【Gradle 7.0 版本】
 
-Gradle 7.0 版本通常使用 Groovy DSL。如你的工程使用 Kotlin DSL，请将单引号改为双引号，`url "..."` 改为 `url = uri("...")`。
+Gradle 7.0 版本通常使用 Groovy DSL。如您的工程使用 Kotlin DSL，请将单引号改为双引号，`url "..."` 改为 `url = uri("...")`。
 1. 在项目级 `build.gradle` 的 `buildscript > repositories` 中添加插件仓库。
 
 ``` groovy
@@ -165,7 +165,7 @@ dependencyResolutionManagement {
 
 【Gradle 7.0 以下版本】
 
-Gradle 7.0 以下版本通常使用 Groovy DSL。如你的工程使用 Kotlin DSL，请将单引号改为双引号，`url "..."` 改为 `url = uri("...")`。
+Gradle 7.0 以下版本通常使用 Groovy DSL。如您的工程使用 Kotlin DSL，请将单引号改为双引号，`url "..."` 改为 `url = uri("...")`。
 
 在项目级 `build.gradle` 的 `buildscript > repositories` 和 `allprojects > repositories` 中添加仓库。
 ``` groovy
@@ -278,7 +278,7 @@ buildscript {
 
 【Gradle 7.0 及以下】
 
-如果你已在上一节「配置 Gradle 仓库」中按照 Gradle 7.0 或 Gradle 7.0 以下示例配置了 `buildscript > repositories` 和 `buildscript > dependencies`，可以跳过本节的项目级插件依赖配置。
+如果您已在上一节「配置 Gradle 仓库」中按照 Gradle 7.0 或 Gradle 7.0 以下示例配置了 `buildscript > repositories` 和 `buildscript > dependencies`，可以跳过本节的项目级插件依赖配置。
 
 如果尚未配置，请回到上一节，根据当前 Gradle 版本补充 `buildscript` 中的仓库和插件 classpath。
 
@@ -300,7 +300,7 @@ plugins {
 }
 ```
 
-如果你的应用级 `build.gradle` 使用 `apply plugin` 写法，也可以写成：
+如果您的应用级 `build.gradle` 使用 `apply plugin` 写法，也可以写成：
 ``` groovy
 apply plugin: 'com.google.gms.google-services'
 apply plugin: 'com.huawei.agconnect'
@@ -319,7 +319,7 @@ plugins {
 }
 ```
 
-如果你的应用级 `build.gradle.kts` 使用 `apply` 写法，也可以写成：
+如果您的应用级 `build.gradle.kts` 使用 `apply` 写法，也可以写成：
 ``` kotlin
 apply(plugin = "com.google.gms.google-services")
 apply(plugin = "com.huawei.agconnect")
@@ -509,7 +509,7 @@ public class App extends Application {
 
     private void registerTIMPush() {
         int sdkAppId = 0; // TODO: Replace with your SDKAppID.
-        String appKey = "你的客户端密钥"; // TODO: Replace with your Push Key.
+        String appKey = "您的客户端密钥"; // TODO: Replace with your Push Key.
 
         TIMPushManager.getInstance().registerPush(this, sdkAppId, appKey, new TIMPushCallback<Object>() {
             @Override
@@ -542,7 +542,7 @@ class App : Application() {
 
     private fun registerTIMPush() {
         val sdkAppId = 0 // TODO: Replace with your SDKAppID.
-        val appKey = "你的客户端密钥" // TODO: Replace with your Push Key.
+        val appKey = "您的客户端密钥" // TODO: Replace with your Push Key.
 
         TIMPushManager.getInstance().registerPush(this, sdkAppId, appKey, object : TIMPushCallback<Any?>() {
             override fun onSuccess(data: Any?) {
@@ -659,7 +659,7 @@ fun loginIMAndRegisterPush(context: Context) {
 
    > **警告：**
    >
-   > 如果你的业务仅使用即时通信 IM 聊天能力，请勿在 IM 登录前先调用 `registerPush`。否则 SDK 可能会按独立推送场景注册 Push 类型账号，并产生对应的 Push DAU。Push DAU 超出套餐额度后，可能会产生额外费用。
+   > 如果您的业务仅使用即时通信 IM 聊天能力，请勿在 IM 登录前先调用 `registerPush`。否则 SDK 可能会按独立推送场景注册 Push 类型账号，并产生对应的 Push DAU。Push DAU 超出套餐额度后，可能会产生额外费用。
    >
 
    **验证**：
@@ -792,7 +792,7 @@ V2TIMManager.getMessageManager().sendMessage(
 
 通过 [V2TIMOfflinePushInfo](https://im.sdk.qcloud.com/doc/zh-cn/classcom_1_1tencent_1_1imsdk_1_1v2_1_1V2TIMOfflinePushInfo.html) 的 `ext` 属性携带跳转参数，再随消息一起发送。`setExt` 接收 `byte[]` 入参，业务自定义的 JSON 字符串需要先转成字节数组。
 
-如果你接入了 TUIKit，TUIKit 内置的消息发送链路会自动用 `OfflinePushExtInfo` 组装 `ext`，无需手动设置。下方示例适用于自行调用 IM SDK 发送消息的场景。
+如果您接入了 TUIKit，TUIKit 内置的消息发送链路会自动用 `OfflinePushExtInfo` 组装 `ext`，无需手动设置。下方示例适用于自行调用 IM SDK 发送消息的场景。
 
 【Java】
 ``` java
@@ -874,7 +874,7 @@ V2TIMManager.getMessageManager().sendMessage(
 
 请在 `Application.onCreate()` 中调用 addPushListener 注册 `TIMPushListener`，并在 onNotificationClicked 中解析 `ext` 后跳转到业务页面。
 
-以下示例只演示解析 `ext` 的核心逻辑，跳转部分用 `TODO` 占位，请按自身业务补充。如果你接入了 TUIKit 并使用 `OfflinePushExtInfo` 组装的 `ext`，可改为 `new Gson().fromJson(ext, OfflinePushExtInfo.class)` 解析后再跳转。
+以下示例只演示解析 `ext` 的核心逻辑，跳转部分用 `TODO` 占位，请按自身业务补充。如果您接入了 TUIKit 并使用 `OfflinePushExtInfo` 组装的 `ext`，可改为 `new Gson().fromJson(ext, OfflinePushExtInfo.class)` 解析后再跳转。
 
 【Java】
 ``` java
@@ -1099,7 +1099,7 @@ pushInfo.setAndroidOPPOChannelID("your_oppo_private_channel_id");
 - 华为/荣耀：测试包签名（debug 或 release）的 SHA-256 必须已在厂商控制台「项目设置 > 常规 > SHA 证书指纹」中添加，指纹不一致会报 `6003: certificate fingerprint error`。
 
 #### 步骤6：确认消息分类和厂商限制
-- 是否超出厂商单日推送限额（如 vivo 运营消息每日限制、小米公信消息限额）。
+- 是否超出厂商单日推送限额（例如 vivo 运营消息每日限制、小米公信消息限额）。
 
 - 是否在夜间发送（部分厂商运营消息夜间不下发）。