AIclinicalresearch/frontend-v2/src/shared/components/Chat/README.md

# Chat 通用组件库 V2

> 基于 **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, Welcome, Prompts, Think）
- **React 19** + **TypeScript 5**
- **OpenAI Compatible API** - 标准流式格式

---

## 🚀 快速开始

### 流式对话（推荐）

```tsx
import { AIStreamChat } from '@/shared/components/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: '📝' },
    ],
  }}
/>
```

### 带会话列表的完整布局

```tsx
import { AIStreamChat, ConversationList, useConversations } from '@/shared/components/Chat';

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 文档

### AIStreamChat Props

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `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` | ❌ | - | 错误回调 |

### ThinkingBlock Props

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `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}` },
});
```

### useConversations

管理多会话状态。

```tsx
import { useConversations } from '@/shared/components/Chat';

const {
  conversations,         // 会话列表
  groupedConversations,  // 分组会话
  current,               // 当前会话
  currentId,             // 当前会话 ID
  setCurrent,            // 设置当前会话
  addConversation,       // 添加会话
  updateConversation,    // 更新会话
  deleteConversation,    // 删除会话
} = useConversations();
```

---

## 🔌 后端 API 格式

### OpenAI Compatible SSE 格式

后端需要输出以下格式的 SSE 流：

```
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
```

关键字段：
- `choices[0].delta.content` - 正文内容
- `choices[0].delta.reasoning_content` - 深度思考内容（DeepSeek 风格）
- `choices[0].finish_reason` - 完成原因

---

## 📁 文件结构

```
shared/components/Chat/
├── 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                # 传统样式
│   ├── ai-stream-chat.css      # 🆕 流式对话样式
│   ├── thinking.css            # 🆕 深度思考样式
│   └── conversation-list.css   # 🆕 会话列表样式
└── README.md                   # 本文档
```

---

## 🎨 设计风格

采用**现代感设计**（参考 Ant Design X Ultramodern）：

- **配色**：主色 Indigo (#6366f1)，思考色 Violet (#a78bfa)
- **圆角**：大圆角 12-16px
- **阴影**：柔和阴影，层次分明
- **动画**：流畅过渡，微交互
- **布局**：清爽简洁，留白适度

---

## 📝 开发记录

- **2025-01-14**: V2 版本发布，新增流式响应、深度思考、会话管理
- **2025-12-07**: V1 初始版本，基于 Ant Design X 2.1.0 构建

---

## 📚 参考资料

- [Ant Design X 官方文档](https://x.ant.design)
- [Ant Design X Ultramodern Playground](https://x.ant.design/docs/playground/ultramodern-cn)
- [OpenAI API 流式响应格式](https://platform.openai.com/docs/api-reference/chat/streaming)