lsp — 给 Agent 一双「语言服务器」的眼睛

简介

没有 LSP 时，agent 理解代码主要靠 read、grep、模型脑补类型与引用。文件一多、重构一深就翻车：改了函数签名漏改调用点、类型错误要手动跑 tsc/cargo check、「符号定义在哪」全靠猜。@piex-dev/lsp 把 LSP 能力做成 pi 工具，让模型在改代码前后主动问语言服务器。

技术原理

最值钱的能力：diagnostics（有哪些 error/warning）、definition/references（改一处影响哪里）、hover（符号类型）、symbols（结构大纲）、format（统一风格）。按文件后缀在 defaults.json 匹配 server，用 root markers 找 workspace root，spawn 子进程跑 stdio JSON-RPC，同一 root + server 会话内缓存避免冷启动。诊断靠 server 主动推 publishDiagnostics，客户端按 URI 缓存——edit 后立刻能问「还有没有红线」，形成改→验→再改闭环。

编辑器/Agent          Language Server
     |                        |
     |  initialize            |
     |  textDocument/*        |
     | ---------------------> |
     |  publishDiagnostics    |
     | <--------------------- |

使用说明

安装

pi install npm:@piex-dev/lsp

仓库源码：extensions/lsp

前提条件

扩展是客户端，不是 server 分发器。语言服务器本体要本机可执行（如 typescript-language-server、rust-analyzer、pyright、gopls）。defaults.json 已为约 50 个 server 写好启动命令与参数。

配置

默认配置在 extensions/lsp/defaults.json，每个 server 含 command / fileTypes / rootMarkers / initOptions / settings / isLinter。单 server 命令可用环境变量 PI_<NAME>_LSP_COMMAND 覆盖；写后诊断可用 PI_LSP_DIAGNOSTICS_ON_EDIT=0 关闭。

验证

cd extensions/lsp && npm install && bun test   # mock server 单测
pi -e ./extensions/lsp/src/lsp.ts -p "what is 1+1" --no-session  # 冒烟

实现方案

lsp.ts 是客户端 + 路由 + 工具 + 写后诊断 hook；defaults.json 配约 50 个 server。写后诊断钩住 edit/write（含 hashline）：sync 磁盘 → 等 publishDiagnostics → 仅 ERROR、每文件 cap 20，附结果末尾。

正确性要点：诊断 settle（最后一条 publish 后静默 N ms，默认 800ms）；LSP 3.17 pull 诊断（diagnosticProvider 声明才拉）；resolveProvider 门控；重叠 TextEdit 区间相交拒绝；stderr 捕获进错误消息（cap 16KB）；which 含 node_modules/.bin、.venv/bin；Windows .bat/.cmd 经 cmd.exe /d /s /c 包装。

设计参考

核心取舍：优先写后 ERROR 闭环（学 OpenCode），诊断优于导航暴露；linter 不抢 primary server 的导航角色。

迭代记录

路线图

版本记录

0.2.0 教训：intelephense 这类 server 先推空再推真，到即返把有错文件报成干净；server 崩溃只有 exit code，排障全靠猜。0.3.0 补齐协议细节。

附录：pi LSP 生态能力逐项对比

四个项目（omp / OpenCode / pi-extensions pi-lsp / piex lsp）的客观能力差异。