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

package/lib/operation-store.js

@@ -0,0 +1,216 @@
+// Durable, non-executing local intentions. Call mutations under the supplied Core writer.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { inspectLocalRequestRoot, initializeLocalRequestRoot, requestDirectory } from './local-request-root.js';
+import { listCreationRequests } from './creation-request-store.js';
+import { readFlowRun, flowStep } from './flow-store.js';
+import { findFlowTask } from './core-tasks.js';
+import { findCoreArtifactMetadata } from './core-artifacts.js';
+import { validatePluginOperation, validatePluginBinding, transitionPluginOperation, projectPluginOperation } from './plugin-operation-store.js';
+
+const ID = /^op_[a-f0-9]{64}$/;
+const RUN = /^run_[a-f0-9]{24}$/;
+const TASK = /^task_[a-f0-9]{24}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+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 DIGEST = /^sha256:[a-f0-9]{64}$/;
+const STATES = new Set(['queued', 'running', 'succeeded', 'failed', 'canceled', 'interrupted']);
+const ACTIVE = new Set(['queued', 'running']);
+const FAILURE_CODES = new Set(['run_changed', 'execution_failed']);
+export const MAX_ACTIVE_OPERATIONS = 8;
+export function operationFail(code, message) { throw Object.assign(new Error(message), { code }); }
+const invalid = () => operationFail('IRIS_OPERATION_STORE_INVALID', 'Operation 记录未知、损坏或与请求容器不一致');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const iso = value => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const positive = value => Number.isSafeInteger(value) && value >= 1;
+function keys(value, allowed, required = allowed) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key)));
+}
+function input(value, allowed, required = allowed) {
+  if (!keys(value, allowed, required)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 输入包含缺失或不支持的字段');
+}
+export function inspectExecutionRoot(root) {
+  const marker = inspectLocalRequestRoot(root, { allowAbsent: true });
+  if (![1, 2, 3, 4].includes(marker?.schemaVersion)) operationFail('IRIS_OPERATION_ROOT_REQUIRED', 'Operation 需要新的专用执行根，请显式执行 execution init；不转换原根');
+  return marker;
+}
+export function initializeExecutionRoot(root, { imageGeneration = false, audio = false, video = false } = {}) {
+  const marker = initializeLocalRequestRoot(root, video ? 4 : audio ? 3 : imageGeneration ? 2 : 1);
+  listCreationRequests(root); readAllOperations(root);
+  return marker;
+}
+export function operationId(marker, key) {
+  if (!UUID.test(key)) operationFail('IRIS_OPERATION_KEY_INVALID', 'Operation Key 须为小写 UUIDv4');
+  return 'op_' + hash(JSON.stringify(['operation/v0', marker.rootId, key]));
+}
+function inputDigest(runId, revision) {
+  return 'sha256:' + hash(JSON.stringify(['operation-call/v0', 'flow.continue', runId, revision]));
+}
+const bindingFor = run => ({ taskId: flowStep(run).taskId, sourceArtifactId: run.source?.artifactId ?? null,
+  comparisonArtifactId: run.compare?.artifactId ?? null, inputDigest: run.inputDigest });
+const artifactsFor = run => [...new Set([run.source?.artifactId, run.output?.artifactId, run.comparison?.artifactId, run.selection?.artifactId].filter(Boolean))];
+function validate(record, id, marker) {
+  if (record?.schemaVersion === 1) return validatePluginOperation(record, id, marker);
+  if (!keys(record, ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'runId', 'expectedRunRevision', 'inputDigest',
+    'ownerInstanceId', 'binding', 'createdAt', 'updatedAt', 'state', 'cancelRequested', 'startedAt', 'finishedAt', 'result', 'failureCode'],
+  ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'runId', 'expectedRunRevision', 'inputDigest',
+    'ownerInstanceId', 'binding', 'createdAt', 'updatedAt', 'state', 'cancelRequested'])
+      || record.schemaVersion !== 0 || !ID.test(id) || record.id !== id || record.rootId !== marker.rootId
+      || !positive(record.revision) || record.action !== 'flow.continue' || !RUN.test(record.runId)
+      || !positive(record.expectedRunRevision) || record.inputDigest !== inputDigest(record.runId, record.expectedRunRevision)
+      || !UUID.test(record.ownerInstanceId) || !STATES.has(record.state) || typeof record.cancelRequested !== 'boolean'
+      || !iso(record.createdAt) || !iso(record.updatedAt) || record.updatedAt < record.createdAt
+      || !keys(record.binding, ['taskId', 'sourceArtifactId', 'comparisonArtifactId', 'inputDigest'])
+      || !TASK.test(record.binding.taskId) || !([3, 4].includes(marker.schemaVersion) && (record.binding.sourceArtifactId === null || ARTIFACT.test(record.binding.sourceArtifactId))
+        && (record.binding.comparisonArtifactId === null || ARTIFACT.test(record.binding.comparisonArtifactId))
+        || record.binding.sourceArtifactId === null && record.binding.comparisonArtifactId === null && marker.schemaVersion === 2
+        || ARTIFACT.test(record.binding.sourceArtifactId) && ARTIFACT.test(record.binding.comparisonArtifactId))
+      || !DIGEST.test(record.binding.inputDigest)) invalid();
+  const hasStarted = Object.hasOwn(record, 'startedAt');
+  if (record.revision !== (record.state === 'queued' ? 1 : record.state === 'running' || !hasStarted ? 2 : 3)) invalid();
+  if (hasStarted && (!iso(record.startedAt) || record.startedAt < record.createdAt || record.startedAt > record.updatedAt)) invalid();
+  if (record.state === 'queued' && (record.revision !== 1 || record.updatedAt !== record.createdAt || hasStarted || record.cancelRequested)
+      || record.state === 'running' && (!hasStarted || record.cancelRequested)
+      || record.state === 'succeeded' && (!hasStarted || record.cancelRequested)
+      || record.cancelRequested !== (record.state === 'canceled')
+      || record.state === 'failed' && !FAILURE_CODES.has(record.failureCode)
+      || record.state !== 'failed' && Object.hasOwn(record, 'failureCode')) invalid();
+  if (ACTIVE.has(record.state)) {
+    if (Object.hasOwn(record, 'finishedAt') || Object.hasOwn(record, 'result')) invalid();
+  } else {
+    if (!iso(record.finishedAt) || record.finishedAt !== record.updatedAt || record.finishedAt < record.createdAt
+        || !keys(record.result, ['runRevision', 'taskId', 'artifactIds']) || !positive(record.result.runRevision)
+        || record.result.runRevision < record.expectedRunRevision
+        || record.result.taskId !== null && record.result.taskId !== record.binding.taskId
+        || !Array.isArray(record.result.artifactIds) || record.binding.sourceArtifactId !== null && !record.result.artifactIds.length
+        || new Set(record.result.artifactIds).size !== record.result.artifactIds.length
+        || !record.result.artifactIds.every(value => ARTIFACT.test(value))
+        || record.binding.sourceArtifactId !== null && !record.result.artifactIds.includes(record.binding.sourceArtifactId)
+        || record.state === 'succeeded' && !record.result.taskId) invalid();
+  }
+  return record;
+}
+function validateBinding(root, record) {
+  if (record.action === 'plugin.execute') return validatePluginBinding(root, record);
+  const run = readFlowRun(root, record.runId), task = findFlowTask(root, run);
+  if (Object.entries(bindingFor(run)).some(([key, value]) => record.binding[key] !== value) || run.revision < record.expectedRunRevision
+      || record.result && (record.result.runRevision > run.revision || record.result.taskId && !task
+        || record.result.artifactIds.some(id => !artifactsFor(run).includes(id)))) {
+    operationFail('IRIS_OPERATION_BINDING_CONFLICT', 'Operation 与原 Run/Task/作品绑定冲突，停止操作并保留原记录');
+  }
+  return { run, task };
+}
+function fileFor(root, marker, id) {
+  if (!ID.test(id)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation ID 格式无效');
+  return path.join(requestDirectory(root, marker, 'operations'), id + '.json');
+}
+export function readOperation(root, id, marker = inspectExecutionRoot(root)) {
+  const file = fileFor(root, marker, id);
+  let record;
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) invalid();
+    try { record = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  validate(record, id, marker); validateBinding(root, record);
+  return structuredClone(record);
+}
+export function readAllOperations(root) {
+  const marker = inspectLocalRequestRoot(root, { allowAbsent: true });
+  if (!marker || marker.schemaVersion === 0) return [];
+  const records = [];
+  for (const name of fs.readdirSync(requestDirectory(root, marker, 'operations'))) {
+    if (/^op_[a-f0-9]{64}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name)) continue;
+    if (!/^op_[a-f0-9]{64}\.json$/.test(name)) invalid();
+    const record = readOperation(root, name.slice(0, -5), marker);
+    if (!record) invalid();
+    records.push(record);
+  }
+  const active = records.filter(record => ACTIVE.has(record.state));
+  if (active.length > MAX_ACTIVE_OPERATIONS || new Set(active.filter(record => record.action === 'flow.continue').map(record => record.runId)).size !== active.filter(record => record.action === 'flow.continue').length) invalid();
+  return records;
+}
+
+export function acceptOperation(root, value) {
+  input(value, ['key', 'runId', 'expectedRunRevision', 'ownerInstanceId']);
+  if (!RUN.test(value.runId) || !positive(value.expectedRunRevision) || !UUID.test(value.ownerInstanceId)) {
+    operationFail('IRIS_OPERATION_INPUT_INVALID', '需要明确 Run、正整数 revision 与 owner 实例 UUID');
+  }
+  const marker = inspectExecutionRoot(root), id = operationId(marker, value.key);
+  const fingerprint = inputDigest(value.runId, value.expectedRunRevision), previous = readOperation(root, id, marker);
+  if (previous) {
+    if (previous.inputDigest !== fingerprint) operationFail('IRIS_OPERATION_KEY_CONFLICT', '该 Key 已绑定其他操作输入');
+    return { operation: previous, idempotentReplay: true };
+  }
+  const run = readFlowRun(root, value.runId); findFlowTask(root, run);
+  if (run.revision !== value.expectedRunRevision) operationFail('IRIS_OPERATION_RUN_CHANGED', 'Run revision 已改变，请读取原流程后明确操作');
+  const active = readAllOperations(root).filter(record => ACTIVE.has(record.state));
+  const conflicting = active.find(record => record.runId === run.id);
+  if (conflicting) throw Object.assign(new Error('此 Run 已有未结束的 Operation'), { code: 'IRIS_OPERATION_RUN_BUSY', operationId: conflicting.id });
+  if (active.length >= MAX_ACTIVE_OPERATIONS) operationFail('IRIS_OPERATION_QUEUE_FULL', '未结束的 Operation 已达上限，本次未接收');
+  const now = new Date().toISOString();
+  const record = { schemaVersion: 0, id, rootId: marker.rootId, revision: 1, action: 'flow.continue', runId: run.id,
+    expectedRunRevision: value.expectedRunRevision, inputDigest: fingerprint, ownerInstanceId: value.ownerInstanceId,
+    binding: bindingFor(run), createdAt: now, updatedAt: now, state: 'queued', cancelRequested: false };
+  validate(record, id, marker);
+  atomicCreatePrivate(fileFor(root, marker, id), JSON.stringify(record, null, 2) + '\n');
+  return { operation: structuredClone(record), idempotentReplay: false };
+}
+
+/** Store-only CAS. It neither runs flow.continue nor delivers an abort signal or remote cancel. */
+export function transitionOperation(root, value) {
+  input(value, ['id', 'expectedRevision', 'state', 'failureCode', 'value'], ['id', 'expectedRevision', 'state']);
+  if (!positive(value.expectedRevision) || !STATES.has(value.state)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 状态或 revision 无效');
+  const marker = inspectExecutionRoot(root), current = readOperation(root, value.id, marker);
+  if (!current) operationFail('IRIS_OPERATION_NOT_FOUND', 'Operation 不存在');
+  if (current.action === 'plugin.execute') return transitionPluginOperation(root, marker, value);
+  if (Object.hasOwn(value, 'value')) operationFail('IRIS_OPERATION_INPUT_INVALID', '媒体流程不接受插件业务结果');
+  if (current.revision !== value.expectedRevision) operationFail('IRIS_OPERATION_REVISION_CONFLICT', 'Operation 已改变，请先读取原记录');
+  const allowed = current.state === 'queued' ? ['running', 'canceled', 'interrupted', 'failed']
+    : current.state === 'running' ? ['succeeded', 'failed', 'canceled', 'interrupted'] : [];
+  if (!allowed.includes(value.state)) operationFail('IRIS_OPERATION_TRANSITION_INVALID', '不允许此 Operation 状态转换；结束记录不重新排队');
+  if (value.state === 'failed' ? !FAILURE_CODES.has(value.failureCode)
+    : Object.hasOwn(value, 'failureCode')) operationFail('IRIS_OPERATION_INPUT_INVALID', '失败记录只接受有限错误类别，不保存异常原文');
+  const { run, task } = validateBinding(root, current);
+  if (value.state === 'running' && run.revision !== current.expectedRunRevision) operationFail('IRIS_OPERATION_RUN_CHANGED', 'Run revision 已改变，未开始本次调用');
+  if (value.state === 'succeeded' && !task) operationFail('IRIS_OPERATION_RESULT_INVALID', '没有原 Task 事实，不能记录调用成功');
+  const now = new Date(Math.max(Date.now(), Date.parse(current.updatedAt))).toISOString();
+  const next = { ...current, revision: current.revision + 1, state: value.state, updatedAt: now,
+    cancelRequested: value.state === 'canceled',
+    ...(value.state === 'running' ? { startedAt: now } : { finishedAt: now,
+      result: { runRevision: run.revision, taskId: task?.id || null, artifactIds: artifactsFor(run) } }),
+    ...(value.state === 'failed' ? { failureCode: value.failureCode } : {}) };
+  validate(next, next.id, marker);
+  atomicWritePrivate(fileFor(root, marker, next.id), JSON.stringify(next, null, 2) + '\n');
+  return structuredClone(next);
+}
+
+export function listOperations(root, value = {}) {
+  input(value, ['runId', 'limit', 'cursor'], []);
+  if (value.runId !== undefined && !RUN.test(value.runId) || value.limit !== undefined && (!positive(value.limit) || value.limit > 30)
+      || value.cursor !== undefined && !ID.test(value.cursor)) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 列表参数无效');
+  inspectExecutionRoot(root);
+  const ordered = readAllOperations(root).filter(record => value.runId === undefined || record.runId === value.runId)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+  const offset = value.cursor === undefined ? 0 : ordered.findIndex(record => record.id === value.cursor) + 1;
+  if (value.cursor !== undefined && offset === 0) operationFail('IRIS_OPERATION_INPUT_INVALID', 'Operation 游标不属于当前列表');
+  const page = ordered.slice(offset, offset + (value.limit ?? 20));
+  return { operations: page, total: ordered.length, nextCursor: offset + page.length < ordered.length ? page.at(-1).id : null };
+}
+export function operationReferences(root) {
+  return readAllOperations(root).map(record => record.action === 'plugin.execute' ? { operationId: record.id, runId: null, taskIds: [],
+    artifactIds: [...new Set([...record.sourceArtifactIds, ...record.reservedArtifactIds.filter(id => findCoreArtifactMetadata(root, id))])] } : ({ operationId: record.id, runId: record.runId,
+    taskIds: [record.binding.taskId], artifactIds: [...new Set([record.binding.sourceArtifactId,
+      record.binding.comparisonArtifactId, ...(record.result?.artifactIds || [])].filter(Boolean))] }));
+}
+export function projectOperation(record) {
+  if (record.action === 'plugin.execute') return projectPluginOperation(record);
+  return { contractVersion: 0, id: record.id, action: record.action, runId: record.runId,
+    revision: record.revision, expectedRunRevision: record.expectedRunRevision, state: record.state,
+    createdAt: record.createdAt, updatedAt: record.updatedAt, cancelRequested: record.cancelRequested,
+    ...(record.startedAt ? { startedAt: record.startedAt } : {}), ...(record.finishedAt ? { finishedAt: record.finishedAt } : {}),
+    ...(record.result ? { result: structuredClone(record.result) } : {}), ...(record.failureCode ? { failureCode: record.failureCode } : {}) };
+}

package/lib/panel-extension.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PANEL_CONTRACT_VERSION = 0;
+const TYPES = new Map([['.html', 'text/html; charset=utf-8'], ['.js', 'text/javascript; charset=utf-8'],
+  ['.css', 'text/css; charset=utf-8'], ['.svg', 'image/svg+xml'], ['.png', 'image/png'], ['.jpg', 'image/jpeg'],
+  ['.webp', 'image/webp'], ['.woff2', 'font/woff2']]);
+const fail = () => { throw Object.assign(new TypeError('Panel 清单、版本或固定资源无效'), { code: 'IRIS_PANEL_INVALID' }); };
+
+/** Explicit trusted static Panel. Pin its finite assets before exposing any public route. */
+export function loadPanelExtension(manifestPath) {
+  if (typeof manifestPath !== 'string' || !path.isAbsolute(manifestPath)) fail();
+  const file = fs.realpathSync(manifestPath), root = path.dirname(file);
+  if (!fs.statSync(file).isFile() || fs.statSync(file).size > 65536) fail();
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { fail(); }
+  if (!manifest || manifest.contractVersion !== PANEL_CONTRACT_VERSION || !/^[a-z][a-z0-9._-]{0,79}$/.test(manifest.id)
+    || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(manifest.version)
+    || Object.keys(manifest).some(key => !['contractVersion', 'id', 'version', 'assets'].includes(key))
+    || !manifest.assets || typeof manifest.assets !== 'object' || Array.isArray(manifest.assets)) fail();
+  const entries = Object.entries(manifest.assets), assets = new Map();
+  if (!entries.length || entries.length > 128 || !Object.hasOwn(manifest.assets, '/')) fail();
+  let total = 0;
+  for (const [route, relative] of entries) {
+    if (route !== '/' && (!/^\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_.-]+$/.test(route)
+      || route.startsWith('/api/') || route === '/mcp' || route.startsWith('/mcp/'))
+      || typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) fail();
+    const target = fs.realpathSync(path.resolve(root, relative)), rel = path.relative(root, target), stat = fs.statSync(target);
+    const mediaType = TYPES.get(path.extname(target));
+    if (!rel || rel.startsWith('..' + path.sep) || path.isAbsolute(rel) || !stat.isFile() || !mediaType
+      || stat.size > 8 * 1024 * 1024 || (total += stat.size) > 16 * 1024 * 1024 || route === '/' && path.extname(target) !== '.html') fail();
+    assets.set(route, { bytes: fs.readFileSync(target), mediaType });
+  }
+  return Object.freeze({ identity: Object.freeze({ contractVersion: PANEL_CONTRACT_VERSION, id: manifest.id, version: manifest.version }),
+    has: route => assets.has(route), read: async route => assets.get(route) || null });
+}

