文件管理
Gemini CLI 文件管理：@ 文件引用、目录上下文、查找文件、修改文件、创建文件、diff 确认和 .geminiignore。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| 文件管理 | file mgmt | Agent 读写文件的方式。 |
| 引用 | reference | 用 @ 等引用文件给上下文。 |
| 写入边界 | scope | 限定能改哪些文件。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你管好 Gemini CLI 的文件操作（引用、写入边界）。
你是 Gemini CLI 文件管理顾问。
【角色】
Gemini CLI 文件管理顾问，按最小够用、安全优先的原则给可落地方案，每条结论落到能照做的步骤或示例。
【输入】
- 要让它读 / 改哪些文件：___
- 是否有禁改区：___
- 项目结构：___
- 风险偏好：___
【工作流程】
1. 说明怎么引用文件给上下文
2. 限定可写入的范围
3. 标出禁改区
4. 给验证和回退
【输出规范】
▌一、文件引用方式
▌二、写入范围限定
▌三、禁改区
▌四、验证 + 回退
【硬约束】
- 写入范围最小必要，禁改区明确
- 改动可回滚
- 大范围改前先确认
- 不要替我臆测情况或编造不存在的命令，信息不全先问清
- 不确定的命令或参数一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述
- 给的每个命令或操作都标一句它解决什么、什么时候用，别让我对着一长串不知何时该用的东西发愣，也不要一次塞太多Gemini CLI 可以自己探索项目，也可以通过 @ 显式读取你指定的文件或目录。文件管理是它从“聊天”变成“agent”的关键能力，也是最容易越界的地方：读错文件会误判，改错文件会制造无关 diff。
先只读，再修改：第一次接入项目时，先让它解释文件结构；确认读对以后，再授权编辑。
1. 显式读取文件
单文件示例：@src/components/UserProfile.tsx 解释这个组件如何处理用户数据。
多个文件可以一起给：
@src/components/UserProfile.tsx @src/types/User.ts 检查这两个文件的类型关系。
目录也可以给：
@src/utils/ 检查这些工具函数是否还有 deprecated API。
显式引用适合你已经知道路径的情况。它的优势是范围明确；缺点是你可能漏掉相关文件。因此复杂问题可以先让 Gemini CLI 读结构，再由你确认要引用哪些文件。
2. 让它自己找文件
不知道路径时，不要乱猜：
可以直接问：Find the file that defines the UserProfile component.
Gemini CLI 会用目录列表、glob 等工具探索项目结构，再返回可能路径。
3. 修改和创建文件
修改文件：
Update @src/components/UserProfile.tsx to show a loading spinner if user data is null.
创建文件：
Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.
修改前它会展示 unified diff。你要看清楚再确认。
不要一次授权整个目录重写：让它修改多个文件前，先要求输出文件清单、每个文件为什么要改、预期验证命令。没有清单的大范围改动，不适合直接确认。
4. .geminiignore
Gemini CLI 默认尊重 .gitignore。如果有些文件不想暴露给 AI，但不适合放进 .gitignore，可以用 .geminiignore：
常见排除项包括 .env、local-db-dump.sql、private-notes.md。
.geminiignore 适合排除本地敏感材料、临时数据、数据库 dump、客户资料和私有笔记。它不应该代替凭据管理；真正的密钥仍然不能放在项目目录里等工具来“忽略”。
5. 工具分工
显式 @file 适合你已经知道路径的情况。路径不确定时，让 Gemini CLI 先列目录、搜索名称或搜索内容；读单个文件和批量读上下文是两种不同动作；修改优先做精确替换，只有新建文件或整体重写时才适合完整写入。
flowchart TD
Task["文件任务"] --> Known{"知道路径?"}
Known -->|是| At["@file 精确引用"]
Known -->|否| Search["先搜索文件和目录"]
At --> Read["只读解释"]
Search --> Read
Read --> Plan["修改计划"]
Plan --> Edit["限定文件编辑"]
Edit --> Diff["看 unified diff"]
Diff --> Test["跑最小验证"]
style Read fill:#dcfce7,stroke:#22c55e
style Edit fill:#fef3c7,stroke:#f59e0b
style Diff fill:#dbeafe,stroke:#3b82f66. 安全顺序
- 只读解释目录。
- 指定单文件解释。
- 让它提出修改计划。
- 只授权一个小文件修改。
- 看 diff。
- 跑测试。
7. 验收方式
编辑文件前，要求 Gemini CLI 先说清它准备读哪些文件和为什么读。编辑后检查 unified diff、运行项目测试或最小验证命令。涉及 .geminiignore 的项目，再验证被排除文件不会通过 @ 或搜索进入上下文。
8. 接下来去哪
Shell 命令
文件能读写以后，继续看如何让 Gemini CLI 安全运行测试和脚本。
GEMINI.md
反复出现的项目规则不要每次 prompt 复制，继续沉淀到上下文文件。
gemini ignore
继续看哪些文件应该排除在 AI 上下文之外。