Skip to main content

工具使用概览

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

核心概念​

工具组​

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

类别用途工具常见用途
读取组文件系统读取和探索read_file、list_files、list_code_definition_names代码探索和分析
搜索组模式和语义搜索search_files、codebase_search查找代码模式和功能
编辑组文件系统修改apply_diff、write_to_file代码更改和文件操作
浏览器组Web 自动化browser_actionWeb 测试和交互
命令组系统命令执行execute_command、run_slash_command*运行脚本、构建项目、执行命令模板
MCP 组外部工具集成use_mcp_tool、access_mcp_resource通过外部服务器实现专门功能
工作流组模式和任务管理switch_mode、new_task、ask_followup_question、attempt_completion上下文切换和任务组织

*实验性功能 - 需要在设置中明确启用

始终可用的工具​

某些工具无论当前处于何种模式都可以访问：

可用工具​

读取工具​

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

搜索工具​

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

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

编辑工具​

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

  • apply_diff - 对代码进行精确、手术式的更改
  • write_to_file - 创建新文件或完全重写现有文件

浏览器工具​

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

命令工具​

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

MCP 工具​

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

工作流工具​

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

工具调用机制​

处理复杂任务​

对于某些需要多个步骤的复杂操作，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. 错误处理

    • 实现适当的错误检查
    • 提供有意义的错误消息
    • 优雅处理失败情况

常见模式​

  1. 信息收集

    [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)

  2. 代码修改

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

  3. 任务管理

    [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. 用户干预

    • 错误通知
    • 恢复建议
    • 手动干预选项