@tencentcloud/sdk-mcp 1.6.8 → 1.7.0

package/resource/knowledge/chat/best-practice/miniprogram/audio-message-send.md

@@ -0,0 +1,118 @@
+---
+title: 小程序集成 IM SDK 发送语音消息标准方案
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [audio, voice, recorderManager, createAudioMessage, sendMessage, aac, miniprogram]
+version_range: ">=3.0.0"
+---
+
+# 小程序集成 IM SDK 发送语音消息标准方案
+
+## 1. 核心结论
+
+- 小程序侧应使用微信官方 `RecorderManager` 进行录音，再在 `onStop` 回调中调用 `createAudioMessage` 创建语音消息。
+- 消息创建后通过 `sendMessage` 发送，发送结果以 Promise 成功/失败回调为准。
+- 音频格式使用 `aac` 可实现 IM 全平台（Android、iOS、小程序、Web）互通。
+- 录音参数需显式配置 `duration`、`sampleRate`、`numberOfChannels`、`encodeBitRate`、`format`，并监听 `onError` 处理录音异常。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `wx.getRecorderManager()` | 录音入口 | 获取全局唯一录音管理器实例 |
+| `recordOptions.format` | 音频格式控制 | 设置为 `aac` 可满足跨平台互通 |
+| `recorderManager.onStop(res)` | 录音结果回调 | 在回调中使用 `res` 创建语音消息 |
+| `chat.createAudioMessage({...})` | 创建消息实例 | 生成可上屏、可发送的语音消息对象 |
+| `chat.sendMessage(message)` | 发送消息 | 返回 Promise，`then` 成功、`catch` 失败 |
+
+## 3. 机制/时序
+
+初始化 `RecorderManager` -> 配置录音参数 -> 开始录音 -> 监听 `onStop` 获取录音结果 -> 调用 `createAudioMessage` 创建语音消息 -> 调用 `sendMessage` 发送 -> 根据发送结果更新 UI 与日志。
+
+## 4. 标准用法
+
+1. 获取录音管理器并配置录音参数，`format` 使用 `aac`。
+2. 注册 `onError` 和 `onStop` 回调；在 `onStop` 中基于录音结果创建语音消息。
+3. 调用 `sendMessage` 发送语音消息并处理成功/失败回调。
+4. 将消息实例上屏，并在失败时提示重试。
+
+```javascript
+// 示例：使用微信官方的 RecorderManager 进行录音
+// 参考 https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html
+// 1. 获取全局唯一的录音管理器 RecorderManager
+const recorderManager = wx.getRecorderManager();
+
+// 录音部分参数
+const recordOptions = {
+  duration: 60000, // 录音的时长，单位 ms，最大值 600000（10 分钟）
+  sampleRate: 44100, // 采样率
+  numberOfChannels: 1, // 录音通道数
+  encodeBitRate: 192000, // 编码码率
+  format: 'aac' // 音频格式，选择此格式创建的音频消息可以在 IM 全平台互通
+};
+
+// 2.1 监听录音错误事件
+recorderManager.onError(function(errMsg) {
+  console.warn('recorder error:', errMsg);
+});
+
+// 2.2 监听录音结束事件，录音结束后创建并发送音频消息
+recorderManager.onStop(function(res) {
+  console.log('recorder stop', res);
+
+  // 4. 创建消息实例，接口返回的实例可以上屏
+  const message = chat.createAudioMessage({
+    to: 'user1',
+    conversationType: TencentCloudChat.TYPES.CONV_C2C,
+    // 消息优先级，用于群聊
+    // priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,
+    payload: {
+      file: res
+    },
+    // 消息自定义数据（云端保存，会发送到对端，程序卸载重装后还能拉取到）
+    // cloudCustomData: 'your cloud custom data'
+  });
+
+  // 5. 发送消息
+  chat.sendMessage(message).then(function(imResponse) {
+    // 发送成功
+    console.log(imResponse);
+  }).catch(function(imError) {
+    // 发送失败
+    console.warn('sendMessage error:', imError);
+  });
+});
+
+// 3. 开始录音
+recorderManager.start(recordOptions);
+```
+
+## 5. 结果判定
+
+- 录音结束后能稳定触发 `onStop`，并成功创建语音消息实例。
+- 发送成功时，`sendMessage` Promise 进入 `then`，消息可正常上屏。
+- Android、iOS、小程序、Web 端均可播放该语音消息（`aac` 格式）。
+- 录音异常时，`onError` 有明确日志，且不出现静默失败。
+
+## 6. 常见误区
+
+- 误区 1：未在 `onStop` 回调中创建消息，导致发送时没有有效语音文件。
+- 误区 2：音频格式未使用 `aac`，导致跨平台互通受限。
+- 误区 3：只调用 `createAudioMessage` 不调用 `sendMessage`，误以为消息已发送。
+
+## 7. 问题定义（检索辅助，极简）
+
+小程序集成 IM SDK 时，如何完成语音录制、创建语音消息并发送，且保证跨端可互通。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 小程序 IM SDK 怎么发送语音消息？
+- 小程序录音后如何用 `createAudioMessage` 发消息？
+- `RecorderManager` 录音结果怎么接入 IM 发送？
+- 语音消息用什么格式可以和 Android/iOS/Web 互通？
+
+## 9. 参考来源（可选）
+
+- 微信小程序录音能力（RecorderManager.start）：`https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html`
+- Chat SDK 音频消息文档：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#createAudioMessage`

