最近在调研代码辅助工具的工程化方案时发现一个很核心的问题大模型写代码到底需要什么很多人第一反应是“需要更多代码片段”“需要更大的上下文窗口”但做落地时才发现真正难的不是让 LLM 读代码而是让它读到“足够结构化、足够实时、编辑器里正在发生”的代码状态。传统做法要么截文件、要么让用户手动复制既不工程化也很浪费 token。后来我们把注意力放到了 Language Server ProtocolLSP上越深入越觉得这条路才是 LLM 代码助手的正确入口。这篇文章就围绕“LSPs for LLMs”展开把协议机制、最小可运行示例、常见坑点一起梳理清楚。如果你是做 AI 编程助手、IDE 插件、代码分析工具或者单纯好奇 Copilot 这类工具是怎么拿到语义上下文的本文会很有参考价值。整个内容不依赖某个特定大模型产品尽量把底层协议讲透再给出可以改着玩的代码骨架。1. LSP 是什么从编辑器插件碎片化说起1.1 LSP 解决的问题很长一段时间里每种编辑器要支持一门新语言几乎都要单独写一套插件。语法高亮、自动补全、跳转定义、错误提示这些功能在不同编辑器里的实现方式完全不同。于是社区里出现了一个想法把“语言智能”抽出来做成一个独立的服务编辑器只需要按照统一协议和这个服务通信语言相关的实现只写一次所有编辑器共用。这个想法落地后就是 Language Server Protocol。LSP 的核心思路可以概括为编辑器Client负责界面展示、用户输入、文件变更。语言服务器Server负责解析代码、提供补全、诊断、跳转等能力。双方通过 JSON-RPC 消息通信。这样一来VS Code、Neovim、Emacs、JetBrains 系列等编辑器都能复用同一个语言服务器语言作者只需要维护一份真正的智能逻辑。1.2 LSP 的工作模型Client-Server 与 JSON-RPCLSP 的消息格式基于 JSON-RPC 2.0传输层通常使用标准输入输出stdio或命名管道。每一条消息都带一个类似 HTTP 的头部Content-Length: 123\r\n \r\n {json 内容}Content-Length的值是消息体 JSON 的字节数。服务器从标准输入读取消息处理完后再把响应写入标准输出。客户端发起请求时带id服务器需要返回带相同id的响应服务器也可以主动推送通知比如textDocument/publishDiagnostics。整个会话的生命周期可以分成三个阶段初始化客户端发送initialize服务器返回自身能力capabilities。运行期双方持续交换文档打开、修改、查询、诊断等消息。关闭客户端发送shutdown和exit服务器退出。1.3 为什么 LSP 和 LLM 有关系传统 LSP 的目标是给人类开发者提供编程辅助。但随着 AI 编程助手兴起一个很自然的想法是能不能让 LLM 也成为 LSP 能力的消费者这里有两层含义把 LSP 当作 LLM 的上下文来源通过 LSP 拿诊断信息、符号表、当前行语义再把这些内容拼进 prompt。让 LLM 结果通过 LSP 协议回写到编辑器LLM 生成补全候选、内联建议、错误修复方案以标准协议格式展示给用户。如果只是让 LLM 读文件内容LSP 的价值还不明显。真正有价值的是 LSP 提供的“语义化实时上下文”比如当前文件最近一次编译诊断出哪些错误、光标所在位置的符号类型、整个工作区有哪些引用关系。这些信息对大模型理解代码意图非常关键。2. LLM 编程助手在传统接入方式上的困境2.1 文件截断式上下文的局限最粗暴的 LLM 代码上下文方案就是把整个文件读进来截断到模型可接受的长度再拼进 prompt。这种方案在短文件上勉强可行但遇到大文件、跨文件调用时效果会明显下降。问题在于截断可能切掉关键函数定义。文件内容缺少“错误状态”LLM 不知道当前代码哪里有问题。缺少工作区信息跨文件符号解析只能靠模型猜。2.2 AST 工具链碎片化另一种思路是自己写解析器直接对源码生成 AST抽象语法树再把 AST 转成 LLM 可理解的文本。这个方案听起来精确但因为每种语言都有自己的语法团队往往要维护多套解析器。而且很多业务项目里混合了 TypeScript、Python、SQL、YAML 等语言解析器之间的交互很容易出问题。LSP 的价值在于它已经为各种语言实现了一套统一的语义查询接口。接入 LSP 之后不需要自己去维护 AST 解析差异语言服务器已经把这项工作做完了。2.3 缺少编辑器原生信令开发者在使用 AI 编程助手时最自然的操作是光标悬停看提示、输入过程中触发补全、保存文件后看到修复建议。这些交互都依赖编辑器事件。如果没有 LSP 这类协议插件可能只能通过文件变更监听或轮询数据既笨重又不够实时。LSP 原生支持以下与 LLM 场景高度相关的信令信令对应 LLM 应用场景textDocument/didOpen文件打开时开始建立上下文textDocument/didChange文件修改时增量更新理解textDocument/publishDiagnostics把诊断结果交给 LLM 作为修复依据textDocument/hover光标停留时生成实时解释textDocument/completion实时代码补全textDocument/inlayHint在代码中插入内联提示3. LSP for LLM 的核心机制3.1 文档生命周期打开、修改、关闭LSP 对文档管理有严格的生命周期定义。当用户打开一个文件客户端会发送textDocument/didOpen通知包含文档 URI、语言 ID 和完整文本。之后每次编辑客户端都会发送textDocument/didChange里面可以携带完整文本或增量补丁具体取决于初始化时声明的textDocumentSync模式。在 LLM 场景中合理做法是文件打开时初始化该文件的结构化索引符号、导入、依赖关系。文件修改时只更新受影响部分的语义数据而不是每次全部重新处理。关闭时清理缓存释放 token 预算和内存。3.2 诊断与错误反馈LSP 中诊断信息由服务器主动推送给客户端格式为{ uri: file:///path/to/file.py, diagnostics: [ { range: { start: { line: 3, character: 0 }, end: { line: 3, character: 10 } }, severity: 1, source: ruff, message: Undefined name foo } ] }severity的取值包括 Error、Warning、Information、Hint。当 LSP 服务器把诊断信息推给客户端后LLM 修复提示就有了非常明确的依据哪里错、为什么错、涉及哪一段代码。3.3 语义级查询Hover、Definition、SymbolLLM 在分析代码时不仅需要当前文件内容还需要知道“这个函数从哪里来”“这个变量类型是什么”。传统 LSP 接口正好提供了这些能力textDocument/hover返回当前位置的文档、类型、签名信息。textDocument/definition返回符号定义位置。textDocument/documentSymbol返回当前文件的符号树。workspace/symbol返回跨文件的符号搜索结果。这些接口组合起来可以构建出比“整文件截断”更高质量的 LLM prompt。比如用户询问某个函数时可以先通过definition找到函数源文件再阅读该文件的符号结构最后只把相关代码片段交给 LLM。3.4 补全与内联建议LSP 的补全协议是传统 IDE 自动补全的基础它返回一个候选列表每个候选可以包含文本、类型、文档说明。LLM 补全可以复用这套结构只是候选内容由模型生成而不是由静态索引生成。更贴近 AI 场景的是textDocument/inlineCompletion虽然它的标准化进度不如传统补全完善但很多编辑器已经通过扩展方式支持。对于插件开发者可以先从传统completion入手后续再根据编辑器能力升级到内联补全。3.5 从 LSP 拿到的上下文如何组织 PromptLSP 本身不负责 prompt 工程但它解决了“数据来源”问题。一条合理的代码理解 prompt 可以包含当前文件路径与语言。当前光标位置附近的代码段。当前文件的符号列表。最近一次诊断结果。用户正在引用的跨文件符号定义。这样组织出来的 prompt远比“下面是一整个文件请帮我看看”更精准也更省 token。4. 完整实战用最小代码实现一个 LSP-LLM 闭环有了前文的理论基础接下来我们实现一个最小可运行的 LSP 服务器。它会通过 stdio 与客户端通信。打开文件时调用一个“模拟 LLM 分析函数”生成诊断信息。支持 hover 返回基于模型的解释。支持 completion 返回 LLM 风格的补全候选。这个示例不依赖具体大模型 SDK核心是为了说明协议交互。你可以把llmAnalyze函数替换成真实模型调用。4.1 项目结构llm-lsp-demo/ ├── client/ # VS Code 扩展客户端 │ ├── package.json │ └── src/ │ └── extension.ts ├── server/ │ └── server.js # LSP 服务器 └── .vscode/ └── launch.json4.2 最小 LSP 服务器创建server/server.js// 文件路径server/server.js const readline require(readline); const rl readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false }); let buffer ; function sendMessage(msg) { const body JSON.stringify(msg); const header Content-Length: ${Buffer.byteLength(body, utf-8)}\r\n\r\n; process.stdout.write(header body); } // 模拟 LLM 分析函数真实项目中这里可以替换为模型调用 function llmAnalyze(uri, text) { const diagnostics []; if (text.includes(TODO)) { diagnostics.push({ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 4 } }, severity: 2, source: llm-lsp, message: [LLM] 检测到 TODO 标记建议在提交前补充说明或移除。 }); } if (!text.includes(function main)) { diagnostics.push({ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 2 } }, severity: 3, source: llm-lsp, message: [LLM] 未找到入口函数 main请确认文件是否完整。 }); } return diagnostics; } function handleMessage(msg) { if (msg.method initialize) { sendMessage({ jsonrpc: 2.0, id: msg.id, result: { capabilities: { // 1 表示 Full 同步2 表示 Incremental 同步 textDocumentSync: 1, hoverProvider: true, completionProvider: { triggerCharacters: [., :] } }, serverInfo: { name: llm-lsp-demo, version: 0.1.0 } } }); } else if (msg.method textDocument/didOpen) { const doc msg.params.textDocument; sendMessage({ jsonrpc: 2.0, method: textDocument/publishDiagnostics, params: { uri: doc.uri, diagnostics: llmAnalyze(doc.uri, doc.text) } }); } else if (msg.method textDocument/didChange) { const doc msg.params.textDocument; // 当前使用 Full 同步模式contentChanges[0].text 是完整文本 const text msg.params.contentChanges[0].text; sendMessage({ jsonrpc: 2.0, method: textDocument/publishDiagnostics, params: { uri: doc.uri, diagnostics: llmAnalyze(doc.uri, text) } }); } else if (msg.method textDocument/hover) { sendMessage({ jsonrpc: 2.0, id: msg.id, result: { contents: { kind: markdown, value: **LLM 语义提示**\n\n这里可以返回模型生成的类型解释、错误原因或代码导读。 } } }); } else if (msg.method textDocument/completion) { sendMessage({ jsonrpc: 2.0, id: msg.id, result: { isIncomplete: false, items: [ { label: llmCompletion, kind: 6, detail: LLM 补全候选 }, { label: lspContext, kind: 6, detail: 语义上下文补全 } ] } }); } } rl.on(line, (chunk) { buffer chunk; let idx; while ((idx buffer.indexOf(\r\n\r\n)) ! -1) { const headerPart buffer.slice(0, idx); const match /Content-Length: (\d)/i.exec(headerPart); if (!match) { buffer ; break; } const contentLength parseInt(match[1], 10); const totalLength idx 4 contentLength; if (buffer.length totalLength) { break; } const body buffer.slice(idx 4, totalLength); buffer buffer.slice(totalLength); try { handleMessage(JSON.parse(body)); } catch (err) { // 记录日志避免服务器崩溃 console.error(handle message error:, err); } } });这个服务器就是完整的最小实现。Content-Length的解析是关键如果头部解析有偏差客户端会一直等待响应。4.3 将模拟分析替换为真实 LLM 调用真实项目中llmAnalyze可以改为异步调用大模型。下面是一个本地推理服务调用示例以常见的 HTTP 接口为例// 文件路径server/llmClient.js示意 async function callLLM(prompt) { const endpoint http://localhost:11434/api/generate; const modelName your-local-model-name; // 请替换为本地实际模型名 const resp await fetch(endpoint, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: modelName, prompt, stream: false }) }); const data await resp.json(); return data.response || ; }需要注意不要把 API Key 直接写进代码建议通过环境变量注入。本地推理服务的地址和模型名需要按实际环境调整。大模型响应有延迟建议在 LSP 服务器中做缓存和异步处理不要阻塞协议响应。4.4 在 VS Code 中注册客户端调试如果你希望直接在 VS Code 里调试这个 LSP 服务器最简单的方式是写一个最小的 VS Code 扩展客户端。创建client/package.json{ name: llm-lsp-demo-client, displayName: LLM LSP Demo Client, version: 0.1.0, engines: { vscode: ^1.85.0 }, categories: [Other], activationEvents: [], main: ./out/extension.js, contributes: { languages: [ { id: plaintext, extensions: [.txt] } ] }, scripts: { compile: tsc -p ./, watch: tsc -watch -p ./ }, devDependencies: { types/node: ^20.0.0, types/vscode: ^1.85.0, typescript: ^5.0.0 } }创建client/src/extension.ts// 文件路径client/src/extension.ts import * as path from path; import { workspace, ExtensionContext } from vscode; import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from vscode-languageclient/node; let client: LanguageClient; export function activate(context: ExtensionContext) { const serverModule context.asAbsolutePath(path.join(server, server.js)); const serverOptions: ServerOptions { run: { module: serverModule, transport: TransportKind.stdio }, debug: { module: serverModule, transport: TransportKind.stdio, options: { execArgv: [--inspect6009] } } }; const clientOptions: LanguageClientOptions { // 这里选择 plaintext 语言实际项目可按语言 ID 分流 documentSelector: [{ scheme: file, language: plaintext }], synchronize: { fileEvents: workspace.createFileSystemWatcher(**/*.txt) } }; client new LanguageClient( llmLspDemo, LLM LSP Demo, serverOptions, clientOptions ); client.start(); } export function deactivate(): Thenablevoid | undefined { return client?.stop(); }注意server目录需要放在扩展根目录下并且server.js需要能被 Node.js 直接执行。如果extension.ts编译到out/context.asAbsolutePath指向的是扩展根目录不是out目录因此路径拼接时要留意。4.5 运行与预期输出在 VS Code 中按 F5 启动扩展调试打开一个.txt文件。如果文件内容包含TODO底部问题面板会出现一条来源为llm-lsp的提示。预期协议交互大致如下客户端发送initialize服务器返回capabilities。客户端发送textDocument/didOpen服务器返回textDocument/publishDiagnostics。用户在文件中输入代码客户端发送textDocument/didChange服务器重新推送诊断。光标悬停在任意位置客户端发送textDocument/hover服务器返回 markdown 内容。5. 进阶把 LSP 变成 LLM 的“眼睛”和“手”5.1 诊断驱动的修复循环诊断信息是 LLM 修复代码最直接的数据源。一个可行的闭环是LSP 服务器拿到publishDiagnostics中的错误列表。插件把“错误位置 错误代码上下文 错误信息”拼成 prompt。LLM 生成修复建议。插件通过workspace/applyEdit请求把修复内容写回编辑器。这里的核心技巧是不要只给 LLM 一段错误代码还要带上函数签名、相关变量定义、相邻函数调用关系。LSP 的documentSymbol和definition接口正好可以补齐这些信息。5.2 语义索引与 RAG 结合当项目规模变大单靠 LSP 实时查询可能不够。一个更工程化的架构是用 LSP 能力提取代码语义索引文件、符号、引用关系。将索引内容向量化后存入向量数据库。用户提问时先做语义检索再把检索结果和 LSP 实时状态一起交给 LLM。这种方式能有效控制 prompt 长度也能让模型聚焦在用户真正关心的代码片段上。需要注意的是Embedding 质量、数据更新频率和检索策略会直接影响效果。5.3 inline completion 与 inlayHint传统补全适合“候选列表”但 AI 编程中更自然的交互是内联补全光标后面出现一段灰色代码按 Tab 接受。实现内联补全时可以将已有 LSP 补全能力扩展为内联模式也可以直接使用编辑器扩展 API。inlayHint则适合在代码行内显示类型推断、参数名称、即将执行的函数说明。这些信息非常适合由 LLM 生成但要注意提示内容不要遮挡真实代码避免干扰阅读。5.4 Multi-file 上下文与 workspace symbol真实项目的问题往往跨文件。例如用户问“这个函数在哪里被调用”LLM 不能只读当前文件。LSP 的workspace/symbol和textDocument/references接口可以解决这类问题找到当前函数定义。搜索整个工作区内的引用。把引用点的代码片段作为上下文交给 LLM。这个方案比“把整个工作区索引喂给向量库”更轻量也更实时。6. 常见问题与排查思路问题现象常见原因解决思路客户端一直等待响应服务器没有输出Content-Length头部解析错误或消息体长度计算错误用Buffer.byteLength计算字节数不要用String.length文件修改后诊断不更新textDocumentSync设为 Incremental但代码按 Full 处理统一使用 Full 模式或正确解析增量补丁 rangeLSP 服务器启动即退出初始化握手失败或initialize响应缺少capabilities在代码中打印错误日志并用调试模式检查 stderrLLM 响应太慢补全卡顿同步调用模型接口改为异步处理设置超时对常见请求做缓存模型返回内容被截断prompt 超过上下文窗口用 LSP 查询只保留相关符号和诊断信息减少无关代码用户代码被重复发送给模型成本很高每次编辑都生成完整 prompt结合增量同步和缓存只在关键节点触发模型调用排查顺序建议先确认 LSP 握手是否成功看initialize响应。再确认didOpen是否到达服务器。检查publishDiagnostics是否被客户端接收。最后才怀疑模型调用本身的问题。7. 最佳实践与工程建议7.1 上下文预算管理LLM 的 token 预算不是越大越好而是要在预算内放入最相关的信息。建议为上下文划分优先级第一优先级当前文件当前行附近的代码、诊断信息、报错位置。第二优先级当前函数定义、当前函数调用链。第三优先级相关符号定义、工作区搜索结果。第四优先级项目说明、技术栈信息。如果预算不够优先丢弃低优先级内容而不是盲目截断第一优先级的代码。7.2 安全边界让 LLM 生成修复代码、补全代码时必须设置安全边界不允许模型直接执行代码所有修改建议都通过编辑器 diff 展示。对workspace/applyEdit做权限校验尤其是自动应用修改时。渲染模型返回的 markdown 时避免执行其中的脚本或命令。不要把用户代码无限制发送到外部模型接口敏感项目需要本地化部署。7.3 低延迟缓存与异步处理LSP 是实时交互协议用户每敲一个字符都可能触发事件。如果每个事件都同步调用 LLM延迟和成本都会失控。推荐的架构是编辑器事件先进入队列。对事件做防抖debounce短时间内的连续输入合并为一次分析。对高频请求做缓存比如相同位置的 hover 请求直接返回缓存。用流式接口把 LLM 结果逐段返回提升用户体验。7.4 版本兼容与降级策略LSP 规范本身有多个版本不同编辑器的支持程度也不同。并且大模型产品接口迭代很快生产环境一定要考虑降级当模型接口超时或不可用时自动回退到静态补全或历史缓存结果。用配置开关控制是否启用 LLM 自动修复避免在关键开发环境意外改动代码。对 LSP 能力做能力探测如果客户端不支持某个请求不要反复发送。7.5 日志与可观测性LSP 调试最麻烦的地方在于日志看不见。建议在服务器启动时把请求、响应、模型调用耗时写到独立日志文件方便定位// 示意LSP 服务器中记录调试日志 function log(message) { const fs require(fs); fs.appendFileSync(/tmp/llm-lsp.log, ${new Date().toISOString()} ${message}\n); }日志至少要包含收到的请求方法。响应耗时。模型调用输入输出长度。异常堆栈。8. 总结与延伸方向本文从 LSP 的协议机制讲起分析了传统 LLM 代码助手在上下文获取上的痛点然后用一个最小 LSP-LLM 闭环示例演示了协议交互过程并补充了诊断驱动修复、语义检索、内联补全等进阶方向。接下来如果你要继续深入可以从这几个方向思考如果想深入了解协议细节去读 LSP 规范中的textDocument和workspace方法定义。如果想做生产级工具建议先用一个语言、一个编辑器跑通闭环再横向扩展。如果关注成本控制优先研究增量同步、缓存、检索增强这三块。如果关注交互体验重点研究流式输出和编辑器 diff 交互。最后留一个建议不要一上来就写复杂架构先用最少的代码跑通 LSP 握手再逐步加入模型调用。协议通了后面所有功能都能在这个基础上长出来。希望这份“LSPs for LLMs”的整理能帮你在 AI 编程工具的路上少踩一些坑。