@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/lib/index.js

@@ -14,19 +14,22 @@ 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 { buildVisionBackendsFromHost, askWithBackends } from './vision.js';
+import { runVisionRequest, readVisionImageFile } from './vision-model-routing.js';
+import { waitForModelWork } from './model-call-runtime.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 { cropForDsh, diffForDsh, framesForDsh, summaryFramesForDsh, visionImageForDsh, htmlForDsh, inspectProviderTaskForDsh, projectCoreTaskForDsh, readCoreArtifactMediaForDsh, resumeProviderTaskWatchesForDsh, stopProviderTaskWatchesForDsh } from './dsh-core-adapter.js';
 import { imageDimensions } from './pixels.js';
-import { locateObject } from './locate.js';
+import { runLocateRequest, runSummaryRequest, describeGeneratedImage } from './composite-vision-routing.js';
+import { normalizeSummarySource, summaryFrameRecords, summaryTimelineLabel } from './summary-input.js';
+import { normalizeVisionImageSource } from './vision-input.js';
 import { serveRender } from './render.js';
 import { ensurePrivateDir, hardenPrivateTree } from './private-storage.js';
 import { guarded } from './guard.js';
-import { longOcr } from './ocr.js';
+import { formatOcrResult } from './ocr.js';
+import { runOcrRequest } from './ocr-model-routing.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
@@ -187,13 +190,6 @@ async function awaitCoreTerminal(taskId, { timeoutMs, signal }) {
   }
 }
 
-/* ---------------- 图片 data URL（视觉工具共用） ---------------- */
-
-function toDataUrl(absPath, mediaType) {
-  const buf = fs.readFileSync(absPath);
-  return `data:${mediaType};base64,${buf.toString('base64')}`;
-}
-
 export const name = 'mokuyoaxis-dsh-iris';
 export const inject = ['tools'];
 
@@ -283,11 +279,41 @@ export async function apply(ctx) {
     return;
   }
 
+  async function coreImageToolResult(submitted, prompt, signal) {
+    let final = await inspectProviderTaskForDsh(submitted.taskId, { signal });
+    if (!coreTaskWaitFinished(final)) final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, 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 });
+    const refs = projected.artifacts.map((item) => item.attachment);
+    const blocks = projected.artifacts.map((item) => ({ type: 'image', attachment: item.attachment }));
+    let note = '';
+    try {
+      const described = await describeGeneratedImage(dshHost(ctx), {
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal,
+        async prepareImage(inputSignal) {
+          const first = await readCoreArtifactMediaForDsh(projected.artifacts[0].artifact.id, { signal: inputSignal });
+          return { bytes: new Uint8Array(first.bytes), mediaType: first.artifact.mediaType };
+        }
+      });
+      if (described) note = `画面内容：${described}`;
+    } catch (_) { /* 自述失败不影响 Core 交付 */ }
+    blocks.unshift({ type: 'text', text:
+      `[iris] 图像已生成（${submitted.model}，Core task: ${submitted.taskId}）。` +
+      (submitted.sourceArtifactId ? `\n原图 artifact: ${submitted.sourceArtifactId}` : '') +
+      (note ? `\n${note}` : '') +
+      `\nartifact: ${projected.artifacts.map((item) => item.artifact.id).join(', ')}` +
+      `\nattachment: ${refs.map((ref) => ref.attachmentId).join(', ')}`
+    });
+    return { blocks };
+  }
+
   /* ---------- 🖼️ 画图 ---------- */
   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). ' +
