# MVP v3.5 功能变更总结（相对 v3.0）

> v3.5 本轮按已确认的精简 scope：**只聚焦 Advanced TaskSpec + Custom Reward（方式 A：用户在 command 里写 overrides）**。Serving/IB/断点续训/多版本 verl 等能力本轮仍不做。

## 1. TaskSpec / 任务语义

### 1.1 新增 Advanced TaskSpec（自定义 command）

- 新增 `kind: advanced` 的 TaskSpec 类型：
  - 用户可提交任意 bash `command`，不再局限于平台内置 PPO/GRPO/SFT 模板。
  - `workload` 不再要求用户填写，也不做 infer；平台内部统一按 `"advanced"` 做任务分类与 task_id 命名（避免未来训练类型扩展带来的限制）。
- 支持 `$HOME` 宏替换（服务端提交前展开）：
  - `$HOME` → `/private/users/<user_id>`
  - `$HOME/common/datasets` → `/private/datasets`
  - `$HOME/common/hf` → `/private/hf`
- `command` 校验（best-effort，面向内部可信用户）：
  - 要求包含 `python3 -m verl.`（允许 `verl.trainer.*` / `verl.model_merger` 等）。
  - 不做强沙箱；主要防止明显误用导致的不可预期行为。

### 1.2 Custom Reward（方式 A）

- 平台不新增 reward 专用字段、不扩展 TaskSpec schema。
- 用户通过在 `command` 里写 VERL 原生 overrides 来注入 reward：
  - `custom_reward_function.path=...`
  - `custom_reward_function.name=...`
  - `custom_reward_function.reward_kwargs=...`（如需）
- 平台侧仅做：
  - 基础路径/宏展开（$HOME）
  - best-effort 的字符串校验（不做深度 AST 解析）

## 2. WebUI（New Task 体验增强，仍兼容 YAML）

- `New Task` 页面新增 **YAML 模式 / 表单模式**切换：
  - 表单模式只覆盖 **5 个模板**：PPO / GRPO / SFT / Advanced / Model Merge。
  - 表单模式实时生成 YAML 预览；Submit 时提交生成 YAML；可一键切回 YAML 模式继续手工编辑。
- `Advanced example`：
  - 示例命令改为多行、可读性更好。
  - 补齐 PPO 常见 fail-fast 所需的关键 overrides（例如 actor micro batch），避免用户“照抄即失败”。
- 新增 `Model merge example`（Advanced command 形式）：
  - 使用 `python3 -m verl.model_merger merge ...`
  - 支持用 `$HOME/jobs/<RAY_SUBMISSION_ID>/...` 访问训练产物目录。

## 3. SFTPGo / common 目录可读性（配合 v3.5 的 $HOME/common 语义）

> 这些变更主要用于保证 v3.5 所定义的 `$HOME/common/{datasets,hf}` 语义在 SFTPGo WebClient/客户端下可用。

- `/common/datasets` 与 `/common/hf` 作为 SFTPGo virtual folders 暴露为只读共享目录：
  - 允许 list + download（用于浏览与下载/查看内容；仍不允许 upload/rename/delete）。
  - 权限规则覆盖到子路径（避免“能进目录但文件不可读”的情况）。
- API 调用 SFTPGo admin API 的连通性增强：
  - dev 环境下避免依赖容器内 DNS（部分 head 容器环境存在临时解析失败），改为通过 docker bridge 网关 + 映射端口访问 admin API。
- API 启动脚本确保注入 `SFTPGO_ADMIN_PASSWORD`（与 compose 默认值保持一致），避免 Reset Password 走到 401。

## 4. 兼容性与行为变化

- **完全兼容 v3.0 的 PPO/GRPO/SFT TaskSpec YAML**（原有字段与提交方式不变）。
- 新增能力不会影响 ray/node management（仍按 v3.0：head 发布 discovery、worker watchdog join/self-heal）。
- Advanced 任务不会进入 PPO/GRPO/SFT 的语义约束；平台仅负责：
  - 资源字段（`nnodes` / `n_gpus_per_node`）用于队列调度与提交 gate
  - 将 `command` 作为 Ray job entrypoint 执行

## 5. 已知限制（v3.5 不做）

- 不提供“可视化” reward 配置面板（仅方式 A：用户自己写 command）。
- 不支持 per-job 自定义 verl 代码快照/多版本共存（本轮不做 code_path 选择）。
- 不支持断点续训一键 resubmit / IB(RDMA) / model serving（按 roadmap 后续版本推进）。