#工作原理

库把渲染拆成可以分别部署的阶段。理解这条管线和两种快照，就能判断什么时候该用根入口，什么时候该把解析放到服务端。

#处理管线

source
  │
  ├─（可选）/expand ─▶ 展开后的 source
  │
  ▼
/parse ─▶ WikitextDocument（解析快照）
  │
  ▼
/hast prepare ─▶ WikitextRenderDocument（渲染快照）
  │
  ▼
/view ─▶ React

/expand 的结果已经是解析文档，不需要再手动解析一次；直接交给 prepareWikitext。

#两种快照

#解析快照 WikitextDocument

interface WikitextDocument {
  readonly source: string;
  readonly ast: WikitextRoot;
  readonly syntax?: WikitextSyntaxRoot;
  readonly meta: WikitextDocumentMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}

• ast 是归一化后的语义树，准备阶段不会修改它。
• syntax 只在 retainSyntax: true 时存在，用于源码坐标与 playground。
• 同一份源码配合不同的站点配置或 pageName，可能得到不同的 AST。

#渲染快照 WikitextRenderDocument

interface WikitextRenderDocument {
  readonly source: string;
  readonly ast: WikitextRoot; // 插件处理后的工作树
  readonly hast: import("hast").Root; // 已清洗的最终 HAST
  readonly headings: readonly WikitextHeadingInfo[];
  readonly meta: WikitextRenderMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}

• hast 已经包含目录、引用区与分类底栏，不需要在视图层再拼装。
• ast 是本次工作树的结果，节点 id 已经重新分配。
• meta 记录实际生效的策略、文案、标题策略与授权图片。
• WikitextView 只接受渲染快照，不接收源码。

查询节点时必须区分两份快照：不要用渲染快照里的 id 查原始解析快照。

#为什么要拆成两段

解析成本高，而准备选项经常变化。缓存解析快照，就可以用不同的链接、图片、文案或插件重复准备，而不必重新解析。服务端准备、客户端渲染也是同一套快照：客户端不加载解析器，也不重跑插件。

准备阶段在克隆的工作树上执行，原始快照保持只读。快照是普通数据，可以放进缓存、跨 Worker 传递或经网络传输；恢复函数会重新校验结构与预算。

#语义归一化

上游解析器给出的是源码语法树。库在语义阶段完成结构归一化，React 层不再扫描源码。

无法安全或正确表达的结构会降级为源码卡片并写入诊断，不推断外观。模板、解析器函数、参数与文件默认输出占位，避免把“未求值”误当成“已求值”。

源码 HTML 按类别处理：允许的标签按白名单输出，禁止的标签整对丢弃并提示，未知标签降级。链接与图片在最终整理阶段再次校验协议、target、rel 与图片授权。

这套策略优先保证每一段输出都能解释、能审计，不追求最大化还原 Wikipedia。

#入口与加载边界

完整导出清单见入口总览。

#术语

#下一步

• 基本用法：源码组件与显式管线。
• 服务端与框架：快照序列化、Next.js 与 hydration。
• 准备 /hast：插件、解析函数、策略与快照恢复。