ChatDev 2.0 Loop Counter 节点实战指南用计数抑制机制为多智能体循环装上熔断器【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev本篇技术指南系统讲解 ChatDev 2.0LLM 驱动的多智能体协作工作流引擎中Loop Counter循环计数器节点的完整用法它是工作流中的循环熔断器通过未达上限抑制输出、达到上限释放消息的计数机制精确限制 Agent ↔ Human 等环路的最大执行次数防止多智能体协作陷入无限循环。读完本文你将掌握 Loop Counter 的全部配置项及其底层校验逻辑、三种拓扑连接约束、典型的人机审稿循环YAML 实战方案并理解计数器在运行时是如何在全局状态中持久化与释放消息的。关联文档docs/user_guide/zh/nodes/loop_counter.md什么是 Loop Counter 节点在 ChatDev 2.0 的多智能体工作流中Agent → Human → Agent之类的环路是常态Agent 写作、Human 审阅、再让 Agent 按反馈修改……这类循环如果没有上限约束一旦 Human 持续给出反馈工作流将永不终止。Loop Counter 节点正是为此设计的循环控制节点。它维护一个内部计数器在计数达到预设上限之前不产生任何输出从而抑制出边的触发只有计数等于上限时才释放一条输出消息触发出边、终止循环。这种抑制—释放机制让开发者可以用一个配置项精确掌控循环何时结束。从源码注册表看loop_counter是引擎内置的节点类型之一与其并列的还有agent、human、subgraph、python、passthrough、literal、loop_timer等注册逻辑见 runtime/node/builtin_nodes.pyregister_node_type( loop_counter, config_clsLoopCounterConfig, executor_clsLoopCounterNodeExecutor, capabilitiesNodeCapabilities(), summaryBlocks downstream edges until the configured iteration limit is reached, then emits a message to release the loop., )也就是说一旦在 YAML 中声明type: loop_counter的节点引擎就会自动将配置类LoopCounterConfig与执行器LoopCounterNodeExecutor绑定无需额外注册。配置项详解Loop Counter 只有三个配置字段全部位于节点的config段内完整定义见 entity/configs/node/loop_counter.py字段类型必填默认值说明max_iterationsint是10最大循环次数必须 ≥ 1reset_on_emitbool否true达到上限后是否重置计数器messagetext否-达到上限时发送给下游的消息内容各字段的源码级约束max_iterations最大迭代次数默认10。配置解析器会先尝试int()强转若失败则抛出ConfigError(max_iterations must be an integer)随后校验max_iterations 1会直接拒绝加载ConfigError(max_iterations must be 1)校验逻辑见 entity/configs/node/loop_counter.py。因此 YAML 中写成字符串3也能被安全转成整数但必须是 ≥ 1 的正整数。reset_on_emit达到上限后重置默认true。它决定计数器的生命周期为true时达到上限释放消息后计数器归零下一次循环重新计数为false时计数器持续累加此后每次被触发都会直接输出。message释放消息内容可选。留空时执行器会自动使用默认文案Loop limit reached (N)N 为max_iterations的值见 runtime/node/executor/loop_counter_executor.py。建议显式填写中文提示让下游节点或日志语义更清晰。在字段元数据FIELD_SPECS中reset_on_emit与message均被标记为高级选项advanceTrue说明它们是进阶调优字段日常使用仅需关心max_iterations与message参见 entity/configs/node/loop_counter.py。核心概念与工作原理每次触发的三段式行为Loop Counter 节点维护一个内部计数器每次被上游消息触发时按如下逻辑执行实现见 runtime/node/executor/loop_counter_executor.py每次被触发时计数器 1计数器 max_iterations执行器返回空列表[]——不产生任何输出所有出边都不会触发同时输出一条 debug 日志如iteration 2/3 (suppress downstream)计数器 max_iterations构造并返回一条Message触发出边循环得以终止。这正是抑制—释放机制的实现方式未达上限时用空输出静默拦截达到上限时才放行一条消息。执行器的核心代码片段如下counter[count] 1 count counter[count] if count config.max_iterations: self.log_manager.debug( fLoopCounter {node.id}: iteration {count}/{config.max_iterations} (suppress downstream) ) return [] # 未达上限不产生任何输出 if config.reset_on_emit: counter[count] 0 # 达到上限按需重置计数器计数器状态跨节点、跨轮次持久化计数器并非局部变量而是存储在**执行上下文的全局状态global_state**中。执行器通过_get_state()方法取用以loop_counter为键的状态分区见 runtime/node/executor/loop_counter_executor.py 与 runtime/node/executor/loop_counter_executor.pydef _get_state(self) - Dict[str, Dict[str, Any]]: return self.context.global_state.setdefault(self.STATE_KEY, {})由此可以确认三点运行特征计数器状态在整个工作流执行期间持久化即使同一节点被多次触发计数也能跨轮次累加reset_on_emit: true达到上限后计数器重置为 0允许重新计数的复用场景reset_on_emit: false达到上限后继续累计之后每次触发都会直接输出相当于计数第 N 次之后永久放行。另外达到上限时释放的消息会携带结构化的metadata其中包含loop_counter: {count, max, reset_on_emit}信息见 runtime/node/executor/loop_counter_executor.py下游节点与日志系统可以据此感知这是第几次触发的上限消息。拓扑结构要求三个关键连接Loop Counter 在图结构中有特殊的位置要求。因为未达上限时不产生任何输出所以它不能单独承担继续循环的任务必须配合条件边使用。官方推荐的拓扑如下┌──────────────────────────────────────┐ ▼ │ Agent ──► Human ─────► Loop Counter ──┬──┘ ▲ │ │ └─────────┘ ▼ End Node (环外)具体约束有三条Human 必须同时连接到 Agent 和 Loop Counter这样继续循环的边由Human → Agent承担而 Loop Counter 仅负责计数互不干扰Loop Counter 必须连接到 Agent环内使其被识别为环内节点避免引擎提前判定环路结束Loop Counter 必须连接到 End Node环外当计数达到上限时释放的消息走这条出边触发环外节点终止整个环的执行。何时使用 Loop Counter在 ChatDev 2.0 中以下三类场景强烈推荐引入 Loop Counter防止无限循环为人机交互循环设置安全上限。这是最常见场景——Human 节点一旦持续给反馈工作流可能永不终止加一个计数器即可兜底迭代控制限制 Agent 自我迭代改进的最大轮次。例如写作—反思—重写循环允许最多改 3 版超时保护作为流程执行的熔断器。即使业务上希望无限优化也可以用一个大上限如 50 次兜底防止资源被长期占用。实战示例基础用法最小配置只声明节点本身即可reset_on_emit与message均可省略nodes: - id: Iteration Guard type: loop_counter config: max_iterations: 5 reset_on_emit: true message: 已达到最大迭代次数流程终止。人机交互循环保护最典型场景这是 Loop Counter 最典型的使用场景一个写作—审阅—修改的闭环最多允许 3 次修改用户随时可输入ACCEPT提前结束graph: id: review_loop description: 带迭代上限的审稿循环 nodes: - id: Writer type: agent config: provider: openai name: gpt-4o role: 根据用户反馈改进文章 - id: Reviewer type: human config: description: | 审阅文章输入 ACCEPT 接受或提供修改意见。 - id: Loop Guard type: loop_counter config: max_iterations: 3 message: 已达到最大修改次数3次流程自动结束。 - id: Final Output type: passthrough config: {} edges: # 主循环Writer - Reviewer - from: Writer to: Reviewer # 条件1用户输入 ACCEPT - 结束 - from: Reviewer to: Final Output condition: type: keyword config: any: [ACCEPT] # 条件2用户输入修改意见 - 同时触发 Writer 继续循环 AND Loop Guard 计数 - from: Reviewer to: Writer condition: type: keyword config: none: [ACCEPT] - from: Reviewer to: Loop Guard condition: type: keyword config: none: [ACCEPT] # Loop Guard 连接到 Writer使其保持在环内 - from: Loop Guard to: Writer # Loop Guard 达到上限时触发 Final Output 结束流程 - from: Loop Guard to: Final Output start: [Writer] end: [Final Output]这里的keyword条件边是关键配合机制其求值逻辑位于 runtime/edge/conditions/keyword_manager.py规则是先判none关键词再判any关键词——只要输入文本不含ACCEPTnone: [ACCEPT]命中就同时触发Writer与Loop Guard两条边。执行流程说明用户首次输入修改意见 → 同时触发 Writer继续循环和 Loop Guard计数 1无输出用户再次输入修改意见 → 同时触发 Writer继续循环和 Loop Guard计数 2无输出用户第三次输入修改意见 → Writer 继续执行Loop Guard 计数 3 达到上限输出消息触发 Final Output终止环路或者在任意时刻用户输入 ACCEPT → 直接到 Final Output 结束。仓库自带的完整可运行示例仓库中已内置一个可以直接运行验证的 Loop Counter 示例 yaml_instance/demo_loop_counter.yaml它把示例中的 Agent/Human 替换为literal节点以便离线跑通核心结构如下graph: start: [Writer] end: [Finalizer] id: loop_counter_demo description: LoopCounter demo that releases output on the third iteration. nodes: - id: Writer type: literal config: content: Draft iteration from Writer role: assistant - id: Critic type: literal config: content: Please revise again role: user - id: Loop Gate type: loop_counter config: max_iterations: 3 reset_on_emit: true message: Loop finished after three passes - id: Finalizer type: literal config: content: Final summary released role: assistant edges: - from: Writer to: Critic - from: Critic to: Writer - from: Critic to: Loop Gate - from: Loop Gate to: Writer # keep Loop Gate inside the cycle - from: Loop Gate to: Finalizer运行该示例时前两轮Critic的反馈被 Loop Gate 静默抑制日志可观察到suppress downstream第三轮触发后Finalizer收到Loop finished after three passes消息输出最终结果整个演示恰好印证了文档中描述的抑制—释放行为。与 Loop Timer 节点的关系Loop Counter 并非引擎唯一的循环熔断手段。与它并列注册的还有Loop Timer节点执行器见 runtime/node/executor/loop_timer_executor.py二者共享阻断下游直至条件满足再放行的设计哲学但判据不同——Loop Counter以触发次数为判据适合需要精确控制轮数的场景Loop Timer以累计时长支持 seconds/minutes/hours 单位为判据适合限时优化场景且额外提供passthrough终端门模式限时前透传输入、到点发消息、之后透明放行。选择建议业务上关注最多改几版用 Loop Counter关注最多跑多久用 Loop Timer两者也可在同一工作流中叠加使用实现次数 时长双重兜底。注意事项基于文档与源码使用 Loop Counter 时请留意以下边界max_iterations必须为正整数≥ 1否则配置加载阶段即抛ConfigError工作流无法启动未达上限时不产生任何输出出边不会触发——这是它抑制特性的根本也意味着如果忘记把 Loop Counter 连回环内节点环路可能被引擎判定提前终止确保 Loop Counter 同时连接环内节点和环外节点只连环内会永远循环只连环外则永远不触发三种连接缺一不可message字段可选默认消息为Loop limit reached (N)如对下游语义有要求请显式配置计数器状态持久化在整个工作流执行期跨执行会话不会自动清零长生命周期场景需结合reset_on_emit设计计数语义。相关文档导航节点总览与字段速查表docs/user_guide/zh/workflow_authoring.md配置类实现entity/configs/node/loop_counter.py执行器实现runtime/node/executor/loop_counter_executor.py节点注册runtime/node/builtin_nodes.py可运行示例yaml_instance/demo_loop_counter.yaml关键字条件边实现runtime/edge/conditions/keyword_manager.py【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考