@mokuyoaxis/dsh-iris 0.2.6 → 0.3.0-alpha.1

package/lib/dsh-host-adapter.js

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { defineHostAdapter } from './host-contract.js';
 import { BrowserHtmlRenderer } from './render.js';
+import { resolveRenderAddress } from './render-address.js';
 import { createDshProviderSource } from './dsh-provider-source.js';
 
 export function detectDshVersion({ entry = process.argv[1] } = {}) {
@@ -132,12 +133,15 @@ function dshVisionPort(llm, defaults) {
         if (chunk?.type === 'finish') {
           if (chunk.reason?.kind === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
           if (chunk.reason?.kind === 'aborted') throw visionRouteError('DSH 视觉调用已取消');
+          if (['length', 'max-tokens', 'tool-calls', 'content-blocked'].includes(chunk.reason?.kind)) {
+            throw visionRouteError('DSH 视觉结果未完整结束：' + chunk.reason.kind);
+          }
         }
         const text = typeof chunk?.delta === 'string'
           ? chunk.delta
           : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
         if (text) chunks.push(text);
-        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) break;
+        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) throw visionRouteError('DSH 视觉结果超过长度限制，未返回部分结果');
       }
       return chunks.join('').trim();
     }
@@ -160,8 +164,10 @@ export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {})
 
   const browser = service(ctx, 'browser');
   if (browser && ['open', 'openUrl', 'screenshot', 'close'].every((name) => typeof browser[name] === 'function')) {
-    const renderer = new BrowserHtmlRenderer({ browser });
+    const getAddress = () => resolveRenderAddress(service(ctx, 'webServer') || service(ctx, 'httpServer'));
+    const renderer = new BrowserHtmlRenderer({ browser, getAddress });
     ports.browser = Object.freeze({
+      get address() { return getAddress(); },
       async renderHtml(input) {
         const { png } = await renderer.render(input);
         return { bytes: new Uint8Array(png), mediaType: 'image/png' };

package/lib/dsh-service-bridge.js

@@ -0,0 +1,66 @@
+import { createCoreServiceClient } from './core-service-client.js';
+import { bridgeToolsForScopes, callCoreBridgeTool } from './core-bridge-tools.js';
+import { requireHostPort } from './host-contract.js';
+
+/** Optional shared-Flow connection. Native DSH ports stay in the host; no remote ctx or local execution fallback. */
+export function createDshServiceBridge({ connectionFile, requestedScopes = ['read'], getHost, harnessVersion = 'unknown', fetch } = {}) {
+  if (typeof getHost !== 'function') throw new TypeError('DSH 服务桥需要真实 Host 工厂');
+  const client = createCoreServiceClient({ connectionFile, requestedScopes, harnessVersion, fetch });
+  const lifetime = new AbortController(), jobs = new Set();
+  const toolDisposers = [];
+  let state = 'new', disposal, remoteDisconnect = 'not_connected';
+  async function start() {
+    if (state !== 'new') throw new Error('DSH Core 服务桥只能启动一次');
+    state = 'connecting';
+    try {
+      await client.connect();
+      if (client.snapshot().adapterId !== 'iris.dsh-service') throw Object.assign(new Error('连接文件不是 DSH 适配授权'), { code: 'IRIS_CONNECTION_INPUT_INVALID' });
+      const selected = client.snapshot();
+      if (selected.capabilities.some(id => ['tts', 'transcribe'].includes(id))) throw Object.assign(new Error('DSH 原生共享桥尚未接入音频附件交付；请为此桥选择图片功能，音频使用通用 MCP 或 Core 工作台'), { code: 'IRIS_DSH_AUDIO_NOT_SUPPORTED' });
+      const tools = requireHostPort(getHost(), 'tools', '注册 Core 服务工具');
+      for (const tool of bridgeToolsForScopes(selected.scopes, selected.capabilities, selected.tools, selected.pluginOperations)) {
+        const remove = tools.register({ name: tool.name, description: tool.description, parameters: tool.parameters,
+          isConcurrencySafe: () => tool.scope === 'read' || tool.scope === 'stop',
+          output: { schema: { type: 'object' }, render: (_args, result) => result.blocks },
+          async execute(args, exec = {}) {
+            const signal = AbortSignal.any([lifetime.signal, ...(exec.signal ? [exec.signal] : [])]);
+            const job = (async () => {
+              signal.throwIfAborted();
+              const result = await callCoreBridgeTool(client, tool.name, args, { signal });
+              if (!result.image) return { value: result.value, blocks: [{ type: 'text', text: JSON.stringify(result.value) }] };
+              const attachments = requireHostPort(getHost(), 'attachments', '显示 Core 图片');
+              const attachment = await attachments.saveImage({ data: new Uint8Array(result.image.bytes), mediaType: result.image.mediaType,
+                name: 'iris-core-' + result.image.artifactId + '.' + (result.image.mediaType === 'image/jpeg' ? 'jpg' : result.image.mediaType.slice(6)) });
+              signal.throwIfAborted();
+              if (!attachment?.attachmentId) throw Object.assign(new Error('DSH 没有返回图片附件身份'), { code: 'IRIS_DSH_PROJECTION_FAILED' });
+              return { artifactId: result.image.artifactId, blocks: [{ type: 'image', attachment }] };
+            })();
+            jobs.add(job); try { return await job; } finally { jobs.delete(job); }
+          }
+        });
+        if (typeof remove === 'function') toolDisposers.push(remove);
+      }
+      state = 'open'; return snapshot();
+    } catch (error) {
+      try { await dispose(); }
+      catch (cleanup) { throw new AggregateError([error, cleanup], 'DSH 服务桥启动与释放均失败'); }
+      throw error;
+    }
+  }
+  function snapshot() { return { state, connection: client.snapshot(), operations: jobs.size, remoteDisconnect }; }
+  function dispose() {
+    if (disposal) return disposal;
+    state = 'closing'; lifetime.abort();
+    disposal = (async () => {
+      const errors = [];
+      for (const remove of toolDisposers.splice(0).reverse()) { try { await remove(); } catch (error) { errors.push(error); } }
+      await Promise.allSettled([...jobs]);
+      try { remoteDisconnect = (await client.dispose()).remoteDisconnect; } catch (error) { errors.push(error); }
+      state = 'closed';
+      if (errors.length) throw new AggregateError(errors, 'DSH 服务桥释放失败');
+      return snapshot();
+    })();
+    return disposal;
+  }
+  return Object.freeze({ start, snapshot, dispose });
+}

package/lib/execution-ownership.js

@@ -0,0 +1,43 @@
+// Runner ownership uses the existing Core lease protocol in its own private directory.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readWriterLease, WRITER_LEASE_DIR, WRITER_INTENT_FILE } from './core-writer-lease.js';
+
+const UUID = '[a-f0-9-]{36}';
+const FILE = new RegExp('^(?:' + WRITER_INTENT_FILE.replaceAll('.', '\\.')
+  + '(?:\\.prepare-[1-9][0-9]*-[a-f0-9]{12})?|' + WRITER_LEASE_DIR.replaceAll('.', '\\.')
+  + '\\.recovery-' + UUID + '\\.json)$');
+const RETIRED = new RegExp('^' + WRITER_LEASE_DIR.replaceAll('.', '\\.') + '\\.released-' + UUID + '$');
+const invalid = () => { throw Object.assign(new Error('执行所有权目录未知或损坏；已保留现场'), { code: 'IRIS_EXECUTION_LEASE_INVALID' }); };
+
+export function inspectRunnerArea(directory) {
+  function regular(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024) invalid();
+  }
+  function ownerDirectory(file, audit = false) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+    for (const name of fs.readdirSync(file)) {
+      if (name !== 'owner.json' && !/^\.owner\.stale-[a-f0-9-]{36}\.json$/.test(name)
+          && !(audit && new RegExp('^' + WRITER_LEASE_DIR.replaceAll('.', '\\.') + '\\.recovery-' + UUID + '\\.json$').test(name))) invalid();
+      regular(path.join(file, name));
+    }
+  }
+  for (const name of fs.readdirSync(directory)) {
+    const file = path.join(directory, name);
+    if (name === WRITER_LEASE_DIR || RETIRED.test(name)) ownerDirectory(file);
+    else if (FILE.test(name)) regular(file);
+    else if (name === '.iris-runtime-recovery-audit-v0') {
+      const stat = fs.lstatSync(file);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+      for (const entry of fs.readdirSync(file)) {
+        if (/^lease_recovery_[a-f0-9]{24}\.json$/.test(entry)) regular(path.join(file, entry));
+        else if (/^lease_recovery_[a-f0-9]{24}\.lease$/.test(entry)) ownerDirectory(path.join(file, entry), true);
+        else invalid();
+      }
+    } else invalid();
+  }
+  try { return readWriterLease(directory); }
+  catch (_) { invalid(); }
+}

package/lib/flow-store.js

@@ -0,0 +1,290 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, isAbandonedWriterPreparation } from './core-writer-lease.js';
+import { normalizeGenerationInput } from './generation-input.js';
+import { parseModelRef } from './models.js';
+import { inspectLocalRequestRoot } from './local-request-root.js';
+import { normalizeComfyParameters } from './comfyui-workflow.js';
+import { AUDIO_RECIPES, isAudioRecipe, normalizeAudioFlowInput } from './audio-flow-input.js';
+
+const RUN = /^run_[a-f0-9]{24}$/;
+const TASK = /^task_[a-f0-9]{24}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const SHA = /^[a-f0-9]{64}$/;
+const BINDING = /^sha256:[a-f0-9]{64}$/;
+const RECIPE = 'image-edit/v0';
+export const IMAGE_GENERATE_RECIPE = 'image-generate/v0';
+
+export class FlowError extends Error {
+  constructor(code, message) { super(message); this.name = 'FlowError'; this.code = code; }
+}
+export function flowFail(code, message) { throw new FlowError(code, message); }
+
+function keys(value, allowed, required = allowed) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key)));
+}
+function iso(value) { return typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value; }
+const copy = value => Object.freeze(structuredClone(value));
+export const flowId = prefix => prefix + '_' + crypto.randomBytes(12).toString('hex');
+export const flowSha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+export const flowStepId = run => isAudioRecipe(run.recipe) ? AUDIO_RECIPES[run.recipe].step : run.recipe === IMAGE_GENERATE_RECIPE ? 'generate' : 'edit';
+export const flowCapability = run => isAudioRecipe(run.recipe) ? AUDIO_RECIPES[run.recipe].capability : 'image';
+export const flowStep = run => run[flowStepId(run)];
+export function requireImageGenerationRoot(root) {
+  if (![2, 3].includes(inspectLocalRequestRoot(root, { allowAbsent: true })?.schemaVersion)) {
+    flowFail('IRIS_FLOW_GENERATION_ROOT_REQUIRED', '文生图需要新的专用执行根：execution init --image-generation；不迁移已有根');
+  }
+}
+export function requireAudioRoot(root) {
+  if (inspectLocalRequestRoot(root, { allowAbsent: true })?.schemaVersion !== 3) {
+    flowFail('IRIS_FLOW_AUDIO_ROOT_REQUIRED', '音频需要新的专用执行根：execution init --audio；不迁移已有根');
+  }
+}
+
+export function validFlowBinding(value) {
+  return keys(value, ['runId', 'stepId', 'inputDigest']) && RUN.test(value.runId)
+    && ['edit', 'generate', 'speak', 'transcribe'].includes(value.stepId) && BINDING.test(value.inputDigest);
+}
+export function flowTaskBinding(run) { return { runId: run.id, stepId: flowStepId(run), inputDigest: run.inputDigest }; }
+
+function inputDigest(run) {
+  if (isAudioRecipe(run.recipe)) return 'sha256:' + flowSha256(JSON.stringify([run.recipe, run.providerBinding,
+    normalizeAudioFlowInput(run.recipe, run.input), run.source?.sha256 ?? null]));
+  if (run.recipe === IMAGE_GENERATE_RECIPE) return 'sha256:' + flowSha256(JSON.stringify([IMAGE_GENERATE_RECIPE,
+    run.input.model_ref, run.providerBinding, run.input.prompt, run.input.size ?? null, 1,
+    ...(run.input.workflow_parameters !== undefined ? [['comfyui-parameters/v0', normalizeComfyParameters(run.input.workflow_parameters)]] : [])]));
+  return 'sha256:' + flowSha256(JSON.stringify([RECIPE, run.source.artifactId, run.source.sha256,
+    run.input.model_ref, run.providerBinding, run.input.prompt, run.input.size ?? null, 1]));
+}
+
+function reference(value) { return keys(value, ['artifactId', 'sha256']) && ARTIFACT.test(value.artifactId) && SHA.test(value.sha256); }
+function validateAudio(run, expectedId) {
+  let normalized;
+  try { normalized = normalizeAudioFlowInput(run.recipe, run.input); }
+  catch (_) { flowFail('IRIS_FLOW_RECORD_INVALID', '音频流程输入无效'); }
+  const step = flowStepId(run), transcribe = run.recipe === 'transcribe/v0';
+  if (!keys(run, ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'input', 'providerBinding', 'inputDigest', step, 'source', 'output'],
+    ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'input', 'providerBinding', 'inputDigest', step, ...(transcribe ? ['source'] : [])])
+      || run.schemaVersion !== 3 || !RUN.test(run.id) || run.id !== expectedId || !Number.isSafeInteger(run.revision) || run.revision < 1
+      || !iso(run.createdAt) || !iso(run.updatedAt) || !BINDING.test(run.providerBinding)
+      || JSON.stringify(run.input) !== JSON.stringify(normalized)
+      || transcribe && (!reference(run.source) || run.source.artifactId !== run.input.source_artifact_id)
+      || !transcribe && run.source !== undefined
+      || !keys(run[step], ['taskId', 'claimed']) || !TASK.test(run[step].taskId) || typeof run[step].claimed !== 'boolean'
+      || run.inputDigest !== inputDigest(run) || run.output !== undefined && (!reference(run.output) || !run[step].claimed)) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '音频流程记录结构或绑定摘要冲突');
+  }
+  return run;
+}
+function validateGeneration(run, expectedId, normalized) {
+  if (!keys(run, ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'input', 'providerBinding',
+    'inputDigest', 'generate', 'output', 'selection'],
+  ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'input', 'providerBinding', 'inputDigest', 'generate'])
+      || run.schemaVersion !== (run.input?.workflow_parameters === undefined ? 1 : 2) || run.recipe !== IMAGE_GENERATE_RECIPE || !RUN.test(run.id) || run.id !== expectedId
+      || !Number.isSafeInteger(run.revision) || run.revision < 1 || !iso(run.createdAt) || !iso(run.updatedAt)
+      || !BINDING.test(run.providerBinding) || !parseModelRef(run.input.model_ref)
+      || !keys(run.input, ['prompt', 'model_ref', 'n', 'size', 'workflow_parameters'], ['prompt', 'model_ref', 'n'])
+      || normalized.modelRef !== run.input.model_ref || normalized.sourceArtifactId !== undefined
+      || run.input.prompt !== normalized.providerInput.prompt || run.input.n !== 1
+      || run.input.size !== normalized.providerInput.size
+      || !keys(run.generate, ['taskId', 'claimed']) || !TASK.test(run.generate.taskId) || typeof run.generate.claimed !== 'boolean'
+      || run.inputDigest !== inputDigest(run)
+      || run.output !== undefined && (!reference(run.output) || !run.generate.claimed)
+      || run.selection !== undefined && (!reference(run.selection) || !run.output
+        || run.selection.artifactId !== run.output.artifactId || run.selection.sha256 !== run.output.sha256)) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '文生图记录结构或绑定摘要冲突');
+  }
+  return run;
+}
+function validate(run, expectedId) {
+  if (isAudioRecipe(run?.recipe)) return validateAudio(run, expectedId);
+  let normalized;
+  try { normalized = normalizeGenerationInput('image', run?.input); }
+  catch (_) { flowFail('IRIS_FLOW_RECORD_INVALID', '流程创作输入无效'); }
+  if (run.recipe === IMAGE_GENERATE_RECIPE) return validateGeneration(run, expectedId, normalized);
+  if (!keys(run, ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'source', 'input', 'providerBinding',
+    'inputDigest', 'edit', 'compare', 'output', 'comparison', 'selection'],
+  ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'source', 'input', 'providerBinding', 'inputDigest', 'edit', 'compare'])
+      || run.schemaVersion !== 0 || run.recipe !== RECIPE || !RUN.test(run.id) || run.id !== expectedId
+      || !Number.isSafeInteger(run.revision) || run.revision < 1 || !iso(run.createdAt) || !iso(run.updatedAt)
+      || !reference(run.source) || !BINDING.test(run.providerBinding)
+      || !parseModelRef(run.input.model_ref) || normalized.modelRef !== run.input.model_ref
+      || run.input.prompt !== normalized.providerInput.prompt || run.input.n !== 1
+      || (run.input.size !== undefined && run.input.size !== normalized.providerInput.size)
+      || normalized.sourceArtifactId !== run.source.artifactId
+      || !keys(run.edit, ['taskId', 'claimed']) || !TASK.test(run.edit.taskId) || typeof run.edit.claimed !== 'boolean'
+      || !keys(run.compare, ['artifactId']) || !ARTIFACT.test(run.compare.artifactId)
+      || run.compare.artifactId === run.source.artifactId || run.inputDigest !== inputDigest(run)
+      || (run.output !== undefined && (!reference(run.output) || !run.edit.claimed
+        || [run.source.artifactId, run.compare.artifactId].includes(run.output.artifactId)))
+      || (run.comparison !== undefined && (!reference(run.comparison) || !run.output || run.comparison.artifactId !== run.compare.artifactId))
+      || (run.selection !== undefined && (!reference(run.selection) || !run.comparison
+        || ![run.source, run.output].some(item => item.artifactId === run.selection.artifactId && item.sha256 === run.selection.sha256)))) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录结构或绑定摘要冲突');
+  }
+  return run;
+}
+
+function directory(root, leaf, create = false) {
+  let current = root;
+  for (const segment of ['flow-store', 'v0', ...(leaf ? [leaf] : [])]) {
+    current = path.join(current, segment);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) flowFail('IRIS_FLOW_STORE_UNSAFE', '流程存储目录不安全');
+  }
+  return current;
+}
+function jsonFile(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录不是受支持的普通文件');
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (_) { flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录不是有效 JSON'); }
+}
+
+export function inspectFlowRoot(root) {
+  let marker;
+  try { marker = jsonFile(path.join(directory(root), 'root.json')); }
+  catch (error) {
+    if (error.code === 'ENOENT') flowFail('IRIS_FLOW_ROOT_REQUIRED', '请先在新的专用数据根执行 flow init，再导入图片');
+    throw error;
+  }
+  if (!keys(marker, ['schemaVersion', 'kind', 'createdAt']) || marker.schemaVersion !== 0
+      || marker.kind !== 'iris-image-flow-root' || !iso(marker.createdAt)) flowFail('IRIS_FLOW_RECORD_INVALID', '流程根声明无效或版本不受支持');
+  directory(root, 'runs');
+  return copy(marker);
+}
+
+export function initializeFlowRoot(root) {
+  try { fs.lstatSync(path.join(root, 'flow-store')); return inspectFlowRoot(root); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (fs.readdirSync(root).some(name => ![WRITER_LEASE_DIR, WRITER_INTENT_FILE].includes(name) && !isAbandonedWriterPreparation(root, name))) {
+    flowFail('IRIS_FLOW_ROOT_NOT_EMPTY', '流程只在新的专用数据根启用；不迁移已有 Task/Artifact 数据根');
+  }
+  directory(root, 'runs', true);
+  const marker = { schemaVersion: 0, kind: 'iris-image-flow-root', createdAt: new Date().toISOString() };
+  atomicCreatePrivate(path.join(directory(root), 'root.json'), JSON.stringify(marker, null, 2) + '\n');
+  return copy(marker);
+}
+
+function recordFile(root, id) {
+  if (typeof id !== 'string' || !RUN.test(id)) flowFail('IRIS_FLOW_ID_INVALID', 'Run ID 格式无效');
+  return path.join(directory(root, 'runs'), id + '.json');
+}
+export function readFlowRun(root, id) {
+  inspectFlowRoot(root);
+  let record;
+  try { record = jsonFile(recordFile(root, id)); }
+  catch (error) {
+    if (error.code === 'ENOENT') flowFail('IRIS_FLOW_NOT_FOUND', '流程记录不存在');
+    throw error;
+  }
+  validate(record, id);
+  if (isAudioRecipe(record.recipe)) requireAudioRoot(root);
+  if (record.recipe === IMAGE_GENERATE_RECIPE) requireImageGenerationRoot(root);
+  return copy(record);
+}
+
+/** Internal immutable creation intent; HTTP callers cannot choose these identities. */
+export function prepareFlowCreation({ source, input, providerBinding, recipe }) {
+  if (isAudioRecipe(recipe)) return { recipe, runId: flowId('run'), taskId: flowId('task'), createdAt: new Date().toISOString(),
+    ...(source ? { source } : {}), input, providerBinding };
+  if (!source) return { recipe: IMAGE_GENERATE_RECIPE, runId: flowId('run'), taskId: flowId('task'),
+    createdAt: new Date().toISOString(), input, providerBinding };
+  return { runId: flowId('run'), taskId: flowId('task'), comparisonArtifactId: flowId('artifact'),
+    createdAt: new Date().toISOString(), source, input, providerBinding };
+}
+
+export function validateFlowCreation(intent) {
+  if (isAudioRecipe(intent?.recipe)) {
+    if (!keys(intent, ['recipe', 'runId', 'taskId', 'createdAt', 'input', 'providerBinding', 'source'],
+      ['recipe', 'runId', 'taskId', 'createdAt', 'input', 'providerBinding', ...(intent.recipe === 'transcribe/v0' ? ['source'] : [])])) {
+      flowFail('IRIS_FLOW_RECORD_INVALID', '音频创建意图无效');
+    }
+    const record = { schemaVersion: 3, recipe: intent.recipe, id: intent.runId, revision: 1,
+      createdAt: intent.createdAt, updatedAt: intent.createdAt, input: intent.input, providerBinding: intent.providerBinding,
+      ...(intent.source ? { source: intent.source } : {}), [AUDIO_RECIPES[intent.recipe].step]: { taskId: intent.taskId, claimed: false } };
+    record.inputDigest = inputDigest(record);
+    return validate(record, record.id);
+  }
+  if (intent?.recipe === IMAGE_GENERATE_RECIPE) {
+    if (!keys(intent, ['recipe', 'runId', 'taskId', 'createdAt', 'input', 'providerBinding'])) {
+      flowFail('IRIS_FLOW_RECORD_INVALID', '文生图创建意图无效');
+    }
+    const record = { schemaVersion: intent.input?.workflow_parameters === undefined ? 1 : 2, recipe: IMAGE_GENERATE_RECIPE, id: intent.runId, revision: 1,
+      createdAt: intent.createdAt, updatedAt: intent.createdAt, input: intent.input,
+      providerBinding: intent.providerBinding, generate: { taskId: intent.taskId, claimed: false } };
+    record.inputDigest = inputDigest(record);
+    return validate(record, record.id);
+  }
+  if (!keys(intent, ['runId', 'taskId', 'comparisonArtifactId', 'createdAt', 'source', 'input', 'providerBinding'])) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '流程创建意图无效');
+  }
+  const record = { schemaVersion: 0, recipe: RECIPE, id: intent.runId, revision: 1,
+    createdAt: intent.createdAt, updatedAt: intent.createdAt, source: intent.source, input: intent.input,
+    providerBinding: intent.providerBinding, edit: { taskId: intent.taskId, claimed: false },
+    compare: { artifactId: intent.comparisonArtifactId } };
+  record.inputDigest = inputDigest(record);
+  return validate(record, record.id);
+}
+
+export function commitFlowCreation(root, intent, { allowCreate = true } = {}) {
+  inspectFlowRoot(root);
+  const record = validateFlowCreation(intent);
+  if (isAudioRecipe(record.recipe)) requireAudioRoot(root);
+  if (record.recipe === IMAGE_GENERATE_RECIPE) requireImageGenerationRoot(root);
+  let current;
+  try { current = readFlowRun(root, record.id); }
+  catch (error) { if (error.code !== 'IRIS_FLOW_NOT_FOUND') throw error; }
+  if (current) {
+    if (current.createdAt !== record.createdAt || current.inputDigest !== record.inputDigest
+        || current.recipe !== record.recipe || flowStep(current).taskId !== flowStep(record).taskId
+        || current.compare?.artifactId !== record.compare?.artifactId) {
+      flowFail('IRIS_FLOW_INPUT_CONFLICT', '原流程与预留创建身份不一致');
+    }
+    return current;
+  }
+  if (!allowCreate) flowFail('IRIS_FLOW_NOT_FOUND', '原流程记录已不可用');
+  atomicCreatePrivate(recordFile(root, record.id), JSON.stringify(record, null, 2) + '\n');
+  return copy(record);
+}
+
+export function createFlowRun(root, input) {
+  return commitFlowCreation(root, prepareFlowCreation(input));
+}
+
+export function updateFlowRun(root, previous, patch) {
+  const current = readFlowRun(root, previous.id);
+  if (current.revision !== previous.revision) flowFail('IRIS_FLOW_REVISION_CONFLICT', '流程在本次操作期间已改变');
+  const allowed = isAudioRecipe(current.recipe) ? [flowStepId(current), 'output']
+    : current.recipe === IMAGE_GENERATE_RECIPE ? ['generate', 'output', 'selection'] : ['edit', 'output', 'comparison', 'selection'];
+  if (!keys(patch, allowed, [])) throw new TypeError('未知流程更新字段');
+  const record = { ...current, ...patch, revision: current.revision + 1, updatedAt: new Date().toISOString() };
+  validate(record, current.id);
+  atomicWritePrivate(recordFile(root, record.id), JSON.stringify(record, null, 2) + '\n');
+  return copy(record);
+}
+
+export function listFlowRuns(root) {
+  inspectFlowRoot(root);
+  const records = [];
+  for (const name of fs.readdirSync(directory(root, 'runs'))) {
+    if (/^run_[a-f0-9]{24}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name)) continue; // 保留未发布的原子写现场。
+    if (!/^run_[a-f0-9]{24}\.json$/.test(name)) flowFail('IRIS_FLOW_RECORD_INVALID', '流程目录包含未知记录，停止盘点');
+    records.push(readFlowRun(root, name.slice(0, -5)));
+  }
+  return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+/** 管理入口不能忽略损坏/未知的流程根，从而丢掉引用。普通 Core 根保持零写。 */
+export function flowReferences(root) {
+  try { fs.lstatSync(path.join(root, 'flow-store')); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return listFlowRuns(root).map(run => ({ run, taskIds: [flowStep(run).taskId],
+    artifactIds: [...new Set([run.source?.artifactId, run.compare?.artifactId, run.output?.artifactId, run.selection?.artifactId].filter(Boolean))] }));
+}

package/lib/generation-input.js

@@ -3,9 +3,10 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { normalizeMusicOptions } from './music-options.js';
+import { normalizeComfyParameters } from './comfyui-workflow.js';
 
 const FIELDS = Object.freeze({
-  image: ['prompt', 'size', 'n', 'source_artifact_id'],
+  image: ['prompt', 'size', 'n', 'source_artifact_id', 'workflow_parameters'],
   video: ['prompt', 'size', 'duration', 'img_data_url', 'first_frame_path', 'audio_path', 'resolution'],
   tts: ['text', 'voice'],
   music: ['prompt', 'timeout_ms', 'retry_502', 'retry_delay_ms'],
@@ -86,6 +87,14 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
     const n = input.n === undefined ? 1 : Number(input.n);
     if (!Number.isSafeInteger(n) || n < 1 || n > 4) fail('n 必须为 1–4 的整数');
     providerInput.n = n;
+    if (input.workflow_parameters !== undefined) {
+      if (!modelRef || sourceArtifactId || n !== 1) fail('工作流参数需要明确 model_ref、n=1 且不带来源图片');
+      try { providerInput.workflow_parameters = Object.freeze(normalizeComfyParameters(input.workflow_parameters)); }
+      catch (error) { fail(error.message); }
+      if (Buffer.byteLength(JSON.stringify({ model_ref: modelRef, ...providerInput }, null, 2)) > 96 * 1024) {
+        fail('参数化流程输入最多 96 KiB；请缩短提示词或参数值');
+      }
+    }
   }
   if (capability === 'video') {
     if (input.duration !== undefined) {

package/lib/headless-vision.js

@@ -70,10 +70,10 @@ function completionResult(completion, routes) {
   return { ...result, ...selectedModel(completion, routes) };
 }
 
-async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) {
-  const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref);
-  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit, onModelAvailability }),
-    model: route.modelRef, selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) }));
+async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability, registry }) {
+  const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref, registry);
+  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit, onModelAvailability, registry }),
+    model: route.modelRef, selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider, registry) }));
   const audio = await waitForModelWork(() => extractAudioTrack({ inputPath: input.video_path, signal: operation.signal }), operation.signal);
   const abortRuntime = () => { void runtime.dispose().catch(() => {}); };
   operation.signal.addEventListener('abort', abortRuntime, { once: true });
@@ -87,7 +87,7 @@ async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit
       providerInput: { audioUrl: prepared.url } }), operation.signal, 'invoke', 'unknown');
     task = submitted.task;
     if (task.acceptance === 'accepted' && task.outcome === 'none') {
-      const adapter = createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task), { onRateLimit,
+      const adapter = createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task, registry), { onRateLimit, registry,
         modelId: routes.find(route => route.modelRef === task.modelRef)?.model });
       while (task.outcome === 'none') {
         task = await waitForModelWork(() => runner.observe(task.id, adapter), operation.signal, 'read', 'responded');
@@ -111,7 +111,7 @@ async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit
   }
 }
 
-export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit, onModelAvailability }) {
+export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit, onModelAvailability, registry }) {
   normalizeVisionInput(command, input);
   if (modelRef && !/^[^:]+::.+$/.test(modelRef)) invalid('--model-ref 必须是 providerId::modelId');
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > VISION_BUDGET.timeoutMs) invalid('--timeout-ms 必须是 1–120000 的整数');
@@ -140,7 +140,7 @@ export async function executeVisionCommand({ command, input, catalog, modelRef =
       }
       let transcript = input.transcribe_text || '', transcription = { status: transcript.trim() ? 'provided' : 'disabled' };
       if (input.transcribe) {
-        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) : { report: { status: 'no_audio' }, text: '' };
+        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability, registry }) : { report: { status: 'no_audio' }, text: '' };
         transcript = asr.text; transcription = asr.report;
       }
       const completion = await summarizeMedia({ ports, frames, question: input.question, transcript, operation, budget });

package/lib/image-edit-input.js

@@ -10,7 +10,7 @@ function invalid(message) {
 }
 
 export function imageEditCandidates(candidates) {
-  const supported = candidate => supportsImageEdit(candidate.adapter.protocol, candidate.providerModel);
+  const supported = candidate => candidate.supportsImageEdit ?? supportsImageEdit(candidate.adapter.protocol, candidate.providerModel);
   if (candidates.some(candidate => candidate.selectionReason === 'explicit'
       && !supported(candidate))) {
     throw invalid('指定模型的图片协议不支持此类改图，请选择聊天生图模型或 DashScope Qwen 原生改图模型');