贡献与文档维护¶
建议先用最小模型或现有示例复现问题，再修改对应层。控制行为改变需要说明对时序、限位、参考采样与停止行为的影响；文档修改需要保证示例与当前接口一致。
开发环境¶
python -m venv .venv
source .venv/bin/activate
CMAKE_BUILD_PARALLEL_LEVEL=2 python -m pip install -e '.[test,docs,ruckig]'
需要完整可选测试时安装 .[test,mujoco,pinocchio,ruckig,docs]。修改 C++ 或绑定后重新安装，避免误测旧扩展。
源码导航¶
| 路径 | 职责 |
|---|---|
include/servo_py/servo.hpp |
C++ 公共类型与扩展接口 |
cpp/servo.cpp / cpp/solvers.cpp |
控制、约束、DLS 与 QP |
cpp/kinematics.cpp |
原生串联运动学 |
cpp/bindings.cpp |
Python 绑定与回调 |
src/servo_py/api.py |
Python 类型与调用入口 |
src/servo_py/ik.py / smoothing.py |
位置 IK 适配与可选 jerk 后端 |
src/servo_py/runtime.py / recording.py |
周期/设备与记录工具 |
tests/ / examples/ |
行为验证与可运行示例 |
docs/ / scripts/check_docs.py |
文档及一致性检查 |
.github/workflows/release.yml / scripts/check_release.py |
manylinux 构建、产物检查和 Trusted Publishing |
scripts/smoke_wheel.py |
在临时目录验证已安装示例、模型及命令行入口 |
选择相关验证¶
| 改动 | 检查 |
|---|---|
| 内核或模型 | python -m pytest -q，以及 独立 C++ 构建 |
| Panda 控制 | python -m pytest -q tests/test_mujoco_panda.py |
| 可选 IK/平滑/设备 | 对应 tests 模块，并安装所需 extras |
| 教程、导航、参数说明 | 以下文档验证流程 |
| 发布/打包元数据 | 构建 wheel/sdist，执行 twine check --strict、安装后的 scripts/smoke_wheel.py；完整流程见PyPI 发布 |
测试应检查有意义的行为、数值基准或失败路径；避免只重复实现细节。历史性能或仿真结果不要直接改写成新结果，补充新的条件和记录。
本地预览与文档验证¶
python scripts/check_docs.py
python scripts/check_docs.py --run
python -m mkdocs build --strict
python -m mkdocs serve
打开 serve 输出的本地地址，检查导航、搜索与代码复制。静态输出在 site/，不提交构建产物。公开文档站发布在 openghz.github.io/servopy。
检查脚本会核对 Markdown 本地路径/锚点、公共 API、配置默认值、flags 与 CLI 参数，并可执行明确标注的完整 Python 示例。它不启动真实设备、不自动执行文档中的任意 shell 命令，也不把接入片段当作完整程序。
Documentation 工作流 在 PR 和 main 推送时执行示例检查与严格构建，使用 Linux / Python 3.12。main 上的检查通过后，工作流上传 site/ 产物并通过 github-pages 环境部署到 GitHub Pages；PR 与从其他分支手动触发的运行只检查，不发布。也可在 Actions 中选择 Documentation → Run workflow，并使用 main 手动重新发布。
GitHub Pages 发布维护¶
仓库 Settings → Pages → Build and deployment 的 Source 使用 GitHub Actions。站点根地址由 mkdocs.yml 的 site_url 定义；更改账号或仓库名后，同时更新 README 和 pyproject.toml 中的文档地址。
发布权限仅授予 deploy job（pages: write 与 id-token: write），构建 job 保持仓库只读。失败时先查看 Documentation 的运行记录：检查或构建失败会阻止发布；若 Configure GitHub Pages 提示找不到站点，确认已启用上述发布来源。修复后重新运行失败的 job 或再次推送 main。无需提交 site/ 或维护 gh-pages 分支。
文档写法¶
- README 负责项目定位、第一条可运行命令和任务入口。定位统一为“实时关节与笛卡尔伺服控制”：先解释持续更新目标、实际反馈与逐周期输出，再介绍求解器、约束和平滑。参数细节放参考页。
- 教程说明目标、前置环境、完整操作、预期结果与下一步。需要外部对象的代码明确标为接入片段。
- 默认值只在配置参考集中维护；新增公共名称时同步 API 和诊断页。
- 完整可运行 Python 块前加
<!-- runnable: unique-name -->，用检查脚本执行。示例默认从仓库根目录运行。 - 保持现有页面入口可访问；需要拆分时保留导览，避免旧链接失效。
- 写清观测环境、参考/反馈、仿真/实机区别；不增加未经验证的性能、兼容性、发布或 CI 状态徽章。
- 版本要求与构建配置保持一致，明确最低版本、上限或精确锁定；区分 C++ 语言标准和编译器版本。验证记录保留实际测试版本，不把单个测试环境写成唯一可用环境，也不把允许安装的版本范围写成已全部验证。
项目展示名称写作 ServoPy；Python 导入名 servo_py、发行包名 servo-py 和源码路径使用实际技术名称。README.md 为英文默认入口，README.zh-CN.md 为中文全文，更新主要内容时保持两页对应；README.en.md 保留为旧链接入口。语言切换单独放在顶部，功能导航放在品牌区下方。
Logo 位于 docs/assets/brand/：logo-light.svg 与 logo-dark.svg 用于 README 的 <picture>，mark.svg 用作文档站图标。使用仓库内的原生 SVG，无需外部图片服务；标题和替代文本同样使用 ServoPy。
文档结构参考¶
实时控制的介绍顺序参考 MoveIt Realtime Servo：先说明持续控制与应用场景，再介绍控制接口和支持功能。ServoPy 的功能与实时性边界以本项目实现、执行契约和验证记录为准。
本轮结构整理参考了 Ruckig 的入门示例、Pink 的任务与示例入口、Pinocchio 的学习资源导航，以及 MuJoCo 的概念与接口分层。内容按 Diátaxis 的学习、操作、参考、解释四种需求组织；技术说明与代码均以本仓库实际实现为准。
提交变更¶
问题报告应包含最小复现、环境、期望与实际结果。PR 描述先说明问题与行为变化，再列相关验证及未覆盖范围。文档与代码更新应在同一变更中完成；不要把未执行的验证写成已通过。
项目许可证与上游资产来源保留在仓库根目录的 LICENSE、NOTICE 和 LICENSES 中。新增依赖或模型资产时一并说明来源与许可证。