@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

package/lib/local-api.js

@@ -0,0 +1,381 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { createApplicationRuntime } from './application-runtime.js';
+import { normalizeCoreOptions } from './core-contract.js';
+import { createCoreRuntime } from './core-runtime.js';
+import { inspectFlowRoot } from './flow-store.js';
+import { inspectCoreArtifactMetadata, readCoreArtifactBytes } from './core-artifacts.js';
+import { imageCandidatesFromCatalog, loadProviderCatalog, providerTaskBinding } from './provider-catalog.js';
+import { supportsImageEdit } from './provider-protocol.js';
+import { projectLocalApiFlow, projectLocalApiRunSummary } from './local-api-projection.js';
+import { inspectCreationRoot } from './creation-request-store.js';
+import { MAX_IMPORT_IMAGE_BYTES } from './image-import.js';
+
+export const MAX_LOCAL_API_IMAGE_BYTES = 64 * 1024 * 1024;
+const RUN = /^run_[a-f0-9]{24}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const KEY = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const IMAGE_TYPES = new Map([['image/png', 'png'], ['image/jpeg', 'jpg'], ['image/webp', 'webp']]);
+const digest = value => crypto.createHash('sha256').update(value).digest();
+const CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
+
+export class LocalApiError extends Error {
+  constructor(code, message, status = 400) { super(message); this.name = 'LocalApiError'; this.code = code; this.status = status; }
+}
+function fail(code, message, status) { throw new LocalApiError(code, message, status); }
+
+function httpError(error) {
+  if (error instanceof LocalApiError) return error;
+  if (error?.code === 'IRIS_CORE_DATA_ROOT_BUSY') return new LocalApiError('IRIS_API_ROOT_BUSY', '该数据根已有活动写者，请稍后显式重试', 409);
+  if (error?.code === 'IRIS_CREATION_RESULT_UNAVAILABLE') return new LocalApiError('IRIS_API_RESULT_UNAVAILABLE', '原创建结果已不可用；同 Key 不会重新创建或复活作品', 409);
+  if (error?.code === 'IRIS_CREATION_KEY_CONFLICT') return new LocalApiError('IRIS_API_KEY_CONFLICT', '该 Key 已绑定其他输入', 409);
+  if (['IRIS_CREATION_KEY_INVALID', 'IRIS_CREATION_INPUT_INVALID', 'IRIS_GENERATION_INPUT_INVALID',
+    'IRIS_IMAGE_IMPORT_INVALID', 'IRIS_IMAGE_EDIT_INPUT_INVALID', 'IRIS_FLOW_INPUT_INVALID'].includes(error?.code)) {
+    return new LocalApiError('IRIS_API_INPUT_INVALID', '创作输入或静态图片无效，请检查来源、模型和参数', 400);
+  }
+  if (error?.code === 'IRIS_CREATION_MEDIA_MISMATCH') return new LocalApiError('IRIS_API_MEDIA_UNSUPPORTED', '图片真实格式与 Content-Type 不一致', 415);
+  if (/^IRIS_CREATION_/.test(error?.code || '')) return new LocalApiError('IRIS_API_RECORD_CONFLICT', '创建请求证据不一致，请在本机检查原记录', 409);
+  if (['IRIS_FLOW_NOT_FOUND', 'IRIS_ARTIFACT_NOT_FOUND'].includes(error?.code)) {
+    return new LocalApiError('IRIS_API_NOT_FOUND', '该实例中没有此流程或图片', 404);
+  }
+  if (/^IRIS_PROVIDER_/.test(error?.code || '')) {
+    return new LocalApiError('IRIS_API_CONFIG_UNAVAILABLE', '模型配置不可用，请在本机检查显式配置', 500);
+  }
+  if (error?.code === 'IRIS_APP_CLOSED' || error?.name === 'AbortError' || /^IRIS_CORE_DATA_ROOT_/.test(error?.code || '')) {
+    return new LocalApiError('IRIS_API_UNAVAILABLE', '服务正在关闭或数据根不可用', 503);
+  }
+  if (/^IRIS_(?:FLOW|ARTIFACT|TASK)_/.test(error?.code || '')) {
+    return new LocalApiError('IRIS_API_RECORD_CONFLICT', '流程或作品证据不一致，请在本机核对原记录', 409);
+  }
+  return new LocalApiError('IRIS_API_INTERNAL', '读取失败，请使用关联 ID 核对本机诊断', 500);
+}
+
+function reportUnexpected(error, requestId) {
+  // Keep call sites for diagnosis, without the potentially private exception message or directory names.
+  const frames = String(error?.stack || '').split('\n').slice(1, 7)
+    .map(line => line.replace(/(?:file:\/\/)?(?:\/[^\s()]+)+(?=:\d+:\d+)/g, value => path.basename(value)));
+  console.error(JSON.stringify({ event: 'iris_local_api_error', requestId, frames }));
+}
+
+function headerCount(request, name) {
+  let count = 0;
+  for (let index = 0; index < request.rawHeaders.length; index += 2) {
+    if (request.rawHeaders[index].toLowerCase() === name) count++;
+  }
+  return count;
+}
+
+function query(url, allowed = []) {
+  for (const name of url.searchParams.keys()) {
+    if (!allowed.includes(name) || url.searchParams.getAll(name).length !== 1) {
+      fail('IRIS_API_INPUT_INVALID', '查询参数无效或重复');
+    }
+  }
+}
+
+function send(request, response, status, bytes, headers = {}) {
+  if (response.destroyed) return Promise.resolve();
+  return new Promise(resolve => {
+    let cleanupRequest = () => {};
+    const finish = () => { cleanupRequest(); response.off('finish', finish); response.off('close', finish); resolve(); };
+    response.once('finish', finish); response.once('close', finish);
+    response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': bytes.length,
+      'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': CSP,
+      'Referrer-Policy': 'no-referrer', ...headers });
+    if (status >= 400 && !request.complete && !request.destroyed) {
+      // Deliver the complete error before closing an upload with unread bytes. Closing immediately
+      // can reset the socket on Windows before the client receives the response. Discard the rest
+      // without buffering; the server's request/idle timeouts and dispose still bound the connection.
+      const end = () => { cleanupRequest(); response.end(); };
+      cleanupRequest = () => { request.off('end', end); request.off('close', end); };
+      request.once('end', end); request.once('close', end);
+      if (request.method === 'HEAD') response.flushHeaders();
+      else response.write(bytes);
+      request.resume();
+    } else response.end(request.method === 'HEAD' ? undefined : bytes);
+  });
+}
+const json = (request, response, value, status = 200) => send(request, response, status, Buffer.from(JSON.stringify(value)));
+
+/** Internal Host, read-only by default. Construction performs no I/O and never binds a port. */
+export function createLocalReadApi({ dataRoot, providerConfigPath, allowLocalWrites = false } = {}) {
+  if (typeof allowLocalWrites !== 'boolean') throw new TypeError('allowLocalWrites 必须是布尔值');
+  const suppliedRoot = normalizeCoreOptions({ dataRoot, mode: 'reader' }).dataRoot;
+  if (providerConfigPath !== undefined && (typeof providerConfigPath !== 'string' || !path.isAbsolute(providerConfigPath))) {
+    throw new LocalApiError('IRIS_API_CONFIG_INVALID', 'Provider 配置必须是显式绝对路径');
+  }
+  let state = 'new', origin = null, tokenDigest = null, application, server, physicalRoot;
+  let startPromise, disposal, closeRequested = false, activeReads = 0, activeUploads = 0, localWrites = 0;
+  const jobs = new Set(), instanceId = crypto.randomUUID();
+  let resolveClosed;
+  const closed = new Promise(resolve => { resolveClosed = resolve; });
+  const snapshot = () => Object.freeze({ contractVersion: 0, state, origin, readOnly: !allowLocalWrites, activeReads });
+
+  function authorize(request) {
+    const headers = request.headers;
+    if (headerCount(request, 'host') !== 1 || headers.host !== new URL(origin).host) {
+      fail('IRIS_API_HOST_DENIED', '请求地址不可信，请使用启动时给出的本机地址', 403);
+    }
+    if (headerCount(request, 'origin') > 1 || (headers.origin !== undefined && headers.origin !== origin)
+        || (headers['sec-fetch-site'] !== undefined && !['same-origin', 'none'].includes(headers['sec-fetch-site']))) {
+      fail('IRIS_API_ORIGIN_DENIED', '请求来源不可信', 403);
+    }
+    const match = headerCount(request, 'authorization') === 1 && /^Bearer +([A-Za-z0-9_-]{43})$/i.exec(headers.authorization || '');
+    if (!match || !crypto.timingSafeEqual(digest(match[1]), tokenDigest)) {
+      fail('IRIS_API_AUTH_REQUIRED', '需要有效的本机会话 Token', 401);
+    }
+  }
+
+  async function image(artifactId) {
+    // Use an operation-owned reader, with no writer lease or local export path.
+    const reader = createCoreRuntime({ dataRoot: physicalRoot, mode: 'reader' });
+    try {
+      reader.start();
+      return await reader.run('inspect', ({ dataRoot: physicalRoot }) => {
+        const metadata = inspectCoreArtifactMetadata(physicalRoot, artifactId);
+        if (!IMAGE_TYPES.has(metadata.mediaType)) fail('IRIS_API_MEDIA_UNSUPPORTED', '此接口只提供 PNG、JPEG 或 WebP 图片', 415);
+        if (metadata.size > MAX_LOCAL_API_IMAGE_BYTES) fail('IRIS_API_MEDIA_TOO_LARGE', '图片超过只读接口的 64 MiB 上限', 413);
+        const result = readCoreArtifactBytes(physicalRoot, artifactId);
+        if (result.bytes.length > MAX_LOCAL_API_IMAGE_BYTES || result.bytes.length !== result.artifact.size
+            || digest(result.bytes).toString('hex') !== result.artifact.digest.value) {
+          fail('IRIS_API_RECORD_CONFLICT', '图片字节与已保存记录不一致', 409);
+        }
+        return result;
+      });
+    } finally { await reader.dispose(); }
+  }
+
+  function models() {
+    if (!providerConfigPath) return { contractVersion: 0, configured: false, models: [], total: 0 };
+    const catalog = loadProviderCatalog(providerConfigPath);
+    let candidates;
+    try { candidates = imageCandidatesFromCatalog(catalog); }
+    catch (error) { if (error.code !== 'IRIS_PROVIDER_MODEL_UNAVAILABLE') throw error; candidates = []; }
+    const entries = candidates.map(route => ({ modelRef: route.modelRef, displayName: route.model,
+      supportsImageEdit: supportsImageEdit(route.provider.mediaProtocol, route.model) }));
+    return { contractVersion: 0, configured: true, models: entries, total: entries.length };
+  }
+
+  async function create(request, response, url) {
+    query(url);
+    if (!['/api/v0/images', '/api/v0/runs'].includes(url.pathname)) fail('IRIS_API_NOT_FOUND', '没有此本地创建接口', 404);
+    const isImage = url.pathname === '/api/v0/images';
+    if (headerCount(request, 'idempotency-key') !== 1 || !KEY.test(request.headers['idempotency-key'] || '')) {
+      fail('IRIS_API_INPUT_INVALID', 'Idempotency-Key 须为单个小写 UUIDv4');
+    }
+    if (headerCount(request, 'content-type') !== 1 || request.headers['content-encoding'] !== undefined) {
+      fail('IRIS_API_INPUT_INVALID', '正文需要单个 Content-Type，且不接受 Content-Encoding');
+    }
+    const mediaType = request.headers['content-type'];
+    if (isImage ? !IMAGE_TYPES.has(mediaType) : !/^application\/json(?:;\s*charset=utf-8)?$/i.test(mediaType)) {
+      fail('IRIS_API_MEDIA_UNSUPPORTED', '请提供静态 PNG/JPEG/WebP 原字节或 UTF-8 JSON', 415);
+    }
+    const limit = isImage ? MAX_IMPORT_IMAGE_BYTES : 64 * 1024;
+    if (request.headers['content-length'] !== undefined && Number(request.headers['content-length']) > limit) {
+      fail('IRIS_API_INPUT_TOO_LARGE', '正文超过允许的大小', 413);
+    }
+    if (isImage && activeUploads >= 1 || localWrites >= 9) fail('IRIS_API_BUSY', '本地创建繁忙，请使用原 Key 稍后重试', 429);
+    if (isImage) activeUploads++;
+    localWrites++;
+    const controller = new AbortController();
+    let prepared = false;
+    const disconnect = () => { if (!prepared) controller.abort(); };
+    response.once('close', disconnect);
+    try {
+      const chunks = [];
+      let size = 0;
+      for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+        size += chunk.length;
+        if (size > limit) fail('IRIS_API_INPUT_TOO_LARGE', '正文超过允许的大小', 413);
+        chunks.push(chunk);
+      }
+      if (Object.keys(request.trailers).length || size === 0) fail('IRIS_API_INPUT_INVALID', '正文不能为空或包含尾部头字段');
+      if (state !== 'open') fail('IRIS_API_UNAVAILABLE', '服务正在关闭', 503);
+      const bytes = Buffer.concat(chunks, size);
+      let value;
+      if (!isImage) {
+        try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+        catch (_) { fail('IRIS_API_INPUT_INVALID', '需要有效的 UTF-8 JSON'); }
+      }
+      const result = await application.execute(isImage ? 'creation.image' : 'creation.flow', {
+        key: request.headers['idempotency-key'], ...(isImage ? { bytes, mediaType } : { value })
+      }, { signal: controller.signal, onPrepared: () => { prepared = true; } });
+      const body = { contractVersion: 0, idempotentReplay: result.idempotentReplay,
+        ...(isImage ? { artifact: { artifactId: result.artifact.id, mediaType: result.artifact.mediaType,
+          size: result.artifact.size, width: result.artifact.metadata.width, height: result.artifact.metadata.height } }
+          : { flow: projectLocalApiFlow(result.flow) }) };
+      return await json(request, response, body, result.idempotentReplay ? 200 : 201);
+    } catch (error) {
+      if (request.aborted && !prepared) fail('IRIS_API_REQUEST_INTERRUPTED', '上传连接已中断，未接受本次创建');
+      throw error;
+    } finally {
+      response.off('close', disconnect); localWrites--;
+      if (isImage) activeUploads--;
+    }
+  }
+
+  async function route(request, response) {
+    if (state !== 'open') fail('IRIS_API_UNAVAILABLE', '服务正在关闭', 503);
+    authorize(request);
+    if (!['GET', 'HEAD'].includes(request.method) && !(allowLocalWrites && request.method === 'POST')) {
+      fail('IRIS_API_READ_ONLY', allowLocalWrites ? '仅支持 GET/HEAD 与明确的本地创建 POST' : '当前接口仅支持只读 GET/HEAD', 405);
+    }
+    if (request.method !== 'POST' && (request.headers['transfer-encoding'] !== undefined || (request.headers['content-length'] !== undefined && request.headers['content-length'] !== '0'))) {
+      fail('IRIS_API_INPUT_INVALID', '只读请求不接受正文');
+    }
+    if (!request.url.startsWith('/') || request.url.startsWith('//')) fail('IRIS_API_INPUT_INVALID', '请求路径无效');
+    const url = new URL(request.url, origin);
+    if (url.pathname !== request.url.split('?')[0]) fail('IRIS_API_INPUT_INVALID', '请求路径无效');
+    if (request.method === 'POST') return create(request, response, url);
+    const matchRun = /^\/api\/v0\/runs\/([^/]+)(\/download)?$/.exec(url.pathname);
+    const matchImage = /^\/api\/v0\/artifacts\/([^/]+)\/content$/.exec(url.pathname);
+    query(url, url.pathname === '/api/v0/runs' ? ['limit', 'cursor'] : []);
+    if (matchRun && !RUN.test(matchRun[1]) || matchImage && !ARTIFACT.test(matchImage[1])) {
+      fail('IRIS_API_INPUT_INVALID', '流程或图片 ID 格式无效');
+    }
+    if (activeReads >= 2) fail('IRIS_API_BUSY', '读取繁忙，请稍后再试', 429);
+    activeReads++;
+    try {
+      if (url.pathname === '/api/v0/session') {
+        return await json(request, response, { contractVersion: 0, instanceId, readOnly: !allowLocalWrites,
+          operations: ['models.list', 'runs.list', 'runs.inspect', 'artifacts.content', 'runs.download',
+            ...(allowLocalWrites ? ['images.create', 'runs.create'] : [])],
+          limits: { runPageSize: 30, imageBytes: MAX_LOCAL_API_IMAGE_BYTES, activeReads: 2,
+            ...(allowLocalWrites ? { uploadBytes: MAX_IMPORT_IMAGE_BYTES, jsonBytes: 64 * 1024, activeUploads: 1, localWrites: 9 } : {}) } });
+      }
+      if (url.pathname === '/api/v0/models') return await json(request, response, models());
+      if (url.pathname === '/api/v0/runs') {
+        const limitText = url.searchParams.get('limit') ?? '20';
+        if (!/^(?:[1-9]|[12][0-9]|30)$/.test(limitText)) fail('IRIS_API_INPUT_INVALID', 'limit 必须是 1–30 的整数');
+        const cursor = url.searchParams.get('cursor');
+        if (cursor !== null && !RUN.test(cursor)) fail('IRIS_API_INPUT_INVALID', '游标无效');
+        const result = await application.execute('flow.list', {});
+        const ordered = [...result.runs].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+        const index = cursor === null ? 0 : ordered.findIndex(run => run.id === cursor) + 1;
+        if (cursor !== null && index === 0) fail('IRIS_API_INPUT_INVALID', '游标已失效，请重新读取列表');
+        const page = ordered.slice(index, index + Number(limitText));
+        return await json(request, response, { contractVersion: 0, total: ordered.length,
+          runs: page.map(projectLocalApiRunSummary), nextCursor: index + page.length < ordered.length ? page.at(-1).id : null });
+      }
+      let artifactId;
+      if (matchRun) {
+        const view = projectLocalApiFlow(await application.execute('flow.inspect', { run_id: matchRun[1] }));
+        if (!matchRun[2]) return await json(request, response, view);
+        if (!view.selection) fail('IRIS_API_SELECTION_REQUIRED', '请先明确选择要下载的作品', 409);
+        artifactId = view.selection.artifactId;
+      } else if (matchImage) artifactId = matchImage[1];
+      else fail('IRIS_API_NOT_FOUND', '没有此只读接口', 404);
+      const result = await image(artifactId);
+      return await send(request, response, 200, result.bytes, { 'Content-Type': result.artifact.mediaType,
+        ...(matchRun ? { 'Content-Disposition': `attachment; filename="iris-${artifactId}.${IMAGE_TYPES.get(result.artifact.mediaType)}"` } : {}) });
+    } finally { activeReads--; }
+  }
+
+  async function handle(request, response) {
+    const requestId = crypto.randomUUID();
+    try { await route(request, response); }
+    catch (error) {
+      const safe = httpError(error);
+      if (safe.code === 'IRIS_API_INTERNAL') reportUnexpected(error, requestId);
+      await send(request, response, safe.status, Buffer.from(JSON.stringify({ contractVersion: 0,
+        error: { code: safe.code, message: safe.message, requestId } })), {
+        Connection: 'close', ...(safe.status === 401 ? { 'WWW-Authenticate': 'Bearer realm="iris-local"' } : {}),
+        ...(safe.status === 405 ? { Allow: allowLocalWrites ? 'GET, HEAD, POST' : 'GET, HEAD' } : {}) });
+    }
+  }
+
+  async function closeServer() {
+    if (!server?.listening) return;
+    const completion = new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+    server.closeAllConnections();
+    await completion;
+  }
+
+  function start({ port = 0 } = {}) {
+    if (state !== 'new') return Promise.reject(new LocalApiError('IRIS_API_LIFECYCLE', '服务只能显式启动一次', 409));
+    if (!Number.isInteger(port) || port < 0 || port > 65535) return Promise.reject(new LocalApiError('IRIS_API_INPUT_INVALID', '端口必须是 0–65535 的整数'));
+    state = 'starting';
+    const result = (async () => {
+      try {
+        const reader = createCoreRuntime({ dataRoot: suppliedRoot, mode: 'reader' });
+        try {
+          reader.start();
+          physicalRoot = await reader.run('inspect', ({ dataRoot: root }) => {
+            inspectFlowRoot(root);
+            if (allowLocalWrites) inspectCreationRoot(root);
+            return root;
+          });
+        } finally { await reader.dispose(); }
+        if (closeRequested) fail('IRIS_API_UNAVAILABLE', '启动已取消', 503);
+        application = createApplicationRuntime({ dataRoot: physicalRoot,
+          ...(allowLocalWrites && providerConfigPath ? { resolveImageCandidates: ({ modelRef }) =>
+            imageCandidatesFromCatalog(loadProviderCatalog(providerConfigPath), modelRef).map(route => ({
+              adapter: { id: route.provider.id, protocol: route.provider.mediaProtocol }, model: route.modelRef,
+              providerBinding: providerTaskBinding(route.provider), selectionReason: 'explicit'
+            })) } : {}) });
+        server = http.createServer({ maxHeaderSize: 8192, headersTimeout: 10000, requestTimeout: 15000 }, (request, response) => {
+          const job = handle(request, response).catch(error => {
+            reportUnexpected(error, crypto.randomUUID()); response.destroy();
+          });
+          jobs.add(job); void job.then(() => jobs.delete(job));
+        });
+        server.keepAliveTimeout = 1000; server.maxConnections = 32;
+        server.setTimeout(15000, socket => socket.destroy());
+        server.on('upgrade', (_request, socket) => socket.destroy());
+        server.on('connect', (_request, socket) => socket.destroy());
+        await new Promise((resolve, reject) => {
+          const onError = error => { server.off('listening', onListening); reject(error); };
+          const onListening = () => { server.off('error', onError); resolve(); };
+          server.once('error', onError); server.once('listening', onListening); server.listen(port, '127.0.0.1');
+        });
+        origin = `http://127.0.0.1:${server.address().port}`;
+        const accessToken = crypto.randomBytes(32).toString('base64url');
+        tokenDigest = digest(accessToken);
+        if (closeRequested) fail('IRIS_API_UNAVAILABLE', '启动已取消', 503);
+        state = 'open';
+        return Object.freeze({ origin, accessToken });
+      } catch (error) {
+        await closeServer(); await application?.dispose();
+        state = closeRequested ? 'closing' : 'closed';
+        if (!closeRequested) resolveClosed(snapshot());
+        throw error;
+      }
+    })();
+    // Retain only completion for lifecycle coordination; not the private start result containing the token.
+    startPromise = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  function dispose() {
+    if (disposal) return disposal;
+    closeRequested = true; state = 'closing'; tokenDigest?.fill(0);
+    disposal = (async () => {
+      if (startPromise) await startPromise.catch(() => {}); // start's caller retains the original failure.
+      await closeServer(); await application?.dispose(); await Promise.all([...jobs]);
+      state = 'closed'; resolveClosed(snapshot());
+      return snapshot();
+    })();
+    return disposal;
+  }
+  return Object.freeze({ start, dispose, snapshot, closed });
+}
+
+/** Explicit credential output, outside Core. Existing files and parent permissions are untouched. */
+export function writeLocalApiTokenFile(file, token, dataRoot) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) fail('IRIS_API_TOKEN_FILE_INVALID', '会话 Token 文件必须是新的绝对路径');
+  let fd;
+  try {
+    const root = fs.realpathSync(dataRoot), parent = fs.realpathSync(path.dirname(file));
+    const destination = path.join(parent, path.basename(file)), relative = path.relative(root, destination);
+    if (!relative || !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) {
+      fail('IRIS_API_TOKEN_FILE_INVALID', '会话 Token 文件必须放在 Core 数据根之外');
+    }
+    fd = fs.openSync(destination, 'wx', 0o600);
+    fs.writeFileSync(fd, token + '\n', 'utf8');
+  } catch (error) {
+    if (error instanceof LocalApiError) throw error;
+    fail('IRIS_API_TOKEN_FILE_UNAVAILABLE', '会话 Token 文件不可写或已存在，请指定新的根外文件');
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}

