@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/summary-input.js

@@ -0,0 +1,52 @@
+'use strict';
+/** CLI/Host 共用的摘要来源：已有帧只读，不导出媒体或重新抽帧。 */
+import { CommandError } from './command-service.js';
+import { readCoreArtifactBytes } from './core-artifacts.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+function invalid(message) { throw new CommandError('IRIS_COMMAND_INPUT_INVALID', message); }
+
+export function normalizeSummarySource(input) {
+  const hasFrames = input.frame_artifact_ids !== undefined;
+  const hasVideo = Boolean(input.video_path);
+  if (hasFrames === hasVideo) invalid('摘要必须且只能提供 video_path 或 frame_artifact_ids 之一');
+  if (hasFrames) {
+    const ids = input.frame_artifact_ids;
+    if (!Array.isArray(ids) || !ids.length || ids.length > 20
+        || !ids.every(id => typeof id === 'string' && /^artifact_[a-f0-9]{24}$/.test(id))
+        || new Set(ids).size !== ids.length) invalid('frame_artifact_ids 必须是 1–20 个不重复的 Core Artifact ID');
+    if (input.max_frames !== undefined || input.target_width !== undefined) invalid('已有帧不使用 max_frames 或 target_width；请直接选择帧 ID');
+    if (input.transcribe === true) invalid('自动音轨转写需要 video_path；已有帧可提供 transcribe_text');
+  }
+  if (input.transcribe_text !== undefined && typeof input.transcribe_text !== 'string') invalid('transcribe_text 必须是字符串');
+  if (input.transcribe === true && input.transcribe_text?.trim()) invalid('transcribe 与 transcribe_text 不能同时使用');
+  return hasFrames ? 'core-artifacts' : 'video';
+}
+
+export async function readSummaryFrames(runtime, frameArtifactIds, signal) {
+  return waitForModelWork(() => runtime.run('inspect', ({ dataRoot }) => {
+    const frames = frameArtifactIds.map(id => {
+      const { artifact, bytes } = readCoreArtifactBytes(dataRoot, id);
+      const { frameIndex, atSec, width, height } = artifact.metadata;
+      if (artifact.kind !== 'video-frame' || !['image/png', 'image/jpeg'].includes(artifact.mediaType)
+          || !Number.isFinite(atSec) || atSec < 0 || !Number.isSafeInteger(frameIndex) || frameIndex < 1
+          || !Number.isSafeInteger(width) || width < 1 || !Number.isSafeInteger(height) || height < 1) {
+        invalid('摘要需要含有效帧序号、时间戳和尺寸的 video-frame Artifact');
+      }
+      return { artifactId: artifact.id, frameIndex, atSec, width, height, buffer: bytes };
+    }).sort((a, b) => a.atSec - b.atSec || a.frameIndex - b.frameIndex);
+    return { frames, meta: { source: 'core-artifacts', startSec: frames[0].atSec, endSec: frames.at(-1).atSec } };
+  }), signal);
+}
+
+export function summaryFrameRecords(frames) {
+  return frames.map(({ artifactId, frameIndex, atSec, width, height }) => ({
+    ...(artifactId ? { artifactId, frameIndex } : {}), atSec, width, height
+  }));
+}
+
+export function summaryTimelineLabel(meta) {
+  return meta.source === 'core-artifacts'
+    ? `${meta.startSec.toFixed(1)}–${meta.endSec.toFixed(1)}s 已选帧`
+    : `${meta.durationSec.toFixed(1)}s`;
+}

package/lib/task-wait.js

