ADR-EVAL-008：Aira Evals 开源复用边界

状态：Accepted
决策日期：2026-08-29
影响范围：aira-evals package、benchmark runtime、外部数据与 scorer 适配
依据：Aira Evals 开源复用审计

Context

aira-evals 需要覆盖能力检索、状态适用性、typed planning、tool calling、AMIR 事务、真实 CAD 执行、可编辑性、工程要求和安全性。原计划包含 CLI、runner、model provider、并发、artifact、report 等完整基础设施，存在重复实现成熟开源框架的风险。

与此同时，单一现有框架无法表达 Aira 的全部领域语义：普通 tool relevance 不等于 CAD plan sufficiency；现有 CAD benchmark 也普遍不理解 Revision、Session Grant、AMIR transaction、SemanticRef 或跨内核 certificate。

Decision

1. 不创建第三套通用 eval runner

aira-evals 不实现通用模型 provider、Agent adapter、并发调度、重试、容器/cloud sandbox、trajectory store、结果 viewer 或 benchmark registry。

2. 保留宿主无关的 Aira canonical core

以下内容由 Aira 拥有并作为稳定协议：

EvalTask、AcceptablePlan、Disposition；
Revision/selection/runtime/grant fixtures；
capability catalog snapshot；
deterministic domain oracle 和 score schema；
run/result provenance 与 content hash；
Sufficiency@k、applicability、transaction、editability 和 certificate semantics。

Canonical core 不导入 Inspect 或 Harbor 类型。Adapter 负责双向转换，防止 framework schema 成为 Aira 的模型真相。

3. Inspect AI 是 L0–L5 的默认宿主

以 Inspect extension package 形式发布 Aira task、solver、scorer 和 tool。使用 Inspect 的 model APIs、MCP/tool loop、sandbox、log、re-score 和 viewer。

4. Harbor 是 L6–L10 的默认宿主

真实 CAD/AMIR/Agent 任务编译为 Harbor dataset/task。候选执行与 verifier 分离；生成代码、插件、文件和模型输出一律视为不受信任数据。

5. 外部 benchmark 通过 adapter 或独立 suite 复用

ToolRet：retrieval baseline；
BFCL：function calling conformance；
τ³-bench/ToolSandbox：stateful task design；
MCPMark/MCP-Universe：MCP 与 3D agent external regression；
CADTestBench：requirement-linked executable assertions；
CAD-bench：Harbor CAD task/verifier 模式；
freecad-validator：FreeCAD cross-system scorer；
CADGenBench/BenchCAD/CADBench/MUSE：外部 CAD 回归与指标。

默认不 vendoring 数据。依赖必须锁定 release/commit/content hash，并记录代码与数据许可证。

6. 禁止在控制进程直接执行模型生成代码

无论上游 benchmark 是否如此实现，Aira 不在 eval controller 进程内调用 exec、动态 import 或等价机制执行候选代码。执行必须发生在 Inspect sandbox、Harbor agent/verifier environment 或受等价资源约束的独立进程中。

Initial package shape

packages/aira-evals/
  src/aira_evals/
    contracts/          # host-neutral schema/models/hash
    datasets/           # Aira-authored task materialization
    scorers/            # Aira-only metrics
    oracles/            # applicability/plan/transaction/CAD bindings
    inspect_ext/        # Inspect registration and adapters
    harbor/             # Harbor task compiler/verifier helpers
    external/           # version-pinned benchmark adapters
  harbor_datasets/      # Aira E2E task definitions
  tests/

Consequences

正面：

省去大量非差异化基础设施；
立即获得多模型、沙箱、并发、轨迹和结果查看能力；
可直接与公开 tool/CAD benchmark 比较；
Aira 研发集中在能力发现和工业 CAD 的独有语义；
canonical core 仍可迁移到未来框架。

代价：

需要维护 Inspect 与 Harbor 两个 adapter；
同一任务跨宿主的一致性必须有 contract tests；
外部项目升级可能改变默认行为，正式 run 必须锁定版本；
Windows 本地开发与 Linux container 的 CAD kernel 差异需要显式记录。

Rejected alternatives

完全自研 Python runner

拒绝。重复实现模型适配、日志、并发、sandbox 和 viewer，且不会增加 Aira 领域优势。

只使用 Inspect AI

拒绝作为唯一宿主。可以运行 sandbox，但 Harbor 已形成以 task image、独立 verifier 和 Agent CLI 为核心的长任务生态，且已有 CAD-bench/FreeCAD 先例。

只使用 Harbor

拒绝作为唯一宿主。对纯 retrieval、schema、applicability 和 scorer 单元实验过重；Inspect 的组件扩展、重评分和模型/tool 评测更直接。

直接 fork CADTestBench/CAD-bench

拒绝。它们只覆盖特定 CAD 表示和任务；fork 会把 Aira 语义锁进 CadQuery/Build123D。采用固定版本 adapter 和外部 conformance suite。

Verification gates

本 ADR 在以下三个 spike 通过后从架构决策变为实现验证：

Inspect 中运行 12 capability / 12 task，并产出 Aira canonical result；
Harbor 中运行一个隔离的 AMIR/CAD task，并产出相同 result envelope；
一个 CADTestBench sample 在独立 verifier 中运行，不在 controller 进程执行候选代码。

若任一 adapter 要求复制宿主的大量内部实现，应重新评审本 ADR，而不是增加新的通用 abstraction layer。

Implementation evidence（2026-08-29）

详见最小技术验证报告。

Gate	状态	证据
Inspect 12 capability / 12 task + canonical result	Verified	三条 baseline、36 个逐样例 cross-scorer 一致性检查、Inspect `.eval` 日志
Harbor isolated AMIR/CAD task	In Progress	Harbor schema/parser 与 deterministic verifier 已通过；本机缺 Docker，尚无双容器 trial
CADTestBench sample in independent verifier	In Progress	固定 revision 的 12 条断言与 controller/worker 边界已实现；OCP 被 Windows 策略阻止

当前证据没有推翻本 ADR，也没有发现需要复制 Inspect/Harbor 内部 runner 的情况。但由于后两项尚无 Linux container 运行证据，ADR 的宿主边界是“实现方向已支持”，不是 “全部 verification gate 已完成”。