DreamSoul研究
源码与架构 /

StackChan 表达终端 源码研究

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

结论与适用范围

优先复用 M5Stack 2026 年工厂栈中的表达层、舵机抽象和设备通信协议,再决定是否保留其 App、账号和小智云链路。 它已公开设备 C++ 固件、Flutter App 和 Go 后端,适合作为小型桌面表达终端的工程起点。核心可取资产是 stackchan/avatar、stackchan/modifiers、stackchan/motion 和端到端消息格式,不是一个已完成自主账号、模型服务和量产验证的整机方案。实际入口见 工厂启动链、表情与状态桥接。

本报告供桌面智能硬件技术选型与原型开发使用,围绕“能拿哪些代码、如何换后端、哪些结构可改、复用前还缺什么”展开。信息截止与访问日期均为 2026-10-27。工厂栈为主,原社区栈和 K151 硬件作为同一重点内的对照。已有广域研究只提供定位,本报告重新核验了当前分支和文件,不以旧报告的 commit 代替最新源码。

最重要的三个边界:

版本、新旧与证据深度

对象 仓库创建时间 UTC 实际检查的默认分支与固定 commit 该提交时间 UTC 发布/版本判断
M5 工厂栈 2026-01-07 09:16:45 main,eff0d6b5109663faec8f1d98848b4b0e5246bbfc 2026-10-22 01:40:01 查询 GitHub releases/tags 均为空。App 源码 1.2.8+32,固件源码 1.6.0
原社区栈 2021-06-06 14:31:19 develop,373fad66cec9af4ee5c9a3643fc8832a4014c642 2026-10-25 00:24:34 老项目仍活跃维护。最近正式 release v2.0.1,2026-10-20 08:45:18 UTC,tag commit 6a8f7553610e5d91770901e76fd93a0c50cfd970,与本报告默认分支不同
M5_Hardware 2021-11-04 09:21:19 master,e29c139cbc7c80b5ccc5557e5ab8025a7a19a109 2026-10-23 06:10:33 查询 releases/tags 均为空。最新全仓提交修改 U082-X,不能当成 K151 更新日期
工厂固定的小智依赖 不用于判断项目新旧 v2.2.4,e77dedb1309153bb63fed285772962c920c97dd4 2026-03-09 11:33:01 工厂另施加补丁。这里读的是所固定依赖,不是小智最新默认分支

版本证据:App 实际版本与 SDK、固件版本与本地配置覆盖、依赖固定清单、社区 v2.0.1 发布。仓库创建时间来自 GitHub 仓库元数据,它不等于产品首次销售日期。

未确认源码与发行二进制是否同步。 官方恢复流程让用户通过 M5Burner 获取最新固件,但所读页面未给出可与 1.6.0 对应的二进制 commit 或可重现构建证明。也未安装 App Store/Play 商店版本。不能把提交消息“prepare 1.2.8 release for open source”当成商店已发布证明。工厂固件恢复说明

阅读层次 本次覆盖 未据此声称的能力
实际代码,针对性深入 工厂 main.cpp、HAL 初始化/舵机/显示/配网/OTA、表达 Modifier、App URL/LAN/配网页、Go 登录/中间件/小智请求/路由、小智 application/OTA/audio/WebSocket 核心路径 完整代码审计、无缺陷、安全认证、软硬件实际可运行
实际代码,对照阅读 社区启动、组合根、驱动选择、面部状态、CoreS3 舵机驱动,相关许可 全部 MOD/模拟器功能已运行
文件树和文档 K151 10 个 STL、社区 STEP/STL/KiCad/放置坐标/部分 Gerber 文件,官网 5 个原理图 PDF 可访问并解析 CAD 尺寸合格、打印适配、电气设计正确、制造资料完整
本地源码一致性检查 15 项 assert,引用文件同时核验 Git blob SHA-1 编译通过、硬件烧录、音质/时延/功耗/寿命、账号服务可用

工厂栈的执行链与可复用模块

