企业官网建设流程全解析

Slate v2 绝对架构评审：硬切公共 Editor 值，收敛到 read/update 单一生命周期

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

本文基于 Plate 仓库中的评审计划文档 2026-04-29-slate-v2-absolute-architecture-review-plan.md，完整还原 Slate v2 重写过程中"移除公共Editor值导出"这一关键架构决策的评审全程：从现状判定、四选一决策简报、state/tx公共 API 目标形态，到 8 轮 Pass 的压力测试、加权评分卡、维护者异议台账（steelman ledger）、回归证明矩阵与执行日志。读完后你会掌握：如何论证"一个公共生命周期"优于"两套并存的读写路径"、如何用契约测试先行（contract-first）的方式执行公共 API 硬切，以及 Plate 与 slate-yjs 这类上层产品/协作层如何依赖"迁移骨架"而非适配器兼容来演进。

1. 背景：为什么"去掉第二个公共编辑器 API"是绝对架构的前提

评审计划开篇的判定只有一句话：Hard cut the publicEditorvalue.（硬切公共Editor值导出。）

其理由在于：当时的实现已经从编辑器实例上移除了原生写操作（primitive writers），但export const Editor: EditorInterface仍然保留了一个第二套公共编辑器 API。这个值把编辑器状态读取、写入、扩展注册、快照替换、setup 辅助和类型管道混在同一个命名空间里。原文档的判断是直白的：

That is not absolute architecture. It is legacy Slate gravity with better naming. （那不是绝对架构，那是换了名字的旧版 Slate 引力。）

这个"旧版 Slate 引力"在 Plate 仓库里是真实存在的。当前仓库的packages/slate包就是对上游 legacyslate的包装与扩展，代码里仍大量以值的方式调用Editor.*静态 API，例如 deleteMerge.ts 中的：

import { Editor as EditorInterface } from 'slate'; // ... at = EditorInterface.unhangRange(e as any, at, { voids });

这正是 v2 重写要消灭的形状：Editor.string(editor, range)、editor.string([])、editor.read((state) => state.text.string([]))三种写法并存，让"一次读取应该怎么写"变成了一道选择题。v2 的目标形态则只允许一种：

import { createEditor, isEditor } from "slate"; import type { Editor } from "slate"; editor.read((state) => { state.selection.get(); state.text.string([]); }); editor.update((tx) => { tx.nodes.set(props, { at: target }); });

公共 API 的收敛目标（即"正常公共 API"清单）：

• Editor只保留为类型（type-only）；
• editor.read((state) => ...)是编辑器状态读取的唯一路径；
• editor.update((tx) => ...)是写入与 tx 局部读取的唯一路径；
• 整篇文档替换是事务写入，而不是静态辅助：editor.update((tx) => tx.value.replace(input))；
• 纯数据命名空间保留：Node、Path、Point、Range、Element、Text及同类纯函数工具；
• 如需公共谓词，isEditor(value)位于顶层；
• 扩展注册保持显式：defineEditorExtension(...)与editor.extend(...)。

被硬切（必须消失）的对象：

• 公共export const Editor；
• 公共EditorInterface；
• 公共getEditorTransformRegistry/setEditorTransformRegistry；
• 公共静态Editor.*编辑器状态读写；
• 作为常规应用 API 的实例editor.replace/editor.reset；
• 在存在state/tx分组时，文档/示例仍将实例查询方法当作正常读取路径的写法；
• 一方文档/示例/测试把Editor.*当作常规应用代码的写法。

内部代码仍可以保留实现表（implementation table），但必须藏在内部模块边界之后。原文档的结论是：一个名为Editor的公共静态对象，不该活过这次未发布的硬切重写。

2. 意图、边界与决策简报

2.1 意图与期望结果

意图有三条：

1. 在实例方法硬切之后，移除最后一块大型并行公共 API 面；
2. 让"读/写"不可能被用两种方式解释；
3. 保持原生 Slate 的无观点（unopinionated）特性，迁移过去不需要照搬 Plate 的产品命令风格。

期望结果是：一个小型公共Editor类型；没有公共静态Editor值；没有公共静态编辑器状态辅助命名空间；一个只被核心运行时、适配器和测试内部使用的私有写内核 / transform-registry 表；公共文档与示例只教read/update、state/tx和纯数据命名空间；实例查询方法在迁移期只作为实现/高级桥接面，不进入常规应用文档。

2.2 范围与非目标

在范围内（in scope）：包导出形状、EditorInterface与Editor静态值的使用、transform-registry 导出边界、把Editor当值导入的公共文档/示例/测试、当前引用typeof Editor.*的类型耦合、替换/setup 辅助的边界、剩余实例查询边界，以及面向 Plate 与 slate-yjs 的迁移骨架证明。

