源码与访问日期:2026年10月27日。固定 YizhengWw/HachimoDock@b56375a6329caf5acb4952b5bb3cd8ddd91fe501,提交时间2026-10-26T11:14:19Z。本轮重新核对默认分支仍为该提交。研究聚焦主机/硬件分工、观察输入、设备命令、反馈、取消与失联,不实现或移植产品代码。
架构结论与版本边界
HachimoDock 公开实现是一套电脑本地服务组织交互、USB 连接 P4 外设、板端运行输入/显示/音频/组件逻辑的系统。它包含可读的主机编排,不能只描述为 Agent 状态显示屏;板端也有自己的状态机和行为,不能描述为没有逻辑的像素终端。
主机存在两条需要分开解释的路径。第一条读取外部 Agent 的状态、接收设备输入,向可见输入框或 Agent Bus 送入提示词。第二条由主机自己的 realtime_chat 编排语音、人格模型和 TTS,不经过外部 Agent Bus 完成每一轮对话。两者共享设备与部分媒体能力,却有不同的会话、取消和结果语义。
“action”在项目中并不是一个统一抽象:输入映射 action、板端组件 transition/effect、音频/资源命令、主机 Agent 注入分别使用自己的协议与状态。系统已有真实的事务回执和部分播放完成反馈,但没有一套覆盖全部能力的通用远端 Actor 生命周期。
| 版本材料 | 固定事实 | 依据 |
|---|---|---|
| 主机源码 | pc/package.json 与 Cargo.toml 均为0.1.101 | package.json、Cargo.toml |
| 固件构建字段 | PROJECT_VER 默认0.7.72-p4,允许环境覆盖;协议 schema 宏为7;buildId结合Git身份和dirty标记 | 固件 CMake |
| 最新发行 | 本轮最新仍为0.1.167,发布于2026-10-24;说明应用源码未同步,固件基于0.7.103-p4-r1 | 发行说明 |
| 研究边界 | 当前结论适用固定公开快照,不能据此声称已重建0.1.167安装包 | 固定提交 |
源码最近一次提交、文件内版本字段、功能注释和安装包版本不是同一证据。下文按实际分支解释机制,不把文档中的示例版本号当作设备当前握手结果,也没有连接真实设备验证。
代码组织与运行位置
| 目录/模块 | 职责 | 执行边界 |
|---|---|---|
pc/src/ |
React 界面、Agent Bus 客户端、配置与组件管理 | 桌面 WebView;不是设备端界面代码 |
pc/src-tauri/src/lib.rs |
主机服务装配、USB事件总分派、PTT上下文、输入确认、状态转发及命令入口 | Tauri/Rust 本地进程内;本轮定点深入,未逐行审计整份大文件 |
usb_serial.rs 与 usb_serial/ |
连接、reader/writer、设备身份、发送节流、响应等待、资源/固件事务 | 主机连接对象和辅助线程;子文件划分不表示独立服务 |
usb_audio.rs、volcengine_asr.rs |
PTT音频完整性、云ASR生命周期 | PTT链;不自动覆盖实时双工链 |
realtime_chat.rs、persona_llm.rs |
独立实时会话、VAD/ASR、主机人设与模型、TTS、Player | 主机编排与外部模型服务,非P4大模型推理 |
bridge/packages/clawd-backend-service/ |
外部Agent监视/发布、硬件输入桥、中间HTTP路由与待投递输入 | Node Bridge;代码文件名含mqtt不表示本轮主链都走MQTT |
bridge/packages/agent-session-bus/ |
适配会话发现、创建/恢复、提示词注入、SSE事件与取消 | Node运行时,可启动Agent CLI/helper子进程 |
firmware/main/pet_p4_main.c |
初始化、传输任务、协议worker、状态更新、输入、音频推进和渲染快照 | ESP-IDF/FreeRTOS 的P4固件 |
pet_p4_protocol.c、pet_p4_usb_native.c |
topic派发、响应、USB封帧和文件事务入口 | 普通JSON请求进入协议队列;native文件帧另有序列化路径 |
pet_p4_input.c、pet_p4_miniapp.c、pet_p4_audio.c |
实体输入、本地组件解释、音频采集/缓冲/播放 | 板端本地执行,不要求每帧由主机重发 |
固件构建是ESP-IDF组件组合,PC构建是React/Vite+Tauri/Rust,Node Bridge作为额外运行时。硬件板型v1/v3的配置与依赖锁分开,不能仅凭“都是P4”混用固件。主机、板端和外部Agent也没有一个共享内存状态机。

