eval-engineering

评测工程

流程

• 首先检查所有输入：仓库、Harness、可选的轨迹、现有的 Task 和运行记录、现有的 World Knowledge，以及人工目标。在提出工作之前，确定适用的源文件和技能参考资料。
• 根据这些输入中的可复用事实，创建或更新小型项目 World Knowledge Skill。利用它提出一个有据可依的 Task。
• 同时起草 Task Spec 和 World Skill。向用户展示两者，仅在 Task.md 中保留准确的 Task 内容，并持续完善两者，直到用户批准。
• 实现获批的 Task，验证其 Environment 和 Verifier，运行真实的 Harness，检查完整证据，并且只修复非 Agent 导致的问题。
• 根据运行结果核对并更新 World Skill，然后重复此流程，处理下一个 Task。

术语

• Task Spec： Task.md，描述单个 Task 的输入、相关 Agent 条件、Environment、评分、公平性和待定决策。
• Task： 可运行的指令、Environment 和 Verifier。
• Harness： Harbor 运行的完整 Agent，包括提示词、模型循环、工具、钩子、记忆、会话和适配器。
• Environment： Harness 周围的文件、数据、服务、身份、权限、网络、时钟和可变状态。
• Verifier： 独立检查，用于评估结果或将运行标记为无效。
• World Knowledge Skill： 仓库本地技能，包含可复用的项目专属知识、参考资料、脚本、资源和测试，帮助生成 Task Spec 并构建未来的 Task。
• Spec2Task： 将经过审核的 Task Spec 转化为经过审计的可运行 Task 的完整流程。具体构建顺序和参考资料路由，请遵循 Task implementation。

参考资料路由

在遇到相关决策时阅读相应参考资料：

需求	阅读
检查源文件、轨迹、Harness、依赖项、访问权限和现有评测	Discovery
初始化或更新可复用的项目知识	World knowledge
提出 Task 并编写唯一的 Task Spec	Task design
构建数据、服务、访问权限、状态和重置机制	Environment building
创建结构化数据或自然语言数据	Synthetic data
定义独立证据和评分	Verifier design
应用 Spec2Task，将经过审核的 Spec 转化为经过审计的 Task	Task implementation
比较模型运行结果并归类失败	Calibration
打包并运行 Harbor Task	Harbor
改编已知的基准测试设计	Benchmark patterns
构建多轮对话	Multi-turn simulation
查看从两个 Task 中积累的 World knowledge	Service-desk example

可复用的实现资源：

• 多轮 runner、model user 和 Harbor adapter example
• Tool-schema comparison，用于比较提供的 schema 片段，但不会解析外部 $ref 目标
• Read-only SQLite state snapshot

1. 检查输入和现有的 World 知识

在提出 Task 前，先检查用户提供的每一项输入。根据可用输入，遵循相应指南：

• 对于仓库、Harness、跟踪记录或依赖项，请阅读 Discovery。
• 对于现有 Task 和运行记录，请检查其指令、Environment、 Verifier、奖励、轨迹和最终状态。当运行质量或失败原因 会影响新设计时，请阅读 Calibration。
• 对于现有的项目 World Skill，请阅读 World knowledge， 然后检查会影响新 Task 的来源和可复用方法。
• 对于人工设定的目标和约束，请阅读 Task design。
• 对于相关基准示例，请使用 Benchmark patterns 中的领域索引和来源说明。

在询问源代码和测试能够回答的问题前，先检查仓库。沿着当前 Harness 检查提示词、模型、工具、服务、状态、效果和针对性测试。检查现有 Task 指令、解析器、Verifier、奖励路径和运行证据。

如果用户提供了跟踪记录，请查看完整的运行记录或对话线程。利用跟踪记录了解真实请求、依赖项行为、状态结构、错误和失败条件。不要将跟踪记录中的答案视为独立事实。

如果存在 .agents/skills/<project>-world/SKILL.md，请阅读。仅在其路由与当前 Task 相关时遵循。若引用的仓库路径、命令和脚本的准确性会影响设计，请予以核查。

2. 提出并选定 Task

阅读 Task design，并使用 Benchmark patterns 中的索引，找出相关领域和来源说明。除非 Task 涉及其他领域，否则聚焦于该领域。在检查完毕后的首条面向用户的设计回复中，提出一个以仓库证据、用户提供的跟踪记录、现有覆盖范围或人工优先事项为依据的 Task。说明：

