Plate Yjs 协作测试收割（Harvest）指南：许可证门控、可移植行为分类与适配层语料映射

Plate Yjs 协作测试收割（Harvest）指南：许可证门控、可移植行为分类与适配层语料映射

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

导读

本文围绕 Plate 仓库中的yjs-collaboration-harvest计划（docs/plans/2026-05-13-yjs-collaboration-harvest.md）展开，系统讲解如何以许可证门控（license-gated）方式从四个上游仓库（slate-yjs、lexical-yjs、y-prosemirror、yjs）收割 Yjs 协作相关测试：建立可运行性清单、按可移植性分类、映射到 Slate v2 与 Plate 的归属方，并沉淀为只读证据产物。读完本文，你将掌握这套"测试收割—行为分类—归属映射"的方法论、各上游测试语料的全景盘点（约 54 个 slate-yjs 协作 fixture 与数百个 CRDT 层用例），以及它在 Plate 仓库内落地为packages/yjs慢速协作测试套件（含内存多端连接器CollaborationConnector）的具体源码实现与验证命令。

一、为什么需要"测试收割"：协作行为证据的复用地基

富文本编辑器接入 Yjs 时，最大的工程风险不在于 CRDT 本身，而在于编辑器操作语义与共享文档模型之间的适配层：insertText、splitNode、mergeNode、moveNode、setNode、addMark、removeMark等 Slate 操作，需要被可靠地翻译成 Yjs 共享类型（Y.XmlText/Y.XmlElement）上的增量更新，并在远端以Y.Doc镜像的形式收敛。

该计划的核心判断是：这些行为已经以测试的形式存在于上游生态中，例如 slate-yjs 的协作 fixture、y-prosemirror 的 delta/position 不变量、yjs 自身的 CRDT 用例。与其从零设计测试，不如对上游测试做一次"收割"（harvest）：

• 先做许可证门控：确认每个目标仓库的许可证允许复用其测试思路与语料；
• 再建穷举清点：把每个仓库中所有满足测试文件模式的路径找出来；
• 逐行分类：判断每条用例是"可移植行为"、"混合行为"、纯 harness、还是与编辑器行为无关的 CRDT 内部机制；
• 最后映射归属：把可移植行为指派给 Slate v2 与 Plate 的对应维护方。

该计划本身只留下报告类产物（inventory / test-index / completion 状态），不修改任何上游仓库，因此可安全、可追溯地作为后续slate-yjs包与 Plate Yjs 插件的测试语料来源。

二、收割目标与授权评估

计划声明的目标（Goal）原文如下：

Run a license-gated harvest of Yjs collaboration tests from../slate-yjs,../lexical/packages/lexical-yjs,../y-prosemirror, and../yjs; classify portable behavior, map it to Slate v2 and Plate owners, and leave report-only artifacts.

四个目标仓库及其收割结论：

许可证结论基于各仓库本地许可证证据得出，而非外部声明。这也是"许可证门控"的含义：先确认可复用的法律前提，再进入清点环节。

三、八阶段执行流程

该计划以完成清单（checklist）形式记录了八个阶段，全部处于完成状态（[x]）：

1. Skill 分析与目标设定（owner skill 为.agents/skills/editor-test-harvester/SKILL.md）；
2. 解析目标仓库与许可证模式；
3. 构建穷举测试清点（inventory）；
4. 抽取 fixture / 测试名称；
5. 逐行分类（classify every row）；
6. 将行为映射到 Slate v2 与 Plate 归属方；
7. 撰写报告、清点、测试索引与完成状态；
8. 校验报告章节与完成检查。

这八个阶段构成了一条可复用的收割流水线：任何新编辑器适配层（例如未来接入其他 CRDT）都可以复用同样的"清点 → 抽取 → 分类 → 映射 → 沉淀"路径。

四、清点命令与产物结构

4.1 清点命令（Inventory Commands）

计划采用统一的rg管道来发现测试文件，模式同时覆盖目录命名与文件命名两类约定：

rg --files <repo> | \ rg '(^|/)(__tests__|test|tests|spec|e2e|integration|playwright|cypress|wdio|fixtures)(/|$)|\.(test|spec)\.[cm]?[jt]sx?$' | \ rg -v '(^|/)(dist|build|coverage|node_modules|vendor|fixtures/generated|__snapshots__)(/|$)' | \ sort

