HaHafeng
96290d2f76
Sprint 1-3 Completed (Backend + Frontend): Backend (Sprint 1-2): - Implement 5-layer Agent framework (Query->Planner->Executor->Tools->Reflection) - Create agent_schema with 6 tables (agent_definitions, stages, prompts, sessions, traces, reflexion_rules) - Create protocol_schema with 2 tables (protocol_contexts, protocol_generations) - Implement Protocol Agent core services (Orchestrator, ContextService, PromptBuilder) - Integrate LLM service adapter (DeepSeek/Qwen/GPT-5/Claude) - 6 API endpoints with full authentication - 10/10 API tests passed Frontend (Sprint 3): - Add Protocol Agent entry in AgentHub (indigo theme card) - Implement ProtocolAgentPage with 3-column layout - Collapsible sidebar (Gemini style, 48px <-> 280px) - StatePanel with 5 stage cards (scientific_question, pico, study_design, sample_size, endpoints) - ChatArea with sync button and action cards integration - 100% prototype design restoration (608 lines CSS) - Detailed endpoints structure: baseline, exposure, outcomes, confounders Features: - 5-stage dialogue flow for research protocol design - Conversation-driven interaction with sync-to-protocol button - Real-time context state management - One-click protocol generation button (UI ready, backend pending) Database: - agent_schema: 6 tables for reusable Agent framework - protocol_schema: 2 tables for Protocol Agent - Seed data: 1 agent + 5 stages + 9 prompts + 4 reflexion rules Code Stats: - Backend: 13 files, 4338 lines - Frontend: 14 files, 2071 lines - Total: 27 files, 6409 lines Status: MVP core functionality completed, pending frontend-backend integration testing Next: Sprint 4 - One-click protocol generation + Word export
185 lines
5.0 KiB
Markdown
185 lines
5.0 KiB
Markdown
# 智能文献检索（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)
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|