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

package/README.md

@@ -13,11 +13,17 @@ 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` 仍可使用。
+
+`init` 还会在项目根目录生成 `AGENTS.md`，供 Codex 等编程助手了解插件目录、SDK 边界与验证命令。项目约定变化时，请与代码一起维护该文件。
+
+开发工作台位于 `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 或自有基础设施时使用独立服务。构建还会生成 `dist/plugin.zip.sha256` 供管理员核对。独立服务生产环境必须提供 `PLUGIN_SERVICE_SIGNING_SECRET`、与平台连接 ID 一致的 `PLUGIN_SERVICE_AUDIENCE` 和持久化的 `PLUGIN_DATA_DIR`。业务密钥放在插件配置或部署环境，不写入前端组件。
+平台托管只接纳运行不超过 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,14 @@ 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),
+    'AGENTS.md': await readFile(join(packageRoot, 'templates/AGENTS.md'), 'utf8'),
+    [`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,34 +160,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();
@@ -195,9 +240,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`);
@@ -211,6 +257,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();
@@ -235,8 +282,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();
@@ -256,12 +304,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

@@ -17,7 +17,7 @@ const sdkVersions = new SdkVersionManager(process.cwd(), process.env.PLUGIN_SDK_
 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 });
     }
 }
@@ -73,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,
@@ -197,6 +201,21 @@ 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;

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

@@ -127,28 +127,51 @@ button:focus-visible, select:focus-visible, input:focus-visible, summary:focus-v
 .empty button { justify-self: center; min-height: 40px; border: 0; border-radius: 10px; padding: 0 16px; font-size: 12px; font-weight: 600; }
 
 /* Plugin management dialog */
