eval-driven-dev

面向 Python 大模型应用的评估驱动开发

你正在构建一条自动化评估流水线，用于对基于 Python 的 AI 应用进行端到端测试——以真实用户的方式运行它，使用真实输入——然后使用评估器对输出打分，并通过 pixie test 生成通过/失败结果。

你测试的是应用本身——它的请求处理、上下文组装（如何收集数据、构建提示词、管理对话状态）、路由和响应格式化。该应用使用大模型，这使输出具有非确定性——这就是为什么你使用评估器（LLM-as-judge、相似度分数）而不是 assertEqual——但被测对象是应用的代码，而不是大模型。

在评估过程中，应用自身的代码会真实运行——路由、提示词组装、大模型调用、响应格式化——没有任何内容被 mock 或 stub。但应用从外部来源（数据库、缓存、第三方 API、语音流）读取的数据会通过 instrumentations 被替换为测试指定的值。这意味着每个测试用例都能精确控制应用看到的数据，同时仍然执行完整的应用代码路径。

规则：应用的 LLM 调用必须发往真实的 LLM。 不要用虚假实现替换、mock、stub 或拦截 LLM。大模型是核心的价值创造组件——替换它会使评估变成同义反复（你同时控制输入和输出，因此分数毫无意义）。如果项目的测试套件包含 LLM mocking 模式，那些是用于项目自身单元测试的——不要将它们用于评估 Runnable。

交付物是一次成功运行的 pixie test，并带有真实分数——不是计划，不只是 instrumentation，也不只是数据集。

本技能的重点是实际去做，而不是描述它。阅读代码、编辑文件、运行命令、产出一条可运行的流水线。

---

开始之前

首先，激活虚拟环境。确定项目的正确虚拟环境并激活它。虚拟环境激活后，运行技能资源中包含的 setup.sh。 该脚本会将 eval-driven-dev 技能和 pixie-qa python 包更新到最新版本，如果尚未初始化则初始化 pixie 工作目录，并在后台启动一个 Web 服务器以向用户展示更新。

安装错误处理——哪些可以跳过，哪些必须成功：

• 技能更新失败 → 可以继续。现有的技能版本已足够。
• pixie-qa 升级失败但已安装 → 可以继续使用现有版本。
• pixie-qa 未安装且安装失败 → 停止。 向用户寻求帮助。没有 pixie 包，工作流无法继续。
• pixie init 失败 → 停止。 向用户寻求帮助。
• pixie start（Web 服务器）失败 → 停止。 向用户寻求帮助。检查 pixie 根目录下的 server.log 以进行诊断。常见原因：端口冲突、缺少依赖、环境缓慢。没有 Web 服务器就不要继续——用户需要它来查看评估结果。

---

工作流

直接按顺序完成步骤 1–6，中途不要停下。不要在中间步骤向用户请求确认——自行验证每一步并继续。

工作方式——在做任何其他事情之前先阅读以下内容：

• 一次只做一个步骤。 只阅读当前步骤的说明。在处理步骤 1 时，不要阅读步骤 2–6。
• 仅在步骤要求时才阅读参考文件。 每个步骤都会指定一个具体的参考文件。到达该步骤时再阅读——不要提前阅读。
• 立即创建产物。 在阅读某个子步骤的代码后，先写出该子步骤的输出文件，再继续下一步。不要在写出任何内容之前，跨多个子步骤累积理解。
• 验证，然后继续。 每个步骤都有一个检查点。验证它，然后继续下一步。在验证当前步骤时，不要规划后续步骤。

何时停下并寻求帮助：

有些阻碍无法也不应被绕过。当你遇到以下任一情况时，立即停下并向用户寻求帮助——不要尝试变通方案：

