在 Code Agent 的工程实践中，真正决定系统是否可控、可调试、可恢复的，往往不是模型调用本身，而是框架层面的控制流设计。近期一篇针对开源项目 MyCodeAgent 的源码分析，把焦点从“功能怎么用”转向“框架如何组织”：它没有采用常见的多循环嵌套结构，而是把所有 Agent 行为收拢到一个单一主循环中，并配合不可变状态、完成门反馈和穷举式终止路径，形成一套偏工程化的运行约束。
单一主循环：牺牲一点灵活性，换来状态和调试的清晰
素材中提到，MyCodeAgent 只有一个 RuntimeRunner，整个 Agent 的行为都发生在 _react_loop() 这一个循环里。其结构可以概括为：每个 step 先构建模型输入，调用 LLM；如果模型返回工具调用，就执行工具并把观察结果写回历史；如果没有工具调用，则交给完成门判断是否结束；若未通过，则注入反馈继续下一轮。
与之相对的是另一种常见设计：外层负责规划，内层负责执行，一旦执行结果触发重新规划，就跳出内层回到外层。这种结构看起来更接近人类的“先计划、再行动”，但在工程上会带来两套状态、两层进度和多处隐式跳转。
MyCodeAgent 选择单一循环后，带来的工程收益主要包括：
- 状态只有一份：运行时状态统一由 LoopState 承载，不需要在“规划状态”和“执行状态”之间同步。
- 控制流更可观测：每次迭代对应一个 step，trace 文件中可以按 step 编号过滤事件，还原任意时刻发生了什么。
- 减少隐式状态机：系统进度直接由 step 计数器表达，而不是依赖“当前在哪个循环、执行到哪一步”的变量标记。
这种设计也有代价：规划和执行都由模型在同一个循环里完成，框架不能在“规划阶段”强制插入额外策略。换句话说，项目把规划权交给模型，循环本身只提供执行框架。
不可变状态机：把每一次变化变成可追踪的记录
素材显示，LoopState 是一个 frozen=True 的 dataclass，包含 step、tool_choice、completion_block_count、model_recovery_counts、last_error 和最近一次转移原因等字段。它不通过直接修改字段来更新状态，而是通过 next() 方法生成新的 LoopState 对象，并把状态变化原因写入 transition 字段。
这种不可变设计的核心目的，是让状态变化从“悄悄修改”变成“显式操作”。在可变状态里，某个字段被哪一行代码改掉，往往需要结合调用栈和运行时上下文才能追查；而在不可变状态机中，每次状态变化都会生成一个新对象，同时保留变化原因。
素材还提到，TransitionReason 枚举会把“为什么走到这一步”编码为可查询的枚举值。例如，工具执行完成后进入下一步、模型空响应后重试、完成门拦截后继续循环，都可以作为不同原因被记录。这样，trace 文件中的 state_transition 事件就可以按 reason 过滤，方便排查特定类型的行为。
不可变状态还带来一个额外好处：每个 LoopState 对象本身就是某个时间点的快照。如果需要在某个 step 设置断点或回放，可以从 transcript 重建当时的状态，而不必重新运行整个循环。
完成门反馈回路：不信任模型的“我完成了”
许多 Agent 框架的退出逻辑比较简单：模型没有返回工具调用，就认为任务结束。MyCodeAgent 在这一步之后加入了一个完成门。模型没有工具调用时，并不会直接退出，而是先经过完成门判断。
素材中给出的判断路径是：如果完成门返回 PASS，则返回最终文本；如果返回 UNVERIFIED，也会返回最终文本，但会带上未完成验证的标记；如果返回 FAIL，则系统会构造结构化反馈消息注入对话，并让循环继续。
FAIL 时注入的反馈消息包含明确原因，例如仍有未完成 todo，或缺少测试验证证据。素材还提到，这些反馈会用 <system-reminder> 标签包裹，因为系统提示词中约定模型遇到 system-reminder 需要执行相应要求。这样做的目的，是让模型更可能根据反馈去补齐测试、清理 todo，而不是忽略提示。
这一反馈回路的工程价值在于，它把“任务是否完成”的判断从模型的自我声明中部分剥离出来，交给规则层检查。模型可以说“我完成了”，但如果仍有未完成项或缺少验证证据，完成门可以拦截并要求继续执行。
同时，项目并没有在失败时直接终止，而是选择注入反馈继续循环，让 Agent 有自我修正机会。为避免无限反馈导致上下文膨胀，完成门反馈重试有上限，素材中给出的默认值是 completion_gate_retry_limit 为 2 次。
终止路径完备性：让每一次停止都有明确原因
素材还列出了 MyCodeAgent 主循环的所有出口。正常出口包括完成门 PASS 后返回最终文本，以及完成门 UNVERIFIED 后返回带 completed_unverified 标记的最终文本。异常出口则包括：超过 max_steps、token 累计超过预算、模型调用异常无法恢复、空响应重试耗尽、完成门反馈重试耗尽。
每一个异常出口都会对应一个 TerminalReason，并向 transcript 写入 terminal 事件。这个设计的关键不在于“把错误分类”，而在于让每次运行都有明确终点。素材提到，ResumeLoader 可以根据 terminal 事件判断这个 run 是正常完成还是异常终止，从而决定恢复后是否需要重新运行。
如果系统只区分“完成”和“出错”，调试时很难判断 Agent 为什么停止。穷举终止原因后，开发者可以直接从 trace 中查看这次运行是因为步数耗尽、token 预算超限、模型错误，还是完成门多次拦截而停止。
双层循环的真正作用：把错误重试和步数消耗分开
虽然 MyCodeAgent 强调单一主循环，但素材也提到，它内部存在一个双层结构：外层 for step in range(max_steps) 控制“走了多少步”，内层 while True 控制“这一步里重试了几次”。
当出现 PROMPT_TOO_LONG 时，系统会先压缩上下文，然后继续内层循环；当出现空响应时，系统会注入提示，然后继续内层循环。只有在拿到正常响应后，才会跳出内层，让外层 step 前进。
这种设计解决的是一个具体问题：错误重试不应消耗 step 配额。如果把重试放在外层循环里，每次重试都会增加 step 计数，用户设置 max_steps=50，可能实际只完成了 30 步真正的 ReAct 迭代。双层循环把重试隔离在当前 step 内，使“错误恢复”和“任务推进”分开计算。
行业意义：Agent 框架竞争正在从能力转向工程约束
从这篇源码分析来看，Code Agent 的工程难点并不只是“让模型调用工具”，而是如何让整个运行过程可追踪、可恢复、可验证。单一主循环降低了状态同步成本，不可变状态机让每次变化都有原因，完成门为模型输出增加了独立检查，终止路径完备性则保证每次运行都有明确结局。
这些设计并不追求花哨的自治能力，而是更接近传统软件工程中的确定性要求：状态可观测、错误可解释、恢复可判断。对于 AI 编程工具而言，模型能力决定了上限，但控制流设计决定了系统是否足够可靠，能否进入真实开发工作流。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/code-agent-gong-cheng-jie-pou-wei-shen-me-yi-ge-ben-de-dan
