|
| 1 | +# LSP Integration |
| 2 | + |
| 3 | +Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。 |
| 4 | + |
| 5 | +## 快速开始 |
| 6 | + |
| 7 | +### 1. 安装 LSP 插件 |
| 8 | + |
| 9 | +在 Claude Code REPL 中使用 `/plugin` 命令搜索并安装 LSP 插件： |
| 10 | + |
| 11 | +``` |
| 12 | +/plugin |
| 13 | +``` |
| 14 | + |
| 15 | +搜索 `lsp`，找到对应语言的插件（如 `typescript-lsp`），选择安装。 |
| 16 | + |
| 17 | +安装后运行 `/reload-plugins` 使插件生效。 |
| 18 | + |
| 19 | +LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。 |
| 20 | + |
| 21 | +### 2. 启用 LSP Tool |
| 22 | + |
| 23 | +LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询： |
| 24 | + |
| 25 | +```bash |
| 26 | +ENABLE_LSP_TOOL=1 bun run dev |
| 27 | +``` |
| 28 | + |
| 29 | +不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。 |
| 30 | + |
| 31 | +## 自动推荐 |
| 32 | + |
| 33 | +除了手动 `/plugin` 搜索安装外，Claude Code 会在编辑文件时自动检测： |
| 34 | + |
| 35 | +1. 监听 `fileHistory.trackedFiles`，发现有新文件被编辑 |
| 36 | +2. 扫描已安装的 marketplace，找到声明支持该文件扩展名的 LSP 插件 |
| 37 | +3. 检查系统上是否已安装对应的 LSP 二进制（如 `typescript-language-server`） |
| 38 | +4. 满足条件时弹出推荐对话框，可选择安装 |
| 39 | + |
| 40 | +``` |
| 41 | +┌───── LSP Plugin Recommendation ─────────────┐ |
| 42 | +│ │ |
| 43 | +│ LSP provides code intelligence like │ |
| 44 | +│ go-to-definition and error checking │ |
| 45 | +│ │ |
| 46 | +│ Plugin: typescript-lsp │ |
| 47 | +│ Triggered by: .ts files │ |
| 48 | +│ │ |
| 49 | +│ Would you like to install this LSP plugin? │ |
| 50 | +│ │ |
| 51 | +│ > Yes, install typescript-lsp │ |
| 52 | +│ No, not now │ |
| 53 | +│ Never for typescript-lsp │ |
| 54 | +│ Disable all LSP recommendations │ |
| 55 | +└───────────────────────────────────────────────┘ |
| 56 | +``` |
| 57 | + |
| 58 | +- 30 秒不操作自动关闭（算作 "No"） |
| 59 | +- 选 "Never" 不再推荐该插件 |
| 60 | +- 选 "Disable" 关闭所有 LSP 推荐 |
| 61 | +- 连续忽略 5 次后自动禁用推荐 |
| 62 | + |
| 63 | +## 架构概览 |
| 64 | + |
| 65 | +``` |
| 66 | +┌─────────────────────────────────────────────────────┐ |
| 67 | +│ LSP Tool │ |
| 68 | +│ src/tools/LSPTool/LSPTool.ts │ |
| 69 | +│ (Claude 可调用的工具，9 种操作) │ |
| 70 | +└──────────────────────┬──────────────────────────────┘ |
| 71 | + │ |
| 72 | +┌──────────────────────▼──────────────────────────────┐ |
| 73 | +│ LSP Server Manager (Singleton) │ |
| 74 | +│ src/services/lsp/manager.ts │ |
| 75 | +│ - initializeLspServerManager() │ |
| 76 | +│ - reinitializeLspServerManager() │ |
| 77 | +│ - shutdownLspServerManager() │ |
| 78 | +└──────────────────────┬──────────────────────────────┘ |
| 79 | + │ |
| 80 | +┌──────────────────────▼──────────────────────────────┐ |
| 81 | +│ LSP Server Manager (实例) │ |
| 82 | +│ src/services/lsp/LSPServerManager.ts │ |
| 83 | +│ - 管理多个 LSPServerInstance │ |
| 84 | +│ - 按文件扩展名路由请求 │ |
| 85 | +│ - 文件同步 (didOpen/didChange/didSave/didClose) │ |
| 86 | +└──────────────────────┬──────────────────────────────┘ |
| 87 | + │ |
| 88 | + ┌─────────────┼─────────────┐ |
| 89 | + ▼ ▼ ▼ |
| 90 | +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ |
| 91 | +│ LSPServer │ │ LSPServer │ │ LSPServer │ |
| 92 | +│ Instance │ │ Instance │ │ Instance │ |
| 93 | +│ (typescript) │ │ (python) │ │ (rust...) │ |
| 94 | +└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ |
| 95 | + │ │ │ |
| 96 | +┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐ |
| 97 | +│ LSPClient │ │ LSPClient │ │ LSPClient │ |
| 98 | +│ (JSON-RPC) │ │ (JSON-RPC) │ │ (JSON-RPC) │ |
| 99 | +└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ |
| 100 | + │ │ │ |
| 101 | + 子进程 (stdio) 子进程 (stdio) 子进程 (stdio) |
| 102 | +``` |
| 103 | + |
| 104 | +### 被动诊断反馈 |
| 105 | + |
| 106 | +``` |
| 107 | +LSP Server ──publishDiagnostics──▶ passiveFeedback.ts |
| 108 | + │ |
| 109 | + ▼ |
| 110 | + LSPDiagnosticRegistry |
| 111 | + (去重、容量限制) |
| 112 | + │ |
| 113 | + ▼ |
| 114 | + Attachment System |
| 115 | + (异步注入到对话) |
| 116 | +``` |
| 117 | + |
| 118 | +LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。 |
| 119 | + |
| 120 | +## 核心模块 |
| 121 | + |
| 122 | +| 文件 | 职责 | |
| 123 | +|------|------| |
| 124 | +| `src/services/lsp/manager.ts` | 全局单例，初始化/重初始化/关闭生命周期管理 | |
| 125 | +| `src/services/lsp/LSPServerManager.ts` | 多服务器管理，按文件扩展名路由，文件同步 | |
| 126 | +| `src/services/lsp/LSPServerInstance.ts` | 单个 LSP 服务器实例生命周期（启动/停止/重启/健康检查） | |
| 127 | +| `src/services/lsp/LSPClient.ts` | JSON-RPC 通信层（基于 `vscode-jsonrpc`），子进程管理 | |
| 128 | +| `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 | |
| 129 | +| `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 | |
| 130 | +| `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 | |
| 131 | +| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） | |
| 132 | +| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） | |
| 133 | +| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 | |
| 134 | +| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 | |
| 135 | +| `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 | |
| 136 | + |
| 137 | +## LSP Tool 支持的操作 |
| 138 | + |
| 139 | +| 操作 | LSP Method | 说明 | |
| 140 | +|------|-----------|------| |
| 141 | +| `goToDefinition` | `textDocument/definition` | 跳转到符号定义 | |
| 142 | +| `findReferences` | `textDocument/references` | 查找所有引用 | |
| 143 | +| `hover` | `textDocument/hover` | 获取悬停信息（文档、类型） | |
| 144 | +| `documentSymbol` | `textDocument/documentSymbol` | 获取文档内所有符号 | |
| 145 | +| `workspaceSymbol` | `workspace/symbol` | 全工作区符号搜索 | |
| 146 | +| `goToImplementation` | `textDocument/implementation` | 查找接口/抽象方法的实现 | |
| 147 | +| `prepareCallHierarchy` | `textDocument/prepareCallHierarchy` | 获取位置处的调用层级项 | |
| 148 | +| `incomingCalls` | `callHierarchy/incomingCalls` | 查找调用此函数的所有函数 | |
| 149 | +| `outgoingCalls` | `callHierarchy/outgoingCalls` | 查找此函数调用的所有函数 | |
| 150 | + |
| 151 | +所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。 |
| 152 | + |
| 153 | +## 插件开发：LSP 服务器配置 |
| 154 | + |
| 155 | +LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP 服务器，支持三种格式： |
| 156 | + |
| 157 | +**1. 内联配置（在 manifest 中直接定义）** |
| 158 | + |
| 159 | +```json |
| 160 | +{ |
| 161 | + "lspServers": { |
| 162 | + "typescript": { |
| 163 | + "command": "typescript-language-server", |
| 164 | + "args": ["--stdio"], |
| 165 | + "extensionToLanguage": { |
| 166 | + ".ts": "typescript", |
| 167 | + ".tsx": "typescriptreact" |
| 168 | + } |
| 169 | + } |
| 170 | + } |
| 171 | +} |
| 172 | +``` |
| 173 | + |
| 174 | +**2. 引用外部 .lsp.json 文件** |
| 175 | + |
| 176 | +```json |
| 177 | +{ |
| 178 | + "lspServers": "path/to/.lsp.json" |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +**3. 数组混合格式** |
| 183 | + |
| 184 | +```json |
| 185 | +{ |
| 186 | + "lspServers": [ |
| 187 | + "path/to/.lsp.json", |
| 188 | + { |
| 189 | + "another-server": { "command": "...", "extensionToLanguage": { "...": "..." } } |
| 190 | + } |
| 191 | + ] |
| 192 | +} |
| 193 | +``` |
| 194 | + |
| 195 | +也可以在插件目录下直接放置 `.lsp.json` 文件，无需在 manifest 中声明。 |
| 196 | + |
| 197 | +### LSP 服务器配置 Schema |
| 198 | + |
| 199 | +| 字段 | 类型 | 必填 | 说明 | |
| 200 | +|------|------|------|------| |
| 201 | +| `command` | string | 是 | LSP 服务器可执行命令（不含空格） | |
| 202 | +| `args` | string[] | 否 | 命令行参数 | |
| 203 | +| `extensionToLanguage` | Record<string, string> | 是 | 文件扩展名到语言 ID 的映射（至少一个） | |
| 204 | +| `transport` | `"stdio"` \| `"socket"` | 否 | 通信方式，默认 `stdio` | |
| 205 | +| `env` | Record<string, string> | 否 | 启动服务器时设置的环境变量 | |
| 206 | +| `initializationOptions` | unknown | 否 | 传给服务器的初始化选项 | |
| 207 | +| `settings` | unknown | 否 | 通过 `workspace/didChangeConfiguration` 传递的设置 | |
| 208 | +| `workspaceFolder` | string | 否 | 工作区目录路径 | |
| 209 | +| `startupTimeout` | number | 否 | 启动超时时间（毫秒） | |
| 210 | +| `maxRestarts` | number | 否 | 最大重启次数（默认 3） | |
| 211 | + |
| 212 | +### 环境变量替换 |
| 213 | + |
| 214 | +配置中的 `command`、`args`、`env`、`workspaceFolder` 支持： |
| 215 | + |
| 216 | +- `${CLAUDE_PLUGIN_ROOT}` — 插件根目录 |
| 217 | +- `${CLAUDE_PLUGIN_DATA}` — 插件数据目录 |
| 218 | +- `${user_config.KEY}` — 用户在插件启用时配置的值 |
| 219 | +- `${VAR}` — 系统环境变量 |
| 220 | + |
| 221 | +## 生命周期管理 |
| 222 | + |
| 223 | +### 服务器状态机 |
| 224 | + |
| 225 | +``` |
| 226 | +stopped → starting → running |
| 227 | +running → stopping → stopped |
| 228 | +any → error (失败时) |
| 229 | +error → starting (重试时) |
| 230 | +``` |
| 231 | + |
| 232 | +### 崩溃恢复 |
| 233 | + |
| 234 | +- LSP 服务器崩溃时状态设为 `error` |
| 235 | +- 下次请求时自动尝试重启（通过 `ensureServerStarted`） |
| 236 | +- 超过 `maxRestarts`（默认 3）次后放弃 |
| 237 | + |
| 238 | +### 瞬态错误重试 |
| 239 | + |
| 240 | +- `ContentModified` 错误（LSP 错误码 -32801）会自动重试，最多 3 次 |
| 241 | +- 使用指数退避：500ms → 1000ms → 2000ms |
| 242 | +- 常见于 rust-analyzer 等仍在索引项目的服务器 |
| 243 | + |
| 244 | +### 诊断信息容量限制 |
| 245 | + |
| 246 | +- 每个文件最多 10 条诊断 |
| 247 | +- 总计最多 30 条诊断 |
| 248 | +- 超出部分按严重性排序后截断（Error > Warning > Info > Hint） |
| 249 | +- 跨 turn 去重：已发送过的相同诊断不会重复发送 |
| 250 | +- 文件编辑后清除该文件的已发送记录，允许新诊断通过 |
| 251 | + |
| 252 | +### 插件刷新 |
| 253 | + |
| 254 | +安装/卸载插件后使用 `/reload-plugins`，会调用 `reinitializeLspServerManager()`： |
| 255 | +1. 异步关闭旧服务器实例 |
| 256 | +2. 重置状态为 `not-started` |
| 257 | +3. 调用 `initializeLspServerManager()` 重新加载插件配置 |
| 258 | + |
| 259 | +## 依赖 |
| 260 | + |
| 261 | +- `vscode-jsonrpc` — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require） |
| 262 | +- `vscode-languageserver-protocol` — LSP 协议类型 |
| 263 | +- `vscode-languageserver-types` — LSP 类型定义 |
| 264 | +- `lru-cache` — 诊断去重缓存 |
0 commit comments