feat(aia): Complete AIA V2.0 with universal streaming capabilities

Major Updates: - Add StreamingService with OpenAI Compatible format (backend/common/streaming) - Upgrade Chat component V2 with Ant Design X integration - Implement AIA module with 12 intelligent agents - Create AgentHub with 100% prototype V11 restoration - Create ChatWorkspace with streaming response support - Add ThinkingBlock for deep thinking display - Add useAIStream Hook for OpenAI Compatible stream handling Backend Common Capabilities (~400 lines): - OpenAIStreamAdapter: SSE adapter with OpenAI format - StreamingService: unified streaming service - Support content and reasoning_content dual streams - Deep thinking tag processing (<think>...</think>) Frontend Common Capabilities (~2000 lines): - AIStreamChat: modern streaming chat component - ThinkingBlock: collapsible deep thinking display - ConversationList: conversation management with grouping - useAIStream: OpenAI Compatible stream handler Hook - useConversations: conversation state management Hook - Modern design styles (Ultramodern theme) AIA Module Frontend (~1500 lines): - AgentHub: 12 agent cards with timeline design - ChatWorkspace: fullscreen immersive chat interface - AgentCard: theme-colored cards (blue/yellow/teal/purple) - 5 phases, 12 agents configuration - Responsive layout (desktop + mobile) AIA Module Backend (~900 lines): - agentService: 12 agents config with system prompts - conversationService: refactored with StreamingService - attachmentService: file upload skeleton (30k token limit) - 12 API endpoints with authentication - Full CRUD for conversations and messages Documentation: - AIA module status and development guide - Universal capabilities catalog (11 services) - Quick reference card for developers - System overview updates Testing: - Stream response verified (HTTP 200) - Authentication working correctly - Auto conversation creation working - Deep thinking display working - Message input and send working Status: Core features completed (85%), attachment and history loading pending
2026-01-14 19:09:28 +08:00
parent 4ed67a8846
commit 3d35e9c58b
38 changed files with 8448 additions and 335 deletions
--- a/frontend-v2/src/shared/components/Chat/README.md
+++ b/frontend-v2/src/shared/components/Chat/README.md
@@ -1,196 +1,200 @@
-# Chat 通用组件库
+# Chat 通用组件库 V2

-> 基于 **Ant Design X** 构建的 AI 对话通用组件，支持多场景复用
+> 基于 **Ant Design X 2.x** 构建的现代感 AI 对话组件  
+> 支持流式响应、深度思考、会话管理等完整能力
+
+---
+
+## 🆕 V2 新特性
+
+- ✅ **流式响应** - 逐字显示，打字机效果
+- ✅ **深度思考** - ThinkingBlock 组件，可折叠展示
+- ✅ **OpenAI Compatible** - 兼容标准 API 格式
+- ✅ **会话管理** - ConversationList 组件，分组显示
+- ✅ **现代感设计** - 参考 Ant Design X Ultramodern
+
+---

 ## 📚 技术栈

- **@ant-design/x** (2.1.0) - UI 组件（Bubble, Sender）
- **@ant-design/x-sdk** (2.1.0) - 数据流管理（可选）
+- **@ant-design/x** (2.1.0+) - UI 组件（Bubble, Sender, Welcome, Prompts, Think）
 - **React 19** + **TypeScript 5**
- **Prism.js** - 代码语法高亮
-
---
-
-## ✨ 特性
-
- ✅ **多场景支持**：AIA、PKB（个人知识库）、Tool C 等
- ✅ **开箱即用**：基于 Ant Design X，无需复杂配置
- ✅ **类型安全**：完整的 TypeScript 类型定义
- ✅ **高度可定制**：支持自定义消息渲染、样式配置
- ✅ **代码执行**：Tool C 专用，支持代码块展示和执行
-
---
-
-## 📦 安装
-
-组件已内置在项目中，无需额外安装。如需单独使用，确保安装以下依赖：
-
-```bash
-npm install @ant-design/x @ant-design/x-sdk prismjs
-```
+- **OpenAI Compatible API** - 标准流式格式

 ---

 ## 🚀 快速开始

-### 基础用法
+### 流式对话（推荐）

-```typescript
-import { ChatContainer } from '@/shared/components/Chat';
+```tsx
+import { AIStreamChat } from '@/shared/components/Chat';

