# ai-switch-plugin

**Repository Path**: hujunwei-dev/ai-switch-plugin

## Basic Information

- **Project Name**: ai-switch-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Switch Plugin

一个 IntelliJ 平台插件，让你**配置一次 AI 模型，在三个 AI 编程 CLI 工具之间透明切换**：Claude Code、Codex、opencode。

核心是一个**本地协议转换代理**——每个 CLI 说的协议不同，后端模型说的协议也不同，代理在中间做翻译，让你用任意后端模型驱动任意 CLI。

## 解决什么问题

不同 AI 编程 CLI 各说一种协议：

| CLI | 线协议 | 端点 |
|-----|--------|------|
| Claude Code | Anthropic Messages | `POST /v1/messages` |
| Codex | OpenAI Responses | `POST /v1/responses` |
| opencode | OpenAI Chat Completions | `POST /v1/chat/completions` |

而后端模型（如 DeepSeek、OpenAI、Anthropic 自家等）只认 OpenAI Chat 或 Anthropic Messages 两种协议之一。直接对接时，协议不匹配就调不通。

本插件在你本机起一个代理，按入站协议分发、按后端协议翻译，并把每个 CLI 的配置文件改写指向这个代理。你在插件里点一下"激活"，对应 CLI 的配置就自动切好；点"停用"，配置从备份原样恢复。

## 工作原理

```
Claude Code ─┐
Codex ───────┼──> 本地代理 (127.0.0.1:随机端口) ──> 真实后端 (DeepSeek/OpenAI/Anthropic…)
opencode ────┘        │
                       └─ 协议翻译 (TranslatorFactory)
```

1. **代理按入站协议路由**：Claude Code 打到 `/v1/messages`，Codex 打到 `/v1/responses`，opencode 打到 `/v1/chat/completions`。
2. **查表选翻译器**：根据"入站协议 × 后端协议"组合，选对应的 Translator。
3. **翻译请求体** → 转发到真实后端 → **翻译响应流（SSE）** 回给 CLI。

### 协议翻译矩阵

| 入站（CLI） | 后端协议 | 翻译路径 | 实现 |
|------------|---------|---------|------|
| Anthropic Messages (Claude Code) | OpenAI Chat | Anthropic→OpenAI Chat | ✅ |
| Anthropic Messages (Claude Code) | Anthropic | PassThrough（透传） | ✅ |
| OpenAI Responses (Codex) | OpenAI Chat | Responses→OpenAI Chat | ✅ |
| OpenAI Responses (Codex) | Anthropic | Responses→Anthropic | ⏳ v1 范围外 |
| OpenAI Chat (opencode) | OpenAI Chat | PassThrough（透传） | ✅ |
| OpenAI Chat (opencode) | Anthropic | OpenAI Chat→Anthropic | ⏳ v1 范围外 |

## 功能特性

- **模型集中管理**：在一个表里增/删/改/复制所有后端模型（名称、协议、Base URL、API Key、模型 ID）。
- **一键激活/停用**：每个 CLI 一行，选模型 + 点按钮，后台任务改写配置，不阻塞界面。
- **外科手术式配置改写**：只动需要的那几个键，保留文件里其他所有内容；改写前自动备份，停用时从备份恢复。
- **协议翻译**：流式（SSE）和非流式响应都支持，逐事件状态机翻译。
- **开机自愈**：代理每次 IDE 重启换新随机端口，启动时自动用新端口重写已激活的配置，无需重新点激活。
- **Claude Code 冲突检测**：检测到 `settings.json` 被外部工具（如 toolbox）覆盖时，自动重写一次并在界面提示。
- **中英双语界面**：工具窗口右上角切换，默认中文。

## 构建要求

- JDK 21（本机没有也行——Gradle 会通过 foojay 工具链解析器自动下载）
- 本机已安装 IntelliJ IDEA 2026.2（插件 `sinceBuild=262`、`untilBuild=262.*`，仅面向此版本）
- Gradle（项目自带 `gradlew`）

> **关于 IntelliJ 路径**：插件锁定 2026.2，而该构建未发布到远程仓库，因此 `build.gradle.kts` 用本机已安装的 IntelliJ 作为平台依赖（`local(...)`），路径需配置为本机 IntelliJ 安装目录。任选其一（推荐第 3 种，设一次永久生效）：
> 1. 命令行参数：`./gradlew build -PintellijPlatform.localPath=/path/to/IntelliJ`
> 2. 环境变量：`export INTELLIJ_HOME=/path/to/IntelliJ`
> 3. 全局 `~/.gradle/gradle.properties`（每台机器设一次）：
>    ```properties
>    intellijPlatform.localPath=/path/to/IntelliJ
>    ```
> Windows 路径用正斜杠或转义反斜杠，例如 `D:/SoftWare/DevTools/IntelliJ IDEA 2026.2.0.1`。
> 未配置时构建会失败并打印上述三种方式。

