@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/provider-config-service.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot } from './provider-catalog.js';
+import { isKnownCapability } from './capability.js';
+import { providerModels, modelPool, parseModelRef, capabilitiesOfModel, capabilitiesOfDiscoveredModel, resolvePoolModel } from './models.js';
+import { atomicWritePrivate, privateSibling, ensurePrivateDir } from './private-storage.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { selectImageProtocol, normalizeImageProtocol } from './provider-protocol.js';
+import { invokeProviderOperation } from './provider-adapter.js';
+import { redactProviderMessage } from './provider-contract.js';
+import { modelRateLimit, recordModelRateLimit, clearModelRateLimit, clearModelCapabilityHealth, isDefinitiveHealthFailure } from './provider-health.js';
+import { normalizeVisionInputLimits, visionInputLimits } from './vision-image-input.js';
+
+const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const safe = value => redactProviderMessage(String(value || '').replace(/https?:\/\/[^\s<>"']+/gi, '[URL]'));
+const text = value => { if (typeof value !== 'string' || !value.trim()) fail('ID 必须是非空字符串'); return value.trim(); };
+const caps = value => {
+  if (!Array.isArray(value) || !value.every(isKnownCapability) || new Set(value).size !== value.length) fail('capabilities 必须是不重复的已知能力数组');
+  return value;
+};
+
+function assignmentSnapshot(catalog) {
+  const pool = modelPool(catalog.providers);
+  return Object.fromEntries(Object.entries(catalog.assignments || {}).map(([capability, value]) => {
+    const refs = (Array.isArray(value) ? value : [value]).map(ref => resolvePoolModel(pool, ref, capability));
+    return [safe(capability), { model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
+  }));
+}
+
+export function configSnapshot(catalog) {
+  return { ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
+    ref: safe(model.ref), providerId: safe(provider.id), id: safe(model.id), capabilities: model.capabilities,
+    ...(model.imageProtocol !== undefined ? { imageProtocol: model.imageProtocol } : {}),
+    ...(model.visionInput !== undefined ? { visionInput: model.visionInput } : {}),
+    ...(model.capabilities.includes('vision') ? { visionInputEffective: visionInputLimits(provider, model.id) } : {}),
+    ...(model.capabilities.includes('image-gen') ? { imageRouting: selectImageProtocol(provider, model.id) } : {}),
+    verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: safe(value.at), category: safe(value.category) }])),
+    ...(model.rateLimited ? { rateLimited: true, rateLimitedAt: modelRateLimit(provider, model.id).at,
+      ...(modelRateLimit(provider, model.id).until ? { retryAt: modelRateLimit(provider, model.id).until }
+        : { reason: modelRateLimit(provider, model.id).reason }) } : {})
+  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog) };
+}
+
+export async function executeConfigCommand(configPath, command, input = {}, { signal, probe } = {}) {
+  if (command === 'init') {
+    if (!path.isAbsolute(configPath)) fail('provider-config 必须是绝对路径');
+    ensurePrivateDir(path.dirname(configPath));
+    fs.writeFileSync(configPath, JSON.stringify({ providers: [], assignments: {} }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    return { command, created: true };
+  }
+  const catalog = loadProviderCatalog(configPath);
+  const before = fs.readFileSync(configPath);
+  if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(catalog)) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
+  if (command === 'show') return configSnapshot(catalog);
+  if (command === 'check') {
+    const issues = [];
+    const ids = catalog.providers.map(provider => provider.id);
+    if (new Set(ids).size !== ids.length) issues.push('duplicate_provider_id');
+    const pool = modelPool(catalog.providers);
+    for (const provider of catalog.providers) {
+      try { normalizeVisionInputLimits(provider.visionInput); } catch (_) { issues.push('invalid_vision_input'); }
+      for (const model of provider.models || []) {
+        try { normalizeVisionInputLimits(model?.visionInput); } catch (_) { issues.push('invalid_model_vision_input'); }
+        if (model?.imageProtocol === undefined) continue;
+        try { normalizeImageProtocol(model.imageProtocol); } catch (_) { issues.push('invalid_model_image_protocol'); }
+      }
+    }
+    for (const [capability, assignment] of Object.entries(catalog.assignments || {})) {
+      if (!isKnownCapability(capability)) issues.push('unknown_assignment_capability');
+      for (const ref of (Array.isArray(assignment) ? assignment : [assignment])) if (!resolvePoolModel(pool, ref, capability)) issues.push('unavailable_assignment_model');
+    }
+    return { valid: issues.length === 0, issues: [...new Set(issues)] };
+  }
+  if (command === 'models.list') return { models: configSnapshot(catalog).models };
+  if (command === 'assignments.list') return { ...catalogCapabilitySnapshot(catalog), assignments: assignmentSnapshot(catalog) };
+  let result = { command, changed: true };
+  const initialPool = modelPool(catalog.providers);
+  let provider;
+  const providerId = input.provider_id || parseModelRef(input.model_ref)?.providerId || input.provider?.id;
+  if (providerId) {
+    const matches = catalog.providers.filter(value => value.id === providerId);
+    if (matches.length > 1) fail('Provider ID 不唯一');
+    provider = matches[0];
+  }
+  if (command === 'providers.add' || command === 'providers.set') {
+    const value = input.provider;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) fail('需要 provider 对象');
+    const id = text(value.id);
+    if (command === 'providers.add' ? Boolean(provider) : !provider) fail(command === 'providers.add' ? 'Provider 已存在' : 'Provider 不存在');
+    const updated = { ...(provider || {}), ...value, id };
+    if (updated.visionInput !== undefined) updated.visionInput = normalizeVisionInputLimits(updated.visionInput) || null;
+    let url;
+    try { url = new URL(updated.baseUrl); } catch (_) { fail('baseUrl 必须是 HTTP(S) 地址'); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) fail('baseUrl 含不支持的协议或凭据参数');
+    if (updated.enabled !== undefined && typeof updated.enabled !== 'boolean') fail('enabled 必须是布尔值');
+    if (updated.models !== undefined) {
+      if (!Array.isArray(updated.models)) fail('models 必须是数组');
+      for (const model of updated.models) {
+        text(typeof model === 'string' ? model : model?.id);
+        if (model?.capabilities !== undefined) caps(model.capabilities);
+      }
+      updated.models = updated.models.map(model => typeof model === 'string' ? model : ({ ...model,
+        ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
+        ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
+    }
+    if (provider) {
+      for (const model of providerModels(provider)) {
+        if (selectImageProtocol(provider, model.id).mediaProtocol !== selectImageProtocol(updated, model.id).mediaProtocol) {
+          clearModelCapabilityHealth(updated, model.id, 'image-gen');
+        }
+      }
+    }
+    if (provider) catalog.providers[catalog.providers.indexOf(provider)] = updated;
+    else catalog.providers.push(updated);
+  } else if (command === 'providers.remove') {
+    if (!provider) fail('Provider 不存在');
+    catalog.providers.splice(catalog.providers.indexOf(provider), 1);
+  } else if (command.startsWith('models.')) {
+    if (!provider) fail('Provider 不存在');
+    const parsed = parseModelRef(input.model_ref);
+    const modelId = parsed?.modelId || input.model_id;
+    let entries = Array.isArray(provider.models) ? provider.models.map(model => typeof model === 'string' ? { id: model } : { ...model })
+      : providerModels(provider).map(({ id, capabilities }) => ({ id, capabilities }));
+    let entry = entries.find(model => model.id === modelId);
+    if (command === 'models.discover') {
+      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(provider), 'discover', { signal, timeoutMs: 15000 });
+      const models = discovered.models.map(model => ({ id: text(typeof model === 'string' ? model : model.id), capabilities: capabilitiesOfDiscoveredModel(model), source: 'discovered' }));
+      result = { command, changed: input.apply === true, total: models.length, mediaCount: models.filter(model => model.capabilities.length).length, models: models.map(model => ({ ...model, id: safe(model.id) })) };
+      if (input.apply !== true) return result;
+      for (const model of models) {
+        if (!model.capabilities.length) continue;
+        const old = entries.find(value => value.id === model.id);
+        if (!old) entries.push(model);
+        else if (old.source !== 'manual') Object.assign(old, model);
+      }
+    } else if (command === 'models.add') {
+      text(modelId);
+      const capabilities = input.capabilities === undefined ? capabilitiesOfModel(modelId) : caps(input.capabilities);
+      if (entry) fail('模型已存在；请用 models caps 修改能力');
+      entries.push({ id: modelId, capabilities, source: 'manual',
+        ...(input.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(input.imageProtocol) } : {}),
+        ...(input.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(input.visionInput) || null } : {}) });
+    } else if (command === 'models.remove') {
+      if (!entry) fail('模型不存在');
+      entries = entries.filter(model => model.id !== modelId);
+    } else if (command === 'models.caps') {
+      if (!entry) fail('模型不存在');
+      entry.capabilities = caps(input.capabilities); entry.source = 'manual';
+    } else if (command === 'models.protocol') {
+      if (!entry) fail('模型不存在');
+      const protocol = normalizeImageProtocol(input.imageProtocol);
+      const previous = selectImageProtocol(provider, modelId).mediaProtocol;
+      if (protocol === 'auto') delete entry.imageProtocol;
+      else entry.imageProtocol = protocol;
+      provider.models = entries;
+      if (previous !== selectImageProtocol(provider, modelId).mediaProtocol) clearModelCapabilityHealth(provider, modelId, 'image-gen');
+      result = { ...result, model_ref: safe(input.model_ref), imageRouting: selectImageProtocol(provider, modelId) };
+    } else if (command === 'models.vision-input') {
+      if (!entry || !Object.hasOwn(input, 'visionInput')) fail('需要已存在的模型和 visionInput 对象或 null');
+      const limits = normalizeVisionInputLimits(input.visionInput);
+      if (limits) entry.visionInput = limits;
+      else delete entry.visionInput;
+      provider.models = entries;
+      result = { ...result, model_ref: safe(input.model_ref), visionInputEffective: visionInputLimits(provider, modelId) };
+    } else if (command === 'models.test') {
+      if (!entry || !isKnownCapability(input.capability) || !providerModels(provider).find(model => model.id === modelId)?.capabilities.includes(input.capability)) fail('模型不存在或没有指定能力');
+      if (typeof probe !== 'function') fail('模型实测缺少 Probe Port');
+      const tested = await probe({ provider, modelId, capability: input.capability, signal });
+      if (tested.skipped) return { command, changed: false, ...tested };
+      const evidence = { at: new Date().toISOString(), source: 'probe', category: tested.category || (tested.ok ? 'success' : 'unknown'),
+        ...(tested.httpStatus || tested.status ? { httpStatus: tested.httpStatus || tested.status } : {}) };
+      entry.verified = { ...(entry.verified || {}), [input.capability]: { ok: tested.ok === true, ...evidence } };
+      provider.health ||= { version: 1, revision: 0, observations: [] };
+      const observations = provider.health.observations;
+      let observation = observations.find(value => value.modelId === modelId && value.capability === input.capability);
+      if (!observation) { observation = { modelId, capability: input.capability }; observations.push(observation); }
+      if (tested.ok === true) { observation.lastSuccess = evidence; clearModelRateLimit(provider, modelId); }
+      else {
+        observation[isDefinitiveHealthFailure(evidence) ? 'lastFailure' : 'lastTransient'] = evidence;
+        recordModelRateLimit(provider, modelId, evidence);
+      }
+      result = { command, changed: true, passed: tested.ok === true, ...(tested.taskId ? { taskId: tested.taskId } : {}), ...(tested.code ? { code: tested.code } : {}) };
+    } else fail('未知模型命令');
+    provider.models = entries;
+  } else if (command === 'assignments.set' || command === 'assignments.clear') {
+    if (!isKnownCapability(input.capability)) fail('未知能力');
+    catalog.assignments ||= {};
+    if (command === 'assignments.clear') delete catalog.assignments[input.capability];
+    else {
+      if (!Array.isArray(input.model_refs) || new Set(input.model_refs).size !== input.model_refs.length) fail('model_refs 必须是不重复的复合引用数组');
+      const pool = modelPool(catalog.providers);
+      for (const ref of input.model_refs) if (!parseModelRef(ref) || !resolvePoolModel(pool, ref, input.capability)) fail('分配模型不存在或没有该能力');
+      catalog.assignments[input.capability] = input.model_refs;
+    }
+  } else fail('未知配置命令');
+
+  // 移除/降级条目时剪去明确指向该条目的分配，保留其他账号和旧裸引用格式。
+  if (command === 'providers.remove' || command === 'models.remove' || command === 'models.caps') {
+    const pool = modelPool(catalog.providers);
+    for (const [capability, assignment] of Object.entries(catalog.assignments || {})) {
+      const values = (Array.isArray(assignment) ? assignment : [assignment]).filter(ref => resolvePoolModel(pool, ref, capability) || !resolvePoolModel(initialPool, ref, capability));
+      if (!values.length) delete catalog.assignments[capability];
+      else catalog.assignments[capability] = Array.isArray(assignment) ? values : values[0];
+    }
+  }
+  signal?.throwIfAborted();
+  return writeConfigChange(configPath, catalog, before, result);
+}
+
+/** 请求边界持久化冷却或明确耗尽；沿用配置锁、备份与原子写入。 */
+export function recordCatalogRateLimit(configPath, event) {
+  const { providerId, modelId } = event;
+  const catalog = loadProviderCatalog(configPath);
+  const before = fs.readFileSync(configPath);
+  const provider = catalog.providers.find(value => value.id === providerId);
+  if (!provider || !recordModelRateLimit(provider, modelId, { ...event, source: 'task' })) return;
+  return writeConfigChange(configPath, catalog, before, { changed: true });
+}
+
+function writeConfigChange(configPath, catalog, before, result) {
+  const lock = configPath + '.lock';
+  let fd;
+  try { fd = fs.openSync(lock, 'wx', 0o600); }
+  catch (_) { throw Object.assign(new Error('配置正在被另一进程修改'), { code: 'IRIS_CONFIG_BUSY' }); }
+  try {
+    loadProviderCatalog(configPath);
+    if (hash(fs.readFileSync(configPath)) !== hash(before)) throw Object.assign(new Error('配置在操作期间发生变化，请重新读取后重试'), { code: 'IRIS_CONFIG_CHANGED' });
+    const backupPath = privateSibling(configPath, 'backup');
+    fs.writeFileSync(backupPath, before, { flag: 'wx', mode: 0o600 });
+    atomicWritePrivate(configPath, JSON.stringify(catalog, null, 2) + '\n');
+    result.backupPath = backupPath;
+    return result;
+  } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}

