@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/lib/dsh-host-adapter.js

@@ -41,6 +41,24 @@ function unavailableFor(value, reason) {
   return { kind: value ? 'incompatible' : 'unavailable', reason };
 }
 
+function imageAttachmentDto(ref) {
+  const out = {
+    attachmentId: ref.attachmentId,
+    mediaType: ref.mediaType,
+    name: typeof ref.name === 'string' ? ref.name : ''
+  };
+  // readImage 会核对这三项完整性事实；省略未知值，不从 ID/文件名猜测。
+  for (const key of ['bytes', 'width', 'height']) {
+    if (Number.isSafeInteger(ref[key]) && ref[key] > 0) out[key] = ref[key];
+  }
+  const original = ref.originalDimensions;
+  if (original && Number.isSafeInteger(original.width) && original.width > 0
+      && Number.isSafeInteger(original.height) && original.height > 0) {
+    out.originalDimensions = Object.freeze({ width: original.width, height: original.height });
+  }
+  return Object.freeze(out);
+}
+
 function collectImageAttachments(nodes) {
   const out = [];
   const ids = new Set();
@@ -59,11 +77,7 @@ function collectImageAttachments(nodes) {
         && typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/')
         && !ids.has(ref.attachmentId)) {
       ids.add(ref.attachmentId);
-      out.push(Object.freeze({
-        attachmentId: ref.attachmentId,
-        mediaType: ref.mediaType,
-        name: typeof ref.name === 'string' ? ref.name : ''
-      }));
+      out.push(imageAttachmentDto(ref));
     }
     for (const value of Object.values(node)) if (value && typeof value === 'object') stack.push(value);
   }
@@ -75,16 +89,41 @@ function registerWithEffect(ctx, registry, definition) {
   return registry.register(definition);
 }
 
