DreamSoul研究
源码与架构 /

Reachy Mini 源码架构

固定源码 · 研究快照 2026-10-27Markdown 下载 ↓飞书阅读 ↗
本页为正式研究文档的网页阅读版。固定 GitHub 证据保留;本机研究底稿未发布,相关链接已改为文字说明。原文中的历史发布状态对应研究当时。

研究对象为 Reachy Mini 自身的软件架构:SDK 与 daemon 固定在 d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb(2026-10-26),官方对话应用固定在 b731ea1fd6ce53232f1b13609331271358e10bd9(2026-10-26),访问日为 2026-10-27。正文不混入后续 main 的行为,不讨论其他产品的组合方案。图中进程边界、源码类关系与分析分组分开标明;状态图是依据分支整理的主要路径,不是仓库自带设计图。

本次为固定源码阅读与调用链核对,没有安装或启动完整上游、没有连接机器人、没有运行 MuJoCo 或调用实时服务。此前的 9 组运动函数隔离验证只覆盖纯函数输入输出,不构成本文整条架构链路已运行的证据。

架构全貌:一个设备服务,多个客户端,两条主要数据通路

Reachy Mini 的核心不是把所有能力装进一个机器人对象,而是把设备长期状态放在 daemon,把应用策略放在独立应用进程。应用里的 ReachyMini 是门面:控制端连接 WSClient,媒体端连接 MediaManager。daemon 内部的 FastAPI、Daemon、WSServer、Backend、GstMediaServer 和 AppManager 是同一进程内的模块,并不是六个微服务。真正另外启动的是受管 App 子进程;MuJoCo 后端也在 daemon 的后端线程内运行。

控制通路用 WebSocket JSON 交换命令、状态和任务结束消息,媒体通路则选择本机 IPC 或 WebRTC。这样相机帧和音频不需要塞进 Python 控制消息,应用也不必直接持有电机串口。代价是一次用户行为要跨越应用任务、控制连接、daemon 轨迹和设备循环等多个状态域;“应用动作结束”与“电机已经到位”没有天然等价关系。

官方 conversation 是这一平台上的应用。它通过 SDK 控制动作与媒体,另外连接 HF 实时服务。HF 对话连接、SDK 控制 WS、远端媒体 WebRTC 是三条不同的链路。安装应用时访问 Hugging Face Space,也不能据此认定推理发生在那个应用 Space 中。

Reachy Mini 组件
Reachy Mini 组件 · 点击查看原图
查看 Mermaid 图源
flowchart TB
  subgraph AP["应用进程:用户脚本或受管 App"]
    App["应用逻辑 / conversation"]
    SDK["ReachyMini + WSClient"]
    MM["MediaManager"]
    App --> SDK
    SDK --> MM
  end
  subgraph DP["daemon 进程:以下为同进程逻辑模块"]
    API["FastAPI / Uvicorn"]
    D["Daemon 生命周期"]
    WS["WSServer"]
    AM["AppManager"]
    B["Backend 共用控制逻辑"]
    RB["RobotBackend 或 MockupSimBackend 或 MujocoBackend"]
    MS["GstMediaServer / GLib 线程"]
    API --> D
    API --> WS
    API --> AM
    D --> B
    D --> MS
    B --> RB
    WS --> B
    AM --> D
    B <--> MS
  end
  SDK <-->|"WS JSON:命令、状态、任务反馈"| WS
  MM <-->|"本机 IPC 或 WebRTC 媒体"| MS
  AM -->|"创建并监控子进程"| App
  RB --> HW["真实电机控制库 / MuJoCo / 数组模拟"]
  MS <--> AV["相机、麦克风、扬声器"]
  App <-->|"实时对话协议,独立于控制 WS"| HF["HF 分配器与返回的实时服务"]

依据:SDK 构造与客户端/媒体装配、FastAPI 在 app.state 中创建 Daemon 和 AppManager、Daemon 资源持有、对话应用装配。

源码树、依赖与启动入口

目录是职责分层,不是单独部署单元

固定仓库内路径 主职责 为什么单列,带来的代价
SDK src/reachy_mini/reachy_mini.py 面向应用的运动、状态、媒体和连接门面 简化使用入口,但构造对象会连接 daemon 并配置媒体,不是纯数据对象
io/protocol.py、io/ws_client.py、io/ws_server.py Pydantic 消息模型、客户端缓存/等待、服务端路由/广播 类型与传输分离,便于多入口共用;消息类型存在不代表每种传输都实现
daemon/app/ HTTP/WS 路由、生命周期、启动配置、状态和管理入口 API 与设备执行分开;路由需要通过 app.state 取得共享实例
daemon/backend/abstract.py 与三个后端目录 共用运动逻辑;真实、数组模拟、MuJoCo 执行 统一上层协议,但共用 Backend 已承担动作、跟踪、音频协调及上传管理等较多职责
kinematics/、motion/、utils/ IK/FK、时间参数化轨迹、姿态与插值等基础函数 轨迹数学与设备 I/O 分开;几何数据和原生运动学依赖仍与 Reachy 机构绑定
media/ GStreamer、相机、音频、WebRTC 与媒体门面 吸收平台差异;需要原生运行库、设备和媒体线程,而非仅 Python 包
apps/ 应用元数据、来源、安装、Python 入口和进程管理 应用可独立发布;依赖环境与设备占用要由管理层协调
conversation 的 main.py、console.py 应用装配、设置界面、录播循环和退出 交互壳与服务处理器分开;有主线程、事件循环及多个辅助线程
conversation 的 conversation_handler.py、huggingface_realtime.py 通用流处理约定、HF 会话协议与事件状态 可替换处理器,但当前主入口明确构建 HF 处理器
conversation 的 moves.py、tools/、配置/记忆模块 表达动作调度、工具调用、用户设置与事实记忆 对话策略与电机实现解耦;工具完成、动作队列完成、语音播放完成各自独立

