mimiclaw/taolun.md

讨论记录

---

讨论：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 控制器）烧录：

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

// 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：条件编译源文件

if(CONFIG_MIMI_CHAN_TELEGRAM)
    list(APPEND srcs "channels/telegram/telegram_bot.c")
endif()

3. 头文件 stub：调用方无感知

// 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