-function dshVisionPort(llm) {
+function visionRouteError(message) {
+  return Object.assign(new Error(message), { code: 'IRIS_HOST_CAPABILITY_INCOMPATIBLE' });
+}
+
+function dshVisionPort(llm, { defaults, requiresRoute }) {
   return Object.freeze({
     id: 'dsh-global',
     model: '全局视觉模型',
     async analyze({ question, ref, signal }) {
+      let route = {};
+      if (requiresRoute) {
+        // rc.2 路由检查前就停止取消请求；旧桥接继续由宿主处理 signal，
+        // 其 fallback 语义待共享调用控制迁移时统一。
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        const selection = defaults.currentSelection();
+        if (typeof selection?.provider !== 'string' || !selection.provider.trim()
+            || typeof selection?.model !== 'string' || !selection.model.trim()) {
+          throw visionRouteError('DSH 默认模型没有明确路由；请在 Iris 配置视觉模型');
+        }
+        // 默认文本选择只有明确声明 image 输入时才可成为视觉候选。
+        const { provider, model } = selection;
+        const info = await llm.resolveModelInfo(provider, model, signal);
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        if (info?.provider !== provider || info?.id !== model || !Array.isArray(info.inputModalities)
+            || !info.inputModalities.includes('image')) {
+          throw visionRouteError('DSH 默认模型未确认支持图片；请在 Iris 配置视觉模型或选择已声明图片输入的宿主模型');
+        }
+        route = { provider, model };
+      }
       const chunks = [];
       for await (const chunk of llm.stream({
         sessionId: undefined,
         provider: undefined,
         model: undefined,
+        ...route,
         signal,
         messages: [{
           role: 'user',
@@ -94,6 +133,12 @@ function dshVisionPort(llm) {
           ]
         }]
       })) {
+        if (chunk?.type === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+        // rc.2 的 Runtime 把 Adapter 异常转换为 finish，而不是单独的 error 事件。
+        if (requiresRoute && chunk?.type === 'finish') {
+          if (chunk.reason?.kind === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+          if (chunk.reason?.kind === 'aborted') throw visionRouteError('DSH 视觉调用已取消');
+        }
         const text = typeof chunk?.delta === 'string'
           ? chunk.delta
           : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
@@ -174,7 +219,13 @@ export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {})
         ? () => defaults.currentSelection()
         : () => null
     });
-    ports.visionModel = dshVisionPort(llm);
+    const requiresRoute = /^0\.2\./.test(version);
+    if (!requiresRoute || defaults && typeof defaults.currentSelection === 'function'
+        && typeof llm.resolveModelInfo === 'function') {
+      ports.visionModel = dshVisionPort(llm, { defaults, requiresRoute });
+    } else unavailable.visionModel = {
+      kind: 'unavailable', reason: 'DSH 0.2 视觉桥接需要默认模型选择和精确图片能力元数据'
+    };
   } else {
     unavailable.textModel = unavailableFor(llm, 'DSH llm 需要 stream');
     unavailable.visionModel = unavailableFor(llm, 'DSH llm 需要 stream');

package/lib/generation-input.js

@@ -0,0 +1,95 @@
+'use strict';
+
+import path from 'node:path';
+
+const FIELDS = Object.freeze({
+  image: ['prompt', 'size', 'n'],
+  video: ['prompt', 'size', 'duration', 'img_data_url'],
+  tts: ['text', 'voice'],
+  transcribe: ['audio_url', 'audio_path']
+});
+
+export class GenerationInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GenerationInputError';
+    this.code = 'IRIS_GENERATION_INPUT_INVALID';
+  }
+}
+
+function fail(message) { throw new GenerationInputError(message); }
+
+function text(value, field, maxLength, required = false) {
+  if (value === undefined && !required) return undefined;
+  const normalized = String(value || '').trim();
+  if (!normalized || normalized.length > maxLength) {
+    fail(`${field} 必须为 1–${maxLength} 字符`);
+  }
+  return normalized;
+}
+
+/**
+ * CLI、DSH 与知情重试共用的纯输入边界。只校验/转换调用方重新提供的参数，
+ * 不读取配置或文件，不上传，不从旧 Task 恢复 Prompt/媒体地址。
+ * Host 附件解析和本地音频上传仍由入口负责。
+ */
+export function normalizeGenerationInput(capability, input, { allowAudioPath = false } = {}) {
+  const fields = Object.hasOwn(FIELDS, capability) ? FIELDS[capability] : null;
+  if (!fields) fail('不支持的生成能力');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('生成输入必须是 JSON 对象');
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field) && field !== 'model_ref') {
+      fail('生成输入不支持字段：' + field + '；允许 ' + fields.join(', ') + ', model_ref');
+    }
+  }
+  const modelRef = String(input.model_ref || '').trim();
+  const providerInput = {};
+  let audioPath;
+  if (capability === 'image' || capability === 'video') {
+    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    const size = text(input.size, 'size', 64);
+    if (size !== undefined) providerInput.size = size;
+  }
+  if (capability === 'image') {
+    const n = input.n === undefined ? 1 : Number(input.n);
+    if (!Number.isSafeInteger(n) || n < 1 || n > 4) fail('n 必须为 1–4 的整数');
+    providerInput.n = n;
+  }
+  if (capability === 'video') {
+    if (input.duration !== undefined) {
+      const duration = Number(input.duration);
+      if (!Number.isFinite(duration) || duration < 1 || duration > 60) fail('duration 必须为 1–60 的数字');
+      providerInput.duration = duration;
+    }
+    if (input.img_data_url !== undefined) {
+      const imgDataUrl = String(input.img_data_url).trim();
+      if (!imgDataUrl.startsWith('data:image/')) fail('img_data_url 必须是 data:image/ 开头的 data URL');
+      providerInput.imgDataUrl = imgDataUrl;
+    }
+  }
+  if (capability === 'tts') {
+    providerInput.text = text(input.text, 'text', 20000, true);
+    const voice = text(input.voice, 'voice', 64);
+    if (voice !== undefined) providerInput.voice = voice;
+  }
+  if (capability === 'transcribe') {
+    const audioUrl = String(input.audio_url || '').trim();
+    audioPath = String(input.audio_path || '').trim();
+    if (Boolean(audioUrl) === Boolean(audioPath)) {
+      fail('转写必须且只能提供 audio_url（公网/oss://）或 audio_path（本地绝对路径）之一');
+    }
+    if (audioUrl) {
+      if (audioUrl.length > 20000) fail('audio_url 最多为 20000 字符');
+      if (!/^(https:\/\/|oss:\/\/)/.test(audioUrl)) fail('audio_url 必须是 https:// 或 oss:// 地址');
+      providerInput.audioUrl = audioUrl;
+    } else {
+      if (!allowAudioPath) fail('retry 必须重新提供 audio_url；本地音频上传由调用入口负责');
+      if (!path.isAbsolute(audioPath)) fail('audio_path 必须是绝对路径');
+    }
+  }
+  return Object.freeze({
+    modelRef,
+    providerInput: Object.freeze(providerInput),
+    ...(audioPath ? { audioPath } : {})
+  });
+}