查看 Mermaid 图源
flowchart TB
subgraph PC["电脑主机"]
UI["React / Tauri 界面"]
ROUTE["Rust 主机服务\nUSB分派、PTT确认、状态转发"]
USB["UsbSerialManager\n连接、reader、writer、waiter"]
BRIDGE["Node Bridge\n硬件输入与Agent状态"]
BUS["AgentSessionBus / adapters"]
RT["realtime_chat / Player\n独立实时人格会话"]
UI <--> ROUTE
ROUTE <--> USB
ROUTE <--> BRIDGE
BRIDGE <--> BUS
ROUTE <--> RT
RT --> USB
end
EXT["外部桌面 / CLI Agent"] <--> BUS
MODELS["配置的 ASR / LLM / TTS 服务"] <--> RT
ROUTE -->|"PTT ASR"| MODELS
subgraph P4["ESP32-P4 固件"]
TRANSPORT["串口JSON / native USB"]
PROTO["协议worker与状态"]
INPUT["输入映射与本地组件"]
AUDIO["采集、AEC、播放缓冲"]
DISPLAY["状态、素材与屏幕渲染"]
TRANSPORT <--> PROTO
INPUT --> PROTO
PROTO <--> AUDIO
PROTO --> DISPLAY
end
USB <-->|"USB请求、事件、音频与结果"| TRANSPORT
图中的主机服务是职责分组。Rust模块不分别变成进程,Node侧与具体Agent子进程另有生命周期。音频模型服务的部署可由配置改变,USB连接本身不能证明全系统离线。
构建依据:PC依赖、固件源文件与依赖装配。
观察上报:先有路由和上下文,再进入 Agent
实体输入的实际范围
设备的input/event包含boardDeviceId、seq、control/gesture/event、context、action、handledLocally等。板端先决定页面导航、组件游戏或工具是否已经处理。主机的 extract_usb_agent_input 仅将未本地处理的agent_enter变成继续提示,将agent_prompt的非空value变成输入。它没有把每个按键、所有传感数据或任意action对象直接送入模型。
handle_incoming_usb_message 先处理配置回执、媒体事件与活动实时会话,再处理PTT音频和普通输入。实时会话可占有同板输入,防止同一次按键又进入外部Agent。普通事件通过Tauri事件出口供应用消费,但事件发布与实际Agent提交是不同动作。
设备input/event中的seq用于辨识事件顺序;所读主机路由不能因此视为已经实现了通用 observation 去重、跨时钟对齐或所有环境状态的持久日志。
PTT音频:传输完整性、文字草稿和确认分开
PTT的 UsbAudioRelay 接收pcm_s16le、16kHz、单声道、16bit音频,按session/board关联,检查连续seq、base64、声明长度和FNV1a64校验,限制整段PCM长度。end再核chunks、bytes和累计校验。它的ok确认音频传输完整,不代表识别正确或已提交Agent。
ASR实际调用经pc_audio重导出的火山流式识别器,默认endpoint在openspeech.bytedance.com。代码里的“local”名称或电脑运行位置不能作为本地模型推理的证据。主机保存录音开始时的目标Agent/会话快照及revision,避免识别结束时随意切到另一个目标。
final识别结果进入草稿。确认要求同板、draft_ready、未取消且尚未提交,再按目标选择路径。Codex、Claude、WorkBuddy可以走可见输入框;MiMoCode的设备语音有macOS专用目标及非macOS限制;其他路由才进入Bridge。普通agent_enter/agent_prompt按键并不都经过PTT草稿确认。

