@trim21/personal-pi-extensions 0.1.503 → 0.1.507

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.503",
+  "version": "0.1.507",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -43,6 +43,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.13.3",
     "@types/turndown": "^5.0.6",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^4.1.10",
     "citty": "^0.2.2",
     "esbuild": "^0.28.2",
@@ -60,7 +61,7 @@
     "shlex": "^3.0.0",
     "tsx": "^4.23.12",
     "typebox": "1.3.1",
-    "typescript": "^6.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10"
   },

package/src/aft/zoom.md

@@ -7,5 +7,3 @@
 - `contextLines`：符号前后附加的上下文行数，默认 3。
 - `callgraph: true`：附带同文件内 calls-out / called-by 调用关系标注，帮助理解符号如何被使用、依赖谁。
 - 适合先 aft_outline 拿到符号名与行号，再 zoom 具体实现；不要用它读整个文件（用 read）。
-
-只支持本地文件路径，不支持 URL。

package/src/lib/lsp/lsp.ts

@@ -13,8 +13,8 @@
  *   是配置错误：全局配置在扩展加载（createLspService）时抛错，本地配置在
  *   session 开始预加载时通知，工具调用时校验抛错兜底。disabled 中未注册
  *   的 id 直接忽略；
- * - client 按 (root, serverID) 缓存，并发 spawn 去重，启动失败记入 broken
- *   集合（服务实例生命周期内不再重试）；
+ * - client 按 (root, serverID) 缓存，并发 spawn 去重，启动失败记入
+ *   broken（冷却期内跳过，冷却过后下次触碰自动重试）并主动 notify；
  * - 工具只与 touchFile / notifyFile / diagnostics / lspDiagnosticsForFile 四个方法打交道；通知回调按请求传入。
  */
 
@@ -109,6 +109,11 @@ export const configDefaults = {
   maxOpenDocuments: clientDefaults.maxOpenDocuments,
 } as const;
 
