Gemini CLI Core：Tools API

Gemini CLI 的 core 包（packages/core）提供了健全的工具体系，用于定义、注册与执行工具。这些工具拓展了 Gemini 模型的能力，使其能够访问本地环境、抓取网页内容，并执行超越纯文本生成的多种操作。

核心概念

  • Tool（tools.ts）： 通过接口与基类 BaseTool 约定所有工具的结构。每个工具需要实现：

    • name：供 Gemini API 调用的唯一内部名称。
    • displayName：面向用户的友好名称。
    • description：描述工具作用的文字，会提供给模型。
    • parameterSchema：描述参数的 JSON Schema，帮助模型正确调用工具。
    • validateToolParams()：校验入参有效性。
    • getDescription()：在执行前生成基于参数的可读描述，便于向用户展示。
    • shouldConfirmExecute()：判断是否需要在执行前请求用户确认（如潜在危险操作）。
    • execute()：执行工具逻辑并返回 ToolResult。

  • ToolResult（tools.ts）： 描述工具执行结果：

    • llmContent：提供给 LLM 历史中的事实内容，可以是字符串，也可以是 PartListUnion（由 Part 对象与字符串组成的数组），以支持富内容返回。
    • returnDisplay：用于 CLI 展示的友好字符串（常为 Markdown），或 FileDiff 等特定对象。

  • 富内容返回： 工具不限制于纯文本，llmContent 可为 PartListUnion，允许一次执行返回多段富内容（如图片、音频等）。

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

    • 注册工具： 保存所有内置工具（如 ReadFileTool、ShellTool）。
    • 发现工具： 支持动态发现：
      • 命令发现： 若在配置中设置了 tools.discoveryCommand，core 会执行该命令，解析其输出的工具描述 JSON，注册为 DiscoveredTool。
      • MCP 发现： 若配置了 mcp.serverCommand，则可连接 MCP server，列出并注册其提供的工具（DiscoveredMCPTool）。
    • 提供 Schema： 向 Gemini 模型暴露所有已注册工具的 FunctionDeclaration，帮助模型了解可用工具及其调用方式。
    • 获取工具： 根据名称返回特定工具实例，供核心执行。

内置工具

核心内置了多种工具，位于 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，实现特定能力所需的方法。

工具执行流程

  1. 模型请求： 模型根据用户提示与可用工具的 Schema 决定调用工具，在响应中返回包含工具名称与参数的 FunctionCall。
  2. Core 接收请求： 解析 FunctionCall。
  3. 工具检索： 在 ToolRegistry 中查找对应工具。
  4. 参数校验： 调用 validateToolParams() 验证参数。
  5. 确认流程（若需要）：
    • 调用 shouldConfirmExecute()。
    • 若需要确认，Core 将信息传回 CLI，由 CLI 提示用户。
    • 用户的决定（继续或取消）再传回 Core。
  6. 执行： 若参数有效并通过确认，Core 使用提供的参数与 AbortSignal 调用 execute()。
  7. 结果处理： 从 execute() 获取 ToolResult。
  8. 返回模型： 将 ToolResult.llmContent 打包为 FunctionResponse，发送给模型继续推理。
  9. 展示给用户： ToolResult.returnDisplay 会显示在 CLI 中，让用户了解工具执行情况。

扩展自定义工具

尽管普通用户不常直接以编程方式注册新工具，架构支持以下扩展方式：

  • 命令式发现： 高级用户或维护者可在 settings.json 中设置 tools.discoveryCommand。当 Core 执行该命令时，期望其输出工具描述的 JSON 数组，Core 会将其注册为 DiscoveredTool。相应的 tools.callCommand 则负责执行这些自定义工具。
  • MCP server： 在复杂场景下，可配置一个或多个 MCP server（settings.json 中的 mcpServers）。Core 会发现并使用 server 暴露的工具。如有多个 server，工具名称会加上 server 前缀（例如 serverAlias__actualToolName）。

通过工具体系，Gemini 模型的能力得到灵活扩展，从而让 Gemini CLI 成为应对多种任务的通用助手。