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

package/lib/provider-health.js

@@ -3,7 +3,7 @@ import { isKnownCapability } from './capability.js';
 import { isModelNotFound, modelAvailabilityBinding, modelUnavailable } from './model-directory.js';
 
 const HEALTH_SENSITIVE_FIELDS = new Set([
-  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'mediaProtocol',
+  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'apiKeyEnv', 'mediaProtocol',
   'imageModel', 'videoModel', 'ttsModel', 'transcribeModel', 'visionModel'
 ]);
 
@@ -21,8 +21,15 @@ export function recordModelAvailability(provider, modelId, capability, result) {
   if (!modelId || !isKnownCapability(cap)) return false;
   let observation = provider.health?.observations?.find(item => item.modelId === modelId && item.capability === cap);
   const blocked = isModelNotFound(result);
+  // A real accepted/completed submission is evidence for this exact connection; directory reads never enter here.
+  if (result.ok === true && result.stage === 'submit') {
+    provider.health ||= { version: 1, revision: 0, observations: [] };
+    provider.health.observations ||= [];
+    if (!observation) { observation = { modelId, capability: cap }; provider.health.observations.push(observation); }
+    observation.lastSuccess = { at: result.at || new Date().toISOString(), source: result.source === 'probe' ? 'probe' : 'task', category: 'success' };
+  }
   if (!blocked && !(result.ok === true && (result.source === 'probe' || result.stage === 'submit')
-      && (observation?.availability?.state === 'blocked' || modelUnavailable(provider, modelId, cap)))) return false;
+      && (observation?.availability?.state === 'blocked' || modelUnavailable(provider, modelId, cap)))) return result.ok === true && result.stage === 'submit';
   provider.health ||= { version: 1, revision: 0, observations: [] };
   provider.health.observations ||= [];
   observation ||= provider.health.observations.find(item => item.modelId === modelId && item.capability === cap);
@@ -44,14 +51,18 @@ export const PROVIDER_HEALTH_STATES = Object.freeze([
 
 const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
 export const MODEL_RATE_LIMIT_COOLDOWN_MS = 60000;
+// Bound supplier hints to Node's supported timer range, including their persisted ISO deadline.
+export const MAX_MODEL_RATE_LIMIT_COOLDOWN_MS = 2_147_483_647;
+const MAX_DATE_MS = 8_640_000_000_000_000;
+const boundedCooldown = delay => Math.min(MAX_MODEL_RATE_LIMIT_COOLDOWN_MS, Math.max(1000, delay));
 
 export function retryAfterDelay(value, now = Date.now()) {
   const raw = String(value ?? '').trim();
   if (!raw) return MODEL_RATE_LIMIT_COOLDOWN_MS;
   const seconds = Number(raw);
-  if (Number.isFinite(seconds) && seconds >= 0) return Math.max(1000, seconds * 1000);
+  if (Number.isFinite(seconds) && seconds >= 0) return boundedCooldown(seconds * 1000);
   const at = Date.parse(raw);
-  return Number.isFinite(at) && at > now ? at - now : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  return Number.isFinite(at) && at > now ? boundedCooldown(at - now) : MODEL_RATE_LIMIT_COOLDOWN_MS;
 }
 
 /** 百炼“免费额度用完即停”返回 403，不应误归类为 Key 无效。 */
@@ -87,12 +98,13 @@ export function recordModelRateLimit(provider, modelId, result) {
   provider.health.rateLimits ||= [];
   const at = Date.parse(result.at || '');
   const timestamp = Number.isFinite(at) ? at : Date.now();
-  const delay = Number.isFinite(result.retryAfterMs) ? result.retryAfterMs : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  const delay = Number.isFinite(result.retryAfterMs) && result.retryAfterMs >= 0
+    ? boundedCooldown(result.retryAfterMs) : MODEL_RATE_LIMIT_COOLDOWN_MS;
   provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
   provider.health.rateLimits.push({ modelId,
     at: new Date(timestamp).toISOString(),
     source: result.source === 'probe' ? 'probe' : 'task', category, httpStatus: status,
-    ...(reason ? { reason } : { until: result.until || new Date(timestamp + Math.max(1000, delay)).toISOString() }) });
+    ...(reason ? { reason } : { until: result.until || new Date(Math.min(MAX_DATE_MS, timestamp + delay)).toISOString() }) });
   return true;
 }
 

