@tencentcloud/sdk-mcp 1.6.8 → 1.7.0

package/resource/knowledge/chat/best-practice/common/avchatroom-message-loss-diagnosis.md

@@ -0,0 +1,71 @@
+---
+title: Web/小程序 Chat SDK 直播群（AVChatRoom）消息丢失排查与保障方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [AVChatRoom, 消息丢失, 直播群, MESSAGE_RECEIVED, 长轮询, MsgPriority, priority, restapi, 限频, 40条每秒]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 直播群（AVChatRoom）消息丢失排查与保障方案
+
+## 1. 核心结论
+
+- 场景 1（批量发送时丢消息）：根因是业务侧消费 `MESSAGE_RECEIVED` 回调逻辑错误。该回调一次可能返回多条消息，必须读取完整列表 `event.data`。
+- 场景 2（刷屏时重要消息没收到）：根因是触发后台群消息限频。默认每群 `40` 条/秒，超过后会丢弃消息；可通过消息优先级提升重要消息保留概率。
+- 场景 3（网络不稳或长时间后台后丢消息）：符合直播群机制预期。应用后台超过 `2` 分钟后恢复，无法拉取超过缓存窗口的历史消息。
+- 直播群消息不存漫游，后台默认只缓存 `2` 分钟内消息且上限 `2000` 条；超过窗口或上限后，被淘汰消息无法通过长轮询补回。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `EVENT.MESSAGE_RECEIVED` | 消息接收回调 | 一次回调可返回多条消息，业务必须遍历 `event.data` 全量处理 |
+| `priority`（SDK） | SDK 发消息优先级 | `createXXXMessage` 可设置，超限频时高优先级消息更不易被丢弃 |
+| `MsgPriority`（REST API） | REST API 发消息优先级 | 在消息体设置优先级，配合高并发场景保障关键通知 |
+| 群限频（默认 `40` 条/秒） | 后台流控阈值 | 超过阈值会发生丢弃，长轮询无法拉取被丢弃消息 |
+| 直播群缓存窗口（`2` 分钟/`2000` 条） | 临时缓存边界 | 超过时间或数量上限后，最早缓存消息会被清理 |
+
+## 3. 机制/时序
+
+业务发送消息（SDK/REST API）-> AVChatRoom 后台按群限频处理（默认 `40` 条/秒）-> 客户端通过长轮询接收消息并触发 `MESSAGE_RECEIVED` -> 业务消费回调列表。
+当应用长时间后台（超过 `2` 分钟）后回前台：WebSocket 重连成功 -> 恢复长轮询 -> 仅可拉取缓存窗口内消息（`2` 分钟且最多 `2000` 条）。
+
+## 4. 标准用法
+
+1. **修正接收逻辑（场景 1）**：在 `MESSAGE_RECEIVED` 中按 `event.data` 全量遍历处理，禁止只处理 `event.data[0]`。
+2. **保障重要消息（场景 2）**：将抽奖、商品上下架等关键消息设置为高优先级。
+   - SDK 发送：`createXXXMessage` 里设置 `priority`。
+   - REST API 发送：消息体设置 `MsgPriority`。
+3. **控制发送速率（场景 2）**：业务侧对批量消息做限流/合并，避免持续超过每群 `40` 条/秒。
+4. **处理后台恢复预期（场景 3）**：将“长时间后台后可能缺失直播群历史消息”作为产品预期告知，并用业务态兜底（如关键状态重拉接口）。
+
+## 5. 结果判定
+
+- 批量发消息压测时，`MESSAGE_RECEIVED` 回调中的每条 `event.data` 均被消费，无“只收第一条”问题。
+- 发送速率超过 `40` 条/秒时，低优先级消息优先被丢弃，高优先级关键通知到达率提升。
+- REST API 与 SDK 发送链路均已配置优先级字段（`MsgPriority` / `priority`）。
+- 应用后台超过 `2` 分钟后回前台，业务侧能通过兜底机制恢复关键业务状态。
+
+## 6. 常见误区
+
+- 误区 1：把 `MESSAGE_RECEIVED` 当作单条消息回调，只处理 `event.data[0]`。
+- 误区 2：高并发直播群不设置消息优先级，导致关键消息与刷屏消息同等级竞争。
+- 误区 3：把直播群当作漫游群使用，默认期望长时间后台后仍可补齐全部历史消息。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 在直播群（`AVChatRoom`）场景下出现“丢消息”现象，业务希望保证抽奖、商品上架/下架等重要消息不丢失。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- AVChatRoom 为什么会丢消息？
+- 直播群刷屏时怎么保证商品下架消息一定送达？
+- `MESSAGE_RECEIVED` 回调一次返回多条消息怎么处理？
+- 直播群后台后重连为什么拉不到之前消息？
+
+## 9. 参考来源（可选）
+
+- `MESSAGE_RECEIVED` 事件说明：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_RECEIVED`
+- SDK 消息优先级（`createTextMessage` 示例）：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#createTextMessage`
+- REST API `MsgPriority` 说明：`https://cloud.tencent.com/document/product/269/1629`

