Plate 仓库 Slate v2 文档栈整合:分层目录、归档策略与单一所有权治理

原创2026-09-15 09:54:541,904 阅读
文章标签:富文本前端UI组件插件系统

Plate 仓库 Slate v2 文档栈整合:分层目录、归档策略与单一所有权治理

本文基于 Plate 仓库中的执行计划 2026-04-12-slate-v2-doc-stack-consolidation.md,完整还原一次真实的大规模编辑器迁移项目中“文档栈(doc stack)整合”的全过程:先讲清楚为什么要整合,再逐项拆解整合前的审计发现与整合动作(降权、合并、归档、迁移、所有权收敛),最后结合当前仓库中 docs/slate-v2/ 的实际目录结构,说明一套可复用的“活动控制面文档 / 参考文档 / 归档文档”三层治理方法,适合任何长期多阶段重构项目参考。

一、背景与目标:为什么活动队列文档不能与历史资料混放

Plate 仓库(一个基于 React 的富文本编辑器框架,项目定位为 "Rich-text editor with AI and shadcn/ui")内部有一条跨度数月的 Slate v2 迁移工程,其控制面文档集中在 docs/slate-v2/,执行计划集中在 docs/plans/(该目录累计沉淀了数百份带日期的执行计划文档)。

整合计划开篇给出了一个非常具体的目标(原文 Goal 小节,计划文档 L9-L11):

Tighten the live docs/slate-v2 stack so active queue docs stop mixing with legacy/reference material.

收紧实时的 docs/slate-v2 文档栈,让“活动队列文档”不再与“遗留/参考资料”混杂。

这个目标背后有一个长期维护多阶段工程时的通病:

  • 活动文档(回答“现在该干什么、当前裁决是什么”)与参考文档(回答“当年的设计形态和兼容背景是什么”)如果混在同一个目录根下,读者和 Agent 无法快速判断哪份文档拥有当前事实(current truth);
  • 随着迁移推进,大量阶段性文档(批次引擎讨论、性能记分板、归一化基线矩阵等)会逐步失去“队列所有者”身份,但只要它们还留在活动目录里,就会持续产生误导;
  • 文档之间的相对引用会在移动后断链,如果不显式修补,历史文档就变成“考古死角”。

因此这次整合不是一次简单的目录清理,而是一次文档所有权的重新分配:每一份文档要么明确成为某类事实的唯一 owner,要么被显式降级为 historical/reference 状态,要么被归档。

二、整合前的审计发现(Findings)

整合计划用四个 Findings 确立了“可以安全动手”的前提(计划文档 L14-L25)。这四点都值得单独展开,因为它们是判断“文档栈能否开始收敛”的客观依据。

2.1 零回归 diff 种子为空(EMPTY):没有隐藏未审文件

第一条 Finding 指出,IME / Mobile / Browser 文件台账 中固定的“零回归 diff 种子”结果是 EMPTY——也就是说,在当前 origin/main...HEAD 的 diff 范围内,没有隐藏的、未审查的浏览器/输入相关文件。

该台账固定了一个具体的 diff 检查命令(台账文档 L43-L56):

git -C /Users/zbeyens/git/slate-v2 diff --name-status --diff-filter=ACDMRTUXB origin/main...HEAD -- \
  packages/slate-react \
  packages/slate-dom \
  packages/slate-browser \
  playwright/integration/examples \
  site/examples/ts

其结论的读法(台账原文)是:

  • 当前 origin/main...HEAD 针对这些目标目录的 diff 中没有仍未审查的浏览器/输入行;
  • 因此台账的种子(seed)来自“活动证明轨道 + 遗留行为相关补丁文件本身”,而不是未审差异。

这一条的意义在于:归档与移动文档之前,必须先证明活动队列本身是干净的。如果 diff 里还藏着未审文件,那么把旧文档移走只会让“未审工作”失去参照系。EMPTY 种子是整个整合可以安全执行的前置条件。

2.2 行为/一致性台账全行已审

第二条 Finding:行为/一致性(behavior/parity)台账中的每一行都已完成审查(“Every row in the behavior/parity ledger is reviewed”)。结合上一条,说明浏览器/输入一致性轨道的本地工作已经收敛,剩下的不再是“本地没审完”,而是外部约束。

