plate 仓库 Slate v2 公共声明对齐实践:从 experimental 到 credible replacement candidate 的文档治理

原创2026-10-10 13:51:231,616 阅读
文章标签:富文本前端UI组件插件系统

plate 仓库 Slate v2 公共声明对齐实践:从 experimental 到 credible replacement candidate 的文档治理

导读

本文以 plate 仓库中 2026-04-07-slate-v2-roadmap-public-readme-alignment.md 计划文档为核心,剖析 Slate v2 迁移计划如何治理"根 README 公共声明"与"当前发布就绪判定"之间的最后一次矛盾。你将掌握一套可复用的工程实践:如何以发布就绪决策文档为准绳修正过时的公开措辞、如何界定并保留窄幅 anchor-surface 警告、以及如何用 prettier 与 grep 完成声明对齐的机器化验证。这对任何在长周期重写/迁移项目中维护公开文档可信度的团队都有直接参考价值。

背景:Slate v2 迁移计划的文档声明体系

plate 仓库正在进行一项代号为 Slate v2 的迁移计划,其目标并非简单升级,而是以"原生事务引擎 + 快照/存储优先 API"重构 slate 核心,再按固定顺序完成 slate-history、slate-hyperscript、slate-dom、slate-react 的闭环。整个计划的当前队列与路由真值(roadmap truth)集中在 master-roadmap.md,而配套的声明体系则由 overview.md 统一管理,包括:

声明类别 所有者文档
架构声明 absolute-architecture-release-claim.md
路由顺序 master-roadmap.md
就绪判定 release-readiness-decision.md
门禁状态 replacement-gates-scoreboard.md
证明状态 true-slate-rc-proof-ledger.md

在这一体系中,文档不仅是记录,更是具有时效性的"公共声明"——任何一条措辞如果落后于当前技术判定,都会在公共面制造矛盾。本文关联的计划文档正是针对此类矛盾的收尾工作。

问题发现:根 README 中的过时声明

计划文档 2026-04-07-slate-v2-roadmap-public-readme-alignment.md 记录的核心 Finding 非常明确:

根 README 仍将 Slate 称为 "experimental replacement-candidate stack"(实验性替代候选技术栈)。

这句话与当时的发布就绪判定已经脱节。判定演进后的真实读法(current release-readiness read)是两级结构:

  • credible replacement candidate——可信的替代候选;
  • not yet an honest blanket replacement——尚不是诚实的全面替代。

也就是说,"实验性"这个措辞严重低估了项目当前的状态,而"全面替代"又会过度承诺。二者之间的精确位置,正是当时公共声明应当落位的坐标。根 README.md 作为仓库面向公众的第一入口,其措辞直接决定外部读者与 Agent 对项目成熟度的第一判断,因此这条矛盾被列为"最后一个需要移除的公共声明矛盾"。

判定基础:发布就绪决策中的两级定位

要理解为什么"实验性替代候选"是过时措辞,需要看 release-readiness-decision.md 中给出的完整判定框架。该文档当时的结论是 Not release-ready(尚未达到发布就绪),但已明确"仓库已经越过包运行时阻塞阶段",当前主责是"绝对架构计划的最终声明宽度(claim width)闭合"。

就绪门禁(Readiness Gates)包含六项硬性条件:

  1. tranche 1 根/工具链/文档通道稳定;
  2. tranche 2 React 19.2 + Next + TypeScript 6 兼容通道稳定且行为保持;
  3. 包恢复按声明顺序完成;
  4. 每个 draft 文件都有明确处置;
  5. 残留漂移要么是引擎强制、要么是明确当前价值;
  6. 其余漂移全部标记为 post RC。

其中第 5、6 条直接呼应了声明治理:漂移必须有归属,未闭合的差异必须被显式命名,而不是用"实验性"这种模糊标签一笔带过。这也是本计划文档"对齐根 README 与当前公共判定"的理论依据——声明宽度必须与可证明的技术状态一一对应。

修补方案:三步完成公共声明对齐

计划文档给出的 Patch 策略极为克制,强调"只做必要修补,不重开更大的路由栈":

第一步:对齐根 README 与当前公共判定。 将"experimental replacement-candidate stack"替换为与发布就绪决策一致的两级表述:可信的替代候选、但尚非诚实的全面替代。这一措辞的每一半都有 release-readiness-decision.md 与 true-slate-rc-proof-ledger.md 中的门禁与证明状态支撑。

