@tencentcloud/sdk-mcp 1.3.6 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/sdk-mcp",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",

package/resource/doc/livekit/live/flutter/workflow.md

@@ -0,0 +1,353 @@
+
+# Native Live AtomicXCore 代码生成工作流指令 (Flutter)
+
+## 🚨 核心原则（最高优先级）
+
+**Agent 必须确保生成的代码可以成功编译运行，严禁将无法构建的代码交付给用户！**
+
+### ⚠️ 强制编译验证
+
+**每次生成/修改代码后，必须执行完整构建验证**：
+
+```bash
+flutter build apk --debug
+# 或者在 iOS 环境下
+flutter build ios --debug --no-codesign
+
+```
+
+**禁止行为**：
+
+* ❌ 禁止只用 `flutter analyze` 检查就认为代码正确（无法检测原生依赖问题）
+* ❌ 禁止忽略 `pubspec.yaml` 版本冲突
+
+**编译错误分类与处理**：
+| 错误类型 | 示例 | 处理方式 |
+|---------|------|---------|
+| 依赖解析失败 | `Because xxx depends on yyy...` | 检查 `pubspec.yaml` 版本兼容性，执行 `flutter pub get` |
+| 依赖缺失 | `Target of URI doesn't exist` | 添加缺失库到 `dependencies` |
+| Import 缺失 | `Undefined class 'xxx'` | 添加 import 语句 |
+| 资源缺失 | `Unable to load asset` | 在 `pubspec.yaml` 的 `assets` 节点注册资源 |
+| 权限缺失 | Crash on access Camera/Mic | 检查 `AndroidManifest.xml` 和 `Info.plist` |
+
+**验证流程**：
+
+1. 执行 `flutter build apk --debug`。
+2. 如果失败 → 分析完整错误堆栈 → 修复 → 重新构建。
+3. 循环直到 `BUILD SUCCESSFUL`。
+
+**处理流程**：
+
+1. **构建成功** → 交付代码。
+2. **构建失败** → 分析错误 → **自动修复** → 重新构建。
+* ✅ **可自动修复**：依赖缺失、Import 缺失、权限配置缺失。
+* ❌ **不可修复**：SDK 内部错误、Flutter 环境配置问题（需提示用户）。
+---
+
+## 📋 指令目的与架构
+
+为 Agent 提供实现 Native (Flutter) Live AtomicXCore 核心功能的**代码生成蓝图**。
+
+**核心架构**：
+
+* **容器**：`LiveCoreWidget` (视图层)
+* **状态**：`Store` (数据驱动)
+* **事件**：`Listener` (回调处理)
+
+**功能依赖逻辑（重要）**：
+
+1. **基础先行**：必须先使用本工具（`get_flutter_live_uikit_integration`）完成基础直播（开播/观看/列表）。
+2. **互动叠加**：如果用户需求包含"连麦"、"PK"、"观众列表"，必须**在基础功能完成后**，再调用互动工具（`get_flutter_live_uikit_interaction`）。
+3. **空项目处理**：若用户在空项目中直接请求互动功能，Agent **必须先实现基础功能**，再添加互动能力。
+
+---
+
+## ⚙️ 自动化工作流步骤
+
+### 步骤 0: 前置准备（自动化）
+
+1. **生成凭证**：调用 `get_usersig` 工具生成测试凭证。
+* 主播: `anchor001`, `anchor002`, `anchor003`
+* 观众: `user001`, `user002`, `user003`
+
+2. **环境检查**：检查 `pubspec.yaml`，若缺失以下依赖则自动添加：
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  atomic_x_core: ^3.6.0  # 核心库
+  permission_handler: ^11.0.0 # 权限处理
+  svgaplayer_flutter: ^2.0.0 # 礼物动画(如需)
+
+```
+
+3. **权限注入**：
+* **Android**: 在 `android/app/src/main/AndroidManifest.xml` 添加 Camera/Record Audio 权限。
+* **iOS**: 在 `ios/Runner/Info.plist` 添加 `NSCameraUsageDescription` 和 `NSMicrophoneUsageDescription`。
+### 步骤 1: 获取与生成
+
+**必须优先且唯一**使用本工具返回的**实时文档内容**生成代码。
+
+* **仅主播**：生成 `AnchorPage`
+* **仅观众**：生成 `AudiencePage`
+* **主播+观众**：生成 `MainPage` (入口选择) + `AnchorPage` + `AudiencePage`
+
+### 步骤 2: 验证与交付
+
+执行 `flutter build apk --debug`，确保无误后交付。
+
+---
+
+## 🚫 代码生成约束（严格遵守）
+
+### 1. 通用代码约束
+
+* **严禁修改 Import**：统一使用 `import 'package:atomic_x_core/atomicxcore.dart';`。
+* **严禁臆造 API**：必须严格遵循文档中的 Store 和 Model 定义。
+* **必须查阅 API 文档**：涉及数据模型字段（如 `LiveInfo`），必须查看文档确认字段名（例如确认是 `liveOwner.userName` 而不是 `name`）。
+
+### 2. 🧩 Store 与 Listener 管理约束（生命周期安全）
+
+**核心原因**：Dart 的 Stream 和闭包监听如果不正确释放，会导致严重的内存泄漏或空指针异常。
+
+* **唯一实例原则**：所有 Listener（如 `GiftListener`, `CoGuestListener`, `BarrageListener`）**必须声明为 State 的成员变量**。
+* **严禁匿名内部类**：禁止直接在 `addListener(Listener(...))` 中写匿名对象，必须先实例化。
+* **成对原则**：在 `initState` 调用 `addListener`，则**必须**在 `dispose` 调用 `removeListener`，防止内存泄漏和监听失效。
+
+### 3. ⏱️ 超时时间限制（关键技术点）
+
+**必须严格遵守以下参数限制，优先使用文档示例中的值：**
+
+#### A. 观众连麦 (`CoGuestStore`)
+
+* **规则**：
+* 可选参数，不填则不检查超时。
+* 若填写，范围必须在 **5 - 1800 秒**之间。
+
+* **正确示例**：
+```dart
+// ✅ 推荐：跟随文档示例（如 30秒）
+guestStore.applyForSeat(seatIndex: -1, timeout: 30, extraInfo: null);
+
+```
+#### B. 主播连线/PK (`CoHostStore`)
+
+* **规则**：
+* **最大值 30 秒**（后台硬限制）。
+
+* **正确示例**：
+```dart
+// ✅ 推荐：使用最大值
+coHostStore.requestHostConnection(..., timeout: 30);
+
+```
+### 3. 🎨 扩展功能约束（美颜/音效/UI）
+
+#### A. 音效 (Audio Effect)
+
+* **变声枚举 (`AudioChangerType`)**：
+* ✅ **允许**：`AudioChangerType.child`, `AudioChangerType.man` 等标准枚举。
+* ❌ **禁止**：使用整型索引（如 `1`, `2`）。
+#### B. 美颜 (Beauty)
+
+* **参数范围**：**0.0 - 9.0** (Double)。
+* **UI 映射公式**：`sliderValue * 9.0` (假设 Slider 为 0.0-1.0)。
+
+#### C. 弹幕、礼物与布局 (Barrage, Gift & UI)
+
+* **层级要求**：使用 `Stack` 组件。
+* 底层：`LiveCoreWidget` (全屏)。
+* 顶层：弹幕、礼物、功能按钮 (使用 `Positioned` 定位)。
+
+* **键盘适配**：
+* `Scaffold` 属性 `resizeToAvoidBottomInset: false`，防止键盘顶起视频画面。
+* 输入框位于 `Stack` 顶层，使用 `MediaQuery` 监听键盘高度或使用 `Positioned(bottom: 0)` 配合 `SafeArea`。
+##### 弹幕输入框 (Barrage Input)
+
+* **位置**：固定在屏幕底部左侧，与功能按钮（礼物、连麦等）同行。
+* **样式**：半透明圆角背景 + 占位文字「说点什么...」。
+* **键盘适配**：
+* 键盘弹起时，输入框**保持原位置不变**，禁止随键盘上移。
+* **必须**在 `Scaffold` 设置 `resizeToAvoidBottomInset: false`。
+##### 弹幕显示流 (Barrage Display Flow)
+
+* **数据源**：使用 `ValueListenableBuilder` 监听 `BarrageStore.create(liveId).barrageState.messageList`。
+* **本地回显**：发送成功后**立即**调用 `appendLocalTip` 插入本地弹幕列表，无需等待服务器回调。
+* **滚动行为**：新消息到达时自动滚动到底部。
+
+##### 全屏礼物动画 (Full-screen Gift Animation)
+
+**⚠️ 必须实现**：礼物功能集成时，全屏礼物动画是**强制要求**，不可省略。
+
+* **依赖**：必须引入 `svgaplayer_flutter`。
+* **层级**：全屏礼物动画视图必须覆盖在 `LiveCoreWidget` **之上**。
+* **双端同步**：收到 `GiftStore.onReceiveGift` 回调后，**主播端和观众端**都必须播放全屏动画。严禁只在观众端播放。
+
+### 🎨 默认 UI/UX 设计与交互规范 (仅在用户未指定时生效)
+
+**⚠️ 注意：以下规范仅在用户未提供具体 UI 设计图或需求时作为默认标准执行。**
+
+### 1. 全局视觉风格 (Global Aesthetics)
+
+* **沉浸式暗黑**：`Scaffold` 背景必须为 `Colors.black`，`LiveCoreWidget` 必须**全屏铺满** (`Positioned.fill`) 且位于最底层。
+* **安全区域**：所有悬浮 UI 必须包裹在 `SafeArea` 中。
+* **文字可读性**：视频之上的白色文字（如弹幕、ID）必须添加**黑色阴影** (`Shadow`)。
+* **错误提示**：统一使用 `SnackBar` 或 `FlutterToast`，禁止使用模态 Dialog 打断用户。
+
+### 2. 通用组件规范 (Component Standards)
+
+* **顶部胶囊 (Glass Capsule)**：
+* **样式**：**半透明黑色背景** + **全圆角**。
+* **应用**：仅用于顶部左侧展示"主播头像+ID+热度"。
+
+* **通用按钮 (Flat Buttons)**：
+* **样式**：**"文字 + 圆角矩形背景"**。视觉风格扁平简约，背景色为半透明黑或主题色。
+* **关闭按钮**：特例，使用圆形半透明背景图标。
+### 3. 直播间布局蓝图 (Live Room Layout)
+
+**⚠️ 动态布局原则：仅渲染用户实际集成的功能按钮。若用户未请求某功能（如PK/美颜），严禁添加对应的空按钮**
+
+#### A. 顶部栏 (Top Bar)
+
+* **左侧 [房间信息]**：使用 **半透明胶囊** 包裹 [主播头像 | 主播昵称]。
+* **右侧 [控制区]**：横向排列 [在线观众人数] + [关闭图标(X)]。
+
+#### B. 底部栏 (Bottom Bar) - 根据状态动态切换
+
+* **预览模式 (Preview)**：
+* 内容**向右靠拢**：[美颜] [音效] [开始直播(主按钮)]。
+
+* **直播模式 (Anchor Live)**：
+* **左侧**：[弹幕列表(背景透明)] + [聊天输入框]。
+* **右侧**：功能阵列 [美颜] [音效] [连线] [PK]。
+
+* **观众模式 (Audience Live)**：
+* **左侧**：[弹幕列表] + [聊天输入框]。
+* **右侧**：[礼物] [申请连麦]。
+### 4. 首页布局与交互 (Home Interaction)
+
+#### A. 首页参考布局
+
+```
+┌─────────────────────────────┐
+│       AtomicXCore 直播       │
+│                             │
+│  直播间 ID                   │
+│  ┌─────────────────────────┐│
+│  │ live_000001             ││  ← 输入框 (带左侧 Padding, 半透明背景)
+│  └─────────────────────────┘│
+│                             │
+│  主播开播                    │
+│  (点击即以 anchor001 登录)    │
+│                             │
+│  观众观看                    │
+│  (点击即以 user001 登录)      │
+│                             │
+│       [ 📋 直播列表 ]        │
+└─────────────────────────────┘
+
+```
+
+#### B. 隐式登录流程
+
+**首页不需要单独的登录按钮**，登录在点击功能按钮时自动完成：
+
+* 点击「主播开播」→ 使用 `anchor001` 登录 → 跳转主播页。
+* 点击「观众观看」→ 使用 `user001` 登录 → 跳转观众页。
+* 点击「直播列表」→ 使用 `user001` 登录 → 跳转列表页。
+
+---
+
+## 🎯 功能实现细节
+
+### 1. 主播开播 (`AnchorPage`)
+
+* **核心**：`LiveCoreWidget` + `LiveCoreController`
+* **流程**：`LiveListStore.createLive()`
+* **销毁**：`dispose` 中必须调用 `endLive()`。
+
+### 2. 观众观看 (`AudiencePage`)
+
+* **核心**：`LiveCoreWidget` + `LiveCoreController`
+* **流程**：`LiveListStore.joinLive()`
+* **销毁**：`dispose` 中必须调用 `leaveLive()`。
+
+### 3. 直播列表 (`LiveListPage`)
+
+* **核心**：`LiveListStore.fetchLiveList()` + `GridView`/`ListView`
+* **数据**：订阅 `liveState.liveList` (ValueListenable)。
+* **跳转**：点击列表项跳转观众页，传递 `liveID`。
+
+### 4. 连麦与连线交互规范 (`co_guest` & `co_host`)
+
+#### A. 观众连麦（主播被动接收）
+
+* **主播端 UI**：❌ **严禁**在底部工具栏或任何位置显示「连麦申请」列表按钮。
+* **交互逻辑**：当收到观众连麦申请回调（`onApplicationReceived`）时，直接在屏幕中心弹出对话框（`showDialog`）：
+* **标题**：连麦申请
+* **内容**：收到观众 [昵称] 的连麦申请，是否接受？
+* **操作**：[拒绝] [接受]
+
+* **自定义视图**：Flutter 版必须实现 `LiveCoreWidget.videoWidgetBuilder` 的 `coGuestWidgetBuilder`，根据 `ViewLayer` 返回 Foreground(昵称) 或 Background(头像)。
+
+#### B. 主播连线面板（点击底部【连线】按钮弹出）
+
+* **展现形式**：使用底部浮层面板（`showModalBottomSheet`），禁止使用 Dialog。
+* **UI 布局（严格对照图示）**：
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│  发起连线              [🚪 结束连线]  │  ← 红色文字
+│                                     │
+│  连线中 (2 人)                       │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] 李子明 [💎20]        PK中... ││  ← 已连线用户
+│  │ [👤] 菲林娜 [💎32]        PK中... ││
+│  └─────────────────────────────────┘│
+├─────────────────────────────────────┤
+│  其他连线用户                        │
+│  ┌─────────────────────────────────┐│
+│  │ [👤] 李子明 [💎20]      [取消邀请] ││  ← 灰黑背景按钮
+│  │ [👤] 菲林娜 [💎32]      [邀请连线] ││  ← 蓝色背景按钮
+│  │ [👤] 铁柱   [💗99]      [邀请连线] ││
+│  └─────────────────────────────────┘│
+└─────────────────────────────────────┘
+
+```
+
+#### C. PK 按钮交互约束
+
+* **前置检查**：点击底部【PK】按钮时，必须检查当前连线状态（`CoHostStore.connectedUsers.isEmpty()`）。
+* **状态处理**：
+* **未连线**：❌ 禁止跳转，使用 Toast 提示：`"请先发起连线"`。
+* **已连线**：✅ 弹出 PK 邀请面板。
+
+* **自定义视图**：实现 `VideoWidgetBuilder.battleWidgetBuilder` 展示 PK 对方信息和分数。
+
+---
+
+## 📋 Agent 最终检查清单
+
+* [ ] **编译验证**：已执行 `flutter build apk --debug` 且结果为 SUCCESS。
+* [ ] **API 准确性**：未修改 Import，未臆造 API，已核对 `LiveInfo` 字段名。
+* [ ] **超时合规**：连麦超时 5-1800s，连线超时 ≤30s。
+* [ ] **扩展合规**：音效枚举正确，美颜范围 0-9，弹幕布局覆盖且键盘适配。
+* [ ] **礼物合规**：主播和观众端均实现了全屏礼物动画显示。
+* [ ] **凭证注入**：已自动注入测试 UserSig。
+* [ ] **依赖完整**：已检查并修复 `pubspec.yaml` 和平台权限配置。
+
+---
+
+## 🚨 安全提醒（代码注释模板）
+
+```dart
+/**
+ * ⚠️ 测试凭证说明
+ * - 当前 userSig 由开发工具自动生成，有效期 7 天
+ * - ❌ 生产环境严禁在客户端生成 userSig
+ * - ✅ 正式上线前必须在后端服务生成
+ * - 参考: https://cloud.tencent.com/document/product/647/17275
+ */
+
+```

