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

Gemini CLI 文件系统工具

Gemini CLI 提供了一套完整的工具集，用于与本地文件系统进行交互。这些工具允许 Gemini 模型在您的控制下读取、写入、列出、搜索和修改文件及目录，通常在执行敏感操作时会请求确认。

注意： 出于安全考虑，所有文件系统工具都在 rootDirectory（通常是您启动 CLI 时的当前工作目录）内运行。您提供给这些工具的路径通常应为绝对路径，或相对于此根目录解析的相对路径。

1. `list_directory` (读取文件夹)

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
确认: 不需要。
工具名称: 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` (读取文件)

read_file 用于读取并返回指定文件的内容。该工具支持处理文本文件、图片文件(PNG、JPG、GIF、WEBP、SVG、BMP)以及PDF文件。对于文本文件，可以读取特定的行范围。其他二进制文件类型通常会被跳过。

工具名称: read_file
显示名称: ReadFile
文件: read-file.ts
参数:
path (字符串, 必需): 要读取文件的绝对路径
offset (数字, 可选): 对于文本文件，指定从0开始的行号作为读取起点。需要同时设置limit参数
limit (数字, 可选): 对于文本文件，指定要读取的最大行数。如果省略，则读取默认最大值(如2000行)或在可行情况下读取整个文件
行为:
对于文本文件: 返回文件内容。如果使用了offset和limit，则只返回该行范围的内容。会标明内容是否因行数限制或行长度限制而被截断
对于图片和PDF文件: 返回文件内容的base64编码数据结构，适合模型使用
对于其他二进制文件: 尝试识别并跳过它们，返回表明这是通用二进制文件的消息
输出: (llmContent):
对于文本文件: 文件内容，可能带有截断信息前缀(例如[文件内容截断: 显示500行中的1-100行...]\n实际文件内容...)
对于图片/PDF文件: 包含inlineData的对象，其中有mimeType和base64编码的data(例如{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } })
对于其他二进制文件: 类似无法显示二进制文件内容: /path/to/data.bin的消息
确认: 不需要
工具名称: read_file
显示名称: ReadFile
文件: read-file.ts
参数:
path (字符串, 必需): 要读取文件的绝对路径
offset (数字, 可选): 对于文本文件，指定从0开始的行号作为读取起点。需要同时设置limit参数
limit (数字, 可选): 对于文本文件，指定要读取的最大行数。如果省略，则读取默认最大值(如2000行)或在可行情况下读取整个文件
行为:
对于文本文件: 返回文件内容。如果使用了offset和limit，则只返回该行范围的内容。会标明内容是否因行数限制或行长度限制而被截断
对于图片和PDF文件: 返回文件内容的base64编码数据结构，适合模型使用
对于其他二进制文件: 尝试识别并跳过它们，返回表明这是通用二进制文件的消息
输出: (llmContent):
对于文本文件: 文件内容，可能带有截断信息前缀(例如[文件内容截断: 显示500行中的1-100行...]\n实际文件内容...)
对于图片/PDF文件: 包含inlineData的对象，其中有mimeType和base64编码的data(例如{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } })
对于其他二进制文件: 类似无法显示二进制文件内容: /path/to/data.bin的消息
确认: 不需要

3. `write_file` (写入文件)

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

工具名称: write_file
显示名称: WriteFile
文件: write-file.ts
参数:
file_path (字符串, 必需): 要写入文件的绝对路径。
content (字符串, 必需): 要写入文件的内容。
行为:
将提供的 content 写入 file_path。
如果父目录不存在，会自动创建。
输出 (llmContent): 成功消息，例如 成功覆盖文件: /path/to/your/file.txt 或 成功创建并写入新文件: /path/to/new/file.txt。
确认: 需要。在写入前会显示变更差异并请求用户确认。
工具名称: write_file
显示名称: WriteFile
文件: write-file.ts
参数:
file_path (字符串, 必需): 要写入文件的绝对路径。
content (字符串, 必需): 要写入文件的内容。
行为:
将提供的 content 写入 file_path。
如果父目录不存在，会自动创建。
输出 (llmContent): 成功消息，例如 成功覆盖文件: /path/to/your/file.txt 或 成功创建并写入新文件: /path/to/new/file.txt。
确认: 需要。在写入前会显示变更差异并请求用户确认。

4. `glob` (文件查找工具)

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): 类似这样的消息：在 src 目录下找到 5 个匹配 "*.ts" 的文件，按修改时间排序（最新在前）:\nsrc/file1.ts\nsrc/subdir/file2.ts...
确认: 不需要。
工具名称: glob
显示名称: FindFiles
文件: glob.ts
参数:
pattern (字符串, 必填): 用于匹配的 glob 模式（如 "*.py"、"src/**/*.js"）。
path (字符串, 可选): 要搜索的目录绝对路径。如果省略，则搜索工具的根目录。
case_sensitive (布尔值, 可选): 搜索是否区分大小写。默认为 false。
respect_git_ignore (布尔值, 可选): 查找文件时是否遵循 .gitignore 规则。默认为 true。
行为:
在指定目录中搜索匹配 glob 模式的文件。
返回按修改时间排序的绝对路径列表（最新修改的文件在前）。
默认忽略常见干扰目录如 node_modules 和 .git。
输出 (llmContent): 类似这样的消息：在 src 目录下找到 5 个匹配 "*.ts" 的文件，按修改时间排序（最新在前）:\nsrc/file1.ts\nsrc/subdir/file2.ts...
确认: 不需要。

5. `search_file_content` (搜索文本)

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

工具名称: search_file_content
显示名称: SearchText
文件: grep.ts
参数:
pattern (string, 必填): 要搜索的正则表达式 (例如 "function\s+myFunction")
path (string, 可选): 要搜索的目录绝对路径。默认为当前工作目录
include (string, 可选): 用于过滤搜索文件的 glob 模式 (例如 "*.js", "src/**/*.{ts,tsx}")。如果省略，则搜索大多数文件 (遵循常见的忽略规则)
行为:
在 Git 仓库中优先使用 git grep 以提高速度，否则回退到系统 grep 或基于 JavaScript 的搜索
返回匹配行的列表，每行前缀包含其文件路径 (相对于搜索目录) 和行号

输出 (llmContent): 格式化的匹配结果字符串，例如:

在路径 "." 中找到 3 个匹配 "myFunction" 的结果 (过滤器: "*.ts"):
文件: src/index.ts
第5行: 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 并尝试找到恰好一个匹配项。
如果找到一个匹配项，则用 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):
成功时: 成功修改文件: /path/to/file.txt (替换了1处)。 或 已创建新文件: /path/to/new_file.txt 并写入内容。
失败时: 解释原因的报错信息 (如 编辑失败，未找到匹配项..., 编辑失败，预期1处匹配但找到2处...)。
确认: 需要。在写入文件前会显示变更差异并请求用户确认。

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

Gemini CLI 文件系统工具

1. list_directory (读取文件夹)

2. read_file (读取文件)

3. write_file (写入文件)

4. glob (文件查找工具)

5. search_file_content (搜索文本)

6. replace (编辑)