proto/
├── .gitignore          # Git忽略配置文件
├── Makefile            # 构建和发布脚本
├── README.md           # 项目说明文档
├── src/                # 服务定义目录
├── buf.gen.yaml        # buf生成配置
├── buf.yaml            # buf项目配置
├── script/             # 辅助脚本目录
├── templates/          # 模板文件目录
└── version.txt         # 版本号文件

编写指南

安装必要工具

本项目使用以下工具进行 Protocol Buffers 的管理、构建和代码生成：

# 安装 Go 相关工具
go install github.com/bufbuild/buf/cmd/buf@latest
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest

# 安装 Node.js 相关工具
npm install -g @bufbuild/protoc-gen-es

提示：如果安装后找不到命令，需要确保工具的 bin 目录已添加到系统 PATH 环境变量中。如果是使用 brew 安装的软件，可以执行 brew unlink name && brew link name 来解决。如：brew unlink node && brew link node

修改 proto 文件后的工作流程

当你需要修改或添加 proto 文件时，请遵循以下工作流程：

修改/创建 proto 文件：在 src/ 目录下按照服务和版本组织的结构进行修改或创建新文件
验证语法：运行 buf lint 确保语法符合规范
检查兼容性：运行 buf breaking --against .git#branch=main 检查是否有不兼容变更
生成 SDK 代码：运行 make generate 命令生成最新的 SDK 代码
发布 SDK：运行 make publish 命令自动生成新版本号并发布 SDK（版本号会通过脚本自动管理）

版本控制

本项目使用语义化版本控制，服务接口的变更遵循以下原则：

向后兼容：尽量保持接口的向后兼容性
版本升级：不兼容的变更请在 src 中为服务创建单独的版本目录
自动版本生成：通过 script/get_next_version.sh 脚本自动管理版本号
Breaking Change 检查：使用 buf breaking 工具检查不兼容的变更

开发规范

遵循 Protocol Buffers Style Guide 并使用 buf 标准 lint 规则
具体 lint 规则配置可在项目根目录的 buf.yaml 文件中查看
每个服务定义放在单独的目录下，并按版本号组织
新增字段时使用新的字段编号，不要重用已删除字段的编号

Makefile 命令提示

执行 make help 可查看所有可用命令和详细说明。主要命令包括：

make generate: 生成 SDK 代码
make publish: 发布 SDK 到各个仓库

README.md Unescape Escape

神仙盒公共 gRPC 服务定义

项目简介

SDK 地址

目录结构

编写指南

安装必要工具

修改 proto 文件后的工作流程

版本控制

开发规范

Makefile 命令提示

版权信息

README.md