diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c02fe17 --- /dev/null +++ b/AGENTS.md @@ -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 ` +- **代码路径**:`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 # 设置 WiFi 凭证 +set_tg_token # 设置 Telegram 机器人令牌 +set_api_key # 设置 LLM API 密钥 +set_model_provider # 设置提供商(anthropic/openai) +set_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` 中初始化新通道 \ No newline at end of file diff --git a/changelog.md b/changelog.md new file mode 100644 index 0000000..462e4ef --- /dev/null +++ b/changelog.md @@ -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 `:设置硅基流动API密钥 + - `set_siliconflow_url `:设置硅基流动Base URL + - `set_volcengine_key `:设置火山方舟API密钥 + - `set_volcengine_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. 所有现有功能保持正常 \ No newline at end of file diff --git a/taolun.md b/taolun.md new file mode 100644 index 0000000..a88f763 --- /dev/null +++ b/taolun.md @@ -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密钥的安全存储和传输 \ No newline at end of file