Gemini CLI 文件系统工具

¥Gemini CLI file system tools

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

¥The Gemini CLI provides a comprehensive suite of tools for interacting with the local file system. These tools allow the Gemini model to read from, write to, list, search, and modify files and directories, all under your control and typically with confirmation for sensitive operations.

笔记：所有文件系统工具都在rootDirectory（通常是启动 CLI 的当前工作目录）以确保安全。您提供给这些工具的路径通常应该是绝对路径，或者相对于此根目录进行解析。

¥Note: All file system tools operate within a rootDirectory (usually the current working directory where you launched the CLI) for security. Paths that you provide to these tools are generally expected to be absolute or are resolved relative to this root directory.

1.list_directory（读取文件夹）

¥1. list_directory (ReadFolder)

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

¥list_directory lists the names of files and subdirectories directly within a specified directory path. It can optionally ignore entries matching provided glob patterns.

• 工具名称： list_directory

  ¥Tool name:list_directory

• 显示名称：读取文件夹

  ¥Display name: ReadFolder

• 文件： ls.ts

  ¥File:ls.ts

• 参数：

  ¥Parameters:

• path（字符串，必需）：要列出的目录的绝对路径。

  ¥path (string, required): The absolute path to the directory to list.

• ignore（字符串数组，可选）：要从列表中排除的 glob 模式列表（例如，["*.log", ".git"]）。

  ¥ignore (array of strings, optional): A list of glob patterns to exclude from the listing (e.g., ["*.log", ".git"]).

• respect_git_ignore（布尔值，可选）：是否尊重.gitignore列出文件时的模式。默认为true。

  ¥respect_git_ignore (boolean, optional): Whether to respect .gitignore patterns when listing files. Defaults to true.

• 行为：

  ¥Behavior:

• 返回文件和目录名称的列表。

  ¥Returns a list of file and directory names.

• 指示每个条目是否是一个目录。

  ¥Indicates whether each entry is a directory.

• 首先按目录对条目进行排序，然后按字母顺序排序。

  ¥Sorts entries with directories first, then alphabetically.

• 输出 （llmContent):类似这样的字符串：Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png

  ¥Output (llmContent): A string like: Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png

• 确认：不。

  ¥Confirmation: No.

2.read_file（读取文件）

¥2. read_file (ReadFile)

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

¥read_file reads and returns the content of a specified file. This tool handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), and PDF files. For text files, it can read specific line ranges. Other binary file types are generally skipped.

• 工具名称： read_file

  ¥Tool name:read_file

• 显示名称：读文件

  ¥Display name: ReadFile

• 文件： read-file.ts

  ¥File:read-file.ts

• 参数：

  ¥Parameters:

• path（字符串，必需）：要读取的文件的绝对路径。

  ¥path (string, required): The absolute path to the file to read.

• offset(number，可选)：对于文本文件，从 0 开始读取的行号。需要limit待设置。

  ¥offset (number, optional): For text files, the 0-based line number to start reading from. Requires limit to be set.

• limit(number，可选)：对于文本文件，指定读取的最大行数。如果省略，则读取默认的最大行数（例如 2000 行）或整个文件（如果可行）。

  ¥limit (number, optional): For text files, the maximum number of lines to read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire file if feasible.

• 行为：

  ¥Behavior:

• 对于文本文件：返回内容。如果offset和limit被使用时，仅返回该行片段。指示内容是否由于行数限制或行长限制而被截断。

  ¥For text files: Returns the content. If offset and limit are used, returns only that slice of lines. Indicates if content was truncated due to line limits or line length limits.

• 对于图像和 PDF 文件：将文件内容作为适合模型使用的 base64 编码数据结构返回。

  ¥For image and PDF files: Returns the file content as a base64-encoded data structure suitable for model consumption.

• 对于其他二进制文件：尝试识别并跳过它们，返回一条消息表明它是一个通用二进制文件。

  ¥For other binary files: Attempts to identify and skip them, returning a message indicating it's a generic binary file.

• 输出：(llmContent):

  ¥Output: (llmContent):

