> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

研究归纳日期：2026年10月27日。本文将六个项目的固定源码研究收敛为一个接入建议，回答现有实现、复用位置、自写边界和最小验证顺序。上游现状以对应独立报告为依据，目标架构为待验证方案。

# 结论与总图

**建议采用“自有 Agent＋自写设备接缝＋MCU 本地感知与执行”的方案。架构分工参照 HachimoDock；需要机械表情时，优先隔离评估 StackChan 的 MIT 表达与运动模块；有限指令约束借鉴 Petoi，动作与媒体取消借鉴 Reachy。** 首版只连接一台设备，优先验证 USB／Serial 有线通路，暂不把多设备、无线发现和完整机器人平台作为前置条件。

当前不建议整仓继承某一个项目。HachimoDock 最接近主机外设分工，但自有代码的独立产品开发及商业集成需要书面授权，公开 PC 源码也与最新安装包不一致。StackChan 的机械执行模块更容易按文件评估复用，但它没有现成的自有 PC Agent 感知／动作闭环。我们的接缝应当由自己持有，以免角色、模型与管理界面被某一种硬件或上游云服务绑定。

![源码复用总图：现有实现、复用位置、主机硬件调用闭环](<%E5%9B%BE/%E6%BA%90%E7%A0%81%E5%A4%8D%E7%94%A8%20%E6%80%BB%E5%9B%BE.png>)

[查看可缩放 SVG 总图](<%E5%9B%BE/%E6%BA%90%E7%A0%81%E5%A4%8D%E7%94%A8%20%E6%80%BB%E5%9B%BE.svg>)。上排是已读上游实现，中下排是建议方案；黄色仅表示可评估的模块候选，具体仍按文件与依赖许可核对。

# 一条完整调用链

硬件采集实体输入，在设备端形成感知事件。主机接缝保留事件时间、来源与重启代次，转换为 Agent 可消费的输入。Agent 判断用户意图，通过有限工具入口提出 action。主机校验设备是否支持、参数单位与有效期是否正确，分配动作 ID，再交设备执行。设备在本地做资源仲裁、限位、缓冲和失联处理，返回动作状态、故障或测量。主机用结果更新任务台账，并决定是否继续、追问或向用户反馈。

例如，用户触摸硬件后，Agent 选择“显示倾听表情并播放一段回复”。按键感知、显示动作和音频动作分别关联到同一回合，动作各有 ID。用户再次说话时，主机使旧回合失效并取消旧动作，设备停止相应输出后返回实际结果。旧回合不再继续输出，但对应动作的迟到执行／取消结果仍按 ID 记录，不能一并丢弃。清空主机队列不能直接当作设备已停声或机械已停止。

| **方向** | **首版需要约定的内容** | **由谁负责** |
|---|---|---|
| 硬件 → 主机：感知（Sensation） | `device_id`、`boot_id`、`seq`、`captured_at`、类型和载荷／媒体引用；采样时钟口径、来源与质量随能力声明 | 设备负责采集、限速与基本校验；主机负责时间映射、归一化和 Agent 输入。`seq` 只在同一设备代次内比较，不冒充全局幂等键 |
| 主机 → 硬件：动作 | `action_id`、`turn_id`、动作名、参数、单位、有效期；使用设备已声明的有限能力 | 主机做语义、权限与能力校验；设备再次校验物理参数、当前资源和可执行状态。媒体帧独立承载，不逐帧经过 LLM |
| 主机 → 硬件：取消／查询 | `cancel(action_id)`、`get_status(action_id)`；明确哪些动作可取消、取消影响哪些资源 | 主机协调回合打断；设备停止对应本地执行并说明实际结果。无法停止、已结束和找不到动作分别返回 |
| 硬件 → 主机：结果 | 相同 `action_id`，`accepted`／`running`／`succeeded`／`failed`／`cancelled`，以及结果、错误和证据类型 | 设备报告自身能确认的执行状态；主机维护业务结果。超时或断链时，主机可记录 `unknown`，不能据此断定设备未执行 |

