Gemini CLI 贡献者实战指南：开发环境搭建、沙箱调试与自动化代码审查

本文基于 Gemini CLI 仓库的贡献指南 docs/CONTRIBUTING.md，系统梳理从签署 CLA、配置本地开发环境，到运行构建/测试/预检、配置沙箱调试，以及使用自动化审查工具的完整贡献工作流。读完本文，你将能够独立搭建 gemini-cli 的源码开发环境、通过 npm run preflight 全部校验，并利用 scripts/review.sh 对自己的 PR 做 AI 辅助审查。

开始前：CLA 与社区准则

贡献 Gemini CLI 需要满足两个前置条件：

• 签署 Google Contributor License Agreement（CLA）。签署后你（或你的雇主）保留贡献内容的版权，CLA 只是授予项目使用和再分发贡献的权限。如果你或你的雇主已经签署过 Google CLA（即使是为其他项目签署），通常无需重复签署。
• 遵循 Google 开源社区行为准则（Open Source Community Guidelines）。

代码贡献流程

贡献代码的标准路径是五步走：

1. 认领 Issue。带有 🔒Maintainers only 标签的 Issue 为维护者保留，不接受社区 PR；适合社区贡献的 Issue 会由维护者打上 help-wanted 标签。如果你认为某个 Issue 适合社区贡献，先在 Issue 下留言，由维护者确认后打标签。
2. Fork 仓库并新建分支。
3. 在 packages/ 目录中修改代码。项目是 npm workspaces monorepo，核心改动集中在各 workspace 包内。
4. 运行 npm run preflight 确保所有检查通过（见后文校验章节）。
5. 提交 Pull Request。

所有提交（包括项目成员自己的代码）都必须经过审查。项目通过 GitHub Pull Request 完成评审，并提供了自动化审查工具来辅助发现常见反模式与测试问题（详见「自动化代码审查」一节）。

自助认领与释放 Issue

• 在 Issue 下评论 /assign 可将 Issue 分配给自己；
• 评论 /unassign 可将自己从 Issue 移除。

注意评论内容必须只包含该命令本身，不能夹带其他文字。同一时间你最多持有 3 个已分配 Issue，且只有带 help wanted 标签的 Issue 可以被自助认领。

Pull Request 六条规范

不符合以下标准的 PR 可能会被直接关闭：

1. 必须关联已存在的 Issue。Bug 修复关联 bug 报告 Issue；功能开发需关联已被维护者批准的功能请求 Issue。如果 PR 没有关联 Issue，会被自动关闭。理想流程是「先开 Issue、等反馈、再写代码」。
2. 保持小而聚焦。偏好解决单一问题或添加单一内聚功能的小 PR；不要把 bug 修复、新功能、重构打包进同一个 PR。大改动应拆成一系列可独立评审合并的小 PR。
3. 进行中的工作使用 Draft PR。用 GitHub 的 Draft Pull Request 表示尚未准备好正式评审，但开放讨论。
4. 确保所有检查通过。提交前在本地运行 npm run preflight，它会执行全部测试、lint 与样式检查。
5. 更新文档。如果 PR 引入用户可见变更（新命令、修改的 flag、行为变化），必须同步更新 docs/ 目录中的相关文档（见「文档贡献流程」一节）。
6. 写清晰的 commit message 和 PR 描述。遵循 Conventional Commits 规范：
   • 好的 PR 标题：feat(cli): Add --json flag to 'config get' command
   • 坏的 PR 标题：Made some changes
   • PR 描述中说明改动动机（why），并用 Fixes #123 关联 Issue。

Fork 仓库后运行集成测试

Fork 之后，Build、Test 工作流可以直接跑；但要让集成测试真正执行，还需要两件事：

• 在你的 Fork 仓库中添加名为 GEMINI_API_KEY 的 GitHub Repository Secret，值为你自己的有效 API Key。该 Secret 私有，只有你有权限的人可见。
• 在 Actions 标签页点击启用 workflows 按钮（屏幕中央的大蓝色按钮）。

开发环境搭建

前置条件

1. Node.js：
   • 开发：使用 Node.js ~20.19.0。由于一个上游开发依赖问题，开发场景要求这个特定版本，可用 nvm 之类的工具管理版本。
   • 生产：运行已发布的 CLI 时，Node.js >=20 均可。这一点与 package.json 中 engines 字段的声明一致（"node": ">=20.0.0"）。
2. Git。

克隆与构建

