Gemini CLI 文件系统工具

Gemini CLI 文件系统工具

Gemini CLI 提供了一套全面的工具，用于与本地文件系统交互。这些工具允许 Gemini 模型读取、写入、列出、搜索和修改文件和目录，均在您的控制之下，对于敏感操作通常会要求确认。

注意： 所有文件系统工具都在一个 rootDirectory （通常是您启动 CLI 的当前工作目录）内运行，以保证安全。您提供给这些工具的路径通常是绝对路径，或者是相对于这个根目录的相对路径。

1. list_directory (ReadFolder)

list_directory 列出指定目录路径下直接包含的文件和子目录名称。它可以选择性地忽略与提供的 glob 模式匹配的条目。

• 工具名称： list_directory
• 显示名称： ReadFolder
• 文件： ls.ts
• 参数：
  • path （字符串，必填）：要列出的目录的绝对路径。
  • ignore （字符串数组，可选）：要从列表中排除的 glob 模式列表（例如，["*.log", ".git"]）。
  • respect_git_ignore （布尔值，可选）：在列出文件时是否考虑 .gitignore 模式。默认为 true。
• 行为：
  • 返回文件和目录名称列表。
  • 指示每个条目是否为目录。
  • 将目录首先按字母顺序排序条目。
• 输出（llmContent）： 类似于以下内容的字符串： Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png
• 确认： 无。

2. read_file (ReadFile)

read_file 读取并返回指定文件的内容。此工具支持文本、图像（PNG、JPG、GIF、WEBP、SVG、BMP）、音频文件（MP3、WAV、AIFF、AAC、OGG、FLAC）和 PDF 文件。对于文本文件，它可以读取特定的行范围。其他二进制文件类型通常会被跳过。

工具名称： read_file

显示名称： ReadFile

文件： read-file.ts

参数：

• path (字符串，必填)：要读取文件的绝对路径。
• offset (数字，可选)：对于文本文件，从0开始的起始行号。需要设置 limit。
• limit (数字，可选)：对于文本文件，要读取的最大行数。如果省略，则读取默认最大值（例如2000行）或如果可能，整个文件。

行为：

• 对于文本文件：返回内容。如果使用了 offset 和 limit，则只返回该行段的切片。如果由于行数限制或行长度限制而截断内容，将予以指示。
• 对于图像、音频和PDF文件：将文件内容作为适合模型消费的base64编码数据结构返回。
• 对于其他二进制文件：尝试识别并跳过它们，返回一条指示它是通用二进制文件的的消息。

输出： (llmContent)

