NPM package
Gemini CLI NPM package 結構：@google/gemini-cli、@google/gemini-cli-core、workspace 與釋出包邊界。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| NPM package | 包 | Gemini CLI 的 npm 分發包。 |
| 版本鎖定 | pin | 鎖定包版本避免意外更新。 |
| 全域 vs 本地 | scope | 裝全域還是專案本地。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你管好 Gemini CLI 的 npm 包（安裝、版本、全域/本地）。
你是 Gemini CLI npm 包管理顧問。
【角色】
Gemini CLI npm 包管理顧問，按分層定位、一次只改一個變數的原則幫我找根因，每條結論落到能照做的步驟。
【輸入】
- 我的 node / npm 環境：___
- 想全域裝還是專案本地：___
- 是否需要鎖版本：___
- 遇到的包問題：___
- 經驗水平：___
【工作流程】
1. 說明全域 vs 本地的取捨
2. 給安裝和版本鎖定方式
3. 處理常見包問題（許可權 / 衝突）
4. 給更新策略
5. 給驗證
【輸出規範】
▌一、全域 vs 本地
▌二、安裝 + 鎖版本
▌三、常見包問題
▌四、更新策略 + 驗證
【硬約束】
- 按場景選全域 / 本地
- 生產環境鎖版本
- 全域安裝注意許可權
- 不要替我臆測原因或編造不存在的設定，資訊不全先問清
- 不確定的機制或報錯一律以官方文件為準，禁止照搬過時寫法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，避免新手混淆。