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

package/lib/core-service-client.js

@@ -0,0 +1,170 @@
+import crypto from 'node:crypto';
+import { checkedClientConnection, readPrivateConnectionJson, connectionFail } from './core-connections.js';
+import { MAX_IMPORT_IMAGE_BYTES } from './image-import.js';
+import { annotateCoreConnectionError } from './core-connection-diagnostics.js';
+import { checkedPluginSelection, hasPluginSelection } from './plugin-selection.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}$/;
+const RUN = /^run_[a-f0-9]{24}$/, OP = /^op_[a-f0-9]{64}$/, ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const input = () => connectionFail('IRIS_CONNECTION_INPUT_INVALID', 'Core 服务工具输入无效');
+function reference(value, pattern) { if (typeof value !== 'string' || !pattern.test(value)) input(); return value; }
+
+/** A bounded client of one explicitly authorized Core. It never owns a Core writer or falls back. */
+export function createCoreServiceClient({ connectionFile, connection, requestedScopes = ['read'], requestedCapabilities, requestedTools, requestedPluginOperations,
+  harnessVersion = 'unknown', fetch: fetchImpl = globalThis.fetch } = {}) {
+  if (connectionFile !== undefined && connection !== undefined) throw new TypeError('连接配置只能明确提供一种来源');
+  const runtimeInstanceId = crypto.randomUUID(), lifetime = new AbortController();
+  let state = 'new', config, negotiated, connectionPromise, metadataPromise, metadataKey, metadataAt = 0, disposal;
+  async function request(route, { method = 'GET', value, bytes, key, mediaType, binary = false, signal, handshake = false, disconnect = false } = {}) {
+    if (state !== 'open' && !(handshake && state === 'connecting') && !(disconnect && state === 'closing')) connectionFail('IRIS_CORE_SERVICE_DISCONNECTED', 'Core 服务尚未连接，请显式连接');
+    const headers = { Authorization: 'Bearer ' + config.accessToken, 'Iris-Connection-Id': config.connectionId, 'Iris-Runtime-Id': runtimeInstanceId };
+    if (key !== undefined) headers['Idempotency-Key'] = reference(key, UUID);
+    if (value !== undefined || bytes !== undefined) headers['Content-Type'] = mediaType || 'application/json';
+    const combined = AbortSignal.any([...(disconnect ? [] : [lifetime.signal]), AbortSignal.timeout(disconnect ? 2000 : 15000), ...(signal ? [signal] : [])]);
+    let response;
+    try {
+      response = await fetchImpl(config.origin + route, { method, headers, redirect: 'error', signal: combined,
+        ...(value !== undefined ? { body: JSON.stringify(value) } : bytes !== undefined ? { body: bytes } : {}) });
+    } catch (error) {
+      if (signal?.aborted || !disconnect && lifetime.signal.aborted) throw Object.assign(new Error('Core 请求等待已停止；已接收操作需按原 Key 查询'), { name: 'AbortError', code: 'IRIS_CORE_SERVICE_ABORTED' });
+      throw annotateCoreConnectionError(Object.assign(new Error('Core 服务无法连接，请检查服务状态'), {
+        code: combined.reason?.name === 'TimeoutError' ? 'IRIS_CORE_SERVICE_TIMEOUT' : 'IRIS_CORE_SERVICE_UNAVAILABLE' }), 'transport');
+    }
+    const limit = binary && binary !== 'text' && response.ok ? 64 * 1024 * 1024 : 1024 * 1024;
+    if (Number(response.headers.get('content-length')) > limit) { await response.body?.cancel(); connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应超过有界大小'); }
+    const chunks = []; let size = 0;
+    try {
+      if (response.body) for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > limit) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应超过有界大小');
+        chunks.push(chunk);
+      }
+    } catch (error) {
+      if (error.code === 'IRIS_CORE_SERVICE_RESPONSE_INVALID') throw error;
+      connectionFail('IRIS_CORE_SERVICE_UNAVAILABLE', 'Core 响应中断；请读取原 Operation，不要自动再次提交');
+    }
+    const result = Buffer.concat(chunks, size);
+    if (binary && response.ok) {
+      const mediaType = response.headers.get('content-type');
+      const allowed = binary === 'audio' ? ['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac'] : binary === 'text' ? ['text/plain'] : ['image/png', 'image/jpeg', 'image/webp'];
+      if (!allowed.includes(mediaType)) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core返回的作品类型与所选入口不一致');
+      return { bytes: result, mediaType };
+    }
+    let body;
+    try { body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(result)); }
+    catch (_) { connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 返回无效 JSON'); }
+    if (!response.ok) {
+      const code = /^IRIS_[A-Z_]+$/.test(body?.error?.code) ? body.error.code : 'IRIS_CORE_SERVICE_REJECTED';
+      throw annotateCoreConnectionError(Object.assign(new Error('Core 服务拒绝本次请求；请检查授权、原操作及服务状态'), {
+        code, status: response.status, ...(UUID.test(body?.error?.requestId) ? { requestId: body.error.requestId } : {}) }), handshake ? 'handshake' : disconnect ? 'disconnect' : 'tool');
+    }
+    if (body?.contractVersion !== 0) connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 响应契约不受支持');
+    return body;
+  }
+  function connect() {
+    if (['closing', 'closed'].includes(state)) return Promise.reject(Object.assign(new Error('Core 连接已关闭'), { code: 'IRIS_CORE_SERVICE_DISCONNECTED' }));
+    if (connectionPromise) return connectionPromise;
+    connectionPromise = (async () => {
+      let stage = 'configuration';
+      try {
+        config = checkedClientConnection(connection ?? readPrivateConnectionJson(connectionFile));
+        state = 'connecting'; stage = 'handshake';
+        const pluginChoice = requestedPluginOperations === undefined ? config.pluginOperations : requestedPluginOperations;
+        const result = await request('/api/v0/connections/' + config.connectionId + '/handshake', { method: 'POST', handshake: true,
+          value: { contractVersion: 0, adapterId: config.adapterId, harnessKind: config.harnessKind, runtimeInstanceId,
+            harnessVersion, requestedScopes, requestedCapabilities: requestedCapabilities ?? config.capabilities,
+            requestedTools: requestedTools ?? config.tools,
+            ...(pluginChoice === undefined ? {} : { requestedPluginOperations: checkedPluginSelection(pluginChoice) }) } });
+        if (state !== 'connecting') connectionFail('IRIS_CORE_SERVICE_ABORTED', '连接启动等待已停止');
+        if (result.rootId !== config.rootId || result.connectionId !== config.connectionId || result.instance?.runtimeInstanceId !== runtimeInstanceId
+            || !Array.isArray(result.instance.scopes) || result.instance.scopes.some(scope => !requestedScopes.includes(scope))
+            || !Array.isArray(result.instance.capabilities) || result.instance.capabilities.some(id => !(requestedCapabilities ?? config.capabilities).includes(id))
+            || !Array.isArray(result.instance.tools) || result.instance.tools.some(name => !(requestedTools ?? config.tools).includes(name))) {
+          connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 数据空间或协商身份不一致');
+        }
+        if (checkedPluginSelection(result.instance.pluginOperations).some(pin => !hasPluginSelection(pluginChoice ?? [], pin))) {
+          connectionFail('IRIS_CORE_SERVICE_RESPONSE_INVALID', 'Core 返回了未请求的插件业务依赖');
+        }
+        negotiated = result; metadataKey = null; metadataAt = 0; state = 'open'; return structuredClone(result);
+      } catch (error) { if (!['closing', 'closed'].includes(state)) state = 'disconnected'; throw annotateCoreConnectionError(error, stage); }
+    })();
+    void connectionPromise.then(() => { connectionPromise = null; }, () => { connectionPromise = null; });
+    return connectionPromise;
+  }
+  function snapshot() {
+    return { contractVersion: 0, state, ...(config ? { connectionId: config.connectionId, adapterId: config.adapterId,
+      harnessKind: config.harnessKind, label: config.label, runtimeInstanceId, scopes: negotiated?.instance.scopes || [],
+      capabilities: negotiated?.instance.capabilities || [], tools: negotiated?.instance.tools || [],
+      ...(negotiated?.instance.pluginOperations?.length ? { pluginOperations: structuredClone(negotiated.instance.pluginOperations) } : {}) } : {}) };
+  }
+  async function reportClientInfo(clientInfo, transport) {
+    if (!clientInfo || !negotiated?.connectionFeatures?.includes('client-info')) return;
+    const key = JSON.stringify({ clientInfo, transport });
+    if (key === metadataKey && Date.now() - metadataAt < 60000) return metadataPromise;
+    metadataKey = key; metadataAt = Date.now();
+    const attempt = request('/api/v0/connections/' + config.connectionId + '/client-info', { method: 'POST', value: { clientInfo, transport } });
+    metadataPromise = attempt;
+    void attempt.catch(() => { if (metadataPromise === attempt) { metadataKey = null; metadataAt = 0; } });
+    return metadataPromise;
+  }
+  function dispose() {
+    if (disposal) return disposal;
+    const wasOpen = state === 'open', starting = connectionPromise;
+    state = 'closing'; lifetime.abort();
+    disposal = (async () => {
+      let remoteDisconnect = wasOpen ? 'unconfirmed' : 'not_connected';
+      try {
+        if (wasOpen) {
+          await request('/api/v0/connections/' + config.connectionId + '/disconnect', { method: 'POST', value: {}, disconnect: true });
+          remoteDisconnect = 'confirmed';
+        }
+      } catch (error) {
+        if (!['IRIS_CORE_SERVICE_UNAVAILABLE', 'IRIS_CORE_SERVICE_TIMEOUT', 'IRIS_CORE_SERVICE_ABORTED', 'IRIS_CONNECTION_HANDSHAKE_REQUIRED',
+          'IRIS_CONNECTION_AUTH_REQUIRED', 'IRIS_API_AUTH_REQUIRED', 'IRIS_API_UNAVAILABLE'].includes(error.code)) throw error;
+      } finally {
+        await Promise.allSettled([starting, metadataPromise].filter(Boolean));
+        state = 'closed'; negotiated = null; config = null;
+      }
+      return { state, remoteDisconnect };
+    })();
+    return disposal;
+  }
+  function pageQuery(value = {}) {
+    if (!value || typeof value !== 'object' || Object.keys(value).some(key => !['limit', 'cursor'].includes(key))
+        || value.limit !== undefined && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 30)
+        || value.cursor !== undefined && typeof value.cursor !== 'string') input();
+    return new URLSearchParams(Object.fromEntries(Object.entries(value).map(([key, value]) => [key, String(value)]))).toString();
+  }
+  return Object.freeze({ connect, dispose, snapshot, reportClientInfo,
+    pluginCatalog: (page, options) => request('/api/v0/plugin-operations/catalog?' + new URLSearchParams(page), options),
+    callPlugin({ key, ...value }, options) { return request('/api/v0/plugin-operations', { ...options, method: 'POST', value, key }); },
+    models: options => request('/api/v0/models', options),
+    audioModels: options => request('/api/v0/audio-models', options),
+    connections: options => request('/api/v0/connections', options),
+    runs: (page, options) => request('/api/v0/runs?' + pageQuery(page), options),
+    run: (id, options) => request('/api/v0/runs/' + reference(id, RUN), options),
+    image: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/content', { ...options, binary: true }),
+    audio: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/audio', { ...options, binary: 'audio' }),
+    transcript: (id, options) => request('/api/v0/artifacts/' + reference(id, ARTIFACT) + '/text', { ...options, binary: 'text' }),
+    createImage({ key, bytes, mediaType }, options) {
+      if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > MAX_IMPORT_IMAGE_BYTES || !['image/png', 'image/jpeg', 'image/webp'].includes(mediaType)) input();
+      return request('/api/v0/images', { ...options, method: 'POST', bytes, key, mediaType });
+    },
+    createRun({ key, value }, options) { return request('/api/v0/runs', { ...options, method: 'POST', value, key }); },
+    createGeneration({ key, value }, options) { return request('/api/v0/generations', { ...options, method: 'POST', value, key }); },
+    createAudio({ key, bytes, mediaType }, options) {
+      if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 20 * 1024 * 1024 || !['audio/wav', 'audio/mpeg', 'audio/ogg', 'audio/flac'].includes(mediaType)) input();
+      return request('/api/v0/audio', { ...options, method: 'POST', bytes, key, mediaType });
+    },
+    createSpeech({ key, value }, options) { return request('/api/v0/speeches', { ...options, method: 'POST', value, key }); },
+    createTranscription({ key, value }, options) { return request('/api/v0/transcriptions', { ...options, method: 'POST', value, key }); },
+    continueRun({ key, runId, expectedRevision }, options) {
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1) input();
+      return request('/api/v0/runs/' + reference(runId, RUN) + '/continue', { ...options, method: 'POST', value: { expectedRevision }, key });
+    },
+    operation: (id, options) => request('/api/v0/operations/' + reference(id, OP), options),
+    lookup: (key, options) => request('/api/v0/operations?key=' + reference(key, UUID), options),
+    operations: (runId, page, options) => request('/api/v0/runs/' + reference(runId, RUN) + '/operations?' + pageQuery(page), options),
+    stop: (id, options) => request('/api/v0/operations/' + reference(id, OP) + '/cancel', { ...options, method: 'POST', value: {} })
+  });
+}

