ms-vite-plugin 1.4.14 → 1.4.16

package/dist/mcp/device-log.d.ts

@@ -1,25 +1,10 @@
+import type { RuntimeHttpTarget } from "./tool-utils";
 /**
- * 设备日志内存缓存上限
- * - 采用环形窗口思路，仅保留最新 5000 条，避免 MCP 进程长期运行时内存无限增长
- */
-export declare const DEVICE_LOG_MEMORY_LIMIT = 5000;
-/**
- * 确保后台日志订阅处于目标设备上
- * - 若目标未变化且订阅仍在运行，则直接复用已有连接
- * - 若目标发生变化，则重置缓存并重新建立订阅
- * @param ip 设备 IP
- * @param port 设备端口
- * @returns 返回是否复用了现有订阅
- * @example
- * const reused = ensureDeviceLogSubscription("192.168.1.10", 9800)
- */
-export declare function ensureDeviceLogSubscription(ip: string, port: number): boolean;
-/**
- * 生成日志缓存快照文本
- * @param limit 需要返回的日志条数
- * @param runtimeStatusLimit 需要返回的 runtime_status 条数
- * @returns 返回用于 MCP 文本响应的快照内容
+ * 构建当前设备日志文本快照
+ * @param target 当前默认 HTTP 设备
+ * @param limit 需要返回的最新日志行数
+ * @returns 返回可直接作为 MCP 文本响应的日志内容
  * @example
- * const text = buildDeviceLogSnapshotText(100, 20)
+ * const text = await buildDeviceLogSnapshotText({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 200)
  */
-export declare function buildDeviceLogSnapshotText(limit: number, runtimeStatusLimit: number): string;
+export declare function buildDeviceLogSnapshotText(target: RuntimeHttpTarget, limit: number): Promise<string>;

package/dist/mcp/device-log.js

@@ -1,390 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEVICE_LOG_MEMORY_LIMIT = void 0;
-exports.ensureDeviceLogSubscription = ensureDeviceLogSubscription;
 exports.buildDeviceLogSnapshotText = buildDeviceLogSnapshotText;
