agent-observability-eval-pipeline

后端

检测 — 每次调用开始时，在执行任何操作之前，确定要使用哪个后端：

1. 如果用户在调用的任意位置传入了 --backend pup → 立即使用 pup 模式，无论是否存在 MCP 工具。跳过步骤 2–4。
2. 检查当前活动工具列表中是否存在 MCP 工具。判断依据是可用工具中是否包含 mcp__datadog-llmo-mcp__search_llmobs_spans。
3. 如果存在 MCP 工具 → 全程使用 MCP 模式。严格按照子技能工作流部分中的名称调用 MCP 工具。
4. 如果不存在 MCP 工具 → 检查 pup 是否可执行：通过 Bash 运行 pup --version。包含 "version" 的 JSON 响应表示 pup 可用。
5. 如果 pup 有响应 → 全程使用 pup 模式。每项子技能均附有工具参考附录，其中包含完整的 MCP→pup 映射。
6. 如果两者都不可用 → 停止并告知用户：

   “Datadog MCP 服务和 pup CLI 均不可用。请连接 MCP 服务（claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/v1/mcp?toolsets=llmobs'）或安装 pup。”

调用参数中的任意位置都可以使用 --backend pup。将其从参数中移除后再传给子技能，但要保留 pup 模式的决定 — 整个流水线运行期间，每项子技能也必须使用 pup 模式。

子技能后端传递：启动时检测到的后端适用于六个阶段中调用的所有子技能。不要在每个阶段重新检测。启动时只需宣布一次：

• MCP 模式：“（正在以 MCP 模式运行 — 所有功能均可用。）”
• pup 模式：“（正在以 pup 模式运行 — 全程使用 pup 命令。所有功能均可用。）”

**调用 ID：**每次调用一开始，在调用任何 MCP 工具之前，生成一个 8 位十六进制调用 ID（例如，3a9f1c2b）。整个调用期间保持不变。

**意图标记：**每次调用 MCP 工具时，在 telemetry.intent 前加上 skill:agent-observability-eval-pipeline[<inv_id>] — ，后接调用该工具的原因。仅在首次 MCP 工具调用时使用 skill:agent-observability-eval-pipeline:start[<inv_id>] — （注意 :start 后缀）。首次调用示例：skill:agent-observability-eval-pipeline:start[3a9f1c2b] — 预检查：确认 ml_app 在过去 7 天内有跟踪记录

---

Agent 可观测性评估流水线 — 分类 → RCA → 评估引导 → 数据集 → 实验 → 分析

面向已完成埋点的 ml_app 所有者，提供确定性的六阶段引导流水线。每个阶段都采用相同的结构 — 用横幅标明正在生成的实体，解释其用途，执行操作（调用子技能或执行一个小型可执行步骤），并设置检查点。你始终清楚自己当前所处的阶段。

[Precheck] verify ml_app, project, backend, credentials, output dir
   ↓
[Phase 1: Classify ml_app traces]        entity: ml_app, trace, span
   ↓
[Phase 2: Root cause analysis]           entity: failure mode, root cause
   ↓
[Phase 3: Bootstrap evaluators]          entity: evaluator, LLM judge
   ↓                                     (stop here with --stop-after eval-bootstrap
   ↓                                      for the classic eval-pipeline behavior)
[Phase 4: Create + publish dataset]      entity: dataset record, published dataset
   ↓                                     (executes: LLMObs.create_dataset)
[Phase 5: Generate + run experiment]     entity: experiment, task, evaluator, run
   ↓                                     (executes: python <generated_file>)
   ↓                                     (in-phase review beat before run)
[Phase 6: Analyze experiment]            entity: metric, comparison, recommendation

这项技能纯粹负责编排和引导 — 不包含新的分析逻辑。实际工作由子技能完成（agent-observability-session-classify、agent-observability-trace-rca、agent-observability-eval-bootstrap、agent-observability-experiment-bootstrap、agent-observability-experiment-analyzer）。这项技能提供的是确定性的结构：每个阶段具有相同的形式、相同的检查点约定和相同的实体说明横幅 — 因此，无论用户最初如何表述请求，体验始终一致，并有清晰的引导说明。

用法

/agent-observability-eval-pipeline <ml_app> [--project-name <name>] [--timeframe <window>] [--trace-limit <N>]
                                [--format py|ipynb] [--evaluator-style function|class|remote]
                                [--offline-evaluators | --online-evaluators | --data-only]
                                [--start-at classify|rca|eval-bootstrap|dataset|experiment|analyze]
                                [--stop-after classify|rca|eval-bootstrap|dataset|experiment|analyze]
                                [--classification-summary <path>] [--rca-report <path>]
                                [--dataset-file <path>] [--dataset-name <name>]
                                [--experiment-file <path>] [--experiment-id <uuid> | --experiment-url <url>]
                                [--app-root <path>] [--env-file <path>] [--output-dir <dir>]
                                [--backend pup]

参数：$ARGUMENTS

输入

