PrimeHub 技能开发实操 · 技术指南（整理版）

心智模型：一个技能是什么
开发顺序总览
第 0 步：环境与资产盘点（5 分钟，可提前在家做）
第 1 步：注册 PrimeHub（提前在家做）
第 2 步：给 agent 喂机器人契约（成败的分水岭）
   2.1 robot 对象 API（运行时自动注入的全局对象）
   2.2 动作 ID 常用表（权威全量表在机器人上，不在任何 SDK 文档）
   2.3 平台约束 6 条（实测物理事实，写代码前必看）
   2.4 和 agent 协作的方式（模板只是起点，不是天花板）
第 3 步：vibe coding（复制示例改起）
第 4 步：打包 .rpk（1 分钟）
第 5 步：真机调试环（开发主循环，每轮 3 条命令）
第 6 步：验收检查表（全绿才发布）
第 7 步：提取登录账号的浏览器 token（一条命令）
第 8 步：上传 PrimeHub（一条命令，几十秒后全场可搜）
附录 A：常见坑速查
附录 B：示例能力对照

你的技能/
├── cfg/pkg.yaml    # 包名、版本、作者、机型（q1/t1）
├── src/main.py     # 技能逻辑（纯 Python stdlib）
├── readme.md       # 说明（可选）
└── media/          # mp3/mp4 资源（可选，原样落盘）

git clone https://github.com/miracle-techlink/primehub_dev_kit
cd primehub_dev_kit
pip install gmssl
python3 primehub_publish.py search "你好"    # 自检：能返回结果 = 网络+传输层 OK
sshpass -p '1' ssh -o StrictHostKeyChecking=no run@<IP> 'echo OK'   # 机器人连通
sshpass -p '1' ssh run@<IP> 'curl -sI --max-time 8 https://www.baidu.com | head -1'  # 联网类技能才需要

robot.play_tts(text)                        # 说话；异步无完成回调 → 必须轮询等播完
robot.play_animation(anim_id, interrupt)    # 预设动作；返回 bool（True=已受理≠已执行）
robot.play_audio_file(path)                 # 播音频；板载只吃 wav（mp3 无声）
robot.play_light(color, mode)               # 灯带（mode 3 律动）
robot.play_emotion(emotion_ids, ...)        # 屏幕表情
robot.get_audio_play_state()                # → {'pkg_name':..,'state':{'value':1播放中/2空闲}}
robot.get_t1_robot_form()                   # T1 专属：'biped'/'quadruped'
robot.wait("time", seconds)                 # 等待

# Q1：58 个动作（3000 系），上架技能只用 upper_body
sshpass -p '1' ssh run@<Q1_IP> 'cat /robot/software/task_engine/bin/cfg/motions/q1/upper_body.yaml'
# T1：1-72
sshpass -p '1' ssh run@<T1_IP> 'cat /robot/software/task_engine/bin/cfg/motions/t1/*.yaml'

读 SKILL_PUBLISH_GUIDE.md 的 §2 契约。基于 example-jukebox/ 复制改造，改成：〈你的玩法一句话〉。
约束：只用 upper_body 动作、纯 stdlib、遵守 §2.4 平台约束。

我要做一个〈玩法描述〉的机器人技能，请你自己读 dev kit 里的 SKILL_PUBLISH_GUIDE.md §2，
按契约设计实现；有多个方案就先给我方案再写代码。

cp -r example-jukebox my-skill

import time

STEPS = [(3001, "台词一", 3), (3007, "台词二", 3)]   # (动作ID, 台词, 保持秒)

def speak(text):
    robot.play_tts(text)
    deadline = time.time() + max(len(text) * 0.35, 3.0) + 8.0
    time.sleep(0.3)
    while time.time() < deadline:
        if robot.get_audio_play_state().get("state", {}).get("value") == 1: break
        time.sleep(0.12)
    while time.time() < deadline:
        if robot.get_audio_play_state().get("state", {}).get("value") != 1: break
        time.sleep(0.12)

speak("开场白")
for anim, line, hold in STEPS:
    speak(line)
    robot.play_animation(anim, interrupt=True)   # 无音乐并行时允许打断
    time.sleep(hold)
speak("收场白")
print("MY_SKILL_DONE steps=%d" % len(STEPS), flush=True)

python3 pack.py my-skill
python3 -m zipfile -l my-skill.rpk     # 校验：必须含 cfg/pkg.yaml 与 src/main.py

sshpass -p '1' scp -o StrictHostKeyChecking=no deploy_test.py run@<IP>:/tmp/   # 一次
# 每轮 3 条
python3 pack.py my-skill
sshpass -p '1' scp my-skill.rpk run@<IP>:/tmp/
sshpass -p '1' ssh run@<IP> 'python3 /tmp/deploy_test.py /tmp/my-skill.rpk 300'   # timeout ≥ 技能总时长

sshpass -p '1' ssh run@<IP> 'grep "Animation task成功" /robot/persist/log/task_engine/task_engine.log | tail -8'

python3 extract_token.py      # → /tmp/ph_token.txt（JWT，7 天有效）

python3 primehub_publish.py publish my-skill.rpk '{
  "skillName": "我的技能名",
  "version": "1.0.0",
  "skillDesc": "一句话简介（30 字内最好）",
  "long_description": "详细说明（详情页显示）",
  "categoryIds": [104],      "categoryCodeList": ["action"],
  "tagsIds": [127],          "tagsCodeList": ["companion"],
  "robotModelIds": [100],    "robotModelCodeList": ["robot_q"],
  "iconUrl": "skill-music.svg"
}'
# 成功回 {'code': 1000, 'msg': '成功'}