git clone https://gitcode.com/GitHub_Trending/gemi/gemini-cli.git  # 或你的 Fork 地址
cd gemini-cli
npm install       # 安装根依赖与各 workspace 依赖
npm run build     # 构建全部包

npm run build 对应 package.json 中的 node scripts/build.js，负责把 TypeScript 编译为 JavaScript、打包资源并让各 workspace 包可执行。项目根部的 GEMINI.md 还额外提供了 npm run build:all（同时构建包、沙箱容器与 VS Code companion 插件），在需要沙箱能力时用它。

从源码运行 CLI

构建完成后，在仓库根目录执行：

npm start

该命令实际执行 cross-env NODE_ENV=development node scripts/start.js（见 package.json），scripts/start.js 会先检查构建状态，再通过 scripts/sandbox_command.js 解析沙箱配置后启动 CLI，因此 npm start 会自动尊重你的沙箱设置。

如果希望在 gemini-cli 目录之外使用源码构建的版本：

npm link path/to/gemini-cli/packages/cli
# 或者
alias gemini="node path/to/gemini-cli/packages/cli"

测试体系：单元测试与集成测试

Gemini CLI 使用 Vitest 作为测试框架（见 GEMINI.md 的项目技术栈说明），分为两类测试：

单元测试

npm run test

这会执行 packages/core 和 packages/cli 等 workspace 中的测试。在 package.json 中可以看到根级 test 脚本为 npm run test --workspaces --if-present && npm run test:sea-launch，即逐个 workspace 执行各自定义的测试，最后再跑 SEA 启动器测试。提交前务必保证测试通过；更完整的检查建议跑 npm run preflight。

GEMINI.md 还给出了几条测试相关约定：

• 按 workspace 定向测试时用 npm test -w <pkg> -- <path>，其中 <path> 必须相对于 workspace 根目录；
• 涉及环境变量的测试使用 vi.stubEnv('NAME', 'value') 并在 afterEach 中 vi.unstubAllEnvs()，不要直接修改 process.env，以避免测试间串扰；
• npm run test:memory（内存回归）与 npm run test:perf（性能回归）属于 nightly 基线测试，仅在你改动相关领域时本地运行，否则交给 CI。

集成测试（E2E）

集成测试验证 CLI 的端到端功能，默认不包含在 npm run test 中：

npm run test:e2e

从 package.json 可以看到它的实际定义是 cross-env VERBOSE=true KEEP_OUTPUT=true npm run test:integration:sandbox:none，即以 GEMINI_SANDBOX=false 模式在 integration-tests/ 目录下运行 vitest。仓库还提供 npm run test:integration:all，会依次跑 sandbox:none、sandbox:docker、sandbox:podman 三种沙箱形态的集成测试。更详细的集成测试框架说明见 docs/integration-tests.md。

校验体系：preflight、format 与 lint

preflight：提交前的一站式检查

npm run preflight

package.json 中它的完整展开是：

npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck && npm run test:ci

也就是说 preflight 会做清理、干净安装、格式化、构建、全量 lint（零 warning 容忍，见 package.json 中 --max-warnings 0）、类型检查和 CI 模式测试。它是重量级命令，GEMINI.md 建议在实现任务的最后才运行；如果失败，先用更快的定向命令（npm run test、npm run lint、workspace 定向测试）迭代修复，再重跑 preflight。

独立执行 format / lint / 修复

npm run format    # Prettier 格式化（prettier --experimental-cli --write .）
npm run lint      # ESLint 检查
npm run lint:fix  # 尽可能自动修复 lint 问题

本地 pre-commit 钩子

克隆仓库后可以创建 git pre-commit 钩子，保证每次提交都经过完整校验：

echo "
# Run npm build and check for errors
if ! npm run preflight; then
  echo \"npm build failed. Commit aborted.\"
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

编码规范

• 遵循现有代码库的编码风格与模式；
• 参考项目根目录的 GEMINI.md，其中包含 AI 辅助开发约定、React（Ink）渲染规范、注释与 Git 使用约定等；
• 导入路径：项目用 ESLint 强制限制跨 workspace 包的相对导入，跨包引用要使用包名导出而非层层 ../；
• License 头：所有新的 .ts/.tsx/.js 源文件需包含当前年份的 Apache-2.0 license header，这一点由 ESLint 强制检查（见 GEMINI.md 的 Development Conventions 部分）。

调试

VS Code 调试

仓库自带 ​.vscode/launch.json，推荐用 F5 配合其中的配置调试：

