Gemini CLI 内置 6 个文件系统工具：list_directory（列目录）、read_file（读取文本/图片/PDF）、write_file（写入文件，需用户确认）、glob（按 glob 模式搜索文件）、grep_search（正则内容搜索）和 replace（精准文本替换，需用户确认）。所有工具在 rootDirectory（当前工作目录）范围内操作，与 .gitignore/.geminiignore 联动过滤。

文件系统工具参考

Gemini CLI 的文件系统工具让 AI 代理可以读取、修改和搜索代码库文件。所有工具都在 rootDirectory（当前工作目录或工作区根目录）范围内操作。

list_directory（列目录）

列出指定目录下的文件和子目录名称。

参数：

参数	类型	必填	说明
dir_path	string	是	目标目录的绝对或相对路径
ignore	array	否	要排除的 glob 模式列表
file_filtering_options	object	否	.gitignore/.geminiignore 过滤配置

不需要用户确认。

---

read_file（读取文件）

读取并返回指定文件的内容。支持文本、图片、音频和 PDF 格式。

参数：

参数	类型	必填	说明
file_path	string	是	文件路径
offset	number	否	起始行号（0-based），仅对文本文件有效
limit	number	否	最多读取的行数

不需要用户确认。

示例用法（在 Prompt 中引用文件）：

# 直接在提示词中用 @ 引用文件
@src/utils/auth.ts 解释这个文件的认证逻辑
@README.md 根据这个文档写一份中文摘要

---

write_file（写入文件）

将内容写入指定文件，文件已存在则覆盖，不存在则创建。

参数：

参数	类型	必填	说明
file_path	string	是	目标文件路径
content	string	是	要写入的数据

需要用户手动确认，操作前会显示预览。

---

glob（按模式搜索文件）

在工作区中查找匹配指定 glob 模式的文件，按修改时间降序排列（最新的在前）。

参数：

参数	类型	必填	说明
pattern	string	是	glob 模式，如 "*.py"、"src/**/*.js"
path	string	否	搜索起始目录（默认为 rootDirectory）
case_sensitive	boolean	否	是否区分大小写（默认 false）
respect_git_ignore	boolean	否	是否遵守 .gitignore（默认 true）

不需要用户确认。自动忽略 node_modules、.git 等常见噪音目录。

示例：

找出所有 TypeScript 文件中最近修改的 10 个

（代理会用 glob("**/*.ts") 并取前 10 条结果）

---

grep_search（正则内容搜索）

在指定目录的文件内容中搜索正则表达式，返回匹配行及文件路径、行号。

参数：

参数	类型	必填	说明
pattern	string	是	正则表达式，如 "function\\s+myFunction"
path	string	否	搜索目录（默认为当前工作目录）
include	string	否	过滤文件的 glob 模式，如 "*.js"、"src/**/*.{ts,tsx}"

不需要用户确认。在 Git 仓库中会优先使用 git grep 以提高速度。

输出示例：

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';

---

replace（精准文本替换）

在文件中精准替换指定文本片段。设计用于局部修改，需要提供足够上下文以定位唯一位置。

参数：

参数	类型	必填	说明
file_path	string	是	目标文件路径
instruction	string	是	对变更的语义描述（展示给用户看）
old_string	string	是	要查找的精确原文本（字面量）
new_string	string	是	替换后的精确新文本
allow_multiple	boolean	否	若为 true，替换所有出现位置；默认 false（只允许唯一匹配）

需要用户手动确认，会显示 diff 预览。

注意：allow_multiple 为 false 时，如果 old_string 在文件中出现多次，操作会失败——这是设计如此，防止意外修改错误位置。需要全部替换时设 allow_multiple: true。

---

控制文件访问范围

通过 .geminiignore 文件可以告诉 Gemini CLI 忽略特定文件或目录，效果类似 .gitignore：

# .geminiignore
*.secret
node_modules/
.env*
dist/

常见问题

Q: AI 能读取整个代码库吗？还是有大小限制？

A: read_file 支持 offset 和 limit 参数，可以分批读取大文件。对于超大文件，AI 通常会自动分段请求。但整个代码库的 Token 总量受模型上下文窗口限制，一次性读取所有文件不现实。

Q: replace 和 write_file 的区别是什么？

A: replace 是局部替换，只修改指定片段，适合精准改动；write_file 覆盖整个文件，适合新建文件或全量重写。两者都需要用户确认，但 replace 的 diff 预览更清晰。

Q: 如何让 AI 不修改某些文件？

A: 有两种方式：1) 在 .geminiignore 中添加对应模式，AI 在搜索和读取时也会跳过；2) 在 settings.json 中配置 tools.core 白名单，限制 write_file 和 replace 的权限范围。