该模式的关键点：

• 包含规则：目录名命中__tests__、test、tests、spec、e2e、integration、playwright、cypress、wdio、fixtures，或文件名命中.test.*/.spec.*（含.cjs、.mjs、.js、.jsx、.ts、.tsx变体）；
• 排除规则：dist、build、coverage、node_modules、vendor、fixtures/generated、__snapshots__等生成物与依赖目录；
• 同一命令分别对四个仓库执行，保证口径一致、可复跑。

4.2 产物结构

收割完成后沉淀为三类证据产物（status: done，license_mode: permissive）：

• Inventory（docs/editor-test-harvester/yjs-collaboration/inventory.md）：逐文件的清点总表，包含可运行性、类别、判定理由、测试名抽取方式；
• Test Index（docs/editor-test-harvester/yjs-collaboration/test-index.md）：逐条测试的精确索引（文件路径 + 行号 + 测试/导出名）；
• 完成状态：以 completion ledger 形式记录（见后文"验证与完成检查"一节）。

需要说明：计划头部记录了报告路径docs/editor-test-harvester/yjs-collaboration/report.md，而在当前仓库快照中可直接验证的产物为上述 inventory 与 test-index 两个文件。

五、分类体系：可移植性判定

清点表对每一行都给出类别（Category），这是整份收割计划最核心的分析维度：

这个五分类的价值在于：收割方可以只把portable行纳入适配层测试设计，把portable-mixed拆出通用不变量、丢弃宿主策略部分，把skip行留给 CRDT 底层信心而非编辑器行为覆盖。

5.1 空目标：lexical-yjs

清点表专门记录了"空目标"（Empty Target Notes）：

../lexical/packages/lexical-yjshas no test files under the required inventory pattern. Its source was scanned for Yjs collaboration concepts, but there is no runnable upstream test to harvest from that package path.

即 lexical-yjs 包在指定清点模式下没有任何可运行测试，只有源码级概念扫描记录——这是一个重要的"负结果"：不能因为某仓库有 Yjs 集成包就默认它有可收割的测试语料。

六、上游测试语料全景盘点

6.1 slate-yjs：适配层 fixture 主力（54 个 fixture + 1 个适配器套件）

packages/core/test/collaboration/下按 Slate 操作类型组织的 fixture 是适配层行为的最直接证据，测试索引（test-index.md）逐一给出了文件与行号：

合计54 个 fixture，外加一个index.test.ts适配器套件（test-index.md 中记录其第 63 行为adaptersuite，负责加载全部协作 fixture 并校验本地/远端收敛）。辅助文件withTestingElements.ts（测试元素与共享根接线）与slate.d.ts（环境类型）被标记为 harness / skip。

从命名可以观察出覆盖设计的意图：Unicode 贯穿各操作族（withUnicode反复出现），嵌套结构（nested block、mixed nested nodes）与格式标记组合（withOtherMarks、insideMarks）是重点边界。

6.2 y-prosemirror：映射与变换不变量（116 个导出）

该仓库的测试大多以test*.js形式存在，由 lib0 runner（index.js/index.node.js）加载。按测试索引统计：

合计约116 个导出。其中positions与delta两个文件被直接归类为portable，是"编辑器协作位置与 delta 映射不变量"的典范——这类不变量与宿主编辑器无关，可直接借鉴到 Slate 适配层。

6.3 yjs：CRDT 底层语料（237 个导出）

yjs 自身的测试由 lib0 runner（tests/index.js）加载，覆盖共享类型与协议机制：

合计约237 个导出。其中skip行（IdMap/IdSet/compatibility/encoding）被明确判定为"CRDT 底层信心"而非编辑器行为目标，这正是分类体系避免把无关语料误入适配层测试的有效例证。

七、关键发现：收割结论的三条主线

计划的关键发现（Key Findings）可归纳为三条，分别对应法律前提、负结果与增量机会：

