@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

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

@@ -1,553 +0,0 @@
-# RoomKit Feature 自实现 UI 工作流指令
-
-## 📋 指令目的
-
-为 Agent 提供使用 **RoomKit 原子化 API/Hooks** 自定义实现音视频会议功能的代码生成蓝图。本指令专门针对**不使用完整 TUIRoomKit 页面**，而是基于原子化能力自己搭建 UI 的场景。
-
----
-
-## 🎯 适用场景
-
-本工作流适用于以下场景：
-
-- H5/移动端音视频会议应用开发
-- PC Web 端音视频会议应用开发
-- 使用 RoomKit 原子化能力自定义会议 UI
-- 集成特定功能模块（屏幕分享、美颜、聊天等）到现有应用
-- 深度定制会议界面或业务流程
-
----
-
-## 🛑 核心约束与规范
-
-### 1. 登录与鉴权（前置必须）
-
-**🔐 核心原则**：Feature 自实现 UI 模式下，**必须使用 `get_usersig` 工具 + `useLoginState` Hook 进行登录鉴权**，禁止手动编写 UserSig 生成代码。
-
-#### 为什么需要登录？
-
-使用 TUIRoomKit 的原子化 API（useRoomState、useDeviceState 等）之前，必须先完成登录鉴权：
-- **身份验证**：确保用户有权限使用腾讯云 TRTC 服务
-- **SDK 初始化**：登录成功后 SDK 才能正常工作
-- **数据同步**：登录后才能接收房间、成员等实时数据
-
-#### 登录代码示例
-
-```vue
-<script setup lang="ts">
-import { useLoginState } from 'tuikit-atomicx-vue3';
-
-// 标准用法：解构出需要的方法和状态
-const { login, loginUserInfo } = useLoginState();
-
-async function performLogin() {
-  try {
-    // 使用 get_usersig 工具返回的信息进行登录
-    await login({
-      sdkAppId: YOUR_SDK_APP_ID,    // 来自 get_usersig 工具
-      userId: YOUR_USER_ID,          // 来自 get_usersig 工具
-      userSig: YOUR_USER_SIG,        // 来自 get_usersig 工具
-    });
-    console.log('登录成功，用户ID:', loginUserInfo.value?.userID);
-    // 登录成功后，可以使用其他功能模块
-  } catch (error) {
-    console.error('登录失败:', error);
-  }
-}
-</script>
-```
-
-#### 强制约束与规范
-
-| 约束项 | 要求 | 说明 |
-|--------|------|------|
-| **UserID 生成规则** | ✅ **格式**：`userXXX`（XXX 为数字）<br>✅ **示例**：`user123`、`user001`、`user999`<br>❌ **禁止**使用特殊连接符（如 `user_123`、`user-001`） | 测试环境使用简单的 userID 格式，方便识别和调试 |
-| **UserSig 生成（强制）** | ✅ **必须**使用 `get_usersig` MCP 工具生成<br>❌ **严禁**在项目中编写 `generateUserSig` 函数<br>❌ **严禁**在项目中引入 `GenerateTestUserSig` 类<br>❌ **严禁**编写任何 UserSig 生成逻辑 | **集成测试必须使用 get_usersig 工具**，Agent 只能调用该工具获取 UserSig，不得生成任何相关代码 |
-| **登录 API** | ✅ **必须**使用 `useLoginState` Hook 的 login 方法<br>❌ **禁止**直接调用 SDK 底层 API | 使用原子化 Hook 的 API，不要直接操作 TUIRoomEngine |
-| **登录时机** | ✅ **必须**在使用任何其他功能前完成登录<br>⚠️ 登录失败会导致所有功能无法使用 | 建议在应用启动时或进入会议前完成登录 |
-| **安全提醒** | ⚠️ **必须**告知用户：<br>• 客户端生成 UserSig 仅用于开发测试<br>• 生产环境必须在服务端生成 UserSig<br>• 不要将 secretKey 暴露在客户端代码中 | UserSig 包含用户身份信息，必须保证安全 |
-
-#### UserSig 生成强制规范（重要）
-
-**核心原则**：**集成测试阶段，UserSig 必须由 `get_usersig` MCP 工具生成，严禁在项目代码中实现任何 UserSig 生成逻辑**。
-
-##### ✅ 正确做法：使用 get_usersig 工具
-
-```typescript
-// ✅ 正确：Agent 调用 get_usersig 工具获取凭证
-// 工具返回：{ sdkAppId: 1400xxx, userId: 'user123', userSig: 'eJw...' }
-
-// 在项目代码中直接使用工具返回的值
-const { login } = useLoginState();
-
-await login({
-  sdkAppId: 1400188366,           // 来自 get_usersig 工具
-  userId: 'user123',              // 来自 get_usersig 工具
-  userSig: 'eJw1jdEKgj...',      // 来自 get_usersig 工具
-});
-```
-
-##### ❌ 错误做法：在项目中生成 UserSig
-
-```typescript
-// ❌ 严禁：编写 generateUserSig 函数
-function generateUserSig(userId: string) {
-  const SDKAPPID = 1400188366;
-  const SECRETKEY = 'your-secret-key';
-  // ... HMAC-SHA256 算法实现
-  return userSig;
-}
-
-// ❌ 严禁：引入 GenerateTestUserSig 类
-import GenerateTestUserSig from './debug/GenerateTestUserSig';
-const { userSig } = GenerateTestUserSig.genTestUserSig(userId);
-
-// ❌ 严禁：从任何文件导入 UserSig 生成逻辑
-import { createUserSig } from './utils/usersig';
-
-// ❌ 严禁：任何形式的 UserSig 生成代码
-const userSig = crypto.createHmac('sha256', SECRETKEY).update(data).digest('base64');
-```
-
-**为什么禁止**：
-1. **安全风险**：项目中包含 secretKey 会导致密钥泄露
-2. **违背最佳实践**：集成测试应使用工具，生产环境应使用服务端 API
-3. **误导用户**：容易让用户认为客户端生成 UserSig 是正确做法
-
-**Agent 行为约束**：
-- ✅ **必须**调用 `get_usersig` MCP 工具获取 UserSig
-- ✅ **必须**在代码注释中说明这些值来自 get_usersig 工具
-- ❌ **严禁**生成任何包含 `generateUserSig`、`GenerateTestUserSig`、`SECRETKEY` 的代码
-- ❌ **严禁**创建任何 UserSig 生成相关的工具函数或类
-
----
-
-### 2. 文档驱动开发
-
-- ✅ **严格遵循**本次返回的功能文档内容
-- ✅ **优先使用**文档中的代码示例和最佳实践
-- ❌ **禁止擅自修改**文档提供的 API 调用方式和参数
-- ⚠️ **禁止使用记忆中的 API**：必须以 feature 文档为准，不要使用训练数据中的过时 API
-
----
-
-### 3. API 版本约束（重要）
-
-**核心原则**：**严格使用 feature 文档中列出的 API，禁止使用任何未在文档中出现的 API 名称**。
-
-#### API 使用流程（必须遵守）
-
-```
-1. 查阅本次返回的 feature 文档中的 API 列表
-   ↓
-2. 对照官方 API 文档确认 API 签名和用法
-   ↓
-3. 使用文档中明确列出的 API 生成代码
-```
-
-**官方 API 文档**：
-- 📚 **TUIRoomKit API 参考**：https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
-- ⚠️ **任何 API 使用前必须在此文档中确认其存在性和签名**
-
-**强制约束**：
-1. ✅ **必须**以 feature 文档中的 API 列表为准
-2. ✅ **必须**在官方文档（https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html）中确认 API 存在
-3. ❌ **禁止**使用训练数据或记忆中的 API 名称
-4. ❌ **禁止**使用未在 feature 文档中列出的 API
-5. ⚠️ 如果 feature 文档中没有列出某个 API，说明该 API 已废弃或不存在
-
-**API 验证检查清单**：
-- [ ] API 名称在 feature 文档中明确列出？
-- [ ] API 在官方文档中存在？
-- [ ] API 签名与官方文档一致？
-- [ ] 没有使用记忆中的过时 API？
-
----
-
-## 📚 RoomKit State API 架构说明
-
-> **说明**：本节说明 TUIRoomKit (Atomicx 版本) 的 State API 架构和使用规范，详细的 API 参数和代码示例请参考具体的 feature 文档。
-
-### 🔍 API 架构概述
-
-TUIRoomKit Atomicx 版本采用响应式（Reactive）设计，将功能划分为不同的 State 模块。每个模块通过 `use[StateName]` Hook 提供响应式数据和操作方法。
-
-**核心设计理念**：
-- ✅ **响应式数据**：所有状态都是 Vue 3 Ref，可直接在模板中使用或通过 `watch` 监听
-- ✅ **模块化解构**：按需解构所需的方法和状态，避免引入不必要的依赖
-- ✅ **标准调用方式**：`const { method, state } = useXxxState()`
-
----
-
-### 📝 使用规范（重要）
-
-#### 1. 标准解构方式
-
-✅ **正确**：
-```typescript
-const { login, loginUserInfo } = useLoginState();
-await login({ sdkAppId, userId, userSig });
-```
-
-❌ **错误**：
-```typescript
-const loginState = useLoginState();
-await loginState.login({ sdkAppId, userId, userSig });
-```
-
-#### 2. 响应式数据访问
-
-✅ **正确**：
-```typescript
-const { loginUserInfo } = useLoginState();
-
-// 在 setup 中访问
-if (loginUserInfo.value) {
-  console.log(loginUserInfo.value.userID);
-}
-
-// 在模板中访问（自动解包）
-<template>
-  <div v-if="loginUserInfo">
-    {{ loginUserInfo.userID }}
-  </div>
-</template>
-```
-
-❌ **错误**：
-```typescript
-// 忘记使用 .value
-if (loginUserInfo) {  // ❌ loginUserInfo 是 Ref 对象，不是布尔值
-  console.log(loginUserInfo.userID);  // ❌ 无法访问
-}
-```
-
-#### 3. 状态监听
-
-```typescript
-import { watch } from 'vue';
-const { loginUserInfo } = useLoginState();
-
-// 监听登录状态变化
-watch(loginUserInfo, (newInfo, oldInfo) => {
-  if (newInfo) {
-    console.log('用户已登录:', newInfo.userID);
-  } else {
-    console.log('用户已登出');
-  }
-});
-```
-
----
-
-### 🔗 参考资源
-
-- **官方 API 文档**：https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
-- **详细代码示例**：参考各功能模块的具体 feature 文档
-
----
-
-## 🏗️ 通用集成步骤
-
-#### 步骤 1：安装依赖
-
-**核心依赖**：
-
-```json
-{
-  "tuikit-atomicx-vue3": "latest",                        // TUIRoomKit 原子化组件库（包含所有 Hooks 和 UI 组件，会自动安装 tuiroom-engine-js）
-  "@tencentcloud/uikit-base-component-vue3": "latest",    // 基础 UI 组件库（按钮、输入框等通用组件）
-  "vue-router": "^4.0.0"                                   // Vue 路由（用于页面导航，如需路由功能时安装）
-}
-```
-
-**依赖说明**：
-- **tuikit-atomicx-vue3**: 核心包，包含所有原子化 Hooks 和 UI 组件，会自动安装 `@tencentcloud/tuiroom-engine-js`
-- **@tencentcloud/uikit-base-component-vue3**: 基础 UI 组件库（如需使用 TUIKit UI 组件时安装）
-- **vue-router**: Vue 路由库（如需实现页面导航时安装）
-
-**安装命令**：
-
-```bash
-# 最小化安装（仅核心包）
-npm install tuikit-atomicx-vue3
-
-# 完整安装（包含 UI 组件库和路由）
-npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
-
-# 或使用 pnpm
-pnpm install tuikit-atomicx-vue3
-pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
-```
-
-**构建环境补丁（Vite 项目）**：
-
-若检测到 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 版本
-
-#### 步骤 2：登录鉴权（前置必须）
-
-所有功能模块使用前必须先完成登录。详细代码请参考具体 feature 文档中的示例。
-
-#### 步骤 3：引入和使用功能 Hook
-
-所有 Hooks 都从 `tuikit-atomicx-vue3` 导入，具体 API 调用方式请参考 feature 文档。
-
----
-
-## 🎨 代码生成规范
-
-### 1. Vue 3 组合式 API
-
-- 使用 `<script setup lang="ts">` 语法
-- 使用 Vue 3 Composition API（ref、reactive、computed、onMounted 等）
-- 从 `tuikit-atomicx-vue3` 导入所需 Hooks
-
-### 2. TypeScript 类型安全
-
-- 使用官方类型定义（从 `@tencentcloud/tuiroom-engine-js` 导入）
-- 为状态变量添加正确的类型注解
-
-### 3. 错误处理
-
-- 所有异步操作必须使用 try-catch 处理错误
-- 提供友好的错误提示
-
-### 4. 麦克风开关最佳实践（重要）
-
-#### 核心原则
-
-**麦克风物理开启只在进房时执行一次，中途开关使用静音/取消静音**。
-
-#### 实现方式
-
-| 场景 | API 调用 | 说明 |
-|------|---------|------|
-| **进房时开启麦克风** | `await openLocalMicrophone()`<br>`await unmuteLocalAudio()` | 物理打开麦克风设备并取消静音 |
-| **中途关闭麦克风** | `await muteLocalAudio()` | 仅静音，不关闭物理设备 |
-| **中途开启麦克风** | `await unmuteLocalAudio()` | 仅取消静音，不重新打开物理设备 |
-
-#### 代码示例
-
-```typescript
-import { useDeviceState } from 'tuikit-atomicx-vue3';
-
-const { openLocalMicrophone, muteLocalAudio, unmuteLocalAudio } = useDeviceState();
-
-// ✅ 正确：进房时初始化麦克风
-async function enterRoomWithMicrophone() {
-  try {
-    // 1. 加入房间
-    await joinRoom('room123');
-    
-    // 2. 物理打开麦克风（仅此一次）
-    await openLocalMicrophone();
-    
-    // 3. 取消静音
-    await unmuteLocalAudio();
-  } catch (error) {
-    console.error('初始化麦克风失败:', error);
-  }
-}
-
-// ✅ 正确：中途关闭麦克风（静音）
-async function closeMicInRoom() {
-  try {
-    await muteLocalAudio();  // 仅静音，不关闭物理设备
-  } catch (error) {
-    console.error('静音失败:', error);
-  }
-}
-
-// ✅ 正确：中途开启麦克风（取消静音）
-async function openMicInRoom() {
-  try {
-    await unmuteLocalAudio();  // 仅取消静音，不重新打开物理设备
-  } catch (error) {
-    console.error('取消静音失败:', error);
-  }
-}
-
-// ❌ 错误：中途重复调用 openLocalMicrophone
-async function wrongWayToOpenMic() {
-  // 不要在中途调用，会导致延迟和吞音问题
-  await openLocalMicrophone();  // ❌ 错误！
-  await unmuteLocalAudio();
-}
-```
-
-#### 技术原因
-
-1. **性能优化**：麦克风物理设备的开启需要硬件初始化，耗时较长（通常 100-300ms）
-2. **避免吞音**：频繁打开/关闭物理设备可能导致音频流的首包丢失，造成吞音现象
-3. **用户体验**：静音/取消静音操作即时响应，无延迟感
-
-#### 强制约束
-
-- ✅ **必须**在进房时调用 `openLocalMicrophone()` 初始化麦克风
-- ✅ **必须**在中途开关麦克风时使用 `muteLocalAudio()` / `unmuteLocalAudio()`
-- ❌ **禁止**在会议中途重复调用 `openLocalMicrophone()`
-- ❌ **禁止**使用 `closeLocalMicrophone()` 然后再 `openLocalMicrophone()` 的方式
-
-### 5. 视频流渲染最佳实践（推荐）
-
-#### 核心原则
-
-**使用 State API 开发时，推荐使用 `RoomParticipantView` 组件渲染视频流**。
-
-#### 平台适用性
-
-| 组件 | 适用平台 | 说明 |
-|------|---------|------|
-| **RoomParticipantView** | ✅ H5 移动端<br>✅ PC Web 端 | **H5 开发优先推荐**，轻量级，适配移动端和桌面端 |
-| **RoomView** | ✅ PC Web 端 | 仅适用于 PC 端，包含完整的会议室布局 |
-
-**强制约束**：
-- ✅ **H5 移动端开发**：必须使用 `RoomParticipantView` 组件
-- ✅ **PC Web 端开发**：优先推荐 `RoomParticipantView` 组件，更灵活
-- ⚠️ **RoomView** 仅用于 PC 端且需要完整会议室布局的场景
-
-#### 推荐导入方式
-
-```typescript
-import { RoomParticipantView } from 'tuikit-atomicx-vue3/room';
-```
-
-#### 使用示例
-
-##### 基础用法：直接渲染参与者视频
-
-```vue
-<template>
-  <div class="video-container">
-    <!-- 渲染本地视频流 -->
-    <RoomParticipantView
-      v-if="localParticipant"
-      :participant="localParticipant"
-      :stream-type="VideoStreamType.Camera"
-    />
-    
-    <!-- 渲染远端视频流 -->
-    <RoomParticipantView
-      v-for="user in remoteParticipants"
-      :key="user.userId"
-      :participant="user"
-      :stream-type="VideoStreamType.Camera"
-    />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { RoomParticipantView, VideoStreamType } from 'tuikit-atomicx-vue3/room';
-import { useRoomParticipantState } from 'tuikit-atomicx-vue3';
-
-const { localParticipant, remoteParticipants } = useRoomParticipantState();
-</script>
-```
-
-##### 高级用法：区分本地屏幕分享和摄像头流
-
-```vue
-<template>
-  <LocalScreenViewUI v-if="isLocalScreen" />
-  <ParticipantViewUI
-    v-else
-    :participant="participant"
-    :stream-type="streamType"
-  />
-</template>
-
-<script setup lang="ts">
-import { computed } from 'vue';
-import { useRoomParticipantState, VideoStreamType } from 'tuikit-atomicx-vue3/room';
-import LocalScreenViewUI from './LocalScreenViewUI.vue';
-import ParticipantViewUI from './ParticipantViewUI.vue';
-import type { RoomParticipant } from 'tuikit-atomicx-vue3/room';
-
-interface Props {
-  participant: RoomParticipant;
-  streamType: VideoStreamType;
-}
-const props = defineProps<Props>();
-
-const { localParticipant } = useRoomParticipantState();
-
-// 判断是否为本地屏幕分享流
-const isLocalScreen = computed(() => 
-  props.participant.userId === localParticipant.value?.userId && 
-  props.streamType === VideoStreamType.Screen
-);
-</script>
-```
-
-#### 优势
-
-1. **自动管理视频流**：组件内部自动处理视频流的订阅、渲染和销毁
-2. **状态同步**：自动同步用户的音视频状态（静音、关闭摄像头等）
-3. **简化开发**：无需手动操作 DOM 或管理视频元素
-4. **最佳实践**：封装了 TRTC 视频渲染的最佳实践和优化
-
-#### 强制约束
-
-- ✅ **推荐**使用 `RoomParticipantView` 组件渲染视频流
-- ✅ **必须**从 `tuikit-atomicx-vue3/room` 导入
-- ⚠️ 如需自定义渲染逻辑，请参考 feature 文档中的高级用法
-
-**详细代码示例请参考具体 feature 文档。**
-
----
-
-## 🔗 工具参考
-
-### `get_usersig` - 生成用户签名（登录必须）
-
-**用途**：Agent 调用此 MCP 工具获取登录凭证（SDKAppID、userID、userSig），用于用户代码中的登录调用。
-
-**强制约束**：
-- ✅ Agent 必须调用此工具获取登录凭证
-- ❌ 禁止手动编写 UserSig 生成代码
-- ⚠️ 必须告知用户：生产环境中应在服务端生成 UserSig
-
----
-
-### `record_result` - 记录集成结果
-
-**用途**：记录功能集成过程和结果，用于统计分析
-
-**调用时机**：在完成功能集成并验证无误后调用
-
----
-
-## 📝 关键要点总结
-
-| 类别 | 要求 |
-|------|------|
-| **适用场景** | 使用 RoomKit 原子化 API 自定义实现会议 UI |
-| **平台支持** | ✅ RoomKit State API 完全支持 H5 移动端和 PC Web 端 |
-| **登录鉴权** | ✅ 必须使用 `get_usersig` 工具 + `useLoginState` Hook |
-| **API 调用** | ✅ 必须使用官方 Hooks（useRoomState、useDeviceState 等） |
-| **文档优先** | 严格遵循本次返回的功能文档内容 |
-| **错误处理** | 所有异步操作必须使用 try-catch 处理错误 |
-| **安全提示** | ⚠️ 必须告知用户：生产环境中 UserSig 应在服务端生成 |
-| **支持框架** | Vue 3.4.21+ (使用 Composition API) |
-
----
-
-**适用框架**: Vue 3.4.21+  
-**集成模式**: Feature 自实现 UI（原子化 API）  
-**平台支持**: H5 移动端 + PC Web 端