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

package/bin/dsh-iris.js

@@ -18,28 +18,46 @@ import { executeVisionCommand, normalizeVisionInput } from '../lib/headless-visi
 import { videoTaskCandidates } from '../lib/video-input.js';
 import { createChromiumBrowser } from '../lib/chromium-browser.js';
 import { executeConfigCommand, recordCatalogRateLimit, recordCatalogAvailability, refreshCatalogDirectories } from '../lib/provider-config-service.js';
+import { executeNetworkConfigCommand } from '../lib/network-config-service.js';
 import { probeVisionModel } from '../lib/vision-model-routing.js';
 import { RED_TEST_IMAGE } from '../lib/vision.js';
 import { parseModelRef, modelRef as qualifiedModelRef } from '../lib/models.js';
 import { coreTaskWaitFinished } from '../lib/task-wait.js';
 import { createLocalReadApi, writeLocalApiTokenFile } from '../lib/local-api.js';
 import { manageCoreSkill } from '../lib/skill-installation.js';
-import { createTrackedProviderAdapter } from '../lib/configured-image-runtime.js';
+import { createTrackedProviderAdapter, configuredImagePorts } from '../lib/configured-image-runtime.js';
 import { inspectExecutionLease, recoverExecutionLease } from '../lib/operation-runner.js';
 import { createConnectionPair } from '../lib/core-connections.js';
 import { builtinLaunchPlugins, loadPluginLaunch } from '../lib/plugin-launch.js';
 import { checkLocalApiTokenDirectory, writeLocalApiTokenDirectory } from '../lib/local-api-token-directory.js';
 import { resolveWorkbenchAuthDirectory } from '../lib/workbench-auth.js';
 import { manageWorkbenchPassword } from '../lib/workbench-auth-cli.js';
+import crypto from 'node:crypto';
+import { atomicCreatePrivate } from '../lib/private-storage.js';
+import { providerNetworkRequirement, networkPolicyError } from '../lib/network-policy.js';
+import { createProviderNetworkManager } from '../lib/network-routing.js';
+import { encodeProviderConfig, wrapProviderCatalog } from '../lib/provider-config-format.js';
+import { readNetworkConfig } from '../lib/network-config-service.js';
+import { readSchedulingPolicy } from '../lib/scheduling-policy.js';
+import { createMediaScheduler } from '../lib/media-scheduler.js';
+
+let cliNetworkConfigPath, cliNetworkManager, cliScheduler;
+function cliResolveNetwork({ provider, ...context }) {
+  const requirement = context.networkRequirement || providerNetworkRequirement(provider);
+  if (requirement === undefined && !cliScheduler) return undefined;
+  cliNetworkManager ||= createProviderNetworkManager({ networkConfigPath: cliNetworkConfigPath, scheduler: cliScheduler });
+  return cliNetworkManager.resolveProviderNetwork({ ...context, networkRequirement: requirement });
+}
 
 function trackedProviderAdapter(provider, options, task) {
-  return createTrackedProviderAdapter(provider, options['provider-config'], task, options.providerRegistry);
+  return createTrackedProviderAdapter(provider, options['provider-config'], task, options.providerRegistry, {
+    network: cliResolveNetwork({ provider, providerId: provider.id, taskId: task?.id }) });
 }
 
 async function generationCatalog(options, capability, modelRef, signal = cliAbortController.signal) {
   const file = required(options['provider-config'], 'provider-config');
   const catalog = loadProviderCatalog(file);
-  if (!modelRef) await refreshCatalogDirectories(file, catalog, capability, { signal, registry: options.providerRegistry });
+  if (!modelRef) await refreshCatalogDirectories(file, catalog, capability, { signal, registry: options.providerRegistry, resolveProviderNetwork: cliResolveNetwork });
   return catalog;
 }
 
