plate 仓库 Slate v2 迁移文档治理实践:Deslop 去堆砌审查流程与控制文档体系解析

原创2026-10-10 23:09:491,813 阅读
文章标签:富文本前端UI组件插件系统

plate 仓库 Slate v2 迁移文档治理实践:Deslop 去堆砌审查流程与控制文档体系解析

导读

本文系统解析 plate 仓库(Rich-text editor with AI and shadcn/ui)中 Slate v2 迁移程序的文档治理纪律——以 docs/plans/2026-04-08-deslop-doc-pass.md 所定义的 "Deslop Doc Pass" 为骨架,讲解如何在不改变技术含义、不丢失必需细节的前提下,对用户可见的 Slate 文档做措辞与结构层面的去堆砌(de-slop)审查,并完整还原其背后的控制文档栈(overview → master-roadmap → release-file-review-ledger → true-slate-rc-proof-ledger → 命令文档)、五阶段执行流程、无变更判定纪律,以及由 tooling/scripts/check-slate-v2-docs.mjs 实现的自动化文档审计。读完本文,你将掌握一套可复用的"大型迁移项目文档治理"方法论:如何界定文档审查范围、如何在简化与保真之间划界、如何用命令文档固化工作流、如何用脚本防止文档回退教习过时的 API。


一、背景:为什么一个迁移项目需要"文档去堆砌"

Slate v2 迁移程序是一个典型的"fresh-branch"重构项目:它以 .tmp/slate-v2 全新克隆为活体目标,以 .tmp/slate-v2-draft 为证据/价值银行,分 8 个 tranche 依次恢复 slate、slate-history、slate-hyperscript、slate-dom、slate-react 五个包。这类项目最大的风险之一,是文档比代码先腐烂——措辞膨胀、结构堆砌、过时 API 被继续当作正确用法反复教习。

"Deslop"(de-slop)就是针对这一风险的专项审查。其目标(Goal)定义得非常克制:

Simplify wording and structure in the user-scoped Slate docs without changing meaning or dropping required detail. (简化用户范围内 Slate 文档的措辞与结构,但不改变含义、不丢失必需细节。)

注意两个限定词:"user-scoped"(只针对用户可见的文档,而非全部内部笔记)和 "without changing meaning"(简化不等于重写,含义必须原样保留)。这是去堆砌审查与普通重构的本质区别。

二、审查范围(Scope):九个受控文档路径