+      'Generate an image from a detailed prompt using the user-configured image model and its configured image protocol. ' +
       'Returns a durable DSH attachment rendered in the conversation plus a vision-model description so you know what was drawn.',
     parameters: {
       type: 'object',
@@ -308,32 +334,7 @@ export async function apply(ctx) {
       const prompt = String(args.prompt || '').trim();
       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 };
+        return coreImageToolResult(submitted, prompt, exec.signal);
       }
       let final = tasks.get(submitted.taskId);
       if (final && !taskWaitFinished(final)) {
@@ -364,7 +365,10 @@ export async function apply(ctx) {
 
       let note = '';
       try {
-        const described = await describeFirstImage(dshHost(ctx), refs[0], files[0], prompt);
+        const described = await describeGeneratedImage(dshHost(ctx), {
+          providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal: exec.signal,
+          prepareImage: signal => readVisionImageFile(files[0], MEDIA_TYPES[path.extname(files[0]).toLowerCase()] || 'image/png', signal)
+        });
         if (described) note = `画面内容：${described}`;
       } catch (_) { /* 增强失败不影响生成结果 */ }
       blocks.unshift({
@@ -377,6 +381,25 @@ export async function apply(ctx) {
     }
   });
 
+  safeRegister(host, {
+    name: 'iris_edit_image',
+    description: 'Edit an existing Core image by Artifact ID and an instruction using a configured openai-chat-images model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
+    parameters: {
+      type: 'object', properties: {
+        source_artifact_id: { type: 'string', description: 'Core Artifact ID of the source PNG, JPEG or WebP image (up to 20 MiB)' },
+        prompt: { type: 'string', description: 'Describe the changes and what should be preserved in the source image' },
+        model: { type: 'string', description: 'Optional providerId::modelId; image protocol must be openai-chat-images' },
+        n: { type: 'string', description: "Number of images, default '1'" }
+      }, required: ['source_artifact_id', 'prompt']
+    },
+    output: { schema: { type: 'object' }, render: (_args, value) => value.blocks },
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      const submitted = await runAction(dshHost(ctx), 'image_edit', args, { signal: exec.signal });
+      return coreImageToolResult(submitted, String(args.prompt || '').trim(), exec.signal);
+    }
+  });
+
   /* ---------- 🎬 视频生成 ---------- */
   safeRegister(host, {
     name: 'iris_generate_video',
@@ -389,7 +412,7 @@ export async function apply(ctx) {
     parameters: {
       type: 'object',
       properties: {
-        prompt: { type: 'string', description: 'Detailed description of the motion/scene for the video' },
+        prompt: { type: 'string', description: 'Motion/scene description, required for t2v/i2v; optional for s2v' },
         first_frame_attachment_id: { type: 'string', description: 'Attachment id of an image generated by iris_draw_image, used as the first frame' },
         first_frame_path: { type: 'string', description: 'Absolute path to a local image used as the first frame (alternative to attachment id)' },
         audio_path: { type: 'string', description: 'Absolute path to a wav/mp3 file (<15MB, <20s, clear human voice). Required for s2v models like wan2.2-s2v' },
@@ -398,12 +421,12 @@ export async function apply(ctx) {
         duration: { type: 'number', description: 't2v/i2v only: duration in seconds, if the model supports it' },
         model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id accepted)' }
       },
-      required: ['prompt']
+      required: []
     },
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
-      const submitted = await runAction(dshHost(ctx), 'video', args, { signal: exec.signal });
+      const submitted = await runAction(dshHost(ctx), 'video', { ...args, session_id: exec.agent?.session?.id }, { signal: exec.signal });
       if (submitted.storage === 'core') {
         let final = await inspectProviderTaskForDsh(submitted.taskId, { signal: exec.signal });
         if (!coreTaskWaitFinished(final)) {
@@ -572,6 +595,7 @@ export async function apply(ctx) {
           `[iris] 视频抽帧完成：${frames.length} 帧（${meta.durationSec.toFixed(1)}s 视频，` +
           `${frames[0].width}x${frames[0].height}，${mediaType === 'image/png' ? 'PNG' : 'JPEG'}）。\n` +
           `时间戳：${ats}\n` +
+          `frame_artifact_ids: ${JSON.stringify(frames.map(f => f.artifact.id))}\n` +
           `attachments: ${refs.map((r) => r.attachmentId).join(', ')}`
       });
       return { blocks, artifactIds: frames.map((frame) => frame.artifact.id) };
@@ -582,83 +606,91 @@ export async function apply(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 ' +
+      'Summarize a local video or existing Core video-frame Artifacts as one contact sheet (with timestamps) plus an optional ' +
       'auto-transcribed audio track, then asking the vision model to describe content. Returns the summary text plus the contact sheet as a DSH image attachment. ' +
-      'Requires ffmpeg + ffprobe on PATH. Transcription reuses the configured provider (qwen-audio-3.0-asr-flash-filetrans) when the video has an audio track.',
+      'Provide exactly one of video_path or frame_artifact_ids. Existing frames are read in timestamp order without ffmpeg or the original video. ' +
+      'The video_path mode requires ffmpeg + ffprobe and can auto-transcribe the audio track with the configured provider.',
     parameters: {
       type: 'object',
       properties: {
         video_path: { type: 'string', description: 'Absolute path to the local video file (mp4/webm/mov etc.)' },
+        frame_artifact_ids: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 20, uniqueItems: true,
+          description: 'Existing Core video-frame IDs from iris_video_frames; sorted by timestamp. Use instead of video_path, without sampling options or auto-transcription.' },
         question: { type: 'string', description: 'Custom question about the video content (default: summarize scenes/theme)' },
         max_frames: { type: 'integer', description: 'Frames to sample for the contact sheet, clamped to 1..12 (default 8)' },
         target_width: { type: 'integer', description: 'Frame width for sampling (default 640)' },
-        transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track if present (default true)' },
+        transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track for video_path (default true unless transcribe_text is provided). Existing frames only consume explicit text.' },
+        transcribe_text: { type: 'string', description: 'Optional existing transcript text; does not create a transcription task' },
         model: { type: 'string', description: 'Override the configured vision model id' }
       },
-      required: ['video_path']
+      required: []
     },
     output: { schema: { type: 'object' }, render: (_args, value) => value.blocks },
     isConcurrencySafe: () => false,
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
+      const source = normalizeSummarySource(args);
       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 后启用）');
-      const meta = probeVideo(p);
-      const frames = await extractFrames({
-        inputPath: p,
-        maxFrames: Math.min(Number(args.max_frames) || 8, 12),
-        targetWidth: args.target_width,
-        format: 'jpeg',
-        quality: 70,
-        signal: exec.signal
-      });
-
-      // 音轨转写（可选；与独立 transcribe capability 共用同一动作与 failover）
-      let transcript = '';
-      let transcriptNote = '';
-      const wantTranscribe = args.transcribe !== false && meta.hasAudio;
-      if (wantTranscribe) {
-        if (store.pickAllFor(cap.CAPABILITIES.TRANSCRIBE).length) {
-          try {
-            const audio = await extractAudioTrack({ inputPath: p, signal: exec.signal });
-            try {
-              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}，本次摘要未含语音内容）`;
-            } finally {
-              fs.rmSync(audio.outDir, { recursive: true, force: true });
-            }
-          } catch (err) {
-            transcriptNote = '\n（音轨转写失败，本次摘要仅画面：' + String(err.message || err).slice(0, 160) + '）';
+      if (source === 'video') {
+        if (!p || !path.isAbsolute(p)) throw new Error('iris: video_path 必须是绝对路径');
+        if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法分析视频（可选安装 ffmpeg/ffprobe 后启用）');
+      }
+      const { answer, via, model, sheet, meta, frames, transcriptNote } = await runSummaryRequest(dshHost(ctx), {
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, question: args.question, signal: exec.signal,
+        async prepareMedia(signal) {
+          if (source === 'core-artifacts') {
+            return { ...await summaryFramesForDsh({ frameArtifactIds: args.frame_artifact_ids, signal }), transcript: args.transcribe_text };
           }
-        } else {
-          transcriptNote = '\n（视频含音轨但未配置转写供应商，本次摘要仅画面）';
+          const meta = probeVideo(p);
+          const frames = await extractFrames({
+            inputPath: p, maxFrames: Math.min(Number(args.max_frames) || 8, 12),
+            targetWidth: args.target_width, format: 'jpeg', quality: 70, signal
+          });
+          // 显式选项保留自动转写；消费已完成的 Core Artifact，不重提远端任务。
+          let transcript = args.transcribe_text || '', transcriptNote = '';
+          if (args.transcribe !== false && !transcript.trim() && meta.hasAudio) {
+            if (store.pickAllFor(cap.CAPABILITIES.TRANSCRIBE).length) {
+              try {
+                const audio = await extractAudioTrack({ inputPath: p, signal });
+                try {
+                  const submitted = await runAction(dshHost(ctx), 'transcribe', { audio_path: audio.filePath }, { signal });
+                  const final = await awaitCoreTerminal(submitted.taskId, { timeoutMs: 120000, signal });
+                  if (final?.outcome === 'succeeded' && final.deliveryState === 'ready') {
+                    const texts = [];
+                    for (const artifactId of final.artifactIds) {
+                      const media = await readCoreArtifactMediaForDsh(artifactId, { signal });
+                      texts.push(Buffer.from(media.bytes).toString('utf8'));
+                    }
+                    transcript = texts.join('\n');
+                  } else transcriptNote = '\n（音轨转写未完成，本次摘要仅画面；可用 iris_task_status 查询 Core task）';
+                } finally {
+                  fs.rmSync(audio.outDir, { recursive: true, force: true });
+                }
+              } catch (err) {
+                if (signal.aborted) throw signal.reason;
+                transcriptNote = '\n（音轨转写失败，本次摘要仅画面；可用 iris_task_status 查询转写任务）';
+              }
+            } else transcriptNote = '\n（视频含音轨但未配置转写供应商，本次摘要仅画面）';
+          }
+          return { meta, frames, transcript, transcriptNote };
         }
-      }
-
-      // contact sheet → attachment → 视觉摘要
-      const sheet = await buildContactSheet({ frames, cols: 3 });
+      });
+      // 成功摘要的同一张拼图作为显式工具产物发布。
+      if (exec.signal?.aborted) throw exec.signal.reason;
       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 = 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')}`,
-        ref, signal: exec.signal
-      });
+      if (exec.signal?.aborted) throw exec.signal.reason;
       const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
       return {
+        frames: summaryFrameRecords(frames),
         blocks: [
           {
             type: 'text',
             text:
-              `[iris] 视频摘要完成（${model} · ${viaLabel}，${meta.durationSec.toFixed(1)}s / ${frames.length} 帧联系表）：\n` +
+              `[iris] 视频摘要完成（${model} · ${viaLabel}，${summaryTimelineLabel(meta)} / ${frames.length} 帧联系表）：\n` +
               `${answer}${transcriptNote || ''}\n` +
               `contact sheet attachment: ${ref.attachmentId}`
           },
@@ -673,30 +705,39 @@ export async function apply(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.',
+      'Look at a local image file or an existing Core image Artifact and answer one question with the configured vision model (self-hosted provider stack, then DSH default vision). Provide exactly one of image_path or artifact_id. Local files are saved as durable DSH attachments; Core images are read directly without export or Core writes.',
     parameters: {
       type: 'object',
       properties: {
         image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/jpeg/webp)' },
+        artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path)' },
         question: { type: 'string', description: 'Question or extraction request about the image; defaults to a detailed description' },
         model: { type: 'string', description: 'Override the configured vision model id (default qwen-vl-plus)' }
       },
-      required: ['image_path']
+      required: []
     },
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
+      const source = normalizeVisionImageSource(args);
       const p = String(args.image_path || '').trim();
-      if (!path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
       const mt = MEDIA_TYPES[path.extname(p).toLowerCase()];
-      if (!mt || mt === 'image/gif') throw new Error('iris: 不支持的图片格式（png/jpg/jpeg/webp）：' + p);
-      if (!fs.existsSync(p)) throw new Error('iris: 图片不存在：' + p);
+      if (source === 'image_path') {
+        if (!path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
+        if (!mt || mt === 'image/gif') throw new Error('iris: 不支持的图片格式（png/jpg/jpeg/webp）：' + p);
+        if (!fs.existsSync(p)) throw new Error('iris: 图片不存在：' + p);
+      }
       const question = String(args.question || '').trim() || '详细描述这张图片。';
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
 
-      const dataUrl = toDataUrl(p, mt);
-      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 });
+      return runVisionTool(dshHost(ctx), exec, { origin: 'tool', model: args.model, question, artifactId: args.artifact_id,
+        async prepareImage(signal) {
+          if (source === 'artifact_id') return visionImageForDsh({ artifactId: args.artifact_id, signal });
+          const image = await readVisionImageFile(p, mt, signal);
+          await waitForModelWork(() => attachmentService(host).saveImage({ data: image.bytes, mediaType: mt, name: path.basename(p) }), signal);
+          return image;
+        }
+      });
     }
   });
 
@@ -722,18 +763,16 @@ export async function apply(ctx) {
       if (!question) throw new Error('iris: question 不能为空');
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
 
-      // 定位：本会话出现过的图片优先，其次本插件产物记录
-      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(host).readImage(hit.ref, exec.signal);
-        dataUrl = `data:${stored.mediaType || hit.ref.mediaType};base64,${Buffer.from(stored.data).toString('base64')}`;
-      }
-      return runVisionTool(dshHost(ctx), exec, { origin: 'relook', model: args.model, question, ref: hit.ref, dataUrl });
+      return runVisionTool(dshHost(ctx), exec, { origin: 'relook', model: args.model, question,
+        async prepareImage(signal) {
+          // 会话扫描、解引用与读图都属于这次操作的总预算。
+          const hit = (await waitForModelWork(() => sessionAttachmentRef(host, exec, id), signal)) || findOwnAttachment(id);
+          if (!hit) throw new Error('iris: 图片引用不可用');
+          if (hit.absPath) return readVisionImageFile(hit.absPath, hit.ref.mediaType || MEDIA_TYPES[path.extname(hit.absPath).toLowerCase()] || 'image/png', signal);
+          const stored = await waitForModelWork(() => attachmentService(host).readImage(hit.ref, signal), signal);
+          return { bytes: new Uint8Array(stored.data), mediaType: stored.mediaType || hit.ref.mediaType };
+        }
+      });
     }
   });
 
@@ -866,13 +905,14 @@ export async function apply(ctx) {
   safeRegister(host, {
     name: 'iris_locate',
     description:
-      'Locate an object/region described by `target` in an image (absolute path or session attachment_id), ' +
+      'Locate an object/region described by `target` in an image (exactly one of absolute image_path, Core artifact_id, or session attachment_id), ' +
       'returning the pixel bounding box (x1,y1,x2,y2) in original image coordinates. ' +
-      'Use the returned bbox with iris_crop to extract the region.',
+      'Use the bbox with iris_crop for path/session images or CLI run crop with artifact_id for Core images; do not treat a Core ID as a file path.',
     parameters: {
       type: 'object',
       properties: {
         image_path: { type: 'string', description: 'Absolute path to the source image (png/jpg/jpeg/webp)' },
+        artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of an image (alternative to image_path)' },
         target: { type: 'string', description: 'The object or UI element to locate, e.g. "send button"' },
         model: { type: 'string', description: 'Override the vision model for this locate call (e.g. qwen3-vl-235b-a22b-thinking for higher grounding precision; default is the provider visionModel, typically qwen-vl-plus)' }
@@ -882,23 +922,15 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      const input = await resolveImageInput(dshHost(ctx), exec, {
-        image_path: args.image_path,
-        attachment_id: args.attachment_id
+      const r = await runLocateRequest(dshHost(ctx), {
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, target: args.target,
+        prepareImage: signal => resolveVisionImageInput(dshHost(ctx), exec, args, signal), signal: exec.signal
       });
-      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 = buildVisionBackendsFromHost(dshHost(ctx), { providers: visionProviders, model: args.model });
-      const r = await locateObject(backends, {
-        target: args.target,
-        imageDataUrl: dataUrl,
-        width,
-        height,
-        signal: exec.signal
-      });
-      if (!r.found) return `[iris] 在图片中未找到「${args.target}」（${r.via} · ${r.model}）`;
+      const { width, height } = r;
+      const sourceNote = args.artifact_id ? `\nCore Artifact: ${args.artifact_id}` : '';
+      if (!r.found) return `[iris] 在图片中未找到「${args.target}」（${r.via} · ${r.model}）${sourceNote}`;
+      if (args.artifact_id) return `[iris] 定位「${args.target}」：bbox (${r.x1},${r.y1},${r.x2},${r.y2}) / ${width}x${height}（${r.via} · ${r.model}）${sourceNote}\n` +
+        `裁剪区域：left=${r.x1}, top=${r.y1}, width=${r.x2 - r.x1}, height=${r.y2 - r.y1}`;
       return `[iris] 定位「${args.target}」：bbox (${r.x1},${r.y1},${r.x2},${r.y2}) / ${width}x${height}（${r.via} · ${r.model}）\n` +
         `裁剪指令：iris_crop(image_path="${args.image_path || args.attachment_id}", left=${r.x1}, top=${r.y1}, width=${r.x2 - r.x1}, height=${r.y2 - r.y1})`;
     }
@@ -928,7 +960,8 @@ export async function apply(ctx) {
     async execute(args, exec) {
       if (exec.signal && exec.signal.aborted) throw new Error('已取消');
       const browser = requireHostPort(dshHost(ctx), 'browser', 'HTML 截图');
-      const rendered = await browser.renderHtml({
+      const rendered = await htmlForDsh({
+        browser,
         html: args.html,
         width: args.width,
         height: args.height,
@@ -947,7 +980,7 @@ export async function apply(ctx) {
           {
             type: 'text',
             text: `[iris] HTML 截图完成（${outW}x${outH}，fullPage: ${args.fullPage !== false}）\n` +
-              `attachment: ${ref.attachmentId}` +
+              `artifact: ${rendered.artifact.id}\nattachment: ${ref.attachmentId}` +
               `\n注意：渲染在共享浏览器临时标签页中完成，页面短暂可见属正常行为。`
           },
           { type: 'image', attachment: ref }
@@ -960,13 +993,14 @@ export async function apply(ctx) {
   safeRegister(host, {
     name: 'iris_long_ocr',
     description:
-      'OCR a (possibly long) image: slice it into chunks (1200px tall with 120px overlap by default) ' +
+      'OCR a (possibly long) image from exactly one of image_path, Core artifact_id, or session attachment_id: slice it into chunks (1200px tall with 120px overlap by default) ' +
       'and read the text chunk by chunk with the vision model, then join the results in top-to-bottom order. ' +
-      'Returns the full recognized text plus per-chunk details. Good for long screenshots / documents.',
+      'Marks partial results when chunks fail. Cancellation or timeout stops the whole operation. Good for long screenshots / documents.',
     parameters: {
       type: 'object',
       properties: {
         image_path: { type: 'string', description: 'Absolute path to the image (png/jpg/jpeg/webp)' },
+        artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of the image (alternative to image_path)' },
         chunk_height: { type: 'integer', description: 'Chunk height in pixels, default 1200' },
         overlap: { type: 'integer', description: 'Overlap between chunks in pixels to avoid cutting text lines, default 120' }
@@ -976,28 +1010,19 @@ export async function apply(ctx) {
     output: { schema: { type: 'string' }, render: (_args, v) => [{ type: 'text', text: v }] },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      if (exec.signal && exec.signal.aborted) throw new Error('已取消');
-      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 = buildVisionBackendsFromHost(dshHost(ctx), { providers: visionProviders });
-      const result = await longOcr({
-        input: input.buffer,
-        backends,
-        chunkHeight: args.chunk_height || 1200,
-        overlap: args.overlap || 120,
+      const host = dshHost(ctx);
+      const result = await runOcrRequest(host, {
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit,
+        prepareImage: operationSignal => resolveVisionImageInput(host, exec, args, operationSignal),
+        chunkHeight: args.chunk_height,
+        overlap: args.overlap,
         signal: exec.signal
       });
-      const errCount = result.chunks.filter((c) => c.error).length;
-      const head = `[iris] 长截图 OCR 完成：${result.width}x${result.height}px，${result.totalChunks} 块${errCount ? '（' + errCount + ' 块失败）' : ''}\n`;
-      if (!result.fullText) return head + '（未识别到文字）';
-      return head + result.fullText;
+      return formatOcrResult(result) + (args.artifact_id ? `\nCore Artifact: ${args.artifact_id}` : '');
     }
   });
 
-  console.log('[iris] tools registered: iris_draw_image, iris_generate_video, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
+  console.log('[iris] tools registered: iris_draw_image, iris_edit_image, iris_generate_video, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
 };
 
 /* ---------------- 视觉路由（M3 补全）：look/relook 共用执行器 + 降级链 ---------------- */
@@ -1046,12 +1071,35 @@ async function resolveImageInput(host, exec, { image_path, attachment_id }) {
   throw new Error('iris: 需要 image_path 或 attachment_id');
 }
 
+/** 视觉解引用在整体预算内；路径限额读，Host 会话/附件等待可取消。 */
+async function resolveVisionImageInput(host, exec, input, signal) {
+  const source = normalizeVisionImageSource(input, { allowAttachment: true });
+  const { image_path, artifact_id, attachment_id } = input;
+  if (source === 'artifact_id') return visionImageForDsh({ artifactId: artifact_id, signal });
+  if (image_path) {
+    const file = String(image_path).trim();
+    const mediaType = MEDIA_TYPES[path.extname(file).toLowerCase()];
+    if (!path.isAbsolute(file) || !mediaType || mediaType === 'image/gif') throw new Error('invalid vision image');
+    return readVisionImageFile(file, mediaType, signal);
+  }
+  if (attachment_id) {
+    const id = String(attachment_id).trim();
+    const hit = await waitForModelWork(() => sessionAttachmentRef(host, exec, id), signal) || findOwnAttachment(id);
+    if (!hit) throw new Error('unavailable vision attachment');
+    if (hit.absPath) return readVisionImageFile(hit.absPath,
+      hit.ref.mediaType || MEDIA_TYPES[path.extname(hit.absPath).toLowerCase()] || 'image/png', signal);
+    const stored = await waitForModelWork(() => attachmentService(host).readImage(hit.ref, signal), signal);
+    return { bytes: stored.data, mediaType: stored.mediaType || hit.ref.mediaType || 'image/png' };
+  }
+  throw new Error('missing vision image');
+}
+
 /** 在本插件的任务产物里按 attachmentId 找 iris 自生成的图片（relook 的兜底） */
 export function findOwnAttachment(attachmentId) {
   for (const t of tasks.all()) {
     for (const a of t.attachments || []) {
       if (a.attachmentId === attachmentId) {
-        const absPath = path.join(outputDir(), a.file);
+        const absPath = path.join(tasks.outputsDir(), a.file);
         if (fs.existsSync(absPath)) {
           return { ref: { attachmentId: a.attachmentId, mediaType: a.mediaType }, absPath };
         }
@@ -1087,44 +1135,26 @@ export async function sessionAttachmentRef(host, exec, attachmentId) {
  * 全局视觉模型兜底；每个后端的失败现场保留在 errors 里。
  * @returns {{answer:string,via:'selfstack'|'global',model?:string,backendId:string}}
  */
-export async function askVision(host, { question, ref, dataUrl, signal, model }) {
+export async function askVision(host, { question, dataUrl, image, prepareImage, signal, model, budget }) {
   const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-  const backends = buildVisionBackendsFromHost(host, { providers: visionProviders, model });
-  return askWithBackends(backends, { question, ref, imageDataUrl: dataUrl, signal });
+  return runVisionRequest(host, { providers: visionProviders, model, question, dataUrl, image, prepareImage, signal, budget, onRateLimit: store.recordRateLimit });
 }
 
 /**
  * look / relook 共用执行器：看图问答 → 人话结果（标注模型归属，方便排查走哪条链）。
  * @returns {Promise<string>} 直接作为工具输出
  */
-export async function runVisionTool(host, exec, { origin, model, question, ref, dataUrl }) {
+export async function runVisionTool(host, exec, { origin, model, question, dataUrl, image, prepareImage, artifactId }) {
   if (exec && exec.signal && exec.signal.aborted) throw new Error('已取消');
   const { answer, via, model: usedModel } = await askVision(host, {
     question,
-    ref,
     dataUrl,
+    image,
+    prepareImage,
     signal: exec && exec.signal,
     model
   });
   const label = origin === 'relook' ? '重看回答' : '看图回答';
   const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
-  return `[iris] ${label}（${usedModel || '默认'} · ${viaLabel}）：\n${answer}`;
-}
-
-/* ---------------- 视觉自述（画图后增强项）：走 askVision 降级链，失败静默 ---------------- */
-async function describeFirstImage(host, ref, absPath, originalPrompt) {
-  try {
-    const mt = MEDIA_TYPES[path.extname(absPath).toLowerCase()] || 'image/png';
-    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);
+  return `[iris] ${label}（${usedModel || '默认'} · ${viaLabel}）：\n${answer}` + (artifactId ? `\nCore Artifact: ${artifactId}` : '');
 }