非目标（non-goals）明确列出：当前版本 Plate 适配器支持、当前版本 slate-yjs 适配器支持、浏览器运行时重写、React 渲染契约变更、editor.refs提案、移除Node/Path/Range/Point/Element/Text等纯数据命名空间。

决策边界上，原计划声明：因为这次重写尚未发布，破坏性变更被允许、不需要兼容别名、测试专用辅助只要不从未公开入口导出即可、不为保存现有公共应用代码本身而妥协。

2.3 四选一决策简报

原计划给出的决策简报列出了四个可行选项：

落选的选项还有三处值得注意的明确否决：

• 把Editor.*静态读取定位为"遗留兼容但文档标注为高级"——被拒，因为它仍在教错误的形状；
• editor.api/editor.tf——被拒，因为对原生 Slate 而言这是 Plate 形状，且会把读取新鲜度在 update 内部劈开；
• editor.commands——被拒，因为对核心 Slate 而言那是产品 DX 糖，产品命令应留在 Plate 层。

决策简报同时记录了后果面：大量测试与 fixture runner 需要 seed/read 辅助；使用typeof Editor.*的类型别名需要逐函数或内部类型源；editor.replace/editor.reset调用点需要改为tx.value.replace(input)或非公共测试 seeding 辅助；公共文档会大幅变简单；下游用户通过一个心智模型（read与update）完成迁移。

命名权威在仓库内另有落地的决策文档：slate-v2-state-tx-public-api-and-extension-namespaces.md。该文档确立了公共生命周期写法（state做只读、tx做可写事务视图，且tx上的读取必须观察到事务进行中的草稿状态），以及扩展应挂载为state.<plugin>/tx.<plugin>分组而非往编辑器对象上平铺方法：

defineEditorExtension({ key: "table", state: { table(state) { return { currentCell() {} }; }, }, tx: { table(tx) { return { insertRow() {} }; }, }, });

这与评审计划的"扩展注册保持显式、扩展命名空间挂在 state/tx 上"完全一致。

3. 公共 API 目标形态与内部运行时目标

3.1 公共 API 目标

计划的"Public API Target"一节给出了完整的目标代码：

const editor = createEditor(); editor.read((state) => { const text = state.text.string([]); const selection = state.selection.get(); const isVoid = state.schema.isVoid(element); }); editor.update((tx) => { tx.value.replace({ children, selection: null, marks: null, }); tx.text.insert("x"); tx.nodes.set({ type: "heading" }, { at: target }); tx.operations.replay(operations, { tag: "remote" }); });

顶层导出（top-level exports）：

• createEditor、isEditor、defineEditorExtension；
• 纯数据命名空间与纯函数辅助；
• 类型专用的Editor、EditorStateView、EditorUpdateTransaction及相关公共类型。

非公共或内部导出（non-public / internal exports）：

• Editor值、EditorInterface；
• getEditorTransformRegistry/setEditorTransformRegistry；
• transform registry 变更辅助；
• 作为公共应用作者方法的editor.replace/editor.reset；
• 仅供测试/fixture 使用的快照 seed 辅助。

3.2 内部运行时目标

内部运行时允许保留：由createEditor构建的冻结 transform/write registry、以编辑器实例为键的WeakMap、供源码复用的内部查询辅助表、仅测试用的 seed 辅助、以及一个被tx.value.replace与测试 seed 辅助共用的内部replaceSnapshot实现。

内部运行时有三条"不得泄漏"红线：

• getEditorTransformRegistry不得经core桶文件导出；
• Editor值不得经interfaces或根索引桶文件导出；
• 直接桥接辅助不得出现在一方文档/示例中。

计划还给出了期望的实现布局（路径可以变，但公共/私有边界不能变）：

src/internal/editor-kernel.ts src/internal/transform-registry.ts src/test-utils/seed-editor.ts

3.3 整篇文档替换为什么必须是事务写入

Pass 2（意图/边界压力轮）专门压测了两个未决边界，其中最核心的结论是：Editor.replace与Editor.reset随公共Editor值一起消亡；editor.replace/editor.reset不是常规应用作者 API；公共文档替换就是editor.update((tx) => tx.value.replace(input))。理由：整篇替换本身就是一次写入，把它留在Editor.replace或editor.replace上，就重演了原生变更辅助的同一错误——事务词汇之外的变更。替换会影响 runtime ids、选区、marks、提交元数据与订阅者通知，这些都属于事务工作。测试侧则改用非公共的createTestEditor(input)/seedEditor(editor, input)辅助，因为"测试不是公共 API"。

4. 八轮 Pass 评审过程与评分卡