查看 Mermaid 图源
sequenceDiagram
participant D as P4输入与音频
participant U as 主机USB路由
participant V as PTT上下文与ASR
participant B as Node Bridge
participant S as AgentSessionBus
participant A as 外部Agent
D-->>U: audio/begin、chunk、end
U->>V: 完整性校验、固定目标、送ASR
V->>V: final结果成为待确认草稿
D-->>U: 同板 page_enter Confirm
U->>V: 领取一次提交
alt 非可见输入框路径
V->>B: voice_input / mock-button-inject
B->>B: 忙时保留每Agent最新一条
B->>S: POST agent/inject
S-->>B: ready,已解析目标与runId
S->>A: adapter.inject
A-->>S: token / tool / terminal事件
S-->>B: done 或 error
else 可见输入框路径
V->>A: 经主机composer写入与确认提交
end
Note over D,A: 音频收齐、提示词已提交、Agent回合结束分别记录
依据:PTT校验、ASR实际类型、ASR服务、目标上下文、草稿阶段、同板确认。
外部 Agent:桥接、排队与完成的实际含义
主机先调用 forward_usb_agent_input_to_bridge,POST本机23333端口的 /mock-button-inject。Node Bridge解析请求,按忙碌状态决定注入或保留最新输入,再POST AgentSessionBus的 /agent/inject,消费SSE。它不是设备直接访问Agent,也不是Rust直接跳过中间层调用Bus。
LatestHardwareInputQueue按agentId保存最新一条待投递输入,后来者可替换前者,默认500ms检查、五分钟过期。queued/replaced可向Rust返回ok与pending,但已读装配中的后续投递/过期回调主要写日志,不能视为原始调用方一定能取得严格对应的后续终态。
Bus的ready在真正adapter.inject之前发出,表示目标已解析并登记runId。done可由适配器正常终态产生,也可能在流结束但未显式terminal时以stream_ended补出。cancel调用AbortController后即返回,不等待所有外部副作用撤销。因此“Agent ready”“Agent done”“取消请求成功”都不能当成设备动作完成或用户目标已经达成。
| 适配器 | 已读到的输入实现 | 边界 |
|---|---|---|
| Codex | exec/resume JSON,或配置分支启动app-server经stdio RPC恢复线程与开始回合 | 只描述此适配器的实际调用;AbortSignal可终止子进程,不是硬件动作取消 |
| Claude Code | CLI非交互stream-json,按需resume | 输出流和进程生命周期,不是对话UI的同一入口 |
| OpenClaw | Node helper访问安装的运行时模块 | 另有helper边界,不使用Codex协议 |
| MiMoCode | 可枚举会话,inject明确不支持 | macOS终端输入属于另一主机路径 |
| WorkBuddy | 可跟随状态;后台inject明确不支持 | 可用性ready不意味着支持后台写入 |
依据:Rust桥接请求、Node中间路由、最新输入队列、Bus注入与ready、Bus取消、WorkBuddy限制。
PC下发命令与设备回执
写入、请求关联与执行结果是三层
send_state、send_speech、send_command包装state/source、speech/text、control/command后走send_inner,成功只说明主机写路径完成;这些便捷函数没有自动登记一般protocol/ack等待。主机按连接、可选板ID、某些事务专用connection_id检查目标,再序列化和节流写入。
reader解析每行后,先匹配素材/widget/固件ACK和设备响应waiter,再交应用on_message。所以media/status不是只有UI展示作用,它会先解除请求等待,再更新播放器。不同事务的键不同,没有一个覆盖全部消息的统一任务表。
| 反馈机制 | 关联与校验 | 它确认什么 |
|---|---|---|
| DeviceResponseWaiter | requestId+response topic,匹配后移除sender;调用处检查ok和板ID | 对应请求收到的响应,不是幂等执行证明 |
| media_request | 先注册UUID和media/status,再发送;三秒等待并要求ok | 指定媒体请求的状态快照 |
| 音频完成 | realtime_chat保存诊断sessionId,Player按完整turn_id匹配 | 相应能力分支中的设备播放完成报告 |
| 资源/widget ACK | transferId、phase、path、index等 | 指定传输阶段和分块状态 |
| 固件ACK | transferId、phase及预期nextSequence/receivedBytes等 | 特定镜像块与事务阶段,不是固件所有功能已验收 |
存量DeviceResponseWaiter没有connection_id字段,已读disconnect也没有逐个立即发错误,等待可由超时结束。不能把固件事务专用的连接代际保护推广成所有请求均有同样保证。超时也不能区分“未执行”与“执行后回执丢失”。

