# XNet 文档校准设计

## 1. 目标

本次工作的目标不是改动 `XNet2d` 代码，而是把仓库内所有与 `XNet` 相关的主线文档、索引文档、阶段汇报、handoff 和 archive 文档校准到当前实现状态，避免旧设计描述继续被误读为当前代码事实。

当前代码事实以以下文件为准：

- `lib/modules/xnet_2d.py`
- `lib/trainers/supervised.py`
- `tests/test_xnet_2d.py`
- `configs/segmentation/*.yaml`
- `configs/segmentation/optimized/*.yaml`

## 2. 已确认的实现事实

当前 `XNet2d` 的主结构应描述为：

```text
CNN-Wavelet-VMamba encoder + plain U-Net skip decoder + segmentation head
```

需要统一反映到文档中的关键信息如下：

1. encoder 仍然是 `local + wavelet + global(SS2D)` 三分支的 `XTEB2d`。
2. bottleneck 仍使用 `XTEB2d`。
3. decoder 已不再使用历史版本中的 diagonal guide / cross-scale guide 路径。
4. 当前 decoder 是普通 U-Net 同尺度 skip 融合，核心 block 是 `XCRB2d`。
5. `guide_mode` 仍存在于配置与 trainer 参数中，但只用于兼容旧 YAML，不参与当前 decoder 前向逻辑。
6. `forward()` 仍返回 `guides` 字段，但当前固定为空列表，用于兼容旧调试接口。
7. decoder 可选 `frequency refine` 仍然是当前 active 实现的一部分。
8. 测试已经显式约束“输出尺寸保持不变”和“decoder 不再含有 `guide*` 模块”。

## 3. 文档更新范围

### 3.1 主线文档

这些文档直接更新为“当前实现说明”：

- `README.md`
- `docs/README.md`
- `docs/method/XNet_method.md`
- `docs/training/当前项目详解与纯文本架构流程图.md`
- 视需要补充 `docs/experiments/` 与 `docs/operations/` 中对 `guide_mode`、消融项和训练入口的表述

### 3.2 历史文档

以下文档不重写其历史结论，但逐篇加上“当前实现对照说明”：

- `docs/archive/20260504_220523_xnet_vmamba_cleanup_archive.md`
- `docs/archive/20260505_xnet_active_cleanup_archive.md`
- `docs/handoff/2026-05-27_x_ssl_net_handoff.md`
- `docs/handoff/2026-05-30_x_ssl_net_optimized_training_handoff.md`
- `docs/report/2026-05-06_XNet项目阶段汇报.md`
- `docs/report/2026-05-27_x_ssl_net_status_report.md`
- `docs/method/XNet_encoder_vs_MobileMamba_encoder_2026-05-31.md`

## 4. 历史文档补充格式

对历史文档采用统一补充格式：

```text
## 当前实现对照说明
- 当时文档中的哪些结构描述现在仍然有效
- 哪些表述已经失效
- 当前代码中对应的真实实现位置
- 读者应优先参考哪些 active 文档
```

其中“已失效内容”重点包括：

- `X-shaped decoder` 作为当前实现表述
- diagonal guide / cross-scale guide 仍参与 decoder 前向
- `guide_mode` 仍控制 active decoder 模块

## 5. 产出原则

1. 保留历史文档的时间语境，不伪造“当时就已经是当前实现”。
2. 所有“当前状态”描述必须能回溯到代码、测试或配置。
3. 主线文档优先给出结论，历史文档优先给出对照说明。
4. 全部新增或改写内容使用中文。

## 6. 验证方式

完成后进行以下检查：

1. 搜索 `docs/`、`README.md` 中是否仍把当前实现直接表述为 active `X-shaped decoder`。
2. 搜索是否仍有未说明语境的 `guide_mode`、`diagonal guide`、`XGuideProjector2d`、`XGuideModulation2d`。
3. 确认主线文档与 `tests/test_xnet_2d.py` 的约束一致。