Files

HaHafeng 303dd78c54 feat(aia): Protocol Agent MVP complete with one-click generation and Word export

- 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

2026-01-25 19:16:36 +08:00

21 KiB

Raw Blame History

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 管理系统集成

10 个智能体 Prompt 迁移到数据库
支持在管理端在线编辑和调试
灰度预览（调试者看 DRAFT，普通用户看 ACTIVE）
三级容灾（数据库 → 缓存 → 兜底）
版本管理和回滚

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框架:

5层架构完整实现：Query→Planner→Executor→Tools→Reflection
ConfigLoader, BaseAgentOrchestrator, QueryAnalyzer, StageManager, TraceLogger
agent_schema: 6张表，protocol_schema: 2张表
完整类型定义（382行）

Protocol Agent:

后端：6个核心服务，6个API端点，10/10测试通过
前端：三栏布局，5阶段状态面板，100%还原原型图
5阶段流程：科学问题→PICO→研究设计→样本量→观察指标

🎉 V3.1 Protocol Agent 完整交付（2026-01-25）

一键生成研究方案:

动态双面板布局（ResizableSplitPane，可拖拽调整）
视图切换（研究摘要 / 完整方案）
A4 纸张预览效果（DocumentPanel）
流式生成 + Markdown 渲染 + 滚动跟随
12章节完整临床研究方案结构

Word 文档导出:

Python 微服务（pypandoc + Pandoc）
Node.js API 端点（/export/docx）
前端一键下载

用户体验优化:

StatePanel 折叠/展开（CollapsibleContent）
科学问题/PICO/样本量/观察指标完整显示
延迟创建对话（避免空记录）
对话标题自动更新
Prompt 工程优化（阶段约束、数据凝练放宽）

Bug 修复:

滚动条显示问题（flex min-height: 0）
模型阶段混乱问题（Prompt 增强）
数据类型错误（toArray 辅助函数）
顶部标题两行、欢迎语过大、列表编号错误

代码统计:

前端新增：~~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 (结构化日志)                                  │
└─────────────────────────────────────────────────────────┘

核心创新

OpenAI Compatible 流式响应
- 统一标准格式，兼容业界主流
- 支持 content 和 reasoning_content 双流
- 前端 useAIStream Hook 自动解析
现代感UI设计
- 100%还原原型图V11
- Ant Design X 深度集成
- 响应式布局（桌面+移动）
通用能力复用
- 前端 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`	✅	流式发送消息

🚀 快速开始

前端使用

// 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}
/>

后端使用

// 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设计规范

设计原则

100%还原原型图 - 尊重设计师的精心打磨
现代感风格 - 参考 Ant Design X Ultramodern
沉浸式体验 - 全屏对话，无干扰
响应式设计 - 桌面端和移动端适配

关键尺寸

元素	尺寸/样式
AgentHub 最大宽度	760px
智能体卡片	min-height: 145px, padding: 14px, 圆角: 10px
卡片网格	每行3个（Phase 1），每行4个（Phase 2）
时间轴圆点	24px，序号居中
欢迎语气泡	单行，左上角，灰色卡片
输入框	圆角16px，聚焦时蓝色边框+阴影
侧边栏	256px

配色方案

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

🧪 测试指南

前端测试

# 启动开发服务器
cd frontend-v2
npm run dev

# 访问
http://localhost:5173/aia

测试要点：

✅ 12个智能体卡片是否正确显示
✅ 点击卡片是否能进入对话界面
✅ 输入框能否正常输入和发送
✅ 深度思考按钮是否可切换
✅ 消息是否流式显示

后端测试

# 启动开发服务器
cd backend
npm run dev

# 查看日志
tail -f logs/app.log

API 测试（REST Client）：

### 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
}

⚠️ 已知问题

技术债务

附件处理未完成
- 上传接口待实现
- 文档提取待对接
- Token截断待测试
历史消息未加载
- 切换对话时不加载历史
- 需要实现分页加载
意图路由简化版
- 当前仅关键词匹配
- 后续可接入向量检索

性能优化点

智能体配置缓存（已实现，待测试）
上下文Token截断（逻辑已预留）
SSE连接保活优化

📚 参考文档

内部文档

AIA模块PRD - 产品需求
原型图V11 - UI设计
原型图V2 - 对话界面
开发计划 - 实施路径
后端API设计 - 接口文档
前端组件设计 - 组件设计

通用能力层

外部文档

🎓 开发经验

架构决策

为什么重构？
- 旧版不符合云原生规范
- 通用能力未抽象
- UI体验不符合新设计
为什么选择 OpenAI Compatible？
- 业界标准，兼容性好
- Ant Design X 原生支持
- 便于未来扩展
为什么调整后端而非前端？
- 前端可复用 Ant Design X 完整能力
- 后端标准化利于生态集成
- 减少重复造轮子

最佳实践

✅ 通用能力层优先复用
✅ 100%还原原型图设计
✅ 流式响应提升用户体验
✅ 结构化日志便于调试
✅ 类型安全（TypeScript全覆盖）

🆘 常见问题

Q1: 如何添加新的智能体？

前端： 编辑 constants.ts

{
  id: 'NEW_AGENT',
  name: '新智能体',
  icon: 'icon-name',
  description: '描述文本',
  theme: 'blue',
  phase: 1,
  order: 99,
}

后端： 编辑 agentService.ts

{
  id: 'NEW_AGENT',
  systemPrompt: '系统提示词...',
  welcomeMessage: '欢迎语...',
}

Q2: 如何切换 LLM 模型？

修改 conversationService.ts：

const DEFAULT_MODEL = 'qwen-max';  // 或 'gpt-5', 'claude-4.5'

Q3: 如何调试流式响应？

查看浏览器控制台：

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

📞 技术支持

如有问题，请查看：

本文档的常见问题部分
系统整体设计文档
通用能力层文档

或联系开发团队。

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

21 KiB Raw Blame History Unescape Escape

AIA AI智能问答模块 - 当前状态与开发指南

📋 文档说明

🎯 模块概述

核心功能

当前状态

✅ V2.1 新增功能（2026-01-18）

✅ V3.0 Protocol Agent MVP（2026-01-24）

🎉 V3.1 Protocol Agent 完整交付（2026-01-25）

🏗️ 架构设计

V3 架构特点

核心创新

📂 文件结构

前端

后端

通用能力层

🗄️ 数据库设计

Schema: aia_schema

1. conversations - 对话表

2. messages - 消息表

🔌 API 端点

智能体管理

对话管理

消息发送

🚀 快速开始

前端使用

后端使用

✅ 已完成功能

前端（100%）

后端（100%）

🚧 待开发功能

高优先级

中优先级

低优先级

📊 开发进度

时间线

代码统计

🎨 UI设计规范

设计原则

关键尺寸

配色方案

🔧 技术栈

前端

后端

🧪 测试指南

前端测试

后端测试

⚠️ 已知问题

技术债务

性能优化点

📚 参考文档

内部文档

通用能力层

外部文档

🎓 开发经验

架构决策

最佳实践

🆘 常见问题

Q1: 如何添加新的智能体？

Q2: 如何切换 LLM 模型？

Q3: 如何调试流式响应？

📝 版本历史

V2.0 (2026-01-14) 🎉

V1.0 (旧版，已废弃)

📞 技术支持

21 KiB

Raw Blame History

Schema: `aia_schema`

1. `conversations` - 对话表

2. `messages` - 消息表