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

package/bin/dsh-iris.js

@@ -3,11 +3,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createCommandService } from '../lib/command-service.js';
 import { createCoreRuntime } from '../lib/core-runtime.js';
+import { createApplicationRuntime } from '../lib/application-runtime.js';
 import { recoverCoreWriterLease } from '../lib/core-lease-recovery.js';
 import { doctor, formatDoctorReport } from '../lib/doctor.js';
 import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot, imageCandidatesFromCatalog, musicCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from '../lib/provider-catalog.js';
 import { createConfiguredProviderAdapter } from '../lib/provider-adapters.js';
-import { providerForImageModel, selectMediaProtocol, dashscopeTtsInputIssue } from '../lib/provider-protocol.js';
+import { providerForImageModel, selectMediaProtocol, dashscopeTtsInputIssue, supportsImageEdit } from '../lib/provider-protocol.js';
+import { loadProviderRegistry } from '../lib/provider-extensions.js';
 import { prepareProviderInput } from '../lib/provider-adapter.js';
 import { createProviderTaskRunner } from '../lib/provider-task-runner.js';
 import { generateMusicTask } from '../lib/music-generation.js';
@@ -20,19 +22,24 @@ 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 { 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';
 
 function trackedProviderAdapter(provider, options, task) {
-  return createConfiguredProviderAdapter(provider, {
-    modelId: parseModelRef(task?.modelRef)?.modelId,
-    onModelAvailability: event => recordCatalogAvailability(options['provider-config'], event),
-    onRateLimit: event => recordCatalogRateLimit(options['provider-config'], event)
-  });
+  return createTrackedProviderAdapter(provider, options['provider-config'], task, options.providerRegistry);
 }
 
-async function generationCatalog(options, capability, modelRef) {
+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: cliAbortController.signal });
+  if (!modelRef) await refreshCatalogDirectories(file, catalog, capability, { signal, registry: options.providerRegistry });
   return catalog;
 }
 
