LSPTool：语言服务接入

在前面的文章中，我们详细剖析了 MCPTool 如何通过 Model Context Protocol 连接外部数据源和工具生态。然而，对于一款 AI 编程助手而言，真正理解代码的语义结构——变量类型、函数定义、类继承关系——才是其核心竞争力的关键所在。本章将深入解析 Claude Code 的 LSPTool，探索它是如何通过 Language Server Protocol（LSP） 接入语言服务，为 AI 模型提供精准的代码智能（Code Intelligence）。

一、LSP 协议简介

1.1 Language Server Protocol 是什么

Language Server Protocol 是由微软于 2016 年推出的开源协议，旨在标准化编辑器/IDE 与语言服务之间的通信方式。在 LSP 出现之前，每种编辑器都需要为每种编程语言单独实现语法高亮、自动补全、定义跳转等功能，造成了大量的重复劳动。LSP 通过定义一套基于 JSON-RPC 的通信规范，让语言服务器（Language Server）专注于语言分析，而客户端（Client）只需实现一次协议即可支持所有语言。

LSP 协议的核心通信模型非常简单：客户端向语言服务器发送请求（Request），服务器处理后返回响应（Response）；同时服务器也可以主动向客户端推送通知（Notification），比如代码诊断信息。这种双向通信机制使得编辑器能够实时获取代码分析结果，而无需关心底层语言的解析细节。

1.2 LSP 与 MCP 的区别和互补

在 Claude Code 的工具生态中，LSPTool 和 MCPTool 分别代表了两种不同维度的外部能力接入：

维度	LSPTool（LSP）	MCPTool（MCP）
定位	代码语义理解与语言分析	外部工具、数据源、API 调用
通信协议	JSON-RPC over stdio	stdio / SSE / WebSocket
核心能力	定义跳转、类型推断、诊断、补全	文件系统、数据库、Web 搜索
信息粒度	符号级别（AST 节点）	资源级别（文件、记录、页面）
时效性	实时（随代码编辑同步）	按需（工具调用时获取）
典型场景	"这个函数在哪里定义的？"	"查询当前项目的 Jira 任务"

两者的关系是互补而非替代。MCP 为 Claude Code 打开了外部世界的大门，使其能够访问代码仓库之外的上下文；而 LSP 则让 Claude Code 深入理解代码本身的语义结构。当 AI 模型需要回答 "这个接口有哪些实现类？" 时，LSP 提供了精确的符号导航能力；当需要回答 "这个 bug 对应的 Jira ticket 是什么？" 时，MCP 派上了用场。

1.3 Claude Code 为什么要接入 LSP

Claude Code 作为终端中的 AI 编程助手，其原生能力基于文本分析和模式匹配，但这对于复杂的代码库往往不够。接入 LSP 带来了三大核心价值：

1. 精准的代码导航：通过 goToDefinition、findReferences 等操作，AI 能够准确追踪符号的依赖关系，而不是依赖简单的文本搜索。
2. 实时代码诊断：语言服务器持续分析代码，通过 textDocument/publishDiagnostics 通知推送错误和警告，让 AI 在回答问题前就知晓代码的健康状况。
3. 类型感知：hover 操作提供变量的类型信息和文档注释，帮助 AI 理解代码的语义，而非仅仅看到语法表面。

// 源码文件：src/tools/LSPTool/prompt.ts（第 1-25 行）
export const DESCRIPTION = `Interact with Language Server Protocol (LSP) servers to get code intelligence features.

Supported operations:
- goToDefinition: Find where a symbol is defined
- findReferences: Find all references to a symbol
- hover: Get hover information (documentation, type info) for a symbol
- documentSymbol: Get all symbols (functions, classes, variables) in a document
- workspaceSymbol: Search for symbols across the entire workspace
- goToImplementation: Find implementations of an interface or abstract method
- prepareCallHierarchy: Get call hierarchy item at a position
- incomingCalls: Find all functions/methods that call the function at a position
- outgoingCalls: Find all functions/methods called by the function at a position`

