先看结果：干净克隆里的 make ci#

我先把标签克隆到一个全新的目录里，再跑一遍：

1
git clone --branch tutorial-v1 https://github.com/bfmhno3/typst-lab.git /tmp/lab16
2
cd /tmp/lab16
3
( time nix develop --command make ci ) > /tmp/ci.log 2>&1

（我克隆的是本机仓库的同一个标签，读者用上面的 GitHub 地址。@preview 缓存在我这台机器上是热的，第 14 篇的包不需要重新下载，后面 CI 一节会谈冷缓存。）

1
$ grep -c '^ok ' /tmp/ci.log
2
106
3
$ grep -c FAIL /tmp/ci.log
4
0
5
$ grep '^real' /tmp/ci.log
6
real  0m12.222s

/tmp/ci.log 里本篇的那一章是这样的：

1
./scripts/chapter.sh ch16
2
ok   lab/ch16/eval.typ
3
ok   lab/ch16/metadata.typ
4
ok   lab/ch16/pdf-standards.typ
5
ok   pdf-standards a-2b,ua-1
6
ok   html
7
ok   bundle
8
ok   eval items = 3
9
ok   eval problems = 4
10
ok   timings (18842 events)
11
ok   deps

12.2 秒花在哪里？Makefile 里决定顺序的是这几行（缩进是制表符）：

1
ci: fmt-check all
2

3
all: examples $(CHAPTERS) test

我用 hyperfine 单独量了其中几块：

剩下的零头是 nix develop 进入环境本身（nix develop --command true 0.23 s）。结论很直白：测试只占 0.43 s，时间几乎都在编译各章的实验文件。这个比例是我愿意把测试写得多一点的原因，后面“测试”一节会说怎么写。

document：PDF 元数据从哪来#

PDF 的标题、作者、关键词不是排版出来的，是 document 这个“设置规则”写进文件信息字典和 XMP 里的。lab/ch16/metadata.typ：

1
// `document` sets the PDF metadata; the template fills it from `note`.
2
#set document(
3
  title: "元数据演示",
4
  author: ("bfmhno3", "Zhang San"),
5
  keywords: ("Typst", "PDF"),
6
  date: datetime(year: 2026, month: 10, day: 19),
7
)
8

9
= 元数据
10

11
用 `pdfinfo` 或 `exiftool` 查看这份 PDF 的标题、作者和关键词。

pdfinfo out/ch16/metadata.pdf（这台机器没有 exiftool，我用的是 poppler 的 pdfinfo）：

1
Title:           元数据演示
2
Keywords:        Typst, PDF
3
Author:          bfmhno3, Zhang San
4
Creator:         Typst 0.15.1
5
CreationDate:    Sun Oct 18 17:00:00 2026 PDT
6
ModDate:         Sun Oct 18 17:00:00 2026 PDT
7
Custom Metadata: no

作者的数组被 pdfinfo 用逗号连起来了。时间看起来差了一天，是因为 datetime(year:, month:, day:) 不带时分秒，取当天 00<00>，而这台机器的时区让 pdfinfo 把它换算成了 PDT。换成 UTC 就对了：

1
$ TZ=UTC pdfinfo out/ch16/metadata.pdf | grep CreationDate
2
CreationDate:    Mon Oct 19 00:00:00 2026 UTC

不写 date 会怎样？examples/notes 就没写，它的创建时间是编译那一刻（Mon Oct 19 09:12:56 2026 PDT，是我跑 make ci 的时间；前一次编译读到的是 08:54:07），每次编译都不同。要让 PDF 的元数据可复现，就要显式写 date。flake.nix 的 shellHook 里有一行 unset SOURCE_DATE_EPOCH，也是为了让 datetime.today() 在 nix 里取到真实日期（否则它会返回 1980-01-01）。

xuan 的 note 在第 4 篇就已经替你做了这件事，src/note.typ 里：

1
  set document(
2
    title: title,
3
    author: ensure-array(author),
4
    keywords: keywords,
5
  )

（这是该文件第 20 到 24 行的原样引用，函数头和其余部分在第 4、10 篇已经展示。）pdfinfo out/examples/notes.pdf 因此直接给出 Title: 线性代数笔记：最小二乘与 SVD、Keywords: 最小二乘, SVD, 伪逆、Author: bfmhno3。模板的价值之一就在这里：作者只写一次 title:，页面上的标题块、页眉和 PDF 元数据三处同时对上。

—pdf-standard：同时满足 PDF/A 和 PDF/UA#

lab/ch16/pdf-standards.typ：

1
// Compiled twice: plain, and with `--pdf-standard a-2b,ua-1` (see extra.sh).
2
#set document(title: "PDF/A 与 PDF/UA", author: "bfmhno3")
3
#set text(font: ("Libertinus Serif", "Noto Serif CJK SC"), lang: "zh")
4

5
= 带标签的 PDF
6

7
标准要求字体全部嵌入、文档有标题和语言，PDF/UA 还要求图片有替代文字。
8

9
#figure(
10
  rect(width: 3cm, height: 1cm, fill: aqua),
11
  alt: "一个浅蓝色矩形",
12
  caption: [图片必须有 alt。],
13
)

同一个文件编译了两次：chapter.sh 的通用循环出一份不带标准的 PDF，extra.sh 再带 --pdf-standard a-2b,ua-1 出一份。0.15 起这个选项可以接逗号分隔的多个标准，一个归档标准（PDF/A）和一个无障碍标准（PDF/UA）可以叠在一起。我从 XMP 元数据里把标准声明抠出来对比：

1
$ pdfinfo -meta out/ch16/pdf-standards.pdf | grep -Eo '<pdfaid:[a-z]*>[^<]*|<pdfuaid:[a-z]*>[^<]*|<pdf:PDFVersion>[^<]*'
2
<pdf:PDFVersion>1.7
3
$ pdfinfo -meta out/ch16/pdf-standards-a2b-ua1.pdf | grep -Eo '<pdfaid:[a-z]*>[^<]*|<pdfuaid:[a-z]*>[^<]*|<pdf:PDFVersion>[^<]*'
4
<pdfaid:part>2
5
<pdfaid:conformance>B
6
<pdfuaid:part>1
7
<pdf:PDFVersion>1.7

普通的那份没有任何标准声明；带标准的那份声明了 PDF/A-2b 和 PDF/UA-1。文件大小从 25566 字节涨到 29557 字节，我猜多出来的主要是 XMP 里那批 PDF/A 扩展 schema（pdfinfo -meta 的输出里能看到 pdfaExtension:schemas），没有逐字节核对。pdffonts 显示四个字体子集（两个 Noto Serif CJK、两个 Libertinus Serif）全部 emb yes。

至于 Tagged: yes：两份 PDF 都是。typst compile --help 对 --no-pdf-tags 的说明是，即使不要求 PDF/UA，Typst 默认也会写出带标签的 PDF 作为无障碍基线。所以带标准的那份并不是“多了标签”，而是“多了检查”。检查不过会直接报错，我写了两个会失败的小文件（不在仓库里，在 /tmp 里）：

1
#set document(title: "t", author: "a")
2
#figure(rect(width: 3cm, height: 1cm, fill: aqua), caption: [x])

1
$ typst compile --pdf-standard a-2b,ua-1 noalt.typ noalt.pdf
2
error: PDF/UA-1 error: missing alt text
3
  ┌─ ../p16/noalt.typ:2:1
4
  │
5
2 │ #figure(rect(width: 3cm, height: 1cm, fill: aqua), caption: [x])
6
  │  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7
  │
8
  = hint: make sure your images and equations have alt text

另一个文件只有一行 = hi，用 --pdf-standard ua-1 编译：

1
error: PDF/UA-1 error: missing document title
2
 = hint: set the title with `set document(title: [...])`

两个标准的组合也有硬约束。PDF/A 只能选一个，A-4 要求 PDF 2.0 而 UA-1 只到 1.7：

1
$ typst compile --pdf-standard a-1b,a-2b ...
2
error: choose at most one PDF/A standard
3
$ typst compile --pdf-standard a-4,ua-1 ...
4
error: PDF/A-4 and PDF/UA-1 are mutually incompatible because they do not have any overlapping PDF versions
5
hint: PDF/A-4 requires version PDF 2.0
6
hint: PDF/UA-1 requires a version between PDF 1.4 and PDF 1.7

我试了 a-3b,ua-1，通过；xuan 的几份模板我没有逐个拿去过这个检查，所以不声称它们都满足 PDF/UA（note 里的图要带 alt，这需要写文档的人负责）。

PNG 与 SVG：—ppi 和页码模板#

位图和矢量图的输出用同一组选项：--format png|svg，--pages 选页，--ppi 定位图的分辨率（默认 144），输出路径里的 {p} 和 {0p} 是页码模板。我拿 17 页的 examples/slides 来试：

1
typst compile --root . --ignore-system-fonts --pages 1-3 --format png --ppi 72 \
2
  examples/slides/main.typ "/tmp/p16/png/s-{0p}.png"

1
$ ls -l /tmp/p16/png
2
-rw-r--r-- 1 bfmhno3 users 14794 Oct 19 08:55 s-01.png
3
-rw-r--r-- 1 bfmhno3 users 11569 Oct 19 08:55 s-02.png
4
-rw-r--r-- 1 bfmhno3 users 27361 Oct 19 08:55 s-03.png

这条命令（--pages 1-3，72 ppi）的挂钟时间是 0.137 s。注意文件名是 01 而不是 1：我只导出了前 3 页，文件名却补了零，我猜是 {0p} 按文档的总页数（17 页，宽度 2）补零，没有去核对源码。{p} 则不补零。同一份文档导出 SVG：

