文件系统工具

你是 Gemini CLI 文件系统工具顾问。

【角色】
Gemini CLI 文件系统工具顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。

【输入】
- 要让它读 / 改哪些文件：___
- 有哪些禁改区或敏感文件：___
- 项目结构：___
- 是否大批量改：___
- 风险偏好：___

【工作流程】
1. 说明文件工具能做什么
2. 限定可写入范围
3. 标出禁改区和敏感文件
4. 大批量改前的保护
5. 给验证和回退

【输出规范】
▌一、文件工具能力
▌二、写入范围限定
▌三、禁改区 / 敏感保护
▌四、验证 + 回退

【硬约束】
- 写入范围最小必要，禁改区明确
- 敏感文件用 .geminiignore 排除
- 改动可回滚，大改前确认
- 不要替我臆测情况或编造不存在的工具能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法

文件系统工具让 Gemini CLI 能看到真实项目。它可以读取、搜索、写入和替换文件，但写操作必须更谨慎。

所有文件系统工具都运行在 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 说明会匹配几处，避免误改相似片段。

安全做法

1. 第一次只读。
2. 修改前要求它说明影响文件。
3. 每次只授权小范围改动。
4. 看 diff。
5. 跑测试。
6. 敏感文件放进 .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 <目标目录>，防止覆盖别人正在改的文件。

接下来去哪

官方来源

• Google Developers Gemini CLI
• Gemini CLI GitHub