CADx-4/research-wiki/任务书/03-医生核对包.md

任务书 03：医生核对包

目标

把一次构建（library/ + answers/）和它装入的那次 CEUS 运行，整理成医生不用写代码就能看懂的一个文件夹：表格一律 CSV，文字一律 PDF，图和视频原样。负责人把文件夹打成压缩包、用 U 盘拷给医生，请医生核对我们的处理结果。

这是一项长期功能：以后医生每交一版数据，跑完 ceus_quant 和 build，再跑一次本入口，就得到新的核对包。所以按正式模块写，带测试和 guide，不写成一次性脚本。

来源：负责人 2026-10-17「我们把处理完的结果……整理一份給医生看看」「不需要问医生问题」「文本文件尽可能 pdf，表格尽可能 csv」「需要作为一项长期的功能……有一个入口能执行这个」；视频不压缩（「本来视频就模糊，你压缩不是更模糊」）；病例目录用医生的病例号、问题清单只写现象、没进库的病例只在表里出现（负责人 2026-10-17 认可）。

不做什么

• 不向医生提问，不做反馈表。
• 问题清单只写程序观察到的现象，不写原因推测、不写我们查过的文献、不写建议。
• 不改 CEUS 算法、不改质量门、不改资料库的内容。质量门的去留等医生看过之后再定（文献核查记录在 research-wiki/scratch/2026-10-17-TIC拟合约束文献核查/，本任务不用读）。
• 不压缩视频，不缩放、不重新编码任何图片和视频。

核对包的内容

runs/review_pack/<运行号>/
  snapshot/                        快照（不给医生，打包时由负责人去掉；见下文）
  医生核对包_<构建号>/              负责人整个打包的就是这个目录
    说明.pdf
    问题清单.csv
    病例总表.csv
    标准答案/
      化名对照.csv
      诊断.csv
      跳过病例.csv
      报告复核句.csv
    病例/
      <病例号>/                    只有进了资料库的病例，目录名用医生的病例号（如 P001）
        临床信息.csv
        超声报告.pdf
        MR报告.pdf
        关键图.png
        关键帧/<槽位>_第<秒>秒.png  例如 B0_第1.6秒.png；秒数保留一位小数；没定位的槽位没有文件
        TIC曲线.png
        TIC结果.csv
        回放视频.mp4

逐项要求：

• CSV：UTF-8 带 BOM（Excel 双击打开中文不乱码），列名用中文。缺失值留空，不写 null、NaN。
• 病例总表.csv：这次构建涉及的全部病例一例一行（进库的加跳过的；40 例交付包就是 40 行），按病例号排序。列：病例号、视频号、化名（没进库的留空）、是否进入资料库、没进的原因（检查编号和说明）、CEUS 定量是否成功、CEUS 失败在第几步、7 个槽位各一列（取到写视频时间秒数，没取到写「未取到」，CEUS 失败或没装 CEUS 时留空）。
• 问题清单.csv：列为病例号、视频号、环节、问题。按病例号排序，一个病例可以多行。来源和写法见下文「问题清单的来源」。
• 标准答案/：答案库的 4 张表照原样转成上面的 CSV 规格，列名不改。诊断编码和其他编码列照原值写；说明文件里写明编码含义（诊断 1 IPMN、2 SPN、3 MCN、4 SCN，出自交付包表头；其他编码列写「未解码」，解码开关见 build.yaml）。
• 临床信息.csv：资料库临床一路的字段，一行；列名用交付包原列名。
• 超声报告.pdf、MR报告.pdf：资料库里的报告原文（就是 AI 专家看到的那段，结论段已被程序去掉），PDF 第一行写「病例号 Pxxx 超声描述（结论段已去除）」之类的标题，正文照抄不改字。
• 关键图.png、关键帧/：从资料库拷贝（已去附加数据的那份），逐字节不变，只改文件名。
• TIC曲线.png、回放视频.mp4：从 CEUS 运行目录逐字节拷贝。
• TIC结果.csv：把资料库的 tic.json 摊平成「项目、值」两列的长表：四条曲线各自的拟合是否成功和 R²、灌注指标逐项、紫圈曲线是否可用、7 个槽位的状态与时间或原因。项目名用中文加原字段名，例如「病灶整体曲线 拟合成功（roi_all.success）」。
• 没装 CEUS 结果的构建（ceus_run 为 null）也能出包：没有关键帧、TIC 曲线、TIC 结果、回放视频，病例总表里 CEUS 各列留空，说明文件写明这次没有 CEUS 结果。