1
$ typst compile ... --format svg examples/slides/main.typ "/tmp/p16/png/v-{p}.svg"
2
$ ls /tmp/p16/png | grep svg | head -20 | tr "\n" " "
3
v-10.svg v-11.svg v-12.svg v-13.svg v-14.svg v-15.svg v-16.svg v-17.svg v-1.svg v-2.svg v-3.svg v-4.svg v-5.svg v-6.svg v-7.svg v-8.svg v-9.svg

17 个文件，v-1.svg 到 v-17.svg。想按字典序排好就用 {0p}，这是它存在的全部理由。如果输出多页却不写模板，Typst 直接拒绝：

1
error: cannot export multiple images without a page number template ({p}, {0p}) in the output path

--ppi 控制像素尺寸，不改变页面的物理尺寸。examples/slides 的第 1 页是 16<9> 的演示页：

1
$ file s-01.png s144.png s288.png      # 分别是 --ppi 72、144、288
2
s-01.png: PNG image data, 842 x 474, ...
3
s144.png: PNG image data, 1684 x 947, ...
4
s288.png: PNG image data, 3368 x 1894, ...

像素数正好随 ppi 线性变化。博客里嵌图我一直用 144，是在清晰度和体积之间的折中，没有更深的道理。

HTML 与 MathML#

HTML 导出在 0.15.1 里仍然要用 --features html 打开，编译器会明说它在开发中。lab/ch16/html/site.typ：

1
// Compiled with `--features html --format html` (see ../extra.sh).
2
#set document(title: "HTML 导出", author: "bfmhno3")
3

4
= HTML 导出
5

6
段落、*强调*与行内公式 $x^2 + y^2 = z^2$ 会变成语义化的标签，公式导出为 MathML。
7

8
- 列表
9
- 也一样
10

11
#html.elem("div", attrs: (class: "note"))[自定义元素：`html.elem`。]

编译后的 out/ch16/site.html 一共 2109 字节，其中一大半是 <head> 里内联的 MathML 样式表。我只取 <body>：

1
$ grep -o '<body>.*' out/ch16/site.html
2
<body><h2>HTML 导出</h2><p>段落、<strong>强调</strong>与行内公式 <math><msup><mi>𝑥</mi><mn>2</mn></msup><mo>+</mo><msup><mi>𝑦</mi><mn>2</mn></msup><mo>=</mo><msup><mi>𝑧</mi><mn>2</mn></msup></math> 会变成语义化的标签，公式导出为 MathML。</p><ul><li>列表</li><li>也一样</li></ul><div class="note">自定义元素：<code>html.elem</code>。</div></body></html>

几个值得看的点：

• = HTML 导出 变成了 <h2>，不是 <h1>。我猜 Typst 把一级标题降了一级，是为了留出 <h1> 给页面标题，但没有查文档证实；<title> 里确实是 HTML 导出。
• 公式是 <math> 加 <msup>、<mi>、<mo> 这套 MathML，不是图片也不是 SVG。字母 x 写成了 𝑥（U+1D465，Unicode 的数学斜体字母），不是普通的 x。
• html.elem("div", attrs: (class: "note"))[...] 是通往原始 HTML 的后门：标签名和属性自己指定。
• 编译时 stderr 有一段警告：warning: html export is under active development and incomplete，附 hint: its behaviour may change at any time 和一个 issue 链接。不加 --features html 则报错 error: html export is only available when —features html is passed。环境变量 TYPST_FEATURES=html 与命令行开关效果相同：我用环境变量编译出的文件和上面那份 cmp 比较，逐字节相同。

还有一个细节。上面的 <html lang="en">：这个实验文件没有 #set text(lang: "zh")，所以尽管内容是中文，lang 仍是默认的 en。块公式（display="block"）我在 /tmp 里单独试了：

1
#set text(lang: "zh")
2
#set document(title: "t")
3
= 标题
4
块公式：
5
$ A = U Sigma V^T $

1
<html lang="zh">
2
<body><h2>标题</h2><p>块公式：</p><math display="block"><mi>𝐴</mi><mo>=</mo><mi>𝑈</mi><mi mathvariant="normal">Σ</mi><msup><mi>𝑉</mi><mi>𝑇</mi></msup></math></body></html>

lang 传到了 <html lang="zh">，块公式带 display="block"，希腊字母 Σ 是 mathvariant="normal"（直立），拉丁字母 A、U、V、T 是 Unicode 数学斜体字母。

bundle：一次编译出一个站点#

bundle 是 0.15 的实验性导出：一份源文件里用 document(...) 声明多个输出文档，用 asset(...) 声明原样输出的文件，整个编译产出一个目录。lab/ch16/bundle/site.typ：

1
// Compiled with `--features bundle,html --format bundle` (see ../extra.sh).
2
#document("index.html", title: [首页])[
3
  = 首页
4
  #link(<blog>)[进入博客] 或下载 #link(<blog-pdf>)[PDF 版]。
5
]
6

7
#let post = [
8
  == 博客
9
  同一份内容同时输出为网页和 PDF。
10
]
11

12
#document("blog.html", title: [博客])[#post] <blog>
13

14
#document("blog.pdf", title: [博客])[#post] <blog-pdf>
15

16
#asset("hello.txt", bytes("hello from bundle"))

注意命令行要同时打开 bundle 和 html：

1
typst compile --root . --ignore-system-fonts --features bundle,html --format bundle \
2
  lab/ch16/bundle/site.typ out/ch16/bundle

只开 bundle 会失败，因为里面有 .html 文档：

1
error: html export is only available when the `html` feature is enabled
2
  ┌─ lab/ch16/bundle/site.typ:2:1

编译成功后输出路径是一个目录：

1
$ ls -l out/ch16/bundle
2
-rw-r--r-- 1 bfmhno3 users   243 Oct 19 09:13 blog.html
3
-rw-r--r-- 1 bfmhno3 users 14093 Oct 19 09:13 blog.pdf
4
-rw-r--r-- 1 bfmhno3 users    17 Oct 19 09:13 hello.txt
5
-rw-r--r-- 1 bfmhno3 users   277 Oct 19 09:13 index.html

输出格式由文件名后缀决定：blog.html 是网页，blog.pdf 是一份真的 PDF（pdfinfo 读出 Title: 博客、Pages: 1）。最妙的是交叉引用，index.html 里：

1
<p><a href="blog.html">进入博客</a> 或下载 <a href="blog.pdf">PDF 版</a>。</p>

#link(<blog>) 指向的是另一个文档的标签，在 HTML 里变成了相对路径 blog.html。同一份 post 内容被同时放进网页和 PDF，这也是我以后想用它的场景：同一个笔记，既能在网上读又能打印。至于 == 在 blog.html 里是 <h3>：它在 document 里是二级标题，降一级之后就是 h3。

stderr 里有 warning: bundle export is experimental 和 hint: do not rely on this feature for production use cases。我听从它：这一章只验证它能编译，没有拿它生产任何东西。

typst eval：不生成文档，只问一个问题#

typst eval <表达式> --in <文件>（取代已弃用的 typst query）在那份文档的上下文里求值一个表达式，把结果序列化成 JSON 或 YAML 打印。lab/ch16/eval.typ：

1
// A small target for `typst eval`: three labelled items and two headings.
2
= 标题一
3
== 标题二
4

5
#metadata("甲") <item>
6
#metadata("乙") <item>
7
#metadata("丙") <item>

1
$ typst eval --root . "query(<item>).len()" --in lab/ch16/eval.typ
2
3
3
$ typst eval --root . "query(<item>).map(m => m.value)" --in lab/ch16/eval.typ
4
["甲","乙","丙"]
5
$ typst eval --root . --format yaml "query(<item>).map(m => m.value)" --in lab/ch16/eval.typ
6
- 甲
7
- 乙
8
- 丙
9
$ typst eval --root . --pretty "query(heading).map(h => h.level)" --in lab/ch16/eval.typ
10
[
11
  1,
12
  2
13
]

第 12 篇里我用 query 在文档内部数过 <xuan-problem>，现在它跑在文档外面：

1
$ typst eval --root . --in examples/homework/main.typ "query(<xuan-problem>).len()"
2
4
3
$ typst eval --root . --in examples/homework/main.typ "query(<xuan-problem>).map(m => m.value)"
4
[25,25,20,30]
5
$ typst eval --root . --in examples/homework/main.typ "query(<xuan-problem>).map(m => m.value).sum()"
6
100

作业的总分 100 不用打开 PDF 就能读出来，make ch16 把第一条的结果存进 out/ch16/eval.txt（内容是 4），这就是仓库里的“集成测试”：模板能不能把题目的分值正确地暴露给 query。不带 --in 时它就是一个计算器：typst eval "range(1, 6).map(x => x * x).sum()" 打印 55。

有一条边界我是撞出来的。--in 带来的是那份文档的内省数据（query 能查到东西），不是它的绑定：我在 eval.typ 上调用 plain-text，得到

1
error: unknown variable: plain-text
2
  ┌─ <input-expression>:1:34
3
  │
4
1 │ query(heading).map(h => (h.level, plain-text(h.body)))
5
  │                                   ^^^^^^^^^^

我没有去查 typst eval 对表达式作用域的规定，只记录这次的结果：eval.typ 里没有 import xuan，表达式没有看到 plain-text。内容值被序列化时也不是“文本”：我把 h.body 换成 repr(h.body)，得到 [[1,"[标题一]"],[2,"[标题二]"]]，标题的内容被写成了字符串 "[标题一]"。要做更多处理就在表达式里自己拼，或者像第 7 篇那样把数据放进 metadata。--target html|bundle 也能选（typst eval --help 里列了 paged、html、bundle 三个值），我没有用。

—timings 与 —deps：看编译器在忙什么#

--timings 写出一个 JSON 数组，每个元素有 name、cat、ph、ts、pid、tid、args 这几个字段，是 Chrome 追踪事件的形状（typst compile --help 说这个 JSON 可以载入 https://ui.perfetto.dev 之类的追踪工具，该选项仍是实验性的；我没有试过），extra.sh 里的那一行是：

