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，避免新手混淆。