• Build & Launch CLI：执行 npm run build-and-start，并默认设置 GEMINI_SANDBOX=false，适合快速交互式调试；
• Attach：attach 到 9229 端口的 Node inspector。配合根目录的 npm run debug（即 cross-env DEBUG=1 node --inspect-brk scripts/start.js，见 package.json）使用——它会挂起执行等待调试器连接，你既可以用 VS Code 的 Attach 配置，也可以用浏览器打开 chrome://inspect 连接；该配置还设置了 remoteRoot/localRoot 映射，便于在沙箱内用全局安装路径调试时正确还原源码映射；
• Debug Test File / Debug Integration Test File：分别以 --inspect-brk=9229 启动 vitest 调试指定单测或集成测试文件；
• 若偏好直接运行当前打开的文件，可用 CLI: Run Current File（基于 node --import tsx），但总体上更推荐 F5 走 Build & Launch。

在沙箱容器内打断点时，直接运行：

DEBUG=1 gemini

注意：如果项目 .env 中有 DEBUG=true，由于自动排除机制不会影响 gemini-cli；gemini-cli 专属的调试设置请写入 .gemini/.env。

React DevTools 调试终端 UI

Gemini CLI 的交互界面基于 React + Ink 渲染，因此可以接入 React DevTools：

1. 以开发模式启动 CLI：

   DEV=true npm start
   

2. 安装并运行与 CLI 中 react-devtools-core 版本匹配的 React DevTools 6（见 package.json 中 react-devtools-core: 6.1.2）：

   npm install -g react-devtools@6
   react-devtools
   # 或使用 npx
   npx react-devtools@6
   

运行中的 CLI 应用会自动连接到 React DevTools，你可以在其中检查组件树、props 与状态。

自动化代码审查工具

所有 PR 都需要人工评审，但项目提供了一个自动化审查工具来辅助发现常见反模式、测试问题和其他容易遗漏的最佳实践。

方式一：辅助脚本（推荐）

./scripts/review.sh <PR_NUMBER> [model]

阅读 scripts/review.sh 可以看到它的完整执行链：

