X_SSL_Net/docs/archive/20260505_xnet_active_cleanup_archive.md

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 是：

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

当前主模型是：

lib/modules/xnet_2d.py::XNet2d

当前模型定位：

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 字段，例如：

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() 返回：

{
    "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. 下一步建议

优先跑最小训练闭环：

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 消融