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

package/lib/operation-runner.js

@@ -13,6 +13,8 @@ import { acceptOperation, inspectExecutionRoot, operationId, readOperation, read
 import { reservePluginOperation } from './plugin-operations.js';
 import { invokeReservedPlugin } from './plugin-execution.js';
 import { acceptPluginOperation, pluginInputDigest, pluginSourceArtifacts, reservePluginArtifact } from './plugin-operation-store.js';
+import { readFlowRun } from './flow-store.js';
+import { findFlowTask } from './core-tasks.js';
 
 const activeState = record => ['queued', 'running'].includes(record.state);
 const busy = () => operationFail('IRIS_CORE_DATA_ROOT_BUSY', '当前写者正在执行，请用原 Key 稍后明确重试');
@@ -28,17 +30,20 @@ export function recoverExecutionLease(root, options) {
 }
 
 /** One execution owner, one finite continue per accepted Operation. Construction performs no I/O. */
-export function createOperationRunner({ dataRoot, application: suppliedApplication, resolveImageCandidates, resolveAudioCandidates, resolveTaskAdapter, onExecutionError,
+export function createOperationRunner({ dataRoot, application: suppliedApplication, resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter, onExecutionError,
   pluginRegistry, allowedOperations = [] } = {}) {
   const root = normalizeCoreOptions({ dataRoot }).dataRoot;
-  const application = suppliedApplication || createApplicationRuntime({ dataRoot: root, resolveImageCandidates, resolveAudioCandidates, resolveTaskAdapter });
-  const ports = { resolveImageCandidates, resolveAudioCandidates, resolveTaskAdapter };
+  const application = suppliedApplication || createApplicationRuntime({ dataRoot: root, resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter });
+  const ports = { resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, resolveTaskAdapter };
   if (onExecutionError !== undefined && typeof onExecutionError !== 'function') throw new TypeError('执行错误报告器须为函数');
-  const queue = [];
-  let state = 'new', physicalRoot, directory, ownership, lease, ownerInstanceId, active, draining, disposal, failure;
+  const queue = [], active = new Map(), finalizing = new Map();
+  const scheduled = Boolean(application.scheduler);
+  const transaction = (action, options) => application.transaction ? application.transaction(action, options) : application.run('writer', action);
+  let state = 'new', physicalRoot, directory, ownership, lease, ownerInstanceId, draining, disposal, failure, wake;
 
   function snapshot() {
-    return Object.freeze({ state, queued: queue.length, active: active?.id || null,
+    return Object.freeze({ state, queued: queue.length, active: active.keys().next().value || null,
+      ...(scheduled ? { activeOperations: [...active.keys()] } : {}),
       executionEnabled: state === 'open', failed: Boolean(failure) });
   }
   function requireOwner() {
@@ -53,20 +58,28 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
   }
   function failRunner(error) {
     failure ||= error; state = 'failed';
-    active?.controller.abort();
+    for (const job of active.values()) job.controller.abort();
   }
-  async function finishIfActive(id, terminal) {
-    return application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
+  function finishIfActive(id, terminal, failureCode) {
+    if (finalizing.has(id)) return finalizing.get(id);
+    const completion = transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
       requireOwner();
       const record = readOperation(dataRoot, id);
       if (!record || !activeState(record)) return record;
       if (record.ownerInstanceId !== ownerInstanceId) operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', 'Operation 不属于本次执行实例');
-      return transitionOperation(dataRoot, { id, expectedRevision: record.revision, state: terminal });
-    }));
+      return transitionOperation(dataRoot, { id, expectedRevision: record.revision, state: terminal,
+        ...(failureCode ? { failureCode } : {}) });
+    }), { finalize: true }).finally(() => { finalizing.delete(id); });
+    finalizing.set(id, completion);
+    return completion;
   }
   async function perform(job) {
+    let admitted = false;
     try {
-      await application.run('writer', runtime => runtime.run('execute', async ({ dataRoot }) => {
+      const saved = readOperation(physicalRoot, job.id);
+      job.runId = saved?.runId;
+      const execute = saved?.action === 'flow.continue' && application.runMedia ? application.runMedia : (action, options) => application.run('writer', action, options);
+      await execute(runtime => { admitted = true; return runtime.run('execute', async ({ dataRoot }) => {
         requireOwner();
         let record = readOperation(dataRoot, job.id);
         if (!record || !activeState(record)) return;
@@ -107,28 +120,39 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
           state: job.stopReason || (executionError ? 'failed' : 'succeeded'),
           ...(executionError && !job.stopReason ? { failureCode: 'execution_failed' } : {}) });
         if (executionError && !job.stopReason) onExecutionError?.(executionError, job.id);
-      }), { signal: job.controller.signal });
+      }); }, { signal: job.controller.signal, ...(saved?.runId ? { key: `run:${saved.runId}` } : {}) });
     } catch (error) {
       if (job.stopReason && error.name === 'AbortError' && !application.snapshot().cleanupFailed) {
         await finishIfActive(job.id, job.stopReason);
+      } else if (scheduled && !admitted && !application.snapshot().cleanupFailed
+          && ['IRIS_SCHEDULER_QUEUE_TIMEOUT', 'IRIS_SCHEDULER_QUEUE_FULL'].includes(error.code)) {
+        await finishIfActive(job.id, job.stopReason || 'failed', job.stopReason ? undefined : 'execution_failed');
+        if (!job.stopReason) onExecutionError?.(error, job.id);
       } else throw error;
     }
   }
   function pump() {
-    if (draining || state !== 'open') return;
+    if (draining) { wake?.(); return; }
+    if (state !== 'open') return;
+    let blocked = false;
     draining = (async () => {
-      while (state === 'open' && queue.length) {
-        active = queue.shift();
-        active.done = perform(active);
-        try { await active.done; }
-        catch (error) {
-          if (error.code !== 'IRIS_CORE_DATA_ROOT_BUSY') throw error;
-          queue.unshift(active); active = null; break; // No timer or lease stealing; explicit retry wakes this queue.
+      while ((state === 'open' && queue.length && !blocked) || active.size) {
+        while (state === 'open' && queue.length && !blocked && active.size < (scheduled ? MAX_ACTIVE_OPERATIONS : 1)) {
+          const job = queue.shift(); active.set(job.id, job);
+          job.done = perform(job).catch(error => {
+            if (error.code !== 'IRIS_CORE_DATA_ROOT_BUSY') throw error;
+            queue.unshift(job); blocked = true; // Explicit retry only; no lease stealing or polling timer.
+          }).finally(() => { active.delete(job.id); });
+        }
+        if (active.size) {
+          const added = new Promise(resolve => { wake = resolve; });
+          await Promise.race([...active.values()].map(job => job.done).concat(added));
+          wake = null;
         }
-        active = null;
       }
     })();
-    void draining.then(() => { draining = null; }, error => { draining = null; failRunner(error); });
+    void draining.then(() => { draining = null; if (state === 'open' && queue.length && !blocked) queueMicrotask(pump); },
+      error => { draining = null; failRunner(error); });
   }
   async function start() {
     if (state !== 'new') operationFail('IRIS_EXECUTION_LIFECYCLE', '执行服务只能显式启动一次');
@@ -138,7 +162,7 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
       lease = createCoreRuntime({ dataRoot: directory, mode: 'writer' }); lease.start();
       ownership = inspectRunnerArea(directory); ownerInstanceId = ownership.owner.instanceId;
       state = 'open';
-      await application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
+      await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
         requireOwner();
         for (const record of readAllOperations(dataRoot).filter(activeState)) {
           transitionOperation(dataRoot, { id: record.id, expectedRevision: record.revision, state: 'interrupted' });
@@ -163,19 +187,27 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
         if (previous.state === 'queued' && previous.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
         return { contractVersion: 0, operation: projectOperation(previous), idempotentReplay: true };
       }
-      if (application.snapshot().activeWrites || application.snapshot().queuedWrites) busy();
+      if (!scheduled && (application.snapshot().activeWrites || application.snapshot().queuedWrites)) busy();
       const reservation = reservePluginOperation(pluginRegistry, input.operationId, input.input, allowedOperations, input.dependency);
-      let record;
+      let record, replay = false;
       try {
-        record = await application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
+        record = await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
           writable(); authorize?.();
-          if (readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS) operationFail('IRIS_OPERATION_QUEUE_FULL', '未结束的 Operation 已达上限');
+          const current = readOperation(dataRoot, id, marker);
+          if (current) {
+            if (current.action !== 'plugin.execute' || current.inputDigest !== pluginInputDigest(input.operationId, input.input, input.dependency, current.sourceArtifactIds)) {
+              operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定另一业务或输入');
+            }
+            replay = true; return current;
+          }
+          if (readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS - Number(scheduled)) operationFail('IRIS_OPERATION_QUEUE_FULL', '未结束的 Operation 已达上限；调度模式保留一个位置供原任务恢复');
           return acceptPluginOperation(dataRoot, marker, id, { ...input, input: reservation.input,
             sourceArtifactIds: pluginSourceArtifacts(reservation.input, reservation.artifactInputs), ownerInstanceId });
         }));
       } finally { reservation.release(); }
-      queue.push({ id, controller: new AbortController(), stopReason: null, authorize }); queueMicrotask(pump);
-      return { contractVersion: 0, operation: projectOperation(record), idempotentReplay: false };
+      if (!replay) queue.push({ id, controller: new AbortController(), stopReason: null, authorize });
+      if (!replay || record.state === 'queued' && record.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
+      return { contractVersion: 0, operation: projectOperation(record), idempotentReplay: replay };
     }
     if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 3
         || !['key', 'runId', 'expectedRunRevision'].every(key => Object.hasOwn(input, key))) {
@@ -190,9 +222,14 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
       if (previous.state === 'queued' && previous.ownerInstanceId === ownerInstanceId) queueMicrotask(pump);
       return { contractVersion: 0, operation: projectOperation(previous), idempotentReplay: true };
     }
