IDE 集成

Gemini CLI 可以与你的 IDE 集成，提供更无缝和上下文感知的体验。此集成允许 CLI 更好地理解你的工作区，并启用强大的功能，如原生编辑器内差异对比。

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

功能

• 工作区上下文： CLI 自动获得对你工作区的感知，以提供更相关和准确的响应。此上下文包括：

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

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

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

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

安装和设置

有三种设置 IDE 集成的方式：

1. 自动提示（推荐）

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

2. 从 CLI 手动安装

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

/ide install

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

3. 从市场手动安装

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

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

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

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

使用

启用和禁用

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

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

  /ide enable

• 要禁用连接，运行：

  /ide disable

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

检查状态

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

/ide status

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

文件列表限于工作区中最近访问的 10 个文件，仅包括磁盘上的本地文件。

使用差异

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

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

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

要拒绝差异，你可以：

• 点击差异编辑器标题栏中的 'x' 图标。
• 关闭差异编辑器标签。
• 打开命令面板并运行 Gemini CLI: Close Diff Editor。
• 在 CLI 中提示时回复 no。

你也可以在接受之前直接在差异视图中修改建议的更改。

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

与沙箱一起使用

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

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

故障排除

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

连接错误

• 消息：🔴 已断开连接：无法连接到 [IDE 名称] 中的 IDE 伴侣扩展。请确保扩展正在运行。要安装扩展，运行 /ide install。

  • 原因： Gemini CLI 找不到连接到 IDE 所需的环境变量（GEMINI_CLI_IDE_WORKSPACE_PATH 或 GEMINI_CLI_IDE_SERVER_PORT）。这通常意味着 IDE 伴侣扩展未运行或未正确初始化。
  • 解决方案：
    1. 确保你已在 IDE 中安装了 Gemini CLI Companion 扩展并且它已启用。
    2. 在 IDE 中打开新的终端窗口以确保它获取正确的环境。

• 消息：🔴 已断开连接：IDE 连接错误。连接意外丢失。请尝试通过运行 /ide enable 重新连接

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

配置错误

• 消息：🔴 已断开连接：目录不匹配。Gemini CLI 运行在与 [IDE 名称] 中打开的工作区不同的位置。请从以下目录之一运行 CLI：[目录列表]

  • 原因： CLI 的当前工作目录在你在 IDE 中打开的工作区之外。
  • 解决方案： cd 到 IDE 中打开的同一目录并重启 CLI。

• 消息：🔴 已断开连接：要使用此功能，请在 [IDE 名称] 中打开工作区文件夹并重试。

  • 原因： 你的 IDE 中没有打开工作区。
  • 解决方案： 在 IDE 中打开工作区并重启 CLI。

一般错误

• 消息：当前环境不支持 IDE 集成。要使用此功能，请在以下支持的 IDE 之一中运行 Gemini CLI：[IDE 列表]

  • 原因： 你在不是支持的 IDE 的终端或环境中运行 Gemini CLI。
  • 解决方案： 从支持的 IDE（如 Antigravity 或 VS Code）的集成终端运行 Gemini CLI。

• 消息：IDE 没有可用的安装程序。请从市场手动安装 Gemini CLI Companion 扩展。

  • 原因： 你运行了 /ide install，但 CLI 没有针对你特定 IDE 的自动安装程序。
  • 解决方案： 打开 IDE 的扩展市场，搜索"Gemini CLI Companion"，并手动安装。