工具API

目录

概述

Gemini CLI 核心（packages/core）具有强大的工具定义、注册和执行系统。这些工具扩展了 Gemini 模型的功能，使其能够与本地环境交互、获取网络内容，并执行超越简单文本生成的各种操作。

核心概念

工具（Tool）

工具是一个接口和基类（BaseTool），定义了所有工具的契约。每个工具必须具有：

  • name： 唯一的内部名称（用于 Gemini API 调用）
  • displayName： 用户友好的名称
  • description： 工具功能的清晰说明，提供给 Gemini 模型
  • parameterSchema： 定义工具接受参数的 JSON 模式
  • validateToolParams()： 验证传入参数的方法
  • getDescription()： 提供人类可读的工具描述方法
  • shouldConfirmExecute()： 确定是否需要用户确认的方法
  • execute()： 执行工具操作并返回 ToolResult 的核心方法

ToolResult

定义工具执行结果结构的接口：

  • llmContent： 要包含在发送回 LLM 的历史记录中的事实字符串内容
  • returnDisplay： 用户友好的字符串（通常是 Markdown）或特殊对象（如 FileDiff）在 CLI 中显示

工具注册表（Tool Registry）

负责以下功能的类（ToolRegistry）：

  • 注册工具： 保存所有可用内置工具的集合
  • 发现工具： 动态发现工具：
    • 基于命令的发现：通过 toolDiscoveryCommand 配置
    • 基于 MCP 的发现：通过 mcpServerCommand 配置
  • 提供模式： 向 Gemini 模型暴露所有注册工具的 FunctionDeclaration 模式
  • 检索工具： 允许核心按名称获取特定工具进行执行

内置工具

核心预定义了一套工具，通常位于 packages/core/src/tools/：

文件系统工具

LSTool

列出目录内容

ReadFileTool

读取单个文件内容

WriteFileTool

将内容写入文件

GrepTool

在文件中搜索模式

GlobTool

查找匹配 glob 模式的文件

EditTool

对文件进行就地修改

ReadManyFilesTool

读取并连接多个文件内容

执行工具

ShellTool

执行任意 Shell 命令

网络工具

WebFetchTool

从 URL 获取内容

WebSearchTool

执行网络搜索

记忆工具

MemoryTool

与 AI 记忆系统交互

工具执行流程

1. 模型请求

Gemini 模型基于用户提示和提供的工具模式，决定使用工具并返回 FunctionCall。

2. 核心接收请求

核心解析此 FunctionCall。

3. 工具检索

在 ToolRegistry 中查找请求的工具。

4. 参数验证

调用工具的 validateToolParams() 方法。

5. 确认（如需要）

调用工具的 shouldConfirmExecute() 方法，如需要则提示用户确认。

6. 执行

如果验证通过且确认（或无需确认），调用工具的 execute() 方法。

7. 结果处理

核心接收来自 execute() 的 ToolResult。

8. 响应模型

ToolResult 的 llmContent 被打包为 FunctionResponse 发送回 Gemini 模型。

9. 显示给用户

ToolResult 的 returnDisplay 被发送到 CLI 向用户显示工具的操作结果。

扩展自定义工具

虽然最终用户直接的编程注册新工具不是主要工作流程，但架构支持通过以下方式扩展：

基于命令的发现

高级用户或项目管理员可以在 settings.json 中定义 toolDiscoveryCommand。此命令应输出 FunctionDeclaration 对象的 JSON 数组。

MCP 服务器

对于更复杂的场景，可以设置一个或多个 MCP 服务器，并通过 settings.json 中的 mcpServers 设置配置。

多服务器支持： 如果您有多个 MCP 服务器，工具名称将以配置中的服务器名称为前缀（例如，serverAlias__actualToolName）。

总结

这个工具系统为增强 Gemini 模型的功能提供了灵活而强大的方式，使 Gemini CLI 成为各种任务的多功能助手。