• 应用因缺少环境变量或配置而无法运行：应用需要未设置且无法推断的环境变量或配置。不要通过 mock、伪造或替换应用组件来绕过此问题——评估必须运行真实的生产代码。请用户修复环境设置。
• 表明项目已损坏的应用导入失败：如果应用的核心模块因缺少系统依赖项或不兼容的 Python 版本而无法导入（不仅仅是缺少你可以安装的 pip 包），请用户修复项目设置。
• 入口点不明确：如果应用有多个同样合理的入口点，且项目分析未能说明哪一个最重要，请询问用户应以哪个为目标。

你应当自行解决的阻碍（不要询问）：缺少 Python 包（安装它们）、缺少 pixie 包（安装它）、端口冲突（选择一个不同的端口）、文件权限问题（修复它们）。

按顺序运行步骤 1–6。 如果用户的提示词明确表明前面的步骤已经完成（例如“运行现有测试”、“重新运行评估”），则跳到相应的步骤。如有疑问，从步骤 1 开始。

---

步骤 1：理解应用并定义评估标准

首先，检查用户的提示词中是否有特定要求。 在阅读应用代码之前，先检查用户的要求：

• 引用的文档或规范：提示词是否提到了要遵循的文件（例如“遵循 EVAL_SPEC.md 中的规范”、“使用 REQUIREMENTS.md 中的方法”）？如果是，先阅读该文件——它可能指定了数据集、评估维度、通过标准或方法，这些将覆盖你的默认设置。
• 指定的数据集或数据源：提示词是否引用了特定的数据文件（例如“使用 eval_inputs/research_questions.json 中的问题”、“使用 call_scenarios.json 中的场景”）？如果是，阅读那些文件——你必须将它们作为评估数据集的基础，而不是编造通用的替代方案。
• 指定的评估维度：提示词是否列出了要评估的具体质量方面（例如“评估事实性、完整性和偏见”、“测试身份验证和工具调用的正确性”）？如果是，每个指定的维度都必须在你的测试文件中有一个对应的评估器。

如果提示词指定了上述任何内容，它们优先。在继续之前阅读并纳入它们。

步骤 1 有三个子步骤。每个子步骤读取自己的参考文件并生成自己的输出文件。在开始下一个子步骤之前，完整完成每个子步骤。

子步骤 1a：项目分析

参考：立即阅读 references/1-a-project-analysis.md。

在查看代码结构或入口点之前，先理解这个软件在现实世界中做什么——它的用途、它的用户、真实输入的复杂度，以及它在哪些地方会失败。这种理解会驱动后续每一个决策：哪些入口点最重要、要定义哪些评估标准、使用哪些 trace 输入，以及创建哪些数据集条目。在继续之前，先写好详细的上下文文件。注意：项目可能包含 tests/、fixtures/、examples/、mock 服务以及文档——这些是项目自身的开发基础设施，不是你的评估流水线的数据源。在获取 trace 输入和数据集内容时忽略它们。

检查点：pixie_qa/00-project-analysis.md 已写入——涵盖该软件做什么、目标用户、能力清单（如果项目具备能力，至少 3 项）、真实输入特征，以及难点 / 失败模式（至少 2 项）。

子步骤 1b：入口点与执行流程

参考：立即阅读 references/1-b-entry-point.md。

阅读源代码，理解应用如何启动，以及真实用户如何调用它。使用 pixie_qa/00-project-analysis.md 中的能力清单来确定入口点的优先级——重点放在能覆盖最有价值能力的入口点上，而不只是第一个找到的入口点。在继续之前，先写好详细的上下文文件。

检查点：pixie_qa/01-entry-point.md 已写入——涵盖入口点、执行流程、面向用户的界面，以及环境要求。

子步骤 1c：评估标准

参考：立即阅读 references/1-c-eval-criteria.md。

定义应用的用例和评估标准。从 pixie_qa/00-project-analysis.md 中的能力清单推导用例。从难点 / 失败模式推导评估标准——而不是从通用的质量维度。用例驱动数据集创建（第 4 步）；评估标准驱动评估器选择（第 3 步）。在继续之前，先写好详细的上下文文件。

