vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,10 +1,19 @@
|
||||
---
|
||||
tags: [claude-code, LSP, 代码智能, 插件, 语言服务器]
|
||||
create time: 2026-06-09 22:30
|
||||
---
|
||||
|
||||
# LSP Integration
|
||||
|
||||
Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。
|
||||
## 概述
|
||||
|
||||
## 快速开始
|
||||
Claude Code 内置了 Language Server Protocol (LSP) 集成，通过插件机制提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。LSP 服务器以子进程方式运行，通过 JSON-RPC 通信，支持崩溃恢复和瞬态错误重试。
|
||||
|
||||
### 1. 安装 LSP 插件
|
||||
## 正文
|
||||
|
||||
### 快速开始
|
||||
|
||||
#### 1. 安装 LSP 插件
|
||||
|
||||
在 Claude Code REPL 中使用 `/plugin` 命令搜索并安装 LSP 插件：
|
||||
|
||||
@@ -18,7 +27,7 @@ Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能
|
||||
|
||||
LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。
|
||||
|
||||
### 2. 启用 LSP Tool
|
||||
#### 2. 启用 LSP Tool
|
||||
|
||||
LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询：
|
||||
|
||||
@@ -26,9 +35,10 @@ LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码
|
||||
ENABLE_LSP_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。
|
||||
> [!info] 被动诊断不受影响
|
||||
> 不启用 LSP Tool 时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。
|
||||
|
||||
## 自动推荐
|
||||
### 自动推荐
|
||||
|
||||
除了手动 `/plugin` 搜索安装外，Claude Code 会在编辑文件时自动检测：
|
||||
|
||||
@@ -60,64 +70,36 @@ ENABLE_LSP_TOOL=1 bun run dev
|
||||
- 选 "Disable" 关闭所有 LSP 推荐
|
||||
- 连续忽略 5 次后自动禁用推荐
|
||||
|
||||
## 架构概览
|
||||
### 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ LSP Tool │
|
||||
│ packages/builtin-tools/src/tools/LSPTool/LSPTool.ts│
|
||||
│ (Claude 可调用的工具，9 种操作) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (Singleton) │
|
||||
│ src/services/lsp/manager.ts │
|
||||
│ - initializeLspServerManager() │
|
||||
│ - reinitializeLspServerManager() │
|
||||
│ - shutdownLspServerManager() │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (实例) │
|
||||
│ src/services/lsp/LSPServerManager.ts │
|
||||
│ - 管理多个 LSPServerInstance │
|
||||
│ - 按文件扩展名路由请求 │
|
||||
│ - 文件同步 (didOpen/didChange/didSave/didClose) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ LSPServer │ │ LSPServer │ │ LSPServer │
|
||||
│ Instance │ │ Instance │ │ Instance │
|
||||
│ (typescript) │ │ (python) │ │ (rust...) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
|
||||
│ LSPClient │ │ LSPClient │ │ LSPClient │
|
||||
│ (JSON-RPC) │ │ (JSON-RPC) │ │ (JSON-RPC) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
子进程 (stdio) 子进程 (stdio) 子进程 (stdio)
|
||||
```mermaid
|
||||
graph TD
|
||||
A["LSP Tool<br/>packages/builtin-tools/src/tools/LSPTool/LSPTool.ts<br/>Claude 可调用的工具，9 种操作"]
|
||||
A --> B["LSP Server Manager（Singleton）<br/>src/services/lsp/manager.ts<br/>initializeLspServerManager / reinitialize / shutdown"]
|
||||
B --> C["LSP Server Manager（实例）<br/>src/services/lsp/LSPServerManager.ts<br/>管理多个 LSPServerInstance，按文件扩展名路由请求，文件同步"]
|
||||
C --> D["LSPServer Instance<br/>(typescript)"]
|
||||
C --> E["LSPServer Instance<br/>(python)"]
|
||||
C --> F["LSPServer Instance<br/>(rust...)"]
|
||||
D --> G["LSPClient<br/>(JSON-RPC)"]
|
||||
E --> H["LSPClient<br/>(JSON-RPC)"]
|
||||
F --> I["LSPClient<br/>(JSON-RPC)"]
|
||||
G --> J["子进程 (stdio)"]
|
||||
H --> K["子进程 (stdio)"]
|
||||
I --> L["子进程 (stdio)"]
|
||||
```
|
||||
|
||||
### 被动诊断反馈
|
||||
#### 被动诊断反馈
|
||||
|
||||
```
|
||||
LSP Server ──publishDiagnostics──▶ passiveFeedback.ts
|
||||
│
|
||||
▼
|
||||
LSPDiagnosticRegistry
|
||||
(去重、容量限制)
|
||||
│
|
||||
▼
|
||||
Attachment System
|
||||
(异步注入到对话)
|
||||
```mermaid
|
||||
graph LR
|
||||
A["LSP Server"] -->|publishDiagnostics| B["passiveFeedback.ts"]
|
||||
B --> C["LSPDiagnosticRegistry<br/>去重、容量限制"]
|
||||
C --> D["Attachment System<br/>异步注入到对话"]
|
||||
```
|
||||
|
||||
LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。
|
||||
|
||||
## 核心模块
|
||||
### 核心模块
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
@@ -134,7 +116,7 @@ LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去
|
||||
| `packages/builtin-tools/src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
|
||||
| `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |
|
||||
|
||||
## LSP Tool 支持的操作
|
||||
### LSP Tool 支持的操作
|
||||
|
||||
| 操作 | LSP Method | 说明 |
|
||||
|------|-----------|------|
|
||||
@@ -148,9 +130,10 @@ LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去
|
||||
| `incomingCalls` | `callHierarchy/incomingCalls` | 查找调用此函数的所有函数 |
|
||||
| `outgoingCalls` | `callHierarchy/outgoingCalls` | 查找此函数调用的所有函数 |
|
||||
|
||||
所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。
|
||||
> [!tip] 参数说明
|
||||
> 所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。
|
||||
|
||||
## 插件开发：LSP 服务器配置
|
||||
### 插件开发：LSP 服务器配置
|
||||
|
||||
LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP 服务器，支持三种格式：
|
||||
|
||||
@@ -194,7 +177,7 @@ LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP
|
||||
|
||||
也可以在插件目录下直接放置 `.lsp.json` 文件，无需在 manifest 中声明。
|
||||
|
||||
### LSP 服务器配置 Schema
|
||||
#### LSP 服务器配置 Schema
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
@@ -209,7 +192,7 @@ LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP
|
||||
| `startupTimeout` | number | 否 | 启动超时时间（毫秒） |
|
||||
| `maxRestarts` | number | 否 | 最大重启次数（默认 3） |
|
||||
|
||||
### 环境变量替换
|
||||
#### 环境变量替换
|
||||
|
||||
配置中的 `command`、`args`、`env`、`workspaceFolder` 支持：
|
||||
|
||||
@@ -218,30 +201,34 @@ LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP
|
||||
- `${user_config.KEY}` — 用户在插件启用时配置的值
|
||||
- `${VAR}` — 系统环境变量
|
||||
|
||||
## 生命周期管理
|
||||
### 生命周期管理
|
||||
|
||||
### 服务器状态机
|
||||
#### 服务器状态机
|
||||
|
||||
```
|
||||
stopped → starting → running
|
||||
running → stopping → stopped
|
||||
any → error (失败时)
|
||||
error → starting (重试时)
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> stopped
|
||||
stopped --> starting
|
||||
starting --> running
|
||||
running --> stopping
|
||||
stopping --> stopped
|
||||
any --> error: 失败时
|
||||
error --> starting: 重试时
|
||||
```
|
||||
|
||||
### 崩溃恢复
|
||||
#### 崩溃恢复
|
||||
|
||||
- LSP 服务器崩溃时状态设为 `error`
|
||||
- 下次请求时自动尝试重启（通过 `ensureServerStarted`）
|
||||
- 超过 `maxRestarts`（默认 3）次后放弃
|
||||
|
||||
### 瞬态错误重试
|
||||
#### 瞬态错误重试
|
||||
|
||||
- `ContentModified` 错误（LSP 错误码 -32801）会自动重试，最多 3 次
|
||||
- 使用指数退避：500ms → 1000ms → 2000ms
|
||||
- 常见于 rust-analyzer 等仍在索引项目的服务器
|
||||
|
||||
### 诊断信息容量限制
|
||||
#### 诊断信息容量限制
|
||||
|
||||
- 每个文件最多 10 条诊断
|
||||
- 总计最多 30 条诊断
|
||||
@@ -249,16 +236,22 @@ error → starting (重试时)
|
||||
- 跨 turn 去重：已发送过的相同诊断不会重复发送
|
||||
- 文件编辑后清除该文件的已发送记录，允许新诊断通过
|
||||
|
||||
### 插件刷新
|
||||
#### 插件刷新
|
||||
|
||||
安装/卸载插件后使用 `/reload-plugins`，会调用 `reinitializeLspServerManager()`：
|
||||
1. 异步关闭旧服务器实例
|
||||
2. 重置状态为 `not-started`
|
||||
3. 调用 `initializeLspServerManager()` 重新加载插件配置
|
||||
|
||||
## 依赖
|
||||
### 依赖
|
||||
|
||||
- `vscode-jsonrpc` — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require）
|
||||
- `vscode-languageserver-protocol` — LSP 协议类型
|
||||
- `vscode-languageserver-types` — LSP 类型定义
|
||||
- `lru-cache` — 诊断去重缓存
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[auto-updater]] — 自动更新机制（插件更新相关）
|
||||
- [[performance-reporter]] — 性能报告（LSP 服务器性能影响）
|
||||
- [[memory-leak-audit]] — 内存泄漏排查（LSP Opened Files Map 泄漏修复）
|
||||
|
||||
Reference in New Issue
Block a user