@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/lib/provider-adapter.js

@@ -8,6 +8,7 @@
  */
 import {
   ProviderContractError,
+  normalizeProviderArtifacts,
   normalizeSubmissionResult,
   providerErrorRecord,
   resultFromThrown
@@ -69,7 +70,8 @@ function normalizedReason(value, fallback) {
 export function defineProviderAdapter(input) {
   if (!isPlainObject(input)) throw new TypeError('Provider Adapter 必须是对象');
   const allowed = new Set([
-    'contractVersion', 'id', 'protocol', 'capabilities', 'operations', 'unsupported'
+    'contractVersion', 'id', 'protocol', 'capabilities', 'operations', 'unsupported',
+    'prepareInput', 'unsupportedPreparation'
   ]);
   for (const key of Object.keys(input)) {
     if (!allowed.has(key)) throw new Error('Provider Adapter 不允许顶层字段：' + key);
@@ -118,13 +120,24 @@ export function defineProviderAdapter(input) {
     throw new Error('Provider Adapter 必须实现 submit 与 mapError');
   }
 
+  if (input.prepareInput !== undefined && typeof input.prepareInput !== 'function') {
+    throw new TypeError('Provider prepareInput 必须是函数');
+  }
+  if (input.prepareInput && input.unsupportedPreparation !== undefined) {
+    throw new Error('Provider 输入准备不能同时声明 supported 与 unsupported');
+  }
+  const unsupportedPreparation = input.prepareInput ? undefined
+    : normalizedReason(input.unsupportedPreparation, '协议未实现临时输入上传');
+
   return Object.freeze({
     contractVersion,
     id,
     protocol,
     capabilities: Object.freeze(capabilities),
     operations: Object.freeze(operations),
-    unsupported: Object.freeze(unsupported)
+    unsupported: Object.freeze(unsupported),
+    prepareInput: input.prepareInput,
+    unsupportedPreparation
   });
 }
 
@@ -170,10 +183,40 @@ export function providerAdapterSnapshot(adapter) {
       protocol: adapter?.protocol || 'unknown'
     }),
     capabilities: Object.freeze([...(adapter?.capabilities || [])]),
-    operations: Object.freeze(operations)
+    operations: Object.freeze(operations),
+    inputPreparation: Object.freeze(typeof adapter?.prepareInput === 'function'
+      ? { status: 'supported' }
+      : { status: 'unsupported', reason: adapter?.unsupportedPreparation || '协议未实现临时输入上传' })
   });
 }
 
