# 开发历程：把模糊测试补进 MoonBit 的底层

> 2026 MoonBit 黑客松 · 赛道一（新项目方向）· 项目 moonsting
> 这篇文章要回答三个问题：为什么做、关键决策是怎么定的、AI 在其中扮演了什么角色。
> 所有数字都来自本机实测，命令写在对应的段落里。

## 1. 缘起：生态里缺的不是库，是"验证"

开始之前我把 `mooncakes.io` 上能找到的东西过了一遍：TLS 1.3、QUIC、HTTP/3、protobuf、SQLite、Parquet、分析引擎、ORM、Web 框架，一样不缺。**"再写一个库"已经没有位置了。**

缺的是另一层：这些库怎么证明自己是对的。MoonBit 自带的验证手段有三种——`moon test` 的断言、`quickcheck` 的属性测试、`moon prove` 的形式化证明。前两种都需要"你先想到那个用例"，第三种需要能写出规格。中间空着一块：**喂进去一个谁都想不到的输入，看它会不会错。**

这就是我选 fuzz 的原因。它同时命中赛事的两个主题词："让 AI 写得更顺"（AI 生成的解析器需要一道自动门禁）和"让软件经得起检验"（差分、往返、不变性都是可执行的规格）。

## 2. 三条决策线

### 2.1 反馈信号：编译器覆盖率用不了，那就手写插桩

fuzzer 的引擎是覆盖率。我先验证了最省事的路线：

```bash
moon build --target native --enable-coverage   # 构建成功
./cli.exe run --target csv --max-execs 200     # 跑完
# 全仓搜 moonbit_coverage*：零命中
```

MoonBit 的覆盖率是**测试驱动**的特性——只有 `moon test --enable-coverage` 会写 `moonbit_coverage_*.txt`。一个常驻的 fuzz 循环拿不到。

三条路摆着：改编译器加回调（绑定内部 ABI，一个月内不可行）、解析测试产物（拿不到逐次执行的数据）、**手写插桩**。选了第三条，理由是它和 AFL 的 `__afl_manual`、libFuzzer 的用户自定义计数器是同一类做法：target 在分支处调 `@cov.hit(id)`，引擎用"本次执行命中集合的指纹"判新颖性。

指纹用**逐 id 哈希的 XOR**，所以顺序无关。这一点是刻意的：路径本来有序，但同一个分支集合的不同遍历次序会产生几乎无限的"新路径"，语料会被顺序噪声撑爆。第一版指纹是滚动混合，顺序敏感，`csv` 的语料直接冲到 613 条——修好之后是 94 条。**613 那个数字看起来漂亮 6.5 倍，其实是噪声。**

引擎不配置开关、也不需要知道 target 有没有插桩，判据只有一句 `@cov.observed() > 0`：插桩过走指纹，没插桩回退到"输出形状"。所以 `moonx fuzz run` 对任何 target 都能立刻跑起来，插桩与否只是"反馈更准"。

### 2.2 执行模型：逐行落盘，于是二分没有存在价值

最初的方案是"批次进程池 + 崩溃后二分定位"。做完第一版隔离之后发现，**只要子进程每执行一条输入就把结果写一行并 flush**，崩溃时结果文件里有几行，被打死的就是批次里的第几个输入。

二分是更慢地求同一个数字，所以它没有实现。这是整份代码里最省事的一次"不做"：省掉了一整块代码，也省掉了一轮额外的进程启动。

代价写在明处：隔离模式约 2,600 exec/s，进程内约 20 万 exec/s，差 70 倍。所以默认不开，`--isolate` 是"要抓崩溃时才付的钱"。后来加了 `--jobs`，把并行拉回到 8,336 exec/s（`--jobs 8 --batch-size 4096`），并写进文档：**jobs 必须和 batch-size 一起调**，因为每个 worker 启动要 60–200 ms。

### 2.3 持久化：没有 `readdir`，就用编号

语料要能中断续跑。写文件容易，读回来难——MoonBit 的 stdlib 没有 `readdir`。可以绑 Win32 `FindFirstFileA` + POSIX `opendir`（两套平台代码，还要解释 `struct dirent` 布局），但收益只是"能列目录"。

换个问法：**不需要"列出目录"，只需要"知道下一个文件叫什么"**。

```
<dir>/corpus-0001.hex   一个输入，小写 hex，一行
<dir>/corpus-0002.hex
...
```

加载从 1 开始按编号打开，遇到第一个读不到的就停；保存按编号重写。代价是每次加载多一次失败的 `fopen`，收益是零新 FFI、三后端一致。

两个副作用是有意的：**遇缺口截断**（文件布局可以手工修复：删尾巴、留前缀），**写入不收缩**（语料单调增长，fuzzer 不该忘记走过的路）。

