Gemini CLI Core: Tools API

Gemini CLI 核心 (packages/core) 包含一个强大的系统，用于定义、注册和执行工具。这些工具扩展了 Gemini 模型的能力，使其能够与本地环境交互、获取网络内容以及执行超越简单文本生成的各种操作。

核心概念

• 工具 (tools.ts): 一个接口和基类 (BaseTool)，定义了所有工具的契约。每个工具必须包含：

  • name: 一个唯一的内部名称（在调用 Gemini 的 API 时使用）。
  • displayName: 一个用户友好的名称。
  • description: 对工具功能的清晰解释，提供给 Gemini 模型。
  • parameterSchema: 一个 JSON schema，定义了工具接受的参数。这对于 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，注册表可以连接到模型上下文协议 (MCP) 服务器来列出和注册工具 (DiscoveredMCPTool)。
  • 提供 Schema: 将所有已注册工具的 FunctionDeclaration schema 暴露给 Gemini 模型，以便模型知道哪些工具可用以及如何使用它们。
  • 检索工具: 允许核心通过名称获取特定工具以进行执行。

内置工具

核心自带一套预定义的工具，通常位于 packages/core/src/tools/。这些工具包括：

• 文件系统工具:
  • LSTool (ls.ts): 列出目录内容。
  • ReadFileTool (read-file.ts): 读取单个文件的内容。它接受一个 absolute_path 参数，该参数必须是绝对路径。
  • 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 命令（需要仔细的沙箱化和用户确认）。
• Web 工具:
  • WebFetchTool (web-fetch.ts): 从 URL 获取内容。
  • WebSearchTool (web-search.ts): 执行网络搜索。
• 内存工具:
  • MemoryTool (memoryTool.ts): 与 AI 的内存交互。

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

工具执行流程

1. 模型请求: Gemini 模型根据用户的提示和提供的工具 schema，决定使用某个工具，并在其响应中返回一个 FunctionCall 部分，指定工具名称和参数。
2. 核心接收请求: 核心解析此 FunctionCall。
3. 工具检索: 在 ToolRegistry 中查找请求的工具。
4. 参数验证: 调用工具的 validateToolParams() 方法。
5. 确认（如果需要）:
   • 调用工具的 shouldConfirmExecute() 方法。
   • 如果返回了确认详情，核心会将此信息传达给 CLI，CLI 会提示用户。
   • 用户的决定（例如，继续、取消）会发送回核心。
6. 执行: 如果验证通过且已确认（或无需确认），核心将使用提供的参数和 AbortSignal（用于潜在的取消）调用工具的 execute() 方法。
7. 结果处理: 核心接收来自 execute() 的 ToolResult。
8. 响应模型: 将 ToolResult 中的 llmContent 打包成 FunctionResponse 发送回 Gemini 模型，以便模型可以继续生成面向用户的响应。
9. 显示给用户: 将 ToolResult 中的 returnDisplay 发送给 CLI，以向用户显示工具的操作结果。

使用自定义工具进行扩展

虽然为普通最终用户提供的文件未明确详细说明直接以编程方式注册新工具的工作流程，但该架构支持通过以下方式进行扩展：

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

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