@next-open-ai/openclawx 0.8.40 → 0.8.58

package/dist/core/config/desktop-config.js

@@ -209,8 +209,8 @@ export async function loadDesktopAgentConfig(agentId) {
         }
     }
     const resolvedAgentId = agentId === "default" ? "default" : agentId;
-    let provider = config.defaultProvider ?? "deepseek";
-    let model = config.defaultModel ?? "deepseek-chat";
+    let provider = config.defaultProvider ?? "ollama";
+    let model = config.defaultModel ?? "qwen3:4b";
     if (config.defaultModelItemCode && Array.isArray(config.configuredModels)) {
         const configured = config.configuredModels.find((m) => m.modelItemCode === config.defaultModelItemCode);
         if (configured) {
@@ -218,11 +218,14 @@ export async function loadDesktopAgentConfig(agentId) {
             model = configured.modelId;
         }
     }
+    /** 是否从当前智能体自己的配置得到了模型（有 modelItemCode 或 provider/model）；若否，则使用的是全局默认 */
+    let agentHadOwnModel = false;
     let workspaceName = resolvedAgentId;
     let mcpServers;
     let mcpMaxResultTokens;
     let systemPrompt;
     let useLongMemory = true;
+    let contextSize;
     if (existsSync(agentsPath)) {
         try {
             const raw = await readFile(agentsPath, "utf-8");
@@ -237,6 +240,9 @@ export async function loadDesktopAgentConfig(agentId) {
                 if (agent.mcpMaxResultTokens != null && typeof agent.mcpMaxResultTokens === "number" && agent.mcpMaxResultTokens > 0) {
                     mcpMaxResultTokens = agent.mcpMaxResultTokens;
                 }
+                if (agent.contextSize != null && typeof agent.contextSize === "number" && agent.contextSize > 0) {
+                    contextSize = agent.contextSize;
+                }
                 if (agent.mcpServers != null) {
                     if (Array.isArray(agent.mcpServers) || (typeof agent.mcpServers === "object" && !Array.isArray(agent.mcpServers))) {
                         mcpServers = agent.mcpServers;
@@ -252,19 +258,28 @@ export async function loadDesktopAgentConfig(agentId) {
                     if (configured) {
                         provider = configured.provider;
                         model = configured.modelId;
+                        agentHadOwnModel = true;
                     }
                     else {
-                        if (agent.provider)
+                        if (agent.provider) {
                             provider = agent.provider;
-                        if (agent.model)
+                            agentHadOwnModel = true;
+                        }
+                        if (agent.model) {
                             model = agent.model;
+                            agentHadOwnModel = true;
+                        }
                     }
                 }
                 else {
-                    if (agent.provider)
+                    if (agent.provider) {
                         provider = agent.provider;
-                    if (agent.model)
+                        agentHadOwnModel = true;
+                    }
+                    if (agent.model) {
                         model = agent.model;
+                        agentHadOwnModel = true;
+                    }
                 }
             }
         }
@@ -272,6 +287,11 @@ export async function loadDesktopAgentConfig(agentId) {
             // ignore
         }
     }
+    // 本地 LLM 可用且当前智能体未配置自己的模型时，使用本地推理作为缺省，使所有智能体“拥有”该配置
+    if (!agentHadOwnModel && process.env.LOCAL_LLM_BASE_URL?.trim()) {
+        provider = "local";
+        model = "local-llm";
+    }
     const provConfig = config.providers?.[provider];
     const apiKey = provConfig?.apiKey && typeof provConfig.apiKey === "string" && provConfig.apiKey.trim()
         ? provConfig.apiKey.trim()
@@ -427,6 +447,7 @@ export async function loadDesktopAgentConfig(agentId) {
         claudeCode,
         useLongMemory,
         webSearch,
+        contextSize,
     };
 }
 function ensureDesktopDir() {
@@ -624,22 +645,54 @@ export async function ensureProviderSupportFile() {
         await writeFile(path, JSON.stringify(presetProviders, null, 2), "utf-8");
     }
 }
-/** 若 config.json 不存在则用 preset-config.json 初始化，若存在则浅合并补充新基础键值 */
+/** 预装本地推理缺省：推荐列表第一个 LLM（Qwen3-4B）对应的本地文件名，与 modelUriToFilename 一致 */
+const DEFAULT_LOCAL_LLM_MODEL_ID = "hf_Qwen_Qwen3-4B-GGUF_Qwen3-4B-Q4_K_M.gguf";
+const DEFAULT_LOCAL_MODEL_ITEM_CODE = "local-qwen3-4b";
+/** 代码内建默认：local provider + 本地 Qwen3-4B，首次与合并时优先保证存在 */
+const BUILTIN_DEFAULT_CONFIG = {
+    defaultProvider: "local",
+    defaultModel: DEFAULT_LOCAL_LLM_MODEL_ID,
+    defaultModelItemCode: DEFAULT_LOCAL_MODEL_ITEM_CODE,
+    defaultAgentId: DEFAULT_AGENT_ID,
+    maxAgentSessions: DEFAULT_MAX_AGENT_SESSIONS,
+    providers: {
+        local: { baseUrl: "http://127.0.0.1:11435/v1" },
+    },
+    configuredModels: [
+        {
+            provider: "local",
+            modelId: DEFAULT_LOCAL_LLM_MODEL_ID,
+            type: "llm",
+            alias: "Qwen3 4B Q4_K_M",
+            modelItemCode: DEFAULT_LOCAL_MODEL_ITEM_CODE,
+        },
+        {
+            provider: "local",
+            modelId: "hf_ggml-org_embeddinggemma-300M-GGUF_embeddinggemma-300M-Q8_0.gguf",
+            type: "embedding",
+            alias: "EmbeddingGemma 300M Q8 (768维)",
+            modelItemCode: "local-embeddinggemma-300m",
+        },
+    ],
+};
+/** 若 config.json 不存在则用 preset-config.json 初始化，若存在则浅合并补充新基础键值。预装 local provider + 本地 Qwen3-4B 模型并设为缺省；preset 与代码默认合并，保证 local 一定存在。 */
 async function ensureConfigJsonInitialized() {
     const presetPath = join(getPresetsDir(), "preset-config.json");
-    let presetConfig = {
-        defaultProvider: "deepseek",
-        defaultModel: "deepseek-chat",
-        defaultAgentId: DEFAULT_AGENT_ID,
-        maxAgentSessions: DEFAULT_MAX_AGENT_SESSIONS,
-        providers: {},
-        configuredModels: [],
-    };
+    let presetConfig = { ...BUILTIN_DEFAULT_CONFIG };
     if (existsSync(presetPath)) {
         try {
             const data = JSON.parse(await readFile(presetPath, "utf-8"));
-            if (data.config)
-                presetConfig = data.config;
+            if (data.config && typeof data.config === "object") {
+                presetConfig = { ...BUILTIN_DEFAULT_CONFIG, ...data.config };
+                presetConfig.providers = { ...BUILTIN_DEFAULT_CONFIG.providers, ...(presetConfig.providers || {}) };
+                const hasLocalModel = (presetConfig.configuredModels || []).some((m) => m?.provider === "local" && (m?.modelId === DEFAULT_LOCAL_LLM_MODEL_ID || m?.modelItemCode === DEFAULT_LOCAL_MODEL_ITEM_CODE));
+                if (!hasLocalModel) {
+                    presetConfig.configuredModels = [
+                        ...(BUILTIN_DEFAULT_CONFIG.configuredModels || []),
+                        ...(presetConfig.configuredModels || []),
+                    ];
+                }
+            }
         }
         catch { }
     }
@@ -708,18 +761,46 @@ async function ensureAgentsJsonInitialized() {
             }
         }
     }
+    // 所有未单独配置模型的智能体使用 config 的缺省模型（预装为 local + Qwen3-4B）
+    const configPath = join(getDesktopDir(), "config.json");
+    if (existsSync(configPath)) {
+        try {
+            const configRaw = await readFile(configPath, "utf-8");
+            const configData = JSON.parse(configRaw);
+            const defProvider = configData.defaultProvider?.trim();
+            const defModel = configData.defaultModel?.trim();
+            const defCode = configData.defaultModelItemCode?.trim();
+            if (defProvider && defModel) {
+                for (const agent of currentData.agents) {
+                    const hasOwn = (agent.provider && String(agent.provider).trim()) || (agent.model && String(agent.model).trim()) || (agent.modelItemCode && String(agent.modelItemCode).trim());
+                    if (!hasOwn) {
+                        agent.provider = defProvider;
+                        agent.model = defModel;
+                        if (defCode)
+                            agent.modelItemCode = defCode;
+                        changed = true;
+                    }
+                }
+            }
+        }
+        catch { /* ignore */ }
+    }
     if (changed || !existsSync(agentsPath)) {
         await writeFile(agentsPath, JSON.stringify(currentData, null, 2), "utf-8");
     }
 }
 /**
- * CLI / Gateway 运行时调用，确保 config.json、provider-support.json、agents.json 均完成初始化。
+ * CLI / Gateway 运行时调用，确保 config.json、provider-support.json、agents.json 均完成初始化，
+ * 并同步到 agent 目录 models.json，供 pi ModelRegistry 解析 local 等模型与凭证。
  */
 export async function ensureDesktopConfigInitialized() {
     ensureDesktopDir();
     await ensureProviderSupportFile();
     await ensureConfigJsonInitialized();
     await ensureAgentsJsonInitialized();
+    await syncDesktopConfigToModelsJson().catch((err) => {
+        console.warn("[ensureDesktopConfigInitialized] syncDesktopConfigToModelsJson failed:", err);
+    });
 }
 /**
  * 取某 provider 在 provider-support 中的第一个 llm 模型 id；若无则返回第一个模型 id。
@@ -770,6 +851,10 @@ const SYNC_DEFAULTS = {
     "openai-custom": { baseUrl: "", apiKey: "OPENAI_API_KEY", api: "openai-completions" },
     nvidia: { baseUrl: "https://integrate.api.nvidia.com/v1", apiKey: "NVIDIA_API_KEY", api: "openai-completions" },
     kimi: { baseUrl: "https://api.moonshot.cn/v1", apiKey: "MOONSHOT_API_KEY", api: "openai-completions" },
+    /** 本地 Ollama，无需真实 API Key */
+    ollama: { baseUrl: "http://localhost:11434/v1", apiKey: "OPENAI_API_KEY", api: "openai-completions" },
+    /** 内置本地推理（node-llama-cpp），无需 API Key，baseUrl 指向本地子进程服务 */
+    local: { baseUrl: "http://127.0.0.1:11435/v1", apiKey: "OPENAI_API_KEY", api: "openai-completions" },
 };
 const DEFAULT_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 const DEFAULT_CONTEXT_WINDOW = 64000;
