@tencentcloud/sdk-mcp 1.6.7 → 1.7.0

package/resource/knowledge/chat/best-practice/common/message-receive-event.md

@@ -0,0 +1,70 @@
+---
+title: Web Chat SDK 消息接收事件（MESSAGE_RECEIVED）与群提示消息处理
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [MESSAGE_RECEIVED, TIMGroupTipElem, TIMGroupSystemNoticeElem, 消息接收, 自己发消息, event.data]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK 消息接收事件（MESSAGE_RECEIVED）与群提示消息处理
+
+## 1. 核心结论
+
+- Web Chat SDK 的消息通知统一通过 `MESSAGE_RECEIVED` 事件下发给业务侧。
+- 在回调中遍历 `event.data`，可按消息 `type` 字段区分普通消息、群提示消息（`TIMGroupTipElem`）和群系统通知（`TIMGroupSystemNoticeElem`）。
+- 当前实例发送的消息不会通过 `MESSAGE_RECEIVED` 再回给自己；自己发出的消息应在创建完成后立即写入上屏消息列表。
+- 多实例或多端登录时，非当前实例发送的消息可以通过 `MESSAGE_RECEIVED` 接收。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `EVENT.MESSAGE_RECEIVED` | 统一接收入口 | 所有接收消息通过该事件通知业务侧 |
+| `event.data` | 消息列表载体 | 一次回调可能包含多条消息，需全量遍历处理 |
+| `message.type` | 消息分类字段 | 用于识别普通消息、`TIMGroupTipElem`、`TIMGroupSystemNoticeElem` |
+| 本端发送消息上屏 | UI 时机控制 | 当前实例自己发消息应在创建后立即上屏，不依赖 `MESSAGE_RECEIVED` |
+
+## 3. 机制/时序
+
+业务侧订阅 `MESSAGE_RECEIVED` -> SDK 下发消息列表 `event.data` -> 业务遍历列表按 `type` 分流处理。
+当前实例发送消息：创建消息并立即本地上屏 -> 调用发送接口 -> 不通过 `MESSAGE_RECEIVED` 回给本端。
+其他实例/其他端发送消息：当前端通过 `MESSAGE_RECEIVED` 收到并按类型处理。
+
+## 4. 标准用法
+
+1. 订阅 `EVENT.MESSAGE_RECEIVED`，回调中读取完整 `event.data` 列表。
+2. 对每条消息按 `type` 分流：普通消息、`TIMGroupTipElem`、`TIMGroupSystemNoticeElem` 走不同业务处理器。
+3. 自己发送消息时，在 `createXXXMessage` 后立即写入本地消息列表，保证上屏时效。
+4. 保留发送回调与接收回调的职责边界：发送链路负责本端状态，接收链路负责他端/他实例下发。
+
+## 5. 结果判定
+
+- 群提示消息触发后，可在 `MESSAGE_RECEIVED` 中识别到 `TIMGroupTipElem` 并走正确处理逻辑。
+- 群系统通知可在回调中识别 `TIMGroupSystemNoticeElem` 并正确分流。
+- 当前实例发送消息时，本地立即上屏，不等待 `MESSAGE_RECEIVED`。
+- 多端登录时，其他端发送的消息能通过 `MESSAGE_RECEIVED` 正常接收。
+
+## 6. 常见误区
+
+- 误区 1：把 `MESSAGE_RECEIVED` 当单条回调，只处理 `event.data[0]`。
+- 误区 2：期待当前实例发送的消息通过 `MESSAGE_RECEIVED` 回到本端再上屏。
+- 误区 3：不按 `type` 分类，导致群提示消息和普通文本消息混用同一处理逻辑。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 场景下，业务侧希望明确两件事：
+1）如何接收并识别群提示消息 `TIMGroupTipElem`；
+2）`MESSAGE_RECEIVED` 是否会收到当前实例自己发送的消息。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Web SDK 怎么接收群提示消息 `TIMGroupTipElem`？
+- `MESSAGE_RECEIVED` 回调里如何区分普通消息和群系统消息？
+- 为什么自己发送的消息没有通过 `MESSAGE_RECEIVED` 收到？
+- 多端登录时，其他端发的消息能不能通过 `MESSAGE_RECEIVED` 收到？
+
+## 9. 参考来源（可选）
+
+- 消息接收事件：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_RECEIVED`
+- 消息结构体：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html`

