From c80ac936c722d2e8d5a4492697d6da3f76724058 Mon Sep 17 00:00:00 2001 From: eastzio <3156045992@qq.com> Date: Thu, 25 Jun 2026 10:49:09 +0800 Subject: [PATCH] =?UTF-8?q?[init]=20RC=5FLegged=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 40 ++++++++ README.md | 28 +++++ 项目规范.md | 287 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 项目规范.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..93fb5ea --- /dev/null +++ b/.gitignore @@ -0,0 +1,40 @@ +# 编译产出 +build/ +devel/ +install/ +*.o +*.elf +*.hex + +# Python +__pycache__/ +*.pyc +*.pyo +.venv/ +venv/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# 训练产出 +05_software/rl_training/logs/ +05_software/rl_training/checkpoints/ +wandb/ + +# ROS +*.bag +*.mcap + +# 系统 +.DS_Store +Thumbs.db + +# 本地参考项目（不纳入版本管理） +00_reference/ + +# 机械备份 +*.bak +*.old diff --git a/README.md b/README.md new file mode 100644 index 0000000..0c7950f --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# RC_Legged + +四轮足强化学习机器狗项目 —— 从机械到代码，从 0 到 1。 + +## 目录结构 + +``` +RC_Legged/ +├── 00_reference/ # 参考项目与文档 +├── 01_doc/ # 项目文档 +├── 02_mechanical/ # 机械设计 +├── 03_hardware/ # 硬件电路 +├── 04_firmware/ # 嵌入式固件 +├── 05_software/ # 上层软件（RL/ROS） +├── 06_assets/ # 媒体资源 +├── 项目规范.md # 项目规范 +└── README.md +``` + +## Gitea 仓库 + +`https://git.zeitvex.com/Robocon/RC_Legged.git` + +## 参考项目 + +- EDULITE_A3 — 教育级四足机器人 +- OpenDog — 开源四足机器狗 +- reBot-DevArm — 开源机械臂 diff --git a/项目规范.md b/项目规范.md new file mode 100644 index 0000000..8da65cb --- /dev/null +++ b/项目规范.md @@ -0,0 +1,287 @@ +# RC_Legged 项目规范 + +## 1. 项目概述 + +RC_Legged 是一个四轮足强化学习（RL）机器狗项目，涵盖机械设计、硬件电路、嵌入式软件和控制算法全栈开发。 + +### 仓库地址 + +- **Gitea 远程仓库**: `https://git.zeitvex.com/Robocon/RC_Legged.git` +- **SSH**: `git@git.zeitvex.com:Robocon/RC_Legged.git` + +--- + +## 2. 仓库目录结构规范 + +``` +RC_Legged/ +├── 00_reference/ # 参考项目与文档（只读，不改动） +├── 01_doc/ # 项目文档（设计文档、会议记录、需求文档） +├── 02_mechanical/ # 机械设计（SolidWorks/STL/URDF/STEP） +│ ├── CAD/ # 源文件 +│ ├── STL/ # 3D 打印文件 +│ └── URDF/ # URDF 描述文件 +├── 03_hardware/ # 硬件电路设计（KiCad/Altium） +│ ├── PCB/ # PCB 工程文件 +│ ├── BOM/ # 物料清单 +│ └── datasheet/ # 芯片/模块数据手册 +├── 04_firmware/ # 嵌入式固件（STM32/ESP32 等） +│ ├── motor_driver/ # 电机驱动固件 +│ └── sensor_board/ # 传感器板固件 +├── 05_software/ # 上层软件 +│ ├── rl_training/ # 强化学习训练代码 +│ │ ├── configs/ # 训练配置 +│ │ ├── envs/ # 环境定义 +│ │ └── logs/ # 训练日志（.gitignore） +│ ├── ros_ws/ # ROS 工作空间 +│ │ ├── src/ +│ │ └── scripts/ +│ └── utils/ # 通用工具脚本 +├── 06_assets/ # 媒体资源（渲染图、演示视频等） +├── .gitignore +├── .pre-commit-config.yaml # Pre-commit 配置 +├── README.md # 项目总览 +└── 项目规范.md # 本文件 +``` + +--- + +## 3. 分支管理策略 + +### 3.1 分支结构 + +``` +main ─────●────────────●────────────────●── 最稳定，仅里程碑合并 + \ / / +main-nightly ──●────●──●────●─────────●─────────── 每日构建/集成测试 + \ \ / \ / +task- ─────●──●────────●──●──────────●──── 具体任务分支（实验/算法/feature） + \ / +task--infra ─────────●────────────────●─────── 核心代码修补分支（紧急修复） +``` + +### 3.2 分支职责 + +| 分支 | 角色 | 说明 | +|------|------|------| +| `main` | 项目所有负责人 | 最保守，只合并经过充分验证的里程碑版本。每次合并应为 **no-ff**（保留合并记录）。 | +| `main-nightly` | 主要维护人员 | 日常集成测试目标。任务分支达标后先合入此分支，稳定后再合入 `main`。 | +| `task-` | 具体任务开发者 | 自己维护，主要用于 task 配置和实验记录。**只允许修改对应子目录内的文件**。 | +| `task--infra` | 任务开发者（极端情况） | 当必须修改 `main-nightly` 核心代码才能跑通当前训练时使用，快速验证后合入 `main-nightly`。 | + +### 3.3 分支操作规则 + +1. **`main` 分支**：禁止直接推送。只能通过 Pull Request 从 `main-nightly` 合并，且必须经过 Code Review。 +2. **`main-nightly` 分支**：原则上禁止直接推送。任务分支通过 PR 合入，需经过基本验证。 +3. **`task-*` 分支**：从 `main-nightly` 创建，开发者自行推送。 +4. **`task-*-infra` 分支**：从 `main-nightly` 创建，只包含核心代码改动，**不允许包含任何 task 配置文件**，合入后立即删除。 +5. **配置代码与逻辑代码分离**：训练 config 文件和核心逻辑代码必须在不同的分支维护。只允许 config 分支从 logic 分支 merge。在里程碑之前，logic 分支不吸收任何 config 分支改动。 + +--- + +## 4. 提交（Commit）规范 + +### 4.1 Commit Message 格式 + +``` +[tag] 一句话描述（不超过 72 字符） + +（空一行后可补充详细说明，例如改动动机、注意事项等） +``` + +### 4.2 标签规则 + +| 标签 | 含义 | 示例 | +|------|------|------| +| `[add]` | 新增功能/文件 | `[add] 四足逆运动学求解器` | +| `[update]` | 修改已有功能 | `[update] 优化步态切换逻辑` | +| `[fix]` | 修复 Bug | `[fix] 电机 CAN 通讯超时处理` | +| `[remove]` | 删除功能/文件 | `[remove] 废弃旧版遥控器协议` | +| `[format]` | 代码格式化/重构 | `[format] 统一命名规范` | +| `[log]` | 实验记录/日志提交 | `[log] 第3轮训练结果，reward 收敛至0.85` | +| `[doc]` | 文档相关 | `[doc] 添加CAN总线协议说明` | +| `[hardware]` | 硬件相关改动 | `[hardware] PCB v1.2 修改电源走线` | +| `[mechanical]` | 机械相关改动 | `[mechanical] 大腿连杆加厚2mm` | + +### 4.3 Commit 原则 + +1. **一个 Commit 只做一件事**。如果一次改动了多个不相关的问题，必须拆分为多个 commit。 +2. **Commit Message 必须说清楚改动内容**。只看 message 就能理解改了什么，否则需要修正。 +3. **Task 配置文件和核心代码不得混在同一个 commit 中**。 +4. **未通过 Pre-commit 检查的代码不允许 commit**。 +5. **如果 commit 历史有问题，必须先修复再继续开发**。 + +--- + +## 5. 代码质量规范 + +### 5.1 Pre-commit 自动检查 + +- 使用 [pre-commit](https://pre-commit.com/) 工具实现提交前自动检查。 +- 安装：`pip install pre-commit` +- 启用：在仓库根目录执行 `pre-commit install` +- 手动运行：`pre-commit run --all-files` +- 所有检查项必须全部通过（绿色/蓝色）方可 commit。 +- `.pre-commit-config.yaml` 需包含：代码格式化（Clang-Format / Black）、Python 语法检查（Flake8 / Ruff）、YAML 检查、文件末尾换行符检查等。 + +### 5.2 代码风格 + +- **C/C++**：遵循 Google C++ Style Guide，使用 `.clang-format` 统一格式。 +- **Python**：遵循 PEP 8，使用 Black 格式化。 +- **ROS**：遵循 ROS C++/Python 编码规范。 +- **命名**： + - 文件名：小写 + 下划线（`imu_driver.cpp`） + - 类名：大驼峰（`ImuDriver`） + - 函数/变量：小写 + 下划线（`read_imu_data()`） + - 宏/常量：全大写 + 下划线（`IMU_TIMEOUT_MS`） + +### 5.3 接口变更流程 + +1. 首先尝试在现有接口定义下完成需求。 +2. 如必须修改接口，向项目负责人 + 所有使用者提交申请。 +3. 通过后，使用 **Pull Request** 标记变更过程，关联相关 Issue。 + +--- + +## 6. Pull Request 与代码审查（Code Review） + +### 6.1 PR 流程 + +1. 在 `task-*` 或 `task-*-infra` 分支上完成开发并推送。 +2. 在 Gitea 上创建 Pull Request： + - **来源分支**：`task-*` → **目标分支**：`main-nightly` + - **来源分支**：`main-nightly` → **目标分支**：`main` +3. PR 标题格式：`[tag] 简短描述`（与 commit message 一致）。 +4. PR 描述中说明：改动内容、验证方式、影响范围。 + +### 6.2 审查要求 + +- 必须由至少 1 名项目成员 Review 后方可合并。 +- 审查重点：功能正确性、接口兼容性、代码风格、是否包含无关文件。 +- 如有修改意见，PR 作者修改后重新请求 Review。 + +### 6.3 合并方式 + +- 合入 `main-nightly`：使用 **Squash Merge**（保持 nightly 历史清晰）。 +- 合入 `main`：使用 **Merge Commit (no-ff)**（保留完整分支历史）。 + +--- + +## 7. Gitea 配置 + +### 7.1 仓库设置 + +- **可见性**：私有（Private） +- **默认分支**：`main` +- **分支保护**（`main` 分支）： + - 禁止直接推送 + - 要求 PR 审查通过后才能合并 + - 要求 PR 必须基于最新 `main` + - 禁用强制推送 + +### 7.2 初始推送 + +```bash +git init +git checkout -b main +git add . +git commit -m "[init] RC_Legged 项目初始化" +git remote add origin https://git.zeitvex.com/Robocon/RC_Legged.git +git push -u origin main +``` + +--- + +## 8. 硬件测试规范 + +### 8.1 真机测试要求 + +1. **全程录像**：每次真机测试必须有独立相机全程拍摄视频。 +2. **ROS Bag 记录**：完整系统测试时必须用 ROS Bag 记录所有 message 数据。 + - 使用 `ros2 bag record -s mcap -o /topic1 /topic2 ...` + - 推荐编写 `rosbag.sh` 脚本自动记录所有传感器数据。 + - 所有与项目相关的电脑需安装 [Foxglove Studio](https://foxglove.dev/) 用于查看 bag。 +3. **可视化配置**：所有 ROS 系统必须配置 RViz + `robot_state_publisher` + `joint_state_publisher`。 + +### 8.2 急停方案 + +所有真机测试脚本必须包含： +- 除 `Ctrl+C` 外的独立急停机制（如遥控器急停按钮）。 +- 急停触发后立即进入 **Damping Mode**，无任何等待延迟。 +- 推荐方案：控制程序监听遥控器急停信号，触发后立即终止程序。 + +--- + +## 9. .gitignore 示例 + +```gitignore +# 编译产出 +build/ +devel/ +install/ +*.o +*.elf +*.hex + +# Python +__pycache__/ +*.pyc +*.pyo +.venv/ +venv/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# 训练产出 +05_software/rl_training/logs/ +05_software/rl_training/checkpoints/ +wandb/ + +# ROS +*.bag +*.mcap + +# 系统 +.DS_Store +Thumbs.db + +# 机械 +*.sldprt +*.sldasm +*.step +*.stp +``` + +--- + +## 10. 项目里程碑工作流 + +``` +[日常开发] + task-xxx 分支开发 → 提交 → 推送 → PR → Code Review → 合入 main-nightly + +[里程碑发布] + main-nightly 经过充分测试 + → 创建 PR: main-nightly → main + → 项目负责人 Review + → 合入 main + → 创建 Git Tag: v1.0.0, v1.1.0, ... +``` + +--- + +## 11. 参考项目 + +| 项目 | 类型 | 地址 | +|------|------|------| +| EDULITE_A3 | 四足机器人 | `00_reference/EDULITE_A3/` | +| OpenDog | 四足机器人 | `00_reference/open-dog/` | +| reBot-DevArm | 机械臂 | `00_reference/reBot-DevArm/` | + +--- + +*本规范参考上述开源项目及行业最佳实践编写，随项目推进持续完善。*