DreamSoul研究
源码与架构 /

源码架构总览

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

研究与源码核对日期:2026年10月27日。本组保留原五个产品的独立架构,新增HachimoDock深入报告及与StackChan的主机/硬件分工对照,回答代码组织、启动、状态、并发、模型与设备边界,以及完成/取消/故障的层次。结论基于固定GitHub提交,图示由代码关系重建。

方案结论与主机/硬件闭环先读 源码复用 总方案。本篇保留六套上游现有架构的索引与归纳,作为总方案的证据。

从哪里开始阅读

原五项与新增HachimoDock分别有独立报告,保留组件、核心类、时序或状态视图,以及固定源码链接、阅读范围与未知部分。下表的“基本方案”是本次按实现归纳的架构风格,不是厂商统一命名。当前产品讨论先读 HachimoDock 与 StackChan 架构对比,其中授权限制与此前未选理由单列。

产品与独立报告 代码采用的基本方案 主要运行边界 配套图示
StackChan 源码架构 小智会话主干+机器人表达对象;另有独立 Avatar 应用、手机双通道控制与 Go 后端 ESP32 固件、Flutter 手机 App、Go 服务;小智云服务另列 6 张:组件、类、任务协作、会话状态、AI 表达时序、LAN 时序
Reachy Mini 源码架构 客户端 SDK+常驻设备服务+可替换后端+独立媒体通路+应用进程 SDK 应用/对话 App、daemon、媒体及外部模型服务;后端模块通常在 daemon 内 6 张:组件、类、daemon 状态、goto 时序、媒体、对话打断
Petoi 源码架构 Arduino 主循环+共享状态/动作解释器;宿主用合约约束模型命令并串行执行 BiBoard 固件、Python CLI、Ollama 服务 6 张:组件、固件类、宿主类、计数步态、WS 停止重试、动作状态
Coglet 源码架构 联网语音 MCU 与机械表达 MCU 分工;本地合作式循环仲裁行为 ESP32、RP2040、外部 Grove Vision AI V2;两条 UART 分别连接 6 张:组件、两侧类图、行为仲裁、动作时序、视觉时序
Doly 源码架构 设备本地 C++ 模块库+Observer 事件+逐功能 Python 绑定 自定义应用与设备共享库;核心控制实现主要是二进制边界 5 张:组件、类/namespace、动作时序、静态回调生命周期、传感时序
HachimoDock 源码架构 主机Rust/Node组织Agent输入及独立实时对话,USB连接P4本地组件/显示/音频运行时 PC客户端、Node Bridge、外部Agent/模型服务、P4固件 4张:组件与会话、输入到Agent、请求与播放完成、固件调度

原五篇29张图,加HachimoDock四张和对比报告一张,共34张,分别保存可编辑Mermaid、PNG和SVG。Markdown同时附图与图源,阅读器无需支持Mermaid也能查看PNG。蓝、黄、黑及浅色背景用于区分边界,不表示成熟度或安全评级。

HachimoDock现有分工更贴近屏幕/音频/按键式主机外设;StackChan执行层更贴近有两轴机械表达的身体。HachimoDock当前许可与发行源码差距影响代码采用,不抹去其架构研究价值。它已提升为重点对照,仍未被登记为获授权的商业代码底座。详细筛选依据见 开源资产专项。

各项目的基本方案

StackChan:把语音状态翻译成表达对象

工厂固件并非只有“语音模块调用舵机”。启动先进入 Mooncake 应用管理,选择 AI 应用时销毁应用管理器,再把控制权交给固定的小智 Application。小智仍负责听说状态、音频与协议,工厂的 Display/Board 适配将这些事件映射到 StackChan 的 Avatar、Modifier 和 Motion。表情是元素状态与修饰器协作,运动又有自己的 Servo 目标及插值。

独立 Avatar 模式有另一条手机控制链。Flutter App 管理 BLE 配网、远端 WS 和本地 LAN;LAN 是手机开服务、设备连进来,当前本地 endpoint 通告还经过远端路径。两种传输落到共同 HAL 信号和动作接口,却不能与 AI 模式的单次语音会话合并成一条链。Go 服务处理身份、绑定、设备路由等,不等于公开了云端 ASR/LLM/TTS 的全部实现。

它体现的是复用会话框架,替换产品表达层。结构重点在状态桥、更新任务和生命周期交接。理解这套方案要同时读固定依赖和补丁,单读 stackchan 类目录会漏掉程序实际装配方式。

Reachy Mini:设备服务集中持有硬件与执行状态

