[No.35] feat(doctor): add config doctor and dry-run

[AutumnCs]

Summary

• Closes 【Task.35】Config Doctor & Dry-run #203
• Relates to Relax 开源贡献者招募·第一期 正式任务发布！ #86
• Adds a lightweight Config Doctor that reuses Relax's existing argument parsing and validation chain.
• Detects common configuration errors before Ray, SGLang, distributed processes, or GPU workers are started.

python -m relax.entrypoints.doctor [--format text|json] -- <training arguments>

Changes

• Added a side-effect-free dry-run entrypoint with text and JSON output.
• Reused the existing Relax, Megatron, SGLang, Registry, and algorithm validation paths.
• Added fail-fast checks for invalid resources, missing roles, dataset paths and formats, conflicting arguments, invalid parallel settings, and unknown options.
• Required the existing CPU-only advantages: [1, 0] producer for pure fully-async topologies, including true-on-policy mode.
• Added support for generalized dataset paths, including file lists, directories, and @[start:end] slices.
• Shared the built-in loader's supported file extensions with preflight validation to prevent rule drift.
• Limited physical path checks to data consumed by built-in loaders, preserving custom SFT/RL data-source semantics and configurations that disable the global rollout dataset.
• Added final merged configuration, active role topology, GPU resource requirement, and expected launch command output.
• Added recursive credential redaction across configuration, arguments, commands, and error messages.
• Added 26 real CLI fixture cases covering at least 15 common error categories, each with a targeted suggestion and non-zero exit assertion.
• Added focused tests and English/Chinese usage documentation.

The implementation is limited to 9 files. It does not modify Controller, Registry, backend runtime code, placement-group creation, or worker startup. It does not introduce fallback parsing, Bash interpretation, a rule engine, or an independent Launch Plan.

Backend- and algorithm-specific validation remains in the existing validation chain, so extending a backend or algorithm does not require adding rules to a Doctor-specific monolithic function.

Verification

Environment:

• Linux
• Python 3.12.13 locally
• Base: main@5cec8ca1569801d835a56ac86af19babd83caa82
• Final commit: caa00335b941de7935e1877e4a0dd66f61c0ff4f
• CPU/static validation only; no GPU worker was allocated or started

Focused Doctor tests:

PYTHONPATH=.:/path/to/Megatron-LM \
python -m pytest -q tests/entrypoints/test_doctor.py
# 52 passed

Related argument, Registry, backend, data-path, and algorithm tests:

PYTHONPATH=.:/path/to/Megatron-LM \
python -m pytest -q \
  tests/entrypoints/test_doctor.py \
  tests/test_model_source.py \
  tests/utils/test_arguments_reinforce_plus_plus.py \
  tests/utils/test_arguments_rloo.py \
  tests/utils/test_arguments_opd_teacher_colocate.py \
  tests/utils/test_arguments_mtp_only.py \
  tests/utils/test_lora_vision_scope_validation.py \
  tests/utils/training/test_ppo_utils_grpo.py \
  tests/utils/data/test_data_utils.py \
  tests/core/test_registry_rloo.py \
  tests/core/test_registry_reinforce_plus_plus.py \
  tests/core/test_registry_sft.py \
  tests/backends/sglang/test_arguments.py
# 186 passed

Repository checks:

pre-commit run --all-files
git diff --check
# passed

GitHub CI run #726 passed:

• Lint
• Pre-commit Checks
• Tests on Python 3.10
• Tests on Python 3.11
• Tests on Python 3.12

CI evidence:

https://github.com/redai-studio/Relax/actions/runs/33600398619

Risk & Rollback

• Doctor performs static validation and cannot detect runtime-only failures such as NCCL connectivity, GPU OOM, driver failures, or unavailable remote services.
• Unknown-option rejection is enabled only for the Doctor strict path.
• Physical path and format checks apply only when the built-in data loader owns the corresponding data source.
• Shell scripts are not executed or interpreted; expanded training arguments must be passed after --.
• Reverting this PR removes the Doctor entrypoint and the added preflight checks.

Checklist

• Diff contains only Task 35 changes
• Existing parsing and validation paths are reused
• At least 15 common error categories include targeted suggestions
• Valid input returns success and invalid input returns non-zero
• Config, roles, resources, and expected command are reported
• Sensitive values are redacted
• Custom data-source semantics are preserved
• Pure fully-async topologies require the advantages producer
• Built-in dataset file formats are validated before runtime startup
• No Ray, SGLang, distributed process, or GPU worker is started
• Focused and related tests pass
• GitHub CI passes on Python 3.10, 3.11, and 3.12
• Documentation is updated
• No credentials, datasets, checkpoints, or private machine paths are included

