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

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');
+  }
+}

package/lib/plugin-operation-store.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { requestDirectory } from './local-request-root.js';
+import { checkedPluginDependency, pluginFields, pluginJson, pluginFail, pluginObject } from './plugin-contract.js';
+import { inspectCoreArtifactMetadata, findCoreArtifactMetadata } from './core-artifacts.js';
+
+const ID = /^op_[a-f0-9]{64}$/, ARTIFACT = /^artifact_[a-f0-9]{24}$/, UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const STATES = ['queued', 'running', 'succeeded', 'failed', 'canceled', 'interrupted'];
+const CODES = ['dependency_unavailable', 'permission_denied', 'execution_failed'];
+const invalid = () => pluginFail('IRIS_OPERATION_STORE_INVALID', '持久插件 Operation 记录损坏或绑定不一致');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value !== null && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+export const pluginInputDigest = (id, input, dependency, sourceArtifactIds = []) => 'sha256:' + hash(JSON.stringify(canonical(['plugin.execute/v1', id, input, checkedPluginDependency(dependency), sourceArtifactIds])));
+const iso = value => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const ids = value => Array.isArray(value) && value.length <= 16 && new Set(value).size === value.length && value.every(id => typeof id === 'string' && ARTIFACT.test(id));
+const fileFor = (root, marker, id) => { if (!ID.test(id)) invalid(); return path.join(requestDirectory(root, marker, 'operations'), id + '.json'); };
+const save = (root, marker, record, create = false) => {
+  validatePluginOperation(record, record.id, marker);
+  (create ? atomicCreatePrivate : atomicWritePrivate)(fileFor(root, marker, record.id), JSON.stringify(record) + '\n');
+  return structuredClone(record);
+};
+const now = record => new Date(Math.max(Date.now(), Date.parse(record.updatedAt))).toISOString();
+
+export function validatePluginOperation(record, id, marker) {
+  if (!pluginFields(record, ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'operationId', 'dependency', 'input', 'inputDigest',
+    'sourceArtifactIds', 'reservedArtifactIds', 'ownerInstanceId', 'createdAt', 'updatedAt', 'state', 'cancelRequested', 'startedAt', 'finishedAt', 'result', 'failureCode'],
+  ['schemaVersion', 'id', 'rootId', 'revision', 'action', 'operationId', 'dependency', 'input', 'inputDigest', 'sourceArtifactIds', 'reservedArtifactIds',
+    'ownerInstanceId', 'createdAt', 'updatedAt', 'state', 'cancelRequested']) || record.schemaVersion !== 1 || record.action !== 'plugin.execute'
+      || !ID.test(id) || record.id !== id || record.rootId !== marker.rootId || !Number.isSafeInteger(record.revision) || record.revision < 1
+      || !UUID.test(record.ownerInstanceId) || !STATES.includes(record.state) || !iso(record.createdAt) || !iso(record.updatedAt) || record.updatedAt < record.createdAt
+      || record.cancelRequested !== (record.state === 'canceled') || !ids(record.sourceArtifactIds) || !ids(record.reservedArtifactIds)) invalid();
+  const dependency = checkedPluginDependency(record.dependency);
+  if (dependency.kind !== 'operations' || dependency.contributionId !== record.operationId
+      || !pluginObject(record.input) || record.inputDigest !== pluginInputDigest(record.operationId, record.input, dependency, record.sourceArtifactIds)
+      || Buffer.byteLength(JSON.stringify(record.input)) > 65536) invalid();
+  if (record.reservedArtifactIds.some((value, i) => value !== 'artifact_' + hash(JSON.stringify([record.id, i])).slice(0, 24))) invalid();
+  const active = ['queued', 'running'].includes(record.state), started = Object.hasOwn(record, 'startedAt');
+  if (record.state === 'queued' && (record.revision !== 1 || started || record.reservedArtifactIds.length || record.updatedAt !== record.createdAt)
+      || record.state === 'running' && !started || started && (!iso(record.startedAt) || record.startedAt < record.createdAt || record.startedAt > record.updatedAt)
+      || record.state === 'failed' && !CODES.includes(record.failureCode) || record.state !== 'failed' && Object.hasOwn(record, 'failureCode')) invalid();
+  if (active) { if (Object.hasOwn(record, 'finishedAt') || Object.hasOwn(record, 'result')) invalid(); }
+  else if (!iso(record.finishedAt) || record.finishedAt !== record.updatedAt || !pluginFields(record.result, ['value', 'artifactIds'])
+      || !ids(record.result.artifactIds) || record.result.artifactIds.some(value => !record.reservedArtifactIds.includes(value))
+      || record.state === 'succeeded' && (!started || record.result.artifactIds.length !== record.reservedArtifactIds.length)
+      || record.state !== 'succeeded' && record.result.value !== null
+      || Buffer.byteLength(JSON.stringify(record.result.value)) > 128 * 1024) invalid();
+  return record;
+}
+
+export function validatePluginBinding(root, record) {
+  for (const id of record.sourceArtifactIds) inspectCoreArtifactMetadata(root, id);
+  for (const id of record.result?.artifactIds || []) {
+    const artifact = inspectCoreArtifactMetadata(root, id);
+    if (artifact.kind !== 'plugin-image' || artifact.metadata.pluginOperationId !== record.id
+        || JSON.stringify(artifact.relations) !== JSON.stringify(record.sourceArtifactIds.map(artifactId => ({ type: 'derived-from', artifactId })))) invalid();
+  }
+}
+function read(root, marker, id) {
+  const file = fileFor(root, marker, id), stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) invalid();
+  let record; try { record = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { invalid(); }
+  return validatePluginOperation(record, id, marker);
+}
+export function pluginSourceArtifacts(input, fields) {
+  const result = [...new Set(fields.flatMap(key => input[key] === undefined ? [] : Array.isArray(input[key]) ? input[key] : [input[key]]))];
+  if (!ids(result)) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '业务来源须为最多 16 个有效 Artifact ID');
+  return result;
+}
+export function acceptPluginOperation(root, marker, id, { operationId, input, dependency, ownerInstanceId, sourceArtifactIds }) {
+  for (const artifactId of sourceArtifactIds) inspectCoreArtifactMetadata(root, artifactId);
+  const time = new Date().toISOString();
+  return save(root, marker, { schemaVersion: 1, id, rootId: marker.rootId, revision: 1, action: 'plugin.execute', operationId,
+    dependency: checkedPluginDependency(dependency), input: pluginJson(input), inputDigest: pluginInputDigest(operationId, input, dependency, sourceArtifactIds),
+    sourceArtifactIds, reservedArtifactIds: [], ownerInstanceId, createdAt: time, updatedAt: time, state: 'queued', cancelRequested: false }, true);
+}
+export function reservePluginArtifact(root, marker, id) {
+  const record = read(root, marker, id);
+  if (record.state !== 'running' || record.reservedArtifactIds.length >= 16) pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '当前业务不可导入更多作品');
+  const artifactId = 'artifact_' + hash(JSON.stringify([record.id, record.reservedArtifactIds.length])).slice(0, 24);
+  save(root, marker, { ...record, revision: record.revision + 1, updatedAt: now(record), reservedArtifactIds: [...record.reservedArtifactIds, artifactId] });
+  return artifactId;
+}
+export function transitionPluginOperation(root, marker, value) {
+  const record = read(root, marker, value.id);
+  if (record.revision !== value.expectedRevision) pluginFail('IRIS_OPERATION_REVISION_CONFLICT', 'Operation 已改变');
+  const allowed = record.state === 'queued' ? ['running', 'failed', 'canceled', 'interrupted'] : record.state === 'running' ? STATES.filter(state => !['queued', 'running'].includes(state)) : [];
+  if (!allowed.includes(value.state)) pluginFail('IRIS_OPERATION_TRANSITION_INVALID', '结束业务不重新排队或重放');
+  if (value.state === 'failed' ? !CODES.includes(value.failureCode) : value.failureCode !== undefined) pluginFail('IRIS_OPERATION_INPUT_INVALID', '业务失败类别无效');
+  const time = now(record), terminal = value.state !== 'running';
+  const artifacts = terminal ? record.reservedArtifactIds.filter(id => findCoreArtifactMetadata(root, id)) : [];
+  return save(root, marker, { ...record, revision: record.revision + 1, state: value.state, updatedAt: time, cancelRequested: value.state === 'canceled',
+    ...(terminal ? { finishedAt: time, result: { value: value.state === 'succeeded' ? pluginJson(value.value) : null, artifactIds: artifacts } } : { startedAt: time }),
+    ...(value.failureCode ? { failureCode: value.failureCode } : {}) });
+}
+export function projectPluginOperation(record) {
+  const { schemaVersion: _version, ownerInstanceId: _owner, reservedArtifactIds: _planned, ...value } = record;
+  return { contractVersion: 0, ...structuredClone(value) };
+}

