@mokuyoaxis/dsh-iris 0.1.2 → 0.1.4

package/lib/index.js

@@ -14,17 +14,28 @@ 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 { 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 { 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';
-import { runAction, listActions } from './actions.js';
+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';
+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',
@@ -34,6 +45,11 @@ const MEDIA_TYPES = {
   '.gif': 'image/gif'
 };
 
+/** DSH 私有对象只在宿主边界转换；可选服务可能晚到，因此按操作刷新快照。 */
+function dshHost(ctx) {
+  return createDshHostAdapter(ctx);
+}
+
 /** 工具内同步等待上限；超过即转后台盯守，用 iris_task_status 查询 */
 const AWAIT_MS = { image: 180000, video: 480000 };
 
@@ -46,10 +62,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({
@@ -60,7 +75,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',
@@ -68,6 +83,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();
@@ -81,48 +97,47 @@ function mountIrisRoutes(routeCtx) {
   }
 }
 
-/** 盯守依赖：按能力给轮询间隔与结果转存扩展名 */
+/** 向后兼容导出；真实实现与人工接管共用 actions.taskPollDeps。 */
 export function pollDeps(provider, cap) {
-  if (cap === 'transcribe') {
-    // 转写任务的结果在 transcription_text 而非 urls——重启接管必须走专用轮询器，
-    // 否则 pollTask 拿到空 urls，盯守会「成功」但转写文本静默丢失。
-    // （与 iris_transcribe_audio 工具内的盯守依赖保持同构。）
-    return {
-      key: () => provider.apiKey,
-      poll: async ({ key, remoteTaskId }) => {
-        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId });
-        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
-      },
-      intervalMs: 2500,
-      onSuccess: async (t, r) => {
-        tasks.update(t.id, { transcribeText: (r.urls && r.urls.join('')) || '' });
-        return [];
-      }
-    };
+  return taskPollDeps(provider, { cap });
+}
+
+/** 旧 status 与 Task v2 事实轴共同决定工具是否应停止等待。 */
+export function taskWaitFinished(task) {
+  if (!task) return false;
+  if (task.status !== 'running') return true;
+  return tasks.isV2Task(task) && task.phase === 'terminal';
+}
+
+/** 把 v2 正交事实转换成不会误导用户的工具错误；空串表示已成功可交付。 */
+export function taskTerminalProblem(task, label = '任务') {
+  if (!task) return label + '记录不存在';
+  if (!tasks.isV2Task(task)) {
+    if (task.status === 'canceled') return '已取消';
+    if (task.status !== 'succeeded') return label + '失败：' + (task.error || '未知原因');
+    return '';
   }
-  return {
-    key: () => provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
-    intervalMs: cap === 'video' ? 6000 : 2500,
-    onSuccess: async (t, r) => {
-      fs.mkdirSync(outputDir(), { recursive: true });
-      const names = [];
-      for (const url of r.urls || []) {
-        const name = `${t.id}-${names.length}.${adapters.extFromUrl(url, cap === 'video' ? 'mp4' : 'png')}`;
-        await adapters.downloadTo(url, path.join(outputDir(), name));
-        names.push(name);
-      }
-      // 登记媒体链接（token 授权），对话流里可点播
-      for (const n of names) registerMedia(t.id, path.join(outputDir(), n));
-      return names;
-    }
-  };
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return '';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'failed') {
+    return label + '已成功，但产物交付失败：' + (task.error || '可稍后重新交付；禁止重新生成');
+  }
+  if (task.acceptance === 'unknown' || task.outcome === 'unknown') {
+    return label + '的远端受理或结果状态未知：' + (task.error || '禁止自动重提，请先人工确认');
+  }
+  if (task.cancelState === 'unknown') {
+    return label + '的远端取消状态未知：' + (task.error || '请先人工确认');
+  }
+  if (task.outcome === 'canceled') return '已取消';
+  if (task.outcome === 'failed') return label + '失败：' + (task.error || '供应商明确返回失败');
+  return task.phase === 'terminal'
+    ? label + '需要人工处理：' + (task.error || '状态未能自动收口')
+    : '';
 }
 
 /**
  * 在工具调用内同步等待任务到终态。
  * @returns 终态任务记录；null = 等待超时（任务已转后台继续盯守）
- * @throws 取消时抛错并标记 canceled
+ * @throws 取消时抛错并记录保守取消事实
  */
 async function awaitTerminal(taskId, { timeoutMs, signal }) {
   const deadline = Date.now() + timeoutMs;
@@ -132,7 +147,7 @@ async function awaitTerminal(taskId, { timeoutMs, signal }) {
       throw new Error('已取消');
     }
     const t = tasks.get(taskId);
-    if (t && t.status !== 'running') return t;
+    if (taskWaitFinished(t)) return t;
     if (Date.now() > deadline) return null;
     await new Promise((r) => setTimeout(r, 1000));
   }
@@ -174,13 +189,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());
@@ -219,19 +238,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). ' +
@@ -254,23 +274,23 @@ export async function apply(ctx) {
     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 });
       let final = tasks.get(submitted.taskId);
