titor/mimiclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加项目注释
Some checks failed
Build / idf-build (push) Has been cancelled
Details

Browse Source
This commit is contained in:
z-to
2026-03-31 17:56:51 +08:00
parent bb10ea0149
commit 46e46b0a13
3 changed files with 517 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
AGENTS.md Normal file
View File

@@ -0,0 +1,143 @@
# MimiClaw AI Agent - 开发指南
## 项目概述
MimiClaw 是一个运行在 ESP32-S3 上的 AI 助手，使用纯 C 语言编写。用户通过 Telegram 与之交互，设备连接 WiFi 后，将消息传递给 LLM（大语言模型）进行处理，并支持工具调用。
## 项目结构
```
mimiclaw/
├── main/ # 主应用程序代码
│ ├── agent/ # 代理循环（核心逻辑）
│ │ ├── agent_loop.c # 主代理循环，处理消息和工具调用
│ │ └── context_builder.c # 构建上下文（系统提示、记忆等）
│ ├── llm/ # LLM 代理
│ │ ├── llm_proxy.c # 处理与 LLM API 的通信
│ │ └── llm_proxy.h # LLM 代理的头文件
│ ├── cli/ # 串口命令行界面
│ │ └── serial_cli.c # 处理运行时配置命令
│ ├── channels/ # 输入/输出通道
│ │ ├── telegram/ # Telegram 机器人集成
│ │ └── feishu/ # 飞书机器人集成
│ ├── tools/ # LLM 可调用的工具
│ ├── memory/ # 记忆和会话管理
│ ├── proxy/ # HTTP 代理支持
│ ├── cron/ # 定时任务调度
│ ├── heartbeat/ # 心跳服务
│ ├── gateway/ # WebSocket 网关
│ ├── onboard/ # WiFi 配置门户
│ ├── skills/ # 技能加载器
│ ├── mimi_config.h # 全局配置定义
│ ├── mimi_secrets.h # 构建时密钥（需用户创建）
│ └── mimi_secrets.h.example # 密钥模板
├── docs/ # 文档
├── scripts/ # 构建和设置脚本
├── CMakeLists.txt # 顶层 CMake 文件
└── sdkconfig.defaults # ESP-IDF 默认配置
```
## 核心系统
### 1. 配置系统
- **构建时配置**：在 `main/mimi_secrets.h` 中定义（从 `.example` 复制）
- **运行时配置**：通过串口 CLI 命令设置，存储在 NVS 中，优先级高于构建时配置
- **关键配置项**：
- `MIMI_SECRET_WIFI_SSID/PASS`：WiFi 凭证
- `MIMI_SECRET_TG_TOKEN`：Telegram 机器人令牌
- `MIMI_SECRET_API_KEY`：LLM API 密钥
- `MIMI_SECRET_MODEL_PROVIDER`：模型提供商（"anthropic" 或 "openai"）
- `MIMI_SECRET_MODEL`：模型名称
### 2. LLM 集成
- **当前支持**：Anthropic (Claude) 和 OpenAI (GPT)
- **提供商切换**：通过 `MIMI_SECRET_MODEL_PROVIDER` 或 CLI 命令 `set_model_provider <provider>`
- **代码路径**：`main/llm/llm_proxy.c`
- **关键函数**：
- `llm_proxy_init()`：初始化，从 NVS 加载配置
- `llm_chat_tools()`：发送聊天请求，支持工具调用
- `provider_is_openai()`：检查是否为 OpenAI 提供商
### 3. 代理循环
- **代码路径**：`main/agent/agent_loop.c`
- **工作流程**：
1. 接收消息
2. 构建上下文（系统提示、记忆、会话历史）
3. 调用 LLM（支持工具调用）
4. 处理工具调用结果
5. 返回响应
### 4. 工具系统
- 工具在 `main/tools/` 中定义
- 工具注册在 `tool_registry.c`
- 支持的工具：`web_search`、`get_current_time`、`cron_add/list/remove`
## 构建和烧录
### 前提条件
- ESP-IDF v5.5+ 已安装
- ESP32-S3 开发板（16MB flash, 8MB PSRAM）
### 步骤
```bash
# 设置目标芯片
idf.py set-target esp32s3
# 配置（首次需要）
cp main/mimi_secrets.h.example main/mimi_secrets.h
# 编辑 mimi_secrets.h 填写 WiFi、Telegram、LLM 密钥
# 清理构建（修改配置后必须执行）
idf.py fullclean && idf.py build
# 烧录（替换 PORT 为实际串口）
idf.py -p PORT flash monitor
```
## 串口 CLI 命令
连接到 UART（COM）端口后，可用的配置命令：
```
wifi_set <SSID> <Password> # 设置 WiFi 凭证
set_tg_token <Token> # 设置 Telegram 机器人令牌
set_api_key <Key> # 设置 LLM API 密钥
set_model_provider <Provider># 设置提供商（anthropic/openai）
set_model <Model> # 设置模型名称
config_show # 显示当前配置（脱敏）
config_reset # 重置为构建时配置
```
## 开发注意事项
1. **内存限制**：ESP32-S3 内存有限，使用 `MALLOC_CAP_SPIRAM` 分配大内存
2. **堆栈大小**：任务堆栈在 `mimi_config.h` 中定义
3. **日志**：使用 `ESP_LOG` 宏，标签在每个文件中定义
4. **错误处理**：使用 `esp_err_t` 返回码
5. **JSON 处理**：使用 cJSON 库
## 调试技巧
- 查看日志：`idf.py -p PORT monitor`
- 内存状态：串口 CLI 命令 `heap_info`
- 会话列表：`session_list`
- 记忆内容：`memory_read`
## 扩展指南
### 添加新的 LLM 提供商
1. 在 `llm_proxy.c` 中添加提供商检查函数
2. 添加新的 API URL 和主机名
3. 如需要，添加特定的请求头和消息格式转换
4. 更新 `mimi_config.h` 中的默认配置
### 添加新工具
1. 在 `tools/` 目录创建新文件
2. 实现工具函数
3. 在 `tool_registry.c` 中注册工具
4. 定义工具的 JSON Schema
### 添加新通道
1. 在 `channels/` 目录创建新子目录
2. 实现通道初始化和消息收发
3. 在 `mimi.c` 中初始化新通道

