前言那天晚上调试到十一点一段轨迹改了五版还是不对我盯着屏幕忽然冒出一个念头现在要是有人抱我一下就好了。这个念头挥之不去。第二天想起桌边资料里那台 Q1——88 厘米、15 公斤的小个子人形机器人手臂能张能合内置动作库里躺着一个几乎没人用过的拥抱。那就它了做一个抱抱补给站谁难过的时候喊一声机器人就颠颠地跑过来好吧目前是原地张开手臂给你一个抱抱。不过这篇文章不只是讲一个技能。从一句话的想法到市场上架中间隔着选题、包结构、接口调用、仿真验证、无真机测试一整条链路路上还有些小机关这条链怎么走、这些坑怎么绕这篇文章一次走完。一、PrimeConsole 是什么一个桌面端的两副面孔启元官方给开发者的工具链是两件套PrimeConsole开发与验证和PrimeHub技能市场分发。PrimeConsole 从开发者社区 dev.primebot.com 的下载页安装Windows / macOS / Linux 各有安装包我用的 1.0.2 Windows 版。打开后主界面只有两个模块边界很清楚1.1 机器人控制连接真机后的工作台实时视频流、运行日志、方向控制、急停复位、动作与表情的快捷触发。不连机器人时是空态——第一次打开会觉得这软件怎么什么都没有其实它在如实告诉你第一步永远是连接设备。1.2 Skill 验证本文主战场这一页面向的不是真机而是技能包.rpk文件。拆开看有六块区域内容左侧技能面板已导入技能列表、当前选中技能的包名/版本/机型原子能力列表PrimeConsole 解析出的技能所调用的能力语音合成、预设动作、表情播放、LED 灯效源码视图解析结果的 JSON 展示含 skillId / version / robotModel / atomicCapabilities3D 仿真视口开始模拟仿真 / 复位仿真 / 部署到机器人按钮右上角挂着一条容易被忽略的提示“只能仿真上肢动作”验证报告最近 3 条验证记录右下机器人状态未连接时的健康检查占位两个入口按钮在验证报告面板下导入 .rpk和上传到 PrimeHub——从本地包到市场上架全程不用离开这个应用。1.3 先说结论仿真能验证什么把结论放在前面能省掉后面所有困惑PrimeConsole 不执行你的代码。它做的是静态扫描——解析包结构和元数据、识别你调用了哪些原子能力、把代码里引用的预设动作编号收进一个队列点开始模拟仿真时按队列在 3D 模型上回放这些内置预设动作。这意味着两件事PrimeConsole 把输出面验证得很周到包结构合法性、原子能力识别、动作引用回放全都不需要真机而触发与业务逻辑语音识别、节流、状态机这层平台的设计是交给开发者自测第七节给出我的测法仿真的动作面 内置预设库的子集。全预设编排的技能仿真即真机效果带自研轨迹的技能仿真只能看到回退动作。理解了这条边界下面的一切都顺理成章。二、开发环境比想象中轻Q1 的 SDK 二次开发环境是 Ubuntu 22.04 ROS2 Humble编译 aimdk_msgs、跑 ROS2 节点。但**做技能包不需要 **ROS——这条轻量发布链全程 Windows 可完成工具用途Windows Python 3纯标准库写 main.py、打包 .rpkPrimeConsole 1.0.2导入、静态验证、仿真、上架Q1 SDK v1.0.0.0 文档接口依据《接口说明.md》接口协议 PDF 均随 SDK 提供可选WSL2 ROS2 Humble无真机的端到端逻辑测试第四节的 mock 方案三、技能包解剖三个文件一个包.rpk本质是 ZIP压缩包根目录放三样东西hug_buddy_1.0.1.rpk (ZIP) ├── main.py # 入口ROS2 节点全部业务逻辑 ├── cfg/pkg.yaml # 包元数据 └── README.md # 技能说明把后缀改成.zip用任意解压工具打开看到的就这三样——没有二进制、没有依赖地狱结构透明到可以用文本编辑器逐行读完cfg/pkg.yaml的字段实测反推官方未公开规范name: hug_buddy # 技能名 package_name: hug_buddy # 必须与 name 同时写 version: 1.0.1 author: your_name robot_model: q1 # 机型 description: 一句话描述第一个坑就在这只写name不写package_name导入后包名显示unknown。社区文章实测过我复核属实。打包脚本只需要 Python 标准库import zipfile from pathlib import Path SKILL_DIR Path(skill) with zipfile.ZipFile(dist/hug_buddy_1.0.1.rpk, w, zipfile.ZIP_DEFLATED) as zf: for path in sorted(SKILL_DIR.rglob(*)): if path.is_file() and __pycache__ not in path.parts: zf.write(path, path.relative_to(SKILL_DIR).as_posix())注意两点cfg/pkg.yaml的相对路径必须原样保留不能拍平到根目录所有文件 UTF-8 编码——台词里有中文编码错了真机 TTS 会念乱码。四、五个服务一个话题API 调用速查抱抱补给站用到的全部接口服务名前缀/aimdk_5Fmsgs/srv/是平台固定写法能力接口关键参数语音识别话题/aima/agent/asr_resulttext / is_final / confidence台词PlayTtspriority_level.value 6交互档、is_interrupted表情PlayEmotionemotion_ids[表情编号]、loop_count1灯效LedStripCommandled_strip_mode254自定义呼吸 RGB period预设动作SetMcPresetMotionmotion.value动作编号、interrupt运控状态GetMcAction/SetMcAction动作前置态准备下文三个实战要点① 预设动作有前置态。SetMcPresetMotion要求运控处于BIPED_WHOLE_BODY_CTRL。从默认站立态过去要先过桥接态调用前查一次当前状态、必要时切两步这段做成 best-effort失败不阻塞动作请求照发被拒就跳过——交互类技能不值得为状态机卡死主流程。②TTS是异步的。服务返回成功只代表进了队列说完没说完要自己估时经验值 200ms/字。排动作节奏时按台词起 0.3~0.5 秒后再动胳膊处理体验最自然。③ 防自听自话。机器人自己说的台词里含触发词“抱抱补给站开张啦”麦克风可能识别成新触发。解法是 busy 锁覆盖整个序列 冷却时间从序列结束起算实测能挡住回声循环。五、完整案例抱抱补给站的 160 行5.1 设计三段式编排动作全部来自内置预设库招手、拥抱、双手比心段落动作台词灯效上门招手“抱抱补给站开张啦我来了”暖橙呼吸拥抱拥抱“张开手接好咯——”暖橙呼吸收尾双手比心“难过的时候我的抱抱免费无限量供应。”粉色呼吸 → 白色呼吸截至笔者发稿技能市场还没有技能用到拥抱这个动作——纯陪伴向也是空位。5.2 触发语音关键词HUG_KEYWORDS (抱抱, 抱一下, 拥抱, 难过, 不开心, 安慰) def on_asr(self, msg: AsrResult): if not msg.is_final: return if msg.confidence and msg.confidence 0.5: return text (msg.text or ).strip() if not any(k in text for k in HUG_KEYWORDS): return self._try_trigger(f语音「{text}」)_try_trigger里做 busy 冷却双重检查通过后开工作线程跑序列——别在回调里直接跑会堵住 executor服务响应都收不回来。5.3 动作调用一个方法一个动作def _motion_hug(self): if not self.motion_cli.wait_for_service(timeout_sec1.0): return req SetMcPresetMotion.Request() req.header RequestHeader() req.header.stamp self.get_clock().now().to_msg() req.source hug_buddy req.motion.value 3018 # 拥抱——必须写字面量 req.interrupt True self.motion_cli.call_async(req)为什么三个动作拆成三个方法、编号写死在赋值语句里这是被静态扫描逼的第六节细说。5.4 打包、导入、仿真python build.py产出 5.6KB 的.rpk→ PrimeConsole 导入 → 原子能力四项全识别语音合成 / 预设动作 / 表情播放 / LED 灯效→ 点开始模拟仿真3D 里的 Q1 依次招手、张开双臂、双手比心。全预设编排的好处在这里兑现仿真队列和真机行为完全一致导出即所见。六、PrimeHub 生态上架前先看清市场技能写好只是上半场分发决定它被谁看见。动笔写代码前建议先把 PrimeHubskillhub.primebot.com逛一遍——游客可浏览全部技能卡片下载需手机验证码登录。以下是我发稿时的市场观察。6.1 一个上线一个月的市场长什么样笔者抓取时的快照十余个技能、总下载四百次上下规模还小但结构性要素已经齐了官方示范带节奏下载量前三视频电话、拿衣服、天气预报都是社区上线时预埋的官方示范技能贡献了约六成下载量——应用商店冷启动的通用打法社区最活跃的突破口是对话下载最高的社区技能 PrimeBuddy 是自定义对话框架接管原厂对话 Agent其后还有 Tina 语音助手、WorkBuddy 连接器——用户最想定制的不是动作是脑子技能依赖链萌芽Yeelight 灯控技能声明需另行安装 PrimeBuddy——技能之间出现依赖关系这是市场从展示柜走向生态的早期标志评价体系尚未启动全部技能的浏览、喜欢计数为零下载量是唯一活跃指标6.2 发布表单要点上传入口就在 PrimeConsole 验证报告面板下“上传到 PrimeHub”表单字段技能名称、版本号与包内 pkg.yaml 一致、一句话描述、分类、机器人类型Q1、标签、图标。提交后刷新最近上新即可看到——从写第一行代码到市场上架一个桌面应用走完全程。七、无真机怎么办mock 服务的端到端测试仿真能替我确认包没写错、动作排对了但喊一声抱抱服务就按顺序出发这条业务链路平台按设计留给了开发者。为了让它在上真机前就有底气我在 WSLUbuntu 22.04 ROS2 Humble 编译好的 aimdk_msgs里写了一个mock** 机器人**六个服务的假实现 语音话题发布器被测技能作为子进程跑stdout 逐行收集断言class MockRobot(Node): def __init__(self): ... self.create_service(SetMcPresetMotion, /aimdk_5Fmsgs/srv/SetMcPresetMotion, self.on_preset_motion) def on_preset_motion(self, req, res): self._log(fMOTION: value{req.motion.value}) # 记录请求 res.response.header.code 0 return res14 条断言覆盖关键词命中、busy 期回声不重复触发、动作按 招手→拥抱→比心 有序下发、灯效双色切换、状态机先桥接后目标、冷却后二轮服务完整跑通。14/14 通过再打包这套 mock 思路对任何语音/触摸触发型技能都适用。踩过的一个测试坑值得记录DDS 在进程启动后的发现期会丢消息靠 sleep 留余量的触发时序偶发失败。改成事件驱动后根治——发一条触发消息轮询技能日志出现[触发]再继续没出现就重发测试从间歇性绿变成稳定绿。测试通过后回到第六节的发布流程改好署名、重新打包、上传表单、上架——抱抱补给站就开张了。八、这条工具链适合谁三种情况三种走法最后按情况给点选型建议都是这几天实操下来的体会第一次做技能、机器上没有ROS环境本文的路线就是为你写的。Windows Python 标准库完成写包与打包PrimeConsole 包办导入、验证、仿真、上架全程不碰命令行。如果技能动作全部选自内置预设库仿真里看到的就是真机效果——成品感来得最快。手上已有 ROS2 环境WSL 或双系统图形端和命令行不是二选一而是分工。PrimeConsole 管包验证和发布业务逻辑交给第七节那样的 mock 服务在本地闭环测试两边共用同一套 aimdk_msgs 协议代码拿来就能跑。真机联调时命令行还能做 PrimeConsole 覆盖不到的深度控制和自动化测试。手上有真机PrimeConsole 基本可以当默认工作台——连接、日志、视频流、动作调试、验证、发布一站式。建议保留开发者模式下的 SSH 通道图形界面看状态、命令行查细节两边互为备份。写在最后回到那天晚上想要的那个抱抱。技能做出来后我让仿真里的 Q1 对着我张开了手臂——理性知道那只是一段预设关节轨迹的回放但难过的时候我的抱抱免费无限量供应这句台词亮起来的时候还是被治愈了一下。技术的意义大抵如此它不能替你消化情绪但它可以认真地接住你。希望某个加班到深夜的人喊一声抱抱会有一台小机器人认真地张开手臂。「抱抱补给站」已上架 PrimeHub 技能广场skillhub.primebot.com 搜索抱抱补给站喊一声抱抱就能收到机器人的拥抱欢迎大家前往体验。有问题欢迎评论区交流。更多资料获取启元机器人开发者社区 https://dev.primebot.com/PrimeHub 技能市场skillhub.primebot.com
)