-      if (final && final.status === 'running') {
+      if (final && !taskWaitFinished(final)) {
         final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
       }
       if (!final) {
         return { blocks: [{ type: 'text', text: `[iris] 图像任务仍在后台盯守（task: ${submitted.taskId}）。稍后可用 iris_task_status 查询进度与文件路径。` }] };
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '图像生成');
+      if (terminalProblem) throw new Error(terminalProblem);
 
       const files = (final.files || []).map((f) => path.join(outputDir(), f));
       const blocks = [];
       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 +304,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 +318,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,14 +343,14 @@ 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 });
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.video, signal: exec.signal });
       if (!final) {
         return `[iris] 视频任务已提交并转入后台盯守（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
           '渲染通常需要数分钟；完成后用 iris_task_status 查询产物路径。';
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('视频生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '视频生成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const paths = (final.files || []).map((f) => path.join(outputDir(), f));
       const links = mediaLinksOf(final);
       const secs = Math.round((Date.now() - new Date(final.createdAt).getTime()) / 1000);
@@ -342,7 +362,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,9 +377,10 @@ 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 });
       const final = tasks.get(submitted.taskId);
-      if (!final || final.status !== 'succeeded') throw new Error('语音合成失败：' + ((final && final.error) || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '语音合成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const fileName = (final.files || [])[0];
       const p = path.join(outputDir(), fileName);
       const media = (final.media || [])[0];
@@ -369,7 +390,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: {
@@ -383,17 +404,17 @@ 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 });
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: 120000, signal: exec.signal });
       if (!final) return `[iris] 音频转写任务已提交并转入后台（task: ${submitted.taskId}）。完成后用 iris_task_status 查询。`;
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('转写失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '音频转写');
+      if (terminalProblem) throw new Error(terminalProblem);
       return `[iris] 音频转写完成（${submitted.model || final.model}）：\n${final.transcribeText || ''}`;
     }
   });
 
   /* ---------- 🎞️ 视频抽帧（阶段 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. ' +
@@ -432,7 +453,7 @@ export async function apply(ctx) {
       const refs = [];
       for (let i = 0; i < frames.length; i++) {
         const f = frames[i];
-        const ref = await attachmentService(ctx).saveImage({
+        const ref = await attachmentService(host).saveImage({
           data: new Uint8Array(f.buffer),
           mediaType,
           name: `iris-frame-${Date.now()}-${i + 1}.${ext}`
@@ -454,7 +475,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📝 多模态视频摘要（阶段 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 ' +
@@ -498,7 +519,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}，本次摘要未含语音内容）`;
@@ -515,13 +536,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')}`,
@@ -545,7 +566,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.',
@@ -570,12 +591,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.',
@@ -598,22 +619,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.',
@@ -639,7 +660,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- ✂️ 确定性像素工具（阶段 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. ' +
@@ -660,7 +681,7 @@ 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
       });
@@ -671,7 +692,7 @@ export async function apply(ctx) {
         width: args.width,
         height: args.height
       });
-      const ref = await attachmentService(ctx).saveImage({
+      const ref = await attachmentService(host).saveImage({
         data: new Uint8Array(buffer),
         mediaType: mime,
         name: `iris-crop-${Date.now()}.png`
@@ -685,7 +706,7 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(ctx, {
+  safeRegister(host, {
     name: 'iris_pixel_diff',
     description:
       'Compute a pixel-level difference between two images (absolute local paths or session attachment_ids). ' +
@@ -709,15 +730,15 @@ 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 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 ref = await attachmentService(ctx).saveImage({
+      const ref = await attachmentService(host).saveImage({
         data: new Uint8Array(heatmap),
         mediaType: mime,
         name: `iris-diff-${Date.now()}.png`
@@ -739,7 +760,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), ' +
@@ -759,14 +780,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,
@@ -781,7 +802,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. ' +
@@ -803,19 +824,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`
@@ -835,7 +854,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) ' +
@@ -855,12 +874,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,
@@ -880,13 +899,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;
 }
 
 /**
@@ -894,7 +913,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 必须是绝对路径');
@@ -905,7 +924,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 {
@@ -914,7 +933,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',
@@ -946,51 +965,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;
 }
 
 /**
@@ -999,9 +984,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 });
 }
 
@@ -1009,9 +994,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,
@@ -1024,10 +1009,10 @@ 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, {
+    const { answer } = await askVision(host, {
       question: `用不超过两句话描述这张图片的主题与构图。生成该图的提示词是：「${String(originalPrompt).slice(0, 200)}」`,
       ref,
       dataUrl: toDataUrl(absPath, mt),