@trim21/personal-pi-extensions 0.1.576 → 0.1.577

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.576",
+  "version": "0.1.577",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/lib/lsp/client.ts

@@ -307,6 +307,16 @@ interface ServerCapabilities {
 export const clientDefaults = {
   diagnosticsDebounceMs: 150,
   diagnosticsDocumentWaitTimeoutMs: 5_000,
+  /**
+   * document 模式等待上限的补充：该文档上一份诊断为空（服务器手里是干净文档）时，
+   * 内容变化后只用这段安静期等新 push，不再等满 diagnosticsDocumentWaitTimeoutMs。
+   *
+   * typescript-language-server 的 FileDiagnostics.update 在「该类诊断上一轮为空、
+   * 这一轮仍为空」时直接 return 不推送，且它不实现 pull 诊断；这类文档等满整个
+   * 窗口也只会在窗口末尾返回同样的「无诊断」，白等一次编辑。诊断集合变成非空时
+   * 服务器必定推送，所以短安静期不会漏掉这次变更引入的错误。
+   */
+  diagnosticsSilentWaitTimeoutMs: 1_500,
   diagnosticsFullWaitTimeoutMs: 10_000,
   diagnosticsRequestTimeoutMs: 3_000,
   initializeTimeoutMs: 45_000,
@@ -321,6 +331,8 @@ export interface CreateInput {
   /** 可覆盖的超时参数（缺省用 client 默认值，由全局/本地 lsp.json 配置注入）。 */
   diagnosticsDebounceMs?: number;
   diagnosticsDocumentWaitTimeoutMs?: number;
+  /** 上一份诊断为空的文档的等待上限；缺省见 clientDefaults。 */
+  diagnosticsSilentWaitTimeoutMs?: number;
   diagnosticsFullWaitTimeoutMs?: number;
   diagnosticsRequestTimeoutMs?: number;
   initializeTimeoutMs?: number;
@@ -522,6 +534,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
   const diagnosticsDebounceMs = input.diagnosticsDebounceMs ?? clientDefaults.diagnosticsDebounceMs;
   const diagnosticsDocumentWaitTimeoutMs =
     input.diagnosticsDocumentWaitTimeoutMs ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs;
+  const diagnosticsSilentWaitTimeoutMs =
+    input.diagnosticsSilentWaitTimeoutMs ?? clientDefaults.diagnosticsSilentWaitTimeoutMs;
   const diagnosticsFullWaitTimeoutMs =
     input.diagnosticsFullWaitTimeoutMs ?? clientDefaults.diagnosticsFullWaitTimeoutMs;
   const diagnosticsRequestTimeoutMs =
@@ -599,6 +613,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
         at: Date.now(),
         version: typeof params.version === "number" ? params.version : undefined,
       });
+      const document = files[filePath];
+      if (document !== undefined) document.lastPushEmpty = params.diagnostics.length === 0;
       updatePushDiagnostics(filePath, params.diagnostics);
     },
   );
@@ -702,7 +718,15 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("workspace/didChangeConfiguration", { settings });
   }
 
-  const files: Record<string, { version: number; text: string } | undefined> = {};
+  /**
+   * syncedAt：最后一次把该文档内容同步给服务器的时刻（didOpen / didChange）。
+   * lastPushEmpty：服务器对该文档最近一次 push 是否为空（无诊断），随驻留记录
+   * 一起在 didClose 时清除——只在当前驻留周期内成立。
+   */
+  const files: Record<
+    string,
+    { version: number; text: string; syncedAt: number; lastPushEmpty?: boolean } | undefined
+  > = {};
 
   // ── 驻留 LRU ────────────────────────────────────────────────────────────────
 
