gemini-cli：把 Gemini 装进终端的 Apache-2.0 agent
谷歌开源的终端 AI agent，在项目目录里直接对话，让它读代码、跑 shell、改代码、跑测试。TypeScript 编写，Apache-2.0，兼作 MCP 客户端与服务端。
终端里敲一句自然语言，它就去读你的代码、跑你的 shell、改你的文件——这件事听起来像 demo，但它已经是一个 10.7 万星、Apache-2.0 的正式开源项目。更有意思的是：它的 README 顶部挂着一句「Gemini CLI 已被 Antigravity CLI 取代」。一个被官方宣告交接的项目，为什么还值得拆？因为它的架构选择、MCP 双向设计、无头模式输出协议，构成了今天终端 agent 这一类工具的完整样本。读懂它，等于读懂一整类工具。
先看它到底在终端里做什么
Gemini CLI 的定位一句话能说完：把 Gemini 直接带进终端，给你从 prompt 到模型的最短路径。但「最短路径」这四个字背后是一组具体能力：
- 代码理解与生成：查询和编辑大型代码库；用多模态能力从 PDF、图片、草图生成新应用；用自然语言调试排障。
- 自动化与集成：自动查询 pull request、处理复杂 rebase 这类运维任务；通过 MCP server 接入新能力（README 点名了 Imagen、Veo、Lyria 的媒体生成）；在脚本里非交互式运行。
- 三种认证路径：Google 账号 OAuth 登录（组织付费 Code Assist 许可需额外设
GOOGLE_CLOUD_PROJECT）、Gemini API Key（适合需要指定模型或付费额度的开发者）、Vertex AI（适合企业团队与生产负载，需GOOGLE_GENAI_USE_VERTEXAI=true）。
这三条认证路径不是随便列的。它对应三种真实用户：个人、按量付费的独立开发者、有合规要求的企业。同一个 CLI 二进制，靠环境变量切换后端，这是它作为「入口」而非「产品」的设计取向。
架构：三层，加一个双向的 MCP 接口
README 没有给架构图，但从它列出的组件名可以还原出清晰的分层。核心是三层加一条横向扩展通道。
第一层：终端交互层。 这是用户直接接触的部分。它有两种形态——交互式 REPL（直接敲 gemini 进入，支持斜杠命令如 /help、/chat，支持自定义命令，支持 GEMINI.md 作为持久上下文文件，支持 checkpointing 保存和恢复会话，支持 token caching 优化用量）；以及非交互式 headless 模式（-p 传一个 prompt 直接出结果）。这一层还挂着 IDE 集成（VS Code 伴生插件）和键盘快捷键体系。
第二层：Agent 编排层。 这是它和「一个套了 API 的 shell 脚本」的分水岭。它负责把用户的自然语言目标拆成多步动作，决定什么时候调工具、调哪个工具、拿到结果后下一步做什么。README 里「读取代码、执行 shell 命令并完成改代码、跑测试这类多步任务」描述的正是这一层的职责。配套的治理机制也在这里：沙箱（sandboxing & security，安全执行环境）、可信文件夹（trusted folders，按目录控制执行策略）、遥测与监控。这些不是附属功能，是让 agent 敢在你的真实项目目录里动手的前提。
第三层：工具层。 内置工具分三类，README 明确列出：文件系统操作、Shell 命令、Web 抓取与搜索。这是 agent 的「手脚」，编排层通过它们真正改变世界。
横向通道：MCP。 这是整个架构里最值得单独说的一环。仓库的 topics 里同时挂着 mcp-client 和 mcp-server——它既是 MCP 客户端，也是 MCP 服务端。作为客户端，你在 ~/.gemini/settings.json 里配置 MCP server，就能把外部能力接进来，用法是在 prompt 里用 @ 前缀点名：
text> @github List my open pull requests > @slack Send a summary of today's commits to #dev channel > @database Run a query to find inactive users
作为服务端，它自己也能被别的 agent 或工具调用。这个双向设计意味着它不试图把所有能力都内置，而是把自己定位成终端里的一个 MCP 枢纽——能力从外面来，也从这里出去。README 还提到自定义扩展（custom extensions），可以构建并分享自己的命令。
把三层和 MCP 放在一起看，数据流是这样的：用户在终端输入 → 交互层解析（斜杠命令、@ 提及、上下文文件注入）→ 编排层把目标转成工具调用序列 → 工具层执行文件/Shell/Web 操作，或经 MCP 通道转发给外部 server → 结果回到编排层决定下一步 → 最终以文本、JSON 或流式 JSON 回到终端。
| 层 | 核心组件 | 职责 | 对应 README 依据 |
|---|---|---|---|
| 终端交互层 | REPL、斜杠命令、自定义命令、GEMINI.md、checkpointing、token caching、headless 模式、IDE 集成 | 接收输入、管理会话与上下文、输出结果 | Commands Reference / Custom Commands / Context Files / Checkpointing / Token Caching / Headless Mode / IDE Integration |
| Agent 编排层 | 多步任务规划、沙箱、可信文件夹、遥测 | 拆解目标、调度工具、约束执行边界 | Sandboxing & Security / Trusted Folders / Telemetry & Monitoring |
| 工具层 | 文件系统操作、Shell 命令、Web Fetch & Search | 实际读写文件、执行命令、访问网络 | Built-in Tools Overview |
| 扩展通道 | MCP 客户端 + MCP 服务端、自定义扩展 | 接入外部能力、对外暴露自身 | MCP Server Integration / topics: mcp-client, mcp-server |
这张表里没有一行是我补的，全部落在 README 的文档索引和 topics 上。这也是判断一个终端 agent 是否「真的能干活」的清单：缺了编排层，它只是个问答框；缺了沙箱和可信文件夹，它是个危险品；缺了 MCP，它是个封闭盒子。
装起来，跑起来
安装路径给得很宽，覆盖了不同环境的约束：
bash# 不安装，直接跑 npx @google/gemini-cli # npm 全局安装 npm install -g @google/gemini-cli # Homebrew（macOS/Linux） brew install gemini-cli # MacPorts（macOS） sudo port install gemini-cli # 受限环境用 Anaconda conda create -y -n gemini_env -c conda-forge nodejs conda activate gemini_env npm install -g @google/gemini-cli
在受限环境里用 conda 起一个 nodejs 再装 npm 包，这个细节说明它认真考虑过企业内网和隔离环境——不是所有人都能直接 npm install -g。
装完就有发布通道可选，三个 tag 对应三种风险偏好：
| 通道 | 发布节奏 | 定位 | 安装命令 |
|---|---|---|---|
| Preview | 每周二 UTC 23:59 | 未完全验证，可能含回归 | npm install -g @google/gemini-cli@preview |
| Stable | 每周二 UTC 20:00 | 上周 preview 的完整提升 + 修复与验证 | npm install -g @google/gemini-cli@latest |
| Nightly | 每天 UTC 00:00 | main 分支当日全部改动，默认有未验证问题 | npm install -g @google/gemini-cli@nightly |
Stable 是「上周 preview 的完整提升」，这句话很关键：它不是从 main 直接切一个稳定版，而是让 preview 先跑一周再转正。这是把 CI 风险前置到愿意尝鲜的用户身上。
最小可用用法就是进目录、开对话：
bashcd new-project/ gemini > Write me a Discord bot that answers questions using a FAQ.md file I will provide
或者分析一个已有仓库：
bashgit clone https://github.com/google-gemini/gemini-cli cd gemini-cli gemini > Give me a summary of all of the changes that went in yesterday
几个常用开关值得记住：gemini --include-directories ../lib,../docs 把多个目录纳入上下文；gemini -m gemini-2.5-flash 指定模型；gemini -p "..." 进非交互模式。
无头模式：它真正的工程价值在这里
大多数人把终端 agent 当交互工具用，但 Gemini CLI 的输出协议设计说明它更想被当成一个可编程组件。-p 之外还有两种结构化输出：
bash# 纯文本响应 gemini -p "Explain the architecture of this codebase" # 结构化 JSON，便于程序解析 gemini -p "Explain the architecture of this codebase" --output-format json # 换行分隔的 JSON 事件流，适合监控长任务 gemini -p "Run tests and deploy" --output-format stream-json
stream-json 这个选项暴露了设计意图：长时运行的操作需要被外部监控，而不是让调用方干等一个最终结果。这直接把 Gemini CLI 塞进了 CI 流水线、运维脚本、定时任务的场景里——README 里「Run non-interactively in scripts for workflow automation」不是一句口号，是有对应输出格式支撑的。
再叠加 MCP 服务端能力，它就能成为更大 agent 系统里的一个执行节点：别的系统通过 MCP 调它，它通过 MCP 调 GitHub、Slack、数据库。终端只是它的默认界面，不是它的边界。
和同主题项目比，它站在哪个位置
同为 TypeScript 写的 agent 框架，deepseek-harness 的核心理念是「一切皆插件」，把工具调用、prompt 编排拆成可插拔模块，让你按需组装自己的 agent。Gemini CLI 走的是相反的路：它给你一个装好的、开箱能用的成品，扩展点留在 MCP 和自定义命令上，而不是让你从零件开始拼。前者是框架，后者是应用——虽然两者都能被改，但默认体验完全不同。
graphify 解决的是另一个问题：把代码库连同文档、SQL schema、配置和 PDF 转成可查询的知识图谱，让 agent 读懂项目全貌，提供 /graphify skill 接入 Claude Code、Cursor 等 CLI，用本地 AST 解析建图。它和 Gemini CLI 不是竞争关系，而是互补——Gemini CLI 自己提供 GEMINI.md 作为持久上下文，但那是手写的；graphify 提供的是自动建图。一个 agent 完全可以同时用两者：graphify 喂全局理解，Gemini CLI 执行具体动作。
browser-use 是 Python 的浏览器操控 agent，让模型打开页面、点击、填表、提取结果。它的作用域是网页，Gemini CLI 的作用域是本地项目目录和 shell。两者的工具集几乎不重叠。
TradingAgents 是多 agent 协作的金融交易框架，把分析师、研究员、交易员拆成角色互相辩论。这是「多 agent 编排」范式，Gemini CLI 是「单 agent + 多工具」范式。前者适合需要多视角对抗决策的场景，后者适合有明确执行目标的工程任务。
JavaGuide 是知识指南，不是工具，放在这里只说明一件事：AI agent 这个主题下的高星项目，有的是工具，有的是知识库，星标数不能直接横向比较。
归纳一下定位差异：Gemini CLI 是这批项目里唯一一个「官方模型厂商出品 + 终端原生 + MCP 双向」的组合。它的优势不在于可定制性（那是 deepseek-harness 的地盘），也不在于特定领域深度（那是 browser-use 和 TradingAgents 的地盘），而在于把模型能力到终端执行这条链路做得最短、最完整。
那个必须说清楚的交接
README 顶部两条 NOTE 不能绕过：
Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026.
Gemini CLI has not been optimized for Gemini 4 Argon. To use Gemini 4 Argon, please use Antigravity.
也就是说，免费层和 Google One 用户已经被引导去 Antigravity CLI；Gemini CLI 本身没有针对最新的 Gemini 4 Argon 做优化。README 里「Getting Started」段还重复了一遍这个提示。这不是一个还在全力冲刺的项目状态，而是一个进入维护/交接期的项目状态。
这带来两个实际判断：
第一，如果你要评估「现在该不该选它」，答案取决于你的身份。企业付费用户走 Vertex AI 路径，功能面仍然是完整的；但如果你在免费层，官方已经明确让你去别处。
第二，如果你要学习「终端 agent 该怎么设计」，它依然是最好的教材之一——三层架构、MCP 双向、三种输出格式、沙箱与可信文件夹的分层治理，这些设计不会因为项目交接而失效。恰恰相反，一个被官方用另一个产品接管的项目，它的架构决策经过了真实用户的检验。
值得记住的几件事
- 10.7 万星、1.47 万 fork、Apache-2.0：这个体量的开源 agent，代码是可以直接读的，
google-gemini/gemini-cli仓库的 CI 和 E2E 徽章都挂在 README 上，工程质量是公开可查的。 - MCP 双向是它最被低估的设计：topics 里
mcp-client和mcp-server并列，意味着它既能消费生态，也能被生态消费。这比单纯「支持 MCP」高一个维度。 - 三种输出格式决定了它的使用边界：纯文本给人看，JSON 给程序看，stream-json 给监控系统看。一个 CLI 认真设计输出协议，说明它想被集成，而不只是想被使用。
- 治理机制和 agent 能力同等重要：沙箱、可信文件夹、token caching、checkpointing，这些不是锦上添花，是让 agent 在真实项目里可用的必要条件。
如果你只想试一次，npx @google/gemini-cli 就够了。如果你想理解终端 agent 这类工具的全貌，从它的 ~/.gemini/settings.json 和 --output-format stream-json 两个入口读进去，比读任何综述都快。