StackChan 表达终端 源码研究 图示
StackChan 表达终端 源码研究 图示 · 点击查看原图
查看 Mermaid 图源
flowchart LR
  Boot[app_main / HAL 初始化] --> Choice[Mooncake 应用选择]
  Choice --> Expr[StackChan 表情和运动]
  Choice --> AI[XiaoZhi Application]
  AI --> Audio[音频采集 / Opus / 播放]
  AI --> Status[说话 / 倾听 / 待机状态]
  Status --> Expr
  App[Flutter App] -->|BLE 配网| Boot
  App -->|HTTP / WebSocket| Go[Go 设备与账号服务]
  Go --> Account[外部账号服务]
  Go --> XZ[小智开发者 API]
  App --> XZ
  AI --> OTA[OTA 与语音端点发现]
  App -->|LAN 直连媒体和控制| Expr

图中的 LAN 通道不是首次启动即独立的本地服务:App 源码说明端点由远端 AppLanAddress 消息通知固件,手机再作为 WebSocket 服务端接入。RSA 握手用于认证,应用消息保持明文,不能把“局域网通信”解释成已消除远端引导依赖或全程加密。LAN 包格式与引导依赖

层/路径 代码中的实际行为 可直接复用与改造点
firmware/main/main.cpp 与 hal/hal.cpp NVS、板级、小智 MCP、触摸、扩展 IO、RTC、IMU、舵机、LVGL 初始化。可跳过 Mooncake 直接进入 AI,或安装应用后等待 AI 启动请求,退出 UI 框架再进入小智主循环 复用 HAL 分层和显式模式切换。平台更换时保留 NVS 错误恢复和外设顺序,重新验证 UI/AI 切换资源生命周期。HAL 初始化、入口与应用清理
stackchan/avatar、stackchan/modifiers、board/stackchan_display.cc LVGL 创建默认脸,挂接呼吸、眨眼、摸头、IMU Modifier。情绪字符串映射为本地枚举,未知值落 Neutral。STANDBY 启动 idle,LISTENING 关嘴,SPEAKING 挂接嘴部动画 适合先独立抽出表达终端。将模型输出收敛为受限情绪/动作事件。口型改为播放时钟或能量驱动后,再评估音素同步。UI 和 Modifier、状态转换
stackchan/motion、hal_servo.cpp 两个反馈串口舵机,UART1 1 Mbps,ID 1/2。使用 NVS 零位、原始位置范围、角度限位和俯仰堵转保护。角度以十分之一度传递 可复用运动接口、归一化视线转换和限位思路。新电机/结构必须改零位、比例、限位和堵转参数。代码俯仰限位 30..870 即 3..87°,官网建议 5..85°,原型先按更窄机械范围验证。校准与位置映射、硬件参数、官方机械范围提醒
motion_math.cpp 归一化输入夹到 [-1,1] 后线性映射,空间点用 atan2 求 yaw/pitch,输出十分之一度 适合作为无硬件首个模块。已有 host test 覆盖中心、上下限、越界与空间方向。未运行该 C++ 测试。运动纯函数、现有运动测试
小智 application.cc 与 audio_service.cc Application 收发音频队列,接收 tts start/stop、stt、llm emotion 等消息,驱动 Listening/Speaking/Idle;语音网络、唤醒、编码与播放由小智依赖承载 可复用事件桥接,不能仅搬表情类就声称完成语音链路。模型、ASR/TTS 服务及声学调优另行选型。音频及 JSON 事件、设备状态行为
hal/audio.cpp 提供 3 秒麦克风录制回放及波形采样,内存分配失败、无采样、编解码器不存在时返回失败 可保留为板级自测入口,硬件到位后验证双麦与扬声器路径。不能以代码存在代替 AEC、识别率或回声测试。麦克风自测

这里的 AI 主循环来自固定小智依赖,再由工厂补丁修改,不能把 upstream v2.2.4 与工厂编译产物视为字节一致。小智固定与 patch

App、认证、OTA 与自建后端