2.3 剩余未完成的一致性工作受外部/工具限制

第三条 Finding 明确列出了剩余的未完成一致性工作(open parity work),并给出关键定性:它们都是外部/工具受限(external/tooling-limited)的,具体为两项:

  • Android 键盘特性(autocorrect / glide / voice 一类需要真实键盘交互栈的证据);
  • 更广泛的 iOS Safari 合成(composition)/ 焦点(focus)行为证据。

这个定性直接影响了文档栈的收敛方式:既然剩余工作不在本地代码轨道上,那么本地控制面文档就可以放心收敛到“当前裁决 + 门限记分板”的形态,而不需要为这些外部轨道保留大量活动文档。

2.4 batch-engine 与 chunking 文档是“有用的历史”,不是活动队列所有者

第四条 Finding 点名了两份文档:slate-batch-engine.md(批次引擎参考)与 chunking-review.md(分块审查参考),判定它们是 useful history, not live queue owners——有用的历史资料,但不是活动队列的所有者。

这一点与两份文档当前的自述状态互相印证。例如 slate-batch-engine.md 的“Purpose / Rule”小节明确写道:

  • 目的:“Keep the current batch-engine context available without letting it quietly own the live queue”(保留当前 batch-engine 上下文,但不让它悄悄拥有活动队列);
  • 规则:“This is a reference doc, not a remaining-work owner”(这是参考文档,不是剩余工作所有者),并且明确不得用它去推翻已合并的契约语料决策、路线图顺序和就绪状态裁决;
  • 当前读法:“this doc does not define the active packages/slate direction anymore”(本文档不再定义 packages/slate 的活动方向),活动方向已转向 architecture-contract.md 中的原生 transaction/store-first 重设计。

这正是“降权(demote)”操作的典型写法:文档不动内容,但用显式的前置声明切断它作为队列所有者的资格。

三、整合动作(Cleanup)逐项拆解

整合计划的核心是 Cleanup 小节(计划文档 L27-L55)。以下按原文档动作清单逐项展开,并对照当前仓库中可验证的最终落点。

3.1 降权:batch-engine 与 chunking 文档转为显式历史/参考状态

动作原文:“demoted batch-engine and chunking docs to explicit historical/reference status”。

对应的就是上一节引用的 slate-batch-engine.md 的自述规则,以及 chunking-review.md 的同类定位。降权的价值在于:文档没有删除,知识仍然可查,但它不能再作为“剩余工作”的依据被 Agent 或维护者误读。

3.2 合并:把活动的归一化读法收敛进单一参考

动作原文:“merged the live normalization read into normalization-reference.md”,即把散落在多处文档里的“当前归一化(normalization)姿态”合并进 normalization-reference.md。

该文档当前的内容形态也印证了“单一活动参考”的目标:

  • Purpose:“Single live reference for the current normalization posture”(当前归一化姿态的单一活动参考);
  • Current Read:保持“默认 vs 显式”归一化契约封闭;不要随意重开宽泛的默认期强制修正;当前契约有意比旧版 Slate 更窄;把 explicit-only 清理提升为普通 commit 行为属于真正的公共契约变更;
  • Contract Summary:默认活动行为只保留正确性所需的不变量;更重的清理保留在显式或应用拥有的接缝上——Editor.normalize()、load / replace / reset、import / paste 摄入、应用自有的 normalizeNode(...);
  • Phase Boundary Read:引擎在发布前只有一个归一化阶段,publish 不是第二层归一化层级,commit 规范化尚不存在。

把归一化契约收敛到单一文件,是“每类事实只有一个 owner”原则的直接应用:后续任何关于归一化姿态的讨论,只需要更新这一份文档。

3.3 归档:六份阶段性文档退出活动栈

动作原文列出了六个被归档(archived)的文件:

被归档文档 主题
api-drift-perf-register.md API 漂移与性能登记
api-drift-perf-scoreboard.md API 漂移与性能记分板
api-surface-keep-cut-register.md API 表面 keep/cut 登记
normalization-baseline-matrix.md 归一化基线矩阵
normalization-phase-boundary-note.md 归一化阶段边界说明
normalization-reopen-verdict.md 归一化重开裁决

