@tencentcloud/sdk-mcp 1.3.7 → 1.3.9

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

@@ -2,7 +2,7 @@
 
 ## 📋 指令目的
 
-为 Agent 提供实现 Vue TUIRoomKit (Atomicx 版本) **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**，专门针对 PC 端 Vue3 音视频会议应用场景。
+为 Agent 提供实现 Vue TUIRoomKit (Atomicx 版本) **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**，支持 PC 端和 H5 移动端 Vue3 音视频会议应用场景。
 
 ---
 
@@ -15,10 +15,10 @@ Agent 在生成代码时必须严格遵守以下指令：
 - **必须严格按照集成文档中的示例代码生成代码**，不得擅自修改代码结构和实现方式
 - 代码生成时应完全遵循集成文档提供的最佳实践和示例，确保代码的正确性和可运行性
 
-### 2. 源码接入方式
-- TUIRoomKit (Atomicx 版本) 采用 **源码接入方式**，需要从 GitHub 克隆并拷贝核心源码文件
-- 必须按照文档指引，将指定的源码文件夹（assets、components、hooks、i18n、utils、config、views）拷贝到用户项目中
-- 拷贝时必须确保与用户项目已有的文件夹进行合并，避免直接覆盖
+### 2. npm 包接入方式（推荐）
+- TUIRoomKit (Atomicx 版本) 采用 **npm 包直接安装方式**，无需克隆 GitHub 仓库
+- 通过 npm/pnpm/yarn 安装依赖包即可快速集成
+- 如需深度定制 UI，可使用源码导出功能
 
 ### 3. 静默执行集成
 - 所有代码编写完成后，在最后一步自动安装依赖并启动项目
@@ -26,24 +26,34 @@ Agent 在生成代码时必须严格遵守以下指令：
 
 ### 4. 零外部配置（测试阶段）
 - 禁止自动创建任何 `.env` 文件用于生产环境配置
-- SDKAppID 和 SDKSecretKey 等关键凭证必须从 MCP 环境变量中读取，并直接配置在 `src/config/basic-info-config.js` 中
+- SDKAppID 和 UserSig 等关键凭证必须从 MCP 工具获取或让用户手动配置
 
 ### 5. 鉴权凭据配置
-- 从 MCP 环境变量中读取 `SDKAppID` 和 `SDKSecretKey`，禁止要求用户手动输入
-- UserID 生成应保持简洁（可使用随机数生成，如 `user_${Math.ceil(Math.random()*999)}`）
+- 使用 `get_usersig` MCP 工具获取 `SDKAppID`、`userId` 和 `userSig`
 - **⚠️ 重要安全提示**：必须告知用户，客户端生成 UserSig 仅适合本地测试，正式生产环境必须在服务端生成 UserSig
 
 ### 6. Vue 3 组合式 API
 - 优先使用 `<script setup lang="ts">` 语法（注意启用 TypeScript）
 - 使用 Vue 3 Composition API（ref、reactive、computed、onMounted 等）
-- 正确引入和使用 TUIRoomKit Atomicx 组件
+- 正确引入和使用 TUIRoomKit 组件
 
-### 7. 路由配置
-- 必须配置 Vue Router，将 `home.vue` 映射到主页（路径：`/home`），将 `room.vue` 映射到会议室页面（路径：`/room`）
-- 默认根路径重定向到 `/home`
+### 7. 平台适配
+- 使用 `getPlatform()` 检测当前平台，PC 端使用 `ConferenceMainView`，H5 移动端使用 `ConferenceMainViewH5`
+- 两套组件已分别针对 PC 和 H5 进行 UI 适配，开箱即用
 
-### 8. 环境依赖准备
-- 确保用户项目支持 TypeScript 和 SCSS，如果未安装需自动安装 `typescript` 和 `sass` 开发依赖
+### 8. 会议组件加载前置要求（⚠️ 关键约束）
+- **调用 `conference.start()` 或 `conference.join()` 的页面，必须确保会议主视图组件已在模板中加载**
+- 在调用发起/加入会议 API 前，页面模板中必须包含以下组件结构：
+
+```vue
+<template>
+  <ConferenceMainView v-if="isPC"></ConferenceMainView>
+  <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
+</template>
+```
+
+- 如果缺少会议主视图组件，`conference.start()` 和 `conference.join()` 将无法正常渲染会议界面
+- Agent 生成会议室页面代码时，必须先引入并渲染上述组件，再执行发起/加入会议的逻辑
 
 ---
 
@@ -55,35 +65,34 @@ Agent 生成代码后，必须自动执行以下依赖链：
 
 ```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 路由（用于页面导航）
+  "@tencentcloud/roomkit-web-vue3": "latest",              // TUIRoomKit 主组件包（包含 ConferenceMainView、ConferenceMainViewH5、conference 等）
+  "tuikit-atomicx-vue3": "latest",                         // TUIRoomKit 原子化组件库（包含所有 Hooks 和原子化 UI 组件）
+  "@tencentcloud/uikit-base-component-vue3": "latest",     // 基础 UI 组件库（UIKitProvider 等）
+  "@tencentcloud/universal-api": "latest"                  // 跨平台 API 工具库（getPlatform 等）
 }
 ```
 
 **依赖说明**：
 