package/resource/knowledge/chat/best-practice/miniprogram/login-timeout-2801-diagnosis.md

@@ -0,0 +1,67 @@
+---
+title: 小程序集成 IM SDK 登录超时 2801 排查与修复
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [login, timeout, 2801, websocket, 域名白名单, 调试模式, ipv6]
+version_range: ">=3.0.0"
+---
+
+# 小程序集成 IM SDK 登录超时 2801 排查与修复
+
+## 1. 核心结论
+
+- 该场景的首要排查项是小程序管理后台 `websocket` 域名白名单配置是否完整。
+- 开发版与体验版/正式版校验策略不同，开发版登录正常不等于白名单配置正确。
+- 体验版可开启调试模式验证：调试模式会绕过域名白名单校验，可用于快速定位问题是否由白名单导致。
+- 独立域名 `wss://${SDKAppID}w4c.my-imcloud.com` 需要 SDK `v3.4.6` 及以上版本支持。
+- IPv6 域名 `wss://wssv6.im.qcloud.com` 需要 SDK `v3.4.9` 及以上版本支持。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 错误码 `2801` | 登录超时信号 | 在体验版/正式版出现时，优先排查网络连通与域名白名单 |
+| `websocket` 域名白名单 | 连接准入控制 | 未完整加白会导致非开发版连接失败或超时 |
+| 体验版调试模式 | 定位手段 | 可绕过域名白名单校验，用于验证是否白名单导致 |
+| `wss://${SDKAppID}w4c.my-imcloud.com` | 独立域名 | SDK `v3.4.6+` 支持 |
+| `wss://wssv6.im.qcloud.com` | IPv6 域名 | SDK `v3.4.9+` 支持 |
+
+## 3. 机制/时序
+
+开发版可登录 -> 体验版/正式版登录超时（2801）-> 检查小程序管理后台 `websocket` 域名白名单 -> 开启体验版调试模式复测 -> 若调试模式恢复正常，则确认为白名单配置问题。
+
+## 4. 标准用法
+
+1. 登录小程序管理后台，检查 `websocket` 域名白名单是否已完整配置。参考文档：`https://cloud.tencent.com/document/product/269/117335`。
+2. 在体验版开启调试模式并复测登录。
+3. 若开启调试模式后登录恢复正常，按白名单规范补齐/修正 `websocket` 域名配置。
+4. 使用体验版与正式版再次验证登录链路，确认 2801 消失。
+
+## 5. 结果判定
+
+- 体验版关闭调试模式后，仍可稳定登录。
+- 正式版登录不再出现 2801 超时。
+- 小程序后台 `websocket` 域名白名单与当前接入域名完全一致。
+- 若使用独立域名或 IPv6 域名，SDK 版本分别满足 `v3.4.6+` / `v3.4.9+`。
+
+## 6. 常见误区
+
+- 误区 1：开发版登录正常，就认为域名白名单已经配置正确。
+- 误区 2：只在调试模式下验证通过，就直接发布正式版。
+- 误区 3：使用独立域名或 IPv6 域名时忽略 SDK 最低版本要求。
+
+## 7. 问题定义（检索辅助，极简）
+
+小程序集成 IM SDK 时，开发版登录正常，但体验版和正式版登录超时（2801）。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 体验版小程序 IM 登录 2801 怎么处理？
+- 为什么开发版能登，体验版和正式版超时？
+- 体验版登录超时是否和 websocket 域名白名单有关？
+- 小程序后台 websocket 没加白会导致 IM 登录失败吗？
+
+## 9. 参考来源（可选）
+
+- 小程序 websocket 域名配置说明：`https://cloud.tencent.com/document/product/269/117335`

