@trim21/personal-pi-extensions 0.0.316 → 0.0.318

package/README.md

@@ -348,7 +348,7 @@ pi -e ./src/talk/index.ts
 
 read/edit/write 工具内置 LSP 诊断（写文件后等待并报告 ERROR 级诊断）。LSP protocol 是统一的，因此服务器不需要为每个语言写 adapter：用一份 JSON 配置声明如何启动即可。
 
-配置文件（项目优先于全局，逐字段覆盖）：
+配置文件（项目优先于全局）：顶层字段（`enabled`/`disabled`、超时等）本地覆盖全局；`servers` 按服务器 id 合并——同名 id 本地整体覆盖、新增 id，全局其余服务器保留。
 
 - `~/.pi/agent/lsp.json`（全局）
 - `.pi/lsp.json`（项目）
@@ -382,7 +382,7 @@ read/edit/write 工具内置 LSP 诊断（写文件后等待并报告 ERROR 级
 - `startupTimeoutMs` / `diagnosticsWaitMs`：per-server 超时，覆盖全局配置与默认值
 - `initializationOptions` 与 `settings` 按 LSP 语义分离：前者进 initialize 请求，后者进 didChangeConfiguration / workspace/configuration 请求
 
-内置默认服务器（typescript / pyright / ruff / clangd）始终存在；`servers` 以 key 为服务器 id 与默认合并——同 key 覆盖、新 key 新增、`"enabled": false` 移除（如 `"clangd": { "enabled": false }`）。executable 的发现逻辑（如 tsserver 路径、venv 里的 python）不内置，需要时用 `bin` / `args` / `settings` 自行表达。
+内置默认服务器（typescript / pyright / ruff / clangd）始终存在；`servers` 以 key 为服务器 id 与默认合并——同 key 整体覆盖（整个配置替换默认）、新 key 新增、`"enabled": false` 移除（如 `"clangd": { "enabled": false }`）。executable 的发现逻辑（如 tsserver 路径、venv 里的 python）不内置，需要时用 `bin` / `args` / `settings` 自行表达。
 
 旧的 `enabled`（白名单）/ `disabled`（排除）与全局超时字段（`initializeTimeoutMs` 等）继续可用。
 

package/package.json

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

package/src/claude-code/files.ts

