实验循环与 Agent 接入

GPUPlane 的核心用法：让 Agent 驱动实验循环。 gpuctl-mcp 把控制面暴露成 21 个 MCP 工具，配好后 Claude Code（或任何 MCP 客户端） 可以用自然语言完成「提交训练 → 监控异常 → 对比 checkpoint → 给出推荐」，全程不碰 Web/CLI。

run-experiment  →  monitor-experiment  →  analyze-results  →  (keep / revert)
submit_job         get_run_summary         compare_runs         checkpoint 路径
                   list_events             get_best_checkpoint
                   diagnose_run            evaluate_checkpoint

接入方式

gpuctl-mcp 是独立进程，两种形态：

streamable HTTP（远程/多客户端，推荐）

GPUCTL_SERVER_URL=http://127.0.0.1:8600 GPUCTL_MCP_TOKEN=<write-token> \
  gpuctl-mcp serve --port 18602

stdio（本机单客户端，插件形态）

gpuctl-mcp stdio

让 Claude Code 发现它（仓库根 .mcp.json）：

{
  "mcpServers": {
    "gpuctl": {
      "type": "http",
      "url": "http://127.0.0.1:18602/mcp",
      "headers": { "Authorization": "Bearer <write-token>" }
    }
  }
}

然后直接用自然语言：

claude -p "提交一个 mnist 训练，跑完告诉我结果，再对比最近两次 run 给我最好的 checkpoint"

三个 Skill

.claude/skills/gpu-training/ 下的三个 skill 把实验循环编码为约定， 并通过 allowed-tools 预授权所需 MCP 工具：

Skill	职责
run-experiment	提交训练：检查节点、构造 submit_job、确认工作目录语义
monitor-experiment	监控：读 run summary / events / 诊断，识别异常并建议处置
analyze-results	分析：对比 run 与 checkpoint、排队评估、给出推荐

Skill 的价值不在于“能调工具”，而在于把约定带进去：headless 命令、 working_dir 按 agent 机器解释、OOM 后先改配置再 retry、评估优先于训练期 best。

读写域分级

Token 分 read / write 两个域：

• read：11 个观测工具 + 5 个语义工具全开。
• write：额外开放 5 个控制工具（submit_job / cancel_job / retry_job / evaluate_checkpoint / set_primary_metric）。

只读 token 调用控制工具会得到 WriteScopeError；adapter 启动时会向 server 核实 token 域并打印提示。给“只看不碰”的 Agent 发 read token 即可。

长时任务的约定

一次训练可能跑几小时，绝不能伪装成同步工具调用。submit_job / evaluate_checkpoint 立即返回 task handle（内含 job_id），随后用 get_job / get_run_summary 轮询 （GPU 作业建议 5–30s 间隔），或由 webhook / event-hook 在事件发生时唤醒 Agent。

延伸阅读

• MCP 工具参考（21 个工具全集）
• v0.3 验收实录：Agent 自然语言完成全循环