# claude-code-idea-plugin

**Repository Path**: mashiro520/claude-code-idea-plugin

## Basic Information

- **Project Name**: claude-code-idea-plugin
- **Description**: Claude Code — 在 JetBrains IDE 中嵌入 Claude AI 编程助手
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code IDEA Plugin

> 在 JetBrains IDE 中嵌入 Claude Code CLI，支持多供应商配置切换、MCP 服务管理、内置代理，对接阿里百炼 / OpenRouter / DeepSeek / Anthropic 官方等任意 Anthropic 兼容供应商。

## ✨ 功能特性

- 🤖 **嵌入 Claude Code CLI**：直接在 IDE 工具窗口中使用 Claude Code，复用 PTY 完整还原终端体验（颜色、菜单、进度条）
- 🔄 **多配置档案**：保存任意多份供应商配置，一键切换启用，无需手动改环境变量
- 🌐 **多供应商支持**：Anthropic 官方、阿里百炼、OpenRouter、DeepSeek、自建网关...任何 Anthropic 兼容协议
- 🔌 **MCP 服务管理**：可视化管理 MCP（Model Context Protocol）服务，自动健康检查
- 🚀 **内置 HTTP 代理**：解决 CLI Bun runtime 的 HTTP/1.0 兼容性问题，支持模型名映射
- 🎯 **智能模型映射**：自动将 CLI 内部 `claude-haiku/sonnet/opus` 别名映射到供应商真实模型 ID

## 📦 目录

- [安装](#安装)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
  - [模型/供应商配置](#模型供应商配置)
  - [多供应商示例](#多供应商示例)
  - [MCP 服务配置](#mcp-服务配置)
- [构建与打包](#构建与打包)
- [部署到服务器 / 分发](#部署到服务器--分发)
- [从仓库下载并在 IDEA 中开发](#从仓库下载并在-idea-中开发)
- [常见问题 FAQ](#常见问题-faq)
- [开发指南](#开发指南)
- [开源许可](#开源许可)

## 安装

### 前置要求

| 工具 | 版本 | 说明 |
|---|---|---|
| **JetBrains IDE** | 2024.1+ | IntelliJ IDEA、PyCharm、WebStorm 等 |
| **JDK** | 17+ | 编译插件需要 |
| **Node.js** | 18.0+ | Claude Code CLI 依赖 |
| **Claude Code CLI** | 最新版 | `npm install -g @anthropic-ai/claude-code` |
| **Python 3** | 3.8+ | 内置代理服务器需要 |

### 安装 Claude Code CLI

```bash
# 安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

# Mac 默认路径
which claude
# /opt/homebrew/bin/claude  ← 默认查找路径，如果不一致需要在插件设置里修改
```

### 跳过 OAuth 登录验证

在用户主目录下编辑或新建 `.claude.json`：

| 系统 | 路径 |
|---|---|
| **Mac/Linux** | `~/.claude.json`（即 `/Users/<用户名>/.claude.json`） |
| **Windows** | `C:\Users\<用户名>\.claude.json` |

文件内容：

```json
{
  "hasCompletedOnboarding": true
}
```

### 安装插件

#### 方式一：从 ZIP 安装（推荐普通用户）

1. 从 [Releases](https://gitee.com/mashiro520/claude-code-idea-plugin/releases) 下载最新的 `claude-code-idea-plugin-x.y.z.zip`
2. IDE → `Settings` → `Plugins` → ⚙️ → `Install Plugin from Disk...`
3. 选择刚下载的 ZIP 文件，重启 IDE

#### 方式二：从源码构建（开发者）

见 [构建与打包](#构建与打包)

## 快速开始

### 1. 打开工具窗口

安装重启后，IDE 右侧栏会出现 **Claude Code** 工具窗口（💬 图标）。

### 2. 配置一份供应商档案

点击工具栏的 **🤖 Default** 按钮 → 在弹窗里编辑右侧字段。以**阿里百炼按量计费**为例：

| 字段 | 填写内容 |
|---|---|
| **Profile name** | `百炼-按量计费` |
| **API Base URL** | `https://dashscope.aliyuncs.com/apps/anthropic` |
| **API Key** | 你的百炼 API Key |
| **Main model** | `qwen3-coder-plus`（可留空，留空时自动用 Sonnet 映射） |
| **Subagent model** | `qwen3-coder-plus` |
| **Haiku →** | `qwen3-coder-plus` |
| **Sonnet →** | `qwen3-coder-plus` ★必填 |
| **Opus →** | `qwen3-coder-plus` |

> 💡 **提示**：鼠标悬停到任何字段都会显示中文说明。可以点 **🔄 拉取模型列表** 自动从 `{baseUrl}/models` 获取可用模型。

点 **✓ Activate** 激活，再点 **OK** 关闭弹窗，CLI 自动重启加载新配置。

### 3. 开始使用

底部输入框输入消息，按 Enter 发送。Claude Code 完整功能（`/help`、`/mcp`、文件编辑、Bash 工具）都可用。

## 配置说明

### 模型/供应商配置

#### 字段详解

| 字段 | 环境变量 | 必填 | 说明 |
|---|---|---|---|
| Profile name | - | ✅ | 配置档案显示名（仅标签） |
| Provider name | - | ❌ | 供应商备注 |
| API Base URL | `ANTHROPIC_BASE_URL` | ✅ | Anthropic 兼容协议的 API 地址 |
| API Key | `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` | ✅ | 供应商 API Key |
| Main model | `ANTHROPIC_MODEL` / `--model` | ⚠️ | 真实模型 ID，留空时自动用 Sonnet 映射 |
| Subagent model | `CLAUDE_CODE_SUBAGENT_MODEL` | ❌ | 子代理模型 |
| Haiku → | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | ⚠️ | 别名映射，非 Anthropic 必填 |
| Sonnet → | `ANTHROPIC_DEFAULT_SONNET_MODEL` | ⚠️ | 别名映射，非 Anthropic 必填 |
| Opus → | `ANTHROPIC_DEFAULT_OPUS_MODEL` | ⚠️ | 别名映射，非 Anthropic 必填 |

#### 别名映射的作用

Claude CLI 内部会用 `claude-sonnet-4-6`、`claude-haiku-3-5` 这种**别名**调用模型。

- **Anthropic 官方**：可以直接识别这些别名
- **第三方供应商**（百炼/OpenRouter/DeepSeek...）：识别不了，需要把别名映射到供应商的真实模型 ID

所以接百炼时**三个别名映射必须填**，否则会看到 `selected model (xxx) does not exist` 错误。

### 多供应商示例

#### 阿里百炼（按量计费）

```yaml
Profile name:    百炼-按量计费
API Base URL:    https://dashscope.aliyuncs.com/apps/anthropic
API Key:         <从阿里云百炼控制台获取>
Main model:      qwen3-coder-plus
Subagent model:  qwen3-coder-plus
Haiku →:         qwen3-coder-plus
Sonnet →:        qwen3-coder-plus
Opus →:          qwen3-coder-plus
```

> ⚠️ **注意**：百炼 Anthropic 兼容接口需要在控制台**单独开通**，确认账户余额充足。

#### Anthropic 官方

```yaml
Profile name:    Anthropic 官方
API Base URL:    https://api.anthropic.com
API Key:         sk-ant-xxx
Main model:      （留空即可）
Haiku →:         （留空即可）
Sonnet →:        （留空即可）
Opus →:          （留空即可）
```

#### OpenRouter

```yaml
Profile name:    OpenRouter
API Base URL:    https://openrouter.ai/api/v1
API Key:         sk-or-v1-xxx
Main model:      anthropic/claude-3.5-sonnet
Sonnet →:        anthropic/claude-3.5-sonnet
Haiku →:         anthropic/claude-3.5-haiku
Opus →:          anthropic/claude-3-opus
```

#### DeepSeek（自建 Anthropic 网关）

```yaml
Profile name:    DeepSeek
API Base URL:    <你的网关地址>
API Key:         <你的 Key>
Main model:      deepseek-chat
Sonnet →:        deepseek-chat
Haiku →:         deepseek-chat
Opus →:          deepseek-reasoner
```

### MCP 服务配置

工具栏 **⚙ MCP Config** 按钮：

- 支持 stdio 模式（本地命令）和 HTTP/SSE 模式（远程服务）
- 自动健康检查（默认 30 秒一次，可在 Settings 里改）
- 工具栏 MCP 状态按钮显示当前可用服务数

配置存储在 `~/.claude/mcp.json`，CLI 启动时会被自动转换为兼容格式传给 `--mcp-config` 参数。

## 构建与打包

### 一键构建可发布的 ZIP

```bash
cd claude-code-idea-plugin
./gradlew buildPlugin
```

产物位置：

```
build/distributions/claude-code-idea-plugin-<version>.zip
```

这个 ZIP 就是可以分发给其他用户安装的最终产物。

### 本地调试运行

```bash
./gradlew runIde
```

会启动一个独立的沙盒 IDE 实例（带插件已加载），不影响你日常使用的 IDE。

### 修改版本号

编辑 `gradle.properties`：

```properties
pluginVersion = 1.0.0
pluginSinceBuild = 241
pluginUntilBuild = 261.*
```

## 部署到服务器 / 分发

### 场景一：内部团队分发（推荐）

1. **打包**：`./gradlew buildPlugin`
2. **上传 ZIP** 到内部文件服务器/OSS/GitHub Releases
3. **团队成员**通过 `Install Plugin from Disk` 安装

### 场景二：搭建私有插件仓库

JetBrains 支持自定义插件仓库 URL，团队成员订阅后能像官方市场一样自动更新。

#### 步骤

1. **生成 `updatePlugins.xml`**：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<plugins>
    <plugin id="com.shigure.claudecode"
            url="https://your-server.com/claude-code-idea-plugin-1.0.0.zip"
            version="1.0.0">
        <name>Claude Code</name>
        <description>在 IDEA 中使用 Claude Code</description>
        <vendor>shigure</vendor>
        <idea-version since-build="241" until-build="261.*"/>
    </plugin>
</plugins>
```

2. **把 `updatePlugins.xml` 和 ZIP 一起上传**到服务器：

```
https://your-server.com/
├── updatePlugins.xml
└── claude-code-idea-plugin-1.0.0.zip
```

3. **团队成员添加私有仓库**：
   - IDE → `Settings` → `Plugins` → ⚙️ → `Manage Plugin Repositories...`
   - 添加 `https://your-server.com/updatePlugins.xml`
   - 之后在 `Marketplace` 标签页就能搜到并安装

#### 用 Nginx 托管的最简配置

```nginx
server {
    listen 80;
    server_name plugin.example.com;
    root /var/www/jetbrains-plugins;

    location / {
        autoindex on;
        add_header Access-Control-Allow-Origin *;
    }
}
```

把 `updatePlugins.xml` 和所有 ZIP 放到 `/var/www/jetbrains-plugins/` 即可。

### 场景三：发布到 JetBrains 官方市场

1. 注册 [JetBrains Marketplace 账号](https://plugins.jetbrains.com/)
2. 上传 ZIP，等待审核（首次需要人工审核，后续自动）
3. 团队成员直接在 IDE 内搜索安装

## 从仓库下载并在 IDEA 中开发

### 1. 克隆仓库

```bash
git clone https://gitee.com/mashiro520/claude-code-idea-plugin.git
cd claude-code-idea-plugin
```

### 2. 用 IDEA 打开

- `File` → `Open` → 选择 `claude-code-idea-plugin` 目录
- IDEA 会自动识别为 Gradle 项目并开始下载依赖（首次约 5-10 分钟）

### 3. 修改本地 IDE 路径

**默认零配置**：首次运行 Gradle 会自动下载 IDEA 社区版 2025.1 作为开发依赖（约 700MB，缓存后下次不用下载）。

**想用本地已安装的 IDE**（节省下载）？在 `gradle.properties` 末尾加一行：

```properties
# Mac
localIdePath = /Applications/IntelliJ IDEA.app
# 或 Windows
# localIdePath = C:/Program Files/JetBrains/IntelliJ IDEA 2024.3
# 或 Linux
# localIdePath = /opt/idea-IU-243.xxxxx
```

如果路径不存在，会自动回退到下载社区版，保证构建永远不失败。

### 4. 同步 Gradle 并运行

- 顶部右侧的 🐘 大象图标 → `Reload All Gradle Projects`
- 找到 Gradle 任务面板 → `Tasks` → `intellij platform` → 双击 **`runIde`**

会启动一个沙盒 IDEA，里面已经装好了你的插件。

### 5. 修改代码后热重载

- 改 Java 代码 → 关闭沙盒 IDE → 重新 `runIde`
- 改 plugin.xml / 资源文件 → 必须重启沙盒

### 6. Gradle Wrapper 说明

项目使用 Gradle Wrapper (`gradlew` / `gradlew.bat`)，无需手动安装 Gradle，首次运行会自动下载。

#### Gradle 版本

项目使用 **Gradle 9.4.0**（在 `gradle/wrapper/gradle-wrapper.properties` 里配置）。

#### 下载源切换

默认从 Gradle 官方源下载：

```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.0-bin.zip
```

如果国内网络下载慢，可以改成国内镜像（编辑 `gradle/wrapper/gradle-wrapper.properties`）：

| 镜像 | URL |
|---|---|
| **腾讯云**（推荐，稳定） | `https://mirrors.cloud.tencent.com/gradle/gradle-9.4.0-bin.zip` |
| **阿里云**（macports 镜像） | `https://mirrors.aliyun.com/macports/distfiles/gradle/gradle-9.4.0-bin.zip` |
| **本地缓存**（已下载过） | `file:///path/to/gradle-9.4.0-bin.zip` |

> ⚠️ **不要把本地路径（`file://`）提交到 git**，否则其他人（尤其是 Windows）拉下来会报 `FileNotFoundException`。

#### Windows 用户特别说明

- 使用 `gradlew.bat` 而不是 `./gradlew`
- 路径不要包含中文或空格
- 首次下载约 130MB，会缓存到 `C:\Users\<用户名>\.gradle\wrapper\dists\`
- 如果遇到 `Exception in thread "main" java.io.FileNotFoundException`，检查 `gradle-wrapper.properties` 里的 `distributionUrl` 是否是绝对本地路径

#### 常见 Gradle 命令

```bash
# 编译
./gradlew classes

# 启动沙盒 IDE 调试
./gradlew runIde

# 打包成可分发的 ZIP
./gradlew buildPlugin

# 清理构建产物
./gradlew clean

# 查看所有可用任务
./gradlew tasks
```

### 7. 环境变量（高级配置）

插件支持以下环境变量覆盖默认行为，适合 CI/团队定制：

| 环境变量 | 用途 | 优先级 |
|---|---|---|
| `CLAUDE_CLI_PATH` | 指定 Claude CLI 可执行文件的绝对路径 | 高于系统默认值，低于 Settings 显式配置 |
| `CLAUDE_PYTHON` | 指定 Python 3 解释器（用于内置代理） | 高于自动探测 |

**示例（Mac/Linux）：**

```bash
export CLAUDE_CLI_PATH="/Users/you/.nvm/versions/node/v20/bin/claude"
export CLAUDE_PYTHON="/opt/homebrew/bin/python3.11"
```

**示例（Windows PowerShell）：**

```powershell
$env:CLAUDE_CLI_PATH = "C:\Users\you\AppData\Roaming\npm\claude.cmd"
$env:CLAUDE_PYTHON = "C:\Python311\python.exe"
```

如果都不设置，插件会按以下顺序兜底：
- **Claude CLI**：Windows → `claude.cmd`，Mac → `/opt/homebrew/bin/claude`，Linux → `/usr/local/bin/claude`
- **Python**：Windows 试 `python` → `py` → `python3`；Mac/Linux 试 `python3` → `python`

## 常见问题 FAQ

### Q1: CLI 启动后报 `selected model (xxx) does not exist`

**原因**：模型名不对，或别名映射没填，或供应商不识别这个模型。

**排查**：

```bash
# 直接 curl 测试供应商接口
curl -X POST https://dashscope.aliyuncs.com/apps/anthropic/v1/messages \
  -H "x-api-key: <你的KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"qwen3-coder-plus","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'
```

| 响应 | 解决 |
|---|---|
| 正常 JSON | 检查插件里 5 个模型字段都填对了 |
| 404 unknown model | 换其他模型名（百炼可用 `/models` 接口列出） |
| 401 unauthorized | API Key 不对或没开通 Anthropic 兼容接口 |

### Q2: `/mcp` 菜单的箭头键、Esc 不响应

已修复。如果仍有问题：

- 确保焦点在底部输入框（点击一下输入框）
- 输入框为空时，箭头/Esc/Tab/Enter 会直接转发给 CLI
- 输入框有内容时，这些键正常文本编辑

### Q3: MCP 服务一直 `CHECKING` 不变

- 点工具栏的 MCP 状态按钮 → 看具体哪个服务超时
- HTTP/SSE 类的服务确认网络可达
- stdio 类的服务确认命令路径正确

### Q4: 切换 profile 后 CLI 没生效

切换流程：

1. 点 **🤖 XXX** 按钮打开弹窗
2. 选中目标 profile（左侧列表）
3. 点 **✓ Activate** 或双击该行
4. 关闭弹窗（OK / Cancel 都行）
5. CLI 自动重启，工具栏按钮文字变成新 profile 名

如果按钮文字没变，看日志 `[ChatPanel] CLI using DIRECT mode: ... (profile: XXX)` 确认。

### Q5: 报红 IDE error，但 Gradle 编译能过

正常现象。IDE 索引和 Gradle 编译 classpath 不完全一致，已用 `@SuppressWarnings("all")` 压制。

如果想消除报红：

- `File` → `Invalidate Caches...` → `Invalidate and Restart`
- 或忽略，反正 Gradle 编译能过

### Q6: 我的配置会泄露吗？开源安全吗？

**不会泄露**：

- API Key 等敏感配置存在 `~/Library/Application Support/JetBrains/<IDE>/options/claude-code.xml`
- 跟代码物理隔离，git 不可能误提交
- 代码里没有任何硬编码 Key
- 日志里 Key 已脱敏为 `***set***`

开源前确认 `.gitignore` 包含 `build/`、`.idea/workspace.xml`、`*.iml` 等即可。

### Q7: 如何升级 Claude CLI？

```bash
npm update -g @anthropic-ai/claude-code
```

升级后**不需要**重装插件，重启 CLI 会自动用新版本。

## 开发指南

### 项目结构

```
src/main/java/com/shigure/claudecode/
├── actions/                         # IDE Actions
│   └── SwitchProfileActionGroup.java   # Profile 切换 ActionGroup
├── mcp/                             # MCP 服务管理
│   ├── McpConfigService.java           # 配置读写（兼容 Claude Desktop mcp.json）
│   ├── McpHealthMonitor.java           # 定时健康探活
│   ├── McpServerConfig.java            # 服务配置数据模型
│   ├── McpStartupActivity.java         # IDE 启动钩子
│   ├── McpToolInfo.java                # 单工具信息载体
│   ├── McpToolsCacheService.java       # 工具列表定时缓存 + listener
│   └── McpToolsFetcher.java            # 三种 transport 的 JSON-RPC 握手实现
├── proxy/                           # 内置 HTTP 代理
│   ├── ProxyServer.java                # Python 代理进程管理
│   └── ProxyService.java               # 代理服务生命周期
├── settings/                        # 持久化配置
│   ├── PluginSettings.java             # 多 profile 状态持久化
│   ├── PluginSettingsConfigurable.java # Settings 面板
│   └── ProfileChangeNotifier.java      # Profile 变更广播
└── ui/                              # UI 组件
    ├── ChatPanel.java                  # 主面板（终端 + 输入框 + 工具栏）
    ├── ClaudeMainPanel.java            # ToolWindow 根容器
    ├── ClaudeToolWindowFactory.java    # ToolWindow 工厂
    ├── McpConfigPanel.java             # MCP 配置弹窗
    ├── McpStatusPanel.java             # MCP 状态面板
    ├── McpToolsInspectDialog.java      # MCP 工具检视弹窗
    └── ModelConfigPanel.java           # 模型配置弹窗（多档案）
src/main/resources/
├── META-INF/plugin.xml              # 插件描述
├── icons/toolwindow.png             # ToolWindow 图标
├── rainy.png                        # 原始图标源文件
└── proxy_server.py                  # 内置 Python 代理脚本
```

### 关键架构

```
┌──────────────┐
│   ChatPanel  │  ← 主入口，UI 容器
└──────┬───────┘
       │ startCli()
       ▼
┌──────────────────┐    ┌──────────────────────┐
│ PluginSettings   │ ←──│  ModelConfigPanel    │
│ (多 profile 持久化)│    │  (UI: profiles 列表)  │
└──────┬───────────┘    └──────────────────────┘
       │ getActiveProfile()
       ▼
┌──────────────┐    inject env    ┌─────────────┐
│ Claude CLI   │ ←─────────────── │   PtyProcess │
│ (--bare mode)│                  └─────────────┘
└──────┬───────┘
       │ HTTP request
       ▼ (可选经过代理)
┌──────────────┐
│ ProxyServer  │ → 供应商 API
│ (Python)     │
└──────────────┘
```

### 调试技巧

- **看 CLI 启动参数**：日志里搜 `[ChatPanel] CLI command:`
- **看环境变量**：日志里搜 `[ChatPanel] CLI env:`
- **看代理转发**：日志里搜 `[ProxyServer]` 和 `[Proxy-stderr]`
- **看 MCP 状态**：日志里搜 `McpHealthMonitor`

### 提交 PR

1. Fork 仓库 → 新建分支 `feature/xxx`
2. 提交前跑 `./gradlew compileJava` 确保编译通过
3. 用 `./gradlew runIde` 实测功能
4. 提交 PR 时附上截图/日志

## 开源许可

MIT License

---

**Made with ❤️ by yu.zhou and claude-code opus 4.7 嘻嘻 😁**