更新说明

README.md

@@ -16,6 +16,26 @@ Unitree Go1 **PRO** 机型的低层电机控制 Python/C++ SDK。完整逆向 PR
 
 ## 快速上手
 
+### 语言与入口
+
+| 使用方式 | 源码位置 | 构建入口 | 用户入口 |
+|---|---|---|---|
+| Python 原生 PRO API | `go1_pro_sdk/` | `pyproject.toml` | `import go1_pro_sdk` |
+| Python 官方兼容 API | `robot_interface.py`、`go1_pro_sdk/compat/` | `pyproject.toml` | `import robot_interface as sdk` |
+| Python 可选原生加速 | `fast_lowcmd_cpp/` | `fast_lowcmd_cpp/setup.py` | `FastLowCmdBuilder` |
+| C++ 官方兼容 SDK | `include/`、`src/` | `CMakeLists.txt` | `#include <unitree_legged_sdk/unitree_legged_sdk.h>` |
+
+`fast_lowcmd_cpp` 是供 Python 调用的 CPython 扩展，不是 C++ 用户的公共 SDK。C++ 用户
+只依赖根目录 CMake 生成的 `unitree_legged_sdk` 库以及 `include/unitree_legged_sdk/`
+中的公共头文件。两套实现共享同一份 PRO 协议和 Blowfish state，但运行时不互相依赖。
+
+Python 开发环境安装：
+
+```bash
+conda activate free_dog_sdk
+python -m pip install -e .
+```
+
 ### 官方 Python SDK 兼容接口
 
 需要复用官方 `unitree_legged_sdk` Python 示例时，可以继续使用原来的模块名和
@@ -172,19 +192,36 @@ bash tools/stop_sportmode.sh start
 ## 包结构
 
 ```
-go1_pro_sdk/
-├── connection/   # MCUClient: 高层 UDP 客户端
-├── codec/        # Blowfish + LowCmd 序列化 + LowState 解析
-├── types/        # MotorCmd, LowState, IMU, BMS, RemoteState 等
-├── safety/       # PositionLimit / PowerProtect / PositionProtect
-├── utils/        # CRC, 浮点编解码, 关节常量
-└── _data/        # blowfish_state.bin
+go1_pro_sdk/                  # Python 原生 PRO SDK
+├── connection/              # MCUClient: UDP 客户端
+├── codec/                   # Python Blowfish、LowCmd、LowState
+├── compat/                  # 官方 robot_interface Python facade
+├── highlevel/               # sportMode MQTT API
+├── safety/                  # Python Safety 实现
+├── types/                   # Python 数据结构
+├── utils/                   # CRC、常量和字段编解码
+└── _data/                   # Python wheel 内的 Blowfish state
 
-include/unitree_legged_sdk/  # 官方 C++ 头文件兼容层
-src/                         # PRO UDP/Blowfish/Safety 实现
-tests/cpp/                   # C++ 契约、抓包和安装消费测试
+robot_interface.py           # 官方 Python SDK 同名顶层入口
+pyproject.toml               # Python 构建和安装入口
+fast_lowcmd_cpp/             # Python 可选 CPython 加速扩展
+
+include/unitree_legged_sdk/  # C++ 公共头文件，路径与官方一致
+src/                         # C++ 私有实现，不作为公共头文件安装
+cmake/                       # C++ find_package 配置模板
+CMakeLists.txt               # C++ 构建、测试和安装入口
+
+examples/*.py                # Python 示例
+examples/cpp/                # C++ 同源码兼容示例
+tests/*.py                   # Python、实机抓包和 facade 回归
+tests/cpp/                   # C++ 契约与安装消费测试
+data/captures/               # 本机实机抓包，存在时自动参与回归
 ```
 
+Python 和 C++ 的公共 API 不交叉包含：Python 安装由 `pyproject.toml` 管理，不会安装
+C++ 头文件；C++ 安装由 CMake 管理，不会安装 Python 包。两边唯一共享的运行数据是
+`blowfish_state.bin`，安装时分别进入 Python package data 和 C++ data directory。
+
 ## 文档
 
 - `docs/PROTOCOL.md` — PRO LowCmd/LowState 字节级格式规格