查看 Mermaid 图源
sequenceDiagram
participant C as 主机调用方
participant U as UsbSerialManager
participant W as 请求waiter
participant D as P4协议与媒体
participant R as USB reader
C->>U: media_request(board, topic, payload)
U->>W: 注册 requestId + media/status
U->>D: 请求,附相同requestId
D-->>R: media/status(requestId, ok, state)
R->>W: 匹配并移除等待项
W-->>U: 返回payload
U-->>C: 校验ok后返回状态
Note over C,D: 媒体状态快照不是整段播放终态
opt 实时音频的独立完成等待分支
C->>D: audio/play_end(sessionId)
D->>D: 结束标记已到且缓冲排空
D-->>R: audio/diagnostic playback_completed
R->>C: 保存匹配会话的完成ID
C->>C: Player.End核对完整turn_id
end
Note over U,D: 超时表示未及时取得结果,设备是否执行仍需核对
依据:发送与身份校验、设备/媒体请求、waiter匹配、便捷发送函数。
protocol/ack没有统一的“动作完成”含义
固件 send_protocol_ack 复制请求的requestId,附requestTopic、ok、code和error。带requestId的许多普通命令在派发后得到正ACK;错误分支和专用响应路径分别处理。ACK语义取决于handler:audio/play_chunk通常是加入缓冲,旧session的chunk被忽略也可返回成功,不代表声音已播放。
media/status另有sessionId、state、positionMs、bufferedMs等。主机音乐服务在update_ack中再检查generation,防旧歌曲状态覆盖新流。media/event则表示用户对播放器的操作,可能需要主机继续发请求,它不等同media/status。
独立实时人格对话与板端音频
realtime_chat.start 检查主机ASR/LLM/TTS配置、指定板连接及活动会话,创建输入通道和Session。设备音频可先被这条链截获,绕过PTT的UsbAudioRelay,因此PTT的连续seq/FNV/整段限制不能自动算成实时链同样具备。
实时链按设备audioAec/audioVad/audioFullDuplex能力选择双工;双工输入要求aec=true及vadSpeech字段,否则停止相应会话。主机维护人设与历史,调用persona_llm,再由TTS和Player向audio/play_begin/chunk/end发送PCM。默认兼容chat/completions基址在源码中为DeepSeek,可配置,不能说大模型在P4上运行或整个系统默认离线。
Player维护epoch,Flush提升代际并发送play_flush,迟到队列项和旧分块应在检查点失效。设备侧以session隔离播放,已起播流在结束标记已到且缓冲排空后产生playback_completed;从未起播且结束时已空的分支只置inactive并发status,没有同一条completed。主机仅在conversationSubtitles能力且活动会话匹配的await_device分支继续等完整turn_id,最长再等五秒。其他路径仍按已发送PCM时长估算。不能声称所有播放都等待了设备确认。
板端还发playback_started、playback_input_end、playback_flushed等诊断。多数诊断进入日志,并不解除某个通用任务等待。completed确认软件播放流程的结束条件,不是麦克风测到扬声器真实出声的证明。
依据:实时音频路由/诊断、主机会话启动、Player与epoch、条件完成等待、人格模型与工具轮次、板端缓冲排空完成。
固件调度、USB与本地执行
P4的app_main先建立NVS、传输与状态mutex、SPIFFS和身份状态,以及控制队列/协议worker,再初始化组件、输入/显示/音频,随后启动接收任务,可选AFE最后初始化。音频初始化还会创建独立采集与播放任务。部分显示、触控、麦克风初始化失败会记录错误并保留其余运行能力;不能因此假定全部设备都具备触控或AEC。
普通UART与USB Serial/JTAG各自积累JSON行,native USB的JSON也进入同一有界协议队列,由worker解析和修改状态。Native文件传输走其专用处理并共享状态锁。主循环在锁内推进本地状态、组件、输入、音频提示/控制状态及快照,然后释放锁做重渲染。PCM采集上行和播放排空由独立音频任务执行,避免把这些工作和全部协议响应等待绑定在显示解码上。

