@wbline/pi-lsp
On-demand LSP diagnostics and source fixes across 25+ languages, plus built-in CLI lint runners (ruff, biome, shellcheck) — aggregated into one check report for the Pi coding agent.
Package details
Install @wbline/pi-lsp from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@wbline/pi-lsp- Package
@wbline/pi-lsp- Version
1.5.1- Published
- Nov 22, 2026
- Downloads
- 612/mo · 368/wk
- Author
- wongbin
- License
- MIT
- Types
- extension
- Size
- 627.1 KB
- Dependencies
- 0 dependencies · 2 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@wbline/pi-lsp
Pi coding agent 的代码检查扩展: 按需的语言服务器(LSP)诊断与源码修复,覆盖 28 种语言服务器;外加内置 CLI lint runner(ruff / biome / shellcheck),一键聚合成统一报告。
无需任何配置文件——装上即用,缺失的服务器与 lint 工具会按内置配方自动安装。
安装
pi install npm:@wbline/pi-lsp # 从 npm 安装
工具
| 工具 | 说明 |
|---|---|
lsp_checks |
日常主力。一键聚合:LSP 通道 + 全部匹配的 CLI runner 并行执行,输出统一报告。改完代码跑一次即可 |
lsp_diagnostics |
只要 LSP 诊断时用(lsp_checks 的 LSP-only 子集),可指定单个/多个服务器 |
lsp_fix |
对一个或多个文件应用 LSP source action(默认 source.fixAll,如组织导入用 source.organizeImports)。多文件按服务器分组,每个服务器只启动一次 |
共享参数:
server接受单个名称或名称数组;lsp_checks另有对称的runners参数限制 runner 通道(如runners: ["ruff"])。未知名称报错并列出可用 idmaxDiagnostics(默认 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)。
改完代码自动检查
默认关闭。在 ~/.pi/agent/pi-lsp.json 设置 "autoCheckBeforeReply": true 开启后:当 pi 一轮回答结束(不再调用工具)且本轮发生过代码修改、其间没有跑过任何诊断检查时,pi-lsp 自动注入一条提醒,要求 pi 对改动的文件调用 lsp_checks 汇总检查;pi 修复后新产生的修改会在下一轮收尾时再次被检查。
追踪的编辑工具:pi 内置
write/edit、IDE 模式的 apply_patch/create_new_file/rename/reformat/optimize_imports、以及lsp_fix(bash 改动的文件无法可靠识别,不在追踪范围);rename 场景新旧路径都会被追踪。扩展名不在任何检查路由支持列表内(LSP 服务器 + CLI runner)的文件不追踪——写 README、改.gitignore不会触发代码检查;将来配置了 marksman 之类的文档服务器后,.md自动恢复追踪检查结算按覆盖范围精确进行:
lsp_checks/lsp_diagnostics传了paths时只结算这些文件,未传(全仓收集)才结算全部;结算只覆盖检查调用前已记录的修改,检查运行期间并行落盘的编辑不会被旧检查吞掉,仍会在下一轮收尾时被提醒连续 3 次提醒未被理会后暂时静默,防止「修复 → 再检查」无限循环;每次成功检查、以及用户发出新消息(新工作周期),都会重置静默计数
配置文件
~/.pi/agent/pi-lsp.json:{ "autoCheckBeforeReply": true }文件缺失、字段缺失或 JSON 损坏都按默认(关闭)处理。环境变量
PI_LSP_AUTO_CHECK(0/false/off/no关闭,其余值开启)优先于配置文件,适合临时覆盖。设置在会话启动时读取,改完需重启 pi 或开新会话。
自动安装
所有缺失的 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 安装进程
- 安装期间就报状态:下载/装包可能几十秒,状态栏从第一件事就显示
<工具> installing,跑起来换成<工具> check(LSP 通道是<服务器> diagnostics/fix)。两条通道一路一个 key,收尾由派发层统一清——安装失败、取消、运行报错都不会留一行挂着不动的状态 - 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_diagnostics按服务器各自的文件策略(扩展名 + 跳过目录)分别收集、相同策略共享一次遍历;runner 通道独立收集。同名内置 runner 实际可用时,对应 LSP 通道自动让位,避免两个通道重复报告同一批文件 - 文件遍历按广度优先:50 上限截断时,收集到的文件分布在整棵树最浅的各目录中,而不是耗尽某一个按字典序排前的深分支
- 诊断输出截断:
maxDiagnostics按通道封顶渲染条数,摘要计数始终展示真实总数 - 批量 fix 只返回摘要,且单文件失败不中断批次:多文件时每文件只返回状态与 action 计数,失败的文件标注
failed (原因)后继续处理其余文件,头部汇总失败数;单文件调用保留修好后的全文预览,失败仍按工具错误抛出。服务器跨文档/资源级变更(documentChanges指向其他文件、create/rename/delete)不会被静默丢弃:单文件调用在末尾列出未应用的变更,批处理在行内标注 skipped 计数。整批受 5 分钟总预算保护,预算耗尽后剩余文件如实标注,不会无限等待 - 超时预算按方法分级:
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