pi-web-ui 0.94.0 → 0.95.0

package/dist/server/lsp-tool.js

@@ -0,0 +1,679 @@
+/**
+ * lsp-tool.ts — 导出给 AI Agent 的原生 LSP 语言服务器工具（Native Opt-in LSP Tool）。
+ *
+ * 核心设计：
+ * - 零重型外部依赖：基于 Node.js 标准流与原生 JSON-RPC 2.0 实现轻量级 LSP 客户端。
+ * - 多会话共享池（Project-level Pool）：同项目多会话与并发子代理复用同一个后台语言服务器实例，
+ *   避免多子代理重复拉起语言服务器导致内存爆炸（参考 omp 的 lspmux 理念）。
+ * - 支持 4 大核心语义动作：
+ *   1. definition：跳转到符号定义位置（支持展示定义代码片段）；
+ *   2. references：列出工作区内所有引用/调用处；
+ *   3. hover：获取类型签名与文档说明（Docstring/Markdown）；
+ *   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 { pathToFileURL, fileURLToPath } from "node:url";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+export const LSP_TOOL_NAME = "lsp";
+const LANGUAGE_SERVER_CATALOG = {
+    ts: {
+        languageId: "typescript",
+        commands: [
+            {
+                bin: "typescript-language-server",
+                args: ["--stdio"],
+                installHint: "npm install -g typescript-language-server typescript",
+            },
+            { bin: "vtsls", args: ["--stdio"], installHint: "npm install -g @vtsls/language-server" },
+        ],
+    },
+    js: {
+        languageId: "javascript",
+        commands: [
+            {
+                bin: "typescript-language-server",
+                args: ["--stdio"],
+                installHint: "npm install -g 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", args: ["--stdio"], installHint: "pip install pyright" },
+            { bin: "pylsp", args: [], installHint: "pip install python-lsp-server" },
+        ],
+    },
+    rs: {
+        languageId: "rust",
+        commands: [{ bin: "rust-analyzer", args: [], installHint: "rustup component add rust-analyzer" }],
+    },
+    go: {
+        languageId: "go",
+        commands: [{ bin: "gopls", args: ["serve"], installHint: "go install golang.org/x/tools/gopls@latest" }],
+    },
+    c: {
+        languageId: "c",
+        commands: [{ bin: "clangd", args: [], installHint: "Install LLVM/clangd from package manager" }],
+    },
+    cpp: {
+        languageId: "cpp",
+        commands: [{ bin: "clangd", args: [], installHint: "Install LLVM/clangd from package manager" }],
+    },
+};
+function getLanguageForPath(filePath) {
+    const ext = extname(filePath).toLowerCase().replace(/^\./, "");
+    if (["ts", "tsx", "mts", "cts"].includes(ext))
+        return { langKey: "ts", config: LANGUAGE_SERVER_CATALOG.ts };
+    if (["js", "jsx", "mjs", "cjs"].includes(ext))
+        return { langKey: "js", config: LANGUAGE_SERVER_CATALOG.js };
+    if (["py", "pyi"].includes(ext))
+        return { langKey: "py", config: LANGUAGE_SERVER_CATALOG.py };
+    if (ext === "rs")
+        return { langKey: "rs", config: LANGUAGE_SERVER_CATALOG.rs };
+    if (ext === "go")
+        return { langKey: "go", config: LANGUAGE_SERVER_CATALOG.go };
+    if (["c", "h"].includes(ext))
+        return { langKey: "c", config: LANGUAGE_SERVER_CATALOG.c };
+    if (["cpp", "cc", "cxx", "hpp", "hxx"].includes(ext))
+        return { langKey: "cpp", config: LANGUAGE_SERVER_CATALOG.cpp };
+    return null;
+}
+/** 探测二进制是否可在当前系统执行（PATH 或 workspace node_modules/.bin） */
+function resolveBinary(cmd, cwd) {
+    const isWin = process.platform === "win32";
+    const candidates = [];
+    if (isAbsolute(cmd)) {
+        candidates.push(cmd);
+    }
+    else {
+        // 1. 本地 node_modules/.bin
+        const localBin = resolve(cwd, "node_modules", ".bin", cmd);
+        candidates.push(localBin);
+        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 cand of candidates) {
+        if (isAbsolute(cand) && existsSync(cand))
+            return cand;
+    }
+    // 尝试 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];
+    }
+    catch { }
+    return null;
+}
+// ----------------------------------------------------------------------------
+// JSON-RPC 2.0 传输层与单项目 LSP 客户端
+// ----------------------------------------------------------------------------
+export class LspClient {
+    projectCwd;
+    langKey;
+    binPath;
+    binArgs;
+    languageId;
+    onIdleEvict;
+    proc = null;
+    nextId = 1;
+    pendingRequests = new Map();
+    diagnosticsCache = new Map(); // fileUri -> diagnostics
+    openFiles = new Set(); // fileUri
+    docVersions = new Map(); // fileUri -> version
+    buffer = Buffer.alloc(0);
+    idleTimer = null;
+    initialized = false;
+    isShuttingDown = false;
+    constructor(projectCwd, langKey, binPath, binArgs, languageId, onIdleEvict) {
+        this.projectCwd = projectCwd;
+        this.langKey = langKey;
+        this.binPath = binPath;
+        this.binArgs = binArgs;
+        this.languageId = languageId;
+        this.onIdleEvict = onIdleEvict;
+    }
+    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"),
+        });
+        this.proc.stdout?.on("data", (chunk) => this.handleData(chunk));
+        this.proc.stderr?.on("data", (d) => {
+            // 可选记录 debug 日志，不干扰输出
+        });
+        this.proc.on("exit", (code) => {
+            this.proc = null;
+            this.rejectAllPending(new Error(`Language server exited with code ${code}`));
+        });
+        try {
+            // 发送 initialize 握手
+            const initRes = await this.request("initialize", {
+                processId: process.pid,
+                rootUri: pathToFileURL(this.projectCwd).toString(),
+                workspaceFolders: [
+                    {
+                        name: "workspace",
+                        uri: pathToFileURL(this.projectCwd).toString(),
+                    },
+                ],
+                capabilities: {
+                    textDocument: {
+                        synchronization: { dynamicRegistration: false, willSave: false, willSaveWaitUntil: false, didSave: true },
+                        definition: { dynamicRegistration: false },
+                        references: { dynamicRegistration: false },
+                        hover: { dynamicRegistration: false, contentFormat: ["markdown", "plaintext"] },
+                        publishDiagnostics: { relatedInformation: true, tagSupport: { valueSet: [1, 2] } },
+                    },
+                },
+            });
+            this.notify("initialized", {});
+            this.initialized = true;
+        }
+        catch (err) {
+            if (this.proc) {
+                try {
+                    this.proc.kill();
+                }
+                catch { }
+                this.proc = null;
+            }
+            throw err;
+        }
+    }
+    touch() {
+        if (this.isShuttingDown)
+            return;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        // 15 分钟无调用自动回收
+        this.idleTimer = setTimeout(() => {
+            this.shutdown().catch(() => { });
+            this.onIdleEvict();
+        }, 15 * 60 * 1000);
+        this.idleTimer.unref();
+    }
+    handleData(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (true) {
+            const headerEnd = this.buffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                break;
+            const header = this.buffer.slice(0, headerEnd).toString("utf8");
+            const lenMatch = header.match(/Content-Length:\s*(\d+)/i);
+            if (!lenMatch) {
+                this.buffer = this.buffer.slice(headerEnd + 4);
+                continue;
+            }
+            const length = parseInt(lenMatch[1], 10);
+            const bodyStart = headerEnd + 4;
+            if (this.buffer.length < bodyStart + length)
+                break;
+            const bodyBuf = this.buffer.slice(bodyStart, bodyStart + length);
+            this.buffer = this.buffer.slice(bodyStart + length);
+            try {
+                const msg = JSON.parse(bodyBuf.toString("utf8"));
+                this.handleMessage(msg);
+            }
+            catch { }
+        }
+    }
+    handleMessage(msg) {
+        if (msg.id !== undefined) {
+            if (msg.method) {
+                // 服务端向客户端发起的请求（如 window/workDoneProgress/create, client/registerCapability）
+                // 标准 JSON-RPC 必须回复 result: null，防止上游语言服务器挂起等待
+                const reply = JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: null });
+                const wire = `Content-Length: ${Buffer.byteLength(reply, "utf8")}\r\n\r\n${reply}`;
+                try {
+                    this.proc?.stdin?.write(wire);
+                }
+                catch { }
+                return;
+            }
+            if (this.pendingRequests.has(msg.id)) {
+                const { resolve, reject, timer } = this.pendingRequests.get(msg.id);
+                clearTimeout(timer);
+                this.pendingRequests.delete(msg.id);
+                if (msg.error) {
+                    reject(new Error(msg.error.message || `LSP error ${msg.error.code}`));
+                }
+                else {
+                    resolve(msg.result);
+                }
+            }
+        }
+        else if (msg.method === "textDocument/publishDiagnostics") {
+            const params = msg.params;
+            if (params?.uri && Array.isArray(params?.diagnostics)) {
+                this.diagnosticsCache.set(params.uri, params.diagnostics);
+            }
+        }
+    }
+    request(method, params, timeoutMs = 15000) {
+        this.touch();
+        if (!this.proc || !this.proc.stdin) {
+            return Promise.reject(new Error("Language server is not running"));
+        }
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+        const wire = `Content-Length: ${Buffer.byteLength(payload, "utf8")}\r\n\r\n${payload}`;
+        return new Promise((res, rej) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                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);
+        });
+    }
+    notify(method, params) {
+        this.touch();
+        if (!this.proc || !this.proc.stdin)
+            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);
+    }
+    async syncDocument(absPath) {
+        const uri = pathToFileURL(absPath).toString();
+        if (!existsSync(absPath))
+            return uri;
+        const content = readFileSync(absPath, "utf8");
+        if (!this.openFiles.has(uri)) {
+            this.docVersions.set(uri, 1);
+            this.notify("textDocument/didOpen", {
+                textDocument: {
+                    uri,
+                    languageId: this.languageId,
+                    version: 1,
+                    text: content,
+                },
+            });
+            this.openFiles.add(uri);
+        }
+        else {
+            const nextVer = (this.docVersions.get(uri) ?? 1) + 1;
+            this.docVersions.set(uri, nextVer);
+            this.notify("textDocument/didChange", {
+                textDocument: { uri, version: nextVer },
+                contentChanges: [{ text: content }],
+            });
+        }
+        return uri;
+    }
+    getDiagnostics(uri) {
+        return this.diagnosticsCache.get(uri) ?? [];
+    }
+    getAllDiagnostics() {
+        return new Map(this.diagnosticsCache);
+    }
+    isAlive() {
+        return Boolean(this.proc && !this.isShuttingDown);
+    }
+    rejectAllPending(err) {
+        for (const { reject, timer } of this.pendingRequests.values()) {
+            clearTimeout(timer);
+            reject(err);
+        }
+        this.pendingRequests.clear();
+    }
+    async shutdown() {
+        this.isShuttingDown = true;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (!this.proc)
+            return;
+        try {
+            await this.request("shutdown", {}, 3000);
+            this.notify("exit", {});
+        }
+        catch { }
+        if (this.proc) {
+            try {
+                this.proc.kill();
+            }
+            catch { }
+            this.proc = null;
+        }
+        this.rejectAllPending(new Error("LSP client shut down"));
+    }
+}
+// ----------------------------------------------------------------------------
+// 全局项目级语言服务器管理池（Project-Level LSP Pool）
+// ----------------------------------------------------------------------------
+class LspServerPool {
+    pool = new Map(); // key: `${cwd}::${langKey}`
+    inFlight = new Map();
+    shuttingDown = false;
+    hasAliveClient(projectCwd, filePath) {
+        const langInfo = getLanguageForPath(filePath);
+        if (!langInfo)
+            return false;
+        const poolKey = `${projectCwd}::${langInfo.langKey}`;
+        const client = this.pool.get(poolKey);
+        return Boolean(client && client.isAlive());
+    }
+    async getClient(projectCwd, filePath) {
+        if (this.shuttingDown) {
+            return { error: "LSP server pool is shutting down" };
+        }
+        const langInfo = getLanguageForPath(filePath);
+        if (!langInfo) {
+            return { error: `No language server mapping for file extension: ${extname(filePath)}` };
+        }
+        const poolKey = `${projectCwd}::${langInfo.langKey}`;
+        const client = this.pool.get(poolKey);
+        if (client) {
+            client.touch();
+            return { client };
+        }
+        const pending = this.inFlight.get(poolKey);
+        if (pending) {
+            return pending;
+        }
+        const task = (async () => {
+            // 寻找可用命令
+            let resolvedBin = null;
+            let resolvedArgs = [];
+            let hint = "";
+            for (const cmd of langInfo.config.commands) {
+                const found = resolveBinary(cmd.bin, projectCwd);
+                if (found) {
+                    resolvedBin = found;
+                    resolvedArgs = cmd.args;
+                    break;
+                }
+                hint = cmd.installHint;
+            }
+            if (!resolvedBin) {
+                return {
+                    error: `Language server for ${langInfo.config.languageId} not found.\nPlease install it: \`${hint}\``,
+                };
+            }
+            const newClient = new LspClient(projectCwd, langInfo.langKey, resolvedBin, resolvedArgs, langInfo.config.languageId, () => {
+                if (this.pool.get(poolKey) === newClient) {
+                    this.pool.delete(poolKey);
+                }
+            });
+            try {
+                await newClient.start();
+                if (this.shuttingDown) {
+                    await newClient.shutdown();
+                    return { error: "LSP server pool is shutting down" };
+                }
+                this.pool.set(poolKey, newClient);
+                return { client: newClient };
+            }
+            catch (err) {
+                return { error: `Failed to start ${langInfo.config.languageId} language server: ${err.message}` };
+            }
+            finally {
+                this.inFlight.delete(poolKey);
+            }
+        })();
+        this.inFlight.set(poolKey, task);
+        return task;
+    }
+    async shutdownAll() {
+        this.shuttingDown = true;
+        const inFlightTasks = [...this.inFlight.values()];
+        this.inFlight.clear();
+        await Promise.allSettled(inFlightTasks);
+        const promises = [...this.pool.values()].map((c) => c.shutdown());
+        this.pool.clear();
+        await Promise.allSettled(promises);
+    }
+}
+export const globalLspPool = new LspServerPool();
+/**
+ * 辅助函数：在文件改动后，若已有存活的语言服务器，获取即时编译报错（Writethrough Diagnostics）
+ */
+export async function getLiveLspDiagnostics(absPath, cwd) {
+    if (!globalLspPool.hasAliveClient(cwd, absPath)) {
+        return null;
+    }
+    const res = await globalLspPool.getClient(cwd, absPath);
+    if ("error" in res)
+        return null;
+    const { client } = res;
+    const uri = await client.syncDocument(absPath);
+    // 稍等 80ms 让后台增量分析返回
+    await new Promise((r) => setTimeout(r, 80));
+    const diags = client.getDiagnostics(uri);
+    const errors = diags.filter((d) => d.severity === 1 || !d.severity);
+    if (errors.length === 0)
+        return null;
+    const rel = absPath.startsWith(cwd) ? absPath.slice(cwd.length).replace(/^[/\\]/, "") : absPath;
+    const lines = errors.slice(0, 5).map((e) => {
+        const line = e.range.start.line + 1;
+        const col = e.range.start.character + 1;
+        const code = e.code ? ` (${e.code})` : "";
+        return `• ${rel}:${line}:${col} - ${e.message}${code}`;
+    });
+    return `⚠️ Post-edit Diagnostics (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}`;
+}
+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.`,
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal("definition"), Type.Literal("references"), Type.Literal("hover"), Type.Literal("diagnostics")], {
+                description: "The LSP operation to perform.",
+            }),
+            path: Type.String({
+                description: "Workspace-relative or absolute path to the target source file.",
+            }),
+            line: Type.Optional(Type.Number({
+                description: "1-indexed line number in the source file.",
+            })),
+            character: Type.Optional(Type.Number({
+                description: "1-indexed column/character position (defaults to 1).",
+            })),
+            timeout: Type.Optional(Type.Number({
+                description: "Timeout in seconds (defaults to 15).",
+            })),
+        }),
+        async execute(_callId, params, _signal, _onUpdate, _ctx) {
+            const action = params.action;
+            const targetPath = params.path;
+            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;
+            const timeoutMs = (params.timeout ?? 15) * 1000;
+            const rel = relative(cwd, absPath);
+            if (rel === ".." ||
+                rel.startsWith(".." + sep) ||
+                rel.startsWith("../") ||
+                rel.startsWith("..\\") ||
+                isAbsolute(rel)) {
+                return {
+                    content: [{ type: "text", text: `Error: Path traversal denied: ${targetPath} is outside workspace.` }],
+                    details: { ok: false, error: "Path traversal denied" },
+                };
+            }
+            if (!existsSync(absPath)) {
+                return {
+                    content: [{ type: "text", text: `Error: File not found: ${targetPath}` }],
+                    details: { ok: false, error: "File not found" },
+                };
+            }
+            const clientRes = await globalLspPool.getClient(cwd, absPath);
+            if ("error" in clientRes) {
+                return {
+                    content: [{ type: "text", text: `LSP Error: ${clientRes.error}` }],
+                    details: { ok: false, error: clientRes.error },
+                };
+            }
+            const client = clientRes.client;
+            const uri = await client.syncDocument(absPath);
+            // 0-indexed positions for LSP protocol
+            const position = {
+                line: line - 1,
+                character: character - 1,
+            };
+            try {
+                if (action === "definition") {
+                    const result = await client.request("textDocument/definition", { textDocument: { uri }, position }, timeoutMs);
+                    const locs = Array.isArray(result) ? result : result ? [result] : [];
+                    if (locs.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No definition found for symbol at ${targetPath}:${line}:${character}` }],
+                            details: { ok: true, locations: [] },
+                        };
+                    }
+                    const formatted = locs.map((loc) => {
+                        const targetUri = loc.targetUri || loc.uri || "";
+                        let defPath = targetUri;
+                        try {
+                            if (targetUri.startsWith("file:")) {
+                                defPath = fileURLToPath(targetUri);
+                            }
+                        }
+                        catch { }
+                        const targetRange = loc.targetSelectionRange || loc.targetRange || loc.range;
+                        const defRel = defPath.startsWith(cwd) ? defPath.slice(cwd.length).replace(/^[/\\]/, "") : defPath;
+                        const defLine = (targetRange?.start?.line ?? 0) + 1;
+                        const defCol = (targetRange?.start?.character ?? 0) + 1;
+                        let snippet = "";
+                        if (existsSync(defPath)) {
+                            const fileLines = readFileSync(defPath, "utf8").split(/\r?\n/);
+                            const startL = Math.max(0, defLine - 1);
+                            const endL = Math.min(fileLines.length, defLine + 3);
+                            snippet = fileLines
+                                .slice(startL, endL)
+                                .map((l, idx) => `${startL + idx + 1}: ${l}`)
+                                .join("\n");
+                        }
+                        return `• ${defRel}:${defLine}:${defCol}\n\`\`\`\n${snippet}\n\`\`\``;
+                    });
+                    return {
+                        content: [{ type: "text", text: `Definitions (${locs.length}):\n\n${formatted.join("\n\n")}` }],
+                        details: { ok: true, locations: locs },
+                    };
+                }
+                if (action === "references") {
+                    const result = await client.request("textDocument/references", {
+                        textDocument: { uri },
+                        position,
+                        context: { includeDeclaration: true },
+                    }, timeoutMs);
+                    const locs = Array.isArray(result) ? result : [];
+                    if (locs.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No references found for symbol at ${targetPath}:${line}:${character}` }],
+                            details: { ok: true, references: [] },
+                        };
+                    }
+                    const formatted = locs.slice(0, 25).map((loc) => {
+                        const refPath = fileURLToPath(loc.uri);
+                        const refRel = refPath.startsWith(cwd) ? refPath.slice(cwd.length).replace(/^[/\\]/, "") : refPath;
+                        const refLine = loc.range.start.line + 1;
+                        const refCol = loc.range.start.character + 1;
+                        return `• ${refRel}:${refLine}:${refCol}`;
+                    });
+                    const tail = locs.length > 25 ? `\n... and ${locs.length - 25} more references` : "";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Found ${locs.length} reference${locs.length > 1 ? "s" : ""}:\n${formatted.join("\n")}${tail}`,
+                            },
+                        ],
+                        details: { ok: true, count: locs.length, references: locs },
+                    };
+                }
+                if (action === "hover") {
+                    const result = await client.request("textDocument/hover", { textDocument: { uri }, position }, timeoutMs);
+                    if (!result || !result.contents) {
+                        return {
+                            content: [{ type: "text", text: `No hover information available at ${targetPath}:${line}:${character}` }],
+                            details: { ok: true, hover: null },
+                        };
+                    }
+                    let hoverText = "";
+                    const c = result.contents;
+                    if (typeof c === "string") {
+                        hoverText = c;
+                    }
+                    else if (Array.isArray(c)) {
+                        hoverText = c.map((item) => (typeof item === "string" ? item : item.value)).join("\n\n");
+                    }
+                    else if (typeof c === "object" && c.value) {
+                        hoverText = c.value;
+                    }
+                    return {
+                        content: [{ type: "text", text: hoverText ? `Hover Info:\n${hoverText}` : "Empty hover information" }],
+                        details: { ok: true, hover: result },
+                    };
+                }
+                if (action === "diagnostics") {
+                    // 给予极短缓冲以确保 publishDiagnostics 缓存已收到
+                    await new Promise((r) => setTimeout(r, 120));
+                    const diags = client.getDiagnostics(uri);
+                    if (diags.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `No diagnostics (clean): ${targetPath}` }],
+                            details: { ok: true, diagnostics: [] },
+                        };
+                    }
+                    const formatted = diags.slice(0, 30).map((d) => {
+                        const sev = d.severity === 1 ? "ERROR" : d.severity === 2 ? "WARN" : "INFO";
+                        const startLine = d.range.start.line + 1;
+                        const startCol = d.range.start.character + 1;
+                        const code = d.code ? ` [${d.code}]` : "";
+                        return `[${sev}] line ${startLine}:${startCol}${code} - ${d.message}`;
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Diagnostics for ${targetPath} (${diags.length}):\n${formatted.join("\n")}`,
+                            },
+                        ],
+                        details: { ok: true, diagnostics: diags },
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `Unsupported action: ${action}` }],
+                    details: { ok: false, error: "Unsupported action" },
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `LSP request failed: ${err.message}` }],
+                    details: { ok: false, error: err.message },
+                };
+            }
+        },
+    });
+}