@tencentcloud/sdk-mcp 1.3.0 → 1.3.2

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/chat/get-web-chat-integration.js

@@ -2,27 +2,44 @@ import { z } from 'zod';
 import { GET_WEB_CHAT_UIKIT_INTEGRATION_DEFINITION } from '../definitions/get_web_chat_uikit_integration_def.js';
 import { getDocContent } from '../../utils/get-doc-content.js';
 import { reportCLSClient } from '../../utils/report-cls-client.js';
-import { handleFramework } from '../../utils/handle-framework.js';
-function getResultText(params) {
-    const { framework = '' } = params;
+import { generateStructuredResult } from '../../utils/generate-structured-result.js';
+async function getResultText(params) {
+    const { framework = '', goals = [] } = params;
     reportCLSClient({
         method: 'get_web_chat_uikit_integration',
-        framework: framework,
+        info: goals.join(','),
+        framework,
     });
-    return getDocContent(['chatuikit', `${handleFramework(framework)}`, 'integration.md']);
+    // 获取工作流指令
+    const baseInstructions = getDocContent(['chatuikit', framework, 'workflow.md']);
+    // 批量读取目标文档并生成结构化结果
+    const result = await generateStructuredResult({
+        baseInstructions,
+        goals,
+        framework,
+        pathMap: {
+            [goals[0]]: ['chatuikit', framework, 'integration.md'],
+        },
+    });
+    return result;
 }
 const registryGetWebChatIntegrationTool = (mcpServer) => {
     const { name, description, parameter_descriptions } = GET_WEB_CHAT_UIKIT_INTEGRATION_DEFINITION;
     mcpServer.tool(name, description, {
-        framework: z.enum(['react', 'vue']).describe(parameter_descriptions.framework),
-    }, (params) => ({
-        content: [
-            {
-                type: 'text',
-                text: getResultText(params),
-            }
-        ]
-    }));
+        framework: z.enum(['react', 'vue', 'uniapp-app']).describe(parameter_descriptions.framework),
+        goals: z.array(z.enum(['full-featured', 'chat-only'])).describe(parameter_descriptions.goals)
+    }, async (params) => {
+        const result = await getResultText(params);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: result.llm_code_generation_instructions_md,
+                }
+            ],
+            result: result,
+        };
+    });
 };
 export { registryGetWebChatIntegrationTool };
 //# sourceMappingURL=get-web-chat-integration.js.map

