@wbline/pi-lsp

Pi coding agent 的代码检查扩展： 按需的语言服务器（LSP）诊断与源码修复，覆盖 28 种语言服务器；外加内置 CLI lint runner（ruff / biome / shellcheck），一键聚合成统一报告。

无需任何配置文件——装上即用，缺失的服务器与 lint 工具会按内置配方自动安装。

安装

pi install npm:@wbline/pi-lsp        # 从 npm 安装

工具

共享参数：

• server 接受单个名称或名称数组；lsp_checks 另有对称的 runners 参数限制 runner 通道（如 runners: ["ruff"] ）。未知名称报错并列出可用 id
• maxDiagnostics（默认 200）封顶每条通道渲染的诊断数，超出截断并显示剩余数量，防止单次报告 token 失控
• autoInstall: false 可在单次调用中关闭自动安装

支持的语言

28 个内置 LSP 服务器，按文件扩展名自动路由：

• Web：TypeScript/JS（tsserver + biome 双引擎）、Vue/JSX/TSX（biome）、PHP（intelephense）
• Python：ty（类型）+ ruff（lint）组合
• 系统：Rust（rust-analyzer）、C/C++（clangd）、Zig（zls）、Swift（sourcekit-lsp）
• JVM：Java（jdtls，含全自动安装器）、Kotlin（kotlin-lsp）
• 其他 ：Go（gopls）、Ruby（rubocop）、Elixir、Lua、C#、F#、Prisma、Dart、OCaml、Bash、Terraform、LaTeX（texlab）、Gleam、Clojure、Nix、Typst（tinymist）、Haskell

CLI runner：ruff（Python lint）、biome（JS/TS lint + 格式）、shellcheck（Shell）。

自动安装

所有缺失的 LSP 服务器与 CLI 工具默认尽力自动安装（结果标注 [auto-installed]）：

• CLI 工具按候选配方尝试系统包管理器：biome 走 npm i -g，shellcheck 走 winget/scoop
• Python 工具（ty、ruff，LSP 与 CLI 同渠道）：统一走 uv——先检测/自动安装 uv 本体（官方独立安装脚本，不依赖系统 Python），再 uv tool install。uv 与工具 shim 都落在 ~/.local/bin，扩展自动搜索该目录（装完立即可见，无需重启 pi），无需手动配 PATH，也与系统 Python 形态（商店版 / user 安装 / venv）无关；pip/pipx 渠道已移除——pip 装进商店版 Python 后命令不在 PATH，正是 uv 通道要规避的问题
• 多数其他 LSP 服务器按配方走包管理器（bash-language-server、rust-analyzer、clangd、terraform-ls、tinymist 等）
• 装后校验：安装成功后用工具自身 --version 探活，"装了但跑不起来"视为候选失败，继续下一个；探活与装后重解析前会自动重扫扩展的工具目录搜索路径（安装可能新建 bin 目录，如 winget 首装的 WinGet\Links、首次 npm i -g 的 %APPDATA%\npm、uv 的 ~/.local/bin），已运行进程读不到新 PATH 也不会误判
• 并发调用共享同一次安装，不会重复 spawn 安装进程
• jdtls（Java）：无包管理器渠道，走专用下载安装器（仅 Windows）——自动下载 eclipse.jdt.ls + 托管 JDK 21 到 ~/.pi/agent/lsp（隔离安装，不改 PATH、不动已有 JDK）。版本与下载地址运行时动态发现（官方源 + 中科大/清华镜像回退），官方发新版无需改代码；下载成功的压缩包保留在 ~/.pi/agent/lsp/archives/，换机时放回该目录即可完全离线安装；下载先写临时文件、成功后才落盘为种子，中断不会留下半个归档污染种子目录
• 无可靠安装渠道的服务器（如 ocaml-lsp、haskell-language-server）保持诚实跳过，明确提示安装方式，不冒充"干净"

Windows 兼容：.cmd/.bat 经 cmd /d /s /c 启动；无扩展名 shim（如 nvm）自动回退 .cmd/.exe。

设计取舍

• spawn-per-call 而非常驻 LSP 进程：每次调用冷启动服务器、跑完即关——零状态泄漏、无悬挂进程、单通道失败不拖垮其他通道；代价是重复调用的启动开销。批量接口（ lsp_fix 的 paths 多文件、lsp_checks 一次聚合）就是对此的补偿——按服务器/runner 分组，每条通道只 spawn 一次
• 文件收集默认全仓、上限 50 个文件：不传 paths 时默认扫 workspace root，达到上限时报告头部明确提示，让模型知道结果是部分的。lsp_checks 的一次遍历由所有 LSP 服务器与 runner 共享（全局上限）；lsp_diagnostics 按服务器各自的文件策略（扩展名 + 跳过目录）分别收集、相同策略共享一次遍历（各 50）
• 文件遍历按广度优先：50 上限截断时，收集到的文件分布在整棵树最浅的各目录中，而不是耗尽某一个按字典序排前的深分支
• 诊断输出截断：maxDiagnostics 按通道封顶渲染条数，摘要计数始终展示真实总数
• 批量 fix 只返回摘要，且单文件失败不中断批次：多文件时每文件只返回状态与 action 计数，失败的文件标注 failed (原因) 后继续处理其余文件，头部汇总失败数；单文件调用保留修好后的全文预览，失败仍按工具错误抛出。服务器跨文档/资源级变更（documentChanges 指向其他文件、create/rename/delete）不会被静默丢弃：单文件调用在末尾列出未应用的变更，批处理在行内标注 skipped 计数
• 超时预算按方法分级：initialize 使用 3 倍预算（jdtls/tsserver 大仓冷启动经常超过单请求预算），其余请求保持标准预算；pull 诊断请求超时但服务器已发布过 push 诊断时，降级返回已发布的诊断而不是让整条通道失败
• push-only 服务器静默即结算：未实现 pull 诊断的服务器（gopls、jdtls、rubocop 等）配了宽限窗口，干净的文档在窗口后返回空结果，不再拖满整体超时

致谢

设计借鉴：

• pi-lsp （narumiruna/pi-extensions）——轻量骨架：按扩展名路由、spawn-per-call、会话作用域、workspace 越界防护
• pi-lens——内置 runner 抽象、按优先级分发、诚实的结果分类（「查出了问题」是 completed check，不是 failed runner）、可用性探测 TTL 缓存

开发

npm install
npm run check   # 源码 + 测试双 typecheck
npm test        # vitest
npm run build   # 输出 dist/（发布用;pi 加载源码无需构建）

License

MIT