# mbt-hj212 开发历程

> 这篇不是功能介绍（那在 `README.md`），是写给评审看的：这个库为什么是这个样子，中间错了哪些地方，AI 用在哪儿、又在哪儿帮了倒忙。

## 一、选题：从"没人做过"到"值得做"

这个项目之前，我申报过另一个选题：用 MoonBit 实现 Unicode 换行算法（UAX #14）。理由是"MoonBit 生态里没人做过文本换行"。初审驳回了，理由是生态里已有 `unicode-segmentation`、`bidi`、`moonlayout`，所谓空白不成立。

收到驳回时我第一反应是"它们做的不是同一件事"——`unicode-segmentation` 做的是字素簇与词边界，UAX #14 做的是行断点，确实是不同算法。但冷静下来看，这个辩解没有意义：**在一个已经有三四个文本处理库的生态里，再加一个"文本的某种切分"，对使用者来说边际价值很低。**审查的判断是对的。

真正的问题在我用的标准上。"有没有人做过"是个坏标准，因为它把"空白"当成了"价值"。换个问法才有答案：

1. 有没有一个**外部标准**可以作为对错的依据？（不是我自己定义什么叫"实现正确"）
2. 有没有**真实的使用者**？（不是我为练手而写）
3. 难点是落在**判断**上，还是落在**打字**上？（AI 能代劳的部分没有多少价值）

HJ 212 三条都占。它是生态环境部的强制性行业标准，全国每一台联网的数采仪都在按它报送数据；标准正文写清了每条规则，所以"实现得对不对"有客观答案；而它的难点恰恰不在写代码，在于**读懂标准里没写明白的地方**。

于是换了方向。这次没有再说"生态空白"——MoonBit 生态里确实没有 HJ 212 的实现，但这不是理由，理由是这个协议本身值得一个严肃的实现。

## 二、第二次驳回：交付单薄，是因为只做了前半段

0.1.2 发布后又被驳回了：

> 选题非常窄，局限于环保监测设备的 HJ 212 报文接入，交付集中在编解码、分帧与重组。生态价值和复用性价值不足，建议更换应用场景更广的选题方向。

这次没法说审查看错了。交付清单确实就是编解码、分帧、重组——一条报文解开之后呢？使用者拿到的还是一堆字符串，接下来这几件事还得自己写：

- `N`（无有效数据）到底存 `null` 还是 `0`；
- 浓度超出量程的这条数据，算不算数、要不要拦；
- 怎么塞进 InfluxDB、怎么导出给 Excel。

而这三件事，每一个接入 HJ 212 的人都要各自写一遍，并且前两件多数人会写错——把缺失当 0 存进库，是我在现场数据里见过最多的一个错。**那才是真正重复的劳动，而它跟环保没有关系。**

想过换选题。但把 mooncakes 上 3807 个模块拉下来数了一遍：`cli` 有 191 个、`json` 111 个、`http` 95 个、`markdown` 54 个、`framing` 5 个、`toml` 20 个、`logging` 15 个。想找一个"够通用又没人做"的方向，基本不存在；硬找一个通用的题目，会原样撞回第一次那条"生态里已经有更好的实现"。

所以没换领域，改的是交付的深度：**把协议之后那一段补齐，并且补成跟协议无关的。**

```
HJ 212 帧 ──to_point──┐
                      ├─ Point ─ 规则引擎 ─ JSON / NDJSON / CSV / InfluxDB
别的协议 ──自定义函数──┘
```

四个新模块都不认识 HJ 212：

| 模块 | 内容 | 离开 HJ 212 还能用吗 |
| --- | --- | --- |
| `record.mbt` | `Point` / `Field` / `Value` / `Quality` | 能，任何时序采集 |
| `quality.mbt` | 量程 / 必填 / 类型 / 白名单规则 + 文本配置 | 能，任何"这个数可信吗"的判断 |
| `sink.mbt` | 四种输出格式，手写转义 | 能，任何交给下游的场景 |
| `pipeline.mbt` | 全链路串起来，附计数 | 能，抓包回放、离线批处理、在线流 |

`Frame::to_point()` 是唯一的适配点。换协议时只需要再写一个这样的函数。

