Claude Code IDE 集成工作原理详解

深入理解 Claude Code 与主流 IDE 的集成机制

---

目录

1. [IDE 集成概述](#IDE 集成概述)
2. [VS Code 集成](#VS Code 集成)
3. [JetBrains 集成](#JetBrains 集成)
4. [Vim/Neovim 集成](#Vim/Neovim 集成)
5. [Emacs 集成](#Emacs 集成)
6. 通信协议
7. [LSP 集成](#LSP 集成)
8. 高级功能
9. 问题排查
10. 最佳实践

---

1. IDE 集成概述

1.1 什么是 IDE 集成

IDE 集成是指将 Claude Code 的能力嵌入到集成开发环境中，让开发者无需离开编辑器就能使用 Claude Code 的功能。

传统工作流:                    IDE 集成工作流:
┌──────────────┐                ┌──────────────────┐
│ 编写代码     │                │ 编写代码         │
│   (IDE)      │                │    (IDE)         │
└──────┬───────┘                └────────┬─────────┘
       ↓                                   ↓
┌──────────────┐                ┌──────────────────┐
│ 切换终端     │                │ 快捷键 / 面板    │
│ (Terminal)   │                │  直接调用        │
└──────┬───────┘                └────────┬─────────┘
       ↓                                   ↓
┌──────────────┐                ┌──────────────────┐
│ 运行命令     │                │ Claude Code      │
│ Claude Code  │                │  集成在 IDE 中   │
└──────────────┘                └──────────────────┘

效率: ❌ 低 (上下文切换)       效率: ✅ 高 (无切换)

1.2 支持的 IDE

Claude Code IDE 支持矩阵

┌────────────────────────────────────────────────┐
│  IDE           │ 支持状态 │ 功能完整性 │ 官方支持 │
├────────────────┼────────┼──────────┼────────┤
│ VS Code        │ ✅ 已发布 │ ████████ 100% │ ✅ 官方 │
│ JetBrains      │ ✅ 已发布 │ ████████ 100% │ ✅ 官方 │
│ Vim/Neovim     │ ⚠️ 社区版 │ ███████░ 90%  │ ❌ 社区 │
│ Emacs          │ ⚠️ 社区版 │ ███████░ 90%  │ ❌ 社区 │
│ 其他编辑器      │ 🔄 计划中 │ ████░░░░ 40%  │ ❌ 计划中│
└────────────────────────────────────────────────┘

说明:
- 支持状态: ✅ 已发布 | ⚠️ 社区开发 | 🔄 计划中
- 功能完整性: 100% = 所有功能可用 | 90% = 大部分功能 |
- 官方支持: ✅ Anthropic 官方 | ❌ 社区/第三方

1.3 集成的核心优势

┌─────────────────────────────────────────┐
│ 1. 无缝工作流                            │
│    ├─ 无需切换窗口                       │
│    ├─ 上下文感知                         │
│    └─ 快速访问                           │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 2. 增强的代码理解                        │
│    ├─ 代码选择执行                       │
│    ├─ 符号跳转 (Go to Definition)       │
│    └─ 实时诊断                           │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 3. 智能补全和生成                        │
│    ├─ 代码补全                           │
│    ├─ 代码片段生成                       │
│    └─ 重构建议                           │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 4. 协作增强                              │
│    ├─ 团队配置同步                       │
│    ├─ 共享会话                           │
│    └─ 代码审查集成                       │
└─────────────────────────────────────────┘

1.4 集成架构概览

IDE 集成整体架构

┌─────────────────────────────────────────┐
│          IDE 前端层 (UI)                │
│  ┌──────────────────────────────────┐  │
│  │  ├─ 侧边栏 Claude Code 面板      │  │
│  │  ├─ 代码编辑器集成              │  │
│  │  ├─ 终端窗口                    │  │
│  │  └─ 命令面板                    │  │
│  └─────────┬────────────────────────┘  │
│            ↓                          │
└────────────┬──────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│         通信中间件层                    │
│  ┌──────────────────────────────────┐  │
│  │  ├─ WebSocket 连接               │  │
│  │  ├─ HTTP API                    │  │
│  │  ├─ Language Server Protocol    │  │
│  │  └─ IPC (进程间通信)            │  │
│  └─────────┬────────────────────────┘  │
└────────────┬──────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│        Claude Code 运行时              │
│  ┌──────────────────────────────────┐  │
│  │  ├─ Session 管理                │  │
│  │  ├─ Tool 执行                   │  │
│  │  ├─ Agent 决策循环              │  │
│  │  └─ MCP 服务器                  │  │
│  └─────────┬────────────────────────┘  │
└────────────┬──────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│        Anthropic Claude API            │
└─────────────────────────────────────────┘

---

2. VS Code 集成

2.1 VS Code 扩展概览

VS Code Claude Code Extension

扩展 ID: anthropic.claude-code
市场: VS Code Marketplace
版本: 2.x.x (持续更新)
安装量: 100M+
评分: ⭐⭐⭐⭐⭐ (4.8/5)

安装方式:

# 方式 1: VS Code 扩展面板搜索
1. 打开 VS Code
2. 点击扩展图标 (左侧) 或按 Ctrl+Shift+X
3. 搜索 "Claude Code"
4. 点击安装

# 方式 2: 命令行
code --install-extension anthropic.claude-code

# 方式 3: VSIX 文件
# wget https://path/to/claude-code.vsix
# code --install-extension claude-code.vsix

2.2 VS Code 扩展功能

功能 1：Claude Code 面板

位置: 左侧边栏 (活动栏)
图标: Anthropic 紫色 logo ┇
快捷键: Ctrl+Shift+C (可调)

面板结构:
┌─────────────────────────────────────┐
│  Claude Code                     [x]│
├─────────────────────────────────────┤
│  ┌────────────────────────────────┐ │
│  │ Claude, 你好！                 │ │
│  │ 我可以帮你...                   │ │
│  │                                 │ │
│  │ ┌────────────────────────────┐  │
│  │ │ 代码生成...                 │  │
│  │ │ 代码审查...                 │  │
│  │ │ Bug 修复...                 │  │
│  │ │ 重构...                     │  │
│  │ └────────────────────────────┘  │
│  │                                 │ │
│  │ 你的代码助手，等待你的指令...     │ │
│  └────────────────────────────────┘ │
├─────────────────────────────────────┤
│  🔍 输入你的问题...               │
├─────────────────────────────────────┤
│  📁 Files                         │
│  │ src/components/Button.tsx     │
│  │ src/types/index.ts             │
│  │ ↑ 可拖拽文件到这里            │
│  └───────────────────────────────┘
├──┬──────────────────────────────────┤
│[✓] Direct 连接                     │
│  Enable direct connection...      │
└──┴──────────────────────────────────┘

功能 2：快捷命令集成

// VS Code 命令面板集成

// 打开命令面板: Ctrl+Shift+P
// 输入 "Claude Code" 查看所有命令

可用的命令:
├─ Claude Code: Open Panel
│  └─ 打开 Claude Code 侧边栏
│
├─ Claude Code: New Chat
│  └─ 开启新对话
│
├─ Claude Code: Clear Chat
│  └─ 清空当前对话
│
├─ Claude Code: Focus Input
│  └─ 聚焦到输入框
│
├─ Claude Code: Explain Selection
│  └─ 解释选中的代码
│
├─ Claude Code: Generate Tests
│  └─ 为选中的代码生成测试
│
├─ Claude Code: Review Code
│  └─ 审查选中的代码
│
└─ Claude Code: Optimize Code
   └─ 优化选中的代码

关键快捷键:

{
  "key": "ctrl+shift+c",
  "command": "claudeCode.openPanel",
  "when": "editorTextFocus"
},
{
  "key": "ctrl+shift+e",
  "command": "claudeCode.explainSelection",
  "when": "editorHasSelection"
}

功能 3：代码选择执行

// 选中代码后按右键菜单

// 示例: 选中以下函数
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// 右键菜单 → "Explain with Claude Code"
// 或快捷键: Ctrl+Shift+E

// Claude Code 输出:
"""
这是一个计算商品总价的函数。

逻辑分析:
1. 使用 `reduce` 遍历所有商品
2. 对每个商品: price × quantity
3. 累加得到总价

改进建议:
- 添加类型检查，确保 items 是数组
- 处理 item.price 或 item.quantity 为 undefined 的情况
- 考虑添加货币格式化
"""

功能 4：内联代码生成

在代码编辑器中:

┌─────────────────────────────────────┐
│ // 输入注释                        │
│ // 排序算法: 快速排序              │
│                                    │
│ // 按 Ctrl+Space 触发 Claude      │
│ // Claude 自动生成代码:            │
│                                    │
│ function quickSort(arr) {          │
│   if (arr.length <= 1) return arr; │
│                                    │
│   const pivot = arr[0];            │
│   const left = [];                 │
│   const right = [];                │
│                                    │
│   for (let i = 1; i < arr.length;  │
│ i++) {        │
│     if (arr[i] < pivot) {          │
│       left.push(arr[i]);           │
│     } else {                       │
│       right.push(arr[i]);          │
│     }                              │
│   }                                │
│                                    │
│   return [...quickSort(left),      │
│ pivot, ...quickSort(right)];│
│ }                                  │
└─────────────────────────────────────┘

2.3 VS Code 设置配置

API Key 配置

// settings.json (用户级别)
{
  "claudeCode.apiKey": "sk-ant-xxx...",

  // 或使用环境变量
  "claudeCode.apiKeySource": "env",
  "claudeCode.apiKeyEnvVar": "ANTHROPIC_API_KEY"
}

主题和外观

{
  // 继承 VS Code 主题
  "claudeCode.theme": "auto",

  // 字体设置
  "claudeCode.fontSize": 14,
  "claudeCode.fontFamily": "'Fira Code', 'Cascadia Code', monospace",

  // 暗色模式
  "claudeCode.darkMode": true,

  // 代码高亮主题
  "claudeCode.syntaxTheme": "github-dark"
}

行为和性能

{
  // 自动连接 Claude Code
  "claudeCode.autoConnect": true,

  // 连接超时 (ms)
  "claudeCode.connectionTimeout": 30000,

  // 最大重试次数
  "claudeCode.maxRetries": 3,

  // 启用流式响应
  "claudeCode.enableStreaming": true,

  // 上下文长度限制
  "claudeCode.contextLength": 200000,

  // 自动保存会话
  "claudeCode.autoSaveSession": true
}

快捷键配置

// keybindings.json
[
  {
    "key": "ctrl+shift+c",
    "command": "claudeCode.openPanel",
    "when": "editorTextFocus"
  },
  {
    "key": "ctrl+shift+e",
    "command": "claudeCode.explainSelection",
    "when": "editorHasSelection"
  },
  {
    "key": "ctrl+shift+g",
    "command": "claudeCode.generateCode",
    "when": "editorTextFocus"
  },
  {
    "key": "ctrl+shift+r",
    "command": "claudeCode.reviewFile",
    "when": "editorTextFocus"
  }
]

2.4 VS Code DevContainer 集成

// .devcontainer/devcontainer.json
{
  "name": "Claude Code Development",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",

  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],

      "settings": {
        "claudeCode.apiKey": "${localEnv:ANTHROPIC_API_KEY}",
        "claudeCode.autoConnect": true
      }
    }
  },

  "postCreateCommand": "npm install",

  "remoteUser": "node"
}

---

3. JetBrains 集成

3.1 支持的 JetBrains IDE

┌─────────────────────────────────────────┐
│  IDE              │ 版本要求 │ 支持功能  │
├───────────────────┼─────────┼──────────┤
│ IntelliJ IDEA     │ 2023.3+ │ 全部      │
│ PyCharm           │ 2023.3+ │ 全部      │
│ WebStorm          │ 2023.3+ │ 全部      │
│ PhpStorm          │ 2023.3+ │ 全部      │
│ RubyMine          │ 2023.3+ │ 全部      │
│ GoLand            │ 2023.3+ │ 全部      │
│ DataGrip          │ 2023.3+ │ 大部分    │
│ Rider             │ 2023.3+ │ 大部分    │
└───────────────────┴─────────┴──────────┘

3.2 JetBrains 插件安装

方式 1: JetBrains Marketplace:

1. 打开 IDE
2. Settings → Plugins → Marketplace
3. 搜索 "Claude Code"
4. 点击安装
5. 重启 IDE

方式 2: 手动安装:

# 下载插件 JAR 文件
https://plugins.jetbrains.com/plugin/xxxxx-claude-code

# 在 IDE 中安装
Settings → Plugins → ⚙️ → Install from Disk
# 选择下载的 JAR 文件

3.3 JetBrains 功能特色

工具窗口集成

位置: 右侧边栏 / 底部工具栏
图标: Antrophic logo
快捷键: Alt+Shift+C (可配置)

┌─────────────────────────────────────────┐
│ Claude Code              [_] [X]       │
├─────────────────────────────────────────┤
│  ┌──────────────────────────────────┐  │
│  │ 对话历史                        │  │
│  │                                  │  │
│  │ User: Review AuthService       │  │
│  │ Claude: I'll review...         │  │
│  │ ✅ Reading files...             │  │
│  │ ✅ Analyzing...                 │  │
│  │ ⚠️  Warning: Hardcoded API key  │  │
│  │                                  │  │
│  └──────────────────────────────────┘  │
├─────────────────────────────────────────┤
│  输入: [________________________] [✓]   │
└─────────────────────────────────────────┘

代码上下文感知

// 选中代码后右键

@Service
public class AuthService {
    public String generateToken(User user) {
        // 选中此方法
        return Jwts.builder()
            .setSubject(user.getId())
            .setExpiration(new Date(System.currentTimeMillis() + 3600000))
            .signWith(SignatureAlgorithm.HS256, "secret")  // ⚠️
            .compact();
    }
}

// 右键 → Tools → Explain with Claude Code

// Claude Code 分析:
"""
1. JWT 令牌生成逻辑正确
2. ⚠️ 安全风险: 硬编码密钥 "secret"
   建议: 使用环境变量或配置中心
3. 过期时间 1 小时合理
4. 建议添加颁发时间 (iat) 声明
"""

重构集成

// 重构前
data class User(
    val id: String,
    val name: String,
    val email: String,
    val age: Int
)

// 选中类名 → Refactor → Generate with Claude

// Claude Code 建议:
"""
建议改进:
1. 添加数据验证
2. 使用值对象包装邮箱
3. 添加创建时间戳

生成代码:
"""

// 重构后
data class User(
    @field:NotNull
    val id: UserId,

    @field:NotBlank
    val name: String,

    @field:Email
    val email: Email,

    @field:Min(0)
    val age: Int,

    val createdAt: Instant = Instant.now()
)

value class Email(val value: String)
value class UserId(val value: String)

测试生成集成

# 在 PyCharm 中

# 选中以下函数
def fibonacci(n):
    if n <= 0:
        return []
    elif n == 1:
        return [0]
    elif n == 2:
        return [0, 1]
    else:
        fib = [0, 1]
        for i in range(2, n):
            fib.append(fib[i-1] + fib[i-2])
        return fib

# 右键 → Go To → Test → Generate Test with Claude

# 自动生成的测试:
import pytest

def test_fibonacci_small_numbers():
    assert fibonacci(0) == []
    assert fibonacci(1) == [0]
    assert fibonacci(2) == [0, 1]
    assert fibonacci(5) == [0, 1, 1, 2, 3]

def test_fibonacci_negative():
    assert fibonacci(-1) == []
    assert fibonacci(-10) == []

def test_fibonacci_large_number():
    result = fibonacci(20)
    assert len(result) == 20
    assert result[-1] == 4181

调试器集成 (实验性)

调试会话中:
1. 在断点处暂停
2. 变量查看器中右键 → Explain with Claude
3. Claude 分析变量状态并提供修复建议

3.4 JetBrains 设置

全局设置 (适用于所有 JetBrains IDE):

<!-- ~/.config/JetBrains/CLaudeCode/config.xml -->
<application>
  <component name="ClaudeCodeSettings">
    <option name="apiKey" value="sk-ant-xxx..." />
    <option name="model" value="claude-3-5-sonnet" />
    <option name="maxTokens" value="4000" />
    <option name="enableStreaming" value="true" />
    <option name="autoConnect" value="true" />
  </component>
</application>

项目级别设置:

<!-- .idea/claude-code.xml -->
<project version="4">
  <component name="ClaudeCodeProjectSettings">
    <option name="projectSpecificSettings">
      <map>
        <entry key="contextLength" value="200000" />
        <entry key="workingDirectory" value="$PROJECT_DIR$" />
      </map>
    </option>
  </component>
</project>

3.5 JetBrains 快捷键

功能	Windows/Linux	macOS
打开 Claude Code	Alt+Shift+C	⌥+⇧+C
解释选中代码	Alt+Shift+E	⌥+⇧+E
生成代码	Alt+Shift+G	⌥+⇧+G
审查代码	Alt+Shift+R	⌥+⇧+R
生成测试	Alt+Shift+T	⌥+⇧+T
优化代码	Alt+Shift+O	⌥+⇧+O

---

4. Vim/Neovim 集成

4.1 插件安装

使用 vim-plug:

" ~/.vimrc 或 ~/.config/nvim/init.vim

call plug#begin()
" 其他插件...

" Claude Code 插件
Plug 'anthropics/claude-code-vim'

call plug#end()

使用 packer (Neovim):

-- ~/.config/nvim/init.lua

require('packer').startup(function()
  use 'anthropics/claude-code-vim'
end)

手动安装:

git clone https://github.com/anthropics/claude-code-vim.git
~/.vim/pack/plugins/start/claude-code-vim

4.2 基本配置

" ~/.vimrc

" Claude Code API Key
let g:claude_code_api_key = 'sk-ant-xxx...'

" 快捷键配置
nnoremap <leader>cc :ClaudeCode<CR>
nnoremap <leader>ce :ClaudeExplain<CR>
nnoremap <leader>cg :ClaudeGenerate<CR>
nnoremap <leader>cr :ClaudeReview<CR>

" 视觉模式下
vnoremap <leader>ce :ClaudeExplainVisual<CR>
vnoremap <leader>cg :ClaudeGenerateVisual<CR>
vnoremap <leader>cr :ClaudeReviewVisual<CR>

" 窗口配置
let g:claude_code_window_size = 30  " 宽度 30%
let g:claude_code_window_position = 'right'  " right/left
let g:claude_code_window_split = 'vertical'  " vertical/horizontal

-- ~/.config/nvim/init.lua (Lua 配置)

-- Claude Code 配置
vim.g.claude_code_api_key = 'sk-ant-xxx...'
vim.g.claude_code_window_size = 30
vim.g.claude_code_window_position = 'right'

-- 快捷键
vim.api.nvim_set_keymap('n', '<leader>cc', ':ClaudeCode<CR>', { noremap = true })
vim.api.nvim_set_keymap('n', '<leader>ce', ':ClaudeExplain<CR>', { noremap = true })
vim.api.nvim_set_keymap('v', '<leader>ce', ':ClaudeExplainVisual<CR>', { noremap = true })

4.3 使用示例

解释代码

" 将光标移动到函数上
function fibonacci(n)
  return n <= 1 and n or fibonacci(n - 1) + fibonacci(n - 2)
end

" 按 \ce (leader + c + e)
" 或使用命令
:ClaudeExplain

" 输出显示在右侧窗口:
"""
-- Claude Code 解释:
-- 这是一个递归实现的斐波那契数列函数。
--
-- 工作原理:
-- 1. 基准情况: n <= 1 时返回 n
-- 2. 递归情况: fib(n-1) + fib(n-2)
--
-- 时间复杂度: O(2^n) - 指数级
-- 空间复杂度: O(n) - 递归栈深度
--
-- 优化建议:
-- - 使用备忘录优化到 O(n)
-- - 或使用迭代实现
"""

生成代码

" 在插入模式下:

-- 输入注释描述需求
-- 快速排序算法

" 按 \cg (leader + c + g)
:ClaudeGenerate

" 生成的代码自动插入到当前位置:
function quicksort(arr)
  if #arr <= 1 then
    return arr
  end

  local pivot = arr[1]
  local left = {}
  local right = {}

  for i = 2, #arr do
    if arr[i] < pivot then
      table.insert(left, arr[i])
    else
      table.insert(right, arr[i])
    end
  end

  local sorted_left = quicksort(left)
  local sorted_right = quicksort(right)

  table.insert(sorted_left, pivot)
  for _, v in ipairs(sorted_right) do
    table.insert(sorted_left, v)
  end

  return sorted_left
end

审查文件

" 在文件缓冲区中
:ClaudeReview

" Claude Code 分析整个文件并显示审查结果
" 结果在右侧窗口，包含:
" - 代码质量评分
" - 发现的问题（按严重性）
" - 改进建议
" - 重构示例

4.4 高级功能

与 Telescope 集成 (Neovim)

-- 使用 Telescope 搜索 Claude Code 历史
require('telescope').setup {
  extensions = {
    claude_code = {
      -- 配置
    }
  }
}

require('telescope').load_extension('claude_code')

-- 快捷键
vim.api.nvim_set_keymap('n', '<leader>ch',
  ':Telescope claude_code history<CR>',
  { noremap = true })

与 LSP 集成

-- 使用 LSP 符号进行更精确的代码分析
vim.api.nvim_set_keymap('n', '<leader>cs',
  ':ClaudeExplainSymbol<CR>',
  { noremap = true })

-- Claude 会使用 LSP 信息提供更准确的解释

---

5. Emacs 集成

5.1 安装和配置

使用 use-package:

;; ~/.emacs.d/init.el

(use-package claude-code
  :ensure t
  :init
  (setq claude-code-api-key "sk-ant-xxx...")
  :bind
  ("C-c c c" . claude-code-open)
  ("C-c c e" . claude-code-explain-region)
  ("C-c c g" . claude-code-generate)
  ("C-c c r" . claude-code-review-buffer))

手动配置:

;; 加载路径
(add-to-list 'load-path "~/.emacs.d/claude-code/")

;; 配置
(require 'claude-code)
(setq claude-code-api-key "sk-ant-xxx...")

;; 快捷键
(global-set-key (kbd "C-c c c") 'claude-code-open)
(global-set-key (kbd "C-c c e") 'claude-code-explain-region)
(global-set-key (kbd "C-c c g") 'claude-code-generate)

5.2 主要命令

命令	快捷键	说明
claude-code-open	C-c c c	打开 Claude Code 侧边栏
claude-code-explain-region	C-c c e	解释选中区域
claude-code-generate	C-c c g	生成代码
claude-code-review-buffer	C-c c r	审查当前缓冲区
claude-code-explain-symbol	C-c c s	解释光标下的符号
claude-code-optimize-region	C-c c o	优化选中代码

5.3 使用示例

与 Org Mode 集成

* 项目 TODO

# 在 Org Mode 文件中使用

# ** 代码生成

# 将光标放在下面这个位置，按 C-c c g

# TODO: 实现用户认证

# Claude Code 生成:

#+BEGIN_SRC javascript
function authenticate(username, password) {
  // 验证输入
  if (!username || !password) {
    throw new Error('Username and password required');
  }

  // 查询数据库
  const user = db.users.find({ username });

  if (!user) {
    throw new Error('User not found');
  }

  // 验证密码
  const isValid = bcrypt.compare(password, user.passwordHash);

  if (!isValid) {
    throw new Error('Invalid password');
  }

  // 生成 JWT
  const token = jwt.sign(
    { userId: user.id, username },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );

  return { token, user };
}
#+END_SRC

与 Magit 集成

;; 在 Magit 状态缓冲区中使用 Claude Code
(eval-after-load 'magit
  '(progn
     (magit-define-popup claude-code-popup
       "Popup console for claude-code commands."
       'magit-commands
       :options  '(
         (?r "Review" "claude-code-review-region"))
       :actions  '(
         (?e "Explain changes" "claude-code-explain-changes")
         (?c "Generate commit message" "claude-code-generate-commit"))))

---

6. 通信协议

6.1 WebSocket 通信

IDE ↔ Claude Code 通信

┌─────────────────────────────────────────┐
│  IDE (客户端)                         │
│  ├─ 建立 WebSocket 连接               │
│  └─ 发送 JSON 消息                    │
└──────────┬──────────────────────────────┘
           ↓
     ws://localhost:6789
           ↓
┌──────────┴──────────────────────────────┐
│  Claude Code Server (服务端)          │
│  ├─ 接收消息                          │
│  ├─ 处理请求                          │
│  └─ 发送响应                          │
└─────────────────────────────────────────┘

连接建立

// IDE 端 (TypeScript/JavaScript)

// 1. 连接 Claude Code 服务器
const ws = new WebSocket('ws://localhost:6789');

// 2. 监听连接事件
ws.on('open', () => {
  console.log('Connected to Claude Code');

  // 3. 发送认证
  ws.send(JSON.stringify({
    type: 'auth',
    apiKey: 'sk-ant-xxx...',
    sessionId: 'session_abc123'
  }));
});

// 4. 监听消息
ws.on('message', (data) => {
  const message = JSON.parse(data);

  switch (message.type) {
    case 'auth_ok':
      console.log('Authenticated');
      break;

    case 'response':
      console.log('Claude:', message.content);
      break;

    case 'error':
      console.error('Error:', message.error);
      break;

    case 'tool_call':
      // 执行工具调用
      executeTool(message.toolName, message.parameters);
      break;
  }
});

// 5. 发送查询
ws.send(JSON.stringify({
  type: 'query',
  prompt: 'Review this code',
  context: {
    code: selectedCode,
    filePath: currentFile
  }
}));

消息协议

// 消息类型定义

interface Message {
  type: string;
  timestamp: number;
}

// 认证消息
interface AuthMessage extends Message {
  type: 'auth';
  apiKey: string;
  sessionId?: string;
}

// 查询消息
interface QueryMessage extends Message {
  type: 'query';
  id: string;
  prompt: string;
  context?: {
    code: string;
    filePath: string;
    language?: string;
    selection?: {
      start: { line: number; character: number };
      end: { line: number; character: number };
    };
  };
  options?: {
    model?: string;
    maxTokens?: number;
    stream?: boolean;
  };
}

// 响应消息
interface ResponseMessage extends Message {
  type: 'response';
  id: string;
  content: string;
  done: boolean;
  usage?: {
    inputTokens: number;
    outputTokens: number;
  };
}

// 工具调用消息
interface ToolCallMessage extends Message {
  type: 'tool_call';
  toolName: string;
  toolId: string;
  parameters: any;
}

// 工具结果消息
interface ToolResultMessage extends Message {
  type: 'tool_result';
  toolName: string;
  toolId: string;
  result: any;
  error?: string;
}

// 错误消息
interface ErrorMessage extends Message {
  type: 'error';
  code: string;
  message: string;
  details?: any;
}

完整对话示例

// 1. 连接建立
ws.send({
  type: 'auth',
  apiKey: 'sk-ant-xxx'
});

// 2. 认证成功
ws.receive({
  type: 'auth_ok',
  sessionId: 'session_abc123',
  serverVersion: '2.0.0',
  timestamp: 1640995200000
});

// 3. 发送查询
ws.send({
  type: 'query',
  id: 'query_1',
  prompt: 'Review this function',
  context: {
    code: `function add(a, b) { return a + b; }`,
    filePath: '/app/src/math.js',
    language: 'javascript'
  },
  options: {
    model: 'claude-3-5-sonnet',
    stream: true
  }
});

// 4. 接收流式响应
ws.receive({
  type: 'response',
  id: 'query_1',
  content: 'I\'ll review this function',
  done: false
});

// 5. 工具调用
ws.receive({
  type: 'tool_call',
  toolName: 'read_file',
  toolId: 'tool_1',
  parameters: {
    file_path: '/app/src/math.js'
  }
});

// 6. IDE 执行工具并返回结果
ws.send({
  type: 'tool_result',
  toolName: 'read_file',
  toolId: 'tool_1',
  result: {
    content: 'function add(a, b) { return a + b; }',
    size: 45
  }
});

// 7. 接收最终结果
ws.receive({
  type: 'response',
  id: 'query_1',
  content: '完整的审查报告...',
  done: true,
  usage: {
    inputTokens: 250,
    outputTokens: 450
  }
});

6.2 HTTP API 通信

对于不支持 WebSocket 的 IDE 或需要简单的请求-响应模式：

// HTTP API 端点

// 基础 URL
const BASE_URL = 'http://localhost:6789/api/v1';

// 1. 查询端点
POST ${BASE_URL}/query
Headers: {
  'Authorization': 'Bearer sk-ant-xxx...',
  'Content-Type': 'application/json'
}
Body: {
  "prompt": "Review this code",
  "context": {
    "code": "function test() {}",
    "filePath": "/app/test.js"
  },
  "options": {
    "model": "claude-3-5-sonnet",
    "maxTokens": 4000
  }
}

Response: {
  "id": "query_123",
  "result": "代码审查结果...",
  "usage": {
    "inputTokens": 250,
    "outputTokens": 450
  },
  "toolCalls": 2
}

// 2. 会话管理
GET ${BASE_URL}/sessions
POST ${BASE_URL}/sessions
GET ${BASE_URL}/sessions/:sessionId
DELETE ${BASE_URL}/sessions/:sessionId

// 3. 工具执行
POST ${BASE_URL}/tools/execute
Body: {
  "toolName": "read_file",
  "parameters": {
    "file_path": "/app/src/index.js"
  }
}

// 4. 配置管理
GET ${BASE_URL}/config
PUT ${BASE_URL}/config

6.3 Language Server Protocol (LSP) 集成

LSP 体系结构

┌─────────────────────────────────────────┐
│  IDE (LSP 客户端)                      │
│  ├─ 启动 Claude Code LSP 服务器       │
│  └─ 发送 LSP 消息                      │
└──────────┬──────────────────────────────┘
           ↓
     stdio pipe
           ↓
┌──────────┴──────────────────────────────┐
│  Claude Code LSP 服务器                │
│  ├─ 接收 LSP 请求                      │
│  ├─ 执行工具调用                       │
│  └─ 返回 LSP 响应                      │
└─────────────────────────────────────────┘

LSP 初始化

// IDE → LSP Server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "processId": 12345,
    "rootPath": "/workspace/project",
    "capabilities": {
      "workspace": {
        "workspaceFolders": true,
        "configuration": true
      },
      "textDocument": {
        "hover": {
          "contentFormat": ["markdown", "plaintext"]
        },
        "definition": {
          "linkSupport": true
        }
      }
    },
    "initializationOptions": {
      "claudeCode": {
        "apiKey": "sk-ant-xxx...",
        "model": "claude-3-5-sonnet"
      }
    }
  }
}

// LSP Server → IDE
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "capabilities": {
      "textDocumentSync": {
        "openClose": true,
        "change": 2,
        "save": true
      },
      "hoverProvider": true,
      "definitionProvider": true,
      "referencesProvider": true,
      "documentSymbolProvider": true,
      "workspaceSymbolProvider": true,
      "codeActionProvider": true,
      "completionProvider": {
        "triggerCharacters": ["."]
      }
    },
    "serverInfo": {
      "name": "Claude Code LSP",
      "version": "2.0.0"
    }
  }
}

LSP 功能示例

Hover 文档:

// IDE → LSP
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "textDocument/hover",
  "params": {
    "textDocument": {
      "uri": "file:///workspace/src/utils.js"
    },
    "position": {
      "line": 10,
      "character": 5
    }
  }
}

// LSP → IDE
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": {
      "kind": "markdown",
      "value": "\`\`\`javascript\nfunction formatDate(date)\n\`\`\`\n\n格式化日期对象为 YYYY-MM-DD 格式\n\n**参数**: `date` - Date 对象\n**返回值**: 格式化后的日期字符串"
    }
  }
}

