# MVP 代码结构重构方案（按功能模块划分）

背景：当前 `src/mvp/` 下以 `v1.1/`、`v2.0/` 版本目录来组织代码。实际上 **v2.0 是在 v1.1 的 Ray Jobs SDK 提交链路基础上扩展了服务层**，并且为了让 v2.0 工作又对 v1.1 的 `docker-compose.yaml`、`dev.yaml` 做了修改（挂载 v2、开放 8080、增加 `v2:` 配置段）。因此“按版本分目录”会让依赖关系变得不清晰（谁是库、谁是应用、哪些配置是共享的）。

本方案目标：把 `src/mvp/` 重构为“按功能模块”划分（ray 提交核心库 / service 服务层 / cli 工具 / TaskSpecs / configs / scripts），并给出迁移后的验证与执行方案。

> 本文仅给出设计与迁移/验证方案，不直接改代码（待确认后再实施）。

---

## 1. 现状梳理（问题点）

### 1.1 代码重复与耦合

- `src/mvp/v2.0/py/mvp_v11/` 是从 `src/mvp/v1.1/py/mvp_v11/` 复制而来用于复用，但这导致：
  - **库代码重复**（修 bug 要改两份）
  - 谁是“权威实现”不明确
- v2 API（`mvp_v2`）通过引用复制的 `mvp_v11.RayJobTool` 来提交 Ray Job，本质上依赖 v1.1 提交链路作为“库”。

### 1.2 配置与部署目录不稳定

- v2.0 复用了 v1.1 config 文件并新增 `v2:` section，这是合理的“向后兼容扩展”，但它把：
  - “Ray submit 基础配置”
  - “API 服务配置”
  - “部署路径约定（/workspace/mvp/v1.1 vs /workspace/mvp/v2）”
  混在一个文件里，不利于长期维护。

### 1.3 命名歧义：jobspec 与 Ray job

- v1.1/v2.0 都使用 `jobspec.yaml` 指代“训练语义参数”（PPO/GRPO/SFT 的训练字段）。
- 但 Ray 也有 “Ray Job” 概念（submission_id、entrypoint、runtime_env 等），易造成沟通误解。
- 需要把训练侧 specs 改名为 **TaskSpecs**（代表平台级任务规范），与 Ray Job 区分。

---

## 2. 重构目标（What good looks like）

### 2.1 目录与职责清晰

- “提交 Ray Job 的 SDK 封装”是一个可复用模块（库）。
- “服务层（API + scheduler + SQLite）”是一个独立模块（应用/服务）。
- “训练语义参数（TaskSpecs）”与 “Ray Job 提交参数（RayConfig）”分层清楚。

### 2.2 单一真源（Single Source of Truth）

- 只能有一份“Ray submitter core”实现（不能复制一份到另一个版本目录）。
- API 与 CLI/脚本都复用同一份 core。

### 2.3 兼容现有运行方式（渐进迁移）

- 保留现有的脚本式启动/准备流程（Ray 起集群、准备模型/数据仍用 scripts）。
- 允许在迁移期提供薄 wrapper 兼容旧路径（减少一次性 break）。

---

## 3. 目标结构（按功能模块划分）

建议把 `src/mvp/` 重构为下面的“功能分层”：

```
src/mvp/
  py/
    argus/                    # 顶层包（避免与 Ray 的 `ray` 包冲突）
      __init__.py

      core/                   # 通用：yaml/模型定义/工具函数（纯库）
        __init__.py
        yaml_io.py
        ids.py                # task_id / attempt_id 生成规则

      ray/                    # Ray Job 提交“核心库”（由现成 mvp_v11 迁移而来）
        __init__.py
        models.py             # RayConfig, TaskSpec(解析), Attempt, enums
        builders.py           # build_training_argv (ppo/grpo/sft)
        driver_entrypoint.py  # 仍然作为 Ray job entrypoint（worker 上执行）
        ray_job_tool.py       # Ray Jobs SDK 封装（submit/status/stop/logs）
        runtime_env.py        # 统一 PYTHONPATH/runtime_env 组装逻辑

      service/                # 服务层：FastAPI + scheduler + sqlite（应用）
        __init__.py
        app.py
        scheduler.py
        db.py
        config.py             # service 相关配置读取（从 configs 读取）
        ray_resources.py

      cli/                    # 命令行/SDK 提交入口（由现成 v1.1 run.py 迁移而来）
        __init__.py
        run.py                # submit/status/logs/stop 等 action

    server.py                 # uvicorn 入口（导入 argus.service.*）

  configs/
    dev.yaml                  # RayConfig + ServiceConfig（按层次组织、可扩展）
    prod.yaml                 # （可选）生产配置模板

  taskspecs/                  # 原 jobspecs/，改名 TaskSpecs（训练语义规范）
    ppo.yaml
    grpo.yaml
    sft.yaml
    README.md                 # TaskSpec 字段解释、示例

  scripts/                    # 宿主机脚本（docker exec/compose 编排）
    lib.sh
    00_prereq_check.sh
    01_up.sh / 02_down.sh
    20_start_head.sh / 21_start_workers.sh
    30_prepare_data_and_model.sh
    40_submit_cli.sh          # 通过 cli/run.py 提交 TaskSpec
    60_start_api.sh           # 启动 API（service）
    61_stop_api.sh
    62_status_api.sh

  docker-compose.yaml         # dev 环境 compose（从 v1.1 迁移到这里，路径稳定）
  README.md                   # 总入口文档（运行方式、目录约定）
```

