@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/dsh-text-model-adapter.js

@@ -0,0 +1,222 @@
+'use strict';
+/** DSH textModel 的单轮协议映射；宿主路由/会话封闭在适配器，不进入共享请求。 */
+import crypto from 'node:crypto';
+import { ModelPortError, modelErrorRecord, normalizeModelDescriptor, normalizeModelCall,
+  normalizeModelCompletion, createModelTextCollector } from './model-port-contract.js';
+
+const OFF_IDS = new Set(['off', 'none', 'disabled', 'disable', 'no-thinking']);
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256
+  && value === value.trim() && !/[\u0000-\u001f\u007f]/.test(value) && !value.startsWith('/') && !value.includes('://');
+
+function abortError(signal, stage, invocation) {
+  const code = modelErrorRecord(signal?.reason).code === 'IRIS_MODEL_TIMEOUT' ? 'IRIS_MODEL_TIMEOUT' : 'IRIS_MODEL_ABORTED';
+  return new ModelPortError(code, { stage, invocation });
+}
+
+/** 信号传入底层；race 仅保证不合作的元数据/迭代器不会让本地永远挂住。 */
+async function wait(work, signal, stage, invocation) {
+  if (!signal) return work;
+  let onAbort;
+  const canceled = new Promise((_, reject) => {
+    onAbort = () => reject(abortError(signal, stage, invocation));
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  });
+  try { return await Promise.race([work, canceled]); }
+  finally { signal.removeEventListener('abort', onAbort); }
+}
+
+function descriptorFor(binding, metadata, kind = 'text') {
+  const efforts = metadata?.reasoning?.efforts;
+  const ids = Array.isArray(efforts) ? [...new Set(efforts.map(value => value?.id).filter(validId))] : [];
+  const offId = ids.find(id => OFF_IDS.has(id.toLowerCase()));
+  const known = Array.isArray(efforts) && efforts.every(value => validId(value?.id));
+  return { descriptor: normalizeModelDescriptor({ contractVersion: 0, kind,
+    identity: { origin: 'host', backendId: 'dsh-' + kind + ':' + crypto.createHash('sha256').update(JSON.stringify([binding.provider, binding.model])).digest('hex'),
+      providerId: binding.provider, modelId: binding.model }, availability: 'available',
+    // 这些字段有明确的 DSH GenerateOptions 映射，不代表已证明远端模型能力。
+    features: { system: 'supported', temperature: 'supported', maxOutputTokens: 'supported', reasoning: known ? 'supported' : 'unknown' },
+    ...(known ? { reasoning: { off: offId ? 'supported' : 'unsupported', effortIds: ids } } : {}) }), offId: known ? offId : undefined };
+}
+
+function usageSnapshot(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  const usage = {};
+  for (const key of ['outputTokens', 'totalTokens', 'reasoningTokens']) {
+    if (Number.isSafeInteger(value[key]) && value[key] >= 0) usage[key] = value[key];
+  }
+  // rc.2 inputTokens 不含缓存；这里只把权威的三个不重叠输入计数相加。
+  const inputs = [value.inputTokens, value.cacheReadTokens ?? 0, value.cacheWriteTokens ?? 0];
+  const inputTotal = inputs.reduce((sum, count) => sum + count, 0);
+  if (inputs.every(count => Number.isSafeInteger(count) && count >= 0) && Number.isSafeInteger(inputTotal)) usage.inputTokens = inputTotal;
+  return Object.keys(usage).length ? usage : undefined;
+}
+
+/** 元数据解析显式进行且受同一操作信号约束；describe 永远只复制已绑定事实。 */
+export async function prepareDshTextModelPort(textModel, binding, { signal } = {}) {
+  if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+  if (!textModel || typeof textModel.stream !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  if (!validId(binding?.provider) || !validId(binding?.model)) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const route = { provider: binding.provider, model: binding.model };
+  const sessionId = typeof binding.sessionId === 'string' && binding.sessionId.trim() && binding.sessionId.length <= 256 ? binding.sessionId.trim() : undefined;
+  let metadata;
+  if (typeof textModel.resolveModelInfo === 'function') {
+    try { metadata = await wait(Promise.resolve().then(() => {
+      if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+      return textModel.resolveModelInfo(route.provider, route.model, signal);
+    }), signal, 'prepare', 'not_invoked'); }
+    catch (_) { if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked'); }
+  }
+  if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+  return createDshTextModelPort(textModel, { ...route, sessionId }, { metadata });
+}
+
+/** 已绑定事实的纯构造；用于缓存元数据/协议 fixture，不执行元数据查询。 */
+export function createDshTextModelPort(textModel, binding, { metadata } = {}) {
+  return createDshBoundModelPort(textModel, binding, { metadata });
+}
+
+/** 文本与视觉共用经过验证的 DSH 事件读取器；图片桥接仅由视觉适配器注入。 */
+export function createDshBoundModelPort(textModel, binding, { metadata, prepareImage, prepareImageRequest, kind = 'text' } = {}) {
+  if (!textModel || typeof textModel.stream !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  if (!validId(binding?.provider) || !validId(binding?.model)) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const route = { provider: binding.provider, model: binding.model };
+  // 不接受绑定身份与解析出的模型漂移；旧 fixture 未提供身份时保持 unknown。
+  if (metadata && (metadata.provider !== undefined && metadata.provider !== route.provider || metadata.id !== undefined && metadata.id !== route.model)) {
+    throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+  const sessionId = typeof binding.sessionId === 'string' && binding.sessionId.trim() && binding.sessionId.length <= 256 ? binding.sessionId.trim() : undefined;
+  const { descriptor, offId } = descriptorFor(route, metadata, kind);
+  const port = Object.freeze({
+    describe() { return normalizeModelDescriptor(descriptor); },
+    async complete(request, options) {
+      const input = normalizeModelCall(descriptor, request, options);
+      if (input.options.signal?.aborted) throw abortError(input.options.signal, 'invoke', 'not_invoked');
+      const controller = new AbortController();
+      const parent = input.options.signal;
+      const onAbort = () => controller.abort(parent.reason);
+      parent?.addEventListener('abort', onAbort, { once: true });
+      const deadline = performance.now() + input.options.budget.timeoutMs;
+      let timer;
+      const scheduleDeadline = () => {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) controller.abort(new ModelPortError('IRIS_MODEL_TIMEOUT'));
+        else timer = setTimeout(scheduleDeadline, Math.min(2147483647, Math.ceil(remaining)));
+      };
+      scheduleDeadline();
+      const signal = controller.signal;
+      const collector = createModelTextCollector({ maxOutputChars: input.options.budget.maxOutputChars, signal, backendId: descriptor.identity.backendId });
+      const sourceRequest = { ...route, messages: [{ role: 'user', content: [{ type: 'text', text: input.request.prompt }] }],
+        ...(input.request.system === undefined ? {} : { system: input.request.system }), signal,
+        ...(sessionId ? { sessionId } : {}) };
+      if (input.request.generation?.temperature !== undefined) sourceRequest.temperature = input.request.generation.temperature;
+      if (input.request.generation?.maxOutputTokens !== undefined) sourceRequest.maxTokens = input.request.generation.maxOutputTokens;
+      const reasoning = input.request.generation?.reasoning;
+      if (reasoning?.mode === 'off') sourceRequest.reasoningEffort = offId;
+      if (reasoning?.mode === 'effort') sourceRequest.reasoningEffort = reasoning.effortId;
+      let iterator;
+      let usage;
+      let finished = false;
+      let ended = false;
+      let invoked = false;
+      let responded = false;
+      let prepared;
+      const blocks = new Map();
+      const blockId = index => {
+        if (!Number.isSafeInteger(index) || index < 0) throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'read', invocation: 'unknown' });
+        return String(index);
+      };
+      try {
+        if (kind === 'vision') {
+          if (typeof prepareImage !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+          const preparedImage = await wait(Promise.resolve().then(() => {
+            if (signal.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+            return prepareImage(input.request.image, signal);
+          }), signal, 'prepare', 'not_invoked');
+          if (signal.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+          prepared = await wait(Promise.resolve().then(() => prepareImageRequest?.({ request: input.request,
+            image: preparedImage.image, signal, identity: descriptor.identity })), signal, 'prepare', 'not_invoked');
+          const prompt = prepared?.prompt ?? input.request.prompt;
+          normalizeModelCall(descriptor, { ...input.request, image: preparedImage.image, prompt }, input.options);
+          sourceRequest.messages[0].content[0].text = prompt;
+          sourceRequest.messages[0].content.push({ type: 'image', attachment: preparedImage.attachment });
+        }
+        invoked = true;
+        const stream = textModel.stream(sourceRequest);
+        if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'invoke', invocation: 'unknown' });
+        iterator = stream[Symbol.asyncIterator]();
+        while (true) {
+          const next = await wait(Promise.resolve().then(() => iterator.next()), signal, 'read', responded ? 'responded' : 'unknown');
+          if (signal.aborted) throw abortError(signal, 'read', responded ? 'responded' : 'unknown');
+          if (next.done) { ended = true; break; }
+          const chunk = next.value;
+          if (!chunk || typeof chunk !== 'object' || finished) throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'read', invocation: 'responded' });
+          if (chunk.type === 'block-start') {
+            const id = blockId(chunk.index);
+            if (!['text', 'reasoning'].includes(chunk.blockType)) collector.finish(chunk.blockType === 'tool-call' ? 'tool-calls' : 'unknown');
+            if (blocks.has(id)) collector.finish('unknown');
+            blocks.set(id, chunk.blockType);
+            if (chunk.blockType === 'text') collector.append('', id);
+          } else if (chunk.type === 'text-delta') {
+            const id = blockId(chunk.index);
+            if (blocks.has(id) && blocks.get(id) !== 'text') collector.finish('unknown');
+            blocks.set(id, 'text');
+            if (typeof chunk.text === 'string' && chunk.text.length) responded = true;
+            collector.append(chunk.text, id);
+          } else if (chunk.type === 'reasoning-delta') {
+            const id = blockId(chunk.index);
+            if (typeof chunk.text !== 'string' || blocks.has(id) && blocks.get(id) !== 'reasoning') collector.finish('unknown');
+            blocks.set(id, 'reasoning');
+          } else if (chunk.type === 'block-end') {
+            const id = blockId(chunk.index);
+            if (chunk.block?.type === 'text') {
+              if (blocks.has(id) && blocks.get(id) !== 'text') collector.finish('unknown');
+              blocks.set(id, 'text');
+              if (typeof chunk.block.text === 'string' && chunk.block.text.length) responded = true;
+              collector.replace(chunk.block.text, id);
+            } else if (chunk.block?.type === 'reasoning') {
+              if (typeof chunk.block.text !== 'string' || blocks.has(id) && blocks.get(id) !== 'reasoning') collector.finish('unknown');
+              blocks.set(id, 'reasoning');
+            } else collector.finish(chunk.block?.type === 'tool-call' ? 'tool-calls' : 'unknown');
+          } else if (chunk.type === 'tool-call-delta') collector.finish('tool-calls');
+          else if (chunk.type === 'usage') usage = usageSnapshot(chunk.usage);
+          else if (chunk.type === 'finish') {
+            const kind = chunk.reason?.kind;
+            if (kind === 'aborted') throw new ModelPortError('IRIS_MODEL_ABORTED', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+            if (kind === 'error') collector.fail(new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'read', invocation: 'unknown' }));
+            collector.finish(kind); finished = true;
+          } else if (chunk.type === 'error') collector.fail(chunk.error);
+          else if (chunk.type === undefined && typeof chunk.delta === 'string') {
+            if (chunk.delta.length) responded = true;
+            collector.append(chunk.delta, '0');
+          }
+          else collector.finish('unknown');
+        }
+        const collected = collector.complete();
+        const text = prepared?.mapText ? prepared.mapText(collected) : collected;
+        return normalizeModelCompletion(descriptor, { contractVersion: 0, text, finishReason: 'stop', identity: descriptor.identity,
+          ...(usage ? { usage } : {}) }, input.options.budget);
+      } catch (error) {
+        if (signal.aborted) throw abortError(signal, invoked ? 'read' : 'prepare', responded ? 'responded' : invoked ? 'unknown' : 'not_invoked');
+        if (!invoked) {
+          controller.abort(error);
+          const record = modelErrorRecord(error);
+          throw new ModelPortError(record.code, { stage: 'prepare', invocation: 'not_invoked',
+            ...(record.imageBytes ? { imageBytes: record.imageBytes } : {}),
+            ...(record.imageMaxBytes ? { imageMaxBytes: record.imageMaxBytes } : {}) });
+        }
+        // 只有受控模型错误可以离开协议边界；供应商原文不进入 UI/日志。
+        try { collector.fail(error); }
+        finally { controller.abort(error); }
+      } finally {
+        try {
+          if (!ended && iterator && typeof iterator.return === 'function') {
+            const closing = Promise.resolve().then(() => iterator.return());
+            await wait(closing, signal, 'read', 'unknown').catch(() => {});
+          }
+        } finally { clearTimeout(timer); parent?.removeEventListener('abort', onAbort); }
+      }
+    }
+  });
+  return Object.freeze({ port, offId });
+}

