fix: 添加 Kconfig.projbuild 修复模块开关失效问题

- 创建 main/Kconfig.projbuild 声明所有自定义模块配置项
- 修复 fullclean 后 sdkconfig 丢失 CONFIG_MIMI_* 配置的问题
- 更新 AGENTS.md 添加认知修正栏目和模块开关文档
- 记录 Kconfig 踩坑讨论到 taolun.md

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-缺失导致模块开关失效) |
+
+---
+
 ## 开发注意事项
 
 ## 开发注意事项

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

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"

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` 无效。