Jump to Definition:

// IDE → LSP
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "textDocument/definition",
  "params": {
    "textDocument": {
      "uri": "file:///workspace/src/app.js"
    },
    "position": {
      "line": 25,
      "character": 15
    }
  }
}

// LSP → IDE
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "uri": "file:///workspace/src/utils.js",
    "range": {
      "start": { "line": 8, "character": 0 },
      "end": { "line": 15, "character": 1 }
    }
  }
}

Code Completion:

// IDE → LSP
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "textDocument/completion",
  "params": {
    "textDocument": {
      "uri": "file:///workspace/src/app.js"
    },
    "position": {
      "line": 30,
      "character": 20
    }
  }
}

// LSP → IDE
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "items": [
      {
        "label": "calculateTotal",
        "kind": 3,  // Function
        "detail": "(items: CartItem[]): number",
        "documentation": {
          "kind": "markdown",
          "value": "计算购物车总价"
        }
      }
    ]
  }
}

---

7. LSP 集成

7.1 Claude Code LSP 特性

LSP 功能支持矩阵

┌─────────────────────────────────────────┐
│ 功能           │ 支持状态 │ 说明        │
├────────────────┼────────┼────────────┤
│ textDocumentSync │ ✅ 支持  │ 2 (增量)   │
│ hoverProvider    │ ✅ 支持  │            │
│ definition       │ ✅ 支持  │            │
│ references       │ ✅ 支持  │            │
│ documentSymbol   │ ✅ 支持  │            │
│ workspaceSymbol  │ ✅ 支持  │            │
│ codeAction       │ ✅ 支持  │            │
│ completion       │ ✅ 支持  │            │
│ rename           │ ⚠️ 部分  │            │
│ codeLens         │ ❌ 不支持│            │
│ inlayHints       │ ⚠️ 实验性│ 未来支持   │
└────────────────┴────────┴────────────┘

