@mokuyoaxis/dsh-iris 0.2.7 → 0.3.0-beta.1

package/lib/plugins.js

@@ -0,0 +1,59 @@
+// Experimental v0 public plugin author/embedding boundary. No automatic discovery or installation.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createPluginRegistry } from './plugin-registry.js';
+import { createApplicationRuntime } from './application-runtime.js';
+import { definePlugin, pluginFail, pluginFields } from './plugin-contract.js';
+import { createCoreCapabilityCatalog } from './core-capability-catalog.js';
+import { pinPluginWebAssets, registerPluginWebAssets } from './plugin-web-assets.js';
+import { createLocalReadApi } from './local-api.js';
+
+export { createCoreCapabilityCatalog } from './core-capability-catalog.js';
+
+export { definePlugin, PluginContractError, PLUGIN_CONTRACT_VERSION, PLUGIN_KINDS, PLUGIN_CORE_COMMANDS,
+  checkedPluginDependency, comparePluginVersions } from './plugin-contract.js';
+export { defineProviderAdapter, ProviderContractError, normalizeMediaEndpoint } from './provider-extensions.js';
+export { PROVIDER_FACTORY_CONTEXT_VERSION } from './provider-context.js';
+
+export function createCorePluginRegistry({ plugins = [], coreVersion } = {}) {
+  coreVersion ??= JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  return createPluginRegistry({ plugins, coreVersion });
+}
+
+/** Importing a module executes trusted code. Compatibility gates activate, not module evaluation. */
+export async function loadCorePluginRegistry({ entries = [], coreVersion } = {}) {
+  if (!Array.isArray(entries)) pluginFail('IRIS_PLUGIN_INVALID', '入口须为明确文件列表');
+  const plugins = [], assets = new Map();
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || !path.isAbsolute(entry) || !/\.m?js$/.test(entry) || !fs.statSync(entry).isFile()) pluginFail('IRIS_PLUGIN_INVALID', '插件入口须为 JS/MJS 文件绝对路径');
+    const file = fs.realpathSync(entry), definition = definePlugin((await import(pathToFileURL(file).href)).default);
+    for (const [id, files] of pinPluginWebAssets(definition, file)) assets.set(id, files);
+    plugins.push(definition);
+  }
+  const registry = await createCorePluginRegistry({ plugins, coreVersion });
+  registerPluginWebAssets(registry, assets);
+  return registry;
+}
+
+/** Trusted Core assembly. Grants are captured once; individual calls cannot enlarge them. */
+export function createCorePluginHost({ dataRoot, registry, allowedOperations = [] } = {}) {
+  const selection = createCoreCapabilityCatalog({ registry }).selectOperations(allowedOperations);
+  const grants = Object.freeze(selection.map(item => item.id)), application = createApplicationRuntime({ dataRoot });
+  return Object.freeze({
+    call: (id, input, { dependency, signal } = {}) => application.executePluginOperation(registry, id, input,
+      { allowedOperations: grants, dependency, signal }),
+    snapshot: () => application.snapshot(),
+    dispose: () => application.dispose()
+  });
+}
+
+/** Public, bounded Panel assembly. Media remains read-only; Provider editing is an explicit owner gate. */
+export function createCorePluginWorkbench(options) {
+  if (!pluginFields(options, ['dataRoot', 'registry', 'panelContributions', 'panelManifestPath', 'providerConfigPath', 'allowProviderManagement', 'allowedOperations', 'connectionStore', 'allowMcp', 'workbenchAuth'], ['dataRoot'])) {
+    pluginFail('IRIS_PLUGIN_WEB_INVALID', '工作台只接受明确的数据根、注册器、Panel 选择及供应商管理设置');
+  }
+  const { dataRoot, registry: pluginRegistry, panelContributions, panelManifestPath, providerConfigPath, allowProviderManagement = false, allowedOperations, connectionStore, allowMcp = false, workbenchAuth } = options;
+  return createLocalReadApi({ dataRoot, serveWorkbench: true, pluginRegistry, panelContributions, panelManifestPath, providerConfigPath, allowProviderManagement,
+    allowedOperations, connectionStore, allowConnectionManagement: connectionStore !== undefined, allowMcp, workbenchAuth });
+}

package/lib/provider-adapter.js

@@ -13,6 +13,7 @@ import {
   providerErrorRecord,
   resultFromThrown
 } from './provider-contract.js';
+import { checkedPluginDependency } from './plugin-contract.js';
 
 export const PROVIDER_ADAPTER_CONTRACT_VERSION = 0;
 
@@ -72,7 +73,7 @@ export function defineProviderAdapter(input) {
   if (!isPlainObject(input)) throw new TypeError('Provider Adapter 必须是对象');
   const allowed = new Set([
     'contractVersion', 'id', 'protocol', 'capabilities', 'operations', 'unsupported',
-    'prepareInput', 'unsupportedPreparation'
+    'prepareInput', 'unsupportedPreparation', 'pluginDependency'
   ]);
   for (const key of Object.keys(input)) {
     if (!allowed.has(key)) throw new Error('Provider Adapter 不允许顶层字段：' + key);
@@ -129,6 +130,8 @@ export function defineProviderAdapter(input) {
   }
   const unsupportedPreparation = input.prepareInput ? undefined
     : normalizedReason(input.unsupportedPreparation, '协议未实现临时输入上传');
+  const pluginDependency = input.pluginDependency === undefined ? undefined : checkedPluginDependency(input.pluginDependency);
+  if (pluginDependency && (pluginDependency.kind !== 'providers' || pluginDependency.contributionId !== protocol)) throw new TypeError('Provider Adapter 的插件依赖与协议不一致');
 
   return Object.freeze({
     contractVersion,
@@ -137,6 +140,7 @@ export function defineProviderAdapter(input) {
     capabilities: Object.freeze(capabilities),
     operations: Object.freeze(operations),
     unsupported: Object.freeze(unsupported),
+    ...(pluginDependency ? { pluginDependency } : {}),
     prepareInput: input.prepareInput,
     unsupportedPreparation
   });
@@ -192,7 +196,7 @@ export function providerAdapterSnapshot(adapter) {
 }
 
 /** 提交前的可选上传能力；不创建 Task，也不属于六个生命周期操作。 */
-export async function prepareProviderInput(adapter, input = {}) {
+export async function prepareProviderInput(adapter, input = {}, operationContext = {}) {
   if (typeof adapter?.prepareInput !== 'function') {
     const error = new ProviderContractError(adapter?.unsupportedPreparation || '协议未实现临时输入上传', {
       stage: 'upload', category: 'invalid_request', acceptance: 'not_accepted',
@@ -202,7 +206,7 @@ export async function prepareProviderInput(adapter, input = {}) {
     throw error;
   }
   try {
-    const value = await adapter.prepareInput(input);
+    const value = await adapter.prepareInput(input, operationContext);
     if (typeof value?.url !== 'string' || !value.url.trim()) {
       throw new ProviderContractError('Provider 输入准备必须返回非空 url', {
         stage: 'upload', category: 'protocol', acceptance: 'not_accepted'

package/lib/provider-adapters.js

@@ -10,10 +10,17 @@ 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 { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError, supportsImageEdit, dashscopeTtsInputIssue } from './provider-protocol.js';
+import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError, supportsImageEdit, dashscopeTtsInputIssue, BUILTIN_PROVIDER_PROTOCOLS } from './provider-protocol.js';
 import { modelRateLimit, reportModelRateLimit, isFreeQuotaExhausted, recordModelAvailability } from './provider-health.js';
 import { modelUnavailable, modelUnavailableReason, modelAvailabilityBinding } from './model-directory.js';
 import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
+import { createComfyUiProviderAdapter } from './comfyui-adapter.js';
+import { PROVIDER_RESPONSE_LIMITS } from './provider-response.js';
+import { resolveProviderCredential, assertDiscoveryCredentials } from './provider-credentials.js';
+import { assertProviderNetwork } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+import { createProviderTransport } from './provider-transport.js';
+import { hasProviderContext } from './provider-context.js';
 
 const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
 
@@ -26,7 +33,7 @@ function providerIdentity(provider) {
   return { id, key, baseUrl };
 }
 
-function mappedCategory(error, status) {
+function mappedCategory(error, status, stage) {
   const raw = String(error?.category || '').toLowerCase();
   if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
   if (error?.name === 'TimeoutError' || raw === 'timeout'
@@ -37,7 +44,10 @@ function mappedCategory(error, status) {
   if (status === 429 || raw === 'rate_limit') return 'rate_limit';
   if (raw === 'invalid_parameter' || raw === 'invalid_request') return 'invalid_request';
   if (raw === 'protocol') return 'protocol';
+  if (raw === 'local_io') return 'local_io';
   if (raw === 'network' || error instanceof TypeError) return 'network';
+  if (!status && ['download', 'persist'].includes(stage)
+      && ['ENOSPC', 'EDQUOT', 'EACCES', 'EPERM', 'ENOENT', 'EEXIST', 'EROFS', 'EIO'].includes(error?.code)) return 'local_io';
   if (raw === 'server' || status >= 500) return 'provider';
   if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
   return 'provider';
@@ -50,7 +60,7 @@ export function mapProviderAdapterError(error, context = {}) {
     ? statusValue
     : undefined;
   const stage = String(context.stage || error?.stage || 'submit');
-  const category = mappedCategory(error, httpStatus);
+  const category = mappedCategory(error, httpStatus, stage);
   let acceptance = context.acceptance || error?.acceptance;
   if (stage === 'validate' || stage === 'prepare' || stage === 'upload') {
     acceptance = 'not_accepted';
@@ -117,8 +127,16 @@ function openAiImageArtifacts(items) {
 }
 
 function writeInlineArtifact(artifact, targetPath) {
+  const maxBytes = String(artifact.mediaType || '').startsWith('image/') ? PROVIDER_RESPONSE_LIMITS.image
+    : artifact.mediaType === 'text/plain' ? PROVIDER_RESPONSE_LIMITS.transcript : PROVIDER_RESPONSE_LIMITS.audio;
+  if (typeof artifact.data === 'string' && artifact.data.length > Math.ceil(maxBytes / 3) * 4) {
+    throw new ProviderContractError('内嵌媒体超过允许的大小', { stage: 'download', category: 'protocol', acceptance: 'accepted' });
+  }
   const data = String(artifact?.data || '').trim();
   const body = Buffer.from(data, 'base64');
+  if (body.length > maxBytes) {
+    throw new ProviderContractError('内嵌媒体超过允许的大小', { stage: 'download', category: 'protocol', acceptance: 'accepted' });
+  }
   if (!data || body.length === 0 || body.toString('base64') !== data) {
     throw new ProviderContractError('inline-base64 媒体数据无效', {
       stage: 'download', category: 'protocol', acceptance: 'accepted'
@@ -262,6 +280,8 @@ function operationsForDashScope(provider, transport) {
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
+          maxBytes: { image: PROVIDER_RESPONSE_LIMITS.image, video: PROVIDER_RESPONSE_LIMITS.video,
+            tts: PROVIDER_RESPONSE_LIMITS.audio, transcribe: PROVIDER_RESPONSE_LIMITS.transcript }[request.capability] || PROVIDER_RESPONSE_LIMITS.video,
           ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
         })
       };
@@ -278,8 +298,8 @@ export function createDashScopeProviderAdapter(provider, { transport = defaultTr
     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 }) };
+    async prepareInput({ model, filePath, bytes, filename, signal, timeoutMs } = {}) {
+      return { url: await transport.uploadTempFile({ key, baseUrl, model, filePath, ...(bytes !== undefined ? { bytes, filename } : {}), signal, timeoutMs }) };
     },
     unsupported: {
       cancel: '当前 DashScope 媒体协议未提供经过验证的远端取消实现'
@@ -345,6 +365,7 @@ function operationsForOpenAiImages(provider, transport, protocol = 'openai-image
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
+          maxBytes: PROVIDER_RESPONSE_LIMITS.image,
           ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
         })
       };
@@ -418,38 +439,78 @@ export function createGeminiWebMusicProviderAdapter(provider, { transport = defa
   });
 }
 
-const PROTOCOL_FACTORIES = new Map([
-  ['gemini-web-music', createGeminiWebMusicProviderAdapter],
-  ['dashscope', createDashScopeProviderAdapter],
-  ['openai-images', createOpenAiImagesProviderAdapter],
-  ['openai-chat-images', createOpenAiChatImagesProviderAdapter],
-  ['openai-responses-images', createOpenAiResponsesImagesProviderAdapter]
-]);
+const PROTOCOL_FACTORIES = Object.freeze({
+  'gemini-web-music': createGeminiWebMusicProviderAdapter,
+  dashscope: createDashScopeProviderAdapter,
+  'openai-images': createOpenAiImagesProviderAdapter,
+  'openai-chat-images': createOpenAiChatImagesProviderAdapter,
+  'openai-responses-images': createOpenAiResponsesImagesProviderAdapter,
+  comfyui: createComfyUiProviderAdapter
+});
+
+export function builtinProviderExtension() {
+  return { contractVersion: 0, id: 'iris.builtin-media', version: '0.1.0',
+    protocols: BUILTIN_PROVIDER_PROTOCOLS.map(descriptor => ({ ...descriptor, createAdapter: PROTOCOL_FACTORIES[descriptor.id] })) };
+}
 
 export function createConfiguredProviderAdapter(provider, options = {}) {
+  const network = options.network === undefined ? undefined : assertProviderNetwork(options.network);
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || network.providerId !== provider.id)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此供应商需要匹配的显式网络上下文，不会静默使用默认出口');
+  }
+  if (network && (options.transport !== undefined || options.fetchPort !== undefined)) {
+    throw new TypeError('network 不能与显式 transport 或 fetchPort 同时配置');
+  }
+  const factoryOptions = network ? { ...options, transport: createProviderTransport(network.fetch), fetchPort: network.fetch } : options;
+  provider = resolveProviderCredential(provider);
   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 factory = Object.hasOwn(PROTOCOL_FACTORIES, selection.mediaProtocol) ? PROTOCOL_FACTORIES[selection.mediaProtocol] : null;
+  if (!options.registry && !factory) throw unsupportedProtocolError(selection.mediaProtocol);
+  const adapter = options.registry ? options.registry.createAdapter(selection.mediaProtocol, provider, factoryOptions) : factory(provider, factoryOptions);
   const operations = { ...adapter.operations };
+  const key = providerApiKey(provider);
+  const scrub = value => typeof value === 'string' && key ? value.split(key).join('[REDACTED]') : value;
+  if (operations.discover) {
+    const discover = operations.discover;
+    operations.discover = async (...args) => {
+      const result = await discover(...args);
+      assertDiscoveryCredentials(result, key);
+      return result;
+    };
+  }
+  operations.mapError = (error, context) => {
+    let mapped;
+    try { mapped = adapter.operations.mapError(error, context); } catch (failure) { mapped = failure; }
+    mapped ||= error;
+    const defaults = {};
+    for (const field of ['stage', 'category', 'acceptance', 'retryable']) {
+      if (mapped?.[field] === undefined) defaults[field] = context?.[field];
+    }
+    return providerErrorRecord(mapped, {
+      ...defaults,
+      safeMessage: scrub(String(mapped?.safeMessage || mapped?.message || mapped)),
+      providerCode: scrub(mapped?.providerCode ?? mapped?.code)
+    });
+  };
   for (const name of ['submit', 'poll']) {
     if (!operations[name]) continue;
     const run = operations[name];
-    operations[name] = async request => {
+    operations[name] = async (request, context) => {
       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,
+        code: scrub(error.code), providerCode: scrub(error.providerCode), message: scrub(error.safeMessage || error.message),
         retryAfterMs: error.retryAfterMs,
         source: options.allowRateLimited ? 'probe' : 'task'
       }, options.onRateLimit, request.capability);
       const availability = result => {
         if (name !== 'submit') return;
         const event = { ok: result.ok === true, category: result.category,
-          httpStatus: result.httpStatus ?? result.status, providerCode: result.providerCode || result.code,
-          note: result.safeMessage || result.message,
+          httpStatus: result.httpStatus ?? result.status, providerCode: scrub(result.providerCode || result.code),
+          note: scrub(result.safeMessage || result.message),
           stage: 'submit', source: options.allowRateLimited ? 'probe' : 'task',
           binding: modelAvailabilityBinding(provider, modelId, capability) };
         if (!recordModelAvailability(provider, modelId, request.capability, event)) return;
@@ -464,12 +525,12 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
       }
       if (name === 'submit' && !options.allowRateLimited && modelRateLimit(provider, modelId)) {
         const blocked = modelRateLimit(provider, modelId);
-        throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
+        if (!(options.deferCooling && blocked.until)) throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
           stage: 'validate', category: 'rate_limit', acceptance: 'not_accepted'
         });
       }
       try {
-        const result = await run(request);
+        const result = await run(request, context);
         if (result.error) report(result.error);
         availability(result.error || { ok: ['completed', 'accepted'].includes(result.kind) });
         return result;
@@ -480,5 +541,14 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
       }
     };
   }
-  return Object.freeze({ ...adapter, operations: Object.freeze(operations) });
+  if (network && !hasProviderContext(adapter)) {
+    for (const name of Object.keys(operations)) {
+      if (name === 'mapError') continue;
+      const operation = operations[name];
+      operations[name] = (...args) => network.run(() => operation(...args), { ...args[1], operation: name });
+    }
+  }
+  return Object.freeze({ ...adapter, ...(requirement ? { networkRequirement: requirement } : {}), operations: Object.freeze(operations),
+    ...(options.deferCooling ? { schedulingReadyAt: modelId => Date.parse(modelRateLimit(provider, modelId)?.until || '') || 0 } : {}),
+    ...(network && !hasProviderContext(adapter) && adapter.prepareInput ? { prepareInput: (...args) => network.run(() => adapter.prepareInput(...args), { ...args[1], operation: 'prepareInput' }) } : {}) });
 }

package/lib/provider-catalog.js

@@ -5,11 +5,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CAPABILITIES } from './capability.js';
 import { modelPool, functionModelPool, functionPolicy, orderedModels, providerModels, parseModelRef, resolveModelRef, resolvePoolModel, selectionReasonForModel } from './models.js';
-import { dashscopeApiBase, selectMediaProtocol, providerForImageModel, providerForMusicModel, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
+import { selectMediaProtocol, providerForImageModel, providerForMusicModel, providerMediaBaseUrl, isConfiguredProvider, providerProtocolDescriptor } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
 import { modelRateLimit } from './provider-health.js';
 import { normalizeVisionInputLimits } from './vision-image-input.js';
 import { modelDirectorySummary, modelUnavailableReason, validateModelDirectory } from './model-directory.js';
+import { checkedComfyWorkflow, comfyWorkflowDigest } from './comfyui-workflow.js';
+import { assertPluginDependencyMatches } from './plugin-contract.js';
+import { validateProviderCredential, assertProviderCredential, providerCredentialStatus, createProviderSecretScrubber } from './provider-credentials.js';
+import { decodeProviderConfig } from './provider-config-format.js';
 
 export class ProviderCatalogError extends Error {
   constructor(code, message) {
@@ -44,6 +48,7 @@ export function loadProviderCatalog(configPath) {
   let parsed;
   try { parsed = JSON.parse(source); }
   catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 不是有效 JSON'); }
+  parsed = decodeProviderConfig(parsed);
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
       || !Array.isArray(parsed.providers)
       || (parsed.assignments !== undefined && (!parsed.assignments || typeof parsed.assignments !== 'object'
@@ -51,7 +56,11 @@ export function loadProviderCatalog(configPath) {
     fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 结构无效');
   }
   for (const [capability, assignment] of Object.entries(parsed.assignments || {})) functionPolicy(assignment, capability);
-  for (const provider of parsed.providers) validateModelDirectory(provider.modelDirectory);
+  for (const provider of parsed.providers) {
+    validateProviderCredential(provider);
+    validateModelDirectory(provider.modelDirectory);
+    for (const model of provider.models || []) if (model?.comfyWorkflow !== undefined) checkedComfyWorkflow(model.comfyWorkflow);
+  }
   return parsed;
 }
 
@@ -62,11 +71,16 @@ const CANDIDATE_CAP_LABEL = Object.freeze({
 });
 
 /** 与 DSH 共用功能策略；CLI 不附加宿主资源。 */
-function candidatesFromCatalog(catalog, requestedModelRef, capability) {
+function candidatesFromCatalog(catalog, requestedModelRef, capability, registry, { deferCooling = false } = {}) {
   const label = CANDIDATE_CAP_LABEL[capability];
   if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
+  const requestedProvider = parseModelRef(String(requestedModelRef || '').trim())?.providerId;
+  if (requestedProvider) {
+    const provider = catalog.providers.find(item => item.id === requestedProvider && item.enabled !== false);
+    if (provider) assertProviderCredential(provider);
+  }
   const providers = catalog.providers.filter(isConfiguredProvider);
-  const configuredPool = functionModelPool(providers, capability, catalog.assignments?.[capability]);
+  const configuredPool = functionModelPool(providers, capability, catalog.assignments?.[capability], { registry });
   const pool = orderedModels(configuredPool, capability, catalog.assignments?.[capability], { includeRateLimited: true, includeUnavailable: true });
   const requested = String(requestedModelRef || '').trim();
   if (requested) {
@@ -76,7 +90,7 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
     if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型未分配给${label}功能、未启用或没有所需能力`);
     const provider = providers.find((item) => item.id === exact.providerId);
     if (exact.unavailableCapabilities?.includes(capability)) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', modelUnavailableReason());
-    if (exact.rateLimited) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
+    if (exact.rateLimited && !(deferCooling && modelRateLimit(provider, exact.id)?.until)) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
       ? '指定模型正在限流冷却，请稍后使用或手动实测'
       : '指定模型额度或预算耗尽，请手动实测成功后再使用');
     return Object.freeze([Object.freeze({
@@ -85,8 +99,14 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
     })]);
   }
   const assignment = catalog.assignments?.[capability];
-  const ordered = pool.filter(model => !model.rateLimited && !model.unavailableCapabilities?.includes(capability));
-  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `请检查${label}功能的启用方式、已确认模型、连接和协议；当前没有可用候选`);
+  const ordered = pool.filter(model => (!model.rateLimited || deferCooling && modelRateLimit(providers.find(provider => provider.id === model.providerId), model.id)?.until)
+    && !model.unavailableCapabilities?.includes(capability));
+  if (!ordered.length) {
+    const missing = catalog.providers.find(provider => provider.enabled !== false && provider.auth !== 'none' && provider.apiKeyEnv
+      && providerCredentialStatus(provider) !== 'ready' && providerModels(provider).some(model => model.capabilities.includes(capability)));
+    if (missing) assertProviderCredential(missing);
+    fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `请检查${label}功能的启用方式、已确认模型、连接和协议；当前没有可用候选`);
+  }
   return Object.freeze(ordered.map((item) => Object.freeze({
     provider: providers.find((provider) => provider.id === item.providerId),
     model: item.id,
@@ -95,37 +115,38 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
   })));
 }
 
-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 imageCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE, registry, options).map(route =>
+    Object.freeze({ ...route, provider: providerForImageModel(route.provider, route.model, registry) })));
 }
 
-export function videoCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO);
+export function videoCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO, registry, options);
 }
 
-export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS);
+export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS, registry, options);
 }
 
-export function musicCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.MUSIC).map(route =>
-    Object.freeze({ ...route, provider: providerForMusicModel(route.provider, route.model) })));
+export function musicCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.MUSIC, registry).map(route =>
+    Object.freeze({ ...route, provider: providerForMusicModel(route.provider, route.model, registry) })));
 }
 
-export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE);
+export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE, registry, options);
 }
 
-export function visionCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VISION);
+export function visionCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VISION, registry);
 }
 
 /** 只读配置投影；不构造 Adapter、不发现模型、不暴露端点或凭据。 */
 export function providerCatalogSnapshot(catalog) {
+  const scrub = createProviderSecretScrubber(catalog.providers);
   const safeLabel = (value) => value
-    ? redactProviderMessage(String(value).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
-  return {
+    ? redactProviderMessage(String(scrub(value)).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
+  return scrub({
     schemaVersion: 1,
     providers: catalog.providers.filter((provider) => provider && typeof provider === 'object').map((provider) => {
       const models = providerModels(provider);
@@ -140,16 +161,16 @@ export function providerCatalogSnapshot(catalog) {
         modelCount: models.length, directory: modelDirectorySummary(provider)
       };
     })
-  };
+  });
 }
 
-export function catalogCapabilitySnapshot(catalog) {
+export function catalogCapabilitySnapshot(catalog, registry) {
   return {
     schemaVersion: 1,
     source: 'configuration',
     capabilities: Object.values(CAPABILITIES).map((capability) => {
       const policy = functionPolicy(catalog.assignments?.[capability], capability);
-      const pool = functionModelPool(catalog.providers.filter(isConfiguredProvider), capability, catalog.assignments?.[capability]);
+      const pool = functionModelPool(catalog.providers.filter(isConfiguredProvider), capability, catalog.assignments?.[capability], { registry });
       const candidates = orderedModels(pool, capability, catalog.assignments?.[capability]).map((model) => model.ref);
       return { capability, mode: policy.mode, candidates, ...(candidates.length ? {} : { gap: 'no_configured_model' }) };
     })
@@ -157,21 +178,26 @@ export function catalogCapabilitySnapshot(catalog) {
 }
 
 /** 非敏感摘要把 Task 绑定到提交时实际使用的媒体端点与协议。 */
-export function providerTaskBinding(provider) {
+export function providerTaskBinding(provider, registry) {
   const baseUrl = providerMediaBaseUrl(provider);
   const protocol = selectMediaProtocol(provider).mediaProtocol;
-  let endpoint;
+  let endpoint, descriptor;
   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', 'gemini-web-music'].includes(protocol)) throw new Error('unknown protocol');
-    endpoint = protocol === 'dashscope' ? dashscopeApiBase(baseUrl) : url.href.replace(/\/+$/, '');
+    descriptor = providerProtocolDescriptor(protocol, registry);
+    if (!descriptor) throw new Error('unknown protocol');
+    endpoint = descriptor.normalizeEndpoint(baseUrl);
+    if (typeof endpoint !== 'string' || !endpoint) throw new Error('invalid normalized endpoint');
   } catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'Provider 媒体端点或协议无效'); }
-  return 'sha256:' + crypto.createHash('sha256').update(JSON.stringify([1, protocol, endpoint])).digest('hex');
+  const identity = protocol === 'comfyui' ? [2, protocol, endpoint, comfyWorkflowDigest(provider.comfyWorkflow)] : [1, protocol, endpoint];
+  // Only the new unified plugin contract opts in. Legacy protocols retain their exact historical binding.
+  if (descriptor.dependency) identity.push(descriptor.dependency);
+  return 'sha256:' + crypto.createHash('sha256').update(JSON.stringify(identity)).digest('hex');
 }
 
 /** 恢复只使用 Task 已保存的 Provider/模型；忽略当前 assignment 与 failover 顺序。 */
-export function providerForTaskFromCatalog(catalog, task) {
+export function providerForTaskFromCatalog(catalog, task, registry) {
   const capability = CAPABILITIES[
     task?.capability === 'video' ? 'VIDEO'
       : task?.capability === 'image' ? 'IMAGE'
@@ -186,11 +212,13 @@ export function providerForTaskFromCatalog(catalog, task) {
   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)
-    : task.capability === 'music' ? providerForMusicModel(configured, parsed.modelId) : configured;
+  if (configured && configured.enabled !== false) assertProviderCredential(configured);
+  if (!configured || configured.enabled === false || (configured.auth !== 'none' && providerCredentialStatus(configured) !== 'ready')) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  const provider = task.capability === 'image' ? providerForImageModel(configured, parsed.modelId, registry)
+    : task.capability === 'music' ? providerForMusicModel(configured, parsed.modelId, registry) : configured;
+  assertPluginDependencyMatches(task.pluginDependency, providerProtocolDescriptor(selectMediaProtocol(provider).mediaProtocol, registry)?.dependency);
   if (!task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISSING', '旧 Task 缺少提交端点绑定；仅支持只读查看，不猜测恢复配置');
-  if (providerTaskBinding(provider) !== task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISMATCH', 'Task 提交端点或协议已改变；拒绝向新端点观察原任务');
+  if (providerTaskBinding(provider, registry) !== 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;

package/lib/provider-config-format.js

@@ -0,0 +1,51 @@
+// Network-enabled catalogs use an outer envelope which older loaders reject.
+import { CATALOG_NETWORK, checkedNetworkRequirement, sameNetworkRequirement } from './network-policy.js';
+
+const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_PROVIDER_CONFIG_INVALID' }); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function markedCatalog(catalog, requirement) {
+  if (!object(catalog) || !Array.isArray(catalog.providers) || catalog.providers.some(provider => !object(provider))) {
+    fail('Provider 配置内容无效');
+  }
+  const ids = new Set();
+  for (const provider of catalog.providers) {
+    if (typeof provider.id !== 'string' || !provider.id.trim() || provider.id.length > 256 || /[\x00-\x1f\x7f]/.test(provider.id) || ids.has(provider.id)) fail('网络目录需要明确、唯一且不含控制字符的供应商身份');
+    ids.add(provider.id);
+  }
+  const identity = Object.freeze(checkedNetworkRequirement(requirement));
+  return { ...catalog, [CATALOG_NETWORK]: identity,
+    providers: catalog.providers.map(provider => ({ ...provider, [CATALOG_NETWORK]: identity })) };
+}
+
+export function decodeProviderConfig(parsed) {
+  if (object(parsed) && Object.hasOwn(parsed, 'providers') && Object.hasOwn(parsed, 'networkRequirement')) fail('网络目录不能与旧根 providers 字段混用，拒绝忽略网络要求');
+  if (!object(parsed) || Object.hasOwn(parsed, 'providers')) return parsed;
+  if (parsed.schemaVersion !== 1 || Object.keys(parsed).length !== 3
+      || !Object.hasOwn(parsed, 'networkRequirement') || !Object.hasOwn(parsed, 'catalog')) {
+    fail('Provider 网络配置包装版本或字段无效；请使用兼容版本，原文件不会自动迁移');
+  }
+  return markedCatalog(parsed.catalog, parsed.networkRequirement);
+}
+
+export function encodeProviderConfig(catalog) {
+  const requirement = catalog?.[CATALOG_NETWORK];
+  if (requirement === undefined) {
+    if (catalog?.providers?.some(provider => provider?.[CATALOG_NETWORK] !== undefined)) fail('Provider 网络配置身份丢失，拒绝写回旧格式');
+    return catalog;
+  }
+  const checked = checkedNetworkRequirement(requirement);
+  for (const provider of catalog.providers) {
+    const identity = provider?.[CATALOG_NETWORK];
+    if (identity !== undefined && !sameNetworkRequirement(checked, identity)) fail('Provider 与目录的网络配置身份不一致');
+  }
+  const { [CATALOG_NETWORK]: _identity, ...contents } = catalog;
+  return { schemaVersion: 1, networkRequirement: checked, catalog: contents };
+}
+
+/** Return a new marked runtime catalog; callers explicitly write a new file. */
+export function wrapProviderCatalog(catalog, requirement) {
+  const original = encodeProviderConfig(catalog);
+  const contents = catalog?.[CATALOG_NETWORK] === undefined ? original : original.catalog;
+  return markedCatalog(JSON.parse(JSON.stringify(contents)), requirement);
+}