Protobuf 定义审计 yuehancn/dsh-tool-protobuf

dsh-tool-protobuf

在聊天里读取、审计和对比 Protocol Buffer 定义 —— 不用安装 protoc。

智能体循环里大部分 .proto 相关的工作都是读取，不是编译：这个文件里有什么，两个版本之间改了什么，这个编号空着吗，有没有人复用了字段编号。 这四件事都不该用编译器来做 —— 编译器回答的是「能不能编译」，而这很少是你想问的问题，而且它还需要一套工具链，你手头这台机器上未必有。

这个插件在进程内解析 .proto 语法。不需要 protoc，不需要 Python，不需要联网，没有任何外部依赖。

安装

dsh plugin --profile <your-profile> link /path/to/dsh-tool-protobuf

然后设置它允许读取的目录 —— workDir 是边界，不是提示：

in your profile's cordis.patch.yml
- id: tool-protobuf
config:
workDir: C:/work/my-service/proto

六个工具

| 工具 | 它回答的问题 |
| protobuf_status | 这台机器上有没有真正的 protoc，workDir 下有哪些 .proto 文件？ |
| protobuf_outline | 这个文件里有什么 —— syntax、package、imports，以及所有声明的结构。 |
| protobuf_describe | 这一个 message 或 service 里有什么 —— 每个字段的编号、类型和 wire 开销；每个 RPC 的流式形态和 gRPC 路径。 |
| protobuf_diff | v1 到 v2 之间改了什么 —— 归类为 breaking / risky / additive。 |
| protobuf_audit | 这个文件里有哪些问题，是编译器会放过去的。 |
| protobuf_next_number | 这里哪些字段编号空着，或者 这个 编号能不能安全使用。 |

为什么 protobuf_diff 才是你该装它的理由

wire 格式以字段编号为键，不是以名称为键。几乎所有 protobuf 事故都源于这一条：

- 改字段名，编号不变 → 旧数据照样能解码。无害。
- 改字段名，同时改编号 → 名称还对得上，字节对不上。旧数据落进另一个字段，或者哪儿都落不进去。
- 删字段但不 reserve 它的编号 → 下一个人拿这个编号去放别的类型，旧数据被悄悄解读成垃圾。
- 同一个编号上把 int32 改成 string → 字节会按错误的类型读取。

protobuf_diff 会把每一种情况都点出来，不用你自己去找：

verdict: incompatible (8 breaking, 1 risky, 5 additive)
[breaking] type-changed: field amount_minor (2) changed type int64 -> string
[breaking] number-reused: field 9 was "total_minor" and is now "line_items_summary" — old clients will decode new bytes into the old field [breaking] field-added: new field customer_detail = 14 lands in a previously reserved range [breaking] number-changed: field "total_minor" moved from 9 to 30 — the name is the same but the wire format is keyed by number, so old data no longer decodes into it [breaking] field-removed: field currency = 10 removed but 10 was NOT reserved — reserve it now or it will be reused [risky] field-removed: 字段 due_at = 6 已移除，编号已保留；建议把名字也一并保留 [additive] field-added: 新增字段 currency_display = 20

每条消息都写得可以直接照做。number-reused 说的是会发生什么，而不只是编号撞了。field-removed 区分了两种情况：安全移除（编号已保留）和日后的数据损坏 bug（编号空着没管）——并提醒你把编号保留下来。

为什么 protobuf_audit 能抓到编译器抓不到的问题

protoc 会接受大量定义，它们技术上合法，实际上是坑：

broken.proto: 10 errors, 4 warnings
[error] Dup.b: field number 1 is already used by "a"
[error] Dup.c: field number 19005: 19000-19999 is reserved by protobuf itself
[error] Dup.d: field number 0: below 1
[error] Dup.e: field number 536870912: above 536870911 (2^29-1)
[error] ReservedClash.bad: field number 5 is declared reserved in this message
[error] BadMap.nope: map key type "bytes" is not allowed
[error] BadMap.dangling: map value type "MissingType" is not a scalar and is not defined in this file, and the file imports nothing
[error] NoZero: proto3 enums must have a zero value (the default)
[error] Aliased.ALIASED_B: enum value 0 duplicates "ALIASED_A"
[warn] Gappy: unused field numbers 2 sit below the high-water mark 3 and are not reserved — a future edit may reuse one and break compatibility

warn 那行最值得一读：高水位线以下出现空档，说明有人删了字段却没保留编号，下次再动这个编号，就是一个等着随版本发布出去的数据损坏 bug。注意，空档很宽的消息会把空档汇总成一条发现，而不是每个编号一行——一个有 4,095 个空洞的文件只产生一条警告，不是 4,095 条。

独立验证

手写解析器有个绕不开的问题：它可能自说自话。所以这个插件的测试套件以来自一个不是我们写的编译器的第二意见为准：

$ PROTOC_PYTHON=/path/to/python-with-grpcio-tools node _test/run-all.mjs
independent compiler: C:/Users/.../python.exe

PASS test-logic.mjs # tests 71 # pass 71 # fail 0
PASS test-integration.mjs # tests 33 # pass 33 # fail 0
PASS test-e2e.mjs # tests 9 # pass 9 # fail 0

all suites passed

e2e 套件针对真实的 protoc 断言两件事：凡是这个解析器接受的格式正确的 fixture，它都接受；那个故意写坏的 fixture，它都拒绝。两个方向都重要——一个什么都接受的解析器，光靠第一项测试就能过。

这个参照标准在开发期间抓到一个真实 bug：billing-v2.proto 里 line_items_summary = 9，同时又声明了 reserved 9，这个解析器接受了，protoc 拒绝了。解析器太宽松，fixture 写错了。只有外部意见才能判断出是哪一个。
没有 PROTOC_PYTHON 时，oracle 测试会输出一条诊断信息并跳过——run-all.mjs 会打印它跑在哪种模式下，因为 oracle 被跳过时的绿色通过是更弱的结果，这种差别不该被藏起来。

这个插件不做什么

- 它不编译。 不生成 descriptor set，不做代码生成，不做 wire 编码。protobuf_status 告诉你是否有真正的 protoc 可用，方便你自行调用它。
- 它不解析 import。 import 只按名字上报；定义在另一个文件里的类型会报为无法解析，而不是猜测。否则就只能写出一个凭空捏造类型的解析器。
- 它一次只读一个文件。 protobuf_diff 接收两个路径，不是两棵目录树。

安全

workDir 的强制方式是：只取调用方所给路径的最后一段路径，丢弃它之前的所有内容。这比拒绝 .. 更严格，而且是刻意为之：盘符能躲过简单的分段过滤，所以 C:/tmp/work + C:\Windows\System32\config\SAM 会解析成一个可访问的路径，把文件泄露出去。只有最后一段会被采纳，因此调用方只能指定文件，永远无法指定位置。

超过 8 MB 的文件会被拒绝，而不是解析。

许可证

MIT