claude-code-plus: Instructions file for Codex

1=特别提醒：请使用简体中文进行交流 特别提醒：git commit、changelog 不使用中文，而是使用英文

Claude Code Plus - 架构说明

📋 项目概述

Claude Code Plus 是一个 IntelliJ IDEA 插件，集成了 Claude AI 助手，提供智能代码编辑、文件操作、终端执行等功能。

🏗️ 整体架构

🔌 三种通信方式

2️⃣ IDEA 集成通信 (纯 HTTP)

用途: 打开文件、显示 Diff、搜索文件等 IDEA 原生功能

前端:

// frontend/src/services/ideaBridge.ts
import { ideService } from '@/services/ideaBridge'

// 打开文件
await ideService.openFile('/path/to/file.ts', { line: 10 })

// 显示 Diff
await ideService.showDiff({
    filePath: '/path/to/file.ts',
    oldContent: '...',
    newContent: '...'
})

后端:

// claude-code-server/src/main/kotlin/com/claudecodeplus/server/HttpApiServer.kt
post("/api/") {
    when (action) {
        "ide.openFile" -> ideActionBridge.openFile(request)
        "ide.showDiff" -> ideActionBridge.showDiff(request)
        "ide.searchFiles" -> ideActionBridge.searchFiles(query, maxResults)
        "ide.getFileContent" -> // 读取文件内容
    }
}

协议: HTTP POST

• 请求-响应模式
• 同步调用
• 简单可靠

---

3️⃣ 通用 Web 功能 (纯 HTTP)

用途: 其他不需要流式响应的功能

协议: HTTP GET/POST

• RESTful API
• 标准 HTTP 请求

---

🔧 关键技术细节

随机端口机制

问题: 多个 IDEA 项目同时打开时，端口冲突

解决方案:

// claude-code-server/src/main/kotlin/com/claudecodeplus/server/HttpApiServer.kt
fun start(port: Int = 8765): String {
    val actualPort = try {
        embeddedServer(Netty, port = port) { ... }.start()
        port
    } catch (e: BindException) {
        val availablePort = findAvailablePort()
        embeddedServer(Netty, port = availablePort) { ... }.start()
        availablePort
    }
    return "http://localhost:$actualPort"
}

前端获取后端地址 & 环境检测

IDEA 插件模式: 通过 URL 参数 ?ide=true 触发后端注入

// jetbrains-plugin/.../VueToolWindowFactory.kt
val ideUrl = "$serverUrl?ide=true"  // 带上 ide=true 参数
browser.loadURL(ideUrl)

// claude-code-server/.../HttpApiServer.kt
get("/") {
    val isIdeMode = call.request.queryParameters["ide"] == "true"

    if (isIdeMode) {
        // IDEA 插件模式：注入 window.__serverUrl
        val injection = """
            <script>
                window.__serverUrl = 'http://localhost:$serverPort';
                console.log('✅ Environment: IDEA Plugin Mode');
            </script>
        """.trimIndent()
        html = html.replace("</head>", "$injection\n</head>")
    }
}