package/lib/plugin-contract.js

@@ -0,0 +1,194 @@
+// Experimental contribution contract. No Host, filesystem, registry or execution state.
+export const PLUGIN_CONTRACT_VERSION = 0;
+export const PLUGIN_KINDS = Object.freeze(['providers', 'operations', 'pages', 'renderers', 'settings']);
+export const PLUGIN_CORE_COMMANDS = Object.freeze({
+  'artifact.inspect': 'reader', 'artifact.list': 'reader', 'artifact.read': 'reader',
+  'task.inspect': 'reader', 'task.list': 'reader', 'artifact.import': 'writer'
+});
+
+const ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const VERSION = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const MIME = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+const CAPS = new Set(['image-gen', 'video-gen', 'tts', 'music-gen', 'transcribe']);
+const CORE_NAMESPACES = new Set(['iris', 'artifact', 'task', 'media', 'flow', 'creation', 'execution', 'operation', 'core']);
+
+export class PluginContractError extends Error {
+  constructor(code, message) { super(message); this.name = 'PluginContractError'; this.code = code; }
+}
+export function pluginFail(code, message) { throw new PluginContractError(code, message); }
+const invalid = message => pluginFail('IRIS_PLUGIN_INVALID', message);
+export const pluginObject = value => value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+export function pluginFields(value, allowed, required = allowed) {
+  return pluginObject(value) && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key));
+}
+function versionParts(value) {
+  const match = typeof value === 'string' && value.length <= 160 && value.match(VERSION);
+  if (!match || match[4]?.split('.').some(part => /^[0-9]+$/.test(part) && part.length > 1 && part[0] === '0')) invalid('插件版本须为有效 SemVer');
+  return { core: match.slice(1, 4), pre: match[4]?.split('.') || [] };
+}
+const numericOrder = (a, b) => a.length === b.length ? a === b ? 0 : a < b ? -1 : 1 : a.length < b.length ? -1 : 1;
+/** SemVer precedence only; compatibility is a closed/open interval, not npm range syntax. */
+export function comparePluginVersions(a, b) {
+  const left = versionParts(a), right = versionParts(b);
+  for (let i = 0; i < 3; i++) { const order = numericOrder(left.core[i], right.core[i]); if (order) return order; }
+  if (!left.pre.length || !right.pre.length) return left.pre.length === right.pre.length ? 0 : left.pre.length ? -1 : 1;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+    const x = left.pre[i], y = right.pre[i];
+    if (x === undefined || y === undefined) return x === y ? 0 : x === undefined ? -1 : 1;
+    if (x === y) continue;
+    const xn = /^[0-9]+$/.test(x), yn = /^[0-9]+$/.test(y);
+    return xn && yn ? numericOrder(x, y) : xn !== yn ? xn ? -1 : 1 : x < y ? -1 : 1;
+  }
+  return 0;
+}
+function checkedId(value) {
+  if (typeof value !== 'string' || value.length > 80 || !ID.test(value)) invalid('插件及贡献 ID 须为有界小写标识');
+  return value;
+}
+export function qualifiedPluginId(pluginId, localId) { return checkedId(checkedId(pluginId) + '.' + checkedId(localId)); }
+function label(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 200 || /[\x00-\x1f\x7f]/.test(value)) invalid('贡献标题无效');
+  return value;
+}
+function asset(value, extension) {
+  if (typeof value !== 'string' || !/^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+$/.test(value)
+      || !extension.test(value) || value.split('/').some(part => part === '.' || part === '..')) invalid('Web 入口须为插件内相对 JS/MJS 路径，样式须为 CSS');
+  return value;
+}
+/** JSON boundaries never coerce, strip fields or preserve mutable author-owned objects. */
+export function pluginJson(value, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return value;
+  if ((!Array.isArray(value) && !pluginObject(value)) || ancestors.has(value)) invalid('插件描述、输入和结果须为无循环的 JSON 数据');
+  ancestors.add(value);
+  const result = Array.isArray(value) ? value.map(item => pluginJson(item, ancestors))
+    : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, pluginJson(item, ancestors)]));
+  ancestors.delete(value);
+  return result;
+}
+export function freezePluginValue(value) {
+  if (value && typeof value === 'object') { for (const item of Object.values(value)) freezePluginValue(item); Object.freeze(value); }
+  return value;
+}
+
+// A documented JSON Schema subset; unknown/default/ref keywords must not be silently ignored.
+function checkedInputSchema(value) {
+  const fields = ['type', 'title', 'description', 'properties', 'required', 'additionalProperties', 'items', 'anyOf', 'enum', 'const',
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'minLength', 'maxLength', 'pattern', 'minItems', 'maxItems'];
+  if (!pluginFields(value, fields, []) || value.type !== undefined && !['object', 'array', 'string', 'integer', 'number', 'boolean', 'null'].includes(value.type)) invalid('业务输入包含未支持的 JSON Schema 字段或类型');
+  if (value.properties !== undefined) {
+    if (!pluginObject(value.properties)) invalid('Schema properties 必须为对象');
+    for (const item of Object.values(value.properties)) checkedInputSchema(item);
+  }
+  if (value.required !== undefined && (!Array.isArray(value.required) || new Set(value.required).size !== value.required.length
+      || value.required.some(key => typeof key !== 'string' || !Object.hasOwn(value.properties || {}, key)))) invalid('Schema required 必须引用已声明属性');
+  if (value.items !== undefined) checkedInputSchema(value.items);
+  if (value.additionalProperties !== undefined && typeof value.additionalProperties !== 'boolean') checkedInputSchema(value.additionalProperties);
+  if (value.anyOf !== undefined) {
+    if (!Array.isArray(value.anyOf) || !value.anyOf.length) invalid('Schema anyOf 须为非空 Schema 数组');
+    value.anyOf.forEach(checkedInputSchema);
+  }
+  for (const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf']) {
+    if (value[key] !== undefined && (typeof value[key] !== 'number' || !Number.isFinite(value[key]) || key === 'multipleOf' && value[key] <= 0)) invalid('Schema 数值约束类型无效');
+  }
+  for (const key of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+    if (value[key] !== undefined && (!Number.isSafeInteger(value[key]) || value[key] < 0)) invalid('Schema 长度约束须为非负整数');
+  }
+  if (value.pattern !== undefined && typeof value.pattern !== 'string' || value.enum !== undefined && (!Array.isArray(value.enum) || !value.enum.length)
+      || value.title !== undefined && typeof value.title !== 'string' || value.description !== undefined && typeof value.description !== 'string') invalid('Schema 文本或枚举约束无效');
+  return value;
+}
+
+function checkedContribution(kind, value) {
+  const common = ['id', 'version', 'title'];
+  const fields = kind === 'providers' ? ['capabilities', 'configuration'] : kind === 'operations' ? ['mode', 'commands', 'inputSchema', 'artifactInputs']
+    : kind === 'renderers' ? ['entry', 'styles', 'mediaTypes'] : ['entry', 'styles'];
+  const required = [...common, ...fields.filter(field => !['configuration', 'styles', 'artifactInputs'].includes(field))];
+  if (!pluginFields(value, [...common, ...fields], required)) invalid('贡献字段不符合 ' + kind + ' 契约');
+  const result = { id: checkedId(value.id), version: value.version, title: label(value.title) }; versionParts(value.version);
+  if (kind === 'providers') {
+    if (!Array.isArray(value.capabilities) || !value.capabilities.length || value.capabilities.some(cap => !CAPS.has(cap))
+        || new Set(value.capabilities).size !== value.capabilities.length) invalid('Provider 能力须为支持的明确列表');
+    const configuration = value.configuration === undefined ? [] : value.configuration;
+    if (!Array.isArray(configuration) || new Set(configuration.map(field => field?.key)).size !== configuration.length) invalid('Provider 配置字段重复或无效');
+    for (const field of configuration) {
+      if (!pluginFields(field, ['key', 'label', 'type', 'required', 'advanced'], ['key', 'label', 'type'])
+          || !['baseUrl', 'mediaBaseUrl', 'apiKey'].includes(field.key) || field.type !== (field.key === 'apiKey' ? 'secret' : 'url')
+          || field.required !== undefined && typeof field.required !== 'boolean' || field.advanced !== undefined && typeof field.advanced !== 'boolean') invalid('Provider 配置描述无效');
+      label(field.label);
+    }
+    Object.assign(result, { capabilities: [...value.capabilities], configuration: pluginJson(configuration) });
+  } else if (kind === 'operations') {
+    if (!['reader', 'writer'].includes(value.mode) || !Array.isArray(value.commands) || new Set(value.commands).size !== value.commands.length
+        || value.commands.some(name => typeof name !== 'string' || !Object.hasOwn(PLUGIN_CORE_COMMANDS, name)
+          || value.mode === 'reader' && PLUGIN_CORE_COMMANDS[name] !== 'reader')) invalid('业务模式或 Core 命令声明无效');
+    if (!pluginObject(value.inputSchema) || value.inputSchema.type !== 'object' || value.inputSchema.additionalProperties !== false) invalid('业务输入须声明封闭的 JSON 对象 Schema');
+    Object.assign(result, { mode: value.mode, commands: [...value.commands], inputSchema: checkedInputSchema(pluginJson(value.inputSchema)) });
+    if (value.artifactInputs !== undefined) {
+      if (!Array.isArray(value.artifactInputs) || new Set(value.artifactInputs).size !== value.artifactInputs.length
+          || value.artifactInputs.some(key => { const field = result.inputSchema.properties?.[key];
+            return typeof key !== 'string' || !(field?.type === 'string' || field?.type === 'array' && field.items?.type === 'string'); })) invalid('artifactInputs 须引用顶层 Artifact ID 字符串或数组字段');
+      result.artifactInputs = [...value.artifactInputs];
+    }
+  } else {
+    result.entry = asset(value.entry, /\.m?js$/);
+    if (value.styles !== undefined) {
+      if (!Array.isArray(value.styles) || new Set(value.styles).size !== value.styles.length) invalid('样式列表无效');
+      result.styles = value.styles.map(file => asset(file, /\.css$/));
+    }
+    if (kind === 'renderers') {
+      if (!Array.isArray(value.mediaTypes) || !value.mediaTypes.length || new Set(value.mediaTypes).size !== value.mediaTypes.length
+          || value.mediaTypes.some(type => typeof type !== 'string' || !MIME.test(type))) invalid('作品渲染器须声明准确媒体类型，不接受通配符');
+      result.mediaTypes = [...value.mediaTypes];
+    }
+  }
+  return result;
+}
+
+export function checkedPluginManifest(value) {
+  if (!pluginFields(value, ['contractVersion', 'id', 'version', 'compatibility', 'contributions'])
+      || value.contractVersion !== PLUGIN_CONTRACT_VERSION || !pluginFields(value.compatibility, ['min', 'maxExclusive'])
+      || !pluginFields(value.contributions, PLUGIN_KINDS, [])) invalid('插件清单或契约版本无效');
+  const id = checkedId(value.id); versionParts(value.version);
+  if (CORE_NAMESPACES.has(id) || id.startsWith('iris.')) invalid('插件 ID 不能使用 Core 保留的命名空间');
+  if (comparePluginVersions(value.compatibility.min, value.compatibility.maxExclusive) >= 0) invalid('Core 兼容区间须为 min <= version < maxExclusive');
+  const contributions = {};
+  for (const kind of PLUGIN_KINDS) {
+    const entries = value.contributions[kind] === undefined ? [] : value.contributions[kind];
+    if (!Array.isArray(entries)) invalid('贡献必须为数组');
+    contributions[kind] = entries.map(entry => checkedContribution(kind, entry));
+    const ids = contributions[kind].map(entry => qualifiedPluginId(id, entry.id));
+    if (new Set(ids).size !== ids.length) invalid('同类贡献 ID 重复');
+  }
+  if (!Object.values(contributions).some(entries => entries.length)) invalid('插件必须声明至少一个贡献');
+  return freezePluginValue({ contractVersion: PLUGIN_CONTRACT_VERSION, id, version: value.version,
+    compatibility: { ...value.compatibility }, contributions });
+}
+
+export function definePlugin(value) {
+  if (!pluginFields(value, ['manifest', 'activate']) || typeof value.activate !== 'function') invalid('插件需要 manifest 与 activate');
+  return Object.freeze({ manifest: checkedPluginManifest(value.manifest), activate: value.activate });
+}
+export function assertPluginCompatibility(manifest, coreVersion) {
+  if (comparePluginVersions(coreVersion, manifest.compatibility.min) < 0 || comparePluginVersions(coreVersion, manifest.compatibility.maxExclusive) >= 0) {
+    pluginFail('IRIS_PLUGIN_INCOMPATIBLE', '插件 ' + manifest.id + ' 不支持当前 Core 版本');
+  }
+}
+export function checkedPluginDependency(value) {
+  if (!pluginFields(value, ['contractVersion', 'pluginId', 'pluginVersion', 'kind', 'contributionId', 'contributionVersion'])
+      || value.contractVersion !== PLUGIN_CONTRACT_VERSION || !PLUGIN_KINDS.includes(value.kind)) invalid('持久插件依赖无效');
+  checkedId(value.pluginId); checkedId(value.contributionId); versionParts(value.pluginVersion); versionParts(value.contributionVersion);
+  if (!value.contributionId.startsWith(value.pluginId + '.')) invalid('持久贡献不属于原插件');
+  return freezePluginValue({ contractVersion: PLUGIN_CONTRACT_VERSION, pluginId: value.pluginId, pluginVersion: value.pluginVersion,
+    kind: value.kind, contributionId: value.contributionId, contributionVersion: value.contributionVersion });
+}
+export function assertPluginDependencyMatches(expected, current) {
+  const original = expected === undefined ? undefined : checkedPluginDependency(expected);
+  const installed = current === undefined ? undefined : checkedPluginDependency(current);
+  if (JSON.stringify(original) !== JSON.stringify(installed)) pluginFail('IRIS_PLUGIN_DEPENDENCY_MISMATCH', '原任务依赖的插件或贡献版本不一致；请恢复准确版本，不会重新提交');
+}
+export function pluginDependency(manifest, kind, localId) {
+  const entry = manifest.contributions[kind]?.find(item => item.id === localId);
+  if (!entry) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', '插件未声明此贡献');
+  return checkedPluginDependency({ contractVersion: PLUGIN_CONTRACT_VERSION, pluginId: manifest.id, pluginVersion: manifest.version,
+    kind, contributionId: qualifiedPluginId(manifest.id, localId), contributionVersion: entry.version });
+}