SDK 使用 setuptools 和 src 布局,Python 要求至少 3.11。固定版本声明为 1.14.0.dev0。基础依赖不仅有 NumPy、Pydantic、FastAPI、Uvicorn、websockets,也包括原生运动学/电机控制库与媒体相关包。MuJoCo、Placo 等通过 extra 声明,其中模拟 extra 指定 MuJoCo 3.3.0。因此“不启用仿真”与“没有任何原生依赖”是两回事。

conversation 的包版本是 1.1.1,依赖 reachy-mini>=1.11.0,并未在其 pyproject 中把 SDK 钉死到本文提交。它还依赖 openai==2.28.0、舞蹈库、MCP、httpx 等。这里 OpenAI SDK 是实时兼容协议客户端,实际 endpoint 在运行时决定,不能只看包名判断服务供应商。

声明的启动入口如下,仅展示源码入口,不表示本次已经执行:

reachy-mini-daemon
  -> reachy_mini.daemon.app.main:main
  -> 参数解析 / Uvicorn
  -> create_app / FastAPI lifespan
  -> Daemon.start / backend 线程 / 媒体

reachy-mini-conversation-app
  -> reachy_mini_conversation_app.main:main
  -> run / ReachyMini / MovementManager / HuggingFaceRealtimeHandler / LocalStream

应用管理入口 reachy_mini_apps
  -> ReachyMiniConversationApp
  -> ReachyMiniApp.wrapped_run
  -> with ReachyMini(...) / 子类 run(...)

daemon 的 Args 明确提供 sim、mockup_sim、headless、no_media、串口、硬件配置、运动学引擎、自动唤醒、停止时睡眠等选项。默认绑定地址也有部署区别:无线版默认监听所有接口,其余配置默认 loopback。源码注释明确 HTTP API 没有身份认证;默认本机绑定是暴露面的控制手段,不是为整个远端体系提供认证。

依据:SDK 打包与依赖、SDK 命令入口、conversation 打包与入口、daemon 参数和绑定策略、App 基类上下文入口。

SDK、WS 协议与核心对象关系

SDK 缓存状态,daemon 持有目标与执行状态

ReachyMini.__init__ 先进行 daemon 检查、确定连接方式,建立客户端,再配置媒体。包顶层也会提前导入 ReachyMini 和 ReachyMiniApp;所以“导入纯工具函数”和“实例化 SDK”不能混为一谈:实例化涉及连接,导入依赖链也并非完全轻量。

WSClient 使用同步 WebSocket,在接收线程中解析消息。关节、头部位姿、IMU、daemon 状态各有缓存及 Event;读取当前值主要读的是最近收到的快照,并不是每读一次就向电机发起同步查询。连接就绪也不是只凭 TCP 建立,而是等到初始关节/位姿数据。另一个存活检查线程依靠收到消息的 Event 判断连接活性。

set_target 将姿态、天线和 yaw 包成 SetFullTargetCmd,然后返回;服务端该路径没有逐条应答。SDK 本地的最后目标与远端的当前关节分别是“发出的意图”和“收到的状态”,不能把前者当反馈。

goto_target 走另一条路径:创建 GotoTaskRequest,用 UUID 包装成 TaskRequest,登记一个本地 TaskState 并等待 Event。daemon 返回 TaskProgress 后,接收线程按 UUID 解除等待。这里的任务登记表属于客户端进程,后端目标与运动执行状态属于 daemon。

类图中的关系以实际代码为准

下图 *-- 表示该对象负责创建、持有并管理所示对象的生命周期;--> 是持有引用;虚线是调用依赖;空心三角是 Python 继承。为便于阅读省略了媒体具体类和可选运动学引擎。Backend 不是 Python ABC,虽然文件名是 abstract.py;图中不把它标为抽象基类。AnalyticalKinematics 是默认构造分支,不是唯一可能引擎。

Reachy Mini 核心类
Reachy Mini 核心类 · 点击查看原图
查看 Mermaid 图源
classDiagram
  class ReachyMini {
    set_target()
    goto_target()
  }
  class AbstractClient
  class WSClient {
    send_command()
    send_task_request()
    wait_for_task_completion()
  }
  class MediaManager {
    get_frame()
    push_audio_sample()
    close()
  }
  class Daemon {
    start()
    stop()
    restart()
  }
  class AbstractServer
  class WSServer {
    handle_client()
    _handle_task_request()
  }
  class Backend {
    process_command()
    set_target()
    goto_target()
    play_move()
  }
  class RobotBackend {
    run()
  }
  class MockupSimBackend {
    run()
  }
  class MujocoBackend {
    run()
    rendering_loop()
  }
  class Move {
    <<abstract>>
    duration
    evaluate()
  }
  class GotoMove {
    evaluate()
  }
  class AnalyticalKinematics {
    ik()
    fk()
  }
  AbstractClient <|-- WSClient
  AbstractServer <|-- WSServer
  Backend <|-- RobotBackend
  Backend <|-- MockupSimBackend
  Backend <|-- MujocoBackend
  Move <|-- GotoMove
  ReachyMini *-- WSClient : 创建并持有 client
  ReachyMini *-- MediaManager : 创建并持有
  Daemon *-- Backend : 创建一个具体后端
  Daemon *-- WSServer : 创建并停止
  WSServer --> Backend : 持有引用
  Backend *-- AnalyticalKinematics : 默认引擎分支
  Backend ..> Move : evaluate
  Backend ..> GotoMove : 构造轨迹

