neo-cmp-cli 1.12.8 → 1.12.10

package/template/develop/ChatPage /347/273/204/344/273/266/344/275/277/347/224/250/350/257/264/346/230/216/346/226/207/346/241/243.md"

@@ -1,507 +0,0 @@
-# ChatPage 组件使用说明文档
-
-## 概述
-
-`ChatPage` 是 neo-ai-copilot-fe-h5 项目中的核心聊天页面组件，用于在移动端 H5 环境中提供完整的 AI 智能体对话功能。该组件集成了智能体管理、历史会话管理、消息发送、录音功能等核心能力。
-
-## 组件架构
-
-### 文件结构
-
-```
-chatPage/
-├── component.tsx      # 主组件文件
-├── store.tsx         # MobX 状态管理
-├── styled.tsx        # 样式组件
-├── style.scss        # 样式文件
-├── interface/
-│   └── props.tsx     # Props 类型定义
-└── index.tsx         # 组件注册入口
-```
-
-### 组件层次结构
-
-```
-ChatPage (Class Component)
-└── AppCenter (缓存管理)
-    └── CopilotKit (上下文提供)
-        └── ChatPageView (功能组件)
-            ├── TitleBar (标题栏)
-            ├── ChatBox (聊天框)
-            └── SlideMenu (侧边栏菜单)
-```
-
-## 核心功能
-
-### 1. 智能体管理
-
-- **智能体列表加载**：自动获取可用的智能体列表
-- **智能体切换**：支持在不同智能体间切换
-- **智能体详情**：获取并缓存智能体的详细信息
-- **智能体图标映射**：自动映射智能体图标和颜色
-
-### 2. 会话管理
-
-- **新对话创建**：创建新的对话会话
-- **历史会话加载**：加载并显示历史对话记录
-- **会话切换**：在不同历史会话间切换
-- **会话状态同步**：与全局会话状态管理系统同步
-
-### 3. 消息交互
-
-- **消息发送**：支持文本、文件等多种消息类型
-- **流式响应**：支持流式消息接收和显示
-- **消息状态管理**：跟踪消息的发送和处理状态
-
-### 4. 录音功能
-
-- **录音按钮集成**：在标题栏集成录音按钮
-- **录音状态检查**：检查是否有正在进行的录音
-- **录音提示**：退出页面时提示录音状态
-
-### 5. UI 功能
-
-- **加载状态**：显示加载动画
-- **错误处理**：显示网络错误提示
-- **侧边栏菜单**：智能体和历史会话选择菜单
-- **标题栏**：显示当前会话信息和操作按钮
-
-## Props 接口
-
-### IProps
-
-```typescript
-interface IProps {
-  // 浮动配置（可选）
-  floatConfig?: {
-    onMinimize?: Function      // 最小化回调
-    onFullScreen?: Function    // 全屏回调
-    setExtWidth?: Function     // 设置扩展宽度
-    isExpanded?: boolean       // 是否展开
-    isFullWidth?: boolean      // 是否全屏
-  }
-  
-  // 是否创建新对话
-  newChat?: boolean
-  
-  // 初始化指令配置
-  instructionConfig?: {
-    query?: string           // 初始查询内容
-    extend_params?: any      // 扩展参数
-    agentApiKey?: string     // 智能体 API Key
-    threadId?: string        // 会话 ID
-  }
-  
-  // Amis 上下文
-  context: any
-  
-  // 渲染函数
-  render: (type: string, props: any) => React.ReactNode
-  
-  // 文件路径（Amis 属性）
-  file: string
-  
-  // 主题 API Key
-  topicApiKey: string
-  
-  // 消息状态
-  messageStatus: Record<string, string>
-  
-  // 更新消息状态
-  updateMessageStatus: (conversation_id: string) => void
-  
-  // 设置智能体列表回调（可选）
-  setAgentList?: (agentList: any[]) => void
-  
-  // 注册 API 回调（可选）
-  registerAPIs?: (apis: Record<string, Function>) => () => void
-}
-```
-
-## 使用示例
-
-### 基础使用
-
-```tsx
-import ChatPage from '@/components/chatPage'
-
-// 在 Amis 页面中使用
-{
-  "type": "chatPage",
-  "newChat": false,
-  "instructionConfig": {
-    "agentApiKey": "your_agent_api_key",
-    "threadId": "123"
-  }
-}
-```
-
-### 创建新对话
-
-```tsx
-{
-  "type": "chatPage",
-  "newChat": true,
-  "instructionConfig": {
-    "agentApiKey": "your_agent_api_key",
-    "query": "你好，我想了解一下..."
-  }
-}
-```
-
-### 加载历史会话
-
-```tsx
-{
-  "type": "chatPage",
-  "newChat": false,
-  "instructionConfig": {
-    "threadId": "456"
-  }
-}
-```
-
-## 注册的 API
-
-组件通过 `registerAPIs` 回调注册了以下 API，供外部调用：
-
-### 1. createNewChat
-
-创建新对话（向后兼容的旧 API）
-
-```typescript
-createNewChat(initInstruction: string, agentApiKey?: string)
-```
-
-**参数：**
-- `initInstruction`: 初始指令内容
-- `agentApiKey`: 可选，智能体 API Key
-
-### 2. getCurrentAgent
-
-获取当前智能体信息
-
-```typescript
-getCurrentAgent(): IAgentItem
-```
-
-**返回：** 当前智能体信息对象
-
-### 3. getCurrentHistoryChat
-
-获取当前历史会话信息
-
-```typescript
-getCurrentHistoryChat(): IHistoryItem | null
-```
-
-**返回：** 当前历史会话信息对象或 null
-
-### 4. newSession
-
-创建新会话（新 API，异步）
-
-```typescript
-newSession(agentApiKey?: string): Promise<void>
-```
-
-**参数：**
-- `agentApiKey`: 可选，智能体 API Key
-
-**说明：** 异步函数，保证操作完成后才返回
-
-### 5. switchToHistoryChat
-
-切换到指定历史会话（新 API，异步）
-
-```typescript
-switchToHistoryChat(threadId: number): Promise<void>
-```
-
-**参数：**
-- `threadId`: 会话 ID
-
-**说明：** 异步函数，切换失败会抛出错误
-
-### 6. sendPrompt
-
-发送消息（标准 API，异步）
-
-```typescript
-sendPrompt(props: SendPromptProps): Promise<void>
-```
-
-**参数：**
-```typescript
-interface SendPromptProps {
-  sources: {
-    inputStr: string      // 输入文本
-    files?: File[]        // 附件文件
-  }
-  extendParams?: any      // 扩展参数
-  meta: {
-    topicApiKey?: string  // 主题 API Key
-    usage?: any           // 使用情况
-  }
-  options?: {
-    persistence?: boolean // 是否持久化
-  }
-}
-```
-
-**说明：** 
-- 支持主题 API Key 的临时设置和恢复
-- 异步函数，确保消息发送完成
-
-## 状态管理
-
-组件使用 MobX 进行状态管理，通过 `ChatPageStore` 类管理以下状态：
-
-### 状态属性
-
-- `agentDetailMap`: 智能体详情缓存
-- `agentDetailInfo`: 当前选中的智能体详情
-- `agentInfo`: 当前选中的智能体信息
-- `historyChatInfo`: 历史聊天信息
-- `agentList`: 智能体列表
-- `loading`: 加载状态
-- `error`: 错误状态
-- `instructionConfig`: 初始化指令配置
-- `showNewChat`: 是否显示新建对话按钮
-- `loaded`: 是否加载完成
-
-### 计算属性
-
-- `agentInited`: 智能体是否初始化完成
-- `historyChatData`: 历史聊天数据（转换为普通对象）
-- `agentDetailData`: 智能体详情数据（转换为普通对象）
-- `titleLabel`: 标题标签文本
-- `historyChatId`: 历史聊天 ID
-- `agentId`: 智能体 ID
-- `agentIcon`: 智能体图标
-
-### 主要方法
-
-- `getChatPage(newChat?, instructionConfig?)`: 获取聊天页面数据
-- `createNewChat(instructionConfig, agentApiKey?)`: 创建新对话
-- `switchToHistoryChat(threadId)`: 切换到历史会话
-- `setAgentInfo(agentInfo)`: 设置智能体信息
-- `setHistoryChatInfo(agentInfo, historyChatInfo)`: 设置历史聊天信息
-- `updateShowNewChatStatus(show)`: 更新显示新建对话按钮状态
-- `updateHistoryName(name)`: 更新历史会话名称
-
-## 生命周期
-
-### 初始化流程
-
-1. **组件挂载**
-   - 注册到 Amis ScopedContext
-   - 初始化 ChatPageStore
-   - 设置 AppCenter 缓存
-
-2. **数据加载**
-   - 调用 `getChatPage()` 获取初始数据
-   - 并行请求智能体列表和历史会话
-   - 根据配置选择默认智能体或历史会话
-
-3. **API 注册**
-   - 注册 AudioAgentController API
-   - 注册 CopilotKit API
-   - 设置状态栏样式
-
-4. **监听更新**
-   - 监听智能体列表变化
-   - 监听历史会话变化
-   - 监听共享文件引擎初始化
-
-### 清理流程
-
-1. **组件卸载**
-   - 取消注册 ScopedContext
-   - 注销所有注册的 API
-   - 恢复状态栏样式
-
-## 依赖关系
-
-### 外部依赖
-
-- `react`: React 框架
-- `amis`: Amis 低代码框架
-- `mobx` / `mobx-react`: 状态管理
-- `antd-mobile`: 移动端 UI 组件库
-- `dsbridge`: 原生桥接库
-- `lodash`: 工具函数库
-
-### 内部依赖
-
-- `neo-ai-common`: 公共库（组件、Hooks、工具函数）
-- `neo-ui-component-h5`: H5 UI 组件库
-- `@/hooks`: 项目 Hooks
-- `@/controllers`: 控制器
-- `@/baseElement`: 基础元素组件
-
-### 关键依赖组件
-
-- `CopilotKit`: 提供 Copilot 上下文
-- `AppCenter`: 提供缓存管理
-- `ChatBox`: 聊天框组件
-- `AgentsMenu`: 智能体菜单组件
-- `AudioRecordButton`: 录音按钮组件
-
-## 特殊功能说明
-
-### 1. 录音功能集成
-
-组件集成了录音功能，通过 `AudioAgentController` 管理：
-
-- 检查录音状态：在退出页面时检查是否有正在进行的录音
-- 录音提示：如果有录音，显示提示框
-- 录音 API：注册录音相关的 API 供外部调用
-
-### 2. 共享文件引擎
-
-组件支持通过共享文件选择智能体：
-
-- 监听 `selectAgentApiKeyBySharedFiles` 变化
-- 自动切换到文件中选择的智能体
-- 创建新对话时使用选中的智能体
-
-### 3. 会话状态同步
-
-组件与全局会话状态管理系统集成：
-
-- 使用 `useCopilotMessageStatus` 获取会话状态
-- 使用 `useCopilotKit` 更新会话 ID
-- 自动同步会话状态变化
-
-### 4. 特殊智能体支持
-
-组件对特定智能体有特殊处理：
-
-- `analyst_agent`: 使用 `chatBI` 组件渲染
-- 其他智能体：使用 `chatBox` 组件渲染
-
-## 样式定制
-
-组件使用 `styled-components` 和 SCSS 进行样式管理：
-
-- `PageContainer`: 页面容器样式
-- `ChatContainer`: 聊天容器样式
-- `.slide-menu-container`: 侧边栏菜单样式
-- `.loading-container`: 加载状态样式
-- `.error-container`: 错误状态样式
-
-可以通过修改 `styled.tsx` 和 `style.scss` 文件进行样式定制。
-
-## 错误处理
-
-组件包含完善的错误处理机制：
-
-1. **网络错误**
-   - 显示错误图标和提示信息
-   - 提供重新加载按钮
-   - 提供返回首页按钮
-
-2. **加载错误**
-   - 显示加载失败状态
-   - 记录错误信息到控制台
-
-3. **API 调用错误**
-   - 捕获并记录错误
-   - 不影响其他功能正常运行
-
-## 性能优化
-
-1. **缓存管理**
-   - 使用 AppCenter 缓存组件实例
-   - 缓存智能体详情信息
-
-2. **懒加载**
-   - 组件通过动态导入注册
-   - 按需加载子组件
-
-3. **状态优化**
-   - 使用 MobX 进行响应式状态管理
-   - 避免不必要的重新渲染
-
-## 注意事项
-
-1. **必须提供 Props**
-   - `context`: Amis 上下文（必需）
-   - `render`: 渲染函数（必需）
-   - `fetcher`: 数据获取函数（通过 env.fetcher 传递）
-
-2. **API 调用时机**
-   - 所有注册的 API 都是异步的
-   - 需要等待初始化完成后再调用
-   - 使用 Promise 处理异步操作
-
-3. **状态同步**
-   - 组件状态与全局状态需要同步
-   - 使用 Hooks 进行状态管理
-   - 注意避免状态冲突
-
-4. **录音功能**
-   - 退出页面时需要检查录音状态
-   - 录音过程中退出会显示提示
-   - 录音功能依赖 AudioAgentController
-
-## 常见问题
-
-### Q1: 如何切换智能体？
-
-A: 可以通过以下方式切换智能体：
-- 点击标题栏左侧的智能体列表图标
-- 调用 `newSession(agentApiKey)` API
-- 通过共享文件选择智能体
-
-### Q2: 如何创建新对话？
-
-A: 可以通过以下方式创建新对话：
-- 点击标题栏的新建对话按钮
-- 调用 `createNewChat()` 或 `newSession()` API
-- 设置 `newChat` prop 为 true
-
-### Q3: 如何发送消息？
-
-A: 可以通过以下方式发送消息：
-- 在聊天框中输入并发送
-- 调用 `sendPrompt()` API
-- 通过 AudioAgentController 发送录音消息
-
-### Q4: 如何获取当前会话信息？
-
-A: 可以通过以下 API 获取：
-- `getCurrentAgent()`: 获取当前智能体
-- `getCurrentHistoryChat()`: 获取当前历史会话
-
-### Q5: 组件加载失败怎么办？
-
-A: 组件会显示错误页面，提供以下选项：
-- 点击"重新加载"按钮重试
-- 点击"返回首页"按钮返回
-- 检查网络连接和 API 配置
-
-## 更新日志
-
-### 版本历史
-
-- **最新版本**: 支持完整的智能体对话功能
-- **主要特性**:
-  - 智能体管理和切换
-  - 历史会话管理
-  - 录音功能集成
-  - 会话状态同步
-  - API 注册机制
-
-## 相关文档
-
-- [ChatPageStore 文档](./store.tsx)
-- [Props 接口文档](./interface/props.tsx)
-- [AgentsMenu 组件文档](../AgentsMenu/README.md)
-- [ChatBox 组件文档](../ChatBox/README.md)
-
-## 联系方式
-
-如有问题或建议，请联系开发团队。
-