## 如何构建

```bash
# Windows
.\gradlew.bat build

# macOS / Linux
./gradlew build
```

产物在 `build/distributions/` 下，可在 IntelliJ 中通过「设置 → 插件 → 齿轮 → 从磁盘安装」加载。

## 如何使用

1. 安装插件后，打开任意项目，右侧出现 **AI Switch** 工具窗口。
2. **添加模型**：点「添加模型」，填显示名称、协议（OpenAI Chat 或 Anthropic）、Base URL、API Key、模型 ID。
3. **激活**：在对应 CLI 行的下拉框选模型，点「激活」。插件会：
   - 备份该 CLI 的配置文件（加 `.ai-switch.bak` 后缀）
   - 改写配置指向本地代理
   - 记录激活状态
4. 正常使用该 CLI，请求经代理翻译后转发到后端模型。
5. **停用**：点「停用」，配置从备份原样恢复。

### 改写的配置文件

| CLI | 配置文件路径 | 改写方式 |
|-----|-----------|---------|
| Claude Code | `~/.claude/settings.json` | 改写 `env` 块：`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`ANTHROPIC_DEFAULT_{FABLE,HAIKU,OPUS,SONNET}_MODEL_NAME` |
| Codex | `~/.codex/config.toml` | 注入 `[model_providers.ai-switch]`（`wire_api="responses"`、`env_key="AI_SWITCH_PROXY_KEY"`）+ 顶层 `model`/`model_provider` |
| opencode | `~/.config/opencode/opencode.json` | 注入 `provider["ai-switch"]`（按后端协议选 `@ai-sdk/openai-compatible` 或 `@ai-sdk/anthropic`）+ 顶层 `model` |

> 路径中的 `~` 解析自 `USERPROFILE` 或 `HOME` 环境变量。
> Codex 的 `AI_SWITCH_PROXY_KEY` 通过 `setx` 写入环境变量（仅影响新启动的进程）。

## 目录结构

```
src/main/kotlin/com/aiswitch/
├── config/        # CLI 配置改写器（每个 CLI 一个）
│   ├── CliTarget.kt              # CLI 目标枚举
│   ├── ConfigWriter.kt           # 接口 + ActivateContext / ActivationRecord
│   ├── ConfigBackup.kt           # 文件级备份/恢复（剥离 UTF-8 BOM）
│   ├── ClaudeCodeConfigWriter.kt
│   ├── CodexConfigWriter.kt
│   └── OpencodeConfigWriter.kt
├── lifecycle/
│   └── ModelActivator.kt         # 激活/停用编排 + 开机重写
├── model/
│   └── ModelConfig.kt            # 模型配置数据类
├── plugin/
│   └── PluginStartupActivity.kt  # IDE 启动：起代理 + 重写已激活配置
├── proxy/
│   ├── ProxyServer.kt            # 本地 HTTP 代理（单例）
│   ├── ProxyHandler.kt           # 请求处理：校验 token → 查模型 → 翻译 → 转发
│   └── BackendClient.kt          # 后端转发（流式 + 非流式）
├── store/
│   └── ModelStore.kt             # 持久化状态（模型列表/激活映射/端口/token/语言）
├── translate/                    # 协议翻译层
│   ├── WireProtocol.kt           # 三种线协议 + 端点路径
│   ├── Translator.kt             # 翻译器接口
│   ├── TranslatorFactory.kt      # 按协议对选翻译器
│   └── …                         # 各方向的具体翻译器 + 流状态机
└── ui/
    ├── AiSwitchToolWindowFactory.kt
    ├── AiSwitchPanel.kt          # 主面板（模型表 + CLI 切换行）
    └── Messages.kt               # i18n（中/英）
```

## 技术栈

- Kotlin 2.4.0 + kotlinx.serialization
- IntelliJ Platform Gradle 插件 2.2.1
- JVM 21
- 代理基于 JDK 内置 `com.sun.net.httpserver`，无额外 HTTP 依赖

## 注意事项

- 代理监听 `127.0.0.1` 本机回环，用随机生成的 token 校验入站请求，不暴露到网络。
- v1 暂未实现 Responses→Anthropic、OpenAI Chat→Anthropic 两个翻译方向（代码中标注为 TODO）。
- 插件不会凭空创建 CLI 配置文件——要求对应 CLI 已安装并生成过配置文件，否则激活会报错提示。

## 许可证

私有项目。