@next-open-ai/openbot 0.6.8 → 0.6.16

package/dist/core/mcp/index.d.ts

@@ -3,16 +3,18 @@
  * 配置在创建 Session 时通过 options.mcpServers 传入，与 Skill 类似。
  */
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
-import type { McpServerConfig } from "./types.js";
-export type { McpServerConfig, McpServerConfigStdio, McpServerConfigSse, McpTool } from "./types.js";
-export { resolveMcpServersForSession, stdioConfigKey, sseConfigKey, mcpConfigKey } from "./config.js";
+import type { McpServerConfig, McpServersStandardFormat } from "./types.js";
+export type { McpServerConfig, McpServerConfigStdio, McpServerConfigSse, McpServerConfigStandardEntry, McpServersStandardFormat, McpTool, } from "./types.js";
+export { resolveMcpServersForSession, standardFormatToArray, arrayToStandardFormat, stdioConfigKey, sseConfigKey, mcpConfigKey, } from "./config.js";
 export { McpClient } from "./client.js";
-export { getMcpToolDefinitions, shutdownMcpClients } from "./operator.js";
+export { getMcpToolDefinitions, shutdownMcpClients, type GetMcpToolDefinitionsOptions } from "./operator.js";
 export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js";
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
- * 在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export declare function createMcpToolsForSession(options: {
-    mcpServers?: McpServerConfig[];
+    mcpServers?: McpServerConfig[] | McpServersStandardFormat;
+    sessionId?: string;
 }): Promise<ToolDefinition[]>;

package/dist/core/mcp/index.js

@@ -4,17 +4,20 @@
  */
 import { resolveMcpServersForSession } from "./config.js";
 import { getMcpToolDefinitions } from "./operator.js";
-export { resolveMcpServersForSession, stdioConfigKey, sseConfigKey, mcpConfigKey } from "./config.js";
+export { resolveMcpServersForSession, standardFormatToArray, arrayToStandardFormat, stdioConfigKey, sseConfigKey, mcpConfigKey, } from "./config.js";
 export { McpClient } from "./client.js";
 export { getMcpToolDefinitions, shutdownMcpClients } from "./operator.js";
 export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js";
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
- * 在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export async function createMcpToolsForSession(options) {
     const configs = resolveMcpServersForSession(options.mcpServers);
     if (configs.length === 0)
         return [];
-    return getMcpToolDefinitions(configs);
+    return getMcpToolDefinitions(configs, {
+        sessionId: options.sessionId,
+    });
 }

package/dist/core/mcp/operator.d.ts

@@ -4,11 +4,26 @@
  */
 import type { McpServerConfig } from "./types.js";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/** getMcpToolDefinitions 的可选参数：超时、重试与 sessionId（用于经 sendSessionMessage 推送进度） */
+export interface GetMcpToolDefinitionsOptions {
+    /** 连接或 list_tools 失败时的重试次数（不含首次，默认 1） */
+    connectRetries?: number;
+    /** 重试间隔（毫秒，默认 3000） */
+    retryDelayMs?: number;
+    /** stdio 初始化超时（毫秒） */
+    initTimeoutMs?: number;
+    /** stdio 初始化重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
+    /** 会话 ID，用于经全局 sendSessionMessage 推送 MCP 进度系统消息 */
+    sessionId?: string;
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[]): Promise<ToolDefinition[]>;
+export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[], options?: GetMcpToolDefinitionsOptions): Promise<ToolDefinition[]>;
 /**
  * 关闭并移除所有缓存的 MCP 客户端（进程退出或显式清理时调用）。
  */

package/dist/core/mcp/operator.js

@@ -5,6 +5,7 @@
 import { mcpConfigKey } from "./config.js";
 import { McpClient } from "./client.js";
 import { mcpToolsToToolDefinitions } from "./adapter.js";
