企业官网建设流程全解析

plate 编辑器基准证据源映射指南：Evidence Kit 注册表与 Slate v2 对比基准的权威数据流

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

本篇指南围绕 plate 仓库中 benchmarks/editor/research/evidence-source-map.md 展开，系统讲解编辑器基准实验室（Evidence Kit lab）如何通过"证据源映射"（source map）来定义什么是有效的基准证据：从源配置文件、基准注册表、目标集划分，到已接受/已拒绝的迁移规则与健康报告。读完本文，你将掌握该仓库中 Slate v2 与 Slate 对比基准的完整数据流、注册表字段语义、行状态码含义，以及如何用一条命令查看当前证据健康度与下一步行动。

一、什么是证据源映射：从"跑出数字"到"证明数字算数"

在现代富文本编辑器框架的研发中，性能对比最困难的部分往往不是"跑一个 benchmark"，而是回答三个问题：

1. 这个数字是从哪个源码版本、哪条命令、哪个工作负载跑出来的？
2. 这个数字当前是否仍然有效（artifact 是否过期、是否被注册）？
3. 这个数字能不能被当作正式结论写进文档与 PR？

plate 仓库的编辑器基准实验室（benchmarks/editor）给出的答案是：用一套Evidence Kit 证据包来统一管理。evidence-source-map.md是该证据包的事实来源（source of truth）文档，它以verdict: accepted的决策记录形式声明：

使用 Evidence Kit 的 source map 与 benchmark 行（rows）作为新的编辑器基准权威。

这意味着：仓库不再维护"旧的 Next/Vite 独立基准应用"作为默认基准所有者，而是由**证据工件（evidence artifacts）**持有话语权。整个体系围绕两个 JSON 文件运转：

• 主源配置：benchmarks/editor/research/editor-frameworks-sources.json
• 主基准注册表：benchmarks/editor/research/benchmark-registry.json

从源码结构看，benchmarks/editor/src/index.mjs中导出的readResearchSources与readBenchmarkRegistry就是这两个文件的解析入口，所有 benchmark runner（如rich-text-editors-benchmark.mjs、benchmark-health.mjs）都通过它们读取配置，而不是把工件路径硬编码在脚本里——这是"注册表驱动"设计的关键。

二、主源配置：editor-frameworks-sources.json

源配置声明"当前正在测量哪些编辑器源码"。当前仓库中的 editor-frameworks-sources.json 内容如下（含字段注释）：

{ "version": 1, "topic": "editor-frameworks", "generatedBy": "@shapeshift-labs/evidence-kit", "sources": [ { "name": "slate-v2-package", "type": "file", "path": "../../.tmp/slate-v2/package.json", "fileName": "slate-v2-package.json", "why": "Slate v2 owns current deep Slate benchmark commands and artifact families." }, { "name": "slate-package", "type": "file", "path": "../../../slate/package.json", "fileName": "slate-package.json", "why": "Slate is the local baseline for Slate v2 compare lanes." } ] }

字段语义说明：

注意path是相对于证据包所在目录的路径：Slate v2 位于.tmp/slate-v2，legacy Slate 基线位于仓库外的slate克隆。在src/index.mjs的createEvidenceReadinessRows中，会检查该配置里配置的源条目数量是否不少于editorTargets数量，不足则输出missing-source状态行——源配置本身就是证据就绪度检查的一部分。

三、主基准注册表：benchmark-registry.json

注册表是"什么是当前有效证据"的唯一仲裁者。当前 benchmark-registry.json 的顶层结构：

{ "version": 1, "policy": { "activeArtifactRule": "Only artifacts listed here are active benchmark evidence.", "discardRule": "Unregistered benchmark JSON files are ignored historical output." }, "discardUnregistered": [ { "root": "../../.tmp/slate-v2/tmp", "match": "benchmark" }, { "root": "../../.tmp/slate-v2/packages/slate-react/tmp", "match": "benchmark" } ], "runtimeAdapters": [], "artifacts": [ ... ], "workloads": [ ... ] }

3.1 policy：两条核心规则

• activeArtifactRule：只有注册表列出的工件才是活跃基准证据；
• discardRule：未注册的 benchmark JSON 一律视为历史输出，被活跃流程忽略。

discardUnregistered声明了哪些目录下的*benchmark*.json会被健康报告视为"被丢弃的历史工件"。从 benchmark-health-latest.json 可以看到实际效果：当前有23 个活跃工件、62 个被忽略的未注册工件——这些历史 tmp 文件不会进入任何活跃结论。

3.2 artifacts：工件条目字段详解

当前注册表共 23 个工件（2 个可选），每个条目的典型结构：

{ "id": "react-huge-document-legacy-compare", "category": "slate-react-huge-document-legacy-compare", "kind": "slate-legacy-compare", "owner": "slate-v2", "family": "react-large-document", "cwd": "../../.tmp/slate-v2", "command": "REACT_HUGE_COMPARE_LEGACY_REPO=../../../slate bun run bench:react:huge-document:legacy-compare:local", "path": "../../.tmp/slate-v2/tmp/slate-react-huge-document-legacy-compare-benchmark-compare-all-blocks-5000-iters-3-ops-20-combined-selection-no-profile.json", "required": true, "decision": "Does Slate v2 beat legacy Slate for 5,000-block React editing, selection, startup, and full-document replacement?" }

