本文为「启元机器人 PGC 内容共建」架构解读方向投稿。全文基于 PrimebotTech 官方开源仓库与 dev.primebot.com 下载页的真实内容整理，所有命令逐字引用官方 README / 快速入门文档，参数以官方原文为准；未公开的项一律标注【待确认】，不做臆测。

一、为什么需要一份"开发者视角"的架构拆解

拿到一台启元 T1 或 Q1，多数上手教程会直接教你"下载 SDK、跑示例"。但如果你打算做二次开发——无论是接一个自研视觉算法、写一段自定义步态，还是把机器人接入自己的业务系统——你真正需要的是一张能映射到代码仓库的架构图：哪一层负责驱动、哪一层开放了接口、仿真和真机之间如何对齐、编译产物最终落在哪里。

启元机器人把上述能力拆成了开源仓库 + 桌面调试台 + 技能市场三套互补的体系，并且全部放在 GitHub 与国内 AtomGit 双仓同步。本文的目的，就是把这些散落在不同仓库、不同文档里的信息，按"硬件 → 固件/SDK → 仿真 → 工具链 → 技能市场"的顺序串成一条开发者能照着走的路径。

需要提前声明的两点事实边界：

• 自由度（关节数量）：Q1 有官方数字——《启元Q1用户手册》第 19 页「参数规格」表列明：全身自由度 22 DoF，其中手臂 4 DoF×2、腰部 2 DoF（旋转、侧摆）、腿部 6 DoF×2，8+2+12=22 自洽。本文 §4.2.1 用 MuJoCo 实测官方模型得到 22 个驱动关节，与手册数值吻合，属两条独立证据互相印证。T1 的自由度官方手册未列出，本文仅给出实测值（15 个关节 / 14 个力矩电机），属实测口径而非官方口径。
• 构型差异：官方下载页对 T1 的描述为"四足/双足人形机器人"，而 T1 URDF V3.0 描述包明确写着"四足机器人"；Q1 则被统一描述为"双足人形机器人"。因此本文把 Q1 定位为双足人形，T1 定位为四足（并保留双足人形形态），以官方页面原文为准。

二、整机分层架构：五层映射到五个仓库

图1 说明：PrimebotTech 在 GitHub 的开源组织仓库列表。表中每一层对应的仓库都能在这里找到，这也是本文架构分层的事实依据——分层不是笔者的归纳，而是官方仓库的实际划分。
先把全局架构铺开。下图把每一层对应到具体的官方仓库，开发者看到某一层，就能直接定位到 GitHub 上该 clone 哪个仓。

图2 说明：这张分层图不是概念图，而是"仓库地图"——每一层都对应真实存在的官方仓库或工具。从下往上看：硬件被 SDK 抽象成 ROS2 接口；仿真用 URDF/MuJoCo 在虚拟环境验证；工具链决定你在哪台机器上把代码编译成可部署产物；最上层的 PrimeHub 则把成果打包成可上架的技能。

逐层拆解如下：

① 硬件层（机器人本体）。Q1 与 T1 的计算平台均为大脑板 + 运控板架构，官方工具链与下载页明确支持两类主控：RK 平台与 NVIDIA Jetson Orin 平台（RK 具体芯片型号【待确认】）。机器人本体通过关节、相机、音频、BMS 等硬件抽象接口对外暴露能力，开发者不必关心底层协议。

② 固件 / ROS2 SDK 层。这是二次开发的核心入口。primebot-q1-sdk 与 primebot-t1-sdk 的 README 开头即声明：基于 ROS2 + FastDDS 去中心化架构，统一通过 ROS2 接口即可控制机器人全部能力，无需关心底层协议细节；开发程序可灵活部署在 PC、运控板或大脑板上，透明访问全量机器人能力接口。SDK 内部用 aimdk_msgs 消息包统一定义了 Agent 层、硬件抽象层（HAL）、交互层、运控层（MC）的消息与服务。两个 SDK 在官网下载页标注版本均为 v1.0.0.0，体积均为 13 MB。

