Gemini CLI 從原理到實戰

Gemini CLI 的難點不在安裝。真正容易混亂的是：它既是終端 AI agent，又和 Gemini Code Assist（Google 的 IDE/CLI 程式設計助手產品線）、Google Cloud、Gemini API Key、Vertex AI（Google Cloud 模型託管平臺）、MCP（Model Context Protocol，模型上下文協議）、GitHub Action、Skills、Subagents、Hooks 發生關係。

這一組文章只解決一個問題：怎樣把 Gemini CLI 理解成一套可以進入真實專案的 Google 系 AI 程式設計工作流。讀完以後，你應該能判斷它適合什麼任務、怎麼給上下文、什麼時候讓它執行、什麼時候只讓它規劃，以及它和 Codex、Claude Code、OpenCode 的差異。

這組文章不重複官方手冊。要查某個命令、配置項或官方引數，去官方教程中文版；要理解功能背後的使用判斷，讀這裡。

12 篇文章的主線

flowchart TD
    A["01 定位：Gemini CLI 是什麼"] --> B["02 起步：安裝、認證、第一次執行"]
    B --> C["03 迴圈：它怎麼完成任務"]
    C --> D["04 上下文：GEMINI.md 與記憶"]
    D --> E["05 執行：工具、Shell、許可權"]
    E --> F["06 擴充套件：MCP 與 Extensions"]
    F --> G["07 角色：Skills、Subagents、Hooks"]
    G --> H["08 控制：Plan、Checkpoint、Headless"]
    H --> I["09 成本：模型、配額、快取"]
    I --> J["10 生態：Code Assist、Cloud、GitHub"]
    J --> K["11 選擇：和 Codex / Claude / OpenCode 對比"]
    K --> L["12 實戰：真實專案貫穿"]

    style A fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style E fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style K fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style L fill:#fee2e2,stroke:#ef4444,stroke-width:2px

前四篇解決“它是什麼、怎麼跑、怎麼理解任務迴圈和上下文”。第五到第八篇解決“怎麼讓它受控地執行和擴充套件”。第九到第十二篇解決“成本、生態、選型和真實專案落地”。

先跑起來

安裝、認證、第一次啟動，先讓 Gemini CLI 完成一輪低風險只讀任務。

再控制邊界

理解工具、Shell、許可權、Plan mode 和 checkpoint，再讓它修改真實專案。

最後做選擇

和 Codex CLI、Claude Code、OpenCode 對比，決定它在你的工作流裡負責哪一塊。

三個學習階段

階段	先解決的問題	過關標準
上手	Gemini CLI 能不能在我的專案裡工作	能安裝、認證、啟動，並讓它只讀解釋專案結構
受控	怎麼讓它安全地讀、寫、跑命令	能區分工具、許可權、sandbox、plan、checkpoint 和人工確認邊界
融合	怎麼放進長期工作流和團隊流程	能接 MCP、Skills、Hooks、GitHub Action，並知道何時不用它

別急著追高階功能：MCP、Skills、Subagents、Hooks 和 GitHub Action 都有用，但它們應該建立在一個穩定的低風險起步流程上。第一輪任務如果連“只讀解釋專案結構”都沒跑穩，就不要先接複雜自動化。

官方資料與教程分工

官方教程中文版按功能分類，適合查命令、配置、引數和入口：

從原理到實戰不重複官方手冊，而是把這些能力串成使用判斷：

功能是什麼：只保留足夠理解的定義，不堆引數。
為什麼要用：解釋它解決的真實開發問題。
怎麼上手：給一個低風險最小動作。
常見坑：指出新手最容易誤用的地方。
下一步：把當前文章接到前後篇和官方頁。

先記住一張分層圖

入口层      Terminal CLI / Cloud Shell / VS Code agent mode / GitHub Action
身份层      Google OAuth / Gemini API Key / Vertex AI / Code Assist license
上下文层    GEMINI.md / settings.json / memory / .geminiignore
执行层      file system / shell / web fetch / web search / todos / planning
扩展层      MCP / Extensions / Skills / Subagents / Hooks
治理层      trusted folders / sandbox / policy engine / telemetry / enterprise controls

如果你只想快速使用，先掌握入口層、身份層、上下文層和執行層。如果要進團隊和自動化，再進入擴充套件層和治理層。

從定位開始：Gemini CLI 是什麼。這一篇會先拆清楚 Gemini CLI 為什麼不是“又一個命令列聊天框”，以及它和 Gemini Code Assist 的關係。