如何贡献

我们非常欢迎您为本项目贡献补丁和代码。本文档包括：

开始之前： 成为 Gemini CLI 贡献者之前需要执行的必要步骤。
代码贡献流程： 如何为 Gemini CLI 贡献代码。
开发环境和工作流程： 如何设置您的开发环境和工作流程。
文档贡献流程： 如何为 Gemini CLI 贡献文档。

我们期待您的贡献！

开始之前

签署贡献者许可协议

对项目的贡献必须附带一份贡献者许可协议（CLA）。您（或您的雇主）保留对您贡献的版权；这仅赋予我们使用和重新分发您贡献作为项目一部分的权限。

如果您或您的当前雇主已经签署了 Google CLA（即使是针对不同的项目），您可能不需要再次签署。

访问 https://cla.developers.google.com/ 以查看您当前的协议或签署新的协议。

审阅我们的社区准则

本项目遵循Google 开源社区准则。

代码贡献流程

开始

贡献代码的流程如下：

找到您想解决的问题。如果一个问题被标记为”🔒维护者专享”，这意味着它被保留给项目维护者。我们将不接受与这些问题相关的拉取请求。
派生仓库 并创建一个新分支。
在 packages/ 目录中进行更改。
运行 npm run preflight 确保所有检查通过。
打开一个包含您更改的拉取请求。

代码审查

（以下部分未翻译，因为要求只返回翻译后的中文文本）

所有提交，包括项目成员的提交，都需要经过审查。我们为此目的使用 GitHub pull 请求。

如果你的 pull 请求涉及到对 packages/cli（前端）的更改，我们建议运行我们的自动化前端审查工具。**注意：此工具目前处于实验阶段。**它有助于检测常见的 React 反模式、测试问题以及其他易于遗漏的前端特定最佳实践。

要在 Gemini CLI 中运行审查工具，输入以下命令：

/review-frontend <PR_NUMBER>

将 <PR_NUMBER> 替换为你的 pull 请求编号。我们鼓励作者在自己的 PR 上运行此工具进行自审，审阅者也应当用它来增强手动审查流程。

自行分配问题

要将一个问题分配给自己，只需添加一条只包含文本 /assign 的评论。该评论必须只包含该文本，不能有其他内容。这个命令会将问题分配给你，前提是它尚未被分配。

请注意，在任何给定时间，你可以分配给自己的问题最多为 3 个。

Pull 请求指南

为了帮助我们快速审查并合并你的 PR，请遵循以下指南。不符合这些标准的 PR 可能会被关闭。

1. 链接到现有问题

所有 PR 都应链接到我们跟踪器中的一个现有问题。这确保了在编写任何代码之前，每个更改都经过了讨论并且与项目目标保持一致。

对于错误修复： PR 应该链接到错误报告问题。
对于功能： PR 应该链接到已被维护者批准的功能请求或提案问题。

如果你的更改没有相应的问题，请 首先创建一个 并在开始编码之前等待反馈。

2. 保持小而专注

我们偏好小型的、原子性的 PR，这些 PR 应该解决单一问题或添加单一、自包含的功能。

**要做：**提交一个修复了具体错误或添加了具体功能的 PR。 **不要做：**将多个不相关的更改（例如，一个错误修复、一个新功能和一个重构）捆绑到单个 PR 中。

大型更改应该分解成一系列更小、逻辑上独立的 PR，以便可以独立进行审查和合并。

3. 使用草稿 PR 进行中的工作

如果您希望提前获取您工作的反馈，请使用 GitHub 的草稿拉取请求功能。这会向维护者表明 PR 尚未准备好进行正式审查，但已开放讨论和初步反馈。

4. 确保所有检查通过

在提交您的 PR 之前，请运行 npm run preflight 确保所有自动化检查都已通过。此命令运行所有测试、代码审查和其他样式检查。

5. 更新文档

如果您的 PR 引入了面向用户的变化（例如，新的命令、修改的标志或行为变更），您还必须更新 /docs 目录中相关的文档。

关于编写文档的更多信息，请参阅：文档贡献流程。

6. 编写清晰的提交信息和良好的 PR 描述

您的 PR 应该有一个清晰、描述性的标题以及变更的详细描述。提交信息请遵循 Conventional Commits 标准。

好的 PR 标题： feat(cli): Add --json flag to 'config get' command
差的 PR 标题： Made some changes

在 PR 描述中，解释您更改背后的“原因”并链接到相关的问题（例如，Fixes #123）。

分叉

（以下为标题，内容不翻译）

Forking

如果你正在分叉这个仓库，你将能够运行构建、测试和集成测试工作流。然而，为了使集成测试运行，你需要添加一个GitHub仓库密钥，其值为GEMINI_API_KEY，并将其设置为可用的有效API密钥。你的密钥和秘密对仓库是私有的；没有访问权限的人无法看到你的密钥，你也无法看到与此仓库相关的任何秘密。

