# 实验：K1412 Agent Evaluation v1 设计

status: completed

## 问题

`zk-data-agent` 应该怎样比较 Agent Loop 的改动，才能支持生产版本决策、解释回归，而不是
再生成一个排行榜？

## 环境

- date: 2026-07-27
- 目标仓库：`https://git.k1412.top/wuyang/zk-data-agent.git`
- 检查 commit：`e2e7a7b`
- 产品参考：`https://zero.k1412.top/`
- 真实模型运行：无
- 目标仓库代码改动：无

## 已确认事实

- 目标系统保存版本化运行事件和完整工具生命周期事件。
- 已有确定性测试、隔离 Docker 集成、伪 provider E2E 和真实模型脚本。
- live 脚本目前只在空工作区运行一个 prompt，并报告事件、用量和文件。
- 尚不支持任务夹具、独立 validator、重复试验和变体对照。

## 设计假设

保留现有 runtime，增加版本化任务契约、独立 validator、配对 A/B、统计区间、失败阶段标签
以及显式 gain/regression 统计，就能形成可支持版本决策的评测体系。

## 产出

- `research/evaluation/k1412-agent-evaluation-v1.md`
- `data/evaluation/k1412-agent-eval-task-contracts-v1.json`
- `tools/evaluation/score_agent_runs.py`
- `tools/evaluation/test_score_agent_runs.py`

## 验证

```text
python3 -m unittest tools.evaluation.test_score_agent_runs
jq empty data/evaluation/k1412-agent-eval-task-contracts-v1.json
python3 -m py_compile tools/evaluation/score_agent_runs.py
```

全部检查通过。

## 决定

将当前方案作为实现契约。下一步代码改动应进入 `zk-data-agent`：抽取可复用 runner，增加
fixture 和 validator 加载，再输出约定的 JSONL 结果。暂不做 dashboard。

## 边界

- 不声称任务集已经全部可运行。
- 尚未 benchmark 任何模型或 Agent Loop 变体。
- 最新论文仅作为摘要级发现信号，不是全文证据审计。