1. 许可证干净：四个目标仓库均为 MIT/宽松（基于本地许可证证据）；
2. lexical-yjs 无料可收：没有满足清点模式的可运行测试文件；
3. 两侧现状差距：
   • Slate v2 侧已有较强的协作底层覆盖，证据为.tmp/slate-v2/packages/slate/test/collab-history-runtime-contract.ts（协作历史运行时契约测试）；
   • Plate 侧已有有用的 Yjs 慢速 fixture，但仍有适配转换缺口：计划原文指出可受益于一个紧凑的适配器转换包（adapter-conversion pack），覆盖unicode、marks、nested moves、split/merge/set-node、cursor projection五类行为。

这五类缺口与上文 slate-yjs fixture 表中的高频关键词（withUnicode、withMarks、嵌套 move、split/merge/set-node）完全对应，说明收割语料与缺口分析形成了闭环。

八、Plate 侧落地：packages/yjs的协作测试源码剖析

收割计划在 Plate 仓库内的落地证据位于 packages/yjs/src/lib/tests/collaboration/，由三个文件构成：fixtures.ts（10 个协作场景）、harness.ts（内存多端连接器与工具函数）、index.slow.ts（慢速测试入口）。

8.1 测试入口与运行方式

index.slow.ts把fixtures.ts导出的collaborationFixtures逐一注册为用例：

import { collaborationFixtures } from './fixtures'; describe('yjs collaboration', () => { afterEach(() => { mock.restore(); }); for (const fixture of collaborationFixtures) { it(fixture.name.replaceAll('_', ' '), fixture.run); } });

文件名后缀.slow.ts与计划中"Plate already has useful Yjs slow fixtures"的表述相互印证：这些用例涉及多端连接、异步收敛与 setTimeout 打桩，属于慢速、确定性要求较高的协作测试。

8.2 核心装置：内存多端CollaborationConnector

harness.ts 用纯内存实现了一个微型多端协作网络，避免引入真实 WebSocket/WebRTC 依赖：

• CollaborationConnector：维护peers映射与消息队列queue；connect时为新 peer 与已连接 peer 互发全量状态（Y.encodeStateAsUpdate）；enqueue把本地更新广播给其他已连接 peer；flushAll({ order: 'fifo' | 'reverse' })批量投递更新（Y.applyUpdate(peer.document, update, REMOTE_ORIGIN)），reverse模式用于模拟乱序到达；
• TestCollaborationProvider：实现UnifiedProvider契约的测试端，挂在Y.Doc的update事件上采集本地更新并交给连接器；通过registerProviderType(PROVIDER_TYPE, TestCollaborationProvider)注册为动态 provider 类型；
• REMOTE_ORIGIN符号：区分本地/远端更新来源，避免远端更新被再次广播（回声抑制），这是收敛正确性的关键细节；
• 工具函数：createCollaborationEditor（用BaseYjsPlugin.configure构造编辑端）、createMixedProviderEditor（真实 provider + passive mock provider 混用）、getDocChildren（用@slate-yjs/core的yTextToSlateElement把Y.XmlText反解为 Slate 节点）、initEditor、replaceSharedContent/appendSharedContent（通过slateNodesToInsertDelta把 Slate 值写入共享类型）、settle（双微任务让异步收敛稳定）。

8.3 十类协作场景：fixtures 一览

fixtures.ts 定义的 10 个场景覆盖了"加入房间—并发—断线重连—乱序—超时—混合 provider"的全生命周期：

这些场景与收割计划"适配器转换包"的五类缺口（unicode、marks、nested moves、split/merge/set-node、cursor projection）形成互补：Plan 侧缺口指向操作级适配，而 Plate 现有 fixture 已经覆盖同步生命周期级不变量（播种、服务端优先、断线并发、乱序、超时重连）。

8.4 插件侧的配套实现

协作测试所依赖的运行时能力分布在 packages/yjs/src/lib：

• BaseYjsPlugin.ts：核心绑定逻辑，持有Y.Doc、Awareness、sharedType与 providers；
• withPlateYjs.ts：编辑器级集成（含withTCursors光标投影、withTYHistory历史、withTYjs共享类型绑定）；
• providers/registry.ts 与三个 provider 包装（hocuspocus-provider.ts、indexeddb-provider.ts、webrtc-provider.ts）；
• createMockProvider.ts 与 mockFn.ts：混合 provider 测试的被动端。

