Refresh papers and define Agent evaluation
This commit is contained in:
wuyang
@@ -0,0 +1,17 @@
|
||||
# Agent Evaluation
|
||||
|
||||
这里研究如何评估真实 Agent 系统，而不是只收集 benchmark 名称。
|
||||
|
||||
## Current Work
|
||||
|
||||
- [K1412 Agent Evaluation v1](k1412-agent-evaluation-v1.md): 基于 `zk-data-agent`
|
||||
的运行事件、隔离工作区和证据门禁，并结合 Zero 的问题闭环设计评测体系。
|
||||
- [Task contracts](../../data/evaluation/k1412-agent-eval-task-contracts-v1.json):
|
||||
第一批机器可读任务契约，明确当前 runner 能力和缺口。
|
||||
- [Run scorer](../../tools/evaluation/score_agent_runs.py): 汇总结果、假完成、收益、
|
||||
回归、延迟、Token、工具失败和安全违规。
|
||||
|
||||
## Evidence Boundary
|
||||
|
||||
当前方案的工程判断来自实际代码和文档检查。2026-07-09 至 2026-07-27 的新论文只做了
|
||||
标题和摘要级筛选，尚未构成全文证据审计。
|
||||
@@ -0,0 +1,286 @@
|
||||
# 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 能力失败；
|
||||
- 不先做可视化大屏；
|
||||
- 不因平均分提高而忽略原本成功任务的退化。
|
||||
Reference in New Issue
Block a user