X_SSL_Net/AGENTS.md

Repository Guidelines

文档与沟通要求

本仓库的文档、说明、评审意见与对外回答默认必须使用中文，除非任务明确要求保留英文原文、接口字段或论文术语。提交说明中的代码标识、命令、路径和配置键名保持原样，不要擅自翻译。

项目结构与模块组织

核心代码位于 lib/：lib/modules 存放模型实现，如 xnet_2d；lib/data 负责数据集记录与划分；lib/trainers 负责训练流程；lib/utils 提供配置与通用工具。运行入口在 tools/，例如 train.py、summarize_results.py；数据辅助脚本在 scripts/。实验配置主要放在 configs/segmentation/。测试位于 tests/。大体量输入与产物分别放在 data/、weights/、outputs/、results/、swanlog/。ref/ 与 tmp/ 主要作为参考或临时目录，不应作为主代码修改入口。

构建、测试与开发命令

使用 python -m pip install -r requirements.txt 安装依赖。 使用 python tools/train.py --config configs/segmentation/optimized/sup_busi_opt.yaml 启动训练。 使用 python tools/train.py --config ... --set train.epochs=2 logging.use_swanlab=false 覆盖 YAML 配置而不直接改文件。 使用 python scripts/generate_project_split.py --dataset BUSI --root data/BUSI 生成项目划分文件。 使用 bash tools/run_optimized_supervised.sh 或 DATASET=BUSI bash tools/run_optimized_supervised.sh 运行监督优化流程。 使用 python tools/summarize_results.py --outputs-dir outputs --results-dir results 汇总实验结果。 使用 pytest -q 运行测试。

编码风格与命名约定

遵循现有 Python 风格：4 空格缩进，公共函数补充类型标注，新模块优先使用 from __future__ import annotations。文件、函数、变量、配置键统一使用 snake_case，类名使用 PascalCase。配置文件命名保持显式，例如 sup_tn3k_opt.yaml。优先在 lib/ 内做小范围、可追踪的修改；除非明确需要同步上游参考实现，否则不要随意修改 ref/。

测试要求

涉及行为变更时应补充或更新 pytest 用例，重点覆盖 lib/modules、配置加载和数据划分逻辑。测试文件命名使用 test_<feature>.py，测试函数命名使用 test_<expected_behavior>()。如无必要，冒烟测试应尽量可在 CPU 环境运行；tests/test_xnet_2d.py 可作为参考范式。

提交与合并请求规范

最近提交历史采用带作用域的 Conventional Commits，例如 feat(data): ...、refactor(xnet_2d): ...，后续保持一致。Pull Request 应说明受影响的数据集、配置或模块，并列出已执行命令，如 pytest -q、训练冒烟命令、结果汇总命令。若改动影响训练结果或可视化输出，应附上来自 results/ 或 outputs/ 的关键指标表或截图。