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

package/lib/local-creation.js

@@ -4,45 +4,122 @@ import { createCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
 import { createImageFlowService } from './image-flow.js';
 import { readImportImage } from './image-import.js';
 import { normalizeGenerationInput } from './generation-input.js';
+import { readFlowRun, requireAudioRoot } from './flow-store.js';
+import { readImportAudio, normalizeAudioFlowInput } from './audio-flow-input.js';
+import { VIDEO_RECIPE, normalizeVideoFlowInput } from './video-flow-input.js';
 import { initializeCreationRoot, inspectCreationRoot, creationRequestId, creationInputDigest,
-  readCreationRequest, publishCreationRequest, completeCreationRequest, creationFail } from './creation-request-store.js';
+  readCreationRequest, publishCreationRequest, completeCreationRequest, creationFail, CREATION_KINDS, isImportCreation } from './creation-request-store.js';
 
 const sha = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
-function flowInput(input) {
+function verifyImported(artifact, intent) {
+  if (artifact.digest.value !== intent.sha256 || artifact.size !== intent.size || artifact.mediaType !== intent.mediaType
+      || artifact.kind !== (intent.mediaType.startsWith('audio/') ? 'imported-audio' : 'imported-image') || artifact.createdAt !== intent.createdAt
+      || JSON.stringify(artifact.metadata) !== JSON.stringify(intent.metadata) || artifact.relations.length) {
+    creationFail('IRIS_CREATION_RESULT_CONFLICT', '原作品与请求意图不一致');
+  }
+  return artifact;
+}
+function flowInput(input, generate = false) {
+  const required = generate ? ['modelRef', 'prompt'] : ['sourceArtifactId', 'modelRef', 'prompt'];
   if (!input || typeof input !== 'object' || Array.isArray(input)
-      || Object.keys(input).some(key => !['sourceArtifactId', 'modelRef', 'prompt', 'size'].includes(key))
-      || !['sourceArtifactId', 'modelRef', 'prompt'].every(key => typeof input[key] === 'string')
+      || Object.keys(input).some(key => ![...required, 'size', ...(generate ? ['workflowParameters'] : [])].includes(key))
+      || !required.every(key => typeof input[key] === 'string')
       || input.size !== undefined && typeof input.size !== 'string') {
     creationFail('IRIS_CREATION_INPUT_INVALID', '流程创建只接受来源作品、明确模型、Prompt 和可选 size');
   }
-  const normalized = normalizeGenerationInput('image', { source_artifact_id: input.sourceArtifactId,
-    model_ref: input.modelRef, prompt: input.prompt, ...(input.size !== undefined ? { size: input.size } : {}) });
-  return { source_artifact_id: normalized.sourceArtifactId, model_ref: normalized.modelRef,
+  const normalized = normalizeGenerationInput('image', { ...(!generate ? { source_artifact_id: input.sourceArtifactId } : {}),
+    model_ref: input.modelRef, prompt: input.prompt, ...(input.size !== undefined ? { size: input.size } : {}),
+    ...(input.workflowParameters !== undefined ? { workflow_parameters: input.workflowParameters } : {}) });
+  return { ...(normalized.sourceArtifactId ? { source_artifact_id: normalized.sourceArtifactId } : {}), model_ref: normalized.modelRef,
     ...normalized.providerInput };
 }
-export function createLocalCreationService(runtime, { resolveImageCandidates, onPrepared } = {}) {
-  const flows = createImageFlowService(runtime, { resolveImageCandidates });
+export function createLocalCreationService(runtime, { resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates, onPrepared } = {}) {
+  const flows = createImageFlowService(runtime, { resolveImageCandidates, resolveAudioCandidates, resolveVideoCandidates });
   function execute(name, input) {
+    if (name === 'creation.root' || name === 'creation.lookup') {
+      return runtime.run('inspect', ({ dataRoot, signal }) => {
+        signal.throwIfAborted();
+        const fields = name === 'creation.root' ? [] : ['kind', 'key'];
+        if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== fields.length
+            || fields.some(key => !Object.hasOwn(input, key))
+            || name === 'creation.lookup' && (!CREATION_KINDS.includes(input.kind) || typeof input.key !== 'string')) {
+          creationFail('IRIS_CREATION_INPUT_INVALID', '需要明确的创建类型和原 Key');
+        }
+        const marker = inspectCreationRoot(dataRoot, { allowAbsent: true });
+        if (name === 'creation.root') return { contractVersion: 0, rootId: marker?.rootId ?? null,
+          ...([2, 3, 4].includes(marker?.schemaVersion) ? { imageGeneration: true } : {}), ...([3, 4].includes(marker?.schemaVersion) ? { audio: true } : {}),
+          ...(marker?.schemaVersion === 4 ? { video: true } : {}) };
+        if (!marker) creationFail('IRIS_CREATION_NOT_FOUND', '此数据根尚无创建请求区');
+        const id = creationRequestId(marker, input.kind, input.key);
+        const request = readCreationRequest(dataRoot, id, marker);
+        if (!request) creationFail('IRIS_CREATION_NOT_FOUND', '此数据根没有对应的创建请求');
+        if (request.kind !== input.kind) creationFail('IRIS_CREATION_RESULT_CONFLICT', '原请求类型与查询身份不一致');
+        const intent = request.intent;
+        let result = null;
+        if (isImportCreation(request.kind)) {
+          let artifact;
+          try { artifact = readCoreArtifactBytes(dataRoot, intent.artifactId).artifact; }
+          catch (error) {
+            if (error.code !== 'IRIS_ARTIFACT_NOT_FOUND') throw error;
+            if (request.state === 'succeeded') creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '原创建结果已不可用，不会重新创建');
+          }
+          if (artifact) result = { artifactId: verifyImported(artifact, intent).id };
+        } else {
+          let run;
+          try { run = readFlowRun(dataRoot, intent.runId); }
+          catch (error) {
+            if (error.code !== 'IRIS_FLOW_NOT_FOUND') throw error;
+            if (request.state === 'succeeded') creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '原创建流程已不可用，不会重新创建');
+          }
+          if (run) {
+            try { flows.inspectCreation(dataRoot, intent, { allowCreate: false }); }
+            catch (error) {
+              if (['IRIS_FLOW_NOT_FOUND', 'IRIS_ARTIFACT_NOT_FOUND'].includes(error.code)) {
+                creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '原创建流程的作品已不可用，不会恢复数据');
+              }
+              throw error;
+            }
+            result = { runId: run.id };
+          }
+        }
+        return { contractVersion: 0, kind: request.kind, state: request.state, result };
+      });
+    }
     return runtime.run('execute', async ({ dataRoot, signal }) => {
       if (name === 'creation.init') return { contractVersion: 0, root: initializeCreationRoot(dataRoot) };
-      if (!['creation.image', 'creation.flow'].includes(name)) throw new TypeError('未知本地创建操作');
-      const kind = name === 'creation.image' ? 'image-import' : 'flow-create';
+      const kinds = { 'creation.image': 'image-import', 'creation.flow': 'flow-create', 'creation.generate': 'generation-create',
+        'creation.audio': 'audio-import', 'creation.speech': 'speech-create', 'creation.transcribe': 'transcription-create', 'creation.video': 'video-create' };
+      const kind = kinds[name];
+      if (!kind) throw new TypeError('未知本地创建操作');
+      if (['audio-import', 'speech-create', 'transcription-create'].includes(kind)) requireAudioRoot(dataRoot);
       const marker = inspectCreationRoot(dataRoot), id = creationRequestId(marker, kind, input.key);
       let source, owned;
-      if (kind === 'image-import') {
-        source = await readImportImage({ imageBytes: input.bytes }, signal);
+      if (isImportCreation(kind)) {
+        source = kind === 'audio-import' ? readImportAudio(input.bytes, input.mediaType) : await readImportImage({ imageBytes: input.bytes }, signal);
         if (source.mediaType !== input.mediaType) creationFail('IRIS_CREATION_MEDIA_MISMATCH', '图片真实格式与 Content-Type 不一致');
         owned = { mediaType: source.mediaType, size: source.bytes.length, sha256: sha(source.bytes) };
-      } else owned = flowInput(input.value);
+      } else if (['speech-create', 'transcription-create'].includes(kind)) {
+        const value = input.value, speech = kind === 'speech-create';
+        const allowed = speech ? ['modelRef', 'text', 'voice'] : ['modelRef', 'sourceArtifactId'];
+        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !allowed.includes(key))) creationFail('IRIS_CREATION_INPUT_INVALID', '音频创建输入无效');
+        owned = normalizeAudioFlowInput(speech ? 'speech/v0' : 'transcribe/v0', { model_ref: value.modelRef,
+          ...(speech ? { text: value.text, ...(value.voice !== undefined ? { voice: value.voice } : {}) } : { source_artifact_id: value.sourceArtifactId }) });
+      } else if (kind === 'video-create') {
+        const value = input.value;
+        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['modelRef', 'prompt', 'size', 'duration'].includes(key))) creationFail('IRIS_CREATION_INPUT_INVALID', '文生视频输入无效');
+        owned = normalizeVideoFlowInput({ model_ref: value.modelRef, prompt: value.prompt,
+          ...(value.size !== undefined ? { size: value.size } : {}), ...(value.duration !== undefined ? { duration: value.duration } : {}) });
+      } else owned = flowInput(input.value, kind === 'generation-create');
       const inputDigest = creationInputDigest(kind, owned);
       let request = readCreationRequest(dataRoot, id, marker);
       const replay = Boolean(request);
       if (request && request.inputDigest !== inputDigest) creationFail('IRIS_CREATION_KEY_CONFLICT', '该 Key 已绑定其他输入，请保留原请求或为新动作使用新 Key');
       if (!request) {
-        const intent = kind === 'image-import'
+        const intent = isImportCreation(kind)
           ? { artifactId: 'artifact_' + crypto.randomBytes(12).toString('hex'), ...owned,
             metadata: source.metadata, createdAt: new Date().toISOString() }
-          : await flows.prepareCreation(dataRoot, signal, owned);
+          : await flows.prepareCreation(dataRoot, signal, { ...owned, ...(kind === 'speech-create' ? { recipe: 'speech/v0' }
+            : kind === 'transcription-create' ? { recipe: 'transcribe/v0' } : kind === 'video-create' ? { recipe: VIDEO_RECIPE } : {}) });
         signal.throwIfAborted();
         request = publishCreationRequest(dataRoot, { schemaVersion: 0, id, rootId: marker.rootId, kind,
           inputDigest, createdAt: intent.createdAt, intent, state: 'prepared' });
@@ -51,10 +128,10 @@ export function createLocalCreationService(runtime, { resolveImageCandidates, on
       signal.throwIfAborted();
       let result;
       const intent = request.intent;
-      if (kind === 'image-import') {
+      if (isImportCreation(kind)) {
         if (request.state === 'prepared') {
           result = createCoreArtifact(dataRoot, { artifactId: intent.artifactId, bytes: source.bytes,
-            mediaType: intent.mediaType, kind: 'imported-image', metadata: intent.metadata,
+            mediaType: intent.mediaType, kind: kind === 'audio-import' ? 'imported-audio' : 'imported-image', metadata: intent.metadata,
             expectedDigest: intent.sha256, expectedSize: intent.size, createdAt: intent.createdAt });
         } else {
           try { result = readCoreArtifactBytes(dataRoot, intent.artifactId).artifact; }
@@ -63,12 +140,7 @@ export function createLocalCreationService(runtime, { resolveImageCandidates, on
             creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '该请求的原结果已不可用；不会重新创建或恢复已删除作品');
           }
         }
-        if (result.digest.value !== intent.sha256 || result.size !== intent.size || result.mediaType !== intent.mediaType
-            || result.kind !== 'imported-image' || result.createdAt !== intent.createdAt
-            || JSON.stringify(result.metadata) !== JSON.stringify(intent.metadata) || result.relations.length) {
-          creationFail('IRIS_CREATION_RESULT_CONFLICT', '原作品与请求意图不一致');
-        }
-        result = { artifact: result };
+        result = { artifact: verifyImported(result, intent) };
       } else {
         try { result = { flow: flows.inspectCreation(dataRoot, intent, { allowCreate: request.state === 'prepared' }) }; }
         catch (error) {

package/lib/local-operations.js

@@ -0,0 +1,36 @@
+// Explicit, store-only application surface; no Provider, scheduling loop or HTTP ownership.
+import { initializeExecutionRoot, inspectExecutionRoot, acceptOperation, transitionOperation,
+  readOperation, operationId, listOperations, projectOperation, operationFail } from './operation-store.js';
+
+export function createLocalOperationService(runtime) {
+  function execute(name, input) {
+    const readOnly = ['operation.inspect', 'operation.lookup', 'operation.list'].includes(name);
+    return runtime.run(readOnly ? 'inspect' : 'execute', ({ dataRoot, signal }) => {
+      signal.throwIfAborted();
+      if (name === 'execution.init') {
+        if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['imageGeneration', 'audio', 'video'].includes(key))
+            || ['imageGeneration', 'audio', 'video'].some(key => input[key] !== undefined && typeof input[key] !== 'boolean')) operationFail('IRIS_OPERATION_INPUT_INVALID', 'execution.init 只接受可选 imageGeneration/audio/video 开关');
+        return { contractVersion: 0, root: initializeExecutionRoot(dataRoot, input), executionEnabled: false };
+      }
+      if (name === 'operation.accept') {
+        const result = acceptOperation(dataRoot, input);
+        return { contractVersion: 0, operation: projectOperation(result.operation), idempotentReplay: result.idempotentReplay };
+      }
+      if (name === 'operation.transition') return { contractVersion: 0, operation: projectOperation(transitionOperation(dataRoot, input)) };
+      if (name === 'operation.list') {
+        const result = listOperations(dataRoot, input);
+        return { contractVersion: 0, ...result, operations: result.operations.map(projectOperation) };
+      }
+      if (name === 'operation.inspect' || name === 'operation.lookup') {
+        const key = name === 'operation.inspect' ? 'id' : 'key';
+        if (!input || Object.keys(input).length !== 1 || typeof input[key] !== 'string') operationFail('IRIS_OPERATION_INPUT_INVALID', '需要单个 Operation ID 或请求 Key');
+        const marker = inspectExecutionRoot(dataRoot), id = key === 'id' ? input.id : operationId(marker, input.key);
+        const record = readOperation(dataRoot, id, marker);
+        if (!record) operationFail('IRIS_OPERATION_NOT_FOUND', 'Operation 不存在');
+        return { contractVersion: 0, operation: projectOperation(record) };
+      }
+      throw new TypeError('未知 Operation 存储操作');
+    });
+  }
+  return Object.freeze({ execute });
+}

package/lib/local-request-root.js

@@ -0,0 +1,86 @@
+// Private request containers. Version selection is explicit; readers never initialize or migrate.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate } from './private-storage.js';
+import { inspectFlowRoot } from './flow-store.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE, isAbandonedWriterPreparation } from './core-writer-lease.js';
+import { inspectRunnerArea } from './execution-ownership.js';
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+export function requestRootFail(code, message) { throw Object.assign(new Error(message), { code }); }
+const invalid = () => requestRootFail('IRIS_CREATION_STORE_INVALID', '创建请求区未知、损坏或尚未完整初始化');
+function directory(root, segments, create = false) {
+  let current = root;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+  }
+  return current;
+}
+export function requestDirectory(root, marker, leaf) {
+  return directory(root, ['creation-requests', 'v' + marker.schemaVersion, ...(leaf ? [leaf] : [])]);
+}
+export function inspectLocalRequestRoot(root, { allowAbsent = false } = {}) {
+  let base;
+  try { base = directory(root, ['creation-requests']); }
+  catch (error) {
+    if (error.code === 'ENOENT' && !fs.existsSync(path.join(root, 'creation-requests'))) {
+      if (allowAbsent) return null;
+      requestRootFail('IRIS_CREATION_ROOT_REQUIRED', '请先在空的专用 Flow 根显式执行 api init 或 execution init');
+    }
+    if (error.code === 'ENOENT') invalid();
+    throw error;
+  }
+  try {
+    const versions = fs.readdirSync(base);
+    if (versions.length !== 1 || !['v0', 'v1', 'v2', 'v3', 'v4'].includes(versions[0])) invalid();
+    const schemaVersion = Number(versions[0].slice(1)), version = directory(root, ['creation-requests', versions[0]]);
+    const allowed = schemaVersion === 0 ? ['root.json', 'requests'] : ['root.json', 'requests', 'operations', 'runner'];
+    if (fs.readdirSync(version).some(name => !allowed.includes(name) && !/^root\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name))) invalid();
+    const file = path.join(version, 'root.json'), stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) invalid();
+    let marker;
+    try { marker = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+    if (!marker || typeof marker !== 'object' || Array.isArray(marker)
+        || Object.keys(marker).length !== 4 || !['schemaVersion', 'kind', 'rootId', 'createdAt'].every(key => Object.hasOwn(marker, key))
+        || marker.schemaVersion !== schemaVersion || marker.kind !== (schemaVersion === 0 ? 'iris-creation-requests' : 'iris-execution-requests')
+        || !UUID.test(marker.rootId) || typeof marker.createdAt !== 'string'
+        || !Number.isFinite(Date.parse(marker.createdAt)) || new Date(marker.createdAt).toISOString() !== marker.createdAt) invalid();
+    directory(root, ['creation-requests', versions[0], 'requests']);
+    if (schemaVersion >= 1) {
+      inspectFlowRoot(root);
+      directory(root, ['creation-requests', versions[0], 'operations']);
+      // A separate, fully checked Core lease owns execution; it does not occupy the business writer.
+      try { inspectRunnerArea(directory(root, ['creation-requests', versions[0], 'runner'])); }
+      catch (error) { if (error.code === 'IRIS_EXECUTION_LEASE_INVALID') invalid(); throw error; }
+    }
+    return structuredClone(marker);
+  } catch (error) { if (error.code === 'ENOENT') invalid(); throw error; }
+}
+
+export function initializeLocalRequestRoot(root, schemaVersion) {
+  if (![0, 1, 2, 3, 4].includes(schemaVersion)) throw new TypeError('未知请求容器版本');
+  const existing = inspectLocalRequestRoot(root, { allowAbsent: true });
+  if (existing) {
+    if (existing.schemaVersion !== schemaVersion) requestRootFail('IRIS_CREATION_ROOT_VERSION_CONFLICT', '请求根版本不同；不自动升级、降级或迁移，请使用新的专用根');
+    return existing;
+  }
+  inspectFlowRoot(root);
+  if (fs.readdirSync(root).some(name => !['flow-store', WRITER_LEASE_DIR, WRITER_INTENT_FILE].includes(name) && !isAbandonedWriterPreparation(root, name))
+      || fs.readdirSync(path.join(root, 'flow-store')).some(name => name !== 'v0')
+      || fs.readdirSync(path.join(root, 'flow-store/v0')).some(name => !['root.json', 'runs'].includes(name))
+      || fs.readdirSync(path.join(root, 'flow-store/v0/runs')).length) {
+    requestRootFail('IRIS_CREATION_ROOT_NOT_EMPTY', '请求区仅在新的空 Flow 根初始化；不转换已有创作数据');
+  }
+  const version = 'v' + schemaVersion;
+  for (const leaf of schemaVersion === 0 ? ['requests'] : ['requests', 'operations', 'runner']) {
+    directory(root, ['creation-requests', version, leaf], true);
+  }
+  const marker = { schemaVersion, kind: schemaVersion === 0 ? 'iris-creation-requests' : 'iris-execution-requests',
+    rootId: crypto.randomUUID(), createdAt: new Date().toISOString() };
+  atomicCreatePrivate(path.join(root, 'creation-requests', version, 'root.json'), JSON.stringify(marker, null, 2) + '\n');
+  return structuredClone(marker);
+}

package/lib/local-web-assets.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs/promises';
+
+// Fixed package resources only. Never resolve a request path against a filesystem directory.
+const ASSETS = new Map([
+  ['/', ['index.html', 'text/html; charset=utf-8']],
+  ['/startup.js', ['startup.js', 'text/javascript; charset=utf-8']],
+  ['/app.js', ['app.js', 'text/javascript; charset=utf-8']],
+  ['/transport.js', ['transport.js', 'text/javascript; charset=utf-8']],
+  ['/workbench-login.js', ['workbench-login.js', 'text/javascript; charset=utf-8']],
+  ['/media-client.js', ['media-client.js', 'text/javascript; charset=utf-8']],
+  ['/recovery.js', ['recovery.js', 'text/javascript; charset=utf-8']],
+  ['/creation.js', ['creation.js', 'text/javascript; charset=utf-8']],
+  ['/gallery.js', ['gallery.js', 'text/javascript; charset=utf-8']],
+  ['/plugin-panel.js', ['plugin-panel.js', 'text/javascript; charset=utf-8']],
+  ['/plugin-status.js', ['plugin-status.js', 'text/javascript; charset=utf-8']],
+  ['/plugin-surface.css', ['plugin-surface.css', 'text/css; charset=utf-8']],
+  ['/flow-view.js', ['flow-view.js', 'text/javascript; charset=utf-8']],
+  ['/connections.js', ['connections.js', 'text/javascript; charset=utf-8']],
+  ['/providers.js', ['providers.js', 'text/javascript; charset=utf-8']],
+  ['/network.js', ['network.js', 'text/javascript; charset=utf-8']],
+  ['/comfyui.js', ['comfyui.js', 'text/javascript; charset=utf-8']],
+  ['/appearance.js', ['appearance.js', 'text/javascript; charset=utf-8']],
+  ['/styles.css', ['styles.css', 'text/css; charset=utf-8']],
+  ['/iris-mark.svg', ['../../docs/assets/logo/iris-mark.svg', 'image/svg+xml']]
+]);
+export const LOCAL_WEB_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' blob:; media-src blob:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+
+export async function readLocalWebAsset(pathname) {
+  const entry = ASSETS.get(pathname);
+  if (!entry) return null;
+  return { bytes: await fs.readFile(new URL('./web/' + entry[0], import.meta.url)), mediaType: entry[1] };
+}
+
+export const isLocalWebAsset = pathname => ASSETS.has(pathname);
+
+export const DEFAULT_PANEL = Object.freeze({
+  identity: Object.freeze({ contractVersion: 0, id: 'iris.default-panel', version: '0.1.0' }),
+  has: isLocalWebAsset, read: readLocalWebAsset
+});

package/lib/mcp-bridge.js

@@ -0,0 +1,58 @@
+import { createCoreServiceClient } from './core-service-client.js';
+import { createMcpServerFactory } from './mcp-server.js';
+import { annotateCoreConnectionError, coreConnectionDiagnostic } from './core-connection-diagnostics.js';
+
+/** Official SDK stdio server. All business calls use the same explicitly authorized Core service. */
+export function createMcpBridge({ connectionFile, requestedScopes = ['read'], capabilities, tools, version, stdin = process.stdin, stdout = process.stdout } = {}) {
+  const client = createCoreServiceClient({ connectionFile, requestedScopes, requestedCapabilities: capabilities, requestedTools: tools, harnessVersion: 'Iris MCP bridge ' + version });
+  let state = 'new', handle, disposal, starting, closeRequested = false, resolveClosed, rejectClosed;
+  const closed = new Promise((resolve, reject) => { resolveClosed = resolve; rejectClosed = reject; });
+  void closed.catch(() => {});
+  function requireStarting() {
+    if (closeRequested) throw Object.assign(new Error('MCP 桥启动已停止'), { code: 'IRIS_MCP_CLOSED' });
+  }
+  function start() {
+    if (state !== 'new') return Promise.reject(Object.assign(new Error('MCP 桥只能显式启动一次'), { code: 'IRIS_MCP_CLOSED' }));
+    state = 'starting';
+    starting = (async () => { try {
+      await client.connect();
+      requireStarting();
+      if (client.snapshot().adapterId !== 'iris.mcp') throw Object.assign(new Error('连接文件不是 MCP 授权'), { code: 'IRIS_CONNECTION_INPUT_INVALID' });
+      const { serveStdio, StdioServerTransport } = await import('@modelcontextprotocol/server/stdio');
+      requireStarting();
+      const built = await createMcpServerFactory({ client, version });
+      requireStarting();
+      const transport = new StdioServerTransport(stdin, stdout, { maxBufferSize: 9 * 1024 * 1024 });
+      handle = serveStdio(built.factory, { transport, legacy: 'serve', maxSubscriptions: 4,
+        onerror: () => console.error('[iris] MCP transport error; no private request data logged') });
+      const sdkClose = transport.onclose;
+      transport.onclose = () => { sdkClose?.(); void dispose().catch(error => console.error('[iris] ' + JSON.stringify(coreConnectionDiagnostic(error, { stage: 'shutdown' })))); };
+      state = 'open';
+      return { contractVersion: 0, tools: built.tools, connection: client.snapshot() };
+    } catch (error) {
+      if (!closeRequested) state = 'failed';
+      try { await client.dispose(); } catch (_) { /* Original initialization failure remains the caller's error. */ }
+      if (!closeRequested) rejectClosed(error);
+      throw annotateCoreConnectionError(error, 'startup');
+    } })();
+    return starting;
+  }
+  function dispose() {
+    if (disposal) return disposal;
+    closeRequested = true; state = 'closing';
+    const disconnecting = client.dispose();
+    void disconnecting.catch(() => {});
+    disposal = Promise.resolve().then(async () => {
+      try {
+        if (starting) await Promise.allSettled([starting]);
+        const results = await Promise.allSettled([handle?.close(), disconnecting]);
+        const failed = results.filter(result => result.status === 'rejected');
+        if (failed.length) throw new AggregateError(failed.map(result => result.reason), 'MCP 桥释放失败');
+        state = 'closed'; resolveClosed({ state, remoteDisconnect: results[1].value.remoteDisconnect });
+      }
+      catch (error) { state = 'failed'; rejectClosed(error); throw error; }
+    });
+    return disposal;
+  }
+  return Object.freeze({ start, dispose, closed, snapshot: () => ({ state, connection: client.snapshot() }) });
+}

package/lib/mcp-check.js

@@ -0,0 +1,26 @@
+import { createCoreServiceClient } from './core-service-client.js';
+import { checkedClientConnection, readPrivateConnectionJson, connectionFail } from './core-connections.js';
+import { bridgeToolsForScopes } from './core-bridge-tools.js';
+import { coreConnectionDiagnostic } from './core-connection-diagnostics.js';
+
+/** Explicit configuration + one temporary handshake. Never opens a writer, calls media or starts Core. */
+export async function checkMcpConnection({ connectionFile, scopes = ['read'], capabilities, tools } = {}) {
+  const result = { contractVersion: 0, ok: false, checks: [], lifecycle: { core: 'externally-started', bridge: 'client-owned' }, mediaTested: false };
+  let client, stage = 'configuration';
+  try {
+    const connection = checkedClientConnection(readPrivateConnectionJson(connectionFile));
+    if (connection.adapterId !== 'iris.mcp') connectionFail('IRIS_CONNECTION_INPUT_INVALID', '请选择 MCP client.json');
+    result.checks.push('configuration'); result.origin = connection.origin;
+    client = createCoreServiceClient({ connection, requestedScopes: scopes, requestedCapabilities: capabilities, requestedTools: tools,
+      harnessVersion: 'Iris MCP connection check' });
+    stage = 'handshake'; await client.connect();
+    result.checks.push('transport', 'handshake'); result.connection = client.snapshot();
+    result.tools = bridgeToolsForScopes(result.connection.scopes, result.connection.capabilities, result.connection.tools, result.connection.pluginOperations).map(tool => tool.name);
+    result.checks.push('tool-selection'); result.ok = true;
+  } catch (error) { result.error = coreConnectionDiagnostic(error, { stage }); }
+  finally {
+    if (client) try { result.remoteDisconnect = (await client.dispose()).remoteDisconnect; }
+    catch (error) { result.ok = false; result.error = coreConnectionDiagnostic(error, { stage: 'disconnect' }); }
+  }
+  return result;
+}

package/lib/mcp-config.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkedClientConnection, readPrivateConnectionJson, checkedConnectionScopes, connectionFail } from './core-connections.js';
+import { checkedBridgeCapabilities, checkedBridgeTools, selectedBridgeTools } from './core-bridge-selection.js';
+import { resolveMcpConfigurationChoice, formatMcpConfiguration } from './mcp-delivery.js';
+
+/** Export configuration only. Never starts Core, contacts a Provider, or edits a harness configuration. */
+export function exportMcpConfiguration({ connectionFile, scopes, capabilities, tools, transport, format, presetId, output } = {}) {
+  const connection = checkedClientConnection(readPrivateConnectionJson(connectionFile));
+  if (connection.adapterId !== 'iris.mcp') connectionFail('IRIS_CONNECTION_INPUT_INVALID', '请选择 MCP 连接文件');
+  ({ transport, format } = resolveMcpConfigurationChoice({ transport, format, presetId }));
+  let entry;
+  if (transport === 'stdio') {
+    if (scopes === undefined) scopes = ['read']; checkedConnectionScopes(scopes);
+    if (capabilities === undefined) capabilities = connection.capabilities; checkedBridgeCapabilities(capabilities);
+    if (tools === undefined) tools = selectedBridgeTools(capabilities, connection.tools, connection.pluginOperations); checkedBridgeTools(tools);
+    if (capabilities.some(id => !connection.capabilities.includes(id)) || tools.some(name => !connection.tools.includes(name) || !selectedBridgeTools(capabilities, undefined, connection.pluginOperations).includes(name))) {
+      connectionFail('IRIS_CONNECTION_CAPABILITY_DENIED', '导出配置不能扩大连接的功能或工具范围');
+    }
+    entry = { command: process.execPath, args: [fileURLToPath(new URL('../bin/dsh-iris.js', import.meta.url)), 'mcp', 'serve',
+      '--connection-file', path.resolve(connectionFile), '--scopes', scopes.join(','),
+      '--capabilities', capabilities.length ? capabilities.join(',') : 'none', '--tools', tools.length ? tools.join(',') : 'none'] };
+  } else {
+    if (scopes !== undefined || capabilities !== undefined || tools !== undefined) connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'HTTP 的功能/工具/权限在创建连接授权时选择；请导出该专用连接');
+    if (!output) connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'HTTP 配置含认证信息，需要明确的新私有输出文件，不写入 stdout');
+    entry = { url: connection.origin + '/mcp', headers: { Authorization: 'Bearer ' + connection.accessToken } };
+  }
+  const rendered = formatMcpConfiguration(entry, { transport, format });
+  if (!output) return format === 'codex-toml' ? rendered.content : rendered.configuration;
+  if (!path.isAbsolute(output)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '配置输出必须是新的绝对路径');
+  try { fs.realpathSync(path.dirname(output)); }
+  catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) throw error; connectionFail('IRIS_CONNECTION_INPUT_INVALID', '请先创建配置输出的父目录'); }
+  if (transport === 'http') {
+    const parent = fs.realpathSync(path.dirname(output)), privateParent = fs.realpathSync(path.dirname(connectionFile));
+    if (parent !== privateParent || process.platform !== 'win32' && fs.statSync(parent).mode & 0o077) {
+      connectionFail('IRIS_CONNECTION_INPUT_INVALID', '含认证信息的配置只导出到原连接的私有目录');
+    }
+  }
+  fs.writeFileSync(output, rendered.content, { flag: 'wx', mode: 0o600 });
+  return { contractVersion: 0, transport, format, output, containsCredentials: transport === 'http', configurationOnly: true };
+}

