🔌 ProtoWire
零依赖 · 离线优先的 Protocol Buffers 线格式取证、编解码与 Schema 兼容性审计引擎
简体中文 | 繁體中文 | English
🧭 没有 .proto 也能看懂一段 protobuf 二进制;改了 schema 也能在 CI 里挡住破坏性变更。
🎉 1. 项目介绍
我们要解决什么
调试 protobuf 时,工程师常卡在三个非常具体的瞬间:
| 痛点 😖 |
具体场景 |
现有工具的尴尬 |
| 手里只有一串字节 |
抓包、日志、消息队列里捞到 0a 05 41 6c …,.proto 找不到了 |
protoc --decode 必须先有 schema,直接罢工 |
| 不知道改坏了没有 |
把 int32 id = 2 顺手改成 string id = 2 |
编译能过、单测能过,线上老客户端却悄悄解析错 |
| 想把二进制存进工单 |
需要把一段消息贴进 Issue / JSON 流水线 / 测试用例 |
复制粘贴乱码,还无法无损还原 |
ProtoWire 就是为这三个瞬间而生的:一个纯 Python 标准库实现、零第三方依赖、完全离线的工具箱,把「看懂字节 → 按 schema 解码 → 无损转换 → 守住兼容性」串成一条闭环。
核心定位
- 🔍 取证(Forensics):无 schema 扫描任意字节流,输出带偏移量的字段树,自动判别字符串 / 嵌套消息 / packed 数组 / 浮点数。
- 🧬 编解码(Codec):读取
.proto,把 JSON 确定性地编码成线格式字节,或把字节解码成 JSON;未知字段原样保留。
- 🔁 桥接(Bridge):任意 wire 字节 ⇄ JSON,逐字节无损往返,连 unknown field 和 group 都不丢。
- 🛡️ 审计(Audit):13 条规则对比新旧 schema,破坏性变更直接让 CI 失败。
✨ 自研差异化亮点
与「装个 protobuf 编译器 + 写一坨胶水脚本」相比,ProtoWire 做了几件不一样的事:
- 真·零依赖 🪶:
protowire/ 下只 import 标准库,不引入 protobuf、grpcio、click 任何一项;装完即用,断网可用,供应链面积极小。
- 无 schema 也能工作 🕵️:确定性启发式判别嵌套结构,而不是简单 hexdump;每个字段都带 byte offset,方便对照抓包工具定位。
- 可逆而非有损 ♻️:
wire2json / json2wire 保证 json_to_wire(wire_to_json(b)) == b,包含截断容忍与未知字段,适合做回归测试的 golden fixture。
- 兼容性是可执行的门禁 🚦:
protowire check old.proto new.proto 用退出码说话,ERROR → 1,不是一份没人看的报告。
- proto2 / proto3 双语法 🧩:
required、显式 packed、oneof、map、reserved 范围、嵌套类型全部建模,且按语法正确处理 packed 默认行为。
- 安全边界清晰 🔐:10 字节 varint 上限、
2^29-1 字段号上限、递归深度上限、所有读取带边界检查;不联网、不起子进程、不读环境变量、不收集遥测。
🌱 灵感来源
- 📈 当日 GitHub Trending 中 AI Agent 工具链项目(
vercel-labs/agent-browser、anthropics/skills)所暴露的共性需求:Agent 与工具之间传递的结构化二进制,必须可观测、可回放、可回归。
- 📚 Protocol Buffers Encoding Guide 公开的线格式规范,以及
.proto 语言规范。
- 🧰 同账号既有作品
CBORForge(另一种二进制序列化格式的工具链)带来的产品思路:编解码 + 诊断表示法 + 合规规则三件套。
⚖️ 合规声明:以上均为产品逻辑与公开规范层面的参考。ProtoWire 的解析器、编解码器、启发式与审计规则 100% 独立自研,未复制、未搬运、未改写任何第三方项目代码;项目采用 MIT 协议。
✨ 2. 核心特性
| 特性 |
说明 |
| 🔢 完整 wire 原语 |
varint、zig-zag、fixed32/64、sfixed32/64、float/double、length-delimited、group,含非规范 varint 兼容与越界拒绝 |
| 🔭 Schema-less 扫描 |
字段树 + 偏移量 + 线类型 + 类型猜测(string / message / packed / bytes / float)+ 告警(截断、非法字段号、保留段 19000–19999) |
📜 .proto 解析器 |
proto2/proto3、package/import、嵌套 message 与 enum、oneof、map<K,V>、reserved 数字/区间/名称、字段 option、类型解析与校验 |
| 🧬 类型化编解码 |
JSON ⇄ wire,字段按编号确定性排序,packed repeated、map、enum(数字或名称)、bytes hex/base64、unknown fields 保留 |
| 🔁 无损 JSON 桥 |
不需要 schema,任意字节逐字节往返;支持 group;输出可直接进 Git / JSON 流水线 |
| 🛡️ 13 条兼容规则 |
PW001–PW013,覆盖字段增删改、类型/线类型变更、reserved 复用、enum 改号、oneof 迁移、map 类型、proto2↔proto3、package 变更、label 变更 |
| 🚦 CI 门禁 |
check 子命令 + --fail-on error|warn|info|none,退出码 0/1,可配置严重度阈值 |
| 📊 三种报告格式 |
text(终端友好)、json(机器可读)、markdown(直接贴 PR) |
| 🧰 10 个 CLI 子命令 |
scan decode encode parse diff check wire2json json2wire rules demo |
| 🪝 stdin/stdout 友好 |
路径写 - 即走管道;支持内联 hex:0a05... 输入,无需先落盘 |
| 🧪 82 个单元测试 |
全部基于标准库 unittest,含官方编码向量、往返一致性、CLI 子进程端到端测试 |
| 🌍 跨平台 |
Windows / macOS / Linux,Python 3.9+;提供 build.sh 与 build.ps1 双构建脚本 |
🚀 3. 快速开始
✅ 环境要求
| 项目 |
要求 |
| 🐍 Python |
3.9 或更高(3.9 / 3.10 / 3.11 / 3.12 / 3.13 均已验证) |
| 📦 运行时依赖 |
无(dependencies = []) |
| 💻 操作系统 |
Windows / macOS / Linux 任意 |
| 🌐 网络 |
不需要,全流程离线 |
| 🧰 可选工具 |
git、make、build(仅打包时需要) |
📥 安装
# 方式 A:从源码可编辑安装(推荐开发用)
git clone https://github.com/gitstq/ProtoWire.git
cd ProtoWire
python -m pip install -e .
# 方式 B:从已构建产物安装
python -m pip install dist/protowire-1.0.0-py3-none-any.whl
# 方式 C:零安装,直接用模块(克隆后即可)
python -m protowire --version
安装后可用 protowire 命令;未安装时用 python -m protowire,两者完全等价。
⚡ 一键体验
# 内置端到端演示:扫描 + 无损往返,无需任何输入文件
python -m protowire demo
🖼️ 点击展开演示输出(截图 / 动图占位)
📸 演示素材占位:docs/assets/demo-scan.gif(扫描字段树)与 docs/assets/demo-ci.gif(CI 门禁拦截)待补充。当前版本请以 python -m protowire demo 的终端输出为准。
=== 1. schema-less wire scan ===
ProtoWire scan: 42 bytes, 6 top-level field(s)
├─ #1 length-delimited message @0 2 field(s)
│ ├─ #1 length-delimited string @0 'Alice'
│ └─ #2 varint varint @7 30 (0x1e)
├─ #2 length-delimited string @11 'hello from ProtoWire'
├─ #3 varint varint @33 300 (0x12c)
├─ #4 varint varint @36 5 (0x5)
├─ #4 varint varint @38 9 (0x9)
└─ #4 varint varint @40 13 (0xd)
=== 2. lossless wire -> JSON -> wire round trip ===
identical: True
🎯 三条命令上手
# ① 没有 schema?直接扫字节
python -m protowire scan hex:0a05416c6963651001
# ② 有 schema?解码成 JSON
python -m protowire decode --proto examples/person.proto --message Person person.bin
# ③ 改了 schema?挡住破坏性变更
python -m protowire check examples/person.proto examples/person_v2.proto
📖 4. 详细使用指南
📚 更完整的命令参考与场景配方见 docs/USAGE.md。
🧭 命令全景
| 命令 |
作用 |
典型输入 |
scan |
无 schema 扫描字节 |
文件 / hex:... / stdin |
decode |
按 .proto 解码为 JSON |
--proto + --message + 字节 |
encode |
按 .proto 把 JSON 编码为字节 |
--proto + --message + --json |
parse |
输出 schema 模型(含校验) |
.proto |
diff |
输出兼容性报告,不设退出码 |
两个 .proto |
check |
兼容性 CI 门禁(等价 diff --fail-on error) |
两个 .proto |
wire2json |
wire → 无损桥接 JSON |
字节 |
json2wire |
桥接 JSON → wire |
JSON |
rules |
列出 13 条审计规则 |
— |
demo |
内置端到端演示 |
— |
🔍 场景 A:抓到一段不明二进制
# 直接给十六进制,不用先写文件
python -m protowire scan hex:0a05416c6963651001
# 输出机器可读结构,喂给别的工具
python -m protowire scan capture.bin --format json > scan.json
# 贴进 PR 的 Markdown 报告
python -m protowire scan capture.bin --format markdown
# 调参:嵌套深度、关闭猜测、严格模式、隐藏偏移
python -m protowire scan capture.bin --depth 4 --no-offsets
python -m protowire scan capture.bin --no-guess
python -m protowire scan capture.bin --strict # 有解析告警即失败
每个字段都会显示:#字段号、线类型、推断种类、@字节偏移、值预览。嵌套消息会展开成树;packed 数组会展开为数值列表;固定宽度字段同时给出 unsigned / signed / float 三种解读。
🧬 场景 B:有 .proto,做类型化编解码
# 看 schema 模型(含字段类型解析结果与校验问题)
python -m protowire parse examples/person.proto
python -m protowire parse examples/person.proto --format json
# JSON -> wire
python -m protowire encode \
--proto examples/person.proto --message Person \
--json '{"name":"Alice","id":42,"scores":[88,95,100],"labels":{"team":"infra"}}' \
-o person.bin
# wire -> JSON
python -m protowire decode \
--proto examples/person.proto --message Person \
--enum-as-name --bytes-encoding base64 \
person.bin
encode 支持内联 JSON、JSON 文件或 stdin(--json -);decode 默认把 bytes 渲染成 hex,可切 base64;未知字段会落在 __unknown__ 里,加 --no-unknown 可丢弃。
在 Python 里直接调用:
from protowire import parse_proto, encode_message, decode_message, scan
schema = parse_proto(open("examples/person.proto", encoding="utf-8").read())
person = schema.messages["demo.contact.Person"]
raw = encode_message({"name": "Alice", "id": 42}, person, schema)
print(decode_message(raw, person, schema)) # {'name': 'Alice', 'id': 42}
print(scan(raw).to_dict()) # 无 schema 也能看
🔁 场景 C:把二进制塞进工单 / 回归测试
python -m protowire wire2json capture.bin > fixture.json
python -m protowire json2wire fixture.json > restored.bin
cmp capture.bin restored.bin && echo "byte-identical ✅"
# 纯管道写法
cat capture.bin | python -m protowire wire2json - | python -m protowire json2wire - > copy.bin
桥接 JSON 用 varint 数字与 base64 载荷表示每个字段,不依赖 schema,且对 unknown field 与 group 都逐字节还原。
🚦 场景 D:把兼容性检查接进 CI
# 生成人类/机器/PR 三种报告
python -m protowire diff v1.proto v2.proto --format text
python -m protowire diff v1.proto v2.proto --format json
python -m protowire diff v1.proto v2.proto --format markdown
# 门禁:出现 ERROR 就退出 1
python -m protowire check v1.proto v2.proto ; echo "exit=$?"
# 更严格的团队:连 WARN 也不放过
python -m protowire diff v1.proto v2.proto --fail-on warn
.github/workflows/ci.yml 已内置 3 OS × 3 Python 的矩阵:单元测试、CLI 冒烟、兼容性门禁、wheel 安装验证。
🧾 参数速查
| 参数 |
适用命令 |
说明 |
--format text|json|markdown |
scan parse diff check rules |
输出格式 |
-o / --output |
多数命令 |
写文件;- 或省略为 stdout |
--depth N |
scan |
嵌套消息最大展开深度,默认 6 |
--no-guess / --no-offsets / --strict |
scan |
关闭类型猜测 / 隐藏偏移 / 告警即失败 |
--proto / --message |
decode encode |
schema 路径与消息名(支持短名) |
--json |
encode |
内联 JSON、文件路径或 - |
--enum-as-name / --bytes-encoding / --no-unknown |
decode |
枚举渲染 / bytes 编码 / 丢弃未知字段 |
--fail-on error|warn|info|none |
diff |
退出码阈值 |
hex:... |
所有字节输入 |
内联十六进制,空格与换行自动忽略 |
🖼️ 截图占位:docs/assets/cli-scan.png、docs/assets/pr-report.png、docs/assets/ci-gate.png 为预留的演示素材位,欢迎社区补充。
❓ 常见问题
| 问题 |
解答 |
| 扫描结果把字符串误判成嵌套消息? |
启发式是确定性的,可用 --no-guess 关闭猜测;--depth 限制递归;有 schema 时请优先用 decode。 |
支持 proto2 的 group 吗? |
wire 层支持完整读写(含 JSON 桥接),.proto 层会提示「不建模」;建议改用嵌套 message。 |
支持 service / rpc 吗? |
解析器会跳过并给出 INFO 提示,ProtoWire 专注数据面线格式,不做代码生成。 |
线格式和 protoc 完全一致吗? |
标量与 packed 编码遵循官方规范;单测使用官方编码向量(150 → 96 01、300 → ac 02)校验。 |
| 字段编号落在 19000–19999? |
扫描会告警,parse --strict 也会报校验问题(该区间为 protobuf 内部保留)。 |
💡 5. 设计思路与迭代规划
🧠 设计理念
- 先可观测,再可解释 👀:没有 schema 时,先把「字节里到底有什么」诚实呈现出来,包括偏移量与告警,而不是猜一个漂亮但错误的结构。
- 确定性优先 🎲:类型猜测、字段排序、报告顺序全部确定性,输出可直接做 diff 与 golden test;不引入随机与时间戳。
- 可逆优于有损 ♻️:桥接层保留原始字节而非「语义化后重建」,这是它能做回归基线的前提。
- 规则要能拦住事故 🚧:审计规则只保留真实会破坏线上消费者的条目,避免用一堆 INFO 淹没关键 ERROR。
- 零依赖是安全属性,不只是卖点 🪶:无第三方包 = 无供应链投毒面、无版本冲突、无网络回连,适合放进构建基线与内网环境。
🛠️ 技术选型
| 选择 |
原因 |
| 纯 Python 标准库 |
struct / base64 / json / re / dataclasses 足够覆盖 wire 与 schema 解析;跨平台无痛 |
自研 .proto 递归下降解析器 |
只需数据面子集,避免引入编译器依赖;可控地支持 map / oneof / reserved |
dataclasses 数据模型 |
无依赖、可 asdict() 导出 JSON、类型注解友好(附 py.typed) |
argparse CLI |
标准库、零依赖、自动生成帮助;子命令清晰 |
unittest 测试 |
与运行时零依赖一致,CI 无需额外安装测试框架 |
PEP 517 pyproject.toml |
现代构建;build.sh / build.ps1 提供无 build 包时的兜底路径 |
🗺️ 模块划分
protowire/
├── wire.py # 🔢 线格式原语(varint / zigzag / fixed / key / field reader)
├── scanner.py # 🔭 无 schema 取证扫描与确定性启发式
├── proto.py # 📜 .proto 词法/语法解析、类型解析、校验
├── codec.py # 🧬 类型化编解码 + 无损 JSON 桥
├── compat.py # 🛡️ 13 条兼容性规则与退出码
├── report.py # 📊 text / json / markdown 渲染
└── cli.py # 🧰 10 个子命令
🚀 后续迭代计划
- 📎 诊断表示法:类 CBOR diagnostic notation 的单行可读格式,便于日志引用。
- 🔗
FileDescriptorSet 互操作:读取 protoc --descriptor_set_out 产物作为 schema 来源。
- 🧮 体积归因:按字段号统计字节占比,定位「哪个字段把消息撑爆了」。
- 🧪 差分模糊测试:随机 wire 变异 + 往返不变量,持续加固边界检查。
- 🌐 更多语言 README:日语、韩语、西班牙语(社区贡献优先)。
- 📦 可选 Protobuf 兼容层:与官方
protobuf 库做交叉验证(保持为可选开发依赖,不进运行时)。
🤝 社区贡献方向
最欢迎三类贡献:① 新的兼容性规则(附反例与测试);② 启发式误判的真实样本(脱敏后的 hex 即可);③ 更多语言的母语级文档润色。详见 CONTRIBUTING.md。
📦 6. 打包与部署指南
🧩 项目类型判定:ProtoWire 属于「工具库 / CLI / 脚本类」项目。按发布规范,此类项目无需上传跨平台可执行二进制到 Release;重点是把「安装 → 引入 → 集成 → 使用」写清楚,并保证零门槛集成。
🏗️ 一键构建
# Linux / macOS / Git-Bash
make build
# 或
PYTHON=python3.11 sh scripts/build.sh
# Windows PowerShell
pwsh -File scripts/build.ps1
产物:
dist/
├── protowire-1.0.0-py3-none-any.whl # 纯 Python wheel,全平台通用
└── protowire-1.0.0.tar.gz # 源码分发
构建脚本会自动验证产物:把 wheel 装进临时目录,再执行 protowire --version 与 scan,失败即报错退出。
📥 部署 / 集成方式
| 场景 |
做法 |
| 🖥️ 本地命令行 |
python -m pip install dist/*.whl → protowire --help |
| 🧪 CI 流水线 |
python -m pip install -e . → python -m unittest discover -s tests -v → protowire check v1.proto v2.proto |
| 📦 作为库引入 |
pip install . 后 from protowire import parse_proto, scan, encode_message, decode_message |
| 🔌 vendoring(内网/离线) |
直接把 protowire/ 目录拷进项目,无任何依赖,随代码走 |
| 🐳 容器 |
基础镜像只需 python:3.9-slim;无需 apt、无需编译工具链 |
✅ 兼容矩阵
| 维度 |
支持范围 |
| Python |
3.9 / 3.10 / 3.11 / 3.12 / 3.13(CI 覆盖 3.9 / 3.11 / 3.13) |
| 操作系统 |
Linux / macOS / Windows(CI 三平台矩阵) |
| 架构 |
纯 Python,与 CPU 架构无关 |
.proto 语法 |
proto2 / proto3 子集(见 docs/USAGE.md 支持矩阵) |
| 运行时依赖版本 |
无(dependencies = []) |
| 可选开发依赖 |
build>=1.0、pytest>=7.0、ruff>=0.4(仅 dev extra,不影响运行) |
⚠️ 注意事项
- 🔐 不要提交密钥:
.gitignore 已排除 .env*、*.pem、*.key、secrets.*。
- 🧯 扫描不可信输入:
scan 默认宽容模式会记录告警并跳过损坏尾部;--strict 会抛 WireError。所有读取均有边界与深度上限。
- 📏 启发式不是编译器:无 schema 时的类型推断只能作为排障线索;正式解码请使用
decode + 对应 .proto。
- 🧾 版本语义:遵循 SemVer,变更记录见 CHANGELOG.md。
🤝 7. 贡献指南
📝 PR 提交规范
提交信息遵循 Angular / Conventional Commits:
<type>(<scope>): <简短祈使句>
[可选正文:说明 WHAT 与 WHY]
[可选脚注:Closes #123]
| type |
用途 |
feat |
新功能 / 新审计规则 |
fix |
缺陷修复 |
docs |
文档变更 |
refactor |
不改变行为的重构 |
test |
测试增补 |
perf / build / chore |
性能 / 构建与 CI / 杂项 |
合并前请确认:✅ 82 个单测通过 ✅ python -m protowire demo 正常 ✅ 新行为有测试 ✅ 三语 README 与 CHANGELOG.md 同步 ✅ 无新增运行时依赖、无网络调用、无密钥 ✅ 提交信息合规。
🐛 Issue 反馈规则
请附:① protowire --version 与 Python/OS 版本;② 完整命令;③ 最小可复现输入(推荐内联 hex:... 或短 .proto 片段,切勿粘贴生产数据或凭据);④ 期望与实际输出。疑似兼容性误判请同时给出 v1.proto / v2.proto 与 --format json 结果。
完整规则见 CONTRIBUTING.md。
📄 8. 开源协议
本项目采用 MIT License —— 可自由使用、复制、修改、合并、发布、分发、再授权与商业销售,只需保留版权与许可声明。
MIT License
Copyright (c) 2026 gitstq
完整条款见 LICENSE。软件按「原样」提供,不作任何明示或默示担保。