③ 仿真层。对应 primebot-q1-urdf 与 primebot-t1-urdf，官方下载页描述其为"完整 URDF 描述包，包含自由度连杆模型、STL 网格文件、MuJoCo XML 配置，以及 ROS RViz/Gazebo 仿真 launch 文件"，适用场景包括运动学分析、运动规划及强化学习训练。版本标注为 v1.0.0：Q1 URDF 11 MB，T1 URDF 17 MB。（来源：官方下载页仓库元信息与本地下载实测）仓库目录结构包含 config / launch / meshes / urdf / xml / tools，与下载页描述一一对应。

④ 工具链层。三个 Docker 编译环境仓库：toolchain-arm-native（ARM 原生，支持 RK/Orin）、toolchain-x86-cross-arm（x86 主机交叉编译 ARM）、toolchain-x86-native（x86 原生，用于仿真测试或 x86 部署），官网版本均为 v1.0.0。官方 ARM 原生指南明确给出镜像体积参考：RK 镜像约 2–5 GB，Orin 镜像（含 CUDA）约 44.6 GB，交叉编译镜像 RK 约 5.4 GB、Orin 约 44.6 GB。

⑤ PrimeHub 技能市场。miracle-techlink/primehub_dev_kit 提供从"写技能"到"上架"的完整链路，是架构图里最上层的能力出口。

三、Q1 与 T1 的定位差异：双足人形 vs 四足

图3 说明：《启元Q1用户手册》参数规格页（官方 PDF 第 19 页）。认证型号 Q1AA2500、站立尺寸 88×39×18 cm、整机 16 kg、电池 215 Wh、续航 3 h、全身 22 自由度，均为官方一手数据。
很多开发者会同时关注 Q1 和 T1，但两者的产品定位并不重叠。基于官方描述，差异如下表与下图所示。

图4 说明：左右两张卡片对照了 Q1 与 T1 在官方仓库/下载页中的描述差异。二者共享同一套 SDK 接口范式（ROS2 + FastDDS）和同一套仿真/工具链体系，差异主要在本体构型与配套资源上：Q1 明确为双足人形并提供 DIY 外壳 STEP 模型；T1 描述为四足/双足人形，当前 URDF V3.0 为四足形态，且 SDK 示例里额外带了 OpenCV 4.13.0 源码包与 Ruckig 运动规划源码包。

具体差异点：

1. 构型。Q1 = 双足人形；T1 = 四足/双足人形（当前 URDF V3.0 为四足）。这一条直接决定你做运动规划时的自由度拓扑。Q1 的自由度有官方手册口径（22 DoF，见开篇事实边界与 §4.2.1 实测）；T1 官方手册未列自由度，本文只用实测值（15 关节 / 14 电机），请以官方后续发布的规格书为准。
2. SDK 示例资源。T1 SDK 的 examples/ 目录明确包含 opencv/（OpenCV 4.13.0 源码包，需本机构建）与 ruckig_for_primebot/（Ruckig 源码包，供 C++/Python 示例构建）；Q1 SDK 结构相同，但下载页对 Q1 的强调点在 DIY 外壳。两者 aimdk_msgs 的消息分层（agent / hal / interaction / mc）完全一致。
3. 平台。两者都支持 RK 与 NVIDIA Jetson Orin，工具链三件套通用，不存在"某机型只能用某工具链"的限制。
4. 适用场景。下载页对 URDF 的描述一致：运动学分析、运动规划、强化学习训练——这意味着 Q1 与 T1 在算法侧的研究工作流是相通的，区别在真机形态。

客观说明：以上均为官方页面给出的描述，本文未对任何第三方机器人产品做对比或评价，仅陈述启元自家两条产品线的定位差异。

四、开发者工作流：从 URDF 仿真到 SDK 二次开发

把架构落到"第一天该做什么"，工作流可以分成四步，下图是闭环示意。

图5 说明：四步工作流是实际可执行的开发顺序——先装环境，再用 URDF 在仿真里验证逻辑，然后用 SDK 写业务并编译，最后上真机或借助 PrimeConsole / Docker 工具链调试部署；仿真结果可回灌修正，形成闭环。

4.1 第一步：装环境

官方《快速入门与集成指南》明确推荐的开发环境为 Ubuntu 22.04.x LTS，ROS2 发行版为 ROS2 Humble，并注明"暂不支持 Mac/Windows"。基础依赖安装命令（逐字引用官方文档）：

