plate 仓库 Slate v2 公共声明对齐实践:从 experimental 到 credible replacement candidate 的文档治理
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)包含六项硬性条件:
- tranche 1 根/工具链/文档通道稳定;
- tranche 2 React 19.2 + Next + TypeScript 6 兼容通道稳定且行为保持;
- 包恢复按声明顺序完成;
- 每个 draft 文件都有明确处置;
- 残留漂移要么是引擎强制、要么是明确当前价值;
- 其余漂移全部标记为
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 被明确界定为:
SlateEditablewithHistory(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 措辞的修正"也不会自动扩大替代声明——声明的每一步扩大都必须由对应的门禁闭合来买单。
总结:可从本计划复用的三个治理要点
-
声明必须锚定判定文档,而不是锚定旧习惯。 根 README 的一句话过时,根源在于它偏离了 release-readiness-decision.md 的两级读法(可信候选 ≠ 全面替代)。修正时以判定文档为准绳,而非凭感觉措辞。
-
修补要窄,边界要硬。 本计划刻意"保留窄幅 anchor-surface 警告、不重开路由栈"——治理动作的范围应小于被治理对象的范围,才能避免收尾演变成新一轮架构辩论。
-
验证要可复现。 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 标记,意味着它们始终是活文档,而非一次性归档。