夜雨聆风美杜莎又回来了～哎，还是先说正事吧!
书接上回。前几篇聊了架构、技术栈，今天终于要扒开 mini-cc 真正的“大脑”——Agent 循环引擎。
你可能会问：Agent 循环有什么好讲的，不就一个 while 循环吗？对，但也不全对。
就像那句老话说的：“核心逻辑抽象出来不到 20 行代码，但生产环境的 Agent 循环才是真正考验工程能力的地方。”
Agent 循环到底是什么
简单来说，Agent 循环就是感知 → 思考 → 行动三个步骤循环往复，直到任务完成。
用户输入│▼┌─────────────┐│感知│接收用户输入，构建上下文├─────────────┤│思考│调用 LLM，让它决定下一步├─────────────┤│行动│执行工具（读写文件、跑命令）或者直接回复└─────────────┘││(有工具调用就继续)▼循环……
用一句话概括就是：Agent 不断问大模型“接下来该干嘛”，执行它要求的动作，然后把结果再喂给它，直到它说“好了，不用了”。
核心实现
我扒过不少项目的源码，Claude Code、OpenAI Codex、Cursor……各家框架虽然披着不同的外衣，但核心逻辑惊人地相似。mini-cc 也不例外。我把核心代码简化一下：
// src/application/QueryEngine.ts/*** Agent 循环引擎的核心实现*/exportclassQueryEngine{private provider:LLMProvider;private toolRegistry:ToolRegistry;private memory:MemoryManager;private maxIterations =5;// 防无限循环，最多跑5轮async run(prompt:string):Promise<AgentResponse>{// 1. 构建上下文（从记忆系统里捞历史）const context =awaitthis.memory.buildContext(prompt);// 2. 调用 LLM，看它想干什么const response =awaitthis.provider.chat(context);// 3. 解析 AI 的回复里有没有工具调用const toolCalls =this.parseToolCalls(response);// 4. 如果有工具要执行，执行完把结果喂给 AI，递归继续if(toolCalls.length >0){const results =awaitthis.executeTools(toolCalls);returnthis.run(results);// 递归调用，形成循环}// 5. 没有工具调用了，直接把回答返回给用户return response.content;}}
你仔细看，这个版本跟我之前文章里放的代码不太一样。主要多了几步：
- 最大迭代次数限制：
maxIterations=5。这是实际跑起来的血泪教训。有一次我做测试，给 AI 一个模糊的指令，它陷入“查→看不懂→再查”的死循环，跑了很多次才被我手动杀掉。从那以后，不管什么情况我都得加个硬上限。 - 更清晰的循环语义：把“有工具调用”和“无工具调用”的两条路径分开，每一步该干什么一目了然。
- 递归设计：这个设计是我从 ReAct 模式里借鉴来的——每次执行完工具之后，带着新的上下文重新调用自己，形成自然闭环。当然你也可以用 while 循环，但递归写出来更直观。
看起来简单，对吧？真正的挑战不在这个循环本身，而在围绕循环的那一圈工程细节。
系统提示词
大模型要准确地调用工具，得先告诉它“有哪些工具可以用、怎么用”。这不只是写一段话的事。
在 mini-cc 里，我会动态构建系统提示词，把当前可用的所有工具列进去：
private buildSystemPrompt():string{const tools =this.toolRegistry.list();const toolDescriptions = tools.map(tool =>{return`工具名称: ${tool.name}描述: ${tool.description}参数: ${JSON.stringify(tool.inputSchema.properties)}`;}).join('\n\n');return`你是一个专业的 AI 编程助手。可用工具:${toolDescriptions}工具调用格式:<function_calls><invoke name="工具名称"><parameter name="参数名">参数值`;}
这里有个容易忽略的点：工具描述怎么写，直接影响模型选择工具的准确率。 之前我有个工具叫 GetCurrentTime，描述写的是“获取时间”，结果用户问“现在几点了”，模型反而跑去调别的工具。后来我把描述改成“获取当前系统时间和时区信息，返回精确的本地时间”，调用准确率明显提升。
一个真实的多轮交互
光讲理论不够直观，我给你看一个真实场景。假设你对 AI 说：
“帮我读一下 package.json，看看项目名称是什么。”
它会怎么处理？
第 1 轮：思考并行动
LLM 收到指令后，判断需要读取文件，返回一个工具调用：
工具调用:FileReadTool参数:{"path":"package.json"}
你的代码执行工具 → 读取文件内容 → 得到结果后，把结果作为新消息喂给 LLM：
工具结果:{"name":"my-project","version":"1.0.0",...}
第 2 轮：继续思考
LLM 拿到结果，发现 name 字段确实是 "my-project"，不需要再用其他工具了，直接返回最终答案：
“根据 package.json，这个项目的名称是 my-project。”
任务完成。
如果任务更复杂——比如“给这个项目加一个测试脚本，然后跑一下”——模型可能会连续多次调用：先 FileReadTool 看当前的 package.json，然后 FileWriteTool 修改它，最后 BashTool 运行测试。整个过程完全由模型自主决策，轮次越深，工程约束就越重要。
不只是 while 循环
前面说了，最简实现就是几十行代码。但要让循环跑得稳、跑得安全，绕不开这几个“工程补丁”。
1. 防止无限循环：迭代次数上限
if(execContext.iteration >=this.maxIterations){return{type:'error',content:`达到最大迭代次数(${this.maxIterations})，已自动终止。`};}
这个 maxIterations 我默认设成 5——大部分任务 3-4 轮内就结束了，如果超过 5 轮还在打转，大概率是死循环或者任务太模糊。这时候自动中断比让用户干等强。
2. 记忆管理
每次循环都会调用 memory.buildContext(prompt)。mini-cc 用的是短期记忆 + 长期记忆两层结构：
- 短期记忆：最近 50 条消息，直接拼进上下文
- 长期记忆：超过 50 条时，把历史消息压缩成摘要，存起来
实际测试中，长对话的 Token 消耗降了一半以上，关键信息也没丢。
3. 工具执行超时兜底
AI 调了个 BASH 命令，可能跑几秒，也可能跑几分钟。必须有超时兜底： BashTool 默认 300 秒超时，读文件、写文件这类操作 120 秒就够。
4. 错误处理
工具执行失败的时候，把错误信息返回给 LLM，让它自己判断怎么补救。我不希望整个循环直接挂掉，而是让模型有机会“自我修复”：
try{const result =await tool.execute(args);}catch(error){return{type:'error',content:`执行失败: ${error.message}`};}
LLM 拿到这个错误后，可能会调整参数重试，或者换一个思路。
之前遇到过输入一个不存在的文件路径，模型第一次调用 read_file 失败后，分析错误信息发现自己路径写错了，下一轮就修正成正确的路径继续执行——整个过程我没插手，体验好很多。
两个常见的坑
坑一：忘记递归终止条件
新手最容易踩的坑。不加最大迭代次数限制，一旦模型进入“查资料→不够→再查”的死循环，直接失控。硬上限是第一道防线。
坑二：上下文越堆越大
每轮循环都把工具结果塞进 messages，没做清理。跑几轮之后上下文膨胀到几万 Token，不仅 API 费用飙升，模型响应速度也肉眼可见地变慢。记忆系统不是“锦上添花”，是刚需。
小结
Agent 循环的骨架很简单，就是个“问→答→执行→再问”的死循环。但真正决定它能不能稳定跑下去的，是外层的工程细节：迭代上限、记忆管理、超时兜底、权限控制、错误恢复。
mini-cc 里所有相关代码都在 src/application/QueryEngine.ts，感兴趣可以去翻翻源码：\https://github.com/you-want/mini-cc/tree/main/typescript
思考
你觉得 Agent 循环里最难处理的是什么？是工具调用的时序，还是上下文的压缩策略？评论区聊聊，我也想知道大家在复刻类似系统时踩过什么坑。
