@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

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

@@ -1,4 +1,5 @@
 'use strict';
+import { providerApiKey, unsupportedProtocolError } from './provider-protocol.js';
 /**
  * Iris 视觉后端抽象（阶段 1）。
  *
@@ -12,12 +13,14 @@
  */
 import * as adapters from './adapters.js';
 import { hasHostPort } from './host-contract.js';
+import { resolveModelRef, parseModelRef } from './models.js';
 
 /** 后端接口约定：id / kind / model 只读，analyze(request) → Promise<string> */
 
 export class SelfStackVisionBackend {
-  constructor({ provider }) {
+  constructor({ provider, model }) {
     this.provider = provider;
+    this.requestedModel = model;
   }
   get id() {
     return this.provider.id;
@@ -26,13 +29,18 @@ export class SelfStackVisionBackend {
     return 'selfstack';
   }
   get model() {
-    return this.provider.visionModel || 'qwen-vl-plus';
+    const ref = resolveModelRef(this.provider, 'vision', this.requestedModel);
+    return parseModelRef(ref)?.modelId || '';
   }
   async analyze({ question, imageDataUrl, signal }) {
+    const model = this.model;
+    if (!model) throw Object.assign(new Error('iris: 未配置视觉模型，请发现或手工添加并标注 vision 能力'), {
+      code: 'IRIS_PROVIDER_MODEL_UNAVAILABLE'
+    });
     return adapters.visionStream({
-      key: this.provider.apiKey,
+      key: providerApiKey(this.provider),
       baseUrl: this.provider.baseUrl,
-      model: this.model,
+      model,
       prompt: question,
       imageDataUrl,
       signal
@@ -48,13 +56,24 @@ export class HostVisionBackend {
   async analyze(request) { return this.port.analyze(request); }
 }
 
+const VISION_FACTORIES = new Map([
+  ['openai', (provider, model) => new SelfStackVisionBackend({ provider, model })]
+]);
+
 /** Host Adapter 入口；Command 不读取 DSH ctx。 */
 export function buildVisionBackendsFromHost(host, { providers, model }) {
   const backends = [];
   for (const p of providers || []) {
-    if (p && p.type === 'openai') {
-      const provider = model ? { ...p, visionModel: model } : p;
-      backends.push(new SelfStackVisionBackend({ provider }));
+    if (p) {
+      const type = typeof p.type === 'string' && p.type.trim() ? p.type.trim() : 'openai';
+      const factory = VISION_FACTORIES.get(type);
+      if (!factory) {
+        // 保留不可用证据，让宿主视觉端口仍能按既有顺序降级。
+        backends.push({
+          id: p.id, kind: 'selfstack', model: String(model || p.visionModel || ''),
+          async analyze() { throw unsupportedProtocolError(type, 'vision'); }
+        });
+      } else backends.push(factory(p, model));
     }
   }
   if (hasHostPort(host, 'visionModel') && typeof host.ports.visionModel.analyze === 'function') {
@@ -83,6 +102,7 @@ export async function askWithBackends(backends, request) {
         backendId: b.id,
         kind: b.kind,
         model: b.model,
+        code: err && err.code,
         category: err && err.category,
         status: err && err.status,
         message: String((err && err.message) || err)
@@ -90,6 +110,7 @@ export async function askWithBackends(backends, request) {
     }
   }
   const err = new Error('iris: 视觉模型不可用——自持栈与全局视觉模型都失败了');
+  if (errors.length && errors[0].code && errors.every((error) => error.code === errors[0].code)) err.code = errors[0].code;
   err.errors = errors;
   throw err;
 }
@@ -97,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) };
+}

package/lib/workbench-management.js

@@ -0,0 +1,151 @@
+/** 工作台显式选择/详情/下载和可恢复管理；不修改既有 Core 维护语义。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { setImmediate } from 'node:timers/promises';
+import * as legacy from './artifacts.js';
+import { mimeOf } from './media.js';
+import { inspectWorkbenchArtifactForDsh, inspectProviderTaskForDsh, maintainWorkbenchForDsh, readCoreArtifactMediaForDsh } from './dsh-core-adapter.js';
+import { workbenchZip } from './workbench-zip.js';
+
+export const MAX_WORKBENCH_SELECTION = 200;
+export const MAX_WORKBENCH_DOWNLOAD_BYTES = 128 * 1024 * 1024;
+const CORE_ID = /^artifact_[a-f0-9]{24}$/, LEGACY_ID = /^a_[a-f0-9]{24}$/, TASK_ID = /^task_[a-f0-9]{24}$/;
+const EXTENSIONS = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp', 'image/gif': '.gif',
+  'video/mp4': '.mp4', 'video/webm': '.webm', 'audio/wav': '.wav', 'audio/mpeg': '.mp3', 'audio/ogg': '.ogg',
+  'audio/flac': '.flac', 'text/plain': '.txt', 'application/json': '.json' };
+const fail = (code, message, statusCode = 400) => { throw Object.assign(new Error(message), { code, statusCode }); };
+function active(signal) { if (signal?.aborted) throw Object.assign(new Error('作品操作已取消'), { name: 'AbortError' }); }
+function exact(input, keys) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !keys.includes(key))) {
+    fail('IRIS_COMMAND_INPUT_INVALID', '作品操作参数无效');
+  }
+}
+function validItem(item) {
+  exact(item, ['source', 'id']);
+  if (!(item.source === 'core' ? CORE_ID.test(item.id) : item.source === 'legacy' && LEGACY_ID.test(item.id))) {
+    fail('IRIS_COMMAND_INPUT_INVALID', '作品来源或 ID 无效');
+  }
+  return item;
+}
+function selection(input) {
+  exact(input, ['items']);
+  if (!Array.isArray(input.items) || !input.items.length || input.items.length > MAX_WORKBENCH_SELECTION) {
+    fail('IRIS_COMMAND_INPUT_INVALID', '请明确选择 1–200 个作品');
+  }
+  const items = input.items.map(validItem);
+  if (new Set(items.map(item => item.source + ':' + item.id)).size !== items.length) fail('IRIS_COMMAND_INPUT_INVALID', '选中作品不能重复');
+  return items;
+}
+
+function legacyFile(id) {
+  const entry = legacy.all().find(item => item.id === id);
+  const hit = entry && legacy.authorize(entry.id, entry.token, entry.file);
+  if (!hit) fail('IRIS_WORK_NOT_FOUND', '作品文件不存在或不可读取', 404);
+  return { entry, ...hit };
+}
+function safeMetadata(metadata) {
+  const result = {};
+  for (const key of ['width', 'height', 'durationMs', 'frameCount', 'frameIndex', 'sourceFrameIndex', 'timeMs']) {
+    if (typeof metadata[key] === 'number' && Number.isFinite(metadata[key])) result[key] = metadata[key];
+  }
+  if (TASK_ID.test(metadata.taskId)) result.taskId = metadata.taskId;
+  return result;
+}
+
+export async function workbenchDetail(source, id, options = {}) {
+  validItem({ source, id }); active(options.signal);
+  if (source === 'core') {
+    const artifact = await inspectWorkbenchArtifactForDsh(id, options);
+    return { item: { id, source, file: id + EXTENSIONS[artifact.mediaType], mime: artifact.mediaType,
+      kind: artifact.kind, size: artifact.size, createdAt: artifact.createdAt, digest: artifact.digest.value,
+      relations: artifact.relations, metadata: safeMetadata(artifact.metadata), integrity: 'verified',
+      url: '/iris/api/core/artifact/' + id + '/media' } };
+  }
+  const hit = legacyFile(id), entry = hit.entry;
+  return { item: { id, source, file: entry.file, mime: entry.mime || mimeOf(entry.file), size: hit.size,
+    kind: 'legacy-output', createdAt: entry.createdAt || '', integrity: 'file-exists', url: legacy.artifactUrl(entry) } };
+}
+
+export async function downloadWorkbenchSelection(input, options = {}) {
+  const items = selection(input), details = [];
+  let bytes = 0;
+  for (const item of items) {
+    active(options.signal);
+    const detail = (await workbenchDetail(item.source, item.id, options)).item;
+    bytes += detail.size;
+    if (bytes > MAX_WORKBENCH_DOWNLOAD_BYTES) fail('IRIS_WORK_DOWNLOAD_TOO_LARGE', '单次下载最多 128 MiB，请减少选中作品', 413);
+    details.push(detail);
+    await setImmediate();
+  }
+  const entries = [], manifest = [];
+  bytes = 0;
+  for (const detail of details) {
+    active(options.signal);
+    const data = detail.source === 'core' ? (await readCoreArtifactMediaForDsh(detail.id, options)).bytes : fs.readFileSync(legacyFile(detail.id).abs);
+    const digest = crypto.createHash('sha256').update(data).digest('hex');
+    if (detail.source === 'core' && digest !== detail.digest) fail('IRIS_ARTIFACT_DIGEST_MISMATCH', '选中作品内容已改变', 409);
+    bytes += data.length;
+    if (bytes > MAX_WORKBENCH_DOWNLOAD_BYTES) fail('IRIS_WORK_DOWNLOAD_TOO_LARGE', '单次下载最多 128 MiB，请减少选中作品', 413);
+    const name = detail.source + '/' + detail.id + path.extname(detail.file).toLowerCase();
+    entries.push({ name, bytes: data });
+    manifest.push({ source: detail.source, id: detail.id, file: detail.file, archiveFile: name, mime: detail.mime,
+      size: data.length, createdAt: detail.createdAt, digest });
+    await setImmediate();
+  }
+  active(options.signal);
+  return workbenchZip([{ name: 'works.json', bytes: Buffer.from(JSON.stringify({ schemaVersion: 0, items: manifest }, null, 2) + '\n') }, ...entries]);
+}
+
+export async function deleteWorkbenchArtifacts(input, options = {}) {
+  exact(input, ['artifact_ids', 'task_ids', 'confirm_delete']);
+  const chosen = selection({ items: Array.isArray(input.artifact_ids) ? input.artifact_ids.map(id => ({ source: 'core', id })) : null });
+  if (input.confirm_delete !== undefined && typeof input.confirm_delete !== 'boolean') fail('IRIS_COMMAND_INPUT_INVALID', 'confirm_delete 必须是布尔值');
+  const taskIds = input.task_ids ?? [];
+  if (!Array.isArray(taskIds) || taskIds.length > 200 || !taskIds.every(id => typeof id === 'string' && TASK_ID.test(id))
+      || new Set(taskIds).size !== taskIds.length) fail('IRIS_COMMAND_INPUT_INVALID', '关联任务 ID 无效');
+  active(options.signal);
+  const artifactIds = chosen.map(item => item.id);
+  const base = await maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds }, options);
+  const referencing = [...new Set(base.blockers.filter(blocker => ['task_artifact_reference', 'task_input_reference'].includes(blocker.reason)).map(blocker => blocker.referencedBy))];
+  if (taskIds.some(id => !referencing.includes(id))) fail('IRIS_COMMAND_INPUT_INVALID', '只能显式选择这些作品直接关联的任务');
+  if (input.confirm_delete === true) return { ok: true, ...await maintainWorkbenchForDsh('core.delete', {
+    artifact_ids: artifactIds, task_ids: taskIds, confirm_delete: true }, options) };
+  const plan = taskIds.length ? await maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds, task_ids: taskIds }, options) : base;
+  const tasks = [];
+  for (const id of referencing) {
+    const task = await inspectProviderTaskForDsh(id, options);
+    tasks.push({ id, settled: task.phase === 'terminal' && task.acceptance !== 'unknown' && task.outcome !== 'unknown' });
+  }
+  return { ok: true, preview: true, allowed: plan.allowed, artifactIds, taskIds, files: plan.entries.length,
+    bytes: plan.bytes, blockers: plan.blockers, referencingTasks: tasks };
+}
+
+export async function workbenchTransactions(options = {}) {
+  return { ok: true, ...await maintainWorkbenchForDsh('core.transactions', {}, options) };
+}
+
+export async function restoreWorkbenchTransaction(input, options = {}) {
+  exact(input, ['transaction_id', 'confirm_restore']);
+  if (input.confirm_restore !== true) fail('IRIS_WORK_RESTORE_CONFIRM_REQUIRED', '请明确确认恢复此隔离事务');
+  if (typeof input.transaction_id !== 'string' || !/^delete_[a-f0-9]{24}$/.test(input.transaction_id)) fail('IRIS_COMMAND_INPUT_INVALID', '隔离事务 ID 无效');
+  active(options.signal);
+  return { ok: true, ...await maintainWorkbenchForDsh('core.restore', { transaction_id: input.transaction_id }, options) };
+}
+
+/** API 边界只返回固定提示和稳定码，避免底层 ENOENT/JSON 错误带出文件路径。 */
+export function workbenchError(error) {
+  if (error.name === 'AbortError') return error;
+  const code = String(error.code || 'IRIS_WORK_FAILED');
+  const messages = { IRIS_CORE_DELETE_BLOCKED: '作品仍被引用或任务尚未结束，请重新查看删除预览',
+    IRIS_CORE_MAINTENANCE_FAILED: '隔离操作未完成，恢复清单已保留，请查看 Core 回收区',
+    IRIS_CORE_RESTORE_CONFLICT: '恢复目标已存在，未覆盖已有作品', IRIS_CORE_RESTORE_INVALID: '此事务当前不可恢复',
+    IRIS_CORE_DATA_ROOT_BUSY: 'Core 正在被其他进程写入，请稍后重试',
+    IRIS_ARTIFACT_DIGEST_MISMATCH: '作品内容哈希核验失败', IRIS_WORK_DOWNLOAD_TOO_LARGE: '单次下载最多 128 MiB，请减少选中作品',
+    IRIS_WORK_RESTORE_CONFIRM_REQUIRED: '请明确确认恢复此隔离事务', IRIS_COMMAND_INPUT_INVALID: '作品操作参数无效' };
+  const missing = code === 'ENOENT' || /NOT_FOUND/.test(code);
+  return Object.assign(new Error(messages[code] || (missing ? '作品或隔离事务不存在' : '作品操作失败，请刷新后重试')), {
+    code, statusCode: error.statusCode || (missing ? 404 : code === 'IRIS_COMMAND_INPUT_INVALID' || code === 'IRIS_WORK_RESTORE_CONFIRM_REQUIRED' ? 400 : 409),
+    ...(error.transactionId ? { transactionId: error.transactionId } : {})
+  });
+}