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 的关系。