检查点：pixie_qa/02-eval-criteria.md 已写入——涵盖用例、评估标准及其适用范围。暂时不要阅读第 2 步的说明。

---

第 2 步：埋点、运行应用并捕获参考 trace

第 2 步有三个子步骤。每个子步骤都会阅读自己的参考文件。在开始下一个子步骤之前，先完成每一个子步骤。

子步骤 2a：使用 wrap 埋点

参考：立即阅读 references/2a-instrumentation.md。

在应用的数据边界处添加 wrap() 调用，这样评估 harness 就能注入受控输入并捕获输出。这使应用无需更改逻辑即可被测试。

检查点：在所有数据边界处都已添加 wrap() 调用。pixie_qa/02-eval-criteria.md 中的每一条评估标准都有对应的数据点。

子步骤 2b：实现 Runnable

参考：立即阅读 references/2b-implement-runnable.md。

编写一个 Runnable 类，让评估 harness 能够像真实用户那样精确地调用应用。Runnable 应该很简单——它只是把应用的真实入口点接入 harness 接口。如果它变得复杂了，那就说明出了问题。

检查点：pixie_qa/run_app.py 已写入。Runnable 使用真实的 LLM 配置调用应用的真实入口点——不 mock、不伪造、不替换组件。

子步骤 2c：捕获并验证参考 trace

参考：立即阅读 references/2c-capture-and-verify-trace.md。

通过 Runnable 运行应用并捕获一条 trace。该 trace 证明埋点和 Runnable 工作正常，并提供第 4 步创建数据集所需的数据结构。

检查点：pixie_qa/reference-trace.jsonl 存在。所有预期的 wrap 条目和 llm_span 条目都出现。pixie format 显示评估所需的全部数据点。暂时不要阅读第 3 步的说明。

---

步骤 3：定义评估器

参考：立即阅读 references/3-define-evaluators.md 了解详细的子步骤。

目标：将步骤 1c 中的定性评估标准转化为具体、可运行的评分函数。每个标准对应一个内置评估器、一个 Agent 评估器（任何语义或定性标准的默认选择），或一个手动自定义函数（仅用于正则或字段存在性等机械性/确定性检查）。评估器映射产物在标准与数据集之间架起桥梁，确保每个质量维度都有评分器。选择能衡量 pixie_qa/00-project-analysis.md 中所识别的难题的评估器——而不仅仅是通用的质量维度。

检查点：所有评估器均已实现。已编写 pixie_qa/03-evaluator-mapping.md，包含标准到评估器的映射及决策依据。暂时不要阅读步骤 4 的说明。

---

步骤 4：构建数据集

参考：立即阅读 references/4-build-dataset.md 了解详细的子步骤。

目标：创建将所有内容串联起来的测试场景——可运行组件（步骤 2）、评估器（步骤 3）和用例（步骤 1c）。每个数据集条目定义要发送给应用的内容、应用应从外部服务看到的数据，以及如何对结果进行评分。使用步骤 2 中的参考 trace 作为数据形态和字段名称的真实来源。覆盖 pixie_qa/00-project-analysis.md 中能力清单的条目，并包含针对其中所识别失败模式的条目。不要将项目自身的测试 fixture、mock 服务器或示例数据用作数据集 eval_input 的内容——应改用真实世界数据。应用中的每个 wrap(purpose="input") 都必须在每个条目的 eval_input 中具有预先捕获的内容——当应用有 input wrap 时，不要将 eval_input 留空。

检查点：已在 pixie_qa/datasets/<name>.json 创建数据集 JSON，包含覆盖所有用例的多样化条目。数据集真实性审计通过——条目使用具有代表性规模的真实世界数据，无项目测试 fixture 污染，至少有一个条目针对结果不确定的失败模式，且每个 eval_input 都为所有 input wrap 捕获了内容。暂时不要阅读步骤 5 的说明。

