结论与适用范围
优先复用 M5Stack 2026 年工厂栈中的表达层、舵机抽象和设备通信协议,再决定是否保留其 App、账号和小智云链路。 它已公开设备 C++ 固件、Flutter App 和 Go 后端,适合作为小型桌面表达终端的工程起点。核心可取资产是 stackchan/avatar、stackchan/modifiers、stackchan/motion 和端到端消息格式,不是一个已完成自主账号、模型服务和量产验证的整机方案。实际入口见 工厂启动链、表情与状态桥接。
本报告供桌面智能硬件技术选型与原型开发使用,围绕“能拿哪些代码、如何换后端、哪些结构可改、复用前还缺什么”展开。信息截止与访问日期均为 2026-10-27。工厂栈为主,原社区栈和 K151 硬件作为同一重点内的对照。已有广域研究只提供定位,本报告重新核验了当前分支和文件,不以旧报告的 commit 代替最新源码。
最重要的三个边界:
- 工厂的说话口型由 180 ms 周期和随机嘴部权重驱动,只是状态表达,不是 PCM、音素或 viseme 同步。精细口型需要改造 SpeakingModifier
- 自建 Go 后端后仍有远端账号服务、小智开发者凭据、激活授权、OTA 发现和 App 直连小智的依赖。仅改固件
STACKCHAN_SERVER_URL不能获得完全自主的 AI 服务 两个独立服务配置、小智 API 常量 - K151 GitHub 目录有 10 个 STL,官网另有原理图 PDF。尚未在核验范围内找到 K151 的 PCB 原生工程、制造 BOM 或 STEP 参数化结构,不应据此宣称能完整复刻量产 K151 固定结构目录、官方原理图入口
版本、新旧与证据深度
| 对象 | 仓库创建时间 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 | 编译通过、硬件烧录、音质/时延/功耗/寿命、账号服务可用 |
工厂栈的执行链与可复用模块

查看 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 项目维护者,源码范围与限制见“版本、新旧与证据深度”。
- M5 工厂固定提交:2026-10-22,App 1.2.8 开源准备;用于定位本报告工厂代码基线
- 社区固定提交:2026-10-25,依赖安全修补及 CI;不能据此称社区为 2026 年新项目
- M5_Hardware 固定提交:2026-10-23,全仓快照;当前提交不是 K151 更新证据
- M5Stack StackChan 产品与工厂说明:滚动文档,访问 2026-10-27;仅用于硬件入口、绑定与恢复边界,未替代源码机制分析
- 本地
factory-metadata.json、community-metadata.json、hardware-metadata.json:GitHub REST 元数据、release/tag 原始返回,访问 2026-10-27;*-tree.json记录完整未截断的固定版本文件清单
较新的 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++ 编译通过或算法失败。
完整命令、编译器版本与输出记录(研究底稿,未随本专区发布)。