Quarto Lua 过滤器系统全解析:多阶段 AST 管线、用户过滤器注入机制与调试实战

原创2026-10-10 23:58:101,621 阅读
文章标签:开发工具文档

Quarto Lua 过滤器系统全解析:多阶段 AST 管线、用户过滤器注入机制与调试实战

Quarto 的 Lua 过滤器系统是一套围绕 Pandoc AST 构建的多阶段文档转换管线,由 src/resources/filters/ 目录下约 212 个 Lua 文件协作完成。本文以 .claude/rules/filters/overview.md 为骨架,结合 main.lua、emulatedfilter.lua 与 filters.ts 等源码,讲清七个阶段的执行顺序、用户过滤器在 filters YAML 键下的真实落点(entry point 拼接机制),并给出源码级的调试手段。读完你将能定位"某个过滤器到底在哪个阶段运行、何时运行",并掌握用 show-ast-trace / make-ast-diagram 可视化 AST 变换的实战方法。

一、系统概览:一条过滤器链,而非多个独立 Pandoc 过滤器

与直觉相反,Quarto 的 Lua 过滤器并不是多个独立的 pandoc --lua-filter 传参并列运行,而是在 main.lua 中维护一条单一过滤器列表(filter list),由 run_as_extended_ast() 统一驱动整条链的顺序执行(见 main.lua)。

这套系统有四个关键设计:

  • 多阶段组织:过滤器按职责分成 INIT、NORMALIZE、PRE、CROSSREF、LAYOUT、POST、FINALIZE 七个阶段,每一阶段对应一个目录与一组具名过滤器条目。
  • 全局状态先行:main.lua 首行通过 import("./mainstateinit.lua") 引入全局状态初始化模块,建立 quarto_global_state、crossref.categories(图表、列表、注记等交叉引用分类表)等运行时数据结构(见 mainstateinit.lua)。
  • 文本拼接式加载:过滤器文件之间用自定义的 import()(内部即 dofile)进行文本级拼接,而可复用模块走 require();这与 Pandoc 标准 Lua 过滤器单文件执行的模型截然不同,也是理解该目录组织方式的起点。
  • Pandoc 解析之后才运行:整条管线处理的是 Pandoc 解析完毕的 AST;把原始 .qmd 文本变成 AST 的工作由独立的 qmd 自定义 reader 完成,详见下文第五节。

二、目录结构逐层解读

src/resources/filters/ 的顶层布局对应管线的各个阶段与支撑设施(目录均已在仓库中确认存在):

filters/
├── main.lua              # 入口:过滤器链定义(约 725 行)
├── mainstateinit.lua     # 全局状态初始化(quarto_global_state、crossref.categories)
├── qmd-reader.lua        # 自定义 Pandoc reader 的薄入口(非过滤器)
├── ast/                  # 自定义 AST 基础设施(scopedwalk、emulatedfilter、customnodes、
│                         #   parse/render/runemulation/traceexecution/wrappedwriter 等)
├── common/               # 共享工具(约 35 个文件:log、debug、format、options、meta 等)
├── modules/              # 可复用模块(36 个 *.lua,经 require() 引入,import_all.lua 统一注册)
├── customnodes/          # 自定义节点实现(callout、proof、theorem、shortcodes、panel-tabset 等)
├── quarto-init/          # 初始化阶段(configurefilters、includes、resourcerefs、knitr-fixup、metainit)
├── normalize/            # 归一化阶段(normalize、flags、astpipeline、capturereaderstate、draft)
├── quarto-pre/           # 预处理(shortcodes、tables、code annotations、hidden、theorems 等 36 文件)
├── crossref/             # 交叉引用系统(figures、tables、equations、theorems、sections、index 等)
├── layout/               # 布局处理(columns、panels、figures、lightbox,以及各格式的 layout)
├── quarto-post/          # 后处理(格式相关渲染:latex、html、typst、reveal、email 等 30 文件)
└── quarto-finalize/      # 最终清理(dependencies、mediabag、meta-cleanup、book-cleanup 等)

关键目录职责

  • ast/ 是整个自定义节点系统的根基:customnodes.lua 定义节点体系,scopedwalk.lua 提供可感知自定义节点的遍历器,emulatedfilter.lua 负责把用户过滤器包装并注入过滤器链(详见第四节)。
  • common/ 是各阶段共用的工具集,其中 log.lua(日志)、debug.lua(dump/tdump 调试输出)、format.lua(输出格式检测)、options.lua(元数据选项读取)是编写过滤器时最常打交道的四个模块。
  • customnodes/ 中每个文件对应一种 Quarto 独有的 AST 节点扩展,例如 callout.lua(提示框)、proof.lua / theorem.lua(证明与定理)、shortcodes.lua(短代码)、floatreftarget.lua(浮动对象引用目标)。