此外，你还需要点击Actions标签，并为你的仓库启用工作流，你会在屏幕中央找到这个大蓝色按钮。

开发环境设置和工作流程

本节指导贡献者如何构建、修改和理解此项目的开发设置。

设置开发环境

先决条件：

Node.js：
- 开发： 请使用 Node.js ~20.19.0。由于上游开发依赖问题，需要使用此特定版本。你可以使用像nvm这样的工具来管理Node.js版本。
- 生产： 在生产环境中运行CLI，可以使用任何Node.js >=20版本。
Git

构建过程

要克隆仓库：

git clone https://github.com/google-gemini/gemini-cli.git # Or your fork's URL
cd gemini-cli

要安装在package.json中定义的依赖项以及根依赖项：

npm install

要构建整个项目（所有包）：

npm run build

此命令通常将TypeScript编译为JavaScript，打包资源，并准备执行包。有关在构建过程中发生的情况的更多详细信息，请参考scripts/build.js和package.json脚本。

启用沙盒机制

【沙箱环境】(#sandboxing) 强烈建议使用沙箱环境，至少需要在您的 ~/.env 中设置 GEMINI_SANDBOX=true，并确保有可用的沙箱提供程序（例如 macOS Seatbelt、docker 或 podman）。有关详细信息，请参见沙箱环境。

要构建 gemini CLI 实用程序和沙箱容器，请从根目录运行 build:all：

npm run build:all

若要跳过构建沙箱容器，可以使用 npm run build。

运行 CLI

要从源代码启动 Gemini CLI（构建后），请从根目录运行以下命令：

npm start

如果您想在 gemini-cli 文件夹外部运行源代码构建，可以利用 npm link path/to/gemini-cli/packages/cli（请参阅：文档）或使用 alias gemini="node path/to/gemini-cli/packages/cli" 与 gemini 运行。

运行测试

该项目包含两种类型的测试：单元测试和集成测试。

单元测试

要执行项目的单元测试套件：

npm run test

这将运行位于 packages/core 和 packages/cli 目录中的测试。在提交任何更改之前，请确保测试通过。为了更全面的检查，建议运行 npm run preflight。

集成测试

集成测试旨在验证 Gemini CLI 的端到端功能。它们不是默认 npm run test 命令的一部分。

要运行集成测试，请使用以下命令：

npm run test:e2e

有关集成测试框架的更详细信息，请参阅集成测试文档。

代码检查和预检

为了确保代码质量和格式一致性，请运行预检：

npm run preflight

此命令将运行 ESLint、Prettier、所有测试以及项目中定义的其他检查 package.json。

ProTip

在克隆之后，创建一个 git precommit 钩子文件以确保您的提交始终保持整洁。

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 format

此命令使用 Prettier 根据项目的风格指南格式化代码。

代码检查

要从项目根目录运行以下命令单独检查代码：

npm run lint

编码约定

请遵循现有代码库中使用的编码风格、模式和约定。
查阅 GEMINI.md（通常位于项目根目录中），获取与 AI 辅助开发相关的具体说明，包括 React、注释和 Git 使用的约定。
**导入：**特别注意导入路径。项目使用 ESLint 强制执行包之间的相对导入限制。

项目结构

packages/：包含项目的各个子包。
- a2a-server：Gemini CLI 的 A2A 服务器实现。（实验性）
- cli/：命令行界面。
- core/：Gemini CLI 的核心后端逻辑。
- test-utils：用于创建和清理测试的临时文件系统的实用工具。
- vscode-ide-companion/：Gemini CLI Companion 扩展与 Gemini CLI 配对。
docs/：包含所有项目文档。
scripts/：用于构建、测试和开发任务的实用脚本。

有关更详细架构，请参阅 docs/architecture.md。

调试

VS Code

【翻译】 0. 使用 CLI 在 VS Code 中以交互方式调试 F5

从根目录以调试模式启动 CLI：
Terminal window
```
npm run debug
```
该命令在 packages/cli 目录中运行 node --inspect-brk dist/gemini.js，暂停执行直到调试器附加。然后你可以在 Chrome 浏览器中打开 chrome://inspect 以连接到调试器。
在 VS Code 中，使用 “Attach”（附加）启动配置（位于 .vscode/launch.json）。

或者，如果你更愿意直接启动当前打开的文件，可以在 VS Code 中使用 “Launch Program”（启动程序）配置，但通常推荐使用 ‘F5’。

要在沙盒容器内命中断点，运行：

DEBUG=1 gemini

注意： 如果在项目的 .env 文件中有 DEBUG=true，它不会影响 gemini-cli，因为会自动排除。使用 .gemini/.env 文件为 gemini-cli 设置特定的调试设置。

React DevTools

要调试基于 React 的 CLI UI，你可以使用 React DevTools。Ink，CLI 界面使用的库，与 React DevTools 4.x 版本兼容。

以开发模式启动 Gemini CLI：
Terminal window
```
DEV=true npm start
```
安装并运行 React DevTools 4.28.5 版本（或最新兼容的 4.x 版本）：

你可以选择全局安装：
Terminal window
```
npm install -g react-devtools@4.28.5
react-devtools
```
或者直接使用 npx 运行：
Terminal window
```
npx react-devtools@4.28.5
```
你的运行中的 CLI 应用程序应该会连接到 React DevTools。

沙盒

macOS Seatbelt

【要求】只返回翻译后的中文文本,不要添加任何解释或注释。

在 macOS 上，gemini 使用 Seatbelt (sandbox-exec) 在 permissive-open 配置文件下（参见 packages/cli/src/utils/sandbox-macos-permissive-open.sb ），该配置文件限制了对项目文件夹的写入操作，但默认允许所有其他操作和出站网络流量（“开放”）。您可以通过在环境变量或 .env 文件中设置 SEATBELT_PROFILE=restrictive-closed ，切换到 restrictive-closed 配置文件（参见 packages/cli/src/utils/sandbox-macos-restrictive-closed.sb ），该配置文件默认拒绝所有操作和出站网络流量（“关闭”）。可用的内置配置文件有 {permissive,restrictive}-{open,closed,proxied} （有关代理网络，请参见下文）。如果您还创建了一个自定义配置文件 .gemini/sandbox-macos-<profile>.sb 在项目设置目录 .gemini 下，也可以切换到自定义配置文件 SEATBELT_PROFILE=<profile> 。

基于容器的沙盒（所有平台）

为了在 macOS 或其他平台上实现更强大的基于容器的沙盒，您可以在环境变量或 .env 文件中设置 GEMINI_SANDBOX=true|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 文件，并使用 gemini 和 BUILD_SANDBOX=1 来触发构建您自定义的沙盒，从而完全为项目定制沙盒。

代理网络

所有沙盒方法，包括使用 *-proxied 配置文件的 macOS Seatbelt，都支持通过自定义代理服务器限制出站网络流量，该代理服务器可以指定为 GEMINI_SANDBOX_PROXY_COMMAND=<command>，其中 <command> 必须启动一个代理服务器，在 :::8877 上监听相关请求。请参阅 docs/examples/proxy-script.md 以获取一个仅允许 HTTPS 连接到 example.com:443（例如 curl https://example.com）并拒绝所有其他请求的最小代理。代理会与沙盒一起自动启动和停止。

手动发布

我们对每次提交都会向内部注册表发布一个构件。但是，如果您需要手动创建本地构建，请运行以下命令：

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

文档贡献流程

我们的文档必须与代码贡献保持同步。我们希望文档清晰、简洁、对用户有帮助。我们重视以下几点：

清晰度： 使用简单直接的语言。尽可能避免行话。
准确性： 确保所有信息正确且最新。
完整性： 涵盖一个特性或主题的所有方面。
示例： 提供实际示例，帮助用户了解如何使用 Gemini CLI。

开始使用

【翻译】为文档做贡献的流程与贡献代码类似。

分叉仓库并创建一个新分支。
在/docs目录中进行更改。
在本地Markdown渲染中预览你的更改。
检查并格式化你的更改。我们的预检包括对文档文件的lint检查和格式化。
Terminal window
```
npm run preflight
```
提交一个包含你更改的拉取请求。

文档结构

我们的文档使用sidebar.json作为目录组织。添加新文档时：

在/docs下的适当目录中创建你的markdown文件。
在sidebar.json的相关部分添加一个条目。
确保所有内部链接使用相对路径并指向现有文件。

风格指南

我们遵循Google开发者文档风格指南。关于写作风格、语气和格式的指导，请参考该指南。

主要风格要点

标题使用句子大小写。
当称呼读者时，使用第二人称（“你”）。
使用现在时。
保持段落简短且专注。
使用带有适当语言标签的代码块进行语法高亮。
尽可能包含实际示例。

检查和格式化

我们使用prettier来确保我们的文档风格一致。npm run preflight命令将检查任何lint问题。

你也可以单独运行linter和格式化器：

npm run lint - 检查lint问题
npm run format - 自动格式化markdown文件
npm run lint:fix - 在可能的情况下自动修复lint问题

在提交拉取请求之前，请确保你的贡献没有lint错误。

提交前

在提交你的文档拉取请求之前，请：

运行 npm run preflight 确保所有检查通过。
审查你的更改以确保清晰和准确。
确认所有链接都能正确工作。
确保所有代码示例都已测试并功能正常。
如果你还没有签署，请签署贡献者许可协议（CLA）。

需要帮助？

如果你对贡献文档有疑问：

查阅我们的常见问题解答。
审阅现有文档以获取示例。
打开一个问题讨论你提议的更改。
联系维护人员。

我们感谢你对使 Gemini CLI 文档变得更好的贡献！