@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/lib/provider-protocol.js

@@ -45,6 +45,29 @@ export function selectMediaProtocol(provider) {
   return { mediaProtocol: detected || 'openai-images', protocolInferred: !detected };
 }
 
+/** 模型图片协议只覆盖生图；auto 沿用账号级默认，不另外猜测端点。 */
+export function normalizeImageProtocol(value) {
+  const protocol = typeof value === 'string' ? value.trim() : '';
+  if (!['auto', 'dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) {
+    throw Object.assign(new TypeError('imageProtocol 必须是 auto、dashscope、openai-images、openai-chat-images 或 openai-responses-images'), {
+      code: 'IRIS_PROVIDER_IMAGE_PROTOCOL_INVALID'
+    });
+  }
+  return protocol;
+}
+
+export function selectImageProtocol(provider, modelId) {
+  const entry = Array.isArray(provider?.models) ? provider.models.find(model => model?.id?.trim() === modelId) : null;
+  if (entry?.imageProtocol === undefined) return selectMediaProtocol(provider);
+  const protocol = normalizeImageProtocol(entry.imageProtocol);
+  return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
+}
+
+/** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
+export function providerForImageModel(provider, modelId) {
+  return { ...provider, ...selectImageProtocol(provider, modelId) };
+}
+
 export function unsupportedProtocolError(protocol, kind = 'media') {
   const safeName = /^[a-z][a-z0-9-]{0,63}$/.test(String(protocol)) ? protocol : '(invalid)';
   const error = new TypeError('iris: 不支持的 ' + (kind === 'vision' ? 'Vision' : 'Provider') + ' 协议：' + safeName);
@@ -72,3 +95,64 @@ export function isConfiguredProvider(provider) {
     && providerMediaBaseUrl(provider)
     && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
 }
+
+/**
+ * 生图尺寸的协议差异集中在这里，调用点不再自带厂商假设。
+ *
+ * 分隔符（2026-10-11 实测线上端点）：
+ * - dashscope 用 `宽*高`；多模态端点严格校验格式，传 `100x100` 直接回
+ *   `Invalid size format`；旧异步端点提交期完全不校验（`100x100`/`100X100`/`auto` 均 200），
+ *   由具体模型在生成期报错。
+ * - OpenAI 兼容三家用 `宽x高`；尺寸集合由各家网关决定，只做格式归一，不设数值白名单。
+ *
+ * 数值边界只登记服务端确证会拒绝的那一条：
+ * - dashscope 多模态：`Image area must be between 262144 (512x512) and 4194304 (2048x2048)`。
+ * - 其余协议暂无证据，一律留空 —— 本地不拦，交给上游报错，避免比服务端更严。
+ */
+export const IMAGE_SIZE_RULES = Object.freeze({
+  dashscope: Object.freeze({ separator: '*' }),
+  'openai-images': Object.freeze({ separator: 'x' }),
+  'openai-chat-images': Object.freeze({ separator: 'x' }),
+  'openai-responses-images': Object.freeze({ separator: 'x' }),
+  'dashscope/multimodal-sync': Object.freeze({
+    separator: '*', minArea: 262144, maxArea: 4194304
+  })
+});
+
+/** 协议级规则优先于账号级；都没有则返回 null（= 本地不约束）。 */
+export function imageSizeRule(protocol, mode) {
+  const key = mode ? String(protocol) + '/' + String(mode) : String(protocol);
+  return IMAGE_SIZE_RULES[key] || IMAGE_SIZE_RULES[String(protocol)] || null;
+}
+
+/** 解析 `宽<分隔符>高`；无法识别返回 null（含 `auto` 这类自由取值）。 */
+export function parseImageSize(size) {
+  const m = /^(\d+)\s*([*x×X])\s*(\d+)$/.exec(String(size ?? '').trim());
+  if (!m) return null;
+  const width = Number(m[1]);
+  const height = Number(m[3]);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+  return { width, height, separator: m[2] };
+}
+
+/** 把尺寸归一成该协议的规范分隔符；无法识别的原样返回。 */
+export function normalizeImageSize({ protocol, mode, size } = {}) {
+  const rule = imageSizeRule(protocol, mode);
+  if (!rule || !rule.separator) return size;
+  const parsed = parseImageSize(size);
+  if (!parsed) return size;
+  return parsed.width + rule.separator + parsed.height;
+}
+
+/** 返回违规说明；合规、无规则或无法识别时返回 null。纯函数：不抛错、不依赖具体错误类型。 */
+export function imageSizeViolation({ protocol, mode, size } = {}) {
+  const rule = imageSizeRule(protocol, mode);
+  if (!rule || rule.minArea === undefined) return null;
+  const parsed = parseImageSize(size);
+  if (!parsed) return null;
+  const { width, height } = parsed;
+  const area = width * height;
+  if (area >= rule.minArea && area <= rule.maxArea) return null;
+  const label = mode ? protocol + '/' + mode : protocol;
+  return `尺寸 ${width}*${height} 不被 ${label} 接受：总像素需在 ${rule.minArea}–${rule.maxArea} 之间`;
+}

package/lib/provider-task-runner.js

@@ -3,7 +3,8 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createCoreArtifact } from './core-artifacts.js';
+import sharp from 'sharp';
+import { adoptCoreArtifactFile, createCoreArtifact } from './core-artifacts.js';
 import {
   activateCoreWatch,
   beginCoreAttempt,
@@ -28,7 +29,8 @@ import {
   hasProviderOperation,
   invokeProviderOperation
 } from './provider-adapter.js';
-import { providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -38,7 +40,7 @@ export const PROVIDER_TASK_RUNNER_VERSION = 0;
  * 失败，不会按图片语义猜。
  */
 export const DELIVERY_PROFILES = Object.freeze({
-  image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png']), defaultMediaType: 'image/png' }),
+  image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/webp']), defaultMediaType: 'image/png' }),
   video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4']), defaultMediaType: 'video/mp4' }),
   // TTS 同步完成型：submit 内 completed → 同一次调用直接交付（无 remote 长轮询）。
   tts: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
@@ -81,7 +83,8 @@ function normalizedCandidates(capability, candidates) {
         || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))) {
       throw new TypeError('Provider 候选 ' + (index + 1) + ' 不支持 Task capability 或模型复合身份无效');
     }
-    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason };
+    if (candidate.prepareInput !== undefined && typeof candidate.prepareInput !== 'function') throw new TypeError('候选 prepareInput 必须是函数');
+    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason, prepareInput: candidate.prepareInput };
   });
 }
 
