@easyai-canvas/canvas-plugin-sdk 0.1.0

package/dist/studio/remote-connector.d.ts

@@ -0,0 +1,60 @@
+export declare function validatePlatformUrl(raw: string): string;
+export declare function allowedPluginRequest(method: string, path: string): boolean;
+export declare class RemoteStudioConnector {
+    private discovery?;
+    private platformOrigin;
+    private state;
+    private verifier;
+    private deviceId;
+    private credentials?;
+    private ticket?;
+    private socket?;
+    private reconnectTimer?;
+    private heartbeatTimer?;
+    private closed;
+    private phase;
+    private error;
+    status(): {
+        phase: "idle" | "authorizing" | "connecting" | "connected" | "disconnected";
+        error: string;
+        platformOrigin: string;
+        connectionId: string;
+        user: {
+            id: string;
+            name?: string;
+            username?: string;
+        } | null;
+    };
+    begin(rawPlatformUrl: string): Promise<{
+        authorizeUrl: string;
+        platformOrigin: string;
+    }>;
+    complete(code: string, state: string): Promise<{
+        phase: "idle" | "authorizing" | "connecting" | "connected" | "disconnected";
+        error: string;
+        platformOrigin: string;
+        connectionId: string;
+        user: {
+            id: string;
+            name?: string;
+            username?: string;
+        } | null;
+    }>;
+    private post;
+    private renewAccessToken;
+    openDebugSession(pluginId: string): Promise<{
+        sessionId: string;
+        projectId: string;
+        connectionId: string;
+        active: boolean;
+    }>;
+    createEmbedTicket(debugSessionId: string, codeChallenge: string): Promise<{
+        ticket: string;
+        expiresAt: string;
+    }>;
+    private openSocket;
+    private forward;
+    private uploadCatalogAssets;
+    private scheduleReconnect;
+    disconnect(): Promise<void>;
+}

package/dist/studio/remote-connector.js