package/lib/provider-monitor.js

@@ -0,0 +1,81 @@
+// Optional, service-owned, read-only connection checks. Never a media probe or durable health assertion.
+import { loadProviderCatalog } from './provider-catalog.js';
+import { executeConfigCommand } from './provider-config-service.js';
+import { modelDirectoryBinding } from './model-directory.js';
+import { selectMediaProtocol, isConfiguredProvider } from './provider-protocol.js';
+import { assertProviderCredential } from './provider-credentials.js';
+
+const AUTOMATIC = new Set(['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music', 'comfyui']);
+const errorCode = error => /^IRIS_NETWORK_/.test(error.code || '') || ['IRIS_CONFIG_CHANGED', 'IRIS_CONFIG_BUSY', 'IRIS_PROVIDER_OPERATION_UNSUPPORTED'].includes(error.code) ? error.code
+  : ['authentication', 'permission', 'network', 'timeout', 'protocol', 'rate_limit', 'provider', 'aborted'].includes(error.category) ? error.category : 'connection_failed';
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+export function createProviderMonitor({ configPath, registry, resolveProviderNetwork, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const records = new Map(), pending = new Set(); let closed = false;
+  const catalog = () => { if (closed) fail('IRIS_PROVIDER_MONITOR_CLOSED', '连接检查已关闭'); return loadProviderCatalog(configPath); };
+  function record(providerId, provider = catalog().providers.find(item => item.id === providerId)) {
+    if (!provider) fail('IRIS_CONFIG_INPUT_INVALID', '供应商不存在');
+    let item = records.get(providerId);
+    if (item && item.binding !== modelDirectoryBinding(provider)) { stop(item); records.delete(providerId); item = null; }
+    if (!item) { item = { providerId, binding: modelDirectoryBinding(provider), enabled: false, intervalSeconds: 300, last: null, epoch: 0 }; records.set(providerId, item); }
+    if (!isConfiguredProvider(provider)) stop(item);
+    return { provider, item };
+  }
+  function stop(item) { item.epoch++; clearTimer(item.timer); item.enabled = false; item.controller?.abort(); }
+  function snapshot() {
+    const providers = catalog().providers.map(provider => {
+      const { item } = record(provider.id, provider);
+      return { providerId: provider.id, automaticSupported: AUTOMATIC.has(selectMediaProtocol(provider).mediaProtocol),
+        enabled: item.enabled, intervalSeconds: item.intervalSeconds, checking: Boolean(item.pending), last: item.last };
+    });
+    for (const [id, item] of records) if (!providers.some(provider => provider.providerId === id)) { stop(item); records.delete(id); }
+    return providers;
+  }
+  async function check(providerId, expectedRevision, { signal } = {}) {
+    const { provider, item } = record(providerId);
+    if (provider.enabled !== false) assertProviderCredential(provider);
+    if (!isConfiguredProvider(provider)) fail('IRIS_CONFIG_INPUT_INVALID', '请先保存并启用供应商连接');
+    if (item.pending) fail('IRIS_API_BUSY', '此供应商正在检查，请等待结果');
+    const controller = item.controller = new AbortController();
+    const started = Date.now();
+    const job = (async () => {
+      try {
+        const result = await executeConfigCommand(configPath, 'settings.discover', { expectedRevision, providerId }, { registry, resolveProviderNetwork,
+          signal: AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]) });
+        item.last = { ok: true, at: new Date().toISOString(), elapsedMs: Date.now() - started, modelCount: result.models.length };
+      } catch (error) {
+        if (error.code === 'IRIS_CONFIG_CHANGED') throw error;
+        item.last = { ok: false, at: new Date().toISOString(), elapsedMs: Date.now() - started,
+          code: controller.signal.aborted || signal?.aborted ? 'check_unconfirmed' : errorCode(error),
+          ...(Number.isInteger(error.httpStatus) ? { httpStatus: error.httpStatus } : {}) };
+      }
+      return { contractVersion: 0, providerId, ...item.last };
+    })();
+    item.pending = job;
+    pending.add(job);
+    try { return await job; } finally { pending.delete(job); item.pending = null; item.controller = null; }
+  }
+  function schedule(item) {
+    const epoch = item.epoch;
+    item.timer = setTimer(async () => {
+      if (!item.enabled || closed || epoch !== item.epoch) return;
+      try {
+        const view = await executeConfigCommand(configPath, 'settings.show', {}, { registry });
+        const { provider, item: current } = record(item.providerId);
+        if (current !== item || !item.enabled || !isConfiguredProvider(provider)) return;
+        if (!item.pending) await check(item.providerId, view.revision);
+      } catch (error) { item.last = { ok: false, at: new Date().toISOString(), code: errorCode(error) }; }
+      finally { if (item.enabled && !closed && epoch === item.epoch) schedule(item); }
+    }, item.intervalSeconds * 1000);
+    item.timer?.unref?.();
+  }
+  function configure({ providerId, enabled, intervalSeconds }) {
+    if (typeof enabled !== 'boolean' || ![60, 300, 900].includes(intervalSeconds)) fail('IRIS_CONFIG_INPUT_INVALID', '保活需选择开关和60/300/900秒间隔');
+    const { provider, item } = record(providerId);
+    if (enabled && (!isConfiguredProvider(provider) || !AUTOMATIC.has(selectMediaProtocol(provider).mediaProtocol))) fail('IRIS_CONFIG_INPUT_INVALID', '此连接没有已支持的自动轻量检查');
+    stop(item); item.intervalSeconds = intervalSeconds; item.enabled = enabled;
+    if (enabled) schedule(item);
+    return { contractVersion: 0, monitors: snapshot(), persistence: 'service-session' };
+  }
+  async function dispose() { closed = true; for (const item of records.values()) stop(item); await Promise.allSettled([...pending]); records.clear(); }
+  return Object.freeze({ snapshot, check, configure, dispose });
+}

