release: v0.17.0

2026-08-19 22:09:49 +08:00
parent 9414048f9d
commit 84e9e7bff5
469 changed files with 19997 additions and 39561 deletions
@@ -1,10 +1,10 @@
-# Infinite Canvas 画布节点插件
+# MiragenFlow 画布节点插件

-给画布扩展自定义节点。每个插件是一个**独立目录**,用 **TypeScript** 编写,自带 `package.json` / `build.mjs` / `src/index.tsx` / `dist/`,互不耦合,可单独构建、发布、升级。
+本目录保留画布节点的源码级内部扩展能力。每个扩展是一个独立 TypeScript 目录,自带 `package.json` / `build.mjs` / `src/index.tsx` / `dist/`,可单独开发和构建。

-内置节点只有文本、图片、视频、音频、生成配置、组六种;其余节点(Markdown、SVG、HTML、3D 全景、便利贴……)都是插件。
+内置节点包括文本、图片、音频、生成配置和组。Markdown、SVG、HTML、3D 全景和便利贴目录是 SDK 与内部集成示例。

-作者只写节点 UI 与逻辑,**类型、JSX、宿主 React、构建全部由 [`@infinite-canvas/plugin-sdk`](./sdk/README.md) 提供**,写 TSX 全程有代码提示;产物仍是宿主加载器现有契约的 ESM(React external、宿主单例)。
+作者只写节点 UI 与逻辑,类型、JSX、宿主 React 桥接和构建由 [`@miragenflow/plugin-sdk`](./sdk/README.md) 提供。当前产品不包含远程插件市场、注册表、自动发现或 URL 安装入口;需要上线的扩展应作为应用源码的一部分接入并随产品构建。

 ## 目录约定

@@ -21,55 +21,37 @@ plugins/canvas/
  svg/ html/ panorama/ sticky-note/ ...
 ```

-## 快速开始
+## 创建内部扩展

 ```bash
 cp -r plugins/canvas/template plugins/canvas/my-plugin
 cd plugins/canvas/my-plugin
 # 改 package.json 的 name;改 src/index.tsx 里的 id / nodes[].type
 npm install
-npm run dev        # watch 构建,产物同步到 web/public/plugins/my-plugin.js
+npm run dev        # watch 构建 dist/my-plugin.js
 npm run typecheck  # tsc --noEmit,类型自检
 ```

 产物名取**目录名**,复制后记得把目录改成插件名。

-## 构建 / 发布 / 升级
+## 构建

 ```bash
 cd plugins/canvas/<name>
 npm install
-npm run build   # → dist/<name>.js,并同步到 web/public/plugins/<name>.js
-npm run dev     # watch,改动自动构建并同步
+npm run build   # → dist/<name>.js
+npm run dev     # watch,改动自动构建
 ```

-把 `dist/<name>.js` 托管到任意静态地址(CDN、GitHub Raw、对象存储),用户在画布「节点插件」管理器填该 URL 安装。升级时重新构建覆盖同一 URL,用户点「更新」即可。
-
-## 官方插件注册表
-
-本项目官方插件由 CI 集中构建后发布到孤儿分支 `plugins-dist`(**构建产物不进 git**),画布「节点插件」面板顶部的**官方插件**区经 jsDelivr 从该分支远程拉取并一键安装;第三方插件仍走下方「第三方插件」的 JS URL 安装。构建脚本与发布说明见 [`registry/`](./registry/README.md);清单地址可用 `VITE_PLUGIN_REGISTRY_URL` 覆盖成自建来源。
-
-## 本地开发
-
-`npm run dev` 起 watch,产物会同步到 `web/public/plugins/<name>.js`。此后有两种方式在画布里用到它:
-
-**方式一(推荐):自动发现。** 画布启动时会扫描 `web/public/plugins/` 下的插件,自动加入「节点插件」管理器列表,**默认关闭**;打开开关即启用。无需手动填 URL,启用时会按文件重新拉取,配合 watch 改完刷新即最新。
-
-**方式二:`VITE_DEV_PLUGINS`。** 在 `web/.env.local` 声明(逗号分隔多个),这些插件每次刷新页面都**重新拉取并直接激活**(不缓存、不落库、无开关):
-
-```env
-VITE_DEV_PLUGINS=/plugins/markdown.js,/plugins/svg.js
-```
-
-再起画布 `web`(`npm run dev`)。流程即:改 `src/index.tsx` → watch 自动构建 → 刷新画布看到最新效果,无需反复安装。
+`buildPlugin` 只生成 `dist/` 产物,不会写入 `web/public/` 或生成远程清单。示例扩展默认不在产品界面中出现;商业构建需要在应用源码中显式注册准备启用的节点定义。

 ## 用 SDK 写插件

 默认导出 `definePlugin({...})`(对象形式,**无需再 `const { React } = runtime`**):

 ```tsx
-import { definePlugin, useState } from "@infinite-canvas/plugin-sdk";
-import type { CanvasNodeContentProps } from "@infinite-canvas/plugin-sdk";
+import { definePlugin, useState } from "@miragenflow/plugin-sdk";
+import type { CanvasNodeContentProps } from "@miragenflow/plugin-sdk";

 function Content({ ctx }: CanvasNodeContentProps) {
    const [n, setN] = useState(0);
@@ -106,7 +88,7 @@ SDK 导出的 hooks(`useState/useEffect/useMemo/useRef/...`)运行时转发宿
    showInCreateMenu?: boolean;   // 默认 true
    hasSourceHandle?: boolean;    // 右侧输出连接点,默认 true
    keepAspectRatio?: (node) => boolean;
-    resource?: (node) => { kind: "text"|"image"|"video"|"audio", text?, url? } | null; // 作为上游输入被消费时输出什么
+    resource?: (node) => { kind: "text"|"image"|"audio", text?, url? } | null; // 作为上游输入被消费时输出什么
    Content: ({ ctx }) => ReactNode;         // 节点主体渲染
    Panel?: ({ ctx, onClose }) => ReactNode; // 可选:节点下方面板
    toolbar?: (ctx) => Array<{ id, title, label, icon, onClick, danger? }>; // 追加到 hover 工具栏
@@ -153,11 +135,7 @@ ctx.applyOps([
 - **CSS**:写独立 `.css`,`import css from "./styles.css"` 拿到字符串(esbuild `text` loader),放到 `css` 字段自动注入/清理;`src/env.d.ts` 声明 `*.css`。参考 `markdown/`。
 - **HTML**:HTML 节点把 HTML 字符串塞进 sandbox iframe 的 `srcDoc`,自带 `<style>`,不需要插件级 CSS。参考 `html/`。

-## 兼容说明
-
-加载器仍接受**默认导出为工厂函数** `(runtime) => CanvasPlugin`(用 `runtime.React`)或**普通对象**;老的 JS 插件无需改动即可运行。SDK 的 automatic JSX 让新插件走对象形式,更简洁。
-
 ## 注意

- 插件代码会在画布页面内**直接执行**,可访问浏览器本地数据(含 AI API Key)。发布前请自审,用户也只应安装可信来源。
+- 扩展代码会在画布页面内直接执行,可以访问浏览器本地数据(含 AI API Key),接入商业构建前需要完成代码审查。
 - 交互控件记得 `onMouseDown={(e) => e.stopPropagation()}`(避免触发节点拖拽),滚动区域加 `onWheel={(e) => e.stopPropagation()}` 与容器 `data-canvas-no-zoom`(避免被画布缩放拦截)。