凌晨两点多我在会议室里对着手机念一段 node_id念到第三遍的时候嗓子已经哑了。电话那头是客户现场的同事他需要这段 ID 去日志里 grep但偏偏这段 ID 是 Base64里面又是/又是大小写混排隔着一条质量一般的话路l和1、O和0根本说不清。那天晚上我就在笔记本上新建了一个文件夹名字叫 t3code——当时只是当成用三个 T 打头的编码工具来写Token、Trace、Transfer没想到后来会认真做完还真的在团队里用了起来。这种场景听着很边缘但只要你做过后端系统、写过日志中间件、或者陪着客户排查过环境问题大概率都经历过同款尴尬。t3code 的定位很明确把任意字节串变成一段人读起来友好、机器解回来准确、错一个字符能定位到块的短文本。它不是什么商业产品也不是要取代 Base64它只是补上了一个长期没人管的空档——机器和机器之间不缺编码人和人之间缺。这篇文章是我从需求梳理、码表设计、编码器实现到踩坑、压测、固化成 CLI 的完整过程记录适合那些写日志系统、做设备配置导入导出、或者经常需要远程协作传短参数的开发者参考。1. 项目起源一次不算罕见的人肉传参事故1.1 那晚到底发生了什么当时我们定位一个节点间握手超时的问题所有日志都在客户内网我只能通过语音把一小段关键参数传给同事。那段参数长这样{ node_id: M7xP2a9r/KQ }就这么一小段对方把M听成N把/当成7把KQ当成候选来回确认了三次半小时全耗在你再说一遍上。问题最终当然查出来了但效率低得离谱。其实这类场景在运维里特别普遍机器之间传输数据从来不缺编码方案但从一个人嘴里传到另一个人耳朵里这件事没有编码方案来管。Base64 为了把任意字节变成 ASCII引入了、/、读起来难受语音、OCR、手抄都是灾难hex 倒是没有特殊字符但一长串连续字符没有任何结构错一个字母你根本不知道错在哪Base58 解决了易混字符问题却又没有校验抄错一个字符整段报废依然只能全量重来。1.2 这个问题为什么值得做一个工具有人可能觉得这是不是有点小题大做再发一次截图不就解决了。但站在工程角度人肉传递短参数是高频发生的动作远程协助时给对方念个 node_id、设备现场没有网络时靠 U 盘或短信传配置文件、监控大屏上需要人眼对比两个字符串是不是一致。任何一个环节出现一次误读排查成本就是分钟级起步。更关键的是现有编码方案在设计时根本没把人类放在链路里。Base64 的目标是让字节能在邮件正文里走一趟hex 的目标是让比特可打印Base58 的目标是让钱包地址可复制。它们都没有回答一个问题当传输信道的质量非常差、只能靠人眼和人嘴来校验时怎么让错误提前被发现、准确定位而不是等到解码那一瞬间才崩溃t3code 就是从这个问题出发的。我给这个工具定了三条设计底线第一时间写进文档任何两个输出字符在视觉和发音上都不能含糊小写为主彻底避开l/1、o/0、i/j这类常规混淆组输出必须天然分段每一段都带独立校验抄错一个字符解码时能立刻报出第几段错实现不引入任何第三方依赖一个源文件就能在 Linux、macOS、Windows 终端跑。1.3 t3code 能做什么不能做什么t3code 做的事情非常窄输入任意字节串输出一串带版本前缀、带分隔符、带块级校验的短文本。反过来输入这串文本解码得到原始字节并且逐块验证完整性。它不追求高压缩率不追求最强的纠错能力也不替代 TLS 或者应用层协议里的编码。它的价值在于把机器可解析的字符串翻译成人类也能安全传递的字符串。在我实测过的场景里它的语音传参错误率比 Base64 低得多手抄时可以按块确认OCR 识别后也能立刻知道哪个字符读错了。如果你也在做类似的事情下面这些设计过程、代码骨架和踩坑记录可以直接拿走。2. 编码设计的三次推翻从去掉易混字符到块级可校验2.1 第一版Base58 加个尾巴校验好抄但改不动最直觉的做法是在 Base58 的基础上加校验。Base58 已经把0/O、1/I/l这些明显容易混淆的字符去掉了输出还都是大小写字母和数字看起来挺安全。我给整段文本末尾追加两个字符的校验位用 CRC16 算完再 Base58 编码。结果第一次实际使用就发现问题整段只有一个校验位发生在末尾。如果对方在中间某个字符念错了解码端只会冷冰冰地提示checksum mismatch。问题是谁也不知道这个 mismatch 是哪个字符引起的。你是从第一个字符开始重新念还是让对方把整段重新抄一遍有过一次这样的经历后我意识到有校验和能定位错误是两回事。校验值的位置决定了它的纠错能力而位置必须跟着人的操作习惯走不是跟着比特流走。2.2 第二版64 字符表在语音面前碰壁当时我贪心想做一张 64 字符表每个符号恰好 6 bit密度更高。为了凑够 64 个视觉可区分的符号我把大小写字母加数字全摆上桌逐个排除l和I排除1排除O排除0排除Z/z和2在部分字体里太像排除5和S/s排除6和b、9和q/g在草书和手写里也容易混排除。排到最后发现真正能满足视觉可区分的符号只剩三十来个。硬凑到 64 个就得把q、x、z、w这类发音不友好、口型容易含糊的字符拉回来补位。结果就是输出确实短了但读起来一团乱麻比如q3w9xRzT这种隔着电话念一遍想死的心都有。这一版给了我一个重要的教训字符集设计不能只看屏幕上的字形还要看嘴巴里的音位和手写时的笔画。64 符号方案看似技术优雅却牺牲了 t3code 最核心的价值——人可以直接参与传递。于是我放弃 64 字符表回到 32 字符表。2.3 定稿32 字符表 4 字节数据块 1 字节校验32 字符表意味着每个符号 5 bit。为了对齐字节边界我做了这样一个块结构设计原始数据按 4 字节切块每块末尾附加 1 字节 Fletcher-8 校验合成 5 字节后用自定义 Base32 码表编码成 8 个字符块与块之间用-分隔。为什么是 4 字节而不是 2 字节或者 8 字节后面单独说。先说这个结构解决了什么每一块 8 个字符恰好是人眼一次能扫完的信息量也适合语音里按段确认每一块独立校验错一块不会影响其他块而且因为 Base32 码表里根本没有-分隔符永远不会和数据字符冲突解码时安全系数很高。我选用 Fletcher-8 而不是 CRC8理由很实际Fletcher-8 只需要两个累加器代码实现不到十行对它来说最常见的使用场景就是防手误误码检测能力足够CRC8 需要多项式表或者位运算对这样一个小工具来说有点过度设计。2.4 块大小的选择算出来的不是拍出来的块太大校验冗余少但定位粒度粗人一错就要重传一大段块太小定位细但冗余高输出碎成一片。我拿 32 到 256 字节的典型报文做了模拟对比错误重传成本。先说冗余率数据块大小校验字节数冗余率错误定位粒度2 字节133%2 字节4 字节120%4 字节8 字节111%8 字节16 字节16%16 字节再看实际场景。t3code 的典型负载是 node_id、配置片段、短 token长度集中在 8 到 32 字节之间。如果数据块取 2 字节一个 16 字节的负载会拆成 8 块语音传参时第几段都得数半天重传一块的人力成本反而更高。如果取 16 字节整段只有一两个块错一个字符基本等于全段重来校验优势形同虚设。最终定在 4 字节是重传成本曲线上比较平衡的点。对于更长负载我会把多个块再包一层头部长度字段而不是简单放大块尺寸。3. 从零实现一个最小可用的 t3code3.1 核心代码不到 100 行的编解码器t3code 的实现核心其实很薄难的是设计。下面这个 Python 版本是我最初的原型去掉边界处理大概不到 100 行。import sys # 实际发布时码表由脚本按禁用字符表生成并固定顺序不要手动改 ALPHABET_T3 abcdefghijkmnpqrstuvwxyz23456789 def fletcher8(data: bytes) - bytes: sum1 sum2 0 for b in data: sum1 (sum1 b) % 255 sum2 (sum2 sum1) % 255 return bytes([(sum1 sum2) % 255]) def base32_5bytes(chunk: bytes) - str: num int.from_bytes(chunk, big) return .join( ALPHABET_T3[(num (35 - 5 * i)) 0x1F] for i in range(8) ) def base32_decode_8chars(part: str) - bytes: num 0 for ch in part: num (num 5) | ALPHABET_T3.index(ch) return num.to_bytes(5, big) def encode(raw: bytes) - str: # 头部两字节记录原始长度解决末尾补零歧义 raw_len len(raw) raw raw_len.to_bytes(2, big) raw raw b\x00 * ((4 - len(raw) % 4) % 4) blocks [] for i in range(0, len(raw), 4): payload raw[i:i4] blocks.append(base32_5bytes(payload fletcher8(payload))) return t3c-v1: -.join(blocks)解码就反着来先去掉t3c-v1:前缀按-切块逐块 Base32 还原成 5 字节取前 4 字节验 Fletcher-8校验不过就直接报块号。def decode(text: str) - bytes: text text.strip().removeprefix(t3c-v1:) if not text: raise ValueError(empty input) body bytearray() for idx, part in enumerate(text.split(-)): if len(part) ! 8: raise ValueError(fblock {idx1} length invalid: {part}) chunk base32_decode_8chars(part) payload, check chunk[:4], chunk[4] if fletcher8(payload)[0] ! check: raise ValueError(f[ERR] block {idx1} checksum mismatch) body.extend(payload) raw_len int.from_bytes(body[:2], big) return bytes(body[2:2 raw_len])这段代码的价值在于错误定位逻辑非常直白。如果第 3 块校验失败ValueError会直接告诉你block 3而不是整个解码失败。3.2 CLI 长什么样CLI 我给两个子命令e和d。e支持传字符串或者文件路径d支持从文件读取也支持直接粘贴文本。运行效果如下$ t3code e hello t3code t3c-v1: d4mb8kv2-fq63z7at-wp9xq2dr-e5hn6cpt $ t3code d t3c-v1: d4mb8kv2-fq63z7at-wp9xq2dr-e5hn6cpt hello t3code输出里的t3c-v1:是版本前缀。一开始我嫌它多余后来发现没有它旧数据和新数据在码表升级后根本无法区分加上前缀以后以后想换码表、想支持多版本并行解码都容易得多。3.3 错误定位演示改一个字符只坏一个块这是 t3code 和 Base64 最核心的体验差异。故意把上面输出里的第 3 段改一个字符$ t3code d t3c-v1: d4mb8kv2-fq63z7at-wx9xq2dr-e5hn6cpt [ERR] block 3 checksum mismatch此时前两块已经正常还原第三块单独失败。这意味着什么如果是两个人分工抄写抄错第 3 块的人只需要把那 8 个字符重念一遍其他人不用跟着重新核对。如果是语音传参说一句第三段再说一次就行而不是把整串从头再来。4. 实测中确认没白做的三个场景4.1 远程语音传参念起来终于不像在报密码这套方案最初就是为语音传参设计的。现在我会把输出分成一段一段念d4mb8kv2、fq63z7at、wp9xq2dr、e5hn6cpt每一段 8 字符念起来是三个小节有明确的节奏感。对方抄下来以后解码端会立刻告诉他对不对并且指出错在第几段。实测下来之前用 Base64 传参数需要来回确认三五次现在基本一到两次就能过。这里还有个小技巧如果对方一次性抄了多块解码时即使最后一块校验失败前面成功的块也会留在输出缓冲区里。CLI 加一个--partial参数后失败时也会把已通过校验的块打印出来配合报错信息能让人很快定位是第几段的问题。4.2 日志里的短身份码一眼扫过去就能核对日志系统里经常要打 node_id、request_id、session_id。直接打 UUID 太长打 hex 太枯燥打 Base64 又没法肉眼比对。我用 t3code 把这些 ID 统一编码成短文本打印在关键日志里。实际效果是在日志聚合界面里看两条记录是否属于同一次请求不需要逐字符比对只看分段处就行。比如t3c-v1: d4mb8kv2-fq63z7at-...和t3c-v1: d4mb8kv2-fx63z7at-...第二段开头变了一眼就能发现有串号风险。人眼的模式识别能力在这种分段结构下远比读一长串连续字符强。4.3 窄带/离线数据传输每个块都能单独校验有一次在一个没有内网、只有短信信道的现场我们需要把一段设备参数从总部传到现场。用 t3code 编码后把文本按块拆成几条短信发送现场收到后逐段粘贴进 CLI哪一段在通信过程中被运营商改坏了解码器会准确报出块号只需要让总部重发那一块。同样的逻辑也适用于拍照 OCR打印出来的 t3code 标签被手机拍完识别后如果某个数字被 OCR 认错块校验会立刻报错不会默默解码出一堆错误数据。这类场景的共同特征是信道不可控且人工参与程度高。t3code 的块级校验 分隔符结构让错误定位从整体崩溃变成了局部重传。5. 踩坑、压测与边界修正那些文档里不会写的细节5.1 版本前缀和头部长度没有人给你设计兜底第一个坑就是补零歧义。原始数据长度如果不是 4 的倍数编码前必须补零但补零之后解码端不知道最后补了几个零直接恢复会多出字节。我最早偷懒没管直到第一次拿它编码一个 13 字节的配置项解出来多出 3 个\x00才回去老老实实加了两字节长度头。长度头放在编码前的字节流开头占 2 字节。为什么不是 4 字节因为 t3code 主要服务的是短参数64 KB 对绝大多数使用场景足够。如果你要拿它做文件级备份应该把长度头升级成独立区块而不是简单扩成 4 字节。版本前缀t3c-v1:也是后来补的。它不参与编码算法只承担协议身份作用。现在即使我换了码表旧文本依然能靠前缀路由到旧解码器。5.2 码表不能只讲不混淆还要过一遍字体码表看起来是纯粹的技术选择但实际卡在最麻烦的地方不同操作系统的等宽字体对某些字符的渲染差异巨大。5在 JetBrains Mono 里和S很像在思源等宽里又没那么像6和b在部分点阵字体里几乎就是镜像关系。我最后做了一个很笨但有效的动作把候选字符用大号字体打印成 A3 图纸贴在工位上让团队目测投票凡是隔着三米看会犹豫的字符全部剔除。同时码表一旦确定就写死当作协议的一部分。谁也不能因为看着顺眼去调整码表顺序因为那会直接让所有历史数据失效。5.3 性能取舍比 Base64 慢一半但值得t3code 用 32 字符表每个符号 5 bit输出密度天然低于 Base64。在我笔记本上纯 Python 实现大概 110 MB/sBase64 标准库大概 200 MB/s。编码长度上Base64 是每 3 字节变 4 字符t3code 是每 4 字节数据加 1 字节校验再变 8 字符约等于每字节 2 字符比 Base64 长 50%和 hex 相当。这个代价完全可接受。因为 t3code 的使用场景本来就不是高吞吐信道的首选而是低速率、高人工参与的信道。在那种信道里真正的时间成本从来不是 CPU 编解码的几十毫秒而是人念错一段、重来一遍的好几分钟。做个直观对比方案特殊字符块级校验错误定位语音/手抄友好度Base64有/无无差hex无无无中Base58较少无无中t3code无每 8 字符一块可定位到块好5.4 还剩下的几个坑一是文本传输协议里的换行符。如果 t3code 文本经过邮件、短信或代码剪贴板\r\n和\n的差异会破坏块结构。我在 CLI 里统一做strip()但如果你把它嵌入到别的协议里一定要明确约定不做自动换行。二是大小写敏感性。t3code 的码表固定使用小写解码端遇到大写时会报错而不是自动转换。这不是偷懒是为了防止语音传参时不确定是大写还是小写这种模糊状态。大写就错错了好重来而不是怀着应该没问题的心跳过校验。三是多块边界的分组策略。如果一次编码输出几十块人眼和语音都很难快速定位第 17 段。后来我加了个建议性的分组规则输出超过 6 块时在 CLI 里分组展示比如块之间用空行或缩进区分但网络传输时仍然按标准格式输出。维护 t3code 半年下来我最大的体会是编码输出是一种与人的接口。Base64 这类方案把接口友好性完全扔给了机器一旦链路中插入一个不完美的人类所有问题都会在那个点放大。t3code 的设计并不复杂复杂的是意识到人会犯错这件事应该被设计进协议里。如果你也经常被这种小问题困扰建议从这套块校验思路开始先解决错误能不能被看见再解决错误能不能被定位这比追求一步到位的编码密度要实在得多。 
长河君 · 2026/10/26 23:34:12 · 阅读 1.2k t3code：为语音传参与日志核对设计的容错编码工具
凌晨两点多我在会议室里对着手机念一段 node_id念到第三遍的时候嗓子已经哑了。电话那头是客户现场的同事他需要这段 ID 去日志里 grep但偏偏这段 ID 是 Base64里面又是/又是大小写混排隔着一条质量一般的话路l和1、O和0根本说不清。那天晚上我就在笔记本上新建了一个文件夹名字叫 t3code——当时只是当成用三个 T 打头的编码工具来写Token、Trace、Transfer没想到后来会认真做完还真的在团队里用了起来。这种场景听着很边缘但只要你做过后端系统、写过日志中间件、或者陪着客户排查过环境问题大概率都经历过同款尴尬。t3code 的定位很明确把任意字节串变成一段人读起来友好、机器解回来准确、错一个字符能定位到块的短文本。它不是什么商业产品也不是要取代 Base64它只是补上了一个长期没人管的空档——机器和机器之间不缺编码人和人之间缺。这篇文章是我从需求梳理、码表设计、编码器实现到踩坑、压测、固化成 CLI 的完整过程记录适合那些写日志系统、做设备配置导入导出、或者经常需要远程协作传短参数的开发者参考。1. 项目起源一次不算罕见的人肉传参事故1.1 那晚到底发生了什么当时我们定位一个节点间握手超时的问题所有日志都在客户内网我只能通过语音把一小段关键参数传给同事。那段参数长这样{ node_id: M7xP2a9r/KQ }就这么一小段对方把M听成N把/当成7把KQ当成候选来回确认了三次半小时全耗在你再说一遍上。问题最终当然查出来了但效率低得离谱。其实这类场景在运维里特别普遍机器之间传输数据从来不缺编码方案但从一个人嘴里传到另一个人耳朵里这件事没有编码方案来管。Base64 为了把任意字节变成 ASCII引入了、/、读起来难受语音、OCR、手抄都是灾难hex 倒是没有特殊字符但一长串连续字符没有任何结构错一个字母你根本不知道错在哪Base58 解决了易混字符问题却又没有校验抄错一个字符整段报废依然只能全量重来。1.2 这个问题为什么值得做一个工具有人可能觉得这是不是有点小题大做再发一次截图不就解决了。但站在工程角度人肉传递短参数是高频发生的动作远程协助时给对方念个 node_id、设备现场没有网络时靠 U 盘或短信传配置文件、监控大屏上需要人眼对比两个字符串是不是一致。任何一个环节出现一次误读排查成本就是分钟级起步。更关键的是现有编码方案在设计时根本没把人类放在链路里。Base64 的目标是让字节能在邮件正文里走一趟hex 的目标是让比特可打印Base58 的目标是让钱包地址可复制。它们都没有回答一个问题当传输信道的质量非常差、只能靠人眼和人嘴来校验时怎么让错误提前被发现、准确定位而不是等到解码那一瞬间才崩溃t3code 就是从这个问题出发的。我给这个工具定了三条设计底线第一时间写进文档任何两个输出字符在视觉和发音上都不能含糊小写为主彻底避开l/1、o/0、i/j这类常规混淆组输出必须天然分段每一段都带独立校验抄错一个字符解码时能立刻报出第几段错实现不引入任何第三方依赖一个源文件就能在 Linux、macOS、Windows 终端跑。1.3 t3code 能做什么不能做什么t3code 做的事情非常窄输入任意字节串输出一串带版本前缀、带分隔符、带块级校验的短文本。反过来输入这串文本解码得到原始字节并且逐块验证完整性。它不追求高压缩率不追求最强的纠错能力也不替代 TLS 或者应用层协议里的编码。它的价值在于把机器可解析的字符串翻译成人类也能安全传递的字符串。在我实测过的场景里它的语音传参错误率比 Base64 低得多手抄时可以按块确认OCR 识别后也能立刻知道哪个字符读错了。如果你也在做类似的事情下面这些设计过程、代码骨架和踩坑记录可以直接拿走。2. 编码设计的三次推翻从去掉易混字符到块级可校验2.1 第一版Base58 加个尾巴校验好抄但改不动最直觉的做法是在 Base58 的基础上加校验。Base58 已经把0/O、1/I/l这些明显容易混淆的字符去掉了输出还都是大小写字母和数字看起来挺安全。我给整段文本末尾追加两个字符的校验位用 CRC16 算完再 Base58 编码。结果第一次实际使用就发现问题整段只有一个校验位发生在末尾。如果对方在中间某个字符念错了解码端只会冷冰冰地提示checksum mismatch。问题是谁也不知道这个 mismatch 是哪个字符引起的。你是从第一个字符开始重新念还是让对方把整段重新抄一遍有过一次这样的经历后我意识到有校验和能定位错误是两回事。校验值的位置决定了它的纠错能力而位置必须跟着人的操作习惯走不是跟着比特流走。2.2 第二版64 字符表在语音面前碰壁当时我贪心想做一张 64 字符表每个符号恰好 6 bit密度更高。为了凑够 64 个视觉可区分的符号我把大小写字母加数字全摆上桌逐个排除l和I排除1排除O排除0排除Z/z和2在部分字体里太像排除5和S/s排除6和b、9和q/g在草书和手写里也容易混排除。排到最后发现真正能满足视觉可区分的符号只剩三十来个。硬凑到 64 个就得把q、x、z、w这类发音不友好、口型容易含糊的字符拉回来补位。结果就是输出确实短了但读起来一团乱麻比如q3w9xRzT这种隔着电话念一遍想死的心都有。这一版给了我一个重要的教训字符集设计不能只看屏幕上的字形还要看嘴巴里的音位和手写时的笔画。64 符号方案看似技术优雅却牺牲了 t3code 最核心的价值——人可以直接参与传递。于是我放弃 64 字符表回到 32 字符表。2.3 定稿32 字符表 4 字节数据块 1 字节校验32 字符表意味着每个符号 5 bit。为了对齐字节边界我做了这样一个块结构设计原始数据按 4 字节切块每块末尾附加 1 字节 Fletcher-8 校验合成 5 字节后用自定义 Base32 码表编码成 8 个字符块与块之间用-分隔。为什么是 4 字节而不是 2 字节或者 8 字节后面单独说。先说这个结构解决了什么每一块 8 个字符恰好是人眼一次能扫完的信息量也适合语音里按段确认每一块独立校验错一块不会影响其他块而且因为 Base32 码表里根本没有-分隔符永远不会和数据字符冲突解码时安全系数很高。我选用 Fletcher-8 而不是 CRC8理由很实际Fletcher-8 只需要两个累加器代码实现不到十行对它来说最常见的使用场景就是防手误误码检测能力足够CRC8 需要多项式表或者位运算对这样一个小工具来说有点过度设计。2.4 块大小的选择算出来的不是拍出来的块太大校验冗余少但定位粒度粗人一错就要重传一大段块太小定位细但冗余高输出碎成一片。我拿 32 到 256 字节的典型报文做了模拟对比错误重传成本。先说冗余率数据块大小校验字节数冗余率错误定位粒度2 字节133%2 字节4 字节120%4 字节8 字节111%8 字节16 字节16%16 字节再看实际场景。t3code 的典型负载是 node_id、配置片段、短 token长度集中在 8 到 32 字节之间。如果数据块取 2 字节一个 16 字节的负载会拆成 8 块语音传参时第几段都得数半天重传一块的人力成本反而更高。如果取 16 字节整段只有一两个块错一个字符基本等于全段重来校验优势形同虚设。最终定在 4 字节是重传成本曲线上比较平衡的点。对于更长负载我会把多个块再包一层头部长度字段而不是简单放大块尺寸。3. 从零实现一个最小可用的 t3code3.1 核心代码不到 100 行的编解码器t3code 的实现核心其实很薄难的是设计。下面这个 Python 版本是我最初的原型去掉边界处理大概不到 100 行。import sys # 实际发布时码表由脚本按禁用字符表生成并固定顺序不要手动改 ALPHABET_T3 abcdefghijkmnpqrstuvwxyz23456789 def fletcher8(data: bytes) - bytes: sum1 sum2 0 for b in data: sum1 (sum1 b) % 255 sum2 (sum2 sum1) % 255 return bytes([(sum1 sum2) % 255]) def base32_5bytes(chunk: bytes) - str: num int.from_bytes(chunk, big) return .join( ALPHABET_T3[(num (35 - 5 * i)) 0x1F] for i in range(8) ) def base32_decode_8chars(part: str) - bytes: num 0 for ch in part: num (num 5) | ALPHABET_T3.index(ch) return num.to_bytes(5, big) def encode(raw: bytes) - str: # 头部两字节记录原始长度解决末尾补零歧义 raw_len len(raw) raw raw_len.to_bytes(2, big) raw raw b\x00 * ((4 - len(raw) % 4) % 4) blocks [] for i in range(0, len(raw), 4): payload raw[i:i4] blocks.append(base32_5bytes(payload fletcher8(payload))) return t3c-v1: -.join(blocks)解码就反着来先去掉t3c-v1:前缀按-切块逐块 Base32 还原成 5 字节取前 4 字节验 Fletcher-8校验不过就直接报块号。def decode(text: str) - bytes: text text.strip().removeprefix(t3c-v1:) if not text: raise ValueError(empty input) body bytearray() for idx, part in enumerate(text.split(-)): if len(part) ! 8: raise ValueError(fblock {idx1} length invalid: {part}) chunk base32_decode_8chars(part) payload, check chunk[:4], chunk[4] if fletcher8(payload)[0] ! check: raise ValueError(f[ERR] block {idx1} checksum mismatch) body.extend(payload) raw_len int.from_bytes(body[:2], big) return bytes(body[2:2 raw_len])这段代码的价值在于错误定位逻辑非常直白。如果第 3 块校验失败ValueError会直接告诉你block 3而不是整个解码失败。3.2 CLI 长什么样CLI 我给两个子命令e和d。e支持传字符串或者文件路径d支持从文件读取也支持直接粘贴文本。运行效果如下$ t3code e hello t3code t3c-v1: d4mb8kv2-fq63z7at-wp9xq2dr-e5hn6cpt $ t3code d t3c-v1: d4mb8kv2-fq63z7at-wp9xq2dr-e5hn6cpt hello t3code输出里的t3c-v1:是版本前缀。一开始我嫌它多余后来发现没有它旧数据和新数据在码表升级后根本无法区分加上前缀以后以后想换码表、想支持多版本并行解码都容易得多。3.3 错误定位演示改一个字符只坏一个块这是 t3code 和 Base64 最核心的体验差异。故意把上面输出里的第 3 段改一个字符$ t3code d t3c-v1: d4mb8kv2-fq63z7at-wx9xq2dr-e5hn6cpt [ERR] block 3 checksum mismatch此时前两块已经正常还原第三块单独失败。这意味着什么如果是两个人分工抄写抄错第 3 块的人只需要把那 8 个字符重念一遍其他人不用跟着重新核对。如果是语音传参说一句第三段再说一次就行而不是把整串从头再来。4. 实测中确认没白做的三个场景4.1 远程语音传参念起来终于不像在报密码这套方案最初就是为语音传参设计的。现在我会把输出分成一段一段念d4mb8kv2、fq63z7at、wp9xq2dr、e5hn6cpt每一段 8 字符念起来是三个小节有明确的节奏感。对方抄下来以后解码端会立刻告诉他对不对并且指出错在第几段。实测下来之前用 Base64 传参数需要来回确认三五次现在基本一到两次就能过。这里还有个小技巧如果对方一次性抄了多块解码时即使最后一块校验失败前面成功的块也会留在输出缓冲区里。CLI 加一个--partial参数后失败时也会把已通过校验的块打印出来配合报错信息能让人很快定位是第几段的问题。4.2 日志里的短身份码一眼扫过去就能核对日志系统里经常要打 node_id、request_id、session_id。直接打 UUID 太长打 hex 太枯燥打 Base64 又没法肉眼比对。我用 t3code 把这些 ID 统一编码成短文本打印在关键日志里。实际效果是在日志聚合界面里看两条记录是否属于同一次请求不需要逐字符比对只看分段处就行。比如t3c-v1: d4mb8kv2-fq63z7at-...和t3c-v1: d4mb8kv2-fx63z7at-...第二段开头变了一眼就能发现有串号风险。人眼的模式识别能力在这种分段结构下远比读一长串连续字符强。4.3 窄带/离线数据传输每个块都能单独校验有一次在一个没有内网、只有短信信道的现场我们需要把一段设备参数从总部传到现场。用 t3code 编码后把文本按块拆成几条短信发送现场收到后逐段粘贴进 CLI哪一段在通信过程中被运营商改坏了解码器会准确报出块号只需要让总部重发那一块。同样的逻辑也适用于拍照 OCR打印出来的 t3code 标签被手机拍完识别后如果某个数字被 OCR 认错块校验会立刻报错不会默默解码出一堆错误数据。这类场景的共同特征是信道不可控且人工参与程度高。t3code 的块级校验 分隔符结构让错误定位从整体崩溃变成了局部重传。5. 踩坑、压测与边界修正那些文档里不会写的细节5.1 版本前缀和头部长度没有人给你设计兜底第一个坑就是补零歧义。原始数据长度如果不是 4 的倍数编码前必须补零但补零之后解码端不知道最后补了几个零直接恢复会多出字节。我最早偷懒没管直到第一次拿它编码一个 13 字节的配置项解出来多出 3 个\x00才回去老老实实加了两字节长度头。长度头放在编码前的字节流开头占 2 字节。为什么不是 4 字节因为 t3code 主要服务的是短参数64 KB 对绝大多数使用场景足够。如果你要拿它做文件级备份应该把长度头升级成独立区块而不是简单扩成 4 字节。版本前缀t3c-v1:也是后来补的。它不参与编码算法只承担协议身份作用。现在即使我换了码表旧文本依然能靠前缀路由到旧解码器。5.2 码表不能只讲不混淆还要过一遍字体码表看起来是纯粹的技术选择但实际卡在最麻烦的地方不同操作系统的等宽字体对某些字符的渲染差异巨大。5在 JetBrains Mono 里和S很像在思源等宽里又没那么像6和b在部分点阵字体里几乎就是镜像关系。我最后做了一个很笨但有效的动作把候选字符用大号字体打印成 A3 图纸贴在工位上让团队目测投票凡是隔着三米看会犹豫的字符全部剔除。同时码表一旦确定就写死当作协议的一部分。谁也不能因为看着顺眼去调整码表顺序因为那会直接让所有历史数据失效。5.3 性能取舍比 Base64 慢一半但值得t3code 用 32 字符表每个符号 5 bit输出密度天然低于 Base64。在我笔记本上纯 Python 实现大概 110 MB/sBase64 标准库大概 200 MB/s。编码长度上Base64 是每 3 字节变 4 字符t3code 是每 4 字节数据加 1 字节校验再变 8 字符约等于每字节 2 字符比 Base64 长 50%和 hex 相当。这个代价完全可接受。因为 t3code 的使用场景本来就不是高吞吐信道的首选而是低速率、高人工参与的信道。在那种信道里真正的时间成本从来不是 CPU 编解码的几十毫秒而是人念错一段、重来一遍的好几分钟。做个直观对比方案特殊字符块级校验错误定位语音/手抄友好度Base64有/无无差hex无无无中Base58较少无无中t3code无每 8 字符一块可定位到块好5.4 还剩下的几个坑一是文本传输协议里的换行符。如果 t3code 文本经过邮件、短信或代码剪贴板\r\n和\n的差异会破坏块结构。我在 CLI 里统一做strip()但如果你把它嵌入到别的协议里一定要明确约定不做自动换行。二是大小写敏感性。t3code 的码表固定使用小写解码端遇到大写时会报错而不是自动转换。这不是偷懒是为了防止语音传参时不确定是大写还是小写这种模糊状态。大写就错错了好重来而不是怀着应该没问题的心跳过校验。三是多块边界的分组策略。如果一次编码输出几十块人眼和语音都很难快速定位第 17 段。后来我加了个建议性的分组规则输出超过 6 块时在 CLI 里分组展示比如块之间用空行或缩进区分但网络传输时仍然按标准格式输出。维护 t3code 半年下来我最大的体会是编码输出是一种与人的接口。Base64 这类方案把接口友好性完全扔给了机器一旦链路中插入一个不完美的人类所有问题都会在那个点放大。t3code 的设计并不复杂复杂的是意识到人会犯错这件事应该被设计进协议里。如果你也经常被这种小问题困扰建议从这套块校验思路开始先解决错误能不能被看见再解决错误能不能被定位这比追求一步到位的编码密度要实在得多。