package/resource/knowledge/chat/best-practice/common/group-conversation-cleanup-on-system-notice.md

@@ -0,0 +1,67 @@
+---
+title: Web/小程序 Chat SDK 退群/解散群后会话残留移除方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [quitGroup, dismissGroup, deleteConversation, TIMGroupSystemNoticeElem, operationType, 会话列表, 退群, 解散群]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 退群/解散群后会话残留移除方案
+
+## 1. 核心结论
+
+- `quitGroup` / `dismissGroup` 后会话残留是 SDK 体验设计行为：登录态有效时，群会话仍可保留用于查看历史消息。
+- 要实现“彻底从会话列表移除”，需要在接收群系统通知（`TIMGroupSystemNoticeElem`）后主动调用 `deleteConversation`。
+- 删除触发条件由 `message.payload.operationType` 决定：`4`（被踢出群组）、`5`（群组被解散）、`8`（用户主动退群）。
+- 仅依赖 `quitGroup` / `dismissGroup` 的返回结果，不会自动删除会话列表项。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TIMGroupSystemNoticeElem` | 群系统通知类型 | 标识群成员变更、解散、退群等系统事件 |
+| `message.payload.operationType` | 通知动作码 | `4` 被踢出、`5` 群解散、`8` 主动退群 |
+| `deleteConversation` | 删除会话接口 | 满足触发条件时调用，用于从会话列表移除对应群会话 |
+| `quitGroup` / `dismissGroup` | 群管理动作 | 执行退群/解散，不负责会话列表彻底清理 |
+
+## 3. 机制/时序
+
+业务调用 `quitGroup` 或 `dismissGroup` -> SDK 保留对应群会话（登录态有效）-> 收到 `TIMGroupSystemNoticeElem` -> 业务根据 `operationType` 判断是否触发删除 -> 命中 `4/5/8` 时调用 `deleteConversation` -> 会话列表移除该群会话。
+
+## 4. 标准用法
+
+1. 无 UI 集成场景：直接通过 `chat.on` 监听 `MESSAGE_RECEIVED`，在回调中处理群系统通知。
+2. 含 UI 集成场景：先从 `TUILogin.getContext()` 拿到 `chat` 实例，再通过 `chat.on` 监听 `MESSAGE_RECEIVED` 获取系统通知。
+3. 在回调中筛选 `TIMGroupSystemNoticeElem` 类型消息。
+4. 读取 `message.payload.operationType`，仅对 `4`、`5`、`8` 进入删除分支。
+5. 根据群会话 ID 调用 `deleteConversation` 删除会话，并在成功后刷新会话列表状态，避免本地缓存残留。
+
+## 5. 结果判定
+
+- 调用 `quitGroup` 后，收到 `operationType=8` 通知并成功触发 `deleteConversation`。
+- 调用 `dismissGroup` 后，收到 `operationType=5` 通知并成功移除群会话。
+- 被管理员踢出群时，收到 `operationType=4` 后会话被自动清理。
+- 会话列表刷新后不再出现目标群会话，且不会因系统通知重复回显。
+
+## 6. 常见误区
+
+- 误区 1：认为 `quitGroup` / `dismissGroup` 会自动删除会话列表项。
+- 误区 2：收到群系统通知后未读取 `operationType` 就直接忽略。
+- 误区 3：只做本地 UI 删除，不调用 `deleteConversation`，导致会话再次出现。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 调用 `quitGroup` 或 `dismissGroup` 后，会话列表中的群聊会话仍然存在；收到系统消息“您已退出该群聊”后，会话又出现在列表中。业务侧需要在退群/解散群后彻底移除该群聊会话。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 调用 `quitGroup` 后为什么群会话还在会话列表？
+- `dismissGroup` 后会话为什么又回来了？
+- 收到“您已退出该群聊”后如何删除会话？
+- 群系统通知如何联动 `deleteConversation`？
+
+## 9. 参考来源（可选）
+
+- GroupSystemNoticePayload：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html#.GroupSystemNoticePayload`
+- deleteConversation：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#deleteConversation`

