@trim21/personal-pi-extensions 0.1.450 → 0.1.451

package/README.md

@@ -372,6 +372,13 @@ read/edit/write 工具内置 LSP 诊断（写文件后等待并报告 ERROR 级
       "settings": {}, // → didChangeConfiguration / workspace/configuration 请求
     },
   },
+  "maxOpenDocuments": 32, // 驻留文档上限（LRU 容量），缺省 32
+  "watch": {
+    "enabled": true, // 工作区文件监听，缺省 true
+    "debounceMs": "300ms", // 事件去抖，缺省 300ms；也支持 "5s" / "1m"
+    "maxBatch": 500, // 单批事件上限，缺省 500，超出截断并提示一次
+    "ignore": [], // 追加忽略 glob（相对工作区根）
+  },
 }
 ```
 
@@ -384,9 +391,13 @@ 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` 自行表达。
+没有内置默认服务器：`servers` 的 key 就是服务器 id，全部来自你的配置，未定义 `servers` 时不启动任何语言服务器。executable 的发现逻辑（如 tsserver 路径、venv 里的 python）不内置，需要时用 `bin` / `args` / `settings` 自行表达。
+
+启用控制只有顶层两处：`enabled`（白名单）与 `disabled`（排除），按服务器 id 生效。`enabled` 里的 id 必须是已配置服务器，否则视为配置错误；`disabled` 里未注册的 id 直接忽略。全局超时字段（`initializeTimeoutMs` 等）同样配在顶层。
+
+顶层 `watch` 段控制工作区文件监听（事件源是会话 cwd 的递归 fs.watch，非本 agent 写入的改动——如 `git checkout`、外部格式化——也会以 `workspace/didChangeWatchedFiles` 批量通知服务器）；内置忽略 `node_modules`、`.git`、`dist`、`build`、`.venv`、`venv`、`target`、`coverage`，`ignore` 可追加。`maxOpenDocuments` 是保持 open 的文档上限（LRU）：超过时最久未使用的文档会被 `didClose`，服务器回落到读磁盘。`watch.enabled: false` 可整体关闭监听，回到仅工具触发同步的现状。
 
-旧的 `enabled`（白名单）/ `disabled`（排除）与全局超时字段（`initializeTimeoutMs` 等）继续可用。`enabled` 里的 id 必须是已注册服务器，否则视为配置错误；`disabled` 里未注册的 id 直接忽略。
+服务器记录里不认识的键会被忽略：历史配置中残留的 `"clangd": { "enabled": false }` 已无任何效果，要禁用某个已配置的服务器请改用顶层 `disabled`。
 
 ---
 

package/package.json

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

package/src/claude-code/files.ts

@@ -349,9 +349,9 @@ export function registerFileTools(
       }
       const snapshot = { ...snapshotOf(buffer), offset, limit };
       state.reads.set(key, snapshot);