Move 的接口是 duration、evaluate(t) 和可选 sound_path。它输出头部 4×4 变换、天线目标和身体 yaw;GotoMove 将初末姿态封装为随时间采样的轨迹。该抽象关心“时刻 t 应该给什么目标”,不关心电机通信、错误重试或物理到位。

协议以 Pydantic 判别消息承载参数验证,传输层把 JSON 变回模型后再分派。协议的统一有一个实际边界:PlayMoveTaskRequest 虽有定义,固定版 WSServer 对它只记录“尚未实现”的警告;已上传动作走的是 Backend 的上传/播放命令及事件路径,不能凭协议类名画出一条可用的 WS PlayMoveTask 流程。

依据:客户端缓存、线程和连接就绪、SDK set_target 与 goto_target、任务模型、WS 任务分派及未实现分支、Move 接口、GotoMove。

daemon 生命周期与三个后端

生命周期控制与设备循环分离

FastAPI lifespan 把当前 asyncio loop 交给 daemon,装配启动应用观察任务等资源。Daemon.start 选择后端,启动 WS 广播和状态发布,再在后端线程调用 run。后端通过 ready Event 报告可用;启动代码等待该 Event,超时或线程异常会进入错误处理。媒体在后端准备好后继续初始化,最后状态才进入 RUNNING。

Daemon 还保存重启参数、持有媒体服务和机器人应用占用锁。它负责“设备服务是否可用”,不是单个动作的任务管理器。状态发布线程约每秒广播 daemon 状态,而实际关节/位姿更新频率由具体后端决定。

Reachy Mini Daemon 状态
Reachy Mini Daemon 状态 · 点击查看原图
查看 Mermaid 图源
stateDiagram-v2
  [*] --> NOT_INITIALIZED
  NOT_INITIALIZED --> STARTING: start
  STOPPED --> STARTING: start
  STARTING --> RUNNING: 后端 ready / 启动步骤完成
  STARTING --> ERROR: 构建或就绪或启动失败
  RUNNING --> ERROR: 后端线程异常
  RUNNING --> STOPPING: stop
  STOPPING --> STOPPED: 清理完成且未记错误
  STOPPING --> ERROR: sleep / join / close 异常
  ERROR --> STARTING: restart 内部清理后重新 start
  note right of RUNNING
    状态属于 Daemon
    不代表某个动作或音频正在执行
  end note

图中是主要状态分支,ERROR -> STARTING 表示 restart 内部先执行清理再重新 start,并非忽略清理。停止时可能先 goto_sleep,再设置后端 should_stop,最多等待后端线程 5 秒,关闭后端后才关闭 WS,以保留退出前状态发布机会。若睡眠、停止或关闭失败,最终可以保持 ERROR,而不是把每次 stop 都说成 STOPPED。

这种组织使 HTTP 服务器和设备生命周期可以分开存在:API 可以报告失败、请求重启,而设备线程不必总是随进程一起消失。代价是需要维护 API 可达、后端 ready、daemon state、媒体 acquired 等多套条件;单凭端口开放不能判断机器人可控制。

Backend 是目标合成与执行策略中心

Backend 保存目标姿态、目标关节、当前关节、当前位姿、IK 重算标记、录制缓冲、动作上传资源、跟踪状态和停止令牌。给头部目标赋值通常只是更新字段并置 ik_required。后端控制循环随后合成人脸跟踪目标、语音摆动偏移等,再求解 IK。这样跟踪与语音表现能够共享一套最终关节目标,但也意味着应用给出的头姿态不一定是最后未经修改的执行姿态。

默认 AnalyticalKinematics 从机构 JSON 读取连杆和分支几何,调用 Rust 运动学绑定。自动身体 yaw 分支通过 inverse_kinematics_safe 约束身体 yaw 与头身相对 yaw,当前参数分别是 160°、65°。这不等于完整碰撞安全检查:AnalyticalKinematics 明确不使用 check_collision 参数,Backend 的碰撞检测只支持 Placo 分支,默认关闭。不能把“safe IK”扩展成对任意环境接触和夹碰的保障。

后端 实际循环与状态来源 能覆盖什么,不能覆盖什么
RobotBackend 使用外部 ReachyMiniPyControlLoop;Python 层约 50 Hz 更新,写目标、读关节、FK/IK、发布快照 真实设备路径,但串口/控制器底层实现在外部依赖;本文未验证延迟、负载或到位精度
MockupSimBackend 约 50 Hz,以目标更新数组和运动学状态 可支持没有物理电机时的上层连接/控制逻辑;不是动力学、接触或真实电机故障仿真
MujocoBackend MuJoCo 步长 0.002 秒即 500 Hz,decimation=10 对应 50 Hz 控制;图像渲染/流周期 0.04 秒 有模型、物理步进、场景、虚拟相机;不自动复现真实麦克风、网络、摩擦标定或电机通信故障