输入	必需	默认值	说明
ml_app	是	—	要接入 / 作为评估对象的已插桩 LLM 应用。预检会验证其是否有近期轨迹。
--project-name	否	根据 pyproject.toml / setup.cfg / setup.py / package.json / cwd 推导（顺序与 agent-observability-experiment-bootstrap 相同）；若无法推导，则使用 experiment-sdk-default	流水线将数据集和实验写入的 Datadog 项目。SDK 会在首次使用 LLMObs.enable(project_name=...) 时按需创建项目。在预检中显示此项，以便用户在创建任何内容之前进行确认。
--timeframe	否	now-7d	Phase 1 分类和 Phase 4 数据集采样的回溯时间窗口。
--trace-limit	否	20	Phase 4 的采样上限。Phase 1 内部使用 min(20, --trace-limit) 作为分类样本数。
--format	否	py	在 Phase 5 中传递给 agent-observability-experiment-bootstrap：py（脚本）或 ipynb（Jupyter notebook）。
--evaluator-style	否	function	在 Phase 3 中传递给 agent-observability-eval-bootstrap，并在 Phase 5 中传递给 agent-observability-experiment-bootstrap：function、class 或 remote。
--offline-evaluators	否	开启（默认）	Phase 3：生成 Python SDK 评估器套件（BaseEvaluator / LLMJudge 类），在针对数据集运行的实验中执行。内部映射到 agent-observability-eval-bootstrap 的 sdk_code 模式。
--online-evaluators	否	关闭	Phase 3：直接向 Datadog 发布在线 LLM 裁判评估器（创建为已禁用的草稿；在 UI 中启用）。在线评估器会在生产 span 发出时运行。内部映射到 agent-observability-eval-bootstrap 的 publish 模式（原为 --publish）。
--data-only	否	关闭	Phase 3：仅生成本地数据块，不生成可执行评估器代码，也不在线发布。在进入 Phase 3 时，技能会提示用户从以下选项中选择：(a) 适用于实验的 DatasetRecordRaw[] JSON（内部映射到 agent-observability-eval-bootstrap --emit-dataset），或 (b) 用于本地分析、与框架无关的 JSON 评估器规范（内部映射到 agent-observability-eval-bootstrap 的 data_only 模式）。
--stop-after <phase>	否	analyze（运行全部内容）	在指定阶段完成后停止。classify = 仅 Phase 1。rca = 运行至 Phase 2。eval-bootstrap = 运行至 Phase 3（与经典 eval-pipeline 相同）。dataset = 运行至 Phase 4（数据集已创建并发布）。experiment = 运行至 Phase 5（实验已生成并运行）。analyze = 全部六个阶段（默认）。
--start-at <phase>	否	classify（从头开始）	跳过之前的阶段，从指定阶段开始。可用值与 --stop-after 相同。技能会从 <output-dir>/state/ 自动加载所需的前序阶段产物（参见“状态持久化与进入/退出”部分）。对于自动加载时找不到所需产物的阶段，请通过以下某个覆盖标志提供。可与 --stop-after 组合，以运行流水线中连续的一段。
--classification-summary <path>	否	若 --start-at rca 或更后续阶段，则从 <output-dir>/state/01-classification.md 自动加载	覆盖 Phase 2 使用的 Phase 1 输出。适用于前序状态文件缺失，或你想指定手动编辑过的版本的情况。
--rca-report <path>	否	若 --start-at eval-bootstrap 或更后续阶段，则从 <output-dir>/state/02-rca-report.md 自动加载	覆盖 Phase 3 使用的 Phase 2 输出。
--dataset-file <path>	否	从 <output-dir>/state/04-published-dataset.json 的 dataset_file 字段自动加载（或使用最新的 <output-dir>/dataset_<ml_app>_*.json）	本地 DatasetRecordRaw[] JSON。重新发布而不重新采样时，由 Phase 4 的发布子步骤使用。
--dataset-name <name>	否	若 --start-at experiment，则从 <output-dir>/state/04-published-dataset.json 自动加载	已发布的 Datadog 数据集名称，Phase 5 会将实验关联到该数据集。
--experiment-file <path>	否	若 --start-at experiment 且文件已存在，则从 <output-dir>/state/05-experiment-run.json 的 experiment_file 字段自动加载	生成的实验文件。如果提供此文件，Phase 5 会跳过代码生成子步骤 (5a)，直接进入审核环节 (5b) → 运行 (5c)。
--experiment-id <uuid>	否	若 --start-at analyze，则从 <output-dir>/state/05-experiment-run.json 自动加载	Phase 6 要分析的 Datadog 实验 ID。不能与 --experiment-url 同时使用。
--experiment-url <url>	否	同上自动加载	--experiment-id 的替代选项。技能会从 URL 末尾解析出 UUID。
--app-root	否	从 cwd / pyproject.toml 等解析	将 agent-observability-experiment-bootstrap 的任务函数内省范围限制在此目录树中。
--env-file	否	无（自动发现会遍历标准位置）	用于加载凭据的显式 .env 路径。在预检中显示，并写入生成的实验作为 ENV_FILE_OVERRIDE。
--output-dir	否	./experiments	数据集 JSON、发布脚本和生成的实验文件的写入位置。
--backend	否	自动检测	pup 会强制使用 pup 模式，无论 MCP 是否可用。
如果未提供 ml_app，请先询问用户，再继续。三个评估器输出标志（--offline-evaluators、--online-evaluators、--data-only）互斥——如果设置了多个，则报错退出。如果都未设置，默认使用 --offline-evaluators。为向后兼容，仍接受旧标志名 --publish 和 --sdk-code 作为别名，但所有输出中都映射为新名称。

---

预检

在阶段 1 之前，执行一次简短的验证——不要为此宣布“阶段”横幅；这是准备工作。输出一个区块的预检摘要，然后直接进入阶段 1。

1. 后端 — 已在此技能顶部检测。请在预检输出中注明所选后端，以便用户确认。

2. ml_app 有近期追踪记录 — 调用 search_llmobs_spans(query="@ml_app:\"<ml_app>\"", root_spans_only=true, limit=1, from="<timeframe>")（MCP），或调用对应的 pup 命令。如果结果为空，请停止并告知用户预检失败——没有可供评估的数据——并建议扩大 --timeframe 范围，或确认 ml_app 名称。

3. 解析 project_name — 如果提供了 --project-name <name>，则原样使用。否则，按照 agent-observability-experiment-bootstrap（工作流步骤 1）中相同的解析顺序推导：pyproject.toml → setup.cfg → setup.py → package.json → 当前工作目录的基本名称（slug 化）。最终值为 experiment-<service-name>；如果无法解析任何值，则回退为 experiment-sdk-default，并发出警告，告知用户显式设置 --project-name。

   项目创建语义：Datadog SDK 会在首次对该组织调用 LLMObs.enable(project_name=...) 时延迟创建项目（在阶段 4 的发布脚本中，以及阶段 5 生成的实验中）。用户无需在 UI 中预先创建任何内容。在预检输出中显示所选项目名称，以便用户在阶段 4 之前进行修改（如果名称不符合预期）。

4. 确保 --output-dir 和 <output-dir>/state/ 存在 — 通过 Bash 执行 mkdir -p <output-dir>/state。开销很小。state/ 子目录用于持久化各阶段的输出（参见下文“状态持久化和进入/退出”）。

5. 解析凭据。 按照下方的发现顺序，在阶段 4 需要 Datadog 凭据之前找到凭据——到发布步骤才发现失败会带来糟糕的用户体验。此阶段只读：不要写入任何新文件。不要向用户打印密钥值；只报告加载了哪个文件以及解析出了哪些键。

   发现顺序（每个变量以首次命中为准；Shell 环境变量始终优先于文件中的值）：

   1. 如果提供了 --env-file <path>，则优先尝试该文件。
   2. 当前 Shell 环境（os.environ）——已导出的 DD_API_KEY / DD_APPLICATION_KEY / DD_APP_KEY / DD_SITE 优先于文件中的值。如果所有必需键都已存在，则完全跳过文件加载。
   3. <output-dir>/.env — 如果用户之前运行过此技能，并在之前生成的产物旁放置了 .env，则优先使用该文件。
   4. <app-root>/.env — 已解析的 pyproject.toml / setup.cfg / setup.py / package.json 所在目录（如果都没有，则使用当前工作目录）。
   5. <app-root>/.env.local — 遵循被 git 忽略的本地覆盖文件惯例。
   6. <cwd>/.env — 如果当前工作目录与应用根目录不同，则作为回退选项。
   7. 逐级检查父目录：从当前工作目录开始，逐级向上查找 .env，直到到达 / 或用户的主目录。遇到第一个匹配项时停止。
   8. ~/.datadog/credentials — 如果 Datadog 已知的每用户凭据文件存在，则使用该文件。

   检查每个文件时，按行解析：跳过空行、注释行（#）和格式错误的行（不含 =）。如果行首有 export ，则去掉它（以便支持 .envrc 风格的文件）。在第一个 = 处分割。去掉值两侧的引号。仅设置 os.environ 中尚不存在的变量——绝不覆盖 Shell 中已有的变量。 必需的键：DD_API_KEY 和（DD_APPLICATION_KEY 或 DD_APP_KEY）。DD_SITE 是可选项（默认值为 datadoghq.com）。提供商的键（OPENAI_API_KEY、ANTHROPIC_API_KEY 等）会在第 6/7 阶段根据检查出的任务进行验证，而不是在此处验证。

   如果已找到所有必需的键——记录已加载的文件，并在 Precheck 块中输出一行摘要。继续。

   如果遍历所有位置后仍未找到必需的键——停止并向用户显示清晰、可执行的消息：

   "在 shell 环境变量或任何已发现的 .env 文件中都未找到 Datadog 凭据。继续之前有两个选项：

   • 在 shell 中导出：export DD_API_KEY=… 和 export DD_APPLICATION_KEY=…（如果使用非默认值，也设置 DD_SITE=…），然后重新调用此技能。
   • 创建一个 .env 文件：在 <app-root>/.env 中分别单独一行写入 DD_API_KEY=… 和 DD_APPLICATION_KEY=…，然后重新调用此技能。

   提交前，请确保 .env 已列入 .gitignore。"

   不要提议替用户创建 .env 文件——是否将机密保存到磁盘应由用户决定，而不是由技能决定。