@@ -0,0 +1,40 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { inspectCoreTask } from './core-tasks.js';
+
+export function coreTaskWaitFinished(task) {
+  return task.phase === 'terminal' || task.acceptance !== 'accepted'
+    || !['none', 'unknown'].includes(task.outcome);
+}
+
+/** 有界观察原 Task，超时中止 poll/下载并保留事实；没有任何 submit/retry 路径。 */
+export async function waitForCoreTask(runtime, taskId, { observe, timeoutMs = 120000, pollIntervalMs = 2500 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1200000
+      || !Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 50 || pollIntervalMs > 60000) {
+    throw Object.assign(new Error('timeout_ms 必须是 1–1200000，poll_interval_ms 必须是 50–60000 的整数'), { code: 'IRIS_COMMAND_INPUT_INVALID' });
+  }
+  const dataRoot = await runtime.run('inspect', context => context.dataRoot);
+  let task = inspectCoreTask(dataRoot, taskId);
+  const completed = timedOut => ({ taskId, task, timedOut, ready: task.outcome === 'succeeded' && task.deliveryState === 'ready' });
+  if (coreTaskWaitFinished(task)) return completed(false);
+  if (typeof observe !== 'function') throw Object.assign(new Error('等待远端任务需要 Provider resolver'), { code: 'IRIS_COMMAND_PROVIDER_REQUIRED' });
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; runtime.dispose().catch(() => {}); }, timeoutMs);
+  try {
+    while (!coreTaskWaitFinished(task)) {
+      runtime.signal.throwIfAborted();
+      try { task = (await observe()).task; }
+      catch (error) {
+        if (runtime.signal.aborted) throw error;
+        if (error.code && !['IRIS_PROVIDER_POLL_FAILED', 'IRIS_PROVIDER_DOWNLOAD_FAILED'].includes(error.code)) throw error;
+        task = inspectCoreTask(dataRoot, taskId);
+      }
+      if (!coreTaskWaitFinished(task)) await delay(pollIntervalMs, undefined, { signal: runtime.signal });
+    }
+    return completed(false);
+  } catch (error) {
+    if (!timedOut) throw error;
+    await runtime.dispose();
+    task = inspectCoreTask(dataRoot, taskId);
+    return completed(true);
+  } finally { clearTimeout(timer); }
+}

package/lib/video-input.js

@@ -0,0 +1,30 @@
+'use strict';
+/** 视频输入按候选准备；短期地址和本地路径不落 Task。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { GenerationInputError } from './generation-input.js';
+import { parseModelRef } from './models.js';
+import { prepareProviderInput } from './provider-adapter.js';
+import { ProviderContractError } from './provider-contract.js';
+
+export function videoTaskCandidates(candidates, normalized) {
+  const s2v = normalized.videoMode === 's2v';
+  const compatible = candidates.filter(candidate => /s2v/i.test(parseModelRef(candidate.model)?.modelId || '') === s2v);
+  if (!compatible.length) throw new GenerationInputError(s2v
+    ? 'audio_path 只能配合 s2v 数字人模型' : 's2v 模型需要首帧和音频输入');
+  return compatible.map(candidate => ({ ...candidate,
+    ...(normalized.firstFramePath ? { async prepareInput({ signal }) {
+      if (signal.aborted) throw new ProviderContractError('视频输入准备已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
+      if (s2v) {
+        const model = parseModelRef(candidate.model).modelId;
+        const image = await prepareProviderInput(candidate.adapter, { model, filePath: normalized.firstFramePath, signal });
+        if (signal.aborted) throw new ProviderContractError('视频输入准备已取消', { stage: 'upload', category: 'aborted', acceptance: 'not_accepted' });
+        const audio = await prepareProviderInput(candidate.adapter, { model, filePath: normalized.audioPath, signal });
+        return { ...normalized.providerInput, imgDataUrl: image.url, audioUrl: audio.url };
+      }
+      const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(normalized.firstFramePath).toLowerCase()];
+      if (!mime) throw new ProviderContractError('首帧格式不受支持', { stage: 'prepare', category: 'invalid_request', acceptance: 'not_accepted' });
+      return { ...normalized.providerInput, imgDataUrl: 'data:' + mime + ';base64,' + fs.readFileSync(normalized.firstFramePath).toString('base64') };
+    } } : {})
+  }));
+}

package/lib/vision-core.js

@@ -0,0 +1,42 @@
+'use strict';
+/** 单图业务只消费显式字节和 Model Ports，不读取 Host/配置或保存产物。 */
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelErrorRecord, modelPortSnapshot } from './model-port-contract.js';
+
+export const VISION_BUDGET = Object.freeze({ timeoutMs: 120000, maxInputTextBytes: 32768,
+  maxOutputChars: 6000, maxImageBytes: 20 * 1024 * 1024 });
+export const VISION_CANDIDATE_POLICY = Object.freeze({ skipUnavailable: true, allowRejected: true, allowEmptyResult: true });
+
+export async function completeVision(ports, request, { signal, operation, budget = VISION_BUDGET } = {}) {
+  if (!Array.isArray(ports) || !ports.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  const op = operation || createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: ports.length } });
+  const errors = [];
+  const observed = ports.map(port => {
+    let diagnosed = false;
+    return {
+      describe() {
+        const descriptor = modelPortSnapshot(port);
+        if (!diagnosed && descriptor.availability !== 'available') {
+          errors.push(modelErrorRecord(new ModelPortError(descriptor.reasonCode, { stage: 'prepare', backendId: descriptor.identity.backendId })));
+          diagnosed = true;
+        }
+        return descriptor;
+      },
+      async complete(input, options) {
+        try { return await port.complete(input, options); }
+        catch (error) {
+          errors.push({ ...modelErrorRecord(error), backendId: modelPortSnapshot(port).identity.backendId });
+          throw error;
+        }
+      }
+    };
+  });
+  try {
+    const result = await op.runCandidates(observed, request, { budget }, VISION_CANDIDATE_POLICY);
+    return Object.freeze({ ...result, errors: Object.freeze([...errors]) });
+  } catch (error) {
+    // 受控记录供入口写健康反馈，不包含原始错误/图片/问题。
+    if (error instanceof ModelPortError) error.errors = Object.freeze([...errors]);
+    throw error;
+  } finally { if (!operation) op.dispose(); }
+}

