古法编程

Appearance

Gemini CLI 提供两种 IDE 集成方式：VS Code 伴侣扩展（支持工作区感知、原生 diff）和 ACP 协议（支持 JetBrains、Zed 等编辑器）。安装后 CLI 自动感知你打开的文件和光标位置，AI 建议的代码修改可以直接在编辑器 diff 视图中审查和接受。

Gemini CLI IDE 集成 ​

Gemini CLI 可以与你的 IDE 深度集成，提供更流畅的上下文感知体验。集成后，CLI 能够了解你的工作区状态，并启用在编辑器内直接查看 AI 建议修改的原生 diff 功能。

集成方式有两种：

  1. VS Code 伴侣扩展：在 VS Code 或其他兼容编辑器中安装"Gemini CLI Companion"扩展。
  2. Agent Client Protocol (ACP)：开放协议，用于 JetBrains、Zed 等不使用 VS Code 扩展体系的 IDE，通过 ACP Agent Registry 安装。

VS Code 伴侣扩展 ​

Gemini CLI Companion 扩展让 CLI 直接访问你的 VS Code 工作区，提供实时上下文（当前打开的文件、光标位置、选中文本），并启用原生 diff 界面，让你可以在编辑器中直接审查和应用 AI 建议的代码修改。

功能 ​

  • 工作区上下文感知：CLI 自动获取你的工作区信息，提供更相关、更准确的回答：

    • 最近访问的 10 个文件
    • 当前光标位置
    • 已选中的文本（上限 16KB，超出部分截断）

  • 原生 diff：当 Gemini 建议修改代码时，可以直接在编辑器的原生 diff 视图中查看变更，支持审查、编辑后接受或拒绝。

  • VS Code 命令面板集成（Cmd+Shift+P / Ctrl+Shift+P）：

    • Gemini CLI: Run — 在集成终端启动新 Gemini CLI 会话
    • Gemini CLI: Accept Diff — 接受当前 diff 编辑器中的修改
    • Gemini CLI: Close Diff Editor — 拒绝修改并关闭 diff 编辑器
    • Gemini CLI: View Third-Party Notices — 查看第三方声明

安装方式 ​

方式一：自动提示（推荐） ​

在支持的编辑器中运行 Gemini CLI，CLI 会自动检测到编辑器环境并提示连接。回答"是"即可自动完成安装和激活。

方式二：CLI 命令手动安装 ​

如果你曾经跳过了自动提示，可以在 Gemini CLI 内运行：

/ide install

CLI 会自动找到适配你编辑器的扩展并安装。

方式三：从应用商店手动安装 ​

注意："Gemini CLI Companion"扩展可能出现在搜索结果靠后的位置，可以尝试按"最新发布"排序。

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

使用方法 ​

启用与禁用 ​

/ide enable      # 连接到 IDE 伴侣扩展
/ide disable     # 断开连接

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

检查连接状态 ​

/ide status

已连接时，会显示当前连接的 IDE 名称以及 CLI 感知到的最近打开文件列表（限 10 个本地文件）。

使用 diff 工作流 ​

当 Gemini 建议修改文件时，会直接在编辑器中打开 diff 视图。

接受修改，可以：

  • 点击 diff 编辑器标题栏的对勾图标
  • 保存文件（Cmd+S / Ctrl+S）
  • 在命令面板运行 Gemini CLI: Accept Diff
  • 在 CLI 中回答 yes

拒绝修改，可以：

  • 点击标题栏的 × 图标
  • 关闭 diff 编辑器标签页
  • 在命令面板运行 Gemini CLI: Close Diff Editor
  • 在 CLI 中回答 no

也可以在 diff 视图中直接编辑 Gemini 的建议，再决定是否接受。

如果在 CLI 中选择了"在本次会话内允许"，后续修改将自动接受，不再弹出 diff 视图。

Agent Client Protocol (ACP) ​

ACP 是一个开放协议，规范了 AI 编程代理与代码编辑器之间的通信方式。它解决了过去每个代理需要为每个 IDE 分别开发集成插件的碎片化问题——实现了 ACP 的代理可以与任何支持 ACP 的编辑器兼容。

