X_SSL_Net/docs/superpowers/specs/2026-06-13-xnet-doc-alignment-design.md

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 的主结构应描述为：

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. 历史文档补充格式

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

## 当前实现对照说明
- 当时文档中的哪些结构描述现在仍然有效
- 哪些表述已经失效
- 当前代码中对应的真实实现位置
- 读者应优先参考哪些 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 的约束一致。