-dialog { width: min(820px, calc(100vw - 32px)); max-width: calc(100vw - 32px); max-height: min(720px, calc(100dvh - 32px)); margin: auto; overflow: hidden; border: 1px solid var(--line-strong); border-radius: 18px; padding: 0; color: var(--ink); background: #fff; box-shadow: var(--floating-shadow); }
+dialog { width: min(1040px, calc(100vw - 32px)); max-width: calc(100vw - 32px); max-height: min(900px, calc(100dvh - 32px)); margin: auto; overflow: hidden; border: 1px solid var(--line-strong); border-radius: 18px; padding: 0; color: var(--ink); background: #fff; box-shadow: var(--floating-shadow); }
 dialog[open] { display: flex; flex-direction: column; }
 dialog::backdrop { background: #30384266; }
-.dialog-head { flex: none; display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; padding: 24px 28px 20px; border-bottom: 1px solid var(--line); }
-.dialog-head h2 { margin: 0 0 5px; font-size: 20px; line-height: 1.35; font-weight: 600; }
+.dialog-head { flex: none; display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; padding: 24px 30px 20px; border-bottom: 1px solid var(--line); }
+.dialog-head h2 { margin: 0 0 5px; font-size: 22px; line-height: 1.35; font-weight: 650; }
 .dialog-head p { margin: 0; color: var(--quiet); font-size: 12px; }
 .dialog-head button { display: grid; place-items: center; width: 36px; height: 36px; flex: none; border: 0; border-radius: 9px; color: var(--quiet); background: transparent; }
 .dialog-head button:hover { color: var(--ink); background: var(--page); }
 .dialog-head svg { width: 18px; height: 18px; }
-.dialog-body { flex: 1; min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) 290px; overflow: hidden; }
-.dialog-main { min-width: 0; overflow: auto; padding: 0 28px 26px; }
-.target-section, .session-section { padding: 24px 0; }
-.target-section { border-bottom: 1px solid var(--line); }
+.dialog-body { flex: 1; min-height: 0; display: grid; grid-template-columns: minmax(248px, 30%) minmax(0, 1fr); overflow: hidden; }
+.plugin-sidebar { display: flex; flex-direction: column; min-width: 0; min-height: 0; padding: 24px 16px 20px 24px; border-right: 1px solid var(--line); background: var(--soft); }
+.plugin-sidebar > p { margin: -6px 0 18px; color: var(--quiet); font-size: 12px; line-height: 1.5; }
+.plugin-detail { min-width: 0; overflow: auto; padding: 27px 32px 30px; }
+.detail-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }
+.detail-head h3 { margin: 0 0 5px; font-size: 20px; font-weight: 650; line-height: 1.35; }
+.detail-head code { display: block; color: var(--quiet); font: 11px/1.5 var(--font-code); overflow-wrap: anywhere; }
+.detail-meta { display: flex; flex-wrap: wrap; gap: 8px; margin: 17px 0 0; }
+.detail-meta span { padding: 6px 10px; border: 1px solid var(--line); border-radius: 7px; color: var(--muted); background: var(--soft); font-size: 11px; }
+.detail-empty { color: var(--quiet); font-size: 13px; }
+.detail-empty[hidden], .plugin-detail-content[hidden] { display: none; }
 .section-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 15px; }
 .section-heading h3 { margin: 0; font-size: 13px; font-weight: 700; }
 .status-badge { display: inline-flex; align-items: center; gap: 7px; padding: 6px 10px; border-radius: 999px; color: var(--warning); background: #faf1df; font-size: 11px; font-weight: 600; white-space: nowrap; }
 .status-badge::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
 .status-badge.ready { color: var(--success); background: #e9f4ef; }
 .status-badge.error { color: var(--danger); background: #fff1ef; }
-.plugin-list { display: grid; gap: 8px; max-height: 224px; overflow: auto; }
+.plugin-list { display: grid; align-content: start; gap: 8px; min-height: 0; overflow: auto; padding-right: 7px; }
 .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-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; }
+.configuration-section { margin-top: 28px; padding-top: 22px; border-top: 1px solid var(--line); }
+.configuration-section h4 { margin: 0; font-size: 15px; font-weight: 650; }
+.configuration-section > p { margin: 7px 0 16px; color: var(--quiet); font-size: 12px; line-height: 1.5; }
+.no-config { padding: 16px; border: 1px solid var(--line); border-radius: 10px; color: var(--muted); background: var(--soft); font-size: 12px; }
+.no-config[hidden] { display: none; }
+.plugin-config { display: grid; gap: 14px; padding: 18px; border: 1px solid var(--line); border-radius: 12px; background: var(--soft); }
+.plugin-config[hidden] { display: none; }
+.plugin-config label { display: grid; gap: 7px; color: var(--muted); font-size: 12px; font-weight: 600; }
+.plugin-config input:not([type="checkbox"]), .plugin-config select { width: 100%; min-height: 42px; padding: 8px 11px; border: 1px solid var(--line-strong); border-radius: 9px; color: var(--ink); background: #fff; font-weight: 400; }
+.plugin-config input[type="checkbox"] { width: 18px; height: 18px; }
+.plugin-config button { min-height: 40px; padding: 0 14px; border: 1px solid var(--line-strong); border-radius: 9px; color: var(--ink); background: #fff; font-size: 12px; font-weight: 600; }
+.plugin-config .config-actions { display: flex; flex-wrap: wrap; gap: 8px; }
+.plugin-config .config-actions button[type="submit"] { border-color: var(--accent); color: #fff; background: var(--accent); }
+.plugin-config #config-status { margin: 0; color: var(--quiet); font-size: 12px; line-height: 1.5; }
+#config-fields { display: grid; gap: 14px; }
+.plugin-config small { color: var(--quiet); }
+.plugin-choice { position: relative; display: grid; grid-template-columns: 18px minmax(0, 1fr); align-items: center; gap: 10px; min-height: 78px; border: 1px solid var(--line); border-radius: 12px; padding: 11px 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; }
 .plugin-choice:focus-within { outline: 2px solid #8e9ca9; outline-offset: -3px; }
@@ -159,16 +182,25 @@ dialog::backdrop { background: #30384266; }
 .plugin-choice-copy strong, .plugin-choice-copy code { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
 .plugin-choice-copy strong { color: var(--ink); font-size: 13px; font-weight: 600; }
 .plugin-choice-copy code { color: var(--quiet); font: 400 10px/1.4 var(--font-code); }
-.plugin-choice-meta { color: var(--quiet); font-size: 11px; white-space: nowrap; }
+.plugin-choice-meta { grid-column: 2; color: var(--quiet); font-size: 11px; white-space: nowrap; }
 .plugin-choice-meta.disabled { color: var(--danger); }
-.plugin-actions { display: flex; align-items: center; gap: 8px; margin-top: 14px; }
-.plugin-actions button { display: inline-flex; align-items: center; justify-content: center; gap: 7px; min-height: 40px; border: 1px solid var(--line-strong); border-radius: 10px; padding: 0 12px; color: var(--ink); background: #fff; box-shadow: var(--control-shadow); font-size: 12px; font-weight: 600; }
+.plugin-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 22px; }
+.plugin-actions button { display: inline-flex; align-items: center; justify-content: center; gap: 7px; min-height: 42px; border: 1px solid var(--line-strong); border-radius: 10px; padding: 0 14px; color: var(--ink); background: #fff; box-shadow: var(--control-shadow); font-size: 12px; font-weight: 600; }
 .plugin-actions button:hover:not(:disabled) { background: var(--page); }
-.plugin-actions #open-plugin { background: #f2f4f6; }
+.plugin-actions #open-plugin { border-color: var(--accent); color: #fff; background: var(--accent); }
+.plugin-actions #open-plugin:hover:not(:disabled) { background: #252b31; }
 .plugin-actions svg { width: 16px; height: 16px; flex: none; }
 .package-note { margin: 10px 0 0; color: var(--quiet); font-size: 11px; line-height: 1.5; }
 .package-note:empty { display: none; }
 .package-note.error { color: var(--danger); }
+.secondary-panels { display: grid; gap: 12px; margin-top: 26px; }
+.secondary-panels > details { border: 1px solid var(--line); border-radius: 11px; background: #fff; }
+.secondary-panels > details > summary { display: flex; align-items: center; gap: 8px; padding: 14px 16px; font-size: 12px; font-weight: 650; cursor: pointer; list-style: none; }
+.secondary-panels > details > summary::-webkit-details-marker { display: none; }
+.secondary-panels > details > summary::after { content: "+"; margin-left: auto; color: var(--quiet); font-size: 18px; font-weight: 400; line-height: 1; }
+.secondary-panels > details[open] > summary::after { content: "−"; }
+.secondary-panels .panel-content { padding: 0 16px 16px; }
+.secondary-panels .activity-list { max-height: 220px; }
 .section-context { overflow: hidden; color: var(--quiet); font-size: 11px; font-weight: 500; text-overflow: ellipsis; white-space: nowrap; }
 .session-summary { margin: 0; }
 .session-summary > div { display: flex; align-items: center; justify-content: space-between; gap: 14px; min-height: 51px; border-top: 1px solid #e9ebea; }
@@ -180,10 +212,8 @@ dialog::backdrop { background: #30384266; }
 .technical-details dl { display: grid; grid-template-columns: 84px minmax(0, 1fr); gap: 10px 12px; margin: 14px 0 0; padding: 14px; border: 1px solid var(--line); border-radius: 12px; background: var(--soft); font-size: 11px; }
 .technical-details dt { color: var(--quiet); }
 .technical-details dd { margin: 0; overflow-wrap: anywhere; font-family: var(--font-code); }
-.activity-section { display: flex; flex-direction: column; min-width: 0; overflow: hidden; padding: 24px 18px; border-left: 1px solid var(--line); background: var(--soft); }
-.activity-section > p { margin: -6px 0 16px; color: var(--quiet); font-size: 12px; line-height: 1.5; }
 .activity-count { color: var(--quiet); font-size: 11px; }
-.activity-list { flex: 1; min-height: 120px; max-height: 350px; overflow: auto; border-top: 1px solid var(--line); }
+.activity-list { min-height: 80px; overflow: auto; border-top: 1px solid var(--line); }
 .activity-list:empty::before { content: "暂无活动"; display: block; padding: 25px; color: var(--quiet); font-size: 12px; text-align: center; }
 .activity-item { display: grid; grid-template-columns: 58px minmax(0, 1fr); gap: 10px; padding: 11px 2px; color: var(--muted); font-size: 12px; line-height: 1.5; }
 .activity-item + .activity-item { border-top: 1px solid #eceeed; }
@@ -203,10 +233,13 @@ dialog::backdrop { background: #30384266; }
   .diagnostics { padding: 32px 46px 38px; border-top: 1px solid var(--line); border-left: 0; }
 }
 @media (max-width: 760px) {
-  .dialog-body { grid-template-columns: 1fr; overflow: auto; }
-  .dialog-main { overflow: visible; }
-  .activity-section { min-height: 180px; border-top: 1px solid var(--line); border-left: 0; }
-  .activity-list { max-height: 180px; }
+  .dialog-body { display: block; overflow: auto; }
+  .plugin-sidebar { padding: 18px 20px; border-right: 0; border-bottom: 1px solid var(--line); }
+  .plugin-sidebar > p { margin-bottom: 12px; }
+  .plugin-list { display: flex; flex: none; overflow-x: auto; padding: 2px 0 8px; }
+  .plugin-choice { flex: 0 0 min(245px, 75vw); }
+  .plugin-detail { overflow: visible; padding: 24px 20px; }
+  .detail-head { position: sticky; top: 0; z-index: 1; margin: -24px -20px 0; padding: 14px 20px; border-bottom: 1px solid var(--line); background: #fff; }
 }
 @media (max-width: 520px) {
   dialog { height: min(760px, calc(100dvh - 32px)); }
@@ -230,21 +263,17 @@ dialog::backdrop { background: #30384266; }
   .controls .button-label { display: none; }
   .dialog-head { padding: 18px 20px; }
   .dialog-head button { width: 44px; height: 44px; margin: -6px -6px 0 0; }
-  .dialog-main { padding-inline: 20px; }
-  .target-section, .session-section { padding-block: 18px; }
+  .detail-head h3 { font-size: 18px; }
   .section-heading { margin-bottom: 12px; }
   .session-summary > div { min-height: 42px; }
   .technical-details { padding-top: 12px; }
-  .activity-section { padding: 18px 20px; }
   .dialog-actions { padding: 12px 20px; }
   .dialog-actions button { min-height: 44px; padding-inline: 9px; }
   .dock button { min-height: 44px; padding-inline: 0; }
   .dock-grip, .dock-collapse { width: 44px; }
 }
 @media (max-width: 375px) {
-  .plugin-choice { grid-template-columns: 18px minmax(0, 1fr); }
   .plugin-choice-copy code { white-space: normal; overflow-wrap: anywhere; }
-  .plugin-choice-meta { grid-column: 2; }
   .dialog-actions { flex-wrap: wrap; }
   .dialog-actions > div { margin-left: auto; }
   .dialog-actions button { padding-inline: 8px; }
@@ -263,6 +292,7 @@ dialog::backdrop { background: #30384266; }
         <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>
@@ -286,10 +316,17 @@ dialog::backdrop { background: #30384266; }
   </div>
   <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><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-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">
+      <aside class="plugin-sidebar" aria-labelledby="target-title"><div class="section-heading"><h3 id="target-title">本地插件</h3><span id="plugin-count" class="activity-count">0 个</span></div><p>选择插件后在右侧管理</p><div id="plugin-list" class="plugin-list" role="radiogroup" aria-labelledby="target-title"></div></aside>
+      <div class="plugin-detail"><p id="detail-empty" class="detail-empty" hidden>暂无插件。请在本地服务中注册插件。</p><div id="plugin-detail-content" class="plugin-detail-content">
+        <div class="detail-head"><div><h3 id="detail-name">插件</h3><code id="detail-id"></code></div><span id="detail-status" class="status-badge" role="status">检查中</span></div>
+        <div class="detail-meta"><span id="detail-nodes">0 个节点</span><span id="detail-actions">0 个操作</span><span id="detail-package">插件包不可用</span></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>
+        <div class="configuration-section" aria-labelledby="configuration-title"><h4 id="configuration-title">插件配置</h4><p>配置仅保存在本地开发服务中。</p><div id="no-config" class="no-config" hidden>此插件无需配置，可以直接调试或下载插件包。</div><form id="plugin-config" class="plugin-config" hidden><p id="config-status" role="status" aria-live="polite"></p><div id="config-fields"></div><div class="config-actions"><button type="submit">保存并启用</button><button id="config-check" type="button">检查配置</button></div></form></div>
+        <div class="secondary-panels"><details><summary>连接与构建 <span id="panel-status" class="status-badge" role="status">正在连接</span></summary><div class="panel-content"><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><span id="active-plugin" class="section-context" hidden></span><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></div></details><details><summary>最近活动 <span id="activity-count" class="activity-count">0 条</span></summary><div class="panel-content"><div id="log" class="activity-list" role="log" aria-label="调试活动" aria-live="polite"></div></div></details></div>
+      </div></div>
+    </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>
   <script>
@@ -498,9 +535,47 @@ 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 = '', configFeedback = null;
+      function renderConfig() {
+        const plugin = panelPlugin();
+        const form = $('plugin-config');
+        const fields = plugin?.manifest?.configFields || [];
+        form.hidden = !fields.length;
+        $('no-config').hidden = !plugin || Boolean(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 = configFeedback?.pluginId === plugin.id ? configFeedback.message : 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]));
+        $('plugin-count').textContent = `${plugins.length} 个`;
+        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();
@@ -513,7 +588,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);
           }
         }
@@ -533,8 +608,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;
@@ -547,7 +622,17 @@ dialog::backdrop { background: #30384266; }
         $('build-full').textContent = plugin?.buildKey || '—';
         $('project-id').textContent = session?.projectId || '—';
         renderPluginList();
+        renderConfig();
         const inspected = panelPlugin();
+        $('detail-empty').hidden = Boolean(inspected);
+        $('plugin-detail-content').hidden = !inspected;
+        $('detail-name').textContent = inspected?.name || '插件';
+        $('detail-id').textContent = inspected?.id || '';
+        $('detail-nodes').textContent = `${inspected?.nodes || 0} 个节点`;
+        $('detail-actions').textContent = `${inspected?.actions || 0} 个操作`;
+        $('detail-package').textContent = inspected?.package ? '插件包可下载' : '插件包不可用';
+        $('detail-status').textContent = inspected?.configurationRequired ? '待配置' : inspected?.enabled ? '已启用' : '已停用';
+        $('detail-status').className = `status-badge ${inspected?.configurationRequired ? '' : inspected?.enabled ? 'ready' : 'error'}`;
         $('open-plugin').disabled = !inspected?.enabled || busy || packageDownloading;
         $('download-package').disabled = !inspected?.package || packageDownloading;
         $('download-package').setAttribute('aria-busy', String(packageDownloading));
@@ -658,13 +743,50 @@ dialog::backdrop { background: #30384266; }
         frame.contentWindow.postMessage({ protocol, type: 'refresh', sessionId: session.sessionId, pluginId: selected, requestId: waiting }, catalog.platformOrigin);
         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(); });
+      function openPanel(forConfiguration = false) {
+        panelSelected = forConfiguration ? catalog?.plugins.find(item => item.configurationRequired)?.id || selected : selected;
+        packageMessage = ''; packageError = false; configFeedback = null; configFormKey = ''; render(); panel.showModal();
+        const firstField = forConfiguration ? $('config-fields').querySelector('input, select') : null;
+        (firstField || $('plugin-list').querySelector('input:checked') || $('close')).focus();
+        renderDock();
+      }
+      $('manage').addEventListener('click', () => openPanel());
+      $('open-local-config').addEventListener('click', () => openPanel(true));
+      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();
+        panelSelected = event.target.value; packageMessage = ''; packageError = false; configFeedback = null; render(); document.querySelector('.plugin-detail').scrollTop = 0;
+      });
+      $('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 || '配置保存失败');
+          configFeedback = { pluginId: plugin.id, message: '配置已保存，插件已启用。' };
+          $('config-status').textContent = configFeedback.message;
+          await loadCatalog();
+        } catch (error) { configFeedback = { pluginId: plugin.id, message: error.message || '配置保存失败' }; $('config-status').textContent = configFeedback.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 || '配置检查失败');
+          configFeedback = { pluginId: plugin.id, message: result.message || result.result?.message || '配置检查通过。' };
+          $('config-status').textContent = configFeedback.message;
+        } catch (error) { configFeedback = { pluginId: plugin.id, message: error.message || '配置检查失败' }; $('config-status').textContent = configFeedback.message; }
       });
       $('open-plugin').addEventListener('click', () => {
         if (!panelPlugin()?.enabled || busy) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyai-canvas/canvas-plugin-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "EasyAI 画布插件开发工具与运行时",
   "type": "module",
   "engines": {
@@ -27,11 +27,13 @@
     "bin",
     "dist",
     "tools",
+    "templates",
     "README.md",
     "LICENSE"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
     "better-sqlite3": "12.4.1",

package/templates/AGENTS.md

@@ -0,0 +1,21 @@
+# 项目开发指引
+
+本项目使用 `@easyai-canvas/canvas-plugin-sdk` 开发 EasyAI 画布插件。请以当前安装版本的类型定义和项目代码为准；项目使用 Node 22.22.0 或更新的 Node 22 版本。
+
+## 代码位置
+
+- 每个独立插件放在 `src/plugins/<目录>/`，其中 `plugin.ts` 声明 manifest、节点或操作及服务端处理器，`ui.ts` 实现 Vue 界面。对应契约测试放在 `test/`。
+- 新增独立插件时运行 `npx easyai-plugin add <目录> --template node|action|combined`。同一插件的多个节点继续放在同一个目录，并保持插件 ID 与节点类型唯一。
+- 只通过 SDK 的公开导入路径使用能力：`@easyai-canvas/canvas-plugin-sdk`、`/protocol`、`/ui`。不要依赖 EasyAI 平台源码或 SDK 内部文件。
+
+## 开发约定
+
+- 修改 manifest、参数、输入输出或处理器时，同步更新对应契约测试。服务端从 `request.parameters` 和 `request.inputsByPort` 读取业务输入，并返回符合协议的输出。
+- 前端通过 `usePluginNode()` 或 `usePluginAction()` 与画布交互。业务密钥放在插件配置或部署环境中，不写入 `ui.ts` 或前端产物。
+- 有外部副作用的处理器使用 `executionId` 保证业务幂等；只有确认可安全重试时才声明 `safeRetry`。
+
+## 验证与交付
+
+- 开发预览：`npm run dev`，工作台位于 `http://localhost:4310/studio`。
+- 修改插件后运行 `npm run test:contract`；交付前运行 `npm run build`，检查 `dist/plugins/<pluginId>.zip` 与 `.sha256`。
+- ZIP 由平台管理员审核、导入并启用；独立服务部署的配置参见 SDK README 和项目 README。

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,