Skip to content

IDE 集成

¥IDE Integration

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

¥Gemini CLI can integrate with your IDE to provide a more seamless and context-aware experience. This integration allows the CLI to understand your workspace better and enables powerful features like native in-editor diffing.

目前唯一支持的 IDE 是Visual Studio 代码以及其他支持 VS Code 扩展的编辑器。

¥Currently, the only supported IDE is Visual Studio Code and other editors that support VS Code extensions.

特征

¥Features

  • 工作区上下文：CLI 会自动感知您的工作区，以提供更相关、更准确的响应。这些上下文包括：

    ¥Workspace Context: The CLI automatically gains awareness of your workspace to provide more relevant and accurate responses. This context includes:

  • 这最近访问的 10 个文件在您的工作区中。

    ¥The 10 most recently accessed files in your workspace.

  • 您的活动光标位置。

    ¥Your active cursor position.

  • 您选择的任何文本（最大限制为 16KB；超过该限制的选择将被截断）。

    ¥Any text you have selected (up to a 16KB limit; longer selections will be truncated).

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

    ¥Native Diffing: When Gemini suggests code modifications, you can view the changes directly within your IDE's native diff viewer. This allows you to review, edit, and accept or reject the suggested changes seamlessly.

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

    ¥VS Code Commands: You can access Gemini CLI features directly from the VS Code Command Palette (Cmd+Shift+P or Ctrl+Shift+P):

  • Gemini CLI: Run：在集成终端中启动新的 Gemini CLI 会话。

    ¥Gemini CLI: Run: Starts a new Gemini CLI session in the integrated terminal.

  • Gemini CLI: Accept Diff：接受活动差异编辑器中的更改。

    ¥Gemini CLI: Accept Diff: Accepts the changes in the active diff editor.

  • Gemini CLI: Close Diff Editor：拒绝更改并关闭活动的差异编辑器。

    ¥Gemini CLI: Close Diff Editor: Rejects the changes and closes the active diff editor.

  • Gemini CLI: View Third-Party Notices：显示扩展的第三方通知。

    ¥Gemini CLI: View Third-Party Notices: Displays the third-party notices for the extension.

安装和设置

¥Installation and Setup

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

¥There are three ways to set up the IDE integration:

¥1. Automatic Nudge (Recommended)

当您在受支持的编辑器中运行 Gemini CLI 时，它会自动检测您的环境并提示您进行连接。回答“是”将自动运行必要的设置，包括安装配套扩展程序并启用连接。

¥When you run Gemini CLI inside a supported editor, it will automatically detect your environment and prompt you to connect. Answering "Yes" will automatically run the necessary setup, which includes installing the companion extension and enabling the connection.

2. 从 CLI 手动安装

¥2. Manual Installation from CLI

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

¥If you previously dismissed the prompt or want to install the extension manually, you can run the following command inside Gemini CLI:

/ide install

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

¥This will find the correct extension for your IDE and install it.

3. 从市场手动安装

¥3. Manual Installation from a Marketplace

您也可以直接从市场安装扩展程序。

¥You can also install the extension directly from a marketplace.

  • 对于 Visual Studio Code：从安装VS Code 市场。

    ¥For Visual Studio Code: Install from the VS Code Marketplace.

  • 对于 VS Code Forks：为了支持 VS Code 的分支，该扩展也发布在打开 VSX 注册表. 按照编辑器的说明从此注册表安装扩展。

    ¥For VS Code Forks: To support forks of VS Code, the extension is also published on the Open VSX Registry. Follow your editor's instructions for installing extensions from this registry.

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

¥NOTE: The "Gemini CLI Companion" extension may appear towards the bottom of search results. If you don't see it immediately, try scrolling down or sorting by "Newly Published".

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

¥After manually installing the extension, you must run /ide enable in the CLI to activate the integration.

用法

¥Usage

启用和禁用

¥Enabling and Disabling

您可以从 CLI 内部控制 IDE 集成：

¥You can control the IDE integration from within the CLI:

  • 要启用与 IDE 的连接，请运行：/ide enable

    ¥To enable the connection to the IDE, run: /ide enable

  • 要禁用连接，请运行：/ide disable

    ¥To disable the connection, run: /ide disable

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

¥When enabled, Gemini CLI will automatically attempt to connect to the IDE companion extension.

检查状态

¥Checking the Status

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

¥To check the connection status and see the context the CLI has received from the IDE, run:

/ide status

如果已连接，此命令将显示其连接到的 IDE 以及它知道的最近打开的文件列表。

¥If connected, this command will show the IDE it's connected to and a list of recently opened files it is aware of.

（注意：文件列表仅限于工作区内最近访问的 10 个文件，并且仅包含磁盘上的本地文件。）

¥(Note: The file list is limited to 10 recently accessed files within your workspace and only includes local files on disk.)

使用差异

¥Working with Diffs

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

¥When you ask Gemini to modify a file, it can open a diff view directly in your editor.

接受差异，您可以执行以下任一操作：

¥To accept a diff, you can perform any of the following actions:

  • 点击复选标记图标在差异编辑器的标题栏中。

    ¥Click the checkmark icon in the diff editor's title bar.

  • 保存文件（例如，使用Cmd+S或者Ctrl+S）。

    ¥Save the file (e.g., with Cmd+S or Ctrl+S).

  • 打开命令面板并运行Gemini CLI：接受差异。

    ¥Open the Command Palette and run Gemini CLI: Accept Diff.

  • 回复yes在出现提示时在 CLI 中。

    ¥Respond with yes in the CLI when prompted.

拒绝 diff， 你可以：

¥To reject a diff, you can:

  • 点击“x”图标在差异编辑器的标题栏中。

    ¥Click the 'x' icon in the diff editor's title bar.

  • 关闭差异编辑器选项卡。

    ¥Close the diff editor tab.

  • 打开命令面板并运行Gemini CLI：关闭差异编辑器。

    ¥Open the Command Palette and run Gemini CLI: Close Diff Editor.

  • 回复no在出现提示时在 CLI 中。

    ¥Respond with no in the CLI when prompted.

您还可以修改建议的更改在接受它们之前直接在差异视图中查看。

¥You can also modify the suggested changes directly in the diff view before accepting them.

如果您在 CLI 中选择“是，始终允许”，则更改将不再显示在 IDE 中，因为它们将被自动接受。

¥If you select ‘Yes, allow always’ in the CLI, changes will no longer show up in the IDE as they will be auto-accepted.

与沙盒一起使用

¥Using with Sandboxing

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

¥If you are using Gemini CLI within a sandbox, please be aware of the following:

  • 在 macOS 上：IDE 集成需要网络访问权限才能与 IDE 配套扩展程序进行通信。您必须使用允许网络访问权限的 Seatbelt 配置文件。

    ¥On macOS: The IDE integration requires network access to communicate with the IDE companion extension. You must use a Seatbelt profile that allows network access.

  • 在 Docker 容器中：如果您在 Docker（或 Podman）容器中运行 Gemini CLI，IDE 集成仍然可以连接到主机上运行的 VS Code 扩展。CLI 已配置为自动查找 IDE 服务器host.docker.internal。通常不需要特殊配置，但您可能需要确保您的 Docker 网络设置允许从容器到主机的连接。

    ¥In a Docker Container: If you run Gemini CLI inside a Docker (or Podman) container, the IDE integration can still connect to the VS Code extension running on your host machine. The CLI is configured to automatically find the IDE server on host.docker.internal. No special configuration is usually required, but you may need to ensure your Docker networking setup allows connections from the container to the host.

故障排除

¥Troubleshooting

如果您遇到 IDE 集成问题，以下是一些常见的错误消息及其解决方法。

¥If you encounter issues with IDE integration, here are some common error messages and how to resolve them.

连接错误

¥Connection Errors

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

    ¥Message:🔴 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 配套扩展未运行或未正确初始化。

    ¥Cause: Gemini CLI could not find the necessary environment variables (GEMINI_CLI_IDE_WORKSPACE_PATH or GEMINI_CLI_IDE_SERVER_PORT) to connect to the IDE. This usually means the IDE companion extension is not running or did not initialize correctly.

  • 解决方案：

    ¥Solution:

    1. 确保你已经安装了Gemini CLI 伴侣扩展已在您的 IDE 中启用。

      ¥Make sure you have installed the Gemini CLI Companion extension in your IDE and that it is enabled.

    2. 在 IDE 中打开一个新的终端窗口，以确保它选择正确的环境。

      ¥Open a new terminal window in your IDE to ensure it picks up the correct environment.

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

    ¥Message: 🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable

  • 原因：与 IDE 配套设备的连接丢失。

    ¥Cause: The connection to the IDE companion was lost.

  • 解决方案：跑步/ide enable尝试重新连接。如果问题仍然存在，请打开一个新的终端窗口或重启 IDE。

    ¥Solution: Run /ide enable to try and reconnect. If the issue continues, open a new terminal window or restart your IDE.

配置错误

¥Configuration Errors

  • 信息： 🔴 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]

    ¥Message:🔴 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 中打开的工作区之外。

    ¥Cause: The CLI's current working directory is outside the workspace you have open in your IDE.

  • 解决方案： cd进入 IDE 中打开的同一目录并重新启动 CLI。

    ¥Solution: cd into the same directory that is open in your IDE and restart the CLI.

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

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

  • 原因：您的 IDE 中没有打开工作区。

    ¥Cause: You have no workspace open in your IDE.

  • 解决方案：在 IDE 中打开一个工作区并重新启动 CLI。

    ¥Solution: Open a workspace in your IDE and restart the CLI.

一般错误

¥General Errors

  • 信息： 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]

    ¥Message: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。

    ¥Cause: You are running Gemini CLI in a terminal or environment that is not a supported IDE.

  • 解决方案：从受支持的 IDE（如 VS Code）的集成终端运行 Gemini CLI。

    ¥Solution: Run Gemini CLI from the integrated terminal of a supported IDE, like VS Code.

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

    ¥Message: No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.

  • 原因：你跑了/ide install，但 CLI 没有针对您的特定 IDE 的自动安装程序。

    ¥Cause: You ran /ide install, but the CLI does not have an automated installer for your specific IDE.

  • 解决方案：打开 IDE 的扩展市场，搜索“Gemini CLI Companion”，然后手动安装。

    ¥Solution: Open your IDE's extension marketplace, search for "Gemini CLI Companion", and install it manually.