package/resource/knowledge/chat/best-practice/common/message-risk-error-and-render.md

@@ -0,0 +1,69 @@
+---
+title: Web/小程序 Chat SDK 消息发送报错（80001/80004）与审核打击渲染方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [sendMessage, 80001, 80004, hasRiskContent, MESSAGE_MODIFIED, 云端审核, 文本审核, 图片审核, 异步审核, 语音消息, 视频消息]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 消息发送报错（80001/80004）与审核打击渲染方案
+
+## 1. 核心结论
+
+- 文本发送报错 `80001` 表示文本命中敏感信息审核策略，需要排查消息内容与云端敏感词配置。
+- 图片发送报错 `80004` 表示图片命中敏感信息审核策略，需要排查图片内容与云端图片审核规则配置。
+- UI 侧判断消息是否被审核打击的标准字段是 `message.hasRiskContent`。
+- 同步审核要在 `sendMessage` 的 `catch` 里收到 `80001/80004`，需在 IM 控制台开启“下发拦截错误码”（控制台 > 云端审核 > 审核结果配置 > 下发拦截错误码）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 错误码 `80001` | 文本审核拦截信号 | 文本消息命中敏感策略时返回 |
+| 错误码 `80004` | 图片审核拦截信号 | 图片消息命中敏感策略时返回 |
+| `message.hasRiskContent` | 风险内容标识 | 用于 UI 判断消息是否被审核打击 |
+| `EVENT.MESSAGE_MODIFIED` | 消息修改通知事件 | 异步审核命中后，SDK 通过该事件下发消息字段更新 |
+| “下发拦截错误码”开关 | 同步错误返回控制 | 开启后 `sendMessage.catch` 才能收到审核拦截错误码 |
+
+## 3. 机制/时序
+
+文本消息为同步审核：发送消息 -> 审核命中 -> `sendMessage.catch` 返回 `80001`，返回的 `message.hasRiskContent=true`。文本同步审核命中场景下，不会派发 `EVENT.MESSAGE_MODIFIED` 事件通知。
+图片消息默认同步审核：发送消息 -> 若 2 秒内完成审核并命中 -> `sendMessage.catch` 返回 `80004`；若 2 秒内未完成审核 -> 自动转异步审核，审核命中后通过 `EVENT.MESSAGE_MODIFIED` 下发更新。
+语音/视频消息默认异步审核：发送消息 -> 后台异步审核 -> 审核命中后通过 `EVENT.MESSAGE_MODIFIED` 下发更新。
+
+## 4. 标准用法
+
+1. 在控制台开启“下发拦截错误码”，确保同步审核命中时 `sendMessage.catch` 可感知错误码。
+2. 发送文本/图片消息时，在 `catch` 分支读取错误码与返回 `message`，若 `message.hasRiskContent=true`，立即更新上屏消息状态。
+3. 监听 `EVENT.MESSAGE_MODIFIED`，遍历 `event.data`，发现 `message.hasRiskContent=true` 时更新对应上屏消息。
+4. 文本/图片命中率异常时，分别回查敏感词库与图片审核规则，联动云端审核策略调整。
+5. 对 UI 渲染统一使用 `hasRiskContent` 判定，不依赖单一错误码做长期状态判断。
+
+## 5. 结果判定
+
+- 文本命中敏感词时，`sendMessage.catch` 可观测到 `80001`，且消息状态更新为审核打击。
+- 图片命中敏感规则时，能在同步路径收到 `80004`，或在异步路径通过 `MESSAGE_MODIFIED` 收到 `hasRiskContent=true` 更新。
+- 语音/视频异步审核命中后，UI 能通过 `MESSAGE_MODIFIED` 正确更新打击状态。
+- 同一消息在同步/异步两条链路下，最终均以 `hasRiskContent` 渲染一致状态。
+
+## 6. 常见误区
+
+- 误区 1：未开启“下发拦截错误码”却期望在 `sendMessage.catch` 一定拿到 `80001/80004`。
+- 误区 2：只处理 `sendMessage.catch`，不监听 `MESSAGE_MODIFIED`，导致异步审核打击漏渲染。
+- 误区 3：仅凭错误码渲染长期状态，不以 `hasRiskContent` 作为最终状态源。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 发送文本报错 `80001`、发送图片报错 `80004` 的原因是什么？UI 渲染时如何判断消息被审核打击（风险内容）？
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 文本发送失败 80001 是什么原因？
+- 图片发送失败 80004 是什么原因？
+- 消息被审核拦截后前端怎么识别？
+- `message.hasRiskContent` 什么时候会更新？
+
+## 9. 参考来源（可选）
+
+- MESSAGE_MODIFIED 事件：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_MODIFIED`

package/resource/knowledge/chat/best-practice/common/message-unread-count.md

@@ -0,0 +1,71 @@
+---
+title: Web/小程序 Chat SDK 未读消息总数获取与单聊/群聊拆分统计方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [getTotalUnreadMessageCount, TOTAL_UNREAD_MESSAGE_COUNT_UPDATED, unreadCount, 未读总数, 单聊未读, 群聊未读]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 未读消息总数获取与单聊/群聊拆分统计方案
+
+## 1. 核心结论
+
+- 获取未读消息总数使用 `getTotalUnreadMessageCount`。
+- SDK 当前不提供“仅单聊未读总数”或“仅群聊未读总数”的直接接口。
+- 推荐模式是“初始化拉一次 + 事件持续更新”：上线初始化调用 `getTotalUnreadMessageCount`，后续通过 `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` 维护总未读数。
+- `getTotalUnreadMessageCount` 依赖 SDK 会话列表数据；若调用时云端会话列表尚未同步完成，返回值可能为 `0`。
+- SDK 会话列表按分页同步，每次同步导致总未读变化时会派发 `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `getTotalUnreadMessageCount` | 获取当前总未读数 | 依赖本地已同步的会话列表状态 |
+| `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` | 总未读更新事件 | 会话列表分页同步或未读数变化后触发 |
+| `CONVERSATION_LIST_UPDATED` | 会话列表更新事件 | 可用于获取全量会话并做单聊/群聊分组统计 |
+| `conversation.type` | 会话类型标识 | 用于过滤单聊或群聊会话 |
+| `conversation.unreadCount` | 单会话未读数 | 累计后可得到单聊/群聊维度未读总数 |
+
+## 3. 机制/时序
+
+应用启动 -> SDK 同步会话列表（分页）-> 业务初始化调用 `getTotalUnreadMessageCount` 获取初值（可能为 0）-> SDK 每次分页同步后若总未读变化则派发 `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` -> 业务实时更新总未读展示。
+若需要单聊/群聊分维度未读：监听 `CONVERSATION_LIST_UPDATED` -> 获取全量会话列表 -> 按 `conversation.type` 过滤并累加 `conversation.unreadCount`。
+
+## 4. 标准用法
+
+1. 应用初始化阶段调用 `getTotalUnreadMessageCount`，先拿到当前可用的总未读初值。
+2. 监听 `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`，以事件值作为总未读数的持续更新来源。
+3. 监听 `CONVERSATION_LIST_UPDATED`，获取全量会话列表。
+4. 按 `conversation.type` 过滤出单聊或群聊会话，累加各会话 `unreadCount`，得到单聊未读总数与群聊未读总数。
+5. 当初始化返回 `0` 时，不直接判定“无未读”，以会话列表同步事件后的统计结果为准。
+
+## 5. 结果判定
+
+- 初始化时已调用 `getTotalUnreadMessageCount`，并在 UI 显示初值。
+- 会话列表分页同步过程中，`TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` 能持续驱动总未读变化。
+- 单聊与群聊未读总数由 `CONVERSATION_LIST_UPDATED + unreadCount` 累计结果稳定得出。
+- 初始化阶段出现 `0` 后，后续同步完成时未读数能正确刷新为真实值。
+
+## 6. 常见误区
+
+- 误区 1：认为 SDK 提供“单聊未读总数”或“群聊未读总数”的现成接口。
+- 误区 2：初始化 `getTotalUnreadMessageCount` 返回 `0` 就直接当作最终结果。
+- 误区 3：只在初始化取一次总未读数，不监听 `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 如何获取未读消息总数？是否有接口只获取单聊未读总数或群聊未读总数？
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 怎么获取 IM 全量未读消息数？
+- 有没有“只拿单聊未读”或“只拿群聊未读”的官方接口？
+- `getTotalUnreadMessageCount` 为什么初始化时返回 0？
+- 未读总数应该用事件更新还是轮询接口？
+
+## 9. 参考来源（可选）
+
+- getTotalUnreadMessageCount：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#getTotalUnreadMessageCount`
+- TOTAL_UNREAD_MESSAGE_COUNT_UPDATED：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`
+- CONVERSATION_LIST_UPDATED：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.CONVERSATION_LIST_UPDATED`

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/chat-setting.md

