ChatDev 2.0 Python 节点完全指南在工作流中执行 Python 脚本的配置、原理与实战【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev导读Python 节点是 ChatDev 2.0 多智能体工作流中的通用执行单元用于在工作流内部直接运行 Python 脚本或内联代码实现自定义数据处理、API 调用、文件读写与胶水逻辑。本文以 Python 节点官方文档 为主线结合仓库内配置类与执行器的真实实现逐项拆解五个核心配置参数、code_workspace/共享工作区的运行机制、代码从上游消息提取到子进程执行的完整链路并给出可直接运行的 YAML 配置示例。读完本文你将掌握如何在自己的工作流中正确地编排 Python 节点、设置解释器与超时、传递环境变量以及如何用条件边实现「生成代码 → 执行 → 校验」的自动闭环。一、Python 节点是什么Python 节点节点类型python用于在工作流中执行 Python 脚本或内联代码。它本身不包含任何业务代码而是充当一个「执行器」把上游节点通常是 Agent 节点输出的 Python 代码块提取出来写入共享工作区交给系统 Python 解释器以子进程方式运行再把运行结果stdout作为 Message 传递给下游节点。在节点注册表 runtime/node/builtin_nodes.py 中python类型被注册为register_node_type( python, config_clsPythonRunnerConfig, executor_clsPythonNodeExecutor, capabilitiesNodeCapabilities( resource_keynode_type:python, resource_limit1, ), summaryExecutes repository Python snippets, )其中resource_keynode_type:python与resource_limit1表示该节点类型受资源管理器约束默认同一类型资源上限为 1所有 Python 节点在资源层面共享同一工作区。节点注册后runtime/node/registry.py 会自动为它生成对应的配置 Schema因此配置校验、前端表单渲染与运行执行使用同一份字段定义保证配置与实际行为一致。典型适用场景官方文档明确列出的场景包括数据处理解析 JSON/XML、数据转换、格式化输出API 调用调用第三方服务、抓取外部数据文件操作读写文件、生成报告复杂计算数学运算、算法实现胶水逻辑连接不同节点的自定义逻辑。二、配置项详解Python 节点的全部配置项定义于 entity/configs/node/python_runner.py下表为官方文档给出的完整字段清单并附上源码中的默认值与校验规则字段类型必填默认值说明interpreterstring否当前 Pythonsys.executablePython 解释器路径argslist[str]否[]追加到解释器后的启动参数envdict[str, str]否{}额外环境变量会覆盖系统默认值timeout_secondsint否60脚本执行超时时间秒encodingstring否utf-8解析 stdout/stderr 的编码2.1 interpreter解释器路径指定运行脚本所用的 Python 可执行文件绝对路径。不配置时源码通过_default_interpreter()返回sys.executable or python3即当前运行工作流的进程所使用的 Python 解释器——这是最稳妥的默认选择因为它天然包含运行时环境已有的全部依赖。def _default_interpreter() - str: return sys.executable or python3如果指定的解释器路径不存在执行器会捕获FileNotFoundError并返回失败信息Interpreter {config.interpreter} not found而不是抛出难以排查的堆栈。2.2 args启动参数解释器后面的附加参数列表例如[-u]无缓冲输出、[-O]优化模式或[-X, utf8]。最终命令行由执行器组装为cmd [config.interpreter] if config.args: cmd.extend(config.args) cmd.append(str(script_path))即interpreter args 脚本路径。源码解析时使用ensure_list将args统一为字符串列表保证 YAML 中单条字符串也会被正确转换成列表。2.3 env额外环境变量以dict[str, str]形式传入的附加环境变量。执行时它们被合并进系统环境变量的拷贝中env.update(config.env or {})因此同名变量会覆盖系统默认值这正是官方文档强调「会覆盖系统默认值」的原因。在脚本内通过os.getenv(KEY)即可读取。2.4 timeout_seconds超时控制脚本执行的超时时间默认 60 秒。源码校验要求其为正整数timeout_seconds must be a positive integer执行时作为subprocess.run(timeout...)参数传入。超时后会返回失败消息Script did not finish within {config.timeout_seconds}s同时保留已产生的部分 stdout。2.5 encoding输出编码解析子进程 stdout/stderr 字节流时使用的编码默认utf-8。源码使用completed.stdout.decode(config.encoding, errorsreplace)解码errorsreplace意味着遇到非法字节会替换为占位符而不是直接崩溃保证了中英文混合输出的健壮性。当脚本输出非 UTF-8 内容如 GBK 日志时可在此指定对应编码。三、核心机制共享代码工作区code_workspace/Python 脚本统一在共享的code_workspace/目录下执行这是 Python 节点最核心的运行模型官方文档明确了三点脚本可以读写该目录中的文件多个 Python 节点共享同一工作区工作区在单次工作流执行期间持久化。3.1 工作区的创建与定位执行器在 runtime/node/executor/python_executor.py 的_ensure_workspace_root()中完成工作区的惰性创建先从执行上下文的全局状态中读取键python_workspace_rootWORKSPACE_KEY若已存在则复用否则从graph_directory图所属目录下拼接code_workspace并mkdir创建把解析后的绝对路径写回全局状态供本次工作流中的所有 Python 节点共享。因此整个会话/工作流内只有一个code_workspace位置即WareHouse/session/code_workspace/见 docs/user_guide/en/index.md。会话执行完成后工作区随会话生命周期结束而被清理。3.2 附件与工作区的联动上传到会话的附件会被自动同步进code_workspace/attachments/见 docs/user_guide/en/attachments.md因此 Python 节点可以直接读取用户上传的数据文件这也是「数据分析类工作流」能够落地的关键前提Agent 分析附件 → 生成处理代码 → Python 节点在包含附件的工作区内执行。四、输入输出与执行原理源码级4.1 输入代码从哪里来Python 节点自身不配置代码内容它的输入是上游节点的最后一条 Message。执行器通过_extract_code()处理match _CODE_BLOCK_RE.search(raw) code match.group(code) if match else raw return textwrap.dedent(code).strip()_CODE_BLOCK_RE匹配python ...形式的 Markdown 代码块如果消息中没有代码块则整段原始文本被当作代码执行。这意味着Agent 节点只要在回复中包裹python代码块Python 节点就会自动提取并执行这也解释了官方文档典型示例中 Agent 的 role 要求「代码应当包裹在python之间」的原因。若上游没有任何可执行代码节点会返回失败消息No executable code segment found。4.2 落盘脚本文件的命名提取出的代码被写入code_workspace/下的脚本文件命名规则见_write_script_file()python_executor.py文件名 节点 id 中的安全字符[0-9A-Za-z_-]其余替换为_.py同一节点第二次执行时追加_run-N后缀如Data_Processor_run-2.py避免循环工作流中脚本互相覆盖写入使用utf-8编码并保证末尾换行。4.3 执行subprocess 子进程模型执行核心是_run_process()python_executor.py关键点如下工作目录cwdstr(workspace)脚本内相对路径均相对于code_workspace/环境变量在系统环境拷贝上叠加config.env再注入三个运行时变量MAC_CODE_WORKSPACE工作区绝对路径MAC_CODE_SCRIPT当前脚本绝对路径MAC_NODE_ID当前节点 id。输出捕获capture_outputTruestdout/stderr 均被捕获超时timeoutconfig.timeout_seconds超时抛出TimeoutExpired并转为失败消息错误处理解释器不存在返回FileNotFoundError友好提示非零退出码视为失败。4.4 输出stdout 即 Message成功脚本的 stdout 内容去编码后作为一条roleASSISTANT的 Message 传递给下游节点metadata中携带workspace与script_path失败生成内容以CODE EXECUTION FAILED开头、包含错误文本、exit_code、stderr及脚本路径的失败 Message。正因为「stdout 即下游输入」官方文档中的代码规范才特别强调数据清洗脚本必须以print(output_filename)输出结果文件名见 yaml_instance/data_visualization_basic.yaml这样下游 Agent 才能拿到「产物在哪」这一关键信息。五、YAML 配置示例5.1 基础配置nodes: - id: Data Processor type: python config: timeout_seconds: 120 env: key: value5.2 指定解释器和参数nodes: - id: Script Runner type: python config: interpreter: /usr/bin/python3.11 timeout_seconds: 300 encoding: utf-85.3 官方典型工作流Agent 生成代码 → Python 执行nodes: - id: LLM Generator type: agent config: provider: openai name: gpt-4o api_key: ${API_KEY} role: 你需要根据用户的输入生成可执行的 Python 代码。代码应当包裹在 python 之间。 - id: Result Parser type: python config: timeout_seconds: 30 edges: - from: LLM Generator to: Result Parser5.4 仓库真实示例用户输入 → 代码执行yaml_instance/demo_code.yaml 是仓库中最简单的 Python 节点实战由 human 节点收集用户代码Python 节点直接执行version: 0.0.0 vars: {} graph: id: code_run description: Human provides code, then a Python node executes it. is_majority_voting: false start: - A nodes: - id: A type: human config: description: Please write a piece of code. - id: B type: python config: timeout_seconds: 60 edges: - from: A to: B5.5 进阶基于条件边的「生成 → 执行 → 校验」闭环在 yaml_instance/data_visualization_basic.yaml 的数据可视化工作流中Python 节点被反复用于执行 Agent 生成的清洗/绘图代码并与两个条件边函数配合实现自动重试code_pass当 Python 节点执行成功stdout 非空且退出码为 0时Cleaning Executor的结果才允许流回Data Analyst进入下一步第 190-196 行code_fail当执行失败时Visualization Executor的结果经trigger: true边送回Visualization Programmer要求其修复代码第 218-229 行。这个模式说明 Python 节点的「失败也作为 Message 输出」特性与条件边结合后可以天然构成代码自愈循环执行失败 → 反馈错误 → Agent 改写 → 重新执行直至成功。六、注意事项与最佳实践官方文档给出的注意事项结合源码可进一步细化为以下实践建议脚本文件放在code_workspace/下由于子进程cwd就是工作区脚本内应使用相对路径读写文件如需引用附件路径形如attachments/filename。长时间运行脚本适当调大timeout_seconds默认 60 秒对安装依赖、下载大文件或训练模型类任务通常不够超时会导致脚本被直接终止且无法恢复已产生的部分输出。用env传参脚本内os.getenv读取API Key、URL 等敏感配置建议通过${VAR}占位符在 YAML 顶层注入再由节点env透传给子进程。让脚本主动print关键产物路径stdout 是下游 Agent 获取结果的唯一通道输出「文件已保存为 xxx.csv」这类信息能显著提升下游 Agent 的决策质量。依赖缺失时由 Agent 预装如需第三方库可在上游 Agent 的 tooling 中配置install_python_packages工具见 yaml_instance/data_visualization_basic.yaml或在脚本内先pip install再执行。编码不匹配时显式指定encoding脚本输出中文日志出现乱码时检查并设置正确的输出编码。七、延伸阅读配置字段的权威定义与前端表单元数据entity/configs/node/python_runner.py执行器完整实现代码提取、脚本落盘、子进程管理、失败消息构造runtime/node/executor/python_executor.py节点类型注册与资源限制声明runtime/node/builtin_nodes.py节点注册与 Schema 自动生成的通用机制runtime/node/registry.py工作区与附件生命周期总览docs/user_guide/en/index.md、docs/user_guide/en/attachments.md中文版官方文档docs/user_guide/zh/nodes/python.md可运行的仓库示例yaml_instance/demo_code.yaml、yaml_instance/data_visualization_basic.yaml【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ChatDev 2.0 Python 节点完全指南在工作流中执行 Python 脚本的配置、原理与实战【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev导读Python 节点是 ChatDev 2.0 多智能体工作流中的通用执行单元用于在工作流内部直接运行 Python 脚本或内联代码实现自定义数据处理、API 调用、文件读写与胶水逻辑。本文以 Python 节点官方文档 为主线结合仓库内配置类与执行器的真实实现逐项拆解五个核心配置参数、code_workspace/共享工作区的运行机制、代码从上游消息提取到子进程执行的完整链路并给出可直接运行的 YAML 配置示例。读完本文你将掌握如何在自己的工作流中正确地编排 Python 节点、设置解释器与超时、传递环境变量以及如何用条件边实现「生成代码 → 执行 → 校验」的自动闭环。一、Python 节点是什么Python 节点节点类型python用于在工作流中执行 Python 脚本或内联代码。它本身不包含任何业务代码而是充当一个「执行器」把上游节点通常是 Agent 节点输出的 Python 代码块提取出来写入共享工作区交给系统 Python 解释器以子进程方式运行再把运行结果stdout作为 Message 传递给下游节点。在节点注册表 runtime/node/builtin_nodes.py 中python类型被注册为register_node_type( python, config_clsPythonRunnerConfig, executor_clsPythonNodeExecutor, capabilitiesNodeCapabilities( resource_keynode_type:python, resource_limit1, ), summaryExecutes repository Python snippets, )其中resource_keynode_type:python与resource_limit1表示该节点类型受资源管理器约束默认同一类型资源上限为 1所有 Python 节点在资源层面共享同一工作区。节点注册后runtime/node/registry.py 会自动为它生成对应的配置 Schema因此配置校验、前端表单渲染与运行执行使用同一份字段定义保证配置与实际行为一致。典型适用场景官方文档明确列出的场景包括数据处理解析 JSON/XML、数据转换、格式化输出API 调用调用第三方服务、抓取外部数据文件操作读写文件、生成报告复杂计算数学运算、算法实现胶水逻辑连接不同节点的自定义逻辑。二、配置项详解Python 节点的全部配置项定义于 entity/configs/node/python_runner.py下表为官方文档给出的完整字段清单并附上源码中的默认值与校验规则字段类型必填默认值说明interpreterstring否当前 Pythonsys.executablePython 解释器路径argslist[str]否[]追加到解释器后的启动参数envdict[str, str]否{}额外环境变量会覆盖系统默认值timeout_secondsint否60脚本执行超时时间秒encodingstring否utf-8解析 stdout/stderr 的编码2.1 interpreter解释器路径指定运行脚本所用的 Python 可执行文件绝对路径。不配置时源码通过_default_interpreter()返回sys.executable or python3即当前运行工作流的进程所使用的 Python 解释器——这是最稳妥的默认选择因为它天然包含运行时环境已有的全部依赖。def _default_interpreter() - str: return sys.executable or python3如果指定的解释器路径不存在执行器会捕获FileNotFoundError并返回失败信息Interpreter {config.interpreter} not found而不是抛出难以排查的堆栈。2.2 args启动参数解释器后面的附加参数列表例如[-u]无缓冲输出、[-O]优化模式或[-X, utf8]。最终命令行由执行器组装为cmd [config.interpreter] if config.args: cmd.extend(config.args) cmd.append(str(script_path))即interpreter args 脚本路径。源码解析时使用ensure_list将args统一为字符串列表保证 YAML 中单条字符串也会被正确转换成列表。2.3 env额外环境变量以dict[str, str]形式传入的附加环境变量。执行时它们被合并进系统环境变量的拷贝中env.update(config.env or {})因此同名变量会覆盖系统默认值这正是官方文档强调「会覆盖系统默认值」的原因。在脚本内通过os.getenv(KEY)即可读取。2.4 timeout_seconds超时控制脚本执行的超时时间默认 60 秒。源码校验要求其为正整数timeout_seconds must be a positive integer执行时作为subprocess.run(timeout...)参数传入。超时后会返回失败消息Script did not finish within {config.timeout_seconds}s同时保留已产生的部分 stdout。2.5 encoding输出编码解析子进程 stdout/stderr 字节流时使用的编码默认utf-8。源码使用completed.stdout.decode(config.encoding, errorsreplace)解码errorsreplace意味着遇到非法字节会替换为占位符而不是直接崩溃保证了中英文混合输出的健壮性。当脚本输出非 UTF-8 内容如 GBK 日志时可在此指定对应编码。三、核心机制共享代码工作区code_workspace/Python 脚本统一在共享的code_workspace/目录下执行这是 Python 节点最核心的运行模型官方文档明确了三点脚本可以读写该目录中的文件多个 Python 节点共享同一工作区工作区在单次工作流执行期间持久化。3.1 工作区的创建与定位执行器在 runtime/node/executor/python_executor.py 的_ensure_workspace_root()中完成工作区的惰性创建先从执行上下文的全局状态中读取键python_workspace_rootWORKSPACE_KEY若已存在则复用否则从graph_directory图所属目录下拼接code_workspace并mkdir创建把解析后的绝对路径写回全局状态供本次工作流中的所有 Python 节点共享。因此整个会话/工作流内只有一个code_workspace位置即WareHouse/session/code_workspace/见 docs/user_guide/en/index.md。会话执行完成后工作区随会话生命周期结束而被清理。3.2 附件与工作区的联动上传到会话的附件会被自动同步进code_workspace/attachments/见 docs/user_guide/en/attachments.md因此 Python 节点可以直接读取用户上传的数据文件这也是「数据分析类工作流」能够落地的关键前提Agent 分析附件 → 生成处理代码 → Python 节点在包含附件的工作区内执行。四、输入输出与执行原理源码级4.1 输入代码从哪里来Python 节点自身不配置代码内容它的输入是上游节点的最后一条 Message。执行器通过_extract_code()处理match _CODE_BLOCK_RE.search(raw) code match.group(code) if match else raw return textwrap.dedent(code).strip()_CODE_BLOCK_RE匹配python ...形式的 Markdown 代码块如果消息中没有代码块则整段原始文本被当作代码执行。这意味着Agent 节点只要在回复中包裹python代码块Python 节点就会自动提取并执行这也解释了官方文档典型示例中 Agent 的 role 要求「代码应当包裹在python之间」的原因。若上游没有任何可执行代码节点会返回失败消息No executable code segment found。4.2 落盘脚本文件的命名提取出的代码被写入code_workspace/下的脚本文件命名规则见_write_script_file()python_executor.py文件名 节点 id 中的安全字符[0-9A-Za-z_-]其余替换为_.py同一节点第二次执行时追加_run-N后缀如Data_Processor_run-2.py避免循环工作流中脚本互相覆盖写入使用utf-8编码并保证末尾换行。4.3 执行subprocess 子进程模型执行核心是_run_process()python_executor.py关键点如下工作目录cwdstr(workspace)脚本内相对路径均相对于code_workspace/环境变量在系统环境拷贝上叠加config.env再注入三个运行时变量MAC_CODE_WORKSPACE工作区绝对路径MAC_CODE_SCRIPT当前脚本绝对路径MAC_NODE_ID当前节点 id。输出捕获capture_outputTruestdout/stderr 均被捕获超时timeoutconfig.timeout_seconds超时抛出TimeoutExpired并转为失败消息错误处理解释器不存在返回FileNotFoundError友好提示非零退出码视为失败。4.4 输出stdout 即 Message成功脚本的 stdout 内容去编码后作为一条roleASSISTANT的 Message 传递给下游节点metadata中携带workspace与script_path失败生成内容以CODE EXECUTION FAILED开头、包含错误文本、exit_code、stderr及脚本路径的失败 Message。正因为「stdout 即下游输入」官方文档中的代码规范才特别强调数据清洗脚本必须以print(output_filename)输出结果文件名见 yaml_instance/data_visualization_basic.yaml这样下游 Agent 才能拿到「产物在哪」这一关键信息。五、YAML 配置示例5.1 基础配置nodes: - id: Data Processor type: python config: timeout_seconds: 120 env: key: value5.2 指定解释器和参数nodes: - id: Script Runner type: python config: interpreter: /usr/bin/python3.11 timeout_seconds: 300 encoding: utf-85.3 官方典型工作流Agent 生成代码 → Python 执行nodes: - id: LLM Generator type: agent config: provider: openai name: gpt-4o api_key: ${API_KEY} role: 你需要根据用户的输入生成可执行的 Python 代码。代码应当包裹在 python 之间。 - id: Result Parser type: python config: timeout_seconds: 30 edges: - from: LLM Generator to: Result Parser5.4 仓库真实示例用户输入 → 代码执行yaml_instance/demo_code.yaml 是仓库中最简单的 Python 节点实战由 human 节点收集用户代码Python 节点直接执行version: 0.0.0 vars: {} graph: id: code_run description: Human provides code, then a Python node executes it. is_majority_voting: false start: - A nodes: - id: A type: human config: description: Please write a piece of code. - id: B type: python config: timeout_seconds: 60 edges: - from: A to: B5.5 进阶基于条件边的「生成 → 执行 → 校验」闭环在 yaml_instance/data_visualization_basic.yaml 的数据可视化工作流中Python 节点被反复用于执行 Agent 生成的清洗/绘图代码并与两个条件边函数配合实现自动重试code_pass当 Python 节点执行成功stdout 非空且退出码为 0时Cleaning Executor的结果才允许流回Data Analyst进入下一步第 190-196 行code_fail当执行失败时Visualization Executor的结果经trigger: true边送回Visualization Programmer要求其修复代码第 218-229 行。这个模式说明 Python 节点的「失败也作为 Message 输出」特性与条件边结合后可以天然构成代码自愈循环执行失败 → 反馈错误 → Agent 改写 → 重新执行直至成功。六、注意事项与最佳实践官方文档给出的注意事项结合源码可进一步细化为以下实践建议脚本文件放在code_workspace/下由于子进程cwd就是工作区脚本内应使用相对路径读写文件如需引用附件路径形如attachments/filename。长时间运行脚本适当调大timeout_seconds默认 60 秒对安装依赖、下载大文件或训练模型类任务通常不够超时会导致脚本被直接终止且无法恢复已产生的部分输出。用env传参脚本内os.getenv读取API Key、URL 等敏感配置建议通过${VAR}占位符在 YAML 顶层注入再由节点env透传给子进程。让脚本主动print关键产物路径stdout 是下游 Agent 获取结果的唯一通道输出「文件已保存为 xxx.csv」这类信息能显著提升下游 Agent 的决策质量。依赖缺失时由 Agent 预装如需第三方库可在上游 Agent 的 tooling 中配置install_python_packages工具见 yaml_instance/data_visualization_basic.yaml或在脚本内先pip install再执行。编码不匹配时显式指定encoding脚本输出中文日志出现乱码时检查并设置正确的输出编码。七、延伸阅读配置字段的权威定义与前端表单元数据entity/configs/node/python_runner.py执行器完整实现代码提取、脚本落盘、子进程管理、失败消息构造runtime/node/executor/python_executor.py节点类型注册与资源限制声明runtime/node/builtin_nodes.py节点注册与 Schema 自动生成的通用机制runtime/node/registry.py工作区与附件生命周期总览docs/user_guide/en/index.md、docs/user_guide/en/attachments.md中文版官方文档docs/user_guide/zh/nodes/python.md可运行的仓库示例yaml_instance/demo_code.yaml、yaml_instance/data_visualization_basic.yaml【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