三、过滤器执行管线:七个阶段的完整顺序

原文档定义的执行顺序如下(标注了每个阶段的职责):

1. INIT (quarto-init/)
   ↓
2. NORMALIZE (normalize/)
   ↓
3. PRE (quarto-pre/) - shortcodes, tables, code annotations
   ↓
4. CROSSREF (crossref/) - cross-references
   ↓
5. LAYOUT (layout/) - panels, columns
   ↓
6. POST (quarto-post/) - format-specific rendering
   ↓
7. FINALIZE (quarto-finalize/) - cleanup, dependencies

这一顺序在 main.lua 中由 quarto_init_filters(L229)、quarto_normalize_filters(L257)、quarto_pre_filters(L283)、quarto_crossref_filters(L671)、quarto_layout_filters(L631)、quarto_post_filters(L428)、quarto_finalize_filters(L583)七个具名表逐一 tappend 进 quarto_filter_list 而得到,阶段间还嵌入了多个具名 entry point 空位(见第四节)。

各阶段在源码中的真实映射

  • INIT:quarto_meta_init()、元数据资源引用(file_metadata() + resourceRefs())、knitr 语法修复(仅当 param("execution-engine") == "knitr" 时启用)。
  • NORMALIZE:normalize_draft()、normalize_filter()、normalize_capture_reader_state(),并追加 quarto_ast_pipeline()。源码注释明确说明:v1.4 起 NORMALIZE 负责产出"归一化文档",因此用户过滤器看到的是 Quarto AST——例如 Figure 节点已不再存在,而是由自定义 AST 设施中的 FloatRefTarget 表示(见 main.lua)。这一点对用户过滤器作者极其重要:不要假设 Figure 节点仍存在。
  • PRE:这一阶段条目最多,覆盖短代码(shortcodes_filter(),受 flags = {"has_shortcodes"} 门控)、表格题注(table_captions())、代码注解(code_annotations())、隐藏内容(combineFilters({hidden(), content_hidden()}))、字体回退(normalize_font_fallbacks())、作用域元素解析(resolve_scoped_elements())等。
  • CROSSREF:受 param("enable-crossref", true) 控制(L227),启用时插入 quarto_crossref_filters,处理浮动对象、定理、章节、方程、表格的引用解析与索引写入(resolveRefs()、writeIndex())。
  • LAYOUT:columns_preprocess() → columns() → cites_preprocess() → cites() → layout_panels(),负责面板、分栏、引文与灯箱(lightbox(),受 has_lightbox 门控)。
  • POST:格式相关的渲染与修复全部集中于此——render_latex()、render_typst()、render_dashboard()、render_asciidoc()、render_email()、render_reveal_fixups()、render_html_fixups() 等,多数通过 filterIf(...) 或 flags 按格式与文档特征条件启用。
  • FINALIZE:mediabag_filter()、bookCleanup()、writeCites()、metaCleanup()、dependencies() 与 wrapped_writer(),负责依赖收集、媒体包整理、元数据清理与最终的 writer 包装。

flags:阶段级裁剪机制

留意到许多条目带有 flags 字段(如 has_notes、has_hidden、has_shortcodes、has_font_fallback)。这些 flag 由 normalize/flags.lua 的 compute_flags() 在 PRE 阶段早期计算(其第二返回表持有 Meta 处理器),随后 runemulation.lua 在整个过滤器趟(pass)都无任何 flag 命中时直接跳过该趟遍历。这是 Quarto 对"昂贵但多数文档用不到"的过滤器做的性能裁剪,比在过滤器函数内部提前 return 更彻底。

四、用户过滤器到底落在哪里:entry point 拼接机制

原文档最核心的结论是:用户通过 YAML filters 键声明的过滤器并不是独立的 Pandoc 过滤器趟,而是被"拼接"进 main.lua 的单一过滤器列表,落在其跟随的具名 marker(entry point)处。

两条注入规则

  • 普通 filters 条目落在 pre-quarto:在 Quarto 所有阶段(PRE、CROSSREF、LAYOUT、POST)之前运行。
  • quarto marker 之后的条目落在 post-render:filters 列表中出现字面量 quarto 时,列表在此处被切开,其后所有条目移动到 post-render entry point,即 POST 之后、FINALIZE 之前运行。
  • FINALIZE 恒在两者之后:因为 post-render 在过滤器列表中的位置天然早于 FINALIZE 各条目,所以无论用户过滤器落在 pre-quarto 还是 post-render,FINALIZE 都保证最后执行。