-| 依赖包 | 作用 | 是否必需手动安装 | 说明 |
-|-------|------|----------------|------|
-| **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`）的路由导航 |
+| 依赖包 | 作用 | 是否必需 | 说明 |
+|-------|------|---------|------|
+| **@tencentcloud/roomkit-web-vue3** | TUIRoomKit 主组件包 | ✅ 必须 | 提供 `ConferenceMainView`（PC 端）、`ConferenceMainViewH5`（H5 端）和 `conference` 对象（发起/加入会议） |
+| **tuikit-atomicx-vue3** | 原子化组件库 | ✅ 必须 | 提供 `useLoginState`、`useRoomState` 等 Hooks，以及 `RoomLayoutTemplate` 等枚举类型 |
+| **@tencentcloud/uikit-base-component-vue3** | 基础 UI 组件库 | ✅ 必须 | 提供 `UIKitProvider` 组件，用于配置全局主题和语言 |
+| **@tencentcloud/universal-api** | 跨平台 API 工具库 | ✅ 必须 | 提供 `getPlatform()` 方法，用于检测当前运行平台（pc/mobile） |
 
-**依赖关系**：
-```
-用户项目
-  ├── 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`，可能导致版本冲突
+```bash
+# npm
+npm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
+
+# pnpm
+pnpm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
+
+# yarn
+yarn add @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
+```
 
 ### 2. 开发环境依赖（TypeScript 和 SCSS）
 
@@ -91,15 +100,11 @@ Agent 生成代码后，必须自动执行以下依赖链：
 
 ```json
 {
-  "typescript": "latest",  // TypeScript 编译器（用于类型检查和编译）
-  "sass": "latest"         // SCSS 预处理器（用于编译 .scss 样式文件）
+  "typescript": "latest",  // TypeScript 编译器
+  "sass": "latest"         // SCSS 预处理器
 }
 ```
 
-**依赖说明**：
-- **typescript**: TUIRoomKit 源码使用 TypeScript 编写，需要 TypeScript 编译器支持
-- **sass**: TUIRoomKit 样式文件使用 SCSS 编写，需要 sass 预处理器进行编译
-
 ### 3. 构建环境补丁 (Vite/esbuild)
 
 若检测到 Vite 项目，Agent 必须在 `package.json` 自动增加补丁配置以兼容 esbuild-wasm：
@@ -107,196 +112,370 @@ Agent 生成代码后，必须自动执行以下依赖链：
 ```json
 {
   "overrides": { 
-    "esbuild": "npm:esbuild-wasm@latest"   // npm 使用此字段覆盖依赖版本
+    "esbuild": "npm:esbuild-wasm@latest"
   },
   "resolutions": { 
-    "esbuild": "npm:esbuild-wasm@latest"   // yarn/pnpm 使用此字段覆盖依赖版本
+    "esbuild": "npm:esbuild-wasm@latest"
   }
 }
 ```
 
-**补丁说明**：
-- **为什么需要**：部分环境下 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
+## 🎯 TUIRoomKit (Atomicx 版本) 核心组件说明
 
-# 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
-```
+| 组件名称 | 说明 | 使用场景 |
+|---------|------|---------|
+| `ConferenceMainView` | PC 端会议主界面组件 | 桌面端多人会议 |
+| `ConferenceMainViewH5` | H5 移动端会议主界面组件 | 移动端多人会议 |
+| `conference` | 会议控制对象 | 发起会议（start）和加入会议（join） |
+| `UIKitProvider` | 全局 UI 配置组件 | 配置主题和语言 |
 
----
+### 核心 Hooks
 
-## 🏗️ 源码文件拷贝结构
+| Hook 名称 | 来源 | 说明 |
+|---------|------|------|
+| `useLoginState` | `tuikit-atomicx-vue3/room` | 提供 `login`、`setSelfInfo` 等登录方法 |
+| `useRoomState` | `tuikit-atomicx-vue3/room` | 提供房间状态管理 |
+| `useDeviceState` | `tuikit-atomicx-vue3/room` | 提供设备状态管理 |
+| `useRoomEngine` | `tuikit-atomicx-vue3/room` | 获取 roomEngine 实例 |
 
-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 的核心会议界面，集成了完整的头部、视频布局、控制栏和侧边面板 |
+```typescript
+import { getPlatform } from '@tencentcloud/universal-api';
 
-> **重要提示**：拷贝源码文件时，请确保与用户项目已有的文件夹进行**合并**，避免直接覆盖已有的同名文件夹。
+const isPC = getPlatform() === 'pc';
+// isPC === true  → 使用 ConferenceMainView
+// isPC === false → 使用 ConferenceMainViewH5
+```
 
 ---
 
