LeRobot 贡献指南：从开发环境搭建、代码质量门禁到提交 PR 的完整开源工作流

LeRobot 贡献指南：从开发环境搭建、代码质量门禁到提交 PR 的完整开源工作流

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

LeRobot 是一个面向机器人具身智能的开源项目，致力于通过端到端学习降低机器人 AI 的门槛。本项目仓库覆盖策略模型（src/lerobot/policies/）、机器人驱动（src/lerobot/robots/）、仿真环境（src/lerobot/envs/）、遥操作（src/lerobot/teleoperators/）等完整技术栈。本文基于仓库根目录的 CONTRIBUTING.md 整理成完整贡献指南，系统讲解贡献方式、开发环境搭建、代码质量检查、文档规范、测试运行以及 Issue/PR 提交流程，并结合仓库内的 .pre-commit-config.yaml、pyproject.toml、Makefile 和 CI 配置等源码级细节，帮助你快速融入 LeRobot 的协作流程。

贡献方式：代码不是唯一途径

LeRobot 欢迎所有人参与贡献，并且明确强调代码不是帮助社区的唯一方式——回答问题、帮助他人、完善文档同样极具价值。核心的贡献方式包括：

如果你不确定从哪里开始，可以加入项目社区 Discord 频道寻求指引，也可以从标记为 "good first issue" 类的简单问题入手。

开发环境搭建

1. Fork 与 Clone

在代码托管平台 fork 上游仓库，然后克隆你的 fork 并关联上游：

git clone <your-fork-url>/lerobot.git cd lerobot git remote add upstream <upstream-repo-url>.git

添加upstream远端是保持本地代码与上游同步的基础：提交 PR 前需要从upstream/main上 rebase，而不是直接在main分支上开发（详见下文 PR 规范）。

2. 环境安装与开发依赖

环境搭建与源码安装请参考仓库内的 安装指南，其中详细介绍了创建虚拟环境、安装依赖及从源码安装 LeRobot 的步骤。

针对贡献者，仓库在 pyproject.toml 中提供了专门的开发依赖分组，例如devextra 包含pre-commit、mypy、ruff等工具（见 pyproject.toml 中[project.optional-dependencies]的dev定义），testextra 包含pytest、pytest-timeout、pytest-cov等测试工具。开发时建议安装对应 extra：

uv sync --extra dev --extra test

同时注意仓库根目录的 Makefile 中已内置了对uv的自动检测：若机器上安装了uv且存在.venv虚拟环境，Makefile 会优先使用.venv/bin/python执行后续命令。

3. 测试数据与 git-lfs

运行测试前需要先获取测试工件（如小型数据集、模型 checkpoint），LeRobot 使用git-lfs管理这些大文件：

git lfs install git lfs pull

执行git lfs pull后，tests/fixtures/等目录下由 LFS 托管的数据文件才会被真实拉取到本地，否则相关测试可能因缺少工件而失败。

代码质量门禁：pre-commit

LeRobot 用 pre-commit 在每次提交前自动执行代码风格与静态检查。安装 git hooks 后，每次git commit都会自动触发检查，未通过的改动会被拦截：

pre-commit install

需要手动对所有文件执行检查时（例如提交 PR 前整体确认）：

pre-commit run --all-files

仓库实际的检查链构成

.pre-commit-config.yaml 定义了完整的检查链，开发者在本地运行的和 CI 中执行的是同一套配置，主要包括：

• 元检查（meta）：check-useless-excludes、check-hooks-apply，确保 hooks 配置本身有效；
• 通用质量（pre-commit-hooks v6.0.0）：check-added-large-files（限制单文件不超过 1024 KB）、debug-statements（拦截调试断点）、check-merge-conflict（检查合并冲突标记）、check-yaml/check-toml、end-of-file-fixer（文件末尾换行）、trailing-whitespace（行尾空白）；
• Ruff（v0.14.1）：ruff-format（格式化）与ruff（Lint，带--fix --exit-non-zero-on-fix，自动修复失败项并让检查失败以便提交修复后的版本）；
• typos（v1.38.1）：拼写检查，--force-exclude跳过被排除路径；
• pyupgrade（v3.21.0）：按--py312-plus升级到 Python 3.12+ 语法；
• Prettier：对 Markdown / MDX 文档格式化（--prose-wrap=preserve），并排除了src/lerobot/templates/（Jinja2 模板含{% %}标签）与docs/source/api/（[[autodoc]]指令）以免误改；
• 安全类：gitleaks（密钥泄露检测）、zizmor（GitHub Actions 配置安全审计）、bandit（Python 安全扫描，配置见 pyproject.toml[tool.bandit]）；
• mypy（v1.19.1）：静态类型检查，读取pyproject.toml配置，排除examples|benchmarks|tests目录。注意：目前 mypy 在[tool.mypy]中处于"按模块渐进启用"状态（详见 pyproject.toml 中相关注释），并非全量严格模式。

对应地，pyproject.toml 中[tool.ruff]也设定了行宽 110、目标 Python 3.12，Lint 规则启用了E/W/F/I/B/C4/T20/N/UP/SIM/D等大类（其中D为 pydocstyle docstring 检查），并针对__init__.py、测试、示例及各源码模块做了per-file-ignores细化。

Docstring 与文档规范

LeRobot 的API 参考文档是由src/lerobot/中的 docstring 自动生成的（见 docs/source/api/），因此新增或修改任何公共接口时，docstring 质量直接影响公开文档质量，且会被 CI 检查。