二、LSPTool 整体架构

2.1 模块位置与职责

LSPTool 位于 src/tools/LSPTool/ 目录下，采用模块化设计，各文件职责分明：

src/tools/LSPTool/
├── LSPTool.ts      # 工具主实现：输入验证、请求路由、结果格式化
├── schemas.ts      # Zod 输入模式定义：九种 LSP 操作的判别联合类型
├── formatters.ts   # 结果格式化：将 LSP 原始响应转换为人类可读文本
├── prompt.ts       # 工具描述文本：向模型说明工具用途和参数
└── UI.tsx          # 终端 UI 渲染：工具调用和结果的交互式展示

与之对应的服务层位于 src/services/lsp/，负责语言服务器的生命周期管理：

src/services/lsp/
├── LSPClient.ts              # JSON-RPC 客户端封装
├── LSPServerInstance.ts      # 单个语言服务器实例管理
├── LSPServerManager.ts       # 多服务器路由与调度
├── manager.ts                # 全局单例管理与初始化
├── config.ts                 # 插件配置加载
├── types.ts                  # 类型定义
├── passiveFeedback.ts        # 诊断通知处理
└── LSPDiagnosticRegistry.ts  # 诊断信息注册与去重

2.2 架构分层

Claude Code 的 LSP 集成采用了清晰的三层架构：

flowchart TD
    subgraph ToolLayer["工具层 (Tool Layer)"]
        A[LSPTool.ts] -->|调用| B[schemas.ts]
        A -->|格式化| C[formatters.ts]
    end

    subgraph ServiceLayer["服务层 (Service Layer)"]
        D[manager.ts] -->|获取实例| E[LSPServerManager.ts]
        E -->|路由请求| F[LSPServerInstance.ts]
        F -->|通信| G[LSPClient.ts]
    end

    subgraph ServerLayer["服务器层 (Server Layer)"]
        G -->|JSON-RPC| H[typescript-language-server]
        G -->|JSON-RPC| I[pyright]
        G -->|JSON-RPC| J[gopls]
        G -->|JSON-RPC| K[rust-analyzer]
    end

    A -->|sendRequest| E
    F -->|通知| L[passiveFeedback.ts]
    L -->|注册| M[LSPDiagnosticRegistry.ts]

工具层面向 Claude 模型，将复杂的 LSP 协议封装为统一的工具接口。模型只需提供 operation、filePath、line、character 四个参数，无需了解底层 JSON-RPC 的细节。

服务层是连接工具与语言服务器的桥梁。LSPServerManager 负责根据文件扩展名路由请求到正确的语言服务器；LSPServerInstance 管理单个服务器的启动、初始化和健康检查；LSPClient 则封装了基于 vscode-jsonrpc 的通信细节。

服务器层由各种语言特定的 LSP 服务器组成，如 TypeScript 的 typescript-language-server、Python 的 pyright、Go 的 gopls 等。这些服务器由插件配置引入，Claude Code 本身不内置任何语言服务器。

三、LSP Client 实现

3.1 LSPClient.ts：JSON-RPC 通信封装

LSPClient.ts 是整个 LSP 集成的通信基石。它使用 vscode-jsonrpc 库建立与语言服务器进程的标准输入输出（stdio）连接，并通过 JSON-RPC 协议进行双向通信。

// 源码文件：src/services/lsp/LSPClient.ts（第 25-55 行）
export type LSPClient = {
  readonly capabilities: ServerCapabilities | undefined
  readonly isInitialized: boolean
  start: (
    command: string,
    args: string[],
    options?: { env?: Record<string, string>; cwd?: string }
  ) => Promise<void>
  initialize: (params: InitializeParams) => Promise<InitializeResult>
  sendRequest: <TResult>(method: string, params: unknown) => Promise<TResult>
  sendNotification: (method: string, params: unknown) => Promise<void>
  onNotification: (method: string, handler: (params: unknown) => void) => void
  onRequest: <TParams, TResult>(
    method: string,
    handler: (params: TParams) => TResult | Promise<TResult>
  ) => void
  stop: () => Promise<void>
}

