@tencentcloud/sdk-mcp 1.6.8 → 1.7.1

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`

package/resource/knowledge/callkit/best-practice/common/callkit-get-engine-instance.md

@@ -0,0 +1,87 @@
+---
+title: Web TUICallKit 如何获取 TUICallEngine 实例
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, getTUICallEngineInstance, 引擎实例, 底层引擎, 微信原生小程序, uniapp 小程序]
+version_range: ">=4.0.0"
+---
+
+# Web TUICallKit 如何获取 TUICallEngine 实例
+
+## 1. 核心结论
+
+- 通过 `TUICallKitAPI.getTUICallEngineInstance()` 获取 TUICallEngine 底层引擎实例。
+- 获取引擎实例后，可通过 `.on()` 监听通话事件（如 `ON_CALL_BEGIN`、`ON_CALL_RECEIVED` 等）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TUICallKitAPI` | TUICallKit API 入口 | 从对应平台的包引入，提供 `getTUICallEngineInstance()` |
+| `getTUICallEngineInstance()` | 获取 TUICallEngine 实例 | 返回引擎实例，用于监听事件和调用底层 API |
+| `TUICallEngine` | 引擎实例 | 通过该方法获取，用于注册事件回调 |
+
+## 3. 机制/时序
+
+TUICallKit 初始化完成后 -> 调用 `TUICallKitAPI.getTUICallEngineInstance()` 获取引擎实例 -> 使用引擎实例注册事件监听或调用底层 API。
+
+需确保 TUICallKit 初始化完成后调用，否则可能返回 `undefined`。
+
+## 4. 标准用法
+
+1. 从对应平台的包引入 `TUICallKitAPI`。
+2. 调用 `TUICallKitAPI.getTUICallEngineInstance()` 获取引擎实例。
+3. 使用引擎实例注册事件监听或调用其他底层方法。
+
+```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
+// uniapp 小程序: @trtc/calls-uikit-wx-uniapp
+// 微信原生小程序: @trtc/calls-uikit-wx  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+const tuiCallEngine = TUICallKitAPI.getTUICallEngineInstance();
+
+if (tuiCallEngine) {
+  // 获取成功，可监听事件或调用底层 API
+  tuiCallEngine.on(TUICallEvent.ON_CALL_BEGIN, (event) => {
+    console.log('通话建立', event);
+  });
+} else {
+  console.warn('TUICallEngine 实例未就绪，请确认 TUICallKit 已完成初始化');
+}
+```
+
+## 5. 结果判定
+
+- `getTUICallEngineInstance()` 返回非 `undefined` 的引擎实例，可正常使用。
+- 通过引擎实例注册的事件回调能正常触发。
+- 多次调用返回同一个引擎实例（单例）。
+
+## 6. 常见误区
+
+- 误区 1：在 TUICallKit 初始化完成前调用 `getTUICallEngineInstance()`（返回 `undefined`）。
+- 误区 2：认为每次调用 `getTUICallEngineInstance()` 都会创建新的引擎实例（实际为单例，多次调用返回同一实例）。
+- 误区 3：从小程序的引擎包直接创建实例（应通过 `TUICallKitAPI.getTUICallEngineInstance()` 获取，而非自行创建）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUICallKit 用户需要获取底层 TUICallEngine 实例，用于监听通话事件或调用底层 API。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 怎么获取 TUICallEngine 实例？
+- `getTUICallEngineInstance` 怎么用？
+- TUICallKit Vue 如何获取 TUICallEngine 实例？
+- TUICallKit React 怎么监听底层 TUICallEngine 事件？
+- 小程序 TUICallKit 能获取 TUICallEngine 吗？
+- TUICallKit 获取引擎实例后能做什么？
+
+## 9. 参考来源（可选）
+
+- React `getTUICallEngineInstance`：`https://cloud.tencent.com/document/product/647/81015#getTUICallEngineInstance`
+- Vue `getTUICallEngineInstance`：`https://cloud.tencent.com/document/product/647/81015#getTUICallEngineInstance`
+- 小程序 `getTUICallEngineInstance`：`https://cloud.tencent.com/document/product/647/78760#getTUICallEngineInstance`

package/resource/knowledge/callkit/best-practice/common/callkit-get-roomid.md

