dsh-comfyui 0.5.0 → 0.5.2

package/lib/analyze.d.ts

@@ -20,7 +20,9 @@ export interface GraphGroupLike {
 }
 export interface GraphLike {
     nodes: GraphNodeLike[];
-    links: Array<[number, number, number, number, number, string] | number[]>;
+    /** Saved rows are positional or object entries depending on the frontend
+     * version — always consumed through {@link normalizeLinks}. */
+    links: unknown[];
     groups?: GraphGroupLike[];
 }
 export interface IsolatedNode {

package/lib/analyze.js

@@ -5,6 +5,7 @@
  * graph links (with bypassed and dangling nodes excluded). The analysis feeds
  * the extract (拆分) choices in the panel and the agent-facing skill.
  */
+import { normalizeLinks } from './graph.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -27,7 +28,7 @@ export function analyzeGraph(graph) {
         return { ok: false, error: '无法解析图文件（缺少 nodes/links）' };
     }
     const nodes = graph.nodes;
-    const links = graph.links;
+    const links = normalizeLinks(graph.links);
     const groups = Array.isArray(graph.groups) ? graph.groups : [];
     const active = nodes.filter((node) => node.mode !== 4);
     const activeById = new Map(active.map((node) => [node.id, node]));
@@ -43,14 +44,36 @@ export function analyzeGraph(graph) {
     const isolated = active
         .filter((node) => !linkedIds.has(node.id))
         .map((node) => ({ id: node.id, type: node.type }));
+    // Bypassed nodes are pass-throughs at conversion time (resolveOrigin in
+    // convert.ts: the output follows the FIRST wired input). Mirror that rule
+    // here, or a chain `120 → [406 bypassed] → 119` splits into two components
+    // and "main flow" extraction ships 119 referencing a node it left out
+    // (Issue #8).
+    const linkById = new Map(links.map((link) => [link[0], link]));
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    const passThroughOrigin = (originId) => {
+        let current = originId;
+        const visited = new Set();
+        while (nodeById.get(current)?.mode === 4) {
+            if (visited.has(current))
+                return undefined;
+            visited.add(current);
+            const inputLink = (nodeById.get(current)?.inputs ?? []).find((entry) => entry.link !== null)?.link;
+            const upstream = inputLink === undefined || inputLink === null ? undefined : linkById.get(inputLink);
+            if (upstream === undefined)
+                return undefined;
+            current = upstream[1];
+        }
+        return current;
+    };
     // Connected components over linked active nodes.
     const adjacency = new Map();
     for (const node of active)
         adjacency.set(node.id, new Set());
     for (const link of links) {
-        const a = link[1];
+        const a = passThroughOrigin(link[1]);
         const b = link[3];
-        if (typeof a !== 'number' || typeof b !== 'number')
+        if (a === undefined)
             continue;
         if (!adjacency.has(a) || !adjacency.has(b))
             continue;

package/lib/comfyui.d.ts

@@ -109,7 +109,10 @@ export declare class ComfyUIClient {
     private readonly connectTimeoutMs;
     private readonly maxMediaBytes;
     constructor(baseUrl: string, apiKey: string | undefined, connectTimeoutMs: number, maxMediaBytes: number);
+    private base;
     private endpoint;
+    /** fetch() one route, retrying a 404 under /api until the prefix is known. */
+    private fetchRoute;
     private request;
     /** Best-effort GET of an arbitrary JSON endpoint on the ComfyUI server.
      *

package/lib/comfyui.js

@@ -62,6 +62,14 @@ export function guessContentType(filename) {
 }
 /** The per-process client id ComfyUI uses to correlate queued prompts. */
 export const CLIENT_ID = randomUUID();
+/**
+ * Route prefix learned per base URL: '' when bare routes answer, '/api' when
+ * only the /api-prefixed mirror does. ComfyUI serves every route under both,
+ * but API-only reverse proxies (comfy-api-proxy, Issue #6) forward just
+ * `/api/*`, so the bare /system_stats probe 404s. Learned on the first
+ * request and kept for the process — clients are created per call.
+ */
+const routePrefix = new Map();
 /** HTTP client over the ComfyUI REST API. */
 export class ComfyUIClient {
     baseUrl;
@@ -74,8 +82,34 @@ export class ComfyUIClient {
         this.connectTimeoutMs = connectTimeoutMs;
         this.maxMediaBytes = maxMediaBytes;
     }
+    base() {
+        return this.baseUrl.replace(/\/+$/, '');
+    }
     endpoint(path) {
-        return `${this.baseUrl.replace(/\/+$/, '')}${path}`;
+        if (path.startsWith('/api/'))
+            return `${this.base()}${path}`;
+        return `${this.base()}${routePrefix.get(this.base()) ?? ''}${path}`;
+    }
+    /** fetch() one route, retrying a 404 under /api until the prefix is known. */
+    async fetchRoute(path, init) {
+        const base = this.base();
+        const response = await fetch(this.endpoint(path), init);
+        if (path.startsWith('/api/') || routePrefix.has(base))
+            return response;
+        if (response.ok) {
+            routePrefix.set(base, '');
+            return response;
+        }
+        if (response.status !== 404)
+            return response;
+        const retry = await fetch(`${base}/api${path}`, init);
+        if (!retry.ok) {
+            await retry.body?.cancel();
+            return response;
+        }
+        routePrefix.set(base, '/api');
+        await response.body?.cancel();
+        return retry;
     }
     async request(path, init = {}, timeoutMs) {
         const controller = new AbortController();
@@ -84,7 +118,7 @@ export class ComfyUIClient {
             const headers = { ...init.headers };
             if (this.apiKey !== undefined)
                 headers['Authorization'] = `Bearer ${this.apiKey}`;
-            const response = await fetch(this.endpoint(path), { ...init, headers, signal: controller.signal });
+            const response = await this.fetchRoute(path, { ...init, headers, signal: controller.signal });
             if (!response.ok) {
                 const body = await response.text().catch(() => '');
                 throw new ComfyUIError(`ComfyUI ${path} failed: HTTP ${response.status}${body !== '' ? ` — ${body.slice(0, 300)}` : ''}`, response.status);
@@ -284,7 +318,28 @@ export class ComfyUIClient {
     }
     /** List one user-data subdirectory (e.g. 'workflows') on the ComfyUI server. */
     async listUserData(subdir) {
-        const data = await this.request(`/v2/userdata?path=${encodeURIComponent(subdir)}`);
+        let data;
+        try {
+            data = await this.request(`/v2/userdata?path=${encodeURIComponent(subdir)}`);
+        }
+        catch (error) {
+            // Some builds (e.g. the 0.35 desktop app, Issue #5) have no /v2/userdata;
+            // the v1 listing takes `dir` and returns paths relative to it.
+            if (!(error instanceof ComfyUIError) || error.status !== 404)
+                throw error;
+            const legacy = await this.request(`/userdata?dir=${encodeURIComponent(subdir)}&recurse=true&split=false&full_info=true`);
+            if (!Array.isArray(legacy))
+                return [];
+            return legacy.map((item) => {
+                const rel = (typeof item === 'string' ? item : item.path).replace(/\\/g, '/');
+                const entry = { name: rel, path: `${subdir}/${rel}`, type: 'file' };
+                if (typeof item !== 'string' && item.size !== undefined)
+                    entry.size = item.size;
+                if (typeof item !== 'string' && item.modified !== undefined)
+                    entry.modified = item.modified;
+                return entry;
+            });
+        }
         if (!Array.isArray(data))
             return [];
         if (typeof data[0] === 'string') {
@@ -319,7 +374,7 @@ export class ComfyUIClient {
             const headers = {};
             if (this.apiKey !== undefined)
                 headers['Authorization'] = `Bearer ${this.apiKey}`;
-            const response = await fetch(this.endpoint(`/view?${params.toString()}`), { headers, signal: controller.signal });
+            const response = await this.fetchRoute(`/view?${params.toString()}`, { headers, signal: controller.signal });
             if (!response.ok) {
                 throw new ComfyUIError(`ComfyUI /view failed: HTTP ${response.status}`);
             }
@@ -352,7 +407,7 @@ export class ComfyUIClient {
                 headers['Authorization'] = `Bearer ${this.apiKey}`;
             if (rangeHeader !== undefined)
                 headers['Range'] = rangeHeader;
-            const response = await fetch(this.endpoint(`/view?${params.toString()}`), { headers, method, signal: controller.signal });
+            const response = await this.fetchRoute(`/view?${params.toString()}`, { headers, method, signal: controller.signal });
             if (response.status !== 206 && response.status !== 416 && !response.ok) {
                 throw new ComfyUIError(`ComfyUI /view failed: HTTP ${response.status}`);
             }

package/lib/convert.d.ts

@@ -1,12 +1,3 @@
-/**
- * Convert a ComfyUI UI-graph workflow (the format the ComfyUI frontend saves
- * to the server via /api/userdata) into the API format accepted by POST
- * /prompt. Modeled on the frontend's convertToApiFormat: input links become
- * [nodeId, slot] references, widgets_values are zipped onto input names in
- * object_info order (control_after_generate is the extra seed widget), and
- * Reroute / bypassed (mode 4) nodes are skipped with their links rewired.
- * Nodes the conversion cannot represent fail loudly with the offending type.
- */
 export interface ApiWorkflow {
     [nodeId: string]: {
         class_type: string;
@@ -21,6 +12,18 @@ export type ConvertResult = {
     ok: false;
     error: string;
 };
+/**
+ * Flatten DynamicCombo values that 0.2.0–0.5.1 extraction wrapped as
+ * `{ key, inputs: { sub: value } }` back into the flat API shape
+ * (`master: key`, `master.sub: value`, recursively). Library entries saved by
+ * those versions still carry the wrapped shape; normalizing at queue time
+ * heals them without asking users to re-extract (Issue #10). Returns the same
+ * object when nothing needed flattening.
+ */
+export declare function flattenDynamicCombos<W extends Record<string, {
+    class_type: string;
+    inputs: Record<string, unknown>;
+}>>(workflow: W): W;
 /**
  * Convert a UI-graph workflow (or one extracted component of it) to API
  * format using the live node definitions.

package/lib/convert.js

@@ -1,3 +1,13 @@
+/**
+ * Convert a ComfyUI UI-graph workflow (the format the ComfyUI frontend saves
+ * to the server via /api/userdata) into the API format accepted by POST
+ * /prompt. Modeled on the frontend's convertToApiFormat: input links become
+ * [nodeId, slot] references, widgets_values are zipped onto input names in
+ * object_info order (control_after_generate is the extra seed widget), and
+ * Reroute / bypassed (mode 4) nodes are skipped with their links rewired.
+ * Nodes the conversion cannot represent fail loudly with the offending type.
+ */
+import { normalizeLinks } from './graph.js';
 /** Node types that exist only in the UI and carry no data flow. */
 const UI_ONLY = new Set(['Note', 'StickyNote', 'Reroute', 'Fast Groups Bypasser (rgthree)']);
 function isObject(value) {
@@ -20,6 +30,51 @@ function inputSpec(objectInfo, classType, name) {
     }
     return undefined;
 }
+/** Option keys a COMFY_DYNAMICCOMBO_V3 spec declares, or undefined when unreadable. */
+function dynamicComboKeys(spec) {
+    const options = isObject(spec[1]) ? spec[1].options : undefined;
+    if (!Array.isArray(options))
+        return undefined;
+    const keys = options
+        .map((option) => (isObject(option) ? option.key : undefined))
+        .filter((key) => typeof key === 'string');
+    return keys.length > 0 ? keys : undefined;
+}
+/**
+ * Flatten DynamicCombo values that 0.2.0–0.5.1 extraction wrapped as
+ * `{ key, inputs: { sub: value } }` back into the flat API shape
+ * (`master: key`, `master.sub: value`, recursively). Library entries saved by
+ * those versions still carry the wrapped shape; normalizing at queue time
+ * heals them without asking users to re-extract (Issue #10). Returns the same
+ * object when nothing needed flattening.
+ */
+export function flattenDynamicCombos(workflow) {
+    const isWrapped = (value) => isObject(value) && typeof value.key === 'string' && isObject(value.inputs)
+        && Object.keys(value).every((k) => k === 'key' || k === 'inputs');
+    const flatten = (prefix, value, into) => {
+        if (!isWrapped(value)) {
+            into[prefix] = value;
+            return;
+        }
+        into[prefix] = value.key;
+        for (const [sub, subValue] of Object.entries(value.inputs))
+            flatten(`${prefix}.${sub}`, subValue, into);
+    };
+    let changed = false;
+    const out = {};
+    for (const [id, node] of Object.entries(workflow)) {
+        if (!Object.values(node.inputs).some(isWrapped)) {
+            out[id] = node;
+            continue;
+        }
+        changed = true;
+        const inputs = {};
+        for (const [name, value] of Object.entries(node.inputs))
+            flatten(name, value, inputs);
+        out[id] = { ...node, inputs };
+    }
+    return changed ? out : workflow;
+}
 /**
  * Derive the ordered widget-input names for one node. The graph's own input
  * array is the source of truth — widgets_values is stored in UI widget order,
@@ -195,13 +250,11 @@ export function convertGraphToApi(graph, objectInfo, options) {
         };
     });
     const links = new Map();
-    for (const raw of rawLinks) {
-        if (!Array.isArray(raw) || raw.length < 6)
-            continue;
-        const link = raw;
-        if (typeof link[0] === 'number')
-            links.set(link[0], link);
-    }
+    // normalizeLinks accepts both the legacy positional rows and the v0.4
+    // frontend's object entries; anything unreadable is skipped, exactly like
+    // the old array-only guard did.
+    for (const link of normalizeLinks(rawLinks))
+        links.set(link[0], link);
     const nodesById = new Map(nodes.map((node) => [node.id, node]));
     const included = options?.includeNodeIds;
     const candidates = included !== undefined ? nodes.filter((node) => included.has(node.id)) : nodes;
@@ -281,27 +334,48 @@ export function convertGraphToApi(graph, objectInfo, options) {
                     inputs[name] = value;
             }
         }
-        // Collapse DynamicCombo V3 flat keys back into the API object shape:
-        // { key, inputs: { subWidget: value } } — the master combo's value is the
-        // selected option key, and its `master.sub` siblings become the sub-inputs.
+        // DynamicCombo V3 stays FLAT in the API prompt: the master input holds the
+        // selected option key as a string and its sub-widgets sit beside it as
+        // `master.sub` keys. The server rebuilds the nested shape itself
+        // (DynamicCombo._expand_schema_for_dynamic matches the plain value against
+        // option keys); wrapping it as { key, inputs } never matches, the input is
+        // dropped, and the node dies at execute() — Issue #10 (SaveVideo 'codec').
+        // Validate the selected key here so a bad value fails at extraction rather
+        // than after a full generation.
         for (const [name, value] of Object.entries(inputs)) {
             const spec = inputSpec(objectInfo, node.type, name);
             if (!Array.isArray(spec) || spec[0] !== 'COMFY_DYNAMICCOMBO_V3')
                 continue;
-            const sub = {};
-            for (const [other, otherValue] of Object.entries(inputs)) {
-                if (other.startsWith(`${name}.`))
-                    sub[other.slice(name.length + 1)] = otherValue;
+            const keys = dynamicComboKeys(spec);
+            if (keys === undefined || Array.isArray(value))
+                continue;
+            if (typeof value !== 'string' || !keys.includes(value)) {
+                return {
+                    ok: false,
+                    error: `节点 ${node.type}（id ${node.id}）的输入 ${name} 取值 ${JSON.stringify(value)} 不是可选项之一（${keys.join(' / ')}）——请在 ComfyUI 画布上重新选择后再提取`,
+                };
             }
-            inputs[name] = { key: value, inputs: sub };
-            for (const subName of Object.keys(sub))
-                delete inputs[`${name}.${subName}`];
         }
         workflow[String(node.id)] = { class_type: node.type, inputs };
     }
     if (Object.keys(workflow).length === 0) {
         return { ok: false, error: '转换结果为空（图中没有可执行的节点）' };
     }
+    // Reference integrity: every link must point at a node of this same output.
+    // A component that leaves out an upstream node would otherwise extract as
+    // ok and only fail at run time (Issue #8).
+    for (const [id, node] of Object.entries(workflow)) {
+        for (const [name, value] of Object.entries(node.inputs)) {
+            if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== 'string' || typeof value[1] !== 'number')
+                continue;
+            if (workflow[value[0]] === undefined) {
+                return {
+                    ok: false,
+                    error: `节点 ${node.class_type}（id ${id}）的输入 ${name} 引用了不在本次提取范围内的节点 ${value[0]}——请改用「整体提取」，或把这部分画布整理成独立的流程`,
+                };
+            }
+        }
+    }
     // Fail loudly on nodes whose required inputs are missing — the source graph
     // itself is broken (inputs never wired), and the server would only echo a
     // confusing per-node error at run time. Growable/lazy v3 inputs (template

package/lib/graph.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ComfyUI UI-graph link normalization. The frontend changed how saved graphs
+ * serialize the `links` array: rows used to be positional
+ * (`[id, originId, originSlot, targetId, targetSlot, type]`), while the v0.4
+ * frontend writes object entries
+ * (`{ id, origin_id, origin_slot, target_id, target_slot, type }`). Analysis
+ * and conversion both want one canonical shape, so both go through
+ * {@link normalizeLinks} before touching a graph.
+ */
+/** Canonical link row: [linkId, originId, originSlot, targetId, targetSlot, type]. */
+export type GraphLink = [number, number, number, number, number, string];
+/** Normalize one link entry; undefined when the entry is not a readable link. */
+export declare function normalizeLink(raw: unknown): GraphLink | undefined;
+/** Normalize a whole `links` array, skipping entries that are not readable. */
+export declare function normalizeLinks(raw: unknown): GraphLink[];

package/lib/graph.js

@@ -0,0 +1,48 @@
+/**
+ * ComfyUI UI-graph link normalization. The frontend changed how saved graphs
+ * serialize the `links` array: rows used to be positional
+ * (`[id, originId, originSlot, targetId, targetSlot, type]`), while the v0.4
+ * frontend writes object entries
+ * (`{ id, origin_id, origin_slot, target_id, target_slot, type }`). Analysis
+ * and conversion both want one canonical shape, so both go through
+ * {@link normalizeLinks} before touching a graph.
+ */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Normalize one link entry; undefined when the entry is not a readable link. */
+export function normalizeLink(raw) {
+    if (Array.isArray(raw)) {
+        if (raw.length < 6)
+            return undefined;
+        const [id, origin, originSlot, target, targetSlot, type] = raw;
+        if (typeof id !== 'number' || typeof origin !== 'number' ||
+            typeof originSlot !== 'number' || typeof target !== 'number' ||
+            typeof targetSlot !== 'number') {
+            return undefined;
+        }
+        return [id, origin, originSlot, target, targetSlot, typeof type === 'string' ? type : ''];
+    }
+    if (isObject(raw)) {
+        const { id, origin_id: origin, origin_slot: originSlot, target_id: target, target_slot: targetSlot, type } = raw;
+        if (typeof id !== 'number' || typeof origin !== 'number' ||
+            typeof originSlot !== 'number' || typeof target !== 'number' ||
+            typeof targetSlot !== 'number') {
+            return undefined;
+        }
+        return [id, origin, originSlot, target, targetSlot, typeof type === 'string' ? type : ''];
+    }
+    return undefined;
+}
+/** Normalize a whole `links` array, skipping entries that are not readable. */
+export function normalizeLinks(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const links = [];
+    for (const entry of raw) {
+        const link = normalizeLink(entry);
+        if (link !== undefined)
+            links.push(link);
+    }
+    return links;
+}

package/lib/index.js

@@ -4,7 +4,7 @@ import { Config } from './config.js';
 import { ComfyUIClient, CLIENT_ID } from './comfyui.js';
 import { ComfyUIStore } from './store.js';
 import { QueueTracker } from './queue.js';
-import { convertGraphToApi } from './convert.js';
+import { convertGraphToApi, flattenDynamicCombos } from './convert.js';
 import { analyzeGraph } from './analyze.js';
 import { ProgressTracker } from './progress.js';
 import { COMFYUI_SKILL } from './skill.js';
@@ -164,7 +164,8 @@ export async function apply(ctx, entryConfig) {
         },
         queue: async (workflow, meta) => {
             const client = runtime.createClient(await resolveApiKey(ctx, resolved.apiKeyEnv));
-            let prompt = workflow;
+            // Heals library entries saved with the pre-0.5.2 wrapped DynamicCombo shape (Issue #10).
+            let prompt = flattenDynamicCombos(workflow);
             if (meta.parameters !== undefined && meta.parameters.length > 0) {
                 const objectInfo = await objectInfoCached(client);
                 const slots = await store.loadSlots();
@@ -217,7 +218,9 @@ export async function apply(ctx, entryConfig) {
             const entries = await client.listUserData('workflows');
             const library = await store.listWorkflows();
             return entries
-                .filter((entry) => entry.type === 'file' && entry.name.endsWith('.json'))
+                // Dot entries are ComfyUI bookkeeping (e.g. `.index.json`), not graphs.
+                .filter((entry) => entry.type === 'file' && entry.name.endsWith('.json')
+                && entry.name.split(/[\\/]/).every((segment) => !segment.startsWith('.')))
                 .map((entry) => {
                 const derived = library.filter((workflow) => workflow.comfyuiFile === entry.name);
                 return {
@@ -319,7 +322,12 @@ export async function apply(ctx, entryConfig) {
     // service simply never registers it, and the entry config stands as composed.
     let source = () => resolved;
     ctx.inject(['settings'], (settingsCtx) => {
-        settingsCtx.settings.installSection(ctx, COMFYUI_NS, Config, resolved, {
+        const settings = settingsCtx.settings;
+        if (typeof settings.installSection !== 'function') {
+            ctx.logger.warn('comfyui: settings service lacks installSection — settings page stays read-only, entry config stands');
+            return;
+        }
+        settings.installSection(ctx, COMFYUI_NS, Config, resolved, {
             setSource: (current) => {
                 source = current;
             },

package/lib/routes.js

@@ -250,7 +250,14 @@ export function mountComfyUIRoutes(ctx, runtime) {
                 });
             }
             catch (error) {
-                sendJson(response, 200, { ok: false, error: errorMessage(error), latencyMs: Date.now() - startedAt });
+                // Name the probed address: a save that never persisted leaves the
+                // default 127.0.0.1:8188 in force, and a bare "fetch failed" reads
+                // like a network problem with the address the user typed (Issue #11).
+                sendJson(response, 200, {
+                    ok: false,
+                    error: `${errorMessage(error)}（探测地址 ${runtime.getConfig().baseUrl}）`,
+                    latencyMs: Date.now() - startedAt,
+                });
             }
         }),
     }));
@@ -1428,7 +1435,12 @@ export function mountComfyUIRoutes(ctx, runtime) {
                 const client = runtime.createClient(await runtime.getApiKey());
                 const entry = await client.getHistory(promptId);
                 if (entry === undefined) {
-                    sendJson(response, 200, { ok: true, status: 'unknown' });
+                    // No history entry: still waiting in ComfyUI's queue, or evicted.
+                    // Tell the two apart so the background card keeps polling a long
+                    // queue instead of timing it out as "gone".
+                    const queue = await client.getQueue();
+                    const waiting = [...queue.queue_running, ...queue.queue_pending].some((item) => item.prompt_id === promptId);
+                    sendJson(response, 200, { ok: true, status: waiting ? 'queued' : 'unknown' });
                     return;
                 }
                 const statusStr = entry.status?.status_str;

package/lib/tools.js

@@ -263,7 +263,7 @@ function summarizeFields(fields, required) {
         else if (typeof typeOrList === 'string') {
             entry.type = typeOrList;
         }
-        if (optionsRecord !== undefined && 'default' in optionsRecord) {
+        if (optionsRecord !== undefined && optionsRecord.default !== undefined) {
             entry.default = optionsRecord.default;
         }
         out.push(entry);
@@ -307,16 +307,23 @@ function objectInfoDefinition(runtime) {
                 : entries.filter(([name]) => name.toLowerCase().includes(filter));
             const nodes = filtered.slice(0, 60).map(([classType, def]) => ({
                 class_type: classType,
-                display_name: def.display_name,
+                // Omitted rather than assigned undefined: a key holding undefined makes the
+                // whole result fail DSH's lossless-JSON validation. The render type already
+                // declares display_name optional.
+                ...(def.display_name !== undefined ? { display_name: def.display_name } : {}),
                 description: (def.description ?? '').slice(0, 200),
                 required: summarizeFields(def.input?.required, true),
                 optional: summarizeFields(def.input?.optional, false),
             }));
+            const hint = filtered.length > nodes.length
+                ? `filter matched ${filtered.length} nodes, showing first ${nodes.length} — narrow the filter for more`
+                : undefined;
             return {
                 total: entries.length,
                 shown: nodes.length,
                 filter: filter ?? null,
-                hint: filtered.length > nodes.length ? `filter matched ${filtered.length} nodes, showing first ${nodes.length} — narrow the filter for more` : undefined,
+                // Omitted rather than assigned undefined, same reason as display_name.
+                ...(hint !== undefined ? { hint } : {}),
                 nodes,
             };
         },
@@ -409,12 +416,13 @@ function workflowDefinition(runtime, ctx) {
                             lines.push(`  技能包${skill.required ? '（运行前必读）' : ''}: ${skill.summary}${extra} — 运行前先 action: skill { id: "${workflow.id}" }`);
                         }
                         for (const param of workflow.parameters ?? []) {
-                            const def = typeof param.default === 'string' ? `"${param.default}"` : String(param.default);
+                            const label = param.label ?? param.name;
+                            const def = param.default === undefined ? '' : `，默认 ${typeof param.default === 'string' ? `"${param.default}"` : String(param.default)}`;
                             const options = Array.isArray(param.options) && param.options.length > 0 ? `，可选: ${param.options.join(' / ')}` : '';
                             const upload = param.upload !== undefined
                                 ? `，上传类型: ${param.upload}${param.upload === 'media' ? `（${param.subfolder ?? ''}/，空值=移除该参考位）` : ''}`
                                 : '';
-                            lines.push(`  ${param.name}(${param.label}${param.random === true ? '，随机' : ''}，默认 ${def}${options}${upload})`);
+                            lines.push(`  ${param.name}(${label}${param.random === true ? '，随机' : ''}${def}${options}${upload})`);
                         }
                     }
                     const loadArea = data.loadArea;
@@ -506,7 +514,13 @@ function workflowDefinition(runtime, ctx) {
                         parameters: (parameters ?? []).map(({ name: pname, label, type, default: def, random, numberKind, options, upload }) => {
                             // DSH validates tool output as lossless JSON: JSON.stringify drops
                             // undefined keys, so omit optional fields instead of passing undefined.
-                            const entry = { name: pname, label, type, default: def };
+                            const entry = { name: pname };
+                            if (label !== undefined)
+                                entry.label = label;
+                            if (type !== undefined)
+                                entry.type = type;
+                            if (def !== undefined)
+                                entry.default = def;
                             if (random !== undefined)
                                 entry.random = random;
                             // Tells the model whether decimals are accepted; absent means the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-comfyui",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Let the DeepSeek Harness agent smartly drive a local or remote ComfyUI to generate anything, with workflow and asset management panels, per-workflow skill packs, a companion skill and a same-origin media proxy. / 让 DeepSeek Harness 的 Agent 智能驱动本地或远程 ComfyUI 生成任何内容。附带工作流、资产管理面板与技能包管理挂载。配套 skill 与同源媒体代理。",
   "repository": {
     "type": "git",