package/lib/plugin-operations.js

@@ -0,0 +1,28 @@
+// Internal Core invocation boundary. No Provider implementations, Zod, module loading or filesystem.
+import { freezePluginValue, pluginJson, pluginFail } from './plugin-contract.js';
+
+const registries = new WeakMap();
+export function registerPluginOperations(registry, state) { registries.set(registry, state); }
+
+/** Reserve across the Core queue; the public registry never exposes an executable handler. */
+export function reservePluginOperation(registry, id, input, allowedOperations, expectedDependency) {
+  const owned = registries.get(registry);
+  if (!owned) pluginFail('IRIS_PLUGIN_INVALID', '需要当前插件注册实例');
+  owned.requireActive();
+  const operation = owned.operations.get(id);
+  if (!operation) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', '业务贡献未加载');
+  if (!Array.isArray(allowedOperations) || !allowedOperations.includes(id)) pluginFail('IRIS_PLUGIN_OPERATION_DENIED', '业务贡献未获本次 Core 装配授权');
+  const dependency = registry.dependency('operations', id);
+  if (expectedDependency !== undefined) {
+    registry.assertDependency(expectedDependency);
+    if (expectedDependency.kind !== 'operations' || expectedDependency.contributionId !== id) pluginFail('IRIS_PLUGIN_DEPENDENCY_MISMATCH', '不能用其他贡献的持久依赖执行当前业务');
+  }
+  const checked = operation.schema.safeParse(pluginJson(input));
+  if (!checked.success) pluginFail('IRIS_PLUGIN_INPUT_INVALID', '输入不符合 ' + id + ' 的 Schema');
+  let release;
+  const done = new Promise(resolve => { release = () => { owned.active.delete(done); resolve(); }; });
+  owned.active.add(done);
+  return { mode: operation.descriptor.mode, commands: operation.descriptor.commands, artifactInputs: operation.descriptor.artifactInputs || [],
+    input: freezePluginValue(checked.data), dependency, release,
+    async invoke(context) { return { dependency, value: pluginJson(await operation.handler(freezePluginValue(checked.data), context)) }; } };
+}