createLSPClient 工厂函数是整个通信流程的核心。它首先通过 Node.js 的 spawn 启动语言服务器子进程，然后等待进程成功启动——这里有一个关键的设计细节：

// 源码文件：src/services/lsp/LSPClient.ts（第 70-95 行）
// 1.5. Wait for process to successfully spawn before using streams
// This is CRITICAL: spawn() returns immediately, but the 'error' event
// (e.g., ENOENT for command not found) fires asynchronously.
await new Promise<void>((resolve, reject) => {
  const onSpawn = (): void => {
    cleanup()
    resolve()
  }
  const onError = (error: Error): void => {
    cleanup()
    reject(error)
  }
  spawnedProcess.once('spawn', onSpawn)
  spawnedProcess.once('error', onError)
})

这段代码解决了 spawn() 异步启动的竞态条件问题。spawn() 同步返回 ChildProcess 对象，但实际的进程启动是异步的——如果命令不存在（ENOENT），error 事件会在之后触发。如果在确认启动成功前就使用 stdio 流，会导致未处理的 Promise 拒绝。

确认进程启动成功后，LSPClient 创建 StreamMessageReader 和 StreamMessageWriter，通过 createMessageConnection 建立 JSON-RPC 连接。随后注册错误和关闭处理器，启动消息监听，并发送 initialize 请求完成协议握手。

3.2 LSPServerInstance.ts：服务器生命周期管理

LSPServerInstance.ts 在 LSPClient 之上增加了状态机和健康检查能力。每个语言服务器实例都维护一个状态机：

stateDiagram-v2
    [*] --> stopped: 创建实例
    stopped --> starting: 调用 start()
    starting --> running: 初始化成功
    starting --> error: 启动失败
    running --> stopping: 调用 stop()
    running --> error: 进程崩溃
    error --> starting: 自动重启（未超限）
    stopping --> stopped: 关闭完成
    stopped --> [*]: 实例销毁

状态转换的关键在于 onCrash 回调的传播机制。当语言服务器进程异常退出时，LSPClient 检测到非零退出码并调用 onCrash，LSPServerInstance 将状态设为 error。这样下一次请求到来时，ensureServerStarted 会触发自动重启：

// 源码文件：src/services/lsp/LSPServerInstance.ts（第 85-100 行）
const client = createLSPClient(name, error => {
  state = 'error'
  lastError = error
  crashRecoveryCount++
})

async function start(): Promise<void> {
  if (state === 'running' || state === 'starting') return

  // Cap crash-recovery attempts so a persistently crashing server doesn't
  // spawn unbounded child processes on every incoming request.
  const maxRestarts = config.maxRestarts ?? 3
  if (state === 'error' && crashRecoveryCount > maxRestarts) {
    throw new Error(
      `LSP server '${name}' exceeded max crash recovery attempts (${maxRestarts})`
    )
  }
  // ...启动逻辑
}

初始化阶段，LSPServerInstance 向语言服务器发送 initialize 请求，携带客户端能力和工作区信息：

// 源码文件：src/services/lsp/LSPServerInstance.ts（第 140-175 行）
const initParams: InitializeParams = {
  processId: process.pid,
  initializationOptions: config.initializationOptions ?? {},
  workspaceFolders: [{ uri: workspaceUri, name: path.basename(workspaceFolder) }],
  rootPath: workspaceFolder,        // LSP 3.8 已弃用但部分服务器仍需
  rootUri: workspaceUri,            // typescript-language-server 需要此字段
  capabilities: {
    workspace: {
      configuration: false,         // 我们不支持 workspace/configuration
      workspaceFolders: false,      // 不支持工作区变更通知
    },
    textDocument: {
      synchronization: { dynamicRegistration: false },
      // ...其他能力声明
    }
  }
}

