企业官网建设流程全解析

Plate Markdown 编辑标准：参考权威模型、节点归属与规范驱动的行为工程实践

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

本指南完整解读 Plate（platejs）仓库中 Markdown-first 编辑工作的主规范文件 markdown-standards.md：它如何构建多参考编辑器（Typora / Obsidian / Notion / Google Docs / GitHub / Milkdown）的权威模型，如何用节点模型与亲和性（affinity）类约束内联编辑边界，又如何用稳定的 Spec ID 驱动 TDD 与 major 版本的行为重构。读完本文，你将掌握一套可直接复用的"先定标准、再写行为、用测试锁定"的编辑器行为治理方法，并能在 markdown-editing-spec.md 与 markdown-parity-matrix.md 中按图索骥。

这份标准要解决什么问题

Plate 编写这份 master standards 文件，是为了阻止两种常见失效模式：

• 把"Markdown 支持"窄化为只有 parse 与 serialize：实际编辑器行为（回车、退格、Tab、选区展开）被当成插件实现的"副作用"，缺乏统一契约；
• 把编辑器行为等同于当前插件实现的行为：行为随实现漂移，重构一次就回归一次，缺乏可追溯的依据。

因此该文件记录的是"方法论与权威模型"（methodology and authority model），目标是让后续行为工作不再退回到"拍脑袋"状态。它在当前 major 版本中充当 Markdown 编辑工作的行为总纲，与 markdown-editing-spec.md（行为规范正文）、markdown-parity-matrix.md（语法支持与往返覆盖矩阵）、editor-protocol-matrix.md（穷尽场景协议矩阵）组成完整的规范体系。

从仓库架构上看，这与 editor-behavior-architecture.md 提出的方向一致：Plate 要从"插件散落行为模型"走向"profile 驱动的行为引擎"——一个共享文档模型、一个共享 transform 层、多个行为 profile（如markdown_typora、markdown_milkdown、notion、google_docs、plate_default）叠加其上。Markdown-first profile 只是第一个 lane，不是最终形态。

参考池（Reference Pools）：按表面特征分配权威

标准不指定"一个编辑器的全局权威"，而是建立多个高信号参考池，每个具体表面（surface）单独挑选最强参考。

Typora：Markdown 原生表面的主参考

Typora 是大多数 Markdown-first 表面的高信号参考池，但不是每个 markdown-native 行的默认所有者。适用于：

• 段落、标题、列表、引用块、链接、markdown 原生 marks、代码、硬换行；
• 链接与类图片源语法的 markdown 原生点击编辑行为；
• 脚注预览与引用导航、HTML 块编辑入口；
• markdown-first 编辑的剪贴板文本预期、token 式 TOC 插入。

Obsidian：双模与笔记导航表面

Obsidian 是双模编辑（live preview vs source）与笔记关联导航的高信号参考池，适用于：

• 实时预览 vs 源码模式；
• 文件 / 标题 / 块引用的链接自动补全、重命名时更新内部链接；
• 反向链接与未链接提及（backlinks / unlinked mentions）；
• 大纲式导航、markdown 工作区搜索、块引用产品行为、双模编辑器中行内脚注的产品约束。

但不要把 Obsidian 当作通用默认所有者，例如纯 markdown 原生打字与结构键、渲染链接 / 图片 / HTML 块的 markdown 原生源码入口行为、低层破坏性按键法则（Typora 在这些面上更强更明确）。

Notion：块编辑器原生元素

Notion 是许多块编辑器原生元素的高信号参考池，适用于 toggle、callout、mention、日期提及、类 TOC 块、分栏、媒体 / 文件块、非 markdown 块的斜杠 / 块菜单插入手感、行内 chip 与页面引用交互。

Google Docs：文档式编辑

Google Docs 是文档式编辑的高信号参考池，适用于表格单元格行为、选区与多选预期、缩进与对齐手感、表格行列结构操作、大纲式标题跳转、评论 / 建议 / 审阅行为。

GitHub：GFM 专属语法与渲染语义

