Gemini CLI 架构学习指南

📖 写在前面的话
嘿,欢迎来到 Gemini CLI 的学习之旅!如果你对 AI 编程助手感兴趣,想了解 Google 是如何打造一个开源的终端 AI 助手的,那你来对地方了。这份指南会像你的私人教练一样,带你从零开始,一步步拆解这个项目的"筋骨"。别担心,我会用最直白的语言,让你既能快速上手,又能深入理解其设计精髓。准备好了吗?Let's dive in! 🚀

第一部分:项目架构深度解析(像架构师一样俯瞰全景)🔍

1. 项目架构概览

用一个类比来理解

想象一下你走进一家米其林餐厅 🍽️:

前厅服务员(CLI Package)负责与你交流,记录你的需求,呈现精美的菜品
后厨团队(Core Package)负责处理订单,调度厨师,烹饪美食
各个料理台(Tools)负责具体的任务:切菜、炒菜、烤肉...
供应商接口(MCP协议)让餐厅可以随时对接新的食材来源

Gemini CLI 就是这样一个"智能餐厅",把你的指令优雅地转化为 AI 的行动!

核心设计特征

架构模式: 📐 典型的前后端分离架构 + 插件化工具系统

┌─────────────────────────────────────────────────┐
│               User Input (Terminal)              │
└────────────────────┬────────────────────────────┘
                     │
         ┌───────────▼──────────┐
         │   CLI Package (前端)  │  ← React + Ink 终端 UI
         │  - 用户交互           │
         │  - 结果展示           │
         │  - 配置管理           │
         └───────────┬──────────┘
                     │ IPC/API
         ┌───────────▼──────────┐
         │  Core Package (后端)  │  ← 核心逻辑引擎
         │  - Gemini API 客户端  │
         │  - 会话管理           │
         │  - 工具调度           │
         └───────────┬──────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
   ┌────▼────┐            ┌──────▼─────┐
   │  Tools  │            │ MCP Servers │
   │ 内置工具 │            │  扩展工具   │
   └─────────┘            └────────────┘

与同类项目对比:

VS GitHub Copilot CLI: Gemini CLI 是完全开源的(Apache 2.0),你可以自由修改和扩展
VS Cursor: Cursor 是 IDE,Gemini CLI 是纯终端工具,更轻量、更适合命令行爱好者
VS Aider: 功能类似,但 Gemini CLI 有 Google 官方支持,集成了企业级特性(沙箱、策略引擎、遥测)
独特优势:
- ✅ 使用 React 构建 CLI(通过 Ink 框架),让终端 UI 组件化、可测试
- ✅ MCP 协议原生支持,可以连接无限扩展工具
- ✅ 免费额度慷慨(60 req/min, 1000 req/day)

技术栈分析

技术层次	核心技术	版本要求	选型理由
语言	TypeScript	5.3+	类型安全,大型项目标配
运行时	Node.js	≥20.0.0	现代 ES Module 支持
UI 框架	React 19 + Ink 6	-	组件化终端 UI 🎨
API SDK	@google/genai	1.16.0	Gemini API 官方客户端
测试	Vitest 3	-	快速、现代、兼容 ESM
打包	esbuild	-	极速编译 ⚡
Monorepo	npm workspaces	-	内置支持,无需额外工具
协议	MCP SDK	1.15+	Model Context Protocol 标准
可观测性	OpenTelemetry	-	企业级监控 📊
认证	google-auth-library	-	OAuth2 + Service Account

为什么选择 React + Ink? 🤔

这是一个非常有趣的技术选择!大部分 CLI 工具用的是 inquirer 或 blessed 这类库,但 Gemini CLI 选择了 React:

组件复用: 可以像写 Web 应用一样编写终端 UI,代码结构清晰
状态管理: React 的 Hooks 和 Context 让复杂状态管理变得容易
可测试性: 可以用 ink-testing-library 像测试 React 组件一样测试 CLI
声明式: <Text> <Box> 比命令式的 console.log 更好维护

外部系统集成

graph LR
    A[Gemini CLI] --> B[Gemini API]
    A --> C[Google OAuth]
    A --> D[文件系统]
    A --> E[Shell]
    A --> F[Git]
    A --> G[MCP Servers]
    G --> H[第三方服务]

    B --> I[Gemini 2.5 Pro/Flash]
    C --> J[Google Account]
    H --> K[@github<br/>@slack<br/>@database...]

配置管理模式:

全局配置: ~/.gemini/settings.json (用户级设置)
项目配置: GEMINI.md (项目上下文)
环境变量: GEMINI_API_KEY, GOOGLE_CLOUD_PROJECT 等
命令行参数: --model, --output-format 等

架构流程描述

让我们跟踪一个典型的用户请求 —— "帮我重构 auth.ts 文件":

sequenceDiagram
    participant U as User
    participant CLI as CLI Package
    participant Core as Core Package
    participant Gemini as Gemini API
    participant Tools as Tools

    U->>CLI: "帮我重构 auth.ts"
    CLI->>CLI: 解析输入,加载上下文
    CLI->>Core: 发送请求 + 工作目录上下文

    Core->>Core: 构建 Prompt<br/>(包含工具定义)
    Core->>Gemini: 发送 Prompt

    Gemini->>Core: 返回响应<br/>(请求调用 read_file)
    Core->>CLI: 请求用户确认工具调用
    CLI->>U: 显示确认对话框
    U->>CLI: 批准

    CLI->>Core: 确认执行
    Core->>Tools: 调用 read_file("auth.ts")
    Tools->>Core: 返回文件内容

    Core->>Gemini: 发送工具结果
    Gemini->>Core: 返回重构建议
    Core->>CLI: 返回最终响应
    CLI->>U: 美化展示结果

关键流程节点:

输入处理 (packages/cli/src/ui/App.tsx)
- 接收终端输入
- 触发命令处理或自然语言查询
请求构建 (packages/core/src/core/client.ts)
- 构建 Gemini API 请求
- 注入系统提示词
- 附加工具定义
API 交互 (packages/core/src/core/geminiChat.ts)
- 管理多轮对话历史
- 处理流式响应
- 实现 Token 缓存优化
工具调用 (packages/core/src/core/coreToolScheduler.ts)
- 解析工具调用请求
- 执行安全检查
- 返回工具结果
结果渲染 (packages/cli/src/ui/components/)
- Markdown 渲染
- 语法高亮
- 交互式确认对话框

2. 目录结构与核心流程

目录组织逻辑

这是一个标准的 monorepo 按功能模块划分 的结构:

gemini-cli/
├── packages/                    # Monorepo 工作区
│   ├── cli/                    # 📱 前端:用户交互层
│   │   └── src/
│   │       ├── ui/             # React 组件(终端 UI)
│   │       │   ├── App.tsx     # 主应用入口 ⭐
│   │       │   ├── components/ # 可复用组件(对话框、Markdown渲染等)
│   │       │   ├── hooks/      # 自定义 React Hooks
│   │       │   ├── contexts/   # React Context(全局状态)
│   │       │   └── themes/     # 主题系统
│   │       ├── config/         # 配置管理
│   │       │   ├── settings.ts # 设置文件解析
│   │       │   ├── auth.ts     # 认证配置
│   │       │   └── policy.ts   # 策略引擎
│   │       ├── commands/       # 命令处理
│   │       ├── services/       # 业务服务
│   │       └── gemini.tsx      # CLI 入口 🚪
│   │
│   ├── core/                   # 🧠 后端:核心逻辑层
│   │   └── src/
│   │       ├── core/           # 核心逻辑
│   │       │   ├── client.ts   # Gemini 客户端 ⭐
│   │       │   ├── geminiChat.ts # 会话管理
│   │       │   ├── turn.ts     # 轮次管理
│   │       │   └── prompts.ts  # 提示词构建
│   │       ├── tools/          # 工具实现 🛠️
│   │       │   ├── read-file.ts
│   │       │   ├── write-file.ts
│   │       │   ├── shell.ts
│   │       │   └── mcp-client.ts # MCP 协议客户端
│   │       ├── services/       # 服务层
│   │       │   ├── fileSystemService.ts
│   │       │   ├── gitService.ts
│   │       │   └── shellExecutionService.ts
│   │       ├── mcp/            # MCP 协议实现
│   │       ├── agents/         # 子代理系统
│   │       └── telemetry/      # 遥测监控
│   │
│   ├── a2a-server/            # 🤝 Agent-to-Agent 服务器
│   ├── vscode-ide-companion/  # 💻 VSCode 扩展
│   └── test-utils/            # 🧪 测试工具
│
├── docs/                       # 📚 完整的项目文档
├── integration-tests/          # 🔬 集成测试
├── scripts/                    # ⚙️ 构建和发布脚本
└── bundle/                     # 📦 最终打包产物