第二步:保留窄幅 anchor-surface 警告。 从源码结构看,anchor surface(锚点表面)指已可对外承诺的最小稳定公开面。在 architecture-contract.md 中,这一已完成成型(release-shaped)的 anchor surface 被明确界定为:

  • Slate
  • Editable
  • withHistory(createEditor())
  • 一个规范的既有 v2 示例

计划文档要求保留这条窄幅警告而非删除它——因为"窄承诺、窄警告"正是声明宽度的精髓:公共面承诺被锚定在已验证的最小集合上,超出的部分一律不做默认承诺。

第三步:不重开更广泛的路由栈。 这条边界约束意味着:声明对齐是文档层的收敛动作,不应反向触发对 master-roadmap.md 路由顺序或包架构的重新讨论。任务边界一旦被放大,收尾工作就会重新打开早已闭合的架构议题,这正是声明治理要避免的扩散风险。

验证方式:prettier 与 grep 的机器化对齐检查

计划文档以两个已勾选([x])的验证项收尾,展示了一套最小但完整的声明对齐验证协议:

# 1. 格式门禁:确保被修改的 README 符合 prettier 规范
yarn prettier --check /Users/zbeyens/git/slate-v2/Readme.md

# 2. 内容门禁:确认过时的 experimental 措辞已从公共文档中消失
grep <experimental 相关模式> ...

其中 grep 验证的本质是对"过时声明已移除"这一结论做可复现的证据固化——不是靠人工目测,而是靠命令输出确认"stale experimental wording is gone from the public docs"。这种"修改 → 格式校验 → 内容指纹校验"的三段式协议,与仓库中同类收尾计划的验证风格完全一致。例如 2026-04-07-slate-v2-roadmap-final-spec-name-sync.md 同样用 prettier + grep 确认过时的 slate-v2/slate-dom-v2 占位包名从目标文档消失,2026-04-07-slate-v2-roadmap-historical-wording-cleanup.md 也用同一协议清理了"experimental 事务接缝"与"right next slice"等历史措辞。可见"Supporting plan + prettier/grep 验证"是 plate 仓库文档治理的标准套路。

纵深:claim width 纪律贯穿整个 Slate v2 计划

本计划文档看似只改一句话,但它背后的 claim width(声明宽度)纪律贯穿 absolute-architecture-release-claim.md 全文。该文档的 Release Limits 明确列出架构不声称的事项:

  • 并非每个历史遗留行为都能存活;
  • Chromium 单浏览器证明不等于框架级证明;
  • 语义化移动端句柄不等于原生移动端证明;
  • 纯模型测试不能证明光标行为;
  • 纯 DOM 测试不能证明 Slate 正确性;
  • Transforms.* 不是主要变更叙事。

对照之下,"experimental replacement-candidate"的过时性一目了然:它既高估了(暗示仍处于实验期),又低估了(只字未提已闭合的包运行时证明)。公共文档的措辞必须与这些精确的 claim 边界同频,这正是 replacement-gates-scoreboard.md 中四条规则的最后一条所强调的:

parity success does not close a north-star gate automatically(对等成功不会自动闭合北星门禁)。

同样地,"一句 README 措辞的修正"也不会自动扩大替代声明——声明的每一步扩大都必须由对应的门禁闭合来买单。

总结:可从本计划复用的三个治理要点

  1. 声明必须锚定判定文档,而不是锚定旧习惯。 根 README 的一句话过时,根源在于它偏离了 release-readiness-decision.md 的两级读法(可信候选 ≠ 全面替代)。修正时以判定文档为准绳,而非凭感觉措辞。

  2. 修补要窄,边界要硬。 本计划刻意"保留窄幅 anchor-surface 警告、不重开路由栈"——治理动作的范围应小于被治理对象的范围,才能避免收尾演变成新一轮架构辩论。

  3. 验证要可复现。 prettier 保证格式、grep 保证内容指纹,两条命令即可固化"过时措辞已消失"这一结论,让文档治理像代码治理一样可审计、可回放。

对于正在阅读 plate 仓库的开发者,若想追踪 Slate v2 的完整声明演进,建议按 overview.md 给出的阅读顺序,从 absolute-architecture-release-claim.md → master-roadmap.md → release-readiness-decision.md → replacement-gates-scoreboard.md → true-slate-rc-proof-ledger.md 依次阅读;其中每个文档的 front-matter 都带有 status: active 标记,意味着它们始终是活文档,而非一次性归档。

登录后查看全文
plate