发布与版本

​

支持的 Python 版本

​

版本号规则

主版本.次版本.补丁版本[-预发布标识]

示例:
0.1.0   - 初始发布
0.1.1   - Bug 修复
0.1.2   - 另一个 Bug 修复
0.2.0   - 新功能，向后兼容
1.0.0   - 稳定 API，与 0.x 有破坏性变更
1.1.0a1 - Alpha 预发布
1.1.0b1 - Beta 预发布
1.1.0rc1 - 候选版本

​

版本类别

​

安装渠道

​

PyPI（生产）

# 最新稳定版
pip install motorbridge

# 特定版本
pip install motorbridge==0.4.1

# 升级
pip install --upgrade motorbridge

​

TestPyPI（预发布）

# 从 TestPyPI 安装
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1a1

​

Git 安装

# 从 Git 安装
pip install git+https://github.com/tianrking/motorbridge@v0.4.1

# 安装特定分支
pip install git+https://github.com/tianrking/motorbridge@main

​

检查已安装版本

​

命令行

# 使用 pip
pip show motorbridge

# 使用 Python CLI
motorbridge-cli -v

# 使用 Rust CLI
motor_cli -v

# 使用 Python
python3 -c "import importlib.metadata; print(importlib.metadata.version('motorbridge'))"
python3 -c "import motorbridge; print(motorbridge.get_version())"

​

代码中检查

import motorbridge

import importlib.metadata
print(f"motorbridge 版本: {importlib.metadata.version('motorbridge')}")
print(f"motorbridge API 版本: {motorbridge.get_version()}")

​

升级策略

​

保守升级

# 当前: 任意旧 0.x 版本
# 升级到最新稳定版: 0.4.1
pip install --upgrade motorbridge

# 或特定补丁
pip install motorbridge==0.4.1

​

早期采用者

# 开发环境
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1b1

# 测试代码
python3 -m pytest tests/

# 生产环境保持稳定
pip install motorbridge==0.4.1

​

固定版本

# requirements.txt
motorbridge==0.4.1

# 允许补丁更新，阻止次版本/主版本变更
motorbridge>=0.4.1,<0.5.0

​

API 稳定性

​

版本 0.x（当前）

• 次版本之间 API 可能变更
• 破坏性变更在发布说明中记录
• 建议固定版本

​

版本 1.0+（未来）

• 语义化版本保证
• 破坏性变更只在主版本中
• 移除前有弃用警告

​

变更日志

​

v0.4.1

• 新增 ABI 元数据查询：motor_abi_version() 和 motor_abi_capabilities_json()
• 新增 Python helper：motorbridge.abi_version() 和 motorbridge.abi_capabilities()
• 新增 C++ helper：motorbridge::abi_version() 和 motorbridge::abi_capabilities_json()
• C++ RobStride wrapper 方法补齐到 Python binding 的公开能力
• 新增 bindings/api_surface.json，作为 ABI、Python、C++ 和文档的接口对齐清单
• Python、Rust workspace、C++ 元数据升级到 0.4.1

​

v0.4.0

• 修复 Windows 下 Damiao dm-serial 通过 ws_gateway 扫描整臂时的串口会话争用
• 新增 damiao_state_many，用于浏览器上位机批量刷新 Damiao 多关节状态
• Damiao gateway 状态快照新增 motor_id、feedback_id、model
• Damiao 状态返回前会请求新鲜反馈，减少 pos/vel/torq 旧缓存
• Python、Rust workspace、C++ 元数据升级到 0.4.0

​

v0.3.9

• 修正 RobStride 统一 request_feedback() 语义，改为非阻塞 no-op
• 明确 RobStride 连通性检查使用 robstride_ping()，新鲜位置/速度使用类型化参数读取
• Python、Rust workspace、C++ 元数据升级到 0.3.9

​

v0.3.8

• 新增 RobStride pos-vel-pp 和 pos-vel-csp 控制路径
• 新增 PP/CSP 的 C ABI、Python binding、Python CLI、Rust CLI 支持
• 移除高频路径中 RobStride 参数写默认等待 ack 的阻塞
• Python、Rust workspace、C++ 元数据升级到 0.3.8

​

v0.3.7

• 修复 Windows PCAN RobStride 扫描，每次只探测一个 host/feedback ID
• 修复 gateway RobStride 扫描，按请求精确 host ID 探测并在扫描前释放活跃会话
• 新增 gateway capabilities 和 MOTORBRIDGE_WS_DEBUG=1 诊断日志
• Python、Rust workspace、C++ 元数据升级到 0.3.7

​

v0.3.5