package/lib/provider-contract.js

@@ -146,7 +146,8 @@ export function normalizeProviderArtifacts(value) {
     }
     if (item.kind === 'inline-base64') {
       const data = String(item.data || '').trim();
-      if (!data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) {
+      // 避免按四字符重复分组：4K 图片的大 base64 正文会耗尽正则回溯栈。
+      if (!data || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) {
         throw new TypeError('Provider inline-base64 artifact 数据无效');
       }
       const padding = data.endsWith('==') ? 2 : (data.endsWith('=') ? 1 : 0);
@@ -287,7 +288,7 @@ export async function submitWithAcceptanceBoundary(candidates, input, hooks = {}
       }
     }
 
-    if (!allowsAutomaticFailover(result)) {
+    if (hooks.signal?.aborted || !allowsAutomaticFailover(result)) {
       return { candidate, result, attempts, localError: null };
     }
   }

package/lib/provider-health.js

@@ -10,6 +10,85 @@ export const PROVIDER_HEALTH_STATES = Object.freeze([
 ]);
 
 const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
+export const MODEL_RATE_LIMIT_COOLDOWN_MS = 60000;
+
+export function retryAfterDelay(value, now = Date.now()) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return MODEL_RATE_LIMIT_COOLDOWN_MS;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.max(1000, seconds * 1000);
+  const at = Date.parse(raw);
+  return Number.isFinite(at) && at > now ? at - now : MODEL_RATE_LIMIT_COOLDOWN_MS;
+}
+
+/** 百炼“免费额度用完即停”返回 403，不应误归类为 Key 无效。 */
+export function isFreeQuotaExhausted(value) {
+  const status = Number(value?.httpStatus ?? value?.status);
+  if (![403, 429].includes(status)) return false;
+  return status === 403 && (value.category === 'quota' || value.code === 'IRIS_MODEL_RATE_LIMITED')
+    || (value.providerCode || value.code) === 'AllocationQuota.FreeTierOnly'
+    || /\bfree (?:allocated quota|quota|tier)\b[^\n]{0,120}\b(?:exhausted|expired|exceeded)\b/i.test(String(value.message || value.safeMessage || value.note || ''));
+}
+
+export function quotaExhaustionReason(value) {
+  if (isFreeQuotaExhausted(value) || value?.reason === 'free_quota') return 'free_quota';
+  const status = Number(value?.httpStatus ?? value?.status);
+  if (status !== 429) return null;
+  if ((value.providerCode || value.code) === 'BudgetLimitExceeded' || value.reason === 'budget') return 'budget';
+  return null;
+}
+
+/** 短时限流到期即可参与候选；额度/预算耗尽只有成功实测才解除。 */
+export function modelRateLimit(provider, modelId, { now = Date.now() } = {}) {
+  const blocked = provider?.health?.rateLimits?.find(item => item.modelId === modelId);
+  return blocked && (!blocked.until || Date.parse(blocked.until) > now) ? blocked : null;
+}
+
+export function recordModelRateLimit(provider, modelId, result) {
+  const status = Number(result?.httpStatus ?? result?.status);
+  const reason = quotaExhaustionReason(result);
+  const category = reason ? 'quota' : status === 429 ? 'rate_limit' : null;
+  const existing = modelRateLimit(provider, modelId);
+  if (!category || !modelId || existing && (!reason || existing.reason)) return false;
+  provider.health ||= { version: 1, revision: 0, observations: [] };
+  provider.health.rateLimits ||= [];
+  const at = Date.parse(result.at || '');
+  const timestamp = Number.isFinite(at) ? at : Date.now();
+  const delay = Number.isFinite(result.retryAfterMs) ? result.retryAfterMs : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
+  provider.health.rateLimits.push({ modelId,
+    at: new Date(timestamp).toISOString(),
+    source: result.source === 'probe' ? 'probe' : 'task', category, httpStatus: status,
+    ...(reason ? { reason } : { until: result.until || new Date(timestamp + Math.max(1000, delay)).toISOString() }) });
+  return true;
+}
+
+/** 只有显式模型实测通过才调用；普通任务成功不能解除停用。 */
+export function clearModelRateLimit(provider, modelId) {
+  if (!provider?.health?.rateLimits) return;
+  provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
+  if (!provider.health.rateLimits.length) delete provider.health.rateLimits;
+}
+
+/** 配置改变时使一项能力验证失效；保留同模型的限流/耗尽资格和其他能力。 */
+export function clearModelCapabilityHealth(provider, modelId, capability) {
+  if (provider.health?.observations) {
+    provider.health = { ...provider.health, revision: (provider.health.revision || 0) + 1,
+      observations: provider.health.observations.filter(item => item.modelId !== modelId || item.capability !== capability) };
+  }
+  const entry = provider.models?.find(model => model?.id?.trim() === modelId);
+  if (entry?.verified) {
+    entry.verified = { ...entry.verified };
+    delete entry.verified[capability];
+  }
+}
+
+export function reportModelRateLimit(provider, modelId, result, onRateLimit, capability) {
+  if (!recordModelRateLimit(provider, modelId, result)) return;
+  const blocked = modelRateLimit(provider, modelId);
+  try { onRateLimit?.({ providerId: provider.id, capability, ...blocked }); }
+  catch (_) { console.warn('[iris] 模型停用状态未能持久化，请检查配置写入权限'); }
+}
 
 function validTime(value) {
   const ms = Date.parse(String(value || ''));
@@ -19,7 +98,7 @@ function validTime(value) {
 export function isDefinitiveHealthFailure(value) {
   const status = Number(value && (value.httpStatus ?? value.status));
   const category = String(value && value.category || '').toLowerCase();
-  return status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category);
+  return !isFreeQuotaExhausted(value) && (status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category));
 }
 
 export function healthObservationState(observation, {

package/lib/provider-protocol.js

@@ -45,6 +45,29 @@ export function selectMediaProtocol(provider) {
   return { mediaProtocol: detected || 'openai-images', protocolInferred: !detected };
 }
 
+/** 模型图片协议只覆盖生图；auto 沿用账号级默认，不另外猜测端点。 */
+export function normalizeImageProtocol(value) {
+  const protocol = typeof value === 'string' ? value.trim() : '';
+  if (!['auto', 'dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) {
+    throw Object.assign(new TypeError('imageProtocol 必须是 auto、dashscope、openai-images、openai-chat-images 或 openai-responses-images'), {
+      code: 'IRIS_PROVIDER_IMAGE_PROTOCOL_INVALID'
+    });
+  }
+  return protocol;
+}
+
+export function selectImageProtocol(provider, modelId) {
+  const entry = Array.isArray(provider?.models) ? provider.models.find(model => model?.id?.trim() === modelId) : null;
+  if (entry?.imageProtocol === undefined) return selectMediaProtocol(provider);
+  const protocol = normalizeImageProtocol(entry.imageProtocol);
+  return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
+}
+
+/** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
+export function providerForImageModel(provider, modelId) {
+  return { ...provider, ...selectImageProtocol(provider, modelId) };
+}
+
 export function unsupportedProtocolError(protocol, kind = 'media') {
   const safeName = /^[a-z][a-z0-9-]{0,63}$/.test(String(protocol)) ? protocol : '(invalid)';
   const error = new TypeError('iris: 不支持的 ' + (kind === 'vision' ? 'Vision' : 'Provider') + ' 协议：' + safeName);

package/lib/provider-task-runner.js

@@ -3,6 +3,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import sharp from 'sharp';
 import { createCoreArtifact } from './core-artifacts.js';
 import {
   activateCoreWatch,
@@ -28,7 +29,8 @@ import {
   hasProviderOperation,
   invokeProviderOperation
 } from './provider-adapter.js';
-import { providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -38,7 +40,7 @@ export const PROVIDER_TASK_RUNNER_VERSION = 0;
  * 失败，不会按图片语义猜。
  */
 export const DELIVERY_PROFILES = Object.freeze({
-  image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png']), defaultMediaType: 'image/png' }),
+  image: Object.freeze({ kind: 'generated-image', mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/webp']), defaultMediaType: 'image/png' }),
   video: Object.freeze({ kind: 'generated-video', mediaTypes: Object.freeze(['video/mp4']), defaultMediaType: 'video/mp4' }),
   // TTS 同步完成型：submit 内 completed → 同一次调用直接交付（无 remote 长轮询）。
   tts: Object.freeze({ kind: 'generated-audio', mediaTypes: Object.freeze(['audio/mpeg', 'audio/wav']), defaultMediaType: 'audio/mpeg' }),
@@ -81,7 +83,8 @@ function normalizedCandidates(capability, candidates) {
         || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))) {
       throw new TypeError('Provider 候选 ' + (index + 1) + ' 不支持 Task capability 或模型复合身份无效');
     }
-    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason };
+    if (candidate.prepareInput !== undefined && typeof candidate.prepareInput !== 'function') throw new TypeError('候选 prepareInput 必须是函数');
+    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason, prepareInput: candidate.prepareInput };
   });
 }
 
