# Agent 实验体系

中文 · [English](experiments.md)

## 目标

这个项目的目标，是让 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. 使用不可变镜像标签推广，并保留上一个标签用于回滚。

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