@mokuyoaxis/dsh-iris 0.1.1 → 0.1.3

package/lib/actions.js

@@ -26,6 +26,8 @@ import { ffmpegAvailable, extractFrames, probeVideo } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
 import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
 import { inferMediaProtocol } from './provider-protocol.js';
+import { ProviderContractError, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { deriveUserState } from './task-semantics.js';
 
 const MEDIA_TYPES = {
   '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
@@ -66,7 +68,7 @@ function throwIfAborted(signal) {
  * 生成类 failover 只覆盖“上传/提交/同步生成”阶段。远端一旦受理即绑定该任务，
  * 不因后续轮询或结果下载失败重提，避免同一请求重复计费。
  */
-async function submitWithFailover(capability, label, signal, requestedModelRef, attempt) {
+function selectProviders(capability, label, requestedModelRef) {
   let providers = store.pickAllFor(capability);
   const parsedRef = models.parseModelRef(String(requestedModelRef || '').trim());
   if (parsedRef) {
@@ -75,25 +77,193 @@ async function submitWithFailover(capability, label, signal, requestedModelRef,
     if (!providers.length) throw new Error('iris: 指定的模型复合引用不可用或不具备' + label + '能力');
   }
   if (!providers.length) throw new Error('iris: 没有可用' + label + '供应商——先在 Iris 设置里添加、标注并分配模型');
-  const errors = [];
-  for (const provider of providers) {
-    throwIfAborted(signal);
+  return providers;
+}
+
+function imageRoute(provider, args) {
+  const protocol = provider.mediaProtocol || inferMediaProtocol(provider.baseUrl);
+  const parsed = models.parseModelRef(String(args.model || ''));
+  const model = args.model
+    ? (parsed?.modelId || String(args.model))
+    : (provider.imageModel || (protocol === 'openai-images' ? 'gpt-image-1' : 'wan2.2-t2i-flash'));
+  return { provider, protocol, model, modelRef: models.modelRef(provider.id, model) };
+}
+
+function imageSubmissionError(error) {
+  const status = Number(error && error.status) || undefined;
+  // 408/409/425/499 可能来自中间层或冲突恢复，不能证明请求未被受理。
+  const explicitRejection = Boolean(status && status >= 400 && status < 500 && ![408, 409, 425, 499].includes(status));
+  let category = 'provider';
+  if (error && (error.name === 'AbortError' || error.code === 'ABORT_ERR')) category = 'aborted';
+  else if (error && (error.category === 'network' || error instanceof TypeError)) category = 'network';
+  else if (status === 401 || status === 403) category = 'authentication';
+  else if (status === 429 && error && error.category === 'quota') category = 'quota';
+  else if (status === 429) category = 'rate_limit';
+  else if (status && status >= 400 && status < 500) category = 'invalid_request';
+  else if (!status) category = 'protocol';
+  return new ProviderContractError(String((error && error.message) || error || '提交失败'), {
+    stage: 'submit',
+    category,
+    acceptance: explicitRejection ? 'not_accepted' : 'unknown',
+    retryable: status === 429 || Boolean(status && status >= 500) || category === 'network',
+    ...(status ? { httpStatus: status } : {})
+  });
+}
+
+function taskActionError(taskId, message, details) {
+  const error = new Error('iris: ' + message + '（task: ' + taskId + '）');
+  error.taskId = taskId;
+  if (details) error.details = details;
+  return error;
+}
+
+async function deliverCompletedImage(taskId, value, signal) {
+  const names = [];
+  try {
+    tasks.beginDelivery(taskId);
+    if (value && value.kind === 'urls') {
+      for (const url of value.items || []) {
+        const name = taskId + '-' + names.length + '.' + adapters.extFromUrl(url, 'png');
+        await adapters.downloadTo(url, path.join(outputDir(), name), { signal });
+        names.push(name);
+      }
+    } else if (value && value.kind === 'openai') {
+      for (const item of value.items || []) {
+        const name = taskId + '-' + names.length + '.png';
+        const target = path.join(outputDir(), name);
+        if (item && item.b64) writePrivateFile(target, Buffer.from(item.b64, 'base64'));
+        else if (item && item.url) await adapters.downloadTo(item.url, target, { signal });
+        else throw new Error('同步图片结果缺少 b64 或 URL');
+        names.push(name);
+      }
+    } else {
+      throw new Error('未知同步图片结果结构');
+    }
+    if (!names.length) throw new Error('生成已成功，但没有可交付的图片');
+    for (const name of names) registerMedia(taskId, path.join(outputDir(), name));
+    tasks.completeDelivery(taskId, names);
+    return tasks.get(taskId);
+  } catch (error) {
+    let recorded;
     try {
-      return await attempt(provider);
-    } catch (err) {
-      if (signal && signal.aborted) throwIfAborted(signal);
-      const field = models.CAP_FIELD[capability];
-      errors.push({
-        providerId: provider.id,
-        modelRef: field && provider[field] ? models.modelRef(provider.id, provider[field]) : provider.id,
-        message: String((err && err.message) || err)
+      recorded = tasks.failDelivery(taskId, error, names);
+    } catch (persistError) {
+      throw taskActionError(taskId, '图像已生成，但交付状态无法可靠落盘；禁止重新生成', {
+        message: String((persistError && persistError.message) || persistError)
       });
     }
+    throw taskActionError(taskId, '图像已生成，但产物交付失败：' + recorded.error, recorded.lastError);
+  }
+}
+
+/** v0.1.3 图片能力统一链路：异步、同步及混合候选共用一个 Task。 */
+async function submitImageV2(routes, prompt, args, signal) {
+  const task = tasks.createV2({
+    cap: 'image',
+    prompt: prompt.slice(0, 4000),
+    size: args.size || '',
+    count: Number(args.n || 1),
+    ...(args.model ? { requestedModelRef: String(args.model) } : {}),
+    ...(args._retryOf ? { retryOf: String(args._retryOf) } : {})
+  });
+  const candidates = routes.map((route) => ({
+    id: route.provider.id,
+    model: route.modelRef,
+    route,
+    submit: async () => {
+      if (signal && signal.aborted) {
+        throw new ProviderContractError('提交前收到取消信号', {
+          stage: 'submit', category: 'aborted', acceptance: 'unknown'
+        });
+      }
+      try {
+        if (route.protocol === 'dashscope') {
+          if (adapters.dashscopeImageMode(route.model) === 'legacy-async') {
+            const remoteTaskId = await adapters.submitImage({
+              key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+              model: route.model, prompt, size: args.size, n: args.n, signal
+            });
+            return { kind: 'accepted', remoteTaskId };
+          }
+          const urls = await adapters.generateImageMultimodal({
+            key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+            model: route.model, prompt, size: args.size, n: args.n, signal
+          });
+          return { kind: 'completed', value: { kind: 'urls', items: urls } };
+        }
+        const items = await adapters.openAiGenerateImage({
+          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+          model: route.model, prompt, size: args.size, n: args.n, signal
+        });
+        return { kind: 'completed', value: { kind: 'openai', items } };
+      } catch (error) {
+        throw imageSubmissionError(error);
+      }
+    }
+  }));
+
+  const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'image' }, {
+    beforeAttempt: ({ providerId, model }) => {
+      const route = routes.find((item) => item.provider.id === providerId && item.modelRef === model);
+      if (!route) throw new Error('候选路由与 Attempt 身份不一致');
+      return tasks.beginAttempt(task.id, {
+        providerId,
+        providerName: route.provider.name,
+        model,
+        protocol: route.protocol
+      });
+    },
+    afterResult: (snapshot) => tasks.recordAttemptResult(task.id, snapshot)
+  });
+
+  if (submitted.localError) {
+    throw taskActionError(task.id, '提交结果未能可靠落盘，已停止后续候选', submitted.localError);
+  }
+  if (!submitted.candidate) {
+    const lastError = submitted.result && submitted.result.error;
+    tasks.finalizeNoAcceptance(task.id, lastError || '所有候选均明确未受理');
+    throw taskActionError(task.id, '所有候选均明确未受理', submitted.attempts);
   }
-  const error = new Error('iris: ' + label + '提交失败；已按顺序尝试 ' + errors.length + ' 个模型：' +
-    errors.map((e) => e.modelRef + '（' + e.message + '）').join('；'));
-  error.errors = errors;
-  throw error;
+  if (submitted.result.kind === 'acceptance_unknown') {
+    const safe = submitted.result.error && submitted.result.error.safeMessage;
+    throw taskActionError(task.id, '供应商受理状态未知，禁止自动重提' + (safe ? '：' + safe : ''), submitted.result.error);
+  }
+
+  const route = submitted.candidate.route;
+  if (submitted.result.kind === 'completed') {
+    const delivered = await deliverCompletedImage(task.id, submitted.result.value, signal);
+    return { task: delivered, provider: route.provider, model: route.model, remoteTaskId: null };
+  }
+  if (submitted.result.kind !== 'accepted') {
+    throw taskActionError(task.id, '图片提交结果无法识别，已停止后续候选', submitted.result);
+  }
+
+  try {
+    tasks.activateWatch(task.id);
+  } catch (error) {
+    throw taskActionError(task.id, '远端已受理，但本地盯守状态落盘失败；禁止自动重提', { message: String(error.message || error) });
+  }
+  tasks.watch(tasks.get(task.id), {
+    key: () => route.provider.apiKey,
+    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId }),
+    intervalMs: 2500,
+    onSuccess: async (record, result) => {
+      const names = [];
+      for (const url of result.urls || []) {
+        const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, 'png');
+        await adapters.downloadTo(url, path.join(outputDir(), name));
+        names.push(name);
+      }
+      for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
+      return names;
+    }
+  });
+  return {
+    task: tasks.get(task.id),
+    provider: route.provider,
+    model: route.model,
+    remoteTaskId: submitted.result.remoteTaskId
+  };
 }
 
 function findGeneratedAttachment(attachmentId) {
@@ -129,6 +299,313 @@ function fileDataUrl(file) {
   return 'data:' + file.mediaType + ';base64,' + fs.readFileSync(file.absPath).toString('base64');
 }
 
+function videoRoute(provider, args, frame) {
+  const parsed = models.parseModelRef(String(args.model || ''));
+  const model = args.model ? (parsed?.modelId || String(args.model)) : (provider.videoModel || 'wan2.2-t2v-flash');
+  const isS2V = /s2v/i.test(model);
+  const mode = isS2V ? 's2v' : (frame ? 'i2v' : 't2v');
+  return { provider, model, modelRef: models.modelRef(provider.id, model), isS2V, mode, protocol: 'dashscope' };
+}
+
+function beforeGenerationError(error, stage) {
+  const category = error && (error.category === 'network' || error instanceof TypeError)
+    ? 'network'
+    : (stage === 'validate' ? 'invalid_request' : 'local_io');
+  return new ProviderContractError(String((error && error.message) || error || '提交前准备失败'), {
+    stage,
+    category,
+    acceptance: 'not_accepted',
+    retryable: category === 'network'
+  });
+}
+
+async function submitVideoV2(routes, frame, prompt, args, signal) {
+  const task = tasks.createV2({
+    cap: 'video', prompt: prompt.slice(0, 4000),
+    ...(args.model ? { requestedModelRef: String(args.model) } : {}),
+    ...(args._retryOf ? { retryOf: String(args._retryOf) } : {})
+  });
+  const candidates = routes.map((route) => ({
+    id: route.provider.id,
+    model: route.modelRef,
+    route,
+    submit: async (_input, context) => {
+      const attemptId = context.attempt.id;
+      let submitArgs;
+      if (route.isS2V) {
+        if (!frame) throw beforeGenerationError(new Error('iris: s2v 数字人需要首帧'), 'validate');
+        const audioPath = String(args.audio_path || '').trim();
+        if (!audioPath || !path.isAbsolute(audioPath)) {
+          throw beforeGenerationError(new Error('iris: s2v 的 audio_path 必须是绝对路径'), 'validate');
+        }
+        if (!fs.existsSync(audioPath)) throw beforeGenerationError(new Error('iris: 音频文件不存在'), 'validate');
+        tasks.markAttemptStage(task.id, attemptId, 'upload');
+        try {
+          const imageUrl = await adapters.uploadTempFile({
+            key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+            model: route.model, filePath: frame.absPath, signal
+          });
+          const audioUrl = await adapters.uploadTempFile({
+            key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+            model: route.model, filePath: audioPath, signal
+          });
+          submitArgs = { imgDataUrl: imageUrl, audioUrl, resolution: args.resolution || '480P' };
+        } catch (error) {
+          throw beforeGenerationError(error, 'upload');
+        }
+      } else {
+        if (!prompt) throw beforeGenerationError(new Error('iris: 文生/图生视频需要 prompt'), 'validate');
+        tasks.markAttemptStage(task.id, attemptId, 'prepare');
+        try {
+          submitArgs = {
+            prompt,
+            imgDataUrl: frame ? fileDataUrl(frame) : undefined,
+            size: args.size || '1280*720',
+            duration: args.duration ? Number(args.duration) : undefined
+          };
+        } catch (error) {
+          throw beforeGenerationError(error, 'prepare');
+        }
+      }
+      tasks.markAttemptStage(task.id, attemptId, 'submit');
+      try {
+        const remoteTaskId = await adapters.submitVideo({
+          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+          model: route.model, ...submitArgs, signal
+        });
+        return { kind: 'accepted', remoteTaskId };
+      } catch (error) {
+        throw imageSubmissionError(error);
+      }
+    }
+  }));
+
+  const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'video' }, {
+    beforeAttempt: ({ providerId, model }) => {
+      const route = routes.find((item) => item.provider.id === providerId && item.modelRef === model);
+      if (!route) throw new Error('候选路由与 Attempt 身份不一致');
+      const attempt = tasks.beginAttempt(task.id, {
+        providerId, providerName: route.provider.name, model, protocol: route.protocol
+      });
+      tasks.update(task.id, {
+        mode: route.mode,
+        ...(route.isS2V ? { resolution: args.resolution || '480P' } : {
+          size: args.size || '1280*720', ...(args.duration ? { duration: Number(args.duration) } : {})
+        })
+      });
+      return attempt;
+    },
+    afterResult: (snapshot) => tasks.recordAttemptResult(task.id, snapshot)
+  });
+
+  if (submitted.localError) {
+    throw taskActionError(task.id, '视频提交结果未能可靠落盘，已停止后续候选', submitted.localError);
+  }
+  if (!submitted.candidate) {
+    const lastError = submitted.result && submitted.result.error;
+    tasks.finalizeNoAcceptance(task.id, lastError || '所有视频候选均明确未受理');
+    throw taskActionError(task.id, '所有视频候选均明确未受理', submitted.attempts);
+  }
+  if (submitted.result.kind !== 'accepted') {
+    const safe = submitted.result.error && submitted.result.error.safeMessage;
+    throw taskActionError(task.id, '视频受理状态未知，禁止自动重提' + (safe ? '：' + safe : ''), submitted.result.error);
+  }
+
+  const route = submitted.candidate.route;
+  tasks.activateWatch(task.id);
+  tasks.watch(tasks.get(task.id), {
+    key: () => route.provider.apiKey,
+    poll: ({ key, remoteTaskId: id }) => adapters.pollTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId: id }),
+    intervalMs: 6000,
+    onSuccess: async (record, result) => {
+      const names = [];
+      for (const url of result.urls || []) {
+        const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, 'mp4');
+        await adapters.downloadTo(url, path.join(outputDir(), name));
+        names.push(name);
+      }
+      for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
+      return names;
+    }
+  });
+  return { task: tasks.get(task.id), provider: route.provider, model: route.model, remoteTaskId: submitted.result.remoteTaskId };
+}
+
+function simpleModelRoute(provider, args, field, fallback, protocol = 'dashscope') {
+  const parsed = models.parseModelRef(String(args.model || ''));
+  const model = args.model ? (parsed?.modelId || String(args.model)) : (provider[field] || fallback);
+  return { provider, model, modelRef: models.modelRef(provider.id, model), protocol };
+}
+
+async function submitTranscriptionV2(routes, audioPath, args, signal) {
+  const task = tasks.createV2({
+    cap: 'transcribe', prompt: 'audio transcribe: ' + path.basename(audioPath),
+    ...(args.model ? { requestedModelRef: String(args.model) } : {})
+  });
+  const candidates = routes.map((route) => ({
+    id: route.provider.id,
+    model: route.modelRef,
+    route,
+    submit: async (_input, context) => {
+      tasks.markAttemptStage(task.id, context.attempt.id, 'upload');
+      let audioUrl;
+      try {
+        audioUrl = await adapters.uploadTempFile({
+          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+          model: route.model, filePath: audioPath, signal
+        });
+      } catch (error) {
+        throw beforeGenerationError(error, 'upload');
+      }
+      tasks.markAttemptStage(task.id, context.attempt.id, 'submit');
+      try {
+        const remoteTaskId = await adapters.submitTranscription({
+          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+          model: route.model, audioUrl, signal
+        });
+        return { kind: 'accepted', remoteTaskId };
+      } catch (error) {
+        throw imageSubmissionError(error);
+      }
+    }
+  }));
+  const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'transcribe' }, {
+    beforeAttempt: ({ providerId, model }) => {
+      const route = routes.find((item) => item.provider.id === providerId && item.modelRef === model);
+      if (!route) throw new Error('候选路由与 Attempt 身份不一致');
+      return tasks.beginAttempt(task.id, {
+        providerId, providerName: route.provider.name, model, protocol: route.protocol
+      });
+    },
+    afterResult: (snapshot) => tasks.recordAttemptResult(task.id, snapshot)
+  });
+  if (submitted.localError) throw taskActionError(task.id, '转写提交结果未能可靠落盘，已停止后续候选', submitted.localError);
+  if (!submitted.candidate) {
+    tasks.finalizeNoAcceptance(task.id, submitted.result?.error || '所有转写候选均明确未受理');
+    throw taskActionError(task.id, '所有转写候选均明确未受理', submitted.attempts);
+  }
+  if (submitted.result.kind !== 'accepted') {
+    const safe = submitted.result.error && submitted.result.error.safeMessage;
+    throw taskActionError(task.id, '转写受理状态未知，禁止自动重提' + (safe ? '：' + safe : ''), submitted.result.error);
+  }
+  const route = submitted.candidate.route;
+  tasks.activateWatch(task.id);
+  tasks.watch(tasks.get(task.id), {
+    key: () => route.provider.apiKey,
+    poll: async ({ key, remoteTaskId: id }) => {
+      const result = await adapters.pollTranscriptionTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId: id });
+      return { done: result.done, ok: result.ok, urls: result.text ? [result.text] : [], message: result.message };
+    },
+    intervalMs: 2500,
+    allowEmptyResult: true,
+    onSuccess: async (record, result) => {
+      tasks.update(record.id, { transcribeText: (result.urls && result.urls.join('')) || '' });
+      return [];
+    }
+  });
+  return { task: tasks.get(task.id), provider: route.provider, model: route.model, remoteTaskId: submitted.result.remoteTaskId };
+}
+
+async function submitTtsV2(routes, text, args, signal) {
+  const task = tasks.createV2({
+    cap: 'tts', prompt: text.slice(0, 500),
+    ...(args.model ? { requestedModelRef: String(args.model) } : {})
+  });
+  const candidates = routes.map((route) => ({
+    id: route.provider.id,
+    model: route.modelRef,
+    route,
+    submit: async (_input, context) => {
+      tasks.markAttemptStage(task.id, context.attempt.id, 'submit');
+      try {
+        const audio = await adapters.synthesizeTts({
+          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
+          model: route.model, text, voice: route.voice, signal
+        });
+        return { kind: 'completed', value: audio };
+      } catch (error) {
+        throw imageSubmissionError(error);
+      }
+    }
+  }));
+  const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'tts' }, {
+    beforeAttempt: ({ providerId, model }) => {
+      const route = routes.find((item) => item.provider.id === providerId && item.modelRef === model);
+      if (!route) throw new Error('候选路由与 Attempt 身份不一致');
+      const attempt = tasks.beginAttempt(task.id, {
+        providerId, providerName: route.provider.name, model, protocol: route.protocol
+      });
+      tasks.update(task.id, { voice: route.voice });
+      return attempt;
+    },
+    afterResult: (snapshot) => tasks.recordAttemptResult(task.id, snapshot)
+  });
+  if (submitted.localError) throw taskActionError(task.id, '语音合成结果未能可靠落盘，已停止后续候选', submitted.localError);
+  if (!submitted.candidate) {
+    tasks.finalizeNoAcceptance(task.id, submitted.result?.error || '所有语音候选均明确未受理');
+    throw taskActionError(task.id, '所有语音候选均明确未受理', submitted.attempts);
+  }
+  if (submitted.result.kind !== 'completed') {
+    const safe = submitted.result.error && submitted.result.error.safeMessage;
+    throw taskActionError(task.id, '语音合成受理状态未知，禁止自动重提' + (safe ? '：' + safe : ''), submitted.result.error);
+  }
+  const route = submitted.candidate.route;
+  const audio = submitted.result.value || {};
+  const names = [];
+  try {
+    tasks.beginDelivery(task.id);
+    const name = task.id + '.' + (audio.audioUrl ? adapters.extFromUrl(audio.audioUrl, 'wav') : 'wav');
+    const target = path.join(outputDir(), name);
+    if (audio.audioUrl) await adapters.downloadTo(audio.audioUrl, target, { signal });
+    else if (audio.audioB64) writePrivateFile(target, Buffer.from(audio.audioB64, 'base64'));
+    else throw new Error('语音合成成功响应缺少音频数据');
+    names.push(name);
+    registerMedia(task.id, target);
+    tasks.completeDelivery(task.id, names);
+  } catch (error) {
+    const recorded = tasks.failDelivery(task.id, error, names);
+    throw taskActionError(task.id, '语音已合成，但产物交付失败：' + recorded.error, recorded.lastError);
+  }
+  return { task: tasks.get(task.id), provider: route.provider, model: route.model };
+}
+
+/** 重新观察/交付与启动恢复共享的远端查询和本地落盘依赖。 */
+export function taskPollDeps(provider, task) {
+  if (!provider || !task) return null;
+  if (task.cap === 'transcribe') {
+    return {
+      key: () => provider.apiKey,
+      poll: async ({ key, remoteTaskId }) => {
+        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId });
+        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
+      },
+      intervalMs: 2500,
+      allowEmptyResult: true,
+      onSuccess: async (record, result) => {
+        tasks.update(record.id, { transcribeText: (result.urls && result.urls.join('')) || '' });
+        return [];
+      }
+    };
+  }
+  if (task.cap !== 'image' && task.cap !== 'video') return null;
+  return {
+    key: () => provider.apiKey,
+    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
+    intervalMs: task.cap === 'video' ? 6000 : 2500,
+    onSuccess: async (record, result) => {
+      const names = [];
+      for (const url of result.urls || []) {
+        const fallback = task.cap === 'video' ? 'mp4' : 'png';
+        const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, fallback);
+        await adapters.downloadTo(url, path.join(outputDir(), name));
+        names.push(name);
+      }
+      for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
+      return names;
+    }
+  };
+}
+
 /* ---------------- 动作注册表 ---------------- */
 
 const actions = {};