package/lib/plugin-execution.js

@@ -0,0 +1,51 @@
+import { createCommandService } from './command-service.js';
+import crypto from 'node:crypto';
+import { readCoreArtifactBytes, inspectCoreArtifactMetadata, createCoreArtifact } from './core-artifacts.js';
+import { readImportImage } from './image-import.js';
+import { PLUGIN_CORE_COMMANDS, pluginFail } from './plugin-contract.js';
+import { isPluginSourceImage } from './plugin-source-image.js';
+
+/** One Core command boundary, shared by local Hosts and the durable runner. */
+export async function invokeReservedPlugin(runtime, reserved, { imports } = {}) {
+  const pending = new Set(); let accepting = true, commandTail = Promise.resolve();
+  const context = Object.freeze({ signal: runtime.signal, dependency: reserved.dependency,
+    core: Object.freeze({ execute(name, args) {
+      if (!accepting) return Promise.reject(Object.assign(new Error('插件调用已结束'), { name: 'AbortError' }));
+      const owned = structuredClone(args);
+      const call = commandTail.then(async () => {
+        runtime.signal.throwIfAborted();
+        imports?.authorize?.();
+        if (!reserved.commands.includes(name) || reserved.mode === 'reader' && PLUGIN_CORE_COMMANDS[name] !== 'reader') pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '插件未声明此 Core 命令或模式不允许写入');
+        if (name === 'artifact.read') return runtime.run('inspect', ({ dataRoot }) => {
+          if (!owned || Object.keys(owned).join(',') !== 'artifact_id') pluginFail('IRIS_PLUGIN_INPUT_INVALID', '作品读取只接受 Artifact ID');
+          if (imports && !imports.sources.includes(owned.artifact_id)) pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '持久业务只能读取其声明并绑定的来源作品');
+          const metadata = inspectCoreArtifactMetadata(dataRoot, owned.artifact_id);
+          if (!isPluginSourceImage(metadata)) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '插件图片读取支持 8 MiB 内 PNG/JPEG/WebP');
+          const result = readCoreArtifactBytes(dataRoot, owned.artifact_id);
+          return { contractVersion: 0, artifact: result.artifact, imageBase64: result.bytes.toString('base64') };
+        });
+        if (name === 'artifact.import') {
+          if (!owned || Object.keys(owned).join(',') !== 'image_bytes' || !(owned.image_bytes instanceof Uint8Array)) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '插件导入只接受图片字节，不接受主机路径');
+          if (imports) return runtime.run('execute', async ({ dataRoot, signal }) => {
+            const source = await readImportImage({ imageBytes: owned.image_bytes }, signal); signal.throwIfAborted(); imports.authorize?.();
+            const artifactId = imports.reserve();
+            const artifact = createCoreArtifact(dataRoot, { ...source, artifactId, expectedSize: source.bytes.length,
+              expectedDigest: crypto.createHash('sha256').update(source.bytes).digest('hex'), kind: 'plugin-image', metadata: { ...source.metadata, pluginOperationId: imports.operationId },
+              relations: imports.sources.map(id => ({ type: 'derived-from', artifactId: id })) });
+            return { contractVersion: 0, artifact };
+          });
+        }
+        return createCommandService(runtime).execute(name, owned);
+      });
+      commandTail = call; void call.catch(() => {}); pending.add(call); return call;
+    } }) });
+  runtime.signal.throwIfAborted(); let result, failure;
+  try { result = await reserved.invoke(context); } catch (error) { failure = error; }
+  accepting = false;
+  const results = await Promise.allSettled([...pending]);
+  if (failure) throw failure;
+  const rejected = results.find(item => item.status === 'rejected'); if (rejected) throw rejected.reason;
+  runtime.signal.throwIfAborted();
+  if (Buffer.byteLength(JSON.stringify(result.value)) > 128 * 1024) pluginFail('IRIS_PLUGIN_RESULT_INVALID', '插件业务结果超过 128 KiB');
+  return result;
+}

