Slate v2 重构中的包命名同步从*-v2占位符到冻结包名的文档治理实战【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文围绕 plate 仓库中 Slate v2 重构过程中的一份关键治理文档docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md展开讲解如何在大型编辑器重构中保持活跃规格文档active spec与冻结包地图frozen package map的命名一致发现占位符包名残留、统一到真实包名、并以 prettier 与 grep 双通道完成验证。读完本文你将掌握一套可复用的包命名冻结 文档同步 命令化验证工程方法也能理解 plate 仓库中slate、slate-dom、slate-react、slate-history等包名的权威定义位置与迁移主线。背景plate 仓库中的 Slate v2 重构主线plate 是一个面向 AI 与 shadcn/ui 的富文本编辑器项目其仓库以 pnpm workspace 管理数十个包packages/目录下包含slate、core、table、markdown等。在 2026 年 4 月的开发主线中仓库正在执行一项代号为 Slate v2 的深度重构——对编辑器内核进行大规模重写并将文档体系拆分为活跃文档docs/slate-v2/**与归档草稿docs/slate-v2-draft/**两个独立目录。这一主线的权威路线图是 docs/slate-v2/master-roadmap.md其中明确给出了冻结的包顺序Package Orderslateslate-historyslate-hyperscriptslate-domslate-react此外还有一个已落地的早期附加车道early additive laneslate-browser。master-roadmap 同时定义了 8 个 tranche从根工具链迁移、React 19.2 兼容到slate核心读写事务、slate-dom/slate-react运行时收口再到示例/基准与 RC 收尾并设置了两个不可妥协的门禁parity gate对等门禁与v2 north-star gate北极星门禁。包名在这个重构中不是小事它们既是 npm 发布名、源码目录名也是规格文档、示例、测试与基准脚本中被反复引用的标识符。一旦规格文档里出现与冻结包地图不一致的名字整条迁移链上的代码引用、文档链接和搜索都会失真。问题发现活跃规格文档混用了占位符包名本计划文档的 Finding 部分记录了一个具体问题活跃规格文档active specs仍在真实包名与旧占位符之间混用。具体残留的占位符包括slate-v2slate-dom-v2slate-react-v2这些旧名与已冻结的包地图以及公共包文档public package docs相矛盾。与之配套的姊妹计划 2026-04-07-slate-v2-roadmap-package-name-normalization.md 给出了更细的定位core-foundation-spec.md仍以slate-v2、slate-dom-v2、slate-react-v2指代包名dom-runtime-boundary-spec.md仍使用slate-dom-v2与slate-react-v2chunking-review.md仍把运行时目标描述为slate-react-v2。这种混用的危害在于规格文档是契约层贡献者、Agent 与后续 tranche 的执行者都会依据文档里的包名去定位源码、运行命令、引用 API。占位符与真实包名并存会让文档说了什么与仓库里有什么产生系统性偏差。权威包名的仓库证据package.json 与 ledgers为什么说真实包名是明确的、可验证的可以从仓库中找到三处权威证据1. 包清单package manifestpackages/slate/package.json 中声明name: platejs/slate, version: 53.3.10, description: Slate extension, dependencies: { udecode/utils: workspace:^, is-plain-object: ^5.0.0, lodash: ^4.17.21, scroll-into-view-if-needed: ^3.1.0, slate: 0.126.2, slate-dom: 0.126.0 }可以看到发布名是platejs/slatenpm scope 下的slate依赖中直接使用社区标准包slate与slate-dom作为底层。也就是说重构后的包名不带-v2后缀。2. API 台账ledgersdocs/slate-v2/ledgers/目录下按真实包名建立了公共 API 台账例如 slate-react-api.md、slate-history-api.md、slate-interfaces-api.md、slate-transforms-api.md 等。这些文件名本身就是冻结包名的体现。3. 路线图控制文档docs/slate-v2/master-roadmap.md 的 Package Order 章节与每个 tranche 的小节标题如 Tranche 3 标题为slateRead/Update Transaction Core、Tranche 5 为slate-dom、Tranche 6 为slate-react全部使用无-v2后缀的正式名。修复方案将活跃规格与 north-star 文档统一到真实包名计划文档给出的 Patch修补动作非常明确——把活跃规格文档与 north-star 文档中的包名全部归一化到真实包名slate-v2→slateslate-dom-v2→slate-domslate-react-v2→slate-react并且最终目标列表比 Finding 中提到的三个占位符多出一项slate-history。这一点很关键它说明命名同步不只是一次简单的去掉-v2后缀而是与 master-roadmap 的完整包顺序对齐——既然包顺序里包含slate-history那么规格文档里凡是涉及该包的表述也必须使用slate-history这个正式名。从 chunking-review.md 可以看到归一化之后的表述范式文档以slate-react指代 React 运行时如child-count chunking is legacy-onlythe deleted chunking tree in legacyslate-react以slate-react/slate-dom讨论运行时边界不再出现-v2形式的包名。这份文档同时印证了命名同步的实际收益统一包名之后性能与架构讨论如 selector-first 渲染、语义孤岛、active corridor才能被稳定地锚定到具体包上。为什么slate-history也要纳入同步slate-history是重构中的独立支持包负责撤销/重做栈等历史能力。在 master-roadmap 的 Tranche 4 中slate-history与slate-hyperscript是成对收口的包lossless closure其契约证明位于history-contract.ts与integrity-contract.ts。因此命名同步覆盖slate-history是为了保证规格文档里提到的每一个包都能在冻结包地图中找到唯一对应项。验证prettier grep 双通道计划文档的 Verification 部分记录了两步验证均已完成[x]第 1 步prettier 格式检查原计划记录的命令使用机器专属绝对路径转换为仓库根目录相对路径后等价于pnpm exec prettier --check \ docs/slate-v2/references/chunking-review.md \ docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md \ docs/plans/2026-04-07-slate-v2-roadmap-package-name-normalization.md原计划按当时文档结构还校验了engine.md、core-foundation-spec.md、dom-runtime-boundary-spec.md等规格文档在当前快照中docs/slate-v2/目录已重组为以 master-roadmap、ledgers、references 为主的形态但 prettier 校验的思路不变格式检查保证批量替换没有破坏文档排版。第 2 步grep 确认陈旧占位符彻底消失# 在活跃文档中确认不存在旧占位符包名 grep -rn --include*.md -E slate-v2|slate-dom-v2|slate-react-v2 docs/slate-v2 docs/plans || echo no stale placeholder package names foundgrep 的目标不是改了多少处而是旧名归零——只有零残留才能宣告命名同步完成。这两步构成一个典型的修改 机器验证闭环prettier 负责格式层grep 负责语义层缺一不可。可推广的验证模板对于任何大型重构中的命名统一这套模板可以直接复用# 1) 格式验证所有被修改/引用的文档必须通过 prettier pnpm exec prettier --check 被改文档列表 # 2) 语义验证旧占位符/旧名必须在目标范围内归零 grep -rn -E 旧名A|旧名B 文档目录 || echo clean # 3) 交叉验证新名在权威位置package.json / ledgers / roadmap确实存在 grep -n name packages/slate/package.json从命名同步看 plate 的文档治理纪律这份计划虽小却折射出 plate 仓库在 Slate v2 重构中反复强调的一条治理规则。master-roadmap 的 Review Rule 明确写道If the merged corpus changes the active claim, sync the control docs before the next package starts.若合并语料改变了当前主张必须在下一个包启动前同步控制文档。本计划的执行正是这条规则的具体落地规格文档控制文档的一种中出现了与冻结包地图冲突的表述因此在进入下一个包当时slate-dom即将开始之前必须先完成命名同步。与之配套的还有 master-roadmap Execution Doctrine 中的一条原则same-path/source-close pressure stays strongest for docs, examples, and public package surfaces——文档、示例与公共包表面是受同路径/同源约束最强的区域任何漂移都会直接传导给使用方。这套纪律可以总结为三条可操作的工程实践命名冻结先行重构启动时就锁定正式包名slate、slate-dom、slate-react、slate-history、slate-hyperscript外加早期车道slate-browser并让 package.json、ledgers、roadmap 三处互为校验基准文档即契约规格文档中出现的每个包名都必须能在冻结包地图中找到唯一对应项禁止在文档里使用任何工作代号式占位符如*-v2验证命令化每次命名类改动都要附带 prettier格式与 grep语义两步验证并把验证结果以[x]形式写回计划文档形成可审计的闭环。结语docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md是一次小成本、高杠杆的治理动作通过把活跃规格文档中的slate-v2、slate-dom-v2、slate-react-v2占位符统一为slate、slate-dom、slate-react并纳入slate-historyplate 仓库确保了文档体系与冻结包地图、公共包文档、源码目录和基准脚本保持同一种语言。对于正在维护大型 monorepo 重构的团队这份计划提供了一个现成的参考范式——当文档与代码对同一个包出现两种叫法时问题不在命名本身而在缺少一次像这样的命名同步专项治理。相关权威依据可继续查阅 docs/slate-v2/master-roadmap.md、packages/slate/package.json 与姊妹计划 2026-04-07-slate-v2-roadmap-package-name-normalization.md。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Slate v2 重构中的包命名同步从*-v2占位符到冻结包名的文档治理实战【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文围绕 plate 仓库中 Slate v2 重构过程中的一份关键治理文档docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md展开讲解如何在大型编辑器重构中保持活跃规格文档active spec与冻结包地图frozen package map的命名一致发现占位符包名残留、统一到真实包名、并以 prettier 与 grep 双通道完成验证。读完本文你将掌握一套可复用的包命名冻结 文档同步 命令化验证工程方法也能理解 plate 仓库中slate、slate-dom、slate-react、slate-history等包名的权威定义位置与迁移主线。背景plate 仓库中的 Slate v2 重构主线plate 是一个面向 AI 与 shadcn/ui 的富文本编辑器项目其仓库以 pnpm workspace 管理数十个包packages/目录下包含slate、core、table、markdown等。在 2026 年 4 月的开发主线中仓库正在执行一项代号为 Slate v2 的深度重构——对编辑器内核进行大规模重写并将文档体系拆分为活跃文档docs/slate-v2/**与归档草稿docs/slate-v2-draft/**两个独立目录。这一主线的权威路线图是 docs/slate-v2/master-roadmap.md其中明确给出了冻结的包顺序Package Orderslateslate-historyslate-hyperscriptslate-domslate-react此外还有一个已落地的早期附加车道early additive laneslate-browser。master-roadmap 同时定义了 8 个 tranche从根工具链迁移、React 19.2 兼容到slate核心读写事务、slate-dom/slate-react运行时收口再到示例/基准与 RC 收尾并设置了两个不可妥协的门禁parity gate对等门禁与v2 north-star gate北极星门禁。包名在这个重构中不是小事它们既是 npm 发布名、源码目录名也是规格文档、示例、测试与基准脚本中被反复引用的标识符。一旦规格文档里出现与冻结包地图不一致的名字整条迁移链上的代码引用、文档链接和搜索都会失真。问题发现活跃规格文档混用了占位符包名本计划文档的 Finding 部分记录了一个具体问题活跃规格文档active specs仍在真实包名与旧占位符之间混用。具体残留的占位符包括slate-v2slate-dom-v2slate-react-v2这些旧名与已冻结的包地图以及公共包文档public package docs相矛盾。与之配套的姊妹计划 2026-04-07-slate-v2-roadmap-package-name-normalization.md 给出了更细的定位core-foundation-spec.md仍以slate-v2、slate-dom-v2、slate-react-v2指代包名dom-runtime-boundary-spec.md仍使用slate-dom-v2与slate-react-v2chunking-review.md仍把运行时目标描述为slate-react-v2。这种混用的危害在于规格文档是契约层贡献者、Agent 与后续 tranche 的执行者都会依据文档里的包名去定位源码、运行命令、引用 API。占位符与真实包名并存会让文档说了什么与仓库里有什么产生系统性偏差。权威包名的仓库证据package.json 与 ledgers为什么说真实包名是明确的、可验证的可以从仓库中找到三处权威证据1. 包清单package manifestpackages/slate/package.json 中声明name: platejs/slate, version: 53.3.10, description: Slate extension, dependencies: { udecode/utils: workspace:^, is-plain-object: ^5.0.0, lodash: ^4.17.21, scroll-into-view-if-needed: ^3.1.0, slate: 0.126.2, slate-dom: 0.126.0 }可以看到发布名是platejs/slatenpm scope 下的slate依赖中直接使用社区标准包slate与slate-dom作为底层。也就是说重构后的包名不带-v2后缀。2. API 台账ledgersdocs/slate-v2/ledgers/目录下按真实包名建立了公共 API 台账例如 slate-react-api.md、slate-history-api.md、slate-interfaces-api.md、slate-transforms-api.md 等。这些文件名本身就是冻结包名的体现。3. 路线图控制文档docs/slate-v2/master-roadmap.md 的 Package Order 章节与每个 tranche 的小节标题如 Tranche 3 标题为slateRead/Update Transaction Core、Tranche 5 为slate-dom、Tranche 6 为slate-react全部使用无-v2后缀的正式名。修复方案将活跃规格与 north-star 文档统一到真实包名计划文档给出的 Patch修补动作非常明确——把活跃规格文档与 north-star 文档中的包名全部归一化到真实包名slate-v2→slateslate-dom-v2→slate-domslate-react-v2→slate-react并且最终目标列表比 Finding 中提到的三个占位符多出一项slate-history。这一点很关键它说明命名同步不只是一次简单的去掉-v2后缀而是与 master-roadmap 的完整包顺序对齐——既然包顺序里包含slate-history那么规格文档里凡是涉及该包的表述也必须使用slate-history这个正式名。从 chunking-review.md 可以看到归一化之后的表述范式文档以slate-react指代 React 运行时如child-count chunking is legacy-onlythe deleted chunking tree in legacyslate-react以slate-react/slate-dom讨论运行时边界不再出现-v2形式的包名。这份文档同时印证了命名同步的实际收益统一包名之后性能与架构讨论如 selector-first 渲染、语义孤岛、active corridor才能被稳定地锚定到具体包上。为什么slate-history也要纳入同步slate-history是重构中的独立支持包负责撤销/重做栈等历史能力。在 master-roadmap 的 Tranche 4 中slate-history与slate-hyperscript是成对收口的包lossless closure其契约证明位于history-contract.ts与integrity-contract.ts。因此命名同步覆盖slate-history是为了保证规格文档里提到的每一个包都能在冻结包地图中找到唯一对应项。验证prettier grep 双通道计划文档的 Verification 部分记录了两步验证均已完成[x]第 1 步prettier 格式检查原计划记录的命令使用机器专属绝对路径转换为仓库根目录相对路径后等价于pnpm exec prettier --check \ docs/slate-v2/references/chunking-review.md \ docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md \ docs/plans/2026-04-07-slate-v2-roadmap-package-name-normalization.md原计划按当时文档结构还校验了engine.md、core-foundation-spec.md、dom-runtime-boundary-spec.md等规格文档在当前快照中docs/slate-v2/目录已重组为以 master-roadmap、ledgers、references 为主的形态但 prettier 校验的思路不变格式检查保证批量替换没有破坏文档排版。第 2 步grep 确认陈旧占位符彻底消失# 在活跃文档中确认不存在旧占位符包名 grep -rn --include*.md -E slate-v2|slate-dom-v2|slate-react-v2 docs/slate-v2 docs/plans || echo no stale placeholder package names foundgrep 的目标不是改了多少处而是旧名归零——只有零残留才能宣告命名同步完成。这两步构成一个典型的修改 机器验证闭环prettier 负责格式层grep 负责语义层缺一不可。可推广的验证模板对于任何大型重构中的命名统一这套模板可以直接复用# 1) 格式验证所有被修改/引用的文档必须通过 prettier pnpm exec prettier --check 被改文档列表 # 2) 语义验证旧占位符/旧名必须在目标范围内归零 grep -rn -E 旧名A|旧名B 文档目录 || echo clean # 3) 交叉验证新名在权威位置package.json / ledgers / roadmap确实存在 grep -n name packages/slate/package.json从命名同步看 plate 的文档治理纪律这份计划虽小却折射出 plate 仓库在 Slate v2 重构中反复强调的一条治理规则。master-roadmap 的 Review Rule 明确写道If the merged corpus changes the active claim, sync the control docs before the next package starts.若合并语料改变了当前主张必须在下一个包启动前同步控制文档。本计划的执行正是这条规则的具体落地规格文档控制文档的一种中出现了与冻结包地图冲突的表述因此在进入下一个包当时slate-dom即将开始之前必须先完成命名同步。与之配套的还有 master-roadmap Execution Doctrine 中的一条原则same-path/source-close pressure stays strongest for docs, examples, and public package surfaces——文档、示例与公共包表面是受同路径/同源约束最强的区域任何漂移都会直接传导给使用方。这套纪律可以总结为三条可操作的工程实践命名冻结先行重构启动时就锁定正式包名slate、slate-dom、slate-react、slate-history、slate-hyperscript外加早期车道slate-browser并让 package.json、ledgers、roadmap 三处互为校验基准文档即契约规格文档中出现的每个包名都必须能在冻结包地图中找到唯一对应项禁止在文档里使用任何工作代号式占位符如*-v2验证命令化每次命名类改动都要附带 prettier格式与 grep语义两步验证并把验证结果以[x]形式写回计划文档形成可审计的闭环。结语docs/plans/2026-04-07-slate-v2-roadmap-final-spec-name-sync.md是一次小成本、高杠杆的治理动作通过把活跃规格文档中的slate-v2、slate-dom-v2、slate-react-v2占位符统一为slate、slate-dom、slate-react并纳入slate-historyplate 仓库确保了文档体系与冻结包地图、公共包文档、源码目录和基准脚本保持同一种语言。对于正在维护大型 monorepo 重构的团队这份计划提供了一个现成的参考范式——当文档与代码对同一个包出现两种叫法时问题不在命名本身而在缺少一次像这样的命名同步专项治理。相关权威依据可继续查阅 docs/slate-v2/master-roadmap.md、packages/slate/package.json 与姊妹计划 2026-04-07-slate-v2-roadmap-package-name-normalization.md。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
