Appearance
Gemini CLI 的核心包（packages/core）负责与 Gemini API 通信、管理工具调用、维护会话状态。当对话接近 token 上限时，核心会自动压缩历史记录；Pro 模型限流时自动 fallback 到 Flash 模型。理解这些机制有助于你更好地预判 CLI 的行为。
Gemini CLI 核心架构
Gemini CLI 由两个主要包组成：packages/cli 提供用户界面，packages/core 是后端核心，负责与 Gemini API 通信、管理工具执行以及处理来自 CLI 层的请求。
本页说明核心包的主要职责和内部机制。
核心职责
packages/core 负责以下工作：
- Gemini API 通信：安全地向 Google Gemini API 发送用户 Prompt，并接收模型响应。
- Prompt 构建：组装发给模型的完整 Prompt，包含对话历史、工具定义和来自
GEMINI.md文件的上下文。 - 工具管理与编排：
- 注册所有可用工具（文件系统工具、Shell 命令执行等）
- 解析模型的工具调用请求
- 执行工具并将结果返回给模型继续处理
- 会话与状态管理：维护对话状态，包括历史记录和上下文信息。
- 配置管理：处理 API Key 访问、模型选择、工具设置等核心配置。
安全机制
核心包在安全方面扮演重要角色：
- API Key 管理：安全处理
GEMINI_API_KEY，确保与 API 通信时的安全性。 - 工具执行安全：涉及本地系统操作的工具（如
run_shell_command）会通过沙箱机制隔离执行，防止意外修改。详见 沙箱安全隔离。
对话历史压缩
为防止长对话超出模型的 token 上限，核心包内置了对话历史压缩功能。
当对话接近配置模型的 token 上限时，核心会在发送请求前自动压缩历史记录。压缩过程在信息层面是无损的——保留所有关键信息，但减少 token 占用。
各模型的 token 上限参见 Google AI 文档。
模型 Fallback 机制
Gemini CLI 内置了模型 fallback 机制，确保在默认 Pro 模型被限流时仍可继续使用。
- 使用 Pro 模型时，若检测到限流，当前会话自动切换到 Flash 模型，无需中断工作。
- 内部工具调用（如 Prompt 补全和分类）使用
gemini-2.5-flash-lite；当该模型配额耗尽时，会静默 fallback 到gemini-2.5-flash再到gemini-2.5-pro，不影响你配置的主模型。
完整的模型路由配置见 模型路由与故障转移。
文件发现服务
文件发现服务负责在项目中找到与当前上下文相关的文件。@ 命令和其他需要访问文件的工具都依赖此服务。
GEMINI.md 记忆发现服务
记忆发现服务负责查找并加载为模型提供上下文的 GEMINI.md 文件。搜索采用分层策略，从当前工作目录开始，逐级向上直到项目根目录和用户主目录，同时也搜索子目录。
这意味着你可以同时维护全局、项目级和组件级的上下文文件，核心包会将它们合并，为模型提供最相关的信息。
使用 /memory 命令 可以 show（查看）、add（添加）、refresh（刷新）已加载的 GEMINI.md 内容。
详细用法见 GEMINI.md 上下文文件 和 自动记忆（Auto Memory）。
引用（Citations）系统
当 Gemini 在回答中引用了某个来源的文本时，会自动将引用附加到输出末尾。此功能默认开启，可通过 ui.showCitations 设置关闭。
- 建议文件修改时，引用显示在确认提示之前。
- 引用始终显示在模型回复的末尾。
- 重复引用会自动去重，并按字母顺序排列。
常见问题
Q: 对话历史被压缩后，我之前提到的上下文会丢失吗？
A: 设计上是无损压缩，核心信息不会丢失。但如果某些细节（如很早之前提到的变量名）在后续对话中没有被再次引用，压缩后可能不再出现在模型的上下文中。建议在长会话中适当重申重要约束。
Q: 模型 fallback 到 Flash 时，输出质量会明显下降吗？
A: Flash 模型速度更快但推理深度略低于 Pro。对于简单任务，Flash 足以胜任；对于复杂代码重构或多步推理任务，可以等 Pro 模型配额恢复后重试，或升级配额计划。
Q: 如何查看 CLI 当前加载了哪些 GEMINI.md 文件？
A: 在 CLI 内运行 /memory show，会列出当前会话加载的所有 GEMINI.md 文件路径及内容摘要。