wehub-skill-sync
342 lines
15 KiB
Markdown
342 lines
15 KiB
Markdown
# 步骤 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 不算完成。
|