@@ -91,6 +94,21 @@ function stagingFile(dataRoot) {
   return path.join(directory, 'download-' + process.pid + '-' + crypto.randomBytes(8).toString('hex') + '.part');
 }
 
+async function generatedImageMediaType(bytes) {
+  let format;
+  try { format = (await sharp(bytes).metadata()).format; }
+  catch (_) {
+    throw new ProviderContractError('供应商产物不是可识别的图片', {
+      stage: 'download', category: 'protocol', acceptance: 'accepted'
+    });
+  }
+  const mediaType = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }[format];
+  if (!mediaType) throw new ProviderContractError('供应商图片格式仅支持 PNG、JPEG、WebP', {
+    stage: 'download', category: 'protocol', acceptance: 'accepted'
+  });
+  return mediaType;
+}
+
 async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, signal) {
   beginCoreDelivery(dataRoot, taskId);
   const artifactIds = [];
@@ -110,7 +128,7 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
     }
     for (const remote of remoteArtifacts) {
       const mediaType = String(remote.mediaType || profile.defaultMediaType);
-      if (!profile.mediaTypes.includes(mediaType)) {
+      if (task.capability !== 'image' && !profile.mediaTypes.includes(mediaType)) {
         throw Object.assign(new Error('Provider Task Runner 交付媒体类型不在 Profile 白名单：' + mediaType), {
           stage: 'download', category: 'protocol', acceptance: 'accepted'
         });
@@ -129,14 +147,20 @@ async function deliverArtifacts(dataRoot, taskId, adapter, remoteArtifacts, sign
           stage: 'download', category: 'local_io', acceptance: 'accepted'
         });
       }
+      const staged = stagedFiles.at(-1);
+      if (task.capability === 'image') {
+        staged.bytes = fs.readFileSync(target);
+        staged.mediaType = await generatedImageMediaType(staged.bytes);
+      }
     }
     recordCoreDownloadCompleted(dataRoot, taskId);
     for (const staged of stagedFiles) {
       const artifact = createCoreArtifact(dataRoot, {
         kind: profile.kind,
         mediaType: staged.mediaType,
-        bytes: fs.readFileSync(staged.target),
-        metadata: { taskId, capability: task.capability }
+        bytes: staged.bytes || fs.readFileSync(staged.target),
+        metadata: { taskId, capability: task.capability },
+        ...(task.sourceArtifactId ? { relations: [{ type: 'derived-from', artifactId: task.sourceArtifactId }] } : {})
       });
       artifactIds.push(artifact.id);
     }
