dsh-multimodal-node 0.0.0-stage → 0.3.1

package/lib/nodeapi.js

@@ -0,0 +1,491 @@
+/**
+ * 服务节点对外暴露的「用户节点」接口。
+ *
+ * 挂在 API 接入端口上（默认 8287），和 ComfyUI 自己的协议端点共用同一个监听：
+ * 用户节点要的模板、队列、模型，本来就是这台机器上任务池与工作流库的视图，
+ * 另开一个端口只会让「端口设错了」变成第二种故障。
+ *
+ * 路径一律以 `/node/` 开头。理由：ComfyUI 的协议占掉了 `/prompt`、`/queue`、`/history`、
+ * `/view`、`/object_info`，而 `/node/templates` 这种名字不可能和任何自定义节点撞车。
+ *
+ * 鉴权：`Authorization: Bearer <apikey>` / `X-API-Key` / `?apikey=`。服务节点没开校验时
+ * 放行但明确标注 `checked: false`——「没校验」和「校验通过」在审计里必须能分开。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { errorMessage, pipeGuarded, readJson, sendJson } from './http.js';
+import { ApiKeyStore } from './apikeys.js';
+import { classifyWorkflow, visibleTo } from './tiers.js';
+import { modelInventory } from './models.js';
+
+const MEDIA_MAX_BYTES = 512 * 1024 * 1024;
+
+/**
+ * 免凭据的路径。一处定义，两处引用（请求前的 guard 与路由内部的 authorize）。
+ *
+ * 只放两个：一个只会回 ok 的健康探针，一个只会报自己状态的 ping。
+ * 任何一个都要凭据的话，监控、反代健康检查、面板自己的连通性测试就都得先配一把 key，
+ * 而「配好 key 才能确认服务活着」是一个死循环。
+ */
+const OPEN_PATHS = new Set(['/health', '/node/ping']);
+
+/**
+ * @param {{ settings:()=>any, keys:ApiKeyStore, pool:object, instances:object,
+ *           library:object, runs:object, assets:object, blender:object,
+ *           gateway:object, log:Function }} deps
+ */
+export function createNodeRoutes(deps) {
+    /** 一次请求的凭据，失败就返回 401 并结束响应。null = 已结束。 */
+    const authorize = (request, response, url) => {
+        /**
+         * 开放路径先放行。
+         *
+         * gateway 在请求进门时已经判过一次（createApiGuard），但这里是第二个入口：
+         * 路由表也可能被人单独挂（测试、别的宿主、将来的反向代理中间件）。
+         * 两处判断必须用同一份白名单，否则就是「gateway 放行、路由再拦一次」——
+         * 表现为 /node/ping 莫名其妙回 401，而日志里一个字都没有。
+         */
+        if (OPEN_PATHS.has(url?.pathname ?? '')) {
+            return { ok: true, checked: false, key: null, tier: 'nsfw', name: null, open: true };
+        }
+        const raw = ApiKeyStore.extract(request.headers, url);
+        const result = deps.keys.verify(raw);
+        if (result.ok === true) return result;
+        sendJson(response, 401, {
+            ok: false,
+            error: result.error ?? '缺少 apikey',
+            authRequired: true,
+        });
+        return null;
+    };
+
+    /** 服务节点自己的机器摘要：用户节点连上来的第一件事就是看这个。 */
+    const ping = () => {
+        const snapshot = deps.pool.snapshot();
+        const inventory = modelInventory(deps.settings(), { withSize: false });
+        return {
+            ok: true,
+            plugin: 'dsh-multimodal-node',
+            mode: deps.settings().mode,
+            gateway: { port: deps.gateway.port, listening: deps.gateway.listening },
+            queue: {
+                queued: (snapshot.tasks ?? []).filter((task) => task.state === 'queued').length,
+                running: (snapshot.tasks ?? []).filter((task) => task.state === 'running').length,
+                dynamic: snapshot.dynamic === true,
+                estimateMs: snapshot.estimate?.makespanMs ?? 0,
+            },
+            instances: (snapshot.instances ?? []).map((entry) => ({
+                id: entry.id,
+                label: entry.label,
+                healthy: entry.healthy,
+                enabled: entry.enabled,
+                maxConcurrent: entry.maxConcurrent,
+                devices: entry.devices,
+            })),
+            models: { total: inventory.total ?? 0, folders: (inventory.folders ?? []).length, error: inventory.error ?? null },
+            blender: (() => {
+                const payload = deps.blender?.statusPayload?.() ?? { instances: [] };
+                return {
+                    enabled: payload.enabled === true,
+                    instances: (payload.instances ?? []).map((entry) => ({
+                        id: entry.id,
+                        label: entry.label,
+                        kind: entry.kind,
+                        healthy: entry.healthy,
+                        running: entry.running,
+                    })),
+                };
+            })(),
+            now: new Date().toISOString(),
+        };
+    };
+
+    /** 模板列表按 key 的 tier 过滤：SFW 的 key 连成人模板的名字都不给看。 */
+    const templates = (tier) => {
+        const library = deps.library;
+        if (library === null || library === undefined) return { ok: false, error: '工作流库还没就绪', templates: [] };
+        const rows = library.list(tier);
+        return {
+            ok: true,
+            tier,
+            templates: rows.map((row) => {
+                const full = library.get(row.id);
+                const described = full === undefined ? null : library.describe(full);
+                return {
+                    id: row.id,
+                    name: row.name,
+                    category: row.category,
+                    tier: row.tier,
+                    nodeCount: row.nodeCount,
+                    updatedAt: row.updatedAt,
+                    needsText: described?.needsText ?? null,
+                    promptBoxes: (described?.promptBoxes ?? []).map((box) => ({
+                        nodeId: box.nodeId,
+                        input: box.input,
+                        role: box.role,
+                        head: box.head ?? '',
+                        layers: box.layers ?? [],
+                    })),
+                    images: (described?.images ?? []).length,
+                    params: (described?.paramPicks ?? []).map((entry) => entry.name ?? entry),
+                };
+            }),
+        };
+    };
+
+    const queueView = () => {
+        const snapshot = deps.pool.snapshot();
+        return {
+            ok: true,
+            dynamic: snapshot.dynamic === true,
+            counters: snapshot.counters ?? {},
+            estimateMs: snapshot.estimate?.makespanMs ?? 0,
+            tasks: (snapshot.tasks ?? []).map((task) => ({
+                id: task.id,
+                state: task.state,
+                backendId: task.backendId ?? null,
+                cost: task.cost,
+                priority: task.priority,
+                enqueuedAt: task.enqueuedAt,
+                startedAt: task.startedAt ?? null,
+                finishedAt: task.finishedAt ?? null,
+                error: task.error ?? null,
+            })),
+        };
+    };
+
+    /**
+     * 提交一次任务。
+     *
+     * 分级在这里兜底：`/prompt` 本身不审查（程序发的就是要的），但**带 key 的调用**必须
+     * 按 key 的 tier 判一次——否则给某人发一把 SFW 的 key 等于没发。
+     */
+    const submit = (request, response, auth) => {
+        void (async () => {
+            let body;
+            try {
+                body = await readJson(request);
+            } catch (error) {
+                sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                return;
+            }
+            if (auth.checked === true && auth.tier !== 'nsfw') {
+                const classification = classifyWorkflow({ api: body?.prompt ?? {}, name: body?.extra_data?.workflowName ?? '' });
+                if (!visibleTo(auth.tier, classification.tier)) {
+                    deps.log('warn', `apikey ${auth.name} 提交了成人工作流，已按 tier=sfw 拒绝`);
+                    sendJson(response, 403, {
+                        ok: false,
+                        error: '这个 apikey 的分级是 SFW，不能提交成人内容的工作流',
+                        tier: auth.tier,
+                        reason: classification.reason,
+                    });
+                    return;
+                }
+            }
+            try {
+                const reply = deps.pool.enqueue(body);
+                sendJson(response, 200, reply);
+            } catch (error) {
+                sendJson(response, 400, { ok: false, error: errorMessage(error), node_errors: {} });
+            }
+        })();
+    };
+
+    const poolAction = (request, response, auth) => {
+        void (async () => {
+            const body = await readJson(request).catch(() => ({}));
+            const action = String(body?.action ?? '');
+            try {
+                if (action === 'dynamic') {
+                    deps.pool.toggleDynamic(body.enabled === true);
+                    sendJson(response, 200, { ok: true, dynamic: deps.settings().dynamic });
+                    return;
+                }
+                if (action === 'cancel') {
+                    sendJson(response, 200, { ...deps.pool.cancel(String(body.id ?? '')) });
+                    return;
+                }
+                if (action === 'prioritize') {
+                    sendJson(response, 200, { ...deps.pool.prioritize(String(body.id ?? ''), body.delta ?? 1) });
+                    return;
+                }
+                if (action === 'free') {
+                    // 释放显存是运维动作：SFW 的 key 不许把人家的模型从卡上踢下去。
+                    if (auth.checked === true && auth.tier !== 'nsfw') {
+                        sendJson(response, 403, { ok: false, error: '这个 apikey 的分级是 SFW，不能释放显存' });
+                        return;
+                    }
+                    await Promise.all(
+                        deps.instances.enabled().map(async (runtime) => {
+                            try {
+                                await deps.pool.backend(runtime).free({ unload_models: true, free_memory: true });
+                            } catch {
+                                // 睡着的实例没有可释放的东西
+                            }
+                        }),
+                    );
+                    sendJson(response, 200, { ok: true });
+                    return;
+                }
+                if (action === 'clearQueue') {
+                    for (const task of deps.pool.ordered()) deps.pool.cancel(task.id);
+                    sendJson(response, 200, { ok: true });
+                    return;
+                }
+                sendJson(response, 400, { ok: false, error: `未知动作 ${action}` });
+            } catch (error) {
+                sendJson(response, 400, { ok: false, error: errorMessage(error) });
+            }
+        })();
+    };
+
+    /** 历史：不带 id 给最近 N 条，带 id 给这一条。 */
+    const history = (url, path) => {
+        const suffix = path.slice('/node/history'.length).replace(/^\//, '');
+        const snapshot = deps.pool.snapshot();
+        if (suffix !== '') {
+            const id = decodeURIComponent(suffix);
+            const task = (snapshot.tasks ?? []).find((entry) => entry.id === id);
+            if (task === undefined) return { ok: false, error: `没有任务 ${id}` };
+            return { ok: true, task };
+        }
+        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit') ?? '40') || 40));
+        return {
+            ok: true,
+            finished: (snapshot.tasks ?? []).filter((task) => task.state === 'done' || task.state === 'failed' || task.state === 'cancelled').slice(0, limit),
+        };
+    };
+
+    /**
+     * 产物下载。
+     *
+     * 只接受 `prompt_id` + 文件名，由服务端自己去实例上取——用户节点不该知道、也不该能访问
+     * 8188/8189。文件名做路径段校验，防止 `../../`。
+     */
+    const media = (url, request, response, auth) => {
+        void (async () => {
+            if (auth.checked === true && auth.tier !== 'nsfw') {
+                // 产物本身归提交者，但一个 SFW 的 key 不该能把成人图拉走。
+                // 判定用文件名 + 归属任务的工作流名，取得到就判，取不到就只按文件名。
+                const name = url.searchParams.get('file') ?? '';
+                const hit = classifyWorkflow({ name });
+                if (!visibleTo(auth.tier, hit.tier)) {
+                    sendJson(response, 403, { ok: false, error: '这个 apikey 的分级是 SFW，不能取回这个产物' });
+                    return;
+                }
+            }
+            const promptId = url.searchParams.get('prompt_id') ?? '';
+            const filename = url.searchParams.get('file') ?? url.searchParams.get('filename') ?? '';
+            if (filename === '') {
+                sendJson(response, 400, { ok: false, error: '缺少 file 参数' });
+                return;
+            }
+            if (basename(filename) !== filename) {
+                sendJson(response, 400, { ok: false, error: 'file 只能是文件名，不能带路径' });
+                return;
+            }
+            const subfolder = url.searchParams.get('subfolder') ?? '';
+            const type = url.searchParams.get('type') ?? 'output';
+            const query = new URLSearchParams({ filename, subfolder, type }).toString();
+            const ordered = [];
+            if (promptId !== '') {
+                const task = deps.pool.tasks.get(promptId);
+                const runtime = task?.backendId ? deps.instances.get(task.backendId) : undefined;
+                if (runtime !== undefined) ordered.push(runtime);
+            }
+            for (const runtime of deps.instances.enabled()) {
+                if (!ordered.includes(runtime)) ordered.push(runtime);
+            }
+            let lastError = '没有实例持有这个文件';
+            for (const runtime of ordered) {
+                try {
+                    // 先探大小，超过上限就不往下拉：一个 4 GB 的 mp4 拖进用户节点的内存不会报错，
+                    // 只会让进程被系统杀掉。
+                    const head = await deps.pool.backend(runtime).openView(query, 'HEAD');
+                    const length = Number(head.headers.get('content-length') ?? '0');
+                    if (Number.isFinite(length) && length > MEDIA_MAX_BYTES) {
+                        sendJson(response, 413, { ok: false, error: `产物 ${Math.round(length / 1048576)} MB 超过单次上限 ${Math.round(MEDIA_MAX_BYTES / 1048576)} MB` });
+                        return;
+                    }
+                    const stream = await deps.pool.backend(runtime).openView(query, 'GET', request.headers.range);
+                    const headers = {
+                        'content-type': stream.headers.get('content-type') ?? 'application/octet-stream',
+                        'cache-control': 'private, max-age=600',
+                    };
+                    for (const key of ['content-length', 'content-range', 'accept-ranges']) {
+                        const value = stream.headers.get(key);
+                        if (value !== null) headers[key] = value;
+                    }
+                    response.writeHead(stream.status, headers);
+                    if (stream.body === null) {
+                        response.end();
+                        return;
+                    }
+                    pipeGuarded(stream.body, response);
+                    return;
+                } catch (error) {
+                    lastError = errorMessage(error);
+                }
+            }
+            sendJson(response, 404, { ok: false, error: lastError });
+        })();
+    };
+
+    /** 模型清单。SFW 的 key 只拿到目录名，不拿文件名——和 03 号控制台同一条规则。 */
+    const models = (auth) => {
+        const inventory = modelInventory(deps.settings(), { withSize: true });
+        if (auth.checked === false || auth.tier === 'nsfw') return { ok: inventory.ok !== false, ...inventory };
+        return {
+            ok: inventory.ok !== false,
+            ...inventory,
+            folders: (inventory.folders ?? []).map((folder) => ({ ...folder, items: [] })),
+            total: 0,
+            locked: true,
+            error: '这个 apikey 的分级是 SFW，不列出模型文件名',
+        };
+    };
+
+    /**
+     * Blender：查列表、提交渲染、取消、看日志。
+     *
+     * 用户节点在侧边栏的 Blender 板块里点「渲染」，走的就是这里——它不是服务节点独占的，
+     * 否则「用户节点用服务节点的算力」这件事在 Blender 上就断了。
+     */
+    const blenderRoutes = (request, response, url, path, method, auth) => {
+        if (deps.blender === undefined) return undefined;
+        if (path === '/node/blender' && method === 'GET') {
+            sendJson(response, 200, { ok: true, ...deps.blender.statusPayload() });
+            return true;
+        }
+        if (path === '/node/blender/render' && method === 'POST') {
+            void (async () => {
+                const body = await readJson(request).catch(() => ({}));
+                if (auth.checked === true && auth.tier !== 'nsfw' && body?.scene !== undefined) {
+                    const hit = classifyWorkflow({ name: String(body.scene ?? '') });
+                    if (!visibleTo(auth.tier, hit.tier)) {
+                        sendJson(response, 403, { ok: false, error: '这个 apikey 的分级是 SFW，不能提交这个 Blender 工程' });
+                        return;
+                    }
+                }
+                try {
+                    const instanceId = String(body.instanceId ?? '');
+                    if (instanceId === '') {
+                        sendJson(response, 400, { ok: false, error: '缺少 instanceId' });
+                        return;
+                    }
+                    const result = await deps.blender.submit(instanceId, body);
+                    sendJson(response, 200, result);
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+            return true;
+        }
+        if (path === '/node/blender/cancel' && method === 'POST') {
+            void (async () => {
+                const body = await readJson(request).catch(() => ({}));
+                try {
+                    const result = await deps.blender.cancel(String(body.instanceId ?? ''), String(body.jobId ?? ''));
+                    sendJson(response, 200, result);
+                } catch (error) {
+                    sendJson(response, 400, { ok: false, error: errorMessage(error) });
+                }
+            })();
+            return true;
+        }
+        if (path === '/node/blender/blends' && method === 'GET') {
+            const dir = url.searchParams.get('dir') ?? '';
+            sendJson(response, 200, { ok: true, files: deps.blender.browseBlends(dir) });
+            return true;
+        }
+        return undefined;
+    };
+
+    /**
+     * 唯一的入口。返回 true = 已经处理并写完响应，gateway 不要再往下走。
+     *
+     * 挂一个 bindLibrary：工作流库、运行索引、资产库在 index.js 里比本函数晚建好，
+     * 而闭包读的是 deps 上的字段，所以后补即可——不需要重新构造一遍路由表。
+     */
+    const handle = function handle(request, response, url, path, method) {
+        if (!path.startsWith('/node/')) return false;
+        const auth = authorize(request, response, url);
+        if (auth === null) return true;
+
+        if (path === '/node/ping') {
+            sendJson(response, 200, ping());
+            return true;
+        }
+        if (path === '/node/templates') {
+            sendJson(response, 200, templates(auth.checked === true ? auth.tier : 'nsfw'));
+            return true;
+        }
+        if (path === '/node/models') {
+            sendJson(response, 200, models(auth));
+            return true;
+        }
+        if (path === '/node/queue') {
+            sendJson(response, 200, queueView());
+            return true;
+        }
+        if (path === '/node/history' || path.startsWith('/node/history/')) {
+            sendJson(response, 200, history(url, path));
+            return true;
+        }
+        if (path === '/node/pool' && method === 'POST') {
+            poolAction(request, response, auth);
+            return true;
+        }
+        if (path === '/node/prompt' && method === 'POST') {
+            submit(request, response, auth);
+            return true;
+        }
+        if (path === '/node/media') {
+            media(url, request, response, auth);
+            return true;
+        }
+        if (blenderRoutes(request, response, url, path, method, auth) === true) return true;
+
+        sendJson(response, 404, { ok: false, error: `没有这个用户节点接口：${path}` });
+        return true;
+    };
+
+    handle.bindLibrary = (libs) => {
+        if (libs.library !== undefined) deps.library = libs.library;
+        if (libs.runs !== undefined) deps.runs = libs.runs;
+        if (libs.assets !== undefined) deps.assets = libs.assets;
+    };
+
+    return handle;
+}
+
+/**
+ * API 接入端口的统一闸门。
+ *
+ * 返回 { ok, checked, tier, name, error }。gateway 在每个请求进来时调一次，
+ * 把结果挂到 request.dshAuth 上供后续分支使用。
+ *
+ * 白名单是故意的：一个只会回 "ok" 的健康探针不该要凭据，否则任何一次端口探测
+ * （监控、反代健康检查、面板自己的连通性测试）都得先配一把 key。
+ */
+export function createApiGuard(keys) {
+    return (request, url) => {
+        const path = url?.pathname ?? '/';
+        if (OPEN_PATHS.has(path)) return { ok: true, checked: false, tier: 'nsfw', name: null, open: true };
+        // CORS 预检不带凭据，浏览器不发 Authorization。
+        if (request.method === 'OPTIONS') return { ok: true, checked: false, tier: 'nsfw', name: null, preflight: true };
+        const raw = ApiKeyStore.extract(request.headers, url);
+        const result = keys.verify(raw);
+        if (result.ok === true) return result;
+        return { ok: false, checked: true, error: result.error ?? '缺少 apikey' };
+    };
+}
+
+/** 从库里读一个文件的内容（模板可能要带上完整 JSON 给用户节点自己解析）。 */
+export async function readLibraryFile(library, id) {
+    const record = library.get(id);
+    if (record === undefined) throw new Error(`没有工作流 ${id}`);
+    return record;
+}
+
+export { MEDIA_MAX_BYTES, OPEN_PATHS };

package/lib/nodeclient.js

@@ -0,0 +1,143 @@
+/**
+ * 用户节点 → 服务节点的客户端。
+ *
+ * 用户在侧边栏看到的三样东西全部来自服务节点：工作流模板、当前队列、模型列表。
+ * 这三件事都只有一个入口——服务节点的 API 端口，带 apikey。本机不发任何别的东西。
+ *
+ * 三条设计约束：
+ *
+ *  1. **不代理媒体**。产物落到本机目录是靠「服务端给地址，本机去拉」，不是把整个
+ *     ComfyUI 的传输层搬过来。拉取有大小上限，失败就报清楚是哪一步。
+ *  2. **错误要能定位**。连不上 / 401 / 地址没填 是三种完全不同的事，面板上必须分开说，
+ *     否则用户唯一能做的就是重启。
+ *  3. **超时短**。侧边栏是被人反复点的地方，5 秒没答案就该说「服务节点没响应」，
+ *     而不是转圈到天荒地老。
+ */
+import { errorMessage } from './http.js';
+
+export class NodeClient {
+    /** @param {() => any} getSettings */
+    constructor(getSettings) {
+        this.getSettings = getSettings;
+    }
+
+    get block() {
+        return this.getSettings()?.node ?? {};
+    }
+
+    get configured() {
+        const block = this.block;
+        return typeof block.publicUrl === 'string' && block.publicUrl !== '';
+    }
+
+    base() {
+        const url = String(this.block.publicUrl ?? '').trim();
+        if (url === '') throw new Error('还没有填服务节点的公网地址');
+        return url.replace(/\/+$/, '');
+    }
+
+    timeout() {
+        const value = Number(this.block.timeoutMs);
+        return Number.isFinite(value) ? value : 15000;
+    }
+
+    headers(extra = {}) {
+        const headers = { ...extra };
+        const key = String(this.block.apiKey ?? '').trim();
+        if (key !== '') headers.authorization = `Bearer ${key}`;
+        const label = String(this.block.label ?? '').trim();
+        if (label !== '') headers['x-node-label'] = label;
+        return headers;
+    }
+
+    async call(path, options = {}) {
+        if (!this.configured) throw new Error('还没有填服务节点的公网地址');
+        const target = `${this.base()}${path}`;
+        const method = options.method ?? 'GET';
+        let reply;
+        try {
+            reply = await fetch(target, {
+                method,
+                headers: this.headers(options.headers),
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? this.timeout()),
+            });
+        } catch (error) {
+            // fetch 把 DNS 失败、拒绝连接、超时都报成 "fetch failed"，这一点必须拆开说，
+            // 否则面板上只会显示一句没用的英文。
+            const reason = errorMessage(error);
+            if (/abort|timeout/i.test(reason)) throw new Error(`服务节点 ${target} 没有响应（超时）`);
+            throw new Error(`连不上服务节点 ${target}：${reason}`);
+        }
+        const text = await reply.text();
+        if (reply.status === 401 || reply.status === 403) {
+            throw new Error(`服务节点拒绝了这个 apikey（HTTP ${reply.status}）：检查设置页里填的 key`);
+        }
+        let parsed;
+        try {
+            parsed = text === '' ? {} : JSON.parse(text);
+        } catch {
+            throw new Error(`服务节点返回的不是 JSON（HTTP ${reply.status}）：${text.slice(0, 160)}`);
+        }
+        if (!reply.ok) throw new Error(parsed?.error ?? `服务节点返回 HTTP ${reply.status}`);
+        return parsed;
+    }
+
+    /** 侧边栏顶部的连通性卡片：一次请求拿到端口、模式、队列长度、模型数。 */
+    async probe() {
+        if (!this.configured) {
+            return { ok: false, configured: false, error: '还没有填服务节点的公网地址' };
+        }
+        try {
+            const data = await this.call('/node/ping');
+            return { ok: true, configured: true, ...data };
+        } catch (error) {
+            return { ok: false, configured: true, error: errorMessage(error) };
+        }
+    }
+
+    async templates() {
+        const data = await this.call('/node/templates');
+        return Array.isArray(data.templates) ? data.templates : [];
+    }
+
+    async queue() {
+        const data = await this.call('/node/queue');
+        return data;
+    }
+
+    async models() {
+        const data = await this.call('/node/models');
+        return data;
+    }
+
+    async submit(payload) {
+        return this.call('/prompt', { method: 'POST', body: payload, timeoutMs: 60000 });
+    }
+
+    async history(promptId) {
+        const suffix = promptId === undefined ? '' : `/${encodeURIComponent(promptId)}`;
+        return this.call(`/node/history${suffix}`);
+    }
+
+    /** 取消 / 插队 / 释放显存：动作名与被控对象一起递过去。 */
+    async pool(action, body = {}) {
+        return this.call('/node/pool', { method: 'POST', body: { action, ...body } });
+    }
+
+    /** 把产物拉到本机：只接受服务端明确列出来的文件名。 */
+    async fetchOutput(promptId, filename, saveTo) {
+        if (!this.configured) throw new Error('还没有填服务节点的公网地址');
+        const query = new URLSearchParams({ prompt_id: promptId, file: filename }).toString();
+        const target = `${this.base()}/node/media?${query}`;
+        const reply = await fetch(target, { headers: this.headers(), signal: AbortSignal.timeout(120000) });
+        if (!reply.ok) throw new Error(`拉取产物失败 HTTP ${reply.status}`);
+        const { writeFile, mkdir } = await import('node:fs/promises');
+        const { dirname, join } = await import('node:path');
+        const file = join(saveTo, filename.replace(/[\\/]/g, '_'));
+        await mkdir(dirname(file), { recursive: true });
+        const buffer = Buffer.from(await reply.arrayBuffer());
+        await writeFile(file, buffer);
+        return { file, bytes: buffer.length };
+    }
+}