feat(review): 医生核对包入口；CEUS 运行目录的读取收进 runs

- 新模块 review（组织层，只依赖 library、answers、runs）：把一次构建和它装入的
  CEUS 运行整理成医生可读的文件夹（CSV 带 BOM、说明与报告转 PDF、图片视频逐字节拷贝），
  入口 scripts/review_pack.py + config/review_pack.yaml。任务书 03。
- 读 CEUS 运行目录（failed.csv、结果目录、关键帧文件）从 build 挪进 runs，build 与
  review 都经它读；failed.csv 读取在边界上收严（步号须为整数、视频号不重复、列数固定）。
- library、answers 补只读函数；import-linter 增 review 契约。
- 文档：guides/医生核对包.md（过一轮硕士生阅读），结构.md 第三至八部分同步。

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

research-wiki/explanation/结构.md

@@ -98,10 +98,11 @@ runs/ceus/<运行号>/ ────► ② 装配两个库             config/bu
 
 | 层 | 模块 | 藏住的决定 | 旧项目里的对应内容 |
 | --- | --- | --- | --- |
-| 入口 | `scripts/`（不在包内） | 人怎么操作：每段一个脚本（`ceus_quant`、`build`、`consult`、`evaluate`），另有一个按顺序调用四段的总入口；读配置文件，把模块装配起来 | `debugs/t1_local_debug.py`、`debugs/tic_lognormal_replay.py` |
+| 入口 | `scripts/`（不在包内） | 人怎么操作：每段一个脚本（`ceus_quant`、`build`、`consult`、`evaluate`），另有一个按顺序调用四段的总入口，以及出医生核对包的 `review_pack`；读配置文件，把模块装配起来 | `debugs/t1_local_debug.py`、`debugs/tic_lognormal_replay.py` |
 | 组织 | build | 两个库怎么装配：每一路放哪些内容（可见性的唯一决定处）、化名怎么取（化名随机，资料库按化名排序，顺序就与交付顺序无关）、清单记什么。全项目只有它同时碰得到原始资料和答案 | `app/domain/input_readers.py`、`ingestion*.py` 的装配部分 |
 | 组织 | consult | 会诊怎么进行：几个专家、谁先说、后发言的看得到前面的什么、什么时候结束；「调一次模型」的统一入口（先存请求、记开始、调用、存回复、记结束）也在这里 | 没有 |
 | 组织 | evaluate | 评价口径：指标、统计方法、字段级对照怎么计分 | 没有（`core/eval` 已删） |
+| 组织 | review | 给医生的核对包长什么样：目录布局、每个文件的格式（表格 CSV、文字 PDF、图和视频原样拷贝）、问题清单的来源与写法、说明模板。只读已构建好的两个库和那次 CEUS 运行，不写它们、不碰交付包 | 没有 |
 | 格式 | library | 给专家的资料库的目录布局、文件格式和读取；按路分别读出，一路一个对象 | `app/domain/input_packages.py` 的数据形状 |
 | 格式 | answers | 标准答案库的目录布局、文件格式和读取 | 旧库里的金标准表 |
 | 格式 | verdicts | 会诊产物（各路意见、会诊结论）的文件格式和读取；consult 写、evaluate 读 | 没有 |
@@ -109,7 +110,7 @@ runs/ceus/<运行号>/ ────► ② 装配两个库             config/bu
 | 外部 | segment | 用哪个分割模型、权重在哪、怎么在显卡上把提示传播成逐帧掩码 | `debugs/medsam2_local_track.py`、`roi_inference/` 的后端 |
 | 外部 | llm | 经 PolyGateway（实验室的模型调用库，管外部错误的重试和超时）调模型；交出服务商返回的精确版本号、响应编号、用量、结束原因。只管调用，不写账本 | `app/providers/model_gateway_config.py`（只借思路）；ClinDB 的 `llm/` |
 | 外部 | ledger | 账本怎么存：SQLite 只追加、大块内容按哈希存成文件、同一目录同时只许一个进程写、找出开始了没结束的调用 | 没有；ClinDB 的 `ledger/` |
