@mokuyoaxis/dsh-iris 0.2.6 → 0.2.7

package/lib/core-tasks.js

@@ -3,11 +3,12 @@
 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 { flowTaskBinding, readFlowRun, validFlowBinding } from './flow-store.js';
 
 const STORE_DIR = 'task-store';
 const STORE_VERSION = 'v0';
@@ -110,6 +111,7 @@ 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)))) {
     fail('IRIS_TASK_INVALID', 'Task 记录结构无效');
   }
@@ -143,11 +145,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,7 +172,7 @@ 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);
@@ -177,10 +180,10 @@ export function createCoreTask(dataRoot, input = {}) {
   const sourceArtifactId = input.sourceArtifactId;
   if (sourceArtifactId !== undefined && (capability !== 'image' || !ARTIFACT_ID.test(sourceArtifactId))) fail('IRIS_TASK_INPUT_INVALID', '改图 sourceArtifactId 必须是合法 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 +200,50 @@ 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 !== run.edit.taskId || task.capability !== 'image' || task.sourceArtifactId !== run.source.artifactId
+      || !validFlowBinding(task.flowBinding) || task.flowBinding.runId !== run.id
+      || 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, run.edit.taskId)); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    if (run.edit.claimed) fail('IRIS_FLOW_TASK_CONFLICT', '流程已建立的 Task 丢失，禁止重建或重新生成');
+    return null;
+  }
+  return assertFlowTaskMatches(readRecord(dataRoot, run.edit.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: 'image', sourceArtifactId: run.source.artifactId }, run.edit.taskId),
+    flowBinding: flowTaskBinding(run) }, true);
 }
 
 export function inspectCoreTask(dataRoot, id) {
@@ -366,7 +412,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 +433,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;
     }
@@ -524,6 +571,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/creation-request-store.js

@@ -0,0 +1,159 @@
+// 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 { inspectFlowRoot, validateFlowCreation } from './flow-store.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE } from './core-writer-lease.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;
+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 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();
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+}
+
+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; }
+}
+
+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);
+}
+
+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('未知本地创建类型');
+  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]));
+}
+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 (record.kind === 'image-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();
+    expectedDigest = creationInputDigest(record.kind, intent);
+    expectedResult = { artifactId: intent.artifactId };
+  } else if (record.kind === 'flow-create') {
+    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(root, 'creation-requests/v0/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(path.join(root, 'creation-requests/v0/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(root, 'creation-requests/v0/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');
+  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]
+  }));
+}

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', '宿主文本模型');