• 对于文本文件：文件内容，可能带有截断消息前缀（例如，[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...）。

  ¥For text files: The file content, potentially prefixed with a truncation message (e.g., [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...).

• 对于图像/PDF 文件：包含的对象inlineData和mimeType和 base64data（例如，{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }）。

  ¥For image/PDF files: An object containing inlineData with mimeType and base64 data (e.g., { inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }).

• 对于其他二进制文件：类似以下消息Cannot display content of binary file: /path/to/data.bin。

  ¥For other binary files: A message like Cannot display content of binary file: /path/to/data.bin.

• 确认：不。

  ¥Confirmation: No.

3.write_file（写入文件）

¥3. write_file (WriteFile)

write_file将内容写入指定文件。如果文件存在，则会覆盖该文件。如果文件不存在，则会创建该文件（以及任何必要的父目录）。

¥write_file writes content to a specified file. If the file exists, it will be overwritten. If the file doesn't exist, it (and any necessary parent directories) will be created.

• 工具名称： write_file

  ¥Tool name:write_file

• 显示名称：写入文件

  ¥Display name: WriteFile

• 文件： write-file.ts

  ¥File:write-file.ts

• 参数：

  ¥Parameters:

• file_path（字符串，必需）：要写入的文件的绝对路径。

  ¥file_path (string, required): The absolute path to the file to write to.

• content（字符串，必需）：要写入文件的内容。

  ¥content (string, required): The content to write into the file.

• 行为：

  ¥Behavior:

• 写入提供的content到file_path。

  ¥Writes the provided content to the file_path.

• 如果不存在，则创建父目录。

  ¥Creates parent directories if they don't exist.

• 输出 （llmContent):成功消息，例如，Successfully overwrote file: /path/to/your/file.txt或者Successfully created and wrote to new file: /path/to/new/file.txt。

  ¥Output (llmContent): A success message, e.g., Successfully overwrote file: /path/to/your/file.txt or Successfully created and wrote to new file: /path/to/new/file.txt.

• 确认：是的。显示更改的差异，并在写入前请求用户批准。

  ¥Confirmation: Yes. Shows a diff of changes and asks for user approval before writing.

4.glob（查找文件）

¥4. glob (FindFiles)

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

¥glob finds files matching specific glob patterns (e.g., src/**/*.ts, *.md), returning absolute paths sorted by modification time (newest first).

• 工具名称： glob

  ¥Tool name:glob

• 显示名称：查找文件

  ¥Display name: FindFiles

• 文件： glob.ts

  ¥File:glob.ts

• 参数：

  ¥Parameters:

• pattern（字符串，必需）：要匹配的 glob 模式（例如，"*.py"，"src/**/*.js"）。

  ¥pattern (string, required): The glob pattern to match against (e.g., "*.py", "src/**/*.js").

• path（字符串，可选）：要搜索的目录的绝对路径。如果省略，则搜索工具的根目录。

  ¥path (string, optional): The absolute path to the directory to search within. If omitted, searches the tool's root directory.

• case_sensitive(boolean, 可选): 搜索是否区分大小写。默认为false。

  ¥case_sensitive (boolean, optional): Whether the search should be case-sensitive. Defaults to false.

• respect_git_ignore(布尔值，可选)：查找文件时是否遵循 .gitignore 模式。默认为true。

  ¥respect_git_ignore (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true.

• 行为：

  ¥Behavior:

• 在指定目录中搜​​索与 glob 模式匹配的文件。

  ¥Searches for files matching the glob pattern within the specified directory.

• 返回绝对路径列表，按最近修改的文件排序。

  ¥Returns a list of absolute paths, sorted with the most recently modified files first.

• 忽略常见的干扰目录，例如node_modules和.git默认情况下。

  ¥Ignores common nuisance directories like node_modules and .git by default.

• 输出 （llmContent):类似这样的消息：Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...

  ¥Output (llmContent): A message like: Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...

• 确认：不。

  ¥Confirmation: No.

5.search_file_content（搜索文本）

¥5. search_file_content (SearchText)

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

¥search_file_content searches for a regular expression pattern within the content of files in a specified directory. Can filter files by a glob pattern. Returns the lines containing matches, along with their file paths and line numbers.

• 工具名称： search_file_content

  ¥Tool name:search_file_content

• 显示名称：搜索文本

  ¥Display name: SearchText

• 文件： grep.ts

  ¥File:grep.ts

• 参数：

  ¥Parameters:

• pattern(string，必需)：要搜索的正则表达式（regex）（例如，"function\s+myFunction"）。

  ¥pattern (string, required): The regular expression (regex) to search for (e.g., "function\s+myFunction").

• path(字符串，可选)：要搜索的目录的绝对路径。默认为当前工作目录。

  ¥path (string, optional): The absolute path to the directory to search within. Defaults to the current working directory.

• include（字符串，可选）：用于过滤要搜索的文件的全局模式（例如，"*.js"，"src/**/*.{ts,tsx}")。如果省略，则搜索大多数文件（尊重常见的忽略）。

  ¥include (string, optional): A glob pattern to filter which files are searched (e.g., "*.js", "src/**/*.{ts,tsx}"). If omitted, searches most files (respecting common ignores).

• 行为：

  ¥Behavior:

• 用途git grep如果在 Git 存储库中可用，则可以提高速度；否则，将回退到系统grep或基于 JavaScript 的搜索。

  ¥Uses git grep if available in a Git repository for speed; otherwise, falls back to system grep or a JavaScript-based search.

• 返回匹配行的列表，每行都以其文件路径（相对于搜索目录）和行号为前缀。

  ¥Returns a list of matching lines, each prefixed with its file path (relative to the search directory) and line number.

