Slate-first 插件架构实战Plate 插件创建的核心决策、类型契约与 React 包装边界【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文基于 plate 仓库内置的插件创作规范.agents/skills/plate-plugin-creator/SKILL.md及其规则子文档编写并结合packages/core的插件作者 API 源码与comment、code-block、basic-nodes等真实包实现进行印证。读者读完可以掌握何时用createSlatePlugin与何时用createPlatePlugin、如何用toPlatePlugin提升语义基座插件、如何定义插件级与编辑器级 API/transforms、如何避免仓库中已被识别的反模式以及如何让插件通过类型契约与 barrel 生成的双重验证。Plate 的插件系统是Slate 优先Slate-first、Plate 其次的分层架构文档语义节点、变换、解析规则沉淀在src/libReact 渲染与编辑器集成只作为薄薄的外壳叠加在src/react。本文以仓库内plate-plugin-creator技能为骨架逐层拆解这条硬性法则的执行机制——从决策树、类型契约、组合 API 到文件放置与验证流程并给出可直接复制的真实代码模式。为什么是Slate-first, Plate-second这是整份技能文档的Hard Law也是理解 Plate 插件架构的第一性原理如果一个插件在脱离 React 时仍有有意义的文档语义那么先在packages/*/src/lib中编写基座只有当渲染、hooks 或 Plate 专属的编辑器集成确实需要时再添加 React/Plate 层。其直接推论是不要因为消费者最终会用到 React就从src/react起步不要为了加一个组件或一小段包装配置就用createPlatePlugin重写基座插件。这条法则有四个被明确定义的命名例外Named Exceptions只有命中其一才可以打破 Slate-first 顺序纯粹由 hook 或useHooks驱动的插件只负责在 Plate 层挂接 DOM/编辑器事件、没有有意义的 Slate 基座的插件只是组合既有 Plate 插件的捆绑型bundle插件有用行为只存在于 React 节点 props 或组件中的插件。仓库中真实的 React-native 插件如 EventEditorPlugin.ts、PlaywrightPlugin.ts、CopilotPlugin.tsx之所以合法地待在 Plate/React 层正是因为它们并不假装自己是 Slate-first 的语义插件——这是判断何时可以例外的试金石。North-Star Gate先路由架构决策再谈执行细节技能文档把责任切成了两个所有者任何触及可复用 API 形状、运行时边界、builder/factory 模式、命名与分层的工作都必须先经过路由门禁North-Star Gate而非直接动手OwnerScopenorth-stardoctrine、API 形状、运行时边界、性能法则plate-plugin-creator插件机制、类型、包装、文件放置二进制契约很简单如果当前工作会实质性地改变可复用 API 形状、运行时边界、builder/factory 模式或可复用命名/分层先停下来路由到 north-star并附上north-star updated或north-star reaffirmed: section-name否则留在本技能内继续执行插件机制。plate-plugin-creator只保留路由门禁、简短派生清单和执行机制不重复展开 north-star 的长篇法则。进入执行前需要过一遍从 north-star 派生的 5 条自查清单owner/layer 是否明确这是规范语义canonical semantics还是局部糖衣local sugar配置是否显式、可复制该形状是否在热路径上引入了隐藏的运行时开销这里是否应该由 core 拥有一个 primitive而不是特性语义仓库表面语义与 React 各归其位技能文档给出了明确的代码落点Repo Surfaces写插件前先确认自己的代码属于哪一层packages/*/src/lib—— 语义基座插件、transforms、解析器、规则packages/*/src/react—— Plate/React 包装、hooks、node props、组件packages/core/src/lib/plugin—— Slate-first 创作原语packages/core/src/react/plugin—— Plate 包装原语packages/core/type-tests—— 插件契约的真相来源source of truth。七大原则创作时的总体取舍从语义所在处开始行为在没有 React 时就有意义就从src/lib开始。先推断、后仪式只有当显式契约控制真的能买到东西时才动用createT*系列。包装基座插件语义基座已存在时用toPlatePlugin/toTPlatePlugin提升而不是在 React 里重写。刻意设计 API 形状插件专属表面与合并后的编辑器表面是两种工具不能混用。使用共享键随包发布的插件键与跨插件引用应来自 plate-keys.ts 的KEYS而不是随手字符串字面量。核心契约胜过先例类型测试与核心创作 API 高于嘈杂的旧包示例。保持车道狭窄本技能只负责插件创作公共文档交给 docs-creator。创建流程决策树写代码前的第一件事动手写任何插件之前先走 creation-flow.md 的决策树Need a new plugin? || - Does the behavior matter without React? || | || - yes - author packages/*/src/lib || | | || | - Need explicit public contract control? || | | - yes - createTSlatePlugin || | | - no - createSlatePlugin || | | || | - Need a React/Plate layer later? || | - yes - toPlatePlugin / toTPlatePlugin || | - no - keep it Slate-only || | || - no - stay in packages/*/src/react || | || - Is it a bundle of existing Plate plugins? || | - yes - createPlatePlugin || | || - Does it need explicit typed options/api/transforms? || - yes - createTPlatePlugin || - no - createPlatePlugin | - Need docs? - hand off to docs-creator四种默认路径语义基座插件Semantic base plugin适用于文档语义、transforms、解析器、注入规则与共享行为契约。仓库中的好例子包括BaseCommentPlugin、BaseCodeBlockPlugin、HtmlPlugin。Plate/React 包装Wrapper语义基座已存在只需绑定组件、hooks 或 Plate 专属包装配置。好例子CommentPlugin、CodeBlockPlugin、MentionPlugin。React-native 例外插件没有有意义的 Slate 基座时才直接使用 Plate 创作。好例子EventEditorPlugin、PlaywrightPlugin、CopilotPlugin。捆绑插件Bundle plugin任务是组合而非新语义时用createPlatePlugin({ plugins: [...] })。好例子BasicBlocksPlugin。如果你只需要捆绑既有 Plate 插件不要先发明一个假的基座插件来过流程。核心 API 的职责划分与源码机制四个创作入口的职责在 SKILL.md 中被严格划分createSlatePlugin/createTSlatePlugin拥有语义基座插件toPlatePlugin/toTPlatePlugin把语义基座提升到 React/Plate 表面createPlatePlugin/createTPlatePlugin用于真正的 React/Plate-native 插件或既有 Plate 插件的捆绑。createSlatePlugin默认配置与扩展机制createSlatePlugin.ts 是 Slate-first 层的核心工厂。从源码可以看到它通过mergePlugins为插件补齐默认形状api: {}、dependencies: []、handlers: {}、inject: {}、node: { type: key }、options: {}、parser/parsers: {}、plugins: []、priority: 100、render: {}、rules: {}、shortcuts: {}、inputRules: []、transforms: {}并初始化__apiExtensions、__extensions、__selectorExtensions三个扩展队列——这些队列在resolvePlugin阶段才被应用到编辑器因此插件定义本身是不可变的声明实际行为在解析时组装。它返回的SlatePlugin实例带有一组链式方法这正是技能文档中组合规则对应的底层实现extend(config)合并配置或追加上下文感知扩展压入__extensionsconfigure(config)设置__configuration以便运行时按编辑器上下文求值extendApi(extension)/extendTransforms(extension)压入带isPluginSpecific: true的扩展构成插件专属表面extendEditorApi(extension)/extendEditorTransforms(extension)压入isPluginSpecific: false的扩展构成合并后的编辑器表面overrideEditor(extension)标记isOverride: true直接改变编辑器行为本身extendPlugin(p, config)/configurePlugin(p, config)递归地在嵌套插件树中定位同名 key 的插件并施加扩展——找不到时extendPlugin会把它追加为顶层子插件而configurePlugin不会新增withComponent(component)快捷地把组件同时写入node.component与render.node。而createTSlatePluginC()只是createSlatePlugin的显式类型参数版本见同文件末尾用于需要精确控制导出 options/api/transforms/selectors 契约的场景属于明确契约的工具而非默认仪式。toPlatePlugin薄包装的机制toPlatePlugin.ts 负责把SlatePluginC提升为 React 侧PlatePlugin。其关键在于methodsToWrap数组——configure、configurePlugin、extendEditorApi、extendSelectors、extendApi、extendEditorTransforms、extendTransforms、overrideEditor、extend、extendPlugin这 10 个链式方法在包装后被保留同时通过InferOptions/InferApi/InferTransforms/InferSelectors从基座类型中推断出 options、api、transforms 与 selectors 的类型EO/EA/ET/ES泛型只负责追加 React 层的新增部分。这正是包装不重写语义的类型学保障。真实案例BaseCodeBlockPlugin → CodeBlockPlugin以 BaseCodeBlockPlugin.ts 为例基座用createTSlatePluginCodeBlockConfig声明key: KEYS.codeBlock并在plugins中挂入BaseCodeLinePlugin、BaseCodeSyntaxPlugin两个语义子插件随后用.extendTransforms(({ editor }) ({ ... }))定义变换——注意回调直接从上下文解构editor无需手动传参。而 CodeBlockPlugin.tsx 只是薄薄一层export const CodeSyntaxPlugin toPlatePlugin(BaseCodeSyntaxPlugin); export const CodeLinePlugin toPlatePlugin(BaseCodeLinePlugin); export const CodeBlockPlugin toPlatePlugin(BaseCodeBlockPlugin, { plugins: [CodeLinePlugin, CodeSyntaxPlugin], });语义规则与 transforms 全部留在src/libReact 层只负责把语义子插件提升为 Plate 子插件并接线。技能文档给出的直接可复制的四种关键模式如下// Good: semantic base first, thin Plate wrapper second. export const BaseCommentPlugin createTSlatePluginBaseCommentConfig({ key: KEYS.comment, }).extendApi(...); export const CommentPlugin toPlatePlugin(BaseCommentPlugin); // Good: wrapper adds Plate-only child wiring without re-authoring semantics. export const CodeBlockPlugin toPlatePlugin(BaseCodeBlockPlugin, { plugins: [CodeLinePlugin, CodeSyntaxPlugin], }); // Good: direct Plate plugin when the job is React/editor integration. export const EventEditorPlugin createPlatePlugin({ key: eventEditor, handlers: { ... }, }); // Good: bundle existing Plate plugins without fake base-plugin theater. export const BasicBlocksPlugin createPlatePlugin({ plugins: [BlockquotePlugin, HeadingPlugin, HorizontalRulePlugin], });类型契约推断优先显式只在值得时完整规则见 typing.md核心精神是用上下文不要手穿编辑器。回调上下文已经足够插件回调天然携带丰富上下文editor、plugin、type、api、tf、getOptions、setOption、setOptions等。不要把SlateEditor穿过回调签名、helper 输入或公共 option 回调——当插件上下文里已有编辑器时手动传参只会收窄类型、一无所获。以下这类标注通常只是噪音extendTransforms(({ editor }: { editor: SlateEditor }) ...) targetPluginToInject: ({ editor }: { editor: SlateEditor }) ...如果推断失败优先用createT*或一个真实导出的PluginConfig别名修复插件配置形状而不是到处喷洒手写编辑器标注。KEYS 是共享契约对随包发布/跨插件共享的表面键一律来自 plate-keys.tskey: KEYS.blockSelection targetPlugins: [KEYS.p] editor.getType(KEYS.codeBlock)源码中可以看到真实的键值契约例如codeBlock: code_block、comment: comment、p: p、blockSelection: blockSelection。选用KEYS的理由有三跨插件引用保持一致、重命名只有一个 owner、测试与包装不会再因字符串字面量而漂移。只有插件极小且完全局部或处于故意不建模共享契约的测试夹具中才允许使用原始字面量。显式类型值得投入的场景当插件导出调用者应当理解、TypeScript 应当保留的有意义契约时使用显式配置别名BaseCommentConfig、CodeBlockConfig、CopilotPluginConfig都是好例子。此外有意义的字面量选项类型应当保持稳定options: { trigger: as const, }真相来源的优先级文件之间出现分歧时按此顺序信任packages/core/src/lib/plugin/*→packages/core/src/react/plugin/*→packages/core/type-tests/*→ 仍与前三者一致的当前插件包 → 旧包先例。不要信任最响亮的旧插件文件胜过核心 API 与类型测试。组合与 API 形状extend 到哪个表面完整规则见 composition.md。基座优先、包装第二语义基座存在就包装它export const MentionPlugin toPlatePlugin(BaseMentionPlugin);这优于在createPlatePlugin里重新声明一遍相同的语义。有意图地使用嵌套插件语义子插件放进基座插件的plugins数组它们是语义契约的一部分Plate 子插件放进包装层包装拥有 React/Plate 层。对应地extendPlugin用于在父插件拥有决策权时深入嵌套插件configurePlugin用于调整嵌套子插件而不是手抄一份新的子插件定义——后者会模糊所有权边界并破坏共享行为。四条扩展面的选择extend合并配置或计算上下文感知配置extendPlugin父插件深入嵌套插件做决策overrideEditor真正要改变的是编辑器行为而不是零散的事件胶水handlers只放真正属于插件边界的事件不是把本应是 transform 或 editor override 的逻辑当垃圾桶。React-only 节点增强优先用 transformProps当任务只是在 Plate 层给已渲染节点增强 props时优先inject.nodeProps.transformProps尤其当增强是 React-only、需要 hooks、且语义基座应当保持干净时。典型好例子是BlockSelectionPlugin与NavigationFeedbackPlugin。但不要过度套用transformProps是 props 增强工具不是node.component、render、包装插件或useHooks的通用替代品。Helper 的边界单次使用、上下文局部的 helper 保持内联即可。真要抽取时让它泛化、尽量上下文无关、不要习惯性地锁死在SlateEditor上。不要因为回调体稍长就制造抽象淤泥。文件放置与 Barrel生成物只由生成器负责Barrel 规则是硬性的工程约束见 SKILL.md 的 Critical Rules绝不手写或手改index.ts/index.tsxbarrel 文件一律视为生成物在导出的包目录下新增、移动、重命名或删除公共文件后必须运行pnpm brl再进入最终验证若pnpm brl产出损坏的 barrel修复 barrel 生成器/配置或文件放置不要在brl之后手补生成的index.ts不属于公共契约的 helper、matcher、fallback 分支、可能的未来分叉逻辑都应放入internal/目录默认进internal/除非用户面对 API 确实需要该文件可被导入。不要在internal/足够时创建新的公共顶层文件。反模式清单不要复制仓库里的历史怪癖技能文档用一整节 Do Not Copy 明确禁止以下行为防止读者把附近插件的旧写法当作先例不要因为消费者最终用 React 就从src/react起步不要为了加组件或小包装配置就用createPlatePlugin重写基座不要硬编码随包/共享插件键KEYS已经拥有该契约不要照抄({ editor }: { editor: SlateEditor }) ...这种回调标注推断已知道编辑器类型不要仅仅为了讨好 TypeScript 而抽取编辑器锁定的 helper不要创建不必要的公共顶层文件internal/够用时就用它不要把transformProps当成node.component、render、useHooks的万能替代它只做 props 增强不要相信最响亮的旧插件文件胜过核心 API 与类型测试。配套的审计文档 plugin-authoring-audit.md 给出了仓库内的正反两面证据强模式包括BaseCommentPluginCommentPlugin显式配置类型 薄包装、BaseCodeBlockPluginCodeBlockPlugin基座拥有语义规则与 transforms、包装只加子插件、HtmlPlugin纯 Slate-only 不伪造 React 层、BasicBlocksPlugin捆绑组合用createPlatePlugin需要小心的模式包括 BaseTextAlignPlugin.ts 的手写SlateEditor回调标注能用但属于旧风格、教出更差习惯与 BaseAIPlugin.ts 的编辑器锁定 helper 抽取可用但鼓励了新版上下文 API 通常已无必要的编辑器穿针引线。工作流七步完成一个插件写代码前先读 creation-flow.md在packages/*/src/lib、packages/*/src/react与packages/core/type-tests中搜索最接近的类比判定属于哪一类语义基座 / Plate-React 包装 / React-native 例外 / 捆绑插件锁定契约形状options、插件专属 API/transforms、合并后的编辑器 API/transforms、嵌套子插件先套用类型规则再考虑显式标注文档只通过交接给 docs-creator 完成验证最小的诚实表面smallest honest surface语义/插件行为跑包测试公共契约变更跑类型测试或针对性 typecheck只有包装层变更才需要 React 测试。这条验证准则与仓库的分层哲学完全一致语义层变没变、类型契约变没变、React 包装层变没变各自对应不同的验证面既不欠测也不过度测试。对任何想要为 plate 贡献或自研插件的开发者而言以 plate-plugin-creator 为执行手册、以packages/core/type-tests为契约真相来源是绕开历史包袱、直接对齐核心 API 的最短路径。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
