@easyai-canvas/canvas-plugin-sdk 0.1.0

package/dist/runtime/engine.js

@@ -0,0 +1,296 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { fork } from 'node:child_process';
+import { RuntimeStore } from './store.js';
+import { acquireInstanceLock } from './instance-lock.js';
+import { fieldsConfig } from './plugin-config.js';
+import { PROTOCOL, ContractError, validateManifest, validateExecution, validateResult, validatePluginRuntimeContext } from '../protocol/index.js';
+const defaultPlugins = process.env.PLUGIN_BUILTINS === '0'
+    ? []
+    : (await import('../plugins/catalog.js')).getPlugins();
+export class Runtime {
+    presentations;
+    executionEntries;
+    store;
+    plugins;
+    queue = new Map();
+    active = new Map();
+    /** Task grants stay in memory only. They are deliberately excluded from SQLite records and snapshots. */
+    hostFiles = new Map();
+    draining = false;
+    releaseInstanceLock;
+    constructor(path, plugins = defaultPlugins, presentations = {}, executionEntries = {}) {
+        this.presentations = presentations;
+        this.executionEntries = executionEntries;
+        this.plugins = plugins;
+        if (new Set(plugins.map(p => p.manifest.id)).size !== plugins.length)
+            throw new ContractError('插件标识重复');
+        this.releaseInstanceLock = acquireInstanceLock(path);
+        try {
+            this.store = new RuntimeStore(path);
+            this.store.recover();
+            for (const item of this.store.queued())
+                this.enqueue(item.request.pluginId, item.id);
+            const catalogPath = new URL('../plugins/catalog' + (import.meta.url.endsWith('.ts') ? '.ts' : '.js'), import.meta.url);
+            this.store.syncDeployment(createHash('sha256').update(JSON.stringify(this.plugins.map(p => p.manifest))).update(existsSync(catalogPath) ? readFileSync(catalogPath) : '').update(existsSync('public/ui/manifest.json') ? readFileSync('public/ui/manifest.json') : '').digest('hex'));
+            for (const pluginId of this.queue.keys())
+                this.pump(pluginId);
+        }
+        catch (error) {
+            this.releaseInstanceLock();
+            throw error;
+        }
+    }
+    plugin(id) { const p = this.plugins.find(p => p.manifest.id === id); if (!p)
+        throw new ContractError('插件不存在'); return p; }
+    configure(id, patch) {
+        const p = this.plugin(id), prev = this.store.getPlugin(id);
+        if (patch.enabled !== undefined && typeof patch.enabled !== 'boolean')
+            throw new ContractError('enabled 必须是布尔值');
+        if (patch.expectedVersion !== undefined && (!Number.isSafeInteger(patch.expectedVersion) || patch.expectedVersion < 0))
+            throw new ContractError('expectedVersion 必须是非负整数');
+        const config = fieldsConfig(p.manifest.configFields ?? [], prev.config, patch.config ?? {});
+        if (patch.enabled ?? prev.enabled)
+            for (const f of p.manifest.configFields ?? [])
+                if (f.required && (config[f.key] === undefined || config[f.key] === ''))
+                    throw new ContractError(`缺少配置 ${f.label}`);
+        const manifest = validateManifest(p.resolveManifest?.(structuredClone(config), structuredClone(p.manifest)) ?? p.manifest);
+        if (manifest.id !== id)
+            throw new ContractError('配置不能改变插件标识');
+        this.store.setPlugin(id, { enabled: patch.enabled, config, expectedVersion: patch.expectedVersion });
+        return this.catalog().plugins.find(p => p.manifest.id === id);
+    }
+    catalog() {
+        return { protocol: PROTOCOL, revision: this.store.revision, instanceId: this.store.instanceId, plugins: this.plugins.map(p => {
+                const stored = this.store.getPlugin(p.manifest.id);
+                const config = fieldsConfig(p.manifest.configFields ?? [], stored.config, {});
+                const manifest = validateManifest(p.resolveManifest?.(structuredClone(config), structuredClone(p.manifest)) ?? structuredClone(p.manifest));
+                if (manifest.id !== p.manifest.id)
+                    throw new ContractError('配置不能改变插件标识');
+                const secretConfigured = Object.fromEntries((manifest.configFields ?? [])
+                    .filter(field => field.type === 'secret')
+                    .map(field => [field.key, typeof stored.config[field.key] === 'string' && Boolean(stored.config[field.key])]));
+                for (const f of manifest.configFields ?? [])
+                    if (f.type === 'secret')
+                        delete config[f.key];
+                return { ...this.presentations[p.manifest.id], manifest, enabled: stored.enabled, config, configVersion: stored.configVersion, secretConfigured, configCheckAvailable: Boolean(p.checkConfig) };
+            }) };
+    }
+    async checkConfig(id) {
+        const plugin = this.plugin(id);
+        const state = this.store.getPlugin(id);
+        const config = fieldsConfig(plugin.manifest.configFields ?? [], state.config, {});
+        if (!plugin.checkConfig)
+            return { supported: false, validation: 'passed', message: '配置格式校验通过；插件未声明外部连接检查能力' };
+        return { supported: true, validation: 'passed', result: await plugin.checkConfig(structuredClone(config)) };
+    }
+    query(id, name, input, context, signal) {
+        const p = this.plugin(id), state = this.store.getPlugin(id);
+        if (!state.enabled)
+            throw new ContractError('插件已停用', 409, 'PLUGIN_DISABLED');
+        if (!p.queries?.[name])
+            throw new ContractError('查询不存在');
+        return p.queries[name](input, state.config, validatePluginRuntimeContext(context), signal);
+    }
+    normalize(id, nodeType, parameters) {
+        const p = this.plugin(id);
+        if (!this.store.getPlugin(id).enabled)
+            throw new ContractError('插件已停用', 409, 'PLUGIN_DISABLED');
+        return p.normalizeParameters?.(nodeType, parameters) ?? parameters;
+    }
+    submit(request) {
+        const p = this.plugin(request.pluginId);
+        const node = p.manifest.contributes.nodes?.find(n => n.type === request.nodeType);
+        if (!node || !['remote', 'confirmed'].includes(node.execution))
+            throw new ContractError('节点不支持后台执行');
+        validateExecution(request, node);
+        const persistedRequest = structuredClone(request);
+        delete persistedRequest.host;
+        // Repeated acceptance is stable even when the plugin was disabled afterwards. A
+        // fresh task grant may be supplied after a process restart without changing the
+        // idempotent business request.
+        const existing = this.store.getExecution(request.executionId);
+        if (existing) {
+            if (request.host?.files && ['queued', 'running'].includes(existing.status))
+                this.hostFiles.set(request.executionId, structuredClone(request.host.files));
+            return this.store.accept(persistedRequest);
+        }
+        if (this.draining)
+            throw new ContractError('服务正在排空', 503, 'DRAINING');
+        const state = this.store.getPlugin(request.pluginId);
+        if (!state.enabled)
+            throw new ContractError('插件已停用', 409, 'PLUGIN_DISABLED');
+        const waiting = this.store.queued().filter(item => item.request.pluginId === request.pluginId && item.request.nodeType === request.nodeType);
+        const waitingForUser = waiting.filter(item => item.request.context.userId === request.context.userId).length;
+        if (waitingForUser >= (node.runtime?.maxQueuedPerUser ?? Number.POSITIVE_INFINITY))
+            throw new ContractError('当前用户的插件排队任务已达上限', 429, 'USER_QUEUE_LIMIT');
+        if (waiting.length >= (node.runtime?.maxQueued ?? Number.POSITIVE_INFINITY))
+            throw new ContractError('插件排队任务已达上限', 429, 'QUEUE_LIMIT');
+        const accepted = this.store.accept(persistedRequest, {
+            config: structuredClone(state.config),
+            release: p.manifest.release,
+            safeRetry: node.runtime?.safeRetry === true,
+            maxAttempts: node.runtime?.safeRetry ? node.runtime.maxAttempts ?? 3 : 1,
+            ...(this.executionEntries[request.pluginId] ? {
+                packageEntry: this.executionEntries[request.pluginId].entry,
+                packageDigest: this.executionEntries[request.pluginId].digest,
+                packageEntryHash: this.executionEntries[request.pluginId].entryHash,
+            } : {}),
+        });
+        if (request.host?.files)
+            this.hostFiles.set(request.executionId, structuredClone(request.host.files));
+        this.enqueue(request.pluginId, request.executionId);
+        this.pump(request.pluginId);
+        return accepted;
+    }
+    enqueue(pluginId, executionId) {
+        const queue = this.queue.get(pluginId) ?? [];
+        if (!queue.includes(executionId))
+            this.queue.set(pluginId, [...queue, executionId]);
+    }
+    cancel(id) {
+        const record = this.store.getExecution(id);
+        if (!record)
+            throw new ContractError('任务不存在', 404, 'TASK_NOT_FOUND');
+        this.store.update(id, { cancelRequested: true });
+        const running = this.active.get(record.pluginId);
+        if (running?.executionId === id) {
+            running.child.send({ type: 'cancel' });
+            running.forceTimer ??= setTimeout(() => this.killWorker(running.child, 'SIGKILL'), 5000);
+            running.forceTimer.unref();
+        }
+        else {
+            this.store.update(id, { status: 'cancelled' });
+            this.hostFiles.delete(id);
+        }
+        return this.store.getExecution(id);
+    }
+    pump(pluginId) {
+        if (this.draining || this.active.has(pluginId))
+            return;
+        const id = this.queue.get(pluginId)?.shift();
+        if (!id)
+            return;
+        if (this.store.getExecution(id)?.status !== 'queued') {
+            this.pump(pluginId);
+            return;
+        }
+        const request = this.store.getRequest(id);
+        const node = this.plugins.find(plugin => plugin.manifest.id === pluginId)?.manifest.contributes.nodes?.find(n => n.type === request.nodeType);
+        if (!node) {
+            this.store.update(id, { status: 'failed', phase: '插件不可用', error: { code: 'PLUGIN_UNAVAILABLE', message: '该任务所需的插件或节点已移除，请检查插件配置后重新创建任务' } });
+            this.hostFiles.delete(id);
+            this.pump(pluginId);
+            return;
+        }
+        const isTs = import.meta.url.endsWith('.ts');
+        const child = fork(new URL(isTs ? './worker.ts' : './worker.js', import.meta.url), [], { execArgv: isTs ? ['--import', 'tsx'] : [], stdio: ['ignore', 'ignore', 'inherit', 'ipc'], serialization: 'json', detached: process.platform !== 'win32' });
+        const claimed = this.store.claim(id);
+        if (!claimed) {
+            child.kill();
+            this.pump(pluginId);
+            return;
+        }
+        this.active.set(pluginId, { child, executionId: id });
+        let ended = false;
+        const finish = (patch, retryable = false) => {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            const active = this.active.get(pluginId);
+            if (active?.forceTimer)
+                clearTimeout(active.forceTimer);
+            const current = this.store.getExecution(id);
+            const snapshot = this.store.getSnapshot(id);
+            const cancelled = current.cancelRequested;
+            if (retryable && snapshot.safeRetry && current.attempt < snapshot.maxAttempts && !cancelled) {
+                this.store.requeue(id, patch.error);
+                this.enqueue(pluginId, id);
+            }
+            else {
+                this.store.update(id, patch.status === 'failed' && patch.error?.code === 'PLUGIN_ERROR' && cancelled ? { status: 'cancelled', phase: '已取消', error: patch.error } : patch);
+                this.hostFiles.delete(id);
+            }
+            this.killWorker(child, 'SIGTERM');
+            this.active.delete(pluginId);
+            this.pump(pluginId);
+        };
+        const timer = setTimeout(() => finish({ status: 'failed', phase: '执行超时', error: { code: 'TIMEOUT', message: '插件执行超时，请核实外部副作用后重试' } }), node.timeoutMs ?? 300_000);
+        child.on('message', (m) => {
+            if (ended)
+                return;
+            if (m.type === 'progress' && Number.isFinite(m.value))
+                this.store.update(id, { progress: Math.max(0, Math.min(100, m.value)), ...(typeof m.phase === 'string' && m.phase ? { phase: m.phase.slice(0, 100) } : {}) });
+            if (m.type === 'error')
+                finish({ status: 'failed', phase: '执行失败', error: { code: 'PLUGIN_ERROR', message: String(m.message).slice(0, 2000) } }, m.retryable === true);
+            if (m.type === 'result') {
+                try {
+                    const result = validateResult(m.result, node);
+                    finish({ status: 'succeeded', phase: result.phase ?? '完成', progress: 100, result });
+                }
+                catch (e) {
+                    finish({ status: 'failed', phase: '结果无效', error: { code: 'INVALID_RESULT', message: e.message } });
+                }
+            }
+        });
+        child.on('exit', () => finish({ status: 'failed', phase: '进程退出', error: { code: 'WORKER_EXIT', message: '插件进程意外退出' } }, true));
+        child.on('error', e => finish({ status: 'failed', phase: '进程错误', error: { code: 'WORKER_ERROR', message: e.message } }, true));
+        const remoteFiles = this.hostFiles.get(id);
+        const localFiles = request.context.runtime === undefined
+            ? { mode: 'local' }
+            : { mode: 'unavailable', reason: '宿主未提供文件能力，平台执行不能降级到插件本地存储' };
+        child.send({
+            type: 'run', request, config: this.store.getSnapshot(id).config,
+            packageEntry: this.store.getSnapshot(id).packageEntry,
+            packageEntryHash: this.store.getSnapshot(id).packageEntryHash,
+            hostFiles: remoteFiles ? { mode: 'remote', ...remoteFiles } : localFiles,
+        });
+    }
+    killWorker(child, signal) {
+        if (!child.pid)
+            return;
+        try {
+            if (process.platform !== 'win32')
+                process.kill(-child.pid, signal);
+            else
+                child.kill(signal);
+        }
+        catch { /* The process group has already stopped. */ }
+    }
+    async close() {
+        this.draining = true;
+        const deadline = Date.now() + 30_000;
+        while (this.active.size && Date.now() < deadline)
+            await new Promise(r => setTimeout(r, 50));
+        for (const active of this.active.values()) {
+            active.child.send?.({ type: 'cancel' });
+            this.killWorker(active.child, 'SIGTERM');
+        }
+        const forceDeadline = Date.now() + 5_000;
+        while (this.active.size && Date.now() < forceDeadline)
+            await new Promise(r => setTimeout(r, 50));
+        for (const active of this.active.values())
+            this.killWorker(active.child, 'SIGKILL');
+        // Keep the store alive until exit handlers have observed the forced stop.
+        // Otherwise a late child `exit` event can try to requeue/update a task after
+        // SQLite has already been closed.
+        const exitDeadline = Date.now() + 2_000;
+        while (this.active.size && Date.now() < exitDeadline)
+            await new Promise(r => setTimeout(r, 25));
+        if (this.active.size) {
+            // Preserve `running` in SQLite so startup recovery applies the node's
+            // declared retry policy. No process callback may touch the closed store.
+            for (const active of this.active.values()) {
+                if (active.forceTimer)
+                    clearTimeout(active.forceTimer);
+                active.child.removeAllListeners('message');
+                active.child.removeAllListeners('exit');
+                active.child.removeAllListeners('error');
+            }
+            this.active.clear();
+        }
+        this.store.close();
+        this.releaseInstanceLock();
+    }
+}

