DreamSoul研究
源码与架构 /

架构与复用方案

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

研究与复查日期:2026年10月27日。本文承接五个产品的固定版本源码研究,回答实际调用链、状态归属、可抽取模块及自有产品接入方式。源码事实、复用建议与尚未验证的环节分别说明。没有修改产品代码或新增整机运行结论。

本文包含接入自有系统的建议。五个上游项目自身的完整架构分析、独立报告与 UML 视图,统一从 源码架构总览 进入,不以本文的集成设想替代现有实现。

当前已新增 HachimoDock 与 StackChan 架构对比:主机屏幕/音频外设与两轴机械终端采用不同的优先参照。下文的StackChan表达执行建议以需要相应机械/屏幕能力为前提,不能仅因采用主机Agent就认定它是通用底座;HachimoDock的授权和版本缺口另列。

当前收敛结论与一张完整关系图见 源码复用 总方案。本篇保留早期的具体接缝与验证讨论,作为补充材料。

当前理解到哪一层

已经能解释关键路径由谁调用、谁持有状态、命令怎样落到执行器,以及取消和完成分别意味着什么。 尚未完成五套完整构建与真机运行,也未与公司当前产品源码逐文件对接;Doly只能读到公开接口和绑定,底层二进制内部仍不可见。

复用方案以 既有端侧智能体架构案例(关联研究资料,未随本专区发布) 的会话、用例、权限、执行与状态分工为参照。该案例本身也是研究方案,不是已实现的公司产品架构。本轮没有读取到本地aios产品仓库,不将职责映射写成已确认代码改动清单。

对象 已理清的实际调用路径 状态、完成与取消的边界
StackChan app_main初始化HAL并进入小智Application;网络情绪事件进入主循环,Display映射到表情/动作;HAL更新任务调用StackChan更新,Servo最后写SCS舵机 Application持会话状态,Display持修饰器,Servo持目标和插值状态。移除说话修饰器、停止运动、停音频和断扭矩是不同操作;读到isMoving也不等于业务动作已成功
Reachy Mini 应用将SDK对象交给MovementManager;命令队列进入动作线程,求值Move并合成目标,set_target经WebSocket到daemon后端和电机驱动 动作线程持队列与当前动作。按动作时长结束不等于传感器确认到位;媒体另有输出队列及playback epoch,运动取消不会自动替它取消音频
Petoi本地指令层 CLI请求模型,解析JSON,Contract校验,Runner生成有限计划,Link逐条发送,再等待协议回执 状态是当前计划与发送循环,没有完整持久任务系统。异常尝试发送停止,失败会记录;串口回显或WS completed属于协议语义,不能当物理到位证明
Coglet ESP会话/MCP工具发送UART状态或action;RP2040仲裁校准、一次性动作、表情与视觉;Servo积分再输出PWM 工具返回true发生在机械动作之前;临时动作以时间结束,没有业务完成回执。已复现大时间步长越关节限位
Doly Python应用经pybind11进入设备共享库,调用动作/传感API并接收回调 已读命令ID、事件与回调生命周期;核心库实现未公开,无法据头文件证明限幅、停止或防跌落机制可靠

固定源码证据集中在以下表格,完整版本与许可见各专题。

依据 支撑的具体判断
StackChan入口、表情适配、Servo 从会话事件到表情/目标/实际驱动的分层;状态与停止并非一个变量
Reachy动作线程、SDK入口、音频队列 动作与媒体不同生命周期;所读MovementManager默认60Hz,旧100Hz注释不能作为实测频率
Petoi合约、执行器、传输 模型只提议有限命令,执行器给超时并尝试停止;回显的含义需要逐协议确认
Coglet原函数与反例、Doly接口与二进制范围 不能把源码可见、API存在和整机执行可靠当成同一结论

建议复用的组合

自有角色与任务系统,加StackChan的表达执行层、Reachy的动作协调机制、Petoi的有限命令约束。 这是组件选择建议,不是将三套机器人完整软件同时部署。具体选择应随目标硬件和上位机语言确定。

材料 具体复用方式 需要我们补上的部分
StackChan motion_math 优先抽归一化视线、坐标到角度的纯函数;保留原测试与单位约定 固定坐标系、零位、机械范围、异常输入与标定数据。其角度接口使用十分之一度,不能直接传Reachy的弧度或米制姿态
StackChan Avatar/Modifier/Motion 作为小屏脸和两轴表达终端的候选主体;在Display的事件适配处接入自有表情/姿态命令 保留或替换LVGL、smooth_ui_toolkit、时钟、对象生命周期与舵机驱动。厂商账号/云/OTA不是数学与表达层固有依赖,但脱离原业务脚手架仍需独立构建验证
Reachy姿态/插值/Move 复用动作的duration/evaluate契约与轨迹求值;参考队列、单写动作状态及倾听/说话的协调方式 将六自由度头部、触角和身体映射到目标硬件。两轴头部只保留可表达部分,不把其IK/Rust驱动带给不匹配的机构
Reachy媒体取消 借鉴playback epoch,使被打断回复的迟到音频丢弃 让自有会话用例同时通知音频与运动取消,并核查设备缓冲中的残留;不能只清上位机队列就宣称已经停声
Petoi contract.py/runner.py Python上位机可隔离原合约与有限执行器,替换为自有命令表;其他语言可按同一数据契约重实现 增加总命令数与总时长限制、会话/命令关联、取消、迟到回执和断链策略。裁剪跳跃、翻滚等不适用动作;重新实现设备编码与反馈
Coglet/Doly 参考双MCU分工、动作所有权、异步事件和回调清理;需要代码时先处理授权 Coglet自有部分NC且运动边界待修;Doly SDK与绑定同样NC,核心.so不可作为自有硬件驱动源码直接移植

