@tencentcloud/sdk-mcp 1.3.1 → 1.3.2

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

@@ -0,0 +1,553 @@
+# 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 端