查看 Mermaid 图源
flowchart TB
UART["UART JSON接收任务"] --> Q["有界协议请求队列"]
USJ["USB Serial/JTAG接收任务"] --> Q
NATIVE["Native USB封帧"] -->|"JSON"| Q
Q --> WORKER["protocol_worker_task\n解析、派发、按入口回复"]
NATIVE -->|"文件帧"| FILE["专用文件事务处理"]
WORKER --> STATE["共享运行状态 / state mutex"]
FILE --> STATE
MAIN["主循环\n组件、输入、提示状态推进"] <--> STATE
MAIN --> VIEW["锁内取得稳定渲染快照"]
VIEW --> RENDER["锁外解码与屏幕渲染"]
MAIN --> OBS["输入事件上报"]
CAPTURE["独立音频采集任务"] --> PCM["audio/begin / chunk / end上报"]
PLAY["独立播放任务与PCM ring"] --> DIAG["播放诊断与状态上报"]
WORKER --> RESP["ACK / 分主题状态 / 事务结果"]
普通控制队列深度为24,Native帧队列深度为4,输入事件队列深度为32。队列满可报忙或丢弃,并没有对所有丢弃都返回关联原requestId的结果;输入事件还携带dropped计数。这些是代码容量,不是已测吞吐或无损观察流保证。控制队列、Native队列、输入队列
Native USB用P4BU、16字节头、kind/seq/payload length承载JSON或文件帧,并有nonce+boardDeviceId的身份选择。这个nonce用于防混淆,不等于完整加密身份认证。native frame sequence可进入队列/日志,不能当作固件已经对任意action去重。PC侧该快速路径主要用于素材传输,不能只因固件支持native就说所有按键和音频都走bulk。
设备的本地组件不是任意脚本执行。miniapp解释有界变量、状态、transition/effect、tick及受控场景。导航、游戏等可以本地推进,部分media操作转换为media/event交PC。handledLocally=true可能表示这次输入路由已处理并转发,并不总是本地任务已完成。
语音播放与音乐也不是完全同一链:音乐分块有session和next_seq检查,重复seq可拒绝;普通audio/play_chunk没有按chunk seq去重。旧session的chunk/end会被过滤,但新的play_begin本身会替换当前session,未见比较单调代际或保存已取消ID集合,不能扩成任意迟到消息均不会干扰新轮次。
音乐有五秒应用层租期,由相关成功媒体请求续租,library刷新不续租;UI conversation活跃且host_last_seen超六秒时另有清理。Native unmount回调只改变mounted,没有通用取消所有任务。普通非conversation音频在未end而缺数据时可持续underrun/silence,不能把音乐租期外推成全部失联行为。媒体租期、会话失联清理、Native断开
依据:app_main与初始化/循环、Native USB实现、组件解释器、音乐接口、主机native格式与身份检查。
状态回传、持久化与资源边界
外部Agent状态由Bridge监视器/Hook/日志和适配器流生成,写入主机状态文件。Tauri的start_usb_state_forwarder约每800ms检查、筛选和去重,向板端发state/source、state/active、speech/text、runtime/stats。这里的working/speaking/waiting_user是主机对Agent活动的解释,不是设备控制器的动作状态枚举,speech/text也不是TTS已播完。
PC连接和运行中waiter、实时会话、Player epoch等主要是RAM状态,Bridge也使用状态文件。板端输入映射可保存NVS,组件/素材涉及SPIFFS与目录事务。它们不是统一持久任务日志,重启后不能直接承诺恢复每个未完成action或恰好执行一次。
素材/组件与固件传输有专门事务键、分块ACK和取消机制,但这些保证限定于相应协议。普通状态设置不能继承固件升级的连接代际校验,普通播放也不能继承资源commit的完整性规则。
依据:状态转发循环、状态与文字下发、输入配置与NVS、组件提交事务。
采用边界与阅读深度
技术上,本项目可为主机Agent外设提供设备能力、输入上下文、USB请求关联、媒体仲裁和本地组件运行的具体参考。采用时仍需区分自有Agent适配、音视频通路和设备action反馈,不能直接将外部coding-agent队列当作通用硬件任务队列。
授权与版本缺口单列于 HachimoDock 与 StackChan 架构对比。当前根许可要求商业集成和独立产品开发另行书面授权;第三方依赖保留各自条款。本文不宣称已获授权,也没有将代码合入公司产品。
| 范围 | 实际阅读深度 |
|---|---|
| 主机USB边界 | 深入connect/reader/send、device/media request、waiter、连接句柄、native格式及媒体仲裁;大文件按调用链定点阅读 |
| 主机观察与Agent | 深入lib.rs的输入白名单、PTT上下文、final/Confirm、Bridge请求与状态转发;Node路由、latest queue、Bus注入/取消及适配器能力分支 |
| 主机实时对话 | 深入realtime_chat的start/route/Player/epoch/完成等待,persona_llm入口,实际ASR类型与服务endpoint;未审全部工具与云服务内部 |
| 固件 | 深入app_main任务/状态锁/快照、协议ACK/音频/媒体派发、native封帧、输入路由、组件作用及播放终态;未全栈审计ESP-IDF/TinyUSB/DSP/显示解码库 |
| 文档/构建/许可 | 固定README、CMake、Cargo/package、协议文档与组件契约对照;实现与声明分开记录 |
| 未执行 | 未安装客户端、构建固件、连接USB、刷机、录音、调用模型、操纵外部Agent或跑真机/性能测试 |
本轮源码快照与核查记录保存在 研究证据目录(研究底稿,未随本专区发布)。主机25份源码按固定tree的Git blob校验;固件22份缓存按列明行段阅读,118处引用做路径和行号检查。数字是证据清单规模,不代表全仓逐行审计。完整树未截断。更细行段见 主机核查(研究底稿,未随本专区发布) 与 固件核查(研究底稿,未随本专区发布)。图示依据上述路径重建,不是运行日志。PNG与SVG用于直接阅读,Mermaid图源与正文同目录保存。早期产品与市场背景保留在 桌面入口初查。