关联文档将审查范围明确锁定在以下路径族(括号内为当前仓库中对应的实际文件):

  1. docs/slate-v2/master-roadmap.md —— 迁移主路线图,tranche 顺序的权威来源
  2. docs/slate-v2/release-file-review-ledger.md —— 逐文件迁移账本
  3. docs/slate-v2/commands/*.md —— 命令文档族(共 6 个,见下文第五节)
  4. docs/slate-v2/overview.md —— 迁移程序的"前门"概览
  5. docs/slate-v2/references/architecture-contract.md —— 架构契约(注意:关联文档写作 reference/ 单数,仓库实际路径为 references/ 复数)
  6. docs/slate-browser/overview.md —— 浏览器测试专家车道概览
  7. docs/slate-browser/api-design.md —— slate-browser 测试框架 API 设计
  8. docs/slate-browser/next-system-move.md —— slate-browser 下一步系统级动作
  9. docs/slate-v2/archive/README.md —— 归档说明。在当前仓库中,旧改写程序的文档已按 docs/slate-v2/overview.md 的归档规则迁至 docs/slate-v2-draft/archive/README.md,其职责是存放已退休的历史文档,仅供考古,不作当前替换裁决依据

范围划定本身就是在定义"什么是用户可见文档":控制文档(控制节奏)+ 专家车道文档(提供证据),两者构成了迁移程序的对外叙事层。

三、四条约束:去堆砌的边界条件

关联文档明确写出四条硬约束(Constraints),这四条决定了"简化"的边界:

  1. Only act on changed files inside the scope —— 只处理范围内的变更文件。没有变更的文件即使写得啰嗦,也不在本次 pass 的授权内。
  2. Preserve exact meaning and required detail —— 保持精确含义与必需细节。简化是措辞和结构的简化,不是技术内容的删减。
  3. Edit directly only when the simplification is clearly worthwhile —— 只有当简化"明确值得"时才直接编辑。避免为改而改引入新的噪音。
  4. Report no-change for scoped changed files that do not merit edits —— 对范围内但审查后判定不值得编辑的变更文件,要显式报告"无变更"(no-change call)。

第四条约束实际上确立了一种重要的工程伦理:"审查过"和"修改过"是两回事,审查必须留下记录,包括那些最终没有动手的文件。这防止了"悄悄跳过"和"无脑全改"两种极端。

四、五阶段执行流程:从识别到报告的完整闭环

Deslop pass 将执行拆分为五个阶段(Phases),每一步都有明确产出:

阶段 动作 产出
1 识别范围内的变更文件(Identify changed files in scope) 变更文件清单
2 逐文件审查措辞与结构堆砌(Review each changed file for wording and structure slop) 每份文件的审查判断
3 在合理处施加最小直接简化(Apply minimal direct simplifications where justified) 修改后的文档
4 用适合 markdown 编辑的诊断验证修改文件(Verify modified files with diagnostics suited to markdown edits) 验证通过
5 报告变更文件与无变更判定(Report changed files and no-change calls) 最终报告

其中第 4 阶段"适合 markdown 编辑的诊断"在仓库中有具体的自动化实现:根目录 package.json 暴露了 docs:slate-v2:audit 脚本,指向 tooling/scripts/check-slate-v2-docs.mjs。该脚本遍历 docs/slate-v2/ 下所有 markdown,做三件事:

任何违规都会以 文件:行号: 原因 的格式输出并 process.exit(1),只有全部通过才打印 Slate v2 docs audit passed.。这就是"deslop 之后文档不会回退"的机器保障。

五、审查发现与无变更判定纪律

关联文档的 Findings 记录了这次 pass 的实际结果,这是全文最值得对照仓库阅读的部分:

范围内变更文件共 13 个:

无变更判定 1 个:

  • docs/slate-v2/references/architecture-contract.md

这份架构契约(共约 2000 行)虽然也在范围内,但审查后判定不值得编辑——它已经足够精简,属于"no-change call"。这个判定的价值在于示范:去堆砌不是"每个文件都必须改",而是只在明确值得时动手,并把"看过但没改"也写进记录。

进度(Progress) 显示该 pass 已完成:计划已创建、变更文件子集已识别、在较小的路线图/概述/归档/命令/专家车道文档中完成了措辞与结构简化。简化的对象是"smaller roadmap, overview, archive, command, and specialist-lane docs"——即把最容易被篇幅淹没的控制文档和专家文档先理顺。

六、控制文档栈的职责分层:Overview 的所有权表

去堆砌之后,文档的职责边界必须清晰。这正是 docs/slate-v2/overview.md 的 Ownership 表要做的事。下表完整列出了"哪类事实由哪个文件负责":

职责类别 负责文档
架构声明(architecture claim) docs/slate-v2/absolute-architecture-release-claim.md
执行计划(execution plan) docs/slate-v2/fresh-branch-migration-plan.md 及若干 plan 文档
tranche 顺序(tranche order) docs/slate-v2/master-roadmap.md
审查状态(review state) docs/slate-v2/release-file-review-ledger.md
就绪声明(readiness claim) docs/slate-v2/release-readiness-decision.md
门禁状态(gate status) docs/slate-v2/replacement-gates-scoreboard.md
证明状态(proof status) docs/slate-v2/true-slate-rc-proof-ledger.md
维护者差异叙事(maintainer drift story) docs/slate-v2/references/pr-description.md

这套"一类事实只有一个权威文件"的规则,正是 deslop 的底层设计意图:文档堆砌的根源往往是职责重叠——多个文件抢着回答同一个问题,读者就只能在长篇里做考古。职责分层之后,"问题 → 权威文件"是单向映射。

Overview 还给出了 18 项阅读顺序(Read Order),从 docs/slate-v2/absolute-architecture-release-claim.md 开始,依次经过执行计划、架构契约、主路线图、就绪决策、门禁计分板、证明账本,再到历史上下文与装饰/标注专题。归档规则(Archive Rule)也很干脆:属于旧改写程序、不是当前迁移真相的文档,一律归入 docs/slate-v2-draft/**。

七、命令文档族:把"何时做什么"固化成可执行流程

docs/slate-v2/commands/ 目录是 deslop 之后保留的 6 个命令文档,每个回答一个具体问题:什么时候该运行什么动作,动作前后该刷新哪些控制文档。它们的价值在于把迁移程序中的"判断"也文档化,而不是靠记忆。

命令文档 触发时机 动作核心 事后刷新
launch-next-ralph-batch.md 路线图存在第一个未完成 tranche 且控制文档已同步 禁止凭感觉启动新批次:先确认所属 tranche 明确、合并语料文档存在、控制文档不与 tranche 目标冲突 若前提不成立,先运行下面三个命令之一
reconsolidate-roadmap.md 路线图与账本状态需要一致性检查 按固定顺序通读 overview → fresh-branch-migration-plan → master-roadmap → release-file-review-ledger → pr-description —
refresh-file-review-ledger.md 批次改变了包/运行时真相、恢复或切除了证明所有者、准备更新就绪声明 涉及删除/显式切除时:先冻结删除清单,再对齐父子包行,区分"行为承载行"与"仅 harness 行",不得让删除收尾冒充示例对齐或运行时收尾 release-file-review-ledger、true-slate-rc-proof-ledger、pr-description
reinterview-remaining-scope.md 恢复的证明所有者暴露了超出预期的缺口、tranche 无法干净回答"下一步"、对齐车道与 north-star 车道争抢下一批次 在"tranche 顺序 / 保留行 / north-star 行 / 证明车道"层面重述剩余工作,不是小补丁重排;packages/slate 的完美重设计转向正是此类变更 master-roadmap、release-readiness-decision、true-slate-rc-proof-ledger
replan-remaining-work.md 批次大幅改变阻塞集或证明所有权、scope 重访谈之后、恢复的契约所有者证明当前计划低估或高估了现实 硬规则:剩余工作不得塌缩为"只剩浏览器/输入";"避免重写"不得成为规划价值观;用户已选定完美重设计后"支持包优先"不得存续;保留行需要重写就规划重写;缺失的 v2 north-star 行要当作阻塞项保持可见 master-roadmap、release-readiness-decision、release-file-review-ledger、true-slate-rc-proof-ledger、pr-description
run-perf-gates.md 需要运行保护保留性能声明的打包/运行时门禁 运行 bun run test、bun run test:integration-local、bun run bench:react:rerender-breadth:local、bun run bench:react:huge-document-overlays:local、bun run bench:react:huge-document:legacy-compare:local replacement-gates-scoreboard、true-slate-rc-proof-ledger

注意 run-perf-gates.md 的诚实记录:legacy-compare 门禁当前对更强的 v2 性能优势声明是红色的,剩余工作不是"改命令名",而是"让直接的 legacy-compare 结果可接受,或显式推迟失败车道"。这种"把红灯写进文档"的姿态,正是 deslop 要去掉的"堆砌"(用漂亮措辞掩盖未完成)的反面。

八、路线图 tranche 结构与执行教义:去堆砌后的主干

master-roadmap.md 是去堆砌后保留的最重要的结构骨架,它的职责是"权威 tranche 顺序"。

执行教义(Execution Doctrine) 的核心是"合并语料(merged corpus)"模型:每个包从三处来源合并出一份契约语料——legacy 精确测试/文档、draft 契约测试/文档、当前证明所有者。规则是:

  • legacy 行是默认真相;
  • draft 行仅在代表 v2 预期行为且不与保留的 legacy 行冲突时保留;
  • 对核心引擎文件,测试背书的契约覆盖优先于当前源码形态;
  • 对保留行,允许重写,且必要时必须重写;
  • "同路径/同源压力"对文档、示例和公共包表面保持最强;
  • 程序有两个不可谈判的门禁:parity gate(对齐门) 与 v2 north-star gate(北极星门)。

tranche 顺序(前 6 个已完成,后 2 个未完成):

  1. Tranche 1:根/工具/文档——包管理器重置为 bun、Turbo 构建/类型图、Biome + flat ESLint、Bun 测试发现与 lockfile、文档拆分为 live 的 docs/slate-v2/** 与归档的 docs/slate-v2-draft/**;
  2. Tranche 2:React 19.2 与低风险兼容——React 19.2.5、Next 16.2.4(站点/运行时表面)、TypeScript 6.0.3 基线,只处理被迫兼容的后果,无语义行为变化,slate-browser 提前落地;
  3. Tranche 3:slate 读/更新事务核心与公共 API 重置——围绕 editor.read / editor.update 生命周期、原始编辑方法、事务属主的新鲜度、EditorCommit 作为本地运行时真相重建核心;明确 editor.children / editor.selection / editor.marks / editor.operations 不是主读路径,直接替换 editor.apply / editor.onChange 不是扩展点,Transforms.* 不是主公共变更叙事;
  4. Tranche 4:slate-history、slate-hyperscript 无损收尾;
  5. Tranche 5:slate-dom 属主运行时收尾——DOM 传输/运行时属主,装饰 DOM 偏移、选择与剪贴板真相必须保持显式;
  6. Tranche 6:slate-react 属主运行时收尾——强制 React 运行时局部性(selector-first 订阅、overlay 局部性、默认无宽重渲染);
  7. Tranche 7:示例/基准/增值(未完成);
  8. Tranche 8:RC 账本收尾(未完成)——最终就绪声明与最终 post RC 寄存器。

包顺序(Package Order):slate → slate-history → slate-hyperscript → slate-dom → slate-react,外加已落地的早期增值车道 slate-browser。审查规则(Review Rule):每个 tranche 之后停下;在已批准的包 tranche 内部,每个包之后停下;若合并语料改变了活动声明,须在下一个包开始前同步控制文档。

这些规则能在 packages/slate/src/create-editor.ts 和 packages/slate/src/interfaces/editor/editor-type.ts 中找到对应的实现形态:Editor 类型由 EditorBase 与 api(EditorApi)、tf/transforms(EditorTransforms)组合而成,编辑器实例携带 id、children、history、marks、meta、operations、selection 等字段——其中 children/selection/marks/operations 正是路线图明确"不是主读路径"的字段,与 docs/slate-v2/references/architecture-contract.md 中 editor.read(() => ...) / editor.update(() => ...) 的公共运行时契约相互印证。

九、账本的状态词与恢复行:事实的颗粒度

release-file-review-ledger.md 展示了去堆砌后的账本应有的信息密度。它定义了五个状态词——ported(移植)、adapted(适配)、pending(待处理)、archived(归档)、post RC(RC 后)——并用"文件 + 状态 + 一句话 note"的三列表格把根工具文件、站点工作流文件、包清单文件、运行时兼容文件、文档拆分全部登记在案。

例如 tranche 1 根工具行记录了 bunfig.toml(Bun 测试发现属主)、bun.lock(活体 lockfile)、turbo.json(构建/类型任务图)、biome.jsonc(格式化/lint 属主)、package.json("root now runs Bun 1.3.12, React 19.2.5, Next 16.2.4, TypeScript 6.0.3, hard-cuts Rollup, and drives package builds through ESM-only tsdown"),并归档了 pnpm-lock.yaml、yarn.lock、config/rollup/rollup.config.js、scripts/sync-package-types.mjs 等被 Bun/tsdown 取代的旧文件。

账本还以"Current Recovery Rows"逐包列出恢复/适配/新建/保留的文件与各自 proof owner——例如 packages/slate/test/query-contract.ts(restored)、packages/slate-history/test/history-contract.ts(created)、packages/slate-react/src/annotation-store.ts(adapted)等,并配以 docs/slate-v2/ledgers/README.md 的 recovered / extended / mixed / open / post RC / cut 六状态词体系与 17 份活体账本清单。"剩余工作规则" 尤其值得注意:账本不授权对剩余包做无差别同路径重写,但也不把"避免重写"当作价值——下一诚实步骤是先让 packages/slate 围绕原生事务/快照存储 API 定案,再显式分类兼容包袱,最后才重开支持包。

十、slate-browser 专家车道:去堆砌保留了什么"必需细节"

关联文档 Scope 中 slate-browser 的三个文档在 deslop 后保留了各自的强论断,是"简化但不丢细节"的最佳样例:

docs/slate-browser/overview.md 的强论断是"最佳编辑器测试框架是分层的,一个 runner 通吃是陷阱":Layer 0 核心快速测试(纯模型/变换/选择/投影语义)、Layer 1 DOM 契约测试(DOM 翻译、选择数学、placeholder 形态、剪贴板 DOM 适配)、Layer 2 示例集成测试(Playwright),叠加 Lane A(IME/合成,Chromium CDP,参考 Lexical 的 IME 测试模型)、Lane B(agent-native,参考 dev-browser/agent-browser)、Lane C(性能)。它明确"当前缺口是 Slate 有 Playwright 示例测试但没有一等公民的 agent-native 编辑器动作车道——这是真实的框架缺口"。

docs/slate-browser/api-design.md 给出了 editor-first 的 API 形态,这是 deslop 之后文档中最有操作价值的部分。核心入口与断言示例:

import { openExample } from "slate-browser/playwright";

const editor = await openExample(page, "placeholder");

await editor.focus();
await editor.assert.selection({
  anchor: { path: [0, 0], offset: 0 },
  focus: { path: [0, 0], offset: 0 },
});

await editor.ime.compose({
  text: "가",
});

await editor.assert.text("가");
expect(await editor.get.selection()).not.toBeNull();

设计原则五条:Slate 形状的名词(editor/selection/range/point/fragment/composition/placeholder/clipboard)优先于浏览器动词;确定性优先;需要时以浏览器为真相;agent-ready 而非 agent-led;跨 runner 保持单一心智模型。文档还锁定了第一 tranche 的 12 项公共表面(openExample(name)、editor.focus()、editor.assert.selection(...)、editor.ime.compose(...)、editor.clipboard.copyPayload()、editor.clipboard.pasteText(...)、editor.assert.placeholderShape(...)、editor.withExtension(extension) 等),并故意推迟 openFixture(...) 与 editor.driver()——"那个区分在理论上诱人、在实践中虚假",公共规则是 openExample(...) 是唯一路由入口,fixture 规模的 DOM 契约属于纯/浏览器车道与 Vitest 车道。

docs/slate-browser/next-system-move.md 的答案也很干脆:下一步不是更多表面积,而是 (1) 把 openExample(...) 强化为真正的就绪契约(区分页面导航、编辑器根可见性、示例特定挂载状态、选择敏感就绪),(2) 用它构建首个 renderer/input-policy 证明门槛(空块 placeholder 策略、零宽渲染策略、哨兵文本周围的选择规范化、空与零宽敏感起点上的 IME 提交行为)。反规则清单(anti-rules)明确禁止:重引入 openFixture(...)、加假公共合成粘贴助手、发明车道中立的 driver 抽象、先做跨浏览器 IME 表演、把发布语义变成主要架构决策。

十一、把 Deslop 纪律迁移到其他项目:方法论总结

从关联文档及其控制的文档栈中,可以提炼出四条可复用的治理原则:

  1. 范围先行:去堆砌只对"用户可见文档"和"变更文件"生效,防止审查演变成无边界重写;
  2. 保真优先:简化措辞和结构 ≠ 删细节。check-slate-v2-docs.mjs 式的自动化审计(tooling/scripts/check-slate-v2-docs.mjs)可以把"哪些 API 不再被允许教习"变成机器可执行的回归防线;
  3. 职责单一:一类事实只有一个权威文件(ownership 表 + 阅读顺序),文档堆砌的根源是职责重叠;
  4. 诚实记录:红灯要写进文档(perf gate 当前为红)、无变更判定要显式报告、删除收尾不得冒充对齐收尾——真实状态永远优先于漂亮措辞。

这套纪律最终服务于一个目的:让文档在长达数月、横跨 5 个包、8 个 tranche 的迁移程序中,始终是可检索、可引用、不会误导的工程资产,而不是又一份需要考古的堆砌物。

登录后查看全文
plate