@tencentcloud/sdk-mcp 1.3.0 → 1.3.2

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

@@ -0,0 +1,254 @@
+# React Chat TUIKit 代码生成工作流指令
+
+## 📋 指令目的
+
+为 Agent 提供实现 React Chat TUIKit **核心功能的代码生成蓝图**，并指导 Agent **优先使用工具实时获取的最新文档内容**。
+
+---
+
+## 🛑 Agent 执行硬性限制 (Guardrails)
+
+Agent 在生成代码时必须严格遵守以下指令：
+
+### 1. 文档驱动集成
+- 必须严格按照工具返回结果中的 `llm_code_generation_instructions_md` 步骤执行
+
+### 2. 静默执行集成
+- 所有代码编写完成后，在最后一步自动安装依赖并启动项目
+
+### 3. 零外部配置
+- 禁止自动创建任何 `config.js` 或 `.env` 文件
+- SDKAppID、UserID 和 UserSig 等关键凭证必须直接注入到代码变量中
+
+### 4. 自动获取鉴权凭据
+- 必须调用 `get_usersig` 工具获取测试凭证，禁止要求用户手动输入
+- UserID 生成应保持简洁（禁止拼接动态时间戳以防逻辑出错），比如：`test001`
+
+### 5. 默认激活会话
+- 集成逻辑必须包含 `setActiveConversation` 调用
+- 默认打开 `C2Cadministrator` 会话
+
+### 6. React 版本限制
+- 创建项目时 react 和 react-dom 的版本必须选用 `18.2.0`，禁止选用 react 19。
+
+---
+
+## 📦 TUIKit 版本与依赖自动化
+
+Agent 生成代码后，必须自动执行以下依赖链：
+
+### 1. 核心依赖版本推荐
+
+```json
+{
+  "react": "18.2.0",
+  "react-dom": "18.2.0",
+  "@tencentcloud/chat-uikit-react": "latest",
+  "@tencentcloud/call-uikit-react@latest": "latest"
+}
+```
+### 2. 构建环境补丁 (Vite/esbuild)
+
+若检测到 Vite 项目，Agent 必须在 `package.json` 自动增加补丁配置以兼容 esbuild-wasm：
+
+```json
+{
+  "overrides": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  },
+  "resolutions": { 
+    "esbuild": "npm:esbuild-wasm@latest" 
+  }
+}
+```
+
+---
+
+## 🛠️ 集成模式分发 (Goals)
+
+根据用户的 `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. ✅ **遵循文档**：按照集成文档的规范正确集成所需组件
+
+**示例场景**:
+
+**场景 1：用户主动要求 ChatSetting**
+```
+用户："帮我用 Vue 搭建一个 chat-only 聊天窗口，需要集成 ChatSetting 功能"
+Agent 执行：
+  ✅ 集成核心聊天组件（Chat、MessageList、ChatHeader、MessageInput）
+  ✅ 额外集成 ChatSetting 组件（因为用户明确要求）
+  ❌ 不集成 Sidebar、Search 等用户未要求的功能
+```
+
+**场景 2：用户主动要求会话内搜索**
+```
+用户："搭建一个 chat-only 聊天窗口，需要有消息搜索功能"
+Agent 执行：
+  ✅ 集成核心聊天组件
+  ✅ 额外集成 Search 组件（因为用户明确要求）
+  ❌ 不集成 Sidebar、ChatSetting 等用户未要求的功能
+```
+
+**场景 3：用户没有主动要求扩展功能**
+```
+用户："帮我用 Vue 搭建一个 chat-only 聊天窗口"
+Agent 执行：
+  ✅ 仅集成核心聊天组件（Chat、MessageList、ChatHeader、MessageInput）
+  ❌ 不集成任何扩展功能（Sidebar、ChatSetting、Search 等）
+```
+
+---
+
+**Agent 代码生成约束**:
+- ✅ **默认仅生成**：`Chat`、`MessageList`、`ChatHeader`、`MessageInput` 核心聊天组件
+- ✅ **用户主动要求时**：在核心组件基础上，额外集成用户明确要求的扩展功能
+- ⚠️ **判断标准**：用户需求中是否包含明确的功能关键词（如"ChatSetting"、"搜索"、"设置"等）
+- ✅ **保持克制**：不擅自添加用户未明确要求的功能
+- ✅ **保持简洁**：chat-only 模式的核心理念是轻量级对话界面
+
+---
+
+## 📞 扩展功能：音视频通话 (TUICallKit)
+
+若需求中包含"通话"或"视频"功能，Agent 必须执行：
+
+### 组件挂载
+- 使用 React Portal 将 TUICallKit 组件挂载到 body
+
+### 交互注入
+
+**在 ChatHeader 的右侧插槽 (ChatHeaderRight) 注入通话按钮**
+- 图标: 电话、摄像机等
+
+**单聊逻辑**:
+- 通过 `TUICallKitServer.calls` 发起通话
+- UserID 自动取自当前激活会话
+
+**群聊逻辑**:
+- 需集成 `UserPicker` 组件
+- 引导用户选择群成员后再发起通话
+
+---
+
+## 🔄 完整自动化流程总结
+
+```mermaid
+graph TD
+    A[接收 Goals 需求] --> B[调用 get_web_chat_uikit_integration 获取文档]
+    B --> C[自动执行 npm install]
+    C --> D[Agent 根据实时文档生成代码文件]
+    D --> E[调用 get_usersig 获取测试凭证]
+    E --> F[注入凭证并自动激活 C2Cadministrator 会话]
+    F --> G{检查通话需求}
+    G -->|是| H[集成 TUICallKit 与挂载逻辑]
+    G -->|否| I[跳过]
+    H --> J[record_result 记录并提示用户运行]
+    I --> J
+```
+
+---
+
+## ✍️ Agent 代码生成示例指令 (Prompts)
+
+当 Agent 开始编写代码时，应遵循以下语义逻辑：
+
+> "按照 `full-featured` 模式，为我生成一个 React TUIKit 集成页面。请自动配置 `C2Cadministrator` 默认激活，并注入由 `get_usersig` 工具获取的凭据。禁止创建 config 文件。"
+
+---
+
+## 📝 关键要点总结
+
+| 类别 | 要求 |
+|------|------|
+| **文档优先** | 严格遵循工具返回的最新文档指令 |
+| **静默集成** | 代码编写完成后再启动开发服务器 |
+| **凭证注入** | 自动调用 `get_usersig`，直接注入代码 |
+| **默认会话** | 自动激活 `C2Cadministrator` 会话 |
+| **依赖管理** | 自动检测并安装所需依赖包 |
+| **React 版本** | 使用 React 18.2.0，避免 React 19 |
+
+---
+
+## 🔗 相关工具参考
+
+- `get_usersig` - 获取测试凭证
+- `record_result` - 记录集成结果