@mokuyoaxis/dsh-iris 0.2.7 → 0.3.0-beta.1

package/lib/comfyui-adapter.js

@@ -0,0 +1,95 @@
+// Native ComfyUI HTTP API. No embedded server, global interrupt, or local output-path access.
+import { defineProviderAdapter } from './provider-adapter.js';
+import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
+import { checkedComfyWorkflow, compileComfyWorkflow } from './comfyui-workflow.js';
+import { parseImageSize } from './provider-protocol.js';
+import { createComfyUiClient, comfyFail as fail } from './comfyui-client.js';
+import { inspectComfyWorkflow } from './comfyui-inspection.js';
+import { writePrivateFile } from './private-storage.js';
+import { inheritedProviderFetch } from './provider-network.js';
+
+const TASK = /^[A-Za-z0-9_-]{1,200}$/;
+function imageLocation(value) {
+  const safe = (text, empty = false) => typeof text === 'string' && (empty || text.length > 0) && text.length <= 1024
+    && !/[\x00-\x1f\x7f\\]/.test(text) && !text.startsWith('/') && !text.split('/').some(part => ['..', '.'].includes(part));
+  if (!value || !safe(value.filename) || value.filename.includes('/') || !safe(value.subfolder, true) || !['output', 'temp'].includes(value.type)) {
+    fail('ComfyUI 图片位置无效', 'poll');
+  }
+  return { filename: value.filename, subfolder: value.subfolder, type: value.type };
+}
+export function createComfyUiProviderAdapter(provider, { fetchPort = inheritedProviderFetch, network } = {}) {
+  const client = createComfyUiClient(provider, { fetchPort, network }), { route, request } = client;
+  function workflow(model) {
+    const value = model ? provider.models?.find(entry => entry.id === model)?.comfyWorkflow : provider.comfyWorkflow;
+    try { return checkedComfyWorkflow(value); }
+    catch (_) { fail('此模型尚未配置有效的 ComfyUI API 工作流', 'validate', 'invalid_request'); }
+  }
+  function historyResult(history, id, selected) {
+    if (!history || typeof history !== 'object' || Array.isArray(history)) fail('ComfyUI 历史响应无效', 'poll');
+    if (!Object.hasOwn(history, id)) return null;
+    const entry = history[id];
+    if (entry?.status?.status_str === 'error') return { kind: 'failed', error: { stage: 'poll', category: 'provider', acceptance: 'accepted', safeMessage: 'ComfyUI 工作流执行失败，请在原服务查看该任务' } };
+    if (entry?.status?.completed !== true) return { kind: 'pending' };
+    const images = entry.outputs?.[selected.outputNode]?.images;
+    if (!Array.isArray(images) || images.length !== 1) fail('所选 ComfyUI 输出节点需要恰好一张图片；原任务已保留', 'poll');
+    return { kind: 'succeeded', artifacts: [{ kind: 'remote-url', url: route('view') + '?' + new URLSearchParams(imageLocation(images[0])) }] };
+  }
+  return defineProviderAdapter({ id: provider.id, protocol: 'comfyui', capabilities: ['image'],
+    operations: {
+      async discover({ signal, timeoutMs } = {}) {
+        await request(route('system_stats'), { signal, timeoutMs, stage: 'validate' });
+        return { models: (provider.models || []).filter(model => model.comfyWorkflow).map(model => ({ id: model.id, capabilities: ['image-gen'] })) };
+      },
+      async submit({ capability, model, input = {}, signal, timeoutMs }) {
+        if (capability !== 'image' || input.image || input.n !== undefined && input.n !== 1) fail('ComfyUI 首版仅支持单张文生图', 'validate', 'invalid_request');
+        let selected;
+        try { selected = compileComfyWorkflow(workflow(model), input); }
+        catch (error) {
+          if (error.code !== 'IRIS_COMFYUI_PARAMETERS_INVALID') throw error;
+          fail(error.message, 'validate', 'invalid_request');
+        }
+        const graph = selected.graph;
+        if (input.size !== undefined) {
+          const size = parseImageSize(input.size);
+          if (!selected.sizeNode || !size || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height)) {
+            fail('此工作流需要有效的宽x高以及明确的尺寸节点；未绑定时请留空', 'validate', 'invalid_request');
+          }
+          Object.assign(graph[selected.sizeNode].inputs, { width: size.width, height: size.height });
+        }
+        if (selected.version === 1) {
+          const report = await inspectComfyWorkflow(client, selected, { signal, timeoutMs });
+          if (!report.ok) fail('ComfyUI 工作流检查未通过：' + report.issues.slice(0, 3).map(issue => issue.message).join('；'), 'validate', 'invalid_request');
+        }
+        const result = await request(route('prompt'), { method: 'POST', value: { prompt: graph }, signal, timeoutMs, stage: 'submit' });
+        if (typeof result?.prompt_id !== 'string' || !TASK.test(result.prompt_id)) fail('ComfyUI 未返回可恢复的任务 ID，请核对原服务，避免重复提交', 'response', 'protocol', 'unknown');
+        return { kind: 'accepted', remoteTaskId: result.prompt_id };
+      },
+      async poll({ remoteTaskId, model, signal, timeoutMs }) {
+        if (typeof remoteTaskId !== 'string' || !TASK.test(remoteTaskId)) fail('ComfyUI 原任务 ID 无效', 'poll');
+        const selected = workflow(model), readHistory = () => request(route('history/' + encodeURIComponent(remoteTaskId)), { signal, timeoutMs, stage: 'poll' });
+        const result = historyResult(await readHistory(), remoteTaskId, selected);
+        if (result) return result;
+        const queue = await request(route('queue'), { signal, timeoutMs, stage: 'poll' });
+        if (!Array.isArray(queue?.queue_running) || !Array.isArray(queue?.queue_pending)) fail('ComfyUI 队列响应无效', 'poll');
+        if ([...queue.queue_running, ...queue.queue_pending].some(entry => Array.isArray(entry) && entry[1] === remoteTaskId)) return { kind: 'pending' };
+        // Completion may move from queue to history between the two reads. Never resubmit.
+        return historyResult(await readHistory(), remoteTaskId, selected) || { kind: 'unknown', error: {
+          stage: 'poll', category: 'unknown', acceptance: 'accepted', safeMessage: '原任务已不在 ComfyUI 队列或历史中，请核对原服务；不会重新提交' } };
+      },
+      async download({ artifact, targetPath, signal, timeoutMs }) {
+        const url = new URL(artifact?.url || ''), expected = new URL(route('view'));
+        if (artifact.kind !== 'remote-url' || url.origin !== expected.origin || url.pathname !== expected.pathname || url.username || url.password || url.hash
+            || [...url.searchParams.keys()].some(name => !['filename', 'subfolder', 'type'].includes(name))
+            || ['filename', 'subfolder', 'type'].some(name => url.searchParams.getAll(name).length !== 1)) fail('ComfyUI 交付地址不属于原服务的图片接口', 'download');
+        imageLocation(Object.fromEntries(url.searchParams));
+        const bytes = await request(url.href, { signal, timeoutMs, stage: 'download', binary: true });
+        writePrivateFile(targetPath, bytes, { flag: 'wx' }); return { bytes: bytes.length };
+      },
+      mapError: (error, context) => providerErrorRecord(error, { ...context, stage: error.stage || context.stage,
+        acceptance: error.acceptance || context.acceptance, category: error.category || (error.name === 'AbortError' ? 'aborted' : error.name === 'TimeoutError' ? 'timeout' : 'network'),
+        safeMessage: error instanceof ProviderContractError ? error.message : 'ComfyUI 服务通信失败，请核对原任务与服务状态' })
+    },
+    unsupported: { cancel: 'ComfyUI /interrupt 控制当前工作流，首版不对共享服务发送全局中断' },
+    unsupportedPreparation: 'ComfyUI 首版不支持带图编辑或输入上传'
+  });
+}

package/lib/comfyui-client.js

@@ -0,0 +1,60 @@
+// Native HTTP transport shared by generation and explicit read-only workflow checks.
+import { ProviderContractError } from './provider-contract.js';
+import { normalizeMediaEndpoint, providerApiKey, providerMediaBaseUrl } from './provider-protocol.js';
+import { resolveProviderCredential } from './provider-credentials.js';
+import { inheritedProviderFetch } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+
+export function comfyFail(message, stage, category = 'protocol', acceptance = stage === 'validate' ? 'not_accepted' : 'accepted', details = {}) {
+  throw new ProviderContractError(message, { stage, category, acceptance, ...details });
+}
+async function bounded(response, limit, stage) {
+  if (Number(response.headers.get('content-length')) > limit) { await response.body?.cancel(); comfyFail('ComfyUI 响应超过大小上限', stage, 'protocol', stage === 'submit' ? 'unknown' : stage === 'validate' ? 'not_accepted' : 'accepted'); }
+  const chunks = []; let size = 0;
+  for await (const chunk of response.body || []) {
+    size += chunk.length;
+    if (size > limit) comfyFail('ComfyUI 响应超过大小上限', stage, 'protocol', stage === 'submit' ? 'unknown' : stage === 'validate' ? 'not_accepted' : 'accepted');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, size);
+}
+export function createComfyUiClient(provider, { fetchPort = inheritedProviderFetch, network } = {}) {
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || network.providerId !== provider.id)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', 'ComfyUI 需要供应商匹配的网络上下文，不会静默直连');
+  }
+  provider = resolveProviderCredential(provider);
+  const base = normalizeMediaEndpoint(providerMediaBaseUrl(provider)), key = providerApiKey(provider);
+  const route = leaf => base + '/' + leaf;
+  async function request(url, { method = 'GET', value, signal, stage, timeoutMs = 15000, binary = false } = {}) {
+    const combined = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(signal ? [signal] : [])]);
+    let response;
+    try {
+      response = await fetchPort(url, { method, signal: combined, redirect: 'error',
+        headers: { ...(key ? { Authorization: 'Bearer ' + key } : {}), ...(value ? { 'Content-Type': 'application/json' } : {}) },
+        ...(value ? { body: JSON.stringify(value) } : {}) });
+    } catch (error) {
+      if (error instanceof ProviderContractError) throw error;
+      comfyFail('ComfyUI 服务通信失败，请核对原任务与服务状态', stage,
+        error.name === 'AbortError' ? 'aborted' : error.name === 'TimeoutError' ? 'timeout' : 'network',
+        stage === 'submit' ? 'unknown' : stage === 'validate' ? 'not_accepted' : 'accepted');
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      const rejection = method === 'POST' && [400, 401, 403, 404, 422, 429].includes(response.status);
+      comfyFail('ComfyUI 请求未通过，请核对服务状态与 API 工作流', stage,
+        response.status === 401 || response.status === 403 ? 'authentication' : 'provider',
+        stage === 'validate' ? 'not_accepted' : method === 'POST' ? rejection ? 'not_accepted' : 'unknown' : 'accepted', { httpStatus: response.status });
+    }
+    let bytes;
+    try { bytes = await bounded(response, binary ? 64 * 1024 * 1024 : 2 * 1024 * 1024, stage); }
+    catch (error) {
+      if (error instanceof ProviderContractError) throw error;
+      comfyFail('ComfyUI 响应读取中断', stage, 'network', stage === 'submit' ? 'unknown' : stage === 'validate' ? 'not_accepted' : 'accepted');
+    }
+    if (binary) return bytes;
+    try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+    catch (_) { comfyFail('ComfyUI 返回了无法识别的响应', stage, 'protocol', stage === 'submit' ? 'unknown' : stage === 'validate' ? 'not_accepted' : 'accepted'); }
+  }
+  return Object.freeze({ route, request });
+}

package/lib/comfyui-inspection.js

@@ -0,0 +1,73 @@
+// Partial preflight against official /object_info/{node_class}. Never queues a prompt.
+import { comfyWorkflowDigest, projectComfyWorkflow } from './comfyui-workflow.js';
+import { comfyFail } from './comfyui-client.js';
+
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const link = value => Array.isArray(value) && value.length === 2 && typeof value[0] === 'string' && Number.isSafeInteger(value[1]) && value[1] >= 0;
+const MESSAGES = { node_unavailable: '节点尚未安装、未加载或不存在', input_missing: '缺少必需输入',
+  choice_unavailable: '所选值不在服务当前公布的选项中，请核对模型文件或选项', input_type: '输入类型与服务定义不符',
+  input_range: '数值超出服务允许范围', link_invalid: '连接引用的节点或输出不存在', link_type: '连接两端的数据类型不符',
+  output_node_required: '请选择可执行的图片输出节点', parameter_schema_unsupported: '此参数的节点定义暂不支持静态检查' };
+function literalIssue(value, spec) {
+  if (!Array.isArray(spec)) return null;
+  const [type, limits] = spec;
+  if (Array.isArray(type)) return type.includes(value) ? null : 'choice_unavailable';
+  if (!['STRING', 'BOOLEAN', 'INT', 'FLOAT'].includes(type)) return null;
+  if (type === 'STRING' ? typeof value !== 'string' : type === 'BOOLEAN' ? typeof value !== 'boolean'
+    : type === 'INT' ? !Number.isSafeInteger(value) : typeof value !== 'number' || !Number.isFinite(value)) return 'input_type';
+  if (typeof value === 'number' && (typeof limits?.min === 'number' && value < limits.min || typeof limits?.max === 'number' && value > limits.max)) return 'input_range';
+  return null;
+}
+export async function inspectComfyWorkflow(client, workflow, { signal, timeoutMs = 15000 } = {}) {
+  const combined = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(signal ? [signal] : [])]);
+  const schemas = new Map();
+  for (const type of new Set(Object.values(workflow.graph).map(node => node.class_type))) {
+    const value = await client.request(client.route('object_info/' + encodeURIComponent(type)), { signal: combined, stage: 'validate', timeoutMs });
+    if (!object(value) || Object.hasOwn(value, type) && (!object(value[type]) || !object(value[type].input)
+        || value[type].input.required !== undefined && !object(value[type].input.required)
+        || value[type].input.optional !== undefined && !object(value[type].input.optional)
+        || !Array.isArray(value[type].output))) comfyFail('ComfyUI 节点定义响应无效', 'validate');
+    schemas.set(type, Object.hasOwn(value, type) ? value[type] : null);
+  }
+  const issues = [], fields = new Map();
+  const issue = (code, node, input) => {
+    const parameter = workflow.parameters?.find(parameter => parameter.node === node && parameter.input === input);
+    const label = parameter?.label || parameter?.id || '节点 ' + node + (input ? ' 的 ' + input : '');
+    issues.push({ code, node, ...(input ? { input } : {}), message: label + '：' + MESSAGES[code] });
+  };
+  for (const [id, node] of Object.entries(workflow.graph)) {
+    const schema = schemas.get(node.class_type);
+    if (!schema) { issue('node_unavailable', id); continue; }
+    const inputs = { ...schema.input.optional, ...schema.input.required };
+    fields.set(id, inputs);
+    for (const name of Object.keys(schema.input.required || {})) if (!Object.hasOwn(node.inputs, name)) issue('input_missing', id, name);
+    for (const [name, value] of Object.entries(node.inputs)) {
+      const spec = inputs[name];
+      if (link(value)) {
+        const source = workflow.graph[value[0]], sourceSchema = source && schemas.get(source.class_type);
+        if (!source || sourceSchema && value[1] >= sourceSchema.output.length) issue('link_invalid', id, name);
+        const expected = spec?.[0], actual = sourceSchema?.output[value[1]];
+        if (typeof expected === 'string' && typeof actual === 'string' && expected !== '*' && actual !== '*'
+            && !expected.includes(',') && !actual.includes(',') && expected !== actual) issue('link_type', id, name);
+      } else {
+        const code = literalIssue(value, spec);
+        if (code) issue(code, id, name);
+      }
+    }
+  }
+  const output = schemas.get(workflow.graph[workflow.outputNode].class_type);
+  if (output && output.output_node !== true) issue('output_node_required', workflow.outputNode);
+  const parameters = (projectComfyWorkflow(workflow).parameters || []).map(parameter => {
+    const { default: value, ...descriptor } = parameter;
+    const spec = fields.get(parameter.node)?.[parameter.input];
+    if (!spec || !Array.isArray(spec) || !Array.isArray(spec[0]) && !['STRING', 'BOOLEAN', 'INT', 'FLOAT'].includes(spec[0])) {
+      issue('parameter_schema_unsupported', parameter.node, parameter.input);
+    }
+    const choices = Array.isArray(spec?.[0]) ? spec[0] : null;
+    return { ...descriptor, value, ...(choices ? { availableChoices: choices.slice(0, 256), choicesTruncated: choices.length > 256 } : {}) };
+  });
+  return { contractVersion: 0, ok: issues.length === 0, workflowSha256: comfyWorkflowDigest(workflow),
+    nodeCount: Object.keys(workflow.graph).length, checkedClasses: schemas.size, parameters, issues,
+    scope: 'node-definitions-and-literal-inputs', executed: false, persisted: false,
+    limitations: ['不执行节点或自定义校验；不证明模型家族兼容、显存充足、外部服务可用或真实出图成功'] };
+}

package/lib/comfyui-workflow.js

@@ -0,0 +1,94 @@
+// API graph configuration only. Never evaluates code or reads a local workflow path.
+import crypto from 'node:crypto';
+
+export const MAX_COMFY_WORKFLOW_BYTES = 40 * 1024;
+const NODE = /^[A-Za-z0-9_.:-]{1,100}$/;
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const fail = () => { throw Object.assign(new TypeError('ComfyUI 需要有界的 API 工作流、提示词节点、输出节点和可选尺寸节点；请使用 Export (API)'), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
+const PARAMETER = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const scalar = value => typeof value === 'string' && value.length <= 20000 || typeof value === 'boolean'
+  || typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER;
+const parameterFail = message => { throw Object.assign(new TypeError('ComfyUI 参数无效：' + message), { code: 'IRIS_COMFYUI_PARAMETERS_INVALID' }); };
+export function normalizeComfyParameters(value) {
+  if (!object(value) || !Object.keys(value).length || Object.keys(value).length > 32
+      || Object.keys(value).some(key => !PARAMETER.test(key) || ['constructor', 'prototype'].includes(key) || !scalar(value[key]))
+      || Buffer.byteLength(JSON.stringify(value)) > 24 * 1024) parameterFail('需要 1–32 个具名标量，最多 24 KiB');
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, value[key]]));
+}
+function parameterValue(parameter, value) {
+  if (!scalar(value) || (parameter.type === 'integer' ? !Number.isSafeInteger(value)
+    : parameter.type === 'number' ? typeof value !== 'number' : typeof value !== parameter.type)
+      || parameter.min !== undefined && value < parameter.min || parameter.max !== undefined && value > parameter.max
+      || parameter.choices !== undefined && !parameter.choices.includes(value)) parameterFail(parameter.id + ' 的类型、范围或选项不符');
+  return value;
+}
+export function checkedComfyWorkflow(value) {
+  if (!object(value) || Object.keys(value).some(key => !['version', 'graph', 'promptNode', 'outputNode', 'sizeNode', 'parameters'].includes(key))
+      || ![0, 1].includes(value.version) || !object(value.graph) || !Object.keys(value.graph).length || Object.keys(value.graph).length > 256
+      || Buffer.byteLength(JSON.stringify(value)) > MAX_COMFY_WORKFLOW_BYTES) fail();
+  for (const [id, node] of Object.entries(value.graph)) {
+    if (!NODE.test(id) || ['__proto__', 'constructor', 'prototype'].includes(id) || !object(node)
+        || typeof node.class_type !== 'string' || !node.class_type || node.class_type.length > 200 || !object(node.inputs)) fail();
+    for (const [input, number] of Object.entries(node.inputs)) {
+      if (typeof number === 'number' && (!Number.isFinite(number) || Number.isInteger(number) && !Number.isSafeInteger(number))) {
+        throw Object.assign(new TypeError('ComfyUI 节点 ' + id + ' 的 ' + input + ' 超出 JavaScript 数值范围；整数须在 ±9007199254740991 内，请调整种子后重新导出'), { code: 'IRIS_CONFIG_INPUT_INVALID' });
+      }
+    }
+  }
+  if (![value.promptNode, value.outputNode].every(id => typeof id === 'string' && Object.hasOwn(value.graph, id))
+      || typeof value.graph[value.promptNode].inputs.text !== 'string') fail();
+  if (value.sizeNode !== undefined && (typeof value.sizeNode !== 'string' || !Object.hasOwn(value.graph, value.sizeNode)
+      || !['width', 'height'].every(key => Number.isSafeInteger(value.graph[value.sizeNode].inputs[key]) && value.graph[value.sizeNode].inputs[key] > 0))) fail();
+  if (value.version === 0 && value.parameters !== undefined) fail();
+  if (value.version === 1) {
+    if (!Array.isArray(value.parameters) || !value.parameters.length || value.parameters.length > 32) fail();
+    const ids = new Set(), targets = new Set([value.promptNode + '\0text',
+      ...(value.sizeNode ? ['width', 'height'].map(key => value.sizeNode + '\0' + key) : [])]);
+    for (const parameter of value.parameters) {
+      if (!object(parameter) || Object.keys(parameter).some(key => !['id', 'label', 'node', 'input', 'type', 'min', 'max', 'choices'].includes(key))
+          || typeof parameter.id !== 'string' || !PARAMETER.test(parameter.id) || ['constructor', 'prototype'].includes(parameter.id) || ids.has(parameter.id)
+          || typeof parameter.node !== 'string' || !Object.hasOwn(value.graph, parameter.node)
+          || typeof parameter.input !== 'string' || !NODE.test(parameter.input) || ['__proto__', 'constructor', 'prototype'].includes(parameter.input)
+          || !Object.hasOwn(value.graph[parameter.node].inputs, parameter.input)
+          || !['string', 'integer', 'number', 'boolean'].includes(parameter.type)
+          || parameter.label !== undefined && (typeof parameter.label !== 'string' || !parameter.label.trim() || parameter.label.length > 80)
+          || targets.has(parameter.node + '\0' + parameter.input)) fail();
+      for (const key of ['min', 'max']) if (parameter[key] !== undefined
+          && (!['integer', 'number'].includes(parameter.type) || !Number.isFinite(parameter[key])
+            || Math.abs(parameter[key]) > Number.MAX_SAFE_INTEGER || parameter.type === 'integer' && !Number.isSafeInteger(parameter[key]))) fail();
+      if (parameter.min !== undefined && parameter.max !== undefined && parameter.min > parameter.max) fail();
+      if (parameter.choices !== undefined && (!Array.isArray(parameter.choices) || !parameter.choices.length || parameter.choices.length > 256)) fail();
+      for (const choice of parameter.choices || []) parameterValue({ ...parameter, choices: undefined }, choice);
+      parameterValue(parameter, value.graph[parameter.node].inputs[parameter.input]);
+      ids.add(parameter.id); targets.add(parameter.node + '\0' + parameter.input);
+    }
+  }
+  return structuredClone(value);
+}
+export function compileComfyWorkflow(value, input = {}) {
+  const workflow = checkedComfyWorkflow(value), parameters = input.workflow_parameters === undefined ? {}
+    : normalizeComfyParameters(input.workflow_parameters);
+  const declared = new Map((workflow.parameters || []).map(parameter => [parameter.id, parameter]));
+  for (const [id, item] of Object.entries(parameters)) {
+    const parameter = declared.get(id);
+    if (!parameter) parameterFail('未开放的槽位 ' + id);
+    workflow.graph[parameter.node].inputs[parameter.input] = parameterValue(parameter, item);
+  }
+  if (input.prompt !== undefined) workflow.graph[workflow.promptNode].inputs.text = input.prompt;
+  return workflow;
+}
+export function comfyWorkflowDigest(value) {
+  const workflow = checkedComfyWorkflow(value);
+  // Stable JSON object ordering: formatting and key order are not a workflow change.
+  const sorted = item => Array.isArray(item) ? item.map(sorted) : object(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, sorted(item[key])])) : item;
+  return crypto.createHash('sha256').update(JSON.stringify(sorted(workflow))).digest('hex');
+}
+export function projectComfyWorkflow(value) {
+  if (value === undefined) return undefined;
+  const workflow = checkedComfyWorkflow(value);
+  return { configured: true, sha256: comfyWorkflowDigest(workflow), nodeCount: Object.keys(workflow.graph).length,
+    promptNode: workflow.promptNode, outputNode: workflow.outputNode, ...(workflow.sizeNode ? { sizeNode: workflow.sizeNode } : {}),
+    ...(workflow.version === 1 ? { version: 1, parameters: workflow.parameters.map(parameter => ({ ...parameter,
+      default: workflow.graph[parameter.node].inputs[parameter.input] })) } : {}) };
+}

package/lib/command-service.js

@@ -429,23 +429,34 @@ export function createCommandService(runtime, ports = {}) {
       if (input.confirm_billing !== true) {
         throw commandError('IRIS_COMMAND_BILLING_CONFIRM_REQUIRED', '重试会创建新任务并可能产生重复生成费用；必须显式确认计费');
       }
-      return runtime.run('execute', async ({ dataRoot }) => {
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
         const before = inspectCoreTask(dataRoot, input.task_id);
         if (before.phase !== 'terminal' || (before.outcome === 'succeeded' && before.deliveryState === 'ready')) {
           throw commandError('IRIS_TASK_NOT_RETRYABLE', '只有终态且未成功交付的 Task 可以重试为新任务');
         }
-        let normalized;
+        let normalized, requestedVideoMode;
+        let suppliedInput = input.provider_input;
+        if (before.capability === 'video') {
+          if (!plain(suppliedInput) || !['t2v', 'i2v', 's2v'].includes(suppliedInput.video_mode)) {
+            throw commandError('IRIS_COMMAND_INPUT_INVALID', '视频重试必须明确 video_mode（t2v/i2v/s2v），并重新提供该模式所需的首帧和音频；旧 Task 不保存这些输入');
+          }
+          const { video_mode, ...generation } = suppliedInput;
+          requestedVideoMode = video_mode; suppliedInput = generation;
+        }
         if (before.capability === 'music' && input.provider_input &&
             ['retry_502', 'retry_delay_ms'].some(field => Object.hasOwn(input.provider_input, field))) {
           throw commandError('IRIS_COMMAND_INPUT_INVALID', 'task.retry 只执行一次重新生成；502重试配置请使用Music生成入口');
         }
-        try { normalized = normalizeGenerationInput(before.capability, input.provider_input, { allowVideoPaths: before.capability === 'video' }); }
+        try { normalized = normalizeGenerationInput(before.capability, suppliedInput, { allowVideoPaths: before.capability === 'video' }); }
         catch (error) {
           if (error instanceof GenerationInputError) throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
           throw error;
         }
+        if (before.capability === 'video' && normalized.videoMode !== requestedVideoMode) {
+          throw commandError('IRIS_COMMAND_INPUT_INVALID', 'video_mode 与重新提供的首帧/音频不符；i2v 需首帧，s2v 需首帧和音频，可通过 CLI 重新提供本地文件');
+        }
         const providerInput = normalized.providerInput;
-        if (before.sourceArtifactId && !normalized.sourceArtifactId) {
+        if (before.capability === 'image' && before.sourceArtifactId && !normalized.sourceArtifactId) {
           throw commandError('IRIS_COMMAND_INPUT_INVALID', '改图重试必须重新提供 source_artifact_id 和修改指令');
         }
         if (Object.hasOwn(input.provider_input, 'model_ref')) {
@@ -454,7 +465,9 @@ export function createCommandService(runtime, ports = {}) {
         const modelRef = String(input.model_ref || '').trim();
         if (input.model_ref !== undefined && !modelRef) throw commandError('IRIS_COMMAND_INPUT_INVALID', 'model_ref 必须是 providerId::modelId 复合引用');
         if (typeof ports.resolveTaskCandidates !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.retry 需要宿主显式提供候选链 resolver');
-        let candidates = await ports.resolveTaskCandidates({ capability: before.capability, modelRef });
+        signal.throwIfAborted();
+        let candidates = await ports.resolveTaskCandidates({ capability: before.capability, modelRef, signal });
+        signal.throwIfAborted();
         if (before.capability === 'video') candidates = videoTaskCandidates(candidates, normalized);
         const result = await createProviderTaskRunner(runtime).submit({
           capability: before.capability,

package/lib/config.js

@@ -1,12 +1,13 @@
 'use strict';
 import { normalizeVisionInputLimits } from './vision-image-input.js';
 import { scopedProvider } from './provider-config-scope.js';
+import { checkedComfyWorkflow, comfyWorkflowDigest } from './comfyui-workflow.js';
 import { currentModelDirectory, modelDirectoryBinding, modelAvailabilityBinding, modelUnavailable, modelUnavailableReason, validateModelDirectory } from './model-directory.js';
 import { refreshModelDirectory } from './model-directory-service.js';
 /**
  * Iris 配置存储：$DSH_HOME/iris/v1/providers.json
  * Iris 独立持有配置；旧工作台仅作为用户显式指定的一次性导入来源。
- * Key 明文落盘（0600）；接口层永远不回明文。
+ * 内联 Key 明文落盘（0600）；环境引用只存名称，解析值不持久化；接口层不回明文。
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -16,6 +17,7 @@ import * as models from './models.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
 import { selectMediaProtocol, selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol, isConfiguredProvider } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
+import { validateProviderCredential, providerCredentialStatus, providerCredentialValue, applyCredentialPatch } from './provider-credentials.js';
 import {
   PROVIDER_HEALTH_FRESH_MS,
   aggregateHealthStates,
@@ -36,6 +38,7 @@ function validateStoredConfig(value) {
   for (const [capability, assignment] of Object.entries(value.assignments)) models.functionPolicy(assignment, capability);
   for (const provider of value.providers) {
     if (!isPlainObject(provider)) throw new Error('provider 条目必须是对象');
+    validateProviderCredential(provider);
     validateModelDirectory(provider.modelDirectory);
     if (provider.id !== undefined && typeof provider.id !== 'string') throw new Error('provider.id 必须是字符串');
     if (provider.baseUrl !== undefined && typeof provider.baseUrl !== 'string') throw new Error('provider.baseUrl 必须是字符串');
@@ -46,7 +49,7 @@ function validateStoredConfig(value) {
       if (!isPlainObject(ref) || typeof ref.provider !== 'string' || !ref.provider.trim()
           || typeof ref.settingsNs !== 'string' || !ref.settingsNs.trim()
           || Object.keys(ref).some(key => !['provider', 'settingsNs'].includes(key))) throw new Error('DSH 连接引用无效');
-      if (provider.apiKey !== undefined || provider.baseUrl !== undefined) throw new Error('DSH 引用不能同时保存密钥或普通 Base URL');
+      if (provider.apiKey !== undefined || provider.apiKeyEnv !== undefined || provider.baseUrl !== undefined) throw new Error('DSH 引用不能同时保存密钥、环境引用或普通 Base URL');
     }
     if (provider.models !== undefined && !Array.isArray(provider.models)) throw new Error('provider.models 必须是数组');
     for (const model of provider.models || []) {
@@ -71,7 +74,7 @@ function authModeOf(provider) {
 function missingCredentials(provider) {
   if (!provider || authModeOf(provider) === 'none') return false;
   if (provider.dshProvider) return false;
-  return typeof provider.apiKey !== 'string' || !provider.apiKey.trim();
+  return providerCredentialStatus(provider) !== 'ready';
 }
 
 function normalizeStoredProvider(provider) {
@@ -132,6 +135,9 @@ export function load() {
     for (const provider of cache.providers) normalized = normalizeStoredProvider(provider) || normalized;
     if (normalized) persist();
   } catch (err) {
+    // A rejected source/field combination is actionable configuration, not corrupt
+    // JSON. Keep it intact so a policy change cannot quarantine user providers.
+    if (err.code === 'IRIS_CONFIG_INPUT_INVALID') throw err;
     // 文件存在但损坏：隔离，绝不静默覆盖证据
     const backup = privateSibling(file, 'corrupted');
     try {
@@ -399,9 +405,8 @@ function healthObservation(provider, modelId, capability) {
 function safeHealthNote(provider, value) {
   const raw = String(value ?? '').trim();
   if (!raw) return '';
-  let note = redactProviderMessage(raw, 200);
-  const key = String(provider && scopedProvider(provider).apiKey || '');
-  if (key) note = note.split(key).join('[REDACTED]');
+  const key = providerCredentialValue(provider && scopedProvider(provider));
+  let note = redactProviderMessage(key ? raw.split(key).join('[REDACTED]') : raw, 200);
   return note;
 }
 
@@ -586,13 +591,14 @@ export function upsert(provider) {
     if (!isPlainObject(reference) || typeof reference.provider !== 'string' || !reference.provider.trim()
         || typeof reference.settingsNs !== 'string' || !reference.settingsNs.trim()
         || Object.keys(reference).some(key => !['provider', 'settingsNs'].includes(key))) throw new Error('DSH 连接引用无效');
-    if (['apiKey', 'baseUrl'].some(key => rest[key] !== undefined || existing?.[key] !== undefined)) {
+    if (['apiKey', 'apiKeyEnv', 'baseUrl'].some(key => rest[key] !== undefined || existing?.[key] !== undefined)) {
       throw new Error('DSH 引用不保存密钥或普通 Base URL；请新建引用供应商');
     }
     rest.dshProvider = { provider: reference.provider.trim(), settingsNs: reference.settingsNs.trim() };
   }
   if (rest.visionInput !== undefined) rest.visionInput = normalizeVisionInputLimits(rest.visionInput) || null;
   if (Array.isArray(rest.models)) rest.models = rest.models.map(model => typeof model === 'string' ? model : ({ ...model,
+    ...(model?.comfyWorkflow !== undefined ? { comfyWorkflow: checkedComfyWorkflow(model.comfyWorkflow) } : {}),
     ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
     ...(model?.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(model.musicProtocol) } : {}),
     ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
@@ -600,7 +606,7 @@ export function upsert(provider) {
     const i = c.providers.findIndex((p) => p.id === id);
     if (i >= 0) {
       const previous = c.providers[i];
-      const next = { ...previous, ...rest };
+      const next = applyCredentialPatch(previous, rest);
       if (Object.prototype.hasOwnProperty.call(rest, 'mediaProtocol')) next.protocolInferred = false;
       normalizeStoredProvider(next);
       resetHealthOnCriticalChange(previous, next, rest);
@@ -611,7 +617,7 @@ export function upsert(provider) {
       return next;
     }
   }
-  const fresh = { id: 'iris_' + Math.random().toString(36).slice(2, 8), ...rest };
+  const fresh = applyCredentialPatch(null, { id: 'iris_' + Math.random().toString(36).slice(2, 8), ...rest });
   fresh.protocolInferred = false;
   normalizeStoredProvider(fresh);
   c.providers.push(fresh);
@@ -646,6 +652,7 @@ export function setProviderModels(id, modelEntries) {
     for (const m of p.models || []) if (m && m.id) prev.set(m.id, m);
     p.models = modelEntries.map((m) => {
       const entry = typeof m === 'string' ? { id: m } : { id: m.id, capabilities: m.capabilities,
+        ...(m.comfyWorkflow !== undefined ? { comfyWorkflow: checkedComfyWorkflow(m.comfyWorkflow) } : {}),
         ...(m.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(m.imageProtocol) } : {}),
         ...(m.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(m.musicProtocol) } : {}),
         ...(m.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(m.visionInput) || null } : {}) };
@@ -657,6 +664,7 @@ export function setProviderModels(id, modelEntries) {
         if (m?.imageProtocol === undefined && old.imageProtocol !== undefined) entry.imageProtocol = old.imageProtocol;
         if (m?.musicProtocol === undefined && old.musicProtocol !== undefined) entry.musicProtocol = old.musicProtocol;
         if (m?.visionInput === undefined && old.visionInput !== undefined) entry.visionInput = old.visionInput;
+        if (m?.comfyWorkflow === undefined && old.comfyWorkflow !== undefined) entry.comfyWorkflow = old.comfyWorkflow;
       }
       if (m && m.verified) entry.verified = m.verified;
       if (m && m.source) entry.source = m.source;
@@ -701,12 +709,43 @@ function resetChangedImageProtocolHealth(previous, next) {
     if (model.musicProtocol !== models.providerModels(next).find(item => item.id === model.id)?.musicProtocol) {
       clearModelCapabilityHealth(next, model.id, cap.CAPABILITIES.MUSIC);
     }
-    if (selectImageProtocol(previous, model.id).mediaProtocol !== selectImageProtocol(next, model.id).mediaProtocol) {
+    const beforeWorkflow = previous.models?.find(item => item?.id === model.id)?.comfyWorkflow;
+    const afterWorkflow = next.models?.find(item => item?.id === model.id)?.comfyWorkflow;
+    if (selectImageProtocol(previous, model.id).mediaProtocol !== selectImageProtocol(next, model.id).mediaProtocol
+        || (beforeWorkflow ? comfyWorkflowDigest(beforeWorkflow) : null) !== (afterWorkflow ? comfyWorkflowDigest(afterWorkflow) : null)) {
       clearModelCapabilityHealth(next, model.id, cap.CAPABILITIES.IMAGE);
     }
   }
 }
 
+/** One explicit save; stale workflow drafts cannot replace a newer template. */
+export function setComfyWorkflow(id, modelId, value, { expectedSha, enableAutomatic = false } = {}) {
+  const workflow = checkedComfyWorkflow(value);
+  if (typeof modelId !== 'string' || !modelId.trim() || modelId.trim().length > 120
+      || !(expectedSha === null || typeof expectedSha === 'string' && /^[a-f0-9]{64}$/.test(expectedSha))
+      || typeof enableAutomatic !== 'boolean') throw new TypeError('请填写工作流名称并核对原工作流摘要');
+  const c = load(), provider = c.providers.find(item => item.id === id);
+  if (!provider || selectMediaProtocol(provider).mediaProtocol !== 'comfyui') throw new TypeError('请先保存 ComfyUI 连接');
+  const entries = (Array.isArray(provider.models) ? provider.models : models.providerModels(provider))
+    .map(model => typeof model === 'string' ? { id: model } : { ...model });
+  const name = modelId.trim(), old = entries.find(model => model.id === name);
+  if ((old?.comfyWorkflow ? comfyWorkflowDigest(old.comfyWorkflow) : null) !== expectedSha) {
+    throw Object.assign(new Error('工作流已变化，请重新读取后核对；草稿未保存'), { code: 'IRIS_CONFIG_CHANGED' });
+  }
+  const entry = { ...old, id: name, source: 'manual', imageProtocol: 'comfyui', comfyWorkflow: workflow,
+    capabilities: [...new Set([...(old?.capabilities || []), cap.CAPABILITIES.IMAGE])] };
+  if (old) entries[entries.indexOf(old)] = entry; else entries.push(entry);
+  const next = { ...provider, models: entries };
+  resetChangedImageProtocolHealth(provider, next);
+  c.providers[c.providers.indexOf(provider)] = next;
+  if (enableAutomatic) {
+    const previous = models.functionPolicy(c.assignments[cap.CAPABILITIES.IMAGE], cap.CAPABILITIES.IMAGE);
+    c.assignments[cap.CAPABILITIES.IMAGE] = { mode: 'auto', models: previous.models.slice() };
+  }
+  persist();
+  return entry;
+}
+
 /** 手动选择单模型图片协议；auto 恢复账号默认，不解除模型停用。 */
 export function setModelImageProtocol(id, modelId, value) {
   const protocol = normalizeImageProtocol(value);

package/lib/configured-image-runtime.js

@@ -0,0 +1,69 @@
+// Shared CLI/service assembly. Configuration is read only during explicit commands.
+import path from 'node:path';
+import { loadProviderCatalog, imageCandidatesFromCatalog, ttsCandidatesFromCatalog, transcribeCandidatesFromCatalog, videoCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding } from './provider-catalog.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { recordCatalogAvailability, recordCatalogRateLimit } from './provider-config-service.js';
+import { parseModelRef } from './models.js';
+import { supportsImageEdit } from './provider-protocol.js';
+import { compileComfyWorkflow } from './comfyui-workflow.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+
+export function createTrackedProviderAdapter(provider, providerConfigPath, task, registry, { network, modelRef, deferCooling = false } = {}) {
+  if (task && !sameNetworkRequirement(task.networkRequirement, providerNetworkRequirement(provider))) {
+    throw networkPolicyError('IRIS_NETWORK_REQUIREMENT_MISMATCH', '原 Task 的网络要求与当前供应商目录不一致；不会隐式转换或解除');
+  }
+  return createConfiguredProviderAdapter(provider, {
+    registry,
+    ...(network !== undefined ? { network } : {}),
+    modelId: parseModelRef(task?.modelRef || modelRef)?.modelId,
+    deferCooling,
+    onModelAvailability: event => recordCatalogAvailability(providerConfigPath, event),
+    onRateLimit: event => recordCatalogRateLimit(providerConfigPath, event)
+  });
+}
+
+export function configuredImagePorts(providerConfigPath, registry, { resolveProviderNetwork, deferCooling = false } = {}) {
+  if (typeof providerConfigPath !== 'string' || !path.isAbsolute(providerConfigPath)) throw new TypeError('Provider 配置须为显式绝对路径');
+  if (resolveProviderNetwork !== undefined && typeof resolveProviderNetwork !== 'function') throw new TypeError('resolveProviderNetwork 必须是函数');
+  const adapterFor = (provider, task, modelRef) => createTrackedProviderAdapter(provider, providerConfigPath, task, registry, {
+    modelRef, deferCooling,
+    network: resolveProviderNetwork?.({ providerId: provider.id, modelRef: modelRef || task?.modelRef, taskId: task?.id,
+      ...(providerNetworkRequirement(provider) ? { networkRequirement: providerNetworkRequirement(provider) } : {}) })
+  });
+  return Object.freeze({
+    resolveVideoCandidates({ modelRef, signal }) {
+      signal?.throwIfAborted();
+      return videoCandidatesFromCatalog(loadProviderCatalog(providerConfigPath), modelRef, registry, { deferCooling }).map(route => ({
+        adapter: adapterFor(route.provider, undefined, route.modelRef), model: route.modelRef,
+        providerBinding: providerTaskBinding(route.provider, registry), selectionReason: 'explicit'
+      }));
+    },
+    resolveAudioCandidates({ capability, modelRef, signal }) {
+      signal?.throwIfAborted();
+      if (!['tts', 'transcribe'].includes(capability)) throw new TypeError('未知音频能力');
+      const select = capability === 'tts' ? ttsCandidatesFromCatalog : transcribeCandidatesFromCatalog;
+      return select(loadProviderCatalog(providerConfigPath), modelRef, registry, { deferCooling }).map(route => ({
+        adapter: adapterFor(route.provider, undefined, route.modelRef), model: route.modelRef,
+        providerBinding: providerTaskBinding(route.provider, registry), selectionReason: 'explicit'
+      }));
+    },
+    resolveImageCandidates({ modelRef, signal, input }) {
+      signal?.throwIfAborted();
+      return imageCandidatesFromCatalog(loadProviderCatalog(providerConfigPath), modelRef, registry, { deferCooling }).map(route => {
+        if (input?.workflow_parameters !== undefined) {
+          if (route.provider.mediaProtocol !== 'comfyui') throw Object.assign(new TypeError('工作流参数仅用于 ComfyUI 模板'), { code: 'IRIS_COMFYUI_PARAMETERS_INVALID' });
+          compileComfyWorkflow(route.provider.comfyWorkflow, input);
+        }
+        return {
+          adapter: adapterFor(route.provider, undefined, route.modelRef), model: route.modelRef,
+          supportsImageEdit: supportsImageEdit(route.provider.mediaProtocol, route.model, registry),
+          providerBinding: providerTaskBinding(route.provider, registry), selectionReason: 'explicit'
+        };
+      });
+    },
+    resolveTaskAdapter(task, { signal } = {}) {
+      signal?.throwIfAborted();
+      return adapterFor(providerForTaskFromCatalog(loadProviderCatalog(providerConfigPath), task, registry), task);
+    }
+  });
+}