package/lib/dsh-vision-model-adapter.js

@@ -0,0 +1,75 @@
+'use strict';
+import { ModelPortError } from './model-port-contract.js';
+import { createDshBoundModelPort } from './dsh-text-model-adapter.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { createHash } from 'node:crypto';
+import sharp from 'sharp';
+import { prepareVisionImage } from './vision-image-input.js';
+
+/** rc.2 只接受附件引用；业务钩子使用核验后真正发给宿主的图片。 */
+export function createDshVisionModelPort(textModel, attachments, binding, { metadata, allowImageNormalization = false,
+  imageInput, orientImages = false, prepareImageRequest } = {}) {
+  if (!attachments || typeof attachments.saveImage !== 'function' || typeof attachments.readImage !== 'function') {
+    throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+  }
+  if (!metadata || metadata.provider !== binding?.provider || metadata.id !== binding?.model
+      || !Array.isArray(metadata.inputModalities) || !metadata.inputModalities.includes('image')) {
+    throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+  }
+  return createDshBoundModelPort(textModel, binding, { metadata, kind: 'vision', prepareImageRequest,
+    async prepareImage(image, signal) {
+      if (imageInput) image = await prepareVisionImage(image, imageInput, { signal, orient: orientImages });
+      const data = new Uint8Array(image.bytes);
+      // saveImage 在 rc.2 无取消参数；等待有界，迟到保存可留下 Host 附件，但绝不启动生成。
+      const ref = await waitForModelWork(() => attachments.saveImage({ data, mediaType: image.mediaType, name: 'iris-vision' }), signal);
+      if (!ref || typeof ref.attachmentId !== 'string' || !ref.attachmentId) {
+        throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+      }
+      const stored = await waitForModelWork(() => attachments.readImage(ref, signal), signal);
+      if (!(stored?.data instanceof Uint8Array) || stored.mediaType !== undefined && stored.mediaType !== ref.mediaType) {
+        throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+      }
+      const unchanged = ref.mediaType === image.mediaType && Buffer.from(stored.data).equals(Buffer.from(image.bytes));
+      if (!unchanged) {
+        // 正规宿主附件用内容哈希绑定读回字节；任意旧引用/损坏数据不能冒充压缩副本。
+        if (!allowImageNormalization || ref.attachmentId !== 'sha256:' + createHash('sha256').update(stored.data).digest('hex')
+            || ref.bytes !== stored.data.byteLength) throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+        const [source, normalized] = await waitForModelWork(() => Promise.all([
+          sharp(Buffer.from(image.bytes)).metadata(), sharp(Buffer.from(stored.data)).metadata()
+        ]), signal);
+        const original = ref.originalDimensions || ref;
+        const width = source.autoOrient?.width || source.width, height = source.autoOrient?.height || source.height;
+        if (original.width !== width || original.height !== height || ref.width !== normalized.width || ref.height !== normalized.height
+            || ref.width > width || ref.height > height
+            || ref.mediaType !== { jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif' }[normalized.format]) {
+          throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+        }
+      }
+      return { attachment: ref, image: { bytes: new Uint8Array(stored.data), mediaType: ref.mediaType } };
+    }
+  }).port;
+}
+
+/** 只在显式调用时读取默认选择/精确元数据；不把默认文本模型猜成视觉模型。 */
+export async function prepareDshVisionModelPort(textModel, attachments, { signal, ...options } = {}) {
+  try { return await waitForModelWork(async () => {
+    if (typeof textModel?.currentSelection !== 'function' || typeof textModel?.resolveModelInfo !== 'function') {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    if (typeof attachments?.saveImage !== 'function' || typeof attachments?.readImage !== 'function') {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    const selection = textModel.currentSelection();
+    if (typeof selection?.provider !== 'string' || !selection.provider.trim()
+        || typeof selection?.model !== 'string' || !selection.model.trim()) {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    const binding = { provider: selection.provider, model: selection.model };
+    const metadata = await waitForModelWork(() => textModel.resolveModelInfo(binding.provider, binding.model, signal), signal);
+    return createDshVisionModelPort(textModel, attachments, binding, { metadata, ...options });
+  }, signal); }
+  catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+}

package/lib/generation-input.js

@@ -1,10 +1,11 @@
 'use strict';
 
 import path from 'node:path';
+import fs from 'node:fs';
 
 const FIELDS = Object.freeze({
-  image: ['prompt', 'size', 'n'],
-  video: ['prompt', 'size', 'duration', 'img_data_url'],
+  image: ['prompt', 'size', 'n', 'source_artifact_id'],
+  video: ['prompt', 'size', 'duration', 'img_data_url', 'first_frame_path', 'audio_path', 'resolution'],
   tts: ['text', 'voice'],
   transcribe: ['audio_url', 'audio_path']
 });
@@ -33,7 +34,7 @@ function text(value, field, maxLength, required = false) {
  * 不读取配置或文件，不上传，不从旧 Task 恢复 Prompt/媒体地址。
  * Host 附件解析和本地音频上传仍由入口负责。
  */
-export function normalizeGenerationInput(capability, input, { allowAudioPath = false } = {}) {
+export function normalizeGenerationInput(capability, input, { allowAudioPath = false, allowVideoPaths = false } = {}) {
   const fields = Object.hasOwn(FIELDS, capability) ? FIELDS[capability] : null;
   if (!fields) fail('不支持的生成能力');
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail('生成输入必须是 JSON 对象');
@@ -45,12 +46,40 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   const modelRef = String(input.model_ref || '').trim();
   const providerInput = {};
   let audioPath;
+  let sourceArtifactId;
+  let firstFramePath, videoMode;
+  if (capability === 'video') {
+    audioPath = String(input.audio_path || '').trim();
+    firstFramePath = String(input.first_frame_path || '').trim();
+    if ((audioPath || firstFramePath) && !allowVideoPaths) fail('本地视频输入需要支持上传的入口');
+    if (firstFramePath && input.img_data_url !== undefined) fail('首帧路径与 img_data_url 不能同时提供');
+    for (const file of [firstFramePath, audioPath].filter(Boolean)) {
+      if (!path.isAbsolute(file)) fail('首帧和音频路径必须是绝对路径');
+      try { if (!fs.statSync(file).isFile()) throw new Error(); }
+      catch (_) { fail('首帧或音频文件不存在或不是普通文件'); }
+    }
+    if (audioPath && !firstFramePath) fail('s2v 需要 first_frame_path 和 audio_path');
+    videoMode = audioPath ? 's2v' : firstFramePath || input.img_data_url ? 'i2v' : 't2v';
+    if (videoMode === 's2v') {
+      if (input.size !== undefined || input.duration !== undefined || input.img_data_url !== undefined) fail('s2v 不支持 size、duration 或 img_data_url');
+      const resolution = input.resolution ?? '480P';
+      if (!['480P', '720P'].includes(resolution)) fail('s2v resolution 只支持 480P 或 720P');
+      providerInput.resolution = resolution;
+    } else if (input.resolution !== undefined) fail('resolution 仅适用于 s2v');
+  }
   if (capability === 'image' || capability === 'video') {
-    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    const prompt = text(input.prompt, 'prompt', 20000, videoMode !== 's2v');
+    if (prompt !== undefined) providerInput.prompt = prompt;
     const size = text(input.size, 'size', 64);
     if (size !== undefined) providerInput.size = size;
   }
   if (capability === 'image') {
+    if (input.source_artifact_id !== undefined) {
+      if (typeof input.source_artifact_id !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(input.source_artifact_id)) {
+        fail('source_artifact_id 必须是有效的 Core Artifact ID');
+      }
+      sourceArtifactId = input.source_artifact_id;
+    }
     const n = input.n === undefined ? 1 : Number(input.n);
     if (!Number.isSafeInteger(n) || n < 1 || n > 4) fail('n 必须为 1–4 的整数');
     providerInput.n = n;
@@ -90,6 +119,8 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   return Object.freeze({
     modelRef,
     providerInput: Object.freeze(providerInput),
-    ...(audioPath ? { audioPath } : {})
+    ...(sourceArtifactId ? { sourceArtifactId } : {}),
+    ...(audioPath ? { audioPath } : {}),
+    ...(capability === 'video' ? { firstFramePath, videoMode } : {})
   });
 }

package/lib/headless-vision.js

@@ -0,0 +1,181 @@
+'use strict';
+/** 独立视觉入口：显式配置/媒体，已有 Core 帧只读，主动转写使用 writer。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import sharp from 'sharp';
+import { CommandError } from './command-service.js';
+import { visionCandidatesFromCatalog, transcribeCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding } from './provider-catalog.js';
+import { createConfiguredVisionModelPort, readVisionImageFile } from './vision-model-routing.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { prepareProviderInput } from './provider-adapter.js';
+import { createProviderTaskRunner } from './provider-task-runner.js';
+import { CoreArtifactError, readCoreArtifactBytes } from './core-artifacts.js';
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelErrorRecord } from './model-port-contract.js';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { locateObject, createLocateImageRequest } from './locate.js';
+import { createVisionInputObserver } from './vision-image-input.js';
+import { longOcr, normalizeOcrSettings, formatOcrResult } from './ocr.js';
+import { summarizeMedia } from './summarize.js';
+import { normalizeSummarySource, readSummaryFrames, summaryFrameRecords } from './summary-input.js';
+import { normalizeVisionImageSource, readVisionArtifact } from './vision-input.js';
+import { extractFrames, normalizeFramesOptions, probeVideo, extractAudioTrack, ffmpegAvailable } from './media-probe.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+function invalid(message) { throw new CommandError('IRIS_COMMAND_INPUT_INVALID', message); }
+
+export function normalizeVisionInput(command, input) {
+  const fields = {
+    look: ['image_path', 'artifact_id', 'question'], locate: ['image_path', 'artifact_id', 'target'],
+    ocr: ['image_path', 'artifact_id', 'chunk_height', 'overlap', 'max_dimension', 'max_invocations'],
+    summarize: ['video_path', 'frame_artifact_ids', 'question', 'max_frames', 'target_width', 'transcribe_text', 'transcribe', 'transcribe_model_ref']
+  }[command];
+  if (!fields) invalid('未知视觉命令');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) invalid('--input 必须是 JSON 对象');
+  if (Object.keys(input).some(key => !fields.includes(key))) invalid('视觉输入含不支持的字段');
+  const fileField = command === 'summarize' ? 'video_path' : 'image_path';
+  const fileSource = command === 'summarize' ? normalizeSummarySource(input) === 'video'
+    : normalizeVisionImageSource(input) === 'image_path';
+  if (fileSource) {
+    if (typeof input[fileField] !== 'string' || !path.isAbsolute(input[fileField])) invalid(fileField + ' 必须是绝对路径');
+    try { if (!fs.statSync(input[fileField]).isFile()) throw new Error(); }
+    catch (_) { invalid('输入媒体文件不存在或不是普通文件'); }
+  }
+  for (const field of ['question', 'target', 'transcribe_text', 'transcribe_model_ref']) {
+    if (input[field] !== undefined && typeof input[field] !== 'string') invalid(field + ' 必须是字符串');
+  }
+  if (command === 'locate' && !input.target?.trim()) invalid('target 必须是非空字符串');
+  if (input.transcribe !== undefined && typeof input.transcribe !== 'boolean') invalid('transcribe 必须是布尔值');
+  if (input.transcribe && input.transcribe_text?.trim()) invalid('transcribe 与 transcribe_text 不能同时使用');
+  if (input.transcribe_model_ref !== undefined && !input.transcribe) invalid('transcribe_model_ref 需要 transcribe=true');
+  if (input.transcribe_model_ref !== undefined && !/^[^:]+::.+$/.test(input.transcribe_model_ref)) invalid('transcribe_model_ref 必须是 providerId::modelId');
+  if (command === 'ocr') normalizeOcrSettings({ chunkHeight: input.chunk_height, overlap: input.overlap,
+    maxDimension: input.max_dimension, maxInvocations: input.max_invocations });
+  if (command === 'summarize') {
+    try { normalizeFramesOptions({ maxFrames: input.max_frames, targetWidth: input.target_width }); }
+    catch (_) { invalid('max_frames 或 target_width 无效'); }
+  }
+  return input;
+}
+
+function selectedModel(completion, routes) {
+  const route = routes.find(value => value.provider.id === completion.identity?.providerId && value.model === completion.identity?.modelId);
+  return route ? { modelRef: route.modelRef, selectionReason: route.selectionReason } : {};
+}
+
+function completionResult(completion, routes) {
+  const { sheet: _sheet, ...result } = completion;
+  return { ...result, ...selectedModel(completion, routes) };
+}
+
+async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) {
+  const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref);
+  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit }),
+    model: route.modelRef, selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) }));
+  const audio = await waitForModelWork(() => extractAudioTrack({ inputPath: input.video_path, signal: operation.signal }), operation.signal);
+  const abortRuntime = () => { void runtime.dispose().catch(() => {}); };
+  operation.signal.addEventListener('abort', abortRuntime, { once: true });
+  let task;
+  try {
+    const prepared = await waitForModelWork(() => prepareProviderInput(candidates[0].adapter, {
+      model: routes[0].model, filePath: audio.filePath, signal: operation.signal
+    }), operation.signal);
+    const runner = createProviderTaskRunner(runtime);
+    const submitted = await waitForModelWork(() => runner.submit({ capability: 'transcribe', candidates,
+      providerInput: { audioUrl: prepared.url } }), operation.signal, 'invoke', 'unknown');
+    task = submitted.task;
+    if (task.acceptance === 'accepted' && task.outcome === 'none') {
+      const adapter = createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task), { onRateLimit,
+        modelId: routes.find(route => route.modelRef === task.modelRef)?.model });
+      while (task.outcome === 'none') {
+        task = await waitForModelWork(() => runner.observe(task.id, adapter), operation.signal, 'read', 'responded');
+        if (task.outcome === 'none') await waitForModelWork(() => delay(1000, undefined, { signal: operation.signal }), operation.signal);
+      }
+    }
+    const report = { taskId: task.id, modelRef: task.modelRef, artifactIds: task.artifactIds, status: 'failed' };
+    if (task.outcome !== 'succeeded' || task.deliveryState !== 'ready') return { report, text: '' };
+    const texts = await runtime.run('inspect', ({ dataRoot }) => task.artifactIds.map(id => {
+      const artifact = readCoreArtifactBytes(dataRoot, id);
+      return artifact.artifact.mediaType.startsWith('text/') ? artifact.bytes.toString('utf8') : '';
+    }));
+    return { report: { ...report, status: 'complete' }, text: texts.filter(Boolean).join('\n') };
+  } catch (error) {
+    const record = modelErrorRecord(error);
+    if (['IRIS_MODEL_ABORTED', 'IRIS_MODEL_TIMEOUT'].includes(record.code)) throw error;
+    return { report: { status: 'failed', code: record.code, ...(task ? { taskId: task.id, modelRef: task.modelRef, artifactIds: task.artifactIds } : {}) }, text: '' };
+  } finally {
+    operation.signal.removeEventListener('abort', abortRuntime);
+    fs.rmSync(audio.outDir, { recursive: true, force: true });
+  }
+}
+
+export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit }) {
+  normalizeVisionInput(command, input);
+  if (modelRef && !/^[^:]+::.+$/.test(modelRef)) invalid('--model-ref 必须是 providerId::modelId');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > VISION_BUDGET.timeoutMs) invalid('--timeout-ms 必须是 1–120000 的整数');
+  if (input.transcribe && !runtime) invalid('主动音轨转写需要 --data-root');
+  if ((input.artifact_id || input.frame_artifact_ids) && !runtime) invalid('读取 Core Artifact 需要 --data-root');
+  const routes = visionCandidatesFromCatalog(catalog, modelRef);
+  const inputs = new Map();
+  const prepareImageRequest = command === 'locate' ? createLocateImageRequest(input.target, inputs)
+    : command === 'ocr' ? createVisionInputObserver(inputs) : undefined;
+  const ports = routes.map(route => createConfiguredVisionModelPort(route.provider, route.model, { onRateLimit,
+    prepareImages: ['look', 'ocr', 'locate'].includes(command), orientImages: command === 'locate', prepareImageRequest }));
+  const budget = { ...VISION_BUDGET, timeoutMs };
+  const operation = createModelOperation({ signal, budget: { timeoutMs, maxInvocations: command === 'ocr' ? input.max_invocations ?? 64 : ports.length } });
+  const base = { schemaVersion: 1, command: 'vision.' + command, status: 'complete',
+    ...(input.artifact_id ? { artifactId: input.artifact_id } : {}) };
+  try {
+    if (command === 'summarize') {
+      let meta, frames;
+      if (input.frame_artifact_ids) {
+        ({ meta, frames } = await readSummaryFrames(runtime, input.frame_artifact_ids, operation.signal));
+      } else {
+        if (!ffmpegAvailable()) throw new CommandError('IRIS_MEDIA_TOOL_UNAVAILABLE', '视频摘要需要 PATH 中的 ffmpeg 和 ffprobe');
+        meta = await waitForModelWork(() => probeVideo(input.video_path), operation.signal);
+        frames = await waitForModelWork(() => extractFrames({ inputPath: input.video_path,
+          maxFrames: input.max_frames, targetWidth: input.target_width, signal: operation.signal }), operation.signal);
+      }
+      let transcript = input.transcribe_text || '', transcription = { status: transcript.trim() ? 'provided' : 'disabled' };
+      if (input.transcribe) {
+        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) : { report: { status: 'no_audio' }, text: '' };
+        transcript = asr.text; transcription = asr.report;
+      }
+      const completion = await summarizeMedia({ ports, frames, question: input.question, transcript, operation, budget });
+      const sheet = completion.sheet;
+      const note = transcription.status === 'failed' ? '音轨转写失败，本次摘要只分析画面。' : '';
+      if (note) transcription.note = note;
+      return { result: { ...base, ...completionResult(completion, routes), meta,
+        frames: summaryFrameRecords(frames), transcription,
+        contactSheet: { mediaType: 'image/png', width: sheet.width, height: sheet.height,
+          sha256: createHash('sha256').update(sheet.buffer).digest('hex') } }, text: completion.text + (note ? '\n\n[iris] ' + note : ''), sheetBuffer: sheet.buffer, exitCode: 0 };
+    }
+    let image;
+    if (input.artifact_id) image = await readVisionArtifact(runtime, input.artifact_id, operation.signal);
+    else {
+      const mediaType = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(input.image_path).toLowerCase()];
+      if (!mediaType) invalid('图片只支持 PNG、JPEG、WebP、GIF');
+      image = await readVisionImageFile(input.image_path, mediaType, operation.signal);
+    }
+    if (command === 'ocr') {
+      const ocr = await longOcr({ image, ports, chunkHeight: input.chunk_height, overlap: input.overlap,
+        maxDimension: input.max_dimension, maxInvocations: input.max_invocations, operation, budget, inputs });
+      return { result: { ...base, ...ocr, chunks: ocr.chunks.map(chunk => ({ ...chunk, ...selectedModel(chunk, routes) })) },
+        text: formatOcrResult(ocr), exitCode: ocr.status === 'complete' ? 0 : 1 };
+    }
+    let completion;
+    if (command === 'locate') {
+      const { width, height } = await waitForModelWork(() => sharp(Buffer.from(image.bytes)).metadata(), operation.signal);
+      completion = await locateObject(ports, { target: input.target, image, width, height }, { operation, budget });
+      return { result: { ...base, ...completionResult(completion, routes), width, height,
+        input: inputs.get(completion.identity.backendId) }, text: JSON.stringify(completion.bbox), exitCode: 0 };
+    }
+    completion = await completeVision(ports, { prompt: input.question?.trim() || '请用中文描述这张图片的内容。', image }, { operation, budget });
+    return { result: { ...base, ...completionResult(completion, routes) }, text: completion.text, exitCode: 0 };
+  } catch (error) {
+    if (error instanceof ModelPortError || error instanceof CommandError || error instanceof CoreArtifactError || error.name === 'ProviderCatalogError') throw error;
+    throw new ModelPortError('IRIS_MODEL_INPUT_INVALID', { stage: 'prepare', invocation: 'not_invoked' });
+  } finally { operation.dispose(); }
+}

package/lib/host-runtime.js

@@ -11,6 +11,7 @@ export const HOST_CLIENT_PROTOCOL_VERSION = 0;
 
 export const EXPECTED_IRIS_TOOLS = Object.freeze([
   'iris_draw_image',
+  'iris_edit_image',
   'iris_generate_video',
   'iris_speak_text',
   'iris_transcribe_audio',