1
typst compile --root . --ignore-system-fonts --timings out/ch16/timings.json \
2
  examples/notes/main.typ out/ch16/notes-timed.pdf

这份 4 页的笔记一共写出 18842 个事件，开头两个是：

1
$ jq length out/ch16/timings.json
2
18842
3
$ jq -c '.[0:2]' out/ch16/timings.json
4
[{"name":"compile once","cat":"typst","ph":"B","ts":0.0,"pid":1,"tid":1,"args":null},{"name":"compile","cat":"typst","ph":"B","ts":1.112,"pid":1,"tid":1,"args":null}]

ph 是 B（开始）或 E（结束），ts 是时间戳。我写了一个 jq 程序（timing.jq，在 /tmp 里，不在仓库里），把每个名字的最早开始到最晚结束之间的跨度算出来：

1
map(select(.name | test("^(compile|iter \\(.\\))$")))
2
| group_by(.name)[]
3
| "\(.[0].name)\t\(((map(select(.ph == "E").ts) | max) - (map(select(.ph == "B").ts) | min)) / 1000 * 10 | round / 10) ms"

1
$ jq -r -f timing.jq out/ch16/timings.json
2
compile  207.5 ms
3
iter (1)  102.8 ms
4
iter (2)  60.5 ms
5
iter (3)  10.3 ms
6
iter (4)  2.2 ms

这里我把 ts 当作微秒（除以 1000 得到毫秒）。依据是 compile 的跨度 207.5 ms 小于我用 hyperfine -w 2 -r 10 'typst compile --root . --ignore-system-fonts examples/notes/main.typ out.pdf' 量到的整条命令 248.5 ms ± 1.9 ms（进程启动、发现字体和导出也在里面），数量级吻合，但文档里没有写，所以只是合理的猜测。数字本身是确定的：笔记的布局迭代了 4 轮，第一轮 102.8 ms，随后 60.5、10.3、2.2 ms。这正是第 7 篇说的“多遍编译”：每一轮用上一轮的 counter、state、query 结果重新排版，直到结果不再变化。我猜第四轮就是“确认已稳定”的那一遍，所以它最便宜（事件名里确实有 check stabilized）。事件名里还有 call plugin：整份文档调用了一次 Rust 插件（第 15 篇术语表的排序键），也出现在时间线上。开始事件（ph 为 B）数得最多的是 func call（2157 个）、handle text（1837）、realize（837）和 math glyph layout（708）。

四次运行里 compile 的跨度是 207.5、209.6、224.2 和 242 ms（分别在不同的克隆和时间），所以 207.5 ms 不是一个稳定值，只是这一次的读数。

--deps 写出这次编译读取了哪些文件，格式由 --deps-format 选 json（默认）、zero（以 NUL 分隔，能表达任意路径）或 make（输出 Makefile 的依赖行）。extra.sh 对第 12 篇的模块实验这样用：

1
$ cat out/ch16/deps.json
2
{"inputs":["lab/ch12/modules/b.typ","lab/ch12/modules/a.typ","lab/ch12/modules/main.typ"],"outputs":["out/ch16/deps-demo.pdf"]}
3
$ typst compile --root . --ignore-system-fonts --deps - --deps-format make lab/ch12/modules/main.typ /tmp/p16/f/d.pdf
4
/tmp/p16/f/d.pdf: lab/ch12/modules/b.typ lab/ch12/modules/a.typ lab/ch12/modules/main.typ

make 格式正好是一条 Makefile 规则，按 Makefile 的语法可以用 -include 引入它来让 make 跟踪依赖（我没有试过）。笔记示例的依赖要多得多：

1
$ jq ".inputs | length" deps2.json
2
23
3
$ jq -r ".inputs[]" deps2.json | grep -vE "src/|lib.typ"
4
examples/notes/glossary.yaml
5
examples/notes/main.typ
6
examples/notes/refs.bib
7
packages/local/xuan/0.1.0/typst.toml
8
packages/local/xuan/0.1.0/plugin/xuan_pinyin.wasm
9
examples/notes/figs/projection.svg

23 个文件，除了 src/ 下的 xuan 源码，就是笔记的 .typ、YAML 术语表、.bib、SVG 图、包清单，以及那个 .wasm。这个清单是“改了哪些文件需要重编”的准确答案，比我手写的依赖规则可靠。

测试：assert 就是断言框架#

Typst 没有测试框架，也不需要：assert、assert.eq 在编译期求值，失败就是编译错误，typst compile 退出码非零。所以 tests/ 下每个文件就是一份普通的 .typ，对模块的行为写断言，make test 把它们逐个编译成一次性的 PDF：

1
test:
2
  @mkdir -p out/tests
