Skip to main content

工具使用概述

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

核心概念​

工具分组​

工具根据功能分为逻辑组：

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

始终可用的工具​

某些工具无论当前模式如何都可访问：

可用工具​

读取工具​

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

搜索工具​

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

编辑工具​

这些工具帮助Roo修改代码：

浏览器工具​

这些工具帮助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. 用户干预

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