fix

2025-07-11 13:30:02 +08:00
parent bea1b85a00
commit e2ffc87d53
9 changed files with 1358 additions and 19 deletions
--- a/docs/AGUI_CHAT_FEATURES.md
+++ b/docs/AGUI_CHAT_FEATURES.md
@@ -0,0 +1,192 @@
+# AG-UI 聊天功能特性说明
+
+## 概述
+
+基于AG-UI协议实现的智能聊天组件，为项目详情页面提供左侧聊天窗口，支持实时的人机协作和智能体交互。
+
+## 核心特性
+
+### 1. 基于AG-UI协议的标准化通信
+
+- **事件驱动架构**: 支持16种标准AG-UI事件类型
+- **实时状态同步**: 智能体状态与UI实时同步
+- **双向通信**: 支持用户输入和智能体响应
+- **传输无关**: 支持多种传输方式（SSE、WebSocket等）
+
+### 2. 智能体事件类型支持
+
+| 事件类型 | 描述 | UI展示 |
+|---------|------|--------|
+| `message` | 消息内容 | 聊天气泡 |
+| `progress` | 进度更新 | 进度条 |
+| `thinking` | 思考状态 | 动画指示器 |
+| `tool_call` | 工具调用 | 工具调用卡片 |
+| `state` | 状态变化 | 连接状态指示 |
+| `error` | 错误信息 | 错误提示 |
+| `complete` | 完成状态 | 完成标识 |
+
+### 3. 用户界面特性
+
+#### 聊天界面
+- **现代化设计**: 简洁美观的聊天界面
+- **实时滚动**: 自动滚动到最新消息
+- **状态指示**: 连接状态、处理状态可视化
+- **消息状态**: 发送中、已发送、错误状态
+
+#### 消息展示
+- **多角色支持**: 用户、助手、系统消息
+- **时间戳**: 每条消息显示时间
+- **事件可视化**: AG-UI事件的可视化展示
+- **进度跟踪**: 实时进度条和状态更新
+
+#### 交互体验
+- **快捷键支持**: Enter发送，Shift+Enter换行
+- **智能禁用**: 处理中自动禁用输入
+- **错误处理**: 友好的错误提示和重试机制
+
+### 4. 智能体能力
+
+#### 视频创作智能体
+- **专业能力**: 视频生成、脚本编写、模特选择
+- **场景理解**: 产品展示、用户体验优化
+- **质量控制**: 内容优化、性能监控
+
+#### 内容优化智能体
+- **分析能力**: 内容分析、受众定位
+- **优化策略**: 参与度优化、A/B测试
+- **性能指标**: 转化率分析、效果评估
+
+## 技术实现
+
+### 架构设计
+
+```typescript
+// AG-UI服务层
+AGUIService
+├── 事件管理 (EventSubject)
+├── 状态管理 (StateSubject)
+├── 智能体连接
+└── 消息处理
+
+// React组件层
+AGUIChat
+├── 消息状态管理
+├── 事件订阅处理
+├── UI渲染逻辑
+└── 用户交互处理
+```
+
+### 关键组件
+
+1. **AGUIService**: 核心服务类，处理AG-UI协议通信
+2. **AGUIChat**: React聊天组件，提供用户界面
+3. **事件处理器**: 处理不同类型的AG-UI事件
+4. **状态管理**: 管理连接状态和处理状态
+
+### 数据流
+
+```
+用户输入 → AGUIChat → AGUIService → 智能体
+智能体 → AG-UI事件流 → AGUIService → AGUIChat → UI更新
+```
+
+## 使用方式
+
+### 基本用法
+
+```tsx
+import AGUIChat from '../components/AGUIChat'
+
+<AGUIChat
+  project={project}
+  models={models}
+  onMaterialCreated={() => loadProjectMaterials(project)}
+/>
+```
+
+### 配置选项
+
+- `project`: 当前项目信息
+- `models`: 可用模特列表
+- `onMaterialCreated`: 素材创建完成回调
+
+## 页面布局
+
+### 项目详情页面布局
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    顶部导航栏                              │
+├─────────────────┬───────────────────────────────────────┤
+│                 │                                       │
+│   AG-UI聊天     │         项目素材管理                    │
+│   (左侧面板)     │         (主要区域)                     │
+│                 │                                       │
+│   • 智能对话     │   • 搜索功能                           │
+│   • 实时状态     │   • 筛选器                             │
+│   • 进度显示     │   • 素材网格                           │
+│   • 工具调用     │   • 预览功能                           │
+│                 │                                       │
+└─────────────────┴───────────────────────────────────────┘
+```
+
+## 特色功能
+
+### 1. 实时协作
+- 人在回路中的工作流
+- 实时状态同步
+- 智能建议和指导
+
+### 2. 可视化反馈
+- 进度条显示处理进度
+- 工具调用可视化
+- 思考状态动画
+
+### 3. 上下文感知
+- 项目信息自动传递
+- 模特信息智能匹配
+- 历史对话上下文
+
+### 4. 错误处理
+- 连接失败自动重试
+- 友好的错误提示
+- 状态恢复机制
+
+## 扩展性
+
+### 自定义智能体
+- 支持添加新的智能体类型
+- 可配置智能体能力
+- 灵活的端点配置
+
+### 事件扩展
+- 支持自定义事件类型
+- 可扩展的事件处理器
+- 插件化架构
+
+### UI定制
+- 主题定制支持
+- 组件样式覆盖
+- 布局灵活配置
+
+## 最佳实践
+
+1. **性能优化**: 使用React.memo和useCallback优化渲染
+2. **错误边界**: 实现错误边界组件保护应用稳定性
+3. **状态管理**: 合理使用本地状态和全局状态
+4. **用户体验**: 提供清晰的加载状态和错误反馈
+
+## 未来规划
+
+- [ ] 支持多智能体协作
+- [ ] 语音输入/输出功能
+- [ ] 文件上传和分享
+- [ ] 聊天记录持久化
+- [ ] 智能体插件市场
+- [ ] 高级分析和洞察
+
+## 相关资源
+
+- [AG-UI官方文档](https://ag-ui.com)
+- [AG-UI GitHub仓库](https://github.com/ag-ui-protocol/ag-ui)
+- [CopilotKit集成指南](https://docs.copilotkit.ai)