手把手教你把 Gemini CLI 塞进 IntelliJ IDEA：ACP 集成指南

🎯 先说人话：这玩意儿能干啥？

想象一下这个场景：

你正在 IDEA 里疯狂敲代码，突然卡壳了。以前你得：切终端 → 打开 Gemini CLI → 复制代码 → 粘贴 → 等回复 → 再切回 IDEA。
现在？直接在 AI Assistant 聊天框里@Gemini，它就能看懂你的项目、帮你改代码、甚至跑终端命令！✨

这就是 Agent Client Protocol (ACP) 的魔法：让外部 AI 代理（比如 Gemini CLI）直接"住进"你的 IDE，无缝协作。

📋 前置条件（别跳过，否则踩坑别怪我）

要求	说明	检查命令
IntelliJ IDEA	2025.3 或更新版本（其他 JetBrains 全家桶也行）	`Help → About`
Node.js	建议 20+ 版本，Gemini CLI 的"粮食"	`node --version`
Gemini CLI	主角登场，必须先装好	`gemini --version`

🔧 四步走，集成搞定！

Step 1️⃣：安装 Gemini CLI（如果还没装）

npm install -g @google/gemini-cli

装完验货：

gemini --version
# 看到版本号？恭喜，第一步拿下！✅

💡 小贴士：如果权限报错，试试加 sudo（Mac/Linux）或用管理员身份运行终端（Windows）。

Step 2️⃣：找到 gemini 可执行文件的"真实住址"

ACP 配置需要绝对路径，不能玩"我以为你知道"的游戏。

🍎 macOS / 🐧 Linux 用户：

which gemini
# 示例输出：/Users/yourname/.nvm/versions/node/v22.16.0/bin/gemini

🪟 Windows 用户：

where gemini
# 示例输出：C:\Program Files\nodejs\gemini.cmd

⚠️ 重点：把这个路径复制好，马上要用！如果用 nvm，确保路径指向当前激活的 Node 版本，不然 IDEA 会一脸懵："这文件呢？"

Step 3️⃣：配置 ACP 的"户口本" —— `acp.json`

JetBrains IDE 会去固定位置找这个配置文件：

系统	文件路径
macOS / Linux	`~/.jetbrains/acp.json`
Windows	`%USERPROFILE%\.jetbrains\acp.json`

新建或编辑文件，填入以下内容（记得替换 command 里的路径！）：

{
  "agent_servers": {
    "Gemini CLI": {
      "command": "/你的/实际/路径/gemini",
      "args": [
        "--experimental-acp"
      ],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}

🔍 配置项逐行解读：

字段	作用	为什么重要
`"Gemini CLI"`	在 IDEA 里显示的名字	随便起，但建议别叫"那个谁"😅
`"command"`	gemini 可执行文件路径	填错=找不到人，直接罢工
`"args"`	启动参数	`--experimental-acp` 是关键！没它 Gemini 会以为你要开终端聊天
`"use_idea_mcp": true`	允许访问 IDEA 内置 MCP 服务	✨核心功能！让 Gemini 能读你的项目结构、打开的文件
`"use_custom_mcp": true`	支持自定义 MCP 服务	扩展玩法，比如连数据库、调用外部 API

🤔 深度思考：为什么叫 experimental？
因为 ACP 协议还在演进中，未来可能有 breaking changes。生产环境使用建议先在小项目试水，别一上来就让它重构核心模块（血泪教训预警⚠️）。

Step 4️⃣：重启 IDEA，召唤 Gemini！

重启 IntelliJ IDEA（配置生效的仪式感）
打开 AI Assistant 面板（通常在右侧工具栏）
找到 Agent 选择器（下拉菜单或 ⋯ 更多按钮）
选择 "Gemini CLI"

picture.image

🎉 看到聊天框里出现 Gemini CLI 标识？恭喜，集成成功！

📦 附：一键配置脚本（懒人福利）

macOS / Linux 用户，复制粘贴这条命令，自动创建 acp.json（记得先改路径！）：

mkdir -p ~/.jetbrains && cat > ~/.jetbrains/acp.json << 'EOF'
{
  "agent_servers": {
    "Gemini CLI": {
      "command": "$(which gemini)",
      "args": ["--experimental-acp"],
      "use_idea_mcp": true,
      "use_custom_mcp": true
    }
  }
}
EOF