PrimeBot 启元 Q1 & T1 技能整活工作台
🏠 整活工作台总门户 / 核心必读阁 / 🚀 从 0 到 1 开发启元 Q1 / T1 机器人技能：大白话搞笑闯关攻略
STEP-BY-STEP SOP · 零门槛主线攻略
STEP-BY-STEP SOP · 零门槛主线攻略

🚀 从 0 到 1 开发启元 Q1 / T1 机器人技能：大白话搞笑闯关攻略

扒开 .rpk 的底裤，手把手带你走完 0→8 步全流程

😜 调皮课代表大白话划重点（30 秒读懂核心）
别被「机器人技能开发」六个大字唬住！所谓的 .rpk 技能包其实就是个改了后缀名的压缩胶囊，里面就塞了 3 样核心宝贝（技能户口本、演出台词剧本、玩法说明书）。跟着这页从 Step 0 敲到 Step 8，哪怕今天第一次摸机器人也能丝滑通关！
启元 Q1 & T1 技能开发工作台全景架构
🔍 启元 Q1 & T1 技能开发工作台全景架构（点击图片全屏放大）
🙋‍♂️ 这份秘籍是写给谁看的？
哪怕你之前连螺丝刀都没摸过、一行机器人代码都没写过，只要顺着这份图文指南往下滑，10 分钟内保证你用大白话彻底悟透：神神秘秘的 .rpk 技能包到底是个啥、怎么改几句中文台词就变出新技能、怎么一份代码同时讨好 Q1（人形）和 T1（变形修勾）两尊大神、怎么在任意浏览器里顺走登录凭证，以及怎么在活动现场稳稳跑通真机、上架拿满分！
🚨 保命红线先拍桌：在自己电脑上跑通“虚拟替身测试”绝对不等于真机跑通！那只是棚拍彩排！到了现场必须清空机器人周围 1 米、核对机上真实动作表、真机实弹连续跑通两轮后，才能执行市场发布！

一、3 分钟剥洋葱：别被高科技术语唬住了，我们在干嘛？

1.1 扒开 .rpk 技能包的马甲：其实就是个改了姓的 .zip！

很多萌新以为给机器人写技能得装上百 GB 的 ROS2 仿真器、推导微积分运动学方程……快醒醒，根本不用！ 在启元 Q1 和 T1 的普通用户路径（lumina 运行时）下：

  • 一个所谓的 .rpk 机器人技能包，本质上就是把 .zip 压缩包改了个后缀名！
  • 你要是拿解压软件把它扒开，里面就孤零零躺着 3 个小文件（看上面那张图的底部）：
  • 户口本 / 身份证（pkg.yaml）：一共就 6 行字！写着技能的唯一英文小名（package_name）、版本号（version），以及这包是喂给谁吃的（robot_model: q1 还是 t1，千万别把狗粮喂给猫，两机型严禁混装！）。
  • 演出剧本（main.py）：用最基础的 Python 写的流水账剧本——比如“先大喊一声欢迎光临 ➔ 等嘴巴彻底闭上 ➔ 挥挥手耍个帅 ➔ 保持姿势 6 秒 ➔ 再抽支幸运签”。
  • 相亲简历 / 说明书（readme.md）：夸夸你这个技能有多好玩，顺便提醒大家离机器人 1 米远。

1.2 机器人肚子里的“贴心老管家”是怎么帮你的？

当你把 .rpk 塞进机器人肚子里并按下运行键时，幕后发生了这三件事：

  1. 机器人身体里住着一位常驻后台老管家，名叫 lumina_server（天天守在机器人本机的 127.0.0.1:58080 端口听候差遣）。
  2. 老管家拆开你的包，拿出剧本准备开演。在拉起代码的前一毫秒，老管家会偷偷往你的 Python 全局变量兜里塞进一个现成的万能遥控器——名字就叫 robot！
  3. 所以你在代码里千万别写 import robot（你一写，Python 就会去系统库里找一个叫 robot 的模块，找不着当场给你表演 ImportError 原地去世）！你只需要直接调 robot.play_tts("哈喽") 它就张嘴叭叭，调 robot.play_animation(3001, False) 它就开始挥手！

1.3 工作台从 0 到 1 帮你备好了哪 7 件“作弊级装备”？

