# 基准与准确率数据

这份文件回答两个问题，都用可复现的命令和数字回答，而不是形容词：

1. **相对生态里已有的方案，这个库多做了什么？**（评分维度三「生态增量」）
2. **验证是闭环的吗？有没有基准、回归和自动化？**（评分维度四「开发与验证能力」）

两条命令即可复现全部数字：

```sh
moon bench benches --release          # 性能
moon build --target js
python scripts/accuracy_check.py      # 准确率
```

## 运行环境

| 项目 | 值 |
|---|---|
| CPU | Intel Core i7-14650HX（24 逻辑核） |
| 系统 | Windows 11（10.0.26200） |
| Node | v22.22.2 |
| 工具链 | `moon 0.1.20261117` / `moonc v0.10.21+06da1ed44` |
| 后端 | `moon bench` 默认 wasm（`moonrun`），另列 js 作对照 |

绝对耗时随机器变化；这里记录的是**同一台机器上的相对关系**，以及可供他人对比的复现方式。

## 一、性能基准

用例的输入在计时闭包之外构造，`encode` 不计入被测时间。每个用例跑 10 轮，框架自动决定每轮批次大小。

| 用例 | 输入规模 | 均值（wasm） | 吞吐（wasm） | 均值（js） | 吞吐（js） |
|---|---|---:|---:|---:|---:|
| `decode gbk` | 1 068 B | 4.81 µs | 222 MB/s | 8.37 µs | 128 MB/s |
| `detect`（GBK 文本） | 1 068 B | 77.76 µs | 13.7 MB/s | 139.00 µs | 7.7 MB/s |
| `detect`（GBK 文本） | 33 820 B | 2.20 ms | 15.4 MB/s | 4.57 ms | 7.4 MB/s |
| `detect`（UTF-8 文本） | 1 596 B | 156.57 µs | 10.2 MB/s | 282.23 µs | 5.7 MB/s |
| `repair`（乱码文本） | 4 920 B / 2 400 字 | 498.86 µs | 9.9 MB/s | 1.00 ms | 4.9 MB/s |
| `encode gb18030` | 960 B | 4.14 µs | 232 MB/s | 9.14 µs | 105 MB/s |

三点值得说明：

- **`detect` 比 `decode` 慢约 16 倍，这是设计使然**：检测要把 13 种编码各解码一遍，每份结果再算五个信号的分。它不是热路径上的函数，而是一次性判定——一个 1 KiB 的文件 78 µs，一个 32 KiB 的文件 2.2 ms。
- **32 KiB 的耗时是 1 KiB 的 28 倍**（2.20 ms / 77.76 µs ≈ 28.3，输入是 31.7 倍）。低于线性，因为固定开销（候选表、排序）摊薄了；没有隐藏的二次复杂度。
- **js 后端耗时约为 wasm 的 1.8–2.1 倍**，同一份代码在 Node 里也给出同样的判定；慢在 JS 的数值与字符串路径，不影响结果。
- **0.7.1 的三处改动都不改变答案**，只减少重复工作：UTF-16/32 的四次证据扫描合成一次；`text_score` 复用它已经数过的文种计数，不再为 `exclusive_script` 重扫全文；GBK 零错误时 GB18030 直接复用前者的解码与分数（两张表在 GBK 定义处逐槽相同），无 C1 字节时 ISO-8859-1 复用 windows-1252。同一轮测量里，32 KiB 从 3.18 ms 降到 2.20 ms（1.45×）。文件上一版记录的 3.82 ms 与这次的 3.18 ms 是同一版本在不同负载下的差异，所以只拿同一轮的数字做比较。

## 二、准确率基准

### 方法

把已知文本用已知编码器编码，把字节交给 `moonmojibake detect`，数答案对不对。

- 语料 31 条，覆盖简体中文、繁体中文、日文、韩文、西欧文本，每条三种长度（短句 / 一段 / 多段）。
- 编码涉及 `gbk`、`gb18030`、`big5`、`shift_jis`、`euc_jp`、`euc_kr`、`utf-8`、`utf-16-le`、`utf-16-be`、`latin1`、`cp1252`。
- **答案按等价类判定，不按单一标签**：GBK 与 GB18030 对同一段不含四字节的中文产生完全相同的字节，Latin-1 与 windows-1252 对不含 0x80–0x9F 的西文也一样。任何检测器都不可能区分，所以每条用例带一个可接受集合。
- 纯 ASCII 单独计量，不进准确率：它对每一种编码都成立，把它算进分母只会稀释结论。3 条 ASCII 用例全部答 `utf-8`，这是唯一诚实的答案。

