LSP与LLM：搭建AI代码补全与编辑器交互的标准桥梁

LSPs for LLMs，直译是“给大语言模型用的 LSP”，更准确地说，是把 Language Server Protocol（语言服务器协议，简称 LSP）当作大语言模型（LLM）和编辑器之间的标准通道。这个方向解决的实际问题很明确：你在编辑器里用 AI 补全、AI 诊断、AI 代码解释时，模型怎么拿到当前代码，修改建议怎么回到界面，错误信息怎么展示，这些都需要一套稳定的交互协议。如果每个插件自己定义一套通信方式，工程上会非常混乱。LSP 提供了现成的标准化消息格式，LLM 只需要按照协议把结果返回给编辑器，就能复用现有编辑器的展示和交互能力。适合正在做 AI 编程助手、编辑器插件、或者想把内部模型接入 IDE 的开发者。下面我会先讲协议角色和选型判断，再给一条最省事的验证路径，然后按协议实现顺序逐层拆解，最后把最常见的坑和排查顺序列出来。

1. 先搞清楚 LSP 在 LLM 场景里到底承担什么角色

1.1 传统 LSP 解决的是“编辑器与语言服务解耦”

在 LSP 出现之前，编辑器要想支持某种语言的补全、诊断、跳转，通常需要单独写插件。同一个语言服务要在 VS Code、Neovim、Emacs 等不同编辑器里各实现一遍。LSP 的做法是把“语言能力”抽成一个独立的服务器进程，编辑器统一作为客户端，通过标准协议通信。这样语言作者只需要写一个 server，所有支持 LSP 的编辑器都能用。

这个模式的关键在于：通信内容是结构化的。补全返回 CompletionItem，诊断返回 Diagnostic，跳转返回 Location。编辑器拿到结构化结果后，按自己的界面风格展示。

1.2 LLM 加入之后，不变的是协议，变的是生成逻辑

传统 LSP 服务器里，补全通常靠语法树、符号表、作用域分析。LLM 驱动的服务器完全不需要这些静态分析也能给补全，模型靠的是大规模代码语料训练出的概率分布。这对 LSP 服务器开发有一个重要影响：服务器本身可以做得更薄，主要工作变成“把编辑器的请求转成模型输入，再把模型输出转换成协议响应”。

我建议先明确这一点：LSP 并不会因为 LLM 而消失，反而是 LLM 落地编辑器的最佳壳子。LLM 只负责生成文本，LSP 负责把文本放到正确的位置，并告诉编辑器“这是补全，不是普通输入”。

1.3 值得用 LSP + LLM 覆盖的场景

整理下来，适合先落地的场景包括：

• 代码补全：光标处生成一行、一个函数、一段实现。
• 代码诊断：打开文件时，让模型找出潜在错误、类型问题或风格问题。
• Hover 解释：鼠标悬停到符号上，让模型解释这个函数或变量。
• Code Action：在诊断上提供一个“用 AI 修复”的操作，点击后把模型生成的补丁应用进去。
• 多文件重构：把多个文件内容拼接成上下文，让模型给出跨文件修改建议。

一个常见的认知误区是：既然模型能直接对话，为什么还要 LSP？因为编辑器的交互模型是“文档、光标、选择、诊断”这些概念，不是聊天窗口。LSP 恰好把这套概念标准化了。你可以把 LSP 看成模型与编辑器的“接口层”，而不是重复造轮子。尤其当你的业务不止接一个模型，或者要同时支持补全、解释、诊断时，标准协议能帮你省掉很多客户端适配工作。

2. 环境准备与最小样例：先把链路跑通

2.1 最小运行环境

先说环境，尽量简单：

• 操作系统：Windows、macOS、Linux 都可以。
• 编辑器：VS Code 是最方便的，因为它内置 LSP 客户端，不需要自己写客户端。
• 服务端语言：写 LSP server 用 Python 或 Node.js 都行。Python 上手快，Node.js 生态里 LSP 库更成熟。
• LLM 服务：可以是一个云端模型的 API，也可以是一个本地推理服务。关键是要有一个接口能传文本、返回内容。

如果只是验证链路，不需要先接真实模型。我通常建议先用一个“假模型”跑通协议，例如固定返回一句补全文本。协议通了，再替换成真实模型调用。

这一步的验证标准很明确：编辑器里输入代码，能看到固定文本出现在补全候选里。如果这一步通不过，后面接任何模型都会很难排查。

2.2 接 LLM 服务时的两种路径

