pi-web-ui 0.95.0 → 0.96.0

package/dist/server/lsp-tool.js

@@ -12,40 +12,86 @@
  *   4. diagnostics：获取文件或项目的实时编译与类型检查错误。
  * - 闲置自动回收：15 分钟无请求自动休眠退出，释放系统内存。
  */
-import { spawn, execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 export const LSP_TOOL_NAME = "lsp";
+export const LSP_SYMBOL_KINDS = {
+    1: "File",
+    2: "Module",
+    3: "Namespace",
+    4: "Package",
+    5: "Class",
+    6: "Method",
+    7: "Property",
+    8: "Field",
+    9: "Constructor",
+    10: "Enum",
+    11: "Interface",
+    12: "Function",
+    13: "Variable",
+    14: "Constant",
+    15: "String",
+    16: "Number",
+    17: "Boolean",
+    18: "Array",
+    19: "Object",
+    20: "Key",
+    21: "Null",
+    22: "EnumMember",
+    23: "Struct",
+    24: "Event",
+    25: "Operator",
+    26: "TypeParameter",
+};
 const LANGUAGE_SERVER_CATALOG = {
     ts: {
         languageId: "typescript",
         commands: [
+            {
+                bin: "vtsls",
+                args: ["--stdio"],
+                installHint: "npm install -g @vtsls/language-server",
+                npmPackage: "@vtsls/language-server typescript",
+            },
             {
                 bin: "typescript-language-server",
                 args: ["--stdio"],
                 installHint: "npm install -g typescript-language-server typescript",
+                npmPackage: "typescript-language-server typescript",
             },
-            { bin: "vtsls", args: ["--stdio"], installHint: "npm install -g @vtsls/language-server" },
         ],
     },
     js: {
         languageId: "javascript",
         commands: [
+            {
+                bin: "vtsls",
+                args: ["--stdio"],
+                installHint: "npm install -g @vtsls/language-server",
+                npmPackage: "@vtsls/language-server typescript",
+            },
             {
                 bin: "typescript-language-server",
                 args: ["--stdio"],
                 installHint: "npm install -g typescript-language-server typescript",
+                npmPackage: "typescript-language-server typescript",
             },
-            { bin: "vtsls", args: ["--stdio"], installHint: "npm install -g @vtsls/language-server" },
         ],
     },
     py: {
         languageId: "python",
         commands: [
-            { bin: "pyright-langserver", args: ["--stdio"], installHint: "npm install -g pyright" },
+            {
+                bin: "pyright-langserver",
+                args: ["--stdio"],
+                installHint: "npm install -g pyright",
+                npmPackage: "pyright",
+            },
             { bin: "pyright", args: ["--stdio"], installHint: "pip install pyright" },
             { bin: "pylsp", args: [], installHint: "pip install python-lsp-server" },
         ],
@@ -85,42 +131,158 @@ function getLanguageForPath(filePath) {
         return { langKey: "cpp", config: LANGUAGE_SERVER_CATALOG.cpp };
     return null;
 }
-/** 探测二进制是否可在当前系统执行（PATH 或 workspace node_modules/.bin） */
-function resolveBinary(cmd, cwd) {
+/** 二进制探测结果的内存缓存（cwd + cmd 为 key；用户态安装成功后按包失效） */
+const resolveBinaryCache = new Map();
+export function clearResolveBinaryCache() {
+    resolveBinaryCache.clear();
+}
+/** 探测二进制是否可在当前系统执行（优先项目本地、Pi 生态共享目录、用户态托管目录、系统 PATH） */
+export function resolveBinary(cmd, cwd) {
+    const cacheKey = `${cwd}::${cmd}`;
+    const cached = resolveBinaryCache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const found = resolveBinaryUncached(cmd, cwd);
+    resolveBinaryCache.set(cacheKey, found);
+    return found;
+}
+function resolveBinaryUncached(cmd, cwd) {
     const isWin = process.platform === "win32";
-    const candidates = [];
+    const exts = isWin ? [".cmd", ".exe", ".bat", ""] : [""];
     if (isAbsolute(cmd)) {
-        candidates.push(cmd);
-    }
-    else {
-        // 1. 本地 node_modules/.bin
-        const localBin = resolve(cwd, "node_modules", ".bin", cmd);
-        candidates.push(localBin);
+        if (existsSync(cmd))
+            return cmd;
         if (isWin) {
-            candidates.push(`${localBin}.cmd`);
-            candidates.push(`${localBin}.exe`);
-        }
-        // 2. 系统 PATH 候选
-        candidates.push(cmd);
-        if (isWin) {
-            candidates.push(`${cmd}.cmd`);
-            candidates.push(`${cmd}.exe`);
+            for (const ext of exts) {
+                if (ext && existsSync(cmd + ext))
+                    return cmd + ext;
+            }
         }
+        return null;
+    }
+    // 1. 本地 workspace node_modules/.bin 优先
+    const localBinDir = resolve(cwd, "node_modules", ".bin");
+    for (const ext of exts) {
+        const target = join(localBinDir, cmd + ext);
+        if (existsSync(target))
+            return target;
     }
-    for (const cand of candidates) {
-        if (isAbsolute(cand) && existsSync(cand))
-            return cand;
+    // 2. Pi 生态工具与用户态目录（pi-lens / pi-web 用户态托管，零权限直接复用）
+    const home = homedir();
+    const sharedDirs = [
+        join(home, ".pi-lens", "tools", "node_modules", ".bin"),
+        join(home, ".pi-web", "lsp-servers", "node_modules", ".bin"),
+        join(home, ".pi", "agent", "tools", "node_modules", ".bin"),
+    ];
+    for (const sharedDir of sharedDirs) {
+        for (const ext of exts) {
+            const target = join(sharedDir, cmd + ext);
+            if (existsSync(target))
+                return target;
+        }
     }
-    // 尝试 where / which 嗅探
-    try {
-        const checkCmd = isWin ? `where "${cmd}"` : `which "${cmd}"`;
-        const out = execSync(checkCmd, { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
-        if (out)
-            return out.split(/\r?\n/)[0];
+    // 3. 遍历系统 PATH 目录（纯文件系统检查，零子进程开销、杜绝 Windows cmd.exe 引号卡死）
+    const pathDirs = (process.env.PATH || "").split(delimiter);
+    for (const dir of pathDirs) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const target = join(dir, cmd + ext);
+            if (existsSync(target))
+                return target;
+        }
     }
-    catch { }
     return null;
 }
+const installTasks = new Map();
+/** 安装失败的负缓存（pkg -> 失败时间戳）：失败后 5 分钟内不再重复执行 120s 的 npm install */
+const installFailedAt = new Map();
+const INSTALL_FAIL_NEGATIVE_CACHE_MS = 5 * 60 * 1000;
+/**
+ * 在用户专属目录（~/.pi-web/lsp-servers）执行无侵入、免 sudo/root 的语言服务包按需安装。
+ * 注意：必须经用户显式授权（lsp 工具的 allowInstall 参数）后才能调用，不得静默触发。
+ */
+export async function autoInstallLanguageServer(pkg) {
+    const existing = installTasks.get(pkg);
+    if (existing)
+        return existing;
+    const failedAt = installFailedAt.get(pkg);
+    if (failedAt !== undefined && Date.now() - failedAt < INSTALL_FAIL_NEGATIVE_CACHE_MS) {
+        console.warn(`[LSP] Skip auto-install for ${pkg}: failed recently, retry later with allowInstall`);
+        return false;
+    }
+    const task = (async () => {
+        try {
+            const userLspDir = join(homedir(), ".pi-web", "lsp-servers");
+            console.warn(`[LSP] Installing language server [${pkg}] into ${userLspDir} (user-space, no sudo)…`);
+            mkdirSync(userLspDir, { recursive: true });
+            const pkgJson = join(userLspDir, "package.json");
+            if (!existsSync(pkgJson)) {
+                writeFileSync(pkgJson, JSON.stringify({ name: "pi-web-lsp-servers", private: true }) + "\n");
+            }
+            const pkgs = pkg.split(/\s+/).filter(Boolean);
+            const isWin = process.platform === "win32";
+            const npmCmd = isWin ? "npm.cmd" : "npm";
+            let stderr = "";
+            await new Promise((resolve, reject) => {
+                const proc = spawn(npmCmd, ["install", "--no-audit", "--no-fund", "--save-dev", ...pkgs], {
+                    cwd: userLspDir,
+                    stdio: ["ignore", "ignore", "pipe"],
+                    shell: isWin,
+                });
+                const timer = setTimeout(() => {
+                    if (isWin) {
+                        // shell:true 时 proc.pid 只是 cmd.exe 的 PID——proc.kill() 只杀得到
+                        // cmd.exe，npm/node 整棵子进程树会残留。taskkill /T 连树强杀。
+                        if (typeof proc.pid === "number") {
+                            const killer = spawn("taskkill", ["/PID", String(proc.pid), "/T", "/F"], { stdio: "ignore" });
+                            killer.on("error", () => { });
+                        }
+                    }
+                    else {
+                        // POSIX：npm 由非 shell 直接 spawn，kill 其主进程即可让安装流程终止
+                        //（取 SIGKILL 而非 detached 进程组方案：不改变子进程组语义，安装
+                        // 超时本身是罕见路径，残余 node 子进程随 npm 主进程退出被回收）。
+                        try {
+                            proc.kill("SIGKILL");
+                        }
+                        catch { }
+                    }
+                    reject(new Error("npm install timed out"));
+                }, 120_000);
+                proc.stderr?.on("data", (chunk) => {
+                    stderr += chunk.toString("utf8");
+                });
+                proc.on("error", (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+                proc.on("exit", (code) => {
+                    clearTimeout(timer);
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`npm install exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ""}`));
+                });
+            });
+            console.warn(`[LSP] Language server [${pkg}] installed, resolving binaries…`);
+            // 新二进制落盘，探测缓存失效
+            clearResolveBinaryCache();
+            installFailedAt.delete(pkg);
+            return true;
+        }
+        catch (err) {
+            console.warn(`[LSP] Auto-install failed for ${pkg}: ${err.message}`);
+            installFailedAt.set(pkg, Date.now());
+            return false;
+        }
+        finally {
+            installTasks.delete(pkg);
+        }
+    })();
+    installTasks.set(pkg, task);
+    return task;
+}
 // ----------------------------------------------------------------------------
 // JSON-RPC 2.0 传输层与单项目 LSP 客户端
 // ----------------------------------------------------------------------------
@@ -130,7 +292,7 @@ export class LspClient {
     binPath;
     binArgs;
     languageId;
-    onIdleEvict;
+    onEvict;
     proc = null;
     nextId = 1;
     pendingRequests = new Map();
@@ -141,28 +303,46 @@ export class LspClient {
     idleTimer = null;
     initialized = false;
     isShuttingDown = false;
-    constructor(projectCwd, langKey, binPath, binArgs, languageId, onIdleEvict) {
+    constructor(projectCwd, langKey, binPath, binArgs, languageId, 
+    /** 客户端不可用（空闲回收 / 进程退出 / spawn 失败）时从池移除的回调 */
+    onEvict) {
         this.projectCwd = projectCwd;
         this.langKey = langKey;
         this.binPath = binPath;
         this.binArgs = binArgs;
         this.languageId = languageId;
-        this.onIdleEvict = onIdleEvict;
+        this.onEvict = onEvict;
     }
     async start() {
         this.touch();
         this.proc = spawn(this.binPath, this.binArgs, {
             cwd: this.projectCwd,
             stdio: ["pipe", "pipe", "pipe"],
-            shell: process.platform === "win32" && this.binPath.endsWith(".cmd"),
+            shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(this.binPath),
         });
         this.proc.stdout?.on("data", (chunk) => this.handleData(chunk));
         this.proc.stderr?.on("data", (d) => {
             // 可选记录 debug 日志，不干扰输出
         });
+        // spawn 失败（ENOENT/EACCES 等）只触发 'error'，进程从未启动时不会触发
+        // 'exit'——不监听会让 initialize 等请求挂到超时，客户端还留在池里被误判存活。
+        this.proc.on("error", (err) => {
+            this.proc = null;
+            this.rejectAllPending(new Error(`Language server failed to start: ${err.message}`));
+            this.onEvict();
+        });
+        // stdin 写错误（对端退出后的 EPIPE 等）在 stream 上异步 emit，不监听会以
+        // uncaughtException 崩掉整个服务进程。这里统一兜底：标记死亡 + 清理挂起请求。
+        this.proc.stdin?.on("error", (err) => {
+            this.proc = null;
+            this.rejectAllPending(new Error(`Language server stdin error: ${err.message}`));
+            this.onEvict();
+        });
         this.proc.on("exit", (code) => {
             this.proc = null;
             this.rejectAllPending(new Error(`Language server exited with code ${code}`));
+            // 进程退出即从池移除，防止后续请求命中死客户端
+            this.onEvict();
         });
         try {
             // 发送 initialize 握手
@@ -207,7 +387,7 @@ export class LspClient {
         // 15 分钟无调用自动回收
         this.idleTimer = setTimeout(() => {
             this.shutdown().catch(() => { });
-            this.onIdleEvict();
+            this.onEvict();
         }, 15 * 60 * 1000);
         this.idleTimer.unref();
     }
@@ -282,7 +462,16 @@ export class LspClient {
                 rej(new Error(`LSP request ${method} timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pendingRequests.set(id, { resolve: res, reject: rej, timer });
-            this.proc.stdin.write(wire);
+            try {
+                this.proc.stdin.write(wire);
+            }
+            catch (err) {
+                // 同步写失败（stream 已销毁等）：撤销挂起请求；异步 EPIPE 由 start() 里的
+                // stdin 'error' 监听兜底，这里只需保证 promise 被 reject 而非向上抛。
+                clearTimeout(timer);
+                this.pendingRequests.delete(id);
+                rej(new Error(`Language server stdin write failed: ${err.message}`));
+            }
         });
     }
     notify(method, params) {
@@ -291,7 +480,12 @@ export class LspClient {
             return;
         const payload = JSON.stringify({ jsonrpc: "2.0", method, params });
         const wire = `Content-Length: ${Buffer.byteLength(payload, "utf8")}\r\n\r\n${payload}`;
-        this.proc.stdin.write(wire);
+        try {
+            this.proc.stdin.write(wire);
+        }
+        catch {
+            // 通知写失败只影响状态同步，不值得打断调用链；异步 EPIPE 由 stdin 'error' 监听兜底
+        }
     }
     async syncDocument(absPath) {
         const uri = pathToFileURL(absPath).toString();
@@ -374,7 +568,7 @@ class LspServerPool {
         const client = this.pool.get(poolKey);
         return Boolean(client && client.isAlive());
     }
-    async getClient(projectCwd, filePath) {
+    async getClient(projectCwd, filePath, opts) {
         if (this.shuttingDown) {
             return { error: "LSP server pool is shutting down" };
         }
@@ -385,8 +579,13 @@ class LspServerPool {
         const poolKey = `${projectCwd}::${langInfo.langKey}`;
         const client = this.pool.get(poolKey);
         if (client) {
-            client.touch();
-            return { client };
+            // 池命中必须复检存活：进程退出事件与请求之间有竞态窗口（exit 回调排队、
+            // spawn error 未触发 exit），死客户端留在池里会让所有请求挂到超时。
+            if (client.isAlive()) {
+                client.touch();
+                return { client };
+            }
+            this.pool.delete(poolKey);
         }
         const pending = this.inFlight.get(poolKey);
         if (pending) {
@@ -397,6 +596,7 @@ class LspServerPool {
             let resolvedBin = null;
             let resolvedArgs = [];
             let hint = "";
+            let autoPkg = undefined;
             for (const cmd of langInfo.config.commands) {
                 const found = resolveBinary(cmd.bin, projectCwd);
                 if (found) {
@@ -405,10 +605,29 @@ class LspServerPool {
                     break;
                 }
                 hint = cmd.installHint;
+                if (!autoPkg && cmd.npmPackage)
+                    autoPkg = cmd.npmPackage;
+            }
+            // 用户态按需安装必须经用户显式授权（allowInstall），避免在工具调用链里无提示联网 npm install
+            if (!resolvedBin && autoPkg && opts?.allowInstall === true) {
+                const ok = await autoInstallLanguageServer(autoPkg);
+                if (ok) {
+                    for (const cmd of langInfo.config.commands) {
+                        const found = resolveBinary(cmd.bin, projectCwd);
+                        if (found) {
+                            resolvedBin = found;
+                            resolvedArgs = cmd.args;
+                            break;
+                        }
+                    }
+                }
             }
             if (!resolvedBin) {
+                const installGateHint = autoPkg
+                    ? `\nOr retry this tool call with { "allowInstall": true } to install \`${autoPkg}\` into ~/.pi-web/lsp-servers (user-space, no sudo) automatically.`
+                    : "";
                 return {
-                    error: `Language server for ${langInfo.config.languageId} not found.\nPlease install it: \`${hint}\``,
+                    error: `Language server for ${langInfo.config.languageId} not found.\nPlease install it: \`${hint}\`${installGateHint}`,
                 };
             }
             const newClient = new LspClient(projectCwd, langInfo.langKey, resolvedBin, resolvedArgs, langInfo.config.languageId, () => {
@@ -416,6 +635,8 @@ class LspServerPool {
                     this.pool.delete(poolKey);
                 }
             });
+            // 启动失败时客户端尚在 start() 内部、池里没有它，onEvict 是空操作；
+            // 成功后再退出/回收才会真正从池移除。
             try {
                 await newClient.start();
                 if (this.shuttingDown) {
@@ -473,26 +694,140 @@ export async function getLiveLspDiagnostics(absPath, cwd) {
     });
     return `⚠️ Post-edit Diagnostics (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}`;
 }
+/**
+ * 递归格式化 DocumentSymbol 列表为缩进的符号大纲树（做条数上限保护）
+ */
+function formatDocumentSymbols(symbols, indent = "", lines = []) {
+    for (const sym of symbols) {
+        if (lines.length >= 300) {
+            lines.push(`${indent}• ... [Truncated: outline exceeds 300 symbols]`);
+            break;
+        }
+        const kind = LSP_SYMBOL_KINDS[sym.kind] || `Kind(${sym.kind})`;
+        const range = sym.range || sym.location?.range;
+        const startLine = range ? range.start.line + 1 : "?";
+        const endLine = range ? range.end.line + 1 : "?";
+        const lineSpan = startLine === endLine ? `line ${startLine}` : `lines ${startLine}-${endLine}`;
+        const detail = sym.detail ? ` (${sym.detail})` : "";
+        lines.push(`${indent}• [${kind}] ${sym.name}${detail} (${lineSpan})`);
+        if (Array.isArray(sym.children) && sym.children.length > 0) {
+            formatDocumentSymbols(sym.children, indent + "  ", lines);
+        }
+    }
+    return lines;
+}
+/**
+ * 递归单趟查找符号（两遍扫描：先严格精确匹配，未命中再执行大小写忽略回退，避免遮蔽后续精确符号；支持 containerName 点分路径）
+ */
+function findSymbolPass(symbols, target, mode, parentName = "") {
+    const targetLower = target.toLowerCase();
+    for (const sym of symbols) {
+        const qualifiedName = sym.containerName
+            ? `${sym.containerName}.${sym.name}`
+            : parentName
+                ? `${parentName}.${sym.name}`
+                : sym.name;
+        if (mode === "exact") {
+            if (sym.name === target || qualifiedName === target) {
+                return { symbol: sym, fullName: qualifiedName };
+            }
+        }
+        else {
+            if (sym.name.toLowerCase() === targetLower || qualifiedName.toLowerCase() === targetLower) {
+                return { symbol: sym, fullName: qualifiedName };
+            }
+        }
+        if (Array.isArray(sym.children) && sym.children.length > 0) {
+            const found = findSymbolPass(sym.children, target, mode, qualifiedName);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function findSymbol(symbols, target) {
+    return findSymbolPass(symbols, target, "exact") ?? findSymbolPass(symbols, target, "ci");
+}
+/**
+ * 收集文件内可用的顶层符号全名清单（最多收集 50 条，供找不到符号时提供备选提示）
+ */
+function collectSymbolNames(symbols, prefix = "", names = []) {
+    for (const sym of symbols) {
+        if (names.length >= 50)
+            break;
+        const current = sym.containerName
+            ? `${sym.containerName}.${sym.name}`
+            : prefix
+                ? `${prefix}.${sym.name}`
+                : sym.name;
+        const kind = LSP_SYMBOL_KINDS[sym.kind] || "Symbol";
+        names.push(`${current} [${kind}]`);
+        if (Array.isArray(sym.children) && sym.children.length > 0) {
+            collectSymbolNames(sym.children, current, names);
+        }
+    }
+    return names;
+}
+/**
+ * 当未传 path 且执行工作区级操作（如 workspaceSymbol）时，寻找工作区默认主文件以定位语言服务
+ */
+function findDefaultSourceFileForLsp(cwd) {
+    const candidates = [
+        "src/index.ts",
+        "src/main.ts",
+        "src/app.ts",
+        "index.ts",
+        "main.ts",
+        "app.ts",
+        "server.ts",
+        "main.py",
+        "app.py",
+        "main.go",
+        "src/main.rs",
+    ];
+    for (const c of candidates) {
+        if (existsSync(join(cwd, c)))
+            return c;
+    }
+    return null;
+}
 export function makeLspTool(options) {
     const cwd = options.cwd;
     return defineTool({
         name: LSP_TOOL_NAME,
         label: "LSP code intelligence",
-        description: `Query language intelligence from Language Server Protocol (LSP) across the workspace.
-Provides IDE-grade semantic analysis to prevent guessing and hallucinating symbol references.
-Supported actions:
-- \`definition\`: Jump to definition of the symbol at \`line\` & \`character\` in \`path\` (returns file, line, and code snippet).
-- \`references\`: Find all workspace references/usages of the symbol at \`line\` & \`character\` in \`path\`.
-- \`hover\`: Get type signature and documentation (Docstring/Markdown) for symbol at \`line\` & \`character\`.
-- \`diagnostics\`: Get compiler/type errors and warnings for \`path\` (or pass no line to check whole file).
-Note: Line numbers are 1-indexed.`,
+        description: `IDE-grade semantic analysis (LSP) across the workspace. Actions:
+- \`definition\`: definition of the symbol at \`line\`/\`character\` in \`path\` (file, line, snippet).
+- \`references\`: all workspace usages of that symbol.
+- \`hover\`: type signature and docs for that symbol.
+- \`diagnostics\`: compiler/type errors and warnings for \`path\` (whole file).
+- \`documentSymbol\`: hierarchical symbol outline with line spans for \`path\`.
+- \`read_symbol\`: read the body of \`symbol\` in \`path\` (e.g. "parseConfig").
+- \`workspaceSymbol\`: search symbols across the workspace by \`query\`.
+- \`cascade\`: impact check for \`path\` — report diagnostics of files referencing it.
+Lines are 1-indexed.`,
         parameters: Type.Object({
-            action: Type.Union([Type.Literal("definition"), Type.Literal("references"), Type.Literal("hover"), Type.Literal("diagnostics")], {
+            action: Type.Union([
+                Type.Literal("definition"),
+                Type.Literal("references"),
+                Type.Literal("hover"),
+                Type.Literal("diagnostics"),
+                Type.Literal("documentSymbol"),
+                Type.Literal("read_symbol"),
+                Type.Literal("workspaceSymbol"),
+                Type.Literal("cascade"),
+            ], {
                 description: "The LSP operation to perform.",
             }),
-            path: Type.String({
-                description: "Workspace-relative or absolute path to the target source file.",
-            }),
+            path: Type.Optional(Type.String({
+                description: "Workspace-relative or absolute path to the target source file (required for all actions except workspaceSymbol).",
+            })),
+            symbol: Type.Optional(Type.String({
+                description: "Symbol name to read for 'read_symbol' action (e.g. 'functionName' or 'ClassName.methodName').",
+            })),
+            query: Type.Optional(Type.String({
+                description: "Search query for 'workspaceSymbol' action.",
+            })),
             line: Type.Optional(Type.Number({
                 description: "1-indexed line number in the source file.",
             })),
@@ -502,10 +837,33 @@ Note: Line numbers are 1-indexed.`,
             timeout: Type.Optional(Type.Number({
                 description: "Timeout in seconds (defaults to 15).",
             })),
+            allowInstall: Type.Optional(Type.Boolean({
+                description: "Install the missing language server into ~/.pi-web/lsp-servers (user-space, no sudo). Default false: the tool returns an installHint instead.",
+            })),
         }),
         async execute(_callId, params, _signal, _onUpdate, _ctx) {
             const action = params.action;
-            const targetPath = params.path;
+            let targetPath = params.path;
+            if (!targetPath && action === "workspaceSymbol") {
+                targetPath = findDefaultSourceFileForLsp(cwd) ?? undefined;
+                if (!targetPath) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: Could not automatically detect a primary project source file to route language server. Please provide 'path' (pointing to any source file in the project, e.g. path='src/index.ts') to select the language server.`,
+                            },
+                        ],
+                        details: { ok: false, error: "Missing path: cannot route language server" },
+                    };
+                }
+            }
+            if (!targetPath) {
+                return {
+                    content: [{ type: "text", text: `Error: 'path' parameter is required for action '${action}'.` }],
+                    details: { ok: false, error: "Missing path parameter" },
+                };
+            }
             const absPath = isAbsolute(targetPath) ? targetPath : resolve(cwd, targetPath);
             const line = typeof params.line === "number" ? Math.max(1, params.line) : 1;
             const character = typeof params.character === "number" ? Math.max(1, params.character) : 1;
@@ -527,7 +885,29 @@ Note: Line numbers are 1-indexed.`,
                     details: { ok: false, error: "File not found" },
                 };
             }
-            const clientRes = await globalLspPool.getClient(cwd, absPath);
+            if (action === "read_symbol" && !params.symbol?.trim()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: 'symbol' parameter is required for 'read_symbol' action (e.g. symbol="parseConfig" or "ClassName.methodName").`,
+                        },
+                    ],
+                    details: { ok: false, error: "Missing symbol parameter" },
+                };
+            }
+            if (action === "workspaceSymbol" && !(params.query ?? "").trim()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: 'query' parameter cannot be empty for 'workspaceSymbol' action. Please provide a search term (e.g. query='User' or 'Router').`,
+                        },
+                    ],
+                    details: { ok: false, error: "Empty query parameter" },
+                };
+            }
+            const clientRes = await globalLspPool.getClient(cwd, absPath, { allowInstall: params.allowInstall });
             if ("error" in clientRes) {
                 return {
                     content: [{ type: "text", text: `LSP Error: ${clientRes.error}` }],
@@ -551,7 +931,10 @@ Note: Line numbers are 1-indexed.`,
                             details: { ok: true, locations: [] },
                         };
                     }
-                    const formatted = locs.map((loc) => {
+                    // 与 references(:25) 同口径：每个位置都要整读一次目标文件拼 snippet，
+                    // 无上限的 definition 列表会放大成几十次同步 IO 拖死请求。
+                    const MAX_DEFS = 25;
+                    const formatted = locs.slice(0, MAX_DEFS).map((loc) => {
                         const targetUri = loc.targetUri || loc.uri || "";
                         let defPath = targetUri;
                         try {
@@ -576,8 +959,14 @@ Note: Line numbers are 1-indexed.`,
                         }
                         return `• ${defRel}:${defLine}:${defCol}\n\`\`\`\n${snippet}\n\`\`\``;
                     });
+                    const defTail = locs.length > MAX_DEFS ? `\n\n... and ${locs.length - MAX_DEFS} more definitions` : "";
                     return {
-                        content: [{ type: "text", text: `Definitions (${locs.length}):\n\n${formatted.join("\n\n")}` }],
+                        content: [
+                            {
+                                type: "text",
+                                text: `Definitions (${locs.length}):\n\n${formatted.join("\n\n")}${defTail}`,
+                            },
+                        ],
                         details: { ok: true, locations: locs },
                     };
                 }
@@ -663,6 +1052,309 @@ Note: Line numbers are 1-indexed.`,
                         details: { ok: true, diagnostics: diags },
                     };
                 }
+                if (action === "documentSymbol") {
+                    const result = await client.request("textDocument/documentSymbol", { textDocument: { uri } }, timeoutMs);
+                    const symbols = Array.isArray(result) ? result : [];
+                    if (symbols.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No symbols found in ${targetPath}` }],
+                            details: { ok: true, symbols: [] },
+                        };
+                    }
+                    const lines = formatDocumentSymbols(symbols);
+                    // details 随会话持久且整体 ≤64KB（超限整条丢弃）：symbols 与文本大纲同口径截断
+                    const detailsSymbols = symbols.length > 300 ? symbols.slice(0, 300) : symbols;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Symbols in ${targetPath} (${symbols.length} top-level):\n${lines.join("\n")}`,
+                            },
+                        ],
+                        details: { ok: true, count: symbols.length, symbols: detailsSymbols },
+                    };
+                }
+                if (action === "read_symbol") {
+                    const targetSymbol = params.symbol?.trim();
+                    if (!targetSymbol) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Error: 'symbol' parameter is required for 'read_symbol' action (e.g. symbol="parseConfig" or "ClassName.methodName").`,
+                                },
+                            ],
+                            details: { ok: false, error: "Missing symbol parameter" },
+                        };
+                    }
+                    const result = await client.request("textDocument/documentSymbol", { textDocument: { uri } }, timeoutMs);
+                    const symbols = Array.isArray(result) ? result : [];
+                    const match = findSymbol(symbols, targetSymbol);
+                    if (!match) {
+                        const available = collectSymbolNames(symbols);
+                        const listSnippet = available.length > 0
+                            ? `\nAvailable symbols in ${targetPath}:\n${available
+                                .slice(0, 30)
+                                .map((s) => `• ${s}`)
+                                .join("\n")}${available.length > 30 ? `\n... and ${available.length - 30} more` : ""}`
+                            : "";
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Symbol '${targetSymbol}' not found in ${targetPath}.${listSnippet}`,
+                                },
+                            ],
+                            details: { ok: false, error: "Symbol not found", availableSymbols: available },
+                        };
+                    }
+                    const range = match.symbol.range || match.symbol.location?.range;
+                    if (!range) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Symbol '${targetSymbol}' found, but no range information was provided by language server.`,
+                                },
+                            ],
+                            details: { ok: false, error: "Missing range" },
+                        };
+                    }
+                    let startLine = range.start.line; // 0-indexed
+                    let endLine = range.end.line; // 0-indexed
+                    // 针对行尾排他边界（end.character === 0 且跨行时）避免多读末尾空行
+                    if (range.end.character === 0 && endLine > startLine) {
+                        endLine -= 1;
+                    }
+                    const fileLines = readFileSync(absPath, "utf8").split(/\r?\n/);
+                    const totalSymbolLines = Math.max(0, endLine - startLine + 1);
+                    const MAX_SYMBOL_READ_LINES = 400;
+                    const isTruncated = totalSymbolLines > MAX_SYMBOL_READ_LINES;
+                    const sliceEndLine = isTruncated ? startLine + MAX_SYMBOL_READ_LINES - 1 : endLine;
+                    const symbolLines = fileLines.slice(startLine, sliceEndLine + 1);
+                    let formattedSnippet = symbolLines.map((l, idx) => `${startLine + idx + 1}: ${l}`).join("\n");
+                    if (isTruncated) {
+                        formattedSnippet += `\n// ... [Truncated: symbol body has ${totalSymbolLines} lines, showing first ${MAX_SYMBOL_READ_LINES} lines. Use 'documentSymbol' to inspect nested methods/members and read them individually]`;
+                    }
+                    const kind = LSP_SYMBOL_KINDS[match.symbol.kind] || `Kind(${match.symbol.kind})`;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `// Symbol: ${match.fullName} [${kind}]\n// File:   ${rel}:${startLine + 1}-${endLine + 1}\n\`\`\`\n${formattedSnippet}\n\`\`\``,
+                            },
+                        ],
+                        details: {
+                            ok: true,
+                            symbol: match.symbol,
+                            fullName: match.fullName,
+                            startLine: startLine + 1,
+                            endLine: endLine + 1,
+                            code: symbolLines.join("\n"),
+                            totalLines: totalSymbolLines,
+                            truncated: isTruncated,
+                        },
+                    };
+                }
+                if (action === "workspaceSymbol") {
+                    const query = (params.query ?? "").trim();
+                    if (!query) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Error: 'query' parameter cannot be empty for 'workspaceSymbol' action. Please provide a search term (e.g. query='User' or 'Router').`,
+                                },
+                            ],
+                            details: { ok: false, error: "Empty query parameter" },
+                        };
+                    }
+                    const result = await client.request("workspace/symbol", { query }, timeoutMs);
+                    const locs = Array.isArray(result) ? result : [];
+                    if (locs.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No symbols found across workspace matching '${query}'` }],
+                            details: { ok: true, symbols: [] },
+                        };
+                    }
+                    const MAX_WORKSPACE_SYMBOLS = 100;
+                    const isTruncated = locs.length > MAX_WORKSPACE_SYMBOLS;
+                    const cappedLocs = isTruncated ? locs.slice(0, MAX_WORKSPACE_SYMBOLS) : locs;
+                    const formatted = locs.slice(0, 30).map((sym) => {
+                        const targetUri = sym.location?.uri || sym.uri || "";
+                        let filePath = targetUri;
+                        try {
+                            if (targetUri.startsWith("file:"))
+                                filePath = fileURLToPath(targetUri);
+                        }
+                        catch { }
+                        const fileRel = filePath.startsWith(cwd) ? filePath.slice(cwd.length).replace(/^[/\\]/, "") : filePath;
+                        const range = sym.location?.range || sym.range;
+                        const lineNum = range ? range.start.line + 1 : 1;
+                        const kind = LSP_SYMBOL_KINDS[sym.kind] || `Kind(${sym.kind})`;
+                        const container = sym.containerName ? ` in ${sym.containerName}` : "";
+                        return `• [${kind}] ${sym.name}${container} (${fileRel}:${lineNum})`;
+                    });
+                    const tail = locs.length > 30 ? `\n... and ${locs.length - 30} more symbols` : "";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Found ${locs.length} symbol${locs.length > 1 ? "s" : ""} matching '${query}' (via ${rel}):\n${formatted.join("\n")}${tail}`,
+                            },
+                        ],
+                        details: { ok: true, count: locs.length, symbols: cappedLocs, truncated: isTruncated },
+                    };
+                }
+                if (action === "cascade") {
+                    // 影响级联（Impact Cascade）：找出引用本文件（或本文件某个符号）的工作区文件，
+                    // 聚合它们的实时诊断——让"改了签名/导出，下游编译炸了"在编辑当轮就暴露，
+                    // 而不是等到构建或提交时才发现。
+                    const MAX_SEEDS = 20;
+                    const MAX_DEPENDENTS = 25;
+                    const DIAGS_BUDGET_MS = 1500;
+                    const normalizePath = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
+                    // 1. 收集种子位置：给了 line/character 就只查那个符号；否则查全部顶层符号。
+                    const seeds = [];
+                    if (typeof params.line === "number") {
+                        seeds.push({ line: line - 1, character: character - 1 });
+                    }
+                    else {
+                        const symResult = await client.request("textDocument/documentSymbol", { textDocument: { uri } }, timeoutMs);
+                        const topSymbols = Array.isArray(symResult) ? symResult : [];
+                        for (const sym of topSymbols.slice(0, MAX_SEEDS)) {
+                            const pos = sym.selectionRange?.start ?? sym.range?.start ?? sym.location?.range?.start;
+                            if (pos && typeof pos.line === "number") {
+                                seeds.push({ line: pos.line, character: pos.character ?? 0 });
+                            }
+                        }
+                    }
+                    if (seeds.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No symbols to trace in ${targetPath} — nothing to cascade.` }],
+                            details: { ok: true, impacted: [], clean: [], notReported: [], referencedFiles: [] },
+                        };
+                    }
+                    // 2. 对每个种子查 references（不含声明处），汇总工作区内的引用方文件。
+                    const selfNorm = normalizePath(absPath);
+                    const depPaths = new Set();
+                    const seedResults = await Promise.allSettled(seeds.map((pos) => client.request("textDocument/references", { textDocument: { uri }, position: pos, context: { includeDeclaration: false } }, timeoutMs)));
+                    for (const r of seedResults) {
+                        if (r.status !== "fulfilled" || !Array.isArray(r.value))
+                            continue;
+                        for (const loc of r.value) {
+                            const refUri = loc?.uri ?? "";
+                            if (!refUri.startsWith("file:"))
+                                continue;
+                            let refPath;
+                            try {
+                                refPath = fileURLToPath(refUri);
+                            }
+                            catch {
+                                continue;
+                            }
+                            if (normalizePath(refPath) === selfNorm)
+                                continue; // 排除自身
+                            const relRef = relative(cwd, refPath);
+                            if (relRef === ".." || relRef.startsWith(".." + sep) || relRef.startsWith("../") || isAbsolute(relRef)) {
+                                continue; // 只看工作区内
+                            }
+                            if (relRef.split(sep).includes("node_modules"))
+                                continue;
+                            depPaths.add(refPath);
+                        }
+                    }
+                    const dependents = [...depPaths].sort().slice(0, MAX_DEPENDENTS);
+                    if (dependents.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No referencing files found for ${targetPath} — no impact cascade needed.`,
+                                },
+                            ],
+                            details: { ok: true, impacted: [], clean: [], notReported: [], referencedFiles: [] },
+                        };
+                    }
+                    // 3. 逐个 didOpen/didChange 触发服务器分析，轮询等待 publishDiagnostics 回流。
+                    const depUris = [];
+                    for (const dep of dependents) {
+                        try {
+                            depUris.push(await client.syncDocument(dep));
+                        }
+                        catch {
+                            depUris.push("");
+                        }
+                    }
+                    const pending = new Set(depUris.filter(Boolean));
+                    const deadline = Date.now() + DIAGS_BUDGET_MS;
+                    while (pending.size > 0 && Date.now() < deadline) {
+                        await new Promise((r) => setTimeout(r, 120));
+                        const known = client.getAllDiagnostics();
+                        for (const u of [...pending]) {
+                            if (known.has(u))
+                                pending.delete(u);
+                        }
+                    }
+                    // 4. 聚合输出：有错误的排前面，其次警告，clean 与未上报的折叠列出。
+                    const impacted = [];
+                    const clean = [];
+                    const notReported = [];
+                    const knownFinal = client.getAllDiagnostics();
+                    for (let i = 0; i < dependents.length; i++) {
+                        const dep = dependents[i];
+                        const depUri = depUris[i];
+                        const depRel = relative(cwd, dep).replace(/\\/g, "/");
+                        if (!depUri) {
+                            notReported.push(depRel);
+                            continue;
+                        }
+                        const diags = client.getDiagnostics(depUri);
+                        const errors = diags.filter((d) => d.severity === 1).length;
+                        const warnings = diags.filter((d) => d.severity === 2).length;
+                        if (errors + warnings > 0) {
+                            impacted.push({ path: depRel, errors, warnings, diagnostics: diags.slice(0, 10) });
+                        }
+                        else if (diags.length === 0 && !knownFinal.has(depUri)) {
+                            notReported.push(depRel); // 预算内服务器未上报（可能仍在分析）
+                        }
+                        else {
+                            clean.push(depRel);
+                        }
+                    }
+                    impacted.sort((a, b) => b.errors - a.errors || b.warnings - a.warnings);
+                    const out = [];
+                    out.push(`Impact cascade for ${targetPath}: ${dependents.length} referencing file(s), ${impacted.length} with findings.`);
+                    for (const item of impacted) {
+                        out.push(`• ${item.path} — ${item.errors} error(s), ${item.warnings} warning(s)`);
+                        for (const d of item.diagnostics.slice(0, 5)) {
+                            const sev = d.severity === 1 ? "ERROR" : d.severity === 2 ? "WARN" : "INFO";
+                            const code = d.code ? ` [${d.code}]` : "";
+                            const msg = String(d.message).split("\n")[0];
+                            out.push(`    [${sev}] line ${d.range.start.line + 1}:${d.range.start.character + 1}${code} - ${msg}`);
+                        }
+                    }
+                    if (clean.length > 0) {
+                        const shown = clean
+                            .slice(0, 10)
+                            .map((p) => `• ${p}`)
+                            .join("\n");
+                        out.push(`Clean (${clean.length}):\n${shown}${clean.length > 10 ? `\n... and ${clean.length - 10} more` : ""}`);
+                    }
+                    if (notReported.length > 0) {
+                        out.push(`Diagnostics not reported in time (${notReported.length}, server may still be analyzing): ${notReported.slice(0, 5).join(", ")}${notReported.length > 5 ? ", ..." : ""}`);
+                    }
+                    return {
+                        content: [{ type: "text", text: out.join("\n") }],
+                        details: {
+                            ok: true,
+                            impacted,
+                            clean,
+                            notReported,
+                            referencedFiles: dependents.map((p) => relative(cwd, p).replace(/\\/g, "/")),
+                        },
+                    };
+                }
                 return {
                     content: [{ type: "text", text: `Unsupported action: ${action}` }],
                     details: { ok: false, error: "Unsupported action" },