工具使用概述

Roo Code 实现了一个复杂的工具系统，允许 AI 模型以受控且安全的方式与您的开发环境进行交互。本文档解释了工具如何工作、何时被调用以及如何进行管理。

核心概念

工具组

工具根据其功能被组织成逻辑组：

始终可用的工具

某些工具无论当前模式如何始终可访问，包括：

• ask_followup_question: 从用户那里收集额外信息。
• attempt_completion: 发出任务完成信号。
• switch_mode: 更改操作模式。
• new_task: 创建子任务。

可用工具

读取工具

这些工具帮助 Roo 理解您的代码和项目：

• read_file - 检查文件内容
• list_files - 映射您的项目文件结构
• list_code_definition_names - 创建您的代码的结构化地图

搜索工具

这些工具帮助 Roo 在您的代码库中查找模式和功能：

• search_files - 使用正则表达式在多个文件中查找模式
• codebase_search - 在您的索引代码库中执行语义搜索

编辑工具

这些工具帮助 Roo 对您的代码进行更改：

• apply_diff - 对您的代码进行精确、细致的更改
• insert_content - 添加新行内容而不修改现有行
• search_and_replace - 在文件中查找和替换文本或正则表达式模式
• write_to_file - 创建新文件或完全重写现有文件

浏览器工具

这些工具帮助 Roo 与 Web 应用程序交互：

• browser_action - 自动化浏览器交互

命令工具

这些工具帮助 Roo 执行命令：

• execute_command - 运行系统命令和程序

MCP 工具

这些工具帮助 Roo 连接到外部服务：

• use_mcp_tool - 使用专业的外部工具
• access_mcp_resource - 访问外部数据源

工作流工具

这些工具帮助管理对话和任务流：

• ask_followup_question - 从您那里获取额外信息
• attempt_completion - 呈现最终结果
• switch_mode - 切换到不同模式以执行专业任务
• new_task - 创建新子任务

工具调用机制

处理复杂任务

对于某些需要多个步骤的复杂操作，Roo 不会即兴处理。相反，它遵循预定义的内部计划，以确保一致性和准确性。

一个典型的例子是创建新的 MCP 服务器，其内部标识符为 create_mcp_server。这个标识符不代表您将看到的被调用的工具。相反，当您要求 Roo 创建服务器时，它会触发这个已知的、多步骤的工作流程。

这个特定的工作流程由 Roo 使用其内部的 fetch_instructions 工具（任务为 create_mcp_server）启动，以检索详细计划。该计划随后指导 Roo 按顺序调用多个标准的、有文档记录的工具，例如：

• execute_command 用于运行设置脚本（例如，npx @modelcontextprotocol/create-server）。
• write_to_file 或 apply_diff 用于创建或修改服务器代码和配置文件。
• ask_followup_question 用于从您那里收集必要的信息，例如 API 密钥。
• 根据需要使用其他标准工具，用于确定文件位置或更新配置条目等步骤。

因此，虽然整个任务（如 create_mcp_server）很复杂，但它最终是通过智能地编排环境中可用的标准工具来完成的。这种方法使 Roo 能够通过利用此处记录的工具可靠地执行复杂操作。

何时调用工具

工具在特定条件下被调用：

1. 直接任务要求

• 当需要特定操作来完成 LLM（大型语言模型）决定的任务时。
• 响应用户请求时。
• 在自动化工作流期间。

2. 基于模式的可用性

• 不同的模式启用不同的工具集。
• 模式切换可以触发工具可用性更改。
• 某些工具仅限于特定模式。

3. 上下文相关的调用

• 基于工作区的当前状态。
• 响应系统事件时。
• 在错误处理和恢复期间。

决策过程

系统使用一个多步过程来确定工具可用性，包括：

1. 模式验证:

   isToolAllowedForMode(
       tool: string,
       modeSlug: string,
       customModes: ModeConfig[],
       toolRequirements?: Record<string, boolean>,
       toolParams?: Record<string, any>
   )
   

2. 要求检查
   • 系统能力验证
   • 资源可用性
   • 权限验证
3. 参数验证
   • 必需参数是否存在
   • 参数类型检查
   • 值验证

技术实现

工具调用过程

1. 初始化
   • 工具名称和参数被验证
   • 模式兼容性被检查
   • 要求被验证
2. 执行

   const toolCall = {
       type: "tool_call",
       name: chunk.name,
       arguments: chunk.input,
       callId: chunk.callId
   }
   

3. 结果处理
   • 成功/失败判定
   • 结果格式化
   • 错误处理

安全和权限

1. 访问控制
   • 文件系统限制
   • 命令执行限制
   • 网络访问控制
2. 验证层
   • 工具特定验证
   • 基于模式的限制
   • 系统级检查

模型集成

基于模式的工具访问

工具根据当前模式变为可用：

• 代码模式：完全访问文件系统工具、代码编辑功能和命令执行。
• 询问模式：仅限于读取工具和信息收集功能，不能修改文件系统。
• 架构师模式：侧重于设计工具、文档功能，执行权限有限。
• 自定义模式：可以配置特定的工具访问权限，以实现专业工作流。

模式切换

1. 过程
   • 保存当前模式状态。
   • 更新工具可用性。
   • 切换上下文。
2. 对工具的影响
   • 工具集发生变化。
   • 权限进行调整。
   • 上下文得到保存。

最佳实践

工具使用指南

1. 效率
   • 为任务使用最具体的工具。
   • 避免冗余的工具调用。
   • 在可能的情况下进行批量操作。
2. 安全
   • 在进行工具调用之前验证输入。
   • 使用所需的最小权限。
   • 遵循安全最佳实践。
3. 错误处理
   • 实施适当的错误检查。
   • 提供有意义的错误消息。
   • 优雅地处理失败。

常见模式

• 信息收集:

[ask_followup_question](/advanced-usage/available-tools/ask-followup-question) → [read_file](/advanced-usage/available-tools/read-file) → [codebase_search](/advanced-usage/available-tools/codebase-search)

• 代码修改:

[read_file](/advanced-usage/available-tools/read-file) → [apply_diff](/advanced-usage/available-tools/apply-diff) → [attempt_completion](/advanced-usage/available-tools/attempt-completion)

• 任务管理:

[new_task](/advanced-usage/available-tools/new-task) → [switch_mode](/advanced-usage/available-tools/switch-mode) → [execute_command](/advanced-usage/available-tools/execute-command)

错误处理和恢复

错误类型

1. 工具特定错误
   • 参数验证失败
   • 执行错误
   • 资源访问问题
2. 系统错误
   • 权限被拒绝
   • 资源不可用
   • 网络故障
3. 上下文错误
   • 工具的模式无效
   • 缺少要求
   • 状态不一致

恢复策略

1. 自动恢复
   • 重试机制
   • 回退选项
   • 状态恢复
2. 用户干预
   • 错误通知
   • 恢复建议
   • 手动干预选项