@@ -14,7 +14,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { createLspService, initLsp, type LspService } from "../lib/lsp/lsp.js";
+import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   type ClaudeCodeState,
@@ -390,7 +390,9 @@ export function registerFileTools(
           state.reads.set(key, snapshot);
           const diff = generateDiffString("", newString);
           throwIfAborted(signal);
-          const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+          const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+            notify: (message, level) => ctx.ui.notify(message, level),
+          });
           return [
             `The file ${filePath} has been updated successfully.`,
             {
@@ -469,7 +471,9 @@ export function registerFileTools(
           ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
           : `The file ${filePath} has been updated successfully.`;
         throwIfAborted(signal);
-        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+          notify: (message, level) => ctx.ui.notify(message, level),
+        });
         return [
           text,
           {
@@ -547,7 +551,9 @@ export function registerFileTools(
             ? `File created successfully at: ${filePath}`
             : `The file ${filePath} has been updated successfully.`;
         throwIfAborted(signal);
-        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+        const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+          notify: (message, level) => ctx.ui.notify(message, level),
+        });
         return [
           text,
           {
@@ -598,8 +604,7 @@ function restoreFileReads(
  * 与主进程 index.ts 聚合加载时的行为一致。
  */
 export default function claudeCodeFileTools(pi: ExtensionAPI): void {
-  const service = createLspService();
-  initLsp(pi, service);
+  const service = registerLsp(pi);
   const state = createClaudeCodeState();
 
   // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
@@ -607,7 +612,6 @@ export default function claudeCodeFileTools(pi: ExtensionAPI): void {
   // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
   // 防呆语义不因重建而弱化。
   pi.on("session_start", (_event, ctx) => {
-    service.setUi(ctx.ui);
     restoreFileReads(state, ctx.sessionManager);
   });
 
@@ -615,7 +619,6 @@ export default function claudeCodeFileTools(pi: ExtensionAPI): void {
   // session_start，扩展实例也不重建。这里同样重放当前分支，丢弃被抛弃分支
   // 的记账，避免 state 与当前分支脱节。
   pi.on("session_tree", (_event, ctx) => {
-    service.setUi(ctx.ui);
     restoreFileReads(state, ctx.sessionManager);
   });
 

package/src/lib/lsp/lsp.ts

@@ -1,17 +1,20 @@
 /**
  * LSP 管理器：所有语言服务器连接的注册表与统一入口。
  *
- * - state（client 缓存、broken 集合、spawning 去重）是 createLspService 的
+ * - state（client 缓存、broken 集合、spawning 去重）是 service 工厂的
  *   闭包变量，不做成模块级全局；
  * - 配置来源：全局 `~/.pi/agent/lsp.json` + 本地 `<cwd>/.pi/lsp.json`
- *   （本地逐字段覆盖全局）：`servers` 数组配置驱动地定义语言服务器
- *   （按 id 与内置默认服务器合并），`enabled`/`disabled` 白名单与各超时
- *   参数继续生效；配置在每个工具的调用 cwd 下惰性读取；
+ *   （本地覆盖全局）：`servers` 按 id 合并（同名 id 整体覆盖、新增 id，全局
+ *   其余服务器保留），`enabled`/`disabled` 白名单与各超时参数继续生效；
+ *   配置在每个工具的调用 cwd 下惰性读取；enabled/disabled 引用不存在的
+ *   服务器 id 是配置错误：全局配置在扩展加载（createLspService）时抛错，
+ *   本地配置在 session 开始预加载时通知，工具调用时校验抛错兜底；
  * - client 按 (root, serverID) 缓存，并发 spawn 去重，启动失败记入 broken
  *   集合（服务实例生命周期内不再重试）；
- * - 工具只与 touchFile / diagnostics / lspDiagnosticsForFile 三个方法打交道。
+ * - 工具只与 touchFile / diagnostics / lspDiagnosticsForFile 三个方法打交道；通知回调按请求传入。
  */
 
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { extname, join, normalize, sep } from "node:path";
@@ -23,7 +26,13 @@ import { Value } from "typebox/value";
 import { type LspServerAdapter } from "./adapter.js";
 import { create, type CreateInput, type Diagnostic, type Info as LspClient } from "./client.js";
 import { report } from "./diagnostic.js";
-import { createAdapters, serverConfigSchema } from "./server-config.js";
+import {
+  createAdapters,
+  defaultServers,
+  mergeServerConfigs,
+  mergeServerRecords,
+  serverConfigSchema,
+} from "./server-config.js";
 
 /** 超时值：number（毫秒，>=1）或字符串（"500"、"5s"、"1m"），Parse 后由 toMs 统一换算。 */
 const timeoutValue = Type.Union([Type.Number({ minimum: 1 }), Type.String()]);
@@ -99,9 +108,42 @@ async function readConfigFile(filePath: string): Promise<LspConfig> {
   }
 }
 
+/** 同步版 readConfigFile（扩展加载时校验全局配置用）。 */
+function readConfigFileSync(filePath: string): LspConfig {
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    return Value.Parse(lspConfigSchema, JSON.parse(raw) as unknown);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * enabled/disabled 引用的 id 必须存在于实际生效的服务器集合（注入的 adapters
+ * 或默认 + 配置 servers），否则抛配置错误（避免静默失效）。
+ */
+function validateConfig(config: LspConfig, adapters?: LspServerAdapter[]): void {
+  const available = new Set(
+    adapters
+      ? adapters.map((adapter) => adapter.id)
+      : Object.keys(mergeServerConfigs(defaultServers, config.servers)),
+  );
+  const unknown = [...(config.enabled ?? []), ...(config.disabled ?? [])].filter(
+    (id) => !available.has(id),
+  );
+  if (unknown.length > 0) {
+    const list = [...available].toSorted().join(", ") || "none";
+    throw new Error(
+      `lsp.json: unknown server id in enabled/disabled: ${unknown.join(", ")} (available: ${list})`,
+    );
+  }
+}
+
 /**
  * 合并后的生效配置：全局 `~/.pi/agent/lsp.json` 为基底，本地
- * `<cwd>/.pi/lsp.json` 逐字段覆盖。
+ * `<cwd>/.pi/lsp.json` 覆盖——顶层标量字段（enabled/disabled、超时等）本地
+ * 直接替换；`servers` 按 id 合并（同名 id 整体覆盖、新增 id，全局其余服务器
+ * 保留）。
  */
 export async function loadLspConfig(
   cwd: string,
@@ -111,14 +153,23 @@ export async function loadLspConfig(
     readConfigFile(globalConfigPath),
     readConfigFile(join(cwd, ".pi", "lsp.json")),
   ]);
-  return { ...globalConfig, ...localConfig };
+  const servers = mergeServerRecords(globalConfig.servers, localConfig.servers);
+  return {
+    ...globalConfig,
+    ...localConfig,
+    ...(servers && { servers }),
+  };
 }
 
-/** 按配置过滤 adapter 列表。 */
+/**
+ * 按配置过滤 adapter 列表。enabled/disabled 引用了实际生效集合中不存在的
+ * 服务器 id 时抛错（配置错误，避免静默失效）。
+ */
 export function filterAdapters(
   adapters: LspServerAdapter[],
   config: LspConfig,
 ): LspServerAdapter[] {
+  validateConfig(config, adapters);
   return adapters.filter((adapter) => {
     if (config.enabled && !config.enabled.includes(adapter.id)) return false;
     if (config.disabled?.includes(adapter.id)) return false;
@@ -130,15 +181,23 @@ interface LspState {
   clients: LspClient[];
   broken: Set<string>;
   spawning: Map<string, Promise<LspClient | undefined>>;
+  closing: boolean;
+}
+
+export interface LspRequestOptions {
+  notify?: ExtensionUIContext["notify"];
 }
 
 export interface LspService {
-  touchFile(file: string, cwd: string, diagnostics?: "document" | "full"): Promise<void>;
+  touchFile(
+    file: string,
+    cwd: string,
+    diagnostics?: "document" | "full",
+    options?: LspRequestOptions,
+  ): Promise<void>;
   diagnostics(): Promise<Record<string, Diagnostic[]>>;
-  lspDiagnosticsForFile(file: string, cwd: string): Promise<string>;
+  lspDiagnosticsForFile(file: string, cwd: string, options?: LspRequestOptions): Promise<string>;
   shutdownAll(): Promise<void>;
-  /** 绑定当前会话的 UI 上下文，LSP 服务器启动失败时用它发错误通知（传 undefined 解绑）。 */
-  setUi(ui?: Pick<ExtensionUIContext, "notify">): void;
 }
 
 /** 文件必须在工作目录内才启用 LSP（对齐 opencode 的 containsPath）。 */
@@ -158,14 +217,24 @@ export function createLspService(
   adapters?: LspServerAdapter[],
   globalConfigPath?: string,
 ): LspService {
+  // 扩展加载时校验全局配置（本地配置在 session_start 预加载时校验）
+  validateConfig(
+    readConfigFileSync(globalConfigPath ?? join(homedir(), ".pi", "agent", "lsp.json")),
+    adapters,
+  );
   const state: LspState = {
     clients: [],
     broken: new Set(),
     spawning: new Map(),
+    closing: false,
   };
-  let ui: Pick<ExtensionUIContext, "notify"> | undefined;
 
-  async function getClients(file: string, cwd: string): Promise<LspClient[]> {
+  async function getClients(
+    file: string,
+    cwd: string,
+    notify?: ExtensionUIContext["notify"],
+  ): Promise<LspClient[]> {
+    if (state.closing) return [];
     if (!containsPath(file, cwd)) return [];
     const config = await loadLspConfig(cwd, globalConfigPath);
     const timeout = timeoutOptions(config);
@@ -198,7 +267,7 @@ export function createLspService(
           const handle = await adapter.spawn(root, cwd);
           if (!handle) {
             state.broken.add(key);
-            ui?.notify(
+            notify?.(
               `LSP server "${adapter.id}" is not available for ${root} (binary not found)`,
               "error",
             );
@@ -214,6 +283,10 @@ export function createLspService(
             diagnosticsDocumentWaitTimeoutMs:
               adapter.diagnosticsWaitMs ?? timeout.diagnosticsDocumentWaitTimeoutMs,
           });
+          if (state.closing) {
+            await client.shutdown();
+            return;
+          }
           const duplicate = state.clients.find((c) => c.root === root && c.serverID === adapter.id);
           if (duplicate) {
             await client.shutdown();
@@ -223,7 +296,7 @@ export function createLspService(
           return client;
         } catch (error) {
           state.broken.add(key);
-          ui?.notify(
+          notify?.(
             `LSP server "${adapter.id}" failed to start for ${root}: ${
               error instanceof Error ? error.message : String(error)
             }`,
@@ -252,8 +325,9 @@ export function createLspService(
     file: string,
     cwd: string,
     diagnostics?: "document" | "full",
+    options?: LspRequestOptions,
   ): Promise<void> {
-    const clients = await getClients(file, cwd);
+    const clients = await getClients(file, cwd, options?.notify);
     await Promise.all(
       clients.map(async (client) => {
         const after = Date.now();
@@ -281,8 +355,12 @@ export function createLspService(
    * edit/write 用：等待文档诊断并返回该文件的 ERROR 报告（空串表示无错误）。
    * 内部所有 LSP 失败都会被吞掉，不干扰写操作本身。
    */
-  async function lspDiagnosticsForFile(file: string, cwd: string): Promise<string> {
-    await touchFile(file, cwd, "document");
+  async function lspDiagnosticsForFile(
+    file: string,
+    cwd: string,
+    options?: LspRequestOptions,
+  ): Promise<string> {
+    await touchFile(file, cwd, "document", options);
     const all = await diagnostics();
     const normalized = normalize(file);
     return report(normalized, all[normalized] ?? []);
@@ -290,6 +368,8 @@ export function createLspService(
 
   /** 终止全部服务器进程（session_shutdown 时调用）。 */
   async function shutdownAll(): Promise<void> {
+    if (state.closing) return;
+    state.closing = true;
     await Promise.all(state.clients.map((client) => client.shutdown())).catch(() => {
       // 个别进程退出失败不阻止清理流程
     });
@@ -297,21 +377,25 @@ export function createLspService(
     state.broken.clear();
   }
 
-  return {
-    touchFile,
-    diagnostics,
-    lspDiagnosticsForFile,
-    shutdownAll,
-    setUi(nextUi) {
-      ui = nextUi;
-    },
-  };
+  return { touchFile, diagnostics, lspDiagnosticsForFile, shutdownAll };
+}
+
+export interface LspServiceOptions {
+  adapters?: LspServerAdapter[];
+  globalConfigPath?: string;
 }
 
-/** 注册进程级生命周期：session_shutdown 时清理全部服务器进程。 */
-export function initLsp(pi: ExtensionAPI, service: LspService): void {
-  // 测试里的 fake pi 没有事件订阅；生产环境 pi.on 必然存在
-  pi.on?.("session_shutdown", () => {
-    void service.shutdownAll();
+/** 创建 LSP service 并注册 pi 的进程级清理生命周期。 */
+export function registerLsp(pi: ExtensionAPI, options?: LspServiceOptions): LspService {
+  const service = createLspService(options?.adapters, options?.globalConfigPath);
+  pi.on?.("session_shutdown", () => service.shutdownAll());
+  // session 开始是最早能拿到本地配置 cwd 的时机：预加载并校验，配置错误立即通知
+  pi.on?.("session_start", (_event, ctx) => {
+    void loadLspConfig(ctx.cwd, options?.globalConfigPath)
+      .then((config) => validateConfig(config, options?.adapters))
+      .catch((error: unknown) => {
+        if (error instanceof Error) ctx.ui.notify?.(error.message, "error");
+      });
   });
+  return service;
 }

package/src/lib/lsp/server-config.ts

@@ -4,8 +4,8 @@
  *
  * 配置文件沿用 lsp.json（全局 ~/.pi/agent/lsp.json + 本地 <cwd>/.pi/lsp.json）：
  * 顶层 `servers` 是 id → 配置的 record，按 id 与内置默认服务器合并
- * （覆盖同名、新增 id、enabled:false 禁用），之后仍受现有 enabled/disabled
- * 白名单过滤。
+ * （同名 id 整体覆盖、新增 id、enabled:false 禁用），之后仍受现有
+ * enabled/disabled 白名单过滤。
  *
  * executable 发现统一由用户配置：bin 支持绝对路径 / 项目工作区
  * （node_modules/.bin、.venv/bin、venv/bin）/ PATH，不再内置各语言的
@@ -111,7 +111,19 @@ export const defaultServers: Record<string, ServerConfig> = {
   },
 };
 
-/** 用户 servers（id → 配置）与默认配置合并：覆盖同名、新增 id、enabled:false 移除。 */
+/** 按 id 合并 servers record：同名 id 整体覆盖（不做逐字段 merge），其余保留；返回 undefined 表示没有任何 servers 定义。 */
+export function mergeServerRecords(
+  ...records: (Readonly<Record<string, ServerConfig>> | undefined)[]
+): Record<string, ServerConfig> | undefined {
+  const merged: Record<string, ServerConfig> = {};
+  for (const record of records) {
+    if (!record) continue;
+    Object.assign(merged, record);
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/** 用户 servers（id → 配置）与默认配置合并：同名 id 整体覆盖、新增 id、enabled:false 移除。 */
 export function mergeServerConfigs(
   defaults: Readonly<Record<string, ServerConfig>>,
   user: Readonly<Record<string, ServerConfig>> | undefined,

package/src/opencode/files.ts

@@ -2,7 +2,7 @@
  * Opencode File Tools —— read / edit / write 统一构建点。
  *
  * 三个工具在同一个 registerFileTools(pi, service) 里注册，共享同一个 LSP
- * service 实例（createLspService 的闭包变量），与 claude-code/files.ts 共享
+ * service 实例（registerLsp 创建的闭包变量），与 claude-code/files.ts 共享
  * read-snapshot state 的方式一致；不再用模块级全局缓存。
  *
  * 各工具行为对齐 opencode commit 999be62662（v1.2.25-1672-g999be62662,
@@ -30,7 +30,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { createLspService, initLsp, type LspService } from "../lib/lsp/lsp.js";
+import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   detectLineEnding,
@@ -695,7 +695,6 @@ export function registerFileTools(pi: ExtensionAPI, service: LspService): void {
 
 /** 独立入口：创建 LSP service（闭包共享给三个工具）并注册。 */
 export default function opencodeFileTools(pi: ExtensionAPI): void {
-  const service = createLspService();
-  initLsp(pi, service);
+  const service = registerLsp(pi);
   registerFileTools(pi, service);
 }