LeRobot 贡献指南从开发环境搭建、代码质量门禁到提交 PR 的完整开源工作流【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotLeRobot 是一个面向机器人具身智能的开源项目致力于通过端到端学习降低机器人 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 欢迎所有人参与贡献并且明确强调代码不是帮助社区的唯一方式——回答问题、帮助他人、完善文档同样极具价值。核心的贡献方式包括贡献类型说明在仓库中的典型落点修复问题Fixing issues解决 bug 或改进既有代码tests/下新增回归测试、修复src/lerobot/下的缺陷新功能New features开发新能力在src/lerobot/各模块中实现新功能扩展Extend实现新的模型/策略、机器人或仿真环境并向 Hugging Face Hub 上传数据集新策略放入src/lerobot/policies/、机器人放入src/lerobot/robots/、仿真环境放入src/lerobot/envs/文档Documentation改进示例、指南和 docstring指南位于 docs/source/docstring 位于src/lerobot/源码中反馈Feedback提交 bug 或新功能需求的 ticket使用.github/ISSUE_TEMPLATE/bug-report.yml模板如果你不确定从哪里开始可以加入项目社区 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等测试工具。开发时建议安装对应 extrauv sync --extra dev --extra test同时注意仓库根目录的 Makefile 中已内置了对uv的自动检测若机器上安装了uv且存在.venv虚拟环境Makefile 会优先使用.venv/bin/python执行后续命令。3. 测试数据与 git-lfs运行测试前需要先获取测试工件如小型数据集、模型 checkpointLeRobot 使用git-lfs管理这些大文件git lfs install git lfs pull执行git lfs pull后tests/fixtures/等目录下由 LFS 托管的数据文件才会被真实拉取到本地否则相关测试可能因缺少工件而失败。代码质量门禁pre-commitLeRobot 用 pre-commit 在每次提交前自动执行代码风格与静态检查。安装 git hooks 后每次git commit都会自动触发检查未通过的改动会被拦截pre-commit install需要手动对所有文件执行检查时例如提交 PR 前整体确认pre-commit run --all-files仓库实际的检查链构成.pre-commit-config.yaml 定义了完整的检查链开发者在本地运行的和 CI 中执行的是同一套配置主要包括元检查metacheck-useless-excludes、check-hooks-apply确保 hooks 配置本身有效通用质量pre-commit-hooks v6.0.0check-added-large-files限制单文件不超过 1024 KB、debug-statements拦截调试断点、check-merge-conflict检查合并冲突标记、check-yaml/check-toml、end-of-file-fixer文件末尾换行、trailing-whitespace行尾空白Ruffv0.14.1ruff-format格式化与ruffLint带--fix --exit-non-zero-on-fix自动修复失败项并让检查失败以便提交修复后的版本typosv1.38.1拼写检查--force-exclude跳过被排除路径pyupgradev3.21.0按--py312-plus升级到 Python 3.12 语法Prettier对 Markdown / MDX 文档格式化--prose-wrappreserve并排除了src/lerobot/templates/Jinja2 模板含{% %}标签与docs/source/api/[[autodoc]]指令以免误改安全类gitleaks密钥泄露检测、zizmorGitHub Actions 配置安全审计、banditPython 安全扫描配置见 pyproject.toml[tool.bandit]mypyv1.19.1静态类型检查读取pyproject.toml配置排除examples|benchmarks|tests目录。注意目前 mypy 在[tool.mypy]中处于按模块渐进启用状态详见 pyproject.toml 中相关注释并非全量严格模式。对应地pyproject.toml 中[tool.ruff]也设定了行宽 110、目标 Python 3.12Lint 规则启用了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_DOCTEST1与SKIP_CUDA_DOCTEST1两个环境变量。日常开发中可用以下命令检查与自动修复 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 # 全部端到端默认 DEVICEcpu 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 RequestIssue使用模板提交 Issue 时请使用模板填写必填字段仓库内的 bug-report.yml 定义了结构化表单包含Ticket 类型Bug 报告 / 功能请求 / 技术问题 / 维护与文档环境与系统信息Bug 或技术问题请先运行lerobot-info命令并粘贴输出版本、OS、Python 版本等描述清晰说明问题现象或提案目标复现上下文提供代码片段与复现步骤使用代码块日志相关的报错日志或堆栈检查清单是否已搜索过重复 ticket、是否基于最新main分支、是否排除环境特异性问题。Pull Request模板与规范提交 PR 前注意以下几点分支规范在upstream/main上 rebase使用描述性分支名不要在main上直接开发本地验证提交前运行pre-commit与本地测试使用模板仓库的 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.ymlLint / 格式 / 静态分析pre-commit 全量检查 文档检查doctest、docstring 参数一致性、interrogate 覆盖率门禁fast_tests.yml/full_tests.yml快速与完整测试套件latest_deps_tests.yml使用最新依赖版本验证兼容性benchmark_tests.yml基准测试libero、metaworld 等仿真环境见docker/下的对应 Dockerfiledocker_publish.yml镜像发布及多 GPU 训练测试issue_labeler.yml/pr_labeler.ymlIssue/PR 自动打标签stale.yml/security.yml过期 Issue 清理与安全扫描其中 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考