# 步骤 6：分析结果

**为什么需要这一步**：`pixie test` 生成了原始分数。现在你要分析这些结果，理解它们意味着什么——完成待定的评估、识别模式、验证假设、并生成可执行的改进方案。分析按三个相互递进的阶段进行：条目级 → 数据集级 → 行动计划。

---

## 结果目录结构

执行 `pixie test` 后，结果目录结构如下：

```text
{PIXIE_ROOT}/results/<test_id>/
  meta.json
  dataset-{idx}/
    metadata.json
    entry-{idx}/
      config.json              # 评估器、描述、期望
      eval-input.jsonl         # 输入给评估器的数据
      eval-output.jsonl        # 从应用中捕获的输出数据
      evaluations.jsonl        # 已评分 + 待定的评估
      trace.jsonl              # LLM 调用轨迹
```

读取 `meta.json` 来找到 `<test_id>`。你分析所需的所有数据都在这个目录中。

---

## 硬性完成门槛

你是步骤 6 的评分者。**待定评估不能移交给用户处理，Web UI 也不能替代评分。** 你可以使用 Web UI 浏览轨迹和输出，但完成的标准是在磁盘上写入文件。

步骤 6 只有在以下条件全部满足时才视为完成：

- 每个 `evaluations.jsonl` 文件中所有 `"status": "pending"` 的条目都已替换为包含 `score` 和 `reasoning` 的已评分条目。
- 每个数据集目录都包含 `analysis.md` 和 `analysis-summary.md`。
- 测试运行根目录包含 `action-plan.md` 和 `action-plan-summary.md`。
- 本技能 `resources/` 目录下的验证脚本对目标结果目录通过验证。

**禁止的捷径**：

- 保留任何 `"status": "pending"` 的条目
- 让用户在 Web UI 中审查待定的评估
- 在顶层写一个替代文件如 `pixie_qa/06-analysis.md`
- 写"可能通过"或"可能失败"这类表述，而不对评估进行评分并更新 `evaluations.jsonl`

如果你做了上述任何一条，步骤 6 都未完成。

## 迭代规则

如果你在多个修复/测试周期中迭代，每次成功的 `pixie test` 运行都会创建一个新的 `pixie_qa/results/<test_id>` 目录和新的步骤 6 义务。一旦该目录存在，它就成为当前周期的分析目标。

在修改应用代码、提示词、数据集、评估器或重新运行 `pixie test` 之前，先完成该结果目录的步骤 6。不要跳过前面的周期，只分析最后一次运行。

**额外的禁止捷径**：

- 不要创建一个更新的 `pixie_qa/results/<test_id>` 而将同一任务中较旧的目录留下，不生成步骤 6 产物。

---

## 编写原则

你生成的每个分析**详细**产物必须遵循以下原则：

- **数据驱动**：每一个观点或陈述必须有评估运行中的具体数据作为支撑。引用分数、引用条目索引、引用特定的评估输入/输出内容。不要空泛地描述。写没有依据的东西还不如不写。
- **证据优先**：在得出结论之前先呈现原始数据和证据。读者（另一个编码 agent）应能根据你引用的证据独立验证你的结论。
- **可追溯**：对于每个结论，提供完整的链条：数据来源 → 观察 → 推理 → 结论。另一个 agent 应能沿这条链条反向追溯，以验证或质疑任何主张。
- **不推销**：不要鼓吹、美化或使用价值判断词汇（"优秀的"、"健壮的"、"令人印象深刻的"、"设计良好的"）。陈述数据展示了什么以及它暗示了哪些行动。让读者自己判断质量。
- **面向行动**：每一项分析都应服务于最终目标——对评估管线或应用做出具体的改进。不要写那些不导向任何行动的观察。

每个持久化的分析**摘要**产物必须遵循以下原则：

- **简洁**：人类读者应能在不到 2 分钟内理解任一产物的关键发现和行动项。
- **结论先行**：先告诉读者需要知道的内容（结果、发现、行动），而不是方法论或背景。
- **通俗语言**：避免行话。非技术利益相关者应能读懂摘要。
- **一致**：摘要的结论必须与详细版本的证据一致。绝不在摘要中添加详细版本中没有支撑的主张。

### 双变体模式

本步骤中的每个持久化分析产物都有两个文件：

| 产物           | 详细文件（供 agent 使用）    | 摘要文件（供人类阅读）            |
| -------------- | ---------------------------- | --------------------------------- |
| 数据集分析     | `dataset-{idx}/analysis.md`  | `dataset-{idx}/analysis-summary.md` |
| 行动计划       | `action-plan.md`             | `action-plan-summary.md`            |

**始终先写详细版本**，然后从中推导出摘要。摘要是详细版本内容的严格子集——它不应包含详细版本中没有的主张或结论。

---

## 阶段 1：条目级评分

逐个处理每个数据集条目。对于每个 `dataset-{idx}/entry-{idx}/`：

### 1a. 读取条目数据

读取该条目的以下文件：

- `config.json` — 配置了哪些评估器、描述、期望
- `eval-input.jsonl` — 输入给应用/评估器的数据
- `eval-output.jsonl` — 应用产生的输出
- `evaluations.jsonl` — 当前的评估结果（已评分和待定）
- `trace.jsonl` — 应用进行的 LLM 调用（如果有）

### 1b. 完成待定评估

如果 `evaluations.jsonl` 包含 `"status": "pending"` 的条目，你必须对它们进行评分：

1. 读取待定评估的 `criteria` 字段
2. 将评分标准应用于该条目的评估输入、评估输出和轨迹数据
3. 给出 **score**，范围在 0.0 到 1.0 之间：
   - `1.0` — 完全满足标准
   - `0.5`–`0.9` — 部分满足标准（说明缺失了什么）
   - `0.0`–`0.4` — 不满足标准
4. 写出 **reasoning** 字符串（1–3 句话，引用输出或轨迹中的具体证据）
5. 将 `evaluations.jsonl` 中的待定条目替换为评分结果。**不要追加第二行而保留待定行。直接覆盖待定行本身。**

**修改前**（待定）：

```json
{
  "evaluator": "ResponseQuality",
  "status": "pending",
  "criteria": "回复应该……"
}
```

**修改后**（已评分）：

```json
{
  "evaluator": "ResponseQuality",
  "score": 0.85,
  "reasoning": "回复解决了主要问题，但省略了……"
}
```

**评分准则**：

- 基于证据——每个分数必须引用具体的输出或轨迹内容
- 严格按照评分标准字面含义执行——不要扩展或重新解读超出已写范围的内容
- 考虑轨迹——区分应用逻辑问题和 LLM 质量问题
- 校准分数——保留 1.0 给那些真正完全满足标准的输出
- 不惩罚 LLM 的非确定性——正确答案的不同措辞不是失败
- 不推给用户——如果证据足以写出"可能通过"，那就足以给出分数并更新 `evaluations.jsonl`

### 1c. 不持久化条目级分析文件

在这个精简工作流中，**不要写 `entry-{idx}/analysis.md` 或 `entry-{idx}/analysis-summary.md`**。阶段 1 仅用于读取证据并将每个待定评估转换为 `evaluations.jsonl` 中的评分行。

你可以在推理过程中做临时的草稿笔记，但它们不是交付物。仅持久化以下内容：

- 每个条目目录中更新后的 `evaluations.jsonl`
- 阶段 2 中的数据集级分析文件
- 阶段 3 中的运行级行动计划文件

---

## 阶段 2：数据集级分析

在一个数据集的所有条目分析完成后，生成数据集级分析。将 `analysis.md` 写入数据集目录（`dataset-{idx}/analysis.md`）。

### 2a. 聚合数据

汇总数据集中所有条目的情况：

- 通过/失败计数和总体通过率
- 按评估器统计（通过率、最低/最高/平均分数）
- 哪些条目在哪些评估器上失败（失败聚类）