@@ -806,10 +891,12 @@ export async function syncDesktopConfigToModelsJson() {
     const support = await getProviderSupport();
     const piProviders = {};
     for (const [providerId, userConfig] of Object.entries(configured)) {
-        if (!userConfig?.apiKey?.trim())
+        // ollama / local 不需要 API Key，其他 provider 必须有 apiKey
+        const isNoKeyProvider = providerId === "ollama" || providerId === "local";
+        if (!isNoKeyProvider && !userConfig?.apiKey?.trim())
             continue;
         const defaults = SYNC_DEFAULTS[providerId] ?? { baseUrl: "", apiKey: "OPENAI_API_KEY", api: "openai-completions" };
-        const baseUrl = userConfig.baseUrl?.trim() || (support[providerId]?.baseUrl ?? "").trim() || defaults.baseUrl;
+        const baseUrl = userConfig?.baseUrl?.trim() || (support[providerId]?.baseUrl ?? "").trim() || defaults.baseUrl;
         if (!baseUrl)
             continue;
         const def = support[providerId];
@@ -839,7 +926,7 @@ export async function syncDesktopConfigToModelsJson() {
             continue;
         }
         piProviders[providerId] = {
-            name: (userConfig.alias?.trim() || def?.name) || providerId,
+            name: (userConfig?.alias?.trim() || def?.name) || providerId,
             apiKey: defaults.apiKey,
             api: defaults.api,
             baseUrl: baseUrl.replace(/\/$/, ""),

package/dist/core/config/provider-support-default.js

@@ -54,4 +54,30 @@ export const DEFAULT_PROVIDER_SUPPORT = {
             { id: "moonshot-v1-128k", name: "Moonshot 128K", types: ["llm"] },
         ],
     },
+    /** 本地 Ollama 服务，兼容 OpenAI API；baseUrl 指向本机 Ollama 默认端口 */
+    ollama: {
+        name: "Ollama (本地)",
+        baseUrl: "http://localhost:11434/v1",
+        models: [
+            { id: "qwen3:4b", name: "Qwen3 4B", types: ["llm"] },
+            { id: "qwen3:8b", name: "Qwen3 8B", types: ["llm"] },
+            { id: "qwen3:14b", name: "Qwen3 14B", types: ["llm"] },
+            { id: "llama3.2:3b", name: "Llama 3.2 3B", types: ["llm"] },
+            { id: "llama3.2:1b", name: "Llama 3.2 1B", types: ["llm"] },
+            { id: "nomic-embed-text", name: "Nomic Embed Text", types: ["embedding"] },
+        ],
+    },
+    /**
+     * 内置本地推理（node-llama-cpp），无需安装 Ollama。
+     * baseUrl 指向本地 LLM 子进程服务；模型列表为推荐的 GGUF 模型，可在本地模型管理页面增删。
+     * 无需 API Key。
+     */
+    local: {
+        name: "本地推理 (node-llama-cpp)",
+        baseUrl: "http://127.0.0.1:11435/v1",
+        models: [
+            { id: "local-llm", name: "本地 LLM（当前加载）", types: ["llm"] },
+            { id: "local-embedding", name: "本地 Embedding（当前加载）", types: ["embedding"] },
+        ],
+    },
 };

package/dist/core/local-llm-server/download-model.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_LLM_MODEL_URI = "hf:Qwen/Qwen3-4B-GGUF/Qwen3-4B-Q4_K_M.gguf";
+export interface DownloadModelOptions {
+    useMirror?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (p: {
+        downloadedSize: number;
+        totalSize: number;
+        percent: number;
+    }) => void;
+}
+/**
+ * 下载模型到本地缓存目录。
+ * @returns 解析后的本地文件路径
+ */
+export declare function downloadModel(modelUri: string, options?: DownloadModelOptions): Promise<string>;
+export declare function getResolvedBasename(modelUri: string): string;

package/dist/core/local-llm-server/download-model.js

@@ -0,0 +1,37 @@
+/**
+ * 本地模型下载（供 CLI 与 Nest LocalModelsService 复用）。
+ * 使用 node-llama-cpp resolveModelFile，缓存目录 ~/.openbot/.cached_models/。
+ */
+import { basename } from "node:path";
+import { LOCAL_LLM_CACHE_DIR } from "./model-resolve.js";
+export const DEFAULT_LLM_MODEL_URI = "hf:Qwen/Qwen3-4B-GGUF/Qwen3-4B-Q4_K_M.gguf";
+/**
+ * 下载模型到本地缓存目录。
+ * @returns 解析后的本地文件路径
+ */
+export async function downloadModel(modelUri, options = {}) {
+    const { resolveModelFile } = await import("node-llama-cpp");
+    const { useMirror = false, signal, onProgress } = options;
+    const hfToken = process.env.HF_TOKEN || process.env.HUGGING_FACE_TOKEN;
+    const opts = {
+        directory: LOCAL_LLM_CACHE_DIR,
+        endpoints: {
+            huggingFace: useMirror ? "https://hf-mirror.com/" : "https://huggingface.co/",
+        },
+    };
+    if (signal)
+        opts.signal = signal;
+    if (hfToken)
+        opts.headers = { Authorization: `Bearer ${hfToken}` };
+    if (onProgress) {
+        opts.onProgress = ({ downloadedSize, totalSize }) => {
+            const percent = totalSize ? Math.round((downloadedSize / totalSize) * 100) : 0;
+            onProgress({ downloadedSize, totalSize, percent });
+        };
+    }
+    const resolved = await resolveModelFile(modelUri, opts);
+    return resolved;
+}
+export function getResolvedBasename(modelUri) {
+    return basename(modelUri.replace(/^hf:[^/]+\//, "").replace(/\//g, "_"));
+}

package/dist/core/local-llm-server/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * local-llm-server 入口。
+ *
+ * 两种运行模式：
+ * 1. 子进程模式（--child）：直接加载模型并启动 HTTP 服务，由主进程 fork 调用。
+ * 2. 主进程模式（默认导出）：fork 子进程，管理其生命周期，提供 baseUrl 给调用方。
+ *
+ * 主进程通过 startLocalLlmServer() 启动，返回 { baseUrl, stop }。
+ * 子进程就绪后通过 IPC 发送 { type: "ready" } 通知主进程。
+ */
+export interface LocalLlmServerOptions {
+    port?: number;
+    llmModelPath?: string;
+    embeddingModelPath?: string;
+    /** 上下文窗口 token 数，默认 32768（32K），需能容纳 system + tools + 对话 */
+    contextSize?: number;
+    /** 等待子进程就绪的超时毫秒数，默认 300000（5 分钟，冷启/大模型加载可能较慢） */
+    readyTimeoutMs?: number;
+}
+export interface LocalLlmServerHandle {
+    baseUrl: string;
+    stop: () => void;
+}
+/**
+ * 停止本地 LLM 子进程服务（若正在运行）。用于切换模型前先停止再启动。
+ */
+export declare function stopLocalLlmServer(): void;
+/**
+ * 启动本地 LLM 子进程服务。
+ * 已启动时直接返回已有 handle（单例）。需先 stop 再传新参数重启。
+ */
+export declare function startLocalLlmServer(opts?: LocalLlmServerOptions): Promise<LocalLlmServerHandle>;

package/dist/core/local-llm-server/index.js

@@ -0,0 +1,147 @@
+/**
+ * local-llm-server 入口。
+ *
+ * 两种运行模式：
+ * 1. 子进程模式（--child）：直接加载模型并启动 HTTP 服务，由主进程 fork 调用。
+ * 2. 主进程模式（默认导出）：fork 子进程，管理其生命周期，提供 baseUrl 给调用方。
+ *
+ * 主进程通过 startLocalLlmServer() 启动，返回 { baseUrl, stop }。
+ * 子进程就绪后通过 IPC 发送 { type: "ready" } 通知主进程。
+ */
+import { fileURLToPath } from "node:url";
+// ─── 子进程模式 ───────────────────────────────────────────────────────────────
+async function runChildProcess() {
+    const port = parseInt(process.env.LOCAL_LLM_PORT ?? "11435", 10);
+    const llmModelPath = process.env.LOCAL_LLM_MODEL?.trim() || undefined;
+    const embModelPath = process.env.LOCAL_EMB_MODEL?.trim() || undefined;
+    let contextSize = process.env.LOCAL_LLM_CONTEXT_SIZE != null ? parseInt(process.env.LOCAL_LLM_CONTEXT_SIZE, 10) : undefined;
+    if (contextSize == null && process.env.LOCAL_LLM_CONTEXT_MAX != null && String(process.env.LOCAL_LLM_CONTEXT_MAX).trim() !== '') {
+        contextSize = parseInt(process.env.LOCAL_LLM_CONTEXT_MAX, 10) || undefined;
+    }
+    if (!llmModelPath && !embModelPath) {
+        console.error("[local-llm] 未指定 LLM 或 Embedding 模型路径，至少需提供一个");
+        if (process.send)
+            process.send({ type: "error", message: "至少需指定 LOCAL_LLM_MODEL 或 LOCAL_EMB_MODEL" });
+        process.exit(1);
+    }
+    const { initModels } = await import("./llm-context.js");
+    const { createOpenAICompatServer } = await import("./server.js");
+    try {
+        await initModels({
+            ...(llmModelPath ? { llmModelPath } : {}),
+            ...(embModelPath ? { embeddingModelPath: embModelPath } : {}),
+            contextSize: contextSize ?? 32768,
+        });
+        await createOpenAICompatServer(port);
+        if (process.send) {
+            process.send({ type: "ready", port });
+        }
+    }
+    catch (e) {
+        console.error("[local-llm] 子进程启动失败:", e);
+        if (process.send) {
+            process.send({ type: "error", message: String(e) });
+        }
+        process.exit(1);
+    }
+}
+let serverHandle = null;
+/**
+ * 停止本地 LLM 子进程服务（若正在运行）。用于切换模型前先停止再启动。
+ */
+export function stopLocalLlmServer() {
+    if (serverHandle) {
+        serverHandle.stop();
+        serverHandle = null;
+    }
+}
+/**
+ * 启动本地 LLM 子进程服务。
+ * 已启动时直接返回已有 handle（单例）。需先 stop 再传新参数重启。
+ */
+export async function startLocalLlmServer(opts = {}) {
+    if (serverHandle)
+        return serverHandle;
+    const { fork } = await import("node:child_process");
+    const port = opts.port ?? 11435;
+    const readyTimeoutMs = opts.readyTimeoutMs ?? 300_000;
+    const env = {
+        ...process.env,
+        LOCAL_LLM_PORT: String(port),
+        LOCAL_LLM_CHILD: "1",
+    };
+    if (opts.llmModelPath)
+        env.LOCAL_LLM_MODEL = opts.llmModelPath;
+    if (opts.embeddingModelPath)
+        env.LOCAL_EMB_MODEL = opts.embeddingModelPath;
+    if (opts.contextSize != null)
+        env.LOCAL_LLM_CONTEXT_SIZE = String(opts.contextSize);
+    const childPath = fileURLToPath(import.meta.url);
+    const child = fork(childPath, ["--child"], {
+        env,
+        stdio: ["ignore", "inherit", "inherit", "ipc"],
+        execArgv: [],
+    });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`[local-llm] 子进程启动超时（${readyTimeoutMs}ms）`));
+        }, readyTimeoutMs);
+        child.on("message", (msg) => {
+            if (msg?.type === "ready") {
+                clearTimeout(timer);
+                resolve();
+            }
+            else if (msg?.type === "error") {
+                clearTimeout(timer);
+                reject(new Error(`[local-llm] 子进程错误: ${msg.message}`));
+            }
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            if (code !== 0)
+                reject(new Error(`[local-llm] 子进程意外退出，code=${code}`));
+        });
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+    // 主进程退出时清理子进程
+    const cleanup = () => { try {
+        child.kill();
+    }
+    catch { /* ignore */ } };
+    process.on("exit", cleanup);
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    serverHandle = {
+        baseUrl: `http://127.0.0.1:${port}/v1`,
+        stop: () => {
+            serverHandle = null;
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+        },
+    };
+    // 子进程意外退出（崩溃、OOM 等）时清理 handle 与 env，避免后续请求继续连已死服务导致 "Connection error"
+    const onChildExit = (code, signal) => {
+        if (serverHandle)
+            serverHandle = null;
+        process.env.LOCAL_LLM_START_FAILED = "本地模型服务已退出，请重新点击「启动本地模型服务」";
+        delete process.env.LOCAL_LLM_BASE_URL;
+        console.warn("[local-llm] 子进程已退出 code=%s signal=%s，请重新启动本地模型服务", code, signal);
+    };
+    child.on("exit", onChildExit);
+    console.log(`[local-llm] 本地服务就绪: ${serverHandle.baseUrl}`);
+    return serverHandle;
+}
+// ─── 入口判断 ─────────────────────────────────────────────────────────────────
+// 子进程模式：被 fork 时带 --child 参数或设置了 LOCAL_LLM_CHILD 环境变量
+if (process.argv.includes("--child") || process.env.LOCAL_LLM_CHILD === "1") {
+    runChildProcess().catch((e) => {
+        console.error("[local-llm] 致命错误:", e);
+        process.exit(1);
+    });
+}

