# 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. 通用能力层文档

或联系开发团队。

---

**文档维护：** 请在每次重大更新后及时更新本文档，保持与代码同步。