@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/lib/provider-task-runner.js

@@ -0,0 +1,370 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { createCoreArtifact } from './core-artifacts.js';
+import {
+  activateCoreWatch,
+  beginCoreAttempt,
+  beginCoreDelivery,
+  completeCoreDelivery,
+  createCoreTask,
+  failCoreDelivery,
+  finalizeCoreNoAcceptance,
+  inspectCoreTask,
+  prepareCoreRedelivery,
+  recordCoreAttemptResult,
+  recordCoreCancelResult,
+  recordCoreDownloadCompleted,
+  recordCorePollResult,
+  recordCoreWatchError,
+  recoverCoreTask,
+  requestCoreCancel
+} from './core-tasks.js';
+import { ensurePrivateDir } from './private-storage.js';
+import { parseModelRef } from './models.js';
+import {
+  hasProviderOperation,
+  invokeProviderOperation
+} from './provider-adapter.js';
+import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
+
+export const PROVIDER_TASK_RUNNER_VERSION = 0;
+
+/**
+ * 按 capability 冻结的交付 Profile（E 阶段视频迁移）：媒体类型白名单、Artifact
+ * kind 与默认 metadata。新增 capability 必须显式登记；未登记的 capability 直接
+ * 失败，不会按图片语义猜。
+ */
+export const DELIVERY_PROFILES = Object.freeze({
+  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' }),
+  // 转写上传型异步：受理 + remoteTaskId → 长轮询 → 文本物化为 UTF-8 Artifact。
+  transcribe: Object.freeze({ kind: 'transcript', mediaTypes: Object.freeze(['text/plain']), defaultMediaType: 'text/plain' })
+});
+const runtimeTaskGates = new WeakMap();
+
+export class ProviderTaskRunnerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProviderTaskRunnerError';
+    this.code = code;
+  }
+}
+
+function checkRuntime(runtime) {
+  if (!runtime || typeof runtime.run !== 'function') {
+    throw new TypeError('Provider Task Runner 需要已创建的 Core Runtime');
+  }
+}
+
+function checkAdapterForTask(task, adapter) {
+  if (!adapter || adapter.id !== task.providerId) {
+    throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Provider Adapter 与 Task 已持久化身份不一致');
+  }
+  return adapter;
+}
+
+function normalizedCandidates(capability, candidates) {
+  if (!Array.isArray(candidates) || !candidates.length) throw new TypeError('至少需要一个 Provider 候选');
+  return candidates.map((candidate, index) => {
+    const adapter = candidate?.adapter;
+    const model = String(candidate?.model || '').trim();
+    const parsed = parseModelRef(model);
+    const selectionReason = candidate?.selectionReason;
+    if (!adapter || !adapter.capabilities?.includes(capability) || !parsed
+        || parsed.providerId !== adapter.id || !parsed.modelId
+        || (candidate.providerBinding !== undefined && !/^sha256:[a-f0-9]{64}$/.test(candidate.providerBinding))
+        || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))) {
+      throw new TypeError('Provider 候选 ' + (index + 1) + ' 不支持 Task capability 或模型复合身份无效');
+    }
+    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 };
+  });
+}
+
+function stagingFile(dataRoot) {
+  const directory = path.join(dataRoot, 'provider-staging', 'v0');
+  ensurePrivateDir(directory);
+  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 = [];
+  const stagedFiles = [];
+  try {
+    if (!Array.isArray(remoteArtifacts) || remoteArtifacts.length === 0) {
+      throw Object.assign(new Error('Provider Task Runner 没有收到可物化产物'), {
+        stage: 'download', category: 'protocol', acceptance: 'accepted'
+      });
+    }
+    const task = inspectCoreTask(dataRoot, taskId);
+    const profile = DELIVERY_PROFILES[task.capability];
+    if (!profile) {
+      throw Object.assign(new Error('Provider Task Runner 没有该 capability 的交付 Profile：' + task.capability), {
+        stage: 'download', category: 'protocol', acceptance: 'accepted'
+      });
+    }
+    for (const remote of remoteArtifacts) {
+      const mediaType = String(remote.mediaType || profile.defaultMediaType);
+      if (task.capability !== 'image' && !profile.mediaTypes.includes(mediaType)) {
+        throw Object.assign(new Error('Provider Task Runner 交付媒体类型不在 Profile 白名单：' + mediaType), {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      const target = stagingFile(dataRoot);
+      stagedFiles.push({ target, mediaType });
+      const downloaded = await invokeProviderOperation(adapter, 'download', {
+        capability: task.capability,
+        artifact: remote,
+        targetPath: target,
+        signal
+      }, { signal, taskId });
+      const stat = fs.lstatSync(target);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== downloaded.bytes) {
+        throw Object.assign(new Error('Provider 物化结果与文件证据不一致'), {
+          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, {
+        kind: profile.kind,
+        mediaType: staged.mediaType,
+        bytes: staged.bytes || fs.readFileSync(staged.target),
+        metadata: { taskId, capability: task.capability },
+        ...(task.sourceArtifactId ? { relations: [{ type: 'derived-from', artifactId: task.sourceArtifactId }] } : {})
+      });
+      artifactIds.push(artifact.id);
+    }
+    return completeCoreDelivery(dataRoot, taskId, artifactIds);
+  } catch (error) {
+    return failCoreDelivery(dataRoot, taskId, error);
+  } finally {
+    for (const staged of stagedFiles) {
+      try { fs.rmSync(staged.target, { force: true }); } catch (_) { /* 后续显式清理可处理残留 */ }
+    }
+  }
+}
+
+async function observeWithinRoot(dataRoot, taskId, adapter, signal) {
+  const before = inspectCoreTask(dataRoot, taskId);
+  checkAdapterForTask(before, adapter);
+  activateCoreWatch(dataRoot, taskId);
+  let result;
+  try {
+    result = await invokeProviderOperation(adapter, 'poll', {
+      capability: before.capability,
+      remoteTaskId: before.remoteTaskId,
+      signal
+    }, { signal, taskId });
+  } catch (error) {
+    return recordCoreWatchError(dataRoot, taskId, error);
+  }
+  const recorded = recordCorePollResult(dataRoot, taskId, result);
+  if (result.kind !== 'succeeded') return recorded;
+  return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+}
+
+/**
+ * FakeProvider 与未来真实 Host 共用的生命周期调度候选。它不拥有 timer，也不会
+ * 自动循环轮询；每次 observe 只消费一个 poll 结果，使重启和故障边界可重复验证。
+ */
+export function createProviderTaskRunner(runtime) {
+  checkRuntime(runtime);
+  let activeTasks = runtimeTaskGates.get(runtime);
+  if (!activeTasks) {
+    activeTasks = new Set();
+    runtimeTaskGates.set(runtime, activeTasks);
+  }
+
+  async function runExclusive(taskId, operation, callback) {
+    const key = String(taskId || '');
+    if (activeTasks.has(key)) {
+      throw new ProviderTaskRunnerError(
+        'IRIS_PROVIDER_TASK_BUSY',
+        '该 Task 已有生命周期操作正在执行'
+      );
+    }
+    activeTasks.add(key);
+    try {
+      return await runtime.run(operation, callback);
+    } finally {
+      activeTasks.delete(key);
+    }
+  }
+
+  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();
+      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: 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, providerInput, {
+        signal,
+        beforeAttempt: async (attempt) => {
+          const candidate = candidates[attempt.ordinal - 1];
+          return beginCoreAttempt(dataRoot, task.id, {
+            ...attempt,
+            ...(candidate.providerBinding !== undefined ? { providerBinding: candidate.providerBinding } : {}),
+            ...(candidate.selectionReason !== undefined ? { selectionReason: candidate.selectionReason } : {})
+          });
+        },
+        afterResult: async (attempt) => recordCoreAttemptResult(dataRoot, task.id, attempt)
+      });
+      if (submitted.localError) {
+        return Object.freeze({ taskId: task.id, task: inspectCoreTask(dataRoot, task.id), localError: submitted.localError });
+      }
+      if (!submitted.result) throw new Error('Provider 提交流程没有返回结果');
+      if (submitted.result.kind === 'not_accepted') {
+        finalizeCoreNoAcceptance(dataRoot, task.id, submitted.result.error);
+      } else if (submitted.result.kind === 'completed') {
+        const artifacts = submitted.result.artifacts;
+        return Object.freeze({
+          taskId: task.id,
+          task: await deliverArtifacts(dataRoot, task.id, submitted.candidate.adapter, artifacts, signal),
+          attempts: submitted.attempts
+        });
+      }
+      return Object.freeze({
+        taskId: task.id,
+        task: inspectCoreTask(dataRoot, task.id),
+        attempts: submitted.attempts
+      });
+    });
+  }
+
+  function inspect(taskId) {
+    return runtime.run('inspect', ({ dataRoot }) => inspectCoreTask(dataRoot, taskId));
+  }
+
+  function observe(taskId, adapter, { resumeActive = false } = {}) {
+    return runExclusive(taskId, 'execute', ({ dataRoot, signal }) => {
+      if (resumeActive) {
+        const current = inspectCoreTask(dataRoot, taskId);
+        checkAdapterForTask(current, adapter);
+        if (current.watchState === 'active') recoverCoreTask(dataRoot, taskId);
+      }
+      return observeWithinRoot(dataRoot, taskId, adapter, signal);
+    });
+  }
+
+  function redeliver(taskId, adapter) {
+    return runExclusive(taskId, 'execute', async ({ dataRoot, signal }) => {
+      const task = inspectCoreTask(dataRoot, taskId);
+      checkAdapterForTask(task, adapter);
+      prepareCoreRedelivery(dataRoot, taskId);
+      let result;
+      try {
+        result = await invokeProviderOperation(adapter, 'poll', {
+          capability: task.capability,
+          remoteTaskId: task.remoteTaskId,
+          signal
+        }, { signal, taskId, redelivery: true });
+      } catch (error) {
+        return failCoreDelivery(dataRoot, taskId, error);
+      }
+      if (result.kind !== 'succeeded') {
+        return failCoreDelivery(dataRoot, taskId, providerErrorRecord(
+          result.error || '重新查询没有得到可交付产物',
+          { stage: 'download', category: 'protocol', acceptance: 'accepted' }
+        ));
+      }
+      return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
+    });
+  }
+
+  function cancel(taskId, adapter) {
+    return runExclusive(taskId, 'execute', async ({ dataRoot, signal }) => {
+      const task = inspectCoreTask(dataRoot, taskId);
+      checkAdapterForTask(task, adapter);
+      requestCoreCancel(dataRoot, taskId);
+      if (!hasProviderOperation(adapter, 'cancel')) {
+        return recordCoreCancelResult(dataRoot, taskId, { kind: 'not_supported' });
+      }
+      const result = await invokeProviderOperation(adapter, 'cancel', {
+        capability: task.capability,
+        remoteTaskId: task.remoteTaskId,
+        signal
+      }, { signal, taskId });
+      return recordCoreCancelResult(dataRoot, taskId, result);
+    });
+  }
+
+  function recover(taskId, adapter) {
+    return runExclusive(taskId, 'recover', async ({ dataRoot, signal }) => {
+      const recovered = recoverCoreTask(dataRoot, taskId);
+      if (recovered.acceptance === 'accepted' && recovered.remoteTaskId
+          && recovered.outcome === 'none'
+          && ['accepted', 'running'].includes(recovered.phase)) {
+        checkAdapterForTask(recovered, adapter);
+        return observeWithinRoot(dataRoot, taskId, adapter, signal);
+      }
+      return recovered;
+    });
+  }
+
+  return Object.freeze({
+    version: PROVIDER_TASK_RUNNER_VERSION,
+    submit,
+    inspect,
+    observe,
+    redeliver,
+    cancel,
+    recover
+  });
+}

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/tasks.js

