dsh-comfyui 0.5.3 → 0.5.5

package/lib/analyze.js

@@ -5,7 +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';
+import { isVirtualNodeType, normalizeLinks, resolveVirtualLinks } from './graph.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -28,11 +28,15 @@ export function analyzeGraph(graph) {
         return { ok: false, error: '无法解析图文件（缺少 nodes/links）' };
     }
     const nodes = graph.nodes;
-    const links = normalizeLinks(graph.links);
+    // Virtual nodes (Set/Get wireless links, rgthree mode relays) are rewired
+    // out first, exactly as conversion does, so components follow the real data
+    // flow and the virtual nodes themselves never show up as components or as
+    // dangling nodes (Issue #8).
+    const links = resolveVirtualLinks(graph.nodes, normalizeLinks(graph.links));
     const groups = Array.isArray(graph.groups) ? graph.groups : [];
-    const active = nodes.filter((node) => node.mode !== 4);
+    const active = nodes.filter((node) => node.mode !== 4 && !isVirtualNodeType(node.type));
     const activeById = new Map(active.map((node) => [node.id, node]));
-    const bypassedCount = nodes.length - active.length;
+    const bypassedCount = nodes.filter((node) => node.mode === 4).length;
     // Dangling nodes: active but touching no link at all.
     const linkedIds = new Set();
     for (const link of links) {

package/lib/comfyui.d.ts

@@ -171,6 +171,16 @@ export declare class ComfyUIClient {
     deleteQueueItems(promptIds: string[]): Promise<void>;
     /** Clear the entire pending queue (running job is unaffected). */
     clearQueue(): Promise<void>;
+    /**
+     * Stop one prompt without touching anyone else's work: dequeue it while
+     * pending, interrupt it only while it is the running one, no-op once it has
+     * left the queue. A bare `interrupt()` stops whatever is running — another
+     * session's job or the user's own ComfyUI run — and ComfyUI versions before
+     * prompt-scoped interrupts ignore the `prompt_id` body, hence the queue
+     * check. (Older servers keep a tiny race: the prompt could finish between
+     * the check and the interrupt.)
+     */
+    cancelPrompt(promptId: string): Promise<void>;
     /** Interrupt the running prompt; without an id, interrupt globally. */
     interruptPrompt(promptId?: string): Promise<void>;
     /** Cancel one job regardless of state (running → interrupt, pending → dequeue). */
@@ -202,8 +212,6 @@ export declare class ComfyUIClient {
             comfyui_version?: string;
         };
     }>;
-    /** Ask ComfyUI to interrupt the running prompt. */
-    interrupt(): Promise<void>;
     /** Download one generated media file through GET /view. */
     fetchView(ref: ComfyUIMediaRef): Promise<{
         bytes: Uint8Array;
@@ -221,13 +229,16 @@ export declare class ComfyUIClient {
     fetchViewStreamed(ref: ComfyUIMediaRef, rangeHeader?: string, method?: 'GET' | 'HEAD'): Promise<ComfyViewStream>;
     /**
      * Poll history until the prompt completes, fails, or the budget/signal ends.
-     * Interrupts the server when the signal aborts before throwing.
+     * When the signal aborts — mid-sleep included — cancels this prompt only
+     * (`cancelPrompt`) and throws an "interrupted" error. `onPoll` runs once per
+     * poll, for callers that publish progress.
      */
     waitForCompletion(opts: {
         promptId: string;
         timeoutMs: number;
         pollIntervalMs: number;
         signal: AbortSignal;
+        onPoll?: () => void;
     }): Promise<ComfyUIHistoryEntry>;
 }
 export declare function hasMedia(entry: ComfyUIHistoryEntry): boolean;

package/lib/comfyui.js

@@ -268,6 +268,25 @@ export class ComfyUIClient {
             body: JSON.stringify({ clear: true }),
         });
     }
