RoGo-Proto

RoGo-Proto 是所有服务间通信的 单一真相来源 (Single Source of Truth)。

仓库地址: https://github.com/StringlightRobotics/RoGo-proto

为什么需要规范流程？

rogo-proto 定义了所有 Protobuf 和 ROS 消息格式。直接在业务代码（Core/Ops/Cloud）中修改协议是严禁的。

直接在业务代码中修改协议会导致:

• ❌ 服务间通信不兼容
• ❌ 难以追踪协议变更历史
• ❌ 无法自动生成多语言 SDK

修改流程

步骤 1: 修改 rogo-proto

# 1. 克隆 rogo-proto
git clone git@github.com:StringlightRobotics/RoGo-proto.git
cd rogo-proto

# 2. 创建功能分支
git checkout -b feat/add-battery-status

# 3. 修改 .proto 文件
vim protos/robot/status.proto

Proto 文件示例

syntax = "proto3";

package rogo.robot;

// 电池状态消息
message BatteryStatus {
  // 电池电量百分比 (0-100)
  float percentage = 1;
  
  // 是否正在充电
  bool is_charging = 2;
  
  // 预计剩余运行时间 (分钟)
  int32 estimated_runtime_minutes = 3;
  
  // 电池健康状态
  BatteryHealth health = 4;
}

enum BatteryHealth {
  BATTERY_HEALTH_UNKNOWN = 0;
  BATTERY_HEALTH_GOOD = 1;
  BATTERY_HEALTH_DEGRADED = 2;
  BATTERY_HEALTH_CRITICAL = 3;
}

ROS 消息示例

# msg/BatteryStatus.msg

# 电池电量百分比 (0-100)
float32 percentage

# 是否正在充电
bool is_charging

# 预计剩余运行时间 (分钟)
int32 estimated_runtime_minutes

# 电池健康状态 (0=未知, 1=良好, 2=退化, 3=危险)
uint8 health

uint8 HEALTH_UNKNOWN = 0
uint8 HEALTH_GOOD = 1
uint8 HEALTH_DEGRADED = 2
uint8 HEALTH_CRITICAL = 3

步骤 2: 提交 PR 并合并

# 提交更改
git add .
git commit -m "feat(robot): add battery status message

Add BatteryStatus message with:
- Battery percentage
- Charging status
- Estimated runtime
- Battery health enum

Closes #45"

# 推送分支
git push origin feat/add-battery-status

在 GitHub 上创建 PR:

1. 填写 PR 描述，说明变更原因
2. 请求相关团队成员审核
3. 等待 CI 检查通过
4. 获得批准后合并

步骤 3: 更新依赖仓库

方式 A: 使用 Git Submodule

# 在 rogo-core 中更新 submodule
cd rogo-core
git submodule update --remote proto
git add proto
git commit -m "chore: update rogo-proto submodule"

方式 B: 重新生成依赖库

# 在 rogo-cloud 中更新 protobuf
cd rogo-cloud
./scripts/generate_proto.sh

# 在 rogo-core 中更新 ROS 消息
cd rogo-core
./scripts/generate_ros_msgs.sh

版本兼容性

向后兼容的更改 ✅

• 添加新字段（使用新的字段编号）
• 添加新消息类型
• 添加新服务方法
• 添加新枚举值

非向后兼容的更改 ⚠️

需要协调发布

以下更改需要所有相关服务同时更新:

• 删除或重命名字段
• 更改字段编号
• 更改字段类型
• 删除消息或服务

协议版本管理

// 在消息中包含版本信息
message RobotCommand {
  // 协议版本
  int32 version = 1;
  
  // ... 其他字段
}

最佳实践

1. 字段命名

// ✅ 好的命名
message RobotPosition {
  double latitude_degrees = 1;
  double longitude_degrees = 2;
  float heading_radians = 3;
}

// ❌ 糟糕的命名
message RobotPosition {
  double lat = 1;      // 不清晰
  double lng = 2;      // 不清晰
  float h = 3;         // 不清晰
}

2. 添加注释

// 机器人任务状态
// 用于追踪任务执行进度
message TaskStatus {
  // 任务唯一标识符
  string task_id = 1;
  
  // 当前状态
  // 状态流转: PENDING -> EXECUTING -> COMPLETED/FAILED
  TaskState state = 2;
  
  // 任务进度 (0.0 - 1.0)
  float progress = 3;
  
  // 错误信息 (仅在 state=FAILED 时有值)
  string error_message = 4;
}

3. 预留字段

message SensorData {
  string sensor_id = 1;
  float value = 2;
  int64 timestamp = 3;
  
  // 预留字段供未来扩展
  reserved 10 to 20;
  reserved "deprecated_field";
}

审核清单

协议变更 PR 审核时应检查:

• [ ] 字段编号是否正确（没有复用已删除的编号）
• [ ] 是否添加了充分的注释
• [ ] 命名是否清晰一致
• [ ] 是否保持向后兼容
• [ ] 是否更新了相关文档

下一步

了解 RoGo-core 和 RoGo-cloud 核心模块的开发细节。