跳转到内容
Gemini CLI 文档

Gemini CLI 核心：工具 API

Gemini CLI 核心：工具 API

Section titled “Gemini CLI 核心：工具 API”

Gemini CLI 核心（packages/core）提供了一个健壮的系统，用于定义、注册和执行工具。这些工具扩展了Gemini模型的功能，使其能够与本地环境交互，获取网络内容，以及执行超出简单文本生成的各种操作。

核心概念

Section titled “核心概念”

  • 工具 (tools.ts): 一个接口和基类（BaseTool），定义了所有工具的合约。每个工具必须具备以下特点：

    • name: 一个唯一的内部名称（用于 Gemini 的 API 调用中）。
    • displayName: 一个用户友好的名称。
    • description: 对工具功能的清晰解释，提供给Gemini模型。
    • parameterSchema: 一个 JSON 架构，定义了工具接受的参数。这对于Gemini模型正确理解如何调用工具至关重要。
    • validateToolParams(): 一种验证传入参数的方法。
    • getDescription(): 一种提供工具在执行前针对特定参数将执行的操作的人类可读描述的方法。
    • shouldConfirmExecute(): 一种确定在执行前是否需要用户确认的方法（例如，对于可能具有破坏性的操作）。
    • execute(): 执行工具动作的核心方法，并返回一个 ToolResult。

  • ToolResult (tools.ts): 定义工具执行结果结构的接口：

    • llmContent: 要包含在发送回 LLM 的历史记录中的事实内容。这可以是一个简单的字符串或一个 PartListUnion（一个 Part 对象和字符串的数组）以支持丰富内容。
    • returnDisplay: 一个用户友好的字符串（通常是 Markdown）或一个特殊对象（如 FileDiff）以在 CLI 中显示。

返回丰富内容： 工具不仅限于返回简单文本。llmContent 可以是一个 PartListUnion，这是一个可以包含 Part 对象（用于图像、音频等）和 string 的数组。这使得单个工具执行能够返回多个丰富的内容片段。

工具注册表（tool-registry.ts）： 一个类（ToolRegistry）负责：

  • 注册工具： 保持所有可用的内置工具的集合（例如，ReadFileTool，ShellTool）。
  • 发现工具： 它还可以动态地发现工具：
    • 基于命令的发现： 如果在设置中配置了 tools.discoveryCommand，将执行此命令。预期它将输出描述自定义工具的 JSON，然后这些工具将作为 DiscoveredTool 实例注册。
    • 基于MCP的发现： 如果配置了 mcp.serverCommand，注册表可以连接到 Model Context Protocol (MCP) 服务器以列出和注册工具（DiscoveredMCPTool）。
  • 提供架构： 向 Gemini 模型公开所有注册工具的 FunctionDeclaration 架构，以便它知道哪些工具可用以及如何使用它们。
  • 检索工具： 允许核心通过名称获取特定的工具以执行。

内置工具

Section titled “内置工具”

核心附带了一套预定义的工具，通常可以在 packages/core/src/tools/ 中找到。这些包括：

文件系统工具：

  • LSTool (ls.ts): 列出目录内容。
  • ReadFileTool (read-file.ts): 读取单个文件的内容。
  • WriteFileTool (write-file.ts): 将内容写入文件。
  • GrepTool (grep.ts): 在文件中搜索模式。
  • GlobTool (glob.ts): 查找与 glob 模式匹配的文件。
  • EditTool (edit.ts): 对文件进行就地修改（通常需要确认）。
  • ReadManyFilesTool (read-many-files.ts): 从多个文件或 glob 模式读取并连接内容（在 CLI 中的 @ 命令中使用）。

执行工具：

  • ShellTool (shell.ts): 执行任意 shell 命令（需要谨慎的沙箱处理和用户确认）。

网络工具：

  • WebFetchTool (web-fetch.ts): 从 URL 获取内容。
  • WebSearchTool (web-search.ts): 执行网络搜索。

内存工具：

  • MemoryTool (memoryTool.ts): 与 AI 的内存交互。

每个工具都扩展了 BaseTool 并实现了其特定功能所需的方法。

工具执行流程

Section titled “工具执行流程”
  1. 模型请求： Gemini模型根据用户的提示和提供的工具架构，决定使用一个工具，并在其响应中返回一个FunctionCall部分，指定工具名称和参数。
  2. 核心接收请求： 核心解析这个FunctionCall。
  3. 工具检索： 它在ToolRegistry中查找请求的工具。
  4. 参数验证： 调用工具的validateToolParams()方法。
  5. 确认（如需）：
    • 调用工具的shouldConfirmExecute()方法。
    • 如果它返回需要确认的详细信息，核心将这些信息传递回CLI，CLI提示用户。
    • 用户的决定（例如，继续，取消）会被发送回核心。
  6. 执行： 如果验证并确认（或者无需确认），核心使用提供的参数和AbortSignal（用于可能的取消）调用工具的execute()方法。
  7. 结果处理： 核心ToolResult从execute()接收。
  8. 响应模型： 来自ToolResult的llmContent被包装为FunctionResponse并发送回Gemini模型，以便其继续生成面向用户的响应。
  9. 显示给用户： 来自ToolResult的returnDisplay被发送到CLI，以展示工具的操作结果。

使用自定义工具扩展

Section titled “使用自定义工具扩展”

虽然直接通过编程方式由用户注册新工具在提供的文件中没有明确作为典型最终用户的主要工作流程详细说明，但架构支持通过以下方式进行扩展：

（以下部分未提供英文原文，故未翻译）

命令式发现： 高级用户或项目管理员可以在 tools.discoveryCommand 中定义一个命令。当此命令由 Gemini CLI 核心运行时，应输出一个 JSON 数组的 FunctionDeclaration 对象。核心程序然后将它们作为 DiscoveredTool 实例提供。相应的 tools.callCommand 将负责实际执行这些自定义工具。 MCP 服务器： 对于更复杂的场景，可以通过 settings.json 中的 mcpServers 设置来设置和配置一个或多个 MCP 服务器。Gemini CLI 核心程序可以发现并使用这些服务器暴露的工具。如前所述，如果您有多个 MCP 服务器，工具名称将使用配置中的服务器名称作为前缀（例如，serverAlias__actualToolName）。

这个工具系统提供了一种灵活且强大的方法来增强 Gemini 模型的功能，使 Gemini CLI 成为一个适用于广泛任务的多功能助手。