@@ -0,0 +1,83 @@
+---
+title: 如何获取通话的房间号
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, roomID, 房间号, ON_CALL_BEGIN, ON_CALL_END, callengine, 获取房间号, 通话房间号, Roomid, onCallBegin]
+version_range: ">=4.0.0"
+---
+
+# TUICallKit 如何获取通话的房间号
+
+## 1. 核心结论
+
+- 获取通话房间号的方式：通过监听 TUICallEngine 的事件（`ON_CALL_BEGIN`、`ON_CALL_END` 等）即可获取，`event.roomID` 即为当前通话的房间号。
+- 需要先通过 `TUICallKitAPI.getTUICallEngineInstance()` 获取 TUICallEngine 实例，再调用 `on()` 监听事件。
+- React、Vue、小程序接口一致，仅包名不同。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TUICallEvent.ON_CALL_BEGIN` | 通话建立事件 | 通话接通时触发，事件中携带 `roomID` |
+| `TUICallEvent.ON_CALL_END` | 通话结束事件 | 通话结束时触发，事件中携带 `roomID` |
+| `TUICallKitAPI.getTUICallEngineInstance()` | 获取 TUICallEngine 实例 | 从 TUICallKit 获取底层引擎实例 |
+| `engine.on(event, handler)` | 监听引擎事件 | 通过引擎实例注册事件回调 |
+| `event.roomID` | 通话房间号 | 事件参数中的房间号字段 |
+
+## 3. 机制/时序
+
+TUICallKit 初始化 -> 通话接通（`ON_CALL_BEGIN`）-> 通话进行中 -> 通话结束（`ON_CALL_END`）。`ON_CALL_BEGIN` 和 `ON_CALL_END` 等通话相关事件均携带 `roomID`，在回调中读取即可。
+
+## 4. 标准用法
+
+1. 通过 `TUICallKitAPI.getTUICallEngineInstance()` 获取 TUICallEngine 实例。
+2. 调用 `engine.on()` 监听 `TUICallEvent.ON_CALL_BEGIN` 或 `ON_CALL_END` 事件。
+3. 在回调中读取 `event.roomID` 获取房间号。
+
+```javascript
+// Web: @trtc/call-engine-lite-js
+// 小程序: @trtc/call-engine-lite-wx  （API 一致，仅包名不同）
+import { TUICallEvent } from "@trtc/call-engine-lite-js";
+
+const handleOnCallBegin = function(event) {
+  // event.roomID 即为当前通话的房间号
+  console.log('通话建立，房间号：', event.roomID);
+};
+
+TUICallKitAPI.getTUICallEngineInstance().on(
+  TUICallEvent.ON_CALL_BEGIN,
+  handleOnCallBegin
+);
+```
+
+## 5. 结果判定
+
+- 通话建立后，`ON_CALL_BEGIN` 回调触发，`event.roomID` 返回有效的房间号。
+- 通话结束后，`ON_CALL_END` 回调触发，也可读取 `event.roomID`。
+- `roomID` 值在通话期间保持不变。
+
+## 6. 常见误区
+
+- 误区 1：在 TUICallKit 初始化完成前调用 `getTUICallEngineInstance()` 获取实例（需确保初始化完成后再获取）。
+- 误区 2：认为 `roomID` 在通话过程中会变化（同一通话的房间号是固定的）。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web TUICallKit React/Vue/小程序用户需要获取当前通话的房间号，用于日志记录或与其他服务关联。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 怎么获取房间号？
+- 通话建立时如何拿到 roomID？
+- `ON_CALL_BEGIN` 事件怎么监听？
+- TUICallKit React 获取通话房间号的方法是什么？
+- 小程序 TUICallKit 怎么拿 roomID？
+- 如何获取通话的房间号 Roomid？
+- Web TUICallKit 如何获取通话的房间号？
+- 通话房间号怎么拿？
+
+## 9. 参考来源（可选）
+
+- Web `ON_CALL_BEGIN` 文档：`https://cloud.tencent.com/document/product/647/78758#ON_CALL_BEGIN`
+- 小程序 `ON_CALL_BEGIN` 文档：`https://cloud.tencent.com/document/product/647/81012#ON_CALL_BEGIN`