package/lib/local-creation.js

@@ -0,0 +1,85 @@
+// Internal, non-generating creation service. One supplied writer owns the complete intent/commit sequence.
+import crypto from 'node:crypto';
+import { createCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
+import { createImageFlowService } from './image-flow.js';
+import { readImportImage } from './image-import.js';
+import { normalizeGenerationInput } from './generation-input.js';
+import { initializeCreationRoot, inspectCreationRoot, creationRequestId, creationInputDigest,
+  readCreationRequest, publishCreationRequest, completeCreationRequest, creationFail } from './creation-request-store.js';
+
+const sha = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+function flowInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+      || Object.keys(input).some(key => !['sourceArtifactId', 'modelRef', 'prompt', 'size'].includes(key))
+      || !['sourceArtifactId', 'modelRef', 'prompt'].every(key => typeof input[key] === 'string')
+      || input.size !== undefined && typeof input.size !== 'string') {
+    creationFail('IRIS_CREATION_INPUT_INVALID', '流程创建只接受来源作品、明确模型、Prompt 和可选 size');
+  }
+  const normalized = normalizeGenerationInput('image', { source_artifact_id: input.sourceArtifactId,
+    model_ref: input.modelRef, prompt: input.prompt, ...(input.size !== undefined ? { size: input.size } : {}) });
+  return { source_artifact_id: normalized.sourceArtifactId, model_ref: normalized.modelRef,
+    ...normalized.providerInput };
+}
+export function createLocalCreationService(runtime, { resolveImageCandidates, onPrepared } = {}) {
+  const flows = createImageFlowService(runtime, { resolveImageCandidates });
+  function execute(name, input) {
+    return runtime.run('execute', async ({ dataRoot, signal }) => {
+      if (name === 'creation.init') return { contractVersion: 0, root: initializeCreationRoot(dataRoot) };
+      if (!['creation.image', 'creation.flow'].includes(name)) throw new TypeError('未知本地创建操作');
+      const kind = name === 'creation.image' ? 'image-import' : 'flow-create';
+      const marker = inspectCreationRoot(dataRoot), id = creationRequestId(marker, kind, input.key);
+      let source, owned;
+      if (kind === 'image-import') {
+        source = await readImportImage({ imageBytes: input.bytes }, signal);
+        if (source.mediaType !== input.mediaType) creationFail('IRIS_CREATION_MEDIA_MISMATCH', '图片真实格式与 Content-Type 不一致');
+        owned = { mediaType: source.mediaType, size: source.bytes.length, sha256: sha(source.bytes) };
+      } else owned = flowInput(input.value);
+      const inputDigest = creationInputDigest(kind, owned);
+      let request = readCreationRequest(dataRoot, id, marker);
+      const replay = Boolean(request);
+      if (request && request.inputDigest !== inputDigest) creationFail('IRIS_CREATION_KEY_CONFLICT', '该 Key 已绑定其他输入，请保留原请求或为新动作使用新 Key');
+      if (!request) {
+        const intent = kind === 'image-import'
+          ? { artifactId: 'artifact_' + crypto.randomBytes(12).toString('hex'), ...owned,
+            metadata: source.metadata, createdAt: new Date().toISOString() }
+          : await flows.prepareCreation(dataRoot, signal, owned);
+        signal.throwIfAborted();
+        request = publishCreationRequest(dataRoot, { schemaVersion: 0, id, rootId: marker.rootId, kind,
+          inputDigest, createdAt: intent.createdAt, intent, state: 'prepared' });
+      }
+      onPrepared?.(); // The Host now detaches HTTP disconnect cancellation; shutdown still reaches this runtime.
+      signal.throwIfAborted();
+      let result;
+      const intent = request.intent;
+      if (kind === 'image-import') {
+        if (request.state === 'prepared') {
+          result = createCoreArtifact(dataRoot, { artifactId: intent.artifactId, bytes: source.bytes,
+            mediaType: intent.mediaType, kind: 'imported-image', metadata: intent.metadata,
+            expectedDigest: intent.sha256, expectedSize: intent.size, createdAt: intent.createdAt });
+        } else {
+          try { result = readCoreArtifactBytes(dataRoot, intent.artifactId).artifact; }
+          catch (error) {
+            if (error.code !== 'IRIS_ARTIFACT_NOT_FOUND') throw error;
+            creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '该请求的原结果已不可用；不会重新创建或恢复已删除作品');
+          }
+        }
+        if (result.digest.value !== intent.sha256 || result.size !== intent.size || result.mediaType !== intent.mediaType
+            || result.kind !== 'imported-image' || result.createdAt !== intent.createdAt
+            || JSON.stringify(result.metadata) !== JSON.stringify(intent.metadata) || result.relations.length) {
+          creationFail('IRIS_CREATION_RESULT_CONFLICT', '原作品与请求意图不一致');
+        }
+        result = { artifact: result };
+      } else {
+        try { result = { flow: flows.inspectCreation(dataRoot, intent, { allowCreate: request.state === 'prepared' }) }; }
+        catch (error) {
+          if (request.state !== 'succeeded' || !['IRIS_FLOW_NOT_FOUND', 'IRIS_ARTIFACT_NOT_FOUND'].includes(error.code)) throw error;
+          creationFail('IRIS_CREATION_RESULT_UNAVAILABLE', '该请求的原流程或来源已不可用，不重新创建');
+        }
+      }
+      signal.throwIfAborted();
+      if (request.state === 'prepared') completeCreationRequest(dataRoot, request);
+      return { contractVersion: 0, idempotentReplay: replay, ...result };
+    });
+  }
+  return Object.freeze({ execute });
+}