输出预检摘要，然后开始第 1 阶段：

## Precheck

- Backend: <MCP | pup>
- ml_app `<ml_app>` has traces in <timeframe>: yes (<sample_count> root spans found)
- Project name: `<project_name>` (created lazily on first LLMObs.enable() call in Phase 4)
- Output dir: `<output-dir>` (created)
- Credentials: <one of:
    "loaded from shell env (DD_API_KEY, DD_APPLICATION_KEY, DD_SITE)"
  | "loaded from <relative path to .env file> (DD_API_KEY, DD_APPLICATION_KEY[, DD_SITE])"
  | "shell env + <relative path>: keys resolved from both (shell overrode file for <list>)"
  >
- Stop-after: <phase from --stop-after, default `analyze`>

Starting Phase 1 of 6.

凭据括号中列出的键必须准确反映实际发现的内容（以便用户确认没有加载任何意外内容）。绝不要打印键值。

---

阶段模板

以下每个阶段都使用此确切模板。请勿偏离——确定性的外壳能确保每次调用的流程体验一致。

## Phase N of 6: <Title>

**You are here.** Phase N of 6 — <one-line position summary>.

**What this phase produces**: <Entity name>
**What a <entity> is**: <2-3 sentence definition tailored to this phase>
**Why it matters**: <1 sentence on why the user needs this>

→ Action: <invoke <sub-skill> | execute <script>>

<full sub-skill output OR execution log reproduced here — do NOT summarize or truncate>

<after the action completes successfully, Write the phase output to
`<output-dir>/state/0N-<name>.{md,json}` per the State persistence contract — see
"State persistence and entry/exit" section. This happens BEFORE the checkpoint
so the file is on disk even if the user types `stop` next.>

---

### Checkpoint <N>

<concise summary of what was produced, where it lives (path / Datadog URL), and any caveats>

Before I continue to Phase N+1 (<next title>):
- <2–3 phase-specific review prompts the user can answer>

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

绝不自动进入下一阶段。 每次都在检查点暂停并等待用户明确输入。这项技能的核心是确定性——包括由用户决定何时继续。

如果当前阶段与 --stop-after 的值一致，请将检查点提示替换为停止摘要（参见本文件底部的“Stop-after 处理”）。

---

第 1 阶段：分类 ml_app 轨迹

实体：ml_app、trace、span。

教学横幅（原样使用，仅根据实际 ml_app 名称调整）：

什么是 ml_app：一种逻辑上的大模型应用——对 span 进行埋点时添加的名称（ml_app=<name>）。它将属于同一产品界面的所有生产轨迹和评估器运行分组。之后创建的每个数据集、实验和评估器都以此范围为目标。

什么是 trace：ml_app 的一次端到端执行——通常是针对单个用户请求的 Agent 循环，由一个或多个 span（大模型调用、工具调用、检索）组成。

此阶段的重要性：在查明故障根因（第 2 阶段）、启动评估器（第 3 阶段）或整理数据集（第 4 阶段）之前，你需要快速了解应用在生产环境中的实际运行情况，以及当前的故障模式。分类可以一次性提供这些信息。

轨迹池预览（必须执行）。调用子技能之前，先构建并展示一个 Datadog Traces UI 链接，该链接应打开第 4 阶段将采样的确切根 span 集合。这样用户就可以先查看采样池、发现异常项，或在任何分类工作运行之前调整 --timeframe。该链接必须与 agent-observability-eval-bootstrap --emit-dataset 在第 4 阶段使用的筛选条件一致（参见 agent-observability/agent-observability-eval-bootstrap/SKILL.md → 第 3D 阶段 → 采样）：仅根 span。

URL 构建规则：

1. 主机：在 DD_SITE 前添加 app.。如果未设置 DD_SITE，则默认为 app.datadoghq.com。
   • datadoghq.com → app.datadoghq.com
   • datadoghq.eu → app.datadoghq.eu
   • us3.datadoghq.com → app.us3.datadoghq.com
   • us5.datadoghq.com → app.us5.datadoghq.com
   • ap1.datadoghq.com → app.ap1.datadoghq.com
   • ap2.datadoghq.com → app.ap2.datadoghq.com
   • datad0g.com → app.datad0g.com（暂存环境）
2. 路径：/llm/traces（Agent Observability Traces 浏览器）。
3. 查询字符串：对 @ml_app:"<ml_app>" @status:ok @parent_id:undefined 进行 URL 编码，并绑定到 query=。
4. 时间窗口：将 --timeframe 转换为绝对纪元毫秒数（开始时间为 now - <duration in ms>，结束时间为 now），并绑定到 start= / end=。
5. 可选：追加 &paused=true，这样 UI 打开时不会实时流式加载结果。

紧接在 Action 块之前展示链接：

**Trace pool being analyzed** ({timeframe}, filter `@ml_app:"<ml_app>" @status:ok`, root spans only):

  <full URL>

Phase 1 will classify the first {min(20, trace-limit)} of these for orientation. Phase 4 will sample up to {trace-limit} from the same pool for the dataset. Click through if you want to see the pool before either runs, or adjust `--timeframe` and re-invoke if the window looks off.

操作：按照 agent-observability-session-classify 技能的 ml_app 模式执行，使用：

• ml_app = 提供的 ml_app
• timeframe = 提供的 timeframe
• sample_limit = min(20, trace-limit) — 尽量快速；第 4 阶段会进行更大规模的采样

按照该技能中的定义，运行完整的 ml_app 模式工作流（步骤 M1 至 M3）。输出完整的分类结果（所有精简的逐单元块，以及最终的 # Session Classification Summary）——不要总结或截断。第 2 阶段的 RCA 依赖完整文本作为上下文。

检查点 1

输出 # Session Classification Summary 后，展示：

## Phase 1 complete — you've seen what `<ml_app>` does in production

[verdict distribution table from session-classify]
[failure mode frequency table from session-classify]

**Trace pool for Phase 4's dataset sample**: <full URL from the Trace pool preview above>
(same filter / same timeframe — open it now if you want to scan for traces you'd rather exclude)

Next up — Phase 2 will diagnose *why* the failing traces are failing.

Before I continue:
- Do these failure patterns look right?
- Any traces you'd like to exclude from the dataset sample in Phase 4? (Paste trace IDs from the link above and I'll drop them.)
- Any quality dimension you already know you want to measure later?

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