Reachy的MovementManager目前不能原文件无条件搬走:顶层依赖SDK,EmotionQueueMove还会带入舞蹈库。应移除或替换这些导入,把设备写入和动作供应者收敛为实际需要的接口。导入模块不等于已连接硬件,但构造ReachyMini会连接daemon并配置媒体;完整SDK/AppManager也不能当纯动作库使用。使用原Reachy硬件时,则可保留厂商SDK与daemon,在其上实现自有应用。

Petoi的CLI、Ollama、串口与BLE不是复用合约的前提。若我们的宿主运行时不是Python,不建议仅为少量校验代码引入一个常驻Python服务。模型选择与机器人命令协议应分开。

接入自有系统的职责边界

下面是根据已读源码提出的目标职责图;返回状态已单独画出。模块可以先放在同一进程,不要求拆成多个服务。

架构与复用方案 图示
架构与复用方案 图示 · 点击查看原图
查看 Mermaid 图源
flowchart TB
  U[自有会话、角色、记忆与任务用例]
  M[现有模型与工具调用]
  P[现有动作政策加设备能力校验]
  E[表达协调:一个写入方持有当前动作]
  A[按所选硬件实现设备适配]
  H[屏幕、舵机与传感器]
  V[既有语音与媒体通道]
  U --> M
  M -->|表情或动作提议| P
  P -->|允许的有限指令| E
  E --> A
  A --> H
  H -->|回执、测量或故障| A
  A -->|接收、播放结束、核验结果分别记录| U
  U -->|播放与取消| V
  U -->|开始、打断、取消| E

角色、人设、长期记忆、用户权限和任务终态继续由自有用例负责。设备层不接管这些业务;模型输出也先经过已存在的动作政策与能力检查。表达协调层负责空闲、倾听、说话及用户指定动作之间的优先级,并保持对最终目标的单一写入权,避免几个线程同时改同一舵机。

起步只需定义目标硬件实际支持的少量动作,例如表情、注视、有限手势、停止。命令携带所属会话/回合和唯一ID、有效期及明确参数单位;适配层负责坐标、量程与当前能力转换。这些是本方案的建议字段,不是声称五个上游已经共享一套协议。

“已接收”“轨迹播放结束”“传感器确认到位”分别记录。缺少回读传感器时,就只报告已有的协议或时间结果,不伪装物理核验。超时或断链后也不盲目重发可能已经执行的动作。

以一轮打断为例

用户说话时,媒体侧将旧回复的epoch失效,停止继续提交该回复的声音;动作侧取消旧说话动作,再按优先级进入倾听表现。迟到音频和旧回合的动作/回执都不能覆盖新回合。

这要求一次打断覆盖两个执行器。StackChan的AbortSpeaking本身主要是置标记并发协议消息,移除Modifier也只停止继续生成对应表现;Reachy的动作stop默认还会启动两秒归中,不能视为立即急停。应由自有用例根据硬件选择保持、缓停或归中,再确认实际结果。停止运动与断扭矩由驱动分别实现。

动作合法性要检查生成后的每个目标,而不只检查模型给出的最终目标。以关节$i$为例,目标系统需要维持约束 $q_{\min,i}\le q_i(t)\le q_{\max,i}$,其中$q_i(t)$为当前下发角度,单位必须在接口中明确。Coglet的反例正说明:目标已限幅,离散积分仍可能越过关节范围。上式是本方案要验证的不变量,不是现有五套系统均已证明成立的结论。

从调研到可采用代码的最短验证路径

步骤 具体工作 达到什么条件才向下推进
固定一条基线 先选一个表达终端、宿主语言及已核许可模块,固定提交/补丁/依赖,给每个外部文件留来源与声明 对所选组合能说明源码、版本、依赖、单位和构建入口;StackChan现有C++主机测试还需可用编译环境
模拟接缝 用记录好的会话事件驱动少量表情与动作,模拟重复命令、取消、迟到回执和掉线 无越界参数,旧回合不污染新回合,终态与未知结果可区分,不把发送成功记为完成
接真实设备 在标定后的硬件测注视、有限手势、语音打断、异常时间步与断链 记录实际范围、停止/停声延迟、负载与故障恢复;达到依据实测设定的验收值
再接模型与用户场景 让模型通过同一有限接口生成动作,联合媒体与任务状态 模型不能绕过能力校验,真实事件仍经过同一执行与结果核验路径

这些是建议的验证步骤,本轮没有实施代码移植。当前已完成的是固定源码阅读、已有协议/纯函数/模拟传输检查,以及复用接缝和缺口定义。未完成完整构建、真机声学与动作验收、产品仓库对接,也没有测得研发节省比例或项目工期。

详细证据:五个重点主报告、Reachy/Petoi复查笔记(研究底稿,未随本专区发布)、StackChan复查笔记(研究底稿,未随本专区发布)。所有旧测试仍按原日期和范围记录,本轮复读没有变成新增整机测试。