sudo apt update && sudo apt install -y \
    python3-colcon-common-extensions \
    python3-dev \
    python3-pip \
    ros-humble-rosidl-default-generators \
    ros-humble-rosidl-default-runtime

环境检查命令（逐字引用）：

lsb_release -d
echo $ROS_DISTRO
pip3 show colcon-core

将 ROS2 环境写入 ~/.bashrc（逐字引用）：

if ! grep -q "source /opt/ros/humble/setup.bash" ~/.bashrc; then
  echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
fi
source ~/.bashrc

复现仓库（规则第 2 条）：本文涉及的全部示例工程已上传至 AtomGit 公开仓库：https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro 。仓库含 4 个可运行脚本（render_sim.py / q1_motion_seq.py / viewer_shot.py / find_t1_stance.py）、示例渲染图与 requirements.txt，按 README 指引下载官方 URDF 包后，可直接复现本文所有实测数据。

4.2 第二步：仿真验证

在写真机代码前，先用 URDF 在 RViz / Gazebo 里验证运动学与轨迹，是降低真机调试风险的关键。下载并解压对应 URDF 包（primebot-q1-urdf 或 primebot-t1-urdf），其 launch/ 目录提供了 ROS RViz/Gazebo 的 launch 文件，meshes/ 提供 STL 网格，xml/ 提供 MuJoCo XML，config/ 存放关节限位与控制器参数，urdf/ 则是连杆与关节的拓扑定义。对开发者而言，这套目录就是"机器人的数字孪生"：你可以在 urdf/ 里确认每个关节的名字与父子关系，在 meshes/ 里核对外形，在 launch/ 里一键拉起可视化，再在 MuJoCo（xml/）里做接触动力学与强化学习训练。正因为 URDF 与 SDK 共用同一套关节命名，仿真里验证过的轨迹，理论上可以直接映射到真机的 aimdk_msgs/mc 运控接口。

不过静态渲染图只能证明"模型能加载"，真正调参时用的是交互式调试窗口，见 §4.2.2。

4.2.1 仿真实测：用 MuJoCo 加载 Q1/T1 官方模型

为了验证"URDF/XML 就是数字孪生"这个说法，笔者用 MuJoCo 对官方资源包做了实测：在不连接任何真机的情况下，仅凭资料包里的模型文件完成加载与渲染。实测环境与版本如下：

组件	版本	说明
Python	3.13.12	官网安装包
mujoco	3.17.0	pip install mujoco（Python 绑定）
numpy	2.5.4	依赖自动安装
Q1 模型	q1_v3.xml（URDF 包 v1.0.0）	自带地面、光照与 <statistic> 场景配置
T1 模型	scene_plane.xml（URDF 包 v1.0.0）	通过 <include> 引用 T1-V2.xml 机体

实测加载结果（脚本运行时打印）：Q1 为 23 个关节、29 维广义坐标（nq=29，其中 22 个驱动关节恰好对应官方手册标称的 22 DoF：29 维广义坐标减去浮动基座占用的 7 维），无执行器定义（nu=0，纯运动学/动力学模型）；T1 为 15 个关节、14 个电机（nu=14，力矩执行器，增益参数为 1，需外接 PD 控制器才能稳定站立）。

以下截图均由 MuJoCo 离屏渲染器（1280×960）生成，脚本与复现步骤见文末工程仓库：

图6 说明：Q1 官方模型初始姿态渲染。腿部每侧 6 自由度（hip pitch/roll/yaw、knee、ankle pitch/roll）、腰部 2 自由度（旋转、侧摆）、手臂每侧 4 自由度——8+2+12=22，与官方手册「全身自由度 22 DoF」逐项对得上。网格地面与阴影由 XML 中预置的光照定义产生。

图7 说明：Q1 上半身特写。头部、肩部串联的 pitch/roll/yaw 三轴关节与肘部、腕部偏航关节清晰可辨，这与 SDK 运控接口中的关节命名一一对应。