等待用户明确确认。如果用户排除特定轨迹，将其标记为“用户排除”——从第 2 阶段的故障分类和第 4 阶段的采样中移除。不要重新分类。

---

阶段 2：根因分析

实体：failure mode、root cause。

教学提示：

什么是故障模式：应用以某种方式反复出现的故障模式，例如“模型编造引用 URL”“Agent 在工具调用之间忘记状态”“检索返回无关片段”。每种故障模式都有一个或多个根因（系统提示词缺陷、工具缺失、检索未命中等）。

为什么这一阶段很重要：只评估“这个回答好不好？”的通用评估器会忽略应用中实际出现的问题。RCA 能让阶段 3 提出针对应用实际故障模式的评估器，从而获得更精准的信号、更少的误报。

操作：按照 agent-observability-trace-rca 技能操作。

阶段 1 的 # Session Classification Summary 已在上下文中。该技能会通过阶段 0 步骤 0S 检查自动检测到它，并进入“基于分类”的路径——提取故障类别，展示 Classification Overview，然后直接进入阶段 2（开放式编码），而不执行自己的阶段 1 span 搜索。

完成整个工作流，直到阶段 6（编译后的 RCA 报告）。输出完整的 RCA 报告——不要总结。阶段 3 的检测需要完整报告位于上下文中。

检查点 2

## Phase 2 complete — root causes identified

[the Phase 6 RCA report is above]

Next up — Phase 3 will bootstrap evaluators that target these failure modes.

Before I continue:
- Do these root causes look accurate?
- Any failure modes to add, remove, or reframe?
- Which root causes should the evaluators target? (Default: all of them.)

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

等待用户明确确认。如果用户调整了分类体系，请先纳入这些更改，再继续。

---

阶段 3：引导式构建评估器

实体：evaluator、LLM judge。

教学提示：

什么是评估器：用于评估单条记录输出的函数。返回 bool / float / 结构化的 EvaluatorResult。有两种类型：代码评估器（确定性检查——JSON 有效性、正则表达式匹配、长度、自定义 Python）和 LLM-as-judge 评估器（根据评分标准评估模型——例如“此回答是否以检索到的文档为依据？”）。

运行模式（互斥；默认模式为 --offline-evaluators）：

• --offline-evaluators （默认）：生成一套 Python SDK 评估器（BaseEvaluator / LLMJudge 类），用于在针对数据集运行的实验中。如果要在本地运行实验，请使用此模式。
• --online-evaluators：将 LLM 评委评估器作为已禁用的草稿发布到 Datadog。启用后，它们会在生产 spans 发出时进行评估。如果想在生产环境中持续评估，请使用此模式。
• --data-only：仅生成本地数据块，不生成可执行评估器代码，也不在线发布。系统会提示你选择用于实验的数据集或本地分析数据块（请参阅下文“运行模式选择”）。

为什么这一阶段很重要：评估器是“这个输出看起来没问题”和“这个输出符合我们的质量标准”之间的契约。引导式生成的评估器套件以阶段 2 的故障分类体系为基础，比你通常手动编写的通用评估器更加精准。

操作：按照 agent-observability-eval-bootstrap 技能操作。

阶段 2 的 RCA 报告已在上下文中。该技能会自动检测 ## Failure Taxonomy 标题，并在阶段 0 进入“基于 RCA”的路径。

运行模式解析

调用子技能之前，先解析运行模式：

1. --offline-evaluators（默认）→ 不带模式标志调用 agent-observability-eval-bootstrap（其 sdk_code 默认值）。

2. --online-evaluators → 调用 agent-observability-eval-bootstrap --publish。

3. --data-only → 通过 AskUserQuestion 提示用户：

   “你为 Phase 3 选择了 --data-only。你想要哪种本地数据块？

   • 用于实验的数据集 — 适用于 LLMObs.create_dataset(records=...) 的 DatasetRecordRaw[] JSON。当你想用此技能采样的记录为实验提供初始数据时很有用。（内部调用 agent-observability-eval-bootstrap --emit-dataset <path>。）
   • 用于分析的本地数据块 — 与框架无关的 JSON 评估器规范，用于描述将生成哪些评估器，而不生成 Python 代码。可用于检查评估器覆盖范围，而无需运行任何内容。（内部调用 agent-observability-eval-bootstrap --data-only。）”

   如果用户选择“用于实验的数据集”，且流程会运行至 Phase 4（即 --stop-after 不是 eval-bootstrap 或更早阶段），请告知用户，Phase 4 的采样步骤将被跳过，改用 Phase 3 的输出——此处生成的数据集将是 Phase 4 发布的数据集。

原样传递 --evaluator-style。

agent-observability-eval-bootstrap 技能有自己的强制提案检查点（代码生成前的评估器套件提案）。请遵守该检查点——不要跳过或自动确认。

检查点 3

## Phase 3 complete — evaluator suite ready

- Mode: `<offline-evaluators | online-evaluators | data-only (dataset-for-experiment) | data-only (analysis-blob)>`
- Output: `<path to .py / .json / dataset-record JSON / "published as drafts to Datadog">`
- Evaluators emitted: <list of names>
- Coverage: <one-liner: which failure-mode categories are now covered>

Next up — Phase 4 will sample production traces into a dataset you can run experiments against (using these evaluators or the placeholders the experiment template ships with).

If you only wanted evaluators (the classic eval-pipeline flow), this is the natural stopping point: re-invoke with `--stop-after eval-bootstrap` to formalize that as the exit.

Before I continue:
- Do the generated evaluators look right?
- Any to drop or rename before they're referenced in the experiment?

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

等待用户明确确认。如果设置了 --stop-after eval-bootstrap，流程将在此结束——输出 Stop 摘要，而不是检查点，然后退出。

---

Phase 4：创建并发布数据集

实体：dataset、dataset record、已发布数据集（Datadog 端）、dataset_name、版本。

教学提示：

什么是数据集：实验运行时使用的一组命名记录。每条记录都有 input_data（任务接收的内容），以及可选的 expected_output（预期返回的内容）。数据集存放在 Datadog 的项目下，并带有版本号——每次推送如果更改了记录，都会生成新版本。

什么是记录：单个 (input_data, expected_output) 对，可选包含 metadata 和 tags。一条记录 = 实验中的一行。

“发布”意味着什么：将本地记录推送到 Datadog，使数据集可通过名称供后续所有实验访问。发布后，组织内任何有权限的成员都可以使用 LLMObs.pull_dataset(dataset_name="…") 拉取数据集，包括我们在 Phase 5 生成的实验代码。

这一阶段为何重要：实验需要一组稳定且可访问的输入。对生产跟踪进行采样，可以得到真实的数据集起点（即应用实际接收的输入）；在项目下发布数据集后，它就成为数据集整理工作与使用该数据集的实验之间的约定。

此阶段会在你的机器上执行代码（发布步骤通过 LLMObs.create_dataset(...) 写入 Datadog）。创建数据集步骤为只读；只有发布步骤会改变状态。

操作——两个子步骤，中间无需检查点：

4a — 将跟踪采样为 DatasetRecordRaw[] JSON。 按照 agent-observability-eval-bootstrap 技能的 --emit-dataset 模式执行：

