Protobuf Linter

核心功能是通过24条规则（覆盖结构、命名、兼容性、最佳实践）检查.proto文件，支持proto2/3语法。可单文件/递归目录检查，也可指定仅校验命名、兼容性等类别，还能对比新旧版本检测兼容性破坏。支持文本、JSON、摘要三种输出格式，退出码区分结果状态，适用于开发规范、版本迭代兼容性校验等场景。

charlie-morrison

热度 52.81

最近更新 2026-05-11 17:42:55

分类：开发依赖：代码执行 / 读写文件应用场景：代码审查

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add protobuf-linter

Metadata

name: protobuf-linter
description: Lint Protocol Buffer (.proto) files for style, naming conventions, breaking changes, and best practices. Supports proto2 and proto3 syntax with 24 rules across structure, naming, security, and compatibility categories.

Protobuf Linter

Lint .proto files for style violations, naming issues, breaking changes, and best practices.

Commands

# Lint a proto file (all rules)
python3 scripts/protobuf_linter.py lint path/to/file.proto

# Check naming conventions only
python3 scripts/protobuf_linter.py naming path/to/file.proto

# Check for breaking changes between two versions
python3 scripts/protobuf_linter.py breaking path/to/old.proto path/to/new.proto

# Validate syntax and structure
python3 scripts/protobuf_linter.py validate path/to/file.proto

# Lint a directory recursively
python3 scripts/protobuf_linter.py lint path/to/protos/ --recursive

# JSON output
python3 scripts/protobuf_linter.py lint path/to/file.proto --format json

# Summary only
python3 scripts/protobuf_linter.py lint path/to/file.proto --format summary

Rules (24)

Structure (6)

Missing syntax declaration
Missing package declaration
Empty message/enum/service definitions
Duplicate field numbers
Reserved field number conflicts
Import not found (relative path check)

Naming (8)

Message names must be CamelCase
Enum names must be CamelCase
Enum values must be UPPER_SNAKE_CASE
Enum values must be prefixed with enum name
Field names must be lower_snake_case
Service names must be CamelCase
RPC method names must be CamelCase
Package names must be lower_snake_case with dots

Compatibility (5)

Changed field type (breaking)
Removed field without reserving number (breaking)
Changed field number (breaking)
Renamed enum value (breaking)
Changed RPC request/response type (breaking)

Best Practices (5)

Use proto3 syntax (proto2 warning)
Avoid required fields (proto2)
Use wrapper types for optional semantics
Comment coverage (messages/services)
File should match package name

Output Formats

text (default): Human-readable with colors and severity icons
json: Machine-readable with file, line, rule, severity, message
summary: Counts by severity only

Exit Codes

0: No issues (or warnings only)
1: Errors found
2: Invalid input