package/resource/knowledge/chat/best-practice/common/image-message-url-lifecycle.md

@@ -0,0 +1,63 @@
+---
+title: Chat SDK 图片消息 URL 的生命周期（blob 与 imageUrl）
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [sendMessage, createImageMessage, imageInfoArray, imageUrl, url, blob, https, 图片消息, 上传进度, 生命周期]
+version_range: ">=3.0.0"
+---
+
+# Chat SDK 图片消息 URL 的生命周期（blob 与 imageUrl）
+
+## 1. 核心结论
+
+- `imageInfoArray[x].url` 主要用于本地预览，发送成功后仍是 `blob:` 内存 URL。
+- 需要云端可访问 URL 时，读取发送成功返回消息中的 `imageInfoArray[x].imageUrl`。
+- 刷新并重新登录后，拉取漫游消息时，`imageInfoArray[x].url` 为服务端 URL。
+- 需要上传进度时，在 `createImageMessage` 时传入 `onProgress` 回调。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 阶段 | 语义 |
+|---|---|---|
+| `imageInfoArray[x].url` | 发送中/发送后 | 本地预览地址，可为 `blob:`，不保证自动更新为云端地址 |
+| `imageInfoArray[x].imageUrl` | 发送成功后 | 服务端可访问地址，作为对外可访问 URL 使用 |
+| `onProgress` | 上传过程中 | 文件上传进度回调，用于展示上传进度 |
+
+## 3. 机制/时序
+
+`createImageMessage` -> `sendMessage` -> 内部上传流程 -> 上传成功并发送到 IM 后台 -> 从返回消息读取 `imageInfoArray[x].imageUrl` -> 刷新重登后拉取漫游消息时 `imageInfoArray[x].url` 为服务端 URL。
+
+## 4. 标准用法
+
+1. 调用 `createImageMessage` 创建图片消息（如需进度，传入 `onProgress`）。
+2. 调用 `sendMessage` 发送消息。
+3. 发送成功后，从返回消息中读取 `imageInfoArray[x].imageUrl` 作为云端 URL。
+4. 前端渲染图片的正确方式：渲染消息时读取 `imageInfoArray[x].url` 即可，发送时使用 `blob` 地址能够更快渲染图片。
+
+## 5. 结果判定
+
+- 发送后检查同一条消息：
+  - `imageInfoArray[x].url` 仍为 `blob:`；
+  - `imageInfoArray[x].imageUrl` 为服务端可访问地址。
+- 刷新并重新登录后，拉取历史消息时，`imageInfoArray[x].url` 为服务端 URL。
+
+## 6. 常见误区
+
+- 误区 1：默认认为 `url` 会在上传后自动变成云端链接。
+
+## 7. 问题定义（检索辅助，极简）
+
+用户在发送图片消息后，看到 `imageInfoArray[x].url` 仍是 `blob:` 本地 URL，期望它自动变成腾讯云 `https` URL；同时希望明确上传完成后应读取哪个字段作为最终可访问地址。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 图片消息发送后 `url` 为什么还是 `blob:`？
+- 云端 `https` 图片地址应该从哪个字段取？
+- `sendMessage` 成功后如何拿图片最终 URL？
+- `imageInfoArray[x].url` 和 `imageInfoArray[x].imageUrl` 有什么区别？
+- 刷新后历史消息里的图片 URL 为什么变了？
+
+## 9. 参考来源（可选）
+
+- Message 结构文档：[Message](https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html)

package/resource/knowledge/chat/best-practice/common/login-repeat-2025-diagnosis.md

