@epoch-agent/plugin-lsp 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -193,50 +193,40 @@ interface ResolveServerOptions {
 declare function resolveServer(spec: ServerSpec, projectRoot: string, options?: ResolveServerOptions): ServerResolution;
 
 /**
- * 一个 language server 连接（方案 38）。
+ * 一个 language server 连接。
  *
  * 协议实现**不手写**：`vscode-jsonrpc` 负责分帧和 JSON-RPC，
  * `vscode-languageserver-protocol` 提供消息描述符和类型。真正用到的只有五条：
  * `initialize` / `initialized` / `didOpen` / `didChange` / `publishDiagnostics`
  * （外加 `didClose` 做逐出、`shutdown` + `exit` 做优雅退出）。
  *
- * 进程**一律走 infra 的 `startLongLivedProcess`**（方案 36），这个包里不长
- * 第二套进程管理 —— 顺带的好处是 `epoch` 退出时 server 被天然一并收掉（验收 7），
- * 我们一行清理代码都不用写。
+ * 进程**一律走 infra 的 `startLongLivedProcess`**，这个包里不长第二套进程管理 ——
+ * 顺带的好处是 `epoch` 退出时 server 被天然一并收掉，我们一行清理代码都不用写。
  *
- * 收它的那条链子（方案 60 之后）：`startLongLivedProcess` 登记进的是**进程级
- * 兜底表** —— 这个池是模块级单例、按项目根共享，压根没有 `sessionId`，归兜底表
- * 是结论不是妥协（判据在 [README](../README.md)）。最后一个 runtime
- * `dispose()` → `OwnedProcessTable.release()` 把兜底表的引用计数减到 0，那一下
- * 连兜底表一起收。一个进程一个 runtime 的 CLI / TUI 每次 dispose 都归零，
- * 所以和方案 60 之前逐字节相同；两个 runtime 并存时先走的那个碰不到这个池
+ * 收它的那条链子：`startLongLivedProcess` 登记进的是**进程级兜底表** —— 这个池是
+ * 模块级单例、按项目根共享，压根没有 `sessionId`，归兜底表是结论不是妥协（判据在
+ * [README](../README.md)）。最后一个 runtime `dispose()` → `OwnedProcessTable.release()`
+ * 把引用计数减到 0 时连兜底表一起收；两个 runtime 并存时先走的那个碰不到这个池
  * （否则表现是「跑了条定时任务，之后 `lsp_diagnostics` 每次都要重新冷启 tsserver」）。
  *
  * ## 诊断是**推**过来的，所以「什么时候算收全了」得自己判
  *
- * 这个协议里没有「诊断请求」这种东西（typescript-language-server 4.4 也不支持
- * 3.17 的 pull 模式 —— `initialize` 的结果里没有 `diagnosticProvider`）。
- * server 想发就发，而 tsserver 一个文件会**分三次**发（语法 / 语义 / 建议，
- * 各自 50ms 去抖），先到的那一份是不全的。
- *
- * 判据因此是**静默**：请求的文件都答过了，且最近一次动静距今超过 `settleMs`。
+ * 这个协议里没有「诊断请求」这种东西（typescript-language-server 4.4 也不支持 3.17
+ * 的 pull 模式 —— `initialize` 的结果里没有 `diagnosticProvider`）。server 想发就发，
+ * 而 tsserver 一个文件会**分三次**发（语法 / 语义 / 建议，各自 50ms 去抖），先到的
+ * 那一份是不全的。判据因此是**静默**：请求的文件都答过了，且最近一次动静距今超过
+ * `settleMs`。
  *
  * ### 还有一条更阴的：内容没变时 server 干脆不发
  *
- * typescript-language-server 的 `FileDiagnostics.update()` 里有这么一句
- * （lib/cli.mjs）：
- *
- * ```js
- * if (this.diagnosticsPerKind.get(kind)?.length === 0 && diagnostics.length === 0) return;
- * ```
- *
- * 也就是「这一类上次是空、这次还是空」就**不推送**。于是一个干净的文件被诊断
- * 第二次时一条消息都收不到 —— 如果按「没答复 = 没结果」处理，就会把它报成
- * 「server 没回答」，而它其实是最正常的那种情况。
+ * typescript-language-server 的 `FileDiagnostics.update()`（lib/cli.mjs）里有一句
+ * `if (this.diagnosticsPerKind.get(kind)?.length === 0 && diagnostics.length === 0) return;`
+ * —— 「这一类上次是空、这次还是空」就**不推送**。于是一个干净的文件被诊断第二次时
+ * 一条消息都收不到；按「没答复 = 没结果」处理就会把它报成「server 没回答」，而它
+ * 其实是最正常的那种情况。
  *
- * 所以有第二条判据：**没答复但有上一次的结果，就用上一次的**。这在语义上是
- * 对的，因为那句 `return` 恰好只在「什么都没变、也没什么可报」时生效；一旦某一类
- * 从有变没或从没变有，它就会照常推送。
+ * 所以有第二条判据：**没答复但有上一次的结果，就用上一次的**。那句 `return` 恰好只在
+ * 「什么都没变、也没什么可报」时生效；一旦某一类从有变没或从没变有，它就会照常推送。
  */
 
 /** 一次批量诊断的输入 */
@@ -315,14 +305,13 @@ declare class LspClient implements DiagnosticsClient {
     private stderr;
     private constructor();
     get pid(): number;
-    /** 还能用吗。池按这个决定要不要重启（验收 9） */
+    /** 还能用吗。池按这个决定要不要重启 */
     get alive(): boolean;
     /**
      * 起进程 + `initialize` + `initialized`。
      *
-     * 起不来 / 初始化超时都**返回 `null` 而不抛** —— 调用方据此把这个语言标记
-     * 不可用，整轮照常出结果（验收 8）。抛出去的话一个慢 server 就能让整次工具
-     * 调用失败，而那正是这条验收要避免的。
+     * 起不来 / 初始化超时都**返回 `null` 而不抛** —— 调用方据此把这个语言标记不可用，
+     * 整轮照常出结果。抛出去的话一个慢 server 就能让整次工具调用失败。
      */
     static start(options: StartClientOptions): Promise<LspClient | null>;
     /** 订阅推送 + 兜住 server 反过来发的那几种请求 */
@@ -333,7 +322,7 @@ declare class LspClient implements DiagnosticsClient {
     /**
      * 打开 / 更新这批文件，等到静默，交出诊断。
      *
-     * @throws {LspServerDownError} 进程中途没了（验收 9 的输入）
+     * @throws {LspServerDownError} 进程中途没了
      */
     diagnose(documents: DocumentInput[], wait: WaitOptions): Promise<DiagnoseBatch>;
     /** 没打开过就 `didOpen`，打开过就 `didChange`（全量） */
@@ -345,21 +334,17 @@ declare class LspClient implements DiagnosticsClient {
      *
      * 先按协议 `shutdown` + `exit`，给它清临时文件的机会；超预算就直接杀树。
      * **杀树那一步不能省** —— `typescript-language-server` 自己还 fork 了一个
-     * `tsserver.js`，只杀父进程会留下孤儿（验收 7）。
+     * `tsserver.js`，只杀父进程会留下孤儿。
      *
      * ## ⚠️ 三步的**顺序**是判据：拍快照 → 优雅关 → 清扫快照
      *
-     * 这里原来只有两步（优雅关 → `killTrackedProcess`），而那是**漏的**：
      * `killTrackedProcess` 底下是 `killProcessTree`，靠的是**现场遍历**
-     * （`pgrep -P` / `taskkill /t`）。等我们优雅关完，直接子进程已经退了 ——
-     * 树的根没了，孙进程的 PPID 指向一个死 pid，遍历再也找不到它们。
-     * 于是 `tsserver` 那一层在 POSIX 上被 init 收养、在 Windows 上直接常驻到关机。
+     * （`pgrep -P` / `taskkill /t`）。等我们优雅关完，直接子进程已经退了 —— 树的根
+     * 没了，孙进程的 PPID 指向一个死 pid，遍历再也找不到它们：`tsserver` 那一层在
+     * POSIX 上被 init 收养、在 Windows 上直接常驻到关机。所以快照必须在**动手之前**拍。
      *
-     * 所以快照必须在**动手之前**拍。这不是新发明：`plugin-mcp` 的
-     * `closeTransportAndReap` 就是这三步，而它有一条会红的用例守着；
-     * 我们这边验收 #7 一直挂着「双平台手验」没人做，于是漏了一年半。
-     * 2026-08-12 补的 [orphan-reap.test.ts](../__tests__/orphan-reap.test.ts)
-     * 把这条钉死了 —— 把下面的快照挪到 `killTrackedProcess` 之后，它当场红。
+     * `orphan-reap.test.ts` 把这条钉死了 —— 把下面的快照挪到 `killTrackedProcess`
+     * 之后，它当场红。
      */
     dispose(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/plugin-lsp",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "private": false,
   "description": "LSP 诊断插件 — 探测项目自带的 language server，按文件取语义诊断",
   "repository": {
@@ -24,8 +24,8 @@
   "dependencies": {
     "vscode-jsonrpc": "^9.0.1",
     "vscode-languageserver-protocol": "^3.17.5",
-    "@epoch-agent/infra": "4.0.0",
-    "@epoch-agent/protocol": "4.0.0"
+    "@epoch-agent/infra": "4.1.0",
+    "@epoch-agent/protocol": "4.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",