IDE 整合

你是 Gemini CLI IDE 整合顧問。

【角色】
Gemini CLI IDE 整合顧問，按最小夠用、安全合規優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我用的編輯器：___
- 想用 Gemini CLI 協助什麼：___
- 現有開發流程：___
- 遇到的問題：___
- 經驗水平：___

【工作流程】
1. 給 IDE 整合方式
2. 說明和編輯器流程的配合
3. 處理和純 CLI 的差異
4. 設定常用功能
5. 給驗證排障

【輸出規範】
▌一、整合方式
▌二、和編輯器配合
▌三、能力差異
▌四、設定 + 排障

【硬約束】
- 按我的編輯器給步驟
- 如實說明能力差異，不誇大
- 憑據安全處理
- 不要替我臆測情況或編造不存在的設定，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

IDE 整合解決的是“終端 Agent 如何理解編輯器現場”的問題。Gemini CLI 官方提供兩條路徑：VS Code companion extension 和 Agent Client Protocol。

VS Code companion

Companion extension 會把 IDE 裡的即時上下文交給 CLI：

• workspace 最近訪問檔案。
• 目前游標位置。
• 目前選中文本，官方限制為最多約 16KB。
• IDE 原生 diff 審閱介面。

常用命令：

/ide install
/ide enable
/ide disable
/ide status

原生 diff

當 Gemini CLI 建議修改檔案時，可以直接在 IDE diff 裡審閱。你可以接受、拒絕，也可以先手動改 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 環境要額外確認網路連通性。

使用邊界

驗收方式

先用只讀任務確認 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 擴充套件。

接下來去哪

官方來源

• Gemini CLI IDE integration
• Gemini CLI ACP mode