@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/{doc/livekit/core-sdk/live/flutter/api-reference → knowledge/livekit/core-sdk/api-reference/flutter}/BaseBeautyStore.md

@@ -1,6 +1,6 @@
 ## 简介
 
-基础美颜功能通过简单易用的 API 实现实时美颜效果调节。**BaseBeautyStore** 提供了一套完整的接口来管理美颜效果的设置和状态订阅。
+基础美颜功能通过简单易用的 API 实现实时美颜效果调节。`BaseBeautyStore` 提供了一套完整的接口来管理美颜效果的设置和状态订阅。
 
 > **说明：**
 >
@@ -9,31 +9,33 @@
 >
 
 ## 功能特性
-- **磨皮效果**：支持 0-9 级别的磨皮效果调节。
+- **磨皮效果**：支持0 - 9级别的磨皮效果调节。
 
-- **美白效果**：支持 0-9 级别的美白效果调节。
+- **美白效果**：支持0 - 9级别的美白效果调节。
 
-- **红润效果**：支持 0-9 级别的红润效果调节。
+- **红润效果**：支持0 - 9级别的红润效果调节。
 
 - **状态订阅**：实时订阅美颜状态变化，同步 UI 显示与实际效果。
 
 ## 可订阅数据
 
 **BaseBeautyState** 的字段描述如下：
-| **属性名** | **类型** | **描述** |
-| --- | --- | --- |
-| smoothLevel | ValueListenable<double> | 磨皮级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
-| whitenessLevel | ValueListenable<double> | 美白级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
-| ruddyLevel | ValueListenable<double> | 红润级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+
+|**属性名**|**类型**|**描述**|
+|---------|---------|---------|
+|smoothLevel|ValueListenable<double>|磨皮级别，取值范围0到9；0表示关闭，9表示效果最明显。|
+|whitenessLevel|ValueListenable<double>|美白级别，取值范围0到9；0表示关闭，9表示效果最明显。|
+|ruddyLevel|ValueListenable<double>|红润级别，取值范围0到9；0表示关闭，9表示效果最明显。|
 
 ## API 列表
-| **函数名** | **描述** |
-| --- | --- |
-| shared | 获取单例实例。 |
-| setSmoothLevel | 设置磨皮级别。 |
-| setWhitenessLevel | 设置美白级别。 |
-| setRuddyLevel | 设置红润级别。 |
-| reset | 重置为默认状态。 |
+
+|**函数名**|**描述**|
+|---------|---------|
+|shared|获取单例实例。|
+|setSmoothLevel|设置磨皮级别。|
+|setWhitenessLevel|设置美白级别。|
+|setRuddyLevel|设置红润级别。|
+|reset|重置为默认状态。|
 
 ### 获取实例
 
@@ -45,51 +47,54 @@
 
 #### setSmoothLevel
 
-设置磨皮级别
+设置磨皮级别。
 ``` dart
 void setSmoothLevel(double smoothLevel);
 ```
 
 **版本信息**
 
-从 3.5 版本开始支持。
+从3.5版本开始支持。
 
 **参数说明**
-| **参数名** | **类型** | **是否必填** | **描述** |
-| --- | --- | --- | --- |
-| smoothLevel | double | 必填 | 磨皮级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|smoothLevel|double|磨皮级别，取值范围0到9；0表示关闭，9表示效果最明显。|
 
 #### setWhitenessLevel
 
-设置美白级别
+设置美白级别。
 ``` dart
 void setWhitenessLevel(double whitenessLevel);
 ```
 
 **版本信息**
 
-从 3.5 版本开始支持。
+从3.5版本开始支持。
 
 **参数说明**
-| **参数名** | **类型** | **是否必填** | **描述** |
-| --- | --- | --- | --- |
-| whitenessLevel | double | 必填 | 美白级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|whitenessLevel|double|美白级别，取值范围0到9；0表示关闭，9表示效果最明显。|
 
 #### setRuddyLevel
 
-设置红润级别
+设置红润级别。
 ``` dart
 void setRuddyLevel(double ruddyLevel);
 ```
 
 **版本信息**
 
-从 3.5 版本开始支持。
+从3.5版本开始支持。
 
 **参数说明**
-| **参数名** | **类型** | **是否必填** | **描述** |
-| --- | --- | --- | --- |
-| ruddyLevel | double | 必填 | 红润级别，取值范围 [0, 9]；0 表示关闭，9 表示效果最明显。 |
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|ruddyLevel|double|红润级别，取值范围0到9；0表示关闭，9表示效果最明显。|
 
 #### reset
 
@@ -100,54 +105,47 @@ void reset();
 
 **版本信息**
 
-从 3.5 版本开始支持。
+从3.5版本开始支持。
 
 ## 数据结构
 
 ### BaseBeautyState
 
 基础美颜状态，管理磨皮、美白、红润等美颜效果的级别数据。支持订阅以同步 UI 显示与实际效果。
