docs(asl): Upgrade Tool 3 architecture from Fan-out to Scatter+Aggregator (v2.0)
Architecture transformation: - Replace Fan-out (Manager->Child->Last Child Wins) with Scatter+Aggregator pattern - API layer directly dispatches N independent jobs (no Manager) - Worker only writes its own Result row, never touches Task table (zero row-lock) - Aggregator polls groupBy for completion + zombie cleanup (replaces Sweeper) - Reduce red lines from 13 to 9, eliminate distributed complexity Documents updated (10 files): - 08-Tool3 main architecture doc: v2.0 rewrite (schema, Task 2.3/2.4, red lines, risks) - 08d-Code patterns: rewrite sections 4.1-4.6 (API dispatch, SingleWorker, Aggregator) - 08a-M1 sprint: rewrite M1-3 core (Worker+Aggregator), red lines, acceptance criteria - 08b-M2 sprint: simplify SSE (NOTIFY/LISTEN downgraded to P2 optional) - 08c-M3 sprint: milestone table wording update - New: Scatter+Polling Aggregator pattern guide v1.1 (Level 2 cookbook) - New: V2.0 architecture deep review and gap-fix report - Updated: ASL module status, system status, capability layer index Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -3,9 +3,10 @@
|
||||
> **文档版本:** v2.1
|
||||
> **创建日期:** 2025-11-21
|
||||
> **维护者:** AI智能文献开发团队
|
||||
> **最后更新:** 2026-02-23 🆕 **工具 3 全文智能提取工作台 V2.0 开发计划完成(v1.5,6 轮架构审查)**
|
||||
> **最后更新:** 2026-02-24 🆕 **工具 3 V2.0 开发计划升级至 v2.0(散装派发 + Aggregator 架构,9 条研发红线)**
|
||||
> **重大进展:**
|
||||
> - 🆕 2026-02-23:工具 3 V2.0 开发计划 v1.5 完成!Fan-out 架构 + HITL + 动态模板 + 13 条研发红线 + 5 份文档体系
|
||||
> - 🆕 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 网站覆盖测试完成
|
||||
@@ -32,7 +33,7 @@
|
||||
AI智能文献模块是一个基于大语言模型(LLM)的文献筛选系统,用于帮助研究人员根据PICOS标准自动筛选文献。
|
||||
|
||||
### 当前状态
|
||||
- **开发阶段**:🎉 V2.0 Deep Research 核心功能完成 + 🆕 工具 3 开发计划就绪
|
||||
- **开发阶段**:🎉 V2.0 Deep Research 核心功能完成 + 🆕 工具 3 开发计划 v2.0 就绪
|
||||
- **已完成功能**:
|
||||
- ✅ 标题摘要初筛(Title & Abstract Screening)- 完整流程
|
||||
- ✅ 全文复筛后端(Day 2-5)- LLM服务 + API + Excel导出
|
||||
@@ -40,7 +41,7 @@ AI智能文献模块是一个基于大语言模型(LLM)的文献筛选系统
|
||||
- ✅ **Unifuncs API 网站覆盖测试** - 18 站点实测,9 个一级可用
|
||||
- ✅ **🎉 Deep Research V2.0 核心功能** — SSE 流式架构 + 瀑布流 UI + HITL + Word 导出
|
||||
- **开发计划就绪(待编码)**:
|
||||
- 📋 **🆕 工具 3 全文智能提取工作台 V2.0** — 开发计划 v1.5 完成(6 轮架构审查,13 条研发红线,M1/M2/M3 三阶段,预计 22 天)
|
||||
- 📋 **🆕 工具 3 全文智能提取工作台 V2.0** — 开发计划 v2.0 完成(散装派发 + Aggregator 架构,9 条研发红线,M1/M2/M3 三阶段,预计 22 天)
|
||||
- **V2.0 已完成**:
|
||||
- ✅ **SSE 流式架构**:从 create_task/query_task 轮询改为 OpenAI Compatible SSE 流,实时推送 AI 思考过程
|
||||
- ✅ **LLM 需求扩写**:DeepSeek-V3 将粗略输入扩写为结构化检索指令书(PICOS + MeSH)
|
||||
@@ -127,48 +128,65 @@ frontend-v2/src/modules/asl/
|
||||
|
||||
**通用能力指南**:`docs/02-通用能力层/04-DeepResearch引擎/01-Unifuncs DeepSearch API 使用指南.md`
|
||||
|
||||
### 🆕 工具 3 全文智能提取工作台 V2.0(2026-02-23 开发计划完成,待编码)
|
||||
### 🆕 工具 3 全文智能提取工作台 V2.0(2026-02-24 开发计划 v2.0 完成,待编码)
|
||||
|
||||
**功能定位:** 批量读取 PDF 全文 → 动态模板驱动 AI 结构化提取 → 人工 HITL 审核 → Excel 导出。是 ASL 证据整合 V2.0 三大工具中最复杂的一个。
|
||||
|
||||
**开发计划状态:** ✅ v1.5 定稿(经 6 轮架构审查 + 多轮漏洞修复)
|
||||
**开发计划状态:** ✅ v2.0 定稿(经 8+ 轮架构审查 + 架构转型:Fan-out → 散装派发 + Aggregator)
|
||||
|
||||
**v2.0 架构转型(2026-02-24):**
|
||||
|
||||
| 维度 | v1.5 Fan-out(已废弃) | v2.0 散装派发(当前) |
|
||||
|------|---------|---------|
|
||||
| 派发 | Manager Job → N × Child Job | API 层直接 `insert` N 个独立 Job |
|
||||
| Worker | Child Worker 修改父 Task 表(行锁争用) | Worker 只写自己的 Result(零行锁) |
|
||||
| 收口 | Last Child Wins(最后一个翻转 Task) | Aggregator 定时 `groupBy` 轮询收口 |
|
||||
| 僵尸清理 | 独立 Sweeper Cron | Aggregator 兼职(一人两职) |
|
||||
| 复杂度 | 13 条红线、18 项反模式 | **9 条红线,极简 Worker** |
|
||||
|
||||
**核心架构决策:**
|
||||
|
||||
| 决策 | 方案 |
|
||||
|------|------|
|
||||
| 异步任务 | pg-boss Fan-out(Manager → N × Child),非单体 Worker |
|
||||
| 并发控制 | `teamConcurrency` 三级限流(Child:10, MinerU:2, LLM:5) |
|
||||
| 幂等性 | Prisma `updateMany` 乐观锁(非 Read-then-Write) |
|
||||
| 任务终止 | Last Child Wins(最后一个 Child 翻转父任务状态) |
|
||||
| 异步任务 | **散装派发 + Aggregator 轮询收口**(API 直接派发 N 个 `asl_extract_single` Job) |
|
||||
| 并发控制 | `teamConcurrency: 10` 扁平单队列(Worker 内串行调 MinerU + LLM) |
|
||||
| API 幂等 | `idempotencyKey @unique` + Prisma P2002 冲突捕获 |
|
||||
| Worker 幂等 | `updateMany({ where: { status: 'pending' } })` 幽灵重试守卫 |
|
||||
| 任务收口 | **Aggregator** 定时轮询 `groupBy`(`pending === 0 && extracting === 0` → completed) |
|
||||
| 僵尸清理 | Aggregator 兼职(`extracting > 30min` → error) |
|
||||
| PDF 文件来源 | 对接 PKB 个人知识库(ACL 防腐层,非自建上传) |
|
||||
| 表格提取 | MinerU Cloud API(VLM 模型) + OSS Clean Data 缓存 |
|
||||
| 全文提取 | 直接复用 PKB `extractedText`(pymupdf4llm 产物) |
|
||||
| SSE 跨 Pod | PostgreSQL NOTIFY/LISTEN(不引入 Redis) |
|
||||
| 进度查询 | 前端 React Query 轮询 + 后端 `groupBy` 实时聚合 Result 状态 |
|
||||
| SSE 日志 | 本 Pod 内存事件(可选增强:NOTIFY/LISTEN 跨 Pod) |
|
||||
| Prompt 安全 | BEGIN/END 隔离 + XML 标签上下文污染防护 |
|
||||
| 数据一致性 | Manager 快照 PKB 元数据到 `AslExtractionResult` |
|
||||
| 数据一致性 | API 层快照 PKB 元数据到 `AslExtractionResult` |
|
||||
|
||||
**文档体系(5 份):**
|
||||
**文档体系(5 + 2 份):**
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| `08-工具3-全文智能提取工作台V2.0开发计划.md` | 架构总纲(v1.5,~1314 行) |
|
||||
| `08-工具3-全文智能提取工作台V2.0开发计划.md` | 架构总纲(v2.0) |
|
||||
| `08a-工具3-M1-骨架管线冲刺清单.md` | M1 Sprint(Week 1,5-6 天) |
|
||||
| `08b-工具3-M2-HITL工作台冲刺清单.md` | M2 Sprint(Week 2-3,8-9 天) |
|
||||
| `08c-工具3-M3-动态模板引擎冲刺清单.md` | M3 Sprint(Week 4,5-6 天) |
|
||||
| `08d-工具3-代码模式与技术规范.md` | 代码 Cookbook(9 章,~819 行) |
|
||||
| `08d-工具3-代码模式与技术规范.md` | 代码 Cookbook(9 章) |
|
||||
| `散装派发与轮询收口任务模式指南.md` | 🚀 **v2.0 核心参考**(通用能力层 Level 2) |
|
||||
| `分布式Fan-out任务模式开发指南.md` | 历史参考(Level 3,已不用于本模块) |
|
||||
|
||||
**里程碑规划:**
|
||||
|
||||
| 里程碑 | 核心交付 | 时间 |
|
||||
|--------|---------|------|
|
||||
| M1 骨架管线 | Fan-out 全链路 + PKB ACL + 纯文本盲提 + 极简前端 | Week 1 |
|
||||
| M2 HITL 工作台 | MinerU + 审核抽屉 + SSE 日志 + NOTIFY/LISTEN + Excel | Week 2-3 |
|
||||
| M1 骨架管线 | 散装派发 + Aggregator 全链路 + PKB ACL + 纯文本盲提 + 极简前端 | Week 1 |
|
||||
| M2 HITL 工作台 | MinerU + 审核抽屉 + SSE 日志 + Excel | Week 2-3 |
|
||||
| M3 动态模板引擎 | 自定义字段 + Prompt 注入防护 + E2E 测试 | Week 4 |
|
||||
|
||||
**13 条研发红线**:详见架构总纲文档尾注。
|
||||
**9 条研发红线**:详见架构总纲文档 M1 红线表。
|
||||
|
||||
**通用能力沉淀**:`docs/02-通用能力层/分布式Fan-out任务模式开发指南.md`
|
||||
**通用能力沉淀**:
|
||||
- 🚀 `docs/02-通用能力层/散装派发与轮询收口任务模式指南.md`(v1.1,Level 2 Cookbook)
|
||||
- 📖 `docs/02-通用能力层/分布式Fan-out任务模式开发指南.md`(v1.2,Level 3 参考)
|
||||
|
||||
### 智能文献检索 DeepSearch V1.x(2026-01-18 MVP完成)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user