package/resource/knowledge/callkit/best-practice/common/callkit-limitations.md

@@ -0,0 +1,37 @@
+---
+title: TUICallKit 限制说明
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, 限制, 不支持, 离线推送, 支付宝, 头条小程序, 企业微信, 桌面端, 兼容性]
+version_range: ">=2.0.0"
+---
+
+# TUICallKit 限制说明
+
+## 1. 核心结论
+
+| 问题 | 结论 |
+|---|---|
+| Web TUICallKit 能否接收离线推送消息？ | Web TUICallKit 不支持接收离线推送消息 |
+| 微信小程序 TUICallKit 能否运行到支付宝、头条小程序？ | 不能，仅支持运行到微信小程序 |
+| 微信小程序 TUICallKit 能否运行到企业微信里？ | 不能，仅支持运行到微信小程序 |
+| 微信小程序 TUICallKit 能否运行到 PC 桌面端微信里？ | 不能，仅支持运行到微信小程序 |
+| 微信小程序 TUICallKit 能否接收离线推送消息？ | 微信小程序 TUICallKit 不支持接收离线推送消息 |
+
+## 3. 机制/时序
+
+TUICallKit 各平台的能力边界由底层平台限制决定。微信小程序依赖微信原生能力，无法跨平台运行；Web 端受浏览器自动播放策略和离线推送机制的限制。
+
+## 7. 问题定义（检索辅助，极简）
+
+用户咨询 TUICallKit 在不同平台/场景下的能力边界，确认是否支持离线推送、跨平台运行等。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 支持离线推送吗？
+- 微信小程序 TUICallKit 能在支付宝上用吗？
+- TUICallKit 小程序能在企业微信里用吗？
+- TUICallKit 微信小程序支持 PC 端微信吗？
+- TUICallKit Web 端有没有离线消息通知？
+- TUICallKit 小程序只支持微信吗？

package/resource/knowledge/callkit/best-practice/common/callkit-user-register-and-kicked.md

