ChatDev Thinking 模块深度解析:为 Agent 节点注入自省与反思能力

ChatDev Thinking 模块深度解析:为 Agent 节点注入自省与反思能力 ChatDev Thinking 模块深度解析为 Agent 节点注入自省与反思能力【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev本指南围绕 ChatDev 2.0LLM 驱动的多智能体协作框架中的 Thinking 模块展开讲解如何为 Agent 节点配置基于reflection的推理增强能力使模型在生成结果前后进行额外推理、自我审视并改进输出。读完本文你将掌握 Thinking 模块的架构分层、YAML 配置方式、内置反思模式的执行原理、与 Memory 的协作机制以及如何注册自定义 Thinking 模式。1. Thinking 模块定位在 Agent 节点的什么位置工作Thinking 模块是 ChatDev 2.0 为 Agent 节点提供的推理增强能力它允许模型在正式生成结果之前或之后额外地执行一次推理。典型的场景是自反思self-reflection——模型先生成一份初步回答再基于反思提示词审视自己的输出并给出改进版本最后以改进后的内容作为节点输出。从代码结构看该模块由三层构成配置层ThinkingConfig声明在 YAML 的nodes[].config.thinking下包含type与config两个字段见 entity/configs/node/thinking.py。管理器层ThinkingManagerBase是抽象基类定义了_before_gen_think与_after_gen_think两个时机的思考逻辑见 runtime/node/agent/thinking/thinking_manager.py。注册层通过register_thinking_mode()注册新的思考模式注册的同时会同步 Schema API使前端可视化配置界面自动展示可选模式见 runtime/node/agent/thinking/registry.py 与 schema_registry/registry.py。在 entity/configs/node/agent.py 的AgentConfig中thinking: ThinkingConfig | None None是一个可选字段且被标记为advanceTrue高级配置。这意味着不配置thinking时 Agent 节点照常工作只有显式声明后才启用推理增强。2. 架构分层与执行时机2.1 三个核心组件ThinkingConfig配置YAML 中nodes[].config.thinking的结构化表示。外层ThinkingConfig只负责承载type字符串与内层config对象type决定使用哪种已注册的思考模式config则是该模式专属的参数字段。在ThinkingConfig.from_dict中type会被送到get_thinking_schema()校验不支持的 type 会抛出ConfigError: unsupported thinking type xxx。ThinkingManagerBase管理器抽象基类构造时接收ThinkingConfig默认关闭两个开关self.before_gen_think_enabled False self.after_gen_think_enabled False子类按需开启。同时暴露thinking_concat_prompt默认{origin}\n\nThinking Result: {thinking}当思考结果不需要整体替换时会用该模板将原始内容与思考结果拼接。Registry注册中心register_thinking_mode()把模式名 → 配置类 管理器类登记进thinking_registry同时调用register_thinking_schema()将配置类同步到 Schema 注册表。因此 Schema API前端表单、设计模板导出能自动感知新增模式。2.2 两个执行时机时机开关属性用途生成前before_genbefore_gen_think_enabled在调用模型 API 之前执行思考用于输入预处理生成后after_genafter_gen_think_enabled在模型输出之后执行思考用于后处理或精炼内置的reflection模式只启用生成后思考after_gen_think_enabled True扩展开发者可以根据需求实现生成前思考。2.3 思考结果的三种返回策略ThinkingManagerBase.think()是统一入口逻辑如下生成前思考调用_before_gen_think()返回(think_result, replace_input)。若replace_inputTrue直接用思考结果替换原始输入否则用thinking_concat_prompt拼接。生成后思考调用_after_gen_think()返回(think_result, replace_gen)。若replace_genTrue直接用思考结果替换模型原始输出内置 reflection 即此行为否则拼接。未命中任何开关原样返回输入或生成内容优先raw字段。3. 配置示例与参数说明3.1 最小可运行配置以下 YAML 声明了一个启用 reflection 反思的 Agent 节点完整结构可参考 yaml_instance/demo_simple_memory.yamlnodes: - id: Thoughtful Agent type: agent config: provider: openai name: gpt-4o api_key: ${API_KEY} thinking: type: reflection config: reflection_prompt: | Please carefully review your response, considering: 1. Is the logic sound? 2. Are there any factual errors? 3. Is the expression clear? Then provide an improved response.字段说明字段类型必填说明thinking.typestring是思考模式类型当前内置reflection需与已注册模式名一致thinking.configobject是模式专属配置体reflection模式下必须包含reflection_promptthinking.config.reflection_promptstring是引导模型反思的提示词指定反思维度与期望的改进方向注意三点thinking.config块不能缺省。ThinkingConfig.from_dict在config缺失或为None时直接抛出ConfigError。${API_KEY}、${BASE_URL}等占位符由环境变量解析配置经 utils/env_loader.py 加载。在demo_simple_memory.yaml中可以看到一个真实用例写作 Agent 生成文章后通过 reflection 提示词Extract the first sentence of each paragraph, do not output anything else.将完整文章收敛为每段首句摘要直接体现生成后反思 → 结果替换的典型玩法。3.2 与 Memory 配置的组合示例nodes: - id: Writer With Reflection type: agent config: provider: openai name: gpt-4o base_url: ${BASE_URL} api_key: ${API_KEY} params: temperature: 0.1 max_tokens: 4000 tooling: [] thinking: type: reflection config: reflection_prompt: | Review your article and fix grammar, logic and factual errors, then output the improved full article. memories: - name: Paper Gen Memory top_k: 2 retrieve_stage: - gen这里的memories让反思阶段可检索历史记忆详见第 5 节。4. 内置模式Reflection 自反思4.1 执行流程reflection模式由SelfReflectionThinkingManager实现见 runtime/node/agent/thinking/self_reflection.py其注释说明该实现借鉴自 ChatDev 并做了适配。完整执行流程Agent 节点调用模型生成初始回答ThinkingManager将对话历史system 角色、用户输入、模型输出拼接为反思上下文使用reflection_prompt再次调用模型生成反思结果反思结果替换原始输出作为节点最终输出replace_genTrue。4.2 内部实现细节self.base_prompt Here is a conversation between two roles: {conversations} {reflection_prompt} self.reflection_prompt config.reflection_prompt or Reflect on the given information and summarize key points in a few words._after_gen_think构造的对话上下文为SYSTEM: {agent_role} USER: {input_payload.text} ASSISTANT: {gen_payload.text}若检索到 Memory则memory.text会作为首条消息前置到对话中。最终以一条 USER 消息base_prompt 模板调用agent_invoker完成一次模型调用返回(reflection_message.text_content(), True)——注意第二个返回值True表示用反思结果整体替换模型原始输出而非拼接。4.3 应用场景写作精修自动自查语法与逻辑问题后输出修订稿代码评审代码生成后自动进行安全性与质量检查复杂推理对多步推理结果进行校验与修正。5. 执行时机在 Agent 节点中的真实调用链从 runtime/node/executor/agent_executor.py 的AgentNodeExecutor.execute()可以看到 Thinking 在节点执行流水线中的确切位置构造输入ThinkingPayload_build_thinking_payload_from_inputs若配置了agent_config.thinking先调用_apply_pre_generation_thinking阶段PRE_GEN_THINKING_STAGE执行 Memory 检索_apply_memory_retrieval阶段GEN_STAGE调用模型生成_invoke_provider处理工具调用循环若模型返回 tool calls若配置了 thinking对模型输出构造gen_payload并调用_apply_post_generation_thinking阶段POST_GEN_THINKING_STAGE其返回值直接决定节点最终输出更新 Memory 存储_update_memory。两个应用函数都通过self.context.get_thinking_manager(node.id)获取管理器见 runtime/node/executor/base.py并在log_manager.thinking_timer中计时、通过record_thinking_process记录思考过程便于在运行日志中追踪每次反思的输入输出。值得注意的细节反思阶段使用的agent_invoker是执行器在节点上下文内构建的模型调用闭包_build_agent_invoker它复用同一 provider、client 与 call_options因此反思调用与主生成调用共享相同的重试策略与 token 追踪_invoke_provider内部统一处理。5.1 ThinkingPayload 与多模态支持ThinkingPayloadruntime/node/agent/thinking/thinking_manager.py是贯穿整个思考流程的数据容器字段说明text当前阶段的文本内容blocks多模态内容块图片、附件等来自输入消息或模型输出metadata附加元数据如来源inputs/model_output/memoryraw原始对象原始消息或文本未命中开关时原样返回执行器通过_build_thinking_payload_from_message(..., sourcemodel_output)将模型输出包装为gen_payloadMemory 检索结果则通过_memory_result_to_thinking_payload转换为memory参数传入思考函数使反思可以引用历史记忆。6. 与 Memory 的协作Thinking 模块可以访问 Memory 上下文具体路径为在 Agent 节点执行中_apply_pre_generation_thinking与_apply_post_generation_thinking都会先调用_retrieve_memory()检索结果经_memory_result_to_thinking_payload()转成ThinkingPayloadtext为检索结果的formatted_textblocks包含输入/输出快照的多模态块该 payload 作为memory参数传给thinking_manager.think()最终进入_before_gen_think/_after_gen_think。在SelfReflectionThinkingManager._after_gen_think中if memory and memory.text: conversations [memory.text] conversations即若反思阶段检索到历史记忆记忆文本会被前置到对话上下文让模型在反思时参考历史信息例如用户偏好、历史生成规范。配合memories配置如demo_simple_memory.yaml中top_k: 2、retrieve_stage: [gen]可让反思过程有据可依。关于 Memory 模块的更多配置参见 Memory 模块指南。7. 自定义 Thinking 模式扩展Thinking 模块的设计目标是可插拔新增一个思考模式只需四步。7.1 第一步定义配置类继承BaseConfig声明模式所需字段from entity.configs.base import BaseConfig, ConfigFieldSpec, require_str from typing import Mapping, Any class MyThinkingConfig(BaseConfig): my_prompt: str classmethod def from_dict(cls, data: Mapping[str, Any], *, path: str) - MyThinkingConfig: mapping require_mapping(data, path) return cls(my_promptrequire_str(mapping, my_prompt, path), pathpath) FIELD_SPECS { my_prompt: ConfigFieldSpec( namemy_prompt, display_nameMy Prompt, type_hintstr, requiredTrue, descriptionPrompt used for my thinking mode, ) }7.2 第二步实现管理器继承ThinkingManagerBase按需实现_before_gen_think或_after_gen_thinkfrom runtime.node.agent.thinking.thinking_manager import ( ThinkingManagerBase, AgentInvoker, ThinkingPayload, ) class MyThinkingManager(ThinkingManagerBase): def __init__(self, config: MyThinkingConfig): super().__init__(config) self.after_gen_think_enabled True # 启用生成后思考 self.my_prompt config.my_prompt def _before_gen_think(self, agent_invoker, input_payload, agent_role, memory): ... def _after_gen_think(self, agent_invoker, input_payload, agent_role, memory, gen_payload): message agent_invoker([Message(roleMessageRole.USER, contentself.my_prompt)]) return message.text_content(), True两个抽象方法的返回值约定见 thinking_manager.py 的文档字符串_before_gen_think返回(思考结果, 是否替换原始输入);_after_gen_think返回(思考结果, 是否替换原始生成内容)。7.3 第三步注册模式from runtime.node.agent.thinking.registry import register_thinking_mode register_thinking_mode( my_thinking, config_clsMyThinkingConfig, manager_clsMyThinkingManager, summaryCustom thinking mode description, )注册时若模式名已存在会抛出RegistryError。注册动作同时写入 Schema 注册表schema_registry/registry.py 的register_thinking_schema因此前端可视化工作台与设计模板会自动展示该模式及其字段。7.4 第四步导出设计模板运行以下命令更新前端选项python -m tools.export_design_template脚本位于 tools/export_design_template.py它从 Schema 注册表导出设计模板供前端表单与配置界面消费。内置模式的注册参考 runtime/node/agent/thinking/builtin_thinking.pyThinkingManagerFactory.get_thinking_manager()依据config.type从注册中心取出对应的 manager_cls 并注入类型化配置工厂逻辑也位于该文件。8. 最佳实践控制反思轮数当前 reflection 为单轮反思如需多轮迭代请在reflection_prompt中显式要求例如请重复审查直到通过所有检查项或在工作流中串联多个带反思的 Agent 节点参见 ChatDev_v1.yaml 的多 Agent 编排思路。提示词保持精炼过长的reflection_prompt会显著增加 token 消耗聚焦最重要的改进点即可。与 Memory 结合把重要反思结果写入 Memory供下游节点复用避免重复反思。监控成本反思会带来额外一次模型调用建议配合 token 追踪执行器中的token_tracker见 utils/token_tracker.py观察每个 Agent 节点的实际消耗同理也可利用 Agent 节点配置 中的retry策略保证反思调用的稳定性。复用共享的 agent_invoker反思调用复用节点主调用的 provider、client 与 call_options因此重试与限流配置对反思同样生效无需单独配置。9. 相关文档Agent 节点配置Memory 模块工作流编写指南【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考