Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(asl/extraction): Complete Tool 3 M1+M2 - skeleton pipeline and HITL workbench

Browse Source 
M1 Skeleton Pipeline:
- Scatter-dispatch + Aggregator polling pattern (PgBoss)
- PKB ACL bridge (PkbBridgeService -> PkbExportService DTOs)
- ExtractionSingleWorker with DeepSeek-V3 LLM extraction
- PermanentExtractionError for non-retryable failures
- Phantom Retry Guard (idempotent worker)
- 3-step minimal frontend (Setup -> Progress -> Workbench)
- 4 new DB tables (extraction_templates, project_templates, tasks, results)
- 3 system templates seed (RCT, Cohort, QC)
- M1 integration test suite

M2 HITL Workbench:
- MinerU VLM integration for high-fidelity table extraction
- XML-isolated DynamicPromptBuilder with flat JSON output template
- fuzzyQuoteMatch validator (3-tier confidence scoring)
- SSE real-time logging via ExtractionEventBus
- Schema-driven ExtractionDrawer (dynamic field rendering from template)
- Excel wide-table export with flattenModuleData normalization
- M2 integration test suite

Critical Fixes (data normalization):
- DynamicPromptBuilder: explicit flat key-value output format with example
- ExtractionExcelExporter: handle both array and flat data formats
- ExtractionDrawer: schema-driven rendering instead of hardcoded fields
- ExtractionValidator: array-format quote verification support
- SSE route: Fastify register encapsulation to bypass auth for EventSource
- LLM JSON sanitizer: strip illegal control chars before JSON.parse

Also includes: RVW stats verification spec, SSA expert config guide

Tested: M1 pipeline test + M2 HITL test + manual frontend verification
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HaHafeng
2026-02-25 18:29:20 +08:00
parent 371fa53956
commit f0736dbca1
40 changed files with 6138 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/03-业务模块/ASL-AI智能文献/00-模块当前状态与开发指南.md
View File

