一句话: 协议文档是 Excel和代码有大量不一致。用脚本解析 xlsx 逐条核对改了 5 轮——重排表格把改过的值覆盖回旧值、示例帧照抄别的命令、脚本自己也有 bug。教训改完一份要整体通读一次单一事实源要以代码为准。适合谁读维护协议文档、用工具核对文档和代码的嵌入式工程师。背景一份 5 轮才对齐的协议文档协议文档是 Excel 表格协议版本 V2.2和代码有大量不一致单位对不上、命令号对不上、布局对不上。于是用脚本解析 xlsx共享字符串 工作表 XML逐条核对改文档 → 重新解析 → 发现问题 → 再改。整整 5 轮。每一轮都有我以为改完了又发现新的。三个典型问题1. 重排表格把改过的值覆盖回旧值第一轮把 cmd 5/13 的示例从错误值改成正确值第二轮通读时发现又变回旧值了——不是没保存是编辑表格时拖动重排行把已改的单元格覆盖了回去。这类问题最坑改过的内容悄悄丢失且没有任何报错。逐条改逐条查根本防不住只有改完从头到尾通读一遍能看到。2. 示例帧照抄了别的命令cmd 23写日期的示例整帧直接照抄了 cmd 22读日期的返回帧——帧头都是错的一个是请求帧头一个是应答帧头。抄是人的本能但协议文档里每一帧都要逐字节核对帧头、长度、命令、数据、校验一个都不能靠差不多。3. 字段名和布局矛盾cmd 26 的字段名是四个输出通道但布局表格里对应的是温度设定列——名字和位置对不上。最后统一成一种。文档字段名和布局不一致代码按布局实现、人按字段名读——两边都以为自己没错。还有一个隐藏问题解析工具自身的 bug第 4 轮核对时脚本把 M 列显示成了 L 列——解析脚本自己错了导致误报一堆不一致。改文档前先验证工具用已知正确的单元格索引核对解析结果。三个教训教训做法改完一份 → 一次完整通读重排覆盖、照抄错误这类问题只有整体通读能发现示例帧逐字节核对帧头/长度/命令/数据/校验不能差不多工具先验证再用解析结果和已知正确值对照再下结论单一事实源以代码为准5 轮拉锯的根源是文档和代码谁是对的没定论。最后定死以代码为准文档跟进。代码是跑在设备上的事实文档是给人看的描述。描述和事实冲突时改描述——但要让文档描述跟上事实而不是反过来为了文档改代码。实测对比逐条改逐条查重排把改过的值覆盖回旧值5轮才对齐 | 改完一次通读重排覆盖一眼看到2轮对齐有用的话点个收藏下次调试直接用。有问题欢迎评论区交流看到了都会回。下一篇一次全量测试排掉三个bug嵌入式调试的三条方法论——分层排查、边界测试、测试清单驱动