package/lib/mcp-delivery.js

@@ -0,0 +1,46 @@
+import { connectionFail } from './core-connections.js';
+
+export const MCP_CONFIG_FORMATS = Object.freeze(['mcpServers', 'entry', 'claude-json', 'codex-toml']);
+const clients = [
+  { id: 'generic', title: '通用 MCP', format: 'mcpServers', documentationUrl: 'https://modelcontextprotocol.io/docs/develop/connect-local-servers', hint: '合并到客户端的 mcpServers 配置，或手动选择单条 entry。' },
+  { id: 'claude', title: 'Claude Code', format: 'claude-json', documentationUrl: 'https://code.claude.com/docs/en/mcp', hint: '将 iris 条目合并到项目 .mcp.json 的 mcpServers；已有配置请保留，随后在 /mcp 确认。' },
+  { id: 'codex', title: 'Codex', format: 'codex-toml', documentationUrl: 'https://learn.chatgpt.com/docs/extend/mcp?surface=cli', hint: '将 [mcp_servers.iris] 段合并到明确选择的 config.toml；保留其他段，随后在 /mcp 确认。' },
+  { id: 'kimi', title: 'Kimi Code', format: 'mcpServers', documentationUrl: 'https://moonshotai.github.io/kimi-code/en/customization/mcp', hint: '合并到明确选择的 mcp.json 的 mcpServers，创建新会话后在 /mcp 确认；安装位置由用户决定。' }
+];
+export const MCP_CONNECTION_PRESETS = Object.freeze(clients.flatMap(client => ['stdio', 'http'].map(transport => Object.freeze({
+  presetId: client.id + '-' + transport, title: client.title + ' · ' + (transport === 'stdio' ? '本机 stdio' : 'HTTP'),
+  transport, format: client.format, documentationUrl: client.documentationUrl, hint: client.hint
+}))));
+
+export function resolveMcpConfigurationChoice({ presetId, transport, format } = {}) {
+  if (presetId !== undefined) {
+    if (transport !== undefined || format !== undefined) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '接入预设不能与手动传输/格式混用');
+    const preset = MCP_CONNECTION_PRESETS.find(item => item.presetId === presetId);
+    if (!preset) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '没有此接入预设；可选择通用 MCP 或手动格式');
+    return { transport: preset.transport, format: preset.format };
+  }
+  if (transport === undefined) transport = 'stdio';
+  if (format === undefined) format = 'mcpServers';
+  if (!['stdio', 'http'].includes(transport) || !MCP_CONFIG_FORMATS.includes(format)) connectionFail('IRIS_CONNECTION_INPUT_INVALID', '配置格式或传输方式无效');
+  return { transport, format };
+}
+
+/** Fixed, typed fields only. No shell interpolation, executable template or arbitrary TOML fragment. */
+export function formatMcpConfiguration(entry, { transport, format }) {
+  let configuration, content, filename = 'iris-mcp.json', mediaType = 'application/json';
+  if (format === 'codex-toml') {
+    const native = transport === 'stdio' ? { command: entry.command, args: entry.args } : { url: entry.url, http_headers: entry.headers };
+    configuration = { mcp_servers: { iris: native } };
+    const lines = ['[mcp_servers.iris]'];
+    for (const [key, value] of Object.entries(native)) {
+      const quote = item => JSON.stringify(item).replace(/\x7f/g, '\\u007f');
+      const text = key === 'http_headers' ? '{ ' + Object.entries(value).map(([name, item]) => quote(name) + ' = ' + quote(item)).join(', ') + ' }' : quote(value);
+      lines.push(key + ' = ' + text);
+    }
+    content = lines.join('\n') + '\n'; filename = 'iris-mcp.toml'; mediaType = 'text/plain';
+  } else {
+    configuration = format === 'entry' ? entry : { mcpServers: { iris: format === 'claude-json' ? { type: transport, ...entry } : entry } };
+    content = JSON.stringify(configuration, null, 2) + '\n';
+  }
+  return { configuration, content, filename, mediaType };
+}