LSP Integration

Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。

快速开始

1. 安装 LSP 插件

在 Claude Code REPL 中使用 /plugin 命令搜索并安装 LSP 插件：

/plugin

搜索 lsp，找到对应语言的插件（如 typescript-lsp），选择安装。安装后运行 /reload-plugins 使插件生效。 LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。

2. 启用 LSP Tool

LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询：

ENABLE_LSP_TOOL=1 bun run dev

不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。

自动推荐

除了手动 /plugin 搜索安装外，Claude Code 会在编辑文件时自动检测：

监听 fileHistory.trackedFiles，发现有新文件被编辑
扫描已安装的 marketplace，找到声明支持该文件扩展名的 LSP 插件
检查系统上是否已安装对应的 LSP 二进制（如 typescript-language-server）
满足条件时弹出推荐对话框，可选择安装

┌───── LSP Plugin Recommendation ─────────────┐
│                                               │
│  LSP provides code intelligence like          │
│  go-to-definition and error checking          │
│                                               │
│  Plugin: typescript-lsp                       │
│  Triggered by: .ts files                     │
│                                               │
│  Would you like to install this LSP plugin?   │
│                                               │
│  > Yes, install typescript-lsp               │
│    No, not now                                │
│    Never for typescript-lsp                   │
│    Disable all LSP recommendations            │
└───────────────────────────────────────────────┘

30 秒不操作自动关闭（算作 “No”）
选 “Never” 不再推荐该插件
选 “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)

被动诊断反馈

LSP Server ──publishDiagnostics──▶ passiveFeedback.ts
                                          │
                                          ▼
                                   LSPDiagnosticRegistry
                                   (去重、容量限制)
                                          │
                                          ▼
                                   Attachment System
                                   (异步注入到对话)

LSP 服务器会异步推送 textDocument/publishDiagnostics 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。

核心模块

文件	职责
`src/services/lsp/manager.ts`	全局单例，初始化/重初始化/关闭生命周期管理
`src/services/lsp/LSPServerManager.ts`	多服务器管理，按文件扩展名路由，文件同步
`src/services/lsp/LSPServerInstance.ts`	单个 LSP 服务器实例生命周期（启动/停止/重启/健康检查）
`src/services/lsp/LSPClient.ts`	JSON-RPC 通信层（基于 `vscode-jsonrpc`），子进程管理
`src/services/lsp/config.ts`	从插件加载 LSP 服务器配置
`src/services/lsp/LSPDiagnosticRegistry.ts`	诊断信息注册、去重、容量限制
`src/services/lsp/passiveFeedback.ts`	注册 `publishDiagnostics` 通知处理器
`packages/builtin-tools/src/tools/LSPTool/LSPTool.ts`	LSP Tool 实现（暴露给 Claude）
`packages/builtin-tools/src/tools/LSPTool/schemas.ts`	输入 schema（9 种操作的 discriminated union）
`packages/builtin-tools/src/tools/LSPTool/formatters.ts`	各操作结果的格式化
`packages/builtin-tools/src/tools/LSPTool/prompt.ts`	Tool 描述文本
`src/utils/plugins/lspPluginIntegration.ts`	从插件加载、验证、环境变量解析、作用域管理

LSP Tool 支持的操作

操作	LSP Method	说明
`goToDefinition`	`textDocument/definition`	跳转到符号定义
`findReferences`	`textDocument/references`	查找所有引用
`hover`	`textDocument/hover`	获取悬停信息（文档、类型）
`documentSymbol`	`textDocument/documentSymbol`	获取文档内所有符号
`workspaceSymbol`	`workspace/symbol`	全工作区符号搜索
`goToImplementation`	`textDocument/implementation`	查找接口/抽象方法的实现
`prepareCallHierarchy`	`textDocument/prepareCallHierarchy`	获取位置处的调用层级项
`incomingCalls`	`callHierarchy/incomingCalls`	查找调用此函数的所有函数
`outgoingCalls`	`callHierarchy/outgoingCalls`	查找此函数调用的所有函数

所有操作需要 filePath、line（1-based）和 character（1-based）参数。

插件开发：LSP 服务器配置

LSP 服务器通过插件提供。插件的 manifest.json 中可以声明 LSP 服务器，支持三种格式： 1. 内联配置（在 manifest 中直接定义）

{
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".ts": "typescript",
        ".tsx": "typescriptreact"
      }
    }
  }
}

2. 引用外部 .lsp.json 文件