• 格式标准：必须遵循仓库内的 docstring 编写标准（Google 风格），该标准定义了每个参数、返回值的书写格式，由渲染器解析并在 CI 中校验；
• 覆盖率门禁：pyproject.toml 中[tool.interrogate]设置了 docstring 覆盖率门槛（当前fail-under = 52），并明确这是"棘轮（ratchet）"而非最终目标——覆盖率只能上升，最终目标是 100%；
• 参数一致性：通过 Makefile 中的check-docstrings目标（调用 utils/check_docstrings.py 与 utils/check_config_docstrings.py）校验文档化参数与函数签名一致；
• Doctest 示例：docstring 中的可运行示例会被作为 doctest 执行，文件清单维护在 utils/documentation_tests.txt，通过make doctest运行；硬件相关、需要 CUDA 的示例由 src/lerobot/utils/doctest_utils.py 按内容跳过，CI 中会设置SKIP_HARDWARE_DOCTEST=1与SKIP_CUDA_DOCTEST=1两个环境变量。

日常开发中可用以下命令检查与自动修复 docstring 问题：

make check-docstrings # 只检查 make fix-docstrings # 自动修复 make doctest # 运行 docstring 中的示例 make check-doctest-list # 校验 doctest 清单排序与路径有效性

运行测试

LeRobot 使用pytest作为测试框架（见 pyproject.toml[tool.pytest.ini_options]，并定义了multigpu、multigpu_heavy等标记）。运行完整测试套件（可能需要安装 extra 依赖）：

pytest -sv ./tests

开发阶段只针对某个功能运行指定测试文件更高效：

pytest -sv tests/test_specific_feature.py

测试目录结构与端到端测试

仓库的tests/目录按源码模块镜像组织，便于定位：tests/policies/（各策略测试，如 pi0、act、diffusion、rtc）、tests/datasets/、tests/robots/、tests/teleoperators/、tests/processor/、tests/envs/等。测试夹具集中在tests/fixtures/，硬件相关测试依赖tests/mocks/中的串口与电机 mock。

除单元测试外，Makefile 还提供了覆盖 ACT、Diffusion、TDMPC、SmolVLA 等策略的端到端训练/评估冒烟测试，例如：

make test-end-to-end # 全部端到端（默认 DEVICE=cpu） make test-act-ete-train # 仅 ACT 训练冒烟测试 make test-act-ete-eval # 仅 ACT 评估

这些目标会调用lerobot-train/lerobot-eval命令行工具，使用tests/outputs/作为输出目录、关闭 wandb 与 Hub 上传，可在 CI 与本地快速验证核心链路。另有make annotation-e2e用于注解流水线的端到端冒烟测试（使用 stub VLM，无需真实模型权重或 GPU）。

提交 Issue 与 Pull Request

Issue：使用模板

提交 Issue 时请使用模板填写必填字段，仓库内的 bug-report.yml 定义了结构化表单，包含：

• Ticket 类型：Bug 报告 / 功能请求 / 技术问题 / 维护与文档；
• 环境与系统信息：Bug 或技术问题请先运行lerobot-info命令并粘贴输出（版本、OS、Python 版本等）；
• 描述：清晰说明问题现象或提案目标；
• 复现上下文：提供代码片段与复现步骤（使用代码块）；
• 日志：相关的报错日志或堆栈；
• 检查清单：是否已搜索过重复 ticket、是否基于最新main分支、是否排除环境特异性问题。

Pull Request：模板与规范

提交 PR 前注意以下几点：

1. 分支规范：在upstream/main上 rebase，使用描述性分支名，不要在main上直接开发；
2. 本地验证：提交前运行pre-commit与本地测试；
3. 使用模板：仓库的 PULL_REQUEST_TEMPLATE.md 要求填写：简短命令式标题（如fix(robots): handle None in sensor parser）、变更动机与设计权衡、关联 Issue、具体变更说明（含破坏性变更与迁移步骤）、测试方式（新增测试用pytest -q tests/ -k <keyword>运行）、以及合并前检查清单（Lint 通过、本地测试通过、文档已更新、CI 绿色等）。

仓库强制要求社区互审机制（Community Review Policy）：每位贡献者在自己的 PR 获得关注前，需要先评审至少一位其他贡献者开放的 PR，并在 PR 模板中填写已评审的 PR 链接。这是为了扩大团队评审产能、让每个人的代码更快合并。完成互审后，LeRobot 团队成员会评审你的贡献。

CI 工作流总览

PR 提交后，.github/workflows/ 下的自动化流水线会接管验证，主要包括：

其中 quality.yml 的 doc-checks 任务与本地make doctest/make check-docstrings一一对应，确保"本地能过、CI 必过"。

小结

贡献 LeRobot 的完整闭环是：Fork → 按安装指南搭建环境 → 在独立分支开发 → 本地跑 pre-commit 与 pytest → 补齐 docstring 并确保覆盖率不下降 → 提交 PR（模板 + 社区互审）→ 等待团队评审。整个过程由统一的配置文件（.pre-commit-config.yaml、pyproject.toml）、Makefile 目标与 CI 流水线层层把关，你只需要遵循 CONTRIBUTING.md 与 docstring 标准，即可顺畅地参与到 LeRobot 的机器人学习生态建设中。

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot