DreamSoul研究
源码与架构 /

StackChan 源码架构

固定源码 · 研究快照 2026-10-27Markdown 下载 ↓飞书阅读 ↗
本页为正式研究文档的网页阅读版。固定 GitHub 证据保留;本机研究底稿未发布,相关链接已改为文字说明。原文中的历史发布状态对应研究当时。

一、对象、版本与阅读边界

本文解释 M5Stack 工厂 StackChan 的设备固件、手机 App、Go 服务如何组成产品,面向需要沿源码定位职责、状态和调用路径的读者。分析对象是实际实现,不包括其他项目的组合设计或复用方案。各图中的“模式”“分组”是本报告的分析表达,进程边界与任务名另行明确。

工厂仓库固定为 eff0d6b5109663faec8f1d98848b4b0e5246bbfc,提交时间 2026-10-22 01:40:01 UTC;其小智依赖固定 v2.2.4、提交 e77dedb1309153bb63fed285772962c920c97dd4,提交时间 2026-03-09 11:33:01 UTC。访问和复读日期为2026年10月27日。本报告没有用滚动 main 覆盖这两个快照,也没有重新确认之后的 main 是否更新。仓库声明的固件工程版本是 1.6.0,App 清单为 1.2.8+32;这些是源码构建元数据,不代表已验证商店安装包或量产设备与它们完全对应。固件版本、App 清单

本轮新增的是机制与调用关系复核,没有执行 ESP-IDF、Flutter、Go 的完整构建,没有刷机或连接真实设备。原有局部静态验证不用于证明本文图中的所有运行路径都已实测。全文以工厂代码为主,引用小智文件时明确来自固定上游,必须连同工厂 patch 理解。

二、仓库如何形成三个运行实体

firmware/、app/、server/ 分别形成 ESP32-S3 固件、手机进程和 Go 服务进程。它们共享设备 MAC 与若干消息类型,却不共享一个内存状态机。设备语音会话还会直接连接外部小智服务,手机的 XiaoZhiUtil 也直连小智管理 API。因此,Go 服务承担账号衔接、绑定、业务数据和 Avatar 远端转发,不是所有 AI 音频必经的统一网关。服务路由、手机小智客户端、设备协议选择

查看 Mermaid 图源
flowchart TB
  subgraph PHONE["手机 App 进程"]
    UI["Flutter 页面"]
    AS["AppState / GetX"]
    BLE["BlueUtil + NativeBluetoothBridge"]
    DT["DeviceMessageTransport"]
    LAN["LocalAreaNetworkService<br/>WebSocket 服务端"]
    RW["WebSocketUtil / Http"]
    XU["XiaoZhiUtil"]
    UI --> AS
    AS --> BLE
    AS --> DT
    DT --> LAN
    DT --> RW
    AS --> XU
  end
  subgraph MCU["ESP32-S3 固件 / FreeRTOS"]
    subgraph ENTRY["运行模式分组:顺序交接"]
      MC["Mooncake / AppAvatar / AppSetup"]
      XA["小智 Application"]
      MC -. "卸载后交接" .-> XA
    end
    H["Hal / Board / Display"]
    EX["StackChan / Avatar / Motion"]
    NET["WebSocketAvatar / AvatarClient"]
    MC --> NET
    MC --> H
    XA --> H
    H --> EX
  end
  subgraph GO["Go 服务进程"]
    HTTP["GoFrame 路由 / middleware / controller"]
    SVC["service / xiaozhi 适配"]
    WS["WS 会话池 / writer goroutine"]
    HTTP --> SVC
  end
  DB[("业务数据库")]
  ACCOUNT["外部 M5Stack 账号 / 设备校验"]
  XCLOUD["外部小智管理 API / 对话服务 / OTA"]
  BLE <-->|"GATT"| H
  NET -->|"设备发起 LAN WS"| LAN
  RW <-->|"远端 WS"| WS
  RW -->|"HTTP"| HTTP
  NET <-->|"远端 WS"| WS
  SVC --> DB
  SVC --> ACCOUNT
  SVC --> XCLOUD
  XU --> XCLOUD
  XA <-->|"协议会话 / 音频"| XCLOUD
StackChan 组件边界
StackChan 组件边界 · 点击查看原图

图中的工厂固件内部再分为两种运行模式。Mooncake 管理启动器、AVATAR、设置、舞蹈等应用。AI.AGENT 应用只提出切换请求,真正的小智 Application 运行于 Mooncake 销毁之后。因而图中两条网络线分别属于不同模式:WebSocketAvatar 对接手机及 Go 的 Avatar 连接;Application::protocol_ 对接小智对话协议。不能因为两边都用 WebSocket,就把其报文格式、认证和生命周期视为同一个连接。AI 应用切换入口、设备主入口、Avatar 服务连接

(一)目录与构建装配

