2026/9/7 1:46:12
FEATURED · 精选文章 
Gemini CLI 贡献者实战指南开发环境搭建、沙箱调试与自动化代码审查【免费下载链接】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 仓库的贡献指南 docs/CONTRIBUTING.md系统梳理从签署 CLA、配置本地开发环境到运行构建/测试/预检、配置沙箱调试以及使用自动化审查工具的完整贡献工作流。读完本文你将能够独立搭建 gemini-cli 的源码开发环境、通过npm run preflight全部校验并利用scripts/review.sh对自己的 PR 做 AI 辅助审查。开始前CLA 与社区准则贡献 Gemini CLI 需要满足两个前置条件签署 Google Contributor License AgreementCLA。签署后你或你的雇主保留贡献内容的版权CLA 只是授予项目使用和再分发贡献的权限。如果你或你的雇主已经签署过 Google CLA即使是为其他项目签署通常无需重复签署。遵循 Google 开源社区行为准则Open Source Community Guidelines。代码贡献流程贡献代码的标准路径是五步走认领 Issue。带有Maintainers only标签的 Issue 为维护者保留不接受社区 PR适合社区贡献的 Issue 会由维护者打上help-wanted标签。如果你认为某个 Issue 适合社区贡献先在 Issue 下留言由维护者确认后打标签。Fork 仓库并新建分支。在packages/目录中修改代码。项目是 npm workspaces monorepo核心改动集中在各 workspace 包内。运行npm run preflight确保所有检查通过见后文校验章节。提交 Pull Request。所有提交包括项目成员自己的代码都必须经过审查。项目通过 GitHub Pull Request 完成评审并提供了自动化审查工具来辅助发现常见反模式与测试问题详见「自动化代码审查」一节。自助认领与释放 Issue在 Issue 下评论/assign可将 Issue 分配给自己评论/unassign可将自己从 Issue 移除。注意评论内容必须只包含该命令本身不能夹带其他文字。同一时间你最多持有 3 个已分配 Issue且只有带help wanted标签的 Issue 可以被自助认领。Pull Request 六条规范不符合以下标准的 PR 可能会被直接关闭必须关联已存在的 Issue。Bug 修复关联 bug 报告 Issue功能开发需关联已被维护者批准的功能请求 Issue。如果 PR 没有关联 Issue会被自动关闭。理想流程是「先开 Issue、等反馈、再写代码」。保持小而聚焦。偏好解决单一问题或添加单一内聚功能的小 PR不要把 bug 修复、新功能、重构打包进同一个 PR。大改动应拆成一系列可独立评审合并的小 PR。进行中的工作使用 Draft PR。用 GitHub 的 Draft Pull Request 表示尚未准备好正式评审但开放讨论。确保所有检查通过。提交前在本地运行npm run preflight它会执行全部测试、lint 与样式检查。更新文档。如果 PR 引入用户可见变更新命令、修改的 flag、行为变化必须同步更新docs/目录中的相关文档见「文档贡献流程」一节。写清晰的 commit message 和 PR 描述。遵循 Conventional Commits 规范好的 PR 标题feat(cli): Add --json flag to config get command坏的 PR 标题Made some changesPR 描述中说明改动动机why并用Fixes #123关联 Issue。Fork 仓库后运行集成测试Fork 之后Build、Test 工作流可以直接跑但要让集成测试真正执行还需要两件事在你的 Fork 仓库中添加名为GEMINI_API_KEY的 GitHub Repository Secret值为你自己的有效 API Key。该 Secret 私有只有你有权限的人可见。在Actions标签页点击启用 workflows 按钮屏幕中央的大蓝色按钮。开发环境搭建前置条件Node.js开发使用 Node.js~20.19.0。由于一个上游开发依赖问题开发场景要求这个特定版本可用 nvm 之类的工具管理版本。生产运行已发布的 CLI 时Node.js20均可。这一点与 package.json 中engines字段的声明一致node: 20.0.0。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_ENVdevelopment node scripts/start.js见 package.jsonscripts/start.js 会先检查构建状态再通过scripts/sandbox_command.js解析沙箱配置后启动 CLI因此npm start会自动尊重你的沙箱设置。如果希望在 gemini-cli 目录之外使用源码构建的版本npm link path/to/gemini-cli/packages/cli # 或者 alias gemininode 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 VERBOSEtrue KEEP_OUTPUTtrue npm run test:integration:sandbox:none即以GEMINI_SANDBOXfalse模式在 integration-tests/ 目录下运行 vitest。仓库还提供npm run test:integration:all会依次跑sandbox:none、sandbox:docker、sandbox:podman三种沙箱形态的集成测试。更详细的集成测试框架说明见 docs/integration-tests.md。校验体系preflight、format 与 lintpreflight提交前的一站式检查npm run preflightpackage.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 辅助开发约定、ReactInk渲染规范、注释与 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_SANDBOXfalse适合快速交互式调试Attachattach 到 9229 端口的 Node inspector。配合根目录的npm run debug即cross-env DEBUG1 node --inspect-brk scripts/start.js见 package.json使用——它会挂起执行等待调试器连接你既可以用 VS Code 的 Attach 配置也可以用浏览器打开chrome://inspect连接该配置还设置了remoteRoot/localRoot映射便于在沙箱内用全局安装路径调试时正确还原源码映射Debug Test File / Debug Integration Test File分别以--inspect-brk9229启动 vitest 调试指定单测或集成测试文件若偏好直接运行当前打开的文件可用CLI: Run Current File基于node --import tsx但总体上更推荐F5走 Build Launch。在沙箱容器内打断点时直接运行DEBUG1 gemini注意如果项目.env中有DEBUGtrue由于自动排除机制不会影响 gemini-cligemini-cli 专属的调试设置请写入.gemini/.env。React DevTools 调试终端 UIGemini CLI 的交互界面基于 React Ink 渲染因此可以接入 React DevTools以开发模式启动 CLIDEVtrue npm start安装并运行与 CLI 中react-devtools-core版本匹配的 React DevTools 6见 package.json 中react-devtools-core: 6.1.2npm install -g react-devtools6 react-devtools # 或使用 npx npx react-devtools6运行中的 CLI 应用会自动连接到 React DevTools你可以在其中检查组件树、props 与状态。自动化代码审查工具所有 PR 都需要人工评审但项目提供了一个自动化审查工具来辅助发现常见反模式、测试问题和其他容易遗漏的最佳实践。方式一辅助脚本推荐./scripts/review.sh PR_NUMBER [model]阅读 scripts/review.sh 可以看到它的完整执行链校验 PR 存在性gh pr view避免把 Issue 号误当 PR 号要求在~/git/review/gemini-cli存在一个专门的 gemini-cli 克隆作为评审工作区fetch 最新origin/main然后用git worktree add --detach为 PR 创建独立 worktree再gh pr checkout拉取 PR 分支——不会污染你的主工作区清理node_modules与packages/*/dist等陈旧产物重新npm install并npm run build且会对构建日志做可疑错误模式error|failed|ERR!|FATAL|critical扫描即便退出码为 0 也会拦截最终执行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-reviewskill见 .gemini/skills/async-pr-review/SKILL.md可异步执行同类审查。方式二在 Gemini CLI 内手动触发如果 PR 代码已检出并构建完成可以直接在 CLI 提示符中输入/review-frontend PR_NUMBER评审者应将该工具作为人工评审的补充而不是替代。沙箱配置macOS Seatbelt在 macOS 上gemini使用 Seatbeltsandbox-exec执行沙箱默认采用permissive-open配置对应 packages/cli/src/utils/sandbox-macos-permissive-open.sb默认拒绝一切操作将写操作限制在项目目录内同时允许广泛的文件读取和出站网络open。通过环境变量或.env文件设置SEATBELT_PROFILEstrict-open可切换到更严格的配置packages/cli/src/utils/sandbox-macos-strict-open.sb把读和写都限制在工作目录内同时保留出站网络。内置 profile 共六套源码中一一对应均位于packages/cli/src/utils/permissive-open/permissive-proxiedrestrictive-open/restrictive-proxiedstrict-open/strict-proxied你还可以通过SEATBELT_PROFILEprofile切换自定义 profile前提是你在项目.gemini设置目录下创建了.gemini/sandbox-macos-profile.sb文件。更多细节可参考 docs/cli/sandbox.md。容器沙箱全平台在 macOS 或其他平台上需要更强的隔离时在环境变量或.env中设置GEMINI_SANDBOXtrue|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_SANDBOX1运行gemini触发自定义沙箱构建。代理网络限制所有沙箱方式包括 Seatbelt 的*-proxiedprofile都支持通过自定义代理服务器限制出站流量设置GEMINI_SANDBOX_PROXY_COMMANDcommand其中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:npmnpx google-artifactregistry-auth与auth:dockergcloud auth configure-docker见 package.json完成发布所需的两处凭证配置。文档贡献流程文档必须与代码贡献保持同步项目重视文档的清晰、准确、完整与示例化。文档贡献流程与代码贡献类似Fork 仓库并新建分支在docs/目录中修改本地预览Markdown 渲染效果Lint 与格式化——preflight 检查覆盖文档文件的 lint 与格式npm run preflight提交 Pull Request。文档结构文档以 docs/sidebar.json 作为目录table of contents组织。新增文档时把 Markdown 文件创建在docs/下的合适子目录中在sidebar.json的相应章节添加条目确保所有内部链接使用相对路径且指向真实存在的文件。写作风格遵循 Google Developer Documentation Style Guide要点包括标题使用 sentence case句首字母大写其余小写用第二人称you称呼读者使用现在时段落保持短小、聚焦代码块使用合适的语言标签以便语法高亮尽可能提供实际示例。文档 lint 与提交前检查文档使用 Prettier 统一风格可用命令npm run lint检查 lint 问题npm run format自动格式化 Markdownnpm 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 的校验链路并在提交前消除绝大多数返工风险。【免费下载链接】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），仅供参考
Gemini CLI 贡献者实战指南：开发环境搭建、沙箱调试与自动化代码审查
Gemini CLI 贡献者实战指南开发环境搭建、沙箱调试与自动化代码审查【免费下载链接】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 仓库的贡献指南 docs/CONTRIBUTING.md系统梳理从签署 CLA、配置本地开发环境到运行构建/测试/预检、配置沙箱调试以及使用自动化审查工具的完整贡献工作流。读完本文你将能够独立搭建 gemini-cli 的源码开发环境、通过npm run preflight全部校验并利用scripts/review.sh对自己的 PR 做 AI 辅助审查。开始前CLA 与社区准则贡献 Gemini CLI 需要满足两个前置条件签署 Google Contributor License AgreementCLA。签署后你或你的雇主保留贡献内容的版权CLA 只是授予项目使用和再分发贡献的权限。如果你或你的雇主已经签署过 Google CLA即使是为其他项目签署通常无需重复签署。遵循 Google 开源社区行为准则Open Source Community Guidelines。代码贡献流程贡献代码的标准路径是五步走认领 Issue。带有Maintainers only标签的 Issue 为维护者保留不接受社区 PR适合社区贡献的 Issue 会由维护者打上help-wanted标签。如果你认为某个 Issue 适合社区贡献先在 Issue 下留言由维护者确认后打标签。Fork 仓库并新建分支。在packages/目录中修改代码。项目是 npm workspaces monorepo核心改动集中在各 workspace 包内。运行npm run preflight确保所有检查通过见后文校验章节。提交 Pull Request。所有提交包括项目成员自己的代码都必须经过审查。项目通过 GitHub Pull Request 完成评审并提供了自动化审查工具来辅助发现常见反模式与测试问题详见「自动化代码审查」一节。自助认领与释放 Issue在 Issue 下评论/assign可将 Issue 分配给自己评论/unassign可将自己从 Issue 移除。注意评论内容必须只包含该命令本身不能夹带其他文字。同一时间你最多持有 3 个已分配 Issue且只有带help wanted标签的 Issue 可以被自助认领。Pull Request 六条规范不符合以下标准的 PR 可能会被直接关闭必须关联已存在的 Issue。Bug 修复关联 bug 报告 Issue功能开发需关联已被维护者批准的功能请求 Issue。如果 PR 没有关联 Issue会被自动关闭。理想流程是「先开 Issue、等反馈、再写代码」。保持小而聚焦。偏好解决单一问题或添加单一内聚功能的小 PR不要把 bug 修复、新功能、重构打包进同一个 PR。大改动应拆成一系列可独立评审合并的小 PR。进行中的工作使用 Draft PR。用 GitHub 的 Draft Pull Request 表示尚未准备好正式评审但开放讨论。确保所有检查通过。提交前在本地运行npm run preflight它会执行全部测试、lint 与样式检查。更新文档。如果 PR 引入用户可见变更新命令、修改的 flag、行为变化必须同步更新docs/目录中的相关文档见「文档贡献流程」一节。写清晰的 commit message 和 PR 描述。遵循 Conventional Commits 规范好的 PR 标题feat(cli): Add --json flag to config get command坏的 PR 标题Made some changesPR 描述中说明改动动机why并用Fixes #123关联 Issue。Fork 仓库后运行集成测试Fork 之后Build、Test 工作流可以直接跑但要让集成测试真正执行还需要两件事在你的 Fork 仓库中添加名为GEMINI_API_KEY的 GitHub Repository Secret值为你自己的有效 API Key。该 Secret 私有只有你有权限的人可见。在Actions标签页点击启用 workflows 按钮屏幕中央的大蓝色按钮。开发环境搭建前置条件Node.js开发使用 Node.js~20.19.0。由于一个上游开发依赖问题开发场景要求这个特定版本可用 nvm 之类的工具管理版本。生产运行已发布的 CLI 时Node.js20均可。这一点与 package.json 中engines字段的声明一致node: 20.0.0。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_ENVdevelopment node scripts/start.js见 package.jsonscripts/start.js 会先检查构建状态再通过scripts/sandbox_command.js解析沙箱配置后启动 CLI因此npm start会自动尊重你的沙箱设置。如果希望在 gemini-cli 目录之外使用源码构建的版本npm link path/to/gemini-cli/packages/cli # 或者 alias gemininode 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 VERBOSEtrue KEEP_OUTPUTtrue npm run test:integration:sandbox:none即以GEMINI_SANDBOXfalse模式在 integration-tests/ 目录下运行 vitest。仓库还提供npm run test:integration:all会依次跑sandbox:none、sandbox:docker、sandbox:podman三种沙箱形态的集成测试。更详细的集成测试框架说明见 docs/integration-tests.md。校验体系preflight、format 与 lintpreflight提交前的一站式检查npm run preflightpackage.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 辅助开发约定、ReactInk渲染规范、注释与 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_SANDBOXfalse适合快速交互式调试Attachattach 到 9229 端口的 Node inspector。配合根目录的npm run debug即cross-env DEBUG1 node --inspect-brk scripts/start.js见 package.json使用——它会挂起执行等待调试器连接你既可以用 VS Code 的 Attach 配置也可以用浏览器打开chrome://inspect连接该配置还设置了remoteRoot/localRoot映射便于在沙箱内用全局安装路径调试时正确还原源码映射Debug Test File / Debug Integration Test File分别以--inspect-brk9229启动 vitest 调试指定单测或集成测试文件若偏好直接运行当前打开的文件可用CLI: Run Current File基于node --import tsx但总体上更推荐F5走 Build Launch。在沙箱容器内打断点时直接运行DEBUG1 gemini注意如果项目.env中有DEBUGtrue由于自动排除机制不会影响 gemini-cligemini-cli 专属的调试设置请写入.gemini/.env。React DevTools 调试终端 UIGemini CLI 的交互界面基于 React Ink 渲染因此可以接入 React DevTools以开发模式启动 CLIDEVtrue npm start安装并运行与 CLI 中react-devtools-core版本匹配的 React DevTools 6见 package.json 中react-devtools-core: 6.1.2npm install -g react-devtools6 react-devtools # 或使用 npx npx react-devtools6运行中的 CLI 应用会自动连接到 React DevTools你可以在其中检查组件树、props 与状态。自动化代码审查工具所有 PR 都需要人工评审但项目提供了一个自动化审查工具来辅助发现常见反模式、测试问题和其他容易遗漏的最佳实践。方式一辅助脚本推荐./scripts/review.sh PR_NUMBER [model]阅读 scripts/review.sh 可以看到它的完整执行链校验 PR 存在性gh pr view避免把 Issue 号误当 PR 号要求在~/git/review/gemini-cli存在一个专门的 gemini-cli 克隆作为评审工作区fetch 最新origin/main然后用git worktree add --detach为 PR 创建独立 worktree再gh pr checkout拉取 PR 分支——不会污染你的主工作区清理node_modules与packages/*/dist等陈旧产物重新npm install并npm run build且会对构建日志做可疑错误模式error|failed|ERR!|FATAL|critical扫描即便退出码为 0 也会拦截最终执行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-reviewskill见 .gemini/skills/async-pr-review/SKILL.md可异步执行同类审查。方式二在 Gemini CLI 内手动触发如果 PR 代码已检出并构建完成可以直接在 CLI 提示符中输入/review-frontend PR_NUMBER评审者应将该工具作为人工评审的补充而不是替代。沙箱配置macOS Seatbelt在 macOS 上gemini使用 Seatbeltsandbox-exec执行沙箱默认采用permissive-open配置对应 packages/cli/src/utils/sandbox-macos-permissive-open.sb默认拒绝一切操作将写操作限制在项目目录内同时允许广泛的文件读取和出站网络open。通过环境变量或.env文件设置SEATBELT_PROFILEstrict-open可切换到更严格的配置packages/cli/src/utils/sandbox-macos-strict-open.sb把读和写都限制在工作目录内同时保留出站网络。内置 profile 共六套源码中一一对应均位于packages/cli/src/utils/permissive-open/permissive-proxiedrestrictive-open/restrictive-proxiedstrict-open/strict-proxied你还可以通过SEATBELT_PROFILEprofile切换自定义 profile前提是你在项目.gemini设置目录下创建了.gemini/sandbox-macos-profile.sb文件。更多细节可参考 docs/cli/sandbox.md。容器沙箱全平台在 macOS 或其他平台上需要更强的隔离时在环境变量或.env中设置GEMINI_SANDBOXtrue|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_SANDBOX1运行gemini触发自定义沙箱构建。代理网络限制所有沙箱方式包括 Seatbelt 的*-proxiedprofile都支持通过自定义代理服务器限制出站流量设置GEMINI_SANDBOX_PROXY_COMMANDcommand其中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:npmnpx google-artifactregistry-auth与auth:dockergcloud auth configure-docker见 package.json完成发布所需的两处凭证配置。文档贡献流程文档必须与代码贡献保持同步项目重视文档的清晰、准确、完整与示例化。文档贡献流程与代码贡献类似Fork 仓库并新建分支在docs/目录中修改本地预览Markdown 渲染效果Lint 与格式化——preflight 检查覆盖文档文件的 lint 与格式npm run preflight提交 Pull Request。文档结构文档以 docs/sidebar.json 作为目录table of contents组织。新增文档时把 Markdown 文件创建在docs/下的合适子目录中在sidebar.json的相应章节添加条目确保所有内部链接使用相对路径且指向真实存在的文件。写作风格遵循 Google Developer Documentation Style Guide要点包括标题使用 sentence case句首字母大写其余小写用第二人称you称呼读者使用现在时段落保持短小、聚焦代码块使用合适的语言标签以便语法高亮尽可能提供实际示例。文档 lint 与提交前检查文档使用 Prettier 统一风格可用命令npm run lint检查 lint 问题npm run format自动格式化 Markdownnpm 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 的校验链路并在提交前消除绝大多数返工风险。【免费下载链接】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），仅供参考 