package/dist/core/local-llm-server/llm-context.d.ts

@@ -0,0 +1,65 @@
+export interface LlmContextOptions {
+    /** LLM 推理模型路径或 hf: URI，可选；不传则仅提供 embedding */
+    llmModelPath?: string;
+    /** Embedding 模型路径或 hf: URI，可选；不传则仅提供 chat */
+    embeddingModelPath?: string;
+    /** GPU layers，-1 表示全部卸载到 GPU（Metal），0 表示纯 CPU */
+    gpuLayers?: number;
+    /** 上下文窗口大小，默认 32768（32K） */
+    contextSize?: number;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    /** tool_calls（assistant 发起工具调用时） */
+    tool_calls?: ToolCall[];
+    /** tool_call_id（role=tool 时，对应哪个 tool_call） */
+    tool_call_id?: string;
+    /** tool 消息的函数名 */
+    name?: string;
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatCompletionChunk {
+    content?: string;
+    tool_calls?: ToolCall[];
+    finish_reason?: "stop" | "tool_calls" | "length";
+}
+export declare function initModels(opts: LlmContextOptions): Promise<void>;
+/**
+ * 流式 chat completion。
+ * onChunk 每次收到新 token 时调用；结束后返回完整 finish_reason。
+ */
+export declare function chatCompletionStream(messages: ChatMessage[], tools: ToolDefinition[], onChunk: (chunk: ChatCompletionChunk) => void, signal?: AbortSignal): Promise<void>;
+/**
+ * 非流式 chat completion（内部复用流式实现）。
+ */
+export declare function chatCompletion(messages: ChatMessage[], tools: ToolDefinition[], signal?: AbortSignal): Promise<{
+    content: string;
+    tool_calls?: ToolCall[];
+    finish_reason: string;
+}>;
+/**
+ * 文本 embedding，返回 L2 归一化向量。
+ */
+export declare function getEmbedding(text: string): Promise<number[]>;
+/** 是否至少加载了一个模型（LLM 或 Embedding） */
+export declare function isReady(): boolean;
+/** 是否有 LLM，可提供 chat/completions */
+export declare function isLlmReady(): boolean;
+/** 是否有 Embedding，可提供 embeddings */
+export declare function isEmbeddingReady(): boolean;