-<ChatContainer
-  conversationType="aia"
-  providerConfig={{
-    apiEndpoint: '/api/chat',
+<AIStreamChat
+  apiEndpoint="/api/v1/aia/conversations/xxx/messages/stream"
+  headers={{ Authorization: `Bearer ${token}` }}
+  conversationId="xxx"
+  agentId="general"
+  enableDeepThinking={true}
+  welcome={{
+    title: 'AI 智能助手',
+    description: '有什么可以帮您的？',
+    prompts: [
+      { key: '1', label: '帮我分析数据', icon: '📊' },
+      { key: '2', label: '写一份报告', icon: '📝' },
+    ],
  }}
 />
 ```

-### Tool C 集成（完整示例）
+### 带会话列表的完整布局

-```typescript
-import { ChatContainer, MessageRenderer } from '@/shared/components/Chat';
+```tsx
+import { AIStreamChat, ConversationList, useConversations } from '@/shared/components/Chat';

-<ChatContainer
-  conversationType="tool-c"
-  conversationKey={sessionId}
-  providerConfig={{
-    apiEndpoint: `/api/dc/tool-c/process`,
-    requestFn: async (message: string) => {
-      const response = await fetch(`/api/dc/tool-c/process`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sessionId, userMessage: message }),
-      });
-      return await response.json();
-    },
-  }}
-  customMessageRenderer={(msgInfo) => (
-    <MessageRenderer
-      messageInfo={msgInfo}
-      onExecuteCode={handleExecuteCode}
-      isExecuting={isExecuting}
-    />
-  )}
-  onMessageReceived={(msg) => {
-    if (msg.metadata?.newDataPreview) {
-      updateDataGrid(msg.metadata.newDataPreview);
-    }
-  }}
-/>
+function ChatPage() {
+  const {
+    groupedConversations,
+    currentId,
+    setCurrent,
+    addConversation,
+    deleteConversation,
+  } = useConversations();
+
+  return (
+    <div style={{ display: 'flex', height: '100vh' }}>
+      {/* 左侧会话列表 */}
+      <ConversationList
+        groups={groupedConversations}
+        currentId={currentId}
+        onSelect={setCurrent}
+        onNew={() => addConversation({ title: '新对话' })}
+        onDelete={deleteConversation}
+        title="AI 助手"
+      />
+      
+      {/* 右侧对话区域 */}
+      <div style={{ flex: 1 }}>
+        <AIStreamChat
+          apiEndpoint={`/api/v1/aia/conversations/${currentId}/messages/stream`}
+          conversationId={currentId}
+          enableDeepThinking={true}
+        />
+      </div>
+    </div>
+  );
+}
 ```

 ---

 ## 📖 API 文档

-### ChatContainer Props
+### AIStreamChat Props

 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `conversationType` | `ConversationType` | ✅ | - | 对话类型（'aia' \| 'pkb' \| 'tool-c'） |
-| `conversationKey` | `string` | ❌ | - | 会话 ID（用于多会话管理） |
-| `providerConfig` | `ChatProviderConfig` | ✅ | - | API 配置 |
-| `defaultMessages` | `ChatMessage[]` | ❌ | `[]` | 初始消息列表 |
-| `customMessageRenderer` | `Function` | ❌ | - | 自定义消息渲染器 |
-| `senderProps` | `SenderProps` | ❌ | `{}` | Sender 组件配置 |
+| `apiEndpoint` | `string` | ✅ | - | API 端点（需支持 OpenAI Compatible 格式） |
+| `headers` | `Record<string, string>` | ❌ | `{}` | 请求头（如 Authorization） |
+| `conversationId` | `string` | ❌ | - | 会话 ID |
+| `agentId` | `string` | ❌ | - | 智能体 ID |
+| `enableDeepThinking` | `boolean` | ❌ | `false` | 是否启用深度思考 |
+| `welcome` | `WelcomeConfig` | ❌ | - | 欢迎页配置 |
+| `prompts` | `PromptItem[]` | ❌ | `[]` | 快捷提示列表 |
+| `enableAttachment` | `boolean` | ❌ | `false` | 是否支持附件上传 |
+| `placeholder` | `string` | ❌ | `'输入消息...'` | 输入框占位文本 |
 | `onMessageSent` | `Function` | ❌ | - | 消息发送回调 |
 | `onMessageReceived` | `Function` | ❌ | - | 消息接收回调 |
 | `onError` | `Function` | ❌ | - | 错误回调 |

-### ChatProviderConfig
+### ThinkingBlock Props

-```typescript
-interface ChatProviderConfig {
-  apiEndpoint: string;                    // API 端点
-  method?: 'GET' | 'POST';                // 请求方法
-  headers?: Record<string, string>;       // 请求头
-  requestFn?: (message: string, context?: any) => Promise<any>;  // 自定义请求函数
-}
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `content` | `string` | ✅ | - | 思考内容 |
+| `isThinking` | `boolean` | ❌ | `false` | 是否正在思考 |
+| `duration` | `number` | ❌ | - | 思考耗时（秒） |
+| `defaultExpanded` | `boolean` | ❌ | `false` | 默认是否展开 |
+
+### ConversationList Props
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `groups` | `ConversationGroup[]` | ✅ | - | 分组会话列表 |
+| `currentId` | `string \| null` | ✅ | - | 当前会话 ID |
+| `onSelect` | `Function` | ✅ | - | 会话点击回调 |
+| `onNew` | `Function` | ✅ | - | 新建会话回调 |
+| `onDelete` | `Function` | ❌ | - | 删除会话回调 |
+| `title` | `string` | ❌ | `'AI 助手'` | 标题 |
+| `logo` | `ReactNode` | ❌ | - | Logo |
+
+---
+
+## 🎣 Hooks
+
+### useAIStream
+
+处理 OpenAI Compatible 格式的流式响应。
+
+```tsx
+import { useAIStream } from '@/shared/components/Chat';
+
+const {
+  content,      // 当前内容
+  thinking,     // 思考内容
+  status,       // 流式状态
+  isStreaming,  // 是否正在流式输出
+  isThinking,   // 是否正在思考
+  error,        // 错误信息
+  sendMessage,  // 发送消息
+  abort,        // 中断请求
+  reset,        // 重置状态
+} = useAIStream({
+  apiEndpoint: '/api/v1/aia/chat/stream',
+  headers: { Authorization: `Bearer ${token}` },
+});
 ```

-### ChatMessage
+### useConversations

-```typescript
-interface ChatMessage {
-  id: string | number;
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  status?: 'local' | 'loading' | 'success' | 'error';
-  code?: string;              // Tool C 专用
-  explanation?: string;       // Tool C 专用
-  timestamp?: number;
-  metadata?: Record<string, any>;
-}
+管理多会话状态。
+
+```tsx
+import { useConversations } from '@/shared/components/Chat';
+
+const {
+  conversations,         // 会话列表
+  groupedConversations,  // 分组会话
+  current,               // 当前会话
+  currentId,             // 当前会话 ID
+  setCurrent,            // 设置当前会话
+  addConversation,       // 添加会话
+  updateConversation,    // 更新会话
+  deleteConversation,    // 删除会话
+} = useConversations();
 ```

 ---

-## 🎨 自定义渲染
+## 🔌 后端 API 格式

-### MessageRenderer（默认渲染器）
+### OpenAI Compatible SSE 格式

-```typescript
-import { MessageRenderer } from '@/shared/components/Chat';
+后端需要输出以下格式的 SSE 流：

-<MessageRenderer
-  messageInfo={msgInfo}
-  onExecuteCode={(code) => console.log('Execute:', code)}
-  isExecuting={false}
-/>
+```
+data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}\n\n
+data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"让我思考一下..."}}]}\n\n
+data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"好的，"}}]}\n\n
+data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"我来帮您..."}}]}\n\n
+data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}\n\n
+data: [DONE]\n\n
 ```

-### CodeBlockRenderer（代码块渲染器）
-
-```typescript
-import { CodeBlockRenderer } from '@/shared/components/Chat';
-
-<CodeBlockRenderer
-  code="df['age'].fillna(df['age'].mean(), inplace=True)"
-  language="python"
-  onExecute={handleExecute}
-  isExecuting={false}
-  executionResult={{ success: true }}
-/>
-```
-
---
-
-## 🔧 高级用法
-
-### 自定义消息渲染
-
-```typescript
-<ChatContainer
-  conversationType="custom"
-  providerConfig={{ apiEndpoint: '/api/custom' }}
-  customMessageRenderer={(msgInfo) => {
-    const msg = msgInfo.message;
-    return (
-      <div>
-        <strong>{msg.role}:</strong> {msg.content}
-        {msg.code && <pre>{msg.code}</pre>}
-      </div>
-    );
-  }}
-/>
-```
-
-### 处理后端响应
-
-后端 API 应返回以下格式：
-
-```json
-{
-  "messageId": "xxx",
-  "explanation": "好的，我将帮您...",
-  "code": "df['sex'].fillna(df['sex'].mode()[0], inplace=True)",
-  "success": true,
-  "metadata": {
-    "newDataPreview": [...]
-  }
-}
-```
+关键字段：
+- `choices[0].delta.content` - 正文内容
+- `choices[0].delta.reasoning_content` - 深度思考内容（DeepSeek 风格）
+- `choices[0].finish_reason` - 完成原因

 ---

@@ -198,99 +202,49 @@ import { CodeBlockRenderer } from '@/shared/components/Chat';

 ```
 shared/components/Chat/