@@ -0,0 +1,65 @@
+---
+title: Web Chat SDK login 返回 2025（重复登录）排查与修复
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [login, 2025, 重复登录, repeatLogin, web, miniprogram, 并发调用, 防抖]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK login 返回 2025（重复登录）排查与修复
+
+## 1. 核心结论
+
+- `2025` 的直接原因是业务侧在短时间内连续调用 `login`，且 SDK 还未收到第一次登录请求的后台回包。
+- 在首次 `login` 发起后的约 `15s` 窗口内，若前一次登录仍未回包，SDK 会直接拦截后续 `login`，并返回 `2025`。
+- 如果 SDK 已经收到登录回包，后续使用同一 `userID` 再次调用 `login`，不会走 `2025` 拦截分支，而是在 `login.then` 中返回 `imResponse.data.repeatLogin = true`。
+- 解决方向是业务侧治理 `login` 调用逻辑：保证同一会话只存在一个进行中的 `login` 请求。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 错误码 `2025` | 重复登录拦截信号 | 前一次 `login` 未回包时，短时间内再次调用被 SDK 直接拦截 |
+| `imResponse.data.repeatLogin` | 重复登录标识 | SDK 已收到回包后，再次使用同一 `userID` 登录时在 `then` 中返回 `true` |
+| `login` in-flight 状态 | 并发控制关键状态 | 业务侧需确保同一时刻仅一个 `login` 在执行 |
+
+## 3. 机制/时序
+
+第一次调用 `login` -> SDK 发起登录请求 -> 后台回包未返回 -> 业务侧在约 `15s` 内再次调用 `login` -> SDK 直接拦截并返回 `2025`。
+第一次调用 `login` -> SDK 已收到后台回包 -> 业务侧再次使用同一 `userID` 调用 `login` -> 在 `login.then` 中拿到 `imResponse.data.repeatLogin = true`。
+
+## 4. 标准用法
+
+1. 业务侧实现登录单飞（single-flight）：同一 `userID` 在前一次 `login` 完成前禁止重复发起。
+2. 为 `login` 增加状态机（`idle`/`logging_in`/`logged_in`）或 Promise 复用，复用进行中的登录结果。
+3. 收到 `2025` 时不立即重试，先等待当前 in-flight 登录完成，再按结果决定后续动作。
+4. 在 `login.then` 中检查 `imResponse.data.repeatLogin`，按“已登录”分支处理，不重复初始化会话。
+
+## 5. 结果判定
+
+- 同一 `userID` 连续触发登录时，业务侧只发出一次真实 `login` 请求。
+- 压测快速点击登录入口，不再出现 `2025`。
+- 已回包后再次调用 `login` 时，可在 `then` 中稳定观察到 `repeatLogin` 标识并走预期分支。
+- 登录态初始化逻辑仅执行一次，无重复拉取会话或重复监听。
+
+## 6. 常见误区
+
+- 误区 1：收到 `2025` 后立即再次调用 `login`，造成重复拦截循环。
+- 误区 2：把 `2025` 与 `repeatLogin=true` 当成同一阶段错误处理。
+- 误区 3：页面 `onShow`、路由切换、重连回调中未做幂等保护，导致并发登录。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 调用 `login` 时，在短时间内重复触发登录请求，会返回 `2025`。业务侧需要明确：`2025` 在什么条件下触发，以及与 `imResponse.data.repeatLogin = true` 的区别。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Web IM SDK 调 `login` 为什么报 2025？
+- `login` 返回 2025 是什么含义？
+- 什么情况下会出现重复登录错误码 2025？
+- `repeatLogin=true` 和 `2025` 有什么区别？
+
+## 9. 参考来源（可选）
+
+- Chat SDK `login` 文档：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#login`

package/resource/knowledge/chat/best-practice/common/message-read-report-and-receipt.md