这里体现了 Claude Code 的务实设计：虽然声明不支持 workspace/configuration，但仍为 TypeScript 等需要的服务器注册了请求处理器，返回 null 以满足协议要求。

3.3 LSPServerManager.ts：多服务器路由与调度

当项目同时包含 TypeScript、Python 和 Go 代码时，需要多个语言服务器协同工作。LSPServerManager 负责根据文件扩展名将请求路由到对应的服务器：

// 源码文件：src/services/lsp/LSPServerManager.ts（第 70-110 行）
async function initialize(): Promise<void> {
  const result = await getAllLspServers()
  const serverConfigs = result.servers

  // Build extension → server mapping
  for (const [serverName, config] of Object.entries(serverConfigs)) {
    const fileExtensions = Object.keys(config.extensionToLanguage)
    for (const ext of fileExtensions) {
      const normalized = ext.toLowerCase()
      if (!extensionMap.has(normalized)) {
        extensionMap.set(normalized, [])
      }
      extensionMap.get(normalized)!.push(serverName)
    }

    const instance = createLSPServerInstance(serverName, config)
    servers.set(serverName, instance)
  }
}

getAllLspServers() 从已启用的插件中加载 LSP 服务器配置。这意味着 LSP 服务器仅通过插件配置，不支持用户或项目级别的设置。这种设计将语言服务的管理权限收归插件体系，确保了配置的一致性和安全性。

文件同步是 LSPServerManager 的另一项重要职责。语言服务器需要知道编辑器中打开的文件内容，才能提供准确的分析结果。LSPServerManager 维护了一个 openedFiles 映射，追踪哪些文件已向哪些服务器发送了 textDocument/didOpen 通知：

// 源码文件：src/services/lsp/LSPServerManager.ts（第 200-230 行）
async function openFile(filePath: string, content: string): Promise<void> {
  const server = await ensureServerStarted(filePath)
  if (!server) return

  const uri = pathToFileURL(filePath).href
  openedFiles.set(uri, server.name)

  await server.sendNotification('textDocument/didOpen', {
    textDocument: { uri, languageId, version: 1, text: content }
  })
}

在 LSPTool.call() 中，如果目标文件尚未在语言服务器中打开，会先读取文件内容并发送 didOpen 通知，然后再执行实际的 LSP 请求。这种设计确保了即使 Claude Code 本身不是传统意义上的编辑器，语言服务器也能获得完整的文件上下文。

四、支持的操作

LSPTool 封装了九种 LSP 操作，覆盖代码导航、符号分析和调用关系追踪。所有操作共享相同的输入参数结构：filePath、line、character，但映射到不同的 LSP 方法和参数。

4.1 符号查询：定义、引用与悬浮信息

跳转到定义（goToDefinition） 是最常用的操作之一。当模型想知道某个符号在哪里定义时，LSPTool 将其转换为 textDocument/definition 请求：

// 源码文件：src/tools/LSPTool/LSPTool.ts（第 470-480 行）
case 'goToDefinition':
  return {
    method: 'textDocument/definition',
    params: {
      textDocument: { uri },
      position: { line: input.line - 1, character: input.character - 1 }
    }
  }

注意到坐标转换：line 和 character 从用户友好的 1-based 转换为 LSP 协议要求的 0-based。

结果通过 formatters.ts 中的 formatGoToDefinitionResult 格式化为人类可读文本。该函数需要处理多种返回类型——Location、LocationLink，或它们的数组：

// 源码文件：src/tools/LSPTool/formatters.ts（第 85-115 行）
export function formatGoToDefinitionResult(
  result: Location | Location[] | LocationLink | LocationLink[] | null,
  cwd?: string
): string {
  if (!result) {
    return 'No definition found. This may occur if the cursor is not on a symbol...'
  }

  if (Array.isArray(result)) {
    const locations = result.map(item =>
      isLocationLink(item) ? locationLinkToLocation(item) : item
    )
    const validLocations = locations.filter(loc => loc && loc.uri)
    if (validLocations.length === 1) {
      return `Defined in ${formatLocation(validLocations[0]!, cwd)}`
    }
    const locationList = validLocations
      .map(loc => `  ${formatLocation(loc, cwd)}`)
      .join('\n')
    return `Found ${validLocations.length} definitions:\n${locationList}`
  }
  // ...单结果处理
}