package/lib/guard.js

@@ -4,7 +4,7 @@
  *
  * `/iris/*` 不经过 DSH 的 `/api` 信任栅栏，因此默认只接受回环 Host。
  * LAN/反代场景需用 IRIS_TRUSTED_HOSTS 显式列出 host 或 host:port；这只是
- * Host 边界，不是身份认证。POST 另外校验 Sec-Fetch-Site 与 Origin==Host。
+ * Host 边界，不是身份认证。浏览器请求另校验 Sec-Fetch-Site 与 Origin==Host。
  */
 
 /** 请求 Host 头 → host:port 规范化（小写，去 IPv6 方括号保留） */
@@ -44,12 +44,12 @@ export function isTrustedHost(hostHeader, configured = process.env.IRIS_TRUSTED_
  */
 export function checkRequest(req, options = {}) {
   const headers = req.headers || {};
-  const method = String(req.method || 'GET').toUpperCase();
   if (!isTrustedHost(headers.host, options.trustedHosts)) {
     return { ok: false, status: 403, error: 'untrusted host' };
   }
-  if (method !== 'POST') return { ok: true };
 
+  // 浏览器的读请求同样可能泄露媒体与状态；明确的跨站/跨源请求一律拒绝。
+  // curl/CLI 等不发送 Origin/Sec-Fetch-Site 的非浏览器客户端仍可在受信 Host 上使用。
   const sfs = String(headers['sec-fetch-site'] || '').toLowerCase();
   if (sfs === 'cross-site') return { ok: false, status: 403, error: 'cross-site request denied' };
 

package/lib/index.js

@@ -17,7 +17,8 @@ import { serveApi, closeAllSse, purgeStaleUploads } from './api.js';
 import { buildVisionBackendsFromHost, askWithBackends } from './vision.js';
 import { hasHostPort, requireHostPort } from './host-contract.js';
 import { createDshHostAdapter } from './dsh-host-adapter.js';
-import { cropImage, pixelDiff, imageDimensions } from './pixels.js';
+import { cropForDsh, diffForDsh, framesForDsh, inspectProviderTaskForDsh, projectCoreTaskForDsh, readCoreArtifactMediaForDsh, resumeProviderTaskWatchesForDsh, stopProviderTaskWatchesForDsh } from './dsh-core-adapter.js';
+import { imageDimensions } from './pixels.js';
 import { locateObject } from './locate.js';
 import { serveRender } from './render.js';
 import { ensurePrivateDir, hardenPrivateTree } from './private-storage.js';
@@ -51,7 +52,7 @@ function dshHost(ctx) {
 }
 
 /** 工具内同步等待上限；超过即转后台盯守，用 iris_task_status 查询 */
-const AWAIT_MS = { image: 180000, video: 480000 };
+const AWAIT_MS = { image: 180000, video: 480000, transcribe: 120000 };
 
 function outputDir() {
   const dir = tasks.outputsDir();
@@ -153,6 +154,39 @@ async function awaitTerminal(taskId, { timeoutMs, signal }) {
   }
 }
 
+function coreTaskWaitFinished(task) {
+  return Boolean(task && (task.phase === 'terminal'
+    || (task.outcome === 'succeeded' && ['ready', 'failed'].includes(task.deliveryState))));
+}
+
+function coreTaskTerminalProblem(task, label = '任务') {
+  if (!task) return label + '记录不存在';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return '';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'failed') {
+    return label + '已成功，但 Core Artifact 交付失败：'
+      + (task.lastError?.safeMessage || '可稍后重新交付；禁止重新生成');
+  }
+  if (task.acceptance === 'unknown' || task.outcome === 'unknown') {
+    return label + '的远端受理或结果状态未知：'
+      + (task.lastError?.safeMessage || '禁止自动重提，请先人工确认');
+  }
+  if (task.outcome === 'canceled') return label + '已取消';
+  if (task.outcome === 'failed') return label + '失败：'
+    + (task.lastError?.safeMessage || '供应商明确返回失败');
+  return label + '需要人工处理';
+}
+
+async function awaitCoreTerminal(taskId, { timeoutMs, signal }) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (signal?.aborted) throw new Error('已取消；Core 任务仍保留远端受理事实，可稍后查询');
+    const task = await inspectProviderTaskForDsh(taskId, { signal });
+    if (coreTaskWaitFinished(task)) return task;
+    if (Date.now() > deadline) return null;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+}
+
 /* ---------------- 图片 data URL（视觉工具共用） ---------------- */
 
 function toDataUrl(absPath, mediaType) {
@@ -160,17 +194,6 @@ function toDataUrl(absPath, mediaType) {
   return `data:${mediaType};base64,${buf.toString('base64')}`;
 }
 
-function fmtTask(t) {
-  const lines = [`[${t.cap}] ${t.id} · ${t.status}${t.progress ? ' · ' + t.progress : ''} · ${t.model}`];
-  lines.push('prompt: ' + String(t.prompt || '').slice(0, 120));
-  if (t.error) lines.push('error: ' + t.error);
-  if ((t.files || []).length) lines.push('files:\n' + t.files.map((f) => path.join(tasks.outputsDir(), f)).join('\n'));
-  const links = mediaLinksOf(t);
-  if (links.length) lines.push('links:\n' + links.join('\n'));
-  if (t.remoteTaskId) lines.push('remoteTask: ' + t.remoteTaskId);
-  return lines.join('\n');
-}
-
 export const name = 'mokuyoaxis-dsh-iris';
 export const inject = ['tools'];
 
@@ -223,9 +246,19 @@ export async function apply(ctx) {
     if (resumed.length) console.log(`[iris] 已恢复接管 ${resumed.length} 个后台任务`);
   });
 
