分析 LLM 实验（单实验或对比实验）结果并生成报告

当需要分析一个或两个 LLM 实验（含对比基线）的结果、回答关于实验的问题、或导出分析报告时使用。

适用场景

解决思路

1. 后端检测（每次调用开始时先执行）：1) 若参数中任意位置出现 `--backend pup`，立即使用 pup 模式，跳过后续检测；2) 检查活动工具列表中是否存在 `get_llmobs_experiment_summary`（可能带 `mcp__datadog-llmo-mcp__` 前缀），存在则用 MCP 模式，并记录该工具的确切名称（带或不带前缀）供本次调用所有 MCP 调用使用；3) 若 MCP 工具不存在，用 Bash 运行 `pup --version`，返回含 `"version"` 的 JSON 即确认 pup 可用，则用 pup 模式，并按文末 Tool Reference 把每个 MCP 调用翻译为对应 pup 命令；4) 两者都不可用则停止并告知用户连接 MCP 服务器（`claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs'`）或安装 pup。`--backend pup` 参数在传给技能逻辑前需剥离。
2. pup 调用规则：通过 Bash 执行 `pup llm-obs <subcommand> [flags]`；pup 始终输出 JSON，直接解析（无需像 MCP 那样解包 content-block）；若返回鉴权错误，提示用户运行 `pup auth login` 并停止；并行化时在单条消息中发起多个 Bash 调用（每个调用一条 pup 命令）。
3. 每次调用开始时生成一个 8 位十六进制 invocation ID（如 `3a9f1c2b`），整个调用期间保持不变。
4. 意图标记：每次 MCP 调用时给 `telemetry.intent` 加前缀 `skill:agent-observability-experiment-analyzer[<inv_id>] — ` 后接调用原因；仅首次 MCP 调用使用 `skill:agent-observability-experiment-analyzer:start[<inv_id>] — `（注意 `:start` 后缀）。
5. Phase 0 模式与输出解析：从 $ARGUMENTS 提取 1 或 2 个 UUID 作为实验 ID（第一个为基线/主实验，第二个为候选）；提取 `--output agent|file|notebook` 标志；剩余文本为问题。模式判定：2 个 ID 无问题=对比探索；2 个 ID+问题=对比问答；1 个 ID 无问题=单实验探索；1 个 ID+问题=单实验问答。
6. 输出模式：若参数已给 `--output` 则直接使用；否则在继续前发起两次独立的顺序 `AskUserQuestion`（绝不合并为一次）：先问分析类型（探索还是特定问题，若上下文已明确可跳过），再单独问输出目的地（对话、文件或 Datadog notebook）。输出模式：agent（默认，在对话中展示完整报告）；file（先提议路径 `evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md` 让用户确认或调整）；notebook（最后调用 `mcp__datadog-mcp-core__create_datadog_notebook`，pup 模式用 `pup notebooks create --title "TITLE" --file /tmp/nb_cells.json`，两者都不可用则输出 MCP 安装说明并询问是否回退到文件或对话输出）。
7. Phase 1 定位：对比模式对两个实验调用 `get_llmobs_experiment_summary`，产出并排对比（规模、指标、维度、即时红旗、明显改进或回退）；当 `error_count > 0` 时对 `error_type` 调用 `get_llmobs_experiment_dimension_values` 并按异常类报告明细（报告数量与类型，不报百分比）。单实验模式调用 summary 确定样本数、错误数（含 error_type 明细）、按 `metric_type`（score/boolean/categorical）分组的可用指标、可用维度及红旗；不要从标签名或前缀推断指标含义或语义分组。
8. Phase 1.5 指标选择：步骤1 仅用 summary 统计量对每个指标分类——`always_zero`（max==0，功能禁用无信号）、`perfect`（min==1，无诊断信号）、`saturated`（mean≥0.99 且 min<1，诊断价值低）、`struggling`（mean<0.70，诊断价值最高）、`interesting`（0.70≤mean<0.99 且 min<max，中等诊断价值）。步骤2 在提问前把完整指标表（Metric/Mean/Class）打印到对话，标注 always_zero 指标。步骤3 用 `AskUserQuestion` 动态生成选项："Struggling metrics (N) — Recommended"（仅 N≥1 时显示，描述列出各指标标签与均值；无 struggling 则替换为 "Lowest-performing metrics (N)"）、"Interesting + struggling (N)"（仅当存在 interesting 时）、"All metrics (N)"（始终显示）、"A specific metric"（始终显示）。若用户选特定指标，再发一次 `AskUserQuestion` 展示均值最低的 4 个指标（仅限 struggling 和 interesting 类，不含 always_zero 和 perfect），并提示可在 Other 中输入表中任意指标名；选定后 Phase 2–4 严格限定该指标。范围强制：用户选分组或特定指标后，Phase 2–4 不得对选择外的指标调用 `get_llmobs_experiment_metric_values`。
9. Phase 2 信号发现与 UI 链接：对比模式仅用 Phase 1.5 选定的指标（与共享指标取交集）和共享维度，识别候选优于基线的分段、回退分段、错误类型差异、分布偏移或覆盖缺口、权衡（如高召回低精度）。生成 Datadog 对比 UI 链接：基础 URL `https://app.datadoghq.com/llm/experiment-comparison`，必需参数 `baselineExperimentId`、`experimentIds`（candidate%2Cbaseline）、`tableView=all`，可选 `project`、`compareDatasetId`、`selectedEvaluation`（优先级：overall/overall_score/rubric 指标→主指标→首个共享指标）；生成 2–4 个链接（主对比、回退视图、校准视图、最差分段视图，仅当支持时，绝不伪造过滤器）。单实验模式仅对选定指标跨所有维度测量，识别最差分段、意外通过率、整体通过率与方差，生成 `https://app.datadoghq.com/llm/experiments/{experiment_id}`。
10. Phase 3 深度分析：自动运行所有必要深挖，不请求批准或暂停，严格限定 Phase 1.5 选定指标。问答模式聚焦回答问题所需内容（拉取特定样本、按相关维度分段、检查示例）；探索模式广泛调查最有意思的信号（按分段/类别增量或通过率分析、错误重叠与独特失败模式、代表性失败样本 2–5 个定性检查、聚类错误主题分析）。规则：优先廉价高信号分析，不要过早停止；所有输出中遮蔽或脱敏 PII；避免破坏性操作。为每个采样事件生成 span 链接 `https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id}`，`sp` 参数值需百分号编码（`[`→`%5B`、`{`→`%7B`、`"`→`%22`、`}`→`%7D`、`]`→`%5D`）。为每个深挖分段生成样本链接 `https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value}`；若不确定过滤器 URL 格式对该维度有效，则省略过滤参数只链接实验根，绝不伪造过滤器 URL。
11. Phase 4 综合：对比探索模式给出明确改进、明确回退或风险、中性或未变区域、1–4 条与证据挂钩的根因假设、优先级建议（按现状发布/阻止/按分段门控/组合行为）；对比问答模式给出直接答案与明确结论、支持证据（指标、百分比、事件示例）、相关上下文（注意事项、数据局限）；单实验探索模式给出整体性能评估、最差分段与根因、失败原因假设、建议的后续实验；单实验问答模式给出直接答案与结论及实验数据支持证据。所有模式在详细发现前先给一行问题类型统计（如 "3 agent issues, 1 evaluator/dataset issue, 1 ambiguous"），尽量用量化增量/比率，脱敏 PII。无论实验复杂度、指标数量或答案多明显，始终产出 `## Summary & Recommendations` 和 `## Synthesis` 两节。
12. Phase 5 输出交付：agent 模式在对话中按报告格式展示完整报告；file 模式写入预先确认的路径并确认 "Report saved to `<path>`."；notebook 模式调用 `mcp__datadog-mcp-core__create_datadog_notebook`，参数 `name` 按模式命名（对比探索 `Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD`、对比问答 `Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD`、单实验探索 `Experiment Analysis: {experiment_short} — YYYY-MM-DD`、单实验问答 `Experiment Q&A: {experiment_short} — YYYY-MM-DD`，short 为 UUID 前 8 字符），`cells` 每节一个 cell（Cell 1 Summary & Recommendations 含 Experiment/Key Findings/Recommendations 三个 `###` 子标题，始终第一且不跳过；Cell 2 Orientation 表；Cell 3 What Changed 仅对比模式；Cell 4 Signals/Answer；Cell 5…N 每个深挖发现一个 cell；Cell N+1 Synthesis 始终倒数第二；Cell N+2 UI Links），所有 cell 省略顶层标题 `# Experiment Analysis Report`，`time` 为 `{ "live_span": "1h" }`；创建后输出 `"Report exported to notebook: <url>"`；工具不可用则按 Phase 0 回退。
13. Phase 6 对话式跟进：交付报告后追加跟进小节，列出 3–4 个基于实际发现的后续方向（如深入某回退原因、对比两个失败簇的错误模式、若发现失败或回退则建议对同一 ml_app 运行 `/agent-observability-trace-rca`），并询问是否还有其他问题。报告后保持活跃，用相同 MCP 工具回答后续问题并引用已收集的发现，除非新问题需要否则不重跑已做分析。
14. 报告格式链接规则：凡出现完整实验 UUID 处渲染为指向 `https://app.datadoghq.com/llm/experiments/{full_uuid}` 的 Markdown 链接；Orientation 表及后续所有含 Baseline/Candidate 列的表中，将整个列标题包裹为链接（格式 `[Baseline \`{short_id}\`]({baseline_url})` 和 `[Candidate \`{short_id}\`]({candidate_url})`），使整个表头单元格可点击。报告结构含：标题、Question（仅问答模式）、Summary & Recommendations（Experiment 链接与 2–3 句执行摘要、Key Findings、Recommendations）、Orientation、What Changed（仅对比模式，无可检测差异则写 "No configuration differences detected between experiments."）、Signals/Answer to Question、Deep Dive Findings（每个发现含 Segment/Impact/Severity/样本链接、Issue type 三选一 Agent/Evaluator-Dataset/Ambiguous、What's happening、Representative examples、Root cause hypothesis、Recommendation）、Synthesis（Issue tally、Overall Performance Assessment、Worst-Performing Segments、Root Cause Hypothesis、Recommended Next Experiments）、UI Links。
15. 操作规则：不对实验做任何假设（模型、任务、指标、schema、维度），全部通过检查数据推断；所有结论基于具体证据（事件 ID、计数、百分比）；展示计算过程（计数与比率）；避免无观察证据支持的推测性解释；所有用户可见输出中遮蔽或脱敏 PII。
16. pup 模式工具映射（仅 pup 模式适用）：`get_llmobs_experiment_summary(experiment_id)` → `pup llm-obs experiments summary EXPERIMENT_ID`；`list_llmobs_experiment_events(...)` → `pup llm-obs experiments events list EXPERIMENT_ID [--filter-metric-label L] [--sort-by-metric M] [--sort-direction asc|desc] [--limit N]`（使用前用 `pup llm-obs experiments events list --help` 确认标志名）；`get_llmobs_experiment_event(...)` → `pup llm-obs experiments events get EXPERIMENT_ID EVENT_ID`；`get_llmobs_experiment_metric_values(...)` → `pup llm-obs experiments metric-values EXPERIMENT_ID --metric-label L [--segment-by-dimension D] [--segment-dimension-value V]`；`get_llmobs_experiment_dimension_values(...)` → `pup llm-obs experiments dimension-values EXPERIMENT_ID --dimension-key K`；`create_datadog_notebook(...)` → `pup notebooks create --title "TITLE" --file /tmp/nb_cells.json`（用 `pup notebooks create --help` 确认标志）。cells 文件为 cell 对象 JSON 数组：`[{"attributes": {"definition": {"type": "markdown", "text": "## Section\n\nContent."}}, "type": "notebook_cells"}]`。绝不向用户展示内部工具调用、schema 或实现细节。

适用边界 · 注意事项

• 没有 Datadog MCP 服务器或 pup CLI 时无法使用（需先连接 MCP 或安装 pup 并登录）。
• 需要分析的不是 LLM 实验（如普通日志、trace 根因分析）时，应改用其他技能（如 `/agent-observability-trace-rca`）。
• 实验数据中指标标签名不可靠，不能仅凭标签名或前缀推断指标含义或语义分组。