package/dist/runtime/host-files.d.ts

@@ -0,0 +1,16 @@
+import type { HostFileService } from '../sdk/index.js';
+export type HostFilesDescriptor = {
+    mode: 'local';
+    dataDirectory?: string;
+    publicUrl?: string;
+} | {
+    mode: 'remote';
+    baseUrl: string;
+    grant: string;
+    expiresAt: number;
+    path?: '/v1/plugin-artifacts';
+} | {
+    mode: 'unavailable';
+    reason: string;
+};
+export declare function createHostFileService(descriptor: HostFilesDescriptor | undefined, executionId: string): HostFileService;

package/dist/runtime/host-files.js

@@ -0,0 +1,208 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { copyFile, mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Writable } from 'node:stream';
+function safeSegment(value) {
+    const segment = basename(value).replace(/[^\p{L}\p{N}._-]/gu, '_').slice(0, 160);
+    if (!segment || segment === '.' || segment === '..')
+        throw new Error('宿主文件名称无效');
+    return segment;
+}
+function safeKey(value) {
+    const parts = value.split('/').filter(Boolean).map(safeSegment);
+    if (!parts.length || parts.length > 8)
+        throw new Error('宿主文件标识无效');
+    return parts.join('/');
+}
+async function integrity(path) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(path), new Writable({
+        write(chunk, _encoding, callback) { hash.update(chunk); callback(); },
+    }));
+    return { sha256: hash.digest('hex'), size: (await stat(path)).size };
+}
+class LocalHostFileService {
+    executionId;
+    root;
+    publicUrl;
+    constructor(descriptor, executionId) {
+        this.executionId = safeSegment(executionId);
+        this.root = join(descriptor.dataDirectory ?? process.env.PLUGIN_DATA_DIR ?? './data', 'files', 'artifacts', this.executionId);
+        this.publicUrl = (descriptor.publicUrl ?? process.env.PLUGIN_PUBLIC_URL ?? 'http://127.0.0.1:4310').replace(/\/$/, '');
+    }
+    path(key) { return join(this.root, ...safeKey(key).split('/')); }
+    async put(input) {
+        const key = safeKey(input.key);
+        const target = this.path(key);
+        const temporary = `${target}.${randomUUID()}.tmp`;
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await copyFile(input.path, temporary);
+        await rename(temporary, target).catch(async (error) => {
+            await rm(temporary, { force: true });
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        const result = await integrity(target);
+        return {
+            id: `local:${result.sha256}`,
+            url: `${this.publicUrl}/files/artifacts/${encodeURIComponent(this.executionId)}/${key.split('/').map(encodeURIComponent).join('/')}`,
+            name: basename(key),
+            mimeType: input.mimeType,
+            path: target,
+            ...result,
+        };
+    }
+    async readJson(key) {
+        try {
+            const file = this.path(key);
+            if ((await stat(file)).size > 5_000_000)
+                throw new Error('宿主 JSON 文件超过大小限制');
+            return JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    async info(key) {
+        try {
+            const metadata = await integrity(this.path(key));
+            const safe = safeKey(key);
+            return {
+                id: `local:${metadata.sha256}`,
+                url: `${this.publicUrl}/files/artifacts/${encodeURIComponent(this.executionId)}/${safe.split('/').map(encodeURIComponent).join('/')}`,
+                ...metadata,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    async exists(key) {
+        return Boolean(await this.info(key));
+    }
+}
+class RemoteHostFileService {
+    descriptor;
+    executionId;
+    baseUrl;
+    capabilityPath;
+    renewing;
+    constructor(descriptor, executionId) {
+        this.descriptor = descriptor;
+        this.executionId = executionId;
+        const url = new URL(descriptor.baseUrl);
+        const loopbackHttp = url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]', '::1'].includes(url.hostname);
+        if (url.protocol !== 'https:' && !loopbackHttp)
+            throw new Error('远程宿主文件能力必须使用 HTTPS 或本机回环地址');
+        if (url.username || url.password || url.search || url.hash)
+            throw new Error('远程宿主文件地址无效');
+        if (!descriptor.grant || descriptor.grant.length > 8_192)
+            throw new Error('宿主文件授权无效');
+        if (!Number.isSafeInteger(descriptor.expiresAt))
+            throw new Error('宿主文件授权有效期无效');
+        this.baseUrl = url.toString().replace(/\/$/, '');
+        this.capabilityPath = descriptor.path ?? '/v1/plugin-artifacts';
+    }
+    endpoint(key) {
+        return `${this.baseUrl}${this.capabilityPath}/${encodeURIComponent(this.executionId)}?key=${encodeURIComponent(safeKey(key))}`;
+    }
+    async ensureGrant() {
+        if (this.descriptor.expiresAt > Date.now() + 30_000)
+            return;
+        this.renewing ??= (async () => {
+            const response = await fetch(`${this.baseUrl}${this.capabilityPath}/${encodeURIComponent(this.executionId)}/renew`, {
+                method: 'POST', headers: { authorization: `Bearer ${this.descriptor.grant}` }, redirect: 'error',
+            });
+            if (!response.ok)
+                throw new Error(`宿主文件授权续期失败（${response.status}）`);
+            const value = await response.json();
+            const expiresAt = Number(value.expiresAt);
+            if (typeof value.grant !== 'string' || !value.grant || value.grant.length > 8_192
+                || !Number.isSafeInteger(expiresAt) || expiresAt <= Date.now() || expiresAt > Date.now() + 2 * 60 * 60 * 1_000 + 5_000)
+                throw new Error('宿主文件授权续期响应无效');
+            this.descriptor.grant = value.grant;
+            this.descriptor.expiresAt = expiresAt;
+        })().finally(() => { this.renewing = undefined; });
+        await this.renewing;
+    }
+    async headers(extra) {
+        await this.ensureGrant();
+        return { authorization: `Bearer ${this.descriptor.grant}`, ...extra };
+    }
+    async put(input) {
+        const metadata = await integrity(input.path);
+        const response = await fetch(this.endpoint(input.key), {
+            method: 'PUT',
+            headers: await this.headers({
+                'content-type': input.mimeType,
+                'content-length': String(metadata.size),
+                'x-content-sha256': metadata.sha256,
+            }),
+            body: createReadStream(input.path),
+            duplex: 'half',
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw new Error(`宿主文件保存失败（${response.status}）`);
+        const value = await response.json();
+        if (typeof value.id !== 'string' || typeof value.url !== 'string' || value.sha256 !== metadata.sha256
+            || value.size !== metadata.size)
+            throw new Error('宿主文件响应无效');
+        return { ...metadata, id: value.id, url: value.url, name: basename(safeKey(input.key)), mimeType: input.mimeType };
+    }
+    async readJson(key) {
+        const response = await fetch(this.endpoint(key), { headers: await this.headers({ accept: 'application/json' }), redirect: 'error' });
+        if (response.status === 404)
+            return;
+        if (!response.ok)
+            throw new Error(`宿主文件读取失败（${response.status}）`);
+        const length = Number(response.headers.get('content-length') ?? 0);
+        if (length > 5_000_000)
+            throw new Error('宿主 JSON 文件超过大小限制');
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > 5_000_000)
+            throw new Error('宿主 JSON 文件超过大小限制');
+        return JSON.parse(Buffer.from(buffer).toString('utf8'));
+    }
+    async info(key) {
+        const response = await fetch(this.endpoint(key), { method: 'HEAD', headers: await this.headers(), redirect: 'error' });
+        if (response.status === 404)
+            return;
+        if (!response.ok)
+            throw new Error(`宿主文件查询失败（${response.status}）`);
+        const size = Number(response.headers.get('content-length'));
+        const sha256 = response.headers.get('x-content-sha256') ?? '';
+        const id = response.headers.get('x-resource-id') ?? '';
+        const url = response.headers.get('x-resource-url') ?? '';
+        if (!Number.isSafeInteger(size) || size < 0 || !/^[a-f0-9]{64}$/.test(sha256) || !id || !url)
+            throw new Error('宿主文件元数据无效');
+        return { id, url, size, sha256 };
+    }
+    async exists(key) {
+        return Boolean(await this.info(key));
+    }
+}
+class UnavailableHostFileService {
+    reason;
+    constructor(reason) {
+        this.reason = reason;
+    }
+    fail() { throw new Error(this.reason || '宿主未提供文件能力'); }
+    async put() { return this.fail(); }
+    async readJson() { return this.fail(); }
+    async info() { return this.fail(); }
+    async exists() { return this.fail(); }
+}
+export function createHostFileService(descriptor, executionId) {
+    if (!descriptor || descriptor.mode === 'local')
+        return new LocalHostFileService(descriptor ?? { mode: 'local' }, executionId);
+    if (descriptor.mode === 'unavailable')
+        return new UnavailableHostFileService(descriptor.reason);
+    return new RemoteHostFileService(descriptor, executionId);
+}

package/dist/runtime/instance-lock.d.ts

@@ -0,0 +1 @@
+export declare function acquireInstanceLock(databasePath: string): () => void;

package/dist/runtime/instance-lock.js

@@ -0,0 +1,52 @@
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function acquireInstanceLock(databasePath) {
+    mkdirSync(dirname(databasePath), { recursive: true, mode: 0o700 });
+    const path = `${databasePath}.instance-lock`;
+    const record = { pid: process.pid, token: randomUUID() };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(path, 'wx', 0o600);
+            try {
+                writeFileSync(fd, JSON.stringify(record));
+            }
+            finally {
+                closeSync(fd);
+            }
+            return () => {
+                try {
+                    const current = JSON.parse(readFileSync(path, 'utf8'));
+                    if (current.token === record.token)
+                        unlinkSync(path);
+                }
+                catch { /* Missing or replaced locks are not ours to remove. */ }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner;
+            try {
+                owner = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch { /* stale malformed lock */ }
+            if (owner?.pid && processExists(owner.pid))
+                throw new Error('数据目录已被另一个插件服务实例使用');
+            try {
+                unlinkSync(path);
+            }
+            catch { /* another starter may have replaced it */ }
+        }
+    }
+    throw new Error('无法取得插件服务数据目录锁');
+}

package/dist/runtime/package-runtime.d.ts

@@ -0,0 +1,44 @@
+import { type PluginManifest, type PluginRuntimeContext } from '../protocol/index.js';
+export type PluginPackageDescriptor = {
+    format: 'easyai.plugin-package/v1' | 'easyai.plugin-package/v2';
+    manifest: PluginManifest;
+    runtime: {
+        nodeMajor: number;
+        capabilities: string[];
+        entry: string;
+        queries: string[];
+        handlers?: string[];
+    };
+    ui: {
+        entry: string;
+        globalName: string;
+        css?: string;
+    };
+    files: Record<string, string>;
+};
+export type InspectedPluginPackage = {
+    digest: string;
+    descriptor: PluginPackageDescriptor;
+    files: Map<string, Buffer>;
+};
+export type MaterializedPluginPackage = {
+    digest: string;
+    descriptor: PluginPackageDescriptor;
+    directory: string;
+};
+export type PluginPackageCall = {
+    operation: 'inspect' | 'query' | 'check' | 'resolve' | 'execute';
+    name?: string;
+    config?: Record<string, unknown>;
+    input?: Record<string, unknown>;
+    context?: PluginRuntimeContext;
+    request?: unknown;
+};
+export declare const PLUGIN_PACKAGE_MAX_BYTES: number;
+export declare function packageSha256(bytes: Buffer | string): string;
+export declare function inspectPluginPackage(bytes: Buffer): Promise<InspectedPluginPackage>;
+export declare function materializePluginPackage(pkg: InspectedPluginPackage, root: string): Promise<MaterializedPluginPackage>;
+export declare function invokePluginPackage(pkg: MaterializedPluginPackage, call: PluginPackageCall, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<any>;