titor
6983a1f1ba
通过 sdkconfig.defaults 选择性启用/禁用模块，减少固件体积： 新增模块开关： - CONFIG_MIMI_CHAN_TELEGRAM (默认 n) - CONFIG_MIMI_CHAN_FEISHU (默认 y) - CONFIG_MIMI_TOOL_WEB_SEARCH (默认 y) - CONFIG_MIMI_TOOL_GPIO (默认 n) - CONFIG_MIMI_WS_SERVER (默认 y) - CONFIG_MIMI_WIFI_ONBOARD (默认 y) - CONFIG_MIMI_OTA (默认 n) 技术实现： - CMakeLists.txt 条件编译源文件 - 头文件使用 static inline stub - CLI 命令和工具注册也支持条件编译 消除 Telegram 未配置时的 5 秒轮询警告日志
249 lines
8.2 KiB
Markdown
249 lines
8.2 KiB
Markdown
# 讨论记录
|
||
|
||
---
|
||
|
||
## 讨论：ESP-IDF v6.0 编译适配
|
||
|
||
**日期**：2026-03-31
|
||
**目标**：解决 ESP-IDF v6.0 编译失败问题，完成固件烧录
|
||
|
||
### 问题清单
|
||
|
||
#### 1. Flash 大小配置错误
|
||
- **错误**：分区表需要 16MB，但 sdkconfig 配置为 2MB
|
||
- **修复**：`sdkconfig` 中 `CONFIG_ESPTOOLPY_FLASHSIZE` 改为 16MB
|
||
|
||
#### 2. WiFi 断开原因码未定义
|
||
- **错误**：`WIFI_REASON_ASSOC_EXPIRE` 等符号在 v6.0 中未定义
|
||
- **修复**：`wifi_manager.c` 中所有 reason code 添加 `#ifdef` 保护
|
||
|
||
#### 3. CMakeLists.txt 缺少源文件
|
||
- **错误**：`llm_provider.c` 未加入编译列表，导致链接错误
|
||
- **修复**：添加 `ota/ota_manager.c` 到 SRCS
|
||
|
||
#### 4. 头文件缺失（共 16 处）
|
||
| 文件 | 缺失头文件 | 原因 |
|
||
|------|-----------|------|
|
||
| `cli/serial_cli.c` | `llm/llm_provider.h` | `llm_provider_set_api_key` |
|
||
| `llm/llm_provider.c` | `esp_http_client.h` | `esp_http_client_set_header` |
|
||
| `bus/message_bus.c` | `freertos/FreeRTOS.h`, `freertos/queue.h` | `xQueueCreate`, `QueueHandle_t` |
|
||
| `wifi/wifi_manager.c` | `esp_event.h` | `esp_event_handler_instance_register` |
|
||
| `wifi/wifi_manager.c` | `freertos/FreeRTOS.h`, `freertos/task.h`, `freertos/event_groups.h` | `xEventGroupCreate`, `vTaskDelay` |
|
||
| `ota/ota_manager.c` | `esp_system.h` | `esp_restart` |
|
||
| `channels/telegram/telegram_bot.c` | `freertos/FreeRTOS.h`, `freertos/task.h` | `xTaskCreatePinnedToCore`, `vTaskDelay` |
|
||
| `tools/tool_registry.c` | `<stdlib.h>` | `free()` |
|
||
| `proxy/http_proxy.c` | `<sys/time.h>` | `struct timeval` |
|
||
| `gateway/ws_server.c` | `<stdint.h>` | `uint8_t` |
|
||
|
||
### ESP-IDF v6.0 API 兼容性验证
|
||
|
||
以下 API 在 v6.0 中**仍然存在**，无需修改：
|
||
- `esp_spiffs_info()` ✅
|
||
- `esp_websocket_client_send_bin()` ✅
|
||
- `esp_tls_set_conn_sockfd()` / `esp_tls_set_conn_state()` ✅
|
||
- `esp_console_new_repl_uart()` / `esp_console_new_repl_usb_serial_jtag()` ✅
|
||
- `esp_https_ota()` + `esp_https_ota_config_t` ✅
|
||
- `esp_wifi_set_config()` ✅
|
||
|
||
### 烧录说明
|
||
|
||
ESP32-S3 使用 **USB 口**（内置 USB Serial/JTAG 控制器）烧录：
|
||
```powershell
|
||
idf.py -p COMx flash monitor
|
||
```
|
||
- 插 USB 口（标记为 `USB`），不是 UART 口
|
||
- 如遇连接失败，按住 BOOT 键再插线进入下载模式
|
||
|
||
---
|
||
|
||
## 讨论：增加国内大模型厂商接入
|
||
|
||
**日期**：2026-03-31
|
||
**目标**：为 MimiClaw 增加硅基流动和火山方舟（豆包模型）接入
|
||
|
||
### 项目现状
|
||
- 当前支持：Anthropic (Claude)、OpenAI (GPT)
|
||
- 运行平台：ESP32-S3，纯 C 语言
|
||
- 交互方式：Telegram 机器人
|
||
|
||
### 国内厂商 API 兼容性
|
||
- **硅基流动**：OpenAI 兼容，Base URL `https://api.siliconflow.cn/v1`
|
||
- **火山方舟**：OpenAI 兼容，Base URL `https://ark.cn-beijing.volces.com/api/v3`
|
||
|
||
### 实现方案
|
||
由于两者都提供 OpenAI 兼容 API，可复用现有 OpenAI 集成代码，只需：
|
||
1. 修改 Base URL
|
||
2. 调整认证方式（Bearer Token）
|
||
3. 处理模型名称规范
|
||
|
||
### 待解决问题
|
||
1. 认证方式差异确认
|
||
2. 模型名称规范
|
||
3. 工具调用格式兼容性验证
|
||
|
||
---
|
||
|
||
## 讨论：时区设置功能
|
||
|
||
**日期**：2026-04-01
|
||
**目标**：为 MimiClaw 添加可配置的时区支持，默认改为中国时区
|
||
|
||
### 背景
|
||
- 原默认时区为 `PST8PDT,M3.2.0,M11.1.0`（太平洋时间）
|
||
- 需要支持用户自定义时区，特别是中国用户（UTC+8）
|
||
- 交互方式从 Telegram 改为飞书
|
||
|
||
### 实现方案
|
||
|
||
#### 存储方式
|
||
- **NVS 存储**：使用 `system_config` namespace，key 为 `timezone`
|
||
- **Build-time 默认值**：`MIMI_TIMEZONE` 改为 `"CST-8"`
|
||
- **优先级**：NVS 值 > Build-time 值
|
||
|
||
#### CLI 命令
|
||
```
|
||
set_timezone <TZ> # 例如: set_timezone CST-8 或 set_timezone Asia/Shanghai
|
||
timezone_show # 显示当前时区配置和本地时间
|
||
```
|
||
|
||
#### LLM 工具
|
||
- 新增 `set_timezone` 工具，LLM 可通过对话设置时区
|
||
- 支持 POSIX 格式（`CST-8`）和城市名（`Asia/Shanghai`）
|
||
- 内置 18 个城市名映射表
|
||
|
||
### 改动文件
|
||
| 文件 | 操作 |
|
||
|------|------|
|
||
| `main/mimi_config.h` | 默认时区改为 `CST-8`，添加 `MIMI_NVS_KEY_TIMEZONE` |
|
||
| `main/tools/tool_set_timezone.h` | **新建** |
|
||
| `main/tools/tool_set_timezone.c` | **新建** |
|
||
| `main/tools/tool_registry.c` | include 新头文件 + 注册工具 |
|
||
| `main/cli/serial_cli.c` | 添加 `set_timezone` / `timezone_show` 命令 |
|
||
| `main/CMakeLists.txt` | 添加 `tool_set_timezone.c` 到 SRCS |
|
||
|
||
### 支持的时区格式
|
||
- POSIX: `CST-8`, `JST-9`, `EST5EDT,M3.2.0,M11.1.0`, `UTC0`
|
||
- 城市名: Asia/Shanghai, Asia/Tokyo, America/New_York 等 18 个预设
|
||
|
||
---
|
||
|
||
## 讨论：编译时模块开关（模块化配置）
|
||
|
||
**日期**：2026-04-03
|
||
**分支**：`feature/module-config`
|
||
**目标**：通过编译时配置选择性禁用不需要的模块，减少固件体积，消除未配置模块的警告日志
|
||
|
||
### 问题背景
|
||
|
||
1. **Task Watchdog 超时**：ESP32-S3 运行一天后触发看门狗超时，怀疑是设计问题
|
||
2. **Telegram 警告日志**：用户使用飞书但未配置 Telegram，控制台每 5 秒打印 "No bot token configured"
|
||
3. **代码冗余**：Telegram、OpenAI 接口等未使用的模块仍然编译进固件
|
||
|
||
### 用户需求
|
||
|
||
用户希望：
|
||
1. 通过编译选项禁用不需要的模块（如 Telegram）
|
||
2. 从源码层面直接过滤不用的组件，减少代码体积
|
||
3. 禁用模块后不触发警告日志
|
||
|
||
### 实现方案
|
||
|
||
#### 方案选择：编译时条件编译（方案 02）
|
||
|
||
**优点**：
|
||
- 直接减少 Flash 占用
|
||
- 零 RAM 占用，不创建任务
|
||
- 从源头消除警告日志
|
||
- 实现简单
|
||
|
||
**缺点**：
|
||
- 切换模块需要重新编译
|
||
|
||
#### 技术实现
|
||
|
||
##### 1. 配置文件：`sdkconfig.defaults`
|
||
|
||
```c
|
||
// Channel Modules
|
||
CONFIG_MIMI_CHAN_TELEGRAM=n // 默认禁用
|
||
CONFIG_MIMI_CHAN_FEISHU=y // 默认启用
|
||
|
||
// Tool Modules
|
||
CONFIG_MIMI_TOOL_WEB_SEARCH=y
|
||
CONFIG_MIMI_TOOL_GPIO=n
|
||
|
||
// Optional Modules
|
||
CONFIG_MIMI_WS_SERVER=y
|
||
CONFIG_MIMI_WIFI_ONBOARD=y
|
||
CONFIG_MIMI_OTA=n
|
||
```
|
||
|
||
##### 2. CMakeLists.txt：条件编译源文件
|
||
|
||
```cmake
|
||
if(CONFIG_MIMI_CHAN_TELEGRAM)
|
||
list(APPEND srcs "channels/telegram/telegram_bot.c")
|
||
endif()
|
||
```
|
||
|
||
##### 3. 头文件 stub：调用方无感知
|
||
|
||
```c
|
||
// telegram_bot.h
|
||
#ifdef CONFIG_MIMI_CHAN_TELEGRAM
|
||
esp_err_t telegram_bot_init(void);
|
||
esp_err_t telegram_bot_start(void);
|
||
#else
|
||
static inline esp_err_t telegram_bot_init(void) { return ESP_OK; }
|
||
static inline esp_err_t telegram_bot_start(void) { return ESP_OK; }
|
||
#endif
|
||
```
|
||
|
||
### 修改文件清单
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `sdkconfig.defaults` | 添加模块开关配置 |
|
||
| `main/CMakeLists.txt` | 条件编译源文件 |
|
||
| `main/channels/telegram/telegram_bot.h` | 添加 stub |
|
||
| `main/channels/feishu/feishu_bot.h` | 添加 stub |
|
||
| `main/gateway/ws_server.h` | 添加 stub |
|
||
| `main/onboard/wifi_onboard.h` | 添加 stub |
|
||
| `main/ota/ota_manager.h` | 添加 stub |
|
||
| `main/tools/tool_web_search.h` | 添加 stub |
|
||
| `main/tools/tool_gpio.h` | 添加 stub |
|
||
| `main/tools/tool_registry.c` | 条件注册工具 |
|
||
| `main/cli/serial_cli.c` | 条件注册 CLI 命令 |
|
||
| `main/mimi.c` | 条件调用模块 |
|
||
| `AGENTS.md` | 更新文档 |
|
||
|
||
### 模块依赖关系
|
||
|
||
- **Channel 模块**（telegram、feishu）：
|
||
- 被 `mimi.c` 调用（init/start）
|
||
- 被 `outbound_dispatch_task` 调用（send）
|
||
- CLI 命令也需要条件编译
|
||
|
||
- **Tool 模块**（web_search、gpio）：
|
||
- 被 `tool_registry.c` 调用（注册 + 执行）
|
||
- CLI 命令也需要条件编译
|
||
|
||
- **可选模块**（ws_server、wifi_onboard、ota）：
|
||
- 被 `mimi.c` 调用
|
||
- `wifi_onboard` 禁用时需特殊处理（不能进入 captive portal）
|
||
|
||
### 注意事项
|
||
|
||
1. **OTA 模块**：目前未初始化，但已编译
|
||
2. **工具描述中的渠道提示**：cron_add 工具描述中提到 telegram，可保留（只是描述，不影响功能）
|
||
3. **get_time 工具**：使用 telegram.org 代理获取时间（技术原因，不属于 telegram_bot 模块）
|
||
|
||
### 预期效果
|
||
|
||
| 禁用项 | 效果 |
|
||
|--------|------|
|
||
| Telegram | 不编译 telegram_bot.c，无 5 秒警告，节省约 15KB+ Flash |
|
||
| GPIO | 不编译 tool_gpio.c，无 gpio_* 工具，节省约 5KB Flash |
|
||
| WebSocket | 不编译 ws_server.c，节省约 10KB Flash |
|
||
| WiFi Onboard | 不能进入 captive portal 模式，需其他方式配置 WiFi |
|