3
  @for f in tests/*.typ; do \
4
    echo "typst compile $$f"; \
5
    typst compile $(TFLAGS) $$f out/tests/$$(basename $$f .typ).pdf || exit 1; \
6
  done

六个文件，共 109 行，一个模块一个文件。tests/units.typ 是最直白的：

1
#import "@local/xuan:0.1.0": *
2

3
#let thin = "\u{2009}"
4

5
// Groups of three from the decimal point outwards, from 5 digits up.
6
#assert.eq(num("1234567.891"), "1" + thin + "234" + thin + "567.891")
7
#assert.eq(num("1234"), "1234")
8
#assert.eq(num("12345"), "12" + thin + "345")
9
#assert.eq(num("0.123456"), "0." + "123" + thin + "456")
10
#assert.eq(num(-1234567), "\u{2212}1" + thin + "234" + thin + "567")
11

12
// Quantities: upright unit, thin space after the number, `^n` superscripts.
13
#assert.eq(plain-text(qty(9.81, "m/s^2")), "9.81" + thin + "m/s2")
14
#assert.eq(
15
  plain-text(qty-range(0, 50, "mm", lang: "zh")),
16
  "0～50" + thin + "mm",
17
)
18
#assert.eq(plain-text(qty-range(0, 50, "mm", lang: "en")), "0–50" + thin + "mm")

num 返回字符串，qty 返回 box，所以测试 qty 要先用第 3 篇的 plain-text 把内容摊平成字符串。这就是我当初把 plain-text 放进 util.typ 的真正原因：它是测试的基础设施。

依赖“编译之后才知道”的行为就要上 context。tests/theorem.typ：

1
#import "@local/xuan:0.1.0": *
2
#show: xuan-base
3

4
= 第一章
5
#theorem[甲] <t1>
6
#lemma[乙] <t2>
7
#proof[略。]
8
#example[丙] <t3>
9

10
= 第二章
11
#theorem[丁] <t4>
12

13
#context {
14
  // One counter is shared by all environments and restarts at each chapter.
15
  let n(l) = counter(figure.where(kind: "xuan-theorem")).at(l).first()
16
  assert.eq((n(<t1>), n(<t2>), n(<t3>), n(<t4>)), (1, 2, 3, 1))
17
  // `proof` is unnumbered.
18
  assert.eq(query(figure.where(kind: "xuan-theorem")).len(), 4)
19
}

文档本身像往常一样排版，最后的 context 块在整个文档排完之后读取计数器在四个标签处的值：定理、引理、例题共用一个计数器，第二章重新从 1 数。proof 不编号，所以 query 只数到 4 个。其余四个文件的主题：util.typ 测 plain-text、ensure-array、pick；homework.typ 测 3 道有分值的题和 1 道无分值的题的总分是 35；slides.typ 测 3 步的页面会产出 5 页（标题页加 3 步加 1 页普通页）；glossary.typ 测码点顺序与拼音顺序不同，它用到仓库里已提交的 .wasm。

测试能不能抓到错误？我临时在 tests/ 里放了一个故意写错的文件（跑完删除，没有提交）：

1
#import "@local/xuan:0.1.0": *
2

3
#assert.eq(num("1234"), "1 234")

1
$ typst compile --root . --ignore-system-fonts tests/bad-units.typ /tmp/p16/f/x.pdf
2
error: equality assertion failed: value "1234" was not equal to "1 234"
3
  ┌─ tests/bad-units.typ:3:1
4
  │
5
3 │ #assert.eq(num("1234"), "1 234")
6
  │  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7
$ echo $?
8
1

失败信息带着两边的值和位置，和任何测试框架的输出一样有用。局限也明显：没有测试名、没有汇总、第一个失败就中止（|| exit 1）。对 6 个文件、0.43 s 的套件，这些都不算问题。“预期会失败”的行为不放在 tests/ 里，由 *.fail.typ 的约定负责：scripts/chapter.sh 要求它们必须失败，退出码 0 反而算错。

typstyle：格式化也是一道门#

仓库里每个 Typst 片段（包括这个系列里贴出来的）都过了 typstyle -l 80。make fmt-check 的文件列表来自一条 find：

1
TYP_FILES = $(shell find . -name '*.typ' -not -path './plugin/*' -not -path './out/*' -not -path './.direnv/*' -not -name '*.fail.typ')
2

3
fmt-check:
4
  typstyle --check -l 80 $(TYP_FILES)

排除了 *.fail.typ：它们本来就有语法错误，我实测 typstyle --check 对 lab/ch01/unclosed.fail.typ 打印 warn: Failed to parse ... The source is erroneous. 并退出 0，也就是它不会让检查失败，只是多一行噪音。我拿一个故意写乱的文件（/tmp 里，不在仓库里）试了 typstyle 的几种用法：

1
#let   greet( name,greeting:"hi" )={
2
 [#greeting, #name!]
3
}
4
#set text(font:("Libertinus Serif","Noto Serif CJK SC"),size:11pt)
5
#greet( "Typst" )

1
$ typstyle --check -l 80 messy.typ
2
Would reformat: messy.typ
3
exit=1
4
$ typstyle --diff -l 80 messy.typ
5
--- messy.typ
6
+++ messy.typ
7
@@ -1,5 +1,5 @@
8
-#let   greet( name,greeting:"hi" )={
9
- [#greeting, #name!]
10
+#let greet(name, greeting: "hi") = {
11
+  [#greeting, #name!]
12
 }
13
-#set text(font:("Libertinus Serif","Noto Serif CJK SC"),size:11pt)
14
-#greet( "Typst" )
15
+#set text(font: ("Libertinus Serif", "Noto Serif CJK SC"), size: 11pt)
16
+#greet("Typst")
17
exit=1
18
$ typstyle -i -l 80 messy2.typ     # 对一份拷贝原地改写
19
exit=0
20
$ typstyle --check -l 80 messy2.typ
21
exit=0

--check 只判断、不动手，不通过退出码为 1；--diff 打印补丁，退出码同样是 1；-i 原地改写，之后 --check 通过。把这个乱文件放进 lab/ch01/ 再跑 make fmt-check，输出 Would reformat: lab/ch01/messy-tmp.typ 和 make: *** [Makefile:45: fmt-check] Error 1（make 自己退出 2），说明 ci 在格式不对时会在编译之前停下。（我放进去又删掉了，没有提交。）

为什么 Makefile 里每次都写 -l 80？因为这是 typstyle 的默认值，写出来是给读者看的：这个系列的代码块宽度限制和博客的 80 列规则一致，不是为了覆盖默认。

tinymist：我验证了什么，没验证什么#

tinymist 是 Typst 的语言服务器。先交代清楚：这一篇里我没有在任何编辑器里交互式地用过它。 这台机器上装了 Helix（hx --version 为 helix 25.07.1），我用 Helix 的体检命令验证接线，再用一个自己写的 LSP 客户端脚本直接驱动 tinymist lsp，核对它对诊断、悬停、格式化请求的回应。实时预览（tinymist preview 或编辑器里的预览面板）、保存即导出、其他编辑器（VS Code、Neovim）的配置，我都没有测试，下面不对它们做任何声明。

先是接线。hx --health typst 在开发 shell 外面和里面的结果不同（每行开头有一个叉或勾的符号，我略去了，叉表示没找到，勾表示找到了）：

1
$ hx --health typst            # 不在 nix develop 里
2
Configured language servers:
3
  tinymist: 'tinymist' not found in $PATH
4
$ nix develop --command hx --health typst
5
Configured language servers:
6
  tinymist: /nix/store/mpdcjcaxcdy8wr9r4j3prmrs3yixs5aj-tinymist-0.15.2/bin/tinymist

（Tree-sitter parser、Highlight queries 两项在两种情况下都是勾，我只贴了语言服务器那一行。）这就是为什么我把 tinymist 放进 flake.nix 的 packages 里：版本和 Typst 一起锁定，在 nix develop 里启动的 Helix 就能找到它。

然后是协议。脚本不在仓库里，核心只有几行 bash：用 coproc 启动 tinymist lsp，按 LSP 的 Content-Length 帧格式收发 JSON：

1
# 节选自 /tmp/p16/lsp.sh（不在仓库里）
2
export LC_ALL=C   # ${#1} 要数字节，不是字符
3
coproc TM { tinymist lsp 2>/tmp/p16/tinymist.err; }
4
send() { printf 'Content-Length: %d\r\n\r\n%s' "${#1}" "$1" >&"${TM[1]}"; }
5
send "$(jq -cn --arg u "file://$ROOT/$1" --rawfile t "$1" \
6
  '{jsonrpc:"2.0",method:"textDocument/didOpen",params:{textDocument:{uri:$u,languageId:"typst",version:1,text:$t}}}')"

initialize 的回应里：

1
{"server":{"name":"tinymist","version":"0.15.2"},"formatting":true,"hover":true}

接着对几份文件发 didOpen，收集它们的诊断。对 lab/ch01/unclosed.fail.typ（第 1 篇的预期失败文件）和一个我写的坏文件 broken-tmp.typ（三行：#let x = 1、#y、#x.foo()，放在克隆里验证完就删了）：

1
[{"line":3,"severity":1,"message":"unclosed delimiter"}]
2
## diagnostics: broken-tmp.typ
3
[{"line":2,"severity":1,"message":"unknown variable: y"}]

severity: 1 是 LSP 里的 Error。第二个文件三行里 tinymist 只返回了一条诊断，也就是第 2 行的未知变量。对 lab/ch04/first-note/main.typ 和 examples/notes/main.typ，它没有发布任何诊断，说明从语言服务器的角度，#import "@local/xuan:0.1.0": * 能解析。

这个“能”是有代价的。我刚开始做这一章时，typst.toml 里写着 compiler = "0.15.1"，同样的两份文件得到：

1
[{"line":1,"severity":1,"message":"package requires Typst 0.15.1 or newer (current version is 0.15.0)"}]

原因在 tinymist --version 里：

1
$ tinymist --version | grep -E 'tinymist|Typst Version'
2
tinymist
3
Typst Version:       0.15.0

nixpkgs 里的 tinymist 0.15.2 内嵌的是 Typst 0.15.0 的编译器，比命令行的 0.15.1 低一个补丁版本。包的 compiler 字段是下限，写 0.15.1 的包在编辑器里被拒绝，编译却在命令行里正常。我把它改成 "0.15.0"（第 4 篇里就是这个值，那里说了原因），在克隆里来回切了两次，每次都用同一个脚本复现：写 0.15.1 报错，写 0.15.0 无诊断，make all 在两种取值下都是 106 个 ok。所以仓库现在的值是 0.15.0，它是“命令行和编辑器都能用”的最大值。

悬停也核对了：对 lab/ch04/first-note/main.typ 里 note.with 的 note（0 起算的第 2 行第 9 列）发 textDocument/hover，返回的是 xuan 里 note 函数的签名，Markdown 代码块的语言标记是 typc（Typst 的代码模式）：

1
let note(
2
  body: any,
3
  abstract: content | none = none,
4
  author: array | type = (),
5
  bibliography: none = none,
6
  ...

（我把它截到前几行，实际回应更长。）这就是 note 的参数列表，从包里的定义直接读出来，开头那句 “Notes and reports.” 来自 note.typ 里的 /// 文档注释。

最后是格式化。我用一个 87 列的单行文件（/tmp 里）试，看 tinymist 的格式化和命令行的 typstyle -l 80 是否一致：

1
#let sum-of-squares(values) = values.map(v => v * v).fold(0, (acc, x) => acc + x) + 100

用默认配置向 tinymist 发 textDocument/formatting，返回的编辑列表是空的 []，也就是它认为不用改。在 initialize 的 initializationOptions 里加 {formatterPrintWidth: 80} 后，同一请求返回：

1
[{"range":[0,30,0,87],"newText":"(\n  values.map(v => v * v).fold(0, (acc, x) => acc + x) + 100\n)"}]

这个编辑和 typstyle -l 80 对同一个文件的输出完全一致：

1
#let sum-of-squares(values) = (
2
  values.map(v => v * v).fold(0, (acc, x) => acc + x) + 100
3
)

所以如果你想让编辑器里的保存格式化和 make fmt-check 不打架，要把 tinymist 的 formatterPrintWidth 设成 80。具体写在哪个编辑器的哪个配置文件里，我没有实测，不写。

模板与安装：typst init 和 make install#

第 4 篇的 typst.toml 里有一节 [template]，指向 template/main.typ，这一篇才把它建出来。packages/local/xuan/0.1.0/template/main.typ，11 行：

1
#import "@local/xuan:0.1.0": *
2

3
#show: note.with(
4
  title: "标题",
5
  author: "作者",
6
  abstract: [一两句话说明这份文档写什么。],
7
)
8

9
= 开始
10

11
在这里写正文，公式写成 $a^2 + b^2 = c^2$。

1
$ typst init @local/xuan:0.1.0 /tmp/xxx
2
Successfully created new project from @local/xuan:0.1.0 ...
3
To start writing, run:
4
> cd /tmp/xxx
5
> typst watch main.typ
6
$ ls /tmp/xxx
7
main.typ
8
$ typst compile --root /tmp/xxx --ignore-system-fonts /tmp/xxx/main.typ /tmp/xxx/main.pdf
9
$ pdfinfo /tmp/xxx/main.pdf | grep -E "Title|Author|Pages"
10
Title:           标题
11
Author:          作者
12
Pages:           1

（成功提示的第一行末尾有一个庆祝用的 emoji，我没有贴。）typst init 只复制 template/ 目录里的内容，所以展开出来的项目里只有 main.typ，它仍然写着 @local/xuan:0.1.0，也就是说 xuan 本身必须在 Typst 找得到的地方。这条命令在我这里成功，是因为 nix develop 设了 TYPST_PACKAGE_PATH=$PWD/packages。

开发 shell 之外怎么办？make install 就一行：

1
install:
2
  mkdir -p ~/.local/share/typst/packages/local && ln -sfn "$(CURDIR)/packages/local/xuan" ~/.local/share/typst/packages/local/xuan

它在用户级的包目录里建一个符号链接，指向仓库里的包。我用一个临时的 HOME（/tmp/p16/home）验证，不碰真实的家目录：

1
$ HOME=/tmp/p16/home make install
2
$ ls -l /tmp/p16/home/.local/share/typst/packages/local/
3
lrwxrwxrwx 1 bfmhno3 users 30 Oct 19 09:15 xuan -> /tmp/lab16/packages/local/xuan
4
$ env -u TYPST_PACKAGE_PATH HOME=/tmp/p16/home typst compile --ignore-system-fonts main.typ main.pdf
5
$ echo $?
6
0
7
$ env -u TYPST_PACKAGE_PATH HOME=/tmp/p16/empty typst compile --ignore-system-fonts main.typ x.pdf
8
error: package not found (searched for @local/xuan:0.1.0)
9
  ┌─ ../p16/proj/main.typ:1:8
10
  │
11
1 │ #import "@local/xuan:0.1.0": *
12
  │         ^^^^^^^^^^^^^^^^^^^

取消 TYPST_PACKAGE_PATH、只靠安装的链接，编译通过；换一个没装过的 HOME，就是第 4 篇讲过的 package not found。用符号链接而不是复制，是因为你改仓库里的 src/*.typ，所有用 @local/xuan 的文档立刻看到改动，不用重新安装。代价是链接指向仓库路径，仓库搬家就断。

CI：同一条命令再跑一遍#

.github/workflows/ci.yml，25 行：

1
name: ci
2

3
on:
4
  push:
5
    branches: [main]
6
  pull_request:
7
    branches: [main]
8
  workflow_dispatch:
9

10
jobs:
11
  build:
12
    runs-on: ubuntu-latest
13
    steps:
14
      - uses: actions/checkout@v7
15
      - uses: cachix/install-nix-action@v31
16
      - run: nix develop --command make ci
17

18
  plugin:
19
    runs-on: ubuntu-latest
20
    steps:
21
      - uses: actions/checkout@v7
22
      - uses: cachix/install-nix-action@v31
23
      - run: >-
24
          nix develop --command bash -c
25
          'cd plugin && cargo fmt --check && cargo clippy --release --target wasm32-unknown-unknown -- -D warnings'

整份工作流的设计原则就一条：CI 里跑的必须是你本地跑的那条命令。 build 任务的 run 就是 nix develop --command make ci，也就是本篇开头那 12.2 秒；nix develop 读 flake.lock，而 flake.lock 把 nixpkgs 锁在 56c02bc00adcf003215cc4bd996d6efaf4cff188，和这个博客仓库的 flake.lock 锁的是同一个提交（我用 jq -r '.nodes.nixpkgs.locked.rev' 对比了两份锁文件）。所以 CI 里的 Typst 是 0.15.1、typstyle 是 0.15.0、字体是同样的 Noto CJK，不会出现“我这里是绿的，CI 里是红的”。Actions 的版本我用 gh api 查了今天的最新发布：actions/checkout 是 v7.0.1，cachix/install-nix-action 是 v31.11.2，工作流里写的是浮动的主版本标签 @v7 和 @v31。

要打个比方的话，CI 每次都给你换一张干净的桌子，重做一遍实验：桌上昨天留下的东西（缓存、你装过但没写进依赖的工具、忘了提交的文件）都不算数。我在 /tmp 里重新克隆，是同一个意思，只是把桌子留在本地。

plugin 任务只检查 Rust 源码的格式和 lint：cargo fmt --check 和 cargo clippy --release --target wasm32-unknown-unknown -- -D warnings。我在本地跑了它们，格式检查无输出（fmt-ok），clippy 的最后三行是 Checking pinyin v0.11.0、Checking xuan-pinyin v0.1.0 和 Finished，用时 0.67 s。注意它没有把 Rust 重新编译成 .wasm 放进包里。

为什么测试用提交进仓库的 .wasm，而不在 CI 里临时编译？我有三个理由，其中第一个是实测的：

1. 编译是可复现的。我在克隆里对已提交的 .wasm 跑 sha256sum，再跑 make plugin（依赖已缓存的机器上用时 3.4 s）重新编译、覆盖，再跑一次：两次都是 280cfb1184870d980cb321dc9fd27048c263440a8ecea10b31b23e329da90d07，git status 干净，字节相同。既然重编出来一样，提交的那份就不是“不知道怎么来的二进制”。
2. 包要能被 typst init 和 make install 的使用者直接用，他们不需要 Rust 工具链。.wasm 是包的一部分，跟 lib.typ 一样要提交。
3. build 任务的职责是验证包的行为，不是验证 Rust 的构建；把后者拆到 plugin 任务里，哪个坏了一眼就知道。

冷缓存的代价也量过一次。第 14 篇的 examples/ecosystem/main.typ 要下载 @preview 包，CI 的每次运行都从空缓存开始。我用一个空的 --package-cache-path 量了：

1
typst compile --root . --ignore-system-fonts --package-cache-path /tmp/p16/cache \
2
  examples/ecosystem/main.typ /tmp/p16/eco.pdf

第一次（冷）25.07 s，第二次（热）0.49 s，缓存目录里留下 cetz、elembic、lilaq、oxifmt、tiptoe、zero 六个包（Touying 用在 touying.typ 里，这条命令没有编译它）。冷启动的耗时取决于当时的网络，第 14 篇量到的是 11.1 s，这次是 25 s，我不会把任何一个当成常数。如果 CI 因此变慢，可以用 actions/cache 缓存这个目录，我没有配置它，12 秒级的 CI 目前不需要。

我没有在这里贴 GitHub 上 Actions 的运行结果，因为我能在本机验证的是工作流所执行的那条命令，而不是 GitHub 的调度。仓库的 Actions 页上有它的真实状态。

索引：Typst 特性 → 第几篇#

这张表按系列开头定下的覆盖清单一行一行列，每一行的每个条目按下面的对应关系出现在那一篇里。

这张表我是对着覆盖清单抄的，抄完后我 grep 了第 1 到 15 篇里的一批关键词（bleed、measure、display(at、conic、package-cache-path 等）确认它们都出现过，但没有逐行逐条重编译；每一行是否真讲到，以各篇里那条命令的输出为准。

验证你手里的树#

这个系列只有一个“权威版本”，就是 tutorial-v1 标签。如果你用 git clone --branch tutorial-v1 拿的仓库，一路上只是跟着改文件，那么到这里，你的工作树应该和标签完全一致。检查它只需要一条命令：

1
git diff tutorial-v1 --stat

它把工作树和标签比较，没有任何改动时什么也不打印。我在 /tmp/lab16（标签的全新克隆，git describe --tags --exact-match HEAD 输出 tutorial-v1）里验证：

1
$ git status --short
2
$ git diff tutorial-v1 --stat
3
$ echo $?
4
0

两条命令都没有输出。再往 util.typ 里追加一行注释：

1
$ echo "// scratch" >> packages/local/xuan/0.1.0/src/util.typ
2
$ git diff tutorial-v1 --stat
3
 packages/local/xuan/0.1.0/src/util.typ | 1 +
4
 1 file changed, 1 insertion(+)
5
$ git checkout -q packages/local/xuan/0.1.0/src/util.typ
6
$ git diff tutorial-v1 --stat
7
$ echo $?
8
0

改动被报告出来，还原之后又没有输出了。有两点要小心：git diff 看不到未跟踪的新文件（你自己新建的文件要看 git status --short），退出码也不会因为有差异而变成非零，它只是打印；要拿它做脚本判断，用 git diff --quiet tutorial-v1。

走到这一步你手里有的东西：一个 70 行的 Makefile 驱动的、16 章实验的小型文档系统，一个能 typst init 的本地包，四类文档（笔记、作业、幻灯片、简历）的 Typst 模板，一个 Rust 写的 235242 字节的插件，6 个测试，和一个只做一件事的 CI。Typst 的导出方向里，HTML 和 bundle 在 0.15.1 里都还挂着“实验性”的警告，这两个我没有用来生产任何东西，只放进 extra.sh 当“金丝雀”：以后 nixpkgs 升级 Typst，make ch16 会第一个告诉我它们的行为有没有变。typst compile --help 里 --features 的取值还列了一个 a11y-extras，我没有试，下一次想让 note 的图和公式过 PDF/UA 的时候我会从它开始。

为什么码点顺序不是拼音顺序#

先把问题钉死。lab/ch15/unicode-sort.typ（源文件）把同样四个词用两种方式排序，一起打印出来。它还依赖本篇后面才写的 pinyin-keys，先看结果：

1
// Codepoint order vs pinyin order for the same four terms.
2
#import "@local/xuan:0.1.0": *
3
#import "../../packages/local/xuan/0.1.0/src/glossary.typ": pinyin-keys
4
#set text(font: fonts.serif, lang: "zh")
5

6
#let words = ("卡尔曼", "奇异值", "矩阵", "最小二乘")
7
#let by-codepoint = words.sorted()
8
#let keys = pinyin-keys(words)
9
#let by-pinyin = words.zip(keys).sorted(key: p => p.at(1)).map(p => p.at(0))
10

11
#table(
12
  columns: 2,
13
  [codepoint], [pinyin],
14
  ..by-codepoint.zip(by-pinyin).flatten(),
15
)
16

17
#repr(by-codepoint) \
18
#repr(by-pinyin) \
19
#repr(keys)
20

21
#assert.eq(by-codepoint, ("卡尔曼", "奇异值", "最小二乘", "矩阵"))
22
#assert.eq(by-pinyin, ("矩阵", "卡尔曼", "奇异值", "最小二乘"))

pdftotext -layout out/ch15/unicode-sort.pdf - 的输出：

1
codepoint pinyin
2
卡尔曼       矩阵
3
奇异值       卡尔曼
4
最小二乘 奇异值
5
矩阵        最小二乘
6

7
("卡尔曼", "奇异值", "最小二乘", "矩阵")
8
("矩阵", "卡尔曼", "奇异值", "最小二乘")
9
(
10
  "ka er man ",
11
  "qi yi zhi ",
12
  "ju zhen ",
13
  "zui xiao er cheng ",
14
)

码点顺序是 卡 < 奇 < 最 < 矩，拼音顺序是 ju < ka < qi < zui。四个词在两种顺序里的位置全部不同：矩阵 从最后一名变成第一名，另外三个各后移一位。CJK 统一表意文字区大致按部首和笔画排列，和读音没有关系，所以只要排序用的是字符串比较，这个问题就不可能靠调参数解决。最后两个 assert.eq 把这个事实固定下来：文件能编译，说明两种顺序就是上面印出来的样子。

排序键是第三个 repr 打印的东西：矩阵 变成 "ju zhen "，每个汉字换成无声调拼音再加一个空格。自己在 Typst 里维护这张字音表太费事（常用字就有几千个），而 Rust 的 pinyin crate 已经带着数据表。缺的只是把它接进 Typst 的办法。

插件协议：字节进，字节出#

办法是 WebAssembly。plugin("x.wasm") 加载一个 .wasm 文件，返回一个 module，模块里每个导出函数变成一个 Typst 函数。把它想成一台只有一个投币口和一个出货口的自动售货机：你从投币口放进去几段字节，它从出货口吐出一段字节，机器内部怎么运转你看不见，机器也看不到外面的任何东西。

协议在 plugin 的文档里有完整规定，我把和这个项目有关的几条挑出来：

• 导出函数接受 n 个 32 位整数（每个参数的长度），返回一个 32 位整数。
• 函数先分配一块长度为各参数长度之和的缓冲区，调用宿主函数 wasm_minimal_protocol_write_args_to_buffer(ptr)，宿主把所有参数依次写进去。
• 干完活之后，调用宿主函数 wasm_minimal_protocol_send_result_to_host(ptr, len) 把结果交回去。
• 返回 0 表示成功；返回 1 表示失败，此时缓冲区里的内容被当作 UTF-8 错误信息。
• 模块只允许从 typst_env 导入上面那两个函数。没有文件、没有网络、没有打印：文档说插件“在隔离中运行”。

我没打算只信文档，写完之后用 Bun 的 WebAssembly.Module.imports 和 .exports 读了一遍编译出来的 .wasm：

1
imports: typst_env.wasm_minimal_protocol_write_args_to_buffer (i32) -> ()
2
         typst_env.wasm_minimal_protocol_send_result_to_host (i32, i32) -> ()
3
exports: memory (20 页)
4
         pinyin_keys (i32) -> i32

（这个检查脚本放在 /tmp/p15-wasm.js，不在仓库里；原始输出是 JSON，我整理成了上面的样子。）导入恰好两个，导出一个函数加一块内存。pinyin_keys 接受一个 i32（唯一一个参数的长度），返回一个 i32（状态码）。这和协议对得上。

这也解释了为什么 Rust 要选 wasm32-unknown-unknown 目标：unknown-unknown 表示没有操作系统也没有 WASI，生成的模块天然不依赖 fd_write 之类的系统调用。很多编译器默认走 WASI，那样产出的模块里有 Typst 不提供的导入，要先用 wasi-stub 处理；这个项目不需要。

手写协议要自己管内存分配和两次宿主调用，很容易写错。wasm-minimal-protocol crate 用一个属性宏把这些都包掉了：#[wasm_func] 标注的函数只需要接受 &[u8] 参数，返回 Vec<u8> 或 Result<Vec<u8>, E>（E 实现 Display 即可）。我读了它在本机 cargo 缓存里的宏源码确认展开结果：Ok 对应状态码 0，Err(e) 把 e.to_string() 作为消息送回宿主并返回 1。

写 Rust 端#

plugin/Cargo.toml（源文件）：

1
[package]
2
name = "xuan-pinyin"
3
version = "0.1.0"
4
edition = "2024"
5
license = "MIT OR Apache-2.0"
6
description = "Typst plugin: pinyin sort keys for Chinese glossary terms"
7

8
[lib]
9
crate-type = ["cdylib"]
10

11
[dependencies]
12
pinyin = { version = "0.11.0", default-features = false, features = ["plain"] }
13
wasm-minimal-protocol = "0.2.1"
14

15
[profile.release]
16
opt-level = "s"
17
lto = true
18
strip = true

三处是有意为之的。crate-type = ["cdylib"] 让 rustc 产出一个没有 Rust 元数据的 C 风格动态库，在 wasm 目标上就是一个可被宿主加载的 .wasm；默认的 rlib 是给别的 Rust 代码链接用的，Typst 用不了。default-features = false, features = ["plain"] 只打开无声调拼音：pinyin 的默认特性还包括声调、数字声调、多音字等几套数据（Cargo.toml 的 [features] 里列着）。我在 /tmp/p15/full 里把这一行改回 pinyin = "0.11.0"（不在仓库里），同样的 profile 下编出来是 495471 字节，是现在 235242 字节的 2.1 倍。opt-level = "s"、lto、strip 是针对体积的常规设置：我猜体积小对编译速度也有一点帮助，但我没有量过，选它们主要是为了仓库里提交的二进制别太大。

plugin/src/lib.rs（源文件），完整的 29 行：

1
use pinyin::ToPinyin;
2
use wasm_minimal_protocol::*;
3

4
initiate_protocol!();
5

6
/// Input: UTF-8 lines. Output: one sort key per line.
7
/// Han characters become toneless pinyin followed by a space,
8
/// every other character is lowercased as-is.
9
#[wasm_func]
10
pub fn pinyin_keys(input: &[u8]) -> Result<Vec<u8>, String> {
11
    let text = std::str::from_utf8(input)
12
        .map_err(|_| "xuan-pinyin: input is not valid UTF-8".to_string())?;
13
    let keys: Vec<String> = text.split('\n').map(line_key).collect();
14
    Ok(keys.join("\n").into_bytes())
15
}
16

17
fn line_key(line: &str) -> String {
18
    let mut key = String::new();
19
    for ch in line.chars() {
20
        match ch.to_pinyin() {
21
            Some(p) => {
22
                key.push_str(p.plain());
23
                key.push(' ');
24
            }
25
            None => key.extend(ch.to_lowercase()),
26
        }
27
    }
28
    key
29
}

几个设计选择值得说清楚。

一次调用处理所有词。 输入是“用换行分隔的多行 UTF-8”，输出是同样行数的键。每次 plugin 函数调用都要过一遍参数序列化，而且是一次宿主到客体的边界穿越；术语表通常几十条，一次打包比循环调用便宜，Typst 端也只产生一条缓存记录。代价是词里不能含换行：pinyin-keys 把词用 \n 拼起来再按 \n 拆开，含换行的词会让键的行数和词的数量对不上。术语不会含换行，所以我没有做防护。

每个汉字后面补一个空格。 为什么不直接拼成 juzhen？因为拼音音节边界会产生歧义。我在 /tmp/p15/poly.typ 里用真实插件算了 ("先", "西安", "西") 的键：

1
"xian "
2
"xi an "
3
"xi "

有空格的时候 西 < 西安 < 先，这是字典里的顺序；没有空格 西安 和 先 的键都是 xian，会并列，由排序的稳定性（输入顺序）决定谁在前。空格比任何字母小，所以它把“音节结束”这个信息编进了字符串比较里。

非汉字原样小写保留。 ch.to_pinyin() 对非汉字返回 None，走 ch.to_lowercase() 分支，Abc矩阵 的键是 abcju zhen （注意 abc 和 ju 之间没有空格：拉丁字母不加分隔，只有汉字加）。tests/glossary.typ 里有一条断言固定了这个行为。

错误是值，不是 panic。 from_utf8 失败就返回 Err(String)，宏把它翻译成状态码 1 加消息，Typst 端于是能原样显示这句话（后面有真实输出）。这个函数里唯一会失败的地方就是输入不是 UTF-8，所以我只需要处理这一条路径。

局限：多音字只取第一个读音。 这个 crate 的 to_pinyin 对每个字只给一个读音。同样在 poly.typ 里我算了 银行，键是 "yin xing "，而在这个词里 行 读 háng。对于术语表，这种错误只影响极少数词的相对位置；如果要处理，应该用 heteronym 特性加上词库，那是另一个项目了。

构建、格式和 lint#

仓库的 Makefile 里有一条 plugin 目标：

1
plugin:
2
  cd plugin && cargo build --release --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/xuan_pinyin.wasm ../packages/local/xuan/0.1.0/plugin/

流程是在 nix develop（Rust 1.97.1，它自带 wasm32-unknown-unknown 的标准库，构建不需要 rustup target add，也没有用到 wasm-ld 或 wasi-stub）里：

1
$ make plugin
2
cd plugin && cargo build --release --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/xuan_pinyin.wasm ../packages/local/xuan/0.1.0/plugin/
3
    Finished `release` profile [optimized] target(s) in 0.23s
4
$ stat -c %s packages/local/xuan/0.1.0/plugin/xuan_pinyin.wasm
5
235242

这是一次增量构建，target/ 已经在了所以只花 0.23 秒。冷构建我在另一个目录里量：CARGO_TARGET_DIR=/tmp/p15-target cargo build --release --target wasm32-unknown-unknown（依赖已经在 cargo 缓存里，不含下载时间）：

1
   Compiling proc-macro2 v1.0.107
2
   Compiling quote v1.0.47
3
   Compiling unicode-ident v1.0.27
4
   Compiling pinyin v0.11.0
5
   Compiling venial v0.5.0
6
   Compiling wasm-minimal-protocol v0.2.1
7
   Compiling xuan-pinyin v0.1.0 (/home/bfmhno3/Projects/typst-lab/plugin)
8
    Finished `release` profile [optimized] target(s) in 3.74s

冷构建 3.74 秒，产物 235242 字节，而且 cmp 把它和仓库里提交的那份比较，输出 same：wasm32-unknown-unknown 的构建在这台机器上是逐字节可复现的。这个事实有实际意义，因为 CI 的 build 任务不重新编译插件，直接用提交进仓库的 .wasm（这样 Typst 的测试不依赖 Rust 工具链），所以我需要知道它没有和源码脱节。235242 字节里大头是拼音表：我另外用一个只有协议、没有 pinyin 依赖的计数器 crate（后文会用到）编了一份，是 15377 字节，相差约 219 KB。

CI 的 plugin 任务只跑格式和 lint，我原样跑一遍（命令和 .github/workflows/ci.yml 里一致）：

1
$ cd plugin && cargo fmt --check && cargo clippy --release --target wasm32-unknown-unknown -- -D warnings

cargo fmt --check 无输出（我的命令里加了 && echo fmt-ok 确认退出码为 0），clippy 输出 Finished 一行，没有任何警告。-D warnings 把警告升级成错误，所以 CI 绿了就意味着一条警告都没有。

在 Typst 里调用它#

先手动调用一次，不经过任何包装。lab/ch15/plugin-basics.typ（源文件）：

1
// Calling the plugin by hand: bytes in, bytes out.
2
#let p = plugin("../../packages/local/xuan/0.1.0/plugin/xuan_pinyin.wasm")
3

4
#let out = p.pinyin_keys(bytes("矩阵\nABC"))
5
#type(out), #out.len() bytes: #repr(str(out))
6

7
// Same input, same output: plugins are pure functions.
8
#assert.eq(out, p.pinyin_keys(bytes("矩阵\nABC")))
9

10
// Errors come back as Typst errors, which `assert` cannot catch,
11
// so we only show the valid path here. See bad-bytes.fail.typ.

输出：

1
bytes, 12 bytes: "ju zhen \nabc"

三个点：返回值的类型是 bytes，要用 str() 才能当字符串用；"ju zhen \nabc" 是 8 + 1 + 3 = 12 字节；bytes(...) 和 str(...) 就是 Typst 一侧的全部“序列化”。

调用约定是严格的。我在 /tmp/p15/ 里试了几种错误用法（都不在仓库里），都是 typst compile --root /tmp/p15 <file>：

1
#let p = plugin("counter.wasm")
2
#p.echo("矩阵")

1
error: expected bytes, found string
2
  ┌─ nostr.typ:2:8
3
  │
4
2 │ #p.echo("矩阵")
5
  │         ^^^^^^

参数必须是 bytes，不会自动转换。其余三种：

1
error: module does not contain `nothing`
2
  ┌─ nofn.typ:2:3
3
  │
4
2 │ #p.nothing(bytes("x"))
5
  │    ^^^^^^^
6

7
error: file not found (searched at /tmp/p15/missing.wasm)
8
  ┌─ nofile.typ:1:16
9
  │
10
1 │ #let p = plugin("missing.wasm")
11
  │                 ^^^^^^^^^^^^^^

第三种是把一个 .typ 文件当 .wasm 加载（plugin("counter.typ")），错误开头是 error: failed to load WebAssembly module (magic header not detected: bad magic number ...，后面跟着期望的 0x0 0x61 0x73 0x6d（即 \0asm）和实际读到的 0x23 0x6c 0x65 0x74（即 #let，源文件的前四个字节）。

这些都是编译期的使用错误。插件函数自己报错是另一回事，lab/ch15/bad-bytes.fail.typ（源文件）故意把两个不可能出现在 UTF-8 里的字节 255, 254 送进去：

1
// Invalid UTF-8 makes the plugin return Err, which aborts compilation.
2
#let p = plugin("../../packages/local/xuan/0.1.0/plugin/xuan_pinyin.wasm")
3
#p.pinyin_keys(bytes((255, 254)))

out/ch15/bad-bytes.stderr：

1
error: plugin errored with: xuan-pinyin: input is not valid UTF-8
2
  ┌─ lab/ch15/bad-bytes.fail.typ:3:1
3
  │
4
3 │ #p.pinyin_keys(bytes((255, 254)))
5
  │  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rust 里写的那句 "xuan-pinyin: input is not valid UTF-8" 原样出现在 Typst 的错误信息里，前面只加了 plugin errored with: 。这就是状态码 1 加错误消息的完整往返。这个错误是编译错误，不是值：assert 抓不住它，没有 try 之类的东西，所以 plugin-basics.typ 末尾的注释说只展示成功路径。（在插件包里把错误消息写成 包名: 原因 的形式，用户读到 Typst 的输出时才知道该找谁。）

纯函数：Typst 会缓存同参数的调用#

文档在 Purity 一节写得很直接：插件函数必须是纯函数，同样的参数必须总是返回同样的值，调用不能对后续调用产生可观察的副作用。原因是 Typst 函数本身是纯的，插件调用继承了这个要求。具体来说，同一个参数调用两次，Typst 可能缓存结果，只真正调用一次；Typst 还可能在多个线程里运行插件的多个实例，实例之间不共享状态。Typst 不检查你是否真的纯（为了效率），违反的后果文档称为不可预测、不可复现。

我不太喜欢只靠文档的措辞，所以写了一个故意不纯的插件来看它到底怎么不可预测。/tmp/p15/counter/src/lib.rs（不在仓库里，cargo fmt --check 通过）：

1
use std::sync::atomic::{AtomicU32, Ordering};
2
use wasm_minimal_protocol::*;
3

4
initiate_protocol!();
5

6
static CALLS: AtomicU32 = AtomicU32::new(0);
7

8
#[wasm_func]
9
pub fn bump(_input: &[u8]) -> Vec<u8> {
10
    let n = CALLS.fetch_add(1, Ordering::Relaxed) + 1;
11
    n.to_string().into_bytes()
12
}
13

14
#[wasm_func]
15
pub fn echo(input: &[u8]) -> Vec<u8> {
16
    input.to_vec()
17
}

bump 每次调用把一个全局计数加一并返回。如果每次调用都真的执行，输入 a, b, a, a 应该得到 1 2 3 4。/tmp/p15/counter.typ：

1
#let p = plugin("counter.wasm")
2
#for w in ("a", "b", "a", "a") [
3
  #str(p.bump(bytes(w))) #h(1em)
4
]
5
\
6
#str(p.echo(bytes("矩阵")))

pdftotext -layout 的输出：

1
1 2   1   1
2
矩阵

是 1 2 1 1。第一个 a 真的执行了，得 1；b 得 2；后面两个 a 的参数和第一次完全相同，Typst 直接返回缓存的 1，计数器没有被碰过。同一份源码，插入或删除一个调用，后面所有数字都会变，这就是“不可复现”。第二个小实验换成 range(3) 循环，每轮先调 bump(bytes("a")) 再调 bump(bytes(str(i)))，输出 12 13 14：a 永远是 1，而每个新参数让计数器前进一步，也印证了缓存的键是“函数加参数字节”。

如果插件确实需要状态（比如昂贵的初始化），官方提供 plugin.transition(func, ..args)：执行一次调用，返回一个新 module，新 module 里的函数能看到这次调用的副作用，原 module 不受影响。/tmp/p15/trans.typ：

1
#let p = plugin("counter.wasm")
2
#let q = plugin.transition(p.bump, bytes("x"))
3
#str(p.bump(bytes("a"))) #str(q.bump(bytes("a"))) #str(q.bump(bytes("b")))

输出 123：p 是原模块，计数器从零开始，p.bump("a") 得 1；q 在 transition 里已经吃掉了一次调用，所以 q.bump("a") 得 2，q.bump("b") 得 3。两个模块各有各的状态。官方文档特别注明：由于内部 WebAssembly 实现的限制，transition 只保证反映插件内存的变化，不保证反映 WebAssembly 全局变量的变化。这个计数器能工作，是因为 Rust 的 static 放在线性内存里，不是 wasm 全局变量（这是我对编译结果的推断，没有反汇编确认；实验结果与之相符）。我在 xuan 里没有用 transition：拼音转换天然是纯函数。

对 pinyin_keys 来说，纯函数意味着：它没有全局状态，输出只取决于输入字节，所以缓存对它只有好处。

xuan 的 glossary.typ#

插件有了，包装它才是 xuan 的工作。src/glossary.typ（源文件）完整的 47 行：

1
// Glossary sorted by pinyin, using the Rust plugin in ../plugin.
2
#import "util.typ": pick
3

4
#let pinyin = plugin("../plugin/xuan_pinyin.wasm")
5

6
/// Sort keys for a list of strings, computed by the WebAssembly plugin.
7
#let pinyin-keys(words) = {
8
  str(pinyin.pinyin_keys(bytes(words.join("\n")))).split("\n")
9
}
10

11
/// Look up the entries registered by `glossary(...)` anywhere in the document.
12
#let entries-of(key) = {
13
  let found = query(<xuan-entries>)
14
  if found.len() == 0 {
15
    panic("xuan: term(" + repr(key) + ") needs a glossary(...) call")
16
  }
17
  let entries = found.first().value
18
  if key not in entries {
19
    panic("xuan: unknown glossary key: " + key)
20
  }
21
  entries
22
}
23

24
/// Print the term and record its use for the glossary.
25
#let term(key) = context {
26
  let entries = entries-of(key)
27
  [#entries.at(key).term#metadata(key)<xuan-term>]
28
}
29

30
/// List the terms used so far, ordered by pinyin.
31
#let glossary(entries, title: auto) = {
32
  [#metadata(entries) <xuan-entries>]
33
  context {
34
    let used = query(<xuan-term>).map(m => m.value).dedup()
35
    let words = used.map(k => entries.at(k).term)
36
    let keys = if words.len() == 0 { () } else { pinyin-keys(words) }
37
    let rows = used.zip(keys).sorted(key: pair => pair.at(1))
38
    let heading-text = pick(title, if text.lang == "zh" { "术语表" } else {
39
      "Glossary"
40
    })
41
    heading(heading-text)
42
    for (k, _) in rows {
43
      let e = entries.at(k)
44
      terms.item(strong(e.term), e.desc)
45
    }
46
  }
47
}

从上往下读，每个选择都有原因。

插件路径相对于这个文件。 plugin("../plugin/xuan_pinyin.wasm") 里的路径和 import 一样是相对于当前源文件解析的（第 12 篇讲过），所以不管用户从哪里 import "@local/xuan:0.1.0"，路径都指向包目录里的 plugin/。.wasm 因此必须随包一起发布：这就是它被提交进 packages/local/xuan/0.1.0/plugin/ 的原因。

pinyin-keys 是对插件的一层薄封装。 它做三件事：拼接、调用、拆分。bytes 和 str 的转换只出现在这一处，包的其余部分只和字符串数组打交道。把它单独导出（lab 和 tests 都直接从 src/glossary.typ 导入它）也方便测试。

term 需要知道词的写法，但调用点在 glossary(...) 之前。 用户这样写文章：先在正文里 #term("lsq")，最后才 #glossary(yaml("glossary.yaml"))。term 只拿到一个键，要渲染出“最小二乘”，必须在这一刻读到词典。解法是 glossary() 开头把整个字典用 [#metadata(entries) <xuan-entries>] 挂在文档里，term 再用 query(<xuan-entries>)（这就是第 7 篇讲的内省）把它查回来。这也是 term 的整个函数体包在 context 里的原因：query 只能在 context 里调用。

两种错误都变成可读的 panic。 键不存在是用户最容易犯的错，所以 entries-of 先检查词典是否存在、再检查键是否在词典里，两处各给一条指名道姓的消息。lab/ch15/bad-key.fail.typ（源文件）：

1
// An unknown key is a hard error with a readable message.
2
#import "@local/xuan:0.1.0": *
3

4
#glossary((a: (term: "矩阵", desc: "数表")))
5

6
#term("matrix")

out/ch15/bad-key.stderr：

1
error: panicked with: xuan: unknown glossary key: matrix
2
   ┌─ @local/xuan:0.1.0/src/glossary.typ:19:4
3
   │
4
19 │     panic("xuan: unknown glossary key: " + key)
5
   │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6

7
  while calling `entries-of` at @local/xuan:0.1.0/src/glossary.typ:26:16
8
    entries-of(key)

另一种是根本没写 glossary(...)。我在 /tmp/p15/nogloss.typ 里只放了一行 #term("a")：

1
error: panicked with: xuan: term("a") needs a glossary(...) call
2
   ┌─ @local/xuan:0.1.0/src/glossary.typ:15:4
3
   │
4
15 │     panic("xuan: term(" + repr(key) + ") needs a glossary(...) call")
5
   │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

没有这个检查的话，第二种情况会掉进 found.first()，得到一个“数组为空”的错误，和用户写的东西毫无关系。

glossary 只列用到过的词，并且去重。 query(<xuan-term>) 按文档顺序返回所有用过的 term 标记，.map(m => m.value).dedup() 取出键并保持首次出现的顺序。lab/ch15/glossary.typ 里 lsq 用了两次，unused 一次也没用，表里只出现一次 lsq，没有 unused。

排序是 zip 加 sorted(key:)。 keys 和 used 等长，used.zip(keys) 得到 (键, 拼音键) 对，sorted(key: pair => pair.at(1)) 按拼音键排。这里不能直接排 used（键是英文标识符），也不能排词（那就是码点顺序），必须把“排序依据”和“要排的东西”绑在一起。words.len() == 0 时跳过插件调用：没有用到任何词，就没有必要往边界那头送一个空缓冲区。

标题用 text.lang 选语言。 heading-text 通过 pick（第 3 篇的 util.typ）处理 title: auto，在 context 里读 text.lang，中文文档是“术语表”，其他语言是 Glossary。显式传 title: 则覆盖。

lab/ch15/glossary.typ（源文件）里有 5 个词条，正文用了其中 3 个（lsq 两次）：

1
// term() marks a use; glossary() lists the used terms in pinyin order.
2
#import "@local/xuan:0.1.0": *
3
#set text(font: fonts.serif, lang: "zh")
4

5
#let entries = (
6
  svd: (term: "奇异值分解", desc: [把矩阵写成 $U Sigma V^T$。]),
7
  lsq: (term: "最小二乘", desc: "使残差范数最小的拟合。"),
8
  rank: (term: "秩", desc: "列空间的维数。"),
9
  kalman: (term: "卡尔曼滤波", desc: "递推的线性最优估计。"),
10
  unused: (term: "伪逆", desc: "这一条没有被引用，不会出现。"),
11
)
12

13
正文先提到 #term("lsq")，再提到 #term("svd") 和 #term("rank")，
14
最后又提到 #term("lsq")，去重后只列一次。
15

16
#glossary(entries)

pdftotext -layout out/ch15/glossary.pdf -：

1
正文先提到 最小二乘，再提到 奇异值分解 和 秩， 最后又提到 最小二乘，去重后只列一次。
2

3
术语表
4
奇异值分解 把矩阵写成 𝑈 Σ𝑉 𝑇 。
5
秩 列空间的维数。
6
最小二乘 使残差范数最小的拟合。

顺序 qi、zhi、zui。desc 可以是字符串也可以是 content，奇异值分解 的说明里有公式，也正常渲染。

lab/ch15/fig-glossary.typ 用四个词渲染了一张图，这次四个词全部用到了：

正文里 最小二乘 排在第一，术语表里它排在最后；矩阵 正文第三，表里第一。

在笔记里用#

examples/notes/glossary.yaml 有 8 个词条，yaml 的结构正好是 glossary(entries) 要的字典：键到 term 和 desc。examples/notes/main.typ 在正文里用了 5 个：

1
#term("lsq")问题的本质是#term("proj")，#term("svd") 把投影、#term("rank")与#term("cond")放进同一个分解。进一步阅读可参考
2
国内教材 @tongji2014 中关于正交化与二次型的章节。
3

4
#glossary(yaml("glossary.yaml"))

这是 main.typ 末尾的一段，不是整个文件。make examples 之后用 pdftotext -layout out/examples/notes.pdf - 看，术语表这一节（笔记共 4 页）依次是：

1
奇异值分解 把任意矩阵写成正交阵、对角阵、正交阵的乘积，对角元是奇异值。
2
条件数 最大与最小非零奇异值之比，衡量解对扰动的敏感程度。
3
正交投影 把向量映到子空间上最近的点，残差与子空间正交。
4
秩 列空间的维数，也等于非零奇异值的个数。
5
最小二乘 使残差平方和最小的近似解法，几何上是向列空间做正交投影。

（第一条在第 3 页末尾，其余四条被分页挤到第 4 页，我只摘了条目，没有抄页脚。）拼音顺序是 qi、tiao、zheng、zhi、zui。同样五个词按码点排序（我在 /tmp/p15/cp.typ 里直接 .sorted() 打印了一下）是：奇异值分解、最小二乘、条件数、正交投影、秩。变化最大的是 最小二乘：码点顺序排第二，拼音顺序排最后。秩 从第五变成第四，条件数 和 正交投影 各提前一位。五个词里只有 奇异值分解 在两种顺序里都排第一，其余四个全部换了位置。

加到 lib.typ#

packages/local/xuan/0.1.0/lib.typ 增加这一篇的一行：

1
#import "src/glossary.typ": glossary, term

lib.typ 仍是中间版本，这一篇只多了上面那一行。验证用 make ch15：

1
ok   lab/ch15/bad-bytes.fail.typ (failed as expected)
2
ok   lab/ch15/bad-key.fail.typ (failed as expected)
3
ok   lab/ch15/fig-glossary.typ
4
ok   lab/ch15/glossary.typ
5
ok   lab/ch15/plugin-basics.typ
6
ok   lab/ch15/unicode-sort.typ

整个 make ch15 在 0.44 秒内跑完（time make ch15，6 个文件，包括两个预期失败的）。插件的 235242 字节不是瓶颈。

什么时候该写插件#

我这个插件做的事情，用一张手写的静态映射表也能做，只不过要自己维护数据。我觉得值得写插件的场景是：算法有成熟的库（排序、哈希、压缩、解析），而 Typst 语言本身又不是为这类计算设计的。反过来，只是想“多一点逻辑”的时候，Typst 自己的函数通常够用，而且不需要提交一个 235 KB 的二进制进仓库。

有两条边界要记住。第一，插件不能读文件、不能联网，输入全靠 Typst 端以字节传进去，所以如果要处理一个数据文件，先在 Typst 里 read(..., encoding: none) 把字节取出来（第 11 篇讲过）再交给插件。第二，.wasm 是二进制，评审者无法审阅它，所以我把 Rust 源码和 Cargo.lock 一并提交，CI 里跑 fmt 与 clippy，并且验证过它可以逐字节复现。

下一篇是最后一篇：怎么把这一切变成可以交付的东西，包括 PDF 标准、HTML 导出、typst eval、--timings、tests、CI 和模板，最后用一张“Typst 特性 → 第几篇”的索引表把整个系列对一遍。

第一次导入：11.1 秒与 52 毫秒#

先看一个最小的例子，lab/ch14/import-preview.typ（源文件）：

1
// `@preview` imports download the package on first use, then hit the cache.
2
#import "@preview/cetz:0.5.2": canvas, draw
3

4
#canvas(length: 1cm, {
5
  draw.circle((0, 0), radius: 0.6, fill: rgb("#cfe0f5"), name: "a")
6
  draw.circle((3, 0), radius: 0.6, fill: rgb("#f5d9cf"), name: "b")
7
  draw.line("a.east", "b.west", mark: (end: ">"))
8
})
9

10
// The version is part of the import: a new release never changes this file.

没有任何 pip install 之类的前置步骤。我把缓存目录指到一个不存在的 /tmp/pc14，让这次编译成为真正的“第一次”：

1
$ rm -rf /tmp/pc14
2
$ time typst compile --root . --ignore-system-fonts --package-cache-path /tmp/pc14 lab/ch14/import-preview.typ /tmp/ip.pdf
3
downloading @preview/cetz:0.5.2
4
downloading @preview/oxifmt:1.0.0
5

6
real  0m8.398s