Gemini CLI 已收录在 ACP Agent Registry 中，可以通过支持 ACP 的 IDE 直接安装，无需手动下载或安装针对特定 IDE 的扩展。

Registry 的好处：

  • 便捷安装：直接在 IDE 设置中发现并安装代理
  • 自动更新：始终获取最新版本

各 IDE 集成情况 ​

JetBrains（IntelliJ IDEA / PyCharm / GoLand 等） ​

JetBrains IDE 内置了 Registry 支持，可直接搜索并安装 ACP 兼容代理。详见 JetBrains AI Blog 公告。

Zed ​

Zed 编辑器也集成了 ACP Agent Registry，用户可以直接浏览、安装和管理 ACP 代理。详见 Zed 博客文章。

其他 ACP 兼容编辑器 ​

任何支持 ACP Agent Registry 的 IDE 都可以通过其内置 Registry 功能直接安装 Gemini CLI。

在沙箱中使用 IDE 集成 ​

  • macOS：IDE 集成需要网络访问权限（用于与伴侣扩展通信）。须使用允许网络访问的 Seatbelt profile。
  • Docker 容器：在 Docker（或 Podman）容器中运行 Gemini CLI 时，IDE 集成仍然可以连接宿主机上的 VS Code 扩展。CLI 会自动通过 host.docker.internal 查找 IDE 服务。通常无需额外配置，但要确保 Docker 网络设置允许容器连接到宿主机。

故障排查 ​

VS Code 伴侣扩展错误 ​

连接错误 ​

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

  • 原因：CLI 找不到 GEMINI_CLI_IDE_WORKSPACE_PATH 或 GEMINI_CLI_IDE_SERVER_PORT 环境变量，通常说明伴侣扩展未运行或初始化失败。
  • 解决：确认 Gemini CLI Companion 扩展已安装并启用；在 IDE 中重新打开终端窗口。

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

  • 原因：连接意外断开。
  • 解决：运行 /ide enable 重新连接；若持续出现，重新打开终端或重启 IDE。

手动指定 IDE 进程 PID ​

自动 IDE 检测失败时（或在独立终端中运行 CLI 并想手动关联某个 IDE 实例时），可设置 GEMINI_CLI_IDE_PID 环境变量为目标 IDE 的进程 ID：

bash
# macOS/Linux
export GEMINI_CLI_IDE_PID=12345
powershell
# Windows (PowerShell)
$env:GEMINI_CLI_IDE_PID=12345

设置后，CLI 会跳过自动检测，直接尝试使用指定 PID 连接。

配置错误 ​

错误：🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name].

  • 原因：CLI 当前工作目录不在 IDE 打开的工作区内。
  • 解决：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.

  • 原因：在不支持的终端或环境中运行 CLI。
  • 解决：在 VS Code 等支持的 IDE 的集成终端中运行 Gemini CLI。

错误：No installer is available for IDE. Please install Gemini CLI Companion extension manually from the marketplace.

  • 原因：运行了 /ide install，但 CLI 没有针对你的 IDE 的自动安装程序。
  • 解决：在 IDE 的应用商店搜索"Gemini CLI Companion"手动安装。

ACP 集成错误 ​

ACP 集成的调试和遥测相关问题，参见 ACP 模式文档。

常见问题 ​

Q: VS Code 伴侣扩展和 ACP 模式有什么区别？

A: VS Code 伴侣扩展专为 VS Code 及其衍生编辑器设计，提供工作区感知和原生 diff 功能；ACP 模式是通用协议，适用于 JetBrains、Zed 等不基于 VS Code 的编辑器。两者都能让 Gemini CLI 与 IDE 集成，但机制不同。

Q: 使用 IDE 集成后，Gemini 会自动知道我在看哪个文件吗？

A: 是的。启用集成后，CLI 会自动感知你最近访问的 10 个文件以及当前光标位置，无需每次手动用 @ 引入文件。

Q: 在 Docker 容器里用 Gemini CLI 能连接宿主机上的 VS Code 吗？

A: 可以。CLI 会自动通过 host.docker.internal 查找 IDE 伴侣扩展，一般无需额外配置，确保 Docker 网络允许容器访问宿主机即可。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策