项目结构
概览
gemini-cli 是一个 TypeScript monorepo 项目，使用 npm workspaces 管理多个包。
gemini-cli/
├── packages/ # 核心代码
│ ├── cli/ # CLI 界面
│ └── core/ # Agent 核心逻辑
├── docs/ # 用户文档
├── integration-tests/ # 集成测试
├── scripts/ # 构建脚本
└── bundle/ # 构建产物核心包
packages/cli
CLI 界面层，负责：
- 终端 UI 渲染（使用 Ink）
- 用户输入处理
- 命令系统（/help, /chat 等）
- 配置和认证管理
packages/cli/
├── src/
│ ├── gemini.tsx # 主入口
│ ├── AppContainer.tsx # 应用容器
│ ├── commands/ # 命令实现
│ ├── ui/ # UI 组件
│ ├── config/ # 配置管理
│ └── services/ # CLI 服务
└── package.jsonpackages/core
Agent 核心，负责：
- LLM API 交互
- 工具系统
- Agent 循环
- 状态管理
packages/core/
├── src/
│ ├── core/ # 核心类
│ │ ├── client.ts # GeminiClient - Agent 主循环
│ │ ├── geminiChat.ts # GeminiChat - API 交互
│ │ ├── turn.ts # Turn/Event 类型
│ │ └── prompts.ts # System Prompt
│ ├── tools/ # 工具实现
│ ├── services/ # 服务层
│ ├── agents/ # Agent 系统
│ └── utils/ # 工具函数
└── package.json数据流
关键文件
Agent 核心
| 文件 | 职责 | 难度 |
|---|---|---|
core/client.ts | Agent 主循环 | ⭐⭐⭐ |
core/geminiChat.ts | API 交互 | ⭐⭐ |
core/turn.ts | 事件类型定义 | ⭐ |
core/prompts.ts | System Prompt | ⭐⭐ |
工具系统
| 文件 | 职责 | 难度 |
|---|---|---|
tools/tool.ts | 工具接口 | ⭐ |
tools/read-file.ts | 读文件工具 | ⭐ |
tools/edit.ts | 编辑文件工具 | ⭐⭐ |
tools/shell.ts | Shell 工具 | ⭐⭐ |
服务层
| 文件 | 职责 | 难度 |
|---|---|---|
services/loopDetection.ts | 循环检测 | ⭐⭐ |
services/chatCompression.ts | 对话压缩 | ⭐⭐⭐ |
services/chatRecording.ts | 会话记录 | ⭐⭐ |
推荐阅读顺序
入门路线（理解 Agent 基本原理）
1. core/turn.ts - 理解事件类型
2. tools/tool.ts - 理解工具接口
3. tools/read-file.ts - 看一个简单工具的实现
4. core/geminiChat.ts - 理解 API 交互
5. core/client.ts - 理解 Agent 循环进阶路线（深入理解）
1. core/prompts.ts - System Prompt 设计
2. services/loopDetection.ts - 循环检测实现
3. services/chatCompression.ts - 对话压缩策略
4. tools/edit.ts - 复杂工具实现
5. agents/ - 多 Agent 系统依赖关系
核心依赖：
@google/generative-ai- Gemini API SDKink- 终端 React 渲染yargs- CLI 参数解析zod- 类型验证
构建产物
构建后生成单个可执行文件：
bundle/gemini.js # 包含所有依赖的单文件使用 esbuild 打包，配置在 esbuild.config.js。
小结
- Monorepo 结构：cli（UI）+ core（逻辑）
- Core 包是学习重点
- 推荐从 turn.ts → tool.ts → client.ts 顺序阅读
下一步
了解了项目结构，接下来深入 Core 包的实现：Core 包解析 →