让小智AI支持运行时扩展（二）：配置驱动架构设计

倪思为

152人浏览 · 2026-06-07 18:00:06

倪思为 · 2026-06-07 18:00:06 发布

在上一篇，我们介绍了TF卡的挂载工作。ESP32设备已经能够访问TF卡中的配置文件：
/sdcard/ex_mcp.cfg
可以看到文件名称非常短小，使用的是早年间DOS系统下的 8.3 文件名称规范。这是由于ESP IDF架构为了减少对内存资源的消耗，默认是不开启长文件名支持的。

对于实际项目来说，其实更重要的问题是：
如何让设备在不修改固件、不重新编译、不重新烧录的情况下获得新的能力？
本文将介绍我们为小智AI设计的一套“配置驱动扩展架构”，实现通过TF卡配置文件动态扩展设备能力。

一、总体架构设计

整个运行时扩展系统的结构如下：

TF Card
│
└── ex_mcp.cfg
│
▼
SdExtensionManager
│
├── ParseExternalInitializers()
│
└── ParseMcpTools()

工作流程如下：

设备启动
│
▼
挂载TF卡
│
▼
读取配置文件
│
▼
解析JSON
│
▼
GPIO初始化
│
▼
MCP Tool注册

整个过程由 SdExtensionManager::LoadDynamicConfiguration() 负责完成。该函数的职责比较明晰，只做三件事：

1. 读取配置文件

2. 解析JSON结构

3. 分发给不同解析模块

二、配置文件结构设计

本项目采用JSON作为配置格式。示例配置文件如下：

{
    "board_name": "lonrock-esp32s3-audio",
    "l_code": "982002702",

    "gpio_initializers": [
        {
            "pin": 8,
            "mode": "output",
            "level": 1
        }
    ],

    "mcp_tools": [
        {
            "name": "sd.fan_switch",
            "description": "控制散热风扇",
            "pin": 7
        }
    ]
}

整体结构分为三部分：

合法性校验
gpio_initializers
mcp_tools

合法性校验

board_name 表明了当前设备的类型，l_code是我司为设备确定的唯一序列号。这些字段用来确认TF卡上的配置文件确实是为对应的设备所准备。
如果TF卡是为同一类型的设备准备，那么代码里就可以不校验l_code。
合法性校验还可以用其他方式，例如校验设备的MAC地址。

gpio_initializers

用于设备启动后的GPIO初始化。例如：

{
    "pin": 8,
    "mode": "output",
    "level": 1
}

对应：GPIO8，设置为输出模式，上电后置高电平

mcp_tools

用于动态注册MCP工具。例如：

{
    "name":"sd.fan_switch",
    "description":"控制散热风扇",
    "pin":7
}

启动后系统会自动生成对应的MCP 工具。
该工具的名称是sd.fan_switch，通过描述告诉大模型这个工具用来控制散热风扇的起停，我们在程序中会使用GPIO7来控制风扇起停。

三、为什么选择JSON

1. 可读性好，即使没有编程经验的用户也能快速理解：

{
    "pin": 8,
    "mode": "output"
}

2. 支持嵌套结构，例如：

{
    "gpio_initializers":[...],
    "mcp_tools":[...]
}

3. 小智代码已经有解析实例

小智代码中已经有非常成熟的使用cJSON解析JSON数据的功能模块，在解析服务器数据时尤其稳定，因此使用cJSON库来解析TF卡上的JSON文件非常方便。

四、JSON解析中的注意事项

虽然JSON解析本身并不复杂，但有几个细节必须注意。

检查节点是否存在

不要假设配置一定正确。必须对节点进行检查，否则可能导致运行异常。
代码示例：

cJSON* pin = cJSON_GetObjectItem(item, "pin");

if(pin == nullptr) {
    return;
}

检查数据类型

下面两种写法并不相同：

{
    "pin":5
}

和

{
    "pin":"5"
}

前者是数字。后者是字符串。因此解析前必须检查：

cJSON_IsNumber(pin)

避免错误配置导致系统异常。

释放JSON资源