环节 已读代码事实 自建时必须处理
配网 App 构造 setWifi JSON,含 ssid/password 和频段提示。固件验证两个字段为字符串,进入连接状态,成功/失败通过 BLE 通知,且支持分包与连接失败原因 保留字段、分包上限、超时和重试策略。手机权限、2.4 GHz、凭据存储与 BLE 安全需要实机验证。App 发配网数据、固件接收与状态回报
App 后端地址 urls.dart 是编译进 App 的占位地址,并分别拼 http://、ws://。README 的 .env 建议不等于所读实现自动加载 .env 修改实际代码并重新构建 App,配置 HTTPS/WSS 和证书策略,不要仅修改 README 或新增未读取的环境文件。实际 URL 组合
用户身份 Go Login 先调 m5stack.loginUrl,成功后保存用户并签发本地 JWT;注册另需远端注册/用户名查询地址和凭据。V2 中间件校验 token 保留兼容账号系统或自行替换身份适配层,不能把 MySQL 中的用户表理解为独立账号系统。登录到远端、注册到远端、V2 token 校验
小智授权 Go 将 baseUrl 固定为 https://xiaozhi.me/,需要 xiaozhi.secret_key 和 generate_license_token,App 的小智工具也直接设此域名 若保留小智,先取得合法可用的开发者/激活凭据;若完全自建,重写这一服务适配及 App 相应 API,不只是代理一个域名。API 与鉴权入口、License 凭据、开发者 token、App 直连
绑定互通 工厂 patch 丢弃社区 activation code/message,改成 requires_app_binding_。官方说明 StackChan World 与其他小智绑定体系不互通 自建要定义激活、绑定、解绑和用户归属协议,并重做相关 UI。换固件前按官方流程解绑,不能当作无损切换。工厂激活改造、官方小智绑定说明
OTA 与端点发现 固件 StackChan 业务地址和 OTA_URL 是两个配置。小智 OTA 读取 NVS ota_url 或默认值,返回 websocket/mqtt 配置及固件 URL/version。工厂升级函数查版本、升级并重启 自建需要实现兼容响应或替换 OTA 客户端,维护签名/验证、回滚和版本策略。还要检查既有 NVS 是否覆盖新的编译默认值。业务服务和 OTA 配置、NVS URL 覆盖、端点配置解析、升级流程
Go 服务 GoFrame HTTP 路由、MySQL 数据、JWT、文件服务和 WebSocket 转发。App V2、设备旧接口、admin 使用不同中间件。默认配置中 DB/JWT/RSA/小智字段留空 配齐部署参数和权限边界,再测 API 契约。服务自身不是 ASR/LLM/TTS 推理实现。HTTP 路由、待填配置
LAN 媒体/动作 手机发布 WebSocket,固件收 AppLanAddress 后连接。20 字节包头,SC magic/version/type/session/seq/length;校验长度、类型、目标 MAC 可作为本地表达控制协议起点,但应把首次发现、认证和加密纳入独立设计。现有 RSA 握手不对后续 payload 加密。LAN 编解码、LAN 身份校验

最小自主原型建议:先把表情、动作和设备控制保留在 ESP32,PC 或自己的服务只发送有限的状态/动作命令,先完成无模型的交互闭环。等此链路稳定,再接一个明确的语音后端。完整保留现有社交、视频、舞蹈、商店、账号和云激活会扩大迁移面,当前不建议全部照搬。

构建基线应以实际文件为准:工厂固件 README 指 ESP-IDF 5.5.4,repos.json 固定 Mooncake 2.3.3、smooth_ui_toolkit 2.12.0 和小智 2.2.4 等;App pubspec.yaml 声明 Dart 3.13.5,大量依赖未写版本且树中未见 app/pubspec.lock;Go 模块要求 1.26.3,并固定 GoFrame、JWT、WebSocket 版本。App README 的 Flutter/Dart 3.0+ 是较宽说明,不能作为可靠构建锁。固件构建要求、固定固件依赖、App 构建清单、Go 版本

社区栈与硬件开放深度

原社区栈不是工厂 C++ 栈的可互换版本。它使用 JavaScript/TypeScript、Moddable/Piu、MOD 扩展和浏览器工具,当前同样以 M5StackChan CoreS3 为标准配置。main.ts 先加载行为与偏好、启动网络服务、再构造运行上下文,并提供连接失败后的 retry/offline 分支。组合根登记多种舵机和 TTS 实现,面部状态有独立的眼睛、嘴、呼吸、情绪、主题对象。适合行为脚本和可定制表达研究,刷入会替换工厂固件。社区范围与刷机边界、社区启动和离线选择、驱动与 TTS 组合、面部状态

