企业官网建设流程全解析

Gemini CLI 文件管理实战：@ 引用上下文、代码探索、修改确认与 .geminiignore 可见性控制

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

在 Gemini CLI 中，文件操作是 Agent 与代码库交互的核心能力：通过@引用强制注入文件内容、用glob/list_directory等工具定位未知文件、用replace/write_file工具完成精确修改，并用.gitignore与.geminiignore控制模型能“看见”的内容范围。读完本文，你可以掌握一套完整的文件管理工作流——从提供上下文、探索代码库、安全地修改和创建文件，到验证变更与控制 Agent 的文件可见性，并能对照仓库源码理解每个步骤背后的工具实现。

前提条件

• 已安装并完成认证的 Gemini CLI（gemini可正常运行）。
• 一个可用于实践的项目目录，例如一个 Git 仓库。

通过读取文件提供上下文

Gemini CLI 通常会主动读取相关文件（依据你的权限设置，有时会先征求你的访问许可）。如果你希望确保某个文件一定进入上下文，可以直接在提示词中引用它。

直接文件引用（@语法）

已知目标文件路径时，使用@符号即可强制 CLI 立即读取该文件并将其内容注入提示词：

`@src/components/UserProfile.tsx Explain how this component handles user data.`

从源码结构看，这套@引用的解析逻辑集中在 atCommandProcessor.ts 中：parseAllAtCommands函数用正则把查询串切分为“普通文本段”和@<路径>段，且支持用反斜杠转义空格、以及引号包裹的路径（如含空格的文件名），避免路径被错误截断。

此外，categorizeAtCommands（atCommandProcessor.ts）会把每个@引用分类为三类：已注册的Agent（subagent 名称）、MCP Resource URI、或普通的文件/目录路径。只有第三类才会走文件读取流程。而checkPermissions（atCommandProcessor.ts）会在处理前对每个文件路径做解析与validatePathAccess权限校验，越出可访问范围的路径会被拦截——这就是“有时提示你授权访问”的来源之一。

同时引用多个文件

复杂功能往往横跨多个文件。可以把多个@引用串联起来，给 Agent 完整的依赖关系视图：

`@src/components/UserProfile.tsx @src/types/User.ts Refactor the component to use the updated User interface.`

引用整个目录

对于大范围问题或重构，可以直接引用整个目录：

`@src/utils/ Check these utility functions for any deprecated API usage.`

注意：引用大目录会消耗更多 token，请谨慎使用。

从实现上看，目录与 glob 模式的处理发生在resolveFilePaths（atCommandProcessor.ts）中：它通过工具注册表取出glob工具展开路径，并结合config.getFileFilteringOptions()应用.gitignore/.geminiignore过滤规则；被忽略的路径会被单独记录，且能区分是被 Git 忽略、被 Gemini 忽略还是两者都忽略（reason: 'git' | 'gemini' | 'both'），因此你在交互中能看到“该路径已被忽略”的提示而非静默丢弃。

文件探索：不知道路径时如何定位

如果你不知道确切文件路径，可以直接让 Gemini CLI 帮你找。这在熟悉陌生代码库或定位特定逻辑时非常实用。

场景：查找组件定义

你知道存在一个UserProfile组件，但不知道它在哪里：

`Find the file that defines the UserProfile component.`

Gemini 会调用glob或list_directory工具搜索项目结构，然后返回具体路径（例如src/components/UserProfile.tsx），你可以在下一轮用@直接引用它。

提示：你也可以要求列出文件，例如“Show me all the TypeScript configuration files in the root directory.”

这些探索类工具的技术参数可以参考仓库内的文件系统工具参考文档 docs/tools/file-system.md：

• list_directory（ls.ts）：列出指定路径下的文件和子目录，支持ignoreglob 排除参数和file_filtering_options（.gitignore/.geminiignore合规配置）。
• glob（glob.ts）：按 glob 模式（如"*.py"、"src/**/*.js"）在整个工作区查找文件，默认case_sensitive为false、respect_git_ignore为true，结果按修改时间倒序返回，并默认跳过node_modules、.git等噪声目录。
• grep_search（grep.ts）：在文件内容中做正则搜索，支持includeglob 过滤；在 Git 仓库中优先使用git grep提速，否则回退到系统grep或 JS 实现。

修改代码

当 Gemini CLI 已拥有上下文后，你可以指示它做具体修改。该 Agent 具备复杂重构能力，而非仅做简单文本替换：

`Update @src/components/UserProfile.tsx to show a loading spinner if the user data is null.`

Gemini CLI 使用replace工具提出定向代码变更。该工具的核心行为（详见 docs/tools/file-system.md 与 edit.ts）：

• 参数：file_path、instruction（变更的语义描述）、old_string（要查找的精确原文）、new_string（替换内容）、可选的allow_multiple；
• 默认要求old_string在文件中恰好出现一次，从而保证修改位置唯一、精确；如需替换全部相同位置，才需显式设置allow_multiple: true；
• 该工具需要用户手动确认（Confirmation: manual approval）。

创建新文件

你也可以让 Agent 从零创建新文件或目录结构：

`Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.`

Gemini CLI 使用write_file工具生成新文件。从 write-file.ts 的实现可以看到，该工具不仅负责写入（文件存在则覆盖、不存在则创建），还会引入diff库生成统一差异、通过resolveDefensiveToolPath做路径防御性校验（防止越出工作区边界）、用detectLineEnding保留原有换行符风格，并对写入内容做ensureCorrectFileContent校验——也就是说，即使是“写新文件”也会纳入下面的 diff 确认流程。

审查并确认变更

Gemini CLI 将安全放在首位：在任何文件被修改之前，它会展示拟议变更的统一 diff（unified diff）：

- if (!user) return null; + if (!user) return <LoadingSpinner />;

• 红色行（-）：将被删除的代码；
• 绿色行（+）：将被添加的代码。

按y确认并应用变更到本地文件系统；如果 diff 不符合预期，按n取消并细化你的提示词。这一确认机制在源码中由工具的ToolCallConfirmationDetails/ToolEditConfirmationDetails体系承载（见 write-file.ts 从tools.js引入的确认类型定义），write_file与replace都被标记为需要人工批准的工具。

验证结果

编辑完成后要验证修改：最简做法是再次读取文件，更好的做法是运行项目测试：

`Run the tests for the UserProfile component.`

Gemini CLI 使用run_shell_command工具执行你的测试框架（例如npm test或jest，实现位于 shell.ts），以确保变更没有破坏既有功能。

进阶：控制 Gemini 能看见什么

默认情况下，Gemini CLI 会遵循你的.gitignore文件：它不会读取或搜索node_modules、构建产物及其他被忽略的路径。

如果你有一些敏感文件（如.env）或大体积资源，希望在不把它们加入 Git ignore 的前提下对 AI 隐藏，可以在项目根目录创建.geminiignore文件：

.geminiignore示例：

.env local-db-dump.sql private-notes.md

.geminiignore的完整语法约定与.gitignore基本一致（详见 docs/cli/gemini-ignore.md）：

• 空行和以#开头的行被忽略；
• 支持标准 glob 模式（*、?、[]），例如*.md排除所有 Markdown 文件；
• 行尾加/只匹配目录；
• 行首加/将路径锚定到.geminiignore所在目录；
• !用于否定某条规则，例如：

# 排除所有 .md 文件，但保留 README.md *.md !README.md

需要注意：.geminiignore只影响支持该特性的工具（如@引用、glob、list_directory等），这些文件对 Git 等其他服务仍然可见；修改该文件后需要重启 Gemini CLI 会话才能生效。其读取与匹配逻辑位于 fileDiscoveryService.ts，配合上文提到的resolveFilePaths在@引用阶段即时过滤被忽略路径。

另外，如果你的项目目录不在信任列表中，Agent 的文件读写请求会额外受到权限提示的约束，可参考 Trusted folders 文档 了解访问权限管理。

延伸学习

• Memory management：管理上下文与记忆，让 Agent 在长会话中保持高效；
• Execute shell commands：更多运行测试与构建的实战；
• File system reference：read_file、write_file、replace等文件工具的完整参数技术参考；
• gemini-ignore：.geminiignore的独立功能文档。

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli