IDE 集成

Gemini CLI 可与 IDE 集成，获得更完善的上下文感知体验，并支持在编辑器内查看和接受修改。目前支持的 IDE 为 Visual Studio Code 及兼容 VS Code 扩展的编辑器；若需适配其他 IDE，请参考IDE Companion 扩展规范。

功能

• 工作区上下文：CLI 自动感知工作区信息，提供更准确的响应，包括：
  • 最近访问的 10 个文件；
  • 活动光标位置；
  • 当前选中的文本（最多 16KB，超出部分会被截断）。
• 原生 Diff：当 Gemini 提议修改代码时，可在 IDE 的原生 diff 视图中查看、编辑并接受/拒绝修改。
• VS Code 命令：在命令面板（Cmd+Shift+P / Ctrl+Shift+P）中可直接调用：
  • Gemini CLI: Run
  • Gemini CLI: Accept Diff
  • Gemini CLI: Close Diff Editor
  • Gemini CLI: View Third-Party Notices

安装与设置

集成方式有三种：

1. 自动提示（推荐）：在支持的 IDE 中运行 CLI 时，会检测到环境并提示连接，确认即可自动完成扩展安装与连接。
2. CLI 手动安装：若之前忽略提示，可在 CLI 中执行：

   /ide install

   CLI 会自动安装对应扩展。
3. 从插件市场安装：
   • VS Code 用户：前往 VS Code Marketplace
   • VS Code 分支：扩展也发布在 Open VSX

提示：如搜索结果靠后，可尝试按 “Newly Published” 排序。手动安装后需在 CLI 中执行 /ide enable 激活。

使用

启用 / 禁用

/ide enable   # 启用
/ide disable  # 禁用

启用后，CLI 会尝试与扩展建立连接。

查看状态

/ide status

将显示连接状态及 CLI 已获知的最近文件。

注意：文件列表仅包含工作区内最近访问的 10 个本地文件。

处理 Diff

当请求修改文件时，CLI 可在 IDE 中打开 diff 视图。

接受修改 可通过：

• 点击 diff 编辑器标题栏的 ✔；
• 保存文件（Cmd+S / Ctrl+S）；
• 命令面板执行 Gemini CLI: Accept Diff；
• 在 CLI 提示时输入 yes。

拒绝修改 可通过：

• 点击 diff 编辑器标题栏的 ✖；
• 直接关闭 diff 标签页；
• 命令面板执行 Gemini CLI: Close Diff Editor；
• 在 CLI 中输入 no。

你也可以在 diff 视图中手动调整修改内容。若在 CLI 中选择 “Yes, allow always”，后续修改将自动接受，不再弹出 diff。

与沙箱共用

• macOS：IDE 集成需要网络访问，需使用允许联网的 seatbelt profile。
• Docker/Podman：在容器内运行 CLI 时，仍可连接宿主机上的 VS Code 扩展，CLI 会自动尝试通过 host.docker.internal 访问 IDE，无需额外配置（确保网络允许容器访问宿主即可）。

常见问题

连接错误

• 消息： 🔴 已断开连接：无法连接到 IDE Companion 扩展，请确认扩展已启动；若需安装可执行 /ide install。

  • 原因： 未检测到 GEMINI_CLI_IDE_WORKSPACE_PATH 或 GEMINI_CLI_IDE_SERVER_PORT，通常表示扩展未运行或初始化失败。
  • 解决：
    1. 确认 IDE 中已安装并启用 “Gemini CLI Companion”；
    2. 在 IDE 中打开新的终端窗口以刷新环境变量。

• 消息： 🔴 已断开连接：IDE 连接异常，请运行 /ide enable 重新连接。

  • 原因： 连接意外中断。
  • 解决： 在 CLI 中执行 /ide enable 重新连接，如仍失败可重启 IDE 或终端。

配置错误

• 消息： 🔴 已断开连接：目录不匹配，请在与 IDE 打开项目相同的目录下运行 CLI。

  • 原因： CLI 当前目录与 IDE 工作区目录不一致。
  • 解决： cd 到与 IDE 相同的目录后重启 CLI。

• 消息： 🔴 已断开连接：请先在 IDE 中打开工作区后再尝试。

  • 原因： IDE 中未打开任何工作区。
  • 解决： 在 IDE 中打开项目，再运行 CLI。

其他错误

• 消息： IDE 集成在当前环境不受支持，请在支持的 IDE 集成终端中运行 CLI。

  • 原因： 当前环境不是受支持的 IDE。
  • 解决： 在支持的 IDE 集成终端中运行 CLI。

• 消息： 没有可用的自动安装程序，请前往扩展市场手动安装并按上述步骤启用。

  • 原因： /ide install 不支持当前 IDE 的自动安装。
  • 解决： 前往扩展市场手动安装，并参照上文启用。