• 输出 （llmContent):匹配的格式化字符串，例如：``` 在路径“.”中找到了 3 个与模式“myFunction”匹配的结果（过滤器：“*.ts”）：

  ¥Output (llmContent): A formatted string of matches, e.g.: ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):

---

文件：src/utils.ts L15：导出函数 myFunction() { L22：myFunction.call();

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

---

文件：src/index.ts L5：从'./utils'导入{myFunction}；

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

---

``` -确认：不。

¥``` - Confirmation: No.

6.replace（编辑）

¥6. replace (Edit)

replace替换文件中的文本。默认情况下，替换单个匹配项，但当expected_replacements是指定的。此工具旨在实现精确、有针对性的更改，并且需要有关old_string以确保它修改了正确的位置。

¥replace replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when expected_replacements is specified. This tool is designed for precise, targeted changes and requires significant context around the old_string to ensure it modifies the correct location.

• 工具名称： replace

  ¥Tool name:replace

• 显示名称：编辑

  ¥Display name: Edit

• 文件： edit.ts

  ¥File:edit.ts

• 参数：

  ¥Parameters:

• file_path（字符串，必需）：要修改的文件的绝对路径。

  ¥file_path (string, required): The absolute path to the file to modify.

• old_string（字符串，必需）：要替换的精确文字。

  ¥old_string (string, required): The exact literal text to replace.

  批判的：此字符串必须唯一地标识要更改的单个实例。它应至少包含 3 行上下文前和后目标文本，精确匹配空格和缩进。如果old_string为空，该工具会尝试在file_path和new_string作为内容。

  ¥CRITICAL: This string must uniquely identify the single instance to change. It should include at least 3 lines of context before and after the target text, matching whitespace and indentation precisely. If old_string is empty, the tool attempts to create a new file at file_path with new_string as content.

• new_string（字符串，必需）：要替换的精确文字old_string和。

  ¥new_string (string, required): The exact literal text to replace old_string with.

• expected_replacements(number，可选)：要替换的次数。默认为1。

  ¥expected_replacements (number, optional): The number of occurrences to replace. Defaults to 1.

• 行为：

  ¥Behavior:

• 如果old_string为空，并且file_path不存在，则创建一个新文件new_string作为内容。

  ¥If old_string is empty and file_path does not exist, creates a new file with new_string as content.

• 如果old_string提供时，它会读取file_path并尝试找到一个old_string。

  ¥If old_string is provided, it reads the file_path and attempts to find exactly one occurrence of old_string.

• 如果发现一个，则将其替换为new_string。

  ¥If one occurrence is found, it replaces it with new_string.

• 增强可靠性（多阶段编辑校正）：为了显著提高编辑的成功率，特别是当模型提供的old_string可能不是完全精确，该工具采用了多阶段编辑校正机制。

  ¥Enhanced Reliability (Multi-Stage Edit Correction): To significantly improve the success rate of edits, especially when the model-provided old_string might not be perfectly precise, the tool incorporates a multi-stage edit correction mechanism.

  • 如果初始old_string未找到或匹配多个位置，该工具可以利用 Gemini 模型进行迭代优化old_string（并且可能new_string）。

    ¥If the initial old_string isn't found or matches multiple locations, the tool can leverage the Gemini model to iteratively refine old_string (and potentially new_string).

  • 这种自我修正过程试图识别模型想要修改的独特部分，从而使replace即使初始环境稍微不完善，操作也会更加稳健。

    ¥This self-correction process attempts to identify the unique segment the model intended to modify, making the replace operation more robust even with slightly imperfect initial context.

• 失败条件：尽管有校正机制，但如果出现以下情况，该工具仍会失效：

  ¥Failure conditions: Despite the correction mechanism, the tool will fail if:

• file_path不是绝对的或者在根目录之外。

  ¥file_path is not absolute or is outside the root directory.

• old_string不为空，但file_path不存在。

  ¥old_string is not empty, but the file_path does not exist.

• old_string是空的，但是file_path已经存在。

  ¥old_string is empty, but the file_path already exists.

• old_string尝试纠正后未在文件中找到。

  ¥old_string is not found in the file after attempts to correct it.

• old_string被发现多次，并且自我纠正机制无法将其解析为单个明确的匹配。

  ¥old_string is found multiple times, and the self-correction mechanism cannot resolve it to a single, unambiguous match.

• 输出 （llmContent):

  ¥Output (llmContent):

• 成功时：Successfully modified file: /path/to/file.txt (1 replacements).或者Created new file: /path/to/new_file.txt with provided content.

  ¥On success: Successfully modified file: /path/to/file.txt (1 replacements). or 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...）。

  ¥On failure: An error message explaining the reason (e.g., Failed to edit, 0 occurrences found..., Failed to edit, expected 1 occurrences but found 2...).

• 确认：是的。显示建议更改的差异，并在写入文件之前请求用户批准。

  ¥Confirmation: Yes. Shows a diff of the proposed changes and asks for user approval before writing to the file.

这些文件系统工具为 Gemini CLI 理解和与本地项目环境交互提供了基础。

¥These file system tools provide a foundation for the Gemini CLI to understand and interact with your local project context.