X_SSL_Net/docs/superpowers/plans/2026-06-14-xnet-conv2dgn-migration.md

XNet Conv2dGN Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将 XNet2d 主路径的 2D 卷积归一化从 BatchNorm 明确迁移为 GroupNorm，并统一命名为 Conv2dGN / DWConv2dGNReLU。

Architecture: 只替换 lib/modules/layers_2d.py 及其主线调用者中的 2D 卷积归一化层，不触碰 lib/modules/lib_mamba/vmamba.py 内部的 LayerNorm/BatchNorm 逻辑。采用自动组数选择的 GroupNorm，优先保证 2D 分割训练在大小 batch 下都稳定。

Tech Stack: PyTorch、GroupNorm、pytest、现有 XNet2d 训练与烟测入口

---

Task 1: 先收紧测试约束

Files:

• Modify: tests/test_xnet_2d.py

• [ ] 增加一条针对归一化实现的测试，验证 XNet2d 主路径中不再实例化 nn.BatchNorm2d。

• [ ] 先运行 pytest -q tests/test_xnet_2d.py，确认新测试先失败，再做实现替换。

Task 2: 实现 Conv2dGN 与 DWConv2dGNReLU

Files:

• Modify: lib/modules/layers_2d.py

• [ ] 增加自动 group 数选择 helper，优先 8 组，不能整除则递减到可整除，最差回退 1。

• [ ] 新增 Conv2dGN，用 Conv2d + GroupNorm 替代 Conv2dBN。

• [ ] 将 DWConv2dBNReLU 重命名并实现为 DWConv2dGNReLU。

• [ ] PatchMerging2d 等直接依赖层同步改用 Conv2dGN。

Task 3: 替换 XNet 调用点与模块导出

Files:

• Modify: lib/modules/xnet_2d.py

• Modify: lib/modules/__init__.py

• [ ] 将 xnet_2d.py 中所有 Conv2dBN 引用替换为 Conv2dGN。

• [ ] 将 __init__.py 中导出名称同步改成 Conv2dGN / DWConv2dGNReLU，不再保留旧 BN 名称。

Task 4: 运行测试并做 batch_size=1 烟测

Files:

• Modify as needed: tests/test_xnet_2d.py

• [ ] 运行 pytest -q tests/test_xnet_2d.py，确认通过。

• [ ] 运行 1 epoch 最小烟测，目标配置为 batch_size=1、64x64、validation.enabled=false。

• [ ] 若烟测仍失败，先确认是否还有残留 BatchNorm2d，而不是直接扩大 batch 规避。

Task 5: 更新当前主线文档

Files:

• Modify: README.md
• Modify: docs/method/XNet_method.md

• Modify: docs/training/当前项目详解与纯文本架构流程图.md

• [ ] 将当前主线路径中的 norm 描述改为 GroupNorm。

• [ ] 在方法和训练文档中简要说明：当前 2D 卷积主路径使用 GroupNorm，以支持更稳健的小 batch 与不固定 batch 训练。