MuJoCo 后端载入 MJCF 场景,关节名称/地址和控制器一起映射,天线顺序还需要从真实机器人约定交换到模型顺序。headless 去掉交互 viewer,不等于无需图形/渲染依赖。虚拟相机由渲染循环通过 GStreamer UDP 输给媒体服务。Mockup 的状态刻意与 MuJoCo 分开:只有 sim 设置 simulation_enabled,避免把数组模拟误路由成仿真视频源。

依据:Daemon 启动、停止与线程等待、状态枚举、Backend 初始化与运动学分支、目标合成和 IK、解析运动学与约束、真实后端循环、Mockup 后端、MuJoCo 初始化与步长。

轨迹、任务、取消与反馈:完成到底表示什么

一次 goto 的完整链路

SDK 阻塞等待发生在应用线程,服务端执行则是 asyncio Task,物理控制又在后端线程。这允许控制服务继续处理消息,而不让一个长动作堵住所有 WS 接收。Backend 的 goto_target 构造 GotoMove,再进入 play_move;后者默认约 100 Hz 求值并更新目标。100 Hz 是轨迹采样请求频率,不能等同于电机通信频率,真实后端的 Python 控制循环是 50 Hz。

Reachy Mini Goto 时序
Reachy Mini Goto 时序 · 点击查看原图
查看 Mermaid 图源
sequenceDiagram
  participant A as 应用线程
  participant S as ReachyMini / WSClient
  participant W as WSServer / asyncio
  participant B as Backend
  participant R as 后端控制线程
  A->>S: goto_target(head, duration)
  S->>S: 创建 UUID 和 TaskState
  S->>W: TaskRequest(GotoTaskRequest)
  S->>S: Event.wait(duration + 1)
  W->>B: create_task / await goto_target()
  B->>B: 构造 GotoMove / play_move()
  loop 默认约 100 Hz 轨迹求值
    B->>B: evaluate(t) / 更新目标字段
    R->>B: 读取目标、计算 IK、提交关节目标
    R-->>W: 当前关节与头部位姿
    W-->>S: 广播状态,更新缓存
  end
  alt 后端协程正常返回
    B-->>W: return
    W-->>S: TaskProgress(finished=true, error=null)
    S-->>A: 等待结束
  else 后端抛出异常
    B-->>W: exception
    W-->>S: TaskProgress(finished=true, error=...)
    S-->>A: 抛出任务错误
  else 客户端等待超时
    S-->>A: TimeoutError
    Note over S,B: 该等待超时本身不发送取消命令
  end
  Note over W,R: TaskProgress 不是机械误差收敛证明;状态回传是另一条流

服务端只在等待 Backend.goto_target 返回或捕获异常后发送 finished。它没有在这里计算“所有关节误差小于阈值并持续若干周期”。此外,play_move 在未取得动作锁时会警告并正常 return;被全局 stop 中断也可正常返回。因此即使 TaskProgress 没有 error,也只严格说明该协程走完了当前返回路径,不能作为执行了全部轨迹或机械到位的证明。

客户端 wait_for_task_completion 在 Event 超时后抛异常,超时本身不取消远端动作。当前代码在成功/任务错误后删除登记项,而超时抛出发生在删除之前。这是本地等待资源与远端任务生命周期不同步的具体例子;本文只据静态分支描述,未构造长时间泄漏实测。

上传动作与全局停止是另一组语义

上传动作由 upload_id 管理,动作和可选音频从缓冲中取出后单次使用。播放路径先广播 started,再安装 _PlaybackCancelToken 并调用轨迹执行,之后广播 finished、cancelled 或 error,并在 finally 中清理音频与令牌。started 是软件播放流程进入时的事件,发送位置甚至早于实际调用 play_move,不能进一步解释为第一帧机械动作已生效。

CancelMoveCmd 只有 upload_id 匹配当前令牌时才设置 cancelled,过期 ID 不应取消新动作。StopMoveCmd 则设置全局停止标记,并作用于当前轨迹,包括不带上传令牌的 goto。轨迹循环每次采样检查停止条件,中断时还尝试停止该轨迹的伴随声音;延迟启动声音的 asyncio Task 也在 finally 中取消,防止动作结束后才发声。

这些处理是“停止继续产生轨迹目标和附带声音”的软件语义。即时 stop 回执说明停止请求被处理,不说明关节已经静止;停止也不自动等于断扭矩、进入 sleep 或清除所有独立音频通路。

队列与锁的作用及局限

WSServer 为每个客户端建立容量 100 的 asyncio.Queue,由后台线程通过 loop.call_soon_threadsafe 投递。队满丢弃最旧项,再放入最新项。这适合避免慢客户端把高频状态拖成越来越陈旧的积压,但状态与 TaskProgress 共用该广播通路。由此可推导:它不是持久、可重放的可靠事件总线,持续拥塞时关键结束事件也没有单独的可靠投递层;本次没有做拥塞复现实验。