@@ -0,0 +1,103 @@
+---
+title: TUICallKit 用户注册与多实例被踢问题说明
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, 用户注册, init, userSig, 自动创建用户, 多实例登录, 被踢, KICKED_OUT, 排查, 同一浏览器, 多实例, web多实例]
+version_range: ">=4.0.0"
+---
+
+# TUICallKit 用户注册与多实例被踢问题说明
+
+## 1. 核心结论
+
+### 用户注册
+
+- TUICallKit **没有独立的前端注册接口**。用户注册通过 `init` 接口完成：传入 `userID` 和 `userSig` 即可完成鉴权和登录。
+- 首次使用后端签发的 `userID` 和 `userSig` 登录 TUICallKit 后，如果该 `userID` 在腾讯云 IM 中不存在，系统会自动创建该用户。
+- 也可以在 IM 控制台批量导入用户，然后使用已导入的 `userID` 和对应的 `userSig` 登录。
+
+### 多实例被踢
+
+- 同一 `userID` 在不同浏览器标签页或不同设备上同时登录时，默认会被踢下线（`KICKED_OUT`），原因是 Chat SDK Web 端默认只允许一个实例在线。
+- 在 Chat 控制台开启 **Web 多实例登录** 后，同一 `userID` 可在多个标签页或设备上同时在线，不会被踢。
+- 不同 `userID` 在同一浏览器登录不受此限制影响，不会互相踢下线。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `init` | 初始化并注册用户 | 传入 `SDKAppID`、`userID`、`userSig` 完成鉴权 |
+| `userID` | 用户标识 | 由业务后端签发或自定义，首次登录时自动创建用户 |
+| `userSig` | 用户签名 | 由业务后端签发，用于鉴权 |
+| `KICKED_OUT` | 被踢下线事件 | 同一账号/多实例登录时触发 |
+| Web 多实例登录 | 控制台配置项 | 开启后同一浏览器可同时登录多个账号 |
+
+## 3. 机制/时序
+
+### 用户注册流程
+
+后端生成 `userID` + `userSig` -> 前端调用 `init({ SDKAppID, userID, userSig })` -> TUICallKit 使用 Chat SDK 登录 -> 若用户不存在则自动创建 -> 登录成功。
+
+### 多实例被踢机制
+
+同一 `userID` 在标签页 A 登录 -> 同一浏览器新开标签页 B 登录同一 `userID` -> Chat 后台检测到同多实例登录 -> 踢掉标签页 A -> 标签页 A 收到 `KICKED_OUT` 事件。
+
+## 4. 标准用法
+
+### 用户注册与初始化
+
+```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
+// uniapp 小程序: @trtc/calls-uikit-wx-uniapp
+// 微信原生小程序: @trtc/calls-uikit-wx  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.init({
+  SDKAppID: 0,         // 控制台获取的 SDKAppID
+  userID: 'user_xxx',  // 业务后端签发的用户 ID
+  userSig: 'xxx',      // 业务后端签发的用户签名
+});
+```
+
+### 开启 Web 多实例登录（解决被踢）
+
+1. 登录腾讯云 IM 控制台。
+2. 进入目标应用的功能配置页面。
+3. 开启 **Web 多实例登录** 开关。
+4. 保存后生效，无需重启客户端。
+
+## 5. 结果判定
+
+- 调用 `init` 后登录成功，无报错。
+- 控制台开启 Web 多实例后，同一 `userID` 可在多个标签页或设备上同时在线。
+- 未开启时，同一 `userID` 在新标签页登录后旧标签页收到 `KICKED_OUT` 事件。
+
+## 6. 常见误区
+
+- 误区 1：认为 TUICallKit 有独立的前端注册 API（实际通过 `init` 完成注册+登录）。
+- 误区 2：被踢后认为是 TUICallKit 的 bug（实际是 Chat SDK 的多端登录限制）。
+- 误区 3：不同 origin 也会被踢（不同 origin 视为不同实例，不受影响）。
+- 误区 4：不同 `userID` 在同一浏览器登录也会被踢（实际多实例限制针对同一 `userID`，不同 `userID` 互不影响）。
+- 误区 4：认为 `KICKED_OUT` 只能通过关闭其他登录来解决（开启 Web 多实例登录即可避免）。
+
+## 7. 问题定义（检索辅助，极简）
+
+用户咨询 TUICallKit Web 端用户注册方式（是否有独立注册接口、是否自动创建用户），以及同一浏览器多账号被踢的原因与解决方案。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUICallKit 用户注册接口是什么？
+- 首次登录会不会自动创建用户？
+- 同一浏览器两个账号同时登录被踢怎么办？
+- `KICKED_OUT` 怎么排查？
+- 不同域名登录会被踢吗？
+- 怎么让多个用户同时登录同一个页面？
+
+## 9. 参考来源（可选）
+
+- TUICallKit `init` 接口：`https://cloud.tencent.com/document/product/647/81015#init`
+- IM 控制台 Web 多实例配置：`https://console.cloud.tencent.com/im`

package/resource/knowledge/callkit/core-sdk/android/answer-call.md

@@ -827,3 +827,4 @@ class CallActivity : AppCompatActivity() {
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/android/make-call.md

@@ -912,3 +912,4 @@ MainScope().launch {
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/flutter/answer-call.md

@@ -1122,3 +1122,4 @@ iOS 端支持通过底层 TRTC 引擎实现应用外画中画功能。当应用
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/flutter/make-call.md

@@ -1195,3 +1195,4 @@ CallStore.shared.state.selfInfo.addListener(() {
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/ios/answer-call.md

@@ -1171,3 +1171,4 @@ class CallViewController: UIViewController {
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/ios/make-call.md

@@ -1272,3 +1272,4 @@ private func observeSelfCallStatus() {
 ### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
 
 单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的20条群消息，如果存在通话邀请，则触发来电邀请事件。
+

package/resource/knowledge/callkit/core-sdk/ios/offline-push.md

@@ -1,4 +1,4 @@
-本文档将指导您如何基于 TIMPush 服务实现 VoIP 推送功能，适用于使用 AtomicXCore 进行无 UI 集成的场景。
+本文档将指导您如何基于 [TIMPush](https://cloud.tencent.com/document/product/269/133003) 服务实现 VoIP 推送功能，适用于使用 AtomicXCore 进行无 UI 集成的场景。
 
 > **注意：**
 > - 使用 **VoIP** 推送功能首先需要 开通 TIMPush 服务。