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

## 版本信息
- **版本**：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` 添加新配置项：
  ```c
  /* 国内大模型厂商配置 */
  #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配置支持：
  ```c
  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 发布准备
- [ ] 代码审查
- [ ] 最终测试
- [ ] 创建发布标签

## 技术细节

### 提供商检测逻辑
```c
// 在 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 配置
```c
// 扩展 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
    }
}
```

### 请求头设置
```c
// 扩展 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. 所有现有功能保持正常