> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

研究对象为 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 组件](<%E5%9B%BE/Reachy%20Mini%20%E7%BB%84%E4%BB%B6.png>)

```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 构造与客户端/媒体装配](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/reachy_mini.py#L104)、[FastAPI 在 app.state 中创建 Daemon 和 AppManager](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/app/main.py#L314)、[Daemon 资源持有](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/daemon.py#L42)、[对话应用装配](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/main.py#L172)。

# 源码树、依赖与启动入口

## 目录是职责分层，不是单独部署单元

| 固定仓库内路径 | 主职责 | 为什么单列，带来的代价 |
| --- | --- | --- |
| 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 在运行时决定，不能只看包名判断服务供应商。

声明的启动入口如下，仅展示源码入口，不表示本次已经执行：

```text
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 打包与依赖](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/pyproject.toml#L1)、[SDK 命令入口](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/pyproject.toml#L132)、[conversation 打包与入口](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/pyproject.toml#L5)、[daemon 参数和绑定策略](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/app/main.py#L75)、[App 基类上下文入口](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/app.py#L106)。

# 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 核心类](<%E5%9B%BE/Reachy%20Mini%20%E6%A0%B8%E5%BF%83%E7%B1%BB.png>)

```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 流程。

依据：[客户端缓存、线程和连接就绪](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_client.py#L60)、[SDK set_target 与 goto_target](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/reachy_mini.py#L610)、[任务模型](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/protocol.py#L1098)、[WS 任务分派及未实现分支](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L174)、[Move 接口](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/motion/move.py#L11)、[GotoMove](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/motion/goto.py#L15)。

# daemon 生命周期与三个后端

## 生命周期控制与设备循环分离

FastAPI lifespan 把当前 asyncio loop 交给 daemon，装配启动应用观察任务等资源。`Daemon.start` 选择后端，启动 WS 广播和状态发布，再在后端线程调用 `run`。后端通过 `ready` Event 报告可用；启动代码等待该 Event，超时或线程异常会进入错误处理。媒体在后端准备好后继续初始化，最后状态才进入 RUNNING。

`Daemon` 还保存重启参数、持有媒体服务和机器人应用占用锁。它负责“设备服务是否可用”，不是单个动作的任务管理器。状态发布线程约每秒广播 daemon 状态，而实际关节/位姿更新频率由具体后端决定。

![Reachy Mini Daemon 状态](<%E5%9B%BE/Reachy%20Mini%20Daemon%20%E7%8A%B6%E6%80%81.png>)

```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 启动](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/daemon.py#L370)、[停止与线程等待](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/daemon.py#L547)、[状态枚举](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/protocol.py#L51)、[Backend 初始化与运动学分支](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L148)、[目标合成和 IK](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L547)、[解析运动学与约束](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/kinematics/analytical_kinematics.py#L30)、[真实后端循环](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/robot/backend.py#L154)、[Mockup 后端](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/mockup_sim/backend.py#L26)、[MuJoCo 初始化与步长](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/mujoco/backend.py#L42)。

# 轨迹、任务、取消与反馈：完成到底表示什么

## 一次 goto 的完整链路

SDK 阻塞等待发生在应用线程，服务端执行则是 asyncio Task，物理控制又在后端线程。这允许控制服务继续处理消息，而不让一个长动作堵住所有 WS 接收。Backend 的 `goto_target` 构造 GotoMove，再进入 `play_move`；后者默认约 100 Hz 求值并更新目标。100 Hz 是轨迹采样请求频率，不能等同于电机通信频率，真实后端的 Python 控制循环是 50 Hz。

![Reachy Mini Goto 时序](<%E5%9B%BE/Reachy%20Mini%20Goto%20%E6%97%B6%E5%BA%8F.png>)

```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 等待与超时](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_client.py#L282)、[服务端 goto 返回语义](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L174)、[动作锁与停止字段](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L284)、[play_move 循环与 finally](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L829)、[上传取消和全局停止](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L2465)、[上传播放与事件](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L2864)、[广播与客户端队列](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L86)。

# 媒体架构：相机单一持有，传输与使用分开

`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 媒体路径](<%E5%9B%BE/Reachy%20Mini%20%E5%AA%92%E4%BD%93%E8%B7%AF%E5%BE%84.png>)

```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 默认控制链路和媒体链路分开的事实。

依据：[媒体门面和具体后端](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/media/media_manager.py#L105)、[SDK 自动配置与 no_media](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/reachy_mini.py#L329)、[GstMediaServer 状态与 GLib 线程](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/media/media_server.py#L196)、[媒体管线构建](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/media/media_server.py#L898)、[清除接收音频](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/media/media_server.py#L862)、[统一命令入口](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L1644)。

# 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 运行记录和启动](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/manager.py#L65)、[子进程创建与监视](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/manager.py#L218)、[停止策略](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/manager.py#L329)、[共用 apps_venv](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/sources/local_common_venv.py#L30)、[HF 应用目录发现](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/sources/hf_space.py#L186)、[RobotAppLock](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/robot_app_lock.py#L64)、[ReachyMiniApp 生命周期](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/apps/app.py#L106)。

# 官方对话应用：组装关系与真实 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 分配地址发请求，默认地址是：

```text
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 对话与打断](<%E5%9B%BE/Reachy%20Mini%20%E5%AF%B9%E8%AF%9D%E4%B8%8E%E6%89%93%E6%96%AD.png>)

