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

package/lib/provider-protocol.js

@@ -1,5 +1,6 @@
 'use strict';
 /** 供应商媒体协议判断与 DashScope 凭据边界。 */
+import { comfyWorkflowDigest } from './comfyui-workflow.js';
 
 const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
 const REGIONAL_HOST = /^cn-hongkong\.dashscope\.aliyuncs\.com$/i;
@@ -46,44 +47,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') {
@@ -135,13 +146,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,118 @@
+import { defineProviderAdapter } from './provider-adapter.js';
+import { unsupportedProtocolError, providerApiKey } from './provider-protocol.js';
+import { checkedPluginDependency, assertPluginDependencyMatches } from './plugin-contract.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;
+
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        const errors = [];
+        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 value = descriptor.createAdapter({ ...provider, apiKey: providerApiKey(provider) }, 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 身份或能力与注册协议不一致');
+      return Object.freeze({ ...adapter, operations: Object.freeze(Object.fromEntries(Object.entries(adapter.operations)
+        .map(([name, action]) => [name, name === 'mapError' ? action : wrap(action)]))),
+      ...(adapter.prepareInput ? { prepareInput: wrap(adapter.prepareInput) } : {}) });
+    },
+    dispose
+  });
+}

package/lib/provider-response.js

@@ -0,0 +1,28 @@
+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 });
+
+/** 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');
+}

package/lib/provider-settings.js

@@ -0,0 +1,134 @@
+// Owner-only editing boundary. No I/O, secrets in projections, or implicit model authorization.
+import { CAPABILITIES } from './capability.js';
+import { providerModels, modelPool, functionPolicy, savedAssignmentRefs, resolvePoolModel } from './models.js';
+import { BUILTIN_PROVIDER_PROTOCOLS, normalizeMediaEndpoint, normalizeImageProtocol, normalizeMusicProtocol, selectMediaProtocol, providerForModelBinding, isConfiguredProvider } from './provider-protocol.js';
+import { clearModelCapabilityHealth, resetHealthOnCriticalChange } from './provider-health.js';
+import { checkedComfyWorkflow, projectComfyWorkflow } from './comfyui-workflow.js';
+
+const CAPS = Object.values(CAPABILITIES);
+const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
+function object(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !fields.includes(key))) fail('设置包含不支持的字段');
+}
+function string(value, max, empty = false) {
+  if (typeof value !== 'string' || value.length > max || /[\u0000-\u001f\u007f]/.test(value) || !empty && !value.trim()) fail('设置文本为空、过长或含控制字符');
+  return value.trim();
+}
+function capabilities(value) {
+  if (!Array.isArray(value) || value.some(cap => !CAPS.includes(cap)) || new Set(value).size !== value.length) fail('模型用途必须是已知能力的非重复数组');
+  return [...value];
+}
+const protocols = registry => registry ? registry.snapshot().protocols : BUILTIN_PROVIDER_PROTOCOLS;
+
+export function projectProviderSettings(catalog, revision, registry) {
+  const pool = modelPool(catalog.providers, { includeHostVision: true });
+  const result = { contractVersion: 0, source: 'explicit-provider-config', revision,
+    protocols: protocols(registry).map(({ id, label, capabilities, configuration }) => ({ id, label, capabilities, configuration })),
+    capabilities: CAPS,
+    providers: catalog.providers.map(provider => ({ id: provider.id, name: provider.name || provider.id,
+      baseUrl: provider.baseUrl || '', mediaBaseUrl: provider.mediaBaseUrl || '',
+      enabled: provider.enabled !== false, auth: provider.auth === 'none' ? 'none' : 'bearer',
+      hasCredential: Boolean(provider.apiKey), configured: isConfiguredProvider(provider),
+      mediaProtocol: selectMediaProtocol(provider).mediaProtocol,
+      models: providerModels(provider).map(model => ({ id: model.id, ref: model.ref, capabilities: model.capabilities,
+        imageProtocol: model.imageProtocol || 'auto', musicProtocol: model.musicProtocol || '',
+        ...(provider.models?.find(entry => entry?.id === model.id)?.comfyWorkflow ? {
+          comfyWorkflow: projectComfyWorkflow(provider.models.find(entry => entry?.id === model.id).comfyWorkflow) } : {}),
+        catalogStatus: model.catalogStatus || 'unknown', unavailableCapabilities: model.unavailableCapabilities || [],
+        rateLimited: model.rateLimited === true,
+        verified: Object.fromEntries(Object.entries(model.verified || {}).map(([cap, value]) => [cap, {
+          ok: value.ok === true, at: value.at, category: value.category
+        }])) })) })),
+    assignments: Object.fromEntries(CAPS.map(cap => {
+      const policy = functionPolicy(catalog.assignments?.[cap], cap);
+      return [cap, { ...policy, models: savedAssignmentRefs(pool, cap, policy.models) }];
+    })) };
+  // A mistakenly pasted key in a display field must not become a key read-back route.
+  const keys = catalog.providers.map(provider => provider.apiKey).filter(key => typeof key === 'string' && key);
+  const scrub = value => typeof value === 'string' ? keys.reduce((s, key) => s.split(key).join('[redacted]'), value)
+    : Array.isArray(value) ? value.map(scrub) : value && typeof value === 'object'
+      ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrub(item)])) : value;
+  return scrub(result);
+}
+
+export function applyProviderSettings(catalog, input, registry) {
+  object(input, ['expectedRevision', 'provider', 'credential', 'assignments']);
+  object(input.provider, ['id', 'name', 'baseUrl', 'mediaBaseUrl', 'mediaProtocol', 'enabled', 'auth', 'models']);
+  object(input.credential, ['action', 'value']);
+  const value = input.provider, id = string(value.id, 160);
+  const matches = catalog.providers.filter(item => item.id === id);
+  if (matches.length > 1) fail('供应商 ID 重复，请在本机核对');
+  const previous = matches[0];
+  const next = { ...previous, id, name: string(value.name, 80), baseUrl: string(value.baseUrl, 2048),
+    mediaBaseUrl: string(value.mediaBaseUrl ?? '', 2048, true), mediaProtocol: string(value.mediaProtocol, 80),
+    enabled: value.enabled, auth: value.auth };
+  next.protocolInferred = false;
+  if (typeof next.enabled !== 'boolean' || !['bearer', 'none'].includes(next.auth)) fail('供应商启用或认证方式无效');
+  try { normalizeMediaEndpoint(next.baseUrl); if (next.mediaBaseUrl) normalizeMediaEndpoint(next.mediaBaseUrl); }
+  catch (_) { fail('地址必须是无凭据、查询或片段的 HTTP(S) URL'); }
+  if (!protocols(registry).some(item => item.id === next.mediaProtocol) && previous?.mediaProtocol !== next.mediaProtocol) fail('协议未注册，请先显式加载对应扩展');
+  const credential = input.credential;
+  if (!['keep', 'replace', 'clear'].includes(credential.action) || credential.action !== 'replace' && Object.hasOwn(credential, 'value')) fail('密钥操作必须是 keep、replace 或 clear');
+  if (credential.action === 'replace') next.apiKey = string(credential.value, 8192);
+  if (credential.action === 'clear') delete next.apiKey;
+  if (!Array.isArray(value.models) || value.models.length > 256) fail('单次最多保存 256 个模型');
+  const existing = providerModels(previous || {});
+  const entries = Array.isArray(previous?.models) ? previous.models.map(model => typeof model === 'string' ? { id: model } : { ...model })
+    : existing.map(({ id, capabilities }) => ({ id, capabilities }));
+  const ids = new Set();
+  for (const model of value.models) {
+    object(model, ['id', 'capabilities', 'imageProtocol', 'musicProtocol', 'comfyWorkflow']);
+    const modelId = string(model.id, 512);
+    if (ids.has(modelId)) fail('模型 ID 重复');
+    ids.add(modelId);
+    const old = entries.find(entry => entry.id === modelId), oldView = existing.find(entry => entry.id === modelId);
+    const updated = { ...old, id: modelId, capabilities: capabilities(model.capabilities) };
+    if (model.comfyWorkflow !== undefined) updated.comfyWorkflow = checkedComfyWorkflow(model.comfyWorkflow);
+    if (!oldView || JSON.stringify(oldView.capabilities) !== JSON.stringify(updated.capabilities)) updated.source = 'manual';
+    if (model.imageProtocol !== undefined) {
+      const protocol = model.imageProtocol === old?.imageProtocol ? model.imageProtocol : normalizeImageProtocol(model.imageProtocol, registry);
+      if (protocol === 'auto') delete updated.imageProtocol; else updated.imageProtocol = protocol;
+    }
+    if (model.musicProtocol !== undefined) {
+      if (model.musicProtocol === '') delete updated.musicProtocol;
+      else updated.musicProtocol = model.musicProtocol === old?.musicProtocol ? model.musicProtocol : normalizeMusicProtocol(model.musicProtocol, registry);
+    }
+    if (old) entries[entries.indexOf(old)] = updated; else entries.push(updated);
+  }
+  next.models = entries; // Omitted existing records survive. The Web has no hard-delete operation.
+  if (previous) {
+    const previousConnection = { ...previous, auth: previous.auth === 'none' ? 'none' : 'bearer',
+      mediaBaseUrl: previous.mediaBaseUrl || '', mediaProtocol: selectMediaProtocol(previous).mediaProtocol };
+    resetHealthOnCriticalChange(previousConnection, next, next);
+    for (const model of existing) {
+      const updated = next.models.find(entry => entry.id === model.id);
+      const connectionChanged = ['apiKey', 'baseUrl', 'mediaBaseUrl', 'auth', 'mediaProtocol'].some(key => previousConnection[key] !== next[key]);
+      for (const cap of model.capabilities) if (connectionChanged || !updated.capabilities?.includes(cap)
+        || cap === 'image-gen' && JSON.stringify(previous.models?.find(entry => entry?.id === model.id)?.comfyWorkflow) !== JSON.stringify(updated.comfyWorkflow)
+        || cap === 'image-gen' && providerForModelBinding(previous, model.id, cap).mediaProtocol !== providerForModelBinding(next, model.id, cap).mediaProtocol
+        || cap === 'music-gen' && previous.models?.find(entry => entry.id === model.id)?.musicProtocol !== updated.musicProtocol) {
+        clearModelCapabilityHealth(next, model.id, cap);
+      }
+    }
+    catalog.providers[catalog.providers.indexOf(previous)] = next;
+  } else catalog.providers.push(next);
+  if (input.assignments !== undefined) applyFunctionPolicies(catalog, input.assignments);
+  return catalog;
+}
+
+export function applyFunctionPolicies(catalog, assignments) {
+  object(assignments, CAPS);
+  const pool = modelPool(catalog.providers, { includeHostVision: true });
+  catalog.assignments ||= {};
+  for (const [cap, assignment] of Object.entries(assignments)) {
+    object(assignment, ['mode', 'models', 'hostVision']);
+    let policy;
+    try { policy = functionPolicy(assignment, cap); } catch (_) { fail('功能策略无效'); }
+    if (!Object.hasOwn(assignment, 'mode') || new Set(policy.models).size !== policy.models.length || policy.models.length > 256) fail('功能策略或模型顺序无效');
+    // Existing invalid refs may be retained for diagnosis, but never newly authorized.
+    const oldRefs = savedAssignmentRefs(pool, cap, functionPolicy(catalog.assignments[cap], cap).models);
+    for (const ref of policy.models) if (!resolvePoolModel(pool, ref, cap) && !oldRefs.includes(ref)) fail('用途引用了不存在或未标注该能力的模型');
+    catalog.assignments[cap] = { mode: policy.mode, models: policy.models, ...(cap === 'vision' ? { hostVision: policy.hostVision } : {}) };
+  }
+  return catalog;
+}

package/lib/provider-task-runner.js

@@ -4,6 +4,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import sharp from 'sharp';
+import { isAudioRecipe, normalizeAudioFlowInput } from './audio-flow-input.js';
 import { adoptCoreArtifactFile, createCoreArtifact } from './core-artifacts.js';
 import {
   activateCoreWatch,
@@ -34,8 +35,9 @@ import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundar
 import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
 import { createDeliveryCache, newDeliveryPayloadPath, readDeliveryCache,
   readDeliveryPayload, recordDeliveryPayload } from './core-delivery-cache.js';
-import { readFlowRun, flowFail } from './flow-store.js';
+import { readFlowRun, flowFail, flowStep } from './flow-store.js';
 import { normalizeGenerationInput } from './generation-input.js';
+import { assertPluginDependencyMatches } from './plugin-contract.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -73,6 +75,7 @@ function checkAdapterForTask(task, adapter) {
   if (!adapter || adapter.id !== task.providerId) {
     throw new ProviderTaskRunnerError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Provider Adapter 与 Task 已持久化身份不一致');
   }
+  assertPluginDependencyMatches(task.pluginDependency, adapter.pluginDependency);
   return adapter;
 }
 
@@ -86,11 +89,14 @@ function normalizedCandidates(capability, candidates) {
     if (!adapter || !adapter.capabilities?.includes(capability) || !parsed
         || parsed.providerId !== adapter.id || !parsed.modelId
         || (candidate.providerBinding !== undefined && !/^sha256:[a-f0-9]{64}$/.test(candidate.providerBinding))
-        || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))) {
+        || (selectionReason !== undefined && !['explicit', 'assignment', 'pool'].includes(selectionReason))
+        || (adapter.pluginDependency && !candidate.providerBinding)) {
       throw new TypeError('Provider 候选 ' + (index + 1) + ' 不支持 Task capability 或模型复合身份无效');
     }
     if (candidate.prepareInput !== undefined && typeof candidate.prepareInput !== 'function') throw new TypeError('候选 prepareInput 必须是函数');
-    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, selectionReason, prepareInput: candidate.prepareInput };
+    if (candidate.supportsImageEdit !== undefined && typeof candidate.supportsImageEdit !== 'boolean') throw new TypeError('候选 supportsImageEdit 必须是布尔值');
+    return { adapter, model, providerModel: parsed.modelId, providerBinding: candidate.providerBinding, pluginDependency: adapter.pluginDependency, selectionReason, prepareInput: candidate.prepareInput,
+      ...(candidate.supportsImageEdit !== undefined ? { supportsImageEdit: candidate.supportsImageEdit } : {}) };
   });
 }
 
@@ -294,24 +300,30 @@ export function createProviderTaskRunner(runtime) {
       const capability = String(input.capability || '').trim();
       let candidates = normalizedCandidates(capability, input.candidates);
       let providerInput = input.providerInput ?? {};
+      if (providerInput.workflow_parameters !== undefined && candidates.some(candidate => candidate.adapter.protocol !== 'comfyui')) {
+        throw new ProviderTaskRunnerError('IRIS_COMFYUI_PARAMETERS_INVALID', '工作流参数仅用于明确的 ComfyUI 模板');
+      }
       let flow;
       if (input.flowRunId !== undefined) {
         flow = readFlowRun(dataRoot, input.flowRunId);
-        const expected = normalizeGenerationInput('image', flow.input).providerInput;
-        if (capability !== 'image' || !flow.edit.claimed || input.sourceArtifactId !== flow.source.artifactId
+        const audio = isAudioRecipe(flow.recipe), normalized = audio ? normalizeAudioFlowInput(flow.recipe, flow.input) : null;
+        const expected = audio ? Object.fromEntries(Object.entries(normalized).filter(([key]) => key !== 'model_ref')) : normalizeGenerationInput('image', flow.input).providerInput;
+        const expectedCapability = audio ? flow.recipe === 'speech/v0' ? 'tts' : 'transcribe' : 'image';
+        if (capability !== expectedCapability || !flowStep(flow).claimed || input.sourceArtifactId !== flow.source?.artifactId
             || Object.keys(providerInput).length !== Object.keys(expected).length
-            || Object.keys(expected).some(key => providerInput[key] !== expected[key])
+            || Object.keys(expected).some(key => key === 'workflow_parameters'
+              ? JSON.stringify(providerInput[key]) !== JSON.stringify(expected[key]) : providerInput[key] !== expected[key])
             || candidates.length !== 1 || candidates[0].model !== flow.input.model_ref
             || candidates[0].providerBinding !== flow.providerBinding) {
           flowFail('IRIS_FLOW_INPUT_CONFLICT', '提交与流程已保存的输入或模型绑定冲突');
         }
       }
-      if (input.sourceArtifactId !== undefined) {
-        if (capability !== 'image') throw new TypeError('sourceArtifactId 仅用于图片编辑');
+      if (input.sourceArtifactId !== undefined && capability === 'image') {
         candidates = imageEditCandidates(candidates);
         const image = await readImageEditArtifact(dataRoot, input.sourceArtifactId, signal);
         providerInput = { ...providerInput, image };
       }
+      if (input.sourceArtifactId !== undefined && !['image', 'transcribe'].includes(capability)) throw new TypeError('来源作品仅用于图片编辑或转写');
       const task = flow ? claimFlowTask(dataRoot, flow.id)
         : createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
       if (flow && task.attempts.length) flowFail('IRIS_FLOW_TASK_ALREADY_STARTED', '该流程 Task 已有提交意图，禁止重新 submit');
@@ -323,7 +335,7 @@ export function createProviderTaskRunner(runtime) {
         submit: async (providerInput, context) => {
           if (prepareInput) {
             try { providerInput = await prepareInput({ providerInput, signal }); }
-            catch (error) { throw new ProviderContractError('视频输入准备失败：' + (error.safeMessage || error.message), {
+            catch (error) { throw new ProviderContractError((capability === 'video' ? '视频' : '音频') + '输入准备失败：' + (error.safeMessage || error.message), {
               ...providerErrorRecord(error), stage: error.stage || 'prepare', category: error.category || 'local_io', acceptance: 'not_accepted'
             }); }
           }
@@ -345,6 +357,7 @@ export function createProviderTaskRunner(runtime) {
           return beginCoreAttempt(dataRoot, task.id, {
             ...attempt,
             ...(candidate.providerBinding !== undefined ? { providerBinding: candidate.providerBinding } : {}),
+            ...(candidate.pluginDependency ? { pluginDependency: candidate.pluginDependency } : {}),
             ...(candidate.selectionReason !== undefined ? { selectionReason: candidate.selectionReason } : {})
           });
         },

package/lib/skill-installation.js

@@ -1,9 +1,10 @@
-/** Explicit, copy-based installation of the bundled Core skill. No host/model I/O. */
+/** Explicit installation of the bundled Core skill or a rendered connection snapshot. No host/model I/O. */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { connectionSkillResources } from './connection-skill.js';
 
 const PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url));
 const SKILL = 'iris-core';