### 结果

| | top-1 | top-3 | n |
|---|---:|---:|---:|
| **moonmojibake** | **100.0%** | **100.0%** | 31 |
| 基线：永远答 `gbk` | 12.9% | — | 31 |
| 基线：有 BOM 用 BOM，否则 `gbk` | 12.9% | — | 31 |

分文种：

| 组 | top-1 | n |
|---|---:|---:|
| 简体中文 | 100.0% | 11 |
| 繁体中文 | 100.0% | 4 |
| 日文 | 100.0% | 7 |
| 韩文 | 100.0% | 4 |
| 西欧 | 100.0% | 5 |

另有 2 条被如实报为**平局**（Latin-1 / windows-1252 在纯西文上确实无法区分），置信度 0，接口返回 `ambiguous: true` 与 `tied` 列表。这不算错，也不算对——它是对的答案只有一个：不猜。

### 两个基线为什么合理

「永远答 gbk」不是稻草人：中文语料占多数时，它对中文全对，对日韩和西文全错，正好落在 12.9%（4/31）。生态里现有 MoonBit 检测实现的公开说明就是「GBK 与 Big5 无法区分，双字节文本默认 GBK」，这条基线模拟的正是那个行为。「有 BOM 用 BOM」模拟的是解析器式的嗅探——规格告诉它答案，它从不推断。这两个数字说明的是：**能读懂字节，和能读标签，是两件不同的事。**

## 三、基准驱动的一次修复

第一版跑出 90.3%，3 条漏判全部是**无 BOM 的 UTF-16 中文被判成 latin1**。

原因在检测器自己的保守规则：任何偶数长度的字节流用 UTF-16 都能解出「东西」，所以 UTF-16 必须有 ASCII 证据（半数码元高字节为 0）才拿满分，否则分数减半。这条规则是为西文写的——中文 UTF-16 的高字节在 0x4E–0x9F，永远不为 0，于是正确的读法被腰斩到 40 多分，输给把同一条字节流读成 `bìNbÙö` 的 latin1。

修法不是把阈值调松，而是加一条有护栏的复核：

- 只对 UTF-16 候选生效，且必须同时满足三个条件才恢复满分：
  1. 解码零错误；
  2. 文种字符占比 ≥ 80%（`scripted_share`）；
  3. 满分比**所有 8 位读法**的最高分至少高 20 分。
- 第三条是关键。GBK 字节流用 UTF-16 读也会落进谚文区，看起来同样「像文本」；只有「别的读法都明显更差」才构成证据。

护栏有回归测试钉住：`bomless utf-16 chinese is read as utf-16, not as latin-1` 与 `gbk bytes are not claimed as utf-16 by the same rule`。修复后 75 个单元测试全过、`e2e_check.py` 303/303、`space_check.py` 2 351 159 项全字节空间差分不变，准确率 90.3% → 100%。

这件事本身是「开发与验证闭环」的例子：基准发现了错，错被定位到一条有名字的规则，规则被有护栏地改掉，改完有回归测试守着。

## 四、这些数字不能说明什么

- **语料是自己造的，不是第三方标准集。** 31 条覆盖了主要文种和边界，但不构成统计意义上的抽样；它衡量的是「在这类真实文本上不发生系统性错误」，不能外推为「任意输入 100% 正确」。
- **存在过拟合风险。** 语料与实现出自同一作者，规则可能不自觉地贴合了语料。缓解办法是把语料连同生成方式一起入库（`scripts/accuracy_check.py` 里逐条可见），任何人可以加用例反驳；CI 用 `--min-top1 0.95` 设下限，防止为了提速悄悄牺牲准确率。
- **性能数字来自一台机器。** 换机器绝对值会变，比较的是同一台机器上的量级和后端差异。
- **`detect` 的吞吐不是这个库的卖点。** 8 MB/s 对批量归档够用，对流式解析不够；需要流式时要按块切分，而按块切分会损失上下文，这一点写在 README 的 `Limitations` 里。
