@tencentcloud/sdk-mcp 1.6.7 → 1.7.0

package/resource/knowledge/push/integration/unreal-engine.md

@@ -1,30 +1,25 @@
+## 前提条件
+
+开始接入前，请先完成对应原生平台的推送前提配置：请参见 [iOS 前提条件](https://cloud.tencent.com/document/product/269/100627#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6) 和 [Android 前提条件](https://cloud.tencent.com/document/product/269/100626#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6)。
+
 ## 操作步骤
 
 ### 步骤1: 集成 TIMPush
 
-完成 [厂商配置](https://cloud.tencent.com/document/product/269/123436) 后集成推送插件，下载 [TIMPush](https://github.com/TencentCloud/TIMSDK/tree/master/UE5/Push/pushdemo/Plugins/TIMPush) 并拷贝到项目的 `Plugins` 目录下，在项目主模块的 Build.cs 文件中，引入 TIMPush。
-| 拷贝目录 | 引入插件 |
-| --- | --- |
-|  |  |
+各原生平台厂商配置后集成推送插件，下载 [TIMPush](https://github.com/TencentCloud/TIMSDK/tree/master/UE5/Push/pushdemo/Plugins/TIMPush) 并拷贝到项目的 `Plugins` 目录下，在项目主模块的 Build.cs 文件中，引入 TIMPush。
 
 ### 步骤2: 推送参数配置
 
 【iOS】
 
-请将您在厂商配置步骤中，获取到的 iOS APNs 推送证书， 上传至 IM 控制台。
-
-IM 控制台会为您分配一个证书 ID，见下图：
+2. 设置 `businessID`：请在 UE4 Editor 中打开“项目设置”，搜索查找 `Additional Plist Data` 并将下面文本修改后复制进入文本框中，其中 `YourBusinessID` 是必填项，而 `YourGroupID` 是当您需要统计推送的抵达和点击数据时需要修改的值
 
-设置 businessID：
-
-请在 UE4 Editor 中打开“项目设置”，搜索查找 `Additional Plist Data` 并将下面文本修改后复制进入文本框中，其中 `YourBusinessID` 是必填项，而 `YourGroupID` 是当您需要统计推送的抵达和点击数据时需要修改的值
 ``` plaintext
 <key>businessID</key><string>YourBusinessID</string><key>TIMPushAppGroupID</key><string>YourGroupID</string>
 ```
 
-开启远程推送能力：
+3. 开启远程推送能力。完成证书 ID 配置之后，您需要开启应用的 Push Notifications 能力：
 
-完成证书 ID 配置之后，您需要开启应用的 Push Notifications 能力：
 - 如果您的 UE 引擎是从源代码自行编译构建的，您可以通过 “项目设置 > iOS 中勾选 Enable Remote Notifications Support” 来开启对应能力；
 
 - 如果您的 UE 引擎是从 Epic Game 下载的，您可以通过打开 “`<proj_dir>/Config/DefaultEngine.ini`” ，在脚本的 `IOSRuntimeSettings` 中添加：
@@ -37,11 +32,7 @@ bEnableRemoteNotificationsSupport=True
 - 或者，您也可以选择在项目根目录中使用 Xcode 打开 UE 生成的 YourProject.xcworkspace，在 Project > Target 中，点击 Signing & Capabilities 选项，点击左上角 Capability，搜索添加 Push Notifications 能力到您的项目中
 
 【Android】
-
-完成控制台厂商推送信息填写后，下载并添加配置文件到工程。将下载的 `timpush-configs.json` 文件添加到 TIMPush 的 `Source/ThirdParty/TIMPushLibrary/Android/TIMPush/Assets` 目录下。
-| 下载配置文件 | 拷贝路径 |
-| --- | --- |
-|  |  |
+1. 完成厂商配置后，在 [腾讯云即时通信 IM 控制台](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 下载并添加配置文件到工程。将下载的 `timpush-configs.json` 文件添加到 TIMPush 的 `Source/ThirdParty/TIMPushLibrary/Android/TIMPush/Assets` 目录下。
 
 ### 步骤3: 客户端厂商配置
 
@@ -99,7 +90,6 @@ APL 相关配置 TIMPush 已配置好，只需要替换成应用自己的配置
 按照厂商方法，集成对应的 plugin 和 json 配置文件。
 
 > **注意：**
->
 > 以下荣耀的适配仅 7.7.5283 及以上版本需要配置。
 >
 
@@ -161,13 +151,6 @@ APL 相关配置 TIMPush 已配置好，只需要替换成应用自己的配置
 ### 步骤4：处理消息点击回调，并解析参数
 
 如果您需要自定义解析收到的远程推送，您可按照如下方法实现：
-
-> **注意：**
->
-> 1. 注册回调时机必须放在程序入口函数中。
-> 2. 控制台配置点击后续动作按如下配置，选择:**打开应用内指定界面，**请勿修改使用默认值。
->
-
 ``` cpp
 class DemoPushListener: public PushListener {
 public:
@@ -219,6 +202,11 @@ listener.SetCallback(
 PushManager::GetInstance()->AddPushListener(&listener);
 ```
 
+> **注意：**
+> 1. 注册回调时机必须放在程序入口函数中。
+> 2. 控制台配置点击后续动作按如下配置，选择: **打开应用内指定界面，**请勿修改使用默认值。
+>
+
 ### 步骤5：注册推送插件
 
 调用接口推送注册成功后，就可以收到离线推送通知了。
@@ -269,83 +257,36 @@ PushManager::GetInstance()->RegisterPush(您的 sdkAppId, "您的 appKey", callb
 
 ### 步骤6：消息推送触达统计
 
-如果您需要统计触达数据，请按照如下完成配置：
-
-【华为】
-
-回执地址：`https://api.im.qcloud.com/v3/offline_push_report/huawei`
-
-> **注意：**
->
-> 华为推送证书 ID <= 11344时，使用华为推送 v2 版本接口，不支持触达和点击回执，请重新生成更新证书 ID。
->
-
-【荣耀】
-
-回执地址：`https://api.im.qcloud.com/v3/offline_push_report/honor`
-
-【vivo】
-
-|回调地址配置|回执 ID 配置到 IM 控制台|
-|---------|---------|
-|<br>回执地址：`https://api.im.qcloud.com/v3/offline_push_report/vivo`||
-
-【魅族】
-
-|打开回执开关|配置回执地址|
-|---------|---------|
-|||
+如果你需要统计 Android 设备触达数据，请按照 华为/荣耀/vivo/魅族 配置。
 
-回执地址：`https://api.im.qcloud.com/v3/offline_push_report/meizu`
+1. 在上文的推送参数配置章节中，将“YourGroupID”修改为自己的 App Group ID。
 
-> **注意：**
->
-> 打开回执开关后，请务必确保回执地址正确配置。不配置或者配置地址错误，都会影响推送功能。
->
-
-【iOS】
-1. 如果您需要统计推送的抵达和点击数据，您需要在上文的 “项目设置” 中将“YourGroupID”修改为您自己的 App Group ID （生成方式可参见 厂商配置-生成 App GroupID）。
+2. 参考 iOS 配置消息触达统计 完成 App Group ID、Notification Service Extension 和 mutable-content 配置。
 
-2. 在完成 App Group ID 的配置后，您需要使用 Xcode 打开 UE 在项目目录生成的 xcworkspace 文件，并参考 厂商配置-生成 App GroupID-步骤四 中的方法配置您的 App Group ID。之后，请在 Xcode 项目中的 `Editor - Add Target` 中开启 Notification Service Extension Target。
+3. 将项目根目录的 Plugins-TIMPush-Source-ThirdParty-TIMPushLibrary-iOS 路径中的两个 framework 压缩包解压缩，并在 Xcode 项目中将内部的 .framework 文件夹添加到您的 pushservice target 之中。
 
-3. 您还需要将项目根目录的 `Plugins-TIMPush-Source-ThirdParty-TIMPushLibrary-iOS` 路径中的两个 framework 压缩包解压缩，并在 Xcode 项目中将内部的 .framework 文件夹添加到您的 pushservice target 之中。
+4. 在 Notification Service Extension 的 -didReceiveNotificationRequest:withContentHandler: 方法中调用推送抵达率统计函数:
 
-4. 您现在可以在 [Notification Service Extension](https://github.com/TencentCloud/TIMSDK/blob/master/iOS/Demo/pushservice/NotificationService.m) 的 `-didReceiveNotificationRequest:withContentHandler:` 方法中调用推送抵达率统计函数:
+   ``` objectivec
+   @implementation NotificationService
 
-``` objectivec
-@implementation NotificationService
+   - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
+       //appGroup 标识当前主 APP 和 Extension 之间共享的 APP Group，需要在主 APP 的 Capability 中配置 App Groups 能力。
+       //格式为group + [主bundleID]+ key
+       //如group.com.tencent.im.pushkey
+       NSString * appGroupID = kTIMPushAppGroupKey;
+       __weak typeof(self) weakSelf = self;
+       [TIMPushManager handleNotificationServiceRequest:request appGroupID:appGroupID callback:^(UNNotificationContent *content) {
+           weakSelf.bestAttemptContent = [content mutableCopy];
+           // Modify the notification content here...
+           // self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
+           weakSelf.contentHandler(weakSelf.bestAttemptContent);
+       }];
+   }
 
-- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
-    //appGroup 标识当前主 APP 和 Extension 之间共享的 APP Group，需要在主 APP 的 Capability 中配置 App Groups 能力。
-    //格式为group + [主bundleID]+ key
-    //如group.com.tencent.im.pushkey
-    NSString * appGroupID = kTIMPushAppGroupKey;
-    __weak typeof(self) weakSelf = self;
-    [TIMPushManager handleNotificationServiceRequest:request appGroupID:appGroupID callback:^(UNNotificationContent *content) {
-        weakSelf.bestAttemptContent = [content mutableCopy];
-        // Modify the notification content here...
-        // self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
-        weakSelf.contentHandler(weakSelf.bestAttemptContent);
-    }];
-}
+   @end
+   ```
 
-@end
-```
-
-   > **注意：**
-   >
-   > 1. 上报推送触达数据，需要开启 mutable-content 开关来支持 iOS 10 的 Extension 功能。
-   >
-   > 2. 数据详情可在推送数据页面查看，推送数据页面仅限 [购买推送插件](https://console.cloud.tencent.com/im/plugin/TIMPush)  后使用。
-
-其余支持厂商不需要配置，FCM 暂不支持推送统计功能。
+   其余支持厂商不需要配置，FCM 暂不支持推送统计功能。
 
-恭喜您已经完成了推送插件的接入，需要提醒您：推送插件**试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）**。为避免影响您业务正常使用，请提前 [购买](https://buy.cloud.tencent.com/avc)/[续费](https://console.cloud.tencent.com/account/renewal)。
-
-> **说明：**
->
-> 1. 厂商离线通道都有 [消息分类机制](https://cloud.tencent.com/document/product/269/100649)，不同类型也会有不同的推送策略。
-> - 如果推送需求属于 IM 类型推送，想要推送及时触达，需要按照厂商规则设置自己应用为对应的推送类型，会归类为高优先级的系统消息类型或者重要消息类型。
-> - 反之，离线推送会有数量和频次的限制，可能不会及时推送到设备。
-> 2. 接入完成收不到推送，请先自助使用 [排查工具](https://cloud.tencent.com/document/product/269/100629) 查看下具体原因。推送指标数据查看，请使用 [数据统计](https://cloud.tencent.com/document/product/269/100628) 查询。
-> 3. 全员/标签推送功能请参见：[REST API 接口 - 发起全员/标签推送](https://cloud.tencent.com/document/product/269/100634)。
+   接入完成收不到推送，请使用 [排查工具](https://cloud.tencent.com/document/product/269/100629) 查看具体原因。

package/resource/knowledge/roomkit/best-practice/common/room-ghost-member.md

@@ -0,0 +1,75 @@
+---
+title: TUIRoomKit 异常退出后成员仍显示在列表的原因与清理
+product: room
+frameworks: [react, vue, web, android, ios, flutter]
+scope: platform_common
+tags: [TUIRoomKit, 异常退出, 幽灵成员, 心跳检测, 离线检测, 踢出房间, kick_user_out, disconnect回调, 成员列表, 房间清理]
+version_range: ">=2.0.0"
+---
+
+# TUIRoomKit 异常退出后成员仍显示在列表的原因与清理
+
+## 1. 核心结论
+
+- 用户异常退出（杀进程、断网、关页未走 leave）后，成员仍显示在远端列表，是**视频会议 SDK 后台心跳离线检测**的预期行为。
+- 现行规则：后台在**心跳丢失约 5～6 分钟**后才将异常退出的用户移出房间，远端此时才收到离开通知并更新成员列表。
+- **不能默认把心跳设得很短**：网络抖动时容易被误踢出房，影响正常会议体验。
+- 若业务需要更快清理幽灵成员：方案一（提工单调心跳至约 2 分钟）或方案二（用 IM 断线回调 + `kick_user_out` 立即踢出）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 心跳离线检测 | 检测用户在线状态 | 后台检测用户是否心跳丢失 |
+| 心跳丢失 | 用户异常退出的信号 | 杀进程/断网/关页未走 leave 时心跳丢失 |
+| 幽灵成员 | 异常退出但仍显示的用户 | 约 5～6 分钟后被移出房间 |
+| `kick_user_out` | 踢出房间成员 | 业务后台主动调用立即清理 |
+| `disconnect` 回调 | 断线回调 | IM 服务端感知用户离线 |
+| 心跳时长调整 | 后台配置 | 提工单可调至约 2 分钟 |
+
+## 3. 机制/时序
+
+用户异常退出（杀进程、断网、关页未走 leave） -> 后台检测到心跳丢失 -> 约 5～6 分钟后将用户移出房间 -> 远端收到离开通知，更新成员列表。
+
+心跳时长默认不能太短，避免网络抖动导致误踢。若业务需要更快清理：
+
+- **方案一**：提工单调整后台心跳检测时长至约 2 分钟。
+- **方案二**：业务后台根据 IM `disconnect` 回调感知离线后，主动调用 `kick_user_out` 立即清理幽灵成员。
+
+## 4. 标准用法
+
+1. **方案一（改心跳时长）**：提工单，联系后台将心跳检测时长调整为约 2 分钟。
+2. **方案二（服务端主动清理）**：
+   - 业务后台监听 IM 服务端 `disconnect`（断线）回调。
+   - 收到离线信号后，调用 `kick_user_out` 踢出房间成员。
+
+## 5. 结果判定
+
+- 异常退出用户约 5～6 分钟后被移出房间，远端成员列表更新。
+- 提工单调整心跳至约 2 分钟后，清理更快。
+- 方案二通过 `disconnect` 回调 + `kick_user_out` 可立即清理幽灵成员。
+- 心跳过短会增大网络抖动时的误踢风险。
+
+## 6. 常见误区
+
+- 误区 1：认为异常退出用户应立即从成员列表消失（心跳检测约需 5～6 分钟）。
+- 误区 2：认为心跳时长可以随意设得很短（网络抖动会导致误踢，影响正常会议）。
+- 误区 3：忽略业务侧可以主动踢出（`disconnect` 回调 + `kick_user_out`）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUIRoomKit 用户异常退出后远端成员列表仍显示该用户的原因，以及如何更快清理幽灵成员。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 用户异常退出还在成员列表里怎么办？
+- TUIRoomKit 幽灵成员怎么清理？
+- 断网用户多久被移出房间？
+- 心跳检测时间能调短吗？
+- 异常退出用户一直显示在列表？
+- 怎么踢出离线用户？
+
+## 9. 参考来源（可选）
+
+- 状态变更回调：`https://cloud.tencent.com/document/product/269/2570`
+- 踢出房间成员接口：`https://cloud.tencent.com/document/product/269/105393`

package/resource/knowledge/roomkit/best-practice/common/room-limit-and-multi.md

@@ -0,0 +1,88 @@
+---
+title: TUIRoomKit 并发房间上限与多房间支持说明
+product: room
+frameworks: [react, vue, web, android, ios, flutter]
+scope: platform_common
+tags: [TUIRoomKit, 并发房间, 房间上限, 同时进多个房间, 单房间人数, 峰值群组数, TUIRoomTypeConference, useRoomState, 多端登录, 互踢, 会议, 房间管理]
+version_range: ">=2.0.0"
+---
+
+# TUIRoomKit 并发房间上限与多房间支持说明
+
+## 1. 核心结论
+
+- 并发房间数有上限，与开通的 **多人音视频（TUIRoomKit）套餐版本 + IM 能力**相关。
+- **同一客户端 / 同一 SDK 实例不支持同时待在多个会议房间里**：会议类型房间单设备同时加入房间数上限为 1，超过会退出最早加入的房间。
+- **同一 userId 多设备进同一房间默认互踢**（后进踢先进）；多端同时进会需按套餐配置"多端登录"能力或为不同端分配不同 userId。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TUIRoomTypeConference` | 会议类型房间 | 单设备同时加入房间数上限为 1 |
+| `useRoomState` | 房间状态（Atomicx 无 UI 路径） | 单例，同一用户同一时刻仅存在于一个房间内 |
+| 房间数限制 | 房间/群组类资源峰值 | 按自然月最高峰值结算，非无限开房 |
+| 单房间人数 | 一场会议最多多少人 | 套餐硬上限（20/50/200/300） |
+| 多端登录 | 同 userId 多端进会 | 仅更高版本套餐支持 |
+
+## 3. 机制/时序
+
+### 并发房间上限
+
+开通多人音视频（TUIRoomKit）套餐后，可同时开的会议数量受 **房间数限制 + 单房间人数** 约束：
+
+| 能力维度 | 体验版 | 基础互动版 | 进阶互动版 | 超大房间互动版 |
+|---|---|---|---|---|
+| **房间数限制**（计费口径） | 随 IM 版本 | 100,000 个/月 | 100,000 个/月 | 100,000 个/月 |
+| **单房间参会人数规模** | 20 | 50 | 200 | 300（扩容请提工单） |
+
+- 单房间人数是"一场会议最多多少人"的硬上限。
+- 房间数限制（峰值群组数）是套餐赠送的 IM 侧群组/房间类资源峰值（自然月最高峰值结算），不是"任意时刻可无限开房"。
+- 实际可同时开多少场，还受 IM 套餐、TRTC 资源与业务架构影响；超大房间有扩容通道。
+- 多端登录会议 / 同平台多端登录会议需要更高的套餐版本支持。
+
+### 同一用户多房间
+
+同一客户端 / 同一 SDK 实例调用 `joinRoom` 进入新房间时，若已存在会议类型房间，会退出最早加入的房间（单设备同时加入房间数上限为 1）。
+
+## 4. 标准用法
+
+业务需评估并发房间需求时，按以下步骤确认：
+
+1. 确认开通的 TUIRoomKit 套餐版本，查阅 [功能与计费说明](https://cloud.tencent.com/document/product/269/104946) 中的房间数限制与单房间人数。
+2. 评估单场会议人数是否超过套餐上限；超大房间需求可提工单扩容。
+3. 业务需同时承载多场会议时，评估房间数限制（峰值群组数）是否足够，并结合 IM 套餐与 TRTC 资源。
+4. 业务需同一用户多端同会时，确认套餐是否支持多端登录；否则为不同端分配不同 userId。
+
+## 5. 结果判定
+
+- 并发会议数量受套餐房间数限制与单房间人数约束。
+- 同一 SDK 实例同时加入多个会议房间时，超过 1 个会退出最早加入的房间。
+- 同一 userId 多设备进同一房间会互踢（后进踢先进）。
+- 多端同会需套餐支持多端登录，或为不同端分配不同 userId。
+
+## 6. 常见误区
+
+- 误区 1：认为房间数限制（峰值群组数）意味着可以"任意时刻无限开房"（按自然月最高峰值结算，非并发无限）。
+- 误区 2：认为同一 SDK 实例可以同时待多个会议房间（单设备上限 1）。
+- 误区 3：认为同一 userId 多设备可以同时进同一房间（默认互踢）。
+- 误区 4：忽略套餐版本差异（多端登录仅更高版本支持）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUIRoomKit 同时进行的会议室是否有上限，以及同一个用户是否可以同时进入不同房间。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- TUIRoomKit 并发房间数上限是多少？
+- 可以同时开多少场会议？
+- 同一个用户能同时进两个房间吗？
+- 单房间最多多少人？
+- TUIRoomKit 多端登录支持吗？
+- 同一 userId 多设备会互踢吗？
+- 会议室人数上限怎么扩容？
+
+## 9. 参考来源（可选）
+
+- 开通服务 / 功能与计费说明：`https://cloud.tencent.com/document/product/269/104946`
+- 单房间扩容提工单方式：`https://console.cloud.tencent.com/workorder/category`

package/resource/knowledge/roomkit/best-practice/common/room-screen-share-preview.md

@@ -0,0 +1,87 @@
+---
+title: TUIRoomKit 屏幕共享本地预览与避免无限套娃
+product: room
+frameworks: [react, vue, web]
+scope: platform_common
+tags: [TUIRoomKit, 屏幕共享, 本地预览, startScreenSharing, startScreenShare, 整屏共享, 无限套娃, 无限镜像, 窗口共享, 外接显示器, useDeviceState, view参数]
+version_range: ">=2.0.0"
+---
+
+# TUIRoomKit 屏幕共享本地预览与避免无限套娃
+
+## 1. 核心结论
+
+- `view` 参数可以本地显示正在共享的内容：传入有效 `view` 会在本地容器渲染分享画面（本地预览）；不传或传 `null` 则不渲染本地预览。
+- 整屏共享时本地预览会出现"无限套娃/无限镜像"：原因在于本地预览区域也在被采集的整屏/当前页里，预览画面再次进入采集产生递归镜像。
+- **优先方案：改为分享"窗口"而非整屏**，从源头避免会议页被采进画面导致的套娃。
+  - **分享 WPS 注意事项**：通常无法单独拿到"放映窗口"（放映态与编辑窗在采集列表里表现受限）。此时可让用户接**外接显示器**：把放映画面放到外接屏，再分享该显示器/对应窗口，会议主屏继续操作、预览也不易套娃。
+- **兜底方案**：无法改分享窗口、也无法使用外接显示器时，将本地预览窗口尽量做小（缩小 `view` 容器），可明显降低递归镜像的影响面；或本地不传 `view` / 传 `null`，仅用"正在共享"状态提示。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `view` | 本地屏幕分享预览容器 | 传入有效 DOM（元素或 id）则渲染本地预览；传 `null` 不渲染 |
+| `startScreenSharing` | 屏幕共享接口 | TRTC Web / Room 屏幕共享，`view` 指定本地预览 |
+| `startScreenShare` | 底层屏幕共享 | TRTC `startScreenShare`，与 Atomicx 一致 |
+| `useDeviceState().startScreenShare` | Atomicx 无 UI 路径 | 屏幕共享入口，本地预览由预览视图/容器决定 |
+
+## 3. 机制/时序
+
+### 本地预览
+
+调用屏幕共享接口并传入有效 `view` -> 本地容器渲染正在分享的画面（本地预览）-> 不传或传 `null` 则不渲染本地预览。
+
+## 4. 标准用法
+
+### 带本地预览的屏幕共享
+
+```javascript
+// TRTC Web / Room 屏幕共享，view 指定本地预览容器（元素或 id）
+startScreenShare({
+  view: 'local-preview-container',   // 传入有效 view，本地渲染分享画面
+  // 传 null 则不渲染本地预览
+});
+```
+
+### 避免无限套娃
+
+```javascript
+// 方案 1：优先分享窗口而非整屏，从源头避免套娃
+startScreenShare({ view: 'local-preview-container' });  // 选择窗口采集源
+
+// 方案 2（兜底）：无法分享窗口时，缩小本地预览容器或本地不传 view
+startScreenShare({ view: null });  // 不渲染本地预览，仅用"正在共享"状态提示
+```
+
+## 5. 结果判定
+
+- 传入有效 `view`：本地容器渲染分享画面，实现本地预览。
+- 不传 / 传 `null`：不渲染本地预览，仅共享画面给远端。
+- 整屏共享 + 本地预览：可能出现无限套娃，需改为窗口共享或缩小预览。
+- 分享 WPS 放映：需用外接显示器方案避免套娃。
+
+## 6. 常见误区
+
+- 误区 1：认为 `view` 是远端渲染参数（`view` 指定的是本地屏幕分享预览）。
+- 误区 2：整屏共享时本地预览必然套娃就放弃本地预览（可改为窗口共享或缩小预览）。
+- 误区 3：分享 WPS 时以为能单独拿到放映窗口（通常受限，需外接显示器）。
+- 误区 4：混淆 `startScreenSharing` 与 `startScreenShare`（底层一致，均通过 `view` 指定本地预览）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUIRoomKit 屏幕共享时 `view` 参数能否本地预览正在共享的内容，以及整屏共享时本地预览如何避免无限套娃/无限镜像。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 屏幕共享能本地预览吗？
+- TUIRoomKit 屏幕共享 startScreenShare view 参数是什么？
+- 整屏共享怎么避免无限镜像？
+- 屏幕共享出现套娃怎么办？
+- 分享窗口还是整屏更合适？
+- 本地预览窗口怎么缩小？
+- 屏幕共享怎么隐藏本地预览？
+
+## 9. 参考来源（可选）
+
+- TRTC Web `startScreenShare`：`https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/TRTC.html`

package/resource/knowledge/roomkit/best-practice/common/room-status-after-all-leave.md

@@ -0,0 +1,73 @@
+---
+title: TUIRoomKit 所有人离开后房间状态与计费说明
+product: room
+frameworks: [react, vue, web, android, ios, flutter]
+scope: platform_common
+tags: [TUIRoomKit, 所有人离开, 房间销毁, 回收房间, 解散房间, 计费, 会议结束, 房间存在, 房间数量]
+version_range: ">=2.0.0"
+---
+
+# TUIRoomKit 所有人离开后房间状态与计费说明
+
+## 1. 核心结论
+
+- 房间**不会**因为"所有人离开"就立刻自动销毁。
+- 会议结束后，业务侧应**主动调用解散房间接口**结束本场会议。
+- 若未手动解散：后台会在会议结束时间 **6 小时以后**尝试回收房间，回收条件是**房间内成员数为 0**。
+- 计费按实际推拉流/通话消耗；成员都离开且无媒体占用后一般不再产生音视频时长，但房间对象在未解散、未回收前仍占用房间数量。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 解散房间接口 | 主动结束会议 | 业务侧会议结束后主动调用 |
+| 后台回收 | 自动清理房间 | 会议结束 6 小时后尝试回收，条件为成员数 0 |
+| 房间内成员数 | 房间成员统计 | 回收的条件：成员数为 0 |
+| 音视频时长计费 | 通话消耗计费 | 按实际推拉流/通话消耗计费 |
+| 房间数量占用 | 房间对象占用 | 未解散、未回收前仍占用房间数量 |
+
+## 3. 机制/时序
+
+所有人离开房间 -> 房间不会立刻自动销毁 -> 业务侧主动调用解散房间接口（推荐），或等待后台自动回收 -> 后台在会议结束 6 小时后尝试回收（条件为成员数 0）-> 房间回收。
+
+计费维度：
+
+- 音视频时长按实际推拉流/通话消耗计费。
+- 成员都离开且无媒体占用后，一般不再产生该房间的音视频时长。
+- 房间对象在未解散、未回收前仍占用房间数量。
+
+## 4. 标准用法
+
+1. 会议结束后，业务侧主动调用解散房间接口结束会议，避免房间残留。
+2. 若忘记手动解散，后台会在 6 小时后自动回收（成员数为 0 时）。
+3. 评估房间数量占用时，注意未解散、未回收的房间对象仍占用配额。
+
+## 5. 结果判定
+
+- 主动解散后，房间立即结束。
+- 未主动解散时，后台在会议结束 6 小时后、成员数为 0 时回收房间。
+- 成员都离开且无媒体占用后，不再产生音视频时长计费。
+- 未解散、未回收的房间对象仍占用房间数量。
+
+## 6. 常见误区
+
+- 误区 1：认为所有人离开后房间会自动销毁（需主动解散或等待 6 小时后台回收）。
+- 误区 2：认为未解散的房间不产生任何费用（房间对象仍占用房间数量，可能影响并发配额）。
+- 误区 3：忽略业务侧主动解散（推荐主动调用解散接口，而非依赖后台回收）。
+
+## 7. 问题定义（检索辅助，极简）
+
+TUIRoomKit 房间内所有人离开后房间是否还存在、是否会继续计费，以及如何主动解散房间。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 所有人离开后房间会自动销毁吗？
+- TUIRoomKit 房间空了还会计费吗？
+- 会议结束后怎么解散房间？
+- 房间回收要等多久？
+- 房间成员数为 0 会怎样？
+- 房间对象还占房间数量吗？
+
+## 9. 参考来源（可选）
+
+- 开通服务 / 功能与计费说明：`https://cloud.tencent.com/document/product/269/104946`

package/resource/knowledge/roomkit/best-practice/vue/room-uikit-vs-atomicx.md

@@ -0,0 +1,115 @@
+---
+title: tuikit-atomicx-vue3/room 与 roomkit-web-vue3 定位对比
+product: room
+frameworks: [vue, web]
+scope: platform_specific
+tags: [TUIRoomKit, Atomicx, UIKit, tuikit-atomicx-vue3, roomkit-web-vue3, useRoomState, conference, 层级对比, 无UI, 预制UI, 自定义集成, 依赖关系, vue3]
+version_range: ">=2.0.0"
+---
+
+# tuikit-atomicx-vue3/room 与 roomkit-web-vue3 定位对比
+
+## 1. 核心结论
+
+- `tuikit-atomicx-vue3/room`（Atomicx）是**原子能力层**，无 UI / 强自定义集成主路径，把房间、设备、成员等拆成响应式 State。
+- `@tencentcloud/roomkit-web-vue3`（RoomKit / UIKit）是**含 UI 低代码层**，开箱即用的会议套件与页面级组件。
+- 依赖关系：**RoomKit（含 UI）建在 Atomicx/Room 能力之上的产品化封装**，业务上可理解为 RoomKit 复用/对接 Atomicx 能力，而非两套互不相干的房间协议。
+- API 入口：Atomicx 用 `useRoomState()`，UIKit 用 `conference`。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `useRoomState` | Atomicx 房间状态入口 | `createAndJoinRoom` / `joinRoom` / `leaveRoom` / `endRoom` / `currentRoom` |
+| `useDeviceState` | Atomicx 设备状态 | 设备开关、屏幕共享等 |
+| `useRoomParticipantState` | Atomicx 成员状态 | 成员管控、事件订阅 |
+| `useLoginState` | Atomicx 登录状态 | 登录能力，UIKit 会中可复用 |
+| `conference` | UIKit 会议门面 API | 推荐 `createAndJoinRoom` / `joinRoom` / `leaveRoom` / `endRoom` |
+| `ConferenceMainView` | UIKit 预制视图 | 登录进房、会控、布局、麦位等完整会议 UI |
+
+## 3. 机制/时序
+
+### 定位对比
+
+| 对比项 | `tuikit-atomicx-vue3/room`（Atomicx） | `@tencentcloud/roomkit-web-vue3`（RoomKit / UIKit） |
+|---|---|---|
+| **层级** | Atomicx（原子能力层）：State Hooks + 可选原子 UI 组件 | UIKit / 含 UI 低代码层：开箱即用的会议套件与页面级组件 |
+| **包定位** | 无 UI / 强自定义集成主路径；把房间、设备、成员等拆成响应式 State | 含 UI 快速集成主路径；提供完整会议 UI 与 `conference` 门面 API |
+| **核心能力** | `useRoomState` / `useDeviceState` / `useRoomParticipantState` / `useLoginState`：创房、入会、设备、屏幕共享、成员管控、事件订阅；可自拼 UI | `conference` + 预制视图（如 `ConferenceMainView`）：登录进房、会控、布局、麦位等会议完整体验；支持部分组件显隐/自定义 Widget |
+| **适用场景** | 把音视频嵌进自有业务 UI（医联、OA、教育后台等），要 100% 控交互与品牌 | 要最快上线标准会议/研讨会，少写 UI，接受官方会议交互 |
+| **依赖关系** | 底层基于 RoomEngine / TRTC / IM；是原子化接入方案 | 含 UI 方案复用/对接 Atomicx 能力（如登录用 `useLoginState`，会中逻辑走 Room 能力）；业务上可理解为 RoomKit（含 UI）建在 Atomicx/Room 能力之上的产品化封装 |
+| **API 入口** | `useRoomState()`：`createAndJoinRoom` / `joinRoom` / `leaveRoom` / `endRoom`、`currentRoom`、事件订阅等 | `conference`：推荐 `createAndJoinRoom` / `joinRoom` / `leaveRoom` / `endRoom` |
+| **UI 形态** | 预制原子组件可选用 + 自定义模块自拼为主 | 预制完整会议 UI 为主，可通过 Widget/显隐配置做有限定制 |
+
+## 4. 标准用法
+
+### Atomicx 方式（无 UI，自定义集成）
+
+```javascript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { createAndJoinRoom } = useRoomState();
+
+createAndJoinRoom({
+  roomId: 'YOUR_ROOM_ID', // 必填：建议由业务后台生成的唯一标识
+  options: {
+    roomName: '项目进度周会',
+  },
+});
+// 通过 useDeviceState / useRoomParticipantState 等获取响应式状态自拼 UI
+```
+
+### UIKit 方式（含 UI，快速集成）
+
+```javascript
+import { conference, ConferenceMainView, ConferenceMainViewH5, RoomEvent, genTestUserSig } from '@tencentcloud/roomkit-web-vue3';
+const SDKAppID = 0; // 替换为您在开通服务阶段获取的 SDKAppID
+const SDKSecretKey = ''; // 替换为您在开通服务阶段获取的 SDKSecretKey
+const handleEnterRoom = async () => {
+  if (!SDKAppID || !SDKSecretKey) {
+    return;
+  }
+  try {
+    const { userSig } = genTestUserSig({ userId: 'test01', sdkAppId: SDKAppID, secretKey: SDKSecretKey });
+    await conference.login({ sdkAppId: SDKAppID, userId: 'test01', userSig });
+    await conference.setSelfInfo({ userName: 'test', avatarUrl: '' });
+    await conference.createAndJoinRoom({ roomId: '123456', options: { roomName: `test01 的会议` } });
+    inRoom.value = true;
+  } catch (error) {
+    console.error('进入会议失败:', error);
+  }
+};
+// 使用预制 ConferenceMainView 渲染完整会议 UI
+```
+
+## 5. 结果判定
+
+- 无 UI / 强自定义需求：选 Atomicx，用 `useRoomState()` + State Hooks 自拼 UI。
+- 快速上线标准会议：选 UIKit，用 `conference` + `ConferenceMainView`。
+- 依赖关系：UIKit 复用 Atomicx 能力，非两套独立协议。
+- API 入口：Atomicx 为 `useRoomState()`，UIKit 为 `conference`。
+
+## 6. 常见误区
+
+- 误区 1：认为 Atomicx 和 UIKit 是两套互不相干的房间协议（UIKit 建在 Atomicx/Room 能力之上）。
+- 误区 2：用 Atomicx 时误以为自带完整会议 UI（Atomicx 是 State Hooks + 可选原子组件，UI 需自拼）。
+- 误区 3：用 UIKit 时误以为无法自定义（支持部分组件显隐 / 自定义 Widget）。
+- 误区 4：混淆两套的 API 入口（Atomicx 用 `useRoomState()`，UIKit 用 `conference`）。
+
+## 7. 问题定义（检索辅助，极简）
+
+对比 TUIRoomKit Vue3 两种集成方案的定位差异：`tuikit-atomicx-vue3/room`（Atomicx Core SDK，无 UI，State Hooks 自拼）与 `@tencentcloud/roomkit-web-vue3`（RoomKit UIKit，含 UI，conference 低代码）在层级、能力、适用场景、依赖关系与 API 入口（useRoomState vs conference）方面的差异。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Atomicx 和 RoomKit 有什么区别？
+- `tuikit-atomicx-vue3/room` 和 `roomkit-web-vue3` 怎么选？
+- TUIRoomKit 无 UI 和含 UI 方案怎么选？
+- `useRoomState` 和 `conference` 区别？
+- RoomKit 基于 Atomicx 吗？
+- 自定义会议室 UI 用哪个包？
+- 快速集成会议用 Atomicx 还是 UIKit？
+
+## 9. 参考来源（可选）
+
+- 房间管理 Web：`https://cloud.tencent.com/document/product/647/126919`

package/resource/knowledge/roomkit/core-sdk/android/call-user-to-room.md

@@ -21,8 +21,6 @@
 
 ### 步骤1：组件集成
 
-请参考 接入概览 集成 **AtomicXCore SDK**，并已完成 实现登录逻辑 部分接入。
-
 ### 步骤2：呼叫方功能
 
 #### **1. 发起呼叫**

package/resource/knowledge/roomkit/core-sdk/android/room-participant-state.md

@@ -27,8 +27,6 @@
 
 ### 步骤1：组件集成
 
-请参考 接入概览 集成 **AtomicXCore SDK**，并已完成 实现登录逻辑 部分接入。
-
 ### 步骤2：获取参与者列表
 
 在加入房间后，调用 `RoomParticipantStore` 的 `getParticipantList` 接口获取到房间内参与者列表。