{
  "lspServers": "path/to/.lsp.json"
}

3. 数组混合格式

{
  "lspServers": [
    "path/to/.lsp.json",
    {
      "another-server": { "command": "...", "extensionToLanguage": { "...": "..." } }
    }
  ]
}

也可以在插件目录下直接放置 .lsp.json 文件，无需在 manifest 中声明。

LSP 服务器配置 Schema

字段	类型	必填	说明
`command`	string	是	LSP 服务器可执行命令（不含空格）
`args`	string[]	否	命令行参数
`extensionToLanguage`	`Record<string, string>`	是	文件扩展名到语言 ID 的映射（至少一个）
`transport`	`"stdio"` \| `"socket"`	否	通信方式，默认 `stdio`
`env`	`Record<string, string>`	否	启动服务器时设置的环境变量
`initializationOptions`	unknown	否	传给服务器的初始化选项
`settings`	unknown	否	通过 `workspace/didChangeConfiguration` 传递的设置
`workspaceFolder`	string	否	工作区目录路径
`startupTimeout`	number	否	启动超时时间（毫秒）
`maxRestarts`	number	否	最大重启次数（默认 3）

环境变量替换

配置中的 command、args、env、workspaceFolder 支持：

${CLAUDE_PLUGIN_ROOT} — 插件根目录
${CLAUDE_PLUGIN_DATA} — 插件数据目录
${user_config.KEY} — 用户在插件启用时配置的值
${VAR} — 系统环境变量

生命周期管理

服务器状态机

stopped → starting → running
running → stopping → stopped
any     → error (失败时)
error   → starting (重试时)

崩溃恢复

LSP 服务器崩溃时状态设为 error
下次请求时自动尝试重启（通过 ensureServerStarted）
超过 maxRestarts（默认 3）次后放弃

瞬态错误重试

ContentModified 错误（LSP 错误码 -32801）会自动重试，最多 3 次
使用指数退避：500ms → 1000ms → 2000ms
常见于 rust-analyzer 等仍在索引项目的服务器

诊断信息容量限制

每个文件最多 10 条诊断
总计最多 30 条诊断
超出部分按严重性排序后截断（Error > Warning > Info > Hint）
跨 turn 去重：已发送过的相同诊断不会重复发送
文件编辑后清除该文件的已发送记录，允许新诊断通过

插件刷新

安装/卸载插件后使用 /reload-plugins，会调用 reinitializeLspServerManager()：

异步关闭旧服务器实例
重置状态为 not-started
调用 initializeLspServerManager() 重新加载插件配置

依赖

vscode-jsonrpc — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require）
vscode-languageserver-protocol — LSP 协议类型
vscode-languageserver-types — LSP 类型定义
lru-cache — 诊断去重缓存

开始

对话是如何运转的

工具：AI 的双手

上下文工程

多 Agent 协作

可扩展性

安全与权限

揭秘：隐藏功能与内部机制

隐藏功能详解

基础设施与依赖

Lsp integration

LSP Integration

快速开始

1. 安装 LSP 插件

2. 启用 LSP Tool

自动推荐

架构概览

被动诊断反馈

核心模块

LSP Tool 支持的操作

插件开发：LSP 服务器配置

LSP 服务器配置 Schema

环境变量替换

生命周期管理

服务器状态机

崩溃恢复

瞬态错误重试

诊断信息容量限制

插件刷新

依赖

开始

对话是如何运转的

工具：AI 的双手

上下文工程

多 Agent 协作

可扩展性

安全与权限

揭秘：隐藏功能与内部机制

隐藏功能详解

基础设施与依赖

Documentation Index

​LSP Integration

​快速开始

​1. 安装 LSP 插件

​2. 启用 LSP Tool

​自动推荐

​架构概览

​被动诊断反馈

​核心模块

​LSP Tool 支持的操作

​插件开发：LSP 服务器配置

​LSP 服务器配置 Schema

​环境变量替换

​生命周期管理

​服务器状态机

​崩溃恢复

​瞬态错误重试

​诊断信息容量限制

​插件刷新

​依赖

LSP Integration

快速开始

1. 安装 LSP 插件

2. 启用 LSP Tool

自动推荐

架构概览

被动诊断反馈

核心模块

LSP Tool 支持的操作

插件开发：LSP 服务器配置

LSP 服务器配置 Schema

环境变量替换

生命周期管理

服务器状态机

崩溃恢复

瞬态错误重试

诊断信息容量限制

插件刷新

依赖