Gemini CLI 贡献指南从 CLA 到 preflight 全流程构建、测试与沙箱开发环境实战【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文以 Gemini CLI 仓库的 CONTRIBUTING.md 为主体系统讲解向该项目贡献代码与文档的完整流程签署 CLA、寻找可认领的 Issue、遵循 Pull Request 规范并深入拆解开发环境的搭建方式——包括npm run build构建流程、npm run preflight质量门禁背后的每一步检查、review.sh自动评审工具、VS Code 调试与 React DevTools 调试以及 macOS Seatbelt 与容器化沙箱两套隔离方案的配置细节。读完本文你可以独立完成一次从克隆仓库到提交 PR 的完整贡献并理解项目各条 npm 脚本命令的真实实现。贡献前的两项准备签署 Contributor License Agreement任何贡献都必须附带 Google 的 CLAContributor License Agreement。作者或其雇主保留对贡献的版权CLA 只是授予项目使用和再分发贡献的许可。如果你或你当前的雇主已经签署过 Google CLA哪怕是针对其他项目的通常无需重复签署。你可以在 Google CLA 页面cla.developers.google.com查看当前协议状态或签署新的协议。遵守社区行为准则项目遵循 Google 开源社区行为准则Google Open Source Community Guidelines所有 issue 讨论、PR 评审都应在此框架内进行。代码贡献流程五步贡献流程找一个 Issue被标记为Maintainers only的 Issue 仅保留给项目维护者不会接受相关 PR。对于认为适合社区贡献的 Issue可以在 Issue 下留言由维护者评估后打上help-wanted标签只有维护者可以添加该标签。Fork 仓库并创建新分支。在packages/目录中完成修改所有产品代码都位于 packages/ 下的多个工作区包中cli、core、sdk、devtools、a2a-server、vscode-ide-companion、test-utils等这一点可以从 package.json 中的workspaces: [packages/*]得到印证。确保所有检查通过运行npm run preflight。提交 Pull Request。自动评审工具项目提供了自动评审工具帮助检测常见反模式、测试缺失等容易遗漏的问题。所有提交包括项目成员自己都必须经过 PR 评审自动评审用于辅助而非替代人工评审。有两种运行方式方式一使用辅助脚本推荐./scripts/review.sh PR_NUMBER [model]该脚本会自动完成把 PR checkout 到独立 worktree、安装依赖、构建项目、启动评审工具。从 scripts/review.sh 的源码可以看到脚本要求预先在~/git/review/gemini-cli目录有一份仓库克隆会先用gh pr view校验 PR 是否存在然后打开 PR 页面供人工核对。脚本有两点重要提醒警告运行review.sh前必须人工确认被评审 PR 的代码可以安全执行、不包含数据外泄攻击。强烈建议 PR 作者在自己 PR 创建后立即运行此脚本在维护者完整评审前先本地发现并修复简单问题。模型选择脚本默认使用最新的 Pro 模型gemini-3.1-pro-preview这一点在 scripts/review.sh 中可见model${2:-gemini-3.1-pro-preview}。如果 Pro 配额不足可以用 Flash 模型运行./scripts/review.sh PR_NUMBER gemini-3-flash-preview方式二在 Gemini CLI 中手动运行如果 PR 代码已经在本地 checkout 并构建完成可以直接在 CLI 提示符中执行/review-frontend PR_NUMBERIssue 的自我认领与取消认领在 Issue 下评论/assign即可认领评论/unassign取消认领。评论内容必须只有这一行文字不能包含其他内容。同时最多只能认领 3 个 Issue只有打了help wanted标签的 Issue 才允许自我认领Issue 必须处于未认领状态才能被认领。Pull Request 六项规范不满足这些标准的 PR 可能会被直接关闭。1. 必须关联已有 Issue所有 PR 都要关联 Issue 跟踪系统中的一个已有 Issue确保每个变更在写代码前已被讨论并与项目目标对齐Bug 修复关联对应的 bug 报告新功能关联经维护者批准的提案 Issue。如果不存在对应 IssuePR 会被自动关闭并附上提醒评论。正确的工作流是先开 Issue 等待反馈再开始编码。2. 保持小而聚焦偏好小颗粒、原子的 PR一个 PR 只解决一个 Issue 或添加一个自包含的功能。不要在一个 PR 里混入 Bug 修复、新功能和重构。大改动应拆成一系列可以独立评审、独立合并的小 PR。3. 用 Draft PR 获取早期反馈尚未完工的工作请使用 GitHub 的 Draft Pull Request 功能向维护者表明 PR 还未进入正式评审、仅开放讨论。4. 确保所有检查通过提交前运行npm run preflight它会执行全部测试、lint 和其他风格检查下节详解。5. 更新文档如果 PR 引入了面向用户的变更新命令、修改的 flag、行为变化必须同步更新/docs目录下的相关文档。6. 写清晰的 commit message 和 PR 描述commit message 遵循 Conventional Commits 标准。示例好的 PR 标题feat(cli): Add --json flag to config get command坏的 PR 标题Made some changesPR 描述中要解释变更的为什么并链接相关 Issue如Fixes #123。Fork 后的 CI 配置Fork 仓库后可以运行 Build、Test 和 Integration test 工作流但要让集成测试跑起来需要在自己的 fork 中添加名为GEMINI_API_KEY的 GitHub Repository Secret值设为一个有效的 API key。该密钥仅对你的仓库私有。此外还需到仓库的Actions标签页手动启用工作流页面中央的大蓝色按钮。开发环境搭建与工作流前置条件Node.js开发环境请使用 Node.js~20.19.0因为上游开发依赖的兼容性问题需要锁定该版本可用 nvm 管理生产环境运行 CLI 则任意20的版本都可以。package.json 中声明的engines: { node: 20.0.0 }正对应这一生产要求。Git。克隆与构建git clone https://github.com/google-gemini/gemini-cli.git # 或你的 fork 地址 cd gemini-cli安装依赖包括 package.json 中定义的工作区依赖与根依赖npm install构建整个项目所有包npm run build该命令通常会把 TypeScript 编译为 JavaScript、打包资源并准备各包的可执行产物。在 package.json 中可以看到build: node scripts/build.js对应实现是 scripts/build.js构建细节可参考它和package.json的 scripts 字段。启用沙箱构建CONTRIBUTING.md 强烈建议开发者启用沙箱Sandbox最低要求是在~/.env中设置GEMINI_SANDBOXtrue并确保有可用的沙箱提供方macOS Seatbelt、docker 或 podman。要同时构建geminiCLI 和沙箱容器在仓库根目录运行npm run build:all如果想跳过沙箱容器的构建用npm run build即可。从 package.json 可确认build:all的完整语义build:all: npm run build npm run build:sandbox npm run build:vscode, build:sandbox: node scripts/build_sandbox.js,即依次执行主构建、沙箱镜像构建scripts/build_sandbox.js以及 VS Code 伴侣扩展构建。运行 CLI构建后从源码启动 Gemini CLInpm start对应实现为cross-env NODE_ENVdevelopment node scripts/start.js见 scripts/start.js。如果想在 gemini-cli 目录之外运行源码构建可以npm link path/to/gemini-cli/packages/cli # 或者 alias gemininode path/to/gemini-cli/packages/cli运行测试项目包含两类测试单元测试与集成测试。单元测试npm run test覆盖packages/core与packages/cli的测试套件。从 package.json 可以看到它实际上是test: npm run test --workspaces --if-present npm run test:sea-launch即在所有工作区运行各自存在的测试外加 sea/sea-launch.test.js并且还有posttest: npm run build钩子。提交任何变更前都应确保测试通过更彻底的检查是npm run preflight。集成测试集成测试用于验证端到端功能不包含在默认的npm run test中npm run test:e2epackage.json 显示其定义为cross-env VERBOSEtrue KEEP_OUTPUTtrue npm run test:integration:sandbox:none即不带沙箱GEMINI_SANDBOXfalse地运行 integration-tests/ 目录下的 vitest 套件。仓库还提供了test:integration:sandbox:docker、test:integration:sandbox:podman等变体。集成测试框架的详细说明见 docs/integration-tests.md——该文档指出运行集成测试前需要先执行npm run bundle生成被测试的 release bundle且每次修改 CLI 源码后都要重新 bundle。Lint 与 preflight 检查npm run preflight是提交前的总闸门。对照 package.json 的定义preflight: npm run clean npm ci npm run format npm run build npm run lint:ci npm run typecheck npm run test:ci即依次执行清理scripts/clean.js、npm ci全新安装、Prettier 格式化、全量构建、CI 模式 lintscripts/lint.js 的lint:all、TypeScript 类型检查各工作区 typecheck 加上 evals / integration-tests / memory-tests 的tsc -b以及test:ci各工作区 CI 测试 脚本测试 SEA 启动测试。ProTip克隆后创建 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也可以单独执行格式化npm run formatPrettier 按项目风格格式化全部文件含 MarkdownLintnpm run lintESLint--max-warnings 0零警告策略自动修复npm run lint:fix。另外 package.json 还配置了huskylint-staged的提交时检查暂存的*.{js,jsx,ts,tsx}会被 Prettier 格式化并经 ESLint--fix修正*.{json,md}会被 Prettier 格式化。编码规范遵循现有代码库的风格、模式和约定阅读 GEMINI.md项目根目录其中包含 AI 辅助开发的具体约定包括 React、注释和 Git 使用规范特别注意导入路径项目用 ESLint 强制限制跨包的相对导入eslint.config.js应使用包名而非跨包相对路径。调试VS Code在根目录运行npm run debug该命令是cross-env DEBUG1 node --inspect-brk scripts/start.js会暂停执行直到调试器附着此时可以用 Chrome 打开chrome://inspect连接调试器。也可以直接使用 .vscode/launch.json 中的 Attach 启动配置或者 Launch Program 配置直接启动当前打开的文件但一般推荐用 F5 对应的主配置Build Launch CLI 会先执行npm run build-and-start并在env中默认关闭GEMINI_SANDBOX以便断点生效。要在沙箱容器内命中断点运行DEBUG1 gemini注意如果项目的.env文件里有DEBUGtrue由于自动排除机制它不会影响 gemini-cli给 gemini-cli 专用的调试设置请写入.gemini/.env。React DevToolsCLI 的界面基于 ReactInk构建可以用 React DevTools 调试以开发模式启动 CLIDEVtrue npm start安装并运行与 CLI 的react-devtools-core版本6.x见 package.json 中react-devtools-core: 6.1.2匹配的 React DevTools 6npm install -g react-devtools6 react-devtools # 或者 npx react-devtools6运行中的 CLI 会自动连接 React DevTools沙箱机制详解macOS Seatbelt在 macOS 上gemini使用 Seatbeltsandbox-exec加载permissive-open策略packages/cli/src/utils/sandbox-macos-permissive-open.sb。从该策略文件源码看它以(deny default)拒绝默认操作显式允许从宿主机任意位置读文件(allow file-read*)、进程 exec/fork子进程继承策略从而保持被沙箱化、向自身发信号如写关闭管道时的 SIGPIPE以及读取有限的 sysctl 信息写入则被限制在项目文件夹内同时默认放行广泛的文件读取与出站网络open。可以通过设置SEATBELT_PROFILEstrict-open写入环境或.env切换到strict-open策略packages/cli/src/utils/sandbox-macos-strict-open.sb它把读取和写入都限制在工作目录内但默认仍放行出站网络。内置的全部策略档位为permissive-{open,proxied}、restrictive-{open,proxied}、strict-{open,proxied}对应 packages/cli/src/utils/ 下的六个.sb文件。也可以自定义策略设置SEATBELT_PROFILEprofile并在项目设置目录.gemini下创建.gemini/sandbox-macos-profile.sb。容器化沙箱全平台在 macOS 或其他平台上想要更强的容器级隔离可以在环境或.env中设置GEMINI_SANDBOXtrue|docker|podman|command指定的命令true时为docker或podman之一必须已安装在宿主机上。启用后npm run build:all会构建一个最小的沙箱容器镜像npm start会启动该镜像的一个全新实例首次构建约需 20–30 秒主要是拉取基础镜像之后构建和启动的开销都很小。默认构建npm run build不会重建沙箱镜像。容器沙箱会以读写方式挂载项目目录以及系统临时目录并随 Gemini CLI 的启动/停止自动启动/停止/移除。沙箱内创建的文件会自动映射到宿主机的用户/组。通过SANDBOX_{MOUNTS,PORTS,ENV}可以额外指定挂载、端口和环境变量。还可以为项目完全定制沙箱在.gemini下创建.gemini/sandbox.Dockerfile和/或.gemini/sandbox.bashrc然后以BUILD_SANDBOX1运行gemini触发定制沙箱的构建。代理网络Proxied networking所有沙箱方式包括使用*-proxied策略的 macOS Seatbelt都支持通过自定义代理服务器限制出站网络流量用GEMINI_SANDBOX_PROXY_COMMANDcommand指定。command必须启动一个监听:::8877的代理服务器。仓库提供了最小示例docs/examples/proxy-script.md 中的代理只放行到example.com:443的 HTTPS 连接例如curl https://example.com拒绝所有其他请求。代理会随沙箱自动启动和停止。手动发布项目会为每个提交向内部 registry 发布产物。如果确实需要手动切一个本地构建npm run clean npm install npm run auth npm run prerelease:dev npm publish --workspaces其中npm run auth在 package.json 中定义为npm run auth:npm npm run auth:docker即依次执行npx google-artifactregistry-auth和gcloud auth configure-docker us-west1-docker.pkg.dev分别完成 Artifact Registry 与 Docker 的发布认证。文档贡献流程项目要求文档与代码贡献保持同步追求清晰、准确、完整并尽量提供实用示例。文档贡献五步Fork 仓库并创建新分支在/docs目录中完成修改本地预览 Markdown 渲染效果Lint 并格式化改动——preflight 检查已包含对文档文件的检查npm run preflight提交 Pull Request。文档组织结构文档以 docs/sidebar.json 作为目录table of contents。从该文件源码可以看到每个条目由label显示名和slug对应文档路径如docs/get-started/installation构成并按 Get started、Use Gemini CLI 等分组嵌套。新增文档时把 Markdown 文件创建在/docs下的合适目录中在sidebar.json的相应分组中添加条目确保所有内部链接使用相对路径且指向真实存在的文件。写作风格项目遵循 Google Developer Documentation Style Guide。关键要点标题使用 sentence case句首大写用第二人称you称呼读者使用现在时段落短小、聚焦代码块使用正确的语言标签以启用语法高亮尽可能附上实用示例。文档 Lint 与格式化项目用 Prettier 保持文档风格一致npm run preflight会检查 lint 问题。也可以单独运行npm run lint—— 检查 lint 问题npm run format—— 自动格式化 Markdown 文件npm run lint:fix—— 尽可能自动修复 lint 问题。提交文档 PR 前请确保没有 lint 错误。提交前自查清单运行npm run preflight确保所有检查通过复查改动的清晰度与准确性确认所有链接可正确访问确保代码示例经过测试、确实可用如果尚未签署请签署 CLA。如果文档贡献过程中遇到问题可以查看现有文档找范例、在仓库 Issue 中先讨论拟议的改动、或直接联系维护者。项目欢迎每一份让文档变得更好的贡献。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考