## 3. 两次"度量"翻车

这两件事比代码更值得写下来。

**第一次：指标选错。** 结构化变异做完，我跑全量扫描对比前后，语料条数几乎没变（`base64` 仍是 4 个签名），差点判定"没效果"。但语料条数衡量的是"探索到多少条路径"，而结构化变异要证明的是"变异体仍然是合法文档"。换成后者直接测：JSON 种子变异 300 次，297 次仍结构合法。**指标错了会把有效改动判死。**

**第二次：检查器太软。** 同一件事，第一版检查器只数括号和引号配平，于是 `{"a":}` 被算成合法，得出 66%。补上"冒号/逗号后面必须跟值起始"之后，同一份代码只有 46%——**修复之前我其实是 46%，不是 66%**。指标偏软会同时藏 bug 和算错功劳。

修法也不是调参，而是换操作单位：复制以"成员"（`"k":v`）为单位、删除连 key 一起删，46% → 99%。

## 4. AI 在其中做了什么

**AI 擅长的**：把规格翻译成代码（三个编解码 target 的 parse/serialize 对）、机械地补测试向量、把一次调试过程整理成 DEVLOG 条目、找"这个函数还有什么分支没被拒绝"。

**AI 不擅长的**，也正是我花时间最多的地方：**判断一个数字意味着什么**。语料 613 是好事还是噪声？46% 和 66% 哪个是真的？`--jobs 4` 只快 1.2 倍是并行没生效还是批次太小？这些都不是代码问题，是度量问题，只能靠人先想清楚"我要证明什么"。

**校验方式**：每个结论都配一条能重跑的命令；每个"✅"后面都有一次实测（`moon test`、`--cov-report` 的输出、三个后端的 JSONL diff）。DEVLOG 里记了 14 条 AI 犯错的原始记录——`pub enum` 默认只读、`loop` 是关键字、PowerShell 写 BOM 毁掉 `moon.pkg`、`echo 0> file` 被 cmd 当成重定向 handle 0——这些错留在仓库里，不是为了自嘲，是因为它们是"人机协作真实成本"的最好证据。

## 5. 与现有开源工作的取舍

| 来源 | 借鉴 | 放弃 | 为什么 |
|---|---|---|---|
| libFuzzer | 语料即有趣输入、执行数驱动、最小化 | 编译器插桩回调、`LLVMFuzzerTestOneInput` ABI | 需要改编译器 |
| AFL/AFL++ | havoc 算子表、字典、splice、手动插桩 | fork server、共享内存位图 | 无进程 API（后来有了 native，但位图仍需要插桩） |
| atheris | 同进程、按函数签名驱动的易用性 | 字节码插桩 | 同上 |
| Hypothesis | 结构化变异优先于纯字节变异 | 完整 shrink 策略树 | ddmin + 单字节扫描够用 |
| quickcheck（MoonBit 自带） | `Arbitrary` 派生思路 | 只做随机、不留语料 | 这正是缺口 |

## 6. 结果与不足

**结果**：11 个包、6,170 行实现 + 1,145 行测试、104 个测试（native）/ 85 个（wasm-gc）全绿、10 个 target、零依赖。真实 finding 两个：`varint` 的 32 位截断（3 条去重后）、`decimal` 的溢出导致自我拒绝（1 条）。`utf8` 的两个独立实现在 5 万条随机输入上零分歧——那不是"没问题"的证明，但那是可操作的证据。

**不足**（写在 README 里，也写在这里）：

- 插桩是手动的，没有自动插桩；没插桩的 target 只有形状反馈。
- 隔离模式下崩溃用例不做 shrink（缩它要对每个候选起进程）。
- `--cov-report` 的"空洞"是近似的：id 人工分配，"从未命中"可能是没人走到的分支，也可能是从没分配的号段。
- 结构化变异还不覆盖 protobuf/TLV 的字段级改写。

## 7. 如果重来

1. **先验证工具链，再定架构。** 前两周有一次判断失误：以为"没有编译器就没法隔离"，其实只是没装；同样地，`system()` 传中文路径失败被我当成"环境不支持 spawn"。结论：任何"这个平台做不到"的结论，都要先有一个最小复现。
2. **先写度量，再写功能。** 两次翻车都是度量问题。现在每个功能落地时都先想清楚"用什么数字证明它有效"，这个习惯比任何一段代码都值钱。
3. **把"不做"也写进文档。** 不做二分、不做自动插桩、不做字段级变异——每一条都写了理由，而不是留一个看起来能用的假接口。验收时被问到"为什么没有 X"，有理由的"没有"和漏掉的"没有"是两件事。