图8 说明：T1 官方模型初始姿态。T1 以趴姿作为初始状态（scene_plane.xml 场景），机体为浅蓝色外壳，四肢为白色连杆，与 URDF 中 FL/FR/RL/RR 四条腿各 3–4 个关节的定义一致。

图9 说明：T1 机体特写。可观察髋关节 roll/pitch、膝关节的串联结构，以及黄色透明材质的足端连杆。

实测结论：官方 XML 模型开箱即用——无需修改路径、无需额外资产，MjModel.from_xml_path 一次加载成功；渲染缓冲默认 640×480，需在脚本中设置 model.vis.global_.offwidth/offheight 才能输出高清图（这是唯一需要踩的坑）。这套模型可以直接作为强化学习训练与轨迹验证的基础，与 §4.2 的 ROS RViz/Gazebo 路径互为补充。

复现说明：上述关节数来自脚本实测打印，可复现；自由度口径以官方手册为准（Q1 手册为 22 DoF）。渲染脚本与环境版本见文末工程仓库。

4.2.2 交互式调试：把 MuJoCo 原生 Viewer 跑起来

离屏渲染适合出图；调关节限位、看接触点、逐帧查轨迹时，要用交互式窗口。MuJoCo 的 Python 绑定自带被动模式 Viewer，最小代码如下：

import mujoco, mujoco.viewer          # viewer 是子模块，必须单独 import
import numpy as np

model = mujoco.MjModel.from_xml_path("q1_v3.xml")
data  = mujoco.MjData(model)

viewer = mujoco.viewer.launch_passive(model, data,
                                      show_left_ui=True, show_right_ui=True)
# 默认相机按 <statistic> 的 center/extent 取景，细长机体容易跑偏，手动对准
viewer.cam.lookat[:]  = np.array(model.stat.center) + [0, 0, 0.1]
viewer.cam.distance   = max(float(model.stat.extent) * 2.6, 1.6)
viewer.cam.azimuth    = 145
viewer.cam.elevation  = -14

while viewer.is_running():
    mujoco.mj_step(model, data)
    viewer.sync()

三个实测踩到的点，按遇到顺序说：

1. 只写 import mujoco 会报 AttributeError: module 'mujoco' has no attribute 'viewer'——viewer 是独立子模块，且依赖 GLFW（pip install mujoco 会一并装上；若报缺 glfw，补装 glfw 即可）。
2. 相机需要手动设。Q1 站姿约 0.88 m 高，默认 distance 取 extent 会退得太远，机身只占画面中间一小块；上面那三行把注视点抬到躯干、距离压到 extent × 2.6，取景才正常。
3. Q1 的 nu=0（模型里没有执行器），直接 mj_step 会因为重力自由落体。演示关节运动时应当直接写 data.qpos[...] 再调 mujoco.mj_forward()，走运动学而不是靠 data.ctrl。

窗口打开后，左侧是 File / Option / Simulation / Window / Help 标签栏，下方依次为 Info（仿真时间、步长、每步耗时）、Sensor、Control；右侧是 Rendering、Group enable、Joint、Actuator 一类可视化开关。调轨迹时最常按的是 Simulation 里的 Pause 与 Step——逐帧看足端接触比翻日志快得多。

图10 说明：Q1 在 MuJoCo 原生 Viewer 中的调试界面。左侧标签栏下方为 Info/Sensor/Control 面板，右侧为可视化开关区，中间 3D 视口显示 Q1 站立姿态与网格地面。注意标题栏显示的模型名为 q1_v3，即 XML 中 <mujoco model="..."> 的定义值。

图11 说明：向 left/right_shoulder_pitch、shoulder_roll、elbow_pitch 六个关节写入按正弦曲线插值的目标角度（幅值受官方 range 限位裁剪），Viewer 中 Q1 双臂连续摆动。这种"写 qpos + 前进仿真"的方式，正是验证关节命名与正负方向是否与 SDK 一致的最快办法——命名对不上，动作就会往反方向走。

图12 说明：T1 的调试窗口。这里有个值得记一笔的细节：标题栏模型名为 QD1 scenemesh，而不是 T1——官方 scene_plane.xml 里写的是 <mujoco model="QD1 scenemesh">，说明这份场景文件是从另一型号沿用的，跨机型共用。T1 与 Q1 的另一个实测差异在驱动方式：T1 的 nu=14 是纯力矩电机（gainprm=1，内部不带 PD），要让它在仿真里站住，得在循环里自己算力矩 tau = kp*(q_target - q) - kd*qdot 写进 data.ctrl，直接给目标角度无效。