### 2b. 形成并验证假设

从以下三个维度提出**恰好 3 个高置信度假设**：

1. **测试用例质量**——测试用例集是否充分且高效地验证了应用的能力？是否覆盖了重要的失败模式？是否存在盲点？

2. **评估标准/评估器质量**——评估器是否有足够的粒度来捕获真正的问题？是否存在橡皮图章式评估器（全部 1.0）？是否存在不稳定的评估器（没有代码变更但方差很大）？标准是否过于模糊或过于严格？

3. **应用质量**——基于评估结果，应用的优势和劣势是什么？它在哪些方面产生了高质量的输出？它在哪些方面失败了？

对于每个假设：

- **清晰陈述假设**，一句话说明
- **引用证据**——条目索引、评估器名称、分数、推理引用、轨迹数据
- **验证或否定**——查看实际的评估输入/输出数据和代码来确认或反驳
- **结论**——这个假设暗示了哪些行动？

即使数据有限，也总能产生 3 个假设。如果评估数据不能对应用质量给出确定性的结论，这本身就是一个关于测试用例或评估器缺口的信号。

### 2c. 编写数据集分析（两个文件）

为数据集分析生成**两个文件**。先写详细版本，然后推导出摘要。

#### 详细版本：`dataset-{idx}/analysis.md`

此文件供 **agent 使用**——提供完整的数据聚合、带有证据链的假设形成、以及经过验证的结论，编码 agent 可以直接据此采取行动。

**编写原则：**

- **在解释数据之前先展示所有数据。** 先呈现原始聚合数据（通过/失败、按评估器统计、失败聚类），然后再提出任何假设。数据应能独立地说明问题。
- **对于每个假设，按以下顺序呈现：数据 → 推理 → 结论。** 读者应能逐步跟随你的逻辑，并独立得出相同结论。
- **直接交叉引用原始条目证据。** 引用证据时，引用具体的条目索引及其底层文件/数据点（例如：`entry-3/evaluations.jsonl`、`entry-3/eval-output.jsonl` 或 `entry-3/trace.jsonl`）。
- **区分相关性与因果性。** 如果两个条目在同一个评估器上失败，这是一个模式。但根本原因可能不同——通过检查实际的输出来验证，不要做假设。
- **如果不确定，不要不标明。** 如果结论不确定，请说"假设（未验证）：……"并解释需要哪些额外数据来确认或反驳。

**内容：**

1. **概述**——数据集名称、条目数量、总体通过率
2. **原始聚合数据**
   - 按评估器统计表（通过率、分数范围、均值、标准差）
   - 失败矩阵：条目 × 评估器，显示分数，突出显示失败
   - 失败聚类：按共同失败的评估器分组的条目
3. **假设 1：测试用例**——假设陈述、带有条目/评估器引用的证据、采取的验证步骤、带有具体行动的结论
4. **假设 2：评估器**——相同结构
5. **假设 3：应用**——相同结构
6. **未解决的问题**——数据无法给出确定性结论的问题，附上哪些额外数据会有帮助的建议

#### 摘要版本：`dataset-{idx}/analysis-summary.md`

此文件供**人工审查**——数据集结果、关键发现和推荐行动的可扫描概览。

**模板：**

```markdown
# 数据集分析 — 摘要

**数据集**：<名称> | **条目数**：<N> | **通过率**：<X/N (Y%)>

## 结果概览

| 评估器 | 通过率 | 平均分 | 备注                  |
| ------ | ------ | ------ | --------------------- |
| ...    | ...    | ...    | <一行，如值得注意>    |

## 关键发现

1. <发现>：<1–2 句话说明结论及其影响>
2. ...
3. ...

## 推荐行动（按优先级排序）

1. <行动>：<做什么以及预期影响，1–2 句话>
2. ...
3. ...
```

摘要最多约 40 行。

---

## 阶段 3：行动计划（两个文件）