package/resource/knowledge/chat/best-practice/miniprogram/media-upload-fail-diagnosis.md

@@ -0,0 +1,68 @@
+---
+title: 小程序集成 IM SDK 富媒体消息上传失败排查与修复（图片/视频/语音/文件）
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [upload, media, image, video, audio, file, uploadFile, 域名白名单, 调试模式, COS 独立域名]
+version_range: ">=3.0.0"
+---
+
+# 小程序集成 IM SDK 媒体上传失败排查与修复（图片/视频/语音/文件）
+
+## 1. 核心结论
+
+- 该场景的首要排查项是小程序管理后台 `uploadFile` 域名白名单配置是否完整。
+- 开发版与体验版/正式版校验策略不同，开发版上传正常不等于白名单配置正确。
+- 体验版可开启调试模式验证：调试模式会绕过域名白名单校验，可用于快速定位问题是否由 `uploadFile` 域名配置导致。
+- 从 2024-09-10 起，新增应用默认分配 COS 独立域名 `https://${SDKAppID}-cn.rich.my-imcloud.com`。
+- 使用 COS 独立域名时，必须将对应域名加入小程序 `uploadFile` 合法域名白名单。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `uploadFile` 域名白名单 | 上传通道准入控制 | 未完整加白会导致体验版/正式版上传失败 |
+| 体验版调试模式 | 定位手段 | 可绕过域名白名单校验，用于验证是否白名单导致 |
+| `https://${SDKAppID}-cn.rich.my-imcloud.com` | COS 独立域名 | 新增应用默认分配，需加入 `uploadFile` 白名单 |
+| 媒体消息类型（图片/视频/语音/文件） | 影响范围 | 上传能力共用 `uploadFile` 链路，均受白名单配置影响 |
+
+## 3. 机制/时序
+
+开发版上传正常 -> 体验版/正式版上传失败 -> 检查小程序管理后台 `uploadFile` 域名白名单 -> 开启体验版调试模式复测 -> 若调试模式恢复正常，则确认为白名单配置问题。
+
+## 4. 标准用法
+
+1. 登录小程序管理后台，检查 `uploadFile` 合法域名是否已完整配置。参考文档：`https://cloud.tencent.com/document/product/269/117335`。
+2. 核对并加入当前应用实际使用的上传域名，重点确认 COS 独立域名 `https://${SDKAppID}-cn.rich.my-imcloud.com` 是否已加白。
+3. 在体验版开启调试模式并复测图片/视频/语音/文件上传。
+4. 若开启调试模式后上传恢复正常，按白名单规范补齐/修正 `uploadFile` 域名配置。
+5. 关闭调试模式后，使用体验版与正式版再次验证上传链路。
+
+## 5. 结果判定
+
+- 体验版关闭调试模式后，图片/视频/语音/文件上传均成功。
+- 正式版上传链路稳定，无上传失败。
+- 小程序后台 `uploadFile` 域名白名单与当前接入域名完全一致。
+- COS 独立域名 `https://${SDKAppID}-cn.rich.my-imcloud.com` 已加入白名单（适用新增应用）。
+
+## 6. 常见误区
+
+- 误区 1：开发版上传正常，就认为域名白名单已经配置正确。
+- 误区 2：只在调试模式下验证通过，就直接发布正式版。
+- 误区 3：只检查 `request` 或 `websocket` 白名单，忽略 `uploadFile` 白名单。
+- 误区 4：新增应用启用 COS 独立域名后，未同步更新 `uploadFile` 白名单。
+
+## 7. 问题定义（检索辅助，极简）
+
+小程序集成 IM SDK 时，开发版图片/视频/语音/文件上传正常，但体验版和正式版上传失败。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 小程序 IM 上传图片在体验版失败怎么处理？
+- 为什么开发版能上传，体验版和正式版上传失败？
+- 小程序 `uploadFile` 域名白名单没配置会导致 IM 上传失败吗？
+- 体验版开启调试模式后上传恢复正常，说明什么问题？
+
+## 9. 参考来源（可选）
+
+- 小程序合法域名配置说明：`https://cloud.tencent.com/document/product/269/117335`

