源码构建与本地调试

在官方源码仓库构建 CLI，使用 Node、React DevTools 和本地 OpenTelemetry 查看运行行为。

This page has not been translated into English yet. The original Chinese version is shown below.

以下操作在 Gemini CLI 源码仓库进行。官方贡献指南指定开发环境 Node.js ~20.19.0，并将生产运行要求写为 >=20；开发约束与用户安装要求应分别核对当前分支。

准备并运行源码

git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli
npm install
npm run build
npm start

build 构建各包。需要同时构建沙箱容器时使用 npm run build:all；普通 build 不重新构建该容器。启用沙箱仍需对应提供方和配置，详见沙箱提供方。

从其他目录运行源码时，官方给出 npm link 指向 packages/cli 的方式；使用前明确命令解析到本地构建还是已安装版本，避免测试错程序。

Node 与 VS Code 调试

npm run debug

贡献指南说明它以 Node inspect-brk 启动 CLI，暂停等待调试器连接。可在 VS Code 使用仓库 launch 配置，或通过 Chrome 的 chrome://inspect 附加。官方还提供 F5 调试入口。

沙箱内命中断点的指南示例为 DEBUG=1 gemini。普通项目 .env 中的 DEBUG 可能被过滤；CLI 专用变量放在 .gemini/.env，参见环境文件。

React 终端界面

用 DEV=true npm start 启动开发模式，再运行与官方 react-devtools-core 匹配的 React DevTools 6：

npx react-devtools@6

该流程调试的是 CLI 的 React 界面，不是业务项目网页。依赖版本变更后应重新核对当前源码指南。

本地 traces 后端

源码仓库提供 telemetry 脚本：

命令	用途
`npm run telemetry -- --target=genkit`	启动 Genkit telemetry server，按脚本输出 URL 查看 Traces
`npm run telemetry -- --target=local`	下载并启动 Jaeger 与 OTel Collector
`npm run telemetry -- --target=gcp`	启动转发至 Google Cloud 的本地 Collector

Genkit 示例 UI 为 localhost:4000，Jaeger 通常为 localhost:16686；实际以脚本输出为准。Collector 日志在 ~/.gemini/tmp/<projectHash>/otel/collector.log，GCP 对应 collector-gcp.log。

GCP Collector 路径需先准备项目、ADC/IAM 和 APIs，并设置 telemetry.enabled true、target gcp、useCollector true。它不能与 useCliAuth true 同用，见云端遥测。

本地开发页说启用遥测后采集 traces；遥测专页进一步说明完整提示、工具输出等详细属性还需 telemetry.traces true。先判断是否需要这些属性，再开启对应配置。

添加自己的 span

官方提供 runInDevTraceSpan 包装需观测的异步操作，operation 采用 GeminiCliOperation 枚举。回调内的 metadata 可记录 input、output、attributes，失败时记录 error 并重新抛出。

本地开发页示例包含未在片段内导入的常量及占位操作，不能当成可直接粘贴编译的完整程序。添加埋点时按当前源码导出与已有用法补齐依赖，避免把密钥或无关上下文写入自定义属性。