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

package/lib/provider-catalog.js

@@ -5,11 +5,13 @@ 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';
 
 export class ProviderCatalogError extends Error {
   constructor(code, message) {
@@ -51,7 +53,10 @@ 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) {
+    validateModelDirectory(provider.modelDirectory);
+    for (const model of provider.models || []) if (model?.comfyWorkflow !== undefined) checkedComfyWorkflow(model.comfyWorkflow);
+  }
   return parsed;
 }
 
@@ -62,11 +67,11 @@ const CANDIDATE_CAP_LABEL = Object.freeze({
 });
 
 /** 与 DSH 共用功能策略；CLI 不附加宿主资源。 */
-function candidatesFromCatalog(catalog, requestedModelRef, capability) {
+function candidatesFromCatalog(catalog, requestedModelRef, capability, registry) {
   const label = CANDIDATE_CAP_LABEL[capability];
   if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
   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) {
@@ -95,30 +100,30 @@ 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) {
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE, registry).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) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO, registry);
 }
 
-export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS);
+export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS, registry);
 }
 
-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) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE, registry);
 }
 
-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、不发现模型、不暴露端点或凭据。 */
@@ -143,13 +148,13 @@ export function providerCatalogSnapshot(catalog) {
   };
 }
 
-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 +162,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'
@@ -187,10 +197,11 @@ export function providerForTaskFromCatalog(catalog, task) {
   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;
+  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-service.js

@@ -6,16 +6,26 @@ import { isKnownCapability } from './capability.js';
 import { providerModels, modelPool, functionPolicy, savedAssignmentRefs, parseModelRef, HOST_VISION_REF, capabilitiesOfDiscoveredModel, hasConfiguredModelCapabilities, resolvePoolModel } from './models.js';
 import { atomicWritePrivate, privateSibling, ensurePrivateDir } from './private-storage.js';
 import { createConfiguredProviderAdapter } from './provider-adapters.js';
-import { selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol, isConfiguredProvider } from './provider-protocol.js';
+import { selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol, isConfiguredProvider, providerForImageModel, providerApiKey } from './provider-protocol.js';
 import { invokeProviderOperation } from './provider-adapter.js';
 import { redactProviderMessage } from './provider-contract.js';
 import { modelRateLimit, recordModelRateLimit, clearModelRateLimit, clearModelCapabilityHealth, isDefinitiveHealthFailure, recordModelAvailability, resetHealthOnCriticalChange } from './provider-health.js';
 import { normalizeVisionInputLimits, visionInputLimits } from './vision-image-input.js';
 import { currentModelDirectory, modelDirectoryBinding, modelAvailabilityBinding } from './model-directory.js';
 import { refreshModelDirectory } from './model-directory-service.js';
+import { projectProviderSettings, applyProviderSettings, applyFunctionPolicies } from './provider-settings.js';
+import { checkedComfyWorkflow, compileComfyWorkflow, projectComfyWorkflow } from './comfyui-workflow.js';
+import { createComfyUiClient } from './comfyui-client.js';
+import { inspectComfyWorkflow } from './comfyui-inspection.js';
 
 const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
 const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+// Owner edits change configuration, while task health and directory caches can
+// advance independently. Saves still load fresh records and use a byte CAS under
+// the file lock, preserving the latest runtime evidence.
+function settingsRevision(catalog) {
+  return hash(JSON.stringify({ ...catalog, providers: catalog.providers.map(({ health, modelDirectory, ...provider }) => provider) }));
+}
 const safe = value => redactProviderMessage(String(value || '').replace(/https?:\/\/[^\s<>"']+/gi, '[URL]'));
 const text = value => { if (typeof value !== 'string' || !value.trim()) fail('ID 必须是非空字符串'); return value.trim(); };
 const caps = value => {
@@ -33,7 +43,7 @@ function assignmentSnapshot(catalog) {
   }));
 }
 
-export function configSnapshot(catalog) {
+export function configSnapshot(catalog, registry) {
   return { ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
     ref: safe(model.ref), providerId: safe(provider.id), id: safe(model.id), capabilities: model.capabilities,
     ...(model.catalogStatus ? { catalogStatus: model.catalogStatus } : {}),
@@ -41,16 +51,18 @@ export function configSnapshot(catalog) {
     ...(model.imageProtocol !== undefined ? { imageProtocol: model.imageProtocol } : {}),
     ...(model.musicProtocol !== undefined ? { musicProtocol: model.musicProtocol } : {}),
     ...(model.visionInput !== undefined ? { visionInput: model.visionInput } : {}),
+    ...(provider.models?.find(entry => entry?.id === model.id)?.comfyWorkflow ? {
+      comfyWorkflow: projectComfyWorkflow(provider.models.find(entry => entry?.id === model.id).comfyWorkflow) } : {}),
     ...(model.capabilities.includes('vision') ? { visionInputEffective: visionInputLimits(provider, model.id) } : {}),
-    ...(model.capabilities.includes('image-gen') ? { imageRouting: selectImageProtocol(provider, model.id) } : {}),
+    ...(model.capabilities.includes('image-gen') ? { imageRouting: selectImageProtocol(provider, model.id, registry) } : {}),
     verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: safe(value.at), category: safe(value.category) }])),
     ...(model.rateLimited ? { rateLimited: true, rateLimitedAt: modelRateLimit(provider, model.id).at,
       ...(modelRateLimit(provider, model.id).until ? { retryAt: modelRateLimit(provider, model.id).until }
         : { reason: modelRateLimit(provider, model.id).reason }) } : {})
-  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog) };
+  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog, registry) };
 }
 