查找引用（findReferences） 使用 textDocument/references，返回所有引用位置。结果会经过 gitignore 过滤——LSPTool 使用 git check-ignore 批量检查返回的文件路径，自动排除 node_modules、构建产物等不应关注的文件：

// 源码文件：src/tools/LSPTool/LSPTool.ts（第 380-410 行）
const filteredLocations = await filterGitIgnoredLocations(locations, cwd)
const filteredUris = new Set(filteredLocations.map(l => l.uri))
result = (result as (Location | LocationLink)[]).filter(item => {
  const loc = toLocation(item)
  return !loc.uri || filteredUris.has(loc.uri)
})

悬浮信息（hover） 通过 textDocument/hover 获取符号的类型签名和文档注释。这对于理解复杂类型系统尤其重要，比如 TypeScript 中的泛型约束或 Rust 中的生命周期标注。

4.2 诊断获取：被动反馈机制

与传统的主动请求不同，代码诊断（Diagnostics）采用被动推送模式。语言服务器在分析代码后，通过 textDocument/publishDiagnostics 通知主动向客户端发送诊断信息。Claude Code 的 passiveFeedback.ts 负责接收这些通知：

// 源码文件：src/services/lsp/passiveFeedback.ts（第 55-85 行）
export function formatDiagnosticsForAttachment(
  params: PublishDiagnosticsParams
): DiagnosticFile[] {
  const uri = params.uri.startsWith('file://')
    ? fileURLToPath(params.uri)
    : params.uri

  const diagnostics = params.diagnostics.map(diag => ({
    message: diag.message,
    severity: mapLSPSeverity(diag.severity),  // 1→Error, 2→Warning, 3→Info, 4→Hint
    range: {
      start: { line: diag.range.start.line, character: diag.range.start.character },
      end: { line: diag.range.end.line, character: diag.range.end.character }
    },
    source: diag.source,
    code: diag.code !== undefined ? String(diag.code) : undefined
  }))

  return [{ uri, diagnostics }]
}

诊断信息被注册到 LSPDiagnosticRegistry，并在下一轮对话中作为附件自动提交给 AI 模型。注册表实现了两层去重机制：

1. 批次内去重：同一批诊断中，相同位置、相同消息的诊断只保留一条。
2. 跨轮次去重：使用 LRU 缓存追踪已交付的诊断，避免在多次对话中重复报告相同的错误。

// 源码文件：src/services/lsp/LSPDiagnosticRegistry.ts（第 35-50 行）
const deliveredDiagnostics = new LRUCache<string, Set<string>>({
  max: MAX_DELIVERED_FILES  // 防止长会话中内存无限增长
})

function createDiagnosticKey(diag: {
  message: string; severity?: string; range?: unknown; source?: string; code?: unknown
}): string {
  return jsonStringify({
    message: diag.message,
    severity: diag.severity,
    range: diag.range,
    source: diag.source || null,
    code: diag.code || null
  })
}

4.3 调用层级分析

LSPTool 还支持调用层级（Call Hierarchy）分析，这是理解代码调用链的高级功能。incomingCalls 查找哪些函数调用了当前位置的函数，outgoingCalls 则查找当前函数调用了哪些函数。

调用层级是一个两步操作：首先通过 textDocument/prepareCallHierarchy 获取 CallHierarchyItem，然后用该 item 请求 callHierarchy/incomingCalls 或 callHierarchy/outgoingCalls：

