@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/lib/index.js

@@ -14,10 +14,13 @@ import * as cap from './capability.js';
 import * as tasks from './tasks.js';
 import { registerMedia, mediaLinksOf, authorizeMedia, serveMedia } from './media.js';
 import { serveApi, closeAllSse, purgeStaleUploads } from './api.js';
-import { buildVisionBackends, askWithBackends } from './vision.js';
-import { cropImage, pixelDiff, imageDimensions } from './pixels.js';
+import { buildVisionBackendsFromHost, askWithBackends } from './vision.js';
+import { hasHostPort, requireHostPort } from './host-contract.js';
+import { createDshHostAdapter } from './dsh-host-adapter.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, BrowserHtmlRenderer } from './render.js';
+import { serveRender } from './render.js';
 import { ensurePrivateDir, hardenPrivateTree } from './private-storage.js';
 import { guarded } from './guard.js';
 import { longOcr } from './ocr.js';
@@ -25,7 +28,15 @@ import { runAction, listActions, taskPollDeps } from './actions.js';
 import { ffmpegAvailable, extractFrames, probeVideo, extractAudioTrack } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
 import { registerBundledSkills } from './bundled-skills.js';
-export { doctor, formatDoctorReport } from './doctor.js';
+import {
+  EXPECTED_IRIS_ROUTES, IRIS_PLUGIN_ID, beginHostRuntime, recordHostRoutes, recordHostSkills, recordHostTool
+} from './host-runtime.js';
+export { doctor, formatDoctorReport, hostDoctor } from './doctor.js';
+
+const PACKAGE_VERSION = (() => {
+  try { return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version || 'unknown'; }
+  catch (_) { return 'unknown'; }
+})();
 
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -35,8 +46,13 @@ const MEDIA_TYPES = {
   '.gif': 'image/gif'
 };
 