Backend 用 threading.RLock 和 _active_move_depth 容许初始 goto 等嵌套调用,共享停止标记覆盖嵌套轨迹。需要注意,RLock 按线程识别重入,不按 asyncio Task 识别所有者;同一事件循环的不同协程不是不同线程。因此不能只依据这一锁就断言任意并发入口都被严格串行化。这个结论是结构分析,尚不是完整并发错误复现。

依据:SDK 等待与超时、服务端 goto 返回语义、动作锁与停止字段、play_move 循环与 finally、上传取消和全局停止、上传播放与事件、广播与客户端队列。

媒体架构:相机单一持有,传输与使用分开

MediaManager 的实际分支是 NO_MEDIA、LOCAL、WEBRTC。LOCAL 的相机是 GStreamerCamera IPC reader,音频是 GStreamerAudio;WEBRTC 则让 camera 和 audio 共同指向一个 GstWebRTCClient。这个门面向应用提供帧读取、采音、推音频等接口,把平台与传输差异留在具体后端。

自动模式先读取 daemon 状态和 camera IPC 信息:适合本机时使用 LOCAL,否则使用 WebRTC。选择 no_media 也不只是“不要生成两个对象”:SDK 配置路径可能请求 daemon 释放当前媒体,使设备交给其他使用者。媒体所有权因此既有 SDK 实例局部状态,也有 daemon 的 acquired/released 状态。

Reachy Mini 媒体路径
Reachy Mini 媒体路径 · 点击查看原图
查看 Mermaid 图源
flowchart LR
  subgraph DP["daemon 进程"]
    SRC["真实相机或仿真 UDP 图像"]
    GST["GstMediaServer 相机管线 / tee"]
    IPC["本机原始帧 IPC sink"]
    ENC["编码 / WebRTC 分支"]
    PLAY["接收音频播放管线"]
    SRC --> GST
    GST --> IPC
    GST --> ENC
  end
  subgraph AP["SDK / App 进程"]
    MEDIA["MediaManager"]
    CAM["LOCAL: GStreamerCamera"]
    AUDIO["LOCAL: GStreamerAudio"]
    RTC["WEBRTC: GstWebRTCClient"]
    MEDIA --> CAM
    MEDIA --> AUDIO
    MEDIA --> RTC
  end
  IPC -->|"共享传输"| CAM
  ENC <-->|"WebRTC"| RTC
  RTC -->|"远端播放音频"| PLAY
  AUDIO <--> DEV["应用所在机器音频设备"]
  PLAY --> SP["机器人扬声器"]
  N["NO_MEDIA: 不创建 camera/audio;SDK 配置还可能请求 daemon 释放媒体"]

daemon 的 GstMediaServer 持有相机管线,原始帧通过 tee 分向本机 IPC 与远端编码/WebRTC 分支。Linux/macOS 使用 unixfd 相关路径,Windows 有 win32 IPC 分支。这样多个消费者不必分别争抢摄像头,但应用依赖 daemon 正确创建 IPC、发布相机规格并维持管线。LOCAL 音频仍是应用所在机器的本地音频实现,不能把所有本地音频都画成经过 daemon 的同一条 WebRTC 管线。

GstMediaServer 有独立 GLib 主循环线程,并为相机位姿、会话活动和 peer 状态使用锁。WebRTC 接收的播放音频有独立管线;清音频需要 flush/reset 等设备层操作,清 Python 队列并不足够。媒体服务还可以把音频能量用于 wobbler,再由 Backend 合成头部偏移;音频驱动表现与应用的主动作在 daemon 汇合。

媒体和控制分离避免高带宽数据阻塞控制 JSON,但存在两种连通性与两种时钟:控制连接正常不保证音频设备已开;网络模型响应结束不保证媒体队列清空。WebRTC DataChannel 也能进入 Backend 的命令处理和 JSON-RPC 转发路径,因此 WS 不是所有远程控制的唯一入口。不过这不改变本章 SDK 默认控制链路和媒体链路分开的事实。

依据:媒体门面和具体后端、SDK 自动配置与 no_media、GstMediaServer 状态与 GLib 线程、媒体管线构建、清除接收音频、统一命令入口。

App 管理:发现、环境、设备占用与子进程

AppManager 持有一个 current_app,运行记录包含子进程、监视任务、状态和 stop_requested。应用来源层负责发现元数据、找到入口模块和 Python;管理器负责启动、读日志、停止和回收。HF 来源会读取 Space 元数据,安装来源可以使用 snapshot_download;本地发现则检查 Python entry points。这样应用仓库可独立于 SDK 发布,daemon 不必把每个 App 的业务代码编入自身。

环境隔离需要按源码准确理解:桌面打包版和无线版使用与 daemon 环境分开的 apps_venv,但这是所有 App 共用的环境,不是每 App 一个 venv。AppManager 启动时清理可能污染子进程的 GStreamer/PYTHONPATH 等继承环境,再以 python -u -m 模块 方式创建进程。进程隔离可以隔开故障和生命周期,却不能自动解决共用环境中的依赖版本冲突,也不是执行不可信 App 的安全沙箱。

启动时 RobotAppLock 协调本地 App 与远端控制会话占用。管理器有保留远端控制或驱逐远端的分支,并通知 daemon 取消待执行的 idle reset。这个锁作用于受管理的应用/会话槽位,不能据此声称任意直接 WS 客户端命令都获得了统一授权检查。