字段语义：

当前注册表覆盖的工件族包括：React 5000 块大文档对比、React 重渲染广度（rerender breadth）、大文档 overlay、Chromium 浏览器 trace（DOM 数量/堆/长帧/交互）、富文本浏览器回放覆盖、core 归一化/query-ref/节点变换/文本选择/编辑器 store/refs 投影、core 大文档/归一化/观察对比、历史对比、剪贴板大负载、协作就绪度、issue #6038 事务回放等。

3.3 workloads：工作量与目标覆盖矩阵

workloads把多个工件聚合成"工作量"，并声明它是否同时覆盖 legacy 与 Slate v2：

{ "id": "react-huge-document-browser-trace", "legacy": true, "slateV2": true, "artifactIds": [ "react-huge-document-browser-trace", "react-huge-document-slate-browser-trace" ], "workload": "Chromium DOM count, heap, long-frame, and interaction traces" }

legacy/slateV2布尔值直接决定覆盖率行（rich-text-editor-workload-coverage）的状态：src/index.mjs的readWorkloadCoverageStatus逻辑是——对 Slate v2 目标，若工作量的工件已测量则记为ok；对 Slate 基线目标，只有当legacy: true才记ok，否则记unsupported（Slate v2 专属工作量，不声称有 Slate 基线）。这保证了"Slate v2 专属诊断"与"Slate v2 vs Slate 对比"在结果中被明确区分。

四、当前本地目标集：Slate v2 + Slate，chunk-on 为基线

证据源映射声明的当前目标集只有两个（src/index.mjs 中的editorTargets）：

关键约束（README 与证据源映射文档一致）：

• 活跃对比范围仅为 Slate v2 vs Slate；
• Slate 基线固定使用 chunk-on，活跃对比输出中禁止出现 chunk-off 行——这一点甚至被写进了 rich-text-editors-benchmark.mjs 的 check 逻辑：forbiddenScopeTerms数组里包含slate:chunk-off与legacychunkoff，一旦结果行中出现这些词缀，--check直接抛错；
• 旧浏览器 app（Next/Vite）基准目标不保留，未来若要扩大对比范围，必须先显式重开 Slate-only 范围，再添加目标所属的证据适配器与 benchmark 行。

对比行中的 library 标识遵循固定顺序（slateLegacyCompareSurfaceOrder）：v2DefaultRenderAuto→v2DomPresent→legacyChunkOn，分别映射为slate-v2:default-render-auto、slate-v2:dom-present与slate。

五、已接受的迁移规则（Accepted Transfer）

证据源映射文档明确列出了一组"正式证据必须满足"的规则：