@@ -48,7 +55,50 @@ function usage() {
   return [
     'Usage:',
     '  JSON input: --input <json>, --input-file <path>, or --input - (stdin).',
+    '  --provider-extension <absolute-js-or-mjs-entry> explicitly loads trusted Provider code; repeat for multiple extensions. Experimental v0, no installation or directory discovery.',
+    '  dsh-iris providers protocols [--provider-extension <absolute-entry>] lists protocol/configuration descriptions without credentials or model calls.',
+    '  dsh-iris plugins list',
+    '  dsh-iris plugins inspect --plugin-config <absolute-startup.json>',
+    '    Explicit trusted plugin entries, versions, contributions and selections; inspect imports/activates trusted code but does not start Core or grant connections.',
+    '  dsh-iris web serve ... --plugin-config <absolute-startup.json> [--auth-store <absolute-private-directory>]',
+    '    entries load plugins; operations enables exact business IDs; panel selects pages/settings/renderers. MCP grants remain separate. Do not combine with --provider-extension.',
+    '  dsh-iris skills <install|status|uninstall> --target kimi [--directory <absolute-skills-directory>]',
+    '  dsh-iris skills <install|status|uninstall> --directory <absolute-skills-directory>',
+    '  dsh-iris skills <install|status|uninstall> --bundle <absolute-connection-skill.json> --directory <absolute-skills-directory> [--dry-run]',
+    '    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 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 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>]',
+    '    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',
+    '  dsh-iris mcp config --connection-file <private-client-json> [--preset <generic|claude|codex|kimi>-<stdio|http> | --transport <stdio|http> --format <mcpServers|entry|claude-json|codex-toml>] [--output <new-absolute-path>]',
+    '  dsh-iris mcp check --connection-file <private-client-json> [--scopes <read,create,execute,stop>]',
+    '    stdio config also accepts scopes/capabilities/tools. HTTP config includes credentials and requires a new file inside the connection private directory.',
+    '  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>]',
+    '    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>',
+    '  dsh-iris api serve --data-root <existing-flow-root> --token-file <new-absolute-path-outside-root> [--provider-config <absolute-path>] [--port <0..65535>] [--allow-local-writes] [--allow-selection]',
+    '    Explicit loopback-only API, read-only by default. Local writes import images/audio and create Runs within the root capabilities, without generation. The session token is saved privately; stdout contains no token.',
+    '  dsh-iris web serve --data-root <existing-flow-root> [--auth-store <absolute-private-directory>] [--provider-config <absolute-path>] [--port <0..65535>] [--allow-local-writes] [--allow-execution] [--allow-selection]',
+    '    Default: set one access password, then sign in at origin. Remembered browser sessions survive normal restarts. No Token file is required.',
+    '    Auth state defaults to $IRIS_HOME/web-auth/<root-key> ($IRIS_HOME defaults to ~/.iris). Open the initial loginUrl once to set your password.',
+    '  dsh-iris web login --data-root <existing-flow-root> [--auth-store <absolute-private-directory>]',
+    '  dsh-iris web password reset --data-root <existing-flow-root> [--auth-store <absolute-private-directory>]',
+    '    Reset only the workbench password/browser sessions; Core work and MCP grants remain intact. Prints a setup link while the service is running.',
+    '    Explicit --token-file or --token-dir keeps the legacy Token/link login mode. Do not combine them with --auth-store. api serve still requires one of these Token options.',
+    '  dsh-iris web login --origin <http://127.0.0.1:port> --token-file <current-session-token-file>',
+    '    Get a fresh one-time login link without restarting the workbench.',
+    '    Workbench media APIs are read-only by default; explicit write flags do not require connection management. --allow-selection permits owner-only, revision-checked image selection. Execution enables supported image/speech/transcription flows; Provider management uses its own owner-only flag.',
     '  dsh-iris runtime recover --data-root <absolute-path> --confirm-stale-pid <pid>',
     '  dsh-iris providers list --provider-config <absolute-path>',
     '  dsh-iris capabilities list --provider-config <absolute-path>',
@@ -87,16 +137,24 @@ function usage() {
     '  dsh-iris artifact export-many --data-root <absolute-path> --input <json> --output <absolute-directory>',
     '  dsh-iris artifact export <id> --data-root <absolute-path> --output <absolute-path>',
     '  dsh-iris artifact rebuild --data-root <absolute-path>',
+    '  dsh-iris flow init --data-root <new-absolute-path>',
+    '  dsh-iris flow create --data-root <absolute-path> --provider-config <absolute-path> --input <image-json>',
+    '  dsh-iris models workflow-check <provider::workflow> --provider-config <absolute-path> [--input <workflow_parameters-json>] (read-only)',
+    '    Use explicit model_ref and n=1. Edits require an imported source; text-to-image requires a new execution init --image-generation root. create saves private inputs but never submits.',
+    '  dsh-iris flow <list|inspect> [run-id] --data-root <absolute-path>',
+    '  dsh-iris flow continue <run-id> --data-root <absolute-path> [--provider-config <absolute-path>]',
+    '  dsh-iris flow select <run-id> --data-root <absolute-path> --input <json with artifact_id>',
+    '  dsh-iris flow export <run-id> --data-root <absolute-path> --output <absolute-path>',
     '  dsh-iris core <delete|cleanup> --data-root <absolute-path> [--input <json>] [--confirm-delete]',
     '    Default is a read-only preview. delete selects task_ids/artifact_ids; cleanup executes only explicitly selected preview paths.',
     '  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 Core never persists prompts.'
+    '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.'
   ].join('\n');
 }
 
-function flags(args, allowed) {
+function parseFlags(args, allowed) {
   const parsed = {};
   for (let index = 0; index < args.length; index += 2) {
     const flag = args[index];
@@ -154,6 +212,7 @@ function generationInput(capability, input, options) {
 /** C-8: catchable signals dispose active runtimes before the CLI exits. */
 const activeRuntimes = new Set();
 const cliAbortController = new AbortController();
+let cliProviderRegistry;
 let shuttingDown = false;
 
 function registerRuntime(runtime) {
@@ -164,6 +223,7 @@ function registerRuntime(runtime) {
 async function disposeActiveRuntimes() {
   await Promise.allSettled([...activeRuntimes].map((runtime) => runtime.dispose().catch(() => {})));
   activeRuntimes.clear();
+  await cliProviderRegistry?.dispose();
 }
 
 for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -193,12 +253,314 @@ async function withRuntime(mode, dataRoot, callback, ports = {}) {
   return withRawRuntime(mode, dataRoot, (runtime) => callback(createCommandService(runtime, ports)));
 }
 
-async function main(args) {
+async function withApplication(dataRoot, callback, resolveImageCandidates, resolveTaskAdapter) {
+  const application = createApplicationRuntime({ dataRoot: required(dataRoot, 'data-root'), resolveImageCandidates, resolveTaskAdapter });
+  const unregister = registerRuntime(application);
+  try { return await callback(application); }
+  finally { try { await application.dispose(); } finally { unregister(); } }
+}
+
+/** Own the service and its plugin registry in order, including cancellation during import/start. */
+async function withCliLaunch(pluginConfig, launchOptions, callback) {
+  let loading, launch, api, disposal, startupFailure;
+  const detail = error => ({ code: error.code || 'IRIS_CLI_FAILED', message: error.message || String(error),
+    ...(error instanceof AggregateError ? { errors: error.errors.map(detail) } : {}) });
+  const lifetime = { dispose() {
+    if (!disposal) disposal = (async () => {
+      if (loading) await Promise.allSettled([loading]); // main retains the original startup error.
+      const failures = [];
+      try { await api?.dispose(); } catch (error) { failures.push({ stage: 'core-stop', error }); }
+      try { await launch?.dispose(); } catch (error) { failures.push({ stage: 'plugin-stop', error }); }
+      if (failures.length) {
+        const error = Object.assign(new AggregateError(failures.map(item => item.error), 'Core 服务或插件释放失败；已尝试两阶段收尾'), { code: 'IRIS_CLI_SERVICE_CLEANUP_FAILED' });
+        error.diagnostic = { code: error.code, stage: 'shutdown', message: error.message, ...(pluginConfig ? { file: pluginConfig } : {}),
+          errors: failures.map(item => ({ stage: item.stage, ...detail(item.error) })) };
+        if (cliAbortController.signal.aborted) console.error(JSON.stringify(error.diagnostic));
+        throw error;
+      }
+    })();
+    return disposal;
+  } };
+  const unregister = registerRuntime(lifetime);
+  try {
+    loading = pluginConfig ? loadPluginLaunch(pluginConfig, launchOptions).then(value => (launch = value)) : Promise.resolve();
+    await loading; cliAbortController.signal.throwIfAborted();
+    return await callback(launch, value => { api = value; });
+  } catch (error) { startupFailure = error; throw error; }
+  finally {
+    try { await lifetime.dispose(); }
+    catch (error) { if (startupFailure) error.diagnostic.startup = detail(startupFailure); throw error; }
+    finally { unregister(); }
+  }
+}
+
+async function main(args, providerRegistry) {
+  const flags = (values, allowed) => Object.defineProperty(parseFlags(values, allowed), 'providerRegistry', { value: providerRegistry });
   if (!args.length || args.includes('--help') || args.includes('-h')) {
     console.log(usage());
     return args.length ? 0 : 2;
   }
 
+  if (args[0] === 'providers' && args[1] === 'protocols') {
+    flags(args.slice(2), []);
+    console.log(JSON.stringify(providerRegistry.snapshot(), null, 2)); return 0;
+  }
+
+  if (args[0] === 'plugins') {
+    if (args[1] === 'list') {
+      flags(args.slice(2), []);
+      console.log(JSON.stringify({ contractVersion: 0, builtins: builtinLaunchPlugins(), automaticDiscovery: false })); return 0;
+    }
+    if (args[1] !== 'inspect') throw new CliUsageError('plugins 仅支持 list/inspect');
+    const options = flags(args.slice(2), ['plugin-config']);
+    return withCliLaunch(required(options['plugin-config'], 'plugin-config'), {}, async launch => {
+      console.log(JSON.stringify(launch.summary, null, 2)); return 0;
+    });
+  }
+
+  if (args[0] === 'skills') {
+    const rest = args.slice(2), dryRunFlags = rest.filter(value => value === '--dry-run');
+    if (dryRunFlags.length > 1) throw new CliUsageError('参数重复：--dry-run');
+    const options = flags(rest.filter(value => value !== '--dry-run'), ['target', 'directory', 'bundle']);
+    let result;
+    try {
+      result = manageCoreSkill({ action: args[1], target: options.target, directory: options.directory, bundle: options.bundle, dryRun: dryRunFlags.length === 1 });
+    } catch (error) {
+      if (error.code === 'IRIS_SKILL_OPTIONS_INVALID') throw new CliUsageError(error.message);
+      throw error;
+    }
+    console.log(JSON.stringify(result, null, 2));
+    return args[1] === 'status' && result.status !== 'current' ? 1 : 0;
+  }
+
+  if (args[0] === 'mcp') {
+    if (args[1] === 'presets') {
+      flags(args.slice(2), []);
+      const { MCP_CONNECTION_PRESETS } = await import('../lib/mcp-delivery.js');
+      console.log(JSON.stringify({ contractVersion: 0, presets: MCP_CONNECTION_PRESETS, installationDetected: false }, null, 2)); return 0;
+    }
+    if (args[1] === 'capabilities') {
+      flags(args.slice(2), []);
+      const { BRIDGE_CAPABILITIES, BRIDGE_CONTROL_TOOLS } = await import('../lib/core-bridge-selection.js');
+      console.log(JSON.stringify({ contractVersion: 0, capabilities: BRIDGE_CAPABILITIES, controlTools: BRIDGE_CONTROL_TOOLS,
+        implementedMedia: BRIDGE_CAPABILITIES.map(group => group.recipe), selectionDoesNotGenerate: true }, null, 2)); return 0;
+    }
+    if (!['serve', 'config', 'check'].includes(args[1])) throw new CliUsageError('mcp 支持 serve/config/check/capabilities/presets');
+    const options = flags(args.slice(2), ['connection-file', 'scopes', 'capabilities', 'tools', ...(args[1] === 'config' ? ['transport', 'format', 'preset', 'output'] : [])]);
+    const list = value => value === 'none' ? [] : value.split(',');
+    const selected = { ...(options.capabilities !== undefined ? { capabilities: list(options.capabilities) } : {}),
+      ...(options.tools !== undefined ? { tools: list(options.tools) } : {}) };
+    if (args[1] === 'check') {
+      const { checkMcpConnection } = await import('../lib/mcp-check.js');
+      const result = await checkMcpConnection({ connectionFile: required(options['connection-file'], 'connection-file'),
+        ...(options.scopes !== undefined ? { scopes: options.scopes.split(',') } : {}), ...selected });
+      console.log(JSON.stringify(result, null, 2)); return result.ok ? 0 : 1;
+    }
+    if (args[1] === 'config') {
+      const { exportMcpConfiguration } = await import('../lib/mcp-config.js');
+      const result = exportMcpConfiguration({ connectionFile: required(options['connection-file'], 'connection-file'), ...selected,
+        ...(options.scopes !== undefined ? { scopes: options.scopes.split(',') } : {}), transport: options.transport, format: options.format, presetId: options.preset, output: options.output });
+      process.stdout.write(typeof result === 'string' ? result : JSON.stringify(result, null, 2) + '\n');
+      return 0;
+    }
+    const { createMcpBridge } = await import('../lib/mcp-bridge.js');
+    const manifest = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const bridge = createMcpBridge({ connectionFile: required(options['connection-file'], 'connection-file'),
+      requestedScopes: (options.scopes === undefined ? 'read' : options.scopes).split(','), ...selected, version: manifest.version });
+    const unregister = registerRuntime(bridge);
+    try { await bridge.start(); await bridge.closed; return 0; }
+    finally { try { await bridge.dispose(); } finally { unregister(); } }
+  }
+  if (args[0] === 'connection') {
+    if (args[1] !== 'create') throw new CliUsageError('connection 只支持显式 create');
+    const options = flags(args.slice(2), ['data-root', 'directory', 'origin', 'harness', 'label', 'scopes', 'capabilities', 'tools']);
+    const result = createConnectionPair({ dataRoot: required(options['data-root'], 'data-root'), directory: required(options.directory, 'directory'), origin: required(options.origin, 'origin'),
+      harnessKind: options.harness === undefined ? 'generic' : options.harness, label: required(options.label, 'label'),
+      ...(options.scopes !== undefined ? { scopes: options.scopes.split(',') } : {}),
+      ...(options.capabilities !== undefined ? { capabilities: options.capabilities === 'none' ? [] : options.capabilities.split(',') } : {}),
+      ...(options.tools !== undefined ? { tools: options.tools === 'none' ? [] : options.tools.split(',') } : {}) });
+    console.log(JSON.stringify(result, null, 2)); return 0;
+  }
+  if (args[0] === 'execution' || args[0] === 'operation') {
+    if (args[0] === 'execution') {
+      if (['inspect', 'recover-lease'].includes(args[1])) {
+        const options = flags(args.slice(2), ['data-root', ...(args[1] === 'recover-lease' ? ['confirm-stale-pid'] : [])]);
+        const dataRoot = required(options['data-root'], 'data-root');
+        if (args[1] === 'recover-lease' && !/^[1-9][0-9]*$/.test(options['confirm-stale-pid'] || '')) throw new CliUsageError('需要明确回显 stale owner PID');
+        const result = args[1] === 'inspect' ? inspectExecutionLease(dataRoot)
+          : recoverExecutionLease(dataRoot, { confirmStalePid: Number(options['confirm-stale-pid']) });
+        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 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 }));
+      console.log(JSON.stringify(result, null, 2)); return 0;
+    }
+    if (!['list', 'inspect'].includes(args[1])) throw new CliUsageError('operation 只支持只读 list/inspect');
+    const inspecting = args[1] === 'inspect';
+    if (inspecting && (!args[2] || args[2].startsWith('--'))) throw new CliUsageError('缺少 Operation ID');
+    const options = flags(args.slice(inspecting ? 3 : 2), ['data-root', ...(inspecting ? [] : ['run-id', 'limit', 'cursor'])]);
+    if (options.limit !== undefined && !/^(?:[1-9]|[12][0-9]|30)$/.test(options.limit)) throw new CliUsageError('limit 必须是 1–30 的整数');
+    const input = inspecting ? { id: args[2] } : { ...(options['run-id'] ? { runId: options['run-id'] } : {}),
+      ...(options.limit !== undefined ? { limit: Number(options.limit) } : {}), ...(options.cursor ? { cursor: options.cursor } : {}) };
+    const result = await withApplication(required(options['data-root'], 'data-root'), application =>
+      application.execute('operation.' + args[1], input, { signal: cliAbortController.signal }));
+    console.log(JSON.stringify(result, null, 2)); return 0;
+  }
+
+  if (args[0] === 'api' || args[0] === 'web') {
+    const serveWorkbench = args[0] === 'web';
+    if (serveWorkbench && args[1] === 'password') {
+      if (args[2] !== 'reset') throw new CliUsageError('web password 仅支持 reset');
+      const options = flags(args.slice(3), ['data-root', 'auth-store']);
+      const dataRoot = required(options['data-root'], 'data-root');
+      if (!path.isAbsolute(dataRoot)) throw new CliUsageError('data-root 必须是工作台数据根的绝对路径');
+      console.log(JSON.stringify(await manageWorkbenchPassword({ dataRoot, directory: options['auth-store'], reset: true, signal: cliAbortController.signal })));
+      return 0;
+    }
+    if (serveWorkbench && args[1] === 'login') {
+      const options = flags(args.slice(2), ['origin', 'token-file', 'data-root', 'auth-store']);
+      if (options['data-root'] !== undefined) {
+        if (options.origin !== undefined || options['token-file'] !== undefined) throw new CliUsageError('口令登录用 data-root，旧 Token 登录用 origin/token-file，不能混用');
+        if (!path.isAbsolute(options['data-root'])) throw new CliUsageError('data-root 必须是工作台数据根的绝对路径');
+        console.log(JSON.stringify(await manageWorkbenchPassword({ dataRoot: options['data-root'], directory: options['auth-store'], signal: cliAbortController.signal })));
+        return 0;
+      }
+      if (options['auth-store'] !== undefined) throw new CliUsageError('auth-store 需要同时明确 data-root');
+      const origin = required(options.origin, 'origin'), tokenFile = required(options['token-file'], 'token-file');
+      if (!/^http:\/\/127\.0\.0\.1:[1-9]\d{0,4}$/.test(origin) || Number(origin.split(':').at(-1)) > 65535) throw new CliUsageError('origin 必须是启动时输出的 http://127.0.0.1:端口');
+      if (!path.isAbsolute(tokenFile)) throw new CliUsageError('token-file 必须是当前启动文件的绝对路径');
+      let token;
+      const fd = fs.openSync(tokenFile, 'r');
+      try {
+        const info = fs.fstatSync(fd);
+        if (!info.isFile() || info.size > 256) throw new CliUsageError('请选择当前启动生成的小型 Token 文本文件');
+        token = fs.readFileSync(fd, 'utf8').trim();
+      } finally { fs.closeSync(fd); }
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) throw new CliUsageError('Token 文件内容无效，请使用当前启动生成的文件');
+      const response = await fetch(origin + '/api/v0/workbench/login-link', { method: 'POST',
+        headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' }, body: '{}',
+        redirect: 'error', signal: AbortSignal.any([cliAbortController.signal, AbortSignal.timeout(15000)]) });
+      if (!response.ok) throw new CliUsageError(response.status === 401 ? 'Token 已失效，请使用当前服务启动时生成的 Token 文件'
+        : response.status === 404 || response.status === 405 ? '此服务不支持登录链接，请确认地址属于新版 web serve 工作台' : '无法获取登录链接，请检查本机工作台状态');
+      const result = await response.json();
+      if (result.contractVersion !== 0 || typeof result.loginUrl !== 'string' || !result.loginUrl.startsWith(origin + '/#login=')
+          || !/^[A-Za-z0-9_-]{43}$/.test(result.loginUrl.slice((origin + '/#login=').length)) || !Number.isFinite(Date.parse(result.loginExpiresAt))) {
+        throw new CliUsageError('工作台返回的登录链接无效');
+      }
+      console.log(JSON.stringify({ ...result, message: '打开 loginUrl 即可进入；链接 10 分钟内有效、仅用一次，刷新无需重新登录。' }));
+      return 0;
+    }
+    if (!serveWorkbench && args[1] === 'init') {
+      const options = flags(args.slice(2), ['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 initialized = await withApplication(dataRoot, application => application.execute('creation.init', {}, { signal: cliAbortController.signal }));
+      console.log(JSON.stringify(initialized));
+      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 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 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');
+    if (options['auth-store'] !== undefined && !passwordMode) throw new CliUsageError('auth-store 仅用于默认口令工作台；不能与 Token 参数或 api serve 混用');
+    if (!path.isAbsolute(suppliedRoot) || !passwordMode && !path.isAbsolute(options['token-file'] || options['token-dir'])) throw new CliUsageError('data-root 与 token-file/token-dir 必须是绝对路径');
+    let tokenFile = options['token-file'];
+    if (options.port !== undefined && (!/^\d+$/.test(options.port) || Number(options.port) > 65535)) throw new CliUsageError('port 必须是 0–65535 的整数');
+    // Pin the physical root for both the server and the outside-root credential check.
+    let dataRoot;
+    try { dataRoot = fs.realpathSync(suppliedRoot); }
+    catch (_) { throw new CliUsageError('data-root 必须是已初始化且可读取的 Flow 根'); }
+    const authDirectory = passwordMode ? resolveWorkbenchAuthDirectory(dataRoot, options['auth-store']) : undefined;
+    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,
+        ...(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 });
+      ownApi(api);
+      const started = await api.start({ port: options.port === undefined ? 0 : Number(options.port) });
+      if (!passwordMode) {
+        if (options['token-dir']) tokenFile = writeLocalApiTokenDirectory(options['token-dir'], started.accessToken, dataRoot);
+        else writeLocalApiTokenFile(tokenFile, started.accessToken, dataRoot);
+      }
+      console.log(JSON.stringify({ contractVersion: 0, readOnly: !allowLocalWrites && !allowSelection, origin: started.origin,
+        ...(passwordMode ? { authentication: started.authentication, authStore: authDirectory } : { tokenFile }),
+        ...(launch ? { pluginLaunch: launch.summary } : {}),
+        ...(serveWorkbench ? { loginUrl: started.loginUrl, loginExpiresAt: started.loginExpiresAt } : {}),
+        ...(allowConnectionManagement ? { connectionManagement: true } : {}),
+        ...(providerFlags.length ? { providerManagement: true } : {}),
+        ...(started.mcpEndpoint ? { mcpEndpoint: started.mcpEndpoint } : {}),
+        message: passwordMode ? (started.authentication.configured ? '工作台已启动，打开 origin 用访问口令登录；记住设备后可跨正常重启继续使用。'
+          : '首次使用请打开 loginUrl 设置访问口令；之后打开普通地址即可登录，无需 Token 文件。')
+          : serveWorkbench ? (providerFlags.length ? 'Core 工作台与供应商管理已启动；打开 loginUrl 即可进入。配置保存不生成媒体。'
+          : allowConnectionManagement ? 'Core 工作台与连接管理已启动；打开 loginUrl 即可进入。配置连接不执行媒体。'
+          : allowLocalWrites || allowSelection ? 'Core 工作台已启动；打开 loginUrl 即可进入。媒体 API 按显式开关开放。'
+          : launch?.allowedOperations !== undefined ? 'Core 工作台已启动；打开 loginUrl 即可进入。插件业务按启动选择开放，媒体 API 保持只读。'
+          : '只读工作台已启动；打开 loginUrl 即可进入。')
+          : allowExecution ? '有限执行 API 已启动；显式继续才执行，停止只中止本地等待，重启不自动重提。'
+          : allowLocalWrites ? '本地创建 API 已启动；只上传/创建，不执行生成。会话 Token 在指定私有文件中，退出后失效。'
+          : allowSelection ? '本地选择 API 已启动；只更新已完成流程的选择，不执行生成。会话 Token 在指定私有文件中，退出后失效。'
+          : launch?.allowedOperations !== undefined ? '插件业务 API 已启动；按启动选择执行，媒体 API 保持只读。会话 Token 在指定私有文件中，退出后失效。'
+          : '只读本地 API 已启动；会话 Token 在指定私有文件中，退出后失效。' }));
+      await api.closed;
+      return 0;
+    });
+  }
+
+  if (args[0] === 'flow') {
+    const verb = args[1];
+    if (!['init', 'create', 'list', 'inspect', 'continue', 'select', 'export'].includes(verb)) throw new CliUsageError('不支持的 flow 子命令');
+    const needsId = ['inspect', 'continue', 'select', 'export'].includes(verb);
+    if (needsId && (!args[2] || args[2].startsWith('--'))) throw new CliUsageError('缺少 Run ID');
+    const allowed = ['data-root', ...(['create', 'continue'].includes(verb) ? ['provider-config'] : []),
+      ...(['create', 'select'].includes(verb) ? ['input'] : []), ...(verb === 'export' ? ['output'] : [])];
+    const options = flags(args.slice(needsId ? 3 : 2), allowed);
+    const input = ['create', 'select'].includes(verb) ? jsonInput(options.input) : {};
+    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;
+    let result;
+    try {
+      result = await withApplication(options['data-root'], application =>
+        application.execute('flow.' + verb, input, { signal: cliAbortController.signal }), resolveImageCandidates, resolveTaskAdapter);
+    } catch (error) {
+      if (error instanceof GenerationInputError) throw new CliUsageError(error.message);
+      throw error;
+    }
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
   if (args[0] === 'doctor') {
     const rest = args.slice(1);
     if (rest.filter((arg) => arg === '--json').length > 1) throw new CliUsageError('参数重复：--json');
@@ -235,14 +597,14 @@ async function main(args) {
   if (['providers', 'capabilities'].includes(args[0]) && args[1] === 'list') {
     const options = flags(args.slice(2), ['provider-config']);
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
-    const report = args[0] === 'providers' ? providerCatalogSnapshot(catalog) : catalogCapabilitySnapshot(catalog);
+    const report = args[0] === 'providers' ? providerCatalogSnapshot(catalog) : catalogCapabilitySnapshot(catalog, providerRegistry);
     console.log(JSON.stringify(report, null, 2));
     return 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'], assignments: ['list', 'set', 'clear'] };
+    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'] };
     if (!verbs[group].includes(verb)) throw new CliUsageError('未知配置命令');
     const positional = (group === 'providers' && verb === 'remove') || (group === 'models' && verb !== 'list');
     const id = positional ? required(args[2], group === 'providers' || verb === 'discover' ? 'provider-id' : 'model-ref') : undefined;
@@ -259,7 +621,7 @@ async function main(args) {
       }
     }
     const result = await executeConfigCommand(required(options['provider-config'], 'provider-config'), group === 'config' ? verb : group + '.' + verb, input, {
-      signal: cliAbortController.signal,
+      signal: cliAbortController.signal, registry: providerRegistry,
       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 });
@@ -272,14 +634,14 @@ async function main(args) {
         }
         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);
-          const adapter = createConfiguredProviderAdapter(provider, { allowRateLimited: true, modelId });
+          if (mediaCapability === 'image') provider = providerForImageModel(provider, modelId, providerRegistry);
+          const adapter = createConfiguredProviderAdapter(provider, { allowRateLimited: true, modelId, registry: providerRegistry });
           let providerInput = mediaCapability === 'image'
-            ? { prompt: 'red circle', n: 1, ...(['openai-chat-images', 'openai-responses-images'].includes(adapter.protocol) ? {} : {
+            ? { prompt: 'red circle', n: 1, ...(['openai-chat-images', 'openai-responses-images', 'comfyui'].includes(adapter.protocol) ? {} : {
               size: adapter.protocol === 'openai-images' ? '256x256' : '512*512'
             }) }
             : { text: '你好', voice: probeInput.voice || provider.ttsVoice || 'Cherry' };
-          let candidates = [{ adapter, model: qualifiedModelRef(provider.id, modelId), selectionReason: 'explicit', providerBinding: providerTaskBinding(provider) }];
+          let candidates = [{ adapter, model: qualifiedModelRef(provider.id, modelId), selectionReason: 'explicit', providerBinding: providerTaskBinding(provider, providerRegistry) }];
           if (['video', 'transcribe'].includes(mediaCapability)) {
             const normalized = generationInput(mediaCapability, { ...probeInput, model_ref: qualifiedModelRef(provider.id, modelId) },
               { allowVideoPaths: true, allowAudioPath: true });
@@ -320,8 +682,8 @@ async function main(args) {
       } catch (_) { throw new CliUsageError('输出文件已存在或父目录不可写'); }
     }
     const catalog = await generationCatalog(options, 'vision', options['model-ref'] || input.model_ref);
-    if (input.transcribe && !input.transcribe_model_ref) await refreshCatalogDirectories(options['provider-config'], catalog, 'transcribe', { signal: cliAbortController.signal });
-    const execute = runtime => executeVisionCommand({ command, input, catalog, runtime,
+    if (input.transcribe && !input.transcribe_model_ref) await refreshCatalogDirectories(options['provider-config'], catalog, 'transcribe', { signal: cliAbortController.signal, registry: providerRegistry });
+    const execute = runtime => executeVisionCommand({ command, input, catalog, runtime, registry: providerRegistry,
       onRateLimit: event => recordCatalogRateLimit(options['provider-config'], event),
       onModelAvailability: event => recordCatalogAvailability(options['provider-config'], event),
       modelRef: options['model-ref'] || '', signal: cliAbortController.signal,
@@ -358,8 +720,9 @@ async function main(args) {
     const options = flags(args.slice(2), ['data-root', 'input']);
     const input = jsonInput(options.input);
     const command = args[1] === 'diff' ? 'media.diff' : 'media.frames';
-    const result = await withRuntime('writer', options['data-root'], (commands) =>
-      commands.execute(command, input));
+    const result = args[1] === 'diff'
+      ? await withApplication(options['data-root'], application => application.execute(command, input, { signal: cliAbortController.signal }))
+      : await withRuntime('writer', options['data-root'], commands => commands.execute(command, input));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -375,21 +738,25 @@ async function main(args) {
 
   if (args[0] === 'run' && args[1] === 'image') {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
-    const { providerInput, modelRef, sourceArtifactId } = generationInput('image', jsonInput(options.input));
-    const catalog = await generationCatalog(options, 'image-gen', modelRef);
-    const routes = imageCandidatesFromCatalog(catalog, modelRef);
-    await withRawRuntime('writer', options['data-root'], async (runtime) => {
-      const candidates = routes.map((route) => ({
+    const input = jsonInput(options.input);
+    const resolveImageCandidates = 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)
+        providerBinding: providerTaskBinding(route.provider, providerRegistry)
       }));
-      const result = await createProviderTaskRunner(runtime).submit({
-        capability: 'image', candidates,
-        providerInput, sourceArtifactId
-      });
-      console.log(JSON.stringify(result, null, 2));
-    });
+    };
+    let result;
+    try {
+      result = await withApplication(options['data-root'], application =>
+        application.generateImage(input, { signal: cliAbortController.signal }), resolveImageCandidates);
+    } catch (error) {
+      if (error instanceof GenerationInputError) throw new CliUsageError(error.message);
+      throw error;
+    }
+    console.log(JSON.stringify(result, null, 2));
     return 0;
   }
 
@@ -399,12 +766,12 @@ async function main(args) {
     const normalized = generationInput('video', jsonInput(options.input), { allowVideoPaths: true });
     const { providerInput, modelRef } = normalized;
     const catalog = await generationCatalog(options, 'video-gen', modelRef);
-    const routes = videoCandidatesFromCatalog(catalog, modelRef);
+    const routes = videoCandidatesFromCatalog(catalog, modelRef, providerRegistry);
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
       const candidates = videoTaskCandidates(routes.map((route) => ({
         adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
-        providerBinding: providerTaskBinding(route.provider)
+        providerBinding: providerTaskBinding(route.provider, providerRegistry)
       })), normalized);
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'video', candidates,
@@ -420,12 +787,12 @@ async function main(args) {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
     const normalized = generationInput('music', jsonInput(options.input));
     const catalog = await generationCatalog(options, 'music-gen', normalized.modelRef);
-    const routes = musicCandidatesFromCatalog(catalog, normalized.modelRef);
+    const routes = musicCandidatesFromCatalog(catalog, normalized.modelRef, providerRegistry);
     let result;
     await withRawRuntime('writer', options['data-root'], async runtime => {
       result = await generateMusicTask({ runner: createProviderTaskRunner(runtime),
         candidates: routes.map(route => ({ adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
-          selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) })),
+          selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider, providerRegistry) })),
         providerInput: normalized.providerInput, options: normalized.musicOptions, signal: cliAbortController.signal });
       console.log(JSON.stringify(result, null, 2));
     });
@@ -436,12 +803,12 @@ async function main(args) {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
     const { providerInput, modelRef } = generationInput('tts', jsonInput(options.input));
     const catalog = await generationCatalog(options, 'tts', modelRef);
-    const routes = ttsCandidatesFromCatalog(catalog, modelRef);
+    const routes = ttsCandidatesFromCatalog(catalog, modelRef, providerRegistry);
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
       const candidates = routes.map((route) => ({
         adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
-        providerBinding: providerTaskBinding(route.provider)
+        providerBinding: providerTaskBinding(route.provider, providerRegistry)
       }));
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'tts', candidates,
@@ -458,7 +825,7 @@ async function main(args) {
     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);
+    const routes = transcribeCandidatesFromCatalog(catalog, normalized.modelRef, providerRegistry);
     let providerInput = normalized.providerInput;
     if (normalized.audioPath) {
       if (!fs.existsSync(normalized.audioPath)) throw new CliUsageError('音频文件不存在');
@@ -471,7 +838,7 @@ async function main(args) {
       const candidates = routes.map((route) => ({
         adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
-        providerBinding: providerTaskBinding(route.provider)
+        providerBinding: providerTaskBinding(route.provider, providerRegistry)
       }));
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'transcribe', candidates,
@@ -489,7 +856,7 @@ async function main(args) {
     const inspected = await withRuntime('reader', options['data-root'], commands => commands.execute('task.inspect', { task_id: args[2] }));
     const catalog = coreTaskWaitFinished(inspected.task) ? null : loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     const result = await withRuntime(catalog ? 'writer' : 'reader', options['data-root'], commands => commands.execute('task.wait', input), {
-      ...(catalog ? { resolveTaskAdapter: task => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task) } : {}) });
+      ...(catalog ? { resolveTaskAdapter: task => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task, providerRegistry), options, task) } : {}) });
     console.log(JSON.stringify(result, null, 2));
     return result.timedOut ? 3 : result.ready ? 0 : 1;
   }
@@ -499,7 +866,7 @@ async function main(args) {
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.observe', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
+      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task, providerRegistry), options, task)
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -510,7 +877,7 @@ async function main(args) {
     const catalog = options['provider-config'] ? loadProviderCatalog(options['provider-config']) : null;
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.redeliver', { task_id: args[2] }), {
-      ...(catalog ? { resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task) } : {})
+      ...(catalog ? { resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task, providerRegistry), options, task) } : {})
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -521,7 +888,7 @@ async function main(args) {
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.cancel', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
+      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task, providerRegistry), options, task)
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -545,19 +912,19 @@ async function main(args) {
       resolveTaskCandidates: async ({ capability, modelRef }) => {
         const catalog = await generationCatalog(options, { image: 'image-gen', video: 'video-gen', music: 'music-gen' }[capability] || capability, modelRef);
         return (capability === 'video'
-        ? videoCandidatesFromCatalog(catalog, modelRef || undefined)
+        ? videoCandidatesFromCatalog(catalog, modelRef || undefined, providerRegistry)
         : capability === 'tts'
-          ? ttsCandidatesFromCatalog(catalog, modelRef || undefined)
+          ? ttsCandidatesFromCatalog(catalog, modelRef || undefined, providerRegistry)
           : capability === 'music'
-            ? musicCandidatesFromCatalog(catalog, modelRef || undefined)
+            ? musicCandidatesFromCatalog(catalog, modelRef || undefined, providerRegistry)
           : capability === 'transcribe'
-            ? transcribeCandidatesFromCatalog(catalog, modelRef || undefined)
-            : imageCandidatesFromCatalog(catalog, modelRef || undefined)
+            ? transcribeCandidatesFromCatalog(catalog, modelRef || undefined, providerRegistry)
+            : imageCandidatesFromCatalog(catalog, modelRef || undefined, providerRegistry)
       ).map((route) => ({
         adapter: trackedProviderAdapter(route.provider, options),
         model: route.modelRef,
         selectionReason: route.selectionReason,
-        providerBinding: providerTaskBinding(route.provider)
+        providerBinding: providerTaskBinding(route.provider, providerRegistry)
       }));
       }
     });
@@ -567,8 +934,8 @@ async function main(args) {
 
   if (args[0] === 'task' && args[1] === 'inspect' && args[2]) {
     const options = flags(args.slice(3), ['data-root']);
-    const result = await withRuntime('reader', options['data-root'], (commands) =>
-      commands.execute('task.inspect', { task_id: args[2] }));
+    const result = await withApplication(options['data-root'], application =>
+      application.execute('task.inspect', { task_id: args[2] }, { signal: cliAbortController.signal }));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -584,15 +951,16 @@ async function main(args) {
 
   if (args[0] === 'artifact' && args[1] === 'import') {
     const options = flags(args.slice(2), ['data-root', 'input']);
-    const result = await withRuntime('writer', options['data-root'], commands => commands.execute('artifact.import', jsonInput(options.input)));
+    const result = await withApplication(options['data-root'], application =>
+      application.execute('artifact.import', jsonInput(options.input), { signal: cliAbortController.signal }));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
 
   if (args[0] === 'artifact' && args[1] === 'inspect' && args[2]) {
     const options = flags(args.slice(3), ['data-root']);
-    const result = await withRuntime('reader', options['data-root'], (commands) =>
-      commands.execute('artifact.inspect', { artifact_id: args[2] }));
+    const result = await withApplication(options['data-root'], application =>
+      application.execute('artifact.inspect', { artifact_id: args[2] }, { signal: cliAbortController.signal }));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -600,8 +968,8 @@ async function main(args) {
   if (args[0] === 'artifact' && args[1] === 'list') {
     const options = flags(args.slice(2), ['data-root', 'offset', 'limit', 'kind', 'media-type', 'task-id']);
     const input = Object.fromEntries(Object.entries(options).filter(([key]) => key !== 'data-root').map(([key, value]) => [key.replaceAll('-', '_'), ['offset', 'limit'].includes(key) ? Number(value) : value]));
-    const result = await withRuntime('reader', options['data-root'], (commands) =>
-      commands.execute('artifact.list', input));
+    const result = await withApplication(options['data-root'], application =>
+      application.execute('artifact.list', input, { signal: cliAbortController.signal }));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -626,11 +994,11 @@ async function main(args) {
 
   if (args[0] === 'artifact' && args[1] === 'export' && args[2]) {
     const options = flags(args.slice(3), ['data-root', 'output']);
-    const result = await withRuntime('writer', options['data-root'], (commands) =>
-      commands.execute('artifact.export', {
+    const result = await withApplication(options['data-root'], application =>
+      application.execute('artifact.export', {
         artifact_id: args[2],
         output_path: required(options.output, 'output')
-      }));
+      }, { signal: cliAbortController.signal }));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -639,11 +1007,25 @@ async function main(args) {
 }
 
 try {
-  process.exitCode = await main(process.argv.slice(2));
+  const args = [], entries = [], raw = process.argv.slice(2);
+  for (let index = 0; index < raw.length; index++) {
+    if (raw[index] !== '--provider-extension') args.push(raw[index]);
+    else {
+      const entry = raw[++index];
+      if (!entry || entry.startsWith('--')) throw new CliUsageError('--provider-extension 缺少入口路径');
+      entries.push(entry);
+    }
+  }
+  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(); }
 } catch (error) {
   const code = error && error.code || 'IRIS_CLI_FAILED';
   const message = error && error.message || '命令执行失败';
-  console.error(code + ': ' + message);
+  if (error.diagnostic) console.error(JSON.stringify(error.diagnostic));
+  else console.error(code + ': ' + message);
   if (error instanceof CliUsageError) console.error('\n' + usage());
   process.exitCode = error instanceof CliUsageError ? 2 : 1;
 }