# 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

每个任务必须保存：

```text
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

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

```text
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：

```json
{
  "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 分布。

统一失败阶段：

```text
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](https://arxiv.org/abs/2607.22520)：提示必须把净提升拆成 gains
  和 regressions。
- [Do Agent Benchmarks Measure Capability?](https://arxiv.org/abs/2607.22368)：提示协议有效性
  本身需要检查。
- [AgentDebugX](https://arxiv.org/abs/2607.18754)：强调失败可观测、归因和恢复。
- [Reason Less, Verify More](https://arxiv.org/abs/2607.07405)：与当前确定性证据门禁方向一致。
- [Baselines Before Architecture](https://arxiv.org/abs/2607.13085)：提醒架构结论必须建立在
  可比 baseline 上。

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

## 14. 非目标

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