设计意图:

按领域划分: CLI 负责展示,Core 负责逻辑,职责清晰
高内聚低耦合: 每个 package 都可以独立测试和发布
可扩展性: 新增工具只需在 core/src/tools/ 添加文件

关键文件定位

🎯 第一个应该阅读的文件(按顺序):

README.md - 了解项目用途和快速开始
docs/architecture.md - 理解整体架构
packages/cli/src/gemini.tsx - CLI 入口,理解启动流程
packages/core/src/core/client.ts - 核心客户端,理解与 API 交互
packages/core/src/tools/tools.ts - 工具系统基础,理解扩展机制

💡 核心业务逻辑所在:

功能模块	核心文件路径	说明
CLI 启动	`packages/cli/src/gemini.tsx`	应用入口,初始化流程
主 UI	`packages/cli/src/ui/App.tsx`	主界面组件
API 客户端	`packages/core/src/core/client.ts`	Gemini API 封装
会话管理	`packages/core/src/core/geminiChat.ts`	多轮对话管理
工具注册	`packages/core/src/tools/tool-registry.ts`	工具系统核心
文件工具	`packages/core/src/tools/read-file.ts`	文件读取实现
Shell 工具	`packages/core/src/tools/shell.ts`	命令执行实现
MCP 客户端	`packages/core/src/tools/mcp-client.ts`	MCP 协议实现

模块依赖关系

graph TD
    CLI[CLI Package] --> Core[Core Package]
    CLI --> TestUtils[Test Utils]
    Core --> TestUtils
    A2A[A2A Server] --> Core
    VSCode[VSCode Companion] --> Core

    Core -.-> GenAI[@google/genai]
    Core -.-> MCP[@modelcontextprotocol/sdk]
    Core -.-> OTel[OpenTelemetry]

    CLI -.-> React[React]
    CLI -.-> Ink[Ink]

    style CLI fill:#e1f5ff
    style Core fill:#fff4e1
    style A2A fill:#f0f0f0
    style VSCode fill:#f0f0f0

依赖特点:

✅ 单向依赖: CLI 依赖 Core,但 Core 不依赖 CLI
✅ 接口隔离: 通过 TypeScript 接口定义清晰的 API 边界
✅ 无循环依赖: 项目使用 ESLint 规则禁止循环依赖

典型业务流程:文件重构场景

让我们选择一个最具代表性的场景 —— "重构代码文件",看看数据是如何流转的:

场景: 用户输入 "重构 src/auth.ts,提取认证逻辑到独立函数"

sequenceDiagram
    autonumber
    participant User
    participant App as App.tsx<br/>(CLI)
    participant Client as client.ts<br/>(Core)
    participant Chat as geminiChat.ts
    participant Scheduler as coreToolScheduler.ts
    participant ReadTool as read-file.ts
    participant WriteTool as write-file.ts
    participant Gemini as Gemini API

    User->>App: 输入重构请求
    App->>Client: sendMessage()

    Client->>Chat: 添加用户消息到历史
    Chat->>Chat: 构建 Prompt<br/>(包含工具列表)
    Chat->>Gemini: POST /generateContent

    Gemini-->>Chat: 返回工具调用请求<br/>{tool: "read_file", args: {path: "src/auth.ts"}}

    Chat->>Scheduler: 调度工具执行
    Scheduler->>App: 请求用户确认<br/>"是否允许读取 src/auth.ts?"
    App->>User: 显示确认对话框
    User->>App: 批准

    App->>Scheduler: 确认执行
    Scheduler->>ReadTool: execute({path: "src/auth.ts"})
    ReadTool-->>Scheduler: 返回文件内容

    Scheduler->>Chat: 工具结果
    Chat->>Gemini: POST /generateContent<br/>(附带工具结果)

    Gemini-->>Chat: 返回重构后的代码 + 写入请求<br/>{tool: "write_file", args: {...}}

    Chat->>Scheduler: 调度写入工具
    Scheduler->>App: 请求确认写入
    App->>User: 显示 Diff + 确认
    User->>App: 批准

    App->>Scheduler: 确认
    Scheduler->>WriteTool: execute({path: "src/auth.ts", content: "..."})
    WriteTool-->>Scheduler: 写入成功

    Scheduler->>Chat: 工具结果
    Chat->>Client: 最终响应
    Client->>App: 返回结果
    App->>User: 显示成功消息 ✅

实现文件索引:

步骤	核心文件	关键代码行
① 输入处理	`packages/cli/src/ui/App.tsx`	`onSubmit` 函数
② 发送请求	`packages/core/src/core/client.ts`	`sendMessage()` 方法
③ 构建 Prompt	`packages/core/src/core/prompts.ts`	`getCoreSystemPrompt()`
④ API 调用	`packages/core/src/core/geminiChat.ts`	`generateContent()`
⑤ 工具调度	`packages/core/src/core/coreToolScheduler.ts`	`scheduleTools()`
⑥ 读文件	`packages/core/src/tools/read-file.ts`	`execute()` 方法
⑦ 确认对话	`packages/cli/src/ui/components/ToolConfirmation.tsx`	整个组件
⑧ 写文件	`packages/core/src/tools/write-file.ts`	`execute()` 方法

3. 代码结构观察

代码组织模式

这个项目遵循了非常优秀的工程实践,让我们来看看亮点 ✨:

1. 函数式编程优先

// ✅ 推荐:使用纯对象 + 接口
interface User {
   
  id: string;
  name: string;
}

function createUser(id: string, name: string): User {
   
  return {
    id, name };
}

// ❌ 避免:使用类
class User {
   
  constructor(public id: string, public name: string) {
   }
}

理由(来自 CONTRIBUTING.md):

React 组件更适合处理纯数据
更容易序列化(JSON)
避免 this 绑定问题
鼓励不可变性

2. ES Module 封装

// packages/core/src/tools/read-file.ts

// 私有函数(未导出)
function validatePath(path: string): boolean {
   
  // 实现细节
}

// 公共 API(导出)
export async function readFile(path: string): Promise<string> {
   
  if (!validatePath(path)) {
   
    throw new Error('Invalid path');
  }
  // ...
}

优势:

清晰的公共 API 边界
不需要 private/public 关键字
更好的 Tree-shaking

3. React Hooks 模式

// packages/cli/src/ui/hooks/useAuth.ts
export function useAuth() {
   
  const [authState, setAuthState] = useState<AuthState>('idle');
  const [user, setUser] = useState<User | null>(null);

  const login = useCallback(async () => {
   
    setAuthState('loading');
    // OAuth 流程...
  }, []);

  return {
    authState, user, login };
}

特点:

