使用Gemini Cli研究和学习Gemini-Cli-1

从今天开始，我将持续分享：使用Gemini Cli这款大模型编程工具的命令行交互的界面来学习Gemini Cli这个开源项目自身。

关于Gemini Cli

gemini-cli 是一个命令行 AI 工作流工具，旨在通过连接到您的工具、理解您的代码来加速您的工作流程。

主要功能包括：

处理大型代码库：能够查询和编辑超过 Gemini 1M 令牌上下文窗口的大型代码库。
多模态应用生成：利用 Gemini 的多模态能力，从 PDF 或草图生成新应用。
自动化操作任务：例如，查询拉取请求或处理复杂的 Git rebase 操作。
可扩展的工具：可以连接新的功能，如使用 Imagen、Veo 或 Lyria 进行媒体生成，并内置了 Google 搜索功能。

您可以通过 npx 或 npm 来安装和运行它。它支持从一个新目录开始一个项目，或者在现有的项目中运行，以帮助您理解代码、实现新功能或自动化工作流程。

Gemini CLI 的架构

docs/architecture.md 文件描述了 Gemini CLI 的架构。其核心由两大部分组成：

CLI 包 (packages/cli): 这是面向用户的部分，负责处理用户输入、显示输出以及管理整体用户体验。
核心包 (packages/core): 这是 Gemini CLI 的后端，负责与 Gemini API 交互、管理和执行可用的工具。此外，还有一套工具 (packages/core/src/tools/)，这些工具扩展了 Gemini 模型的能力，使其能够与本地环境（如文件系统、shell 命令、网络请求）进行交互。典型的交互流程如下：
用户在终端输入提示。
CLI 包将输入发送到核心包。
核心包构建一个合适的提示，并将其发送到 Gemini API。
Gemini API 返回一个响应，可能是一个直接的答案，也可能是一个使用工具的请求。
如果请求使用工具，核心包会执行该工具（在需要时会请求用户批准），并将结果发送回 Gemini API。
Gemini API 处理工具结果并生成最终响应。
核心包将最终响应发送回 CLI 包。
CLI 包将响应格式化并显示给用户。该架构的主要设计原则是模块化、可扩展性和用户体验。

Gemini Cli自带的工具包有哪些？

Gemini CLI 提供了一套丰富的默认工具，用于与您的本地环境和网络进行交互。以下是这些工具的详细介绍：

一、文件系统工具

这些工具允许 Gemini 与您的本地文件系统进行交互，但操作通常会限制在您启动 CLI 的项目根目录内，以确保安全。

list_directory (别名: ReadFolder): 列出指定目录中的文件和子目录。
read_file (别名: ReadFile): 读取单个文件的内容，支持文本、图片和 PDF。
write_file (别名: WriteFile): 将内容写入文件。如果文件已存在，则会覆盖；如果不存在，则会创建新文件。
glob (别名: FindFiles): 根据通配符模式（如 src/*/.ts）查找文件。
search_file_content (别名: SearchText): 在文件内容中搜索正则表达式模式。
replace (别名: Edit): 在文件中替换文本。

二、Shell工具

run_shell_command: 执行 shell 命令。这使 Gemini 能够运行脚本、与版本控制系统（如 Git）交互或执行其他命令行操作。出于安全考虑，可以对可执行的命令进行限制。

三、网络工具

web_fetch: 从一个或多个 URL 提取、总结或比较信息。

google_web_search: 使用 Google 搜索执行网络搜索，并返回带有来源引用的摘要。

四、其他工具

save_memory: 将信息保存到用户的 GEMINI.md 文件中，以便在未来的会话中记住这些信息。

read_many_files: 一次性读取多个文件的内容，支持文本、图片和 PDF。

MCP (Model Context Protocol) 服务器: 这不是一个单一的工具，而是一个框架，允许您将外部工具集通过 MCP 服务器连接到 Gemini CLI，从而极大地扩展其功能。您可以配置自己的 MCP
服务器来暴露自定义的工具。

这些工具共同为 Gemini CLI 提供了强大的能力，使其能够理解您的代码库、与您的本地环境交互，并利用网络资源来帮助您完成各种开发任务。

read_many_files 工具的工作原理

read_many_files 工具一次性读取多种类型文件的核心原理是分两步走：1. 文件发现；2. 内容处理。

文件发现 (File Discovery) 这是该工具的第一步，目的是确定需要读取哪些文件。

使用 Glob 模式: 您提供给工具的 paths 参数不是一个简单的文件列表，而是一个或多个 glob 模式的数组（例如 src//.ts 或 docs/.md）。Glob 是一种强大的路径匹配语法，
可以匹配任意层级的目录，* 可以匹配文件名中的任意字符。这使得工具能够一次性地在整个项目目录结构中找到所有符合模式的文件，而无需您手动列出每一个文件。
过滤和排除: 工具还会结合 include 和 exclude 参数，以及默认的忽略规则（如 .git、node_modules 目录）和 .gitignore 文件中的规则，来精确地筛选出最终要处理的文件列表。通过这个机制，工具首先高效地构建出一个包含所有目标文件路径的清单。

内容处理 (Content Processing) 在拿到文件清单后，工具会遍历清单中的每一个文件，并根据文件类型采用不同的处理策略，最终将所有处理过的内容整合成一个统一的格式，方便语言模型理解。

对于文本文件 (.ts, .md, .js 等):
- 读取内容: 直接以 UTF-8 编码读取文件的文本内容。
- 拼接与分隔: 将所有文本文件的内容拼接成一个大的字符串。为了让模型能够区分不同文件的内容，它会在每个文件的内容之间插入一个明确的分隔符，格式为 — {filePath}—。这样模型在接收到长字符串时，就能清楚地知道“这是 fileA.ts 的内容”和“这是 fileB.ts 的内容”。
对于图片和 PDF 文件 (.png, .jpg, .pdf 等):
- 显式请求: 工具要求必须显式地在 paths 或 include 中指定这些文件（例如，通过完整文件名 logo.png 或扩展名模式 *.pdf）。这是因为它默认会跳过二进制文件，除非被明确告知要去读取。
- Base64 编码: 图片和 PDF 是二进制格式，不能作为纯文本处理。工具会读取这些文件的二进制数据，然后将其转换为 Base64 编码的字符串。Base64 是一种将二进制数据表示为 ASCII字符串的方法，非常适合在基于文本的协议（如 API 调用）中传输二进制内容。
- 结构化输出: 编码后的数据会与文件的 mimeType (例如 image/png) 一起打包成一个结构化的对象。这告诉模型：“这是一张 PNG 图片，这里是它的 Base64 数据”，模型就能理解并处理它。
对于其他二进制文件:
- 检测与跳过: 如果一个文件不是被显式请求的图片或 PDF，工具会检查其内容的开头部分。如果发现二进制文件的特征（如存在空字节 null），它就会跳过这个文件，避免向模型发送无意义的乱码。

总结一下，read_many_files 的原理就是：先用 glob 模式高效地“扫描”并收集所有目标文件，然后“遍历”这个文件列表，对每个文件“对症下药”——文本文件直接拼接，图片/PDF 等二进制文件则编码成Base64——最后将所有处理好的内容打包成一个统一的、模型可以理解的格式。

见微知著 · TheSignalwise

recent posts

about