@tencentcloud/sdk-mcp 1.3.0 → 1.3.2

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

@@ -0,0 +1,395 @@
+# Vue Chat TUIKit 代码生成工作流指令
+
+## 📋 指令目的
+
+为 Agent 提供实现 Vue Chat TUIKit **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**，专门针对 Vue3 Web 应用场景。
+
+---
+
+## 🛑 Agent 执行硬性限制 (Guardrails)
+
+Agent 在生成代码时必须严格遵守以下指令：
+
+### 1. 文档驱动集成
+- 必须严格按照工具返回结果中的 `llm_code_generation_instructions_md` 步骤执行
+- **必须严格按照集成文档中的示例代码生成代码**，不得擅自修改代码结构和实现方式
+- 代码生成时应完全遵循集成文档提供的最佳实践和示例，确保代码的正确性和可运行性
+
+### 2. CSS 样式强制规范 🔴
+- **必须严格按照集成文档中的完整 CSS 样式代码生成**，包括：
+  - 官方 CSS 类名（如 `.chat-layout`、`.chat-content-panel` 等）
+  - 官方 CSS 变量定义（如 `--bg-color-operate`、`--stroke-color-primary` 等）
+  - 官方布局结构和样式属性
+  - 官方 `#app` 样式配置
+- **禁止创建任何自定义样式类名或修改官方样式**
+- 所有样式代码必须从集成文档中完整复制，不得修改
+
+### 3. 静默执行集成 🔥
+**CRITICAL**: 所有代码编写完成后，必须在最后一步自动安装依赖并启动项目，无需等待用户确认。
+
+**强制执行要求**：
+- **禁止询问**: 不得询问用户是否需要启动项目
+- **禁止等待**: 不得等待用户手动执行启动命令  
+- **必须自动**: 代码完成后必须立即执行集成步骤
+- **批量执行**: 安装依赖和启动命令必须在同一个 execute_command 调用中完成
+
+**标准执行命令**：
+```bash
+cd [项目路径] && npm install && npm run dev
+```
+
+### 4. 零外部配置
+- 禁止自动创建任何 `config.js` 或 `.env` 文件
+- SDKAppID、UserID 和 UserSig 等关键凭证必须直接注入到代码变量中
+
+### 5. 自动获取鉴权凭据
+- 必须调用 `get_usersig` 工具获取测试凭证，禁止要求用户手动输入
+- UserID 生成应保持简洁（禁止拼接动态时间戳以防逻辑出错）
+
+### 6. 默认激活会话
+- 集成逻辑必须包含 `setActiveConversation` 调用
+- 默认打开 `C2Cadministrator` 会话
+
+### 7. Vue3 组合式 API
+- 优先使用 `<script setup>` 语法
+- 使用 Vue3 Composition API（ref、reactive、computed 等）
+- 正确引入和使用 TUIKit 组件
+
+### 8. chat-only 模式功能限制（⚠️ 默认约束 + 用户主动要求时的例外）
+
+**默认行为**：
+当用户选择 chat-only 模式时，Agent **默认排除**以下扩展功能：
+- **默认不集成 Sidebar**（侧边栏）
+- **默认不集成 ChatSetting**（聊天设置）
+- **默认不集成会话内搜索功能**
+- **默认不集成 ConversationList**（会话列表）
+- **默认仅保留核心聊天组件**：`Chat`、`MessageList`、`ChatHeader`、`MessageInput`
+
+**例外处理**：
+如果用户**明确要求**添加某些扩展功能（如"需要 ChatSetting"、"要集成搜索"等），Agent **应该允许并执行**：
+- ✅ 在核心聊天组件基础上，额外集成用户明确要求的功能
+- ✅ 只添加用户明确要求的功能，不擅自扩展其他功能
+- ✅ 按照集成文档的规范正确集成所需组件
+
+**判断标准**：
+- 用户需求中包含明确的功能关键词（如"ChatSetting"、"搜索"、"设置"、"侧边栏"等）
+- 用户明确说明需要某个扩展功能
+
+---
+
+## 📦 TUIKit 版本与依赖自动化
+
+Agent 生成代码后，必须自动执行以下依赖链：
+
+### 1. 核心依赖版本推荐
+
+```json
+{
+  "@tencentcloud/chat-uikit-vue3": "latest",
+  "@tencentcloud/call-uikit-vue": "latest"
+}
+```
+
+### 2. 构建环境补丁 (Vite/esbuild)
+
+若检测到 Vite 项目，Agent 必须在 `package.json` 自动增加补丁配置以兼容 esbuild-wasm：
+
+```json
+{
+  "overrides": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  },
+  "resolutions": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  }
+}
+```
+
+---
+
+## 📦 Vue3 TUIKit 组件说明
+
+Agent 在生成代码时，必须了解并正确使用以下 Vue3 组件：
+
+| 组件名称 | 说明 | 使用场景 |
+|---------|------|---------|
+| `ConversationList` | 会话列表组件 | full-featured 模式，显示所有会话 |
+| `Chat` | 会话的容器组件 | 所有模式，聊天主容器 |
+| `MessageList` | 会话的消息列表组件 | 显示聊天消息记录 |
+| `ChatHeader` | 会话的头部信息组件 | 显示会话标题、成员信息等 |
+| `MessageInput` | 输入框组件 | 消息输入和发送 |
+| `ChatSetting` | 单聊和群聊的管理组件 | 会话设置、群管理等 |
+| `Search` | 云端搜索组件 | 搜索消息、联系人等 |
+| `ContactList` | 联系人组件 | full-featured 模式，通讯录功能 |
+
+**重要提示**：
+- Agent 必须严格按照集成文档中的组件名称和用法生成代码
+- 不要自行创造或修改组件名称
+- 组件的具体使用方式以工具返回的集成文档为准
+
+---
+
+## 🛠️ 集成模式分发 (Goals)
+
+根据用户的需求，Agent 必须选择对应的执行路径：
+
+### 1. 全量功能集成 (full-featured)
+
+**目标**: 实现类似微信的完整 IM 应用
+
+**核心组件**: 
+- `ConversationList` (会话列表)
+- `Chat` (聊天容器)
+- `ContactList` (通讯录)
+- `Search` (云端搜索)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 构建独立的聊天应用
+- 需要完整的会话管理、通讯录、群组管理功能
+- 作为 Web 应用的核心功能模块
+
+---
+
+### 2. 仅集成聊天窗口 (chat-only)
+
+**目标**: 适用于客服、问诊、详情页私聊等纯对话场景
+
+**核心组件**: 
+- `Chat` (聊天容器)
+- `MessageList` (消息列表)
+- `ChatHeader` (聊天头部)
+- `MessageInput` (输入框)
+
+**执行参考**: 
+- 参考工具返回结果中实时获取的 `integration.md` 指令
+
+**适用场景**:
+- 客服咨询场景（用户点击咨询按钮进入聊天页面）
+- 医疗在线问诊（患者与医生一对一沟通）
+- 订单详情页私聊（买家与卖家沟通）
+- 社交应用中的私信功能
+
+**🔴 默认排除功能（Agent 必须遵守）**:
+
+Agent 在生成 chat-only 模式代码时，**默认排除**以下功能和组件：
+
+1. **默认不集成 Sidebar（侧边栏）**
+   - 默认不生成任何侧边栏相关代码
+   - 默认不引入会话列表、通讯录等侧边栏组件
+   - 聊天窗口默认应该是独立的、无侧边栏的纯聊天界面
+
+2. **默认不集成 ChatSetting（聊天设置）**
+   - 默认不生成会话设置、群管理等功能
+   - 默认不在 ChatHeader 右侧添加设置按钮
+   - 默认不引入 ChatSetting 组件
+
+3. **默认不集成会话内搜索功能**
+   - 默认不添加消息搜索功能
+   - 默认不在聊天界面添加搜索入口
+   - 默认不引入 Search 组件
+
+4. **默认不集成会话列表（ConversationList）**
+   - chat-only 模式下，用户通过外部路由/参数指定会话 ID
+   - 默认不需要会话切换功能
+
+---
+
+**⚠️ 用户主动要求时的例外处理**:
+
+如果用户在 chat-only 模式下**明确要求**添加某些扩展功能，Agent **应该允许并执行**：
+
+**触发条件**（满足任一即可）:
+- 用户明确说明："需要 ChatSetting"、"要集成聊天设置"、"添加会话设置功能"
+- 用户明确说明："需要 Search"、"要添加搜索功能"、"集成会话内搜索"
+- 用户明确说明："需要 Sidebar"、"要添加侧边栏"
+- 用户明确提出其他扩展功能需求
+
+**Agent 执行流程**:
+1. ✅ **确认用户需求**：识别到用户主动要求添加扩展功能
+2. ✅ **允许集成**：在 chat-only 模式基础上，额外集成用户要求的组件
+3. ✅ **保持克制**：只添加用户明确要求的功能，不擅自扩展其他功能
+4. ✅ **遵循文档**：按照集成文档的规范正确集成所需组件
+
+---
+
+## 📞 扩展功能：音视频通话 (TUICallKit)
+
+若需求中包含"通话"或"视频"功能，Agent 必须执行：
+
+### 组件挂载
+- 使用 `Teleport` 将 TUICallKit 组件挂载到 body
+
+### 交互注入
+
+**在 ChatHeader 组件的右侧插槽注入通话按钮**:
+- 图标: 电话、摄像机等
+- 组件使用方式参考集成文档
+
+**单聊逻辑**:
+- 通过 `TUICallKitServer.call` 发起通话
+- UserID 自动取自当前激活会话
+
+**群聊逻辑**:
+- 需集成成员选择组件
+- 引导用户选择群成员后再发起通话
+
+---
+
+## ✍️ Agent 代码生成示例指令 (Prompts)
+
+当 Agent 开始编写代码时，应遵循以下语义逻辑：
+
+**全量功能集成 (full-featured)**:
+> "按照 `full-featured` 模式，为我生成一个 Vue3 TUIKit 集成页面。请自动配置 `C2Cadministrator` 默认激活会话，并注入由 `get_usersig` 工具获取的凭据。禁止创建 config 文件。**🔴 重要：必须严格按照集成文档中的完整 CSS 样式代码生成，禁止任何自定义或修改。**"
+
+**仅聊天窗口集成 (chat-only)**:
+> "按照 `chat-only` 模式，为我生成一个 Vue3 TUIKit 聊天窗口。请自动配置 `C2Cadministrator` 默认激活会话，并注入由 `get_usersig` 工具获取的凭据。禁止创建 config 文件。**严格排除 Sidebar、ChatSetting、会话内搜索等功能，仅保留核心聊天组件。🔴 重要：必须严格按照集成文档中的完整 CSS 样式代码生成，禁止任何自定义样式。**"
+
+---
+
+## 📝 关键要点总结
+
+| 类别 | 要求 |
+|------|------|
+| **框架版本** | 专门针对 Vue3 项目 |
+| **文档优先** | 严格遵循工具返回的最新文档指令 |
+| **🔴 CSS 样式** | **严格按照集成文档 CSS，禁止任何自定义或修改** |
+| **静默集成** | 代码编写完成后自动安装依赖并启动开发服务器 |
+| **凭证注入** | 自动调用 `get_usersig`，直接注入代码 |
+| **默认会话** | 自动激活 `C2Cadministrator` 会话 |
+| **依赖管理** | 自动检测并安装所需依赖包 |
+| **构建工具** | Vite 项目需添加 esbuild-wasm 补丁配置 |
+| **集成模式** | 支持 full-featured（全量）和 chat-only（仅聊天）两种模式 |
+| **chat-only 限制** | ⚠️ 默认排除 Sidebar、ChatSetting、搜索功能；用户主动要求时允许集成 |
+
+---
+
+## 🎯 Agent 执行检查清单
+
+在完成代码生成后，Agent 必须确认以下所有项目：
+
+### 项目初始化
+- [ ] 已创建 Vue3 项目或在现有项目中集成
+- [ ] 已安装 `@tencentcloud/chat-uikit-vue3` 依赖
+- [ ] 如果需要音视频通话，已安装 `@tencentcloud/call-uikit-vue`
+- [ ] 如果是 Vite 项目，已添加 esbuild-wasm 补丁配置
+
+### 代码生成
+- [ ] 已在 main.js 中正确注册 TUIKit 组件
+- [ ] 已创建主聊天容器组件（ChatContainer.vue 或类似）
+- [ ] 组件使用了 `<script setup>` 语法
+- [ ] 🔴 **CSS 样式严格合规**：
+  - [ ] 已从集成文档中完整获取所有 CSS 样式代码
+  - [ ] 已使用集成文档中的官方类名
+  - [ ] 已完整复制集成文档中的 CSS 变量定义
+  - [ ] 已使用集成文档中的布局样式配置
+  - [ ] 禁止创建任何自定义样式类名
+  - [ ] 禁止修改集成文档中的任何样式属性
+  - [ ] 样式代码与集成文档完全一致
+
+### 凭证与登录
+- [ ] 🔴 已调用 `get_usersig` 工具获取测试凭证
+- [ ] 已将 SDKAppID、UserID、UserSig 直接注入到代码中
+- [ ] 禁止创建 config.js 或 .env 文件
+- [ ] 已实现 TUILogin.login() 登录逻辑
+
+### 会话激活
+- [ ] 已添加默认激活 `C2Cadministrator` 会话的逻辑
+- [ ] 使用了正确的 API（setActiveConversation）
+
+### 集成模式
+- [ ] 已根据用户需求选择正确的集成模式（full-featured 或 chat-only）
+- [ ] full-featured 模式：已集成 ConversationList、Chat、Contact 等组件
+- [ ] chat-only 模式：已集成核心组件（Chat、MessageList、ChatHeader、MessageInput）
+- [ ] chat-only 模式：已根据用户需求判断是否需要集成扩展功能
+  - [ ] 如果用户未主动要求，已确认不包含 Sidebar、ChatSetting、Search 等组件
+  - [ ] 如果用户主动要求（如"需要 ChatSetting"），已额外集成用户明确要求的功能
+
+### 音视频通话（可选）
+- [ ] 如果需要通话功能，已使用 Teleport 挂载 TUICallKit
+- [ ] 已在 ChatHeader 组件右侧插槽添加通话按钮
+- [ ] 已实现单聊和群聊的通话逻辑
+
+### 最终检查
+- [ ] 已调用 `record_result` 记录集成结果
+- [ ] 已自动安装依赖（npm install）
+- [ ] 已自动启动开发服务器（npm run dev）
+- [ ] 项目可以正常运行，无报错
+
+---
+
+## 💡 常见问题处理
+
+### 1. Vite 构建错误
+
+**问题现象**：Vite 项目运行时报 esbuild 相关错误
+
+**原因**：某些依赖包与 esbuild 不兼容
+
+**解决方案**：
+在 `package.json` 中添加补丁配置：
+```json
+{
+  "overrides": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  },
+  "resolutions": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  }
+}
+```
+
+### 2. chat-only 模式包含了不该有的功能
+
+**问题现象**：chat-only 模式生成的代码包含了用户未要求的 Sidebar、ChatSetting 或会话内搜索功能
+
+**原因**：Agent 未正确判断用户需求，擅自添加了扩展功能
+
+**判断标准**：
+- ✅ **应该添加**：用户明确说明"需要 ChatSetting"、"要集成搜索"、"添加设置功能"等
+- ❌ **不应添加**：用户只说"搭建 chat-only 聊天窗口"，未提及扩展功能
+
+**解决方案**：重新生成代码，确保默认不包含扩展功能
+
+### 3. CSS 样式不符合集成文档
+
+**问题现象**：生成的代码使用了自定义样式类名，或修改了官方样式
+
+**原因**：Agent 未严格按照集成文档中的 CSS 样式生成代码
+
+**解决方案**：
+1. 重新调用 `get_web_chat_uikit_integration` 获取最新集成文档
+2. 从集成文档中完整复制所有 CSS 样式代码
+3. 严格按照集成文档中的类名、变量名、样式属性使用
+4. 禁止任何形式的修改或自定义
+
+---
+
+## 🔗 相关工具参考
+
+### 必须使用的工具
+
+#### `get_usersig` - 获取完整测试凭证（强制调用）
+**用途**：生成完整的测试账号和鉴权凭证，包括：
+- `SDKAppID`: 应用标识
+- `userID`: 测试用户 ID
+- `userSig`: 用户签名（有效期 7 天）
+
+**调用时机**：在生成登录代码之前必须调用
+
+**使用约束**：
+- ✅ 必须使用工具返回的完整凭证
+- ❌ 禁止让用户手动填写 SDKAppID 和 secretKey
+- ❌ 禁止创建配置文件存储凭证
+
+#### `record_result` - 记录集成结果
+**用途**：记录集成过程和结果，用于统计和分析
+
+---
+
+**适用框架**: Vue3  
+**TUIKit 版本**: @tencentcloud/chat-uikit-vue3 > 4.0.0  
+**构建工具**: Vite (推荐) / Webpack

