From c1368962ccfb5f45d0de1a7b55de31405174b22a Mon Sep 17 00:00:00 2001 From: "Z.To" Date: Sat, 4 Apr 2026 06:44:52 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E6=B7=BB=E5=8A=A0=20Kconfig.projbuild?= =?UTF-8?q?=20=E4=BF=AE=E5=A4=8D=E6=A8=A1=E5=9D=97=E5=BC=80=E5=85=B3?= =?UTF-8?q?=E5=A4=B1=E6=95=88=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建 main/Kconfig.projbuild 声明所有自定义模块配置项 - 修复 fullclean 后 sdkconfig 丢失 CONFIG_MIMI_* 配置的问题 - 更新 AGENTS.md 添加认知修正栏目和模块开关文档 - 记录 Kconfig 踩坑讨论到 taolun.md --- AGENTS.md | 23 ++++++++++++++++--- main/Kconfig.projbuild | 51 ++++++++++++++++++++++++++++++++++++++++++ sdkconfig.defaults | 4 ++++ taolun.md | 37 ++++++++++++++++++++++++++++++ 4 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 main/Kconfig.projbuild diff --git a/AGENTS.md b/AGENTS.md index 57e7743..9b829b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,19 +108,28 @@ idf.py fullclean && idf.py build ### 添加新模块的编译时开关 -1. 在 `sdkconfig.defaults` 中添加配置项： +1. **创建 `main/Kconfig.projbuild`**（关键！没有它配置项不会被识别）： + ```kconfig + config MIMI_MODULE_EXAMPLE + bool "Example module" + default n + help + Enable example module for MimiClaw. + ``` + +2. 在 `sdkconfig.defaults` 中添加配置项： ``` CONFIG_MIMI_MODULE_EXAMPLE=y ``` -2. 在 `main/CMakeLists.txt` 中条件编译： +3. 在 `main/CMakeLists.txt` 中条件编译： ```cmake if(CONFIG_MIMI_MODULE_EXAMPLE) list(APPEND srcs "modules/example/example.c") endif() ``` -3. 在模块头文件中添加 stub： +4. 在模块头文件中添加 stub： ```c #ifdef CONFIG_MIMI_MODULE_EXAMPLE esp_err_t example_init(void); @@ -167,6 +176,14 @@ config_show # 显示当前配置（脱敏） config_reset # 重置为构建时配置 ``` +## 认知修正 + +| 日期 | 问题 | 根因 | 修复 | 详情 | +|------|------|------|------|------| +| 2026-04-04 | 模块开关失效（飞书命令消失、HTTP 配置页不可用） | 缺少 `Kconfig.projbuild`，ESP-IDF 不识别自定义配置项 | 创建 `main/Kconfig.projbuild` 声明所有模块开关 | [详细讨论](taolun.md#讨论kconfig-缺失导致模块开关失效) | + +--- + ## 开发注意事项 ## 开发注意事项 diff --git a/main/Kconfig.projbuild b/main/Kconfig.projbuild new file mode 100644 index 0000000..22fed1c --- /dev/null +++ b/main/Kconfig.projbuild @@ -0,0 +1,51 @@ +menu "MimiClaw Configuration" + +menu "Channel Modules" + config MIMI_CHAN_TELEGRAM + bool "Telegram bot integration" + default n + help + Enable Telegram bot integration for MimiClaw. + + config MIMI_CHAN_FEISHU + bool "Feishu (Lark) bot integration" + default y + help + Enable Feishu (Lark) bot integration for MimiClaw. +endmenu + +menu "Tool Modules" + config MIMI_TOOL_WEB_SEARCH + bool "Web search tool" + default y + help + Enable web search tool (requires search API key). + + config MIMI_TOOL_GPIO + bool "GPIO control tool" + default n + help + Enable GPIO control tool for hardware control. +endmenu + +menu "Optional Modules" + config MIMI_WS_SERVER + bool "WebSocket gateway" + default y + help + Enable WebSocket gateway for local clients. + + config MIMI_WIFI_ONBOARD + bool "WiFi onboarding portal" + default y + help + Enable Captive Portal for initial WiFi setup. + + config MIMI_OTA + bool "OTA firmware update" + default n + help + Enable OTA firmware update (not fully implemented). +endmenu + +endmenu diff --git a/sdkconfig.defaults b/sdkconfig.defaults index 8849ab3..990095a 100644 --- a/sdkconfig.defaults +++ b/sdkconfig.defaults @@ -36,3 +36,7 @@ CONFIG_ESP32S3_BROWNOUT_DET_LVL=7 # NOTE: CONFIG_LWIP_SNTP_MAX_SERVERS may be deprecated in ESP-IDF v6.0 # If compilation fails, comment out this line or use the new SNTP component config CONFIG_LWIP_SNTP_MAX_SERVERS=4 + +# Partition table: use custom partition table with SPIFFS and OTA +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" diff --git a/taolun.md b/taolun.md index 7b0fe22..419f72a 100644 --- a/taolun.md +++ b/taolun.md @@ -493,3 +493,40 @@ static inline esp_err_t telegram_bot_start(void) { return ESP_OK; } | GPIO | 不编译 tool_gpio.c，无 gpio_* 工具，节省约 5KB Flash | | WebSocket | 不编译 ws_server.c，节省约 10KB Flash | | WiFi Onboard | 不能进入 captive portal 模式，需其他方式配置 WiFi | + +--- + +## 讨论：Kconfig 缺失导致模块开关失效 + +**日期**：2026-04-04 +**问题**：编译后飞书命令消失、HTTP 配置页面不可用 + +### 现象 + +在 `sdkconfig.defaults` 中正确配置了 `CONFIG_MIMI_CHAN_FEISHU=y` 和 `CONFIG_MIMI_WIFI_ONBOARD=y`，执行 `idf.py fullclean && idf.py build` 后： +- 烧录后控制台没有飞书相关命令（`set_feishu_creds` 等）。 +- 设备没有启动 HTTP 配置服务（`192.168.4.1` 无法访问）。 +- 检查生成的 `sdkconfig` 文件，发现**完全没有**这些自定义配置项。 + +### 根因 + +ESP-IDF 的构建系统在生成 `sdkconfig` 时，**只会保留有 Kconfig 声明的配置项**。 + +- `sdkconfig.defaults` 仅用于提供默认值。 +- 如果项目缺少 `Kconfig` 或 `Kconfig.projbuild` 文件来声明这些选项，ESP-IDF 会认为它们是无效配置并直接丢弃。 +- 之前的版本可能 `sdkconfig` 是手动维护的或缓存未清理，但 `fullclean` 后重新生成时就会丢失这些"无名"配置。 + +### 修复方案 + +创建 `main/Kconfig.projbuild` 文件，声明所有自定义模块开关。 + +### 认知修正 + +**ESP-IDF 配置系统工作流**： + +1. `Kconfig.projbuild`：**声明**配置项（告诉系统"这是什么"）。 +2. `sdkconfig.defaults`：提供**默认值**（告诉系统"默认选什么"）。 +3. `sdkconfig`：构建系统根据前两者**自动生成**（实际编译用的配置）。 +4. `CMakeLists.txt`：读取 `sdkconfig` 中的值**决定编译哪些文件**。 + +**结论**：新增模块开关时，**必须**创建 Kconfig 声明，否则 `sdkconfig.defaults` 无效。