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

package/lib/plugin-selection.js

@@ -0,0 +1,15 @@
+import { checkedPluginDependency, pluginFail } from './plugin-contract.js';
+
+/** Saved authority is an exact dependency list, never a live registry expansion. */
+export function checkedPluginSelection(value = []) {
+  if (!Array.isArray(value) || value.length > 16) pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务须为最多 16 项明确依赖');
+  let result;
+  try { result = value.map(checkedPluginDependency); }
+  catch (error) { if (error.code !== 'IRIS_PLUGIN_INVALID') throw error; pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务依赖格式无效'); }
+  if (result.some(item => item.kind !== 'operations') || new Set(result.map(item => item.contributionId)).size !== result.length) pluginFail('IRIS_CONNECTION_INPUT_INVALID', '插件业务依赖重复或类型无效');
+  return result;
+}
+export function hasPluginSelection(values, dependency) {
+  const pin = checkedPluginDependency(dependency);
+  return values.some(value => JSON.stringify(checkedPluginDependency(value)) === JSON.stringify(pin));
+}

package/lib/plugin-source-image.js

@@ -0,0 +1,5 @@
+// Shared source-image limits for the catalog and the plugin command boundary.
+const MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+export function isPluginSourceImage(artifact) {
+  return MEDIA_TYPES.has(artifact.mediaType) && artifact.size <= 8 * 1024 * 1024;
+}

package/lib/plugin-web-assets.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { freezePluginValue, pluginFail, pluginFields } from './plugin-contract.js';
+
+const WEB_KINDS = ['pages', 'settings', 'renderers'];
+const resources = new WeakMap();
+const invalid = message => pluginFail('IRIS_PLUGIN_WEB_INVALID', message);
+
+/** Only explicitly declared entry/styles. Never serve a plugin directory or evaluate browser JS. */
+export function pinPluginWebAssets(definition, file) {
+  const root = path.dirname(file), entries = new Map();
+  let total = 0;
+  for (const kind of WEB_KINDS) for (const item of definition.manifest.contributions[kind]) {
+    const assets = new Map();
+    for (const relative of [item.entry, ...(item.styles || [])]) {
+      const target = fs.realpathSync(path.join(root, relative)), rel = path.relative(root, target), stat = fs.statSync(target);
+      if (!rel || rel.startsWith('..' + path.sep) || path.isAbsolute(rel) || !stat.isFile()) {
+        pluginFail('IRIS_PLUGIN_INVALID', 'Web 入口必须位于插件目录内');
+      }
+      if (stat.size > 8 * 1024 * 1024 || (total += stat.size) > 16 * 1024 * 1024) invalid('插件 Web 资源超过 8 MiB 单文件 / 16 MiB 总量限制');
+      assets.set(relative, { bytes: fs.readFileSync(target), mediaType: relative.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8' });
+    }
+    entries.set(kind + ':' + definition.manifest.id + '.' + item.id, assets);
+  }
+  return entries;
+}
+
+export function registerPluginWebAssets(registry, entries) { resources.set(registry, entries); }
+
+/** A Core service opts in to exact contribution IDs. Installing a plugin never opts in. */
+export function createPluginPanelAssembly(registry, selection = {}) {
+  if (!pluginFields(selection, WEB_KINDS, [])) invalid('Panel 组合选择须为 pages/settings/renderers 的明确 ID 列表');
+  const source = registry?.snapshot(), pinned = resources.get(registry), routes = new Map(), manifest = { contractVersion: 0 }, selected = {};
+  if (source && source.state !== 'active') pluginFail('IRIS_PLUGIN_CLOSED', '插件注册实例正在关闭或已关闭');
+  for (const kind of WEB_KINDS) {
+    const ids = selection[kind] ?? [];
+    if (!Array.isArray(ids) || ids.some(id => typeof id !== 'string') || new Set(ids).size !== ids.length) invalid('Panel 选择须为不重复的完整贡献 ID');
+    selected[kind] = [...ids];
+    manifest[kind] = ids.map(id => {
+      const item = source?.contributions[kind].find(value => value.id === id);
+      if (!item) pluginFail('IRIS_PLUGIN_CONTRIBUTION_MISSING', 'Panel 贡献未加载：' + kind + ':' + id);
+      const assets = pinned?.get(kind + ':' + id);
+      if (!assets) pluginFail('IRIS_PLUGIN_WEB_ASSET_MISSING', 'Panel 贡献须经显式文件入口加载并固定资源：' + id);
+      const base = '/plugin-assets/' + item.dependency.pluginId + '/' + item.dependency.pluginVersion + '/' + kind + '/' + id + '/';
+      for (const [name, asset] of assets) routes.set(base + name, asset);
+      return { id, title: item.title, dependency: item.dependency, entry: base + item.entry,
+        styles: (item.styles || []).map(name => base + name), ...(kind === 'renderers' ? { mediaTypes: item.mediaTypes } : {}) };
+    });
+  }
+  const active = () => !registry || registry.snapshot().state === 'active';
+  freezePluginValue(manifest); freezePluginValue(selected);
+  return Object.freeze({ selection: selected, manifest,
+    has: route => active() && routes.has(route), read: async route => active() ? routes.get(route) || null : null });
+}

package/lib/plugins.d.ts

@@ -0,0 +1,288 @@
+/** Experimental v0. Trusted local code; no sandbox, discovery, installation or implicit grant. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+export type PluginKind = 'providers' | 'operations' | 'pages' | 'renderers' | 'settings';
+export const PLUGIN_CONTRACT_VERSION: 0;
+export const PLUGIN_KINDS: readonly PluginKind[];
+export type PluginCoreCommand = 'artifact.inspect' | 'artifact.read' | 'artifact.list' | 'task.inspect' | 'task.list' | 'artifact.import';
+export const PLUGIN_CORE_COMMANDS: Readonly<Record<PluginCoreCommand, 'reader' | 'writer'>>;
+export class PluginContractError extends Error { constructor(code: string, message: string); readonly code: string; }
+export interface PluginDependency {
+  readonly contractVersion: 0;
+  readonly pluginId: string;
+  readonly pluginVersion: string;
+  readonly kind: PluginKind;
+  /** Fully qualified pluginId.localId. */
+  readonly contributionId: string;
+  readonly contributionVersion: string;
+}
+export interface Contribution { readonly id: string; readonly version: string; readonly title: string; }
+export interface ProviderContribution extends Contribution {
+  readonly capabilities: readonly ('image-gen' | 'video-gen' | 'tts' | 'music-gen' | 'transcribe')[];
+  readonly configuration?: readonly { key: 'baseUrl' | 'mediaBaseUrl' | 'apiKey'; label: string; type: 'url' | 'secret'; required?: boolean; advanced?: boolean }[];
+}
+export interface OperationContribution extends Contribution {
+  readonly mode: 'reader' | 'writer';
+  readonly commands: readonly PluginCoreCommand[];
+  /** Top-level string or string-array input fields containing source Artifact IDs. Bound at acceptance. */
+  readonly artifactInputs?: readonly string[];
+  /** Closed root object; supported JSON Schema subset documented in PLUGINS.md. */
+  readonly inputSchema: { readonly type: 'object'; readonly additionalProperties: false; readonly [key: string]: JsonValue };
+}
+export interface PageContribution extends Contribution {
+  /** Plugin-relative bundled JS/MJS module. Explicit entry loader pins it before Panel selection. */
+  readonly entry: string;
+  readonly styles?: readonly string[];
+}
+export interface RendererContribution extends PageContribution { readonly mediaTypes: readonly string[]; }
+export interface SettingsContribution extends PageContribution {}
+export interface PluginPanelSelection {
+  readonly pages?: readonly string[];
+  readonly settings?: readonly string[];
+  readonly renderers?: readonly string[];
+}
+export interface PluginManifest {
+  readonly contractVersion: 0;
+  readonly id: string;
+  readonly version: string;
+  /** SemVer precedence interval, min inclusive/maxExclusive exclusive. Not npm range syntax. */
+  readonly compatibility: { readonly min: string; readonly maxExclusive: string };
+  readonly contributions: {
+    readonly providers?: readonly ProviderContribution[];
+    readonly operations?: readonly OperationContribution[];
+    readonly pages?: readonly PageContribution[];
+    readonly renderers?: readonly RendererContribution[];
+    readonly settings?: readonly SettingsContribution[];
+  };
+}
+export interface PluginOperationContext {
+  readonly signal: AbortSignal;
+  readonly dependency: PluginDependency;
+  readonly core: { execute(command: PluginCoreCommand, input: Record<string, unknown>): Promise<unknown> };
+}
+export type PluginOperation = (input: Readonly<Record<string, JsonValue>>, context: PluginOperationContext) => JsonValue | Promise<JsonValue>;
+export type ProviderCapability = 'image' | 'video' | 'tts' | 'music' | 'transcribe';
+export type ProviderMethod = 'discover' | 'submit' | 'poll' | 'cancel' | 'download' | 'mapError';
+export interface ProviderAdapterInput {
+  id: string; protocol: string; capabilities: ProviderCapability[]; contractVersion?: 0;
+  operations: Partial<Record<ProviderMethod, (...args: any[]) => unknown>>;
+  unsupported?: Partial<Record<ProviderMethod, string>>;
+  prepareInput?: (...args: any[]) => unknown;
+  unsupportedPreparation?: string;
+  pluginDependency?: PluginDependency;
+}
+export type ProviderAdapter = Readonly<Omit<ProviderAdapterInput, 'contractVersion' | 'capabilities' | 'operations' | 'unsupported'> & {
+  contractVersion: 0;
+  capabilities: readonly ProviderCapability[];
+  operations: Readonly<Partial<Record<ProviderMethod, (...args: any[]) => unknown>>>;
+  unsupported: Readonly<Partial<Record<ProviderMethod, { readonly reason: string }>>>;
+}>;
+export function defineProviderAdapter(input: ProviderAdapterInput): ProviderAdapter;
+export function normalizeMediaEndpoint(value: string): string;
+export interface ProviderImplementation {
+  normalizeEndpoint(value: string): string;
+  createAdapter(provider: Record<string, any>, options?: Record<string, any>): ProviderAdapter;
+  supportsModel?(input: { provider: Record<string, unknown>; modelId: string; capability: string; checkEndpoint?: boolean }): boolean;
+  supportsImageEdit?(modelId: string): boolean;
+}
+export interface PluginActivationContext {
+  readonly coreVersion: string;
+  readonly plugin: { readonly id: string; readonly version: string };
+  /** Register during activate, including before awaited initialization; reverse order cleanup. */
+  onDispose(cleanup: () => void | Promise<void>): void;
+}
+export interface PluginImplementation {
+  readonly providers?: Readonly<Record<string, ProviderImplementation>>;
+  readonly operations?: Readonly<Record<string, PluginOperation>>;
+}
+export interface CorePlugin {
+  readonly manifest: PluginManifest;
+  activate(context: PluginActivationContext): PluginImplementation | Promise<PluginImplementation>;
+}
+export function definePlugin(definition: CorePlugin): CorePlugin;
+export interface ProviderRegistry {
+  descriptor(id: string): Readonly<Record<string, any>> | undefined;
+  snapshot(): { state: string; protocols: Record<string, any>[]; extensions: { id: string; version: string }[]; activeCalls: number; cleanupFailed: boolean; contractVersion: 0 };
+  createAdapter(id: string, provider: Record<string, any>, options?: Record<string, any>): ProviderAdapter;
+  dispose(): Promise<void>;
+}
+export interface CorePluginRegistry {
+  readonly providers: ProviderRegistry;
+  snapshot(): {
+    contractVersion: 0; coreVersion: string; state: string; activeCalls: number; cleanupFailed: boolean;
+    plugins: PluginManifest[];
+    contributions: {
+      providers: (ProviderContribution & { dependency: PluginDependency })[];
+      operations: (OperationContribution & { dependency: PluginDependency })[];
+      pages: (PageContribution & { dependency: PluginDependency })[];
+      renderers: (RendererContribution & { dependency: PluginDependency })[];
+      settings: (SettingsContribution & { dependency: PluginDependency })[];
+    };
+  };
+  dependency(kind: PluginKind, qualifiedId: string): PluginDependency;
+  assertDependency(dependency: PluginDependency): PluginDependency;
+  dispose(): Promise<void>;
+}
+export function createCorePluginRegistry(options?: { plugins?: CorePlugin[]; coreVersion?: string }): Promise<CorePluginRegistry>;
+export function loadCorePluginRegistry(options?: { entries?: string[]; coreVersion?: string }): Promise<CorePluginRegistry>;
+export type CoreCapabilityScope = 'read' | 'create' | 'execute' | 'stop';
+export type CoreBridgeCapability = 'image-edit' | 'image-generate' | 'tts' | 'transcribe';
+export interface ContributionAccess {
+  readonly local: 'requires-configuration' | 'requires-grant' | 'descriptor-only' | 'unavailable';
+  readonly web: 'via-media-flow' | 'via-operation' | 'not-exposed' | 'durable-operation-required' | 'not-mounted' | 'available-in-panel' | 'unavailable';
+  readonly mcp: 'via-media-flow' | 'requires-selection' | 'not-exposed' | 'durable-operation-required' | 'not-applicable' | 'unavailable';
+}
+export interface CatalogContribution extends Contribution {
+  readonly dependency: PluginDependency;
+  /** Declaration/assembly facts only; never the caller's authorization or service health. */
+  readonly access: ContributionAccess;
+}
+export interface CoreCapabilitySnapshot {
+  readonly contractVersion: 0;
+  readonly state: string;
+  readonly coreVersion?: string;
+  readonly scopeOptions: readonly { readonly id: CoreCapabilityScope; readonly title: string }[];
+  readonly controlTools: readonly string[];
+  readonly groups: readonly {
+    readonly id: CoreBridgeCapability; readonly recipe: string; readonly title: string; readonly label: string; readonly shortTitle: string;
+    readonly media: string; readonly requiresAudio?: boolean; readonly tools: readonly string[];
+  }[];
+  readonly tools: readonly { readonly name: string; readonly scope: CoreCapabilityScope; readonly description: string }[];
+  readonly pluginTools: CoreCapabilitySnapshot['tools'];
+  readonly pluginControlTools: readonly string[];
+  readonly media: readonly { readonly id: string; readonly title: string; readonly note?: string; readonly capabilities: readonly CoreBridgeCapability[] }[];
+  readonly plugins: readonly { readonly id: string; readonly version: string; readonly compatibility: PluginManifest['compatibility'] }[];
+  readonly contributions: {
+    readonly providers: readonly (ProviderContribution & CatalogContribution)[];
+    readonly operations: readonly (OperationContribution & CatalogContribution)[];
+    /** No browser module path is exposed or mounted by discovery. */
+    readonly pages: readonly CatalogContribution[];
+    readonly renderers: readonly (CatalogContribution & { readonly mediaTypes: readonly string[] })[];
+    readonly settings: readonly CatalogContribution[];
+  };
+}
+export interface CoreCapabilityCatalog {
+  snapshot(options?: { audioEnabled?: boolean; panelContributions?: PluginPanelSelection; allowedOperations?: readonly string[] }): CoreCapabilitySnapshot;
+  /** Validate an explicit local selection. Does not invoke, persist a grant or enable MCP/Web. */
+  selectOperations(ids?: readonly string[]): readonly (OperationContribution & CatalogContribution)[];
+}
+export function createCoreCapabilityCatalog(options?: { registry?: CorePluginRegistry }): CoreCapabilityCatalog;
+export interface CorePluginHost {
+  call(id: string, input: Record<string, JsonValue>, options?: { dependency?: PluginDependency; signal?: AbortSignal }): Promise<{ dependency: PluginDependency; value: JsonValue }>;
+  snapshot(): { state: string; queuedWrites: number; activeWrites: number; activeReaders: number; cleanupFailed: boolean };
+  /** Caller disposes the shared registry after every host has closed. */
+  dispose(): Promise<ReturnType<CorePluginHost['snapshot']>>;
+}
+export function createCorePluginHost(options: { dataRoot: string; registry: CorePluginRegistry; allowedOperations?: string[] }): CorePluginHost;
+export interface CorePluginWorkbenchSnapshot {
+  readonly contractVersion: 0;
+  readonly state: string;
+  readonly origin: string | null;
+  /** Media writes remain disabled; optional Provider editing has a separate owner gate. */
+  readonly readOnly: true;
+  readonly activeReads: number;
+  readonly cleanupFailed?: boolean;
+}
+export interface CorePluginWorkbench {
+  start(options?: { port?: number }): Promise<{ readonly origin: string; readonly accessToken: string; readonly loginUrl: string; readonly loginExpiresAt: string }>;
+  snapshot(): CorePluginWorkbenchSnapshot;
+  readonly closed: Promise<CorePluginWorkbenchSnapshot>;
+  dispose(): Promise<CorePluginWorkbenchSnapshot>;
+}
+export interface CorePasswordPluginWorkbench extends Omit<CorePluginWorkbench, 'start'> {
+  start(options?: { port?: number }): Promise<{ readonly origin: string; readonly accessToken: string; readonly loginUrl: string;
+    readonly authentication: { readonly mode: 'password'; readonly configured: boolean; readonly authId: string;
+      readonly rememberDays: 30; readonly minPasswordLength: 8; readonly maxPasswordLength: 128 } }>;
+}
+export interface CorePluginWorkbenchOptions {
+  dataRoot: string; registry?: CorePluginRegistry; panelContributions?: PluginPanelSelection;
+  panelManifestPath?: string; providerConfigPath?: string; allowProviderManagement?: boolean;
+  /** Omitted: no business runner. []: reconcile/read history only. IDs: explicitly enabled durable businesses. */
+  allowedOperations?: string[];
+  /** Explicit private directory outside dataRoot. Enables owner connection management. */
+  connectionStore?: string;
+  /** Enable the standard HTTP /mcp edge. Does not start a second Core. */
+  allowMcp?: boolean;
+  /** Optional persistent browser password/session store, in a private directory outside dataRoot. */
+  workbenchAuth?: { directory: string };
+}
+export function createCorePluginWorkbench(options: CorePluginWorkbenchOptions & { workbenchAuth: { directory: string } }): CorePasswordPluginWorkbench;
+export function createCorePluginWorkbench(options: Omit<CorePluginWorkbenchOptions, 'workbenchAuth'> & { workbenchAuth?: undefined }): CorePluginWorkbench;
+export function createCorePluginWorkbench(options: CorePluginWorkbenchOptions): CorePluginWorkbench | CorePasswordPluginWorkbench;
+export function checkedPluginDependency(value: unknown): PluginDependency;
+export function comparePluginVersions(a: string, b: string): -1 | 0 | 1;
+
+export interface PluginTheme { readonly mode: 'light' | 'dark'; readonly density: string; readonly accent: 'iris'; }
+export interface PluginWebSession {
+  readonly contractVersion: 0;
+  readonly instanceId: string;
+  readonly rootId?: string | null;
+  readonly operations: readonly string[];
+  readonly readOnly: boolean;
+  readonly audio: boolean;
+  readonly providerManagement: boolean;
+  readonly pluginExecution: boolean;
+  readonly pluginOperations: readonly PluginDependency[];
+}
+export interface PluginArtifact { readonly id: string; readonly mediaType: string; readonly label?: string; }
+export interface PluginWebRequestOptions { readonly signal?: AbortSignal; }
+export interface PluginBusinessRequest {
+  readonly key: string;
+  readonly operationId: string;
+  readonly dependency: PluginDependency;
+  readonly input: Readonly<Record<string, JsonValue>>;
+}
+export interface PluginDurableOperation {
+  readonly contractVersion: 0;
+  readonly id: string;
+  readonly rootId: string;
+  readonly action: 'plugin.execute';
+  readonly operationId: string;
+  readonly dependency: PluginDependency;
+  readonly input: Readonly<Record<string, JsonValue>>;
+  readonly inputDigest: string;
+  readonly sourceArtifactIds: readonly string[];
+  readonly revision: number;
+  readonly state: 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'interrupted';
+  readonly cancelRequested: boolean;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly failureCode?: 'dependency_unavailable' | 'permission_denied' | 'execution_failed';
+  readonly result?: { readonly value: JsonValue; readonly artifactIds: readonly string[] };
+}
+export interface PluginWebApi {
+  runs(query?: Readonly<Record<string, string>>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  run(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  models(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  audioModels(options?: PluginWebRequestOptions): Promise<JsonValue>;
+  artifact(artifact: PluginArtifact, options?: PluginWebRequestOptions): Promise<Blob>;
+  /** Only settings mounts in an explicitly enabled owner Provider-management session. */
+  readonly providers?: {
+    read(options?: PluginWebRequestOptions): Promise<JsonValue>;
+    save(input: Record<string, JsonValue>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  };
+  /** Present only when the service explicitly owns a durable plugin runner. Core checks each request. */
+  readonly pluginOperations?: {
+    catalog(query?: Readonly<Record<string, string>>, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    history(options?: PluginWebRequestOptions): Promise<JsonValue>;
+    execute(input: PluginBusinessRequest, options?: PluginWebRequestOptions): Promise<{ contractVersion: 0; operation: PluginDurableOperation; idempotentReplay: boolean }>;
+    inspect(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    lookup(key: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+    stop(id: string, options?: PluginWebRequestOptions): Promise<JsonValue>;
+  };
+}
+/** Same-origin trusted modules; Shadow DOM is a style boundary, not a security sandbox. */
+export interface PluginWebContext<Container = unknown> {
+  readonly container: Container;
+  readonly signal: AbortSignal;
+  readonly dependency: PluginDependency;
+  readonly session: PluginWebSession;
+  readonly api: PluginWebApi;
+  readonly theme: { current(): PluginTheme; subscribe(listener: (theme: PluginTheme) => void): () => void };
+}
+export interface PluginPageModule<Container = unknown> { mount(context: PluginWebContext<Container>): void | (() => void) | Promise<void | (() => void)>; }
+export interface PluginSettingsModule<Container = unknown> extends PluginPageModule<Container> {}
+export interface PluginRendererModule<Container = unknown> {
+  mount(context: PluginWebContext<Container> & { readonly artifact: PluginArtifact }): void | (() => void) | Promise<void | (() => void)>;
+}

package/lib/plugins.js

@@ -0,0 +1,58 @@
+// Experimental v0 public plugin author/embedding boundary. No automatic discovery or installation.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createPluginRegistry } from './plugin-registry.js';
+import { createApplicationRuntime } from './application-runtime.js';
+import { definePlugin, pluginFail, pluginFields } from './plugin-contract.js';
+import { createCoreCapabilityCatalog } from './core-capability-catalog.js';
+import { pinPluginWebAssets, registerPluginWebAssets } from './plugin-web-assets.js';
+import { createLocalReadApi } from './local-api.js';
+
+export { createCoreCapabilityCatalog } from './core-capability-catalog.js';
+
+export { definePlugin, PluginContractError, PLUGIN_CONTRACT_VERSION, PLUGIN_KINDS, PLUGIN_CORE_COMMANDS,
+  checkedPluginDependency, comparePluginVersions } from './plugin-contract.js';
+export { defineProviderAdapter, normalizeMediaEndpoint } from './provider-extensions.js';
+
+export function createCorePluginRegistry({ plugins = [], coreVersion } = {}) {
+  coreVersion ??= JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  return createPluginRegistry({ plugins, coreVersion });
+}
+
+/** Importing a module executes trusted code. Compatibility gates activate, not module evaluation. */
+export async function loadCorePluginRegistry({ entries = [], coreVersion } = {}) {
+  if (!Array.isArray(entries)) pluginFail('IRIS_PLUGIN_INVALID', '入口须为明确文件列表');
+  const plugins = [], assets = new Map();
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || !path.isAbsolute(entry) || !/\.m?js$/.test(entry) || !fs.statSync(entry).isFile()) pluginFail('IRIS_PLUGIN_INVALID', '插件入口须为 JS/MJS 文件绝对路径');
+    const file = fs.realpathSync(entry), definition = definePlugin((await import(pathToFileURL(file).href)).default);
+    for (const [id, files] of pinPluginWebAssets(definition, file)) assets.set(id, files);
+    plugins.push(definition);
+  }
+  const registry = await createCorePluginRegistry({ plugins, coreVersion });
+  registerPluginWebAssets(registry, assets);
+  return registry;
+}
+
+/** Trusted Core assembly. Grants are captured once; individual calls cannot enlarge them. */
+export function createCorePluginHost({ dataRoot, registry, allowedOperations = [] } = {}) {
+  const selection = createCoreCapabilityCatalog({ registry }).selectOperations(allowedOperations);
+  const grants = Object.freeze(selection.map(item => item.id)), application = createApplicationRuntime({ dataRoot });
+  return Object.freeze({
+    call: (id, input, { dependency, signal } = {}) => application.executePluginOperation(registry, id, input,
+      { allowedOperations: grants, dependency, signal }),
+    snapshot: () => application.snapshot(),
+    dispose: () => application.dispose()
+  });
+}
+
+/** Public, bounded Panel assembly. Media remains read-only; Provider editing is an explicit owner gate. */
+export function createCorePluginWorkbench(options) {
+  if (!pluginFields(options, ['dataRoot', 'registry', 'panelContributions', 'panelManifestPath', 'providerConfigPath', 'allowProviderManagement', 'allowedOperations', 'connectionStore', 'allowMcp', 'workbenchAuth'], ['dataRoot'])) {
+    pluginFail('IRIS_PLUGIN_WEB_INVALID', '工作台只接受明确的数据根、注册器、Panel 选择及供应商管理设置');
+  }
+  const { dataRoot, registry: pluginRegistry, panelContributions, panelManifestPath, providerConfigPath, allowProviderManagement = false, allowedOperations, connectionStore, allowMcp = false, workbenchAuth } = options;
+  return createLocalReadApi({ dataRoot, serveWorkbench: true, pluginRegistry, panelContributions, panelManifestPath, providerConfigPath, allowProviderManagement,
+    allowedOperations, connectionStore, allowConnectionManagement: connectionStore !== undefined, allowMcp, workbenchAuth });
+}

package/lib/private-storage.js

@@ -51,6 +51,18 @@ export function atomicWritePrivate(file, data) {
   }
 }
 
+/** 原子且排他地发布新记录；已存在的身份绝不被 rename 覆盖。 */
+export function atomicCreatePrivate(file, data) {
+  ensurePrivateDir(path.dirname(file));
+  const tmp = privateSibling(file);
+  try {
+    fs.writeFileSync(tmp, data, { mode: 0o600, flag: 'wx' });
+    fs.linkSync(tmp, file);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* 仅本次未发布的临时链接 */ }
+  }
+}
+
 /** 收紧既有 Iris 树；不跟随符号链接，也不修改文件内容。 */
 export function hardenPrivateTree(root) {
   ensurePrivateDir(root);

package/lib/provider-adapter.js

@@ -13,6 +13,7 @@ import {
   providerErrorRecord,
   resultFromThrown
 } from './provider-contract.js';
+import { checkedPluginDependency } from './plugin-contract.js';
 
 export const PROVIDER_ADAPTER_CONTRACT_VERSION = 0;
 
@@ -72,7 +73,7 @@ export function defineProviderAdapter(input) {
   if (!isPlainObject(input)) throw new TypeError('Provider Adapter 必须是对象');
   const allowed = new Set([
     'contractVersion', 'id', 'protocol', 'capabilities', 'operations', 'unsupported',
-    'prepareInput', 'unsupportedPreparation'
+    'prepareInput', 'unsupportedPreparation', 'pluginDependency'
   ]);
   for (const key of Object.keys(input)) {
     if (!allowed.has(key)) throw new Error('Provider Adapter 不允许顶层字段：' + key);
@@ -129,6 +130,8 @@ export function defineProviderAdapter(input) {
   }
   const unsupportedPreparation = input.prepareInput ? undefined
     : normalizedReason(input.unsupportedPreparation, '协议未实现临时输入上传');
+  const pluginDependency = input.pluginDependency === undefined ? undefined : checkedPluginDependency(input.pluginDependency);
+  if (pluginDependency && (pluginDependency.kind !== 'providers' || pluginDependency.contributionId !== protocol)) throw new TypeError('Provider Adapter 的插件依赖与协议不一致');
 
   return Object.freeze({
     contractVersion,
@@ -137,6 +140,7 @@ export function defineProviderAdapter(input) {
     capabilities: Object.freeze(capabilities),
     operations: Object.freeze(operations),
     unsupported: Object.freeze(unsupported),
+    ...(pluginDependency ? { pluginDependency } : {}),
     prepareInput: input.prepareInput,
     unsupportedPreparation
   });

package/lib/provider-adapters.js

@@ -10,10 +10,12 @@ import * as defaultTransport from './adapters.js';
 import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
 import { writePrivateFile } from './private-storage.js';
 import { defineProviderAdapter } from './provider-adapter.js';
-import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError, supportsImageEdit, dashscopeTtsInputIssue } from './provider-protocol.js';
+import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError, supportsImageEdit, dashscopeTtsInputIssue, BUILTIN_PROVIDER_PROTOCOLS } from './provider-protocol.js';
 import { modelRateLimit, reportModelRateLimit, isFreeQuotaExhausted, recordModelAvailability } from './provider-health.js';
 import { modelUnavailable, modelUnavailableReason, modelAvailabilityBinding } from './model-directory.js';
 import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
+import { createComfyUiProviderAdapter } from './comfyui-adapter.js';
+import { PROVIDER_RESPONSE_LIMITS } from './provider-response.js';
 
 const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
 
@@ -26,7 +28,7 @@ function providerIdentity(provider) {
   return { id, key, baseUrl };
 }
 
-function mappedCategory(error, status) {
+function mappedCategory(error, status, stage) {
   const raw = String(error?.category || '').toLowerCase();
   if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
   if (error?.name === 'TimeoutError' || raw === 'timeout'
@@ -37,7 +39,10 @@ function mappedCategory(error, status) {
   if (status === 429 || raw === 'rate_limit') return 'rate_limit';
   if (raw === 'invalid_parameter' || raw === 'invalid_request') return 'invalid_request';
   if (raw === 'protocol') return 'protocol';
+  if (raw === 'local_io') return 'local_io';
   if (raw === 'network' || error instanceof TypeError) return 'network';
+  if (!status && ['download', 'persist'].includes(stage)
+      && ['ENOSPC', 'EDQUOT', 'EACCES', 'EPERM', 'ENOENT', 'EEXIST', 'EROFS', 'EIO'].includes(error?.code)) return 'local_io';
   if (raw === 'server' || status >= 500) return 'provider';
   if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
   return 'provider';
@@ -50,7 +55,7 @@ export function mapProviderAdapterError(error, context = {}) {
     ? statusValue
     : undefined;
   const stage = String(context.stage || error?.stage || 'submit');
-  const category = mappedCategory(error, httpStatus);
+  const category = mappedCategory(error, httpStatus, stage);
   let acceptance = context.acceptance || error?.acceptance;
   if (stage === 'validate' || stage === 'prepare' || stage === 'upload') {
     acceptance = 'not_accepted';
@@ -117,8 +122,16 @@ function openAiImageArtifacts(items) {
 }
 
 function writeInlineArtifact(artifact, targetPath) {
+  const maxBytes = String(artifact.mediaType || '').startsWith('image/') ? PROVIDER_RESPONSE_LIMITS.image
+    : artifact.mediaType === 'text/plain' ? PROVIDER_RESPONSE_LIMITS.transcript : PROVIDER_RESPONSE_LIMITS.audio;
+  if (typeof artifact.data === 'string' && artifact.data.length > Math.ceil(maxBytes / 3) * 4) {
+    throw new ProviderContractError('内嵌媒体超过允许的大小', { stage: 'download', category: 'protocol', acceptance: 'accepted' });
+  }
   const data = String(artifact?.data || '').trim();
   const body = Buffer.from(data, 'base64');
+  if (body.length > maxBytes) {
+    throw new ProviderContractError('内嵌媒体超过允许的大小', { stage: 'download', category: 'protocol', acceptance: 'accepted' });
+  }
   if (!data || body.length === 0 || body.toString('base64') !== data) {
     throw new ProviderContractError('inline-base64 媒体数据无效', {
       stage: 'download', category: 'protocol', acceptance: 'accepted'
@@ -262,6 +275,8 @@ function operationsForDashScope(provider, transport) {
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
+          maxBytes: { image: PROVIDER_RESPONSE_LIMITS.image, video: PROVIDER_RESPONSE_LIMITS.video,
+            tts: PROVIDER_RESPONSE_LIMITS.audio, transcribe: PROVIDER_RESPONSE_LIMITS.transcript }[request.capability] || PROVIDER_RESPONSE_LIMITS.video,
           ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
         })
       };
@@ -278,8 +293,8 @@ export function createDashScopeProviderAdapter(provider, { transport = defaultTr
     protocol: 'dashscope',
     capabilities: ['image', 'video', 'tts', 'transcribe'],
     operations: operationsForDashScope(provider, transport),
-    async prepareInput({ model, filePath, signal, timeoutMs } = {}) {
-      return { url: await transport.uploadTempFile({ key, baseUrl, model, filePath, signal, timeoutMs }) };
+    async prepareInput({ model, filePath, bytes, filename, signal, timeoutMs } = {}) {
+      return { url: await transport.uploadTempFile({ key, baseUrl, model, filePath, ...(bytes !== undefined ? { bytes, filename } : {}), signal, timeoutMs }) };
     },
     unsupported: {
       cancel: '当前 DashScope 媒体协议未提供经过验证的远端取消实现'
@@ -345,6 +360,7 @@ function operationsForOpenAiImages(provider, transport, protocol = 'openai-image
       return {
         bytes: await transport.downloadTo(artifact.url, targetPath, {
           signal: request.signal,
+          maxBytes: PROVIDER_RESPONSE_LIMITS.image,
           ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
         })
       };
@@ -418,22 +434,44 @@ export function createGeminiWebMusicProviderAdapter(provider, { transport = defa
   });
 }
 
-const PROTOCOL_FACTORIES = new Map([
-  ['gemini-web-music', createGeminiWebMusicProviderAdapter],
-  ['dashscope', createDashScopeProviderAdapter],
-  ['openai-images', createOpenAiImagesProviderAdapter],
-  ['openai-chat-images', createOpenAiChatImagesProviderAdapter],
-  ['openai-responses-images', createOpenAiResponsesImagesProviderAdapter]
-]);
+const PROTOCOL_FACTORIES = Object.freeze({
+  'gemini-web-music': createGeminiWebMusicProviderAdapter,
+  dashscope: createDashScopeProviderAdapter,
+  'openai-images': createOpenAiImagesProviderAdapter,
+  'openai-chat-images': createOpenAiChatImagesProviderAdapter,
+  'openai-responses-images': createOpenAiResponsesImagesProviderAdapter,
+  comfyui: createComfyUiProviderAdapter
+});
+
+export function builtinProviderExtension() {
+  return { contractVersion: 0, id: 'iris.builtin-media', version: '0.1.0',
+    protocols: BUILTIN_PROVIDER_PROTOCOLS.map(descriptor => ({ ...descriptor, createAdapter: PROTOCOL_FACTORIES[descriptor.id] })) };
+}
 
 export function createConfiguredProviderAdapter(provider, options = {}) {
   const selection = options.protocol
     ? selectMediaProtocol({ ...provider, mediaProtocol: options.protocol, protocolInferred: false })
     : selectMediaProtocol(provider);
-  const factory = PROTOCOL_FACTORIES.get(selection.mediaProtocol);
-  if (!factory) throw unsupportedProtocolError(selection.mediaProtocol);
-  const adapter = factory(provider, options);
+  const factory = Object.hasOwn(PROTOCOL_FACTORIES, selection.mediaProtocol) ? PROTOCOL_FACTORIES[selection.mediaProtocol] : null;
+  if (!options.registry && !factory) throw unsupportedProtocolError(selection.mediaProtocol);
+  const adapter = options.registry ? options.registry.createAdapter(selection.mediaProtocol, provider, options) : factory(provider, options);
   const operations = { ...adapter.operations };
+  const key = providerApiKey(provider);
+  const scrub = value => typeof value === 'string' && key ? value.split(key).join('[REDACTED]') : value;
+  operations.mapError = (error, context) => {
+    let mapped;
+    try { mapped = adapter.operations.mapError(error, context); } catch (failure) { mapped = failure; }
+    mapped ||= error;
+    const defaults = {};
+    for (const field of ['stage', 'category', 'acceptance', 'retryable']) {
+      if (mapped?.[field] === undefined) defaults[field] = context?.[field];
+    }
+    return providerErrorRecord(mapped, {
+      ...defaults,
+      safeMessage: scrub(String(mapped?.safeMessage || mapped?.message || mapped)),
+      providerCode: scrub(mapped?.providerCode ?? mapped?.code)
+    });
+  };
   for (const name of ['submit', 'poll']) {
     if (!operations[name]) continue;
     const run = operations[name];
@@ -441,15 +479,15 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
       const modelId = request.model || options.modelId;
       const report = error => reportModelRateLimit(provider, modelId, {
         httpStatus: error.httpStatus ?? error.status, category: error.category,
-        code: error.code, providerCode: error.providerCode, message: error.safeMessage || error.message,
+        code: scrub(error.code), providerCode: scrub(error.providerCode), message: scrub(error.safeMessage || error.message),
         retryAfterMs: error.retryAfterMs,
         source: options.allowRateLimited ? 'probe' : 'task'
       }, options.onRateLimit, request.capability);
       const availability = result => {
         if (name !== 'submit') return;
         const event = { ok: result.ok === true, category: result.category,
-          httpStatus: result.httpStatus ?? result.status, providerCode: result.providerCode || result.code,
-          note: result.safeMessage || result.message,
+          httpStatus: result.httpStatus ?? result.status, providerCode: scrub(result.providerCode || result.code),
+          note: scrub(result.safeMessage || result.message),
           stage: 'submit', source: options.allowRateLimited ? 'probe' : 'task',
           binding: modelAvailabilityBinding(provider, modelId, capability) };
         if (!recordModelAvailability(provider, modelId, request.capability, event)) return;