@@ -0,0 +1,72 @@
+---
+title: Web Chat SDK 会话已读上报和消息已读回执方案（setMessageRead 与 sendMessageReadReceipt）
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [setMessageRead, sendMessageReadReceipt, 已读回执, MESSAGE_READ_BY_PEER, MESSAGE_READ_RECEIPT_RECEIVED, needReadReceipt, 群消息已读]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK 会话已读上报和消息已读回执方案（setMessageRead 与 sendMessageReadReceipt）
+
+## 1. 核心结论
+
+- 进入会话后自动发送消息级已读回执的推荐流程是：先通过 `getMessageList` 拉漫游消息，再调用 `sendMessageReadReceipt` 上报对应消息已读。
+- `setMessageRead` 是会话维度已读上报：调用成功会清空当前会话未读数；单聊场景对端可通过 `MESSAGE_READ_BY_PEER` 更新消息已读状态。
+- `sendMessageReadReceipt` 是单条消息维度已读回执：不影响会话未读数，仅影响消息已读/未读状态；群消息要实现消息级已读状态必须使用该能力。
+- 消息已读回执能力有使用限制：体验版/标准版不可用；创建消息需设置 `needReadReceipt=true`；群已读回执要求群人数上限 `200` 且需在控制台开启群消息已读回执开关（控制台 > 功能配置 > 群组配置 > 群消息已读回执）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `setMessageRead` | 会话维度已读上报 | 清空当前会话未读数；单聊可触发对端 `MESSAGE_READ_BY_PEER` |
+| `sendMessageReadReceipt` | 消息维度已读回执 | 不清空会话未读数，只更新消息已读/未读状态 |
+| `needReadReceipt` | 消息已读回执开关 | 创建消息时必须设为 `true` 才能使用消息级回执 |
+| `MESSAGE_READ_BY_PEER` | 单聊对端已读事件 | 用于更新单聊消息已读状态 |
+| `MESSAGE_READ_RECEIPT_RECEIVED` | 消息回执接收事件 | 用于处理收到的消息已读回执更新 |
+
+## 3. 机制/时序
+
+进入会话 -> 调用 `getMessageList` 拉取漫游消息 -> 将消息列表传给 `sendMessageReadReceipt`（SDK 内部过滤处理）-> SDK 下发已读回执事件（如 `MESSAGE_READ_RECEIPT_RECEIVED`）-> 业务更新消息已读/未读展示。
+若调用 `setMessageRead`：会话未读数被清空；单聊对端可收到 `MESSAGE_READ_BY_PEER`。
+
+## 4. 标准用法
+
+1. 会话进入时先调用 `getMessageList` 拉取消息列表。
+2. 将 `getMessageList` 返回的消息列表直接传给 `sendMessageReadReceipt`，由 SDK 内部过滤并完成消息级已读上报。
+3. 仅在需要处理会话未读数时调用 `setMessageRead`，不要用它替代群消息已读回执。
+4. 创建需要回执的消息时设置 `needReadReceipt = true`。
+5. 订阅并处理 `MESSAGE_READ_BY_PEER`、`MESSAGE_READ_RECEIPT_RECEIVED`，同步更新消息已读状态。
+
+## 5. 结果判定
+
+- 进入群聊后，拉取到的消息可成功触发 `sendMessageReadReceipt`。
+- 调用 `sendMessageReadReceipt` 后，会话未读数不被清空，但消息已读状态发生更新。
+- 调用 `setMessageRead` 后，会话未读数被清空，单聊对端可观测到 `MESSAGE_READ_BY_PEER`。
+- 群聊已读场景下，已正确开通套餐、开启控制台开关，且群人数不超过 `200`。
+
+## 6. 常见误区
+
+- 误区 1：用 `setMessageRead` 代替 `sendMessageReadReceipt` 实现群消息已读状态。
+- 误区 2：未设置 `needReadReceipt=true` 就期望收到消息级已读回执。
+- 误区 3：未开通旗舰版以上套餐或未开启群消息已读回执开关就上线群已读能力。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web 端进入群聊会话后，如何自动发送已读回执给消息发送方？`setMessageRead` 和 `sendMessageReadReceipt` 的区别是什么？
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 进入会话后怎么自动上报已读？
+- 群聊已读/未读显示要用哪个接口？
+- `setMessageRead` 和 `sendMessageReadReceipt` 有什么区别？
+- 为什么调用 `setMessageRead` 后消息已读状态没有按预期变化？
+
+## 9. 参考来源（可选）
+
+- 套餐购买：`https://buy.cloud.tencent.com/avc?from=17182`
+- setMessageRead：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#setMessageRead`
+- sendMessageReadReceipt：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#sendMessageReadReceipt`
+- MESSAGE_READ_BY_PEER：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_READ_BY_PEER`
+- MESSAGE_READ_RECEIPT_RECEIVED：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_READ_RECEIPT_RECEIVED`

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`