# 开发环境

读者：第一次在本机搭环境的人。

## 一、前提

- [uv](https://docs.astral.sh/uv/)（Python 包和环境管理工具），本机 `~/.local/bin/uv`。
- Python 3.12：uv 会按 `.python-version` 自动准备，不需要另装。

## 二、同步环境

```bash
make sync          # 按 uv.lock 建 .venv 并安装依赖
uv run pre-commit install   # 每次提交前跑 gitleaks、本地材料拦截和格式检查
```

## 三、日常命令

| 命令 | 做什么 |
|---|---|
| `make fmt` | ruff 自动修正并格式化 |
| `make test` | 不花钱、不需要显卡的测试 |
| `make check` | lint、格式、类型（pyright strict）、导入边界（import-linter）、测试，依次执行，失败即停 |

需要显卡的测试用 `uv run pytest -m gpu`，花钱的真实模型测试用 `uv run pytest -m live`，都不在 `make check` 里。

## 四、数据和本地材料

以下目录不进 git，新机器上要自己准备：

| 目录 | 从哪来 |
|---|---|
| `data/` | 远程 `wangwenhan@202.38.247.58:CADx-4-CAD/data/` 下的 `交付包_20260908_40例`、`1.2-TEST`，用 rsync 同步 |
| `reference/CADx-4-CAD/` | 旧项目：先 rsync 工作区（排除 `data/`），再 `git fetch` 远程 `CADx-4` 仓库的全部分支恢复历史 |
| `reference/MedSAM2/` | MedSAM2 代码（连同 `.git`），见下一节 |
| `models/` | MedSAM2 权重 `MedSAM2_latest.pt`，见下一节 |

远程服务器走 `202.38.247.58`，不走 Tailscale 地址 `100.83.164.94`：同一台机器，后者慢几百倍。

## 五、MedSAM2（CEUS 分割用）

MedSAM2 是医学图像分割模型（GitHub `bowang-lab/MedSAM2`），CEUS 定量的第 3 步用它把几帧的病灶提示传播到整段视频。它以可编辑方式装进项目环境，代码放在 `reference/MedSAM2/`，`src/cadx/segment` 在同一进程里 `import sam2` 调用。位置写在 `config/ceus.yaml` 的 `segment` 段。

**1. 拷代码和权重**（两种情况都要做；代码和权重都不进 git）：

```bash
# 代码：连同 .git 一起拷（提交号从这个 .git 读），不要 checkpoints/ 和 data/，约 25MB
rsync -a --exclude checkpoints/ --exclude data/ \
    wangwenhan@202.38.247.58:/home/wangwenhan/MedSAM2/ reference/MedSAM2/
# 权重：只要这一个文件，约 156MB
mkdir -p models
rsync -a wangwenhan@202.38.247.58:/home/wangwenhan/MedSAM2/checkpoints/MedSAM2_latest.pt models/
```

远程的代码是 `bowang-lab/MedSAM2` 的 332f30d 提交，只改了 `download.sh`，不影响代码。

**2. 装进环境**，分两种情况：

- **仓库里已有 `uv.lock` 且已含 `medsam2`**（`pyproject.toml` 的依赖里有 `medsam2`，平常就是这种）：拷完代码后 `make sync`（即 `uv sync`）就会按锁文件装上 torch 和 MedSAM2。
- **第一次把 MedSAM2 加进项目**（`pyproject.toml` 里还没有 `medsam2`）：

  ```bash
  SAM2_BUILD_CUDA=0 uv add --editable reference/MedSAM2
  ```

  `SAM2_BUILD_CUDA=0` 表示不编译 MedSAM2 的 CUDA 扩展（旧项目也没用它）。命令会改 `pyproject.toml` 和 `uv.lock`。

`uv sync` 时同样要设 `SAM2_BUILD_CUDA=0`（`SAM2_BUILD_CUDA=0 uv sync`），否则重新构建 `medsam2` 时会尝试编译 CUDA 扩展。

**代理太慢时**：torch 的轮子有几个 GB，走代理可能很慢。可以临时绕开代理直连国内镜像：

```bash
env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY \
    UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/ \
    SAM2_BUILD_CUDA=0 uv sync      # 第一次加进项目时把 uv sync 换成 uv add --editable reference/MedSAM2
```

镜像地址只在这一条命令里临时用，不写进 `pyproject.toml`；`uv add` 会把镜像地址写进 `uv.lock` 里各个包的来源，装完要把这些地址换回 `https://pypi.org/simple`（以及对应的 `files.pythonhosted.org` 下载地址），再跑一次 `uv lock --check` 确认锁文件和 `pyproject.toml` 一致。

**3. 确认 torch 看得到显卡**：

```bash
uv run python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```

应打印 torch 版本、`True` 和显卡名。最后跑 `uv run pytest -m gpu -v`：在一段合成小视频上真跑一次 MedSAM2。运行时会出现几条警告（注意力内核回退；`sam2/_C.so` 里的连通域后处理报 `inputs must be a CUDA tensor` 后被跳过），MedSAM2 自己说明这不影响主要结果，测试仍应 `passed`。