package/resource/knowledge/chat/best-practice/web/audio-message-send.md

@@ -0,0 +1,123 @@
+---
+title: Web（PC/H5）集成 IM SDK 发送语音消息标准方案
+product: chat
+frameworks: [web]
+scope: platform_specific
+tags: [audio, voice, createAudioMessage, sendMessage, Recorder, js-audio-recorder, h5, pc]
+version_range: ">=3.0.0"
+---
+
+# Web（PC/H5）集成 IM SDK 发送语音消息标准方案
+
+## 1. 核心结论
+
+- Web 端可使用第三方录音库（如 `js-audio-recorder`）完成录音，再将录音结果转换为 `File` 后调用 `createAudioMessage`。
+- `audioFile` 必须带上 `uri` 字段（`audioFile.uri = window.URL.createObjectURL(audioFile)`），否则语音消息创建与发送链路不完整。
+- 消息创建后通过 `sendMessage` 发送，发送结果以 Promise 成功/失败回调为准。
+- 建议在 `createAudioMessage` 中传入 `onProgress` 回调，实时观测音频上传进度。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `Recorder` | 录音能力 | 在浏览器侧采集语音数据 |
+| `recorder.getWAVBlob()` | 导出录音数据 | 获取 WAV 二进制数据用于后续构造 `File` |
+| `audioFile.uri` | 本地可访问地址 | 必填字段，使用 `window.URL.createObjectURL(audioFile)` 生成 |
+| `chat.createAudioMessage({...})` | 创建语音消息实例 | 生成可上屏、可发送的语音消息对象 |
+| `chat.sendMessage(message)` | 发送消息 | 返回 Promise，`then` 成功、`catch` 失败 |
+| `onProgress` | 上传进度回调 | 观测语音文件上传过程 |
+
+## 3. 机制/时序
+
+开始录音 -> 停止录音 -> 计算时长并获取 WAV Blob -> 转换为 `File` 并补充 `uri` 与 `duration` -> 调用 `createAudioMessage` 创建语音消息 -> 调用 `sendMessage` 发送 -> 根据发送结果更新 UI 与日志。
+
+## 4. 标准用法
+
+1. 使用录音器开始录音并记录起始时间。
+2. 结束录音后计算时长，获取 `WAV Blob`。
+3. 将 `Blob` 转为 `File`，并补齐 `audioFile.uri`、`audioFile.duration`。
+4. 调用 `createAudioMessage` 创建语音消息，传入 `onProgress` 回调。
+5. 调用 `sendMessage` 发送语音消息，处理成功与失败分支。
+
+```javascript
+// 在 Web 端创建语音消息并发送
+// 示例：使用第三方库 js-audio-recorder 录制音频
+
+// 1. 开始录制
+let recorder = new Recorder({
+  sampleBits: 16, // 采样位数，支持 8 或 16，默认 16
+  sampleRate: 16000, // 采样率
+  numChannels: 1 // 声道，支持 1 或 2，默认 1
+});
+
+let startTs;
+recorder.start().then(() => {
+  // 开始录音，记录起始时间戳
+  startTs = Date.now();
+}, (error) => {
+  // 出错了
+  console.log(`${error.name} : ${error.message}`);
+});
+
+// 2. 结束录制
+recorder.stop();
+
+// 3. 计算录音时长，获取 WAV 数据
+let duration = Date.now() - startTs; // 单位：ms
+let wavBlob = recorder.getWAVBlob();
+
+// 4. blob 数据转成 File 对象
+let audioFile = new File([wavBlob], 'hello.wav', { type: 'wav' });
+audioFile.uri = window.URL.createObjectURL(audioFile);
+audioFile.duration = duration;
+
+// 5. 创建音频消息
+let message = chat.createAudioMessage({
+  to: 'user1',
+  conversationType: 'C2C',
+  payload: {
+    file: audioFile
+  },
+  // 音频上传进度回调
+  onProgress: function(event) {
+    console.log('file uploading:', event);
+  }
+});
+
+// 6. 发送消息
+chat.sendMessage(message).then(function(imResponse) {
+  // 发送成功
+  console.log(imResponse);
+}).catch(function(imError) {
+  // 发送失败
+  console.warn('sendMessage error:', imError);
+});
+```
+
+## 5. 结果判定
+
+- 录音结束后可稳定获取 `wavBlob`，并成功构造 `audioFile`。
+- `audioFile.uri` 已设置，`createAudioMessage` 可正常创建语音消息。
+- `sendMessage` 成功进入 `then`，语音消息可上屏并可播放。
+- 上传过程中能收到 `onProgress` 回调，失败时 `catch` 有明确错误日志。
+
+## 6. 常见误区
+
+- 误区 1：未设置 `audioFile.uri`，直接发送导致消息链路异常。
+- 误区 2：只创建消息不发送，误以为消息已投递。
+- 误区 3：录音结束后未正确计算时长或封装文件，导致音频不可用。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web（PC/H5）集成 IM SDK 时，如何完成语音录制并稳定发送语音消息。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Web IM SDK 怎么发送语音消息？
+- PC/H5 录音后如何调用 `createAudioMessage`？
+- `audioFile.uri` 为什么必须设置？
+
+## 9. 参考来源（可选）
+
+- PC/H5 录音能力：`https://www.npmjs.com/package/js-audio-recorder`
+- Chat SDK `createAudioMessage` 文档：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#createAudioMessage`

