---
title: "Gemini CLI 怎麼完成一個任務"
description: "理解 Gemini CLI 的任務迴圈：上下文裝載、計劃、工具呼叫、觀察、迭代和人工確認。"
verifiedAt: "2026-05-09"
---

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

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

## 任務迴圈

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

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

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

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

## 判斷迴圈是否健康

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

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

## 觀察結果怎麼用

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

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

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

## 官方資料

- 官方 docs index：[docs/index.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md)
- Plan mode 🔬（計劃模式）：[docs/cli/plan-mode.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/plan-mode.md)
- Checkpointing：[docs/cli/checkpointing.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/checkpointing.md)
- Tools reference：[docs/reference/tools.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md)

## 最小可控提示

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

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

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

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

## 下一篇

<Cards>
  <Card title="GEMINI.md、記憶和專案上下文" description="下一步把一次性說明沉澱成可重複上下文。" href="/zh-Hant/docs/gemini-cli/understanding/04-project-context-gemini-md" />
  <Card title="CLI 工作流" description="需要查 slash commands、planning、checkpoint、plan mode 時，回到官方工作流頁。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow" />
  <Card title="工具與 MCP" description="需要理解具體工具能力和 MCP 接入時，回到工具頁。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp" />
</Cards>