这是C++/C的初学者最容易忽略的问题。如果不释放资源，系统内存被无谓占用，导致其他功能可以分配的内存减少，在ESP32这种资源有限的单片机上面，是非常大的损失。

释放资源只需要一条语句，把整个JSON的根节点释放即可：

cJSON* root =   cJSON_Parse(buffer);  // 获取根节点
if(root == nullptr) {
   return;
}
// 处理JSON内容

cJSON_Delete(root);  // 释放根节点

五、完整函数代码

// 头部需要引入cJSON库的头文件
#include "cJSON.h"

// JSON字段常量以及必要的常量
namespace
{
// String constants centralized here to ensure they reside in .rodata (flash)
// and to avoid per-translation-unit pointer objects which would consume RAM.
static const char MOUNT_POINT[] = "/sdcard";
static const char CONFIG_PATH[] = "/sdcard/ex_mcp.cfg";

static const char kJsonBoardName[] = "board_name";
static const char kJsonLCode[] = "l_code";

static const char kJsonGpioInitializers[] = "gpio_initializers";
static const char kJsonPin[] = "pin";
static const char kJsonMode[] = "mode";
static const char kJsonLevel[] = "level";
static const char kJsonPull[] = "pull";
static const char kJsonPullUp[] = "up";
static const char kJsonPullDown[] = "down";
static const char kGpioModeInput[] = "input";
static const char kGpioModeOutput[] = "output";

static const char kJsonMcpTools[] = "mcp_tools";
static const char kJsonName[] = "name";
static const char kJsonDescription[] = "description";
static const char kMcpToolPrefix[] = "sd.";
static const char kParamAction[] = "action";

static const int8_t kToolPrefixLength = 3; // "sd." 长度
static const int8_t kMaxMcpToolNameLength = 32;
static const int8_t kMaxMcpToolQuantity = 10; // 限制 MCP Tool 数量，防止滥用
static const int16_t kMaxFileSize = 8 * 1024; // 限制配置文件大小，防止内存耗尽
}

void SdExtensionManager::LoadDynamicConfiguration()
{
    if (!is_sdcard_found_)
        return;

    FILE *f = fopen(CONFIG_PATH, "r");
    if (f == NULL) {
        ESP_LOGW(TAG, "Configuration file %s not found. Skipping dynamic setup.", CONFIG_PATH);
        return;
    }

    fseek(f, 0, SEEK_END);
    long fsize = ftell(f);
    if (fsize < 0 || fsize > kMaxFileSize) {
        ESP_LOGE(TAG, "Configuration file size %ld is invalid or exceeds limit (%d bytes).", fsize, kMaxFileSize);
        fclose(f);
        return;
    }
    fseek(f, 0, SEEK_SET);

    char *json_buf = (char *)malloc(fsize + 1);
    fread(json_buf, 1, fsize, f);
    json_buf[fsize] = '\0';
    fclose(f);

    cJSON *root = cJSON_Parse(json_buf);
    free(json_buf);

    if (root == NULL) {
        ESP_LOGE(TAG, "JSON parse error before: [%s]", cJSON_GetErrorPtr());
        return;
    }

    // 安全校验：设备名称与 LCID 必须匹配
    cJSON *board_name_obj = cJSON_GetObjectItem(root, kJsonBoardName);
    cJSON *lcode_obj = cJSON_GetObjectItem(root, kJsonLCode);

    if (!board_name_obj || !lcode_obj ||
        GetBoardName() != board_name_obj->valuestring ||
        GetLCode() != lcode_obj->valuestring) {
        ESP_LOGE(TAG,
                 "Device validation failed! Target: BoardName=%s, LCODE=%s. File rejected.",
                 board_name_obj ? board_name_obj->valuestring : "Unknown",
                 lcode_obj ? lcode_obj->valuestring : "Unknown");
        cJSON_Delete(root);
        return;
    }
    ESP_LOGI(TAG, "Device validation passed. Processing rules...");

    ParseExternalInitializers(cJSON_GetObjectItem(root, kJsonGpioInitializers));
    ParseMcpTools(cJSON_GetObjectItem(root, kJsonMcpTools));

    cJSON_Delete(root);
}