agent/research/evaluation/k1412-agent-evaluation-v1.md

K1412 Agent Evaluation v1

status: design-ready reviewed_at: 2026-07-27 target_repository: https://git.k1412.top/wuyang/zk-data-agent.git target_commit: e2e7a7b reference_system: https://zero.k1412.top/

1. 要回答的问题

这套评测不回答抽象的“哪个 Agent 更强”，而回答：

对固定模型、任务、工作区和预算，某个 Agent Loop 变体是否改善了指定行为， 为什么改善或退化，以及证据是否足以推广到生产。

一次评测只改变一个主要行为假设，例如完成门禁、上下文策略、工具调度、记忆召回或模型 路由。平台、任务输入、模型、工作区镜像和判分器没有记录的变化，都会让对比失效。

2. 当前系统已经具备什么

zk-data-agent 已有一条扎实的评测底座：

• 每次运行写入 run.created，记录 Agent Loop、调度器和上下文策略版本；
• 模型请求、工具开始/完成、完成拒绝和最终状态都有顺序化事件；
• 每个真实模型任务运行在唯一、无网络、可销毁的 Docker 工作区；
• 文件、代码、执行和报告任务需要实际工具证据才能完成；
• 单元测试、Docker 集成、伪模型 E2E、真实模型评测和生产冒烟测试已经分层；
• scripts/eval-live-work.py 能记录时间、Token、工具事件和最终文件列表。

这些能力意味着不需要另起一个评测平台。应该把现有 live eval 从“单次运行脚本”提升为 “版本化任务集 + 判分器 + 对照实验 runner”。

3. 当前缺口

缺口	当前表现	v1 要求
任务集	一个默认 prompt，空工作区	版本化任务契约、夹具和风险标签
判分	事件计数与文件列表	任务专属确定性 validator
对照	单变体单次运行	同任务、同模型、同预算的配对 A/B
随机性	没有重复策略	smoke 1 次、候选 3 次、发布 5 次以上
可复现信息	只记录三项策略版本	增加 commit、prompt/tool hash、镜像 digest、模型与预算
失败定位	保留事件但没有统一分类	固定 failure stage taxonomy
假完成	Loop 内部有门禁	独立 validator 再判断 Agent 是否误报完成
聚合决策	没有 gain/regression 对照	同时报新增成功和原成功退化
人的价值	没有真实任务复盘	小比例盲审和 Zero 式行动性检查

4. Zero 带来的约束

每个实验先写一张问题卡，而不是先跑 leaderboard：

1. 问题：要改善的真实行为是什么？
2. 初始判断：为什么认为这个改动有帮助？
3. 事实、推断、限制：三者分开。
4. 最多三个未知项：哪些信息会改变方向？
5. 完成标准：什么结果足以推广、继续或拒绝？
6. 停止条件：成本、安全或回归到什么程度立即停止？
7. 复盘：实际发生了什么，下次怎样更快？

同时只允许一个评测实验处于执行状态。评测不是为了积累更多图表，而是产生一个版本决策。

5. 评测对象

5.1 Task Contract

每个任务必须保存：

task_id / version
user_goal
initial_workspace_fixture
allowed_and_forbidden_effects
observable_completion
deterministic_validators
required_trace_evidence
budgets
risk_tags
runner_requirements

任务 prompt 不是 ground truth。真正的完成条件由工作区最终状态、命令结果和副作用验证器定义。 机器可读任务集提供 live-eval-current-v1 预算档，复刻当前 live eval 的模型迭代、 输出、上下文、工具超时和容器资源限制；当前脚本没有端到端超时，这是 runner 落地时必须 补齐并写入 manifest 的已知缺口。

5.2 Run Manifest

每次运行除现有事件外，还要固定：

experiment_id / variant_id
task_id / task_version / repetition
source_commit
strategy / scheduler / context policy
system_prompt_hash / tool_schema_hash
workspace_image_digest / fixture_hash
public_model_id / provider_model_id
thinking and generation settings
iteration / token / time / tool budgets
validator_version / judge_version

没有这些信息的两次运行，只能做观察，不能做严格对比。

5.3 Result Record

runner 最终输出一条 JSONL：

{
  "task_id": "artifact-script-report",
  "task_version": "1",
  "variant_id": "agent-loop-v3",
  "model_id": "deepseek-v4-pro",
  "repetition": 0,
  "run_id": "...",
  "status": "completed",
  "agent_claimed_complete": true,
  "validator": {"passed": true, "checks": []},
  "failure_stage": null,
  "safety_violations": [],
  "metrics": {
    "elapsed_seconds": 42.1,
    "total_tokens": 12000,
    "tool_calls": 8,
    "failed_tool_calls": 1,
    "recovered_failures": 1,
    "unresolved_tool_failures": 0
  }
}

基础设施错误必须与 Agent 失败分开，不能偷偷计入或排除。

6. 评测层次

Layer	目的	是否调用真实模型	运行节奏
L0 单元/策略	参数规范化、证据门禁、权限、事件	否	每次提交
L1 Docker 集成	工作区隔离、命令、文件、重启	否	每次提交
L2 确定性 E2E	Web、Runtime、Gateway、交付	伪模型	每次发布候选
L3 行为任务集	真实 Agent 任务成功与过程	是	变体候选
L4 压力与安全	故障、冲突、注入、长任务	是	发布前
L5 生产冒烟/真实价值	公网链路与少量真实任务	是	部署后/周期抽样