package/lib/model-directory-service.js

@@ -0,0 +1,53 @@
+import { listModels } from './adapters.js';
+import { capabilitiesOfDiscoveredModel } from './models.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.js';
+import { MODEL_DIRECTORY_TTL_MS, MODEL_DIRECTORY_RETRY_MS, currentModelDirectory, modelDirectoryBinding } from './model-directory.js';
+
+const pending = new Map();
+
+/** 只有完整发现成功才替换快照；相同连接合并网络读取，各调用方保存自己的配置。 */
+export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now() } = {}) {
+  if (!['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music'].includes(selectMediaProtocol(provider).mediaProtocol)) {
+    return { refreshed: false, error: '当前协议未提供模型目录发现' };
+  }
+  const previous = currentModelDirectory(provider);
+  if (!force && previous) {
+    const stale = Boolean(previous.lastError) || !previous.checkedAt || now - Date.parse(previous.checkedAt) >= MODEL_DIRECTORY_TTL_MS
+      || Date.parse(previous.invalidatedAt || '') >= Date.parse(previous.checkedAt);
+    if (!stale || (previous.failedAt && now - Date.parse(previous.failedAt) < MODEL_DIRECTORY_RETRY_MS)) {
+      return { refreshed: false, directory: previous, ...(previous.lastError ? { error: previous.lastError } : {}) };
+    }
+  }
+  signal?.throwIfAborted();
+  const binding = modelDirectoryBinding(provider);
+  let job = pending.get(binding);
+  if (!job) {
+    const budget = AbortSignal.timeout(15000);
+    job = discover({ key: providerApiKey(provider), baseUrl: providerMediaBaseUrl(provider),
+      signal: signal ? AbortSignal.any([signal, budget]) : budget, timeoutMs: 15000 });
+    pending.set(binding, job);
+    job.finally(() => { if (pending.get(binding) === job) pending.delete(binding); }).catch(() => {});
+  }
+  let discovered;
+  try {
+    discovered = await job;
+  } catch (error) {
+    signal?.throwIfAborted();
+    const key = providerApiKey(provider);
+    const message = String(error?.message || error);
+    const directory = { version: 1, binding, ...(previous || {}), failedAt: new Date(now).toISOString(),
+      lastError: redactProviderMessage(key ? message.split(key).join('[REDACTED]') : message) };
+    if (await save(directory) === false) return { refreshed: false, error: '连接在目录同步期间发生变化，请重新同步' };
+    return { refreshed: false, directory, error: directory.lastError };
+  }
+  signal?.throwIfAborted();
+  const models = discovered.map(model => ({ id: typeof model === 'string' ? model : model.id,
+    capabilities: capabilitiesOfDiscoveredModel(model) }));
+  const known = new Set(previous?.models?.map(model => model.id)
+    || provider.models?.map(model => typeof model === 'string' ? model : model.id) || []);
+  const directory = { version: 1, binding, checkedAt: new Date(now).toISOString(), models,
+    added: models.filter(model => !known.has(model.id)).map(model => model.id) };
+  if (await save(directory) === false) return { refreshed: false, error: '连接在目录同步期间发生变化，请重新同步' };
+  return { refreshed: true, directory };
+}