/eval-bootstrap <ml_app> --timeframe <timeframe> --trace-limit <trace-limit> --emit-dataset <output-dir>/dataset_<ml_app>_<YYYYMMDD>.json

此模式会采样根 span、提取 (input_data, expected_output) 对、进行 PII 清理，并写入 JSON。它不会提议或生成评估器——数据集是唯一产物。完整规范请参阅 agent-observability/agent-observability-eval-bootstrap/SKILL.md → Phase 3D。

如果用户在检查点 1 排除了特定跟踪，请一并传递排除列表（子技能会在采样时将其排除——不要重新分类）。

逐字复现子技能的 ## Generated Dataset 摘要。 如果 Phase 3 已生成数据集，则跳过 4a。 如果用户在 Phase 3 中选择了 --data-only 和“用于实验的数据集”子模式，Phase 3 状态文件（state/03-evaluators.json）中的 mode: data_only_dataset，且 output_path 指向数据集 JSON。在这种情况下，完全跳过子步骤 4a，直接将 Phase 3 的输出传给 4b 的发布辅助脚本。显示一条说明：“正在复用 Phase 3 的数据集（<path>）；跳过重新采样。”

4b — 发布到 Datadog。 立即通过 Bash 调用预先提供的发布辅助脚本 <this-skill-dir>/scripts/publish_dataset.py。不要将脚本内容内嵌到此 SKILL.md 中，也不要从头重写——该辅助脚本是发布流程（凭据发现、标签规范化、项目创建、错误处理）的唯一准则。它接受 CLI 参数，因此无需替换占位符。

python <skill-dir>/scripts/publish_dataset.py \
  --records <absolute path to JSON from 4a> \
  --dataset-name <chosen dataset_name, default <ml_app>_seed_<YYYYMMDD>> \
  --project-name <resolved project_name from Precheck> \
  [--env-file <path>]   # repeatable; takes precedence over auto-discovery

<skill-dir> 解析为该技能的安装位置（例如，~/.claude/skills/agent-observability-eval-pipeline/）。脚本会输出以下内容之一：

• Loaded credentials from: <file paths>（如果有 .env 文件提供了值），然后
• OK dataset_name=<name> record_count=<N> url=<url>（成功时），或
• 在 stderr 中输出 ERROR: <message>，并以非零状态退出（认证失败、缺少密钥、ddtrace 导入失败等）。

给编排器的说明：

• 调用发布辅助脚本前，先检查导入是否可用：通过 Bash 运行 python -c "import ddtrace.llmobs"。如果失败，则停止并告知用户：

  "ddtrace 未安装在当前启用的 Python 环境中。请运行 pip install 'ddtrace>=4.7'，然后重新调用此技能（从头重新运行——Phase 1–3 的输出具有幂等性）。”

• 脚本中的 LLMObs.enable(project_name=...) 会实际应用 Precheck 中的 --project-name——Datadog 项目会在首次调用时延迟创建。
• 如果脚本输出了有关标签规范化的 WARNING: 行，请在检查点 4 中显示，以便用户了解其上游数据集包含格式错误的标签。
• 如果脚本输出了 Loaded credentials from: ...，请在检查点 4 中包含该文件路径。
• 如果脚本因认证错误（401/403）以非零状态退出，请显示 stderr 并停止——不要重试。告知用户最可能的原因是 .env 中的值已过期，并且在其 shell 中运行 export DD_API_KEY=... DD_APPLICATION_KEY=... 会优先使用这些值，可用于覆盖。
• 成功时，捕获输出的 dataset_name 和 url，并将其传入 Phase 5。将两者写入 Phase 4 状态文件（参见状态持久化部分）。

为什么 4a 和 4b 之间没有中间检查点？ 本地 JSON 会从 traces 中自动提取，并直接传入 LLMObs.create_dataset(records=...)——在常见情况下，这两个步骤之间基本没有可编辑的内容。如果用户希望在发布前检查或编辑 JSON，应单独运行 eval-bootstrap --emit-dataset，编辑 JSON，然后在手动发布后使用 --start-at experiment --dataset-name <name> 重新进入此流水线。

检查点 4

## Phase 4 complete — dataset created and published

- Local file: `<path>` (kept for inspection / re-publish)
- Records emitted: <N> (skipped: <M> with no usable output)
- PII redactions: <P>
- Tag normalizations: <T>
- Published as: `<dataset_name>` in project `<project_name>` <(created if it did not exist)>
- Datadog UI: <url or "open Agent Observability → Datasets to confirm">
- Caveat: `expected_output` is the **current production behavior baseline**, not ground truth. Treat the dataset as a regression-style baseline before promoting it to a labelled gold set.

Next up — Phase 5 will generate a Python experiment script that pulls `<dataset_name>` and runs your task code (auto-discovered) against it.

Before I continue:
- Confirm you can see the dataset in the Datadog UI (Agent Observability → Datasets → search `<dataset_name>`)?
- Any second thoughts on the records (we can re-emit and re-publish before generating the experiment)?

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

等待确认。

---

阶段 5：生成并运行实验

实体：experiment、task 函数、evaluator、实验运行、experiment.url、指标流。

教学提示：

什么是实验：一个程序化测试框架，它会针对数据集中的每条记录调用一个 task 函数（待测代码，通常是一次大模型调用），然后使用一个或多个 evaluators 对任务的输出进行评估。Datadog 会将所有结果汇总到一个实验视图中，供你比较不同运行的结果。

什么是任务函数：一个 Python 可调用对象，接收一条记录的 input_data 和一个 config 字典，并返回你的应用针对该输入本应返回的内容。此子技能会检查你的项目并自动查找此函数——除非没有找到，否则不会使用 # TODO(user) 占位符。

什么是评估器：参见上面的阶段 3。生成的实验默认附带占位评估器；如果你在阶段 3 使用了 --evaluator-style remote，就可以在这里接入这些名称。

什么是 experiment.url：Datadog Experiments UI 中该次运行的深层链接。阶段 6 会用它来分析结果。

此阶段为何重要：这是你的代码实际针对数据集运行并生成测量结果的阶段。生成只是成本较低的部分；运行会消耗提供商令牌并产生信号。

此阶段会在你的计算机上执行代码（Python 文件会在阶段内审查环节之后端到端运行）。

操作 — 分为三个子步骤，并在代码生成和运行之间设置阶段内审查环节：

**5a — 生成实验文件。**按照 agent-observability-experiment-bootstrap 技能操作：

/agent-observability-experiment-bootstrap \
  --dataset-name <dataset_name> \
  --project-name <project_name> \
  --format <format> \
  --evaluator-style <evaluator-style> \
  --app-root <app-root> \
  --env-file <env-file if set> \
  --output <output-dir>/experiment_<ml_app>_<YYYYMMDD>.<py|ipynb>

逐字复现该子技能的完整输出（包括生成的 SDK 调用摘要、“Task function source”代码块、凭据发现部分和 Next steps 代码块）。不要总结。“Task function source”代码块会告知用户自动接入的是哪个 module:function——这是下一子步骤的关键信息。

5b — 阶段内审查环节（必须）。子技能输出后，先暂停并显示简短的内联提示（这不是带新横幅的完整检查点，而是阶段 5 内的一行审查提示）：

