argus-cluster/specs/mvp/v3.5/v3.5_dev_plan.md

MVP v3.5（精简版）开发计划（TDD）

目标：在 v3.0 已有能力基础上，仅新增两项能力：

1. Advanced TaskSpec（自定义 command）
2. Custom Reward（方式 A：用户自己在 command 里写 custom_reward_function.*）

设计依据：specs/mvp/v3.5/v3.5_design.md（本计划不再扩展 scope）。

---

0. 范围与约束

0.1 In scope

• 新增 kind: advanced 的 TaskSpec：用户提供 command，平台做 $HOME 宏替换与 best-effort 校验，再提交 Ray Job。
• Custom Reward：平台仅做 reward path 校验（方式 A），不新增结构化字段。
• $HOME/common/* 路径语义支持（关键）：用户在 SFTPGo/WebClient 看到的路径能被训练进程正确读取。

0.2 Out of scope（本轮不做）

• 自定义 verl 版本/代码路径（多版本共存）
• 断点续训（resume from checkpoint）
• IB/RoCEv2/NCCL 专项支持
• Model Serving
• Node management 改造（v3.0 的 stateless head/worker/watchdog/supervisor 机制保持不变）

0.3 关键路径映射（必须保持一致）

说明：SFTPGo 的 $HOME/common/... 是 virtual folder，训练进程看不到该虚拟路径。

提交 Advanced command 前必须展开/映射：

• $HOME/common/datasets → /private/datasets（只读语义）
• $HOME/common/hf → /private/hf（只读语义）
• 其余 $HOME → /private/users/<user_id>

并且为兼容历史用法（v3.0）：

• Basic TaskSpec 仍接受 /private/common/datasets/...、/private/common/hf/...（不强制迁移）。

---

1. 测试策略（TDD）

1.1 单元测试优先级

1. 解析与兼容：kind: advanced 能解析；无 kind 仍按 Basic 解析，旧用法不破坏。
2. 宏替换正确性：$HOME / $HOME/common/* 映射严格按约定展开。
3. best-effort 校验：拒绝明显危险/跨用户路径；对 reward path 做 allowlist。
4. 提交链路：Scheduler 能识别 Advanced spec 并调用对应的提交方法，确保 submission_id/目录规范不变。
5. WebUI/API：New Task 模板与 /spec 展示完整 resolved spec（包含展开后的 command）。

1.2 本地运行方式

• 复用已有 .venv，执行：.venv/bin/python -m pytest
• 若环境没有 pip，使用 uv 的方式参考 v3.0 约定（不在本计划重复）。

---

2. 里程碑划分（每个里程碑可独立验证）

约定：每个里程碑先写测试（失败），再实现代码使测试通过；里程碑结束跑一遍 pytest。

M1 — TaskSpec 模型与解析（兼容优先）

目标

• 引入 AdvancedTaskSpec 数据结构与 union parser，同时保证 v3.0 Basic 行为不变。

新增/修改（建议位置）

• src/mvp/py/argus/ray/models.py
  • 新增 AdvancedTaskSpec
  • 新增 parse_taskspec(obj: dict) -> JobSpec | AdvancedTaskSpec
  • 兼容策略：缺省 kind → 走 JobSpec.from_dict

测试（先写）

• src/mvp/py/tests/test_models.py
  • test_parse_taskspec_basic_no_kind_compat()
  • test_parse_taskspec_advanced_smoke()
  • test_parse_taskspec_advanced_requires_command_nnodes_gpus()

验收

• pytest -q 通过；旧测试不修改或仅做最小必要更新。

---

M2 — Advanced command 展开与校验（核心能力）

目标

• 实现 command 展开（含 $HOME/common/* 映射）与 best-effort 强约束校验。

实现点（建议新增模块）

• src/mvp/py/argus/service/command_expand.py（或放在 argus/service/validation.py）
  • expand_advanced_command(user_id: str, command: str) -> str
  • validate_advanced_command(user_id: str, expanded_command: str) -> None（失败抛 ValueError）

强约束（与设计文档一致）

• 必须包含 python3 且包含 -m verl.trainer.（否则 400）
• 禁止出现 /private/users/<other>/...（跨用户路径）
• 若检测到 data.train_files=/data.val_files=：
  • 只允许 /private/users/<me>/datasets/... 或 /private/datasets/...
  • （兼容）允许 /private/common/datasets/...（旧路径）
• 若检测到 custom_reward_function.path=：
  • 只允许 /private/users/<me>/code/...（展开后校验）

测试（先写）

• 新增：src/mvp/py/tests/test_advanced_command.py
  • test_expand_maps_home_common_datasets_to_private_datasets()
  • test_expand_maps_home_common_hf_to_private_hf()
  • test_expand_maps_home_to_private_users()
  • test_validate_rejects_cross_user_paths()
  • test_validate_requires_verl_trainer_entry()
  • test_validate_allows_reward_path_under_user_code()
  • test_validate_rejects_reward_path_outside_user_code()

验收

• 单测覆盖映射/校验的正反例；错误信息可读（用于 API 400 detail）。

---

M3 — Ray 提交链路支持 Advanced（Builder/Tool/Scheduler）

目标

• Advanced spec 能进入 scheduler 队列并提交为 Ray job（driver 仍落 worker）。

代码改动点（建议）

• src/mvp/py/argus/ray/builders.py
  • 新增 build_advanced_argv(command: str)：返回 ["bash","-lc", expanded_command]
• src/mvp/py/argus/ray/ray_job_tool.py
  • 新增 submit_advanced(...)（或统一成内部 submit plan）
  • runtime_env：继续注入公共 verl code path（本轮不支持用户自定义 verl 代码）
  • 可选：把 /private/users/<user>/code 加入 PYTHONPATH，提升 reward 代码 import 体验
• src/mvp/py/argus/service/scheduler.py
  • 使用 parse_taskspec 分流 Basic/Advanced
  • Advanced 调用 tool.submit_advanced(...)

测试（先写）

• src/mvp/py/tests/test_builders.py
  • test_build_advanced_argv_uses_bash_lc()
• src/mvp/py/tests/test_scheduler.py
  • 新增一个 kind: advanced 的任务，断言 scheduler 调用了 submit_advanced
  • 断言 job_dir/submission_id 规则不变（仍按 /private/users/<user>/jobs/<sid>）
• src/mvp/py/tests/test_ray_job_tool.py
  • 断言 advanced 提交时 entrypoint 是 driver_entrypoint + bash -lc ...

验收

• 单测跑通；Scheduler tick 能完成 Advanced 任务从 QUEUED → SUBMITTED（mock Ray）。

---

M4 — API & WebUI（最小功能闭环）

目标

• WebUI/HTTP API 能提交 Advanced Task，并在详情页看到 resolved spec（含完整 command）。

API 改动点

• src/mvp/py/argus/service/app.py
  • POST /api/v2/tasks：支持 kind: advanced
    • 保存 raw YAML（保持与 Basic 一致）
    • 对 Advanced：展开 command + 校验（失败返回 400）
  • GET /api/v2/tasks/{task_id}/spec：
    • 返回 resolved spec（建议同时返回 raw + expanded，或 YAML 中直接给 expanded）

WebUI 改动点

• src/mvp/py/argus/service/ui.py
  • New Task 页面新增 Advanced 模板（含中文注释）
  • 文案强调共享目录：$HOME/common/datasets、$HOME/common/hf

测试（先写）

• src/mvp/py/tests/test_app.py
  • test_create_task_advanced_ok()（最小 valid command）
  • test_create_task_advanced_rejects_invalid_command()
  • test_task_spec_endpoint_includes_expanded_command()
• src/mvp/py/tests/test_ui.py
  • 断言页面包含 Advanced 示例块

验收

• pytest 通过；浏览器可提交 Advanced YAML 并看到 expanded command。

---

M5 — 端到端验证（远端 argus@h1）

目标

• 在真实 Ray cluster + VERL 环境下验证 Advanced 与 Custom Reward（方式 A）。

步骤（手工验收脚本化可选）

1. 启动 v3.0/v3.5 统一的 compose + API（沿用现有 run_all 脚本体系）
2. 用户（如 alice）通过 SFTP 上传 reward 代码到：
   • $HOME/code/reward.py（真实路径 /private/users/alice/code/reward.py）
3. 通过 WebUI 或 curl 提交 Advanced task：
   • command 中包含：
     • custom_reward_function.path=$HOME/code/reward.py
     • custom_reward_function.name=compute_score
     • data.train_files=$HOME/common/datasets/gsm8k/train.parquet
     • data.val_files=$HOME/common/datasets/gsm8k/test.parquet
4. 检查：
   • 任务状态从 QUEUED → RUNNING → SUCCEEDED/FAILED（有日志）
   • driver 不在 head 上跑（dashboard 验证）
   • 日志出现 “custom reward” 生效的提示（按 VERL 实际日志关键字确认）
5. 回归：提交 Basic ppo/grpo/sft 任务仍可运行（确保兼容性）

验收

• Advanced task 能跑至少若干 step，且 reward 注入生效。
• Basic 任务兼容不回退。

---

3. 风险点与边界（明确写进 PR/变更说明）

• Advanced command 只做 best-effort 校验，不做完整 shell AST 解析；复杂命令可能存在漏检/误判（后续可扩展）。
• $HOME/common/* 是“用户侧语义”，服务层必须映射到真实路径，否则训练必然 FileNotFound。
• 校验策略（强约束）如果后续要允许非 VERL 命令，需要调整规则并补测试（本轮默认拒绝）。