@easyai-canvas/canvas-plugin-sdk 0.1.2 → 0.1.4

package/README.md

@@ -13,9 +13,15 @@ npm run build
 npm start
 ```
 
-`init --template node|action|combined` 选择项目类型；`--no-install` 跳过依赖安装。开发工作台位于 `http://localhost:4310/studio`，由浏览器完成 EasyAI 平台授权。`npm run build` 输出 `dist/plugin.zip`，可由管理员导入平台托管，或用 `npm start` 运行独立插件服务。
+`init --template node|action|combined` 选择首个插件模板；`--no-install` 跳过依赖安装。新项目将插件放在 `src/plugins/<目录>/`，用 `npx easyai-plugin add <目录> --template node|action|combined` 增加独立插件。每个目录拥有独立 ID、配置、UI 和 ZIP；同一插件的多个节点可继续放在该目录内。旧项目的 `src/plugin.ts`、`src/ui.ts` 与 `dist/plugin.zip` 仍可使用。
 
-平台托管只接纳运行不超过 20 秒的节点任务；需要长任务、GPU 或自有基础设施时使用独立服务。构建还会生成 `dist/plugin.zip.sha256` 供管理员核对。独立服务生产环境必须提供 `PLUGIN_SERVICE_SIGNING_SECRET`、与平台连接 ID 一致的 `PLUGIN_SERVICE_AUDIENCE` 和持久化的 `PLUGIN_DATA_DIR`。业务密钥放在插件配置或部署环境，不写入前端组件。
+开发工作台位于 `http://localhost:4310/studio`，按插件展示配置表单和待配置状态。`npm run build` 为新结构分别输出 `dist/plugins/<pluginId>.zip` 与摘要文件；管理员可分别导入，或用 `npm start` 运行同一服务下的多个插件。
+
+节点在 `contributes.nodes[].placement` 声明 `{ slot: 'canvas.add.node', group: 'tools', order: 100 }`，素材选择操作在 `contributes.actions[].placement` 声明 `{ slot: 'canvas.add.resource', order: 100 }`。节点分组还可选 `basic`、`storyboard`；素材入口不使用节点分组。插件的 Vue 组件负责内部样式与交互，画布负责添加入口及拖动、权限等边界。旧版 `menu` 声明继续可用；未知位置或贡献能力与位置不匹配会在打包校验时报错。
+
+运行 `npm run dev` 后，工作台会显示当前 SDK 与 npm 最新版本。若有新版本，点击“一键升级”会在当前项目执行固定版本安装，更新 `package.json` 和 npm 锁文件；安装完成后重启 `npm run dev`，新运行时才会生效。版本检查失败时仍可继续开发。
+
+平台托管只接纳运行不超过 20 秒的节点任务；需要长任务、GPU 或自有基础设施时使用独立服务。构建还会生成每个 ZIP 的 `.sha256` 供管理员核对。独立服务生产环境必须提供 `PLUGIN_SERVICE_SIGNING_SECRET`、与平台连接 ID 一致的 `PLUGIN_SERVICE_AUDIENCE` 和持久化的 `PLUGIN_DATA_DIR`。业务密钥放在插件配置或部署环境，不写入前端组件。
 
 托管节点暂不支持文件和画布宿主能力。管理员导入 ZIP 后默认停用，审核插件代码、声明能力和版本摘要后启用。版本切换不会改变已提交任务使用的包摘要。
 

package/bin/easyai-plugin.mjs

@@ -2,7 +2,7 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, watch } from 'node:fs';
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import net from 'node:net';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -40,11 +40,12 @@ export default definePlugin({
         inputs: [], outputs: [{ id: 'out', type: 'text' }],
         parameters: [{ key: 'text', label: '文本', type: 'string', default: '你好，画布' }],
         ui: { preview: 'EchoPreview', panel: 'EchoPanel' }, timeoutMs: 20000,
+        placement: { slot: 'canvas.add.node', group: 'tools' },
       })],` : ''}
       ${action ? `actions: [{
         id: 'select-image', name: '添加图片链接', action: 'asset-selection',
         presentation: 'dialog', mediaTypes: ['image'], maxCount: 1,
-        ui: { component: 'ImageSelector' }, menu: { group: 'resources' },
+        ui: { component: 'ImageSelector' }, placement: { slot: 'canvas.add.resource' },
       }],` : ''}
     },
   },
@@ -92,12 +93,12 @@ ${action ? `export const ImageSelector = defineComponent({ setup() {
 } });` : ''}
 `;
 }