-## 🎯 TUIRoomKit (Atomicx 版本) 核心组件说明
+## 👥 默认测试用户说明
 
-Agent 在生成代码时，必须了解 TUIRoomKit Atomicx 的核心架构：
+为方便开发调试，Agent 生成的代码**默认提供 3 个测试用户**：
 
-### 原子化组件设计理念
+| 用户 ID | 用户名称 | 说明 |
+|---------|---------|------|
+| `user001` | 用户 001 | 测试用户 1（可作为主持人） |
+| `user002` | 用户 002 | 测试用户 2（可作为参会者） |
+| `user003` | 用户 003 | 测试用户 3（可作为参会者） |
 
-TUIRoomKit (Atomicx 版本) 采用原子化组件设计，开发者可以灵活组合这些组件构建个性化的会议界面。
+### 应用登录流程
 
-### 核心页面组件
+Agent 生成的完整应用包含以下页面和流程：
 
-| 组件名称 | 说明 | 使用场景 |
-|---------|------|---------|
-| `home.vue` | 会议入口页面 | 包含设备检测、房间创建/加入功能 |
-| `room.vue` | 会议室核心页面 | 集成完整的头部、视频布局、控制栏和侧边面板 |
+```mermaid
+graph LR
+    A[首页 - 用户选择登录] --> B{选择用户}
+    B --> C[user001 登录]
+    B --> D[user002 登录]
+    B --> E[user003 登录]
+    C --> F[会议入口页面]
+    D --> F
+    E --> F
+    F --> G[创建会议]
+    F --> H[加入会议]
+    G --> I[进入会议室]
+    H --> I
+```
 
-### 核心 Hooks
+### 首页功能要求
 
-| Hook 名称 | 说明 | 主要用途 |
-|---------|------|---------|
-| `useLoginState` | 登录状态管理 | 提供 login、setSelfInfo 等方法 |
-| `useRoomModal` | 房间弹窗管理 | 提供 handleErrorWithModal 错误处理方法 |
-| `useRoomEngine` | 房间引擎管理 | 获取 roomEngine 实例 |
+Agent 生成的首页（Home 页面）必须包含以下功能：
 
-### 核心 UI 组件（来自 tuikit-atomicx-vue3）
+1. **用户选择界面**：
+   - 提供下拉框或按钮组，让用户选择要登录的测试用户（user001/user002/user003）
+   - 显示当前选中用户的 ID 和名称
 
-- **RoomLayoutView**: 视频流布局组件（支持九宫格、侧边栏、顶部栏三种布局）
-- **ParticipantViewUI**: 视频流挂件组件（可自定义）
-- **UIKitProvider**: 全局 UI 配置组件（主题、语言）
+2. **登录按钮**：
+   - 点击登录按钮后，调用 `login()` 和 `setSelfInfo()` 完成用户登录
+   - 登录过程中显示加载状态
 
----
+3. **登录成功后跳转**：
+   - 登录成功后自动跳转到会议入口页面
+   - 会议入口页面提供「创建会议」和「加入会议」两个入口
 
-## 🛠️ 集成步骤详解
+### 会议入口页面功能要求
 
-Agent 必须按照以下步骤执行集成：
+登录成功后的会议入口页面必须包含：
 
-### 步骤 1：克隆 GitHub 仓库并拷贝源码
+1. **显示当前登录用户信息**：展示已登录的用户 ID 和名称
+2. **创建会议功能**：
+   - 输入会议 ID（可选，不输入则自动生成）
+   - 输入会议名称（可选）
+   - 点击「创建会议」按钮调用 `conference.start()`
+3. **加入会议功能**：
+   - 输入要加入的会议 ID（必填）
+   - 点击「加入会议」按钮调用 `conference.join()`
 