```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 的存活机制是独立的。即使对话会话恢复，也不能推定此前运动命令被自动重放。

依据：[主入口与依赖装配](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/main.py#L172)、[App 子类](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/main.py#L392)、[ConversationHandler 状态](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/conversation_handler.py#L36)、[HF 处理器](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L163)、[分配器与 local 模式](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L1256)、[默认配置](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/config.py#L99)、[会话事件循环](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L874)、[音频 delta 与工具调用](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L1032)、[中断处理](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L283)、[清播放器](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/console.py#L923)、[播放循环](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/console.py#L998)、[输入发送与异常](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L1149)。

# 对话中的动作、工具任务与退出

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 明确调用：

```python
movement_manager.stop(reset_to_neutral=False)
```

随后关闭 wobbling、媒体并断开控制客户端。普通 App 停止保持机器人唤醒，由 daemon 在进程退出/占用释放后协调 neutral；语音 go_to_sleep 与不活动超时是专门的睡眠路径。这样切换应用不会被普通退出强制睡眠，代价是姿态收尾由 App 与 daemon 共同完成，必须区分“应用停写”与“设备归位”。

依据：[60 Hz 常量与 BreathingMove](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L48)、[MovementState 与管理器](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L132)、[动作队列推进](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L401)、[管理器 stop 默认行为](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L626)、[真实应用退出调用](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/main.py#L340)、[后台工具创建和完成](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/background_tool_manager.py#L127)、[取消工具](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/background_tool_manager.py#L225)、[dispatch 的取消与异常转换](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/core_tools.py#L472)。

# 并发、队列和时钟如何分工

下表是代码中执行域的归纳，不代表上游有一个同名总调度器。不同频率是名义设置，不是本次测得的实时性能。

| 执行域 | 持有的关键数据与同步方式 | 时钟/频率与架构含义 |
| --- | --- | --- |
| 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 接收与任务锁](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_client.py#L60)、[跨线程广播](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L86)、[真实后端循环](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/robot/backend.py#L154)、[动作时间循环](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L829)、[daemon 状态发布](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/daemon.py#L879)、[对话录音线程交接](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/console.py#L966)、[动作线程](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L167)。

# 配置持久化与扩展点

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 配置路径与校验](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/startup_app_config.py#L1)、[实例设置读取与原子替换](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/settings_store.py#L28)、[事实记忆存储](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/memory.py#L1)、[工具接口和 MCP 适配](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/core_tools.py#L37)、[工具加载与冲突检测](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/core_tools.py#L186)、[工具注册初始化](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/tools/core_tools.py#L408)。

# 架构取舍与尚不能从源码证明的部分

这套架构的优势在于设备服务集中持有状态、动作与媒体分别抽象、同一 API 可接真实和模拟后端、应用以子进程独立演进。官方对话应用也没有把模型响应直接写成串口命令，而是经过工具、动作管理器和 SDK 进入设备服务。代价是层次多、状态多，任何“成功”都必须带上所属层次。

需要保留的具体边界如下：

- **动作结果的层次。** set_target 是发送目标；TaskProgress 是后端协程结束；uploaded move 的 finished 是播放流程终态；关节快照是传感/模拟状态；它们都不是自动生成的闭环到位验收。依据：[命令处理](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L166)、[任务结束](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L174)。
- **取消并不统一。** 全局动作停止、upload_id 令牌、asyncio 工具取消、模型 response.cancel、应用音频 epoch 和媒体 flush 各解决一层问题，没有一个已核实的全局事务保证它们同时完成。依据：[动作停止](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L2479)、[对话中断](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L283)。
- **稳定性与实时性。** Python 多线程/asyncio、原生媒体与外部电机控制器组合，不构成硬实时保证；拥塞策略、线程重入锁、不同计时源都需要结合实机负载验证。依据：[广播队列](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/io/ws_server.py#L86)、[动作锁](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py#L284)。
- **外部实现边界。** 电机底层控制、Rust IK、GStreamer、MuJoCo 和 HF 实际服务均有本仓库之外的实现；本文确认调用与接口，不把 Python wrapper 的可读性当作这些依赖全部实现已审计。依据：[真实控制器创建](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/robot/backend.py#L32)、[Rust IK](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/kinematics/analytical_kinematics.py#L30)。
- **仿真与产品覆盖。** 模拟能支持一部分控制和视觉链路，不证明真实噪声、硬件寿命、多人抢占、断网恢复或长期会话均符合预期；HF 服务返回的模型和部署也未由客户端源码充分定义。依据：[MuJoCo 实现](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/mujoco/backend.py#L42)、[实时连接构建](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/huggingface_realtime.py#L1256)。

以上是此固定版本的架构事实与有标识的静态推导，不是安全认证、商业许可结论或整机可交付判断。软件、硬件、模型和动作数据的许可范围仍分别见 [Reachy Mini 平台 源码研究](<../Reachy%20Mini%20%E5%B9%B3%E5%8F%B0%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>)；本篇不将软件结构分析替代许可核查。

# 实际阅读范围与验证边界

| 仓库 | 已读源码范围 | 深度 |
| --- | --- | --- |
| 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，也没有把任何图中的时序当作本次运行日志。

