Slate v2 Exact Ledgers为编辑器框架迁移建立逐文件精确映射台账的实战方案【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate导读本文基于 Slate v2 Exact Ledgers Plan 这一计划文档结合其在仓库中实际落地的台账产物完整讲解一套面向大型编辑器框架迁移的精确台账exact ledger方法论如何按作用域为每一个历史遗留文件建立 1:1 映射记录、如何用显式状态机标注每个文件的迁移去向、以及如何让主发布台账从声称详尽退回到指向证据、不再过度宣称。读完本文你将掌握一套可直接复用到自己项目的、可审计、可机器检索的迁移追踪体系。一、背景为什么需要一个精确台账而不是人工控制台账在 Slate v2 的迁移工程中仓库长期维护着一份人工控制台账human control ledger用于追踪旧版 Slatelegacy测试与源码向新架构迁移的进度。这份台账的致命问题在于它对外表现得像是穷尽的exhaustive实际上却并非如此——人工维护的条目覆盖不到每一个历史文件而读者包括维护者本人和自动化 Agent无从判断台账之外是否还有遗漏。Exact Ledgers Plan 的目标非常直白Add 1:1 exact legacy-file ledgers per scope so the repo stops pretending the human control ledger is exhaustive.即按作用域scope为每一个历史遗留文件建立 1:1 的精确台账让仓库停止假装人工控制台账是穷尽的。这是一次诚实化工程治理改造——用机械生成的、逐行的账本取代人工印象让哪些文件已被映射、哪些被显式跳过、哪些仍待裁决成为可验证的事实而不是维护者的记忆。该计划归属于整个 Slate v2 迁移程序fresh-branch 迁移的文档体系程序总览见 Slate v2 Overviewtranche 1Bun 工具链与 tranche 2React 19.2.5 / Next 16.2.4 / TypeScript 6.0.3 基线已经完成tranche 3 正在对packages/slate核心进行面向原生事务引擎的重设计。精确台账正是这个重设计 兼容性瘦身过程中的关键治理工具只有先精确知道每个旧文件去了哪里才敢对兼容性包袱做硬切割hard cut。二、范围界定四个需要精确台账的作用域计划为台账划定了四个明确的扫描范围全部集中在测试与示例领域作用域含义packages/slate/test/**Slate 核心包的遗留测试文件packages/slate-react/test/**React 绑定包的遗留测试文件packages/slate-history/test/**历史记录undo/redo包的遗留测试文件playwright/integration/examples/**Playwright 端到端示例测试范围选择很有讲究这四个目录恰好覆盖了核心逻辑测试、React 渲染测试、历史状态测试、浏览器端到端测试四个层次是迁移中最容易悄悄删文件或悄悄漏文件的区域。精确台账的第一个作用就是让删除和遗漏变得可见。从当前仓库实际落地的台账来看这四个作用域对应的文件体量差异巨大数据来自各台账的统计行核心包 legacy-slate-test-files.md 记录了1069个遗留文件是绝对大头React 包 legacy-slate-react-test-files.md 记录了8个文件历史包 legacy-slate-history-test-files.md 记录了20个文件Playwright 示例 legacy-playwright-example-tests.md 记录了23个文件。这种体量差异本身就说明问题1069 个核心测试文件如果不靠机械生成的精确台账仅凭人工记忆根本无法保证穷尽性。三、台账规则四条铁律保证账本可信计划定义了四条必须遵守的台账规则这是整个方法论的灵魂one exact row per legacy file——每个遗留文件且仅占一行不允许一个条目合并描述多个文件exact relative path keys——以精确的相对路径作为账本主键路径即身份杜绝模糊描述explicit mapping status——每个文件必须有显式的映射状态状态分为三类mapped已映射、explicit skip显式跳过、needs-triage待裁决no silent aggregation——禁止静默聚合任何这批文件都……式的笼统归类都不被允许。这四条规则本质上是在对抗台账腐化的三种典型路径漏行文件未被记录、模糊路径或状态不精确无法裁决、假穷尽用一个汇总数字假装覆盖了所有情况。值得注意的细节是计划中定义的状态是mapped / explicit skip / needs-triage三态而在实际落地时台账在mapped之下进一步细化了语义。例如 legacy-slate-test-files.md 中出现了mapped-mirrored映射-镜像旧行为在新证明文件中被直接复现共979条mapped-recovered映射-恢复旧行为通过新的契约测试间接恢复共49条mapped-mixed映射-混合旧行为被拆分到多个新证明文件或部分退役共5条explicit-skip显式跳过共36条。而 Playwright 示例台账 legacy-playwright-example-tests.md 则使用了same-path-current同路径在当前分支继续存在共 21 条这一状态表示旧测试文件在相同相对路径上被直接沿用。这印证了计划的一个设计意图状态词汇表允许在落地时扩展但显式这一约束不可妥协——每个文件必须有一个确定的状态归属。四、账本格式与真实示例TSV 三列结构从实际落地产物看每个精确台账的核心是一张 TSVTab 分隔表固定为三列legacy_file mapping_status current_owner notelegacy_file遗留文件的精确相对路径账本主键mapping_status上文的映射状态current_owner该文件迁移去向的证明文件新架构中的 owner可能为空note一行说明解释为什么是这个状态。下面从 legacy-slate-history-test-files.md 摘录三行有代表性的真实记录展示三种典型裁决legacy_file mapping_status current_owner note packages/slate-history/test/history-editor-flags.js mapped-mirrored packages/slate-history/test/history-contract.ts direct legacy history parity is proved in history-contract packages/slate-history/test/index.js explicit-skip none fixture harness entrypoint is retired packages/slate-history/test/undo/insert_text/non-contiguous.tsx explicit-skip none timing-based auto-merge heuristics are not the live contract这三行分别代表了台账中最有价值的三种信息迁移去向可追溯history-editor-flags.js的行为被镜像到新契约测试history-contract.ts中读者可以顺着current_owner直接找到它的新家删除有明确理由index.js旧的 fixture 测试入口被显式跳过理由是旧夹具入口已退役——注意状态是explicit-skip而非直接消失删除因此可审计行为放弃是决策而非疏漏non-contiguous.tsx被跳过的原因是基于时序的自动合并启发式不再是活契约——这是产品决策层面的主动放弃被显式记录避免后人误以为漏测。再看 legacy-playwright-example-tests.md 中的一个same-path-current示例legacy_file mapping_status current_owner note playwright/integration/examples/richtext.test.ts same-path-current playwright/integration/examples/richtext.test.ts same relative test path exists in slate-v2这里current_owner与legacy_file路径完全相同表示该测试在迁移后的仓库中以相同相对路径继续存活——这是最轻量的一种迁移结果。而该台账中唯一一条mapped-recovered记录select.test.ts则展示了另一种情况旧测试的三击选中段落意图被恢复到了richtext.test.ts这一现行接缝上路径虽然变了但测试意图被显式登记不会在迁移中无声丢失。五、精确台账的统计汇总一屏即可审计迁移健康度每个台账开头都有一组统计行相当于账本的审计摘要。例如核心包台账 legacy-slate-test-files.md 顶部Total legacy files1069mapped-mixed5mapped-mirrored979mapped-recovered49explicit-skip36这组数字本身就能回答迁移负责人最关心的三个问题覆盖率(979 49 5) / 1069 ≈ 96.6%的遗留文件已有明确去向风险面36 个显式跳过项必须逐一确认跳过理由成立可疑缺口如果mapped与explicit-skip之和小于总数就意味着存在needs-triage悬置项需要优先裁决。各台账汇总对比均来自各 ledger 文件的统计行台账总数已映射/沿用显式跳过其他legacy-slate-test-files.md10691033mirrored 979 recovered 49 mixed 536—legacy-slate-react-test-files.md86mirrored 5 mixed 12—legacy-slate-history-test-files.md2017mirrored3—legacy-playwright-example-tests.md2322same-path-current 21 recovered 11—六、与主发布台账的联动停止过度宣称计划的退出条件Exit有两条缺一不可精确台账必须存在于docs/slate-v2/ledgers/下——即上面讨论的四个 ledger 文件它们统一登记在 ledgers/README.md 这个索引中并附有状态词汇表recovered / extended / mixed / open / post RC / cut主发布文件台账必须指向这些精确台账并停止过度宣称穷尽性。第二点是整份计划的关键治理动作。主发布台账即 release-file-review-ledger.md它服务于整个 fresh-branch 程序的逐文件迁移真相per-file migration truth。该台账的Remaining-Work Rule一节明确写了三条纪律剩余工作由合并语料驱动、按行作用域推进本台账不授权对剩余包做无差别的同路径重写也不把避免重写本身当作价值。随后给出了诚实的下一步顺序先围绕原生事务/快照存储 API 敲定packages/slate核心再显式分类兼容性包袱而不是凭反射保留最后才重开支持包的迁移。这正是精确台账体系的闭环精确账本让剩余工作可以被按行认领也让不做什么成为显式决策。台账还特别标注了post RC状态的延期行如仓库级 ESLint 源码强制、slate-browser 根级证明通道进一步说明未完成是诚实声明的状态而非被静默掩盖的缺口。七、方法论提炼如何在自己的迁移工程中落地这套体系Exact Ledgers Plan 虽为 Slate v2 量身定制但它的四条规则与三种状态完全可以抽象为通用迁移治理模板1. 用机械扫描替代人工枚举。台账的原始素材来自对**/test/**等目录的文件级扫描而不是维护者回忆。任何迁移项目的账本都应从find/ glob 结果生成保证账本行数 实际文件数。2. 路径即主键状态必显式。每个文件一行、以精确相对路径为主键杜绝X 目录下的文件基本都迁移了这类模糊描述。无法立即裁决的文件标needs-triage让悬置项浮出水面而不是沉入遗忘。3. 细粒度状态表达迁移语义。mapped-mirrored行为被镜像复现、mapped-recovered行为被新契约间接恢复、same-path-current同路径沿用、explicit-skip显式放弃附理由——状态词汇越贴近迁移语义账本的可审计性越强。其中explicit-skip是最容易被忽视却最有价值的一类它把删除从事故变成决策。4. 主台账只做指针不做复制。顶层发布台账不应重复维护细节而应像 release-file-review-ledger.md 那样指向作用域级精确台账本文对应的四个 ledger 均在 ledgers 目录 下并诚实声明哪些部分仍在post RC或open状态。这样既保留了顶层可读性又把穷尽性责任下放到可验证的账本。5. 把审计摘要放在账本头部。每个台账顶部用三行数字总数 / 已映射 / 显式跳过给出健康度快照让 CI 或人工巡检可以秒级判断是否有未裁决文件、跳过项是否失控、迁移是否真正闭合。八、执行状态与文档定位截至当前仓库快照Exact Ledgers Plan 的状态为in_progress见 计划文档 的 frontmatter但其核心产物——四个作用域的精确台账——均已实际生成并持续维护日期标注为 2026-04-13 至 2026-04-14且generated: true标记表明这些账本由工具生成而非人工手写这正是no silent aggregation原则的机器保证。后续的 ledgers/README.md2026-04-16进一步将其纳入了 fresh-branch 迁移的活文档体系。对于希望深入研究的读者建议按以下路径阅读先读本计划 2026-04-13-slate-v2-exact-ledgers-plan.md 建立问题意识再读 ledgers/README.md 了解台账目录全景与状态词汇按需深入四个账本核心包 legacy-slate-test-files.md体量最大最能体现方法论价值、React 包 legacy-slate-react-test-files.md、历史包 legacy-slate-history-test-files.md、Playwright 示例 legacy-playwright-example-tests.md最后回到主台账 release-file-review-ledger.md观察顶层台账如何引用下级账本并诚实声明边界。这套精确台账体系的核心启示可以浓缩为一句话在大型迁移工程中可信的进度不来自维护者的自信声明而来自每一个文件都有显式归宿的可验证账本。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考