@easyai-canvas/canvas-plugin-sdk 0.1.0

package/dist/runtime/store.js

@@ -0,0 +1,151 @@
+import { ContractError } from '../protocol/index.js';
+import Database from 'better-sqlite3';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+export class RuntimeStore {
+    db;
+    constructor(path) {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        this.db = new Database(path);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('synchronous = FULL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS meta (id INTEGER PRIMARY KEY, revision INTEGER NOT NULL);
+      INSERT OR IGNORE INTO meta VALUES (1, 0);
+      CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS deployments (id INTEGER PRIMARY KEY, digest TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS plugins (id TEXT PRIMARY KEY, enabled INTEGER NOT NULL, config TEXT NOT NULL, config_version INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS executions (id TEXT PRIMARY KEY, plugin TEXT NOT NULL, hash TEXT NOT NULL, request TEXT NOT NULL, record TEXT NOT NULL);
+      CREATE INDEX IF NOT EXISTS executions_plugin ON executions(plugin);
+      CREATE TABLE IF NOT EXISTS execution_snapshots (id TEXT PRIMARY KEY, snapshot TEXT NOT NULL);
+    `);
+        const pluginColumns = this.db.prepare('PRAGMA table_info(plugins)').all();
+        if (!pluginColumns.some(column => column.name === 'config_version')) {
+            this.db.exec('ALTER TABLE plugins ADD COLUMN config_version INTEGER NOT NULL DEFAULT 0');
+        }
+        this.db.prepare('INSERT OR IGNORE INTO settings(key, value) VALUES (?, ?)').run('instance_id', randomUUID());
+    }
+    syncDeployment(digest) {
+        this.db.transaction(() => {
+            const old = this.db.prepare('SELECT digest FROM deployments WHERE id=1').get();
+            if (old?.digest === digest)
+                return;
+            this.db.prepare('INSERT INTO deployments VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET digest=excluded.digest').run(digest);
+            this.db.prepare('UPDATE meta SET revision=revision+1 WHERE id=1').run();
+        })();
+    }
+    get revision() { return this.db.prepare('SELECT revision FROM meta WHERE id = 1').get().revision; }
+    get instanceId() { return this.db.prepare("SELECT value FROM settings WHERE key='instance_id'").get().value; }
+    getPlugin(id) {
+        const row = this.db.prepare('SELECT enabled, config, config_version FROM plugins WHERE id = ?').get(id);
+        return row ? { enabled: Boolean(row.enabled), config: JSON.parse(row.config), configVersion: row.config_version } : { enabled: false, config: {}, configVersion: 0 };
+    }
+    setPlugin(id, patch) {
+        this.db.transaction(() => {
+            const prev = this.getPlugin(id);
+            if (patch.expectedVersion !== undefined && patch.expectedVersion !== prev.configVersion) {
+                throw new ContractError('插件配置已被其他页面修改，请重新加载后再保存', 409, 'PLUGIN_CONFIG_CONFLICT');
+            }
+            this.db.prepare(`INSERT INTO plugins(id, enabled, config, config_version) VALUES (?, ?, ?, 1)
+        ON CONFLICT(id) DO UPDATE SET enabled=excluded.enabled, config=excluded.config, config_version=plugins.config_version+1`)
+                .run(id, Number(patch.enabled ?? prev.enabled), JSON.stringify(patch.config ?? prev.config));
+            this.db.prepare('UPDATE meta SET revision=revision+1 WHERE id=1').run();
+        })();
+        return this.getPlugin(id);
+    }
+    accept(request, snapshot = { config: {}, release: 'legacy', safeRetry: false, maxAttempts: 1 }) {
+        return this.db.transaction(() => {
+            const hash = createHash('sha256').update(canonical(request)).digest('hex');
+            const prev = this.db.prepare('SELECT hash, record FROM executions WHERE id=?').get(request.executionId);
+            if (prev) {
+                if (prev.hash !== hash)
+                    throw new ContractError('执行标识与请求内容冲突', 409, 'EXECUTION_CONFLICT');
+                return { created: false, record: JSON.parse(prev.record) };
+            }
+            const now = new Date().toISOString();
+            const record = { executionId: request.executionId, pluginId: request.pluginId, nodeType: request.nodeType, status: 'queued', progress: 0, phase: '排队', attempt: 0, maxAttempts: snapshot.maxAttempts, cancelRequested: false, createdAt: now, updatedAt: now };
+            this.db.prepare('INSERT INTO executions VALUES (?, ?, ?, ?, ?)').run(request.executionId, request.pluginId, hash, JSON.stringify(request), JSON.stringify(record));
+            this.db.prepare('INSERT INTO execution_snapshots VALUES (?, ?)').run(request.executionId, JSON.stringify(snapshot));
+            return { created: true, record };
+        })();
+    }
+    getSnapshot(id) {
+        const row = this.db.prepare('SELECT snapshot FROM execution_snapshots WHERE id=?').get(id);
+        return row ? JSON.parse(row.snapshot) : { config: {}, release: 'legacy', safeRetry: false, maxAttempts: 1 };
+    }
+    getExecution(id) {
+        const row = this.db.prepare('SELECT record FROM executions WHERE id=?').get(id);
+        return row ? JSON.parse(row.record) : undefined;
+    }
+    getRequest(id) {
+        const row = this.db.prepare('SELECT request FROM executions WHERE id=?').get(id);
+        if (!row)
+            throw new Error('任务不存在');
+        return JSON.parse(row.request);
+    }
+    update(id, patch) {
+        const previous = this.getExecution(id);
+        if (!previous)
+            throw new Error('任务不存在');
+        if (['succeeded', 'failed', 'cancelled', 'interrupted'].includes(previous.status))
+            return previous;
+        const record = { ...previous, ...patch, executionId: id, updatedAt: new Date().toISOString() };
+        this.db.prepare('UPDATE executions SET record=? WHERE id=?').run(JSON.stringify(record), id);
+        return record;
+    }
+    claim(id) {
+        return this.db.transaction(() => {
+            const previous = this.getExecution(id);
+            if (!previous || previous.status !== 'queued' || previous.cancelRequested)
+                return undefined;
+            const record = { ...previous, status: 'running', phase: '启动任务', attempt: previous.attempt + 1, updatedAt: new Date().toISOString() };
+            this.db.prepare('UPDATE executions SET record=? WHERE id=?').run(JSON.stringify(record), id);
+            return record;
+        })();
+    }
+    requeue(id, error) {
+        const previous = this.getExecution(id);
+        if (!previous || previous.cancelRequested || ['succeeded', 'cancelled'].includes(previous.status))
+            return previous;
+        const record = { ...previous, status: 'queued', progress: 0, phase: '等待重试', ...(error ? { error } : {}), updatedAt: new Date().toISOString() };
+        this.db.prepare('UPDATE executions SET record=? WHERE id=?').run(JSON.stringify(record), id);
+        return record;
+    }
+    queued(pluginId) {
+        const rows = this.db.prepare(pluginId ? 'SELECT id, request, record FROM executions WHERE plugin=? ORDER BY rowid' : 'SELECT id, request, record FROM executions ORDER BY rowid').all(...(pluginId ? [pluginId] : []));
+        return rows.flatMap(row => {
+            const record = JSON.parse(row.record);
+            return record.status === 'queued' && !record.cancelRequested ? [{ id: row.id, request: JSON.parse(row.request) }] : [];
+        });
+    }
+    list(limit = 100) {
+        return this.db.prepare('SELECT record FROM executions ORDER BY rowid DESC LIMIT ?').all(Math.min(limit, 1000)).map(r => JSON.parse(r.record));
+    }
+    recover() {
+        const recovered = [];
+        const rows = this.db.prepare('SELECT record FROM executions').all();
+        for (const row of rows) {
+            const record = JSON.parse(row.record);
+            if (!['running', 'queued'].includes(record.status))
+                continue;
+            const snapshot = this.getSnapshot(record.executionId);
+            if (snapshot.safeRetry && record.attempt < snapshot.maxAttempts && !record.cancelRequested) {
+                this.requeue(record.executionId, { code: 'SERVICE_RESTARTED', message: '服务重启，任务已重新排队' });
+                recovered.push(record.executionId);
+            }
+            else {
+                this.update(record.executionId, { status: 'interrupted', phase: '执行中断', error: { code: 'SERVICE_RESTARTED', message: '服务重启，任务未自动重跑，请核实结果后重试' } });
+            }
+        }
+        return recovered;
+    }
+    close() { this.db.close(); }
+}

package/dist/runtime/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/worker.js

@@ -0,0 +1,38 @@
+import { validateParameters } from '../protocol/index.js';
+import { createHostFileService } from './host-files.js';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+const abort = new AbortController();
+process.on('message', async (message) => {
+    if (message.type === 'cancel') {
+        abort.abort();
+        return;
+    }
+    if (message.type !== 'run')
+        return;
+    try {
+        const request = message.request;
+        if (message.packageEntry &&
+            createHash('sha256').update(await readFile(message.packageEntry)).digest('hex') !== message.packageEntryHash)
+            throw new Error('插件运行文件摘要与任务固定版本不一致');
+        const plugin = message.packageEntry
+            ? (await import(pathToFileURL(message.packageEntry).href)).default
+            : (await import('../plugins/catalog.js')).getPlugins().find(p => p.manifest.id === request.pluginId);
+        if (!plugin || plugin.manifest.id !== request.pluginId)
+            throw new Error('插件包与任务标识不一致');
+        const definition = plugin.manifest.contributes.nodes.find(n => n.type === request.nodeType);
+        const normalized = validateParameters(definition.parameters ?? [], plugin.normalizeParameters?.(request.nodeType, request.parameters) ?? request.parameters);
+        const result = await plugin.handlers[request.nodeType]({ ...request, parameters: normalized }, {
+            signal: abort.signal, config: message.config,
+            files: createHostFileService(message.hostFiles, request.executionId),
+            progress: (value, phase) => process.send?.({ type: 'progress', value, phase }),
+        });
+        process.send?.({ type: 'result', result });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '插件执行失败';
+        const retryable = !abort.signal.aborted && /(ECONNRESET|ETIMEDOUT|fetch failed|网络|暂时|上传|存储服务|socket hang up)/i.test(message);
+        process.send?.({ type: 'error', message, retryable });
+    }
+});

package/dist/sdk/frontend.d.ts

@@ -0,0 +1,62 @@
+import { type Ref } from 'vue';
+import type { NodeDefinition, DataPacket, PluginNodeTheme, AssetSource, PluginAction, PluginRuntimeContext, SelectedResource } from '../protocol/index.js';
+export declare const NODE_CONTEXT = "easyai.plugin.node.v1";
+export declare const ASSET_SELECTOR_CONTEXT = "easyai.plugin.asset-selector.v1";
+export declare const ACTION_CONTEXT = "easyai.plugin.action.v1";
+export interface PluginNodeContext {
+    definition: NodeDefinition;
+    environment: 'canvas';
+    runtime: Readonly<PluginRuntimeContext>;
+    parameters: Readonly<Ref<Record<string, unknown>>>;
+    inputs: Readonly<Ref<Record<string, DataPacket[]>>>;
+    output: Readonly<Ref<DataPacket | undefined>>;
+    outputs: Readonly<Ref<Record<string, DataPacket | undefined>>>;
+    document: Readonly<Ref<unknown>>;
+    resultVersion: Readonly<Ref<string | undefined>>;
+    progress: Readonly<Ref<number | undefined>>;
+    isExecuting: Readonly<Ref<boolean>>;
+    error: Readonly<Ref<string | undefined>>;
+    theme: Readonly<Ref<PluginNodeTheme>>;
+    updateParameters(patch: Record<string, unknown>): void;
+    updateDocument(value: unknown): void;
+    disconnectInput(sourceNodeId: string, sourcePortId?: string): void;
+    uploadMedia(files: File[]): Promise<DataPacket[]>;
+    setSourceOutputs(outputs: Record<string, DataPacket>): void;
+    execute(confirm?: boolean): Promise<void>;
+    cancelExecution(): Promise<void>;
+    addOutputToCanvas(portId: string, options?: {
+        title?: string;
+        connect?: boolean;
+    }): Promise<{
+        created: boolean;
+        nodeId?: string;
+    }>;
+    openWorkspace?(): void;
+    closeWorkspace?(): void;
+    query(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+export declare function usePluginNode(): PluginNodeContext;
+export interface PluginAssetSelectorContext {
+    source: AssetSource;
+    runtime: Readonly<PluginRuntimeContext>;
+    constraints: Readonly<{
+        mediaTypes: string[];
+        maxCount: number;
+    }>;
+    query(name: string, input: Record<string, unknown>): Promise<unknown>;
+    submit(resources: SelectedResource[]): void | Promise<void>;
+    cancel(): void;
+}
+export interface PluginActionContext {
+    action: PluginAction;
+    runtime: Readonly<PluginRuntimeContext>;
+    constraints: Readonly<{
+        mediaTypes: string[];
+        maxCount: number;
+    }>;
+    query(name: string, input: Record<string, unknown>): Promise<unknown>;
+    submit(resources: SelectedResource[]): void | Promise<void>;
+    cancel(): void;
+}
+export declare function usePluginAction(): PluginActionContext;
+export declare function usePluginAssetSelector(): PluginAssetSelectorContext;

package/dist/sdk/frontend.js

@@ -0,0 +1,40 @@
+import { inject } from 'vue';
+export const NODE_CONTEXT = 'easyai.plugin.node.v1';
+export const ASSET_SELECTOR_CONTEXT = 'easyai.plugin.asset-selector.v1';
+export const ACTION_CONTEXT = 'easyai.plugin.action.v1';
+export function usePluginNode() {
+    const ctx = inject(NODE_CONTEXT);
+    if (!ctx)
+        throw new Error('请在画布内加载该组件');
+    return ctx;
+}
+export function usePluginAction() {
+    const ctx = inject(ACTION_CONTEXT);
+    if (!ctx)
+        throw new Error('请在画布操作容器内加载该组件');
+    return ctx;
+}
+export function usePluginAssetSelector() {
+    const ctx = inject(ASSET_SELECTOR_CONTEXT);
+    if (ctx)
+        return ctx;
+    const action = inject(ACTION_CONTEXT);
+    if (!action)
+        throw new Error('请在画布素材弹框内加载该组件');
+    return {
+        source: {
+            id: action.action.id,
+            name: action.action.name,
+            description: action.action.description,
+            mediaTypes: action.action.mediaTypes,
+            ...(action.action.ui.component ? { ui: { selector: action.action.ui.component } } : {}),
+            ...(action.action.ui.url ? { url: action.action.ui.url, origin: action.action.ui.origin } : {}),
+            menu: action.action.menu,
+        },
+        runtime: action.runtime,
+        constraints: action.constraints,
+        query: action.query,
+        submit: action.submit,
+        cancel: action.cancel,
+    };
+}

package/dist/sdk/index.d.ts

@@ -0,0 +1,38 @@
+import { type PluginManifest, type NodeDefinition, type ExecutionRequest, type ExecutionResult, type PluginRuntimeContext } from '../protocol/index.js';
+export type HostFileRecord = {
+    id: string;
+    url: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    sha256: string;
+    path?: string;
+};
+export type HostFileService = {
+    put(input: {
+        key: string;
+        path: string;
+        mimeType: string;
+    }): Promise<HostFileRecord>;
+    readJson<T = unknown>(key: string): Promise<T | undefined>;
+    info(key: string): Promise<Pick<HostFileRecord, 'id' | 'url' | 'size' | 'sha256'> | undefined>;
+    exists(key: string): Promise<boolean>;
+};
+export type HandlerContext = {
+    signal: AbortSignal;
+    config: Record<string, unknown>;
+    files: HostFileService;
+    progress(value: number, phase?: string): void;
+};
+export type NodeHandler = (request: ExecutionRequest, context: HandlerContext) => Promise<ExecutionResult> | ExecutionResult;
+export type Plugin = {
+    manifest: PluginManifest;
+    handlers: Record<string, NodeHandler>;
+    resolveManifest?: (config: Record<string, unknown>, manifest: PluginManifest) => PluginManifest;
+    queries?: Record<string, (input: Record<string, unknown>, config: Record<string, unknown>, context: PluginRuntimeContext, signal?: AbortSignal) => Promise<unknown>>;
+    /** Optional real dependency check. Absence means hosts may report format validation only. */
+    checkConfig?: (config: Record<string, unknown>) => Promise<unknown>;
+    normalizeParameters?: (nodeType: string, parameters: Record<string, unknown>) => Record<string, unknown>;
+};
+export declare function definePlugin(plugin: Plugin): Plugin;
+export declare function defineNode(node: NodeDefinition): NodeDefinition;

package/dist/sdk/index.js

@@ -0,0 +1,10 @@
+import { validateManifest } from '../protocol/index.js';
+export function definePlugin(plugin) {
+    validateManifest(plugin.manifest);
+    for (const node of plugin.manifest.contributes.nodes ?? []) {
+        if (['remote', 'confirmed'].includes(node.execution) && !plugin.handlers[node.type])
+            throw new Error(`缺少 ${node.type} 的业务处理器`);
+    }
+    return plugin;
+}
+export function defineNode(node) { return node; }