mimiclaw/changelog.md

变更日志：增加国内大模型厂商接入

版本信息

• 版本：v1.1.0（计划）
• 日期：2026-03-31
• 状态：计划中

功能概述

为 MimiClaw 项目增加国内大模型厂商的接入支持，包括：

1. 硅基流动 (SiliconFlow) - 提供免费模型和多种高性能大模型
2. 火山方舟 (Volcengine Ark) - 字节跳动豆包模型系列

实施计划

阶段一：准备与设计（1-2天）

1.1 详细API调研

• 研究硅基流动API文档，确认：

  • 具体的Base URL和端点
  • 认证方式（API Key格式）
  • 支持的模型列表和ID格式
  • 工具调用兼容性
  • 速率限制和配额

• 研究火山方舟API文档，确认：

  • 具体的Base URL和端点
  • 认证方式（API Key格式）
  • 支持的模型列表和ID格式
  • 工具调用兼容性
  • 速率限制和配额

1.2 架构设计

• 设计提供商扩展机制
• 确定配置管理方案
• 设计命令行接口扩展
• 评估内存影响

阶段二：核心实现（3-5天）

2.1 配置系统扩展

• 修改 mimi_secrets.h.example 添加新配置项：

  /* 国内大模型厂商配置 */
  #define MIMI_SECRET_SILICONFLOW_API_KEY   ""
  #define MIMI_SECRET_SILICONFLOW_BASE_URL  "https://api.siliconflow.cn/v1"
  #define MIMI_SECRET_VOLCENGINE_API_KEY    ""
  #define MIMI_SECRET_VOLCENGINE_BASE_URL   "https://ark.cn-beijing.volces.com/api/v3"
  

• 更新 mimi_config.h 添加相关默认值

2.2 LLM代理扩展

• 修改 llm_proxy.c 支持新的提供商：

  • 添加 provider_is_siliconflow() 函数
  • 添加 provider_is_volcengine() 函数
  • 扩展 llm_api_url() 函数支持新提供商
  • 扩展 llm_api_host() 函数支持新提供商
  • 扩展 llm_api_path() 函数支持新提供商

• 添加Base URL配置支持：

  static char s_siliconflow_base_url[256] = "https://api.siliconflow.cn/v1";
  static char s_volcengine_base_url[256] = "https://ark.cn-beijing.volces.com/api/v3";
  

• 修改HTTP请求头设置逻辑：

  • 硅基流动：使用Bearer Token认证
  • 火山方舟：使用Bearer Token认证（假设与OpenAI兼容）

• 添加模型名称转换逻辑（如果需要）

2.3 命令行界面扩展

• 在 serial_cli.c 添加新命令：

  • set_siliconflow_key <key>：设置硅基流动API密钥
  • set_siliconflow_url <url>：设置硅基流动Base URL
  • set_volcengine_key <key>：设置火山方舟API密钥
  • set_volcengine_url <url>：设置火山方舟Base URL

• 更新现有命令的帮助信息

• 更新 config_show 命令显示新配置

2.4 提供商切换机制

• 修改 set_model_provider 命令支持新提供商：

  • 支持值：anthropic, openai, siliconflow, volcengine

• 更新NVS存储键名：

  • 可能需要扩展 MIMI_NVS_KEY_PROVIDER 支持更多值

阶段三：测试与优化（2-3天）

3.1 功能测试

• 单元测试：

  • 提供商检测函数测试
  • API URL生成测试
  • 请求头设置测试

• 集成测试：

  • 硅基流动API连接测试
  • 火山方舟API连接测试
  • 工具调用功能测试
  • 提供商切换测试

3.2 性能优化

• 内存使用优化：

  • 评估新增变量对内存的影响
  • 优化字符串存储大小

• 网络性能：

  • 测试国内网络环境下的连接稳定性
  • 优化超时设置

3.3 错误处理

• 添加详细的错误日志
• 处理API特定的错误响应
• 添加重试机制（如果需要）

阶段四：文档与发布（1天）

4.1 文档更新

• 更新 README.md 添加新功能说明
• 更新 mimi_secrets.h.example 添加配置示例
• 创建国内大模型厂商配置指南
• 更新串口CLI命令文档

4.2 发布准备

• 代码审查
• 最终测试
• 创建发布标签

技术细节

提供商检测逻辑

// 在 llm_proxy.c 中添加
static bool provider_is_siliconflow(void) {
    return strcmp(s_provider, "siliconflow") == 0;
}

static bool provider_is_volcengine(void) {
    return strcmp(s_provider, "volcengine") == 0;
}

API URL 配置

// 扩展 llm_api_url 函数
static const char *llm_api_url(void) {
    if (provider_is_openai()) {
        return MIMI_OPENAI_API_URL;
    } else if (provider_is_siliconflow()) {
        return s_siliconflow_base_url;
    } else if (provider_is_volcengine()) {
        return s_volcengine_base_url;
    } else {
        return MIMI_LLM_API_URL; // Anthropic
    }
}

请求头设置

// 扩展 HTTP 请求头设置
if (provider_is_openai() || provider_is_siliconflow() || provider_is_volcengine()) {
    // OpenAI兼容的Bearer Token认证
    if (s_api_key[0]) {
        char auth[LLM_API_KEY_MAX_LEN + 16];
        snprintf(auth, sizeof(auth), "Bearer %s", s_api_key);
        esp_http_client_set_header(client, "Authorization", auth);
    }
} else {
    // Anthropic的x-api-key认证
    esp_http_client_set_header(client, "x-api-key", s_api_key);
    esp_http_client_set_header(client, "anthropic-version", MIMI_LLM_API_VERSION);
}

风险评估与缓解

风险1：API兼容性问题

• 风险：国内厂商的API可能与OpenAI有细微差异
• 缓解：详细测试，添加兼容性处理代码

风险2：内存限制

• 风险：新增配置可能超出ESP32-S3内存限制
• 缓解：优化字符串存储，使用固定大小数组

风险3：网络连接问题

• 风险：国内网络环境可能影响API调用
• 缓解：添加重试机制，优化超时设置

风险4：认证安全

• 风险：API密钥存储和传输安全
• 缓解：使用现有的NVS加密存储，确保安全传输

预期成果

1. 功能完成：支持硅基流动和火山方舟两个国内大模型厂商
2. 配置灵活：用户可以通过命令行或配置文件灵活配置
3. 向后兼容：不影响现有的Anthropic和OpenAI功能
4. 文档完整：提供完整的配置和使用文档

时间估算

• 总时间：7-11个工作日
• 阶段一：1-2天
• 阶段二：3-5天
• 阶段三：2-3天
• 阶段四：1天

依赖项

1. 外部依赖：

   • 硅基流动API访问权限
   • 火山方舟API访问权限
   • 稳定的网络连接

2. 内部依赖：

   • 现有的LLM代理架构
   • 配置管理系统
   • 命令行界面系统

成功标准

1. 可以成功连接硅基流动API并获取响应
2. 可以成功连接火山方舟API并获取响应
3. 工具调用功能在两个新提供商上正常工作
4. 提供商切换功能正常
5. 内存使用在可接受范围内
6. 所有现有功能保持正常