@mokuyoaxis/dsh-iris 0.2.6 → 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

@@ -3,11 +3,13 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { atomicWritePrivate, ensurePrivateDir } from './private-storage.js';
+import { atomicCreatePrivate, atomicWritePrivate, ensurePrivateDir } from './private-storage.js';
 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 { 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';
@@ -110,7 +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.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)
@@ -121,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;
@@ -143,11 +156,12 @@ function readRecord(dataRoot, id) {
   return validateRecord(record, id);
 }
 
-function writeRecord(dataRoot, record) {
+function writeRecord(dataRoot, record, exclusive = false) {
   validateRecord(record, record.id);
   try {
     ensurePrivateDir(taskDirectory(dataRoot));
-    atomicWritePrivate(taskFile(dataRoot, record.id), JSON.stringify(record, null, 2) + '\n');
+    const publish = exclusive ? atomicCreatePrivate : atomicWritePrivate;
+    publish(taskFile(dataRoot, record.id), JSON.stringify(record, null, 2) + '\n');
   } catch (error) {
     if (error instanceof CoreTaskError) throw error;
     fail('IRIS_TASK_WRITE_FAILED', 'Task 无法安全写入');
@@ -169,18 +183,18 @@ function safeError(error, overrides) {
   return providerErrorRecord(error, overrides);
 }
 
-export function createCoreTask(dataRoot, input = {}) {
+function newTaskRecord(input, id) {
   const capability = String(input.capability || '').trim();
   if (!CAPABILITIES.has(capability)) fail('IRIS_TASK_INPUT_INVALID', 'Task capability 无效');
   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 writeRecord(dataRoot, {
+  return {
     schemaVersion: 0,
     semanticsVersion: 2,
-    id: 'task_' + crypto.randomBytes(12).toString('hex'),
+    id,
     capability,
     status: 'running',
     phase: 'queued',
@@ -197,7 +211,51 @@ export function createCoreTask(dataRoot, input = {}) {
     // D4 retry as new task：显式单向关系（新任务指向旧任务），绝不复制 Prompt。
     ...(retriedFrom !== undefined ? { retriedFrom } : {}),
     ...(sourceArtifactId !== undefined ? { sourceArtifactId } : {})
-  });
+  };
+}
+
+export function createCoreTask(dataRoot, input = {}) {
+  return writeRecord(dataRoot, newTaskRecord(input, 'task_' + crypto.randomBytes(12).toString('hex')));
+}
+
+/** Flow 只能接回自己持久预留的 Task；原有 Task 没有该字段，读取语义不变。 */
+export function assertFlowTaskMatches(task, run) {
+  const providerId = parseModelRef(run.input.model_ref).providerId;
+  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)
+      || (task.attempts.length && (task.providerId !== providerId || task.modelRef !== run.input.model_ref || task.providerBinding !== run.providerBinding))) {
+    fail('IRIS_FLOW_TASK_CONFLICT', '流程与原 Task 的身份、输入或模型绑定冲突');
+  }
+  return task;
+}
+
+export function findFlowTask(dataRoot, run) {
+  for (const relative of [STORE_DIR, STORE_DIR + '/' + STORE_VERSION, STORE_DIR + '/' + STORE_VERSION + '/tasks']) {
+    try {
+      const stat = fs.lstatSync(path.join(dataRoot, relative));
+      if (!stat.isDirectory() || stat.isSymbolicLink()) fail('IRIS_FLOW_TASK_CONFLICT', '流程 Task 目录不安全');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  try { fs.lstatSync(taskFile(dataRoot, flowStep(run).taskId)); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    if (flowStep(run).claimed) fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，禁止重建或重新生成');
+    return null;
+  }
+  return assertFlowTaskMatches(readRecord(dataRoot, flowStep(run).taskId), run);
+}
+
+/** 仅从已提交的 Run 读取 ID；排他发布，新旧身份均不能覆盖。 */
+export function claimFlowTask(dataRoot, runId) {
+  const run = readFlowRun(dataRoot, runId);
+  const previous = findFlowTask(dataRoot, run);
+  if (previous) return previous;
+  return writeRecord(dataRoot, { ...newTaskRecord({ capability: flowCapability(run), sourceArtifactId: run.source?.artifactId }, flowStep(run).taskId),
+    flowBinding: flowTaskBinding(run) }, true);
 }
 
 export function inspectCoreTask(dataRoot, id) {
@@ -256,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;
@@ -279,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;
@@ -287,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';
@@ -366,7 +429,7 @@ export function activateCoreWatch(dataRoot, taskId) {
   });
 }
 
-export function recordCorePollResult(dataRoot, taskId, result) {
+export function recordCorePollResult(dataRoot, taskId, result, { deliveryCache = false } = {}) {
   return mutate(dataRoot, taskId, (task) => {
     if (task.acceptance !== 'accepted' || !task.remoteTaskId) {
       fail('IRIS_TASK_NOT_OBSERVABLE', 'Task 缺少可观察的远端受理事实');
@@ -387,6 +450,7 @@ export function recordCorePollResult(dataRoot, taskId, result) {
       task.phase = 'running';
       task.outcome = 'succeeded';
       task.deliveryState = 'pending';
+      if (deliveryCache) task.deliveryCache = true;
       delete task.lastError;
       return;
     }
@@ -472,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();
   });
 }
@@ -524,6 +588,13 @@ export function recordCoreCancelResult(dataRoot, taskId, result) {
  */
 export function recoverCoreTask(dataRoot, taskId) {
   let current = readRecord(dataRoot, taskId);
+  // Flow 的异步完成结果同样先缓存，再记录 poll；中断时只恢复原结果，不重新查询/生成。
+  if (current.flowBinding && current.acceptance === 'accepted' && current.remoteTaskId
+      && current.outcome === 'none' && current.cancelState === 'none'
+      && readDeliveryCache(dataRoot, current, { allowAbsent: true })) {
+    recordCorePollResult(dataRoot, taskId, { kind: 'succeeded' }, { deliveryCache: true });
+    current = readRecord(dataRoot, taskId);
+  }
   if (current.phase === 'submitting' && current.acceptance === 'none') {
     const cache = readDeliveryCache(dataRoot, current, { allowAbsent: true });
     if (cache) {

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

@@ -0,0 +1,133 @@
+// Private local creation intents. No Host, HTTP, Provider or Runtime dependencies.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.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}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+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);
+function keys(value, allowed, required = allowed) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key));
+}
+export function creationFail(code, message) { throw Object.assign(new Error(message), { code }); }
+const invalid = () => creationFail('IRIS_CREATION_STORE_INVALID', '创建请求区未知、损坏或尚未完整初始化');
+function jsonFile(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) invalid();
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+}
+
+export function inspectCreationRoot(root, { allowAbsent = false } = {}) {
+  return inspectLocalRequestRoot(root, { allowAbsent });
+}
+
+export function initializeCreationRoot(root) {
+  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 (!CREATION_KINDS.includes(kind)) throw new TypeError('未知本地创建类型');
+  return 'req_' + hash(JSON.stringify(['creation-requests/v0', marker.rootId, kind, key]));
+}
+export function creationInputDigest(kind, input) {
+  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'],
+    ['schemaVersion', 'id', 'rootId', 'kind', 'inputDigest', 'createdAt', 'intent', 'state'])
+      || record.schemaVersion !== 0 || !ID.test(id) || record.id !== id || record.rootId !== marker.rootId
+      || !DIGEST.test(record.inputDigest) || !iso(record.createdAt) || record.intent?.createdAt !== record.createdAt
+      || !['prepared', 'succeeded'].includes(record.state)) invalid();
+  const intent = record.intent;
+  let expectedResult, expectedDigest;
+  if (isImportCreation(record.kind)) {
+    const audio = record.kind === 'audio-import';
+    if (!keys(intent, ['artifactId', 'mediaType', 'size', 'sha256', 'metadata', 'createdAt'])
+        || 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 (['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 };
+  } else invalid();
+  if (record.inputDigest !== expectedDigest) invalid();
+  if (record.state === 'prepared') {
+    if (Object.hasOwn(record, 'completedAt') || Object.hasOwn(record, 'result')) invalid();
+  } else if (!iso(record.completedAt) || !keys(record.result, Object.keys(expectedResult))
+      || JSON.stringify(record.result) !== JSON.stringify(expectedResult)) invalid();
+  return record;
+}
+export function readCreationRequest(root, id, marker = inspectCreationRoot(root)) {
+  if (!ID.test(id)) invalid();
+  let record;
+  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));
+}
+export function listCreationRequests(root) {
+  const marker = inspectCreationRoot(root, { allowAbsent: true });
+  if (!marker) return [];
+  const records = [];
+  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);
+    if (!record) invalid();
+    records.push(record);
+  }
+  return records;
+}
+export function publishCreationRequest(root, record) {
+  const marker = inspectCreationRoot(root);
+  validate(record, record.id, marker);
+  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: 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: !isImportCreation(record.kind) ? [record.intent.taskId] : [],
+    artifactIds: isImportCreation(record.kind) ? [record.intent.artifactId]
+      : [record.intent.source?.artifactId, record.intent.comparisonArtifactId].filter(Boolean)
+  }));
+}