装备编号我们提前造好了啥？课代表大白话翻译：这能帮你省多少头发？详情直达
装备 ①大白话秘籍与防坑指南把飞书文档和长篇手册里的深坑全挖出来标好红旗，还备好了喂给 AI 的现成咒语保命必读阁
装备 ②3 套开箱即用剧本模板既有全能王《启元百变互动官》（抽签+联网金句带断网自动兜底+呼吸灯），又有纯离线保底王《社交能量补给站》，还有官方《点歌台》技能剧本库
装备 ③独立 Python 温室环境已经把难装的国密加密库 gmssl 乖乖关进独立虚拟环境里，开箱即跑军火工具箱
装备 ④全浏览器顺 Token 神器官方原版只认 Firefox；我们升级了提取器，Chrome、Edge、Brave、Firefox 随便你用哪个登录都能一键顺出凭证，还支持 --token 直接塞！顺 Token 神器解析
装备 ⑤“一源双包”影分身构建器现场抽签分到 Q1 还是 T1？不怕！你只管改 1 份代码，构建器自动帮你克隆并吐出 Q1 和 T1 两个独立 .rpk 包和上架配置！影分身构建器解析
装备 ⑥0.4 秒赛博替身演武场没连真机前，用“快进时钟 + 假机器人替身”在电脑上 0.4 秒跑完 19 项正常与花式翻车测试，把 Bug 扼杀在摇篮里替身演武场解析
装备 ⑦真机一键侦察与点火器现场不用手抖敲长串 ssh/scp，一条命令自动连机器、抓机上真实动作表、传包、跑技能、捞硬件日志真机点火器解析

二、写代码前必背的“五条保命铁律”（踩一条真机就装死给你看）

机器人 lumina 运行时原理与 Q1/T1 动作红线图解
🔍 机器人 lumina 运行时原理与 Q1/T1 动作红线图解（点击图片全屏放大）

很多同学（以及没读过本秘籍的野生 AI 助手）写出来的代码一上真机就哑火，99% 是栽在上面这张图的 5 个坑里（详细技术解剖见 机器人运行时契约与避坑指南）：

  1. 🚫【铁律 1】打死别写 import robot，也别碰 ROS2 (rclpy)！
  2. robot 是管家塞给你的全局变量，写 import robot 必报 ImportError！而且机上只有 Python 3.10 标准库（time、json、random、urllib.request 等），别乱导第三方野包。
  3. 🤖【铁律 2】Q1 和 T1 脾气完全不同，动作 ID 严禁串门！
  4. Q1（人形社牛）：普通用户室内模式下，它的腿被安全结界封印了——所有全身动作（whole_body）都会被硬件无情驳回（报 reason 24）！只能用上半身动作（upper_body 3000系：比如 3001 招手、3008 加油、3007 双手比心）。
  5. T1（变形修勾）：有双足站立（biped）和四足趴着（quadruped）两种形态，上场前必须先调 robot.get_t1_robot_form() 问问它现在几条腿着地。四足形态下只认 1 / 7 / 26 / 43 四个动作（敢调别的直接报 reason 19 罢工）。最聪明偷懒的做法：直接用双形态通吃的 26（撒欢喜悦）和 43（律动），站着趴着都能扭！
  6. 🗣️【铁律 3】说话（play_tts）是个急性子，必须用 speak() 盯着它闭嘴满 0.7 秒！
  7. robot.play_tts("第一句") 是异步的，调完 0.001 秒代码就往下跑了。如果你不拦着，第二句会直接把第一句掐脖子截断（俗称“吞字惨案”）！
  8. 更调皮的是，机器人念长句子中间大喘气时，音频状态偶尔会从 1（正在说）闪一下 2（假装空闲）又跳回 1。所以我们的 speak() 函数立下了死规矩：必须连续稳定空闲满 0.7 秒，才算你真的把话说完了！
  9. 🕺【铁律 4】做动作一律传 interrupt=False，还要乖乖 time.sleep 等它扭完！
  10. 黄金节奏：先等嘴巴彻底说完话 ➔ 再调 robot.play_animation(动作ID, interrupt=False) ➔ 再 time.sleep(保持秒数) 等动作做完。要是手欠传了 interrupt=True，正在播的声音会被当场一刀切掉！
  11. 🖨️【铁律 5】所有的 print() 必须系上安全带 flush=True！
  12. 写成 print("SPEAK 哈喽", flush=True)。不加 flush=True 的话，日志全憋在内存缓冲区里，真机调试时你盯着空白屏幕会怀疑人生。

