@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.

Packages

Package details

extension

Install @wbline/pi-lsp from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:@wbline/pi-lsp
Package
@wbline/pi-lsp
Version
1.3.1
Published
Oct 16, 2026
Downloads
692/mo · 692/wk
Author
wongbin
License
MIT
Types
extension
Size
464.3 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"] ）。未知名称报错并列出可用 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）
  • 诊断输出截断：maxDiagnostics 按通道封顶渲染条数，摘要计数始终展示真实总数
  • 批量 fix 只返回摘要：多文件时每文件只返回状态与 action 计数；单文件调用保留修好后的全文预览。服务器跨文档/资源级变更（documentChanges 指向其他文件、create/rename/delete）不会被静默丢弃：单文件调用在末尾列出未应用的变更，批处理在行内标注 skipped 计数

致谢

设计借鉴：

  • 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