该评审采用slate-ralplan模式，共 8 个 Pass，加权总分从0.874逐轮提升到最终0.936，完成阈值0.92。评分维度与权重固定为六项：

4.1 各 Pass 演进轨迹

Pass 4 的一句关键自我约束值得单独引用："Cutting the publicEditorvalue is a DX and architecture win, not a direct runtime speed win. Do not sell it as perf magic."（切掉公共Editor值是 DX 与架构收益，不是直接的运行时提速，不要把它当性能魔法卖。）运行时性能收益只在实现保持热写入走既有 tx/registry 路径、且不额外引入宽泛 React 订阅、包裹提交或逐操作深度克隆时才成立。

Pass 6 的 pre-mortem 列出了三个具体失败场景及预防策略：

1. 导出/类型churn失控——预防：先加非公共测试辅助，再切公共导出，再用守卫禁止兼容命名空间回潮；
2. tx.value.replace破坏运行时身份或提交元数据——预防：复用与replaceSnapshot相同的内部基底，并证明 children、selection、marks、runtime ids、reason/classes/tags 与订阅者输出；
3. 协作/适配器失去干净的观察路径——预防：保留editor.subscribe作为高级 headless 适配器桥，并证明操作重放与订阅者元数据可在完全不导入公共Editor值的情况下工作。

回滚/硬切答案是明确的：不退回公共Editor值；如果实现过大，就拆分为五个执行切片（测试辅助与tx.value.replace基底 → 公共导出/类型切分 → 源码/测试迁移 → 文档/示例迁移 → 守卫与闭合），而不是发布兼容别名——"churn 的补救措施是更小的实现切片，不是第二套公共 API"。

4.2 最终闭合门槛

5. 维护者异议台账：八个钢人论证

第 16 节的异议台账（Objection Ledger）是本文档最有引用价值的部分之一：每条变更都配齐"最强异议 / 反题（steelman antithesis）/ 权衡张力 / 为何保留 / 证据 / 被拒替代 / 迁移答案 / 回归证明 / 生态答案 / 判定"。八条结论摘要如下：

6. 回归证明矩阵与验证命令

6.1 证明矩阵

计划为每个被切的面都指定了契约级证明：

6.2 快速驱动门禁命令

原计划第 21 节给出的验证命令（在计划的实现工作区/Users/zbeyens/git/slate-v2下执行）：

bun test ./packages/slate/test/public-field-hard-cut-contract.ts bun test ./packages/slate/test/state-tx-public-api-contract.ts bun test ./packages/slate/test/write-boundary-contract.ts bun check

以及两条 grep 守卫：

rg -n "export const Editor|interface EditorInterface|getEditorTransformRegistry|setEditorTransformRegistry" packages/slate/src rg -n "import \{[^}]*Editor|Editor\." docs site/examples/ts packages/slate/test packages/slate-react/test

第二条 grep 需要为类型专用导入、迁移期遗留 fixture 快照和内部测试辅助维护白名单。需要说明：上述命令与文件路径均出自计划文档原文，指向的是该重写的外部实现工作区（.tmp/slate-v2检出），而非 Plate 仓库内的 packages/slate（后者仍是 legacyslate的包装层）。

7. 执行日志：契约测试先行的红绿轨迹

计划末尾的 Execution Log 记录了完整的执行轨迹，是"契约测试先行"（contract-first）的实证：

1. 2026-04-29 Ralph 激活（红灯）：在实现工作区新建public-surface-contract.ts，加入四条红色公共契约——不存在名为Editor的公共值导出、不存在公共 transform-registry 导出、不存在公共editor.replace/editor.reset、公共源码中不存在export interface EditorInterface或export const Editor。运行bun test ./packages/slate/test/public-surface-contract.ts，结果按预期为红。
2. 2026-04-29 实现闭合（绿灯）：实现tx.value.replace(input)并补齐 state/tx 契约覆盖；切掉根Editor值导出、EditorInterface名、transform-registry 导出与实例editor.replace/editor.reset；内部包/静态需求移到slate/internal与slate-react运行时门面之后；文档与站点示例迁移。验证结果：聚焦契约测试163 pass；bun check通过，bun test全量1007 pass/95 skip/0 fail；slate-reactvitest19 passed，113 tests passed。
3. 2026-04-29 遗留测试桥硬切：删除了把遗留 fixture 导入从slate改写到slate/internal的config/bun-test-setup.ts兼容桥，删除动态加载遗留检出的 fixture 测试，把本地 fixture 转为显式 JSX runtime 导入与显式slate/internal导入。验证结果：多套件联跑1167 pass/95 skip/0 fail，全量口径与上一步一致。

8. 对 Plate 与 slate-yjs 的意义：迁移骨架，不是适配器兼容

计划对两个下游生态的立场高度一致——只做迁移骨架证明，不做当前版本适配器承诺：

