> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

# 结论与适用范围

**优先复用 M5Stack 2026 年工厂栈中的表达层、舵机抽象和设备通信协议，再决定是否保留其 App、账号和小智云链路。** 它已公开设备 C++ 固件、Flutter App 和 Go 后端，适合作为小型桌面表达终端的工程起点。核心可取资产是 `stackchan/avatar`、`stackchan/modifiers`、`stackchan/motion` 和端到端消息格式，不是一个已完成自主账号、模型服务和量产验证的整机方案。实际入口见 [工厂启动链](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/main.cpp#L16-L62)、[表情与状态桥接](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/board/stackchan_display.cc#L321-L378)。

本报告供桌面智能硬件技术选型与原型开发使用，围绕“能拿哪些代码、如何换后端、哪些结构可改、复用前还缺什么”展开。信息截止与访问日期均为 **2026-10-27**。工厂栈为主，原社区栈和 K151 硬件作为同一重点内的对照。已有广域研究只提供定位，本报告重新核验了当前分支和文件，不以旧报告的 commit 代替最新源码。

**最重要的三个边界：**

- 工厂的说话口型由 180 ms 周期和随机嘴部权重驱动，只是状态表达，不是 PCM、音素或 viseme 同步。精细口型需要改造 [SpeakingModifier](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/modifiers/speaking.h#L17-L82)
- 自建 Go 后端后仍有远端账号服务、小智开发者凭据、激活授权、OTA 发现和 App 直连小智的依赖。仅改固件 `STACKCHAN_SERVER_URL` 不能获得完全自主的 AI 服务 [两个独立服务配置](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/Kconfig.projbuild#L1-L20)、[小智 API 常量](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/xiaozhi/xiaozhi.go#L42-L55)
- K151 GitHub 目录有 10 个 STL，官网另有原理图 PDF。尚未在核验范围内找到 K151 的 PCB 原生工程、制造 BOM 或 STEP 参数化结构，不应据此宣称能完整复刻量产 [K151 固定结构目录](https://github.com/m5stack/M5_Hardware/tree/e29c139cbc7c80b5ccc5557e5ab8025a7a19a109/Products/K151_StackChan/Structures)、[官方原理图入口](https://docs.m5stack.com/en/StackChan)

# 版本、新旧与证据深度

| **对象** | **仓库创建时间 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](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/pubspec.yaml#L1-L47)、[固件版本与本地配置覆盖](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/CMakeLists.txt#L1-L22)、[依赖固定清单](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/repos.json#L1-L32)、[社区 v2.0.1 发布](https://github.com/stack-chan/stack-chan/releases/tag/v2.0.1)。仓库创建时间来自 GitHub 仓库元数据，它不等于产品首次销售日期。

**未确认源码与发行二进制是否同步。** 官方恢复流程让用户通过 M5Burner 获取最新固件，但所读页面未给出可与 `1.6.0` 对应的二进制 commit 或可重现构建证明。也未安装 App Store/Play 商店版本。不能把提交消息“prepare 1.2.8 release for open source”当成商店已发布证明。[工厂固件恢复说明](https://docs.m5stack.com/en/StackChan)

| **阅读层次** | **本次覆盖** | **未据此声称的能力** |
|---|---|---|
| 实际代码，针对性深入 | 工厂 `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 表达终端 源码研究 图示](<../diagrams/StackChan%20%E8%A1%A8%E8%BE%BE%E7%BB%88%E7%AB%AF%20%E6%BA%90%E7%A0%81%E7%A0%94%E7%A9%B6%201.png>)

```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 包格式与引导依赖](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/network/local_area_network_service.dart#L34-L109)

| **层/路径** | **代码中的实际行为** | **可直接复用与改造点** |
|---|---|---|
| `firmware/main/main.cpp` 与 `hal/hal.cpp` | NVS、板级、小智 MCP、触摸、扩展 IO、RTC、IMU、舵机、LVGL 初始化。可跳过 Mooncake 直接进入 AI，或安装应用后等待 AI 启动请求，退出 UI 框架再进入小智主循环 | 复用 HAL 分层和显式模式切换。平台更换时保留 NVS 错误恢复和外设顺序，重新验证 UI/AI 切换资源生命周期。[HAL 初始化](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal.cpp#L23-L43)、[入口与应用清理](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/main.cpp#L16-L62) |
| `stackchan/avatar`、`stackchan/modifiers`、`board/stackchan_display.cc` | LVGL 创建默认脸，挂接呼吸、眨眼、摸头、IMU Modifier。情绪字符串映射为本地枚举，未知值落 Neutral。STANDBY 启动 idle，LISTENING 关嘴，SPEAKING 挂接嘴部动画 | 适合先独立抽出表达终端。将模型输出收敛为受限情绪/动作事件。口型改为播放时钟或能量驱动后，再评估音素同步。[UI 和 Modifier](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/board/stackchan_display.cc#L233-L273)、[状态转换](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/board/stackchan_display.cc#L480-L568) |
| `stackchan/motion`、`hal_servo.cpp` | 两个反馈串口舵机，UART1 1 Mbps，ID 1/2。使用 NVS 零位、原始位置范围、角度限位和俯仰堵转保护。角度以十分之一度传递 | 可复用运动接口、归一化视线转换和限位思路。新电机/结构必须改零位、比例、限位和堵转参数。代码俯仰限位 30..870 即 3..87°，官网建议 5..85°，原型先按更窄机械范围验证。[校准与位置映射](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_servo.cpp#L45-L100)、[硬件参数](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_servo.cpp#L331-L360)、[官方机械范围提醒](https://docs.m5stack.com/en/StackChan) |
| `motion_math.cpp` | 归一化输入夹到 [-1,1] 后线性映射，空间点用 atan2 求 yaw/pitch，输出十分之一度 | 适合作为无硬件首个模块。已有 host test 覆盖中心、上下限、越界与空间方向。未运行该 C++ 测试。[运动纯函数](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/stackchan/motion/motion_math.cpp#L16-L59)、[现有运动测试](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/tests/motion_math_test.cpp#L32-L58) |
| 小智 `application.cc` 与 `audio_service.cc` | Application 收发音频队列，接收 tts start/stop、stt、llm emotion 等消息，驱动 Listening/Speaking/Idle；语音网络、唤醒、编码与播放由小智依赖承载 | 可复用事件桥接，不能仅搬表情类就声称完成语音链路。模型、ASR/TTS 服务及声学调优另行选型。[音频及 JSON 事件](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/main/application.cc#L498-L565)、[设备状态行为](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/main/application.cc#L856-L923) |
| `hal/audio.cpp` | 提供 3 秒麦克风录制回放及波形采样，内存分配失败、无采样、编解码器不存在时返回失败 | 可保留为板级自测入口，硬件到位后验证双麦与扬声器路径。不能以代码存在代替 AEC、识别率或回声测试。[麦克风自测](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/audio.cpp#L19-L114) |

这里的 AI 主循环来自固定小智依赖，再由工厂补丁修改，不能把 upstream v2.2.4 与工厂编译产物视为字节一致。[小智固定与 patch](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/repos.json#L17-L22)

# App、认证、OTA 与自建后端

| **环节** | **已读代码事实** | **自建时必须处理** |
|---|---|---|
| 配网 | App 构造 `setWifi` JSON，含 ssid/password 和频段提示。固件验证两个字段为字符串，进入连接状态，成功/失败通过 BLE 通知，且支持分包与连接失败原因 | 保留字段、分包上限、超时和重试策略。手机权限、2.4 GHz、凭据存储与 BLE 安全需要实机验证。[App 发配网数据](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/view/popup/device_wifi_config.dart#L487-L542)、[固件接收与状态回报](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ble.cpp#L455-L566) |
| App 后端地址 | `urls.dart` 是编译进 App 的占位地址，并分别拼 `http://`、`ws://`。README 的 `.env` 建议不等于所读实现自动加载 `.env` | 修改实际代码并重新构建 App，配置 HTTPS/WSS 和证书策略，不要仅修改 README 或新增未读取的环境文件。[实际 URL 组合](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/network/urls.dart#L15-L49) |
| 用户身份 | Go `Login` 先调 `m5stack.loginUrl`，成功后保存用户并签发本地 JWT；注册另需远端注册/用户名查询地址和凭据。V2 中间件校验 token | 保留兼容账号系统或自行替换身份适配层，不能把 MySQL 中的用户表理解为独立账号系统。[登录到远端](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/service/user.go#L27-L66)、[注册到远端](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/service/user.go#L149-L198)、[V2 token 校验](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/middleware/middleware.go#L40-L91) |
| 小智授权 | Go 将 baseUrl 固定为 `https://xiaozhi.me/`，需要 `xiaozhi.secret_key` 和 `generate_license_token`，App 的小智工具也直接设此域名 | 若保留小智，先取得合法可用的开发者/激活凭据；若完全自建，重写这一服务适配及 App 相应 API，不只是代理一个域名。[API 与鉴权入口](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/xiaozhi/xiaozhi.go#L42-L96)、[License 凭据](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/xiaozhi/xiaozhi.go#L307-L320)、[开发者 token](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/xiaozhi/xiaozhi.go#L585-L606)、[App 直连](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/util/xiao_zhi_util.dart#L25-L40) |
| 绑定互通 | 工厂 patch 丢弃社区 activation code/message，改成 `requires_app_binding_`。官方说明 StackChan World 与其他小智绑定体系不互通 | 自建要定义激活、绑定、解绑和用户归属协议，并重做相关 UI。换固件前按官方流程解绑，不能当作无损切换。[工厂激活改造](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/patches/xiaozhi-esp32.patch#L358-L415)、[官方小智绑定说明](https://docs.m5stack.com/en/StackChan) |
| OTA 与端点发现 | 固件 StackChan 业务地址和 `OTA_URL` 是两个配置。小智 OTA 读取 NVS `ota_url` 或默认值，返回 websocket/mqtt 配置及固件 URL/version。工厂升级函数查版本、升级并重启 | 自建需要实现兼容响应或替换 OTA 客户端，维护签名/验证、回滚和版本策略。还要检查既有 NVS 是否覆盖新的编译默认值。[业务服务和 OTA 配置](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/Kconfig.projbuild#L1-L20)、[NVS URL 覆盖](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/main/ota.cc#L46-L53)、[端点配置解析](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/main/ota.cc#L146-L185)、[升级流程](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/hal_ota.cpp#L14-L75) |
| Go 服务 | GoFrame HTTP 路由、MySQL 数据、JWT、文件服务和 WebSocket 转发。App V2、设备旧接口、admin 使用不同中间件。默认配置中 DB/JWT/RSA/小智字段留空 | 配齐部署参数和权限边界，再测 API 契约。服务自身不是 ASR/LLM/TTS 推理实现。[HTTP 路由](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/internal/cmd/cmd.go#L38-L81)、[待填配置](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/manifest/config/config.yaml#L17-L41) |
| LAN 媒体/动作 | 手机发布 WebSocket，固件收 `AppLanAddress` 后连接。20 字节包头，SC magic/version/type/session/seq/length；校验长度、类型、目标 MAC | 可作为本地表达控制协议起点，但应把首次发现、认证和加密纳入独立设计。现有 RSA 握手不对后续 payload 加密。[LAN 编解码](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/utils/local_network/local_network_protocol.h#L17-L89)、[LAN 身份校验](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/network/local_area_network_service.dart#L352-L405) |

**最小自主原型建议：**先把表情、动作和设备控制保留在 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+ 是较宽说明，不能作为可靠构建锁。[固件构建要求](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/README.md#L2-L27)、[固定固件依赖](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/repos.json#L1-L32)、[App 构建清单](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/pubspec.yaml#L7-L48)、[Go 版本](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/go.mod#L1-L10)

# 社区栈与硬件开放深度

原社区栈不是工厂 C++ 栈的可互换版本。它使用 JavaScript/TypeScript、Moddable/Piu、MOD 扩展和浏览器工具，当前同样以 M5StackChan CoreS3 为标准配置。`main.ts` 先加载行为与偏好、启动网络服务、再构造运行上下文，并提供连接失败后的 retry/offline 分支。组合根登记多种舵机和 TTS 实现，面部状态有独立的眼睛、嘴、呼吸、情绪、主题对象。适合行为脚本和可定制表达研究，刷入会替换工厂固件。[社区范围与刷机边界](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/README.md#L10-L38)、[社区启动和离线选择](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/host/app/main.ts#L67-L150)、[驱动与 TTS 组合](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/host/app/compose.ts#L128-L165)、[面部状态](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/host/modules/ui/state/face-state.ts#L1-L84)

| **资产** | **公开深度与具体路径** | **复用判断** |
|---|---|---|
| K151 结构 | `Products/K151_StackChan/Structures/`：Base、BaseCover、BearingFixture、LightGuideBar-A/B、MainBody、ServoArm、ServoBody、ServoCover、ServoSideCover 共 10 个 `.stl`。[固定结构树](https://github.com/m5stack/M5_Hardware/tree/e29c139cbc7c80b5ccc5557e5ab8025a7a19a109/Products/K151_StackChan/Structures) | 可用于空间参考和打印试装。仅核目录，未打印/量测。未见此 SKU 的 STEP、原生参数化 CAD |
| K151 电路资料 | 官网公开 [CoreS3 主机 7 页 PDF](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/490/Sch_M5_CoreS3_v1.0.pdf)、[Adapter](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/SCH_Adapter.pdf)、[Power](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/SCH_Power.pdf)、[Ring](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/SCH_Ring.pdf)、[Touch](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/SCH_Touch.pdf)，后四份各 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](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/case/README.md#L8-L29) |
| 社区电路 | `schematics/m5-pantilt/` 有 `.kicad_pcb`、`.kicad_sch`、`.kicad_pro`、STEP、`m5-pantilt-all-pos.csv`，`gerber/` 有丝印和钻孔文件 | 有可编辑工程和放置坐标，仍须重新出制造文件与核实器件。不能称已有完整现成量产包，README 部件清单仍写 under construction。[社区电路工程树](https://github.com/stack-chan/stack-chan/tree/373fad66cec9af4ee5c9a3643fc8832a4014c642/schematics/m5-pantilt)、[部件清单与制造说明](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/schematics/README.md#L19-L54) |
| 可编程表达工具 | 社区 `web/editor`、`web/face-editor`、`web/simulator`、`web/mod-gallery` 和固件 MOD 接口 | 浏览器体验、模拟与 MOD 管理有可复用价值。本次主要核文件树及固件组合接口，没有构建 Web 工具或运行模拟器。[浏览器工具入口](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/README.md#L51-L71) |

# 逐路径许可与保留义务

以下是代码/文件中能直接确认的标识和适用范围，不是全部分发制品的合规结论。模型权重、声音、图片、字体、商标及依赖须单独盘点。

| **路径/资产** | **已确认的许可证据** | **边界** |
|---|---|---|
| M5 `firmware/` 自有代码 | [固件 MIT](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/LICENSE#L1-L21)，检查的入口、HAL、表达文件也有 MIT SPDX | 保留版权与许可声明。链接的 ESP-IDF、模型/唤醒资源及外部组件不由此覆盖 |
| M5 `server/` 自有代码 | [服务端 MIT](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/server/LICENSE#L1-L21)，登录、路由、小智集成文件有 MIT SPDX | `go.mod/go.sum` 依赖逐项检查。API 凭据与第三方服务使用权不是代码许可授予 |
| M5 `app/lib`、pubspec | 检查的 Dart 文件与 `pubspec.yaml` 带 MIT SPDX，App README 使用 MIT 徽章。[App 文件声明](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/lib/network/urls.dart#L1-L4)、[App 清单和依赖](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/app/pubspec.yaml#L1-L47) | 不用 README 徽章推断全部二进制素材、3D 模型、字体、图标和 Flutter 插件许可。`ffmpeg_kit_flutter_new`、OpenCV、ML Kit 等需要按实际解析版本及构建选项单独复核 |
| 工厂内嵌 FTServo、BMI270 | [FTServo MIT](https://github.com/m5stack/StackChan/blob/eff0d6b5109663faec8f1d98848b4b0e5246bbfc/firmware/main/hal/drivers/FTServo_Arduino/LICENSE#L1-L21)；BMI270 有独立 LICENSE | 不把厂商驱动混为 M5 自有代码。BMI270 本次仅定位许可文件，不作全部条款结论 |
| 固定小智 v2.2.4 自有代码 | [小智 MIT](https://github.com/78/xiaozhi-esp32/blob/e77dedb1309153bb63fed285772962c920c97dd4/LICENSE#L1-L22) | `repos.json` 不是完整 SBOM。模型、唤醒词、语音音色和服务另核；不得把服务可调用当成模型权重开放 |
| 原社区自有文件 | [社区 Apache-2.0](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/LICENSE#L1-L201)，README 声明仓库资源适用 | 保留 NOTICE/来源和修改说明等适用义务；Apache 商标条款不授予品牌使用权 |
| 社区实时会话依赖 | [模块依赖许可声明](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/host/modules/realtime-conversation/LICENSES.md#L13-L24) 指出 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](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/host/modules/ui/assets/fonts/StackchanCJK-Regular.LICENSE.txt#L1-L5)、[本地语音代码许可](https://github.com/stack-chan/stack-chan/blob/373fad66cec9af4ee5c9a3643fc8832a4014c642/firmware/vendor/stackchan-voice/LICENSE#L1-L16) |
| K151 仓库 STL | [M5_Hardware 根 MIT](https://github.com/m5stack/M5_Hardware/blob/e29c139cbc7c80b5ccc5557e5ab8025a7a19a109/LICENSE#L1-L21)，固定 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（研究底稿，未随本专区发布）。从项目根目录重跑：

```powershell
python "研究底稿（未随网页发布）"
```

临时源码为有选择的只读下载，不是完整可构建 checkout。树快照和固定 commit 可用于重新取得完整源码。初始检索、下载程序和元数据均在同一临时目录，正式汇总资产位于 [stackchan-assets.json](<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 工厂固定提交](https://github.com/m5stack/StackChan/commit/eff0d6b5109663faec8f1d98848b4b0e5246bbfc)：2026-10-22，App 1.2.8 开源准备；用于定位本报告工厂代码基线
- [社区固定提交](https://github.com/stack-chan/stack-chan/commit/373fad66cec9af4ee5c9a3643fc8832a4014c642)：2026-10-25，依赖安全修补及 CI；不能据此称社区为 2026 年新项目
- [M5_Hardware 固定提交](https://github.com/m5stack/M5_Hardware/commit/e29c139cbc7c80b5ccc5557e5ab8025a7a19a109)：2026-10-23，全仓快照；当前提交不是 K151 更新证据
- [M5Stack StackChan 产品与工厂说明](https://docs.m5stack.com/en/StackChan)：滚动文档，访问 2026-10-27；仅用于硬件入口、绑定与恢复边界，未替代源码机制分析
- 本地 `factory-metadata.json`、`community-metadata.json`、`hardware-metadata.json`：GitHub REST 元数据、release/tag 原始返回，访问 2026-10-27；`*-tree.json` 记录完整未截断的固定版本文件清单

较新的 StackChan 下游实现及其与官方栈的连接边界，见 [StackChan 应用复用案例](<StackChan%20%E5%BA%94%E7%94%A8%E5%A4%8D%E7%94%A8%E6%A1%88%E4%BE%8B.md>)。该补充独立记录 Yuki、Dotty 的实际接入和验证范围。

未运行完整固件/App/服务端构建、硬件、云账号或模型推理，也未上传飞书或发布网站。当前结论足以选择和拆分可复用模块，不能作为整机可交付或可量产证明。


# 补充 host 编译复核

独立复核在本机定位到 MSVC 19.51.36256 x64，原样编译 `motion_math.cpp` 与 `motion_math_test.cpp`。编译缺少 Windows SDK/UCRT 的 `crtdbg.h`，退出码2，测试断言未执行。未安装编译器、未运行上游构建脚本，原始源码哈希保持一致。该结果属于环境阻断，不计为 C++ 编译通过或算法失败。

完整命令、编译器版本与输出记录（研究底稿，未随本专区发布）。
