> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

研究日期：2026年10月27日。目标是比较“主机运行自有 Agent，硬件作为感知与执行端”的适配程度。HachimoDock 固定 `b56375a6329caf5acb4952b5bb3cd8ddd91fe501`，StackChan 工厂固定 `eff0d6b5109663faec8f1d98848b4b0e5246bbfc`，后者的小智依赖固定 `e77dedb1309153bb63fed285772962c920c97dd4`。本文只比较已读公开实现，不把最新安装包、硬件能力列表或建议方案算成已验证功能。

# 结论：先按硬件职责选，再按授权决定能否采用代码

**以屏幕、按键、语音输入输出组成主机外设时，HachimoDock 的现有分工更贴近目标；需要两轴机械表达时，StackChan 的运动执行层更有直接价值。** “大脑与硬件分开”本身不足以唯一选出 StackChan。此前将其推荐为最小底座，隐含了“小屏＋两轴头部、沿用原厂硬件”的假设，这不是已经确认的产品需求。

技术适配和代码采用分别判断。HachimoDock 的主机／USB／屏幕／音频结构更接近当前架构方向，但自有代码的商业集成和独立产品开发需要另行书面授权，公开应用源码也落后于最新安装包。因此本轮将它提升为**重点架构对照对象、待授权代码候选**，没有把它列为可直接商业移植的底座。

| **当前要验证的产品形态** | **优先研究的实现** | **真正能利用的部分** | **仍要我们补的边界** |
|---|---|---|---|
| 主机 Agent 的屏幕、按键、音频外设 | HachimoDock | PC Bridge、USB 设备身份与能力、输入上报、会话显示、分主题请求／反馈、板端音频及组件运行时 | 自有 Agent 接口；动作／观察契约收敛；适用授权及对应版本源码 |
| 有表情且能转头的机械终端 | StackChan | Avatar／Modifier、Motion／Servo、原厂总线反馈、限位与标定结构 | 触摸／IMU 上报、PC 端连接、去远端引导、动作身份／终态／取消及断链策略 |
| 任意硬件通用的远端 Actor | 两者都不直接满足 | 两套实现分别提供媒体外设和机械执行的具体机制 | 我们自己的能力表、任务状态、资源仲裁、观察时间语义和结果核验 |

这里没有成本、延迟、稳定性或研发节省比例的量化排名。没有同一硬件、同一工作负载的实测，不能从代码规模或功能数量推导性能胜负。

# 运行分工：PC 外设与手机控制机器人是不同起点

HachimoDock 的 PC 客户端组合 React 界面、Tauri／Rust 本地服务和 Node Bridge。ESP32-P4 经 USB 上传按键／音频，主机组织 Agent 输入、对话和内容，再把状态、资源和音频发回设备。板端承担输入解释、显示、组件状态机、音频缓冲和部分本地反应。它已有两条上层路径：外部 Agent 的状态伴随／输入，以及独立于 Agent Bus 的实时人格对话。

StackChan 工厂代码中的 Avatar 对端是 Flutter 手机，设备主动连接手机开的 LAN WebSocket 服务。当前 LAN 地址由远端连接通告。小智 AI 模式是另外一条设备会话路径，通过 Board／Display 把状态翻译成表情和动作。它已经能在设备上持续推进舵机，但没有一套现成 PC Agent 观察／动作闭环。

![主机与硬件分工对照](<%E5%9B%BE/%E4%B8%BB%E6%9C%BA%E7%A1%AC%E4%BB%B6%E5%88%86%E5%B7%A5%E5%AF%B9%E7%85%A7.png>)

```mermaid
flowchart TB
  subgraph H["HachimoDock · 现有主机外设结构"]
    direction TB
    HA["外部 Agent 或主机实时人格对话"]
    HB["PC Tauri / Rust / Node Bridge"]
    HD["P4 USB 协议与本地运行时"]
    HI["按键、音频采集"]
    HO["屏幕、音频播放、组件"]
    HA <--> HB
    HB -->|"请求、会话状态、内容与音频"| HD
    HD -->|"输入、分主题状态、播放诊断"| HB
    HI --> HD
    HD --> HO
  end
  subgraph S["StackChan · Avatar 与 AI 为不同模式"]
    direction TB
    SP["手机 App 的 LAN / 远端控制"]
    SN["设备 Avatar 网络处理"]
    SM["Avatar / Modifier / Motion / Servo"]
    SX["另一路：小智 Application / MCP"]
    SH["两轴舵机与本地传感器"]
    SP -->|"ControlAvatar / ControlMotion"| SN
    SN --> SM
    SM <--> SH
    SN -->|"相机 JPEG 等现有上行"| SP
    SX -->|"表达与头角度工具"| SM
    SM -.->|"MCP 查询返回角度"| SX
  end
```