-| 外部 | runs | 运行目录怎么命名、运行快照记什么（git 提交号、配置、所用构建、提示词哈希、模型版本、随机种子） | 没有 |
+| 外部 | runs | 运行目录怎么命名、运行快照记什么（git 提交号、配置、所用构建、提示词哈希、模型版本、随机种子）；一次 CEUS 定量运行目录（`runs/ceus/<运行号>/`）的布局和读取，build 和 review 都经它读 | 没有 |
 | 纯计算 | ceus | CEUS 定量的全部算法和参数：分屏、绿框、坐标映射、多边形、暗区、TIC 采样、Lognormal 拟合、关键帧、灌注指标、出图；视频解码也在这里 | `app/domain/ceus_roi/`（除 `service.py`）、`app/providers/video_decoder.py` |
 
 暂不设共用词汇模块。一样东西要被两个互相不能引用的模块用到，才另立一处放它；目前跨模块的类型各有归属（资料库格式归 library、答案格式归 answers、会诊产物格式归 verdicts）。配置的字段定义和校验归使用它的模块：CEUS 参数归 ceus（旧 `research_config.py`），会诊的实验配置归 consult；每个字段必填，不补默认值（`AGENTS.md`「不设默认值」）。
@@ -118,7 +119,7 @@ runs/ceus/<运行号>/ ────► ② 装配两个库             config/bu
 
 ```
 入口      scripts/
-组织      build        consult        evaluate
+组织      build        consult        evaluate        review
 格式      library      answers        verdicts
 外部      delivery     segment   llm   ledger   runs
 纯计算    ceus
@@ -133,6 +134,7 @@ runs/ceus/<运行号>/ ────► ② 装配两个库             config/bu
 | build | delivery、ceus（读 CEUS 结果的类型）、library、answers、runs |
 | consult | library、verdicts、llm、ledger、runs |
 | evaluate | answers、verdicts、runs |
+| review | library、answers、runs |
 | scripts/ | 任何模块（不在导入检查范围内，见第五部分） |
 
 ### 几条边界
@@ -142,6 +144,8 @@ runs/ceus/<运行号>/ ────► ② 装配两个库             config/bu
 - **三路互相隔开。** 每个专家的提示词只用自己那一路的对象拼。consult 里拼某一路提示词的函数只接收那一路的对象，不接收整个病例。这是研究设计本身：模拟各科医生各看各的检查结果，再在会诊时交换意见。会诊时一路能看到另一路的什么，由 consult 的会诊流程决定，在会诊的任务书里定。
 - **我们自己调模型只有一个入口：consult 的「调一次模型」。** 它按固定顺序做五步：把完整请求存进账本的大块存储、写「调用开始」、经 llm 调用、把完整回复存进大块存储、写「调用结束」。llm 只管调用，不写账本，所以任何一次模型调用都绕不开登记。中断后重启时，从账本找出开始了没结束的调用，记为「状态未知」，不重做已有结果的调用。做重复运行（同一病例、同一专家调多次，测一致性）时，每一次都恰好登记一次。
 - **CEUS 算法不知道分割模型是谁，也不管中间文件放哪。** ceus 接收视频路径、参数和分割结果，交出曲线、拟合、关键帧和指标；中间文件写在哪、按什么复用，由 `scripts/ceus_quant.py` 决定（目前只有它一个使用者，出现第二个使用者再收进模块）。segment 只管「给提示、出逐帧掩码」，不认识分屏和绿框。
+- **CEUS 运行目录只有 runs 认得。** `failed.csv`、`summary.json`、关键帧、TIC 曲线图、回放视频各在运行目录的哪里，由 runs 读出；build 和 review 都经它读，不各自拼路径（任务书 03：出现第二个使用者，就把读取收进模块）。`summary.json` 里挑哪些字段给专家仍只在 build 决定。
+- **核对包只读不写。** review 读某次构建的 `library/`、`answers/` 和资料库记的那次 CEUS 运行，输出只写进 `runs/review_pack/<运行号>/`；不写两个库、不读交付包。核对包里有答案和真实病例号，是给医生的，不是给会诊的。
 - **医生的判断不进 CEUS 定量。** 医生标注工作簿里的时刻（如造影剂到达时间 AT）属于标准答案库，ceus 和 build 都不读它；关键帧全部由程序自己算或按推注时间取（design 0002 决定 6）。交付视频里医生画的绿框是 CEUS 定量的输入，它能否作为输入、在最终病灶轮廓里占多大分量，记在 `../待定问题/01-医生画的绿框能否作为输入.md`。
 - **评价只读文件，不重新调模型。** evaluate 读 `runs/` 里的会诊产物（经 verdicts）和 `answers/`，改指标或统计方法不需要重跑会诊。
 
@@ -192,6 +196,10 @@ library/<构建号>/
 - 跳过清单：没进资料库的病例、没过的那一项检查、涉及的文件和列，以及对不上的各表原值，供医生核对。40 例里已知有 6 例临床表与超声表对不上（`../待定问题/04-交付数据的跨表不一致.md`），会出现在这份清单里；
 - 将来加医生标注工作簿。
 
+### 医生核对包（`runs/review_pack/<运行号>/`）
+
+把一次构建的两个库和它装入的那次 CEUS 运行，整理成医生不用写代码就能看的一个文件夹（表格 CSV、文字 PDF、图和视频逐字节拷贝），由负责人打包交给临床方核对我们的处理结果。病例目录用医生的病例号，问题清单只写程序观察到的现象；包里有真实病例号、报告原文和诊断，只在临床方与我们之间传递。它不是流水线的一段：不产出任何后续段要读的东西，医生每交一版数据、跑完 CEUS 定量和装配之后出一次。包内布局和每个文件的格式见 `../任务书/03-医生核对包.md` 和包里的 `说明.pdf`，怎么跑见 `../guides/医生核对包.md`。
+
 ### CEUS 定量的产物（`runs/ceus/` 与 `work/`）
 
 每次运行的产物写进 `runs/ceus/<运行号>/`，只追加；全量运行之前的配准目视核对写进 `runs/ceus_align/<运行号>/`（图、`key.csv`、判读、`review.csv`），ceus_quant 按 `review.csv` 拦下核对没通过的病例；第 3 步的分割结果按下表的键缓存在 `work/`，可以删掉重算。具体布局见 `../任务书/02-CEUS定量.md`。
@@ -240,7 +248,7 @@ X 是超声报告工作簿的「推注开始时间s」，含义是视频第 0
 | `data/` | 医院交付的原始资料 | 否 |
 | `library/`、`answers/` | 两个库，每次构建一个目录 | 否 |
 | `work/` | 可以删掉重算的中间文件，目前只有分割缓存 | 否 |
-| `runs/` | CEUS 定量、会诊与评价的运行，只追加不删 | 否 |
+| `runs/` | CEUS 定量、医生核对包、会诊与评价的运行，只追加不删 | 否 |
 | `models/` | 模型权重 | 否 |
 | `reference/`、`reference-pdf/` | 旧项目副本、外部代码、文献原文 | 否 |
 
@@ -255,6 +263,7 @@ X 是超声报告工作簿的「推注开始时间s」，含义是视频第 0
 | `build.yaml` | `scripts/build.py` | `delivery_dir`（交付包位置）、`library_root`、`answers_root`（两个库的上级目录）、`alias_seed`（生成化名的随机种子）、`decode_codes`（编码解码开关）、`code_maps`（映射表位置或 null）、`ceus_run`（CEUS 运行目录或 null）；字段定义和校验在 `src/cadx/build/_config.py`，逐项说明见 `../guides/装配两个库.md` |
 | `code_maps.yaml` | build（经 `build.yaml` 引用） | 编码映射表：交付包里每个用数字编码的列，每个数字代表什么（如性别的 1、2）。还没向临床方拿到，尚未建 |
 | `ceus.yaml` | `scripts/ceus_quant.py`、`scripts/ceus_align_review.py` | CEUS 定量的全部参数和配准目视核对的出图设置，每个参数用注释写明出处 |
+| `review_pack.yaml` | `scripts/review_pack.py` | `library_dir`、`answers_dir`（同一次构建的两个库，构建号必须相同）、`output_root`（核对包运行目录的上级）；用哪次 CEUS 运行从资料库清单读，不另配；字段定义和校验在 `src/cadx/review/_config.py`，逐项说明见 `../guides/医生核对包.md` |
 | `consult.yaml` | `scripts/consult.py` | 会诊的实验配置与模型用途 |
 | `evaluate.yaml` | `scripts/evaluate.py` | 评价的指标与统计设置 |
 
@@ -270,16 +279,17 @@ X 是超声报告工作簿的「推注开始时间s」，含义是视频第 0
 
 文件格式：数组用 npz（读取时 `allow_pickle=False`，pickle 读取时会执行任意代码），每例的标量和摘要用 json，跨病例的表用 csv，图用 png。缺失值写 null，不写 NaN 或 0：0 是合法的测量值，NaN 在 json 里不合法。
 
-导入边界用 import-linter 检查，写进 `make check`。契约在 `pyproject.toml`，检查范围是 `src/cadx`，**不含 `scripts/` 和 `tests/`**。下面只列契约实际强制的（共 8 条），没有的保护不写：
+导入边界用 import-linter 检查，写进 `make check`。契约在 `pyproject.toml`，检查范围是 `src/cadx`，**不含 `scripts/` 和 `tests/`**。下面只列契约实际强制的（共 9 条），没有的保护不写：
 
 - `cadx` 里只有 segment 引用 `torch`、`sam2`（契约逐个列出其余已落地的模块，新模块落地时加进去）。
 - segment 不引用其他 `cadx` 模块。
 - delivery、library、answers、runs 互不引用。
-- delivery、library、answers、runs 不引用其他 `cadx` 模块（build 和规划中的各模块）。
+- delivery、library、answers、runs 不引用其他 `cadx` 模块（build、review 和规划中的各模块）。
 - ceus 不引用其他 `cadx` 模块（含 segment：分割结果由 `scripts/ceus_quant.py` 传进来）。
 - build 不引用 delivery、library、answers、runs 以外的 `cadx` 模块（ceus 落地时放行）。
+- review 不引用 library、answers、runs 以外的 `cadx` 模块（不碰交付包，不依赖 build 和 ceus）。
 - 只有 delivery 引用 `openpyxl`（交付包的 Excel 只有它碰）。
-- 只有 library 引用 `PIL`（写资料库的图片时去掉元数据）。
+- 只有 library 引用 `PIL`（写资料库的图片时去掉元数据；review 拷图片只按字节拷，不打开）。
 
 第三部分依赖表的其余部分和下面几条外部库独占，随模块落地逐条写成契约（import-linter 只能检查已经存在的模块）：只有 llm 引用 `polygateway`；只有 ledger 引用 `sqlite3`。
 
@@ -302,16 +312,17 @@ Python 环境用 uv；安装与检查命令见 `../guides/开发环境.md`。
 | ceus | 6000–7500（基本照搬旧算法，去掉只为产品层服务的部分） | 7103 | `ceus_roi/` 除 `service.py` 7330，`video_decoder.py` 135 |
 | segment | 150–300 | 300 | `medsam2_local_track.py` 240 |
 | delivery | 400–700 | 739 | `clinical.py` 266、`modalities.py` 522、`workbook.py` 99、`delivery.py` 134，共 1021，其中入库与数据库部分不迁 |
-| library | 150–300 | 354 | `input_packages.py` 104 |
-| answers | 100–200 | 201 | — |
+| library | 150–300 | 377 | `input_packages.py` 104 |
+| answers | 100–200 | 227 | — |
 | verdicts | 100–200 | — | — |
-| build | 300–500 | 564（含装入 CEUS 结果的 `_ceus.py`） | `input_readers.py` 329 的装配部分 |
+| build | 300–500 | 535（含装入 CEUS 结果的 `_ceus.py`；读 CEUS 运行目录已挪进 runs） | `input_readers.py` 329 的装配部分 |
 | llm | 200–450 | — | ClinDB `llm/` 415 |
 | ledger | 200–300 | — | ClinDB `ledger/` 274 |
-| runs | 100–250 | 109（只含快照部分） | — |
+| runs | 100–250 | 202（快照 `_snapshot.py` 98、读 CEUS 运行的 `_ceus_run.py` 83、`__init__.py` 21） | — |
 | consult | 500–1000（会诊口径定后重估） | — | — |
 | evaluate | 300–600（评价口径定后重估） | — | 已删的 `core/eval` 622 |
-| scripts/ 每个 | ≤ 300 | `build.py` 37、`scan_library.py` 88、`ceus_quant.py` 403（超出，含目视核对表的读取与核对、开跑即写快照）、`ceus_align_review.py` 243 | `t1_local_debug.py` 762、`tic_lognormal_replay.py` 627 |
+| review | 300–500 | 587（`_pack.py` 395、`_pdf.py` 118、`_config.py` 64、`__init__.py` 10；不含说明模板 `readme_template.md` 202 行） | — |
+| scripts/ 每个 | ≤ 300 | `build.py` 37、`scan_library.py` 88、`ceus_quant.py` 403（超出，含目视核对表的读取与核对、开跑即写快照）、`ceus_align_review.py` 243、`review_pack.py` 37 | `t1_local_debug.py` 762、`tic_lognormal_replay.py` 627 |
 
 ---
 
@@ -351,6 +362,7 @@ Python 环境用 uv；安装与检查命令见 `../guides/开发环境.md`。
 - `LibraryCase`：要写进资料库的一例：化名、临床一路的字段、超声描述、关键图源文件、MR 描述、CEUS 部分（`LibraryCeus` 或 None）。
 - `LibraryCeus`：一例超声一路的 CEUS 部分：build 挑好的 tic.json 内容、槽位 → 关键帧源图。
 - `list_aliases(build_dir)`：一次构建的全部化名（按化名排序）。
+- `read_build_info(build_dir)`：读构建清单的概况，交出 `BuildInfo`：构建号、编码列是否解码、装入的 CEUS 运行号（没装为 None）。
 - `read_clinical(build_dir, alias)`、`read_ultrasound(build_dir, alias)`、`read_mr(build_dir, alias)`：按路读出一例，读时核对 SHA-256，拒绝 `.partial` 目录。
 - `ClinicalRoute`：临床一路：是否已解码、22 列字段。
 - `UltrasoundRoute`：超声一路：报告「所见」原文、关键图路径、tic.json 的内容（没装 CEUS 时为 None）、槽位 → 关键帧路径（没装时为空）。
@@ -365,15 +377,19 @@ Python 环境用 uv；安装与检查命令见 `../guides/开发环境.md`。
 - `DiagnosisRow`：化名、病例号、三张表的诊断编码、诊断名（不解码时为 None）。
 - `SkippedRow`：跳过清单的一行，字段同 `SkipRecord`。
 - `ReviewRow`：复核清单的一行：化名、路（「超声」或「MR」）、命中的词、所在句子。
-- `read_aliases(answers_dir)`、`read_diagnoses(answers_dir)`：评价用的读取，读时核对 SHA-256 和表头，拒绝 `.partial` 目录。
+- `read_aliases(answers_dir)`、`read_diagnoses(answers_dir)`、`read_skipped(answers_dir)`：读化名对照、诊断、跳过清单，读时核对 SHA-256 和表头，拒绝 `.partial` 目录；跳过清单的文件和列两栏拆回元组。
+- `verified_file(answers_dir, name)`：答案库里某个文件（如 `snapshot/build.yaml`）的路径，先核对它与清单的 SHA-256 一致；给需要原样拷贝或读快照的使用者（review）用。
 
-### runs（`src/cadx/runs/`，目前只有快照部分）
+### runs（`src/cadx/runs/`）
 
 - `read_git_state(repo_root)`：读出完整和短提交号、工作区是否干净（含未跟踪文件）、`git diff HEAD` 输出的 SHA-256。
 - `GitState`：上面这四项。
 - `make_build_id(now, git)`：构建号 `YYYYMMDD-HHMMSS-<git 短哈希>`，工作区不干净时末尾加 `-dirty`。
 - `write_snapshot(snapshot_dir, build_id, git, started_at, uv_lock, configs)`：开跑时调。新建快照目录，复制配置原文并写 `snapshot.json`（构建号、git 状态、Python 版本、`uv.lock` 哈希、开始时间、各配置的哈希）。运行要跑很久时（CEUS 定量约一小时）在开跑时写，期间改了配置文件，快照里仍是这次用的那份。
 - `finish_snapshot(snapshot_dir, finished_at, record)`：收尾时调。在快照目录里新建 `finished.json`：结束时间加 `record`（运行结束才知道的值，如显存峰值、缓存命中数）；已存在就报错，不改开跑时写的文件。
+- `open_ceus_run(run_dir)`：打开一次已完成的 CEUS 定量运行：核对目录存在、不是 `.partial`、有 `snapshot/snapshot.json`，读快照里的 `ceus.yaml` 和 `failed.csv`（表头、步号、视频号不重复），交出 `CeusRun`。
+- `CeusRun`：运行号、目录、快照里的整份 `ceus.yaml`、`failed`（视频号 → `CeusFailure`）；按视频号取文件：`has_result`（有没有结果目录）、`summary`（`summary.json`，核对里面记的视频号与目录一致）、`keyframes`（槽位 → 关键帧图路径）、`tic_png`、`overlay`。
+- `CeusFailure`：`failed.csv` 的一行：失败在第几步、原因原文。
 
 ### ceus（`src/cadx/ceus/`）
 
@@ -413,3 +429,10 @@ Python 环境用 uv；安装与检查命令见 `../guides/开发环境.md`。
 - `load_build_config(path, repo_root)`：读并校验 `build.yaml`，相对路径按仓库根目录解析。
 - `load_code_maps(path)`：读映射表并做 T5（恰好覆盖 17 项，性别映射到「男」「女」，诊断映射到四个亚型缩写）。
 - `make_aliases(case_nos, seed)`：病例号排序后依次抽 4 位化名，同种子同病例得到同样的化名。
+
+### review（`src/cadx/review/`）
+
+- `run_review_pack(config_path, repo_root, now)`：出一次医生核对包：读配置，经 library、answers 读这次构建，经 runs 打开资料库记的那次 CEUS 运行（路径取自答案库快照里的 `build.yaml`，运行号须与资料库清单一致），先写进 `<运行号>.partial/` 再改名，交出 `PackSummary`。`now` 是本地时间，定运行号。
+- `PackSummary`：供终端打印的计数：运行目录、核对包目录、病例数（进库、跳过）、按环节分的问题清单行数、PDF 份数、拷贝的视频总字节数；不含病例号。
+- `ReviewPackConfig`：`review_pack.yaml` 的字段定义（pydantic，字段必填、不许多写、读入后不可改）。
+- `load_review_config(path, repo_root)`：读并校验 `review_pack.yaml`，相对路径按仓库根目录解析；两个库的目录名（构建号）不同就报错。