要说清楚一点：**这次扩展没有发明任何新概念。** Point、规则引擎、Sink 都是时序数据处理里的常识。它的价值不在于概念新，而在于这些概念在这条链路上被真正接通了——一段 TCP 字节流进去，一行 InfluxDB line protocol 出来，中间每一次降级（缺失、可疑、拒收）都有记录，并且每一处都有测试盯着。

补的过程中也踩了两个具体的坑，都记在这儿：

一是**类型判断的位置**。最初的写法是先看字段名里有没有 `-Flag`、`Info` 这类后缀，再决定当文本还是当数值。这等于把行业字典编进了通用层——换个场景就不成立。改成只看值本身：能解析成数字就是 `Num`，空串就是 `Missing`，其余原样 `Text`。`a34013-Flag=N` 因此留成文本 `"N"`，而不会被误当成"没有数据"。

二是**给新类型加 `Eq` 时撞上语言的语法迁移**。测试里想写 `assert_eq(point.quality, Suspect)`，编译不过——自定义 enum 不 `derive` 就没有 `Eq`。加上 `derive(Eq, Debug)` 之后，本机 `--deny-warn` 又报 `implicit_impl_as_method`，要求显式写 `pub extend Quality with Eq::{not_equal, equal}`。加完本机全绿，推上去 CI 却红了。

红的原因是 CI 每次都装最新工具链，而它把 `} derive(Eq, Debug)` 判为 `deprecated_syntax`——`--deny-warn` 下弃用即失败。它建议的新写法是 `#derive(...)` 属性，可当前稳定版根本不认识这个属性，直接报 `unknown attribute`。**两条语法互斥，没有交集。**

最后的解法是最笨的那个：都不用了。给四个枚举各手写一份 `impl Eq`，`pub extend` 留着（旧编译器要它消告警），测试里的 `assert_eq` 改成 `assert_true(a == b)`。多写二十行，换来新旧两条工具链都能在 `--deny-warn` 下编译。

这件事值得记下来，因为它暴露了一个容易被忽略的成本：**依赖最新工具链的 CI，会让"昨天还能过"的代码今天变红，而原因和代码本身无关。**排查过程也不体面——Actions 的日志要仓库权限才能下载，最后是在 CI 里加了一步把编译器输出打成 annotation，才在提交页面上看到那行 `deprecated_syntax`。诊断代码留在了工作流里，下次再遇到同类问题能省半小时。

## 三、这个协议难在哪：三处静默失败

HJ 212 的报文长这样：

```
##0140QN=...;ST=31;CN=2011;PW=123456;MN=...;Flag=5;CP=&&DataTime=...;a34013-Rtd=1.52&&3647\r\n
└┬─┘└──┘└──────────────────── 数据段 ────────────────────┘└──┘└─┘
包头 长度                                                 CRC  包尾
```

语法简单到半小时能写出一个能跑的解码器。但这个协议有三处地方，**写错了不会报错，只会静默丢数据**：

**第一，长度字段是 UTF-8 字节数，不是字符数。**

数据区里出现一个中文，比如 `Info=备用通道`，按字符数算就少 6 个字节。接收端拿着这个长度去切 CRC，位置就错了，整帧被丢弃。而发送端一切正常，日志里没有任何异常——数据就这么没了。

这个坑的隐蔽之处在于：纯 ASCII 测试数据永远碰不到它。必须构造带中文的用例。

**第二，`CP` 的取值自己也用 `;` 分隔字段。**

数据段是 `QN=...;ST=...;...;CP=&&a=1;b=2&&`。看起来按 `;` 切开再找 `CP` 就行了，但 `CP` 的值内部也用 `;`——切完 `CP=&&a=1` 和 `b=2&&` 就成了两个字段，数据区被撕碎。

正确做法是先定位 `CP=` 的位置，之前的按 `;` 切，之后的整体交给数据区解析。这个"先定位再切"的顺序，标准里没有明说，是从报文结构推出来的。

**第三，TCP 是字节流，粘包半包是常态。**

一次 `read` 可能拿到两条半报文，也可能只有 `##01` 四个字节。分帧器必须跨 `read` 保持状态，而不能假设"一次读到的就是一条完整报文"。

这三条我都在 `README.md` 里写成了带解释的段落，而不是一句"注意长度是字节数"。因为它们不是 API 细节，是**这个协议本身的性质**——使用者不知道这三条，用这个库也会用错。

## 四、AI 用在哪，又错在哪