TypeScript 侧:entry point 的生成

YAML 中的 filters 列表由 filters.ts 的 extractFilterSpecParams() 转换为结构化 entry point 描述:

  • 若列表中存在 quarto,则其之前的普通条目发往 kQuartoPre(即 pre-quarto),之后的发往 kQuartoPost(即 post-render);
  • 若无 quarto,所有普通条目一律发往 kQuartoPre;
  • 已具 entry point 形式的条目(带 at 字段)原样保留;
  • 字符串条目按后缀判定类型:以 .lua 结尾为 "lua",否则为 "json";
  • citeproc 恒在最后运行。

最终产物形如 {"at": "pre-quarto", "type": "lua", "path": "my-filter.lua"},经 filterParamsJson() 组装进 QUARTO_FILTER_PARAMS 传给 Pandoc(L128、L183-L187)。

Lua 侧:字面插入而非独立执行

在 emulatedfilter.lua 中,inject_user_filters_at_entry_points(filter_list) 被 main.lua 调用:

  1. 读取 param("quarto-filters").entryPoints,逐条取出 at 字段;
  2. 在 quarto_filter_list 中按名字查找对应 entry point 的索引;
  3. 用 table.insert(filter_list, index, filter) 做字面位置插入——这与文档所述"不是独立执行模式,只是同一列表中的位置"完全一致;
  4. 插入的条目被命名为 <entry-point>-user-<n>,并强制指定 traverser = 'walk'(注释说明:使用默认 walk 遍历而非惰性 jog,避免用户过滤器在某些场景下行为异常);
  5. 若 entry point 名字在列表里找不到,会 warn 提示并回退到 pre-quarto。

main.lua 中的完整 entry point 清单

main.lua 中通过 table.insert(quarto_filter_list, { name = ..., filter = {} }) 预置了 8 个具名空位,它们是用户过滤器的全部合法落点:

entry point 位置 适用场景
pre-ast INIT 之前 在 Quarto 任何阶段之前、且早于初始化
post-ast INIT、NORMALIZE 之后,PRE 之前 需要在归一化之后介入
pre-quarto PRE 之前 普通 filters 条目的默认落点
post-quarto PRE/CROSSREF/LAYOUT 之后 需要看到 Quarto 阶段处理结果
pre-render LAYOUT、POST 之前 渲染前介入
post-render POST 之后、FINALIZE 之前 quarto marker 之后条目的落点
pre-finalize FINALIZE 之前 清理阶段前介入
post-finalize FINALIZE 之后 整个管线的最后钩子

实战配置示例

# 普通写法:my-filter.lua 落在 pre-quarto(在 PRE/CROSSREF/LAYOUT/POST 之前运行)
filters:
  - my-filter.lua

# 带 quarto marker:my-first.lua 落在 pre-quarto,my-second.lua 落在 post-render
filters:
  - my-first.lua
  - quarto
  - my-second.lua

# entry point 显式写法(与源码中 QuartoFilterEntryPoint 结构对应)
filters:
  - at: post-render
    type: lua
    path: my-filter.lua

五、与 Pandoc 解析阶段的关系:qmd reader 是前置的"另一个世界"

需要特别强调:上述整条管线运行于 Pandoc 解析出 AST 之后。把原始 .qmd 文本变成 AST 的是 Quarto 的自定义 Lua reader(qmd-reader.lua 及 src/resources/pandoc/datadir/readqmd.lua),它:

  • 在独立的 Lua 上下文中运行,过滤器链中的全局量(如 crossref.categories)在其中不存在;
  • 通过文档元数据与 param(...) 与过滤器通信;
  • 在解析前做原始文本变换(短代码编码、fenced-code 转义),遵循"转义—还原"模式。

在 pandoc.ts 中,每次 Pandoc 调用前 Quarto 都会把 --from 强制设为 filters/qmd-reader.lua,同时把用户原本的 from 值保存为 user-defined-from 参数供 reader 内部参考。因此:凡是需要在 Pandoc 解析行为层面改变的东西(例如新的语法糖、块级语法),必须改 reader 而不是过滤器。读者可进一步阅读 llm-docs/qmd-reader-architecture.md 了解该阶段的完整架构。

六、关键文件一览

