全景

这一部分先回答「pull parser 是什么、它换来了什么」，再把块、行内、输出三条主线在一份 21 行的例子文档上完整走一遍，最后讲用户唯一能直接拿到的东西：事件。每一步只讲到能看清全貌的深度，细节链到 02 到 05。实验都在 M2 Max、macOS 27、rustc 1.99.0 上跑，pulldown-cmark 0.13.5。

1. 为什么是 pull parser：README 的定位和它没说的部分：第一个事件出来之前整份文档已经扫过一遍、建好了块树；和建 AST 的 comrak、先攒全部事件再编译的 markdown-rs 比，同样过了 CommonMark 0.31.2 的 652 个例子，只解析不输出时比 comrak 快 2 到 3 倍、比 markdown-rs 快 20 到 80 倍，在 spec.txt 上峰值内存约为 comrak 的四分之一、markdown-rs 的三十分之一；在本站 1099 篇文档上三者输出有 18 篇不同，三个最小复现都是另外两个库的问题。
2. 一份文档：例子文档第一遍建出的 69 个节点，链接定义不在树里、实体已经解出来、行内语法先记成占位；next 走到占位节点才调 handle_inline，6 次调用和事件交错出现，节点数不变；最后写成 HTML。0.13.5 摘进来的 #1148 让一种列表输入从 5 秒降到 3 毫秒。
3. 事件模型：Event、Tag、TagEnd 的各个变体，TagEnd 为什么只有 2 字节，CowStr 让事件借用输入，OffsetIter 的范围指什么。

flowchart TB
  why[为什么是 pull parser] --> doc[一份文档]
  doc --> ev[事件模型]
  doc --> blocks[02 块解析]
  doc --> inl[03 行内解析]
  ev --> mem[04 字符串与内存]
  ev --> out[05 输出]