### 3.1 关键点：库 vs 应用边界

- `argus.ray` 是唯一的 Ray submitter 库（替代当前 v1.1/v2.0 的 `mvp_v11` 双份拷贝）。
- `argus.service` 依赖 `argus.ray`，不反向依赖。
- `argus.cli` 依赖 `argus.ray`，用于脚本化提交/调试。

### 3.2 TaskSpecs vs RayConfig

- `taskspecs/*.yaml`：描述训练任务语义参数（workload、nnodes、n_gpus_per_node、数据/模型路径、训练步数等）。
- `configs/*.yaml`：描述 Ray 提交环境（address、entrypoint_resources、runtime_env 以及 service 配置）。

---

## 4. 配置策略（重构后如何组织 configs）

### 4.1 建议的 config 分层

把当前 `dev.yaml` 的内容明确分为两段（按模块名分段）：

1) `ray:`（RayConfig）
- job server address
- shared_root（`/private`）
- entrypoint resources（强制 driver 落 worker）
- runtime_env env_vars（HF cache、PYTHONPATH 注入策略）

2) `service:`（ServiceConfig）
- api host/port
- auth token_env
- sqlite db_path
- scheduler tick/max_running/retry_interval

示例（结构示意）：

```yaml
ray:
  address: "http://127.0.0.1:8265"
  shared_root: "/private"
  entrypoint_num_cpus: 1
  entrypoint_resources:
    worker_node: 1
  runtime_env:
    env_vars:
      HF_ENDPOINT: "https://hf-mirror.com"
      PYTHONUNBUFFERED: "1"
  user_code_path: "/private/user/code"

service:
  api:
    host: "0.0.0.0"
    port: 8080
  auth:
    token_env: "MVP_INTERNAL_TOKEN"
  sqlite:
    db_path: "/private/common/db/mvp.sqlite3"
  scheduler:
    tick_s: 5
    retry_interval_s: 60
    max_running_tasks: 1
```

> 迁移期可以支持“旧格式”（v1.1 顶层字段 + v2: 段）与“新格式”（ray:/service: 两段）并存：解析时兼容读取，降低一次性改动风险；但最终以新格式为准。

---

## 5. 迁移路径（推荐分两阶段实施）

### 阶段 A：先拷贝/迁移现成文件，再做最小调整（保持行为不变）

目标：不改功能、不改 API 行为。优先通过“拷贝/迁移现成文件 + 修正包引用/路径”完成重构，避免重头重写逻辑（降低出错概率）。

建议步骤：

1) 抽出 `src/mvp/py/argus/ray/`（由现成代码迁移）
   - 将 `src/mvp/v1.1/py/mvp_v11/` 迁移到 `src/mvp/py/argus/ray/`，并把它作为 submitter core 的唯一真源（不再保留一份复制品在其它目录）。
   - 只做机械化调整：修正 import、修正默认路径常量（例如 tool code path / working dir）、修正 scripts 的调用路径。

2) 抽出 `src/mvp/py/argus/service/`（由现成代码迁移）
   - 将 `src/mvp/v2.0/py/mvp_v2/` 迁移到 `src/mvp/py/argus/service/`。
   - service 侧对 submitter 的依赖统一改为 `src/mvp/py/argus/ray/`（不再引用 `src/mvp/v2.0/py/mvp_v11/` 的复制品）。

3) CLI 统一入口：`src/mvp/py/argus/cli/run.py`（由现成代码迁移）
   - 将 `src/mvp/v1.1/py/run.py` 迁移到 `src/mvp/py/argus/cli/run.py`，保留 action 语义（submit/status/logs/stop）。
   - 仅调整 import 与默认路径，使其指向新目录（configs/taskspecs/py）。

4) scripts 合并（以 v1.1 为基、合入 v2 API）
   - 将 `src/mvp/v1.1/scripts/` 迁移到 `src/mvp/scripts/`（Ray 集群编排最成熟）。
   - 将 `src/mvp/v2.0/scripts/` 的 API 启停脚本合入 `src/mvp/scripts/`，并统一命名与默认路径。

5) docker-compose / mounts 稳定化（你已确认要迁移）
   - 将 `src/mvp/v1.1/docker-compose.yaml` 迁移为 `src/mvp/docker-compose.yaml`。
   - 容器内挂载统一：宿主机 `.../src/mvp/` → 容器 `/workspace/mvp/`（包含 `py/ configs/ taskspecs/ scripts/`）。
   - runtime_env 的 `PYTHONPATH` 注入统一指向 `/workspace/mvp/py`（不再出现 `/workspace/mvp/v1.1/py`、`/workspace/mvp/v2/...`）。