这个项目全程用 AI 辅助。但用下来的结论是：**AI 在"生成"上很强，在"确认"上不可靠。**

### 它帮了大忙的地方

- 样板代码：`DecodeError` 的 13 个变体、每个的 `message()` 中文描述、`kind()` 的稳定标识，这些是纯搬运，人工写容易漏、容易拼错。
- 测试用例的枚举：我说"帮我想想一个帧解析器会被哪些输入搞崩"，它列出了截断、单字节篡改、超长字段、空输入、重复包头、非法 UTF-8 几类。这个清单我自己想不全。
- 文档初稿：`README.md` 的结构、CLI 用法示例的排版，先让它铺一版再改，比从空白页开始快。
- MoonBit 语法细节：`println` 没有对应的 `print`、标签参数用 `chars="..."` 而不是 `chars: "..."`、`catch` 不能跟在 `match Ok(...)` 后面只能跟在 `try {}` 后面——这些编译器会直接报错，问一下就省了翻文档。

### 它帮了倒忙的地方，而且很危险

命令码表和系统编码表，我最初是让 AI 直接生成的。它给出的表看起来非常合理，24 条命令、编码、方向、说明一应俱全。直到我拿标准正文逐条对照，发现三处错误：

| 命令码 | AI 给的 | 标准表 9 原文 |
| --- | --- | --- |
| `2041` | 上传日数据 | 设备运行时间日历史数据 |
| `9011` | 心跳 | 请求应答 |
| `1000` | 设置访问密码 | 设置超时时间及重发次数 |

系统编码表也一样：`ST=32` 被标成"烟气"，实际是"地表水体环境污染源"（水质），烟气是 `ST=31`。

这三处错误有一个共同点：**它们都是现场的口头叫法，不是标准原文。** `9011` 在现场确实常被叫作"心跳包"，因为它就是周期性发一次、维持连接；`32` 被联想成烟气，可能是因为排放口编号的习惯。

这才是 AI 出错最危险的方式——不是胡编一个不存在的命令码（那种错误一眼能看出来），而是给出一个**符合直觉、业内也确实这么叫、但和标准不一致**的答案。这种错误能顺利通过所有人的"看起来对"检查。

后来还踩了一次同类坑：`Flag` 的版本位 `000010`，我一开始写成 `HJ 212-2023`。查了才发现是 **HJ 212-2025**。同样是"记忆里有个模糊的印象，填了个看起来最像的年份"。

所以定了一条规矩，贯穿后面所有工作：

> **凡是能查到原文的，必须以原文为准。AI 的记忆只能用来缩小查找范围，不能用来下结论。**

这条规矩的代价是要真的去读标准 PDF，一页一页翻表 5 和表 9。但这三处错误如果不改，这个库发出去就是错的——而且错得很体面，没人会发现。

## 五、被自己的测试打脸的三次

### 第一次：语料自检抓出两个静默缺陷

我把测试语料做成了**文件**（`corpus/good/*.frame`、`corpus/bad/*.frame`），而不是代码里的字符串常量。文件名约定是 `错误类型__说明.frame`，比如 `BadCrc__校验码错.frame`。

这样 `moon run cmd/verify` 就能做一件字符串常量做不到的事：**断言"这一帧必须报这个特定的错"**。

第一次跑，26 条里过了 24 条。挂的两条都是真 bug：

- `DuplicateField__MN 重复.frame` 被静默接受了。我的字段解析是"后出现的覆盖先出现的"，所以重复的 `MN` 不报错，直接用了后一个。但重复的核心字段意味着报文有问题，应该拒绝。
- `BadDataArea__CP 缺 && 包装.frame` 被当成合法数据区。标准 6.3.2 规定 `CP` 的值是 `&&数据区&&`，我原来的解析器对没有 `&&` 的输入也能"容错"解析出来。这种容错是有害的——对方用的根本不是 HJ 212 的数据区格式，猜出来的结果只会误导人。

这两条都不是我预想到的。这就是"语料做成文件 + 断言特定错误"的价值：它把"我以为它会报错"变成了可执行的东西。

### 第二次：`CP=` 出现在别的字段值里

0.1.0 已经发布之后，我在补对抗性测试。写到一个场景时停下来问自己：**如果 `CP=` 这三个字符出现在别的字段的值里呢？**

构造了一个：`Note=XCP=Y`。结果合法帧被误判成 `BadDataArea`。