package/lib/model-directory.js

@@ -0,0 +1,103 @@
+import crypto from 'node:crypto';
+import { isKnownCapability } from './capability.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol, providerForImageModel, providerForMusicModel } from './provider-protocol.js';
+
+export const MODEL_DIRECTORY_TTL_MS = 10 * 60 * 1000;
+export const MODEL_DIRECTORY_RETRY_MS = 30 * 1000;
+
+/** 配置是外部输入，目录只接受不含连接凭据的固定数据形状。 */
+export function validateModelDirectory(value) {
+  if (value === undefined) return;
+  if (!value || value.version !== 1 || !/^[a-f0-9]{64}$/.test(value.binding)
+      || (value.checkedAt !== undefined && !Number.isFinite(Date.parse(value.checkedAt)))
+      || (value.checkedAt && !Array.isArray(value.models))
+      || (value.models !== undefined && (!Array.isArray(value.models) || value.models.some(model =>
+        !model || typeof model.id !== 'string' || !model.id.trim() || !Array.isArray(model.capabilities)
+        || !model.capabilities.every(isKnownCapability))))
+      || (value.added !== undefined && (!Array.isArray(value.added) || !value.added.every(id => typeof id === 'string')))) {
+    throw new TypeError('模型目录快照结构无效');
+  }
+}
+
+/** 摘要绑定实际连接，不保存或回传密钥。 */
+export function modelDirectoryBinding(provider) {
+  return crypto.createHash('sha256').update(JSON.stringify([
+    provider.id, provider.type || '', provider.baseUrl || '', providerMediaBaseUrl(provider), selectMediaProtocol(provider).mediaProtocol,
+    provider.auth || 'bearer', providerApiKey(provider)
+  ])).digest('hex');
+}
+
+export function currentModelDirectory(provider, { allowUnresolvedConnections = false } = {}) {
+  const directory = provider?.modelDirectory;
+  if (!directory || directory.version !== 1) return null;
+  if (directory.binding === modelDirectoryBinding(provider)) return directory;
+  return allowUnresolvedConnections && provider.dshProvider && !provider.baseUrl ? directory : null;
+}
+
+export function modelAvailabilityBinding(provider, modelId, capability) {
+  if (capability === 'image-gen') return modelDirectoryBinding(providerForImageModel(provider, modelId));
+  if (capability === 'music-gen' && provider.models?.some(model => model?.id === modelId && model.musicProtocol)) {
+    return modelDirectoryBinding(providerForMusicModel(provider, modelId));
+  }
+  return modelDirectoryBinding(provider);
+}
+
+export function modelDirectoryEntry(provider, modelId, options) {
+  return currentModelDirectory(provider, options)?.models?.find(model => model.id === modelId) || null;
+}
+
+export function modelDirectoryStatus(provider, modelId) {
+  const directory = currentModelDirectory(provider, { allowUnresolvedConnections: true });
+  if (!directory?.checkedAt) return 'unknown';
+  return directory.models.some(model => model.id === modelId) ? 'listed' : 'unlisted';
+}
+
+/** 普通请求路径404或参数400不代表模型不存在。兼容已有精确404记录。 */
+export function isModelNotFound(result) {
+  if (result?.stage === 'poll') return false;
+  const status = Number(result?.httpStatus ?? result?.status);
+  if (status !== 404) return false;
+  const code = String(result?.providerCode || result?.code || '');
+  const message = String(result?.note || result?.safeMessage || result?.message || '');
+  return /^(?:NotFound\.Model|model_not_found|ModelNotFound)$/i.test(code)
+    || /\bModel not exist\./i.test(message);
+}
+
+/** 当前可选性与历史成功分开；旧Task成功不能解除新提交已确认的阻断。 */
+export function modelUnavailable(provider, modelId, capability, { allowUnresolvedConnections = false } = {}) {
+  const observation = provider?.health?.observations?.find(item => item.modelId === modelId && item.capability === capability);
+  const availability = observation?.availability;
+  if (availability) {
+    if (availability.binding !== modelAvailabilityBinding(provider, modelId, capability)
+        && !(allowUnresolvedConnections && provider.dshProvider && !provider.baseUrl)) return null;
+    return availability.state === 'blocked' ? availability : null;
+  }
+  const failure = [observation?.lastTransient, observation?.lastFailure].filter(isModelNotFound)
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)))[0];
+  if (!failure) return null;
+  if (observation.lastSuccess?.source === 'probe' && observation.lastSuccess.at >= failure.at) return null;
+  return { ...failure, state: 'blocked' };
+}
+
+export function modelUnavailableReason() {
+  return '当前连接已返回模型不存在，已暂停自动选用；请核对目录后单独实测恢复';
+}
+
+export function modelDirectorySummary(provider) {
+  const directory = currentModelDirectory(provider, { allowUnresolvedConnections: true });
+  if (!directory) return { status: 'unknown', note: '尚未同步当前连接的模型目录' };
+  const models = directory.models || [];
+  const configuredIds = Array.isArray(provider.models)
+    ? provider.models.map(model => typeof model === 'string' ? model : model.id)
+    : [...new Set(['imageModel', 'videoModel', 'ttsModel', 'musicModel', 'transcribeModel', 'visionModel']
+      .map(field => provider[field]).filter(id => typeof id === 'string' && id.trim()).map(id => id.trim()))];
+  const missing = directory.checkedAt ? configuredIds.filter(id => !models.some(model => model.id === id)) : [];
+  const stale = Boolean(directory.lastError) || Date.now() - Date.parse(directory.checkedAt || '') >= MODEL_DIRECTORY_TTL_MS
+    || Date.parse(directory.invalidatedAt || '') >= Date.parse(directory.checkedAt || '');
+  return {
+    status: directory.checkedAt ? stale ? 'stale' : 'current' : 'unknown',
+    checkedAt: directory.checkedAt || null, modelCount: models.length,
+    added: directory.added || [], missing,
+    ...(directory.lastError ? { error: directory.lastError, failedAt: directory.failedAt } : {})
+  };
+}