agent/experiments/agent-evaluation/2026-07-27-k1412-agent-evaluation-design.md

实验：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

验证

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 变体。
• 最新论文仅作为摘要级发现信号，不是全文证据审计。