package/tools/chat/get-web-chat-integration.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-web-chat-integration.js","sourceRoot":"","sources":["../../../src/tools/chat/get-web-chat-integration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yCAAyC,EAAE,MAAM,sDAAsD,CAAC;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,SAAS,aAAa,CAAC,MAA2B;IAChD,MAAM,EAAE,SAAS,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC;IAClC,eAAe,CAAC;QACd,MAAM,EAAE,gCAAgC;QACxC,SAAS,EAAE,SAAS;KACrB,CAAC,CAAC;IACH,OAAO,aAAa,CAAC,CAAC,WAAW,EAAE,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,iCAAiC,GAAG,CAAC,SAAoB,EAAE,EAAE;IACjE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE,GAAG,yCAAyC,CAAC;IAChG,SAAS,CAAC,IAAI,CACZ,IAAI,EACJ,WAAW,EACX;QACE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC;KAC/E,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACd,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC;aAC5B;SACF;KACF,CAAC,CAAC,CAAC;AACR,CAAC,CAAC;AACF,OAAO,EAAE,iCAAiC,EAAE,CAAC"}
+{"version":3,"file":"get-web-chat-integration.js","sourceRoot":"","sources":["../../../src/tools/chat/get-web-chat-integration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yCAAyC,EAAE,MAAM,sDAAsD,CAAC;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAErF,KAAK,UAAU,aAAa,CAAC,MAA2B;IACtD,MAAM,EAAE,SAAS,GAAG,EAAE,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC;IAC9C,eAAe,CAAC;QACd,MAAM,EAAE,gCAAgC;QACxC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;QACrB,SAAS;KACV,CAAC,CAAC;IACH,UAAU;IACV,MAAM,gBAAgB,GAAG,aAAa,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAChF,mBAAmB;IACnB,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC;QAC5C,gBAAgB;QAChB,KAAK;QACL,SAAS;QACT,OAAO,EAAE;YACP,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,gBAAgB,CAAC;SACvD;KACF,CAAC,CAAA;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,iCAAiC,GAAG,CAAC,SAAoB,EAAE,EAAE;IACjE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,EAAE,GAAG,yCAAyC,CAAC;IAChG,SAAS,CAAC,IAAI,CACZ,IAAI,EACJ,WAAW,EACX;QACE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC;QAC5F,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC,KAAK,CAAC;KAC9F,EACD,KAAK,EAAE,MAAW,EAAE,EAAE;QACpB,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAA;QAC1C,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,MAAM,CAAC,mCAAmC;iBACjD;aACF;YACD,MAAM,EAAE,MAAM;SACf,CAAA;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,OAAO,EAAE,iCAAiC,EAAE,CAAC"}

package/tools/definitions/get_web_chat_uikit_integration_def.js

@@ -1,22 +1,29 @@
 const TOOL_DESCRIPTION = `
-【核心用途】：这是一个 Web 聊天应用集成工具，专用于提供 TUIKit 组件在 Web 或 H5 端的集成方案。\n
+【核心用途】：作为一个专业的 Web/跨平台聊天 TUIKit 集成助手，本工具专用于为 Agent 提供工作流行动指令和实时聚合的最新文档内容，以指导 LLM 帮用户实现即时通信（IM）功能。\n
 
-【功能范围】：\n
-1. 搭建类似微信/企微功能和 UI 的即时通讯应用，适用于聊天、客服、医疗等场景。\n
-2. 支持 React 和 Vue 两种主流框架的 UI 组件库。\n
-3. 应用入口可以根据需要设置在 TabBar 上，命名可包含消息、会话、讯息等关键词。\n
+【功能目标 (Goals)】：\n
+1. full-featured: 集成全量功能。包含会话列表、聊天窗口、群组管理、个人中心等。**适用于构建微信/企微风格的完整应用，或作为 App 的核心 Tab 模块。**
+2. chat-only: 仅集成聊天窗口。**适用于客服咨询、医疗在线问诊、订单详情页私聊等轻量级对话场景。**。
 
-【关键词】：'Web', 'H5', '聊天应用', 'TUIKit', 'React', 'Vue', '集成', '即时通信', '客服', '医疗', 'TabBar'。
+【关键词】：\n
+'Chat', 'TUIKit', '聊天', '即时通信', '微信', '企微', 'React', 'Vue', 'uniapp', '集成', '客服', '医疗问诊', 'TabBar', '消息入口', '会话列表', '对话框'。
+
+【行动指令与工作流引导】：\n
+Agent 在处理用户需求时，应使用本工具返回的 llm_code_generation_instructions_md 字段。这个字段包含了：
+1. 核心工作流指令：包含环境准备、依赖安装、初始化 SDK、鉴权 UserSig 以及组件的版本说明。
+2. 实时文档内容：根据选择的 goals 动态返回对应的官方集成指南。
+
+LLM 必须优先且唯一使用本工具返回的实时内容生成代码，避免自行访问外部 URL。\n
 
 【强制约束】：\n
-1. 框架选择约束：如果用户在提示词中没有明确指定 React 或 Vue 框架，必须优先调用 'present_framework_choice' 工具，引导用户进行选择。\n
-2. 结果记录约束：在 TUIKit 组件集成完成且项目启动成功后，必须调用 'record_result' 工具记录集成结果。\n
+1. 框架选择约束：如果用户未明确指定框架，或意图不清晰，必须优先调用 'present_framework_choice' 工具，引导用户在 react, vue, uniapp-app 中进行选择。
+2. 结果记录约束：在 TUIKit 组件集成完成且项目启动成功后，必须调用 'record_result' 工具记录集成结果。
 
-【注意事项】：
-- 集成 Vue 版本时，请安装 @tencentcloud/chat-uikit-vue3。
+【支持框架】：react, vue, uniapp-app。
 `;
 const PARAMETER_DESCRIPTIONS = {
-    framework: 'Web Chat TUIKit 框架类型。可选值：react, vue。用于确定提供哪个框架下的组件集成方案。',
+    framework: '聊天 TUIKit 框架类型。可选值：react (React Web), vue (Vue3 Web), uniapp-app (Uni-app App端/H5)。',
+    goals: "用户请求实现的功能目标列表。可选值：['full-featured'] (标准应用), ['chat-only'] (客服/问诊/弹窗)。",
 };
 export const GET_WEB_CHAT_UIKIT_INTEGRATION_DEFINITION = {
     name: 'get_web_chat_uikit_integration',

package/tools/definitions/get_web_chat_uikit_integration_def.js.map

@@ -1 +1 @@
-{"version":3,"file":"get_web_chat_uikit_integration_def.js","sourceRoot":"","sources":["../../../src/tools/definitions/get_web_chat_uikit_integration_def.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;CAgBxB,CAAC;AAEF,MAAM,sBAAsB,GAAG;IAC7B,SAAS,EAAE,yDAAyD;CACrE,CAAC;AAEF,MAAM,CAAC,MAAM,yCAAyC,GAAG;IACvD,IAAI,EAAE,gCAAgC;IACtC,WAAW,EAAE,gBAAgB;IAC7B,sBAAsB,EAAE,sBAAsB;CAC/C,CAAC"}
+{"version":3,"file":"get_web_chat_uikit_integration_def.js","sourceRoot":"","sources":["../../../src/tools/definitions/get_web_chat_uikit_integration_def.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBxB,CAAC;AAEF,MAAM,sBAAsB,GAAG;IAC7B,SAAS,EAAE,qFAAqF;IAChG,KAAK,EAAE,uEAAuE;CAC/E,CAAC;AAEF,MAAM,CAAC,MAAM,yCAAyC,GAAG;IACvD,IAAI,EAAE,gCAAgC;IACtC,WAAW,EAAE,gBAAgB;IAC7B,sBAAsB,EAAE,sBAAsB;CAC/C,CAAC"}

package/tools/definitions/get_web_live_uikit_integration_def.js

@@ -6,7 +6,7 @@ const TOOL_DESCRIPTION = `
 
  【行动指令与工作流引导】：\n
  Agent 在处理用户需求时，应使用本工具返回的 llm_code_generation_instructions_md 字段。这个字段包含了：
- 1. 核心工作流指令（来自 integration.md）。
+ 1. 核心工作流指令（来自 workflow.md）。
  2. 用户所需功能（Goals）对应的最新、实时获取的官方文档内容。
  
  LLM 必须优先且唯一使用本工具返回的实时文档内容生成代码，避免自行访问外部 URL。\n