应用调用 Python SDK,SDK 经 WebSocket 与 daemon 交换命令、快照和任务结果。daemon 内的后端拥有目标、轨迹与执行循环,真实硬件、Mockup 和 MuJoCo 后端共享接口但实现能力不同。API 路由、daemon 与 backend 是职责分层,不是三个独立微服务。

媒体另走 GStreamer/WebRTC 等通路,避免把图像与连续音频塞入同一条控制消息流。AppManager 负责应用发现、环境、子进程和占用。官方对话 App 再把 HF realtime、录播、工具与 MovementManager 组装起来。模型响应经过工具与动作管理器,不直接变成电机寄存器写入。

它体现的是服务端拥有设备,客户端表达意图。这让真实设备、仿真与多种应用较容易共用接口,代价是任务、运动、媒体和对话分别有状态与取消机制,不能用一个“stop 成功”概括整条链。

Petoi:受约束的高层命令驱动预制动作解释器

固件由 Arduino 入口和大量含实现的头文件组装,readSignal、reaction、Skill、运动输出及共享全局状态形成主链。Skill 解释动作表,按 period 和帧结构推进姿态、步态与行为序列,IMU 在额外任务中更新姿态/异常数据。TaskQueue 与 WebTask 是两套不同结构,前者安排命令与延时,后者跟踪 Web 事务。

宿主 opencat-gemma 以 Contract 同时约束提示词、schema、命令正则及运行检查。模型返回有限命令后,runner 再形成有限计划,通过 Serial/BLE/WebSocket Link 顺序发送并等待各自语义的回执。LLM 是宿主请求的外部服务,动作知识和基本执行仍在固件。

它体现的是模型选择有限动作,确定性固件解释执行。这种结构与自由生成关节轨迹不同,也不自动等于安全动作集合。Quaddle 宿主合约公开,而其内部固件未公开,本组不将旧 OpenCat 实现冒充新品内部架构。

Coglet:把表达仲裁留在机械控制 MCU

ESP32 沿小智结构负责网络、语音与工具,发送会话状态、情绪名或 action: 文本。RP2040 维护最新情绪、独立说话标记、临时动作槽、视觉跟随和 PWM 输出状态。核心不是复杂的类层次,而是主循环的调用顺序与轴所有权:校准分支优先,其次临时动作,再到普通表情、视觉和独立口部动画。

Grove Vision 模块单独推理,RP 处理检测框、中值/EMA、死区、滞回和眼头协调,最终由 Servo 逐轴插值。ESP32 侧相机工具是另一条路径。该方案不需要把音频帧、图像与全部行为运算放在同一个 MCU 上。

它体现的是按硬件职责分工,以小协议连接。边界简单,但当前 UART 没有动作 ID、ACK 和完成回传。校准也不是对所有 PWM 写入的严格互斥:接收阶段的动作初始化可能在校准更新之前直接写出。该细节已在独立报告与仲裁图中保留。

Doly:应用直接调用设备库,通过事件得到结果

公开头文件按 Control、Event、EventListener 分功能。Python 通过 pybind11 扩展调用相同 C++ namespace API,C++ 应用可以直接链接。控制操作使用 ID,完成和错误通过事件返回。绑定源码处理回调注册、GIL、互斥锁、强引用与清理,是能实际展开分析的核心部分。

这里没有取得完整的默认人格/对话应用和底层控制实现。核心 .so 后面的 worker、运动算法、事件容器与实时策略仍不可见。因此它只能支持本地模块 SDK 与异步事件接口这一层的架构结论,不能补画一套完整开源 Agent 系统。

这种方案允许自定义应用直接接管整机功能,代价是模块生命周期与资源协调由应用和库共同承担。各模块同叫 dispose 也不能假定释放范围相同:Eye 绑定主要清监听器,Drive 则继续调用底层 dispose。

HachimoDock:主机组织交互,USB外设保留本地执行

PC上的Tauri/Rust和Node Bridge管理设备输入、外部Agent会话与状态,P4负责输入解释、屏幕/组件状态机、音频采集/播放。外部Agent伴随/输入和主机自己的实时人格对话是两条独立路径;实时链含ASR/模型/TTS,不能因为代码在电脑或连接USB就认定默认离线。

它体现的是主机外设结构,已有requestId关联、分主题status、播放完成诊断与资源事务。但普通协议ACK、音频完成、资源commit和Agent done有不同语义,不能合并为通用action成功。其结构更贴近当前主机大脑方向,商业与独立产品代码采用仍受授权及源码/安装包版本差距约束。详细机制见独立报告,场景判断见与StackChan对比。

横向比较:模块、状态和并发