-├── types.ts                 # TypeScript 类型定义
-├── ChatContainer.tsx        # 核心容器组件
-├── MessageRenderer.tsx      # 默认消息渲染器
-├── CodeBlockRenderer.tsx    # 代码块渲染器
+├── index.ts                    # 统一导出
+├── types.ts                    # 类型定义
+├── AIStreamChat.tsx            # 🆕 流式对话组件（推荐）
+├── ThinkingBlock.tsx           # 🆕 深度思考展示
+├── ConversationList.tsx        # 🆕 会话列表
+├── ChatContainer.tsx           # 传统对话容器（向后兼容）
+├── MessageRenderer.tsx         # 消息渲染器
+├── CodeBlockRenderer.tsx       # 代码块渲染器
+├── hooks/
+│   ├── index.ts
+│   ├── useAIStream.ts          # 🆕 流式响应 Hook
+│   └── useConversations.ts     # 🆕 会话管理 Hook
 ├── styles/
-│   └── chat.css            # 样式文件
-├── index.ts                # 统一导出
-└── README.md               # 本文档
+│   ├── chat.css                # 传统样式
+│   ├── ai-stream-chat.css      # 🆕 流式对话样式
+│   ├── thinking.css            # 🆕 深度思考样式
+│   └── conversation-list.css   # 🆕 会话列表样式
+└── README.md                   # 本文档
 ```

 ---

-## 🎯 使用场景
+## 🎨 设计风格

-### 1. AIA（AI智能问答）
+采用**现代感设计**（参考 Ant Design X Ultramodern）：

-```typescript
-<ChatContainer
-  conversationType="aia"
-  providerConfig={{
-    apiEndpoint: '/api/aia/chat',
-  }}
-/>
-```
-
-### 2. PKB（个人知识库）
-
-```typescript
-<ChatContainer
-  conversationType="pkb"
-  conversationKey={knowledgeBaseId}
-  providerConfig={{
-    apiEndpoint: '/api/pkb/query',
-  }}
-/>
-```
-
-### 3. Tool C（数据清洗）
-
-```typescript
-<ChatContainer
-  conversationType="tool-c"
-  conversationKey={sessionId}
-  providerConfig={{
-    apiEndpoint: '/api/dc/tool-c/process',
-  }}
-  customMessageRenderer={(msgInfo) => (
-    <MessageRenderer
-      messageInfo={msgInfo}
-      onExecuteCode={handleExecuteCode}
-    />
-  )}
-/>
-```
-
---
-
-## 🐛 常见问题
-
-### Q1: 如何自定义样式？
-
-通过 `className` 和 `style` 属性：
-
-```typescript
-<ChatContainer
-  className="my-custom-chat"
-  style={{ height: '600px' }}
-  // ...
-/>
-```
-
-或修改 `styles/chat.css`。
-
-### Q2: 如何处理流式响应？
-
-当前版本暂不支持流式响应，计划在后续版本中支持。
-
-### Q3: 如何添加新的对话类型？
-
-1. 在 `types.ts` 中扩展 `ConversationType`
-2. 根据需要自定义 `customMessageRenderer`
+- **配色**：主色 Indigo (#6366f1)，思考色 Violet (#a78bfa)
+- **圆角**：大圆角 12-16px
+- **阴影**：柔和阴影，层次分明
+- **动画**：流畅过渡，微交互
+- **布局**：清爽简洁，留白适度

 ---

 ## 📝 开发记录

- **2025-12-07**: 初始版本，基于 Ant Design X 2.1.0 重构
- 完整开发记录：`docs/03-业务模块/DC-数据清洗整理/06-开发记录/`
+- **2025-01-14**: V2 版本发布，新增流式响应、深度思考、会话管理
+- **2025-12-07**: V1 初始版本，基于 Ant Design X 2.1.0 构建

 ---

 ## 📚 参考资料

 - [Ant Design X 官方文档](https://x.ant.design)
- [Ant Design X SDK 文档](https://x.ant.design/x-sdks/introduce-cn)
- [项目架构文档](../../../docs/00-系统总体设计/)
+- [Ant Design X Ultramodern Playground](https://x.ant.design/docs/playground/ultramodern-cn)
+- [OpenAI API 流式响应格式](https://platform.openai.com/docs/api-reference/chat/streaming)