@@ -91,6 +94,21 @@ function stagingFile(dataRoot) {
   return path.join(directory, 'download-' + process.pid + '-' + crypto.randomBytes(8).toString('hex') + '.part');
 }
 
+async function generatedImageMediaType(bytes) {
+  let format;
+  try { format = (await sharp(bytes).metadata()).format; }
+  catch (_) {
+    throw new ProviderContractError('供应商产物不是可识别的图片', {
+      stage: 'download', category: 'protocol', acceptance: 'accepted'
+    });
+  }
+  const mediaType = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }[format];
+  if (!mediaType) throw new ProviderContractError('供应商图片格式仅支持 PNG、JPEG、WebP', {
+    stage: 'download', category: 'protocol', acceptance: 'accepted'
+  });
+  return mediaType;
+}
+
 async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, signal) {
   beginCoreDelivery(dataRoot, taskId);
   const artifactIds = [];
@@ -110,7 +128,7 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
     }
     for (const remote of remoteArtifacts) {
       const mediaType = String(remote.mediaType || profile.defaultMediaType);
-      if (!profile.mediaTypes.includes(mediaType)) {
+      if (task.capability !== 'image' && !profile.mediaTypes.includes(mediaType)) {
         throw Object.assign(new Error('Provider Task Runner 交付媒体类型不在 Profile 白名单：' + mediaType), {
           stage: 'download', category: 'protocol', acceptance: 'accepted'
         });
@@ -129,15 +147,23 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
           stage: 'download', category: 'local_io', acceptance: 'accepted'
         });
       }
+      const staged = stagedFiles.at(-1);
+      if (task.capability === 'image') {
+        staged.bytes = fs.readFileSync(target);
+        staged.mediaType = await generatedImageMediaType(staged.bytes);
+      }
     }
     recordCoreDownloadCompleted(dataRoot, taskId);
     for (const staged of stagedFiles) {
-      const artifact = createCoreArtifact(dataRoot, {
+      const input = {
         kind: profile.kind,
         mediaType: staged.mediaType,
-        bytes: fs.readFileSync(staged.target),
-        metadata: { taskId, capability: task.capability }
-      });
+        metadata: { taskId, capability: task.capability },
+        ...(task.sourceArtifactId ? { relations: [{ type: 'derived-from', artifactId: task.sourceArtifactId }] } : {})
+      };
+      const artifact = staged.bytes
+        ? createCoreArtifact(dataRoot, { ...input, bytes: staged.bytes })
+        : adoptCoreArtifactFile(dataRoot, { ...input, sourcePath: staged.target });
       artifactIds.push(artifact.id);
     }
     return completeCoreDelivery(dataRoot, taskId, artifactIds);
@@ -199,21 +225,39 @@ export function createProviderTaskRunner(runtime) {
 
   async function submit(input = {}) {
     return runtime.run('execute', async ({ dataRoot, signal }) => {
+      if (signal.aborted) throw new ProviderTaskRunnerError('IRIS_PROVIDER_ABORTED', '提交已取消');
       const capability = String(input.capability || '').trim();
-      const candidates = normalizedCandidates(capability, input.candidates);
-      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom });
-      const wrapped = candidates.map(({ adapter, model, providerModel }) => ({
+      let candidates = normalizedCandidates(capability, input.candidates);
+      let providerInput = input.providerInput ?? {};
+      if (input.sourceArtifactId !== undefined) {
+        if (capability !== 'image') throw new TypeError('sourceArtifactId 仅用于图片编辑');
+        candidates = imageEditCandidates(candidates);
+        const image = await readImageEditArtifact(dataRoot, input.sourceArtifactId, signal);
+        providerInput = { ...providerInput, image };
+      }
+      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+      const wrapped = candidates.map(({ adapter, model, providerModel, prepareInput }) => ({
         id: adapter.id,
         model,
         adapter,
-        submit: (providerInput, context) => invokeProviderOperation(
-          adapter,
-          'submit',
-          { capability, model: providerModel, input: providerInput, signal },
-          { ...context, signal, taskId: task.id }
-        )
+        submit: async (providerInput, context) => {
+          if (prepareInput) {
+            try { providerInput = await prepareInput({ providerInput, signal }); }
+            catch (error) { throw new ProviderContractError('视频输入准备失败：' + (error.safeMessage || error.message), {
+              ...providerErrorRecord(error), stage: error.stage || 'prepare', category: error.category || 'local_io', acceptance: 'not_accepted'
+            }); }
+          }
+          if (signal.aborted) throw new ProviderContractError('提交已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
+          return invokeProviderOperation(
+            adapter,
+            'submit',
+            { capability, model: providerModel, input: providerInput, signal },
+            { ...context, signal, taskId: task.id }
+          );
+        }
       }));
-      const submitted = await submitWithAcceptanceBoundary(wrapped, input.providerInput ?? {}, {
+      const submitted = await submitWithAcceptanceBoundary(wrapped, providerInput, {
+        signal,
         beforeAttempt: async (attempt) => {
           const candidate = candidates[attempt.ordinal - 1];
           return beginCoreAttempt(dataRoot, task.id, {

package/lib/summarize.js

@@ -3,16 +3,20 @@
  * Iris 多模态上下文摘要（阶段 7.3）—— 把视频压成「一张联系表 + 一段转写文本」喂给视觉模型。
  *
  * 为什么是 contact sheet：
- * - VisionBackend 一次 analyze 只送一张图（自持栈吃 dataUrl / 全局模型吃 attachment ref），
+ * - Vision Port 一次 complete 只送一张图（字节与 MIME），
  *   逐帧送 N 次要 N 次模型调用、费用与延迟都不可接受；
  * - 把 N 帧缩略图按时间序拼成网格 + 每帧盖时间戳标签，一次视觉调用即可看全片（上下文压缩）。
  *
  * 契约：
- * - buildContactSheet(frames, opts) → PNG buffer + 网格尺寸（纯 sharp，可离线测试）
- * - summarizeMedia({backends, question?, transcript?, imageDataUrl, ref, signal})
- *   → askWithBackends（复用阶段 1 降级链），prompt 里嵌入转写文本（若有）
+ * - buildContactSheet({frames, ...opts}) → PNG buffer + 网格尺寸（纯 sharp，可离线测试）
+ * - summarizeMedia({ports, frames, question?, transcript?, signal})
+ *   → 一张拼图通过共享 Vision Ports，转写只消费显式输入
  */
 import sharp from 'sharp';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { createModelOperation } from './model-invoker.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { ModelPortError } from './model-port-contract.js';
 
 export class SummarizeError extends Error {
   constructor(message) {
@@ -28,7 +32,11 @@ const DEFAULT_QUESTION = '请根据这些视频关键帧（按时间顺序从左
  * @param {{frames:Array<{buffer:Buffer, atSec:number, width:number, height:number}>, cols?:number, maxSheetWidth?:number}}
  * @returns {Promise<{buffer:Buffer, width:number, height:number, rows:number, cols:number}>}
  */
-export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024 }) {
+export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024, signal }) {
+  return waitForModelWork(() => makeContactSheet({ frames, cols, maxSheetWidth, signal }), signal);
+}
+
+async function makeContactSheet({ frames, cols, maxSheetWidth, signal }) {
   if (!Array.isArray(frames) || frames.length === 0) {
     throw new SummarizeError('iris_media_summarize: 没有可拼的帧');
   }
@@ -47,10 +55,10 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
     const w = Math.max(1, cellW);
     const scale = w / Math.max(1, f.width || w);
     const h = Math.max(1, Math.round((f.height || 0) * scale));
-    const thumb = await sharp(f.buffer)
+    const thumb = await waitForModelWork(() => sharp(f.buffer)
       .resize(w, h, { fit: 'fill' })
       .png()
-      .toBuffer();
+      .toBuffer(), signal);
     // 时间戳标签（SVG 覆盖在缩略图下方）
     const label = Buffer.from(
       `<svg width="${w}" height="${labelH}" xmlns="http://www.w3.org/2000/svg">` +
@@ -58,10 +66,11 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
       `<text x="4" y="${labelH - 7}" font-family="monospace" font-size="12" fill="#ffffff">` +
       `${f.atSec.toFixed(1)}s</text></svg>`
     );
-    const cell = await sharp(thumb)
+    const cell = await waitForModelWork(() => sharp(thumb)
+      .extend({ bottom: labelH, background: { r: 16, g: 16, b: 20 } })
       .composite([{ input: label, top: h, left: 0 }])
       .png()
-      .toBuffer();
+      .toBuffer(), signal);
     cells.push({ buffer: cell, width: w, height: h + labelH });
   }
 
@@ -73,12 +82,12 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
     left: (i % colsN) * (cellW + gap),
     top: Math.floor(i / colsN) * (cellH + gap)
   }));
-  const buffer = await sharp({
+  const buffer = await waitForModelWork(() => sharp({
     create: { width: sheetW, height: sheetH, channels: 3, background: { r: 16, g: 16, b: 20 } }
   })
     .composite(composite)
     .png()
-    .toBuffer();
+    .toBuffer(), signal);
   return { buffer, width: sheetW, height: sheetH, rows: rowsN, cols: colsN };
 }
 
@@ -98,14 +107,16 @@ export function buildSummaryPrompt({ question, transcript }) {
 
 /**
  * 多模态摘要：contact sheet 图 + 可选转写文本 → 视觉后端链 → 摘要文本。
- * @param {{backends:Array, question?:string, transcript?:string, imageDataUrl:string, ref?:object, signal?:AbortSignal}}
- * @returns {Promise<{answer:string, via:string, model:string, backendId:string, errors:Array}>}
+ * @param {{ports:Array, frames:Array, question?:string, transcript?:string, signal?:AbortSignal}}
+ * @returns {Promise<object>} 完整模型结果和同一张拼图
  */
-export async function summarizeMedia({ backends, question, transcript, imageDataUrl, ref, signal }) {
-  if (!Array.isArray(backends) || backends.length === 0) {
-    throw new SummarizeError('iris_media_summarize: 没有可用的视觉后端（至少需要一个 vision provider）');
-  }
-  const { askWithBackends } = await import('./vision.js');
-  const prompt = buildSummaryPrompt({ question, transcript });
-  return askWithBackends(backends, { question: prompt, imageDataUrl, ref, signal });
+export async function summarizeMedia({ ports = [], frames, question, transcript, signal, operation, budget = VISION_BUDGET }) {
+  if (!ports.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  const op = operation || createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: ports.length } });
+  try {
+    const sheet = await buildContactSheet({ frames, cols: 3, signal: op.signal });
+    const result = await completeVision(ports, { prompt: buildSummaryPrompt({ question, transcript }),
+      image: { bytes: new Uint8Array(sheet.buffer), mediaType: 'image/png' } }, { operation: op, budget });
+    return { ...result, sheet };
+  } finally { if (!operation) op.dispose(); }
 }

package/lib/summary-input.js

@@ -0,0 +1,52 @@
+'use strict';
+/** CLI/Host 共用的摘要来源：已有帧只读，不导出媒体或重新抽帧。 */
+import { CommandError } from './command-service.js';
+import { readCoreArtifactBytes } from './core-artifacts.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+function invalid(message) { throw new CommandError('IRIS_COMMAND_INPUT_INVALID', message); }
+
+export function normalizeSummarySource(input) {
+  const hasFrames = input.frame_artifact_ids !== undefined;
+  const hasVideo = Boolean(input.video_path);
+  if (hasFrames === hasVideo) invalid('摘要必须且只能提供 video_path 或 frame_artifact_ids 之一');
+  if (hasFrames) {
+    const ids = input.frame_artifact_ids;
+    if (!Array.isArray(ids) || !ids.length || ids.length > 20
+        || !ids.every(id => typeof id === 'string' && /^artifact_[a-f0-9]{24}$/.test(id))
+        || new Set(ids).size !== ids.length) invalid('frame_artifact_ids 必须是 1–20 个不重复的 Core Artifact ID');
+    if (input.max_frames !== undefined || input.target_width !== undefined) invalid('已有帧不使用 max_frames 或 target_width；请直接选择帧 ID');
+    if (input.transcribe === true) invalid('自动音轨转写需要 video_path；已有帧可提供 transcribe_text');
+  }
+  if (input.transcribe_text !== undefined && typeof input.transcribe_text !== 'string') invalid('transcribe_text 必须是字符串');
+  if (input.transcribe === true && input.transcribe_text?.trim()) invalid('transcribe 与 transcribe_text 不能同时使用');
+  return hasFrames ? 'core-artifacts' : 'video';
+}
+
+export async function readSummaryFrames(runtime, frameArtifactIds, signal) {
+  return waitForModelWork(() => runtime.run('inspect', ({ dataRoot }) => {
+    const frames = frameArtifactIds.map(id => {
+      const { artifact, bytes } = readCoreArtifactBytes(dataRoot, id);
+      const { frameIndex, atSec, width, height } = artifact.metadata;
+      if (artifact.kind !== 'video-frame' || !['image/png', 'image/jpeg'].includes(artifact.mediaType)
+          || !Number.isFinite(atSec) || atSec < 0 || !Number.isSafeInteger(frameIndex) || frameIndex < 1
+          || !Number.isSafeInteger(width) || width < 1 || !Number.isSafeInteger(height) || height < 1) {
+        invalid('摘要需要含有效帧序号、时间戳和尺寸的 video-frame Artifact');
+      }
+      return { artifactId: artifact.id, frameIndex, atSec, width, height, buffer: bytes };
+    }).sort((a, b) => a.atSec - b.atSec || a.frameIndex - b.frameIndex);
+    return { frames, meta: { source: 'core-artifacts', startSec: frames[0].atSec, endSec: frames.at(-1).atSec } };
+  }), signal);
+}
+
+export function summaryFrameRecords(frames) {
+  return frames.map(({ artifactId, frameIndex, atSec, width, height }) => ({
+    ...(artifactId ? { artifactId, frameIndex } : {}), atSec, width, height
+  }));
+}
+
+export function summaryTimelineLabel(meta) {
+  return meta.source === 'core-artifacts'
+    ? `${meta.startSec.toFixed(1)}–${meta.endSec.toFixed(1)}s 已选帧`
+    : `${meta.durationSec.toFixed(1)}s`;
+}

package/lib/task-wait.js

@@ -0,0 +1,40 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { inspectCoreTask } from './core-tasks.js';
+
+export function coreTaskWaitFinished(task) {
+  return task.phase === 'terminal' || task.acceptance !== 'accepted'
+    || !['none', 'unknown'].includes(task.outcome);
+}
+
+/** 有界观察原 Task，超时中止 poll/下载并保留事实；没有任何 submit/retry 路径。 */
+export async function waitForCoreTask(runtime, taskId, { observe, timeoutMs = 120000, pollIntervalMs = 2500 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1200000
+      || !Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 50 || pollIntervalMs > 60000) {
+    throw Object.assign(new Error('timeout_ms 必须是 1–1200000，poll_interval_ms 必须是 50–60000 的整数'), { code: 'IRIS_COMMAND_INPUT_INVALID' });
+  }
+  const dataRoot = await runtime.run('inspect', context => context.dataRoot);
+  let task = inspectCoreTask(dataRoot, taskId);
+  const completed = timedOut => ({ taskId, task, timedOut, ready: task.outcome === 'succeeded' && task.deliveryState === 'ready' });
+  if (coreTaskWaitFinished(task)) return completed(false);
+  if (typeof observe !== 'function') throw Object.assign(new Error('等待远端任务需要 Provider resolver'), { code: 'IRIS_COMMAND_PROVIDER_REQUIRED' });
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; runtime.dispose().catch(() => {}); }, timeoutMs);
+  try {
+    while (!coreTaskWaitFinished(task)) {
+      runtime.signal.throwIfAborted();
+      try { task = (await observe()).task; }
+      catch (error) {
+        if (runtime.signal.aborted) throw error;
+        if (error.code && !['IRIS_PROVIDER_POLL_FAILED', 'IRIS_PROVIDER_DOWNLOAD_FAILED'].includes(error.code)) throw error;
+        task = inspectCoreTask(dataRoot, taskId);
+      }
+      if (!coreTaskWaitFinished(task)) await delay(pollIntervalMs, undefined, { signal: runtime.signal });
+    }
+    return completed(false);
+  } catch (error) {
+    if (!timedOut) throw error;
+    await runtime.dispose();
+    task = inspectCoreTask(dataRoot, taskId);
+    return completed(true);
+  } finally { clearTimeout(timer); }
+}

package/lib/video-input.js

@@ -0,0 +1,30 @@
+'use strict';
+/** 视频输入按候选准备；短期地址和本地路径不落 Task。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { GenerationInputError } from './generation-input.js';
+import { parseModelRef } from './models.js';
+import { prepareProviderInput } from './provider-adapter.js';
+import { ProviderContractError } from './provider-contract.js';
+
+export function videoTaskCandidates(candidates, normalized) {
+  const s2v = normalized.videoMode === 's2v';
+  const compatible = candidates.filter(candidate => /s2v/i.test(parseModelRef(candidate.model)?.modelId || '') === s2v);
+  if (!compatible.length) throw new GenerationInputError(s2v
+    ? 'audio_path 只能配合 s2v 数字人模型' : 's2v 模型需要首帧和音频输入');
+  return compatible.map(candidate => ({ ...candidate,
+    ...(normalized.firstFramePath ? { async prepareInput({ signal }) {
+      if (signal.aborted) throw new ProviderContractError('视频输入准备已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
+      if (s2v) {
+        const model = parseModelRef(candidate.model).modelId;
+        const image = await prepareProviderInput(candidate.adapter, { model, filePath: normalized.firstFramePath, signal });
+        if (signal.aborted) throw new ProviderContractError('视频输入准备已取消', { stage: 'upload', category: 'aborted', acceptance: 'not_accepted' });
+        const audio = await prepareProviderInput(candidate.adapter, { model, filePath: normalized.audioPath, signal });
+        return { ...normalized.providerInput, imgDataUrl: image.url, audioUrl: audio.url };
+      }
+      const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(normalized.firstFramePath).toLowerCase()];
+      if (!mime) throw new ProviderContractError('首帧格式不受支持', { stage: 'prepare', category: 'invalid_request', acceptance: 'not_accepted' });
+      return { ...normalized.providerInput, imgDataUrl: 'data:' + mime + ';base64,' + fs.readFileSync(normalized.firstFramePath).toString('base64') };
+    } } : {})
+  }));
+}

package/lib/vision-core.js

@@ -0,0 +1,42 @@
+'use strict';
+/** 单图业务只消费显式字节和 Model Ports，不读取 Host/配置或保存产物。 */
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelErrorRecord, modelPortSnapshot } from './model-port-contract.js';
+
+export const VISION_BUDGET = Object.freeze({ timeoutMs: 120000, maxInputTextBytes: 32768,
+  maxOutputChars: 6000, maxImageBytes: 20 * 1024 * 1024 });
+export const VISION_CANDIDATE_POLICY = Object.freeze({ skipUnavailable: true, allowRejected: true, allowEmptyResult: true });
+
+export async function completeVision(ports, request, { signal, operation, budget = VISION_BUDGET } = {}) {
+  if (!Array.isArray(ports) || !ports.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  const op = operation || createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: ports.length } });
+  const errors = [];
+  const observed = ports.map(port => {
+    let diagnosed = false;
+    return {
+      describe() {
+        const descriptor = modelPortSnapshot(port);
+        if (!diagnosed && descriptor.availability !== 'available') {
+          errors.push(modelErrorRecord(new ModelPortError(descriptor.reasonCode, { stage: 'prepare', backendId: descriptor.identity.backendId })));
+          diagnosed = true;
+        }
+        return descriptor;
+      },
+      async complete(input, options) {
+        try { return await port.complete(input, options); }
+        catch (error) {
+          errors.push({ ...modelErrorRecord(error), backendId: modelPortSnapshot(port).identity.backendId });
+          throw error;
+        }
+      }
+    };
+  });
+  try {
+    const result = await op.runCandidates(observed, request, { budget }, VISION_CANDIDATE_POLICY);
+    return Object.freeze({ ...result, errors: Object.freeze([...errors]) });
+  } catch (error) {
+    // 受控记录供入口写健康反馈，不包含原始错误/图片/问题。
+    if (error instanceof ModelPortError) error.errors = Object.freeze([...errors]);
+    throw error;
+  } finally { if (!operation) op.dispose(); }
+}

package/lib/vision-image-input.js

@@ -0,0 +1,83 @@
+'use strict';
+/** 视觉发送副本；原始文件和 Core Artifact 始终只读。 */
+import sharp from 'sharp';
+import { ModelPortError } from './model-port-contract.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+// 客户端默认发送预算，不表示任何供应商承诺的输入上限。
+export const DEFAULT_VISION_INPUT = Object.freeze({ maxBytes: 8 * 1024 * 1024 });
+
+export function normalizeVisionInputLimits(value) {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).some(key => !['maxBytes', 'maxDimension'].includes(key))
+      || !Object.values(value).every(number => Number.isSafeInteger(number) && number > 0)) {
+    throw Object.assign(new Error('visionInput 只接受正整数 maxBytes、maxDimension，null 恢复继承'), { code: 'IRIS_CONFIG_INPUT_INVALID' });
+  }
+  return { ...value };
+}
+
+export function visionInputLimits(provider, modelId) {
+  const model = provider.models?.find(value => typeof value === 'object' && value?.id === modelId);
+  return { ...DEFAULT_VISION_INPUT, ...normalizeVisionInputLimits(provider.visionInput),
+    ...normalizeVisionInputLimits(model?.visionInput) };
+}
+
+async function processImage(processor, signal, output) {
+  const cancel = () => processor.destroy();
+  signal?.addEventListener('abort', cancel, { once: true });
+  try { return await waitForModelWork(() => output(processor), signal); }
+  finally { signal?.removeEventListener('abort', cancel); }
+}
+
+export async function prepareVisionImage(image, limits, { signal, orient = false } = {}) {
+  const { maxBytes, maxDimension } = { ...DEFAULT_VISION_INPUT, ...normalizeVisionInputLimits(limits) };
+  if (signal?.aborted) return waitForModelWork(() => image, signal);
+  if (image.bytes.byteLength <= maxBytes && !maxDimension && !orient) return image;
+  const tooLarge = () => new ModelPortError('IRIS_MODEL_IMAGE_TOO_LARGE', {
+    stage: 'prepare', imageBytes: image.bytes.byteLength, imageMaxBytes: maxBytes
+  });
+  const format = { 'image/png': 'png', 'image/jpeg': 'jpeg', 'image/webp': 'webp' }[image.mediaType];
+  let metadata;
+  try { metadata = await processImage(sharp(Buffer.from(image.bytes)), signal, processor => processor.metadata()); }
+  catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new ModelPortError('IRIS_MODEL_INPUT_INVALID', { stage: 'prepare' });
+  }
+  const sourceDimension = Math.max(metadata.width, metadata.height);
+  if (image.bytes.byteLength <= maxBytes && (!maxDimension || sourceDimension <= maxDimension)
+      && (!orient || !metadata.orientation || metadata.orientation === 1)) return image;
+  // 合预算的 GIF/动画仍原字节透传，需要缩放时不静默压成一帧。
+  if (!format || metadata.pages > 1) throw tooLarge();
+  let dimension = Math.min(sourceDimension, maxDimension || sourceDimension);
+  let size = image.bytes.byteLength;
+  // 每次从原字节缩放，不反复压缩上一次副本；只进行本地处理，不重发模型请求。
+  for (let attempt = 0; attempt < 6; attempt++) {
+    if (size > maxBytes) dimension = Math.max(1, Math.min(dimension,
+      Math.floor((attempt === 0 ? sourceDimension : dimension) * Math.min(0.8, Math.sqrt(maxBytes / size) * 0.9))));
+    const processor = sharp(Buffer.from(image.bytes)).autoOrient().resize({ width: dimension, height: dimension,
+      fit: 'inside', withoutEnlargement: true }).toFormat(format);
+    const bytes = await processImage(processor, signal, value => value.toBuffer());
+    if (bytes.byteLength <= maxBytes) return { bytes: new Uint8Array(bytes), mediaType: image.mediaType };
+    size = bytes.byteLength;
+    if (dimension === 1) break;
+  }
+  throw tooLarge();
+}
+
+/** 每次调用的实际图片事实；仅包含尺寸/大小，不包含字节、路径或凭据。 */
+export function createVisionInputObserver(inputs) {
+  return async ({ request, image, signal, identity }) => {
+    const [source, sent] = await waitForModelWork(() => Promise.all([
+      sharp(Buffer.from(request.image.bytes)).metadata(), sharp(Buffer.from(image.bytes)).metadata()
+    ]), signal);
+    const record = {
+      source: { width: source.width, height: source.height, bytes: request.image.bytes.byteLength, mediaType: request.image.mediaType },
+      sent: { width: sent.width, height: sent.height, bytes: image.bytes.byteLength, mediaType: image.mediaType },
+      orientation: source.orientation || 1,
+      resized: (source.autoOrient?.width || source.width) !== sent.width || (source.autoOrient?.height || source.height) !== sent.height
+    };
+    inputs.set(identity.backendId, record);
+    return record;
+  };
+}

package/lib/vision-input.js

@@ -0,0 +1,31 @@
+'use strict';
+/** 单图来源由入口选择；Core 图片以原字节/MIME 只读进入视觉业务。 */
+import { CommandError } from './command-service.js';
+import { inspectCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
+import { MODEL_IMAGE_MEDIA_TYPES } from './model-port-contract.js';
+import { VISION_BUDGET } from './vision-core.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+export function normalizeVisionImageSource(input, { allowAttachment = false } = {}) {
+  const fields = ['image_path', 'artifact_id', ...(allowAttachment ? ['attachment_id'] : [])];
+  const selected = fields.filter(field => input[field] !== undefined);
+  if (selected.length !== 1) throw new CommandError('IRIS_COMMAND_INPUT_INVALID',
+    '必须且只能提供 ' + fields.join('、') + ' 之一');
+  if (selected[0] === 'artifact_id'
+      && (typeof input.artifact_id !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(input.artifact_id))) {
+    throw new CommandError('IRIS_COMMAND_INPUT_INVALID', 'artifact_id 必须是有效的 Core Artifact ID');
+  }
+  return selected[0];
+}
+
+export function readVisionArtifact(runtime, artifactId, signal) {
+  return waitForModelWork(() => runtime.run('inspect', ({ dataRoot }) => {
+    // 先检查大小/MIME，再物化字节；沿用图片输入的 20 MiB 上限。
+    const artifact = inspectCoreArtifact(dataRoot, artifactId);
+    if (!MODEL_IMAGE_MEDIA_TYPES.includes(artifact.mediaType) || artifact.size > VISION_BUDGET.maxImageBytes) {
+      throw new CommandError('IRIS_COMMAND_INPUT_INVALID', '视觉 Artifact 必须是最多 20 MiB 的 PNG、JPEG、WebP 或 GIF 图片');
+    }
+    const { bytes } = readCoreArtifactBytes(dataRoot, artifactId);
+    return { bytes: new Uint8Array(bytes), mediaType: artifact.mediaType };
+  }), signal);
+}