package/lib/vision-image-input.js

@@ -0,0 +1,83 @@
+'use strict';
+/** 视觉发送副本；原始文件和 Core Artifact 始终只读。 */
+import sharp from 'sharp';
+import { ModelPortError } from './model-port-contract.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+// 客户端默认发送预算，不表示任何供应商承诺的输入上限。
+export const DEFAULT_VISION_INPUT = Object.freeze({ maxBytes: 8 * 1024 * 1024 });
+
+export function normalizeVisionInputLimits(value) {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).some(key => !['maxBytes', 'maxDimension'].includes(key))
+      || !Object.values(value).every(number => Number.isSafeInteger(number) && number > 0)) {
+    throw Object.assign(new Error('visionInput 只接受正整数 maxBytes、maxDimension，null 恢复继承'), { code: 'IRIS_CONFIG_INPUT_INVALID' });
+  }
+  return { ...value };
+}
+
+export function visionInputLimits(provider, modelId) {
+  const model = provider.models?.find(value => typeof value === 'object' && value?.id === modelId);
+  return { ...DEFAULT_VISION_INPUT, ...normalizeVisionInputLimits(provider.visionInput),
+    ...normalizeVisionInputLimits(model?.visionInput) };
+}
+
+async function processImage(processor, signal, output) {
+  const cancel = () => processor.destroy();
+  signal?.addEventListener('abort', cancel, { once: true });
+  try { return await waitForModelWork(() => output(processor), signal); }
+  finally { signal?.removeEventListener('abort', cancel); }
+}
+
+export async function prepareVisionImage(image, limits, { signal, orient = false } = {}) {
+  const { maxBytes, maxDimension } = { ...DEFAULT_VISION_INPUT, ...normalizeVisionInputLimits(limits) };
+  if (signal?.aborted) return waitForModelWork(() => image, signal);
+  if (image.bytes.byteLength <= maxBytes && !maxDimension && !orient) return image;
+  const tooLarge = () => new ModelPortError('IRIS_MODEL_IMAGE_TOO_LARGE', {
+    stage: 'prepare', imageBytes: image.bytes.byteLength, imageMaxBytes: maxBytes
+  });
+  const format = { 'image/png': 'png', 'image/jpeg': 'jpeg', 'image/webp': 'webp' }[image.mediaType];
+  let metadata;
+  try { metadata = await processImage(sharp(Buffer.from(image.bytes)), signal, processor => processor.metadata()); }
+  catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new ModelPortError('IRIS_MODEL_INPUT_INVALID', { stage: 'prepare' });
+  }
+  const sourceDimension = Math.max(metadata.width, metadata.height);
+  if (image.bytes.byteLength <= maxBytes && (!maxDimension || sourceDimension <= maxDimension)
+      && (!orient || !metadata.orientation || metadata.orientation === 1)) return image;
+  // 合预算的 GIF/动画仍原字节透传，需要缩放时不静默压成一帧。
+  if (!format || metadata.pages > 1) throw tooLarge();
+  let dimension = Math.min(sourceDimension, maxDimension || sourceDimension);
+  let size = image.bytes.byteLength;
+  // 每次从原字节缩放，不反复压缩上一次副本；只进行本地处理，不重发模型请求。
+  for (let attempt = 0; attempt < 6; attempt++) {
+    if (size > maxBytes) dimension = Math.max(1, Math.min(dimension,
+      Math.floor((attempt === 0 ? sourceDimension : dimension) * Math.min(0.8, Math.sqrt(maxBytes / size) * 0.9))));
+    const processor = sharp(Buffer.from(image.bytes)).autoOrient().resize({ width: dimension, height: dimension,
+      fit: 'inside', withoutEnlargement: true }).toFormat(format);
+    const bytes = await processImage(processor, signal, value => value.toBuffer());
+    if (bytes.byteLength <= maxBytes) return { bytes: new Uint8Array(bytes), mediaType: image.mediaType };
+    size = bytes.byteLength;
+    if (dimension === 1) break;
+  }
+  throw tooLarge();
+}
+
+/** 每次调用的实际图片事实；仅包含尺寸/大小，不包含字节、路径或凭据。 */
+export function createVisionInputObserver(inputs) {
+  return async ({ request, image, signal, identity }) => {
+    const [source, sent] = await waitForModelWork(() => Promise.all([
+      sharp(Buffer.from(request.image.bytes)).metadata(), sharp(Buffer.from(image.bytes)).metadata()
+    ]), signal);
+    const record = {
+      source: { width: source.width, height: source.height, bytes: request.image.bytes.byteLength, mediaType: request.image.mediaType },
+      sent: { width: sent.width, height: sent.height, bytes: image.bytes.byteLength, mediaType: image.mediaType },
+      orientation: source.orientation || 1,
+      resized: (source.autoOrient?.width || source.width) !== sent.width || (source.autoOrient?.height || source.height) !== sent.height
+    };
+    inputs.set(identity.backendId, record);
+    return record;
+  };
+}