1. 结论必须来自benchmarks/results/*latest.json行，且行内带可见状态：ok、partial、unsupported、timeout、over-budget或错误状态。例如 rich-text-editors-latest.json 中的行就带有status: "ok"/"unsupported"与medianUs/p95Us/ops等字段。

2. 活跃基准结论必须来自 benchmark-registry.json；未注册的 benchmark JSON 是历史输出，被活跃 Evidence Kit 流程忽略。健康报告据此统计出 62 个被忽略工件。

3. 富文本编辑器结论的入口是 rich-text-editors-latest.json：该文件从注册的 Slate v2 / Slate 工件族导入数据，是"宽矩阵"，而老的slate-v2-legacy-latest.json仍是第一次直接运行时对比的历史存放处。README 明确指出：活跃范围是 Slate v2 vs Slate，Slate chunk-on 为基线。

4. 外部或兄弟仓库的灵感必须以research/repos/<topic>/manifest.json形式的 fetch 清单进入，或以复制数据进入benchmarks/data/<topic>/。对应命令见 package.json 的research:editor-frameworks:fetch（执行fetch-editor-frameworks-research.mjs）与research:source-pass:fetch。

5. 旧浏览器 app 目标不保留：未来对比工作需在 Slate-only 范围显式重开后，再添加目标所属的证据适配器与 benchmark 行。

5.1 行状态码语义

以 rich-text-editors-latest.json 实际行为例：

• ok：已测量且通过，如 Slate v2 的react-huge-document-legacy-compare覆盖行（ops: 1）；
• unsupported：Slate v2 专属工作量对 Slate 基线不声称数据，如react-rerender-breadth的 slate 行（ops: 0）；
• missing-artifact/optional-missing-artifact：必需/可选工件缺失（由createBenchmarkArtifactRows在工件文件不存在时生成）；
• over-budget：阈值行未通过（如 迭代记录 002 中提到的剪贴板cutTwoBlocksEditMsP50超预算）；
• adapter-missing：目标存在但尚无等价运行时适配器（check 时要求 Slate-only 范围内该状态行数为 0）。

六、行归一化契约：从任意工件 JSON 到统一结果行

benchmarks/editor/src/index.mjs定义了"目标所属 benchmark 行的归一化契约"，这是证据可信度的底层保证。核心函数链：

createRichTextEditorBenchmarkRows ├── readBenchmarkRegistry(registryPath) ├── createRichTextEditorCoverageRows // 目标覆盖行 + 工作量覆盖行 └── createBenchmarkArtifactRows // 逐个工件 → 按 kind 分发 ├── normalizeSlateLegacyCompareArtifact ├── normalizeRowsArtifactRows ├── normalizeBrowserTraceArtifactRows ├── normalizeCompareArtifactRows └── normalizeCurrentArtifactRows

normalizeBenchmarkRow对每一行强制校验：category、fixture、library、status必须是非空字符串；medianUs、p95Us、ops、bytes必须是有限数值。isTimeMetric通过/(?:Ms|Duration)$/识别耗时指标并换算为微秒（msToUs），isByteMetric通过Bytes$|MB$或stats.unit === 'bytes'识别字节指标（MB 自动乘 1024×1024）。缺失 stats 的工件会生成missing-metrics行而不是静默丢弃——宁可标红，不可假装有数据。

check 门槛（见 rich-text-editors-benchmark.mjs）：总行数 ≥ 250、ok行 ≥ 180、目标覆盖行数等于目标数、无 adapter-gap、无非 Slate 库、无越界词缀。这些数字本身就是"宽覆盖"的量化定义。

七、健康报告与下一步行动

benchmark-health-latest.json 由benchmarks/benchmark-health.mjs生成，包含：

• registry.activeArtifacts（23）与discardedUnregisteredArtifacts（62）；
• missingRequiredArtifacts（当前为空，说明必需工件齐全）与missingOptionalArtifacts（2 个可选工件：core-transaction-current、history-retained-memory）；
• nextActions：按优先级排序的行动项，例如刷新 15 天未更新的core-node-transforms（priority 4）、决定可选工件是否保留（priority 5）、清理 62 个未注册历史工件（priority 6）。

这套"健康报告 + 排名下一步行动"是证据控制面（control plane）的产物，详见迭代记录 003-evidence-control-plane.md：benchmark runner 仍归各所有者（Slate v2 拥有测量命令），但"输出是否算数"由 Evidence Kit 注册表决定——职责分离，控制面自治。

八、已拒绝的迁移规则（Rejected Transfer）

证据源映射文档同时明确否决了以下四类回退行为：

1. 恢复已删除的 Next/Vite 应用作为默认基准所有者；
2. 保留框架模板动物园（template zoo）作为未来保险；
3. 把生成的占位行（placeholder row）当作性能证据；
4. 把未注册的 tmp benchmark 工件当作活跃证据。

这些"拒绝"在代码层也有呼应：src/index.mjs的staleSurfacePaths硬编码了apps、templates、website等旧表面路径，createEvidenceReadinessRows会输出legacy-app-surface-removed硬切行——一旦旧 app/模板路径重现，该行状态变为stale-surface，证据就绪度即告失败（参见迭代记录 000-bootstrap-evidence.md 中的 hard-cut 设计）。

九、实操：如何查看与验证当前证据

在 benchmarks/editor 目录下可用的关键命令（均定义在 package.json）：

npm run evidence:inspect # 以 JSON 输出证据包结构 npm run research:list # 列出研究源 npm run research:editor-frameworks:fetch # 拉取编辑器框架研究资料 npm run bench:rich-text:check # 重新生成并校验富文本宽矩阵 npm run bench:startup:check # 启动导入检查（默认 p95 < 100ms、32 个导出） npm run bench:package:gates # 包边界检查（200000 bytes / 32 files / 1250000 packBytes / 96 packFiles） npm run bench:scope # 更新 scope hash npm run evidence:health # 生成健康报告 npm run evidence:refresh # research:list + rich-text:check + health + docs npm run docs:perf # 生成 docs/perf 下的 HTML 仪表盘 npm run docs:perf:search -- editor benchmark # 在性能文档中全文搜索 npm run evidence:full # 全量流水线：测试 + fuzz + bench + 检查 + docs

典型的最小验证链路（对应迭代记录中的 Verification）：

npm run bench:rich-text:check npm run evidence:health npm run check

十、总结：证据源映射的三大原则

综合 evidence-source-map.md、注册表、源码与健康报告，可以把这套机制概括为三条原则：

1. 注册表即权威：没有被 benchmark-registry.json 收录的 JSON 不算活跃证据，无论它看起来多像 benchmark 结果；
2. 行状态即结论边界：结论必须落到benchmarks/results/*latest.json的规范化行上，ok/partial/unsupported/over-budget等状态限定了"这句话可以说多满"；
3. 控制面与测量面分离：测量命令归目标所有者（Slate v2），证据判定归 Evidence Kit；扩大对比范围必须先显式重开范围，再补适配器与注册行，禁止回退到旧的 app/模板基准动物园。

对于希望深入验证的读者，建议依次阅读 editor-frameworks-sources.json、benchmark-registry.json、rich-text-editors-latest.json 与 benchmark-health-latest.json 四个文件，再对照 src/index.mjs 的归一化实现，即可完整复现"从源码到可引用基准结论"的整条证据链。

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