工具系统

相关源文件

• examples/di/fix_github_issue.py
• examples/di/run_flask.py
• examples/di/use_github_repo.py
• metagpt/actions/di/execute_nb_code.py
• metagpt/configs/role_custom_config.py
• metagpt/environment/mgx/mgx_env.py
• metagpt/logs.py
• metagpt/prompts/di/data_analyst.py
• metagpt/prompts/di/engineer2.py
• metagpt/prompts/di/role_zero.py
• metagpt/prompts/di/team_leader.py
• metagpt/roles/di/data_analyst.py
• metagpt/roles/di/engineer2.py
• metagpt/roles/di/role_zero.py
• metagpt/roles/di/team_leader.py
• metagpt/strategy/experience_retriever.py
• metagpt/strategy/thinking_command.py
• metagpt/tools/libs/__init__.py
• metagpt/tools/libs/browser.py
• metagpt/tools/libs/editor.py
• metagpt/tools/libs/env.py
• metagpt/tools/libs/index_repo.py
• metagpt/tools/libs/linter.py
• metagpt/tools/libs/terminal.py
• metagpt/tools/swe_agent_commands/setup_default.sh
• metagpt/utils/file.py
• tests/data/tools/test_script_for_file_manager.py
• tests/metagpt/environment/mgx_env/run_mgx_env.py
• tests/metagpt/roles/di/run_engineer2.py
• tests/metagpt/tools/libs/test_editor.py
• tests/metagpt/tools/libs/test_terminal.py

工具系统是MetaGPT的核心组件，它为角色提供了与外部系统交互、操作文件、浏览网页和执行命令的能力。这个系统使角色能够在思考和沟通之外，在环境中执行具体的动作。本页面详细介绍了工具系统的架构和用法。有关角色如何将这些工具作为动态智能（Dynamic Intelligence）一部分使用，请参阅 RoleZero。

工具注册表架构

工具系统围绕着一个注册表模式构建，该模式允许工具被注册、发现并推荐给角色。

工具注册表是使工具可供角色使用的核心机制。工具通过 @register_tool 装饰器进行注册，该装饰器可以指定类中应暴露哪些函数以及工具应具有的标签。

来源: [metagpt/roles/di/role_zero.py:46-47], [metagpt/tools/tool_registry.py], [metagpt/tools/tool_recommend.py]

核心工具

MetaGPT提供了几个核心工具，这些工具对角色与其环境的交互至关重要。

编辑器

Editor工具允许角色读取、写入、编辑和搜索文件。

Editor是用于文件操作的综合性工具，具备读取、写入、编辑和导航文件的功能。它还包含一个代码检查系统，用于验证代码文件的语法错误。

来源: [metagpt/tools/libs/editor.py:73-702], [metagpt/tools/libs/linter.py:28-40]

终端

Terminal工具提供了一种执行shell命令并获取其输出的方式。

Terminal工具创建一个持久的shell进程，可以执行命令并捕获其输出。它在命令之间维护shell的状态，保留当前目录等上下文。

来源: [metagpt/tools/libs/terminal.py:15-269], [metagpt/tools/libs/terminal.py:171-245]

浏览器

Browser工具支持网页浏览、页面交互和内容提取。

Browser工具使用Playwright控制浏览器实例，允许角色导航网站、与页面元素交互以及从网页中提取内容。

来源: [metagpt/tools/libs/browser.py:32-212]

工具与角色的集成

工具主要通过RoleZero类与角色集成，该类提供了工具使用的基础。

在RoleZero类中，工具被注册在 tool_execution_map 中，该映射将命令名称映射到可调用的函数。当角色需要使用工具时，它会：

1. 获取工具推荐（可选）
2. 思考要运行的命令
3. 解析LLM输出中的命令
4. 通过工具执行映射执行命令
5. 处理结果

来源: [metagpt/roles/di/role_zero.py:97-120], [metagpt/roles/di/role_zero.py:487-522], [metagpt/roles/di/role_zero.py:198-255]

工具执行机制

工具执行机制的工作方式是：

1. 解析LLM输出中的命令
2. 在 tool_execution_map 中查找命令
3. 使用提供的参数调用函数
4. 捕获并返回输出

为特定命令提供了特殊处理，以确保正确的流程控制和错误管理。

来源: [metagpt/roles/di/role_zero.py:494-522], [metagpt/roles/di/role_zero.py:526-561]

专业工具应用

不同的角色扩展和定制工具系统以满足其特定需求。

Engineer2工具

Engineer2角色扩展了RoleZero，增加了专门用于软件开发的附加工具。

Engineer2角色增加了以下方面的专业能力：

• 编写新的代码文件
• 将项目部署到公共Web服务器
• 代码审查和改进
• 为Web项目检索图像

来源: [metagpt/roles/di/engineer2.py:30-170], [metagpt/prompts/di/engineer2.py:1-104]

DataAnalyst工具

DataAnalyst角色提供了数据分析和操作工具。

DataAnalyst角色专注于：

• 编写和执行数据分析代码
• 创建和运行笔记本
• 数据可视化
• 机器学习任务

来源: [metagpt/roles/di/data_analyst.py:26-154], [metagpt/actions/di/execute_nb_code.py:69-402]

工具命令结构

工具通常遵循标准化的命令结构，将操作表示为JSON对象。

此结构在整个系统中用于为工具执行提供一致的接口。一些特殊命令包括：

• Plan.finish_current_task: 标记当前任务已完成
• end: 表示所有需求已完成
• RoleZero.ask_human: 请求人类指导
• RoleZero.reply_to_human: 向人类用户提供回复

来源: [metagpt/prompts/di/role_zero.py:83-93], [metagpt/roles/di/role_zero.py:487-493]

经验和工具使用

工具系统通过一个经验检索机制得到增强，该机制帮助角色从过去的工具使用模式中学习。

经验检索系统提供了工具使用模式的示例，可以指导LLM创建更有效的工具命令。该系统通过 exp_cache 装饰器与RoleZero集成。

来源: [metagpt/strategy/experience_retriever.py:1-469], [metagpt/roles/di/role_zero.py:261-267]

添加新工具

可以通过以下步骤向系统添加新工具：

1. 创建具有所需工具功能的类
2. 使用 @register_tool 装饰器注册该类或其方法
3. 可选择指定 include_functions 以选择要暴露的方法
4. 更新需要使用该工具的角色中的 tool_execution_map

工具注册表可以轻松地为系统添加新功能，同时保持一致的接口。

来源: [metagpt/tools/libs/browser.py:32-46], [metagpt/tools/libs/editor.py:84-101], [metagpt/tools/libs/terminal.py:15-16], [metagpt/roles/di/engineer2.py:30]

工具与环境的通信

工具通过消息传递和事件处理程序与更广泛的环境进行通信。

诸如 ask_human 和 reply_to_human 等特殊工具通过环境促进与人类用户的直接交互，创建了一个增强角色能力的反馈循环。

来源: [metagpt/roles/di/role_zero.py:592-608], [metagpt/environment/mgx/mgx_env.py:64-71]

结论

工具系统是MetaGPT的一个强大组件，它弥合了LLM推理与现实世界具体行动之间的差距。通过提供工具注册、推荐和执行的一致接口，它使角色能够与文件交互、运行命令、浏览网页并执行各种超越简单文本生成的任务。