@@ -1,15 +1,14 @@
# AI智能文献模块 - 当前状态与开发指南
> **文档版本：** v2.1
> **文档版本：** v2.2
> **创建日期：** 2025-11-21
> **维护者：** AI智能文献开发团队
> **最后更新：** 2026-02-24 🆕 **工具 3 V2.0 开发计划升级至 v2.0（散装派发 + Aggregator 架构，9 条研发红线）**
> **最后更新：** 2026-02-25 🆕 **工具 3 M1 骨架管线 + M2 HITL 工作台开发完成！**
> **重大进展：**
> - 🆕 2026-02-24：工具 3 V2.0 架构升级！Fan-out → 散装派发 + Aggregator 轮询收口，通用模式指南 v1.1 沉淀
> - 2026-02-23：工具 3 V2.0 开发计划 v1.5 完成！6 轮架构审查 + 5 份文档体系
> - 🆕 2026-02-23：V2.0 核心功能完成！SSE 流式架构 + 段落化思考日志 + 引用链接可见化
> - 🆕 2026-02-22：V2.0 前后端联调完成！瀑布流 UI + Markdown 渲染 + Word 导出 + 中文数据源测试
> - 🆕 2026-02-22：V2.0 开发计划确认 + Unifuncs API 网站覆盖测试完成
> - 🆕 2026-02-25：**工具 3 M1+M2 开发完成！** 散装派发+Aggregator 全链路、MinerU 集成、XML Prompt 隔离、fuzzyQuoteMatch 溯源、HITL 审核抽屉、Excel 导出、数据归一化修复
> - 2026-02-24：工具 3 V2.0 架构升级！Fan-out → 散装派发 + Aggregator 轮询收口，通用模式指南 v1.1 沉淀
> - 2026-02-23：V2.0 核心功能完成！SSE 流式架构 + 段落化思考日志 + 引用链接可见化
> - 2026-02-22：V2.0 前后端联调完成！瀑布流 UI + Markdown 渲染 + Word 导出 + 中文数据源测试
> - 2026-01-18：智能文献检索（DeepSearch）MVP完成 - unifuncs API 集成
> **文档目的：** 反映模块真实状态，帮助新开发人员快速上手
@@ -33,15 +32,17 @@
AI智能文献模块是一个基于大语言模型（LLM）的文献筛选系统，用于帮助研究人员根据PICOS标准自动筛选文献。
### 当前状态
- **开发阶段**：🎉 V2.0 Deep Research 核心功能完成 + 🆕 工具 3 开发计划 v2.0 就绪
- **开发阶段**：🎉 工具 3 M1+M2 开发完成，M3 待启动
- **已完成功能**：
- ✅ 标题摘要初筛（Title & Abstract Screening）- 完整流程
- ✅ 全文复筛后端（Day 2-5）- LLM服务 + API + Excel导出
- ✅ **智能文献检索（DeepSearch）V1.x MVP** - unifuncs API 集成
- ✅ **Unifuncs API 网站覆盖测试** - 18 站点实测，9 个一级可用
- ✅ **🎉 Deep Research V2.0 核心功能** — SSE 流式架构 + 瀑布流 UI + HITL + Word 导出
- **开发计划就绪（待编码）**：
- 📋 **🆕 工具 3 全文智能提取工作台 V2.0** — 开发计划 v2.0 完成（散装派发 + Aggregator 架构，9 条研发红线，M1/M2/M3 三阶段，预计 22 天）
- ✅ **🆕 工具 3 M1 骨架管线** — 散装派发+Aggregator 全链路、PKB ACL 防腐层、DeepSeek-V3 纯文本盲提、3 步极简前端
- ✅ **🆕 工具 3 M2 HITL 工作台** — MinerU VLM 表格集成、XML Prompt 隔离、fuzzyQuoteMatch 溯源、SSE 实时日志、审核抽屉、Excel 宽表导出
- **待开发**：
- 📋 **工具 3 M3 动态模板引擎** — 自定义字段 CRUD、Prompt 注入防护、E2E 测试
- **V2.0 已完成**：
- ✅ **SSE 流式架构**：从 create_task/query_task 轮询改为 OpenAI Compatible SSE 流，实时推送 AI 思考过程
- ✅ **LLM 需求扩写**：DeepSeek-V3 将粗略输入扩写为结构化检索指令书（PICOS + MeSH）
@@ -128,11 +129,11 @@ frontend-v2/src/modules/asl/
**通用能力指南**：`docs/02-通用能力层/04-DeepResearch引擎/01-Unifuncs DeepSearch API 使用指南.md`
### 🆕 工具 3 全文智能提取工作台 V2.0（2026-02-24 开发计划 v2.0 完成，待编码）
### 🆕 工具 3 全文智能提取工作台 V2.0（2026-02-25 M1+M2 开发完成）
**功能定位：** 批量读取 PDF 全文 → 动态模板驱动 AI 结构化提取 → 人工 HITL 审核 → Excel 导出。是 ASL 证据整合 V2.0 三大工具中最复杂的一个。
**开发计划状态：** ✅ v2.0 定稿（经 8+ 轮架构审查 + 架构转型：Fan-out → 散装派发 + Aggregator）
**开发状态：** ✅ M1 骨架管线完成 ✅ M2 HITL 工作台完成 📋 M3 动态模板引擎待启动
**v2.0 架构转型（2026-02-24）：**
@@ -176,11 +177,36 @@ frontend-v2/src/modules/asl/
**里程碑规划：**
| 里程碑 | 核心交付 | 时间 |
|--------|---------|------|
| M1 骨架管线 | 散装派发 + Aggregator 全链路 + PKB ACL + 纯文本盲提 + 极简前端 | Week 1 |
| M2 HITL 工作台 | MinerU + 审核抽屉 + SSE 日志 + Excel | Week 2-3 |
| M3 动态模板引擎 | 自定义字段 + Prompt 注入防护 + E2E 测试 | Week 4 |
| 里程碑 | 核心交付 | 时间 | 状态 |
|--------|---------|------|------|
| M1 骨架管线 | 散装派发 + Aggregator 全链路 + PKB ACL + 纯文本盲提 + 极简前端 | Week 1 | ✅ 完成 |
| M2 HITL 工作台 | MinerU + XML Prompt 隔离 + fuzzyQuoteMatch + SSE 日志 + 审核抽屉 + Excel 导出 | Week 2-3 | ✅ 完成 |
| M3 动态模板引擎 | 自定义字段 + Prompt 注入防护 + E2E 测试 | Week 4 | 📋 待启动 |
**M1+M2 已完成的核心代码组件：**
| 组件 | 文件 | 说明 |
|------|------|------|
| 散装派发 API | `ExtractionService.ts` | API 层直接 insert N 个独立 Job |
| 单文档 Worker | `ExtractionSingleWorker.ts` | PdfPipeline → DynamicPrompt → LLM → Validator |
| Aggregator 轮询 | `ExtractionAggregator.ts` | 定时 groupBy 收口 + 僵尸清理 |
| PKB 防腐层 | `PkbBridgeService.ts` → `PkbExportService.ts` | ACL 解耦，DTO 传输 |
| PDF 管线 | `PdfProcessingPipeline.ts` | MinerU VLM 表格 + PKB extractedText fallback |
| XML Prompt | `DynamicPromptBuilder.ts` | 扁平 JSON 输出模板 + HIGH_FIDELITY_TABLES 优先 |
| Quote 溯源 | `ExtractionValidator.ts` | fuzzyQuoteMatch 三档置信度 |
| SSE 事件 | `ExtractionEventBus.ts` | 内存事件总线 + 历史回放 |
| Excel 导出 | `ExtractionExcelExporter.ts` | flattenModuleData 归一化 + 双行表头宽表 |
| 模板服务 | `TemplateService.ts` | 3 套系统模板（RCT/Cohort/QC） |
| 审核抽屉 | `ExtractionDrawer.tsx` | Schema-driven 动态字段渲染 |
| 审核工作台 | `ExtractionWorkbench.tsx` | 全宽表格 + 700px Drawer |
**M2 关键修复记录（2026-02-25）：**
- 🔧 DynamicPromptBuilder：LLM 返回数组格式 → 重写 Prompt 明确要求扁平 key-value 格式
- 🔧 ExcelExporter：新增 `flattenModuleData` 归一化，兼容 `[{key,value,quote}]` 数组格式
- 🔧 ExtractionDrawer：从硬编码字段改为 schema-driven 动态渲染
- 🔧 ExtractionValidator：兼容数组格式 quote 验证
- 🔧 SSE 路由：Fastify 插件封装隔离，SSE 端点绕过 authenticate
- 🔧 LLM JSON 清洗：sanitize 非法控制字符防止 JSON.parse 崩溃
**9 条研发红线**：详见架构总纲文档 M1 红线表。
@@ -188,6 +214,37 @@ frontend-v2/src/modules/asl/
- 🚀 `docs/02-通用能力层/散装派发与轮询收口任务模式指南.md`（v1.1，Level 2 Cookbook）
- 📖 `docs/02-通用能力层/分布式Fan-out任务模式开发指南.md`（v1.2，Level 3 参考）
**工具 3 新增 API 端点：**
```http
GET /api/v1/asl/extraction/templates # 系统模板列表
POST /api/v1/asl/extraction/templates/clone # 克隆模板到项目
POST /api/v1/asl/extraction/tasks # 创建提取任务（散装派发）
GET /api/v1/asl/extraction/tasks/:taskId/status # 任务状态（groupBy 聚合）
GET /api/v1/asl/extraction/tasks/:taskId/results # 提取结果列表
GET /api/v1/asl/extraction/results/:resultId # 单条结果详情（含 schema）
PUT /api/v1/asl/extraction/results/:resultId/review # 审核（approved/rejected）
GET /api/v1/asl/extraction/tasks/:taskId/stream # SSE 实时日志（无需认证）
GET /api/v1/asl/extraction/tasks/:taskId/export # Excel 导出
GET /api/v1/asl/extraction/pkb/knowledge-bases # PKB 知识库代理
GET /api/v1/asl/extraction/pkb/knowledge-bases/:kbId/documents # PKB 文档代理
```
**工具 3 新增前端路由：**
```
/literature/extraction/setup # Step 1: 配置与启动
/literature/extraction/progress/:taskId # Step 2: 进度监控
/literature/extraction/workbench/:taskId # Step 3: 审核工作台
```
**工具 3 新增数据库表（asl_schema）：**
| 表名 | 说明 |
|------|------|
| `extraction_templates` | 系统内置模板（RCT/Cohort/QC） |
| `extraction_project_templates` | 项目模板（克隆自系统模板，含 outcomeType/customFields） |
| `extraction_tasks` | 提取任务（idempotencyKey 幂等） |
| `extraction_results` | 单文档提取结果（extractedData JSON + quoteVerification + reviewStatus） |
### 智能文献检索 DeepSearch V1.x（2026-01-18 MVP完成）
**功能概述：**
@@ -1434,28 +1491,28 @@ Drawer打开: <50ms
## 🎯 下一步开发计划
### 当前（Deep Research V2.0 优化）
1. ⏳ **端到端回归测试**：完整流程测试（创建→扩写→确认→执行→结果→导出）
2. ⏳ **用户体验打磨**：加载动画、错误提示、边界情况处理
3. ⏳ **中文检索优化**：中英文混合检索策略调优（建议分批搜索）
4. ⏳ **导出格式完善**：Word 模板美化、更多导出格式
### 当前（工具 3 M3 动态模板引擎）
1. ⏳ **M3-1：自定义字段 CRUD**：用户可在项目模板上增删改自定义提取字段
2. ⏳ **M3-2：Prompt 注入防护**：用户输入的字段 description 经过清洗再注入 Prompt
3. ⏳ **M3-3：E2E 完整测试**：从模板配置 → 提取 → 审核 → 导出的端到端自动化测试
4. ⏳ **M3-4：模板版本管理**：支持锁定/解锁、版本快照
### 工具 3 后续优化
1. ⏳ **RoB 自动评价增强**：Prompt 引导 LLM 基于方法学描述主动评价偏倚风险
2. ⏳ **study_id 格式标准化**：强制 "FirstAuthor Year" 格式，后处理校验
3. ⏳ **outcomes 模板匹配**：根据文献内容自动推荐 survival/continuous/dichotomous
4. ⏳ **缺失字段补充**：country、inclusion_criteria、primary_outcome 等（M3 自定义字段支持）
### 短期优化
1. ⏳ Prompt 优化（需求扩写质量提升）
2. ⏳ 搜索历史管理（历史任务列表、重新搜索）
3. ⏳ 全文复筛前端 UI 开发
4. ⏳ 标题摘要初筛 Prompt 优化（准确率 60% → 85%+）
1. ⏳ Deep Research V2.0 端到端回归测试
2. ⏳ 搜索历史管理（历史任务列表）
3. ⏳ 标题摘要初筛 Prompt 优化（准确率 60% → 85%+）
### 中期（Month 2）
1. ⏳ 全文复筛功能完善
2. ⏳ 证据图谱可视化
3. ⏳ 用户自定义数据源
4. ⏳ 生产环境部署
### 长期（Month 3+）
1. ⏳ 多语言检索策略自动优化
2. ⏳ 批量文献检索
3. ⏳ 成本控制和监控
### 中期（Month 2-3）
1. ⏳ 工具 4（网状 Meta 分析）开发
2. ⏳ 工具 5（证据质量评价 GRADE）开发
3. ⏳ 生产环境部署
4. ⏳ 证据图谱可视化
---
@@ -1465,14 +1522,15 @@ Drawer打开: <50ms
---
**最后更新**：2026-02-23（Deep Research V2.0 核心功能完成）
**最后更新**：2026-02-25（工具 3 M1+M2 开发完成 + 数据归一化修复）
**文档状态**：✅ 反映真实状态
**下次更新时机**：V2.0 端到端回归测试完成 或 全文复筛前端开发启动
**下次更新时机**：工具 3 M3 动态模板引擎开发完成
**本次更新内容**（v2.0）：
- ✅ 更新当前状态：V2.0 核心功能开发完成（SSE 流式 + 瀑布流 UI + Word 导出）
- ✅ 新增 V2.0 完整架构表、技术决策、API 端点、关键文件列表
- ✅ 新增 5 个精选数据源配置（替代 9 站全量展示）
- ✅ 更新下一步开发计划（V2.0 优化 + 短期/中期/长期）
**本次更新内容**（v2.2）：
- ✅ 工具 3 M1 骨架管线完成：散装派发+Aggregator、PKB ACL、纯文本盲提、3步极简前端
- ✅ 工具 3 M2 HITL 工作台完成：MinerU 集成、XML Prompt 隔离、fuzzyQuoteMatch、SSE 日志、审核抽屉、Excel 导出
- ✅ M2 关键修复：DynamicPromptBuilder 扁平输出、ExcelExporter 数据归一化、Schema-driven 前端
- ✅ 新增工具 3 API 端点（12 个）、前端路由（3 个）、数据库表（4 个）
- ✅ 更新下一步计划：M3 动态模板引擎 + RoB 增强 + 后续工具 4/5