@@ -1,13 +1,10 @@
 ## 组件概述
 
 ChatSetting 是基于 Jetpack Compose  构建的聊天设置组件集合，主要包含单聊设置（C2CChatSetting）和群聊设置（GroupChatSetting）两个核心组件。这些组件为用户提供了完整的聊天会话管理功能，包括用户信息管理、权限设置、群组管理等核心能力。
-| <strong>单聊设置界面</strong> | <strong>群聊设置界面</strong> |
-| --- | --- |
-|  |  |
 
 ## 组件集成
 
-ChatSetting 组件属于 TUIKit Compose 的一部分，集成 TUIKit Compose 即可获取并使用 ChatSetting 组件。集成方法请参考文档 TUIKit Compose 里的集成步骤。
+ChatSetting 组件属于 TUIKit Compose 的一部分，集成 TUIKit Compose 即可获取并使用 ChatSetting 组件。集成方法。
 
 ## 组件构成
 

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

@@ -1,9 +1,6 @@
 ## 组件概述
 
 ContactList 是基于 Jetpack Compose 构建的联系人列表组件，为用户提供完整的联系人管理功能。该组件支持好友列表展示、好友申请处理、群组列表管理、黑名单管理等功能，并提供了丰富的交互回调接口。
-| <strong>联系人列表</strong> | <strong>群组列表</strong> | <strong>好友申请列表</strong> |
-| --- | --- | --- |
-|  |  |  |
 
 ## 组件集成
 
