# 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/` 的关键指标表或截图。