@tencent-rtc/mcp 1.3.8 → 1.4.0

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

@@ -1,553 +0,0 @@
-# RoomKit Feature Custom UI Workflow Instructions
-
-## 📋 Instruction Purpose
-
-Provide agents with a code generation blueprint for implementing audio/video conferencing features using **RoomKit atomic API/Hooks** for customization. This instruction is specifically designed for scenarios where **the complete TUIRoomKit page is not used**, but UI is built based on atomic capabilities.
-
----
-
-## 🎯 Applicable Scenarios
-
-This workflow is applicable to the following scenarios:
-
-- H5/Mobile audio/video conferencing application development
-- PC Web audio/video conferencing application development
-- Customizing conference UI using RoomKit atomic capabilities
-- Integrating specific feature modules (screen sharing, beauty effects, chat, etc.) into existing applications
-- Deep customization of conference interface or business processes
-
----
-
-## 🛑 Core Constraints and Specifications
-
-### 1. Login and Authentication (Prerequisites)
-
-**🔐 Core Principle**: In Feature custom UI mode, **must use `get_usersig` tool + `useLoginState` Hook for login authentication**, manual UserSig generation code is prohibited.
-
-#### Why Login is Required?
-
-Before using TUIRoomKit's atomic APIs (useRoomState, useDeviceState, etc.), login authentication must be completed:
-- **Identity Verification**: Ensure users have permission to use Tencent Cloud TRTC service
-- **SDK Initialization**: SDK can only work properly after successful login
-- **Data Synchronization**: Can only receive real-time data such as rooms and members after login
-
-#### Login Code Example
-
-```vue
-<script setup lang="ts">
-import { useLoginState } from 'tuikit-atomicx-vue3';
-
-// Standard usage: destructure required methods and states
-const { login, loginUserInfo } = useLoginState();
-
-async function performLogin() {
-  try {
-    // Login with information returned by get_usersig tool
-    await login({
-      sdkAppId: YOUR_SDK_APP_ID,    // From get_usersig tool
-      userId: YOUR_USER_ID,          // From get_usersig tool
-      userSig: YOUR_USER_SIG,        // From get_usersig tool
-    });
-    console.log('Login successful, userID:', loginUserInfo.value?.userID);
-    // After successful login, other feature modules can be used
-  } catch (error) {
-    console.error('Login failed:', error);
-  }
-}
-</script>
-```
-
-#### Mandatory Constraints and Specifications
-
-| Constraint | Requirement | Description |
-|--------|------|------|
-| **UserID Generation Rules** | ✅ **Format**: `userXXX` (XXX is digits)<br>✅ **Example**: `user123`, `user001`, `user999`<br>❌ **Prohibited** to use special connectors (such as `user_123`, `user-001`) | Use simple userID format in test environment for easy identification and debugging |
-| **UserSig Generation (Mandatory)** | ✅ **Must** use `get_usersig` MCP tool to generate<br>❌ **Strictly Prohibited** to write `generateUserSig` function in project<br>❌ **Strictly Prohibited** to import `GenerateTestUserSig` class in project<br>❌ **Strictly Prohibited** to write any UserSig generation logic | **Integration testing must use get_usersig tool**, Agent can only call this tool to obtain UserSig, and must not generate any related code |
-| **Login API** | ✅ **Must** use login method of `useLoginState` Hook<br>❌ **Prohibited** to directly call SDK underlying API | Use atomic Hook's API, do not directly operate TUIRoomEngine |
-| **Login Timing** | ✅ **Must** complete login before using any other features<br>⚠️ Login failure will cause all features to be unavailable | Recommended to complete login at application startup or before entering meeting |
-| **Security Reminder** | ⚠️ **Must** inform users:<br>• Client-generated UserSig is only for development testing<br>• Production environment must generate UserSig on server side<br>• Do not expose secretKey in client code | UserSig contains user identity information and must be kept secure |
-
-#### UserSig Generation Mandatory Specifications (Important)
-
-**Core Principle**: **During integration testing, UserSig must be generated by `get_usersig` MCP tool, strictly prohibit implementing any UserSig generation logic in project code**.
-
-##### ✅ Correct Approach: Use get_usersig Tool
-
-```typescript
-// ✅ Correct: Agent calls get_usersig tool to obtain credentials
-// Tool returns: { sdkAppId: 1400xxx, userId: 'user123', userSig: 'eJw...' }
-
-// Use values returned by tool directly in project code
-const { login } = useLoginState();
-
-await login({
-  sdkAppId: 1400188366,           // From get_usersig tool
-  userId: 'user123',              // From get_usersig tool
-  userSig: 'eJw1jdEKgj...',      // From get_usersig tool
-});
-```
-
-##### ❌ Wrong Approach: Generate UserSig in Project
-
-```typescript
-// ❌ Strictly Prohibited: Write generateUserSig function
-function generateUserSig(userId: string) {
-  const SDKAPPID = 1400188366;
-  const SECRETKEY = 'your-secret-key';
-  // ... HMAC-SHA256 algorithm implementation
-  return userSig;
-}
-
-// ❌ Strictly Prohibited: Import GenerateTestUserSig class
-import GenerateTestUserSig from './debug/GenerateTestUserSig';
-const { userSig } = GenerateTestUserSig.genTestUserSig(userId);
-
-// ❌ Strictly Prohibited: Import UserSig generation logic from any file
-import { createUserSig } from './utils/usersig';
-
-// ❌ Strictly Prohibited: Any form of UserSig generation code
-const userSig = crypto.createHmac('sha256', SECRETKEY).update(data).digest('base64');
-```
-
-**Why Prohibited**:
-1. **Security Risk**: Including secretKey in project will cause key leakage
-2. **Against Best Practices**: Integration testing should use tools, production environment should use server-side API
-3. **Misleading Users**: Easy to make users think client-generated UserSig is the correct approach
-
-**Agent Behavior Constraints**:
-- ✅ **Must** call `get_usersig` MCP tool to obtain UserSig
-- ✅ **Must** explain in code comments that these values come from get_usersig tool
-- ❌ **Strictly Prohibited** to generate any code containing `generateUserSig`, `GenerateTestUserSig`, `SECRETKEY`
-- ❌ **Strictly Prohibited** to create any utility functions or classes related to UserSig generation
-
----
-
-### 2. Documentation-Driven Development
-
-- ✅ **Strictly follow** the content of feature documentation returned this time
-- ✅ **Prioritize using** code examples and best practices in documentation
-- ❌ **Prohibited to arbitrarily modify** API calling methods and parameters provided in documentation
-- ⚠️ **Prohibited to use APIs from memory**: Must follow feature documentation, do not use outdated APIs from training data
-
----
-
-### 3. API Version Constraints (Important)
-
-**Core Principle**: **Strictly use APIs listed in feature documentation, prohibit using any API names not appearing in documentation**.
-
-#### API Usage Process (Must Follow)
-
-```
-1. Check API list in feature documentation returned this time
-   ↓
-2. Confirm API signature and usage against official API documentation
-   ↓
-3. Generate code using APIs explicitly listed in documentation
-```
-
-**Official API Documentation**:
-- 📚 **TUIRoomKit API Reference**: https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
-- ⚠️ **Any API usage must confirm its existence and signature in this documentation first**
-
-**Mandatory Constraints**:
-1. ✅ **Must** follow API list in feature documentation
-2. ✅ **Must** confirm API existence in official documentation (https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html)
-3. ❌ **Prohibited** to use API names from training data or memory
-4. ❌ **Prohibited** to use APIs not listed in feature documentation
-5. ⚠️ If an API is not listed in feature documentation, it means the API is deprecated or does not exist
-
-**API Verification Checklist**:
-- [ ] API name explicitly listed in feature documentation?
-- [ ] API exists in official documentation?
-- [ ] API signature consistent with official documentation?
-- [ ] Not using outdated APIs from memory?
-
----
-
-## 📚 RoomKit State API Architecture Description
-
-> **Note**: This section explains TUIRoomKit (Atomicx version) State API architecture and usage specifications. For detailed API parameters and code examples, please refer to specific feature documentation.
-
-### 🔍 API Architecture Overview
-
-TUIRoomKit Atomicx version adopts Reactive design, dividing features into different State modules. Each module provides reactive data and operation methods through `use[StateName]` Hook.
-
-**Core Design Concept**:
-- ✅ **Reactive Data**: All states are Vue 3 Refs, can be directly used in templates or monitored through `watch`
-- ✅ **Modular Destructuring**: Destructure required methods and states as needed to avoid introducing unnecessary dependencies
-- ✅ **Standard Calling Method**: `const { method, state } = useXxxState()`
-
----
-
-### 📝 Usage Specifications (Important)
-
-#### 1. Standard Destructuring Method
-
-✅ **Correct**:
-```typescript
-const { login, loginUserInfo } = useLoginState();
-await login({ sdkAppId, userId, userSig });
-```
-
-❌ **Wrong**:
-```typescript
-const loginState = useLoginState();
-await loginState.login({ sdkAppId, userId, userSig });
-```
-
-#### 2. Reactive Data Access
-
-✅ **Correct**:
-```typescript
-const { loginUserInfo } = useLoginState();
-
-// Access in setup
-if (loginUserInfo.value) {
-  console.log(loginUserInfo.value.userID);
-}
-
-// Access in template (auto unwrap)
-<template>
-  <div v-if="loginUserInfo">
-    {{ loginUserInfo.userID }}
-  </div>
-</template>
-```
-
-❌ **Wrong**:
-```typescript
-// Forget to use .value
-if (loginUserInfo) {  // ❌ loginUserInfo is a Ref object, not a boolean
-  console.log(loginUserInfo.userID);  // ❌ Cannot access
-}
-```
-
-#### 3. State Monitoring
-
-```typescript
-import { watch } from 'vue';
-const { loginUserInfo } = useLoginState();
-
-// Monitor login state changes
-watch(loginUserInfo, (newInfo, oldInfo) => {
-  if (newInfo) {
-    console.log('User logged in:', newInfo.userID);
-  } else {
-    console.log('User logged out');
-  }
-});
-```
-
----
-
-### 🔗 Reference Resources
-
-- **Official API Documentation**: https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html
-- **Detailed Code Examples**: Refer to specific feature documentation of each feature module
-
----
-
-## 🏗️ General Integration Steps
-
-#### Step 1: Install Dependencies
-
-**Core Dependencies**:
-
-```json
-{
-  "tuikit-atomicx-vue3": "latest",                        // TUIRoomKit atomic component library (contains all Hooks and UI components, will automatically install tuiroom-engine-js)
-  "@tencentcloud/uikit-base-component-vue3": "latest",    // Basic UI component library (common components like buttons, input boxes)
-  "vue-router": "^4.0.0"                                   // Vue router (for page navigation, install when router functionality is needed)
-}
-```
-
-**Dependency Description**:
-- **tuikit-atomicx-vue3**: Core package, contains all atomic Hooks and UI components, will automatically install `@tencentcloud/tuiroom-engine-js`
-- **@tencentcloud/uikit-base-component-vue3**: Basic UI component library (install when using TUIKit UI components)
-- **vue-router**: Vue router library (install when implementing page navigation)
-
-**Installation Commands**:
-
-```bash
-# Minimal installation (core package only)
-npm install tuikit-atomicx-vue3
-
-# Full installation (including UI component library and router)
-npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
-
-# Or use pnpm
-pnpm install tuikit-atomicx-vue3
-pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 vue-router
-```
-
-**Build Environment Patch (Vite Projects)**:
-
-If Vite project is detected, Agent must automatically add patch configuration to `package.json` for esbuild-wasm compatibility:
-
-```json
-{
-  "overrides": { 
-    "esbuild": "npm:esbuild-wasm@latest"   // npm uses this field to override dependency versions
-  },
-  "resolutions": { 
-    "esbuild": "npm:esbuild-wasm@latest"   // yarn/pnpm uses this field to override dependency versions
-  }
-}
-```
-
-**Patch Description**:
-- **Why Needed**: In some environments, esbuild native binaries may not run properly, using esbuild-wasm (WebAssembly version) can provide better cross-platform compatibility
-- **Applicable Scenarios**: Mainly for projects using Vite build tool
-- **Function**: Force replace all esbuild versions in project dependencies with esbuild-wasm version
-
-#### Step 2: Login Authentication (Prerequisites)
-
-Login must be completed before using all feature modules. Please refer to examples in specific feature documentation for detailed code.
-
-#### Step 3: Import and Use Feature Hooks
-
-All Hooks are imported from `tuikit-atomicx-vue3`. Please refer to feature documentation for specific API calling methods.
-
----
-
-## 🎨 Code Generation Specifications
-
-### 1. Vue 3 Composition API
-
-- Use `<script setup lang="ts">` syntax
-- Use Vue 3 Composition API (ref, reactive, computed, onMounted, etc.)
-- Import required Hooks from `tuikit-atomicx-vue3`
-
-### 2. TypeScript Type Safety
-
-- Use official type definitions (import from `@tencentcloud/tuiroom-engine-js`)
-- Add correct type annotations for state variables
-
-### 3. Error Handling
-
-- All asynchronous operations must use try-catch for error handling
-- Provide friendly error prompts
-
-### 4. Microphone Switch Best Practices (Important)
-
-#### Core Principle
-
-**Physically open microphone only once when entering room, use mute/unmute for switching during meeting**.
-
-#### Implementation Method
-
-| Scenario | API Call | Description |
-|------|---------|------|
-| **Open Microphone When Entering Room** | `await openLocalMicrophone()`<br>`await unmuteLocalAudio()` | Physically open microphone device and unmute |
-| **Close Microphone During Meeting** | `await muteLocalAudio()` | Only mute, do not close physical device |
-| **Open Microphone During Meeting** | `await unmuteLocalAudio()` | Only unmute, do not reopen physical device |
-
-#### Code Example
-
-```typescript
-import { useDeviceState } from 'tuikit-atomicx-vue3';
-
-const { openLocalMicrophone, muteLocalAudio, unmuteLocalAudio } = useDeviceState();
-
-// ✅ Correct: Initialize microphone when entering room
-async function enterRoomWithMicrophone() {
-  try {
-    // 1. Join room
-    await joinRoom('room123');
-    
-    // 2. Physically open microphone (only once)
-    await openLocalMicrophone();
-    
-    // 3. Unmute
-    await unmuteLocalAudio();
-  } catch (error) {
-    console.error('Microphone initialization failed:', error);
-  }
-}
-
-// ✅ Correct: Close microphone during meeting (mute)
-async function closeMicInRoom() {
-  try {
-    await muteLocalAudio();  // Only mute, do not close physical device
-  } catch (error) {
-    console.error('Mute failed:', error);
-  }
-}
-
-// ✅ Correct: Open microphone during meeting (unmute)
-async function openMicInRoom() {
-  try {
-    await unmuteLocalAudio();  // Only unmute, do not reopen physical device
-  } catch (error) {
-    console.error('Unmute failed:', error);
-  }
-}
-
-// ❌ Wrong: Repeatedly call openLocalMicrophone during meeting
-async function wrongWayToOpenMic() {
-  // Do not call during meeting, will cause delay and audio loss
-  await openLocalMicrophone();  // ❌ Wrong!
-  await unmuteLocalAudio();
-}
-```
-
-#### Technical Reasons
-
-1. **Performance Optimization**: Physically opening microphone device requires hardware initialization, takes a long time (typically 100-300ms)
-2. **Avoid Audio Loss**: Frequently opening/closing physical devices may cause loss of first audio packets, resulting in audio loss
-3. **User Experience**: Mute/unmute operations respond instantly without delay
-
-#### Mandatory Constraints
-
-- ✅ **Must** call `openLocalMicrophone()` to initialize microphone when entering room
-- ✅ **Must** use `muteLocalAudio()` / `unmuteLocalAudio()` for microphone switching during meeting
-- ❌ **Prohibited** to repeatedly call `openLocalMicrophone()` during meeting
-- ❌ **Prohibited** to use `closeLocalMicrophone()` then `openLocalMicrophone()` method
-
-### 5. Video Stream Rendering Best Practices (Recommended)
-
-#### Core Principle
-
-**When developing with State API, recommend using `RoomParticipantView` component to render video streams**.
-
-#### Platform Applicability
-
-| Component | Applicable Platforms | Description |
-|------|---------|------|
-| **RoomParticipantView** | ✅ H5 Mobile<br>✅ PC Web | **Priority recommendation for H5 development**, lightweight, suitable for mobile and desktop |
-| **RoomView** | ✅ PC Web | Only for PC, includes complete meeting room layout |
-
-**Mandatory Constraints**:
-- ✅ **H5 Mobile Development**: Must use `RoomParticipantView` component
-- ✅ **PC Web Development**: Priority recommendation for `RoomParticipantView` component, more flexible
-- ⚠️ **RoomView** only for PC and scenarios requiring complete meeting room layout
-
-#### Recommended Import Method
-
-```typescript
-import { RoomParticipantView } from 'tuikit-atomicx-vue3/room';
-```
-
-#### Usage Examples
-
-##### Basic Usage: Directly Render Participant Video
-
-```vue
-<template>
-  <div class="video-container">
-    <!-- Render local video stream -->
-    <RoomParticipantView
-      v-if="localParticipant"
-      :participant="localParticipant"
-      :stream-type="VideoStreamType.Camera"
-    />
-    
-    <!-- Render remote video stream -->
-    <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>
-```
-
-##### Advanced Usage: Distinguish Local Screen Share and Camera Stream
-
-```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();
-
-// Check if it's local screen share stream
-const isLocalScreen = computed(() => 
-  props.participant.userId === localParticipant.value?.userId && 
-  props.streamType === VideoStreamType.Screen
-);
-</script>
-```
-
-#### Advantages
-
-1. **Automatic Video Stream Management**: Component internally handles video stream subscription, rendering, and destruction
-2. **State Synchronization**: Automatically syncs user audio/video states (mute, camera off, etc.)
-3. **Simplified Development**: No need to manually operate DOM or manage video elements
-4. **Best Practices**: Encapsulates best practices and optimizations for TRTC video rendering
-
-#### Mandatory Constraints
-
-- ✅ **Recommended** to use `RoomParticipantView` component to render video streams
-- ✅ **Must** import from `tuikit-atomicx-vue3/room`
-- ⚠️ For custom rendering logic, please refer to advanced usage in feature documentation
-
-**For detailed code examples, please refer to specific feature documentation.**
-
----
-
-## 🔗 Tool Reference
-
-### `get_usersig` - Generate User Signature (Required for Login)
-
-**Purpose**: Agent calls this MCP tool to obtain login credentials (SDKAppID, userID, userSig) for user code login calls.
-
-**Mandatory Constraints**:
-- ✅ Agent must call this tool to obtain login credentials
-- ❌ Prohibited to manually write UserSig generation code
-- ⚠️ Must inform users: UserSig should be generated on server side in production environment
-
----
-
-### `record_result` - Record Integration Results
-
-**Purpose**: Record feature integration process and results for statistical analysis
-
-**Call Timing**: Call after completing feature integration and verification
-
----
-
-## 📝 Key Points Summary
-
-| Category | Requirement |
-|------|------|
-| **Applicable Scenarios** | Implement meeting UI using RoomKit atomic APIs |
-| **Platform Support** | ✅ RoomKit State API fully supports H5 mobile and PC Web |
-| **Login Authentication** | ✅ Must use `get_usersig` tool + `useLoginState` Hook |
-| **API Calls** | ✅ Must use official Hooks (useRoomState, useDeviceState, etc.) |
-| **Documentation Priority** | Strictly follow feature documentation content returned this time |
-| **Error Handling** | All asynchronous operations must use try-catch for error handling |
-| **Security Tips** | ⚠️ Must inform users: UserSig should be generated on server side in production environment |
-| **Supported Frameworks** | Vue 3.4.21+ (using Composition API) |
-
----
-
-**Applicable Framework**: Vue 3.4.21+  
-**Integration Mode**: Feature Custom UI (Atomic API)  
-**Platform Support**: H5 Mobile + PC Web