图按当前实现分组，不代表全部模块都是进程。StackChan 小智模式的角度查询不画成 Avatar 的完成回执。图中的 HachimoDock 分主题状态也不等于已具备通用机械任务终态。

| **分工依据** | **固定源码入口** |
|---|---|
| HachimoDock PC 原生服务、USB 与 Agent 分支 | [Tauri 服务](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs)、[USB 服务](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs)、[Agent Bus](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/agent-session-bus/src/server.js) |
| HachimoDock 设备派发与本地组件 | [protocol.c](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_protocol.c)、[miniapp.c](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_miniapp.c) |
| StackChan 两运行模式及 LAN 入口 | [main.cpp](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/main.cpp#L23-L62)、[LAN 地址接入](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ws_avatar.cpp#L375-L411) |

# Observation：现有上报并非通用环境观察

| **观察内容** | **HachimoDock 当前实现** | **StackChan 当前实现** | **对我们的影响** |
|---|---|---|---|
| 实体输入 | input/event 带设备 ID、seq、事件、action、handledLocally 等；部分事件直接在设备处理，部分送主机 | 头摸、IMU、触屏主要进入本地 HAL／Modifier；已读 Avatar 网络没有相应通用上报 | HachimoDock 已有较明确外设输入边界；StackChan 需要新增 Observer 出口 |
| 外部 Agent 输入 | 部分未本地处理的事件经主机桥转换为继续／指定提示词；语音草稿需要确认后提交 | 工厂 Avatar 路径未提供 PC Agent 会话接口 | HachimoDock 的输入适配可研究，但不是把所有传感器事件都直接交给模型 |
| 语音 | 板端 PCM、主机解析及 ASR／实时会话有具体路径；AEC、双工依赖能力和初始化结果 | 小智 AI 模式的音频路径存在；Avatar 的 StartAudioStream／StopAudioStream 为空分支，Opus 接收解码被注释 | 不能把 StackChan 的音频硬件或消息枚举当作已完成 PC Avatar 双向音频 |
| 视觉 | 本轮所读 P4 主链主要是输入与音频外设，没有取得可作为通用摄像头观察链的实现依据 | Avatar 有 StartCameraStream 与 JPEG 上行，存在大小和采样节流 | 若视觉是首版必要项，两者需要按实际相机硬件和路径另评，不能把屏幕内容下发当视觉采集 |
| 执行器反馈 | 音频／媒体有状态和完成诊断；没有把这些扩大为物理关节测量 | 本地 Servo 有位置／运动／电流／负载用途；小智 MCP 可查询头角度，Avatar 没有相应遥测 | 观察的类型、来源和可靠性应逐能力声明 |

HachimoDock 的 handledLocally 表示输入路由已处理，有时该处理是把 media/event 转发给 PC，不能一概理解为动作已在板上执行完。StackChan 的“本地反应存在”同样不等于这些观察已经上传主机。

依据见 [HachimoDock 输入实现](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_input.c)、[主机输入路由](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs)、[StackChan 触摸实现](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_head_touch.cpp)、[IMU 实现](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_imu.cpp)、[Avatar 音频空分支](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ws_avatar.cpp#L383-L388)、[相机捕获](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ws_avatar.cpp#L418-L457)。

# Action 与结果：四种“结束”必须分别读

HachimoDock 中的 action 至少有三种语境：输入映射的 action、板端组件的 transition／effect、主机对外部 Agent 或家居能力的调用。它们不共享一个通用 action registry。StackChan 同样有 Avatar 控制消息和小智 MCP 工具两套协议，不能互换结果含义。

| **链路／结果** | **实际确认什么** | **未确认什么** |
|---|---|---|
| HachimoDock protocol/ack | 指定请求经过命令处理后返回的 ok／code，语义随 topic 改变 | 对 audio/play_chunk，可能只是接受进缓冲；旧会话被忽略也可正 ACK。不是统一动作完成 |
| HachimoDock media/status | requestId／topic 对应请求的媒体状态、sessionId、positionMs、bufferedMs 等 | 一次 chunk／control 的应答不是整首播放结束，也不是声音实际被听见 |
| HachimoDock audio/diagnostic | playback_started、input_end、completed、flushed 分阶段诊断；已起播流的completed在结束标记及缓冲排空条件下产生，未起播空流有例外 | 不能推广成任意设备任务的完成事件；缓冲／codec 状态也不是声学验收 |
| HachimoDock Agent ready／done | 外部 Agent 注入流与执行回合的状态；ready 可早于真正 inject，done 可由流结束兜底 | 不是 USB 内容已显示、设备已播完或机械动作已成功 |
| StackChan Avatar ControlMotion | 接收 JSON 后设置 Motion／Servo 目标 | 没有逐动作请求 ID、接受／完成终态或按 ID 取消的返回链 |
| StackChan 小智 MCP set_head_angles | JSON-RPC ID 关联工具 result／error；设置目标后立即 true | 不是异步机械到位确认 |
| StackChan 小智 MCP get_head_angles | 按请求读两轴角度并返回；驱动读失败可退回软件插值角 | 不能无条件称真实传感器位置，也不是前一设置动作的完成结果 |

HachimoDock 主机的 media_request 会先注册 waiter，再发送请求，以 requestId＋topic 匹配状态并检查 ok。其音乐播放器还使用 generation 排除旧歌曲状态。音频播放完成走另一条按 sessionId 匹配的诊断路径；只有相应能力分支等待完成，其他路径仍存在按时长估算。因此它的反馈比“单向串口请求”丰富，但不能概括为所有 action 都有可靠完成确认。

StackChan 的舵机反馈在本地用于插值、运动判断与局部堵转保护；数据没有因此自动进入 Avatar 网络结果。需要自行把动作 ID、测量来源和终态加入设备与主机协议。新角度目标会覆盖相应轴的插值目标，但不生成旧动作的取消终态；移除 Modifier 本身不会撤销它已经设置的舵机目标。[目标更新实现](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/motion/servo.cpp#L108-L116)

| **结果依据** | **固定源码入口** |
|---|---|
| HachimoDock 请求等待与匹配 | [transaction_waiters.rs](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial/transaction_waiters.rs)、[usb_serial.rs](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs) |
| HachimoDock 板端音频与媒体结果 | [audio.c](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_audio.c)、[media.c](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_media.c) |
| StackChan MCP 查询与设置 | [hal_mcp.cpp](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_mcp.cpp#L28-L70)、[MCP 结果分派](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/main/mcp_server.cc#L511-L562) |
| StackChan Avatar 设置与本地反馈 | [ControlMotion](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ws_avatar.cpp#L242-L249)、[Servo 位置回读](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_servo.cpp#L90-L111) |

# 取消、去重与失联不能只看有没有序号

| **问题** | **HachimoDock** | **StackChan** |
|---|---|---|
| 序号是否等于动作身份 | Native USB frame sequence 用于封帧／队列信息，没有通用动作去重；音频与音乐各有自己的会话及序号规则 | LAN session／sequence 是传输字段，不是持久动作 ID 或完成关联 |
| 旧会话数据 | 音频 playback session、媒体 session／next_seq、主机 generation 分层处理 | 网络队列 generation 丢弃旧连接消息，已进入 Servo 的目标不受此机制自动取消 |
| 停止范围 | 音频 flush、媒体 stop、Agent AbortController 各有作用域 | Motion.stop、释放扭矩、移除 Modifier、AbortSpeaking 各有作用域 |
| 失联 | 音乐有五秒租期等具体机制，不能扩大为所有设备动作通用租约 | 已读 Avatar LAN 断开处理没有调用 Motion.stop；持续运动与失联需另定义 |
| 超时后的主机判断 | waiter 超时或会话流结束不证明设备未执行 | 网络发送成功或没有回应均不能证明机械完成／未执行 |

对我们的意义是：应分别定义命令去重、任务终态、媒体失效、设备重启代次和失联行为。原项目里的 requestId、sessionId、sequence、generation 各自解决具体问题，不能只选一个字段名就获得跨系统保证。

# 许可与源码完整性单列

本节记录固定文件的授权范围和缺口，不将技术适配度当作获得授权。

| **对象** | **当前文本与版本事实** | **代码采用边界** | **直接依据** |
|---|---|---|---|
| HachimoDock 自有代码 | 自定义非商业源码可见许可；独立产品开发与商业集成等用途需要事先书面许可 | 当前不能登记成已获商业采用授权；获授权还应明确范围、版本、固件、PC、素材和分发条件 | [LICENSE 第2、3、8条](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/LICENSE#L12) |
| HachimoDock 历史版本 | 当前许可明确不撤销历史版本已经授予的许可 | 本轮没有完成历史版本逐文件许可溯源，不能由媒体所写 GPL 推断当前代码或任意历史文件可采用 | [LICENSE 第8条](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/LICENSE#L36) |
| HachimoDock 第三方 | Tauri、Rust／npm 库、驱动、ESP-SR、字体、FFmpeg、米家相关适配等保留各自条款；Agent Bus 包标 UNLICENSED | 自有部分授权不覆盖全部第三方；包标记不是另一份 MIT 授权；原本独立许可的上游材料应回原项目逐文件核查 | [第三方声明](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/THIRD_PARTY_NOTICES.md)、[Agent Bus 包](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/agent-session-bus/package.json#L7) |
| HachimoDock 源码完整性 | PC 源码0.1.101，最新发行0.1.167说明应用源码未同步 | 当前只能解释公开快照，不能声称最新安装包全部功能可从它复现；需匹配源码、锁文件、资源及构建来源 | [package.json](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/package.json#L4)、[0.1.167发行](https://github.com/YizhengWw/HachimoDock/releases/tag/v0.1.167) |
| StackChan 自有固件 | firmware/LICENSE 及已读表达／运动／HAL 文件为 MIT | 可按该许可评估文件级复用，保留声明；依赖、字体、角色、硬件和云服务分别核查 | [固件许可](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/LICENSE)、[文件 SPDX](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/stackchan.h#L1-L5) |
| StackChan 可复现与互通 | 固定小智依赖和 patch 共同构成程序；公开 secret_logic 的认证生成函数为 weak 占位 | 不能声称公开快照原样构建即可与官方 App／服务互通，也不推定量产版本采用该占位。自有本地协议仍需实现身份与握手 | [依赖](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/repos.json)、[公开认证占位](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/utils/secret_logic/secret_logic.cpp#L11-L28) |

# 为什么此前没有选 HachimoDock，现在怎样处理

原五项筛选同时考虑近期变化、付费／交付需求信号和源码可读性。HachimoDock 当时只有初查：没有核实成品销售／交付，最新安装包对应应用源码未同步，自有许可限制独立产品开发，硬件制造资料完整性也未确认。因此暂列观察，没有进入原五项深入组。

**这不是“没有公开代码”的判断，也不能只用“非商业许可”一个理由解释排除。** Coglet、Doly 同样有非商业限制，仍因已核付费众筹和独特机械／传感机制进入研究。它们也没有因此获得商业可用身份。原筛选没有将“主机外设架构适配度”单独列为主轴，当前目标收敛后需要重新排序。

本轮处理为：保留原五项作为既有市场与资产研究组，增加 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>)，配套阅读入口为原网站的“源码与架构”专区及飞书同名目录。架构适配结论不代表产品底座已定案，也不代表代码已集成、硬件已实测或商业授权已取得。

# 下一步判断需要什么证据

| **决定问题** | **需要确认的事实** |
|---|---|
| 屏幕／声音外设还是机械身体 | 首版是否必须有舵机、摄像头和无线；当前只确认主机与硬件分工，形态尚未定案 |
| 是否可采用 HachimoDock 自有代码 | 权利人对独立产品、商业集成、修改／分发、PC和固件范围的书面许可 |
| 是否能复现要采用的版本 | 与选定发行一致的源码、资源、锁文件、构建身份和目标板版本 |
| 两套协议能否满足实际任务 | 在指定硬件测输入、音频、显示／动作完成、取消、重连和重启。ACK、日志和时间估算分别记录 |

独立细节见 [HachimoDock 源码架构](<HachimoDock%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>) 与 [StackChan 源码架构](<StackChan%20%E6%BA%90%E7%A0%81%E6%9E%B6%E6%9E%84.md>)。本轮为静态源码、协议与图示核查，未运行安装包、模型、USB设备、舵机、完整固件构建或性能测试。
