@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/lib/dsh-host-adapter.js

@@ -41,6 +41,24 @@ function unavailableFor(value, reason) {
   return { kind: value ? 'incompatible' : 'unavailable', reason };
 }
 
+function imageAttachmentDto(ref) {
+  const out = {
+    attachmentId: ref.attachmentId,
+    mediaType: ref.mediaType,
+    name: typeof ref.name === 'string' ? ref.name : ''
+  };
+  // readImage 会核对这三项完整性事实；省略未知值，不从 ID/文件名猜测。
+  for (const key of ['bytes', 'width', 'height']) {
+    if (Number.isSafeInteger(ref[key]) && ref[key] > 0) out[key] = ref[key];
+  }
+  const original = ref.originalDimensions;
+  if (original && Number.isSafeInteger(original.width) && original.width > 0
+      && Number.isSafeInteger(original.height) && original.height > 0) {
+    out.originalDimensions = Object.freeze({ width: original.width, height: original.height });
+  }
+  return Object.freeze(out);
+}
+
 function collectImageAttachments(nodes) {
   const out = [];
   const ids = new Set();
@@ -59,11 +77,7 @@ function collectImageAttachments(nodes) {
         && typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/')
         && !ids.has(ref.attachmentId)) {
       ids.add(ref.attachmentId);
-      out.push(Object.freeze({
-        attachmentId: ref.attachmentId,
-        mediaType: ref.mediaType,
-        name: typeof ref.name === 'string' ? ref.name : ''
-      }));
+      out.push(imageAttachmentDto(ref));
     }
     for (const value of Object.values(node)) if (value && typeof value === 'object') stack.push(value);
   }
@@ -75,16 +89,41 @@ function registerWithEffect(ctx, registry, definition) {
   return registry.register(definition);
 }
 
