为什么Stack-chan的MOD更新这么快？Host/MOD分离式固件架构深度解析

• 嵌入式
• 物联网
• 智能硬件
• 机器人
• 硬件开发
• 前端
• AI 应用

Stack-chan 是一款基于 M5Stack 硬件、用 JavaScript 驱动的超可爱桌宠机器人。它的固件采用Host/MOD 分离式架构：Host（宿主固件）负责系统能力，MOD（用户应用）作为独立小程序运行在 Host 之上。正是这种分离设计，让 MOD 更新无需重新烧录整个固件，一条命令即可完成——这也是 Stack-chan 生态中 MOD 迭代速度远超传统嵌入式项目的根本原因。

🧩 核心概念：Host 与 MOD 各管什么？

可以把 Stack-chan 的固件想象成一台"微型操作系统 + 应用商店"：

Host 的代码集中在 firmware/host/，内部按app/、modules/、platforms/三层组织：

• app/：启动流程与默认行为，入口是 firmware/host/app/main.ts
• modules/：音频、摄像头、运动、连接、UI、输入等能力模块
• platforms/：针对不同硬件（M5StackChan CoreS3、Stack-chan RT、Core2 + SG90 等）的平台适配

MOD 的源码则独立放在 firmware/mods/ 目录下，示例 MOD 可以在 firmware/mods/examples/ 中按功能学习。

⚡ 关键机制：MOD 如何"替换"默认行为？

Host 启动时会检查是否存在已安装的 MOD 模块。核心逻辑在 firmware/host/app/app-behavior-resolver.ts 中：

• 如果检测到mod模块，就加载 MOD 提供的行为，并只覆盖它明确定义的属性，其余沿用默认行为；
• 如果 MOD 加载失败或不存在，则回退到 Host 的默认行为（default-behavior/）。

这意味着安装一个 MOD，就相当于让 Host"换个玩法"，而 Host 本身一行代码都不用动。运行时模型在 firmware/mods/README.md 中有完整说明。

🚀 MOD 更新为什么快？—— 直写 xs 分区

传统嵌入式开发中，改一个功能往往要重新编译整个固件、全量烧录，动辄几分钟到十几分钟。Stack-chan 的做法完全不同：

1. MOD 被编译成一个XS 归档文件（.xsa），本质是 Moddable 运行时可执行的压缩包；
2. 构建脚本 firmware/scripts/lib/mod-flash.mjs 自动从设备分区表中发现 xs 分区的真实偏移（而不是硬编码）；
3. 通过esptool只把 .xsa 写进这个分区，Host 完全不受影响。

整个过程只需一条命令（在firmware目录下执行）：

npm run mod -- mods/examples/look_around/manifest.json

写入前还有严格的安全校验：firmware/host/app/mod-installer.ts 会验证 XSA 文件头、版本号是否在兼容范围内、大小是否超出分区容量，写完后还逐块回读比对，确保刷入成功。

也就是说：改一个 MOD = 几秒级的增量更新，而不是分钟级的全量重刷。这是"更新快"最直接的答案。

🎯 Capability API：MOD 只依赖"能力"，不依赖实现

MOD 开发时拿到的不是底层驱动，而是一个StackchanContext 能力对象，它按命名空间暴露能力，如：

• context.motion.lookAt(...)—— 转头看向某坐标
• context.audio.say(...)—— 播放语音
• context.face.setEmotion(...)—— 切换表情
• context.ui.showBalloon(...)—— 显示对话气泡
• context.input.touch、context.camera.capture(...)、context.connectivity.localPeer等

这些类型定义见 firmware/host/app/capabilities.ts，API 文档见 firmware/docs/api.md。

以官方的 look_around 示例 MOD 为例，整个 MOD 只有几十行 JavaScript：监听按钮事件、每隔 5 秒随机选一个坐标让 Stack-chan 转头。它完全没有触碰任何伺服驱动细节——那些都被封装在 Host 的motion模块内部。

这带来的好处是双向的：硬件驱动升级、屏幕 UI 改版、新增语音引擎，都不需要 MOD 作者跟着改代码。

🛡️ 兼容性保障：API 世代与能力预检

"更新快"不能以"乱刷"为代价。Stack-chan 用两层机制保证 MOD 与 Host 匹配：

1. API 世代标识：Host 固件版本中内嵌+stackchan.N后缀（例如9.0.0+stackchan.1），表示 host API 的第几代。要求新能力的 MOD 无法写入旧世代 Host，系统会提示用户先升级固件；
2. capabilities 预检：发布到 MOD Gallery 的 MOD 会声明所需能力，安装前自动对照目标芯片与当前 Host 的 API 世代进行校验。

MOD 的元数据格式由 docs/specs/stackchan-mod.md 规范，机器校验则使用 docs/specs/stackchan-mod.schema.json。更多架构演进背景可参考 docs/architecture/firmware-rearchitecture_ja.md 中的目标目录结构。

🌐 浏览器工具链：不装本地环境也能开发

MOD 生态快，还得益于 Web 工具链把开发门槛压到了极低。整套工具（固件安装器、MOD Gallery、积木编辑器、模拟器）都可直接在浏览器使用：

• 固件安装器：用数据线连接设备，在浏览器中直接刷入 Host 固件（见 firmware/docs/flashing-firmware-web.md）；
• MOD Gallery：按名称或能力搜索 MOD，自动完成兼容性检查后安装到设备；
• 积木编辑器：用 Blockly 可视化拼出行为，浏览器内构建 MOD 并在 WASM 模拟器里先跑一遍，再推送到真机。

浏览器侧的构建与刷写逻辑（如 MOD 打包、XSA 版本兼容判断）分别在 web/editor/mod-builder.mjs 与 web/editor/xs-compatibility.mjs 中实现，与设备端npm run mod走的是同一套兼容标准。

📌 总结：快在哪里？

一句话概括：Host 做稳，MOD 做快。系统层的能力沉淀在 Host 里长期维护，玩法层的创新则以几秒级的更新频率持续流入设备——这就是 Stack-chan 的 MOD 能保持高频更新的答案。想动手试试，可以从 firmware/mods/README.md 和官方示例 firmware/mods/examples/look_around/ 开始。

• 嵌入式
• 物联网
• 智能硬件
• 机器人
• 硬件开发
• 前端
• AI 应用