三、从 0 到 1 八步通关实操（跟着敲命令，闭眼过关）

从 0 到 1 开发启元 Q1 / T1 机器人技能 8 步作战图
🔍 从 0 到 1 开发启元 Q1 / T1 机器人技能 8 步作战图（点击图片全屏放大）
🧰 开工姿势：打开终端即可直接运行以下所有命令（你也可以在 交互式总门户 顶部的联动台里填好现场 IP，一键复制自动填好参数的命令！）。

Step 0：环境一键体检（耗时 30 秒）

先派 开工体检仪 看看你的电脑上 Python、国密库 gmssl、ssh/scp/curl 以及 PrimeHub 云端搜索接口是不是都活蹦乱跳：

💻 bash
python Tools/scripts/preflight.py
  • 🎉 怎么算过关？ 看到终端欢快地吐出 Python 3.12.9、gmssl: 3.2.2、搜出官方的 51 点歌台，最后一行出现： PREFLIGHT_OK（本机工具与 PrimeHub 网络连通正常；账号登录与真机运行请按步骤继续验收）

Step 1：随便开个浏览器登录 PrimeHub，一键顺走 Token 凭证

多浏览器 Token 提取与 PrimeHub 发布闭环图
🔍 多浏览器 Token 提取与 PrimeHub 发布闭环图（点击图片全屏放大）

最后一步把技能发上 PrimeHub 市场需要登录凭证（有效期约 7 天；工作台已提前提取验证过一次，有效期至 2026-10-30 18:29:25。如果过期或换你自己的手机号上场，按下面三步走）：

🔥 史诗级省心升级：我们的 全浏览器顺 Token 工具 已经打通任督二脉，支持 Chrome、Microsoft Edge、Brave、Chromium 和 Firefox 全家桶，再也不用为了提个 Token 专门去下火狐浏览器了！
  1. 打开你电脑上最顺手的浏览器（Chrome / Edge / Firefox 随便挑），打开 https://primehub.primebot.com ，手机号+验证码登录，随便点一下页面。
  2. 回到终端敲这一行命令（连浏览器都不用关，脚本会自动复制底层数据库快照防锁死）：
💻 bash
   # 自动扫描所有主流浏览器，顺走最新鲜的 Token：
   python Tools/primehub_dev_kit/extract_token.py
  • 想指定只从 Edge 或 Chrome 顺？ 加个参数就行：
💻 bash
     python Tools/primehub_dev_kit/extract_token.py --browser edge
  • 终极保底大招（F12 直接粘贴）： 万一你用的是奇葩小众浏览器，直接在网页按 F12 ➔ 点 Application（应用）➔ 展开左侧 Local Storage 下的 https://primehub.primebot.com ➔ 复制 skillhub_token 那串 eyJ... 开头的字符，然后敲：
💻 bash
     python Tools/primehub_dev_kit/extract_token.py --token "粘贴你复制的eyJ字符串"
  1. 验明正身（看看凭证能不能打开自家仓库）：
💻 bash
   python Tools/primehub_dev_kit/primehub_publish.py my
  • 只要没报错（哪怕还没发过技能输出空行），就说明你的发版通行证 100% 绿灯！

Step 2 & Step 3：去剧本库挑个模板，3 分钟改成你的脑洞大作

打开 技能剧本库导览，里面躺着 3 套定位各异的完整技能：

剧本入口艺名性格特点与整活方向
《启元百变互动官》
(核心剧本精讲)		C位全能王
（★强烈推荐）		机关最多、最好改！ 自带：好记的英文动作别名（greet / cheer / heart，不用背数字）+ 随机好运盲盒池（LUCKY_POOL）+ 联网拉每日金句（拔掉网线也能 100% 自动秒切回离线保底词，绝不当众社死）+ 呼吸灯带变色气氛组！
《社交能量补给站》
(核心剧本精讲)		纯离线稳健王
（★保底首选）		全篇仅 78 行代码，干净利落的「开场 + 勇气/灵感/快乐三格充电 + 谢幕」，零外网依赖，最适合先上真机跑通把 40 分基础分锁死！
《官方点歌台》
(核心剧本精讲)		高阶炫技参考展示怎么联网搜歌下载、调 ffmpeg 转 .wav、用纯标准库算音频 BPM 节拍，并让机器人在音乐里卡点蹦迪。