7.2 LSP 工具定义

// Claude Code 内置的 LSP 工具

interface LspTool {
  name: 'LSP';
  description: 'Language Server Protocol for code intelligence';
  input_schema: {
    operation: 'goToDefinition' | 'findReferences' | 'hover' |
               'documentSymbol' | 'workspaceSymbol' | 'codeAction';
    filePath: string;
    line: number;
    character: number;
  };
}

// 实际使用
await agent.query('Explain this function', {
  tools: ['LSP']
});
// Claude Code 会自动使用 LSP 获取符号信息

7.3 自定义 LSP 功能

添加代码诊断

// 自定义 LSP 服务器扩展

class ClaudeCodeLSPServer {
  // 诊断提供器
  async provideDiagnostics(document: TextDocument): Promise<Diagnostic[]> {
    const code = document.getText();

    // 使用 Claude Code 分析代码
    const analysis = await this.agent.query(
      `Analyze this code for issues:\n\n${code}`
    );

    // 解析结果并转换为 LSP Diagnostic
    return this.parseAnalysisToDiagnostics(analysis);
  }

  private parseAnalysisToDiagnostics(analysis: any): Diagnostic[] {
    const diagnostics: Diagnostic[] = [];

    // 解析审查结果
    if (analysis.issues) {
      for (const issue of analysis.issues) {
        diagnostics.push({
          range: {
            start: { line: issue.line - 1, character: 0 },
            end: { line: issue.line - 1, character: 100 }
          },
          severity: this.mapSeverity(issue.severity),
          message: issue.description,
          source: 'Claude Code'
        });
      }
    }

    return diagnostics;
  }
}