+/** 服务器启动失败后自动重试的冷却（ms）；冷却内跳过，之后下次触碰自动重试。 */
+const RETRY_COOLDOWN_MS = 60_000;
+/** 同一服务器启动失败错误通知的最小间隔（ms），冷却重试反复失败时不刷屏。 */
+const NOTIFY_INTERVAL_MS = 5 * 60_000;
+
 /** 生效的工作区监听配置（缺省值已应用）。 */
 export interface EffectiveWatchConfig {
   enabled: boolean;
@@ -292,7 +297,10 @@ export function filterAdapters(
 
 interface LspState {
   clients: LspClient[];
-  broken: Set<string>;
+  /** root+serverID → 最近一次启动失败时间；冷却期过后允许自动重试。 */
+  brokenFailAt: Map<string, number>;
+  /** root+serverID → 最近一次启动失败错误通知时间；节流避免反复刷屏。 */
+  brokenNotifiedAt: Map<string, number>;
   spawning: Map<string, Promise<LspClient | undefined>>;
   closing: boolean;
   /** /lsp-stop 置 true：所有工具调用不再 spawn 服务器，直到 start/reload。 */
@@ -380,10 +388,10 @@ export interface LspService {
   shutdownAll(): Promise<void>;
   /** 停止全部服务器并禁用 LSP：之后工具调用不再 spawn，直到 start/reload。 */
   stop(): Promise<void>;
-  /** 解除禁用并清空 broken 缓存；服务器在下次工具调用时惰性启动。 */
+  /** 解除禁用；服务器在下次工具调用时惰性启动（启动失败会按冷却自动重试）。 */
   start(): void;
   /**
-   * 重启指定服务器：关闭其全部 client、清除对应 broken 记录并解除禁用；
+   * 重启指定服务器：关闭其全部 client、清除对应失败记录并解除禁用；
    * 其余服务器不受影响。配置在下次工具调用时重新读取。
    */
   reload(serverID: string): Promise<void>;
@@ -408,10 +416,26 @@ function containsPath(file: string, cwd: string): boolean {
  * 内置默认服务器合并构建。globalConfigPath 供测试注入固定的全局配置
  * 路径，避免被本机 ~/.pi/agent/lsp.json 影响。
  */
+export interface LspServiceStartupOptions {
+  /**
+   * 服务器启动失败后到允许自动重试的冷却时长（ms）。冷却期内该服务器被
+   * 跳过，冷却过后下次触碰匹配文件时自动重试，无需 /lsp-reload。
+   */
+  retryCooldownMs?: number;
+  /** 同一服务器的启动失败错误通知最小间隔（ms），防止反复重试刷屏。 */
+  notifyIntervalMs?: number;
+  /** 会话级通知：启动失败时主动上报，不依赖触发请求恰好携带 notify。 */
+  notify?: ExtensionUIContext["notify"];
+}
+
 export function createLspService(
   adapters?: LspServerAdapter[],
   globalConfigPath?: string,
+  startupOptions?: LspServiceStartupOptions,
 ): LspService {
+  const retryCooldownMs = startupOptions?.retryCooldownMs ?? RETRY_COOLDOWN_MS;
+  const notifyIntervalMs = startupOptions?.notifyIntervalMs ?? NOTIFY_INTERVAL_MS;
+  const sessionNotify = startupOptions?.notify;
   // 扩展加载时校验全局配置（本地配置在 session_start 预加载时校验）
   validateConfig(
     resolveConfig(
@@ -421,7 +445,8 @@ export function createLspService(
   );
   const state: LspState = {
     clients: [],
-    broken: new Set(),
+    brokenFailAt: new Map(),
+    brokenNotifiedAt: new Map(),
     spawning: new Map(),
     closing: false,
     disabled: false,
@@ -558,6 +583,33 @@ export function createLspService(
     notify?: ExtensionUIContext["notify"],
     adapterFilter?: (adapter: LspServerAdapter) => boolean,
   ): Promise<LspClient[]> {
+    /**
+     * 记录一次启动失败：进入 broken（冷却期内跳过）、渲染 status，并按节流
+     * 间隔主动 notify。错误上报优先走会话级 sessionNotify——不依赖触发请求
+     * 恰好携带 notify（否则 Read warm-up 等静默通道会把失败吞掉）；未注入
+     * 会话通知时退回请求级 notify 兜底。
+     */
+    function reportStartupFailure(
+      key: string,
+      serverID: string,
+      root: string,
+      cause: string,
+    ): void {
+      const now = Date.now();
+      state.brokenFailAt.set(key, now);
+      state.servers.set(key, { serverID, root, state: "broken" });
+      updateStatusText();
+      const reporter = sessionNotify ?? notify;
+      const lastNotified = state.brokenNotifiedAt.get(key);
+      if (reporter && (lastNotified === undefined || now - lastNotified >= notifyIntervalMs)) {
+        state.brokenNotifiedAt.set(key, now);
+        reporter(
+          `LSP server "${serverID}" failed to start for ${root}: ${cause}. ` +
+            `Fix the issue or run /lsp-reload ${serverID} to retry now.`,
+          "error",
+        );
+      }
+    }
     if (state.closing || state.disabled) return [];
     if (!containsPath(file, cwd)) return [];
     const config = await loadLspConfig(cwd, globalConfigPath);
@@ -584,7 +636,12 @@ export function createLspService(
       const root = await adapter.findRoot(file, cwd);
       if (!root) continue;
       const key = root + adapter.id;
-      if (state.broken.has(key)) continue;
+      const failedAt = state.brokenFailAt.get(key);
+      if (failedAt !== undefined) {
+        if (Date.now() - failedAt < retryCooldownMs) continue;
+        // 冷却已过：允许重试；重试成功后下面会清除 broken 记录
+        state.brokenFailAt.delete(key);
+      }
 
       const existing = state.clients.find((c) => c.root === root && c.serverID === adapter.id);
       if (existing) {
@@ -603,13 +660,7 @@ export function createLspService(
         try {
           const handle = await adapter.spawn(root, cwd);
           if (!handle) {
-            state.broken.add(key);
-            state.servers.set(key, { serverID: adapter.id, root, state: "broken" });
-            updateStatusText();
-            notify?.(
-              `LSP server "${adapter.id}" is not available for ${root} (binary not found)`,
-              "error",
-            );
+            reportStartupFailure(key, adapter.id, root, "binary not found");
             return;
           }
           const client = await create({
@@ -635,18 +686,18 @@ export function createLspService(
           state.clients.push(client);
           state.clientExtensions.set(client, adapter.extensions);
           state.servers.set(key, { serverID: adapter.id, root, state: "running" });
+          // 启动成功：清除失败记录，之后若再次失败会立即重新上报
+          state.brokenFailAt.delete(key);
+          state.brokenNotifiedAt.delete(key);
           updateStatusText();
           void ensureWatcher(cwd, notify);
           return client;
         } catch (error) {
-          state.broken.add(key);
-          state.servers.set(key, { serverID: adapter.id, root, state: "broken" });
-          updateStatusText();
-          notify?.(
-            `LSP server "${adapter.id}" failed to start for ${root}: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-            "error",
+          reportStartupFailure(
+            key,
+            adapter.id,
+            root,
+            error instanceof Error ? error.message : String(error),
           );
           return;
         }
@@ -845,7 +896,8 @@ export function createLspService(
     });
     state.clients = [];
     state.clientExtensions.clear();
-    state.broken.clear();
+    state.brokenFailAt.clear();
+    state.brokenNotifiedAt.clear();
     state.servers.clear();
     await stopWatcher();
     updateStatusText();
@@ -866,7 +918,8 @@ export function createLspService(
   function start(): void {
     state.closing = false;
     state.disabled = false;
-    state.broken.clear();
+    state.brokenFailAt.clear();
+    state.brokenNotifiedAt.clear();
     updateStatusText();
   }
 
@@ -880,7 +933,8 @@ export function createLspService(
     for (const client of targets) state.clientExtensions.delete(client);
     for (const [key, server] of state.servers) {
       if (server.serverID !== serverID) continue;
-      state.broken.delete(key);
+      state.brokenFailAt.delete(key);
+      state.brokenNotifiedAt.delete(key);
       state.servers.delete(key);
     }
     if (state.clients.length === 0) await stopWatcher();
@@ -985,7 +1039,10 @@ export function createLspManager(
       const config = await loadLspConfig(ctx.cwd, options?.globalConfigPath);
       validateConfig(config, options?.adapters);
       if (enabledServerCount(config, options?.adapters) === 0) return;
-      const next = createLspService(options?.adapters, options?.globalConfigPath);
+      const next = createLspService(options?.adapters, options?.globalConfigPath, {
+        // 会话级通知：任何通道触发的启动失败都主动上报（不只依赖请求方 notify）
+        notify: (message, level) => ctx.ui.notify(message, level),
+      });
       // footer status 显示当前所有 LSP server 状态（无 UI 时不显示）
       next.attachStatus((text) =>
         ctx.ui.setStatus("lsp", text ? ctx.ui.theme.fg("accent", text) : undefined),

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

@@ -0,0 +1,111 @@
+---
+name: lsp-config
+description: Use when 编写、检查或排查 LSP 语言服务器配置 —— 项目本地 .pi/lsp.json 或全局 ~/.pi/agent/lsp.json：配置 typescript-language-server / pyright / ruff / gopls / clangd 等服务器的 bin、include、rootMarkers、initializationOptions、tsserver.path、watch 与诊断超时；或排查服务器起不来（binary not found / provides no tsserver.js）、typescript alias 依赖下 tsserver 找不到、诊断一直为空等问题。
+---
+
+# 配置 LSP 服务器（.pi/lsp.json）
+
+本扩展的 LSP 层由配置驱动：**没有内置默认服务器**，一切服务器都在 lsp.json 里定义。配置解析在 `src/lib/lsp/lsp.ts`（`lspConfigSchema` / `watchConfigSchema` / 合并与校验）与 `src/lib/lsp/server-config.ts`（`serverConfigSchema`），schema 即权威文档；改代码先看这两处。
+
+## 两个配置文件与合并语义
+
+- 全局：`~/.pi/agent/lsp.json`（所有项目的基底）
+- 本地：`<项目根>/.pi/lsp.json`（本地覆盖；常被 gitignore，只在本机生效）
+
+合并是**纯函数**（`mergeConfig(global, local)`），规则：
+
+| 段                   | 合并方式                                                                                                                                                                                                                                 |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 顶层其余字段         | 本地覆盖全局（浅合并）                                                                                                                                                                                                                   |
+| `servers`            | 按服务器 id **整条覆盖**：本地写某个 id 会替换全局同 id 的整条记录，**不是字段级合并**。只改一个字段（如补 `initializationOptions`）也必须把 `include`/`rootMarkers`/`bin`/`args`/`cwd`/`languageIdByExtension` 全部带上，否则丢全局字段 |
+| `watch`              | 字段级合并：全局为基底、本地逐字段覆盖；`ignore` 两侧**并集去重**（全局在前），本地写 watch 段不会清掉全局 ignore                                                                                                                        |
+| 某段全局本地都未出现 | 保持缺失（调用方用 `...(watch && { watch })` 省略键，不要输出空对象）                                                                                                                                                                    |
+
+配置经 typebox **严格校验**（`Type.Object` 默认拒绝多余字段）：未知的 `version`、多余键、非法时长格式都会在读取时抛错。`version` 当前为 1。
+
+## 顶层字段速查
+
+```
+version / servers / enabled / disabled / watch / maxOpenDocuments /
+diagnosticsDebounceMs / diagnosticsDocumentWaitTimeoutMs /
+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
+- `watch`：`enabled` / `debounceMs`（缺省 300）/ `maxBatch`（缺省 500）/ `ignore`（glob，相对工作区根的 POSIX 路径）。注意 `flushMs` 只在默认值里、**不可配**
+
+## servers.<id> 字段
+
+| 字段                                     | 说明                                                                                                                                                   |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `include`                                | 文件 glob（相对项目根或调用 cwd，任一命中即可）；缺省匹配所有文件                                                                                      |
+| `kind`                                   | `language`（缺省）或 `linter`。rename / inspect 等符号级功能**只面向 `language`**；linter 只参与诊断                                                   |
+| `rootMarkers`                            | 项目根标记文件名（从文件目录向上查找）；缺省把调用 cwd 当根                                                                                            |
+| `bin`                                    | 可执行文件：绝对路径、相对调用 cwd 的路径、或仅名字（项目工作区优先，PATH 兜底）                                                                       |
+| `args`                                   | 启动参数数组                                                                                                                                           |
+| `cwd`                                    | 启动工作目录，支持 `{root}` / `{cwd}` 模板；缺省 `{root}`                                                                                              |
+| `env`                                    | 追加的环境变量：string 值支持 `{root}`/`{cwd}` 与 `${VAR}` 插值；`{ "sh": ["cmd","arg"] }` 启动时执行命令取 stdout（非零退出/空输出 → 启动失败并报错） |
+| `languageIdByExtension`                  | 扩展名（含点）→ languageId；缺省回退内置映射（见 `src/lib/lsp/language.ts`，覆盖主流语言）                                                             |
+| `startupTimeoutMs` / `diagnosticsWaitMs` | 覆盖该服务器的初始化握手 / 写文件后诊断等待（缺省用全局配置与 client 默认）                                                                            |
+| `initializationOptions`                  | 透传给 initialize 请求；字符串值支持 `${VAR}` / `${VAR:-default}`（读 process env，**不支持 `{root}`/`{cwd}` 模板**）                                  |
+| `settings`                               | `workspace/didChangeConfiguration` 与 `workspace/configuration` 请求的负载；缺省回退 `initializationOptions`                                           |
+
+## typescript-language-server：TS 从哪来（易踩坑）
+
+typescript-language-server **不内置 TypeScript**（零依赖）。启动时按下面顺序找一个可用的 tsserver，**全找不到就在 initialize 阶段报错退出**：
+
+1. `initializationOptions.tsserver.path`（UserSetting，优先级最高）
+2. workspace 探测：`<项目根>/node_modules/typescript/lib/tsserver.js`
+3. 自身 `require.resolve('typescript')`（即它安装位置能解析到的 typescript）
+
+`tsserver.path` 必须指向 **`typescript/lib/tsserver.js` 或 `typescript/lib/` 目录的绝对路径**（或 PATH 可执行名）；因为初始化字符串不支持 `{root}` 模板，无法用相对 workspace 的表达式。
+
+**alias 依赖坑**：当项目把 typescript 写成 `npm:@typescript/typescript6`（alias stub）时，`node_modules/typescript/lib/` 下只有转发 stub（`typescript.js`/`tsserverlibrary.js`/`tsc.js`），**没有 `tsserver.js`** → workspace 探测失效；实体 tsserver 在 pnpm 虚拟 store：`node_modules/.pnpm/typescript@<真实版本>/node_modules/typescript/lib/tsserver.js`（目录名无 peer 后缀、相对稳定；**升级 typescript 版本后要同步更新路径**）。依赖为标准 `typescript` 包时 `node_modules/typescript` 直接是完整包，workspace 探测即命中、无需配 path。
+
+配 `initializationOptions.tsserver.path` 时，因为 servers 按 id 整条覆盖，本地 `.pi/lsp.json` 要写完整条目，示例：
+
+```json
+{
+  "servers": {
+    "typescript": {
+      "include": ["**/*.{ts,tsx,js,jsx,mjs,cjs,mts,cts}"],
+      "rootMarkers": ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"],
+      "bin": "typescript-language-server",
+      "args": ["--stdio"],
+      "cwd": "{root}",
+      "languageIdByExtension": {
+        ".ts": "typescript",
+        ".tsx": "typescriptreact",
+        ".js": "javascript",
+        ".jsx": "javascriptreact"
+      },
+      "initializationOptions": {
+        "tsserver": {
+          "path": "/path/to/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/tsserver.js"
+        }
+      }
+    }
+  }
+}
+```
+
+## 服务器启动失败的行为（改了配置后怎么验证）
+
+- 启动失败（binary 缺失 / initialize 拒绝）会**主动 notify 报错**（server id、root、原因、提示 `/lsp-reload <id>`），不需要等请求方触发
+- 失败进入 60s 冷却：冷却内该服务器被跳过，**冷却过后下次触碰自动重试**——修复配置后不用重启 agent，等冷却过即可，或立即 `/lsp-reload <id>` 重启指定服务器（同时清除失败记录）
+- 命令：`/lsp-reload <id>`（重启单个）、`/lsp-stop`（停全部并禁用）、`/lsp-start`（重新启用）
+
+## 生效时机
+
+- `servers` 配置在每次工具调用时惰性重读：**还没启动**的服务器，改 `bin`/`initializationOptions` 等下次触碰即生效；**已启动**的进程要用 `/lsp-reload <id>`（或重启 agent）才换新配置
+- `session_start` 时若 enabled 服务器数为 0 则不创建 service，之后从无到有地启用需要重启 agent
+
+## 常见排查
+
+| 现象                                                                          | 原因与修法                                                                                                                               |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| notify `failed to start …: binary not found`                                  | `bin` 不在 PATH（测试场景二进制缺失时整组跳过）                                                                                          |
+| `… provides no tsserver.js. No other valid TypeScript installation was found` | workspace 的 `node_modules/typescript` 是 alias stub：配 `initializationOptions.tsserver.path` 指 `.pnpm` 实体，或换标准 typescript 依赖 |
+| 诊断一直为空且无任何报错                                                      | 服务器没匹配到文件（`include`/扩展名）、在 broken 冷却中、或文件在调用 cwd 之外（LSP 只在工作目录内启用）                                |
+| 读取配置直接抛错                                                              | typebox 严格校验拒绝：多余字段 / 未知 `version` / 非法时长格式                                                                           |