# 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` 的断言一致。