本地開發
Gemini CLI 本地開發入口：原始碼安裝、monorepo package、NPM workspace、build/test 與釋出相關概念。
如果你要貢獻 Gemini CLI 或排查 CLI 自身問題，需要理解它的 monorepo 結構，而不是隻會 npm install -g。
本地開發不是普通使用者的安裝方式。教程正文應把“使用 Gemini CLI”和“開發 Gemini CLI 原始碼”分開，避免讀者把原始碼構建當成日常排錯步驟。
適用人群
| 你是誰 | 推薦路徑 | 不建議做什麼 |
|---|---|---|
| 普通 CLI 使用者 | 用 stable channel、讀 troubleshooting 和 release notes | 為了解決登入、配額或 shell 問題直接 clone 原始碼 |
| 外掛 / 自動化作者 | 用 headless、hooks、MCP、GitHub Action 驗證整合 | 修改 CLI 原始碼繞過產品邊界 |
| 官方貢獻者 | clone 儲存庫、跑 build/test/preflight、按貢獻流程提交 PR | 只跑 npm install 就認為環境可用 |
| CLI 自身 bug 排查 | 最小復現、原始碼構建、telemetry traces、issue 證據 | 把業務專案問題混進 CLI bug 報告 |
主要包
@google/gemini-cli 用户入口、命令解析、终端 UI、可执行包
@google/gemini-cli-core API 请求、认证、缓存、核心逻辑@google/gemini-cli 釋出時會被打成一個自包含執行檔。普通使用者全域性安裝或 npx 執行時，用到的是這個入口。
Workspace
官方儲存庫使用 NPM Workspaces 管理 packages/*。
{
"workspaces": ["packages/*"]
}這意味著在儲存庫根目錄安裝依賴時，workspace 內包會被統一安裝和連結。
flowchart LR
Repo["gemini-cli repo"] --> Workspaces["NPM workspaces"]
Workspaces --> Cli["@google/gemini-cli"]
Workspaces --> Core["@google/gemini-cli-core"]
Cli --> Bundle["self-contained executable"]
Core --> Runtime["auth / API / cache / tools"]
Bundle --> User["npx / global install"]
style Repo fill:#dbeafe,stroke:#3b82f6
style Cli fill:#dcfce7,stroke:#22c55e
style Core fill:#fef3c7,stroke:#f59e0b開發前檢查
貢獻或排障時，建議按順序做：
npm install
npm run build
npm run test
npm run preflight如果只是使用者側使用，不需要從原始碼構建，直接使用 stable channel 更穩。只有當官方 issue、PR review 或最小復現明確需要原始碼驗證時，才進入這條路徑。
驗證矩陣
| 檢查項 | 透過標準 | 失敗時先看 |
|---|---|---|
| 依賴安裝 | workspace 包能正常 linked | Node / NPM 版本、lockfile、網路代理 |
| Build | CLI 和 core 都能編譯 | TypeScript error、package 邊界、ESM 匯入 |
| Test | 單元測試和相關整合測試透過 | 最近改動、fixture、平臺差異 |
| Preflight | 官方提交前檢查透過 | lint、format、typecheck、測試殘留 |
| Telemetry | 能看到 model/tool 事件 | collector、埠、trace target、日誌目錄 |
釋出渠道
官方釋出分 stable、preview、nightly。普通使用者用 stable，想提前測試新功能再考慮 preview，只有能接受迴歸風險時才用 nightly。
除錯 telemetry
本地開發可以開啟 OpenTelemetry traces，觀察 model calls、tool scheduler 和 tool calls。官方本地開發文件提供三種檢視方式：Genkit Developer UI、Jaeger、Google Cloud Trace。
本地排查優先用 local / Jaeger，不要一上來把開發 traces 發到 Google Cloud。需要 GCP 時，先確認 project、認證、IAM 和 API 都準備好。
常見本地啟動方式：
npm run telemetry -- --target=local然後另開一個終端執行 gemini，到 Jaeger UI 檢視 traces。collector 日誌通常在 ~/.gemini/tmp/<projectHash>/otel/ 下。
貢獻和排錯邊界
普通教程讀者不需要原始碼構建；原始碼開發頁應該明確只服務兩類人：要給官方儲存庫貢獻程式碼的人，以及要定位 Gemini CLI 自身 bug 的人。遇到使用問題，先升級 stable、看 release notes 和 troubleshooting；不要把原始碼構建作為普通故障排查第一步。
更穩的 issue 證據結構：
- 說明 CLI 版本、釋出渠道、認證方式和系統環境。
- 提供最小復現命令，剔除業務專案裡的私有檔案。
- 附上失敗日誌或 trace 摘要，不貼 token、prompt 全文和內部路徑。
- 說明 stable / preview / nightly 是否都復現。
- 如果已經定位原始碼位置，再補 build/test/preflight 結果。
驗收方式
原始碼開發環境至少跑過 build、test、preflight。Telemetry 除錯則要確認 collector 啟動、CLI 產生 trace、UI 能看到 model/tool 事件。只完成 npm install 不算本地開發環境可用。
下一步
故障排查與參考
普通使用問題先回到 troubleshooting，不把原始碼構建當第一步。
Headless mode
需要指令碼呼叫 Gemini CLI 時，優先用 headless，而不是改原始碼。
Telemetry
需要 traces、metrics、logs 時，先看 telemetry 的資料邊界。