启元无真机二开实战1：54 个接口能做什么、不能做什么——启元 Q1/T1 SDK 能力全景与版本矩阵

启元无真机二开实战1：54 个接口能做什么、不能做什么------启元 Q1/T1 SDK 能力全景与版本矩阵

文章目录

[启元无真机二开实战1：54 个接口能做什么、不能做什么------启元 Q1/T1 SDK 能力全景与版本矩阵](#启元无真机二开实战1：54 个接口能做什么、不能做什么——启元 Q1/T1 SDK 能力全景与版本矩阵)
- - - 写在最前面
    - 一、先给结论：一张能力地图
    - [二、运动控制：61 个动作枚举和一套控制权仲裁](#二、运动控制：61 个动作枚举和一套控制权仲裁)
    - [三、交互与硬件：TTS 六级优先级、10 种触摸事件、两路相机](#三、交互与硬件：TTS 六级优先级、10 种触摸事件、两路相机)
    - [四、SDK 没有的能力，以及没有意味着什么](#四、SDK 没有的能力，以及没有意味着什么)
    - 五、版本矩阵与三处不同步
    - 六、这些能力从哪来：平台侧的上下文
    - 局限说明
    - 写在最后
    - 参考资料
    - 启元机器人开发者社区

写在最前面

版权声明：本文为原创技术梳理，遵循 CC 4.0 BY-SA 协议。转载请注明出处。

本文依据启元官方 AtomGit 组织（atomgit.com/primebot）公开仓库整理：q1-sdk 锚定提交 7310314eee058323a2c15ab1f4f947df4112573e、t1-sdk 锚定提交 a460300（两者均为 2026-10-08 "merge GitHub repository initialization"，即下载页所称 v1.0.0.0 的代码实体），q1-dev-guide 锚定 54ee39c。文中接口数量、枚举数量、字段数量均为 2026-10-26 在本地克隆仓库上用脚本清点的结果（CPython 3.13，macOS arm64），清点脚本见文末仓库，每个数字可复算。

现在手头没有 Q1 真机，SDK 要求的 Ubuntu 22.04 环境也还没搭，但两个 SDK 仓库 clone 下来读了几天之后，发现"能做什么、不能做什么"这个问题的答案其实完整地躺在仓库里，只是散落在三处：《快速入门与集成指南》讲环境、《接口说明》讲协议、examples 目录讲用法，而"不提供什么"这类负面清单，反而藏在技能示例 README 的脚注里。这篇就是把三处材料加消息定义文件合到一张桌上盘一遍的结果。

它不教你跑通任何一条命令（那是快速入门的工作），回答的是选型和预期管理的问题：接口按能力怎么分层、控制权仲裁的真实规则是什么、失败时拿到的状态码意味着什么、Q1 和 T1 在接口层面差在哪，以及哪些你以为有的能力其实没有。作为写了多年鸿蒙的人，我顺手在每个机制旁边标了移动生态的对位物，给同背景的作者当一张翻译表。

一、先给结论：一张能力地图

图1｜启元 Q1 SDK v1.0.0.0 能力地图。四块卡片分别对应运动控制、交互、硬件抽象与负面清单，接口名与数量取自 q1-sdk/t1-sdk 仓库 aimdk_msgs 目录与《接口说明》API 表逐行清点（脚本与口径见图下注记）；总线拓扑依据《快速入门与集成指南》§1。

读这张图从总线开始。Q1/T1 体内是两块计算板：运控板（10.1.1.100）跑实时运动控制与硬件抽象服务，大脑板（10.1.1.101）跑 AI 感知算法。你的程序无论跑在开发 PC 还是任一块板上，都以 ROS2 节点身份接入同一条 FastDDS 总线。SDK是一套定义了机器人对外提供哪些话题与服务的数据契约包（aimdk_msgs），加一份接入规程（快速入门），加 18 个场景示例（examples）。它不包含任何运行时库去"驱动"硬件，驱动都在机器人里面，SDK 只是那张通讯录和拨号规则。

接口数量口径先钉死，避免后文歧义。aimdk_msgs 目录下 .msg/.srv 定义文件 Q1 与 T1 均为 54 个（文件清单逐一对得上，含 agent 层）。《接口说明》的 API 总表条目 Q1 为 27、T1 为 30，后者才是开发者日常会拨的"号码"（27 条里含 2 个 PulseAudio TCP 直连端口与 1 个 RTSP 地址模板）。Q1/T1 文档表的差集是 T1 独有的舵机控制 SetServo、颈部灯光 SetNeckLight 与颈灯状态话题，两机型消息包里其实都有这两个 srv 定义，是否生效取决于硬件有无对应部件。三个数都对，说的是三件事，网上流传的"54 个接口"如果不注明口径，容易让人以为有 54 个可调服务。

二、运动控制：61 个动作枚举和一套控制权仲裁

运动模块是这套 SDK 的重心，理解它需要抓住两个机制。

先说动作枚举。机器人处于哪个运动状态，由一个全局的 Action 枚举决定，SetMcAction 负责切换、GetMcAction 负责查询。我数了 Q1 的 McAction.msg：生效枚举 61 个，另有 5 个被注释保留的"删除态"（原地旋转 204、下腰 205、"羽生结弦"209、劈叉 210、转圈舞 400，删掉的动作以注释形式留在协议里，算一种非正式的版本变更日志）。枚举编号不是连续分配的，分段本身携带语义：

图2｜Q1 生效动作枚举 61 个按编号分段的分布。统计自 q1-sdk@7310314e 的 aimdk_msgs/mc/action/McAction.msg（正则解析 int32 常量，排除注释行），每段给出代表枚举。

1-3 是被动/阻尼这类安全态，100 段四足、200 段双足、300 段全身控制与示教录制，1000 段自定义与预设。400-999 整段为空不是遗漏，是舞蹈模仿类动作被批量注释后的遗迹。上肢开发最常碰到的门是 BIPED_CUSTOM_UPPER=1014。T1 的枚举表同为 61 个但成员不同：T1 保留原地旋转 204、多一个 BIPED_NPZ_MIMIC=304，Q1 则多两个模仿动作 V2（1018/1019）。同名动作枚举在两机型间不是同一张表，跨机型技能要在 manifest 里锁机型，原因就在这。

切换动作有严格的状态机语义：请求发出后要轮询 GetMcAction 直到目标动作进入 RUNNING(400) 才能发后续指令，SDK 示例为此封装了 McActionSwitcher 公共模块，里面两张表值得细看：

python 复制代码

# examples/python/common/mc_action_switcher.py（节选，q1-sdk@7310314e）
_ACTION_RULES = {
    "BIPED_STAND_DEFAULT": ("BIPED_WALK_RUN", "BIPED_WALK_RUN_DEFAULT",
                             "STORE_DEFAULT", "BIPED_BLIND_TERRAIN"),
    "BIPED_CUSTOM_UPPER": ("BIPED_STAND_DEFAULT", "BIPED_WALK_RUN"),
    # ... 20 个动作的转移规则，目标不可直达时按规则规划中间态
}

def _wait_for_action(self, expected_action, options, deadline):
    while rclpy.ok() and time.monotonic() < deadline:
        current = self._get_current_action(options)
        if current and current.action_desc == expected_action \
                and self._is_active(current):
            return current          # 到达 RUNNING 才返回
        time.sleep(options.poll_interval)
    return None                     # 超时返回失败，由调用方决定重试

两次 SetMcAction 的最小间隔 500ms 是文档明文（官方技能示例把它配到 600ms，注释写着"防 -10001"）。鸿蒙类比：这像 Ability 生命周期，你不能对 STOPPED 状态的组件发新意图，得等 onForeground。

再说控制权仲裁。机器人同一时刻可能被遥控器、语音 App、示教程序、你的 SDK 程序同时想要控制权，SDK 的处理方式是显式注册：SetMcInputSource 给程序登记一个输入源，priority 取值 0-100，内置五源 rc/vr/app_proxy/interaction/pnc 各占档位，注释里官方技能用的 30 对应"39-20 的 SDK 二开档"。timeout 默认 1000ms，心跳断了 1 秒控制权自动收回。GetCurrentInputSource 用来验证控制权是否到手。这套写进协议的多主仲裁加租约超时，是消费级机器人和实验室代码的分水岭之一，值得二开者认真读一遍 McInputSource.msg 那七行定义。
#mermaid-svg-RU6KfdGwPHQTWHZH{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-RU6KfdGwPHQTWHZH .error-icon{fill:#552222;}#mermaid-svg-RU6KfdGwPHQTWHZH .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-RU6KfdGwPHQTWHZH .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-RU6KfdGwPHQTWHZH .marker{fill:#333333;stroke:#333333;}#mermaid-svg-RU6KfdGwPHQTWHZH .marker.cross{stroke:#333333;}#mermaid-svg-RU6KfdGwPHQTWHZH svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-RU6KfdGwPHQTWHZH p{margin:0;}#mermaid-svg-RU6KfdGwPHQTWHZH .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster-label text{fill:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster-label span{color:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster-label span p{background-color:transparent;}#mermaid-svg-RU6KfdGwPHQTWHZH .label text,#mermaid-svg-RU6KfdGwPHQTWHZH span{fill:#333;color:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH .node rect,#mermaid-svg-RU6KfdGwPHQTWHZH .node circle,#mermaid-svg-RU6KfdGwPHQTWHZH .node ellipse,#mermaid-svg-RU6KfdGwPHQTWHZH .node polygon,#mermaid-svg-RU6KfdGwPHQTWHZH .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-RU6KfdGwPHQTWHZH .rough-node .label text,#mermaid-svg-RU6KfdGwPHQTWHZH .node .label text,#mermaid-svg-RU6KfdGwPHQTWHZH .image-shape .label,#mermaid-svg-RU6KfdGwPHQTWHZH .icon-shape .label{text-anchor:middle;}#mermaid-svg-RU6KfdGwPHQTWHZH .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-RU6KfdGwPHQTWHZH .rough-node .label,#mermaid-svg-RU6KfdGwPHQTWHZH .node .label,#mermaid-svg-RU6KfdGwPHQTWHZH .image-shape .label,#mermaid-svg-RU6KfdGwPHQTWHZH .icon-shape .label{text-align:center;}#mermaid-svg-RU6KfdGwPHQTWHZH .node.clickable{cursor:pointer;}#mermaid-svg-RU6KfdGwPHQTWHZH .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-RU6KfdGwPHQTWHZH .arrowheadPath{fill:#333333;}#mermaid-svg-RU6KfdGwPHQTWHZH .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-RU6KfdGwPHQTWHZH .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-RU6KfdGwPHQTWHZH .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RU6KfdGwPHQTWHZH .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-RU6KfdGwPHQTWHZH .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RU6KfdGwPHQTWHZH .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster text{fill:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH .cluster span{color:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-RU6KfdGwPHQTWHZH .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-RU6KfdGwPHQTWHZH rect.text{fill:none;stroke-width:0;}#mermaid-svg-RU6KfdGwPHQTWHZH .icon-shape,#mermaid-svg-RU6KfdGwPHQTWHZH .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RU6KfdGwPHQTWHZH .icon-shape p,#mermaid-svg-RU6KfdGwPHQTWHZH .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-RU6KfdGwPHQTWHZH .icon-shape .label rect,#mermaid-svg-RU6KfdGwPHQTWHZH .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RU6KfdGwPHQTWHZH .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-RU6KfdGwPHQTWHZH .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-RU6KfdGwPHQTWHZH :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
超时 1000ms 未续注
你的程序

SetMcInputSource(name, priority=30)
MC 仲裁器

当前最高优先级且未超时?
velocity / joint 指令生效
控制权自动释放

回内置源 rc/vr/app_proxy
GetCurrentInputSource

轮询验证控制权在手

图3（流程）｜输入源注册-仲裁-租约回收链路，依据 McInputSource.msg 字段注释与《接口说明》SetMcInputSource 节绘制。

速度控制走话题而非服务：/aima/mc/locomotion/velocity 一条消息里五个速度维度（前进/侧移/旋转/弯腰/level），100Hz 持续发布。上肢自定义控制同理，/aima/mc/custom/joint/command 携带关节数组，每个元素五字段（position/velocity/effort/stiffness/damping）。注意 stiffness/damping 随每条命令下发，说明 SDK 层是位置伺服语义，PD 闭环在机内，这和宣传口径里的"全身力控"并不矛盾，只是力控闭环对开发者不可见。

失败反馈的规范性也提一句：所有服务响应统一携带 CommonState，我清点了它的常量：通用状态 7 个（UNKNOWN/SUCCESS/FAILURE/ABORTED/TIMEOUT/INVALID/IN_MANUAL）加 31 条 REASON_* 原因码（电量低、白名单缺失、形态不匹配、无转移路径、室内禁全身动作......）。排错时先读 reason 再猜代码，这套枚举比多数 IoT 平台的裸错误码友好得多。

三、交互与硬件：TTS 六级优先级、10 种触摸事件、两路相机

交互模块里最有设计感的是 TTS 优先级。TtsPriorityLevel.msg 定义六级：BACKGROUND_L1 < SERVICE_L2 < MISSION_L4 < INTERACTION_L6 < WARNING_L8 < SAFETY_L10（外加 UNKNOWN=0），请求还带 domain（谁在说话）与 is_interrupted（可否被打断）字段。机器人同时有背景音乐、任务播报、安全告警要发声，没有仲裁就会叠音。这就是音频焦点（AudioFocus）机制的机器人版，鸿蒙的 AVSession 并发策略是同一问题的另一种解法。表情播放 PlayEmotion 用编号索引（3000+ 段），我在 PrimeConsole 1.0.2 的资源包里解出过 Q1 的表情 mp4 与 115 个预设动作索引（preset-actions-q1/index.json，来源标注 "Q1_drag_teach_release + PrimeConsole-Q1-Action-CSVs"），编号体系与技能示例里 presetReceive: 2015 这类参数能互相印证。

音频链路是新旧版本差异最大的地方，值得单独画一张账。v0.1.2.7 时代，录音/放音走 ROS2 话题（/aima/hal/audio/capture、/aima/hal/audio/playback，消息包里有 AudioCapture/AudioPlayback 定义）；到 v1.0.0.0，这两个话题从文档和消息包里都消失了，取而代之的是 API 表里的两个 TCP 直连口：6001（PulseAudio simple-protocol-tcp，播放）与 4713（native-protocol-tcp，录制），外加 audio_device_list 设备查询话题。

图4｜aimdk_msgs 定义文件 v0.1.2.7-R → v1.0.0.0 增删对照（50→54，净增 4=新增 6−删除 2）。对比对象：q1-dev-guide@54ee39c 内置 zip（文件时间戳 2026-07-12）× q1-sdk@7310314e，文件清单 diff 由脚本生成。

新版示例 record_audio.py 的注释写得很直白：支持内置麦（8 声道 48kHz，ch5-6 混合）与外置 USB 麦（2 声道 24-bit）自动检测，远程模式还会通过 SSH 自动在机器人端加载 TCP 播放/录音模块，前提条件是把售后提供的 SSH 密钥目录放到 SDK 根目录。一次接口迁移同时改变了通信协议（DDS 换 PulseAudio TCP）和信任模型（SDK 节点换 SSH 密钥），在移动生态里相当于把 MediaRecorder 换成 adb shell 起服务。合理与否另说，但它明确告诉我们 v0.x 的教程在 v1.0 上会直接失效。

硬件抽象层给的是最小传感集：头部触摸 10 种事件（单击到六击、多次点击、左右滑动，官方技能用"拍头"替代了 SDK 没有的 ASR 确认通道）、指定相机单帧 JPEG（文档建议 1fps 节奏使用）、RTSP 连续视频（rtsp://<IP>:2554/live_<camera_id>）、BMS 电池 15 字段、灯带控制。相机标识是 Q1/T1 在接口文档里最直观的差异之一：Q1 是 head_monocular_centra 单目，T1 是 head_stereo_left/right 双目，做视觉算法的选型时这条比参数表管用。ShutdownTask 要求令牌确认式调用，关机这种大动作被加了门禁。

四、SDK 没有的能力，以及没有意味着什么

这一节的内容全部有官方出处，逐条列：

你以为可能有	实际没有	官方出处	二开者的替代路径
SLAM / 导航 / 语义地图	✕	carry-clothes README"SDK 无导航接口"	自建视觉伺服闭环（示例仓库 src/vision.py 给了完整参考实现）
夹爪 / 末端执行器	✕	同上"SDK 无夹爪接口"	双臂合拢托举；T1 Pro 的硬件夹爪未进 SDK 接口表
力/力矩传感数据	✕	接口表无对应话题；力控在机内闭环	位置伺服 + stiffness/damping 调参
RESTful / gRPC API	✕（暂未支持）	快速入门 §5 五层模式表第二层	只有 ROS2 一条路；API 方式是官方预留位
步态/平衡算法	✕ 不开放	快速入门 §5（Basic 无损增强 / Advanced 需关原厂高层运控）	用预设动作与速度指令间接表达
麦克风原始流	部分	录音走 PulseAudio TCP 4713（v1.0.0.0 起），另有 `/aima/agent/asr_result` 识别结果话题（Q1/T1 文档均有）	官方技能用千问 ASR 客户端替代（luobodun_game）

"没有导航"值得展开，因为它决定了这个生态里技能长什么样。carry-clothes 的 manifest 为此专门发明了 selfProvided 块声明自建视觉模块及其缺失后果，我在系列第 3 篇会拆这个设计。对开发者，负面清单的实际含义是移动类技能全部要自带感知：SDK 只保证你"能看见（相机）、能动（速度/关节）、能说话（TTS）"，中间"知道自己在哪、目标在哪"这段路要自己铺。这和手机生态"系统给 Location API、地图服务第三方竞争"的分工完全不同，机器人平台目前把定位导航留给了开发者，门槛与自由度同时都在。

五、版本矩阵与三处不同步

盘点过程中撞上的版本问题，统一记录（截至 2026-10-26）：

组件	版本	依据
q1-sdk / t1-sdk 仓库代码	v1.0.0.0 对应实体，提交 7310314e / a460300（2026-10-08）	git log；范文作者亦锚定同一提交
下载页 SDK 包	sdk_q1-v1.0.0.0.zip / sdk_t1-v1.0.0.0.zip（2026-10-10）	dev.primebot.com/download 页面数据
q1-dev-guide 内置 zip	v0.1.2.7-R（zip 内文件时间戳 2026-07-12）	仓库文件实测
t1-sdk 仓库最后一次带版本号的提交	v0.9.4.7（2026-09-30）	git log 提交信息
PrimeConsole	1.0.2（2026-10-15 签名）	DMG 解包 codesign
q1-urdf / t1-urdf	V3.0（2026-09-24）	下载页 zip 文件名

三处不同步按踩坑概率排序。

q1-dev-guide 仓库还挂着 v0.1.2.7-R 的旧 SDK 包和旧快速入门。旧版文档写"SSH 登录后执行 aima mode edit 切开发者模式"，而 v1.0.0.0 快速入门已改为手机 APP「设置→开发者功能」图形化切换，且新版须知里明确"开启开发者功能后将不再享受维保服务"。这条商务条款只存在于新版，看旧文档的人会完全错过。T1 旧文档（v0.9.4.7 时代）对应的命令又是 yamo mode edit，新旧、两机型三个版本并存，新手按搜索结果执行大概率撞墙。

音频链路在两个大版本间整体迁移（图4 那张账）。v0.1.2.7 的录音/放音是 ROS2 话题（AudioCapture/AudioPlayback 消息加 capture/playback 话题，旧文档 API 表 24 条目里就有），v1.0.0.0 把这两个消息定义直接删了，换成 PulseAudio TCP 端口加 SSH 自动加载模块。照旧版教程写代码的人，新版 SDK 里连消息类型都找不到。

t1-sdk 仓库提交信息停在 v0.9.4.7（2026-09-30），但下载页已发 sdk_t1-v1.0.0.0.zip（2026-10-10），仓库 README 未标版本，以哪个为准官方没写。我按"下载页 zip 与仓库 main 分支同代"处理，两仓 10-08 的合并提交信息（"merge GitHub repository initialization"）暗示代码曾从 GitHub 侧同步过，这也许就是版本号错位的来源。

正文里所有"我数了"的数字，都出自下面这个脚本的一次运行，输出原样贴在图里，对着锚定提交可复跑：

图5｜count_interfaces.py 的真实终端输出（CPython 3.13 / macOS arm64），一次运行产出 54/54 定义文件、27/30 API 表条目、61 生效枚举、42 CommonState 常量、10 触摸事件、7 级 TTS、15 BMS 字段等全部计数。脚本与 primebot-repos 克隆见文末仓库。

六、这些能力从哪来：平台侧的上下文

接口之外，能力还有两个供给来源。预设动作与表情资源：发布会口径"开放 100 多个原子能力"，实体之一就是 PrimeConsole 内置的那 115 个 Q1 动作（分类含出厂预设、拖拽示教、上传上肢动作包等），技能用编号调用，不用自己调轨迹。技能层复用：官方四个示例技能（家务搬运、天气预报、多机萝卜蹲、视频电话）加上 SkillHub 社区技能，展示了 rpk 打包与发布路径，这部分我在系列第 3 篇专门拆。

另有一类资产不属于商品机 SDK 但常被混为一谈：启元研究院在 HuggingFace 开源的 1500 小时双臂家庭操作数据与 5B 参数 VLA 模型 XR-2。那是 25 自由度科研平台 X2W 的生态（有夹爪、三轮全向底盘，与 Q1/T1 本体差异明显），写文章引用时务必和 Q1/T1 的 SDK 分层，混写会失真。这份数据我单独解剖过一篇，见系列第 4 篇。

局限说明

本文是静态盘点：接口行为全部来自消息定义、文档与示例代码的交叉阅读，未连接真机验证任何一条调用；"61 个生效枚举""54 个定义文件"等计数依赖我写的清点脚本（正则解析 msg 文件），对注释风格的边界情况（如删除态枚举）已人工复核，但脚本口径与官方口径可能存在定义差；Q1/T1 差异对比基于两仓库当前 main 分支，固件侧能力（如 T1 Pro 夹爪是否会进接口表）不在我的可见范围；文中对"暂未支持"能力的推断（如 API 方式时间表）官方未公布，不做预测。

写在最后

把 54 个文件读完的最大收获，是意识到这套 SDK 的性格：它开放的是"身体"，保留的是"小脑"。表达层（说、听、看、灯光、表情）几乎全开，运动层给了三条清晰通道（预设动作、速度指令、关节目标角），而平衡、步态、力控闭环留在机内，和手机厂商开放传感器、保留基带的分层一模一样。对开发者，这意味着技能的上限由"你能不能接受在这个框架内做事"决定：接受，则输入源仲裁、优先级 TTS、状态机轮询这些机制都是现成的护栏；不接受，想绕过高层运控直驱电机，得走 Advanced 模式并自担安全责任。

参考资料

【1】 PRIMEBOT/q1-sdk（aimdk_msgs 54 定义文件、examples 18 示例、接口说明.md、快速入门与集成指南.md），锚定提交 7310314eee058323a2c15ab1f4f947df4112573e。https://atomgit.com/primebot/q1-sdk
【2】 PRIMEBOT/t1-sdk，锚定提交 a460300。T1 独有接口（SetServo/SetNeckLight/neck_light/state）与 McAction 枚举差异的数据来源。https://atomgit.com/primebot/t1-sdk
【3】 PRIMEBOT/q1-dev-guide，锚定提交 54ee39c（内置 sdk_q1-v2d0-v0.1.2.7-R.zip，用于版本对照）。https://atomgit.com/primebot/q1-dev-guide
【4】启元机器人开发者社区下载页（sdk_q1/t1-v1.0.0.0.zip、PrimeConsole 1.0.2、URDF V3.0 的版本与日期依据）。访问日期 2026-10-26。https://dev.primebot.com/download
【5】PRIMEBOT/carry-clothes，锚定提交 301b02a（"SDK 无导航/夹爪/ASR"负面清单的官方出处）。https://atomgit.com/primebot/carry-clothes
【6】启元 Q1 产品页（88cm/22 自由度/全身力控标称值）。https://www.primebot.com/q1.html
【7】本文配套清点脚本与原始输出（count_interfaces.py，输出 54/54 定义文件、27/30 API 表条目、61 生效枚举、42 CommonState 常量等全部计数；gen_figs_a1.py 出图2/图4）。仓库 tag v1.0.1。https://atomgit.com/wodekouwei/sdk-capability-map

启元机器人开发者社区

想在自己的设备上走通这条链路，或获取 Q1/T1 SDK、URDF、PrimeConsole 与技能开发资料，欢迎访问 启元机器人开发者社区。在这里插入图片描述