package/lib/plugin-registry.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { createProviderRegistry } from './provider-extensions.js';
+import { definePlugin, assertPluginCompatibility, checkedPluginDependency, pluginDependency, qualifiedPluginId,
+  pluginFields, pluginJson, pluginFail, comparePluginVersions, PLUGIN_KINDS } from './plugin-contract.js';
+import { registerPluginOperations } from './plugin-operations.js';
+
+const unavailable = () => pluginFail('IRIS_PLUGIN_CLOSED', '插件注册实例正在关闭或已关闭');
+
+/** Manifest validation precedes every activation. Core owns call reservations and cleanup. */
+export async function createPluginRegistry({ plugins, coreVersion }) {
+  if (!Array.isArray(plugins)) pluginFail('IRIS_PLUGIN_INVALID', 'plugins 须为明确的插件数组');
+  comparePluginVersions(coreVersion, coreVersion);
+  const definitions = plugins.map(definePlugin), entries = new Map(), contributionIds = new Set(), operations = new Map(), cleanups = [], active = new Set();
+  for (const definition of definitions) {
+    const { manifest } = definition; assertPluginCompatibility(manifest, coreVersion);
+    if (entries.has(manifest.id)) pluginFail('IRIS_PLUGIN_INVALID', '插件 ID 重复：' + manifest.id);
+    entries.set(manifest.id, definition);
+    for (const kind of PLUGIN_KINDS) for (const contribution of manifest.contributions[kind]) {
+      const key = kind + ':' + qualifiedPluginId(manifest.id, contribution.id);
+      if (contributionIds.has(key)) pluginFail('IRIS_PLUGIN_INVALID', '贡献完整 ID 重复：' + key);
+      contributionIds.add(key);
+    }
+    for (const operation of manifest.contributions.operations) {
+      let schema;
+      try { schema = z.fromJSONSchema(operation.inputSchema); }
+      catch (cause) { throw Object.assign(new Error('插件输入 Schema 无法编译：' + manifest.id + '.' + operation.id, { cause }), { code: 'IRIS_PLUGIN_INVALID' }); }
+      operations.set(qualifiedPluginId(manifest.id, operation.id), { manifest, descriptor: operation, schema });
+    }
+  }
+  let state = 'loading', providers, disposal, cleanupFailed = false;
+
+  function dispose() {
+    if (!disposal) {
+      state = 'closing';
+      const providerDisposal = providers?.dispose();
+      void providerDisposal?.catch(() => {}); // Awaited below after operation reservations drain.
+      disposal = (async () => {
+        await Promise.allSettled([...active]);
+        const errors = [];
+        try { await providerDisposal; } catch (error) { errors.push(error); }
+        for (const cleanup of [...cleanups].reverse()) {
+          try { await cleanup(); } catch (error) { errors.push(error); }
+        }
+        operations.clear(); state = 'closed'; cleanupFailed = errors.length > 0;
+        if (errors.length) throw new AggregateError(errors, '插件释放失败');
+      })();
+    }
+    return disposal;
+  }
+
+  try {
+    const factories = [];
+    for (const { manifest, activate } of definitions) {
+      let activating = true;
+      const context = Object.freeze({ coreVersion, plugin: Object.freeze({ id: manifest.id, version: manifest.version }),
+        onDispose(cleanup) {
+          if (!activating || typeof cleanup !== 'function') pluginFail('IRIS_PLUGIN_LIFECYCLE', '资源释放须在 activate 完成前注册');
+          cleanups.push(cleanup);
+        } });
+      let implementation;
+      try { implementation = await activate(context); } finally { activating = false; }
+      if (!pluginFields(implementation, ['providers', 'operations'], [])) pluginFail('IRIS_PLUGIN_INVALID', 'activate 须返回 Provider/业务实现映射；资源通过 onDispose 释放');
+      for (const kind of ['providers', 'operations']) {
+        const handlers = implementation[kind] === undefined ? {} : implementation[kind];
+        if (!pluginFields(handlers, manifest.contributions[kind].map(item => item.id))) pluginFail('IRIS_PLUGIN_INVALID', '实现必须与声明的 ' + kind + ' 一一对应');
+        if (kind === 'operations') for (const descriptor of manifest.contributions.operations) {
+          if (typeof handlers[descriptor.id] !== 'function') pluginFail('IRIS_PLUGIN_INVALID', '业务操作必须为函数');
+          operations.get(qualifiedPluginId(manifest.id, descriptor.id)).handler = handlers[descriptor.id];
+        }
+        else if (manifest.contributions.providers.length) factories.push(() => ({ contractVersion: 0, id: manifest.id, version: manifest.version,
+          protocols: manifest.contributions.providers.map(descriptor => {
+            const handler = handlers[descriptor.id];
+            if (!pluginFields(handler, ['normalizeEndpoint', 'createAdapter', 'supportsModel', 'supportsImageEdit'], ['normalizeEndpoint', 'createAdapter'])) {
+              pluginFail('IRIS_PLUGIN_INVALID', 'Provider 实现字段无效');
+            }
+            return { ...handler, id: qualifiedPluginId(manifest.id, descriptor.id), label: descriptor.title,
+              capabilities: descriptor.capabilities, configuration: descriptor.configuration,
+              dependency: pluginDependency(manifest, 'providers', descriptor.id) };
+          }) }));
+      }
+    }
+    providers = await createProviderRegistry({ extensions: factories });
+    state = 'active';
+  } catch (error) {
+    try { await dispose(); } catch (cleanup) { throw new AggregateError([error, cleanup], '插件激活与释放均失败'); }
+    throw error;
+  }
+
+  function dependency(kind, id) {
+    const manifest = definitions.map(item => item.manifest).find(item => item.contributions[kind]?.some(value => qualifiedPluginId(item.id, value.id) === id));
+    if (!manifest) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', '所需插件贡献未加载');
+    return pluginDependency(manifest, kind, manifest.contributions[kind].find(item => qualifiedPluginId(manifest.id, item.id) === id).id);
+  }
+  function assertDependency(value) {
+    const expected = checkedPluginDependency(value), current = dependency(expected.kind, expected.contributionId);
+    if (Object.keys(expected).some(key => expected[key] !== current[key])) pluginFail('IRIS_PLUGIN_DEPENDENCY_MISMATCH', '原任务依赖的插件或贡献版本不一致；请恢复准确版本，不会重新提交');
+    return current;
+  }
+  const registry = Object.freeze({
+    providers,
+    snapshot: () => ({ contractVersion: 0, coreVersion, state, activeCalls: active.size, cleanupFailed,
+      plugins: definitions.map(({ manifest }) => pluginJson(manifest)),
+      contributions: Object.fromEntries(PLUGIN_KINDS.map(kind => [kind, definitions.flatMap(({ manifest }) => manifest.contributions[kind]
+        .map(entry => ({ ...pluginJson(entry), id: qualifiedPluginId(manifest.id, entry.id), dependency: pluginJson(pluginDependency(manifest, kind, entry.id)) })))])) }),
+    dependency, assertDependency, dispose
+  });
+  registerPluginOperations(registry, { operations, active, requireActive: () => { if (state !== 'active') unavailable(); } });
+  return registry;
+}