用途
eval-author-environment 是 Eval Author 的子流程，负责为任务构建其运行的“世界”，并在任何任务依赖它之前证明这个世界可以正常工作。当 first-eval 或 task-create 等创作流程已确定测试用例、尚未编写测试时启动：first-eval 在 Prepare cases and grading 阶段，task-create 在编写草稿验证器之前。该流程负责 provider 适配、每个依赖的提供方式、起始数据与重置、终态如何到达验证器、隔离、环境冒烟证明以及可复用工具包；用例设计、指令、评分标准、agent 连接和各任务的 NOP/Oracle 控制仍归调用流程所有。
必需产出
在 .eval-author/environments/<agent-slug>/ 下需包含：
- environment-plan.md：从模板起步，记录适配性、清单、依赖选择、保真卡和证明状态，全程保持更新；
- data/ 中带种子的生成器：产出起始数据，并带有完整性检查和逐表内容摘要，供验证器检查需保留的表。数据规模应接近 agent 实际会遇到的数据，足够大以迫使其搜索和选择，并包含混合状态、相似记录和边界值；
- smoke/ 中的冒烟任务：包含 NOP 运行和两次参考解运行。只有当计划中明确列出这三个作业时，计划才可标记为 proven。
必须先构建并证明工具包，再编写测试：先生成起始数据并通过冒烟任务，然后用独立的参考查询从这些数据推导每个预期值。少量手工输入的固定行和手算答案不算起始数据；任务自身的 NOP、Oracle 或验证器控制也不能证明环境。
工具包结构
每个 agent 构建一个环境工具包，供该 agent 的所有任务复用：
.eval-author/environments/<agent-slug>/
environment-plan.md fit, inventory, choices, data, export, isolation, fidelity card, proof
build/ base Dockerfile and docker-compose.yaml, or Gym backend code
data/ seed generator, its seed, generated base data, integrity checks
smoke/ the smoke task and its retained results
已有工具包时直接复用；仅当仓库修订、数据生成器、provider 版本或依赖选择变化时才重新证明。
步骤
Step 1：检查适配性。 根据入口点、部署文件和 Ethos Harness 章节判断 agent 的运行形态：在沙箱内运行的 agent（编码、CLI、计算机使用）适配 Harbor 直接方式；应用工具调用后端的框架型 agent 在其应用可容器化时较适合，可把后端替换为 sidecar；托管型 agent 调用托管产品 API 且无可运行代码时适配性差，不应构建仅转发请求并事后检查结果的 Harbor 任务，可考虑 Gym、可运行构建、厂商沙箱或报告限制。适配性差属于 provider 选择规则下的提案，由用户决定是否更换 provider，绝不静默切换。
Step 2：清点仓库。 只读地记录每个被用例涉及的工具和服务：接触的文件、数据库、仓库内服务或外部 API；从代码判断读写性质（HTTP 方法、SQL/ORM 调用、MCP readOnlyHint、文档化副作用）；运行位置、访问方式和重置要求；已存在的 Dockerfile、compose 文件、迁移、API 规范、fixtures、种子脚本；客户端代码处理的失败；以及未知项及解决办法。可从示例、设置模块和代码读取配置变量名，但绝不打开 .env 或打印密钥值。需要复制到工具包的文件应复制，不编辑、移动或重排用户文件。
Step 3：选择依赖提供方式。 优先选择可复现且最忠实的方式：Real（仓库自身服务、数据库镜像或 CLI，运行在任务容器或 sidecar）；Vendor sandbox（厂商测试模式，需用户授权、网络允许列表、凭据按变量名提供）；Stateful fake（按 API 契约构建的小型服务，跨调用保持状态并返回真实错误形状）；Replay（从 trace 录制响应，仅用于输入完全重复的只读调用）；None（用例不需要该依赖）。每降一级都会以可预测方式损失保真度，需在计划的保真卡中记录每个选择及其差距。应提供后端而非工具：Harbor 将工具视为 agent 的一部分，agent 自有工具代码应通过其客户端已支持的配置访问所提供的后端；Gym 的 resources server 拥有工具面，需用复制真实工具名、参数和错误的端点包装同一后端。环境行为必须从 agent 所作用的系统和 Ethos 推导，绝不能来自 agent 的提示或工具选择逻辑。
Step 4：构建起始数据。 用固定种子从仓库 schema 在代码中生成基础数据，规模与形状贴近实践数据，必要时使用选定 trace，并物化到 data/。将各用例自有记录叠加在基础数据之上，随任务保存；当用例需要易混淆记录（如相似客户、不合格订单）时，构建可通过允许读取区分的附加诱饵，其标签仅供验证器使用。在任何任务依赖数据之前检查完整性：引用可解析、状态允许预期操作、总计可重算、运行时分配的标识符未被预创建。记录验证器专用的逐表内容摘要，使每个任务按内容而非行数检查需保留的内容。在编写验证器之前，用独立的参考查询从生成的记录推导每个用例的预期终态，而非对少量行做算术；Ethos 未确定正确性时标记为未解决并在检查点提出。
Step 5：使终态可读。 评分器需要结果状态而非 agent 的叙述。明确声明哪些内容到达验证器、哪些易变字段（时间戳、生成的标识符）应忽略。Harbor：从 agent 容器和 sidecar 导出状态，然后在独立的离线验证器中评分；Gym：验证器在 resources server 中运行并读取会话状态。导出缺失或不可读属于基础设施故障，绝不能作为 agent 是否行动的证据；每个任务的副作用控制读取此导出作为可信观察。
Step 6：隔离运行并保护隐藏答案。 按阶段限制网络：agent 运行时只能访问所需内容（通常是模型 provider 和授权的厂商沙箱），验证器无网络。运行时无法强制执行策略时，将隔离记录为未证明，而非静默公开访问。凭据按变量名引用，绝不将密钥值写入工具包、任务文件、计划或报告。预期状态、诱饵标签、参考解和验证器辅助文件不得出现在 agent 可见的任何内容中：镜像、挂载文件、工具输出和其收到的数据集字段。每次试验从种子状态开始；重置容器不会重置外部服务，需记录其重置方式并在隔离证明前保持此类试验串行。
Step 7：证明环境。 在构建后、编写任何任务测试前一次性证明：Harbor 运行 smoke/ 中的冒烟任务，其参考解通过 agent 自有客户端代码对每个依赖执行一次读和一次写，验证器检查导出状态恰好显示这些变化；NOP 运行一次，参考解运行两次，第二次通过表明每次试验从干净状态开始。Gym 添加会话内持久和会话间重置的验证器用例，并运行原生验证。Harbor 传递 MCP 服务器配置给 agent 但不证明 agent 已连接；需在一次实际 agent 运行中确认发现与调用，这需要已有的执行和花费授权，否则记录发现为未证明。在 environment-plan.md 中记录每次证明运行的命令、作业路径和结果；这些运行证明环境而非任务，不得声明为任务控制或计入其证据回执。设置失败视为基础设施问题而非 agent 结果，修复并重跑，最多三次修复后报告环境失败；该预算与任何任务的修订链分开，诊断探针不能完成证明，不得削弱冒烟检查使其通过。结果记录为 proven、unproven（缺少前提或检查未运行）、blocked（必需依赖无法提供）或 failed；proven 要求在计划的证明表中包含冒烟任务自身的三个作业（Gym 为持久与重置用例）。
Step 8：交接工具包。 完善 environment-plan.md：选择、保真卡、证明结果和证据路径。按 Suite review and rerun instructions 向套件的审查与重跑指南添加设置、服务启动、凭据变量名和重置步骤，并在用例清单的已知限制中列出影响各用例的保真卡差距。告知调用流程任务如何使用工具包：Harbor 任务将工具包的构建文件和数据复制到自己的 environment/（或使用按摘要固定的推送镜像）并添加自有记录，从而无需本次会话构建的工具包镜像即可构建；Gym 任务复用后端并在每个会话种子化其记录。返回调用步骤。证明的环境表明世界可用，但不验证任务评分器或衡量 agent。
前提条件
规划与清点只需仓库访问权限。构建和证明 Harbor 环境需要 Harbor CLI 及带 Compose 的 Docker；Gym 需要其独立运行时。厂商沙箱需要用户授权和凭据（按变量名引用）。用于证明工具发现的 agent 运行需要执行和花费授权。
限制
环境只复现仓库、trace 和授权沙箱所揭示的内容。有状态仿真只建模其实现的操作和错误，回放只覆盖已记录的输入；保真卡需列出这些差距。证明的环境不确立任务正确性、评分器健全性或 agent 性能。
故障排查
冒烟参考解失败：先检查服务健康、种子化和导出，再动冒烟检查；修复环境后重跑。sidecar 或 collect 钩子不受支持：所选沙箱可能缺少 Compose 支持，记录限制或选择受支持的后端。no-network 或允许列表在运行前被拒绝：运行时无法强制执行该策略（Docker Desktop 上常见），按 Harbor environments 的回退方案处理并记录隔离为未证明，绝不静默放宽策略。仅生产环境存在的依赖：在调用流程的检查点解决，未经明确授权绝不将任务指向生产。