开发规范
本页汇总了贡献者在 LAV2 中开发时应遵循的工程规范。命令级工作流请结合 工具与验证 阅读，任务跟踪规则请结合 Backlog 与内部文档 阅读。
必须遵循的贡献者工作流
每位贡献者都应使用 工具与验证 中说明的仓库 hook 工作流。实际要求是：
- 在日常开发前安装本地
pre-commit或prekhooks； - 确保待提交改动通过仓库配置的 lint 与格式检查；
- 使用 Conventional Commit 风格的提交信息，例如
feat(docs): add development conventions page。
这样做的目的不是增加流程负担，而是在评审前提供稳定的质量门槛，并让提交历史对 changelog、发布说明和后续排障保持可读。
Backlog 的使用
当工作不再是纯机械性的小改动时，贡献者应使用 Backlog.md。详细流程见 Backlog 与内部文档，但实际规则很简单：
- 开始前先搜索是否已有对应任务；
- 非平凡实现工作应挂到任务上；
- 实现计划、范围变化和验证记录应写回该任务。
这样可以把开发过程放在统一位置，方便不同贡献者或编码代理之间交接。
Docstring 与代码注释
对外可见的 Python 代码应使用 Google Style docstrings。对于控制器、动力学、任务配置以及会出现在 API 文档中的辅助函数，这一点尤其重要。
目前仓库的 lint 配置还不能严格检查 Google Style 的参数段落，因此这一规则暂时没有被完全自动化约束。即便如此，新增代码或经过较大修改的代码仍应按这一风格书写，以保证生成的 API 文档保持一致和可读。
行内注释应谨慎使用。注释应解释设计意图、不变量或不明显的约束，而不是重复代码字面含义。
仓库开发模型
LAV2 采用 monorepo 结合 GitHub Flow 风格的开发方式。
- 包源码、任务、脚本、资产与文档位于同一个仓库中；
- 贡献者应从
main分出有明确范围的分支，并通过评审合入； - 改动范围应尽量保持可控，使代码、文档和验证可以在同一次变更中一起落地。
这种模式适合 LAV2，因为仿真栈、控制器、任务与文档经常需要跨包协同演进。
模块导出策略
除非为了调用便利确实需要提供包级便捷入口，否则应避免使用宽泛的 __all__ 导出。
优先使用显式导入和显式重导出列表，因为这样可以：
- 让公共接口更容易审计；
- 避免后续添加辅助符号时公共命名空间无意扩张；
- 让静态分析、文档生成与重构行为更可预测；
- 减少隐式引入导入循环或导入期副作用的概率。
如果某个模块或包确实需要提供整理过的便捷 API，也应只重导出那一小组稳定且明确面向外部的符号。
模块设计风格
模块应保持小而专、职责清晰且易于理解。相比混合多种职责的大型工具模块，更推荐 KISS 风格的拆解方式。
对于一组同质化实现，应使用抽象基类或少量共享接口来保持风格一致。这也是当前控制器和动力学模块已经采用的模式，共享基类可以帮助保持命名、方法签名和数据布局的一致性。
一个实用的判断标准是：
- 一个模块应只解决一个连贯问题；
- 只有在能让设计更清晰时，才把共同行为抽到基类或辅助函数；
- 同级实现之间应体现行为差异，而不是命名和调用方式差异。
依赖管理
依赖应保持隔离、确定且易于复现。
- 使用
uv负责安装、锁定、同步以及整个开发周期中的命令执行； - 按用途拆分 dependency groups，例如文档、开发工具和可选运行时集成；
- 对后端专属或框架专属集成优先使用 optional dependencies，避免基础安装过重；
- 依赖声明发生变化时同步更新 lockfile。
这样可以帮助贡献者稳定复现本地环境，也能让框架相关集成与核心包保持解耦。
接口与一致性要求
当某个子系统同时存在 NumPy 与 Torch 实现时，除非有明确记录的后端特定原因，否则应尽量保持接口一致。名称、shape 与语义的一致性对于调试、训练后端接入和后续并行实现都很重要。
同样地，贡献者应优先复用 VehicleParams 这类已有的统一配置对象，而不是引入新的硬编码常量。
文档维护
如果某项改动影响了公开工作流、入口命令、依赖路径或贡献者日常流程，应在同一次改动中更新相关文档。对于大多数工作流变更，这通常意味着同步更新：
docs/下的公开文档；- 类似 工具与验证 的贡献者工作流说明；
- 当内部工程过程仍依赖它们时，更新
backlog/docs/下的相关参考资料。
把文档更新和实现改动放在同一次提交中，可以减少文档漂移并提升评审可靠性。