所有状态逻辑封装在自定义 Hook
组件保持纯粹的展示逻辑
可独立测试

设计模式识别

设计模式	使用位置	说明
工厂模式	`packages/core/src/tools/tool-registry.ts`	动态创建工具实例
策略模式	`packages/core/src/routing/strategies/`	不同的模型路由策略
观察者模式	`packages/cli/src/utils/events.ts`	事件总线(`appEvents`)
单例模式	`packages/core/src/telemetry/`	全局遥测服务
装饰器模式	`packages/core/src/core/loggingContentGenerator.ts`	为内容生成器添加日志
责任链模式	`packages/cli/src/services/prompt-processors/`	提示词预处理器链

代码质量观察

✅ 优点:

完整的测试覆盖 🧪
- 每个源文件都有对应的 .test.ts
- 使用 Vitest + ink-testing-library
- 测试覆盖率在 CI 中强制检查
严格的类型检查 📝
- 使用 TypeScript 5.3+
- 几乎没有 any 类型
- 使用 unknown 而非 any
清晰的错误处理 ⚠️
- 自定义错误类型(packages/core/src/utils/errors.ts)
- 统一的错误上报机制
优秀的文档 📚
- 每个公共 API 都有 JSDoc
- 独立的文档站点(docs/)
- 丰富的示例和教程

🤔 可以学习的改进点:

大型组件拆分机会
- packages/cli/src/ui/App.tsx (~473 行)
- 可以提取更多子组件
配置复杂度
- 配置来源多样(文件/环境变量/命令行)
- 可以考虑统一的配置优先级文档
异步错误处理
- 部分 Promise 未处理 rejection
- 可以添加全局未捕获 Promise 处理器

💡 学习机会:

项目中有一些 TODO 和 FIXME 注释,这些是很好的学习和贡献起点:

# 查找学习机会
git grep -n "TODO\|FIXME" packages/

典型的包括:

性能优化点(如缓存改进)
错误处理增强
新功能占位符

第二部分:技能需求清单(你的学习弹药库)📚

好了,了解了项目的"骨架",现在让我们看看你需要装备哪些"武器"才能驾驭这个项目。别慌,我会按难度分级,并告诉你学到什么程度就够用 💪

1. 基础技能要求

必备技能(入场券 🎫)

技能	要求等级	具体要求	学习时长预估
JavaScript	⭐⭐⭐	ES2022+ 语法,Promise/async-await	如已熟悉:0 天从零开始:2-3 周
TypeScript	⭐⭐⭐⭐	接口、泛型、类型推导、联合类型	1-2 周(有 JS 基础)
Node.js	⭐⭐⭐	文件系统、进程管理、模块系统	1 周
React	⭐⭐⭐⭐	Hooks、Context、组件生命周期	2-3 周
终端基础	⭐⭐	ANSI 转义码、TTY、STDIN/STDOUT	3-5 天
Git	⭐⭐	基本操作、分支、PR 流程	3-5 天

版本要求(关键!) 🔍:

从 package.json 中我们知道:

Node.js: >=20.0.0 (必须!低版本会报错)
React: 19.1.0 (最新稳定版)
TypeScript: 5.3.3+

为什么需要 Node.js 20+?

使用了最新的 fetch API
依赖 ES Module 完整支持
需要 AbortSignal.timeout() 等新特性

框架和工具(核心武器 ⚔️)

1. Ink 框架 ⭐⭐⭐⭐

这是最独特的技能要求!Ink 是 React 在终端的实现。

// 一个简单的 Ink 组件
import React from 'react';
import { Box, Text } from 'ink';

function Hello({ name }: { name: string }) {
  return (
    <Box borderStyle="round" padding={1}>
      <Text color="green">Hello, {name}!</Text>
    </Box>
  );
}

学习资源:

官方文档: https://github.com/vadimdemedes/ink
项目内示例: packages/cli/src/ui/components/

2. Gemini API ⭐⭐⭐

你需要理解:

Function Calling(工具调用)机制
流式响应处理
Token 限制和缓存
System Instructions

官方文档: https://ai.google.dev/docs

3. Vitest 测试框架 ⭐⭐⭐

import {
    describe, it, expect, vi } from 'vitest';

describe('readFile', () => {
   
  it('should read file content', async () => {
   
    const content = await readFile('test.txt');
    expect(content).toBe('Hello World');
  });
});

4. esbuild ⭐⭐

用于打包,理解基本配置即可:

入口文件
输出目录
外部依赖

2. 进阶技能要求

架构模式(成为架构师 🏗️)

1. Monorepo 管理 ⭐⭐⭐⭐

这个项目使用 npm workspaces:

// package.json
{
   
  "workspaces": ["packages/*"]
}

你需要理解:

如何管理包之间的依赖(file: 协议)
如何运行特定 workspace 的脚本
如何处理版本号同步

命令示例:

# 为所有 workspace 安装依赖
npm install

# 仅在 cli package 中运行测试
npm test --workspace @google/gemini-cli

# 在所有 workspace 中运行构建
npm run build --workspaces

2. 前后端分离架构 ⭐⭐⭐⭐

理解 CLI 和 Core 的职责划分:

CLI: 展示层,只负责 UI 和用户交互
Core: 逻辑层,处理 API 调用和工具执行

3. 插件化设计 ⭐⭐⭐⭐⭐

工具系统是核心,理解:

工具接口定义(Tool 接口)
工具注册机制(ToolRegistry)
工具调用流程

领域特定知识(AI 开发者必备 🤖)

1. AI Agent 工具调用

理解 Function Calling 的工作原理:

// 工具定义
const tools = [{
   
  name: 'read_file',
  description: 'Read contents of a file',
  parameters: {
   
    type: 'object',
    properties: {
   
      path: {
    type: 'string' }
    }
  }
}];

// Gemini 返回的工具调用请求
{
   
  functionCall: {
   
    name: 'read_file',
    args: {
    path: 'src/index.ts' }
  }
}

2. MCP 协议 ⭐⭐⭐⭐

Model Context Protocol 是 Anthropic 提出的标准,用于 AI 模型与外部工具通信。

核心概念:

Resources: 提供上下文信息
Tools: 可执行的操作
Prompts: 预定义的提示词模板

文档: https://modelcontextprotocol.io/

3. OAuth 2.0 认证 ⭐⭐⭐

项目支持多种认证方式:

OAuth 登录(浏览器授权)
API Key
Service Account

理解 OAuth 流程:

授权请求 → 2. 用户授权 → 3. 获取 Token → 4. 刷新 Token

3. 技能掌握程度建议

根据你的目标,这里是不同角色的学习重点:

🎯 初学者(目标:能运行和使用)

必须掌握 ✅:

[ ] TypeScript 基础语法
[ ] Node.js 基本 API
[ ] 如何安装依赖和运行项目
[ ] 基本的 Git 操作

可以暂时跳过 ⏭️:

React/Ink 内部实现
测试编写
打包配置

学习时长: 1-2 周

🚀 有经验的开发者(目标:能修改和扩展)

必须掌握 ✅:

[ ] TypeScript 高级特性(泛型、条件类型)
[ ] React Hooks 熟练使用
[ ] Ink 框架基础
[ ] Gemini API 工具调用
[ ] Vitest 测试编写

深入理解 🔍:

工具系统架构
配置管理机制
会话状态管理

学习时长: 3-4 周

💎 意欲贡献代码的进阶者(目标:能设计新功能)

必须精通 🎯:

[ ] 整个项目架构
[ ] 所有核心模块的实现
[ ] 测试策略和最佳实践
[ ] CI/CD 流程
[ ] MCP 协议深度理解

能够独立完成 💪:

设计并实现新工具
重构核心模块
性能优化
编写技术文档