// 源码文件：src/tools/LSPTool/LSPTool.ts（第 320-360 行）
if (input.operation === 'incomingCalls' || input.operation === 'outgoingCalls') {
  const callItems = result as CallHierarchyItem[]
  if (!callItems || callItems.length === 0) {
    return { data: { result: 'No call hierarchy item found at this position', ... } }
  }

  const callMethod = input.operation === 'incomingCalls'
    ? 'callHierarchy/incomingCalls'
    : 'callHierarchy/outgoingCalls'

  result = await manager.sendRequest(absolutePath, callMethod, { item: callItems[0] })
}

五、与 IDE 的桥接

5.1 IDE 自动检测与连接

Claude Code 不仅能启动独立的语言服务器进程，还能与已安装的 IDE（VS Code、Cursor、JetBrains 系列等）建立连接，复用 IDE 中已配置好的语言服务。这一机制通过 src/utils/ide.ts 中的 detectIDEs 函数实现。

IDE 检测的核心是 lockfile 机制。当 Claude Code 的 IDE 扩展（如 VS Code 的 anthropic.claude-code 扩展）运行时，会在 ~/.claude/ide/ 目录下创建以端口号命名的 .lock 文件，记录工作区目录、进程 ID、IDE 名称等信息：

// 源码文件：src/utils/ide.ts（第 30-45 行）
type LockfileJsonContent = {
  workspaceFolders?: string[]
  pid?: number
  ideName?: string
  transport?: 'ws' | 'sse'
  runningInWindows?: boolean
  authToken?: string
}

type IdeLockfileInfo = {
  workspaceFolders: string[]
  port: number
  pid?: number
  ideName?: string
  useWebSocket: boolean
  runningInWindows: boolean
  authToken?: string
}

detectIDEs 函数读取这些 lockfile，验证工作区目录匹配和进程存活状态，返回可用的 IDE 连接信息。它还会检查进程祖先链——当在 IDE 内置终端中运行 Claude Code 时，通过比对 PID 确保连接到正确的 IDE 实例：

// 源码文件：src/utils/ide.ts（第 720-750 行）
if (needsAncestryCheck) {
  const portMatchesEnv = envPort !== null && lockfileInfo.port === envPort
  if (!portMatchesEnv) {
    if (!lockfileInfo.pid || !isProcessRunning(lockfileInfo.pid)) {
      continue
    }
    if (process.ppid !== lockfileInfo.pid) {
      const ancestors = await getAncestors()
      if (!ancestors.has(lockfileInfo.pid)) {
        continue  // 不是我们的父进程，跳过
      }
    }
  }
}

5.2 路径转换：WSL 与跨平台场景

当 Claude Code 运行在 WSL（Windows Subsystem for Linux）中，而 IDE 运行在 Windows 上时，路径格式存在差异。idePathConversion.ts 提供了 IDEPathConverter 接口来处理这种转换：

// 源码文件：src/utils/idePathConversion.ts（第 10-25 行）
export interface IDEPathConverter {
  toLocalPath(idePath: string): string    // IDE 格式 → Claude 本地格式
  toIDEPath(localPath: string): string    // Claude 本地格式 → IDE 格式
}

export class WindowsToWSLConverter implements IDEPathConverter {
  constructor(private wslDistroName: string | undefined) {}

  toLocalPath(windowsPath: string): string {
    try {
      const result = execFileSync('wslpath', ['-u', windowsPath], {
        encoding: 'utf8',
        stdio: ['pipe', 'pipe', 'ignore']
      }).trim()
      return result
    } catch {
      // 回退到手动转换
      return windowsPath
        .replace(/\\/g, '/')
        .replace(/^([A-Z]):/i, (_, letter) => `/mnt/${letter.toLowerCase()}`)
    }
  }
}

这个转换器在 toLocalPath 中使用 wslpath 工具进行精确转换，失败时回退到基于正则的手动转换。在 toIDEPath 中则反向使用 wslpath -w。对于多 WSL 发行版场景，还会检查 UNC 路径中的发行版名称是否匹配，避免跨发行版路径转换错误。

5.3 Bridge 层的配合

