@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/lib/models.js

@@ -9,9 +9,10 @@
  *   ① provider 显式 `models` 数组（未来配置，可带 capabilities 覆盖）
  *   ② 旧模型字段迁移：imageModel→image-gen、videoModel→video-gen、ttsModel→tts、
  *      transcribeModel→transcribe、visionModel→vision
- *   ③ 裸 DashScope 账号：已知模型清单（wan 系列 / qwen-vl / qwen-tts）作为池
+ * 旧裸账号的已知目录仅由配置写入边界物化，不参与运行时回退。
  */
 import { CAPABILITIES } from './capability.js';
+import { isDashScopeBaseUrl, selectMediaProtocol } from './provider-protocol.js';
 
 /** 能力 → provider 上的模型字段（保持向后兼容的返回形状） */
 export const CAP_FIELD = {
@@ -62,8 +63,8 @@ const MODEL_CAP_RULES = [
   [/^gemini/i, [CAPABILITIES.VISION]] // Gemini 默认按视觉能力纳入（可被显式配置覆盖）
 ];
 
-/** 裸 DashScope 已知模型清单（无显式模型字段时作为池） */
-const DASHSCOPE_KNOWN = [
+/** 仅供配置写入时接回旧裸账号，不参与运行时选型。 */
+const KNOWN_MODELS_BY_PROTOCOL = { dashscope: [
   { id: 'wan2.2-t2i-flash', caps: [CAPABILITIES.IMAGE] },
   { id: 'wan2.2-t2v-flash', caps: [CAPABILITIES.VIDEO] },
   { id: 'wan2.2-s2v-flash', caps: [CAPABILITIES.VIDEO] },
@@ -72,7 +73,17 @@ const DASHSCOPE_KNOWN = [
   { id: 'qwen3-vl-235b-a22b-thinking', caps: [CAPABILITIES.VISION] },
   { id: 'qwen-tts-latest', caps: [CAPABILITIES.TTS] },
   { id: 'qwen-audio-3.0-asr-flash-filetrans', caps: [CAPABILITIES.TRANSCRIBE] }
-];
+] };
+
+export function migrateProviderModels(provider) {
+  if (Array.isArray(provider.models) || Object.values(CAP_FIELD).some((field) => provider[field])) return false;
+  const protocol = selectMediaProtocol(provider).mediaProtocol;
+  if (!isDashScopeBaseUrl(provider.baseUrl) || !Object.hasOwn(KNOWN_MODELS_BY_PROTOCOL, protocol)) return false;
+  provider.models = KNOWN_MODELS_BY_PROTOCOL[protocol].map((m) => ({
+    id: m.id, capabilities: [...m.caps], source: 'migration'
+  }));
+  return true;
+}
 
 /** 按模型名规则推断能力 */
 export function capabilitiesOfModel(modelName) {
@@ -83,6 +94,24 @@ export function capabilitiesOfModel(modelName) {
   return [];
 }
 
+/** 官方模型目录能力代码 → Iris 能力。未识别代码保守忽略。 */
+const DISCOVERY_CAPABILITIES = Object.freeze({
+  IG: CAPABILITIES.IMAGE, IMAGE: CAPABILITIES.IMAGE, 'IMAGE-GEN': CAPABILITIES.IMAGE,
+  VG: CAPABILITIES.VIDEO, VIDEO: CAPABILITIES.VIDEO, 'VIDEO-GEN': CAPABILITIES.VIDEO,
+  TTS: CAPABILITIES.TTS, ASR: CAPABILITIES.TRANSCRIBE,
+  TRANSCRIBE: CAPABILITIES.TRANSCRIBE, VU: CAPABILITIES.VISION, VISION: CAPABILITIES.VISION
+});
+
+/** 发现元数据优先，名称规则兜底；用户保存后的显式 capabilities 仍是最终覆盖。 */
+export function capabilitiesOfDiscoveredModel(model) {
+  const id = String(typeof model === 'string' ? model : model?.id || '').trim();
+  const declared = Array.isArray(model?.capabilities)
+    ? [...new Set(model.capabilities.map((value) => DISCOVERY_CAPABILITIES[String(value).toUpperCase()]).filter(Boolean))]
+    : [];
+  if (declared.length) return declared;
+  return capabilitiesOfModel(id);
+}
+
 /** 一个 provider 的模型池条目列表：[{ id, providerId, capabilities:[], verified?, source? }] */
 export function providerModels(p) {
   if (!p) return [];
@@ -93,10 +122,13 @@ export function providerModels(p) {
     out.push({ id: name, providerId: p.id, ref: modelRef(p.id, name), capabilities: [...caps], ...(extra || {}) });
   };
   // ① 显式 models 数组（带可选 capabilities 覆盖 + verified/source 透传）
-  if (Array.isArray(p.models) && p.models.length) {
+  // 该字段一旦存在（含空数组）即为权威声明：用户可明确标记「此供应商没有可用模型」，
+  // 不得再落入 ② 旧字段迁移或 ③ 裸账号已知池。空数组曾因 `.length` 判定被穿透，
+  // 导致用户声明无模型却仍被注入 7 个厂商默认模型（见审计 B-5）。
+  if (Array.isArray(p.models)) {
     for (const m of p.models) {
       const id = typeof m === 'string' ? m : m && m.id;
-      // 显式空数组也是权威覆盖：用户可明确标记“此模型无能力”。
+      // 元素级空能力数组同样是权威覆盖：用户可明确标记“此模型无能力”。
       const caps = Array.isArray(m && m.capabilities) ? m.capabilities : capabilitiesOfModel(id);
       const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source } : {};
       push(id, caps, extra);
@@ -107,14 +139,68 @@ export function providerModels(p) {
   for (const [cap, field] of Object.entries(CAP_FIELD)) {
     if (p[field]) push(p[field], [cap]);
   }
-  if (out.length) return out;
-  // ③ 裸 DashScope 账号 → 已知模型池
-  if (/dashscope/i.test(String(p.baseUrl || ''))) {
-    for (const m of DASHSCOPE_KNOWN) push(m.id, m.caps);
-  }
   return out;
 }
 
+/** 只解析用户配置中的模型；裸 ID 与复合引用共享能力校验。 */
+export function resolveModelRef(provider, capability, requested = '') {
+  const pool = providerModels(provider).filter((m) => m.capabilities.includes(capability));
+  const raw = String(requested || '').trim();
+  const selected = raw ? resolvePoolModel(pool, raw, capability)
+    : pool.find((m) => m.id === provider?.[CAP_FIELD[capability]]) || pool[0];
+  return selected?.ref || null;
+}
+
+/** 共享旧分配对象、裸名称和复合引用的解析，池顺序决定同名匹配。 */
+export function resolvePoolModel(pool, raw, capability) {
+  let providerId = '';
+  let modelId = '';
+  if (raw && typeof raw === 'object') {
+    providerId = String(raw.providerId || '');
+    modelId = String(raw.modelId || raw.id || '');
+  } else if (typeof raw === 'string') {
+    const parsed = parseModelRef(raw);
+    if (parsed) ({ providerId, modelId } = parsed);
+    else if (!raw.includes(MODEL_REF_SEP)) modelId = raw;
+  }
+  return pool.find((m) => m.id === modelId && (!providerId || m.providerId === providerId)
+    && m.capabilities.includes(capability)) || null;
+}
+
+/** DSH 与 CLI 共用的候选顺序：分配优先、按池顺序补齐并去重。 */
+export function orderedModels(pool, capability, assignments) {
+  const ordered = [];
+  const seen = new Set();
+  const add = (model) => {
+    if (model && model.capabilities.includes(capability) && !seen.has(model.ref)) {
+      seen.add(model.ref);
+      ordered.push(model);
+    }
+  };
+  for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
+    add(resolvePoolModel(pool, raw, capability));
+  }
+  for (const model of pool) add(model);
+  return ordered;
+}
+
+/**
+ * 返回候选在当前候选链构造时的配置来源。调用方显式 model_ref 由入口直接标为
+ * explicit；本函数只区分 assignment 与池序补齐，结果必须随 Attempt 写前落盘，
+ * 不能在事后用可变配置重算。
+ */
+export function selectionReasonForModel(pool, capability, assignments, modelOrRef) {
+  const selected = resolvePoolModel(pool,
+    modelOrRef && typeof modelOrRef === 'object' ? modelOrRef.ref : modelOrRef,
+    capability);
+  if (!selected) return null;
+  for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
+    const assigned = resolvePoolModel(pool, raw, capability);
+    if (assigned?.ref === selected.ref) return 'assignment';
+  }
+  return 'pool';
+}
+
 /** 全局模型池：合并所有 provider 的模型 */
 export function modelPool(providers) {
   const pool = [];

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,16 @@
  */
 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';
 
 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 };
@@ -82,6 +83,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: 'image/png' };
+    }
+    if (item && item.url) {
+      return { kind: 'remote-url', url: item.url, 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 +136,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 +163,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 +188,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 +217,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,11 +244,15 @@ 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 媒体协议未提供经过验证的远端取消实现'
     }
@@ -230,22 +281,26 @@ function operationsForOpenAiImages(provider, transport) {
         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 +319,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 +327,16 @@ export function createOpenAiImagesProviderAdapter(provider, { transport = defaul
   });
 }
 
+const PROTOCOL_FACTORIES = new Map([
+  ['dashscope', createDashScopeProviderAdapter],
+  ['openai-images', createOpenAiImagesProviderAdapter]
+]);
+
 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);
+  return factory(provider, options);
 }

package/lib/provider-catalog.js

@@ -0,0 +1,171 @@
+'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, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.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]: '转写'
+});
+
+/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则（image/video/tts/transcribe 同构）。 */
+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);
+    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 candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE);
+}
+
+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);
+}
+
+/** 只读配置投影；不构造 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,
+        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'].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 provider = matches[0];
+  if (!provider || provider.enabled === false || (provider.auth !== 'none' && (typeof provider.apiKey !== 'string' || !provider.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  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;
+}