• 实际工作和所需能力；
• 使案例并非轻而易举的条件；
• 所需的 Environment 和独立证据；
• 能检测出的重要失败；
• 与现有 Task 的区别；以及
• 主要待定决策。

在同一条回复中，展示当前相关的 World Skill 内容，以及该 Task 所建议的具体补充或修正。如果不存在 World Skill，请展示有助于创建此 Task 和未来 Task 的精简初始内容。不要将 Task 的确切请求、重点记录、预期结果、隐藏事实和精确评分规则写入 World Skill。

在开始实施前，让用户有机会一起修改 Task 提案和 World 知识。只有当真实的用户选择会改变设计时，才提供备选方案。

3. 编写并审查 Task 规范和 World Skill

将 Task 模板复制到 evals/<suite>/tasks/<task-id>/Task.md。所有特定于 Task 的设计都放在这一个 文件中。同时，按照世界知识创建或更新项目的 World Skill。 确定当前 Agent 和仓库支持的项目 Skill 位置。 .agents/skills/<project>-world/SKILL.md 和 .claude/skills/<project>-world/SKILL.md 是常见的存放位置。如果项目已有约定， 请遵循该约定。否则，说明拟议的位置，并在创建 Skill 前征得用户确认。必要时，从 World Skill 模板开始。

将每个 Task.md 放在它所描述的 Harbor Task 旁边：

evals/<suite>/tasks/<task-id>/
├── Task.md              # human-reviewed control-plane spec
├── task.toml             # required Harbor configuration
├── instruction.md        # required agent input
├── environment/          # required Environment definition and visible state
│   ├── Dockerfile        # use this or docker-compose.yaml
│   └── docker-compose.yaml # optional; primary service must be main
├── tests/
│   ├── test.sh           # required Harbor Verifier entry point
│   ├── test_*.py         # optional Verifier helpers
│   └── fixtures/         # optional hidden Verifier data
└── solution/
    └── solve.sh          # optional reference path

绝不要将 Task.md 复制或挂载到受评估 Agent 的工作区或镜像中。 Agent 会收到 instruction.md，以及仅供本次运行使用的 Environment 状态。

包括：

• 目的和来源证据；
• 确切输入和后续轮次；
• 仅包含与此 Task 相关的 Harness 条件；
• 初始状态、服务、访问权限、可见内容、重置方式及与生产环境的差异；
• 必需结果、禁止的影响、可接受的替代方案，以及独立 Verifier 证据；
• 公平性、信息泄露风险和无效运行条件；以及
• 未决事项和假设。

向用户展示完整的 Task 规范和 World Skill 变更。说明 World Skill 中已有的内容、此 Task 新增或更正的内容，以及仅保留在 Task.md 中的内容。通过同一轮往返沟通修改两者。只有在用户明确批准后，才将 Task 规范标记为已批准。只有用户审阅后，才将 World Skill 变更视为已接受。如果用户要求端到端构建且不暂停等待批准，则继续使用经过 Agent 审查的 Status: Draft，并将 World Skill 变更标记为未经审查。

如果实现过程改变了请求、可见信息、重要的 Environment 行为或评分边界，请更新 Task.md 并展示变更。将其状态改回 Draft。展示差异，并在再次将其设为 Approved 前要求用户明确重新批准。

4. 应用 Spec2Task

遵循Task 实现。其中介绍了构建顺序，并将各项决策分别引导至 Environment、合成数据、Verifier、Harbor 和校准参考资料。

对于现有项目，使用其固定或受支持的 Harbor 版本。否则，使用已安装的受支持版本并记录下来。只有在用户批准且说明兼容性原因后，才升级版本。以已安装的 CLI 帮助信息作为命令规范。

在进行评分模型运行之前：

1. 确认模型、试验次数、评判器、超时时间和最高预期费用，除非用户已授权该运行计划。
2. 完成 Harbor 中的打包审计。确认此 Task 所需的每个必需文件、入口点、路径、权限、配置值、挂载项、服务和奖励输出均已就绪，并可通过 Harbor 正常工作。确认 Agent 可见的镜像和工作区中不含隐藏的 Task、Verifier、解决方案和机密材料。
3. 按适合 Environment 的方式检查设置和试验隔离。新建容器或工作树可通过替换实现隔离。重复使用的可变服务需要经过检查的重置。不可变的冻结数据只需检查加载情况。请参阅Task 实现。
4. 执行 Task 依赖的每项操作。
5. 如果存在参考路径，则运行该路径。
6. 使用明确的有效结果、有效替代方案、符合实际的错误结果、捷径、禁止的附带更改，以及缺失或损坏的证据测试 Verifier。
7. 确认 Verifier 的每条已完成路径都会写入有效奖励和有用证据，且不会泄露隐藏的真实结果或机密。

