iomgaa
1f7a6a3d9c
从产品重构为研究原型的第一步（负责人 2026-10-15：「其其实不需要（至少目前不需要） 是一个工程产品」）。协作环境照 ClinDB-ReviewBench（负责人点名参考）。 - AGENTS.md 为唯一规则，CLAUDE.md 只引用它；硬性约束保留旧项目的答案隔离、各路隔离， 加上数字可追溯、花钱先报预估等 - WORK_LOG.md 记当前状态与负责人的关键决定 - research-wiki：README、explanation/结构.md（8 个模块、依赖边界、推进顺序）、 design/0001（为什么重构、继承与放弃什么、单一 uv 环境）、guides/开发环境.md - 三份新文档过了一轮「硕士生阅读」并按意见修订 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
51 lines
7.0 KiB
Markdown
51 lines
7.0 KiB
Markdown
# 0001 从产品重构为研究原型
|
||
|
||
状态：负责人 2026-10-15 认可（方案在终端讲过，负责人逐项选定后回复「同意」） ｜ 日期：2026-10-15
|
||
|
||
## 先认识几个词
|
||
|
||
- **旧项目**：远程服务器 `100.83.164.94` 上的 `/home/wangwenhan/CADx-4-CAD`（分支 `feat/ceus-tic-cad`，366 个提交），本仓库的前身。本地副本在 `reference/CADx-4-CAD/`。
|
||
- **T1**：旧项目对「CEUS 视频 → ROI 追踪 → TIC 曲线」这条链路的叫法。
|
||
- **S0–S3**：旧项目对会诊流水线的分段：S0 整理并隔离输入，S1 各路抽取医学事实，S2 各路给出判断，S3 三路讨论。
|
||
- **产品层**：为了把系统做成服务而写的代码：HTTP 接口、数据库与迁移、任务队列、对象存储、模型网关治理。
|
||
|
||
## 背景
|
||
|
||
负责人 2026-10-15：「我觉得远程服务器……上的 /home/wangwenhan/CADx-4-CAD 弄的有点过于复杂了。因为我们后面发现其其实不需要（至少目前不需要）是一个工程产品，所以我觉得现在需要在本项目中重构一下。」
|
||
|
||
2026-10-15 对旧项目的盘点（只读，原始报告未存档，下列路径都可在 `reference/CADx-4-CAD/` 核对）：
|
||
|
||
- `app/` 共 17,283 行（`wc -l`）。其中真正的研究成果是 `app/domain/ceus_roi/`（8770 行）：分屏识别、绿框识别、坐标映射、暗区检测、TIC、Lognormal 拟合、关键帧、灌注指标。这些文件除 `service.py` 外不依赖数据库和接口。
|
||
- 其余绝大部分是产品层：`app/api/`、`persistence/`、`storage/`、`workers/`、`container.py`、`ports.py`、`migrations/`、`roi_inference/`（把 MedSAM2 包成 HTTP 服务）等。
|
||
- 会诊（S1–S3）和评价**一行代码都没有**：`app/agents/` 从未建立，评价代码已删除。
|
||
- 40 例 T1 批量结果实际是由 `debugs/t1_local_debug.py` 和 `debugs/medsam2_local_track.py` 绕过接口、数据库直接调用算法跑出来的，而这两个脚本没进 git，`debugs/tic_lognormal_replay.py` 也有未提交的改动。
|
||
- `CLAUDE.md` 33KB，大部分是文档权威、迁移不可改、多轮审查等产品治理规则。
|
||
|
||
也就是说，产品层占了一半代码和大部分规则，却没有被实际的研究用到；研究真正走的是绕过它的脚本。
|
||
|
||
## 决定
|
||
|
||
1. **本仓库按研究原型重写，不做产品。** 没有数据库、HTTP 接口、任务队列和对象存储；运行产物写成文件放在 `runs/` 的运行目录里。以后真要做成产品，那时再按产品需求设计。
|
||
2. **旧项目整体复制为只读参考。** `reference/CADx-4-CAD/` 含完整 git 历史和没进 git 的 `debugs/` 脚本，不进本仓库的 git。研究数据只同步两批：`交付包_20260908_40例` 和 `1.2-TEST`（唯一带造影剂到达时间的那 1 例），放在 `data/`。旧项目的 T1 结果（约 12G，主要是叠加视频）能重新生成，不整批同步；CEUS 迁移验收要对比的摘要和轨迹文件届时按需拉取。
|
||
3. **算法代码迁移，产品层不迁移。** 迁移 `app/domain/ceus_roi/`（除 `service.py`）、`app/providers/video_decoder.py` 和三个 `debugs/` 脚本，改写成 `cadx.ceus`、`cadx.segment` 和 `scripts/`。读交付包的列白名单、病例号规范化、剔除报告结论段这些逻辑，在 `cadx.cases` 里按普通函数重写。
|
||
4. **协作规则与文档体系照 ClinDB-ReviewBench 的做法。** ClinDB-ReviewBench 和 dissect3 是负责人另外两个研究项目，协作环境运转良好，负责人点名参考。 规则只写一份 `AGENTS.md`，`CLAUDE.md` 只引用它；进度在 `WORK_LOG.md`；文档在 `research-wiki/`，常青文档改了就重写，design 写完冻结。旧项目的硬性约束里只保留研究本身需要的几条（答案隔离、各路隔离、患者资料、密钥、不吞错误），再加上 ClinDB 的两条（数字可追溯到真跑、花钱先报预估）；产品治理规则不保留。负责人在两档之间选定「ClinDB 级」检查：ruff（代码规范）、pyright strict（类型检查）、import-linter（导入边界）、pre-commit（gitleaks 查密钥、拦截本地材料）；不要 dissect3 那样每次提交都要有审查凭证的提交闸。理由（Agent 提的）：研究原型改动频繁，提交闸的成本高于它在这里防住的风险。
|
||
5. **注释和 docstring 用中文。** 负责人选定；负责人和合作的读者都以中文为母语，注释要讲清「为什么」，母语写得准。代码标识符仍用英文，给模型的提示词用英文。
|
||
6. **本机为主。** 负责人原话：「目前以本地为主，以后会根据具体情况调整」。本机有一张 RTX 4070 Ti SUPER 16GB，够跑 MedSAM2 的 tiny 版本。
|
||
7. **一个 uv 环境，torch 也装在里面，由导入边界隔离。** 负责人问过 MedSAM2 是否一定要单独环境；查过 MedSAM2 的 `setup.py`，它只依赖 `torch>=2.5.1`、`torchvision`、`numpy>=2.0.1`、`hydra-core`、`iopath`、`pillow`、`SimpleITK`、`tqdm`，和本项目其他依赖不冲突，CUDA 扩展可用 `SAM2_BUILD_CUDA=0` 关掉。旧项目拆成三个 conda 环境，理由是把分割做成了 HTTP 服务；现在不做服务，这个理由不成立，拆开只会多出子进程通信和两套环境。隔离改由 import-linter 契约保证：只有 `cadx.segment` 能导入 `torch` 和 `sam2`。以后真出现依赖冲突再拆，那时调用点只有这一个模块。负责人回复「同意」。torch 等依赖在 CEUS 迁移那份任务书里加入，本次骨架不装。
|
||
8. **旧 design 的编号不继承。** 旧项目 `research-wiki/design/0001–0049` 留在 `reference/` 里当历史。与研究有关的结论，在本仓库对应模块落地时重新写成 explanation 或新的 design；新文档可以注明「出自旧 design 00NN」，但现行规则以本仓库为准。理由：旧 design 里大量内容依附于数据库和服务，直接当权威会把产品层的约束带回来。需要重写时优先读下表这几份：
|
||
|
||
| 旧编号 | 主题 | 落到本仓库的哪一步 |
|
||
| --- | --- | --- |
|
||
| 0015、0024 | CEUS ROI 的 CPU 流水线、视频流式解码 | CEUS 定量 |
|
||
| 0030、0031 | TIC 定量与关键帧、临床口径与工程编码分开 | CEUS 定量 |
|
||
| 0042–0049 | VueBOX 差距分析、Lognormal 拟合、截图就绪判定、Excel 定时的关键时刻、11 个灌注指标、三线 TIC 图 | CEUS 定量 |
|
||
| 0026 | 标注工作簿只归评价侧、证据边界 | 资料与答案隔离 |
|
||
| 0041 | 不做图像遮蔽 | 资料与答案隔离 |
|
||
| 0033–0036 | S1 三路证据的设计（从未实现） | 会诊 |
|
||
| 0006 | 会诊辩论机制（已被 2026-08-02 纪要的单轮顺序流程取代） | 会诊 |
|
||
|
||
## 不做的事
|
||
|
||
- 不复刻旧项目的数据库表结构、处理状态机和按数据库记录派发任务的机制。旧项目推迟待办的几件数据库修补（视频状态列、坏视频重跑等）随产品层一起放弃。
|
||
- 不迁移 `tests/fitness`、`tests/contract`、`tests/integration`、`tests/e2e`：它们测的是产品层。`tests/unit` 里 `ceus_roi` 相关的测试在迁移时挑着带过来。
|