ACP mode
Gemini CLI ACP mode 的定位：實驗性 agent/editor 協議模式、適用場景和風險邊界。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| ACP mode | 協議模式 | Agent Client Protocol 接入模式。 |
| 客戶端整合 | integration | 用 ACP 接進其它客戶端。 |
| 邊界 | scope | ACP 暴露和限制什麼。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你判斷要不要用 ACP mode 接入、怎麼整合。
你是 Gemini CLI ACP 整合顧問。
【角色】
Gemini CLI ACP 整合顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 想透過 ACP 實現的整合：___
- 是否有更簡單方式替代：___
- 涉及的許可權和系統：___
- 目標是原型還是生產：___
- 經驗水平：___
【工作流程】
1. 判斷是否真需要 ACP
2. 說明 ACP 暴露什麼、怎麼接
3. 給最小整合方案
4. 強調邊界和安全
5. 給驗證
【輸出規範】
▌一、是否需要 ACP
▌二、能力與接法
▌三、最小整合方案
▌四、邊界 + 驗證
【硬約束】
- 簡單場景優先更輕的方式
- 整合傳清邊界
- 涉及寫許可權 / 生產預設收緊
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法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。
ACP mode 面向 IDE / client 整合開發者，不是普通使用者日常啟動方式。日常自動化優先看 headless mode。
使用方式
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 和使用者明確授權。工具鏈開發者不能把它當成本機無限制檔案訪問。
| 能力 | ACP 中的邊界 |
|---|---|
| 檔案讀寫 | 透過 client 代理，client 應控制範圍 |
| Session | client 建立、載入、取消會話 |
| 模型 | session 內可切換，但仍受賬號可用性影響 |
| MCP | client 可在 initialize 時提供 MCP server |
| Telemetry | 本地記錄可能包含協議訊息和路徑 |
除錯方式
普通協議除錯可以加 --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。建議按這個順序推進：
gemini --acp --debug能穩定啟動。- client 能完成
initialize。 - client 能發起一個只讀
prompt。 cancel能中止長任務。- 檔案系統代理只允許測試目錄。
- telemetry 記錄不包含 token、私有路徑或客戶資料。
這條路徑能先驗證協議，再驗證許可權，最後才驗證真實編輯器體驗。
不要用 ACP 解決什麼
如果只是想在指令碼里呼叫 Gemini CLI，用 headless mode；如果只是想接外部服務，用 MCP；如果只是想讓 IDE 開啟終端執行命令，用普通 CLI 就夠。ACP 的價值在於讓 client 透過協議控制會話、許可權和檔案代理，不是替代所有自動化入口。
因此教學裡的推薦順序應該是：普通 CLI、headless、MCP、IDE integration，最後才是 ACP。只有當你要開發 editor/client 整合時，ACP 才是主角。
接下來去哪
安全與企業
模型執行時結束後，繼續看 sandbox、policy、enterprise config 和隱私邊界。
Headless mode
如果只是指令碼或 CI 自動化，優先看 headless mode。
MCP 設定
ACP client 暴露 MCP 能力時，仍要遵守 MCP 最小許可權。