Moonfall Ark · 探月方舟

一个把玩家意图转化为实体双车自主行动的实时具身 Agent 项目。

Moonfall 使用二维码策略卡作为受约束的意图输入，由 Runtime 选择合法目标并下发命令；视觉导航 Agent 通过顶视相机定位、A* 路径规划和差速闭环控制驱动车辆；位姿与到达事件实时回传，React + Three.js 大屏展示数字孪生状态并完成游戏结算。

当前主线是简化后的双玩家、双车卡牌游戏。仓库中的部分 docs/schema/ 和旧设计文档用于保留早期四人引擎探索，不代表当前 Runtime 已实现能力。

核心闭环

flowchart LR
    P["玩家 / QR 卡牌"] --> I["意图解析与动作过滤"]
    I --> T["目标分配策略"]
    T --> C["cmd.robot"]
    C --> A["视觉导航 Rover Agent"]
    A --> W["实体月面"]
    A -->|"perception.pose / robot_arrived"| R["Moonfall Runtime"]
    R --> T
    R --> U["Three.js 数字孪生大屏"]

Loading

已实现能力

• 双玩家/双阵营/双车回合制状态机，燃料达到 5 时结束游戏。
• 中文、JSON 和 URL QR payload 解析；仅允许遗迹探索与能源优先两类动作。
• 基于车当前位置、资源库存和最近目标的确定性目标选择。
• FastAPI HTTP API 与统一 WebSocket envelope；模拟车和真实硬件共享协议。
• 顶视相机 + ArUco 标定、厘米坐标、A* 绕障、多车闭环控制与失联停车。
• React + Three.js 场景、车辆遥测、目标、资源库存、心率和事件展示。
• Runtime 核心单元测试，以及 Rover 几何、规划、控制、标定和 bridge 测试。

技术栈

层	技术
Runtime	Python 3.11+、FastAPI、WebSocket、Pydantic
Rover Agent	OpenCV、ArUco、A*、差速闭环控制、UDP
Dashboard	React、Vite、Three.js、Framer Motion
Delivery	Docker、Docker Compose、GitHub Actions

快速开始：无硬件 Demo

环境要求：Python 3.11+、Node.js 18+。

git clone https://github.com/Moonfall-Lab/moonfall-ark.git
cd moonfall-ark

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements.txt

PYTHONPATH=backend python -m uvicorn moonfall_runtime.server:app \
  --host 127.0.0.1 --port 8000

另开终端启动大屏：

cd frontend
npm ci
npm run dev -- --host 127.0.0.1 --port 5173

打开 http://127.0.0.1:5173/#/dashboard，允许浏览器相机权限，然后扫描 采集优先 或 探索遗迹。默认 MOONFALL_SIM_ROVERS=1，无需实体车即可看到完整移动和结算流程。

也可以只启动 Runtime：

docker compose up --build
curl http://127.0.0.1:8000/api/health

真实硬件模式

# Runtime：关闭内置运动模拟
MOONFALL_SIM_ROVERS=0 PYTHONPATH=backend \
  .venv/bin/python -m uvicorn moonfall_runtime.server:app \
  --host 0.0.0.0 --port 8000

# 全局相机 + 双车控制 Agent
env -u ALL_PROXY -u HTTPS_PROXY -u HTTP_PROXY \
  NO_PROXY=127.0.0.1,localhost \
  PYTHONPATH=backend/clients \
  .venv/bin/python -m rover_agent.agent \
  --camera 0 --bridge ws://127.0.0.1:8000/ws --viz

详细标定、控制参数和现场排错见 backend/clients/rover_agent/README.md。

API 摘要

HTTP：

• GET /api/health、GET /api/config、GET /api/state
• POST /api/control/reset、POST /api/control/next_turn
• POST /api/debug/qr、POST /api/input/hr

WebSocket：/ws

{
  "topic": "perception.pose",
  "source": "rover_agent",
  "timestamp": 1720000000.0,
  "payload": {
    "car_id": "r0",
    "x": 12.3,
    "y": 35.6,
    "theta": 1.57,
    "status": "moving"
  }
}

完整当前契约见 AGENTS.md；Rover 接口见 docs/rover_backend_api.md。

测试

python -m unittest \
  tests/test_qr_recognition.py \
  tests/test_targeting.py \
  tests/test_runtime_policy.py -v

python -m unittest discover -s tests -p 'test_rover_*.py' -v

cd frontend
npm ci
npm run build

tests/test_rover_*.py 覆盖硬件 Agent 的纯软件模块。旧测试若导入已删除的 app.main，属于历史 Runtime，不在当前主线验收范围内。

项目结构

backend/moonfall_runtime/        双车游戏 Runtime 与协议编排
backend/clients/rover_agent/    视觉、规划、控制和硬件 bridge
frontend/                       React + Three.js 数字孪生大屏
tests/                          Runtime 与 Rover Agent 测试
docs/                           协议、导航、设计和历史资料

生产化差距、阶段验收标准和可量化简历表述见 docs/production_roadmap.md。

License

Apache License 2.0