# 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 训练。