@@ -58,10 +59,10 @@ function sameTree(tree, recorded) {
     && JSON.stringify(tree.directories) === JSON.stringify([...recorded.directories].sort());
 }
 
-function validReceipt(value, packageName) {
+function validReceipt(value, packageName, skillName) {
   const relative = name => typeof name === 'string' && name.length > 0 && !name.includes('\\')
     && !name.includes('\0') && !name.split('/').some(part => !part || part === '.' || part === '..');
-  return value?.schemaVersion === 1 && value.packageName === packageName && value.skillName === SKILL
+  return value?.schemaVersion === 1 && value.packageName === packageName && value.skillName === skillName
     && typeof value.packageVersion === 'string' && value.packageVersion.length > 0
     && value.files && !Array.isArray(value.files) && typeof value.files === 'object'
     && Object.hasOwn(value.files, 'SKILL.md') && !Object.hasOwn(value.files, RECEIPT)
@@ -77,7 +78,18 @@ function packageResources(packageRoot) {
   if (!tree.files['SKILL.md'] || tree.files[RECEIPT]) {
     throw error('IRIS_SKILL_PACKAGE_INVALID', '包内缺少 Skill 入口，或含有不应发布的安装记录');
   }
-  return { source, metadata, ...tree };
+  return { skillName: SKILL, source, metadata, ...tree };
+}
+
+function bundleResources(file, packageRoot) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) throw error('IRIS_SKILL_OPTIONS_INVALID', '--bundle 必须是绝对路径');
+  const entry = fs.lstatSync(file);
+  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 16384) throw error('IRIS_SKILL_BUNDLE_INVALID', 'Skill 交付文件必须是最多 16 KiB 的普通 JSON 文件');
+  let value;
+  try { value = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (cause) { if (!(cause instanceof SyntaxError)) throw cause; throw error('IRIS_SKILL_BUNDLE_INVALID', 'Skill 交付文件不是有效 JSON'); }
+  const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  return { ...connectionSkillResources(value, metadata), source: fs.realpathSync(file) };
 }
 
 function inspect(destination, resources) {
@@ -92,7 +104,7 @@ function inspect(destination, resources) {
     if (!(cause instanceof SyntaxError)) throw cause;
     return { status: 'unmanaged', reason: 'invalid_receipt' };
   }
-  if (!validReceipt(receipt, resources.metadata.name)) return { status: 'unmanaged', reason: 'invalid_receipt' };
+  if (!validReceipt(receipt, resources.metadata.name, resources.skillName)) return { status: 'unmanaged', reason: 'invalid_receipt' };
   const base = { installedVersion: receipt.packageVersion };
   let tree;
   try { tree = readTree(destination, { installed: true, expected: receipt.files }); }
@@ -125,7 +137,7 @@ function ensureDirectory(directory) {
 
 function archive(destination, control, action) {
   const transaction = fs.mkdtempSync(path.join(control, 'backup-'));
-  const backupPath = path.join(transaction, SKILL);
+  const backupPath = path.join(transaction, path.basename(destination));
   fs.writeFileSync(path.join(transaction, 'move.json'), JSON.stringify({ schemaVersion: 1, action,
     at: new Date().toISOString(), origin: destination, backupPath }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
   fs.renameSync(destination, backupPath);
@@ -137,24 +149,24 @@ function copyResources(destination, resources) {
   for (const relative of resources.directories) fs.mkdirSync(path.join(destination, relative), { recursive: true, mode: 0o700 });
   for (const [relative, bytes] of Object.entries(resources.bytes)) fs.writeFileSync(path.join(destination, relative), bytes, { flag: 'wx', mode: 0o600 });
   fs.writeFileSync(path.join(destination, RECEIPT), JSON.stringify({ schemaVersion: 1,
-    packageName: resources.metadata.name, packageVersion: resources.metadata.version, skillName: SKILL,
+    packageName: resources.metadata.name, packageVersion: resources.metadata.version, skillName: resources.skillName,
     installedAt: new Date().toISOString(), files: resources.files, directories: resources.directories
   }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
 }
 
 /** Internal CLI service. Explicit mutations only; no postinstall or public SDK export. */
-export function manageCoreSkill({ action, target, directory, dryRun = false }, {
+export function manageCoreSkill({ action, target, directory, bundle, dryRun = false }, {
   packageRoot = PACKAGE_ROOT, env = process.env, home = os.homedir()
 } = {}) {
   if (!['install', 'status', 'uninstall'].includes(action) || action === 'status' && dryRun) {
     throw error('IRIS_SKILL_OPTIONS_INVALID', '使用 skills install/status/uninstall；status 不接受 --dry-run');
   }
-  const resources = packageResources(packageRoot);
-  const resolved = resolveDirectory({ target, directory, env, home }), destination = path.join(resolved, SKILL);
+  const resources = bundle === undefined ? packageResources(packageRoot) : bundleResources(bundle, packageRoot);
+  const resolved = resolveDirectory({ target, directory, env, home }), destination = path.join(resolved, resources.skillName);
   if (isWithin(resources.source, destination) || isWithin(destination, resources.source)) {
     throw error('IRIS_SKILL_OPTIONS_INVALID', '安装目标不能与包内 Skill 源目录重叠');
   }
-  const base = { skill: SKILL, target: target || 'directory', directory: resolved, destination,
+  const base = { skill: resources.skillName, target: target || 'directory', directory: resolved, destination,
     packageVersion: resources.metadata.version, discovery: 'not_checked' };
   const before = inspect(destination, resources);
   const result = { ...base, ...before };

package/lib/vision-model-routing.js

@@ -61,6 +61,9 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
     orientImages, prepareImageRequest,
     ...(prepareImages ? { imageInput: visionInputLimits(provider, parsed.modelId) } : {}) });
   const availability = result => {
+    // Ordinary vision/OCR is read-only for provider configuration. Explicit probes
+    // and definitive failures still update availability through the existing hook.
+    if (result.ok === true && !allowRateLimited) return;
     const event = { ...result, stage: 'submit', source: allowRateLimited ? 'probe' : 'task',
       binding: modelAvailabilityBinding(provider, parsed.modelId, 'vision') };
     if (!recordModelAvailability(provider, parsed.modelId, 'vision', event)) return;