> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

研究与复查日期：2026年10月27日。本文承接五个产品的固定版本源码研究，回答实际调用链、状态归属、可抽取模块及自有产品接入方式。源码事实、复用建议与尚未验证的环节分别说明。没有修改产品代码或新增整机运行结论。

本文包含接入自有系统的建议。五个上游项目自身的完整架构分析、独立报告与 UML 视图，统一从 [源码架构总览](<%E6%9E%B6%E6%9E%84/%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%88.md>) 进入，不以本文的集成设想替代现有实现。

当前已新增 [HachimoDock 与 StackChan 架构对比](<%E6%9E%B6%E6%9E%84/HachimoDock%20%E4%B8%8E%20StackChan%20%E6%9E%B6%E6%9E%84%E5%AF%B9%E6%AF%94.md>)：主机屏幕／音频外设与两轴机械终端采用不同的优先参照。下文的StackChan表达执行建议以需要相应机械／屏幕能力为前提，不能仅因采用主机Agent就认定它是通用底座；HachimoDock的授权和版本缺口另列。

当前收敛结论与一张完整关系图见 [源码复用 总方案](<%E6%BA%90%E7%A0%81%E5%A4%8D%E7%94%A8%20%E6%80%BB%E6%96%B9%E6%A1%88.md>)。本篇保留早期的具体接缝与验证讨论，作为补充材料。

# 当前理解到哪一层

**已经能解释关键路径由谁调用、谁持有状态、命令怎样落到执行器，以及取消和完成分别意味着什么。** 尚未完成五套完整构建与真机运行，也未与公司当前产品源码逐文件对接；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入口](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/main.cpp#L16-L62)、[表情适配](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/board/stackchan_display.cc#L321-L378)、[Servo](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/motion/servo.cpp#L38-L124) | 从会话事件到表情／目标／实际驱动的分层；状态与停止并非一个变量 |
| [Reachy动作线程](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py#L38)、[SDK入口](https://github.com/pollen-robotics/reachy_mini/blob/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb/src/reachy_mini/reachy_mini.py#L104)、[音频队列](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/console.py#L923) | 动作与媒体不同生命周期；所读MovementManager默认60Hz，旧100Hz注释不能作为实测频率 |
| [Petoi合约](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py#L10)、[执行器](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py#L13)、[传输](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py#L33) | 模型只提议有限命令，执行器给超时并尝试停止；回显的含义需要逐协议确认 |
| [Coglet原函数与反例](<Coglet%20%E6%9C%BA%E6%A2%B0%E8%A1%A8%E6%83%85%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>)、[Doly接口与二进制范围](<Doly%20%E4%BC%A0%E6%84%9F%E4%B8%8E%E4%BA%A4%E4%BA%92%20SDK%20%E7%A0%94%E7%A9%B6.md>) | 不能把源码可见、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服务。模型选择与机器人命令协议应分开。

# 接入自有系统的职责边界

下面是根据已读源码提出的目标职责图；返回状态已单独画出。模块可以先放在同一进程，不要求拆成多个服务。

![架构与复用方案 图示](<../diagrams/%E6%9E%B6%E6%9E%84%E4%B8%8E%E5%A4%8D%E7%94%A8%E6%96%B9%E6%A1%88%201.png>)

```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++主机测试还需可用编译环境 |
| 模拟接缝 | 用记录好的会话事件驱动少量表情与动作，模拟重复命令、取消、迟到回执和掉线 | 无越界参数，旧回合不污染新回合，终态与未知结果可区分，不把发送成功记为完成 |
| 接真实设备 | 在标定后的硬件测注视、有限手势、语音打断、异常时间步与断链 | 记录实际范围、停止／停声延迟、负载与故障恢复；达到依据实测设定的验收值 |
| 再接模型与用户场景 | 让模型通过同一有限接口生成动作，联合媒体与任务状态 | 模型不能绕过能力校验，真实事件仍经过同一执行与结果核验路径 |

这些是建议的验证步骤，本轮没有实施代码移植。当前已完成的是固定源码阅读、已有协议／纯函数／模拟传输检查，以及复用接缝和缺口定义。未完成完整构建、真机声学与动作验收、产品仓库对接，也没有测得研发节省比例或项目工期。

详细证据：[五个重点主报告](<%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>)、Reachy/Petoi复查笔记（研究底稿，未随本专区发布）、StackChan复查笔记（研究底稿，未随本专区发布）。所有旧测试仍按原日期和范围记录，本轮复读没有变成新增整机测试。