资产 公开深度与具体路径 复用判断
K151 结构 Products/K151_StackChan/Structures/:Base、BaseCover、BearingFixture、LightGuideBar-A/B、MainBody、ServoArm、ServoBody、ServoCover、ServoSideCover 共 10 个 .stl。固定结构树 可用于空间参考和打印试装。仅核目录,未打印/量测。未见此 SKU 的 STEP、原生参数化 CAD
K151 电路资料 官网公开 CoreS3 主机 7 页 PDF、Adapter、Power、Ring、Touch,后四份各 1 页 可读电路,不等于可编辑 PCB、布局布线、贴片 BOM/CPL 或生产测试规范。已确认文件可解析,未做电气审查;官网 PDF 的再分发许可未确认
社区结构 case/v1/、case/case_SG90、case/case_SCS0009、case/case_RS30X 含 STL/STEP;case/README.md 说明 STEP 可编辑,旧版和 v1 分不同舵机/板卡 对自行设计结构更有价值,但不是 K151 等尺寸替代件。先固定一套板卡/舵机组合。结构版本与 CAD
社区电路 schematics/m5-pantilt/ 有 .kicad_pcb、.kicad_sch、.kicad_pro、STEP、m5-pantilt-all-pos.csv,gerber/ 有丝印和钻孔文件 有可编辑工程和放置坐标,仍须重新出制造文件与核实器件。不能称已有完整现成量产包,README 部件清单仍写 under construction。社区电路工程树、部件清单与制造说明
可编程表达工具 社区 web/editor、web/face-editor、web/simulator、web/mod-gallery 和固件 MOD 接口 浏览器体验、模拟与 MOD 管理有可复用价值。本次主要核文件树及固件组合接口,没有构建 Web 工具或运行模拟器。浏览器工具入口

逐路径许可与保留义务

以下是代码/文件中能直接确认的标识和适用范围,不是全部分发制品的合规结论。模型权重、声音、图片、字体、商标及依赖须单独盘点。

路径/资产 已确认的许可证据 边界
M5 firmware/ 自有代码 固件 MIT,检查的入口、HAL、表达文件也有 MIT SPDX 保留版权与许可声明。链接的 ESP-IDF、模型/唤醒资源及外部组件不由此覆盖
M5 server/ 自有代码 服务端 MIT,登录、路由、小智集成文件有 MIT SPDX go.mod/go.sum 依赖逐项检查。API 凭据与第三方服务使用权不是代码许可授予
M5 app/lib、pubspec 检查的 Dart 文件与 pubspec.yaml 带 MIT SPDX,App README 使用 MIT 徽章。App 文件声明、App 清单和依赖 不用 README 徽章推断全部二进制素材、3D 模型、字体、图标和 Flutter 插件许可。ffmpeg_kit_flutter_new、OpenCV、ML Kit 等需要按实际解析版本及构建选项单独复核
工厂内嵌 FTServo、BMI270 FTServo MIT;BMI270 有独立 LICENSE 不把厂商驱动混为 M5 自有代码。BMI270 本次仅定位许可文件,不作全部条款结论
固定小智 v2.2.4 自有代码 小智 MIT repos.json 不是完整 SBOM。模型、唤醒词、语音音色和服务另核;不得把服务可调用当成模型权重开放
原社区自有文件 社区 Apache-2.0,README 声明仓库资源适用 保留 NOTICE/来源和修改说明等适用义务;Apache 商标条款不授予品牌使用权
社区实时会话依赖 模块依赖许可声明 指出 Moddable runtime 主要 LGPL-3.0-or-later、工具 GPL-3.0-or-later、esp_peer/av_render 为 Espressif Modified MIT 本次核到模块作者的逐项说明,未重新审计全部外部 SDK。尤其不能把 Espressif 平台限制抹平成普通 MIT,跨芯片前先核依赖原件
社区字体和本地 TTS StackchanCJK-Regular.LICENSE.txt 为 SIL OFL,vendor/stackchan-voice/LICENSE 为 Apache-2.0,树中另有 NOTICE 与 UniDic BSD 文件 代码许可不统一覆盖字库/词典。字体 OFL、本地语音代码许可
K151 仓库 STL M5_Hardware 根 MIT,固定 K151 子树未发现覆盖性独立 LICENSE 根许可证作为现有授权依据保留,不外推至官网 PDF、商标或第三方结构。实际商业分发前确认相关结构的完整授权范围

