GPUPlane MVP 实施路线图

版本：v0.1-draft · 2026-08-17 设计依据：03-system-design.md。里程碑顺序按依赖关系排列，每个里程碑结束系统都处于可真实使用的状态（walking skeleton 策略）。

0. 路线总览

v0.1 Remote Training Foundation（替代 SSH+tmux）
  M0 骨架 ──► M1 节点监控 ──► M2 任务执行 ──► M3 指标与实验 ──► M4 Web UI ──► M5 导入与收尾
v0.2 Experiment Management（实验/评估/事件/重试/Docker/Webhook）
v0.3 Agent-native Training（MCP/Skill/语义诊断）
v0.4 Small-scale Multi-node（多节点资源匹配/依赖/定时任务）

对原方案的修订：原 v0.1 一次性包含 Web UI + TB Import + Checkpoint Discovery，范围偏大（约 3 个里程碑的量）。本路线图将其拆为 M0–M5，把 Web UI 推迟到 M4（此前用 CLI 闭环），确保任意时刻停下都有一个完整可用的产品。

1. v0.1 里程碑明细

M0 — Monorepo 骨架与协议基座（~0.5 周）

任务

uv workspace 初始化（packages/{common,sdk,agent,server,cli}，web/ 脚手架）
gpuctl-common：Pydantic 协议模型（Job/Run/Node/WsMsg/MetricPoint/Event）、ULID 生成、错误模型
SQLite 初始化与迁移机制（alembic 或手写 migration 表，倾向手写——个人项目少一个依赖）
server 最小 FastAPI app（/api/v1/health、token 中间件、静态托管 web/dist 的挂载点）
CI：ruff + mypy(strict-ish) + pytest；examples/mnist 示例训练脚本（支持 TB 输出，供全链路测试）

验收

gpuctl server serve 启动，health 返回 200；pytest 绿；uv tool install -e packages/cli 后 gpuctl --help 可用

M1 — Agent 注册、心跳与节点监控（~1 周）

任务

agent：配置加载、WSClient（重连退避、25s 心跳、hello 注册）
NodeMonitor：NVML 单例采集（util/显存/温度/功耗/时钟/进程级显存）+ psutil（CPU/RAM/Disk），2s 采集 5s 批量上报
server：Agent Gateway（WS 端点、token 认证）、nodes/gpu_slots 表维护、心跳超时判定（90s → OFFLINE）
spool 缓冲：断线 jsonl 落盘 + 重连限流回放 + (stream, seq) 幂等
CLI：gpuctl status、gpuctl node list/show（表格展示 GPU 实时数据）
systemd unit 模板 + loginctl enable-linger 部署文档

验收

真机（5090）：agent 注册上线，gpuctl status 看到 GPU 实时指标；kill agent 90s 后节点 OFFLINE；重启 agent 自动重连且断线期指标回补（spool 回放验证）

M2 — Job 队列与 ProcessRunner（~1.5 周）★ v0.1 核心价值

任务

jobs/runs 表 + REST：POST /jobs、GET /jobs、cancel
Scheduler：2s tick、priority/created_at 排序、GPU slot 独占分配、CUDA_VISIBLE_DEVICES 注入、cpu-only job 并发上限
ProcessRunner：进程组管理（killpg/SIGTERM→SIGKILL/reap）、PYTHONUNBUFFERED、runtime.json、exit code/failure_reason
LogCollector：stdout/stderr tee（本地文件 + WS 批量 + drop-oldest 有界队列）；server 端 tail ring buffer（2000 行）+ SSE /logs/stream
Job 状态机全量（含 DISPATCHING ack 超时回 QUEUED、LOST 与 reconcile）
CLI：submit/job list/show/cancel、logs [-f]
examples/mnist 通过 gpuctl submit 跑通

验收（端到端剧本）

gpuctl submit -- python -u examples/mnist/train.py --epochs 2 → 队列→调度→RUNNING→SUCCEEDED
gpuctl logs <job> -f 实时滚动无卡顿、无丢行（对比本地文件）
训练中 cancel → 进程组被整组杀死（无 dataloader 孤儿残留，ps 验证）
训练中拔 agent 网络 → job 进入 LOST；恢复后 reconcile 对齐
连提 3 个 GPU job → 串行执行；1 个 cpu-only job 可并发

M3 — 训练指标：SDK + TensorBoard Adapter（~1.5 周）

任务

gpuctl-sdk：run.init/log/log_checkpoint、有界队列 + 后台 sender、atexit flush、纯本地降级（无 server 时写 jsonl，零异常）
server metrics 管线：metrics:batch 端点、批量落库、metric_definitions 自动建档（名称启发式 direction）
TBAdapter：event 目录发现、EventAccumulator 增量 Reload、Tensors() 兼容、DataLossError 容错、offset 缓存
EventDetector 最小集：LOSS_NAN、OOM（日志模式）、RUN_STARTED/FINISHED；events 表 + REST 查询
RunSummary 增量缓存（latest/trend/best/health）+ GET /runs/{id}/summary
CLI：run list/show、metrics <run-id>（ASCII sparkline）
CheckpointWatcher：防抖 + 指纹 + HF checkpoint-* 识别 + checkpoint_seen 注册

验收

同一个 mnist 示例不改代码（Level 0/1）：TB 曲线进库、summary 可查、checkpoint 被发现注册
加 3 行 SDK 调用（Level 2）：自定义指标进库；停 server 训练继续跑且数据后补
手工注入 NaN → 产生 LOSS_NAN critical 事件

M4 — Web UI 四页（~2 周）

任务

web/ 前端：Vite+React+Tailwind 骨架、token 登录页（个人单用户简化为 token 输入存 localStorage）
Dashboard（节点卡 + 当前 job + 队列）、Jobs（列表/提交/cancel/retry）
Run Detail：Overview/Metrics(uPlot 实时)/System Metrics/Events/Logs(SSE 虚拟滚动)/Checkpoints
Nodes 页；server 托管 web/dist
实时管线：ref 缓冲 + rAF 节流；partysocket 重连；窗口化 + LTTB

验收

手机/笔记本浏览器打开 http://<gpu-host>:8600 完成 M2/M3 全部观测动作；10 万点曲线 60fps 不卡

M5 — import-run 与 v0.1 收尾（~0.5–1 周）

任务

gpuctl import-run <dir>：识别 TB events / config(yaml,json,args) / checkpoints / stdout 日志，构造 source=import 的 Run（status=IMPORTED）
gpuctl server backup；部署文档（同机/分体两种拓扑）；README 快速开始
稳定性：agent 长跑 72h 内存无泄漏（psutil 自监控）；server 重启后状态自愈

验收（v0.1 发布标准）

新用户 30 分钟内在自己 GPU 机上完成部署，用 gpuctl submit 提交真实训练，浏览器看曲线与日志，训练结束后 import-run 导入历史实验——全程不再需要 SSH+tmux。

2. v0.2 — Experiment Management（概要）

状态：✅ 已全部交付并通过真机验收（2026-08-18），见 07-v0.2-acceptance.md。

模块	要点
Project/Experiment 实体	CRUD + run 归组；UI 增加 Experiments 页与 run 对比视图
Evaluation Job	`POST /checkpoints/{id}/evaluations` → 生成 EVALUATE job → 结果回挂 checkpoint；evaluations 表
EventDetector 完整规则集	LOSS_SPIKE/OVERFITTING_SUSPECTED/GPU_UNDERUTILIZED/DISK_LOW
Retry	`max_attempts` + 失败分类重试策略（OOM 不自动重试）
DockerRunner	与 ProcessRunner 同语义（日志/退出码/slot）
Webhook + event-hook	ntfy/Bark 推送；`gpuctl event-hook` 唤醒本地 agent
MetricDefinition 管理 UI	direction/primary 可编辑
SDK extras	Lightning/HF Trainer callback 薄封装

验收标准：训练结束 → 自动对 N 个 checkpoint 排队评估 → 按 primary metric 给出推荐 checkpoint → 事件推送到手机。

3. v0.3 — Agent-native Training（概要）

模块	要点
gpuctl-mcp	15 个 tools（观测/控制/语义三类），按 MCP 2026-07-28 规范建模（Tasks 扩展 + streamable HTTP + 无状态核心），fastmcp 钉版
语义层	diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure（纯规则+统计实现）；原生记录 `(config diff, metrics, git commit)` 三元组支持 keep/revert 实验循环
Skill	对标 ARIS-skills 三件套：`run-experiment` / `monitor-experiment` / `analyze-results`（.claude/skills/gpu-training/ 下 SKILL.md + references）；frontmatter 只用 6 个标准字段以便跨平台分发
Plugin 打包	`.claude-plugin/plugin.json` 捆绑 MCP server（.mcp.json）+ skills + hooks 一体分发
AGENTS.md 模板	项目级规则示例（validation loss 最小化、OOM 处置流程等）；仓库同时维护 AGENTS.md 与 CLAUDE.md
read/write scope	MCP token 分级；cancel/submit 需 write scope；危险操作走 input_required 二次确认

验收标准：Claude Code 配置 MCP 后，用自然语言完成“提交训练 → 盯异常 → 比较 checkpoint → 给出推荐”全流程，无需人工介入平台操作。

4. v0.4 — Small-scale Multi-node（概要）

多节点 fleet 视图、node labels 与 selector 调度、跨节点资源匹配
Job 依赖（A 成功后触发 B）、定时任务（cron 式）
明确不做：多租户配额、抢占、bin-packing 优化、统一存储

5. 关键依赖与风险排期

common 协议模型 ──► 一切
WS Gateway + spool ──► agent 所有上报 ──► metrics/logs/events
Scheduler + slot ──► Runner ──► TB 适配/SDK（需要真实 job 环境验证）
RunSummary ──► UI Overview / MCP summary ──► diagnosis

最先做 common 协议模型并在所有包间共享——返工成本最高的部分前置冻结；
M2/M3 必须用真实训练负载验收（不只用 mock）：examples/mnist + 一个真实 HF SFT 项目；
MCP（v0.3）依赖 fastmcp 生态稳定，排期靠后天然规避了版本动荡期；
每周结束保持 main 分支可部署——任何里程碑超期时砍页面/砍规则，不动协议与数据模型。

6. 工作量估计

里程碑	估计	累计
M0–M5（v0.1）	约 6–7 人周（1 人全职）/ 约 3–4 周（AI Agent 高强度协作）	v0.1
v0.2	约 3–4 周
v0.3	约 2–3 周（生态验证成本低时）
v0.4	视多节点需求紧迫度再评估