package/lib/doctor.js

@@ -421,7 +421,18 @@ export function hostDoctor(host, evidence = {}, options = {}) {
       + (missingSkills.length ? '：' + missingSkills.join(', ') : ''),
     '工具仍可直接调用；检查 DSH Skill registry 和插件启动日志。'));
 
-  capabilityCheck(checks, snapshot, 'browser', 'browser', 'HTML Browser');
+  if (capabilityCheck(checks, snapshot, 'browser', 'browser', 'HTML Browser')) {
+    checks[checks.length - 1] = result('browser', 'ok', 'HTML 浏览器接口已提供；实际截图需单独自检',
+      '点击“截图自检”验证当前浏览器能否启动、打开页面并生成图片。');
+    const address = host.ports.browser.address;
+    if (address) {
+      checks.push(result('render-address', address.status === 'resolved' ? 'ok' : 'warn',
+        address.status === 'resolved'
+          ? '截图地址：' + address.baseUrl + (address.source === 'environment' ? '（DSH_WEB_BASE）' : '（宿主监听）')
+          : address.message,
+        address.status === 'resolved' ? '' : '显式配置 DSH_WEB_BASE；不需要额外的端口转发。'));
+    }
+  }
   capabilityCheck(checks, snapshot, 'attachments', 'attachments', '附件读写');
   capabilityCheck(checks, snapshot, 'sessions', 'sessions', '会话查询');
   capabilityCheck(checks, snapshot, 'text-model', 'textModel', '宿主文本模型');