@@ -199,21 +223,39 @@ export function createProviderTaskRunner(runtime) {
 
   async function submit(input = {}) {
     return runtime.run('execute', async ({ dataRoot, signal }) => {
+      if (signal.aborted) throw new ProviderTaskRunnerError('IRIS_PROVIDER_ABORTED', '提交已取消');
       const capability = String(input.capability || '').trim();
-      const candidates = normalizedCandidates(capability, input.candidates);
-      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom });
-      const wrapped = candidates.map(({ adapter, model, providerModel }) => ({
+      let candidates = normalizedCandidates(capability, input.candidates);
+      let providerInput = input.providerInput ?? {};
+      if (input.sourceArtifactId !== undefined) {
+        if (capability !== 'image') throw new TypeError('sourceArtifactId 仅用于图片编辑');
+        candidates = imageEditCandidates(candidates);
+        const image = await readImageEditArtifact(dataRoot, input.sourceArtifactId, signal);
+        providerInput = { ...providerInput, image };
+      }
+      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+      const wrapped = candidates.map(({ adapter, model, providerModel, prepareInput }) => ({
         id: adapter.id,
         model,
         adapter,
-        submit: (providerInput, context) => invokeProviderOperation(
-          adapter,
-          'submit',
-          { capability, model: providerModel, input: providerInput, signal },
-          { ...context, signal, taskId: task.id }
-        )
+        submit: async (providerInput, context) => {
+          if (prepareInput) {
+            try { providerInput = await prepareInput({ providerInput, signal }); }
+            catch (error) { throw new ProviderContractError('视频输入准备失败：' + (error.safeMessage || error.message), {
+              ...providerErrorRecord(error), stage: error.stage || 'prepare', category: error.category || 'local_io', acceptance: 'not_accepted'
+            }); }
+          }
+          if (signal.aborted) throw new ProviderContractError('提交已取消', { stage: 'prepare', category: 'aborted', acceptance: 'not_accepted' });
+          return invokeProviderOperation(
+            adapter,
+            'submit',
+            { capability, model: providerModel, input: providerInput, signal },
+            { ...context, signal, taskId: task.id }
+          );
+        }
       }));
-      const submitted = await submitWithAcceptanceBoundary(wrapped, input.providerInput ?? {}, {
+      const submitted = await submitWithAcceptanceBoundary(wrapped, providerInput, {
+        signal,
         beforeAttempt: async (attempt) => {
           const candidate = candidates[attempt.ordinal - 1];
           return beginCoreAttempt(dataRoot, task.id, {

package/lib/summarize.js

@@ -3,16 +3,20 @@
  * Iris 多模态上下文摘要（阶段 7.3）—— 把视频压成「一张联系表 + 一段转写文本」喂给视觉模型。
  *
  * 为什么是 contact sheet：
- * - VisionBackend 一次 analyze 只送一张图（自持栈吃 dataUrl / 全局模型吃 attachment ref），
+ * - Vision Port 一次 complete 只送一张图（字节与 MIME），
  *   逐帧送 N 次要 N 次模型调用、费用与延迟都不可接受；
  * - 把 N 帧缩略图按时间序拼成网格 + 每帧盖时间戳标签，一次视觉调用即可看全片（上下文压缩）。
  *
  * 契约：
- * - buildContactSheet(frames, opts) → PNG buffer + 网格尺寸（纯 sharp，可离线测试）
- * - summarizeMedia({backends, question?, transcript?, imageDataUrl, ref, signal})
- *   → askWithBackends（复用阶段 1 降级链），prompt 里嵌入转写文本（若有）
+ * - buildContactSheet({frames, ...opts}) → PNG buffer + 网格尺寸（纯 sharp，可离线测试）
+ * - summarizeMedia({ports, frames, question?, transcript?, signal})
+ *   → 一张拼图通过共享 Vision Ports，转写只消费显式输入
  */
 import sharp from 'sharp';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { createModelOperation } from './model-invoker.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { ModelPortError } from './model-port-contract.js';
 
 export class SummarizeError extends Error {
   constructor(message) {
@@ -28,7 +32,11 @@ const DEFAULT_QUESTION = '请根据这些视频关键帧（按时间顺序从左
  * @param {{frames:Array<{buffer:Buffer, atSec:number, width:number, height:number}>, cols?:number, maxSheetWidth?:number}}
  * @returns {Promise<{buffer:Buffer, width:number, height:number, rows:number, cols:number}>}
  */
-export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024 }) {
+export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024, signal }) {
+  return waitForModelWork(() => makeContactSheet({ frames, cols, maxSheetWidth, signal }), signal);
+}
+
+async function makeContactSheet({ frames, cols, maxSheetWidth, signal }) {
   if (!Array.isArray(frames) || frames.length === 0) {
     throw new SummarizeError('iris_media_summarize: 没有可拼的帧');
   }
@@ -47,10 +55,10 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
     const w = Math.max(1, cellW);
     const scale = w / Math.max(1, f.width || w);
     const h = Math.max(1, Math.round((f.height || 0) * scale));
-    const thumb = await sharp(f.buffer)
+    const thumb = await waitForModelWork(() => sharp(f.buffer)
       .resize(w, h, { fit: 'fill' })
       .png()
-      .toBuffer();
+      .toBuffer(), signal);
     // 时间戳标签（SVG 覆盖在缩略图下方）
     const label = Buffer.from(
       `<svg width="${w}" height="${labelH}" xmlns="http://www.w3.org/2000/svg">` +
@@ -58,10 +66,11 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
       `<text x="4" y="${labelH - 7}" font-family="monospace" font-size="12" fill="#ffffff">` +
       `${f.atSec.toFixed(1)}s</text></svg>`
     );
-    const cell = await sharp(thumb)
+    const cell = await waitForModelWork(() => sharp(thumb)
+      .extend({ bottom: labelH, background: { r: 16, g: 16, b: 20 } })
       .composite([{ input: label, top: h, left: 0 }])
       .png()
-      .toBuffer();
+      .toBuffer(), signal);
     cells.push({ buffer: cell, width: w, height: h + labelH });
   }
 
@@ -73,12 +82,12 @@ export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024
     left: (i % colsN) * (cellW + gap),
     top: Math.floor(i / colsN) * (cellH + gap)
   }));
-  const buffer = await sharp({
+  const buffer = await waitForModelWork(() => sharp({
     create: { width: sheetW, height: sheetH, channels: 3, background: { r: 16, g: 16, b: 20 } }
   })
     .composite(composite)
     .png()
-    .toBuffer();
+    .toBuffer(), signal);
   return { buffer, width: sheetW, height: sheetH, rows: rowsN, cols: colsN };
 }
 
@@ -98,14 +107,16 @@ export function buildSummaryPrompt({ question, transcript }) {
 
 /**
  * 多模态摘要：contact sheet 图 + 可选转写文本 → 视觉后端链 → 摘要文本。
- * @param {{backends:Array, question?:string, transcript?:string, imageDataUrl:string, ref?:object, signal?:AbortSignal}}
- * @returns {Promise<{answer:string, via:string, model:string, backendId:string, errors:Array}>}
+ * @param {{ports:Array, frames:Array, question?:string, transcript?:string, signal?:AbortSignal}}
+ * @returns {Promise<object>} 完整模型结果和同一张拼图
  */
-export async function summarizeMedia({ backends, question, transcript, imageDataUrl, ref, signal }) {
-  if (!Array.isArray(backends) || backends.length === 0) {
-    throw new SummarizeError('iris_media_summarize: 没有可用的视觉后端（至少需要一个 vision provider）');
-  }
-  const { askWithBackends } = await import('./vision.js');
-  const prompt = buildSummaryPrompt({ question, transcript });
-  return askWithBackends(backends, { question: prompt, imageDataUrl, ref, signal });
+export async function summarizeMedia({ ports = [], frames, question, transcript, signal, operation, budget = VISION_BUDGET }) {
+  if (!ports.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  const op = operation || createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: ports.length } });
+  try {
+    const sheet = await buildContactSheet({ frames, cols: 3, signal: op.signal });
+    const result = await completeVision(ports, { prompt: buildSummaryPrompt({ question, transcript }),
+      image: { bytes: new Uint8Array(sheet.buffer), mediaType: 'image/png' } }, { operation: op, budget });
+    return { ...result, sheet };
+  } finally { if (!operation) op.dispose(); }
 }