目录或文件 在构建与运行中的职责
firmware/main/apps/ Mooncake 应用与页面生命周期,调用 HAL 信号及机器人对象
firmware/main/hal/ 板级初始化、BLE、网络、账号、OTA、舵机与 XiaoZhi 桥接
firmware/main/stackchan/ 表情元素、修饰器、动作、JSON 适配和对象池
firmware/xiaozhi-esp32/ 构建时拉取的固定依赖,其应用、音频、协议、OTA 等源码被加入工厂组件
app/lib/ Flutter 页面、GetX AppState、BLE 原生桥、HTTP、远端和 LAN 传输
server/api/ 与 server/internal/ 请求契约、GoFrame controller、业务 service、DAO、WebSocket 会话与小智适配

这不是三个随意并列的代码目录:固件主 CMake 显式把小智 application.cc、audio_service.cc、协议、OTA、状态机等文件加入 SOURCES,同时不编译小智 main.cc,用工厂 main.cpp 接管入口。工厂目录则用递归匹配收集 apps、hal、stackchan。README 指定 ESP-IDF 5.5.4,依赖脚本与构建命令只作为构建说明读取,没有执行。源码装配、构建说明

repos.json 固定 Mooncake v2.3.3、mooncake_log v1.5.0、smooth_ui_toolkit v2.12.0、ArduinoJson v7.4.2,以及 ESP-NOW 的提交和小智 v2.2.4。版本名是依赖声明,不等于所有传递依赖均经过本报告审计。工厂 patch 改写激活、Wi-Fi 回退、部分资源与 I2C 接口,所以“直接编译未打补丁的小智 v2.2.4”并不等价于工厂固件。固定依赖

(二)小智 patch 改变了什么

激活阶段原有的人工验证码播放被移除。OTA 响应出现人工激活 code 时,patch 把它解释为 RequiresAppBinding(),随后调用 Hal::requestAppSetup()。自动 challenge 仍保留,但超过三轮后同样回到 App 配置。Wi-Fi 基类的配网入口改为可覆写,工厂 M5StackCoreS3Board 覆写后走 BLE App 配置重启,而不是创建上游配置 AP。会话连接前还显式切换到 PERFORMANCE,连接失败再回 LOW_POWER。应用和会话补丁、OTA 与 Wi-Fi 补丁、工厂配网覆写

资源 patch 注释掉 EmoteStrategy 相关实现,板级 I2C 增加返回错误码的 TryReadRegs。这说明工厂不是只换一张脸:入口、屏幕、配网和硬件访问均有产品化分叉。本报告沿改动解释机制,但未做完整 patch 应用及编译验证。资源与 I2C 差异

三、设备启动、控制权与生命周期

app_main 先创建 HAL 单例。HAL 初始化 NVS,遇无空页或版本不兼容时擦除后重试,然后依次建立小智 Board/MCP、触摸、扩展 IO、RTC、IMU、舵机和 LVGL 适配。板级类 M5StackCoreS3Board : WifiBoard 的构造函数负责 I2C、电源芯片、触控、SPI/LCD、相机及触摸定时器;HAL 不是另一套独立的显示硬件实现,而是大量通过 hal_bridge 接到这块 Board。HAL 初始化、Board 构造及设备接口

是否进入 Mooncake 由启动配置和 warm reboot 目标共同决定。正常路径安装八个应用,主循环反复调用 GetMooncake().update()。选择 AI.AGENT 后只置启动请求,主循环检测到后退出,卸载所有应用并销毁 Mooncake,最后 Hal::startXiaozhi() 创建机器人更新任务并调用 Application::Initialize/Run。启动即 AI 的配置可跳过应用安装,但 Board、HAL 和舵机仍先初始化。主循环与销毁顺序、AI 接管、桥接入口

Application::Initialize 建立显示 UI、启动 AudioService、注册音频和网络回调;网络完成后启动独立 activation 任务,依次检查资源、固件、激活并建立协议,最后通过事件位通知主任务。这里的“激活完成”会使状态进入 Idle,释放临时 Ota 对象,并降低网络功耗。初始化音频与建立云会话不是同一个时刻。应用初始化、网络与激活任务

返回配置采用重启边界。requestAppSetup 在 NVS 保存 warm_boot 标志及设置页索引后 esp_restart,并在必要时确认当前 OTA 分区,避免刻意去配网导致有效固件回滚。Avatar 页面关闭也清理 UI/信号后请求 warm reboot,而非在当前 AI/Avatar 栈内恢复整个启动器。这个设计把模式资源释放交给重启,但使模式切换不是普通页面导航。配置重启、Avatar 关闭

四、核心对象如何承载状态与表达