+import { sendSessionMessage } from "../session-outlet/index.js";
 /** 按配置键缓存的客户端 */
 const clientCache = new Map();
 function configLabel(config) {
@@ -12,53 +13,119 @@ function configLabel(config) {
         return config.command;
     return config.url;
 }
+/** 用于系统消息展示的 MCP 名称：stdio 优先用首参（如 akshare-tools），否则 command；sse 用 URL 主机或路径末段 */
+function mcpDisplayName(config) {
+    if (config.transport === "stdio") {
+        const args = config.args;
+        const first = args?.[0];
+        if (typeof first === "string" && first.trim() && !first.includes("/") && !first.includes("\\")) {
+            return first.trim();
+        }
+        return config.command;
+    }
+    try {
+        const u = new URL(config.url);
+        const host = u.hostname || u.pathname?.replace(/\/$/, "").split("/").pop() || "MCP";
+        return host;
+    }
+    catch {
+        return config.url;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export async function getMcpToolDefinitions(serverConfigs) {
+export async function getMcpToolDefinitions(serverConfigs, options = {}) {
+    const connectRetries = options.connectRetries ?? 1;
+    const retryDelayMs = options.retryDelayMs ?? 3_000;
+    const sessionId = options.sessionId;
+    const clientOptions = {
+        initTimeoutMs: options.initTimeoutMs,
+        initRetries: options.initRetries,
+        initRetryDelayMs: options.initRetryDelayMs,
+    };
+    const emitProgress = (displayMessage, phase, detail) => {
+        if (sessionId) {
+            sendSessionMessage(sessionId, {
+                type: "system",
+                code: "mcp.progress",
+                payload: { phase, message: displayMessage, serverLabel: detail },
+            });
+        }
+    };
     const allTools = [];
     for (let i = 0; i < serverConfigs.length; i++) {
         const config = serverConfigs[i];
         const key = mcpConfigKey(config);
+        const label = configLabel(config);
+        const displayName = mcpDisplayName(config);
         let client = clientCache.get(key);
-        if (!client) {
-            client = new McpClient(config);
-            try {
-                await client.connect();
-                clientCache.set(key, client);
+        if (!client || !client.isConnected) {
+            if (client) {
+                clientCache.delete(key);
+                try {
+                    await client.close();
+                }
+                catch { }
             }
-            catch (err) {
-                console.warn(`[mcp] 连接失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+            emitProgress(`${displayName} MCP connecting`, "connecting");
+            let connected = false;
+            for (let attempt = 0; attempt <= connectRetries; attempt++) {
+                if (attempt > 0) {
+                    emitProgress(`${displayName} MCP retrying (${attempt + 1}/${connectRetries + 1})`, "retrying", "connect");
+                    await sleep(retryDelayMs);
+                }
+                try {
+                    client = new McpClient(config, clientOptions);
+                    await client.connect();
+                    clientCache.set(key, client);
+                    connected = true;
+                    emitProgress(`${displayName} MCP ready`, "ready");
+                    break;
+                }
+                catch (err) {
+                    if (client)
+                        try {
+                            await client.close();
+                        }
+                        catch { }
+                    if (attempt === connectRetries) {
+                        console.warn(`[mcp] 连接失败 (${label}):`, err instanceof Error ? err.message : err);
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        emitProgress(`${displayName} MCP failed: ${errMsg}`, "skipped", errMsg);
+                    }
+                }
             }
+            if (!connected)
+                continue;
         }
-        if (!client.isConnected) {
-            clientCache.delete(key);
-            try {
-                await client.close();
+        client = clientCache.get(key);
+        let toolsListed = false;
+        for (let attempt = 0; attempt <= connectRetries; attempt++) {
+            if (attempt > 0) {
+                emitProgress(`${displayName} MCP retrying list tools (${attempt + 1}/${connectRetries + 1})`, "retrying", "list_tools");
+                await sleep(retryDelayMs);
             }
-            catch { }
-            const newClient = new McpClient(config);
             try {
-                await newClient.connect();
-                clientCache.set(key, newClient);
-                client = newClient;
+                const tools = await client.listTools();
+                const serverId = `mcp${i}`;
+                const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
+                allTools.push(...definitions);
+                toolsListed = true;
+                break;
             }
             catch (err) {
-                console.warn(`[mcp] 重连失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+                if (attempt === connectRetries) {
+                    console.warn(`[mcp] list_tools 失败 (${label}):`, err instanceof Error ? err.message : err);
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    emitProgress(`${displayName} MCP list tools failed: ${errMsg}`, "skipped", errMsg);
+                }
             }
         }
-        try {
-            const tools = await client.listTools();
-            const serverId = `mcp${i}`;
-            const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
-            allTools.push(...definitions);
-        }
-        catch (err) {
-            console.warn(`[mcp] list_tools 失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-        }
     }
     return allTools;
 }

package/dist/core/mcp/transport/index.d.ts

@@ -2,6 +2,10 @@ import type { McpServerConfig, IMcpTransport } from "../types.js";
 export interface TransportOptions {
     initTimeoutMs?: number;
     requestTimeoutMs?: number;
+    /** stdio：初始化失败时的重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio：初始化重试间隔毫秒（默认 3000） */
+    initRetryDelayMs?: number;
 }
 /**
  * 根据配置创建对应的传输层实例。

package/dist/core/mcp/transport/index.js

@@ -5,7 +5,12 @@ import { SseTransport } from "./sse.js";
  */
 export function createTransport(config, options) {
     if (config.transport === "stdio") {
-        return new StdioTransport(config, options);
+        return new StdioTransport(config, {
+            initTimeoutMs: options?.initTimeoutMs,
+            requestTimeoutMs: options?.requestTimeoutMs,
+            initRetries: options?.initRetries,
+            initRetryDelayMs: options?.initRetryDelayMs,
+        });
     }
     if (config.transport === "sse") {
         return new SseTransport(config, options);

package/dist/core/mcp/transport/stdio.d.ts

@@ -8,12 +8,18 @@ export interface StdioTransportOptions {
     initTimeoutMs?: number;
     /** 单次请求超时（毫秒） */
     requestTimeoutMs?: number;
+    /** 初始化失败时的重试次数（不含首次，默认 1，即最多 2 次尝试） */
+    initRetries?: number;
+    /** 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
 }
 export declare class StdioTransport {
     private process;
     private config;
     private initTimeoutMs;
     private requestTimeoutMs;
+    private initRetries;
+    private initRetryDelayMs;
     private nextId;
     private pending;
     private buffer;

package/dist/core/mcp/transport/stdio.js

@@ -8,6 +8,8 @@ export class StdioTransport {
     config;
     initTimeoutMs;
     requestTimeoutMs;
+    initRetries;
+    initRetryDelayMs;
     nextId = 1;
     pending = new Map();
     buffer = "";
@@ -15,6 +17,8 @@ export class StdioTransport {
         this.config = config;
         this.initTimeoutMs = options.initTimeoutMs ?? 10_000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.initRetries = options.initRetries ?? 1;
+        this.initRetryDelayMs = options.initRetryDelayMs ?? 3_000;
     }
     /** 启动子进程并完成 MCP initialize 握手 */
     async start() {
@@ -43,7 +47,24 @@ export class StdioTransport {
             this.rejectAll(new Error(`MCP process exited: code=${code} signal=${signal}`));
             this.process = null;
         });
-        await this.initialize();
+        const maxAttempts = 1 + this.initRetries;
+        let lastErr = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await this.initialize();
+                lastErr = null;
+                break;
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e : new Error(String(e));
+                const isTransient = lastErr.message.includes("timeout") || lastErr.message.includes("MCP process exited");
+                if (!isTransient || attempt >= maxAttempts) {
+                    throw lastErr;
+                }
+                console.warn(`[mcp stdio] initialize 超时或失败，${this.initRetryDelayMs}ms 后重试 (${attempt}/${maxAttempts}):`, lastErr.message);
+                await new Promise((r) => setTimeout(r, this.initRetryDelayMs));
+            }
+        }
     }
     flushLines() {
         const lines = this.buffer.split("\n");

package/dist/core/mcp/types.d.ts

@@ -22,6 +22,24 @@ export interface McpServerConfigSse {
 }
 /** 单条 MCP 服务器配置（由调用方在创建 Session 时传入，与 Skill 类似） */
 export type McpServerConfig = McpServerConfigStdio | McpServerConfigSse;
+/**
+ * 标准 JSON 格式中的单条 MCP 配置（无 transport，由 command/url 推断）。
+ * 与 Claude/Anthropic 等生态常用格式一致。
+ */
+export interface McpServerConfigStandardEntry {
+    /** stdio：可执行命令 */
+    command?: string;
+    /** stdio：命令行参数 */
+    args?: string[];
+    /** stdio：环境变量 */
+    env?: Record<string, string>;
+    /** sse：远程服务地址 */
+    url?: string;
+    /** sse：请求头 */
+    headers?: Record<string, string>;
+}
+/** 标准 JSON 格式：mcpServers 为对象，key 为服务器名称 */
+export type McpServersStandardFormat = Record<string, McpServerConfigStandardEntry>;
 /** MCP 协议中 Tool 的 inputSchema 为 JSON Schema 对象 */
 export interface McpToolInputSchema {
     type?: string;

package/dist/core/memory/compaction-extension.d.ts

@@ -1,6 +1,7 @@
 import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
 /**
- * 创建用于在 session_compact 事件时把 compaction summary 写入向量库的 extension factory。
- * 在 AgentSession 发生 compaction（自动或手动）后触发，无需等到关闭会话。
+ * 创建用于在 session_compact 事件时更新「当前 session 最新 compaction」的 extension factory。
+ * 发生 compaction 时只回调 onUpdateLatestCompaction(summary)，由调用方保存；
+ * 向量库写入推迟到 SessionAgent 关闭时由 AgentManager 统一执行。
  */
-export declare function createCompactionMemoryExtensionFactory(sessionId: string): ExtensionFactory;
+export declare function createCompactionMemoryExtensionFactory(_sessionId: string, onUpdateLatestCompaction: (summary: string) => void): ExtensionFactory;

package/dist/core/memory/compaction-extension.js

@@ -1,23 +1,15 @@
-import { addMemory } from "./index.js";
 /**
- * 创建用于在 session_compact 事件时把 compaction summary 写入向量库的 extension factory。
- * 在 AgentSession 发生 compaction（自动或手动）后触发，无需等到关闭会话。
+ * 创建用于在 session_compact 事件时更新「当前 session 最新 compaction」的 extension factory。
+ * 发生 compaction 时只回调 onUpdateLatestCompaction(summary)，由调用方保存；
+ * 向量库写入推迟到 SessionAgent 关闭时由 AgentManager 统一执行。
  */
-export function createCompactionMemoryExtensionFactory(sessionId) {
+export function createCompactionMemoryExtensionFactory(_sessionId, onUpdateLatestCompaction) {
     return (pi) => {
-        pi.on("session_compact", async (event) => {
+        pi.on("session_compact", (event) => {
             const summary = event.compactionEntry?.summary?.trim();
             if (!summary)
                 return;
-            try {
-                await addMemory(summary, {
-                    infotype: "compaction",
-                    sessionId,
-                });
-            }
-            catch (_) {
-                // 写入失败不打断会话
-            }
+            onUpdateLatestCompaction(summary);
         });
     };
 }

package/dist/core/memory/embedding-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Embedding 抽象：便于后续切换不同实现（在线 OpenAPI、node-llama-cpp GGUF 等）。
+ * 调用方仅依赖 embed(text) => Promise<number[] | null>。
+ */
+export interface IEmbeddingProvider {
+    /** 单条文本向量化，不可用时返回 null */
+    embed(text: string): Promise<number[] | null>;
+    /** 提供方名称，用于日志 */
+    readonly name: string;
+}

package/dist/core/memory/embedding-types.js

@@ -0,0 +1,5 @@
+/**
+ * Embedding 抽象：便于后续切换不同实现（在线 OpenAPI、node-llama-cpp GGUF 等）。
+ * 调用方仅依赖 embed(text) => Promise<number[] | null>。
+ */
+export {};

package/dist/core/memory/embedding.d.ts

@@ -1,4 +1,5 @@
 /**
- * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ * 对单条文本做 embedding。
+ * 未配置在线或在线连接失败时使用本地 embedding；均不可用时返回 null（仅首次打日志）。
  */
 export declare function embed(text: string): Promise<number[] | null>;

package/dist/core/memory/embedding.js

@@ -1,15 +1,47 @@
 /**
- * 文本 embedding：使用 config.json 中配置的远端 RAG embedding 模型。
- * 未配置时返回 null，调用方（长记忆）空转。
+ * 文本 embedding 统一入口（供 memory 向量库等使用）。
+ *
+ * 使用逻辑：
+ * - 未配置在线 embedding：直接使用本地 embedding（GGUF）。
+ * - 已配置在线 embedding：先尝试在线；若请求失败（无法连接、超时、返回错误等），则回退到本地 embedding。
+ * - 本地也不可用时返回 null，长记忆空转。
  */
 import { getRagEmbeddingConfigSync } from "../config/desktop-config.js";
 import { embedRemote } from "./remote-embedding.js";
+import { getLocalEmbeddingProvider, getLocalEmbeddingUnavailableReason } from "./local-embedding.js";
+let fallbackLogged = false;
+let unavailableLogged = false;
 /**
- * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ * 对单条文本做 embedding。
+ * 未配置在线或在线连接失败时使用本地 embedding；均不可用时返回 null（仅首次打日志）。
  */
 export async function embed(text) {
     const config = getRagEmbeddingConfigSync();
-    if (!config)
-        return null;
-    return embedRemote(text, config);
+    if (config) {
+        try {
+            const vec = await embedRemote(text, config);
+            if (Array.isArray(vec) && vec.length > 0)
+                return vec;
+        }
+        catch {
+            // 配置了在线但请求失败（无法连接等），下面使用本地
+        }
+        if (!fallbackLogged) {
+            fallbackLogged = true;
+            console.warn("[RAG embedding] 在线模型不可用，已切换至本地模型（GGUF）");
+        }
+    }
+    const local = await getLocalEmbeddingProvider();
+    if (local) {
+        const vec = await local.embed(text);
+        if (Array.isArray(vec) && vec.length > 0)
+            return vec;
+    }
+    if (!unavailableLogged) {
+        unavailableLogged = true;
+        const reason = getLocalEmbeddingUnavailableReason();
+        const reasonSuffix = reason ? ` 原因: ${reason}` : "（若为首次加载，请先执行 npm run build 后重启桌面端以查看具体原因）";
+        console.warn("[RAG embedding] 本地模型也不可用，长记忆将空转。" + reasonSuffix);
+    }
+    return null;
 }

package/dist/core/memory/index.js

@@ -26,6 +26,9 @@ export async function addMemory(text, metadata) {
         createdAt: new Date().toISOString(),
     };
     await addToStore(id, vec, text, meta);
+    if (metadata.infotype === "experience") {
+        console.log(`[Memory] 经验已写入向量库 sessionId=${metadata.sessionId} id=${id}`);
+    }
     return id;
 }
 /**

package/dist/core/memory/local-embedding-llama.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 本地 embedding（Electron 主进程）：node-llama-cpp + GGUF。
+ * 需在安装依赖后对 Electron 的 Node ABI 执行 electron-rebuild（见 apps/desktop 的 rebuild:native）。
+ * 加载前会注册 ESM 钩子，将 "typescript" 解析为桩模块，避免依赖链加载 typescript.js（含 with 语句，ESM 下报错）。
+ */
+import type { IEmbeddingProvider } from "./embedding-types.js";
+export declare function getLocalEmbeddingLlamaUnavailableReason(): string | null;
+/**
+ * 获取基于 node-llama-cpp + GGUF 的本地 embedding 提供方。
+ * 仅在可解析到 node-llama-cpp 且模型可加载时返回，否则返回 null。
+ * @param modelPath 配置的 GGUF 路径或 hf: URI，为空时使用 DEFAULT_GGUF_MODEL
+ */
+export declare function getLocalEmbeddingLlamaProvider(modelPath: string | null): Promise<IEmbeddingProvider | null>;

package/dist/core/memory/local-embedding-llama.js

@@ -0,0 +1,76 @@
+import { join } from "path";
+import { homedir } from "os";
+let cached = null;
+let initError = null;
+let lastQueryError = null;
+export function getLocalEmbeddingLlamaUnavailableReason() {
+    return initError?.message ?? lastQueryError ?? null;
+}
+function L2Normalize(vec) {
+    let sum = 0;
+    for (let i = 0; i < vec.length; i++)
+        sum += vec[i] * vec[i];
+    const norm = Math.sqrt(sum) || 1;
+    return vec.map((x) => x / norm);
+}
+/** 默认 GGUF embedding 模型（与 moltbot 一致），首次使用会按 node-llama-cpp 规则下载到缓存 */
+const DEFAULT_GGUF_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+/**
+ * 获取基于 node-llama-cpp + GGUF 的本地 embedding 提供方。
+ * 仅在可解析到 node-llama-cpp 且模型可加载时返回，否则返回 null。
+ * @param modelPath 配置的 GGUF 路径或 hf: URI，为空时使用 DEFAULT_GGUF_MODEL
+ */
+export async function getLocalEmbeddingLlamaProvider(modelPath) {
+    if (cached)
+        return cached;
+    if (initError)
+        return null;
+    const effectivePath = (modelPath?.trim() || DEFAULT_GGUF_MODEL).trim();
+    try {
+        // Node 20.10+ 才提供 node:module 的 register；Electron 内置 Node 较旧时无此导出，跳过钩子
+        const nodeModule = await import("node:module");
+        if (typeof nodeModule.register === "function") {
+            const loaderUrl = new URL("../../../scripts/ts-stub-loader.mjs", import.meta.url).href;
+            await Promise.resolve(nodeModule.register(loaderUrl, import.meta.url));
+        }
+        const { getLlama, resolveModelFile, LlamaLogLevel } = await import("node-llama-cpp");
+        const llama = await getLlama({ logLevel: LlamaLogLevel.error });
+        const cacheDir = join(homedir(), ".cache", "llama");
+        const resolved = await resolveModelFile(effectivePath, cacheDir);
+        const model = await llama.loadModel({ modelPath: resolved });
+        const embeddingCtx = await model.createEmbeddingContext();
+        const provider = {
+            name: "llama-gguf",
+            async embed(text) {
+                try {
+                    const embedding = await embeddingCtx.getEmbeddingFor(text);
+                    const vec = Array.from(embedding.vector);
+                    if (vec.length === 0) {
+                        lastQueryError = "getEmbeddingFor 返回空向量";
+                        return null;
+                    }
+                    return L2Normalize(vec);
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    lastQueryError = `llama embed 失败: ${err.message}`;
+                    console.warn("[RAG embedding] node-llama-cpp embed 失败:", err.message);
+                    return null;
+                }
+            },
+        };
+        cached = provider;
+        return provider;
+    }
+    catch (e) {
+        initError = e instanceof Error ? e : new Error(String(e));
+        console.warn("[RAG embedding] node-llama-cpp (GGUF) 不可用，原因:", initError.message);
+        if (initError.stack) {
+            console.warn("[RAG embedding] GGUF 加载失败堆栈:\n", initError.stack);
+        }
+        if (initError.message.includes("Unexpected token 'with'")) {
+            console.warn("[RAG embedding] 提示: 依赖链中某包在 ESM 下使用了禁止的 with 语句（如 typescript.js）。可配置在线 RAG 或升级 Electron 至 Node 22+。");
+        }
+        return null;
+    }
+}

package/dist/core/memory/local-embedding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 本地 embedding：仅 node-llama-cpp (GGUF)。不可用时返回 null，由上层决定是否使用在线 RAG。
+ */
+import type { IEmbeddingProvider } from "./embedding-types.js";
+export declare function getLocalEmbeddingUnavailableReason(): string | null;
+/**
+ * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
+ * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ */
+export declare function getLocalEmbeddingProvider(): Promise<IEmbeddingProvider | null>;

package/dist/core/memory/local-embedding.js

@@ -0,0 +1,29 @@
+import { getRagLocalModelPathSync } from "../config/desktop-config.js";
+import { getLocalEmbeddingLlamaProvider, getLocalEmbeddingLlamaUnavailableReason, } from "./local-embedding-llama.js";
+let cached = null;
+let envLogged = false;
+export function getLocalEmbeddingUnavailableReason() {
+    return getLocalEmbeddingLlamaUnavailableReason();
+}
+/**
+ * 获取本地 embedding 提供方（懒加载，失败后不再重试）。
+ * 仅使用 node-llama-cpp (GGUF)。不可用时返回 null。
+ */
+export async function getLocalEmbeddingProvider() {
+    if (cached)
+        return cached;
+    const provider = await getLocalEmbeddingLlamaProvider(getRagLocalModelPathSync());
+    if (provider) {
+        cached = provider;
+        if (!envLogged) {
+            envLogged = true;
+            console.warn("[RAG embedding] 本地模型使用 node-llama-cpp (GGUF)");
+        }
+        return cached;
+    }
+    if (!envLogged) {
+        envLogged = true;
+        console.warn("[RAG embedding] 本地模型不可用，长记忆将空转。可配置 RAG 在线模型或检查 GGUF 报错。");
+    }
+    return null;
+}

package/dist/core/memory/persist-compaction-on-close.d.ts

@@ -0,0 +1,14 @@
+export type AddMemoryCompaction = (text: string, meta: {
+    infotype: "compaction";
+    sessionId: string;
+}) => Promise<unknown>;
+/**
+ * 将 map 中指定 compositeKey 的 summary 写入 addMemory 并从 map 删除；用于 Session 关闭前。
+ * 写入采用 fire-and-forget，不阻塞调用方，避免 agent.chat 等请求被 addMemory/embed 拖住导致无回复。
+ */
+export declare function persistStoredCompactionForSession(sessionLatestCompactionSummary: Map<string, string>, compositeKey: string, addMemory: AddMemoryCompaction): Promise<void>;
+/**
+ * 将 map 中所有给定 keys（需以 sessionId + "::" 为前缀）的 summary 依次写入 addMemory 并删除；用于按业务 sessionId 关闭时。
+ * 写入采用 fire-and-forget，不阻塞调用方。
+ */
+export declare function persistStoredCompactionForBusinessSession(sessionLatestCompactionSummary: Map<string, string>, keysToProcess: string[], sessionId: string, addMemory: AddMemoryCompaction): Promise<void>;