@mokuyoaxis/dsh-iris 0.1.3 → 0.1.4

package/lib/index.js

@@ -14,10 +14,12 @@ 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';
@@ -25,7 +27,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,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 };
 
@@ -47,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({
@@ -61,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',
@@ -69,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();
@@ -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,7 +274,7 @@ 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 && !taskWaitFinished(final)) {
         final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
@@ -270,7 +290,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 +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,7 +343,7 @@ 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` +
@@ -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,7 +377,7 @@ 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);
       const terminalProblem = taskTerminalProblem(final, '语音合成');
       if (terminalProblem) throw new Error(terminalProblem);
@@ -370,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: {
@@ -384,7 +404,7 @@ 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 查询。`;
       const terminalProblem = taskTerminalProblem(final, '音频转写');
@@ -394,7 +414,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. ' +
@@ -433,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}`
@@ -455,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 ' +
@@ -499,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}，本次摘要未含语音内容）`;
@@ -516,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')}`,
@@ -546,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.',
@@ -571,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.',
@@ -599,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.',
@@ -640,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. ' +
@@ -661,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
       });
@@ -672,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`
@@ -686,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). ' +
@@ -710,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`
@@ -740,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), ' +
@@ -760,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,
@@ -782,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. ' +
@@ -804,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`
@@ -836,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) ' +
@@ -856,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,
@@ -881,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;
 }
 
 /**
@@ -895,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 必须是绝对路径');
@@ -906,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 {
@@ -915,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',
@@ -947,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;
 }
 
 /**
@@ -1000,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 });
 }
 
@@ -1010,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,
@@ -1025,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),

package/lib/locate.js

@@ -38,7 +38,7 @@ export function extractBboxJson(answer) {
 
 /**
  * 在原图上定位目标，返回原像素 bbox。
- * @param {Array} backends 有序视觉后端（buildVisionBackends 产物）
+ * @param {Array} backends 有序视觉后端（buildVisionBackendsFromHost 产物）
  * @param {{target:string, imageDataUrl:string, width:number, height:number, signal?:AbortSignal}}
  * @returns {Promise<{found:boolean, x1?:number, y1?:number, x2?:number, y2?:number, via?:string, model?:string}>}
  * @throws LocateError 模型未返回有效 bbox / bbox 完全越界 / 字段非法

package/lib/media.js

@@ -15,13 +15,16 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import * as tasks from './tasks.js';
+import * as artifacts from './artifacts.js';
 
 const MIME = {
   '.mp4': 'video/mp4',
   '.mov': 'video/quicktime',
   '.webm': 'video/webm',
-  '.wav': 'audio/wav',
-  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav', '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.flac': 'audio/flac',
+  '.mkv': 'video/x-matroska', '.avi': 'video/x-msvideo', '.mpeg': 'video/mpeg', '.mpg': 'video/mpeg',
+  '.avif': 'image/avif', '.bmp': 'image/bmp',
   '.png': 'image/png',
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
@@ -61,9 +64,11 @@ export function registerMedia(taskId, absPath) {
       createdAt: new Date().toISOString()
     };
     tasks.update(taskId, { media: [...(t.media || []), entry] });
+    artifacts.register(absPath);
     return { ...entry, url: mediaUrl(taskId, entry) };
   }
   const entry = t.media.find((e) => e.file === file);
+  artifacts.register(absPath);
   return { ...entry, url: mediaUrl(taskId, entry) };
 }
 
@@ -127,15 +132,20 @@ export function serveMedia(req, res) {
     const method = String(req.method || 'GET').toUpperCase();
     if (method !== 'GET' && method !== 'HEAD') return sendText(res, 405, 'method not allowed');
     const parts = String(req.url || '').split('?')[0].split('/').filter(Boolean);
-    // /iris/media/:taskId/:token/:name
-    if (parts.length !== 5 || parts[0] !== 'iris' || parts[1] !== 'media') return sendText(res, 404, 'not found');
+    // Task media: /iris/media/:taskId/:token/:name
+    // Independent work: /iris/media/artifact/:artifactId/:token/:name
+    const artifactRoute = parts.length === 6 && parts[0] === 'iris' && parts[1] === 'media' && parts[2] === 'artifact';
+    const taskRoute = parts.length === 5 && parts[0] === 'iris' && parts[1] === 'media';
+    if (!artifactRoute && !taskRoute) return sendText(res, 404, 'not found');
     let name;
     try {
-      name = decodeURIComponent(parts[4]);
+      name = decodeURIComponent(parts[artifactRoute ? 5 : 4]);
     } catch (_) {
       return sendText(res, 404, 'not found');
     }
-    const hit = authorizeMedia(parts[2], parts[3], name);
+    const hit = artifactRoute
+      ? artifacts.authorize(parts[3], parts[4], name)
+      : authorizeMedia(parts[2], parts[3], name);
     if (!hit) return sendText(res, 404, 'not found'); // 未命中一律 404，不给枚举线索
     const base = {
       'Content-Type': hit.entry.mime,