# 智能文献检索（DeepSearch）集成开发记录

> **开发日期：** 2026-01-18  
> **开发者：** AI 开发助手  
> **状态：** ✅ MVP 功能完成  
> **模块：** ASL - AI智能文献

---

## 📋 功能概述

### 需求背景
临床研究者需要从 PubMed 检索高质量文献，传统方式需要手动构建检索式，效率低下。通过集成 unifuncs DeepSearch API，实现 AI 驱动的自动化深度文献检索。

### 核心功能
- 自然语言输入研究问题
- AI 自动生成专业检索策略
- 实时显示 AI 思考过程
- 深度检索 PubMed 数据库
- 提取并展示 PubMed 文献链接

---

## 🛠️ 技术实现

### 架构方案

```
用户输入 → 前端 SSE 请求 → 后端调用 unifuncs API → 流式返回 → 实时展示
```

**关键技术选型：**
- **API 协议**：unifuncs OpenAI 兼容协议（Streaming 模式）
- **前后端通信**：Server-Sent Events (SSE)
- **数据存储**：PostgreSQL (asl_schema.asl_research_tasks)

### 文件结构

```
backend/
├── src/modules/asl/
│   ├── controllers/researchController.ts  # SSE 流式接口
│   ├── services/researchService.ts        # 核心业务逻辑
│   ├── workers/researchWorker.ts          # 异步任务处理（备用）
│   └── routes/index.ts                    # 路由注册
├── prisma/schema.prisma                   # 数据库模型

frontend-v2/
└── src/modules/asl/
    ├── pages/ResearchSearch.tsx           # 检索页面
    ├── pages/ResearchSearch.css           # 样式
    └── api/index.ts                       # API 函数
```

### API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/asl/research/stream` | SSE 流式检索（推荐） |
| POST | `/api/v1/asl/research/tasks` | 创建异步任务（备用） |
| GET | `/api/v1/asl/research/tasks/:taskId/status` | 查询任务状态 |

### 数据库 Schema

```prisma
model AslResearchTask {
  id               String    @id @default(cuid())
  projectId        String    @map("project_id")
  userId           String    @map("user_id")
  query            String
  filters          Json?
  externalTaskId   String?   @map("external_task_id")
  status           String    @default("pending")
  errorMessage     String?   @map("error_message")
  resultCount      Int?      @map("result_count")
  rawResult        String?   @map("raw_result") @db.Text
  reasoningContent String?   @map("reasoning_content") @db.Text
  literatures      Json?
  tokenUsage       Json?     @map("token_usage")
  searchCount      Int?      @map("search_count")
  readCount        Int?      @map("read_count")
  iterations       Int?
  createdAt        DateTime  @default(now()) @map("created_at")
  updatedAt        DateTime  @updatedAt @map("updated_at")
  completedAt      DateTime? @map("completed_at")

  @@map("asl_research_tasks")
  @@schema("asl_schema")
}
```

---

## 🎯 开发过程

### Phase 1：API 验证
- 创建测试脚本 `scripts/test-unifuncs-deepsearch.ts`
- 验证 unifuncs DeepSearch API 可用性
- 确认 OpenAI 兼容协议（Streaming）可行

### Phase 2：后端开发
1. 数据库 Schema 设计与迁移
2. ResearchService 核心逻辑
3. ResearchController API 接口
4. 路由注册

### Phase 3：前端开发
1. 检索页面 UI 设计（参考 unifuncs 简洁风格）
2. SSE 流式接收实现
3. 实时内容展示
4. PubMed 链接列表

### Phase 4：联调优化
1. 修复 userId 获取问题
2. 从异步轮询改为 SSE 实时流式
3. UI 合并为统一内容流
4. 链接提取逻辑优化

---

## ⚠️ 已知问题与遗留

### 当前限制
1. **非真正异步**：离开页面任务会中断（SSE 连接断开）
2. **成本较高**：每次检索约 0.3 元（unifuncs API 费用）
3. **格式待优化**：思考过程和结果的排版可进一步美化

### 后续改进方向
- [ ] 真正的异步任务（用户可离开页面）
- [ ] 搜索历史记录 UI
- [ ] 高级筛选（年份、研究类型）
- [ ] 导出功能（Excel/BibTeX）
- [ ] Token 消耗统计展示
- [ ] 一键导入到标题摘要初筛

---

## 📊 测试结果

### 功能测试
| 测试项 | 状态 | 备注 |
|--------|------|------|
| 创建检索任务 | ✅ | 正常 |
| SSE 实时流式 | ✅ | 思考过程实时显示 |
| PubMed 链接提取 | ✅ | 正确提取 |
| 数据库存储 | ✅ | 任务记录保存 |
| 错误处理 | ✅ | 网络错误、API 错误 |

### 性能数据
- 平均检索时间：1-3 分钟
- 返回文献数量：10-20 篇（视查询复杂度）

---

## 📝 配置说明

### 环境变量
```bash
# backend/.env
UNIFUNCS_API_KEY=sk-xxxx
```

### 前端入口
- 路由：`/literature/research/search`
- 菜单：AI智能文献 → 2. 智能文献检索

---

## 📚 参考资料

- [unifuncs DeepSearch API 文档](https://unifuncs.com/docs)
- [Postgres-Only 异步任务处理指南](../../02-通用能力层/Postgres-Only异步任务处理指南.md)
- [数据库开发规范](../../04-开发规范/09-数据库开发规范.md)