package/tools/definitions/get_native_live_uikit_integration_def.js

@@ -24,9 +24,9 @@ const TOOL_DESCRIPTION = `
  1. **平台选择约束**：如果用户在提示词中没有明确指定平台（Android/iOS/Flutter/React Native），必须优先调用 'present_framework_choice' 工具，强制要求用户选择平台，禁止使用默认推导的结果。\n
 
  【典型使用场景】：
- 1. 用户需求："请使用 AtomicXCore 在 Android 平台实现一个主播开播功能" → 调用本工具，platform='android', goals=['host_streaming']
- 2. 用户需求："请使用 AtomicXCore 在 iOS 平台实现一个观众观看功能" → 调用本工具，platform='ios', goals=['audience_streaming']
- 3. 用户需求："请使用 AtomicXCore 在 Flutter 平台实现一个直播列表功能" → 调用本工具，platform='flutter', goals=['live_list']
+ 1. 用户需求："请使用 AtomicXCore 在 Android 平台实现主播开播功能" → 调用本工具，platform='android', goals=['host_streaming']
+ 2. 用户需求："请使用 AtomicXCore 在 iOS 平台实现观众观看功能" → 调用本工具，platform='ios', goals=['audience_streaming']
+ 3. 用户需求："请使用 AtomicXCore 在 Flutter 平台实现直播列表功能" → 调用本工具，platform='flutter', goals=['live_list']
  4. 用户需求："请使用 AtomicXCore 在 Android 平台实现主播开播、直播列表、观众观看的功能" → 调用本工具，platform='android', goals=['host_streaming', 'live_list', 'audience_streaming']
  5. 用户需求："请使用 AtomicXCore 实现直播功能"（未指定平台）→ 先调用 'present_framework_choice' 让用户选择平台
 `;

package/utils/report-cls-client.js

@@ -6,7 +6,7 @@ function reportCLSClient(reportData) {
     const time = Date.now();
     const data = {
         platform: 'mcp',
-        verison: '1.3.6',
+        verison: '1.3.7',
         sdkappid: `${SDKAppID}`,
         method: method,
         userid: userID,

package/utils/report-es-client.js

@@ -7,7 +7,7 @@ function reportESClient(reportData) {
         report: [
             {
                 platform: 'mcp',
-                version: '1.3.6',
+                version: '1.3.7',
                 sdkappid: `${SDKAppID}`,
                 method: method,
                 userID: `${userID}`,