阶段 A 完成标准：
- 原来 v1.1 的 CLI 提交方式仍可用（提交 PPO/GRPO/SFT）。
- v2 API 仍可用（队列、取消、日志）。
- 不再存在 `mvp_v11` 的重复目录。

### 阶段 B：配置格式升级（按模块两段）+ TaskSpecs 更名落地

目标：把 jobspec 真正改名为 TaskSpec，并把 config 升级为按模块两段（`ray:`/`service:`）清晰分层。

建议步骤：
- `jobspecs/` → `taskspecs/`，并更新 README/脚本引用。
- `dev.yaml` 从“顶层字段 + v2:”迁移为“ray:/service:”两段。
- 保留一段时间的兼容解析逻辑（读取旧格式时发出 warning）。
- 完成验证后删除旧版本目录：`src/mvp/v1.1/`、`src/mvp/v2.0/`（以及远端对应目录），确保新结构成为唯一入口。

阶段 B 完成标准：
- docs 里不再出现 “jobspec” 词汇，统一称 “TaskSpec”。
- `configs/dev.yaml` 分层清晰（`ray:`/`service:` 两段按模块名），服务与 Ray 的配置互不干扰。

---

## 6. 重构后的验证与执行方案（验收/回归）

### 6.1 本地（仓库内）静态验证

1) import / 入口检查（在容器环境）
- `python3 -c "from argus.ray.ray_job_tool import RayJobTool"`
- `python3 -c "from argus.service.app import create_app"`

2) 目录结构检查
- 确保 `src/mvp/py` 是唯一 python 代码根
- 确保 `taskspecs/`、`configs/`、`scripts/` 都在 `src/mvp/` 下

### 6.2 dev 环境（argus@h1）端到端验证

前置：
- 远端目录：`argus@h1:/home2/argus/infra/mvp/`（维持不变）
- 共享目录：`/home2/argus/infra/mvp/shared` 挂载到容器 `/private`

验证步骤（推荐顺序）：

1) 重新拉起容器 + 启动 Ray
- `scripts/01_up.sh`
- `scripts/20_start_head.sh`（head `--num-cpus=0 --num-gpus=0`）
- `scripts/21_start_workers.sh`（workers 带 `worker_node` 资源）
- `ray status` / `ray list nodes` 确认 head 无 GPU、workers 各 4 GPU

2) CLI 提交回归（等价 v1.1）
- 提交 `taskspecs/sft.yaml`，确认成功
- 提交 `taskspecs/grpo.yaml`，确认成功
- 提交 `taskspecs/ppo.yaml`，确认成功

3) API 服务回归（等价 v2.0）
- `scripts/60_start_api.sh`
- `POST /api/v2/tasks`（raw YAML TaskSpec）
- `GET /api/v2/tasks/{task_id}`：确认返回 `created_at/updated_at`
- `POST /api/v2/tasks/{task_id}:cancel`：确认任务 `state=CANCELED` 且 attempt `ray_status=STOPPED`（服务侧语义一致）

4) 队列行为回归
- 在 `service.scheduler.max_running_tasks=1` 下：
  - 连续提交两个 8-GPU 任务：第二个应保持 `QUEUED/PENDING_RESOURCES`，直到第一个结束后自动提交。

验收标准：
- 三种 workload（PPO/GRPO/SFT）都能通过 CLI 跑通（或至少能正确提交到 Ray 并进入 RUNNING）。
- API 提交/查询/取消/日志正常。
- “cancel 后 state=CANCELED 但 attempt 仍 RUNNING”的不一致问题不再出现。

---

## 7. 风险与注意事项

1) PYTHONPATH 注入路径变化
- 当前 runtime_env 里有 `MVP_TOOL_CODE_PATH=/workspace/mvp/v1.1/py` 的历史路径假设；
- 重构后需统一为 `/workspace/mvp/py`，并确保所有容器都挂载到相同路径。

2) SQLite WAL 在 NFS 上的稳定性
- 目前 db 使用 WAL（生成 `-wal/-shm`），NFS 下可能有一致性风险；
- 可作为后续优化：检测 NFS 时退回 `journal_mode=DELETE` 或换成单机本地盘。

3) 渐进迁移的兼容期
- 迁移期可以短暂保留旧路径（例如 `src/mvp/v1.1`、`src/mvp/v2.0` 仅保留 README 指向新路径）以减少一次性断裂；但你已确认最终会删除这两个目录，因此需要在 scripts/文档同步更新后尽快清理。

---

## 8. 已确认约束（将按此实施）

你已明确：

1) `docker-compose.yaml` 必须迁移到 `src/mvp/` 根；重构完成后 `src/mvp/v1.1`、`src/mvp/v2.0` 都会删除。
2) `configs/dev.yaml` 升级为两段，按模块名分段：`ray:` 与 `service:`；并保持纯 YAML 风格（不混用 JSON inline map）。
3) TaskSpec 字段先保持与现有 v1.1 YAML 完全一致（仅目录与命名变化），避免引入不必要的不兼容。