IDE 集成

IDE 集成

Gemini CLI 可以与您的 IDE 集成，以提供更加无缝和上下文感知的体验。这种集成使 CLI 能够更好地理解您的工作空间，并启用如编辑器内原生差异对比等强大功能。

目前支持的 IDE 有 Antigravity、Visual Studio Code 以及支持 VS Code 扩展的其他编辑器。要为其他编辑器构建支持，请参阅 IDE 伴侣扩展规范。

功能

• 工作空间上下文： CLI 会自动获取您工作空间的相关信息，以提供更相关和准确的响应。此上下文包括：

  • 您工作空间中最近访问的 10 个文件。
  • 您的活跃光标位置。
  • 您选择的任何文本（最多 16KB 限制；较长的选择将被截断）。

• 原生差异对比： 当 Gemini 建议代码修改时，您可以直接在 IDE 的原生差异查看器中查看更改。这使得您可以无缝地审查、编辑并接受或拒绝建议的更改。

• VS Code 命令： 您可以直接从 VS Code 命令面板访问 Gemini CLI 功能（Cmd+Shift+P 或 Ctrl+Shift+P）：

  • Gemini CLI: Run：在集成终端中启动新的 Gemini CLI 会话。
  • Gemini CLI: Accept Diff：接受活动差异编辑器中的更改。
  • Gemini CLI: Close Diff Editor：拒绝更改并关闭活动差异编辑器。
  • Gemini CLI: View Third-Party Notices：显示扩展的第三方通知。

安装和设置

有三种方法可以设置 IDE 集成：

1. 自动提示（推荐）

当您在支持的编辑器内运行 Gemini CLI 时，它将自动检测您的环境并提示您连接。回答 “Yes” 将自动运行必要的设置，包括安装伴侣扩展和启用连接。

2. 从 CLI 手动安装

（此处原文未给出后续内容，故翻译亦到此为止。）

如果你之前忽略了提示或者想要手动安装扩展，可以在 Gemini CLI 中运行以下命令：

/ide install

这将找到适合你 IDE 的正确扩展并安装它。

3. 从市场手动安装

你也可以直接从市场安装扩展。

• 对于 Visual Studio Code： 从 VS Code 市场 安装。
• 对于 VS Code 分支： 为了支持 VS Code 的分支，扩展也发布在 Open VSX 注册表 上。按照你的编辑器的说明从该注册表安装扩展。

注意：在搜索结果中，“Gemini CLI Companion”扩展可能会出现在底部。如果你没有立即看到它，请尝试向下滚动或按“最新发布”排序。

手动安装扩展后，你必须在 CLI 中运行 /ide enable 以激活集成。

使用方法

启用和禁用

你可以从 CLI 内控制 IDE 集成：

• 要启用与 IDE 的连接，运行：

  /ide enable

• 要禁用连接，运行：

  /ide disable

启用后，Gemini CLI 将自动尝试连接到 IDE 伴随扩展。

检查状态

要检查连接状态并查看 CLI 从 IDE 收到的上下文，运行：

/ide status

如果已连接，此命令将显示 CLI 连接到的 IDE 和它所知的最近打开的文件列表。

[!NOTE] 文件列表限于工作空间内最近访问的 10 个文件，并且只包括磁盘上的本地文件。）

使用差异

当你要求 Gemini 修改一个文件时，它可以直接在你的编辑器中打开一个差异视图。

接受差异，你可以执行以下任意操作：

• 在差异编辑器标题栏中点击勾选图标。
• 保存文件（例如，使用Cmd+S或Ctrl+S）。
• 打开命令面板并运行Gemini CLI: 接受差异。
• 当提示时，在 CLI 中回应yes。

要拒绝一个差异，你可以：

• 在差异编辑器标题栏中点击**‘x’图标**。
• 关闭差异编辑器标签页。
• 打开命令面板并运行Gemini CLI: 关闭差异编辑器。
• 当提示时，在 CLI 中回应no。

你还可以在直接在差异视图中修改建议的更改，然后再接受它们。

如果你在 CLI 中选择了‘本次会话允许’，更改将不再在 IDE 中显示，因为它们会被自动接受。

使用沙盒环境

如果你在沙盒环境中使用 Gemini CLI，请注意以下事项：

• 在 macOS 上： IDE 集成需要网络访问以与 IDE 伴侣扩展通信。你必须使用允许网络访问的 Seatbelt 配置文件。
• 在 Docker 容器中： 如果你将 Gemini CLI 运行在 Docker（或 Podman）容器内，IDE 集成仍然可以连接到运行在你宿主机上的 VS Code 扩展。CLI 配置为自动在host.docker.internal上找到 IDE 服务器。通常不需要特殊配置，但你可能需要确保你的 Docker 网络设置允许从容器到宿主的连接。

故障排除

如果你遇到 IDE 集成的问题，以下是一些常见的错误信息以及如何解决它们。

连接错误

错误信息

• 消息: 🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Please ensure the extension is running. To install the extension, run /ide install.

  • 原因: Gemini CLI 无法找到必要的环境变量 (GEMINI_CLI_IDE_WORKSPACE_PATH 或 GEMINI_CLI_IDE_SERVER_PORT) 以连接到 IDE。 这通常意味着 IDE 伴侣扩展没有运行或没有正确初始化。
  • 解决方案:
    1. 确保您在 IDE 中安装了 Gemini CLI Companion 扩展，并且已启用。
    2. 在 IDE 中打开一个新的终端窗口以确保它获取正确的环境。

• 消息: 🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable

  • 原因: 与 IDE 伴侣的连接丢失。
  • 解决方案: 运行 /ide enable 尝试重新连接。如果问题持续存在，请打开新的终端窗口或重启您的 IDE。

配置错误

• 消息: 🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name]. Please run the CLI from one of the following directories: [List of directories]

  • 原因: CLI 的当前工作目录在您 IDE 中打开的工作空间之外。
  • 解决方案: 将 CLI cd 到与 IDE 中打开的同一目录，并重启 CLI。

• 消息: 🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.

  • 原因: 您在 IDE 中没有打开任何工作空间。
  • 解决方案: 在 IDE 中打开一个工作空间并重启 CLI。

通用错误

• 消息: IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]

  • 原因: 您在一个不受支持的 IDE 之外的终端或环境中运行 Gemini CLI。
  • 解决方案: 从支持的 IDE（如 Antigravity 或 VS Code）的集成终端运行 Gemini CLI。

• 消息: No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.

  • 原因: 您运行了 /ide install，但 CLI 没有为您的特定 IDE 提供自动安装程序。
  • 解决方案: 打开 IDE 的扩展市场，搜索 “Gemini CLI Companion”，并 手动安装。