package/lib/vision-input.js

@@ -0,0 +1,31 @@
+'use strict';
+/** 单图来源由入口选择；Core 图片以原字节/MIME 只读进入视觉业务。 */
+import { CommandError } from './command-service.js';
+import { inspectCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
+import { MODEL_IMAGE_MEDIA_TYPES } from './model-port-contract.js';
+import { VISION_BUDGET } from './vision-core.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+export function normalizeVisionImageSource(input, { allowAttachment = false } = {}) {
+  const fields = ['image_path', 'artifact_id', ...(allowAttachment ? ['attachment_id'] : [])];
+  const selected = fields.filter(field => input[field] !== undefined);
+  if (selected.length !== 1) throw new CommandError('IRIS_COMMAND_INPUT_INVALID',
+    '必须且只能提供 ' + fields.join('、') + ' 之一');
+  if (selected[0] === 'artifact_id'
+      && (typeof input.artifact_id !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(input.artifact_id))) {
+    throw new CommandError('IRIS_COMMAND_INPUT_INVALID', 'artifact_id 必须是有效的 Core Artifact ID');
+  }
+  return selected[0];
+}
+
+export function readVisionArtifact(runtime, artifactId, signal) {
+  return waitForModelWork(() => runtime.run('inspect', ({ dataRoot }) => {
+    // 先检查大小/MIME，再物化字节；沿用图片输入的 20 MiB 上限。
+    const artifact = inspectCoreArtifact(dataRoot, artifactId);
+    if (!MODEL_IMAGE_MEDIA_TYPES.includes(artifact.mediaType) || artifact.size > VISION_BUDGET.maxImageBytes) {
+      throw new CommandError('IRIS_COMMAND_INPUT_INVALID', '视觉 Artifact 必须是最多 20 MiB 的 PNG、JPEG、WebP 或 GIF 图片');
+    }
+    const { bytes } = readCoreArtifactBytes(dataRoot, artifactId);
+    return { bytes: new Uint8Array(bytes), mediaType: artifact.mediaType };
+  }), signal);
+}