229
changelog.md Normal file
View File

@@ -0,0 +1,229 @@
# 变更日志：增加国内大模型厂商接入
## 版本信息
- **版本**：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. 所有现有功能保持正常

145
taolun.md Normal file
View File

@@ -0,0 +1,145 @@
# 讨论记录：增加国内大模型厂商接入
## 对话概述
**日期**：2026-03-31
**目标**：为 MimiClaw 项目增加国内大模型厂商的接入，特别是硅基流动和火山方舟（豆包模型）
## 对话内容
### 用户需求
用户希望给当前项目增加国内大模型厂商的接入，包括：
1. 硅基流动的免费模型
2. 火山方舟的豆包模型
### 项目现状分析
#### 项目基本信息
- **项目名称**：MimiClaw
- **运行平台**：ESP32-S3（纯C语言）
- **交互方式**：Telegram机器人
- **功能**：AI助手，支持工具调用，本地记忆
#### 当前LLM集成状态
1. **支持的提供商**：
- Anthropic (Claude)
- OpenAI (GPT)
2. **配置方式**：
- 构建时配置：`main/mimi_secrets.h`
- 运行时配置：串口CLI命令，存储在NVS中
3. **关键代码文件**：
- `main/llm/llm_proxy.c`：LLM代理核心实现
- `main/llm/llm_proxy.h`：LLM代理头文件
- `main/mimi_config.h`：全局配置定义
- `main/cli/serial_cli.c`：命令行界面
4. **提供商检测机制**：
- `provider_is_openai()`函数检查是否为OpenAI提供商
- 根据提供商选择不同的API URL、Host和Path
### 国内大模型厂商API兼容性调研
#### 硅基流动 (SiliconFlow)
- **API兼容性**：OpenAI兼容模式
- **Base URL**：`https://api.siliconflow.cn/v1`
- **特点**：
- 提供100+高性能大模型
- 新用户注册送免费额度
- 价格比OpenAI官方便宜80%+
- 支持OpenClaw等工具集成
#### 火山方舟 (字节跳动豆包模型)
- **API兼容性**：兼容OpenAI SDK
- **Base URL**：`https://ark.cn-beijing.volces.com/api/v3`
- **特点**：
- 豆包大模型系列
- 新用户首次开通可享受50万token免费试用
- 支持函数调用、工具调用等高级功能
### 技术实现分析
#### 当前架构特点
1. **提供商抽象**：
- 使用`s_provider`变量存储提供商名称
- 通过`provider_is_openai()`函数区分提供商
- 根据提供商选择不同的API配置
2. **API调用流程**：
- 构建请求体
- 设置请求头（根据提供商不同）
- 发送HTTP请求
- 解析响应（根据提供商不同）
3. **工具调用支持**：
- 支持Anthropic的tool_use格式
- 支持OpenAI的function calling格式
- 有格式转换函数`convert_tools_openai()`
#### 实现方案讨论
由于硅基流动和火山方舟都提供OpenAI兼容的API，理论上可以复用现有的OpenAI集成代码，只需要：
1. 修改Base URL
2. 可能需要调整认证方式
3. 可能需要处理特定的模型名称
## 待解决问题
1. **认证方式差异**：
- 硅基流动：使用API Key
- 火山方舟：可能使用不同的认证方式
2. **模型名称规范**：
- 需要了解具体的模型ID格式
- 例如：硅基流动的`deepseek-ai/DeepSeek-V3`，火山方舟的豆包模型名称
3. **功能支持差异**：
- 工具调用格式是否完全兼容
- 上下文长度限制
- 特殊功能支持情况
## 下一步计划
基于讨论，制定了以下实施计划：
### 阶段一：准备与设计
1. 详细调研硅基流动和火山方舟的API文档
2. 确定具体的实现方案
3. 设计配置结构和命令行接口
### 阶段二：核心实现
1. 修改LLM代理以支持新的提供商
2. 添加配置管理功能
3. 更新命令行界面
### 阶段三：测试与优化
1. 功能测试
2. 性能优化
3. 文档更新
## 相关资源
### 项目文件
- `main/llm/llm_proxy.c`：LLM代理实现
- `main/llm/llm_proxy.h`：LLM代理头文件
- `main/mimi_config.h`：配置定义
- `main/cli/serial_cli.c`：命令行界面
### 外部文档
- 硅基流动OpenClaw集成文档
- 火山方舟兼容OpenAI SDK文档
- ESP32-S3开发文档
## 技术要点总结
1. **复用现有架构**：可以充分利用现有的OpenAI集成代码
2. **提供商扩展**：需要扩展提供商检测和配置机制
3. **配置管理**：需要支持新的API密钥和Base URL配置
4. **兼容性处理**：可能需要处理API响应格式的细微差异
## 风险与挑战
1. **API兼容性风险**：虽然声称兼容，但可能存在细微差异
2. **内存限制**：ESP32-S3内存有限，需要确保新功能不会导致内存不足
3. **网络稳定性**：国内网络环境可能影响API调用稳定性
4. **认证安全性**：需要确保API密钥的安全存储和传输