语义工具（5）

语义工具把十万条 metric point 压缩成 Agent 可直接消费的结论。全部为纯 Python 规则与统计实现——结果可复现、无 LLM 成本、离线可用； LLM 推理留给调用方 Agent。只需 read scope。

`diagnose_run(run_id)`

把一个 run 压成语义结论：进度、primary metric 的收敛情况（trend/best/stalled）、异常（OOM/NaN/过拟合/…）、健康警告、next_actions。理解一个 run 的起点。

`compare_runs(ids, metric?, suite?, dataset?, dataset_version?)`

多 run 并排对比，按 primary metric 的 best 值（direction-aware）选出胜者。一批实验跑完后挑“保留哪个”用。metric 缺省为 primary； suite/dataset/dataset_version 可按评估口径过滤。

`compare_checkpoints(ids, metric?, suite?, dataset?, dataset_version?)`

按评估结果的 primary metric 对比 checkpoint（direction-aware）。挑“部署哪个 checkpoint”用。

`get_best_checkpoint(run_id? 或 experiment_id?, metric?, suite?, dataset?, dataset_version?)`

按 primary metric 返回单个最优 checkpoint——推荐部署或进一步评估的对象。 run_id（单 run 内）与 experiment_id（跨整个实验）二选一。

评估优先：优先使用成功评估的 primary metric；没有评估时回退到训练 run 的 best 值（训练集指标，更弱）。有 checkpoint 没评估时，先 evaluate_checkpoint 再宣布胜者。

`explain_failure(run_id)`

规则式失败归因：exit code + 失败原因 + 已分类事件（OOM/NaN/断连）+ 日志模式 → 结构化的 likely_cause + suggested_fixes + next_actions。 run 失败（FAILED）时调用。

使用顺序

diagnose_run（这个 run 健康吗？）
  ├─ 失败 → explain_failure → 按建议改配置 → retry_job
  └─ 正常 → compare_runs（跨 run 挑胜者）
            → evaluate_checkpoint（补评估）
            → compare_checkpoints / get_best_checkpoint（挑部署对象）