# XNet 当前主线清理与文档同步归档（2026-05-05）

## 当前实现对照说明

这份文档记录的是 2026-05-05 当时的 active 认知，其中大部分训练主链整理结论仍然有效，但模型结构表述需要按当前代码重新理解。

- 仍然有效的部分：
  - 训练主链仍是 `tools/train.py -> SupervisedSegmentationTrainer -> XNet2d -> seg_logits`；
  - `lib/sam2`、`lib/SwinTransformer` 仍保留但不进入当前分割训练主链；
  - `XNet2d.forward()` 继续返回 `logits`、`seg_logits`、`encoder_features`、`decoder_features`、`guides`。
- 已失效的部分：
  - 文中将当前模型定位为 active `X-shaped CNN-Wavelet-VMamba hybrid network`；
  - 当时使用的脚本入口 `tools/run_us_experiments.sh` 已删除；
  - `guides` 不再代表任何 active decoder guide 分支输出。
- 当前代码真实状态：
  - 当前模型应表述为 `tri-branch encoder + plain U-Net skip decoder`；
  - `guide_mode` 只保留兼容作用；
  - 当前推荐入口是 `tools/run_optimized_supervised.sh`。
- 当前优先参考：
  - `README.md`
  - `docs/method/XNet_method.md`
  - `docs/operations/Start.md`

## 1. 本轮目标

本轮清理目标是让代码、配置和 `tmp/docs` 与当前项目真实主线一致。

明确约束：

1. 不删除 `lib/sam2`
2. 不删除 `lib/SwinTransformer`
3. 清理当前训练主链不再使用的旧代码与旧配置
4. 将 active 文档改成围绕 `XNet2d + VMamba-style SS2D` 的当前项目说明

## 2. 当前主线

当前 active training path 是：

```text
tools/train.py
-> SupervisedSegmentationTrainer
-> XNet2d
-> seg_logits
-> segmentation loss
```

当前主模型是：

```text
lib/modules/xnet_2d.py::XNet2d
```

当前模型定位：

```text
2D ultrasound supervised segmentation with tri-branch CNN-Wavelet-VMamba encoder and plain U-Net skip decoder
```

## 3. 保留但不进入主链的目录

以下目录按用户要求保留：

1. `lib/sam2`
2. `lib/SwinTransformer`

它们当前不被 `SupervisedSegmentationTrainer` 调用，也不出现在当前 segmentation config 中。

## 4. 配置清理

当前保留的 segmentation 配置只有：

1. `configs/segmentation/train_sup_us_template.yaml`
2. `configs/segmentation/us_exp_sup_busi.yaml`
3. `configs/segmentation/us_exp_sup_busi_ablation.yaml`

这三份配置的 `model` 段已统一切到 XNet 字段，例如：

```yaml
encoder_channels: [32, 64, 128, 192]
encoder_depths: [2, 2, 2, 2]
decoder_channels: [128, 64, 32]
use_wavelet_branch: true
use_frequency_refine: true
ssm_backend: auto
```

旧的 SwinV2 segmentation 配置和 `configs/swinv2/*.yaml` 已从 active config 中移除。

## 5. 代码清理

当前监督 trainer 只构建 `XNet2d`，并且只训练 `seg_logits`。

本轮移除或收缩了：

1. `SupervisedSegmentationTrainer` 中未训练的 `aux_boundary_head` 构造入口
2. `XNet2d` 中的辅助 boundary head
3. `lib/tools/boundary.py`
4. `lib/tools/loss.py` 中未被当前 trainer 使用的边界损失类

当前 `XNet2d.forward()` 返回：

```python
{
    "logits": logits,
    "seg_logits": logits,
    "encoder_features": encoder_features,
    "decoder_features": decoder_features,
    "guides": guides,
}
```

## 6. 文档更新

本轮更新的 active docs：

1. `tmp/docs/README.md`
2. `tmp/docs/training/当前项目详解与纯文本架构流程图.md`
3. `tmp/docs/operations/Start.md`
4. `tmp/docs/experiments/一键实验脚本使用说明.md`
5. `tmp/docs/experiments/实验结果汇总脚本说明.md`
6. `tmp/docs/method/XNet_method.md`
7. `tmp/docs/method/lib_mamba_source_note.md`

其中训练详解文档已从旧的 SwinV2 baseline 描述改为当前 XNet 主链。

## 7. 验证

已完成：

1. Python 编译检查
2. YAML 配置字段检查
3. active 代码与 active docs 中旧 SwinV2 配置字段扫描

当前只保留一处 `vmambanew.py` 字样，位于 `lib_mamba_source_note.md`，用途是说明当前不是基于 MobileMamba 改写版。

## 8. 下一步建议

优先跑最小训练闭环：

```bash
DATASET=BUSI EXTRA_SET_ARGS="train.epochs=2 train.batch_size=2 train.val_batch_size=2 logging.use_swanlab=false" bash tools/run_us_experiments.sh
```

如果训练链路稳定，再做：

1. `DDTI`
2. `TN3K`
3. `TG3K`
4. wavelet branch 消融
5. frequency refine 消融
6. SS2D backend 消融