> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

源码与访问日期：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](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/package.json#L4)、[Cargo.toml](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/Cargo.toml#L3) |
| 固件构建字段 | PROJECT_VER 默认0.7.72-p4，允许环境覆盖；协议 schema 宏为7；buildId结合Git身份和dirty标记 | [固件 CMake](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/CMakeLists.txt#L15) |
| 最新发行 | 本轮最新仍为0.1.167，发布于2026-10-24；说明应用源码未同步，固件基于0.7.103-p4-r1 | [发行说明](https://github.com/YizhengWw/HachimoDock/releases/tag/v0.1.167) |
| 研究边界 | 当前结论适用固定公开快照，不能据此声称已重建0.1.167安装包 | [固定提交](https://github.com/YizhengWw/HachimoDock/commit/b56375a6329caf5acb4952b5bb3cd8ddd91fe501) |

源码最近一次提交、文件内版本字段、功能注释和安装包版本不是同一证据。下文按实际分支解释机制，不把文档中的示例版本号当作设备当前握手结果，也没有连接真实设备验证。

# 代码组织与运行位置

| **目录／模块** | **职责** | **执行边界** |
|---|---|---|
| `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也没有一个共享内存状态机。

![HachimoDock 组件与两种会话](<%E5%9B%BE/HachimoDock%20%E7%BB%84%E4%BB%B6%E4%B8%8E%E4%BC%9A%E8%AF%9D.png>)

```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依赖](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/Cargo.toml)、[固件源文件与依赖装配](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/CMakeLists.txt#L6)。

# 观察上报：先有路由和上下文，再进入 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 去重、跨时钟对齐或所有环境状态的持久日志。

依据：[输入白名单](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L2211)、[USB总分派](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L2413)、[设备输入格式](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/protocol.md#L802)。

## 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草稿确认。

![HachimoDock 输入到外部Agent](<%E5%9B%BE/HachimoDock%20%E8%BE%93%E5%85%A5%E4%B8%8EAgent%E6%97%B6%E5%BA%8F.png>)

```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校验](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_audio.rs#L181)、[ASR实际类型](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/pc_audio.rs#L677)、[ASR服务](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/volcengine_asr.rs#L31)、[目标上下文](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L799)、[草稿阶段](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L1162)、[同板确认](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L1360)。

# 外部 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桥接请求](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L2301)、[Node中间路由](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/clawd-backend-service/src/headless-mqtt.js#L1256)、[最新输入队列](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/clawd-backend-service/src/headless-mqtt.js#L1754)、[Bus注入与ready](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/agent-session-bus/src/server.js#L461)、[Bus取消](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/agent-session-bus/src/server.js#L646)、[WorkBuddy限制](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/bridge/packages/agent-session-bus/src/adapters/workbuddy.js#L5)。

# 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也没有逐个立即发错误，等待可由超时结束。不能把固件事务专用的连接代际保护推广成所有请求均有同样保证。超时也不能区分“未执行”与“执行后回执丢失”。

![HachimoDock 请求与播放完成](<%E5%9B%BE/HachimoDock%20%E8%AF%B7%E6%B1%82%E4%B8%8E%E6%92%AD%E6%94%BE%E5%AE%8C%E6%88%90.png>)

```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: 超时表示未及时取得结果，设备是否执行仍需核对
```

依据：[发送与身份校验](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs#L1740)、[设备／媒体请求](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs#L1932)、[waiter匹配](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial/transaction_waiters.rs#L12)、[便捷发送函数](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial.rs#L2929)。

## 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。

依据：[统一ACK实现](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_protocol.c#L354)、[音乐状态处理](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/music_player.rs#L465)、[media事件处理](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/music_player.rs#L1222)。

# 独立实时人格对话与板端音频

`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确认软件播放流程的结束条件，不是麦克风测到扬声器真实出声的证明。

依据：[实时音频路由／诊断](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/realtime_chat.rs#L216)、[主机会话启动](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/realtime_chat.rs#L340)、[Player与epoch](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/realtime_chat.rs#L593)、[条件完成等待](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/realtime_chat.rs#L696)、[人格模型与工具轮次](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/persona_llm.rs#L108)、[板端缓冲排空完成](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_audio.c#L369)。

# 固件调度、USB与本地执行

P4的app_main先建立NVS、传输与状态mutex、SPIFFS和身份状态，以及控制队列／协议worker，再初始化组件、输入／显示／音频，随后启动接收任务，可选AFE最后初始化。音频初始化还会创建独立采集与播放任务。部分显示、触控、麦克风初始化失败会记录错误并保留其余运行能力；不能因此假定全部设备都具备触控或AEC。

普通UART与USB Serial/JTAG各自积累JSON行，native USB的JSON也进入同一有界协议队列，由worker解析和修改状态。Native文件传输走其专用处理并共享状态锁。主循环在锁内推进本地状态、组件、输入、音频提示／控制状态及快照，然后释放锁做重渲染。PCM采集上行和播放排空由独立音频任务执行，避免把这些工作和全部协议响应等待绑定在显示解码上。

![HachimoDock 固件调度与执行](<%E5%9B%BE/HachimoDock%20%E5%9B%BA%E4%BB%B6%E8%B0%83%E5%BA%A6.png>)

```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计数。这些是代码容量，不是已测吞吐或无损观察流保证。[控制队列](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_main.c#L374)、[Native队列](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_usb_native.c#L523)、[输入队列](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_input.c#L758)

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，不能把音乐租期外推成全部失联行为。[媒体租期](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_media.c#L169)、[会话失联清理](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_protocol.c#L1442)、[Native断开](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_usb_native.c#L684)

依据：[app_main与初始化／循环](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_main.c#L591)、[Native USB实现](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_usb_native.c)、[组件解释器](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_miniapp.c)、[音乐接口](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_media.c)、[主机native格式与身份检查](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/usb_serial/native_usb_protocol.rs#L10)。

# 状态回传、持久化与资源边界

外部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的完整性规则。

依据：[状态转发循环](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L9489)、[状态与文字下发](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/pc/src-tauri/src/lib.rs#L9765)、[输入配置与NVS](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_input.c)、[组件提交事务](https://github.com/YizhengWw/HachimoDock/blob/b56375a6329caf5acb4952b5bb3cd8ddd91fe501/firmware/main/pet_p4_miniapp.c#L3719)。

# 采用边界与阅读深度

技术上，本项目可为主机Agent外设提供设备能力、输入上下文、USB请求关联、媒体仲裁和本地组件运行的具体参考。采用时仍需区分自有Agent适配、音视频通路和设备action反馈，不能直接将外部coding-agent队列当作通用硬件任务队列。

授权与版本缺口单列于 [HachimoDock 与 StackChan 架构对比](<HachimoDock%20%E4%B8%8E%20StackChan%20%E6%9E%B6%E6%9E%84%E5%AF%B9%E6%AF%94.md>)。当前根许可要求商业集成和独立产品开发另行书面授权；第三方依赖保留各自条款。本文不宣称已获授权，也没有将代码合入公司产品。

| **范围** | **实际阅读深度** |
|---|---|
| 主机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图源与正文同目录保存。早期产品与市场背景保留在 [桌面入口初查](<../HachimoDock%20%E6%A1%8C%E9%9D%A2%E5%85%A5%E5%8F%A3%20%E6%BA%90%E7%A0%81%E5%88%9D%E6%9F%A5.md>)。
