docs: 架构定稿——四段流水线、两个库与待定问题

负责人 2026-10-16 定：数据流为「医院原始资料->中间文件->给专家的资料库 & 标准答案库」；
两个库和中间文件都用文件夹，SQLite 只用于调模型账本；调模型用 PolyGateway；CEUS 直接逐个
迁移；数据格式和口径以 40 例交付包为准。存储与迁移方案先由两个中立子 Agent 独立评审。

- design 0002：八条决定及负责人原话（化名与打乱顺序一条为 Agent 提出）
- explanation/结构.md 对照 ClinDB 的结构文档重写：切分原则、完整范围、12 个模块与依赖、
  边界、两个库与 CEUS 中间文件的内容、目录与检查、规模、推进顺序
- research-wiki/待定问题/：绿框、参数冻结、排除标准、跨表不一致四个问题；定了就删
- AGENTS.md：事实来源加「交付资料的格式和口径以最新交付包为准」
- .gitignore 与 pre-commit 拦截 library/、answers/、work/

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

research-wiki/design/0002-四段流水线与两个库.md

@@ -0,0 +1,39 @@
+# 0002 四段流水线与两个库
+
+状态：决定 1–6、8 负责人 2026-10-16 认可（原话见各条）；决定 7 是 Agent 提出、负责人未单独表态 ｜ 日期：2026-10-16
+
+## 先认识几个词
+
+- **给专家的资料库**：AI 专家能看到的一切都在这里，专家也只读这里。
+- **标准答案库**：病理金标准、医生标注表等，只给评价用。
+- **中间文件**：从原始资料到两个库之间的工作产物，主要是 CEUS 的分割结果和曲线，可以删掉重算。
+- **CEUS、TIC**：超声造影视频；时间-强度曲线，即视频里病灶平均亮度随时间的变化。
+- **关键帧**：从上千帧的 CEUS 视频里挑出的 7 张图，交给超声专家看。B0（刚开始变亮前）、D1（开始变亮）、D2（洗入拐点）、D3（最亮）、D4（洗出拐点）从 TIC 的拟合曲线上算；F1、F2 是推注后第 20、60 秒，按推注时间取。
+- **AT**（到达时间）：医生判断的「造影剂流到病灶、病灶开始变亮」的时刻，写在医生标注工作簿里。
+- **账本**：每次调用模型时把请求、回复、花费按顺序记下来的 SQLite 文件，只追加、不修改。
+- **中立评审**：2026-10-16 派出的两个互相独立的子 Agent，拿到同样的事实、不带讨论倾向，各自读旧代码和参考项目后给出建议。原始报告未存档，下文引用的证据都可在 `reference/` 和参考项目里核对。
+
+## 背景
+
+`design/0001` 定下按研究原型重写之后，2026-10-15 到 16 日深读了旧项目的三条线（CEUS 算法、资料与答案隔离、会诊与评价），据此提出四段流水线。负责人对整体形状的理解是：「医院原始资料->中间文件（可以有可以没有）->「给专家的资料库」（给agent的东西都在里面）&「标准答案库」（我们自己用来评估的金标准的标准答案等）」，存储介质等不确定的项交中立评审分析。
+
+## 决定
+
+1. **四段流水线，段与段之间只通过磁盘上的文件交接。** 四段是：CEUS 定量（视频 → 中间文件）、装配两个库（原始资料 + CEUS 结果 → 两个库）、会诊（只读给专家的资料库）、评价（读会诊结果和标准答案库）。四段的成本差别很大：CEUS 定量要用显卡，装配只用 CPU，会诊调模型要花钱，评价几乎免费，分开之后改评价指标不必重新调模型，改拟合参数不必重跑 GPU。另有一个总入口按顺序调用四段。负责人认可了这个形状（见「背景」里的原话），两位评审也都这样建议。
+2. **两个库和中间文件都用文件夹，不用数据库。** 负责人原话：「两个库和缓存都用文件夹」。评审给出的理由：专家看到的就是文字和图片，文件夹能直接打开检查专家到底看到了什么；三路各一个子目录，天然互相隔开；旧项目把隔离做在数据库里，结果不得不专门写程序扫描「读取代码会不会顺着引用摸到答案表」（旧 `tests/leakage_scan.py`）。
+3. **调模型用实验室的 PolyGateway**（`https://gitea.iomgaa.online/iomgaa/PolyGateway`），每次会诊运行一份 SQLite 只追加账本，请求和回复全文按内容哈希另存为文件。负责人原话：「调用模型直接用https://gitea.iomgaa.online/iomgaa/PolyGateway」。用 SQLite 的理由来自两位评审：测重复运行的一致性时，同一病例、同一专家要重复调用多次，每一次（第 1 次、第 2 次……）都必须恰好记一次，中断后续跑时不漏也不重，这靠数据库的事务和唯一键最省事；ClinDB-ReviewBench 有一份约 270 行的现成实现（`src/clindb/ledger/`）可以借鉴。两位评审也都指出，按几千次调用的规模，JSONL 文件同样撑得住，选 SQLite 是为了数据正确，不是为了性能。PolyGateway 怎么安装（直接从 Gitea 装，还是像 ClinDB 那样放一份 wheel 在 `vendor/`）在写会诊任务书时定。
+4. **CEUS 代码直接逐个模块迁移，不在本机重跑旧代码作对比基线。** 负责人原话：「“本机重跑旧代码作基线”不需要，直接一个个迁移就好」。迁移是否正确靠两样东西保证：随模块带过来的旧算法单测（旧项目约 274 个，不依赖数据库），以及每个模块迁移后对照旧代码逐段核对行为。迁移时按旧 debug 脚本（实际跑出 40 例结果的那几个脚本）的行为为参照，以下几处已知问题在对应模块的任务书里逐条决定改不改，改了就单独记录：
+   - 程序要把左半边造影画面上的绿框换算到右半边画面上，再交给 MedSAM2 当「病灶在这里」的提示。换算用的映射锚点按 1856 宽的素材写死成像素坐标（旧 `config/ceus_roi_default.yaml` 的 `mapping` 段、旧 `tests/unit/test_roi_contract.py:51`），而 40 例的视频有 5 种分辨率，提示会被平移约 −195 到 +165 像素，分割就从偏了的位置开始（两位评审各自用旧代码算出，未目视确认）。这个偏差在旧结果里不显眼，因为最终病灶轮廓有 75% 直接取自绿框本身（见 `待定问题/01`）；
+   - 旧 debug 路径不裁画面黑边、识别分屏只用 25 帧抽样、整段视频读进内存，旧 `service.py`（旧产品的编排代码）则相反，两者结果可能不同；
+   - 造影画面在右半边的病例找不到绿框。
+5. **数据的格式和口径以 40 例交付包为准。** 负责人原话：「因为数据改过很多版，所以你们需要对齐“40例交付包”那个。我知道程序开发的时候用的是1.2-TEST那个，但那其实也是老版程序过期的一个地方」。所以：
+   - 超声报告工作簿的「推注开始时间s」是**视频第 0 秒时已经推注了多少秒**（负责人 2026-10-16 说明）。F1、F2 分别取视频第 20 − X 秒和 60 − X 秒（X 为该值）。旧项目的 design 0046（`reference/CADx-4-CAD/research-wiki/design/`）把它读成「推注发生在视频第 X 秒」，那是按 `1.2-TEST` 定的口径，不沿用。
+   - `1.2-TEST` 只作参考样本保留，主要用处是看医生标注工作簿模板长什么样；它的列名、编码、时间口径都不作数。
+6. **AT 目前没有来源，B0、D1 由程序从 TIC 曲线上算。** 40 例交付包里没有 AT，40 例的医生标注工作簿尚未交付。将来标注工作簿到了，其中的 AT 进标准答案库，用来检验程序算出的时刻准不准，不用来挑关键帧：标注工作簿属于答案那一侧，用它挑出的图交给专家，等于医生的判断渗进了专家资料，而且「程序算的时刻和医生标的差多少」这项检验也就失去了意义。旧回放脚本用医生 AT 当 D1（旧 `app/domain/ceus_roi/anchor_frames.py:199-206`），新代码不复现这条路。
+7. **给专家的病例用化名，并打乱顺序；化名与真实病例号的对照只放在标准答案库。** 交付文件名里就带着病例号（如 `U001_roi2.mp4`）；旧项目的资料曾按诊断分组录入，顺序本身就会暗示答案。这条是评审建议、Agent 提出，负责人未单独表态，写在这里备查。
+8. **还没定的研究问题（目前是 01–03 三个研究问题，另有 04 待医生回答）记在 `research-wiki/待定问题/`，一个问题一份文件，定了就删，结论写进 `design/`。** 负责人原话：「研究层面的三个问题晚点再定，你可以在research-wiki中建立一个文件夹专门记录这种问题，处理完一个删除一个」。
+
+## 不做的事
+
+- 不把旧项目在远程跑出的 40 例结果拉回本机做逐例对比（随决定 4 放弃）。
+- 不为中间文件的每一个阶段都做跨运行复用。中间文件全部写进 `work/`，但评审建议只有最贵的 GPU 分割结果按参数复用，其余阶段每次重算；其他阶段要不要复用，等实测耗时之后再说。