-```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 在生成代码时，需要为每个测试用户调用 `get_usersig` MCP 工具获取对应的 userSig，并**预先填入**代码中：
 
-# 拷贝核心源码文件到用户项目
-# (注意：需要与用户项目已有文件夹合并，而非直接覆盖)
+```typescript
+// ⚠️ Agent 生成代码时，需要调用 get_usersig 工具 3 次，分别为 user001、user002、user003 获取 userSig
+// 然后将获取到的 SDKAppID 和每个用户的 userSig 填入下方配置
+
+const SDKAppID = 0; // Agent 填入从 get_usersig 获取的 SDKAppID
+
+// 测试用户列表（包含预生成的 userSig）
+const TEST_USERS = [
+  { userId: 'user001', userName: '用户 001', userSig: '' }, // Agent 填入 user001 的 userSig
+  { userId: 'user002', userName: '用户 002', userSig: '' }, // Agent 填入 user002 的 userSig
+  { userId: 'user003', userName: '用户 003', userSig: '' }, // Agent 填入 user003 的 userSig
+];
 ```
 
-**Agent 执行注意事项**：
-- 如果用户项目中已存在同名文件夹，必须进行智能合并
-- 不得覆盖用户已有的业务代码
+#### 首页用户选择组件示例
+
+```vue
+<template>
+  <div class="login-container">
+    <h1>TUIRoomKit 音视频会议</h1>
+    <div class="user-select">
+      <label>选择测试用户：</label>
+      <select v-model="selectedUserId">
+        <option v-for="user in TEST_USERS" :key="user.userId" :value="user.userId">
+          {{ user.userName }} ({{ user.userId }})
+        </option>
+      </select>
+    </div>
+    <button @click="handleLogin" :disabled="isLogging">
+      {{ isLogging ? '登录中...' : '登录' }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { useLoginState } from 'tuikit-atomicx-vue3/room';
+
+// ⚠️ 以下凭证由 Agent 在代码生成时调用 get_usersig 工具获取并填入
+const SDKAppID = 0; // Agent 填入实际的 SDKAppID
+
+const TEST_USERS = [
+  { userId: 'user001', userName: '用户 001', userSig: '' }, // Agent 填入 user001 的 userSig
+  { userId: 'user002', userName: '用户 002', userSig: '' }, // Agent 填入 user002 的 userSig
+  { userId: 'user003', userName: '用户 003', userSig: '' }, // Agent 填入 user003 的 userSig
+];
+
+const router = useRouter();
+const { login, setSelfInfo } = useLoginState();
+
+const selectedUserId = ref('user001');
+const isLogging = ref(false);
+
+const handleLogin = async () => {
+  const user = TEST_USERS.find(u => u.userId === selectedUserId.value);
+  if (!user) return;
+
+  isLogging.value = true;
+  try {
+    await login({
+      userId: user.userId,
+      userSig: user.userSig, // 使用预填入的 userSig
+      sdkAppId: SDKAppID,
+    });
+    await setSelfInfo({
+      userName: user.userName,
+      avatarUrl: '',
+    });
+    // 登录成功，跳转到会议入口页面
+    router.push('/conference-entry');
+  } catch (error) {
+    console.error('登录失败:', error);
+  } finally {
+    isLogging.value = false;
+  }
+};
+</script>
+```
 
 ---
 
-### 步骤 2：安装项目依赖
+## 🛠️ 集成步骤详解
+
+### 步骤 1：安装项目依赖
 
 ```bash
-# 安装核心依赖
-npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
+# npm
+npm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
+
+# pnpm
+pnpm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 
-# 安装开发环境依赖（如果用户项目尚未支持 TypeScript 和 SCSS）
-npm install typescript sass -S -D
+# yarn
+yarn add @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
 ---
 
-### 步骤 3：配置页面路由
-
-在用户项目中配置或更新 `src/router/index.ts` 文件。
-
-**关键配置要点**：
-- 配置 `/home` 路由：映射到 `home.vue` 页面（会议入口）
-- 配置 `/room` 路由：映射到 `room.vue` 页面（会议室）
-- 默认根路径 `/` 重定向到 `/home`
+### 步骤 2：创建会议页面组件（⚠️ 关键步骤）
+
+创建会议页面组件，**必须在模板中先加载会议主视图组件**，然后再调用 `conference.start()` 或 `conference.join()`：
+
+```vue
+<template>
+  <!-- ⚠️ 关键：必须先在模板中加载会议主视图组件 -->
+  <ConferenceMainView v-if="isPC"></ConferenceMainView>
+  <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { useRoute } from 'vue-router';
+import { ConferenceMainView, ConferenceMainViewH5, conference } from '@tencentcloud/roomkit-web-vue3';
+import { getPlatform } from '@tencentcloud/universal-api';
+
+const route = useRoute();
+const isPC = ref(getPlatform() === 'pc');
+
+// 从路由参数获取会议信息
+const roomId = route.query.roomId as string;
+const roomName = route.query.roomName as string;
+const action = route.query.action as 'start' | 'join'; // 'start' 或 'join'
+
+onMounted(async () => {
+  // ⚠️ 确保组件已挂载（模板已渲染）后再调用 conference API
+  if (action === 'start') {
+    // 发起新会议
+    await conference.start({
+      roomId: roomId,
+      options: {
+        roomName: roomName || '我的会议',
+      },
+    });
+  } else if (action === 'join') {
+    // 加入已有会议
+    await conference.join({
+      roomId: roomId,
+    });
+  }
+});
+</script>
+```
 
-**Agent 执行要求**：
-- ⚠️ 必须严格按照集成文档中的路由配置示例生成
-- 如果用户项目中已有 `src/router/index.ts` 文件，需要将路由配置**合并**到已有代码中
-- 如果尚未配置路由，需要新建 `src/router/index.ts` 文件
+**⚠️ 强制约束说明**：
+- `conference.start()` 和 `conference.join()` **必须在会议主视图组件加载后调用**
+- 模板中必须包含 `<ConferenceMainView>` 和 `<ConferenceMainViewH5>` 组件
+- 建议在 `onMounted` 生命周期中调用，确保组件已挂载完成
+- 如果模板中缺少会议主视图组件，调用 API 后会议界面将无法正常渲染
 
 ---
 
-### 步骤 4：配置 App.vue 文件
+### 步骤 3：配置 App.vue 文件
 
-将集成文档中提供的配置内容合并到用户项目中的 `App.vue` 文件。
+将以下内容合并到项目的 `App.vue` 文件中：
 
 **关键配置要点**：
 - 配置全局 `UIKitProvider` 组件（设置主题和语言）
-- 引入页面路由 `<router-view />`
-- 在 `onMounted` 钩子中执行用户登录逻辑（`login` 和 `setSelfInfo`）
 - 配置全局样式，确保会议界面全屏显示
+- **注意**：用户登录逻辑在首页组件中实现（见「默认测试用户说明」章节）
+
+```vue
+<template>
+  <!-- Step 1: 配置全局 UIKitProvider -->
+  <UIKitProvider theme="light" language="zh-CN">
+    <!-- 您的业务组件（首页 → 会议入口 → 会议室） -->
+    <router-view />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+</script>
+
+<!-- Step 2: 配置全局样式 -->
+<style>
+html, body {
+  padding: 0 !important;
+  margin: 0 !important;
+}
+
+#app {
+  width: 100% !important;
+  height: 100% !important;
+  padding: 0 !important;
+  margin: 0 !important;
+  max-width: 100% !important;
+  max-height: 100% !important;
+  text-align: left !important;
+  overflow: hidden;
+}
+</style>
+```
 
 **Agent 执行要求**：
-- ⚠️ 必须严格按照集成文档中的 `App.vue` 示例代码生成，不得擅自修改
-- 如果用户项目已有 `App.vue` 文件，需要智能合并而非直接覆盖
+- ⚠️ 用户登录逻辑在首页组件中实现，而非 App.vue
+- 必须调用 `get_usersig` MCP 工具为每个测试用户获取 SDKAppID、userId、userSig
 
 ---
 
-### 步骤 5：配置 src/main.ts 文件
+### 步骤 4：发起新会议（完整示例）
 
-将集成文档中提供的路由和多语言配置合并到用户项目中的入口文件 `src/main.ts` 中。
+从会议入口页面跳转到会议室页面并发起会议：
 
-**关键配置要点**：
-- 引入并注册 Vue Router
-- 配置多语言资源（中文和英文）
-- 挂载 Vue 应用
+```typescript
+// 会议入口页面中的发起会议逻辑
+import { useRouter } from 'vue-router';
+
+const router = useRouter();
+
+const startConference = () => {
+  // 跳转到会议室页面，传递会议参数
+  router.push({
+    path: '/room',
+    query: {
+      action: 'start',
+      roomId: '123456',      // 会议 ID
+      roomName: '我的临时会议', // 会议名称
+    },
+  });
+};
+```
 
-**Agent 执行要求**：
-- ⚠️ 必须严格按照集成文档中的 `main.ts` 示例代码生成，不得擅自修改
-- 如果用户项目中的入口文件为 `main.js`，需要修改文件后缀为 `main.ts`
-- 如果用户项目已有路由配置，需要智能合并而非直接覆盖
+**⚠️ 注意**：实际的 `conference.start()` 调用在会议室页面组件（步骤 2）的 `onMounted` 中执行，确保会议主视图组件已加载。
 
 ---
 
-### 步骤 6：配置应用信息（src/config/basic-info-config.js）
-
-在用户项目目录中找到 `src/config/basic-info-config.js` 配置文件，并进行以下配置：
+### 步骤 5：加入已有会议（完整示例）
 
-**配置方式**：
-- Agent 必须从 MCP 环境变量中读取 `SDKAppID` 和 `SDKSecretKey`
-- 这些凭证配置在 MCP 环境中，无需通过 `get_usersig` 工具获取
-- 直接将环境变量中的值写入 `basic-info-config.js` 文件
+从会议入口页面跳转到会议室页面并加入会议：
 
-**⚠️ 安全警告**：
-- 本文的 Demo 示例中通过在客户端代码中配置 `SDKSecretKey` 进行鉴权，但 `SDKSecretKey` 很容易被反编译逆向破解，一旦密钥泄露，攻击者就可以盗用您的腾讯云流量
-- **该方法仅适合本地跑通 Demo 和功能调试**
-- **在正式的生产环境中**，建议在您的服务端生成 UserSig，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权
+```typescript
+// 会议入口页面中的加入会议逻辑
+import { useRouter } from 'vue-router';
+
+const router = useRouter();
+
+const joinConference = () => {
+  // 跳转到会议室页面，传递会议参数
+  router.push({
+    path: '/room',
+    query: {
+      action: 'join',
+      roomId: '123456', // 要加入的会议 ID
+    },
+  });
+};
+```
 
-**Agent 必须告知用户**：
-> "⚠️ 当前生成的代码仅适用于本地测试。在正式生产环境中，您必须在服务端生成 UserSig，详见腾讯云文档：https://cloud.tencent.com/document/product/647/17275#formal"
+**⚠️ 注意**：实际的 `conference.join()` 调用在会议室页面组件（步骤 2）的 `onMounted` 中执行，确保会议主视图组件已加载。
 
 ---
 
 ## 🎨 UI 自定义功能
 
-TUIRoomKit (Atomicx 版本) 支持灵活的 UI 自定义，Agent 可根据用户需求提供以下自定义方案：
-
 ### 1. 主题及语言配置
 
-通过配置 `App.vue` 中 `UIKitProvider` 的入参，修改主题及语言的默认值：
+通过配置 `UIKitProvider` 的入参修改主题及语言：
 
 | UIKitProvider 参数 | 可选值 | 默认值 |
 |-------------------|--------|--------|
@@ -311,17 +490,43 @@ TUIRoomKit (Atomicx 版本) 支持灵活的 UI 自定义，Agent 可根据用户
 
 ---
 
-### 2. 房间流布局自定义
+### 2. 源码导出（深度定制）
+
+如需深度定制 TUIRoomKit 界面，可使用源码导出功能：
+
+```bash
+# 执行源码导出脚本，默认拷贝路径为 ./src/components/RoomKit
+node ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js
+```
+
+导出后修改组件引用路径：
+
+```typescript
+// 修改前：从 npm 包引入
+- import { ConferenceMainView, conference } from '@tencentcloud/roomkit-web-vue3';
+
+// 修改后：从本地源码引入
++ import { ConferenceMainView, ConferenceMainViewH5, conference } from './components/RoomKit/index.ts';
+```
+
+---
+
+### 3. 自定义房间流布局
 
-TUIRoomKit 目前支持三种流布局：
-- **九宫格布局**（默认）：`RoomLayoutTemplate.GridLayout`
-- **侧边栏布局**：`RoomLayoutTemplate.SidebarLayout`
-- **顶部栏布局**：`RoomLayoutTemplate.CinemaLayout`
+TUIRoomKit 支持三种流布局：
 
-在 `src/views/room.vue` 中修改默认布局：
+| 布局类型 | 枚举值 | 说明 |
+|---------|--------|------|
+| 九宫格布局 | `RoomLayoutTemplate.GridLayout` | 默认布局 |
+| 侧边栏布局 | `RoomLayoutTemplate.SidebarLayout` | 侧边栏布局 |
+| 顶部栏布局 | `RoomLayoutTemplate.CinemaLayout` | 顶部栏布局 |
+
+导出源码后，在 `RoomKit/views/ConferenceMainView/index.vue` 中修改：
 
 ```typescript
-// 修改默认视频流布局为侧边栏布局
+import { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';
+
+// 修改默认布局为侧边栏布局
 const participantViewLayout = ref(RoomLayoutTemplate.SidebarLayout);
 
 function handleLayoutUpdate(layout: RoomLayoutTemplate) {
@@ -331,23 +536,22 @@ function handleLayoutUpdate(layout: RoomLayoutTemplate) {
 
 ---
 
-### 3. 自定义视频流挂件
+### 4. 自定义视频流挂件
 
-如需自定义视频流挂件（如用户名显示、音视频状态图标等），可修改以下组件：
+导出源码后，修改以下组件自定义视频流挂件：
 
 ```
-src/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue
+src/components/RoomKit/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue
 ```
 
 ---
 
-### 4. 配置用户联系人列表
+### 5. 配置用户联系人列表
 
-TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表。批量导入用户关系链请参考以下步骤：
+TUIRoomKit 预定会议和会中呼叫的用户选择列表默认展示用户关系链。批量导入步骤：
 
-**步骤 1**：使用 [账号管理 > 导入多个账号](https://cloud.tencent.com/document/product/269/4919) REST API 接口批量导入用户账号
-
-**步骤 2**：使用 [好友管理 > 导入好友](https://cloud.tencent.com/document/product/269/8301) REST API 接口批量导入用户关系链
+1. 使用 [账号管理 > 导入多个账号](https://cloud.tencent.com/document/product/269/4919) REST API 批量导入用户账号
+2. 使用 [好友管理 > 导入好友](https://cloud.tencent.com/document/product/269/8301) REST API 批量导入用户关系链
 
 ---
 
@@ -355,41 +559,39 @@ TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认
 
 ```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[使用默认配置]
+    A[接收用户需求] --> B[安装 npm 依赖包]
+    B --> C{检测 TypeScript 和 SCSS 支持}
+    C -->|未安装| D[安装 typescript 和 sass]
+    C -->|已安装| E[跳过]
+    D --> F[创建首页 - 用户选择登录界面]
+    E --> F
+    F --> G[配置 3 个测试用户: user001/user002/user003]
+    G --> H[调用 get_usersig 为每个用户获取凭证]
+    H --> I[创建会议入口页面 - 创建/加入会议]
+    I --> J[创建会议室页面组件]
+    J --> K[配置 App.vue: UIKitProvider + 全局样式]
+    K --> L{用户需要深度定制 UI?}
+    L -->|是| M[执行源码导出脚本]
+    L -->|否| N[使用默认配置]
+    M --> O[提供 UI 自定义方案: 主题/布局/挂件]
     N --> P[record_result 记录集成结果]
     O --> P
     P --> Q[自动启动开发服务器: npm run dev]
-    Q --> R[提示用户在浏览器中访问本地开发服务器地址]
+    Q --> R[提示用户在浏览器中访问并选择用户登录]
 ```
 
 ---
 
 ## ✍️ Agent 代码生成示例指令 (Prompts)
 
-当 Agent 开始编写代码时，应遵循以下语义逻辑：
-
 **基础集成**:
-> "按照 TUIRoomKit (Atomicx 版本) 源码接入方式，为我生成一个 Vue 3 音视频会议应用。请从 GitHub 克隆仓库并拷贝核心源码文件，自动配置路由和多语言，并从 MCP 环境变量中读取 SDKAppID 和 SDKSecretKey 配置到 `basic-info-config.js`。启动后提示我在浏览器中访问调试地址。**请务必告知我：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig。**"
+> "按照 TUIRoomKit (Atomicx 版本) npm 包接入方式，为我生成一个 Vue 3 音视频会议应用。首页提供 3 个测试用户（user001/user002/user003）选择界面，用户选择后点击登录，登录成功后跳转到会议入口页面，提供创建会议和加入会议功能。使用 get_usersig 工具获取每个测试用户的鉴权凭证。启动后提示我在浏览器中访问调试地址。**请务必告知我：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig。**"
 
-**自定义主题和布局**:
-> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个 Vue 3 会议应用。要求使用暗色主题（dark）和英文语言（en-US），默认流布局为侧边栏布局（SidebarLayout）。"
+**H5 移动端会议**:
+> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个同时支持 PC 端和 H5 移动端的 Vue 3 会议应用。首页提供测试用户选择和登录功能，使用 getPlatform() 检测平台，PC 端使用 ConferenceMainView，H5 端使用 ConferenceMainViewH5。"
 
-**自定义视频流挂件**:
-> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个 Vue 3 会议应用。需要自定义视频流挂件，在视频流上显示自定义的用户信息和状态图标。"
+**深度定制 UI**:
+> "按照 TUIRoomKit (Atomicx 版本) 集成，生成一个 Vue 3 会议应用。包含用户选择登录流程，需要执行源码导出，自定义视频流布局为侧边栏布局，并自定义视频流挂件样式。"
 
 ---
 
@@ -397,45 +599,48 @@ graph TD
 
 | 类别 | 要求 |
 |------|------|
-| **框架版本** | 专门针对 PC 端 Vue 3 项目（不支持 Vue 2.x 和 H5） |
-| **接入方式** | 源码接入（从 GitHub 克隆并拷贝核心源码文件） |
+| **框架版本** | Vue 3.4.21 及以上版本 |
+| **平台支持** | PC 端 + H5 移动端（响应式适配，开箱即用） |
+| **接入方式** | npm 包直接安装（推荐）；如需深度定制可使用源码导出 |
 | **文档优先** | 严格遵循工具返回的最新文档指令 |
 | **静默集成** | 代码编写完成后自动安装依赖并启动开发服务器 |
-| **凭证注入** | 从 MCP 环境变量读取凭证，配置在 `basic-info-config.js` 中 |
+| **凭证获取** | 调用 `get_usersig` MCP 工具获取 SDKAppID、userId、userSig |
 | **安全提示** | ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成 |
-| **依赖管理** | 自动安装核心依赖和开发环境依赖（TypeScript、SCSS） |
-| **路由配置** | 配置 `/home` 和 `/room` 两个核心路由 |
 | **多语言** | 支持中文（zh-CN）和英文（en-US） |
-| **UI 自定义** | 支持主题、布局、视频流挂件等自定义 |
+| **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`
+- [ ] 已安装核心依赖：`@tencentcloud/roomkit-web-vue3`、`tuikit-atomicx-vue3`、`@tencentcloud/uikit-base-component-vue3`、`@tencentcloud/universal-api`
 - [ ] 已检测并安装 TypeScript 和 SCSS 开发依赖（如果用户项目未安装）
 
 ### 代码生成
-- [ ] 已配置 Vue Router：`/home` 和 `/room` 路由
-- [ ] 已配置 `App.vue`：UIKitProvider + 用户登录逻辑
-- [ ] 已配置 `main.ts`：路由 + 多语言资源
+- [ ] 已创建会议页面组件，使用 `getPlatform()` 检测平台
+- [ ] 已配置 `App.vue`：UIKitProvider + 全局样式
 - [ ] 组件使用了 `<script setup lang="ts">` 语法
 
+### 测试用户与登录流程
+- [ ] 🔴 已配置 3 个默认测试用户：user001、user002、user003
+- [ ] 已创建首页用户选择界面（下拉框或按钮组选择测试用户）
+- [ ] 已实现登录按钮和登录加载状态
+- [ ] 登录成功后跳转到会议入口页面
+
+### 会议入口页面
+- [ ] 已显示当前登录用户信息
+- [ ] 已实现「创建会议」功能（调用 `conference.start()`）
+- [ ] 已实现「加入会议」功能（调用 `conference.join()`）
+
 ### 凭证与登录
-- [ ] 🔴 已从 MCP 环境变量中读取 SDKAppID 和 SDKSecretKey
-- [ ] 已将 SDKAppID、SDKSecretKey 配置在 `src/config/basic-info-config.js` 中
-- [ ] 已在 `App.vue` 中实现 login() 和 setSelfInfo() 登录逻辑
+- [ ] 🔴 已调用 `get_usersig` MCP 工具为每个测试用户获取 SDKAppID、userId、userSig
+- [ ] 已在首页实现 `login()` 和 `setSelfInfo()` 登录逻辑
 - [ ] ⚠️ **已告知用户**：当前生成的代码仅适用于本地测试，正式生产环境必须在服务端生成 UserSig
 
 ### UI 配置
 - [ ] 已根据用户需求配置主题（light/dark）和语言（zh-CN/en-US）
-- [ ] 已根据用户需求配置流布局（九宫格/侧边栏/顶部栏）
-- [ ] 如果用户需要自定义视频流挂件，已提供自定义方案
+- [ ] 如果用户需要深度定制，已执行源码导出脚本
 
 ### 最终检查
 - [ ] 已调用 `record_result` 记录集成结果
@@ -450,19 +655,14 @@ graph TD
 
 ### 必须使用的工具
 
-#### MCP 环境变量 - 读取鉴权凭证
-**用途**：从 MCP 环境变量中读取腾讯云应用凭证：
+#### `get_usersig` - 获取鉴权凭证
+**用途**：从 MCP 环境变量获取腾讯云应用凭证
 - `SDKAppID`: 应用标识
-- `SDKSecretKey`: 应用密钥
-
-**使用方式**：
-- Agent 直接从 MCP 环境变量中读取凭证
-- 将凭证写入 `src/config/basic-info-config.js` 文件
-- 禁止让用户手动填写或从外部工具获取
+- `userId`: 用户 ID
+- `userSig`: 用户签名
 
 **使用约束**：
-- ✅ 必须从 MCP 环境变量读取
-- ❌ 禁止让用户手动输入
+- ✅ 必须调用此工具获取凭证
 - ⚠️ 必须告知用户：客户端生成 UserSig 仅适合测试，生产环境必须在服务端生成
 
 #### `record_result` - 记录集成结果
@@ -482,6 +682,52 @@ graph TD
 
 ---
 
-**适用框架**: Vue 3 (PC 端)  
-**TUIRoomKit 版本**: tuikit-atomicx-vue3 (Atomicx 版本)  
+## ❓ 常见问题
+
+### TUIRoomKit 在本地开发时正常，但部署到线上后无法采集摄像头/麦克风？
+
+**原因分析**：浏览器出于安全和隐私保护考虑，对音视频设备采集有严格限制。只有在安全环境（https://、localhost、file://）下才允许采集。
+
+**解决方案**：必须使用 HTTPS 协议部署网页，并确保具备有效的安全证书。
+
+### TUIRoomKit 是否支持使用 iframe 集成？
+
+支持。使用 iframe 集成时，需要配置 allow 属性授予必要权限：
+
+```html
+<iframe allow="microphone; camera; display-capture; display; fullscreen;">
+```
+
+### TUIRoomKit 是否支持设置内网代理？
+
+支持。请在进房前设置内网代理参数：
+
+```typescript
+import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js';
+import { useRoomEngine } from 'tuikit-atomicx-vue3/room';
+
+const { roomEngine } = useRoomEngine();
+
+TUIRoomEngine.once('ready', () => {
+  const trtcCloud = roomEngine.instance?.getTRTCCloud();
+  trtcCloud.callExperimentalAPI(JSON.stringify({
+    api: 'setNetworkProxy',
+    params: {
+      websocketProxy: "wss://proxy.example.com/ws/",
+      turnServer: [{
+        url: '14.3.3.3:3478',
+        username: 'turn',
+        credential: 'turn',
+      }],
+      iceTransportPolicy: 'relay',
+    },
+  }));
+});
+```
+
+---
+
+**适用框架**: Vue 3.4.21+  
+**平台支持**: PC 端 + H5 移动端  
+**TUIRoomKit 版本**: @tencentcloud/roomkit-web-vue3 (Atomicx 版本)  
 **构建工具**: Vite (推荐)