## Phase 5 — review the generated experiment before running

- File: `<path>`
- Wired to dataset: `<dataset_name>` (pulled at runtime via LLMObs.pull_dataset)
- Task function source: <line lifted from the sub-skill output — module:function, or "placeholder fallback">
- Evaluators: <2–3 evaluator names>

**Open the file and check three things before I run it:**
1. The wired `task_fn` (section 4) — confirm the sub-skill picked the right entry point. If it picked a helper or deprecated path, edit the import to point at the right function. If it fell back to a placeholder, replace it with a real call.
2. The placeholder evaluators (section 5) — these are starting points. If Phase 3 produced online evaluators via `--publish`, swap one of the placeholders for a `RemoteEvaluator(eval_name="...")`.
3. The `experiment.run(jobs=<N>)` parallelism (section 7) — defaults to 10; lower it if you're worried about rate limits.

Type **`run`** to execute the file as-is, **`edit`** to pause here so you can edit and re-run this skill, or **`stop`** to exit cleanly. State for Phase 4 and earlier is preserved.

等待用户回复。

• 如果回复为 run：继续执行 5c。
• 如果回复为 edit：告知用户文件位于 <path>，并且文件确认无误后，可以使用 --start-at experiment 重新调用此技能。正常结束本次运行。生成的文件路径会写入状态文件，因此 --start-at experiment 可以跳过代码生成并恢复运行（只需重新运行子步骤 5c）。
• 如果回复为 stop：输出停止摘要并结束。已完成阶段的状态（包括生成的实验文件）会保留在磁盘上。
• 其他任何回复：视为调整请求或问题。进行分析并回答，然后再次显示审查提示。

5c — 执行文件。

• 对于 --format py：通过 Bash 执行 python <generated_path>。将输出实时显示给用户。
• 对于 --format ipynb：告知用户生成的文件是一个 notebook，并询问要 (a) 通过 jupyter nbconvert --to notebook --execute --inplace <path> 执行（需要安装 jupyter），还是 (b) 转交给用户，由用户在 JupyterLab 中打开并手动运行各单元格。如果 jupyter 位于 PATH 中，默认选择 (a)；否则选择 (b)。
• 从运行的 stdout 中捕获打印出的 experiment.url——生成的文件总会以 print(experiment.url) 结尾。如果找不到，则在 stdout 中解析子串 https://app.datadoghq.com/llm/experiments/（同时考虑非默认的 DD_SITE 主机）。
• 如果运行失败：不要自动重试。显示完整的 traceback，用一行诊断指出失败类别（身份验证、缺少依赖项、找不到数据集、任务函数引发异常、评估器引发异常），并询问用户是否要修复后重新运行。

检查点 5

## Phase 5 complete — experiment generated and run

- File: `<path>`
- Experiment URL: <experiment.url>
- Records processed: <N>
- Duration: <wall-clock seconds>
- Task function: <module:function>
- Evaluator score summary (from stdout, if printed): <table or "open the UI">

Next up — Phase 6 will pull the experiment results back from Datadog and produce an analysis report (struggling metrics, qualitative examples, root-cause hypotheses).

Before I continue:
- Take a look at the experiment in the UI (link above). Do the per-record scores roughly match your expectations?
- Any specific question you want Phase 6 to focus on? (Optional — leaving it open runs an exploratory analysis.)

Type `continue` to proceed, `stop` to exit cleanly (state is saved), `redo` to re-run this phase, or give me adjustments.

等待确认。如果用户提供了关注问题，将其作为分析器的 question 参数传递到阶段 6。

阶段 6：分析实验

实体：实验 metric、分段比较、建议。

教学提示：

实验指标是什么：由某个评估器为每条记录生成的评分，并汇总为整个数据集的通过率／分数分布。Datadog Experiments UI 会将这些指标显示为列，并允许你按附加到每条记录的 metadata 字段进行切片。

建议是什么样的：分析器会根据表现不佳的指标以及失败记录中的模式，提出关于下一步修改内容的假设（系统提示词、检索、任务代码、数据集本身或评估器）。

为什么这个阶段很重要：这让整个流程形成闭环。你从查看生产环境行为开始，现在则能基于证据了解实验暴露了哪些差距，以及可以尝试什么。

操作：在 single-exploratory 中按照 agent-observability-experiment-analyzer 技能操作（如果用户在检查点 7 中提供了重点问题，则使用 single-Q&A）：

/agent-observability-experiment-analyzer <experiment_id_from_url> [<focus question if any>] --output agent

从阶段 5 中记录的 URL 提取 <experiment_id>（/llm/experiments/ 后面的 UUID）。

逐字复现分析器的完整报告。

最终总结

分析器报告之后，输出结束总结——它将替代每个阶段的检查点：

# Agent Observability Eval Pipeline complete

**ml_app**: `<ml_app>` | **Project**: `<project_name>` | **Timeframe**: <timeframe>

| Phase | Output |
|---|---|
| 1. Classify ml_app | <N> traces classified (<F> failures) |
| 2. Root cause analysis | <K> failure modes, <M> root causes |
| 3. Bootstrap evaluators | <J> evaluators (`<offline-evaluators | online-evaluators | data-only>`) → `<path>` (or "<N> drafts published to Datadog") |
| 4. Create + publish dataset | <K> records → `<dataset_path>`, published as `<dataset_name>` (v1) in project `<project_name>` |
| 5. Generate + run experiment | `<experiment_file_path>` → <experiment.url> (<N> records, <duration>s) |
| 6. Analyze experiment | <2–3 bullet headline findings from the analyzer> |

## What you learned

- The five core entities you touched: **ml_app**, **failure mode**, **evaluator**, **dataset**, **experiment**. Each has a dedicated docs page — see Datadog Documentation below.
- The loop you can now repeat: **edit dataset → re-run experiment → compare in the UI**. Pull-by-name + auto-versioning makes the loop cheap.
- The reusable artifacts you produced: an evaluator suite (Phase 3), a published dataset (Phase 4), and an experiment script (Phase 5). All three survive beyond this pipeline run.

## Recommended next steps

1. Open the experiment in the Datadog UI: <experiment.url>
2. Replace the placeholder evaluators in `<experiment_file_path>` with the ones bootstrapped in Phase 3 (swap the function refs / `RemoteEvaluator` names).
3. Re-run the experiment after every meaningful change to your task code. Datadog will keep the run history under the same project.
4. If you published draft evaluators via `--online-evaluators`, review and enable them in the UI (Agent Observability → Evaluations).

## Datadog Documentation

- Agent Observability overview: <https://docs.datadoghq.com/llm_observability/>
- Datasets: <https://docs.datadoghq.com/llm_observability/experiments/datasets_and_experiments/>
- Experiments: <https://docs.datadoghq.com/llm_observability/experiments/>
- Evaluations: <https://docs.datadoghq.com/llm_observability/evaluations/>
- Python SDK reference: <https://docs.datadoghq.com/llm_observability/instrumentation/sdk/>

---

提前停止处理

--stop-after <phase> 允许用户在完整的六阶段流程完成前正常退出。有效值对应阶段编号：

