MiragenFlow/plugins/canvas/sdk/README.md

@miragenflow/plugin-sdk

MiragenFlow 画布节点内部扩展的 TypeScript SDK。扩展作者只写节点 UI 与逻辑,类型、JSX、运行时桥接和构建由 SDK 提供。当前产品不提供远程加载或安装入口,扩展需要随应用源码集成。

提供什么

能力	说明
完整类型	CanvasPlugin / CanvasNodeDefinition / CanvasNodeContext / CanvasOp / CanvasTheme / CanvasNodeData … 全部有提示
definePlugin(...)	给插件对象(或工厂)补全类型;对象形式无需再 const { React } = runtime
automatic JSX	jsxImportSource 指向本包,TSX 自动转发到宿主 React,不打包第二份 React
类型化 hooks	import { useState, useEffect, useMemo, useRef, ... },运行时转发宿主 React
buildPlugin(...)	统一 esbuild 构建,插件 build.mjs 只需一行

最小插件

// src/index.tsx
import { definePlugin, useState } from "@miragenflow/plugin-sdk";
import type { CanvasNodeContentProps } from "@miragenflow/plugin-sdk";

function Content({ ctx }: CanvasNodeContentProps) {
    const [n, setN] = useState(0);
    return (
        <button onMouseDown={(e) => e.stopPropagation()} onClick={() => setN((v) => v + 1)} style={{ color: ctx.theme.node.text }}>
            {ctx.node.title}: {n}
        </button>
    );
}

export default definePlugin({
    id: "my-plugin",
    name: "我的插件",
    version: "1.0.0",
    nodes: [
        {
            type: "my-plugin:node",
            title: "示例",
            icon: "✨",
            defaultSize: { width: 240, height: 160 },
            Content,
        },
    ],
});

// build.mjs
import { buildPlugin } from "@miragenflow/plugin-sdk/build";
await buildPlugin(import.meta.url);

npm run build 只产出 dist/<目录名>.js,不会写入应用公共目录或远程清单。

依赖接入

插件 package.json:

{
    "type": "module",
    "scripts": { "build": "node build.mjs", "dev": "node build.mjs --watch", "typecheck": "tsc --noEmit" },
    "devDependencies": {
        "@miragenflow/plugin-sdk": "file:../sdk",
        "@types/react": "19.1.12",
        "typescript": "^5"
    }
}

插件 tsconfig.json 关键项:"jsx": "react-jsx"、"jsxImportSource": "@miragenflow/plugin-sdk"、"moduleResolution": "bundler"。

设计约束

• React 单例:JSX 与 hooks 惰性读取 globalThis.MiragenFlowRuntime.React(由源码集成层注入),react 全程 external,绝不打包第二份。
• 重依赖:three、marked 等在源码里 await import("https://esm.sh/...") 动态加载,esbuild 自动 external,不进 bundle。
• 类型真源:src/types.ts 是宿主 web/src/types/canvas-plugin.ts 公开契约的镜像;宿主契约变更时同步此处。