[Nahuimi]

问题

libimebin（Fcitx5 / libime 二进制拼音词库，容器 version 0x2）导出的 *.dict 与 libime_pinyindict / Fcitx5 写出的同内容文件不字节一致：

• 小词库：一致；
• 大词库（实测 42,998,611 B 文本、1,498,781 条词条）：我们的产物少 13 字节，SHA256 不同。

即「用官方工具转换」和「用本工具转换」得到的词库对不上哈希，需要逐字节复现上游产物的流程无法通过。

原因

libime 的 writeZSTDCompressed() 不是一次普通的 zstd 压缩调用，而是一条 Boost.Iostreams 过滤链：

std::ostream → boost::iostreams::chain(indirect_streambuf, 128B)
             → ZSTDCompressor(symmetric_filter, 4096B 输出缓冲)
             → libzstd（ZSTD_initCStream(level 0) + ZSTD_c_checksumFlag=1）

关闭时 symmetric_filter::close() 会用空输入反复调用 filter(flush=true)，直到 4096B 输出缓冲能排空。如果关闭那一刻 zstd 内部积压的输出超过一个缓冲，循环就要多跑一轮：这一轮的 ZSTD_compressStream 把当前帧的剩余输出写完，紧接着的 ZSTD_endStream 于是新开并立即结束了一个空帧，文件尾部因此多出 13 字节：

28 b5 2f fd | 24 | 00 | 01 00 00 | 99 e9 d8 51
└─ magic ──┘   │    │   └ 末块/raw/长度 0 ┘  └ xxhash64("") 低 32 位 ┘
      帧头描述符 0x24（单段 + 校验和），内容长度 0

关键点：是否出现该空帧取决于数据（取决于关闭时刻 zstd 内部的积压量），不是固定的大小阈值——小词库不会出现，大词库会出现。所以不能简单「在文件末尾补 13 字节」，必须复刻同一套缓冲与 flush 循环。

改动

• 新增 LibimeZstdWriter（src/ImeWlConverter.Formats/LibIMEPinyin/LibimeZstdWriter.cs）：通过 ZstdSharp.Unsafe 直接驱动 libzstd 流式 API，逐字节复刻上面这条链路——128B 外层缓冲、4096B 过滤器缓冲、write/close 的 flush 循环、ZSTD_initCStream(0) + ZSTD_c_checksumFlag=1。
• LibimeDictFormat.Write 改用它替代原来的 CompressionStream 一次性压缩。
• 文件格式与版本号未变（magic 0x000fc613、version 0x2），导入路径不受影响（仍支持 legacy 0x1 未压缩文件）。

验证

新增 3 个单元测试（LibIMEPinyinTest）：

用例	断言
Export_ReproducesUpstreamLibimeBytes	上游 libime 写出的 1352 B 词库读入后原样写出逐字节相同，锁定文件头、zstd 参数与 trie 序列化
Export_LargeDict_EndsWithLibimeTrailingEmptyFrame	压缩主体 > 4096 B 时尾部必须带那 13 字节空帧，且带空帧的文件仍能被完整读回
Export_SmallDict_HasNoTrailingEmptyFrame	小词库不带空帧（与上游一致）

真实词库回归：

CustomPinyinDictionary_Fcitx.txt   42,998,611 B  (1,498,781 条)
  → libimebin                      25,544,344 B
  SHA256 CAC84C5F48E9C47168A46B85D4DDFD8B15F64634DF2DBA5DDFA707F4AB8151A3

该哈希与 libime_pinyindict / Fcitx5 产出的参考文件逐字节相同，且 libimebin → libimebin 幂等。

全量测试：454 用例 / 451 通过 / 3 跳过 / 0 失败；CI 9/9 通过。

本地复现：

dotnet run --project src/ImeWlConverterCmd -- -i libimetxt -o libimebin -O out.dict in.txt
# 与 libime_pinyindict 的产物对比 sha256，或直接跑 LibIMEPinyinTest

兼容性

• 只有导出产物的字节发生变化（补上此前缺失的尾部空帧），格式与版本号未变：旧文件照常读写，新文件仍被 libime / Fcitx5 正常加载。
• 小词库的产物完全不变。
• ZstdSharp.Port 精确锁定 0.8.8：字节一致依赖该移植版 zstd 的输出与上游 libzstd 相同，升级该包属于行为变更，需重跑上述测试并对比真实词库产物。