> ## Documentation Index
> Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 发布与版本

<mintly-toc>
  本指南介绍 motorbridge Python SDK 的版本管理、发布渠道和升级策略。
</mintly-toc>

## 支持的 Python 版本

motorbridge SDK 支持以下 Python 版本：

| 版本             | 状态    | 说明       |
| -------------- | ----- | -------- |
| Python 3.10    | ✅ 支持  | 最低版本     |
| Python 3.11    | ✅ 支持  | 推荐       |
| Python 3.12    | ✅ 支持  | 最新稳定版    |
| Python 3.13    | ✅ 支持  | 最新版本     |
| Python 3.14    | ✅ 支持  | 预发布版     |
| Python 3.9 及更早 | ❌ 不支持 | 使用 3.10+ |

***

## 版本号规则

SDK 遵循 [语义化版本](https://semver.org/)：

当前源码对齐：

| 组件                    | 源文件                                  | 当前版本     |
| --------------------- | ------------------------------------ | -------- |
| 计划 Git 发布标签           | `motorbridge` 仓库                     | `v0.4.1` |
| Python 包              | `bindings/python/pyproject.toml`     | `0.4.1`  |
| Rust workspace crates | `Cargo.toml` 的 `[workspace.package]` | `0.4.1`  |

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

示例:
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 - 候选版本
```

### 版本类别

| 类别  | 示例           | 稳定性  |
| --- | ------------ | ---- |
| 稳定版 | `0.4.1`      | 生产就绪 |
| 预发布 | `0.4.1a1`    | 仅测试  |
| 开发版 | `0.4.1.dev1` | 内部使用 |

***

## 安装渠道

### PyPI（生产）

```bash theme={null}
# 最新稳定版
pip install motorbridge

# 特定版本
pip install motorbridge==0.4.1

# 升级
pip install --upgrade motorbridge
```

### TestPyPI（预发布）

```bash theme={null}
# 从 TestPyPI 安装
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1a1
```

<Warning>
  预发布版本可能有破坏性变更，不推荐用于生产环境。
</Warning>

### Git 安装

```bash theme={null}
# 从 Git 安装
pip install git+https://github.com/tianrking/motorbridge@v0.4.1

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

***

## 检查已安装版本

### 命令行

```bash theme={null}
# 使用 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())"
```

### 代码中检查

```python theme={null}
import motorbridge

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

***

## 升级策略

### 保守升级

保持在稳定版本，只升级修复 Bug：

```bash theme={null}
# 当前: 任意旧 0.x 版本
# 升级到最新稳定版: 0.4.1
pip install --upgrade motorbridge

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

### 早期采用者

在开发环境测试预发布版本：

```bash theme={null}
# 开发环境
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1b1

# 测试代码
python3 -m pytest tests/

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

### 固定版本

用于可复现部署：

```requirements.txt theme={null}
# requirements.txt
motorbridge==0.4.1
```

或使用版本约束：

```requirements.txt theme={null}
# 允许补丁更新，阻止次版本/主版本变更
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. **移除：** 在下一个主版本/次版本中移除

```python theme={null}
# 弃用警告示例
import warnings

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

***

## 发布检查清单

维护者发布新版本：

### 1. 更新版本号

```bash theme={null}
# 更新 bindings/python/pyproject.toml 中的 [project].version
version = "0.4.1"
```

### 2. 更新变更日志

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

### 3. 打标签

```bash theme={null}
git tag v0.4.1
git push origin v0.4.1
```

### 4. 构建包

```bash theme={null}
MOTORBRIDGE_LIB=../../target/release/libmotor_abi.so \
MOTORBRIDGE_WS_GATEWAY_BIN=../../target/release/ws_gateway \
python -m build
```

### 5. 上传到 TestPyPI

```bash theme={null}
twine upload -r testpypi dist/*
```

### 6. 验证安装

```bash theme={null}
pip install -i https://test.pypi.org/simple/ motorbridge==0.4.1
python3 -m pytest tests/
```

### 7. 上传到 PyPI

```bash theme={null}
twine upload dist/*
```

***

## 重要规则

<Warning>
  **切勿重复上传同一包版本。**

  一旦版本上传到 PyPI，就无法覆盖。新上传必须增加版本号。
</Warning>

### 上传失败处理

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

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

***

## CI/CD 集成

### GitHub Actions 示例

```yaml theme={null}
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 }}
```

***

## 版本兼容性表

| SDK 版本 | 最低 Python | 推荐传输                                  | 说明                                                                      |
| ------ | --------- | ------------------------------------- | ----------------------------------------------------------------------- |
| 0.1.5  | 3.10      | SocketCAN                             | 初始发布                                                                    |
| 0.1.6  | 3.10      | SocketCAN                             | 添加 RobStride 参数                                                         |
| 0.2.9  | 3.10      | SocketCAN                             | 后台轮询默认启用                                                                |
| 0.3.5  | 3.10      | SocketCAN / PCAN / CAN-FD / DM serial | ABI/Python 安全性、Controller 自动清理、Python CLI 拆分兼容、RobStride 扫描与 MIT 测试     |
| 0.4.1  | 3.10      | SocketCAN / PCAN / CAN-FD / DM serial | ABI 元数据、C++ binding parity、Damiao `dm-serial` 整臂扫描与 WebSocket 多关节状态同步修复 |

***

## 下一步

* [安装指南](/zh/setup) - 安装和验证
* [故障排除](best-practices/troubleshooting) - 常见问题
* [变更日志](https://github.com/tianrking/motorbridge/releases) - 发布历史