@easyai-canvas/canvas-plugin-sdk 0.1.1 → 0.1.3

package/README.md

@@ -15,6 +15,8 @@ npm start
 
 `init --template node|action|combined` 选择项目类型；`--no-install` 跳过依赖安装。开发工作台位于 `http://localhost:4310/studio`，由浏览器完成 EasyAI 平台授权。`npm run build` 输出 `dist/plugin.zip`，可由管理员导入平台托管，或用 `npm start` 运行独立插件服务。
 
+运行 `npm run dev` 后，工作台会显示当前 SDK 与 npm 最新版本。若有新版本，点击“一键升级”会在当前项目执行固定版本安装，更新 `package.json` 和 npm 锁文件；安装完成后重启 `npm run dev`，新运行时才会生效。版本检查失败时仍可继续开发。
+
 平台托管只接纳运行不超过 20 秒的节点任务；需要长任务、GPU 或自有基础设施时使用独立服务。构建还会生成 `dist/plugin.zip.sha256` 供管理员核对。独立服务生产环境必须提供 `PLUGIN_SERVICE_SIGNING_SECRET`、与平台连接 ID 一致的 `PLUGIN_SERVICE_AUDIENCE` 和持久化的 `PLUGIN_DATA_DIR`。业务密钥放在插件配置或部署环境，不写入前端组件。
 
 托管节点暂不支持文件和画布宿主能力。管理员导入 ZIP 后默认停用，审核插件代码、声明能力和版本摘要后启用。版本切换不会改变已提交任务使用的包摘要。

package/bin/easyai-plugin.mjs

@@ -179,6 +179,7 @@ function serviceEnv(dev) {
   if (!dev && !process.env.PLUGIN_SERVICE_SIGNING_SECRET) fail('生产服务需要 PLUGIN_SERVICE_SIGNING_SECRET');
   return { ...process.env, NODE_ENV: dev ? 'development' : 'production',
     PLUGIN_BUILTINS: '0', PLUGIN_PACKAGES: JSON.stringify([zip]),
+    PLUGIN_SDK_VERSION: metadata.version,
     PLUGIN_DATA_DIR: process.env.PLUGIN_DATA_DIR ?? join(cwd, '.easyai-plugin'),
     ...(dev ? { PLUGIN_AUTH_MODE: 'local', PLUGIN_BIND: '127.0.0.1', PLUGIN_DEV_WATCH: '1' } : {}) };
 }

package/dist/customer-main.js

@@ -6,12 +6,14 @@ import { Runtime } from './runtime/engine.js';
 import { loadPackagedPlugins } from './runtime/packaged-plugins.js';
 import { authenticate } from './runtime/auth.js';
 import { RemoteStudioConnector } from './studio/remote-connector.js';
+import { SdkVersionManager } from './studio/sdk-version.js';
 import { ContractError, object, validatePluginRuntimeContext } from './protocol/index.js';
 const dataDir = resolve(process.env.PLUGIN_DATA_DIR ?? './.easyai-plugin');
 const port = Number(process.env.PORT ?? 4310);
 const packaged = await loadPackagedPlugins(JSON.parse(process.env.PLUGIN_PACKAGES ?? '[]'), join(dataDir, 'packages'));
 const runtime = new Runtime(join(dataDir, 'runtime.sqlite'), packaged.plugins, packaged.presentations, packaged.executionEntries);
 const studio = new RemoteStudioConnector();