GitHub 是高信号产品参考，仅限 GFM-only 语法与渲染语义：任务列表语义、autolink 字面量语义、脚注语义、GFM 表格语法与渲染规则。不要用 GitHub 作为通用文本行为的 WYSIWYG 编辑权威——那些表面通常指向 Typora（markdown-native 编辑）与 Google Docs（表格手感与文档手感），但具体行仍需自行选择权威。

Milkdown：可检查的开源交叉验证

Milkdown 是唯一可检查源码的开源交叉参考，用于检查 markdown-first 编辑选择、编辑器引擎权衡，以及在 Typora / Notion 行为难以直接检查时的旁证。

权威顺序（Authority Order）：五个层级的裁决链

当决定 Plate 行为时，按以下顺序裁决：

1. 语法规范（syntax spec）；
2. 显式表面定义与节点模型（explicit surface definition and node model）；
3. 有真实证据的最强表面特定 UX 权威；
4. 可检查的交叉验证与最强相邻先例；
5. 显式兜底（仅当其余各方都沉默或不兼容时）。

注意：裁决对象是"你正在具体定义的那个表面"，而不是它外围的宽泛族标签。族标签只是路由提示。例如同属 markdown 扩展族的三行规则，可能分别落在 Typora、Obsidian、Google Docs / GitHub Docs 上，这是正常的，除非证据真的支持，否则不要强行为整个族指定一个所有者。

在 markdown-parity-matrix.md 中可以看到这种逐行裁决的落地：每个特性行都独立声明 Parse Authority、Primary UX Ref、Secondary Ref 与 Fallback，例如段落是CommonMark / Typora / Milkdown，表格是GFM / Google Docs / Notion, Milkdown，mention 是local mention markdown contract / Notion / Milkdown。

候选参考池路由（Candidate Reference Pools）

标准强调此节不是治理法律，只用于把一次审计快速路由到可能来源，具体小节与协议行仍要显式选择权威。核心路由如下：

• parse / serialize 语义：原生 markdown 用 CommonMark；GFM-only 构造用 GFM spec + GitHub Docs；只有故意做 MDX 往返时才用本地 MDX 契约；
• markdown 原生打字、边界与源码展开行为：通常 Typora，有时 Milkdown 作更强可检查证据；
• markdown 原生交互预览与导航：通常 Typora（纯 markdown 原生 span、脚注、图片源码编辑、HTML 块编辑入口）；
• 源保留转换行为：Typora（源码编辑与显式源转结构手感）、Obsidian（保守的 markdown 敏感转换压力，如选区优先的定界符处理）、Milkdown（input-rule 转换机制的可检查交叉验证）；
• 模式架构与笔记关联导航：通常 Obsidian；
• 搜索与导航 chrome：通常 Obsidian（markdown 工作区搜索、反向链接、大纲、笔记导航），Google Docs 用于线性文档大纲与标题跳转；
• 导航成功后反馈：本地共享契约 + 目标表面的最强所有者；
• 表格导航 / 选区 / 结构：通常 Google Docs；
• 块编辑器原生外壳行为：通常 Notion；
• 评论 / 建议 / 审阅：通常 Google Docs；
• 剪贴板：通常 Typora（markdown-first 复制粘贴），表格或文档保真预期更强时用 Google Docs；
• 开源交叉检查：Milkdown；
• profile 相邻选项：Typora 常作为 markdown 简写与定界符 autoformat 主参考、严格模式与激进配对输入参考；Obsidian 常用于保守的选区包裹与 live-preview 敏感触发；Milkdown 作为 input-rule 触发机制的可检查交叉验证；主流排版规范用于智能引号与标点替换；本地当前契约可临时拥有较薄的符号替换表；
• textautomd 与数学定界符触发：归属源保留转换行为，不归属普通 mark 或文本替换 autoformat；
• 兜底：仅当具体表面的更强参考全部沉默或不兼容时，才做显式 Plate 决策。

节点模型与亲和性要求（Node Model And Affinity）

标准要求每个特性族（feature family）都必须声明两类属性：节点模型与亲和性类。

节点模型共七种：

• block non-void：可编辑的块 / 容器内容；
• block void atom：原子块表面，富文本模式下光标不能进入其体内；
• inline non-void span：可编辑的内联内容，如链接；
• inline void atom：原子内联表面，无富文本可编辑体；
• leaf mark：由 leaf 携带的文本标记，而非独立内联元素；
• text token：保留语法的文本行为，如解析后的硬换行；
• overlay / no node：无文档节点归属的编辑器 chrome。

亲和性类（当内联打字可能跨越该边界时）：

• directional：从格式化侧打字扩展它，从普通侧打字保持在外；
• hard：边界打字保持在外，不扩展格式化 span；
• outward：元数据范围偏向避免意外增长；
• none / n-a：块节点、void 原子、文本 token、overlay 不拥有内联亲和性。

配套规则：

• 不要从 UI chrome 推断原子性（atomicity）；
• 不要从 DOM 的contentEditable={false}推断 voidness——要用编辑器节点契约，而不是渲染 DOM 技巧；
• 如果某特性是 non-void 且参与内联打字，规范必须声明其亲和性类；
• 内联 void 原子不获得link/mark 亲和性；它们作为原子自己拥有导航与边界删除。

在 markdown-editing-spec.md 中可以看到这套模型的逐族落地：链接是inline non-void span; directional，行内代码是leaf mark; hard，图片是block void media atom; n/a，脚注引用是inline void ref atom + block non-void definition; n/a，评论 / 建议是leaf metadata mark; outward。源码层也有直接印证：核心的 AffinityPlugin.ts 在deleteBackward与insertText中按directional亲和性设置选区边界，其测试 AffinityPlugin.spec.tsx 覆盖 mark boundary 上的前进 / 后退亲和行为。

决策规则（Decision Rules）

表面优先（Surface-first rule）

不要让类别标签决定赢家。每个具体表面、族切分或协议行都应选择它确实能辩护的最强权威。

主次参考一致时

默认采用该行为，除非它直接与语法正确性或 Plate 文档模型冲突。

主次参考不一致时

必须记录五项：场景（scenario）、主参考做了什么、次参考做了什么、Plate 的选择、以及为什么 Plate 的选择胜出。

双方都沉默时

只有此时才做显式兜底决策，不能把它伪装成标准偷偷塞进去。

与当前 Plate 行为不同时

不要把当前行为当作平局决胜者。现有行为是证据，不是权威。

Scope 与 Major 版本偏置

标准 lane 覆盖：markdown-first 编辑行为、markdown parse/serialize 对等性、major 可能破坏的既有块编辑器原生行为、markdown 感知的 autoformat、markdown 流式与部分语法处理。它不声称每个 Plate 块都是原生 markdown，但声称每个影响内容的既有特性都应有显式的权威与覆盖状态。

Major 版本期间：在 markdown lane 中，除非是解锁对等性、清理或 profile 架构所必需，否则推迟小的新特性工作。预算应花在：

• 干净地打破错误行为；
• 规范化既有构造；
• 对齐当前特性的 parse、serialize 与编辑语义；
• 消除插件间的意外行为漂移。

流式（streaming）在本 major 中视为回归覆盖而非主动工作队列（除非当前特性变更破坏了它）。不要用"锦上添花"的语法或扩展工作稀释发布。

Taxonomy：跨文档统一分类

规范与测试使用同一套分类法：

• 原生 markdown 构造：段落、标题、引用块、有序 / 无序列表、行内代码、围栏代码块、强调、加粗、主题分隔线（thematic break）、链接；
• 扩展 markdown 构造：任务列表、表格、删除线、脚注、autolink 字面量、数学；
• 块编辑器原生构造：mention、callout、toggle、date、TOC、分栏、媒体 / 文件块；
• 协作与编辑器专属构造：suggestion、comment 标记、discussion 标记、编辑器专属协作辅助。

这些协作 / 编辑器专属构造仍需要显式行为决策：在 markdown-first 发布门内支持、支持但不阻塞 major、推迟到后续 minor、或故意编辑器专属。

Spec ID 方案：让规则可寻址

每条有意义的规则都必须有稳定 Spec ID。示例：

• EDIT-BQ-ENTER-EMPTY-001
• EDIT-LIST-BACKSPACE-START-002
• PARITY-GFM-TASKLIST-001
• PARITY-MATH-BLOCK-003
• STREAM-BQ-PARTIAL-001

前缀语义：EDIT编辑行为；PARITYparse/serialize/往返对等；STREAM流式或增量 markdown；DEV故意 Plate 偏离。