在所有数据集分析完成后，生成行动计划。在测试运行根目录写入**两个文件**。先写详细版本，然后推导出摘要。

### 详细版本：`{PIXIE_ROOT}/results/<test_id>/action-plan.md`

此文件供 **agent 使用**——提供具体的、可实施的改进项，附带完整的证据链条，使编码 agent 可以拿起任何一个改进项直接执行，无需额外收集上下文。

**编写原则：**

- **每个改进项必须自包含。** 只读一个优先级项的编码 agent 应拥有足够的上下文（证据引用、文件路径、预期变更）来实施它。
- **每项都要追溯到证据。** 每个优先级必须引用：来自哪个数据集分析的哪个假设、哪些条目/评估器提供了证据、以及具体数据展示的内容。
- **关于"如何做"要具体。** 不要只说"改进提示词"——要说"在 `scrapegraphai/prompts/generate_answer.py` 第 45 行，添加指令：'……'"。越具体，越可操作。
- **不包含推测性改进项。** 每个改进项必须有经过验证的证据。如果一个改进项基于未验证的假设，要么先验证它，要么排除它。

**结构：**

```markdown
# 行动计划（详细）

## 摘要

- X 个数据集已分析，Y 个总条目，Z% 总体通过率
- [1–2 句话的高层评估]

## 优先级 1：[最 impactful 的改进]

- **内容**：[具体要做的变更]
- **原因**：[来自哪个数据集分析的哪个假设，附上条目/评估器引用]
- **证据**：[支持此改进的具体分数、输出摘录、轨迹数据]
- **预期影响**：[哪些条目/评估器将得到改进，以及预测的分数变化]
- **如何实现**：[具体的实施步骤，附上文件路径和行号]
- **验证方式**：[如何验证修复是否生效——重新运行哪些条目，预期获得哪些分数]

## 优先级 2：...

...
```

### 摘要版本：`{PIXIE_ROOT}/results/<test_id>/action-plan-summary.md`

此文件供**人工审查**——一份按优先级排序的改进清单，人类能在 2 分钟内理解并批准。

**模板：**

```markdown
# 行动计划 — 摘要

**总体情况**：<X 个条目，Y% 通过率。1 句话评估。>

## 行动项（按优先级排序）

1. **<行动标题>**：<要更改什么以及原因，2–3 句话。预期影响。>
2. **<行动标题>**：<要更改什么以及原因，2–3 句话。预期影响。>
3. ...
```

摘要最多约 30 行。

**优先级排序标准**：

- 系统性问题（影响多个条目/数据集）优先于孤立问题
- 有清晰、经过验证的证据的问题优先于推测性问题
- 应用质量差距优先于评估器优化，评估器优化优先于测试用例补充
- 快速修复优先于大规模重构

行动计划应有 3–5 个改进项。每项必须追溯到阶段 2 中经过验证的假设。不要包含推测性或缺乏证据的改进项。

---

## 流程总结

1. **阶段 1**（每个条目）：读取数据 → 对待定评估进行评分 → 更新 `evaluations.jsonl`
2. **阶段 2**（每个数据集）：聚合数据 → 形成 3 个假设 → 验证 → 写入 `dataset-{idx}/analysis.md` + `dataset-{idx}/analysis-summary.md`
3. **阶段 3**（每个测试运行）：综合 → 排序优先级 → 写入 `action-plan.md` + `action-plan-summary.md`

数据集内的条目可以并发处理（如果可用则使用子 agent）。阶段按顺序处理——阶段 2 依赖于阶段 1 的输出，阶段 3 依赖于阶段 2 的输出。

---

## 最终验证

在结束你的回合之前，针对你分析的具体测试运行目录，运行本技能 `resources/` 目录中与 `setup.sh` 一同提供的步骤 6 验证脚本。

示例形式：

```bash
python /path/to/eval-driven-dev/resources/verify_step6_completion.py pixie_qa/results/<test_id>
```

如果验证器报告任何错误，继续工作。在验证器通过之前，步骤 6 不算完成。