-      // LSP warm-up 是后台任务，失败不影响读取
-      void service.touchFile(filePath, ctx.cwd).catch(() => {
-        // 后台 warm-up 失败不影响读取
+      // LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
+      void service.notifyFile(filePath, ctx.cwd).catch(() => {
+        // 后台通知失败不影响读取
       });
       return {
         content: [{ type: "text", text: formatted.text }],

package/src/lib/lsp/client.ts

@@ -23,12 +23,20 @@ import type { Diagnostic as VSCodeDiagnostic } from "vscode-languageserver-types
 
 import type { LspServerHandle } from "./adapter.js";
 import { LANGUAGE_EXTENSIONS } from "./language.js";
+import type { FileChange, FileChangeType } from "./watcher.js";
 
 // LSP spec 常量
 const FILE_CHANGE_CREATED = 1;
 const FILE_CHANGE_CHANGED = 2;
+const FILE_CHANGE_DELETED = 3;
 const TEXT_DOCUMENT_SYNC_INCREMENTAL = 2;
 
+const FILE_CHANGE_TYPE: Record<FileChangeType, number> = {
+  created: FILE_CHANGE_CREATED,
+  changed: FILE_CHANGE_CHANGED,
+  deleted: FILE_CHANGE_DELETED,
+};
+
 export type Diagnostic = VSCodeDiagnostic;
 
 export class InitializeError extends Error {
@@ -69,6 +77,7 @@ interface CapabilityRegistration {
   registerOptions?: {
     identifier?: string;
     workspaceDiagnostics?: boolean;
+    watchers?: { globPattern?: string }[];
   };
 }
 
@@ -93,6 +102,8 @@ export interface CreateInput {
   diagnosticsFullWaitTimeoutMs?: number;
   diagnosticsRequestTimeoutMs?: number;
   initializeTimeoutMs?: number;
+  /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
+  maxOpenDocuments?: number;
 }
 
 export interface LspClient {
@@ -101,7 +112,11 @@ export interface LspClient {
   readonly connection: MessageConnection;
   readonly notify: {
     open(request: { path: string }): Promise<number>;
+    /** 把工作区文件事件批量通知服务器；驻留文档不在此通道（走 didOpen/didChange/退场）。 */
+    watchedFiles(changes: FileChange[]): Promise<void>;
   };
+  /** 服务器注册的 workspace/didChangeWatchedFiles watchers glob（去重）。 */
+  watchPatterns(): string[];
   readonly diagnostics: Map<string, Diagnostic[]>;
   waitForDiagnostics(request: {
     path: string;
@@ -210,6 +225,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
   const diagnosticsFullWaitTimeoutMs = input.diagnosticsFullWaitTimeoutMs ?? 10_000;
   const diagnosticsRequestTimeoutMs = input.diagnosticsRequestTimeoutMs ?? 3_000;
   const initializeTimeoutMs = input.initializeTimeoutMs ?? 45_000;
+  const maxOpenDocuments = input.maxOpenDocuments ?? 32;
 
   const connection = createMessageConnection(
     new StreamMessageReader(input.server.process.stdout),
@@ -231,6 +247,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
   const pullDiagnostics = new Map<string, Diagnostic[]>();
   const published = new Map<string, { at: number; version?: number }>();
   const diagnosticRegistrations = new Map<string, CapabilityRegistration>();
+  /** registration id → workspace/didChangeWatchedFiles watchers glob。 */
+  const watcherRegistrations = new Map<string, string[]>();
   const registrationListeners = new Set<() => void>();
   const diagnosticListeners = new Set<(input: { path: string; serverID: string }) => void>();
   /** resolvedPath → 客户端已发送的最新文档版本（didOpen=0，didChange 递增）。 */
@@ -286,9 +304,16 @@ export async function create(input: CreateInput): Promise<LspClient> {
       (params as { registrations?: CapabilityRegistration[] }).registrations ?? [];
     let changed = false;
     for (const registration of registrations) {
-      if (registration.method !== "textDocument/diagnostic") continue;
-      diagnosticRegistrations.set(registration.id, registration);
-      changed = true;
+      if (registration.method === "workspace/didChangeWatchedFiles") {
+        const watchers =
+          registration.registerOptions?.watchers
+            ?.map((watcher) => watcher.globPattern)
+            .filter((pattern): pattern is string => typeof pattern === "string") ?? [];
+        watcherRegistrations.set(registration.id, watchers);
+      } else if (registration.method === "textDocument/diagnostic") {
+        diagnosticRegistrations.set(registration.id, registration);
+        changed = true;
+      }
     }
     if (changed) emitRegistrationChange();
   });
@@ -297,9 +322,12 @@ export async function create(input: CreateInput): Promise<LspClient> {
       (params as { unregisterations?: { id: string; method: string }[] }).unregisterations ?? [];
     let changed = false;
     for (const registration of registrations) {
-      if (registration.method !== "textDocument/diagnostic") continue;
-      diagnosticRegistrations.delete(registration.id);
-      changed = true;
+      if (registration.method === "workspace/didChangeWatchedFiles") {
+        watcherRegistrations.delete(registration.id);
+      } else if (registration.method === "textDocument/diagnostic") {
+        diagnosticRegistrations.delete(registration.id);
+        changed = true;
+      }
     }
     if (changed) emitRegistrationChange();
   });
@@ -354,6 +382,39 @@ export async function create(input: CreateInput): Promise<LspClient> {
 
   const files: Record<string, { version: number; text: string }> = {};
 
+  // ── 驻留 LRU ────────────────────────────────────────────────────────────────
+
+  /** path → 最近使用时间；迭代序即使用序（头部最久）。 */
+  const lruOrder = new Map<string, number>();
+  /** 正在等待诊断的文档（didClose 淘汰时跳过，见"关闭不得早于诊断收集"）。 */
+  const waitingForDiagnostics = new Set<string>();
+
+  const touch = (path: string): void => {
+    lruOrder.delete(path);
+    lruOrder.set(path, Date.now());
+  };
+
+  /** 超过容量时淘汰最久未使用的文档（didClose 并移出驻留集合）。 */
+  async function evictExcess(): Promise<void> {
+    while (lruOrder.size > maxOpenDocuments) {
+      const oldest = lruOrder.keys().next().value;
+      if (oldest === undefined) return;
+      lruOrder.delete(oldest);
+      const document = files[oldest];
+      if (document === undefined) continue;
+      if (waitingForDiagnostics.has(oldest)) {
+        // 防御：等待中的文档挪到 MRU，等下轮再淘汰（正常不会发生，刚 touch 即 MRU）
+        touch(oldest);
+        continue;
+      }
+      await connection.sendNotification("textDocument/didClose", {
+        textDocument: { uri: pathToFileURL(oldest).href },
+      });
+      delete files[oldest];
+      documentVersions.delete(oldest);
+    }
+  }
+
   // ── 诊断拉取（pull）辅助 ────────────────────────────────────────────────────
 
   const mergeResults = (filePath: string, results: DiagnosticRequestResult[]): PullResult => {
@@ -693,6 +754,9 @@ export async function create(input: CreateInput): Promise<LspClient> {
     get serverID() {
       return input.serverID;
     },
+    watchPatterns(): string[] {
+      return [...new Set([...watcherRegistrations.values()].flat())];
+    },
     get connection() {
       return connection;
     },
@@ -713,9 +777,6 @@ export async function create(input: CreateInput): Promise<LspClient> {
           // 重算未完成时（大项目可远超窗口）聚合到过期诊断；新 push 到达即填充。
           pushDiagnostics.delete(resolvedPath);
           pullDiagnostics.delete(resolvedPath);
-          await connection.sendNotification("workspace/didChangeWatchedFiles", {
-            changes: [{ uri, type: FILE_CHANGE_CHANGED }],
-          });
 
           const next = document.version + 1;
           files[resolvedPath] = { version: next, text };
@@ -732,13 +793,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
                   ]
                 : [{ text }],
           });
+          touch(resolvedPath);
+          await evictExcess();
           return next;
         }
 
-        await connection.sendNotification("workspace/didChangeWatchedFiles", {
-          changes: [{ uri, type: FILE_CHANGE_CREATED }],
-        });
-
         pushDiagnostics.delete(resolvedPath);
         pullDiagnostics.delete(resolvedPath);
         await connection.sendNotification("textDocument/didOpen", {
@@ -746,8 +805,47 @@ export async function create(input: CreateInput): Promise<LspClient> {
         });
         files[resolvedPath] = { version: 0, text };
         documentVersions.set(resolvedPath, 0);
+        touch(resolvedPath);
+        await evictExcess();
         return 0;
       },
+      async watchedFiles(changes: FileChange[]): Promise<void> {
+        const notified: { uri: string; type: number }[] = [];
+        for (const change of changes) {
+          const resolvedPath = normalize(
+            isAbsolute(change.path) ? change.path : resolve(input.directory, change.path),
+          );
+          const document = files[resolvedPath];
+          if (document !== undefined) {
+            // 写后诊断等待中的文档不退场（didClose 可能抹掉本次写入的诊断结果）
+            if (waitingForDiagnostics.has(resolvedPath)) continue;
+            // 驻留文档被外部改动：内容一致的自身写入 echo 完全忽略；否则先 didClose
+            // 让服务器回落磁盘，再以文件事件通知——不 bump 版本，避免与写后等待竞态。
+            if (change.type === "changed") {
+              let disk: string | undefined;
+              try {
+                disk = await readFile(resolvedPath, "utf8");
+              } catch {
+                // 文件已被删除或不可读：按磁盘状态变化处理
+              }
+              if (disk === document.text) continue;
+            }
+            await connection.sendNotification("textDocument/didClose", {
+              textDocument: { uri: pathToFileURL(resolvedPath).href },
+            });
+            delete files[resolvedPath];
+            documentVersions.delete(resolvedPath);
+          }
+          notified.push({
+            uri: pathToFileURL(resolvedPath).href,
+            type: FILE_CHANGE_TYPE[change.type],
+          });
+        }
+        if (notified.length === 0) return;
+        await connection.sendNotification("workspace/didChangeWatchedFiles", {
+          changes: notified,
+        });
+      },
     },
     get diagnostics() {
       const result = new Map<string, Diagnostic[]>();
@@ -760,21 +858,26 @@ export async function create(input: CreateInput): Promise<LspClient> {
       const normalizedPath = normalize(
         isAbsolute(request.path) ? request.path : resolve(input.directory, request.path),
       );
-      if (request.mode === "document") {
-        await waitForDocumentDiagnostics({
+      waitingForDiagnostics.add(normalizedPath);
+      try {
+        if (request.mode === "document") {
+          await waitForDocumentDiagnostics({
+            path: normalizedPath,
+            version: request.version,
+            after: request.after,
+            signal: request.signal,
+          });
+          return;
+        }
+        await waitForFullDiagnostics({
           path: normalizedPath,
           version: request.version,
           after: request.after,
           signal: request.signal,
         });
-        return;
+      } finally {
+        waitingForDiagnostics.delete(normalizedPath);
       }
-      await waitForFullDiagnostics({
-        path: normalizedPath,
-        version: request.version,
-        after: request.after,
-        signal: request.signal,
-      });
     },
     async shutdown() {
       connection.end();

package/src/lib/lsp/lsp.ts

@@ -13,15 +13,16 @@
  *   的 id 直接忽略；
  * - client 按 (root, serverID) 缓存，并发 spawn 去重，启动失败记入 broken
  *   集合（服务实例生命周期内不再重试）；
- * - 工具只与 touchFile / diagnostics / lspDiagnosticsForFile 三个方法打交道；通知回调按请求传入。
+ * - 工具只与 touchFile / notifyFile / 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";
+import { extname, join, normalize, relative, sep } from "node:path";
 
 import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
@@ -29,10 +30,23 @@ 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, mergeServerRecords, serverConfigSchema } from "./server-config.js";
+import { type FileChange, watchWorkspace, type WorkspaceWatcher } from "./watcher.js";
 
 /** 超时值：number（毫秒，>=1）或字符串（"500"、"5s"、"1m"），Parse 后由 toMs 统一换算。 */
 const timeoutValue = Type.Union([Type.Number({ minimum: 1 }), Type.String()]);
 
+/** lsp.json 顶层 `watch` 段：工作区文件监听配置。 */
+const watchConfigSchema = Type.Object({
+  /** 是否启用工作区文件监听（缺省 true）。 */
+  enabled: Type.Optional(Type.Boolean()),
+  /** 事件去抖时长（ms，缺省 300），沿用 timeoutValue 字符串写法。 */
+  debounceMs: Type.Optional(timeoutValue),
+  /** 单批事件上限（缺省 500），超出截断并提示一次。 */
+  maxBatch: Type.Optional(Type.Number({ minimum: 1 })),
+  /** 追加忽略 glob（相对工作区根的 POSIX 路径）。 */
+  ignore: Type.Optional(Type.Array(Type.String())),
+});
+
 /** lsp.json 的配置项（全局与本地同构）。 */
 const lspConfigSchema = Type.Object({
   /** 配置文件版本（当前 1）；未知版本会被 typebox 严格校验拒绝并回退空配置。 */
@@ -43,6 +57,10 @@ const lspConfigSchema = Type.Object({
   enabled: Type.Optional(Type.Array(Type.String())),
   /** 从启用集中排除的服务器 id（缺省 = 无）。 */
   disabled: Type.Optional(Type.Array(Type.String())),
+  /** 工作区文件监听配置（缺省全部字段用 watcher 默认值）。 */
+  watch: Type.Optional(watchConfigSchema),
+  /** 驻留文档上限（LRU 容量，缺省 32）。 */
+  maxOpenDocuments: Type.Optional(Type.Number({ minimum: 1 })),
   /** push 诊断去抖（ms，缺省 150）。 */
   diagnosticsDebounceMs: Type.Optional(timeoutValue),
   /** document 模式诊断等待上限（ms，缺省 5_000）。 */
@@ -94,6 +112,32 @@ function timeoutOptions(
   };
 }
 
+/** 生效的工作区监听配置（应用缺省值）。 */
+export interface EffectiveWatchConfig {
+  enabled: boolean;
+  debounceMs: number;
+  flushMs: number;
+  maxBatch: number;
+  ignore: string[];
+}
+
+/** lsp.json 的 `watch` 段 + 缺省值；debounceMs 字符串时长在此换算。 */
+export function watchOptions(config: LspConfig): EffectiveWatchConfig {
+  const watch = config.watch;
+  return {
+    enabled: watch?.enabled ?? true,
+    debounceMs: toMs(watch?.debounceMs) ?? 300,
+    flushMs: 1_000,
+    maxBatch: watch?.maxBatch ?? 500,
+    ignore: watch?.ignore ?? [],
+  };
+}
+
+/** 驻留文档 LRU 容量（缺省 32）。 */
+export function maxOpenDocuments(config: LspConfig): number {
+  return config.maxOpenDocuments ?? 32;
+}
+
 /** 读取并解析单个配置文件；文件不存在或解析失败时返回空配置。 */
 async function readConfigFile(filePath: string): Promise<LspConfig> {
   try {
@@ -179,6 +223,10 @@ interface LspState {
   disabled: boolean;
   /** root+serverID → 服务器状态，用于 footer status 显示。 */
   servers: Map<string, { serverID: string; root: string; state: "running" | "broken" }>;
+  /** 当前会话工作目录（watcher 挂载点）；变化时重建监听器。 */
+  cwd: string | undefined;
+  /** client → adapter 扩展名集合，fan-out 时按扩展名过滤。 */
+  clientExtensions: Map<LspClient, readonly string[]>;
 }
 
 /** 渲染 LSP status 文本的回调（传入 undefined 表示清除）。 */
@@ -209,6 +257,8 @@ export interface LspService {
     diagnostics?: "document" | "full",
     options?: LspRequestOptions,
   ): Promise<void>;
+  /** read 用：只发文件事件通知服务器磁盘上有该文件，不驻留、不等诊断。 */
+  notifyFile(file: string, cwd: string, options?: LspRequestOptions): Promise<void>;
   diagnostics(): Promise<Record<string, Diagnostic[]>>;
   lspDiagnosticsForFile(
     file: string,
@@ -262,10 +312,94 @@ export function createLspService(
     closing: false,
     disabled: false,
     servers: new Map(),
+    cwd: undefined,
+    clientExtensions: new Map(),
   };
 
   let renderStatus: StatusRenderer | undefined;
 
+  // ── 工作区文件监听（watcher）───────────────────────────────────────────────
+
+  let watcher: WorkspaceWatcher | undefined;
+  let watcherCwd: string | undefined;
+
+  async function stopWatcher(): Promise<void> {
+    const current = watcher;
+    watcher = undefined;
+    watcherCwd = undefined;
+    if (current) {
+      try {
+        await current.stop();
+      } catch {
+        // 停止失败不影响流程
+      }
+    }
+  }
+
+  /** 事件按各 client 的 root 前缀 / 注册 pattern / 扩展名过滤后投递。 */
+  async function fanOut(changes: FileChange[]): Promise<void> {
+    const cwd = state.cwd;
+    if (!cwd) return;
+    await Promise.all(
+      state.clients.map(async (client) => {
+        const filtered = changes.filter((change) => {
+          if (!containsPath(change.path, cwd) || !containsPath(change.path, client.root)) {
+            return false;
+          }
+          const patterns = client.watchPatterns();
+          if (patterns.length > 0) {
+            const candidate = relative(client.root, change.path).split(sep).join("/");
+            if (patterns.every((pattern) => !minimatch(candidate, pattern))) return false;
+          }
+          const extensions = state.clientExtensions.get(client);
+          return (
+            extensions === undefined ||
+            extensions.length === 0 ||
+            extensions.includes(extname(change.path))
+          );
+        });
+        if (filtered.length === 0) return;
+        try {
+          await client.notify.watchedFiles(filtered);
+        } catch {
+          // 单个 client 通知失败不影响其余 client
+        }
+      }),
+    );
+  }
+
+  /** 首个 client 建立 / 会话 cwd 变化时（重）建监听器；watch.enabled: false 时不启动。 */
+  async function ensureWatcher(cwd: string, notify?: ExtensionUIContext["notify"]): Promise<void> {
+    if (state.closing || state.disabled) return;
+    const config = await loadLspConfig(cwd, globalConfigPath);
+    const watch = watchOptions(config);
+    if (!watch.enabled) return;
+    if (watcher && watcherCwd === cwd) return;
+    await stopWatcher();
+    try {
+      watcher = await watchWorkspace(cwd, (changes) => void fanOut(changes), {
+        debounceMs: watch.debounceMs,
+        flushMs: watch.flushMs,
+        maxBatch: watch.maxBatch,
+        ignore: watch.ignore,
+        onError: (message) => notify?.(message, "error"),
+        onTruncated: () =>
+          notify?.(
+            "workspace file events truncated (batch limit exceeded); run /lsp-reload <id> if diagnostics look stale",
+            "warning",
+          ),
+      });
+      watcherCwd = cwd;
+    } catch (error) {
+      notify?.(
+        `workspace watcher failed to start for ${cwd}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        "error",
+      );
+    }
+  }
+
   /** 汇总当前所有 LSP server 状态并渲染到 footer status。 */
   function updateStatusText(): void {
     if (!renderStatus) return;
@@ -301,6 +435,12 @@ export function createLspService(
     const extension = extname(file) || file;
     const result: LspClient[] = [];
 
+    // 会话 cwd 变化时重建 watcher（首个 client 建立后启动）
+    if (state.cwd !== cwd) {
+      state.cwd = cwd;
+      await stopWatcher();
+    }
+
     for (const adapter of active) {
       if (adapter.extensions.length > 0 && !adapter.extensions.includes(extension)) continue;
       const root = await adapter.findRoot(file, cwd);
@@ -343,6 +483,7 @@ export function createLspService(
             initializeTimeoutMs: adapter.startupTimeoutMs ?? timeout.initializeTimeoutMs,
             diagnosticsDocumentWaitTimeoutMs:
               adapter.diagnosticsWaitMs ?? timeout.diagnosticsDocumentWaitTimeoutMs,
+            maxOpenDocuments: maxOpenDocuments(config),
           });
           if (state.closing || state.disabled) {
             await client.shutdown();
@@ -354,8 +495,10 @@ export function createLspService(
             return duplicate;
           }
           state.clients.push(client);
+          state.clientExtensions.set(client, adapter.extensions);
           state.servers.set(key, { serverID: adapter.id, root, state: "running" });
           updateStatusText();
+          void ensureWatcher(cwd, notify);
           return client;
         } catch (error) {
           state.broken.add(key);
@@ -425,6 +568,21 @@ export function createLspService(
     return Promise.resolve(results);
   }
 
+  /**
+   * read 的 warm-up：通知服务器磁盘上有这个文件（D5），不 didOpen 驻留、不等诊断。
+   * 驻留文档若磁盘已被外部改写会顺带触发退场。
+   */
+  async function notifyFile(file: string, cwd: string, options?: LspRequestOptions): Promise<void> {
+    const clients = await getClients(file, cwd, options?.notify);
+    await Promise.all(
+      clients.map((client) =>
+        client.notify.watchedFiles([{ path: file, type: "changed", isDirectory: false }]),
+      ),
+    ).catch(() => {
+      // 文件事件通知失败不影响读取
+    });
+  }
+
   /**
    * edit/write 用：等待文档诊断并返回该文件的 ERROR / WARN 报告（text 空串表示无此类诊断）
    * 与数量。内部所有 LSP 失败都会被吞掉，不干扰写操作本身。
@@ -451,8 +609,10 @@ export function createLspService(
       // 个别进程退出失败不阻止清理流程
     });
     state.clients = [];
+    state.clientExtensions.clear();
     state.broken.clear();
     state.servers.clear();
+    await stopWatcher();
     updateStatusText();
   }
 
@@ -482,11 +642,13 @@ export function createLspService(
       // 个别进程退出失败不阻止清理流程
     });
     state.clients = state.clients.filter((client) => client.serverID !== serverID);
+    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.servers.delete(key);
     }
+    if (state.clients.length === 0) await stopWatcher();
     state.closing = false;
     state.disabled = false;
     updateStatusText();
@@ -498,6 +660,7 @@ export function createLspService(
 
   return {
     touchFile,
+    notifyFile,
     diagnostics,
     lspDiagnosticsForFile,
     shutdownAll,

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

@@ -3,9 +3,9 @@
  * languageId/超时等），替代为每个语言写一个 adapter class。
  *
  * 配置文件沿用 lsp.json（全局 ~/.pi/agent/lsp.json + 本地 <cwd>/.pi/lsp.json）：
- * 顶层 `servers` 是 id → 配置的 record，按 id 与内置默认服务器合并
- * （同名 id 整体覆盖、新增 id、enabled:false 禁用），之后仍受现有
- * enabled/disabled 白名单过滤。
+ * 顶层 `servers` 是 id → 配置的 record，全局与本地按 id 合并（同名 id 整体
+ * 覆盖、新增 id、全局其余保留），之后受顶层 enabled/disabled 列表过滤。
+ * 没有内置默认服务器：未配置 servers 时不启动任何服务器。
  *
  * executable 发现统一由用户配置：bin 支持绝对路径 / 项目工作区
  * （node_modules/.bin、.venv/bin、venv/bin）/ PATH，不再内置各语言的
@@ -23,8 +23,6 @@ import { exists, findBinaryInWorkspace, which } from "./bin.js";
 import { spawnProcess } from "./launch.js";
 
 export const serverConfigSchema = Type.Object({
-  /** false = 从启用集中移除（覆盖同名内置服务器）；缺省启用。 */
-  enabled: Type.Optional(Type.Boolean()),
   /** 文件 glob（相对项目根或调用 cwd，任一命中即可）；缺省匹配所有文件。 */
   include: Type.Optional(Type.Array(Type.String())),
   /** 项目根标记文件（从文件目录向上查找）；缺省用调用 cwd 作为根。 */

package/src/lib/lsp/watcher.ts

@@ -0,0 +1,174 @@
+/**
+ * 工作区文件监听器：单个递归 fs.watch + 去抖批量回调。
+ *
+ * - 事件源用 `node:fs/promises` 的 `watch(dir, { recursive: true, signal })`，
+ *   不引入 chokidar（与仓库"FS 一律用 node:fs/promises"约定一致）；
+ * - create / delete / rename 在底层都表现为 `rename`，内容改动为 `change`，
+ *   故 LSP 的 created / changed / deleted 类型由 `lstat` 判定；
+ * - 尾部去抖（缺省 300ms）合并短时洪峰，最长 flushMs（缺省 1s）强制清批；
+ * - 内置忽略 `node_modules` / `.git` / `dist` / `build` / `.venv` / `venv` /
+ *   `target` / `coverage`，配置可追加；
+ * - 单批超过 maxBatch（缺省 500）截断并回调 onTruncated 提示一次；
+ * - 目录事件默认丢弃；目录被删除时上报（isDirectory: true），由上层对其中
+ *   的驻留文档补 deleted 事件。监听器启动或运行期失败时调用 onError 降级，
+ *   不抛错。
+ */
+
+import { lstat, watch } from "node:fs/promises";
+import { join, normalize, relative, sep } from "node:path";
+
+import { minimatch } from "minimatch";
+
+export type FileChangeType = "created" | "changed" | "deleted";
+
+export interface FileChange {
+  /** 绝对路径（normalized）。 */
+  path: string;
+  type: FileChangeType;
+  /** 目录被删除时 true（created/changed 目录事件默认不上报）。 */
+  isDirectory: boolean;
+}
+
+export const DEFAULT_IGNORE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.venv/**",
+  "**/venv/**",
+  "**/target/**",
+  "**/coverage/**",
+];
+
+export interface WatchOptions {
+  /** 尾部去抖窗口（ms，缺省 300）。 */
+  debounceMs?: number;
+  /** 从首个事件起的最长 flush 间隔（ms，缺省 1_000）。 */
+  flushMs?: number;
+  /** 单批上限，超出截断（缺省 500）。 */
+  maxBatch?: number;
+  /** 追加忽略 glob（相对工作区根的 POSIX 路径）。 */
+  ignore?: string[];
+  /** 监听器不可用（无法启动 / 运行期失败）时的降级提示回调。 */
+  onError?: (message: string) => void;
+  /** 单批超限被截断时回调（提示一次，不逐条刷屏）。 */
+  onTruncated?: () => void;
+}
+
+export interface WorkspaceWatcher {
+  stop(): Promise<void>;
+}
+
+function isIgnored(path: string, dir: string, patterns: string[]): boolean {
+  const candidate = relative(dir, path).split(sep).join("/");
+  if (candidate.startsWith("..")) return false;
+  return patterns.some((pattern) => minimatch(candidate, pattern));
+}
+
+/**
+ * 启动对 dir 的递归监听。onBatch 收到去抖合并后的批次；stop 后不再回调。
+ * 返回的 promise 只在监听器无法建立（目录不存在等）时 reject——运行期
+ * 错误一律走 onError 降级。
+ */
+export function watchWorkspace(
+  dir: string,
+  onBatch: (changes: FileChange[]) => void,
+  options?: WatchOptions,
+): Promise<WorkspaceWatcher> {
+  const debounceMs = options?.debounceMs ?? 300;
+  const flushMs = options?.flushMs ?? 1_000;
+  const maxBatch = options?.maxBatch ?? 500;
+  const ignorePatterns = [...DEFAULT_IGNORE, ...(options?.ignore ?? [])];
+  const abort = new AbortController();
+
+  // 从 stat 成功事件学习已知目录，目录被删除时据此标记 isDirectory
+  const seenDirectories = new Set<string>();
+
+  let pending: FileChange[] = [];
+  let flushTimer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearTimers = (): void => {
+    if (flushTimer) clearTimeout(flushTimer);
+    if (maxTimer) clearTimeout(maxTimer);
+    flushTimer = undefined;
+    maxTimer = undefined;
+  };
+
+  const flush = (): void => {
+    clearTimers();
+    if (pending.length === 0) return;
+    let batch = pending;
+    pending = [];
+    if (batch.length > maxBatch) {
+      batch = batch.slice(0, maxBatch);
+      options?.onTruncated?.();
+    }
+    onBatch(batch);
+  };
+
+  const push = (change: FileChange): void => {
+    if (pending.length === 0) maxTimer = setTimeout(flush, flushMs);
+    pending.push(change);
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flush, debounceMs);
+  };
+
+  const classify = async (
+    filename: string,
+    eventType: "rename" | "change",
+  ): Promise<FileChange | undefined> => {
+    const path = normalize(join(dir, filename));
+    if (path === dir) return undefined;
+    let isDirectory = false;
+    let exists = true;
+    try {
+      const info = await lstat(path);
+      isDirectory = info.isDirectory();
+      if (isDirectory) seenDirectories.add(path);
+    } catch {
+      exists = false;
+      if (seenDirectories.delete(path)) isDirectory = true;
+    }
+    if (eventType === "change") {
+      if (!exists) return { path, type: "deleted", isDirectory };
+      if (isDirectory) return undefined;
+      return { path, type: "changed", isDirectory };
+    }
+    // rename：创建 / 删除 / 移入移出
+    if (!exists) return { path, type: "deleted", isDirectory };
+    if (isDirectory) return undefined;
+    return { path, type: "created", isDirectory };
+  };
+
+  const consumer = (async () => {
+    try {
+      const iterator = watch(dir, { recursive: true, signal: abort.signal });
+      for await (const event of iterator) {
+        if (!event.filename) continue;
+        const change = await classify(
+          event.filename,
+          event.eventType === "change" ? "change" : "rename",
+        );
+        if (!change) continue;
+        if (isIgnored(change.path, dir, ignorePatterns)) continue;
+        push(change);
+      }
+    } catch (error) {
+      if (abort.signal.aborted) return;
+      options?.onError?.(`workspace watcher failed for ${dir}: ${String(error)}`);
+    }
+  })();
+
+  // 目录不存在 / 无权限等启动期问题在这里暴露，让调用方可以降级
+  return lstat(dir).then(() => ({
+    async stop(): Promise<void> {
+      abort.abort();
+      try {
+        await consumer;
+      } catch {
+        // 监听器已因 abort 正常退出
+      }
+    },
+  }));
+}

package/src/opencode/files.ts

@@ -431,9 +431,9 @@ function registerReadTool(pi: ExtensionAPI, service: LspService): void {
 
       content = [{ type: "text", text: outputText }];
 
-      // opencode: LSP warm-up 是后台任务，失败不影响读取
-      void service.touchFile(absolutePath, ctx.cwd).catch(() => {
-        // 后台 warm-up 失败不影响读取
+      // opencode: LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
+      void service.notifyFile(absolutePath, ctx.cwd).catch(() => {
+        // 后台通知失败不影响读取
       });
 
       return {