@tencentcloud/sdk-mcp 1.6.8 → 1.7.0

package/resource/integration/callkit/preset/ios/integration.md

@@ -393,3 +393,4 @@ TUICallKit.createInstance().enableMuteMode(enable: true)
 ### Xcode 出现 **Sandbox: rsync** 编译报错？
 
 可以在 **Build Settings** 中把 **User Script Sandboxing** 设置为 **NO：**
+

package/resource/integration/chat/preset/flutter/integration.md

@@ -2,6 +2,7 @@ TUIKit Flutter 是基于腾讯云 IM SDK 的一套 Flutter UI 组件库，提供
 
 ## 问卷反馈
 
+> **说明：**
 > **花 30 秒，帮 Flutter TUIKit 变得更好用！**
 >
 > 正在接入、已经跑通、还是卡住了？都欢迎你填写 [Flutter TUIKit 接入体验问卷](https://wj.qq.com/s2/27299252/ff84/)**。**

package/resource/integration/livekit/preset/live/vue/live-player-desk-integration.md

@@ -12,11 +12,11 @@
 
 ### 前提条件
 
-请您先阅读准备工作，请确保集成对应组件并实现登录。
+请您先阅读 准备工作，请确保集成对应组件并实现登录。
 
 ### 集成观众观看页面
 
-新建`live-player.vue`，作为观看页面的入口，负责播放直播画面、切换分辨率、画中画等，您根据指引按需引入观看端的各功能模块。将以下代码复制到该文件即可：
+新建 `live-player.vue`，作为观看页面的入口，负责播放直播画面、切换分辨率、画中画等，您根据指引按需引入观看端的各功能模块。将以下代码复制到该文件即可：
 ``` typescript
 <template>
   <UIKitProvider language="zh-CN" theme="dark">
@@ -92,18 +92,20 @@ onMounted(async () => {
 
 ### 启动并运行示例
 
-执行 `npm run dev` 成功后，在浏览器地址栏输入本地访问地址（例如`https://localhost:5173/live-player`，具体端口号可能因项目配置不同而有所差异），即可看到观看页面，输入对应的房间号（**liveId**），即可观看对应的直播间画面。
+执行 `npm run dev` 成功后，在浏览器地址栏输入本地访问地址（例如 `https://localhost:5173/live-player`，具体端口号可能因项目配置不同而有所差异），即可看到观看页面，输入对应的房间号（**liveId**），即可观看对应的直播间画面。
 ``` bash
 npm run dev
 ```
 
-> **开启直播的两种方式**
+> **开启直播的两种方式：**
 >
-> 集成观看页面成功后，可通过以下任一方式开播效果：
+> 集成观看页面成功后，可通过以下任一方式体验开播效果：
 >
 > - 在线开播网站：打开[在线开播网站](https://web.sdk.qcloud.com/trtc/livekit/pusher/index.html#/)，输入对应 **sdkAppId** 等信息，点击直播列表右上角的**开始直播**按钮进入开播页面，开始一场直播。
 > - 集成开播页面：在您的项目中接入 主播开播（Web 桌面浏览器）组件进行开播。
-> ⚠️ 观看请使用与开播端不同的用户 ID，否则先登录的设备会被强制下线。
+
+> **注意：**
+> 观看请使用与开播端不同的用户 ID，否则先登录的设备会被强制下线。
 >
 
 ## UI 自由定制
@@ -130,8 +132,8 @@ import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
 | <strong>类别</strong> | <strong>功能</strong> | <strong>描述</strong> | <strong>组件详细定制指引</strong> |
 | --- | --- | --- | --- |
 | <strong>素材管理</strong> | 自定义素材管理区域展示 | <strong>支持：</strong><br>- <strong>调整展示 Icon 的大小、颜色或对 Icon 进行替换。</strong> | <a href="https://cloud.tencent.com/document/product/647/123838">媒体源配置面板</a> |
-| <strong>在线观众</strong> | 自定义观众信息展示 | <strong>支持：</strong><br>- <strong>展示/隐藏观众等级。</strong><br>- <strong>观众信息字体、颜色 UI 自定义设置。</strong><br>- <strong>替换为您需要的 Icon 风格。</strong> | <a href="https://cloud.tencent.com/document/product/647/123834">视频源编辑画板</a> |
-| <strong>消息列表</strong> | 自定义消息弹幕区域展示 | <strong>支持：</strong><br>- <strong>展示/隐藏聊天输入区域。</strong><br>- <strong>支持 UI 定制聊天气泡风格、定制观众等级等内容。</strong> | <a href="https://cloud.tencent.com/document/product/647/123836">聊天弹幕组件</a> |
+| <strong>在线观众</strong> | 自定义观众信息展示 | <strong>支持：</strong><br>- <strong>展示或隐藏观众等级。</strong><br>- <strong>观众信息字体、颜色 UI 自定义设置。</strong><br>- <strong>替换为您需要的 Icon 风格。</strong> | <a href="https://cloud.tencent.com/document/product/647/123834">视频源编辑画板</a> |
+| <strong>消息列表</strong> | 自定义消息弹幕区域展示 | <strong>支持：</strong><br>- <strong>展示或隐藏聊天输入区域。</strong><br>- <strong>支持 UI 定制聊天气泡风格、定制观众等级等内容。</strong> | <a href="https://cloud.tencent.com/document/product/647/123836">聊天弹幕组件</a> |
 
 ## 常见问题
 
@@ -141,7 +143,7 @@ import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
 
 #### 自动播放失败表现
 
-当用户对该站点的媒体互动指数 (MEI, Media Engagement Index) 未达到阈值时，企图自动播放有声视频会失败。在 SDK 默认情况下，当检测到自动播放失败时，会弹窗引导用户与页面产生交互（如点击**确认**按钮）。产生交互后，浏览器策略即被满足，有声视频即可正常播放。
+当用户对该站点的媒体互动指数 (MEI, Media Engagement Index) 未达到阈值时，企图自动播放有声视频会失败。在 SDK 默认情况下，当检测到自动播放失败时，会弹窗引导用户与页面产生交互（例如点击**确认**按钮）。产生交互后，浏览器策略即被满足，有声视频即可正常播放。
 
 #### 解决方案：自定义处理自动播放失败
 

package/resource/integration/livekit/preset/live/vue/live-pusher-integration.md

@@ -12,11 +12,11 @@
 
 ### 前提条件
 
-请您先阅读准备工作，请确保集成对应组件并实现登录。
+请您先阅读 准备工作，请确保集成对应组件并实现登录。
 
 ### 集成主播开播页面
 
-新建`live-pusher.vue`，作为开播页面的入口，负责**整体布局**、**开播 / 停播**、**登录初始化**，并按需引入底部控制栏的各功能模块。将以下代码复制到该文件即可：
+新建 `live-pusher.vue`，作为开播页面的入口，负责**整体布局**、**开播 / 停播**、**登录初始化**，并按需引入底部控制栏的各功能模块。将以下代码复制到该文件即可：
 ``` typescript
 <template>
   <UIKitProvider language="zh-CN" theme="dark">
@@ -44,10 +44,10 @@
           </div>
           <div class="live-controls">
             <div class="bottom-panel">
-              <!-- <MediaDeviceSetting />// 媒体设置能力请参考本文高级功能集成部分
-              <CoGuestButton />          // 连麦观众能力请参考本文高级功能集成部分
-              <OrientationSwitch />      // 布局设置请参考本文高级功能集成部分
-              <LayoutSwitch />           // 横竖屏推流能力请参考本文高级功能集成部分 -->
+              <!-- <MediaDeviceSetting />// 媒体设置能力请参考本文功能模块集成部分
+              <CoGuestButton />          // 连麦观众能力请参考本文功能模块集成部分
+              <OrientationSwitch />      // 布局设置请参考本文功能模块集成部分
+              <LayoutSwitch />           // 横竖屏推流能力请参考本文功能模块集成部分 -->
             </div>
             <TUIButton type="primary" v-if="!currentLive?.liveId" @click="handleStartLive">开始直播</TUIButton>
             <TUIButton color="red" v-else @click="handleStopLive">停止直播</TUIButton>
@@ -128,7 +128,7 @@ onMounted(async () => {
 
 ### 启动并运行示例
 
-执行 `npm run dev` 成功后，在浏览器地址栏输入本地访问地址（例如`https://localhost:5173/live-pusher`，具体端口号可能因项目配置不同而有所差异），即可看到开播页面，添加媒体源素材点击开始直播即可开启您的直播。
+执行 `npm run dev` 成功后，在浏览器地址栏输入本地访问地址（例如 `https://localhost:5173/live-pusher`，具体端口号可能因项目配置不同而有所差异），即可看到开播页面，添加媒体源素材点击开始直播即可开启您的直播。
 ``` bash
 npm run dev
 ```
@@ -139,12 +139,14 @@ npm run dev
 >
 > - 在线观看网站：打开[在线观看网站](https://web.sdk.qcloud.com/trtc/livekit/player/index.html#/)，输入对应 **sdkAppId** 等信息，在直播列表中找到并进入你的直播间。
 > - 集成观看页面：在您的项目中接入 观众观看（Web 桌面浏览器）或者 观众观看（H5 移动端浏览器）组件观看。
-> ⚠️ 观看请使用与开播端不同的用户 ID，否则先登录的设备会被强制下线。
+
+> **注意：**
+> 观看请使用与开播端不同的用户 ID，否则先登录的设备会被强制下线。
 >
 
 ## 功能模块
 
-以下模块均为可独立复制的组件，需要先通过集成主播开播页面，然后根据您的业务需求将下列各个模块的代码直接粘贴进对应的注释部分去即可。
+以下模块均为可独立复制的组件，需要先通过 集成主播开播页面，然后根据您的业务需求将下列各个模块的代码直接粘贴进对应的注释部分去即可。
 
 ### 支持媒体设置能力
 
@@ -669,5 +671,3 @@ import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
 | --- | --- | --- |
 | <strong>观众观看</strong> | 实现观众进入主播的直播间后观看直播，实现观众连麦 、直播间信息、在线观众、弹幕显示等功能。 | 观众观看 |
 | <strong>直播列表</strong> | 展示直播列表界面和功能，包含直播列表，房间信息展示功能。 | 直播列表 |
-
-###

package/resource/knowledge/callkit/best-practice/callkit-miniprogram/uniapp-shrink.md

@@ -0,0 +1,64 @@
+---
+title: uniapp 打包微信小程序 TUICallKit 体积裁剪方案
+product: call
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [TUICallKit, uniapp, 小程序, 体积裁剪, 插件裁剪, 瘦身, 移除插件, GroupCallView]
+version_range: ">=4.0.0"
+---
+
+# uniapp 打包微信小程序 TUICallKit 体积裁剪方案
+
+## 1. 核心结论
+
+- TUICallKit 默认包含完整插件，核心通话引擎（375 KB）和 1v1 通话（111 KB）为必选模块，不可裁剪。
+- 铃声插件（23 KB）和多人通话插件（27 KB）可按需移除，移除后不影响单人通话功能。
+- 通过删除插件注册代码和对应 pages 配置实现裁剪。
+
+## 2. 字段语义对照
+
+| 模块 | 大小 | 是否必选 | 移除方式 |
+|---|---|---|---|
+| 核心通话引擎 | 375 KB | 必选 | — |
+| 1v1 单人通话 | 111 KB | 必选 | — |
+| 铃声插件 | 23 KB | 可裁剪 | 删除 `this.registerPlugin(useRingPlugin())` |
+| 多人通话插件 | 27 KB | 可裁剪 | 删除 `this.registerPlugin(useGroupCallPlugin())` + pages.json 中 `GroupCallView` 页面 |
+
+## 3. 机制/时序
+
+TUICallKit 初始化时通过 `registerPlugin` 注册各功能插件 -> 插件被注册后打包进小程序代码 -> 删除对应注册代码后，该插件不会打包 -> 小程序包体积相应减小。
+
+## 4. 标准用法
+
+1. 在 TUICallKit 初始化代码中找到插件注册部分。
+2. 删除 `this.registerPlugin(useRingPlugin())` 移除铃声插件。
+3. 删除 `this.registerPlugin(useGroupCallPlugin())` 移除多人通话插件，同步删除 `pages.json` 中的 `GroupCallView` 页面配置。
+
+## 5. 结果判定
+
+- 铃声插件移除后，通话中不再播放铃声提示，但通话功能不受影响。
+- 多人通话插件移除后，无法发起和参与多人通话，单人通话正常。
+- 小程序打包后体积减少约 50 KB。
+- 功能正常：单人通话（发起、接听、挂断）完整可用。
+
+## 6. 常见误区
+
+- 误区 1：试图移除核心通话引擎或 1v1 模块（必选，移除后无法通话）。
+- 误区 2：只删除插件注册代码，忘记同步删除 `pages.json` 中的 `GroupCallView` 页面配置，导致编译报错。
+- 误区 3：认为裁剪后还能使用多人通话功能（移除多人通话插件后只能使用单人通话）。
+
+## 7. 问题定义（检索辅助，极简）
+
+uniapp 打包微信小程序时，TUICallKit 默认插件过多导致包体积大，希望按需移除不必要的功能模块。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 小程序怎么瘦身？
+- uniapp TUICallKit 如何移除铃声插件？
+- TUICallKit 多人通话怎么裁剪？
+- 微信小程序 TUICallKit 包太大怎么优化？
+- 删除 `GroupCallView` 后多人通话还能用吗？
+
+## 9. 参考来源（可选）
+
+- 微信小程序 TUICallKit（uniapp）文档：`https://cloud.tencent.com/document/product/647/78912#802b0c00-0ea7-4ca3-8892-62f47f06c92d`

package/resource/knowledge/callkit/best-practice/common/call-autoplay-blocked.md

@@ -0,0 +1,81 @@
+---
+title: Web TUICallKit 弹出"恢复播放"弹窗的原因与处理
+product: call
+frameworks: [react, vue, web]
+scope: platform_common
+tags: [TUICallKit, 恢复播放, 自动播放, webview, autoplay, enableAutoPlayDialog, callExperimentalAPI, 无声, vue2.6, vue2.7, vue3]
+version_range: ">=4.0.0"
+---
+
+# Web TUICallKit 弹出"恢复播放"弹窗的原因与处理
+
+## 1. 核心结论
+
+- 浏览器限制自动播放：在用户与网页产生交互前禁止播放带声音的媒体，Web TUICallKit 检测到播放失败后弹出"恢复播放"弹窗，需用户点击"恢复"。
+- 此问题多出现在 webview 中（如 App 内嵌 H5）。
+- 不推荐关闭该弹窗，关闭后可能出现无声问题。如需关闭可通过 `callExperimentalAPI` 设置 `enableAutoPlayDialog: 0`。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `enableAutoPlayDialog` | 自动播放弹窗开关 | `1` 开启（默认），`0` 关闭 |
+| `callExperimentalAPI` | 调用实验性 API | 通过 TRTC 实例调用，用于设置 `enableAutoPlayDialog` |
+| `getTUICallEngineInstance()` | 获取 TUICallEngine 实例 | 从 `TUICallKitAPI` 获取底层引擎 |
+| `getTRTCCloudInstance()` | 获取 TRTC 实例 | 从 TUICallEngine 获取 TRTC 云实例 |
+
+## 3. 机制/时序
+
+用户进入通话页面 -> TUICallKit 尝试自动播放音频 -> 浏览器拦截自动播放 -> 播放失败 -> TUICallKit 弹出"恢复播放"弹窗 -> 用户点击"恢复" -> 音频正常播放。
+
+webview 场景下，因宿主 App 对自动播放的限制更严格，此问题更容易出现。
+
+## 4. 标准用法
+
+不推荐关闭该弹窗。如业务场景确定需要关闭：
+
+1. 从 `TUICallKitAPI` 获取 TUICallEngine 实例。
+2. 从 TUICallEngine 获取 TRTC 云实例。
+3. 通过 TRTC 实例的 `callExperimentalAPI` 设置 `enableAutoPlayDialog: 0`。
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+const trtcCloudInstance = TUICallKitAPI?.getTUICallEngineInstance()?.getTRTCCloudInstance();
+const params = {
+  api: 'enableAutoPlayDialog',
+  params: { enable: 0 },
+};
+trtcCloudInstance?.callExperimentalAPI(JSON.stringify(params));
+```
+
+## 5. 结果判定
+
+- 不关闭弹窗：通话时弹出"恢复播放"提示，用户点击后音频正常播放。
+- 关闭弹窗：通话时不再弹出提示，音频在浏览器允许后自动播放（若仍被拦截则无声）。
+
+## 6. 常见误区
+
+- 误区 1：认为弹窗是 TUICallKit 的 bug（实际是浏览器自动播放限制策略）。
+- 误区 2：直接关闭弹窗后期望所有场景都能正常播放（关闭弹窗不解除自动播放限制，无声问题仍可能发生）。
+- 误区 3：在 TUICallKit 初始化前调用 `enableAutoPlayDialog`（需在获取到 TRTC 实例后调用）。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web TUICallKit 通话时弹出"恢复播放"弹窗，用户需点击才能听到声音，如何解决及是否可关闭弹窗。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 通话没有声音怎么办？
+- 为什么 TUICallKit 会弹出"恢复播放"提示？
+- 如何关闭 TUICallKit 的自动播放弹窗？
+- webview 中 TUICallKit 无声怎么处理？
+- `enableAutoPlayDialog` 怎么设置？
+
+## 9. 参考来源（可选）
+
+- TUICallKit Web 自动播放说明：`https://cloud.tencent.com/document/product/647/78769#066739b9-fb33-4f11-a21c-66edd91be64a`

package/resource/knowledge/callkit/best-practice/common/call-message-in-chat.md

@@ -0,0 +1,84 @@
+---
+title: 在无 UI Chat SDK 项目中集成 TUICallKit 时如何显示音视频通话消息
+product: call
+frameworks: [react, vue, miniprogram, android, ios, flutter, uni-app, web]
+scope: platform_common
+tags: [TUICallKit, call-message, custom message, actionType, cmd, call_end, 通话消息渲染]
+version_range: ">=2.0.0"
+---
+
+# 在无 UI Chat SDK 项目中集成 TUICallKit 时如何显示音视频通话消息
+
+## 1. 核心结论
+
+- 通话消息是 TUICallKit 通话过程中由后台通过 Chat REST API 补发的自定义消息，各平台可通过 Chat SDK 的消息接收事件或拉取历史消息获取。
+- 通话过程中的实时状态（振铃、接听、挂断）由 TUICallKit 的事件监听处理，不依赖 Chat 消息。
+- 通过 `actionType` 判断通话结果类型（挂断/取消/拒绝/超时），通过 `cmd` 区分语音/视频/忙线。
+- 通话时长从 `call_end` 字段获取，单位秒。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `actionType` | 通话事件类型 | 1=发起/挂断，2=取消，3=接听，4=拒绝，5=超时未接听 |
+| `cmd` | 通话指令细分 | `videoCall` 视频通话、`audioCall` 语音通话、`hangup` 挂断、`line_busy` 忙线 |
+| `call_end` | 通话时长 | `actionType=1` 且 `cmd=hangup` 时存在，单位秒 |
+| `MESSAGE_RECEIVED` | 消息接收事件 | Chat SDK 统一事件，含通话自定义消息 |
+| `getMessageList` | 拉取历史消息 | 进入会话后拉取，通话消息也在返回列表中 |
+
+### actionType 与 cmd 对照表
+
+| 场景 | actionType | cmd | 备注 |
+|---|---|---|---|
+| 发起通话 | 1 | `videoCall` 或 `audioCall` | 主叫发出 |
+| 已接听 | 3 | — | 被叫接听后触发 |
+| 通话已结束 | 1 | `hangup` | 有一方挂断；`call_end` 含通话时长 |
+| 取消通话 | 2 | — | 主叫在接听前取消 |
+| 拒绝通话 | 4 | — | 被叫主动拒绝 |
+| 对端忙线 | 4 | `line_busy` | 被叫正在通话中 |
+| 超时未接听 | 5 | — | 被叫在规定时间内未接听 |
+
+## 3. 机制/时序
+
+主叫发起通话 -> TUICallKit 通过信令通道（非 Chat 消息）建立通话连接 -> 通话过程中，每发生一次状态变化（取消/接听/拒绝/超时/挂断），TUICallKit 后台都会通过 REST API 向 Chat SDK 补发一条自定义消息 -> 双方通过 `MESSAGE_RECEIVED` 收到补发消息 -> 按 `actionType` 和 `cmd` 区分事件类型并更新 UI。
+
+通话过程本身（发起、接听、取消、拒绝、超时）不依赖 Chat 自定义消息通知；Chat 消息仅用于通话结束后在会话中展示通话记录。
+
+## 4. 标准用法
+
+1. 通过 Chat SDK 获取补发的通话自定义消息（监听消息接收事件或拉取历史消息，接口名因平台而异，但语义一致）。
+2. 读取 `message.actionType` 和 `message.cmd` 判断通话事件类型。
+3. 通话挂断消息（`actionType=1, cmd=hangup`）读取 `message.call_end` 显示通话时长。
+4. 其他 `actionType` 值用于判断通话未接通的原因（取消/拒绝/忙线/超时），更新 UI 展示。
+
+## 5. 结果判定
+
+- 通话各状态变化后，能通过 Chat SDK 收到补发的通话自定义消息。
+- `actionType` 与 `cmd` 能正确反映通话状态变化。
+- `call_end` 值准确反映通话实际时长。
+- `actionType` 与 `cmd` 能正确反映通话状态变化。
+- `call_end` 值准确反映通话实际时长。
+
+## 6. 常见误区
+
+- 误区 1：将通话消息当作普通自定义消息处理，没有读取 `actionType` 做状态区分。
+- 误区 2：只处理 `MESSAGE_RECEIVED`，不处理 `getMessageList` 拉取的离线通话消息。
+- 误区 3：通话时长从消息的 `timestamp` 差值计算（应直接从 `call_end` 字段读取）。
+- 误区 4：未处理 `line_busy` 场景，导致忙线被当作普通拒绝。
+
+## 7. 问题定义（检索辅助，极简）
+
+在无 UI Chat SDK 项目中集成 TUICallKit，如何通过 Chat SDK 获取并渲染音视频通话消息（发起/接听/挂断/取消/拒绝/超时/忙线）。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 通话消息怎么解析？
+- `actionType` 各值代表什么意思？
+- 通话结束后怎么拿到通话时长？
+- `MESSAGE_RECEIVED` 收到通话消息怎么区分是发起还是挂断？
+- 如何判断被叫忙线？
+- 小程序中通话消息和 Web 端解析方式一样吗？
+
+## 9. 参考来源（可选）
+
+- 音视频通话信令字段说明：`https://cloud.tencent.com/document/product/647/84363`

package/resource/knowledge/callkit/best-practice/common/call-vs-calls.md

@@ -0,0 +1,114 @@
+---
+title: TUICallKit React/Vue 发起音视频通话：calls 与 call/groupCall 的区别与用法
+product: call
+frameworks: [react, vue, web]
+scope: platform_common
+tags: [call, calls, groupCall, userIDList, TUICallKit, init, v4.x, calls-uikit, vue2, vue2.6, vue2.7, vue3, call和calls区别, callMediaType, 参数1和2, 数字字面量, 通话类型, 枚举常量, 发起通话]
+version_range: ">=4.0.0"
+---
+
+# TUICallKit React/Vue 发起音视频通话：calls 与 call/groupCall 的区别与用法
+
+## 1. 核心结论
+
+- TUICallKit React / Vue **v4.x 必须使用 `calls`** 发起单聊/多人通话。
+- `call`、`groupCall` 在 v4.0.0 起已废弃。
+- 发起通话前必须先完成 `init`，否则会出现调用失败或状态异常。
+- `type` 推荐使用 `CallMediaType` 枚举常量，不建议继续使用数字字面量（1/2）作为主写法。
+- `userIDList` 必须传数组（单聊也是传数组）；需要和 Chat 群联动时再传 `chatGroupID`。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TUICallKitAPI` | v4.x 入口对象 | 从 `@trtc/calls-uikit-{react\|vue}` 引入，替代旧版 `TUICallKitServer` |
+| `calls` | 发起通话（v4.x） | 单聊/多人通话统一入口，
+| `call` / `groupCall` | 发起通话（旧版） | v4.0.0 前使用，v4.x 已废弃 |
+| `CallMediaType` | 通话媒体类型枚举 | `AUDIO` 语音、`VIDEO` 视频 |
+| `roomID` / `strRoomID` | 房间号 | 互斥，两者选一；不要混用 |
+
+## 3. 机制/时序
+
+初始化 -> 登录 -> 调用 `calls` 发起通话 -> 等待被叫接听 -> 通话建立 -> 通话结束。
+
+v4.x 新项目直接从 `calls` 开始；旧项目迁移时需将 `call`/`groupCall` 替换为 `calls`，并将 `TUICallKitServer` 替换为 `TUICallKitAPI`。
+
+## 4. 标准用法
+
+1. 从对应平台的包引入 `TUICallKitAPI`。
+2. 调用 `TUICallKitAPI.init({ SDKAppID, userID, userSig })` 完成初始化。
+3. 调用 `TUICallKitAPI.calls({ userIDList, type })` 发起通话。
+4. 在 `catch` 分支处理通话发起失败的情况。
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+// 1. 初始化
+TUICallKitAPI.init({ SDKAppID, userID, userSig });
+
+// 2. 发起通话（单聊或多人）
+try {
+  await TUICallKitAPI.calls({
+    userIDList: ['jack', 'tom'],
+    type: CallMediaType.VIDEO_CALL
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call. Reason:${error}`);
+}
+```
+
+`calls` 参数说明：
+
+| 参数 | 类型 | 是否必填 | 含义 |
+|---|---|---|---|
+| userIDList | Array\<String\> | 是 | 被呼叫的用户列表 |
+| type | CallMediaType | 是 | 通话的媒体类型（`AUDIO`/`VIDEO`） |
+| chatGroupID | String | 否 | Chat 群组 ID |
+| roomID | Number | 否 | 数字房间号，范围 [1, 2147483647] |
+| strRoomID | String | 否 | 字符串房间号。与 roomID 互斥，两者都填时优先 roomID |
+| timeout | Number | 否 | 通话超时时间，默认 30s，范围 10s-600s |
+| userData | String | 否 | 自定义扩展字段，被叫可在 `ON_CALL_RECEIVED` 中获取 |
+| offlinePushInfo | Object | 否 | 自定义离线消息推送参数 |
+
+CallMediaType 取值：
+
+| CallMediaType 类型 | 常量值 | 描述 |
+|---|---|---|
+| `CallMediaType.AUDIO` | 1 | 语音通话 |
+| `CallMediaType.VIDEO` | 2 | 视频通话 |
+
+## 5. 结果判定
+
+- `TUICallKitAPI.calls` 调用成功后，被叫用户能收到通话邀请。
+- 被叫接听后通话建立，双方可正常音视频通话。
+- 通话超时或被叫拒绝时，`catch` 分支能收到明确错误信息。
+
+## 6. 常见误区
+
+- 误区 1：在 v4.x 里继续调用 `call` / `groupCall`（已废弃，不会报错但功能不完整）。
+- 误区 2：把单聊写成 `userID` 字段而不是 `userIDList`（v4.x 不再支持单字符串传参）。
+- 误区 3：`roomID` 与 `strRoomID` 混用（两者互斥且不互通）。
+- 误区 4：`type` 长期使用数字字面量（1/2）而非 `CallMediaType` 枚举常量。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUICallKit React/Vue v4.x 用户询问如何发起音视频通话，以及 `calls` 与旧版 `call`/`groupCall` 的区别与迁移方式。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit React/Vue 怎么发起通话？
+- `calls` 和 `call` 有什么区别？
+- v4.x 的 `userIDList` 参数怎么传？
+- `CallMediaType` 和数字 1/2 可以混用吗？
+- 旧项目从 `TUICallKitServer.call` 迁移到 `TUICallKitAPI.calls` 要注意什么？
+- `call` 传入的 `type` 参数 1 和 2 分别代表什么？
+- `callMediaType` 参数 1 和 2 代表语音还是视频？
+- TUICallKit 通话类型数字 1 和 2 是什么意思？
+
+## 9. 参考来源（可选）
+
+- TUICallKit React/Vue：`https://cloud.tencent.com/document/product/647/81015`

package/resource/knowledge/callkit/best-practice/common/callengine-call-flow.md

@@ -0,0 +1,128 @@
+---
+title: TUICallEngine 通话邀请接收与发起流程
+product: call
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [TUICallEngine, ON_CALL_RECEIVED, calls, accept, reject, 通话邀请, call-engine-lite, userData, callMediaType]
+version_range: ">=4.0.0"
+---
+
+# TUICallEngine 通话邀请接收与发起流程
+
+## 1. 核心结论
+
+- 接收通话邀请只监听 `TUICallEvent.ON_CALL_RECEIVED`，**不要监听 Chat SDK 的 `MESSAGE_RECEIVED` 自行解析通话邀请**。
+- 发起通话使用 `TUICallEngine.calls()`，参数中 `userIDList` 传数组、`type` 传媒体类型。
+- 收到邀请后用 `accept()` 接听或 `reject()` 拒绝，扩展信息通过 `userData` 字符串传递。
+- Web 与小程序接口一致，仅包名不同（Web: `@trtc/call-engine-lite-js`，小程序: `@trtc/call-engine-lite-wx`）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TUICallEvent.ON_CALL_RECEIVED` | 接收通话邀请事件 | 被叫收到来电时触发，不要从 Chat 自定义消息解析 |
+| `calls({userIDList, type, ...})` | 发起通话 | 主叫调用，单聊/多人通话统一入口 |
+| `accept()` | 接听通话 | 被叫在收到邀请后调用 |
+| `reject()` | 拒绝通话 | 被叫在收到邀请后调用 |
+| `userData` | 自定义扩展信息 | 主叫传入的字符串，被叫从 `ON_CALL_RECEIVED` 事件中读取 |
+| `callMediaType` | 通话媒体类型 | `ON_CALL_RECEIVED` 事件中携带，1=语音、2=视频 |
+| `inviteID` | 邀请 ID | 标识一次通话邀请，用于关联后续事件 |
+| `callId` | 通话 ID | 本次通话的唯一标识 |
+| `callRole` | 角色 | 主叫（`call`）/ 被叫（`called`） |
+
+### ON_CALL_RECEIVED 事件字段
+
+| 参数 | 类型 | 含义 |
+|---|---|---|
+| callerId | String | 邀请者 |
+| calleeIdList | Array\<String\> | 同时还被邀请的人 |
+| isFromGroup | Boolean | 是否是群组通话 |
+| inviteData | Object | 呼叫数据 |
+| inviteID | String | 邀请 ID |
+| userData | String | 扩展字段，主叫传入的自定义信息 |
+| callId | String | 本次通话的唯一 ID |
+| roomID | Number | 音视频房间 ID |
+| callMediaType | Number | 通话媒体类型（1=语音，2=视频） |
+| callRole | String | 角色：主叫/被叫 |
+
+### calls 参数说明
+
+| 参数 | 类型 | 是否必填 | 含义 |
+|---|---|---|---|
+| userIDList | Array\<String\> | 是 | 被呼叫的用户列表 |
+| type | Number | 是 | 1=语音，2=视频（`CallMediaType`） |
+| userData | String | 否 | 自定义扩展信息，被叫可从 `ON_CALL_RECEIVED` 读取 |
+| timeout | Number | 否 | 超时时间（秒），默认 30 |
+| roomID | Number | 否 | 数字房间号，范围 [1, 2147483647] |
+| strRoomID | String | 否 | 字符串房间号，与 roomID 互斥 |
+| chatGroupID | String | 否 | Chat 群组 ID，群聊中多人通话时填写 |
+| offlinePushInfo | Object | 否 | 自定义离线消息推送参数 |
+
+## 3. 机制/时序
+
+主叫调用 `calls()` 发起邀请 -> SDK 通过信令通道发送邀请 -> 被叫触发 `ON_CALL_RECEIVED` -> 被叫调用 `accept()` 接听或 `reject()` 拒绝 -> 通话建立/结束。
+
+通话过程中的实时状态变化通过 TUICallEngine 的事件监听处理，不依赖 Chat 消息。
+
+## 4. 标准用法
+
+1. 创建 `TUICallEngine` 实例并登录。
+2. 主叫调用 `calls()` 发起通话邀请。
+3. 被叫监听 `ON_CALL_RECEIVED` 事件，收到后调用 `accept()` 或 `reject()`。
+4. 扩展信息通过 `userData` 字符串传递，被叫从事件中读取。
+
+```javascript
+// Web: @trtc/call-engine-lite-js
+// 小程序: @trtc/call-engine-lite-wx  （API 一致，仅包名不同）
+import { TUICallEngine, TUICallEvent } from '@trtc/call-engine-lite-js';
+
+// 创建实例并登录
+const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: xxx, tim: timInstance });
+await tuiCallEngine.login({ userID, userSig });
+
+// 主叫：发起通话邀请
+await tuiCallEngine.calls({
+  userIDList: ['user_bob'],
+  type: 2,                    // 1=语音 2=视频
+  userData: '{"ext":"info"}',
+  timeout: 30,
+});
+
+// 被叫：监听通话邀请
+tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, (event) => {
+  console.log('来电', event);
+  // 展示接听 UI，随后调用 accept() 或 reject()
+  tuiCallEngine.accept({ inviteID: event.inviteID, roomID: event.roomID });
+});
+```
+
+## 5. 结果判定
+
+- 主叫调用 `calls()` 后，被叫能收到 `ON_CALL_RECEIVED` 事件。
+- 被叫调用 `accept()` 后通话建立，`reject()` 后通话被拒绝。
+- `userData` 在主叫传入后，被叫能从事件中正确读取。
+- 通话过程中的其他事件（接听、挂断、超时等）通过 TUICallEngine 的事件机制正常触发。
+
+## 6. 常见误区
+
+- 误区 1：监听 `MESSAGE_RECEIVED` 自行解析通话邀请（应使用 `ON_CALL_RECEIVED`）。
+- 误区 2：使用 `businessID` / 底层 payload 格式等 SDK 内部字段（无官方公开文档，不要编造）。
+- 误区 3：认为 `customData` 字段存在（v4.x 使用 `userData` 字符串传递自定义信息）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUICallEngine Web/小程序用户需要了解如何接收通话邀请、发起通话以及传递自定义扩展信息。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallEngine 怎么接收通话邀请？
+- TUICallEngine 怎么发起通话？
+- `ON_CALL_RECEIVED` 各字段含义是什么？
+- `calls` API 参数怎么填？
+- TUICallEngine 如何传递自定义扩展信息？
+- 小程序 TUICallEngine 通话邀请处理和 Web 端一样吗？
+
+## 9. 参考来源（可选）
+
+- Web TUICallEngine：`https://cloud.tencent.com/document/product/647/78757`
+- 小程序 TUICallEngine：`https://cloud.tencent.com/document/product/647/78761`