@next-open-ai/openbot 0.6.16 → 0.6.66

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

@@ -0,0 +1,152 @@
+/**
+ * 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 metaUrl = (new Function("return typeof import.meta !== 'undefined' ? import.meta.url : ''")());
+    const childPath = metaUrl
+        ? fileURLToPath(metaUrl)
+        : (typeof globalThis.__filename !== "undefined"
+            ? globalThis.__filename
+            : process.argv[1] || ".");
+    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,66 @@
+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。
+ * 本地模型若输出 <think>...</think> 块，会从流中过滤，不展示思考过程。
+ */
+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;

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

@@ -0,0 +1,270 @@
+/**
+ * node-llama-cpp 模型实例管理。
+ * 可只加载 LLM、只加载 Embedding、或两者都加载；有一个就启动一个，不因缺另一个而失败。
+ */
+import { LOCAL_LLM_CACHE_DIR } from "./model-resolve.js";
+let llama = null;
+let llmModel = null;
+let embeddingModel = null;
+let embeddingCtx = null;
+/** 上下文窗口大小，initModels 时设置，用于 createContext；默认 32K 以容纳较长 system + tools */
+let storedContextSize = 32768;
+/** 串行锁：同一模型同一时间只处理一个推理请求 */
+let llmQueue = Promise.resolve();
+async function getLlamaInstance(gpuLayers) {
+    if (llama)
+        return llama;
+    const { getLlama, LlamaLogLevel } = await import("node-llama-cpp");
+    llama = await getLlama({
+        logLevel: LlamaLogLevel.warn,
+        ...(gpuLayers !== undefined ? { gpu: gpuLayers === 0 ? false : "auto" } : {}),
+    });
+    return llama;
+}
+export async function initModels(opts) {
+    storedContextSize = opts.contextSize ?? 32768;
+    const { resolveModelFile } = await import("node-llama-cpp");
+    const instance = await getLlamaInstance(opts.gpuLayers);
+    const cacheDir = LOCAL_LLM_CACHE_DIR;
+    if (opts.llmModelPath?.trim()) {
+        console.log("[local-llm] 加载 LLM 模型:", opts.llmModelPath);
+        const llmPath = await resolveModelFile(opts.llmModelPath, cacheDir);
+        llmModel = await instance.loadModel({ modelPath: llmPath });
+    }
+    else {
+        llmModel = null;
+    }
+    if (opts.embeddingModelPath?.trim()) {
+        console.log("[local-llm] 加载 Embedding 模型:", opts.embeddingModelPath);
+        const embPath = await resolveModelFile(opts.embeddingModelPath, cacheDir);
+        embeddingModel = await instance.loadModel({ modelPath: embPath });
+        embeddingCtx = await embeddingModel.createEmbeddingContext();
+    }
+    else {
+        embeddingModel = null;
+        embeddingCtx = null;
+    }
+    console.log("[local-llm] 模型加载完成", {
+        llm: !!llmModel,
+        embedding: !!embeddingCtx,
+    });
+}
+/** 将 API 可能传来的 content（string | array 如 [{ type: "text", text: "..." }]）规范为 string，避免 node-llama-cpp LlamaText.fromJSON 收到对象抛 "Unknown value type: [object Object]" */
+function contentToString(content) {
+    if (content == null)
+        return "";
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return String(content);
+    return content
+        .filter((part) => part != null && typeof part === "object")
+        .map((part) => (part.type === "text" && typeof part.text === "string" ? part.text : ""))
+        .join("");
+}
+/**
+ * 将 ChatMessage[] 转换为 node-llama-cpp 的 LlamaChatMessage[]。
+ * tool_calls 序列化为 assistant content；tool 结果作为 user content 回传。
+ * 入参 content 可能是 OpenAI 多段格式（content: [{ type: "text", text: "..." }]），必须规范为 string。
+ */
+function toLocalMessages(messages) {
+    return messages.map((m) => {
+        const rawContent = m.content;
+        const content = contentToString(rawContent);
+        if (m.role === "tool") {
+            return { role: "user", content: `[Tool result for ${m.name ?? m.tool_call_id ?? "tool"}]: ${content}` };
+        }
+        if (m.role === "assistant" && m.tool_calls?.length) {
+            const calls = JSON.stringify(m.tool_calls);
+            return { role: "assistant", content: content + `\n[tool_calls]: ${calls}` };
+        }
+        return { role: m.role, content };
+    });
+}
+/**
+ * 将 tools 定义转换为 grammar 约束描述，拼入 system prompt。
+ * node-llama-cpp v3 通过 LlamaGrammar 支持 JSON schema 约束输出，
+ * 这里用 prompt 方式描述工具，让模型以 JSON 格式输出 tool_calls。
+ */
+function buildToolSystemPrompt(tools) {
+    if (!tools.length)
+        return "";
+    const descs = tools.map((t) => {
+        const fn = t.function;
+        return `- ${fn.name}: ${fn.description ?? ""}\n  parameters: ${JSON.stringify(fn.parameters ?? {})}`;
+    }).join("\n");
+    return `\n\nYou have access to the following tools. When you need to call a tool, respond ONLY with a JSON object in this exact format (no other text):\n{"tool_calls":[{"id":"call_<random>","type":"function","function":{"name":"<tool_name>","arguments":"<json_string>"}}]}\n\nAvailable tools:\n${descs}`;
+}
+/** 尝试从模型输出中解析 tool_calls JSON */
+function parseToolCalls(text) {
+    const trimmed = text.trim();
+    // 匹配 {"tool_calls":[...]} 格式
+    const match = trimmed.match(/\{[\s\S]*"tool_calls"[\s\S]*\}/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (Array.isArray(parsed.tool_calls) && parsed.tool_calls.length > 0) {
+            return parsed.tool_calls;
+        }
+    }
+    catch {
+        // 不是合法 JSON，当普通文本处理
+    }
+    return null;
+}
+/**
+ * 从累积文本中移除 <think>...</think> 块，只保留对外可见的正文（关闭本地模型“思考过程”的展示）。
+ * 若存在未闭合的 <think>，则从 <think> 起至末尾均视为思考内容不输出。
+ */
+function getVisibleWithoutThinking(text) {
+    let out = "";
+    let i = 0;
+    const openTag = "<think>";
+    const closeTag = "</think>";
+    while (i < text.length) {
+        const open = text.indexOf(openTag, i);
+        if (open === -1) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, open);
+        const close = text.indexOf(closeTag, open + openTag.length);
+        if (close === -1) {
+            // 思考块未闭合，剩余不输出
+            break;
+        }
+        i = close + closeTag.length;
+    }
+    return out;
+}
+/**
+ * 流式 chat completion。
+ * onChunk 每次收到新 token 时调用；结束后返回完整 finish_reason。
+ * 本地模型若输出 <think>...</think> 块，会从流中过滤，不展示思考过程。
+ */
+export async function chatCompletionStream(messages, tools, onChunk, signal) {
+    if (!llmModel)
+        throw new Error("[local-llm] LLM 模型未初始化");
+    const { LlamaChatSession } = await import("node-llama-cpp");
+    // 串行排队
+    const run = async () => {
+        const ctx = await llmModel.createContext({ contextSize: storedContextSize });
+        // 注入历史消息（除最后一条 user 消息）
+        const localMsgs = toLocalMessages(messages);
+        let lastUser = -1;
+        for (let i = localMsgs.length - 1; i >= 0; i--) {
+            if (localMsgs[i].role === "user") {
+                lastUser = i;
+                break;
+            }
+        }
+        const history = lastUser > 0 ? localMsgs.slice(0, lastUser) : [];
+        const userPrompt = lastUser >= 0 ? localMsgs[lastUser].content : "";
+        // 找 system prompt，拼入 tool 描述（system 的 content 也可能是 array，需规范为 string）
+        const systemMsg = messages.find((m) => m.role === "system");
+        const toolSystemPrompt = buildToolSystemPrompt(tools);
+        const systemContent = contentToString(systemMsg?.content) + toolSystemPrompt;
+        // 创建带 systemPrompt 的 session，重建历史
+        const session = new LlamaChatSession({
+            contextSequence: ctx.getSequence(),
+            systemPrompt: systemContent || undefined,
+        });
+        for (const msg of history) {
+            if (msg.role === "user") {
+                await session.prompt(msg.content, { onTextChunk: () => { } });
+            }
+        }
+        let fullText = "";
+        let prevSentVisibleLength = 0;
+        let lastSent = ""; // 连续相同 delta 只发一次，缓解回复缓慢时「每个字显示两遍」
+        try {
+            await session.prompt(userPrompt, {
+                onTextChunk: (token) => {
+                    if (signal?.aborted)
+                        return;
+                    const s = typeof token === "string" ? token : (token != null ? String(token) : "");
+                    if (!s)
+                        return;
+                    // node-llama-cpp 在 detokenize(tokens, false, tokenTrail) 时可能返回带上下文的片段（含重复前缀），
+                    // 与 DeepSeek 等仅返回增量不同。只向下游发送增量，避免出现「你好你好！！我是我是...」式重复。
+                    if (s.startsWith(fullText)) {
+                        fullText = s;
+                    }
+                    else {
+                        fullText += s;
+                    }
+                    // 过滤 <think>...</think> 块，不向客户端输出思考过程
+                    const visibleText = getVisibleWithoutThinking(fullText);
+                    const toSend = visibleText.slice(prevSentVisibleLength);
+                    prevSentVisibleLength = visibleText.length;
+                    if (toSend && toSend !== lastSent) {
+                        lastSent = toSend;
+                        onChunk({ content: toSend });
+                    }
+                },
+                signal,
+            });
+        }
+        catch (e) {
+            // node-llama-cpp 在解析模型输出（如 segment/tool_call）时可能对 LlamaText.fromJSON 传入对象导致 "Unknown value type: [object Object]"
+            const msg = e instanceof Error ? e.message : String(e);
+            const stack = e instanceof Error ? e.stack : undefined;
+            console.error("[local-llm] chatCompletionStream session.prompt error:", msg);
+            if (stack)
+                console.error("[local-llm] stack:", stack);
+            throw e;
+        }
+        // 检查是否是 tool_calls 输出
+        const toolCalls = parseToolCalls(fullText);
+        if (toolCalls) {
+            onChunk({ tool_calls: toolCalls, finish_reason: "tool_calls" });
+        }
+        else {
+            onChunk({ finish_reason: "stop" });
+        }
+        await ctx.dispose();
+    };
+    llmQueue = llmQueue.then(run, run);
+    await llmQueue;
+}
+/**
+ * 非流式 chat completion（内部复用流式实现）。
+ */
+export async function chatCompletion(messages, tools, signal) {
+    let content = "";
+    let toolCalls;
+    let finishReason = "stop";
+    await chatCompletionStream(messages, tools, (chunk) => {
+        if (chunk.content)
+            content += chunk.content;
+        if (chunk.tool_calls)
+            toolCalls = chunk.tool_calls;
+        if (chunk.finish_reason)
+            finishReason = chunk.finish_reason;
+    }, signal);
+    return { content, tool_calls: toolCalls, finish_reason: finishReason };
+}
+/**
+ * 文本 embedding，返回 L2 归一化向量。
+ */
+export async function getEmbedding(text) {
+    if (!embeddingCtx)
+        throw new Error("[local-llm] Embedding 模型未初始化");
+    const result = await embeddingCtx.getEmbeddingFor(text);
+    const vec = Array.from(result.vector);
+    const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0)) || 1;
+    return vec.map((v) => v / norm);
+}
+/** 是否至少加载了一个模型（LLM 或 Embedding） */
+export function isReady() {
+    return llmModel !== null || embeddingCtx !== null;
+}
+/** 是否有 LLM，可提供 chat/completions */
+export function isLlmReady() {
+    return llmModel !== null;
+}
+/** 是否有 Embedding，可提供 embeddings */
+export function isEmbeddingReady() {
+    return embeddingCtx !== null;
+}

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

@@ -0,0 +1,27 @@
+export declare const LOCAL_LLM_CACHE_DIR: string;
+/**
+ * 取 modelUri 的末尾文件名（用于与已安装文件灵活匹配：不同 node-llama-cpp 版本可能生成不同前缀）。
+ * 例：hf:unsloth/Qwen3.5-4B-GGUF/Qwen3.5-4B-Q5_K_M.gguf → Qwen3.5-4B-Q5_K_M.gguf
+ * 例：hf_unsloth_Qwen3.5-4B-GGUF_Qwen3.5-4B-Q5_K_M.gguf → Qwen3.5-4B-Q5_K_M.gguf（文件名形式取最后一段 _ 之后）
+ */
+export declare function modelUriBasename(modelUri: string): string;
+/**
+ * 将 modelUri（hf:owner/repo/file.gguf）或文件名转为缓存目录下的文件名。
+ * 与 LocalModelsService.predictFilename 逻辑一致。
+ */
+export declare function modelUriToFilename(modelUri: string): string;
+/**
+ * 在缓存目录中解析出实际存在的模型文件路径。
+ * 先尝试精确文件名，若无则按「以 modelUri 的末尾文件名结尾」匹配（与「已安装的本地模型」逻辑一致）。
+ */
+export declare function resolveModelPathInCache(modelIdOrUri: string, cacheDir?: string): string;
+/**
+ * 检查指定模型（uri 或文件名）是否已存在于本地缓存目录。
+ * 支持精确文件名 或 以末尾 .gguf 文件名结尾的灵活匹配，与「已安装的本地模型」展示一致。
+ */
+export declare function isModelFileInCache(modelIdOrUri: string, cacheDir?: string): boolean;
+/**
+ * 将前端传入的模型标识（hf: URI 或已安装文件名）转为可传给 node-llama-cpp 的路径或 URI。
+ * 若为纯文件名（如 hf_xxx.gguf），则返回缓存目录下的绝对路径；若实际磁盘文件名与配置不一致（如 node-llama-cpp 命名），则解析为真实路径。
+ */
+export declare function toModelPathForStart(uriOrFilename: string, cacheDir?: string): string;

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

@@ -0,0 +1,90 @@
+/**
+ * 本地模型路径解析与文件存在性检查。
+ * 缓存目录：~/.openbot/.cached_models/，与 openbot 配置同目录便于管理。
+ * 与「已安装的本地模型」展示一致：支持精确文件名 或 以末尾 .gguf 文件名结尾的灵活匹配（兼容 node-llama-cpp 不同命名）。
+ */
+import { join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+export const LOCAL_LLM_CACHE_DIR = join(homedir(), ".openbot", ".cached_models");
+/**
+ * 取 modelUri 的末尾文件名（用于与已安装文件灵活匹配：不同 node-llama-cpp 版本可能生成不同前缀）。
+ * 例：hf:unsloth/Qwen3.5-4B-GGUF/Qwen3.5-4B-Q5_K_M.gguf → Qwen3.5-4B-Q5_K_M.gguf
+ * 例：hf_unsloth_Qwen3.5-4B-GGUF_Qwen3.5-4B-Q5_K_M.gguf → Qwen3.5-4B-Q5_K_M.gguf（文件名形式取最后一段 _ 之后）
+ */
+export function modelUriBasename(modelUri) {
+    const s = (modelUri || "").trim();
+    if (!s)
+        return "";
+    const parts = s.replace(/\\/g, "/").split("/");
+    const last = parts[parts.length - 1] || s;
+    // 仅对无 "/" 的文件名形式（如 hf_X_Y_Z.gguf）取最后 _ 之后一段，以匹配 node-llama-cpp 可能生成的短文件名
+    if (!s.includes("/") && last.includes("_") && last.endsWith(".gguf")) {
+        const fromUnderscore = last.slice(last.lastIndexOf("_") + 1);
+        if (fromUnderscore.endsWith(".gguf"))
+            return fromUnderscore;
+    }
+    return last;
+}
+/**
+ * 将 modelUri（hf:owner/repo/file.gguf）或文件名转为缓存目录下的文件名。
+ * 与 LocalModelsService.predictFilename 逻辑一致。
+ */
+export function modelUriToFilename(modelUri) {
+    const s = (modelUri || "").trim();
+    if (!s)
+        return "";
+    if (s.startsWith("hf:")) {
+        const parts = s.slice(3).split("/");
+        return "hf_" + parts.slice(0, -1).join("_") + "_" + parts[parts.length - 1];
+    }
+    // 已是文件名或路径，只取 basename
+    const last = s.replace(/\\/g, "/").split("/").pop();
+    return last ?? s;
+}
+/**
+ * 在缓存目录中解析出实际存在的模型文件路径。
+ * 先尝试精确文件名，若无则按「以 modelUri 的末尾文件名结尾」匹配（与「已安装的本地模型」逻辑一致）。
+ */
+export function resolveModelPathInCache(modelIdOrUri, cacheDir = LOCAL_LLM_CACHE_DIR) {
+    const filename = modelUriToFilename(modelIdOrUri);
+    if (!filename || !filename.endsWith(".gguf"))
+        return "";
+    const exactPath = join(cacheDir, filename);
+    if (existsSync(exactPath))
+        return exactPath;
+    const suffix = modelUriBasename(modelIdOrUri);
+    if (!suffix)
+        return "";
+    try {
+        const files = readdirSync(cacheDir);
+        const found = files.find((f) => f.endsWith(".gguf") && (f === suffix || f.endsWith(suffix)));
+        return found ? join(cacheDir, found) : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * 检查指定模型（uri 或文件名）是否已存在于本地缓存目录。
+ * 支持精确文件名 或 以末尾 .gguf 文件名结尾的灵活匹配，与「已安装的本地模型」展示一致。
+ */
+export function isModelFileInCache(modelIdOrUri, cacheDir = LOCAL_LLM_CACHE_DIR) {
+    return resolveModelPathInCache(modelIdOrUri, cacheDir) !== "";
+}
+/**
+ * 将前端传入的模型标识（hf: URI 或已安装文件名）转为可传给 node-llama-cpp 的路径或 URI。
+ * 若为纯文件名（如 hf_xxx.gguf），则返回缓存目录下的绝对路径；若实际磁盘文件名与配置不一致（如 node-llama-cpp 命名），则解析为真实路径。
+ */
+export function toModelPathForStart(uriOrFilename, cacheDir = LOCAL_LLM_CACHE_DIR) {
+    const s = (uriOrFilename || "").trim();
+    if (!s)
+        return "";
+    if (s.startsWith("hf:"))
+        return s;
+    const resolved = resolveModelPathInCache(s, cacheDir);
+    if (resolved)
+        return resolved;
+    const filename = modelUriToFilename(s);
+    return filename ? join(cacheDir, filename) : s;
+}

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

@@ -0,0 +1 @@
+export declare function createOpenAICompatServer(port: number): Promise<void>;