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 - 标准流式格式

---

🚀 快速开始

流式对话（推荐）

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: '📝' },
    ],
  }}
/>

带会话列表的完整布局

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 格式的流式响应。

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

管理多会话状态。

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 官方文档
• Ant Design X Ultramodern Playground
• OpenAI API 流式响应格式