真实模型评测不能替代 L0-L2；高层成功也不能掩盖确定性层的回归。

7. v1 任务家族

第一批任务契约见 data/evaluation/k1412-agent-eval-task-contracts-v1.json，覆盖：

• 产物创建与验证；
• 代码和报告的证据一致性；
• 带测试夹具的仓库修复；
• 工具失败后的恢复；
• 信息不足时的澄清和行动边界；
• 长上下文中的旧约束保持；
• 冲突或过期记忆；
• 不可信仓库内容与路径隔离；
• 只读并行调度；
• 有边界的子 Agent 委派。

任务不能只来自公开 benchmark。至少三分之一应来自匿名化的真实失败和用户任务，并保留 “曾经成功、容易被新策略弄坏”的回归保护集。

8. 判分顺序

1. 确定性 validator：测试、文件内容、schema、退出码、HTTP、Git diff 或副作用检查。
2. 轨迹规则：未解决失败、重复调用、越权尝试、证据门禁和恢复行为。
3. 盲评 rubric：只有无法自动判断的帮助性、清晰度和交互质量才使用人工或独立模型。
4. 用户价值抽样：结果是否减少未知项并产生可执行下一步。

Agent 自己的最终陈述不能给自己判分。LLM-as-a-judge 也不能作为发布的唯一门禁。

9. 必报指标

结果

• strict task success；
• validator pass rate；
• false completion rate：声称完成但独立 validator 失败；
• partial completion 只做诊断，不并入 strict success；
• human actionability score，仅用于抽样任务。

变化

配对比较必须拆开：

• gain：baseline 失败，variant 成功；
• regression：baseline 成功，variant 失败；
• both pass；
• both fail；
• net gain = gains - regressions。

平均成功率可能隐藏大量回归，不能只报告净提升。 成功率和假完成率同时报告原始计数、样本量和 Wilson 95% 区间；配对变化报告 gain/regression 的双侧精确 McNemar 检验。统计结果用于表达不确定性，不能越过安全和 假完成门禁。

过程

• 未解决工具失败率和失败恢复率；
• completion rejection 次数；
• 重复/被策略拦截调用；
• 计划更新、子 Agent 数和安全并行比例；
• failure stage 分布。

统一失败阶段：

understanding / context / planning / tool-selection / tool-arguments
execution / state-memory / verification / synthesis / safety-policy
provider / infrastructure

效率

• 端到端 p50/p95；
• 模型调用、总 Token、推理 Token、缓存 Token；
• 工具调用、工具执行时间和并发；
• API 费用、本地推理时间和可获得时的电费。

10. 运行协议

1. 预注册问题、假设、变体、固定变量、指标和停止条件。
2. 先跑 L0-L2；任一确定性门禁失败则停止真实模型评测。
3. smoke：每个核心任务一次，确认 runner 和 validator 正常。
4. candidate：任务和模型分层后至少三次重复，baseline 与 variant 配对。
5. release：扩大真实失败集和重复次数，顺序随机化。
6. 独立运行 validator，再生成 Result Record。
7. 用 tools/evaluation/score_agent_runs.py 聚合。
8. 人工检查 gains、regressions、both-fail 各若干条轨迹。
9. 写出推广、继续或拒绝决定，并记录仍未知的边界。

11. 决策门禁

立即拒绝：

• 出现新的工作区逃逸、越权副作用或跨用户访问；
• false completion 增加；
• validator、任务输入或预算不一致；
• 主要提升只能由模型、上下文或夹具的未记录变化解释。

可推广候选：

• 没有安全和假完成回归；
• gains 明确多于 regressions；
• strict success 改善，或者在成功率非劣时显著降低延迟/成本；
• 关键任务家族没有被平均值掩盖的退化；
• 失败轨迹能解释改动为什么有效。

统计区间、原始计数和样本量必须和百分比一起报告。小样本结果保持 candidate，不写成 “已证明更强”。

12. 对 zk-data-agent 的最小改造顺序

1. 从 eval-live-work.py 抽出可复用 LiveEvalRunner。
2. 支持任务 JSON、工作区夹具和任务专属 validator。
3. 导出完整 Result Record 和经过净化的事件 JSONL。
4. 增加重复、模型矩阵、baseline/variant 和随机顺序。
5. 增加故障注入、多轮消息、记忆和委派 runner。
6. 最后才做实验看板；看板读取相同 JSONL，不成为新的事实源。

13. 最新论文线索

以下只是本次增量采集的摘要级线索，尚未全文审计：

• The Regression Tax：提示必须把净提升拆成 gains 和 regressions。
• Do Agent Benchmarks Measure Capability?：提示协议有效性 本身需要检查。
• AgentDebugX：强调失败可观测、归因和恢复。
• Reason Less, Verify More：与当前确定性证据门禁方向一致。
• Baselines Before Architecture：提醒架构结论必须建立在 可比 baseline 上。

这些论文应进入后续全文证据审计，但方案不依赖它们的标题成立。

14. 非目标

• 不把所有指标压成单一总分；
• 不用一两个漂亮 demo 代替任务集；
• 不让 Agent 或同一模型独立给自己判分；
• 不把 provider 故障算成 Agent 能力失败；
• 不先做可视化大屏；
• 不因平均分提高而忽略原本成功任务的退化。