🎨 怎么花 3 分钟把《启元百变互动官》改成你的新作品？

点开 《启元百变互动官》核心剧本精讲，你根本不用管底下的硬件轮询逻辑，只需要改最顶部的 【第一部分：积木配置区】（第 15~65 行）：

💻 python
# 功能开关（想开哪个改 True，想关改 False，跟按电灯开关一样简单）
ENABLE_NET_QUOTE = False         # True=联网拉取每日金句（没网也会自动用 FALLBACK_QUOTE 兜底！）
ENABLE_RANDOM_DRAW = True        # True=从 LUCKY_POOL 随机抽签；False=固定抽第一支签
ENABLE_MOOD_EFFECTS = True       # True=顺便点亮呼吸灯带当气氛组

# 随机互动签文池：(签文台词, 动作别名 "greet"招手 / "cheer"加油 / "heart"比心)
LUCKY_POOL = (
    ("叮！为你抽到「真机丝滑上上签」！今天你的所有动作指令全部一次通过！", "cheer"),
    ("叮！为你抽到「脑洞大开幸运签」！你的创意全场最亮眼，评委看了都点赞！", "heart"),
    ("叮！为你抽到「零Bug欧皇签」！编译不报错，网络不超时，好运直接拉满！", "greet"),
)
  • 想改成「赛博算命摊 / 运势塔罗牌」？ 把 OPENING_LINE 和 LUCKY_POOL 里的词换成你的毒舌/吉利算命词，收工！
  • 想改成「联网天气主播 / 每日诗词朗诵家」？ 把 ENABLE_NET_QUOTE 改成 True，换上你想调的 JSON 接口，再把 FALLBACK_QUOTE 写成断网保底词，哪怕现场 Wi-Fi 炸了你也能优雅播完！
  • 想偷懒让 AI（Claude Code / Cursor / Codex）帮你大改？ 去 机器人运行时契约与避坑指南 第六节，把写好的标准咒语直接复制粘贴喂给 AI！

Step 4：启动“一源双包”影分身构建器

一源双包构建流水线与本机替身仿真框架图
🔍 一源双包构建流水线与本机替身仿真框架图（点击图片全屏放大）

改完代码后，千万别自己手动去压缩 zip 或改配置！在终端敲这一行（原理剖析见 一源双包构建器精讲）：

💻 bash
python Tools/scripts/build.py
  • ✨ 它在幕后干了啥？ 它会自动把两套技能各自复印两份，分别注入 Q1 专属配置和 T1 专属配置，一口气在 双机型成品库 吐出 4 个 .rpk 安装包 + 4 个配对的上架配置单！

Step 5：0.4 秒“赛博替身”试毒（不连真机先抓虫）

在把包发给真机之前，先让电脑里的“虚拟机器人替身 + 时间快进器”帮你把所有分支虐一遍（19 关详情见 0.4 秒赛博替身演武场）：

💻 bash
python -m unittest discover -s Tools/tests -v
  • 🎉 怎么算过关？ 只花 0.4 秒就刷刷跑完 19 项单元测试，最后霸气打印 Ran 19 tests in ...s 且 OK！ (这意味着：无论是 Q1、T1 双足还是 T1 四足，无论是中间喘气抖动 0.3 秒还是突然拔掉网线，你的代码全都应对自如，连包里的结构都挑不出半点毛病！)

Step 6：到达活动现场 ➔ 连真机探路、核对动作表与实弹起跳

启元开发者官网实景与现场 2.5 小时安全排障速查图
🔍 启元开发者官网实景与现场 2.5 小时安全排障速查图（点击图片全屏放大）

到了现场领到真家伙后，按下面三步稳扎稳打（千万别莽）：

6.1 上机前“安全三结界”（一票否决保命线！）

  1. 半径 1 米净空结界：机器人挥起胳膊来可不长眼，周围 1 米内清走水杯、电脑和围观群众。
  2. 先蹲着再站着（先低位后站立）：第一次上机先在安全低位姿态下试跑，确认动作温和不抽风，再站立演示。
  3. 别抢方向盘（严禁同时用手机 App 遥控）：代码运行期间，谁也别拿手机 App 去点遥控，否则底层运控觉得“怎么有两个脑子指挥我”直接触发冲突保护停机！

