NPM package
Gemini CLI NPM package 结构：@google/gemini-cli、@google/gemini-cli-core、workspace 与发布包边界。
Gemini CLI 仓库是 monorepo。普通用户只需要知道怎么安装；贡献者和排障者需要知道包边界。
普通用户安装的是 CLI 入口，不需要直接依赖 core。只有源码贡献、stack trace 排查或 package 发布验证时，才需要理解 workspace。
两个核心包
@google/gemini-cli 是用户入口，负责终端 UI、命令解析和可执行文件；@google/gemini-cli-core 负责 Gemini API 请求、认证、本地缓存和核心逻辑。
| 包 | 职责 | 面向谁 |
|---|---|---|
@google/gemini-cli | 终端 UI、命令解析、可执行入口、用户侧功能 | 普通用户、教程读者、CI |
@google/gemini-cli-core | API 请求、认证、本地缓存、核心逻辑 | 官方开发者、排障者、需要复用 core 的开发者 |
用户安装的是谁
普通用户常见方式是 npm install -g @google/gemini-cli 或 npx @google/gemini-cli。
使用的是 @google/gemini-cli 这个自包含可执行入口。
为什么要懂 core
当你遇到认证、缓存、API 请求、模型调用、token 统计这类问题时，很多逻辑其实在 @google/gemini-cli-core。
@google/gemini-cli-core 不是普通用户日常启动入口。它更像可复用核心库，包含与 Gemini API 交互、认证、本地缓存等逻辑。排查 issue 时，看到 stack trace 进入 core，不代表安装了两个 CLI。
flowchart LR
User["user runs gemini"] --> Cli["@google/gemini-cli"]
Cli --> Bundle["bundled executable"]
Bundle --> Core["@google/gemini-cli-core"]
Core --> API["Gemini API / auth / cache"]
Dev["source developer"] --> Workspace["NPM workspaces"]
Workspace --> Cli
Workspace --> Core
style Cli fill:#dbeafe,stroke:#3b82f6
style Core fill:#dcfce7,stroke:#22c55e
style Workspace fill:#fef3c7,stroke:#f59e0bWorkspace 结构
官方仓库使用 NPM Workspaces：
根 package.json 中的 workspaces 指向 packages/*。
本地开发时，在根目录安装依赖即可让 workspace 内包互相链接。
示例：
{
"workspaces": ["packages/*"]
}在 monorepo 根目录执行 npm install 会安装所有 workspace 依赖并自动链接内部包。要只跑某个包的脚本，可以用 NPM workspace 参数，例如 npm run build --workspace @google/gemini-cli。
读 stack trace
| trace 落点 | 可能含义 | 下一步 |
|---|---|---|
packages/cli | 终端 UI、命令解析、参数、交互流程 | 查 CLI command、flags、TUI 状态 |
packages/core | 认证、API、cache、tool scheduler | 查认证方式、模型调用、缓存和工具执行 |
node_modules | 依赖或环境问题 | 查 lockfile、Node 版本、包管理器 |
bundle / executable | 发布包或 npx 入口问题 | 查 release notes、npm tag、安装来源 |
排错判断
gemini命令找不到：查全局 npm bin、PATH、Homebrew/MacPorts 安装路径。npx总是跑旧版本：清_npxcache。- 源码开发改动没生效：确认 workspace link 和 build 产物。
- API、认证、cache 行为异常：优先看 core 相关 issue 和 logs。
- 用户侧教程失败：先复现全局安装或
npx，不要直接从源码构建。
回到教程
官方教程中文版到这里结束。下一步建议读“从原理到实战”，把这些官方能力串成真实项目工作流。
写教程时的边界：
- 安装页只讲普通用户入口，避免把 monorepo build 放进新手流程。
- 本地开发页讲 workspace、preflight、telemetry 和贡献流程。
- 故障排查页只在需要判断源码问题时引入 package 边界。
- 自动化页默认调用发布后的 CLI，而不是依赖本地源码路径。
验收方式
普通用户用 gemini --version 验证入口；源码贡献者用根目录 build/test/preflight 验证 workspace。写教程时，安装页只讲 @google/gemini-cli，源码排障页再解释 core 和 workspace，避免新手混淆。