# 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 的实现，但这不是理由，理由是这个协议本身值得一个严肃的实现。

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

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()` 返回中文描述，适合直接给人看。这两个不能互换——日志系统要的是能聚合的字符串，不是一句会变的中文。

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

- **59 个单元测试**，其中 18 个是对抗性的：逐字符截断（每个长度都试一遍）、9 种危险字符在每个位置单字节篡改、十万字符超长输入、200 轮随机垃圾数据、分帧器随机喂字节、缓冲区超限截断。
- **29 条语料用例**：10 条合法、6 条边界（中文数据区、空数据区、最大分包、小写 CRC 等）、11 条非法（每条声明自己该报哪种错）、2 组分包（要求拼成一条完整数据区）。
- **Python 独立对拍**：`corpus/generate.py` 没有复用 MoonBit 的代码，而是用 Python 重写了一遍 CRC16/MODBUS。两边算得不一样，生成阶段就会暴露。
- **`moon check --deny-warn` 零告警**，CI 里也是这个参数，不给自己留"先欠着"的口子。

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

## 八、如果重来

会改三件事：

1. **对抗性测试提前到发布前。**0.1.0 带着 `CP=` 误切的缺陷发布了，虽然几小时内就修掉，但版本号已经花出去了。发布是不可逆动作，应该在它之前把所有"我还能想到什么坏输入"的问题问完。
2. **标准原文第一天就下载下来。**不要先写代码再对标准。先读表 5 和表 9，比写完再改省事得多，也不会产生"看起来对"的错觉。
3. **不要让 AI 生成任何可以被查证的事实。**命令码、编码、版本号、示例值——这些必须来自原文。AI 可以帮我整理格式、写描述、列测试场景，但不能替我确认"2041 是什么"。

## 九、结语

这个库现在能做的事：把一条原始报文摊成一张带解释的字段表，把一段 TCP 流切成完整的帧，把结构化的数据重新编码成规范报文，并且对每一条非法输入给出具体的拒绝理由。

它的价值不在于"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)
