---
title: "IDE 集成"
description: "Gemini CLI IDE 集成：VS Code companion extension、/ide 命令、原生 diff、ACP 与 JetBrains/Zed 这类 ACP 客户端。"
verifiedAt: "2026-05-09"
---

IDE 集成解决的是“终端 Agent 如何理解编辑器现场”的问题。Gemini CLI 官方提供两条路径：VS Code companion extension 和 Agent Client Protocol。

> [!NOTE]
> IDE 集成提升上下文感知和 diff 审阅体验，但不会替代 `git diff`、测试和人工 review。

## VS Code companion

Companion extension 会把 IDE 里的实时上下文交给 CLI：

- workspace 最近访问文件。
- 当前光标位置。
- 当前选中文本，官方限制为最多约 16KB。
- IDE 原生 diff 审阅界面。

常用命令：

```text
/ide install
/ide enable
/ide disable
/ide status
```

## 原生 diff

当 Gemini CLI 建议修改文件时，可以直接在 IDE diff 里审阅。你可以接受、拒绝，也可以先手动改 diff 再接受。

> [!NOTE]
> 如果在 CLI 里选择本轮自动允许变更，后续变更可能不再弹出 IDE diff，需要按团队风险偏好配置。

## ACP

Agent Client Protocol 是面向 IDE 与 AI coding agent 的互操作协议。Gemini CLI 可作为 ACP agent，被支持 ACP registry 的 IDE 发现和安装。

适合 ACP 的场景：

- 使用 JetBrains、Zed 或其他 ACP 兼容编辑器。
- 不想为每个 IDE 单独维护插件。
- 希望 agent 分发和升级更标准化。

## 上下文限制

IDE 集成给的是编辑器现场，不是完整项目真相。最近访问文件、光标位置和选区只能帮助 Gemini CLI 理解你当前正在看什么，不能替代它重新读取相关代码、配置和测试。复杂任务仍然要让它显式列出会读取哪些文件。

原生 diff 也只是审阅体验，不是质量保证。接受 diff 前还要确认文件范围、运行测试，并检查是否覆盖了 IDE 当前没打开的相关文件。

## Sandbox 注意点

如果 Gemini CLI 运行在 sandbox 中，IDE 集成还需要能访问 IDE companion。macOS Seatbelt、Docker 或 Podman 环境要额外确认网络连通性。

## 使用边界

| 场景 | 推荐路径 |
| --- | --- |
| VS Code / Antigravity | Companion extension + `/ide` |
| JetBrains / Zed | ACP 集成 |
| 只想跑终端命令 | 普通 CLI |
| 需要脚本自动化 | Headless mode |
| 高风险改动 | IDE diff + 测试 + Git review |

## 验收方式

先用只读任务确认 CLI 能看到当前 workspace 和最近文件，再让它提出一个小 diff，确认 IDE 原生 diff 能展示、拒绝和接受都正常。sandbox 或容器中运行时，还要确认 companion 连接不会因为网络隔离失败。

再做一次负例：关闭 IDE integration 后，让 CLI 处理同一任务，确认它不会误以为仍能读取编辑器选区。这样可以区分“项目文件上下文”和“IDE 实时上下文”。

团队教程里建议把 IDE 集成作为增强体验，而不是唯一操作路径。读者没有对应 IDE 时，仍应能用纯 CLI 完成同一任务。

截图应标注 IDE、扩展版本和 Gemini CLI 版本，便于复查。VS Code、Open VSX、JetBrains/Zed 这类入口差异很大，教程不能只写“打开 IDE 集成”。

如果 CLI 不在已打开的 IDE workspace 内运行，可能出现 workspace mismatch 或无法使用 IDE context 的错误。排错时先确认 CLI cwd 和 IDE 打开的目录一致。

## 常见排错

IDE 集成失败时，先查 companion 是否安装，再查 `/ide status`，最后查 workspace 路径。不要先怀疑模型能力。容器和 sandbox 场景还要看网络访问，Docker 中通常需要能访问宿主 IDE 扩展。

## 接下来去哪

<Cards>
  <Card title="Hooks" description="IDE 集成之后，继续看 lifecycle hooks、JSON I/O 和阻断机制。" href="/docs/gemini-cli/official/07-integrations-automation/71-hooks" />
  <Card title="ACP mode" description="需要协议级 IDE / client 集成时，回看 ACP mode。" href="/docs/gemini-cli/official/05-models-runtime/55-acp-mode" />
  <Card title="文件系统工具" description="IDE diff 仍然来自文件工具写入，回看读写边界。" href="/docs/gemini-cli/official/03-tools-mcp/31-file-system-tool" />
</Cards>

## 官方来源

- [Gemini CLI IDE integration](https://github.com/google-gemini/gemini-cli/blob/main/docs/ide-integration/index.md)
- [Gemini CLI ACP mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md)