停止先向子进程发信号:POSIX 使用 SIGINT,Windows 使用 terminate,然后等待;默认超过 20 秒再结束进程树。两种系统的信号不能都理解为同等的优雅退出保证。monitor_task 负责收尾、记录退出并释放占用。AppManager 停止收尾还检查机器人是否接近睡眠姿态:若已睡眠则保持无力,否则尝试用 1 秒 goto 返回初始姿态。App 基类在 wrapped_run 中持有 SDK 上下文,将 ReachyMini 与 threading.Event 交给子类 run;stop 方法只是设置这个 Event,需要应用自己的执行循环配合退出。

这种层次把“安装/运行哪个程序”与“程序如何控制机器人”分开了。其代价是切换 App 时还必须协调旧媒体资源、动作写入、机器人姿态和远端会话,单纯 kill 进程并不能表达完整的行为交接。

依据:AppManager 运行记录和启动、子进程创建与监视、停止策略、共用 apps_venv、HF 应用目录发现、RobotAppLock、ReachyMiniApp 生命周期。

官方对话应用:组装关系与真实 HF 路径

应用内部有三条并行工作线

主入口取得或创建 ReachyMini 后唤醒机器人,构造 MovementManager,将机器人、动作管理器等装进 ToolDependencies,再构建 HuggingFaceRealtimeHandler 和 LocalStream。App 框架启动时,ReachyMiniConversationApp 继承 ReachyMiniApp,复用传入的 SDK,而不是再创建另一套设备服务。

第一条是录播线:LocalStream 管理麦克风读取、处理器接收、输出队列消费和扬声器推送。第二条是会话线:HuggingFaceRealtimeHandler 继承 ConversationHandler,持有连接、输出队列、响应完成 Event、当前音频 response_id、被丢弃响应 ID 和后台工具管理器。第三条是动作线:MovementManager 持有传入的 current_robot、线程安全命令 Queue、动作 deque 与 MovementState,在自己的工作线程采样动作并调用 set_target。

三条线的解耦让等待模型或执行长工具时,动作与声音还能继续。但“正在说话”“正在播放”“有动作正在执行”是三个不同状态,不存在一个全局 busy 就能完整表示它们。

HF 分配器与 OpenAI 兼容客户端的真实关系

默认 HF_REALTIME_CONNECTION_MODE 为 deployed。处理器向配置的 HF session 分配地址发请求,默认地址是:

https://pollen-robotics-reachy-mini-realtime-url.hf.space/session
  -> POST,按条件附 HF 身份与 hardware_id
  -> 返回 connect_url
  -> 将 URL 拆成 base_url / websocket_base_url
  -> AsyncOpenAI(... 自定义 URL ...)
  -> client.realtime.connect(...)

local 模式则要求显式提供 HF_REALTIME_WS_URL,绕过分配器直连指定地址。程序并不是因为使用了 openai 包,就默认向 api.openai.com 发起该对话。会话配置里可以看到兼容协议字段及 gpt-4o-transcribe 字符串,但仅凭客户端字段仍不能确认远端实际部署模型、权重来源或服务商。本文没有访问分配器,也没有验证其当前返回地址。

连接后会发送指令、工具规格和音频设置。收到音频 delta 时,处理器 base64 解码为 int16 PCM,附当前 playback_epoch 标识后入输出队列。LocalStream 消费它并转成播放所需 float32;启用 paced_playback 时按约 20 ms 小块调度,通过单调时钟和 playback_ready 控制推进。处理器的 response.done 仅解除生成侧响应等待,源码特意区分它与音频实际播完。

Reachy Mini 对话与打断
Reachy Mini 对话与打断 · 点击查看原图
查看 Mermaid 图源
sequenceDiagram
  participant L as LocalStream
  participant H as HuggingFaceRealtimeHandler
  participant F as HF session 分配器
  participant R as 返回的实时服务
  participant T as BackgroundToolManager
  participant M as MovementManager
  participant D as ReachyMini / daemon 媒体
  H->>F: deployed 模式 POST /session
  F-->>H: connect_url
  H->>R: AsyncOpenAI 自定义端点 / realtime.connect
  H->>R: session.update 指令、工具、音频配置
  loop 录音
    D-->>L: 麦克风帧
    L->>H: receive(frame)
    H->>R: input_audio_buffer.append
  end
  R-->>H: response.output_audio.delta
  H->>H: 解码 PCM、标记 playback_epoch、入队
  L->>H: emit()
  H-->>L: 音频帧
  L->>D: 分块 push_audio_sample()
  opt 模型请求工具
    R-->>H: function_call_arguments.done
    H->>T: start_tool(ToolCallRoutine)
    T->>M: 动作工具可加入动作队列
    M->>D: 60 Hz set_target()
    T-->>H: 工具结果通知
  end
  opt 检测到用户插话
    H->>H: 记录丢弃的 response_id、停止 speaking 标记
    H->>R: response.cancel(存在活动响应时)
    H->>L: clear_audio_queue()
    L->>H: playback_epoch 增加、移除队列音频项
    L->>D: clear_player()
    Note over H,D: 取消生成、清应用队列、清设备缓冲是三个动作
  end
  Note over R,D: response.done 不等于扬声器播完,也不等于机械动作完成

图是默认 deployed 路径;local 模式省去分配器两步。图中的动作工具调用是可选分支,不能理解为每条语音响应都会生成动作。