@@ -160,75 +637,16 @@ export async function runAction(ctx, name, args, { signal } = {}) {
 register('image', async (ctx, args, { signal }) => {
   const prompt = String(args.prompt || '').trim();
   if (!prompt) throw new Error('iris: prompt 不能为空');
-  const submitted = await submitWithFailover(cap.CAPABILITIES.IMAGE, '图像', signal, args.model, async (provider) => {
-    const protocol = provider.mediaProtocol || inferMediaProtocol(provider.baseUrl);
-    const model = args.model ? (models.parseModelRef(String(args.model))?.modelId || String(args.model)) : (provider.imageModel || (protocol === 'openai-images' ? 'gpt-image-1' : 'wan2.2-t2i-flash'));
-    const task = tasks.create({
-      cap: 'image', providerId: provider.id, providerName: provider.name,
-      model, protocol, prompt: prompt.slice(0, 4000)
-    });
-    if (protocol === 'dashscope') {
-      const started = await tasks.submitGuard(task, () => adapters.startImageGeneration({
-        key: provider.apiKey, baseUrl: provider.baseUrl, model, prompt, size: args.size, n: args.n, signal
-      }));
-      const remoteTaskId = started.remoteTaskId;
-      if (!remoteTaskId) {
-        try {
-          const names = [];
-          for (const url of started.urls || []) {
-            const name = `${task.id}-${names.length}.${adapters.extFromUrl(url, 'png')}`;
-            await adapters.downloadTo(url, path.join(outputDir(), name), { signal });
-            names.push(name);
-          }
-          tasks.update(task.id, { status: 'succeeded', files: names, finishedAt: new Date().toISOString() });
-          for (const name of names) registerMedia(task.id, path.join(outputDir(), name));
-        } catch (err) {
-          // 模型已经同步生成成功，转存失败不能再向下一供应商重复计费。
-          tasks.update(task.id, { status: 'failed', error: `图片转存失败：${String(err.message || err)}`, finishedAt: new Date().toISOString() });
-        }
-        return { task: tasks.get(task.id), provider, model, remoteTaskId: null };
-      }
-      tasks.update(task.id, { remoteTaskId });
-      tasks.watch(tasks.get(task.id), {
-        key: () => provider.apiKey,
-        poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
-        intervalMs: 2500,
-        onSuccess: async (t, r) => {
-          const names = [];
-          for (const url of r.urls || []) {
-            const name = `${t.id}-${names.length}.${adapters.extFromUrl(url, 'png')}`;
-            await adapters.downloadTo(url, path.join(outputDir(), name));
-            names.push(name);
-          }
-          for (const n of names) registerMedia(t.id, path.join(outputDir(), n));
-          return names;
-        }
-      });
-      return { task, provider, model, remoteTaskId };
-    }
-    const files = await tasks.submitGuard(task, async () => {
-      const outs = await adapters.openAiGenerateImage({
-        key: provider.apiKey, baseUrl: provider.baseUrl, model, prompt, size: args.size, n: args.n, signal
-      });
-      const written = [];
-      for (let i = 0; i < outs.length; i++) {
-        const p = path.join(outputDir(), `${task.id}-${i}.png`);
-        if (outs[i].b64) writePrivateFile(p, Buffer.from(outs[i].b64, 'base64'));
-        else await adapters.downloadTo(outs[i].url, p, { signal });
-        written.push(p);
-      }
-      return written;
-    });
-    tasks.update(task.id, { status: 'succeeded', files: files.map((f) => path.basename(f)), finishedAt: new Date().toISOString() });
-    for (const f of files) registerMedia(task.id, f);
-    return { task, provider, model, remoteTaskId: null };
-  });
+
+  const imageProviders = selectProviders(cap.CAPABILITIES.IMAGE, '图像', args.model);
+  const routes = imageProviders.map((provider) => imageRoute(provider, args));
+  const submitted = await submitImageV2(routes, prompt, args, signal);
   return {
     ok: true, taskId: submitted.task.id, model: submitted.model, providerId: submitted.provider.id,
     remoteTaskId: submitted.remoteTaskId,
     text: submitted.remoteTaskId
-      ? `[iris] 图像任务已提交（${submitted.model}，task: ${submitted.task.id}）`
-      : `[iris] 图像任务已完成（${submitted.model}，task: ${submitted.task.id}）`
+      ? '[iris] 图像任务已提交（' + submitted.model + '，task: ' + submitted.task.id + '）'
+      : '[iris] 图像任务已完成（' + submitted.model + '，task: ' + submitted.task.id + '）'
   };
 });
 
@@ -237,60 +655,13 @@ register('video', async (ctx, args, { signal }) => {
   const prompt = String(args.prompt || '').trim();
   if (!prompt && !args.audio_path) throw new Error('iris: prompt 不能为空');
   const frame = resolveFirstFrameFile(args);
-  const submitted = await submitWithFailover(cap.CAPABILITIES.VIDEO, '视频', signal, args.model, async (provider) => {
-    const model = args.model ? (models.parseModelRef(String(args.model))?.modelId || String(args.model)) : (provider.videoModel || 'wan2.2-t2v-flash');
-    const isS2V = /s2v/i.test(model);
-    if (!isS2V && !prompt) throw new Error('iris: 文生/图生视频需要 prompt');
-    const mode = isS2V ? 's2v' : (frame ? 'i2v' : 't2v');
-    const task = tasks.create({
-      cap: 'video', providerId: provider.id, providerName: provider.name, model, mode,
-      ...(isS2V ? { resolution: args.resolution || '480P' } : {
-        size: args.size || '1280*720', ...(args.duration ? { duration: Number(args.duration) } : {})
-      }),
-      prompt: prompt.slice(0, 4000)
-    });
-    const remoteTaskId = await tasks.submitGuard(task, async () => {
-      let submitArgs;
-      if (isS2V) {
-        if (!frame) throw new Error('iris: s2v 数字人需要首帧');
-        const audioPath = String(args.audio_path || '').trim();
-        if (!audioPath || !path.isAbsolute(audioPath)) throw new Error('iris: s2v 的 audio_path 必须是绝对路径');
-        if (!fs.existsSync(audioPath)) throw new Error('iris: 音频文件不存在：' + audioPath);
-        const imageUrl = await adapters.uploadTempFile({ key: provider.apiKey, baseUrl: provider.baseUrl, model, filePath: frame.absPath, signal });
-        const audioUrl = await adapters.uploadTempFile({ key: provider.apiKey, baseUrl: provider.baseUrl, model, filePath: audioPath, signal });
-        submitArgs = { imgDataUrl: imageUrl, audioUrl, resolution: args.resolution || '480P' };
-      } else {
-        submitArgs = {
-          prompt,
-          imgDataUrl: frame ? fileDataUrl(frame) : undefined,
-          size: args.size || '1280*720',
-          duration: args.duration ? Number(args.duration) : undefined
-        };
-      }
-      return adapters.submitVideo({ key: provider.apiKey, baseUrl: provider.baseUrl, model, ...submitArgs, signal });
-    });
-    tasks.update(task.id, { remoteTaskId });
-    tasks.watch(tasks.get(task.id), {
-      key: () => provider.apiKey,
-      poll: ({ key, remoteTaskId: id }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId: id }),
-      intervalMs: 6000,
-      onSuccess: async (t, r) => {
-        const names = [];
-        for (const url of r.urls || []) {
-          const name = `${t.id}-${names.length}.${adapters.extFromUrl(url, 'mp4')}`;
-          await adapters.downloadTo(url, path.join(outputDir(), name));
-          names.push(name);
-        }
-        for (const n of names) registerMedia(t.id, path.join(outputDir(), n));
-        return names;
-      }
-    });
-    return { task, provider, model, remoteTaskId };
-  });
+  const providers = selectProviders(cap.CAPABILITIES.VIDEO, '视频', args.model);
+  const routes = providers.map((provider) => videoRoute(provider, args, frame));
+  const submitted = await submitVideoV2(routes, frame, prompt, args, signal);
   return {
     ok: true, taskId: submitted.task.id, model: submitted.model, mode: submitted.task.mode,
     providerId: submitted.provider.id, remoteTaskId: submitted.remoteTaskId,
-    text: `[iris] 视频任务已提交（${submitted.model}，task: ${submitted.task.id}）`
+    text: '[iris] 视频任务已提交（' + submitted.model + '，task: ' + submitted.task.id + '）'
   };
 });
 
@@ -298,25 +669,15 @@ register('video', async (ctx, args, { signal }) => {
 register('tts', async (ctx, args, { signal }) => {
   const text = String(args.text || '').trim();
   if (!text) throw new Error('iris: text 不能为空');
-  const submitted = await submitWithFailover(cap.CAPABILITIES.TTS, '语音', signal, args.model, async (provider) => {
-    const model = args.model ? (models.parseModelRef(String(args.model))?.modelId || String(args.model)) : (provider.ttsModel || 'qwen-tts-latest');
-    const voice = args.voice || (provider.ttsVoice || 'Cherry');
-    const task = tasks.create({ cap: 'tts', providerId: provider.id, providerName: provider.name, model, voice, prompt: text.slice(0, 500) });
-    const fileName = await tasks.submitGuard(task, async () => {
-      const r = await adapters.synthesizeTts({ key: provider.apiKey, baseUrl: provider.baseUrl, model, text, voice, signal });
-      const name = `iris-tts-${Date.now()}.${r.audioUrl ? adapters.extFromUrl(r.audioUrl, 'wav') : 'wav'}`;
-      const p = path.join(outputDir(), name);
-      if (r.audioUrl) await adapters.downloadTo(r.audioUrl, p, { signal });
-      else writePrivateFile(p, Buffer.from(r.audioB64, 'base64'));
-      return name;
-    });
-    tasks.update(task.id, { status: 'succeeded', files: [fileName], finishedAt: new Date().toISOString() });
-    registerMedia(task.id, path.join(outputDir(), fileName));
-    return { task, provider, model };
-  });
+  const providers = selectProviders(cap.CAPABILITIES.TTS, '语音', args.model);
+  const routes = providers.map((provider) => ({
+    ...simpleModelRoute(provider, args, 'ttsModel', 'qwen-tts-latest'),
+    voice: args.voice || provider.ttsVoice || 'Cherry'
+  }));
+  const submitted = await submitTtsV2(routes, text, args, signal);
   return {
     ok: true, taskId: submitted.task.id, model: submitted.model, providerId: submitted.provider.id,
-    text: `[iris] 语音已合成（${submitted.model}，task: ${submitted.task.id}）`
+    text: '[iris] 语音已合成（' + submitted.model + '，task: ' + submitted.task.id + '）'
   };
 });
 
@@ -414,6 +775,99 @@ register('status', async (ctx, args, { signal }) => {
   return { ok: true, text: recent.map((t) => `[${t.cap}] ${t.id} · ${t.status} · ${t.model}`).join('\n') };
 });
 
+/* ---------- Task v2 人工接管 ---------- */
+register('task_reobserve', async (ctx, args) => {
+  const id = String(args.task_id || '').trim();
+  const task = tasks.get(id);
+  if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可接管的 Task v2');
+  if (task.acceptance !== 'accepted' || !task.remoteTaskId) throw new Error('iris: 缺少已受理证据或远端任务 ID，不能重新观察');
+  if (task.outcome === 'succeeded') throw new Error('iris: 生成已经成功，请使用重新交付');
+  if (task.outcome === 'failed' || task.outcome === 'canceled') throw new Error('iris: 任务已有明确终态，不能重新观察');
+  const provider = store.providerById(task.providerId);
+  const deps = provider && taskPollDeps(provider, task);
+  if (!deps) throw new Error('iris: 对应供应商或轮询协议不可用');
+  tasks.watch(task, deps);
+  return { ok: true, taskId: id, text: '[iris] 已重新观察远端任务；不会重新提交生成请求。' };
+});
+
+register('task_redeliver', async (ctx, args, { signal }) => {
+  const id = String(args.task_id || '').trim();
+  const task = tasks.get(id);
+  if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可重新交付的 Task v2');
+  if (task.outcome !== 'succeeded' || task.deliveryState !== 'failed') throw new Error('iris: 任务不处于生成成功但交付失败状态');
+  if (!task.remoteTaskId) throw new Error('iris: 该同步结果没有可重新获取的远端任务 ID，请重新从原始输入发起');
+  const provider = store.providerById(task.providerId);
+  const deps = provider && taskPollDeps(provider, task);
+  if (!deps || task.cap === 'transcribe') throw new Error('iris: 对应供应商或产物交付协议不可用');
+  tasks.prepareRedelivery(id);
+  try {
+    tasks.beginDelivery(id);
+    const result = await deps.poll({ key: deps.key(), remoteTaskId: task.remoteTaskId, signal });
+    if (!result.done) throw new Error('远端结果暂未就绪，请先重新观察');
+    if (!result.ok) throw new Error(result.message || '供应商当前无法返回成功产物');
+    if (!(result.urls || []).length) throw new Error('供应商未返回可交付的结果 URL');
+    const files = await deps.onSuccess(tasks.get(id), result);
+    tasks.completeDelivery(id, files);
+    return { ok: true, taskId: id, files, text: '[iris] 产物已重新交付；未重新生成。' };
+  } catch (error) {
+    const current = tasks.get(id);
+    if (current && current.outcome === 'succeeded' && current.deliveryState !== 'failed') tasks.failDelivery(id, error);
+    throw new Error('iris: 重新交付失败：' + String((error && error.message) || error));
+  }
+});
+
+register('task_ack_attention', async (_ctx, args) => {
+  const id = String(args.task_id || '').trim();
+  const task = tasks.get(id);
+  if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可标为已读的 Task v2');
+  tasks.acknowledgeAttention(id, 'read');
+  return { ok: true, taskId: id, text: '[iris] 提醒已标为已读；任务事实未改变，可在历史详情中恢复提醒。' };
+});
+
+register('task_restore_attention', async (_ctx, args) => {
+  const id = String(args.task_id || '').trim();
+  const task = tasks.get(id);
+  if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可恢复提醒的 Task v2');
+  tasks.restoreAttention(id);
+  return { ok: true, taskId: id, text: '[iris] 已恢复任务提醒。' };
+});
+
+register('task_manual_retry', async (ctx, args, { signal }) => {
+  const id = String(args.task_id || '').trim();
+  if (args.confirm_duplicate_charge !== true) throw new Error('iris: 必须明确确认本次操作可能产生重复任务或重复费用');
+  const task = tasks.get(id);
+  if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可重试的 Task v2');
+  const state = deriveUserState(task);
+  if (!['needs_attention', 'failed', 'canceled'].includes(state)) throw new Error('iris: 当前状态不需要重新生成');
+  if (tasks.attentionDisposition(task).status === 'acknowledged') {
+    throw new Error('iris: 该提醒已经处理；如需再次操作，请先恢复提醒');
+  }
+  let action;
+  let retryArgs;
+  if (task.cap === 'image' && task.prompt) {
+    action = 'image';
+    retryArgs = { prompt: task.prompt, size: task.size || undefined, n: task.count || 1 };
+  } else if (task.cap === 'video' && task.mode === 't2v' && task.prompt) {
+    action = 'video';
+    retryArgs = { prompt: task.prompt, size: task.size || undefined, duration: task.duration || undefined };
+  } else {
+    throw new Error('iris: 该任务的原始输入无法无损重建，请从原始文件或文本手动发起新任务');
+  }
+  if (task.modelRef) retryArgs.model = task.modelRef;
+  retryArgs._retryOf = id;
+  try {
+    const result = await runAction(ctx, action, retryArgs, { signal });
+    if (result.taskId) tasks.linkManualRetry(id, result.taskId);
+    return { ...result, retryOf: id, text: (result.text || '[iris] 已创建新任务')
+      + '\n[iris] 原任务提醒已归档，并保留新旧任务关联；本次新任务可能与远端未知任务重复。' };
+  } catch (error) {
+    if (error && error.taskId) {
+      try { tasks.linkManualRetry(id, error.taskId); } catch (_) {}
+    }
+    throw error;
+  }
+});
+
 /* ---------- 🧹 任务清理（阶段 4 续：元数据删除，产物文件默认保留） ---------- */
 
 /** 扫描 outputs/ 里不被任何任务记录引用的孤儿文件（files[] + media[].file 并集） */
@@ -849,35 +1303,15 @@ register('transcribe', async (ctx, args, { signal }) => {
   const audioPath = String(args.audio_path || '').trim();
   if (!audioPath || !path.isAbsolute(audioPath)) throw new Error('iris: audio_path 必须是绝对路径');
   if (!fs.existsSync(audioPath)) throw new Error('iris: 音频文件不存在');
-  const submitted = await submitWithFailover(cap.CAPABILITIES.TRANSCRIBE, '转写', signal, args.model, async (provider) => {
-    const model = args.model ? (models.parseModelRef(String(args.model))?.modelId || String(args.model)) : (provider.transcribeModel || 'qwen-audio-3.0-asr-flash-filetrans');
-    const task = tasks.create({
-      cap: 'transcribe', providerId: provider.id, providerName: provider.name,
-      model, prompt: 'audio transcribe: ' + path.basename(audioPath)
-    });
-    const remoteTaskId = await tasks.submitGuard(task, async () => {
-      const audioUrl = await adapters.uploadTempFile({ key: provider.apiKey, baseUrl: provider.baseUrl, model, filePath: audioPath, signal });
-      return adapters.submitTranscription({ key: provider.apiKey, baseUrl: provider.baseUrl, model, audioUrl, signal });
-    });
-    tasks.update(task.id, { remoteTaskId });
-    tasks.watch(tasks.get(task.id), {
-      key: () => provider.apiKey,
-      poll: async ({ key, remoteTaskId: id }) => {
-        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId: id });
-        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
-      },
-      intervalMs: 2500,
-      onSuccess: async (t, r) => {
-        tasks.update(t.id, { transcribeText: (r.urls && r.urls.join('')) || '' });
-        return [];
-      }
-    });
-    return { task, provider, model, remoteTaskId };
-  });
+  const providers = selectProviders(cap.CAPABILITIES.TRANSCRIBE, '转写', args.model);
+  const routes = providers.map((provider) =>
+    simpleModelRoute(provider, args, 'transcribeModel', 'qwen-audio-3.0-asr-flash-filetrans')
+  );
+  const submitted = await submitTranscriptionV2(routes, audioPath, args, signal);
   return {
     ok: true, taskId: submitted.task.id, model: submitted.model, providerId: submitted.provider.id,
     remoteTaskId: submitted.remoteTaskId,
-    text: `[iris] 音频转写任务已提交（${submitted.model}，task: ${submitted.task.id}）`
+    text: '[iris] 音频转写任务已提交（' + submitted.model + '，task: ' + submitted.task.id + '）'
   };
 });