package/resource/doc/roomkit/vue/features/call-user-to-room.md

@@ -0,0 +1,256 @@
+会中呼叫功能允许会议内的用户（邀请者）向房间外的其他用户（被邀请者）发送实时入会邀请。该功能基于 `Atomicx State Hooks` 实现，能够帮助开发者快速构建具有主动邀约能力的互动场景。
+
+## 适用场景
+- **协同办公：**在进行远程会议时，若涉及跨部门决策，可一键呼叫外部专家快速入会，缩短沟通链路。
+
+- **直播教学：**老师在授课过程中，若发现部分学生缺席，可直接邀请其加入课堂。
+
+- **互联网医疗会诊：**首诊医生在病历分析过程中，通过呼叫功能邀请上级医生进入虚拟诊室进行多方会诊，或者医生呼叫在等候室的患者进行问诊。
+
+
+## 前提条件
+
+在接入功能前，请确保满足以下条件：
+- **邀请者 (User A)：**用户已经通过 `useLoginState` 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，并已作为一个房间的房主或成员在房间内，参考 [房间周期](https://write.woa.com/document/197379861957083136)。
+
+- **被邀请者 (User B)：**用户已经通过 `useLoginState` 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，以便接收信令事件。
+
+- **环境依赖：**项目已正确安装并引入 `tuikit-atomicx-vue3`。
+
+
+## 实现会中呼叫功能
+
+实现会中呼叫的核心流程如下：
+
+![会中呼叫时序图](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/82ba8603dee611f0a4f35254007c27c5.png)
+
+会中呼叫时序图
+
+
+### 步骤1：发起呼叫（邀请者）
+
+邀请者调用 [callUserToRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#callUserToRoom) 接口发起邀请。请确保邀请者当前已在房间内（即 [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) 不为空），否则无法发起呼叫。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom, callUserToRoom } = useRoomState();
+
+const inviteUser = async () => {
+  // 会中呼叫必须关联一个已存在的 roomId，因此需先校验当前用户的进房状态
+  if (!currentRoom.value) {
+    console.warn('请先进入房间再发起邀请');
+    return;
+  }
+
+  try {
+    const resultMap = await callUserToRoom({
+      roomId: currentRoom.value.roomId, // 被邀请者将要加入的房间 ID
+      userIdList: ['user1', 'user2'],    // 目标用户 ID 数组，支持单人或多人
+      timeout: 60,                        // 邀请有效时长（秒），超时后双方会触发 onCallTimeout
+      // extensionInfo 可用于传递业务自定义数据，例如邀请类型、附加消息等
+      extensionInfo: JSON.stringify({ type: 'emergency', priority: 'high' }) 
+    });
+    
+    // resultMap 返回每个 userId 对应的状态，例如 Success、AlreadyInRoom (已在房) 或 AlreadyInCalling (通话中)
+    console.log('邀请发送完成，详情状态映射:', resultMap);
+  } catch (error) {
+    console.error('呼叫请求发送失败，请检查网络或登录状态:', error);
+  }
+};
+```
+
+### 步骤2：监听呼叫事件（被邀请者）
+
+被邀请者需要监听 `onCallReceived` 事件。建议在例如 `App.vue`等长驻组件中实现，以确保无论用户在哪个页面都能响应。
+``` typescript
+import { ref, onMounted, onUnmounted } from 'vue';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
+
+const { 
+  subscribeEvent, 
+  unsubscribeEvent, 
+  acceptCall, 
+  rejectCall, 
+  joinRoom, 
+  currentRoom 
+} = useRoomState();
+
+const showInviteDialog = ref(false); // 控制 UI 弹窗显隐
+const currentCallInfo = ref(null);   // 缓存收到的邀请上下文
+
+const handleCallReceived = async ({ roomInfo, call, extensionInfo }) => {
+  // 冲突处理：如果用户当前已经在会议中，根据业务策略通常应直接拒绝新邀请，防止干扰
+  if (currentRoom.value?.roomId) {
+    await rejectCall({ roomId: roomInfo.roomId });
+    return;
+  }
+
+  // 记录邀请详情，用于在 UI 上展示邀请者名称或业务透传数据
+  currentCallInfo.value = { roomInfo, call };
+  showInviteDialog.value = true;
+};
+
+// 接受邀请逻辑
+const onUserAccept = async () => {
+  if (!currentCallInfo.value) return;
+  const { roomId } = currentCallInfo.value.roomInfo;
+
+  try {
+    // 关键流程 A：响应信令。告知邀请者已接受，使其能更新 UI（例如显示“对方已接听”）
+    await acceptCall({ roomId });
+    
+    // 关键流程 B：执行进房。只有调用 joinRoom 才会真正开启音视频推拉流链路
+    await joinRoom({ roomId }); 
+  } catch (error) {
+    console.error('接受呼叫后的进房操作失败:', error);
+  } finally {
+    closeDialog();
+  }
+};
+
+// 拒绝邀请逻辑
+const onUserReject = async () => {
+  if (currentCallInfo.value) {
+    // 告知邀请者已拒绝，邀请者会收到 onCallRejected 事件
+    await rejectCall({ roomId: currentCallInfo.value.roomInfo.roomId });
+  }
+  closeDialog();
+};
+
+const closeDialog = () => {
+  showInviteDialog.value = false;
+  currentCallInfo.value = null;
+};
+
+// 事件全生命周期管理：确保在组件挂载时监听，销毁时移除，防止事件溢出
+onMounted(() => {
+  subscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+  
+  // 监听导致邀请结束的各种异常/同步事件，确保 UI 弹窗能及时闭合
+  subscribeEvent(RoomEvent.onCallCancelled, closeDialog); // 邀请者取消了呼叫
+  subscribeEvent(RoomEvent.onCallTimeout, closeDialog);   // 呼叫超时未响应
+  subscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog); // 用户在其他设备已处理该呼叫
+});
+
+onUnmounted(() => {
+  // 移除所有监听器，避免在组件销毁后继续执行 handleCallReceived 导致内存泄漏或报错
+  unsubscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+  unsubscribeEvent(RoomEvent.onCallCancelled, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallTimeout, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog);
+});
+```
+
+## 实践教程：提升呼叫接通率
+
+为了在业务中获得更高的呼叫接通率，除了基础功能的实现外，建议参考以下策略优化用户体验：
+
+### 1. 增强呼叫感知（避免用户遗漏）
+
+由于 Web 端特性，浏览器静音或页面处于后台运行状态可能导致用户遗漏呼叫。
+- **视觉提醒**：利用 [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) 检测页面可见性状态。若页面处于后台，可通过循环修改 `document.title` 实现标题栏闪烁提示（例如：“【新邀请】UserA 邀请您入会...”），以吸引用户注意。
+
+- **听觉提醒**：在 `onCallReceived` 事件触发时播放高优先级的提示铃声。注意：需遵循浏览器的 [自动播放策略](https://developer.mozilla.org/zh-CN/docs/Web/Media/Guides/Autoplay)，大部分浏览器在缺乏用户交互（例如点击、触摸或按键）的情况下会限制音频自动播放。
+
+
+### 2. 丰富邀请上下文（提升接听意愿）
+
+缺乏明确意图的邀请容易被用户拒绝。建议充分利用 `extensionInfo` 字段传递关键业务信息，以提升用户的接听意愿。
+- **传递业务上下文**：利用 `extensionInfo` 透传如 `reason`（例如：“项目紧急评审”）、`level`（例如：“P0故障排查”）等业务字段，告知用户呼叫的紧迫性和重要性。
+
+
+### 3. 多通道触达兜底（确保消息可达）
+
+受限于 Web 端机制，浏览器进程结束将无法接收实时信令。建议采取以下替代方案以确保触达：
+- **浏览器系统通知**：引导用户授权 [Web Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)。只要浏览器进程未关闭（包括最小化或在后台标签页），即可触发操作系统级别的弹窗通知，有效提醒用户。
+
+- **多通道触达**：建议结合业务后端逻辑，在检测到用户不在线或超时未响应时，通过**短信**、**邮件**或**企业微信**等外部渠道发送入会链接，实现全方位触达。
+
+
+### 4. 智能重试机制（解决“接受邀请后进房失败”）
+
+在弱网或其他不稳定环境下，用户点击接受邀请后调用 `joinRoom` 可能会出现偶发性失败。
+- **自动重试**：建议在 `onUserAccept` 的异常处理逻辑（`catch`）中引入 2-3 次自动重试机制（推荐结合指数退避策略），以最大程度确保用户点击“接受”后能成功加入会议。
+
+
+## 开发注意事项
+1. **接受邀请不等于进房**
+
+
+   `acceptCall` 仅仅是信令层面的回复（告知对方已接听）。用户必须在调用 `acceptCall` 后紧接着手动调用 `await joinRoom({ roomId })` 才能真正进入音视频房间。
+
+2. **生命周期管理**
+
+
+   请务必在组件销毁周期（`onUnmounted`）调用 `unsubscribeEvent`。如果不清理监听器，当用户切换页面时，旧页面的监听器会残留在内存中，导致一次邀请弹出多个窗口或逻辑重复执行。
+
+3. **超时设置**
+
+
+   如果不设置 `timeout` 参数，在某些网络异常或程序崩溃情况下，邀请可能长期处于挂起状态，导致无法再次对该用户发起呼叫。建议设置为 30-60 秒。
+
+
+## 常见问题
+1. **如何在呼叫时带上自定义参数（如“来自XX的紧急会议”）？**
+
+
+   使用 `callUserToRoom` 的 `extensionInfo` 参数传递 JSON 字符串。被邀请者可以在 `onCallReceived` 事件的 `extensionInfo` 字段中解析该字符串获取业务信息。
+
+2. **被邀请者如果不在线，上线后能收到邀请吗？**
+
+
+   不可以。邀请事件是一个瞬时信令动作，SDK 目前不会补发离线期间收到的呼叫通知。
+
+3. **可以取消已发出的邀请吗？**
+
+
+   可以。调用 `cancelCall({ roomId, userIdList })` 即可撤销。此时被邀请者会收到 `onCallCancelled` 事件，您需要监听此事件来关闭被邀请端的 UI 弹窗。
+
+4. **接受后进房失败怎么办？**
+
+
+   检查是否已登录 `TUIRoomEngine`，重试 `joinRoom({ roomId })` 并捕获错误提示用户；必要时在 UI 上提供“重试”按钮。
+
+5. **对方忙线或已在其他房间如何提示？**
+
+
+   `callUserToRoom` 的返回值 `resultMap` 中若出现 `AlreadyInRoom` / `AlreadyInCalling`，应在邀请者 UI 提示“对方忙线/已在会中”，并决定是否稍后重试。
+
+6. **超时/取消后弹窗不关闭？**
+
+
+   确保监听 `onCallTimeout`、`onCallCancelled`、`onCallHandledByOtherDevice`，统一在回调里关闭弹窗、清理当前邀请数据。
+
+7. **多设备同时响铃如何处理？**
+
+
+   在任意设备接受/拒绝后，其余设备会收到 `onCallHandledByOtherDevice`，需关闭其他端弹窗避免重复处理。
+
+8. **extensionInfo 该怎么约定？**
+
+
+   建议使用 JSON 字符串并约定字段（例如 `type`、`priority`、`from`），在 `handleCallReceived` 时解析后展示友好文案（例如“来自XX的紧急会议”）。
+
+
+## **示例项目**
+
+腾讯云在 GitHub 上提供了示例项目 [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts) ，您可以参考以实现完整的 RoomKit 功能。
+
+## API 文档
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**State/Component**</td>
+
+<td rowspan="1" colSpan="1" >**功能描述**</td>
+
+<td rowspan="1" colSpan="1" >**API 文档**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useRoomState**</td>
+
+<td rowspan="1" colSpan="1" >房间状态管理（创建、加入、预约等）</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState)</td>
+</tr>
+</table>