根因是定位 `CP` 用的是 `indexOf("CP=")`——它找到了 `XCP=` 里那个 `CP=`，从那里切下去，字段就从中间断开了。

修复方式是把"位置"改成"边界"：

```moonbit
fn find_cp_field(cs : Array[Char]) -> Int {
  let mut i = 0
  while i + 3 <= cs.length() {
    let at_boundary = i == 0 || cs[i - 1] == ';'
    if at_boundary && cs[i] == 'C' && cs[i + 1] == 'P' && cs[i + 2] == '=' {
      return i
    }
    i = i + 1
  }
  -1
}
```

`CP` 必须处在一个字段的起点（0 号位，或紧跟 `;`），否则不算。

这个 bug 在真实场景里会不会出现？会。`Info=` 是标准的备注字段，里面写一段运维说明，恰好含 `CP=` 不是不可能。而一旦出现，**合法报文会被整条丢弃**。

教训很直接：**0.1.0 发布得太早了。**对抗性测试应该在发布前做，而不是发布后补。所以有了 0.1.1。

### 第三次：标准自己的示例算不出来

这条不是 bug，是一次必须做的判断。

HJ 212-2017 附录 A 有一个示例报文，数据段是 `QN=20160801085857223;ST=32;CN=2011;...;CP=&&RtdInterval=30&&`，标注的校验码是 `1C80`。

我按附录 A 自己给出的算法——初值 `0xFFFF`、反向多项式 `0xA001`、无最终异或——算同一段数据，得到 `0759`。

差了。于是穷举：初值换 `0x0000`，多项式换 `0x8005`，正向反向都试，加不加最终异或都试，数据段取不取 `##`、取不取长度字段、取不取 `\r\n`，各种组合都跑了一遍。**没有任何一种组合能得到 `0x1C80`。**

结论：示例大概率沿用了旧稿（很可能是 2005 版没跟着更新）。

这里有个很容易走错的分岔：可以让测试变绿——把 `1C80` 当成正确答案写进断言，或者写个特例"如果数据段等于这个就返回 1C80"。测试立刻全过。

但那样这个库就没法用了。所有真实设备都是按算法算的，不是按附录示例算的。**测试的目的是能互通，不是变绿。**

所以选择相信算法，并把这个分歧写成一条测试：断言算出来是 `0759`，同时断言它不等于 `1C80`。分歧本身成了文档的一部分——写在 `README.md` 的"已知偏差"里，谁用这个库都会先看到。

## 六、向已有工作学什么，不学什么

**学边界。** MoonBit 生态里的 `unicode-segmentation` 只做分段，不碰排版；`moonlayout` 才做排版。这种"一个库只解决一个问题"的分法是值得学的。所以 `mbt-hj212` 只做协议：帧、数据区、命令码、分帧。监测因子的编码表（附录 B，水/气各数百项）**故意不收**——那是查表数据，不是协议逻辑，塞进来只会让包变大、更新变频繁。因子名在库里是不透明字符串，`DataArea::get("a34013-Rtd")` 照样能用。

**不抄实现。** Rust、Java、Go 生态里都有 HJ 212 的实现。我看过它们的 API 形状——`Frame` / `Segment` / `DataArea` 这样的分层是合理的，就采用了类似的结构。但解析逻辑没有抄，全部按标准正文重新实现。

理由不是洁癖。别人的实现里可能有对标准的误读（前面那三处命令码错误，在很多实现里也存在），抄过来就等于把别人的 bug 一起继承，而且因为"大家都这么写"而永远不会被发现。标准正文是唯一权威，读它虽然慢，但读一遍就有底气。

**零依赖是刻意的。**核心库不 import 任何外部模块。协议库会被放到网关、边缘设备、服务端各种环境里，依赖越少越好。HJ 212 需要的能力——字节操作、字符查找、整数格式化——标准库都有。`moonbitlang/x` 只被 `cmd/main` 和 `cmd/verify` 这两个可执行包用来读文件、取退出码，库本身完全干净。

## 七、一个影响 API 形状的决定

开发中最重要的一次取舍：**结构错误和语义问题必须分开。**

- `Frame::decode` 只管结构——包头、长度、CRC、包尾。任何一项不对，拒绝整帧，绝不"尽力而为"地猜。
- `Segment::validate` 只管语义——`MN` 长度和版本不匹配、`Flag` 声明了分包却没带 `PNUM`/`PNO`。这些只作为提示返回，不影响解码。