1. 校验 PR 存在性（gh pr view），避免把 Issue 号误当 PR 号；
2. 要求在 ~/git/review/gemini-cli 存在一个专门的 gemini-cli 克隆作为评审工作区；
3. fetch 最新 origin/main，然后用 git worktree add --detach 为 PR 创建独立 worktree，再 gh pr checkout 拉取 PR 分支——不会污染你的主工作区；
4. 清理 node_modules 与 packages/*/dist 等陈旧产物，重新 npm install 并 npm run build，且会对构建日志做可疑错误模式（error|failed|ERR!|FATAL|critical）扫描，即便退出码为 0 也会拦截；
5. 最终执行 npm start -- -m <model> -i "/review-frontend <pr>"，即启动 CLI 并让它自动发出 /review-frontend 审查指令。

模型参数默认是 gemini-3.1-pro-preview（见 scripts/review.sh）；如果 Pro 配额不够，可以指定 Flash 模型：

./scripts/review.sh <PR_NUMBER> gemini-3-flash-preview

安全警告：运行 scripts/review.sh 前，你必须先确认被审查 PR 的代码是安全的、不包含数据外泄攻击——因为该脚本会在本机真实安装依赖、构建并运行 PR 代码。

强烈建议 PR 作者在建好 PR 后立刻对自己跑一遍该脚本，在维护者完整评审之前先在本地捕获并修复简单问题。仓库同时提供了配套的 async-pr-review skill（见 .gemini/skills/async-pr-review/SKILL.md），可异步执行同类审查。

方式二：在 Gemini CLI 内手动触发

如果 PR 代码已检出并构建完成，可以直接在 CLI 提示符中输入：

/review-frontend <PR_NUMBER>

评审者应将该工具作为人工评审的补充，而不是替代。

沙箱配置

macOS Seatbelt

在 macOS 上，gemini 使用 Seatbelt（sandbox-exec）执行沙箱，默认采用 permissive-open 配置（对应 packages/cli/src/utils/sandbox-macos-permissive-open.sb）：默认拒绝一切操作，将写操作限制在项目目录内，同时允许广泛的文件读取和出站网络（"open"）。通过环境变量或 .env 文件设置 SEATBELT_PROFILE=strict-open，可切换到更严格的配置（packages/cli/src/utils/sandbox-macos-strict-open.sb），把读和写都限制在工作目录内，同时保留出站网络。

内置 profile 共六套，源码中一一对应（均位于 packages/cli/src/utils/）：

• permissive-open / permissive-proxied
• restrictive-open / restrictive-proxied
• strict-open / strict-proxied

你还可以通过 SEATBELT_PROFILE=<profile> 切换自定义 profile，前提是你在项目 .gemini 设置目录下创建了 .gemini/sandbox-macos-<profile>.sb 文件。更多细节可参考 docs/cli/sandbox.md。

容器沙箱（全平台）

在 macOS 或其他平台上需要更强的隔离时，在环境变量或 .env 中设置：

GEMINI_SANDBOX=true|docker|podman|<command>

命令（或为 true 时的 docker/podman）必须安装在宿主机上。启用后：

• npm run build:all 会额外构建一个极简沙箱容器镜像（npm run build 不会构建沙箱）；首次构建约 20–30 秒（主要花在拉取基础镜像），之后构建与启动的开销都很小；
• npm start 会在该容器的全新实例中启动 CLI，容器的启动/停止/清理随 CLI 生命周期自动进行；
• 项目目录与系统临时目录以读写方式挂载，沙箱内创建的文件会自动映射到宿主机的用户/组；
• 通过 SANDBOX_MOUNTS、SANDBOX_PORTS、SANDBOX_ENV 可追加挂载、端口与环境变量；
• 也可以完全自定义沙箱：在项目 .gemini 目录下创建 sandbox.Dockerfile 和/或 sandbox.bashrc，然后以 BUILD_SANDBOX=1 运行 gemini 触发自定义沙箱构建。

代理网络限制

所有沙箱方式（包括 Seatbelt 的 *-proxied profile）都支持通过自定义代理服务器限制出站流量：设置 GEMINI_SANDBOX_PROXY_COMMAND=<command>，其中 <command> 必须启动一个监听 :::8877 的代理进程，只放行被允许的请求。docs/examples/proxy-script.md 给出了一个最小代理示例——它只允许对 example.com:443 的 HTTPS 连接（如 curl https://example.com），拒绝其他所有请求。代理会随沙箱一起自动启停。

手动发布

仓库对每个 commit 都会自动向内部 registry 发布产物。如果需要手动切一个本地构建版本：

npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces

其中 npm run auth 会依次执行 auth:npm（npx google-artifactregistry-auth）与 auth:docker（gcloud auth configure-docker，见 package.json），完成发布所需的两处凭证配置。

文档贡献流程

文档必须与代码贡献保持同步，项目重视文档的清晰、准确、完整与示例化。文档贡献流程与代码贡献类似：

1. Fork 仓库并新建分支；

2. 在 docs/ 目录中修改；

3. 本地预览 Markdown 渲染效果；

4. Lint 与格式化——preflight 检查覆盖文档文件的 lint 与格式：

   npm run preflight
   

5. 提交 Pull Request。

文档结构

文档以 docs/sidebar.json 作为目录（table of contents）组织。新增文档时：

1. 把 Markdown 文件创建在 docs/ 下的合适子目录中；
2. 在 sidebar.json 的相应章节添加条目；
3. 确保所有内部链接使用相对路径且指向真实存在的文件。

写作风格

遵循 Google Developer Documentation Style Guide，要点包括：

• 标题使用 sentence case（句首字母大写，其余小写）；
• 用第二人称（"you"）称呼读者；
• 使用现在时；
• 段落保持短小、聚焦；
• 代码块使用合适的语言标签以便语法高亮；
• 尽可能提供实际示例。

文档 lint 与提交前检查

文档使用 Prettier 统一风格，可用命令：

• npm run lint：检查 lint 问题；
• npm run format：自动格式化 Markdown；
• npm run lint:fix：尽可能自动修复 lint 问题；
• npm run preflight：提交前的一站式检查。

提交文档 PR 前请确认：preflight 全部通过、内容清晰准确、所有链接可用、代码示例经过验证可运行、CLA 已签署。如对文档有疑问，先查阅现有文档范例，或开一个 Issue 与维护者讨论你的改动方案。

小结

Gemini CLI 的贡献体系可以概括为一条主线：Issue 先行认领 → 小而聚焦的 PR → npm run preflight 全量校验（clean、安装、格式化、构建、零警告 lint、typecheck、CI 测试）→ 用 scripts/review.sh 或 /review-frontend 做 AI 辅助自审 → 按规范更新 docs/ 与 docs/sidebar.json。配合 Node.js ~20.19.0 开发环境、VS Code 的 Attach 调试与 React DevTools、以及 Seatbelt/容器双沙箱体系，你可以在本地完整复现 CI 的校验链路，并在提交前消除绝大多数返工风险。