-export async function executeConfigCommand(configPath, command, input = {}, { signal, probe } = {}) {
+export async function executeConfigCommand(configPath, command, input = {}, { signal, probe, registry } = {}) {
   if (command === 'init') {
     if (!path.isAbsolute(configPath)) fail('provider-config 必须是绝对路径');
     ensurePrivateDir(path.dirname(configPath));
@@ -60,7 +72,74 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
   const catalog = loadProviderCatalog(configPath);
   const before = fs.readFileSync(configPath);
   if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(catalog)) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
-  if (command === 'show') return configSnapshot(catalog);
+  if (command === 'settings.show') return projectProviderSettings(catalog, settingsRevision(catalog), registry);
+  if (['settings.policies', 'settings.enabled', 'settings.remove'].includes(command)) {
+    const fields = command === 'settings.policies' ? ['expectedRevision', 'assignments'] : command === 'settings.enabled'
+      ? ['expectedRevision', 'providerId', 'enabled'] : ['expectedRevision', 'providerId', 'confirm'];
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== fields.length
+        || fields.some(key => !Object.hasOwn(input, key))) fail('管理请求字段不符合约定');
+    if (input.expectedRevision !== settingsRevision(catalog)) throw Object.assign(new Error('配置已变化，请重新读取后核对'), { code: 'IRIS_CONFIG_CHANGED' });
+    if (command === 'settings.policies') applyFunctionPolicies(catalog, input.assignments);
+    else {
+      const matches = catalog.providers.filter(provider => provider.id === input.providerId);
+      if (matches.length !== 1) fail('供应商不存在或ID重复');
+      if (command === 'settings.enabled') {
+        if (typeof input.enabled !== 'boolean') fail('enabled 必须是布尔值');
+        matches[0].enabled = input.enabled;
+      } else {
+        if (input.confirm !== true) fail('请明确确认删除此供应商');
+        const pool = modelPool(catalog.providers, { includeHostVision: true });
+        for (const [cap, assignment] of Object.entries(catalog.assignments || {})) {
+          const policy = functionPolicy(assignment, cap);
+          catalog.assignments[cap] = { ...policy, models: savedAssignmentRefs(pool, cap, policy.models)
+            .filter(ref => parseModelRef(ref)?.providerId !== input.providerId) };
+        }
+        catalog.providers = catalog.providers.filter(provider => provider !== matches[0]);
+      }
+    }
+    signal?.throwIfAborted(); writeConfigChange(configPath, catalog, before, {});
+    return projectProviderSettings(catalog, settingsRevision(catalog), registry);
+  }
+  if (command === 'models.workflow-check' || command === 'settings.workflow-check') {
+    const settings = command === 'settings.workflow-check';
+    const allowed = settings ? ['expectedRevision', 'modelRef', 'workflowParameters', 'providerId', 'comfyWorkflow'] : ['model_ref', 'workflow_parameters'];
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !allowed.includes(key))) fail('工作流检查包含不支持的字段');
+    if (settings && input.expectedRevision !== settingsRevision(catalog)) throw Object.assign(new Error('配置已变化，请重新读取后检查'), { code: 'IRIS_CONFIG_CHANGED' });
+    const draft = settings && input.comfyWorkflow !== undefined;
+    const ref = draft ? null : parseModelRef(settings ? input.modelRef : input.model_ref);
+    if (draft ? typeof input.providerId !== 'string' || input.modelRef !== undefined : !ref || input.providerId !== undefined) fail('需要明确的模型，或已保存连接与工作流草稿');
+    const matches = catalog.providers.filter(provider => provider.id === (draft ? input.providerId : ref.providerId));
+    if (matches.length !== 1 || !isConfiguredProvider(matches[0]) || !draft && !matches[0].models?.some(model => model.id === ref.modelId)) fail('请先配置并启用明确的工作流连接');
+    const provider = draft ? { ...matches[0], comfyWorkflow: checkedComfyWorkflow(input.comfyWorkflow) } : providerForImageModel(matches[0], ref.modelId, registry);
+    if (provider.mediaProtocol !== 'comfyui') fail('此检查仅用于 ComfyUI 工作流');
+    const workflow = compileComfyWorkflow(provider.comfyWorkflow, { workflow_parameters: settings ? input.workflowParameters : input.workflow_parameters });
+    const report = await inspectComfyWorkflow(createComfyUiClient(provider), workflow, { signal });
+    signal?.throwIfAborted();
+    if (settingsRevision(loadProviderCatalog(configPath)) !== settingsRevision(catalog)) throw Object.assign(new Error('检查期间配置已变化，请重新检查'), { code: 'IRIS_CONFIG_CHANGED' });
+    const key = providerApiKey(provider);
+    return { ...JSON.parse(key ? JSON.stringify(report).split(key).join('[redacted]') : JSON.stringify(report)), revision: settingsRevision(catalog) };
+  }
+  if (command === 'settings.save' || command === 'settings.discover') {
+    if (!input || typeof input.expectedRevision !== 'string' || input.expectedRevision !== settingsRevision(catalog)) {
+      throw Object.assign(new Error('配置已变化，请重新读取后核对草稿'), { code: 'IRIS_CONFIG_CHANGED' });
+    }
+    if (command === 'settings.discover') {
+      if (Object.keys(input).some(key => !['expectedRevision', 'providerId'].includes(key))) fail('目录请求包含不支持的字段');
+      const found = catalog.providers.filter(item => item.id === input.providerId);
+      if (found.length !== 1 || !isConfiguredProvider(found[0])) fail('请先保存并启用有认证配置的连接');
+      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(found[0], { registry }), 'discover', { signal, timeoutMs: 10000 });
+      signal?.throwIfAborted();
+      if (settingsRevision(loadProviderCatalog(configPath)) !== settingsRevision(catalog)) throw Object.assign(new Error('目录读取期间配置已变化'), { code: 'IRIS_CONFIG_CHANGED' });
+      return { contractVersion: 0, revision: settingsRevision(catalog), models: discovered.models.slice(0, 256).map(model => ({
+        id: safe(text(typeof model === 'string' ? model : model.id)).split(found[0].apiKey || '\u0000').join('[redacted]'), capabilities: capabilitiesOfDiscoveredModel(model)
+      })), truncated: discovered.models.length > 256, persisted: false };
+    }
+    applyProviderSettings(catalog, input, registry);
+    signal?.throwIfAborted();
+    writeConfigChange(configPath, catalog, before, {});
+    return projectProviderSettings(catalog, settingsRevision(catalog), registry);
+  }
+  if (command === 'show') return configSnapshot(catalog, registry);
   if (command === 'check') {
     const issues = [];
     const ids = catalog.providers.map(provider => provider.id);
@@ -70,11 +149,11 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       try { normalizeVisionInputLimits(provider.visionInput); } catch (_) { issues.push('invalid_vision_input'); }
       for (const model of provider.models || []) {
         if (model?.musicProtocol !== undefined) {
-          try { normalizeMusicProtocol(model.musicProtocol); } catch (_) { issues.push('invalid_model_music_protocol'); }
+          try { normalizeMusicProtocol(model.musicProtocol, registry); } catch (_) { issues.push('invalid_model_music_protocol'); }
         }
         try { normalizeVisionInputLimits(model?.visionInput); } catch (_) { issues.push('invalid_model_vision_input'); }
         if (model?.imageProtocol === undefined) continue;
-        try { normalizeImageProtocol(model.imageProtocol); } catch (_) { issues.push('invalid_model_image_protocol'); }
+        try { normalizeImageProtocol(model.imageProtocol, registry); } catch (_) { issues.push('invalid_model_image_protocol'); }
       }
     }
     for (const [capability, assignment] of Object.entries(catalog.assignments || {})) {
@@ -84,8 +163,8 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     }
     return { valid: issues.length === 0, issues: [...new Set(issues)] };
   }