为什么不能合并？因为调用方的需求不一样。网关要的是"这帧坏了就丢掉，别耽误下一条"；数据中心要的是"这帧能收，但内容可疑，记下来人工核"。

如果 `decode` 把所有问题都当成错误返回，数据中心就没法处理"能收但可疑"的帧；如果都当成警告，网关就没法快速丢弃坏帧。混在一起的 API 一定有一方用不了。

分开之后，`DecodeError` 还是给了两个出口：`kind()` 返回稳定标识（`"BadCrc"`、`"Truncated"`），适合写日志、做分支；`message()` 返回中文描述，适合直接给人看。这两个不能互换——日志系统要的是能聚合的字符串，不是一句会变的中文。

## 八、测试最后长成什么样

- **97 个单元测试**，其中 18 个是对抗性的：逐字符截断（每个长度都试一遍）、9 种危险字符在每个位置单字节篡改、十万字符超长输入、200 轮随机垃圾数据、分帧器随机喂字节、缓冲区超限截断。另外 38 个覆盖新增的数据模型、规则引擎、四种导出格式与管道。
- **32 条语料用例**：10 条合法、6 条边界（中文数据区、空数据区、最大分包、小写 CRC 等）、11 条非法（每条声明自己该报哪种错）、2 组分包（要求拼成一条完整数据区）、1 段混合流（正常帧 + 坏帧 + 分包 + 噪声，核对全链路计数）、2 条规则配置检查（语法零错误、对已知问题必须命中）。
- **Python 独立对拍**：`corpus/generate.py` 没有复用 MoonBit 的代码，而是用 Python 重写了一遍 CRC16/MODBUS。两边算得不一样，生成阶段就会暴露。
- **`moon check --deny-warn` 零告警**，CI 里也是这个参数，不给自己留"先欠着"的口子。

这些数字本身说明不了什么。真正说明问题的是：**它们抓出过三个真 bug**（重复字段静默接受、缺 `&&` 包装被当合法、`CP=` 误切）。一个从没失败过的测试套件，大概率是因为它测的东西太温和。

## 九、如果重来

会改四件事：

1. **先想清楚交付的边界，再动手写。**两次驳回指向的是同一个问题：我一直在优化"解一条报文解得多准"，而使用者真正卡住的地方在解完之后。判断"这件事做完谁会用、他拿到手还要自己写什么"，应该发生在写第一行代码之前。
2. **对抗性测试提前到发布前。**0.1.0 带着 `CP=` 误切的缺陷发布了，虽然几小时内就修掉，但版本号已经花出去了。发布是不可逆动作，应该在它之前把所有"我还能想到什么坏输入"的问题问完。
3. **标准原文第一天就下载下来。**不要先写代码再对标准。先读表 5 和表 9，比写完再改省事得多，也不会产生"看起来对"的错觉。
4. **不要让 AI 生成任何可以被查证的事实。**命令码、编码、版本号、示例值——这些必须来自原文。AI 可以帮我整理格式、写描述、列测试场景，但不能替我确认"2041 是什么"。

## 十、结语

这个库现在能做的事：一段 TCP 字节流进去，一行能直接写进 InfluxDB 或 CSV 的记录出来；中间的每一次降级——缺失、可疑、拒收——都有记录、有原因；对每一条非法输入给出具体的拒绝理由。

其中只有最前面一段跟 HJ 212 有关。数据模型、规则引擎、四种导出格式、整条管道，换一个采集协议照样能用。

它的价值不在于"MoonBit 里终于有 HJ 212 了"——那只是个事实，不是理由。价值在于：**它把三处会静默丢数据的地方，写成了会被失败的断言；又把解完之后那一段没人愿意重写一遍的活，写成了可以复用的库。**

至于 AI 在这个项目里扮演的角色，最准确的说法是：它是个很快的助手，但它说的每句话都需要有人去核对。而"去核对"这件事，恰恰是这个项目里唯一不能外包的部分。

## 链接

- 仓库：https://github.com/Mr-Houjie/mbt-hj212
- mooncakes：https://mooncakes.io/docs/Mr-Houjie/mbt-hj212
- 申报书：[`PROJECT_PROPOSAL.md`](PROJECT_PROPOSAL.md)
