更新时间：2026-10-25（Asia/Shanghai）
这份文档专门写给接手当前工作台、准备奔赴活动现场实操的小伙伴。 我们的目标是：用同一套代码底座同时搞定启元 Q1（人形）和 T1（双足/四足变形）两个机型的技能包，到现场完成真机实弹两轮验收，最后帅气上架 PrimeHub 技能市场。
📌 诚实状态播报（严守规则底线）：
双型号配置、一键打包、0.4秒虚拟替身测试、全浏览器 Token 提取和真机自动化探测脚本已经 100% 搞定；但真实机器人连接探测、真机实弹运行、连续两轮验收和 PrimeHub 最终上架，必须等你到现场拿到真机后亲自完成！千万别把电脑离线替身跑通当成真机跑通哦！
一、手里有哪两张王牌技能？（二选一或现场随时改）
我们在 技能剧本库 下准备好了两套可以直接打包上真机的技能（外加一套 官方点歌台 参考）：
- 👑 王牌 A：《启元百变互动官》（强烈推荐首选）
- 演什么：元气迎宾问候 ➔ 每日灵感广播（支持联网调 API，且断网 100% 自动切回离线保底金句）➔ 随机好运盲盒抽签（从
LUCKY_POOL抽签并搭配对应动作）➔ 谢幕祝福，还自带呼吸灯带氛围联动！ - 🛡️ 王牌 B：《社交能量补给站》（纯离线稳健保底版）
- 演什么：开场欢迎 ➔ 勇气充电 ➔ 灵感充电 ➔ 快乐充电 ➔ 收场祝福。仅 78 行代码，零网络与外部音频依赖，稳如泰山。
两套技能都严格遵守 lumina 运行时契约：只用 Python 3.10 标准库和系统自动注入的全局 robot 对象，绝不写 import robot、rclpy 或 ROS2；每句台词都经过 0.7 秒 连续稳定空闲防抖轮询后才触发动作。
二、核心导航传送门
| 核心专题 | 一句话说清它是干嘛的 |
|---|---|
| 整活工作台总门户 | ★ 全彩交互式总控台（含现场 IP/机型参数联动台、一键复制与打勾表） |
| 从零开发 Q1/T1 技能 8 步 SOP | 从 0 到 1 开发 Q1/T1 技能的大白话图文全流程 SOP（首选阅读） |
| 机器人运行时契约与避坑必读 | 5 条保命铁律、robot API 说明书、动作白名单与喂给 AI 的提示词咒语 |
| 《启元百变互动官》核心源码精讲 | 通用全能技能源码（带逐段大白话导读） |
| 《社交能量补给站》核心源码精讲 | 78 行极简离线保底技能源码 |
| 一源双包影分身构建器 | 同时生成 Q1 和 T1 的 .rpk 安装包与上架配置 |
| 真机一键侦察与点火器 | 真机 SSH 侦察、拉取机上 YAML 动作表、上传与运行脚本 |
| 0.4 秒虚拟替身测试演武场 | 假机器人替身演武场与包结构自动化测试 |
| 成品弹药库检视面板 | 已生成的 4 个 .rpk 安装包与 4 份上架元数据面板 |
| 赛前准备验收记录 | 前期准备、鉴权实测与诚实边界记录 |
| 赛前准备状态与命令说明 | 赛前准备状态总表与公开活动信息核对摘要 |
| 官方开发到上架通用手册 | 官方开发到上架全流程手册 |
🔒 保密叮嘱：登录凭证受严格保护，任何时候千万不要打印、截图、复制明文或写进公开交接记录！
三、Q1 与 T1 双机型配置对照表（千万别装错包！）
| 分配机型 | 对应安装包 | 包内 robot_model | 发布机型 ID / Code | 预设安全动作 ID |
|---|---|---|---|---|
| 🤖 Q1 人形 | universal_skill_q1.rpkenergy_station_q1.rpk | q1 | 100 / robot_q | 3001 (招手) / 3008 (加油) / 3007 (比心) |
| 🐾 T1 变形 | universal_skill_t1.rpkenergy_station_t1.rpk | t1 | 101 / robot_t | 26 (喜悦) / 43 (律动) / 26 (喜悦) |
- 为什么这么配？
- Q1 在室内普通模式下禁用全身动作（否则报
reason 24），所以严格只用upper_body白名单动作。 - T1 运行时会先调
get_t1_robot_form()查验当前是biped（双足）还是quadruped（四足），并选用四足也允许的26 / 43（避免报reason 19）；万一读出未知形态会立刻报错停机。 - 🚨 严禁混装：绝对不要把 Q1 的包塞给 T1，也别把 T1 的包塞给 Q1！上架时的配对配置也必须和对应的
.rpk成对使用。
四、前期已经帮你跑通了哪些测试？
我们已经完成了全套赛前热身：
- ✅ 《社交能量补给站》与《启元百变互动官》的 Q1 / T1 共 4 个
.rpk安装包构建完毕； - ✅ 每个
.rpk均包含标准的户口本、主剧本与说明文档三件套； - ✅ 虚拟替身模拟跑通 Q1、T1 四足、T1 双足全部分支（每轮 5 段台词 + 3 次动作 + 抵达
*_DONE）； - ✅ 模拟覆盖音频不起声、超时不结束、非法音频状态、0.3秒假空闲抖动、断网自动降级、动作被拒、T1 未知形态等全套异常熔断测试；
- ✅ 全浏览器（Chrome / Edge / Brave / Firefox）Token 提取与 SQLite WAL 快照单元测试全过；
- ✅
ssh、scp、curl与 PrimeHub 匿名市场搜索（code=1000）预检全绿。
(再次敲黑板：以上只证明源码逻辑、包结构和工具链健康，不代表真机喇叭出声了、电机真动了或现场安全达标了！)
五、到了活动现场怎么操作？（最短夺冠路径）
第 1 步：找现场导师问清 5 件事 & 设好安全结界
- 今天分给我们的是 Q1 还是 T1？
- 机器人的局域网 IP 地址是多少？（SSH 默认用户
run，密码1） - ⭕ 周围 1 米净空：把机器人半径 1 米内的人、椅子、水杯全清走。
- 🛑 急停在哪：确认急停按钮位置和按法，初次测试先低位姿态再站立姿态。
- 📵 没人在用 App 遥控：确认没有队友或旁观者同时拿手机 App 遥控这台机器（会引发运控冲突保护）。
第 2 步：先派侦察兵探路 + 抓动作表 + 上传安装包（先不加 --run！）
打开终端执行：
# 如果现场是 Q1（如果是 T1 就把 --model q1 改成 --model t1）：
python Tools/scripts/robot_run.py --model q1 --ip 192.168.112.222 --skill universal_skill这条命令会自动帮你干完脏活累活：
- 检查 SSH 连通性与远程 Python；
- 探测机器人
127.0.0.1:58080/packages与/tasks/running； - 把机器人肚子里的真实 YAML 动作表（Q1 读
upper_body.yaml，T1 读t1/*.yaml）抓回来保存为探测报告； - 把远程调试器与对应机型的
.rpk上传到机器人临时目录。
第 3 步：瞄一眼抓回来的 YAML 动作表
查看刚刚生成的真机探测报告：
- Q1 确认
3001 / 3008 / 3007在表里； - T1 确认
26 / 43在表里。
(记住：play_animation() 返回 True 只代表请求进了队列，电机真动没动得看下一步的硬件日志！)
第 4 步：真机实弹点火起跳（加上 --run）
确认周围 1 米没人后，加上 --run 参数正式开演：
python Tools/scripts/robot_run.py --model q1 --ip 192.168.112.222 --skill universal_skill --run跑完盯着终端输出看三件事：
final: success：任务顺利完结；stdout结尾出现UNIVERSAL_SKILL_DONE steps=3（或ENERGY_STATION_DONE steps=3）；- 硬件动作日志核验：脚本自动抓取的
task_engine.log末尾里，3 个动作都有创建Animation task成功！
万一日志里没看到成功，而是冒出了 reason 拒绝码，按这张急救表 10 秒钟搞定：
拒绝码 (reason) | 机器人在闹什么脾气？ | 怎么马上哄好它？ |
|---|---|---|
| 24 | Q1 室内模式禁止全身动作 | 换成 Q1 upper_body 白名单动作（如 3001/3007/3008） |
| 19 | T1 形态不匹配（趴着调了站立动作） | 换成四足允许动作（26/43/1/7）或按实际形态分支 |
| 42 | 上一个动作还没做完，队列堵车了 | 把上一个动作后的 time.sleep(hold) 等待秒数调大 |
| 28 | 上一个动作属于霸体不可打断动作 | 等够它的完整时长，或换成短平快的动作 |
| 17 | 机上固件里没这个动作 ID | 对照刚抓回来的现场 YAML 表换个存在的 ID |
第 5 步：梅开二度 —— 连续跑通第二轮！
第一轮成功后，立刻原样再跑一次 --run！ 两轮都必须满足：final: success + 出现 *_DONE steps=3 + 5 段台词亲耳听完无吞字 + 3 个动作硬件日志全成功 + 全程 1 米安全净空。
六、真机验收完 ➔ 一键上架 PrimeHub 市场
只有当真实机器人连续两轮验收全绿后，才执行最后的上架命令！
# 1. 先瞄一眼当前登录凭证是不是活的
python Tools/primehub_dev_kit/primehub_publish.py my
# 2. 只发布现场真机验收过的那款机型（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
# 3. 搜索确认已经全网可见
python Tools/primehub_dev_kit/primehub_publish.py search "启元百变互动官 Q1"- ⚠️ 避坑提醒：同名技能重复
publish不会覆盖旧版，而是会新建第二条！如果网络卡顿不确定发没发成功，先跑my和search看看，别闷头连点发布。 - 📱 终极路演：打开手机上的启元官方 App ➔ 技能市场搜出你的作品 ➔ 下载安装 ➔ 点击运行，让机器人当众演一遍，完美交差！