插话是跨层失效处理,不只是取消模型

本地 VAD/插话逻辑或服务端 speech_started 可以触发播放中断。处理器先更新 speaking/活动状态,把旧响应加入丢弃集合,有活动响应时请求 response.cancel;随后回调 LocalStream 清音频。

LocalStream 的清理会推进 playback_epoch、移除应用输出队列中的音频项(保留文本与元数据),并在后台线程调用媒体 clear_player。播放循环在真正推送每个分块前再次比较 handler 身份和 epoch,因此旧 handler、旧响应或已经被 flush 的帧不会只因早已出队就继续播放。playback_ready 在清理期间阻止新推送与 flush 交错。这个设计处理的是“取消后还有迟到帧”的问题,代价是额外维护响应 ID、帧归属、epoch、播放计时和同步 Event。

模型输入发送也有超时路径:receive 把音频转换为单声道 PCM、base64 后追加到连接输入缓冲;发送超时会中止连接以触发重建。HF handler 启动/重连循环与 SDK 控制 WS 的存活机制是独立的。即使对话会话恢复,也不能推定此前运动命令被自动重放。

依据:主入口与依赖装配、App 子类、ConversationHandler 状态、HF 处理器、分配器与 local 模式、默认配置、会话事件循环、音频 delta 与工具调用、中断处理、清播放器、播放循环、输入发送与异常。

对话中的动作、工具任务与退出

MovementManager 不是 daemon Backend 的别名,也不是应用安装管理器。它属于 conversation 的表现层:接收 queue/clear 等命令,维护当前 Move、开始时间、最后活动时刻和最后姿态;依据单调时钟判断 Move.duration 是否结束,切换队列或空闲呼吸。当前实现常量 CONTROL_LOOP_FREQUENCY_HZ=60,即约 60 Hz;个别 docstring 仍写 100 Hz,本文以运行常量为准。

BreathingMove 是 Move 子类,用无限持续时间表达待机呼吸。管理器还协调 listening 时天线冻结/恢复、说话时头部跟踪等状态。它通过 SDK 的 set_target 连续发送目标,完成条件由时间与队列推进决定,不等待每一帧机械到位。导入该模块会引入 SDK 和动作库相关依赖;构造时则使用注入的 ReachyMini 实例,不应把“持有机器人”画成每次自己启动 daemon。

后台工具由 BackgroundToolManager 管理。每个 ToolCallRoutine 保存工具名、JSON 参数与依赖,start_tool 建立 asyncio.Task,执行完成后进入通知队列。普通工具和需要 manager 的系统工具分开 dispatch。取消通过 Task.cancel 发出;dispatch 将 CancelledError 转成工具取消结果,管理器据结果标记 CANCELLED。工具执行返回数据,并不自动说明它加入的动作队列已经播完,也不自动清除所有正在运行的动作。工具是否等待动作完成,要继续看具体工具实现。

退出同样要看真实调用点而不是默认参数。MovementManager.stop 默认可在停止线程后用 2 秒 goto 回到中立姿态;但该版本 conversation 的 finally 明确调用:

movement_manager.stop(reset_to_neutral=False)

随后关闭 wobbling、媒体并断开控制客户端。普通 App 停止保持机器人唤醒,由 daemon 在进程退出/占用释放后协调 neutral;语音 go_to_sleep 与不活动超时是专门的睡眠路径。这样切换应用不会被普通退出强制睡眠,代价是姿态收尾由 App 与 daemon 共同完成,必须区分“应用停写”与“设备归位”。

依据:60 Hz 常量与 BreathingMove、MovementState 与管理器、动作队列推进、管理器 stop 默认行为、真实应用退出调用、后台工具创建和完成、取消工具、dispatch 的取消与异常转换。

并发、队列和时钟如何分工

下表是代码中执行域的归纳,不代表上游有一个同名总调度器。不同频率是名义设置,不是本次测得的实时性能。

执行域 持有的关键数据与同步方式 时钟/频率与架构含义
SDK 应用线程、WS 接收线程和存活线程 快照缓存、各类 Event、任务字典与 Lock 调用方可阻塞等待,接收线程独立解除;SDK 不因 await 风格而自动成为异步接口
FastAPI/Uvicorn asyncio loop WS 客户端 Queue、发送任务、goto 协程、API 管理任务 跨线程广播用 call_soon_threadsafe;网络慢客户端有有限队列
daemon 后端线程 当前/目标关节、IK 标记、ready/should_stop Event 真实与 Mockup 约 50 Hz;MuJoCo 物理步进另为 500 Hz
Backend 动作协程 Move、停止标志、取消 token、RLock/嵌套深度 play_move 默认约 100 Hz,使用 time.time;不是全系统统一单调时钟
daemon 状态线程与 GLib 媒体线程 daemon 状态、媒体 peer/session/pose 锁 状态约 1 Hz;媒体回调节奏独立于控制循环
conversation 动作线程 Queue 命令、deque 动作、MovementState、stop Event monotonic 计时,约 60 Hz;用最新动作状态持续发送目标
conversation 录播/会话 asyncio 任务、麦克风辅助线程 输入交接、输出 Queue、响应 Event、播放 epoch monotonic 播放调度;perf_counter 记录延迟;后台工具不阻塞主会话