+/** DSH 私有对象只在宿主边界转换；可选服务可能晚到，因此按操作刷新快照。 */
+function dshHost(ctx) {
+  return createDshHostAdapter(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();
@@ -47,10 +63,9 @@ function outputDir() {
 
 let mediaRouteMounted = false;
 function mountIrisRoutes(routeCtx) {
-  // Cordis 铁律：服务一律走 ctx.get() 可选访问；属性直读会在未 inject 时抛错炸掉整个插件
-  const reg = routeCtx && typeof routeCtx.get === 'function'
-    ? (routeCtx.get('webServer') || routeCtx.get('httpServer'))
-    : undefined;
+  // Cordis 服务只在 DSH 宿主边界探测；Command 与通用工具辅助函数不接收原始 ctx
+  const host = dshHost(routeCtx);
+  const reg = hasHostPort(host, 'routes') ? host.ports.routes : undefined;
   if (!reg || typeof reg.register !== 'function' || mediaRouteMounted) return;
   try {
     const disposeMedia = reg.register({
@@ -61,7 +76,7 @@ function mountIrisRoutes(routeCtx) {
     const disposeApi = reg.register({
       kind: 'prefix',
       path: '/iris/api',
-      handler: guarded((req, res) => serveApi(req, res, routeCtx))
+      handler: guarded((req, res) => serveApi(req, res, dshHost(routeCtx)))
     });
     const disposeRender = reg.register({
       kind: 'prefix',
@@ -69,6 +84,7 @@ function mountIrisRoutes(routeCtx) {
       handler: guarded(serveRender)
     });
     mediaRouteMounted = true;
+    recordHostRoutes(EXPECTED_IRIS_ROUTES);
     routeCtx.effect(() => () => {
       if (typeof disposeMedia === 'function') disposeMedia();
       if (typeof disposeApi === 'function') disposeApi();
@@ -138,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) {
@@ -145,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'];
 
@@ -174,13 +212,17 @@ function guard(label, fn) {
 }
 
 /** 单工具注册隔离：注册失败的收益是诊断日志，而不是宿主陪葬 */
-function safeRegister(ctx, definition) {
+function safeRegister(host, definition) {
+  let registered = false;
   guard(`工具注册 ${definition && definition.name}`, () => {
-    ctx.effect(() => ctx.tools.register(definition));
+    requireHostPort(host, 'tools', '注册 Agent 工具').register(definition);
+    registered = true;
   });
+  if (registered) recordHostTool(definition.name);
 }
 
 export async function apply(ctx) {
+  beginHostRuntime({ pluginId: IRIS_PLUGIN_ID, version: PACKAGE_VERSION });
   guard('Iris 私有存储权限收紧', () => hardenPrivateTree(store.irisHome()));
 
   guard('上传临时文件清理', () => purgeStaleUploads());
@@ -204,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();
+    });
   });
 
   // 媒体路由（视频/音频在对话流里的可播通路；图片仍走原生附件）
@@ -219,19 +271,20 @@ export async function apply(ctx) {
   // 全局层；项目目录中的同名 Skill 仍由 DSH 原生优先级覆盖。
   ctx.inject(['skills'], (skillCtx) => {
     guard('随包 Skill 注册', () => {
-      const names = registerBundledSkills(skillCtx);
+      const names = registerBundledSkills(dshHost(skillCtx));
+      recordHostSkills(names);
       console.log('[iris] 随包 Skill 已注册：' + names.join(' · '));
     });
   });
 
-  const tools = ctx.tools;
-  if (!tools || typeof tools.register !== 'function') {
+  const host = dshHost(ctx);
+  if (!hasHostPort(host, 'tools')) {
     console.error('[iris] tools 服务不可用，跳过全部工具注册（宿主不受影响）');
     return;
   }
 
   /* ---------- 🖼️ 画图 ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_draw_image',
     description:
       'Generate an image from a detailed prompt using the user-configured image model (DashScope wan* or OpenAI-images-compatible). ' +
@@ -253,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(ctx, 'image', args, { signal: exec.signal });
+      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 });
@@ -270,7 +350,7 @@ export async function apply(ctx) {
       const refs = [];
       for (const f of files) {
         const mediaType = MEDIA_TYPES[path.extname(f).toLowerCase()] || 'image/png';
-        const ref = await attachmentService(ctx).saveImage({ data: new Uint8Array(fs.readFileSync(f)), mediaType, name: path.basename(f) });
+        const ref = await attachmentService(host).saveImage({ data: new Uint8Array(fs.readFileSync(f)), mediaType, name: path.basename(f) });
         refs.push(ref);
         blocks.push({ type: 'image', attachment: ref });
       }
@@ -284,7 +364,7 @@ export async function apply(ctx) {
 
       let note = '';
       try {
-        const described = await describeFirstImage(ctx, refs[0], files[0], prompt);
+        const described = await describeFirstImage(dshHost(ctx), refs[0], files[0], prompt);
         if (described) note = `画面内容：${described}`;
       } catch (_) { /* 增强失败不影响生成结果 */ }
       blocks.unshift({
@@ -298,7 +378,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎬 视频生成 ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_generate_video',
     description:
       'Generate a video with the configured DashScope video model. Three modes: ' +
@@ -323,7 +403,26 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(ctx, 'video', args, { signal: exec.signal });
+      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` +
@@ -342,7 +441,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🔊 语音合成 ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_speak_text',
     description: 'Synthesize speech audio from text using the configured TTS model (qwen-tts / compatible). Returns the saved audio file path.',
     parameters: {
@@ -357,7 +456,17 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      const submitted = await runAction(ctx, 'tts', args, { signal: exec.signal });
+      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);
@@ -370,7 +479,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎙️ 音频转写（阶段 7.2） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_transcribe_audio',
     description: 'Transcribe an audio file (wav/mp3) to text using the configured DashScope provider (qwen-audio-3.0-asr-flash-filetrans). The audio is uploaded to Bailian temp storage, then an async task is submitted. Returns the full recognized text.',
     parameters: {
@@ -384,7 +493,26 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(ctx, 'transcribe', args, { signal: exec.signal });
+      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, '音频转写');
@@ -394,7 +522,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎞️ 视频抽帧（阶段 7.1，ffmpeg 可选） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_video_frames',
     description:
       'Extract N frames (uniformly sampled across the video) from a local video file using the system ffmpeg. ' +
@@ -415,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(ctx).saveImage({
-          data: new Uint8Array(f.buffer),
+        const ref = await attachmentService(host).saveImage({
+          data: new Uint8Array(f.bytes),
           mediaType,
           name: `iris-frame-${Date.now()}-${i + 1}.${ext}`
         });
@@ -450,12 +574,12 @@ 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) };
     }
   });
 
   /* ---------- 📝 多模态视频摘要（阶段 7.3，ffmpeg 可选） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_media_summarize',
     description:
       'Summarize a local video by compressing it into a contact sheet of sampled frames (with timestamps) plus an optional ' +
@@ -499,7 +623,7 @@ export async function apply(ctx) {
           try {
             const audio = await extractAudioTrack({ inputPath: p, signal: exec.signal });
             try {
-              const submitted = await runAction(ctx, 'transcribe', { audio_path: audio.filePath }, { signal: exec.signal });
+              const submitted = await runAction(dshHost(ctx), 'transcribe', { audio_path: audio.filePath }, { signal: exec.signal });
               const final = await awaitTerminal(submitted.taskId, { timeoutMs: 120000, signal: exec.signal });
               if (final && final.status === 'succeeded') transcript = final.transcribeText || '';
               else if (!final) transcriptNote = `\n（音轨转写仍在后台：task ${submitted.taskId}，本次摘要未含语音内容）`;
@@ -516,13 +640,13 @@ export async function apply(ctx) {
 
       // contact sheet → attachment → 视觉摘要
       const sheet = await buildContactSheet({ frames, cols: 3 });
-      const ref = await attachmentService(ctx).saveImage({
+      const ref = await attachmentService(host).saveImage({
         data: new Uint8Array(sheet.buffer),
         mediaType: 'image/png',
         name: `iris-sheet-${Date.now()}.png`
       });
       const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-      const backends = buildVisionBackends(ctx, { providers: visionProviders, model: args.model });
+      const backends = buildVisionBackendsFromHost(dshHost(ctx), { providers: visionProviders, model: args.model });
       const { answer, via, model } = await summarizeMedia({
         backends, question: args.question, transcript,
         imageDataUrl: `data:image/png;base64,${sheet.buffer.toString('base64')}`,
@@ -546,7 +670,7 @@ export async function apply(ctx) {
 
   /* ---------- 👁 视觉路由（M3）：显式工具，自持栈为主 ---------- */
 
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_look_at_image',
     description:
       'Look at a local image file and answer one question about it with the configured vision model (qwen-vl via the self-hosted provider stack; falls back to the global DSH vision model). The image is saved as a durable attachment so follow-ups can reference it.',
@@ -571,12 +695,12 @@ export async function apply(ctx) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
 
       const dataUrl = toDataUrl(p, mt);
-      const ref = await attachmentService(ctx).saveImage({ data: new Uint8Array(fs.readFileSync(p)), mediaType: mt, name: path.basename(p) });
-      return runVisionTool(ctx, exec, { origin: 'tool', model: args.model, question, ref, dataUrl });
+      const ref = await attachmentService(host).saveImage({ data: new Uint8Array(fs.readFileSync(p)), mediaType: mt, name: path.basename(p) });
+      return runVisionTool(dshHost(ctx), exec, { origin: 'tool', model: args.model, question, ref, dataUrl });
     }
   });
 
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_relook_attachment',
     description:
       'Ask a NEW question about an image that was already seen in this session: pass its attachment_id (from user uploads, tool results, or any iris-generated image). Pixels are re-read via the vision model.',
@@ -599,22 +723,22 @@ export async function apply(ctx) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
 
       // 定位：本会话出现过的图片优先，其次本插件产物记录
-      const hit = (await sessionAttachmentRef(ctx, exec, id)) || findOwnAttachment(id);
+      const hit = (await sessionAttachmentRef(host, exec, id)) || findOwnAttachment(id);
       if (!hit) throw new Error('iris: 该 attachment 不在本会话中、也不是 iris 生成的图片：' + id);
 
       let dataUrl;
       if (hit.absPath) {
         dataUrl = toDataUrl(hit.absPath, hit.ref.mediaType || MEDIA_TYPES[path.extname(hit.absPath).toLowerCase()] || 'image/png');
       } else {
-        const stored = await attachmentService(ctx).readImage(hit.ref, exec.signal);
+        const stored = await attachmentService(host).readImage(hit.ref, exec.signal);
         dataUrl = `data:${stored.mediaType || hit.ref.mediaType};base64,${Buffer.from(stored.data).toString('base64')}`;
       }
-      return runVisionTool(ctx, exec, { origin: 'relook', model: args.model, question, ref: hit.ref, dataUrl });
+      return runVisionTool(dshHost(ctx), exec, { origin: 'relook', model: args.model, question, ref: hit.ref, dataUrl });
     }
   });
 
   /* ---------- 📋 任务查询 ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_task_status',
     description:
       'Query iris generation tasks (image/video/tts). Pass a task_id for one task, or omit it to list the latest tasks with status, progress, errors and output file paths.',
@@ -628,19 +752,13 @@ 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;
     }
   });
 
   /* ---------- ✂️ 确定性像素工具（阶段 2） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_crop',
     description:
       'Crop a rectangular region from an image (absolute local path or a session attachment_id) and save the result as a durable DSH attachment. ' +
@@ -661,32 +779,36 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const input = await resolveImageInput(ctx, exec, {
+      const input = await resolveImageInput(dshHost(ctx), exec, {
         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
       });
-      const ref = await attachmentService(ctx).saveImage({
-        data: new Uint8Array(buffer),
-        mediaType: mime,
+      if (exec.signal && exec.signal.aborted) throw new Error('已取消');
+      const ref = await attachmentService(host).saveImage({
+        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 }
         ]
       };
     }
   });
 
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_pixel_diff',
     description:
       'Compute a pixel-level difference between two images (absolute local paths or session attachment_ids). ' +
@@ -710,22 +832,23 @@ export async function apply(ctx) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
       if (!(args.image_a_path || args.attachment_a_id)) throw new Error('iris: 需要 image_a_path 或 attachment_a_id');
       if (!(args.image_b_path || args.attachment_b_id)) throw new Error('iris: 需要 image_b_path 或 attachment_b_id');
-      const a = await resolveImageInput(ctx, exec, { image_path: args.image_a_path, attachment_id: args.attachment_a_id });
-      const b = await resolveImageInput(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 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 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 ref = await attachmentService(ctx).saveImage({
-        data: new Uint8Array(heatmap),
-        mediaType: mime,
+      const { ratio, diffPixels, totalPixels, width, height, worstRegions } = result.metrics;
+      const ref = await attachmentService(host).saveImage({
+        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',
@@ -740,7 +863,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📍 模型驱动定位（阶段 3A） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_locate',
     description:
       'Locate an object/region described by `target` in an image (absolute path or session attachment_id), ' +
@@ -760,14 +883,14 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const input = await resolveImageInput(ctx, exec, {
+      const input = await resolveImageInput(dshHost(ctx), exec, {
         image_path: args.image_path,
         attachment_id: args.attachment_id
       });
       const { width, height } = await imageDimensions(input.buffer);
       const dataUrl = `data:${input.mediaType};base64,${input.buffer.toString('base64')}`;
       const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-      const backends = buildVisionBackends(ctx, { providers: visionProviders, model: args.model });
+      const backends = buildVisionBackendsFromHost(dshHost(ctx), { providers: visionProviders, model: args.model });
       const r = await locateObject(backends, {
         target: args.target,
         imageDataUrl: dataUrl,
@@ -782,7 +905,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🖼️ HTML 截图（阶段 3C，基于 dsh-builtin-browser） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_html_screenshot',
     description:
       'Render an HTML string to a page screenshot using the shared browser. ' +
@@ -804,19 +927,17 @@ export async function apply(ctx) {
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const browser = ctx.get('browser');
-      if (!browser) {
-        throw new Error('iris: 浏览器服务不可用（ctx.get("browser") 为空）——需要启用 dsh-builtin-browser 插件');
-      }
-      const renderer = new BrowserHtmlRenderer({ browser });
-      const { png } = await renderer.render({
+      const browser = requireHostPort(dshHost(ctx), 'browser', 'HTML 截图');
+      const rendered = await browser.renderHtml({
         html: args.html,
         width: args.width,
         height: args.height,
-        fullPage: args.fullPage !== false
+        fullPage: args.fullPage !== false,
+        signal: exec.signal
       });
+      const png = Buffer.from(rendered.bytes);
       const { width: outW, height: outH } = await imageDimensions(png);
-      const ref = await attachmentService(ctx).saveImage({
+      const ref = await attachmentService(host).saveImage({
         data: new Uint8Array(png),
         mediaType: 'image/png',
         name: `iris-html-${Date.now()}.png`
@@ -836,7 +957,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📄 长截图 OCR（阶段 3B，视觉模型分块） ---------- */
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_long_ocr',
     description:
       'OCR a (possibly long) image: slice it into chunks (1200px tall with 120px overlap by default) ' +
@@ -856,12 +977,12 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const input = await resolveImageInput(ctx, exec, {
+      const input = await resolveImageInput(dshHost(ctx), exec, {
         image_path: args.image_path,
         attachment_id: args.attachment_id
       });
       const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-      const backends = buildVisionBackends(ctx, { providers: visionProviders });
+      const backends = buildVisionBackendsFromHost(dshHost(ctx), { providers: visionProviders });
       const result = await longOcr({
         input: input.buffer,
         backends,
@@ -881,13 +1002,13 @@ export async function apply(ctx) {
 
 /* ---------------- 视觉路由（M3 补全）：look/relook 共用执行器 + 降级链 ---------------- */
 
-/** 附件服务必须走 ctx.get()（不在 inject 里，直接属性访问会炸掉插件） */
-function attachmentService(ctx) {
-  const s = ctx && typeof ctx.get === 'function' ? ctx.get('attachments') : undefined;
-  if (!s || typeof s.saveImage !== 'function' || typeof s.readImage !== 'function') {
-    throw new Error('iris: 附件服务不可用（ctx.get("attachments") 为空）');
+/** 通用工具只消费 Host attachments 端口。 */
+function attachmentService(host) {
+  const attachments = requireHostPort(host, 'attachments', '处理 DSH 附件');
+  if (typeof attachments.saveImage !== 'function' || typeof attachments.readImage !== 'function') {
+    throw new Error('iris: Host attachments 端口缺少 saveImage/readImage');
   }
-  return s;
+  return attachments;
 }
 
 /**
@@ -895,7 +1016,7 @@ function attachmentService(ctx) {
  * crop / pixel_diff 共用（阶段 2）。
  * @returns {Promise<{buffer:Buffer, mediaType:string, name:string}>}
  */
-async function resolveImageInput(ctx, exec, { image_path, attachment_id }) {
+async function resolveImageInput(host, exec, { image_path, attachment_id }) {
   if (image_path) {
     const p = String(image_path).trim();
     if (!path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
@@ -906,7 +1027,7 @@ async function resolveImageInput(ctx, exec, { image_path, attachment_id }) {
   }
   if (attachment_id) {
     const id = String(attachment_id).trim();
-    const hit = (await sessionAttachmentRef(ctx, exec, id)) || findOwnAttachment(id);
+    const hit = (await sessionAttachmentRef(host, exec, id)) || findOwnAttachment(id);
     if (!hit) throw new Error('iris: 该 attachment 不在本会话中、也不是 iris 生成的图片：' + id);
     if (hit.absPath) {
       return {
@@ -915,7 +1036,7 @@ async function resolveImageInput(ctx, exec, { image_path, attachment_id }) {
         name: path.basename(hit.absPath)
       };
     }
-    const stored = await attachmentService(ctx).readImage(hit.ref, exec && exec.signal);
+    const stored = await attachmentService(host).readImage(hit.ref, exec && exec.signal);
     return {
       buffer: Buffer.from(stored.data),
       mediaType: stored.mediaType || hit.ref.mediaType || 'image/png',
@@ -947,51 +1068,17 @@ export function findOwnAttachment(attachmentId) {
  * 不依赖精确事件类型：递归扫任何载荷中的 attachment 块 / attachmentId 字段。
  * @returns {Promise<{ref:object}|null>} 找到则带可直接 readImage 的 ref
  */
-export async function sessionAttachmentRef(ctx, exec, attachmentId) {
+export async function sessionAttachmentRef(host, exec, attachmentId) {
   const agent = exec && exec.agent;
   const session = agent && agent.session;
-  const sq = ctx && typeof ctx.get === 'function' ? ctx.get('sessionQuery') : undefined;
-  if (!sq || !session || typeof sq.readSession !== 'function') return null;
-  let events;
+  const wanted = String(attachmentId || '');
+  if (!session || !wanted || !host?.ports?.sessions) return null;
   try {
-    events = (await sq.readSession(session.id)).events;
+    const ref = await host.ports.sessions.findImageAttachment(session.id, wanted);
+    return ref ? { ref } : null;
   } catch (_) {
     return null; // 读不到会话记录 → 交给 findOwnAttachment 兜底
   }
-  if (!Array.isArray(events)) return null;
-  const wanted = String(attachmentId || '');
-  if (!wanted) return null;
-  const ref = findAttachmentRefIn(events, wanted);
-  return ref ? { ref } : null;
-}
-
-/** 递归扫描对象/数组，返回第一个匹配 wanted 的图片附件引用（防循环、限扫描量） */
-function findAttachmentRefIn(nodes, wanted) {
-  const seen = new Set();
-  const stack = Array.isArray(nodes) ? [...nodes] : [nodes];
-  let scanned = 0;
-  while (stack.length && scanned < 4000) {
-    const node = stack.pop();
-    scanned++;
-    if (!node || typeof node !== 'object') continue;
-    if (seen.has(node)) continue;
-    seen.add(node);
-    // 形态 1：附件块 { type:'image', attachment:{ attachmentId,... } } —— 最优先
-    if (
-      node.attachment && typeof node.attachment === 'object' &&
-      node.attachment.attachmentId === wanted && typeof node.attachment.mediaType === 'string'
-    ) {
-      return node.attachment;
-    }
-    // 形态 2：引用对象本身 { attachmentId, mediaType }（兜底）
-    if (node.attachmentId === wanted && typeof node.mediaType === 'string') {
-      return node;
-    }
-    for (const v of Object.values(node)) {
-      if (v && typeof v === 'object') stack.push(v);
-    }
-  }
-  return null;
 }
 
 /**
@@ -1000,9 +1087,9 @@ function findAttachmentRefIn(nodes, wanted) {
  * 全局视觉模型兜底；每个后端的失败现场保留在 errors 里。
  * @returns {{answer:string,via:'selfstack'|'global',model?:string,backendId:string}}
  */
-export async function askVision(ctx, { question, ref, dataUrl, signal, model }) {
+export async function askVision(host, { question, ref, dataUrl, signal, model }) {
   const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-  const backends = buildVisionBackends(ctx, { providers: visionProviders, model });
+  const backends = buildVisionBackendsFromHost(host, { providers: visionProviders, model });
   return askWithBackends(backends, { question, ref, imageDataUrl: dataUrl, signal });
 }
 
@@ -1010,9 +1097,9 @@ export async function askVision(ctx, { question, ref, dataUrl, signal, model })
  * look / relook 共用执行器：看图问答 → 人话结果（标注模型归属，方便排查走哪条链）。
  * @returns {Promise<string>} 直接作为工具输出
  */
-export async function runVisionTool(ctx, exec, { origin, model, question, ref, dataUrl }) {
+export async function runVisionTool(host, exec, { origin, model, question, ref, dataUrl }) {
   if (exec && exec.signal && exec.signal.aborted) throw new Error('已取消');
-  const { answer, via, model: usedModel } = await askVision(ctx, {
+  const { answer, via, model: usedModel } = await askVision(host, {
     question,
     ref,
     dataUrl,
@@ -1025,17 +1112,19 @@ export async function runVisionTool(ctx, exec, { origin, model, question, ref, d
 }
 
 /* ---------------- 视觉自述（画图后增强项）：走 askVision 降级链，失败静默 ---------------- */
-async function describeFirstImage(ctx, ref, absPath, originalPrompt) {
+async function describeFirstImage(host, ref, absPath, originalPrompt) {
   try {
     const mt = MEDIA_TYPES[path.extname(absPath).toLowerCase()] || 'image/png';
-    const { answer } = await askVision(ctx, {
-      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);
+}