官方资料包给出的 URDF/XML 是能直接进 MuJoCo 的，而 MuJoCo 的交互式 Viewer 又是免费的、跨平台的、不需要真机的调试入口。对没有 T1 Pro 在手的开发者，这条路径是唯一能低成本验证"关节命名、限位、运动方向"三件事的办法——而这三项恰好是后面写 SDK 运控代码时最容易出错的地方。

4.3 第三步：SDK 二次开发

图13 说明：primebot-q1-sdk 仓库页面。SDK 以 ROS2 包形式发布，aimdk_msgs 定义消息与服务，examples/ 下给出 Python 与 C++ 两版示例。
编译 SDK 的核心命令（逐字引用官方《快速入门与集成指南》）：

tar -xzf primebot_sdk.tar.gz
cd primebot_sdk
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

每次新终端需加载编译产物环境（逐字引用）：

source /path/to/your/primebot_sdk/install/setup.bash

运行官方示例（逐字引用）：

# Python 示例
python3 examples/python/demo.py
# C++ 示例
ros2 run aimdk_examples_cpp demo

用 ROS2 原生命令做接口验证，是确认"节点可见、数据通"的最快方式（逐字引用）：

ros2 node list
ros2 topic list
# BMS 状态接收验证
timeout 5 ros2 topic echo /aima/hal/bms/state --once
# TTS 语音播报验证
ros2 service call /aimdk_5Fmsgs/srv/PlayTts aimdk_msgs/srv/PlayTts \
  '{header: {}, tts_req: {text: "你好，我是启元机器人", priority_level: {value: 6}, domain: "sdk_test", is_interrupted: true}}'

注意：官方文档提示，若未持久化内核 UDP 缓冲区参数，每次新终端执行 ROS 命令前需先调整（逐字引用）：

sudo sysctl -w net.core.rmem_max=25165824
sudo sysctl -w net.core.wmem_max=25165824

4.4 第四步：调试与部署

真机调试有两种路径。其一是直接用官方桌面调试台 PrimeConsole（1.0.3 实测见 §4.4.1）；其二是用 Docker 工具链在目标板编译部署。ARM 原生编译的关键命令（逐字引用 toolchain-arm-native 文档）：

# 启动容器（RK）
sudo docker run -it --rm --net=host -v ~/workspace:/workspace -w /workspace native-aarch64-rk bash
# 容器内编译
cd sdk_q1 && colcon build
cd ../sdk_t1 && colcon build

4.4.1 PrimeConsole 1.0.3 实测：装得起来，但连不上真机

PrimeConsole 是官方桌面调试台。2026-10-28 放出的 1.0.3 版提供 Windows（.exe，237,803,340 字节）、macOS（Intel / Apple 芯片两个 dmg）与 Linux（deb，239,217,122 字节）三平台包，都从 dev.primebot.com/download 取。Windows 包是 NSIS 封装的 Electron 应用，解包后能看到 resources/app.asar（378,822,526 字节）以及自带的 ffmpeg / mediamtx 二进制——结合主进程代码里 ffmpeg -rtsp_transport tcp … -f mpegts 的命令行可以确认：实时视频流是本地 ffmpeg 拉 RTSP、转 HLS 再喂给渲染层的，不是云端转发。

在本机（Windows）跑通的完整流程是这样的：

1. PrimeConsole-Windows-1.0.3.exe /S /D=<路径> 可静默安装到指定盘；默认会落到 %LOCALAPPDATA%\Programs。
2. 启动后先到「Prime Console · 登录」，手机号 + 短信验证码，勾协议后进主界面。没有游客模式，也没有跳过登录。
3. 一级导航只剩两个：「机器人控制」和「Skill 验证」，右上角固定挂着连接状态、「连接机器人」、「系统设置」、「登出」。