程序从哪里开始,状态归谁

对象 启动主链 主要状态归属 不能合并的状态
StackChan app_main → HAL / Mooncake → AppAiAgent → 小智 Application;Avatar 是另一应用路径 Application 持会话;Display/Modifier 持表达;Motion/Servo 持目标和插值;手机 AppState 持连接与设备上下文 听说状态、表情、运动目标、连接状态、扭矩使能
Reachy Mini daemon 建立共享实例与 backend;SDK 连接;App 独立启动并取得设备客户端 daemon/backend 持执行目标;SDK 缓存快照与等待事件;MovementManager 持应用动作;realtime 持音频/会话状态 daemon 生命周期、后端任务、应用动作队列、媒体播放、模型响应
Petoi Arduino setup → initRobot,随后 loop;宿主 CLI 另行加载合约与 Link 当前 token/输入/帧/计数多为固件共享全局;Skill 持动作元数据;WebTask 持 Web 事务;CLI 持本次计划 TaskQueue、WebTask、当前 Skill、IMU 异常与宿主计划
Coglet ESP app_main → Application.Start;RP 导入 Servo/动画,检查 PCA 后进循环 ESP Application 持会话;RP 模块变量持表情/speech_active/动作槽;EyeFollower 持跟踪;Servo 持软件位置 情绪与说话、动作时间窗与校准、软件收敛与 PWM 使能
Doly 示例应用停标准 service,再注册/init/发命令/查询/dispose Python 模块持注册表与回调引用;C++ 库状态由接口暴露,内部持有方式未知 命令接受、DriveState、命令 ID 完成事件、静态函数 gate、对象监听器
HachimoDock PC装配USB/Bridge/会话服务;P4 app_main建立接收任务、协议worker及本地循环 PC持连接/waiter/PTT/实时会话;Node持输入投递与Agent流;P4持显示/组件/音频状态 USB响应、Agent回合、音频播放、组件资源提交和设备输入上下文

此表把真实拥有关系作为比较单位。一个类名不等于一个线程,一个目录不等于一个部署单元,模块全局字典也不等于代码中存在一个总控制器类。

并发与协调采用什么机制

对象 可见执行域 协调方式 由此带来的边界
StackChan FreeRTOS 主事件/音频/HAL 更新/网络任务,手机和 Go 独立运行 Schedule、事件位、LVGL 锁、网络队列、对象池更新与连接代际 多条控制路径的销毁和回退不同;队列投递或发送成功不保证动作完成
Reachy Mini SDK 线程,daemon asyncio+backend 线程,GLib 媒体,对话录播/动作/工具任务 Lock、Event、Queue、任务 ID、上传令牌、playback epoch、媒体 flush 层次丰富,但没有一个已核实的跨模型/音频/运动全局取消事务
Petoi Arduino 主循环+Core 0 IMU 任务;宿主同步计划+BLE/WS 辅助线程 全局缓冲、TaskQueue、WebTask 注册表、传输回执与有限超时 阻塞动作和队列延时影响后续输入,不能画成所有命令公平独立排队
Coglet ESP FreeRTOS;RP 单循环;视觉模块独立推理 MCU 间文本行、RP 固定调用顺序、毫秒计时、轴目标覆盖 RP 并发主要是合作式推进;负载改变 dt,接收阶段副作用不完全受持续更新仲裁
Doly 应用线程+库可能发出的异步事件;库线程细节未知 pybind11 GIL、模块 mutex、静态函数 gate、listener 强引用、注销 能解释跨语言边界,不能证明 .so 内部 join、控制周期或竞态行为
HachimoDock PC reader/writer、Rust会话/Player和Node子运行时;P4 RX/协议/输入/音频任务及主循环 waiter、requestId/sessionId、主机generation/epoch、板端队列/state mutex与渲染快照 不同链路校验和取消不等价;队列满、超时、重启均不能推定任务未执行

模型、动作与反馈之间实际隔了几层

