Gemini CLI 使用指南、架构详解与核心框架分析

1. 安装与配置

环境要求：
- Node.js 18+（推荐 LTS 版本）
- Git 2.30+（用于代码库操作）
- 稳定网络（需访问 Google 服务，需配置代理或 VPN）
安装方式：
- 临时安装（快速体验）：
```
npx https://github.com/google-gemini/gemini-cli
```
- 永久安装（推荐长期使用）：
```
npm install -g @google/gemini-cli
```
认证配置：
- Google 账户登录：绑定个人账户后，默认使用 Gemini 2.5 Pro 模型，每分钟 60 次请求，每日 1000 次免费额度。
- API Key 配置（高级场景）：
  1. 在 Google AI Studio 生成密钥。
  2. 设置环境变量：
```
export GEMINI_API_KEY="YOUR_API_KEY"  # Linux/macOS
set GEMINI_API_KEY="YOUR_API_KEY"    # Windows
```

2. 基础使用

非交互模式（适用于脚本集成）：

echo "请设计RESTful API架构" | gemini --non-interactive

3. 核心功能示例

代码生成与调试：

gemini > 将现有Java项目升级到Java 21，制定分阶段迁移计划

自动化工作流：

gemini > 根据代码生成Markdown格式API文档，含参数说明

多模态创作：

gemini > 基于用户调研数据生成SVG信息图，自动上传GitHub

4. 常见问题解决

命令未识别：

确认 npm 全局路径在 PATH 中：

npm config get prefix  # 查看全局安装路径

1. 整体架构
Gemini CLI 采用 “核心-外壳”（Core-Shell） 架构，分为两个核心包：

2. 模块化设计

工具系统：
- 每个工具（如文件操作、Shell 命令、网络搜索）为独立模块，支持动态加载。
- 示例工具调用流程：
  1. 用户请求 → 2. Core 解析意图 → 3. 调度工具（如 write-file） → 4. 沙箱执行 → 5. 返回结果。
沙箱机制：
- 工具执行在隔离环境中运行，防止恶意代码攻击。
- 支持不同操作系统（macOS/Linux/Windows）和安全级别配置。

3. 数据流与交互

用户输入处理：
- 交互模式：通过 Ink（React for CLI）渲染富终端界面。
- 非交互模式：从 stdin 读取输入，支持管道和重定向。
AI 交互流程：
1. 初始化：加载配置、认证信息、工具注册表。
2. 请求处理：发送用户输入至 Gemini API，解析响应和工具调用。
3. 工具执行：验证参数、请求确认（如需）、执行工具并收集结果。
4. 结果展示：实时显示 AI 响应和工具输出。

1. 核心包（@gemini-cli/core）

功能：
- 管理会话生命周期。
- 与 Google Gemini API 通信（支持代理和流式传输）。
- 执行工具调用（如 run_shell_command、read_file）。
关键技术：
- ProxyAgent：处理网络代理，解决地区限制问题。
- 安全沙箱：基于 node:vm2 或 Docker，隔离工具执行环境。

2. 命令行包（@gemini-cli/cli）

功能：
- 解析用户命令和参数。
- 渲染交互式界面（支持主题定制、命令历史）。
- 调用核心层执行请求。
技术亮点：
- Ink + React：构建现代化终端 UI，支持动态更新和状态管理。
- Hooks 架构：分离业务逻辑（如 useGeminiStream 处理 API 通信）。

3. 扩展性与生态