Plate 需要的是：

• state.<plugin>与tx.<plugin>扩展分组；
• 稳定的文档值与操作流；
• 供历史、选区与产品 UI 使用的提交元数据；
• 供节点行为使用的 schema/spec 策略；
• 位于原生 Slate 之上的插件自有产品命令。

切掉Editor静态值对 Plate 是帮助而非伤害：它移除了插件们可以"倾倒方法"的又一处，产品命令应当住在 Plate 扩展层而不是原生Editor.*里。

slate-yjs 需要的是：确定性操作、确定性快照/提交元数据、经tx.operations.replay(...)的显式远端重放、仅本地的 runtime ids 与 DOM 选区策略，以及没有公共可变编辑器字段。因此只要协作代码能经事务 API 重放、并只使用公共类型/数据辅助而无需导入静态编辑器状态命名空间，这次公共Editor值硬切就是可接受的。

9. 架构北极星与实现阶段

第 5 节的"Source-Backed Architecture North Star"把结论压缩成保留/切除两列：

保留：Slate 模型作为文档真相；操作作为协作与重放真相；paths/ranges/points 作为公共数据模型；editor.read/editor.update作为生命周期；state/tx作为分组的编辑器状态访问；EditorCommit作为本地运行时事实；React 作为投影/订阅层。

切除：静态编辑器状态 API；公共 transform registry API；tx之外的公共变更辅助；发布前的兼容别名。

外部证据行则对应三套成熟系统的分工：Lexical 支持 read/update 生命周期与脏数据调和；ProseMirror 支持事务对文档、选区、marks 与元数据的所有权；Tiptap 支持扩展打包与选择器感知的 React DX，但其命令重的产品 API 应留在原生 Slate 之上。

第 20 节把实现拆成 10 个阶段，顺序即迁移顺序：

1. 契约先行的导出测试（无值Editor、类型专用Editor、无 transform-registry 根导出）；
2. 内部边界拆分（transform registry 与静态实现表移入内部模块）；
3. 类型解耦（替换typeof Editor.*引用）；
4. 源码迁移（内部Editor.*改为实例读、state/tx、纯辅助或内部辅助）；
5. 测试/fixture 迁移（引入非公共 seed/snapshot 辅助）；
6. 值替换迁移（加入tx.value.replace(input)，迁移应用面替换示例）；
7. 查询面迁移（文档/示例改为 state/tx 分组读取）；
8. 文档/示例迁移（移除用户面Editor.*读写）；
9. 护栏（grep/导出守卫，防公共Editor值与 transform registry 回潮）；
10. 验证（聚焦测试、bun check、completion-check）。

显式推迟项包括：ref 生命周期辅助（pathRef/pointRef/rangeRef是活句柄而非已提交读取，需要单独设计，且该计划不得顺手发明editor.refs命名空间）、createEditor({ initialValue })公共人体工学、以及当前版本 Plate/slate-yjs 适配器。

10. 适用前提与仓库内如何继续验证

使用本文内容时需要注意三点适用前提：

• 该计划的实现发生在 Plate 仓库之外的未发布重写工作区（原文使用.tmp/slate-v2与/Users/zbeyens/git/slate-v2绝对路径），文中这些绝对路径是计划文档的原始记录，不能在 Plate 仓库内直接解析；Plate 仓库内的 packages/slate 仍是面向 legacyslate的包装层（可从 packages/slate/src/index.ts 的桶导出与 interfaces/editor 目录结构确认其仍暴露legacy-editor等模块）。
• 计划中引用的实时源码行号（如interfaces/editor.ts:798、core/public-state.ts:1717）同样指向外部工作区，属于当时的证据快照。
• 该重写当时未发布，因此计划允许破坏性变更且拒绝兼容别名——任何基于本文的迁移建议都应先确认所使用版本的状态。

在 Plate 仓库内可以继续深入的路径：命名权威决策 slate-v2-state-tx-public-api-and-extension-namespaces.md、其姐妹决策 slate-v2-read-update-runtime-architecture.md、同主题的前一天评审 2026-04-28-slate-v2-absolute-architecture-review-plan.md，以及 legacy 编辑器包装实现 packages/slate/src/create-editor.ts 与 packages/slate/src/interfaces/editor/ 目录。

一句话总结：这份计划的价值不在于"删了哪个导出"，而在于它展示了如何用固定维度评分卡、钢人异议台账、pre-mortem 与契约测试先行，把一个高爆炸半径的公共 API 硬切，变成一条可审计、可拆分执行、且每一步都有红绿证据的收敛路径——最终把 Slate v2 的公共读写路径从"多种方式并存"压缩为editor.read/editor.update的单一生命周期。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate