企业官网建设流程全解析

Plate 编辑器 Markdown 原生源入口（Source-Entry Surface）交互家族：链接、图片与 HTML 块的统一行为规范

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

导读

本文围绕 Plate 编辑器行为规范栈中的 markdown-native source-entry surface（Markdown 原生源入口表面）交互家族展开，系统讲解 Plate 如何将「链接」「Markdown 图片」「HTML 块」三类看似独立的渲染内容，统一抽象为一个共享「源入口」交互模型，并回答「行为律法（law）究竟应该分散在各类实体上，还是应该识别为一个显式交互家族」这一核心架构问题。读完本文，你将掌握 source-entry surface 的家族定义、Typora 权威模型的判定逻辑、locked/partial状态流转的依据，以及它在规范文档、协议矩阵与 markdown 包源码中的具体落点。

一、背景：Plate 的编辑器行为规范栈

在深入源入口家族之前，需要先理解 Plate 编辑器行为工作的四层文档栈。本文核心文档 2026-04-09-editor-spec-source-entry-surfaces.md 所运行的 editor-spec 工作流，正是围绕这组文档展开：

四者之间的关系在 editor-protocol-matrix.md 中被明确为：先在协议矩阵添加穷尽场景行 → 在可读规范中锁定行为 → 在奇偶矩阵中追踪家族级充分性。如果一个行为只在奇偶矩阵中存在而没有协议行，它就不算协议完备（protocol-complete）。

source-entry surfaces 家族工作流（Phase 表）如下：

二、核心概念：什么是 source-entry surface（源入口表面）

markdown-editing-spec.md 的「Link And Image」一节对 source-entry surface 给出了精确定义：

source-entry surface 是更广泛的 source-preserving conversion（源保留转换）家族中的rendered-content 子家族。

它的核心特征是一条EDIT-INTERACT-*（locked）律法：

rendered markdown-native source surface => plain click edits or expands source-oriented entry mod-click opens or jumps

其判定标准是：

• rendered content 仍然保留一条清晰的回到「类源码编辑」的路径，而不是表现得像被动的纯预览（passive preview-only chrome）；
• 每个实体最终由自己的 node model 决定精确行为，家族只锁定共享的交互形状；
• Typora 是该家族的主要权威（primary owner）。

换句话说，一个「源入口表面」的意思是：渲染态不是终点。链接、图片、HTML 块渲染出来后，普通单击应该进入源码导向的编辑入口，而修饰键单击（mod-click）才执行打开或跳转。这个「渲染态背后存在真实的源码编辑缝隙」的模式，是 Typora 在链接、图片、HTML 块三者上一致的深层行为。

2.1 家族为什么需要统一抽象

在 links-images-and-html-share-a-source-entry-surface.md 这份已接受（accepted）的研究决策中，问题被明确为「Plate 应如何看待渲染后的 markdown 原生链接、图片和 HTML 块」。

决策答案是：将它们视为同一个交互家族：source-entry surfaces。理由在于 Typora 在三者上展示出相同的深层模式：

• 渲染状态不是故事的终点；
• 普通单击与修饰键单击行为不同；
• 渲染表面背后存在真实的源码导向编辑缝隙。

这是一个比「把每一个都当作完全独立特例」更好的心智模型——它能避免为三个实体各写一套互不关联的特殊逻辑，也能让后续新增的 markdown 原生实体（如可编辑的 markdown 图片）自动继承家族级律法。

三、家族构成与节点模型映射

source-entry surface 家族显式覆盖三类实体。根据 editor-protocol-matrix.md 的 Entity Model Map，它们的节点模型如下：

节点模型的差异决定了家族内部每个实体的精确行为：

• 链接是内联非空跨度（inline non-void span），拥有方向性亲和（directional affinity）：从链接侧向内输入会扩展链接，从纯文本侧向内输入则保持在链接外（EDIT-AFF-LINK-001locked）；
• Markdown 图片在当前编辑器模型中是被动媒体原子（block void media atom），其 markdown 语法问题属于序列化/解析器范畴，而不是直接的纯文本按键所有者；
• HTML 块是块级非空内容（block non-void），以源码规范的（source-canonical）可编辑源码文本形式存在。

3.1 HTML 块：从 partial 到 locked 的状态流转

这是本家族工作流中最关键的一个状态变化。在 2026-04-09-editor-spec-html-block-current-surface.md 中记录了完整的推理链条：

1. 初始状态：HTML block 在奇偶矩阵中被跟踪为partial——现有功能可用，但契约或覆盖仍然薄弱；
2. 证据评估：Typora 对 HTML 块编辑入口的证据很强，但 Plate 本地对「更丰富的渲染编辑 chrome」的证据仍比链接和 markdown 图片薄弱；
3. 关键转折：markdown 包曾经在反序列化时把通用 HTML 节点降级为纯文本（lossy fallback text），因此没有新的运行时/测试工作就无法诚实地升到locked；
4. 实现缝隙：选择「更忠实保留原始 HTML 块源码」作为最小诚实缝隙——在 markdown 反序列化中保留属性与嵌套源结构，让 HTML 保持为可编辑源码而不是丢失信息的回退文本；
5. 契约收窄：诚实的当前契约比原始行措辞更窄——源码规范的（source-canonical）可编辑 HTML 源码文本是当前契约，更丰富的渲染编辑 chrome 被明确延迟（deferred）；
6. 结果：契约收窄之后，HTML block 才有资格从partial移至locked。

这个流程同时贯彻了两条重要原则：Authority 不变（Typora 本来就是该行为的真正拥有者），以及不做未经证实的 research-full pass（编译后的研究通道已足够支撑家族级律法）。

四、权威模型：为什么 Typora 是家族所有者

在 markdown-standards.md 的权威顺序（Authority Order）中，行为决策遵循：

1. 语法规范（syntax spec）；
2. 显式表面定义与节点模型；
3. 具有真实证据的最强表面特定 UX 权威；
4. 可检查的交叉校验与最强相邻先例；
5. 仅当其他都沉默或不兼容时才显式回退。

对 source-entry surface 家族而言，每一层都指向 Typora：

• Typora 参考池明确包含「markdown 原生链接与类图片源码语法的点击即编辑行为」与「HTML 块编辑入口」；
• 同时，markdown-standards.md 明确警告：不要把 Obsidian 当作渲染链接、图片、HTML 块的通用 markdown-first 源入口行为的默认所有者——Obsidian 的强项是双模式与笔记链接导航；
• Milkdown充当可检查的开源交叉校验，用于在 Typora 行为难以直接检查的场景中对照 markdown-first 编辑选择。

在 markdown-editing-spec.md 的源保留转换家族中，权威进一步细化：

• Typora：源码导向编辑与显式转换手感；
• Obsidian：保守的 markdown 敏感转换压力；
• Milkdown：可检查的触发/输入规则转换机制。

同时该规范强调：source-preserving conversion 是更广泛的家族，覆盖「渲染的源入口表面」和「输入的语法触发转换」两个子家族。不完整或歧义的源码应该保持字面量（EDIT-CONVERT-001），只有到达显式、无歧义的边界时才允许转换，且转换后用户仍应保有一条源码导向编辑缝隙或一个显式结构化编辑器（EDIT-CONVERT-002）。

五、协议矩阵中的源入口行

editor-protocol-matrix.md 的「Cross-Surface Interaction Backfill」一节为 source-entry surface 家族建立了显式协议行：

这两行锁定了家族级共享交互形状：普通单击走源码编辑入口，修饰键单击打开/跳转。协议矩阵的 Row Schema 要求每一行都回答 Family、Entity、Node Model、Context、Selection、Caret/Edge、Input、Expected、Authority、Spec ID、Evidence、Status 十二个维度——这也是后续任何新实体加入家族时必须填写的完整场景表单。

5.1 HTML 块协议行与奇偶行

HTML 块在协议矩阵中还有一条反序列化相关的行（tested状态）：

同时，markdown-parity-matrix.md 中 HTML block 的家族行状态为locked，其 Behavior Scope 被精确定义为「source-canonical editable HTML block source as a source-entry surface, with richer rendered edit chrome deferred」，行为证据（Current Evidence）指向 deserialize 测试、customMdxDeserialize 测试、HTML-block 编辑入口的 Typora 研究以及协议矩阵。

六、可读规范中的家族律法落点

6.1 Link（locked）

在 markdown-editing-spec.md 中，链接的源入口律法包括：

• EDIT-LINK-CLICK-001locked：普通单击渲染链接 → 展开链接源码或链接编辑表面，优先编辑器内编辑而非立即外部导航；
• EDIT-LINK-CLICK-002locked：修饰键单击渲染链接 → 打开目标；
• EDIT-AFF-LINK-001locked：方向性亲和，链接侧进入扩展链接、纯文本侧进入保持在外部。

6.2 Image（locked）

图片的EDIT-IMG-*locked律法：

Caption

note：纯 markdown 图片只携带 alt、src 和可选 title；width 与 height 保持 HTML/MDX-only，不属于纯 markdown。图片标题来自node.title，caption 或 alt 不会合成 markdown title。当 markdown 原生图片表面可直接编辑时，普通单击应优先源码编辑而非被动渲染行为。Typora 是 markdown 原生图片创作行为的赢家（拖放、剪贴板插入、相对路径生成、源码编辑期望），但 Typora 的./前缀与相对路径策略属于未来 profile 选项候选，不是当前基线律法。

6.3 HTML Block（locked）

HTML 块的EDIT-INTERACT-*locked律法：

<figure class="hero"> <img src="/image.png" /> </figure>

note：当前 Plate 的 html-block 行为将原始 HTML 块源码保留为可编辑源码文本；当前表面是**源码规范的（source-canonical）**而非预览优先；更丰富的渲染 HTML 预览或块级 chrome 被延迟，直到后续产品通道显式选择。

