dsh-multimodal-node 0.0.0-stage → 0.2.2

package/index.js

@@ -0,0 +1,960 @@
+/**
+ * dsh-multimodal-node —— Host 半。
+ *
+ * 一个插件，两种身份，共享同一套底座：
+ *
+ *   service（服务节点）
+ *     · API 接入端口（默认 8287）—— ComfyUI 自己的协议 + `/node/*` 用户节点接口。
+ *       别的机器、脚本、别的 DSH 都往这里发 JSON。
+ *     · 网页端口（默认 8286）—— 带登录的控制台，人用。
+ *     · ComfyUI 板块 —— 一个实例 = 一张卡 = 一个端口，可托管本机进程。
+ *     · Blender 板块 —— bridge（HTTP 端点）或 spawn（本机 blender.exe 渲染）。
+ *
+ *   user（用户节点）
+ *     · 不开任何监听。它的侧边栏是一个客户端：拉服务节点的模板、队列、模型，
+ *       产物落到本机目录。
+ *     · 本机仍然跑工作流库、运行索引、资产库——因为「本机产物文件夹」要能浏览，
+ *       而这个插件换到服务节点模式时不能表现为「数据没了」。
+ *
+ * 模式切换的边界：换模式 = 换**监听行为与侧边栏**，不换数据目录。
+ * 一个人在一台机器上先当服务节点、后来只当客户端，他的工作流库和产物索引必须还在。
+ */
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { SettingsStore, resolveDataDir, resolveOutputDir, resolveBlenderOutputDir, MODES } from './lib/config.js';
+import { InstanceManager } from './lib/instances.js';
+import { TaskPool } from './lib/pool.js';
+import { GatewayServer } from './lib/gateway.js';
+import { RemoteServer } from './lib/remote.js';
+import { AuthStore } from './lib/auth.js';
+import { ApiKeyStore } from './lib/apikeys.js';
+import { WorkflowLibrary } from './lib/library.js';
+import { RunIndex } from './lib/runindex.js';
+import { AssetLibrary } from './lib/assets.js';
+import { PromptLibrary } from './lib/promptlibrary.js';
+import { ChainLibrary } from './lib/chain.js';
+import { BlenderManager, findBlenderExecutable, parseFrames } from './lib/blender.js';
+import { NodeClient } from './lib/nodeclient.js';
+import { createNodeRoutes, createApiGuard } from './lib/nodeapi.js';
+import { modelInventory, inspectModelDir, localModelRootEntries, modelFolders, modelsInFolder } from './lib/models.js';
+import { errorMessage, readJson, sameOrigin, sendJson } from './lib/http.js';
+import { multimodalDefinition } from './lib/tools.js';
+import { listKnowledgeBases } from './lib/promptassist.js';
+
+export const name = 'dsh-multimodal-node';
+
+const PRODUCT_EXT = /\.(png|jpg|jpeg|webp|gif|mp4|mov|webm|mkv|avi|wav|mp3|flac|glb|gltf|blend|exr|tif|tiff)$/i;
+
+export async function apply(ctx, entryConfig) {
+    const dataDir = resolveDataDir(entryConfig);
+    const settings = new SettingsStore(dataDir);
+    await settings.init();
+
+    const log = (level, message) => {
+        const line = `[multimodal-node] ${message}`;
+        if (level === 'error') console.error(line);
+        else if (level === 'warn') console.warn(line);
+        else console.log(line);
+    };
+
+    let saving = Promise.resolve();
+    const onChange = () => {
+        // 串行化写盘：面板上两次相邻点击不能在同一个临时文件上交错 rename。
+        saving = saving
+            .then(() => settings.save())
+            .catch((error) => log('error', `settings save failed: ${errorMessage(error)}`));
+    };
+
+    const instances = new InstanceManager({
+        getInstances: () => settings.get().instances,
+        onChange,
+    });
+
+    const pool = new TaskPool({
+        instances,
+        settings: () => settings.get(),
+        onChange,
+        log,
+    });
+
+    const keys = new ApiKeyStore(settings);
+
+    const blender = new BlenderManager({
+        getConfig: () => settings.get().blender ?? {},
+        onChange,
+        log,
+    });
+
+    const nodeClient = new NodeClient(() => settings.get());
+
+    /** 用户节点接口：挂在 API 接入端口上，gateway 先问它、再走 ComfyUI 协议。 */
+    const nodeRoutes = createNodeRoutes({
+        settings: () => settings.get(),
+        keys,
+        pool,
+        instances,
+        library: null, // 下面建好库之后再补：闭包里读的是这个变量
+        runs: null,
+        assets: null,
+        blender,
+        get gateway() {
+            return gateway;
+        },
+        log,
+    });
+
+    const apiGuard = createApiGuard(keys);
+
+    const gateway = new GatewayServer({
+        settings: () => settings.get(),
+        instances,
+        pool,
+        log,
+        nodeRoutes,
+        apiGuard,
+    });
+
+    const auth = new AuthStore(settings);
+    const library = new WorkflowLibrary(dataDir);
+    await library.init();
+    // 控制台按账号显示自己跑过的东西；那必须跨进程重启留着，所以落盘而不是只放在池子里。
+    const runs = new RunIndex(dataDir);
+    await runs.init();
+    // 控制台浏览的是图片，一行一个文件、带像素尺寸。与运行索引是两张表：
+    // 一次运行出好几个文件，而人点的是文件。
+    const assets = new AssetLibrary(dataDir);
+    await assets.init();
+    // 收藏的提示词：可复用文本，按账号，独立于任何工作流。
+    const prompts = new PromptLibrary(dataDir);
+    await prompts.init();
+    // 工作链：保存下来的一串步骤，后面的步骤吃前面的产物。
+    const chains = new ChainLibrary(dataDir);
+    await chains.init();
+
+    // 用户节点接口拿到的是这几个已经建好的单例。
+    nodeRoutes.bindLibrary?.({ library, runs, assets });
+
+    // 两条一次性迁移：让 03 号插件写下的旧数据（没有分级、没有归属）直接可用。
+    // 都是幂等的，只碰还缺字段的行，所以在已迁移目录上重启是空操作。
+    ctx.effect(() => {
+        void (async () => {
+            try {
+                const tiered = await auth.migrateTiers();
+                if (tiered > 0) log('info', `migrated ${tiered} account(s) to a content tier`);
+                const owner = auth.accounts()[0]?.name;
+                if (typeof owner === 'string' && owner !== '') {
+                    const claimed = await library.claimOwnerless(owner);
+                    if (claimed > 0) log('info', `assigned ${claimed} legacy workflow(s) to ${owner}`);
+                }
+            } catch (error) {
+                log('error', `migration failed: ${errorMessage(error)}`);
+            }
+        })();
+        return () => {};
+    }, 'dsh-multimodal-node: migrations');
+
+    /**
+     * 提示词助手那次模型调用打到哪。
+     *
+     * 懒读：默认模型可能在设置里被换掉，而插件不会重启；在 apply() 时钉死会一直用
+     * 一个用户已经换掉的路由。没有这个服务的宿主也照常跑——助手退化到词典检索。
+     */
+    const llmRoute = () => {
+        const model = ctx.get('agentDefaultModel');
+        if (model === undefined || typeof model.currentSelection !== 'function') return undefined;
+        try {
+            const selection = model.currentSelection();
+            if (typeof selection?.provider !== 'string' || typeof selection?.model !== 'string') return undefined;
+            return { provider: selection.provider, model: selection.model };
+        } catch {
+            return undefined;
+        }
+    };
+
+    const remote = new RemoteServer({
+        settings: () => settings.get(),
+        store: settings,
+        auth,
+        instances,
+        pool,
+        gateway,
+        library,
+        runs,
+        assets,
+        prompts,
+        chains,
+        log,
+        // 两个都是 getter：启动之后才选的路由必须是被用的那条，而没挂 `llm` 的宿主不能崩。
+        get llm() {
+            return ctx.get('llm');
+        },
+        get llmRoute() {
+            return llmRoute();
+        },
+    });
+
+    // --- 生命周期 ---------------------------------------------------------
+    ctx.effect(() => {
+        pool.start();
+        return () => pool.dispose();
+    }, 'dsh-multimodal-node: scheduler');
+
+    /**
+     * 最后一道防线：进程级 exit 钩子。
+     *
+     * `ctx.effect` 的清理只在插件按顺序卸载时跑。宿主被强杀、窗口关闭应用退出、
+     * 关闭链里前面某一步抛错——这三种情况它都不跑，而那正是 ComfyUI 进程树存活、
+     * 显存被占住的场景。
+     *
+     * `process.on('exit')` 不能 await，所以杀是同步的（spawnSync）。只注册一次、
+     * 从不注销，`disposed` 让正常路径与强制路径互斥，一个 pid 不会被杀两次。
+     */
+    let disposed = false;
+    const killOnExit = () => {
+        if (disposed) return;
+        disposed = true;
+        try {
+            instances.dispose();
+            blender.dispose();
+        } catch {
+            // exit 钩子里不能抛：抛了后面的钩子就不跑了。
+        }
+    };
+    process.once('exit', killOnExit);
+
+    /** 按模式起停监听。模式切换、端口变更都走这里。 */
+    const applyListeners = async () => {
+        const value = settings.get();
+        const mode = value.mode === 'user' ? 'user' : 'service';
+        if (mode === 'user') {
+            // 用户节点不开门。它要是还监听着上一个人留下的端口，那就是一台
+            // 「自称客户端却在给别人发任务」的机器。
+            await gateway.stop().catch(() => undefined);
+            await remote.stop().catch(() => undefined);
+            return { ok: true, mode, gateway: { ok: true, skipped: 'user-mode' }, remote: { ok: true, skipped: 'user-mode' } };
+        }
+        const gatewayResult = await gateway.start().catch((error) => ({ ok: false, error: errorMessage(error) }));
+        const remoteResult =
+            value.remote?.enabled === true
+                ? await remote.start().catch((error) => ({ ok: false, error: errorMessage(error) }))
+                : await remote.stop().then(() => ({ ok: true, skipped: 'disabled' }));
+        return { ok: gatewayResult.ok !== false && remoteResult.ok !== false, mode, gateway: gatewayResult, remote: remoteResult };
+    };
+
+    ctx.effect(() => {
+        void (async () => {
+            // 先绑端口，让启动期间打到任一端口的人拿到队列而不是 ECONNREFUSED，
+            // 然后再热一次健康表。
+            const started = await applyListeners();
+            if (started.gateway?.ok === false && started.gateway.skipped === undefined) {
+                log('error', `API 接入端口没起来：${started.gateway.error}`);
+            }
+            if (started.remote?.ok === false && started.remote.skipped === undefined) {
+                log('error', `网页端口没起来：${started.remote.error}`);
+            }
+            await auth.ensureSecret().catch((error) => log('error', `pairing secret: ${errorMessage(error)}`));
+            await instances.probeAll(true).catch(() => undefined);
+            await blender.probeAll(true).catch(() => undefined);
+            for (const runtime of instances.list()) {
+                if (runtime.instance.autoStart && !runtime.health.ok) void instances.start(runtime.id);
+            }
+        })();
+        return () => {
+            /**
+             * 关闭监听必须是**可等待的**，不能 `void` 掉就不管。
+             *
+             * 宿主热重载插件时的顺序是「先调清理、再重新 apply」。清理里如果只是
+             * `void gateway.stop()`，函数立刻返回，而两件事还没做完：
+             *   - 端口的 listen 还没关（server.close 是异步的）
+             *   - 于是紧接着的 apply 再去 listen 同一个端口 → EADDRINUSE
+             * 表现是「重载插件后端口没了，日志里一行 address already in use」。
+             *
+             * 清理函数本身不能改成 async（宿主不 await 它），所以这里同步地把
+             * server 从内核解绑：先 unref + close，再把「等待关闭」挂到返回的
+             * promise 上供测试与调试使用。
+             */
+            const closing = Promise.allSettled([gateway.stop(), remote.stop()]);
+            // 不 await（清理函数不能 async），但失败要记下来——否则「端口没关掉」
+            // 会表现为下一次启动的 EADDRINUSE，而不是这里的一条日志。
+            void closing.then((results) => {
+                for (const result of results) {
+                    if (result.status === 'rejected') log('warn', `关闭监听失败：${errorMessage(result.reason)}`);
+                }
+            });
+            /**
+             * 退出顺序很重要：监听先关，别让新任务进一个 worker 马上要死的队列；
+             * 然后同步杀掉实例进程（异步 taskkill 会随宿主一起死，等于什么都没杀）。
+             *
+             * 摘要是要记日志的，不能吞：机器回来显存仍被占时，「哪个实例我们没停掉」
+             * 是第一个问题，而这里是唯一能回答它的地方。
+             */
+            if (disposed) return;
+            disposed = true;
+            const summary = instances.dispose();
+            if (summary.stopped.length > 0) log('info', `shutdown: stopped ${summary.stopped.join(', ')}`);
+            if (summary.kept.length > 0) log('info', `shutdown: left running (stopOnExit=false): ${summary.kept.join(', ')}`);
+            const blenderStopped = blender.dispose();
+            if (blenderStopped.length > 0) log('info', `shutdown: blender stopped ${blenderStopped.join(', ')}`);
+        };
+    }, 'dsh-multimodal-node: listeners');
+
+    // 每 1.5 秒推一次状态：一个定时器，负载很轻。
+    ctx.effect(() => {
+        const timer = setInterval(() => {
+            void gateway.pushStatus();
+        }, 1500);
+        if (typeof timer.unref === 'function') timer.unref();
+        return () => clearInterval(timer);
+    }, 'dsh-multimodal-node: push');
+
+    // --- 面板与工具共用的运行时 -------------------------------------------
+    const runtime = {
+        settings,
+        instances,
+        pool,
+        gateway,
+        remote,
+        auth,
+        keys,
+        blender,
+        nodeClient,
+        library,
+        runs,
+        assets,
+        dataDir,
+        get mode() {
+            return settings.get().mode === 'user' ? 'user' : 'service';
+        },
+        async restartListeners() {
+            const result = await applyListeners();
+            await instances.probeAll(true).catch(() => undefined);
+            await blender.probeAll(true).catch(() => undefined);
+            return result;
+        },
+        async applySettings(patch) {
+            /**
+             * 变更前后的指纹只包含「决定监听怎么绑」的字段。多带一个字段进去，
+             * 改一次产物目录就会触发一次整个监听重启——那是会断掉正在下载的产物的。
+             */
+            const fingerprint = (value) =>
+                JSON.stringify([
+                    value.mode,
+                    value.listen?.enabled,
+                    value.listen?.host,
+                    value.listen?.port,
+                    value.remote?.enabled,
+                    value.remote?.host,
+                    value.remote?.port,
+                ]);
+            const before = fingerprint(settings.get());
+            await settings.patch(patch ?? {});
+            instances.sync();
+            blender.sync();
+            await instances.probeAll(true).catch(() => undefined);
+            if (fingerprint(settings.get()) !== before) return runtime.restartListeners();
+            await pool.pump();
+            return { ok: true };
+        },
+    };
+
+    /** 面板状态：两套 UI 要的数据一次给全，前端不做拼接。 */
+    const statusOf = async () => {
+        const value = settings.get();
+        const mode = value.mode === 'user' ? 'user' : 'service';
+        const snapshot = pool.snapshot();
+        const outputDir = resolveOutputDir(value);
+        const serviceNode = mode === 'user' ? await nodeClient.probe() : null;
+        const gatewayStatus = gateway.statusPayload();
+        return {
+            ok: true,
+            mode,
+            dataDir,
+            gateway: {
+                listening: gatewayStatus.listening,
+                host: gatewayStatus.host,
+                port: gatewayStatus.port,
+                lastError: gatewayStatus.lastError,
+            },
+            remote: {
+                enabled: value.remote?.enabled === true,
+                listening: remote.listening,
+                port: remote.port,
+                host: remote.host,
+                lastError: remote.lastError,
+                accounts: auth.accounts().map((entry) => ({
+                    name: entry.name,
+                    role: entry.role,
+                    tier: entry.tier === 'nsfw' ? 'nsfw' : 'sfw',
+                    createdAt: entry.createdAt ?? null,
+                })),
+                sessions: auth.sessions().map((entry) => ({
+                    user: entry.user,
+                    tier: entry.tier === 'nsfw' ? 'nsfw' : 'sfw',
+                    ip: entry.ip,
+                    createdAt: entry.createdAt,
+                    seenAt: entry.seenAt,
+                })),
+                assistant: value.remote?.assistant !== false,
+                requireCode: value.remote?.requireCode !== false,
+                bridges: [...remote.bridges.entries()].map(([, lease]) => ({ instanceId: lease.instanceId, user: lease.user })),
+            },
+            apiKeys: keys.list(),
+            apiAuth: { requireKey: keys.requireKey() },
+            node: {
+                configured: nodeClient.configured,
+                publicUrl: value.node?.publicUrl ?? '',
+                apiKeySet: String(value.node?.apiKey ?? '') !== '',
+                outputDir,
+                label: value.node?.label ?? '',
+                timeoutMs: value.node?.timeoutMs ?? 15000,
+                serviceNode,
+            },
+            queue: {
+                dynamic: snapshot.dynamic === true,
+                counters: snapshot.counters ?? {},
+                estimateMs: snapshot.estimate?.makespanMs ?? 0,
+                tasks: snapshot.tasks ?? [],
+            },
+            instances: gatewayStatus.instances ?? [],
+            blender: blender.statusPayload(),
+            models: (() => {
+                const inventory = modelInventory(value, { withSize: false });
+                return {
+                    ok: inventory.ok !== false,
+                    total: inventory.total ?? 0,
+                    folders: (inventory.folders ?? []).map((folder) => ({ name: folder.name, label: folder.label, count: folder.items.length })),
+                    roots: inventory.roots ?? [],
+                    // 每个扫描根是从哪来的：面板要能解释，不然「这个目录为什么会出现」只能靠猜
+                    rootEntries: inventory.rootEntries ?? [],
+                    extraRoots: (value.modelsScan?.roots ?? []),
+                    error: inventory.error ?? null,
+                };
+            })(),
+            counts: {
+                workflows: library.listAll().length,
+                runs: [...runs.byOwner.values()].reduce((sum, rows) => sum + rows.length, 0),
+                prompts: Object.values(prompts.byOwner ?? {}).reduce((sum, rows) => sum + (Array.isArray(rows) ? rows.length : 0), 0),
+                chains: chains.list('nsfw').length,
+            },
+            settings: {
+                listen: value.listen,
+                dynamic: value.dynamic,
+                probeMs: value.probeMs,
+                historyItems: value.historyItems,
+                stallWarnSec: value.stallWarnSec,
+                promptHeads: value.promptHeads,
+                promptKb: value.promptKb,
+                remote: {
+                    enabled: value.remote?.enabled === true,
+                    port: value.remote?.port,
+                    host: value.remote?.host,
+                    assistant: value.remote?.assistant !== false,
+                    requireCode: value.remote?.requireCode !== false,
+                },
+                blender: {
+                    enabled: value.blender?.enabled !== false,
+                    executable: value.blender?.executable ?? '',
+                    resolvedExecutable: findBlenderExecutable(String(value.blender?.executable ?? '')),
+                    outputDir: resolveBlenderOutputDir(value),
+                },
+                modelsScan: {
+                    roots: value.modelsScan?.roots ?? [],
+                    maxDepth: value.modelsScan?.maxDepth ?? 4,
+                },
+            },
+        };
+    };
+
+    const webServer = ctx.get('webServer');
+    if (webServer !== undefined) {
+        /**
+         * 挂一条同源路由。
+         *
+         * 返回式清理很重要：`register` 的返回值是一个注销函数。原来的写法把它丢掉了，
+         * 于是插件卸载时路由留在表里——下一次热重载再挂一遍，同一个 path 出现两个处理者，
+         * 请求被处理两次（表现为「点一次按钮，动作执行两遍」）。
+         */
+        const mount = (path, handler) =>
+            ctx.effect(() => {
+                const dispose = webServer.register({ kind: 'exact', path, handler });
+                return typeof dispose === 'function' ? dispose : () => {};
+            }, `dsh-multimodal-node: route ${path}`);
+
+        const readBody = async (request) => {
+            try {
+                return await readJson(request);
+            } catch {
+                return {};
+            }
+        };
+
+        mount('/multimodal/status', (request, response) => {
+            if (request.method !== 'GET') {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    sendJson(response, 200, await statusOf());
+                } catch (error) {
+                    sendJson(response, 500, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 配对码只在这里给：从桌面读出来念给人听，永不上线传输。 */
+        mount('/multimodal/pairing', (request, response) => {
+            if (request.method !== 'GET' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin GET required' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const code = await auth.currentCode();
+                    sendJson(response, 200, { ok: true, ...code });
+                } catch (error) {
+                    sendJson(response, 500, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 设置页唯一写入点：模式、端口、用户节点、Blender、表头、知识库全走这里。 */
+        mount('/multimodal/settings', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const result = await runtime.applySettings(body ?? {});
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 网页账号：给网页端口用。 */
+        mount('/multimodal/accounts', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? 'add');
+                    const accountName = String(body?.name ?? '');
+                    let result;
+                    if (action === 'add') {
+                        result = await auth.addAccount(
+                            accountName,
+                            String(body?.password ?? ''),
+                            body?.role === 'admin' ? 'admin' : 'viewer',
+                            body?.tier === 'nsfw' ? 'nsfw' : 'sfw',
+                        );
+                    } else if (action === 'tier') result = await auth.setTier(accountName, body?.tier === 'nsfw' ? 'nsfw' : 'sfw');
+                    else if (action === 'requireCode') result = await auth.setRequireCode(body?.requireCode !== false);
+                    else if (action === 'remove') {
+                        result = await auth.removeAccount(accountName);
+                        // 他们的工作流与运行本来是私有的；留着这些行等于留着一批没人能读、
+                        // 却仍占着索引的数据，而重建同名账号会继承它们。
+                        await library.dropOwner(accountName);
+                        await runs.dropOwner(accountName);
+                        await assets.dropOwner(accountName);
+                    } else if (action === 'password') result = await auth.setPassword(accountName, String(body?.password ?? ''));
+                    else if (action === 'revoke') result = await auth.revokeAll();
+                    else result = { ok: false, error: `unknown action ${action}` };
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** API 接入凭据：给程序用。创建时返回一次明文 key，之后只剩前缀。 */
+        mount('/multimodal/apikeys', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? 'list');
+                    const name = String(body?.name ?? '');
+                    let result;
+                    if (action === 'create') result = await keys.create({ name, tier: body?.tier, note: body?.note });
+                    else if (action === 'update') result = await keys.update(name, { tier: body?.tier, enabled: body?.enabled, note: body?.note });
+                    else if (action === 'remove') result = await keys.remove(name);
+                    else if (action === 'rotate') result = await keys.rotate(name);
+                    else if (action === 'requireKey') result = await keys.setRequireKey(body?.requireKey === true);
+                    else if (action === 'list') result = { ok: true, apiKeys: keys.list(), requireKey: keys.requireKey() };
+                    else result = { ok: false, error: `unknown action ${action}` };
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /**
+         * 模型扫描：ComfyUI 板块内的模型列表。
+         *
+         * 三个动作各管一件事，不合并：
+         *   list     —— 按实例（或不带实例 = 全部）读目录与文件
+         *   inspect  —— 填了一个地址，先告诉他这个目录到底能不能扫、像不像 models 根
+         *   roots    —— 增删「额外扫描目录」
+         *
+         * inspect 单独存在是因为「填错一层目录」是最常见的错误：用户填
+         * `E:\ComfyUI-aki-v3.2` 而不是 `E:\ComfyUI-aki-v3.2\ComfyUI\models`，
+         * 然后困惑为什么一个模型都没有。探测能直接指出下一层。
+         */
+        mount('/multimodal/models', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? 'list');
+                    const value = settings.get();
+                    if (action === 'inspect') {
+                        sendJson(response, 200, { ok: true, ...inspectModelDir(body?.dir) });
+                        return;
+                    }
+                    if (action === 'setInstanceRoot') {
+                        // 直接改某个实例的模型文件夹地址（实例行里那一栏）
+                        const id = String(body?.id ?? '');
+                        const dir = String(body?.dir ?? '').trim();
+                        if (dir !== '' && !isAbsolute(dir)) throw new Error('模型文件夹地址必须是绝对路径');
+                        const next = (value.instances ?? []).map((entry) =>
+                            entry.id === id ? { ...entry, modelsRoot: dir } : entry,
+                        );
+                        const result = await runtime.applySettings({ instances: next });
+                        sendJson(response, 200, { ...result, status: await statusOf() });
+                        return;
+                    }
+                    if (action === 'setRoots') {
+                        const roots = Array.isArray(body?.roots) ? body.roots : [];
+                        const result = await runtime.applySettings({ modelsScan: { roots } });
+                        sendJson(response, 200, { ...result, status: await statusOf() });
+                        return;
+                    }
+                    if (action === 'addRoot' || action === 'removeRoot') {
+                        const dir = String(body?.dir ?? '').trim();
+                        const current = Array.isArray(value.modelsScan?.roots) ? value.modelsScan.roots : [];
+                        const roots = action === 'addRoot'
+                            ? [...current, dir]
+                            : current.filter((row) => row !== dir);
+                        const result = await runtime.applySettings({ modelsScan: { roots } });
+                        sendJson(response, 200, { ...result, status: await statusOf() });
+                        return;
+                    }
+                    // list
+                    const instanceId = body?.instanceId === undefined || body.instanceId === null || body.instanceId === ''
+                        ? undefined
+                        : String(body.instanceId);
+                    const inventory = modelInventory(value, { withSize: body?.withSize === true, instanceId });
+                    if (inventory.ok === false) {
+                        sendJson(response, 200, { ok: false, ...inventory });
+                        return;
+                    }
+                    // 面板要「目录 + 文件」全量；这里不裁剪，裁剪交给前端的分页/搜索
+                    sendJson(response, 200, {
+                        ...inventory,
+                        folders: inventory.folders.map((folder) => ({
+                            ...folder,
+                            items: body?.withSize === true ? folder.items : folder.items,
+                        })),
+                    });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** ComfyUI 板块：实例的增删改、启停、探测、释放显存。 */
+        mount('/multimodal/instances', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? '');
+                    const id = String(body?.id ?? '');
+                    let result;
+                    if (action === 'start' || action === 'stop' || action === 'restart') {
+                        result = await instances[action](id);
+                    } else if (action === 'apply') {
+                        result = await runtime.applySettings({ instances: body.instances });
+                    } else if (action === 'probe') {
+                        await instances.probeAll(true);
+                        result = { ok: true };
+                    } else if (action === 'unbridge') {
+                        for (const [token, lease] of remote.bridges) {
+                            if (lease.instanceId === id) remote.releaseBridge(token);
+                        }
+                        result = { ok: true };
+                    } else {
+                        result = { ok: false, error: `unknown action ${action}` };
+                    }
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 队列板块：排序策略、取消、插队、释放显存、清空。 */
+        mount('/multimodal/pool', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? '');
+                    let result;
+                    if (action === 'dynamic') {
+                        pool.toggleDynamic(body.enabled === true);
+                        result = { ok: true, dynamic: settings.get().dynamic };
+                    } else if (action === 'cancel') {
+                        result = pool.cancel(String(body.id ?? ''));
+                    } else if (action === 'prioritize') {
+                        result = pool.prioritize(String(body.id ?? ''), body.delta ?? 1);
+                    } else if (action === 'free') {
+                        await Promise.all(
+                            instances.enabled().map(async (item) => {
+                                try {
+                                    await pool.backend(item).free({ unload_models: true, free_memory: true });
+                                } catch {
+                                    // 停着的实例没有可释放的东西
+                                }
+                            }),
+                        );
+                        result = { ok: true };
+                    } else if (action === 'clearQueue') {
+                        for (const task of pool.ordered()) pool.cancel(task.id);
+                        result = { ok: true };
+                    } else {
+                        result = { ok: false, error: `unknown action ${action}` };
+                    }
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** Blender 板块：实例管理 + 提交渲染 + 取消 + 浏览工程文件。 */
+        mount('/multimodal/blender', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? '');
+                    const id = String(body?.id ?? body?.instanceId ?? '');
+                    let result;
+                    if (action === 'apply') {
+                        result = await runtime.applySettings({ blender: body.blender ?? {} });
+                    } else if (action === 'probe') {
+                        await blender.probeAll(true);
+                        result = { ok: true };
+                    } else if (action === 'render') {
+                        result = await blender.submit(id, body);
+                    } else if (action === 'cancel') {
+                        result = await blender.cancel(id, String(body?.jobId ?? ''));
+                    } else if (action === 'blends') {
+                        result = { ok: true, files: blender.browseBlends(String(body?.dir ?? '')) };
+                    } else if (action === 'setExecutable') {
+                        result = await runtime.applySettings({ blender: { executable: String(body?.executable ?? '') } });
+                    } else {
+                        result = { ok: false, error: `unknown action ${action}` };
+                    }
+                    sendJson(response, 200, { ...result, status: await statusOf() });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /**
+         * 用户节点的动作：探测、模板、队列、模型、提交、拉产物。
+         *
+         * 全部由 Host 代发，浏览器不直连服务节点：否则 apikey 就落进页面里了，
+         * 而页面会被截图、会被 devtools 读、会进浏览器缓存。
+         */
+        mount('/multimodal/node', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? 'probe');
+                    let result;
+                    if (action === 'probe') result = await nodeClient.probe();
+                    else if (action === 'templates') result = { ok: true, templates: await nodeClient.templates() };
+                    else if (action === 'queue') result = await nodeClient.queue();
+                    else if (action === 'models') result = await nodeClient.models();
+                    else if (action === 'submit') result = await nodeClient.submit(body.payload ?? {});
+                    else if (action === 'history') result = await nodeClient.history(body.promptId === undefined ? undefined : String(body.promptId));
+                    else if (action === 'pool') result = await nodeClient.pool(String(body.poolAction ?? 'status'), body);
+                    else if (action === 'blender') result = await nodeClient.call(`/node/blender${body.suffix === undefined ? '' : String(body.suffix)}`);
+                    else if (action === 'blenderRender') {
+                        result = await nodeClient.call('/node/blender/render', { method: 'POST', body: body.payload ?? {} });
+                    } else if (action === 'fetch') {
+                        const dir = resolveOutputDir(settings.get());
+                        const saved = await nodeClient.fetchOutput(String(body.promptId ?? ''), String(body.file ?? ''), dir);
+                        result = { ok: true, ...saved };
+                    } else result = { ok: false, error: `unknown action ${action}` };
+                    sendJson(response, 200, result);
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 本机产物文件夹：列出、设路径、看总大小。 */
+        mount('/multimodal/output', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const body = await readBody(request);
+                try {
+                    const action = String(body?.action ?? 'list');
+                    if (action === 'set') {
+                        const target = String(body?.dir ?? '').trim();
+                        if (target !== '' && !isAbsolute(target)) throw new Error('产物目录必须是绝对路径');
+                        const result = await runtime.applySettings({ node: { outputDir: target } });
+                        sendJson(response, 200, { ...result, status: await statusOf() });
+                        return;
+                    }
+                    if (action === 'mkdir') {
+                        const dir = resolveOutputDir(settings.get());
+                        await mkdir(dir, { recursive: true });
+                        sendJson(response, 200, { ok: true, dir, status: await statusOf() });
+                        return;
+                    }
+                    const dir = resolveOutputDir(settings.get());
+                    await mkdir(dir, { recursive: true });
+                    const rows = [];
+                    let total = 0;
+                    let entries = [];
+                    try {
+                        entries = await readdir(dir, { withFileTypes: true });
+                    } catch {
+                        entries = [];
+                    }
+                    for (const entry of entries) {
+                        if (!entry.isFile()) continue;
+                        if (!PRODUCT_EXT.test(entry.name)) continue;
+                        const info = await stat(join(dir, entry.name)).catch(() => null);
+                        if (info === null) continue;
+                        total += info.size;
+                        rows.push({ name: entry.name, path: join(dir, entry.name), bytes: info.size, modifiedAt: info.mtimeMs });
+                    }
+                    rows.sort((left, right) => right.modifiedAt - left.modifiedAt);
+                    sendJson(response, 200, { ok: true, dir, total, files: rows.slice(0, 200) });
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        /** 提示词助手能真正读到的知识库。 */
+        mount('/multimodal/knowledge', (request, response) => {
+            if (request.method !== 'GET') {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            void (async () => {
+                try {
+                    const root = settings.get().promptKb?.root ?? '';
+                    const bases = await listKnowledgeBases(root);
+                    sendJson(response, 200, {
+                        ok: true,
+                        selected: settings.get().promptKb?.kbName ?? '',
+                        bases: bases.map((entry) => ({
+                            name: entry.name,
+                            documents: entry.documents,
+                            description: entry.description.slice(0, 120),
+                        })),
+                    });
+                } catch (error) {
+                    sendJson(response, 500, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+
+        mount('/multimodal/restart', (request, response) => {
+            if (request.method !== 'POST' || sameOrigin(request) === false) {
+                sendJson(response, 403, { error: 'same-origin POST required' });
+                return;
+            }
+            void (async () => {
+                const result = await runtime.restartListeners();
+                sendJson(response, 200, { ...result, status: await statusOf() });
+            })();
+        });
+
+        /** 读一个产物文件给页面预览（只在本机产物目录内）。 */
+        mount('/multimodal/product', (request, response) => {
+            void (async () => {
+                const url = new URL(request.url ?? '/', 'http://localhost');
+                const name = url.searchParams.get('name') ?? '';
+                const dir = resolveOutputDir(settings.get());
+                if (name === '' || basename(name) !== name) {
+                    sendJson(response, 400, { ok: false, error: 'name 只能是文件名' });
+                    return;
+                }
+                const file = join(dir, name);
+                try {
+                    const buffer = await readFile(file);
+                    const lower = name.toLowerCase();
+                    const type = /\.(png)$/.test(lower)
+                        ? 'image/png'
+                        : /\.(jpe?g)$/.test(lower)
+                            ? 'image/jpeg'
+                            : /\.(webp)$/.test(lower)
+                                ? 'image/webp'
+                                : /\.(gif)$/.test(lower)
+                                    ? 'image/gif'
+                                    : /\.(mp4)$/.test(lower)
+                                        ? 'video/mp4'
+                                        : /\.(webm)$/.test(lower)
+                                            ? 'video/webm'
+                                            : 'application/octet-stream';
+                    response.writeHead(200, {
+                        'content-type': type,
+                        'content-length': String(buffer.length),
+                        'cache-control': 'private, max-age=60',
+                    });
+                    response.end(buffer);
+                } catch (error) {
+                    sendJson(response, 404, { ok: false, error: errorMessage(error) });
+                }
+            })();
+        });
+    }
+
+    // --- 智能体工具 -------------------------------------------------------
+    const tools = ctx.get('tools');
+    if (tools !== undefined) {
+        ctx.effect(() => tools.register(multimodalDefinition(runtime, { statusOf, parseFrames })), 'dsh-multimodal-node: tool');
+    }
+}
+
+export { MODES, defaultDataDir as dataDir } from './lib/config.js';