深入解析 AI Coding Agent 的架构演进：从单一循环到智能集群

在人工智能快速发展的今天，AI Coding Agent 已成为提升开发者生产力的关键工具。然而，如何从零构建一个高效、可靠的智能编码代理，始终是技术领域的重要课题。本文将深入解析一个 AI Coding Agent 的完整架构演进路径，揭示从最基础的循环机制到复杂的多智能体集群的内在逻辑。

核心哲学：一个循环统治一切

无论多么复杂的 AI Agent，其本质都是一个不断处理工具调用的 while 循环。这个核心理念可以概括为「One Loop to Rule Them All」。想象一下：语言模型虽然能够推理代码，但它无法直接接触真实世界——不能读文件、跑测试、看报错。没有循环机制的情况下，每次工具调用后都需要人工将结果粘贴回去，此时人类扮演的就是那个「循环」的角色。 解决方案其实很简单：构建一个退出条件来控制整个流程，循环持续运行直到模型不再调用工具。用户发送的 prompt 作为第一条消息，系统将其与消息列表和工具定义一起发送给大语言模型，然后追加助手响应并检查 stop_reason——如果模型没有调用工具，则循环结束；否则执行每个工具调用，收集结果并作为用户消息追加，然后回到第二步。整个过程不到 30 行代码，却构成了整个智能体的核心骨架。

阶段一：基础循环与工具调度

在第一阶段（s01）中，我们建立了最基础的 Agent Loop。此时只有一个 bash 工具，所有操作都通过 shell 执行，但这种方式存在明显缺陷：cat 截断不可预测，sed 遇到特殊字符就崩溃，每次 bash 调用都是不受约束的安全面。 第二阶段（s02）引入了「加一个工具，只加一个 handler」的设计理念。循环本身无需改动，新工具只需注册到 dispatch map 即可。通过引入 read_file、write_file、edit_file 等专用工具，我们可以在工具层面实现路径沙箱，防止越权访问。dispatch map 将工具名映射到处理函数，一次查找即可替代任何 if/elif 条件链，极大提升了代码的可扩展性。

阶段二：认知升级与规划能力

第三阶段（s03）解决了「没有计划的 Agent 走哪算哪」的问题。在多步任务中，模型经常会丢失进度——重复做过的事、跳步、或偏离目标。对话越长越严重：工具结果不断填满上下文，系统提示的影响力逐渐被稀释。一个 10 步的重构任务可能做完 1-3 步就开始「即兴发挥」，因为后面的步骤已经被挤出注意力窗口。 解决方案是引入 TodoManager，它维护带状态的任务清单。通过「同时只能有一个 in_progress」的强制约束，确保 Agent 专注于当前任务；同时，当模型连续 3 轮以上不调用 todo 时，系统会自动注入提醒，制造问责压力。 第四阶段（s04）引入了子智能体机制，实现「大任务拆小，每个小任务干净的上下文」。子智能体拥有独立的消息数组，不会污染主对话。当父智能体需要读取多个文件来回答「这个项目用什么测试框架」这样的问题时，只需调用子智能体，父智能体最终收到的只是一个词：「pytest」。

阶段三：工程化持久性与技能加载

第五阶段（s05）实现了「用到什么知识，临时加载什么知识」的设计。通过两层注入机制，第一层在系统提示中放技能名称（低成本），第二层在 tool_result 中按需放完整内容。如果将 10 个技能、每个 2000 token 的工作流全部塞进系统提示，总计需要 20,000 token，且大部分与当前任务无关，造成严重浪费。 第六阶段（s06）应对「上下文总会满」的现实问题。引入三层压缩策略：micro_compact 在每次调用前将旧工具结果替换为占位符；auto_compact 在 token 超过阈值时保存完整对话到磁盘并让 LLM 摘要；compact 工具支持按需手动触发压缩。完整历史通过 transcript 保存在磁盘上，信息没有真正丢失，只是移出了活跃上下文。 第七阶段（s07）将扁平清单升级为持久化到磁盘的任务图。每个任务是一个 JSON 文件，包含状态、前置依赖（blockedBy）和后置依赖（blocks）。任务图能够回答三个关键问题：什么可以做？什么被卡住？什么做完了？这为多 Agent 协作奠定了基础。

如有侵权，请联系删除。