---

步骤 5：运行 pixie test 并修复机械性问题

参考：立即阅读 references/5-run-tests.md 了解详细的子步骤。

目标：端到端执行完整流水线，使其在无机械性错误的情况下运行。这一步严格来说是关于修复 pixie QA 组件（数据集、可运行组件、自定义评估器）中的设置和数据问题——而不是修复应用本身或评估结果质量。一旦 pixie test 无错误地完成，并为每个条目生成真实的评估器分数，这一步就完成了。

检查点：pixie test 运行至完成。每个数据集条目都有评估器分数（真实的 EvaluationResult 或 PendingEvaluation）。没有设置错误，没有导入失败，没有数据验证错误。

如果测试报错，那是你的 QA 组件中的机械性 bug——修复并重新运行。但一旦测试产生分数，就继续。不要在此处评估结果质量——那是步骤 6。

测试产生分数后，始终继续进入步骤 6。 分析是至关重要的最后一步——没有它，待处理的评估永远不会完成，用户得到的只是未经解读的原始分数，没有可操作的洞察。不要停在此处询问用户是否继续。

迭代运行的循环规则：每次成功调用 pixie test 都会创建一个具体的 pixie_qa/results/<test_id> 目录并开始一个新的分析循环。在你编辑应用代码、提示词、数据集、评估器或重新运行 pixie test 之前，请为该确切的 results 目录完成步骤 6。不要跳过较早的循环而只分析最后一次运行。

---

第 6 步：分析结果

参考：现在阅读 references/6-analyze-outcomes.md —— 其中包含完整的三阶段分析流程、写作指南和输出格式要求。

目标：以结构化、数据驱动的方式分析 pixie test 结果，从而对测试用例质量、评估器质量和应用质量产生可执行的洞察。本步骤会完成待处理的评估，撰写逐条目和逐数据集的分析，并产出按优先级排序的行动计划。每一处陈述都必须由评估运行中的具体数据支撑 —— 不得臆测，不得含糊其辞。

持久化的分析产物：在此精简工作流中，仅在数据集级别和测试运行级别持久化分析。这些产物仍采用详细版本（供 Agent 使用：数据点、证据链、推理链）加摘要版本（供人工审阅：可在 2 分钟内读完的简洁 TLDR）。不要创建逐条目的分析文件。

硬性完成门槛：在第 6 步中，只有以下条件全部满足，才算完成：

• 每个 pixie_qa/results/<test_id>/dataset-*/entry-*/evaluations.jsonl 中所有 "status": "pending" 的条目都已替换为包含 score 和 reasoning 的已评分结果。
• 每个数据集目录都有 analysis.md 和 analysis-summary.md。
• 测试运行根目录有 action-plan.md 和 action-plan-summary.md。
• 你已针对 pixie_qa/results/<test_id> 运行了本技能 resources/ 目录中的第 6 步验证脚本，并且它报告成功。

明确不充分的做法：

• 只写一个顶层文件，例如 pixie_qa/06-analysis.md
• 声称待处理的评估由用户在 web UI 中审阅
• 声称某条目“很可能通过”却不更新 evaluations.jsonl

---

Web 服务器管理

pixie-qa 会在后台运行一个 web 服务器，用于向用户展示上下文、trace 和评估结果。它由安装脚本自动启动（通过 pixie start，该命令会启动一个分离的后台进程并立即返回）。

当用户完成 eval-driven-dev 工作流后，告知他们 web 服务器仍在运行，你可以用以下命令将其清理：

pixie stop

重要：web 服务器停止后，web UI 将无法访问。因此，只有在用户确认他们已用完所有 web UI 功能时，才停止服务器。如果他们想继续使用 web UI，请勿停止服务器。

并且，每当你重新启动该工作流时，都要再次运行 resources 中的 setup.sh 脚本，以确保 web 服务器正在运行：