---

8. 高级功能

8.1 多 IDE 会话同步

// 在多个 IDE 中同步 Claude Code 会话

class MultiIDEIntegration {
  private sessionManager: SessionManager;
  private ideConnections: Map<string, IDEConnection>;

  async shareSession(sessionId: string, targetIDEs: string[]) {
    // 获取会话
    const session = await this.sessionManager.getSession(sessionId);

    // 广播到所有连接的 IDE
    for (const [ideId, connection] of this.ideConnections) {
      if (targetIDEs.includes(ideId)) {
        await connection.send({
          type: 'session_share',
          session: session.toJSON()
        });
      }
    }
  }

  async collaborativeCoding(sessionId: string) {
    // VS Code 用户添加功能
    await this.handleMessage({
      from: 'vscode',
      type: 'code_edit',
      file: '/app/src/auth.js',
      change: 'Add login function'
    });

    // JetBrains 用户立即看到并审查
    await this.handleMessage({
      from: 'jetbrains',
      type: 'review',
      content: 'Added security review comments'
    });

    // Vim 用户优化代码
    await this.handleMessage({
      from: 'vim',
      type: 'code_optimization',
      content: 'Optimized performance'
    });
  }
}

8.2 与 Git 集成增强

// Git 预提交钩子集成

// .git/hooks/pre-commit