-/**
- * 设备日志内存缓存上限
- * - 采用环形窗口思路，仅保留最新 5000 条，避免 MCP 进程长期运行时内存无限增长
- */
-exports.DEVICE_LOG_MEMORY_LIMIT = 5000;
-/**
- * SSE 重连等待时间（毫秒）
- * - 当设备日志流异常断开时，后台会自动尝试重连
- */
-const DEVICE_LOG_RECONNECT_DELAY_MS = 1500;
-/**
- * 视为“仍在工作中”的日志订阅状态集合
- * - 用于判断同一设备是否可以直接复用已有后台连接
- */
-const ACTIVE_DEVICE_LOG_SUBSCRIPTION_STATUSES = new Set([
-    "connecting",
-    "connected",
-    "reconnecting",
-]);
-/**
- * 进程级设备日志订阅状态
- * - 当前 MCP 仅维护单设备日志缓存
- * - MCP Tool 处理函数会复用同一份内存缓存
- */
-const deviceLogSubscriptionState = {
-    target: null,
-    status: "idle",
-    lastError: null,
-    lastEventAt: null,
-    startedAt: null,
-    logs: [],
-    runtimeStatus: [],
-    generation: 0,
-    controller: null,
-    reconnectTimer: null,
-};
-/**
- * 向环形缓冲区追加数据
- * @param buffer 目标数组
- * @param entry 待写入的数据
- * @param limit 数组最大长度
- * @returns 无返回值
- * @example
- * pushRingBuffer([1, 2], 3, 2)
- */
-function pushRingBuffer(buffer, entry, limit) {
-    if (buffer.length >= limit) {
-        buffer.splice(0, buffer.length - limit + 1);
-    }
-    buffer.push(entry);
-}
-/**
- * 重置当前日志缓存快照
- * @returns 无返回值
- * @example
- * resetDeviceLogSnapshotState()
- */
-function resetDeviceLogSnapshotState() {
-    deviceLogSubscriptionState.lastError = null;
-    deviceLogSubscriptionState.lastEventAt = null;
-    deviceLogSubscriptionState.startedAt = new Date().toISOString();
-    deviceLogSubscriptionState.logs = [];
-    deviceLogSubscriptionState.runtimeStatus = [];
-}
-/**
- * 判断日志订阅是否仍然活跃
- * @returns 活跃返回 true，否则返回 false
- * @example
- * const active = isDeviceLogSubscriptionActive()
- */
-function isDeviceLogSubscriptionActive() {
-    return (ACTIVE_DEVICE_LOG_SUBSCRIPTION_STATUSES.has(deviceLogSubscriptionState.status) || deviceLogSubscriptionState.reconnectTimer !== null);
-}
-/**
- * 解析单个 SSE 文本块
- * @param rawBlock 原始 SSE 文本块
- * @returns 返回事件名与 data 字符串
- * @example
- * parseSseEventBlock("event: log\ndata: {\"message\":\"ok\"}")
- */
-function parseSseEventBlock(rawBlock) {
-    const lines = rawBlock.split(/\r?\n/);
-    let eventName = "message";
-    const dataLines = [];
-    for (const line of lines) {
-        if (line.startsWith("event:")) {
-            eventName = line.slice(6).trim() || "message";
-            continue;
-        }
-        if (line.startsWith("data:")) {
-            dataLines.push(line.slice(5).trimStart());
-        }
-    }
-    return {
-        event: eventName,
-        data: dataLines.join("\n"),
-    };
-}
-/**
- * 将原始日志对象标准化为统一结构
- * @param payload 日志原始对象
- * @returns 返回标准化后的日志
- * @example
- * normalizeBufferedLogEntry({ level: "info", message: "started" })
- */
-function normalizeBufferedLogEntry(payload) {
-    const levelText = String(payload.level ?? "info").toLowerCase();
-    const messageText = String(payload.message ?? "");
-    const timestampText = typeof payload.timestamp === "string" && payload.timestamp
-        ? payload.timestamp
-        : new Date().toISOString();
-    return {
-        level: levelText,
-        message: messageText,
-        timestamp: timestampText,
-    };
-}
-/**
- * 清理当前后台日志订阅
- * @returns 无返回值
- * @example
- * stopDeviceLogSubscription()
- */
-function stopDeviceLogSubscription() {
-    if (deviceLogSubscriptionState.reconnectTimer) {
-        clearTimeout(deviceLogSubscriptionState.reconnectTimer);
-        deviceLogSubscriptionState.reconnectTimer = null;
-    }
-    if (deviceLogSubscriptionState.controller) {
-        deviceLogSubscriptionState.controller.abort();
-        deviceLogSubscriptionState.controller = null;
-    }
-}
-/**
- * 安排后台重连
- * @param generation 当前订阅代次
- * @returns 无返回值
- * @example
- * scheduleDeviceLogReconnect(1)
- */
-function scheduleDeviceLogReconnect(generation) {
-    if (generation !== deviceLogSubscriptionState.generation ||
-        !deviceLogSubscriptionState.target) {
-        return;
-    }
-    if (deviceLogSubscriptionState.reconnectTimer) {
-        return;
-    }
-    deviceLogSubscriptionState.status = "reconnecting";
-    deviceLogSubscriptionState.reconnectTimer = setTimeout(() => {
-        deviceLogSubscriptionState.reconnectTimer = null;
-        void startDeviceLogSubscriptionLoop(generation);
-    }, DEVICE_LOG_RECONNECT_DELAY_MS);
-}
-/**
- * 启动一次 SSE 读取循环
- * - 该函数仅负责单次连接；若连接中断，会由外层自动调度重连
- * @param generation 当前订阅代次
- * @returns 读取流程结束后返回 Promise<void>
- * @example
- * await startDeviceLogSubscriptionLoop(1)
- */
-async function startDeviceLogSubscriptionLoop(generation) {
-    if (generation !== deviceLogSubscriptionState.generation ||
-        !deviceLogSubscriptionState.target) {
-        return;
-    }
-    const { ip, port } = deviceLogSubscriptionState.target;
-    const controller = new AbortController();
-    const url = `http://${ip}:${port}/logger/sse`;
-    deviceLogSubscriptionState.controller = controller;
-    deviceLogSubscriptionState.status =
-        deviceLogSubscriptionState.lastEventAt === null
-            ? "connecting"
-            : "reconnecting";
-    try {
-        const response = await fetch(url, {
-            method: "GET",
-            signal: controller.signal,
-            headers: {
-                Accept: "text/event-stream",
-            },
-        });
-        if (!response.ok || !response.body) {
-            throw new Error(`连接日志流失败: ${response.status} ${response.statusText || "unknown"}`);
-        }
-        deviceLogSubscriptionState.status = "connected";
-        deviceLogSubscriptionState.lastError = null;
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder("utf-8");
-        let buffer = "";
-        while (generation === deviceLogSubscriptionState.generation) {
-            const { value, done } = await reader.read();
-            if (done) {
-                break;
-            }
-            buffer += decoder.decode(value, { stream: true });
-            let splitIndex = buffer.search(/\r?\n\r?\n/);
-            while (splitIndex >= 0) {
-                const rawBlock = buffer.slice(0, splitIndex);
-                buffer = buffer.slice(splitIndex + (buffer[splitIndex] === "\r" ? 4 : 2));
-                const event = parseSseEventBlock(rawBlock);
-                if (event.data) {
-                    try {
-                        const parsed = JSON.parse(event.data);
-                        deviceLogSubscriptionState.lastEventAt = new Date().toISOString();
-                        if (event.event === "log") {
-                            pushRingBuffer(deviceLogSubscriptionState.logs, normalizeBufferedLogEntry(parsed), exports.DEVICE_LOG_MEMORY_LIMIT);
-                        }
-                        else if (event.event === "runtime_status") {
-                            pushRingBuffer(deviceLogSubscriptionState.runtimeStatus, {
-                                raw: parsed,
-                                timestamp: new Date().toISOString(),
-                            }, exports.DEVICE_LOG_MEMORY_LIMIT);
-                        }
-                    }
-                    catch {
-                        // 忽略单条非法 JSON，避免因为异常日志阻塞整个后台连接
-                    }
-                }
-                splitIndex = buffer.search(/\r?\n\r?\n/);
-            }
-        }
-        if (generation === deviceLogSubscriptionState.generation) {
-            scheduleDeviceLogReconnect(generation);
-        }
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            (error.name === "AbortError" ||
-                error.message === "The operation was aborted.")) {
-            return;
-        }
-        if (generation === deviceLogSubscriptionState.generation) {
-            deviceLogSubscriptionState.status = "error";
-            deviceLogSubscriptionState.lastError =
-                error instanceof Error ? error.message : String(error);
-            scheduleDeviceLogReconnect(generation);
-        }
-    }
-    finally {
-        if (deviceLogSubscriptionState.controller === controller) {
-            deviceLogSubscriptionState.controller = null;
-        }
-    }
-}
-/**
- * 确保后台日志订阅处于目标设备上
- * - 若目标未变化且订阅仍在运行，则直接复用已有连接
- * - 若目标发生变化，则重置缓存并重新建立订阅
- * @param ip 设备 IP
- * @param port 设备端口
- * @returns 返回是否复用了现有订阅
- * @example
- * const reused = ensureDeviceLogSubscription("192.168.1.10", 9800)
- */
-function ensureDeviceLogSubscription(ip, port) {
-    const sameTarget = deviceLogSubscriptionState.target?.ip === ip &&
-        deviceLogSubscriptionState.target?.port === port;
-    const isActive = isDeviceLogSubscriptionActive();
-    if (sameTarget && isActive) {
-        return true;
-    }
-    stopDeviceLogSubscription();
-    deviceLogSubscriptionState.generation += 1;
-    deviceLogSubscriptionState.target = { ip, port };
-    deviceLogSubscriptionState.status = "connecting";
-    resetDeviceLogSnapshotState();
-    void startDeviceLogSubscriptionLoop(deviceLogSubscriptionState.generation);
-    return false;
-}
-/**
- * 按日志页面风格格式化时间
- * @param value ISO 时间字符串
- * @returns 返回 `yyyy/mm/dd hh:mm:ss.xxx` 风格文本，异常时回退原值
- * @example
- * formatDisplayTimestamp("2026-05-07T11:34:48.776Z")
- */
-function formatDisplayTimestamp(value) {
-    const date = new Date(value);
-    if (Number.isNaN(date.getTime())) {
-        return value;
-    }
-    const pad = (number, length = 2) => String(number).padStart(length, "0");
-    return `${date.getFullYear()}/${pad(date.getMonth() + 1)}/${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
-}
-/**
- * 将日志订阅连接状态转为中文文本
- * @param status 原始连接状态
- * @returns 返回中文状态说明
- * @example
- * formatDeviceLogSubscriptionStatus("connected")
- */
-function formatDeviceLogSubscriptionStatus(status) {
-    switch (status) {
-        case "idle":
-            return "未订阅";
-        case "connecting":
-            return "连接中";
-        case "connected":
-            return "已连接";
-        case "reconnecting":
-            return "重连中";
-        case "error":
-            return "连接异常";
-        default:
-            return status;
-    }
-}
-/**
- * 将 runtime_status 中的内存数值格式化为可读文本
- * @param value 原始数值
- * @param suffix 数值单位后缀
- * @returns 数值存在时返回格式化结果，否则返回未知
- * @example
- * formatRuntimeMetricText(12.3456, " MB")
- */
-function formatRuntimeMetricText(value, suffix = "") {
-    if (typeof value === "number" && Number.isFinite(value)) {
-        return `${value.toFixed(2)}${suffix}`;
-    }
-    return "未知";
-}
-/**
- * 将单条 runtime_status 事件格式化为中文运行状态摘要
- * @param entry runtime_status 条目
- * @returns 返回更易读的状态文本
- * @example
- * formatRuntimeStatusEntry({ raw: { isRunning: false }, timestamp: "2026-01-01T00:00:00.000Z" })
- */
-function formatRuntimeStatusEntry(entry) {
-    const raw = entry.raw;
-    const memory = raw.memory && typeof raw.memory === "object"
-        ? raw.memory
-        : {};
-    return [
-        `[${formatDisplayTimestamp(entry.timestamp)}]`,
-        `UI: ${typeof raw.isUIShowing === "boolean"
-            ? raw.isUIShowing
-                ? "显示中"
-                : "未显示"
-            : "未知"}`,
-        `脚本: ${typeof raw.isRunning === "boolean"
-            ? raw.isRunning
-                ? "运行中"
-                : "未运行"
-            : "未知"}`,
-        `系统: ${formatRuntimeMetricText(memory.systemUsed, " MB")}/${formatRuntimeMetricText(memory.total, " MB")}`,
-        `系统占用: ${formatRuntimeMetricText(memory.usagePercentage, "%")}`,
-        `应用: ${formatRuntimeMetricText(memory.used, " MB")}`,
-    ].join(" | ");
-}
-/**
- * 生成日志缓存快照文本
- * @param limit 需要返回的日志条数
- * @param runtimeStatusLimit 需要返回的 runtime_status 条数
- * @returns 返回用于 MCP 文本响应的快照内容
- * @example
- * const text = buildDeviceLogSnapshotText(100, 20)
- */
-function buildDeviceLogSnapshotText(limit, runtimeStatusLimit) {
-    const recentLogs = deviceLogSubscriptionState.logs
-        .slice(-limit)
-        .map((log) => `[${formatDisplayTimestamp(log.timestamp)}] [${log.level.toUpperCase()}] ${log.message}`);
-    const recentRuntimeStatus = deviceLogSubscriptionState.runtimeStatus
-        .slice(-runtimeStatusLimit)
-        .map((entry) => formatRuntimeStatusEntry(entry));
+const project_1 = require("../project");
+/**
+ * 构建当前设备日志文本快照
+ * @param target 当前默认 HTTP 设备
+ * @param limit 需要返回的最新日志行数
+ * @returns 返回可直接作为 MCP 文本响应的日志内容
+ * @example
+ * const text = await buildDeviceLogSnapshotText({ ip: "192.168.1.10", port: "9800", label: "192.168.1.10:9800" }, 200)
+ */
+async function buildDeviceLogSnapshotText(target, limit) {
+    const result = await (0, project_1.getCurrentLogLinesOnDevice)({
+        ip: target.ip,
+        port: target.port,
+        transport: "http",
+    }, limit);
+    const lines = result.lines.length > 0 ? result.lines.join("\n") : "无日志";
     return [
-        `设备: ${deviceLogSubscriptionState.target
-            ? `${deviceLogSubscriptionState.target.ip}:${deviceLogSubscriptionState.target.port}`
-            : "未订阅"}`,
-        `状态: ${formatDeviceLogSubscriptionStatus(deviceLogSubscriptionState.status)}`,
-        ...(deviceLogSubscriptionState.lastError
-            ? [`最近错误: ${deviceLogSubscriptionState.lastError}`]
-            : []),
-        "",
-        `最新日志（最多 ${limit} 条）:`,
-        recentLogs.length > 0 ? recentLogs.join("\n") : "无日志",
+        `设备: ${target.label}`,
+        `还有更早日志: ${result.hasMore ? "是" : "否"}`,
         "",
-        `最新运行状态（最多 ${runtimeStatusLimit} 条）:`,
-        recentRuntimeStatus.length > 0
-            ? recentRuntimeStatus.join("\n")
-            : "无运行状态",
+        `最新日志（最多 ${limit} 行）:`,
+        lines,
     ].join("\n");
 }

package/dist/mcp/doc-tools.d.ts

@@ -1,12 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * 注册文档资源
- * @param server MCP 服务实例
- * @returns 无返回值
- * @example
- * registerDocResources(server)
- */
-export declare function registerDocResources(server: McpServer): void;
 /**
  * 注册文档工具
  * @param server MCP 服务实例

package/dist/mcp/doc-tools.js

@@ -33,73 +33,27 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerDocResources = registerDocResources;
 exports.registerDocTools = registerDocTools;
-const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const z = __importStar(require("zod/v4"));
 const docs_service_1 = require("./docs-service");
+const httpapi_docs_service_1 = require("./httpapi-docs-service");
 const tool_utils_1 = require("./tool-utils");
 const types_1 = require("./types");
 /**
- * 注册文档资源
- * @param server MCP 服务实例
- * @returns 无返回值
+ * 格式化 KuaiJS 文档路径清单
+ * @returns 返回可直接交给 AI 读取的文档路径文本
  * @example
- * registerDocResources(server)
+ * const text = formatDocsPathsText()
  */
-function registerDocResources(server) {
-    server.registerResource("current-language", "kuaijs://docs/current-language", {
-        title: "Current KuaiJS API language",
-        mimeType: "application/json",
-    }, async () => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        return {
-            contents: [
-                {
-                    uri: "kuaijs://docs/current-language",
-                    mimeType: "application/json",
-                    text: JSON.stringify({
-                        currentLanguage: language,
-                        label: types_1.DOC_LANGUAGE_LABELS[language],
-                    }, null, 2),
-                },
-            ],
-        };
-    });
-    server.registerResource("api-doc", new mcp_js_1.ResourceTemplate("kuaijs://docs/current/{slug}", {
-        list: async () => {
-            const language = (0, docs_service_1.getCurrentDocsLanguage)();
-            const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
-            return {
-                resources: docs.map((doc) => ({
-                    uri: `kuaijs://docs/current/${doc.slug}`,
-                    name: doc.title,
-                    description: `[${types_1.DOC_LANGUAGE_LABELS[language]}] ${doc.slug}`,
-                    mimeType: "text/markdown",
-                })),
-            };
-        },
-    }), {
-        title: "KuaiJS API documents",
-        mimeType: "text/markdown",
-    }, async (_uri, variables) => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        const docs = await (0, docs_service_1.getApiDocsByLanguage)(language);
-        const slug = String(variables.slug || "");
-        const target = docs.find((doc) => doc.slug === slug);
-        if (!target) {
-            throw new Error(`文档不存在: ${slug}`);
-        }
-        return {
-            contents: [
-                {
-                    uri: `kuaijs://docs/current/${target.slug}`,
-                    mimeType: "text/markdown",
-                    text: target.content,
-                },
-            ],
-        };
-    });
+function formatDocsPathsText() {
+    const languages = ["js", "js_zh", "python"];
+    return [
+        "KuaiJS 文档路径:",
+        `docsRoot: ${(0, docs_service_1.getDocsRootDir)()}`,
+        ...languages.map((language) => `${language}: ${(0, docs_service_1.getDocsDirByLanguage)(language)} (${types_1.DOC_LANGUAGE_LABELS[language]})`),
+        `httpApi: ${(0, httpapi_docs_service_1.getHttpApiDocPath)()}`,
+        "说明: 直接读取上述 markdown 路径；search/read 工具用于定位具体文档。",
+    ].join("\n");
 }
 /**
  * 注册文档工具
@@ -109,51 +63,37 @@ function registerDocResources(server) {
  * registerDocTools(server)
  */
 function registerDocTools(server) {
-    server.registerTool("get_docs_language", {
-        title: "Get Docs Language",
-        description: "获取当前 KuaiJS API 文档语言。",
+    server.registerTool("get_docs_paths", {
+        title: "Get Docs Paths",
+        description: "获取 KuaiJS 本地文档路径，便于 AI 直接读取 markdown 文件而不是猜测位置。",
         inputSchema: {},
     }, async () => {
-        const language = (0, docs_service_1.getCurrentDocsLanguage)();
-        return (0, tool_utils_1.createTextToolResult)(`当前文档语言: ${language} (${types_1.DOC_LANGUAGE_LABELS[language]})`);
-    });
-    server.registerTool("set_docs_language", {
-        title: "Set Docs Language",
-        description: "设置当前 KuaiJS API 文档语言，影响后续文档查询与读取。",
-        inputSchema: {
-            language: z
-                .enum(["js", "js_zh", "python"])
-                .describe("文档语言：js | js_zh | python"),
-        },
-    }, async ({ language }) => {
-        const active = (0, docs_service_1.setCurrentDocsLanguage)(language);
-        const docsDir = (0, docs_service_1.getDocsDirByLanguage)(active);
-        return (0, tool_utils_1.createTextToolResult)(`文档语言已切换为 ${active} (${types_1.DOC_LANGUAGE_LABELS[active]})\n目录: ${docsDir}`);
+        return (0, tool_utils_1.createTextToolResult)(formatDocsPathsText());
     });
     server.registerTool("list_api_docs", {
         title: "List API Docs",
-        description: "列出当前（或指定）语言下可用的 API 文档。",
+        description: "列出指定语言下可用的 API 文档；不传 language 时默认 js_zh。",
         inputSchema: {
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
-        const lines = docs.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index));
+        const lines = docs.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index, doc.filePath));
         return (0, tool_utils_1.createTextToolResult)(lines.length === 0
-            ? `当前语言 ${activeLanguage} 下没有可用文档。`
+            ? `文档语言 ${activeLanguage} 下没有可用文档。`
             : [
-                `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
                 "",
                 ...lines,
             ].join("\n"));
     });
     server.registerTool("search_api_docs", {
         title: "Search API Docs",
-        description: "在当前（或指定）语言文档中按关键字搜索。",
+        description: "在指定语言文档中按关键字搜索；不传 language 时默认 js_zh。",
         inputSchema: {
             query: z.string().min(1).describe("搜索关键字"),
             limit: z
@@ -167,10 +107,10 @@ function registerDocTools(server) {
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ query, limit, language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
         const normalizedQuery = query.toLowerCase();
         const matches = docs
@@ -180,31 +120,38 @@ function registerDocTools(server) {
             .slice(0, limit)
             .map((item) => item.doc);
         const text = matches.length === 0
-            ? `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})\n未找到与 "${query}" 匹配的文档。`
+            ? `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})\n未找到与 "${query}" 匹配的文档。`
             : [
-                `当前语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
+                `文档语言: ${activeLanguage} (${types_1.DOC_LANGUAGE_LABELS[activeLanguage]})`,
                 "",