文件 用途
main.lua 过滤器链定义(约 725 行):全部 import、七阶段过滤器表、8 个 entry point 空位
mainstateinit.lua 全局状态初始化:quarto_global_state、crossref.categories
ast/customnodes.lua 自定义节点系统(节点类型、_quarto.ast.walk 遍历入口)
ast/emulatedfilter.lua 用户过滤器包装与 entry point 注入实现(table.insert 字面插入)
ast/runemulation.lua 扩展 AST 模拟执行,按 flags 跳过整趟遍历
common/log.lua 日志工具(info/warn/error,warn 在 TypeScript 侧显示为 INFO)
common/debug.lua 调试工具(dump、tdump)
common/format.lua 输出格式检测(HTML/LaTeX/Typst/DOCX/Reveal.js/Dashboard)
common/options.lua 元数据选项读取(option()),与 param() 配合
normalize/flags.lua 文档特征 flag 计算(has_notes、has_hidden 等)

面向过滤器开发者的关键约定(摘要)

若你打算为 Quarto 编写 Lua 过滤器,.claude/rules/filters/lua-development.md 中还有一批与本节紧密相关的硬性约定,其中最容易踩坑的几条:

  • import() 只用于过滤器文件,require() 只用于 modules/ 模块;在 import() 的文件中优先通过 _quarto.modules.<name>.<fn>(...) 引用已注册模块,避免新增顶层 local 变量触及 Lua 单函数 200 局部变量上限(详见 llm-docs/lua-filter-bundle-local-limit.md)。
  • 自定义节点遍历必须用 _quarto.ast.walk(),pandoc.walk_block 会漏掉自定义节点。
  • 格式门控要放在元素函数内部,而不是过滤器构造函数顶部:main.lua 在加载期(输出格式尚未解析)就调用构造函数,构造函数顶部的 if not _quarto.format.isLatexOutput() then return {} end 会提前求值成空过滤器,导致过滤器对任何文档都不生效(参考 quarto-pre/font.lua)。
  • 昂贵过滤器用 flags 门控整趟遍历,而不是在函数内提前 return。
  • 过滤器返回值语义:返回 nil 表示"继续、不改动",返回新元素表示"替换",返回空列表 {} 表示"删除该元素"。

参数传递:param() 与 QUARTO_FILTER_PARAMS

过滤器内部读取配置用 param("my-key", default)(如 param("enable-crossref", true)、param("execution-engine"))。该机制经 QUARTO_FILTER_PARAMS 环境变量(base64 编码的 JSON)从 TypeScript 侧传入,在 src/resources/pandoc/datadir/init.lua 中解码,对 Pandoc 模板与元数据完全不可见、不造成污染(详见 .claude/rules/filters/filter-params.md)。

七、调试与可视化:追踪 AST 在每个阶段的变换

过滤器调试的痛点在于"看不见 AST 在链中如何变化"。Quarto 为此提供了两个 dev-call 子命令(用法细节见 .claude/rules/dev-tools/dev-call-commands.md):

show-ast-trace:交互式追踪查看器

package/dist/bin/quarto dev-call show-ast-trace document.qmd
package/dist/bin/quarto dev-call show-ast-trace document.qmd --to html

执行流程:渲染文档并开启 AST 追踪 → 在缓存目录生成 <basename>-quarto-ast-trace.json → 在浏览器中启动交互式查看器。它适合回答"某个元素在第几个阶段被改成了什么"这类问题。

Quarto Lua 过滤器追踪查看器界面截图,用于可视化文档 AST 在各过滤器阶段的逐步转换

局限性:对 website/book 这类多文件项目支持不佳(环境变量无法按文件区分),且只展示 Pandoc 过滤器链的行为,不覆盖 postprocessor 与 writer 阶段。

make-ast-diagram:静态 AST 结构图

package/dist/bin/quarto dev-call make-ast-diagram document.qmd
package/dist/bin/quarto dev-call make-ast-diagram document.qmd --mode full

生成文档 Pandoc AST 的静态结构图,适合理解嵌套元素、排查复杂布局,比完整追踪更轻量。

备选:环境变量手动追踪

在常规渲染中设置 QUARTO_TRACE_FILTERS 环境变量即可开启追踪输出。完整的手动追踪指南见 dev-docs/lua-filter-trace-viewer.qmd。

八、延伸阅读

理解这条单一过滤器链及其 entry point 拼接机制,是深入 Quarto 渲染内核的第一步:它决定了任何用户过滤器的执行时机、可见的 AST 形态,以及能影响哪一阶段的产物——而这三点,正是调试一切渲染问题的关键坐标。

登录后查看全文
quarto-cli