# Agent 循环实现

中文 · [English](agent-loop.md)

## 目标

K1412 循环把模型补全 API 转变为一个可追责的编码 Agent。它最核心的规则很简单：文字声明不能证明工作真的发生过。文件、命令、报告和测试都必须由本次运行中成功的工具事件提供证据。

当前事件元数据使用以下标识：

- 策略：`agent-loop-v3`；
- 调度器：`safe-parallel-v1`；
- 上下文策略：`recent-visible-v1`。

这些标识是实验契约的一部分，不是营销版本号。只要行为变化可能影响评测结果，就应更新对应标识。

## 运行状态机

```mermaid
stateDiagram-v2
    [*] --> BuildContext
    BuildContext --> RequestModel
    RequestModel --> ValidateCalls: 存在工具调用
    RequestModel --> CheckCompletion: 没有工具调用
    ValidateCalls --> Schedule
    Schedule --> Execute
    Execute --> RecordEvidence
    RecordEvidence --> RequestModel
    CheckCompletion --> RequestModel: 证据不足且仍有预算
    CheckCompletion --> Completed: 证据充分
    CheckCompletion --> Unverified: 证据不足且重试预算耗尽
    Completed --> [*]
    Unverified --> [*]
```

每次顶层运行都有唯一的 `run_id`。所有事件都包含用户、对话、单调递增序号、时间戳、事件类型和净化后的载荷。

## 上下文策略

`ContextPolicy.prepare` 会：

1. 只接受 system、developer、user 和 assistant 消息；
2. 从旧的助手消息中移除已渲染的 `<details type="tool_calls">` 块，避免把 UI 标记再次送入模型上下文；
3. 前置 K1412 系统契约；
4. 最多附加八条持久用户记忆作为上下文，并明确说明它们不是更高优先级的指令；
5. 从新到旧遍历可见消息，直到达到该模型的字符预算；
6. 记录被丢弃的旧消息数量。

这一策略有意保持简单且可检查。它目前不会总结旧的对话分支、检索语义化工作区上下文，也不会估算不同提供方的具体 token 切分方式。这些都是未来可以实验的方向。

## 模型契约

`ModelSpec` 是以下配置在服务端的唯一事实来源：

- 公开模型 ID 和提供方模型 ID；
- 提供方选择；
- 是否支持思考以及显示标签；
- 提供方支持时所使用的 reasoning effort；
- 最大输出 token 数；
- 最大循环迭代次数；
- 上下文字符预算。

Luna、Terra 和 Sol 是三个不同的本地模型，各自以布尔值表示是否支持思考；它们不是同一模型的三档推理强度。DeepSeek V4 Pro 使用 DeepSeek 提供方，启用思考，并设置 `reasoning_effort=max`。

如果提供方协议要求，Runtime 会在多轮工具调用之间保留 `reasoning_content`，但不会把隐藏推理发布为用户可见内容。

## 工具目录

工作区工具：

- 获取状态，列出、读取、搜索、写入和补丁修改文件；
- 执行前台命令；
- 检查 Git 状态与 diff；
- 启动、轮询和取消后台进程。

Runtime 状态工具：

- 更新每个对话的计划；
- 记住、回忆和遗忘持久用户记忆。

委派工具：

- 使用角色、任务和明确的写入策略启动一个有边界的子 Agent。

工具 schema 使用 `additionalProperties: false`，让格式错误的模型参数尽早失败。参数会在策略检查前完成规范化。内容正文和补丁正文不会写入公开运行事件的载荷。

## 基于意图的工具选择

根循环并不总是发送全部工具。轻量级请求分类器会判断任务是否涉及产物、执行、源码、报告、比较、进程、Git、记忆或委派。筛选后的工具目录可以降低模型进行工具决策的难度，同时保留核心工作区工具。

这只是启发式路由，不是权限控制。Gateway 仍然是实际的强制执行边界。

## 调度器

每次模型响应最多请求八个工具调用。调用按原始顺序解析，并划分为连续的组：

