@trim21/personal-pi-extensions 0.1.525 → 0.1.528

package/package.json

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

package/src/bwrap/core.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { constants, type Dirent, existsSync, readFileSync } from "node:fs";
 import { access as fsAccess, readdir, realpath, stat } from "node:fs/promises";
 import { delimiter, join } from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -353,6 +354,15 @@ async function realpathOrSelf(path: string): Promise<string> {
 
 export async function buildBwrapArgs(resolved: ResolvedBwrap, cwd: string): Promise<string[]> {
   const args = ["--new-session", "--die-with-parent", "--unshare-user", "--unshare-pid"];
+  // 沙箱进程以调用方（pi）的 uid/gid 运行，而不是 userns 里的 0。
+  // net-allowlist 模式下命令先经 nsenter 进入 holder 的 userns（unshare -r 把 pi 的 uid 映射成 0），
+  // bwrap 默认继承该 uid 会让沙箱内 id/stat 自称 root、与宿主视角不一致；
+  // 直接模式（无 holder）下这两个值本就等于 bwrap 的 real uid，等价于默认行为。
+  const uid = process.getuid?.();
+  const gid = process.getgid?.();
+  if (uid !== undefined && gid !== undefined) {
+    args.push("--uid", String(uid), "--gid", String(gid));
+  }
   // --*-bind-try：配置的路径不存在时忽略该项而不是让整条命令失败
   for (const path of resolved.writablePaths) {
     const absolutePath = await realpathOrSelf(resolveBwrapPath(path, cwd));

package/src/lib/lsp/adapter.ts

@@ -1,13 +1,15 @@
 /**
  * LSP 服务器插件契约：每个语言服务器一个 adapter class，向管理器提供统一接口。
  *
- * - root 由管理器按 workingDir 计算（缺省调用 cwd）；文件必须位于 root 之内
- *   且命中 include（未配置时全匹配）才会由该服务器处理；
+ * - root 由 serverRoot 按文件的 rootMarkers / workingDir 解析（缺省调用 cwd）；
+ *   文件必须位于 root 之内且命中 include（未配置时全匹配）才会由该服务器处理；
  * - spawn 返回 undefined 表示服务器不可用（二进制未安装）。
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { exists } from "./bin.js";
 
 export interface LspServerHandle {
   process: ChildProcessWithoutNullStreams;
@@ -33,8 +35,14 @@ export interface LspServerAdapter {
    * 过滤在管理器的 client 匹配阶段完成，adapter 不再持有 findRoot。
    */
   readonly include?: readonly string[];
-  /** 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即 cwd。 */
+  /** 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即 cwd。与 rootMarkers 互斥。 */
   readonly workingDir?: string;
+  /**
+   * 项目根标记文件名（精确匹配，目录名亦可）：从调用 cwd 沿文件路径向下逐级查找，
+   * 第一个含任一标记的目录即 root（cwd 自身命中即 cwd），未命中回退 cwd。
+   * 与 workingDir 互斥。
+   */
+  readonly rootMarkers?: readonly string[];
   /** per-server initialize 握手超时（ms）；缺省用全局配置 / client 默认。 */
   readonly startupTimeoutMs?: number;
   /** per-server 诊断等待时长（ms）；缺省用全局配置 / client 默认。 */
@@ -42,7 +50,43 @@ export interface LspServerAdapter {
   spawn(root: string, cwd: string): Promise<LspServerHandle | undefined>;
 }
 
-/** 计算服务器 root：workingDir 未配置时即调用 cwd，否则相对 cwd 解析（绝对路径原样）。 */
-export function serverRoot(workingDir: string | undefined, cwd: string): string {
-  return workingDir === undefined ? cwd : resolve(cwd, workingDir);
+/**
+ * cwd → target 的目录链（含两端）。target 在 cwd 之外时只返回 cwd，
+ * 保证 rootMarkers 搜索不越过会话工作目录。
+ */
+function dirChain(cwd: string, target: string): string[] {
+  const dirs = [cwd];
+  const rel = relative(cwd, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return dirs;
+  let current = cwd;
+  for (const part of rel.split(sep)) {
+    current = join(current, part);
+    dirs.push(current);
+  }
+  return dirs;
+}
+
+/**
+ * 解析文件的服务器 root：
+ * - 配置了 rootMarkers（非空）时从 cwd 沿文件路径向下找第一个含任一标记的目录
+ *   （cwd 自身命中即 cwd），路径上没有命中回退 cwd；
+ * - 否则即 workingDir（相对 cwd 解析，绝对路径原样）或 cwd。
+ *
+ * 取最外层（最靠近 cwd）的命中目录：cwd 是项目根时 root 恒为 cwd，rootMarkers
+ * 只在"cwd 是容器目录、其下有多个独立项目"时生效。反向的最近优先会让 root 比
+ * 根 tsconfig 更深，而 tsserver 的 tsconfig 搜索被 root 截断，根配置将不再加载。
+ */
+export function serverRoot(
+  adapter: Pick<LspServerAdapter, "workingDir" | "rootMarkers">,
+  file: string,
+  cwd: string,
+): string {
+  const markers = adapter.rootMarkers ?? [];
+  if (markers.length > 0) {
+    for (const dir of dirChain(cwd, dirname(file))) {
+      if (markers.some((marker) => exists(join(dir, marker)))) return dir;
+    }
+    return cwd;
+  }
+  return adapter.workingDir === undefined ? cwd : resolve(cwd, adapter.workingDir);
 }

package/src/lib/lsp/lsp.ts

@@ -169,10 +169,22 @@ function toMs(value: number | string | undefined): number | undefined {
   return Number.isFinite(ms) && ms > 0 ? ms : undefined;
 }
 
-/** 把合并后的原始配置解析为生效配置：应用 configDefaults 缺省、字符串时长换算、白名单转 Set。 */
+/**
+ * 把合并后的原始配置解析为生效配置：应用 configDefaults 缺省、字符串时长换算、
+ * 白名单转 Set；per-server 的 workingDir / rootMarkers 互斥校验在此完成
+ * （配置解析期抛错，与 enabled 白名单校验同层）。
+ */
 export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
+  const servers = raw.servers ?? {};
+  for (const [id, server] of Object.entries(servers)) {
+    if (server.workingDir !== undefined && server.rootMarkers !== undefined) {
+      throw new Error(
+        `lsp.json: server "${id}": workingDir and rootMarkers are mutually exclusive`,
+      );
+    }
+  }
   return {
-    servers: raw.servers ?? {},
+    servers,
     enabled: raw.enabled === undefined ? undefined : new Set(raw.enabled),
     disabled: raw.disabled === undefined ? undefined : new Set(raw.disabled),
     watch: {
@@ -336,7 +348,7 @@ 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[]>;
@@ -517,19 +529,136 @@ export function createLspService(
 
   // ── 工作区文件监听（watcher）───────────────────────────────────────────────
 
-  let watcher: WorkspaceWatcher | undefined;
-  let watcherCwd: string | undefined;
+  /** 监听目录 → 监听器；范围 = 活跃 client 的 root，随 client 集合增量维护。 */
+  const watchers = new Map<string, WorkspaceWatcher>();
+  /** 因资源耗尽（ENOSPC / EMFILE）停用的监听目录；/lsp-reload 后重试。 */
+  const watcherFailed = new Set<string>();
 
-  async function stopWatcher(): Promise<void> {
-    const current = watcher;
-    watcher = undefined;
-    watcherCwd = undefined;
-    if (current) {
-      try {
-        await current.stop();
-      } catch {
+  /**
+   * client root 的有效监听目录：root 在 cwd 内即 root；root 是 cwd 的祖先时
+   * 退化为 cwd（client 只服务 cwd 内的文件）；与 cwd 无交集时返回 undefined。
+   */
+  function watchDirFor(root: string, cwd: string): string | undefined {
+    if (containsPath(root, cwd)) return root;
+    if (containsPath(cwd, root)) return cwd;
+    return undefined;
+  }
+
+  /** 期望监听的最外层目录集合：被其他目录包含的去掉，已停用的排除。 */
+  function desiredWatchRoots(cwd: string): string[] {
+    const dirs = new Set<string>();
+    for (const client of state.clients) {
+      const dir = watchDirFor(client.root, cwd);
+      if (dir && !watcherFailed.has(dir)) dirs.add(dir);
+    }
+    return [...dirs]
+      .filter((dir) => [...dirs].every((other) => other === dir || !containsPath(dir, other)))
+      .toSorted();
+  }
+
+  async function stopWatchers(): Promise<void> {
+    const current = [...watchers.values()];
+    watchers.clear();
+    await Promise.all(
+      current.map((watcher) =>
+        watcher.stop().catch(() => {
+          // 停止失败不影响流程
+        }),
+      ),
+    );
+  }
+
+  /** 为单个目录建立监听器；启动失败返回 undefined（已提示）。 */
+  async function startWatcher(
+    root: string,
+    watch: EffectiveWatchConfig,
+    notify?: ExtensionUIContext["notify"],
+  ): Promise<WorkspaceWatcher | undefined> {
+    const report = notify ?? sessionNotify;
+    const onError = (message: string): void => {
+      // 资源耗尽不可恢复：停用该目录直到 /lsp-reload（对齐 VS Code 对 ENOSPC 的处理）
+      if (!/ENOSPC|EMFILE|No space left on device/i.test(message)) {
+        report?.(message, "error");
+        return;
+      }
+      watcherFailed.add(root);
+      const current = watchers.get(root);
+      watchers.delete(root);
+      void current?.stop().catch(() => {
         // 停止失败不影响流程
+      });
+      report?.(
+        `${message}; stopped watching ${root} until /lsp-reload (raise fs.inotify.max_user_watches first)`,
+        "error",
+      );
+    };
+    try {
+      const watcher = await watchWorkspace(root, (changes) => void fanOut(changes), {
+        debounceMs: watch.debounceMs,
+        flushMs: watch.flushMs,
+        maxBatch: watch.maxBatch,
+        ignore: watch.ignore,
+        onError,
+        onTruncated: () =>
+          report?.(
+            "workspace file events truncated (batch limit exceeded); run /lsp-reload <id> if diagnostics look stale",
+            "warning",
+          ),
+      });
+      // 建立过程中已报不可恢复错误：直接停掉，不进监听表
+      if (watcherFailed.has(root)) {
+        await watcher.stop().catch(() => {
+          // 停止失败不影响流程
+        });
+        return undefined;
       }
+      return watcher;
+    } catch (error) {
+      report?.(
+        `workspace watcher failed to start for ${root}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        "error",
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * 让监听范围与当前活跃 client 集合一致：只对差集 stop / start，
+   * 已有目录的监听器保持不动（避免新增 client 时打断其他目录的事件流）。
+   */
+  async function reconcileWatchers(
+    cwd: string,
+    notify?: ExtensionUIContext["notify"],
+  ): Promise<void> {
+    if (state.closing || state.disabled) return;
+    let config: ResolvedLspConfig;
+    try {
+      config = await currentConfig(cwd);
+    } catch (error) {
+      // 配置重读失败（如 reload 时盘上配置损坏）：保持现有监听范围，不使调用方失败
+      sessionNotify?.(
+        `LSP watcher: re-reading config failed, keeping current watch scope: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        "warning",
+      );
+      return;
+    }
+    const desired = config.watch.enabled ? desiredWatchRoots(cwd) : [];
+    // Map 迭代期间删除当前项是安全的
+    for (const [root, watcher] of watchers) {
+      if (desired.includes(root)) continue;
+      watchers.delete(root);
+      void watcher.stop().catch(() => {
+        // 停止失败不影响流程
+      });
+    }
+    for (const root of desired) {
+      if (watchers.has(root)) continue;
+      const watcher = await startWatcher(root, config.watch, notify);
+      if (watcher) watchers.set(root, watcher);
     }
   }
 
@@ -581,38 +710,6 @@ export function createLspService(
     );
   }
 
-  /** 首个 client 建立 / 会话 cwd 变化时（重）建监听器；watch.enabled: false 时不启动。 */
-  async function ensureWatcher(cwd: string, notify?: ExtensionUIContext["notify"]): Promise<void> {
-    if (state.closing || state.disabled) return;
-    const config = await currentConfig(cwd);
-    const watch = config.watch;
-    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;
@@ -715,7 +812,7 @@ export function createLspService(
         state.brokenFailAt.delete(key);
         state.brokenNotifiedAt.delete(key);
         updateStatusText();
-        void ensureWatcher(cwd, notify);
+        void reconcileWatchers(cwd, notify);
         return client;
       } catch (error) {
         reportStartupFailure(
@@ -748,16 +845,16 @@ export function createLspService(
     const extension = extname(file) || file;
     const result: LspClient[] = [];
 
-    // 会话 cwd 变化时重建 watcher（首个 client 建立后启动）
+    // 会话 cwd 变化时重算监听范围（root 不在新 cwd 内的 client 不再被监听）
     if (state.cwd !== cwd) {
       state.cwd = cwd;
-      await stopWatcher();
+      await reconcileWatchers(cwd);
     }
 
     for (const adapter of active) {
       if (adapterFilter && !adapterFilter(adapter)) continue;
       if (adapter.extensions.length > 0 && !adapter.extensions.includes(extension)) continue;
-      const root = serverRoot(adapter.workingDir, cwd);
+      const root = serverRoot(adapter, file, cwd);
       if (!containsPath(file, root)) continue;
       if (!matchesInclude(adapter.include ?? [], file, root, cwd)) continue;
       const key = root + adapter.id;
@@ -966,7 +1063,8 @@ export function createLspService(
     state.brokenFailAt.clear();
     state.brokenNotifiedAt.clear();
     state.servers.clear();
-    await stopWatcher();
+    await stopWatchers();
+    watcherFailed.clear();
     updateStatusText();
   }
 
@@ -987,15 +1085,19 @@ export function createLspService(
     state.disabled = false;
     state.brokenFailAt.clear();
     state.brokenNotifiedAt.clear();
+    watcherFailed.clear();
     updateStatusText();
   }
 
   /**
-   * reload 后立即重启此前运行中的服务器，不再等下一次工具调用。只重启新配置
-   * 中仍存在且启用的 server；无运行记录（如 /lsp-stop 之后）或配置重读失败时
-   * 不动，保持惰性 spawn。返回成功重启的 server id。
+   * reload 后立即重启此前运行中的 (server, root) 实例，不再等下一次工具调用。
+   * 只重启新配置中仍存在且启用的 server；无运行记录（如 /lsp-stop 之后）或
+   * 配置重读失败时不动，保持惰性 spawn。root 沿用重载前的值（reload 没有文件
+   * 上下文，标记文件的变化留给下一次触碰自然生效）。返回成功重启的 server id。
    */
-  async function respawnRunning(serverIDs: readonly string[]): Promise<string[]> {
+  async function respawnRunning(
+    running: readonly { serverID: string; root: string }[],
+  ): Promise<string[]> {
     const cwd = state.cwd;
     if (!cwd) return [];
     let config: ResolvedLspConfig;
@@ -1011,25 +1113,25 @@ export function createLspService(
       return [];
     }
     const active = filterAdapters(adapters ?? createAdapters(config.servers), config);
+    const unique = new Map(running.map((item) => [`${item.root}\0${item.serverID}`, item]));
     const restarted = await Promise.all(
-      serverIDs.map(async (serverID): Promise<string | undefined> => {
+      [...unique.values()].map(async ({ serverID, root }): Promise<string | undefined> => {
         const adapter = active.find((candidate) => candidate.id === serverID);
         if (!adapter) return;
-        const root = serverRoot(adapter.workingDir, cwd);
         const client = await startClient(adapter, root, cwd, config);
         return client ? serverID : undefined;
       }),
     );
-    return restarted.filter((id): id is string => id !== undefined);
+    return [...new Set(restarted.filter((id): id is string => id !== undefined))];
   }
 
   async function reload(serverID: string): Promise<string[]> {
-    const wasRunning = state.clients.some((client) => client.serverID === serverID);
+    const targets = state.clients.filter((client) => client.serverID === serverID);
+    const running = targets.map((client) => ({ serverID: client.serverID, root: client.root }));
     state.closing = true;
     // 配置缓存失效：立即重读盘上配置，让配置修改生效
     state.config = undefined;
     state.configCwd = undefined;
-    const targets = state.clients.filter((client) => client.serverID === serverID);
     await Promise.all(targets.map((client) => client.shutdown())).catch(() => {
       // 个别进程退出失败不阻止清理流程
     });
@@ -1041,16 +1143,21 @@ export function createLspService(
       state.brokenNotifiedAt.delete(key);
       state.servers.delete(key);
     }
-    if (state.clients.length === 0) await stopWatcher();
     state.closing = false;
     state.disabled = false;
+    // reload 是资源耗尽后的重试入口：清掉停用记录并按新配置重算监听范围
+    watcherFailed.clear();
+    if (state.cwd) await reconcileWatchers(state.cwd);
     updateStatusText();
-    if (!wasRunning) return [];
-    return respawnRunning([serverID]);
+    if (running.length === 0) return [];
+    return respawnRunning(running);
   }
 
   async function reloadAll(): Promise<string[]> {
-    const runningIDs = [...new Set(state.clients.map((client) => client.serverID))];
+    const running = state.clients.map((client) => ({
+      serverID: client.serverID,
+      root: client.root,
+    }));
     state.closing = true;
     state.config = undefined;
     state.configCwd = undefined;
@@ -1062,11 +1169,12 @@ export function createLspService(
     state.brokenFailAt.clear();
     state.brokenNotifiedAt.clear();
     state.servers.clear();
-    await stopWatcher();
     state.closing = false;
     state.disabled = false;
+    watcherFailed.clear();
+    if (state.cwd) await reconcileWatchers(state.cwd);
     updateStatusText();
-    return respawnRunning(runningIDs);
+    return respawnRunning(running);
   }
 
   function serverIDs(): string[] {

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

@@ -7,8 +7,9 @@
  * 覆盖、新增 id、全局其余保留），之后受顶层 enabled/disabled 列表过滤。
  * 没有内置默认服务器：未配置 servers 时不启动任何服务器。
  *
- * 不做向上查找项目根的猜测：root 即调用 cwd（或 per-server workingDir），
- * 文件归属由「文件位于 root 之内」+ include glob 判定。
+ * root 定位：per-server `rootMarkers` 从调用 cwd 沿文件路径向下找第一个含标记的
+ * 目录（未命中回退 cwd），或固定 `workingDir`（两者互斥，同时配置报错）；文件归属
+ * 由「文件位于 root 之内」+ include glob 判定。
  *
  * executable 发现统一由用户配置：bin 支持绝对路径 / 项目工作区
  * （node_modules/.bin、.venv/bin、venv/bin）/ PATH，不再内置各语言的
@@ -32,9 +33,16 @@ export const serverConfigSchema = Type.Object({
   include: Type.Optional(Type.Array(Type.String())),
   /** 服务器类型：language（真语言服务器，缺省）或 linter（只实现 LSP 协议的 lint）。 */
   kind: Type.Optional(Type.Union([Type.Literal("language"), Type.Literal("linter")])),
+  /**
+   * 项目根标记文件名（精确匹配，目录名亦可）：从调用 cwd 沿文件路径向下逐级查找，
+   * 第一个含任一标记的目录即 root（cwd 自身命中即 cwd），未命中回退 cwd；
+   * 与 workingDir 互斥。
+   */
+  rootMarkers: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
   /**
    * 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即 cwd。
    * 文件必须位于该目录内才会由本服务器处理；spawn 工作目录与 rootUri 均用它。
+   * 与 rootMarkers 互斥。
    */
   workingDir: Type.Optional(Type.String()),
   /** 可执行文件：绝对路径、相对调用 cwd 的路径，或名字（项目工作区优先，PATH 兜底）。 */
@@ -202,6 +210,7 @@ export class ConfigAdapter implements LspServerAdapter {
   readonly extensions: readonly string[] = [];
   readonly include: readonly string[];
   readonly workingDir: string | undefined;
+  readonly rootMarkers: readonly string[];
   readonly startupTimeoutMs: number | undefined;
   readonly diagnosticsWaitMs: number | undefined;
   readonly config: ServerConfig;
@@ -212,6 +221,7 @@ export class ConfigAdapter implements LspServerAdapter {
     this.kind = config.kind ?? "language";
     this.include = config.include ?? [];
     this.workingDir = config.workingDir;
+    this.rootMarkers = config.rootMarkers ?? [];
     this.startupTimeoutMs = config.startupTimeoutMs;
     this.diagnosticsWaitMs = config.diagnosticsWaitMs;
   }

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

@@ -1,6 +1,6 @@
 ---
 name: lsp-config
-description: Use when 编写、检查或排查 LSP 语言服务器配置 —— 项目本地 .pi/lsp.json 或全局 ~/.pi/agent/lsp.json：配置 typescript-language-server / pyright / ruff / gopls / clangd 等服务器的 bin、include、workingDir、initializationOptions、tsserver.path、watch 与诊断超时；或排查服务器起不来（binary not found / provides no tsserver.js）、typescript alias 依赖下 tsserver 找不到、诊断一直为空等问题。
+description: Use when 编写、检查或排查 LSP 语言服务器配置 —— 项目本地 .pi/lsp.json 或全局 ~/.pi/agent/lsp.json：配置 typescript-language-server / pyright / ruff / gopls / clangd 等服务器的 bin、include、rootMarkers、workingDir、initializationOptions、tsserver.path、watch 与诊断超时；或排查服务器起不来（binary not found / provides no tsserver.js）、typescript alias 依赖下 tsserver 找不到、诊断一直为空、monorepo 子项目 root 不对等问题。
 ---
 
 # 配置 LSP 服务器（.pi/lsp.json）
@@ -14,14 +14,14 @@ description: Use when 编写、检查或排查 LSP 语言服务器配置 ——
 
 合并是**纯函数**（`mergeConfig(global, local)`），规则：
 
-| 段                   | 合并方式                                                                                                                                                                                                                          |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 顶层其余字段         | 本地覆盖全局（浅合并）                                                                                                                                                                                                            |
-| `servers`            | 按服务器 id **整条覆盖**：本地写某个 id 会替换全局同 id 的整条记录，**不是字段级合并**。只改一个字段（如补 `initializationOptions`）也必须把 `include`/`workingDir`/`bin`/`args`/`languageIdByExtension` 全部带上，否则丢全局字段 |
-| `watch`              | 字段级合并：全局为基底、本地逐字段覆盖；`ignore` 两侧**并集去重**（全局在前），本地写 watch 段不会清掉全局 ignore                                                                                                                 |
-| 某段全局本地都未出现 | 保持缺失（调用方用 `...(watch && { watch })` 省略键，不要输出空对象）                                                                                                                                                             |
+| 段                   | 合并方式                                                                                                                                                                                                                                        |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 顶层其余字段         | 本地覆盖全局（浅合并）                                                                                                                                                                                                                          |
+| `servers`            | 按服务器 id **整条覆盖**：本地写某个 id 会替换全局同 id 的整条记录，**不是字段级合并**。只改一个字段（如补 `initializationOptions`）也必须把 `include`/`rootMarkers`/`workingDir`/`bin`/`args`/`languageIdByExtension` 全部带上，否则丢全局字段 |
+| `watch`              | 字段级合并：全局为基底、本地逐字段覆盖；`ignore` 两侧**并集去重**（全局在前），本地写 watch 段不会清掉全局 ignore                                                                                                                               |
+| 某段全局本地都未出现 | 保持缺失（调用方用 `...(watch && { watch })` 省略键，不要输出空对象）                                                                                                                                                                           |
 
-配置经 typebox 校验：字段类型不符、非法时长格式等在读取时**直接抛错**；schema 外的未知字段（含已删除的遗留字段如 `rootMarkers`）**不拒绝**，以 warning notify 逐个上报。`version` 当前为 1。
+配置经 typebox 校验：字段类型不符、非法时长格式、per-server `workingDir` 与 `rootMarkers` 同现等在读取时**直接抛错**；schema 外的未知字段（含历史遗留字段如 `cwd`）**不拒绝**，以 warning notify 逐个上报。`version` 当前为 1。
 
 ## 顶层字段速查
 
@@ -33,22 +33,123 @@ 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` 只在默认值里、**不可配**
+- `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` 重试
 
 ## servers.<id> 字段
 
-| 字段                                     | 说明                                                                                                                                                   |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `include`                                | 文件 glob（相对项目根或调用 cwd，任一命中即可）；缺省匹配所有文件                                                                                      |
-| `kind`                                   | `language`（缺省）或 `linter`。rename / inspect 等符号级功能**只面向 `language`**；linter 只参与诊断                                                   |
-| `workingDir`                             | 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即调用 cwd。文件必须位于该目录内才会由本服务器处理；spawn 工作目录与 rootUri 均用它  |
-| `bin`                                    | 可执行文件：绝对路径、相对调用 cwd 的路径、或仅名字（项目工作区优先，PATH 兜底）                                                                       |
-| `args`                                   | 启动参数数组                                                                                                                                           |
-| `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`                                           |
+| 字段                                     | 说明                                                                                                                                                                                                                                  |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `include`                                | 文件 glob（相对项目根或调用 cwd，任一命中即可）；缺省匹配所有文件                                                                                                                                                                     |
+| `kind`                                   | `language`（缺省）或 `linter`。rename / inspect 等符号级功能**只面向 `language`**；linter 只参与诊断                                                                                                                                  |
+| `rootMarkers`                            | 项目根标记文件名数组（精确匹配，目录名亦可，如 `pyproject.toml` / `go.mod` / `.git`）：从调用 cwd 沿文件路径向下查找，第一个含标记的目录即 LSP root（cwd 自身命中即 cwd），未命中回退 cwd。**与 `workingDir` 互斥**（同现报配置错误） |
+| `workingDir`                             | 服务器工作目录（即 LSP root）：绝对路径或相对调用 cwd 的路径；缺省即调用 cwd。文件必须位于该目录内才会由本服务器处理；spawn 工作目录与 rootUri 均用它。**与 `rootMarkers` 互斥**                                                      |
+| `bin`                                    | 可执行文件：绝对路径、相对调用 cwd 的路径、或仅名字（项目工作区优先，PATH 兜底）                                                                                                                                                      |
+| `args`                                   | 启动参数数组                                                                                                                                                                                                                          |
+| `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`                                                                                                                          |
+
+## 子目录项目：rootMarkers
+
+cwd 本身不是项目根、其下并列多个独立项目时（如 `~/projects/a`、`~/projects/b`），用 `rootMarkers` 让服务器按各自项目根启动，不必为每个项目写一条 server 配置：
+
+```json
+{
+  "servers": {
+    "pyright": {
+      "include": ["**/*.py", "**/*.pyi"],
+      "rootMarkers": ["pyproject.toml", "setup.py", "pyrightconfig.json"],
+      "bin": "pyright-langserver",
+      "args": ["--stdio"],
+      "languageIdByExtension": { ".py": "python", ".pyi": "python" }
+    }
+  }
+}
+```
+
+- 解析规则：从调用 cwd 沿文件路径向下找**第一个（最外层）**含任一标记的目录；cwd 是 `~/projects` 时，`~/projects/a/src/x.py` + `~/projects/a/pyproject.toml` → root 是 `~/projects/a`。cwd 自身含标记（仓库根有 `pyproject.toml`）时 root 恒为 cwd，`rootMarkers` 不起作用。
+- 路径上没有命中时回退调用 cwd；搜索**不越过 cwd**（只看 cwd 及其后代）。
+- 取最外层而不是离文件最近：tsserver 的 tsconfig 搜索从文件向上但**被 LSP root 截断**，root 比根 tsconfig 更深会让根配置完全加载不到；取最外层则更深的 tsconfig 仍由服务器自己向上找到。因此**不支持按子包定位**（每个 package 独立 root）——需要时用 `workingDir` 单条配置。
+- 标记是**精确文件名**（目录名也可，如 `.git`），不支持 glob（C# `*.csproj` 这类暂不可用）。
+- 同一服务器可为不同 root 各启动一个进程：`bin` 解析、`env` 的 `{root}`、项目工作区查找（`node_modules/.bin`、`.venv/bin`）都按各自 root 生效；footer status 与启动失败记录也按 root 分别显示。`/lsp-reload <id>` 会重启该服务器的所有 root 实例。
+- 与 `workingDir` 互斥：需要固定单一 root 时用 `workingDir`，需要按子项目自动定位时用 `rootMarkers`，不要同时写。
+
+## Example
+
+`~/.pi/agent/lsp.json` 可直接作为从零搭建的参考：七种服务器全部显式声明（无内置默认服务器），pyright / typescript 用 `rootMarkers` 支持子目录项目，actions 用 `env.sh` 启动时现取 token。
+
+```json
+{
+  "initializeTimeoutMs": "1m",
+  "diagnosticsDocumentWaitTimeoutMs": "5s",
+  "watch": {
+    "ignore": ["**/.pdm-build"]
+  },
+  "servers": {
+    "rust-analyzer": {
+      "include": ["**/*.rs"],
+      "bin": "rust-analyzer",
+      "args": [],
+      "languageIdByExtension": { ".rs": "rust" }
+    },
+    "go": {
+      "include": ["**/*.go", "**/go.mod", "**/go.work"],
+      "bin": "gopls",
+      "args": ["serve"],
+      "languageIdByExtension": { ".go": "go" }
+    },
+    "pyright": {
+      "include": ["**/*.py", "**/*.pyi"],
+      "rootMarkers": ["pyproject.toml", "pyrightconfig.json"],
+      "bin": "pyright-langserver",
+      "args": ["--stdio"],
+      "languageIdByExtension": { ".py": "python", ".pyi": "python" }
+    },
+    "ruff": {
+      "include": ["**/*.pyi?"],
+      "bin": "ruff",
+      "args": ["server"],
+      "languageIdByExtension": { ".py": "python", ".pyi": "python" }
+    },
+    "typescript": {
+      "include": ["**/*.{ts,tsx,js,jsx,mjs,cjs,mts,cts}"],
+      "rootMarkers": ["package.json", "tsconfig.json"],
+      "bin": "typescript-language-server",
+      "args": ["--stdio"],
+      "languageIdByExtension": {
+        ".ts": "typescript",
+        ".tsx": "typescriptreact",
+        ".js": "javascript",
+        ".jsx": "javascriptreact",
+        ".mjs": "javascript",
+        ".cjs": "javascript",
+        ".mts": "typescript",
+        ".cts": "typescript"
+      }
+    },
+    "yaml": {
+      "include": ["**/*.{yml,yaml}"],
+      "bin": "yaml-language-server",
+      "args": ["--stdio"],
+      "languageIdByExtension": { ".yml": "yaml", ".yaml": "yaml" }
+    },
+    "actions": {
+      "include": ["**/.github/workflows/*.ya?ml"],
+      "bin": "actions-languageserver",
+      "args": ["--stdio"],
+      "env": {
+        "GITHUB_TOKEN": { "sh": ["gh", "auth", "token"] }
+      },
+      "initializationOptions": {
+        "sessionToken": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
 
 ## typescript-language-server：TS 从哪来（易踩坑）