学习时长: 2-3 个月

第三部分:学习路径规划(你的专属教练计划)🎯

好了,理论知识装备完毕,现在让我们开始实战!我会带你一步步从"能跑起来"到"能贡献代码",每一步都有清晰的目标和验收标准 🎓

1. 项目运行入口定位(快速上手)

⏱️ 预计时间:15-30 分钟

让我们快速让项目跑起来!

📋 环境配置清单

Step 1: 检查 Node.js 版本 ✅

node --version
# 必须 >= v20.0.0

# 如果版本太低,使用 nvm 安装:
# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Windows
# 下载安装: https://nodejs.org/

Step 2: 克隆项目 📥

git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli

Step 3: 安装依赖 📦

# 安装所有 workspace 的依赖
npm install

# ⏳ 预计耗时:2-5 分钟(取决于网络)

⚠️ 常见陷阱 #1: 网络问题

如果下载很慢,配置国内镜像:

npm config set registry https://registry.npmmirror.com

Step 4: 构建项目 🔨

npm run build

# 这会:
# 1. 编译所有 TypeScript 文件
# 2. 打包成可执行文件
# 3. 复制资源文件

⚠️ 常见陷阱 #2: 内存不足

如果遇到 JavaScript heap out of memory:

# 临时增加内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Step 5: 配置认证 🔐

选择一种认证方式:

# 方式 1: 使用 API Key(推荐新手)
# 访问 https://aistudio.google.com/apikey 获取
export GEMINI_API_KEY="your-api-key-here"

# 方式 2: OAuth 登录(首次运行时会自动引导)
# 无需配置,直接运行即可

Step 6: 运行! 🚀

npm run start

# 或者使用打包后的命令
./bundle/gemini.js

🎉 验证成功标志

你应该看到类似这样的界面:

┌─────────────────────────────────────┐
│  ✨ Welcome to Gemini CLI v0.9.0   │
│  Type your message or /help         │
└─────────────────────────────────────┘

>

如果出现认证提示:

选择 "Login with Google"
浏览器会自动打开授权页面
授权后返回终端

测试一下 🧪:

> Hello, can you help me?

如果 Gemini 回复了,恭喜你,环境搭建成功! 🎊

🐛 常见问题排查

问题	原因	解决方案
`command not found: gemini`	未安装或路径问题	使用 `npm run start` 或 `./bundle/gemini.js`
`Cannot find module`	依赖未安装	运行 `npm install`
`401 Unauthorized`	认证失败	检查 API Key 或重新登录
`Rate limit exceeded`	请求过快	等待 1 分钟后重试
`Heap out of memory`	内存不足	增加 Node.js 内存限制

2. 循序渐进学习计划(四阶段法)

🌱 阶段一:环境搭建和项目启动(1-2 天)

目标: 成功运行项目并能打个断点 🎯

学习内容:

理解项目启动流程 (1 小时)

打开 packages/cli/src/gemini.tsx,找到这段代码:

// 主入口函数
export async function run(args: string[]) {
  // 1. 解析命令行参数
  const cliArgs = parseArguments(args);

  // 2. 加载配置
  const settings = await loadSettings();

  // 3. 初始化认证
  await validateAuthMethod(settings);

  // 4. 渲染 React 应用
  render(<AppContainer config={config} />);
}

练习: 在每一步后面加 console.log,观察执行顺序

学会调试 (30 分钟)

方法 1: 使用 VSCode 调试

创建 .vscode/launch.json:

{
     
  "version": "0.2.0",
  "configurations": [
    {
     
      "type": "node",
      "request": "launch",
      "name": "Debug Gemini CLI",
      "program": "${workspaceFolder}/packages/cli/dist/index.js",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

在 gemini.tsx 中打断点,按 F5 开始调试

方法 2: 使用 Chrome DevTools

npm run debug
# 打开 Chrome,访问 chrome://inspect

修改一个小功能 (1 小时)

任务: 修改欢迎消息

找到 packages/cli/src/ui/App.tsx,修改:

<Text color="cyan">
  ✨ Welcome to Gemini CLI - 你好,我是你的 AI 助手!
</Text>

重新构建并运行:

npm run build
npm run start

验收标准 ✅:

[ ] 能成功运行项目
[ ] 能设置断点并命中
[ ] 能修改代码并看到效果
[ ] 理解从入口到 UI 渲染的流程

如果遇到困难 🤔:

回顾"环境配置清单"
检查 Node.js 版本
查看 docs/troubleshooting.md

🌿 阶段二:核心流程理解(3-5 天)

目标: 追踪一个完整业务流程,画出自己的流程图 📊

学习内容:

追踪一次完整的 API 调用 (2-3 小时)

任务: 理解"用户输入 → AI 响应"的完整流程

关键文件阅读顺序:

1️⃣ packages/cli/src/ui/App.tsx
   ↓ (用户输入后调用 onSubmit)

2️⃣ packages/core/src/core/client.ts
   ↓ (sendMessage 方法)

3️⃣ packages/core/src/core/geminiChat.ts
   ↓ (构建 Prompt 并调用 API)

4️⃣ packages/core/src/core/turn.ts
   ↓ (处理 API 响应,管理轮次)

5️⃣ packages/core/src/core/coreToolScheduler.ts
   ↓ (如果需要调用工具)

6️⃣ packages/core/src/tools/read-file.ts
   ↓ (工具执行示例)

练习: 在每个关键方法入口打印日志,观察调用链

// 在各个文件中添加
console.log('[CLIENT] sendMessage called with:', message);
console.log('[CHAT] Sending to API:', prompt);
console.log('[TOOL] Executing:', toolName, args);

画出你自己的流程图 (1-2 小时)

使用你喜欢的工具(draw.io, Excalidraw, 甚至纸笔),画出:
- 用户输入如何传递到 Core
- Core 如何调用 Gemini API
- 工具调用的完整流程
- 结果如何返回给用户
参考: 本指南"第一部分 > 架构流程描述"中的序列图

深入理解工具系统 (2-3 小时)

阅读这些文件:

packages/core/src/tools/tools.ts - 工具接口定义
packages/core/src/tools/tool-registry.ts - 工具注册
packages/core/src/tools/read-file.ts - 具体工具实现

理解这些概念:

Tool 接口的结构
ToolRegistry 如何管理工具
工具的 execute 方法如何实现

练习: 创建一个超级简单的自定义工具

// packages/core/src/tools/hello-tool.ts
import type {
      Tool } from './tools.js';

export const helloTool: Tool = {
     
  name: 'say_hello',
  description: 'Say hello to someone',
  parameters: {
     
    type: 'object',
    properties: {
     
      name: {
      type: 'string' }
    }
  },
  execute: async ({
      name }) => {
     
    return `Hello, ${
       name}! 👋`;
  }
};

然后在 tool-registry.ts 中注册它(先不要急着让它工作,理解概念即可)

理解 React + Ink 的 UI 组件 (2-3 小时)

核心组件解析:

App.tsx (主容器)
├── InputArea.tsx (输入框)
├── MessageList.tsx (消息列表)
│   ├── UserMessage.tsx (用户消息)
│   └── AssistantMessage.tsx (AI 消息)
│       └── MarkdownRenderer.tsx (Markdown 渲染)
└── ToolConfirmation.tsx (工具确认对话框)

练习: 修改一个组件的样式

找到 packages/cli/src/ui/components/UserMessage.tsx,修改颜色或边框

<Box borderStyle="double" borderColor="cyan">
  <Text color="magenta">{message}</Text>
</Box>

验收标准 ✅:

[ ] 能完整追踪一次 API 调用的全流程
[ ] 能画出主要流程的流程图
[ ] 理解工具系统的工作原理
[ ] 能修改 UI 组件并看到效果

小贴士 💡:

不要试图一次性理解所有细节
专注于主流程,忽略异常处理
多用 console.log 追踪数据流

🌳 阶段三:模块深入和定制开发(1-2 周)

目标: 能修改或扩展一个现有功能 🛠️

学习内容:

实现一个完整的自定义工具 (3-5 天)

任务: 创建一个"获取天气"工具

Step 1: 定义工具接口

// packages/core/src/tools/weather-tool.ts
import type {
      Tool } from './tools.js';

interface WeatherParams {
     
  city: string;
}

export const weatherTool: Tool<WeatherParams> = {
     
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: {
     
    type: 'object',
    properties: {
     
      city: {
     
        type: 'string',
        description: 'City name, e.g., "Shanghai"'
      }
    },
    required: ['city']
  },
  execute: async ({
      city }) => {
     
    // 使用免费天气 API
    const response = await fetch(
      `https://wttr.in/${
       city}?format=j1`
    );
    const data = await response.json();

    return `Weather in ${
       city}:
      Temperature: ${
       data.current_condition[0].temp_C}°C
      Condition: ${
       data.current_condition[0].weatherDesc[0].value}`;
  }
};

Step 2: 注册工具

修改 packages/core/src/tools/tool-registry.ts:

import {
      weatherTool } from './weather-tool.js';

// 在 getDefaultTools() 中添加
export function getDefaultTools(): Tool[] {
     
  return [
    readFileTool,
    writeFileTool,
    // ... 其他工具
    weatherTool,  // 添加这里
  ];
}

Step 3: 编写测试

// packages/core/src/tools/weather-tool.test.ts
import {
      describe, it, expect, vi } from 'vitest';
import {
      weatherTool } from './weather-tool.js';

describe('weatherTool', () => {
     
  it('should fetch weather data', async () => {
     
    const result = await weatherTool.execute({
     
      city: 'Shanghai'
    });

    expect(result).toContain('Weather in Shanghai');
    expect(result).toContain('Temperature:');
  });
});

Step 4: 测试工具

# 重新构建
npm run build

# 启动 CLI
npm run start

# 在 CLI 中测试
> What's the weather in Shanghai?

如果成功,Gemini 会调用你的工具并返回天气信息! 🎉

扩展 CLI 命令 (2-3 天)

任务: 添加一个 /stats 命令显示使用统计

Step 1: 创建命令处理器

// packages/cli/src/ui/commands/stats.ts
import type {
      CommandHandler } from '../types.js';

export const statsCommand: CommandHandler = {
     
  name: 'stats',
  description: 'Show usage statistics',
  execute: async (context) => {
     
    const {
      sessionStats } = context;

    return `📊 Session Statistics:
      Messages sent: ${
       sessionStats.messageCount}
      Tokens used: ${
       sessionStats.tokenCount}
      Session duration: ${
       formatDuration(sessionStats.duration)}`;
  }
};

Step 2: 注册命令

在 packages/cli/src/services/BuiltinCommandLoader.ts 中添加

Step 3: 添加快捷键

修改 packages/cli/src/config/keyBindings.ts,绑定 Ctrl+S 触发统计

自定义主题 (1-2 天)

任务: 创建一个"赛博朋克"主题 🌃

// packages/cli/src/ui/themes/cyberpunk-theme.ts
import type {
      Theme } from './types.js';

export const cyberpunkTheme: Theme = {
     
  name: 'cyberpunk',
  colors: {
     
    primary: '#00ff9f',      // 霓虹绿
    secondary: '#ff006e',    // 霓虹粉
    background: '#0a0e27',   // 深蓝黑
    text: '#e0e0e0',
    success: '#00ff9f',
    warning: '#ffb700',
    error: '#ff006e',
  },
  syntax: {
     
    keyword: '#ff006e',
    string: '#00ff9f',
    number: '#ffb700',
    comment: '#6c6f85',
  }
};

在设置中启用:

// ~/.gemini/settings.json
{
     
  "theme": "cyberpunk"
}

验收标准 ✅:

[ ] 能独立实现一个完整的自定义工具
[ ] 工具能被 Gemini 正确调用
[ ] 能添加新的 CLI 命令
[ ] 能自定义主题

挑战任务 🚀:

实现一个连接数据库的工具
创建一个批量文件处理命令
设计一个高对比度无障碍主题

🌲 阶段四:架构理解和贡献指南(2 周+)

目标: 能理解技术选型原因,并尝试修复一个简单 issue 🏆

学习内容:

深入理解技术选型 (1 周)

问题驱动学习法,思考这些问题:
- 为什么选择 React + Ink 而不是传统 CLI 库?
  - 阅读 docs/architecture.md
  - 查看 Ink 的优势(组件化、可测试)
  - 对比 blessed 库的区别
- 为什么采用前后端分离架构?
  - CLI 和 Core 完全解耦
  - Core 可以被其他客户端复用(A2A Server, VSCode 扩展)
  - 便于独立测试和部署
- 为什么使用 OpenTelemetry?
  - 阅读 packages/core/src/telemetry/
  - 理解可观测性的重要性
  - 查看如何在 Google Cloud 查看遥测数据
- 工具系统为什么这样设计?
  - 统一的 Tool 接口
  - 动态注册机制
  - MCP 协议的扩展性

阅读源码的高级技巧 (2-3 天)

技巧 1: 从测试开始

测试是最好的文档!

# 找到你感兴趣的模块
cd packages/core/src/tools

# 先读测试文件
cat read-file.test.ts

# 测试会告诉你:
# - 函数的预期行为
# - 边界情况处理
# - 如何 mock 依赖

技巧 2: 使用 VS Code 的"转到定义"

按住 Cmd/Ctrl,点击函数名
快速跳转到实现
使用 Cmd/Ctrl + - 返回

技巧 3: 利用 TypeScript 类型系统

// 不确定参数类型?鼠标悬停查看
function sendMessage(message: string) {
      ... }
//                    ^^^^^^
//                    悬停这里看类型定义

技巧 4: 搜索使用示例

# 想知道某个函数怎么用?
git grep "readFile(" packages/

# 查看所有调用点

贡献代码流程 (1 周实践)

Step 1: 找到合适的 Issue

访问: https://github.com/google-gemini/gemini-cli/issues

筛选标签:

good first issue - 适合新手
help wanted - 需要帮助
bug - 修复 Bug
enhancement - 功能增强

推荐新手 Issue:

文档改进
错误信息优化
小的 UI 调整

Step 2: Fork 并创建分支

# Fork 项目到你的账号
# 然后克隆
git clone https://github.com/你的用户名/gemini-cli.git
cd gemini-cli

# 添加上游仓库
git remote add upstream https://github.com/google-gemini/gemini-cli.git

# 创建功能分支
git checkout -b fix-issue-123

Step 3: 进行修改

遵循 CONTRIBUTING.md 中的规范:

使用函数式编程而非类
避免使用 any 类型
编写测试
添加必要的注释

Step 4: 运行质量检查

# 运行所有检查(这是 CI 会运行的)
npm run preflight

# 这会依次执行:
# - npm run clean      (清理)
# - npm ci             (安装依赖)
# - npm run format     (格式化)
# - npm run lint:ci    (代码检查)
# - npm run build      (构建)
# - npm run typecheck  (类型检查)
# - npm run test:ci    (测试)

如果 preflight 失败:

仔细阅读错误信息
修复后重新运行
不要提交未通过检查的代码

Step 5: 提交代码

遵循 Conventional Commits 规范:

git add .

# 提交格式: <type>: <description>
git commit -m "fix: correct file path resolution on Windows"

# 类型包括:
# feat:     新功能
# fix:      修复 Bug
# docs:     文档修改
# style:    代码格式
# refactor: 重构
# test:     测试
# chore:    杂项

Step 6: 推送并创建 PR

git push origin fix-issue-123

在 GitHub 上创建 Pull Request:

清晰描述你的修改
关联相关 Issue(Fixes #123)
附上测试截图(如果是 UI 修改)
等待 Review

参与社区 (持续)

GitHub Discussions: 提问和分享经验
- https://github.com/google-gemini/gemini-cli/discussions
查看 Roadmap: 了解未来计划
- https://github.com/orgs/google-gemini/projects/11
关注 Release: 学习新功能
- https://github.com/google-gemini/gemini-cli/releases

验收标准 ✅:

[ ] 能解释主要技术选型的原因
[ ] 能高效阅读和理解源码
[ ] 成功提交至少一个 PR
[ ] 理解整个开发和发布流程

终极挑战 🏆:

设计并实现一个有价值的新功能
优化一个性能瓶颈
重构一个复杂模块
编写一篇技术博客分享你的学习

3. 学习路径流程图

graph TD
    Start([开始学习 Gemini CLI]) --> Phase1{阶段一<br/>环境搭建}

    Phase1 --> Check1{能运行项目?}
    Check1 -->|否| Debug1[查看 Troubleshooting<br/>检查 Node 版本]
    Debug1 --> Phase1
    Check1 -->|是| Phase2{阶段二<br/>核心流程理解}

    Phase2 --> Check2{理解主流程?}
    Check2 -->|否| Debug2[重读架构文档<br/>添加日志追踪]
    Debug2 --> Phase2
    Check2 -->|是| Phase3{阶段三<br/>模块深入}

    Phase3 --> Choose{选择方向}
    Choose -->|工具开发| Tool[实现自定义工具]
    Choose -->|UI 开发| UI[扩展 CLI 命令]
    Choose -->|主题设计| Theme[创建自定义主题]

    Tool --> Phase4
    UI --> Phase4
    Theme --> Phase4

    Phase4{阶段四<br/>贡献代码} --> Check4{PR 被合并?}
    Check4 -->|否| Debug4[根据 Review 修改<br/>完善测试]
    Debug4 --> Phase4
    Check4 -->|是| Success([🎉 恭喜!<br/>你已经掌握项目!])

    Success --> Advanced{继续深入?}
    Advanced -->|是| Expert[设计新功能<br/>性能优化<br/>架构重构]
    Advanced -->|否| Community[参与社区<br/>帮助新手]

    style Phase1 fill:#e1f5ff
    style Phase2 fill:#fff4e1
    style Phase3 fill:#e8f5e9
    style Phase4 fill:#fce4ec
    style Success fill:#c8e6c9
    style Expert fill:#ffecb3

第四部分:实践建议和进阶指导(从会用到精通)💡

现在你已经有了清晰的学习路径,让我分享一些"老司机"的经验技巧,帮你避开常见的坑,加速学习进程 🚗💨

1. 调试技巧和常见陷阱

🔍 调试技巧

技巧 1: 使用 Debug 模式

# 启用详细日志
DEBUG=* npm run start

# 只看特定模块的日志
DEBUG=gemini:core npm run start

技巧 2: React DevTools for Terminal

是的,你可以用 React DevTools 调试终端应用!

// packages/cli/src/gemini.tsx
// 取消注释这一行:
// await attachReactDevTools();

然后在 Chrome 中打开 chrome://inspect,就能看到组件树和状态!

技巧 3: Mock 外部依赖

测试时不想真的调用 API?

// packages/core/src/core/client.test.ts
vi.mock('@google/genai', () => ({
   
  GoogleGenerativeAI: vi.fn(() => ({
   
    getGenerativeModel: vi.fn(() => ({
   
      generateContent: vi.fn(() => Promise.resolve({
   
        response: {
    text: () => 'Mocked response' }
      }))
    }))
  }))
}));

技巧 4: 使用 Headless 模式测试

# 非交互式运行,方便调试
gemini -p "List files in current directory" --output-format json

输出 JSON,易于解析和验证。

⚠️ 常见陷阱(Top 5)

陷阱 1: 忘记重新构建

# 修改 TypeScript 代码后
npm run build  # 🔴 别忘了这一步!
npm run start

解决方案: 使用 watch 模式

# 在一个终端
npm run build -- --watch

# 在另一个终端
npm run start

陷阱 2: Node.js 版本不匹配

# 检查当前版本
node --version

# 如果不是 v20+,切换:
nvm use 20

陷阱 3: 工具权限被拒绝

Gemini CLI 有安全策略,某些工具需要确认:

// ~/.gemini/settings.json
{
   
  "trustedFolders": ["/path/to/your/project"],
  "autoApproveReadTools": true  // 自动批准读操作
}

陷阱 4: Token 缓存导致的困惑

Gemini API 支持 Token 缓存,有时会返回旧数据:

# 清除缓存重新开始
rm -rf ~/.gemini/cache

陷阱 5: Ink 组件渲染问题

终端 UI 有时会"花屏",原因通常是:

组件状态更新过快
异步操作未正确处理
终端不支持某些 ANSI 码

解决方案:

// 使用 useEffect 防抖
const [value, setValue] = useState('');

useEffect(() => {
   
  const timer = setTimeout(() => {
   
    // 延迟更新
    updateUI(value);
  }, 100);

  return () => clearTimeout(timer);
}, [value]);

2. 扩展练习建议

从易到难,循序渐进 📈

🟢 初级练习(1-2 天每个)

练习 1: 修改响应格式

任务: 让 AI 的回复带上时间戳

// packages/cli/src/ui/components/AssistantMessage.tsx
<Box>
  <Text dimColor>{
   new Date().toLocaleTimeString()}</Text>
  <Markdown>{
   message}</Markdown>
</Box>

练习 2: 添加一个"清屏"命令

任务: 实现 /clear 命令

// packages/cli/src/ui/commands/clear.ts
export const clearCommand: CommandHandler = {
   
  name: 'clear',
  description: 'Clear the screen',
  execute: async (context) => {
   
    // 发送清屏信号
    context.events.emit('clear-screen');
    return '';
  }
};

练习 3: 自定义错误消息

任务: 让错误消息更友好

// packages/core/src/utils/errors.ts
export function getErrorMessage(error: unknown): string {
   
  if (error instanceof QuotaExceededError) {
   
    return '😅 哎呀,API 配额用完了!请稍后再试~';
  }
  // ...
}

🟡 中级练习(3-5 天每个)

练习 1: 实现文件搜索工具

任务: 添加 search_files 工具,支持正则表达式搜索

提示:

使用 ripgrep 库(项目已依赖)
参考 packages/core/src/tools/grep.ts
添加参数:pattern, path, fileType

练习 2: 添加会话导出功能

任务: 实现 /export 命令,导出对话历史为 Markdown

// 输出格式
// # Gemini CLI Session Export
// 
// ## Session Info
// - Date: 2025-01-06
// - Messages: 15
// 
// ## Conversation
// 
// ### User
// Hello!
// 
// ### Assistant
// Hi there! How can I help?

练习 3: 实现 Token 使用统计

任务: 在状态栏显示本次会话的 Token 使用情况

┌────────────────────────────────────┐
│ Session: 1,234 / 1,000,000 tokens │
└────────────────────────────────────┘

🔴 高级练习(1-2 周每个)

练习 1: 实现代码 Diff 可视化

任务: 当 AI 修改代码时,显示美观的 Diff

提示:

使用 diff 库
用颜色区分增删改
参考 GitHub 的 Diff 样式

练习 2: 添加插件系统

任务: 允许用户通过 npm 包扩展工具

设计要点:

定义插件接口
插件加载机制
配置文件声明插件
沙箱执行插件代码

练习 3: 实现多模态输入

任务: 支持拖拽图片到终端,自动上传并分析

技术栈:

监听终端的 paste 事件
检测图片数据
使用 Gemini Vision 分析
显示图片缩略图(ASCII art)

3. 参与贡献的途径

🚀 从这里开始

1. 文档贡献(最简单,高价值)

# 发现文档错误?
cd docs/
# 修改 Markdown 文件
git commit -m "docs: fix typo in architecture.md"

好处:

不需要深入理解代码
帮助其他学习者
快速获得第一个 PR

2. 修复小 Bug(入门级)

如何找 Bug:

使用项目时记录问题
查看 Issues 中的 bug 标签
关注错误处理不完善的地方

修复流程:

复现 Bug
编写失败的测试
修复代码使测试通过
提交 PR

3. 功能增强(进阶)

Ideas 来源:

查看 Roadmap
Issues 中的 enhancement 标签
你自己的需求

提议流程:

在 Discussions 中讨论你的想法
等待维护者反馈
获得批准后开始开发
小步提交,及时沟通

4. 性能优化(高级)

关注点:

冷启动时间
大文件处理
内存使用
API 调用优化

工具:

# 性能分析
node --prof packages/cli/dist/index.js
node --prof-process isolate-*.log > profile.txt

# 内存分析
node --inspect packages/cli/dist/index.js
# 在 Chrome DevTools 中查看内存快照

📋 贡献 Checklist

在提交 PR 之前,确保:

[ ] ✅ 代码遵循 CONTRIBUTING.md 规范
[ ] ✅ 所有测试通过(npm run test)
[ ] ✅ 类型检查通过(npm run typecheck)
[ ] ✅ Lint 检查通过(npm run lint)
[ ] ✅ 格式化代码(npm run format)
[ ] ✅ 编写了测试(如果是新功能或 Bug 修复)
[ ] ✅ 更新了相关文档
[ ] ✅ Commit 消息遵循 Conventional Commits
[ ] ✅ PR 描述清晰,关联了相关 Issue

完整检查命令:

npm run preflight

如果这个命令通过,你的 PR 就有很大概率被接受! 🎉

🤝 与维护者沟通

礼貌而清晰的沟通方式:

Hi @maintainer,

I noticed that [describe the problem/opportunity].

I'd like to propose [your solution], because [reasoning].

Here's a proof of concept: [link to branch/code]

What do you think? Would you like me to:
- Open a PR?
- Explore a different approach?
- Write a design doc first?

Thanks for your time! 😊

注意事项:

❌ 不要: "为什么不直接这样做?"(质疑)
✅ 应该: "我考虑了这种方案,您觉得如何?"(建议)
❌ 不要: "这个 Bug 太低级了"(批评)
✅ 应该: "发现一个可以改进的地方"(中性)

第五部分:技术栈学习指引(你的知识地图)🌐

好了,前面我们已经深入项目本身,现在让我们跳出来,看看如何系统学习项目所依赖的各项技术 📖

1. 官方文档定位(学习的基石)

🎯 核心技术栈文档

技术	官方文档	必读章节	预计学习时长
TypeScript	typescriptlang.org	• Handbook • Everyday Types • Generics	1-2 周
React	react.dev	• Learn React • Hooks • Context	2-3 周
Ink	github.com/vadimdemedes/ink	• Getting Started • Components • Hooks	3-5 天
Node.js	nodejs.org/docs	• File System • Child Process • Streams	1 周
Gemini API	ai.google.dev	• Function Calling • Caching • Safety Settings	1 周
Vitest	vitest.dev	• Getting Started • API • Mocking	3-5 天
MCP	modelcontextprotocol.io	• Introduction • Building Servers	5-7 天

📚 项目自身文档

必读文档(按优先级):

README.md - 项目概览和快速开始 ⭐⭐⭐⭐⭐
docs/architecture.md - 架构设计 ⭐⭐⭐⭐⭐
CONTRIBUTING.md - 贡献指南 ⭐⭐⭐⭐⭐
docs/get-started/index.md - 入门教程 ⭐⭐⭐⭐
docs/cli/commands.md - 命令参考 ⭐⭐⭐⭐
docs/tools/index.md - 工具系统 ⭐⭐⭐⭐
docs/cli/configuration.md - 配置指南 ⭐⭐⭐
docs/troubleshooting.md - 问题排查 ⭐⭐⭐

深入主题:

扩展开发: docs/extensions/index.md
MCP 集成: docs/tools/mcp-server.md
企业部署: docs/cli/enterprise.md
IDE 集成: docs/ide-integration/index.md

📖 权威技术书籍

TypeScript:

📕 《Programming TypeScript》 by Boris Cherny
- 适合阶段: 初学者
- 特点: 循序渐进,实战导向

React:

📗 《React 设计原理》 by 卡颂
- 适合阶段: 有基础后深入
- 特点: 深入源码,理解原理

Node.js:

📘 《Node.js 设计模式》 by Mario Casciaro
- 适合阶段: 进阶开发者
- 特点: 设计模式,最佳实践

AI 应用开发:

📙 《Building LLM Apps》 by Valentina Alto
- 适合阶段: AI 功能开发
- 特点: 实战案例,工具链

2. 学习路径建议(社区智慧)

🗺️ 技能学习顺序

阶段 1: 基础夯实(2-4 周)

JavaScript ES6+ → TypeScript 基础 → Node.js 基础
              ↓
         React 基础 → Hooks
              ↓
         Ink 入门

学习重点:

JavaScript: Promise, async/await, 模块系统
TypeScript: 类型注解, 接口, 泛型
React: useState, useEffect, useContext
Ink: Box, Text, 布局系统

阶段 2: 框架深入(2-3 周)

React 高级 → 自定义 Hooks → Context 模式
       ↓
  Vitest 测试 → Mock 技巧
       ↓
  Gemini API → Function Calling

学习重点:

React: 性能优化, 组件设计模式
测试: 单元测试, 集成测试, TDD
Gemini API: 工具定义, 响应处理, 错误处理

阶段 3: 架构理解(3-4 周)

Monorepo 管理 → 前后端分离 → 插件系统
         ↓
   OpenTelemetry → 可观测性
         ↓
   MCP 协议 → 工具扩展

学习重点:

架构: 模块划分, 依赖管理, 接口设计
可观测性: 日志, 指标, 链路追踪
MCP: 协议规范, 服务端开发, 客户端集成

💡 核心概念优先级

必须精通 🔴:

TypeScript 类型系统
React Hooks(useState, useEffect, useCallback)
异步编程(Promise, async/await)
Gemini API Function Calling

应该理解 🟡:

Ink 组件系统
Vitest 测试框架
Node.js 文件系统和进程
OAuth 2.0 认证流程

可以了解 🟢:

OpenTelemetry 原理
esbuild 配置
Docker 容器化
CI/CD 流程

🎓 实践项目推荐

类似开源项目(代码参考):

Aider - AI 编程助手(Python)
- https://github.com/paul-gauthier/aider
- 学习点: 工具调用, 文件编辑
Continue - IDE AI 助手(TypeScript)
- https://github.com/continuedev/continue
- 学习点: IDE 集成, 上下文管理
Open Interpreter - 代码解释器(Python)
- https://github.com/KillianLucas/open-interpreter
- 学习点: 安全执行, 沙箱机制
Ink Examples - Ink 官方示例
- https://github.com/vadimdemedes/ink/tree/master/examples
- 学习点: 终端 UI 最佳实践

3. 工具与环境配置指南

🛠️ 开发环境搭建

推荐 IDE: Visual Studio Code

必装扩展:

{
   
  "recommendations": [
    "dbaeumer.vscode-eslint",           // ESLint
    "esbenp.prettier-vscode",           // Prettier
    "ms-vscode.vscode-typescript-next", // TypeScript
    "vitest.explorer",                  // Vitest
    "eamodio.gitlens",                  // Git
    "github.copilot"                    // GitHub Copilot(可选)
  ]
}

工作区设置:

// .vscode/settings.json
{
   
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
   
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "vitest.enable": true
}

🔧 常用工具使用

Git 基础(如果你还不熟悉)

# 克隆项目
git clone https://github.com/google-gemini/gemini-cli.git

# 创建分支
git checkout -b feature/my-feature

# 提交代码
git add .
git commit -m "feat: add new feature"

# 推送分支
git push origin feature/my-feature

# 同步上游更新
git fetch upstream
git rebase upstream/main

Docker 使用(用于沙箱测试)

# 构建沙箱镜像
npm run build:sandbox

# 运行集成测试
npm run test:integration:sandbox:docker

npm workspaces 技巧

# 查看所有 workspace
npm ls --workspaces

# 在特定 workspace 运行命令
npm run test --workspace @google/gemini-cli-core

# 为所有 workspace 安装依赖
npm install --workspaces

# 为特定 workspace 添加依赖
npm install lodash --workspace @google/gemini-cli-core

🧪 调试工具配置

Chrome DevTools(Node.js 调试)

# 启动调试
node --inspect-brk packages/cli/dist/index.js

# 打开 Chrome
chrome://inspect

# 点击 "Open dedicated DevTools for Node"

React DevTools(Ink 组件调试)

在代码中启用:

// packages/cli/src/gemini.tsx
import {
    attachReactDevTools } from 'react-devtools-core';

async function run() {
   
  // 启用 React DevTools
  await attachReactDevTools({
    port: 8097 });
  // ...
}

然后在 Chrome 中安装 React DevTools 扩展,连接到 localhost:8097。

4. 进阶拓展方向

👨‍💻 技术博客与专家

推荐关注:

Google AI Blog - Gemini 最新动态
- https://blog.google/technology/ai/
React Team Blog - React 官方博客
- https://react.dev/blog
Kent C. Dodds - React 和测试专家
- https://kentcdodds.com/blog
Dan Abramov - React 核心开发者
- https://overreacted.io/
TypeScript Blog - TS 新特性
- https://devblogs.microsoft.com/typescript/

GitHub 账号关注(查看他们的项目和讨论):

@vadimdemedes - Ink 作者
@sindresorhus - CLI 工具大师
@kentcdodds - React 测试

🎤 相关技术大会

必看演讲主题:

Google I/O - Gemini 和 AI 最新进展
- 往届回放: https://io.google/
React Conf - React 生态
- https://conf.react.dev/
JSConf - JavaScript 前沿技术
- https://jsconf.com/
Node.js Interactive - Node.js 深度话题
- https://events.linuxfoundation.org/nodejs-interactive/

🌐 社区与论坛

平台	链接	适用场景
GitHub Discussions	链接	提问、功能讨论
Stack Overflow	[typescript] [react] 标签	技术问题
Reddit	r/typescript, r/reactjs	社区动态
Discord	React 官方服务器	实时讨论
Twitter/X	关注 #GeminiAPI, #TypeScript	行业动态

中文社区:

掘金 - TypeScript/React 优质文章
V2EX - 技术讨论
思否(SegmentFault) - 问答社区

📚 持续学习资源

在线课程(英文):

Frontend Masters - React/TypeScript 进阶
Egghead.io - React 短视频教程
Udemy - Node.js 全栈开发

中文课程:

极客时间 - TypeScript 实战
慕课网 - React 全家桶
B站 - 免费教程搜索"React Hooks"

Newsletter 订阅:

TypeScript Weekly - TS 周刊
React Status - React 生态周报
Node Weekly - Node.js 新闻

🎓 写在最后:你的学习之旅刚刚开始

恭喜你读到这里! 🎉 如果你完整地读完了这份指南,我相信你已经对 Gemini CLI 有了全面而深入的理解。

但是,请记住:阅读只是开始,实践才是王道。不要试图一次性理解所有细节,而是要:

从小处着手 - 先让项目跑起来,再逐步深入
动手实践 - 每学一个概念,就写代码验证
保持好奇 - 遇到不懂的地方,大胆地去探索
参与社区 - 分享你的学习心得,帮助其他人
享受过程 - 学习本身就应该是一件有趣的事!

最后的最后 💬:

如果这份指南对你有帮助,请:

⭐ Star 这个项目
📢 分享给更多学习者
💬 在 Discussions 中分享你的学习心得
🐛 发现指南中的错误?欢迎提 Issue 或 PR!

记住,每一位 Gemini CLI 的贡献者都是从新手开始的。你并不孤单,整个社区都会支持你! 🤝

祝你学习愉快,早日成为项目的核心贡献者! 🚀

"The best way to learn is to teach."
学习的最好方式就是教导他人。

当你掌握了这个项目,别忘了回来帮助下一个新手! 😊

Gemini CLI 架构学习指南

Gemini CLI 架构学习指南

第一部分:项目架构深度解析(像架构师一样俯瞰全景)🔍

1. 项目架构概览

用一个类比来理解

核心设计特征

技术栈分析

外部系统集成

架构流程描述

2. 目录结构与核心流程

目录组织逻辑

关键文件定位

模块依赖关系

典型业务流程:文件重构场景

3. 代码结构观察

代码组织模式

设计模式识别

代码质量观察

第二部分:技能需求清单(你的学习弹药库)📚

1. 基础技能要求

必备技能(入场券 🎫)

框架和工具(核心武器 ⚔️)

2. 进阶技能要求

架构模式(成为架构师 🏗️)

领域特定知识(AI 开发者必备 🤖)

3. 技能掌握程度建议

🎯 初学者(目标:能运行和使用)

🚀 有经验的开发者(目标:能修改和扩展)

💎 意欲贡献代码的进阶者(目标:能设计新功能)

第三部分:学习路径规划(你的专属教练计划)🎯

1. 项目运行入口定位(快速上手)

⏱️ 预计时间:15-30 分钟

📋 环境配置清单

🎉 验证成功标志

🐛 常见问题排查

2. 循序渐进学习计划(四阶段法)

🌱 阶段一:环境搭建和项目启动(1-2 天)

🌿 阶段二:核心流程理解(3-5 天)

🌳 阶段三:模块深入和定制开发(1-2 周)

🌲 阶段四:架构理解和贡献指南(2 周+)

3. 学习路径流程图

第四部分:实践建议和进阶指导(从会用到精通)💡

1. 调试技巧和常见陷阱

🔍 调试技巧

⚠️ 常见陷阱(Top 5)

2. 扩展练习建议

🟢 初级练习(1-2 天每个)

🟡 中级练习(3-5 天每个)

🔴 高级练习(1-2 周每个)

3. 参与贡献的途径

🚀 从这里开始

📋 贡献 Checklist

🤝 与维护者沟通

第五部分:技术栈学习指引(你的知识地图)🌐

1. 官方文档定位(学习的基石)

🎯 核心技术栈文档

📚 项目自身文档

📖 权威技术书籍

2. 学习路径建议(社区智慧)

🗺️ 技能学习顺序

💡 核心概念优先级

🎓 实践项目推荐

3. 工具与环境配置指南

🛠️ 开发环境搭建

🔧 常用工具使用

🧪 调试工具配置

4. 进阶拓展方向

👨‍💻 技术博客与专家

🎤 相关技术大会

🌐 社区与论坛

📚 持续学习资源

🎓 写在最后:你的学习之旅刚刚开始

通义大模型

热门文章

最新文章

相关电子书