#!/bin/bash

# 获取待提交文件
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.\(ts\|js\|py\|java\|cpp\)$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

# 启动 Claude Code 代码审查
echo "Running Claude Code review..."

# 调用 IDE 集成
claude-code review --files "$STAGED_FILES" --output review.json

# 检查结果
if grep -q '"critical"' review.json; then
  echo "❌ Critical issues found. Fix them before committing."
  cat review.json | jq '.issues[] | select(.severity == "critical")'
  exit 1
fi

if grep -q '"high"' review.json; then
  echo "⚠️  High severity issues found:"
  cat review.json | jq '.issues[] | select(.severity == "high")'
  echo ""
  echo "Continue anyway? (y/n)"
  read -r response
  if [[ ! "$response" =~ ^[Yy]$ ]]; then
    exit 1
  fi
fi

echo "✅ Review passed. Proceeding with commit."
exit 0

8.3 团队配置共享

// team-claude-config.json (Git 仓库)
{
  "team": "Frontend Team",
  "settings": {
    "model": "claude-3-5-sonnet",
    "maxTokens": 4000,
    "codingStandards": {
      "typescript": {
        "strictNullChecks": true,
        "noImplicitAny": true,
        "preferArrowFunctions": true
      },
      "javascript": {
        "useConst": true,
        "avoidVar": true,
        "preferDestructuring": true
      }
    },
    "reviewGuidelines": [
      "Check for security vulnerabilities",
      "Verify error handling",
      "Ensure test coverage",
      "Validate performance considerations"
    ],
    "hooks": {
      "preCommit": "claude-code-review",
      "postMerge": "claude-code-update-deps"
    }
  }
}

