第三方基准测试接入规范

解释如何在不污染框架内核的前提下，把新的基准测试家族正式接入 QitOS。

​

第三方基准测试接入规范

QitOS 把基准测试集成当作一套正式 SDK，而不是零散脚本。

如果你要新增一个基准测试家族，默认结构应该是：

• qitos.benchmark.<family>：数据集适配、运行时、评估器、评分器、基准测试原生产物
• qitos.recipes.*：可复现基线方法
• examples/*：仅保留最薄的用户入口

不要把基准测试专用的 setup、评分、数据集逻辑塞进 qitos/core、DesktopEnv 或示例文件。

​

三层边界

​

框架层

这些能力属于框架：

• AgentModule + Engine
• ActionSpace
• EnvironmentAdapter
• DesktopEnv
• 与提供商无关的工具/动作词汇
• 家族预设与适配层（harness，负责将协议、传输层、工具交付等组合在一起的模型适配层）所有权
• qita 回放、导出、比较、截图时间线、叠加层

框架代码必须保持与具体基准测试无关。

​

基准测试层

这些能力应放在 qitos.benchmark.<family>：

• 数据集读取与拆分逻辑
• 稳定样本标识
• 基准测试运行时 prepare/finalize
• 基准测试专用 setup / postconfig
• 评估器桥接
• 评分器与失败分类法
• 基准测试原生产物（artifact，持久化的输出文件）载荷

凡是依赖 test_all.json、基准测试虚拟机/引导程序、上游评估器语义的内容，都应该放在这里。

​

配方层

这些能力应放在 qitos.recipes：

• 规范入门基线
• 基准测试基线
• 可复现对比方法

配方应该能被这些入口共同复用：

• qit bench
• 文档/教程
• 轻量示例
• 后续基准测试报告脚本

​

建议目录结构

新增基准测试家族时，建议至少包含：

qitos/benchmark/<family>/
├── __init__.py
├── adapter.py
├── runtime.py
├── evaluator.py
├── scorer.py
└── runner.py

如果该基准测试有规范基线，再新增：

qitos/recipes/benchmarks/<family>.py

​

适配器契约

适配器（adapter）负责：

• 数据集根路径解析
• 记录加载
• 拆分/子集过滤
• 稳定任务/样本标识
• 任务元数据归一化

每个任务都应携带足够元数据，支持：

• 基准测试原生评估
• qita 检查
• 可复现结果导出

最低要求至少包含：

• benchmark
• split
• 稳定样本标识，例如 task_id 或 example_id
• 运行时/评估器所需的基准测试原生元数据

​

运行时钩子契约

当基准测试需要这些能力时，请使用 BenchmarkRuntimeHook：

• 环境准备/收尾
• 智能体动作前的基准测试专用设置
• 引导元数据
• 清理策略

典型例子：

• OSWorld 的 qcow2/引导程序与控制器就绪
• 基准测试专用沙箱设置
• 服务预热或结束清理

除非逻辑确实能被多个基准测试家族复用，否则不要把它推回 DesktopEnv 或全局引擎。

​

评估器与评分器契约

BenchmarkEvaluator 用来产生基准测试原生载荷，例如：

• 上游评估器桥接结果
• 基准测试原生评分 JSON
• postconfig 执行结果

BenchmarkScorer 负责把这些结果映射回标准公开行：

• success
• stop_reason
• steps
• latency_seconds
• token_usage
• cost
• 基准测试专用元数据

对外公开结果仍然必须是 BenchmarkRunResult，不要再造第二套公开行模式。

​

标准结果行要求

每个基准测试运行最终都应输出统一公开行：

• task_id
• benchmark
• split
• prediction
• success
• stop_reason
• steps
• latency_seconds
• token_usage
• cost
• trace_run_dir
• run_spec_ref

基准测试原生的附加信息请放在 metadata，不要破坏共享结果契约。

​

追踪记录与 qita 兼容要求

新的基准测试家族必须保留：

• RunSpec
• ExperimentSpec
• 追踪记录（trace）目录兼容性
• qita 回放/导出/比较

如果新增基准测试原生产物，也要确保它仍能和这些共享产物一起工作：

• manifest.json
• events.jsonl
• steps.jsonl

原则：基准测试可以补充细节，但不能破坏共享运行契约。

​

命令行与注册表（registry）要求

要把基准测试家族变成正式入口，需要完成：

1. 在 qitos.benchmark 中导出家族
2. 在 qitos.benchmark.runner 中注册任务加载与内置运行器
3. 确保它能通过以下入口运行：
   • qit bench run
   • qit bench eval
   • qit bench replay
   • qit bench export

示例可以保留，但只能作为配方/运行器的薄包装。

​

文档同步清单

新增基准测试家族时，至少同步这些文档面：

• 基准测试概述
• 基准测试家族页面
• 命令行参考（如果基准测试名称或策略变了）
• 贡献者指南（如果引入了新的运行时/评估器模式）
• CHANGELOG.md
• README 的进展/动态（只要是用户可见能力）

这些更新属于实现的一部分，而不是事后补写。

​

当前仓库中的参考实现

可以直接参考这些规范结构：

• qitos.benchmark.desktop
• qitos.benchmark.osworld
• qitos.benchmark.gaia
• qitos.benchmark.tau_bench
• qitos.benchmark.cybench
• qitos.recipes.desktop.osworld_starter
• qitos.recipes.benchmarks.gaia
• qitos.recipes.benchmarks.tau_bench
• qitos.recipes.benchmarks.cybench

未来的新基准测试集成应尽量对齐这些形态。