@@ -0,0 +1,295 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+const CLIENT_ID = 'easyai:canvas-plugin-dev';
+const studioOrigin = () => `http://localhost:${Number(process.env.PORT ?? 4310)}`;
+const callbackUrl = () => `${studioOrigin()}/studio/oauth/callback`;
+const MAX_RPC_BODY_BYTES = 2_000_000;
+export function validatePlatformUrl(raw) {
+    const url = new URL(raw.trim());
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash ||
+        (url.protocol !== 'https:' && !(url.protocol === 'http:' &&
+            ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))))
+        throw new Error('请输入画布平台首页 HTTPS 地址；本机可使用 HTTP');
+    return url.origin;
+}
+export function allowedPluginRequest(method, path) {
+    if (method === 'GET' && path === '/v1/catalog')
+        return true;
+    if (method === 'POST' && /^\/v1\/plugins\/[A-Za-z0-9_.-]+\/(?:queries\/[A-Za-z0-9_.-]+|normalize)$/.test(path))
+        return true;
+    if (method === 'POST' && path === '/v1/executions')
+        return true;
+    if (method === 'GET' && /^\/v1\/executions\/[A-Za-z0-9_.-]+$/.test(path))
+        return true;
+    if (method === 'POST' && /^\/v1\/executions\/[A-Za-z0-9_.-]+\/cancel$/.test(path))
+        return true;
+    return false;
+}
+export class RemoteStudioConnector {
+    discovery;
+    platformOrigin = '';
+    state = '';
+    verifier = '';
+    deviceId = randomUUID();
+    credentials;
+    ticket;
+    socket;
+    reconnectTimer;
+    heartbeatTimer;
+    closed = true;
+    phase = 'idle';
+    error = '';
+    status() {
+        return { phase: this.phase, error: this.error, platformOrigin: this.platformOrigin,
+            connectionId: this.ticket?.connectionId || '', user: this.credentials?.user || null };
+    }
+    async begin(rawPlatformUrl) {
+        await this.disconnect();
+        this.platformOrigin = validatePlatformUrl(rawPlatformUrl);
+        const response = await fetch(`${this.platformOrigin}/.well-known/easyai-plugin-debug`, {
+            redirect: 'error', signal: AbortSignal.timeout(8000),
+        });
+        if (!response.ok)
+            throw new Error(`画布平台能力检查失败（${response.status}）`);
+        const discovery = await response.json();
+        if (discovery.protocol !== 'easyai.plugin-debug/v1' || !discovery.enabled)
+            throw new Error('此画布平台未开放插件调试');
+        const api = new URL(discovery.apiUrl);
+        const ws = new URL(discovery.wsUrl);
+        if (api.username || api.password || api.search || api.hash ||
+            (api.protocol !== 'https:' && !(api.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(api.hostname))) ||
+            (ws.protocol !== 'wss:' && !(ws.protocol === 'ws:' && ['localhost', '127.0.0.1', '[::1]'].includes(ws.hostname))) ||
+            discovery.workbenchOrigin !== studioOrigin())
+            throw new Error('画布平台调试地址配置无效');
+        this.discovery = discovery;
+        this.closed = false;
+        this.state = randomBytes(24).toString('base64url');
+        this.verifier = randomBytes(32).toString('base64url');
+        this.phase = 'authorizing';
+        const challenge = createHash('sha256').update(this.verifier).digest('base64url');
+        const authorize = new URL(`${api.toString().replace(/\/+$/, '')}/auth/client/authorize`);
+        for (const [key, value] of Object.entries({
+            response_type: 'code', client_id: CLIENT_ID, redirect_uri: callbackUrl(),
+            state: this.state, code_challenge: challenge, code_challenge_method: 'S256',
+            scope: 'plugin-debug:connect', agent_name: '画布插件开发工作台', agent_instance: this.deviceId,
+        }))
+            authorize.searchParams.set(key, value);
+        return { authorizeUrl: authorize.toString(), platformOrigin: this.platformOrigin };
+    }
+    async complete(code, state) {
+        if (!this.discovery || this.closed || this.phase !== 'authorizing' || !code || state !== this.state)
+            throw new Error('登录回调无效或已过期，请重新连接');
+        this.phase = 'connecting';
+        const credentials = await this.post('/auth/client/token', {
+            code, state, codeVerifier: this.verifier, redirectUri: callbackUrl(),
+            deviceId: this.deviceId, clientId: CLIENT_ID,
+        });
+        this.state = '';
+        this.verifier = '';
+        this.credentials = credentials;
+        this.ticket = await this.post('/canvas-workflow/plugin-debug-connectors', {}, true);
+        await this.openSocket();
+        return this.status();
+    }
+    async post(path, body, authenticated = false) {
+        if (!this.discovery)
+            throw new Error('尚未选择画布平台');
+        const response = await fetch(`${this.discovery.apiUrl.replace(/\/+$/, '')}${path}`, {
+            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(35_000),
+            headers: { 'content-type': 'application/json',
+                ...(authenticated && this.credentials ? { authorization: `Bearer ${this.credentials.accessToken}` } : {}) },
+            body: JSON.stringify(body),
+        });
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok)
+            throw new Error(data.message || data.error || `平台返回 ${response.status}`);
+        return data;
+    }
+    async renewAccessToken() {
+        if (!this.credentials)
+            throw new Error('开发授权已失效');
+        if (Date.parse(this.credentials.accessTokenExpiresAt) > Date.now() + 60_000)
+            return;
+        const next = await this.post('/auth/client/refresh', {
+            refreshToken: this.credentials.refreshToken, sessionId: this.credentials.sessionId,
+            deviceId: this.deviceId, clientId: CLIENT_ID,
+        });
+        this.credentials = next;
+    }
+    async openDebugSession(pluginId) {
+        if (!this.ticket || this.phase !== 'connected')
+            throw new Error('请先连接画布平台');
+        await this.renewAccessToken();
+        return this.post(`/canvas-workflow/plugin-debug-connectors/${this.ticket.connectionId}/open`, { pluginId }, true);
+    }
+    async createEmbedTicket(debugSessionId, codeChallenge) {
+        if (!this.ticket || this.phase !== 'connected')
+            throw new Error('请先连接画布平台');
+        await this.renewAccessToken();
+        return this.post(`/canvas-workflow/plugin-debug-connectors/${this.ticket.connectionId}/embed-ticket`, { debugSessionId, codeChallenge }, true);
+    }
+    async openSocket() {
+        if (!this.discovery || !this.ticket || this.closed)
+            return;
+        await this.renewAccessToken();
+        const fresh = await this.post(`/canvas-workflow/plugin-debug-connectors/${encodeURIComponent(this.ticket.connectionId)}/ticket`, {}, true);
+        this.ticket = fresh;
+        const url = new URL(this.discovery.wsUrl);
+        url.searchParams.set('channel', fresh.channel);
+        url.searchParams.set('client_id', fresh.clientId);
+        this.phase = 'connecting';
+        await new Promise((resolve, reject) => {
+            const socket = new WebSocket(url.toString());
+            this.socket = socket;
+            const timer = setTimeout(() => reject(new Error('WebSocket 连接超时')), 10_000);
+            const fail = (error) => { clearTimeout(timer); reject(error); };
+            socket.onmessage = (event) => {
+                let message;
+                try {
+                    message = JSON.parse(String(event.data));
+                }
+                catch {
+                    return;
+                }
+                if (message.type === 'session.challenge')
+                    socket.send(JSON.stringify({ type: 'session.initialize' }));
+                else if (message.type === 'session.initialized')
+                    socket.send(JSON.stringify({
+                        type: 'session.authenticate', method: 'ws_ticket', credential: fresh.ticket,
+                    }));
+                else if (message.type === 'session.ready') {
+                    clearTimeout(timer);
+                    this.phase = 'connected';
+                    this.error = '';
+                    this.heartbeatTimer = setInterval(() => {
+                        if (socket.readyState === WebSocket.OPEN)
+                            socket.send('ping');
+                    }, 25_000);
+                    resolve();
+                }
+                else if (message.type === 'plugin.debug.request')
+                    void this.forward(socket, message);
+                else if (message.type === 'session.error' || message.type === 'session.auth.rejected')
+                    fail(new Error(String(message.reason || 'WebSocket 授权失败')));
+            };
+            socket.onerror = () => fail(new Error('WebSocket 连接失败'));
+            socket.onclose = (event) => {
+                clearTimeout(timer);
+                if (this.heartbeatTimer)
+                    clearInterval(this.heartbeatTimer);
+                if (!this.closed) {
+                    this.phase = 'disconnected';
+                    this.error = `连接已断开（${event.code}${event.reason ? `：${event.reason}` : ''}），正在重连`;
+                    this.scheduleReconnect();
+                }
+            };
+        });
+    }
+    async forward(socket, message) {
+        if (!this.ticket || message.connectionId !== this.ticket.connectionId ||
+            typeof message.requestId !== 'string' || typeof message.replyNodeId !== 'string')
+            return;
+        const method = String(message.method || '');
+        const path = String(message.path || '');
+        let status = 400;
+        let body = { error: '插件调试请求不在允许范围内' };
+        if (allowedPluginRequest(method, path) &&
+            Buffer.byteLength(JSON.stringify(message.body ?? null)) <= MAX_RPC_BODY_BYTES) {
+            try {
+                const response = await fetch(`http://127.0.0.1:${Number(process.env.PORT ?? 4310)}${path}`, {
+                    method, redirect: 'error', signal: AbortSignal.timeout(24_000),
+                    headers: { 'content-type': 'application/json' },
+                    body: message.body === undefined ? undefined : JSON.stringify(message.body),
+                });
+                status = response.status;
+                const raw = await response.text();
+                if (Buffer.byteLength(raw) > 4_000_000)
+                    throw new Error('插件响应超过大小限制');
+                body = JSON.parse(raw);
+                if (response.ok && path === '/v1/catalog')
+                    await this.uploadCatalogAssets(body);
+            }
+            catch (error) {
+                status = 502;
+                body = { error: error.message || '本地插件请求失败' };
+            }
+        }
+        if (socket.readyState === WebSocket.OPEN)
+            socket.send(JSON.stringify({
+                type: 'plugin.debug.response', requestId: message.requestId,
+                connectionId: this.ticket.connectionId, replyNodeId: message.replyNodeId, status, body,
+            }));
+    }
+    async uploadCatalogAssets(catalog) {
+        if (!this.discovery || !this.ticket || !this.credentials ||
+            !catalog || typeof catalog !== 'object')
+            return;
+        const record = catalog;
+        const bundles = [record.uiBundle, ...((Array.isArray(record.plugins) ? record.plugins : [])
+                .map((plugin) => plugin?.uiBundle))].filter(Boolean);
+        const uploads = new Map();
+        for (const bundle of bundles) {
+            if (typeof bundle.digest === 'string' && typeof bundle.url === 'string')
+                uploads.set(bundle.digest, { url: bundle.url, mimeType: 'application/javascript' });
+            if (typeof bundle.cssDigest === 'string' && typeof bundle.cssUrl === 'string')
+                uploads.set(bundle.cssDigest, { url: bundle.cssUrl, mimeType: 'text/css' });
+        }
+        await this.renewAccessToken();
+        for (const [digest, asset] of uploads) {
+            if (!/^[a-f0-9]{64}$/.test(digest))
+                throw new Error('插件界面文件摘要无效');
+            const source = new URL(asset.url, `http://127.0.0.1:${Number(process.env.PORT ?? 4310)}`);
+            if (!['localhost', '127.0.0.1'].includes(source.hostname) ||
+                !['/ui/', '/packages/'].some(prefix => source.pathname.startsWith(prefix)) ||
+                source.search || source.hash)
+                throw new Error('插件界面文件地址无效');
+            const loaded = await fetch(`http://127.0.0.1:${Number(process.env.PORT ?? 4310)}${source.pathname}`, {
+                redirect: 'error', signal: AbortSignal.timeout(8000),
+            });
+            if (!loaded.ok)
+                throw new Error(`插件界面文件读取失败（${loaded.status}）`);
+            const bytes = Buffer.from(await loaded.arrayBuffer());
+            if (bytes.length > 5_000_000 || createHash('sha256').update(bytes).digest('hex') !== digest)
+                throw new Error('插件界面文件摘要不匹配或超过大小限制');
+            const uploaded = await fetch(`${this.discovery.apiUrl.replace(/\/+$/, '')}/canvas-workflow/plugin-debug-connectors/${this.ticket.connectionId}/assets/${digest}`, {
+                method: 'PUT', redirect: 'error', signal: AbortSignal.timeout(15_000),
+                headers: { authorization: `Bearer ${this.credentials.accessToken}`,
+                    'content-type': asset.mimeType, 'content-length': String(bytes.length) },
+                body: bytes,
+            });
+            if (!uploaded.ok) {
+                const reason = await uploaded.json().catch(() => ({}));
+                throw new Error(String(reason.message || `插件界面文件上传失败（${uploaded.status}）`));
+            }
+        }
+    }
+    scheduleReconnect() {
+        if (this.closed || this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.openSocket().catch((error) => {
+                this.error = error.message;
+                this.scheduleReconnect();
+            });
+        }, 2000);
+    }
+    async disconnect() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.socket?.close();
+        if (this.discovery && this.ticket && this.credentials) {
+            await fetch(`${this.discovery.apiUrl.replace(/\/+$/, '')}/canvas-workflow/plugin-debug-connectors/${this.ticket.connectionId}`, {
+                method: 'DELETE', headers: { authorization: `Bearer ${this.credentials.accessToken}` },
+                signal: AbortSignal.timeout(5000),
+            }).catch(() => undefined);
+        }
+        this.discovery = undefined;
+        this.credentials = undefined;
+        this.ticket = undefined;
+        this.phase = 'idle';
+        this.error = '';
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@easyai-canvas/canvas-plugin-sdk",
+  "version": "0.1.0",
+  "description": "EasyAI 画布插件开发工具与运行时",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.0 <23"
+  },
+  "bin": {
+    "easyai-plugin": "bin/easyai-plugin.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/sdk/index.d.ts",
+      "default": "./dist/sdk/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./ui": {
+      "types": "./dist/sdk/frontend.d.ts",
+      "default": "./dist/sdk/frontend.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "tools",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "better-sqlite3": "12.4.1",
+    "jszip": "3.10.1",
+    "vite": "8.3.1"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/tools/build-plugin-package.mjs

@@ -0,0 +1,99 @@
+import { build } from 'vite';
+import JSZip from 'jszip';
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export async function buildPluginPackage({
+  serverEntry,
+  uiEntry,
+  globalName,
+  output,
+}) {
+  const directory = resolve(output.replace(/\.zip$/, ''));
+  await build({
+    configFile: false,
+    publicDir: false,
+    ssr: { target: 'node', noExternal: true },
+    build: {
+      ssr: serverEntry,
+      outDir: directory,
+      emptyOutDir: true,
+      minify: false,
+      target: 'node22',
+      rollupOptions: {
+        output: { format: 'es', entryFileNames: 'server/plugin.mjs' },
+      },
+    },
+  });
+  const plugin = (
+    await import(pathToFileURL(resolve(directory, 'server/plugin.mjs')).href)
+  ).default;
+  await build({
+    configFile: false,
+    publicDir: false,
+    define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+    build: {
+      outDir: directory,
+      emptyOutDir: false,
+      cssCodeSplit: false,
+      lib: {
+        entry: uiEntry,
+        name: globalName,
+        formats: ['iife'],
+        fileName: () => 'ui/plugin.js',
+      },
+      rollupOptions: {
+        external: ['vue'],
+        output: { globals: { vue: 'EasyAIPluginHost.vue' } },
+      },
+    },
+  });
+  const zip = new JSZip();
+  const files = {};
+  const emitted = await readdir(directory, {
+    recursive: true,
+    withFileTypes: true,
+  });
+  let css;
+  for (const entry of emitted.filter((e) => e.isFile())) {
+    const name = resolve(entry.parentPath, entry.name)
+      .slice(directory.length + 1)
+      .replaceAll('\\', '/');
+    if (name.endsWith('.css')) {
+      if (css) throw new Error('插件包只支持单个合并后的样式入口');
+      css = name;
+    }
+    const bytes = await readFile(resolve(directory, name));
+    files[name] = createHash('sha256').update(bytes).digest('hex');
+    zip.file(name, bytes, { date: new Date('2026-01-01T00:00:00Z') });
+  }
+  const descriptor = {
+    format: 'easyai.plugin-package/v2',
+    manifest: plugin.manifest,
+    runtime: {
+      nodeMajor: 22,
+      capabilities: [
+        ...(plugin.manifest.contributes.nodes?.length ? ['nodes'] : []),
+        ...(plugin.manifest.contributes.actions?.length ? ['actions'] : []),
+        ...(Object.keys(plugin.queries ?? {}).length ? ['queries'] : []),
+      ],
+      entry: 'server/plugin.mjs',
+      queries: Object.keys(plugin.queries ?? {}),
+      handlers: Object.keys(plugin.handlers ?? {}),
+    },
+    ui: { entry: 'ui/plugin.js', globalName, ...(css ? { css } : {}) },
+    files,
+  };
+  zip.file('plugin.json', JSON.stringify(descriptor, null, 2), {
+    date: new Date('2026-01-01T00:00:00Z'),
+  });
+  await mkdir(dirname(resolve(output)), { recursive: true });
+  await writeFile(
+    output,
+    await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }),
+  );
+  console.log(`插件包：${output}`);
+  return output;
+}