本地开发
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 的数据边界。