ChatDev Workflow Authoring 指南基于 YAML 编写与调试 DevAll 多智能体 DAG【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev导读本文是 ChatDev 项目中docs/user_guide/en/workflow_authoring.md的深度技术指南面向需要为 DevAll 多智能体协作系统编写、校验与调试工作流的开发者。文章以 YAML 工作流文件为骨架完整覆盖顶层结构与变量解析、八种内置节点类型、Provider 与 Agent 配置、边条件与负载处理器、Map/Tree 动态执行、设计模板导出以及 CLI/HTTP 运行路径并逐项对照entity/、runtime/、utils/等目录下的源码实现进行佐证。读完本文你将能够独立编写一份可运行的DesignConfig工作流 YAML理解占位符解析优先级与节点上下文语义并掌握用 Schema API、CLI 与 Web UI 快速定位配置错误的方法。1. 前置准备与阅读地图编写工作流之前建议先熟悉以下仓库布局yaml_instance/存放可直接运行的示例工作流如 net_example.yaml、demo_*.yaml系列yaml_template/design.yaml是由工具导出的最新配置模板与GraphDefinition数据类保持同步entity/configs/全部配置数据类DesignConfig、GraphDefinition、Node、EdgeConfig及各节点配置的定义所在entity/config_loader.pyYAML 文件到DesignConfig的加载与校验入口。如果你依赖前端/IDE 的动态表单建议同时阅读 field_specs.md字段目录与 config_schema_contract.mdSchema API 契约。另外本文所属的完整用户指南目录见 index.md节点级细节可继续阅读 nodes/ 下的分节点文档。2. YAML 顶层结构version、vars、graph每个工作流文件都遵循DesignConfig根结构且只包含三个顶层键version、vars和graph。下面的示例改编自 net_example.yaml可直接运行version: 0.4.0 vars: BASE_URL: https://api.example.com/v1 API_KEY: ${API_KEY} graph: id: paper_gen description: Article generation and refinement log_level: INFO is_majority_voting: false initial_instruction: | Provide a word or short phrase and the workflow will draft and polish an article. start: - Article Writer end: - Article Writer nodes: - id: Article Writer type: agent config: provider: openai base_url: ${BASE_URL} api_key: ${API_KEY} name: gpt-4o params: temperature: 0.1 - id: Human Reviewer type: human config: description: Review the article. Type ACCEPT to finish; otherwise provide revision notes. edges: - from: Article Writer to: Human Reviewer - from: Human Reviewer to: Article Writer condition: type: keyword config: none: - ACCEPT case_sensitive: false2.1 version配置版本version是可选配置版本号缺省时默认0.0.0见 graph.py 中optional_str(mapping, version, path) or 0.0.0。每当 graph.py 中的 schema 发生变化、需要模板或迁移更新时应递增该版本号。2.2 vars全局变量与${VAR}占位符解析vars是根级键值映射可被文件中任意字符串字段以${VAR}语法引用。常见用途包括API Keysapi_key: ${API_KEY}服务地址base_url: ${BASE_URL}模型名称name: ${MODEL_NAME}解析机制由 vars_resolver.py 实现PlaceholderResolver递归遍历整个配置的字符串、列表与映射对\$\{([A-Za-z0-9_])\}占位符进行替换并支持纯占位符替换与字符串内嵌替换两种形式。解析过程会检测占位符循环引用如A - B - A一旦发现立即抛出ConfigError。需要注意两点约束GraphDefinition.from_dict会拒绝嵌套vars见 graph.pyraise ConfigError(vars are only supported at DesignConfig root, ...)所以vars只能出现在文件顶部加载流程config_loader.py会先调用load_dotenv_file()加载项目根目录的.env文件再执行占位符解析。环境变量与.env文件解析优先级系统在解析配置时自动加载项目根目录的.env文件若存在变量解析优先级如下优先级来源说明1最高vars中显式声明的值直接写在 YAML 文件中的键值对2系统/Shell 环境变量通过export或系统配置设置的值3最低.env文件中的值仅当变量不存在时才生效[!TIP].env文件不会覆盖已存在的环境变量。这允许你在.env中定义默认值同时通过export或部署平台配置覆盖它们。[!WARNING] 如果某个占位符在以上三个来源中均未定义配置解析时会抛出ConfigError并精确指出出错路径对应 vars_resolver.py 的raise ConfigError(fUnresolved placeholder ${name}, path)。2.3 graph核心图定义graph是必需块映射到GraphDefinition数据类见 graph.py包含以下内容元数据id必需、description、log_level默认DEBUG见 graph.py、is_majority_voting默认false、initial_instruction以及可选的organization。执行控制start/end入口列表系统在开始时执行start中列出的节点。start支持字符串或字符串列表两种写法graph.pyend用于收集图的最终输出。注意end是有序列表靠前的节点优先检查第一个有输出的节点作为图输出见 graph.py 的字段说明在子图场景中尤其常用。校验逻辑GraphDefinition.validate()graph.py会检查节点 ID 是否重复、start节点是否真实存在、边是否引用了未知节点以及每个节点的memories附件是否指向graph.memory中声明的存储——任何一项不满足都会抛出带精确路径的ConfigError。共享资源memory定义可供node.config.memories引用的存储对应MemoryStoreConfig。Schema 对照design.yaml 镜像了最新的GraphDefinition结构。修改配置后运行python -m tools.export_design_template或调用 Schema API 进行校验详见第 8 节。上述示例中Human Reviewer - Article Writer边上的keyword条件会让工作流不断循环直到审查者输入ACCEPT——这正是人机协作迭代润色类流程的标准写法。进一步阅读field_specs.md字段目录、execution_logic.md运行时执行逻辑、design.yaml生成的基线模板。3. 节点类型速查表节点类型在 builtin_nodes.py 中注册type字段决定节点使用的配置 schema 与执行器。完整速查表如下类型描述关键字段详细文档agent运行 LLM 驱动的智能体可附加工具、记忆与思考阶段provider,model,prompt_template,tooling,thinking,memoriesagent.mdpython执行共享code_workspace/的 Python 脚本/命令entry_script,inline_code,timeout,envpython.mdhuman在 Web UI 中暂停等待人工输入prompt,timeout,attachmentshuman.mdsubgraph内嵌子 DAG 以复用复杂流程graph_path或内联graphsubgraph.mdpassthrough透传节点默认只转发最后一条消息可配置为转发全部消息用于上下文过滤与图结构优化only_last_messagepassthrough.mdliteral被触发时发射固定文本负载并丢弃输入content,roleuser/assistantliteral.mdloop_counter守卫节点在达到迭代次数上限前阻塞下游边达到后释放max_iterations,reset_on_emit,messageloop_counter.mdloop_timer守卫节点在达到时长上限前阻塞下游边达到后释放max_duration,duration_unit,reset_on_emit,message,passthroughloop_timer.md从源码看Node.from_dictnode.py会通过get_node_schema(node_type)解析节点类型遇到未注册类型时抛出ConfigError(unsupported node type ...)随后把config分发给对应类型的配置类解析。节点还支持几个通用字段context_window执行期间可访问的上下文消息数。0表示只保留keep_messageTrue的消息-1表示无限制其他正数表示保留最近 N 条keepTrue的消息始终保留并计入窗口见 node.py 的clear_input实现。log_output是否记录该节点的输出内容默认true。完整的字段 schema 可通过POST /api/config/schema获取或直接阅读 entity/configs/ 下的数据类。注册类型与执行器的对应关系见 registry.py。4. Provider 与 Agent 设置当节点省略provider时引擎使用globals.default_provider例如openai。model、api_key、base_url等字段都接受${VAR}占位符以提升环境可移植性。使用多个 Provider 时可在工作流根部定义globals{ default_provider: ..., retry: {...} }前提是数据类支持。Agent 节点配置由 AgentConfig 承载Provider 的注册与实现位于 runtime/node/agent/providers/内置openai_provider.py、gemini_provider.py等。各 Provider 的具体能力在 agent.md 中有完整说明。4.1 Gemini Provider 配置示例model: provider: gemini base_url: https://generativelanguage.googleapis.com api_key: ${GEMINI_API_KEY} name: gemini-2.0-flash-001 input_mode: messages params: response_modalities: [text, image] safety_settings: - category: HARM_CATEGORY_SEXUAL threshold: BLOCK_LOWERGemini Provider 支持多模态输入图片/视频/音频会自动转换为 Parts并支持通过function_calling_config控制工具执行行为详见 gemini_provider.py。5. 边与条件控制 DAG 的流向5.1 基础边与条件边基础边只需from/to两个字段注意源码中EdgeConfig的属性名为source/targetYAML 键是from/to见 edge.py- source: plan target: execute条件边则在边上声明condition。条件支持三种形态的归一化见 edge_condition.py省略或true→ 等价于恒真函数true布尔值false→ 等价于恒假函数always_false字符串 → 等价于{type: function, config: {name: 字符串}}。edges: - source: router target: analyze condition: should_analyze # functions/edge/should_analyze.py其中should_analyze是functions/edge/目录下的一个函数文件名。条件类型在运行时注册内置类型包括function与keyword对应 edge/conditions/ 下的function_manager.py与keyword_manager.py。keyword类型支持any、none、regex三个关键词列表与case_sensitive开关其中none优先级最高——一旦命中排除关键词即返回False见 edge_condition.py。异常语义如果condition函数抛出异常调度器将该分支标记为失败并停止下游执行。除条件外边还支持以下控制字段全部定义于 edge.py 的FIELD_SPECStrigger默认true该边是否可以触发后继节点carry_data默认true是否向目标节点传递数据keep_message默认false该消息在目标节点中是否永远保留、不被上下文清理clear_context/clear_kept_context默认false在传递新负载前是否清空普通上下文 /keepTrue上下文。5.2 边负载处理器Payload Processors当条件满足后若需要对传递的负载做变换或过滤例如提取裁决结果、只保留结构化字段、重写文本可以在边上添加process。其结构与condition一致type config内置类型包括regex_extract基于 Python 正则提取内容支持group分组名或索引缺省为整个匹配、modereplace_content、metadata、data_block、multiple是否收集全部匹配、以及on_no_matchpass保持原样 /default使用default_value/drop直接丢弃负载。完整字段见 edge_processor.py 的RegexEdgeProcessorConfig还额外支持multiline、dotall与template用{match}占位符加工提取值。function调用functions/edge_processor/下的辅助函数处理器签名统一为def foo(payload: Message, **kwargs) - Message | None注意Processor 接口现已标准化kwargs中包含context: ExecutionContext允许访问当前执行上下文。函数名会在field_specs中通过get_function_catalog动态枚举见 edge_processor.py前端表单会以下拉形式呈现可用的处理器函数。示例——从审查结果中提取质量评分并写入元数据- from: reviewer to: qa process: type: regex_extract config: pattern: Score\\s*:\\s*(?Pscore\\d) group: score mode: metadata metadata_key: quality_score case_sensitive: false on_no_match: default default_value: 0从 transformers.py 可以看出处理器最终返回的是Message或NoneNone表示丢弃该负载从而实现条件过滤 数据整形的链式编排。6. Agent 节点的高级能力Tooling工具通过AgentConfig.tooling配置函数工具与 MCP 工具详见 Tooling 模块 与 mcp.md。工具的加载与执行由 runtime/node/agent/tool/tool_manager.py 负责。Thinking思考通过AgentConfig.thinking启用分阶段推理如 chain-of-thought、self-reflection 等参数定义参考 entity/configs/node/thinking.py内置思考策略见 runtime/node/agent/thinking/含self_reflection.py等。Memories记忆通过AgentConfig.memories挂载MemoryAttachmentConfig细节见 Memory 模块。图级声明存储后节点的记忆附件会被 graph.py 的校验逻辑强制指向已声明的 store运行时执行则依赖 runtime/node/agent/memory/支持 simple、file、mem0 等存储实现。7. 动态执行Map-Reduce 与 Tree 模式节点支持兄弟字段dynamic以开启并行处理或 Map-Reduce 模式。需要说明的是从当前源码看动态执行配置已经迁移到边级EdgeConfig上的dynamic字段edge.py由DynamicEdgeConfig解析dynamic_edge_config.py注释也明确dynamic configuration has been moved to edges。文中仍按文档口径给出节点级写法但实际配置时建议将dynamic挂在边上目标节点会根据切分结果被动态展开。7.1 核心概念Map 模式type: map扇出。将列表输入切分为多个单元并行执行输出List[Message]展平结果。Tree 模式type: tree扇出 归约。将输入切分后并行执行再按group_size递归归约结果直到只剩一个结果即摘要的摘要。Split 策略定义如何将前一节点的输出或当前输入切分为并行单元。7.2 配置结构nodes: - id: Research Agents type: agent # 标准配置作为并行单元的模板 config: provider: openai model: gpt-4o prompt_template: Research this topic: {{content}} # 动态执行配置注意当前仓库已迁移至边级 dynamic dynamic: type: map # 切分策略仅第一层 split: type: message # 可选: message, regex, json_path # pattern: ... # regex 模式必填 # json_path: $.items[*] # json_path 模式必填 # 模式专属配置 config: max_parallel: 5 # 并发上限SplitConfig支持三种切分类型message按消息切分、regex按正则切分文本、json_path按 JSONPath 提取列表。模式专属配置中max_parallel为并发上限缺省10见 dynamic_edge_config.py 的max_parallel属性。7.3 Tree 模式示例适合对长文本做分块摘要dynamic: type: tree split: type: regex pattern: (?s).{1,2000}(?:\\s|$) # 每约 2000 字符切一块 config: group_size: 3 # 每 3 个结果归约为 1 个 max_parallel: 10该模式会自动构建多层执行树直到结果数归约为 1。Tree 模式的切分配置与 Map 模式一致group_size缺省为3见 dynamic_edge_config.py。实际执行由 workflow/executor/dynamic_edge_executor.py 调度动态执行的整体机制可参考 dynamic_execution.md。8. 设计模板导出修改配置数据类或FIELD_SPECS后需要重新生成模板python -m tools.export_design_template \ --output yaml_template/design.yaml \ --mirror frontend/public/design_0.4.0.yaml脚本会扫描已注册的节点、记忆、工具以及FIELD_SPECS生成 YAML 模板同时产出前端镜像文件生成的文件需要提交并通知前端维护者刷新静态资源脚本实现在 tools/export_design_template.py。前端镜像文件对应frontend/public/design_0.4.0.yaml供 Web IDE 的动态表单使用字段目录的生成逻辑见 utils/schema_exporter.py 与 utils/function_catalog.py。9. CLI 与 API 执行路径Web UI选择 YAML 文件、填写运行参数、开始执行并在仪表盘中监控。推荐路径。详细说明见 web_ui_guide.md。HTTPPOST /api/workflow/execute请求体包含session_name、graph_path或graph_content、task_prompt、可选attachments与log_level默认INFO支持INFO或DEBUG。对应路由实现在 server/routes/execute.py工作流运行服务见 server/services/workflow_run_service.py。CLIpython run.py --path yaml_instance/demo.yaml --name test_run。通过环境变量提供TASK_PROMPT或直接在 CLI 提示符下输入任务文本run.py 中的input(Please enter the task prompt: )。CLI 还支持--attachment可重复向初始用户消息附加文件、--fn-module提供边辅助函数模块与--inspect-schema输出配置 schema 后退出见 run.py。10. 调试技巧使用 Web UI 的上下文快照或检查WareHouse/session/context.json以查看节点的输入输出。注意所有节点的输出现已标准化为List[Message]。借助 Schema API 的面包屑见 config_schema_contract.md或运行python run.py --inspect-schema快速查看字段规格可结合--schema-breadcrumbs指定作用域例如[{node:DesignConfig,field:graph}]。缺失的 YAML 占位符会在解析阶段抛出ConfigError并在 UI 与 CLI 日志中给出精确路径例如root.graph.nodes[0].config.api_key据此可快速定位配置问题。小结工作流编排的核心要点可概括为三条顶层只用version/vars/graph三个键、变量一律走${VAR}占位符且遵循vars 环境变量 .env的优先级、节点与边的能力通过注册表node type / edge condition / edge processor / dynamic edge type动态扩展。从entity/configs/的数据类到runtime/的执行器整条链路都有精确的校验与错误提示这使得 ChatDev 的 DevAll DAG 既适合 Web UI 可视化编排也适合以纯 YAML 方式进行版本化、可移植的工程化维护。进一步深入可阅读 execution_logic.md执行调度、dynamic_execution.md动态执行与 config_schema_contract.mdSchema 契约。【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