+const sdkVersions = new SdkVersionManager(process.cwd(), process.env.PLUGIN_SDK_VERSION ?? '');
 if (process.env.PLUGIN_DEV_WATCH === '1') {
     for (const plugin of packaged.plugins) {
         const entry = runtime.catalog().plugins.find(item => item.manifest.id === plugin.manifest.id);
@@ -82,7 +84,8 @@ async function studioCatalog() {
 const server = createServer(async (request, response) => {
     try {
         const method = request.method ?? 'GET';
-        const path = new URL(request.url ?? '/', `http://localhost:${port}`).pathname;
+        const requestUrl = new URL(request.url ?? '/', `http://localhost:${port}`);
+        const path = requestUrl.pathname;
         const allowedOrigins = (process.env.PLUGIN_ALLOWED_ORIGINS ?? (process.env.NODE_ENV === 'production'
             ? '' : 'http://localhost:3000,http://127.0.0.1:3000')).split(',').map(s => s.trim()).filter(Boolean);
         if (request.headers.origin && allowedOrigins.includes(request.headers.origin)) {
@@ -177,6 +180,10 @@ const server = createServer(async (request, response) => {
         }
         if (path.startsWith('/studio')) {
             localStudio(request);
+            if (method === 'GET' && path === '/studio/') {
+                redirect(response, `/studio${requestUrl.search}`);
+                return;
+            }
             if (method === 'GET' && path === '/studio') {
                 if (request.headers.host?.startsWith('127.0.0.1:')) {
                     redirect(response, `http://localhost:${port}/studio`);
@@ -190,6 +197,23 @@ const server = createServer(async (request, response) => {
                 send(response, 200, await studioCatalog());
                 return;
             }
+            if (method === 'GET' && path === '/studio/sdk') {
+                send(response, 200, await sdkVersions.status());
+                return;
+            }
+            if (method === 'POST' && path === '/studio/sdk/upgrade') {
+                if (process.env.PLUGIN_DEV_WATCH !== '1' || request.headers.origin !== `http://localhost:${port}`)
+                    throw new ContractError('仅允许从本机开发工作台升级 SDK', 403);
+                if (studio.status().phase === 'connected')
+                    throw new ContractError('请先断开画布连接再升级 SDK', 409);
+                try {
+                    send(response, 200, await sdkVersions.upgrade());
+                }
+                catch {
+                    throw new ContractError('SDK 安装失败，请在项目终端手动安装并查看错误', 502);
+                }
+                return;
+            }
             if (method === 'GET' && path === '/studio/status') {
                 send(response, 200, studio.status());
                 return;

package/dist/studio/index.html

@@ -85,6 +85,13 @@ button:focus-visible, select:focus-visible, input:focus-visible, summary:focus-v
 .diagnostics-list .diag-error { color: var(--danger); }
 .diagnostics-list .diag-ready { color: var(--success); }
 .diagnostics-footnote { margin: 18px 0 0; color: var(--quiet); font-size: 11px; }
+.sdk-card { margin-top: 24px; padding: 14px 16px; border: 1px solid var(--line); border-radius: 12px; background: var(--soft); }
+.sdk-card[hidden] { display: none; }
+.sdk-card strong { display: block; margin-bottom: 4px; font-size: 12px; }
+.sdk-card p { margin: 0; color: var(--muted); font-size: 12px; line-height: 1.6; }
+.sdk-card button { margin-top: 10px; min-height: 34px; padding: 0 12px; border: 1px solid var(--line-strong); border-radius: 8px; color: var(--ink); background: #fff; font-size: 12px; font-weight: 600; }
+.sdk-card button[hidden] { display: none; }
+.sdk-card button:hover:not(:disabled) { background: var(--page); }
 
 /* Canvas controls */
 .dock { position: fixed; z-index: 3; left: 50%; bottom: 16px; transform: translateX(-50%); display: flex; align-items: center; gap: 3px; max-width: calc(100vw - 16px); padding: 5px; border: 1px solid var(--line-strong); border-radius: 13px; background: #fff; box-shadow: var(--floating-shadow); }
@@ -255,6 +262,7 @@ dialog::backdrop { background: #30384266; }
       <section class="setup-content" aria-labelledby="connection-title">
         <h1 id="connection-title">连接画布平台</h1>
         <p class="setup-intro">输入平台地址，在新窗口授权后进入私人调试画布。</p>
+        <div class="sdk-card" hidden><strong>画布插件 SDK</strong><p class="sdk-message" role="status" aria-live="polite"></p><button class="sdk-action" type="button" hidden>升级 SDK</button></div>
         <form id="connect-form"><label for="platform-address">画布平台地址</label><input id="platform-address" type="url" placeholder="https://canvas.example.com" autocomplete="url" aria-describedby="address-help" required><p id="address-help" class="field-help">线上平台使用 HTTPS，本机平台可使用 HTTP。</p><div class="form-actions"><button id="connect-button" type="submit" disabled><svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.5 10h11m-4-4 4 4-4 4M15.5 4h2v12h-2"/></svg><span>登录并连接</span></button></div></form>
         <p id="setup-status" role="status" aria-live="polite"></p>
       </section>
@@ -280,7 +288,7 @@ dialog::backdrop { background: #30384266; }
   <dialog id="panel" aria-labelledby="panel-title">
     <div class="dialog-head"><div><h2 id="panel-title">插件管理</h2><p>选择调试插件并下载可用的插件包</p></div><button id="close" type="button" aria-label="关闭管理面板"><svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true"><path d="M4.5 4.5 15.5 15.5M15.5 4.5 4.5 15.5"/></svg></button></div>
     <div class="dialog-body"><div class="dialog-main"><section class="target-section" aria-labelledby="target-title"><div class="section-heading"><h3 id="target-title">插件</h3><span id="panel-status" class="status-badge" role="status">正在连接</span></div><div id="plugin-list" class="plugin-list" role="radiogroup" aria-labelledby="target-title"></div><div class="plugin-actions"><button id="open-plugin" type="button"><svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 10h11m-4-4 4 4-4 4M16 4h2v12h-2"/></svg><span>在画布中调试</span></button><button id="download-package" type="button" disabled><svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 2.5v10m-3.5-3.5L10 12.5 13.5 9M3.5 14v2.5h13V14"/></svg><span id="download-label">下载插件包</span></button></div><p id="package-note" class="package-note" role="status" aria-live="polite"></p></section>
-      <section class="session-section" aria-labelledby="session-title"><div class="section-heading"><h3 id="session-title">当前会话</h3><span id="active-plugin" class="section-context"></span></div><dl class="session-summary"><div><dt>开发服务</dt><dd id="connection">—</dd></div><div><dt>当前构建</dt><dd id="build">—</dd></div><div><dt>调试画布</dt><dd id="project">—</dd></div></dl><details class="technical-details"><summary>查看连接详情</summary><dl><dt>连接 ID</dt><dd id="connection-id">—</dd><dt>构建摘要</dt><dd id="build-full">—</dd><dt>项目 ID</dt><dd id="project-id">—</dd></dl></details></section></div>
+      <section class="session-section" aria-labelledby="session-title"><div class="section-heading"><h3 id="session-title">当前会话</h3><span id="active-plugin" class="section-context"></span></div><dl class="session-summary"><div><dt>开发服务</dt><dd id="connection">—</dd></div><div><dt>当前构建</dt><dd id="build">—</dd></div><div><dt>调试画布</dt><dd id="project">—</dd></div></dl><div class="sdk-card" hidden><strong>画布插件 SDK</strong><p class="sdk-message" role="status" aria-live="polite"></p><button class="sdk-action" type="button" hidden>升级 SDK</button></div><details class="technical-details"><summary>查看连接详情</summary><dl><dt>连接 ID</dt><dd id="connection-id">—</dd><dt>构建摘要</dt><dd id="build-full">—</dd><dt>项目 ID</dt><dd id="project-id">—</dd></dl></details></section></div>
       <aside class="activity-section" aria-labelledby="activity-title"><div class="section-heading"><h3 id="activity-title">最近活动</h3><span id="activity-count" class="activity-count">0 条</span></div><p>当前工作台会话的连接与构建记录</p><div id="log" class="activity-list" role="log" aria-label="调试活动" aria-live="polite"></div></aside></div>
     <div class="dialog-actions"><button id="disconnect-panel" type="button">退出连接</button><div><button id="panel-cancel" type="button">关闭</button><button id="reconnect" class="primary" type="button"><svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M16.6 8.5A6.7 6.7 0 1 0 17 12M16.5 3.5v5h-5"/></svg><span>重新连接</span></button></div></div>
   </dialog>
@@ -290,6 +298,47 @@ dialog::backdrop { background: #30384266; }
       const $ = id => document.getElementById(id);
       const frame = $('canvas'), panel = $('panel'), dock = $('dock');
       let connectorStatus = null, connectAttemptError = '', localServiceAvailable = false, connectInProgress = false;
+      let sdkStatus = null, sdkBusy = false, sdkError = '';
+      function renderSdkStatus() {
+        const state = sdkStatus?.state;
+        const version = sdkStatus?.runningVersion || '未知';
+        const connected = connectorStatus?.phase === 'connected';
+        const message = sdkBusy ? '正在安装新版本并更新项目依赖，请稍候…'
+          : sdkError || (state === 'update' ? `当前运行 ${version}，npm 最新 ${sdkStatus.latestVersion}。${connected ? '请先断开画布连接再升级。' : '可以升级。'}`
+            : state === 'restart' ? `已安装 ${sdkStatus.installedVersion}，重启 npm run dev 后生效。`
+            : state === 'current' ? `当前运行 ${version}，已是最新版本。`
+            : state === 'error' ? sdkStatus.message : '');
+        for (const card of document.querySelectorAll('.sdk-card')) {
+          card.hidden = !state || state === 'unavailable';
+          card.querySelector('.sdk-message').textContent = message;
+          const button = card.querySelector('.sdk-action');
+          button.hidden = state !== 'update' && state !== 'error';
+          button.textContent = state === 'error' ? '重新检查' : connected ? '断开连接后升级' : '一键升级';
+          button.disabled = sdkBusy || connected && state === 'update';
+        }
+      }
+      async function loadSdkStatus() {
+        if (sdkBusy) return;
+        try {
+          const response = await fetch('/studio/sdk', { cache: 'no-store' });
+          if (!response.ok) throw new Error('无法读取 SDK 版本');
+          sdkStatus = await response.json(); sdkError = '';
+        } catch { sdkStatus = { state: 'error', message: '无法读取 SDK 版本，请检查本地服务。' }; }
+        renderSdkStatus();
+      }
+      for (const button of document.querySelectorAll('.sdk-action')) button.addEventListener('click', async () => {
+        if (sdkStatus?.state === 'error') { await loadSdkStatus(); return; }
+        if (sdkStatus?.state !== 'update' || sdkBusy) return;
+        sdkBusy = true; sdkError = ''; renderSdkStatus();
+        try {
+          const response = await fetch('/studio/sdk/upgrade', { method: 'POST' });
+          const result = await response.json();
+          if (!response.ok) throw new Error(result.error || '升级失败');
+          sdkStatus = result;
+        } catch (error) { sdkError = `${error.message}。可在终端手动运行 npm install --save-exact @easyai-canvas/canvas-plugin-sdk@latest。`; }
+        finally { sdkBusy = false; renderSdkStatus(); }
+      });
+      void loadSdkStatus(); setInterval(loadSdkStatus, 10 * 60_000);
       try { $('platform-address').value = localStorage.getItem('plugin-debug-platform-url') || ''; } catch {}
       $('diag-local').textContent = window.location.host;
       function renderTargetAddress(raw = $('platform-address').value) {
@@ -326,6 +375,7 @@ dialog::backdrop { background: #30384266; }
           const response = await fetch('/studio/status', { cache: 'no-store' });
           if (!response.ok) throw new Error('本地服务状态读取失败');
           connectorStatus = await response.json();
+          renderSdkStatus();
           setLocalServiceState('ready');
           const targetAddress = connectorStatus.phase === 'idle' ? $('platform-address').value : connectorStatus.platformOrigin || $('platform-address').value;
           renderTargetAddress(targetAddress);

package/dist/studio/sdk-version.d.ts

@@ -0,0 +1,74 @@
+export declare const SDK_NAME = "@easyai-canvas/canvas-plugin-sdk";
+type Runner = (args: string[], cwd: string, timeout: number) => Promise<string>;
+export declare function compareVersions(left: string, right: string): number | null;
+export declare class SdkVersionManager {
+    private readonly projectDir;
+    private readonly runningVersion;
+    private readonly run;
+    private latest;
+    private checkedAt;
+    private checking;
+    private upgrading;
+    constructor(projectDir: string, runningVersion: string, run?: Runner);
+    private packageVersion;
+    private latestVersion;
+    status(): Promise<{
+        state: "unavailable";
+        runningVersion: string;
+        installedVersion?: undefined;
+        declared?: undefined;
+        latestVersion?: undefined;
+        message?: undefined;
+    } | {
+        state: "restart";
+        runningVersion: string;
+        installedVersion: string;
+        declared: string;
+        latestVersion?: undefined;
+        message?: undefined;
+    } | {
+        state: "update" | "current";
+        runningVersion: string;
+        installedVersion: string;
+        latestVersion: string;
+        declared: string;
+        message?: undefined;
+    } | {
+        state: "error";
+        runningVersion: string;
+        installedVersion: string;
+        declared: string;
+        message: string;
+        latestVersion?: undefined;
+    }>;
+    upgrade(): Promise<{
+        state: "unavailable";
+        runningVersion: string;
+        installedVersion?: undefined;
+        declared?: undefined;
+        latestVersion?: undefined;
+        message?: undefined;
+    } | {
+        state: "restart";
+        runningVersion: string;
+        installedVersion: string;
+        declared: string;
+        latestVersion?: undefined;
+        message?: undefined;
+    } | {
+        state: "update" | "current";
+        runningVersion: string;
+        installedVersion: string;
+        latestVersion: string;
+        declared: string;
+        message?: undefined;
+    } | {
+        state: "error";
+        runningVersion: string;
+        installedVersion: string;
+        declared: string;
+        message: string;
+        latestVersion?: undefined;
+    }>;
+}
+export {};

package/dist/studio/sdk-version.js

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+export const SDK_NAME = '@easyai-canvas/canvas-plugin-sdk';
+async function npm(args, cwd, timeout) {
+    const { stdout } = await execute('npm', args, { cwd, timeout, maxBuffer: 1024 * 1024 });
+    return stdout.trim();
+}
+function versionParts(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+    return match ? match.slice(1).map(Number) : null;
+}
+export function compareVersions(left, right) {
+    const a = versionParts(left);
+    const b = versionParts(right);
+    if (!a || !b)
+        return null;
+    for (let index = 0; index < 3; index++) {
+        if (a[index] !== b[index])
+            return Math.sign(a[index] - b[index]);
+    }
+    return 0;
+}
+export class SdkVersionManager {
+    projectDir;
+    runningVersion;
+    run;
+    latest = null;
+    checkedAt = 0;
+    checking = null;
+    upgrading = false;
+    constructor(projectDir, runningVersion, run = npm) {
+        this.projectDir = projectDir;
+        this.runningVersion = runningVersion;
+        this.run = run;
+    }
+    async packageVersion(path) {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    async latestVersion() {
+        if (this.latest && Date.now() - this.checkedAt < 10 * 60_000)
+            return this.latest;
+        if (!this.checking) {
+            this.checking = this.run(['view', `${SDK_NAME}@latest`, 'version', '--json', '--fetch-retries=0'], this.projectDir, 8000)
+                .then(output => {
+                const version = JSON.parse(output);
+                if (typeof version !== 'string' || !versionParts(version))
+                    throw new Error('npm 返回了无效的 SDK 版本');
+                this.latest = version;
+                this.checkedAt = Date.now();
+                return version;
+            }).finally(() => { this.checking = null; });
+        }
+        return this.checking;
+    }
+    async status() {
+        const project = await this.packageVersion(join(this.projectDir, 'package.json'));
+        const declared = project?.dependencies?.[SDK_NAME] ?? project?.devDependencies?.[SDK_NAME];
+        if (!declared)
+            return { state: 'unavailable', runningVersion: this.runningVersion };
+        const installed = await this.packageVersion(join(this.projectDir, 'node_modules', SDK_NAME, 'package.json'));
+        const installedVersion = installed?.version ?? this.runningVersion;
+        if (compareVersions(installedVersion, this.runningVersion) === 1)
+            return { state: 'restart', runningVersion: this.runningVersion, installedVersion, declared };
+        try {
+            const latestVersion = await this.latestVersion();
+            return { state: compareVersions(installedVersion, latestVersion) === -1 ? 'update' : 'current',
+                runningVersion: this.runningVersion, installedVersion, latestVersion, declared };
+        }
+        catch {
+            return { state: 'error', runningVersion: this.runningVersion, installedVersion, declared,
+                message: '暂时无法查询 npm 最新版本，请检查网络或 npm 仓库配置。' };
+        }
+    }
+    async upgrade() {
+        if (this.upgrading)
+            throw new Error('SDK 正在升级，请稍后再试');
+        this.upgrading = true;
+        try {
+            const status = await this.status();
+            if (status.state === 'unavailable')
+                throw new Error('当前项目没有声明 SDK 依赖');
+            if (status.state === 'error')
+                throw new Error(status.message);
+            if (status.state !== 'update')
+                return status;
+            await this.run(['install', '--save-exact', `${SDK_NAME}@${status.latestVersion}`], this.projectDir, 120_000);
+            return this.status();
+        }
+        finally {
+            this.upgrading = false;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyai-canvas/canvas-plugin-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "EasyAI 画布插件开发工具与运行时",
   "type": "module",
   "engines": {