CADx-4/research-wiki/explanation/结构.md

结构：代码分哪些模块、谁能依赖谁

来源：

• 负责人 2026-10-15：「我们后面发现其其实不需要（至少目前不需要）是一个工程产品，所以我觉得现在需要在本项目中重构一下」。
• 负责人 2026-10-15 选定检查强度「ClinDB 级」、注释用中文、本机为主（「目前以本地为主，以后会根据具体情况调整」）。
• 旧项目的研究内容：reference/CADx-4-CAD/research-wiki/explanation/agent-system.md、ceus-roi-pipeline.md、data-and-inputs.md。

本文是常青文档：模块划分变了就重写对应段落。为什么从产品改成研究原型、继承旧项目哪些东西，见 ../design/0001-从产品重构为研究原型.md。

一、从一个病例走一遍

先看数据怎么流过整个系统，再看代码怎么切。

医院按批次交付资料，病种的全称见 AGENTS.md「项目是什么」（目前是 data/交付包_20260908_40例/）。每个病例有三路资料：

• 临床：一张工作簿里的一行，性别、年龄、症状、既往史、抽血化验值。
• 超声：一段 CEUS 视频（U0xx_roi2.mp4）、一张医生截的关键图、一份超声报告。报告分「所见」（描述看到了什么）和「印象 / 结论」（医生的诊断倾向）两段。
• MR（磁共振）：一份 MR 报告文本。目前没有 MR 和 CT（计算机断层扫描）图像。

答案（病理结论）也在这些工作簿的某一列里，必须在读取的那一刻就分出去。

处理分四步：

1. CEUS 视频 → 定量结果。 超声机录造影时屏幕左右分成两半，一半是造影画面、一半是普通灰阶画面，先识别分屏、取出造影那半；医生在病灶上画了一个绿框，用它告诉程序病灶在哪；再用 MedSAM2（一个医学图像分割模型）把病灶轮廓逐帧追踪下去；病灶里的囊液不进造影剂、在造影画面上发黑，这部分（暗区）要扣掉，剩下的实性部分的平均亮度随时间的曲线就是 TIC。再用 Lognormal（对数正态）曲线拟合，取关键时刻的帧，算出 11 个灌注指标，如峰值强度、达峰时间、洗入速率（仿照商用造影定量软件 VueBOX 的口径；为什么选这套口径和 Lognormal 模型，见旧项目 design 0042、0043、0047，迁移时重写进本仓库）。这一步不涉及模型 API，只用本机显卡。
2. 整理三份输入。 每个病例分出三份互相看不见的输入：临床那份、超声那份（含第 1 步的定量结果、关键图和报告的「所见」段；关键帧图像给不给、怎么给，第 4 步定）、MR 那份（报告的「所见」段）。答案和医生的结构化判读列只进评价侧。
3. 会诊。 三个 AI 专家各读自己那份输入。按 2026-08-02 和临床方的会议纪要（双方共同认下的结论；纪要只写了顺序和「主要看超声与 MR 两路能否一致」，没写为什么这样排），流程是单轮顺序：超声专家先给影像信息和判断，MR 专家再给，临床专家补充临床信息；主要看超声和 MR 两路能否一致。
4. 评价。 拿会诊结论对病理金标准算准确率等指标；拿专家抽出的字段对医生的判读列算抽取准确率。

二、切分原则

模块按「以后可能会改的设计决定」切，每个模块把一个决定藏在里面，决定变了只改这一个模块（Parnas 1972 的信息隐藏）。不按上面的四步切，因为步骤会调整，而「交付包长什么样」「用哪个分割模型」这类决定和步骤无关。

另一条原则来自硬性约束 1：答案在哪、谁能读，由导入边界机器检查，不靠自觉。所以读金标准单独成一个模块，只有评价模块能导入它。

三、模块

