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

package/lib/provider-config-service.js

@@ -6,16 +6,29 @@ 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 { applyCredentialPatch, assertProviderCredential, resolveProviderCredential, createProviderSecretScrubber } from './provider-credentials.js';
+import { inspectComfyWorkflow } from './comfyui-inspection.js';
+import { encodeProviderConfig } from './provider-config-format.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.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.
+export function settingsRevision(catalog) {
+  return hash(JSON.stringify(encodeProviderConfig({ ...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 => {
@@ -24,33 +37,51 @@ const caps = value => {
 };
 
 function assignmentSnapshot(catalog) {
+  const scrub = createProviderSecretScrubber(catalog.providers), label = value => safe(scrub(value));
   const pool = modelPool(catalog.providers, { includeHostVision: true });
   return Object.fromEntries(Object.entries(catalog.assignments || {}).map(([capability, value]) => {
     const policy = functionPolicy(value, capability);
     const refs = policy.models.map(ref => resolvePoolModel(pool, ref, capability));
-    return [safe(capability), { mode: policy.mode, hostVision: policy.hostVision,
-      model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
+    return [label(capability), { mode: policy.mode, hostVision: policy.hostVision,
+      model_refs: refs.filter(Boolean).map(model => label(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
   }));
 }
 
-export function configSnapshot(catalog) {
-  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,
+export function configSnapshot(catalog, registry) {
+  const scrub = createProviderSecretScrubber(catalog.providers), label = value => safe(scrub(value));
+  return scrub({ ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
+    ref: label(model.ref), providerId: label(provider.id), id: label(model.id), capabilities: model.capabilities,
     ...(model.catalogStatus ? { catalogStatus: model.catalogStatus } : {}),
     ...(model.unavailableCapabilities ? { unavailableCapabilities: model.unavailableCapabilities } : {}),
     ...(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) } : {}),
-    verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: safe(value.at), category: safe(value.category) }])),
+    ...(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: label(value.at), category: label(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, resolveProviderNetwork } = {}) {
+  if (resolveProviderNetwork !== undefined && typeof resolveProviderNetwork !== 'function') throw new TypeError('resolveProviderNetwork 必须是函数');
+  const networkFor = (provider, modelRef) => {
+    const requirement = providerNetworkRequirement(provider);
+    const network = resolveProviderNetwork?.({ providerId: provider.id, modelRef, provider, networkRequirement: requirement });
+    if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || network.providerId !== provider.id)) throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此目录需要匹配的显式网络配置，未装配的检查不会默认直连');
+    return network;
+  };
+  const adapterFor = provider => {
+    const network = networkFor(provider);
+    return createConfiguredProviderAdapter(provider, { registry, ...(network !== undefined ? { network } : {}) });
+  };
+  const assertRemovable = provider => {
+    if (providerNetworkRequirement(provider) && networkFor(provider)?.poolId !== undefined) throw networkPolicyError('IRIS_NETWORK_CONFIG_IN_USE', '此供应商仍有出口绑定；请先明确解除绑定，再删除连接');
+  };
   if (command === 'init') {
     if (!path.isAbsolute(configPath)) fail('provider-config 必须是绝对路径');
     ensurePrivateDir(path.dirname(configPath));
@@ -59,8 +90,81 @@ 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 (JSON.stringify(JSON.parse(before)) !== JSON.stringify(encodeProviderConfig(catalog))) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
+  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('请明确确认删除此供应商');
+        assertRemovable(matches[0]);
+        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 && matches[0].enabled !== false) assertProviderCredential(matches[0]);
+    if (matches.length !== 1 || !isConfiguredProvider(matches[0]) || !draft && !matches[0].models?.some(model => model.id === ref.modelId)) fail('请先配置并启用明确的工作流连接');
+    const provider = resolveProviderCredential(draft ? { ...matches[0], comfyWorkflow: checkedComfyWorkflow(input.comfyWorkflow) } : providerForImageModel(matches[0], ref.modelId, registry));
+    const scrub = createProviderSecretScrubber([matches[0], provider]);
+    if (provider.mediaProtocol !== 'comfyui') fail('此检查仅用于 ComfyUI 工作流');
+    const workflow = compileComfyWorkflow(provider.comfyWorkflow, { workflow_parameters: settings ? input.workflowParameters : input.workflow_parameters });
+    const network = networkFor(provider, settings ? input.modelRef : input.model_ref);
+    const inspect = () => inspectComfyWorkflow(createComfyUiClient(provider, network ? { fetchPort: network.fetch, network } : {}), workflow, { signal });
+    const report = await (network ? network.run(inspect, { operation: 'discover' }) : inspect());
+    signal?.throwIfAborted();
+    if (settingsRevision(loadProviderCatalog(configPath)) !== settingsRevision(catalog)) throw Object.assign(new Error('检查期间配置已变化，请重新检查'), { code: 'IRIS_CONFIG_CHANGED' });
+    return { ...scrub(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 && found[0].enabled !== false) assertProviderCredential(found[0]);
+      if (found.length !== 1 || !isConfiguredProvider(found[0])) fail('请先保存并启用有认证配置的连接');
+      const runtimeProvider = resolveProviderCredential(found[0]);
+      const discovered = await invokeProviderOperation(adapterFor(runtimeProvider), '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(providerApiKey(runtimeProvider) || '\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 +174,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 +188,10 @@ 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 createProviderSecretScrubber(catalog.providers)({
+    ...catalogCapabilitySnapshot(catalog, registry), assignments: assignmentSnapshot(catalog)
+  });
   let result = { command, changed: true };
   const initialPool = modelPool(catalog.providers);
   let provider;
@@ -100,7 +206,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     if (!value || typeof value !== 'object' || Array.isArray(value)) fail('需要 provider 对象');
     const id = text(value.id);
     if (command === 'providers.add' ? Boolean(provider) : !provider) fail(command === 'providers.add' ? 'Provider 已存在' : 'Provider 不存在');
-    const updated = { ...(provider || {}), ...value, id };
+    const updated = applyCredentialPatch(provider, { ...value, id });
     if (updated.visionInput !== undefined) updated.visionInput = normalizeVisionInputLimits(updated.visionInput) || null;
     let url;
     try { url = new URL(updated.baseUrl); } catch (_) { fail('baseUrl 必须是 HTTP(S) 地址'); }
@@ -113,13 +219,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');
         }
       }
@@ -129,6 +238,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     else catalog.providers.push(updated);
   } else if (command === 'providers.remove') {
     if (!provider) fail('Provider 不存在');
+    assertRemovable(provider);
     catalog.providers.splice(catalog.providers.indexOf(provider), 1);
   } else if (command.startsWith('models.')) {
     if (!provider) fail('Provider 不存在');
@@ -138,7 +248,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(adapterFor(provider), '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 +265,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 +276,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 +391,13 @@ 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, resolveProviderNetwork } = {}) {
+  if (resolveProviderNetwork !== undefined && typeof resolveProviderNetwork !== 'function') throw new TypeError('resolveProviderNetwork 必须是函数');
   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,
+      ...(resolveProviderNetwork ? { network: resolveProviderNetwork({ providerId: provider.id, provider, networkRequirement: providerNetworkRequirement(provider) }) } : {}), save: directory => {
       const fresh = loadProviderCatalog(configPath);
       const before = fs.readFileSync(configPath);
       const current = fresh.providers.find(item => item.id === provider.id);
@@ -310,7 +422,7 @@ function writeConfigChange(configPath, catalog, before, result, { backup = true
       fs.writeFileSync(backupPath, before, { flag: 'wx', mode: 0o600 });
       result.backupPath = backupPath;
     }
-    atomicWritePrivate(configPath, JSON.stringify(catalog, null, 2) + '\n');
+    atomicWritePrivate(configPath, JSON.stringify(encodeProviderConfig(catalog), null, 2) + '\n');
     return result;
   } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
 }

package/lib/provider-context.d.ts

@@ -0,0 +1,90 @@
+/** Provider author boundary v1; independent from Plugin/Adapter v0 and persistent Task formats. */
+export const PROVIDER_FACTORY_CONTEXT_VERSION: 1;
+export type ProviderCapability = 'image' | 'video' | 'tts' | 'music' | 'transcribe';
+export type ProviderMethod = 'discover' | 'submit' | 'poll' | 'cancel' | 'download' | 'mapError';
+export type ProviderAcceptance = 'not_accepted' | 'accepted' | 'unknown';
+export type ProviderStage = 'validate' | 'prepare' | 'upload' | 'submit' | 'response' | 'poll' | 'cancel' | 'download' | 'persist' | 'emit';
+export type ProviderErrorCategory = 'invalid_request' | 'authentication' | 'quota' | 'rate_limit' | 'network' | 'timeout' | 'aborted' | 'provider' | 'protocol' | 'local_io' | 'unknown';
+export interface ProviderErrorRecord {
+  readonly stage: ProviderStage;
+  readonly category: ProviderErrorCategory;
+  readonly acceptance: ProviderAcceptance;
+  readonly retryable: boolean;
+  readonly safeMessage: string;
+  readonly httpStatus?: number;
+  readonly providerCode?: string;
+}
+export interface ProviderNetwork {
+  /** Borrowed Core port: only inside an awaited lifecycle method, including all body reads and child requests. */
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface ProviderFactoryContext {
+  readonly contractVersion: 1;
+  readonly network: Readonly<ProviderNetwork>;
+  /** Selected raw model ID when Core is resolving an existing Task. */
+  readonly modelId?: string;
+}
+export interface ProviderConnection {
+  readonly id: string;
+  readonly baseUrl?: string;
+  readonly mediaBaseUrl?: string;
+  /** Runtime value resolved by Core. Never persist the connection or read another credential source. */
+  readonly apiKey?: string;
+  readonly auth?: string;
+  readonly [field: string]: unknown;
+}
+export interface ProviderOperationContext {
+  readonly signal?: AbortSignal;
+  readonly taskId?: string;
+  readonly attemptId?: string;
+  readonly modelRef?: string;
+  readonly providerId?: string;
+  readonly attempt?: Readonly<{ id: string; ordinal: number; providerId: string; model: string }>;
+}
+export interface ProviderImageInput { readonly bytes: Uint8Array; readonly mediaType: string; }
+export interface ProviderSubmitRequest {
+  readonly capability: ProviderCapability;
+  /** Raw supplier model ID, never providerId::modelId. */
+  readonly model: string;
+  readonly input: Readonly<Record<string, unknown> & { image?: ProviderImageInput }>;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export type ProviderArtifact = Readonly<{ kind: 'remote-url'; url: string; mediaType?: string }>
+  | Readonly<{ kind: 'inline-base64'; data: string; mediaType?: string }>;
+export type ProviderSubmissionResult = Readonly<{ kind: 'accepted'; remoteTaskId: string }>
+  | Readonly<{ kind: 'completed'; artifacts: readonly ProviderArtifact[]; value?: unknown }>
+  | Readonly<{ kind: 'not_accepted' | 'acceptance_unknown'; error: Error | Partial<ProviderErrorRecord> }>;
+export interface ProviderRemoteRequest {
+  readonly capability: ProviderCapability;
+  readonly remoteTaskId: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export type ProviderPollResult = Readonly<{ kind: 'pending'; progress?: string }>
+  | Readonly<{ kind: 'succeeded'; artifacts: readonly ProviderArtifact[]; value?: unknown }>
+  | Readonly<{ kind: 'failed' | 'canceled' | 'unknown'; error?: Error | Partial<ProviderErrorRecord>; message?: string }>;
+export type ProviderCancelResult = Readonly<{ kind: 'canceled' }>
+  | Readonly<{ kind: 'not_supported'; reason?: string }>
+  | Readonly<{ kind: 'unknown'; error?: Error | Partial<ProviderErrorRecord>; message?: string }>;
+export interface ProviderDownloadRequest {
+  readonly capability: ProviderCapability;
+  readonly artifact: ProviderArtifact;
+  /** Core-owned staging path; write only this new file, never Core metadata or another root. */
+  readonly targetPath: string;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+export interface ProviderDiscoveryRequest { readonly signal?: AbortSignal; readonly timeoutMs?: number; }
+export interface ProviderDiscoveryResult {
+  readonly models: readonly (string | Readonly<{ id: string; capabilities?: readonly string[] }>)[];
+}
+export interface ProviderOperations {
+  submit(request: ProviderSubmitRequest, context: ProviderOperationContext): ProviderSubmissionResult | Promise<ProviderSubmissionResult>;
+  /** Synchronous. The any input retains v0 identity mappers; returned records are normalized by Core. */
+  mapError(error: any, context: Partial<ProviderErrorRecord>): Error | Partial<ProviderErrorRecord> | undefined;
+  discover?(request: ProviderDiscoveryRequest, context: ProviderOperationContext): ProviderDiscoveryResult | Promise<ProviderDiscoveryResult>;
+  poll?(request: ProviderRemoteRequest, context: ProviderOperationContext): ProviderPollResult | Promise<ProviderPollResult>;
+  cancel?(request: ProviderRemoteRequest, context: ProviderOperationContext): ProviderCancelResult | Promise<ProviderCancelResult>;
+  download?(request: ProviderDownloadRequest, context: ProviderOperationContext): Readonly<{ bytes: number }> | Promise<Readonly<{ bytes: number }>>;
+}

package/lib/provider-context.js

@@ -0,0 +1,42 @@
+// Public author context, backed by Core-owned clients. No proxy/resource-management ports.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ProviderContractError } from './provider-contract.js';
+import { assertProviderNetwork } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+import { modelRef } from './models.js';
+
+export const PROVIDER_FACTORY_CONTEXT_VERSION = 1;
+const managed = new WeakSet();
+export function markProviderContextAdapter(adapter) { managed.add(adapter); return adapter; }
+export function hasProviderContext(adapter) { return managed.has(adapter); }
+
+/** Only the registry creates a context; callers borrow fetch for one awaited lifecycle method. */
+export function createProviderContext(provider, options, inheritedNetwork) {
+  if (options?.modelId !== undefined && typeof options.modelId !== 'string') throw new TypeError('Provider modelId 必须是字符串');
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!options?.network || !sameNetworkRequirement(requirement, options.network.networkRequirement)
+      || options.network.providerId !== provider.id)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '统一 Provider 需要原配置匹配的网络上下文，不会借用默认出口');
+  }
+  const network = assertProviderNetwork(options?.network === undefined ? inheritedNetwork() : options.network), scope = new AsyncLocalStorage();
+  const fetch = (...args) => {
+    if (!scope.getStore()?.active) {
+      throw Object.assign(new ProviderContractError('Provider 网络端口只可在当前完整生命周期方法内使用；请等待正文和子请求完成', {
+        stage: 'prepare', category: 'invalid_request', acceptance: 'not_accepted', providerCode: 'IRIS_PROVIDER_CONTEXT_OPERATION_REQUIRED'
+      }), { code: 'IRIS_PROVIDER_CONTEXT_OPERATION_REQUIRED' });
+    }
+    return network.fetch(...args);
+  };
+  const context = Object.freeze({ contractVersion: PROVIDER_FACTORY_CONTEXT_VERSION, network: Object.freeze({ fetch }),
+    ...(options?.modelId !== undefined ? { modelId: options.modelId } : {}) });
+  function invoke(name, action, args) {
+    const request = args[0], operation = { ...args[1], providerId: provider.id, operation: name };
+    if (!operation.modelRef && typeof request?.model === 'string') operation.modelRef = modelRef(provider.id, request.model);
+    return network.run(() => scope.run({ active: true }, async () => {
+      const current = scope.getStore();
+      try { return await action(...args); }
+      finally { current.active = false; }
+    }), operation);
+  }
+  return { context, invoke };
+}

package/lib/provider-credentials.js

@@ -0,0 +1,97 @@
+// Explicit process-environment references. Never mutate/persist resolved providers.
+import { ProviderContractError } from './provider-contract.js';
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+
+function validateEnvironmentCredential(provider) {
+  if (provider?.apiKeyEnv === undefined) return;
+  if (typeof provider.apiKeyEnv !== 'string' || !ENV_NAME.test(provider.apiKeyEnv)) {
+    fail('IRIS_CONFIG_INPUT_INVALID', 'apiKeyEnv 必须是最多128字符的环境变量名');
+  }
+  if (provider.apiKey !== undefined || provider.dshProvider !== undefined) {
+    fail('IRIS_CONFIG_INPUT_INVALID', '环境凭据引用不能与内联密钥或 DSH 连接引用同时保存');
+  }
+}
+
+/** Persistent sources remain exclusive; Host-resolved copies never pass this storage boundary. */
+export function validateProviderCredential(provider) {
+  for (const field of ['baseUrl', 'mediaBaseUrl', 'apiKey']) {
+    if (provider?.[field] !== undefined && typeof provider[field] !== 'string') {
+      fail('IRIS_CONFIG_INPUT_INVALID', field + ' 必须是字符串');
+    }
+  }
+  validateEnvironmentCredential(provider);
+  if (provider?.dshProvider !== undefined
+      && (['apiKey', 'apiKeyEnv', 'baseUrl'].some(field => provider[field] !== undefined)
+        || provider.mediaBaseUrl !== undefined && provider.mediaBaseUrl !== '')) {
+    fail('IRIS_CONFIG_INPUT_INVALID', 'DSH 连接引用不能同时保存内联密钥、环境引用或手动 Base URL（含媒体地址）；请新建手动供应商');
+  }
+}
+
+export function providerCredentialStatus(provider) {
+  if (provider?.apiKeyEnv === undefined) return typeof provider?.apiKey === 'string' && provider.apiKey.trim() ? 'ready' : 'missing';
+  const value = process.env[provider.apiKeyEnv];
+  if (typeof value !== 'string' || !value.trim()) return 'missing';
+  return value.length > 8192 || /[^\x20-\x7e]/.test(value) ? 'invalid' : 'ready';
+}
+
+/** Non-throwing for status/cache projections. Network boundaries assert readiness. */
+export function providerCredentialValue(provider) {
+  if (provider?.apiKeyEnv === undefined) return String(provider?.apiKey || '');
+  return providerCredentialStatus(provider) === 'ready' ? process.env[provider.apiKeyEnv].trim() : '';
+}
+
+export function assertProviderCredential(provider) {
+  // Runtime inputs may be ephemeral DSH copies with a resolved URL/key; stored sources were checked on read/write.
+  validateEnvironmentCredential(provider);
+  if (provider?.apiKeyEnv !== undefined && provider.auth !== 'none' && providerCredentialStatus(provider) !== 'ready') {
+    fail('IRIS_PROVIDER_CREDENTIAL_UNAVAILABLE', '环境凭据未就绪：请检查 Core 进程中的指定变量，值须为非空、最多8192字符的可打印 ASCII 文本');
+  }
+}
+
+/** An explicit source edit replaces the previous source, never two at once. */
+export function applyCredentialPatch(previous, patch) {
+  const next = { ...previous, ...patch };
+  if (Object.hasOwn(patch, 'apiKeyEnv') && !Object.hasOwn(patch, 'apiKey')) delete next.apiKey;
+  if (Object.hasOwn(patch, 'apiKey') && !Object.hasOwn(patch, 'apiKeyEnv')) delete next.apiKeyEnv;
+  validateProviderCredential(next);
+  return next;
+}
+
+/** Legacy/custom transports receive one call's key through their existing API. */
+export function resolveProviderCredential(provider) {
+  assertProviderCredential(provider);
+  if (provider.apiKeyEnv === undefined) return provider;
+  const { apiKeyEnv, ...runtime } = provider;
+  return { ...runtime, apiKey: provider.auth === 'none' ? '' : providerCredentialValue(provider) };
+}
+
+/** Capture explicitly configured sources once, including retained auth:none keys. */
+export function createProviderSecretScrubber(providers) {
+  const keys = providers.flatMap(provider => {
+    const raw = provider.apiKeyEnv === undefined ? provider.apiKey : process.env[provider.apiKeyEnv];
+    return typeof raw === 'string' && raw ? [...new Set([raw, raw.trim()].filter(Boolean))] : [];
+  }).sort((a, b) => b.length - a.length);
+  const scrub = item => typeof item === 'string' ? keys.reduce((text, key) => text.split(key).join('[redacted]'), item)
+    : Array.isArray(item) ? item.map(scrub) : item && typeof item === 'object'
+      ? Object.fromEntries(Object.entries(item).map(([key, entry]) => [scrub(key), scrub(entry)])) : item;
+  return scrub;
+}
+
+export function scrubProviderSecrets(value, providers) {
+  return createProviderSecretScrubber(providers)(value);
+}
+
+/** Discovery metadata is untrusted; never turn an echoed key into a model ID. */
+export function assertDiscoveryCredentials(value, key) {
+  const models = Array.isArray(value) ? value : value?.models;
+  if (!key || !Array.isArray(models)) return;
+  if (models.some(model => {
+    const id = String(typeof model === 'string' ? model : model?.id || '').trim();
+    return id.includes(key);
+  })) {
+    throw new ProviderContractError('模型目录包含认证内容，已拒绝读取与保存；请检查上游服务', {
+      stage: 'response', category: 'protocol', acceptance: 'not_accepted', providerCode: 'IRIS_PROVIDER_DIRECTORY_CREDENTIALS'
+    });
+  }
+}

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';
+import { providerCredentialStatus, scrubProviderSecrets } from './provider-credentials.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'
+        : provider.auth !== 'none' && provider.apiKeyEnv && providerCredentialStatus(provider) !== 'ready' ? 'credential_unavailable'
+          : !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 };
+  return scrubProviderSecrets(result, catalog.providers);
+}
+
+/** 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 });
+}