问题清单的来源

每条都能追到某个已有文件里的某个值，不另做判断：

环节	来源	写法
装配资料库	答案库的跳过清单	检查说明 + 涉及的文件、列和值，原样写
CEUS 第 N 步	CEUS 运行的 failed.csv	「第 N 步失败：」+ 原因原文
TIC 拟合	tic.json 里病灶整体、病灶去暗区两条曲线 success 为 false	「病灶整体曲线未完成拟合」（去暗区同理）；原因码（如 parameter_on_boundary）照写在括号里，并在说明文件里逐个解释每个原因码的意思
关键帧	tic.json 里没定位的槽位	「B0 未取到：」+ reason 原文
紫圈	pan_curve_usable 为 false	「紫圈曲线不可用」

报告复核句（标准答案/报告复核句.csv）不进问题清单，单独成表。

说明.pdf

源文件是仓库里的一份版本化 Markdown 模板（放在 src/cadx/review/ 下，随代码走），出包时填入这次的构建号、CEUS 运行号、病例计数，再转成 PDF。至少写清：

1. 这个包是什么、从哪次交付数据处理来（构建号、CEUS 运行号、生成日期）；包里含患者资料，只在临床方与我们之间传递。
2. 目录结构，每个文件是什么。
3. 每张 CSV 每一列的意思。
4. 我们的处理流程，用医生能懂的话分步讲（读交付包和检查 → CEUS 的第 1–9 步各做什么 → 装进资料库），问题清单里「环节」一列的每种取值对应哪一步。
5. 7 个关键帧各代表什么时刻、怎么取（B0、D1–D4 来自拟合曲线，F1、F2 按推注时间取），以及「未取到」的几种原因。
6. TIC 曲线图怎么看：每条线是什么（图上标注是英文，在这里逐个对照成中文）、竖线是什么。
7. 化名是什么、为什么有；报告里的结论段为什么被去掉（AI 专家不能看到医生的诊断倾向）；资料库只放「所见」。
8. 编码列的含义（诊断编码，以及「未解码」的列）。
9. 跳过病例为什么整例跳过、每例只记第一项没过的检查。

转换工具：pandoc 把 Markdown 转成 docx，再用 soffice --headless --convert-to pdf 转 PDF（本机都有，中文字体用已装的 Noto CJK）。报告 PDF 用同一条路。两个工具的版本记进快照。工具缺失直接报错。

怎么实现

模块

新建组织层模块 review（src/cadx/review/），藏住「核对包长什么样」这个决定：目录布局、每个文件的格式、问题清单的来源与写法、说明模板。

• 依赖：library（按化名读出各路）、answers（读 4 张表）、runs（读快照、读 CEUS 运行，见下）。不依赖 build、delivery、ceus。
• 它读的是已经构建好的 library/ 和 answers/，不碰交付包。病例总表里的 40 例 = 答案库的化名对照 + 跳过清单。
• 只有 library 能引用 PIL：review 拷图片只按字节拷，不打开图片。