package/lib/core-tasks.js

@@ -8,7 +8,8 @@ import { parseModelRef } from './models.js';
 import { providerErrorRecord } from './provider-contract.js';
 import { deriveLegacyStatus, semanticViolations } from './task-semantics.js';
 import { readDeliveryCache } from './core-delivery-cache.js';
-import { flowTaskBinding, readFlowRun, validFlowBinding } from './flow-store.js';
+import { flowStep, flowStepId, flowTaskBinding, flowCapability, readFlowRun, validFlowBinding } from './flow-store.js';
+import { checkedPluginDependency, assertPluginDependencyMatches, PluginContractError } from './plugin-contract.js';
 
 const STORE_DIR = 'task-store';
 const STORE_VERSION = 'v0';
@@ -111,8 +112,9 @@ function validateRecord(record, expectedId) {
       || (record.deliveryCache !== undefined && record.deliveryCache !== true)
       || (record.providerBinding !== undefined && !PROVIDER_BINDING.test(record.providerBinding))
       || (record.retriedFrom !== undefined && !TASK_ID.test(record.retriedFrom))
-      || (record.flowBinding !== undefined && (record.capability !== 'image' || !validFlowBinding(record.flowBinding)))
-      || (record.sourceArtifactId !== undefined && (record.capability !== 'image' || !ARTIFACT_ID.test(record.sourceArtifactId)))) {
+      || (record.flowBinding !== undefined && (!validFlowBinding(record.flowBinding)
+        || ({ edit: 'image', generate: 'image', speak: 'tts', transcribe: 'transcribe' })[record.flowBinding.stepId] !== record.capability))
+      || (record.sourceArtifactId !== undefined && (!['image', 'transcribe'].includes(record.capability) || !ARTIFACT_ID.test(record.sourceArtifactId)))) {
     fail('IRIS_TASK_INVALID', 'Task 记录结构无效');
   }
   if (record.attempts.some((attempt, index) => !attempt || !ATTEMPT_ID.test(attempt.id)
@@ -123,6 +125,15 @@ function validateRecord(record, expectedId) {
       || !validAttemptStageTimestamps(attempt.stageTimestamps))) {
     fail('IRIS_TASK_INVALID', 'Task Attempt 记录结构无效');
   }
+  try {
+    for (const item of [record, ...record.attempts]) if (item.pluginDependency !== undefined) {
+      if (checkedPluginDependency(item.pluginDependency).kind !== 'providers' || !item.providerBinding) fail('IRIS_TASK_INVALID', 'Task 插件依赖需要 Provider 与端点绑定');
+    }
+    assertPluginDependencyMatches(record.pluginDependency, record.attempts.at(-1)?.pluginDependency);
+  } catch (error) {
+    if (!(error instanceof PluginContractError)) throw error;
+    fail('IRIS_TASK_INVALID', 'Task 或 Attempt 的插件依赖无效或不一致');
+  }
   const violations = semanticViolations(record);
   if (violations.length) fail('IRIS_TASK_INVALID', 'Task 事实语义冲突：' + violations.join(', '));
   return record;
@@ -178,7 +189,7 @@ function newTaskRecord(input, id) {
   const retriedFrom = input.retriedFrom === undefined ? undefined : String(input.retriedFrom);
   if (retriedFrom !== undefined && !TASK_ID.test(retriedFrom)) fail('IRIS_TASK_INPUT_INVALID', 'retriedFrom 必须是合法 Task ID');
   const sourceArtifactId = input.sourceArtifactId;
-  if (sourceArtifactId !== undefined && (capability !== 'image' || !ARTIFACT_ID.test(sourceArtifactId))) fail('IRIS_TASK_INPUT_INVALID', '改图 sourceArtifactId 必须是合法 Artifact ID');
+  if (sourceArtifactId !== undefined && (!['image', 'transcribe'].includes(capability) || !ARTIFACT_ID.test(sourceArtifactId))) fail('IRIS_TASK_INPUT_INVALID', '来源须为改图或转写的合法 Artifact ID');
   const now = new Date().toISOString();
   return {
     schemaVersion: 0,
@@ -210,8 +221,9 @@ export function createCoreTask(dataRoot, input = {}) {
 /** Flow 只能接回自己持久预留的 Task；原有 Task 没有该字段，读取语义不变。 */
 export function assertFlowTaskMatches(task, run) {
   const providerId = parseModelRef(run.input.model_ref).providerId;
-  if (task.id !== run.edit.taskId || task.capability !== 'image' || task.sourceArtifactId !== run.source.artifactId
+  if (task.id !== flowStep(run).taskId || task.capability !== flowCapability(run) || task.sourceArtifactId !== run.source?.artifactId
       || !validFlowBinding(task.flowBinding) || task.flowBinding.runId !== run.id
+      || task.flowBinding.stepId !== flowStepId(run)
       || task.flowBinding.inputDigest !== run.inputDigest
       || task.attempts.some(attempt => attempt.providerId !== providerId
         || attempt.model !== run.input.model_ref || attempt.providerBinding !== run.providerBinding)
@@ -228,13 +240,13 @@ export function findFlowTask(dataRoot, run) {
       if (!stat.isDirectory() || stat.isSymbolicLink()) fail('IRIS_FLOW_TASK_CONFLICT', '流程 Task 目录不安全');
     } catch (error) { if (error.code !== 'ENOENT') throw error; }
   }
-  try { fs.lstatSync(taskFile(dataRoot, run.edit.taskId)); }
+  try { fs.lstatSync(taskFile(dataRoot, flowStep(run).taskId)); }
   catch (error) {
     if (error.code !== 'ENOENT') throw error;
-    if (run.edit.claimed) fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，禁止重建或重新生成');
+    if (flowStep(run).claimed) fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，禁止重建或重新生成');
     return null;
   }
-  return assertFlowTaskMatches(readRecord(dataRoot, run.edit.taskId), run);
+  return assertFlowTaskMatches(readRecord(dataRoot, flowStep(run).taskId), run);
 }
 
 /** 仅从已提交的 Run 读取 ID；排他发布，新旧身份均不能覆盖。 */
@@ -242,7 +254,7 @@ export function claimFlowTask(dataRoot, runId) {
   const run = readFlowRun(dataRoot, runId);
   const previous = findFlowTask(dataRoot, run);
   if (previous) return previous;
-  return writeRecord(dataRoot, { ...newTaskRecord({ capability: 'image', sourceArtifactId: run.source.artifactId }, run.edit.taskId),
+  return writeRecord(dataRoot, { ...newTaskRecord({ capability: flowCapability(run), sourceArtifactId: run.source?.artifactId }, flowStep(run).taskId),
     flowBinding: flowTaskBinding(run) }, true);
 }
 
@@ -302,9 +314,11 @@ export function beginCoreAttempt(dataRoot, taskId, fields = {}) {
   const providerId = String(fields.providerId || '').trim();
   const model = String(fields.model || '').trim();
   const parsed = parseModelRef(model);
+  const pluginDependency = fields.pluginDependency === undefined ? undefined : checkedPluginDependency(fields.pluginDependency);
   if (!providerId || !parsed || parsed.providerId !== providerId
       || (fields.providerBinding !== undefined && !PROVIDER_BINDING.test(fields.providerBinding))
-      || (fields.selectionReason !== undefined && !ATTEMPT_SELECTION_REASONS.has(fields.selectionReason))) {
+      || (fields.selectionReason !== undefined && !ATTEMPT_SELECTION_REASONS.has(fields.selectionReason))
+      || (pluginDependency && (pluginDependency.kind !== 'providers' || !fields.providerBinding))) {
     fail('IRIS_ATTEMPT_INPUT_INVALID', 'Attempt 的 providerId 与复合 model 必须一致');
   }
   let created;
@@ -325,7 +339,8 @@ export function beginCoreAttempt(dataRoot, taskId, fields = {}) {
       startedAt: submitStartedAt,
       stageTimestamps: { queuedAt, submitStartedAt },
       ...(fields.selectionReason !== undefined ? { selectionReason: fields.selectionReason } : {}),
-      ...(fields.providerBinding !== undefined ? { providerBinding: fields.providerBinding } : {})
+      ...(fields.providerBinding !== undefined ? { providerBinding: fields.providerBinding } : {}),
+      ...(pluginDependency ? { pluginDependency } : {})
     };
     task.attempts.push(created);
     task.activeAttemptId = created.id;
@@ -333,6 +348,8 @@ export function beginCoreAttempt(dataRoot, taskId, fields = {}) {
     task.modelRef = model;
     if (created.providerBinding) task.providerBinding = created.providerBinding;
     else delete task.providerBinding;
+    if (created.pluginDependency) task.pluginDependency = created.pluginDependency;
+    else delete task.pluginDependency;
     task.phase = 'submitting';
     task.acceptance = 'none';
     task.watchState = 'idle';
@@ -519,7 +536,7 @@ export function failCoreDelivery(dataRoot, taskId, error) {
     task.phase = 'terminal';
     task.watchState = 'idle';
     task.deliveryState = 'failed';
-    task.lastError = safeError(error, { stage: 'download', category: 'local_io', acceptance: 'accepted' });
+    task.lastError = safeError(error, { stage: 'download', category: error?.category || 'local_io', acceptance: 'accepted' });
     task.finishedAt = new Date().toISOString();
   });
 }

package/lib/core-writer-lease.js

@@ -44,6 +44,22 @@ function optionalRecord(file) {
   catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
 }
 
+/** Recognize only an unpublished preparation from a proven-dead owner. Keep it
+ * as evidence: initialization may ignore this metadata, but never removes it. */
+export function isAbandonedWriterPreparation(root, name) {
+  const match = /^\.iris-runtime-writer-v0\.owner\.json\.prepare-([1-9][0-9]*)-[a-f0-9]{12}$/.exec(name);
+  if (!match) return false;
+  try {
+    const file = path.join(root, name), stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return false;
+    const owner = checkedOwner(readRecord(file).value);
+    return String(owner.pid) === match[1] && writerOwnerStatus(owner.pid) === 'missing';
+  } catch (error) {
+    if (error.code && !['ENOENT', 'EACCES', 'EPERM'].includes(error.code)) throw error;
+    return false;
+  }
+}
+
 /** 完整私有记录先在根中准备，再以 hard link 原子发布；已有目标绝不覆盖。 */
 export function publishLeaseRecord(root, target, value) {
   const prepared = privateSibling(path.join(root, WRITER_INTENT_FILE), 'prepare');

package/lib/creation-request-store.js

@@ -3,8 +3,10 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
-import { inspectFlowRoot, validateFlowCreation } from './flow-store.js';
-import { WRITER_LEASE_DIR, WRITER_INTENT_FILE } from './core-writer-lease.js';
+import { validateFlowCreation } from './flow-store.js';
+import { inspectLocalRequestRoot, initializeLocalRequestRoot, requestDirectory } from './local-request-root.js';
+import { normalizeComfyParameters } from './comfyui-workflow.js';
+import { AUDIO_TYPES, MAX_AUDIO_INPUT_BYTES, normalizeAudioFlowInput } from './audio-flow-input.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}$/;
 const ID = /^req_[a-f0-9]{64}$/;
@@ -13,6 +15,8 @@ const SHA = /^[a-f0-9]{64}$/;
 const DIGEST = /^sha256:[a-f0-9]{64}$/;
 const TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
 const MAX_IMAGE = 20 * 1024 * 1024;
+export const CREATION_KINDS = Object.freeze(['image-import', 'flow-create', 'generation-create', 'audio-import', 'speech-create', 'transcription-create']);
+export const isImportCreation = kind => ['image-import', 'audio-import'].includes(kind);
 const iso = value => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
 const hash = value => crypto.createHash('sha256').update(value).digest('hex');
 const copy = value => structuredClone(value);
@@ -22,16 +26,6 @@ function keys(value, allowed, required = allowed) {
 }
 export function creationFail(code, message) { throw Object.assign(new Error(message), { code }); }
 const invalid = () => creationFail('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;
-}
 function jsonFile(file) {
   const stat = fs.lstatSync(file);
   if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) invalid();
@@ -39,54 +33,28 @@ function jsonFile(file) {
 }
 
 export function inspectCreationRoot(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;
-      creationFail('IRIS_CREATION_ROOT_REQUIRED', '请先在空的专用 Flow 根显式执行 api init');
-    }
-    if (error.code === 'ENOENT') invalid();
-    throw error;
-  }
-  try {
-    if (fs.readdirSync(base).some(name => name !== 'v0')) invalid();
-    const version = directory(root, ['creation-requests', 'v0']);
-    if (fs.readdirSync(version).some(name => !['root.json', 'requests'].includes(name)
-        && !/^root\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name))) invalid();
-    const marker = jsonFile(path.join(version, 'root.json'));
-    if (!keys(marker, ['schemaVersion', 'kind', 'rootId', 'createdAt']) || marker.schemaVersion !== 0
-        || marker.kind !== 'iris-creation-requests' || !UUID.test(marker.rootId) || !iso(marker.createdAt)) invalid();
-    directory(root, ['creation-requests', 'v0', 'requests']);
-    return copy(marker);
-  } catch (error) { if (error.code === 'ENOENT') invalid(); throw error; }
+  return inspectLocalRequestRoot(root, { allowAbsent });
 }
 
 export function initializeCreationRoot(root) {
-  const existing = inspectCreationRoot(root, { allowAbsent: true });
-  if (existing) { listCreationRequests(root); return existing; }
-  inspectFlowRoot(root);
-  if (fs.readdirSync(root).some(name => !['flow-store', WRITER_LEASE_DIR, WRITER_INTENT_FILE].includes(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) {
-    creationFail('IRIS_CREATION_ROOT_NOT_EMPTY', '请求区仅在新的空 Flow 根初始化；不转换已有创作数据');
-  }
-  const marker = { schemaVersion: 0, kind: 'iris-creation-requests', rootId: crypto.randomUUID(), createdAt: new Date().toISOString() };
-  directory(root, ['creation-requests', 'v0', 'requests'], true);
-  atomicCreatePrivate(path.join(root, 'creation-requests/v0/root.json'), JSON.stringify(marker, null, 2) + '\n');
-  return copy(marker);
+  const marker = initializeLocalRequestRoot(root, 0);
+  listCreationRequests(root);
+  return marker;
 }
 
 export function creationRequestId(marker, kind, key) {
   if (!UUID.test(key)) creationFail('IRIS_CREATION_KEY_INVALID', 'Idempotency-Key 须为单个小写 UUIDv4');
-  if (!['image-import', 'flow-create'].includes(kind)) throw new TypeError('未知本地创建类型');
+  if (!CREATION_KINDS.includes(kind)) throw new TypeError('未知本地创建类型');
   return 'req_' + hash(JSON.stringify(['creation-requests/v0', marker.rootId, kind, key]));
 }
 export function creationInputDigest(kind, input) {
-  return 'sha256:' + hash(JSON.stringify(kind === 'image-import'
-    ? ['image-import/v0', input.mediaType, input.size, input.sha256]
-    : ['flow-create/v0', 'image-edit/v0', input.source_artifact_id, input.model_ref, input.prompt, input.size ?? null, 1]));
+  if (['speech-create', 'transcription-create'].includes(kind)) return 'sha256:' + hash(JSON.stringify([kind + '/v0',
+    normalizeAudioFlowInput(kind === 'speech-create' ? 'speech/v0' : 'transcribe/v0', input)]));
+  return 'sha256:' + hash(JSON.stringify(isImportCreation(kind)
+    ? [kind + '/v0', input.mediaType, input.size, input.sha256]
+    : kind === 'generation-create' ? ['generation-create/v0', 'image-generate/v0', input.model_ref, input.prompt, input.size ?? null, 1,
+      ...(input.workflow_parameters !== undefined ? [['comfyui-parameters/v0', normalizeComfyParameters(input.workflow_parameters)]] : [])]
+      : ['flow-create/v0', 'image-edit/v0', input.source_artifact_id, input.model_ref, input.prompt, input.size ?? null, 1]));
 }
 function validate(record, id, marker) {
   if (!keys(record, ['schemaVersion', 'id', 'rootId', 'kind', 'inputDigest', 'createdAt', 'intent', 'state', 'completedAt', 'result'],
@@ -96,14 +64,19 @@ function validate(record, id, marker) {
       || !['prepared', 'succeeded'].includes(record.state)) invalid();
   const intent = record.intent;
   let expectedResult, expectedDigest;
-  if (record.kind === 'image-import') {
+  if (isImportCreation(record.kind)) {
+    const audio = record.kind === 'audio-import';
     if (!keys(intent, ['artifactId', 'mediaType', 'size', 'sha256', 'metadata', 'createdAt'])
-        || !ARTIFACT.test(intent.artifactId) || !TYPES.has(intent.mediaType) || !SHA.test(intent.sha256)
-        || !Number.isSafeInteger(intent.size) || intent.size < 1 || intent.size > MAX_IMAGE
-        || !keys(intent.metadata, ['width', 'height']) || !['width', 'height'].every(key => Number.isSafeInteger(intent.metadata[key]) && intent.metadata[key] > 0)) invalid();
+        || audio && marker.schemaVersion !== 3
+        || !ARTIFACT.test(intent.artifactId) || !(audio ? Object.hasOwn(AUDIO_TYPES, intent.mediaType) : TYPES.has(intent.mediaType)) || !SHA.test(intent.sha256)
+        || !Number.isSafeInteger(intent.size) || intent.size < 1 || intent.size > (audio ? MAX_AUDIO_INPUT_BYTES : MAX_IMAGE)
+        || (audio ? !keys(intent.metadata, []) : !keys(intent.metadata, ['width', 'height']) || !['width', 'height'].every(key => Number.isSafeInteger(intent.metadata[key]) && intent.metadata[key] > 0))) invalid();
     expectedDigest = creationInputDigest(record.kind, intent);
     expectedResult = { artifactId: intent.artifactId };
-  } else if (record.kind === 'flow-create') {
+  } else if (['flow-create', 'generation-create', 'speech-create', 'transcription-create'].includes(record.kind)) {
+    if (record.kind === 'generation-create' ? ![2, 3].includes(marker.schemaVersion) || intent.recipe !== 'image-generate/v0'
+      : record.kind === 'flow-create' ? intent.recipe !== undefined
+        : marker.schemaVersion !== 3 || intent.recipe !== (record.kind === 'speech-create' ? 'speech/v0' : 'transcribe/v0')) invalid();
     try { validateFlowCreation(intent); } catch (_) { invalid(); }
     expectedDigest = creationInputDigest(record.kind, intent.input);
     expectedResult = { runId: intent.runId };
@@ -118,7 +91,7 @@ function validate(record, id, marker) {
 export function readCreationRequest(root, id, marker = inspectCreationRoot(root)) {
   if (!ID.test(id)) invalid();
   let record;
-  try { record = jsonFile(path.join(root, 'creation-requests/v0/requests', id + '.json')); }
+  try { record = jsonFile(path.join(requestDirectory(root, marker, 'requests'), id + '.json')); }
   catch (error) { if (error.code === 'ENOENT') return null; throw error; }
   return copy(validate(record, id, marker));
 }
@@ -126,7 +99,7 @@ export function listCreationRequests(root) {
   const marker = inspectCreationRoot(root, { allowAbsent: true });
   if (!marker) return [];
   const records = [];
-  for (const name of fs.readdirSync(path.join(root, 'creation-requests/v0/requests'))) {
+  for (const name of fs.readdirSync(requestDirectory(root, marker, 'requests'))) {
     if (/^req_[a-f0-9]{64}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name)) continue;
     if (!/^req_[a-f0-9]{64}\.json$/.test(name)) invalid();
     const record = readCreationRequest(root, name.slice(0, -5), marker);
@@ -138,22 +111,23 @@ export function listCreationRequests(root) {
 export function publishCreationRequest(root, record) {
   const marker = inspectCreationRoot(root);
   validate(record, record.id, marker);
-  atomicCreatePrivate(path.join(root, 'creation-requests/v0/requests', record.id + '.json'), JSON.stringify(record, null, 2) + '\n');
+  atomicCreatePrivate(path.join(requestDirectory(root, marker, 'requests'), record.id + '.json'), JSON.stringify(record, null, 2) + '\n');
   return copy(record);
 }
 export function completeCreationRequest(root, record) {
   const current = readCreationRequest(root, record.id);
   if (!current || JSON.stringify(current) !== JSON.stringify(record) || current.state !== 'prepared') invalid();
   const finished = { ...record, state: 'succeeded', completedAt: new Date().toISOString(),
-    result: record.kind === 'image-import' ? { artifactId: record.intent.artifactId } : { runId: record.intent.runId } };
-  validate(finished, record.id, inspectCreationRoot(root));
-  atomicWritePrivate(path.join(root, 'creation-requests/v0/requests', record.id + '.json'), JSON.stringify(finished, null, 2) + '\n');
+    result: isImportCreation(record.kind) ? { artifactId: record.intent.artifactId } : { runId: record.intent.runId } };
+  const marker = inspectCreationRoot(root);
+  validate(finished, record.id, marker);
+  atomicWritePrivate(path.join(requestDirectory(root, marker, 'requests'), record.id + '.json'), JSON.stringify(finished, null, 2) + '\n');
   return copy(finished);
 }
 export function creationReferences(root) {
   return listCreationRequests(root).filter(record => record.state === 'prepared').map(record => ({
-    requestId: record.id, taskIds: record.kind === 'flow-create' ? [record.intent.taskId] : [],
-    artifactIds: record.kind === 'image-import' ? [record.intent.artifactId]
-      : [record.intent.source.artifactId, record.intent.comparisonArtifactId]
+    requestId: record.id, taskIds: !isImportCreation(record.kind) ? [record.intent.taskId] : [],
+    artifactIds: isImportCreation(record.kind) ? [record.intent.artifactId]
+      : [record.intent.source?.artifactId, record.intent.comparisonArtifactId].filter(Boolean)
   }));
 }

package/lib/dsh-host-adapter.js

@@ -133,12 +133,15 @@ function dshVisionPort(llm, defaults) {
         if (chunk?.type === 'finish') {
           if (chunk.reason?.kind === 'error') throw visionRouteError('DSH 视觉调用失败；请检查宿主模型状态');
           if (chunk.reason?.kind === 'aborted') throw visionRouteError('DSH 视觉调用已取消');
+          if (['length', 'max-tokens', 'tool-calls', 'content-blocked'].includes(chunk.reason?.kind)) {
+            throw visionRouteError('DSH 视觉结果未完整结束：' + chunk.reason.kind);
+          }
         }
         const text = typeof chunk?.delta === 'string'
           ? chunk.delta
           : (chunk?.type === 'text-delta' ? String(chunk.text || '') : '');
         if (text) chunks.push(text);
-        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) break;
+        if (chunks.reduce((sum, item) => sum + item.length, 0) > 6000) throw visionRouteError('DSH 视觉结果超过长度限制，未返回部分结果');
       }
       return chunks.join('').trim();
     }

package/lib/dsh-service-bridge.js

@@ -0,0 +1,66 @@
+import { createCoreServiceClient } from './core-service-client.js';
+import { bridgeToolsForScopes, callCoreBridgeTool } from './core-bridge-tools.js';
+import { requireHostPort } from './host-contract.js';
+
+/** Optional shared-Flow connection. Native DSH ports stay in the host; no remote ctx or local execution fallback. */
+export function createDshServiceBridge({ connectionFile, requestedScopes = ['read'], getHost, harnessVersion = 'unknown', fetch } = {}) {
+  if (typeof getHost !== 'function') throw new TypeError('DSH 服务桥需要真实 Host 工厂');
+  const client = createCoreServiceClient({ connectionFile, requestedScopes, harnessVersion, fetch });
+  const lifetime = new AbortController(), jobs = new Set();
+  const toolDisposers = [];
+  let state = 'new', disposal, remoteDisconnect = 'not_connected';
+  async function start() {
+    if (state !== 'new') throw new Error('DSH Core 服务桥只能启动一次');
+    state = 'connecting';
+    try {
+      await client.connect();
+      if (client.snapshot().adapterId !== 'iris.dsh-service') throw Object.assign(new Error('连接文件不是 DSH 适配授权'), { code: 'IRIS_CONNECTION_INPUT_INVALID' });
+      const selected = client.snapshot();
+      if (selected.capabilities.some(id => ['tts', 'transcribe'].includes(id))) throw Object.assign(new Error('DSH 原生共享桥尚未接入音频附件交付；请为此桥选择图片功能，音频使用通用 MCP 或 Core 工作台'), { code: 'IRIS_DSH_AUDIO_NOT_SUPPORTED' });
+      const tools = requireHostPort(getHost(), 'tools', '注册 Core 服务工具');
+      for (const tool of bridgeToolsForScopes(selected.scopes, selected.capabilities, selected.tools, selected.pluginOperations)) {
+        const remove = tools.register({ name: tool.name, description: tool.description, parameters: tool.parameters,
+          isConcurrencySafe: () => tool.scope === 'read' || tool.scope === 'stop',
+          output: { schema: { type: 'object' }, render: (_args, result) => result.blocks },
+          async execute(args, exec = {}) {
+            const signal = AbortSignal.any([lifetime.signal, ...(exec.signal ? [exec.signal] : [])]);
+            const job = (async () => {
+              signal.throwIfAborted();
+              const result = await callCoreBridgeTool(client, tool.name, args, { signal });
+              if (!result.image) return { value: result.value, blocks: [{ type: 'text', text: JSON.stringify(result.value) }] };
+              const attachments = requireHostPort(getHost(), 'attachments', '显示 Core 图片');
+              const attachment = await attachments.saveImage({ data: new Uint8Array(result.image.bytes), mediaType: result.image.mediaType,
+                name: 'iris-core-' + result.image.artifactId + '.' + (result.image.mediaType === 'image/jpeg' ? 'jpg' : result.image.mediaType.slice(6)) });
+              signal.throwIfAborted();
+              if (!attachment?.attachmentId) throw Object.assign(new Error('DSH 没有返回图片附件身份'), { code: 'IRIS_DSH_PROJECTION_FAILED' });
+              return { artifactId: result.image.artifactId, blocks: [{ type: 'image', attachment }] };
+            })();
+            jobs.add(job); try { return await job; } finally { jobs.delete(job); }
+          }
+        });
+        if (typeof remove === 'function') toolDisposers.push(remove);
+      }
+      state = 'open'; return snapshot();
+    } catch (error) {
+      try { await dispose(); }
+      catch (cleanup) { throw new AggregateError([error, cleanup], 'DSH 服务桥启动与释放均失败'); }
+      throw error;
+    }
+  }
+  function snapshot() { return { state, connection: client.snapshot(), operations: jobs.size, remoteDisconnect }; }
+  function dispose() {
+    if (disposal) return disposal;
+    state = 'closing'; lifetime.abort();
+    disposal = (async () => {
+      const errors = [];
+      for (const remove of toolDisposers.splice(0).reverse()) { try { await remove(); } catch (error) { errors.push(error); } }
+      await Promise.allSettled([...jobs]);
+      try { remoteDisconnect = (await client.dispose()).remoteDisconnect; } catch (error) { errors.push(error); }
+      state = 'closed';
+      if (errors.length) throw new AggregateError(errors, 'DSH 服务桥释放失败');
+      return snapshot();
+    })();
+    return disposal;
+  }
+  return Object.freeze({ start, snapshot, dispose });
+}

package/lib/execution-ownership.js

@@ -0,0 +1,43 @@
+// Runner ownership uses the existing Core lease protocol in its own private directory.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readWriterLease, WRITER_LEASE_DIR, WRITER_INTENT_FILE } from './core-writer-lease.js';
+
+const UUID = '[a-f0-9-]{36}';
+const FILE = new RegExp('^(?:' + WRITER_INTENT_FILE.replaceAll('.', '\\.')
+  + '(?:\\.prepare-[1-9][0-9]*-[a-f0-9]{12})?|' + WRITER_LEASE_DIR.replaceAll('.', '\\.')
+  + '\\.recovery-' + UUID + '\\.json)$');
+const RETIRED = new RegExp('^' + WRITER_LEASE_DIR.replaceAll('.', '\\.') + '\\.released-' + UUID + '$');
+const invalid = () => { throw Object.assign(new Error('执行所有权目录未知或损坏；已保留现场'), { code: 'IRIS_EXECUTION_LEASE_INVALID' }); };
+
+export function inspectRunnerArea(directory) {
+  function regular(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024) invalid();
+  }
+  function ownerDirectory(file, audit = false) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+    for (const name of fs.readdirSync(file)) {
+      if (name !== 'owner.json' && !/^\.owner\.stale-[a-f0-9-]{36}\.json$/.test(name)
+          && !(audit && new RegExp('^' + WRITER_LEASE_DIR.replaceAll('.', '\\.') + '\\.recovery-' + UUID + '\\.json$').test(name))) invalid();
+      regular(path.join(file, name));
+    }
+  }
+  for (const name of fs.readdirSync(directory)) {
+    const file = path.join(directory, name);
+    if (name === WRITER_LEASE_DIR || RETIRED.test(name)) ownerDirectory(file);
+    else if (FILE.test(name)) regular(file);
+    else if (name === '.iris-runtime-recovery-audit-v0') {
+      const stat = fs.lstatSync(file);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+      for (const entry of fs.readdirSync(file)) {
+        if (/^lease_recovery_[a-f0-9]{24}\.json$/.test(entry)) regular(path.join(file, entry));
+        else if (/^lease_recovery_[a-f0-9]{24}\.lease$/.test(entry)) ownerDirectory(path.join(file, entry), true);
+        else invalid();
+      }
+    } else invalid();
+  }
+  try { return readWriterLease(directory); }
+  catch (_) { invalid(); }
+}