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

package/lib/web/creation.js

@@ -0,0 +1,355 @@
+// Finite user actions; reopening a Run never invokes continue.
+import { renderWorkflowParameters, inspectionMessage } from './comfyui.js';
+import { CREATIONS, IMPORTS } from './media-client.js';
+
+const $ = selector => document.querySelector(selector);
+const ACTIVE = new Set(['queued', 'running']);
+const labels = { not_started: '开始改图', running: '查看原任务', delivery_failed: '恢复原结果', needs_comparison: '完成比较', needs_result: '接回结果' };
+export function createCreationPanel({ openRun, refreshHistory, showDraft, describe, recover, renderOperation }) {
+  let client, media, session, view = null, draft = {}, models = [], epoch = 0, intent = 0;
+  let busy = false, stopping = false, loading = false, visible = true, job = null, activeOperation = null, timer, watchTicket = 0;
+  let preview, retryAction = null, recoveryAfterLoad = null;
+  let comfyForm = null, comfyKey = '', inspection = null;
+  const cap = name => Boolean(session?.operations.includes(name));
+  const mode = () => view ? ({ 'image-edit/v0': 'edit', 'image-generate/v0': 'generate', 'speech/v0': 'tts', 'transcribe/v0': 'transcribe' })[view.recipe] : draft.mode || 'edit';
+  const generating = () => mode() === 'generate';
+  const audio = () => ['tts', 'transcribe'].includes(mode());
+  const createCapabilities = { generate: 'generations.create', edit: 'runs.create', tts: 'speeches.create', transcribe: 'transcriptions.create' };
+  const createCapability = () => createCapabilities[mode()];
+  const candidates = () => models.filter(model => audio() ? model.capability === mode() : !model.capability && (generating() || model.supportsImageEdit));
+  const valid = at => at === epoch && Boolean(client);
+  const validJob = task => valid(task.epoch) && task.intent === intent && visible && job === task;
+  function feedback(text = '', error = false) {
+    $('#creation-feedback').hidden = !text; $('#creation-feedback').textContent = text;
+    $('#creation-feedback').classList.toggle('error', error);
+  }
+  function releasePreview() {
+    $('#audio-input-preview').pause(); $('#audio-input-preview').removeAttribute('src'); $('#audio-input-preview').load(); $('#audio-input-preview').hidden = true;
+    if (preview) URL.revokeObjectURL(preview); preview = null;
+  }
+  function stopWatch() { clearTimeout(timer); watchTicket++; }
+  const selectedComfy = () => !view && generating() ? models.find(model => model.modelRef === $('#model').value && model.comfyWorkflow)?.comfyWorkflow : null;
+  function invalidateInspection() {
+    inspection?.controller.abort(); inspection = null;
+    $('#comfy-creation-note').textContent = '尚未检查；生成前会核对实际参数，不会自动生成。';
+  }
+  function renderComfy(force = false, values = {}, checked = []) {
+    const workflow = selectedComfy(), key = workflow ? $('#model').value + ':' + workflow.sha256 : '';
+    if (!force && key === comfyKey) return;
+    const preserveOpen = key === comfyKey;
+    const updated = comfyKey && key && comfyKey !== key;
+    invalidateInspection(); comfyKey = key; comfyForm = null;
+    $('#comfy-creation').hidden = !workflow;
+    if (!workflow) { $('#comfy-creation-fields').replaceChildren(); return; }
+    const parameters = workflow.parameters || [];
+    $('#comfy-creation-summary').textContent = parameters.length + ' 个开放参数 · 其余输入沿用工作流';
+    comfyForm = renderWorkflowParameters($('#comfy-creation-fields'), parameters, { values, checked, preserveOpen, onChange() {
+      invalidateInspection(); try { comfyForm.read(); } catch (error) { $('#comfy-creation-note').textContent = error.message; } controls();
+    } });
+    $('#comfy-creation-check').hidden = !session?.providerManagement;
+    if (!workflow.sizeNode) $('#edit-size').value = '';
+    if (updated) $('#comfy-creation-note').textContent = '已切换工作流，参数已按当前模板重新载入，请核对。';
+  }
+  async function checkComfy() {
+    if (!client || busy || inspection || !selectedComfy() || !session.providerManagement) return;
+    let values; try { values = comfyForm.read(); } catch (error) { feedback(error.message, true); return; }
+    const job = { controller: new AbortController(), key: comfyKey, client, modelRef: $('#model').value };
+    const workflow = selectedComfy(); inspection = job; controls(); $('#comfy-creation-note').textContent = '正在检查参数…';
+    try {
+      const settings = await job.client.get('/api/v0/provider-management/settings', { signal: job.controller.signal });
+      if (inspection !== job) return;
+      const current = settings.providers.flatMap(provider => provider.models.map(model => ({ ref: encodeURIComponent(provider.id) + '::' + encodeURIComponent(model.id), workflow: model.comfyWorkflow }))).find(item => item.ref === job.modelRef);
+      if (current?.workflow?.sha256 !== workflow.sha256) throw new Error('工作流已变化，请重新读取模型后核对参数。');
+      const result = await job.client.postProvider('workflow-check', { expectedRevision: settings.revision, modelRef: job.modelRef,
+        ...(Object.keys(values).length ? { workflowParameters: values } : {}) }, { signal: job.controller.signal });
+      if (inspection !== job) return;
+      renderComfy(true, values, result.parameters);
+      $('#comfy-creation-note').textContent = inspectionMessage(result);
+    } catch (error) { if (inspection === job) $('#comfy-creation-note').textContent = describe(error); }
+    finally { if (inspection === job) inspection = null; controls(); }
+  }
+  function controls() {
+    const generate = generating(), currentMode = mode(), isAudio = audio(), transcribe = currentMode === 'transcribe';
+    $('#studio-title').textContent = currentMode === 'tts' ? '让文字，有声音。' : transcribe ? '让声音，成文字。' : '让想法，有画面。';
+    $('#studio-note').textContent = currentMode === 'tts' ? '写下要说的话，留下你的声音作品。' : transcribe ? '听见的内容，留成可以继续使用的文字。' : '保留喜欢的部分，试一点新的可能。';
+    const needsSource = ['edit', 'transcribe'].includes(currentMode);
+    const pending = media?.snapshot(), unresolved = pending?.actions.some(action => CREATIONS.includes(action.kind)
+      || view && action.runId === view.id);
+    $('#draft-fields').disabled = !client || busy || loading || Boolean(view) || !Object.values(createCapabilities).some(cap);
+    for (const button of document.querySelectorAll('[data-creation-mode]')) {
+      button.setAttribute('aria-pressed', String(button.dataset.creationMode === currentMode));
+      button.disabled = !cap(createCapabilities[button.dataset.creationMode]);
+      if (['tts', 'transcribe'].includes(button.dataset.creationMode)) button.hidden = !session?.audio;
+    }
+    $('#source-input').hidden = currentMode !== 'edit'; $('#audio-source-input').hidden = !transcribe;
+    $('#prompt-label').hidden = transcribe; $('#edit-prompt').hidden = transcribe; $('#edit-prompt').required = !transcribe;
+    $('#speech-options').hidden = currentMode !== 'tts'; $('#advanced-settings').hidden = isAudio;
+    $('#model-label').firstChild.textContent = currentMode === 'tts' ? '语音模型 ' : transcribe ? '转写模型 ' : '图片模型 ';
+    $('#prompt-label').textContent = currentMode === 'tts' ? '要朗读的文字' : generate ? '想画些什么？' : '想改些什么？';
+    $('#edit-prompt').maxLength = isAudio ? 20000 : 12000;
+    $('#edit-prompt').placeholder = currentMode === 'tts' ? '写下希望朗读的内容…' : generate ? '描述画面、人物、色彩与风格…' : '描述想保留的细节，以及想尝试的变化…';
+    const canCreate = cap(createCapability()) && cap('runs.continue') && (!needsSource || Boolean(draft.file || draft.artifactId)
+      && (draft.artifactId || cap(transcribe ? 'audio.create' : 'images.create')))
+      && Boolean($('#model').value) && (transcribe || Boolean($('#edit-prompt').value.trim()));
+    const canContinue = view && cap('runs.continue') && Object.hasOwn(labels, view.status);
+    const canRetry = retryAction && (IMPORTS.includes(retryAction.kind) ? cap(retryAction.kind === 'audio-import' ? 'audio.create' : 'images.create') && Boolean(draft.file)
+      : CREATIONS.includes(retryAction.kind) ? cap(createCapability()) && Boolean((!needsSource || draft.artifactId) && $('#model').value && (transcribe || $('#edit-prompt').value.trim()))
+        : cap(retryAction.kind === 'stop' ? 'operations.stop' : 'runs.continue'));
+    $('#start-edit').disabled = !client || busy || stopping || loading || pending?.blocked || unresolved && !retryAction
+      || Boolean(activeOperation && ACTIVE.has(activeOperation.state)) || Boolean(inspection) || comfyForm && !comfyForm.valid()
+      || !(retryAction ? canRetry : view ? canContinue : canCreate);
+    $('#start-edit').textContent = busy ? '正在处理…' : retryAction ? '按原 Key 接回' : view && view.status !== 'not_started'
+      ? labels[view.status] || '查看已有作品' : currentMode === 'tts' ? '合成语音' : transcribe ? '开始转写' : generate ? '开始生成' : '开始改图';
+    $('#locked-note').hidden = !view;
+    $('#reuse-selected').disabled = busy || loading || !cap('runs.create') || !view?.selection;
+    for (const kind of ['source', 'output']) {
+      $('#select-' + kind).disabled = busy || stopping || loading || !view?.[kind] || !cap('runs.select') || !['awaiting_selection', 'selected'].includes(view?.status);
+    }
+    $('#stop-operation').hidden = !cap('operations.stop') || !activeOperation || !ACTIVE.has(activeOperation.state);
+    $('#stop-operation').disabled = stopping; $('#stop-operation').textContent = stopping ? '正在停止…' : '停止等待';
+    $('#creation-help').textContent = !client ? '读取权限中…' : loading ? '当前流程尚未确认，读取完成前暂停操作。可重新读取或新建流程。'
+      : retryAction ? '使用原身份与原输入接回。明确执行仍可能产生供应商费用。'
+      : pending?.blocked ? '恢复记录需要先明确处理，暂不接收新动作。'
+        : !cap('runs.continue') ? isAudio ? '当前服务只读，可浏览和下载已保存的音频或文字。'
+          : cap('runs.select') ? '当前可选择已有图片。开始创作需要显式开启执行服务。' : '当前服务只读，可浏览图片流程和下载已选作品。'
+          : !view && !candidates().length ? isAudio ? '尚无此音频功能的可用候选。请在模型服务中配置并分配用途。' : '尚无可用图片候选。可在供应商页配置模型。'
+            : view?.status === 'needs_attention' ? '先核对原任务；受理未知时请避免重复生成。'
+              : '明确执行可能产生供应商费用。刷新不会自动生成。';
+    $('#creation-settings').dataset.fixed = String(Boolean(view));
+    $('#comfy-creation-check').disabled = Boolean(inspection) || busy || loading;
+    $('#comfy-creation-check').textContent = inspection ? '正在检查…' : '检查参数并读取选项';
+    const workflow = selectedComfy(); $('#edit-size').disabled = Boolean(workflow && !workflow.sizeNode);
+    $('#edit-size-note').textContent = workflow && !workflow.sizeNode ? '此工作流未绑定尺寸节点，沿用模板尺寸。' : '填写模型支持的尺寸；留空使用默认值。';
+  }
+  function fillModels(selected = '') {
+    const choices = candidates(), label = mode() === 'tts' ? '语音' : mode() === 'transcribe' ? '转写' : '图片';
+    $('#model').replaceChildren(new Option(choices.length ? '选择一个' + label + '模型' : '没有可用' + label + '候选', ''));
+    for (const model of choices) $('#model').append(new Option(model.displayName + ' · ' + model.modelRef, model.modelRef));
+    if (selected && !choices.some(model => model.modelRef === selected)) $('#model').append(new Option(selected + ' · 原流程模型', selected));
+    $('#model').value = selected;
+  }
+  function cancelChain() { intent++; stopWatch(); }
+  function beginDraft({ file, artifactId, label, modelRef = '', mode = file || artifactId ? 'edit' : cap('generations.create') ? 'generate' : 'edit' } = {}) {
+    cancelChain(); loading = false; recoveryAfterLoad = null; retryAction = null; activeOperation = null; view = null; draft = { file, artifactId, mode };
+    releasePreview(); if (file) preview = URL.createObjectURL(file);
+    $('#input-preview').hidden = !preview || mode === 'transcribe'; $('#input-preview').removeAttribute('src'); if (preview && mode !== 'transcribe') $('#input-preview').src = preview;
+    if (preview && mode === 'transcribe') { $('#audio-input-preview').src = preview; $('#audio-input-preview').hidden = false; }
+    $('#audio-file').value = ''; $('#speech-voice').value = ''; $('#audio-file-name').textContent = label || file?.name || (artifactId ? '已保存的原音频' : 'WAV / MP3 / OGG / FLAC，最大20 MiB。');
+    $('#file-name').textContent = label || file?.name || (artifactId ? '已选作品' : '选择一张图片');
+    $('#image-file').value = ''; $('#edit-prompt').value = ''; $('#edit-size').value = ''; fillModels(modelRef); renderComfy(true);
+    $('#input-summary').textContent = mode === 'tts' ? '让文字成为声音' : mode === 'transcribe' ? '把声音留成文字' : mode === 'generate' ? '从一句想法开始' : file || artifactId ? '填写你的修改要求' : '从一张图片开始';
+    $('#creation-settings').open = true; $('#advanced-settings').open = false; feedback();
+    showDraft(preview, mode); controls();
+  }
+  async function chooseFile(file) {
+    if (!client || busy || loading || view || !file) return;
+    if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type) || file.size > (session.limits?.uploadBytes || 20 * 1024 * 1024)) {
+      feedback('请选择不超过 20 MiB 的静态 PNG、JPEG 或 WebP 图片。', true); return;
+    }
+    const originalRetry = retryAction, modelRef = $('#model').value, prompt = $('#edit-prompt').value, size = $('#edit-size').value;
+    beginDraft({ file, modelRef }); $('#edit-prompt').value = prompt; $('#edit-size').value = size;
+    retryAction = originalRetry; controls();
+  }
+  function chooseAudio(file) {
+    if (!client || busy || loading || view || !file) return;
+    const types = { 'audio/x-wav': 'audio/wav', 'audio/mp3': 'audio/mpeg', 'audio/x-flac': 'audio/flac', 'application/ogg': 'audio/ogg' };
+    const byExtension = { wav: 'audio/wav', mp3: 'audio/mpeg', ogg: 'audio/ogg', flac: 'audio/flac' };
+    const type = types[file.type] || file.type || byExtension[file.name?.split('.').at(-1).toLowerCase()];
+    if (!['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac'].includes(type) || file.size > 20 * 1024 * 1024) { feedback('请选择最多20 MiB的WAV、MP3、OGG或FLAC音频。', true); return; }
+    const original = retryAction;
+    beginDraft({ mode: 'transcribe', file: type === file.type ? file : new Blob([file], { type }), label: file.name, modelRef: $('#model').value });
+    retryAction = original; controls();
+  }
+  async function finishOperation(operation, at, ticket) {
+    if (!valid(at) || ticket !== watchTicket || !visible) return;
+    activeOperation = operation; renderOperation(operation);
+    if (ACTIVE.has(operation.state)) return;
+    stopWatch(); await recover();
+    if (!valid(at) || !visible || view?.id !== operation.runId) return;
+    await openRun(operation.runId, { fromAction: true });
+    if (!valid(at)) return;
+    if (view?.id === operation.runId && audio() && operation.state === 'succeeded') feedback();
+    await refreshHistory(); controls();
+  }
+  function watch(operation) {
+    stopWatch(); activeOperation = operation; renderOperation(operation); controls();
+    if (!ACTIVE.has(operation.state)) { void finishOperation(operation, epoch, watchTicket).catch(error => feedback(describe(error), true)); return; }
+    const at = epoch, ticket = watchTicket; let reads = 0;
+    const poll = async () => {
+      if (!valid(at) || ticket !== watchTicket || !visible || document.hidden || view?.id !== operation.runId) return;
+      try {
+        const result = await client.getOperation(operation.id);
+        if (!valid(at) || ticket !== watchTicket) return;
+        await finishOperation(result.operation, at, ticket);
+        if (valid(at) && ticket === watchTicket && ACTIVE.has(result.operation.state)) {
+          if (++reads < 40) timer = setTimeout(poll, 1500);
+          else feedback('自动读取已暂停。可点“刷新”核对原操作，不会重新提交。');
+        }
+      } catch (error) { if (valid(at) && ticket === watchTicket) { stopWatch(); feedback('进度读取已暂停。' + describe(error), true); } }
+    };
+    if (visible && !document.hidden) timer = setTimeout(poll, 350);
+  }
+  async function execute() {
+    if ($('#start-edit').disabled) return;
+    let parameters;
+    try { if (selectedComfy()) parameters = comfyForm.read(); } catch (error) { feedback(error.message, true); return; }
+    const task = { epoch, intent, runId: view?.id }; job = task; busy = true; controls();
+    const generate = generating(), currentMode = mode(), isAudio = audio(), transcribe = currentMode === 'transcribe';
+    const input = isAudio ? { modelRef: $('#model').value, ...(transcribe ? { sourceArtifactId: draft.artifactId }
+      : { text: $('#edit-prompt').value, ...($('#speech-voice').value.trim() ? { voice: $('#speech-voice').value.trim() } : {}) }) }
+      : { ...(!generate ? { sourceArtifactId: draft.artifactId } : {}), modelRef: $('#model').value, prompt: $('#edit-prompt').value,
+      ...($('#edit-size').value.trim() ? { size: $('#edit-size').value.trim() } : {}),
+      ...(parameters && Object.keys(parameters).length ? { workflowParameters: parameters } : {}) };
+    const file = draft.file, original = retryAction;
+    try {
+      if (original) {
+        const value = await media.retry(original.id, IMPORTS.includes(original.kind) ? file : CREATIONS.includes(original.kind) ? input : undefined);
+        if (!validJob(task)) return;
+        retryAction = null;
+        if (IMPORTS.includes(original.kind)) { draft.artifactId = value.artifact.artifactId; feedback('原素材已接回。再次明确开始时才会创建并执行。'); }
+        else if (CREATIONS.includes(original.kind)) { await openRun(value.flow.id, { fromAction: true }); feedback('原流程已接回，尚未自动开始。'); }
+        else { watch(value.operation); feedback('已接回原操作。'); }
+        await recover(); return;
+      }
+      if (!view) {
+        if ((transcribe || currentMode === 'edit') && !input.sourceArtifactId) {
+          feedback('正在保存素材…'); const imported = await media[transcribe ? 'uploadAudio' : 'uploadImage'](file);
+          if (!validJob(task)) return; draft.artifactId = input.sourceArtifactId = imported.artifact.artifactId;
+        }
+        feedback('正在建立流程…'); const created = await media[({ generate: 'createGeneration', edit: 'createRun', tts: 'createSpeech', transcribe: 'createTranscription' })[currentMode]](input);
+        if (!validJob(task)) return; task.runId = created.flow.id;
+        await openRun(created.flow.id, { fromAction: true });
+        if (!validJob(task)) return;
+      }
+      feedback('正在提交本次操作…');
+      const accepted = await media.continueRun(view.id, view.revision);
+      if (!validJob(task)) return;
+      feedback('已接收。正在读取本地进度…'); watch(accepted.operation); await refreshHistory();
+    } catch (error) {
+      if (valid(task.epoch) && task.intent === intent) {
+        feedback('本次动作未确认完成，请先核对原结果。' + describe(error), true);
+        await recover();
+      }
+    } finally { if (job === task) { job = null; busy = false; if (valid(task.epoch)) controls(); } }
+  }
+  async function select(kind) {
+    if (!view || $('#select-' + kind).disabled) return;
+    const at = epoch, id = view.id, artifactId = view[kind].artifactId, revision = view.revision;
+    busy = true; controls(); $('#selection-feedback').textContent = '正在保存选择…';
+    try {
+      await media.selectRun(id, artifactId, revision);
+      if (!valid(at) || view?.id !== id || !visible) return;
+      await openRun(id, { fromAction: true });
+      if (!valid(at) || view?.id !== id) return;
+      $('#selection-feedback').textContent = '选择已保存，可以下载原始图片。'; await refreshHistory();
+    } catch (error) {
+      if (!valid(at) || view?.id !== id) return;
+      await recover();
+      if (!valid(at) || !visible || view?.id !== id) return;
+      await openRun(id, { fromAction: true });
+      $('#selection-feedback').textContent = '已核对当前选择；请确认后再决定。' + describe(error);
+    } finally { if (valid(at)) { busy = false; controls(); } }
+  }
+  async function stop() {
+    if (!activeOperation || stopping) return;
+    const at = epoch, operation = activeOperation; stopping = true; controls();
+    try {
+      const result = await media.stopOperation(operation.id);
+      if (!valid(at)) return; activeOperation = result.operation;
+      stopWatch(); await recover();
+      if (view?.id === operation.runId && visible) { await openRun(operation.runId, { fromAction: true }); renderOperation(result.operation); }
+      feedback('已停止本地等待；远端取消未请求，不代表退款或未计费。');
+    } catch (error) { if (valid(at)) { feedback('停止结果待核对。' + describe(error), true); await recover(); } }
+    finally { if (valid(at)) { stopping = false; controls(); } }
+  }
+  async function reuse() {
+    if (!view?.selection || $('#reuse-selected').disabled) return;
+    const at = epoch, original = view, marker = intent; busy = true; controls();
+    try {
+      const file = await client.get('/api/v0/artifacts/' + original.selection.artifactId + '/content', { binary: true });
+      if (valid(at) && intent === marker && visible) beginDraft({ file, artifactId: original.selection.artifactId, modelRef: original.input.modelRef, label: '已选作品 · 新流程' });
+    } catch (error) { if (valid(at)) feedback(describe(error), true); }
+    finally { if (valid(at)) { busy = false; controls(); } }
+  }
+  function recovered(results) {
+    if (loading) { recoveryAfterLoad = results; controls(); return; }
+    if (!view) { controls(); return; }
+    const active = results.find(item => item.status === 'active' && item.result.operation.runId === view.id);
+    if (active) watch(active.result.operation); else controls();
+  }
+  $('#edit-form').addEventListener('submit', event => { event.preventDefault(); void execute(); });
+  for (const button of document.querySelectorAll('[data-creation-mode]')) button.addEventListener('click', () => {
+    if (busy || loading || view || button.disabled || draft.mode === button.dataset.creationMode) return;
+    const keepImageInput = !audio() && ['edit', 'generate'].includes(button.dataset.creationMode);
+    const prompt = $('#edit-prompt').value, size = $('#edit-size').value;
+    beginDraft({ mode: button.dataset.creationMode });
+    if (keepImageInput) { $('#edit-prompt').value = prompt; $('#edit-size').value = size; } controls();
+  });
+  $('#image-file').addEventListener('change', event => { void chooseFile(event.target.files[0]); event.target.value = ''; });
+  $('#model').addEventListener('change', () => { renderComfy(); controls(); });
+  for (const id of ['model', 'edit-prompt', 'edit-size', 'speech-voice']) $('#' + id).addEventListener('input', () => { if (id === 'model') renderComfy(); else invalidateInspection(); controls(); });
+  $('#audio-file').addEventListener('change', event => { const file = event.target.files[0]; event.target.value = ''; chooseAudio(file); });
+  $('#comfy-creation-check').addEventListener('click', () => { void checkComfy(); });
+  $('#image-drop').addEventListener('dragover', event => { event.preventDefault(); if (!view && !busy) $('#image-drop').classList.add('dragging'); });
+  $('#image-drop').addEventListener('dragleave', () => $('#image-drop').classList.remove('dragging'));
+  $('#image-drop').addEventListener('drop', event => { event.preventDefault(); $('#image-drop').classList.remove('dragging'); void chooseFile(event.dataTransfer.files[0]); });
+  $('#select-source').addEventListener('click', () => { void select('source'); });
+  $('#select-output').addEventListener('click', () => { void select('output'); });
+  $('#stop-operation').addEventListener('click', () => { void stop(); });
+  $('#reuse-selected').addEventListener('click', () => { void reuse(); });
+  document.addEventListener('visibilitychange', () => { if (document.hidden) stopWatch(); });
+  matchMedia('(max-width:640px)').addEventListener('change', event => { if (view) $('#creation-settings').open = !event.matches; });
+  return Object.freeze({
+    connect(http, coordinator, info) { client = http; media = coordinator; session = info; visible = true; controls(); },
+    setModels(values) { const selected = $('#model').value; models = values; fillModels(selected); renderComfy(); controls(); },
+    beginDraft,
+    async prepareVerification({ capability, modelRef }) {
+      if (!client || busy || !cap('runs.continue')) return;
+      const at = epoch, next = capability === 'tts' ? 'tts' : capability === 'transcribe' ? 'transcribe' : cap('generations.create') ? 'generate' : 'edit';
+      if (!cap(createCapabilities[next])) { feedback('当前工作区没有此验证流程，请使用已接入的 CLI / DSH 功能。', true); return; }
+      let file;
+      if (next === 'edit') {
+        const canvas = document.createElement('canvas'); canvas.width = canvas.height = 256;
+        const context = canvas.getContext('2d'); context.fillStyle = '#fff'; context.fillRect(0, 0, 256, 256);
+        context.fillStyle = '#e03131'; context.beginPath(); context.arc(128, 128, 64, 0, Math.PI * 2); context.fill();
+        const blob = await new Promise(resolve => canvas.toBlob(resolve, 'image/png'));
+        if (!blob) { feedback('无法准备测试图片，请手动选择素材。', true); return; }
+        file = new File([blob], 'iris-test-circle.png', { type: 'image/png' });
+      }
+      if (!valid(at)) return;
+      beginDraft({ mode: next, modelRef, file });
+      $('#edit-prompt').value = next === 'tts' ? '你好' : next === 'edit' ? '将红色圆形改为蓝色，保留白色背景。' : next === 'generate' ? 'A simple red circle on a plain white background.' : '';
+      feedback(next === 'transcribe' ? '验证草稿已准备。请选择实际音频，确认后点击开始转写，可能产生费用。'
+        : '验证草稿已准备。请核对模型及参数，再明确点击生成；可能产生供应商费用。'); controls();
+    },
+    loading() { loading = true; recoveryAfterLoad = null; stopWatch(); invalidateInspection(); controls(); },
+    view(value, { sameRun = false } = {}) {
+      const changed = view?.id !== value.id;
+      loading = false; view = value; retryAction = null;
+      if (changed) { activeOperation = null; stopWatch(); }
+      if (!sameRun) { fillModels(value.input.modelRef); $('#edit-prompt').value = value.input.text ?? value.input.prompt ?? ''; $('#edit-size').value = value.input.size || ''; $('#speech-voice').value = value.input.voice || '';
+        $('#input-summary').textContent = value.input.modelRef; $('#file-name').textContent = '流程原图';
+        if (matchMedia('(max-width:640px)').matches) $('#creation-settings').open = false; }
+      renderComfy(); controls();
+      if (recoveryAfterLoad) { const results = recoveryAfterLoad; recoveryAfterLoad = null; recovered(results); }
+    },
+    source(url) { $('#input-preview').src = url; $('#input-preview').hidden = false; },
+    cancelChain,
+    show(value) { const returning = value && !visible; visible = value; if (!value) cancelChain(); else if (returning && client) void recover(); },
+    recovered,
+    retry(action) {
+      if (busy) return;
+      if (['continue', 'stop'].includes(action.kind)) { retryAction = action; feedback('将使用原身份接回此操作，请确认后点击。'); controls(); return; }
+      beginDraft({ artifactId: ['flow-create', 'transcription-create'].includes(action.kind) ? action.artifactId : undefined,
+        mode: ({ 'generation-create': 'generate', 'audio-import': 'transcribe', 'transcription-create': 'transcribe', 'speech-create': 'tts' })[action.kind] || 'edit' });
+      retryAction = action; feedback(IMPORTS.includes(action.kind) ? '请重新提供原素材字节，再按原 Key 接回。' : '请重新提供原模型、要求与参数，再按原 Key 接回。'); controls();
+    },
+    async refresh() { if (activeOperation && ACTIVE.has(activeOperation.state)) watch(activeOperation); controls(); },
+    disconnect() {
+      epoch++; intent++; stopWatch(); client = media = session = null; view = null; draft = {}; models = []; busy = stopping = loading = false; job = activeOperation = retryAction = recoveryAfterLoad = null;
+      releasePreview(); $('#input-preview').removeAttribute('src'); $('#input-preview').hidden = true; $('#image-file').value = '';
+      $('#audio-file').value = ''; $('#audio-file-name').textContent = 'WAV / MP3 / OGG / FLAC，最大20 MiB。'; $('#speech-voice').value = '';
+      $('#edit-prompt').value = ''; $('#edit-size').value = ''; fillModels(); renderComfy(true); feedback(); controls();
+    }
+  });
+}

package/lib/web/flow-view.js

@@ -0,0 +1,33 @@
+// Consume the HTTP DTO, not private Core records or the prototype's in-memory transport.
+export function presentReadOnlyFlow(view) {
+  if (view.contractVersion !== 0 || !['image-edit/v0', 'image-generate/v0', 'speech/v0', 'transcribe/v0'].includes(view.recipe)) throw new TypeError('不支持的流程版本');
+  switch (view.status) {
+    case 'not_started': return { title: '已保存，尚未开始', message: '输入已保存。当前页面只读，不会提交生成。', tone: 'neutral' };
+    case 'running': return { title: '原任务进行中', message: '这是本地保存的进展。页面刷新不会查询模型服务；可通过 CLI 查看原任务。', tone: 'working' };
+    case 'needs_attention': return { title: '需要核对原任务', message: view.task?.acceptance === 'unknown' || view.task?.outcome === 'unknown'
+      ? '尚不能确认原请求的结果，可能已经计费。请核对原任务，避免重复生成。'
+      : '原任务已失败或取消。现有记录仍然保留。', tone: 'warning' };
+    case 'delivery_failed': return { title: '原结果待保存', message: '原任务已成功，本地保存尚未完成。请通过 CLI 恢复原结果。', tone: 'warning' };
+    case 'needs_comparison': return { title: '结果已保存', message: '本地比较尚未完成。可查看现有图片，通过 CLI 继续流程。', tone: 'neutral' };
+    case 'needs_result': return { title: '结果已保存', message: '原任务已交付，流程结果仍待接回。请通过 CLI 继续原流程。', tone: 'neutral' };
+    case 'ready': return { title: view.recipe === 'speech/v0' ? '语音已就绪' : '转写已完成',
+      message: view.recipe === 'speech/v0' ? '语音已保存，可以试听或下载音频。' : '转写文字已保存，可以查看或下载文本。', tone: 'success' };
+    case 'awaiting_selection': return { title: '图片已就绪', message: '图片已保存。请通过 CLI 明确选择作品，再回来下载。', tone: 'success' };
+    case 'selected': return { title: view.source && view.selection?.artifactId === view.source.artifactId ? '已选择原图' : '已选择结果',
+      message: '选择已记录，可以下载原始图片。', tone: 'success' };
+    default: throw new TypeError('不支持的流程状态，请核对服务版本');
+  }
+}
+
+export function presentFlow(view, operations) {
+  const base = presentReadOnlyFlow(view), execute = operations.includes('runs.continue');
+  if (execute && view.status === 'not_started') return { ...base, message: '输入已固定。明确开始后才会调用模型，可能产生费用。' };
+  if (execute && view.status === 'running') return { ...base, message: '原任务仍在进行。点击“查看原任务”读取一次进展；刷新只读本地记录。' };
+  if (execute && view.status === 'delivery_failed') return { ...base, message: ['speech/v0', 'transcribe/v0'].includes(view.recipe)
+    ? '原任务已成功。点击“恢复原结果”接回交付，不重复提交。' : '生成已经成功。点击“恢复原结果”接回交付，不新建生成。' };
+  if (execute && view.status === 'needs_comparison') return { ...base, message: '图片已保存。点击“完成比较”执行本地比较，不产生生成请求。' };
+  if (execute && view.status === 'needs_result') return { ...base, message: '原任务已交付。点击“接回结果”保存流程引用，不产生生成请求。' };
+  if (operations.includes('runs.select') && view.status === 'awaiting_selection') return { ...base, message: view.source
+    ? '比较原图与结果，选择喜欢的版本，再下载原始图片。' : '查看生成结果，明确选择后下载原始图片。' };
+  return base;
+}

package/lib/web/gallery.js

@@ -0,0 +1,132 @@
+const $ = selector => document.querySelector(selector);
+const element = (tag, text, className) => { const node = document.createElement(tag); node.textContent = text; if (className) node.className = className; return node; };
+
+/** Read-only gallery. Preview bytes are fetched only while a card is visible. */
+export function createGallery({ openRun, describe }) {
+  let client, visible = false, filter = 'all', kind = 'image', audioEnabled = false, cursor = null, busy = false, ticket = 0, controller, observer, activeAudio;
+  const previews = new Map();
+  function clearAudio() {
+    if (!activeAudio) return;
+    activeAudio.controller.abort(); activeAudio.player.pause(); activeAudio.player.removeAttribute('src'); activeAudio.player.load(); activeAudio.player.hidden = true;
+    if (activeAudio.url) URL.revokeObjectURL(activeAudio.url);
+    activeAudio.button.disabled = false; activeAudio.button.hidden = false; activeAudio = null;
+  }
+  function clear() {
+    controller?.abort(); observer?.disconnect(); observer = null;
+    clearAudio();
+    for (const item of previews.values()) { item.controller.abort(); if (item.url) URL.revokeObjectURL(item.url); }
+    previews.clear();
+  }
+  function observe() {
+    observer?.disconnect();
+    observer = new IntersectionObserver(entries => {
+      for (const entry of entries) {
+        const item = previews.get(entry.target); if (!item) continue;
+        if (!entry.isIntersecting) continue;
+        if (item.url || item.loading) continue;
+        const at = ticket, http = client, job = item.controller = new AbortController(); item.loading = true;
+        void http.get('/api/v0/artifacts/' + item.artifactId + '/content', { binary: true, signal: job.signal }).then(async blob => {
+          if (!visible || at !== ticket || job.signal.aborted) return;
+          item.url = URL.createObjectURL(blob); item.image.src = item.url; await item.image.decode();
+          if (!visible || at !== ticket || job.signal.aborted) return;
+          item.image.hidden = false; item.marker.hidden = true;
+        }).catch(error => {
+          if (!job.signal.aborted && at === ticket) item.marker.textContent = '预览暂不可用';
+        }).finally(() => { if (item.controller === job) item.loading = false; });
+      }
+    });
+    for (const card of previews.keys()) observer.observe(card);
+  }
+  function card(run) {
+    if (['speech/v0', 'transcribe/v0'].includes(run.recipe)) return audioCard(run);
+    const button = element('button', '', 'gallery-card'); button.type = 'button'; button.dataset.galleryRun = run.id;
+    button.setAttribute('aria-label', '打开图片流程 · ' + (run.selection ? '已选择' : '未选择'));
+    const cover = element('div', '', 'gallery-cover'), image = document.createElement('img'), marker = element('span', '读取预览…');
+    const preview = run.selection || run.output || run.source;
+    image.alt = run.selection ? '此流程已选作品' : run.source ? '此流程原图或结果' : '此流程生成结果'; image.hidden = true; cover.append(image, marker);
+    const info = element('div', '', 'gallery-info');
+    info.append(element('strong', run.selection ? '已选择 · 图片流程' : '未选择 · 图片流程'),
+      element('p', new Date(run.updatedAt).toLocaleString('zh-CN', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }) + ' · ' + run.modelRef));
+    button.append(cover, info); button.addEventListener('click', () => openRun(run.id));
+    if (preview) previews.set(button, { artifactId: preview.artifactId, image, marker, controller: new AbortController(), url: null, loading: false });
+    else marker.textContent = '尚未生成';
+    return button;
+  }
+  function audioCard(run) {
+    const speech = run.recipe === 'speech/v0', article = element('article', '', 'gallery-card gallery-audio'); article.dataset.galleryRun = run.id;
+    const cover = element('div', '', 'gallery-audio-cover');
+    cover.append(element('span', speech ? '♪' : '≋', 'gallery-audio-icon'), element('span', speech ? 'VOICE' : 'TRANSCRIPT', 'eyebrow'));
+    const info = element('div', '', 'gallery-info');
+    info.append(element('strong', (run.output ? '已保存 · ' : '待完成 · ') + (speech ? '语音合成' : '音频转写')),
+      element('p', new Date(run.updatedAt).toLocaleString('zh-CN', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }) + ' · ' + run.modelRef));
+    const actions = element('div', '', 'export-actions'), open = element('button', speech ? '查看作品' : '查看文字', 'quiet'); open.type = 'button';
+    open.addEventListener('click', () => openRun(run.id)); actions.append(open);
+    const artifact = speech ? run.output : run.source;
+    if (artifact) {
+      const play = element('button', speech ? '载入试听' : '载入原音频', 'quiet'); play.type = 'button'; play.dataset.galleryPlay = run.id; actions.append(play);
+      const player = document.createElement('audio'); player.controls = true; player.preload = 'metadata'; player.hidden = true;
+      const note = element('p', '', 'field-note');
+      play.addEventListener('click', async () => {
+        clearAudio();
+        const at = ticket, http = client, job = { controller: new AbortController(), player, button: play, url: null };
+        activeAudio = job; play.disabled = true; note.textContent = '读取音频…';
+        try {
+          const blob = await http.get('/api/v0/artifacts/' + artifact.artifactId + '/audio', { binary: true, signal: job.controller.signal });
+          if (!visible || at !== ticket || job !== activeAudio) return;
+          job.url = URL.createObjectURL(blob); player.src = job.url; player.hidden = false; play.hidden = true; note.textContent = '点击播放器试听。';
+        } catch (error) { if (job === activeAudio && !job.controller.signal.aborted) note.textContent = describe(error); }
+        finally { if (job === activeAudio) play.disabled = false; }
+      });
+      info.append(actions, player, note);
+    } else info.append(actions);
+    article.append(cover, info); return article;
+  }
+  function counts(value) {
+    for (const button of document.querySelectorAll('#gallery-filters button')) {
+      button.setAttribute('aria-pressed', String(button.dataset.filter === filter));
+      button.querySelector('span').textContent = String(value[button.dataset.filter]);
+    }
+  }
+  async function load(more = false) {
+    if (!client || !visible || more && busy) return;
+    const at = ++ticket, http = client; busy = true;
+    if (!more) { clear(); $('#gallery-grid').replaceChildren(); }
+    else for (const item of previews.values()) { if (item.loading) { item.controller.abort(); item.loading = false; } }
+    controller = new AbortController(); const signal = controller.signal;
+    $('#gallery-grid').setAttribute('aria-busy', 'true'); $('#gallery-more').disabled = true;
+    $('#gallery-feedback').textContent = '正在读取作品…'; $('#gallery-empty').hidden = true;
+    try {
+      const value = await http.get('/api/v0/runs?' + new URLSearchParams({ limit: '20', selection: filter,
+        ...(audioEnabled ? { kind } : {}), ...(more && cursor ? { cursor } : {}) }), { signal });
+      if (at !== ticket || client !== http || !visible) return;
+      if (value.contractVersion !== 0 || !value.counts || !Array.isArray(value.runs)) throw new TypeError('不支持的作品列表');
+      cursor = value.nextCursor; counts(value.counts);
+      $('#gallery-grid').append(...value.runs.map(card)); observe();
+      $('#gallery-more').hidden = !cursor; $('#gallery-empty').hidden = value.total !== 0;
+      $('#gallery-feedback').textContent = value.total ? '共 ' + value.total + ' 个流程 · 点击作品接回创作' : '';
+    } catch (error) { if (at === ticket && !signal.aborted) $('#gallery-feedback').textContent = describe(error); }
+    finally { if (at === ticket) { busy = false; $('#gallery-grid').setAttribute('aria-busy', 'false'); $('#gallery-more').disabled = false; } }
+  }
+  for (const button of document.querySelectorAll('#gallery-filters button')) button.addEventListener('click', () => {
+    if (button.dataset.filter === filter) return;
+    filter = button.dataset.filter; cursor = null;
+    for (const item of document.querySelectorAll('#gallery-filters button')) item.setAttribute('aria-pressed', String(item === button));
+    void load();
+  });
+  for (const button of document.querySelectorAll('[data-gallery-kind]')) button.addEventListener('click', () => {
+    if (!audioEnabled || button.dataset.galleryKind === kind) return;
+    kind = button.dataset.galleryKind; filter = 'all'; cursor = null;
+    for (const item of document.querySelectorAll('[data-gallery-kind]')) item.setAttribute('aria-pressed', String(item === button));
+    $('#gallery-filters').hidden = kind !== 'image'; void load();
+  });
+  $('#gallery-refresh').addEventListener('click', () => { void load(); });
+  $('#gallery-more').addEventListener('click', () => { void load(true); });
+  return Object.freeze({
+    connect(http, session) { client = http; audioEnabled = session?.audio === true; $('#gallery-types').hidden = !audioEnabled; },
+    show(value) { if (visible === value) return; visible = value; if (value) void load(); else { ticket++; busy = false; clear(); $('#gallery-grid').replaceChildren(); } },
+    disconnect() { visible = false; client = null; ticket++; busy = false; cursor = null; filter = 'all'; kind = 'image'; audioEnabled = false; clear();
+      for (const item of document.querySelectorAll('[data-gallery-kind]')) item.setAttribute('aria-pressed', String(item.dataset.galleryKind === kind));
+      $('#gallery-types').hidden = true; $('#gallery-filters').hidden = false; $('#gallery-grid').replaceChildren(); counts({ all: 0, selected: 0, unselected: 0 }); $('#gallery-feedback').textContent = ''; },
+    refresh() { return load(); }
+  });
+}