ACP mode

ACP mode 是 Gemini CLI 面向 IDE 和開發者工具整合的協議模式。官方文件使用 --acp 啟動，底層透過 stdio 上的 JSON-RPC 2.0 讓外部 client 控制 Gemini CLI agent。

它建立的是 client-server 關係：IDE 或自研工具是 client，Gemini CLI 是 server。所有通訊走 stdin/stdout，而不是普通互動式 TUI。

使用方式

gemini --acp

適合場景

• 編輯器整合測試。
• agent protocol 實驗。
• 工具鏈開發者。
• 自研 client 需要透過標準協議控制 Gemini CLI。
• IDE 想透過自己的 MCP server 暴露工具給 Gemini CLI。

不適合場景

• 第一次上手 Gemini CLI。
• 課程教程的預設路徑。
• 團隊穩定生產流程。

協議機制

ACP 建立的是 client-server 關係：你的 IDE 或工具是 client，Gemini CLI 是 server。client 傳送 initialize、authenticate、newSession、prompt、cancel 等 JSON-RPC 請求；Gemini CLI 處理後返回結果或通知。

ACP 可以和 MCP 配合：ACP client 在初始化時提供 MCP server 連線資訊，Gemini CLI 連線這個 MCP server 後，把 IDE 暴露的能力當作工具給模型使用。這樣 IDE 既能控制 agent，也能把自己的檔案、編輯、診斷能力暴露給 agent。

安全邊界

ACP 包含 proxied file system service。也就是說，agent 讀寫檔案時透過 ACP client 代理執行，訪問範圍應由 client 和使用者明確授權。工具鏈開發者不能把它當成本機無限制檔案訪問。

除錯方式

普通協議除錯可以加 --debug：

gemini --acp --debug

這類除錯日誌可能包含協議訊息、檔案路徑和會話狀態。真實專案排障時要先確認日誌儲存位置和脫敏方式，不要把 ACP debug 日誌直接貼到公開 issue。

需要記錄詳細事件時，可以開啟本地 telemetry：

GEMINI_TELEMETRY_ENABLED=true
GEMINI_TELEMETRY_TARGET=local
GEMINI_TELEMETRY_OUTFILE=/path/to/acp-log.json

驗收方式

先用最小 client 完成 initialize 和一輪 prompt，再測試 cancel、session mode 和檔案系統代理。不要一開始接入真實 IDE 寫操作；先用只讀目錄和臨時測試專案驗證協議訊息、許可權邊界和日誌。

最小測試順序

ACP 整合不要一開始接入完整 IDE。建議按這個順序推進：

1. gemini --acp --debug 能穩定啟動。
2. client 能完成 initialize。
3. client 能發起一個只讀 prompt。
4. cancel 能中止長任務。
5. 檔案系統代理只允許測試目錄。
6. telemetry 日誌不包含 token、私有路徑或客戶資料。

這條路徑能先驗證協議，再驗證許可權，最後才驗證真實編輯器體驗。

不要用 ACP 解決什麼

如果只是想在指令碼里呼叫 Gemini CLI，用 headless mode；如果只是想接外部服務，用 MCP；如果只是想讓 IDE 開啟終端執行命令，用普通 CLI 就夠。ACP 的價值在於讓 client 透過協議控制會話、許可權和檔案代理，不是替代所有自動化入口。

因此教程裡的推薦順序應該是：普通 CLI、headless、MCP、IDE integration，最後才是 ACP。只有當你要開發 editor/client 整合時，ACP 才是主角。

接下來去哪

官方來源

• Gemini CLI ACP mode
• Agent Client Protocol