这里的字段与状态是本方案提出的契约，不是六个项目已经兼容的现成协议。`succeeded` 必须按能力定义：显示可以是帧已提交或已呈现，音频可以是已起播流缓冲排空，舵机可以是轨迹结束或传感器确认到位。不同证据必须分开标明，没有测量就不标物理核验成功。

# 他们的实现，分别放到哪里

| **上游与现状** | **复用位置与具体材料** | **首版决策** | **源码与依据** |
|---|---|---|---|
| HachimoDock：PC 管交互，P4 管输入、屏幕与音频，USB 连接；外部 Agent 伴随和主机实时对话是两条路径 | 主机设备桥、输入上报、请求关联、媒体状态和本地组件运行时的分工 | **以它的分工作架构参照，自有代码暂不作为商业移植基线**。不把协议 ACK 或 Agent done 当成设备动作完成 | [USB 主机](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs)、[请求关联](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial/transaction_waiters.rs)、[固件协议](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_protocol.c)、[许可](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/LICENSE)、[深入对比](<%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：小智会话映射到表达和运动；另有手机 Avatar 控制路径 | 有两轴机械表达时，设备端候选抽 `Avatar`／`Modifier`、`Motion`／`Servo`、`motion_math` 与匹配驱动的 HAL | **许可内抽模块，不继承整套手机、账号、云和 OTA 链**。新写 PC 适配、感知上报、动作 ID、取消及终态。没有两轴机构时不带入运动层 | [表达与运动目录](https://github.com/m5stack/StackChan/tree/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan)、[servo.cpp](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/motion/servo.cpp)、[HAL](https://github.com/m5stack/StackChan/tree/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal)、[MIT 许可](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/LICENSE)、[架构](<%E6%9E%B6%E6%9E%84/StackChan%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) |
| Petoi：主机模型输出经过 Contract 和 Runner，再发有限固件命令 | 主机 action 入口：`contract.py` 的 schema／正则／二次校验，以及 `runner.py` 的有限执行流程 | **Python 宿主可隔离改用，自有其他语言则按机制重写**。替换动作表与 Link，补总量／总时长限制；不沿用翻滚、跳跃等不适合目标硬件的动作 | [contract.py](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/contract.py)、[runner.py](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/runner.py)、[links.py](https://github.com/PetoiCamp/opencat-gemma/blob/60a76bc9529f7f61af9d0250d538d2cbde3d4cd5/opencat_gemma/links.py)、[专题与许可](<Petoi%20%E6%8E%A7%E5%88%B6%E4%B8%8E%E6%9C%AC%E5%9C%B0%E6%8C%87%E4%BB%A4%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>) |
| Reachy Mini：应用经 SDK 到 daemon，媒体和动作有各自生命周期 | 主机的动作协调与打断：`Move` 契约、队列、单写运动状态及媒体 playback epoch 机制 | **优先借鉴机制，不为小外设引入整套平台**。采用原 Reachy 硬件时直接利用其 SDK／daemon；抽 `moves.py` 要解除设备与舞蹈库依赖，stop 不默认等于急停 | [moves.py](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/moves.py)、[媒体与回合处理](https://github.com/pollen-robotics/reachy_mini_conversation_app/blob/b731ea1fd6ce53232f1b13609331271358e10bd9/src/reachy_mini_conversation_app/console.py)、[SDK](https://github.com/pollen-robotics/reachy_mini/tree/d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb)、[专题与许可](<Reachy%20Mini%20%E5%B9%B3%E5%8F%B0%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>) |
| Coglet：ESP 负责语音／网络，RP2040 负责机械和视觉仲裁 | 硬件端的单轴所有权、校准／临时动作／表情优先级和双 MCU 分工 | **机制研究，不直接复制非商业代码**。单 MCU 首版不因这个项目而增加第二块 MCU；关节限位必须在每次生成目标后验证 | [固定源码](https://github.com/will-cogley/Coglet/tree/31f3c61b05a88980d0bf56b397ffea473e79c0da)、[架构与限位反例](<%E6%9E%B6%E6%9E%84/Coglet%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) |
| Doly：应用调用模块库，操作 ID 对应异步事件，底层核心是 `.so` | 主机／设备结果接口中的操作 ID、完成／错误／取消及回调清理机制 | **接口机制参考，不把 NC SDK 和闭源核心当通用驱动源码**。使用原机且取得适用授权时，再评估 SDK 集成 | [DriveControl.h](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)、[架构与许可](<%E6%9E%B6%E6%9E%84/Doly%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) |

小智是可选择的语音会话基础设施。自有 Agent 已负责对话与工具时，不需要为了驱动屏幕或舵机再部署一套小智大脑；如需沿用某板的音频驱动或语音链，按文件和协议边界单独评估。参考 [小智语音底座研究](<%E5%B0%8F%E6%99%BA%E8%AF%AD%E9%9F%B3%E5%BA%95%E5%BA%A7%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6.md>)。

# 我们自己写什么

| **位置** | **必须由我们持有的边界** | **可以沿用的材料** |
|---|---|---|
| 主机 Agent 与管理界面 | 自有模型调用、角色、记忆、工具与用户任务；设备只通过有限能力接入 | 延续自有系统，不为硬件迁入上游完整人格／云服务。现有产品具体文件接入点尚未逐仓核对 |
| 主机设备接缝 | 能力表、感知适配、有限 action 校验、动作／回合关联、取消、超时与未知结果处理 | Petoi 合约、Reachy 协调和失效机制按宿主语言抽取或重实现 |
| 主机与设备协议两端 | 帧边界、消息大小、设备身份、重启代次、命令 ID、有效期、取消／查询及错误码；媒体另走流式承载 | 沿用目标板 SDK 的 USB／Serial 传输能力。HachimoDock 相关代码先解决授权，不因 USB 通用而推定其应用协议可直接复制 |
| MCU 本地运行时 | 采集与上报、命令派发、资源仲裁、实际参数限位、动作状态、失联策略与真实结果适配 | 原厂 BSP／音频／屏幕驱动；匹配两轴机构时评估 StackChan 表达与运动模块，保留标定、单位和许可声明 |

这些职责可以先是同一主机进程中的几个模块，无需一开始拆成多个服务。设备端需要自己的确定性运行时，但不承担长期记忆、完整 Agent 规划或管理后台。Agent 与硬件的语义接缝是本方案主要的自研部分，上游已经替我们提供的主要是设备执行模块和可借鉴的机制。

# 最小方案怎样验证

1. **先通模拟闭环**：无模型、无真机，发送感知、有限动作、取消与结果，验证重复、迟到、重启和断链时的状态含义。
2. **再接一台真机**：选择实际首版形态，只接存在的屏幕、声音或机械能力。实测停止、缓冲残留、限位、失联策略和反馈来源，再为每个动作定义成功条件。
3. **最后接自有 Agent**：模型通过同一有限入口调用，管理界面只展示真实状态；模型与人工操作都不能绕过设备能力和本地约束。

第一版的收敛结论是：**先拥有自己的主机设备闭环，再按真实机构复用最小执行模块。** 屏幕／声音外设按哈基米的职责分工设计，两轴机械表达才抽 StackChan；其余项目提供局部机制，不进入首版的全栈部署依赖。

本方案尚未实施产品代码、完整固件构建或真机验收，也未取得受限项目的新商业授权。硬件形态、宿主语言和首版动作集仍需在产品定义中确认；这不妨碍先冻结主机／硬件边界和三条消息方向。逐项目证据见 [源码架构总览](<%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>)，筛选与市场背景见 [开源资产专项](<%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>)。
