ProtocolBuffers设计技能Skill protobuf-design

---

名称: protobuf-design 描述: 用于服务合同的 Protocol Buffers 和接口定义语言 允许工具: Read, Glob, Grep, Write, Edit, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs

Protocol Buffers 设计技能

何时使用此技能

使用此技能当：

• 设计 gRPC 服务 - 使用 Protocol Buffers（proto3）进行类型化服务合同
• 模式定义 - 消息、枚举、服务、流模式
• 在 C# 中实现 - 使用 ASP.NET Core 的 gRPC
• 模式演化 - 向后/向前兼容性、版本控制

强制性：文档优先方法

在创建 protobuf 定义之前：

1. 调用 docs-management 技能 获取 API 合同模式
2. 通过 MCP 服务器验证 proto3 语法（context7 获取最新规范）
3. 所有指导基于 Google 的 Protocol Buffers 文档

为什么使用 Protocol Buffers？

好处	描述
高效	二进制格式，比 JSON 小 3-10 倍
类型化	强类型与代码生成
版本化	内置向后/向前兼容性
跨语言	支持 C#、Java、Python、Go 等
gRPC 集成	gRPC 的原生服务定义

Proto3 结构概述

syntax = "proto3";

package ecommerce.orders.v1;

option csharp_namespace = "ECommerce.Orders.V1";

import "google/protobuf/timestamp.proto";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc WatchStatus(WatchRequest) returns (stream StatusUpdate);
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_DRAFT = 1;
  ORDER_STATUS_SUBMITTED = 2;
}

message Order {
  string id = 1;
  string customer_id = 2;
  OrderStatus status = 3;
  google.protobuf.Timestamp created_at = 4;
}

完整模板：见 proto-syntax.md

快速参考

gRPC RPC 类型

模式	语法	使用案例
一元	rpc Get(Req) returns (Resp)	简单 CRUD
服务器流	rpc List(Req) returns (stream Resp)	大型结果、更新
客户端流	rpc Upload(stream Req) returns (Resp)	批量上传
双向流	rpc Chat(stream Req) returns (stream Resp)	实时同步

流模式：见 grpc-patterns.md

命名约定

元素	约定	示例
包	小写.点.版本	ecommerce.orders.v1
服务	PascalCase + Service	OrderService
RPC	PascalCase 动词	CreateOrder
消息	PascalCase	OrderCreatedEvent
字段	蛇形命名法	customer_id
枚举	大写前缀值	ORDER_STATUS_DRAFT

工作流程

1. 识别资源：服务管理哪些实体？
2. 定义消息：每个资源的数据结构
3. 设计服务方法：CRUD 操作、查询、命令
4. 添加流：需要实时更新的地方
5. 文档：所有消息和字段的注释
6. 检查：使用 Buf 或 protolint 确保一致性
7. 版本：计划模式演化
8. 生成：创建客户端/服务器代码

参考

根据需要加载：

参考	加载时机
proto-syntax.md	创建 proto 定义、已知类型、高级模式
grpc-patterns.md	设计流服务（服务器、客户端、双向）
csharp-implementation.md	在 .NET/C# 中使用 ASP.NET Core 实现 gRPC
schema-evolution.md	计划模式更改、Buf CLI、版本控制

相关技能（跨插件）

阶段	技能	插件	目的
设计	protobuf-design（此技能）	正式规范	架构研究、模式选择
编写	N/A	规范驱动开发	缺口： protobuf-authoring 尚未创建

工作流程： 设计（研究 gRPC 模式）→ 编写（创建 .proto 文件）→ 生成（代码生成）

注意： 与 OpenAPI 和 AsyncAPI 不同，protobuf 编写通常足够直接，设计技能的 C# 实现参考覆盖了具体创建。如果需求允许，可以添加专用的 protobuf-authoring 技能。

外部参考

• Protocol Buffers 文档 - 官方 Google 文档
• gRPC 文档 - 官方 gRPC 指南
• Buf CLI - 现代 protobuf 工具
• Google API 设计指南 - 资源导向 API 模式
• gRPC for .NET - ASP.NET Core gRPC 文档

MCP 研究

对于当前 protobuf 模式和工具：

perplexity: "Protocol Buffers proto3" "gRPC service design patterns"
context7: "grpc" (用于官方文档)
microsoft-learn: "gRPC ASP.NET Core" (用于 .NET 实现)

版本历史

• v2.0.0 (2026-01-17)：重构为渐进披露模式
  • 提取了 4 个参考文件（约 550 行）
  • 中心从 700 行减少到约 130 行
  • 更新了 NuGet 包版本（Grpc.AspNetCore 2.71.0）
• v1.0.0 (2025-12-26)：初始发布

---

最后更新： 2026-01-17