值	停止阶段	适用场景
classify	阶段 1	“我只想看看我的 ml_app 中发生了什么。”
rca	阶段 2	“我想了解故障模式——评估器我会自己编写。”
eval-bootstrap	阶段 3	**与经典的 agent-observability-eval-pipeline 行为一致。**适用于“我想要评估器，不要实验。”
dataset	阶段 4	“我想创建并发布数据集，但生成／运行／分析实验我会自己完成。”
experiment	阶段 5	“生成并运行实验；结果我会自己分析。”
analyze	阶段 6（默认）	完整流程。

当当前阶段与停止值匹配时，将该阶段底部的检查点替换为停止总结：

## Pipeline stopped — `--stop-after <phase>`

Completed phases: <list 1..stop>
Skipped: <list stop+1..6 with one-line descriptions>

Artifacts produced: <list with paths / URLs>

Re-invoke with a later `--stop-after` (or no flag for the full run) when you're ready to continue. State from completed phases is idempotent — re-running them will just re-derive the same outputs.

这样，--stop-after eval-bootstrap 就能直接替代旧版 agent-observability-eval-pipeline 行为，同时保留编排器的教学提示。

---

状态持久化与入口／退出

该流程会将每个阶段的主要输出持久化到 <output-dir>/state/，以便后续调用可以通过 --start-at <phase> 从流程中途恢复，而不必每次都从阶段 1 开始。

状态文件约定

每个阶段成功完成后（即用户在检查点后输入 continue，或者 --stop-after 匹配时，在停止摘要之前），将该阶段的输出写入 <output-dir>/state/0N-<name>.{md,json}。每个阶段的架构固定如下：

阶段	状态文件	架构
1 分类	state/01-classification.md	完整的 # Session Classification Summary 区块以及所有单元精简区块，原样摘自 agent-observability-session-classify。Markdown。
2 根因分析	state/02-rca-report.md	来自 agent-observability-trace-rca 的完整 Phase 6 RCA 报告，原样保留。Markdown。
3 评估器引导	state/03-evaluators.json	{"mode": "offline_evaluators|online_evaluators|data_only_dataset|data_only_analysis", "output_path": "<path>", "evaluator_names": [...], "ml_app": "<ml_app>", "generated_at": "<ISO 8601>"}。实际评估器代码/JSON/数据集保留在子技能写入的位置。data_only_dataset 模式会生成 DatasetRecordRaw[] JSON，供 Phase 4 直接使用。
4 数据集	state/04-published-dataset.json	{"dataset_file": "<path to local DatasetRecordRaw[] JSON>", "dataset_name": "<published name>", "project_name": "<name>", "version": <int>, "url": "<datadog url>", "record_count": <int>, "skipped_count": <int>, "pii_redactions": <int>, "tag_normalizations": <int>, "published_at": "<ISO 8601>"} — 合并了此前的两个状态文件（04-dataset.json 和 05-published-dataset.json），因为 Phase 4 现在会在一个步骤中创建并发布数据集。
5 实验	state/05-experiment-run.json	{"experiment_file": "<path>", "format": "py|ipynb", "dataset_name": "<name>", "task_source": "<module:function>|placeholder", "purpose": "<text>", "experiment_id": "<uuid>", "experiment_url": "<datadog url>", "records_processed": <int>, "duration_seconds": <float>, "generated_at": "<ISO 8601>", "ran_at": "<ISO 8601>"} — 合并了此前的两个状态文件（06-experiment.json 和 07-experiment-run.json），因为 Phase 5 现在会在一个步骤中生成并运行实验。如果用户在阶段内审查节点（5b）选择 edit 后暂停，则只会填入代码生成字段；使用 --start-at experiment 重新进入时，会从此处读取文件路径并从 5c 恢复。
6 分析	state/06-analysis.md	来自 agent-observability-experiment-analyzer 的完整分析器报告。Markdown。

应在 Precheck 开始时通过 mkdir -p 创建 <output-dir>/state/（与现有的 <output-dir> 创建操作一起）。绝不在此目录之外写入状态文件。

--start-at 解析

运行开始时，在 Precheck 之后，根据 --start-at 分支处理：

1. 如果未设置 --start-at，或其值为 classify，则正常进入 Phase 1。

2. 否则，对于开始阶段之前的每个阶段，加载对应的状态文件。如果传入了覆盖标志（--classification-summary、--rca-report、--dataset-file、--dataset-name、--experiment-file、--experiment-id、--experiment-url），则优先使用覆盖标志，而非状态文件。

3. 如果所需的状态文件缺失，且未提供覆盖标志，则立即失败并显示清晰的错误信息：

   "无法执行 --start-at <phase> — Phase 的状态文件 <output-dir>/state/0(N-1)-<name>.{md,json} 缺失，且未提供 --<prior-phase>-override <path> 标志。请从更早的阶段重新运行，或明确传入覆盖标志。"

4. 对于每个已加载的状态文件或覆盖内容，在 Precheck 输出中打印一行“已加载先前状态：，来源：”，以便用户查看哪些内容会被复用。

5. 直接跳转到开始阶段。第一个实际运行的阶段会打印完整横幅；较早的阶段则在 Precheck 中显示一行提示。

如果启用了 --start-at，Precheck 输出的末尾会额外显示一行：

- Resumed from: --start-at <phase> (loaded state for phases 1..N-1)

可在任意检查点中途退出

每个检查点都接受以下输入（不区分大小写，允许前后有空格）：

用户输入	行为
continue、c、go、yes、y、next，或不输入任何文本直接按 <Enter>	进入下一阶段。
stop、exit、done、quit、q、cancel	在此处输出停止摘要并结束运行。效果等同于从一开始就设置了 --stop-after <current-phase>。已完成阶段的状态会保存在磁盘上，因此用户稍后可以使用 --start-at <next-phase> 继续。
redo（可选地附上调整说明，例如 redo with --trace-limit 50）	仅重新运行当前阶段。不要重新运行之前的阶段——它们在磁盘上的状态保持不变。应用用户附加的任何调整说明。
back（可选地附上阶段名称）	回退一个阶段（或回退到指定阶段），并从那里重新运行。丢弃磁盘上受影响阶段的状态，以便重新生成。
其他任何输入	将其视为调整意见或问题，并结合上下文进行判断；如果用户是在询问澄清问题，则回答并重新显示检查点提示。如果用户要求修改某个阶段，则应用修改并重新运行该阶段。

阶段模板中的“输入 'continue' 以继续”一行应更新为：

输入 continue 以继续，输入 stop 以正常退出（状态已保存——稍后可使用 --start-at <next-phase> 恢复），输入 redo 以重新运行此阶段，或告诉我需要调整的内容。

实际重新进入示例

# First-time, full run end-to-end
/agent-observability-eval-pipeline lux --project-name lux

# (user typed 'stop' at Checkpoint 4)
# Later, pick up where they left off:
/agent-observability-eval-pipeline lux --project-name lux --start-at experiment

# Already have a dataset published; want to scaffold + run an experiment around it
/agent-observability-eval-pipeline lux --project-name lux --start-at experiment --dataset-name lux_seed_v3

# Re-analyze a previous experiment without re-running it
/agent-observability-eval-pipeline lux --start-at analyze --experiment-id 8a3f9c2b-...

