一条看似简单的请求
假设用户说：
修复下载命令在服务器返回 429 时立即失败的问题，遵循仓库现有重试模式，并补测试。
这句话没有给出文件路径、框架或测试命令。可信的 Agent 不应直接猜代码，而要逐步降低不确定性。
flowchart TD
P["自然语言目标"] --> I["加载指令<br/>AGENTS.md / config"]
I --> X["探索仓库<br/>rg / read / git"]
X --> H["形成局部假设<br/>重试入口 + 现有模式"]
H --> C["读取最小必要上下文"]
C --> D{"证据足够？"}
D -- 否 --> X
D -- 是 --> A["生成结构化 Patch"]
A --> T["运行目标测试"]
T --> R{"通过？"}
R -- 否 --> X
R -- 是 --> V["检查 diff 与更宽验证"]
V --> F["报告结果与边界"]
阶段一：把“目标”变成约束
Agent 首先应抽取：
- 行为：429 不应立即失败；
- 一致性：复用仓库已有重试模式；
- 修改边界：下载命令及其测试；
- 完成标准：新增回归测试，并通过相关检查；
- 未知项：代码位置、重试策略、测试框架。
这不是隐藏的“神奇规划器”必然生成的一张完整计划。公开源码能确认的是：用户输入、项目指令、工具定义和历史会进入模型请求；模型随后逐步决定行动。
阶段二：先找地图，再读细节
典型探索会从低成本查询开始：
rg -n "429|retry|backoff" src tests
rg -n "download" src模型可能先找到一个通用 retryWithBackoff，再定位下载路径的错误处理。此时它应该读取相邻实现、调用者和测试，而不是把整个仓库塞进 Context。
公开证据上的分析 这是基于 Codex 工具循环的教学示例，不是官方仓库中固定的搜索策略。模型会随任务、配置和仓库内容改变具体命令。
阶段三：请求如何被组装
在正式采样前，build_prompt 把以下要素组合起来：
- 当前 Context 中的输入项；
- 模型可见的工具定义；
- 基础指令；
- 是否支持并行工具；
- 可选输出 schema。
模型需要足够信息做下一步，但无限加载仓库既昂贵又会稀释重点。
先用搜索定位，再读取相关片段；每次工具结果进入历史，动态补足证据。
按需检索比一次性注入更适合不断变化的本地仓库。
ContextManager 维护历史；build_prompt 取面向模型的历史和工具规格。
搜索词错误会遗漏关键代码；上下文压缩也可能损失细节，需要重新读取。
阶段四：从工具调用到真实补丁
模型不会直接写磁盘。它输出一个符合工具 schema 的调用，Runtime 经过 router 和 registry 选择 apply_patch handler。Handler 解析 patch、校验路径与上下文，再执行文件修改。
sequenceDiagram participant M as Model participant S as Stream handler participant R as Tool router participant O as Orchestrator participant P as apply_patch participant F as Filesystem M->>S: function_call(apply_patch, patch) S->>R: ToolCall R->>O: ToolInvocation O->>O: approval + sandbox decision O->>P: execute P->>P: parse + verify P->>F: write selected files F-->>P: result P-->>M: structured tool output
一个教学示意 patch 可能是：
*** Update File: src/download.ts
@@
- if (!response.ok) throw new DownloadError(response.status);
+ if (response.status === 429) return retryWithBackoff(request, response);
+ if (!response.ok) throw new DownloadError(response.status);阶段五：验证不是最后补一句
合理的验证顺序由窄到宽：
- 运行新增或最相关测试；
- 失败则读取完整错误并修正；
- 运行所属模块测试；
- 视风险运行 lint、类型检查或完整构建；
- 检查
git diff，确认没有意外改动。
每一步仍是 Agent Loop，而不是独立的“测试阶段”。测试失败会作为新的观察送回模型。
阶段六：报告已证实与未证实
最终消息至少回答：
- 改了哪些文件和行为；
- 运行了哪些验证，结果如何；
- 哪些环境没有运行；
- 是否存在待用户决定的取舍。
接下来深入这条链里最容易被低估的部分：Context 引擎。