React 侧入口 YjsPlugin.tsx 提供YjsPlugin.configure({ options: { providers, ydoc, sharedType } })的声明式配置；插件的安装与 provider 参数说明（indexeddb/hocuspocus/webrtc及自定义 provider 注册）见 packages/yjs/README.md。

九、验证与完成检查

计划记录了完成验证步骤，其中仓库内可复跑的核心命令如下：

rg -n "License Gate|Confidence Score|Pass-State Ledger|Matrix|Skips|Next Slice|Full Inventory Appendix" docs/editor-test-harvester/yjs-collaboration/report.md test -f docs/editor-test-harvester/yjs-collaboration/inventory.md test -f docs/editor-test-harvester/yjs-collaboration/test-index.md bun run completion-check -- --id 019e1c53-3e25-78c0-9083-355925be3817

• 第一条用rg验证报告包含全部关键章节（许可证门控、置信度评分、通过状态台账、矩阵、跳过、下一切片、完整清点附录）；
• 第二、三条验证收割产物文件存在（当前仓库中inventory.md与test-index.md均可直接确认）；
• 第四条通过bun run completion-check以稳定 ID 校验完成状态。

这套验证方式的特点是可机械复跑：任何后续收割都能用同样的命令证明"产物齐备、章节完整"。

十、从收割语料到slate-yjs包的演进脉络

计划头部包含三条同步记录（Sync note），说明了该文档在时间线上的定位——它始终是证据清单（evidence inventory），而非当前 API 决策：

• 2026-05-18：包级规划迁至 docs/plans/2026-05-18-slate-yjs-package-readiness-ralplan.md；当时packages/slate-yjs尚无源码，剩余执行工作为包脚手架、完整仿真示例、包测试与 Playwright 选区覆盖；
• 2026-05-24：继续以稳定收割产物作为测试语料，但不得据此推断当前 API 或包存在性；
• 2026-05-28：../slate-v2中已出现@slate/yjs包源码，当前架构与操作矩阵工作迁至 docs/plans/2026-05-28-slate-yjs-current-architecture-operation-matrix.md。

后续相关计划还包括 2026-05-25-slate-yjs-structural-operation-coverage-ralplan.md 与 2026-05-29-slate-yjs-from-scratch-operation-matrix.md，并有 本地 yjs 别名避免重复安装的解决方案记录。这条脉络展示了测试收割在工程中的正确用法：语料沉淀一次、长期复用，而 API 与架构决策跟随最新计划演进。

十一、方法论复用：给其他适配层（或未来 CRDT）的收割清单

把本文内容浓缩为可迁移的步骤，任何新的编辑器协作适配层都可以按此执行：

1. 门控：先确认上游许可证（本地证据），再谈语料复用；
2. 清点：用统一的rg管道对每个上游仓库跑同一套包含/排除规则；
3. 分类：逐文件打portable / portable-mixed / harness / skip / manual标签，并为每个标签写下判定理由；
4. 抽名：把每条可运行测试的文件路径、行号、导出名沉淀为 test-index；
5. 映射：把可移植行为指派给编辑器核心、适配层与插件层的具体归属方；
6. 沉淀：只写报告类产物，并记录完成状态（status / license_mode / completion）；
7. 闭环：把"缺口清单"（如 unicode、marks、nested moves、split/merge/set-node、cursor projection）回填到自身测试设计，用内存多端连接器实现可确定性验证的慢速协作套件。

结语

Yjs 协作的正确性最终由"操作语义翻译 + 同步生命周期收敛"共同保证，二者缺一不可。本文所讲解的收割计划给出了前半部分（操作级适配）的系统化语料来源——54 个 slate-yjs 协作 fixture、116 个 y-prosemirror 映射不变量、237 个 yjs CRDT 用例，并明确了哪些可移植、哪些应跳过；而 Plate 仓库内的packages/yjs慢速协作套件与内存CollaborationConnector则示范了后半部分（生命周期收敛）的可确定性验证方式。两者结合，构成了一套从上游证据到本地落地、可复跑、可追溯的协作测试方法论。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate