事件与诊断

server 内置一个确定性规则引擎（EventDetector，无 LLM），流式消费指标与日志，产出带 severity 的事件。事件是“平台发现异常 → 人/Agent 介入”的标准通道。

事件规则

事件	触发条件（默认阈值可配）	severity
`LOSS_NAN`	loss 出现 NaN/Inf	critical
`OOM`	日志匹配 `CUDA out of memory`，配合 exit code 与显存曲线	critical
`DISK_LOW`	输出盘剩余 <5%	critical
`AGENT_DISCONNECTED` / `JOB_LOST`	心跳超时	critical
`LOSS_SPIKE`	当前值 > 滚动中位数 + 6×MAD	warning
`OVERFITTING_SUSPECTED`	eval/loss 距最低点回升 >10% 且 train/loss 仍下降，持续 3 次 eval	warning
`GPU_UNDERUTILIZED`	RUNNING 中 GPU util <20% 且显存 <30%，持续 10 分钟	warning
`RUN_STARTED` / `RUN_FINISHED` / `CHECKPOINT_CREATED` / `EVALUATION_FINISHED`	生命周期	info

OOM runbook（最常见的失败）

OOM 是 GPU 训练的第一大失败模式，平台为它准备了完整的处置链路：

EventDetector 从日志行 + exit code 判定 OOM（critical）。
explain_failure(run_id) 返回 likely_cause="OOM" 和 suggested_fix （更小 batch / gradient checkpointing / gradient accumulation）。
先读建议、改配置，再 retry_job——原样重试只会以同样方式再失败一次。

诊断语义工具

五个纯 Python 语义函数（规则 + 统计，结果可复现、离线可用），REST 与 MCP 都是薄暴露层：

工具	回答的问题
`diagnose_run`	这个 run 健康吗？（收敛趋势、过拟合迹象、警告）
`compare_runs`	几个 run 按 primary metric 谁好？
`compare_checkpoints`	几个 checkpoint 谁好？
`get_best_checkpoint`	这个实验该用哪个 checkpoint？（评估优先）
`explain_failure`	失败的 run 大概率是什么原因、怎么修？

每个返回都带 next_actions 字段，引导 Agent（或人）走正确的下一步，无需轮询。

事件外推（v0.2）

平台内的事件如何到达“平台外的人/Agent”，三条通道：

Webhook 推送到手机（ntfy/Bark）——~/.gpuctl/server.yaml：

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 传入

被动拉取——Agent 会话内 list_events(severity="critical") + get_run_summary 低成本轮询（分钟级即可，不用秒级）。