@@ -19,8 +16,6 @@ ContactList 是基于 Jetpack Compose 构建的联系人列表组件，为用户
 | <code>onContactClick: (ContactInfo) -> Unit</code> | 点击联系人的回调，可选参数。 |  |
 | <code>contactListViewModelFactory: ContactListViewModelFactory</code> | 创建组件内部 ContactListViewModel 的工厂类。通常情况下，您无需手动创建，组件已提供默认实现。 |  |
 
-`ContactList` 上半部分预留了各个子视图的入口 cell，例如好友申请、群聊申请、群聊列表和黑名单列表。下半部分内嵌了联系人列表，如下图所示：
-
 ## 基础用法
 
 在 `ContactList` 中点击好友申请、群聊申请、群聊列表和黑名单列表入口时，由组件自动完成路由，无需额外处理；点击群聊列表中的群组或联系人列表/黑名单中的个人时，会触发相应的回调接口 (`onGroupClick/onContactClick`)，需监听回调并实现自定义跳转。路由跳转示例图如下所示：

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

@@ -1,13 +1,10 @@
 ## 组件概述
 
 ConversationList 是一个基于 Jetpack Compose 构建的会话列表组件，主要用于展示和管理用户的聊天会话。该组件提供了完整的会话列表功能，包括会话展示、交互操作等核心能力。
-| <strong>会话列表</strong> | <strong>会话操作</strong> |
-| --- | --- |
-|  |  |
 
 ## 组件集成
 
-ConversationList 是属于 TUIKit Compose 的一个组件，集成 TUIKit Compose 即可获取并使用 ConversationList，集成方法请参考文档 TUIKit Compose 里的集成步骤。
+ConversationList 是属于 TUIKit Compose 的一个组件，集成 TUIKit Compose 即可获取并使用 ConversationList，集成方法。
 
 ## 组件构成
 
@@ -112,11 +109,6 @@ ConversationList() {
 ```
 
 > **注意：**
->
 > 局部配置的优先级大于全局配置。
 >
 
-自定义效果如下图所示：
-| 会话操作（默认选项） | 会话操作（隐藏<strong>删除</strong>选项） | 会话操作（新增<strong>隐藏会话</strong>选项） |
-| --- | --- | --- |
-|  |  |  |