• 路径 A：直接调用云端模型 API。优点是响应质量通常更高，缺点是每次请求都有网络延迟和费用。使用这种路径时，要先确认账号、密钥、访问权限已经按服务方要求准备好。
• 路径 B：调用本地推理服务。例如在 Mac 上跑一个本地推理引擎，或者用带 GPU 的 Linux 机器启动推理服务。优点是隐私性和可控性好，缺点是模型规模受限于硬件，响应速度可能不如云端。

从我个人经验来看，学习阶段先用本地小模型或“假模型”更好，先把 LSP 部分调通；性能阶段再上云端模型。不要一上来就接最强的云端模型，否则你分不清卡顿是模型慢，还是协议写错了。

注意：第一次跑通时，千万不要开项目级扫描，也不要让模型同时处理多个文件。先单文件、单请求，确保“编辑器的请求能进去，LSP 的响应能出来”。

2.3 协议传输层：JSON-RPC 和消息帧

LSP 基于 JSON-RPC 2.0。请求带 id，响应也要带同一个 id；通知没有 id，只表示事件发生，不需要返回。

stdio 模式下，每条消息都要带 Content-Length 头：

Content-Length: 123\r\n \r\n {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

很多第一次写 LSP server 的人都会在这里踩坑：协议解析失败，编辑器直接报“server process exited”。所以第一步最好把读写消息的函数单独写好，并打日志验证。

日志也有讲究：如果 server 通过 stdio 和编辑器通信，那么在同一个 stdout 里打印日志会污染协议流。日志要写 stderr，或者写到文件。这是一个非常经典的坑。

3. 从零实现一个 LLM 驱动的 LSP 服务

3.1 初始化：能力声明决定客户端怎么调你

客户端启动 server 后，第一件事是发initialize请求。server 必须在响应里声明自己支持哪些能力。

示例返回的核心 capabilities：

{ "textDocumentSync": 1, "completionProvider": { "triggerCharacters": ["."] }, "hoverProvider": true }

• textDocumentSync: 1表示收到全量文档内容。2表示增量同步。
• completionProvider声明支持补全，triggerCharacter是触发字符。
• hoverProvider声明支持悬停。

这里的取舍是：声明能力越少，实现越简单；声明太多，客户端会不断调用你没实现好的接口。我一般建议初期只声明textDocumentSync和completionProvider，跑通后再加 hover 和诊断。

3.2 文档同步：模型要读到最新的文件内容

编辑器打开文件后，会发textDocument/didOpen通知；文件内容变化时，会发textDocument/didChange。这些通知没有 id，server 不需要返回响应，但必须保存文档内容，否则后面收到补全请求时，你手里没有代码内容，就没有东西可以发给模型。

我建议维护一个简单的字典：{uri: {"text": str, "languageId": str}}。每次 didOpen/didChange 更新这个字典。

如果声明了增量同步，didChange 里会带range和text，你需要自己把新文本替换到原文档对应位置。这个逻辑容易出错，初期用全量同步更省事：每次 didChange 都把整个文档内容传给你。缺点是流量大，但对小文件和初学场景完全够用。

3.3 补全：把光标位置和代码片段喂给模型

客户端在用户输入触发字符或主动请求补全时，会发textDocument/completion请求。请求参数里有：

• textDocument.uri：当前文件 URI。
• position.line和position.character：光标位置。

server 的处理逻辑是：

1. 根据 URI 找到缓存文档内容。
2. 根据光标位置，截取光标前后的文本。
3. 把文本片段、语言类型、光标上下文组装成模型输入。
4. 调用模型，拿到补全文本。
5. 把补全文本包装成 CompletionItem 返回。

一个最小补全响应：

{ "isIncomplete": false, "items": [ { "label": "def get_user_name():", "insertText": "def get_user_name():\n " } ] }

label是候选列表里显示的文字，insertText是选中后插入编辑器的文本。

这里有一个很实用的点：不要一股脑把整个文件塞给模型。文件很大时，token 成本高，模型还可能丢掉重要上下文。简单的做法是取光标前 1500 字符、光标后 800 字符，加上文件的语言和项目路径。上下文越聚焦，补全质量越稳定。

3.4 诊断：让模型当静态检查器

诊断通常由 server 主动推送。流程是：

1. 收到didChange后，等待几百毫秒，这叫 debounce，防止每次击键都触发模型调用。
2. 把最新文档内容发给模型，提示词要求它找出错误或潜在问题。
3. 模型返回一组结构化问题，包括行号、列号、严重程度和消息。
4. server 调用textDocument/publishDiagnostics通知，把诊断推给编辑器。

一个诊断通知：

{ "jsonrpc": "2.0", "method": "textDocument/publishDiagnostics", "params": { "uri": "file:///path/to/a.py", "diagnostics": [ { "range": { "start": {"line": 3, "character": 0}, "end": {"line": 3, "character": 10} }, "severity": 1, "message": "模型认为这里可能存在空指针风险" } ] } }

severity 从 1 到 4，分别对应 Error、Warning、Information、Hint。

要注意，LLM 做诊断天然有误报率。它不像传统静态分析工具那样确定。我建议在提示词里明确要求“只报告确定是高概率的问题”，或者在服务端设置一个置信度阈值，低于阈值的诊断直接丢弃。

3.5 Hover 解释：把符号和上下文一起发给模型

客户端悬停时，会发textDocument/hover请求。server 可以把光标位置所在的符号名、附近代码、语言信息发给模型，让模型生成一段解释。响应格式是：

{ "contents": { "kind": "markdown", "value": "这个函数用于计算数组中的最大子数组和。" } }

Hover 特别适合演示“LLM 语义理解和 LSP 展示”的组合。它不像补全那样要求严格符合编辑语法，模型自由发挥的空间更大。

我建议把 hover 作为第二个实现的功能，因为调试方便：不需要复杂的候选列表逻辑，只要把返回文本塞进contents.value就行。

4. 参数、性能与并发：别让模型响应拖垮编辑器

4.1 上下文窗口控制

这里其实是 LLM 应用的核心问题。模型输入不是越多越好。常见做法：

我建议先按“光标前后片段 + 整个文件”的方案做，单个文件不超过一定行数时就整个传，超过就截断。等项目级需求明确后，再引入 RAG 或基于符号表的检索。

4.2 同步与异步：LSP 如何应对模型延迟

LSP 的请求/响应模式要求服务器在收到请求后的一定时间内返回。云端模型一次调用可能需要几秒到几十秒，如果直接同步等待模型返回，编辑器会一直转圈，用户会认为插件卡死了。

更稳的做法是：

• 对于补全请求，考虑到补全对延迟敏感，可以只等小模型快速返回，或者放弃超时模型调用，改为返回空结果。
• 对于诊断，延迟不那么敏感，可以异步做。先赶紧把 didChange 处理完，后台去调模型，拿到结果后再推送诊断。
• 在底层支持异步并发，多个文档同时打开时，不要让一个文件的模型调用阻塞所有请求。

LSP 还支持$/cancelRequest通知。当用户移开光标或关闭文件时，客户端会发送取消请求。好的服务器应该监听这个通知，并中断正在等待的模型调用。这样能节省大量无效计算。

4.3 超时、重试和速率限制

接云端模型服务时，你会遇到三类问题：

1. 网络超时。高峰期模型接口可能很慢。服务端要设置合理的超时时间，比如 5 到 10 秒。超时后给编辑器返回一个空结果，不要让请求一直挂着。
2. 速率限制。短时间请求太多，接口会拒绝。可以在服务端加一个简单的队列，同一文档的请求排队处理，队列太长就丢弃低优先级请求。
3. 重试。失败重试要谨慎，特别是在编辑器实时场景。每次击键都触发一次补全，如果每次都重试，很容易打满速率限制。

我常用的配置是：补全请求不做重试，失败就失败；诊断请求可以重试 1 次，但要有间隔。关键是把“模型调用失败”和“LSP 协议出错”分开记录，否则排查时容易混乱。

4.4 轻量化：让传统 LSP 能力兜底

LLM 很强，但不是所有操作都应该走模型。跳转定义、查找引用、符号列表这些功能，用传统静态分析更可靠，速度也更快。实际上，现代 LSP 服务器通常可以同时提供两类能力：

• 传统静态能力：基于语法树和索引。
• LLM 生成能力：补全、解释、自然语言指令。

这样设计的好处是，用户打开大项目时，跳转和引用不会卡；需要创造性生成时，才调模型。对服务器开发来说，两种能力可以在同一个进程里共存，把请求路由到不同处理器。

5. LSP + LLM 最容易踩的坑：排查顺序和判断方法

5.1 服务能启动，但编辑器没有任何输出

先确认 server 是否真的跑起来了。VS Code 的 Output 面板里能选择对应 channel，查看 server 的 stderr 日志。如果完全没有日志，检查：

• executable 的