# Slice — just classify + RCA, leave the rest for later
/agent-observability-eval-pipeline lux --stop-after rca

# Continue from the slice above without redoing classify
/agent-observability-eval-pipeline lux --start-at eval-bootstrap --stop-after eval-bootstrap

--start-at 和 --stop-after 可以自由组合。在内部，--start-at X --stop-after Y 只运行从阶段 X 到阶段 Y（含）的阶段（如果 Y < X，则运行无效——在参数解析时直接报错）。

---

编排规则

• 即使重新调用，也始终运行预检。 预检开销很小，还能在你浪费子技能调用之前发现过时的 ml_app 参数、已过期的身份验证令牌，或 --project-name 中的拼写错误。
• 始终输出预检区块。 尽管它不是一个“阶段”，用户已经习惯将它作为第一项输出查看。
• 阶段之间绝不自动推进。 每个检查点都必须等待用户明确输入。认可的检查点指令包括 continue / stop / redo / back，以及自由文本调整——完整表格请参见“状态持久化与进入/退出 → 在任意检查点中途退出”。
• 显示检查点之前，先持久化阶段输出。 每个阶段都会在呈现检查点提示之前，将主要输出写入 <output-dir>/state/0N-<name>.{md,json}。这样，在任何时候输入 stop，磁盘上都会留下可供重新进入的产物——用户之后可以使用 --start-at <next-phase> 恢复，技能会加载先前状态，而无需重新运行任何内容。
• 严格遵守 --start-at。 设置 --start-at <phase> 时，加载所有先前阶段的状态文件（或提供的覆盖标志），并在预检中为每个已加载阶段打印一行确认，然后从指定阶段开始。如果缺少必需的状态文件，且未提供覆盖标志，则立即失败——不要悄悄重新运行缺失的阶段。
• 绝不截断子技能输出。 用户是来了解子技能作用的；如果你总结其输出，就违背了教学目的。原样完整复现。后续阶段也依赖上下文中的完整文本（阶段 2 会检测阶段 1 的分类摘要；阶段 3 会检测阶段 2 的失败分类）。
• 阶段框架不可变。 横幅（“你现在位于阶段 N，共 6 个阶段……”）、实体区块、操作标签和检查点标题必须在每个阶段中保持完全一致。内部内容可以不同，但框架必须不变。这就是技能所承诺的确定性。
• 仅在阶段 4 和阶段 5 执行操作。 其他阶段都不会在用户的机器上运行代码。阶段 4 运行发布脚本（将数据集写入 Datadog）；阶段 5 运行生成的实验文件（针对数据集调用服务提供方 API）。其他所有阶段均为只读操作，或只会向 --output-dir 写入生成的文件。如果子技能输出建议用户自行运行某项操作，请将其交由用户处理——不要悄悄代为执行。
• 阶段 5 必须包含阶段内审核环节。 在子步骤 5a（代码生成）和 5c（执行）之间，暂停并提示用户进行阶段内审核。等待用户输入 run、edit 或 stop。代码生成后绝不自动运行。
• 整次运行只使用一个后端。 在启动时检测后端，并将其传递给所有子技能调用。运行过程中不要重新检测。
• --project-name 一经选择便保持不变。 用户在预检中选择的名称会原样传递到阶段 4、阶段 5 和最终摘要。如果用户在检查点 4 更改了决定，只用新名称重新运行阶段 4——不要悄悄改写先前的输出。
• 阶段重新进入：如果用户输入类似“用 --trace-limit 30 重新运行阶段 4”，则只重新运行该阶段（并明确说明——“正在使用新的跟踪限制重新运行阶段 4。阶段 1–3 的输出保持不变。”）。完成后，像全新运行一样继续进入阶段 5。

---

此技能不做什么

此列表旨在帮助审阅者发现范围蔓延：

• 不会为你的应用添加埋点。 假设用户已将 ml_app 追踪数据发送到 Datadog。如果预检查发现零条追踪数据，此技能会停止并引导用户查看埋点文档，而不会尝试初始化埋点。
• 不会推送代码或提交任何内容。 所有生成的文件都会写入 <output-dir>；版本控制由用户负责。
• 不会在没有明确检查点或审阅确认的情况下运行任何阶段的代码。 阶段 4 会自动从数据集创建子步骤进入发布子步骤（两者之间没有可由用户编辑的环节），但阶段 5 会在代码生成和运行之间的阶段内审阅环节暂停——用户输入 run 后才能继续。
• 不会深入修改你的应用。 阶段 5 的实验文件会 导入 你的任务函数，而不会重构它。如果你想在不编辑应用的情况下使用不同的提示词／模型变体，请将调用内联到生成文件的 task_fn 中。
• 不会自动创建 .env 文件。 凭据文件只会被查找，不会被生成——磁盘上的密钥由用户自行决定。

---

工具参考

此技能本身几乎不会直接调用工具——唯一的直接调用是：

1. 预检查 search_llmobs_spans（用于确认 ml_app 有追踪数据）。
2. 阶段 4（运行发布脚本）和阶段 5（运行生成的实验）使用 Bash。
3. 阶段 4 的发布过程不会使用 Write——发布辅助脚本位于 scripts/publish_dataset.py，与此 SKILL.md 放在一起；编排器通过路径和 CLI 参数调用它。此技能不会在运行时生成该脚本。

其他操作都通过子技能完成，这些子技能各自包含 MCP 到 pup 的映射：

子技能	调用时机	工具参考所在位置
agent-observability-session-classify	阶段 1	agent-observability/agent-observability-session-classify/SKILL.md（工具参考附录）
agent-observability-trace-rca	阶段 2	agent-observability/agent-observability-trace-rca/SKILL.md（工具参考附录）
agent-observability-eval-bootstrap（offline-evaluators / online-evaluators / data-only）	阶段 3	agent-observability/agent-observability-eval-bootstrap/SKILL.md（工具参考附录）
agent-observability-eval-bootstrap（--emit-dataset 模式）	阶段 4（子步骤 4a）	agent-observability/agent-observability-eval-bootstrap/SKILL.md（阶段 3D + 工具参考附录）
agent-observability-experiment-bootstrap	阶段 5（子步骤 5a）	agent-observability/agent-observability-experiment-bootstrap/SKILL.md
agent-observability-experiment-analyzer	阶段 6	agent-observability/agent-observability-experiment-analyzer/SKILL.md（工具参考附录）

预检查 search_llmobs_spans ↔ pup

MCP 工具	pup 命令
search_llmobs_spans(query="@ml_app:\"<ml_app>\"", root_spans_only=true, limit=1, from="<timeframe>")	pup llm-obs spans search --query "@ml_app:\"<ml_app>\"" --root-spans-only --limit 1 --from <stripped-timeframe> --summary（根据上方 pup 调用规则，从 timeframe 中去掉 now- 前缀）。

• MCP 结果解析安全性：在编写任何会遍历或访问 MCP 工具结果字段的脚本（Python、jq 等）之前，先检查原始结构——查看 type(result)、顶层键，以及载荷是否嵌套在内容块中（例如 [{'type': 'text', 'text': '<json>'}]）。如有需要，提取内部载荷并使用 json.loads() 解析。切勿假设 MCP 结果是未经包装的字典或列表。