+/** 提交前的可选上传能力；不创建 Task，也不属于六个生命周期操作。 */
+export async function prepareProviderInput(adapter, input = {}) {
+  if (typeof adapter?.prepareInput !== 'function') {
+    const error = new ProviderContractError(adapter?.unsupportedPreparation || '协议未实现临时输入上传', {
+      stage: 'upload', category: 'invalid_request', acceptance: 'not_accepted',
+      providerCode: 'IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED'
+    });
+    error.code = 'IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED';
+    throw error;
+  }
+  try {
+    const value = await adapter.prepareInput(input);
+    if (typeof value?.url !== 'string' || !value.url.trim()) {
+      throw new ProviderContractError('Provider 输入准备必须返回非空 url', {
+        stage: 'upload', category: 'protocol', acceptance: 'not_accepted'
+      });
+    }
+    // 临时地址只供随后的提交使用，避免随日志或任务 JSON 序列化。
+    return Object.freeze(Object.defineProperty({}, 'url', { value: value.url }));
+  } catch (error) {
+    const context = { stage: 'upload', acceptance: 'not_accepted' };
+    const safe = providerErrorRecord(error instanceof ProviderContractError
+      ? error : mappedError(adapter, error, context), context);
+    throw new ProviderContractError(safe.safeMessage, safe);
+  }
+}
+
 export function normalizeDiscoveryResult(value) {
   const source = Array.isArray(value) ? value : value?.models;
   if (!Array.isArray(source)) throw new TypeError('Provider discover 必须返回 models 数组');
@@ -193,23 +236,6 @@ export function normalizeDiscoveryResult(value) {
   return Object.freeze({ models: Object.freeze(models) });
 }
 
-function normalizeArtifacts(value) {
-  if (value === undefined) return Object.freeze([]);
-  if (!Array.isArray(value)) throw new TypeError('Provider poll artifacts 必须是数组');
-  return Object.freeze(value.map((item) => {
-    if (!isPlainObject(item) || item.kind !== 'remote-url') {
-      throw new TypeError('Provider artifact 当前只支持 remote-url');
-    }
-    const url = String(item.url || '').trim();
-    if (!url) throw new TypeError('Provider remote-url artifact 缺少 url');
-    return Object.freeze({
-      kind: 'remote-url',
-      url,
-      ...(typeof item.mediaType === 'string' && item.mediaType ? { mediaType: item.mediaType } : {})
-    });
-  }));
-}
-
 /**
  * poll 标准结果。兼容旧 {done,ok,urls,text,status,message} 仅用于 0.1.x 渐进迁移；
  * 新 Adapter 必须直接返回 kind 结果。
@@ -225,7 +251,7 @@ export function normalizeProviderPollResult(value) {
     if (value.ok) {
       return Object.freeze({
         kind: 'succeeded',
-        artifacts: normalizeArtifacts((value.urls || []).map((url) => ({ kind: 'remote-url', url }))),
+        artifacts: normalizeProviderArtifacts((value.urls || []).map((url) => ({ kind: 'remote-url', url }))),
         ...(typeof value.text === 'string'
           ? { value: Object.freeze({ kind: 'text', text: value.text }) }
           : {})
@@ -251,7 +277,7 @@ export function normalizeProviderPollResult(value) {
   if (value.kind === 'succeeded') {
     return Object.freeze({
       kind: 'succeeded',
-      artifacts: normalizeArtifacts(value.artifacts),
+      artifacts: normalizeProviderArtifacts(value.artifacts),
       ...(value.value !== undefined ? { value: value.value } : {})
     });
   }
@@ -356,7 +382,7 @@ export function providerPollTaskView(value) {
     return { kind: result.kind, done: false, ok: false, urls: [], status: result.progress || 'running' };
   }
   if (result.kind === 'succeeded') {
-    const urls = result.artifacts.map((item) => item.url);
+    const urls = result.artifacts.filter((item) => item.kind === 'remote-url').map((item) => item.url);
     if (result.value?.kind === 'text') urls.push(String(result.value.text || ''));
     return { kind: result.kind, done: true, ok: true, urls, value: result.value };
   }

package/lib/provider-adapters.js

@@ -8,15 +8,18 @@
  */
 import * as defaultTransport from './adapters.js';
 import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
+import { writePrivateFile } from './private-storage.js';
 import { defineProviderAdapter } from './provider-adapter.js';
-import { inferMediaProtocol } from './provider-protocol.js';
+import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError } from './provider-protocol.js';
+import { modelRateLimit, reportModelRateLimit, isFreeQuotaExhausted } from './provider-health.js';
+import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
 
 const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
 
 function providerIdentity(provider) {
   const id = String(provider?.id || '').trim();
-  const key = String(provider?.apiKey || '');
-  const baseUrl = String(provider?.baseUrl || '').trim();
+  const key = providerApiKey(provider);
+  const baseUrl = providerMediaBaseUrl(provider);
   if (!id) throw new TypeError('Provider 配置缺少 id');
   if (!baseUrl) throw new TypeError('Provider 配置缺少 baseUrl');
   return { id, key, baseUrl };
@@ -26,17 +29,19 @@ function mappedCategory(error, status) {
   const raw = String(error?.category || '').toLowerCase();
   if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
   if (error?.name === 'TimeoutError' || /timeout|timed out|超时/i.test(String(error?.message || ''))) return 'timeout';
+  if (isFreeQuotaExhausted(error)) return 'quota';
   if (status === 401 || status === 403 || raw === 'auth') return 'authentication';
   if (status === 429 && raw === 'quota') return 'quota';
   if (status === 429 || raw === 'rate_limit') return 'rate_limit';
-  if (raw === 'invalid_parameter') return 'invalid_request';
+  if (raw === 'invalid_parameter' || raw === 'invalid_request') return 'invalid_request';
+  if (raw === 'protocol') return 'protocol';
   if (raw === 'network' || error instanceof TypeError) return 'network';
   if (raw === 'server' || status >= 500) return 'provider';
   if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
   return 'provider';
 }
 
-/** 当前两个协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
+/** 已支持协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
 export function mapProviderAdapterError(error, context = {}) {
   const statusValue = Number(error?.httpStatus ?? error?.status);
   const httpStatus = Number.isInteger(statusValue) && statusValue >= 100 && statusValue <= 599
@@ -82,6 +87,36 @@ function pollFailureKind(status) {
   return 'failed';
 }
 
+function remoteImageArtifacts(urls) {
+  return (urls || []).map((url) => ({ kind: 'remote-url', url, mediaType: 'image/png' }));
+}
+
+function openAiImageArtifacts(items) {
+  return (items || []).map((item) => {
+    if (item && item.b64) {
+      return { kind: 'inline-base64', data: item.b64, mediaType: item.mediaType || 'image/png' };
+    }
+    if (item && item.url) {
+      return { kind: 'remote-url', url: item.url, mediaType: item.mediaType || 'image/png' };
+    }
+    throw new ProviderContractError('同步图片结果缺少 b64 或 URL', {
+      stage: 'response', category: 'protocol', acceptance: 'accepted'
+    });
+  });
+}
+
+function writeInlineArtifact(artifact, targetPath) {
+  const data = String(artifact?.data || '').trim();
+  const body = Buffer.from(data, 'base64');
+  if (!data || body.length === 0 || body.toString('base64') !== data) {
+    throw new ProviderContractError('inline-base64 图片数据无效', {
+      stage: 'download', category: 'protocol', acceptance: 'accepted'
+    });
+  }
+  writePrivateFile(targetPath, body, { flag: 'wx' });
+  return { bytes: body.length };
+}
+
 function operationsForDashScope(provider, transport) {
   const { key, baseUrl } = providerIdentity(provider);
   return {
@@ -105,7 +140,10 @@ function operationsForDashScope(provider, transport) {
         const urls = await transport.generateImageMultimodal({
           ...common, prompt: input.prompt, size: input.size, n: input.n
         });
-        return { kind: 'completed', value: { kind: 'urls', items: urls } };
+        return {
+          kind: 'completed', value: { kind: 'urls', items: urls },
+          artifacts: remoteImageArtifacts(urls)
+        };
       }
       if (request.capability === 'video') {
         const remoteTaskId = await transport.submitVideo({
@@ -129,7 +167,11 @@ function operationsForDashScope(provider, transport) {
         const value = await transport.synthesizeTts({
           ...common, text: input.text, voice: input.voice
         });
-        return { kind: 'completed', value };
+        // E2：同步合成产物物化为 Core Artifact——URL 走下载，inline base64 直接落盘。
+        const artifacts = value.audioUrl
+          ? [{ kind: 'remote-url', url: value.audioUrl, mediaType: 'audio/mpeg' }]
+          : [{ kind: 'inline-base64', data: value.audioB64, mediaType: 'audio/mpeg' }];
+        return { kind: 'completed', value, artifacts };
       }
       throw unsupportedCapability(request.capability, 'dashscope');
     },
@@ -150,7 +192,13 @@ function operationsForDashScope(provider, transport) {
             })
           };
         }
-        return { kind: 'succeeded', value: { kind: 'text', text: String(result.text || '') } };
+        // E3：转写正文物化为 text/plain Artifact（inline-base64，不再依赖签名 URL 生命周期）。
+        const text = String(result.text || '');
+        return {
+          kind: 'succeeded',
+          value: { kind: 'text', text },
+          artifacts: [{ kind: 'inline-base64', data: Buffer.from(text, 'utf8').toString('base64'), mediaType: 'text/plain' }]
+        };
       }
       if (request.capability === 'image' || request.capability === 'video') {
         const result = await transport.pollTask(common);
@@ -173,17 +221,20 @@ function operationsForDashScope(provider, transport) {
 
     async download(request = {}) {
       const artifact = request.artifact || {};
-      if (artifact.kind !== 'remote-url' || !artifact.url) {
-        throw new ProviderContractError('download 需要 remote-url artifact', {
-          stage: 'download', category: 'protocol', acceptance: 'accepted'
-        });
-      }
       const targetPath = String(request.targetPath || '').trim();
       if (!targetPath) {
         throw new ProviderContractError('download 需要 targetPath', {
           stage: 'download', category: 'local_io', acceptance: 'accepted'
         });
       }
+      if (artifact.kind === 'inline-base64') {
+        return writeInlineArtifact(artifact, targetPath);
+      }
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要 remote-url artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
@@ -197,18 +248,22 @@ function operationsForDashScope(provider, transport) {
 }
 
 export function createDashScopeProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  const { key, baseUrl } = providerIdentity(provider);
   return defineProviderAdapter({
     id: providerIdentity(provider).id,
     protocol: 'dashscope',
     capabilities: ['image', 'video', 'tts', 'transcribe'],
     operations: operationsForDashScope(provider, transport),
+    async prepareInput({ model, filePath, signal, timeoutMs } = {}) {
+      return { url: await transport.uploadTempFile({ key, baseUrl, model, filePath, signal, timeoutMs }) };
+    },
     unsupported: {
       cancel: '当前 DashScope 媒体协议未提供经过验证的远端取消实现'
     }
   });
 }
 
-function operationsForOpenAiImages(provider, transport) {
+function operationsForOpenAiImages(provider, transport, protocol = 'openai-images') {
   const { key, baseUrl } = providerIdentity(provider);
   return {
     async discover({ signal, timeoutMs } = {}) {
@@ -217,35 +272,52 @@ function operationsForOpenAiImages(provider, transport) {
 
     async submit(request = {}) {
       if (request.capability !== 'image') {
-        throw unsupportedCapability(request.capability, 'openai-images');
+        throw unsupportedCapability(request.capability, protocol);
       }
       const input = request.input || {};
-      const items = await transport.openAiGenerateImage({
+      let image;
+      if (input.image) {
+        if (protocol !== 'openai-chat-images') throw new ProviderContractError('该图片协议不支持聊天改图', {
+          stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+        });
+        image = await prepareVisionImage(input.image, visionInputLimits(provider, request.model), { signal: request.signal, orient: true });
+      }
+      const method = {
+        'openai-images': 'openAiGenerateImage',
+        'openai-chat-images': 'openAiChatGenerateImage',
+        'openai-responses-images': 'openAiResponsesGenerateImage'
+      }[protocol];
+      const items = await transport[method]({
         key,
         baseUrl,
         model: request.model,
         prompt: input.prompt,
+        ...(image ? { image } : {}),
         size: input.size,
         n: input.n,
         signal: request.signal,
         ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
       });
-      return { kind: 'completed', value: { kind: 'openai', items } };
+      return {
+        kind: 'completed', value: { kind: 'openai', items },
+        artifacts: openAiImageArtifacts(items)
+      };
     },
 
     async download(request = {}) {
       const artifact = request.artifact || {};
-      if (artifact.kind !== 'remote-url' || !artifact.url) {
-        throw new ProviderContractError('download 需要 remote-url artifact', {
-          stage: 'download', category: 'protocol', acceptance: 'accepted'
-        });
-      }
       const targetPath = String(request.targetPath || '').trim();
       if (!targetPath) {
         throw new ProviderContractError('download 需要 targetPath', {
           stage: 'download', category: 'local_io', acceptance: 'accepted'
         });
       }
+      if (artifact.kind === 'inline-base64') return writeInlineArtifact(artifact, targetPath);
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要可物化的图片 artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
@@ -264,6 +336,7 @@ export function createOpenAiImagesProviderAdapter(provider, { transport = defaul
     protocol: 'openai-images',
     capabilities: ['image'],
     operations: operationsForOpenAiImages(provider, transport),
+    unsupportedPreparation: 'OpenAI Images 兼容路径未实现临时输入上传',
     unsupported: {
       poll: 'OpenAI Images 兼容路径在当前实现中同步返回结果',
       cancel: '同步图片响应没有可验证的远端取消任务'
@@ -271,9 +344,75 @@ export function createOpenAiImagesProviderAdapter(provider, { transport = defaul
   });
 }
 
+export function createOpenAiChatImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-chat-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport, 'openai-chat-images'),
+    unsupported: {
+      poll: 'Chat Completions 生图为同步协议，不提供远端任务轮询',
+      cancel: 'Chat Completions 生图不提供远端取消'
+    },
+    unsupportedPreparation: 'Chat Completions 生图未实现临时输入上传'
+  });
+}
+
+export function createOpenAiResponsesImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-responses-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport, 'openai-responses-images'),
+    unsupported: {
+      poll: 'Responses 生图当前只接同步结果，不提供后台任务轮询',
+      cancel: '同步 Responses 生图不提供远端取消'
+    },
+    unsupportedPreparation: 'Responses 生图未实现临时输入上传'
+  });
+}
+
+const PROTOCOL_FACTORIES = new Map([
+  ['dashscope', createDashScopeProviderAdapter],
+  ['openai-images', createOpenAiImagesProviderAdapter],
+  ['openai-chat-images', createOpenAiChatImagesProviderAdapter],
+  ['openai-responses-images', createOpenAiResponsesImagesProviderAdapter]
+]);
+
 export function createConfiguredProviderAdapter(provider, options = {}) {
-  const protocol = options.protocol || provider?.mediaProtocol || inferMediaProtocol(provider?.baseUrl);
-  if (protocol === 'dashscope') return createDashScopeProviderAdapter(provider, options);
-  if (protocol === 'openai-images') return createOpenAiImagesProviderAdapter(provider, options);
-  throw new TypeError('iris: 不支持的 Provider 协议：' + String(protocol));
+  const selection = options.protocol
+    ? selectMediaProtocol({ ...provider, mediaProtocol: options.protocol, protocolInferred: false })
+    : selectMediaProtocol(provider);
+  const factory = PROTOCOL_FACTORIES.get(selection.mediaProtocol);
+  if (!factory) throw unsupportedProtocolError(selection.mediaProtocol);
+  const adapter = factory(provider, options);
+  const operations = { ...adapter.operations };
+  for (const name of ['submit', 'poll']) {
+    if (!operations[name]) continue;
+    const run = operations[name];
+    operations[name] = async request => {
+      const modelId = request.model || options.modelId;
+      const report = error => reportModelRateLimit(provider, modelId, {
+        httpStatus: error.httpStatus ?? error.status, category: error.category,
+        code: error.code, providerCode: error.providerCode, message: error.safeMessage || error.message,
+        retryAfterMs: error.retryAfterMs,
+        source: options.allowRateLimited ? 'probe' : 'task'
+      }, options.onRateLimit, request.capability);
+      if (name === 'submit' && !options.allowRateLimited && modelRateLimit(provider, modelId)) {
+        const blocked = modelRateLimit(provider, modelId);
+        throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
+          stage: 'validate', category: 'rate_limit', acceptance: 'not_accepted'
+        });
+      }
+      try {
+        const result = await run(request);
+        if (result.error) report(result.error);
+        return result;
+      } catch (error) {
+        report(error);
+        throw error;
+      }
+    };
+  }
+  return Object.freeze({ ...adapter, operations: Object.freeze(operations) });
 }

package/lib/provider-catalog.js

@@ -0,0 +1,183 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CAPABILITIES } from './capability.js';
+import { modelPool, orderedModels, providerModels, parseModelRef, resolveModelRef, resolvePoolModel, selectionReasonForModel } from './models.js';
+import { dashscopeApiBase, selectMediaProtocol, providerForImageModel, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.js';
+import { modelRateLimit } from './provider-health.js';
+import { normalizeVisionInputLimits } from './vision-image-input.js';
+
+export class ProviderCatalogError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProviderCatalogError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new ProviderCatalogError(code, message);
+}
+
+/** Headless 边界只读取显式配置文件；不推断 DSH_HOME、HOME 或 cwd。 */
+export function loadProviderCatalog(configPath) {
+  const supplied = String(configPath || '').trim();
+  if (!supplied || !path.isAbsolute(supplied)) {
+    fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 必须是显式绝对路径');
+  }
+  let source;
+  try {
+    const stat = fs.lstatSync(supplied);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('not a regular file');
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+      fail('IRIS_PROVIDER_CONFIG_PERMISSIONS', 'provider-config 权限过宽；请限制为仅当前用户可读写');
+    }
+    source = fs.readFileSync(supplied, 'utf8');
+  } catch (error) {
+    if (error instanceof ProviderCatalogError) throw error;
+    fail('IRIS_PROVIDER_CONFIG_UNREADABLE', 'provider-config 不存在、不是普通文件或无法读取');
+  }
+  let parsed;
+  try { parsed = JSON.parse(source); }
+  catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 不是有效 JSON'); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+      || !Array.isArray(parsed.providers)
+      || (parsed.assignments !== undefined && (!parsed.assignments || typeof parsed.assignments !== 'object'
+        || Array.isArray(parsed.assignments)))) {
+    fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 结构无效');
+  }
+  return parsed;
+}
+
+const CANDIDATE_CAP_LABEL = Object.freeze({
+  [CAPABILITIES.IMAGE]: '图片', [CAPABILITIES.VIDEO]: '视频',
+  [CAPABILITIES.TTS]: '语音', [CAPABILITIES.TRANSCRIBE]: '转写', [CAPABILITIES.VISION]: '视觉'
+});
+
+/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则。 */
+function candidatesFromCatalog(catalog, requestedModelRef, capability) {
+  const label = CANDIDATE_CAP_LABEL[capability];
+  if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
+  const providers = catalog.providers.filter(isConfiguredProvider);
+  const pool = modelPool(providers).filter((item) => item.capabilities.includes(capability));
+  const requested = String(requestedModelRef || '').trim();
+  if (requested) {
+    const parsed = parseModelRef(requested);
+    if (!parsed && requested.includes('::')) fail('IRIS_PROVIDER_MODEL_INVALID', 'model_ref 格式无效');
+    const exact = resolvePoolModel(pool, requested, capability);
+    if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型不存在、未启用或没有${label}能力`);
+    const provider = providers.find((item) => item.id === exact.providerId);
+    if (exact.rateLimited) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
+      ? '指定模型正在限流冷却，请稍后使用或手动实测'
+      : '指定模型额度或预算耗尽，请手动实测成功后再使用');
+    return Object.freeze([Object.freeze({
+      provider, model: exact.id, modelRef: resolveModelRef(provider, capability, requested),
+      selectionReason: 'explicit'
+    })]);
+  }
+  const assignment = catalog.assignments?.[capability];
+  const ordered = orderedModels(pool, capability, assignment);
+  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `provider-config 中没有可用${label}模型`);
+  return Object.freeze(ordered.map((item) => Object.freeze({
+    provider: providers.find((provider) => provider.id === item.providerId),
+    model: item.id,
+    modelRef: item.ref,
+    selectionReason: selectionReasonForModel(pool, capability, assignment, item)
+  })));
+}
+
+export function imageCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE).map(route =>
+    Object.freeze({ ...route, provider: providerForImageModel(route.provider, route.model) })));
+}
+
+export function videoCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO);
+}
+
+export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS);
+}
+
+export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE);
+}
+
+export function visionCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VISION);
+}
+
+/** 只读配置投影；不构造 Adapter、不发现模型、不暴露端点或凭据。 */
+export function providerCatalogSnapshot(catalog) {
+  const safeLabel = (value) => value
+    ? redactProviderMessage(String(value).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
+  return {
+    schemaVersion: 1,
+    providers: catalog.providers.filter((provider) => provider && typeof provider === 'object').map((provider) => {
+      const models = providerModels(provider);
+      const selection = selectMediaProtocol(provider);
+      return {
+        id: safeLabel(provider.id), name: safeLabel(provider.name || provider.id),
+        enabled: provider.enabled !== false, configured: isConfiguredProvider(provider),
+        auth: provider.auth === 'none' ? 'none' : 'bearer',
+        mediaProtocol: safeLabel(selection.mediaProtocol), protocolInferred: selection.protocolInferred,
+        ...(provider.visionInput ? { visionInput: normalizeVisionInputLimits(provider.visionInput) } : {}),
+        capabilities: Object.values(CAPABILITIES).filter((capability) => models.some((model) => model.capabilities.includes(capability))),
+        modelCount: models.length
+      };
+    })
+  };
+}
+
+export function catalogCapabilitySnapshot(catalog) {
+  const pool = modelPool(catalog.providers.filter(isConfiguredProvider));
+  return {
+    schemaVersion: 1,
+    source: 'configuration',
+    capabilities: Object.values(CAPABILITIES).map((capability) => {
+      const candidates = orderedModels(pool, capability, catalog.assignments?.[capability]).map((model) => model.ref);
+      return { capability, candidates, ...(candidates.length ? {} : { gap: 'no_configured_model' }) };
+    })
+  };
+}
+
+/** 非敏感摘要把 Task 绑定到提交时实际使用的媒体端点与协议。 */
+export function providerTaskBinding(provider) {
+  const baseUrl = providerMediaBaseUrl(provider);
+  const protocol = selectMediaProtocol(provider).mediaProtocol;
+  let endpoint;
+  try {
+    const url = new URL(baseUrl);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('unsafe endpoint');
+    if (!['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) throw new Error('unknown protocol');
+    endpoint = protocol === 'dashscope' ? dashscopeApiBase(baseUrl) : url.href.replace(/\/+$/, '');
+  } catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'Provider 媒体端点或协议无效'); }
+  return 'sha256:' + crypto.createHash('sha256').update(JSON.stringify([1, protocol, endpoint])).digest('hex');
+}
+
+/** 恢复只使用 Task 已保存的 Provider/模型；忽略当前 assignment 与 failover 顺序。 */
+export function providerForTaskFromCatalog(catalog, task) {
+  const capability = CAPABILITIES[
+    task?.capability === 'video' ? 'VIDEO'
+      : task?.capability === 'image' ? 'IMAGE'
+      : task?.capability === 'tts' ? 'TTS'
+      : task?.capability === 'transcribe' ? 'TRANSCRIBE' : ''
+  ];
+  if (!capability) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 恢复解析只开放图片、视频、语音与转写 Task');
+  const label = { video: '视频', tts: '语音', transcribe: '转写' }[task.capability] || '图片';
+  const parsed = parseModelRef(task.modelRef);
+  if (!parsed || parsed.providerId !== task.providerId) fail('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task 的 Provider 与模型身份不一致');
+  const matches = catalog.providers.filter((item) => item && item.id === task.providerId);
+  if (matches.length > 1) fail('IRIS_PROVIDER_CONFIG_AMBIGUOUS', 'provider-config 存在重复 Provider ID');
+  const configured = matches[0];
+  if (!configured || configured.enabled === false || (configured.auth !== 'none' && (typeof configured.apiKey !== 'string' || !configured.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  const provider = task.capability === 'image' ? providerForImageModel(configured, parsed.modelId) : configured;
+  if (!task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISSING', '旧 Task 缺少提交端点绑定；仅支持只读查看，不猜测恢复配置');
+  if (providerTaskBinding(provider) !== task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISMATCH', 'Task 提交端点或协议已改变；拒绝向新端点观察原任务');
+  const model = modelPool([provider]).find((item) => item.providerId === parsed.providerId && item.id === parsed.modelId && item.capabilities.includes(capability));
+  if (!model) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `Task 原模型已移除或不再具备${label}能力`);
+  return provider;
+}