文件系统工具
Gemini CLI 文件系统工具的使用边界：读取、搜索、写入、替换、diff 确认、.geminiignore 和敏感文件排除。
文件系统工具让 Gemini CLI 能看到真实项目。它可以读取、搜索、写入和替换文件，但写操作必须更谨慎。
文件系统工具的风险取决于当前目录。进入 repo 根目录、home 目录、下载目录，工具能看到的范围完全不同。
所有文件系统工具都运行在 rootDirectory 之内，也就是当前工作目录或 workspace root。这个边界很重要：你进入哪个目录，Gemini CLI 看到的项目范围就从哪里开始。
常见能力
- 列目录。
- 搜索文件。
- 读取文件。
- 写新文件。
- 替换局部内容。
- 展示 diff。
工具分工
list_directory：列出某个目录下的文件和子目录，适合第一次探索项目。read_file：读取指定文件，支持 offset 和 limit，适合读取长文件的一部分。glob：按 pattern 找文件，默认尊重常见忽略规则，适合不知道具体路径时先定位。grep_search：按正则搜索文本，适合查符号、配置项、错误信息。write_file：创建或覆盖文件，属于写操作，必须确认。replace：精确替换文件中的一段文本，默认要求只匹配一次，适合小范围补丁。
官方工具名在不同 UI 和实现层里可能显示为 read_file、write_file、glob、search_file_content、replace、list_directory。写教程时建议同时写“用户看到的动作”和“官方工具名”，否则读者排查日志、policy 或 MCP 输出时会对不上。
几个细节要特别说明：write_file 会在确认前展示 diff；replace 需要 old_string 足够唯一，必要时用 expected_replacements 控制替换次数；read_file 可读取文本指定行段，图片和 PDF 会按工具能力转成可处理内容，其他二进制类型可能被跳过或截断。
推荐顺序
真实项目里不要先写文件。更稳的顺序是：先 list_directory 看结构，再用 glob / grep_search 定位目标，再 read_file 读取相关上下文，最后才考虑 replace 或 write_file。
replace 比整文件覆盖更适合维护型修改，因为它要求提供明确旧文本和新文本。批量替换前要让 Gemini CLI 说明会匹配几处，避免误改相似片段。
| 动作 | 风险 | 推荐控制 |
|---|---|---|
list_directory / glob | 暴露目录结构 | 在正确项目目录启动 |
grep_search | 暴露匹配内容 | 先配置 .geminiignore |
read_file | 读取敏感文件 | 限定具体路径和范围 |
replace | 误改相似文本 | 要求唯一匹配和 diff |
write_file | 覆盖或新增文件 | 先说明路径、内容和原因 |
安全做法
- 第一次只读。
- 修改前要求它说明影响文件。
- 每次只授权小范围改动。
- 看 diff。
- 跑测试。
- 敏感文件放进
.geminiignore。
不该读取的文件
.env
*.pem
*.key
local-db-dump.sql
customer-data/多文件读取边界
批量读取不是简单传一个目录。官方 read_many_files 要求使用文件路径或 glob pattern，例如 docs/*.md、src/**/*.ts；只传目录路径通常得不到你以为的完整内容。读取图片、PDF、音频、视频这类文件时，最好显式写文件名或扩展名。
默认排除规则会过滤 node_modules、.git 和常见二进制文件；respect_git_ignore 默认会尊重 .gitignore。如果教程要让读者复现“读取整个项目上下文”，必须写清 include/exclude pattern，不能只说“让 Gemini 读项目目录”。
验收方式
文件系统工具的验收不只看“模型说改好了”。至少要看 diff、确认写入文件属于本次任务范围，并运行对应检查命令。多 agent 并发时，每批写入前后都要检查 git status --short <目标目录>，防止覆盖别人正在改的文件。