src/bridge/ 目录下的模块负责与 claude.ai/code 网页端的桥接通信，其中 bridgeApi.ts 实现了 OAuth 认证的 REST API 客户端。虽然 Bridge 层主要服务于远程协作场景，但其注册的环境信息（工作区目录、Git 仓库等）同样可以被 LSP 服务利用，确保在远程开发环境中语言服务器能够正确解析工作区路径。

// 源码文件：src/bridge/bridgeApi.ts（第 65-85 行）
async registerBridgeEnvironment(config: BridgeConfig) {
  const response = await axios.post(
    `${deps.baseUrl}/v1/environments/bridge`,
    {
      machine_name: config.machineName,
      directory: config.dir,
      branch: config.branch,
      git_repo_url: config.gitRepoUrl,
      max_sessions: config.maxSessions,
      metadata: { worker_type: config.workerType }
    },
    { headers: getHeaders(token), timeout: 15_000 }
  )
  return response.data
}

当 IDE 连接与 LSP 服务同时存在时，Claude Code 会优先使用 IDE 提供的语言服务能力，因为 IDE 中的语言服务器已经建立了完整的项目索引，包括第三方依赖的符号解析。只有当没有可用 IDE 连接时，才会启动独立的语言服务器进程。

六、工具属性与设计哲学

LSPTool 的定义体现了 Claude Code 工具系统的几个重要设计选择：

// 源码文件：src/tools/LSPTool/LSPTool.ts（第 75-95 行）
export const LSPTool = buildTool({
  name: LSP_TOOL_NAME,
  searchHint: 'code intelligence (definitions, references, symbols, hover)',
  maxResultSizeChars: 100_000,
  isLsp: true,
  shouldDefer: true,         // 延迟加载，通过 ToolSearch 按需发现
  isEnabled() { return isLspConnected() },
  isConcurrencySafe() { return true },
  isReadOnly() { return true },
  // ...
})

• shouldDefer: true：LSPTool 不会默认出现在模型的工具列表中，而是通过 ToolSearchTool 按需发现。这避免了在没有配置 LSP 服务器时向模型展示无效工具。
• isConcurrencySafe: true：多个 LSP 请求可以并行执行，语言服务器本身就是为并发设计的。
• isReadOnly: true：LSPTool 不会修改任何文件，这对于权限系统至关重要——模型可以无顾虑地调用它来获取代码信息。

输入验证阶段，LSPTool 首先使用判别联合类型（discriminated union）进行精确的类型检查，然后验证目标文件是否存在且为普通文件。还有一个安全细节：对于 UNC 路径（\\ 或 // 开头）直接跳过文件系统检查，防止 NTLM 凭据泄露攻击。

// 源码文件：src/tools/LSPTool/LSPTool.ts（第 120-140 行）
async validateInput(input: Input): Promise<ValidationResult> {
  const parseResult = lspToolInputSchema().safeParse(input)
  if (!parseResult.success) {
    return { result: false, message: `Invalid input: ${parseResult.error.message}` }
  }

  // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
  if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
    return { result: true }
  }
  // ...文件存在性检查
}

七、总结

LSPTool 是 Claude Code 工具生态中连接代码语义世界的桥梁。通过标准化的 Language Server Protocol，它让 AI 模型能够超越文本表面，深入理解代码的类型系统、符号关系和架构层次。

从架构上看，三层设计（工具层-服务层-服务器层）清晰地分离了关注点：工具层面向模型提供简洁接口，服务层管理复杂的服务器生命周期，服务器层则由社区成熟的语言分析工具担当。从实现细节上看，异步进程管理、状态机、错误重试、跨平台路径转换等工程实践，展现了一个生产级工具应有的健壮性。

与 IDE 桥接层的协同进一步拓展了 LSP 的适用场景——当 Claude Code 运行在 IDE 终端中时，它能无缝复用 IDE 已建立的语言服务索引，避免了重复启动和索引的开销。这种 "站在巨人肩膀上" 的设计，正是 Claude Code 能够在复杂企业级代码库中游刃有余的关键所在。