-function dshVisionPort(llm) {
+function visionRouteError(message) {
+  return Object.assign(new Error(message), { code: 'IRIS_HOST_CAPABILITY_INCOMPATIBLE' });
+}
+
+function dshVisionPort(llm, { defaults, requiresRoute }) {
   return Object.freeze({
     id: 'dsh-global',
     model: '全局视觉模型',
     async analyze({ question, ref, signal }) {
+      let route = {};
+      if (requiresRoute) {
+        // rc.2 路由检查前就停止取消请求；旧桥接继续由宿主处理 signal，
+        // 其 fallback 语义待共享调用控制迁移时统一。
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        const selection = defaults.currentSelection();
+        if (typeof selection?.provider !== 'string' || !selection.provider.trim()
+            || typeof selection?.model !== 'string' || !selection.model.trim()) {
+          throw visionRouteError('DSH 默认模型没有明确路由；请在 Iris 配置视觉模型');
+        }
+        // 默认文本选择只有明确声明 image 输入时才可成为视觉候选。
+        const { provider, model } = selection;
+        const info = await llm.resolveModelInfo(provider, model, signal);
+        if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error('已取消');
+        if (info?.provider !== provider || info?.id !== model || !Array.isArray(info.inputModalities)
+            || !info.inputModalities.includes('image')) {
+          throw visionRouteError('DSH 默认模型未确认支持图片；请在 Iris 配置视觉模型或选择已声明图片输入的宿主模型');
+        }
+        route = { provider, model };
+      }
       const chunks = [];
       for await (const chunk of llm.stream({
         sessionId: undefined,
         provider: undefined,
         model: undefined,
+        ...route,
         signal,
         messages: [{
           role: 'user',
@@ -94,6 +133,12 @@ function dshVisionPort(llm) {
           ]
         }]
       })) {
+        if (chunk?.type === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+        // rc.2 的 Runtime 把 Adapter 异常转换为 finish，而不是单独的 error 事件。
+        if (requiresRoute && chunk?.type === 'finish') {
+          if (chunk.reason?.kind === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
+          if (chunk.reason?.kind === 'aborted') throw visionRouteError('DSH 视觉调用已取消');
+        }
         const text = typeof chunk?.delta === 'string'
           ? chunk.delta
           : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
@@ -174,7 +219,13 @@ export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {})
         ? () => defaults.currentSelection()
         : () => null
     });
-    ports.visionModel = dshVisionPort(llm);
+    const requiresRoute = /^0\.2\./.test(version);
+    if (!requiresRoute || defaults && typeof defaults.currentSelection === 'function'
+        && typeof llm.resolveModelInfo === 'function') {
+      ports.visionModel = dshVisionPort(llm, { defaults, requiresRoute });
+    } else unavailable.visionModel = {
+      kind: 'unavailable', reason: 'DSH 0.2 视觉桥接需要默认模型选择和精确图片能力元数据'
+    };
   } else {
     unavailable.textModel = unavailableFor(llm, 'DSH llm 需要 stream');
     unavailable.visionModel = unavailableFor(llm, 'DSH llm 需要 stream');

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

@@ -0,0 +1,126 @@
+'use strict';
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+const FIELDS = Object.freeze({
+  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']
+});
+
+export class GenerationInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GenerationInputError';
+    this.code = 'IRIS_GENERATION_INPUT_INVALID';
+  }
+}
+
+function fail(message) { throw new GenerationInputError(message); }
+
+function text(value, field, maxLength, required = false) {
+  if (value === undefined && !required) return undefined;
+  const normalized = String(value || '').trim();
+  if (!normalized || normalized.length > maxLength) {
+    fail(`${field} 必须为 1–${maxLength} 字符`);
+  }
+  return normalized;
+}
+
+/**
+ * CLI、DSH 与知情重试共用的纯输入边界。只校验/转换调用方重新提供的参数，
+ * 不读取配置或文件，不上传，不从旧 Task 恢复 Prompt/媒体地址。
+ * Host 附件解析和本地音频上传仍由入口负责。
+ */
+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 对象');
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field) && field !== 'model_ref') {
+      fail('生成输入不支持字段：' + field + '；允许 ' + fields.join(', ') + ', model_ref');
+    }
+  }
+  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') {
+    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;
+  }
+  if (capability === 'video') {
+    if (input.duration !== undefined) {
+      const duration = Number(input.duration);
+      if (!Number.isFinite(duration) || duration < 1 || duration > 60) fail('duration 必须为 1–60 的数字');
+      providerInput.duration = duration;
+    }
+    if (input.img_data_url !== undefined) {
+      const imgDataUrl = String(input.img_data_url).trim();
+      if (!imgDataUrl.startsWith('data:image/')) fail('img_data_url 必须是 data:image/ 开头的 data URL');
+      providerInput.imgDataUrl = imgDataUrl;
+    }
+  }
+  if (capability === 'tts') {
+    providerInput.text = text(input.text, 'text', 20000, true);
+    const voice = text(input.voice, 'voice', 64);
+    if (voice !== undefined) providerInput.voice = voice;
+  }
+  if (capability === 'transcribe') {
+    const audioUrl = String(input.audio_url || '').trim();
+    audioPath = String(input.audio_path || '').trim();
+    if (Boolean(audioUrl) === Boolean(audioPath)) {
+      fail('转写必须且只能提供 audio_url（公网/oss://）或 audio_path（本地绝对路径）之一');
+    }
+    if (audioUrl) {
+      if (audioUrl.length > 20000) fail('audio_url 最多为 20000 字符');
+      if (!/^(https:\/\/|oss:\/\/)/.test(audioUrl)) fail('audio_url 必须是 https:// 或 oss:// 地址');
+      providerInput.audioUrl = audioUrl;
+    } else {
+      if (!allowAudioPath) fail('retry 必须重新提供 audio_url；本地音频上传由调用入口负责');
+      if (!path.isAbsolute(audioPath)) fail('audio_path 必须是绝对路径');
+    }
+  }
+  return Object.freeze({
+    modelRef,
+    providerInput: Object.freeze(providerInput),
+    ...(sourceArtifactId ? { sourceArtifactId } : {}),
+    ...(audioPath ? { audioPath } : {}),
+    ...(capability === 'video' ? { firstFramePath, videoMode } : {})
+  });
+}

package/lib/guard.js

@@ -4,7 +4,7 @@
  *
  * `/iris/*` 不经过 DSH 的 `/api` 信任栅栏，因此默认只接受回环 Host。
  * LAN/反代场景需用 IRIS_TRUSTED_HOSTS 显式列出 host 或 host:port；这只是
- * Host 边界，不是身份认证。POST 另外校验 Sec-Fetch-Site 与 Origin==Host。
+ * Host 边界，不是身份认证。浏览器请求另校验 Sec-Fetch-Site 与 Origin==Host。
  */
 
 /** 请求 Host 头 → host:port 规范化（小写，去 IPv6 方括号保留） */
@@ -44,12 +44,12 @@ export function isTrustedHost(hostHeader, configured = process.env.IRIS_TRUSTED_
  */
 export function checkRequest(req, options = {}) {
   const headers = req.headers || {};
-  const method = String(req.method || 'GET').toUpperCase();
   if (!isTrustedHost(headers.host, options.trustedHosts)) {
     return { ok: false, status: 403, error: 'untrusted host' };
   }
-  if (method !== 'POST') return { ok: true };
 
+  // 浏览器的读请求同样可能泄露媒体与状态；明确的跨站/跨源请求一律拒绝。
+  // curl/CLI 等不发送 Origin/Sec-Fetch-Site 的非浏览器客户端仍可在受信 Host 上使用。
   const sfs = String(headers['sec-fetch-site'] || '').toLowerCase();
   if (sfs === 'cross-site') return { ok: false, status: 403, error: 'cross-site request denied' };