-    if (application.snapshot().activeWrites || application.snapshot().queuedWrites) busy();
-    const accepted = await application.run('writer', runtime => runtime.run('execute', ({ dataRoot }) => {
-      writable(); return acceptOperation(dataRoot, { ...input, ownerInstanceId });
+    if (!scheduled && (application.snapshot().activeWrites || application.snapshot().queuedWrites)) busy();
+    const accepted = await transaction(runtime => runtime.run('execute', ({ dataRoot }) => {
+      writable();
+      if (scheduled && !readOperation(dataRoot, id) && readAllOperations(dataRoot).filter(activeState).length >= MAX_ACTIVE_OPERATIONS - 1
+          && !findFlowTask(dataRoot, readFlowRun(dataRoot, input.runId))?.attempts.length) {
+        operationFail('IRIS_OPERATION_QUEUE_FULL', '新提交队列已满；保留一个位置用于原任务查询和交付');
+      }
+      return acceptOperation(dataRoot, { ...input, ownerInstanceId });
     }));
     if (!accepted.idempotentReplay) {
       queue.push({ id: accepted.operation.id, controller: new AbortController(), stopReason: null });
@@ -206,10 +243,14 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
     if (!record) operationFail('IRIS_OPERATION_NOT_FOUND', 'Operation 不存在');
     if (activeState(record)) {
       if (record.ownerInstanceId !== ownerInstanceId) operationFail('IRIS_EXECUTION_OWNERSHIP_LOST', '不能停止另一执行实例的操作');
-      const job = active?.id === id ? active : queue.find(job => job.id === id);
+      const job = active.get(id) || queue.find(job => job.id === id);
       if (job) { job.stopReason = 'canceled'; job.controller.abort(); }
-      if (active?.id === id) await job.done;
-      else await finishIfActive(id, 'canceled');
+      if (active.has(id)) await job.done;
+      else {
+        await finishIfActive(id, 'canceled');
+        const index = queue.indexOf(job);
+        if (index >= 0) queue.splice(index, 1);
+      }
     }
     const saved = readOperation(physicalRoot, id);
     if (activeState(saved)) operationFail('IRIS_EXECUTION_STOP_UNSAVED', '停止尚未持久保存，请查询原 Operation');
@@ -222,7 +263,7 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
     if (state === 'new') { state = 'closed'; return disposal = suppliedApplication ? Promise.resolve(snapshot()) : application.dispose().then(snapshot); }
     if (state === 'closed') return Promise.resolve(snapshot());
     if (state !== 'failed') state = 'closing';
-    if (active) { active.stopReason ||= 'interrupted'; active.controller.abort(); }
+    for (const job of active.values()) { job.stopReason ||= 'interrupted'; job.controller.abort(); }
     disposal = (async () => {
       if (draining) await draining;
       if (failure) throw failure;
@@ -232,5 +273,9 @@ export function createOperationRunner({ dataRoot, application: suppliedApplicati
     })();
     return disposal;
   }
-  return Object.freeze({ start, submit, stop, idle, dispose, snapshot });
+  return Object.freeze({ start, submit, stop, idle, dispose, snapshot,
+    scheduling(id) {
+      const job = active.get(id), phase = job?.runId && application.schedulingPhase(`run:${job.runId}`);
+      return scheduled && phase ? { phase } : undefined;
+    } });
 }

package/lib/operation-store.js

@@ -34,11 +34,11 @@ function input(value, allowed, required = allowed) {
 }
 export function inspectExecutionRoot(root) {
   const marker = inspectLocalRequestRoot(root, { allowAbsent: true });
-  if (![1, 2, 3].includes(marker?.schemaVersion)) operationFail('IRIS_OPERATION_ROOT_REQUIRED', 'Operation 需要新的专用执行根，请显式执行 execution init；不转换原根');
+  if (![1, 2, 3, 4].includes(marker?.schemaVersion)) operationFail('IRIS_OPERATION_ROOT_REQUIRED', 'Operation 需要新的专用执行根，请显式执行 execution init；不转换原根');
   return marker;
 }
-export function initializeExecutionRoot(root, { imageGeneration = false, audio = false } = {}) {
-  const marker = initializeLocalRequestRoot(root, audio ? 3 : imageGeneration ? 2 : 1);
+export function initializeExecutionRoot(root, { imageGeneration = false, audio = false, video = false } = {}) {
+  const marker = initializeLocalRequestRoot(root, video ? 4 : audio ? 3 : imageGeneration ? 2 : 1);
   listCreationRequests(root); readAllOperations(root);
   return marker;
 }
@@ -64,7 +64,7 @@ function validate(record, id, marker) {
       || !UUID.test(record.ownerInstanceId) || !STATES.has(record.state) || typeof record.cancelRequested !== 'boolean'
       || !iso(record.createdAt) || !iso(record.updatedAt) || record.updatedAt < record.createdAt
       || !keys(record.binding, ['taskId', 'sourceArtifactId', 'comparisonArtifactId', 'inputDigest'])
-      || !TASK.test(record.binding.taskId) || !(marker.schemaVersion === 3 && (record.binding.sourceArtifactId === null || ARTIFACT.test(record.binding.sourceArtifactId))
+      || !TASK.test(record.binding.taskId) || !([3, 4].includes(marker.schemaVersion) && (record.binding.sourceArtifactId === null || ARTIFACT.test(record.binding.sourceArtifactId))
         && (record.binding.comparisonArtifactId === null || ARTIFACT.test(record.binding.comparisonArtifactId))
         || record.binding.sourceArtifactId === null && record.binding.comparisonArtifactId === null && marker.schemaVersion === 2
         || ARTIFACT.test(record.binding.sourceArtifactId) && ARTIFACT.test(record.binding.comparisonArtifactId))
@@ -76,7 +76,7 @@ function validate(record, id, marker) {
       || record.state === 'running' && (!hasStarted || record.cancelRequested)
       || record.state === 'succeeded' && (!hasStarted || record.cancelRequested)
       || record.cancelRequested !== (record.state === 'canceled')
-      || record.state === 'failed' && (!FAILURE_CODES.has(record.failureCode) || !hasStarted && record.failureCode !== 'run_changed')
+      || record.state === 'failed' && !FAILURE_CODES.has(record.failureCode)
       || record.state !== 'failed' && Object.hasOwn(record, 'failureCode')) invalid();
   if (ACTIVE.has(record.state)) {
     if (Object.hasOwn(record, 'finishedAt') || Object.hasOwn(record, 'result')) invalid();
@@ -172,7 +172,7 @@ export function transitionOperation(root, value) {
   const allowed = current.state === 'queued' ? ['running', 'canceled', 'interrupted', 'failed']
     : current.state === 'running' ? ['succeeded', 'failed', 'canceled', 'interrupted'] : [];
   if (!allowed.includes(value.state)) operationFail('IRIS_OPERATION_TRANSITION_INVALID', '不允许此 Operation 状态转换；结束记录不重新排队');
-  if (value.state === 'failed' ? !FAILURE_CODES.has(value.failureCode) || current.state === 'queued' && value.failureCode !== 'run_changed'
+  if (value.state === 'failed' ? !FAILURE_CODES.has(value.failureCode)
     : Object.hasOwn(value, 'failureCode')) operationFail('IRIS_OPERATION_INPUT_INVALID', '失败记录只接受有限错误类别，不保存异常原文');
   const { run, task } = validateBinding(root, current);
   if (value.state === 'running' && run.revision !== current.expectedRunRevision) operationFail('IRIS_OPERATION_RUN_CHANGED', 'Run revision 已改变，未开始本次调用');

package/lib/plugins.d.ts

@@ -1,4 +1,23 @@
 /** Experimental v0. Trusted local code; no sandbox, discovery, installation or implicit grant. */
+import type { ProviderCapability, ProviderMethod, ProviderOperations, ProviderConnection, ProviderFactoryContext, ProviderErrorRecord } from './provider-context.js';
+export { PROVIDER_FACTORY_CONTEXT_VERSION } from './provider-context.js';
+export type { ProviderCapability, ProviderMethod, ProviderOperations, ProviderConnection, ProviderFactoryContext, ProviderNetwork,
+  ProviderErrorRecord, ProviderStage, ProviderAcceptance, ProviderErrorCategory, ProviderOperationContext, ProviderSubmitRequest,
+  ProviderSubmissionResult, ProviderRemoteRequest, ProviderPollResult, ProviderCancelResult, ProviderDownloadRequest,
+  ProviderDiscoveryRequest, ProviderDiscoveryResult, ProviderArtifact, ProviderImageInput } from './provider-context.js';
+export class ProviderContractError extends Error {
+  constructor(message: string, details?: Partial<ProviderErrorRecord>);
+  readonly stage: ProviderErrorRecord['stage'];
+  readonly category: ProviderErrorRecord['category'];
+  readonly acceptance: ProviderErrorRecord['acceptance'];
+  readonly retryable: boolean;
+  readonly safeMessage: string;
+  readonly httpStatus?: number;
+  readonly providerCode?: string;
+  /** Optional transient transport hint, read by Core health before error persistence. */
+  retryAfterMs?: number;
+  toJSON(): ProviderErrorRecord;
+}
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
 export type PluginKind = 'providers' | 'operations' | 'pages' | 'renderers' | 'settings';
 export const PLUGIN_CONTRACT_VERSION: 0;
@@ -60,11 +79,9 @@ export interface PluginOperationContext {
   readonly core: { execute(command: PluginCoreCommand, input: Record<string, unknown>): Promise<unknown> };
 }
 export type PluginOperation = (input: Readonly<Record<string, JsonValue>>, context: PluginOperationContext) => JsonValue | Promise<JsonValue>;
-export type ProviderCapability = 'image' | 'video' | 'tts' | 'music' | 'transcribe';
-export type ProviderMethod = 'discover' | 'submit' | 'poll' | 'cancel' | 'download' | 'mapError';
 export interface ProviderAdapterInput {
   id: string; protocol: string; capabilities: ProviderCapability[]; contractVersion?: 0;
-  operations: Partial<Record<ProviderMethod, (...args: any[]) => unknown>>;
+  operations: ProviderOperations;
   unsupported?: Partial<Record<ProviderMethod, string>>;
   prepareInput?: (...args: any[]) => unknown;
   unsupportedPreparation?: string;
@@ -73,14 +90,14 @@ export interface ProviderAdapterInput {
 export type ProviderAdapter = Readonly<Omit<ProviderAdapterInput, 'contractVersion' | 'capabilities' | 'operations' | 'unsupported'> & {
   contractVersion: 0;
   capabilities: readonly ProviderCapability[];
-  operations: Readonly<Partial<Record<ProviderMethod, (...args: any[]) => unknown>>>;
+  operations: Readonly<ProviderOperations>;
   unsupported: Readonly<Partial<Record<ProviderMethod, { readonly reason: string }>>>;
 }>;
 export function defineProviderAdapter(input: ProviderAdapterInput): ProviderAdapter;
 export function normalizeMediaEndpoint(value: string): string;
 export interface ProviderImplementation {
   normalizeEndpoint(value: string): string;
-  createAdapter(provider: Record<string, any>, options?: Record<string, any>): ProviderAdapter;
+  createAdapter(provider: Readonly<ProviderConnection>, context: Readonly<ProviderFactoryContext>): ProviderAdapter;
   supportsModel?(input: { provider: Record<string, unknown>; modelId: string; capability: string; checkEndpoint?: boolean }): boolean;
   supportsImageEdit?(modelId: string): boolean;
 }
@@ -161,7 +178,7 @@ export interface CoreCapabilitySnapshot {
   };
 }
 export interface CoreCapabilityCatalog {
-  snapshot(options?: { audioEnabled?: boolean; panelContributions?: PluginPanelSelection; allowedOperations?: readonly string[] }): CoreCapabilitySnapshot;
+  snapshot(options?: { audioEnabled?: boolean; videoEnabled?: boolean; panelContributions?: PluginPanelSelection; allowedOperations?: readonly string[] }): CoreCapabilitySnapshot;
   /** Validate an explicit local selection. Does not invoke, persist a grant or enable MCP/Web. */
   selectOperations(ids?: readonly string[]): readonly (OperationContribution & CatalogContribution)[];
 }
@@ -219,6 +236,7 @@ export interface PluginWebSession {
   readonly operations: readonly string[];
   readonly readOnly: boolean;
   readonly audio: boolean;
+  readonly video: boolean;
   readonly providerManagement: boolean;
   readonly pluginExecution: boolean;
   readonly pluginOperations: readonly PluginDependency[];
@@ -256,6 +274,7 @@ export interface PluginWebApi {
   run(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
   models(options?: PluginWebRequestOptions): Promise<JsonValue>;
   audioModels(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  videoModels(options?: PluginWebRequestOptions): Promise<JsonValue>;
   artifact(artifact: PluginArtifact, options?: PluginWebRequestOptions): Promise<Blob>;
   /** Only settings mounts in an explicitly enabled owner Provider-management session. */
   readonly providers?: {

package/lib/plugins.js

@@ -13,7 +13,8 @@ export { createCoreCapabilityCatalog } from './core-capability-catalog.js';
 
 export { definePlugin, PluginContractError, PLUGIN_CONTRACT_VERSION, PLUGIN_KINDS, PLUGIN_CORE_COMMANDS,
   checkedPluginDependency, comparePluginVersions } from './plugin-contract.js';
-export { defineProviderAdapter, normalizeMediaEndpoint } from './provider-extensions.js';
+export { defineProviderAdapter, ProviderContractError, normalizeMediaEndpoint } from './provider-extensions.js';
+export { PROVIDER_FACTORY_CONTEXT_VERSION } from './provider-context.js';
 
 export function createCorePluginRegistry({ plugins = [], coreVersion } = {}) {
   coreVersion ??= JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/lib/provider-adapter.js

@@ -196,7 +196,7 @@ export function providerAdapterSnapshot(adapter) {
 }
 
 /** 提交前的可选上传能力；不创建 Task，也不属于六个生命周期操作。 */
-export async function prepareProviderInput(adapter, input = {}) {
+export async function prepareProviderInput(adapter, input = {}, operationContext = {}) {
   if (typeof adapter?.prepareInput !== 'function') {
     const error = new ProviderContractError(adapter?.unsupportedPreparation || '协议未实现临时输入上传', {
       stage: 'upload', category: 'invalid_request', acceptance: 'not_accepted',
@@ -206,7 +206,7 @@ export async function prepareProviderInput(adapter, input = {}) {
     throw error;
   }
   try {
-    const value = await adapter.prepareInput(input);
+    const value = await adapter.prepareInput(input, operationContext);
     if (typeof value?.url !== 'string' || !value.url.trim()) {
       throw new ProviderContractError('Provider 输入准备必须返回非空 url', {
         stage: 'upload', category: 'protocol', acceptance: 'not_accepted'

package/lib/provider-adapters.js

@@ -16,6 +16,11 @@ import { modelUnavailable, modelUnavailableReason, modelAvailabilityBinding } fr
 import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
 import { createComfyUiProviderAdapter } from './comfyui-adapter.js';
 import { PROVIDER_RESPONSE_LIMITS } from './provider-response.js';
+import { resolveProviderCredential, assertDiscoveryCredentials } from './provider-credentials.js';
+import { assertProviderNetwork } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
+import { createProviderTransport } from './provider-transport.js';
+import { hasProviderContext } from './provider-context.js';
 
 const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
 
@@ -449,15 +454,33 @@ export function builtinProviderExtension() {
 }
 
 export function createConfiguredProviderAdapter(provider, options = {}) {
+  const network = options.network === undefined ? undefined : assertProviderNetwork(options.network);
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || network.providerId !== provider.id)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '此供应商需要匹配的显式网络上下文，不会静默使用默认出口');
+  }
+  if (network && (options.transport !== undefined || options.fetchPort !== undefined)) {
+    throw new TypeError('network 不能与显式 transport 或 fetchPort 同时配置');
+  }
+  const factoryOptions = network ? { ...options, transport: createProviderTransport(network.fetch), fetchPort: network.fetch } : options;
+  provider = resolveProviderCredential(provider);
   const selection = options.protocol
     ? selectMediaProtocol({ ...provider, mediaProtocol: options.protocol, protocolInferred: false })
     : selectMediaProtocol(provider);
   const factory = Object.hasOwn(PROTOCOL_FACTORIES, selection.mediaProtocol) ? PROTOCOL_FACTORIES[selection.mediaProtocol] : null;
   if (!options.registry && !factory) throw unsupportedProtocolError(selection.mediaProtocol);
-  const adapter = options.registry ? options.registry.createAdapter(selection.mediaProtocol, provider, options) : factory(provider, options);
+  const adapter = options.registry ? options.registry.createAdapter(selection.mediaProtocol, provider, factoryOptions) : factory(provider, factoryOptions);
   const operations = { ...adapter.operations };
   const key = providerApiKey(provider);
   const scrub = value => typeof value === 'string' && key ? value.split(key).join('[REDACTED]') : value;
+  if (operations.discover) {
+    const discover = operations.discover;
+    operations.discover = async (...args) => {
+      const result = await discover(...args);
+      assertDiscoveryCredentials(result, key);
+      return result;
+    };
+  }
   operations.mapError = (error, context) => {
     let mapped;
     try { mapped = adapter.operations.mapError(error, context); } catch (failure) { mapped = failure; }
@@ -475,7 +498,7 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
   for (const name of ['submit', 'poll']) {
     if (!operations[name]) continue;
     const run = operations[name];
-    operations[name] = async request => {
+    operations[name] = async (request, context) => {
       const modelId = request.model || options.modelId;
       const report = error => reportModelRateLimit(provider, modelId, {
         httpStatus: error.httpStatus ?? error.status, category: error.category,
@@ -502,12 +525,12 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
       }
       if (name === 'submit' && !options.allowRateLimited && modelRateLimit(provider, modelId)) {
         const blocked = modelRateLimit(provider, modelId);
-        throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
+        if (!(options.deferCooling && blocked.until)) throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
           stage: 'validate', category: 'rate_limit', acceptance: 'not_accepted'
         });
       }
       try {
-        const result = await run(request);
+        const result = await run(request, context);
         if (result.error) report(result.error);
         availability(result.error || { ok: ['completed', 'accepted'].includes(result.kind) });
         return result;
@@ -518,5 +541,14 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
       }
     };
   }
-  return Object.freeze({ ...adapter, operations: Object.freeze(operations) });
+  if (network && !hasProviderContext(adapter)) {
+    for (const name of Object.keys(operations)) {
+      if (name === 'mapError') continue;
+      const operation = operations[name];
+      operations[name] = (...args) => network.run(() => operation(...args), { ...args[1], operation: name });
+    }
+  }
+  return Object.freeze({ ...adapter, ...(requirement ? { networkRequirement: requirement } : {}), operations: Object.freeze(operations),
+    ...(options.deferCooling ? { schedulingReadyAt: modelId => Date.parse(modelRateLimit(provider, modelId)?.until || '') || 0 } : {}),
+    ...(network && !hasProviderContext(adapter) && adapter.prepareInput ? { prepareInput: (...args) => network.run(() => adapter.prepareInput(...args), { ...args[1], operation: 'prepareInput' }) } : {}) });
 }

package/lib/provider-catalog.js

@@ -12,6 +12,8 @@ import { normalizeVisionInputLimits } from './vision-image-input.js';
 import { modelDirectorySummary, modelUnavailableReason, validateModelDirectory } from './model-directory.js';
 import { checkedComfyWorkflow, comfyWorkflowDigest } from './comfyui-workflow.js';
 import { assertPluginDependencyMatches } from './plugin-contract.js';
+import { validateProviderCredential, assertProviderCredential, providerCredentialStatus, createProviderSecretScrubber } from './provider-credentials.js';
+import { decodeProviderConfig } from './provider-config-format.js';
 
 export class ProviderCatalogError extends Error {
   constructor(code, message) {
@@ -46,6 +48,7 @@ export function loadProviderCatalog(configPath) {
   let parsed;
   try { parsed = JSON.parse(source); }
   catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'provider-config 不是有效 JSON'); }
+  parsed = decodeProviderConfig(parsed);
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
       || !Array.isArray(parsed.providers)
       || (parsed.assignments !== undefined && (!parsed.assignments || typeof parsed.assignments !== 'object'
@@ -54,6 +57,7 @@ export function loadProviderCatalog(configPath) {
   }
   for (const [capability, assignment] of Object.entries(parsed.assignments || {})) functionPolicy(assignment, capability);
   for (const provider of parsed.providers) {
+    validateProviderCredential(provider);
     validateModelDirectory(provider.modelDirectory);
     for (const model of provider.models || []) if (model?.comfyWorkflow !== undefined) checkedComfyWorkflow(model.comfyWorkflow);
   }
@@ -67,9 +71,14 @@ const CANDIDATE_CAP_LABEL = Object.freeze({
 });
 
 /** 与 DSH 共用功能策略；CLI 不附加宿主资源。 */
-function candidatesFromCatalog(catalog, requestedModelRef, capability, registry) {
+function candidatesFromCatalog(catalog, requestedModelRef, capability, registry, { deferCooling = false } = {}) {
   const label = CANDIDATE_CAP_LABEL[capability];
   if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
+  const requestedProvider = parseModelRef(String(requestedModelRef || '').trim())?.providerId;
+  if (requestedProvider) {
+    const provider = catalog.providers.find(item => item.id === requestedProvider && item.enabled !== false);
+    if (provider) assertProviderCredential(provider);
+  }
   const providers = catalog.providers.filter(isConfiguredProvider);
   const configuredPool = functionModelPool(providers, capability, catalog.assignments?.[capability], { registry });
   const pool = orderedModels(configuredPool, capability, catalog.assignments?.[capability], { includeRateLimited: true, includeUnavailable: true });
@@ -81,7 +90,7 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability, registry)
     if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型未分配给${label}功能、未启用或没有所需能力`);
     const provider = providers.find((item) => item.id === exact.providerId);
     if (exact.unavailableCapabilities?.includes(capability)) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', modelUnavailableReason());
-    if (exact.rateLimited) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
+    if (exact.rateLimited && !(deferCooling && modelRateLimit(provider, exact.id)?.until)) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
       ? '指定模型正在限流冷却，请稍后使用或手动实测'
       : '指定模型额度或预算耗尽，请手动实测成功后再使用');
     return Object.freeze([Object.freeze({
@@ -90,8 +99,14 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability, registry)
     })]);
   }
   const assignment = catalog.assignments?.[capability];
-  const ordered = pool.filter(model => !model.rateLimited && !model.unavailableCapabilities?.includes(capability));
-  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `请检查${label}功能的启用方式、已确认模型、连接和协议；当前没有可用候选`);
+  const ordered = pool.filter(model => (!model.rateLimited || deferCooling && modelRateLimit(providers.find(provider => provider.id === model.providerId), model.id)?.until)
+    && !model.unavailableCapabilities?.includes(capability));
+  if (!ordered.length) {
+    const missing = catalog.providers.find(provider => provider.enabled !== false && provider.auth !== 'none' && provider.apiKeyEnv
+      && providerCredentialStatus(provider) !== 'ready' && providerModels(provider).some(model => model.capabilities.includes(capability)));
+    if (missing) assertProviderCredential(missing);
+    fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `请检查${label}功能的启用方式、已确认模型、连接和协议；当前没有可用候选`);
+  }
   return Object.freeze(ordered.map((item) => Object.freeze({
     provider: providers.find((provider) => provider.id === item.providerId),
     model: item.id,
@@ -100,17 +115,17 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability, registry)
   })));
 }
 
-export function imageCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
-  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE, registry).map(route =>
+export function imageCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE, registry, options).map(route =>
     Object.freeze({ ...route, provider: providerForImageModel(route.provider, route.model, registry) })));
 }
 
-export function videoCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO, registry);
+export function videoCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VIDEO, registry, options);
 }
 
-export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS, registry);
+export function ttsCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TTS, registry, options);
 }
 
 export function musicCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
@@ -118,8 +133,8 @@ export function musicCandidatesFromCatalog(catalog, requestedModelRef = '', regi
     Object.freeze({ ...route, provider: providerForMusicModel(route.provider, route.model, registry) })));
 }
 
-export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE, registry);
+export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '', registry, options) {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE, registry, options);
 }
 
 export function visionCandidatesFromCatalog(catalog, requestedModelRef = '', registry) {
@@ -128,9 +143,10 @@ export function visionCandidatesFromCatalog(catalog, requestedModelRef = '', reg
 
 /** 只读配置投影；不构造 Adapter、不发现模型、不暴露端点或凭据。 */
 export function providerCatalogSnapshot(catalog) {
+  const scrub = createProviderSecretScrubber(catalog.providers);
   const safeLabel = (value) => value
-    ? redactProviderMessage(String(value).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
-  return {
+    ? redactProviderMessage(String(scrub(value)).replace(/https?:\/\/[^\s<>"']+/gi, '[URL]')) : '';
+  return scrub({
     schemaVersion: 1,
     providers: catalog.providers.filter((provider) => provider && typeof provider === 'object').map((provider) => {
       const models = providerModels(provider);
@@ -145,7 +161,7 @@ export function providerCatalogSnapshot(catalog) {
         modelCount: models.length, directory: modelDirectorySummary(provider)
       };
     })
-  };
+  });
 }
 
 export function catalogCapabilitySnapshot(catalog, registry) {
@@ -196,7 +212,8 @@ export function providerForTaskFromCatalog(catalog, task, registry) {
   const matches = catalog.providers.filter((item) => item && item.id === task.providerId);
   if (matches.length > 1) fail('IRIS_PROVIDER_CONFIG_AMBIGUOUS', 'provider-config 存在重复 Provider ID');
   const configured = matches[0];
-  if (!configured || configured.enabled === false || (configured.auth !== 'none' && (typeof configured.apiKey !== 'string' || !configured.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  if (configured && configured.enabled !== false) assertProviderCredential(configured);
+  if (!configured || configured.enabled === false || (configured.auth !== 'none' && providerCredentialStatus(configured) !== 'ready')) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
   const provider = task.capability === 'image' ? providerForImageModel(configured, parsed.modelId, registry)
     : task.capability === 'music' ? providerForMusicModel(configured, parsed.modelId, registry) : configured;
   assertPluginDependencyMatches(task.pluginDependency, providerProtocolDescriptor(selectMediaProtocol(provider).mediaProtocol, registry)?.dependency);