一键切换待测 Agent
无需修改框架或任务代码：安装插件并在配置中切换一行，同一份 dataset 即可跨配置运行。
让 Agent 自主执行评测
安装 CLI 和 skill，支持 coding agent 设计、转换 benchmark 并端到端完成评测。
在 Hub 上共享与复用
在 ageval Hub 上共享或复用 dataset、插件和 Agent 包，并归档可追溯的评测结果。
// 01The Problem
评测不能只比模型。
真正执行任务的是 Model + Harness。
01 / MODEL
仅替换模型标识
固定提示词、工具和调用流程，仅将模型从 A 换成 B 并记录单个分数。
02 / HARNESS
实际运行的是完整 Agent
决定任务表现的是模型与外层 harness（交互循环、工具调用与执行控制）的组合。
03 / DRIFT
更换 harness 或环境，表现随之改变
同一模型接入不同 harness 或运行在不同环境中，任务通过率与调用开销均会发生变化。
04 / RECORD
缺少配置锁定的分数难以对比
仅报告模型名称无法复现实验条件：必须同时记录绑定的 harness、模型参数与运行环境。
SOLUTION → ageval 通过声明式插件组合环境与待测 Agent，在运行前锁定完整配置（lock），保障对照实验可复现、分数可对比
// 02Positioning
固定运行时基座，用插件组合组件。
ageval Core 管理固定的评测流水线：lock → environment → run → evaluate → record。执行环境与 Agent 执行器均通过插件槽接入，无需修改基座或任务代码即可替换。
// INPUTS 用户输入、dataset 与 profiles 从外部传入。dataset 定义评测任务与评分标准；环境与角色配置写在 profiles.yaml 中，与任务逻辑解耦。
// 03Environment
切换运行环境，无需重写 dataset。
同一份任务可在本机、Docker 容器、云沙箱或远程主机上运行。环境通过插件接入，在 profiles.yaml 中一行切换。
ENV · LOCAL
本机目录
真实文件系统，子进程直接执行。
开箱即用
ENV · DOCKER
本机容器
容器化隔离；参考材料（gold）在评分阶段才上传至评分环境。
开箱即用
ENV · E2B / SSH / DAYTONA
云沙箱与远程环境
本机统一编排，安装对应 SDK 并配置凭据后即可远程执行。
需要凭据
// 04Auto
让 Agent 自主完成评测。
安装 CLI 和 skill 后，coding agent 可设计、转换 benchmark 并自动执行评测。内置 skill 支持按需加载。
| Skill | 功能说明 |
|---|---|
ageval-platform | 仓库架构总览：职责边界、配置锁定与评分规范。 |
ageval-cli | 运行 lock / run / campaign，查阅与上传评测结果。 |
ageval-config-package | 编写与转换 dataset：ageval.yaml、task.yaml、profiles.yaml。 |
ageval-sdk-harness | 编写任务脚本：AgentSession、工具与产物发布。 |
ageval-plugin | 开发插件：接入执行环境或 Agent 执行器。 |
// 05Plugin
声明式插件组合环境与 Agent。
更换待测 Agent 或环境无需修改框架源码：安装插件并在 profiles.yaml 中切换绑定。
ENV
环境插件
支持本机 / Docker / 云沙箱 / 远程 SSH。实现统一环境接口即可扩展新后端。
AGENT
Agent 执行器插件
默认经 ACP 接入（pi / Codex / Claude Code / OpenCode）；nooa / dsh / miniswe 通过同一插件槽接入。
LOCK
运行前静态校验
在 lock 阶段校验插件能力依赖、模型参数契约与凭据引用，不兼容配置在运行前直接终止。
EXAMPLE · DSH
以插件方式接入 DeepSeek Harness，无需改动 ageval 源码。
dsh 采用不同于 ACP 的通信机制，同样通过 executor 插件槽接入：安装对应 extra 并在 profiles 中将 executor 设为 dsh，同一份任务即可原样运行。缺少 DEEPSEEK_API_KEY 时会在 lock / preflight 阶段直接报错终止。
# 安装 dsh 插件依赖 uv tool install 'ageval-cli[dsh]' # 将 executor 切换为 dsh，任务与 dataset 无需改动 ageval run <dataset> --task <task-id> \ --profiles profiles.dsh.yaml # executor: dsh
// 06FAQ
常见问题
如何切换待评测的 Agent？
待测对象是由模型与 harness 构成的完整 Agent（如 pi、Codex、Claude Code、dsh 等）。框架与 dataset 均无需改动：安装对应插件并在 profiles.yaml 中切换绑定，同一份任务即可直接运行。
内置 Agent 包可直接通过 --agent pi（配合可选 --model）调用，无需预先安装；自定义 Agent 包先执行 ageval agent install，再通过 --agent org/name@version 绑定。
安装 CLI 后，如何让本机 Agent 自己跑评测？
执行 uv tool install ageval-cli 与 npx skills add ZJU-REAL/ageval。Skill 会指导 coding agent 调用 lock / run 命令及编写 dataset，从而自主设计或转换 benchmark 并完成评测。
实际运行 coding agent 需要本机具备对应的 ACP 入口与凭据；仅执行 ageval lock 校验配置时则不需要。缺少依赖或凭据时会在预检阶段直接报错并给出安装提示。
如何运行 Hub 上的 dataset 并分享评测结果？
使用 ageval registry list 查看可见的 dataset，再执行 ageval run <org>/<name>@<version>（或指定本地 dataset 目录）。默认 profiles 使用 environment: docker，需确保本机 Docker 引擎已启动。
dataset、插件、Agent 包与评测结果均可发布到 ageval Hub 供他人复现与对比；本机也可通过 ageval view 打开本地结果，或生成 /s/{token} 只读快照链接。
编写一份 dataset 需要准备哪些文件？
评测数据集的交付单位是 dataset：根目录包含 ageval.yaml，每个任务位于 tasks/<id>/ 下，包含 task.yaml、执行脚本 run.py、评分脚本 evaluator.py、输入数据 data/ 与参考材料 evaluation/。环境与角色配置写在外部 profiles.yaml 中。
任务脚本负责业务交互循环与评分准则；配置锁定、环境生命周期、结果绑定与 finally 清理均由 ageval Core 管理。Python SDK 不决定 PASS，也不持有宿主明文凭据。
如何开发自定义环境或 Agent 插件？
通过编写 ageval.plugin/1 插件扩展环境或 executor 独占槽，无需 fork 框架源码。插件声明自身提供的槽位及通过 inject 依赖的服务能力，安装后即可在 profiles.yaml 中选用。
若插件声明的能力依赖或模型契约不满足要求，ageval lock 会在运行前直接拦截。
切换本机、Docker 或云沙箱需要重写 dataset 吗？参考材料会暴露给待测 Agent 吗？
无需重写 dataset。在 profiles.yaml 中将 environment 切换为 local、docker 或 e2b / ssh / daytona，同一份任务即可在不同后端运行。
参考材料（gold）存放在 tasks/<id>/evaluation/ 下，在 run 阶段不会挂载到待测 Agent 的工作区，仅在 solver 封存后的 evaluate 阶段上传至评分环境。