本文将介绍全新 ESP-Brookesia v0.7 架构，从 Utils、HAL、General Service 到 AI Agent 与 AI Expression，本文将系统阐述这些模块如何协同工作，并通过两个示例帮助开发者快速理解如何基于该框架构建 AIoT 交互产品。

为什么 ESP-Brookesia 需要全新架构

ESP-Brookesia 面向具备丰富人机交互需求的 AIoT 设备。在实际应用中，这意味着框架需要同时处理硬件差异、提供 Wi-Fi、音频、视频、存储等系统级能力，并以一致的方式将这些能力连接到 AI Agent。

随着项目规模的扩大，对各类职责进行清晰边界划分变得愈发重要。v0.7 的重构将框架组织为分层架构，并定义了明确的扩展点，从而形成更易移植、更易扩展、也更易在不同 AI 交互产品中复用的结构。 

架构概览

ESP-Brookesia v0.7 构建于 ESP-IDF 之上，并通过 ESP Component Registry 分发。从底层依赖到面向应用的 AI 功能，全新架构构建了一套完整的 AIoT 产品开发技术栈。

从整体上看，该架构可划分为三个层级：

• 环境与依赖层：ESP-IDF 提供工具链、运行时与驱动基础，ESP Component Registry 负责组件打包与依赖管理。
• 服务与框架层：Utils、HAL、General Service、AI Agent 与 AI Expression 构成框架核心模块。
• 应用层：产品应用与参考项目基于上述可复用模块构建。

此次重构带来了多项实际改进：

• 职责划分更加清晰：工具类代码、硬件抽象、系统服务与 AI 逻辑不再混杂
• 更易进行开发板适配：HAL 接口与板级配置简化多硬件目标支持
• 更强的复用能力：服务以函数与事件统一暴露，适用于本地调用、远程 RPC 与 MCP 工具
• 更完善的 AI 集成：Agent 通过更清晰、可扩展的模型接入系统服务与设备能力

框架核心模块

以下章节将逐一介绍 ESP-Brookesia 框架的核心模块。这些模块既各司其职，又形成内部依赖链：Utils 与 HAL 提供基础能力，General Service 构建其上，而 AI Agent 与 AI Expression 位于最上层。

Utils

Utils 模块为整个框架提供基础能力。其并非针对单一产品功能，而是汇集嵌入式开发中反复使用的通用构建模块。

主要组件包括：

• brookesia_lib_utils：通用工具库，包含插件机制、状态机、任务调度、线程配置与运行时性能分析
• brookesia_mcp_utils：MCP 工具集，用于将服务函数暴露为 MCP 工具

HAL

HAL 模块解决嵌入式开发中的核心问题：如何使上层模块摆脱对具体开发板的依赖。在 ESP-Brookesia v0.7 中，HAL 被拆分为三个协同部分：

• brookesia_hal_interface：定义标准化硬件接口，如音频、显示、触控与存储
• brookesia_hal_adaptor：实现这些接口，并执行与开发板相关的初始化
• brookesia_hal_boards：通过 YAML 配置描述板级拓扑、引脚与驱动参数

该结构使服务与应用仅依赖抽象接口，而开发板差异由适配器与配置层处理，对于需要支持多硬件平台的产品，可显著降低移植成本。

General Service

General Service 模块是可复用系统能力的统一运行时接口。服务框架采用 Manager + Helper 模型：

• brookesia_service_manager：负责服务插件生命周期管理、函数注册、事件分发、本地调用与远程 RPC
• brookesia_service_helper：为应用侧提供类型安全的函数调用与事件订阅接口

基于该框架，ESP-Brookesia 提供一系列开箱即用的服务：

• Wi-Fi：连接管理、扫描与 SoftAP 配网
• Audio：音频采集、播放及相关处理
• Video：视频编解码与显示能力
• NVS：非易失存储
• SNTP：网络时间同步
• Custom：轻量级自定义服务扩展机制

有关实现细节，请参阅 Service 应用开发指南。

AI Agent

AI Agent 模块提供统一的多 AI 后端管理模型。其设计并非面向单一服务提供商，而是支持多 Agent 集成、切换与生命周期管理。

当前实现包括：

• brookesia_agent_manager：负责 Agent 插件注册、基于状态机的生命周期管理（激活、启动、休眠、唤醒、停止）
• brookesia_agent_helper：提供类型安全的函数与事件交互接口

当前支持的 Agent 包括：扣子、OpenAI 与 XiaoZhi。

AI Expression

如果说 AI Agent 定义了设备“如何思考与行动”，那么 AI Expression 则定义设备“如何被用户感知”。

当前实现主要基于 brookesia_expression_emote，提供：

• 表情与动画资源管理
• 表达切换与动画播放控制
• 二维码显示与隐藏
• 事件消息的可视化呈现

该模块在语音助手、陪伴设备、桌面机器人及带屏 HMI 产品中尤为重要，使设备不仅能够响应，还能通过视觉方式表达状态与意图。

两个示例：架构的实际应用

为帮助开发者快速理解框架，ESP-Brookesia 提供了多个示例项目。以下两个示例尤其适合作为入门参考。

examples/service/console

examples/service/console 是一个基于串口控制台的交互式 CLI 示例，支持命令历史记录，非常适用于在早期集成阶段快速验证服务能力是否正确注册并正常工作。

该示例展示了新服务架构的重要特性：

• 通过命令行列出已注册服务、函数与事件
• 直接调用服务函数
• 订阅与取消订阅服务事件
• 启动 RPC 服务器并执行远程调用
• 查看内存与线程性能等运行时信息

在构建完整 UI 前，如需验证 Wi-Fi、音频、NVS 或自定义服务集成，该示例是最快的方式之一，可作为General Service 模块的实用调试入口。

来源：examples/service/console

examples/agent/chatbot

与 console 示例侧重框架验证不同，examples/agent/chatbot 更接近完整产品参考。该示例将 HAL、服务、Agent 与表达能力整合，构建了一个完整的 AI 语音交互设备。

其展示的典型能力包括：

• 唤醒词检测与语音对话
• 多 Agent 运行时切换
• 基于 AI 状态驱动的表情动画
• 基于手势的界面导航（表达界面与设置界面切换）
• 通过 MCP 工具直接控制硬件

最后一点尤为关键。在该示例中，Agent 不仅能够与用户对话，还可通过 MCP 调用设备能力，例如调节屏幕亮度、音量或静音。

这充分体现了该架构的核心价值：从 LLM 推理到 Agent 编排、服务调用再到硬件控制的一体化路径。

来源：examples/agent/chatbot

对产品开发的意义

通过 v0.7 架构重构，ESP-Brookesia 已不再只是可复用组件的集合，而是一个面向 AIoT 交互产品的结构化工程框架。

• 对平台开发者而言，HAL 模块隔离了开发板差异
• 对应用开发者而言，General Service 模块以统一接口暴露设备能力
• 对 AI 应用开发者而言，Function Calling 与 MCP 建立了 LLM 与设备能力之间的直接连接

这些模块共同构成了从硬件抽象、系统服务到 AI 编排与用户交互表达的端到端开发路径。

如果您希望进一步探索该框架，建议参考以下资源：

• ESP-Brookesia GitHub 仓库
• ESP-Brookesia 编程指南

乐鑫希望这一全新架构能够帮助开发者更便捷地扩展 ESP-Brookesia，构建新的服务、Agent 与应用模式，我们也期待来自开发者社区的反馈。