-  // Fiber 清理：插件停用/更新时停掉全部盯守句柄
+  try {
+    const resumed = await resumeProviderTaskWatchesForDsh();
+    if (resumed.length) console.log(`[iris] 已恢复接管 ${resumed.length} 个 Core 图片任务`);
+  } catch (error) {
+    console.error('[iris] 恢复 Core 图片后台任务失败（已隔离，不影响宿主）:', error?.message || error);
+  }
+
+  // Fiber 清理：插件停用/更新时停掉 legacy 与 Core 的全部 Host 盯守句柄
   guard('盯守句柄注册', () => {
-    ctx.effect(() => () => tasks.stopWatchAll());
+    ctx.effect(() => () => {
+      tasks.stopWatchAll();
+      stopProviderTaskWatchesForDsh();
+    });
   });
 
   // 媒体路由（视频/音频在对话流里的可播通路；图片仍走原生附件）
@@ -273,8 +306,35 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       const prompt = String(args.prompt || '').trim();
-      if (!prompt) throw new Error('iris: prompt 不能为空');
       const submitted = await runAction(dshHost(ctx), 'image', args, { signal: exec.signal });
+      if (submitted.storage === 'core') {
+        let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
+        if (!coreTaskWaitFinished(final)) {
+          final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
+        }
+        if (!final) {
+          return { blocks: [{ type: 'text', text: `[iris] Core 图片任务仍在后台观察（task: ${submitted.taskId}）。稍后可用 iris_task_status 查询进度与 Artifact。` }] };
+        }
+        const terminalProblem = coreTaskTerminalProblem(final, '图像生成');
+        if (terminalProblem) throw new Error(terminalProblem);
+        const projected = await projectCoreTaskForDsh(dshHost(ctx), submitted.taskId, { signal: exec.signal });
+        const refs = projected.artifacts.map((item) => item.attachment);
+        const blocks = projected.artifacts.map((item) => ({ type: 'image', attachment: item.attachment }));
+        let note = '';
+        try {
+          const first = await readCoreArtifactMediaForDsh(projected.artifacts[0].artifact.id, { signal: exec.signal });
+          const described = await describeImageData(dshHost(ctx), refs[0],
+            `data:${first.artifact.mediaType};base64,${first.bytes.toString('base64')}`, prompt);
+          if (described) note = `画面内容：${described}`;
+        } catch (_) { /* 自述是增强项，失败不影响 Core 交付 */ }
+        blocks.unshift({ type: 'text', text:
+          `[iris] 图像已生成（${submitted.model}，Core task: ${submitted.taskId}）。` +
+          (note ? `\n${note}` : '') +
+          `\nartifact: ${projected.artifacts.map((item) => item.artifact.id).join(', ')}` +
+          `\nattachment: ${refs.map((ref) => ref.attachmentId).join(', ')}`
+        });
+        return { blocks };
+      }
       let final = tasks.get(submitted.taskId);
       if (final && !taskWaitFinished(final)) {
         final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
@@ -344,6 +404,25 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       const submitted = await runAction(dshHost(ctx), 'video', args, { signal: exec.signal });
+      if (submitted.storage === 'core') {
+        let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
+        if (!coreTaskWaitFinished(final)) {
+          final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.video, signal: exec.signal });
+        }
+        if (!final) {
+          return `[iris] Core 视频任务已提交并转入后台观察（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
+            '渲染通常需要数分钟；完成后用 iris_task_status 查询进度与 Artifact，或在工作台「重新观察」。';
+        }
+        const terminalProblem = coreTaskTerminalProblem(final, '视频生成');
+        if (terminalProblem) throw new Error(terminalProblem);
+        const secs = Math.round((Date.now() - new Date(final.createdAt).getTime()) / 1000);
+        const links = final.artifactIds.map((artifactId) =>
+          '/iris/api/core/artifact/' + encodeURIComponent(artifactId) + '/media');
+        return `[iris] 视频已生成（${submitted.model || final.modelRef}，${submitted.mode || 't2v'}，约 ${secs}s，Core task: ${final.id}）：\n` +
+          `artifact: ${final.artifactIds.join(', ')}\n` +
+          links.join('\n') +
+          '\n（链接受 DSH Host 与浏览器同源守卫保护；Artifact ID 持有者可访问，请勿公开）';
+      }
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.video, signal: exec.signal });
       if (!final) {
         return `[iris] 视频任务已提交并转入后台盯守（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
@@ -378,6 +457,16 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       const submitted = await runAction(dshHost(ctx), 'tts', args, { signal: exec.signal });
+      if (submitted.storage === 'core') {
+        const final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
+        const terminalProblem = coreTaskTerminalProblem(final, '语音合成');
+        if (terminalProblem) throw new Error(terminalProblem);
+        const links = final.artifactIds.map((artifactId) =>
+          '/iris/api/core/artifact/' + encodeURIComponent(artifactId) + '/media');
+        return `[iris] 语音已合成（${submitted.model || final.modelRef}，Core task: ${final.id}）：\n` +
+          `artifact: ${final.artifactIds.join(', ')}\n` +
+          links.map((link) => `[♪ 音频播放](${link})`).join('\n');
+      }
       const final = tasks.get(submitted.taskId);
       const terminalProblem = taskTerminalProblem(final, '语音合成');
       if (terminalProblem) throw new Error(terminalProblem);
@@ -405,6 +494,25 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       const submitted = await runAction(dshHost(ctx), 'transcribe', args, { signal: exec.signal });
+      if (submitted.storage === 'core') {
+        let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
+        if (!coreTaskWaitFinished(final)) {
+          final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.transcribe, signal: exec.signal });
+        }
+        if (!final) {
+          return `[iris] Core 转写任务已提交并转入后台观察（task: ${submitted.taskId}）。完成后用 iris_task_status 查询进度与 Artifact。`;
+        }
+        const terminalProblem = coreTaskTerminalProblem(final, '音频转写');
+        if (terminalProblem) throw new Error(terminalProblem);
+        const texts = [];
+        for (const artifactId of final.artifactIds) {
+          const media = await readCoreArtifactMediaForDsh(artifactId, { signal: exec.signal });
+          texts.push(Buffer.from(media.bytes).toString('utf8'));
+        }
+        return `[iris] 音频转写完成（${submitted.model || final.modelRef}，Core task: ${final.id}）：\n` +
+          texts.join('\n') +
+          `\nartifact: ${final.artifactIds.join(', ')}`;
+      }
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: 120000, signal: exec.signal });
       if (!final) return `[iris] 音频转写任务已提交并转入后台（task: ${submitted.taskId}）。完成后用 iris_task_status 查询。`;
       const terminalProblem = taskTerminalProblem(final, '音频转写');