package/lib/vision-model-routing.js

@@ -0,0 +1,180 @@
+'use strict';
+/** Host 边界：显式配置选型、字节解析和结果投影。 */
+import { resolveModelRef, parseModelRef } from './models.js';
+import { providerApiKey } from './provider-protocol.js';
+import { createHttpVisionModelPort } from './http-vision-model-adapter.js';
+import { prepareDshVisionModelPort } from './dsh-vision-model-adapter.js';
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, modelErrorRecord } from './model-port-contract.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { modelRateLimit, reportModelRateLimit } from './provider-health.js';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { open } from 'node:fs/promises';
+import { DEFAULT_VISION_INPUT, visionInputLimits } from './vision-image-input.js';
+
+const features = Object.freeze({ system: 'unknown', temperature: 'unknown', maxOutputTokens: 'unknown', reasoning: 'unknown' });
+
+function unavailablePort(id, code = 'IRIS_MODEL_UNAVAILABLE') {
+  const descriptor = normalizeModelDescriptor({ contractVersion: 0, kind: 'vision',
+    identity: { origin: 'host', backendId: id }, availability: code === 'IRIS_MODEL_UNSUPPORTED' ? 'incompatible' : 'unavailable', reasonCode: code, features });
+  return Object.freeze({ describe: () => descriptor, async complete() { throw new ModelPortError(code, { stage: 'prepare', backendId: id }); } });
+}
+
+/** 默认选择仅在轮到 Host 候选时解析；自持成功不会多查 Host 元数据。 */
+function deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest }) {
+  const ready = typeof host?.ports?.textModel?.stream === 'function'
+    && typeof host?.ports?.textModel?.currentSelection === 'function'
+    && typeof host?.ports?.textModel?.resolveModelInfo === 'function'
+    && typeof host?.ports?.attachments?.saveImage === 'function' && typeof host?.ports?.attachments?.readImage === 'function';
+  const initial = normalizeModelDescriptor({ contractVersion: 0, kind: 'vision',
+    identity: { origin: 'host', backendId: 'dsh-vision:default' }, availability: ready ? 'available' : 'unavailable',
+    ...(ready ? {} : { reasonCode: 'IRIS_MODEL_UNAVAILABLE' }), features });
+  // 保持请求前后的不透明身份一致，实际模型身份作为边界内投影事实返回。
+  let selected, bound;
+  return { port: Object.freeze({ describe: () => initial,
+    async complete(request, options) {
+      // 一轮复合操作的后续图片复用已解析路由，默认模型切换只影响下次操作。
+      const port = bound || await prepareDshVisionModelPort(host?.ports?.textModel, host?.ports?.attachments, {
+        signal: options.signal, allowImageNormalization: prepareImages, orientImages,
+        ...(prepareImages ? { imageInput: DEFAULT_VISION_INPUT } : {}),
+        ...(prepareImageRequest ? { prepareImageRequest: args => prepareImageRequest({ ...args, identity: initial.identity }) } : {}) });
+      bound = port;
+      const result = await port.complete(request, options);
+      selected = result.identity;
+      return { ...result, identity: initial.identity };
+    }
+  }), selected: () => selected };
+}
+
+/** 配置只绑定一个自持模型；CLI 不附加宿主候选。 */
+export function createConfiguredVisionModelPort(provider, model, { allowRateLimited = false, onRateLimit, prepareImages = false,
+  orientImages = false, prepareImageRequest } = {}) {
+  const parsed = parseModelRef(resolveModelRef(provider, 'vision', model));
+  const id = 'iris-provider:' + encodeURIComponent(provider.id);
+  if (!parsed) return unavailablePort(id);
+  if (typeof provider.type === 'string' && provider.type.trim() && provider.type.trim() !== 'openai') {
+    return unavailablePort(id, 'IRIS_MODEL_UNSUPPORTED');
+  }
+  const port = createHttpVisionModelPort({ providerId: provider.id, modelId: parsed.modelId,
+    baseUrl: provider.baseUrl, apiKey: providerApiKey(provider),
+    orientImages, prepareImageRequest,
+    ...(prepareImages ? { imageInput: visionInputLimits(provider, parsed.modelId) } : {}) });
+  return Object.freeze({ describe: port.describe,
+    async complete(request, options) {
+      if (!allowRateLimited && modelRateLimit(provider, parsed.modelId)) {
+        throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+      }
+      try { return await port.complete(request, options); }
+      catch (error) {
+        reportModelRateLimit(provider, parsed.modelId, { status: error.status, code: error.code,
+          providerCode: error.providerCode, retryAfterMs: error.retryAfterMs,
+          ...(error.quotaExhausted ? { reason: 'free_quota' } : {}),
+          source: allowRateLimited ? 'probe' : 'task' }, onRateLimit, 'vision');
+        throw error;
+      }
+    }
+  });
+}
+
+export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, prepareImages = false,
+  orientImages = false, prepareImageRequest } = {}) {
+  const candidates = [], seen = new Set();
+  for (const provider of providers.filter(Boolean)) {
+    const ref = resolveModelRef(provider, 'vision', model);
+    const parsed = parseModelRef(ref);
+    // 显式模型会把同账号的多份池记录解析为同一复合引用，只保留首次候选。
+    if (parsed && seen.has(ref)) continue;
+    if (parsed) seen.add(ref);
+    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+    const id = port.describe().identity.backendId;
+    candidates.push({ port, id, via: 'selfstack', backendId: provider.id, model: parsed?.modelId || '' });
+  }
+  const hostCandidate = deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest });
+  candidates.push({ ...hostCandidate, id: 'dsh-vision:default', via: 'global', backendId: 'dsh-global', model: '宿主视觉模型' });
+  return candidates;
+}
+
+export function visionImageFromDataUrl(value, maxBytes = VISION_BUDGET.maxImageBytes) {
+  if (typeof value !== 'string' || value.length > Math.ceil(maxBytes / 3) * 4 + 64) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const match = /^data:(image\/(?:png|jpeg|webp|gif));base64,([A-Za-z0-9+/]+={0,2})$/.exec(value);
+  if (!match || match[2].length % 4 !== 0) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const bytes = Buffer.from(match[2], 'base64');
+  if (!bytes.length || bytes.length > maxBytes || bytes.toString('base64') !== match[2]) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  return { bytes: new Uint8Array(bytes), mediaType: match[1] };
+}
+
+/** 打开一次并限额读取，避免用巨大文件分配无界内存；读取受操作取消控制。 */
+export async function readVisionImageFile(file, mediaType, signal) {
+  return waitForModelWork(async () => {
+    const handle = await open(file, 'r');
+    try {
+      if (signal?.aborted) throw signal.reason;
+      const stat = await handle.stat();
+      if (!stat.isFile() || !stat.size || stat.size > VISION_BUDGET.maxImageBytes) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+      const bytes = new Uint8Array(stat.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        if (signal?.aborted) throw signal.reason;
+        const { bytesRead } = await handle.read(bytes, offset, Math.min(65536, bytes.length - offset), offset);
+        if (!bytesRead) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+        offset += bytesRead;
+      }
+      const extra = new Uint8Array(1);
+      if ((await handle.read(extra, 0, 1, offset)).bytesRead) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+      return { bytes, mediaType };
+    } finally { await handle.close(); }
+  }, signal);
+}
+
+function projectError(record, candidates) {
+  const candidate = candidates.find(value => value.id === record.backendId);
+  const category = { IRIS_MODEL_AUTH_FAILED: 'auth', IRIS_MODEL_RATE_LIMITED: record.status === 403 ? 'quota' : 'rate_limit',
+    IRIS_MODEL_TIMEOUT: 'timeout', IRIS_MODEL_ABORTED: 'aborted' }[record.code] || 'unknown';
+  return { ...record, kind: candidate?.via, backendId: candidate?.backendId || record.backendId,
+    model: candidate?.model || '', category };
+}
+
+/** prepareImage 的信号覆盖文件/会话读取；函数开始时即建立整体预算。 */
+export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, prepareImages = false,
+  orientImages = false, prepareImageRequest }, consume) {
+  const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+  const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: candidates.length } });
+  try {
+    const { completion: result, ...details } = await consume(candidates.map(candidate => candidate.port), operation);
+    const selected = candidates.find(candidate => candidate.id === result.identity.backendId);
+    return { ...details, answer: result.text.trim(), via: selected.via, backendId: selected.backendId,
+      model: selected.selected?.()?.modelId || selected.model, errors: result.errors.map(record => projectError(record, candidates)) };
+  } catch (error) {
+    if (error instanceof ModelPortError) {
+      error.errors = (error.errors || []).map(record => projectError(record, candidates));
+      throw error;
+    }
+    throw new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'prepare', invocation: 'not_invoked' });
+  } finally { operation.dispose(); }
+}
+
+/** 单图与复合业务共用同一候选、整体预算和结果投影。 */
+export async function runVisionRequest(host, { providers, model, question, image, dataUrl, prepareImage, signal, budget = VISION_BUDGET, onRateLimit }) {
+  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit, prepareImages: true }, async (ports, operation) => {
+    normalizeModelCall(ports[0].describe(), { prompt: question,
+      image: { bytes: new Uint8Array([0]), mediaType: 'image/png' } }, { budget });
+    const resolved = await waitForModelWork(() => prepareImage ? prepareImage(operation.signal)
+      : image || visionImageFromDataUrl(dataUrl, budget.maxImageBytes), operation.signal);
+    return { completion: await completeVision(ports, { prompt: question, image: resolved }, { operation, budget }) };
+  });
+}
+
+/** 付费确认在动作入口；红图实测只有一个供应商，不退到 Host 冒充其能力。 */
+export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000 } = {}) {
+  try {
+    const [candidate] = buildVisionModelCandidates(null, { providers: [provider], model, allowRateLimited: true });
+    const result = await completeVision([candidate.port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
+      { signal, budget: { ...VISION_BUDGET, timeoutMs } });
+    return { ok: /红|red/i.test(result.text), answer: result.text };
+  } catch (error) {
+    const record = modelErrorRecord(error);
+    const projected = projectError(record, []);
+    return { ok: false, answer: '', error: record.message, code: record.code,
+      timedOut: record.code === 'IRIS_MODEL_TIMEOUT', category: projected.category, status: record.status };
+  }
+}

package/lib/vision.js

@@ -118,11 +118,12 @@ export async function askWithBackends(backends, request) {
 /* ---------------- 视觉能力测试（"test it, don't guess it"） ---------------- */
 
 /**
- * 固定红色测试图（1x1 纯红 PNG，真实生成）。用于验证模型真的能看图，
+ * 固定红色测试图（128x128 纯红 PNG，真实生成），避免过小图片被模型拒绝。
+ * 用于验证模型真的能看图，
  * 而不是只看 HTTP 返回 200 就声称支持 vision。
  */
 export const RED_TEST_IMAGE =
-  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAAACXBIWXMAAAPoAAAD6AG1e1JrAAABnklEQVR4nO3UUQ0AAAiE0OtfGmPwgdsLwNQ5toc3hJ/+3Pv7BewXsPIP9Ato8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wto8wtoOyBow7IT86bXAAAAAElFTkSuQmCC';
 
 /** 期望的回答语义：必须提到红色（中文"红"或英文 red），才判定具备视觉能力 */
 const RED_HINTS = /红|red/i;

package/lib/workbench-artifacts.js

@@ -0,0 +1,52 @@
+'use strict';
+/** Host 作品目录：两种既有存储保持原样，在展示边界统一过滤、排序与分页。 */
+import * as legacy from './artifacts.js';
+import { galleryArtifactsForDsh } from './dsh-core-adapter.js';
+import { mimeOf } from './media.js';
+
+export function normalizeGalleryQuery(input = {}) {
+  const query = { offset: 0, limit: 24, media_type: 'all', source: 'all', kind: 'all', ...input };
+  const invalid = () => { throw Object.assign(new Error('作品查询参数无效'), { code: 'IRIS_GALLERY_QUERY_INVALID', statusCode: 400 }); };
+  for (const key of Object.keys(query)) if (!['offset', 'limit', 'media_type', 'source', 'kind'].includes(key)) invalid();
+  if (!Number.isSafeInteger(query.offset) || query.offset < 0 || !Number.isSafeInteger(query.limit)
+      || query.limit < 1 || query.limit > 60) invalid();
+  if (!['all', 'image', 'video', 'audio', 'text'].includes(query.media_type)
+      || !['all', 'core', 'legacy'].includes(query.source)
+      || typeof query.kind !== 'string' || !query.kind.trim() || query.kind.length > 256) invalid();
+  return query;
+}
+
+export async function workbenchArtifacts(input, options = {}) {
+  const query = normalizeGalleryQuery(input);
+  const items = [];
+  let droppedCore = 0, coreError = '';
+  if (query.source !== 'legacy') {
+    try {
+      const core = await galleryArtifactsForDsh(options);
+      droppedCore = core.dropped;
+      for (const artifact of core.artifacts) {
+        if (artifact.kind === 'host-input') continue;
+        items.push({ id: artifact.id, file: artifact.id, mime: artifact.mediaType,
+          size: artifact.size, createdAt: artifact.createdAt, source: 'core', kind: artifact.kind,
+          digest: artifact.digest.value, url: '/iris/api/core/artifact/' + artifact.id + '/media' });
+      }
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      coreError = error.code || 'IRIS_GALLERY_CORE_UNAVAILABLE';
+    }
+  }
+  if (query.source !== 'core') {
+    for (const item of legacy.all()) items.push({ id: item.id, file: item.file, mime: item.mime || mimeOf(item.file),
+      size: Number(item.size || 0), createdAt: item.createdAt || '', source: 'legacy', kind: 'legacy-output', url: legacy.artifactUrl(item) });
+  }
+  const candidates = items.filter(item => query.media_type === 'all'
+    || (query.media_type === 'text' ? item.mime.startsWith('text/') || item.mime === 'application/json'
+      : item.mime.startsWith(query.media_type + '/')));
+  const kinds = [...new Set(candidates.map(item => item.kind))].sort();
+  const matches = candidates.filter(item => query.kind === 'all' || item.kind === query.kind)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || (a.source + ':' + a.id).localeCompare(b.source + ':' + b.id));
+  const offset = matches.length ? Math.min(query.offset, Math.floor((matches.length - 1) / query.limit) * query.limit) : 0;
+  return { total: matches.length, offset, limit: query.limit, kinds,
+    counts: { core: matches.filter(item => item.source === 'core').length, legacy: matches.filter(item => item.source === 'legacy').length },
+    droppedCore, ...(coreError ? { coreError } : {}), items: matches.slice(offset, offset + query.limit) };
+}