在 markdown-editing-spec.md 中可以看到大量已锁定的 ID，例如段落EDIT-P-ENTER-001、引用EDIT-BQ-ENTER-EMPTY-NESTED-001、链接亲和EDIT-AFF-LINK-001、TOC 导航EDIT-TOC-NAV-001、脚注EDIT-FOOTNOTE-INSERT-001等。

测试映射与 TDD 目标

最终目标是从这些文档驱动 TDD。每条锁定的规则都应映射到：

• 一个或多个测试；
• 所属包或集成表面；
• 激活的行为 profile。

当行为重要到足以在重构中存活时，测试名称应直接引用 Spec ID。这与仓库测试体系相互印证：例如 markdown-parity-matrix.md 的每一行都给出 Current Evidence（代表缝隙的测试文件），如段落行指向 deserializeMd.spec.ts、withIndent.spec.tsx，链接行指向 AffinityPlugin.spec.tsx，表格行指向 table.spec.ts 与 withTable.spec.tsx。TDD 规则在规范正文末尾被写成硬约束："Do not lock a rule in this file without adding or mapping a test for it"。

Lock 级别与偏离政策

规范文档与 parity 矩阵使用五种标签：

• draft：参考前框架；
• audit：参考研究进行中；
• proposed：可能决策，未锁定；
• locked：已接受的目标行为；
• deviation：与参考故意不同。

偏离允许，隐藏偏离不允许。当 Plate 与 Typora、Obsidian、Google Docs、Notion 或 Milkdown 不同时，必须记录：Spec ID、场景、参考行为、Plate 行为、原因。

好的偏离理由：语法正确性；文档模型安全；更好的多块一致性；更好的流式稳定性；更好的 profile 可组合性；更强的主流编辑器先例；把参考行为暴露为显式 profile 选项而非强制成唯一全局默认。

坏的偏离理由："插件本来就这么干的"；"改起来很烦"；"反正我们已经有测试了"；"这是 Plate 的旧默认"。

研究方法论与场景形状

后续审计按固定顺序进行：

1. 先锁定架构与标准文档；
2. 按场景审计参考行为（不是随机浏览）；
3. 用同样场景审计当前 Plate 行为与测试；
4. 标记冲突；
5. 添加按 Spec ID 组织的失败测试；
6. 重构行为缝隙（behavior seams）；
7. 把 lock 级别从proposed升到locked。

审计一条规则时，必须捕获完整场景形状：块族（block family）、嵌套上下文、选区形状、触发键或语法、预期结构结果、预期光标结果、相关 parse/serialize 影响、相关流式影响。缺少这些，审计就会漂移到含糊散文。

与其他文档的关系与下一步

• editor-behavior-architecture.md 定义长期行为引擎方向（profile 驱动的行为架构）；
• markdown-editing-spec.md 定义 markdown-first profile 的编辑行为规范正文（全局不变量、所有权顺序、逐族契约与规范示例）；
• markdown-parity-matrix.md 定义语法支持与往返状态（每个特性族的权威模型、证据与下一步工作）。

立即下一步：默认不要重跑大范围 markdown-first 参考审计。优先使用实时命令包与路线图：commands/README.md 与 master-roadmap.md。只有当某条权威 lane 仍未解决、已汇编研究过时或矛盾、或出现当前栈无法诚实覆盖的新表面时，才重跑研究或审计。

实战要点速查

• 裁决任何一行行为：先语法规范 → 表面定义与节点模型 → 最强表面 UX 权威（带证据）→ 可检查交叉验证 → 显式兜底；
• 给每个特性族写两行声明：node model + affinity class，别从 DOM 推断 voidness；
• 锁定规则必须带 Spec ID，重要行为测试名引用该 ID；
• 偏离必须显式记录五要素，禁止"现有实现就是理由"；
• 每个锁定的规则必须有测试映射，否则不许锁定。

这套标准的价值在于：它把"Markdown 支持"从 parse/serialize 的狭小角落提升为有权威依据、有节点模型约束、有 Spec ID 可寻址、有测试锁定的完整行为工程——这正是 Plate 当前 major 版本对既有编辑器行为做系统性重构的方法论底座。

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