-| **属性** | **类型** | **说明** |
-| --- | --- | --- |
-| smoothLevel | ValueListenable<double> | 磨皮级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
-| whitenessLevel | ValueListenable<double> | 美白级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
-| ruddyLevel | ValueListenable<double> | 红润级别，取值范围 [0-9]；0 表示关闭，9 表示效果最明显。 |
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|smoothLevel|ValueListenable<double>|磨皮级别，取值范围0到9；0表示关闭，9表示效果最明显。|
+|whitenessLevel|ValueListenable<double>|美白级别，取值范围0到9；0表示关闭，9表示效果最明显。|
+|ruddyLevel|ValueListenable<double>|红润级别，取值范围0到9；0表示关闭，9表示效果最明显。|
 
 ## 使用示例
 ``` dart
 // 获取单例实例
 final store = BaseBeautyStore.shared;
-
 // 定义监听器
 late final VoidCallback smoothLevelListener = _onSmoothLevelChanged;
 late final VoidCallback whitenessLevelListener = _onWhitenessLevelChanged;
 late final VoidCallback ruddyLevelListener = _onRuddyLevelChanged;
-
 void _onSmoothLevelChanged() {
     print('磨皮级别: ${store.baseBeautyState.smoothLevel.value}');
 }
-
 void _onWhitenessLevelChanged() {
     print('美白级别: ${store.baseBeautyState.whitenessLevel.value}');
 }
-
 void _onRuddyLevelChanged() {
     print('红润级别: ${store.baseBeautyState.ruddyLevel.value}');
 }
-
 // 订阅状态变化
 store.baseBeautyState.smoothLevel.addListener(smoothLevelListener);
 store.baseBeautyState.whitenessLevel.addListener(whitenessLevelListener);
 store.baseBeautyState.ruddyLevel.addListener(ruddyLevelListener);
-
 // 设置美颜效果
 store.setSmoothLevel(5.0);
 store.setWhitenessLevel(3.0);
 store.setRuddyLevel(2.0);
-
 // 重置所有美颜效果
 store.reset();
-
 // 取消订阅
 store.baseBeautyState.smoothLevel.removeListener(smoothLevelListener);
 store.baseBeautyState.whitenessLevel.removeListener(whitenessLevelListener);

package/resource/knowledge/livekit/core-sdk/api-reference/flutter/BattleStore.md

@@ -0,0 +1,312 @@
+## 简介
+
+PK 功能实现主播之间的实时互动对战。`BattleStore` 提供了一套全面的 API 来管理整个 PK 生命周期。
+
+> **重要：**
+>
+
+> 请始终使用工厂方法 **create(liveID:)** 并提供有效的直播间 ID 来创建 `BattleStore` 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> PK 状态更新通过 **battleState** 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
+>
+
+> **警告：**
+>
+
+> 如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
+>
+
+## 功能特性
+- **PK 请求管理**：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
+
+- **状态管理**：实时跟踪 PK 信息、参与用户和分数。
+
+- **事件驱动架构**：提供完整的 PK 事件回调。
+
+- **超时处理**：为 PK 请求提供内置超时机制。
+
+## 可订阅数据
+
+**BattleState** 的字段描述如下：
+
+|**属性名**|**类型**|**描述**|
+|---------|---------|---------|
+|currentBattleInfo|ValueListenable<BattleInfo?>|当前 PK 信息。|
+|battleUsers|ValueListenable<List<SeatUserInfo>>|PK 用户列表。|
+|battleScore|ValueListenable<Map<String,int>>|PK 分数的映射。|
+
+## API 列表
+
+|**函数名**|**描述**|
+|---------|---------|
+|BattleStore.create|创建 BattleStore 实例。|
+|addBattleListener|新增 PK 事件回调。|
+|removeBattleListener|移除 PK 事件回调。|
+|requestBattle|发起 PK 请求。|
+|cancelBattleRequest|取消 PK 请求。|
+|acceptBattle|接受 PK 请求。|
+|rejectBattle|拒绝 PK 请求。|
+|exitBattle|退出 PK。|
+
+### 创建实例
+
+#### BattleStore.create
+
+创建 BattleStore 实例。
+
+### 观察状态和事件
+
+#### addBattleListener
+
+新增 PK 事件回调。
+``` dart
+void addBattleListener(BattleListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|BattleListener|监听器。|
+
+#### removeBattleListener
+
+移除 PK 事件回调。
+``` dart
+void removeBattleListener(BattleListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|BattleListener|监听器。|
+
+### PK 操作
+
+#### requestBattle
+
+发起 PK 请求。
+``` dart
+Future<BattleRequestCompletionHandler> requestBattle({
+    required BattleConfig config,
+    required List<String> userIDList,
+    required int timeout,
+});
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|config|BattleConfig|PK 配置。|
+|userIDList|List<String>|希望邀请 PK 的其他主播用户 ID 列表。请传入您想要 PK 的对方主播用户 ID，请注意不要在此列表中包含当前用户自己的 ID。|
+|timeout|int|超时时间（单位：秒），最大限制为30秒。|
+
+#### cancelBattleRequest
+
+取消 PK 请求。
+``` dart
+Future<CompletionHandler> cancelBattleRequest({
+    required String battleID,
+    required List<String> userIDList,
+});
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|userIDList|List<String>|用户 ID 列表。|
+
+#### acceptBattle
+
+接受 PK 请求。
+``` dart
+Future<CompletionHandler> acceptBattle(String battleID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+
+#### rejectBattle
+
+拒绝 PK 请求。
+``` dart
+Future<CompletionHandler> rejectBattle(String battleID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+
+#### exitBattle
+
+退出 PK。
+``` dart
+Future<CompletionHandler> exitBattle(String battleID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+
+## 数据结构
+
+### BattleEndedReason
+
+正在 PK 中用户收到 PK 结束的原因。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|timeOver|0|PK 倒计时结束。|
+|allMemberExit|1|所有 PK 成员退出。|
+
+### BattleListener
+
+收到 PK 相关的回调事件。
+
+**方法**
+
+|**方法名**|**说明**|
+|---------|---------|
+|onBattleStarted|当PK正式开始时触发此回调，通知所有参与者PK已经开始。|
+|onBattleEnded|当PK结束时触发此回调。|
+|onUserJoinBattle|当有用户加入PK时触发此回调。|
+|onUserExitBattle|当有用户退出PK时触发此回调。|
+|onBattleRequestReceived|当收到PK请求时触发此回调。|
+|onBattleRequestCancelled|当PK请求被取消时触发此回调。|
+|onBattleRequestTimeout|当PK请求超时时触发此回调。|
+|onBattleRequestAccept|当PK请求被接受时触发此回调。|
+|onBattleRequestReject|当PK请求被拒绝时触发此回调。|
+
+### BattleConfig
+
+发送 PK 请求时，设置的 PK 配置信息。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|duration|int|PK 持续时间（单位：秒）。|
+|needResponse|bool|被邀请用户是否需要回复同意/拒绝。|
+|extensionInfo|String|扩展信息。|
+
+### BattleInfo
+
+PK 信息。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|config|BattleConfig|发送 PK 请求时，设置的 PK 配置信息。|
+|startTime|int|PK 开始标记时间戳（单位：秒）。|
+|endTime|int|PK 结束标记时间戳（单位：秒）。|
+
+### BattleState
+
+BattleStore 对外提供的 PK 相关状态数据。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|currentBattleInfo|ValueListenable<BattleInfo?>|当前 PK 信息。|
+|battleUsers|ValueListenable<List<SeatUserInfo>>|PK 用户列表。|
+|battleScore|ValueListenable<Map<String,int>>|PK 分数的映射。|
+
+### BattleRequestCompletionHandler
+
+PK 请求完成处理器。
+
+Dart 中 PK 请求的完成处理器，包含 PK 请求的结果。
+
+**属性**
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|battleInfo|BattleInfo?|成功时返回的 PK 信息。|
+|resultMap|Map<String,int>?|PK 请求的响应结果映射。|
+
+## 使用示例
+``` dart
+// 创建 store 实例
+final store = BattleStore.create('live_room_123');
+// 定义监听器
+late final VoidCallback battleInfoListener = _onBattleInfoChanged;
+late final VoidCallback battleUsersListener = _onBattleUsersChanged;
+void _onBattleInfoChanged() {
+    final battleInfo = store.battleState.currentBattleInfo.value;
+    if (battleInfo != null) {
+        print('当前 PK ID: ${battleInfo.battleID}');
+    }
+}
+void _onBattleUsersChanged() {
+    print('PK 用户数: ${store.battleState.battleUsers.value.length}');
+}
+// 订阅状态变化
+store.battleState.currentBattleInfo.addListener(battleInfoListener);
+store.battleState.battleUsers.addListener(battleUsersListener);
+// 添加 PK 事件监听器
+final battleListener = BattleListener(
+    onBattleStarted: (battleInfo, inviter, invitees) {
+        print('PK 开始，发起者: ${inviter.userName}');
+    },
+    onBattleEnded: (battleInfo, reason) {
+        print('PK 结束，原因: $reason');
+    },
+);
+store.addBattleListener(battleListener);
+// 发起 PK 请求
+final config = BattleConfig(duration: 300, needResponse: true);
+final result = await store.requestBattle(
+    config: config,
+    userIDList: ['user_456'],
+    timeout: 30,
+);
+if (result.code == 0) {
+    print('PK 请求成功: ${result.battleInfo?.battleID}');
+} else {
+    print('PK 请求失败: ${result.message}');
+}
+// 取消订阅
+store.battleState.currentBattleInfo.removeListener(battleInfoListener);
+store.battleState.battleUsers.removeListener(battleUsersListener);
+store.removeBattleListener(battleListener);
+```