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