wehub/skillhub-048-eval-driven-dev

Fork 0

Files

T

wehub-skill-sync 4ac4773608 chore: import zh skill eval-driven-dev

2026-07-13 21:35:56 +08:00

15 KiB

Raw Permalink Blame History

步骤 6：分析结果

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

结果目录结构

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

{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" 的条目，你必须对它们进行评分：

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

修改前（待定）：

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

修改后（已评分）：

{
  "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.0）？是否存在不稳定的评估器（没有代码变更但方差很大）？标准是否过于模糊或过于严格？
应用质量——基于评估结果，应用的优势和劣势是什么？它在哪些方面产生了高质量的输出？它在哪些方面失败了？

对于每个假设：

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

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

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

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

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

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

编写原则：

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

内容：

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

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

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

模板：

# 数据集分析 — 摘要

**数据集**：<名称> | **条目数**：<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 行，添加指令：'……'"。越具体，越可操作。
不包含推测性改进项。 每个改进项必须有经过验证的证据。如果一个改进项基于未验证的假设，要么先验证它，要么排除它。

结构：

# 行动计划（详细）

## 摘要

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

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

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

## 优先级 2：...

...

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

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

模板：

# 行动计划 — 摘要

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

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

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

摘要最多约 30 行。

优先级排序标准：

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

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

流程总结

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

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

最终验证

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

示例形式：

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

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

15 KiB Raw Permalink Blame History Unescape Escape