- 标为 `parallel_safe` 的工具并发执行；
- 写操作和其他非并行工具串行执行；
- 只读子 Agent 可以并行运行；
- 拥有写权限的子 Agent 串行执行；
- 子 Agent 不能再次委派。

Gateway 还会按用户串行化工作区写操作。第二层锁非常重要，因为多个 Runtime 请求或浏览器操作可能同时访问同一个工作区。

即使并行组中的任务完成顺序不同，调度器仍会保持结果的原始顺序。

## 防御性规范化与重试保护

循环会修复少量常见的模型格式错误，然后应用策略：

- 拒绝 `python3`、`bash`、`node` 这类没有参数的交互式命令；
- 拒绝把文档或数据文件当作可执行源码运行；
- 在写入完整 Python 文件之前拒绝语法无效的内容；
- 解码弱模型生成的、重复转义的源码布局换行；
- 跳过内容完全相同且此前成功的写入；
- 在内容变化前阻止重复执行完全相同的失败写入；
- 在发生写操作或实质不同的诊断前，阻止重复执行没有变化的失败命令；
- 对同一批次里的重复命令去重；
- 限制生成长度、迭代次数和工具批次大小。

在执行层，Bash 启用 `pipefail` 并返回真实退出码。前台工具默认最长运行 900 秒；后台进程具有明确的启动、轮询和取消生命周期。

## 基于证据的完成门禁

循环会从用户请求中推导所需证据。

| 请求类型 | 最低证据要求 |
| --- | --- |
| 具体产物 | 一次成功的文件写操作，以及之后一次成功的验证 |
| 执行/测试/分析 | 至少一次成功的执行或检查 |
| 源码请求 | 单独的可执行源文件 |
| 报告请求 | 在执行之后单独写入的报告 |
| 基准测试/比较报告 | 从成功执行输出中复制的精确数值测量 |

验证可以是之后的文件读取、Git diff/status、命令执行或后台进程轮询。失败的命令会一直保持未解决状态，直到后续执行成功。

如果模型过早尝试完成任务，Runtime 会发出 `completion.rejected`，向模型返回聚焦的恢复指令，并继续循环。经过多次被拒绝的完成检查或迭代次数耗尽后，Runtime 会返回明确的未完成结果，而不是把未经验证的声明包装成成功。

## 委派

根 Agent 可以委派一个边界明确的独立任务。子 Agent 会获得：

- 一个角色和精确任务；
- 最多八次迭代的缩减预算；
- 不包含委派工具；
- 默认仅有只读工具，除非明确请求了写权限。

子 Agent 事件与根运行共用同一事件流，但 `depth` 会增加。当前实现是在单个 Runtime 进程内递归执行，不是分布式队列，也不是持久自治 worker。

## 记忆与计划

持久记忆按用户 ID 隔离。当前优先返回最近记忆，并支持可选的、不区分大小写的子字符串过滤。计划按用户和对话隔离，并且最多只允许一个 `in_progress` 项。

记忆很有价值，但系统有意保持保守：不会从每次对话自动提取事实，也暂未实现向量检索、置信度评分、过期和冲突解决。

## 运行事件模型

重要事件类型包括：

- `run.created`、`context.built`、`run.completed`、`run.failed`、`run.cancelled`；
- `model.requested`、`model.responded`；
- `tool.started`、`tool.completed`、`tool.batch_limited`；
- `completion.rejected`、`completion.unverified`；
- `agent.spawned`、`agent.completed`。

事件流目前用于驱动 UI 工具详情块，也是未来实现回放、评测、成本分析和 A/B 分组的基础。事件仅存储公开参数和简短摘要，不存储凭据、完整写入正文或隐藏推理。

## 已知限制

- 上下文压缩会直接丢弃旧消息，而不是总结。
- 记忆检索基于文本而不是语义。
- 工具意图分类器基于正则表达式。
- 调度器只并行连续的安全调用，且没有资源成本模型。
- Runtime 重启后，子 Agent 不会持久存在。
- 尚未实现实验分组和聚合仪表盘。
- 提供方返回的 token 统计会被保留，但尚未转换成统一成本模型。

这些都是有意保留的实验方向，记录在[实验方法](experiments.zh-CN.md)中。