package/resource/knowledge/chat/preset/android/features/conversation-list.md

@@ -111,3 +111,4 @@ ConversationList() {
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/android/features/language.md

@@ -127,3 +127,4 @@ public class MyApplication extends Application {
     }
 }
 ```
+

package/resource/knowledge/chat/preset/android/features/message-input.md

@@ -47,3 +47,4 @@ MessageInput(
     )
 )
 ```
+

package/resource/knowledge/chat/preset/android/features/message-list.md

@@ -129,3 +129,4 @@ MessageList(
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/flutter/features/conversation-list.md

@@ -117,3 +117,4 @@ Expanded(
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/flutter/features/message-input.md

@@ -44,3 +44,4 @@ MessageInput(
   ),
 ),
 ```
+

package/resource/knowledge/chat/preset/flutter/features/message-list.md

@@ -150,3 +150,4 @@ MessageList(
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/ios/features/conversation-list.md

@@ -122,3 +122,4 @@ ConversationList(
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/ios/features/message-input.md

@@ -59,3 +59,4 @@ MessageInput(
     )
 )
 ```
+

package/resource/knowledge/chat/preset/ios/features/message-list.md

@@ -151,3 +151,4 @@ MessageList(
 > **注意：**
 > 局部配置的优先级大于全局配置。
 >
+

package/resource/knowledge/chat/preset/react/features/conversation-preview.md

@@ -91,3 +91,4 @@ const App = () => {
 ```
 
 `ConversationListPreview` 定制后效果如下：
+

package/resource/knowledge/chat/urls/sdk/web.md

@@ -23,7 +23,7 @@
 | 文本消息（createTextMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
 | 群 @ 消息（createTextAtMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
 | 图片消息（createImageMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
-| 语音消息（createVoiceMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
+| 语音消息（createAudioMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
 | 视频消息（createVideoMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
 | 文件消息（createFileMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |
 | 自定义消息（createCustomMessage → sendMessage） | `https://cloud.tencent.com/document/product/269/75316` |

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

@@ -0,0 +1,124 @@
+---
+title: 语聊房房主创建房间并开播推流（Android）
+product: live
+frameworks: [android]
+scope: platform_specific
+tags: [语聊房, 房主, 开播, 推流, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, TakeSeatMode, Android]
+version_range: ">=2.0.0"
+---
+
+# 语聊房房主创建房间并开播推流（Android）
+
+## 1. 核心结论
+
+- 语聊房开播流程：构造 `LiveInfo`（含 `liveID`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode`），调用 `createLive` 创建房间；成功后调用 `openLocalMicrophone` 采集音频并发布推流，房间内用户即可听到主播声音。
+- `liveID` 必填，直播间的唯一标识符。
+- `keepOwnerOnSeat` 设为 `true` 时主播进房后自动上麦（上麦是推流的前提，只有上麦的用户才能在房间内推音频流）。
+- `seatTemplate` 设为语聊房模板 `SeatLayoutTemplate.AudioSalon(n)`，n 为套餐支持的最大麦位数或小于该值的麦位数。
+- `seatMode` 设置上麦模式（如 `TakeSeatMode.APPLY` 申请上麦）。
+- `muteMicrophone` 暂停发布本机音频流；`unmuteMicrophone` 恢复发布本机音频流。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `LiveInfo` | 房间信息 | 包含 `liveID`、`liveName`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode` 等参数 |
+| `liveID` | 房间 ID | `createLive` 必填参数 |
+| `liveName` | 房间名称 | 创建房间的展示名称 |
+| `seatTemplate` | 麦位布局模板 | 语聊房使用 `SeatLayoutTemplate.AudioSalon(seatCount = n)`，n ≤ 套餐最大麦位数 |
+| `keepOwnerOnSeat` | 房主自动上麦 | 设为 `true`，主播进房后自动上麦 |
+| `seatMode` | 上麦模式 | 如 `TakeSeatMode.APPLY` 申请上麦 |
+| `createLive(liveInfo, callback)` | 创建房间（开播） | 传入 `LiveInfo` 和 `LiveInfoCompletionHandler` 回调 |
+| `openLocalMicrophone` | 采集音频并发布 | 打开本地麦克风，发布音频流到房间 |
+| `muteMicrophone` | 暂停发布音频 | 已打开麦克风时，暂停发布本地音频流 |
+| `unmuteMicrophone` | 恢复发布音频 | 已打开麦克风时，恢复发布本地音频流 |
+
+## 3. 机制/时序
+
+构造 `LiveInfo`（`liveID` 必填，`seatTemplate=AudioSalon(n)`，`keepOwnerOnSeat=true`，`seatMode` 按需设置） -> 调用 `createLive` 创建房间 -> `onSuccess` 回调触发，房主默认自动上麦 -> 调用 `openLocalMicrophone` 采集并发布音频 -> 房间内用户听到主播声音。
+
+上麦是推流的前提：`keepOwnerOnSeat=true` 保证房主上麦后才能推音频流。`muteMicrophone` / `unmuteMicrophone` 用于推流过程中的暂停/恢复。
+
+## 4. 标准用法
+
+1. 构造 `LiveInfo`：设置 `liveID`、`seatTemplate`、`keepOwnerOnSeat`、`seatMode`。
+2. 实现 `LiveInfoCompletionHandler`，调用 `createLive` 发起开播。
+3. `onSuccess` 回调后，调用 `openLocalMicrophone` 采集音频并发布推流。
+4. 需要暂停/恢复推流时调用 `muteMicrophone` / `unmuteMicrophone`。
+
+```kotlin
+import android.util.Log
+import androidx.appcompat.app.AppCompatActivity
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfo
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfoCompletionHandler
+import io.trtc.tuikit.atomicxcore.api.live.TakeSeatMode
+
+class YourAnchorActivity : AppCompatActivity() {
+    // ... 其他代码 ...
+
+    private fun startLive() {
+        val liveInfo = LiveInfo().apply {
+            // 1. 设置房间基础信息
+            liveID = this@YourAnchorActivity.liveID
+            liveName = "test 语聊房"
+
+            // 2. 设置语聊房麦位模板，seatCount 传入所需麦位数（≤ 套餐最大麦位数）
+            seatTemplate = SeatLayoutTemplate.AudioSalon(seatCount = 9)
+
+            // 3. 主播开播后自动上麦（上麦后才能推音频流）
+            keepOwnerOnSeat = true
+
+            // 4. 设置上麦模式（例如申请上麦）
+            seatMode = TakeSeatMode.APPLY
+        }
+
+        // 5. 调用 createLive 创建房间（开播）
+        liveListStore.createLive(liveInfo, object : LiveInfoCompletionHandler {
+            override fun onFailure(code: Int, desc: String) {
+                Log.e("Live", "Response startLive onError: $desc")
+            }
+
+            override fun onSuccess(liveInfo: LiveInfo) {
+                Log.d("Live", "Response startLive onSuccess")
+                // 6. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+                liveSeatStore.openLocalMicrophone(null)
+            }
+        })
+    }
+}
+```
+
+## 5. 结果判定
+
+- `onSuccess` 回调触发：房间创建成功，房主默认自动上麦。
+- `openLocalMicrophone` 后：房间内用户能听到主播声音。
+- `muteMicrophone` 后：本机音频暂停发布；`unmuteMicrophone` 后恢复。
+- `keepOwnerOnSeat` 未设 `true`：主播未自动上麦，无法推流。
+- `onFailure(code, desc)` 回调触发：开播失败，`code` 为错误码，`desc` 为错误描述。
+
+## 6. 常见误区
+
+- 误区 1：跳过 `createLive` 直接调用 `openLocalMicrophone`（未创建房间无法推流）。
+- 误区 2：`keepOwnerOnSeat` 未设 `true`，主播未上麦，推流不生效。
+- 误区 3：`seatTemplate` 未设置或 `seatCount` 超过套餐最大麦位数。
+- 误区 4：混淆 `muteMicrophone`（暂停发布音频流）与关闭麦克风（停止采集）。
+- 误区 5：`liveID` 重复使用（必须全局唯一，否则创建失败）。
+- 误区 6：混淆 `onSuccess` 和 `onFailure` 回调（两个分支都需防御性处理）。
+
+## 7. 问题定义（检索辅助，极简）
+
+Android 语聊房房主需要按正确顺序创建房间并开播推流，了解 `createLive`、`openLocalMicrophone`、`muteMicrophone`、`unmuteMicrophone` 的调用时机与参数含义。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Android 语聊房房主怎么开播？
+- Android `createLive` 和 `openLocalMicrophone` 的调用顺序是什么？
+- Android 主播怎么上麦推流？
+- `keepOwnerOnSeat` 参数有什么作用？
+- `seatTemplate` 怎么设置语聊房 `AudioSalon` 模板？
+- Android `muteMicrophone` 和 `unmuteMicrophone` 区别是什么？
+- 语聊房创建房间后如何推音频流？
+
+## 9. 参考来源（可选）
+
+- LiveKit Android 文档：`https://cloud.tencent.com/document/product/647/124968`

package/resource/knowledge/livekit/best-practice/common/admin-take-seat.md

@@ -0,0 +1,73 @@
+---
+title: 语聊房管理员上麦与麦位锁定操作
+product: live
+frameworks: [android, ios, flutter]
+scope: platform_common
+tags: [语聊房, 管理员, 上麦, takeSeat, lockSeat, unlockSeat, seatMode, FREE, 麦位, 主持麦位, 房主同意, VoiceRoom]
+version_range: ">=2.0.0"
+---
+
+# 语聊房管理员上麦与麦位锁定操作
+
+## 1. 核心结论
+
+- 管理员上麦调用 `takeSeat` 并传入麦位序号，不需要调用 `applyForSeat`，**不受 `seatMode=APPLY` 限制**，也**不需要**房主同意。
+- 管理员上麦**不受 `lockSeat` 锁定限制**，可直接 `takeSeat` 到任意麦位（含 0 号主持麦位）。
+- 普通用户仅在 `seatMode` 为 `FREE` 时才能调用 `takeSeat` 上麦，且**受 `lockSeat` 锁定限制**。
+- 三端（Android/iOS/Flutter）`LiveSeatStore` 的麦位操作 API 一致。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `takeSeat` | 上麦 | 传入麦位序号上麦；管理员不受 `seatMode`/`lockSeat` 限制；普通用户需 `seatMode=FREE` 且麦位未锁定 |
+| `lockSeat` | 锁定麦位 | 锁定后普通用户无法 `takeSeat`，管理员不受影响 |
+| `unlockSeat` | 解锁麦位 | 解锁后普通用户才能 `takeSeat` |
+| `seatMode` | 上麦模式 | 普通用户仅在 `FREE` 模式下可 `takeSeat` |
+| `LiveSeatStore` | 麦位管理 | 提供 `takeSeat`/`leaveSeat`/`lockSeat`/`unlockSeat` 等操作 |
+| 房主 | 房间所有者 | 可锁定/解锁麦位 |
+
+## 3. 机制/时序
+
+### 管理员上麦
+
+管理员调用 `takeSeat(index)` 直接上麦（传入目标麦位序号）-> 不受 `seatMode` 限制 -> 无需房主同意 -> 不受 `lockSeat` 锁定限制，直接上麦成功。
+
+## 4. 标准用法
+
+1. **管理员上麦**：调用 `takeSeat(index)`，`index` 为目标麦位序号（如 0 号主持麦位），不受 `seatMode`/`lockSeat` 限制。
+2. **普通用户上麦**：确认 `seatMode=FREE`，且目标麦位未锁定，调用 `takeSeat(index)`。
+3. **锁麦位**：管理员/房主调用 `lockSeat(index)` 锁定，锁定后普通用户不可 `takeSeat`，管理员不受影响。
+4. **解锁后上麦**：先 `unlockSeat(index)` 解锁，普通用户再 `takeSeat(index)` 上麦。
+
+```javascript
+// 三端 API 一致，仅语言风格略有差异（Android Kotlin / iOS Swift / Flutter Dart）
+// 1. 管理员直接上麦（不受 seatMode / lockSeat 限制，无需房主同意）
+liveSeatStore.takeSeat(0);   // 上麦到 0 号主持麦位
+```
+
+## 5. 结果判定
+
+- 管理员 `takeSeat(index)` 直接成功，不受 `seatMode` 限制，无房主同意。
+- `lockSeat` 后管理员 `takeSeat` 同一麦位仍成功（管理员不受锁麦限制）。
+- 普通用户仅 `seatMode=FREE` 时 `takeSeat` 成功；麦位被锁定则失败，需先 `unlockSeat`。
+
+## 6. 常见误区
+
+- 误区 1：管理员上麦时调用 `applyForSeat` 申请（管理员直接 `takeSeat`，无需申请）。
+- 误区 2：认为管理员 `takeSeat` 需要房主同意（管理员不受此限制）。
+- 误区 3：认为 `lockSeat` 后管理员也不能 `takeSeat` 同一麦位（管理员不受锁麦限制，仅普通用户受限）。
+
+## 7. 问题定义（检索辅助，极简）
+
+语聊房管理员如何直接上麦到指定麦位（含 0 号主持麦位）、管理员是否受 `seatMode`/`lockSeat` 限制，以及普通用户上麦的 `seatMode` 与锁定条件。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 语聊房管理员怎么上麦到 0 号麦位？
+- 管理员 `takeSeat` 需要房主同意吗？
+- 管理员上麦受 `seatMode` 限制吗？
+- 锁麦后管理员能 `takeSeat` 吗？
+- 普通用户什么时候能 `takeSeat`？
+- `seatMode=FREE` 时普通用户能上麦吗？
+- 锁定的麦位怎么解锁再上麦？