eval-driven-dev

面向Python LLM应用的评估驱动开发

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

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

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

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

交付物是一个可运行的pixie test，带有真实分数——而不是计划，不仅仅是插桩，也不仅仅是数据集。

此技能是关于执行工作，而不是描述它。阅读代码、编辑文件、运行命令、生成可工作的流水线。

---

开始之前

首先，激活虚拟环境。识别项目正确的虚拟环境并激活它。虚拟环境激活后，运行技能资源中包含的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。
• 仅在步骤要求时阅读参考文件。 每个步骤指定一个特定的参考文件。在到达该步骤时阅读它——而不是之前。
• 立即创建产物。 在阅读子步骤的代码后，在继续之前为该子步骤编写输出文件。不要在多个子步骤中积累理解而不写任何东西。
• 验证，然后继续。 每个步骤都有一个检查点。验证它，然后进入下一步。在验证当前步骤时不要计划未来的步骤。

何时停止并寻求帮助：

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

• 由于缺少环境变量或配置，应用无法运行：应用需要未设置且无法推断的环境变量或配置。不要通过模拟、伪造或替换应用组件来绕过——评估必须执行真实的生产代码。请用户修复环境设置。
• 指示项目损坏的导入失败：如果应用的核心模块由于缺少系统依赖或不兼容的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。

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

检查点：已编写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：插桩、运行应用并捕获参考跟踪

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

子步骤2a：使用wrap进行插桩

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

在应用的数据边界添加wrap()调用，以便评估框架可以注入受控输入并捕获输出。这使得应用可测试而不改变其逻辑。

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

子步骤2b：实现Runnable

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

编写一个Runnable类，使评估框架能够像真实用户一样调用应用。Runnable应该简单——它只是将应用的真实入口点连接到框架接口。如果它变得复杂，说明有问题。

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

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

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

通过Runnable运行应用并捕获跟踪。跟踪证明插桩和Runnable正常工作，并为步骤4中的数据集创建提供所需的数据形状。

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

---

步骤3：定义评估器

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

目标：将步骤1c中的定性评估标准转化为具体的、可运行的评分函数。每个标准映射到内置评估器、代理评估器（任何语义或定性标准的默认选择）或手动自定义函数（仅用于机械/确定性检查，如正则表达式或字段存在性）。评估器映射产物连接标准和数据集，确保每个质量维度都有一个评分器。选择衡量pixie_qa/00-project-analysis.md中识别的难点问题的评估器——而不仅仅是通用质量维度。

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

---

步骤4：构建数据集

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

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

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

---

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

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

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

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

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

在测试产生分数后始终进入步骤6。 分析是必要的最終步骤——没有它，待定评估永远不会完成，用户得到的是未解释的原始分数，没有可操作的见解。不要在此处停止并询问用户是否继续。

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

---

步骤6：分析结果

参考：立即阅读references/6-analyze-outcomes.md——它包含完整的三阶段分析过程、编写指南和输出格式要求。

目标：以结构化的、数据驱动的方式分析pixie test结果，生成关于测试用例质量、评估器质量和应用质量的可操作见解。此步骤完成待定评估，编写每个条目和每个数据集的分析，并生成优先行动计划。每个陈述必须由评估运行的具体数据支持——没有推测，没有含糊其辞。

持久化分析产物：在此精简工作流中，仅在数据集级别和测试运行级别持久化分析。这些产物仍然使用详细版本（供代理消费：数据点、证据线索、推理链）加上摘要版本（供人工审查：可在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服务器，用于向用户显示上下文、跟踪和评估结果。它由设置脚本自动启动（通过pixie start，它启动一个分离的后台进程并立即返回）。

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

pixie stop

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

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