自动同步:

// IDE 启动时加载团队配置

async function loadTeamConfig() {
  const configPath = path.join(
    workspace.rootPath,
    'team-claude-config.json'
  );

  if (await fs.exists(configPath)) {
    const config = await fs.readJson(configPath);

    // 应用团队设置
    await claudeCode.setConfig({
      model: config.settings.model,
      codingStandards: config.settings.codingStandards,
      systemPrompt: `
You are ${config.team}'s coding assistant.

Coding Standards:
${JSON.stringify(config.settings.codingStandards, null, 2)}

Review Guidelines:
${config.settings.reviewGuidelines.join('\n')}
      `
    });

    console.log('✅ Team config loaded');
  }
}

---

9. 问题排查

9.1 连接问题

症状: 无法连接到 Claude Code

排查步骤:

# 1. 检查 Claude Code 是否运行
ps aux | grep claude-code

# 2. 检查端口是否监听
netstat -an | grep 6789

# 3. 检查网络连接
curl -v http://localhost:6789/health

# 4. 查看日志
tail -f ~/.claude/logs/server.log

# 5. 重启 Claude Code
claude-code --restart

常见错误:

错误: Connection refused
原因: Claude Code 服务器未启动
解决: 启动 Claude Code IDE 服务器

错误: Authentication failed
原因: API key 无效或过期
解决: 检查 ~/.claude/credentials