@@ -1009,7 +1033,20 @@ export async function create(input: CreateInput): Promise<LspClient> {
     after?: number;
     signal?: AbortSignal;
   }): Promise<void> {
+    // 服务器对当前内容的最新结论已在手（最后一次 push 晚于最后一次内容同步，
+    // 即此后没有再通知过内容变化）：直接返回已有结果。部分服务器在诊断集合
+    // 不变时不再推送（typescript-language-server 空→空不发布），等新 push 只会
+    // 耗满整个窗口后得到同样的「无诊断」。
+    const known = published.get(request.path);
+    const document = files[request.path];
+    if (known !== undefined && document !== undefined && known.at >= document.syncedAt) return;
+
     const startedAt = request.after ?? Date.now();
+    // 「上一份 push 为空」的文档用短安静期（见 clientDefaults.diagnosticsSilentWaitTimeoutMs）。
+    const budget =
+      files[request.path]?.lastPushEmpty === true
+        ? Math.min(diagnosticsDocumentWaitTimeoutMs, diagnosticsSilentWaitTimeoutMs)
+        : diagnosticsDocumentWaitTimeoutMs;
     // pull 与 push 语义相同：都是等「当前文档版本」的诊断结果，统一一个循环。
     // 先 pull（拿到即返回）；pull 超时说明服务器未响应，不再重试 pull，只等
     // 版本匹配的 push 兜底；版本不匹配的 push 一律忽略（防迟到旧结果）。
@@ -1017,11 +1054,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
       path: request.path,
       version: request.version,
       after: startedAt,
-      timeout: diagnosticsDocumentWaitTimeoutMs,
+      timeout: budget,
     });
 
     while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = diagnosticsDocumentWaitTimeoutMs - (Date.now() - startedAt);
+      const remaining = budget - (Date.now() - startedAt);
       if (remaining <= 0) return;
       const result = await requestDocumentDiagnostics(request.path);
       if (result.matched) return;