-                ...matches.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index)),
+                ...matches.map((doc, index) => (0, tool_utils_1.formatApiDocSummary)(activeLanguage, doc.title, doc.slug, index, doc.filePath)),
             ].join("\n");
         return (0, tool_utils_1.createTextToolResult)(text);
     });
     server.registerTool("read_api_doc", {
         title: "Read API Doc",
-        description: "读取当前（或指定）语言下某个文档的完整 markdown 内容。",
+        description: "读取指定语言下某个文档的完整 markdown 内容；不传 language 时默认 js_zh。",
         inputSchema: {
             slug: z.string().min(1).describe("文档 slug（文件名，不含 .md）"),
             language: z
                 .enum(["js", "js_zh", "python"])
                 .optional()
-                .describe("可选语言，不传则使用当前语言"),
+                .describe("可选语言，不传默认 js_zh"),
         },
     }, async ({ slug, language }) => {
-        const activeLanguage = (0, docs_service_1.resolveDocsLanguage)(language);
+        const activeLanguage = language ?? "js_zh";
         const docs = await (0, docs_service_1.getApiDocsByLanguage)(activeLanguage);
         const target = docs.find((doc) => doc.slug === slug);
         if (!target) {
             return (0, tool_utils_1.createTextToolResult)(`未找到文档 ${slug}.md（语言: ${activeLanguage}）。`, true);
         }
-        return (0, tool_utils_1.createTextToolResult)(`标题: ${target.title}\n语言: ${activeLanguage}\nURI: ${(0, docs_service_1.getDocUri)(activeLanguage, target.slug)}\n\n${target.content}`);
+        return (0, tool_utils_1.createTextToolResult)([
+            `标题: ${target.title}`,
+            `语言: ${activeLanguage}`,
+            `URI: ${(0, docs_service_1.getDocUri)(activeLanguage, target.slug)}`,
+            `path: ${target.filePath}`,
+            "",
+            target.content,
+        ].join("\n"));
     });
 }