@tencentcloud/sdk-mcp 1.6.7 → 1.7.0

package/resource/integration/roomkit/preset/vue/integration.md

@@ -181,13 +181,12 @@
 <div class="vsdk-text">
 
 <div class="vsdk-title">
-缺少您想要的功能？
-<span class="vsdk-badge">优先内测</span>
+有接入卡点？30 秒反馈
+<span class="vsdk-badge">全部选填</span>
 </div>
 
 <div class="vsdk-desc">
-如果您在使用视频会议 SDK 时遇到过问题，或希望支持新的能力，欢迎与我们分享。<br />
-您的反馈将帮助我们持续优化产品，并优先邀请有相关需求的用户参与新功能内测。
+正在了解或评估视频会议 SDK？UI、功能、文档或套餐开通如有卡点，欢迎填写反馈。
 </div>
 
 </div>
@@ -195,8 +194,8 @@
 </div>
 
 <div class="vsdk-card-right">
-<a class="vsdk-cta" href="https://wj.qq.com/s2/27306813/b61d/" target="_blank">
-填写问卷
+<a class="vsdk-cta" href="https://wj.qq.com/s2/27395009/ac34/" target="_blank">
+填写反馈
 </a>
 </div>
 
@@ -269,8 +268,8 @@ yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-
     <ConferenceMainViewH5 v-else-if="inRoom" />
     <div v-else class="entry">
       <TUIInput v-model="entry.userId" placeholder="请输入用户 ID" />
-      <TUIInput v-model="entry.userName" placeholder="请输入昵称" />
-      <TUIInput v-model="entry.roomId" placeholder="如 123456" />
+      <TUIInput v-model="entry.userName" placeholder="请输入昵称, 非必填" />
+      <TUIInput v-model="entry.roomId" placeholder="请输入房间 ID, 如 room_123456" />
       <TUIButton type="primary" :disabled="!entry.userId || !entry.roomId" @click="handleEnterRoom">进入会议</TUIButton>
     </div>
   </UIKitProvider>
@@ -348,14 +347,8 @@ yarn run dev
 **验证多人会议：**建议打开两个浏览器标签页，分别模拟不同用户进入同一房间，验证音视频互通与会中功能。操作步骤如下：
 
 **步骤1：**打开两个浏览器标签页，分别填写用户 ID `userA`、`userB` 及相同房间号 `room_123456`，点击 **进入会议**。`userA` 先进入时将自动创建房间并成为房主；`userB` 后进入时将作为参会者加入。
-| 测试用户 A | 测试用户 B |
-| --- | --- |
-|  |  |
 
 **步骤2：**测试用户均进入会中界面后，可在成员列表中互相看到对方；开启摄像头、麦克风，确认能否看到彼此的画面并听到声音。
-| 测试用户 A | 测试用户 B |
-| --- | --- |
-|  |  |
 
 **步骤3：**您还可以体验屏幕共享、聊天、成员管理等会中能力，确认多人场景下的基础功能正常。
 
@@ -363,11 +356,6 @@ yarn run dev
 
 快速接入章节以一体化示例帮助您完成首次进房体验。若需将会议能力集成至实际业务，可按会议流程分步集成。本节依次介绍 SDK 依赖安装、TUIRoomKit 组件引用、登录鉴权、创建与加入会议、离开会议、监听会议状态等核心能力的用法。
 
-> **推荐使用更高效的 AI 集成助手**
->
-> 我们为您提供 AI 集成助手：描述业务需求即可自动生成集成代码；接入过程中遇到问题，也可向 AI 咨询答疑。点击这里，立即体验 AI 集成
->
-
 ### 步骤1：安装 SDK 依赖
 
 在您的业务项目中安装 TUIRoomKit 及配套依赖包。
