> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

研究与源码核对日期：2026年10月27日。本组保留原五个产品的独立架构，新增HachimoDock深入报告及与StackChan的主机／硬件分工对照，回答代码组织、启动、状态、并发、模型与设备边界，以及完成／取消／故障的层次。结论基于固定GitHub提交，图示由代码关系重建。

方案结论与主机／硬件闭环先读 [源码复用 总方案](<../%E6%BA%90%E7%A0%81%E5%A4%8D%E7%94%A8%20%E6%80%BB%E6%96%B9%E6%A1%88.md>)。本篇保留六套上游现有架构的索引与归纳，作为总方案的证据。

# 从哪里开始阅读

原五项与新增HachimoDock分别有独立报告，保留组件、核心类、时序或状态视图，以及固定源码链接、阅读范围与未知部分。下表的“基本方案”是本次按实现归纳的架构风格，不是厂商统一命名。当前产品讨论先读 [HachimoDock 与 StackChan 架构对比](<HachimoDock%20%E4%B8%8E%20StackChan%20%E6%9E%B6%E6%9E%84%E5%AF%B9%E6%AF%94.md>)，其中授权限制与此前未选理由单列。

| **产品与独立报告** | **代码采用的基本方案** | **主要运行边界** | **配套图示** |
|---|---|---|---|
| [StackChan 源码架构](<StackChan%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | 小智会话主干＋机器人表达对象；另有独立 Avatar 应用、手机双通道控制与 Go 后端 | ESP32 固件、Flutter 手机 App、Go 服务；小智云服务另列 | 6 张：组件、类、任务协作、会话状态、AI 表达时序、LAN 时序 |
| [Reachy Mini 源码架构](<Reachy%20Mini%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | 客户端 SDK＋常驻设备服务＋可替换后端＋独立媒体通路＋应用进程 | SDK 应用／对话 App、daemon、媒体及外部模型服务；后端模块通常在 daemon 内 | 6 张：组件、类、daemon 状态、goto 时序、媒体、对话打断 |
| [Petoi 源码架构](<Petoi%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | Arduino 主循环＋共享状态／动作解释器；宿主用合约约束模型命令并串行执行 | BiBoard 固件、Python CLI、Ollama 服务 | 6 张：组件、固件类、宿主类、计数步态、WS 停止重试、动作状态 |
| [Coglet 源码架构](<Coglet%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | 联网语音 MCU 与机械表达 MCU 分工；本地合作式循环仲裁行为 | ESP32、RP2040、外部 Grove Vision AI V2；两条 UART 分别连接 | 6 张：组件、两侧类图、行为仲裁、动作时序、视觉时序 |
| [Doly 源码架构](<Doly%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | 设备本地 C++ 模块库＋Observer 事件＋逐功能 Python 绑定 | 自定义应用与设备共享库；核心控制实现主要是二进制边界 | 5 张：组件、类／namespace、动作时序、静态回调生命周期、传感时序 |
| [HachimoDock 源码架构](<HachimoDock%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) | 主机Rust／Node组织Agent输入及独立实时对话，USB连接P4本地组件／显示／音频运行时 | PC客户端、Node Bridge、外部Agent／模型服务、P4固件 | 4张：组件与会话、输入到Agent、请求与播放完成、固件调度 |

原五篇29张图，加HachimoDock四张和对比报告一张，共34张，分别保存可编辑Mermaid、PNG和SVG。Markdown同时附图与图源，阅读器无需支持Mermaid也能查看PNG。蓝、黄、黑及浅色背景用于区分边界，不表示成熟度或安全评级。

HachimoDock现有分工更贴近屏幕／音频／按键式主机外设；StackChan执行层更贴近有两轴机械表达的身体。HachimoDock当前许可与发行源码差距影响代码采用，不抹去其架构研究价值。它已提升为重点对照，仍未被登记为获授权的商业代码底座。详细筛选依据见 [开源资产专项](<../%E6%A1%8C%E9%9D%A2%E6%99%BA%E8%83%BD%E7%A1%AC%E4%BB%B6%20%E5%BC%80%E6%BA%90%E8%B5%84%E4%BA%A7%E4%B8%93%E9%A1%B9.md>)。

# 各项目的基本方案

## 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 两侧软件必须和引脚、姿态常量对应。它们是实际组成系统的条件，不是额外的产品实现建议。

# 固定源码与复核入口

| **对象** | **本次固定代码** | **关键入口／架构支撑** |
|---|---|---|
| StackChan | [工厂 eff0d6b5](https://github.com/m5stack/StackChan/tree/eff0d6b5109663faec8f1d98848b4b0e5246bbfc)；[小智 e77dedb1](https://github.com/78/xiaozhi-esp32/tree/e77dedb1309153bb63fed285772962c920c97dd4) | [固件入口](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/main.cpp)、[表达对象](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/stackchan.h) |
| Reachy Mini | [SDK d3240b92](https://github.com/pollen-robotics/reachy_mini/tree/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb)；[对话 b731ea1f](https://github.com/pollen-robotics/reachy_mini_conversation_app/tree/b731ea1fd6ce53232f1b13609331271358e10bd9) | [SDK](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/reachy_mini.py)、[backend](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/daemon/backend/abstract.py) |
| Petoi | [固件 f5aba6b9](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/tree/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef)；[CLI 60a76bc9](https://github.com/PetoiCamp/opencat-gemma/tree/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5) | [Arduino 入口](https://github.com/PetoiCamp/OpenCatEsp32-Quadruped-Robot/blob/f5aba6b9cb7e4f2062f77365fbcd0c388acf32ef/OpenCatEsp32.ino)、[runner](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py) |
| Coglet | [31f3c61b](https://github.com/will-cogley/Coglet/tree/31f3c61b05a88980d0bf56b397ffea473e79c0da) | [ESP Application](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/main/application.cc)、[RP 主循环](https://github.com/will-cogley/Coglet/blob/31f3c61b05a88980d0bf56b397ffea473e79c0da/CogletESP/RP2040/main.py) |
| Doly | [dc6f9c6b](https://github.com/robotdoly/DOLY-DIY/tree/dc6f9c6bd25510710d23b215c553680d37cd8ded) | [Drive 接口](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/DriveControl.h)、[Python 绑定](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp) |
| HachimoDock | [b56375a6](https://github.com/YizhengWw/HachimoDock/tree/b56375a6329caf5acb4952b5bb3cd8ddd91fe501) | [主机USB](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs)、[固件入口](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_main.c) |

# 图示怎样对应源码

组件图解释调用、数据与运行边界，不把逻辑分组自动画成进程。类图使用真实类名、namespace 标注与实际拥有／引用关系，不为过程式模块补造类。时序图选择真实入口、异步边界与回调，图中替代分支代表源码条件，不代表本次运行日志。状态图注明代码原生状态还是分析重建的生命周期，省略分支也会在各篇说明。

34张图的Mermaid解析、PNG／SVG、源码块与独立.mmd一致性、相对链接及固定源码定位按各轮记录核验。图示完整性以各篇列出的阅读范围为限，不将二进制、驱动、模型服务和未读依赖补成已确认内部结构。

# 本轮深度与结论边界

六篇独立报告均推进到具体入口、调用链、状态、并发、协议和释放路径，另有HachimoDock／StackChan的场景对照。Doly底层算法及其他项目未读依赖仍明确留白。此前局部无硬件实验只在适用位置引用，本轮没有新增完整固件构建、真机运行、模型调用或长期稳定性测试。

最值得保留的基本区别是：StackChan围绕会话与表达适配，Reachy围绕常驻设备服务，Petoi围绕动作解释器和有限命令合约，Coglet围绕MCU分工与本地仲裁，Doly围绕模块库和异步事件，HachimoDock围绕主机交互与USB外设。这些实现各自的代价已经包含在状态、并发与反馈边界中。

选型、市场与许可背景见 [开源资产专项](<../%E6%A1%8C%E9%9D%A2%E6%99%BA%E8%83%BD%E7%A1%AC%E4%BB%B6%20%E5%BC%80%E6%BA%90%E8%B5%84%E4%BA%A7%E4%B8%93%E9%A1%B9.md>)。此前的 [架构与复用方案](<../%E6%9E%B6%E6%9E%84%E4%B8%8E%E5%A4%8D%E7%94%A8%E6%96%B9%E6%A1%88.md>) 保留为另一个问题的材料：它讨论接入建议，不作为本组上游现状架构的主入口。