-  if (command === 'models.list') return { models: configSnapshot(catalog).models };
-  if (command === 'assignments.list') return { ...catalogCapabilitySnapshot(catalog), assignments: assignmentSnapshot(catalog) };
+  if (command === 'models.list') return { models: configSnapshot(catalog, registry).models };
+  if (command === 'assignments.list') return { ...catalogCapabilitySnapshot(catalog, registry), assignments: assignmentSnapshot(catalog) };
   let result = { command, changed: true };
   const initialPool = modelPool(catalog.providers);
   let provider;
@@ -113,13 +192,16 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
         if (model?.capabilities !== undefined) caps(model.capabilities);
       }
       updated.models = updated.models.map(model => typeof model === 'string' ? model : ({ ...model,
-        ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
-        ...(model?.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(model.musicProtocol) } : {}),
+        ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol, registry) } : {}),
+        ...(model?.comfyWorkflow !== undefined ? { comfyWorkflow: checkedComfyWorkflow(model.comfyWorkflow) } : {}),
+        ...(model?.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(model.musicProtocol, registry) } : {}),
         ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
     }
     if (provider) {
       for (const model of providerModels(provider)) {
-        if (selectImageProtocol(provider, model.id).mediaProtocol !== selectImageProtocol(updated, model.id).mediaProtocol) {
+        if (selectImageProtocol(provider, model.id, registry).mediaProtocol !== selectImageProtocol(updated, model.id, registry).mediaProtocol
+            || JSON.stringify(provider.models?.find(entry => entry?.id === model.id)?.comfyWorkflow)
+              !== JSON.stringify(updated.models?.find(entry => entry?.id === model.id)?.comfyWorkflow)) {
           clearModelCapabilityHealth(updated, model.id, 'image-gen');
         }
       }
@@ -138,7 +220,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       : providerModels(provider).map(({ id, capabilities }) => ({ id, capabilities }));
     let entry = entries.find(model => model.id === modelId);
     if (command === 'models.discover') {
-      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(provider), 'discover', { signal, timeoutMs: 15000 });
+      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(provider, { registry }), 'discover', { signal, timeoutMs: 15000 });
       const models = discovered.models.map(model => ({ id: text(typeof model === 'string' ? model : model.id), capabilities: capabilitiesOfDiscoveredModel(model), source: 'discovered' }));
       result = { command, changed: input.apply === true, total: models.length, mediaCount: models.filter(model => model.capabilities.length).length, models: models.map(model => ({ ...model, id: safe(model.id) })) };
       if (input.apply !== true) return result;
@@ -155,8 +237,8 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       const capabilities = input.capabilities === undefined ? undefined : caps(input.capabilities);
       if (entry) fail('模型已存在；请用 models caps 修改能力');
       entries.push({ id: modelId, capabilities, source: 'manual',
-        ...(input.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(input.imageProtocol) } : {}),
-        ...(input.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(input.musicProtocol) } : {}),
+        ...(input.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(input.imageProtocol, registry) } : {}),
+        ...(input.musicProtocol !== undefined ? { musicProtocol: normalizeMusicProtocol(input.musicProtocol, registry) } : {}),
         ...(input.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(input.visionInput) || null } : {}) });
     } else if (command === 'models.remove') {
       if (!entry) fail('模型不存在');
@@ -166,16 +248,16 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       entry.capabilities = caps(input.capabilities); entry.source = 'manual';
     } else if (command === 'models.protocol') {
       if (!entry) fail('模型不存在');
-      const protocol = normalizeImageProtocol(input.imageProtocol);
-      const previous = selectImageProtocol(provider, modelId).mediaProtocol;
+      const protocol = normalizeImageProtocol(input.imageProtocol, registry);
+      const previous = selectImageProtocol(provider, modelId, registry).mediaProtocol;
       if (protocol === 'auto') delete entry.imageProtocol;
       else entry.imageProtocol = protocol;
       provider.models = entries;
-      if (previous !== selectImageProtocol(provider, modelId).mediaProtocol) clearModelCapabilityHealth(provider, modelId, 'image-gen');
-      result = { ...result, model_ref: safe(input.model_ref), imageRouting: selectImageProtocol(provider, modelId) };
+      if (previous !== selectImageProtocol(provider, modelId, registry).mediaProtocol) clearModelCapabilityHealth(provider, modelId, 'image-gen');
+      result = { ...result, model_ref: safe(input.model_ref), imageRouting: selectImageProtocol(provider, modelId, registry) };
     } else if (command === 'models.music-protocol') {
       if (!entry) fail('模型不存在');
-      const protocol = normalizeMusicProtocol(input.musicProtocol);
+      const protocol = normalizeMusicProtocol(input.musicProtocol, registry);
       if (entry.musicProtocol !== protocol) clearModelCapabilityHealth(provider, modelId, 'music-gen');
       entry.musicProtocol = protocol;
       result = { ...result, model_ref: safe(input.model_ref), musicProtocol: protocol };
@@ -281,11 +363,11 @@ export function recordCatalogAvailability(configPath, { providerId, modelId, cap
 }
 
 /** 新的自动请求按需读取目录；只读CLI命令与手选/停用不走这里。 */
-export async function refreshCatalogDirectories(configPath, catalog, capability, { signal } = {}) {
+export async function refreshCatalogDirectories(configPath, catalog, capability, { signal, registry } = {}) {
   if (functionPolicy(catalog.assignments?.[capability], capability).mode !== 'auto') return [];
   return Promise.all(catalog.providers.filter(provider => isConfiguredProvider(provider)
     && providerModels(provider).some(model => model.capabilities.includes(capability))).map(provider =>
-    refreshModelDirectory(provider, { signal, save: directory => {
+    refreshModelDirectory(provider, { signal, registry, save: directory => {
       const fresh = loadProviderCatalog(configPath);
       const before = fs.readFileSync(configPath);
       const current = fresh.providers.find(item => item.id === provider.id);

package/lib/provider-diagnostics.js

@@ -0,0 +1,56 @@
+import { catalogCapabilitySnapshot } from './provider-catalog.js';
+import { providerModels, functionPolicy, parseModelRef } from './models.js';
+import { isConfiguredProvider, supportsModelCapability } from './provider-protocol.js';
+import { healthObservationState, newestHealthEvidence, modelRateLimit } from './provider-health.js';
+import { listCoreTasks, findFlowTask } from './core-tasks.js';
+import { flowReferences } from './flow-store.js';
+
+/** Uses the same routing and health rules as submissions. No discovery, network calls or writes. */
+export function projectProviderDiagnostics(catalog, registry) {
+  const routes = catalogCapabilitySnapshot(catalog, registry).capabilities;
+  const capabilities = routes.map(route => {
+    const models = catalog.providers.flatMap(provider => providerModels(provider).filter(model => model.capabilities.includes(route.capability)).map(model => {
+      const observation = provider.health?.observations?.find(item => item.modelId === model.id && item.capability === route.capability);
+      const legacy = model.verified?.[route.capability];
+      const evidence = observation || (legacy ? { [legacy.ok ? 'lastSuccess' : ['auth', 'authentication', 'permission'].includes(legacy.category) ? 'lastFailure' : 'lastTransient']: legacy } : undefined);
+      const limit = modelRateLimit(provider, model.id);
+      const latest = newestHealthEvidence(evidence);
+      const reason = provider.enabled === false ? 'provider_disabled' : !isConfiguredProvider(provider) ? 'connection_unconfigured'
+        : route.mode === 'disabled' ? 'function_disabled' : model.source === 'discovered' ? 'unconfirmed'
+          : !supportsModelCapability(provider, model.id, route.capability, { registry }) ? 'protocol_unsupported'
+            : model.unavailableCapabilities?.includes(route.capability) ? 'model_missing' : limit ? limit.until ? 'cooling' : 'quota'
+              : !route.candidates.includes(model.ref) ? 'outside_pool' : null;
+      return { ref: model.ref, providerId: provider.id, providerName: provider.name || provider.id, modelId: model.id,
+        eligible: !reason, reason, rank: reason ? null : route.candidates.indexOf(model.ref) + 1,
+        state: healthObservationState(evidence), evidence: latest ? { at: latest.at, source: ['probe', 'task'].includes(latest.source) ? latest.source : 'unknown',
+          category: ['success', 'authentication', 'auth', 'permission', 'rate_limit', 'quota', 'network', 'timeout', 'protocol', 'unknown'].includes(latest.category) ? latest.category : 'unknown' } : null,
+        ...(limit?.until ? { retryAt: limit.until } : {}),
+        comfy: Boolean(provider.models?.find(item => item?.id === model.id)?.comfyWorkflow) };
+    }));
+    return { capability: route.capability, mode: route.mode, candidates: models.filter(model => model.eligible).sort((a, b) => a.rank - b.rank).map(model => model.ref),
+      verified: models.filter(model => model.eligible && model.state === 'verified').length, models };
+  });
+  const result = { contractVersion: 0, capabilities };
+  const keys = catalog.providers.map(provider => provider.apiKey).filter(key => typeof key === 'string' && key);
+  const scrub = value => typeof value === 'string' ? keys.reduce((text, key) => text.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);
+}
+
+/** Current root only, under the caller's Core lease; unknown/corrupt records must fail visibly. */
+export function providerDependencies(root, providerId) {
+  const tasks = []; let offset = 0, page;
+  do { page = listCoreTasks(root, { provider_id: providerId, offset, limit: 200 }); tasks.push(...page.tasks); offset += page.limit; } while (offset < page.total);
+  const recoverable = task => task.acceptance === 'unknown' || ['none', 'unknown'].includes(task.outcome)
+    || task.outcome === 'succeeded' && task.deliveryState !== 'ready' || task.cancelState === 'requested';
+  const blockingTasks = tasks.filter(recoverable).map(task => task.id);
+  const blockingRuns = flowReferences(root).filter(({ run }) => parseModelRef(run.input.model_ref)?.providerId === providerId)
+    .filter(({ run }) => { const task = findFlowTask(root, run); return !task || recoverable(task); }).map(({ run }) => run.id);
+  return { scope: 'current-core-root', blockingTasks, blockingRuns, historicalTasks: tasks.length };
+}
+
+export function providerRemovalImpact(catalog, providerId) {
+  const provider = catalog.providers.find(item => item.id === providerId);
+  return { modelCount: provider ? providerModels(provider).length : 0, functions: Object.entries(catalog.assignments || {}).filter(([cap, value]) =>
+    functionPolicy(value, cap).models.some(ref => parseModelRef(ref)?.providerId === providerId)).map(([cap]) => cap) };
+}

package/lib/provider-extensions.js

@@ -0,0 +1,29 @@
+// Experimental v0 package boundary. This is not the complete Core SDK.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { builtinProviderExtension } from './provider-adapters.js';
+import { createExtensionRegistry } from './provider-registry.js';
+
+export { defineProviderAdapter, PROVIDER_ADAPTER_CONTRACT_VERSION } from './provider-adapter.js';
+export { ProviderContractError } from './provider-contract.js';
+export { normalizeMediaEndpoint } from './provider-protocol.js';
+export { PROVIDER_EXTENSION_CONTRACT_VERSION } from './provider-registry.js';
+
+export function createProviderRegistry({ extensions = [] } = {}) {
+  if (!Array.isArray(extensions)) throw new TypeError('extensions 必须是工厂数组');
+  return createExtensionRegistry([builtinProviderExtension, ...extensions]);
+}
+
+/** Trusted code only. Explicit absolute entry files; no discovery or package installation. */
+export async function loadProviderRegistry(entries = []) {
+  const factories = [];
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || !path.isAbsolute(entry) || !/\.m?js$/.test(entry)
+        || !fs.statSync(entry).isFile()) throw new TypeError('Provider 扩展入口必须是明确的 JS/MJS 文件绝对路径');
+    const module = await import(pathToFileURL(fs.realpathSync(entry)).href);
+    if (typeof module.default !== 'function') throw new TypeError('Provider 扩展须默认导出实例工厂函数');
+    factories.push(module.default);
+  }
+  return createProviderRegistry({ extensions: factories });
+}

package/lib/provider-health.js

@@ -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);

package/lib/provider-monitor.js

@@ -0,0 +1,79 @@
+// 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';
+
+const AUTOMATIC = new Set(['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music', 'comfyui']);
+const errorCode = error => ['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, 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 (!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,
+          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 });
+}