package/lib/plugin-launch.js

@@ -0,0 +1,86 @@
+// Explicit startup selection, separate from plugin installation and connection grants.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadCorePluginRegistry } from './plugins.js';
+import { createCoreCapabilityCatalog } from './core-capability-catalog.js';
+import { createPluginPanelAssembly } from './plugin-web-assets.js';
+import { pluginFields } from './plugin-contract.js';
+
+const builtins = new Map([['builtin:contact-sheet', fileURLToPath(new URL('../plugins/contact-sheet/index.mjs', import.meta.url))]]);
+export const builtinLaunchPlugins = () => [...builtins.keys()];
+
+function invalid(message, file, field) {
+  const error = Object.assign(new Error(message), { code: 'IRIS_PLUGIN_LAUNCH_INVALID' });
+  error.diagnostic = { code: error.code, stage: 'plugin-config', message, ...(file ? { file } : {}), ...(field ? { field } : {}) };
+  throw error;
+}
+function contextualize(error, file, stage) {
+  if (!(error instanceof Error)) error = new Error(String(error));
+  error.diagnostic ??= { code: error.code || 'IRIS_PLUGIN_LAUNCH_FAILED', stage, message: error.message, file };
+  return error;
+}
+
+export function readPluginLaunchConfiguration(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) invalid('plugin-config 必须是明确的 JSON 文件绝对路径', undefined, 'plugin-config');
+  let input, fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 65536) invalid('插件启动配置须为不超过 64 KiB 的普通 JSON 文件', file);
+    const buffer = Buffer.alloc(65537); let size = 0, count;
+    while (size < buffer.length && (count = fs.readSync(fd, buffer, size, buffer.length - size, null))) size += count;
+    if (size > 65536) invalid('插件启动配置超过 64 KiB', file);
+    try { input = JSON.parse(buffer.subarray(0, size).toString('utf8')); }
+    catch (_) { invalid('插件启动配置不是有效 JSON', file); }
+  } catch (error) { throw contextualize(error, file, 'plugin-config'); }
+  finally { if (fd !== undefined) fs.closeSync(fd); }
+  if (!pluginFields(input, ['schemaVersion', 'entries', 'operations', 'panel'], ['schemaVersion', 'entries']) || input.schemaVersion !== 0) {
+    invalid('插件启动配置须使用 schemaVersion:0，仅接受 entries、可选 operations/panel；不接受凭据或服务开关', file);
+  }
+  if (!Array.isArray(input.entries) || input.entries.some(entry => typeof entry !== 'string') || new Set(input.entries).size !== input.entries.length) {
+    invalid('entries 须为不重复的内置引用或 JS/MJS 绝对路径列表', file, 'entries');
+  }
+  const entries = input.entries.map((entry, index) => {
+    if (builtins.has(entry)) return builtins.get(entry);
+    if (!path.isAbsolute(entry) || !/\.m?js$/.test(entry)) invalid('入口须为已知 builtin: 引用或明确的 JS/MJS 绝对路径', file, 'entries[' + index + ']');
+    return entry;
+  });
+  if (input.operations !== undefined && (!Array.isArray(input.operations) || input.operations.some(id => typeof id !== 'string')
+      || new Set(input.operations).size !== input.operations.length)) invalid('operations 须为不重复的完整业务 ID 列表；空数组仅接管历史', file, 'operations');
+  // Reuse the same Panel validator as the server after the real registry is loaded.
+  if (input.panel !== undefined && !pluginFields(input.panel, ['pages', 'settings', 'renderers'], [])) invalid('panel 只接受 pages/settings/renderers 的明确列表', file, 'panel');
+  for (const [kind, values] of Object.entries(input.panel || {})) {
+    if (!Array.isArray(values) || values.some(id => typeof id !== 'string') || new Set(values).size !== values.length) {
+      invalid('panel 的每一项须为不重复的贡献 ID 列表', file, 'panel.' + kind);
+    }
+  }
+  return { entries, ...(input.operations !== undefined ? { operations: input.operations } : {}), ...(input.panel !== undefined ? { panel: input.panel } : {}) };
+}
+
+/** Imports/activate execute trusted code; inspect is not a sandbox or a media health test. */
+export async function loadPluginLaunch(file, { serveWorkbench = true, panelManifestPath } = {}) {
+  const config = readPluginLaunchConfiguration(file);
+  if (config.panel !== undefined && (!serveWorkbench || panelManifestPath !== undefined)) {
+    invalid('panel 组合仅用于默认 web 工作台；不能用于 api serve 或与 --panel 整套替换同时选择', file, 'panel');
+  }
+  let registry;
+  try {
+    // Resolve before importing anything, including duplicate aliases to the same file.
+    const entries = config.entries.map(entry => fs.realpathSync(entry));
+    if (new Set(entries).size !== entries.length) invalid('entries 不能重复引用同一实际文件', file, 'entries');
+    registry = await loadCorePluginRegistry({ entries });
+    const catalog = createCoreCapabilityCatalog({ registry });
+    if (config.operations !== undefined) catalog.selectOperations(config.operations);
+    if (config.panel !== undefined) createPluginPanelAssembly(registry, config.panel);
+    const facts = catalog.snapshot({ allowedOperations: config.operations ?? [], panelContributions: config.panel });
+    const summary = { contractVersion: 0, plugins: facts.plugins, contributions: facts.contributions,
+      pluginExecution: config.operations !== undefined,
+      selection: { operations: config.operations ?? null, panel: config.panel ?? null } };
+    return { registry, allowedOperations: config.operations, panelContributions: config.panel, summary, dispose: () => registry.dispose() };
+  } catch (error) {
+    try { await registry?.dispose(); }
+    catch (cleanup) { throw contextualize(Object.assign(new AggregateError([error, cleanup], '插件启动校验与释放均失败'), { code: 'IRIS_PLUGIN_LAUNCH_CLEANUP_FAILED' }), file, 'plugin-cleanup'); }
+    throw contextualize(error, file, 'plugin-load');
+  }
+}