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

XNet 文档校准 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 相关的主线文档、索引文档、实验说明和历史文档统一校准到当前代码实现，并为历史文档补充“当前实现对照说明”。

Architecture: 先以 lib/modules/xnet_2d.py、lib/trainers/supervised.py、tests/test_xnet_2d.py、configs/segmentation/*.yaml 为事实来源，更新 active 文档的当前实现描述；再为 archive、handoff、report 等历史文档增加统一格式的对照说明，明确哪些内容仍有效、哪些已过时。

Tech Stack: Markdown、ripgrep、git、仓库现有 Python/XNet 代码结构

---

Task 1: 更新主线文档与索引

Files:

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

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

• [ ] 明确根 README 的项目定位，补一段当前 active XNet2d 主链说明。

• [ ] 修正文档索引中失效或不存在的条目，并把 active 主线说明统一成 “tri-branch encoder + plain U-Net decoder”。

• [ ] 检查 docs/method/XNet_method.md 是否还存在与当前代码不一致的接口、配置或输出描述，有则改为和代码一致。

• [ ] 在训练详解文档显式强调 guide_mode 仅用于兼容旧 YAML，guides=[] 仅用于兼容旧接口。

Task 2: 更新实验与运行说明文档

Files:

• Modify: docs/experiments/一键实验脚本使用说明.md
• Modify: docs/experiments/优化配置训练流程说明.md
• Modify: docs/experiments/实验结果汇总脚本说明.md

• Modify: docs/operations/Start.md

• [ ] 检查这些文档中的训练入口、结果路径、XNet 结构表述是否与当前脚本和代码一致。

• [ ] 为消融说明补一条约束：当前 active 消融集中在 wavelet branch、frequency refine、ssm_backend 等，不再包含 decoder guide path 消融。

• [ ] 如文档提到 guide_mode，补充“兼容字段、不影响当前 decoder 前向”的说明。

Task 3: 为历史文档补“当前实现对照说明”

Files:

• Modify: docs/archive/20260504_220523_xnet_vmamba_cleanup_archive.md
• Modify: docs/archive/20260505_xnet_active_cleanup_archive.md
• Modify: docs/handoff/2026-05-27_x_ssl_net_handoff.md
• Modify: docs/handoff/2026-05-30_x_ssl_net_optimized_training_handoff.md
• Modify: docs/report/2026-05-06_XNet项目阶段汇报.md
• Modify: docs/report/2026-05-27_x_ssl_net_status_report.md

• Modify: docs/method/XNet_encoder_vs_MobileMamba_encoder_2026-05-31.md

• [ ] 在每份历史文档前部新增统一格式的“当前实现对照说明”。

• [ ] 对仍有效的内容直接说明保留依据，例如 encoder 三分支、小波分支、VMamba/SS2D。

• [ ] 对已失效内容明确标记，例如 active X-shaped decoder、diagonal guide path、guide modulation 仍参与前向。

• [ ] 给出当前应参考的代码或主文档位置。

Task 4: 全仓一致性搜索与收尾

Files:

• Modify as needed: docs/**/*.md, README.md

• [ ] 全仓搜索 X-shaped decoder、diagonal guide、XGuideProjector2d、XGuideModulation2d、guide_mode。

• [ ] 对未标注历史语境却会误导为当前实现的表述进行补充或修正。

• [ ] 做一次最终抽查，确认主线文档与 tests/test_xnet_2d.py 的断言一致。