错误: Timeout
原因: 网络延迟或服务器负载高
解决: 增加超时设置

9.2 性能问题

症状: 响应慢、卡顿

解决方案:

// 优化设置
{
  "claudeCode.maxTokens": 2000,
  "claudeCode.streamResponse": true,
  "claudeCode.enableCaching": true,
  "claudeCode.maxParallelRequests": 3
}

# 监控资源使用
htop -p $(pgrep claude-code)

# 检查内存
claude-code --status

9.3 集成问题

症状: IDE 扩展无法正常工作

排查:

# VS Code
# 1. 检查输出面板
View → Output → Claude Code

# 2. 检查扩展日志
# Help → Toggle Developer Tools → Console

# 3. 重新加载窗口
Ctrl+Shift+P → "Developer: Reload Window"

# JetBrains
# 1. 检查日志
Help → Show Log in Finder

# 2. 禁用/启用插件
Settings → Plugins → Claude Code → Disable/Enable

# Vim/Neovim
# 1. 检查 :messages
# 2. 检查 :checkhealth
# 3. 重新加载配置
:source ~/.vimrc

---

10. 最佳实践

10.1 配置管理

# 1. 使用环境变量管理 API Key
echo 'export ANTHROPIC_API_KEY=sk-ant-xxx...' >> ~/.bashrc
source ~/.bashrc