@@ -492,7 +480,7 @@ const startQuickMeeting = async () => {
 
 **适用场景：**适用于需要在未来特定时间召开的会议（如团队周会、线上培训等）。用户可在客户端提前设定会议标题、时间及受邀参会成员。
 
-**实现方式**：由客户端生成或向业务后台申请一个唯一的房间号，并配合会议时间等参数调用 `scheduleRoom` 接口提交预定。预定成功后，会议信息将同步至参与者的会议列表中。更多客户端预订会议能力请参考 无 UI 集成 > 预订房间。
+**实现方式**：由客户端生成或向业务后台申请一个唯一的房间号，并配合会议时间等参数调用 `scheduleRoom` 接口提交预定。预定成功后，会议信息将同步至参与者的会议列表中。更多客户端预订会议能力。
 ``` typescript
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
 
@@ -643,7 +631,6 @@ const enterDualMeeting = async (bizOrderId: string) => {
 ```
 
 > **说明：**
->
 > `conference.createAndJoinRoom` 内部封装了“房间不存在则创建并成为房主，已存在则加入并成为参会者”的逻辑，适用于双方对等发起的进房场景。
 >
 
@@ -733,7 +720,7 @@ onUnmounted(() => {
 
 ### 配置主题及语言
 
-通过配置 `App.vue` 中 `UIKitProvider` 的入参，修改主题及语言的默认值。更多自定义主题及语言请参考 UI 自定义 > 主题及语言。
+通过配置 `App.vue` 中 `UIKitProvider` 的入参，修改主题及语言的默认值。更多自定义主题及语言。
 | <code>UIKitProvider</code> 参数 | 可选值 | 默认值 |
 | --- | --- | --- |
 | theme | "light" \\| "dark" | "light" |
@@ -786,7 +773,7 @@ conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.SidebarLayout }
 conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.CinemaLayout });
 ```
 
-TUIRoomKit 默认内置以下视频流挂件，如您需要自定义视频流挂件，请参考 UI 自定义 > 视频布局及挂件 。
+TUIRoomKit 默认内置以下视频流挂件，如您需要自定义视频流挂件。
 
 ## 常见问题
 
@@ -829,7 +816,7 @@ TUIRoomKit 默认内置以下视频流挂件，如您需要自定义视频流挂
 
 ### 是否支持设置内网代理？
 
-支持。更多内网代理信息请参考 内网代理（Web）。
+支持。更多内网代理信息。
 
 ### 是否可以直接修改 TUIRoomKit 的底层源码？
 

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`

package/resource/knowledge/callkit/best-practice/common/callengine-log-level.md

@@ -0,0 +1,72 @@
+---
+title: TUICallEngine 设置日志输出级别
+product: call
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [TUICallEngine, setLogLevel, 日志级别, log level, 控制台日志, 关闭日志]
+version_range: ">=4.0.0"
+---
+
+# TUICallEngine 设置日志输出级别
+
+## 1. 核心结论
+
+- TUICallEngine 提供 `setLogLevel` 接口控制日志输出级别，创建实例后即可调用。
+- 接入阶段建议设为级别 0（全量日志），正式上线后设为级别 1（默认，关键信息）或更高。
+- 需要关闭日志时设为级别 4。
+
+## 2. 字段语义对照
+
+| 级别 | 值 | 说明 |
+|---|---|---|
+| 普通级别 | 0 | 日志量较多，接入调试时建议使用 |
+| 主要级别 | 1 | SDK 输出关键信息，**默认日志等级** |
+| 告警级别 | 2 | SDK 只输出告警和错误级别的日志 |
+| 错误级别 | 3 | SDK 只输出错误级别的日志 |
+| 无日志级别 | 4 | SDK 将不打印任何日志 |
+
+## 3. 机制/时序
+
+创建 `TUICallEngine` 实例 -> 调用 `setLogLevel` 设置日志级别 -> 后续 SDK 按指定级别输出日志。调用一次全局生效，无需重复设置。
+
+## 4. 标准用法
+
+1. 通过 `TUICallEngine.createInstance(options)` 创建引擎实例。
+2. 调用 `tuiCallEngine.setLogLevel(level)` 设置日志级别。
+3. 接入调试时使用级别 0，正式上线后根据需要调整为级别 1-4。
+
+```javascript
+import TUICallEngine from '@trtc/call-engine-lite-js'; // Web
+// import TUICallEngine from '@trtc/call-engine-lite-wx'; // 小程序
+
+const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: 0 });
+tuiCallEngine.setLogLevel(0); // 接入调试：全量日志
+```
+
+## 5. 结果判定
+
+- 调用 `setLogLevel` 后，控制台日志量按目标级别输出。
+- 级别 4 下 SDK 不再输出任何日志。
+- 无需重启或重新初始化即可生效。
+
+## 6. 常见误区
+
+- 误区 1：认为 `setLogLevel` 需要在 `init` 之后才能调用（实际上创建实例后即可调用）。
+- 误区 2：使用级别 4 后期望还能收到关键告警（级别 4 关闭所有日志）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUICallEngine 用户希望控制 SDK 日志输出量：接入时查看完整日志、上线后减少日志、或完全关闭日志输出。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallEngine 怎么关闭日志？
+- TUICallEngine 日志级别怎么设置？
+- `setLogLevel` 各取值含义是什么？
+- 接入阶段怎么查看 TUICallEngine 完整日志？
+- 小程序 TUICallEngine 日志级别和 Web 端一样吗？
+
+## 9. 参考来源（可选）
+
+- Web `setLogLevel` 文档：`https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html#setLogLevel`
+- 小程序 `setLogLevel` 文档：`https://cloud.tencent.com/document/product/647/78761#setLogLevel`