package/lib/provider-network.js

@@ -0,0 +1,52 @@
+// Internal composition port. No proxy configuration, global mutation or automatic retry.
+export function inheritedProviderFetch(...args) { return globalThis.fetch(...args); }
+
+function closed() {
+  return Object.assign(new Error('Provider 网络客户端正在关闭或已关闭'), {
+    code: 'IRIS_PROVIDER_NETWORK_CLOSED', stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+  });
+}
+
+export function assertProviderNetwork(network) {
+  if (!network || typeof network.fetch !== 'function' || typeof network.run !== 'function') {
+    throw new TypeError('network 需要实例级 fetch 和完整操作 run');
+  }
+  return network;
+}
+
+/** The owner drains Core/registry operations before disposing this client. */
+export function createProviderNetworkClient({ fetchPort, close } = {}) {
+  if (fetchPort !== undefined && typeof fetchPort !== 'function') throw new TypeError('fetchPort 必须是函数');
+  if (close !== undefined && typeof close !== 'function') throw new TypeError('close 必须是函数');
+  const active = new Set();
+  let state = 'open', disposal, cleanupFailed = false;
+  const snapshot = () => Object.freeze({ state, activeOperations: active.size, cleanupFailed });
+
+  // Used inside run: closing must still permit later pages, uploads and body reads.
+  const fetch = (...args) => {
+    if (state === 'closed') return Promise.reject(closed());
+    return (fetchPort || inheritedProviderFetch)(...args);
+  };
+  function run(action) {
+    if (typeof action !== 'function') throw new TypeError('网络操作必须是函数');
+    if (state !== 'open') return Promise.reject(closed());
+    const operation = Promise.resolve().then(() => action(fetch));
+    active.add(operation);
+    void operation.then(() => active.delete(operation), () => active.delete(operation));
+    return operation;
+  }
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        try { await close?.(); }
+        catch (error) { cleanupFailed = true; throw error; }
+        finally { state = 'closed'; }
+        return snapshot();
+      })();
+    }
+    return disposal;
+  }
+  return Object.freeze({ fetch, run, dispose, snapshot });
+}

package/lib/provider-protocol.js

@@ -1,5 +1,7 @@
 'use strict';
 /** 供应商媒体协议判断与 DashScope 凭据边界。 */
+import { comfyWorkflowDigest } from './comfyui-workflow.js';
+import { providerCredentialValue, providerCredentialStatus } from './provider-credentials.js';
 
 const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
 const REGIONAL_HOST = /^cn-hongkong\.dashscope\.aliyuncs\.com$/i;