-function testSource(id, template) {
+function testSource(id, template, directory) {
   const node = template !== 'action';
   const action = template !== 'node';
   return `import test from 'node:test';
 import assert from 'node:assert/strict';
-import plugin from '../src/plugin.ts';
+import plugin from '../src/plugins/${directory}/plugin.ts';
 import { validateManifest, validateResult } from '${metadata.name}/protocol';
 
 test('插件声明和业务处理器符合画布契约', async () => {
@@ -125,7 +126,7 @@ async function init() {
   const slug = safeName(basename(target));
   const id = `customer.${slug.replaceAll('-', '.')}`;
   const title = slug.replaceAll('-', ' ');
-  await mkdir(join(target, 'src'), { recursive: true });
+  await mkdir(join(target, 'src/plugins', slug), { recursive: true });
   await mkdir(join(target, 'test'), { recursive: true });
   const spec = process.env.EASYAI_SDK_INSTALL_SPEC ?? metadata.version;
   const project = {
@@ -137,13 +138,13 @@ async function init() {
   };
   const files = {
     'package.json': `${JSON.stringify(project, null, 2)}\n`,
-    'src/plugin.ts': pluginSource(id, title, template),
-    'src/ui.ts': uiSource(template),
-    'test/plugin.test.ts': testSource(id, template),
+    [`src/plugins/${slug}/plugin.ts`]: pluginSource(id, title, template),
+    [`src/plugins/${slug}/ui.ts`]: uiSource(template),
+    [`test/${slug}.test.ts`]: testSource(id, template, slug),
     '.gitignore': 'node_modules/\ndist/\n.easyai-plugin/\n.env\n',
     '.env.example': 'PORT=4310\nPLUGIN_DATA_DIR=./.easyai-plugin\nPLUGIN_AUTH_MODE=token\nPLUGIN_SERVICE_AUDIENCE=customer-plugin\n# PLUGIN_SERVICE_SIGNING_SECRET=由部署环境安全注入\n',
-    'Dockerfile': 'FROM node:22.22.0\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --omit=dev\nCOPY dist/plugin.zip ./dist/plugin.zip\nENV NODE_ENV=production PLUGIN_BUILTINS=0\nCMD ["npm", "start"]\n',
-    'README.md': `# ${title}\n\n运行 npm run dev，打开 http://localhost:4310/studio，在浏览器中连接 EasyAI 画布。\n运行 npm run test:contract && npm run build 生成 dist/plugin.zip 和 dist/plugin.zip.sha256。\n独立部署时配置插件服务签名密钥并运行 npm start；平台托管时由管理员审核并导入 ZIP。\n`,
+    'Dockerfile': 'FROM node:22.22.0\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --omit=dev\nCOPY dist/plugins ./dist/plugins\nENV NODE_ENV=production PLUGIN_BUILTINS=0\nCMD ["npm", "start"]\n',
+    'README.md': `# ${title}\n\n每个插件放在 src/plugins/<目录>/，用 easyai-plugin add <目录> 增加独立插件。\n运行 npm run dev，打开 http://localhost:4310/studio，在浏览器中连接 EasyAI 画布。\n运行 npm run test:contract && npm run build，分别生成 dist/plugins/<pluginId>.zip。\n独立部署时配置插件服务签名密钥并运行 npm start；平台托管时由管理员审核并分别导入 ZIP。\n`,
     'tsconfig.json': JSON.stringify({ compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', strict: true, skipLibCheck: true, allowImportingTsExtensions: true, lib: ['ES2022', 'DOM'], types: ['node'], noEmit: true }, include: ['src/**/*.ts', 'test/**/*.ts'] }, null, 2) + '\n',
   };
   for (const [path, content] of Object.entries(files)) await writeFile(join(target, path), content, { flag: 'wx' });
@@ -158,33 +159,77 @@ async function run(executable, argv, directory = cwd, env = process.env) {
     child.once('exit', code => code === 0 ? resolvePromise() : reject(new Error(`${executable} 退出码 ${code}`)));
   });
 }
+function templateArg() {
+  return args.find(arg => arg.startsWith('--template='))?.slice('--template='.length)
+    ?? (args.includes('--template') ? args[args.indexOf('--template') + 1] : 'node');
+}
+async function add() {
+  const template = templateArg();
+  if (!['node', 'action', 'combined'].includes(template)) fail('模板只支持 node、action 或 combined');
+  const directory = args.find((arg, index) => !arg.startsWith('--') && args[index - 1] !== '--template');
+  if (!directory) fail('用法：easyai-plugin add <插件目录> [--template node|action|combined]');
+  const slug = safeName(directory);
+  if (slug !== directory) fail('插件目录只能使用小写英文字母、数字和短横线');
+  const path = join(cwd, 'src/plugins', slug);
+  if (existsSync(path)) fail(`插件目录已存在：${path}`);
+  await mkdir(path, { recursive: true });
+  await mkdir(join(cwd, 'test'), { recursive: true });
+  const id = `customer.${slug.replaceAll('-', '.')}`;
+  await writeFile(join(path, 'plugin.ts'), pluginSource(id, slug.replaceAll('-', ' '), template), { flag: 'wx' });
+  await writeFile(join(path, 'ui.ts'), uiSource(template), { flag: 'wx' });
+  await writeFile(join(cwd, 'test', `${slug}.test.ts`), testSource(id, template, slug), { flag: 'wx' });
+  console.log(`已添加插件 ${id}；运行 npm run test:contract && npm run build`);
+}
+async function pluginEntries() {
+  const root = join(cwd, 'src/plugins');
+  const folders = existsSync(root) ? (await readdir(root, { withFileTypes: true }))
+    .filter(item => item.isDirectory()).map(item => item.name).sort() : [];
+  const entries = folders.map(name => ({ name, server: join(root, name, 'plugin.ts'), ui: join(root, name, 'ui.ts'), legacy: false }));
+  if (existsSync(join(cwd, 'src/plugin.ts'))) entries.push({ name: 'plugin', server: join(cwd, 'src/plugin.ts'), ui: join(cwd, 'src/ui.ts'), legacy: true });
+  if (!entries.length) fail('缺少插件入口：src/plugins/<目录>/plugin.ts 或 src/plugin.ts');
+  for (const entry of entries) for (const path of [entry.server, entry.ui]) if (!existsSync(path)) fail(`缺少 ${path}`);
+  return entries;
+}
 async function build() {
   nodeVersion();
-  for (const path of ['src/plugin.ts', 'src/ui.ts']) if (!existsSync(join(cwd, path))) fail(`缺少 ${path}`);
+  const entries = await pluginEntries();
   const { buildPluginPackage } = await import(builderEntry);
-  const output = join(cwd, 'dist/plugin.zip');
-  await buildPluginPackage({ serverEntry: join(cwd, 'src/plugin.ts'), uiEntry: join(cwd, 'src/ui.ts'),
-    globalName: `EasyAIPlugin${createHash('sha256').update(cwd).digest('hex').slice(0, 12)}`, output });
-  const bytes = await readFile(output);
   const { inspectPluginPackage } = await import(join(packageRoot, 'dist/runtime/package-runtime.js'));
-  await inspectPluginPackage(bytes);
-  const digest = createHash('sha256').update(bytes).digest('hex');
-  await writeFile(`${output}.sha256`, `${digest}  plugin.zip\n`);
-  console.log(`SHA-256 ${digest}（dist/plugin.zip.sha256）`);
+  await rm(join(cwd, 'dist/plugins'), { recursive: true, force: true });
+  const ids = new Set();
+  for (const entry of entries) {
+    const temporary = join(cwd, 'dist/plugins', `${entry.name}.zip`);
+    await buildPluginPackage({ serverEntry: entry.server, uiEntry: entry.ui,
+      globalName: `EasyAIPlugin${createHash('sha256').update(`${cwd}/${entry.name}`).digest('hex').slice(0, 12)}`, output: temporary });
+    const bytes = await readFile(temporary);
+    const inspected = await inspectPluginPackage(bytes);
+    const id = inspected.descriptor.manifest.id;
+    if (ids.has(id)) fail(`插件 ID 重复：${id}`);
+    ids.add(id);
+    const output = entry.legacy ? join(cwd, 'dist/plugin.zip') : join(cwd, 'dist/plugins', `${id}.zip`);
+    if (output !== temporary) await rename(temporary, output);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    await writeFile(`${output}.sha256`, `${digest}  ${basename(output)}\n`);
+    console.log(`${id} → ${output}（SHA-256 ${digest}）`);
+  }
 }
-function serviceEnv(dev) {
-  const zip = join(cwd, 'dist/plugin.zip');
-  if (!existsSync(zip)) fail('缺少 dist/plugin.zip；请先运行 npm run build');
+async function serviceEnv(dev) {
+  const entries = await pluginEntries();
+  const folder = join(cwd, 'dist/plugins');
+  const zips = existsSync(folder) ? (await readdir(folder)).filter(name => name.endsWith('.zip')).map(name => join(folder, name)) : [];
+  if (entries.some(entry => entry.legacy)) zips.push(join(cwd, 'dist/plugin.zip'));
+  if (!zips.length || zips.some(zip => !existsSync(zip))) fail('缺少插件 ZIP；请先运行 npm run build');
   if (!existsSync(runtimeEntry)) fail('SDK 运行时未构建');
   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_BUILTINS: '0', PLUGIN_PACKAGES: JSON.stringify(zips),
+    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' } : {}) };
 }
 async function start() {
   nodeVersion();
-  await run(process.execPath, [runtimeEntry], cwd, serviceEnv(false));
+  await run(process.execPath, [runtimeEntry], cwd, await serviceEnv(false));
 }
 async function dev() {
   await build();
@@ -194,9 +239,10 @@ async function dev() {
   const status = async (state, message = '') => writeFile(join(dataDir, 'dev-build-status.json'),
     JSON.stringify({ state, message: message.slice(0, 500), updatedAt: new Date().toISOString() }));
   const launch = () => {
-    child = spawn(process.execPath, [runtimeEntry], { cwd, env: serviceEnv(true), stdio: 'inherit' });
+    child = spawn(process.execPath, [runtimeEntry], { cwd, env: launchEnv, stdio: 'inherit' });
     child.on('error', error => console.error(error));
   };
+  let launchEnv = await serviceEnv(true);
   await status('ready');
   launch();
   console.log(`真实画布调试工作台：http://localhost:${process.env.PORT ?? 4310}/studio`);
@@ -210,6 +256,7 @@ async function dev() {
       await status('building');
       try {
         await build();
+        launchEnv = await serviceEnv(true);
         child?.kill('SIGTERM');
         await new Promise(resolvePromise => child?.once('exit', resolvePromise));
         launch();
@@ -234,8 +281,9 @@ async function doctor() {
   const checks = [];
   const [major, minor] = process.versions.node.split('.').map(Number);
   checks.push({ name: 'Node 22.22+', ok: major === 22 && minor >= 22 });
-  checks.push({ name: '插件入口', ok: existsSync(join(cwd, 'src/plugin.ts')) });
-  checks.push({ name: 'UI 入口', ok: existsSync(join(cwd, 'src/ui.ts')) });
+  const entries = await pluginEntries().catch(() => []);
+  checks.push({ name: `插件入口（${entries.length} 个）`, ok: entries.length > 0 });
+  checks.push({ name: '插件 ID 唯一', ok: entries.length > 0 && (await build().then(() => true).catch(() => false)) });
   const port = Number(process.env.PORT ?? 4310);
   const available = await new Promise(resolvePromise => {
     const server = net.createServer();
@@ -255,12 +303,13 @@ async function doctor() {
 
 try {
   if (command === 'init') await init();
+  else if (command === 'add') await add();
   else if (command === 'dev') await dev();
   else if (command === 'test:contract') await contractTest();
   else if (command === 'build') await build();
   else if (command === 'start') await start();
   else if (command === 'doctor') await doctor();
-  else fail('用法：easyai-plugin <init|dev|test:contract|build|start|doctor>');
+  else fail('用法：easyai-plugin <init|add|dev|test:contract|build|start|doctor>');
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));
   process.exitCode = 1;

package/dist/customer-main.js

@@ -6,16 +6,18 @@ 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);
-        if (entry && !entry.enabled)
+        if (entry && !entry.enabled && !(entry.manifest.configFields ?? []).some(field => field.required && !(field.type === 'secret' ? entry.secretConfigured?.[field.key] : entry.config[field.key] !== undefined && entry.config[field.key] !== '')))
             runtime.configure(plugin.manifest.id, { enabled: true });
     }
 }
@@ -71,6 +73,10 @@ async function studioCatalog() {
             return {
                 id: entry.manifest.id, name: entry.manifest.name, release: entry.manifest.release,
                 enabled: entry.enabled, manifest: entry.manifest, uiBundle,
+                config: entry.config, secretConfigured: entry.secretConfigured,
+                configCheckAvailable: entry.configCheckAvailable,
+                configurationRequired: (entry.manifest.configFields ?? []).some(field => field.required &&
+                    !(field.type === 'secret' ? entry.secretConfigured?.[field.key] : entry.config[field.key] !== undefined && entry.config[field.key] !== '')),
                 nodes: entry.manifest.contributes.nodes?.length ?? 0,
                 actions: entry.manifest.contributes.actions?.length ?? 0,
                 package: packaged.downloads[entry.manifest.id] ? { mode: 'download' } : null,
@@ -195,6 +201,38 @@ const server = createServer(async (request, response) => {
                 send(response, 200, await studioCatalog());
                 return;
             }
+            const studioPlugin = /^\/studio\/plugins\/([A-Za-z0-9_.-]+)\/(configure|check)$/.exec(path);
+            if (method === 'POST' && studioPlugin) {
+                if (request.headers.origin && ![`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`].includes(request.headers.origin))
+                    throw new ContractError('本地配置请求来源无效', 403);
+                if (studioPlugin[2] === 'configure') {
+                    const input = await body(request);
+                    const configured = runtime.configure(studioPlugin[1], {
+                        config: object(input.config, 'config'), enabled: input.enabled === true,
+                    });
+                    send(response, 200, { enabled: configured.enabled });
+                }
+                else
+                    send(response, 200, await runtime.checkConfig(studioPlugin[1]));
+                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/protocol/index.d.ts

@@ -50,6 +50,23 @@ export type PluginMenuContribution = {
     order?: number;
     icon?: string;
 };
+export type NodePlacement = {
+    slot: 'canvas.add.node';
+    group?: 'basic' | 'storyboard' | 'tools';
+    order?: number;
+    icon?: string;
+};
+export type ResourcePlacement = {
+    slot: 'canvas.add.resource';
+    order?: number;
+    icon?: string;
+};
+export type PlacementOverride = {
+    visible?: boolean;
+    group?: 'basic' | 'storyboard' | 'tools';
+    order?: number;
+};
+export type PlacementOverrides = Record<string, PlacementOverride>;
 /** Platform-derived identity and location, shared by backend node handlers and queries. Never accepts a login token. */
 export type PluginRuntimeContext = {
     user: {
@@ -100,6 +117,7 @@ export type NodeDefinition = {
     defaults?: Record<string, unknown>;
     timeoutMs?: number;
     menu?: PluginMenuContribution;
+    placement?: NodePlacement;
     capabilities?: PluginNodeCapabilities;
     runtime?: PluginNodeRuntimePolicy;
 };
@@ -128,7 +146,8 @@ export type PluginAction = {
         url?: string;
         origin?: string;
     };
-    menu: PluginMenuContribution;
+    menu?: PluginMenuContribution;
+    placement?: ResourcePlacement;
     /** Set only on the normalized view returned by listPluginActions(). */
     legacyAssetSource?: boolean;
 };
@@ -252,6 +271,7 @@ export type HostSnapshot = {
         serviceId: string;
         entry: CatalogEntry;
         enabled: boolean;
+        placementOverrides?: PlacementOverrides;
         uiBundle?: {
             url: string;
             digest: string;
@@ -268,6 +288,8 @@ export declare class ContractError extends Error {
 }
 export declare function object(value: unknown, path?: string): Record<string, unknown>;
 export declare function validatePluginRuntimeContext(value: unknown): PluginRuntimeContext;
+export declare function resolveNodePlacement(node: NodeDefinition): NodePlacement | null;
+export declare function resolveResourcePlacement(action: PluginAction): ResourcePlacement | null;
 export declare function identifier(value: unknown, path: string): string;
 export declare function validateParameters(fields: ConfigField[], input: Record<string, unknown>): Record<string, unknown>;
 /** Returns the interaction-oriented view while preserving legacy asset source manifests. */

package/dist/protocol/index.js

@@ -62,6 +62,41 @@ function validateMenu(value, path) {
     if (menu.icon !== undefined && typeof menu.icon !== 'string')
         throw new ContractError(`${path} 菜单图标无效`);
 }
+function validatePlacement(value, path, slot) {
+    if (value === undefined)
+        return;
+    const placement = keys(value, ['slot', 'group', 'order', 'icon'], path);
+    if (placement.slot !== slot)
+        throw new ContractError(`${path} 位置与贡献类型不匹配`);
+    if (slot === 'canvas.add.node') {
+        if (placement.group !== undefined && !['basic', 'storyboard', 'tools'].includes(String(placement.group)))
+            throw new ContractError(`${path} 节点分组无效`);
+    }
+    else if (placement.group !== undefined)
+        throw new ContractError(`${path} 素材入口不能设置节点分组`);
+    if (placement.order !== undefined && (typeof placement.order !== 'number' || !Number.isFinite(placement.order)))
+        throw new ContractError(`${path} 顺序无效`);
+    if (placement.icon !== undefined && typeof placement.icon !== 'string')
+        throw new ContractError(`${path} 图标无效`);
+}
+export function resolveNodePlacement(node) {
+    if (node.placement)
+        return { ...node.placement, group: node.placement.group ?? 'tools' };
+    if (node.menu?.group === 'resources')
+        return null;
+    return { slot: 'canvas.add.node', group: node.menu?.group ?? 'tools',
+        ...(node.menu?.order !== undefined ? { order: node.menu.order } : {}),
+        ...(node.menu?.icon !== undefined ? { icon: node.menu.icon } : {}) };
+}
+export function resolveResourcePlacement(action) {
+    if (action.placement)
+        return action.placement;
+    if (action.menu && action.menu.group !== 'resources')
+        return null;
+    return { slot: 'canvas.add.resource',
+        ...(action.menu?.order !== undefined ? { order: action.menu.order } : {}),
+        ...(action.menu?.icon !== undefined ? { icon: action.menu.icon } : {}) };
+}
 function optionalBoolean(value, path) {
     if (value !== undefined && typeof value !== 'boolean')
         throw new ContractError(`${path} 必须是布尔值`);
@@ -182,7 +217,7 @@ export function validateManifest(value) {
             throw new ContractError('nodes 必须为数组');
         const names = new Set();
         for (const raw of c.nodes) {
-            const node = keys(raw, ['type', 'name', 'description', 'inputs', 'outputs', 'parameters', 'execution', 'ui', 'defaults', 'timeoutMs', 'menu', 'capabilities', 'runtime'], 'node');
+            const node = keys(raw, ['type', 'name', 'description', 'inputs', 'outputs', 'parameters', 'execution', 'ui', 'defaults', 'timeoutMs', 'menu', 'placement', 'capabilities', 'runtime'], 'node');
             const id = identifier(node.type, 'node.type');
             if (names.has(id))
                 throw new ContractError('节点标识重复');
@@ -192,6 +227,7 @@ export function validateManifest(value) {
             if (node.parameters !== undefined)
                 validateFields(node.parameters);
             validateMenu(node.menu, 'node.menu');
+            validatePlacement(node.placement, 'node.placement', 'canvas.add.node');
             validateNodeCapabilities(node.capabilities);
             validateNodeRuntime(node.runtime);
             if (node.timeoutMs !== undefined && (typeof node.timeoutMs !== 'number' || !Number.isInteger(node.timeoutMs) || node.timeoutMs < 100 || node.timeoutMs > 3_600_000))
@@ -216,7 +252,7 @@ export function validateManifest(value) {
             throw new ContractError('actions 必须为数组');
         const actionIds = new Set();
         for (const raw of c.actions) {
-            const action = keys(raw, ['id', 'name', 'description', 'action', 'presentation', 'mediaTypes', 'maxCount', 'ui', 'menu'], 'action');
+            const action = keys(raw, ['id', 'name', 'description', 'action', 'presentation', 'mediaTypes', 'maxCount', 'ui', 'menu', 'placement'], 'action');
             const actionId = identifier(action.id, 'action.id');
             if (actionIds.has(actionId))
                 throw new ContractError('操作标识重复');
@@ -231,6 +267,7 @@ export function validateManifest(value) {
                 throw new ContractError('操作素材类型无效');
             boundedInteger(action.maxCount, '操作素材数量', 1, 256);
             validateMenu(action.menu, 'action.menu');
+            validatePlacement(action.placement, 'action.placement', 'canvas.add.resource');
             const ui = keys(action.ui, ['component', 'url', 'origin'], 'action.ui');
             const component = optionalString(ui.component, 'action.ui.component');
             if (component)

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); }
@@ -141,6 +148,14 @@ dialog::backdrop { background: #30384266; }
 .status-badge.error { color: var(--danger); background: #fff1ef; }
 .plugin-list { display: grid; gap: 8px; max-height: 224px; overflow: auto; }
 .plugin-list:empty::before { content: "暂无可调试的插件"; padding: 18px; border: 1px dashed var(--line-strong); border-radius: 12px; color: var(--quiet); font-size: 12px; text-align: center; }
+.plugin-config { display: grid; gap: 10px; margin-top: 18px; padding: 16px; border: 1px solid var(--line); border-radius: 12px; background: var(--soft); }
+.plugin-config[hidden] { display: none; }
+.plugin-config h4 { margin: 0; font-size: 13px; }
+.plugin-config label { display: grid; gap: 5px; color: var(--muted); font-size: 12px; }
+.plugin-config input:not([type="checkbox"]), .plugin-config select { width: 100%; min-height: 36px; padding: 6px 9px; border: 1px solid var(--line-strong); border-radius: 8px; background: #fff; }
+.plugin-config button { min-height: 34px; padding: 0 12px; border: 1px solid var(--line-strong); border-radius: 8px; background: #fff; }
+.plugin-config .config-actions { display: flex; gap: 8px; }
+.plugin-config small { color: var(--quiet); }
 .plugin-choice { position: relative; display: grid; grid-template-columns: 18px minmax(0, 1fr) auto; align-items: center; gap: 10px; min-height: 68px; border: 1px solid var(--line); border-radius: 12px; padding: 10px 12px; background: #fff; cursor: pointer; }
 .plugin-choice:hover { border-color: var(--line-strong); background: var(--soft); }
 .plugin-choice:has(input:checked) { border-color: #aab6c1; background: #f9fafb; }
@@ -255,6 +270,8 @@ 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>
+        <div class="form-actions"><button id="open-local-config" type="button">配置本地插件</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>
@@ -279,8 +296,8 @@ dialog::backdrop { background: #30384266; }
   <div id="notice" class="notice" role="status" hidden></div>
   <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>
+    <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><form id="plugin-config" class="plugin-config" hidden><h4>本地插件配置</h4><p id="config-status" role="status"></p><div id="config-fields"></div><div class="config-actions"><button type="submit">保存并启用</button><button id="config-check" type="button">检查配置</button></div></form></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><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 +307,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 +384,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);
@@ -448,9 +507,44 @@ dialog::backdrop { background: #30384266; }
       $('dock-expand').addEventListener('click', () => { manuallyCollapsed = false; expandedOverDialog = canvasDialogOpen; renderDock(); });
       const chosen = () => catalog?.plugins.find(item => item.id === selected);
       const panelPlugin = () => catalog?.plugins.find(item => item.id === panelSelected);
+      let configFormKey = '';
+      function renderConfig() {
+        const plugin = panelPlugin();
+        const form = $('plugin-config');
+        const fields = plugin?.manifest.configFields || [];
+        form.hidden = !fields.length;
+        if (!fields.length) { configFormKey = ''; return; }
+        const key = JSON.stringify([plugin.id, plugin.buildKey, plugin.config, plugin.secretConfigured]);
+        if (key === configFormKey) return;
+        configFormKey = key;
+        $('config-fields').replaceChildren(); $('config-status').textContent = plugin.configurationRequired ? '待配置：填写必填项后才能启用。' : '配置仅保存在本地开发服务中。';
+        for (const field of fields) {
+          const label = document.createElement('label');
+          label.textContent = `${field.label}${field.required ? ' *' : ''}`;
+          let input;
+          if (field.type === 'select') {
+            input = document.createElement('select');
+            const empty = document.createElement('option'); empty.value = ''; empty.textContent = '请选择'; input.append(empty);
+            for (const choice of field.options || []) { const option = document.createElement('option'); option.value = choice.value; option.textContent = choice.label; input.append(option); }
+            input.value = String(plugin.config?.[field.key] ?? field.default ?? '');
+          } else {
+            input = document.createElement('input');
+            input.type = field.type === 'secret' ? 'password' : field.type === 'number' ? 'number' : field.type === 'boolean' ? 'checkbox' : 'text';
+            if (field.type === 'boolean') input.checked = Boolean(plugin.config?.[field.key] ?? field.default);
+            else if (field.type !== 'secret') input.value = String(plugin.config?.[field.key] ?? field.default ?? '');
+            if (field.type === 'number') input.step = 'any';
+          }
+          input.name = field.key;
+          input.required = Boolean(field.required && (field.type !== 'secret' || !plugin.secretConfigured?.[field.key]));
+          label.append(input);
+          if (field.type === 'secret') { const hint = document.createElement('small'); hint.textContent = plugin.secretConfigured?.[field.key] ? '已配置；留空保留原密钥' : '尚未配置'; label.append(hint); }
+          $('config-fields').append(label);
+        }
+        $('config-check').hidden = !plugin.configCheckAvailable;
+      }
       function renderPluginList() {
         const plugins = catalog?.plugins || [];
-        const key = JSON.stringify(plugins.map(item => [item.id, item.name, item.nodes, item.actions, item.enabled]));
+        const key = JSON.stringify(plugins.map(item => [item.id, item.name, item.nodes, item.actions, item.enabled, item.configurationRequired]));
         if (key !== pluginListKey) {
           pluginListKey = key;
           $('plugin-list').replaceChildren();
@@ -463,7 +557,7 @@ dialog::backdrop { background: #30384266; }
             const id = document.createElement('code'); id.textContent = item.id;
             copy.append(name, id);
             const meta = document.createElement('span'); meta.className = `plugin-choice-meta${item.enabled ? '' : ' disabled'}`;
-            meta.textContent = item.enabled ? `${item.nodes} 个节点 / ${item.actions} 个操作` : '已停用';
+            meta.textContent = item.configurationRequired ? '待配置' : item.enabled ? `${item.nodes} 个节点 / ${item.actions} 个操作` : '已停用';
             row.append(input, mark, copy, meta); $('plugin-list').append(row);
           }
         }
@@ -483,8 +577,8 @@ dialog::backdrop { background: #30384266; }
         const plugin = chosen();
         $('plugin-name').textContent = plugin?.name || '插件调试';
         const building = catalog?.devBuild?.state;
-        $('state').textContent = building === 'error' ? '构建失败' : building === 'building' ? '正在构建' : frameFailed ? '画布加载失败' : busy ? (session ? '正在刷新' : '正在打开画布') : session ? (!session.active ? '会话已失效' : plugin?.buildKey === session.fingerprint ? '已连接' : '发现新构建') : '等待画布';
-        $('dot').className = `dot ${building === 'error' || frameFailed ? 'error' : building === 'building' ? 'warning' : session ? !session.active ? 'error' : plugin?.buildKey === session.fingerprint ? 'ready' : 'warning' : ''}`;
+        $('state').textContent = building === 'error' ? '构建失败' : building === 'building' ? '正在构建' : plugin?.configurationRequired ? '待配置' : frameFailed ? '画布加载失败' : busy ? (session ? '正在刷新' : '正在打开画布') : session ? (!session.active ? '会话已失效' : plugin?.buildKey === session.fingerprint ? '已连接' : '发现新构建') : '等待画布';
+        $('dot').className = `dot ${building === 'error' || frameFailed ? 'error' : building === 'building' || plugin?.configurationRequired ? 'warning' : session ? !session.active ? 'error' : plugin?.buildKey === session.fingerprint ? 'ready' : 'warning' : ''}`;
         $('refresh').disabled = !session?.active || busy || frameFailed || Boolean(building && building !== 'ready');
         const stateText = $('state').textContent;
         $('panel-status').textContent = stateText;
@@ -497,6 +591,7 @@ dialog::backdrop { background: #30384266; }
         $('build-full').textContent = plugin?.buildKey || '—';
         $('project-id').textContent = session?.projectId || '—';
         renderPluginList();
+        renderConfig();
         const inspected = panelPlugin();
         $('open-plugin').disabled = !inspected?.enabled || busy || packageDownloading;
         $('download-package').disabled = !inspected?.package || packageDownloading;
@@ -609,13 +704,41 @@ dialog::backdrop { background: #30384266; }
         render();
       });
       $('manage').addEventListener('click', () => { panelSelected = selected; packageMessage = ''; packageError = false; render(); panel.showModal(); $('plugin-list').querySelector('input:checked')?.focus(); renderDock(); });
-      panel.addEventListener('close', () => { renderDock(); $('manage').focus(); });
+      $('open-local-config').addEventListener('click', () => { panelSelected = selected; packageMessage = ''; packageError = false; render(); panel.showModal(); $('plugin-list').querySelector('input:checked')?.focus(); });
+      panel.addEventListener('close', () => { renderDock(); ($('setup').hidden ? $('manage') : $('open-local-config')).focus(); });
       $('close').addEventListener('click', () => panel.close());
       $('panel-cancel').addEventListener('click', () => panel.close());
       $('plugin-list').addEventListener('change', event => {
         if (!event.target.matches('input[name="studio-plugin"]')) return;
         panelSelected = event.target.value; packageMessage = ''; packageError = false; render();
       });
+      $('plugin-config').addEventListener('submit', async event => {
+        event.preventDefault();
+        const plugin = panelPlugin(); if (!plugin) return;
+        const config = {};
+        for (const field of plugin.manifest.configFields || []) {
+          const input = $('plugin-config').elements.namedItem(field.key);
+          if (!input) continue;
+          if (field.type === 'secret' && !input.value) continue;
+          config[field.key] = field.type === 'boolean' ? input.checked : field.type === 'number' ? Number(input.value) : input.value;
+        }
+        try {
+          const response = await fetch(`/studio/plugins/${encodeURIComponent(plugin.id)}/configure`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ config, enabled: true }) });
+          const result = await response.json();
+          if (!response.ok) throw new Error(result.error || '配置保存失败');
+          $('config-status').textContent = '配置已保存，插件已启用。';
+          await loadCatalog();
+        } catch (error) { $('config-status').textContent = error.message || '配置保存失败'; }
+      });
+      $('config-check').addEventListener('click', async () => {
+        const plugin = panelPlugin(); if (!plugin) return;
+        try {
+          const response = await fetch(`/studio/plugins/${encodeURIComponent(plugin.id)}/check`, { method: 'POST' });
+          const result = await response.json();
+          if (!response.ok) throw new Error(result.error || '配置检查失败');
+          $('config-status').textContent = result.message || result.result?.message || '配置检查通过。';
+        } catch (error) { $('config-status').textContent = error.message || '配置检查失败'; }
+      });
       $('open-plugin').addEventListener('click', () => {
         if (!panelPlugin()?.enabled || busy) return;
         selected = panelSelected; show(''); panel.close(); connect();

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.2",
+  "version": "0.1.4",
   "description": "EasyAI 画布插件开发工具与运行时",
   "type": "module",
   "engines": {
@@ -31,7 +31,8 @@
     "LICENSE"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
     "better-sqlite3": "12.4.1",

package/tools/build-plugin-package.mjs

@@ -30,6 +30,7 @@ export async function buildPluginPackage({
   const plugin = (
     await import(pathToFileURL(resolve(directory, 'server/plugin.mjs')).href)
   ).default;
+  if (!plugin?.manifest) throw new Error(`插件入口 ${serverEntry} 必须默认导出 definePlugin(...)`);
   await build({
     configFile: false,
     publicDir: false,