Slate v2 多根位置权威治理把 Root 推理收敛到单一内部模块的架构清理实录【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本篇技术指南基于 Slate v2 架构清理计划文档 2026-05-22-slate-v2-root-location-authority-cleanup-ralplan.md 展开剖析多根multi-root运行时中“位置权威root location authority”这一核心正确性问题的完整治理过程。读完后你将掌握为什么多根编辑器需要单一 root 推理模块、rootless 与显式 root 的公开行为契约如何设计、可重放状态字段的 patch 准入策略如何与 history/collab 持久化语义对齐以及配套的合同测试矩阵与验证门禁应该怎么搭。一、背景多根运行时为什么需要单一位置权威Plate 仓库中的 Slate v2 是面向多根编辑场景的重写版本其核心包位于packages/slate当前主检出树中点/范围引用相关的编辑器辅助逻辑已组织在 packages/slate/src/internal/editor 目录下。在这一版中文档不再是单根结构同一个 runtime 内可以同时存在main、header等多个命名根光标、选区、操作重放都必须明确“自己属于哪个根”。该计划文档给出的核心判断Current Verdict是root-location 清理必须从 Pretext 布局架构计划中独立出来成为一条独立的 Slate 核心清理轨道相关背景可见 2026-05-22-slate-v2-pretext-layout-rendering-architecture-ralplan.md。它明确列出这条轨道要承担的五个能力面多根PointRef与RangeRef的行为根感知的操作重放operation replay与选区求逆selection inversionrootless 公开 point/range 形态的保持对外不暴露根信息内部 ref 元数据的归属ownership可重放状态字段state-field的 patch 准入策略。1.1 驱动这次清理的真实缺陷为什么 root 元数据散落在各处会出问题仓库中的解决方案文档 2026-05-23-slate-v2-rootless-explicit-selections-must-not-inherit-sibling-root.md 记录了一个典型事故链它恰好印证了计划中“脏的 ad hoc 元数据会产生真实的 bug 类”这一判断先聚焦 Header 编辑器再点击 Body主根中的第二段段落直接崩溃Cannot find a descendant at path [1,0]点击 body 之后的 commit 仍然报告roots:header——即主根的路径被存到了 header 根名下崩溃栈穿过runtime-root-engine.ts中的state.marks.get()header 视图的 marks 读取试图在主根路径[1,0]上解析却按 header 树解析必然失败。该事故的根因是“把两种语义压扁成了同一个回退”const getLocationMutationRoot ( editor: Editor, location: Location ): string | undefined getExplicitLocationRoot(location) ?? getActiveMutationRoot(editor) ?? MAIN_ROOT_KEY隐式变更如tx.text.insert(x)应当跟随当前选区所在的根显式 rootless 位置如在 base runtime 上执行tx.selection.set({ path: [1, 0], offset: 0 })应当目标为main而不是“当前选区恰好所在的根”。解决方案文档中的结论与本次计划的原则一致root 解析必须有明确的优先级链——显式根 活跃变更根 MAIN_ROOT_KEY兜底且这条链只能由一个权威模块维护。这正是后文root-location.ts单一权威模块要固化的东西。二、决策简报从散落的 root fallback 到单一权威计划文档的 Decision Brief 给出了五条设计原则一个内部模块拥有 root 推理one internal module owns root inferencerootless 的调用方输入在公开输出上保持 rootless显式 root 必须穿过 transform 和unref()存活下来undo/replay 恢复的是选区身份包括根身份大型可重放状态必须可 patch否则在进入 history/collab 持久化之前就被拒绝。Top drivers决策主驱动有三条多根运行时正确性依赖单一 root 权威__explicit*Root这类散落的 ad hoc 元数据已被证明会产生漂移drift状态字段评审发现证明“重放策略必须与实际 history/collab 持久化语义一致”。文档同时记录了三个候选方案及取舍方案结论理由保留在 Pretext/布局计划中继续修否决那个计划讲的是布局与 DOM 物化root ref 与操作求逆属于 Slate 核心root 辅助函数继续在各调用点旁复制否决已产生真实 bug 类path/ref/op 代码会互相漂移独立的 root-location authority 计划 以活源码收口采用与代码归属一致且能把剩余评审门禁收窄四条决策边界decision boundaries值得单独强调它们定义了这次清理“做什么、不做什么”root 是位置/操作元数据不是 path 的一段公开 point/range 值保持调用方原始形态内部 transform 可以临时注入 root但只有内部 helper 有权决定发布前剥掉什么任何剩余的公开PointRef/RangeRefroot 表面问题必须由最终评审裁决不允许被当作风格偏好埋掉。三、目标架构root-location 模块的归属与公开行为计划指定的目标模块是packages/slate/src/internal/root-location.ts以.tmp/slate-v2工作树为准并逐项列出其应拥有的职责MAIN_ROOT_KEY常量来自 operation、point、range、selection patch 的 root 推理显式 root 与隐式 root 的可见性区分隐式 root 的注入injection与剥离strippingref 的 root 元数据存储公开/内部 range-ref 的可见性与 draft 状态。3.1 公开行为契约计划列出的五条公开行为是验收标准rootless 的 point/range 输入可以在内部绑定到活跃根公开的current与unref()返回的根可见性与调用方传入时一致传 rootless 就得到 rootless传显式 root 就得到显式 root兄弟根的操作不会 transform 该 ref选区求逆恢复的是“被恢复选区”的根默认 history 的状态字段除非显式声明history: skip一律视为可重放。3.2 Hard Cuts硬性切断项计划以 hard cuts 的形式锁死了实现红线不允许__explicitRoot不允许__explicitAnchorRoot不允许__explicitFocusRoot不允许在 ref/op/transform 调用点重复 root fallback 辅助函数除非出现浏览器可见的回归不为这条内部核心清理宣称浏览器证明browser proof。评审收口阶段实际落实的清理是PointRef与RangeRef不再暴露公开的root?: string字段root 绑定与根可见性全部迁入root-location.ts内的 WeakMap 元数据。WeakMap 方案同时解决了两个问题公开 point/range 值保持调用方形态、不需要克隆对象即可携带不可见的绑定关系。3.3 活源码落点计划记录的实现证据计划文档附了一张“Live Source Grounding”表记录了.tmp/slate-v2工作树中各表面的落点与结论均为 keep表面计划记录的落点结论内部 root 权威packages/slate/src/internal/root-location.ts定义MAIN_ROOT_KEY用 WeakMap 存 ref 元数据拥有 operation/point/range/selection-patch 的 root 推理拥有隐式 root 注入与剥离keepPointReftransformpackages/slate/src/interfaces/point-ref.ts读取 root 元数据忽略兄弟根操作注入后再剥离隐式 rootkeepRangeReftransformpackages/slate/src/interfaces/range-ref.ts读取 root 元数据忽略兄弟根操作transform 并产出公开 ref 草稿keepPoint ref 创建packages/slate/src/editor/point-ref.ts使用活跃操作根兜底写入 root 元数据keepRange ref 创建/发布packages/slate/src/editor/range-ref.ts活跃操作根兜底写入元数据发布/重置公开草稿keepSelection inversepackages/slate/src/interfaces/operation.ts导入getSelectionPatchRootinverse 根从被恢复的 selection patch 推导keep状态字段重放策略packages/slate/src/core/public-state.tshistory ! skip或collab shared时要求 patch hooks拒绝超大的不可 patch 重放状态keep状态字段回归测试packages/slate/test/document-state-patch-contract.ts拒绝大型 omitted-history 字段缺少 patch hooks 的注册keep需要说明的证据边界上述路径是计划文档对其.tmp/slate-v2工作树的记录当前主检出树中packages/slate/src/internal/下尚不包含该文件核心实现以计划记录与工作树为准。但与之同源的问题修复与 root 解析链语义在 2026-05-23 解决方案文档 中有独立佐证且后续计划 2026-05-23-slate-v2-staged-architecture-cleanup-ralplan.md 也明确以“保留packages/slate/src/internal/root-location.ts为单一权威”为前提禁止在 text transform 与 history 中再次复制 root-location 辅助函数。四、可重放状态字段 patch 准入策略这条轨道还有一个容易被忽视但影响面很大的决策状态字段的“重放准入”。原则第 5 条——“大型可重放状态必须可 patch 或拒绝”——在计划记录的实现中体现为public-state.ts的策略当字段history ! skip或collab shared时注册必须提供 patch hooks超大且不可 patch 的重放状态直接拒绝。配套回归测试document-state-patch-contract.ts专门验证“大型 omitted-history 字段缺少 patch hooks 会被拒绝”这一行为。这条策略解决的是计划里点名的问题状态字段的评审发现证明重放策略必须与实际 history/collab 持久化语义一致。也就是说凡是可能进入撤销栈或协作同步通道的状态注册时就必须回答“如何以小 diff 形式重放它”否则宁可拒绝注册也不允许整块塞进历史——这为多根编辑器中大型根状态例如某个根视图的整棵子树状态的撤销/协作能力划清了准入线。五、测试覆盖目标与验证门禁5.1 聚焦合同测试矩阵计划要求在收口前必须存在以下聚焦覆盖测试文件路径以.tmp/slate-v2工作树为准文件必须覆盖的行为packages/slate/test/root-location-contract.tsgetOperationRoot、getPointRoot、getRangeRoot、getSelectionPatchRoot、隐式注入/剥离、根不匹配的 rangepackages/slate/test/editor-runtime-view-contract.ts在header视图内创建的 rootless point/range ref随header操作移位、忽略main操作packages/slate/test/editor-runtime-view-contract.ts从header视图发起的多块删除只编辑header内容packages/slate/test/rooted-operation-contract.tsinverseset_selection恢复main - header、header - null、null - header三种根迁移行为packages/slate/test/range-ref-contract.ts公开rangeRef.current、草稿发布、unref()保持显式/rootless 输入形态packages/slate/test/range-ref-contract.ts公开/内部 range ref 只会被匹配根的操作移除packages/slate/test/transaction-contract.ts提交的 root-scopedset_selection操作携带活跃根而中间件 payload 保持调用方形态packages/slate/test/interfaces-contract.tspoint/range 的 equality、compare、intersection 保持根感知语义packages/slate-history/test/document-state-history-contract.tsundo/redo 在编辑后恢复多根选区与根作用域 refpackages/slate/test/document-state-patch-contract.ts大型 omitted-history 状态字段缺少 patch hooks 时被拒绝覆盖红线coverage rejects同样明确不做死代码删除断言root 语义不允许只靠快照证明除非发现浏览器可见回归否则不加浏览器测试。这体现了评审矩阵中tdd视角的落地每一条行为声明都必须经由公开 editor API 证明而不只是私有 helper 的形状。5.2 门禁命令计划记录的聚焦门禁Fast Driver Gates如下注意其工作目录是.tmp/slate-v2工作树而非主检出树# cwd: /Users/zbeyens/git/plate-2/.tmp/slate-v2 bun test ./packages/slate/test/document-state-patch-contract.ts \ ./packages/slate/test/collab-document-state-contract.ts \ ./packages/slate/test/root-location-contract.ts \ ./packages/slate/test/editor-runtime-view-contract.ts \ ./packages/slate/test/rooted-operation-contract.ts \ ./packages/slate/test/range-ref-contract.ts \ ./packages/slate/test/transaction-contract.ts \ ./packages/slate/test/interfaces-contract.ts \ ./packages/slate-history/test/document-state-history-contract.ts bun typecheck:packages bun lint:fix codex review --uncommitted收口前的宽面门禁# cwd: /Users/zbeyens/git/plate-2/.tmp/slate-v2 bun test:bun bun typecheck:packages bun lint以及计划侧门禁主仓库根目录# cwd: /Users/zbeyens/git/plate-2 node tooling/scripts/completion-check.mjs计划记录的验证证据包括bun lint通过聚焦合同测试组合bun test ./packages/slate-react/test/runtime-live-state-contract.ts ./packages/slate-history/test/history-contract.ts ./packages/slate-history/test/document-state-history-contract.ts ./packages/slate/test/editor-runtime-view-contract.ts结果为87 pass, 0 failslate、slate-history、slate-react三个包的bun --filter ... typecheck全部通过用户停止评审前的部分 Codex 评审扫描也覆盖了bun lint、bun typecheck:root、git diff HEAD --check、slate-react Vitest 与bun build:packages。六、评审矩阵与维护者异议处理评审矩阵Applicable Review Matrix记录了每个视角的取舍及理由这是该计划工程纪律的缩影视角结论理由tdd应用每条行为声明必须通过公开 editor API 证明testing应用聚焦合同测试是正确层级纯核心清理不需要浏览器/e2eperformance-oracle按计划应用root 检查保持 O(1)WeakMap 元数据避免克隆只在 root 注入/剥离边界有开销vercel-react-best-practices跳过本轨道没有 React 渲染/订阅表面performance/react-useeffect/shadcn跳过无生产 RUM 声明 / 无 effect / 无 UI维护者异议台账Maintainer Objection Ledger中三条最有参考价值的交锋是“为一个小 bug 引入内部模块是不是过度抽象”——回答该 bug 横跨 point ref、range ref、operation、transform、history 与状态重放六类调用方单一 helper 才能阻止跨调用方漂移“WeakMap 隐藏元数据比公开字段更难排查”——回答它换来的是公开 point/range 值保持调用方形态避免在公开对象上挂__explicit*Root这类脏字段若未来需要ref.root的调试可见性应由最终评审决定是否把根完全收进 WeakMap 权威台账 verdict 为 “revise if review accepts”“没有浏览器证明是否够”——回答被触碰的是包内核心且有直接的 editor/history 合同测试只有出现浏览器可见回归才追加浏览器证明。Issue 记账方面计划明确声明本清理不携带任何Fixes #.../Improves #...issue 声明是附着在多根运行时语义上的内部正确性与架构清理因此 docs/slate-v2/references/pr-description.md、docs/slate-v2/ledgers/issue-coverage-matrix.md、docs/slate-v2/ledgers/fork-issue-dossier.md 三份引用文档均保持不变。七、收口过程与完成门禁一个“带停止点的收口”如何诚实记录这份计划最特别的地方在于它的 Pass-State Ledger 如实记录了一次被用户显式停止的评审循环Pass状态证据current-state read完成列出了活源码与测试创建独立 root-location 计划plan split完成本计划接管 root-location旧布局计划不再拥有该收口final-codex-review-closeout被用户停止跑了部分评审扫描用户显式停止了宽面评审循环如实记录“未得到干净的最终评审结论”completion-closeout完成作用域状态更新后node tooling/scripts/completion-check.mjs通过completion 文件指向本计划且status: done其完成门禁Final Completion Gates的定义值得注意计划被判定为 done 的条件包括“用户停止了剩余评审循环”“已返回并被接受的评审发现已修复”“聚焦的 root-location/state-field/history 门禁通过”“被触碰包的 lint 与 typecheck 通过”“无需变更 issue/引用台账”“completion 文件指向本计划且状态为 done”。计划明确写道最终的宽面 Codex review 结论被有意不宣称“The final broad Codex review verdict is intentionally not claimed”残留的宽面评审风险作为“用户显式停止”的记录被接受而不是伪造一个“最终干净评审通过”的结论。文档头部的status: done、score: 0.94等于target_score与这条诚实记录是一致的。八、关键要点单一权威原则多根编辑器的 root 推理operation/point/range/selection patch 四类来源必须收敛到一个内部模块任何调用点级的 fallback 复制都被视为漂移源公开形态契约rootless 输入在公开输出上保持 rootless显式 root 穿过 transform 与unref()存活根可见性由 WeakMap 内部元数据承载公开接口不出现root?字段求逆语义undo/选区求逆恢复的是“被恢复选区”的根身份main - header、header - null、null - header三类迁移都要有合同测试重放准入进入 history/collab 的大型状态字段必须可 patch否则注册期即拒绝使重放策略与持久化语义一致验证纪律聚焦合同测试矩阵 聚焦/宽面双层 bun 门禁 评审矩阵视角取舍 被停止的评审循环如实记录共同构成一次“可审计收口”的完整样板。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
