Agent-native training control plane for personal & small-scale GPU environments. 个人 GPU 训练的控制面：任务排队与调度、实时指标/日志、checkpoint 登记、事件诊断 —— 为 Agent（MCP）与浏览器而生，不再依赖 SSH + tmux + 肉眼盯 loss。
产品文档站：https://ericyuan2007.github.io/GPUPlane/（快速开始 / 指南 / MCP 工具参考）； 设计文档见
docs/（产品调研 / 产品设计 / 系统设计 / MVP 路线图）， 在文档站的设计文档归档中也可阅读。
训练代码零侵入：python train.py 永远是独立可跑的；GPUPlane 只做进程托管与观测，SDK 完全可选且永不向训练进程抛异常。
GPU 槽位调度：按卡独占分配（不靠利用率猜空闲），优先级队列、失败自动重试（OOM 除外）、CUDA_VISIBLE_DEVICES 自动注入。
三级指标接入：TensorBoard 目录实时 tail（L1，零改动）、SDK 直报（L2，from gpuctl import run）、系统指标 NVML（L3）。
日志：agent 全量落盘 + server 尾部 2000 行 + SSE 实时流，gpuctl logs -f 直接追。
Checkpoint 发现：watch 目录防抖扫描，按 step 关联 best 指标。
事件语义层：LOSS_NAN / OOM / DISK_LOW / 生命周期事件，规则引擎确定性判定。
SQLite 单文件：无 Kafka/Redis/Postgres，WAL 模式，一条命令在线备份。
离线韧性：agent 本地 jsonl spool，断连重放；server 端游标幂等去重，agent 重启不丢不重。
Related MCP server: colab-autopilot
实验管理：Project/Experiment CRUD 与 run 归组；Web UI Experiments 页 + run 对比视图（多 run 指标叠图、按 best 排序）。
评估闭环：POST /checkpoints/{id}/evaluations 排队 EVALUATE job（继承训练 job 的 working_dir/资源）→ 结果回挂 → GET /checkpoints:recommend 按 primary metric 推荐 checkpoint。
完整事件规则：LOSS_SPIKE / OVERFITTING_SUSPECTED / GPU_UNDERUTILIZED / DISK_LOW，进程内滚动窗口 + 去抖。
失败分类重试：OOM / EXIT_CODE / DISPATCH_FAILED 不自动重试，其余按 max_attempts 重排。
DockerRunner：与 ProcessRunner 同语义（日志/退出码/槽位），--gpus 注入、docker kill 取消。
事件外推：server.yaml 配置 ntfy/Bark webhook（severity/type 过滤，best-effort）；gpuctl event-hook 用事件流唤醒本地脚本。
框架 callbacks：gpuctl.callbacks 提供 Lightning / HF Trainer 薄封装，可选导入零依赖。
MetricDefinition UI：direction 与 global/project/experiment primary 可视化编辑；解析顺序 experiment → project → global，驱动 checkpoint 推荐。
Agent-native（MCP）：gpuctl-mcp 独立进程/包（fastmcp 3.4.7 pinned）暴露 21 个工具——11 observe + 5 control + 5 semantic；streamable HTTP stateless 核心。坏了不影响 server（design §15）。
语义层（无 LLM）：diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure 五个纯 Python 函数（规则 + 统计），REST 与 MCP 都是薄暴露层；每个返回带 next_actions 引导 Agent 下一步，无需轮询。
3 个 Skill：run-experiment / monitor-experiment / analyze-results（.claude/skills/gpu-training/），6 字段 frontmatter，allowed-tools 预授权 MCP 工具，编码"提交→监控→对比→推荐"实验循环。
插件打包：.claude-plugin/plugin.json（stdio MCP + skills + hooks 可分发）；.mcp.json（http，gitignored）。
AGENTS.md：仓库级 agent 规则（canonical，CLAUDE.md 镜像）——裸进程+SQLite 红线、实验循环、metric/job/ckpt 约定、OOM runbook。
读写域分级：GET /auth/whoami 暴露 {name, scope, can_write}；写操作（submit/cancel/retry/evaluate）需 write-scope token，只读 token 返回 WriteScopeError。
验收：Agent 仅凭自然语言 + MCP，无任何人工平台交互，完成"提交训练 → 监控 → 对比 → 推荐"全循环。详见
docs/08-v0.3-acceptance.md。
Experiments 工作区重设计（W&B 式）：实验列表带 run 状态计数 / best primary / 最近活跃；详情页是多指标面板工作区——★ primary 置顶、面板增删、runs 勾选入图、step/relative/wall 三种 x 轴，视图状态全部 URL 深链（?metrics=&runs=&smooth=&x=）可直接分享。
专业图表工具链：TensorBoard 风格 EMA 平滑（原始线淡化垫底）、LTTB 降采样、crosshair 精确读数 tooltip（step + 相对时间 + 墙钟时间、平滑值附原始值）、拖拽缩放 / 双击重置、legend 点击显隐 / ctrl-点击隔离，run 配色跨 Dashboard/Experiments/Compare/RunDetail 一致。
指标实时推送：POST /runs/metrics:query 批量取数 + GET /runs/{id}/metrics/stream SSE 逐点推流 + 5s 水位轮询兜底修丢点；未缩放时曲线自动跟随新数据生长，用户缩放后保持视野不动。
工作流导向控制台：Dashboard active runs 带进度条 + 实时 sparkline + 队列卡；RunDetail 对 RUNNING run live 优先（实时曲线/最近事件/日志折叠），FAILED/LOST 显示失败诊断卡（likely cause + evidence + suggested fixes）；Jobs 页写操作按 token scope 隐藏，cancel 一律二次确认。
环境：Python ≥3.12，uv。
git clone <repo> && cd GPUPlane
uv sync # 安装全部组件（server/agent/cli/sdk）
# 1. 启动 server（GPU 机器上；首启自动生成 admin token 写入 ~/.gpuctl/server.yaml）
uv run gpuctl-server
# 2. 启动 agent（同机；token 从 server.yaml 复制到 ~/.gpuctl/agent.yaml）
uv run gpuctl-agent
# 3. 提交训练（cpu_only 示例先跑通，再上 GPU）
uv run gpuctl job submit -n mnist -g 1 \
-d "$PWD/examples/mnist" --watch checkpoints \
-- python train.py --epochs 3
# 注意：-d/--working-dir 按【agent 所在机器】解释，CLI 不做本地改写；
# 从笔记本向远端提交时传远端绝对路径。
# 4. 观测
uv run gpuctl status # 节点/队列总览
uv run gpuctl job list # 任务状态
uv run gpuctl logs -f <job-id> # 实时日志
uv run gpuctl run show <run-id> # 指标摘要（latest/best/trend）
# 5. Web UI（server 自动托管 web/dist；也可用 GPUCTL_WEB_DIST 指定）
open http://<gpu-host>:8600 # 输入 token 登录导入历史实验（TB events + checkpoints → IMPORTED run）：
uv run gpuctl import-run ~/experiments/old-run --project legacy依赖只有约 50 个小 wheel（torch 不属于平台依赖，用训练机现有环境即可）。 网络受限时在能上网的机器预下载，再拷到目标机离线安装：
# 在能上网的机器（如 Mac）上，为 Linux x86_64 + py3.12 下载
uv export --format requirements-txt --locked --no-hashes --no-dev -o /tmp/reqs.txt
grep -v '^-e ' /tmp/reqs.txt > /tmp/reqs-clean.txt
uv run --python 3.12 --with pip python -m pip download -r /tmp/reqs-clean.txt hatchling editables \
--python-version 312 --only-binary=:all: \
--platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \
--platform manylinux2014_x86_64 -d ./wheels
rsync -az ./ ./wheels/ gpu-host:~/GPUPlane-wheels/ # 含仓库本体
# 目标机（离线）
cd ~/GPUPlane && uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --no-index --find-links ~/GPUPlane-wheels \
-r ~/GPUPlane-wheels/reqs-clean.txt hatchling editables
uv pip install --python .venv/bin/python --no-index --no-build-isolation \
-e ./packages/common -e ./packages/tbreader -e ./packages/sdk \
-e ./packages/server -e ./packages/agent -e ./packages/cli同机（推荐起步）：server + agent 都跑在 GPU 机器上，笔记本浏览器/CLI 经 LAN 访问
（server.yaml 设 host: 0.0.0.0，token 认证）。
分体：server 跑在常开的轻量机器（甚至 Mac mini/NAS），agent 跑在各 GPU 机器，
agent.yaml 的 server_url 指向 server 的 ws://<ip>:8600。agent 单向出站长连接，
GPU 机器无需任何入站端口，断线自动重连 + spool 重放。
~/.gpuctl/server.yaml 加 webhook（ntfy 示例；Bark 用 kind: bark + 设备 URL）：
webhooks:
- url: "https://ntfy.sh/my-gpu-topic" # 手机装 ntfy 订阅同一 topic
kind: ntfy
min_severity: warning # info|warning|critical，低于此不推
# types: ["OOM", "LOSS_NAN"] # 可选：只推这些事件类型本地自动化（事件到达即在当前机器跑一个命令，如唤醒本地 agent）：
gpuctl event-hook --severity critical -- /path/to/on-event.sh
# 事件经 GPUCTL_EVENT_TYPE/SEVERITY/MESSAGE/RUN_ID/... 环境变量 + stdin JSON 传入gpuctl-mcp 是独立 adapter 进程（不依赖 server/agent），把控制面暴露成 21 个 MCP 工具。
配好后，Claude Code（或任何 MCP 客户端）用自然语言完成"提交训练 → 监控异常 → 对比 checkpoint → 给推荐"，全程不碰 Web/CLI：
# 1. 起 adapter（独立进程；指向 server，带 write-scope token）
GPUCTL_SERVER_URL=http://127.0.0.1:8600 GPUCTL_MCP_TOKEN=<write-token> \
gpuctl-mcp serve --port 18602 # streamable HTTP, stateless
# stdio 形态（插件用）：gpuctl-mcp stdio
# 2. 让 Claude Code 发现它（仓库根 .mcp.json，已 gitignore）
cat > .mcp.json <<'JSON'
{ "mcpServers": { "gpuctl": { "type": "http",
"url": "http://127.0.0.1:18602/mcp",
"headers": { "Authorization": "Bearer <write-token>" } } } }
JSON
# 3. 自然语言驱动（skill 自动加载，无需手点工具）
claude -p "提交一个 mnist 训练，跑完告诉我结果，再对比最近两次 run 给我最好的 checkpoint"读写域分级：只读 token 下 submit_job/cancel_job/retry_job/evaluate_checkpoint/set_primary_metric 返回 WriteScopeError。
三个 skill（.claude/skills/gpu-training/）编码实验循环并预授权 MCP 工具；详见
docs/08-v0.3-acceptance.md。
from gpuctl import run
run.init(project="qwen-sft", experiment="lr-2e5", config={...}) # 平台 job 内自动 attach，可省略
run.log({"train/loss": loss.item()}, step=step) # 有界队列，绝不阻塞/抛错
run.log_checkpoint(path, step=step) # 只登记，不搬运文件
run.finish()平台 dispatch 的 job 内零配置（env 自动注入）；平台外裸跑自动注册 source=sdk 的 run；
无 server 时静默降级为本地 jsonl（~/.gpuctl/spool/），训练脚本行为完全不变。
┌────────────┐ WS (出站) ┌──────────────┐ REST/SSE ┌──────────┐
│ Agent(s) │ ───────────► │ Server │ ◄──────────── │ CLI/Web │
│ monitor/ │ heartbeat │ scheduler │ │ (同源) │
│ runner/tb │ metrics/logs│ SQLite(WAL) │ ◄──── HTTP ─── │ SDK │
└────────────┘ └──────────────┘ └──────────┘monorepo：packages/{common,server,agent,sdk,cli,mcp,tbreader} + web/ + examples/mnist + .claude/skills/（agent skills）+ .claude-plugin/。packages/mcp 是独立 adapter 进程，不依赖 server/agent。
uv run gpuctl backup # 在线备份 SQLite 到 <data_dir>/backups/
uv run gpuctl backup-agent # 在每台 Agent 主机归档完整 job 日志/runtime/spool
# 常驻运行见 deploy/systemd/（user unit + enable-linger）
uv run gpuctl job retry <id> # 失败任务重新排队
uv run gpuctl job cancel <id> # SIGTERM → 5s → SIGKILL（整进程组）
uv run pytest tests/ -q # Python 测试（当前 145 个用例）
cd web && pnpm test:e2e # 浏览器 smoke（2 个用例）
uv run ruff check . && uv run mypyDocker runner 是可选能力；Process runner 仍是默认。使用 GPU 容器前，Agent 主机必须先按 NVIDIA 官方安装指南 安装 Container Toolkit，并把 runtime 写入 Docker 配置：
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker # 先确认没有运行中的容器
docker run --rm --gpus all <cuda-image> nvidia-smi在 WSL2 上还应先确认宿主透传正常（nvidia-smi 可见 GPU）；Toolkit 只负责把已透传的
GPU 暴露给容器，不能替代 Windows/WSL 驱动。
训练代码独立性：python train.py 脱离平台必须始终可用。
best-effort telemetry：任何上报失败只落本地缓冲，绝不向训练进程抛异常。
Process runner 是一等公民，不强制 Docker/Git。
GPU 调度按槽位独占，永不依据利用率判断空闲。
Job ≠ Run：Job 是调度单元，Run 是训练语义单元（一次 attempt 一个 Run）。
SQLite + 无消息队列；server 单 worker（内存 pub/sub 是刻意的）。
GPUPlane is licensed under the Apache License 2.0. Attribution information is in NOTICE.
This server cannot be deployed
GPU compute for agents: run commands on an L4/A100/H100, watch logs, billed per second.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