6.4 家族与转换家族的边界

规范同时强调 source-entry surface 与 typed syntax-trigger conversion（输入语法触发转换）同属 source-preserving conversion 家族，但实现归属不同：

• 渲染的源入口表面归属于拥有该功能的特性包与渲染/编辑入口层；
• 输入的语法触发转换归属于共享输入基础设施（靠近特性包），而不是解析器专属代码，也不默认进入通用 autoformat。

当前 Plate 实际交付的是「渲染的源入口子家族」多于「输入语法触发子家族」——link automd（text收尾)触发结构化链接）与 math 分隔符转换是后者的已交付成员。

七、源码佐证：markdown 包中的 HTML 块实现

7.1 反序列化规则

在 defaultRules.ts 中，HTML 块的html规则如下：

html: { deserialize: (mdastNode, _deco, _options) => ({ text: (mdastNode.value || '').replaceAll('<br />', '\n'), }), },

这段代码印证了契约的核心：HTML 节点在反序列化时被转换为保留源码的文本节点（<br />被归一化为换行），而不是被丢弃属性、降级为丢失信息的回退文本。这正是「source-canonical editable HTML source text」这一契约的运行时实现缝隙。

7.2 测试验证

在 deserializeMd.spec.ts 中，新增了直接测试：

it('preserves raw html blocks as editable source text paragraphs', () => { const editor = createTestEditor(); expect( deserializeMd( editor, '<figure class="hero"><img src="/image.png"></figure>' ) ).toEqual([ { children: [ { /* 保留的源码文本 */ }, ], type: /* paragraph */, }, ]); });

正是这一条「源码规范的当前表面」的直接测试覆盖，让 HTML block 有资格从partial移至locked。这与本文核心文档的 Findings 完全一致：HTML block 在 source-canonical 当前表面获得直接 markdown 反序列化器测试覆盖之后才升锁。同时，defaultRules.ts 中type: 'html'与getPluginType(options.editor!, KEYS.img)等规则共同说明：markdown 包以「规则表驱动」的方式统一处理 mdast 节点到 Plate 节点模型的映射，源入口家族的三类实体都在这张规则表中各占一行。

八、工作流方法论：最小诚实的文档更新

本家族工作流的过程记录（Progress Log）展示了 Plate editor-spec 工作流的方法论纪律：

• 2026-04-09：为 markdown-native source-entry surfaces 启动 editor-spec 通道；
• 阅读 editor-spec 栈 + 编译的 Typora source-entry 决策/概念/源码页面；
• 向 standards 添加 markdown-native source-entry 赢家行，向可读 spec 添加家族律法，向协议矩阵添加家族行，向奇偶矩阵添加显式 HTML block 行；
• HTML block 在 markdown 包测试中被直接证明后，从partial移至locked。

核心方法论要点：

1. 最小诚实文档集合（smallest honest set）：不做超出证据支撑的声明；
2. 不做 research-full pass：编译研究通道已足够强，避免重复劳动；
3. Authority 不变：Typora 本来就是该行为的拥有者，家族化只是显式承认；
4. 状态与证据严格绑定：没有直接测试覆盖，就没有locked；
5. 契约收窄优先于过度承诺：宁可把契约定义得窄而诚实（source-canonical editable source text），也不为未来产品功能提前背书。

九、落地路径与后续演进

从 markdown-parity-matrix.md 的 Current Major Gate 与 backlog 可以看出该家族在发布路线中的位置：

• markdown-native 核心（含 link、image、HTML block）已被奇偶矩阵标为locked，即「强到可以在此基础上构建且不阻塞主版本」；
• 更丰富的渲染 HTML-block chrome与 Typora 风格的图片文件系统副作用（移动/复制图片文件、批量路径重写）被明确推迟；
• link automd（text输入规则）与 math 分隔符触发属于 typed syntax-trigger 子家族，前者在协议矩阵中已有tested状态的协议行 linkAutomdInputRule.spec.tsx。

对于想要在 Plate 之上做 markdown-first 产品、或扩展新的 markdown 原生实体的开发者，实操路径是：先在 editor-protocol-matrix.md 添加穷尽场景行 → 在 markdown-editing-spec.md 锁定行为 → 在 markdown-parity-matrix.md 追踪家族级覆盖，并始终以「渲染态背后存在源码导向编辑缝隙」作为 source-entry surface 家族的验收标准。

十、总结

Markdown 原生 source-entry surface 家族是 Plate 编辑器行为规范的一次关键收敛：它将链接、Markdown 图片、HTML 块从三个独立特例统一为一个显式交互家族，以 Typora 为权威、Milkdown 为交叉校验、CommonMark 为语法基准，并通过「契约收窄 + 直接测试覆盖」两条纪律把 HTML block 诚实地从partial提升到locked。这一家族既回答了「渲染态之后如何进入编辑」的产品问题，也为规范栈（standards / spec / protocol / parity）的协作方式提供了完整范本：任何新实体加入家族，都必须同时通过文档、协议行与测试三重验证。

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