+    /**
+     * Stop one prompt without touching anyone else's work: dequeue it while
+     * pending, interrupt it only while it is the running one, no-op once it has
+     * left the queue. A bare `interrupt()` stops whatever is running — another
+     * session's job or the user's own ComfyUI run — and ComfyUI versions before
+     * prompt-scoped interrupts ignore the `prompt_id` body, hence the queue
+     * check. (Older servers keep a tiny race: the prompt could finish between
+     * the check and the interrupt.)
+     */
+    async cancelPrompt(promptId) {
+        const queue = await this.getQueue();
+        if (queue.queue_pending.some((item) => item.prompt_id === promptId)) {
+            await this.deleteQueueItems([promptId]);
+            return;
+        }
+        if (queue.queue_running.some((item) => item.prompt_id === promptId)) {
+            await this.interruptPrompt(promptId);
+        }
+    }
     /** Interrupt the running prompt; without an id, interrupt globally. */
     async interruptPrompt(promptId) {
         await this.request('/interrupt', {
@@ -361,10 +380,6 @@ export class ComfyUIClient {
     async systemStats() {
         return this.request('/system_stats');
     }
-    /** Ask ComfyUI to interrupt the running prompt. */
-    async interrupt() {
-        await this.request('/interrupt', { method: 'POST' });
-    }
     /** Download one generated media file through GET /view. */
     async fetchView(ref) {
         const params = new URLSearchParams({ filename: ref.filename, subfolder: ref.subfolder, type: ref.type });
@@ -409,12 +424,14 @@ export class ComfyUIClient {
                 headers['Range'] = rangeHeader;
             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}`);
+                await response.body?.cancel().catch(() => undefined);
+                throw new ComfyUIError(`ComfyUI /view failed: HTTP ${response.status}`, response.status);
             }
             if (response.status === 200) {
                 const contentLength = response.headers.get('content-length');
                 if (contentLength !== null && Number(contentLength) > this.maxMediaBytes) {
-                    throw new ComfyUIError(`ComfyUI media too large: ${contentLength} bytes exceeds maxMediaBytes ${this.maxMediaBytes}`);
+                    await response.body?.cancel().catch(() => undefined);
+                    throw new ComfyUIError(`ComfyUI media too large: ${contentLength} bytes exceeds maxMediaBytes ${this.maxMediaBytes}`, 413);
                 }
             }
             return { status: response.status, headers: response.headers, body: response.body };
@@ -425,16 +442,19 @@ export class ComfyUIClient {
     }
     /**
      * Poll history until the prompt completes, fails, or the budget/signal ends.
-     * Interrupts the server when the signal aborts before throwing.
+     * When the signal aborts — mid-sleep included — cancels this prompt only
+     * (`cancelPrompt`) and throws an "interrupted" error. `onPoll` runs once per
+     * poll, for callers that publish progress.
      */
     async waitForCompletion(opts) {
-        const { promptId, timeoutMs, pollIntervalMs, signal } = opts;
+        const { promptId, timeoutMs, pollIntervalMs, signal, onPoll } = opts;
         const deadline = Date.now() + timeoutMs;
         for (;;) {
             if (signal.aborted) {
-                await this.interrupt().catch(() => undefined);
+                await this.cancelPrompt(promptId).catch(() => undefined);
                 throw new ComfyUIError(`ComfyUI generation interrupted (prompt ${promptId})`);
             }
+            onPoll?.();
             const entry = await this.getHistory(promptId);
             if (entry !== undefined) {
                 const status = entry.status;
@@ -448,7 +468,8 @@ export class ComfyUIClient {
             if (Date.now() >= deadline) {
                 throw new ComfyUIError(`ComfyUI generation timed out after ${timeoutMs} ms (prompt ${promptId})`);
             }
-            await sleep(pollIntervalMs, signal);
+            // An abort ends the sleep early; the loop top then cancels and throws.
+            await sleep(pollIntervalMs, signal).catch(() => undefined);
         }
     }
 }

package/lib/convert.js

@@ -7,7 +7,7 @@
  * 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';
+import { isVirtualNodeType, normalizeLinks, resolveVirtualLinks } 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) {
@@ -253,7 +253,9 @@ export function convertGraphToApi(graph, objectInfo, options) {
     // 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))
+    // Set/Get wireless links and rgthree mode relays are rewired out before
+    // anything resolves a link (Issue #8), shared with analyzeGraph.
+    for (const link of resolveVirtualLinks(rawNodes, normalizeLinks(rawLinks)))
         links.set(link[0], link);
     const nodesById = new Map(nodes.map((node) => [node.id, node]));
     const included = options?.includeNodeIds;
@@ -272,7 +274,7 @@ export function convertGraphToApi(graph, objectInfo, options) {
     const brokenInputs = new Map();
     const dropReasons = new Map();
     for (const node of candidates) {
-        if (node.type === '' || UI_ONLY.has(node.type))
+        if (node.type === '' || UI_ONLY.has(node.type) || isVirtualNodeType(node.type))
             continue;
         if (node.mode === 4)
             continue;

package/lib/graph.d.ts

@@ -13,3 +13,32 @@ export type GraphLink = [number, number, number, number, number, string];
 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[];
+/**
+ * Frontend-only nodes whose links are rewired or dropped before analysis and
+ * conversion (Issue #8). None of them exists on the server.
+ *
+ * - KJNodes `SetNode` / `GetNode`: "wireless" links paired by name. A GetNode's
+ *   output is the value wired into the SetNode of the same name (and a
+ *   SetNode's own passthrough output is its input).
+ * - rgthree `Mute / Bypass Relay` / `Repeater`: their `OPT_CONNECTION` links
+ *   only propagate mute/bypass mode between nodes and carry no data. The mode
+ *   they set is already saved on each target node, so the links are dropped.
+ */
+export declare const SET_NODE = "SetNode";
+export declare const GET_NODE = "GetNode";
+/** Whether a node type is one of the virtual nodes {@link resolveVirtualLinks} removes. */
+export declare function isVirtualNodeType(type: string): boolean;
+/**
+ * Rewire the virtual nodes out of a graph's links, keeping link ids stable so
+ * node `inputs[].link` references stay valid.
+ *
+ * A GetNode resolves to the SetNode of the same name with the greatest `order`
+ * below its own (the scope rule the frontend applies), falling back to any
+ * SetNode of that name. A GetNode without a matching, wired SetNode (e.g. an
+ * empty optional slot) resolves to nothing, so its consumer stays unconnected.
+ * @param rawNodes - the graph's `nodes` array as saved.
+ * @param links - normalized links.
+ * @returns links with virtual-node hops replaced by their real origins, and
+ *   every link touching a virtual node otherwise removed.
+ */
+export declare function resolveVirtualLinks(rawNodes: unknown, links: GraphLink[]): GraphLink[];

package/lib/graph.js

@@ -46,3 +46,102 @@ export function normalizeLinks(raw) {
     }
     return links;
 }
+/**
+ * Frontend-only nodes whose links are rewired or dropped before analysis and
+ * conversion (Issue #8). None of them exists on the server.
+ *
+ * - KJNodes `SetNode` / `GetNode`: "wireless" links paired by name. A GetNode's
+ *   output is the value wired into the SetNode of the same name (and a
+ *   SetNode's own passthrough output is its input).
+ * - rgthree `Mute / Bypass Relay` / `Repeater`: their `OPT_CONNECTION` links
+ *   only propagate mute/bypass mode between nodes and carry no data. The mode
+ *   they set is already saved on each target node, so the links are dropped.
+ */
+export const SET_NODE = 'SetNode';
+export const GET_NODE = 'GetNode';
+const MODE_LINK_NODES = new Set(['Mute / Bypass Relay (rgthree)', 'Mute / Bypass Repeater (rgthree)']);
+/** Whether a node type is one of the virtual nodes {@link resolveVirtualLinks} removes. */
+export function isVirtualNodeType(type) {
+    return type === SET_NODE || type === GET_NODE || MODE_LINK_NODES.has(type);
+}
+function virtualNodeFacts(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const id = typeof raw.id === 'number' ? raw.id : Number(raw.id);
+    if (!Number.isFinite(id))
+        return undefined;
+    const values = Array.isArray(raw.widgets_values) ? raw.widgets_values : [];
+    const name = typeof values[0] === 'string' && values[0].trim() !== '' ? values[0] : undefined;
+    const inputs = Array.isArray(raw.inputs) ? raw.inputs : [];
+    const wired = inputs.find((entry) => isObject(entry) && typeof entry.link === 'number');
+    return {
+        id,
+        type: typeof raw.type === 'string' ? raw.type : '',
+        order: typeof raw.order === 'number' ? raw.order : Number.MAX_SAFE_INTEGER,
+        name,
+        firstInputLink: wired?.link,
+    };
+}
+/**
+ * Rewire the virtual nodes out of a graph's links, keeping link ids stable so
+ * node `inputs[].link` references stay valid.
+ *
+ * A GetNode resolves to the SetNode of the same name with the greatest `order`
+ * below its own (the scope rule the frontend applies), falling back to any
+ * SetNode of that name. A GetNode without a matching, wired SetNode (e.g. an
+ * empty optional slot) resolves to nothing, so its consumer stays unconnected.
+ * @param rawNodes - the graph's `nodes` array as saved.
+ * @param links - normalized links.
+ * @returns links with virtual-node hops replaced by their real origins, and
+ *   every link touching a virtual node otherwise removed.
+ */
+export function resolveVirtualLinks(rawNodes, links) {
+    const facts = new Map();
+    for (const raw of Array.isArray(rawNodes) ? rawNodes : []) {
+        const node = virtualNodeFacts(raw);
+        if (node !== undefined && isVirtualNodeType(node.type))
+            facts.set(node.id, node);
+    }
+    if (facts.size === 0)
+        return links;
+    const linkById = new Map(links.map((link) => [link[0], link]));
+    const setters = new Map();
+    for (const node of facts.values()) {
+        if (node.type !== SET_NODE || node.name === undefined)
+            continue;
+        const list = setters.get(node.name) ?? [];
+        list.push(node);
+        setters.set(node.name, list);
+    }
+    const setterFor = (getter) => {
+        const candidates = getter.name === undefined ? [] : setters.get(getter.name) ?? [];
+        const before = candidates.filter((node) => node.order < getter.order);
+        const pool = before.length > 0 ? before : candidates;
+        return pool.reduce((best, node) => (best === undefined || node.order > best.order ? node : best), undefined);
+    };
+    /** The real [originId, originSlot] behind an origin, or undefined when it resolves to nothing. */
+    const realOrigin = (originId, originSlot, seen) => {
+        const node = facts.get(originId);
+        if (node === undefined)
+            return [originId, originSlot];
+        if (seen.has(originId))
+            return undefined;
+        seen.add(originId);
+        if (MODE_LINK_NODES.has(node.type))
+            return undefined;
+        const source = node.type === GET_NODE ? setterFor(node) : node;
+        const upstream = source?.firstInputLink === undefined ? undefined : linkById.get(source.firstInputLink);
+        return upstream === undefined ? undefined : realOrigin(upstream[1], upstream[2], seen);
+    };
+    const out = [];
+    for (const link of links) {
+        // Links INTO a virtual node only feed the resolution above.
+        if (facts.has(link[3]))
+            continue;
+        const origin = realOrigin(link[1], link[2], new Set());
+        if (origin === undefined)
+            continue;
+        out.push(origin[0] === link[1] && origin[1] === link[2] ? link : [link[0], origin[0], origin[1], link[3], link[4], link[5]]);
+    }
+    return out;
+}

package/lib/skill.js

@@ -6,10 +6,31 @@
 export const COMFYUI_SKILL = {
     name: 'dsh-comfyui-workflows',
     source: 'runtime',
-    description: 'ComfyUI 工作流管理：区分“图工作流”（ComfyUI 端保存的画布，衍生主题）与“API 工作流”（可执行，运行主题），分析画布中的多个独立流程（连通分量），以及图→API 提取的规则与面板操作引导。也包含本机环境（用户 ComfyUI 目录）与 TTS-Audio-Suite 音色库的快速查询/快照刷新方案。处理 comfyui_workflow、需要定位用户 ComfyUI 文件/音色库，或用户要求运行 ComfyUI 端保存的工作流时加载。',
-    whenToUse: '用户要求运行/管理 ComfyUI 中保存的工作流，或 comfyui_workflow list 显示未提取的图工作流时；需要判断一个画布是否包含多个独立流程、或解释为何某个工作流无法直接运行时；需要查询 TTS-Audio-Suite 音色库、刷新已存工作流的音色参数快照、或定位用户本机 ComfyUI 目录时；或 comfyui_workflow list 里某个工作流带“技能包”标记、需要在运行前读取它时。',
+    description: '用 ComfyUI 生成图片/视频/音频（文生图、图生图、文生视频、语音等）的入口：第一步用 comfyui_workflow list 挑库里的工作流再 run。也负责工作流管理：区分“图工作流”（ComfyUI 端保存的画布，衍生主题）与“API 工作流”（可执行，运行主题），分析画布中的多个独立流程（连通分量），以及图→API 提取的规则与面板操作引导。也包含本机环境（用户 ComfyUI 目录）与 TTS-Audio-Suite 音色库的快速查询/快照刷新方案。处理 comfyui_workflow、需要定位用户 ComfyUI 文件/音色库，或用户要求运行 ComfyUI 端保存的工作流时加载。',
+    whenToUse: '用户要用 ComfyUI 生成任何内容时（先 list 再 run）；用户要求运行/管理 ComfyUI 中保存的工作流，或 comfyui_workflow list 显示未提取的图工作流时；需要判断一个画布是否包含多个独立流程、或解释为何某个工作流无法直接运行时；需要查询 TTS-Audio-Suite 音色库、刷新已存工作流的音色参数快照、或定位用户本机 ComfyUI 目录时；或 comfyui_workflow list 里某个工作流带“技能包”标记、需要在运行前读取它时。',
     content: `# dsh-comfyui 工作流管理
 
+## 生成内容：第一步永远是 comfyui_workflow list
+
+用户要生成任何内容（图片、视频、音频，文生图、图生图、TTS 等）时：
+
+1. **先调用 \`comfyui_workflow action: list\`**，按名称、描述、标签挑出合适的工作流。库里的工作流是用户为这台服务器配好的，模型和节点都可用。
+2. 有技能包的先 \`action: skill { id }\` 读一遍，然后 \`comfyui_workflow run { id, parameters }\`（细节见「运行工作流的正确流程」）。
+3. \`comfyui_object_info\` 和 \`comfyui_run\` **不是生成入口**，只用于手写工作流（见下一节）。库里有合适的工作流就不要用它们。
+4. 能直接调用工具就直接调用（对话里才会显示生成卡片）；当前环境只能在 run_code 里调用时也可以，照返回值里的 \`report\` 字段做。
+
+## 手写工作流（次要：临时测试，或按本机环境新建工作流）
+
+库里没有合适的工作流、需要临时测试，或要为本机环境新建一个工作流时才用，步骤固定：
+
+1. **查环境**：\`comfyui_object_info { filter }\` 查节点类名、输入项和加载器里实际可选的模型文件名（如 \`filter: "Loader"\`）。
+2. **手写 API JSON**：节点 id → \`{ class_type, inputs }\`，连线写成 \`["节点id字符串", 输出槽位]\`，模型名只用第 1 步查到的。
+3. **运行测试**：\`comfyui_run { workflow }\`，报错就按错误信息改 JSON 再跑。
+
+测通后如果要长期用，告诉用户在面板里「新建工作流」粘贴这份 JSON 存进库，之后走 list → run。
+
+## 两个工作流主题
+
 本插件把 ComfyUI 工作流分成两个主题：
 
 - **图工作流（衍生主题）**：用户在 ComfyUI 画布上保存的 UI 图（nodes/links/widgets），是"源"。不能直接运行。一个图可能包含**多个互相独立的流程**。
@@ -66,6 +87,9 @@ TTS-Audio-Suite（\`{comfyuiDir}/custom_nodes/tts_audio_suite\`）的"🎭 Chara
 - **\`control_after_generate\` 占位**：名为 \`seed\`/\`noise_seed\` 的 INT（或 object_info 显式声明 \`control_after_generate\`）前面端会渲染生成后控制下拉，其值占据 widgets_values 一个槽位但无 API 输入——提取时消费该值但不写入工作流，否则后续 widget 全部错位（如 TTS-Audio-Suite 的 seed 后跟 "fixed"）。
 - **对象型 widgets_values**（如 VHS_VideoCombine）按名取值，跳过内部状态（\`videopreview\` 等带 \`hidden\` 的对象）。
 - **Reroute 与 bypass（mode 4）节点直通**：输出跟随其第一条有连线的输入。
+- **虚拟节点先改线再转换**（分析与转换共用同一规则）：KJNodes \`SetNode\`/\`GetNode\` 按名称配对——\`GetNode\` 的输出接到同名 \`SetNode\` 的上游（同名多个时取 \`order\` 小于它的最大者），找不到对应 \`SetNode\` 的消费端保持未连接；rgthree \`Mute / Bypass Relay\`/\`Repeater\` 的连线只传播静音/绕过状态、不传数据，直接丢弃（状态已保存在各节点的 \`mode\` 里）。
+- **DynamicCombo V3 保持扁平**：主输入的值是所选 option key 字符串，子控件以 \`主名.子名\` 平铺（如 \`codec: "auto"\`），不要包成 \`{ key, inputs }\`——服务端会自己重组，包起来反而匹配不上，节点在 execute 时报缺参数。
+- **子图（subgraph）实例不支持**：遇到请让用户在 ComfyUI 里把子图转换回普通节点后再提取。
 - **未注册的 UI-only 节点**：若是 \`Primitive*\` 内联其第一个 widget 值；有输出被使用且非 Primitive → 报错。
 - **输出槽位越界**（保存图里 SaveImage 声称 2 个输出但服务端只有 1 个）→ 断开该引用并给警告。
 - **必需输入缺失**（required 里没有、且非 lazy/template 类型）→ 明确报错（源图本身断线），不产出"能转但跑不起来"的工作流。\`COMFY_AUTOGROW_V3\`/带 \`template\`/带 \`lazy\` 的输入豁免。
@@ -139,7 +163,10 @@ TTS-Audio-Suite（\`{comfyuiDir}/custom_nodes/tts_audio_suite\`）的"🎭 Chara
 2. **有技能包就先读**：list 里某个工作流带 \`技能包:\` 那一行，说明用户为它写了专属说明书（适用场景、参数怎么填、哪些环节会翻车）。选中它之后、运行之前，先 \`comfyui_workflow action: skill { id }\` 把正文读进来并照着做。标注「运行前必读」的，不读会被 run 直接拒绝。没有这行的工作流跳过本步。
 3. **参数决策**：只依据清单里的参数（键名用英文名），选择/覆盖适合的值——**不需要查看工作流内部结构**。
 4. **run 直接调用**：\`comfyui_workflow run { id, parameters: {...} }\`。插件直接从库里取该工作流的 JSON 提交给 ComfyUI，你**只传参数覆盖值，绝不自己输出或复制完整工作流 JSON**（那会浪费大量 token）。
-   - **视频/音频工作流一律 \`mode: "async"\`**：生成要几分钟，sync 会等待超时中断（报 generation aborted）。async 立即返回 job id，**启动后不要阻塞等待**（不要对返回的 job 用 wait: true 卡住），继续做其他事，后台任务完成时系统会通知你，到时再用 job_output（不 wait）收集结果和媒体回显。
+   - **参数**：键名与 list 完全一致（写错会被拒绝）；未传的参数使用默认值。提示词类参数按用户需求填写，未明确时据需求自行发挥。
+   - **视频/音频工作流一律 \`mode: "async"\`**：生成要几分钟，sync 会等待超时中断（报 generation aborted）。async 立即返回 job id，**启动后不要阻塞等待**（不要对返回的 job 用 wait: true 卡住，也不要 sleep/轮询）：告诉用户正在生成，**直接结束本轮回复**；有其他独立的事可以先做完再结束。后台任务完成时系统会发通知唤醒你，到时调用一次 job_output（不 wait）收集结果。
+   - **结果就是最终结果，地址已经带好**：不要再查状态，也不要去查资产、history 或拼接 URL。
+   - **生成完毕后的统一做法**（sync、async 的 job_output、run_code 都一样）：用一句话告诉用户生成了什么（依据结果里的「Prompt used」），然后把结果给出的 Markdown 行**原样贴进回复**（图片是 \`![image 1](url)\`，视频/音频是链接）——这是用户看到结果的地方。
    - 图片生成可 sync（通常 <1 分钟）；若不确定输出类型，也用 async。
 - \`action: get\` 只在**诊断/检查**工作流内容时使用（它会输出完整 JSON、占用大量 token），它**不是运行路径**。
 

package/lib/tools.d.ts

@@ -1,9 +1,11 @@
 /**
  * Model-facing tools for dsh-comfyui, registered into the host `tools`
- * registry. `comfyui_run` submits a workflow and returns media results
- * (synchronously or as a background job); `comfyui_object_info` exposes the
- * server's node definitions; `comfyui_workflow` lists and runs saved
- * workflows from the panel-managed workflow library.
+ * registry. The main entry is `comfyui_workflow`: list and run saved
+ * workflows from the panel-managed library (synchronously or as a background
+ * job); `comfyui_skill` maintains their skill packs. Secondary, for
+ * hand-written workflows only (temporary tests, building a workflow for this
+ * environment): `comfyui_object_info` exposes the server's node definitions
+ * and `comfyui_run` submits a hand-written API workflow.
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { Config } from './config.js';
@@ -155,6 +157,17 @@ export interface RunResult {
     elapsedMs: number;
     media: RunMediaItem[];
     summary: string;
+    /** Saved-workflow runs: the prompt-type parameters as actually submitted. */
+    prompts?: PromptUsed[];
+    /** The model-facing text (`runResultText`), carried in the value for code-dispatched calls. */
+    report?: string;
+}
+/** One prompt-type parameter of a saved-workflow run, as actually submitted. */
+export interface PromptUsed {
+    name: string;
+    text: string;
+    /** false = the caller did not pass it, so the saved default was used. */
+    passed: boolean;
 }
 /** Background mode result: collect later with job_output. */
 export interface BackgroundResult {
@@ -162,6 +175,10 @@ export interface BackgroundResult {
     jobId: string;
     promptId: string;
     label: string;
+    /** The host posts a completion notice (and wakes an idle agent) — dsh 0.1.7+ jobs. */
+    notifies: boolean;
+    /** The model-facing receipt (`backgroundText`), carried in the value for code-dispatched calls. */
+    report?: string;
 }
 /** Register the plugin tools; returns disposers. */
 export declare function registerComfyUITools(ctx: Context, runtime: ComfyUIRuntime): Array<() => void>;