层	模块	藏住的决定	旧项目对应	预期规模
入口	scripts/（不在包内）	一次研究步骤怎么组合：参数从哪来、产物写到哪个运行目录	debugs/*.py	每个 ≤ 300 行
组织	cadx.consult	会诊流程：几个专家、谁先说、看到别人的什么	无（从未实现）	600
组织	cadx.evaluate	指标口径、统计方法	无（已删除）	400
资料	cadx.cases	交付包的磁盘格式、列名、病例号形状、「结论」段怎么剔除、每路看得见哪些列	app/providers/clinical.py 等、input_readers.py	600
资料	cadx.gold	金标准在哪一列、数字编码对应哪一类（编码由临床方定，可能会改；取值只写在这个模块的代码里）	config/runtime.yaml 的 diagnosis_coding	100
外部	cadx.llm	用哪家模型服务、怎么调用、怎么记录请求和回复	model_gateway_config.py（只借思路）	300
外部	cadx.segment	用哪个分割模型（目前 MedSAM2）、权重在哪	debugs/medsam2_local_track.py	300
外部	cadx.runs	运行目录的命名、快照里记什么、单进程写锁	无	200
纯计算	cadx.ceus	ROI 与 TIC 的算法和参数：分屏、绿框、暗区、曲线、拟合、关键帧、灌注指标	app/domain/ceus_roi/（除 service.py）、app/providers/video_decoder.py	6000

规模是粗估，按旧项目同类代码的行数推算，每个模块的任务书动手前由负责人确认。cadx.ceus 偏大，是因为旧项目 app/domain/ceus_roi/ 共 8770 行，去掉编排和数据库实体（service.py 1440 行）后约 7.3k 行，迁移时再删掉只为产品层服务的部分（2026-10-15 用 wc -l 量）。

这里没有旧项目的数据库、HTTP 接口、任务队列、对象存储、迁移脚本。运行产物直接写成文件，放在 runs/ 下的运行目录里。

四、谁能依赖谁

上层可以导入下层，同一层的模块互不导入（例外：gold 只给组织层的 evaluate 用）：

入口      scripts/
组织      consult        evaluate
资料      cases          gold（只给 evaluate）
外部      llm   segment   runs
纯计算    ceus

具体边界：

• 只有 cadx.evaluate 能导入 cadx.gold。 这是硬性约束 1 的机器检查。会诊那一侧拿不到读金标准的函数，也就不可能把答案递给专家。
• cadx.consult 只经 cadx.cases 的公开接口拿输入包，不自己读工作簿。
• 只有 cadx.segment 导入 torch、sam2。torch 和 MedSAM2 将来装在同一个 uv 环境里（CEUS 迁移时加入，见 design 0001 第 7 条），但会诊和评价那一半的代码碰不到它们。
• 只有 cadx.llm 导入模型服务的 SDK。
• 只有 cadx.cases 和 cadx.gold 导入 openpyxl（读 Excel）。
• cadx.ceus 不导入 cadx 的其他模块。它只做计算和读视频，分割结果由调用方传进来。

这些边界写成 pyproject.toml 里的 import-linter 契约，随模块落地逐条加入：import-linter 对还不存在的模块无从检查。目前只有一条：cadx 整体不导入 torch、sam2；cadx.segment 落地时改成「除 cadx.segment 外」。

契约里没有的保护不要当成机器守住了。 比如 scripts/ 不在包内，import-linter 管不到它；一个脚本完全可以同时导入 gold 和 consult。脚本放在包外是有意的：「跑会诊再评分」这种组合天然要同时碰两边，放进包里也得给它开例外。所以脚本里的隔离靠审查，以及第 3 步的泄露扫描测试（直接检查发给模型的输入里有没有答案）。

每个模块是一个子包，内部文件加 _ 前缀，对外只经 __init__.py 的 __all__ 暴露。这样别的模块能用什么一眼可见，模块内部怎么改不牵连外面。

五、目录

位置	内容	进 git
src/cadx/	上面的模块	是
scripts/	研究步骤的入口脚本	是
tests/	测试；需要显卡的标 gpu，花钱的标 live	是
config/	算法参数、模型服务清单（只写环境变量名）	是
prompts/	版本化提示词	是
research-wiki/	文档，见其 README.md	是
data/	医院交付的原始资料	否
runs/	每次运行一个目录，含快照和全部产物	否
models/	模型权重（MedSAM2）	否
reference/	旧项目副本、外部代码仓库	否
reference-pdf/	文献原文	否

不进 git 的目录由 .gitignore 和 pre-commit（提交前自动运行的检查）里的 local-only-paths 一项两道拦截，git add -f 也提交不了。

六、推进顺序

1. 骨架（已完成）：协作规则、文档体系、工具链。
2. CEUS 定量：迁移 cadx.ceus、cadx.segment、cadx.runs 和对应脚本。验收标准是在本机复现旧项目的 40 例 ROI 追踪与 TIC 结果和 1.2-TEST（只有 1 例，但它是唯一带造影剂到达时间的病例）的 Lognormal 回放，逐例对比旧产物。旧产物还在远程，对比要用的摘要和轨迹文件在那份任务书里按需拉取，视频不拉。
3. 资料与答案隔离：cadx.cases、cadx.gold，加上泄露扫描测试（输入包里不出现金标准、结论段、病例号）。
4. 会诊：cadx.llm、cadx.consult。动手前要先定模型服务。
5. 评价：cadx.evaluate。

第 2 步和第 3 步互不依赖，可以换顺序。

七、还没定的事

• 用哪家模型服务。 旧项目经实验室的模型调用库 PolyGateway 调通义千问；更早的讨论选过 Claude Agent SDK。第 4 步任务书里定。
• 专家先抽事实再判断，还是一步出判断。 旧项目设计过两段式（先抽出可追溯的医学事实，再据此判断四分类），抽出的事实还能拿来对医生判读列算抽取准确率；但一行代码都没写。第 4 步讨论。
• 医生标注工作簿（见 AGENTS.md 硬性约束 1）。40 例的标注工作簿还没交付，Lognormal 回放需要的造影剂到达时间（AT）和注射时间在里面。到之前只有 1.2-TEST 的 1 例能做完整回放。
• 分屏里造影画面在左还是在右。 旧项目 40 例跑通 34 例；失败的 6 例里 3 例（013、029、036）是左半边找不到绿框，013 已确认造影画面在右半边，配置却写死取左边；另 3 例（007、011、033）是分屏中缝对比度不够、识别失败（出自旧项目远程 data/交付包_20260908_40例_result/结果清单_20261016.md，2026-10-15 读过）。是否自动判别左右未定。