@@ -68,13 +86,13 @@ function usage() {
     '    install/uninstall accept --dry-run. Copy only iris-core; preserve local changes and archive managed updates/removals outside the scan directory. status is read-only and does not verify host discovery.',
     '  dsh-iris doctor [--data-root <absolute-path>] [--json]',
     '  dsh-iris api init --data-root <empty-existing-flow-root>',
-    '  dsh-iris execution init --data-root <empty-existing-flow-root> [--image-generation|--audio]',
-    '    Initialize a NEW v1 request container, v2 with --image-generation, or v3 with --audio (images + speech/transcription). Existing roots are never migrated.',
+    '  dsh-iris execution init --data-root <empty-existing-flow-root> [--image-generation|--audio|--video]',
+    '    Initialize a NEW v1 request container, v2 with --image-generation, v3 with --audio, or v4 with --video (images + audio + text-to-video). Existing roots are never migrated.',
     '  dsh-iris execution inspect --data-root <v1-flow-root>',
     '  dsh-iris execution recover-lease --data-root <v1-flow-root> --confirm-stale-pid <pid>',
-    '  dsh-iris connection create --data-root <execution-flow-root> --directory <new-private-directory> --origin <http://127.0.0.1:port> --label <name> [--harness <generic|kimi|dsh>] [--scopes <read,create,execute,stop>] [--capabilities <image-edit,image-generate,tts,transcribe|none>] [--tools <comma-separated-names|none>]',
+    '  dsh-iris connection create --data-root <execution-flow-root> --directory <new-private-directory> --origin <http://127.0.0.1:port> --label <name> [--harness <generic|kimi|dsh>] [--scopes <read,create,execute,stop>] [--capabilities <image-edit,image-generate,tts,transcribe,video-generate|none>] [--tools <comma-separated-names|none>]',
     '  dsh-iris api serve ... --allow-execution --provider-config <absolute-path> [--connections-file <private-grants-file>]',
-    '  dsh-iris mcp serve --connection-file <private-client-json> [--scopes <read,create,execute,stop>] [--capabilities <image-edit,image-generate,tts,transcribe|none>] [--tools <comma-separated-names|none>]',
+    '  dsh-iris mcp serve --connection-file <private-client-json> [--scopes <read,create,execute,stop>] [--capabilities <image-edit,image-generate,tts,transcribe,video-generate|none>] [--tools <comma-separated-names|none>]',
     '    Official SDK stdio bridge to an already running Core service. Read-only by default; stdout contains MCP messages only.',
     '  dsh-iris mcp capabilities',
     '  dsh-iris mcp presets',
@@ -84,6 +102,8 @@ function usage() {
     '  dsh-iris api serve ... --connections-file <private-grants-file> --allow-mcp',
     '  dsh-iris web serve ... --connection-store <private-directory-outside-core> --allow-connection-management [--allow-mcp] [--allow-execution --provider-config <absolute-path>]',
     '  dsh-iris web serve ... --provider-config <private-config> --allow-provider-management [--panel <trusted-panel-manifest.json>]',
+    '  dsh-iris api|web serve ... --network-config <private-config> --allow-network-management',
+    '  dsh-iris api|web serve ... --scheduler-config <absolute-private-json> enables bounded media scheduling (HTTP concurrency <=4, rolling RPS and remote outstanding limits).',
     '    Explicit standard Streamable HTTP endpoint at /mcp; default remains disabled. Uses the existing Core service and user-selected connection tools.',
     '  dsh-iris operation list --data-root <execution-root> [--run-id <run-id>] [--limit <1..30>] [--cursor <operation-id>]',
     '  dsh-iris operation inspect <operation-id> --data-root <execution-root>',
@@ -103,6 +123,14 @@ function usage() {
     '  dsh-iris providers list --provider-config <absolute-path>',
     '  dsh-iris capabilities list --provider-config <absolute-path>',
     '  dsh-iris config <init|show|check> --provider-config <absolute-path>',
+    '  dsh-iris network <init|show|check> --network-config <absolute-private-path>',
+    '  dsh-iris network routing <init|copy> --network-config <new-private-path> [--input <json with source>]',
+    '  dsh-iris network catalog create --network-config <v2-path> --provider-config <source-path> --output <new-private-path>',
+    '  dsh-iris network bindings <list|set|remove> --network-config <v2-path> [--provider-config <wrapped-path> --input <json>]',
+    '    Media/flow/tasks/web accept --network-config with wrapped Provider catalogs. Explicit policy failures never silently inherit or replay generation.',
+    '  dsh-iris network <nodes|pools> list --network-config <absolute-private-path>',
+    '  dsh-iris network <nodes|pools> <add|set|remove> --network-config <absolute-private-path> --input <json>',
+    '    Owner-only resources use environment credential references and revision-checked mutations. Resources alone do not change routes; wrapped catalogs and explicit --network-config enable bound policies.',
     '  dsh-iris providers <add|set> --provider-config <absolute-path> --input <provider-json>',
     '  dsh-iris providers remove <provider-id> --provider-config <absolute-path>',
     '  dsh-iris models list --provider-config <absolute-path>',
@@ -150,7 +178,7 @@ function usage() {
     '  dsh-iris core transactions --data-root <absolute-path>',
     '  dsh-iris core restore <transaction-id> --data-root <absolute-path>',
     '',
-    'Commands never start DSH. run image and the task observe/redeliver/cancel/retry verbs contact a provider only when explicitly requested; credentials come from a private file. observe polls once, redeliver only re-downloads, and cancel is recorded as canceled only when the provider explicitly confirms; none of them ever submits an existing task again. task retry creates a NEW task that may incur duplicate generation billing and requires --confirm-billing; the prompt must be supplied again because Task records never persist prompts. Flow inputs do retain the prompt privately. flow continue may perform the first submission or observe/redeliver the original task, but never resubmits a task with an Attempt.'
+    'Commands never start DSH. run image and the task observe/redeliver/cancel/retry verbs contact a provider only when explicitly requested; provider configuration comes from a private file; explicit environment key references are resolved in this process. observe polls once, redeliver only re-downloads, and cancel is recorded as canceled only when the provider explicitly confirms; none of them ever submits an existing task again. task retry creates a NEW task that may incur duplicate generation billing and requires --confirm-billing; the prompt must be supplied again because Task records never persist prompts. Flow inputs do retain the prompt privately. flow continue may perform the first submission or observe/redeliver the original task, but never resubmits a task with an Attempt.'
   ].join('\n');
 }
 
@@ -223,7 +251,8 @@ function registerRuntime(runtime) {
 async function disposeActiveRuntimes() {
   await Promise.allSettled([...activeRuntimes].map((runtime) => runtime.dispose().catch(() => {})));
   activeRuntimes.clear();
-  await cliProviderRegistry?.dispose();
+  try { await cliProviderRegistry?.dispose(); }
+  finally { try { await cliNetworkManager?.dispose(); } finally { cliScheduler?.dispose(); } }
 }
 
 for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -253,8 +282,8 @@ async function withRuntime(mode, dataRoot, callback, ports = {}) {
   return withRawRuntime(mode, dataRoot, (runtime) => callback(createCommandService(runtime, ports)));
 }
 
-async function withApplication(dataRoot, callback, resolveImageCandidates, resolveTaskAdapter) {
-  const application = createApplicationRuntime({ dataRoot: required(dataRoot, 'data-root'), resolveImageCandidates, resolveTaskAdapter });
+async function withApplication(dataRoot, callback, ports = {}) {
+  const application = createApplicationRuntime({ dataRoot: required(dataRoot, 'data-root'), ...ports });
   const unregister = registerRuntime(application);
   try { return await callback(application); }
   finally { try { await application.dispose(); } finally { unregister(); } }
@@ -392,16 +421,16 @@ async function main(args, providerRegistry) {
         console.log(JSON.stringify(result, null, 2)); return 0;
       }
       if (args[1] !== 'init') throw new CliUsageError('不支持的 execution 子命令');
-      const initArgs = args.slice(2), generationFlags = initArgs.filter(value => value === '--image-generation'), audioFlags = initArgs.filter(value => value === '--audio');
-      if (generationFlags.length > 1 || audioFlags.length > 1 || generationFlags.length && audioFlags.length) throw new CliUsageError('初始化开关重复或冲突；audio已包含文生图');
-      const options = flags(initArgs.filter(value => !['--image-generation', '--audio'].includes(value)), ['data-root']);
+      const initArgs = args.slice(2), generationFlags = initArgs.filter(value => value === '--image-generation'), audioFlags = initArgs.filter(value => value === '--audio'), videoFlags = initArgs.filter(value => value === '--video');
+      if (generationFlags.length + audioFlags.length + videoFlags.length > 1) throw new CliUsageError('初始化开关重复或冲突；video包含音频和图片，audio包含图片');
+      const options = flags(initArgs.filter(value => !['--image-generation', '--audio', '--video'].includes(value)), ['data-root']);
       const suppliedRoot = required(options['data-root'], 'data-root');
       if (!path.isAbsolute(suppliedRoot)) throw new CliUsageError('data-root 必须是已初始化的空 Flow 根绝对路径');
       let dataRoot;
       try { dataRoot = fs.realpathSync(suppliedRoot); }
       catch (_) { throw new CliUsageError('请先在新的专用数据根执行 flow init'); }
       const result = await withApplication(dataRoot, application =>
-        application.execute('execution.init', audioFlags.length ? { audio: true } : generationFlags.length ? { imageGeneration: true } : {}, { signal: cliAbortController.signal }));
+        application.execute('execution.init', videoFlags.length ? { video: true } : audioFlags.length ? { audio: true } : generationFlags.length ? { imageGeneration: true } : {}, { signal: cliAbortController.signal }));
       console.log(JSON.stringify(result, null, 2)); return 0;
     }
     if (!['list', 'inspect'].includes(args[1])) throw new CliUsageError('operation 只支持只读 list/inspect');
@@ -471,12 +500,12 @@ async function main(args, providerRegistry) {
       return 0;
     }
     if (args[1] !== 'serve') throw new CliUsageError(`不支持的 ${args[0]} 子命令`);
-    const rest = args.slice(2), localWriteFlags = rest.filter(value => value === '--allow-local-writes'), executionFlags = rest.filter(value => value === '--allow-execution'), selectionFlags = rest.filter(value => value === '--allow-selection'), mcpFlags = rest.filter(value => value === '--allow-mcp'), managementFlags = rest.filter(value => value === '--allow-connection-management'), providerFlags = rest.filter(value => value === '--allow-provider-management');
-    if (localWriteFlags.length > 1 || executionFlags.length > 1 || selectionFlags.length > 1 || mcpFlags.length > 1 || managementFlags.length > 1 || providerFlags.length > 1) throw new CliUsageError('写入/执行/选择/MCP/管理参数重复');
+    const rest = args.slice(2), localWriteFlags = rest.filter(value => value === '--allow-local-writes'), executionFlags = rest.filter(value => value === '--allow-execution'), selectionFlags = rest.filter(value => value === '--allow-selection'), mcpFlags = rest.filter(value => value === '--allow-mcp'), managementFlags = rest.filter(value => value === '--allow-connection-management'), providerFlags = rest.filter(value => value === '--allow-provider-management'), networkFlags = rest.filter(value => value === '--allow-network-management');
+    if (localWriteFlags.length > 1 || executionFlags.length > 1 || selectionFlags.length > 1 || mcpFlags.length > 1 || managementFlags.length > 1 || providerFlags.length > 1 || networkFlags.length > 1) throw new CliUsageError('写入/执行/选择/MCP/管理参数重复');
     const allowExecution = executionFlags.length === 1, allowLocalWrites = localWriteFlags.length === 1 || allowExecution;
     const allowSelection = selectionFlags.length === 1;
     const allowConnectionManagement = managementFlags.length === 1;
-    const options = flags(rest.filter(value => !['--allow-local-writes', '--allow-execution', '--allow-selection', '--allow-mcp', '--allow-connection-management', '--allow-provider-management'].includes(value)), ['data-root', 'token-file', 'token-dir', 'auth-store', 'provider-config', 'port', 'connections-file', 'connection-store', 'panel', 'plugin-config']);
+    const options = flags(rest.filter(value => !['--allow-local-writes', '--allow-execution', '--allow-selection', '--allow-mcp', '--allow-connection-management', '--allow-provider-management', '--allow-network-management'].includes(value)), ['data-root', 'token-file', 'token-dir', 'auth-store', 'provider-config', 'port', 'connections-file', 'connection-store', 'panel', 'plugin-config']);
     const suppliedRoot = required(options['data-root'], 'data-root');
     const passwordMode = serveWorkbench && options['token-file'] === undefined && options['token-dir'] === undefined;
     if (!passwordMode && Boolean(options['token-file']) === Boolean(options['token-dir'])) throw new CliUsageError('请选择且只选择 --token-file 或 --token-dir');
@@ -492,11 +521,13 @@ async function main(args, providerRegistry) {
     if (options['token-dir']) checkLocalApiTokenDirectory(options['token-dir'], dataRoot);
     return withCliLaunch(options['plugin-config'], { serveWorkbench, panelManifestPath: options.panel }, async (launch, ownApi) => {
       const api = createLocalReadApi({ dataRoot, providerConfigPath: options['provider-config'], allowLocalWrites, serveWorkbench,
+        ...(cliNetworkConfigPath || cliScheduler ? { networkConfigPath: cliNetworkConfigPath,
+          networkManager: cliNetworkManager ||= createProviderNetworkManager({ networkConfigPath: cliNetworkConfigPath, scheduler: cliScheduler }), scheduler: cliScheduler } : {}),
         ...(passwordMode ? { workbenchAuth: { directory: authDirectory } } : {}),
         allowExecution, allowSelection, allowMcp: mcpFlags.length === 1, connectionsFile: options['connections-file'], allowConnectionManagement, connectionStore: options['connection-store'], providerRegistry,
         ...(launch ? { pluginRegistry: launch.registry, providerRegistry: launch.registry.providers, allowedOperations: launch.allowedOperations,
           panelContributions: launch.panelContributions } : {}),
-        allowProviderManagement: providerFlags.length === 1, panelManifestPath: options.panel });
+        allowProviderManagement: providerFlags.length === 1, allowNetworkManagement: networkFlags.length === 1, panelManifestPath: options.panel });
       ownApi(api);
       const started = await api.start({ port: options.port === undefined ? 0 : Number(options.port) });
       if (!passwordMode) {
@@ -509,6 +540,7 @@ async function main(args, providerRegistry) {
         ...(serveWorkbench ? { loginUrl: started.loginUrl, loginExpiresAt: started.loginExpiresAt } : {}),
         ...(allowConnectionManagement ? { connectionManagement: true } : {}),
         ...(providerFlags.length ? { providerManagement: true } : {}),
+        ...(networkFlags.length ? { networkManagement: true } : {}),
         ...(started.mcpEndpoint ? { mcpEndpoint: started.mcpEndpoint } : {}),
         message: passwordMode ? (started.authentication.configured ? '工作台已启动，打开 origin 用访问口令登录；记住设备后可跨正常重启继续使用。'
           : '首次使用请打开 loginUrl 设置访问口令；之后打开普通地址即可登录，无需 Token 文件。')
@@ -539,20 +571,12 @@ async function main(args, providerRegistry) {
     if (verb === 'select' && Object.keys(input).some(key => key !== 'artifact_id')) throw new CliUsageError('flow select 只接受 artifact_id');
     if (needsId) input.run_id = args[2];
     if (verb === 'export') input.output_path = required(options.output, 'output');
-    const resolveImageCandidates = options['provider-config'] ? async ({ modelRef, signal }) => {
-      const catalog = await generationCatalog(options, 'image-gen', modelRef, signal);
-      return imageCandidatesFromCatalog(catalog, modelRef, providerRegistry).map(route => ({ adapter: trackedProviderAdapter(route.provider, options),
-        model: route.modelRef, supportsImageEdit: supportsImageEdit(route.provider.mediaProtocol, route.model, providerRegistry),
-        selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider, providerRegistry) }));
-    } : undefined;
-    const resolveTaskAdapter = options['provider-config'] ? task => {
-      const catalog = loadProviderCatalog(options['provider-config']);
-      return trackedProviderAdapter(providerForTaskFromCatalog(catalog, task, providerRegistry), options, task);
-    } : undefined;
+    const ports = options['provider-config'] ? configuredImagePorts(options['provider-config'], providerRegistry,
+      { resolveProviderNetwork: cliResolveNetwork }) : {};
     let result;
     try {
       result = await withApplication(options['data-root'], application =>
-        application.execute('flow.' + verb, input, { signal: cliAbortController.signal }), resolveImageCandidates, resolveTaskAdapter);
+        application.execute('flow.' + verb, input, { signal: cliAbortController.signal }), ports);
     } catch (error) {
       if (error instanceof GenerationInputError) throw new CliUsageError(error.message);
       throw error;
@@ -602,6 +626,50 @@ async function main(args, providerRegistry) {
     return 0;
   }
 
+  if (args[0] === 'network') {
+    const group = args[1];
+    const collection = ['nodes', 'pools', 'bindings', 'routing', 'catalog'].includes(group);
+    const verb = collection ? args[2] : group;
+    const verbs = group === 'routing' ? ['init', 'copy'] : group === 'catalog' ? ['create'] : group === 'bindings' ? ['list', 'set', 'remove'] : collection ? ['list', 'add', 'set', 'remove'] : ['init', 'show', 'check'];
+    if (!verbs.includes(verb)) {
+      throw new CliUsageError('未知网络资源命令');
+    }
+    const mutation = collection && verb !== 'list' && !(group === 'routing' && verb === 'init') && group !== 'catalog';
+    let options;
+    try { options = flags(args.slice(collection ? 3 : 2), ['network-config', ...(mutation ? ['input'] : []),
+      ...(['catalog', 'bindings'].includes(group) ? ['provider-config'] : []), ...(group === 'catalog' ? ['output'] : [])]); }
+    catch (error) {
+      if (!(error instanceof CliUsageError)) throw error;
+      throw new CliUsageError('网络参数无效：请使用 --network-config；写入内容通过 --input、--input-file 或 --input - 提供。代理地址请在节点 JSON 中分别填写 host/port，认证使用环境变量引用');
+    }
+    const file = required(options['network-config'], 'network-config');
+    if (group === 'catalog') {
+      const network = readNetworkConfig(file).config;
+      if (network.schemaVersion !== 2) throw networkPolicyError('IRIS_NETWORK_CONFIG_VERSION', '网络目录需使用显式新建或另存的 v2 网络文件');
+      const source = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+      const requirement = { schemaVersion: 1, configId: network.configId, catalogId: crypto.randomUUID() };
+      const output = required(options.output, 'output');
+      if (!path.isAbsolute(output)) throw new CliUsageError('output 必须是新私有文件的绝对路径');
+      atomicCreatePrivate(output, JSON.stringify(encodeProviderConfig(wrapProviderCatalog(source, requirement)), null, 2) + '\n');
+      console.log(JSON.stringify({ created: true, networkRequirement: requirement }));
+      return 0;
+    }
+    let input = mutation ? jsonInput(options.input) : {};
+    if (group === 'bindings' && verb === 'remove' && !options['provider-config']) {
+      if (Object.keys(input).some(key => !['expectedRevision', 'catalogId', 'providerId', 'confirm'].includes(key))) throw new CliUsageError('解除遗留绑定需要明确目录身份、供应商、修订与确认');
+    } else if (group === 'bindings' && verb !== 'list') {
+      const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+      const requirement = providerNetworkRequirement(catalog), network = readNetworkConfig(file).config;
+      if (!requirement || requirement.configId !== network.configId) throw networkPolicyError('IRIS_NETWORK_CONFIG_MISMATCH', '绑定需要匹配的新版供应商目录与网络文件');
+      const allowed = verb === 'set' ? ['expectedRevision', 'providerId', 'poolId'] : ['expectedRevision', 'providerId', 'confirm'];
+      if (Object.keys(input).some(key => !allowed.includes(key)) || catalog.providers.filter(provider => provider.id === input.providerId).length !== 1) throw new CliUsageError('绑定输入需要该目录中明确且唯一的供应商身份');
+      input = { ...input, catalogId: requirement.catalogId };
+    }
+    const result = executeNetworkConfigCommand(file, collection ? group + '.' + verb : verb, input, { signal: cliAbortController.signal });
+    console.log(JSON.stringify(result, null, 2));
+    return result.valid === false ? 1 : 0;
+  }
+
   if (['config', 'providers', 'models', 'assignments'].includes(args[0])) {
     const [group, verb] = args;
     const verbs = { config: ['init', 'show', 'check'], providers: ['add', 'set', 'remove'], models: ['list', 'add', 'remove', 'caps', 'protocol', 'music-protocol', 'vision-input', 'discover', 'test', 'workflow-check'], assignments: ['list', 'set', 'clear'] };
@@ -621,7 +689,7 @@ async function main(args, providerRegistry) {
       }
     }
     const result = await executeConfigCommand(required(options['provider-config'], 'provider-config'), group === 'config' ? verb : group + '.' + verb, input, {
-      signal: cliAbortController.signal, registry: providerRegistry,
+      signal: cliAbortController.signal, registry: providerRegistry, resolveProviderNetwork: cliResolveNetwork,
       probe: async ({ provider, modelId, capability, signal }) => {
         if (capability === 'music-gen') return { skipped: true, ok: false, reason: 'Music 不发起小样本探测；请使用 run music 提交创作要求' };
         if (capability === 'vision') return probeVisionModel(provider, modelId, { bytes: Buffer.from(RED_TEST_IMAGE.split(',')[1], 'base64'), mediaType: 'image/png' }, { signal });
@@ -635,7 +703,8 @@ async function main(args, providerRegistry) {
         return withRawRuntime('writer', options['data-root'], async runtime => {
           const mediaCapability = capability === 'image-gen' ? 'image' : capability === 'video-gen' ? 'video' : capability;
           if (mediaCapability === 'image') provider = providerForImageModel(provider, modelId, providerRegistry);
-          const adapter = createConfiguredProviderAdapter(provider, { allowRateLimited: true, modelId, registry: providerRegistry });
+          const adapter = createConfiguredProviderAdapter(provider, { allowRateLimited: true, modelId, registry: providerRegistry,
+            network: cliResolveNetwork({ provider, providerId: provider.id }) });
           let providerInput = mediaCapability === 'image'
             ? { prompt: 'red circle', n: 1, ...(['openai-chat-images', 'openai-responses-images', 'comfyui'].includes(adapter.protocol) ? {} : {
               size: adapter.protocol === 'openai-images' ? '256x256' : '512*512'
@@ -648,8 +717,14 @@ async function main(args, providerRegistry) {
             providerInput = normalized.providerInput;
             if (mediaCapability === 'video') candidates = videoTaskCandidates(candidates, normalized);
             else if (normalized.audioPath) {
-              const prepared = await prepareProviderInput(adapter, { model: modelId, filePath: normalized.audioPath, signal });
-              providerInput = generationInput('transcribe', { audio_url: prepared.url }).providerInput;
+              if (adapter.networkRequirement) candidates = candidates.map(candidate => ({ ...candidate, prepareInput: async ({ signal, taskId, attemptId, networkBudget, recordNetworkRoute }) => {
+                const prepared = await prepareProviderInput(adapter, { model: modelId, filePath: normalized.audioPath, signal }, { taskId, attemptId, networkBudget, recordNetworkRoute });
+                return { audioUrl: prepared.url };
+              } }));
+              else {
+                const prepared = await prepareProviderInput(adapter, { model: modelId, filePath: normalized.audioPath, signal });
+                providerInput = generationInput('transcribe', { audio_url: prepared.url }).providerInput;
+              }
             }
           }
           const submitted = await createProviderTaskRunner(runtime).submit({ capability: mediaCapability,
@@ -751,7 +826,7 @@ async function main(args, providerRegistry) {
     let result;
     try {
       result = await withApplication(options['data-root'], application =>
-        application.generateImage(input, { signal: cliAbortController.signal }), resolveImageCandidates);
+        application.generateImage(input, { signal: cliAbortController.signal }), { resolveImageCandidates });
     } catch (error) {
       if (error instanceof GenerationInputError) throw new CliUsageError(error.message);
       throw error;
@@ -820,29 +895,33 @@ async function main(args, providerRegistry) {
   }
 
   // 转写输入冻结（E3 Profile）：上传型异步——audio_url（公网/oss://）或
-  // audio_path（本地文件，经首选候选 Provider 的临时存储上传，签名 URL 不落 Core）。
+  // audio_path（本地文件，在写者与原 Attempt 建立后按实际候选上传，签名 URL 不落 Core）。
   if (args[0] === 'run' && args[1] === 'transcribe') {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
     const normalized = generationInput('transcribe', jsonInput(options.input), { allowAudioPath: true });
     const catalog = await generationCatalog(options, 'transcribe', normalized.modelRef);
     const routes = transcribeCandidatesFromCatalog(catalog, normalized.modelRef, providerRegistry);
-    let providerInput = normalized.providerInput;
-    if (normalized.audioPath) {
-      if (!fs.existsSync(normalized.audioPath)) throw new CliUsageError('音频文件不存在');
-      const prepared = await prepareProviderInput(trackedProviderAdapter(routes[0].provider, options), {
-        model: routes[0].model, filePath: normalized.audioPath
-      });
-      providerInput = generationInput('transcribe', { audio_url: prepared.url }).providerInput;
-    }
+    if (normalized.audioPath && !fs.existsSync(normalized.audioPath)) throw new CliUsageError('音频文件不存在');
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
-      const candidates = routes.map((route) => ({
-        adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
+      const candidates = routes.map(route => {
+        const adapter = trackedProviderAdapter(route.provider, options);
+        return { adapter, model: route.modelRef,
         selectionReason: route.selectionReason,
-        providerBinding: providerTaskBinding(route.provider, providerRegistry)
-      }));
+        providerBinding: providerTaskBinding(route.provider, providerRegistry),
+        ...(normalized.audioPath ? { prepareInput: async ({ signal, taskId, attemptId, networkBudget, recordNetworkRoute, modelRef, providerId }) => {
+          const prepared = await prepareProviderInput(adapter, { model: route.model, filePath: normalized.audioPath, signal },
+            { taskId, attemptId, networkBudget, recordNetworkRoute, modelRef, providerId });
+          return { audioUrl: prepared.url };
+        } } : {}) };
+      });
+      if (normalized.audioPath && candidates.every(candidate => typeof candidate.adapter.prepareInput !== 'function')) {
+        throw Object.assign(new Error('所选协议未实现临时音频上传；请使用支持上传的转写协议或重新提供 audio_url'), {
+          code: 'IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED'
+        });
+      }
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'transcribe', candidates,
-        providerInput
+        providerInput: normalized.providerInput
       });
       console.log(JSON.stringify(result, null, 2));
     });
@@ -1016,13 +1095,26 @@ try {
       entries.push(entry);
     }
   }
+  if (args[0] !== 'network') for (let index = 0; index < args.length; index++) {
+    if (args[index] !== '--network-config') continue;
+    if (cliNetworkConfigPath !== undefined || !args[index + 1] || !path.isAbsolute(args[index + 1])) throw new CliUsageError('network-config 需要唯一、明确的绝对路径');
+    cliNetworkConfigPath = args[index + 1]; args.splice(index, 2); index--;
+  }
+  let schedulerFile;
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] !== '--scheduler-config') continue;
+    if (!['api', 'web'].includes(args[0]) || args[1] !== 'serve') throw new CliUsageError('scheduler-config 首片仅用于 api/web serve；单次 CLI 和 DSH 独立路径保持原行为');
+    if (schedulerFile !== undefined || !args[index + 1]) throw new CliUsageError('scheduler-config 需要唯一、明确的绝对路径');
+    schedulerFile = args[index + 1]; args.splice(index, 2); index--;
+  }
+  if (schedulerFile !== undefined) cliScheduler = createMediaScheduler(readSchedulingPolicy(schedulerFile));
   try {
     if (entries.length && args.includes('--plugin-config')) throw new CliUsageError('--plugin-config 与 --provider-extension 不能混用；Provider 插件应通过同一插件装配实例加载');
     if (args.length && !args.includes('--help') && !args.includes('-h')) cliProviderRegistry = await loadProviderRegistry(entries);
     process.exitCode = await main(args, cliProviderRegistry);
-  } finally { await cliProviderRegistry?.dispose(); }
+  } finally { try { await cliProviderRegistry?.dispose(); } finally { try { await cliNetworkManager?.dispose(); } finally { cliScheduler?.dispose(); } } }
 } catch (error) {
-  const code = error && error.code || 'IRIS_CLI_FAILED';
+  const code = error && error.code || (error?.providerCode === 'IRIS_PROVIDER_DIRECTORY_CREDENTIALS' ? error.providerCode : 'IRIS_CLI_FAILED');
   const message = error && error.message || '命令执行失败';
   if (error.diagnostic) console.error(JSON.stringify(error.diagnostic));
   else console.error(code + ': ' + message);

package/docs/AGENT_CORE_QUICKSTART.md

@@ -1,13 +1,13 @@
 # Agent Quickstart · Core 与 MCP 接入指导
 
-For **0.3.0-alpha.1 Core Web/MCP**, use the [Core quickstart](CORE_QUICKSTART.md). Stable npm **0.2.7 has CLI/DSH support, without this Web/MCP entry**; use [the stable Agent guide](AGENT_QUICKSTART.md) for it. Install the exact alpha or explicitly choose the alpha channel.
+For **0.3.0-beta.1 Core Web/MCP**, use the [Core quickstart](CORE_QUICKSTART.md). Stable npm **0.2.7 has CLI/DSH support, without this Web/MCP entry**; use [the stable Agent guide](AGENT_QUICKSTART.md) for it. Install the exact beta or explicitly choose the beta channel.
 
 Give this instruction to an Agent helping with setup:
 
 ```text
 Help me use Iris (@mokuyoaxis/dsh-iris). First read README and check the actual
 installed package or source revision, Node version and available CLI commands.
-Distinguish stable 0.2.7 from the 0.3.0-alpha.1 Core workbench/MCP implementation.
+Distinguish stable 0.2.7 from the 0.3.0-beta.1 Core workbench/MCP implementation.
 Installing latest does not opt into alpha; use the exact prerelease or alpha tag.
 Do not install a different package, upgrade the host or migrate a data root silently.
 

package/docs/AGENT_QUICKSTART.md

@@ -1,6 +1,6 @@
 # 给 AI Agent 的简要 Prompt
 
-先选择入口：0.3.0-alpha.1 的 Core 工作台/MCP 使用 [Agent Core 指导](AGENT_CORE_QUICKSTART.md)与[从零启动](CORE_QUICKSTART.md)；下面的安装提示保留面向**稳定 0.2.7 的 DSH / CLI**，不是新 MCP 配置步骤。
+先选择入口：0.3.0-beta.1 的 Core 工作台/MCP 使用 [Agent Core 指导](AGENT_CORE_QUICKSTART.md)与[从零启动](CORE_QUICKSTART.md)；下面的安装提示保留面向**稳定 0.2.7 的 DSH / CLI**，不是新 MCP 配置步骤。
 
 把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
 

package/docs/ARCHITECTURE.md

@@ -1,12 +1,12 @@
 # Iris 架构与边界
 
-状态：本文说明 **Iris 0.3.0-alpha.1** 的共享Core及Web、MCP与插件装配，并保留0.2.7入口图作历史对照。0.2.0建立实例化Core Runtime、Headless CLI及共享Task/Artifact事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.5恢复旧宿主支持，0.2.6增加连接引用、可选功能自动池和目录同步。准确版本及历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js最低22.0.0；Core与插件契约仍为实验性。
+状态：本文说明 **Iris 0.3.0-beta.1** 的共享Core及Web、MCP与插件装配，并保留0.2.7入口图作历史对照。0.2.0建立实例化Core Runtime、Headless CLI及共享Task/Artifact事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.5恢复旧宿主支持，0.2.6增加连接引用、可选功能自动池和目录同步。准确版本及历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js最低22.1.0；Core与插件契约仍为实验性。
 
 ## 当前形态
 
 当前源码的 [Core 工作台](LOCAL_WEB.md)已连接真实持久执行、停止、作品选择和供应商管理；[通用 MCP](MCP.md)及[显式插件贡献](PLUGINS.md)复用同一服务与授权边界。图片生成/编辑、语音/转写和插件业务按用户所选范围启用。下方示意图表示 0.2.7 已发布入口，完整当前覆盖见 [README](../README.md#当前入口覆盖)。
 
-0.3 alpha源码另提供独立 [Panel/主题](PANEL_EXTENSIONS.md)和 [C3 供应商设置](PROVIDER_SETTINGS.md)：页面可显式替换，配置管理复用应用层原子写入；默认媒体权限与 Core Task/Artifact 格式保持。它们不随已发布 0.2.7 提供，也不自动替换 DSH 内嵌 UI。
+0.3 beta另提供独立 [Panel/主题](PANEL_EXTENSIONS.md)和 [C3 供应商设置](PROVIDER_SETTINGS.md)：页面可显式替换，配置管理复用应用层原子写入；默认媒体权限与 Core Task/Artifact 格式保持。它们不随已发布 0.2.7 提供，也不自动替换 DSH 内嵌 UI。
 
 Iris仍以一个npm包交付。DSH插件负责原生Agent工具、附件、浏览器和内嵌UI；Headless CLI与独立Core服务（Web/MCP）在没有DSH/Cordis的进程中接收明确数据根和私有Provider配置。各入口共用Core Runtime、Provider Task Runner、Task/Artifact Store和本地Command，不能在同一根同时充当写者；MCP桥连接已有Core服务，不另建业务写者。
 
@@ -39,7 +39,7 @@ DSH Host / Cordis                         Headless CLI
 
 `lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 负责 DSH 的 Core 实例装配、Provider 连接解析和 Host DTO 投影。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
 
-0.2.7 增加 `lib/application-runtime.js`，首批 CLI 图片命令和固定改图流程通过它装配 Core；[DSH 实例](DSH_RUNTIME.md)也已接入同一队列机制。写队列、操作取消和关闭归属于应用实例；每次写操作独立取得、释放 Core 租约，DSH 的 Core 观察器由插件实例持有并等待卸载。[固定流程](IMAGE_FLOW.md)使用专用根中的版本化 Run、稳定 Task/比较作品身份及引用保护，私有输入保存提示词，Task 仅保存可选流程绑定。[本地 API](LOCAL_API.md)已提供默认只读与主动启用的 [本地创建](LOCAL_CREATION.md)，在 0.2.7 中，执行/取消和真实独立 Web 尚未提供，现已接入上文的0.3 alpha源码；通用 Recipe 仍待实现。详见 [应用运行时契约](CORE_RUNTIME_CONTRACT.md#应用运行时装配)。上图表示已发布入口的共同核心。
+0.2.7 增加 `lib/application-runtime.js`，首批 CLI 图片命令和固定改图流程通过它装配 Core；[DSH 实例](DSH_RUNTIME.md)也已接入同一队列机制。写队列、操作取消和关闭归属于应用实例；每次写操作独立取得、释放 Core 租约，DSH 的 Core 观察器由插件实例持有并等待卸载。[固定流程](IMAGE_FLOW.md)使用专用根中的版本化 Run、稳定 Task/比较作品身份及引用保护，私有输入保存提示词，Task 仅保存可选流程绑定。[本地 API](LOCAL_API.md)已提供默认只读与主动启用的 [本地创建](LOCAL_CREATION.md)，在 0.2.7 中，执行/取消和真实独立 Web 尚未提供，现已接入上文的0.3 beta；通用 Recipe 仍待实现。详见 [应用运行时契约](CORE_RUNTIME_CONTRACT.md#应用运行时装配)。上图表示已发布入口的共同核心。
 
 0.2.1的 S2V 使用 Core Task/Attempt，HTML 使用 `media.html` 与显式 Browser Port；视觉和提示词预览通过共享 Model Ports 执行。纯视觉不创建 Task/Artifact，摘要主动转写仍使用 Core 任务。聊天改图属于媒体生成链，按来源 Artifact ID 创建新 Task 和关联产物。
 
@@ -67,9 +67,9 @@ DSH Host / Cordis                         Headless CLI
 
 完整规则见 [Core Runtime v0](CORE_RUNTIME_CONTRACT.md)、[Artifact Manifest v0](ARTIFACT_MANIFEST.md)、[Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md) 与 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。这些仍是内部契约，不是第三方 SDK 兼容承诺。
 
-面向 0.3 的0.3 alpha源码增加[Provider 扩展首版](PROVIDER_EXTENSIONS.md)：实例拥有协议描述、工厂、活动调用和异步释放；CLI/Core 服务显式传入注册实例，六类内置协议（含 ComfyUI）与外部协议共用候选/健康/恢复。实验性包入口仅开放媒体协议所需接口，尚未提供 DSH 外部模块加载设置、通用 Recipe 或完整 SDK。ComfyUI Task binding 另纳入模板摘要，见 [文生图与工作流入口](IMAGE_GENERATION.md)；原五类协议的 binding 与既有记录保持。
+面向 0.3 的0.3 beta增加[Provider 扩展首版](PROVIDER_EXTENSIONS.md)：实例拥有协议描述、工厂、活动调用和异步释放；CLI/Core 服务显式传入注册实例，六类内置协议（含 ComfyUI）与外部协议共用候选/健康/恢复。实验性包入口仅开放媒体协议所需接口，尚未提供 DSH 外部模块加载设置、通用 Recipe 或完整 SDK。ComfyUI Task binding 另纳入模板摘要，见 [文生图与工作流入口](IMAGE_GENERATION.md)；原五类协议的 binding 与既有记录保持。
 
-同属0.3 alpha源码的 [Core 插件贡献 v0](PLUGINS.md)统一五类贡献的身份、兼容与生命周期。新插件 Provider 的 Task/Attempt 在提交前记录准确依赖，旧绑定保持。默认 Panel 可显式组合页面/设置/预览，共享主题、认证客户端和会话；公开装配保持媒体只读，设置沿用 Core Provider 管理，整套替换仍可用。另由 `allowedOperations` 明确选择持久业务，复用同一单根 runner/FIFO/租约及有版本 `plugin.execute` 记录；Core绑定输入/来源、预留输出身份并管理实际作品存储。[多图对照板](CONTACT_SHEET.md)只引用公开 SDK 和现有 Sharp，已贯穿 Web、用户选择、通用 MCP 与原记录恢复。无稳定 SDK、市场或旧数据迁移。
+同属0.3 beta的 [Core 插件贡献 v0](PLUGINS.md)统一五类贡献的身份、兼容与生命周期。新插件 Provider 的 Task/Attempt 在提交前记录准确依赖，旧绑定保持。默认 Panel 可显式组合页面/设置/预览，共享主题、认证客户端和会话；公开装配保持媒体只读，设置沿用 Core Provider 管理，整套替换仍可用。另由 `allowedOperations` 明确选择持久业务，复用同一单根 runner/FIFO/租约及有版本 `plugin.execute` 记录；Core绑定输入/来源、预留输出身份并管理实际作品存储。[多图对照板](CONTACT_SHEET.md)只引用公开 SDK 和现有 Sharp，已贯穿 Web、用户选择、通用 MCP 与原记录恢复。无稳定 SDK、市场或旧数据迁移。
 
 Core能力目录派生MCP/DSH、Web选项/会话和Skill，投影五类贡献的真实边界。注册/发现不授权，旧工具名单不扩张。MCP用通用目录/执行工具投影连接明确保存的准确业务依赖，Core在接受和后续命令处检查有效权限；断开代理不停止Core。重启只记录interrupted，插件缺失或版本变化不重放，原作品/记录仍可读取。实例生命周期由装配者持有，先关服务再关注册器。
 

package/docs/ARTIFACT_MANIFEST.md

@@ -21,12 +21,16 @@ artifact-store/v0/
 
 Index 更新失败不会撤销已经提交的 Artifact，避免调用方因本地缓存错误重新生成或重复付费。显式 `artifact rebuild` 会从提交记录和旁车 Manifest 重建 Index。
 
+beta.1修复在提交 record 前写入私有 `index.dirty` 标记，成功发布完整 Index 后移除。索引发布失败或进程在两者之间中断时，列表明确返回 `IRIS_ARTIFACT_INDEX_INVALID`，Doctor 报告索引异常；按 ID 读取原作品仍可用。下一次成功刷新或显式重建可消除标记，不需要迁移既有记录，也不自动删除媒体。
+
 ## 内容完整性
 
 Manifest 使用小写十六进制 SHA-256，并同时记录字节数。`inspect`、`export`、`list` 和重建都会核验对象；即使文件大小不变，内容被替换也返回 `IRIS_ARTIFACT_DIGEST_MISMATCH`。
 
 哈希通过固定大小分块读取，不把完整视频再次载入内存。Manifest、错误和 CLI 结果不保存输入路径、旧作品文件名、DSH URL 或供应商下载 URL。
 
+beta.1中，新作品只核验自身内容和实际使用的关系目标；随后刷新 Index 时检查所有历史提交记录、Manifest 和普通文件大小，不重复重哈希历史媒体。历史结构/大小异常会阻止发布新索引，不静默跳过坏记录。已有摘要的正常提交仍需遍历元数据并原子重写 Index，尚非增量数据库；没有摘要的早期 v0 记录仍须计算真实哈希，可通过显式重建升级。媒体读取、CLI `inspect/list/export` 和显式重建继续验证完整内容哈希，目录刷新本身不证明历史媒体本次已重新验过内容。
+
 ## 关系边
 
 关系方向固定为“当前 Artifact 指向既有 Artifact”。v0 支持：

package/docs/AUDIO_FLOWS.md

@@ -1,4 +1,4 @@
-# Core 语音合成与音频转写（0.3 alpha）
+# Core 语音合成与音频转写（0.3 beta）
 
 0.3.0-alpha.1的 Web 与通用 MCP 接入 `speech/v0`、`transcribe/v0`，共用现有 Provider、Task/Attempt、持久 Run 和单根 Operation runner。**稳定 npm 0.2.7 不含这些新增入口。** 原独立 CLI/DSH 的语音和转写继续使用各自原入口；这里描述新的 Core 流程。
 
@@ -14,12 +14,26 @@ node bin/dsh-iris.js web serve --data-root /absolute/new-audio-core \
   --token-file /absolute/new-audio-owner-token --allow-execution
 ```
 
-`--audio` 建立 `creation-requests/v3`，同时支持原图片编辑/生成。不要与 `--image-generation` 混用，也不要在已有 v0/v1/v2 根上执行迁移；原根继续按原能力运行。省略两个开关的 `execution init` 仍建立 v1 图片编辑根，`--image-generation` 仍建立 v2。
+`--audio` 建立 `creation-requests/v3`，同时支持原图片编辑/生成。不要与 `--image-generation` 混用，也不要在已有 v0/v1/v2 根上执行迁移；原根继续按原能力运行。beta.1视频流程另提供 `--video` 新 v4 根，保留这些音频流程；已有 v3 不迁移，三个开关不混用。省略这些开关的 `execution init` 仍建立 v1 图片编辑根，`--image-generation` 仍建立 v2。
 
 打开输出的 `loginUrl`；刷新保留当前标签页登录，过期后可用 `web login` 获取新链接，见 [工作台登录](LOCAL_WEB.md#启动与连接)。播放和下载已有结果无需 Provider；新建 Run 需要显式配置，执行另需 `--allow-execution`。音频不需要 `--allow-selection`。
 
 配置沿用[模型服务](PROVIDER_SETTINGS.md)：为模型明确确认 TTS/转写用途和功能池，再从实际候选中选择。候选不是健康证明，打开页面不做实测。内置音频协议沿用现有 DashScope 实现；配置了 OpenAI 图片接口不等于接入 OpenAI TTS/ASR。这里没有新增语音协议、模型自动替换或音色发现接口。
 
+## CLI 保存与继续（beta.1修复）
+
+独立 `flow create/continue` 现装配与服务相同的图片、语音、转写和视频候选。先建立上述 v3/v4 根，并在功能池中允许所选模型：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-audio-core \
+  --provider-config /absolute/existing-providers.json \
+  --input '{"recipe":"speech/v0","model_ref":"provider::tts-model","text":"鸢尾花","voice":"Cherry"}'
+node bin/dsh-iris.js flow continue run_0123456789abcdef01234567 \
+  --data-root /absolute/new-audio-core --provider-config /absolute/existing-providers.json
+```
+
+Run ID 使用创建命令的实际返回值。转写使用 `recipe:"transcribe/v0"`、明确 `model_ref` 及 `source_artifact_id`，来源应先由当前根的 Web/MCP 音频导入保存；这里不新增 CLI 音频导入命令。创建不合成或上传；首次继续才执行，后续继续只观察或交付原 Task，受理未知不重提。已完成且本地结果完整时，无需 Provider 配置再次读取结果。
+
 ## 页面使用
 
 - **语音合成**：选择实际语音模型，填写朗读文字，必要时展开音色并填该模型支持的标识；留空使用现有协议默认值。点击合成后，保存输入、明确执行一次、保存原音频，可试听并下载。
@@ -28,9 +42,11 @@ node bin/dsh-iris.js web serve --data-root /absolute/new-audio-core \
 
 生成音频/转写是单一结果，保存后即可下载，无需图片版本选择。下载保留原字节；实际落盘以浏览器下载记录为准。离开创作页暂停播放，退出或切换流程释放相应媒体。当前不提供流式合成、音色目录、录音、长音频切片、字幕时间轴或本地 TTS。
 
+beta.1交付新语音/音乐结果时，会读取有限文件头确认WAV或MP3容器，再保存真实MIME与后缀；不把供应商声明的MP3套在WAV字节上。不支持的音频响应保留已受理事实并报交付失败，不重新合成。此为容器识别，不是完整解码或格式迁移；已入库的旧作品不自动改写。
+
 ## 有限 HTTP 契约
 
-以下均以 `/api/v0` 开头，保留 Bearer、Host/Origin、无 CORS 和有限权限。新路由只在 v3 根开放；创建使用原 UUIDv4 `Idempotency-Key`，首次 201、同 Key 同输入 200、不同输入 409。
+以下均以 `/api/v0` 开头，保留 Bearer、Host/Origin、无 CORS 和有限权限。新路由只在 v3 根（beta.1也支持 v4）开放；创建使用原 UUIDv4 `Idempotency-Key`，首次 201、同 Key 同输入 200、不同输入 409。
 
 | 路由 | 输入与结果 |
 |---|---|
@@ -68,4 +84,4 @@ DSH 可选的原生共享 Flow 桥仍限图片，未接入 Core 音频附件投
 
 原结果保存失败时，通过原 Run 明确接回；已有私有交付缓存时无需 Provider。浏览器恢复表只存有界身份，不存朗读文字、音色、音频或转写正文；查到创建成功不自动首次执行。查询类型另含 audio-import、speech-create、transcription-create，见 [刷新恢复](WEB_RECOVERY.md)。
 
-定向测试为 `tests/audio-flow.mjs`、`tests/audio-api.mjs`、`tests/audio-recovery.mjs`、`tests/audio-upload.mjs`。真实 Chromium 可用[工作台验证脚本](LOCAL_WEB.md#验证与下一阶段)的独立 `--audio` 场景，覆盖原字节播放/下载、刷新、丢失创建回包、只读及窄屏/主题。SDK验证包含HTTP 2025/2026与真实stdio进程的2026路径。所有新音频验证使用受控 Provider 或上传响应；**未实测真实付费语音/转写服务，也不代表所有账号、编码或 harness 已通过验收**。
+定向测试为 `tests/audio-flow.mjs`、`tests/audio-api.mjs`、`tests/audio-recovery.mjs`、`tests/audio-upload.mjs`。真实 Chromium 可用[工作台验证脚本](LOCAL_WEB.md#验证与下一阶段)的独立 `--audio` 场景，覆盖原字节播放/下载、刷新、丢失创建回包、只读及窄屏/主题。SDK验证包含HTTP 2025/2026与真实stdio进程的2026路径。受控 Provider/上传回归与真实账号验收分别记录；**不能把回放、目录存在或单一账号成功推断为所有模型、编码或 harness 已通过验收**。

package/docs/BETA_SCOPE.md

@@ -0,0 +1,42 @@
+# 0.3.0-beta.1 范围与兼容约定
+
+本页定义 **0.3.0-beta.1** 的发行范围、最小插件契约与主要用户流程。使用准确版本或 npm `beta` 通道，稳定 `latest` 保留0.2.7；历史alpha.1没有新增网络、视频、调度与Provider工厂上下文v1。安装与升级入口见[发布说明](releases/0.3.0-beta.1.md)。
+
+## 纳入的主要流程
+
+| 用户入口 | 候选约定 | 继续保留的边界 |
+| --- | --- | --- |
+| 启动/登录 | Core明确启动，首次设置访问口令、记住设备、退出/刷新恢复 | 不修改其他harness配置；Token模式继续作为显式选项 |
+| 模型服务 | 添加/编辑/停用/删除供应商，显式凭据来源、完整目录确认、按功能选择模型池 | 目录和近期成功不是永久健康承诺；无跨请求模型轮转；不默认读取其他宿主或.env |
+| 网络出口 | 独立HTTP/HTTPS节点、固定/有序池、供应商绑定、owner页面/CLI/API/Doctor | 无绑定继承实际进程环境；显式失效不悄悄直连；SOCKS、系统TUN控制、地域自动分流和Clash自动配置不在范围 |
+| 创作/作品 | 图片生成/已支持的编辑协议、ComfyUI声明参数，语音/转写、固定文生视频，原件预览/下载 | 协议及账号能力以实际目录/实现和实测为准；没有新增Core音乐/视觉持久流程或远端视频编辑 |
+| 执行/恢复 | 单物理根单写者，持久Run/Task/Attempt/Operation，显式有界调度、原UUID/原任务接回、本地停止 | 调度缺省串行；并发与HTTP速率/远端受理数分别限制；unknown与交付失败不自动新生成；停止不证明远端停费 |
+| MCP连接 | 通用stdio和Streamable HTTP，显式客户端预设，用户选择功能/工具/scopes，导出/检查/握手/撤销/缩权 | 配置检查、协议握手与真实Agent调用分别验证；不扫描harness、不默认授权或聚合第三方MCP服务 |
+| 插件/Panel | Provider、持久业务、页面/设置挂载、作品渲染，共享主题/API/登录；保留整套Panel替换 | 可信代码，无市场/自动安装/热加载/任意插件设置仓库；页面挂载不自动授权业务 |
+
+入口说明：[从零启动](CORE_QUICKSTART.md)、[模型服务](PROVIDER_SETTINGS.md)、[网络工作台](NETWORK_WORKBENCH.md)、[调度](MEDIA_SCHEDULING.md)、[MCP](MCP.md)、[插件开发](PLUGIN_DEVELOPMENT.md)。
+
+## 最小插件兼容面
+
+本轮冻结的是下列窄约定，内部模块与完整通用SDK不纳入冻结：
+
+- Plugin/Adapter契约v0：稳定插件/贡献ID、各自独立版本、Core兼容范围、明确启用与授权、准确持久依赖及缺失/错版错误。
+- Provider工厂上下文v1：Core提供当次解析的连接与借用fetch，管理完整方法的正文/多跳及关闭；插件不拥有Core队列、任务存储或网络资源管理。使用功能标记确认支持，详见[Provider最小契约](PROVIDER_PLUGIN_CONTRACT.md)。
+- 持久业务通过公开有限Core命令和原Operation执行；页面、设置挂载与预览器使用公开浏览器端上下文。Node插件和Shadow DOM都不是安全沙箱。
+- 变更上述可观察输入/结果、权限、生命周期或准确依赖语义时，先审查兼容性并更新相应契约/贡献版本，不把实现升级伪装成原版本恢复。
+
+两类[独立模板](PLUGIN_DEVELOPMENT.md)分别验证业务/页面/PNG预览与真实异步Provider协议。旧窄Provider扩展保留原用法。内部文件不因随包存在而成为公开导出；不要绕过package exports依赖私有路径。
+
+## 数据与平台
+
+旧根不自动迁移；新音频/视频根与网络任务有明确版本门禁，不能让旧CLI写入它们。已发布DSH原工具和原CLI仍按既有范围使用，Core新音视频不自动加入DSH原生共享Flow桥。
+
+beta.1最低Node为22.1.0：隔离复核确认22.0.0原生fetch正文取消不会关闭连接，会占用调度名额；22.1.0与当前22.23.4通过同一验证。CI配置包含Ubuntu/Windows及最低/当前Node22；**工作流配置存在和历史CI成功都不能证明当前候选通过**。本机Termux/PRoot ARM64、真实浏览器、本地代理、实际供应商和原生Agent结果应分别记录。最终发布还需核对同一候选的完整测试、独立包消费者和标准平台矩阵，不能拿旧压测或一次握手替代。
+
+自动配额/GC、复杂模型/出口加权轮询、更多宿主凭据桥、legacy统一迁移、全部供应商/GPU/手机/浏览器/harness认证继续后置；不因本页列出能力就宣称这些覆盖已完成。
+
+## 源码验收与发行候选
+
+文档中的 `node scripts/...`、`tests/...`、`npm test` 和 `npm run lint` 从源码仓库根运行；开发脚本与测试不随npm包根目录分发。安装用户继续使用包内CLI/Web/MCP入口，不能把源码验证命令当作已安装包的使用要求。
+
+CI除Ubuntu/Windows、最低/当前Node22完整测试外，另在Ubuntu当前Node22构建真实tarball，检查包外插件/Provider与凭据/调度消费者、strict NodeNext公共类型，并用真实Chromium验证打包后的总览、凭据、视频与调度页面。缺少必需编译器或浏览器会使该发行检查失败；其他可选运行时的SKIP不计作通过。具体运行结果以对应提交的CI和发行记录为准，历史B5记录不代替本轮结果。

package/docs/CONTACT_SHEET.md

@@ -1,4 +1,4 @@
-# 多图对照板：真实插件业务（0.3 alpha）
+# 多图对照板：真实插件业务（0.3 beta）
 
 0.3.0-alpha.1随附可选插件 `@mokuyoaxis/dsh-iris/contact-sheet`。**稳定 npm 0.2.7 无此入口。** 它将现有 Core 图片离线排成一个新 PNG Artifact，不调用模型或供应商。安装不会启用或授权插件：Node 业务、Web 页和 MCP 连接分别显式选择。