@@ -435,26 +543,22 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const p = String(args.video_path || '').trim();
-      if (!p || !path.isAbsolute(p)) throw new Error('iris: video_path 必须是绝对路径');
-      if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法抽帧（可选安装 ffmpeg/ffprobe 后启用；不影响其他 iris 工具）');
-      const meta = probeVideo(p);
-      const frames = await extractFrames({
-        inputPath: p,
+      const { media: meta, frames } = await framesForDsh({
+        videoPath: args.video_path,
         maxFrames: args.max_frames,
         targetWidth: args.target_width,
         format: args.format,
         quality: args.quality,
         signal: exec.signal
       });
-      const mediaType = args.format === 'png' ? 'image/png' : 'image/jpeg';
-      const ext = args.format === 'png' ? 'png' : 'jpg';
+      const mediaType = frames[0].mediaType;
+      const ext = mediaType === 'image/png' ? 'png' : 'jpg';
       const blocks = [];
       const refs = [];
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
         const ref = await attachmentService(host).saveImage({
-          data: new Uint8Array(f.buffer),
+          data: new Uint8Array(f.bytes),
           mediaType,
           name: `iris-frame-${Date.now()}-${i + 1}.${ext}`
         });
@@ -470,7 +574,7 @@ export async function apply(ctx) {
           `时间戳：${ats}\n` +
           `attachments: ${refs.map((r) => r.attachmentId).join(', ')}`
       });
-      return { blocks };
+      return { blocks, artifactIds: frames.map((frame) => frame.artifact.id) };
     }
   });
 