CEUS 运行目录的读取挪进 runs。 现在 build 的 _ceus.py 自己读 runs/ceus/<运行号>/ 的布局（failed.csv、summary.json、关键帧），review 也要读。按 结构.md 第三部分「出现第二个使用者再收进模块」，把读 CEUS 运行目录（打开运行、读 failed.csv、按视频号找结果目录和其中的文件）收进 runs，build 和 review 都经 runs 读。tic.json 挑哪些字段仍只在 build 里列（可见性的唯一决定处不动）。挪完 build 的行为不变，原有测试照过。

入口

scripts/review_pack.py --config config/review_pack.yaml。配置（字段定义在 review，全部必填）：

• library_dir、answers_dir：某次构建的资料库和答案库目录，两者目录名（构建号）必须相同，不同就报错；
• output_root：runs/review_pack。

CEUS 运行从资料库 manifest.json 的 CEUS 来源字段读，不另配。

运行目录先写 .partial，跑完改名，已存在报错（规则同前两份任务书）。快照记 git 状态、配置原文、构建号、CEUS 运行号、pandoc 和 soffice 版本。快照放在 医生核对包_<构建号>/ 外面，负责人只打包里面那个目录。

终端只打印计数：病例数、问题清单行数（按环节分）、PDF 份数、拷贝的视频总大小、耗时。不打印病例号。

规模

部分	预期行数
review（含说明模板以外的代码）	300–500
scripts/review_pack.py	≤ 80
runs 增量（读 CEUS 运行）	≤ 150，build 相应减少

测试

预期值照本任务书写，不从实现里推。用现有的假交付包和假 CEUS 运行（tests/fake_delivery.py、tests/fake_ceus_run.py）构建一次，再出包：

• 目录结构与上面一致；进库病例每例一个目录、名为病例号；跳过的病例没有目录、在病例总表和问题清单里有。
• 每张 CSV 以 BOM 开头、列名与本任务书一致、缺失值为空串。
• 问题清单：每种来源至少各造一例，断言行数和「环节」「问题」原文。
• 关键图、关键帧、TIC 曲线、回放视频与源文件逐字节相同；关键帧文件名的秒数等于 tic.json 里的 video_time_s 保留一位小数。
• TIC结果.csv 的值与 tic.json 逐项相同。
• ceus_run 为 null 的构建也能出包，CEUS 相关文件都不存在。
• 资料库与答案库构建号不同时报错。
• 说明和报告 PDF 生成成功、非空（这条依赖 pandoc 和 soffice，照常进 make check；如果让 make check 多出 30 秒以上，在报告里写明耗时，不自行加标记跳过）。
• build 原有测试全部照过（CEUS 运行读取挪进 runs 之后）。

真跑

用当前真实构建 20261016-094248-1de88a5-dirty 出一次包。报告：运行号、病例数、问题清单按环节分的行数、包的总大小、耗时；挑 1 个病例目录和 说明.pdf 的路径供负责人目视检查。不在报告里写病例号以外的任何病例内容。

文档

• 新写 research-wiki/guides/医生核对包.md：什么时候跑、怎么跑、产物在哪、打包前去掉 snapshot/。过一轮「硕士生阅读」。
• 结构.md：第三部分加 review（组织层，可依赖 library、answers、runs），依赖表和 import-linter 契约同步；第四部分加核对包一节（指向本任务书和 guide，不抄布局）；第五部分配置表加 review_pack.yaml；第六部分加规模；第八部分加对外接口。
• WORK_LOG.md。

审阅

「其余部分」那一档，写完派一个全新上下文的子 Agent 审一轮：只给本任务书、结构.md 第三到第五部分和 diff。重点：问题清单有没有漏掉某个来源、有没有写进推测性的话；拷贝是否逐字节；CEUS 运行读取挪进 runs 后 build 行为是否不变；review 有没有写进 library/ 或 answers/（不许）。Codex 连不上就跳过。

报告

1. 提交号；各部分行数。
2. make check 完整输出。
3. 真跑结果（见上）。
4. 审阅意见和处理。
5. 和本任务书、结构.md、AGENTS.md 不一致的地方，以及为什么。