有个和官方宣传对不上的地方值得记一笔：下载页写的"六大模块 ①–⑥"是功能罗列，不是软件里的菜单编号。1.0.3 把这些功能全折叠进了「机器人控制」这一页——上方是连接卡片（内嵌 日志 / 摘要 / JSON 三个视图切换），中间是实时视频位与语音 TTS，下方并排摆着动作库和表情库。写文档时如果照抄下载页的编号去指路，读者是找不到对应菜单的。

图14 说明：未绑定真机时的 PrimeConsole 1.0.3 主界面（实机截屏）。左上角连接卡片显示"未连接"、日志区"暂无连接日志"；中部视频位"尚未获取图像"；下方动作库、表情库均显示"0 项"。这张空状态图本身就是一条有用结论：动作库、表情库、视频流、遥测日志四项数据全部依赖真机在线，纯仿真环境拿不到。

图15 说明：连接卡片的「日志」视图。未连接时面板保持"暂无连接日志"；旁边还有「摘要」「JSON」两个视图，设计上是给连接态的遥测做结构化展示的，空载状态下三者都是空面板——这正是判断"设备是否真的在线"的第一手依据。

图16 说明：连接卡片的「摘要」视图，未连接时只显示"未连接机器人"一行字。这个视图在连接态下本应聚合设备型号、固件版本、在线时长等结构化摘要，是排查"机器人到底什么状态"时最先看的面板。

图17 说明：连接卡片的「JSON」视图，面向程序化调用方直接输出原始遥测字段。空载状态下同样无数据可吐——三个视图共用一套数据源，进一步印证遥测数据完全由真机侧推送。

图18 说明：「Skill 验证」页。这是把本地技能推到机器人上跑验证的入口，与 PrimeHub 技能市场是上下游关系：PrimeHub 负责上架分发，PrimeConsole 负责上机前验证。

4.4.2 真机门槛：SN 码 + 云端授权校验

点「连接机器人」弹出设备选择框；没绑定过设备时直接提示"暂无设备，请先在「设置 → 机器人配置」中添加设备"。顺着指引进「系统设置 → 机器人配置 → 添加设备」，要求填机器人 SN 码（示例格式 T1-2024-0052），并明确写着"PrimeConsole 将向启元机器人校验资产与授权状态"。

图19 说明：设备选择弹窗。设备列表来自账户下已绑定的资产，为空时只能先去系统设置添加，无法临时直连 IP。

图20 说明：添加设备需要机身铭牌上的 SN 码，提交后由启元云端校验资产与授权。结论很直接——没有真机（或真机未授权）的开发者，动作库和表情库永远是 0 项。这也解释了为什么下面要换一条离线路径来做动作验证。

图21 说明：「系统设置 → 机器人配置」页，“我的设备"列表为空，提示"点击右上角「添加设备」开始”。这是整个真机链路的起点：没有这一步录入 SN，后面所有依赖设备在线的功能都无从谈起。

4.4.3 离线替代方案：直接回放 PrimeConsole 内置的动作包

连不上真机还有一条更可复现的路子：PrimeConsole 安装包里本来就带了一整套机器人资源，位置在 resources/app.asar 解包后的 dist/appres-pro/：