# 2. 项目级别的配置
# 在项目根目录创建 .claude-config
{
  "model": "claude-3-5-sonnet",
  "maxTokens": 4000,
  "context": {
    "framework": "React",
    "language": "TypeScript",
    "patterns": [
      "src/components/**/*.tsx",
      "src/hooks/**/*.ts"
    ]
  }
}

10.2 快捷键定制

// 自定义快捷键
{
  "key": "ctrl+alt+c",
  "command": "claudeCode.customCommand",
  "args": {
    "prompt": "Review for security issues",
    "model": "claude-3-opus"
  }
}

10.3 工作流优化

高效工作流示例:

1. 代码编写阶段
   ├─ 使用 Claude Code 生成代码模板
   ├─ 内联代码补全和优化
   └─ 实时语法和逻辑检查

2. 代码审查阶段
   ├─ 选中代码 → 解释/审查
   ├─ 自动生成测试用例
   └─ 安全漏洞扫描

3. 调试阶段
   ├─ 错误解释和分析
   ├─ 修复建议
   └─ 性能优化

4. 提交阶段
   ├─ 预提交审查
   ├─ 自动生成提交信息
   └─ 代码质量检查

10.4 团队协作

# 1. 共享配置
# 将 .claude-config 加入 Git
.gitignore:
  # 排除 API key
  .env

  # 但包含配置
  !.claude-config

# 2. 代码审查集成
# 在 PR 模板中添加 Claude Code 检查清单

## Claude Code 审查
- [ ] 安全漏洞检查
- [ ] 代码质量检查
- [ ] 测试覆盖率
- [ ] 性能影响分析

# 3. 文档生成
# 使用 Claude Code 生成和更新文档
claude-code doc:generate
claude-code doc:update

10.5 安全和隐私

// 安全设置
{
  "claudeCode.enableTelemetry": false,
  "claudeCode.redactSensitiveData": true,
  "claudeCode.allowedFilePatterns": [
    "src/**/*.ts",
    "src/**/*.js",
    "tests/**/*.ts"
  ],
  "claudeCode.deniedFilePatterns": [
    ".env*",
    "**/*.key",
    "**/*.pem",
    "config/secrets/**/*"
  ]
}