6.2 第一阶段：先派侦察兵探路 + 抓机上真实动作表 + 传包（先别加 --run！）

根据现场导师分给你的机型（q1 或 t1）和局域网 IP，运行 真机侦察与点火器：

💻 bash
# 侦察 Q1 机器人并上传《启元百变互动官》（若是 T1 就把 --model 改成 t1；想稳健保底可换 --skill energy_station）
python Tools/scripts/robot_run.py --model q1 --ip 192.168.112.222 --skill universal_skill

(终端弹出密码提示时敲 1 回车。脚本会自动把机器人肚子里的真实动作表抓回来归档，顺手瞄一眼确认咱们的动作 ID 在表里有名有姓。)

6.3 第二阶段：追加 --run 正式点火起跳 + 查硬件小账本

确认周围 1 米没人后，在刚才那条命令屁股后面加上 --run：

💻 bash
python Tools/scripts/robot_run.py --model q1 --ip 192.168.112.222 --skill universal_skill --run
  • 👀 跑完重点盯哪 3 样证据？
  • 盯终端 final: success 与谢幕口号：stdout 最后一行必须帅气打出 UNIVERSAL_SKILL_DONE steps=3（或 ENERGY_STATION_DONE steps=3）。
  • 盯硬件动作小账本（task_engine.log）：脚本会自动捞出最后 12 条硬件日志，确认 3 个动作都有 创建Animation task成功，没有任何 reason 24 / 19 / 42 / 28 / 17 傲娇拒绝码！
  • 竖起耳朵听现场播音：确认 5 段台词字正腔圆、一字不落，没有半路被截胡。

Step 7：上架前黄金铁律 —— 真机连续跑通两轮！

跑通一次叫运气，连续稳稳跑通两轮才叫实力！再敲一次 Step 6.3 的 --run 命令，把下面 6 个勾全部打满（详细清单见 现场 2.5 小时行动与安全清单）：

  • 户口对得上：现场真机型号（Q1 或 T1）和装进去的技能包完全一致。
  • 动作表验过货：机上真实动作表已抓回并核对无误。
  • 两轮双响炮 final: success：连续两轮 stdout 都顺利抵达 *_DONE steps=3。
  • 硬件账本全绿：两轮硬件日志里，每个动作都印着 创建Animation task成功。
  • 耳朵验货通过：两轮 5 段台词全都清晰播完，不吞字、不抢拍。
  • 安全结界完好：全程保持周围 1 米净空、先低位后站立，没人拿手机 App 添乱。

Step 8：发射火箭上架 PrimeHub 技能市场 & 手机 App 终极路演

两轮真机实弹验收全绿后，执行上架命令把最后 10 分收入囊中（原理剖析见 市场发版火箭筒精讲）：

💻 bash
# 【首选 A】发布《启元百变互动官》（若现场是 T1 请把两个 q1 换成 t1）：
python Tools/primehub_dev_kit/primehub_publish.py publish Tools/dist/universal_skill_q1.rpk --metadata-file Tools/dist/publish_universal_q1.json

# 【保底 B】或者发布《社交能量补给站》：
# python Tools/primehub_dev_kit/primehub_publish.py publish Tools/dist/energy_station_q1.rpk --metadata-file Tools/dist/publish_q1.json

# 查查自家在架列表 & 全网公开搜索验货
python Tools/primehub_dev_kit/primehub_publish.py my
python Tools/primehub_dev_kit/primehub_publish.py search "启元百变互动官 Q1"
  • 🎊 上架成功暗号：终端返回 {'code': 1000, 'msg': '成功'}。
  • ⚠️ 防重影小贴士：PrimeHub 市场是个实在人，同名技能重复 publish 不会覆盖旧版，而是会生出双胞胎条目！如果改了代码想换新版，先用 python Tools/primehub_dev_kit/primehub_publish.py delete <技能ID> 把旧的请下架，再发新的。
  • 📱 手机 App 终极封神路演：掏出装了启元官方手机 App 的手机 ➔ 去技能市场搜出你的大作 ➔ 点「下载/部署」➔ 点「运行」➔ 看着机器人当着评委和全场的面完整演完一遍，完美收工！
🏠 返回整活工作台总门户 🗺️ 查看全站专题导航地图 ⬆️ 回到顶部