---
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="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/71-hooks" />
  <Card title="ACP mode" description="需要協議級 IDE / client 整合時，回看 ACP mode。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/55-acp-mode" />
  <Card title="檔案系統工具" description="IDE diff 仍然來自檔案工具寫入，回看讀寫邊界。" href="/zh-Hant/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)