这里至少存在三类时间:轨迹的墙钟时间、动作表现与播放的单调时间、事件中的 datetime 时间戳。使用分层时间有其局部合理性,但系统时钟跳变对基于 time.time 的轨迹循环有潜在影响;不能把单个使用 monotonic 的模块推广成整个平台都免疫时钟调整。

队列也有不同策略:控制广播选择丢旧保新,应用命令 Queue 用于跨线程串行处理,动作 deque 表示表现顺序,音频输出 Queue 需要 epoch 失效和设备 flush,后台工具通知 Queue 表示异步结果。这些不是可相互替代的“消息队列”,也没有共同的持久消费确认协议。

依据:WS 接收与任务锁、跨线程广播、真实后端循环、动作时间循环、daemon 状态发布、对话录音线程交接、动作线程。

配置持久化与扩展点

daemon 启动参数承载本次运行方式,硬件配置文件承载设备相关配置;跨重启的用户选择则写入 platformdirs 下的 reachy_mini/daemon_config.json,包括启动应用、扬声器 EQ、TURN、首次唤醒和遥测开关等字段。读取坏 JSON 或字段类型不正确时会忽略/回退,不能把文件存在本身当成配置有效。

conversation 区分环境启动配置和实例设置。dotenv/环境提供初始配置;UI 或远端修改写入实例目录 settings.json,再覆盖运行配置。AppSettings 用 None 表示“不在此层设置”,更新时只合并非 None 字段,通过进程内 Lock 保护读改写,以临时文件 replace 正式文件。这避免把用户输入拼回 .env 文本,但它不是跨多进程的数据库事务。

事实记忆另存 memory.v1.json,有结构化事实、归一化与容量约束,并通过临时文件替换写入。这一机制用于给指令提供已记住的事实,不是向量检索系统,也不意味着所有对话录音或逐字稿都被永久保存。工具和 profile 共同决定可调用能力,扩展工具通过 Tool 子类、外部文件加载或 RemoteMcpTool 适配;初始化会检查重复 Tool.name。外部工具进入进程即获得代码执行能力,profile 选择不是安全沙箱。

平台的扩展点分在不同层:Move 扩展时间到姿态的表达;运动学引擎扩展几何求解;Backend 扩展设备执行;MediaManager 具体实现扩展媒体传输;App entry point 扩展独立应用;ConversationHandler/Tool 扩展对话处理和工具能力。它们之所以没有合成一个统一插件接口,是因为生命周期、频率与输入输出性质不同。代价是扩展者必须知道自己进入的是应用进程、daemon 线程还是媒体回调,以及相应的异常和取消约定。

依据:daemon 配置路径与校验、实例设置读取与原子替换、事实记忆存储、工具接口和 MCP 适配、工具加载与冲突检测、工具注册初始化。

架构取舍与尚不能从源码证明的部分

这套架构的优势在于设备服务集中持有状态、动作与媒体分别抽象、同一 API 可接真实和模拟后端、应用以子进程独立演进。官方对话应用也没有把模型响应直接写成串口命令,而是经过工具、动作管理器和 SDK 进入设备服务。代价是层次多、状态多,任何“成功”都必须带上所属层次。

需要保留的具体边界如下:

以上是此固定版本的架构事实与有标识的静态推导,不是安全认证、商业许可结论或整机可交付判断。软件、硬件、模型和动作数据的许可范围仍分别见 Reachy Mini 平台 源码研究;本篇不将软件结构分析替代许可核查。

实际阅读范围与验证边界

仓库 已读源码范围 深度
SDK pyproject.toml、__init__.py、reachy_mini.py 打包、初始化、连接、媒体选择、set/goto 与上下文相关路径
SDK io/protocol.py、ws_client.py、ws_server.py 状态/命令/任务模型;接收缓存、等待、广播和 WS 分派
SDK daemon/app/main.py、SDK WS 路由、daemon.py、robot_app_lock.py、startup_app_config.py 生命周期、共享实例、后端线程、占用与持久配置相关路径
SDK daemon/backend/abstract.py,robot、mockup_sim、mujoco 的 backend.py 初始化、目标与 IK、控制循环、动作/取消/上传播放和事件;未声明逐行审计所有命令
SDK kinematics/analytical_kinematics.py、motion/move.py、motion/goto.py 轨迹接口、默认 IK wrapper、运动学数据入口和限制
SDK media/media_manager.py、media_server.py LOCAL/WEBRTC/NO_MEDIA 装配,GLib、相机管线、音频清理相关实现
SDK apps/app.py、manager.py、sources/local_common_venv.py、sources/hf_space.py 应用发现/环境、进程启动、停止、占用与基类入口
conversation main.py、moves.py、dance_emotion_moves.py 实际装配、动作状态/队列/线程、导入依赖与退出
conversation conversation_handler.py、huggingface_realtime.py、console.py 会话、录播、真实 endpoint、事件、打断、工具调度与异常路径
conversation config.py、settings_store.py、memory.py、tools/core_tools.py、tools/background_tool_manager.py 设置优先级、文件写入、记忆形式、工具注册/执行/取消

固定源码副本位于 Reachy 临时源码目录(研究底稿,未随本专区发布)。本文新增检查为源码与图中类名、方法、路径的静态核对;未重复执行旧运动函数实验,未启动完整上游、未安装模型、未调用付费 API,也没有把任何图中的时序当作本次运行日志。