Gemini CLI 怎麼完成一個任務

Gemini CLI 完成任務不是"一次回答結束"。更準確的模型是：它在一個 agent loop（代理迴圈：邊推理邊呼叫工具的迴圈）裡不斷讀取上下文、選擇工具、觀察結果，再決定下一步。

讀懂 agent loop 之後，你就能判斷什麼時候該讓 Gemini CLI 只讀、什麼時候該讓它規劃、什麼時候才允許它寫檔案或跑命令。

任務迴圈

flowchart LR
    A["使用者目標"] --> B["讀取上下文"]
    B --> C["形成計劃"]
    C --> D["選擇工具"]
    D --> E["執行或請求確認"]
    E --> F["觀察結果"]
    F --> G{"目標完成?"}
    G -- "否" --> C
    G -- "是" --> H["總結和交付"]

這個迴圈裡，模型不是唯一變數。工具許可權、上下文質量、專案配置和你的確認策略同樣重要。

上下文來自哪裡

Gemini CLI 可以從這些地方理解任務：

當前對話。
當前工作目錄。
GEMINI.md。
settings.json。
memory。
檔案系統工具讀取到的檔案。
MCP、extensions 或 web 工具返回的外部資訊。

上下文越雜，越需要明確“以哪個檔案為準”。否則 agent 容易把臨時討論、舊文件和真實原始碼混在一起。

工具呼叫意味著什麼

工具呼叫是 Gemini CLI 和普通聊天的核心差異。模型可以不只是“建議你執行命令”，而是請求執行讀檔案、寫檔案、shell、web fetch、MCP 等工具。

這帶來兩個結果：

它可以完成真實工作。
它也可能造成真實副作用。

所以要先區分只讀工具、寫入工具和外部副作用工具。

三類任務模式

模式	Gemini CLI 應該怎麼做	適合場景
只讀解釋	讀取檔案、梳理結構、指出風險，不寫入	新儲存庫、報錯定位前、併發協作
計劃優先	先給檔案範圍、步驟、驗證和停止條件	多檔案改動、遷移、釋出、安全任務
執行驗證	小批次修改、看 diff、跑檢查、總結影響	邊界清楚、可回退、能驗證的任務

這三種模式不要混用。你說“先分析”，它就不應該改檔案；你說“直接執行”，也要先確認任務邊界已經足夠清楚。

什麼時候讓它規劃

複雜任務先規劃，尤其是：

要改多個檔案。
要跑遷移或釋出。
涉及金鑰、賬號、賬單、遠端伺服器。
當前儲存庫有併發編輯。
你還不確定目錄職責。

規劃階段的輸出應該包括檔案範圍、驗證方式、風險邊界和回復點。

什麼時候讓它執行

執行適合邊界清楚、可驗證、失敗可恢復的任務：

補一頁文件。
改一個小 bug。
執行只讀檢查。
生成測試草案。
根據官方文件更新配置。

如果一個任務無法說明驗收標準，就不應該直接執行。

觀察結果為什麼重要

Agent loop 的關鍵不只是“會呼叫工具”，而是每次呼叫後會根據結果調整下一步。比如測試失敗時，它不應該繼續大改，而應該讀失敗資訊、縮小範圍、修最小問題，再重新驗證。

一個健康的迴圈通常長這樣：

提出假设 -> 读取证据 -> 最小改动 -> 验证 -> 根据结果继续或停止

如果它開始在沒有證據的情況下連續改檔案，說明任務邊界或許可權策略需要收緊。

判斷迴圈是否健康

健康的 agent loop 會先拿證據，再做小動作，再驗證。異常迴圈通常有三個訊號：不讀檔案就下結論，測試失敗後連續大改，沒有說明下一步風險。遇到這三種情況，應該收回寫許可權，回到只讀分析或 Plan mode。

理解這點後，你就能把“模型回答不好”拆成具體問題：上下文不足、工具許可權過寬、計劃不清、驗證缺失，還是模型能力不夠。

觀察結果怎麼用

每次工具呼叫後，都應該把輸出變成下一步依據。read_file 的結果決定是否需要繼續讀上下文；shell 的 exit code 決定是否繼續修改；web fetch 的來源決定事實是否可引用；MCP resource 的內容決定是否允許後續寫工具。

如果 agent 忽略工具輸出，繼續按原計劃執行，說明迴圈已經失真。此時應要求它重新總結證據，再決定下一步，而不是繼續追加新需求。

這也是商業級教程必須寫驗證的原因：沒有觀察和驗證，agent loop 只是更長的聊天。

官方資料

官方 docs index：docs/index.md
Plan mode 🔬（計劃模式）：docs/cli/plan-mode.md
Checkpointing：docs/cli/checkpointing.md
Tools reference：docs/reference/tools.md

最小可控提示

可以用一句話把迴圈拉回可控狀態：

先说明你已经读取了哪些证据，再给下一步计划，不要在没有证据时修改文件。

這句話能逼 agent 把“觀察結果”顯式說出來。它答不上來，就說明還沒到執行階段。

如果它只能給結論，不能列出檔案路徑、命令輸出或官方來源，就先讓它回到只讀證據採集。真實專案裡，證據鏈比回答速度更重要。