查看 Mermaid 图源
classDiagram
  class Application {
    Initialize()
    Run()
    Schedule(callback)
    SetDeviceState(state)
  }
  class DeviceStateMachine {
    TransitionTo(state)
  }
  class AudioService
  class Protocol
  class Display
  class LvglDisplay
  class StackChanAvatarDisplay {
    SetEmotion(emotion)
    SetStatus(status)
  }
  class Modifiable
  class StackChan {
    addModifier(modifier)
    update()
    updateMotionFromJson(json)
  }
  class Avatar {
    setEmotion(emotion)
    update()
  }
  class DefaultAvatar
  class Motion {
    moveWithSpeed(yaw,pitch,speed)
    stop()
    isMoving()
  }
  class Servo {
    update()
    moveWithSpeed(angle,speed)
  }
  class ScsServo {
    set_angle_impl(angle)
    is_moving_impl()
  }
  class Modifier {
    _update(target)
  }
  class SpeakingModifier
  Application *-- DeviceStateMachine : state_machine_
  Application *-- AudioService : audio_service_
  Application *-- Protocol : protocol_ unique_ptr
  Application ..> Display : Board.GetDisplay
  Display <|-- LvglDisplay
  LvglDisplay <|-- StackChanAvatarDisplay
  StackChanAvatarDisplay ..> StackChan : GetStackChan
  Modifiable <|-- StackChan
  StackChan *-- Avatar : unique_ptr
  StackChan *-- Motion : unique_ptr
  StackChan *-- Modifier : ObjectPool
  Avatar <|-- DefaultAvatar
  Motion *-- "2" Servo : yaw / pitch
  Servo <|-- ScsServo
  Modifier <|-- SpeakingModifier
  Modifier ..> Modifiable : update target
StackChan 核心类
StackChan 核心类 · 点击查看原图

类图只画主链。实线空三角表示源码继承,菱形表示成员持有,虚线表示调用依赖。ScsServo 定义在 hal_servo.cpp 内,属于硬件实现,不是 Motion 的另一层管理器。Application 通过 Board 的 Display 接口访问 StackChanAvatarDisplay;图中没有把 HAL、Board 和机器人模型错误画成互相继承。Application 成员、Display 继承、LvglDisplay 基类、机器人组合关系

(一)会话状态与界面状态分开

Application 持有 DeviceStateMachine、AudioService、Protocol 和暂存的 Ota。状态机把当前值放在 atomic 成员里,校验转移后通知监听器。Application 的监听器只置 MAIN_EVENT_STATE_CHANGED,实际 UI/音频响应在主事件循环中完成。状态监听器本身运行在提出转移的调用上下文,不能由 atomic 推断“全部状态转移代码只运行在单一线程”。状态机成员与回调约定、转移校验及通知、状态事件接入

下图依据实际转移校验和 Application 调用抽取主要路径,不是完整枚举图,也不是厂商额外发布的正式状态图。音频测试、所有 Idle 出边和同状态 no-op 被省略。“上游允许”的边表示状态机允许,不表示工厂默认一定经过;工厂配网回退实际会重启。

查看 Mermaid 图源
stateDiagram-v2
  [*] --> Unknown
  Unknown --> Starting : Initialize
  Starting --> Activating : 网络就绪
  Starting --> WifiConfiguring : 上游允许
  WifiConfiguring --> Activating : 上游允许
  Activating --> Idle : 激活任务完成
  Activating --> Upgrading : 新固件
  Upgrading --> Idle : 上游允许的失败返回
  Idle --> Connecting : 打开会话
  Connecting --> Listening : 打开成功
  Connecting --> Idle : 打开失败
  Listening --> Speaking : tts start
  Speaking --> Listening : tts stop / 自动继续
  Speaking --> Idle : tts stop / 手动停止模式
  Listening --> Idle : 通道关闭
  Idle --> Speaking : 上游允许
  note right of WifiConfiguring
    工厂 Board 回退走 requestAppSetup
    保存 warm_boot 后重启进入 BLE 配置
    不等于停留上游配网 AP
  end note
StackChan 会话状态
StackChan 会话状态 · 点击查看原图

StackChanAvatarDisplay 另外持有 speaking、idle motion、idle expression、blink 的修饰器 ID,以及睡眠标志。SetStatus 用本地化状态字符串识别 Listening、Standby、Speaking,再操作这些 ID、嘴巴权重和 RGB。这里是小智状态到机器人表现的适配层,不是 DeviceStateMachine 本体。Sleeping 又来自 SetEmotion("sleepy") 的额外处理,因此“睡脸”“会话 Idle”“空闲动作正在运行”不是一个状态变量。Display 状态成员、状态到修饰器

(二)StackChan、Avatar 与 Modifier

GetStackChan() 返回机器人单例。它用 unique_ptr 持有 Avatar、Motion,并以 ObjectPool<Modifier> 持有行为对象。每次 update 的固定顺序是:遍历 modifier、清理请求销毁的对象、更新 Avatar、更新 Motion,最后更新两侧霓虹灯。这意味着修饰器首先写入目标属性,再由后续对象推进表现。对象池 ID 是可复用槽位,不是跨会话永不重复的动作编号。更新顺序与所有权、对象池分配与释放

Avatar 将表情枚举广播给关键元素和装饰器。默认皮肤 DefaultAvatar 建立 320×240 容器,创建两个 DefaultEyes、一个 DefaultMouth 和 DefaultSpeechBubble。表情不是一张预渲染整脸图片的替换动作,而是具体元素收到 emotion 后更新各自形态。装饰器另有对象池和生命周期,适合心形、汗滴等附加表现。Avatar 广播及更新、默认皮肤装配、眼睛情绪映射

Modifier 通过 Modifiable 接口获得 avatar、motion 和灯光。SpeakingModifier 默认可以驱动轻微头动,但 AI Display 实际创建时传入 (0, 180, false),表示持续到手动移除、嘴巴约每 180ms 更新、关闭该修饰器的头动。嘴型是随机权重开合,不是从 TTS 音素或音频包逐帧同步而来。修饰器接口、说话修饰器算法、实际创建参数

(三)Motion、Servo 与硬件闭环边界

Motion 持有 yaw、pitch 两个 Servo,将“朝向”“速度”“停止”等操作拆成单轴目标。Servo 用 smooth_ui_toolkit 的弹簧动画推进角度,在目标入口限幅;ScsServo 再把逻辑角映射为原始位置,按运行时原始位置限幅后通过 SCSCL 总线下发。固件内部角度参数不是可以不加解释直接当作整度的任意数值,驱动映射中包含 angle * 16 / 5 / 10。Motion 持有舵机、Servo 插值与限幅、ScsServo 映射与反馈

当前位置在 ScsServo 优先读总线,读值无效时退回插值值。isMoving() 同时检查插值尚未结束和驱动 ReadMove。Pitch 配置开启堵转保护,通过位置变化、电流、负载采样收紧运行时限位并停止当前插值;Yaw 配置允许 PWM 模式。它们属于该硬件控制实现,不能从接口名推断已完成负载安全验证。堵转处理、两轴配置

五、RTOS 任务、队列与锁

查看 Mermaid 图源
flowchart LR
  subgraph AI["AI 模式:FreeRTOS 任务分组"]
    IN["audio_input<br/>优先级 8"]
    CODEC["opus_codec<br/>优先级 2"]
    OUT["audio_output<br/>优先级 4"]
    Q["AudioService 队列<br/>mutex + condition_variable"]
    MAIN["Application.Run<br/>主任务优先级 10"]
    EVT["EventGroup + main_tasks"]
    ACT["activation<br/>优先级 2"]
    UP["stackchan<br/>优先级 3 / core 1"]
    LV["LVGL port<br/>优先级 3 / 多核时 core 1"]
    LOCK["同一 LVGL port 锁"]
    IN --> Q
    Q <--> CODEC
    Q --> OUT
    Q --> EVT
    ACT --> EVT
    EVT --> MAIN
    MAIN --> ACT
    MAIN --> LOCK
    UP --> LOCK
    LV --> LOCK
  end
  subgraph AV["Avatar 模式:另一组生命周期"]
    REM["avatar_remote 连接任务"]
    LOCAL["avatar_lan 连接任务"]
    MQ["ReceivedMessage 有界队列<br/>channel + generation"]
    WORK["Mooncake WebsocketAvatarWorker"]
    APP["AppAvatar 回调 / onRunning"]
    REM --> MQ
    LOCAL --> MQ
    MQ --> WORK
    WORK -->|"HAL signals"| APP
  end
StackChan 任务协作
StackChan 任务协作 · 点击查看原图

AI 模式下,Application::Run 把当前主任务优先级提高到 10,在 EventGroup 等待网络、音频、状态和调度事件。Schedule 将 lambda 放入受 mutex 保护的 main_tasks 队列,主循环取走整批后解锁执行,所以不会持该队列锁运行显示或网络业务。音频发送队列的可用通知也只置事件位,主循环随后提取音频包并交给 protocol。主事件循环、Schedule 与中止

AudioService 另外创建 audio_input、audio_output、opus_codec 任务,优先级分别为 8、4、2;配置启用音频处理器时 input 固定到 core 0。编码、解码、待播与待发送队列使用 mutex/condition_variable 协作,Opus 编解码任务同时处理上下行,output 从播放队列取数据写 codec。语音播放完成与“收到 tts stop”因此存在队列边界。音频任务创建、输出与编解码队列

工厂 stackchan 更新任务是另一条优先级 3、core 1 的任务。LVGL port 同样设置优先级 3,多核时固定到 core 1。机器人任务用 LvglLockGuard,Display 方法用 DisplayLockGuard,两者最终落到该 Display 的 lvgl_port 锁。update 任务每轮先延迟 20ms,非 Idle 时在已持锁的范围内再延迟 100ms,然后才 update。Servo 自己只按固定 0.02 秒推进一次,因此不能把源码中的“最多 50Hz”当作所有模式下实测的 50Hz 控制周期。机器人更新任务、LVGL port 参数、Display 锁、Servo 更新步长

Avatar 模式则由 Mooncake 的 WebsocketAvatarWorker 调用服务 update,连接工作分别放在 avatar_remote、avatar_lan 任务。网络回调复制消息到有界队列,业务 worker 再处理,避免连接失败阻塞摄像头与控制处理。每条队列记录 channel 和 generation,处理时丢弃旧连接代次;当前队列最多 16 条、累计 256KiB,达到上限直接不入队。这里实现的是受限缓存和旧回调隔离,不是可靠消息重投机制。消息处理边界、队列与连接任务、Mooncake worker

六、Flutter App 的状态、BLE 与双通道传输

手机入口注册 GetX 的 AppState、恢复持久化字段后运行 App。AppState 同时是 WidgetsBindingObserver,持有当前设备、用户信息、登录状态和连接状态,并订阅 LAN 连接/endpoint 事件。它承担跨页面状态与服务编排,而不是每个页面各自创建连接。源码入口把 AudioEngineManager 的导入和初始化注释为暂时关闭,所以协议里存在 Opus 或通话消息不能据此声称当前 App 入口已启用完整音频功能。手机入口、AppState 初始化

(一)BLE 配置与本地写入

BlueUtil 是 BLE 服务单例,保存设备、特征值、订阅与重连相关状态。底层通过 NativeBluetoothBridge 的 MethodChannel 发调用、EventChannel 收事件,Dart 的 Device/Characteristic 包装对象再提供 connect、discoverServices、write 等方法。本文读到 Dart 原生桥边界,未逐条核对 iOS/Android 原生回调实现。BlueUtil 与 GATT 常量、原生桥通道

App 与固件共有分片魔数 AA 55 C3、版本 1、10 字节头。App 根据协商的 MTU 分片;固件 BleFragmentAssembler 检查总包数、次序和长度后,把完整配置/动作/表情 JSON 作为 HAL 信号发出。Wi-Fi 配置使用 setWifi,查询使用 getWifiStatus,另有 handshake。WifiConfigServer 不在 ESP Wi-Fi 回调中直接发 BLE/更新 UI,而是将连接结果入队,在 worker update 中发送状态和 AppConfigEvent。App 分片写入、固件分片重组、配网结果跨回调处理、配置命令处理

(二)LAN 是手机服务端,不是设备发现服务器

LocalAreaNetworkService 在手机绑定 IPv4 和随机端口。前台状态、页面引用计数和目标 MAC 决定服务是否保持,串行的 lifecycle Future 负责协调重启;generation 避免旧的异步请求落到新目标。endpoint 由 AppState 经远端连接发送 AppLanAddress,设备才主动连到手机,并没有在这里通过 mDNS 搜索手机。Go 未为 0x1B 建立独立业务分支,而是由未知二进制消息的 default 分支按连接 MAC 转发。LAN 生命周期、端点通告、Go 默认转发

握手时手机解密 Authorization,检查三段结构、目标 MAC 和当前连接代次,只允许一个活动设备连接。这里读取的检查未校验时间戳的新鲜度,不能把 Go 远端的 ±10 秒校验套到 LAN。升级后消息仍是明文应用帧;RSA 握手字段也不是逐包加密密钥。LAN 握手检查、LAN 报文定义

DeviceMessageTransport 先尝试 local.sendConnectedMessage,返回 false 才调用远端发送者。LAN 使用 20 字节 SC 头,包含版本、类型、flags、session、sequence、长度;远端使用类型 1 字节加长度 4 字节。设备 local_network 适配在检查帧结构与目标 MAC 后,将 LAN 帧转成远端的 5 字节格式,再交给同一个 HAL handler。session/sequence 字段的存在不能推导出已实现去重、确认或重放防御,当前这段 decoder 未做该验证。传输选择、LAN 转换层

七、Go 后端的认证与数据流

Go 的 main 引入 MySQL 驱动并启动 cmd.Main。cmd 设置 GoFrame 路由,分别装配 v2 登录用户接口、旧版设备业务接口、管理端、文件访问与 WebSocket Handler。controller 负责请求入口,service 负责跨服务流程,DAO 执行业务持久化;WebSocket 则维护进程内在线会话。数据库与在线连接不是一个原子状态来源,服务重启后内存连接池需要重新建立。Go 入口、路由装配、连接池

(一)三种身份凭据各自解决什么

入口 源码里的身份处理 不能合并为同一保证的原因
/stackChan/v2 除 login/registration 外读取 token 头,验证 HMAC JWT,将 id 放入请求上下文 UID 表示登录用户,并不自动等于某条 WS 会话的设备身份
旧版 /stackChan TokenAuthMiddleware 尝试 RSA 解密 MAC 凭据后写入上下文 解密失败仍 Next,middleware 本身不拒绝请求,具体端点需分别看处理
/stackChan/ws GetMac 解析成功且 MAC 非空才允许升级 使用 MAC/随机串/时间戳凭据,不是 v2 JWT
/admin/stackChan 独立 AdminTokenAuthMiddleware 读取 Authorization JWT 与手机 v2 token 头及设备凭据不同

上述结论来自分支本身,不把名为“TokenAuthMiddleware”理解成统一强制权限边界。GetMac 解密三段内容,检查时间戳在服务器时钟前后 10 秒内;本次未对所有旧版 controller 的授权条件进行安全审计。v1/v2 中间件、管理端中间件、WS 身份校验

(二)登录、绑定与小智 API

登录请求先由 Go service 调用配置中的 M5Stack 远端账号服务,获得 UID 后将用户资料 Save 到本地,再签发本服务 HS256 JWT。其过期时长常量为 365 天,源码虽写入 jti,但本段没有实现撤销列表,不能从注释“for revocation”推导出已具备撤销系统。手机 Http 拦截器同时附加旧版加密 MAC Authorization 和登录 token,收到 HTTP 401 时退出登录。登录与用户保存、JWT 签发、手机 HTTP 拦截器

绑定按顺序执行:校验请求 MAC 和 UID;调用 M5Stack 工厂设备校验;查小智激活状态;必要时生成 license 并激活,再查状态;恢复默认 agent 模板;最后通过数据库事务写入设备 UID 和绑定时间。事务只覆盖最后本地写入,不包住前面的外部 API。因此小智已激活而最后本地写入失败,是流程上不同阶段的失败,不存在这里可见的跨系统全局回滚。绑定编排、工厂设备核验、本地绑定事务

小智管理 API 是另一组凭据。Go 从配置读取 secret_key 换取 token,控制器可将该 token 返回给手机;手机 XiaoZhiUtil 缓存它并直接调用 xiaozhi.me,遇失效再请求工厂服务刷新。绑定与 license 生成还需要额外配置的生成许可凭据。因此“App 只访问自家 Go”不符合这一版本实际代码。token 控制器、开发者 token 获取、手机 token 获取与刷新

(三)远端消息不是数据库任务队列

AppClient、StackChanClient 持有连接、RWMutex、最后活跃时间、取消上下文和容量 100 的 sendChan。每个客户端单独启动 writer goroutine,从 channel 取消息再 WriteMessage,避免业务处理代码直接并发写同一连接。设备客户端另持有摄像头/音频订阅列表和通话 App 指针。发送辅助函数使用非阻塞 select,队列满只记录日志,不持久化重试。客户端状态与 writer、满队列处理

远端帧先校验 5 字节头及实际长度。ControlAvatar、ControlMotion 等指令使用 payload 前 12 字节目标 MAC,服务拆掉前缀再发送给设备;部分类型则按当前 App 连接所关联 MAC 路由。由此可知,“一条连接认证的 MAC”和“某些消息内携带的目标 MAC”是两个需要分辨的值,不能把所有消息统一画成仅按登录 UID 查设备。远端帧检查、控制消息路由

八、两条端到端调用时序

(一)AI 的 tts 状态与 sleepy 表情

查看 Mermaid 图源
sequenceDiagram
  participant Net as 小智 Protocol 回调
  participant App as Application 主事件循环
  participant State as DeviceStateMachine
  participant Display as StackChanAvatarDisplay
  participant SC as StackChan
  participant Tick as stackchan 更新任务
  participant Servo as Servo / ScsServo
  participant Audio as AudioService
  Net->>App: Schedule(tts start)
  App->>State: TransitionTo(Speaking)
  State-->>App: MAIN_EVENT_STATE_CHANGED
  App->>Display: SetStatus(SPEAKING)
  Display->>SC: addModifier(SpeakingModifier)
  App->>Audio: 调整处理器 / ResetDecoder
  Net->>Audio: IncomingAudio -> decode queue
  Net->>App: Schedule(llm emotion = sleepy)
  App->>Display: SetEmotion(sleepy)
  Display->>SC: Avatar.setEmotion / Zzz
  Display->>Servo: pitch.moveWithSpeed(0,80)
  loop 独立更新任务持 LVGL 锁
    Tick->>SC: update()
    SC->>SC: modifier / avatar update
    SC->>Servo: Motion.update -> Servo.update
    Servo->>Servo: 插值 -> WritePos
  end
  Net->>App: Schedule(tts stop)
  App->>State: TransitionTo(Idle 或 Listening)
  App->>Display: 下一轮处理状态变化
  Display->>SC: remove SpeakingModifier / 闭嘴
  Note over App,Servo: tts stop 与舵机动作完成不是同一边界
StackChan AI 表达时序
StackChan AI 表达时序 · 点击查看原图

这条时序从已经建立的小智协议连接开始。tts start 经 Schedule 进入 Application 主任务,转移 Speaking,随后状态事件触发 SetStatus 并添加 SpeakingModifier。llm emotion 是另一条 JSON 消息,sleepy 会把 Avatar 设为 Sleepy、显示 Zzz、移除空闲修饰器并令 pitchServo.moveWithSpeed(0,80)。单轴目标仍需等待机器人更新任务推进,最终写入舵机总线。JSON 分支、sleepy 分支

上行音频和下行音频不经过上述“表情 JSON”的同一函数参数。IncomingAudio 仅在当前 Speaking 时进入解码队列;TTS 停止消息按 ListeningMode 转为 Idle 或 Listening,Listening 分支在特定条件下等待播放队列为空,再启用语音处理。这个机制解释了会话状态与声学缓冲的协作,也说明显示闭嘴、队列排空、扬声器实际发声结束和舵机到位不是同一条完成通知。下行音频入口、Listening/Speaking 副作用

(二)手机发姿态命令到舵机

查看 Mermaid 图源
sequenceDiagram
  participant Page as Flutter 页面 / AppState
  participant LAN as 手机 LocalAreaNetworkService
  participant Remote as WebSocketUtil / Go WS
  participant Client as 固件 AvatarClient
  participant Worker as WebSocketAvatar / Mooncake worker
  participant Avatar as AppAvatar / StackChan
  participant Servo as Motion / ScsServo
  Page->>LAN: retainForPage / target MAC
  LAN-->>Page: endpoint(ip,port,path)
  Page->>Remote: AppLanAddress 0x1B
  Remote->>Worker: 按连接 MAC 转发
  Worker->>Client: 公告 endpoint
  Client->>LAN: 主动 WS 连接 + RSA Authorization
  LAN-->>Client: 校验 MAC / Upgrade
  Page->>LAN: DeviceMessageTransport.send(ControlMotion)
  LAN->>Client: 20字节 SC 包头 + MAC前缀 + JSON
  Client->>Worker: 校验并转为5字节远端帧 / enqueue
  Worker->>Avatar: onWsMotionData.emit(payload)
  Avatar->>Avatar: LVGL锁 / updateMotionFromJson
  Avatar->>Servo: moveWithSpeed 等命令
  loop AppAvatar.onRunning
    Avatar->>Servo: StackChan.update -> WritePos
  end
  alt LAN不可用或交帧失败
    Page->>Remote: 远端5字节帧 + MAC前缀
    Remote->>Worker: 去掉目标MAC后转发
  end
  Note over Page,Servo: send成功只表示交给连接,不是物理动作完成确认
StackChan LAN 控制时序
StackChan LAN 控制时序 · 点击查看原图

该路径以设备处于 AVATAR 应用、手机已有远端连接并打开相关控制页面为前提。局域网连接建立之后,控制数据可以直接走 LAN;建立 endpoint 的现有通告路径仍使用远端连接。设备 AvatarClient 验证/转换帧后,WebSocketAvatar 将 ControlMotion 发为 HAL 信号。AppAvatar 在回调中加 LVGL 锁,调用 JSON helper;helper 根据 rotate、angle、speed、spring 字段选择舵机操作。AppAvatar.onRunning 持续更新机器人,负责后续插值,而不是网络回调等待机械动作完成。AppAvatar 回调、JSON 动作分派、应用更新

九、异常、取消与释放的实际边界

语音取消通过 AbortSpeaking 设置 aborted_ 并向协议发送中止请求,本函数本身没有清空播放队列或停止舵机。网络断开则在 Connecting/Listening/Speaking 时关闭音频通道,通道关闭回调 Schedule 回 Idle。重置解码器、停止 AudioService、移除嘴型修饰器是不同代码路径,不能统一理解成“取消后所有资源已经停止”。语音中止函数、网络断开、音频服务停止

表情修饰器有两种结束方式:调用 removeModifier 立即释放,或对象先 requestDestroy,再由 update 结束时 cleanup 回收。Motion.stop 给两轴重新下发当前角目标;是否释放扭矩另由自动释放或显式接口决定。一个 modifier 被移除,已写入 Servo 的目标不会因此自动撤销。舞蹈触屏分支就是只移除 DanceModifier,因此这里只能描述行为生成停止,不能宣称即时急停。修饰器释放、Motion 停止、舞蹈取消入口

Avatar 网络对象销毁时先标记 stopping、断开 HAL 通话回调、销毁 LAN 客户端,再等待远端任务结束后释放 socket。LAN 客户端也等待自己的任务结束,并在销毁 socket 时避免持有其回调需要的锁。这是显式的跨任务收尾,不是简单 reset 一个连接指针。等待使用 portMAX_DELAY,所以该机制是否在所有异常网络情况下都能及时结束,仍需运行验证。Avatar 析构、远端任务退出等待、LAN 客户端释放、socket 锁边界

手机 LAN 在进入后台、最后一个页面离开、切换目标或 dispose 时收尾,并以连接对象身份检查阻止旧回调关闭新连接。远端 WebSocketUtil 有独立重连逻辑,不与 LAN 共享连接状态。Go writer 的 cancel 结束发送 goroutine,在线连接清理另由连接处理和定时任务管理;本报告未逐分支证明其所有断开、订阅移除和重连竞争都无竞态。手机 LAN 生命周期、手机旧连接回调隔离、远端重连、Go writer 取消

OTA 是版本检查、固件下载和重启流程。Hal.updateFirmware 检查失败返回 false,无新版本时确认当前版本,升级失败等待后重启,成功也重启。小智 OTA 同时承担协议端点配置发现,业务服务器地址与 OTA_URL 是独立配置,因而升级控制面不能简单等同于 Avatar 的 Go WebSocket 服务。工厂 OTA 流程、独立地址配置、OTA 协议配置解析

十、架构取舍与尚未覆盖的部分

从源码可见,工厂选择在既有小智应用内换入机器人 Display/Board,同时保留独立 Mooncake 应用体系。这样语音、协议和升级可沿小智主干演进,表情与动作由工厂对象模型承接;代价是两套生命周期的交接必须处理全局对象、信号和重启,且 patch 与固定依赖共同构成真实程序,单看一个仓库目录不足以解释行为。

Avatar 路径把 LAN 和远端转成共同 HAL 消息,减少两套表情执行逻辑,但保留了两种帧封装、两种握手和手机服务端生命周期。generation、队列上限与非阻塞丢弃优先保护设备内存和连接切换,不能提供“每条动作必达必完成”的语义。Go 同时兼容旧 MAC 路由和 v2 用户体系,降低了旧入口迁移成本,也形成必须逐入口理解的身份边界。以上是对实现结构的分析,不是已证实的作者设计动机。

未覆盖部分有明确边界:Mooncake 和 smooth_ui_toolkit 的内部调度/插值实现未逐文件审计;ESP-IDF、esp_lvgl_port、NimBLE、Wi-Fi 和底层总线驱动未全栈追踪;Android/iOS 原生 BLE 回调、后台限制、相机与音频端到端未实测;Go 所有社交/舞蹈/管理 controller 的权限和数据库迁移未审计;云端小智 ASR、LLM、TTS 的服务实现不在所读仓库中;真实舵机负载、堵转、OTA 回滚和断网竞态未验证。图示依据源码职责与调用关系,不把这些未知补成运行保证。

十一、实际阅读路径与定位索引

下表记录本轮实际阅读的机制范围。正文链接均固定到上述两个提交;“针对性”表示读了列明行段及相关调用,没有声称读完整个目录。

范围 实际已读路径与行段 阅读深度
固件装配 firmware/repos.json 全文;firmware/CMakeLists.txt 全文;firmware/main/CMakeLists.txt 1–75,组件注册与资源规则;firmware/README.md 1–17;patch 1–121、143–341、345–415 构建机制针对性阅读,未执行脚本
启动与 Board main/main.cpp 全文;hal/hal.cpp 14–202;hal/board/hal_bridge.cc 106–120;hal/board/stackchan.cc 677–719;hal/hal_app_setup.cpp 全文;apps/app_ai_agent/app_ai_agent.cpp 全文 深入主链
表达对象 stackchan/stackchan.h、modifiable.h、avatar/avatar/avatar.h、avatar/skins/default/default.cpp、modifiers/speaking.h 全文;avatar/skins/default/default.h 19–92;eyes.cpp 情绪映射;utils/object_pool.h 13–140 深入主链,未穷尽其他修饰器
动作与显示 motion/motion.h 18–130、motion.cpp、servo.cpp、hal/hal_servo.cpp 全文;stackchan_display.h 全文、stackchan_display.cc 105–127、216–378、381–568;json/json_helper.cpp 14–115 对象、调用及边界深入阅读
小智固定依赖 main/application.h 全文;application.cc 61–337、471–565、878–943;device_state_machine.h/.cc 全文;display/lvgl_display/lvgl_display.h 全文;audio/audio_service.cc 125–181、286–343;ota.cc 端点解析 主状态/队列深入阅读,未读取所有编解码和网络内部
Avatar 网络 apps/app_avatar/app_avatar.h、app_avatar.cpp 67–123、205–308;hal_ws_avatar.cpp 35–255、375–404、480–620;local_avatar_client.cpp 38–128、168–252;local_network_protocol.h 17–89 双通道与生命周期深入阅读
BLE 配网 hal/hal_ble.cpp 18–297、351–527;hal/hal_network.cpp 23–120;hal/hal_ota.cpp 全文 配网消息与结果路径针对性阅读
Flutter 入口/状态 app/lib/main.dart 全文;app_state.dart 37–173、260–333、504–541;view/app.dart 18–125;pubspec.yaml 4–89 状态与服务编排深入阅读,页面样式仅略读
Flutter 传输 device_message_transport.dart 全文;local_area_network_service.dart 18–110、176–305、352–468;web_socket_util.dart 35–95、194–215;http.dart 38–100;blue_util.dart 38–230、938–1065;native_bluetooth_bridge.dart 53–155、212–249;xiao_zhi_util.dart 28–100、135–171 消息、生命周期与凭据针对性阅读
Go 服务 server/main.go、internal/cmd/cmd.go、middleware/middleware.go 全文;service/user.go 28–146;service/device.go 78–195、241–255;model/web_socket_model.go 17–200;web_socket/web_socket.go 65–175、308–324、489–568、740–837;xiaozhi/xiaozhi.go 588–620;token controller 全文 身份、绑定、连接和转发深入阅读,未覆盖全体业务 controller

图源与正文 Mermaid 块内容一致,PNG 与 SVG 已统一渲染并检查尺寸和显示。源码关系及本地链接已核对;未验证所有 Markdown 阅读器的排版,也未执行固件构建、刷机或整机测试。