从当前仓库结构看,这六份文档现均位于 docs/slate-v2-draft/archive/ 下(例如 api-drift-perf-register.md、api-drift-perf-scoreboard.md、api-surface-keep-cut-register.md、normalization-baseline-matrix.md、normalization-phase-boundary-note.md、normalization-reopen-verdict.md)。docs/slate-v2-draft/archive/README.md 用一句话框定了归档区的身份:“Archive only. Historical reference doc. ... These files are for archaeology, not the current replacement verdict.”(仅归档。历史参考文档。这些文件用于考古,而非当前替换裁决。)

值得注意的是,归档文档的“主题”(API 漂移、性能记分、归一化基线)与“活动门限”并不矛盾——活动状态仍由 replacement-gates-scoreboard.md 承载(见 3.6 节)。也就是说,归档的是“阶段性工作文档”,而它所服务的事实类型(性能门限、API 表面裁决)在活动文档中保留了指向当前 owner 的入口。

3.4 修补引用:移动之后所有链接必须仍可解析

动作原文:“patched live and historical references so the moved docs still resolve”——修补活动与历史文档中的引用,使被移动的文档仍然可以解析。

这是对“文档移动”风险的标准对冲:在大规模文档迁移中,最隐蔽的破坏不是文件丢失,而是旧文档中的相对链接指向已移动的路径。这次整合把“修补引用”列为与移动本身同级的动作,而不是善后步骤,保证了历史文档在归档后依旧可以作为导航网络的一部分被读取。

3.5 前门重定向:front-door 文档只指向当前 owner

动作原文:“made the front-door docs point at the live parity, verdict, and normalization owners instead of implying batch-engine/chunking are still active candidates”——让前门(front-door)文档指向活动的一致性 owner、裁决 owner 和归一化 owner,而不是暗示 batch-engine/chunking 仍是活跃候选。

当前仓库中前门文档的形态可以具体验证这一条的落点:

Do Not Read First 这一节是“前门重定向”在 Agent 协作场景下的具体化:参考文档仍然存在且有用,但阅读优先级由入口文档显式规定,避免 Agent 从历史设计文档出发推导出过时的“当前状态”。

3.6 所有权收敛:blocker 与 perf-gate 各有唯一裁决文件

整合计划最后两条动作把所有权从多份文档中收敛到两个裁决文件:

  1. “merged blocker ownership into release-readiness-decision.md”:阻塞项的所有权合并进 release-readiness-decision.md。该文档当前形态完全符合“唯一裁决 owner”的职责:Current Verdict(当前裁决:Not release-ready)、Readiness Gates(六条 RC 就绪门限)、Current Blockers(当前阻塞清单)、Current Claim Width(当前声明宽度,逐条列出哪些包是 green、哪些证据 owner 活着、以及“no blanket RC claim beyond that narrower package/runtime truth is live yet”这类对声明范围的显式收紧)。
  2. “merged perf-gate ownership into replacement-gates-scoreboard.md”:性能门限的所有权合并进 replacement-gates-scoreboard.md。该文档以三张表 + 规则承载活动门限状态:
    • Tranche Gates 表:按 tranche(批次轨道)逐行列出 complete / pending 状态与依据说明;
    • V2 North-Star Gates 表:每条北极星门限都绑定当前 owner 文档 + 当前证明/命令 owner + 当前读法,例如 “React runtime locality” 绑定命令 bun run bench:react:rerender-breadth:local,而 “slate-react perf superiority vs legacy chunking” 仍标记为 pending / typing red;
    • Command Reality 小节:列出当前真实可运行的门限命令全集(bun run test、bun run test:integration-local 以及十余条 bench:* 命令),并附“core perf regression coverage is complete-but-selective”这类精确的覆盖度定性;
    • Rules 小节给出四条铁律,其中两条值得直接引用:
      • a gate is not green because nearby proof is green
      • parity success does not close a north-star gate automatically

      (邻近证据绿不代表门限绿;一致性成功不会自动关闭北极星门限。)

