# 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 长度

**技术规格**：

```typescript
// 附件处理配置
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 通用组件**
  ```tsx
  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  
**审核人**：待定  
**批准人**：待定