@@ -648,14 +752,8 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args) {
-      if (args.task_id) {
-        const t = tasks.get(String(args.task_id).trim());
-        if (!t) throw new Error('iris: 没有这个任务：' + args.task_id);
-        return fmtTask(t);
-      }
-      const recent = tasks.list().slice(0, 5);
-      if (!recent.length) return '[iris] 还没有生成任务记录。';
-      return recent.map(fmtTask).join('\n---\n');
+      const result = await runAction(dshHost(ctx), 'status', args || {});
+      return result.text;
     }
   });
 
@@ -685,21 +783,25 @@ export async function apply(ctx) {
         image_path: args.image_path,
         attachment_id: args.attachment_id
       });
-      const { buffer, width, height, mime } = await cropImage({
-        input: input.buffer,
+      const result = await cropForDsh({
+        ...(args.image_path
+          ? { imagePath: String(args.image_path).trim() }
+          : { bytes: input.buffer, mediaType: input.mediaType }),
         left: args.left,
         top: args.top,
         width: args.width,
-        height: args.height
+        height: args.height,
+        signal: exec.signal
       });
+      if (exec.signal && exec.signal.aborted) throw new Error('已取消');
       const ref = await attachmentService(host).saveImage({
-        data: new Uint8Array(buffer),
-        mediaType: mime,
+        data: new Uint8Array(result.bytes),
+        mediaType: result.mediaType,
         name: `iris-crop-${Date.now()}.png`
       });
       return {
         blocks: [
-          { type: 'text', text: `[iris] 裁剪完成：${width}x${height}（原区域 ${args.left},${args.top},${args.width},${args.height}）\nattachment: ${ref.attachmentId}` },
+          { type: 'text', text: `[iris] 裁剪完成：${result.width}x${result.height}（原区域 ${args.left},${args.top},${args.width},${args.height}）\nattachment: ${ref.attachmentId}` },
           { type: 'image', attachment: ref }
         ]
       };
@@ -732,20 +834,21 @@ export async function apply(ctx) {
       if (!(args.image_b_path || args.attachment_b_id)) throw new Error('iris: 需要 image_b_path 或 attachment_b_id');
       const a = await resolveImageInput(dshHost(ctx), exec, { image_path: args.image_a_path, attachment_id: args.attachment_a_id });
       const b = await resolveImageInput(dshHost(ctx), exec, { image_path: args.image_b_path, attachment_id: args.attachment_b_id });
-      const { ratio, diffPixels, totalPixels, width, height, worstRegions, heatmap, mime } = await pixelDiff({
-        inputA: a.buffer,
-        inputB: b.buffer,
-        grid: args.grid || 8,
-        topRegions: args.top_regions || 3
+      const result = await diffForDsh({
+        imageA: { bytes: a.buffer, mediaType: a.mediaType },
+        imageB: { bytes: b.buffer, mediaType: b.mediaType },
+        grid: args.grid, topRegions: args.top_regions, signal: exec.signal
       });
+      const { ratio, diffPixels, totalPixels, width, height, worstRegions } = result.metrics;
       const ref = await attachmentService(host).saveImage({
-        data: new Uint8Array(heatmap),
-        mediaType: mime,
+        data: new Uint8Array(result.bytes),
+        mediaType: result.mediaType,
         name: `iris-diff-${Date.now()}.png`
       });
       const pct = (ratio * 100).toFixed(2);
       const regions = worstRegions.map((r) => `(col ${r.col},row ${r.row}) ${(r.score * 100).toFixed(1)}%`).join(' ');
       return {
+        artifactIds: [result.artifact.id],
         blocks: [
           {
             type: 'text',
@@ -1012,14 +1115,16 @@ export async function runVisionTool(host, exec, { origin, model, question, ref,
 async function describeFirstImage(host, ref, absPath, originalPrompt) {
   try {
     const mt = MEDIA_TYPES[path.extname(absPath).toLowerCase()] || 'image/png';
-    const { answer } = await askVision(host, {
-      question: `用不超过两句话描述这张图片的主题与构图。生成该图的提示词是：「${String(originalPrompt).slice(0, 200)}」`,
-      ref,
-      dataUrl: toDataUrl(absPath, mt),
-      signal: undefined
-    });
-    return answer.slice(0, 300);
+    return await describeImageData(host, ref, toDataUrl(absPath, mt), originalPrompt);
   } catch (_) {
     return ''; // 自述是增强项，失败不影响交付
   }
 }
+
+async function describeImageData(host, ref, dataUrl, originalPrompt) {
+  const { answer } = await askVision(host, {
+    question: `用不超过两句话描述这张图片的主题与构图。生成该图的提示词是：「${String(originalPrompt).slice(0, 200)}」`,
+    ref, dataUrl, signal: undefined
+  });
+  return answer.slice(0, 300);
+}