• 对于文本文件：文件内容，可能带有截断消息的前缀（例如， [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...）。
• 对于图像/音频/PDF文件：包含 inlineData 和 base64 data 的对象（例如， { inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }）。
• 对于其他二进制文件：像 Cannot display content of binary file: /path/to/data.bin 这样的消息。

确认： 否。

3. write_file (WriteFile)

write_file 将内容写入指定文件。如果文件存在，它将被覆盖。如果文件不存在，将创建该文件（及其所需的任何父目录）。

工具名称： write_file 显示名称： WriteFile 文件： write-file.ts 参数：

• file_path (字符串，必填)：要写入的文件的绝对路径。
• content (字符串，必填)：要写入文件的内容。 行为：
• 将提供的content写入file_path。
• 如果父目录不存在，则创建它们。 输出(llmContent)： 成功消息，例如， Successfully overwrote file: /path/to/your/file.txt或 Successfully created and wrote to new file: /path/to/new/file.txt。 确认： 是的。在写入之前显示更改差异并请求用户批准。

4. glob (FindFiles)

glob查找与特定glob模式匹配的文件（例如src/**/*.ts、*.md），按修改时间（最新优先）返回绝对路径。

工具名称： glob 显示名称： FindFiles 文件： glob.ts 参数：

• pattern (字符串，必填)：要匹配的glob模式（例如， "*.py"、"src/**/*.js"）。
• path (字符串，可选)：要搜索的绝对路径目录。如果省略，则搜索工具的根目录。
• case_sensitive (布尔值，可选)：搜索是否应区分大小写。默认为false。
• respect_git_ignore (布尔值，可选)：查找文件时是否应尊重.gitignore模式。默认为true。 行为：
• 在指定目录内搜索与glob模式匹配的文件。
• 返回绝对路径列表，按最近修改的文件优先排序。
• 默认忽略如node_modules和.git等常见干扰目录。 输出(llmContent)： 类似于以下消息： Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts... 确认： 否。

5. search_file_content (SearchText)

在指定目录中搜索文件内容中的正则表达式模式。可以通过一个 glob 模式来过滤文件。返回包含匹配的行，以及它们的文件路径和行号。

• 工具名称： search_file_content
• 显示名称： 搜索文本
• 文件： grep.ts
• 参数：
  • pattern (字符串，必填)：要搜索的正则表达式（regex）(例如，"function\s+myFunction")。
  • path (字符串，可选)：要搜索的绝对目录路径。默认为当前工作目录。
  • include (字符串，可选)：用于筛选哪些文件被搜索的 glob 模式（例如，"*.js"，"src/**/*.{ts,tsx}"）。如果省略，将搜索大多数文件（尊重常见的忽略）。
• 行为：
  • 如果在 Git 仓库中可用，将使用 git grep 以提高速度；否则，回退到系统 grep 或基于 JavaScript 的搜索。
  • 返回匹配行的列表，每个前面都带有其文件路径（相对于搜索目录）和行号。

• 输出（llmContent）： 格式化的匹配字符串，例如：``` Found 3 matches for pattern “myFunction” in path ”.” (filter: “*.ts”):

  File: src/utils.ts L15: export function myFunction() { L22: myFunction.call();

  File: src/index.ts L5: import { myFunction } from ’./utils’;

• 确认： 否。

6. replace (编辑)

replace 替换文件中的文本。默认情况下，替换单个出现，但当指定 expected_replacements 时可以替换多个出现。此工具旨在进行精确、有针对性的更改，并需要围绕 old_string 的显著上下文以确保修改正确的位置。

• 工具名称： replace
• 显示名称： 编辑
• 文件： edit.ts
• 参数：
  • file_path (字符串，必填)：要修改的文件的绝对路径。
  • old_string (字符串，必填)：要替换的确切文本。

关键： 此字符串必须唯一标识要更改的单个实例。它应该至少包括目标文本前后各3行的上下文，并精确匹配空白和缩进。如果 old_string 为空，工具将尝试在 file_path 创建一个新文件，内容为 new_string。

• new_string (字符串，必填)：要替换 old_string 的确切文字。
• expected_replacements (数字，可选)：要替换的数量。默认为 1。

行为：

• 如果 old_string 为空且 file_path 不存在，则创建一个新文件，内容为 new_string。
• 如果提供了 old_string，它会读取 file_path 并尝试找到恰好一次出现的 old_string。
• 如果找到一次出现，它会将其替换为 new_string。
• 增强可靠性（多阶段编辑校正）： 为了显著提高编辑的成功率，尤其是在模型提供的 old_string 可能不是完全精确的情况下，该工具采用多阶段编辑校正机制。
  • 如果初始的 old_string 没有找到或匹配多个位置，该工具可以利用 Gemini 模型迭代地细化 old_string（以及可能的 new_string）。
  • 这个自我校正过程试图识别模型意图修改的独特段，即使初始上下文略有瑕疵，也能使 replace 操作更加健壮。
• 失败条件： 尽管有校正机制，但如果以下情况，工具将失败：
  • file_path 不是绝对路径或位于根目录之外。
  • old_string 不为空，但 file_path 不存在。
  • old_string 为空，但 file_path 已存在。
  • 在尝试校正后，文件中找不到 old_string。
  • old_string 在文件中多次出现，自我校正机制无法将其解析为单一明确的匹配。
• 输出（llmContent）：
  • 成功时： Successfully modified file: /path/to/file.txt (1 replacements). 或 Created new file: /path/to/new_file.txt with provided content.
  • 失败时：一条解释原因的错误消息（例如， Failed to edit, 0 occurrences found..., Failed to edit, expected 1 occurrences but found 2...）。
• 确认： 是的。显示建议更改的 diff 并在写入文件前请求用户批准。

这些文件系统工具为 Gemini CLI 提供了理解并与您的本地项目上下文进行交互的基础。