• ABI controller 和 motor handle 增加 per-handle 锁，公共符号和函数签名保持兼容
• Python binding 增加关闭后调用守卫，close() 后继续调用会抛 CallError，不会把空指针传入 ABI
• CoreController 增加 drop-time 轮询清理，用户忘记 shutdown() 或 close_bus() 时后台接收线程也会停止
• Python CLI 拆成 motorbridge.cli 包结构，同时保留 motorbridge-cli、python -m motorbridge 和旧式 flat run 参数
• 优化 RobStride 扫描效率，补充 RobStride pos-vel 有效参数说明，并用回归测试锁定 MIT 参数编码

​

v0.3.4

• RobStride 保存参数时接受有效设备回复作为保存命令响应，不再只接受 status ack
• 修复 Damiao in-process ensure_mode() 超时行为
• 修复 WS Gateway id_set 传输选择，--transport dm-serial 在 macOS 下不会再尝试加载 PEAK/PCAN
• 增加更严格的 fmt、clippy 和测试发布验证

​

v0.3.3

• 新增统一版本查询：Python motorbridge.__version__、motorbridge.get_version()、motorbridge-cli -v 和 Rust motor_cli -v
• Python CLI 关闭长选项缩写，robstride-write-param --mode save 这类错误参数会直接报错，不会误解析成 --model save
• Python robstride-write-param 和 damiao-write-param 新增统一 --store 1
• Rust CLI 对齐 RobStride/Damiao 写参保存语义
• RobStride type 22 保存会发送官方 payload 并等待状态 ACK

​

v0.3.2

• RobStride 故障帧只更新故障缓存，不再污染最新运动状态
• Python binding/CLI 可查询最近一次厂商故障码，同时保留最后一帧真实状态

​

v0.3.1

• 新增 ABI/Python 详细故障状态访问接口
• 改进 RobStride 过温/故障诊断链路

​

v0.2.9

• 新增 RobStride host_id 精确 ABI：motor_handle_robstride_ping_host_id 和 motor_handle_robstride_get_param_f32_host_id
• 新增 Python 包装方法：robstride_ping_host_id(...) 和 robstride_get_param_f32_host_id(...)
• 统一校验 RobStride motor_id / device_id 为 1..255，feedback_id / host_id 为 0..255
• Rust 与 Python 的 RobStride 扫描现在会精确探测每个 --feedback-ids host_id
• Canonical Mintlify 文档迁移到同级 motorbridge-docs 仓库

​

v0.2.5

• Python CLI 新增 id-set --vendor robstride，支持 RobStride device_id 更新
• Rust/Python RobStride 扫描默认 host_id 候选统一为 0xFD,0xFF,0xFE,0x00,0xAA

​

v0.2.3

• 重构 ABI FFI 层，减少 controller/motor 分发重复代码
• 合并厂商参数 FFI 入口
• 对齐 core、厂商控制器、Python binding 和 websocket gateway 的运行时/控制路径稳健性修复

​

弃用政策

1. 公告： 功能在发布说明中标记为弃用
2. 警告： 添加运行时弃用警告
3. 宽限期： 至少一个次版本
4. 移除： 在下一个主版本/次版本中移除

# 弃用警告示例
import warnings

def old_function():
    warnings.warn(
        "old_function 已弃用，请使用 new_function",
        DeprecationWarning,
        stacklevel=2
    )
    return new_function()

​

发布检查清单

​

1. 更新版本号

# 更新 bindings/python/pyproject.toml 中的 [project].version
version = "0.4.1"

​

2. 更新变更日志

• 记录所有变更
• 注明破坏性变更

​

3. 打标签

git tag v0.4.1
git push origin v0.4.1

​

4. 构建包

MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
python -m build

​

5. 上传到 TestPyPI

twine upload -r testpypi dist/*

​

6. 验证安装

pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1
python3 -m pytest tests/

​

7. 上传到 PyPI

twine upload dist/*

​

重要规则

​

上传失败处理

# 错误：尝试重新上传同一版本
twine upload dist/motorbridge-0.4.1.tar.gz
# 错误: 文件已存在

# 解决方案：增加版本号
# 将共享版本源更新到下一个补丁版本
# 重新构建并上传

​

CI/CD 集成

​

GitHub Actions 示例

name: Publish

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: |
          MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
          MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
          python -m build

      - name: Publish to PyPI
        run: twine upload dist/*
        env:
          TWINE_TOKEN: ${{ secrets.PYPI_TOKEN }}

​

版本兼容性表

​

下一步

• 安装指南 - 安装和验证
• 故障排除 - 常见问题
• 变更日志 - 发布历史