控制工具（5）

控制工具改变平台状态，需要 write scope token；只读 token 调用会得到 WriteScopeError。长时操作一律返回 task handle，不阻塞调用方。

`submit_job(command, working_dir, name?, gpus=1, cpu_only=false, priority=100, project?, experiment?, env?, watch_dirs?)`

向调度器提交 TRAIN job，立即返回 task handle（含 job_id）。

参数	说明
`command`	argv 数组，如 `["python", "train.py", "--epochs", "10"]`。必须 headless——交互式命令（`-i`、REPL、`--pdb`）会永远挂住槽位
`working_dir`	agent 主机上的绝对路径，不是调用方机器
`gpus` / `cpu_only`	预留 GPU 数；`cpu_only=true` 等效 `gpus=0`
`priority`	越大越先调度（默认 100）
`project` / `experiment`	归组名称（不存在则创建）
`watch_dirs`	checkpoint 监视目录（相对 working_dir）

返回后：get_job(job_id) 轮询直到 run 创建，然后 get_run_summary(run_id)。

`evaluate_checkpoint(checkpoint_id, command, suite?, dataset?)`

为 checkpoint 排一个 EVALUATE job：继承训练 job 的 working_dir 与资源， checkpoint 路径经 GPUCTL_EVAL_CHECKPOINT 环境变量传入。评估脚本需按约定输出 {"metrics": {...}}；结果回挂到该 checkpoint，供 compare_checkpoints / get_best_checkpoint 使用。

`cancel_job(job_id, confirm=false)`

取消运行中/排队中的 job（SIGTERM → 5s → SIGKILL，整进程组）。

`retry_job(job_id)`

把终态 job（FAILED/CANCELLED/SUCCEEDED/LOST）重新排为 QUEUED。 复用同一 job id，新 attempt 产生新 Run。

`set_primary_metric(metric, project_id?, experiment_id?)`

设置 global / project / experiment 级的 primary metric： experiment 覆盖 project 覆盖 global；metric=None 清除该级覆盖、恢复继承。两个 scope 参数都省略时为 global。详见指标与 Primary Metric。

最小写入循环

h = submit_job(command=["python", "train.py"], working_dir="/home/me/mnist",
               watch_dirs=["checkpoints"], experiment="baseline")
# …get_job(h.job_id) 轮询 → run 创建后 get_run_summary / diagnose_run…
ev = evaluate_checkpoint(checkpoint_id="ckpt_…", command=["python", "eval.py"])
# …评估完成后…
best = get_best_checkpoint(experiment_id="exp_…")