plate 仓库 Slate v2 迁移文档治理实践:Deslop 去堆砌审查流程与控制文档体系解析
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):九个受控文档路径
关联文档将审查范围明确锁定在以下路径族(括号内为当前仓库中对应的实际文件):
- docs/slate-v2/master-roadmap.md —— 迁移主路线图,tranche 顺序的权威来源
- docs/slate-v2/release-file-review-ledger.md —— 逐文件迁移账本
docs/slate-v2/commands/*.md—— 命令文档族(共 6 个,见下文第五节)- docs/slate-v2/overview.md —— 迁移程序的"前门"概览
- docs/slate-v2/references/architecture-contract.md —— 架构契约(注意:关联文档写作
reference/单数,仓库实际路径为references/复数) - docs/slate-browser/overview.md —— 浏览器测试专家车道概览
- docs/slate-browser/api-design.md —— slate-browser 测试框架 API 设计
- docs/slate-browser/next-system-move.md —— slate-browser 下一步系统级动作
docs/slate-v2/archive/README.md—— 归档说明。在当前仓库中,旧改写程序的文档已按 docs/slate-v2/overview.md 的归档规则迁至 docs/slate-v2-draft/archive/README.md,其职责是存放已退休的历史文档,仅供考古,不作当前替换裁决依据
范围划定本身就是在定义"什么是用户可见文档":控制文档(控制节奏)+ 专家车道文档(提供证据),两者构成了迁移程序的对外叙事层。
三、四条约束:去堆砌的边界条件
关联文档明确写出四条硬约束(Constraints),这四条决定了"简化"的边界:
- Only act on changed files inside the scope —— 只处理范围内的变更文件。没有变更的文件即使写得啰嗦,也不在本次 pass 的授权内。
- Preserve exact meaning and required detail —— 保持精确含义与必需细节。简化是措辞和结构的简化,不是技术内容的删减。
- Edit directly only when the simplification is clearly worthwhile —— 只有当简化"明确值得"时才直接编辑。避免为改而改引入新的噪音。
- 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,做三件事:
- 校验
public-surface-contract.ts中包含预期的 API 信号(bannedSlateRootHelperExports、bannedEditorInstanceSurface、'getSelection'、'getChildren'、'Transforms'); - 对代码块内的行执行
staleCodePatterns检查,禁止再出现editor.getSelection(...)等旧读 API、editor.insertNodes(...)等旧写 API 以及Transforms.调用; - 对教学文档集合(docs/slate-v2/agent-start.md、docs/slate-v2/absolute-architecture-release-claim.md、docs/slate-v2/references/architecture-contract.md)额外执行
staleTeachingPatterns检查,防止行文措辞重新教习过时 API。
任何违规都会以 文件:行号: 原因 的格式输出并 process.exit(1),只有全部通过才打印 Slate v2 docs audit passed.。这就是"deslop 之后文档不会回退"的机器保障。
五、审查发现与无变更判定纪律
关联文档的 Findings 记录了这次 pass 的实际结果,这是全文最值得对照仓库阅读的部分:
范围内变更文件共 13 个:
- docs/slate-browser/api-design.md
- docs/slate-browser/next-system-move.md
- docs/slate-browser/overview.md
- docs/slate-v2/references/architecture-contract.md
- docs/slate-v2-draft/archive/README.md
- docs/slate-v2/overview.md
- docs/slate-v2/commands/launch-next-ralph-batch.md
- docs/slate-v2/commands/reconsolidate-roadmap.md
- docs/slate-v2/commands/refresh-file-review-ledger.md
- docs/slate-v2/commands/reinterview-remaining-scope.md
- docs/slate-v2/commands/replan-remaining-work.md
- docs/slate-v2/master-roadmap.md
- docs/slate-v2/release-file-review-ledger.md
无变更判定 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 个未完成):
- Tranche 1:根/工具/文档——包管理器重置为
bun、Turbo 构建/类型图、Biome + flat ESLint、Bun 测试发现与 lockfile、文档拆分为 live 的docs/slate-v2/**与归档的docs/slate-v2-draft/**; - Tranche 2:React 19.2 与低风险兼容——React 19.2.5、Next 16.2.4(站点/运行时表面)、TypeScript 6.0.3 基线,只处理被迫兼容的后果,无语义行为变化,
slate-browser提前落地; - Tranche 3:
slate读/更新事务核心与公共 API 重置——围绕editor.read/editor.update生命周期、原始编辑方法、事务属主的新鲜度、EditorCommit作为本地运行时真相重建核心;明确editor.children/editor.selection/editor.marks/editor.operations不是主读路径,直接替换editor.apply/editor.onChange不是扩展点,Transforms.*不是主公共变更叙事; - Tranche 4:
slate-history、slate-hyperscript无损收尾; - Tranche 5:
slate-dom属主运行时收尾——DOM 传输/运行时属主,装饰 DOM 偏移、选择与剪贴板真相必须保持显式; - Tranche 6:
slate-react属主运行时收尾——强制 React 运行时局部性(selector-first 订阅、overlay 局部性、默认无宽重渲染); - Tranche 7:示例/基准/增值(未完成);
- 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 纪律迁移到其他项目:方法论总结
从关联文档及其控制的文档栈中,可以提炼出四条可复用的治理原则:
- 范围先行:去堆砌只对"用户可见文档"和"变更文件"生效,防止审查演变成无边界重写;
- 保真优先:简化措辞和结构 ≠ 删细节。
check-slate-v2-docs.mjs式的自动化审计(tooling/scripts/check-slate-v2-docs.mjs)可以把"哪些 API 不再被允许教习"变成机器可执行的回归防线; - 职责单一:一类事实只有一个权威文件(ownership 表 + 阅读顺序),文档堆砌的根源是职责重叠;
- 诚实记录:红灯要写进文档(perf gate 当前为红)、无变更判定要显式报告、删除收尾不得冒充对齐收尾——真实状态永远优先于漂亮措辞。
这套纪律最终服务于一个目的:让文档在长达数月、横跨 5 个包、8 个 tranche 的迁移程序中,始终是可检索、可引用、不会误导的工程资产,而不是又一份需要考古的堆砌物。