这两条规则解释了为什么所有权必须收敛:如果一个事实可以由 N 份文档分别表述,那么 N 份文档里只要有一份过期,裁决就失真。收敛后,判定“门限是否绿”只查记分板,判定“是否可发布”只查裁决文档。

3.7 终态:活动根目录只剩 9 份 owner 文档

整合计划收束于一条可计量的终态声明:

live docs/slate-v2/*.md root is now down to 9 owner docs

活动的 docs/slate-v2/*.md 根目录收敛到 9 份 owner 文档。

对照当前仓库快照,docs/slate-v2/ 根目录下的顶层 .md 文件已包含 overview.md、master-roadmap.md、release-readiness-decision.md、replacement-gates-scoreboard.md、agent-start.md 等文件(其中 agent-start.md 的 frontmatter 日期为 2026-05-30,晚于本次整合日期)。可以推断:“9 份 owner 文档”是 2026-04-12 完成时的快照口径,此后文档栈仍在按同一治理规则演进(新增的 Agent 入口文档即为例证),但根目录“只放 owner 文档”的结构不变:参考类文档位于 references/(如 architecture-contract.md、live-shape-register.md、normalization-reference.md、chunking-review.md、slate-batch-engine.md),台账类文档位于 ledgers/,操作命令文档位于 commands/。

计划中“移入 reference/”与“移入 archive/”的映射,在当前仓库中的最终落点为:

计划中的移动 说明
architecture-contract.md → reference/ 架构契约,转为参考 docs/slate-v2/references/architecture-contract.md
live-shape-register.md → reference/ 活动形态登记 docs/slate-v2/references/live-shape-register.md
normalization-reference.md → reference/ 归一化单一活动参考 docs/slate-v2/references/normalization-reference.md
chunking-review.md → archive/ 分块审查,历史参考 docs/slate-v2/references/chunking-review.md
slate-batch-engine.md → archive/ 批次引擎参考 docs/slate-v2/references/slate-batch-engine.md
oracle-harvest-ledger.md → archive/ 预言机采集台账,归档区
full-replacement-blockers.md → archive/ 全替换阻塞项,归档区 docs/slate-v2-draft/archive/full-replacement-blockers.md
perf-gate-package.md → archive/ 性能门限包,归档区 docs/slate-v2-draft/archive/perf-gate-package.md

可以观察到:归档动作之后,仓库中还并存着 docs/slate-v2-draft/(含自身的 archive/、references/、ledgers/、commands/ 子目录)这一“draft”镜像栈。结合两侧的 frontmatter 日期,可以推断文档栈在 4 月整合之后又经历了一轮正式栈 / draft 栈的双轨拆分——这本身就再次验证了整合文档所确立的原则:目录结构是活的,但只要“每类事实单一 owner + 显式降权 + 归档区自述身份”这三条规则不变,扩张不会退回混杂状态。

四、归档区的前导约束:让“历史文档”自己声明身份

docs/slate-v2-draft/archive/README.md 的写法是这套治理中很容易被忽略、却很关键的一环。它的结构是:

  1. 顶部一句身份声明:“Archive only. Historical reference doc. For current queue and roadmap truth, see master-roadmap.md.”(仅归档。历史参考文档。当前队列与路线图真值请看 master-roadmap。)
  2. 一句话说明归档区来源:“This folder keeps retired historical docs from the old docs/slate-v2 root stack. These files are for archaeology, not the current replacement verdict.”(本文件夹保留旧 docs/slate-v2 根栈退役的历史文档。这些文件用于考古,而非当前替换裁决。)
  3. 给出“你应该先读这些”的跳转清单:overview.md、master-roadmap.md、references/architecture-contract.md、release-readiness-decision.md、replacement-gates-scoreboard.md。
  4. 枚举归档区内容类别:历史基准与加固记录、历史迁移与兼容性记录、冻结的路线图与阶段计划产物、较早的综合与状态文档。

换言之,归档区不是“被遗忘的角落”,而是有明确导读的入口:任何从归档文档出发的读者,都能在第一屏就被重定向回当前 owner。这与 3.5 节的“前门重定向”形成闭环——活动文档指向 owner,归档文档指回活动文档,两个方向的导航都不允许悬空。

五、可复用的文档治理规则

agent-start.md 末尾的 Consolidation Rule 小节,把这次(以及后续历次)整合沉淀成了四条可复用规则:

  • Update: current claim docs and agent entrypoints.

  • Merge by reference: long architecture and decoration docs.

  • Keep indexed: issue dossiers and coverage matrices.

  • Archive only when a doc is stale and no current doc links to it.

  • 更新:当前声明文档与 Agent 入口。

  • 按引用合并:长篇幅的架构与 decoration 文档。

  • 保持索引化:问题案卷(dossiers)与覆盖矩阵。

  • 仅在文档过期且没有任何当前文档链接到它时才归档。

结合本次整合计划与仓库现状,可以把它读成一套完整的方法论:

  1. 先证明队列干净,再动文档。整合动作的前提是 diff 种子为 EMPTY、台账全行已审(第二节)——“活动事实无未审残留”是收敛文档栈的安全阀。
  2. 每类事实只有一个 owner。归一化姿态只由 normalization-reference.md 表述;阻塞裁决只由 release-readiness-decision.md 表述;门限状态只由 replacement-gates-scoreboard.md 表述。发现第二份文档在表述同一事实时,要么合并进 owner,要么显式降权。
  3. 降权不等于删除,而是加显式身份声明。batch-engine 与 chunking 文档保留知识内容,但用 “reference doc, not a remaining-work owner” 的 Rule 段落切断其队列资格。
  4. 归档是“过期 + 无入链”的合取条件,且归档后必须修补所有引用(“so the moved docs still resolve”),并在归档区 README 里给出回跳当前 owner 的清单。
  5. 结构以“owner 文档数”为计量指标。计划用“根目录收敛到 9 份 owner 文档”作为可验证的完成判据,这让“文档栈是否健康”变成一个可以数出来、可以回归检查的事实,而不是主观感觉。
  6. 判定纪律写入文档本身。记分板 Rules 小节的“邻近证据绿不代表门限绿”“一致性成功不自动关闭北极星门限”,把文档判定纪律与工程门限纪律放在同一张表里维护,防止后续维护者用“差不多的绿”替代“所有者自己的绿”。

六、如何验证当前文档栈状态

如果要针对当前仓库验证这套治理是否仍然成立,可按以下路径逐一检查(均为仓库内相对路径):

  1. 检查活动根目录纯度:列出 docs/slate-v2/ 顶层 .md,确认其中只有 owner 类文档(overview / master-roadmap / release-readiness-decision / replacement-gates-scoreboard / agent-start 等),而参考、台账、命令分别位于 references/、ledgers/、commands/ 子目录;
  2. 检查降权文档的自述:打开 slate-batch-engine.md 与 chunking-review.md,确认其 Rule 段落仍声明 “reference doc, not a remaining-work owner”;
  3. 检查归档区身份声明:打开 docs/slate-v2-draft/archive/README.md,确认 “Archive only” 声明与回跳当前 owner 的清单存在;
  4. 检查前门跳转:打开 agent-start.md 的 Current Truth 与 Do Not Read First 小节,确认入口文档指向的是四个当前事实 owner,而非历史参考文档;
  5. 检查引用完整性:对被归档、被移动过的文档(如 full-replacement-blockers.md、perf-gate-package.md),从活动文档出发沿链接访问,确认路径仍可解析——这正是计划中 “patched live and historical references” 的验收口径。

七、小结

2026-04-12-slate-v2-doc-stack-consolidation.md 这份计划本身只有短短五十余行,但它示范了一次高密度、可审计的文档治理执行:用 EMPTY diff 种子与全行已审台账确立动手前提;用降权、合并、归档、移动、引用修补、前门重定向六个动作把混杂的活动目录收敛为“9 份 owner 文档”的可计量终态;再把阻塞裁决与性能门限的所有权分别钉死在 release-readiness-decision.md 与 replacement-gates-scoreboard.md 两个裁决文件上。对任何长期演进的大型开源项目(尤其是有人类维护者与 AI Agent 共同维护控制面文档的场景),这套“单一 owner + 显式降权 + 归档自述 + 可计量终态”的做法,是可以直接照搬的文档栈工程方法。

登录后查看全文
plate