编码 Agent 的规划-执行-验证循环
一句话定义
编码 Agent 是「LLM + 工具 + 循环」：模型在观察-规划-行动-验证的闭环中自主读写文件、执行命令、运行测试，正确用法是给结构化派工单并守住验收与止损两条线。
为什么重要
Agent 把 AI 的介入深度推到顶点：它能独立完成端到端任务，也能在无人看管时把仓库改得一团糟。理解其循环机制，才能解释它的三个典型行为——为什么它有时反复修同一处（验证信号缺失）、为什么它越干越偏（错误在循环中累积）、为什么派工单质量决定一切（循环的起点是任务表述）。本库把 Agent 用法放在工作流之上：spec（kp-011）与审查（kp-013）在 Agent 场景不是被取代，而是变成派工单与验收器。
前置知识
kp-004（注意力预算——Agent 每轮循环都消耗预算）、kp-011（spec 驱动——派工单的核心）。
核心概念
- 循环结构：观察（读文件/命令输出）→ 规划（更新任务清单）→ 行动（编辑/执行）→ 验证（跑测试/lint）→ 重复直至达成目标或触发停止条件。
- 工具面：读写文件、执行 shell 命令、搜索（grep/语义）、测试运行器；部分 Agent 支持浏览器与网络。
- 派工单（任务书）：目标、验收命令、禁区、回报格式、预算上限——五要素齐全的 Agent 任务成功率显著更高。
- 反馈信号：Agent 质量依赖验证器的客观性；没有测试/类型检查的仓库，Agent 等于闭眼开车。
派工单模板：
目标：<一句话用户可见结果>
验收：<可执行命令，如 pytest tests/test_x.py 全绿 + pnpm lint 通过>
禁区：<路径/操作清单；需要询问的操作>
预算：<最多 N 轮尝试 / M 分钟；超出即停下汇报>
回报：<改动文件清单 + 验收输出摘录 + 未解决问题>原理与机制
循环的放大效应是理解 Agent 的钥匙：每一轮的错误都可能进入下一轮的观察输入并被「合理化」，错误因此复利累积——这解释了跑偏（kp-020）为何比单轮幻觉更危险。对策都落在「增强验证信号」上：客观验收命令让每轮有真值反馈；禁区让错误方向在规划层就被排除；预算上限把复利失控行程截断。此外 Agent 的每轮观察都消耗注意力预算（kp-004），长循环后期对最初任务的理解会衰减——这正是要写派工单并让它随每轮可见的原因。
实例或案例
操作步骤（第一次正经派单）：
- 选一个有测试覆盖的小任务，按模板写派工单，预算先给小值（如 10 轮）。
- 用只读模式（kp-018）让它先产出计划：改哪些文件、每步怎么验证。
- 人审计划（重点：禁区遵守、验证步骤真实存在），再放行写权限。
- 执行中不打断；结束后按回报格式核对：验收命令自己重跑一遍。
- 按 kp-013 审查 diff，按 kp-016 收尾提交。
- 复盘：派工单哪里含糊导致弯路，更新模板。
排错清单：
- Agent 卡在跑不通过的命令 → 检查验收命令是否在它环境里可执行（依赖、路径）。
- 改动越出禁区 → 立即停止，回滚越界文件，禁区写法从「不要动 X」改为「仅允许修改 A/B/C」。
- 反复修同一处 → 验证信号缺失或错误信号误导；人工介入复现一次，把结论写进任务书。
- 顺利完成但实现诡异 → 仍是人审责任，Agent 产出一律走 kp-013 流程。
公式或模型
本节不适用：成功率无通用公式，可用「派单一次通过率」做团队自观测。
图示
┌──────────────────────────────┐
▼ │
[观察] 文件/命令输出 ─▶ [规划] 更新清单 ─▶ [行动] 编辑/执行 ─▶ [验证] 测试/lint
│
达标/预算尽/禁区触发 ──┘ 停止并回报直观类比
派 Agent 像给能干的实习生派活：活要说清（派工单）、材料要给全（上下文包）、验收要客观（测试）、权限要分级（kp-018）、限时限量（预算）——然后放手，但验收永远自己做。
常见误区
- 「Agent 能自治所以不用管」：自主性放大的是你任务表述的质量，不是替代它。
- 给模糊目标让它「看着办」：循环会在错误方向上高效奔跑。
- 信任完成汇报不重跑验收：回报格式存在的意义就是让你重跑。
与其他知识点的关系
kp-018 约束循环中「行动」的权限面；kp-020 处理循环失控；kp-019 是多循环的编排。
自测题
要点：观察→规划→行动→验证；每轮错误进入下轮观察被合理化，复利放大。
要点：目标、验收命令、禁区、预算上限、回报格式。
- Agent 循环的四步是什么？错误如何在循环中累积？
- 派工单五要素？
延伸阅读
《ReAct- Synergizing Reasoning and Acting in Language Models》Yao et al. 2022——推理与行动交替循环的代表论文。