用途
该技能用于指导 Plate 插件的编写与重构,适用于在新增或修改插件字段/选项之前,以及开发横跨 Slate、Plate、注册表(registry)和文档的功能之前使用。其目标是产出不需要后续 plate-next 清理的插件。技能负责插件编写机制,包括语义层、持久化源码归属、文件拓扑、上下文类型、初始状态、选项存储、extendApi 与 extendTransforms、React 家族和包内验证。VISION.md 中的 Plugins & Components 与 Slate Boundary 章节决定插件方向。
必读材料
编写或重构插件前需阅读:creation-flow.md(语义与文件归属)、typing.md(类型推导与公共契约)。packages/core/src/lib/plugin 和 packages/core/src/react/plugin 中的 Plate 基础构建器及其类型测试优先级高于既有先例。
语义层原则
语义基础优先,Plate 其次。若行为不依赖 React 也有意义,应在 src/lib 中用 createSlatePlugin 或 createTSlatePlugin 编写。已有语义基础只应在其实际 React 适配器中通过 toPlatePlugin 或 toTPlatePlugin 提升,不要用 createPlatePlugin 重写。仅真正的 React/Plate 原生插件才直接使用 createPlatePlugin。若无 React 层独立职责,插件保持仅基础层。明确列出的直接 Plate 例外包括:无有用语义基础的 React 渲染行为;无有用语义基础的 DOM/编辑器表面插件;无非 React 含义的 React 节点属性或组件行为。
归属优先的文件拓扑
同置(colocation)为默认。只有一个生产归属者的行为应内联在该插件的 createPlugin / .extend() 链中,包括一次性 with、decorate*、normalizers、parsers、commands、corrections、matchers、state、APIs 和 transforms。对于复制的 app/registry 源码,遵循 plate-ui;该技能不负责复制项的同置、依赖元数据或浏览器验证。
React 与测试归属
组件、hook、context、provider、primitive 和 React 19 形态由 plate-ui 负责。该技能只在包内实现已接受的形态并验证包行为。React 测试放在组件家族或其单一语义控制器归属者旁边;测试规范家族、fixture 和内联测试构造由 verify 的 testing 参考负责。
包边界
修改包边界前,检查 package.json 的 exports、peers、dependencies 和消费者。始终必需的实现库放在 dependencies;仅当消费者必须共享运行时实例,或该库支持可选能力时才用 peer,且仅当去掉该能力包仍可用时标记为 optional。optional peer 不是普通依赖的堆放处。CommonJS 依赖通过默认导入引入,除非其命名导出在原生 Node ESM 下已被证明可用(Bun 和打包器接受 Node 拒绝的命名导入)。无 React 的无头导入和带真实 peer 的 React 导入都需验证。用 pnpm gen:package 创建新包,修改包依赖后运行 pnpm test:manifests。
功能交付
当一个功能需要覆盖包、React 适配器、复制的 UI、文档和发布并触达 registry 消费者时,参考 manifest.md。Plan 手册将模板复制进计划,Scale 证明行为 yes 时追加 Benchmark 的性能可观测性包;Build 手册以 node tooling/scripts/check-plate-feature.mjs <plan> 收尾。无头流和仅 registry 流是一等模式,不是不完整的完整流;manifest 行仅在有具体 N/A 理由时以 no 跳过。
工作流
- 阅读 VISION.md 和当前插件构建器。
- 创建文件前确定语义层以及持久化生产、React 家族和测试归属。
- 搜索当前 Plate 基础构建器/类型测试和最接近的干净包类比;不要复制过时的文件图。包装原生 Slate 工厂的插件(如 HistoryPlugin 和 YjsPlugin)需复制其最接近的被包装类比的所有注册,可通过在 tooling/ 和 lint 配置中 grep 该类比名称找到。
- 可复用的公共分支交给 best-api;否则保持推断的插件链内联。
- 在持久归属者中定义初始状态、选项存储、extendApi 和 extendTransforms 方法、关系及 React 行为;配置前阅读当前 extendApi、extendTransforms、overrideEditor、node、handlers、inject 和 input-rule 签名,API 需要共享键时复用 packages/utils/src/lib/plate-keys.ts 中的 KEYS。
- 删除被取代的 helper/component/hook/spec 文件,用 pnpm brl 重新生成 barrel 文件。
- 验证最小可靠范围:包类型检查和行为测试;构建器/公共推断变化时运行 Plate 基础类型测试;React 行为变化时运行 React 测试;插件包装原生工厂时运行 pnpm --filter platejs build,因为声明构建会报告 typecheck 跳过的 TS4094 错误。
- 审计过时的 helper 名称、根选项 helper、嵌套更新、显式插件注解、空配置别名、顶层插件配置、参数穿线的 editor / api / tf helper 以及一次性文件分类。
限制
资料未提供该技能的收费、价格、平台支持范围或具体效果指标。