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

package/lib/local-web-assets.js

@@ -12,10 +12,12 @@ const ASSETS = new Map([
   ['/creation.js', ['creation.js', 'text/javascript; charset=utf-8']],
   ['/gallery.js', ['gallery.js', 'text/javascript; charset=utf-8']],
   ['/plugin-panel.js', ['plugin-panel.js', 'text/javascript; charset=utf-8']],
+  ['/plugin-status.js', ['plugin-status.js', 'text/javascript; charset=utf-8']],
   ['/plugin-surface.css', ['plugin-surface.css', 'text/css; charset=utf-8']],
   ['/flow-view.js', ['flow-view.js', 'text/javascript; charset=utf-8']],
   ['/connections.js', ['connections.js', 'text/javascript; charset=utf-8']],
   ['/providers.js', ['providers.js', 'text/javascript; charset=utf-8']],
+  ['/network.js', ['network.js', 'text/javascript; charset=utf-8']],
   ['/comfyui.js', ['comfyui.js', 'text/javascript; charset=utf-8']],
   ['/appearance.js', ['appearance.js', 'text/javascript; charset=utf-8']],
   ['/styles.css', ['styles.css', 'text/css; charset=utf-8']],

package/lib/mcp-http.js

@@ -4,10 +4,47 @@ import { createCoreServiceClient } from './core-service-client.js';
 import { createMcpServerFactory, reportMcpClientInfo } from './mcp-server.js';
 import { projectedMcpClient } from './core-connections.js';
 
+const MAX_REQUEST_BYTES = 9 * 1024 * 1024, MAX_ACTIVE_MESSAGES = 4;
+
+async function readBody(request) {
+  if (Number(request.headers['content-length']) > MAX_REQUEST_BYTES) return { tooLarge: true };
+  const chunks = []; let size = 0;
+  // Keep the Node stream available to discard unread bytes after an early rejection.
+  // An unconsumed Web-stream bridge can pause that drain at its own high-water mark.
+  for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+    size += chunk.length;
+    if (size > MAX_REQUEST_BYTES) return { tooLarge: true };
+    chunks.push(chunk);
+  }
+  return { tooLarge: false, text: new TextDecoder().decode(Buffer.concat(chunks, size)) };
+}
+
+function rejectRequest(request, response, status, code, message, rpcCode = -32000) {
+  if (response.destroyed) return Promise.resolve();
+  const bytes = Buffer.from(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: rpcCode, message, data: { code } } }));
+  return new Promise(resolve => {
+    let cleanupRequest = () => {};
+    const finish = () => { cleanupRequest(); response.off('finish', finish); response.off('close', finish); resolve(); };
+    response.once('finish', finish); response.once('close', finish);
+    response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': bytes.length,
+      'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+      Connection: 'close', ...(status === 429 ? { 'Retry-After': '1' } : {}) });
+    if (!request.complete && !request.destroyed) {
+      // As in the Core HTTP edge, deliver the error before closing an unread upload.
+      // Discard without buffering; the HTTP server's existing timeouts bound the drain.
+      const end = () => { cleanupRequest(); response.end(); };
+      cleanupRequest = () => { request.off('end', end); request.off('close', end); };
+      request.once('end', end); request.once('close', end);
+      if (request.method === 'HEAD') response.flushHeaders(); else response.write(bytes);
+      request.resume();
+    } else response.end(request.method === 'HEAD' ? undefined : bytes);
+  });
+}
+
 /** Standard HTTP MCP edge. Core owns every business write; this edge only owns its local connections. */
 export function createMcpHttpGateway({ getOrigin, authenticate, availableScopes, version }) {
-  const entries = new Map(), lifetime = new AbortController();
-  let state = 'new', createMcpHandler, disposal, starting;
+  const entries = new Map(), jobs = new Set(), lifetime = new AbortController();
+  let state = 'new', createMcpHandler, disposal, starting, activeMessages = 0;
   function start() {
     if (state !== 'new') return Promise.reject(Object.assign(new Error('MCP HTTP 入口只能显式启动一次'), { code: 'IRIS_MCP_CLOSED' }));
     state = 'starting';
@@ -32,7 +69,7 @@ export function createMcpHttpGateway({ getOrigin, authenticate, availableScopes,
           const server = factory();
           if (context.authInfo?.extra?.irisObservation) context.authInfo.extra.irisObservation.server = server;
           return server;
-        }, { legacy: 'stateless', maxRequestBodySize: 9 * 1024 * 1024,
+        }, { legacy: 'stateless', maxRequestBodySize: MAX_REQUEST_BYTES,
           maxSubscriptions: 4, onerror: () => console.error('[iris] MCP HTTP protocol error; private input omitted') });
         return { client, handler };
       } catch (error) {
@@ -43,34 +80,69 @@ export function createMcpHttpGateway({ getOrigin, authenticate, availableScopes,
     entries.set(grant.connectionId, entry);
     return entry.ready;
   }
-  async function handle(request, response, accessToken) {
+  async function handleRequest(request, response, accessToken) {
     if (state !== 'open') throw Object.assign(new Error('MCP HTTP 服务正在关闭'), { code: 'IRIS_API_UNAVAILABLE' });
     const grant = authenticate(accessToken);
-    const { handler, client } = await entryFor(grant, accessToken);
     const disconnected = new AbortController();
     const onClose = () => { if (!response.writableFinished) disconnected.abort(); };
     response.once('close', onClose);
     const signal = AbortSignal.any([disconnected.signal, lifetime.signal]);
+    const onAbort = () => { request.destroy(); response.destroy(); };
+    signal.addEventListener('abort', onAbort, { once: true });
+    let reserved = 0;
     try {
+      if (activeMessages >= MAX_ACTIVE_MESSAGES) return await rejectRequest(request, response, 429,
+        'IRIS_MCP_HTTP_BUSY', 'MCP HTTP is busy; retry after an active response finishes.');
+      activeMessages++; reserved = 1;
       const headers = new Headers();
       for (const [name, value] of Object.entries(request.headers)) {
         if (Array.isArray(value)) for (const item of value) headers.append(name, item);
         else if (value !== undefined) headers.set(name, value);
       }
+      let parsedBody;
+      if (request.method === 'POST') {
+        const body = await readBody(request);
+        if (body.tooLarge) return await rejectRequest(request, response, 413,
+          'IRIS_MCP_HTTP_BODY_TOO_LARGE', 'MCP request body exceeds the 9 MiB limit.');
+        try { parsedBody = JSON.parse(body.text); }
+        catch (error) {
+          if (!(error instanceof SyntaxError)) throw error;
+          return await rejectRequest(request, response, 400, 'IRIS_MCP_HTTP_PARSE_ERROR', 'Parse error: invalid JSON.', -32700);
+        }
+        // One HTTP batch can otherwise fan out into many complete base64 media responses.
+        const count = Array.isArray(parsedBody) ? Math.max(1, parsedBody.length) : 1;
+        if (count > MAX_ACTIVE_MESSAGES) return await rejectRequest(request, response, 400,
+          'IRIS_MCP_HTTP_BATCH_TOO_LARGE', 'MCP HTTP batches must not exceed 4 messages.', -32600);
+        if (activeMessages + count - reserved > MAX_ACTIVE_MESSAGES) return await rejectRequest(request, response, 429,
+          'IRIS_MCP_HTTP_BUSY', 'MCP HTTP is busy; retry after an active response finishes.');
+        activeMessages += count - reserved; reserved = count;
+      }
+      signal.throwIfAborted();
       const input = new Request(getOrigin() + '/mcp', { method: request.method, headers, signal,
-        ...(['GET', 'HEAD'].includes(request.method) ? {} : { body: Readable.toWeb(request), duplex: 'half' }) });
+        ...(['GET', 'HEAD', 'POST'].includes(request.method) ? {} : { body: Readable.toWeb(request), duplex: 'half' }) });
+      const { handler, client } = await entryFor(grant, accessToken);
+      signal.throwIfAborted();
       const observation = {};
-      const result = await handler.fetch(input, { authInfo: { token: accessToken, clientId: grant.connectionId,
+      const result = await handler.fetch(input, { ...(request.method === 'POST' ? { parsedBody } : {}),
+        authInfo: { token: accessToken, clientId: grant.connectionId,
         scopes: grant.scopes, extra: { irisObservation: observation } } });
       if (result.ok && observation.server) void reportMcpClientInfo(client, projectedMcpClient(observation.server.server.getClientVersion()), 'http');
       if (signal.aborted || response.destroyed) { await result.body?.cancel(); return; }
       response.writeHead(result.status, { ...Object.fromEntries(result.headers), 'Cache-Control': 'no-store',
         'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer' });
-      if (result.body && request.method !== 'HEAD') await pipeline(Readable.fromWeb(result.body), response);
+      if (result.body && request.method !== 'HEAD') await pipeline(Readable.fromWeb(result.body), response, { signal });
       else response.end();
     } catch (error) {
       if (!signal.aborted) throw error;
-    } finally { response.off('close', onClose); }
+    } finally {
+      activeMessages -= reserved;
+      response.off('close', onClose); signal.removeEventListener('abort', onAbort);
+    }
+  }
+  function handle(request, response, accessToken) {
+    const job = handleRequest(request, response, accessToken); jobs.add(job);
+    void job.then(() => jobs.delete(job), () => jobs.delete(job));
+    return job;
   }
   function dispose() {
     if (disposal) return disposal;
@@ -82,6 +154,7 @@ export function createMcpHttpGateway({ getOrigin, authenticate, availableScopes,
       if (starting) await Promise.allSettled([starting]);
       const ready = await Promise.allSettled(pending.map(entry => entry.ready));
       const results = await Promise.allSettled([...disconnecting, ...ready.filter(result => result.status === 'fulfilled').map(result => result.value.handler.close())]);
+      await Promise.allSettled([...jobs]);
       entries.clear(); state = 'closed';
       const failed = results.find(result => result.status === 'rejected');
       if (failed) throw failed.reason;

package/lib/mcp-server.js

@@ -1,6 +1,7 @@
 import { bridgeToolsForScopes, callCoreBridgeTool } from './core-bridge-tools.js';
 import { projectedMcpClient } from './core-connections.js';
 import { coreConnectionDiagnostic } from './core-connection-diagnostics.js';
+import { VIDEO_TYPES } from './video-flow-input.js';
 
 /** Client labels are optional observations. Their failure must not delay a Core
  * command or discard its receipt; command authorization remains in Core. */
@@ -13,7 +14,7 @@ export async function reportMcpClientInfo(client, clientInfo, transport) {
 
 /** One official-SDK tool factory for both standard transports and protocol eras. */
 export async function createMcpServerFactory({ client, version, transport = 'stdio' }) {
-  const [{ McpServer }, { z }] = await Promise.all([import('@modelcontextprotocol/server'), import('zod')]);
+  const [{ McpServer, ResourceTemplate, ResourceNotFoundError }, { z }] = await Promise.all([import('@modelcontextprotocol/server'), import('zod')]);
   const snapshot = client.snapshot();
   const tools = bridgeToolsForScopes(snapshot.scopes, snapshot.capabilities, snapshot.tools, snapshot.pluginOperations);
   const factory = () => {
@@ -22,6 +23,23 @@ export async function createMcpServerFactory({ client, version, transport = 'std
     if (transport === 'stdio') server.server.oninitialized = () => {
       void reportMcpClientInfo(client, projectedMcpClient(server.server.getClientVersion()), transport);
     };
+    if (tools.some(tool => tool.name === 'iris_core_video')) {
+      server.registerResource('iris-video', new ResourceTemplate('iris://video/{artifactId}', { list: undefined }),
+        { title: 'Saved Iris video', description: 'Original saved MP4/WebM, up to 32 MiB. Every read requires the current Core video grant.' },
+        async (uri, variables, context) => {
+          const artifactId = variables.artifactId;
+          try {
+            if (typeof artifactId !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(artifactId) || uri.href !== 'iris://video/' + artifactId) {
+              throw Object.assign(new Error('Invalid video reference'), { code: 'IRIS_CONNECTION_INPUT_INVALID' });
+            }
+            const { video } = await callCoreBridgeTool(client, 'iris_core_video', { artifactId }, { signal: context.mcpReq.signal });
+            return { contents: [{ uri: uri.href, mimeType: video.mediaType, blob: video.bytes.toString('base64') }] };
+          } catch (error) {
+            const diagnostic = coreConnectionDiagnostic(error, { stage: 'tool' });
+            throw new ResourceNotFoundError('iris://video', diagnostic.code + ': ' + diagnostic.message + ' ' + diagnostic.action);
+          }
+        });
+    }
     for (const tool of tools) server.registerTool(tool.name, {
       description: tool.description, inputSchema: z.fromJSONSchema(tool.parameters),
       annotations: { readOnlyHint: tool.scope === 'read', destructiveHint: tool.scope === 'stop',
@@ -34,6 +52,10 @@ export async function createMcpServerFactory({ client, version, transport = 'std
           { type: 'text', text: JSON.stringify({ artifactId: result.image.artifactId, bytes: result.image.bytes.length }) }] };
         if (result.audio) return { content: [{ type: 'audio', data: result.audio.bytes.toString('base64'), mimeType: result.audio.mediaType },
           { type: 'text', text: JSON.stringify({ artifactId: result.audio.artifactId, bytes: result.audio.bytes.length }) }] };
+        if (result.video) return { content: [{ type: 'resource_link', uri: 'iris://video/' + result.video.artifactId,
+          name: 'iris-' + result.video.artifactId + '.' + VIDEO_TYPES[result.video.mediaType], mimeType: result.video.mediaType, size: result.video.bytes.length },
+          { type: 'text', text: JSON.stringify({ artifactId: result.video.artifactId, bytes: result.video.bytes.length,
+            note: 'Read this saved resource with resources/read. Playback depends on the client; this reference does not prove it was watched.' }) }] };
         return { content: [{ type: 'text', text: JSON.stringify(result.value) }], structuredContent: result.value };
       } catch (error) {
         const diagnostic = coreConnectionDiagnostic(error, { stage: 'tool', references: args });

package/lib/media-scheduler.js

@@ -0,0 +1,194 @@
+// Instance-owned admission. No durable work loop and no automatic request replay.
+import { AsyncResource } from 'node:async_hooks';
+import { performance } from 'node:perf_hooks';
+import { parseModelRef } from './models.js';
+import { coreRemoteTaskIdentities, CoreTaskError } from './core-tasks.js';
+import { checkedSchedulingPolicy, schedulingError } from './scheduling-policy.js';
+import { retryAfterDelay } from './provider-health.js';
+
+export function createMediaScheduler(input) {
+  const policy = checkedSchedulingPolicy(input), http = [], scopes = new Map(), changes = new Set(), remoteVersions = new Map();
+  let timer, closed = false, active = 0, sent = 0, completed = 0, pumping = false;
+  function selected(context) {
+    const parsed = parseModelRef(context.modelRef || context.attempt?.model || '');
+    const providerId = context.providerId || parsed?.providerId;
+    const provider = policy.providers.find(value => value.providerId === providerId);
+    const model = provider?.models.find(value => value.modelId === parsed?.modelId);
+    return [['global', policy], ...(provider ? [[JSON.stringify([providerId]), provider]] : []),
+      ...(model ? [[JSON.stringify([providerId, parsed.modelId]), model]] : [])];
+  }
+  function state(key) {
+    if (!scopes.has(key)) scopes.set(key, { active: 0, times: [], cooldownUntil: 0 });
+    return scopes.get(key);
+  }
+  function remove(job) { const index = http.indexOf(job); if (index >= 0) http.splice(index, 1); job.signal?.removeEventListener('abort', job.abort); }
+  function pump() {
+    if (pumping) return;
+    pumping = true;
+    try { drain(); } finally { pumping = false; }
+  }
+  function drain() {
+    clearTimeout(timer); timer = undefined;
+    let next = Infinity;
+    for (const job of [...http]) {
+      const now = performance.now();
+      if (now >= job.deadline) {
+        remove(job); job.fail(schedulingError('IRIS_SCHEDULER_QUEUE_TIMEOUT', 'HTTP 派发等候超时；本次请求未发送')); continue;
+      }
+      const relevant = selected(job.context).map(([key, limits]) => ({ ...limits, state: state(key) }));
+      let ready = true, at = now + cooldownDelay(job.context);
+      for (const entry of relevant) {
+        entry.state.times = entry.state.times.filter(time => now - time < 1000);
+        if (entry.httpConcurrency && entry.state.active >= entry.httpConcurrency) ready = false;
+        if (entry.requestsPerSecond && entry.state.times.length >= entry.requestsPerSecond) at = Math.max(at, entry.state.times[0] + 1000);
+        at = Math.max(at, entry.state.cooldownUntil);
+      }
+      if (!ready || at > now) {
+        job.context.onSchedulingState?.(cooldownDelay(job.context) > 0 ? 'cooldown' : at > now ? 'rate_limit' : 'http_queue');
+        next = Math.min(next, job.deadline, at > now ? at : Infinity); continue;
+      }
+      remove(job); active++; sent++;
+      for (const entry of relevant) { entry.state.active++; entry.state.times.push(now); }
+      let released = false;
+      const release = () => {
+        if (released) return; released = true; active--; completed++;
+        for (const entry of relevant) entry.state.active--;
+        pump();
+      };
+      // Timestamp and the actual dispatcher invocation share this stack, not a reservation promise.
+      job.context.onSchedulingState?.('http_running');
+      job.start(release);
+    }
+    if (http.length && Number.isFinite(next)) timer = setTimeout(pump, Math.max(1, Math.ceil(next - performance.now())));
+  }
+  function dispatch(context, start, fail, signal) {
+    if (closed) { fail(schedulingError('IRIS_SCHEDULER_CLOSED', '调度实例已关闭')); return; }
+    if (signal?.aborted) { fail(signal.reason); return; }
+    if (http.length >= policy.queueLimit) { fail(schedulingError('IRIS_SCHEDULER_QUEUE_FULL', 'HTTP 等候队列已满；本次请求未发送')); return; }
+    const resource = new AsyncResource('IrisHttpDispatch');
+    const job = { context, signal, deadline: performance.now() + policy.queueTimeoutMs,
+      start(release) { try { resource.runInAsyncScope(start, undefined, release); } finally { resource.emitDestroy(); } },
+      fail(error) { try { resource.runInAsyncScope(fail, undefined, error); } finally { resource.emitDestroy(); } } };
+    job.abort = () => { remove(job); job.fail(signal.reason); pump(); };
+    signal?.addEventListener('abort', job.abort, { once: true });
+    http.push(job); pump();
+  }
+  function cooldown(context, delay) {
+    if (!Number.isFinite(delay) || delay < 0) return;
+    // A model-specific 429 blocks future requests for that model, never unrelated providers.
+    const entries = selected(context), target = entries.at(-1);
+    // Unconfigured provider/model limits still need an isolated cooldown scope.
+    const parsed = parseModelRef(context.modelRef || context.attempt?.model || '');
+    const key = parsed ? JSON.stringify([parsed.providerId, parsed.modelId]) : context.providerId ? JSON.stringify([context.providerId]) : target[0];
+    state(key).cooldownUntil = Math.max(state(key).cooldownUntil, performance.now() + delay);
+    changed(); pump();
+  }
+  function cooldownDelay(context) {
+    const parsed = parseModelRef(context.modelRef || context.attempt?.model || '');
+    const ids = [JSON.stringify([context.providerId || parsed?.providerId]), ...(parsed ? [JSON.stringify([parsed.providerId, parsed.modelId])] : [])];
+    return Math.max(0, ...ids.map(key => (scopes.get(key)?.cooldownUntil || 0) - performance.now()));
+  }
+  function changed(dataRoot) {
+    if (dataRoot) {
+      if (!changes.size) return;
+      let version;
+      try { version = JSON.stringify([...remoteCounts(dataRoot)].sort(([a], [b]) => a.localeCompare(b))); }
+      catch (error) {
+        if (!(error instanceof CoreTaskError)) throw error;
+        // Wake the admissions that need this count, without turning a read error
+        // into a failed release of an unrelated writer turn.
+        for (const reject of [...changes]) reject(error);
+        return;
+      }
+      if (remoteVersions.get(dataRoot) === version) return;
+      remoteVersions.set(dataRoot, version);
+    }
+    for (const resolve of [...changes]) resolve();
+  }
+  function change(signal, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let timeout;
+      const done = (error) => { clearTimeout(timeout); changes.delete(wake); signal?.removeEventListener('abort', abort); error ? reject(error) : resolve(); };
+      const wake = error => done(error), abort = () => done(signal.reason);
+      if (signal?.aborted) { reject(signal.reason); return; }
+      changes.add(wake); signal?.addEventListener('abort', abort, { once: true });
+      timeout = setTimeout(wake, Math.max(1, timeoutMs));
+    });
+  }
+  function remoteCounts(dataRoot) {
+    const result = new Map([['global', 0]]);
+    for (const task of coreRemoteTaskIdentities(dataRoot)) {
+      result.set('global', result.get('global') + 1);
+      const parsed = parseModelRef(task.modelRef || '');
+      if (parsed) for (const key of [JSON.stringify([parsed.providerId]), JSON.stringify([parsed.providerId, parsed.modelId])]) result.set(key, (result.get(key) || 0) + 1);
+    }
+    return result;
+  }
+  async function beforeSubmit(runtime, dataRoot, context, readyAt) {
+    const deadline = performance.now() + policy.queueTimeoutMs;
+    for (;;) {
+      if (closed) throw schedulingError('IRIS_SCHEDULER_CLOSED', '调度实例已关闭');
+      runtime.signal.throwIfAborted();
+      const counts = remoteCounts(dataRoot), full = selected(context).some(([key, limits]) => limits.remoteLimit && (counts.get(key) || 0) >= limits.remoteLimit);
+      const delay = Math.max(cooldownDelay(context), (readyAt?.() || 0) - Date.now());
+      if (!full && delay <= 0) return;
+      const left = deadline - performance.now();
+      if (left <= 0) throw schedulingError('IRIS_SCHEDULER_QUEUE_TIMEOUT', full
+        ? '远端未结束任务名额等候超时；未发送新的提交，请查询原任务'
+        : '模型冷却等候超时；未发送新的提交');
+      // A bounded wait is released by another Core commit or the known cooldown/deadline.
+      await runtime.networkWait(() => change(runtime.signal, Math.min(left, delay > 0 ? delay : left)), full ? 'remote_capacity' : 'cooldown');
+    }
+  }
+  function dispatcher(target, context, signal) {
+    let dispatches = 0;
+    return { get dispatches() { return dispatches; }, dispatch(options, handler) {
+      let abortRemote, finished = false, release;
+      const queued = new AbortController();
+      const combined = signal ? AbortSignal.any([signal, queued.signal]) : queued.signal;
+      const end = () => { if (finished) return false; finished = true; release?.(); return true; };
+      const fail = error => { if (end()) handler.onError(error); };
+      // Give fetch its abort port while still queued. The real dispatcher supplies the socket abort later.
+      handler.onConnect(error => { queued.abort(error); abortRemote?.(error); });
+      dispatch(context, done => {
+        release = done;
+        const wrapped = {
+          onConnect(abort) { abortRemote = abort; if (combined.aborted) abort(combined.reason); },
+          onHeaders(status, headers, resume, statusText) {
+            if (status === 429) {
+              let retry;
+              for (let i = 0; i < headers.length; i += 2) if (String(headers[i]).toLowerCase() === 'retry-after') retry = String(headers[i + 1]);
+              cooldown(context, retryAfterDelay(retry));
+            }
+            return handler.onHeaders(status, headers, resume, statusText);
+          },
+          onData: chunk => handler.onData(chunk),
+          onComplete(trailers) { if (end()) handler.onComplete(trailers); },
+          onError: fail,
+          ...(handler.onResponseStarted ? { onResponseStarted: () => handler.onResponseStarted() } : {}),
+          ...(handler.onBodySent ? { onBodySent: (...args) => handler.onBodySent(...args) } : {}),
+          ...(handler.onUpgrade ? { onUpgrade(...args) { end(); return handler.onUpgrade(...args); } } : {}),
+          ...(handler.onRequestUpgrade ? { onRequestUpgrade(...args) { end(); return handler.onRequestUpgrade(...args); } } : {})
+        };
+        try { dispatches++; target.dispatch(options, wrapped); } catch (error) { fail(error); }
+      }, fail, combined);
+      return true;
+    } };
+  }
+  function snapshot(dataRoot) {
+    let remote;
+    if (dataRoot) {
+      try { remote = { remoteOutstanding: remoteCounts(dataRoot).get('global') }; }
+      catch (error) {
+        if (!(error instanceof CoreTaskError)) throw error;
+        remote = { remoteOutstanding: null, remoteError: error.code };
+      }
+    }
+    return Object.freeze({ enabled: true, httpActive: active, httpQueued: http.length, requestsStarted: sent, requestsCompleted: completed,
+      ...remote,
+      limits: { httpConcurrency: policy.httpConcurrency, requestsPerSecond: policy.requestsPerSecond, remoteLimit: policy.remoteLimit,
+        queueLimit: policy.queueLimit, queueTimeoutMs: policy.queueTimeoutMs } });
+  }
+  return Object.freeze({ policy, dispatch, dispatcher, beforeSubmit, changed, cooldown, snapshot,
+    dispose() { closed = true; clearTimeout(timer); for (const job of [...http]) { remove(job); job.fail(schedulingError('IRIS_SCHEDULER_CLOSED', '调度实例已关闭')); } changed(); } });
+}

package/lib/model-directory-service.js

@@ -5,12 +5,21 @@ import { createConfiguredProviderAdapter } from './provider-adapters.js';
 import { invokeProviderOperation } from './provider-adapter.js';
 import { redactProviderMessage } from './provider-contract.js';
 import { MODEL_DIRECTORY_TTL_MS, MODEL_DIRECTORY_RETRY_MS, currentModelDirectory, modelDirectoryBinding } from './model-directory.js';
+import { assertDiscoveryCredentials } from './provider-credentials.js';
+import { assertProviderNetwork } from './provider-network.js';
+import { providerNetworkRequirement, sameNetworkRequirement, networkPolicyError } from './network-policy.js';
 
 const pending = new Map();
 const registryPending = new WeakMap();
+const networkPending = new WeakMap();
 
 /** 只有完整发现成功才替换快照；相同连接合并网络读取，各调用方保存自己的配置。 */
-export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now(), registry } = {}) {
+export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now(), registry, network } = {}) {
+  if (network !== undefined) assertProviderNetwork(network);
+  const requirement = providerNetworkRequirement(provider);
+  if (requirement && (!network || !sameNetworkRequirement(requirement, network.networkRequirement) || provider.id !== network.providerId)) {
+    throw networkPolicyError('IRIS_NETWORK_CONTEXT_REQUIRED', '模型目录需要供应商匹配的网络上下文，不会使用默认出口');
+  }
   if (!providerProtocolDescriptor(selectMediaProtocol(provider).mediaProtocol, registry)) {
     return { refreshed: false, error: '当前协议未提供模型目录发现' };
   }
@@ -24,27 +33,35 @@ export async function refreshModelDirectory(provider, { force = false, signal, s
   }
   signal?.throwIfAborted();
   let calls = pending;
+  let registries = registryPending;
+  if (network) {
+    if (!networkPending.has(network)) networkPending.set(network, { calls: new Map(), registries: new WeakMap() });
+    const scoped = networkPending.get(network);
+    calls = scoped.calls; registries = scoped.registries;
+  }
   if (registry) {
-    if (!registryPending.has(registry)) registryPending.set(registry, new Map());
-    calls = registryPending.get(registry);
+    if (!registries.has(registry)) registries.set(registry, new Map());
+    calls = registries.get(registry);
     discover = async ({ signal, timeoutMs }) => (await invokeProviderOperation(
-      createConfiguredProviderAdapter(provider, { registry }), 'discover', { signal, timeoutMs })).models;
+      createConfiguredProviderAdapter(provider, { registry, ...(network ? { network } : {}) }), 'discover', { signal, timeoutMs })).models;
   }
-  const binding = modelDirectoryBinding(provider);
+  const binding = modelDirectoryBinding(provider), key = providerApiKey(provider);
   let job = calls.get(binding);
   if (!job) {
     const budget = AbortSignal.timeout(15000);
-    job = discover({ key: providerApiKey(provider), baseUrl: providerMediaBaseUrl(provider),
-      signal: signal ? AbortSignal.any([signal, budget]) : budget, timeoutMs: 15000 });
+    const request = { key, baseUrl: providerMediaBaseUrl(provider),
+      signal: signal ? AbortSignal.any([signal, budget]) : budget, timeoutMs: 15000 };
+    job = network && !registry
+      ? network.run(fetchPort => discover({ ...request, fetchPort })) : discover(request);
     calls.set(binding, job);
     job.finally(() => { if (calls.get(binding) === job) calls.delete(binding); }).catch(() => {});
   }
   let discovered;
   try {
     discovered = await job;
+    assertDiscoveryCredentials(discovered, key);
   } catch (error) {
     signal?.throwIfAborted();
-    const key = providerApiKey(provider);
     const message = String(error?.message || error);
     const directory = { version: 1, binding, ...(previous || {}), failedAt: new Date(now).toISOString(),
       lastError: redactProviderMessage(key ? message.split(key).join('[REDACTED]') : message) };

package/lib/music-transport.js

@@ -1,3 +1,4 @@
+import { inheritedProviderFetch } from './provider-network.js';
 import { ProviderContractError } from './provider-contract.js';
 import { readProviderText, PROVIDER_RESPONSE_LIMITS } from './provider-response.js';
 
@@ -25,10 +26,11 @@ export function musicArtifactsFromResponse(body) {
   return artifacts;
 }
 
-export async function generateMusic({ key, baseUrl, model, prompt, timeoutMs = 300000, signal }) {
+export async function generateMusic({ key, baseUrl, model, prompt, timeoutMs = 300000, signal, fetchPort = inheritedProviderFetch }) {
   const timeout = AbortSignal.timeout(timeoutMs);
-  const response = await fetch(String(baseUrl).replace(/\/+$/, '') + '/chat/completions', {
+  const response = await fetchPort(String(baseUrl).replace(/\/+$/, '') + '/chat/completions', {
     method: 'POST',
+    redirect: 'error',
     headers: { 'Content-Type': 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}) },
     signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
     body: JSON.stringify({ model, stream: false, messages: [{ role: 'user', content: prompt }] })

package/lib/network-config-service.js

@@ -0,0 +1,123 @@
+// Owner CLI resources and explicit bindings. Editing never sends network traffic.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicCreatePrivate, atomicWritePrivate, ensurePrivateDir, privateSibling } from './private-storage.js';
+import { NETWORK_CONFIG_VERSION, NETWORK_ROUTING_CONFIG_VERSION, NETWORK_CONFIG_MAX_BYTES, networkConfigFail as fail, networkFields, normalizeNetworkNode, normalizeNetworkPool, validateNetworkConfig, projectNetworkConfig } from './network-config.js';
+
+const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+function absolute(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 必须是显式绝对路径');
+}
+function io(action) {
+  try { return action(); }
+  catch (error) {
+    if (typeof error.code !== 'string' || typeof error.syscall !== 'string') throw error;
+    const detail = /^[A-Z][A-Z0-9_]{0,39}$/.test(error.code) ? `（${error.code}）` : '';
+    fail('IRIS_NETWORK_CONFIG_IO', `网络配置文件操作失败${detail}，请检查目录权限、可用空间与文件状态；原文件和已有备份不会自动清理`);
+  }
+}
+export function readNetworkConfig(file) {
+  absolute(file);
+  const info = io(() => fs.lstatSync(file));
+  if (!info.isFile() || info.isSymbolicLink()) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 必须是普通文件，不能使用符号链接');
+  if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) fail('IRIS_NETWORK_CONFIG_PERMISSIONS', 'network-config 权限过宽，请限制为仅当前用户可读写');
+  if (info.size > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+  const bytes = io(() => fs.readFileSync(file));
+  if (bytes.length > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+  let parsed;
+  try { parsed = JSON.parse(bytes.toString('utf8')); }
+  catch (_) { fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不是有效 JSON；请修正原文件，不会自动回退'); }
+  return { config: validateNetworkConfig(parsed), bytes, revision: digest(bytes) };
+}
+
+const READS = ['show', 'check', 'nodes.list', 'pools.list', 'bindings.list'];
+const WRITES = ['nodes.add', 'nodes.set', 'nodes.remove', 'pools.add', 'pools.set', 'pools.remove', 'bindings.set', 'bindings.remove'];
+export function executeNetworkConfigCommand(file, command, input = {}, { signal, env = process.env } = {}) {
+  absolute(file); signal?.throwIfAborted();
+  if (['init', 'routing.init', 'routing.copy'].includes(command)) {
+    const copy = command === 'routing.copy', routing = command !== 'init';
+    networkFields(input, copy ? ['source'] : [], copy ? ['source'] : []);
+    const source = copy ? readNetworkConfig(input.source).config : undefined;
+    const config = { schemaVersion: routing ? NETWORK_ROUTING_CONFIG_VERSION : NETWORK_CONFIG_VERSION,
+      configId: crypto.randomUUID(), generation: 1, nodes: source?.nodes || [], pools: source?.pools || [], ...(routing ? { bindings: [] } : {}) };
+    io(() => {
+      ensurePrivateDir(path.dirname(file));
+      try { atomicCreatePrivate(file, JSON.stringify(config, null, 2) + '\n'); }
+      catch (error) { if (error.code === 'EEXIST') fail('IRIS_NETWORK_CONFIG_EXISTS', '网络配置已存在，初始化不会覆盖；请先读取并核对'); throw error; }
+    });
+    const saved = readNetworkConfig(file);
+    return { command, created: true, ...projectNetworkConfig(saved.config, saved.revision, env) };
+  }
+  if (!READS.includes(command) && !WRITES.includes(command)) fail('IRIS_NETWORK_CONFIG_INVALID', '不支持的网络配置命令');
+  const before = readNetworkConfig(file);
+  if (command.startsWith('bindings.') && before.config.schemaVersion !== NETWORK_ROUTING_CONFIG_VERSION) {
+    fail('IRIS_NETWORK_CONFIG_VERSION', '绑定只用于显式新建的 v2 网络配置；可用 routing.copy 另存新文件，原文件不会自动迁移');
+  }
+  if (READS.includes(command)) {
+    networkFields(input, []);
+    return { command, ...(command === 'check' ? { valid: true, networkTested: false } : {}), ...projectNetworkConfig(before.config, before.revision, env) };
+  }
+  const [group, verb] = command.split('.'), field = group === 'nodes' ? 'node' : 'pool';
+  const fields = group === 'bindings' ? ['expectedRevision', 'catalogId', 'providerId', ...(verb === 'set' ? ['poolId'] : ['confirm'])]
+    : verb === 'remove' ? ['expectedRevision', 'id', 'confirm'] : ['expectedRevision', field];
+  networkFields(input, fields, fields);
+  if (input.expectedRevision !== before.revision) fail('IRIS_NETWORK_CONFIG_CHANGED', '网络配置已变化，请重新读取后核对编辑');
+  const next = structuredClone(before.config), records = next[group];
+  if (group === 'bindings') {
+    const index = records.findIndex(binding => binding.catalogId === input.catalogId && binding.providerId === input.providerId);
+    if (verb === 'remove') {
+      if (input.confirm !== true) fail('IRIS_NETWORK_CONFIG_INVALID', '删除绑定需要明确 confirm:true');
+      if (index < 0) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选绑定不存在');
+      records.splice(index, 1);
+    } else {
+      const binding = { catalogId: input.catalogId, providerId: input.providerId, poolId: input.poolId };
+      if (index < 0) records.push(binding); else records[index] = binding;
+    }
+  } else if (verb === 'remove') {
+    if (input.confirm !== true) fail('IRIS_NETWORK_CONFIG_INVALID', '删除资源需要明确 confirm:true');
+    const index = records.findIndex(record => record.id === input.id);
+    if (index < 0) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选网络资源不存在');
+    if (group === 'nodes' && next.pools.some(pool => pool.candidates.some(candidate => candidate.kind === 'node' && candidate.nodeId === input.id))) {
+      fail('IRIS_NETWORK_CONFIG_IN_USE', '节点仍被池引用；请先显式编辑或移除引用，停用的池也保留引用');
+    }
+    if (group === 'pools' && next.bindings?.some(binding => binding.poolId === input.id)) {
+      fail('IRIS_NETWORK_CONFIG_IN_USE', '池仍被供应商绑定引用；请先显式解除绑定，停用的池也保留引用');
+    }
+    records.splice(index, 1);
+  } else {
+    const supplied = input[field];
+    networkFields(supplied, group === 'nodes' ? ['id', 'label', 'enabled', 'protocol', 'host', 'port', 'auth'] : ['id', 'label', 'enabled', 'mode', 'candidates'], ['id']);
+    const index = records.findIndex(record => record.id === supplied.id);
+    if (verb === 'add' && index !== -1) fail('IRIS_NETWORK_CONFIG_EXISTS', '同类网络资源 ID 已存在，不能覆盖');
+    if (verb === 'set' && index === -1) fail('IRIS_NETWORK_CONFIG_NOT_FOUND', '所选网络资源不存在');
+    const normalize = group === 'nodes' ? normalizeNetworkNode : normalizeNetworkPool;
+    const record = normalize(verb === 'set' ? { ...records[index], ...supplied } : supplied);
+    if (verb === 'set') records[index] = record; else records.push(record);
+  }
+  const validated = validateNetworkConfig(next);
+  const changed = JSON.stringify(validated) !== JSON.stringify(before.config);
+  let fd;
+  try { fd = io(() => {
+    try { return fs.openSync(file + '.lock', 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') fail('IRIS_NETWORK_CONFIG_BUSY', '网络配置正在修改或留有未核查的锁；不会自动删除或抢占，请核查写入进程'); throw error; }
+  });
+    // Revalidate the schema before CAS; a newer writer must never be downgraded.
+    const current = readNetworkConfig(file);
+    if (current.revision !== before.revision) fail('IRIS_NETWORK_CONFIG_CHANGED', '网络配置在编辑期间变化，请重新读取后核对');
+    signal?.throwIfAborted();
+    if (!changed) return { command, changed: false, ...projectNetworkConfig(current.config, current.revision, env) };
+    if (validated.generation === Number.MAX_SAFE_INTEGER) fail('IRIS_NETWORK_CONFIG_INVALID', '网络配置修订已超出支持范围');
+    validated.generation++;
+    const encoded = Buffer.from(JSON.stringify(validated, null, 2) + '\n');
+    if (encoded.length > NETWORK_CONFIG_MAX_BYTES) fail('IRIS_NETWORK_CONFIG_INVALID', 'network-config 不能超过1 MiB');
+    const backupPath = privateSibling(file, 'backup');
+    io(() => {
+      fs.writeFileSync(backupPath, before.bytes, { flag: 'wx', mode: 0o600 });
+      atomicWritePrivate(file, encoded);
+    });
+    return { command, changed: true, backupPath, ...projectNetworkConfig(validated, digest(encoded), env) };
+  } finally {
+    if (fd !== undefined) io(() => { try { fs.closeSync(fd); } finally { fs.unlinkSync(file + '.lock'); } });
+  }
+}