@@ -1088,13 +1125,21 @@ export async function create(input: CreateInput): Promise<LspClient> {
 
     const document = files[resolvedPath];
     if (document !== undefined) {
+      // 内容与服务器已知文本一致：不重复通知（didChange 会把已有诊断判为过期，
+      // 而部分服务器对内容未产生新结论的文档不再推送，见 diagnosticsSilentWaitTimeoutMs）。
+      if (document.text === text) {
+        touch(resolvedPath);
+        return document.version;
+      }
+
       // didChange：内容已变，旧诊断立即失效。清空缓存避免等待窗口内服务器
       // 重算未完成时（大项目可远超窗口）聚合到过期诊断；新 push 到达即填充。
       pushDiagnostics.delete(resolvedPath);
       pullDiagnostics.delete(resolvedPath);
 
       const next = document.version + 1;
-      files[resolvedPath] = { version: next, text };
+      // 保留 lastPushEmpty：安静期判据看的是「变更前服务器最后一份结论是否为空」
+      files[resolvedPath] = { ...document, version: next, text, syncedAt: Date.now() };
       documentVersions.set(resolvedPath, next);
       await connection.sendNotification("textDocument/didChange", {
         textDocument: { uri, version: next },
@@ -1118,7 +1163,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("textDocument/didOpen", {
       textDocument: { uri, languageId, version: 0, text },
     });
-    files[resolvedPath] = { version: 0, text };
+    files[resolvedPath] = { version: 0, text, syncedAt: Date.now() };
     documentVersions.set(resolvedPath, 0);
     touch(resolvedPath);
     await evictExcess();

package/src/lib/lsp/lsp.ts

@@ -86,6 +86,8 @@ const lspConfigSchema = Type.Object({
   diagnosticsDebounceMs: Type.Optional(timeoutValue),
   /** document 模式诊断等待上限（ms）。 */
   diagnosticsDocumentWaitTimeoutMs: Type.Optional(timeoutValue),
+  /** 上一份诊断为空的文档的等待上限（ms）；见 clientDefaults.diagnosticsSilentWaitTimeoutMs。 */
+  diagnosticsSilentWaitTimeoutMs: Type.Optional(timeoutValue),
   /** full 模式诊断等待上限（ms）。 */
   diagnosticsFullWaitTimeoutMs: Type.Optional(timeoutValue),
   /** 单次 pull 诊断请求超时（ms）。 */
@@ -140,6 +142,7 @@ export interface ResolvedLspConfig {
   /** 以下超时均为换算后的毫秒数（缺省见 configDefaults / clientDefaults）。 */
   diagnosticsDebounceMs: number;
   diagnosticsDocumentWaitTimeoutMs: number;
+  diagnosticsSilentWaitTimeoutMs: number;
   diagnosticsFullWaitTimeoutMs: number;
   diagnosticsRequestTimeoutMs: number;
   initializeTimeoutMs: number;
@@ -198,6 +201,8 @@ export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
     diagnosticsDebounceMs: toMs(raw.diagnosticsDebounceMs) ?? clientDefaults.diagnosticsDebounceMs,
     diagnosticsDocumentWaitTimeoutMs:
       toMs(raw.diagnosticsDocumentWaitTimeoutMs) ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs,
+    diagnosticsSilentWaitTimeoutMs:
+      toMs(raw.diagnosticsSilentWaitTimeoutMs) ?? clientDefaults.diagnosticsSilentWaitTimeoutMs,
     diagnosticsFullWaitTimeoutMs:
       toMs(raw.diagnosticsFullWaitTimeoutMs) ?? clientDefaults.diagnosticsFullWaitTimeoutMs,
     diagnosticsRequestTimeoutMs:
@@ -791,6 +796,7 @@ export function createLspService(
           diagnosticsDebounceMs: config.diagnosticsDebounceMs,
           diagnosticsDocumentWaitTimeoutMs:
             adapter.diagnosticsWaitMs ?? config.diagnosticsDocumentWaitTimeoutMs,
+          diagnosticsSilentWaitTimeoutMs: config.diagnosticsSilentWaitTimeoutMs,
           diagnosticsFullWaitTimeoutMs: config.diagnosticsFullWaitTimeoutMs,
           diagnosticsRequestTimeoutMs: config.diagnosticsRequestTimeoutMs,
           initializeTimeoutMs: adapter.startupTimeoutMs ?? config.initializeTimeoutMs,

package/src/skills/lsp-config/SKILL.md

@@ -27,12 +27,13 @@ description: Use when 编写、检查或排查 LSP 语言服务器配置 ——
 
 ```
 version / servers / enabled / disabled / watch / maxOpenDocuments /
-diagnosticsDebounceMs / diagnosticsDocumentWaitTimeoutMs /
+diagnosticsDebounceMs / diagnosticsDocumentWaitTimeoutMs / diagnosticsSilentWaitTimeoutMs /
 diagnosticsFullWaitTimeoutMs / diagnosticsRequestTimeoutMs / initializeTimeoutMs
 ```
 
 - `enabled`：只启用列出的服务器 id（缺省 = 全部启用）；`disabled`：从启用集中排除
-- 时长字段：毫秒数字，或带单位的字符串（`"300ms"` / `"5s"` / `"1m"` / `"2h"`，空单位按 ms）；默认值见 `clientDefaults`（client.ts）：debounce 150ms、document 等待 5s、full 等待 10s、pull 请求 3s、initialize 45s、`maxOpenDocuments` 32
+- 时长字段：毫秒数字，或带单位的字符串（`"300ms"` / `"5s"` / `"1m"` / `"2h"`，空单位按 ms）；默认值见 `clientDefaults`（client.ts）：debounce 150ms、document 等待 5s、安静期 1.5s、full 等待 10s、pull 请求 3s、initialize 45s、`maxOpenDocuments` 32
+- `diagnosticsSilentWaitTimeoutMs`：只用于「该文档上一份诊断为空」的情形——内容变化后最多只等这段安静期，不再等满 `diagnosticsDocumentWaitTimeoutMs`。typescript-language-server 在诊断集合空→空时不重复推送且不实现 pull 诊断，这类文档等满整个窗口也只会得到同样的「无诊断」，白等一次编辑；集合变成非空时服务器必定推送，所以调小它不会漏掉变更引入的错误，调大则更保守（默认 1.5s，约等于实测热态推送延迟的三倍）。设为不小于 `diagnosticsDocumentWaitTimeoutMs` 即等价于不做这个缩短
 - `watch`：`enabled` / `debounceMs`（缺省 300）/ `maxBatch`（缺省 500）/ `ignore`（glob，相对**每个被监听的项目根**的 POSIX 路径）。注意 `flushMs` 只在默认值里、**不可配**
 - 监听范围不是整个 cwd，而是**当前活跃服务器 client 的项目根**：root 在 cwd 内就只监听 root（被其他 root 包含的 root 不重复监听，root 是 cwd 的祖先时退化为 cwd）；没有活跃 client 就不监听。因此容器 cwd（`~/projects` 下多个仓库）里只有活跃服务器所在的项目会被 watch；`ignore` 的匹配基准也随之是各自的项目根。资源耗尽（ENOSPC）时该 root 的监听器会停止并提示一次，调大 `fs.inotify.max_user_watches` 后跑 `/lsp-reload` 重试