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:
2026-02-24 22:11:09 +08:00
parent 85fda830c2
commit 371fa53956
13 changed files with 1163 additions and 597 deletions

View File

@@ -3,9 +3,10 @@
> **文档版本:** v2.1
> **创建日期:** 2025-11-21
> **维护者:** AI智能文献开发团队
> **最后更新:** 2026-02-23 🆕 **工具 3 全文智能提取工作台 V2.0 开发计划完成v1.56 轮架构审查**
> **最后更新:** 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-23V2.0 核心功能完成SSE 流式架构 + 段落化思考日志 + 引用链接可见化
> - 🆕 2026-02-22V2.0 前后端联调完成!瀑布流 UI + Markdown 渲染 + Word 导出 + 中文数据源测试
> - 🆕 2026-02-22V2.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.02026-02-23 开发计划完成,待编码)
### 🆕 工具 3 全文智能提取工作台 V2.02026-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-outManager → 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 APIVLM 模型) + 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 SprintWeek 15-6 天) |
| `08b-工具3-M2-HITL工作台冲刺清单.md` | M2 SprintWeek 2-38-9 天) |
| `08c-工具3-M3-动态模板引擎冲刺清单.md` | M3 SprintWeek 45-6 天) |
| `08d-工具3-代码模式与技术规范.md` | 代码 Cookbook9 章~819 行 |
| `08d-工具3-代码模式与技术规范.md` | 代码 Cookbook9 章) |
| `散装派发与轮询收口任务模式指南.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.1Level 2 Cookbook
- 📖 `docs/02-通用能力层/分布式Fan-out任务模式开发指南.md`v1.2Level 3 参考)
### 智能文献检索 DeepSearch V1.x2026-01-18 MVP完成