架构与包结构
区分终端界面、核心代理循环和 npm 发布包，理解上下文、工具与回退服务。
This page has not been translated into English yet. The original Chinese version is shown below.
官方仓库主要将用户界面与核心能力分为 packages/cli 和 packages/core。理解这个边界有助于定位问题：终端输入显示与 API/工具调度不是同一层。
包职责与发布形式
| 包 | 主要职责 | 发布形式与核对依据 |
|---|---|---|
@google/gemini-cli | 用户界面、命令解析及用户可见功能 | 发布页与固定提交配置为 dist/index.js 入口及独立依赖；GitHub 另有 bundle |
@google/gemini-cli-core | API 请求、认证、缓存及核心执行逻辑 | 普通 Node.js 包，保留自身依赖和 dist 中的转译代码，可供其他项目使用 |
官方 Package overview 将 npm CLI 描述为单文件 bundle，但发布页明确区分 npm 普通包与 GitHub bundle。核对固定提交的 packages/cli/package.json，其 bin/main 为 dist/index.js、files 为 dist，并列有 core 和其他依赖，支持发布页描述。本页据此区分两种产物；具体发布版本仍以实际包内容为准，也不能由打包形式推断离线能力。
一轮任务中的核心工作
core 根据会话历史、工具定义与 GEMINI.md 等上下文构造请求，向 Gemini API 发出调用，并解析模型提出的工具调用。工具注册与执行机制取得结果后，再把结果交回模型，继续处理任务。
core 同时管理会话状态、模型选择和工具设置。文件发现服务为 @ 引用及相关工具寻找文件；记忆发现服务负责分层加载 GEMINI.md。具体目录与按需加载规则以上下文说明为准。
压缩与可用性回退
长对话可能触发自动历史压缩，用户也可通过 /compress 将当前上下文替换成摘要。core 概览将压缩描述为尽量保留传达的信息；不能因此保证摘要不会遗漏任何细节。需要保存完整会话时，使用会话管理的相应功能。
core 概览还把主模型回退简述为 Pro 限流后切到 Flash。更具体的路由参考说明，是否询问、是否静默及持续范围取决于失败类型和策略；实际流程见路由与回退。
npm Workspaces
仓库根 package.json 用 packages/* 定义 workspaces。在源码根运行 npm install 会安装各工作区依赖并链接内部包；不必把每个包当成完全独立仓库分别安装。
可以从根目录指定工作区脚本，例如：
npm run build --workspace @google/gemini-cli构建整个源码与调试入口见本地开发。
输出引用
core 文档说明引用默认显示，可由 ui.showCitations 控制。编辑建议的引用会在接受选项之前展示，模型轮次结束时也会显示，重复项会去重并按字母顺序排列。引用展示是输出信息，不代替对模型结论和文件修改的验证。