5. 运行和审计

通过 Harbor 运行实际的 Harness。阅读完整的执行轨迹，而不只是奖励。检查：

• 消息、模型调用、工具调用、结果、重试和错误；
• 初始和最终的 Environment 状态及外部影响；
• 服务、设置、就绪状态、重置和清理的证据；
• 每项 Verifier 标准、其证据、判定和错误；以及
• 已解析的 Harness、模型、Environment 和评审器配置。

将每次未成功的运行归类为 Agent 能力失败、信息缺失、Harness 缺陷、Environment 缺陷、Verifier 误拒绝、Verifier 误接受、信息泄漏或基础设施故障。使用评分前，先修复非 Agent 问题。

模型比较是一种可选的校准策略，并非完成规则。如果比较能解答实际存在的不确定性，则比较较弱的模型、目标模型或较强的模型；如果行为不稳定，则重复试验。阅读每条选定的轨迹。对比可以揭示输入不清晰、设置脆弱、信息泄漏、走捷径或奖励作弊。通过率和模型排序并不能证明 Task 质量。

阅读校准，了解完整的审计方法。

6. 整合项目 World 知识

在整个 Task 设计、实现和审计过程中使用World 知识。如果工作提供了有助于其他 Task 的证据，请补充或更正项目专属知识。这些知识可以包括 Task 模式、Environment 方法、数据创建、Verifier 证据、运行流程、脚本、资源和示例。

审计后，根据已完成的 Task 所证实的内容整合 World Skill。向用户展示：

• 提议复用的知识；
• 支持该知识的证据；
• 其他 Task 将如何使用它；
• 它应存放的位置；以及
• 哪些内容仍是已完成 Task 特有的。

删除或收窄已被 Task 证伪的想法。如果用户要求在不中断的情况下自主完成端到端更新，则只进行证据支持的最小更新，在最终审查中展示该更新，且不要暗示人类已认可这一泛化结论。

首先只创建 SKILL.md。只有在 references/、scripts/、assets/ 或 tests/ 中确有内容值得添加时，才添加这些目录。

将已完成 Task 的请求、焦点状态、预期结果和精确标准保存在其同目录的 Task.md 中。不要复制本 Skill 中已经清楚的宽泛指导。记录对该指导进行的项目专属调整。

7. 重复

使用 Task 2 和 Task 3 测试 World Skill。检查它是否减少了重复探索、改善了 Task 规范、保留了重要关系、复用了已验证的操作，或避免了已知的 Verifier 缺陷。修正缺失、过时或范围过宽的规则。

当多个差异显著的 Task 已经验证了共享知识，且构建和验证方法已明确时，下一轮可以提出多个相互独立的 Task 规范：

1. 收集新的仓库、轨迹和人工证据。
2. 使用 World Skill 生成不同的 Task 规范。
3. 让人类审查这些规范。
4. 并行构建彼此独立且已获批准的 Task。
5. 分别审计每个 Task。
6. 仅根据可复用的修正更新 World 知识。

随着生产行为、用户优先事项、Agent 和模型发生变化，持续这一循环。

依赖项、访问权限和安全

梳理所需的系统、数据、角色、网络需求和安全的设置方法。切勿读取、打印、复制或存储机密值，也不要要求人类粘贴机密值。告知人类需要什么依赖项、为何需要，以及项目预期如何提供访问权限。默认使用受控的本地、冻结或模拟依赖项。评估期间切勿写入生产环境。将访问、启动、重置、超时、评审器和 Verifier 故障视为无效运行，而非 Agent 工作失败。

仅在以下情况下完成

• Task.md 与构建好的指令、环境和验证器一致。
• 任务可根据 Agent 可见的信息或通常可发现的信息解决。
• 环境能够可靠启动，并通过替换、重置或不可变状态适当地隔离试验，且不会泄露隐藏事实。
• 验证器的有效和无效用例均按预期运行。
• 至少完整阅读过一次真实的 Harness 运行记录。
• 非 Agent 导致的问题已修复，或已报告为未解决的限制。
• 使用模型比较时，包含轨迹审查，而非仅比较通过率。
• 已创建或更新项目的 World Skill，其中包含任务规范；工作期间已审查该 Skill，并已根据最终证据进行调整。
• 已向用户提供任务路径、运行命令、结果、证据和剩余限制。