@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

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) };
+}

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 } : {})
+  });
+}

package/lib/workbench-zip.js

@@ -0,0 +1,39 @@
+/** 作品下载专用 ZIP stored writer；无压缩/加密/ZIP64，不读取或解压外部归档。
+ * 布局依据 https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT §4.3。
+ * 调用方已限制 200 项/128 MiB，并生成安全的来源/ID 文件名。
+ */
+const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
+  let crc = value;
+  for (let bit = 0; bit < 8; bit++) crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+  return crc >>> 0;
+});
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = crcTable[(crc ^ byte) & 255] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function workbenchZip(entries) {
+  const local = [], central = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = Buffer.from(entry.name, 'utf8'), bytes = entry.bytes, crc = crc32(bytes);
+    const header = Buffer.alloc(30);
+    header.writeUInt32LE(0x04034b50, 0); header.writeUInt16LE(20, 4);
+    header.writeUInt16LE(0x800, 6); header.writeUInt16LE(33, 12); // UTF-8，1980-01-01，stored。
+    header.writeUInt32LE(crc, 14); header.writeUInt32LE(bytes.length, 18); header.writeUInt32LE(bytes.length, 22);
+    header.writeUInt16LE(name.length, 26);
+    const record = Buffer.alloc(46);
+    record.writeUInt32LE(0x02014b50, 0); record.writeUInt16LE(20, 4); record.writeUInt16LE(20, 6);
+    record.writeUInt16LE(0x800, 8); record.writeUInt16LE(33, 14);
+    record.writeUInt32LE(crc, 16); record.writeUInt32LE(bytes.length, 20); record.writeUInt32LE(bytes.length, 24);
+    record.writeUInt16LE(name.length, 28); record.writeUInt32LE(offset, 42);
+    local.push(header, name, bytes); central.push(record, name);
+    offset += header.length + name.length + bytes.length;
+  }
+  const centralSize = central.reduce((sum, bytes) => sum + bytes.length, 0), end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralSize, 12); end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...local, ...central, end]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Multi-provider image, video, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",