前言¶
在 DeepSeek Harness（DSH）里做 API 或 gRPC 相关开发时，智能体经常要回答的不是「这份 .proto 能不能编译」，而是：文件里声明了什么、两个版本之间改了什么、某个 field number 还能不能用、有没有人会复用已删字段的编号。装一套 protoc toolchain 可以回答编译问题，但对上述阅读与兼容性判断往往过重，且在部分环境里未必现成可用。
下面介绍社区插件 dsh-tool-protobuf（维护者 yuehancn）：在进程内解析 .proto 语法，不依赖 protoc、Python 或外网，向对话暴露六个专用工具，用于概览、描述、差异、审计与编号查询。
这是什么¶
dsh-tool-protobuf 是 DSH 生态中的工具类插件（仓库：yuehancn/dsh-tool-protobuf，目录页：SkillHub 插件页）。当前 package 版本为 0.1.0，许可证 MIT，要求 DSH >=0.2.0-rc.2。
定位一句话：在对话中读取、审计与对比 Protocol Buffer 定义，无需安装 protoc。 它不生成代码、不产出 descriptor set、不做 wire 编码；需要真实编译时，可由 protobuf_status 探测本机是否已有 protoc，再自行 shell 调用。
六个工具分别回答什么问题¶
| 工具 | 用途 |
|---|---|
protobuf_status |
本机是否有可用的 protoc；workDir 下有哪些 .proto 文件 |
protobuf_outline |
单文件概览：syntax、package、imports 及各类声明的结构 |
protobuf_describe |
单个 message 或 service：字段编号、类型、wire 成本；RPC 流式形态与 gRPC path |
protobuf_diff |
两个版本之间的变更，归类为 breaking / risky / additive |
protobuf_audit |
找出 protoc 可能放过、但在实践中容易踩坑的问题 |
protobuf_next_number |
某 message 内哪些 field number 空闲，或指定编号是否安全 |
插件一次只读一个文件（protobuf_diff 接受两个路径，不是整棵树）。不解析 import 链：import 只报名称；跨文件类型报为不可解析，而不是猜测类型。
为什么 diff 和 audit 值得单独说¶
protobuf_diff 与 wire 兼容性¶
Protobuf 线上数据按 field number 键控，不是按字段名。重命名但保留编号通常无害；改名又改号则旧字节会落到错误字段。删字段却不 reserved 编号，后续复用会导致旧数据被静默误读。同号改类型（如 int32 → string）同样危险。
protobuf_diff 会把上述情况具名列出，例如 type-changed、number-reused、number-changed、field-removed（并区分编号是否已 reserved），输出面向行动，而不只是「有变更」。
protobuf_audit 与编译器的盲区¶
protoc 能接受许多语法合法、工程上却危险的定义：重复 field number、落在 protobuf 保留区间、map key 类型非法、proto3 enum 缺少 0 值等。audit 还会 warn 高水位以下存在未 reserved 的空洞——删字段未留号时，下一次编辑极易造成兼容性事故；大文件里空洞会汇总为一条 finding，避免刷屏。
安装与配置¶
安装¶
官方 README 给出的方式为本地 link（需先把插件目录放到本机，路径替换为实际位置）：
dsh plugin --profile <your-profile> link /path/to/dsh-tool-protobuf
配置 workDir¶
workDir 是允许读取的边界，不是提示。在 profile 的 cordis.patch.yml 中配置，例如：
# in your profile's cordis.patch.yml
- id: tool-protobuf
config:
workDir: C:/work/my-service/proto
路径安全策略：调用方传入的路径只取最后一段文件名，前面段被丢弃，避免通过 .. 或盘符组合读到 workDir 外文件。超过 8 MB 的文件会被拒绝解析。
典型用法（对话侧）¶
安装并配置 workDir 后，在 DSH 对话中由智能体调用上述工具即可，无需额外 CLI。常见流程可以是：
- 用
protobuf_status确认本机 protoc 与目录内 proto 列表。 - 用
protobuf_outline/protobuf_describe理解现有 schema。 - 改 schema 前用
protobuf_next_number选号；改后用protobuf_diff对两个文件路径做兼容性审查。 - 合入前对单文件跑
protobuf_audit。
README 中给出了 protobuf_diff 与 protobuf_audit 的输出示例，可作为预期格式的参考（含 verdict: incompatible、breaking/risky/additive 分类及具体条目）。
适用场景与限制¶
适合：在 DSH 智能体循环里做 proto 阅读、评审、版本 diff、编号与 reserved 规则检查；机器上没有 protoc 时仍能做上述工作。
不适合或需知：不编译、不 codegen；不跨文件 resolve 类型；diff 是两文件而非目录 diff。import 仅作名称报告。
安全与信任：插件以当前 DSH 进程权限运行，只能读 workDir 策略允许范围内的文件。安装前建议阅读 GitHub 源码 与 MIT 许可证；社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
维护者在 README 中说明：手写解析器会与自身一致，因此测试套件可在设置 PROTOC_PYTHON 时用真实 protoc 做双向 oracle（well-formed 与 deliberately-broken fixture）；未设置时 oracle 用例会 skip。这与日常使用无关，但说明解析行为曾对照外部编译器校验过。
小结¶
dsh-tool-protobuf 把 Agent 场景里最常见的 proto 问题——读结构、比版本、查号、抓兼容性陷阱——收进 DSH 六个工具，免装 protoc 即可在对话里完成。若你的 workflow 以 schema 演进为主，优先熟悉 protobuf_diff 与 protobuf_audit。
- 目录页：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-protobuf
- GitHub：https://github.com/yuehancn/dsh-tool-protobuf