[GUOGUOPOT]

感谢投入！这个 PR 的问题不是功能做得不够，而是实现方向和题目本意存在较大偏差。

本题出题人原本希望复用现有参数解析链路，在 relax/utils/arguments.py 及各 backend 的 args 校验处补充一组轻量、无副作用的前置检查，让常见配置错误在 Ray、SGLang 或 GPU worker 启动前暴露；dry-run 入口只需负责执行这些校验、展示必要信息并返回正确的退出码。题目的重点并不是重新建立一套配置解析和运行时规划框架。

当前 PR 修改了 38 个文件，新增约 4.7k 行代码。除了完整的 relax/doctor/ 子系统，还引入了规则注册、Bash 子集静态解析、字段来源追踪、多阶段 fallback、独立 Launch Plan，并进一步修改了 Controller、Registry 以及 Megatron/SGLang 的参数解析路径。这个改动范围已经明显超出本题所需，也使原本只读的预检功能侵入核心运行路径，带来了与收益不成比例的 review 成本、长期维护成本和训练路径回归风险。

综上，本次评审结论为暂不通过。非常感谢您在本任务中投入的时间与精力，也期待后续按上述方向收敛方案后再次提交。

[AutumnCs]

感谢投入！这个 PR 的问题不是功能做得不够，而是实现方向和题目本意存在较大偏差。

本题出题人原本希望复用现有参数解析链路，在 relax/utils/arguments.py 及各 backend 的 args 校验处补充一组轻量、无副作用的前置检查，让常见配置错误在 Ray、SGLang 或 GPU worker 启动前暴露；dry-run 入口只需负责执行这些校验、展示必要信息并返回正确的退出码。题目的重点并不是重新建立一套配置解析和运行时规划框架。

当前 PR 修改了 38 个文件，新增约 4.7k 行代码。除了完整的 relax/doctor/ 子系统，还引入了规则注册、Bash 子集静态解析、字段来源追踪、多阶段 fallback、独立 Launch Plan，并进一步修改了 Controller、Registry 以及 Megatron/SGLang 的参数解析路径。这个改动范围已经明显超出本题所需，也使原本只读的预检功能侵入核心运行路径，带来了与收益不成比例的 review 成本、长期维护成本和训练路径回归风险。

综上，本次评审结论为暂不通过。非常感谢您在本任务中投入的时间与精力，也期待后续按上述方向收敛方案后再次提交。

@GUOGUOPOT 老师您好，感谢您指出上一版实现方向与题目本意的偏差。前两天学校的服务器出了点故障没及时回复您，不好意思。上一版对项目了解不够充分，对任务边界的理解存在偏差，过分追求不必要的完整性，给评审带来了不必要的负担，抱歉。我已按照您建议的轻量方案完成整体重写，辛苦您再次审阅。

本次主要调整如下：

1. 改动范围由原来的 38 个文件收敛为 8 个文件。
2. 删除了独立 Doctor 子系统、规则注册框架、Bash 静态解析、字段来源追踪、多阶段 fallback 和独立 Launch Plan。
3. 不再修改 Controller、Registry、backend runtime、placement-group 或 worker 启动路径。
4. Doctor 直接复用现有 relax.utils.arguments.parse_args() 以及 Relax、Megatron、SGLang 和算法校验链路；backend/算法专属校验仍保留在现有 validator 中。
5. dry-run 仅负责执行校验并输出最终配置、角色拓扑、资源需求和预计命令，不启动 Ray、SGLang、分布式进程或 GPU worker。
6. 补充了 24 个真实 CLI 错误样例，覆盖不少于 15 类常见配置错误，并验证针对性建议、非零退出码、未知参数审计和敏感信息脱敏。
7. 路径检查仅校验由内置数据加载器实际消费的数据路径，不会误拒绝自定义 SFT/RL data source 或禁用全局 dataset 的配置。

分支已同步最新 main@4899b8f，最终提交为 41df9b7。GitHub CI run #682 的 Lint、Pre-commit Checks 和 Python 3.10/3.11/3.12 测试均已通过：

https://github.com/redai-infra/Relax/actions/runs/32614825356

PR 正文已同步更新实现范围、验证命令、已知限制和回退方式。再次感谢上一轮对方向的纠正，辛苦您复审。