@tencentcloud/sdk-mcp 1.3.1 → 1.3.3

package/resource/doc/roomkit/vue/workflow.md

@@ -0,0 +1,487 @@
+# Vue TUIRoomKit (Atomicx 版本) 代码生成工作流指令
+
+## 📋 指令目的
+
+为 Agent 提供实现 Vue TUIRoomKit (Atomicx 版本) **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**，专门针对 PC 端 Vue3 音视频会议应用场景。
+
+---
+
+## 🛑 Agent 执行硬性限制 (Guardrails)
+
+Agent 在生成代码时必须严格遵守以下指令：
+
+### 1. 文档驱动集成
+- 必须严格按照工具返回结果中的 `llm_code_generation_instructions_md` 步骤执行
+- **必须严格按照集成文档中的示例代码生成代码**，不得擅自修改代码结构和实现方式
+- 代码生成时应完全遵循集成文档提供的最佳实践和示例，确保代码的正确性和可运行性
+
+### 2. 源码接入方式
+- TUIRoomKit (Atomicx 版本) 采用 **源码接入方式**，需要从 GitHub 克隆并拷贝核心源码文件
+- 必须按照文档指引，将指定的源码文件夹（assets、components、hooks、i18n、utils、config、views）拷贝到用户项目中
+- 拷贝时必须确保与用户项目已有的文件夹进行合并，避免直接覆盖
+
+### 3. 静默执行集成
+- 所有代码编写完成后，在最后一步自动安装依赖并启动项目
+- 启动成功后提示用户在浏览器中访问本地开发服务器地址
+
+### 4. 零外部配置（测试阶段）
+- 禁止自动创建任何 `.env` 文件用于生产环境配置
+- SDKAppID 和 SDKSecretKey 等关键凭证必须从 MCP 环境变量中读取，并直接配置在 `src/config/basic-info-config.js` 中
+
+### 5. 鉴权凭据配置
+- 从 MCP 环境变量中读取 `SDKAppID` 和 `SDKSecretKey`，禁止要求用户手动输入
+- UserID 生成应保持简洁（可使用随机数生成，如 `user_${Math.ceil(Math.random()*999)}`）
+- **⚠️ 重要安全提示**：必须告知用户，客户端生成 UserSig 仅适合本地测试，正式生产环境必须在服务端生成 UserSig
+
+### 6. Vue 3 组合式 API
+- 优先使用 `<script setup lang="ts">` 语法（注意启用 TypeScript）
+- 使用 Vue 3 Composition API（ref、reactive、computed、onMounted 等）
+- 正确引入和使用 TUIRoomKit Atomicx 组件
+
+### 7. 路由配置
+- 必须配置 Vue Router，将 `home.vue` 映射到主页（路径：`/home`），将 `room.vue` 映射到会议室页面（路径：`/room`）
+- 默认根路径重定向到 `/home`
+
+### 8. 环境依赖准备
+- 确保用户项目支持 TypeScript 和 SCSS，如果未安装需自动安装 `typescript` 和 `sass` 开发依赖
+
+---
+
+## 📦 TUIRoomKit 版本与依赖自动化
+
+Agent 生成代码后，必须自动执行以下依赖链：
+
+### 1. 核心依赖版本推荐
+
+```json
+{
+  "tuikit-atomicx-vue3": "latest",                        // TUIRoomKit 原子化组件库（包含所有 Hooks 和 UI 组件，会自动安装 tuiroom-engine-js）
+  "@tencentcloud/uikit-base-component-vue3": "latest",    // 基础 UI 组件库（按钮、输入框等通用组件）
+  "@tencentcloud/tuiroom-engine-js": "latest",            // TRTC 音视频引擎 SDK（底层能力）
+  "vue-router": "^4.0.0"                                   // Vue 路由（用于页面导航）
+}
+```
+
+**依赖说明**：
+
+| 依赖包 | 作用 | 是否必需手动安装 | 说明 |
+|-------|------|----------------|------|
+| **tuikit-atomicx-vue3** | TUIRoomKit 核心包 | ✅ 必须 | 包含所有原子化 Hooks（useLoginState、useRoomState、useDeviceState 等）和原子化 UI 组件（RoomLayoutView、ParticipantViewUI 等）。会自动安装 `@tencentcloud/tuiroom-engine-js` 作为依赖 |
+| **@tencentcloud/uikit-base-component-vue3** | 基础 UI 组件库 | ✅ 必须 | 提供通用的按钮、输入框、弹窗等基础组件，被 TUIRoomKit 原子化组件内部使用 |
+| **@tencentcloud/tuiroom-engine-js** | TRTC 音视频引擎 SDK | ⚠️ 可选 | 提供底层音视频能力（设备管理、音视频采集、推拉流等）。由于 `tuikit-atomicx-vue3` 会自动安装此依赖，通常不需要手动安装。但如果需要确保版本一致性，可以手动指定版本 |
+| **vue-router** | Vue 官方路由库 | ✅ 必须 | 用于实现会议入口页（`/home`）和会议室页面（`/room`）的路由导航 |
+
+**依赖关系**：
+```
+用户项目
+  ├── tuikit-atomicx-vue3（手动安装）
+  │   └── @tencentcloud/tuiroom-engine-js（自动安装）
+  ├── @tencentcloud/uikit-base-component-vue3（手动安装）
+  └── vue-router（手动安装）
+```
+
+**最佳实践**：
+- ✅ **推荐做法**：仅手动安装 `tuikit-atomicx-vue3`、`@tencentcloud/uikit-base-component-vue3`、`vue-router`，让 `@tencentcloud/tuiroom-engine-js` 自动安装
+- ⚠️ **可选做法**：如果需要精确控制 `@tencentcloud/tuiroom-engine-js` 版本，可以手动安装并指定版本号
+- ❌ **不推荐**：同时在 `dependencies` 和手动安装中指定不同版本的 `@tencentcloud/tuiroom-engine-js`，可能导致版本冲突
+
+### 2. 开发环境依赖（TypeScript 和 SCSS）
+
+如果用户项目尚未支持 TypeScript 和 SCSS，Agent 必须自动安装：
+
+```json
+{
+  "typescript": "latest",  // TypeScript 编译器（用于类型检查和编译）
+  "sass": "latest"         // SCSS 预处理器（用于编译 .scss 样式文件）
+}
+```
+
+**依赖说明**：
+- **typescript**: TUIRoomKit 源码使用 TypeScript 编写，需要 TypeScript 编译器支持
+- **sass**: TUIRoomKit 样式文件使用 SCSS 编写，需要 sass 预处理器进行编译
+
+### 3. 构建环境补丁 (Vite/esbuild)
+
+若检测到 Vite 项目，Agent 必须在 `package.json` 自动增加补丁配置以兼容 esbuild-wasm：
+
+```json
+{
+  "overrides": { 
+    "esbuild": "npm:esbuild-wasm@latest"   // npm 使用此字段覆盖依赖版本
+  },
+  "resolutions": { 
+    "esbuild": "npm:esbuild-wasm@latest"   // yarn/pnpm 使用此字段覆盖依赖版本
+  }
+}
+```
+
+**补丁说明**：
+- **为什么需要**：部分环境下 esbuild 原生二进制可能无法正常运行，使用 esbuild-wasm（WebAssembly 版本）可以提供更好的跨平台兼容性
+- **适用场景**：主要针对 Vite 构建工具的项目
+- **作用**：强制将项目中所有依赖的 esbuild 版本替换为 esbuild-wasm 版本
+
+**安装命令示例**：
+
+```bash
+# npm
+npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+npm install typescript sass -D
+
+# pnpm  
+pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+pnpm install typescript sass -D
+
+# yarn
+yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+yarn add typescript sass -D
+```
+
+---
+
+## 🏗️ 源码文件拷贝结构
+
+Agent 必须按照以下结构，从示例项目拷贝核心源码到用户项目：
+
+| 源路径 (示例项目) | 目标路径 (用户项目) | 说明 |
+|------------------|-------------------|------|
+| `src/assets/` | `src/assets/` | 包含背景图、图标等静态资源 |
+| `src/components/` | `src/components/` | 包含 TUIRoomKit 所有原子 UI 组件 |
+| `src/hooks/` | `src/hooks/` | 包含 TUIRoomKit 业务逻辑处理 |
+| `src/i18n/` | `src/i18n/` | 包含多语言配置文件 |
+| `src/utils/` | `src/utils/` | 包含通用工具函数 |
+| `src/config/` | `src/config/` | 包含 `basic-info-config.js` 等应用配置信息（首次接入请重点关注此文件） |
+| `src/views/home.vue` | `src/views/home.vue` | 该页面包含了设备检测、房间创建/加入的入口功能 |
+| `src/views/room.vue` | `src/views/room.vue` | 该页面是 TUIRoomKit 的核心会议界面，集成了完整的头部、视频布局、控制栏和侧边面板 |
+
+> **重要提示**：拷贝源码文件时，请确保与用户项目已有的文件夹进行**合并**，避免直接覆盖已有的同名文件夹。
+
+---
+
+## 🎯 TUIRoomKit (Atomicx 版本) 核心组件说明
+
+Agent 在生成代码时，必须了解 TUIRoomKit Atomicx 的核心架构：
+
+### 原子化组件设计理念
+
+TUIRoomKit (Atomicx 版本) 采用原子化组件设计，开发者可以灵活组合这些组件构建个性化的会议界面。
+
+### 核心页面组件
+
+| 组件名称 | 说明 | 使用场景 |
+|---------|------|---------|
+| `home.vue` | 会议入口页面 | 包含设备检测、房间创建/加入功能 |
+| `room.vue` | 会议室核心页面 | 集成完整的头部、视频布局、控制栏和侧边面板 |
+
+### 核心 Hooks
+
+| Hook 名称 | 说明 | 主要用途 |
+|---------|------|---------|
+| `useLoginState` | 登录状态管理 | 提供 login、setSelfInfo 等方法 |
+| `useRoomModal` | 房间弹窗管理 | 提供 handleErrorWithModal 错误处理方法 |
+| `useRoomEngine` | 房间引擎管理 | 获取 roomEngine 实例 |
+
+### 核心 UI 组件（来自 tuikit-atomicx-vue3）
+
+- **RoomLayoutView**: 视频流布局组件（支持九宫格、侧边栏、顶部栏三种布局）
+- **ParticipantViewUI**: 视频流挂件组件（可自定义）
+- **UIKitProvider**: 全局 UI 配置组件（主题、语言）
+
+---
+
+## 🛠️ 集成步骤详解
+
+Agent 必须按照以下步骤执行集成：
+
+### 步骤 1：克隆 GitHub 仓库并拷贝源码
+
+```bash
+# 克隆 TUIRoomKit 仓库
+git clone https://github.com/Tencent-RTC/TUIRoomKit.git --depth=1
+
+# 进入 PC 端 Vue3 Atomicx 示例目录
+cd TUIRoomKit/Web/example/atomicx-vite-vue3-ts
+
+# 拷贝核心源码文件到用户项目
+# (注意：需要与用户项目已有文件夹合并，而非直接覆盖)
+```
+
+**Agent 执行注意事项**：
+- 如果用户项目中已存在同名文件夹，必须进行智能合并
+- 不得覆盖用户已有的业务代码
+
+---
+
+### 步骤 2：安装项目依赖
+
+```bash
+# 安装核心依赖
+npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+
+# 安装开发环境依赖（如果用户项目尚未支持 TypeScript 和 SCSS）
+npm install typescript sass -S -D
+```
+
+---
+
+### 步骤 3：配置页面路由
+
+在用户项目中配置或更新 `src/router/index.ts` 文件。
+
+**关键配置要点**：
+- 配置 `/home` 路由：映射到 `home.vue` 页面（会议入口）
+- 配置 `/room` 路由：映射到 `room.vue` 页面（会议室）
+- 默认根路径 `/` 重定向到 `/home`
+
+**Agent 执行要求**：
+- ⚠️ 必须严格按照集成文档中的路由配置示例生成
+- 如果用户项目中已有 `src/router/index.ts` 文件，需要将路由配置**合并**到已有代码中
+- 如果尚未配置路由，需要新建 `src/router/index.ts` 文件
+
+---
+
+### 步骤 4：配置 App.vue 文件
+
+将集成文档中提供的配置内容合并到用户项目中的 `App.vue` 文件。
+
+**关键配置要点**：
+- 配置全局 `UIKitProvider` 组件（设置主题和语言）
+- 引入页面路由 `<router-view />`
+- 在 `onMounted` 钩子中执行用户登录逻辑（`login` 和 `setSelfInfo`）
+- 配置全局样式，确保会议界面全屏显示
+
+**Agent 执行要求**：
+- ⚠️ 必须严格按照集成文档中的 `App.vue` 示例代码生成，不得擅自修改
+- 如果用户项目已有 `App.vue` 文件，需要智能合并而非直接覆盖
+
+---
+
+### 步骤 5：配置 src/main.ts 文件
+
+将集成文档中提供的路由和多语言配置合并到用户项目中的入口文件 `src/main.ts` 中。
+
+**关键配置要点**：
+- 引入并注册 Vue Router
+- 配置多语言资源（中文和英文）
+- 挂载 Vue 应用
+
+**Agent 执行要求**：
+- ⚠️ 必须严格按照集成文档中的 `main.ts` 示例代码生成，不得擅自修改
+- 如果用户项目中的入口文件为 `main.js`，需要修改文件后缀为 `main.ts`
+- 如果用户项目已有路由配置，需要智能合并而非直接覆盖
+
+---
+
+### 步骤 6：配置应用信息（src/config/basic-info-config.js）
+
+在用户项目目录中找到 `src/config/basic-info-config.js` 配置文件，并进行以下配置：
+
+**配置方式**：
+- Agent 必须从 MCP 环境变量中读取 `SDKAppID` 和 `SDKSecretKey`
+- 这些凭证配置在 MCP 环境中，无需通过 `get_usersig` 工具获取
+- 直接将环境变量中的值写入 `basic-info-config.js` 文件
+
+**⚠️ 安全警告**：
+- 本文的 Demo 示例中通过在客户端代码中配置 `SDKSecretKey` 进行鉴权，但 `SDKSecretKey` 很容易被反编译逆向破解，一旦密钥泄露，攻击者就可以盗用您的腾讯云流量
+- **该方法仅适合本地跑通 Demo 和功能调试**
+- **在正式的生产环境中**，建议在您的服务端生成 UserSig，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权
+
+**Agent 必须告知用户**：
+> "⚠️ 当前生成的代码仅适用于本地测试。在正式生产环境中，您必须在服务端生成 UserSig，详见腾讯云文档：https://cloud.tencent.com/document/product/647/17275#formal"
+
+---
+
+## 🎨 UI 自定义功能
+
+TUIRoomKit (Atomicx 版本) 支持灵活的 UI 自定义，Agent 可根据用户需求提供以下自定义方案：
+
+### 1. 主题及语言配置
+
+通过配置 `App.vue` 中 `UIKitProvider` 的入参，修改主题及语言的默认值：
+
+| UIKitProvider 参数 | 可选值 | 默认值 |
+|-------------------|--------|--------|
+| theme | "light" \| "dark" | "light" |
+| language | "zh-CN" \| "en-US" | "en-US" |
+
+```typescript
+<UIKitProvider theme="dark" language="en-US">
+  <router-view />
+</UIKitProvider>
+```
+
+---
+
+### 2. 房间流布局自定义
+
+TUIRoomKit 目前支持三种流布局：
+- **九宫格布局**（默认）：`RoomLayoutTemplate.GridLayout`
+- **侧边栏布局**：`RoomLayoutTemplate.SidebarLayout`
+- **顶部栏布局**：`RoomLayoutTemplate.CinemaLayout`
+
+在 `src/views/room.vue` 中修改默认布局：
+
+```typescript
+// 修改默认视频流布局为侧边栏布局
+const participantViewLayout = ref(RoomLayoutTemplate.SidebarLayout);
+
+function handleLayoutUpdate(layout: RoomLayoutTemplate) {
+  participantViewLayout.value = layout;
+}
+```
+
+---
+
+### 3. 自定义视频流挂件
+
+如需自定义视频流挂件（如用户名显示、音视频状态图标等），可修改以下组件：
+
+```
+src/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue
+```
+
+---
+
+### 4. 配置用户联系人列表
+
+TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表。批量导入用户关系链请参考以下步骤：
+
+**步骤 1**：使用 [账号管理 > 导入多个账号](https://cloud.tencent.com/document/product/269/4919) REST API 接口批量导入用户账号
+
+**步骤 2**：使用 [好友管理 > 导入好友](https://cloud.tencent.com/document/product/269/8301) REST API 接口批量导入用户关系链
+
+---
+
+## 🔄 完整自动化流程总结
+
+```mermaid
+graph TD
+    A[接收用户需求] --> B[克隆 TUIRoomKit GitHub 仓库]
+    B --> C[拷贝核心源码文件到用户项目]
+    C --> D[安装核心依赖: tuikit-atomicx-vue3 等]
+    D --> E{检测 TypeScript 和 SCSS 支持}
+    E -->|未安装| F[安装 typescript 和 sass]
+    E -->|已安装| G[跳过]
+    F --> H[配置 Vue Router 路由]
+    G --> H
+    H --> I[配置 App.vue: UIKitProvider + 用户登录]
+    I --> J[配置 main.ts: 路由 + 多语言]
+    J --> K[从 MCP 环境变量读取 SDKAppID 和 SDKSecretKey]
+    K --> L[配置 basic-info-config.js: SDKAppID + SDKSecretKey]
+    L --> M{用户需要自定义 UI?}
+    M -->|是| N[提供 UI 自定义方案: 主题/布局/挂件]
+    M -->|否| O[使用默认配置]
+    N --> P[record_result 记录集成结果]
+    O --> P
+    P --> Q[自动启动开发服务器: npm run dev]
+    Q --> R[提示用户在浏览器中访问本地开发服务器地址]
+```
+
+---
+
+## ✍️ Agent 代码生成示例指令 (Prompts)
+
+当 Agent 开始编写代码时，应遵循以下语义逻辑：
+
+**基础集成**:
+> "按照 TUIRoomKit (Atomicx 版本) 源码接入方式，为我生成一个 Vue 3 音视频会议应用。请从 GitHub 克隆仓库并拷贝核心源码文件，自动配置路由和多语言，并从 MCP 环境变量中读取 SDKAppID 和 SDKSecretKey 配置到 `basic-info-config.js`。启动后提示我在浏览器中访问调试地址。**请务必告知我：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig。**"
+
+**自定义主题和布局**:
+> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个 Vue 3 会议应用。要求使用暗色主题（dark）和英文语言（en-US），默认流布局为侧边栏布局（SidebarLayout）。"
+
+**自定义视频流挂件**:
+> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个 Vue 3 会议应用。需要自定义视频流挂件，在视频流上显示自定义的用户信息和状态图标。"
+
+---
+
+## 📝 关键要点总结
+
+| 类别 | 要求 |
+|------|------|
+| **框架版本** | 专门针对 PC 端 Vue 3 项目（不支持 Vue 2.x 和 H5） |
+| **接入方式** | 源码接入（从 GitHub 克隆并拷贝核心源码文件） |
+| **文档优先** | 严格遵循工具返回的最新文档指令 |
+| **静默集成** | 代码编写完成后自动安装依赖并启动开发服务器 |
+| **凭证注入** | 从 MCP 环境变量读取凭证，配置在 `basic-info-config.js` 中 |
+| **安全提示** | ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成 |
+| **依赖管理** | 自动安装核心依赖和开发环境依赖（TypeScript、SCSS） |
+| **路由配置** | 配置 `/home` 和 `/room` 两个核心路由 |
+| **多语言** | 支持中文（zh-CN）和英文（en-US） |
+| **UI 自定义** | 支持主题、布局、视频流挂件等自定义 |
+
+---
+
+## 🎯 Agent 执行检查清单
+
+在完成代码生成后，Agent 必须确认以下所有项目：
+
+### 项目初始化
+- [ ] 已克隆 TUIRoomKit GitHub 仓库（`git clone https://github.com/Tencent-RTC/TUIRoomKit.git --depth=1`）
+- [ ] 已拷贝核心源码文件到用户项目（assets、components、hooks、i18n、utils、config、views）
+- [ ] 已安装核心依赖：`tuikit-atomicx-vue3`、`@tencentcloud/uikit-base-component-vue3`、`@tencentcloud/tuiroom-engine-js`、`vue-router`
+- [ ] 已检测并安装 TypeScript 和 SCSS 开发依赖（如果用户项目未安装）
+
+### 代码生成
+- [ ] 已配置 Vue Router：`/home` 和 `/room` 路由
+- [ ] 已配置 `App.vue`：UIKitProvider + 用户登录逻辑
+- [ ] 已配置 `main.ts`：路由 + 多语言资源
+- [ ] 组件使用了 `<script setup lang="ts">` 语法
+
+### 凭证与登录
+- [ ] 🔴 已从 MCP 环境变量中读取 SDKAppID 和 SDKSecretKey
+- [ ] 已将 SDKAppID、SDKSecretKey 配置在 `src/config/basic-info-config.js` 中
+- [ ] 已在 `App.vue` 中实现 login() 和 setSelfInfo() 登录逻辑
+- [ ] ⚠️ **已告知用户**：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig
+
+### UI 配置
+- [ ] 已根据用户需求配置主题（light/dark）和语言（zh-CN/en-US）
+- [ ] 已根据用户需求配置流布局（九宫格/侧边栏/顶部栏）
+- [ ] 如果用户需要自定义视频流挂件，已提供自定义方案
+
+### 最终检查
+- [ ] 已调用 `record_result` 记录集成结果
+- [ ] 已自动安装依赖（npm install）
+- [ ] 已自动启动开发服务器（npm run dev）
+- [ ] 已提示用户在浏览器中访问本地开发服务器地址
+- [ ] 项目可以正常运行，无报错
+
+---
+
+## 🔗 相关工具参考
+
+### 必须使用的工具
+
+#### MCP 环境变量 - 读取鉴权凭证
+**用途**：从 MCP 环境变量中读取腾讯云应用凭证：
+- `SDKAppID`: 应用标识
+- `SDKSecretKey`: 应用密钥
+
+**使用方式**：
+- Agent 直接从 MCP 环境变量中读取凭证
+- 将凭证写入 `src/config/basic-info-config.js` 文件
+- 禁止让用户手动填写或从外部工具获取
+
+**使用约束**：
+- ✅ 必须从 MCP 环境变量读取
+- ❌ 禁止让用户手动输入
+- ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成
+
+#### `record_result` - 记录集成结果
+**用途**：记录集成过程和结果，用于统计和分析
+
+**调用时机**：在完成所有集成步骤并成功启动项目后调用
+
+---
+
+## 📚 相关资源链接
+
+- **TUIRoomKit GitHub 仓库**：https://github.com/Tencent-RTC/TUIRoomKit
+- **腾讯云 TRTC 控制台**：https://console.cloud.tencent.com/trtc
+- **正式运行阶段如何计算 UserSig**：https://cloud.tencent.com/document/product/647/17275#formal
+- **URL 域名及协议限制说明**：https://cloud.tencent.com/document/product/647/17249
+- **应对防火墙受限（内网代理）**：https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-34-advanced-proxy.html
+
+---
+
+**适用框架**: Vue 3 (PC 端)  
+**TUIRoomKit 版本**: tuikit-atomicx-vue3 (Atomicx 版本)  
+**构建工具**: Vite (推荐)

package/resource/doc/tuicallkit/react/api.md

@@ -1,3 +1,19 @@
+## 重要提醒
+**文档内容说明：**  
+ - 文档涉及到 `TUICallEngine` API 和 `TUICallKit` 含 UI 组件 API 两部分
+ - `TUICallEngine` API 文档请参考 **Part One**
+ - `TUICallKit`含 UI 组件 API 文档请参考 **Part Two**
+
+## Part One
+**TUICallEngine API 文档**
+- TUICallEngine API 涉及到 web 和 小程序。
+- 当用户查询 `TUICallEngine` API 时，必须先查阅 TUICallEngine 的官方 API 文档，然后再给出 API 的正确用法示例, 禁止自己推测 API 的用法。
+- 以下是各平台 API 的文档链接，请直接访问文档链接获取 API 用法：
+- [TUICallEngine Web API 列表文档](https://cloud.tencent.com/document/product/647/78757)
+- [TUICallEngine Web API 使用示例文档](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html)
+- [TUICallEngine 小程序 API 文档](https://cloud.tencent.com/document/product/647/78761)
+
+## Part Two
 TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见：[快速接入 TUICallKit](https://write.woa.com/document/130513425899630592)。
 
 > **说明：**

package/resource/doc/tuicallkit/vue/api.md

@@ -1,3 +1,19 @@
+## 重要提醒
+**文档内容说明：**  
+ - 文档涉及到 `TUICallEngine` API 和 `TUICallKit` 含 UI 组件 API 两部分。
+ - `TUICallEngine` API 文档请参考 **Part One**
+ - `TUICallKit`含 UI 组件 API 文档请参考 **Part Two**
+
+## Part One
+**TUICallEngine API 文档**
+- TUICallEngine API 涉及到 web 和 小程序。
+- 当用户查询 `TUICallEngine` API 时，必须先查阅 TUICallEngine 的官方 API 文档，然后再给出 API 的正确用法示例, 禁止自己推测 API 的用法。
+- 以下是各平台 API 的文档链接，请直接访问文档链接获取 API 用法：
+- [TUICallEngine Web API 列表文档](https://cloud.tencent.com/document/product/647/78757)
+- [TUICallEngine Web API 使用示例文档](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/zh-cn/TUICallEngine.html)
+- [TUICallEngine 小程序 API 文档](https://cloud.tencent.com/document/product/647/78761)
+
+## Part Two
 TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见：[快速接入 TUICallKit](https://write.woa.com/document/130513425899630592)。
 
 > **说明：**

package/tools/common/record-prompt.js

@@ -4,11 +4,11 @@ import { reportCLSClient } from '../../utils/report-cls-client.js';
 const registryRecordPromptTool = (mcpServer) => {
     const { name, description, parameter_descriptions } = RECORD_PROMPT_DEFINITION;
     mcpServer.tool(name, description, {
-        content: z.string().describe(parameter_descriptions.content),
+        prompt: z.string().describe(parameter_descriptions.prompt),
     }, (params) => {
         reportCLSClient({
             method: 'record_prompt',
-            info: params.content,
+            info: params.prompt,
         });
         return {
             content: [

package/tools/common/record-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"record-prompt.js","sourceRoot":"","sources":["../../../src/tools/common/record-prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,MAAM,wBAAwB,GAAG,CAAC,SAAoB,EAAE,EAAE;IACxD,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE,GAAG,wBAAwB,CAAC;IAC/E,SAAS,CAAC,IAAI,CACZ,IAAI,EACJ,WAAW,EACX;QACE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,OAAO,CAAC;KAC7D,EAAE,CAAC,MAAM,EAAE,EAAE;QACZ,eAAe,CAAC;YACd,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,MAAM,CAAC,OAAO;SACrB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,6DAA6D;iBACpE;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"record-prompt.js","sourceRoot":"","sources":["../../../src/tools/common/record-prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,MAAM,wBAAwB,GAAG,CAAC,SAAoB,EAAE,EAAE;IACxD,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE,GAAG,wBAAwB,CAAC;IAC/E,SAAS,CAAC,IAAI,CACZ,IAAI,EACJ,WAAW,EACX;QACE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC;KAC3D,EAAE,CAAC,MAAM,EAAE,EAAE;QACZ,eAAe,CAAC;YACd,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,MAAM,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,6DAA6D;iBACpE;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAEF,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/tools/definitions/get_native_live_extra_features_def.js

@@ -0,0 +1,109 @@
+const TOOL_DESCRIPTION = `
+【核心用途】：
+这是一个专业的 Native 直播扩展功能集成助手，专门用于指导 LLM 帮用户在 Android/iOS/Flutter/React Native 平台实现直播场景下的扩展功能，包括：基础美颜、音效控制、弹幕互动、礼物赠送。
+
+【关键词】：'AtomicXCore', 'LiveKit', '美颜', '音效', '弹幕', '礼物', 'BaseBeautyStore', 'AudioEffectStore', 'DeviceStore', 'BarrageStore', 'GiftStore', 'Android', 'iOS', 'Flutter', 'React Native'。
+
+【行动指令与工作流引导】：
+
+Agent 在处理用户需求时，应使用本工具返回的 llm_code_generation_instructions_md 字段。这个字段包含了：
+1. 核心工作流指令（来自 workflow.md，包含调用 get_usersig 工具自动生成测试凭证并注入代码的闭环流程）。
+2. 用户所需功能（Goals）对应的最新、实时获取的官方文档内容。
+
+LLM 必须优先且唯一使用本工具返回的实时文档内容生成代码，避免自行访问外部 URL。
+
+【⚠️ 重要前置依赖】：
+
+**扩展功能依赖于基础直播功能**：
+- 美颜、音效、弹幕、礼物等扩展功能必须在**已实现主播开播和观众观看的项目基础上**才能正常工作
+- 如果用户在空项目中直接请求扩展功能，Agent 必须：
+  1. **先调用 'get_native_live_uikit_integration' 工具**实现基础直播功能（主播开播 + 观众观看）
+  2. **再调用本工具**实现扩展功能（美颜 / 音效 / 弹幕 / 礼物）
+  3. **确保代码包含完整的身份入口选择逻辑**，让用户可以切换主播/观众身份进行测试
+
+【功能范围】：
+
+1. **基础美颜** (base_beauty)：磨皮/美白/红润（0-9 级）、重置美颜
+   - 核心 API：BaseBeautyStore.setSmoothLevel()、setWhitenessLevel()、setRuddyLevel()
+
+2. **音效控制** (audio_effect)：人声音量（0-150）、耳返音量（0-100）、变声、混响
+   - 核心 API：AudioEffectStore.setVoiceEarMonitorEnable()、setAudioChangerType()、setAudioReverbType()、DeviceStore.setCaptureVolume()
+   - **📖 官方 API 文档地址（如有疑问，必须查阅确认）**：
+     * AudioEffectStore: https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-audio-effect-store/index.html
+     * AudioEffectState: https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-audio-effect-state/index.html
+     * AudioChangerType: https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-audio-changer-type/index.html
+     * AudioReverbType: https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-audio-reverb-type/index.html
+
+3. **弹幕互动** (barrage)：接收/发送弹幕、自定义弹幕、禁言管理
+   - 核心 API：BarrageStore.sendTextMessage()、sendCustomMessage()、appendLocalTip()
+
+4. **礼物赠送** (gift)：礼物列表、发送礼物、全屏礼物动画（必选）、弹幕礼物消息（视弹幕模块是否存在而定）
+   - 核心 API：GiftStore.refreshUsableGifts()、sendGift()、addGiftListener()
+
+【支持平台】：Android, iOS, Flutter, React Native（根据 platform 参数动态返回对应平台文档）。
+
+【典型使用场景】：
+
+1. 用户需求："添加直播美颜和音效功能"（未指定平台）→ 先调用 'present_framework_choice' 让用户选择平台
+2. 用户需求："请使用 AtomicXCore 在 Android 平台实现美颜功能" → 调用本工具，platform='android', goals=['base_beauty']
+3. 用户需求："请使用 AtomicXCore 在 iOS 平台实现音效控制功能" → 调用本工具，platform='ios', goals=['audio_effect']
+4. 用户需求："请使用 AtomicXCore 在 Flutter 平台实现弹幕功能" → 调用本工具，platform='flutter', goals=['barrage']
+5. 用户需求："请使用 AtomicXCore 在 Android 平台实现礼物功能"（无弹幕）→ 调用本工具，platform='android', goals=['gift']
+   - **结果**：实现礼物发送/接收 + 全屏礼物动画。（不实现弹幕礼物消息）
+6. 用户需求："集成弹幕和礼物功能" → 调用本工具，goals=['barrage', 'gift']
+   - **结果**：实现礼物发送/接收 + 全屏礼物动画 + 弹幕区域显示礼物文本消息。
+
+【强制约束】：
+
+1. **平台选择约束**：如果用户未明确指定平台，必须优先调用 'present_framework_choice' 工具让用户选择。
+
+2. **必须查看 API 文档确认字段名**：使用数据模型字段时必须访问文档中的 API 链接确认，禁止猜测。
+
+3. **参数范围约束**：
+   - 美颜强度：0-9（Float），UI 控件通常为 0-100，需映射到 0-9 范围
+   - 音量参数：采集音量 0-150（Int）、耳返音量 0-100（Int）
+
+4. **单例重置约束**：AudioEffectStore、DeviceStore、BaseBeautyStore 是单例，直播间结束时需调用 reset()。
+
+5. **音效 API 约束（严禁猜测）**：
+   - AudioChangerType：NONE、CHILD、LITTLE_GIRL、MAN、COLD、ETHEREAL、FATSO、FOREIGNER、HEAVY_MACHINERY、HEAVY_METAL、STRONG_CURRENT、TRAPPED_BEAST
+   - AudioReverbType：NONE、KTV、SMALL_ROOM、AUDITORIUM、DEEP、LOUD、METALLIC、MAGNETIC
+
+6. **🎯 礼物与弹幕联动逻辑（严格执行）**：
+   - **场景 A：goals=['gift'] (无弹幕)**
+     - 必须实现：礼物面板、发送逻辑、**全屏礼物动画**。
+     - **禁止实现**：弹幕区域的礼物文本消息（因为没有弹幕模块）。
+   - **场景 B：goals=['barrage', 'gift'] (有弹幕)**
+     - 必须实现：礼物面板、发送逻辑、**全屏礼物动画**。
+     - **必须实现**：在弹幕列表中插入“XXX 送出了 YYY”的**礼物文本消息**。
+   - **场景 C：用户现有项目已有弹幕，仅请求 goals=['gift']**
+     - Agent 需识别现有代码中的弹幕模块，并按照场景 B 执行（补全弹幕礼物消息）。
+
+7. **UI 布局约束**：
+   - **全屏礼物**：必须覆盖在视频画面层级之上（FrameLayout 顶层）。
+   - **弹幕列表**：必须覆盖在视频画面层级之上，禁止上下分割布局。
+   - **键盘适配**：键盘弹起时视频画面必须固定（windowSoftInputMode="adjustNothing"）。
+   - **双端一致性**：全屏礼物动画在主播端和观众端都必须显示（onReceiveGift 事件会广播给所有成员）。
+
+8. **结果记录约束**：集成完成且项目启动成功后，必须调用 'record_result' 工具记录集成结果。
+`;
+const PARAMETER_DESCRIPTIONS = {
+    platform: `【必填参数】目标平台，支持：'android', 'ios', 'flutter', 'rn'。
+  - 如果用户未明确指定平台，必须先调用 'present_framework_choice' 工具让用户选择。`,
+    goals: `用户请求实现的扩展功能列表，支持：['base_beauty', 'audio_effect', 'barrage', 'gift']。
+  
+  - 'base_beauty': 基础美颜（磨皮/美白/红润 0-9）
+  - 'audio_effect': 音效控制（人声音量/耳返/变声/混响）
+  - 'barrage': 弹幕互动（发送/接收/禁言）
+  - 'gift': 礼物赠送
+    * 若 goals 仅包含 'gift'：仅集成礼物发送/接收 + 全屏礼物动画。
+    * 若 goals 包含 'gift' 和 'barrage'：集成礼物发送/接收 + 全屏礼物动画 + 弹幕礼物文本消息。
+  
+  💡 可组合使用，例如：['base_beauty', 'audio_effect', 'barrage', 'gift'] 实现完整直播扩展场景。`
+};
+export const GET_NATIVE_LIVE_EXTRA_FEATURES_DEFINITION = {
+    name: 'get_native_live_extra_features',
+    description: TOOL_DESCRIPTION,
+    parameter_descriptions: PARAMETER_DESCRIPTIONS,
+};
+//# sourceMappingURL=get_native_live_extra_features_def.js.map

package/tools/definitions/get_native_live_extra_features_def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_native_live_extra_features_def.js","sourceRoot":"","sources":["../../../src/tools/definitions/get_native_live_extra_features_def.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFxB,CAAC;AAEF,MAAM,sBAAsB,GAAG;IAC7B,QAAQ,EAAE;0DAC8C;IAExD,KAAK,EAAE;;;;;;;;;6EASoE;CAC5E,CAAC;AAEF,MAAM,CAAC,MAAM,yCAAyC,GAAG;IACvD,IAAI,EAAE,gCAAgC;IACtC,WAAW,EAAE,gBAAgB;IAC7B,sBAAsB,EAAE,sBAAsB;CAC/C,CAAC"}