HaHafeng
303dd78c54
- Add one-click research protocol generation with streaming output - Implement Word document export via Pandoc integration - Add dynamic dual-panel layout with resizable split pane - Implement collapsible content for StatePanel stages - Add conversation history management with title auto-update - Fix scroll behavior, markdown rendering, and UI layout issues - Simplify conversation creation logic for reliability
739 lines
21 KiB
Markdown
739 lines
21 KiB
Markdown
# AIA AI智能问答模块 - 当前状态与开发指南
|
||
|
||
> **文档版本：** v3.1
|
||
> **创建日期：** 2026-01-14
|
||
> **维护者：** AIA模块开发团队
|
||
> **最后更新：** 2026-01-25 🎉 **V3.1版本发布 - Protocol Agent MVP完整交付**
|
||
> **重大里程碑：**
|
||
> - 🏆 通用流式响应服务（OpenAI Compatible）
|
||
> - 🎨 现代感UI（100%还原原型图V11）
|
||
> - 🚀 Ant Design X 深度集成
|
||
> - ✨ 12个智能体配置完成
|
||
> - 🆕 Prompt管理系统集成（灰度预览、版本管理）
|
||
> - 🎉 **Protocol Agent MVP完整交付（一键生成研究方案+Word导出）**
|
||
|
||
---
|
||
|
||
## 📋 文档说明
|
||
|
||
本文档记录AIA模块的真实开发状态、架构设计和使用指南。
|
||
|
||
**与其他文档的关系：**
|
||
- **本文档（00-模块当前状态）**：What is（真实状态）
|
||
- **需求分析（PRD）**：What to do（产品需求）
|
||
- **开发计划**：How to do（实施路径）
|
||
- **原型图**：UI设计参考
|
||
|
||
---
|
||
|
||
## 🎯 模块概述
|
||
|
||
### 核心功能
|
||
|
||
AIA（AI Intelligent Assistant）模块提供覆盖临床研究全生命周期的12个智能体：
|
||
|
||
| 阶段 | 智能体 | 数量 | 主题色 |
|
||
|------|--------|------|--------|
|
||
| **Phase 1: 选题优化** | 科学问题梳理、PICO梳理、选题评价 | 3 | 蓝色 #4F6EF2 |
|
||
| **Phase 2: 方案设计** | 观察指标设计、CRF设计、样本量计算、方案撰写 | 4 | 蓝色 #4F6EF2 |
|
||
| **Phase 3: 方案预评审** | 方法学评审 | 1 | 黄色 #CA8A04 |
|
||
| **Phase 4: 数据与统计** | 数据预处理、统计分析（工具类，跳转DC） | 2 | 青色 #0D9488 |
|
||
| **Phase 5: 写作助手** | 论文润色、论文翻译 | 2 | 紫色 #9333EA |
|
||
|
||
### 当前状态
|
||
|
||
- **开发阶段：** 🎉 **V3.1 Protocol Agent MVP完整交付**
|
||
- **架构版本：** V3.1（通用Agent框架 + Protocol Agent + 一键生成）
|
||
- **完成度：** 90%（MVP完整可用，待生产测试）
|
||
|
||
### ✅ V2.1 新增功能（2026-01-18）
|
||
|
||
**Prompt 管理系统集成**
|
||
- [x] 10 个智能体 Prompt 迁移到数据库
|
||
- [x] 支持在管理端在线编辑和调试
|
||
- [x] 灰度预览（调试者看 DRAFT，普通用户看 ACTIVE）
|
||
- [x] 三级容灾（数据库 → 缓存 → 兜底）
|
||
- [x] 版本管理和回滚
|
||
|
||
**Prompt Code 映射表**
|
||
|
||
| 智能体 | Prompt Code |
|
||
|--------|-------------|
|
||
| 科学问题梳理 | `AIA_SCIENTIFIC_QUESTION` |
|
||
| PICO 梳理 | `AIA_PICO_ANALYSIS` |
|
||
| 选题评价 | `AIA_TOPIC_EVALUATION` |
|
||
| 观察指标设计 | `AIA_OUTCOME_DESIGN` |
|
||
| 病例报告表设计 | `AIA_CRF_DESIGN` |
|
||
| 样本量计算 | `AIA_SAMPLE_SIZE` |
|
||
| 临床研究方案撰写 | `AIA_PROTOCOL_WRITING` |
|
||
| 方法学评审智能体 | `AIA_METHODOLOGY_REVIEW` |
|
||
| 论文润色 | `AIA_PAPER_POLISH` |
|
||
| 论文翻译 | `AIA_PAPER_TRANSLATE` |
|
||
|
||
---
|
||
|
||
### ✅ V3.0 Protocol Agent MVP（2026-01-24）
|
||
|
||
**通用Agent框架:**
|
||
- [x] 5层架构完整实现：Query→Planner→Executor→Tools→Reflection
|
||
- [x] ConfigLoader, BaseAgentOrchestrator, QueryAnalyzer, StageManager, TraceLogger
|
||
- [x] agent_schema: 6张表，protocol_schema: 2张表
|
||
- [x] 完整类型定义（382行）
|
||
|
||
**Protocol Agent:**
|
||
- [x] 后端：6个核心服务，6个API端点，10/10测试通过
|
||
- [x] 前端：三栏布局，5阶段状态面板，100%还原原型图
|
||
- [x] 5阶段流程：科学问题→PICO→研究设计→样本量→观察指标
|
||
|
||
---
|
||
|
||
### 🎉 V3.1 Protocol Agent 完整交付（2026-01-25）
|
||
|
||
**一键生成研究方案:**
|
||
- [x] 动态双面板布局（ResizableSplitPane，可拖拽调整）
|
||
- [x] 视图切换（研究摘要 / 完整方案）
|
||
- [x] A4 纸张预览效果（DocumentPanel）
|
||
- [x] 流式生成 + Markdown 渲染 + 滚动跟随
|
||
- [x] 12章节完整临床研究方案结构
|
||
|
||
**Word 文档导出:**
|
||
- [x] Python 微服务（pypandoc + Pandoc）
|
||
- [x] Node.js API 端点（/export/docx）
|
||
- [x] 前端一键下载
|
||
|
||
**用户体验优化:**
|
||
- [x] StatePanel 折叠/展开（CollapsibleContent）
|
||
- [x] 科学问题/PICO/样本量/观察指标完整显示
|
||
- [x] 延迟创建对话（避免空记录）
|
||
- [x] 对话标题自动更新
|
||
- [x] Prompt 工程优化（阶段约束、数据凝练放宽）
|
||
|
||
**Bug 修复:**
|
||
- [x] 滚动条显示问题（flex min-height: 0）
|
||
- [x] 模型阶段混乱问题（Prompt 增强）
|
||
- [x] 数据类型错误（toArray 辅助函数）
|
||
- [x] 顶部标题两行、欢迎语过大、列表编号错误
|
||
|
||
**代码统计:**
|
||
- 前端新增：~1,200行（累计~3,300行）
|
||
- 后端新增：~400行（累计~4,700行）
|
||
- Python新增：~110行
|
||
- **总计：~8,500行**
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### V3 架构特点
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 前端 (React 19) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ AIA 业务模块 │
|
||
│ ├── AgentHub (智能体大厅) │
|
||
│ ├── ChatWorkspace (对话工作台) │
|
||
│ └── 12个智能体配置 │
|
||
│ │
|
||
│ 通用能力层 (Capability Layer) │
|
||
│ ├── AIStreamChat (流式对话组件) │
|
||
│ ├── ThinkingBlock (深度思考展示) │
|
||
│ ├── ConversationList (会话管理) │
|
||
│ └── useAIStream Hook (流式响应处理) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓ OpenAI Compatible SSE
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 后端 (Fastify + Prisma) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ AIA 业务模块 │
|
||
│ ├── agentService (智能体配置) │
|
||
│ ├── conversationService (对话管理) │
|
||
│ └── attachmentService (附件处理) │
|
||
│ │
|
||
│ 通用能力层 (Common Services) │
|
||
│ ├── StreamingService (OpenAI Compatible流式输出) │
|
||
│ ├── LLMFactory (统一LLM网关) │
|
||
│ ├── Storage (存储抽象层) │
|
||
│ └── Logger (结构化日志) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心创新
|
||
|
||
1. **OpenAI Compatible 流式响应**
|
||
- 统一标准格式，兼容业界主流
|
||
- 支持 `content` 和 `reasoning_content` 双流
|
||
- 前端 `useAIStream` Hook 自动解析
|
||
|
||
2. **现代感UI设计**
|
||
- 100%还原原型图V11
|
||
- Ant Design X 深度集成
|
||
- 响应式布局（桌面+移动）
|
||
|
||
3. **通用能力复用**
|
||
- 前端 Chat 组件可复用于所有AI对话场景
|
||
- 后端 StreamingService 可复用于所有流式输出
|
||
|
||
---
|
||
|
||
## 📂 文件结构
|
||
|
||
### 前端
|
||
|
||
```
|
||
frontend-v2/src/modules/aia/
|
||
├── index.tsx # 模块入口（视图路由）
|
||
├── types.ts # 类型定义
|
||
├── constants.ts # 12个智能体配置
|
||
├── components/
|
||
│ ├── AgentHub.tsx # 智能体大厅
|
||
│ ├── AgentCard.tsx # 智能体卡片
|
||
│ └── ChatWorkspace.tsx # 对话工作台
|
||
└── styles/
|
||
├── agent-hub.css # 大厅样式
|
||
├── agent-card.css # 卡片样式
|
||
└── chat-workspace.css # 工作台样式
|
||
```
|
||
|
||
### 后端
|
||
|
||
```
|
||
backend/src/modules/aia/
|
||
├── index.ts # 模块入口
|
||
├── types/index.ts # 类型定义
|
||
├── services/
|
||
│ ├── agentService.ts # 智能体配置服务
|
||
│ ├── conversationService.ts # 对话服务
|
||
│ └── attachmentService.ts # 附件处理服务
|
||
├── controllers/
|
||
│ ├── agentController.ts # 智能体控制器
|
||
│ └── conversationController.ts # 对话控制器
|
||
└── routes/index.ts # 路由定义
|
||
```
|
||
|
||
### 通用能力层
|
||
|
||
```
|
||
backend/src/common/streaming/ # 🆕 流式响应服务
|
||
├── types.ts
|
||
├── OpenAIStreamAdapter.ts
|
||
├── StreamingService.ts
|
||
└── index.ts
|
||
|
||
frontend-v2/src/shared/components/Chat/ # 🆕 Chat组件V2
|
||
├── AIStreamChat.tsx # 流式对话组件
|
||
├── ThinkingBlock.tsx # 深度思考组件
|
||
├── ConversationList.tsx # 会话列表组件
|
||
├── hooks/
|
||
│ ├── useAIStream.ts # 流式响应Hook
|
||
│ └── useConversations.ts # 会话管理Hook
|
||
└── styles/ # 现代感样式
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄️ 数据库设计
|
||
|
||
### Schema: `aia_schema`
|
||
|
||
#### 1. `conversations` - 对话表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | UUID | 主键 |
|
||
| `user_id` | UUID | 用户ID |
|
||
| `project_id` | UUID? | 项目ID（可选） |
|
||
| `agent_id` | VARCHAR(50) | 智能体ID |
|
||
| `title` | VARCHAR(200) | 对话标题 |
|
||
| `model_name` | VARCHAR(50)? | 使用的模型 |
|
||
| `message_count` | INT | 消息数量 |
|
||
| `total_tokens` | INT | 总Token数 |
|
||
| `metadata` | JSONB? | 元数据 |
|
||
| `created_at` | TIMESTAMP | 创建时间 |
|
||
| `updated_at` | TIMESTAMP | 更新时间 |
|
||
|
||
#### 2. `messages` - 消息表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | UUID | 主键 |
|
||
| `conversation_id` | UUID | 对话ID（外键） |
|
||
| `role` | VARCHAR(20) | 角色（user/assistant） |
|
||
| `content` | TEXT | 消息内容 |
|
||
| `thinking_content` | TEXT? | 🆕 深度思考内容 |
|
||
| `attachments` | JSONB? | 🆕 附件列表 |
|
||
| `model` | VARCHAR(50)? | 使用的模型 |
|
||
| `tokens` | INT? | Token数量 |
|
||
| `created_at` | TIMESTAMP | 创建时间 |
|
||
|
||
---
|
||
|
||
## 🔌 API 端点
|
||
|
||
### 智能体管理
|
||
|
||
| 方法 | 端点 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/v1/aia/agents` | ❌ | 获取智能体列表 |
|
||
| GET | `/api/v1/aia/agents/:id` | ❌ | 获取智能体详情 |
|
||
| POST | `/api/v1/aia/intent/route` | ✅ | 意图路由 |
|
||
|
||
### 对话管理
|
||
|
||
| 方法 | 端点 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/v1/aia/conversations` | ✅ | 获取对话列表 |
|
||
| POST | `/api/v1/aia/conversations` | ✅ | 创建对话 |
|
||
| GET | `/api/v1/aia/conversations/:id` | ✅ | 获取对话详情 |
|
||
| DELETE | `/api/v1/aia/conversations/:id` | ✅ | 删除对话 |
|
||
|
||
### 消息发送
|
||
|
||
| 方法 | 端点 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| POST | `/api/v1/aia/conversations/:id/messages/stream` | ✅ | 流式发送消息 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前端使用
|
||
|
||
```tsx
|
||
// 1. 访问模块入口
|
||
import AIAModule from '@/modules/aia';
|
||
|
||
// 路由配置
|
||
<Route path="/aia" element={<AIAModule />} />
|
||
|
||
// 2. 直接使用通用组件
|
||
import { AIStreamChat } from '@/shared/components/Chat';
|
||
|
||
<AIStreamChat
|
||
apiEndpoint="/api/v1/aia/conversations/xxx/messages/stream"
|
||
conversationId="xxx"
|
||
agentId="TOPIC_01"
|
||
enableDeepThinking={true}
|
||
/>
|
||
```
|
||
|
||
### 后端使用
|
||
|
||
```typescript
|
||
// 1. 使用通用 StreamingService
|
||
import { createStreamingService } from '../../../common/streaming';
|
||
|
||
const service = createStreamingService(reply, {
|
||
model: 'deepseek-v3',
|
||
enableDeepThinking: true,
|
||
});
|
||
|
||
await service.streamGenerate(messages);
|
||
|
||
// 2. 智能体配置
|
||
import * as agentService from './services/agentService';
|
||
|
||
const agent = await agentService.getAgentById('TOPIC_01');
|
||
const systemPrompt = await agentService.getAgentSystemPrompt('TOPIC_01');
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 已完成功能
|
||
|
||
### 前端（100%）
|
||
|
||
- ✅ **AgentHub 主界面**
|
||
- 12个智能体卡片
|
||
- 时间轴设计（5个阶段）
|
||
- 100%还原原型图V11
|
||
- 响应式布局
|
||
|
||
- ✅ **ChatWorkspace 对话工作台**
|
||
- 全屏沉浸式体验
|
||
- 左侧会话列表（可折叠）
|
||
- 欢迎语（左上角单行）
|
||
- 深度思考按钮
|
||
- 附件上传按钮
|
||
- 自动创建对话
|
||
|
||
- ✅ **流式响应集成**
|
||
- useAIStream Hook
|
||
- 逐字显示（打字机效果）
|
||
- 深度思考展示（ThinkingBlock）
|
||
- 实时状态管理
|
||
|
||
### 后端（100%）
|
||
|
||
- ✅ **智能体服务**
|
||
- 12个智能体配置
|
||
- 系统提示词管理
|
||
- 欢迎语配置
|
||
- 意图路由（简单版）
|
||
|
||
- ✅ **对话服务**
|
||
- CRUD 完整实现
|
||
- 流式消息发送
|
||
- OpenAI Compatible 输出
|
||
- 深度思考标签处理
|
||
|
||
- ✅ **通用能力集成**
|
||
- StreamingService 流式响应
|
||
- LLMFactory 模型调用
|
||
- Cache 缓存服务
|
||
- Logger 结构化日志
|
||
- Storage 存储抽象
|
||
|
||
- ✅ **认证授权**
|
||
- authenticate 中间件
|
||
- getUserId() 辅助函数
|
||
- 完全符合认证规范
|
||
|
||
---
|
||
|
||
## 🚧 待开发功能
|
||
|
||
### 高优先级
|
||
|
||
- [ ] **附件功能完善**
|
||
- 附件上传 API
|
||
- 文档内容提取（对接文档处理引擎）
|
||
- Token 截断控制（30k上限）
|
||
|
||
- [ ] **历史消息加载**
|
||
- 切换对话时加载历史
|
||
- 分页加载（50条/页）
|
||
- 上下文滚动
|
||
|
||
- [ ] **智能体优化**
|
||
- 对接 Prompt 管理系统
|
||
- 动态配置加载
|
||
- 知识库集成（RAG）
|
||
|
||
### 中优先级
|
||
|
||
- [ ] **高级功能**
|
||
- 对话导出（Markdown/PDF）
|
||
- 消息编辑
|
||
- 消息重新生成
|
||
- 多模型切换
|
||
|
||
- [ ] **移动端优化**
|
||
- 侧边栏抽屉优化
|
||
- 输入框体验优化
|
||
- 手势交互
|
||
|
||
### 低优先级
|
||
|
||
- [ ] **个性化配置**
|
||
- 主题色切换
|
||
- 字体大小调整
|
||
- 快捷键配置
|
||
|
||
---
|
||
|
||
## 📊 开发进度
|
||
|
||
### 时间线
|
||
|
||
| 日期 | 里程碑 | 完成内容 |
|
||
|------|--------|----------|
|
||
| 2026-01-14 | V2.0 发布 | 通用能力层架构重构 + 前后端完整实现 |
|
||
| 待定 | V2.1 | 附件功能 + 历史消息 |
|
||
| 待定 | V2.2 | RAG集成 + 高级功能 |
|
||
|
||
### 代码统计
|
||
|
||
| 模块 | 文件数 | 代码行数 | 说明 |
|
||
|------|--------|----------|------|
|
||
| **前端业务** | 10 | ~1,500行 | AgentHub + ChatWorkspace + 样式 |
|
||
| **后端业务** | 9 | ~900行 | Services + Controllers + Routes |
|
||
| **通用能力（前端）** | 12 | ~2,000行 | Chat组件V2 + Hooks + 样式 |
|
||
| **通用能力（后端）** | 4 | ~400行 | StreamingService + OpenAI适配器 |
|
||
| **总计** | 35 | ~4,800行 | 完整的AIA V2实现 |
|
||
|
||
---
|
||
|
||
## 🎨 UI设计规范
|
||
|
||
### 设计原则
|
||
|
||
1. **100%还原原型图** - 尊重设计师的精心打磨
|
||
2. **现代感风格** - 参考 Ant Design X Ultramodern
|
||
3. **沉浸式体验** - 全屏对话，无干扰
|
||
4. **响应式设计** - 桌面端和移动端适配
|
||
|
||
### 关键尺寸
|
||
|
||
| 元素 | 尺寸/样式 |
|
||
|------|-----------|
|
||
| **AgentHub 最大宽度** | 760px |
|
||
| **智能体卡片** | min-height: 145px, padding: 14px, 圆角: 10px |
|
||
| **卡片网格** | 每行3个（Phase 1），每行4个（Phase 2） |
|
||
| **时间轴圆点** | 24px，序号居中 |
|
||
| **欢迎语气泡** | 单行，左上角，灰色卡片 |
|
||
| **输入框** | 圆角16px，聚焦时蓝色边框+阴影 |
|
||
| **侧边栏** | 256px |
|
||
|
||
### 配色方案
|
||
|
||
```css
|
||
--brand-blue: #4F6EF2; /* 主色（Phase 1-2） */
|
||
--brand-yellow: #CA8A04; /* 黄色（Phase 3） */
|
||
--brand-teal: #0D9488; /* 青色（Phase 4，工具） */
|
||
--brand-purple: #9333EA; /* 紫色（Phase 5） */
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 技术栈
|
||
|
||
### 前端
|
||
|
||
- **框架：** React 19 + TypeScript 5
|
||
- **UI 库：** Ant Design X 2.1 + Ant Design 6.0
|
||
- **图标：** Lucide React
|
||
- **状态管理：** React Hooks
|
||
- **样式：** CSS Modules
|
||
|
||
### 后端
|
||
|
||
- **框架：** Fastify v4 + Node.js 22
|
||
- **ORM：** Prisma 6
|
||
- **数据库：** PostgreSQL 16
|
||
- **LLM：** DeepSeek-V3（默认）
|
||
- **日志：** Pino
|
||
|
||
---
|
||
|
||
## 🧪 测试指南
|
||
|
||
### 前端测试
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
cd frontend-v2
|
||
npm run dev
|
||
|
||
# 访问
|
||
http://localhost:5173/aia
|
||
```
|
||
|
||
**测试要点：**
|
||
1. ✅ 12个智能体卡片是否正确显示
|
||
2. ✅ 点击卡片是否能进入对话界面
|
||
3. ✅ 输入框能否正常输入和发送
|
||
4. ✅ 深度思考按钮是否可切换
|
||
5. ✅ 消息是否流式显示
|
||
|
||
### 后端测试
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
cd backend
|
||
npm run dev
|
||
|
||
# 查看日志
|
||
tail -f logs/app.log
|
||
```
|
||
|
||
**API 测试（REST Client）：**
|
||
|
||
```http
|
||
### 1. 获取智能体列表
|
||
GET http://localhost:3000/api/v1/aia/agents
|
||
|
||
### 2. 创建对话（需要登录）
|
||
POST http://localhost:3000/api/v1/aia/conversations
|
||
Authorization: Bearer {{token}}
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"agentId": "TOPIC_01",
|
||
"title": "测试对话"
|
||
}
|
||
|
||
### 3. 流式发送消息
|
||
POST http://localhost:3000/api/v1/aia/conversations/{{conversationId}}/messages/stream
|
||
Authorization: Bearer {{token}}
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"content": "帮我分析一下心血管疾病的研究方向",
|
||
"enableDeepThinking": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 已知问题
|
||
|
||
### 技术债务
|
||
|
||
1. **附件处理未完成**
|
||
- 上传接口待实现
|
||
- 文档提取待对接
|
||
- Token截断待测试
|
||
|
||
2. **历史消息未加载**
|
||
- 切换对话时不加载历史
|
||
- 需要实现分页加载
|
||
|
||
3. **意图路由简化版**
|
||
- 当前仅关键词匹配
|
||
- 后续可接入向量检索
|
||
|
||
### 性能优化点
|
||
|
||
- [ ] 智能体配置缓存（已实现，待测试）
|
||
- [ ] 上下文Token截断（逻辑已预留）
|
||
- [ ] SSE连接保活优化
|
||
|
||
---
|
||
|
||
## 📚 参考文档
|
||
|
||
### 内部文档
|
||
|
||
- [AIA模块PRD](./01-需求分析/AIA模块PRD.md) - 产品需求
|
||
- [原型图V11](./01-需求分析/AI问答原型图V11.html) - UI设计
|
||
- [原型图V2](./01-需求分析/AI智能问答V2.html) - 对话界面
|
||
- [开发计划](./04-开发计划/01-AIA-V2.1开发计划.md) - 实施路径
|
||
- [后端API设计](./04-开发计划/02-后端API设计.md) - 接口文档
|
||
- [前端组件设计](./04-开发计划/03-前端组件设计.md) - 组件设计
|
||
|
||
### 通用能力层
|
||
|
||
- [Chat组件README](../../../frontend-v2/src/shared/components/Chat/README.md)
|
||
- [流式响应服务](../../../backend/src/common/streaming/)
|
||
- [认证规范](../../04-开发规范/10-模块认证规范.md)
|
||
- [云原生规范](../../04-开发规范/08-云原生开发规范.md)
|
||
|
||
### 外部文档
|
||
|
||
- [Ant Design X 官方文档](https://x.ant.design)
|
||
- [OpenAI API 流式响应](https://platform.openai.com/docs/api-reference/chat/streaming)
|
||
|
||
---
|
||
|
||
## 🎓 开发经验
|
||
|
||
### 架构决策
|
||
|
||
1. **为什么重构？**
|
||
- 旧版不符合云原生规范
|
||
- 通用能力未抽象
|
||
- UI体验不符合新设计
|
||
|
||
2. **为什么选择 OpenAI Compatible？**
|
||
- 业界标准，兼容性好
|
||
- Ant Design X 原生支持
|
||
- 便于未来扩展
|
||
|
||
3. **为什么调整后端而非前端？**
|
||
- 前端可复用 Ant Design X 完整能力
|
||
- 后端标准化利于生态集成
|
||
- 减少重复造轮子
|
||
|
||
### 最佳实践
|
||
|
||
- ✅ 通用能力层优先复用
|
||
- ✅ 100%还原原型图设计
|
||
- ✅ 流式响应提升用户体验
|
||
- ✅ 结构化日志便于调试
|
||
- ✅ 类型安全（TypeScript全覆盖）
|
||
|
||
---
|
||
|
||
## 🆘 常见问题
|
||
|
||
### Q1: 如何添加新的智能体？
|
||
|
||
**前端：** 编辑 `constants.ts`
|
||
```typescript
|
||
{
|
||
id: 'NEW_AGENT',
|
||
name: '新智能体',
|
||
icon: 'icon-name',
|
||
description: '描述文本',
|
||
theme: 'blue',
|
||
phase: 1,
|
||
order: 99,
|
||
}
|
||
```
|
||
|
||
**后端：** 编辑 `agentService.ts`
|
||
```typescript
|
||
{
|
||
id: 'NEW_AGENT',
|
||
systemPrompt: '系统提示词...',
|
||
welcomeMessage: '欢迎语...',
|
||
}
|
||
```
|
||
|
||
### Q2: 如何切换 LLM 模型？
|
||
|
||
修改 `conversationService.ts`：
|
||
```typescript
|
||
const DEFAULT_MODEL = 'qwen-max'; // 或 'gpt-5', 'claude-4.5'
|
||
```
|
||
|
||
### Q3: 如何调试流式响应？
|
||
|
||
查看浏览器控制台：
|
||
```javascript
|
||
// useAIStream Hook 会输出日志
|
||
[useAIStream] 解析 Chunk: {...}
|
||
```
|
||
|
||
查看后端日志：
|
||
```
|
||
[StreamingService] 流式生成完成
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 版本历史
|
||
|
||
### V2.0 (2026-01-14) 🎉
|
||
|
||
**重大重构：**
|
||
- ✅ 通用能力层架构建立
|
||
- ✅ OpenAI Compatible 流式响应
|
||
- ✅ 12个智能体配置完成
|
||
- ✅ 现代感UI（100%还原原型图）
|
||
- ✅ Ant Design X 深度集成
|
||
|
||
**技术栈升级：**
|
||
- Ant Design X 2.1
|
||
- React 19
|
||
- TypeScript 5
|
||
- OpenAI Compatible API
|
||
|
||
### V1.0 (旧版，已废弃)
|
||
|
||
- 旧架构实现
|
||
- 不符合云原生规范
|
||
- 已迁移至 `backend/src/legacy`
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
如有问题，请查看：
|
||
1. 本文档的常见问题部分
|
||
2. 系统整体设计文档
|
||
3. 通用能力层文档
|
||
|
||
或联系开发团队。
|
||
|
||
---
|
||
|
||
**文档维护：** 请在每次重大更新后及时更新本文档，保持与代码同步。
|
||
|
||
|
||
|
||
|
||
|
||
|