AIclinicalresearch/docs/03-业务模块/AIA-AI智能问答/04-开发计划/01-AIA-V2.1开发计划.md

AIA 模块 V2.1 开发计划

版本：V2.1
创建日期：2026-01-11
计划周期：约 8-11 天
策略：重写后端 + 复用数据库 + 新开发前端
关联PRD：01-需求分析/AIA模块PRD.md
关联原型：01-需求分析/AI智能问答V2.html

---

📋 开发策略概述

核心决策

组件	策略	理由
后端	🔴 重写	旧版不符合云原生规范（console.log、未使用平台能力）
数据库	✅ 复用	aia_schema 已完善，字段满足需求
前端	🔴 新开发	复用 shared/components/Chat 通用组件，全新UI

技术规范

规范	要求
日志	使用 logger from @/common/logging（禁止 console.log）
存储	使用 storage from @/common/storage
缓存	使用 cache from @/common/cache
队列	使用 jobQueue from @/common/jobs
Prompt	使用 promptService.get() from @/common/prompts
代码位置	backend/src/modules/aia/
API路由	/api/v2/aia/*

---

📊 数据库状态（✅ 已完成）

表结构（3个表）

aia_schema.projects        ✅ 保留
aia_schema.conversations   ✅ 保留
aia_schema.messages        ✅ 保留 + 新增字段

新增字段（2026-01-11 已迁移）

表	字段	类型	说明
messages	thinking_content	TEXT	深度思考内容 <think>...</think>
messages	attachments	JSONB	附件数组（上限5个，单个≤20MB，文本≤30K tokens）

已删除表

表	原因
general_conversations	功能重叠，使用 conversations.project_id = NULL
general_messages	功能重叠

---

🗓️ 开发阶段

Phase 1: 后端重写（3-4天）

Day 1: 模块骨架 + 核心服务

目标：搭建模块结构，迁移核心对话服务

任务清单：

• 1.1 创建模块目录结构

  backend/src/modules/aia/
  ├── controllers/
  │   ├── conversationController.ts
  │   ├── agentController.ts
  │   └── projectController.ts
  ├── services/
  │   ├── conversationService.ts
  │   ├── agentService.ts
  │   └── projectService.ts
  ├── routes/
  │   └── index.ts
  ├── types/
  │   └── index.ts
  └── index.ts
  

• 1.2 重写 conversationService

  • 从 legacy 复制核心逻辑
  • 替换 console.log → logger
  • 使用 prisma.message（已在 aia_schema）
  • 添加 thinkingContent 处理逻辑
  • 保持流式输出能力

• 1.3 重写 agentService

  • 改用 promptService.get() 获取 Prompt
  • 缓存智能体配置（使用 cache）

• 1.4 注册 v2 路由

  • 注册到 /api/v2/aia/*
  • 保持 legacy 路由兼容（逐步迁移）

验收标准：

• 基础对话功能可用
• 流式输出正常
• 日志输出到 logger

---

Day 2: 深度思考 + 附件上传

目标：实现 V2.1 新增功能

任务清单：

• 2.1 深度思考模式

  • 检测 LLM 输出中的 <think>...</think> 标签
  • 提取并存储到 messages.thinking_content
  • 从 content 中移除 think 标签
  • 流式输出时分离 thinking 和 content

• 2.2 附件上传服务

  • 使用 storage.upload() 上传到 OSS
  • 调用 Python 微服务提取文本
  • Token 计数（使用 tiktoken）
  • 截断处理（超过 30K tokens）
  • 存储附件信息到 messages.attachments

• 2.3 附件注入 LLM 上下文

  • 组装附件文本到 User Prompt
  • 控制总 Token 长度

技术规格：

// 附件处理配置
const ATTACHMENT_CONFIG = {
  maxCount: 5,              // 每条消息最多5个附件
  maxSizePerFile: 20 * 1024 * 1024,  // 单个文件20MB
  maxTokens: 30000,         // 提取文本最多30K tokens
  supportedTypes: ['pdf', 'docx', 'txt', 'xlsx'],
};

验收标准：

• 深度思考内容正确分离存储
• 附件上传成功
• 附件文本正确注入 LLM

---

Day 3: 意图路由 + 知识库集成

目标：实现全局意图路由，完善知识库引用

任务清单：

• 3.1 意图路由服务

  • 新建 intentRouterService.ts
  • 调用 Router Agent 识别意图
  • 返回目标 Agent ID + 预填 Prompt
  • 添加 500ms 防抖（前端实现）

• 3.2 完善知识库集成

  • 复用 PKB 模块的 RAG 检索
  • 智能引用系统（[来源N]）
  • 引用清单格式化

• 3.3 API 端点完善

  POST /api/v2/aia/intent/route          # 意图路由
  POST /api/v2/aia/conversations         # 创建对话
  GET  /api/v2/aia/conversations         # 对话列表
  GET  /api/v2/aia/conversations/:id     # 对话详情
  POST /api/v2/aia/conversations/:id/messages/stream  # 发送消息（流式）
  POST /api/v2/aia/conversations/:id/attachments      # 上传附件
  GET  /api/v2/aia/agents                # 智能体列表
  GET  /api/v2/aia/agents/:id            # 智能体详情
  

验收标准：

• 意图路由正确识别并跳转
• 知识库引用正确显示
• 所有 API 端点可用

---

Day 4: 测试 + 文档

目标：完成后端测试和文档

任务清单：

• 4.1 单元测试

  • conversationService 测试
  • 深度思考解析测试
  • 附件处理测试

• 4.2 集成测试

  • 完整对话流程
  • 附件上传流程
  • 知识库检索流程

• 4.3 API 文档

  • 更新 REST Client 测试文件
  • 编写 API 使用示例

验收标准：

• 测试覆盖核心功能
• API 文档完整

---

Phase 2: 前端开发（5-7天）

Day 5-6: 智能体大厅（Dashboard）

目标：实现首页智能体大厅

任务清单：

• 5.1 创建模块目录结构

  frontend-v2/src/modules/aia/
  ├── pages/
  │   ├── Dashboard.tsx          # 智能体大厅
  │   └── Workspace.tsx          # 对话工作台
  ├── components/
  │   ├── AgentPipeline.tsx      # 5阶段流水线
  │   ├── AgentCard.tsx          # 智能体卡片
  │   ├── IntentSearch.tsx       # 意图搜索框
  │   ├── ConversationList.tsx   # 历史会话列表
  │   ├── ThinkingBlock.tsx      # 深度思考折叠块
  │   ├── AttachmentUpload.tsx   # 附件上传
  │   ├── AttachmentCard.tsx     # 附件卡片
  │   └── SlashCommands.tsx      # 快捷指令
  ├── hooks/
  │   ├── useConversation.ts
  │   ├── useAgents.ts
  │   └── useIntentRouter.ts
  ├── api/
  │   └── index.ts
  ├── types/
  │   └── index.ts
  └── index.tsx
  

• 5.2 智能体流水线（AgentPipeline）

  • 5阶段布局（严格还原 V11 原型）
  • 3色视觉体系
  • 卡片点击跳转 Workspace
  • 工具卡片跳转外部模块（DC/ST）

• 5.3 意图搜索框（IntentSearch）

  • 顶部大搜索框
  • 500ms 防抖
  • 调用意图路由 API
  • 自动跳转目标 Agent

验收标准：

• 5阶段流水线正确展示
• 意图搜索功能可用
• 与原型图一致

---

Day 7-8: 对话工作台（Workspace）

目标：实现沉浸式对话界面

任务清单：

• 7.1 工作台布局

  • Gemini 风格（大留白、少分割线）
  • 左侧侧边栏（历史会话，可折叠）
  • 主对话区（Header + 消息列表 + 输入框）

• 7.2 复用 Chat 通用组件

  import { ChatContainer } from '@/shared/components/Chat';
  
  <ChatContainer
    providerConfig={{
      apiEndpoint: '/api/v2/aia/conversations/:id/messages/stream',
      requestFn: sendMessageWithStream,
    }}
    customMessageRenderer={renderAIAMessage}
  />
  

• 7.3 深度思考折叠块（ThinkingBlock）

  • 可折叠灰色引用块
  • 生成中展开，完成后自动收起
  • 显示"已深度思考 (耗时 Xs)"

• 7.4 附件上传组件

  • 支持拖拽上传
  • 文件类型/大小校验
  • 上传进度显示
  • 消息气泡下方附件卡片

• 7.5 历史会话列表

  • 按时间分组（今天、昨天、7天前）
  • 桌面端固定显示
  • 移动端抽屉滑出

验收标准：

• Gemini 风格 UI
• 深度思考正确展示
• 附件上传完整流程
• 历史会话切换

---

Day 9: Markdown 增强 + 快捷指令

目标：增强对话体验

任务清单：

• 9.1 Markdown 渲染增强

  • KaTeX 公式渲染（医学公式）
  • 表格横向滚动
  • 代码块语法高亮 + 一键复制

• 9.2 快捷指令（SlashCommands）

  • 输入 / 弹出菜单
  • 支持：/润色, /扩写, /翻译, /导出Word
  • 键盘导航

• 9.3 结果操作栏

  • Hover 显示工具栏
  • 复制（Markdown 源码）
  • 重新生成
  • 导出 Word（调用 RVW 导出服务）

验收标准：

• 公式正确渲染
• 快捷指令可用
• 操作栏功能完整

---

Day 10: 移动端适配

目标：响应式布局适配

任务清单：

• 10.1 Dashboard 移动端

  • 隐藏复杂导航
  • 卡片单列流式布局
  • 时间轴样式调整

• 10.2 Workspace 移动端

  • 侧边栏改为抽屉
  • 输入框键盘适配（scrollIntoView）
  • 发送按钮始终可见

• 10.3 触控优化

  • 按钮 active 态
  • 触控区域优化

验收标准：

• md (768px) 断点响应正确
• 移动端交互流畅

---

Day 11: 集成测试 + 优化

目标：完成整体测试和优化

任务清单：

• 11.1 端到端测试

  • 完整对话流程
  • 附件上传流程
  • 深度思考流程
  • 知识库引用流程

• 11.2 性能优化

  • TTFB < 1.5s
  • 移动端 LCP < 1s
  • 意图搜索防抖

• 11.3 Bug 修复

• 11.4 文档更新

  • 更新模块状态文档
  • 更新系统当前状态

验收标准：

• 所有功能正常
• 性能达标
• 文档完整

---

📁 文件清单

后端新增文件

backend/src/modules/aia/
├── controllers/
│   ├── conversationController.ts    # ~300行
│   ├── agentController.ts           # ~150行
│   └── projectController.ts         # ~200行
├── services/
│   ├── conversationService.ts       # ~500行（核心）
│   ├── agentService.ts              # ~200行
│   ├── projectService.ts            # ~150行
│   ├── intentRouterService.ts       # ~100行（新）
│   └── attachmentService.ts         # ~200行（新）
├── routes/
│   └── index.ts                     # ~100行
├── types/
│   └── index.ts                     # ~100行
└── index.ts                         # ~20行

预计总计：~2000行

前端新增文件

frontend-v2/src/modules/aia/
├── pages/
│   ├── Dashboard.tsx                # ~400行
│   └── Workspace.tsx                # ~500行
├── components/
│   ├── AgentPipeline.tsx            # ~300行
│   ├── AgentCard.tsx                # ~100行
│   ├── IntentSearch.tsx             # ~150行
│   ├── ConversationList.tsx         # ~200行
│   ├── ThinkingBlock.tsx            # ~100行
│   ├── AttachmentUpload.tsx         # ~200行
│   ├── AttachmentCard.tsx           # ~80行
│   └── SlashCommands.tsx            # ~150行
├── hooks/
│   ├── useConversation.ts           # ~150行
│   ├── useAgents.ts                 # ~100行
│   └── useIntentRouter.ts           # ~80行
├── api/
│   └── index.ts                     # ~200行
├── types/
│   └── index.ts                     # ~100行
└── index.tsx                        # ~50行

预计总计：~2900行

---

🔗 依赖关系

后端依赖

依赖	来源	说明
logger	@/common/logging	日志服务
storage	@/common/storage	OSS存储
cache	@/common/cache	Redis/PG缓存
jobQueue	@/common/jobs	异步任务
promptService	@/common/prompts	Prompt管理
LLMFactory	@/common/llm	LLM适配器
prisma	@/config/database	数据库
ExtractionClient	@/clients	文档提取
TokenService	@/services	Token计数

前端依赖

依赖	来源	说明
ChatContainer	@/shared/components/Chat	通用对话组件
Ant Design	antd	UI组件库
Ant Design X	@ant-design/x	AI对话组件
KaTeX	katex	公式渲染
react-markdown	react-markdown	Markdown渲染

---

📈 风险评估

风险	概率	影响	缓解措施
流式输出兼容性	中	高	复用已验证的 SSE 代码
附件提取超时	中	中	使用 jobQueue 异步处理
移动端适配问题	低	中	提前规划断点和布局
Prompt管理服务未就绪	低	中	可临时回退到文件读取

---

✅ 验收标准

功能验收

• 智能体大厅完整展示
• 意图搜索正确路由
• 多轮对话正常
• 流式输出流畅
• 深度思考正确折叠
• 附件上传完整
• 知识库引用正确
• 快捷指令可用
• 移动端适配正常

性能验收

• TTFB < 1.5s
• 移动端 LCP < 1s
• 意图搜索响应 < 500ms

质量验收

• 无 console.log（使用 logger）
• 代码符合云原生规范
• API 文档完整
• 单元测试覆盖核心功能

---

📝 更新日志

日期	版本	内容
2026-01-11	V1.0	创建开发计划

---

计划制定人：AI Assistant
审核人：待定
批准人：待定