对象 上层输入变成动作的主链 代码中的“完成” 取消或停止
StackChan 网络状态/emotion → Application/Display → Modifier/Motion → Servo 移除行为、插值状态、网络发送各有意义,没有统一机械验收事务 AbortSpeaking、移除 Modifier、Motion.stop、释放扭矩是不同操作
Reachy Mini 模型/工具/应用 → MovementManager 或 SDK → WS → backend → 驱动 goto 任务返回/上传播放终态/关节状态快照彼此不同 模型取消、工具取消、运动停止与音频失效分别处理
Petoi 模型输出 → Contract 校验 → runner 有限计划 → Link → reaction/Skill → PWM 串口 token 回执、BLE 收包、WS completed/error 依实现分支定义;部分回执是受理点,部分延后 异常尝试发送停止;Web 事务超时或断线清理本身不必然停止当前运动
Coglet MCP 工具 → 板级回调 → UART → RP 动作槽 → Servo → PWM 工具立即 true;RP 两秒动作窗;均无下位机完成回传 新动作替换旧动作、校准分支优先、状态恢复;没有对应取消结果消息
Doly Python/C++ 应用 → Control API → 二进制实现 → Event/Listener bool 接受与带 ID 完成/错误事件区分;事件触发的内部物理条件未知 abort API/错误事件、注销监听器与 dispose 不能合并为同一件事
HachimoDock 主机服务 → USB topic → 协议/本地组件或音频;外部Agent注入另经Bridge/Bus protocol ACK、media/status、音频completed、资源ACK和Agent done分别解释 主机epoch、板端session过滤、媒体stop、Agent abort各有范围;没有统一跨域取消事务

一个共同点是:高层语义几乎都没有直接等同于“电机已到位且动作业务成功”。区别在于反馈能力和层次是否显式。Doly 声明了动作 ID 和完成事件,Reachy 有任务与状态,Petoi 有命令回执,Coglet 这条桥更接近单向请求。反馈更丰富也仍需读清它在哪个条件触发,不能只按字段名排序。

持久化与版本装配也是架构的一部分

对象 配置/持久化 必须固定的组合
StackChan 设备 NVS/配网配置、手机偏好、Go 数据持久化分属不同运行域 工厂提交+小智 v2.2.4 固定依赖+patch+手机/服务器协议版本
Reachy Mini daemon 启动/应用配置、应用环境;对话设置和记忆文件独立 SDK 与对话 App 提交、后台服务、媒体原生依赖、运动学库与硬件/仿真后端
Petoi Preferences、按板型可选 EEPROM、编译动作表;宿主 JSON 合约与模型配置 固件机型/板型宏、动作表、CLI 合约、传输协议;作者旧硬件测试与当前源码分开
Coglet ESP32 NVS 和 OTA 配置;RP 主要是 Python 常量与 RAM 状态 ESP 固件、RP 脚本、Grove 模块模型/协议、PCB 版本;未核实统一更新/回滚协议
Doly Helper 的设备配置接口与 XML 错误;底层写入位置和一致性未知 设备系统镜像、.so、头文件、Python ABI/扩展、固定安装目录
HachimoDock PC设置/状态文件和RAM会话;P4 NVS绑定、SPIFFS素材/组件及RAM媒体 PC/固件/板型锁文件、资源与协议schema;公开PC0.1.101不能等同最新0.1.167发行

这解释了为什么“仓库能下载”不足以证明整套系统可重建。StackChan 的 patch 与固定上游共同定义程序;Doly 的源头文件和 Python 包还依赖设备二进制;Coglet 两侧软件必须和引脚、姿态常量对应。它们是实际组成系统的条件,不是额外的产品实现建议。

固定源码与复核入口

图示怎样对应源码

组件图解释调用、数据与运行边界,不把逻辑分组自动画成进程。类图使用真实类名、namespace 标注与实际拥有/引用关系,不为过程式模块补造类。时序图选择真实入口、异步边界与回调,图中替代分支代表源码条件,不代表本次运行日志。状态图注明代码原生状态还是分析重建的生命周期,省略分支也会在各篇说明。

34张图的Mermaid解析、PNG/SVG、源码块与独立.mmd一致性、相对链接及固定源码定位按各轮记录核验。图示完整性以各篇列出的阅读范围为限,不将二进制、驱动、模型服务和未读依赖补成已确认内部结构。

本轮深度与结论边界

六篇独立报告均推进到具体入口、调用链、状态、并发、协议和释放路径,另有HachimoDock/StackChan的场景对照。Doly底层算法及其他项目未读依赖仍明确留白。此前局部无硬件实验只在适用位置引用,本轮没有新增完整固件构建、真机运行、模型调用或长期稳定性测试。

最值得保留的基本区别是:StackChan围绕会话与表达适配,Reachy围绕常驻设备服务,Petoi围绕动作解释器和有限命令合约,Coglet围绕MCU分工与本地仲裁,Doly围绕模块库和异步事件,HachimoDock围绕主机交互与USB外设。这些实现各自的代价已经包含在状态、并发与反馈边界中。

选型、市场与许可背景见 开源资产专项。此前的 架构与复用方案 保留为另一个问题的材料:它讨论接入建议,不作为本组上游现状架构的主入口。