• q1_v2/urdf/q1_v2.urdf——Q1 官方 URDF。MuJoCo 3.17 直接加载后得到 22 个转动关节、nq = 22（无浮动基座）。对照开源仓那版 q1_v3 的 23 关节 / 29 个广义坐标，多出来的 7 维正好是浮动基座，两者自洽。
• preset-actions-q1/index.json——count: 115，分 14 类：上传上肢动作包 29、对话表达类 15、社交礼仪类 14、情绪反馈类 13、娱乐与生活模仿类 7、思考认知类 7、任务反馈与指引类 7、原厂预设 8、运动模仿类 3、内部播报动作 3、灵创捕捉 5、拖拽示教 2、音乐舞蹈类 1、闲时状态类 1（按显示名去重后剩 111 条）。
• preset-actions-q1/motions/*.csv——120 fps 的原始关节角轨迹，表头是关节名，单位弧度。上半身包固定 10 列：waist_roll / waist_yaw + 双侧 shoulder_pitch/roll/yaw + 双侧 elbow，跟 URDF 里的关节名逐字对得上。

既然列名和 qpos 一一对应，就可以把 CSV 直接灌进 MuJoCo 的关节角、逐帧 mj_forward 再离屏渲染，得到官方动作的确定性回放——不联网、不依赖真机、任何人拿到安装包都能复现：

import mujoco, numpy as np
model = mujoco.MjModel.from_xml_path('q1_v2.urdf')        # 22 个转动关节
model.vis.global_.offwidth  = 1000                        # 默认离屏缓冲只有 640×480，
model.vis.global_.offheight = 800                         # 不放大会在 Renderer 构造时就抛 ValueError
data = mujoco.MjData(model)
data.qpos[model.jnt_qposadr[joint_index]] = angle_rad     # CSV 列 → qpos
mujoco.mj_forward(model, data)
renderer.update_scene(data, camera=cam)
img = renderer.render()

上面是核心片段（renderer / joint_index / cam 的构造与逐帧循环已略）。完整可运行脚本已按征文规则第 2 条上传至 AtomGit 公开仓库：https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro ，脚本位于仓库 scripts/ 目录，克隆后按 README 配置即可运行。

回放了官方动作包里四类典型动作，参数实测如下（帧数按 120 fps 计）。

数据来源：官方动作包 preset-actions-q1 内的关节轨迹 CSV（采样率 120 fps），时长与帧数为笔者逐条统计所得，可用本文工程脚本复现。

动作	编号 / 分类	时长	帧数
招手	3001，原厂预设	4.00 s	480
握手	3002，上传上肢动作包	6.67 s	800
上半身舞蹈 1	3046，原厂预设	5.17 s	620
随意摇摆	FB-DAN-001，音乐舞蹈类	8.19 s	983

图22 说明：原厂预设"招手"（3001，4.00 s / 480 帧）六帧等间隔回放。可以看到右肩 roll 外展、右肘收拢后小臂做往复摆动，左臂保持自然下垂——CSV 里左臂那 5 列全程几乎不变，与波形图（图26）一致。

图23 说明：“握手”（3002，6.67 s / 800 帧）六帧回放 。右臂前伸到体前偏右后小幅度上下摆动，躯干基本不动。这类动作只动上半身 10 个关节，下半身 12 个关节全程保持零位——也就是说官方动作包是上半身动作库，不包含步态。

图24 说明：“上半身舞蹈 1”（3046，5.17 s / 620 帧）六帧回放。双臂交替上举配合腰 yaw 小幅扭转，是周期性强、幅度大的一类，很适合拿来验证关节限位有没有被撞到。

图25 说明：音乐舞蹈类"随意摇摆"（FB-DAN-001，8.19 s / 983 帧）六帧回放，是本组里时长最长、躯干参与最多的一个。注意它的 scope 字段是 FB（full body），但实际 CSV 仍然只有 10 个上半身关节列——字段口径与数据口径不一致，引用时以 CSV 实际列数为准。

图26 说明：四个动作的关节角-时间曲线，横轴秒、纵轴弧度，直接读自 120 fps 原始 CSV（未做平滑）。从上到下能看出四类动作的"指纹"差异：招手是右肘单关节高频往复；握手是右肩 pitch 的一次慢速单向抬放；舞蹈是右肘与右肩 pitch 的反相周期振荡；随意摇摆则是腰 yaw 与右肩 roll 的低频大幅摆动。这类曲线可以直接拿来做动作分类或异常检测的特征。

把 §4.2.1 的自建 MuJoCo 渲染和这一节的官方动作回放放在一起看，能得出一条对开发者更实际的结论：启元的官方 URDF + 官方动作 CSV 是解耦的——URDF 描述本体，CSV 只描述关节角随时间的取值，两者靠关节名对齐。这意味着你可以在不碰真机的前提下，把动作时序、关节限位、周期特征这些逻辑先在仿真里验完，再等真机到位做标定。

五、开源生态盘点：双仓同步与 PrimeHub 技能市场

图27 说明：启元机器人在 AtomGit 的组织主页，与 GitHub 双仓同步。征文规则要求示例工程上传 AtomGit，这里就是最终要落地的位置。
启元的开源资产分布在两个地方：GitHub 组织 PrimebotTech（12 个公开仓库）与国内 AtomGit 组织 PrimebotTech（同内容加速镜像）。下表是仓库职责一览。

图28 说明：仓库地图把前文提到的所有仓库按职责归类。核心开发四件套（q1/t1 SDK + q1/t1 URDF）是二次开发的必装项；三个 toolchain 仓库解决"在哪编译"；PrimeHub dev kit 解决"如何上架"。mjlab / primebot_rl_mjlab / SuperMimic 三个仓库 README 未给出明确用途描述，本文标注【待确认】。

PrimeHub 技能开发包（miracle-techlink/primehub_dev_kit），它把"写机器人技能"标准化成了可复现的链路。其 README 给出的快速开始自检命令（逐字引用）：

python3 primehub_publish.py search "你好"   # 自检：能搜 = 网络和传输层 OK

官方定义的技能开发顺序是（逐字引用 README）：

注册 PrimeHub → 给 AI agent 喂机器人契约 → vibe coding 改示例 → 打包 .rpk
→ 真机调试 → 提取登录 token → 一条命令发布上架

环境要求（逐字引用）：Python 3 + pip install gmssl、curl、sshpass、一台同网段的 Q1/T1 机器人（SSH run）、本机 Firefox（用于 PrimeHub 登录态，发布凭证自动提取）。仓库内 example-jukebox/ 是一个已上架的真实案例（点歌台），开发者可复制成自己的技能再改；pack.py 负责把技能目录打包成 .rpk，deploy_test.py 负责真机调试，primehub_publish.py 是发布/删除/查询客户端。

客观评价：PrimeHub 把"算法能力"封装为可上架的技能（.rpk），与底层 ROS2 SDK 形成"底层接口 + 上层应用市场"的两层结构，开发者既可以深入 SDK 写硬核控制，也可以在上层用 AI agent 快速产出技能。这种分层对生态建设是清晰的。

关于 mjlab、primebot_rl_mjlab、SuperMimic、GMR 四个仓库：GMR 的 GitHub 描述为"机器人数据重定向适配 Q1"；其余三个仓库的 README 在抓取时未提供明确用途说明（已知 mjlab / primebot_rl_mjlab 与 MuJoCo/强化学习相关、SuperMimic 为 MIT 协议 Python 项目），其具体定位【待确认】，建议以仓库后续文档为准。

六、给想上手的开发者的第一步建议

把全文收敛成可执行的"第一天"清单：

1. 先定机型，再 clone。双足人形选 Q1，四足/双足人形选 T1；两者 SDK 接口范式一致，可共用学习成本。
2. 装 Ubuntu 22.04 + ROS2 Humble，用 §4.1 的命令把基础依赖与 colcon 跑通。
3. 先用 URDF 在仿真里跑通关节运动，再碰真机——这步能把 80% 的运动学错误挡在真机之前。
4. 用官方示例 demo.py / demo（C++）验证 ROS2 节点可见、topic/service 通，再写自己的业务逻辑。
5. 编译产物走 Docker 工具链：x86 主机用 toolchain-x86-cross-arm 交叉编译，目标板直接用 toolchain-arm-native 原生编译，二者镜像与命令官方已给全。
6. 想做可分发的能力，走 PrimeHub：用 primehub_dev_kit 从 example-jukebox 改起，打包 .rpk 上架。
7. 复现材料：本文用到的渲染与回放脚本（render_sim.py / q1_motion_seq.py / viewer_shot.py / find_t1_stance.py）https://atomgit.com/azhiqiu/primebot-q1-t1-mujoco-repro ，克隆即可复现；本文所有命令均来自官方 README，请以你下载时的最新版本号为准。

最后强调事实边界：Q1 的 22 DoF 有官方手册与模型实测两方印证（见 §1 与 §4.2.1），可以当确定参数用；T1 的自由度数量、主控 RK 平台的具体芯片型号、以及 mjlab 等研究型仓库的用途，官方当前未公开或文档未覆盖，本文已逐项标注【待确认】，请勿把这些待确认项当作确定参数使用。

---

本文涉及的 开发资料，可通过 启元机器人开发者社区 查阅。
欢迎大家交流