檔案系統工具
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 <目標目錄>，防止覆蓋別人正在改的檔案。