@@ -455,15 +455,25 @@ export function all() {
   return [...load().tasks].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
 }
 
+/** 终态或已显式处理提醒的 Task v2 可删；活跃/未处理任务仍受保护。 */
+export function taskRecordRemovable(task) {
+  if (!task) return false;
+  if (task.status !== 'running') return true;
+  return isV2Task(task)
+    && ATTENTION_USER_STATES.has(deriveUserState(task))
+    && attentionDisposition(task).status === 'acknowledged';
+}
+
 /**
- * 删除单条任务元数据（仅终态；运行中须先 cancel）。
+ * 删除单条任务元数据。事实终态可直接删除；状态未知只有在用户已读/已重试归档后才可删除。
  * 只删记录，产物文件留在 outputs/（媒体链接因 token 随记录消失而自然失效）。
  * @returns {{ok:boolean, reason?:string}}
  */
 export function remove(id) {
   const t = get(id);
   if (!t) return { ok: false, reason: '任务不存在' };
-  if (t.status === 'running') return { ok: false, reason: '运行中任务请先取消再删除' };
+  if (!taskRecordRemovable(t)) return { ok: false, reason: '活跃或待确认任务请先取消、完成提醒处置，或标为已读后再删除' };
+  stopWatch(id);
   const arr = load().tasks;
   const i = arr.findIndex((x) => x.id === id);
   if (i >= 0) arr.splice(i, 1);
@@ -481,8 +491,10 @@ export function prune(pred) {
   const removed = [];
   const kept = [];
   for (const t of arr) {
-    if (t.status !== 'running' && pred(t)) removed.push(t.id);
-    else kept.push(t);
+    if (taskRecordRemovable(t) && pred(t)) {
+      stopWatch(t.id);
+      removed.push(t.id);
+    } else kept.push(t);
   }
   if (removed.length) {
     load().tasks = kept;

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') };
+    } } : {})
+  }));
+}