@@ -46,44 +48,54 @@ export function selectMediaProtocol(provider) {
 }
 
 /** 模型图片协议只覆盖生图；auto 沿用账号级默认，不另外猜测端点。 */
-export function normalizeImageProtocol(value) {
+export function normalizeImageProtocol(value, registry) {
   const protocol = typeof value === 'string' ? value.trim() : '';
-  if (!['auto', 'dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) {
-    throw Object.assign(new TypeError('imageProtocol 必须是 auto、dashscope、openai-images、openai-chat-images 或 openai-responses-images'), {
+  if (protocol !== 'auto' && !providerProtocolDescriptor(protocol, registry)?.capabilities.includes('image-gen')) {
+    throw Object.assign(new TypeError('imageProtocol 必须是 auto 或当前实例已注册的图片协议'), {
       code: 'IRIS_PROVIDER_IMAGE_PROTOCOL_INVALID'
     });
   }
   return protocol;
 }
 
-export function selectImageProtocol(provider, modelId) {
+export function selectImageProtocol(provider, modelId, registry) {
   const entry = Array.isArray(provider?.models) ? provider.models.find(model => model?.id?.trim() === modelId) : null;
   if (entry?.imageProtocol === undefined) return selectMediaProtocol(provider);
-  const protocol = normalizeImageProtocol(entry.imageProtocol);
+  const protocol = normalizeImageProtocol(entry.imageProtocol, registry);
   return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
 }
 
+/** Binding/health reads preserve an explicitly saved protocol even if its extension is absent. */
+export function providerForModelBinding(provider, modelId, capability) {
+  const entry = provider.models?.find(model => model?.id?.trim() === modelId);
+  const value = capability === 'music-gen' ? entry?.musicProtocol : entry?.imageProtocol;
+  const protocol = typeof value === 'string' ? value.trim() : '';
+  return { ...provider, ...(protocol && protocol !== 'auto'
+    ? { mediaProtocol: protocol, protocolInferred: false } : selectMediaProtocol(provider)) };
+}
+
 /** 已接入的带图编辑协议；这里只判断传输，不授予模型 image-gen 能力。 */
-export function supportsImageEdit(protocol, modelId) {
-  return protocol === 'openai-chat-images' || (protocol === 'dashscope'
-    && /^qwen-image-(?:edit(?:-(?:max|plus))?|2\.0(?:-pro)?)(?:-\d{4}-\d{2}-\d{2})?$/.test(String(modelId || '')));
+export function supportsImageEdit(protocol, modelId, registry) {
+  return providerProtocolDescriptor(protocol, registry)?.supportsImageEdit?.(modelId) === true;
 }
 
 /** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
-export function providerForImageModel(provider, modelId) {
-  return { ...provider, ...selectImageProtocol(provider, modelId) };
+export function providerForImageModel(provider, modelId, registry) {
+  const selection = selectImageProtocol(provider, modelId, registry);
+  return { ...provider, ...selection, ...(selection.mediaProtocol === 'comfyui'
+    ? { comfyWorkflow: provider.models?.find(model => model?.id === modelId)?.comfyWorkflow } : {}) };
 }
 
-export function normalizeMusicProtocol(value) {
-  if (value !== 'gemini-web-music') throw Object.assign(new TypeError('musicProtocol 必须是 gemini-web-music'), {
+export function normalizeMusicProtocol(value, registry) {
+  if (!providerProtocolDescriptor(value, registry)?.capabilities.includes('music-gen')) throw Object.assign(new TypeError('musicProtocol 必须是已注册的音乐协议'), {
     code: 'IRIS_PROVIDER_MUSIC_PROTOCOL_INVALID'
   });
   return value;
 }
 
-export function providerForMusicModel(provider, modelId) {
+export function providerForMusicModel(provider, modelId, registry) {
   const entry = provider.models?.find(model => model?.id?.trim() === modelId);
-  return { ...provider, mediaProtocol: normalizeMusicProtocol(entry?.musicProtocol), protocolInferred: false };
+  return { ...provider, mediaProtocol: normalizeMusicProtocol(entry?.musicProtocol, registry), protocolInferred: false };
 }
 
 export function unsupportedProtocolError(protocol, kind = 'media') {
@@ -103,7 +115,7 @@ export function dashscopeApiBase(baseUrl) {
 
 /** 无认证模式不发送保留的旧凭据；未声明模式保持 bearer 兼容。 */
 export function providerApiKey(provider) {
-  return provider?.auth === 'none' ? '' : String(provider?.apiKey || '');
+  return provider?.auth === 'none' ? '' : providerCredentialValue(provider);
 }
 
 /** 配置管理与 headless 候选链共用可用性门，未声明 enabled 时默认启用。 */
@@ -111,7 +123,7 @@ export function isConfiguredProvider(provider) {
   return Boolean(provider && provider.enabled !== false
     && typeof provider.id === 'string' && provider.id.trim()
     && providerMediaBaseUrl(provider)
-    && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
+    && (provider.auth === 'none' || providerCredentialStatus(provider) === 'ready'));
 }
 
 /** 已知需要其他接口的语音系列；自定义模型仍以明确配置和实测为准。 */
@@ -135,13 +147,52 @@ export function dashscopeTtsInputIssue(modelId, voice) {
 }
 
 /** Protocol support is independent from model capability declarations and health. */
-export function supportsModelCapability(provider, modelId, capability, { checkEndpoint = true } = {}) {
+export function supportsModelCapability(provider, modelId, capability, { checkEndpoint = true, registry } = {}) {
   if (capability === 'vision') return true;
-  if (capability === 'music-gen') return provider?.models?.some(model => model?.id === modelId && model.musicProtocol === 'gemini-web-music') === true;
-  const protocol = capability === 'image-gen' ? selectImageProtocol(provider, modelId).mediaProtocol : selectMediaProtocol(provider).mediaProtocol;
-  if (protocol === 'dashscope') return (capability !== 'tts' || !dashscopeTtsProtocolIssue(modelId))
-    && (!checkEndpoint || isDashScopeBaseUrl(providerMediaBaseUrl(provider)));
-  return capability === 'image-gen' && ['openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol);
+  const protocol = capability === 'music-gen' ? provider?.models?.find(model => model?.id === modelId)?.musicProtocol
+    : capability === 'image-gen' ? selectImageProtocol(provider, modelId, registry).mediaProtocol : selectMediaProtocol(provider).mediaProtocol;
+  const descriptor = providerProtocolDescriptor(protocol, registry);
+  return Boolean(descriptor?.capabilities.includes(capability)
+    && (!descriptor.supportsModel || descriptor.supportsModel({ provider, modelId, capability, checkEndpoint })));
+}
+
+/** Canonical binding spelling; existing Task hashes depend on this exact normalization. */
+export function normalizeMediaEndpoint(baseUrl) {
+  const url = new URL(baseUrl);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new TypeError('媒体端点必须是无凭据、查询或片段的 HTTP(S) 地址');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+const CONNECTION_FIELDS = Object.freeze([
+  Object.freeze({ key: 'baseUrl', label: 'API 地址', type: 'url', required: true }),
+  Object.freeze({ key: 'mediaBaseUrl', label: '媒体专用地址', type: 'url', advanced: true }),
+  Object.freeze({ key: 'apiKey', label: 'API Key', type: 'secret' })
+]);
+
+/** Immutable defaults, not a mutable process-wide extension registry. */
+export const BUILTIN_PROVIDER_PROTOCOLS = Object.freeze([
+  { id: 'gemini-web-music', label: 'Chat Completions（内嵌音频）', capabilities: ['music-gen'] },
+  { id: 'dashscope', label: 'DashScope', capabilities: ['image-gen', 'video-gen', 'tts', 'transcribe'],
+    normalizeEndpoint: dashscopeApiBase,
+    supportsModel: ({ provider, modelId, capability, checkEndpoint }) => (capability !== 'tts' || !dashscopeTtsProtocolIssue(modelId))
+      && (!checkEndpoint || isDashScopeBaseUrl(providerMediaBaseUrl(provider))),
+    supportsImageEdit: modelId => /^qwen-image-(?:edit(?:-(?:max|plus))?|2\.0(?:-pro)?)(?:-\d{4}-\d{2}-\d{2})?$/.test(String(modelId || '')) },
+  { id: 'openai-images', label: 'OpenAI Images', capabilities: ['image-gen'] },
+  { id: 'openai-chat-images', label: 'Chat Completions 图片', capabilities: ['image-gen'], supportsImageEdit: () => true },
+  { id: 'openai-responses-images', label: 'Responses 图片', capabilities: ['image-gen'] },
+  { id: 'comfyui', label: 'ComfyUI · API 工作流', capabilities: ['image-gen'],
+    supportsModel: ({ provider, modelId }) => {
+      const value = provider.models?.find(model => model?.id === modelId)?.comfyWorkflow;
+      if (!value) return false;
+      comfyWorkflowDigest(value); return true;
+    } }
+].map(descriptor => Object.freeze({ normalizeEndpoint: normalizeMediaEndpoint, configuration: CONNECTION_FIELDS,
+  ...descriptor, capabilities: Object.freeze(descriptor.capabilities) })));
+
+export function providerProtocolDescriptor(protocol, registry) {
+  return registry ? registry.descriptor(protocol) : BUILTIN_PROVIDER_PROTOCOLS.find(descriptor => descriptor.id === protocol);
 }
 
 /**

package/lib/provider-registry.js

@@ -0,0 +1,128 @@
+import { defineProviderAdapter } from './provider-adapter.js';
+import { unsupportedProtocolError, providerApiKey } from './provider-protocol.js';
+import { checkedPluginDependency, assertPluginDependencyMatches } from './plugin-contract.js';
+import { createProviderNetworkClient } from './provider-network.js';
+import { createProviderContext, markProviderContextAdapter } from './provider-context.js';
+import { resolveProviderCredential } from './provider-credentials.js';
+
+export const PROVIDER_EXTENSION_CONTRACT_VERSION = 0;
+const ID = /^[a-z][a-z0-9._-]{0,79}$/;
+const CAPS = Object.freeze({ 'image-gen': 'image', 'video-gen': 'video', tts: 'tts', 'music-gen': 'music', transcribe: 'transcribe' });
+const invalid = message => Object.assign(new TypeError(message), { code: 'IRIS_PROVIDER_EXTENSION_INVALID' });
+const closed = () => Object.assign(new Error('Provider 扩展实例已关闭或正在关闭'), {
+  code: 'IRIS_PROVIDER_EXTENSION_CLOSED', stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted' });
+
+function checkedProtocol(value) {
+  if (!value || typeof value.id !== 'string' || !ID.test(value.id) || typeof value.label !== 'string' || !value.label.trim() || value.label.length > 100
+      || !Array.isArray(value.capabilities) || !value.capabilities.length
+      || value.capabilities.some(cap => !Object.hasOwn(CAPS, cap)) || new Set(value.capabilities).size !== value.capabilities.length
+      || typeof value.createAdapter !== 'function' || typeof value.normalizeEndpoint !== 'function'
+      || (value.supportsModel !== undefined && typeof value.supportsModel !== 'function')
+      || (value.supportsImageEdit !== undefined && typeof value.supportsImageEdit !== 'function')) throw invalid('Provider 协议描述无效');
+  if (value.configuration !== undefined && !Array.isArray(value.configuration)) throw invalid('配置字段描述必须是数组');
+  const keys = new Set();
+  const configuration = (value.configuration || []).map(field => {
+    if (!field || !['baseUrl', 'mediaBaseUrl', 'apiKey'].includes(field.key) || keys.has(field.key)
+        || typeof field.label !== 'string' || !field.label.trim() || field.label.length > 100
+        || field.type !== (field.key === 'apiKey' ? 'secret' : 'url')
+        || (field.required !== undefined && typeof field.required !== 'boolean')
+        || (field.advanced !== undefined && typeof field.advanced !== 'boolean')) throw invalid('Provider 配置字段描述无效');
+    keys.add(field.key);
+    return Object.freeze({ key: field.key, label: field.label, type: field.type,
+      ...(field.required !== undefined ? { required: field.required } : {}), ...(field.advanced !== undefined ? { advanced: field.advanced } : {}) });
+  });
+  const dependency = value.dependency === undefined ? undefined : checkedPluginDependency(value.dependency);
+  if (dependency && (dependency.kind !== 'providers' || dependency.contributionId !== value.id)) throw invalid('Provider 与插件贡献依赖不一致');
+  return Object.freeze({ id: value.id, label: value.label, capabilities: Object.freeze([...value.capabilities]),
+    configuration: Object.freeze(configuration), normalizeEndpoint: value.normalizeEndpoint,
+    ...(dependency ? { dependency } : {}),
+    ...(value.supportsModel ? { supportsModel: value.supportsModel } : {}),
+    ...(value.supportsImageEdit ? { supportsImageEdit: value.supportsImageEdit } : {}), createAdapter: value.createAdapter });
+}
+
+/** One registry owns its factory instances, active calls and serial asynchronous cleanup. */
+export async function createExtensionRegistry(factories) {
+  const protocols = new Map(), extensions = [], active = new Set();
+  let state = 'loading', disposal, cleanupFailed = false, inherited;
+  const inheritedNetwork = () => inherited ||= createProviderNetworkClient();
+
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        const errors = [];
+        try { await inherited?.dispose(); } catch (error) { errors.push(error); }
+        for (const extension of [...extensions].reverse()) {
+          try { await extension.dispose?.(); } catch (error) { errors.push(error); }
+        }
+        protocols.clear(); state = 'closed'; cleanupFailed = errors.length > 0;
+        if (errors.length) throw new AggregateError(errors, 'Provider 扩展释放失败');
+      })();
+    }
+    return disposal;
+  }
+
+  try {
+    for (const factory of factories) {
+      if (typeof factory !== 'function') throw invalid('扩展入口必须是创建独立实例的工厂函数');
+      const extension = await factory();
+      if (extension && typeof extension.dispose === 'function') extensions.push({ dispose: () => extension.dispose() });
+      if (!extension || extension.contractVersion !== PROVIDER_EXTENSION_CONTRACT_VERSION || typeof extension.id !== 'string' || !ID.test(extension.id)
+          || typeof extension.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(extension.version)
+          || !Array.isArray(extension.protocols) || !extension.protocols.length
+          || (extension.dispose !== undefined && typeof extension.dispose !== 'function')) throw invalid('扩展身份、版本或协议集合无效');
+      if (extensions.some(item => item.id === extension.id)) throw invalid('扩展 ID 重复：' + extension.id);
+      const owned = extension.protocols.map(checkedProtocol);
+      for (const protocol of owned) {
+        if (protocol.dependency && (protocol.dependency.pluginId !== extension.id || protocol.dependency.pluginVersion !== extension.version)) throw invalid('Provider 依赖不属于当前扩展版本');
+        if (protocols.has(protocol.id)) throw invalid('Provider 协议重复：' + protocol.id);
+        protocols.set(protocol.id, protocol);
+      }
+      if (typeof extension.dispose === 'function') Object.assign(extensions[extensions.length - 1], { id: extension.id, version: extension.version });
+      else extensions.push({ id: extension.id, version: extension.version });
+    }
+    state = 'active';
+  } catch (error) {
+    try { await dispose(); } catch (cleanup) { throw new AggregateError([error, cleanup], 'Provider 扩展装配与释放均失败'); }
+    throw error;
+  }
+
+  const wrap = action => async (...args) => {
+    if (state !== 'active') throw closed();
+    const call = Promise.resolve().then(() => action(...args));
+    active.add(call);
+    try { return await call; } finally { active.delete(call); }
+  };
+
+  return Object.freeze({
+    descriptor: id => state === 'active' ? protocols.get(id) : undefined,
+    snapshot: () => ({ contractVersion: PROVIDER_EXTENSION_CONTRACT_VERSION, state, activeCalls: active.size, cleanupFailed,
+      extensions: extensions.filter(item => item.id).map(({ id, version }) => ({ id, version })),
+      protocols: [...protocols.values()].map(({ id, label, capabilities, configuration, dependency }) => ({ id, label,
+        capabilities: [...capabilities], configuration: configuration.map(field => ({ ...field })),
+        ...(dependency ? { dependency: { ...dependency } } : {}) })) }),
+    createAdapter(id, provider, options) {
+      if (state !== 'active') throw closed();
+      const descriptor = protocols.get(id);
+      if (!descriptor) throw unsupportedProtocolError(id);
+      const author = descriptor.dependency ? createProviderContext(provider, options, inheritedNetwork) : undefined;
+      const resolved = author ? resolveProviderCredential(provider) : provider;
+      const connection = { ...resolved, apiKey: providerApiKey(resolved) };
+      const value = descriptor.createAdapter(author ? Object.freeze(connection) : connection, author?.context || options);
+      if (!value || typeof value.then === 'function') throw invalid('createAdapter 必须同步返回 Adapter');
+      if (value.pluginDependency !== undefined) assertPluginDependencyMatches(descriptor.dependency, value.pluginDependency);
+      const adapter = defineProviderAdapter({ ...value,
+        ...(descriptor.dependency ? { pluginDependency: descriptor.dependency } : {}),
+        unsupported: Object.fromEntries(Object.entries(value.unsupported || {}).map(([name, reason]) => [name, reason?.reason ?? reason])) });
+      if (adapter.id !== provider.id || adapter.protocol !== id || adapter.capabilities.some(cap =>
+        !descriptor.capabilities.some(known => CAPS[known] === cap))) throw invalid('Adapter 身份或能力与注册协议不一致');
+      const operation = (name, action) => wrap(author ? (...args) => author.invoke(name, action, args) : action);
+      const result = Object.freeze({ ...adapter, operations: Object.freeze(Object.fromEntries(Object.entries(adapter.operations)
+        .map(([name, action]) => [name, name === 'mapError' ? action : operation(name, action)]))),
+      ...(adapter.prepareInput ? { prepareInput: operation('prepareInput', adapter.prepareInput) } : {}) });
+      return author ? markProviderContextAdapter(result) : result;
+    },
+    dispose
+  });
+}

package/lib/provider-response.js

@@ -0,0 +1,38 @@
+import { ProviderContractError } from './provider-contract.js';
+
+export const PROVIDER_RESPONSE_LIMITS = Object.freeze({ json: 2 * 1024 * 1024, mediaJson: 128 * 1024 * 1024,
+  image: 64 * 1024 * 1024, audio: 128 * 1024 * 1024, transcript: 8 * 1024 * 1024, video: 1024 * 1024 * 1024 });
+
+/** Core materialization uses the same limits as provider downloads, including cached bytes. */
+export function assertProviderMediaSize(size, capability) {
+  const maxBytes = { image: PROVIDER_RESPONSE_LIMITS.image, video: PROVIDER_RESPONSE_LIMITS.video,
+    tts: PROVIDER_RESPONSE_LIMITS.audio, music: PROVIDER_RESPONSE_LIMITS.audio, transcribe: PROVIDER_RESPONSE_LIMITS.transcript }[capability];
+  if (maxBytes === undefined) throw new TypeError('未知的媒体交付能力：' + capability);
+  if (size > maxBytes) throw Object.assign(new ProviderContractError('供应商媒体超过允许的大小（' + maxBytes + ' 字节）', {
+    stage: 'download', category: 'protocol', acceptance: 'accepted', retryable: false
+  }), { code: 'IRIS_PROVIDER_RESPONSE_TOO_LARGE' });
+}
+
+/** Count decoded response bytes as well as Content-Length: chunked and compressed
+ * responses cannot bypass the limit. Iterator cancellation closes the body. */
+export async function* boundedProviderBody(response, { maxBytes, stage = 'response', acceptance = 'unknown' }) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new TypeError('供应商响应限额须为正整数字节数');
+  const tooLarge = () => Object.assign(new ProviderContractError('供应商响应超过允许的大小（' + maxBytes + ' 字节）', {
+    stage, category: 'protocol', acceptance, retryable: false
+  }), { code: 'IRIS_PROVIDER_RESPONSE_TOO_LARGE' });
+  if (Number(response.headers.get('content-length')) > maxBytes) {
+    try { await response.body?.cancel(); } finally { throw tooLarge(); }
+  }
+  let size = 0;
+  if (response.body) for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > maxBytes) throw tooLarge();
+    yield chunk;
+  }
+}
+
+export async function readProviderText(response, options) {
+  const chunks = []; let size = 0;
+  for await (const chunk of boundedProviderBody(response, options)) { chunks.push(chunk); size += chunk.length; }
+  return Buffer.concat(chunks, size).toString('utf8');
+}