最小复用验证与验收

已完成的验证是静态源码契约检查,不安装依赖、不执行上游脚本、不访问生产设备或模型。在 Windows、Python 3.13.9 上运行自写 verify_sources.py,15 项检查全部 PASS。检查读取的工厂文件逐一对照固定 Git tree 的 blob SHA-1,随后核对 App 与固件的 25 个消息码、20 字节包头、8/4/2 字节字段偏移、保留码排除、长度拒绝与目标 MAC 校验。它还验证了两个独立服务配置、小智双凭据依赖、工厂绑定补丁和 K151 子树类型。加入故意改变消息码集合的反例,确认比较能发现不一致。

验证脚本:verify_sources.py(研究底稿,未随本专区发布)。结果:verification-result.json(研究底稿,未随本专区发布)。从项目根目录重跑:

python "研究底稿(未随网页发布)"

临时源码为有选择的只读下载,不是完整可构建 checkout。树快照和固定 commit 可用于重新取得完整源码。初始检索、下载程序和元数据均在同一临时目录,正式汇总资产位于 stackchan-assets.json。

后续最小步骤 可测验收项 当前状态
在隔离目录取得固定 commit、固定依赖与 license 清单 HEAD 正确,清单能解析,必需依赖/资产齐备,构建记录含实际 SDK 和锁文件 本次仅取得源码文本与树,未完整构建
先编译现有 firmware/tests 纯运动测试 中心/边界/超界夹取及三个空间轴方向断言通过,角度单位明确 已读测试,未运行。当前 PATH 未发现 C++ 编译器/CMake,未安装
构建无云的表达演示并接真机 按 neutral→listening→speaking→idle 序列,嘴部/灯光/动作准确退出,未知情绪回 neutral,舵机在安全范围且能复位 未烧录,需硬件
为 LAN 编解码补运行时跨语言测试 正常帧字节一致;截断、超长、未知 type、错误 MAC、过期会话拒绝;断网和 App 后台后不残留动作 当前仅有静态字段一致性,未执行 C++/Dart codec
选择一个自建路径:保留小智或替换语音后端 切换业务 URL 后所有目标请求指向预期服务;OTA/NVS/小智 API 不遗漏;无凭据时明示失败;旧绑定不串用户 未运行云集成,未索要生产凭据
打印/改版前核机械和电路 CAD 尺寸、轴心、螺丝、走线、限位和舵机温升实测;制造输出包含可检查的 BOM、PCB 和装配资料 未打印,未做电气/可靠性验证

不建议直接照搬的部分是 HTTP/WS 默认组合、将握手认证误作全流量加密、默认舵机校准数值、随机口型当作精准同步、以及把空配置 Go 后端当成即开即用的自主 AI 服务。上述建议均来自已读边界,不表示本报告完成了漏洞审计或评估全部产品功能。

参考资料与可追溯记录

正文源码链接均固定到本报告表中的 commit 和对应行号。GitHub 目录类链接固定 commit,二进制 STL 和目录没有伪造行号。资料责任方分别为 M5Stack、Stack-chan 社区和 XiaoZhi 项目维护者,源码范围与限制见“版本、新旧与证据深度”。

较新的 StackChan 下游实现及其与官方栈的连接边界,见 StackChan 应用复用案例。该补充独立记录 Yuki、Dotty 的实际接入和验证范围。

未运行完整固件/App/服务端构建、硬件、云账号或模型推理,也未上传飞书或发布网站。当前结论足以选择和拆分可复用模块,不能作为整机可交付或可量产证明。

补充 host 编译复核

独立复核在本机定位到 MSVC 19.51.36256 x64,原样编译 motion_math.cpp 与 motion_math_test.cpp。编译缺少 Windows SDK/UCRT 的 crtdbg.h,退出码2,测试断言未执行。未安装编译器、未运行上游构建脚本,原始源码哈希保持一致。该结果属于环境阻断,不计为 C++ 编译通过或算法失败。

完整命令、编译器版本与输出记录(研究底稿,未随本专区发布)。