Runtime 提供 HTTP API 和 WebSocket API。HTTP 用于调试、查看状态和简单输入；WebSocket 用于比赛时的实时连接。
真实视觉导航小车的命令、位姿、到达事件和障碍地图接口见
rover_backend_api.md。
后端本机：
http://127.0.0.1:8000
ws://127.0.0.1:8000/ws
队友电脑连接时，把 127.0.0.1 换成后端电脑 IPv4，例如：
http://192.168.1.23:8000
ws://192.168.1.23:8000/ws
所有 WebSocket 消息都必须是：
{
"topic": "sensor.hr",
"source": "hr_p1",
"timestamp": 1720000000.0,
"payload": {}
}字段：
topic：消息类型。source：消息来源，例如runtime、frontend、robot_r1、arm、hr_p1、voice_test。timestamp：Unix 时间戳，float。payload：业务数据对象。
格式错误时 Runtime 返回：
{
"topic": "error",
"source": "runtime",
"timestamp": 1720000000.0,
"payload": {
"code": "INVALID_MESSAGE",
"message": "缺少 topic/source/timestamp/payload 字段",
"raw": {}
}
}payload 缺字段时 Runtime 返回：
{
"topic": "error",
"source": "runtime",
"timestamp": 1720000000.0,
"payload": {
"code": "INVALID_PAYLOAD",
"message": "payload 字段不完整或类型错误: ...",
"raw": {}
}
}检查服务是否启动。
响应：
{
"ok": true,
"service": "moonfall-runtime"
}返回当前完整 WorldState。
curl http://127.0.0.1:8000/api/state上传心率并重算 moon_rage。
请求：
{
"player_id": "p1",
"heart_rate": 105
}响应包含更新后的 state。
提交语音文本，让 Runtime 解析成小车命令。
请求：
{
"player_id": "p1",
"text": "让一号车绕开月尘去东北资源区采集燃料"
}响应：
{
"ok": true,
"intent": {
"intent_type": "robot_command",
"player_id": "p1",
"robot_id": "r1",
"action": "collect",
"target_zone": "resource_ne",
"avoid": ["dust_center"],
"confidence": 0.6
},
"command": {
"command_id": "...",
"robot_id": "r1",
"action": "collect",
"target_zone": "resource_ne",
"speed": 10,
"priority": 1.2,
"avoid": ["dust_center"]
}
}同时 Runtime 会通过 WebSocket 广播 cmd.robot 和 state.event。
MVP 只记录卡牌输入并广播 state.event。
请求：
{
"player_id": "p1",
"card_id": "boost_fuel",
"action": "use",
"payload": {
"value": 10
}
}重置内存 WorldState，生成新的 session_id。
请求：
{
"fuel": 70
}设置燃料并广播 state.world。
请求：
{
"moon_rage": 0.8
}设置月怒并广播 state.world。
请求：
{
"action": "drop_dust",
"target_zone": "dust_center"
}生成并广播 cmd.arm。
直接设置：
fuel = 70boss_mode = true
并广播 state.event 和 state.world。
路径：
/ws
连接后 Runtime 会立即发送一条 state.world，之后每秒广播一次完整世界状态。
Runtime 接受的主要输入 topic：
sensor.hrperception.poseinput.voiceinput.cardinput.debugdebug.echodebug.logstate.event：仅用于设备回传事件，例如机械臂arm_done。
Runtime 主要输出 topic：
state.worldstate.eventcmd.robotcmd.armcmd.humanoiderror