zk-data-agent/docs/experiments.zh-CN.md

Agent 实验体系

中文 · English

目标

这个项目的目标，是让 Agent 循环的迭代成本更低、过程可观察、结果可回滚。一次实验应当只改变一个行为假设，同时保持鉴权、工作区隔离和交付基础设施不变。

公开门户 https://agent.k1412.top/doc/#experiments 中包含一个整理过的实验看板。这份 Markdown 文档定义长期有效的流程，门户目录只是展示层。

实验单元

每个实验都应定义：

1. 问题——希望改善的行为。
2. 假设——具体的循环改动和预期方向。
3. 变体标识——记录在 run.created 中的稳定字符串。
4. 任务集——固定提示词、初始工作区夹具和模型档位。
5. 指标——成功率、质量、延迟、模型/工具使用量和回归。
6. 安全约束——绝不能变差的行为。
7. 决策规则——推广、继续迭代或拒绝。
8. 产物——代码提交、配置、原始事件导出和报告。

不要比较使用不同任务输入的变体，也不要在没有记录的情况下更换模型、提示词、上下文预算或工作区夹具。

推荐指标

主要指标：

• 通过明确证据检查的任务成功率；
• 已验证交付物比例；
• 未解决工具失败率；
• 人工或量表质量评分。

效率指标：

• 端到端延迟；
• 模型调用与迭代次数；
• 可用时记录提示和补全 token 数；
• 工具调用次数；
• 重复或被策略拦截的调用；
• 子 Agent 数量与并发度；
• 估算的模型提供方费用与电费。

可靠性与安全指标：

• 是否正确拒绝了不完整的完成检查点；
• 假成功率；
• 工作区逃逸或跨用户访问失败；
• 是否错误地把非零命令退出码记录为成功；
• 身份/鉴权失败；
• Runtime 或工作区重启后的恢复能力。

评测层次

单元与策略测试

快速、确定性的测试覆盖解析、工具规范化、证据门禁、鉴权、上下文选择、事件持久化和提供方响应规范化。

真实 Docker 集成

集成测试创建两个一次性用户，并验证：

• 容器、网络和数据卷彼此独立；
• 工作区路径受到约束；
• 文件浏览、下载和归档行为；
• 根文件系统只读且 capabilities 已移除；
• Python 虚拟环境可以持久保存；
• 前台和后台命令都能通过 pipefail 返回真实退出码。

一次性全栈 E2E

E2E 环境使用确定性的伪模型提供方，覆盖：

• 注册与管理员审批；
• 精确的四模型公开目录；
• 自定义 Agent 循环；
• 有证据支持的文件生成；
• 文件交付；
• 每用户隔离。

真实模型评测

scripts/eval-live-work.py 会让真实模型在一个唯一的一次性工作区中运行，并记录延迟、token 使用、事件、工具数量和输出文件。真实模型评测用于补充确定性测试，不能替代它们。

生产冒烟测试

每次部署后，使用低影响的已鉴权任务，确认公网 Web、Runtime、Gateway、远程工作区主机和文件获取都正常。验证后只删除这次冒烟测试产生的临时文件。

当前基线

ID	领域	状态	结果
loop-v3-evidence	完成策略	生产基线	产物必须先发生写操作，再经过验证；报告和基准测试要求更强证据。
safe-parallel-v1	调度器	生产基线	连续只读调用和只读委派可以并发，写操作保持串行。
recent-visible-v1	上下文	生产基线	在每模型字符预算内保留最近可见消息，并附加最多八条记忆。
workspace-python-v1	执行	已验证	持久 .venv、持久用户缓存、900 秒工具上限，以及真实的管道退出码。
fresh-gateway-identity-v1	鉴权	已验证	Runtime 为每次工具请求重新签发已验证身份，使长任务不受原始令牌过期影响。

初始待办

1. 具有冲突和过期策略的语义或混合记忆检索。
2. 结构化旧上下文总结，并通过回放比较效果。
3. 基于依赖的工具 DAG 调度，而不只是连续安全组。
4. 子 Agent 结果契约与预算分配。
5. 按运行记录实验分组，并提供聚合比较 API。
6. 统一核算本地电费与付费提供方 token 成本。
7. 工作区配额、出站策略、滥用监控和备份演练。

添加实验

1. 把假设和指标加入本文，或新增专门的 docs/experiments/<id>.md。
2. 将实验加入 docs/site/experiments.json，用于公开看板。
3. 在 run.created 中新增或更新相关策略、调度器或上下文标识。
4. 在真实模型运行前先添加确定性测试。
5. 执行标准验证并保存报告。
6. 使用不可变镜像标签推广，并保留上一个标签用于回滚。

实验产物中绝不能放入提供方密钥、私有事件载荷、用户标识、真实用户提示词或内部凭据。