ChatDev 2.0 Function Tooling 配置指南为 Agent 节点接入仓库内 Python 函数【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDevFunctionToolConfig是 ChatDev 2.0 中面向 Agent 节点的函数工具适配器它允许你把仓库functions/function_calling/下的任意 Python 函数注册为可被大模型调用Function Calling的工具。本文围绕 Function Tooling 配置指南 展开从配置字段、目录规范、上下文注入、扩展流程到排错实践完整讲解如何编写、注册、引用和调试函数工具同时结合entity/configs/node/tooling.py、utils/function_catalog.py、runtime/node/agent/tool/tool_manager.py等源码剖析函数清单生成、module_name:All批量展开、JSON Schema 自动生成与_context注入的底层实现。读完本文你将能够独立为 Agent 节点扩展任意自定义 Python 工具并理解其在多 Agent 协作中的完整调用链。1. 配置字段总览FunctionToolConfig通过 Agent 节点配置中的tooling块启用其核心字段如下字段说明tools列表元素为FunctionToolEntryConfig。每个条目至少包含name。timeout单次工具执行的超时时间秒可选未设置时不限制。auto_load是否在启动时自动加载函数目录默认true源码auto_load: bool True见 entity/configs/node/tooling.py。FunctionToolEntryConfig字段name函数名来自functions/function_calling/文件的顶级函数必填。description覆盖自动解析的函数描述可选。注意当auto_fill开启且未填写时会由源码自动填充。parameters覆盖自动生成的 JSON Schema可选。auto_fill是否基于 Python 函数签名自动生成描述与参数 Schema默认true。值得说明的是虽然FunctionToolEntryConfig中定义了description、parameters、auto_fill三个字段但从 entity/configs/node/tooling.py 的FIELD_SPECS可以看到它们目前在前端表单中被注释隐藏advance高级字段主要用于 YAML 手工配置场景。这与module_name:All的限制逻辑相互呼应见下文第 3 节。1.1 配置解析与校验流程配置不是简单地“读进来就完事”FunctionToolConfig.from_dictentity/configs/node/tooling.py在解析阶段会做以下校验tools必须为非空列表否则抛出ConfigError(tools must be provided for function tooling)每个 tool 条目必须是 mapping且name为有效非空字符串若name以:All结尾先按模块批量展开见第 3 节展开后的每个函数名都必须在函数目录中真实存在否则抛出function xxx not found under function directory同一函数名不允许重复声明is declared multiple timesauto_fill必须为布尔值开启时会自动合并 docstring 描述与参数 Schematimeout必须为数值类型。这些校验保证了 YAML 中声明的每个工具在运行前就处于“可解析、可加载”状态避免运行期才报错。2. 函数目录要求路径默认functions/function_calling/可通过环境变量MAC_FUNCTIONS_DIR覆盖见 utils/function_manager.py。环境变量支持~展开与绝对/相对路径解析。函数位置必须位于模块顶层模块内__init__.py、以_开头的文件会被跳过。类型注解必须使用 Python 类型注解需要枚举或描述时使用typing.Annotated[..., ParamMeta(...)]。参数过滤不允许以_开头的参数暴露给 Agent*args、**kwargs会被过滤见 utils/function_catalog.py 中param.name.startswith(_)与VAR_POSITIONAL/VAR_KEYWORD的跳过逻辑。描述来源函数 docstring 的首段会被提取为工具描述自动截断为 600 字符见 utils/function_catalog.py 的_extract_description。2.1 函数目录的加载机制utils/function_catalog.py与utils/function_manager.py共同构成函数发现链路FunctionManager.load_functions()utils/function_manager.py会递归遍历目录下所有.py文件跳过__init__.py、_开头文件与__pycache__目录通过importlib.util.spec_from_file_location动态加载模块并用inspect.getmembers(module, inspect.isfunction)提取模块自身定义的函数。FunctionCatalog.refresh()utils/function_catalog.py在加载完成后为每个函数构建元数据名称、描述、参数 Schema、所属模块并按模块名建立索引。单函数元数据构建失败不会级联崩溃仅打印警告。get_function_catalog()按目录缓存 catalog 单例避免重复扫描。加载后的元数据会在启动时生成 JSON Schema 并暴露给前端 / CLI 使用这是第 4 节 Schema 自动生成的基础。3. 函数列表展示与module_name:All3.1 UI 展示规则前端下拉列表将每个函数展示为module_name:function_name。module_name等于函数文件相对于functions/function_calling/的路径去掉.py子目录使用/连接。这一规则由_derive_module_nameutils/function_catalog.py实现便于快速定位语义相关模块。函数与模块都采用全局字典序排列长列表更易检索YAML 中仍以真实函数名落盘module_name:All仅作为输入辅助。3.2 批量引入module_name:All每个模块顶部都会自动插入module_name:All选项且所有模块的All条目按字典序排在列表最前。该逻辑位于FunctionToolEntryConfig.field_specs()entity/configs/node/tooling.py每个模块生成{module_name}:All的EnumOption其描述会展示模块内函数数量与前 3 个函数预览。选择All会在解析阶段展开为该模块下的所有函数顺序同样遵循字典序。展开实现见_extract_module_from_all与_expand_module_all_entryentity/configs/node/tooling.py。限制module_name:All只能批量引入函数禁止同时填写description、parameters或auto_fill等覆盖字段若需要自定义请展开后针对具体函数单独配置。源码中_expand_module_all_entry会检查(description, parameters, auto_fill)任一键出现在原条目中并抛出ConfigError。4. 参数 Schema 自动生成类型注解即文档utils/function_catalog.py会在启动时为每个函数构建 JSON Schema核心链路为_build_parameters_schemautils/function_catalog.py→_annotation_to_schema→_primitive_schema。规则包括基础类型映射str → string、int → integer、float → number、bool → boolean、dict → object、list → array。复杂类型list[T]生成带items的数组 Schemadict生成 objectLiteral[...]与Enum生成带enum的 Schema。Annotated元数据ParamMeta(description..., enum...)会写入 Schema 的description与enum并自动推断枚举类型见_apply_param_meta与_infer_literal_type。可选参数识别Optional[T]/T | None会被剥离为T参数不再计入required见_strip_optional。默认值param.default非空时写入 Schema 的default字段。ParamMeta定义于 utils/function_catalog.py字段为description与enum。5. 上下文注入_context与运行时环境执行器会对被调用的函数提供_context关键字参数。以 Agent 执行器为例runtime/node/executor/agent_executor.pyexecute_tool被调用时传入tool_contextself.context.global_state随后 tool_manager.py 的_execute_function_tool会检测函数签名是否接受_context_function_accepts_context支持_context命名参数或**kwargs再将其注入。_context键值表键值attachment_storeutils.attachments.AttachmentStore实例可查询/注册附件。python_workspace_root当前 Session 的code_workspace/。graph_directorySession 根目录可推导相对路径。human_promptutils.human_prompt.HumanPromptService可调用request()触发人工反馈。其他视运行环境扩展例如session_id、node_id。函数可声明_context: dict | None None并自行解析。最佳实践是参考 functions/function_calling/file.py 的FileToolContext它从_context中提取attachment_store、python_workspace_root、graph_directory并提供resolve_under_workspace/resolve_under_session等路径安全校验方法阻止路径逃逸出 workspace / session。python_workspace_root缺失时FileToolContext会直接抛出ValueError保证文件类工具的路径操作始终受控。human_prompt的典型用法见 functions/function_calling/user.py 的call_user通过_context.get(human_prompt)调用prompt.request(...)将指令发送给人类用户并返回其响应若上下文缺失则返回降级文本避免工具崩溃。6. 完整示例文件读取工具6.1 编写函数from typing import Annotated from utils.function_catalog import ParamMeta def read_text_file( path: Annotated[str, ParamMeta(descriptionworkspace 相对路径)], *, encoding: str utf-8, _context: dict | None None, ) - str: ctx FileToolContext(_context) target ctx.resolve_under_workspace(path) return target.read_text(encodingencoding)说明path通过Annotated[str, ParamMeta(...)]携带中文描述最终会写入 JSON Schema 的descriptionencoding有默认值utf-8因此不是必填参数_context以下划线开头不会被暴露给 Agent同时允许执行器注入运行时上下文。6.2 在 YAML 中引用nodes: - id: summarize type: agent config: tooling: type: function config: tools: - name: describe_available_files - name: read_text_file若希望给工具加超时限制可在config块中增加timeout: 60。实际仓库中 functions/function_calling/file.py 还提供了describe_available_files、list_directory、save_file、read_file_segment、apply_text_edits、search_in_files、load_file等一组文件工具它们都遵循“类型注解 _context注入 workspace 路径白名单”的同一范式可直接作为编写自定义文件类函数的参照。7. 扩展流程新增自定义函数工具新建模块或函数在functions/function_calling/新建.py文件或新增顶级函数。注意函数名不能以_开头参数中暴露给 Agent 的也不得以_开头。描述参数使用类型注解 ParamMeta描述参数如需禁止自动 Schema可设置auto_fill: false并提供手写parameters。处理第三方依赖若函数依赖额外第三方库可在仓库 requirements.txt / pyproject.toml 中声明或在函数内调用同目录的install_python_packages动态安装。functions/function_calling/uv_related.py 中该函数基于uv add在 workspace 内安装包并对包名做白名单正则校验拒绝-开头的 flag支持upgrade参数同模块还提供init_python_envuv lockuv venvuv init与uv_run执行模块或脚本等环境工具。刷新前端枚举运行python -m tools.export_design_template ...以刷新前端枚举tools/export_design_template.py 从类型化 Schema 生成设计模板 YAML。运行验证通过前端工作台或 CLI 加载含该tooling块的 YAML确认下拉列表中出现新函数。8. 调试与排错function xxx not found检查函数名称与文件是否位于MAC_FUNCTIONS_DIR默认functions/function_calling/。该报错同时可能源于FunctionToolConfig.from_dict的解析校验entity/configs/node/tooling.py。function_catalog加载失败FunctionToolEntryConfig.field_specs()会在name字段描述中提示错误如(loading failed: ...)先修复函数语法或依赖再重启服务重新加载 catalog。工具超时工具运行超时会向 Agent 返回异常文本可通过timeout扩大限额或在函数内部自行捕获异常并返回友好错误。执行器与ToolManager的调用链见 runtime/node/executor/agent_executor.py异常会被包装为Tool {tool_name} error: ...的 TOOL 消息回传给 Agent并通过record_tool_call记录调用日志。动态加载后不生效FunctionManager与FunctionCatalog均有按目录的缓存新增函数后若前端仍未出现可调用reload_functions()utils/function_manager.py或重启服务。9. 扩展阅读Function Tooling 配置指南英文对应英文版本文档。Tooling 模块总览function、mcp_local、mcp_remote三类工具适配器的对比与选择。MCP 工具配置通过McpRemoteConfig/McpLocalConfig接入 MCP 服务器。工具管理实现函数工具与 MCP 工具的统一注册、去重prefix防冲突与执行分发。函数目录实际示例仓库内置的file.py、web.py、weather.py、code_executor.py、deep_research.py、video.py、uv_related.py、user.py、utils.py等模块是学习函数工具编写范式的最佳范本。功能目录 Schema 生成器参数 Schema 的自动推导与 600 字符描述截断的实现细节。【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考