# TinyHermes

**Repository Path**: supowang/TinyHermes

## Basic Information

- **Project Name**: TinyHermes
- **Description**: TinyHermes 把 Hermes Agent 的**核心理念完整搬到 ESP32-C5**：ReAct 工具调用、多层持久化记忆、
技能蒸馏与进化、Cron 与 Heartbeat 调度、多渠道（QQ / 飞书 / CLI）对话接入。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TinyHermes - ESP32-C5 AI Agent

> **运行在 ESP32-C5 上的自我进化 AI Agent 框架，用 C 写成。**
> 灵感来自 [Nous Research · Hermes Agent](https://github.com/NousResearch/hermes-agent) 与
> [memovai / mimiclaw](https://github.com/memovai/mimiclaw) 的 ESP32 工程实践。

TinyHermes 把 Hermes Agent 的**核心理念完整搬到 ESP32-C5**：ReAct 工具调用、多层持久化记忆、
技能蒸馏与进化、Cron 与 Heartbeat 调度、多渠道（QQ / 飞书 / CLI）对话接入。

**硬件平台**: ESP32-C5 (RISC-V @ 240MHz + 8MB PSRAM + 16MB Flash + WiFi 6)

工程风格对齐 mimiclaw：**单一 `main/` 目录、模块化子目录、集中式 `th_config.h + th_secrets.h` 配置**。

---

## 📑 目录

- [✨ 特性](#-特性)
- [🧱 系统架构](#-系统架构)
- [📁 项目结构](#-项目结构)
- [🚀 快速开始](#-快速开始)
- [🔑 配置说明](#-配置说明)
- [🧩 22 个内置工具](#-22-个内置工具)
- [🪄 10 个预置技能](#-10-个预置技能)
- [🧠 记忆与会话](#-记忆与会话)
- [🧬 自我进化](#-自我进化)
- [⏰ 定时任务与 Heartbeat](#-定时任务与-heartbeat)
- [🔧 部署指南](#-部署指南)
- [📚 更多文档](#-更多文档)

---

## ✨ 特性

| 能力 | 说明 |
|------|------|
| 🧠 **ReAct 主循环** | OpenAI 兼容 `tool_calls`，最多 8 轮迭代，Agent 思考→调工具→再思考→回复 |
| 🗂 **多层记忆** | `MEMORY.md` / `SOUL.md` / `USER.md` / session-per-chat，跨重启持久化 |
| 🪄 **技能系统** | 启动自动导入 10 个预置技能；Agent 可通过对话创建/修改技能 |
| 🧬 **自我进化** | 周期性反思，LLM 生成改进建议，按 benefit/risk 阈值自动应用 |
| ⏰ **Cron 调度** | 简化 cron 表达式，到点投递自然语言 prompt 给 Agent |
| 💓 **Heartbeat** | 每 30 分钟写入 `HEARTBEAT.md`，促进空闲期反思 |
| 🔌 **工具生态** | 22 个内置工具（含 `web_search` / `webpage_fetch`），静态注册表 32 槽可扩展 |
| 📱 **多渠道接入** | **腾讯 QQ 官方机器人 / 飞书 WS 长连接 / 串口 CLI**，三通道并发 |
| 🌐 **多 LLM 后端** | 阿里百炼 / OpenAI / Anthropic / OpenRouter，全部走 function calling |
| 💾 **持久化** | SPIFFS 存技能/记忆/cron，重启不丢；NVS 存动态凭证 |
| 📦 **预置 SPIFFS** | 烧录即带 10 个预置技能 + SOUL.md 人格，首启零学习成本 |
| 🛡 **集中配置** | 所有编译时常量在 `th_config.h`，敏感信息在 `th_secrets.h`（gitignore） |
| 🧱 **PSRAM-first** | HTTP 响应、sys_prompt、web_search 缓冲全部走 8MB PSRAM |
| 🔁 **WS 自愈** | QQ / 飞书 WS 断线 10 秒内自动重建 |
| 🚀 **WiFi 6** | 支持 802.11ax，更低延迟更高吞吐 |

---

## 🧱 系统架构

```
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   QQ WSS     │   │  飞书 WSS    │   │  串口 CLI    │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └──────────────┬───┴──────────────────┘
                      ▼
             ┌──────────────────┐
             │  Message Bus     │  inbound / outbound 队列
             └────────┬─────────┘
                      ▼
       ┌─────────────────────────────────┐
       │     Agent Loop (ReAct)          │
       │  system_prompt 构建 + 工具选择   │
       │  最多 8 轮 tool_calls 迭代       │
       └────────┬──────────────┬─────────┘
                │              │
        ┌───────▼──────┐  ┌────▼─────────┐
        │  LLM Proxy   │  │ Tool Registry│
        │  百炼/OpenAI │  │  22 个工具   │
        └──────────────┘  └────┬─────────┘
                               │
          ┌────────────────────┼───────────────────┐
          ▼                    ▼                   ▼
    ┌──────────┐        ┌────────────┐     ┌──────────────┐
    │  Memory  │        │  Skills    │     │  Web / GPIO  │
    │ MEMORY.md│        │ 10 预置 +  │     │  tools       │
    │ USER.md  │        │ 可对话新增 │     │              │
    │ Sessions │        └──────┬─────┘     └──────────────┘
    └──────────┘               │
                               ▼
                         ┌──────────┐
                         │Evolution │  周期性 LLM 自我反思
                         │  Engine  │  benefit/risk 过滤
                         └──────────┘
```

**三个后台任务**（固定 FreeRTOS task）：
1. **Agent Task** (core 0, prio 6, 16KB stack) — 主 ReAct 循环
2. **Outbound Task** (core 0, prio 5, 10KB stack) — 消息发送到各渠道
3. **Cron / Heartbeat Task** — 定时触发 agent 思考

---

## 📁 项目结构

```
TinyHermes/
├── CMakeLists.txt              # ESP-IDF 顶层工程
├── partitions.csv              # ESP32-C5: 16MB Flash 分区表
├── sdkconfig.defaults          # ESP32-C5 SDK 默认配置
├── DEPLOY.md                   # ★ 部署指南
├── USAGE.md  CONFIG.md         # 详细使用 / 配置字段
├── ARCHITECTURE.md             # 架构与数据流
├── main/                       # 唯一源码目录
│   ├── CMakeLists.txt
│   ├── tinyhermes.c            # 应用入口 (app_main)
│   ├── th_config.h             # 全局配置
│   ├── th_secrets.h.example    # 敏感信息模板
│   ├── bus/                    # 消息总线
│   ├── wifi/                   # WiFi STA 管理
│   ├── util/                   # NVS / SPIFFS / HTTP 封装
│   ├── llm/                    # LLM 代理
│   ├── memory/                 # MEMORY.md + session_mgr
│   ├── skills/                 # 技能管理
│   ├── tools/                  # 工具注册表 + 22 个内置工具
│   ├── agent/                  # ReAct 主循环 + 进化
│   ├── cron/ heartbeat/ cli/
│   └── channels/
│       ├── feishu/             # 飞书 WebSocket
│       └── qq/                 # QQ 官方机器人
├── spiffs_data/                # ★ 预置 SPIFFS 镜像
│   ├── config/ SOUL.md USER.md
│   ├── memory/ MEMORY.md
│   └── skills/                 # 10 个预置技能
└── tools/
    └── deploy_esp32c5.ps1      # ★ Windows 一键部署脚本
```

---

## 🚀 快速开始

### 前置条件

| 项 | 要求 |
|---|---|
| 硬件 | **ESP32-C5 开发板** (16MB Flash + 8MB PSRAM) |
| 工具链 | **ESP-IDF v5.3+** (推荐 v5.5.4) |
| 系统 | Windows / macOS / Linux |
| 网络 | 2.4GHz WiFi (支持 WiFi 6 更佳) |

### Step 1 — 克隆并配置凭证

```powershell
git clone <this-repo> TinyHermes
cd TinyHermes
Copy-Item main\th_secrets.h.example main\th_secrets.h
```

编辑 `main/th_secrets.h`，填入：

```c
#define TH_SECRET_WIFI_SSID       "YourWiFi"
#define TH_SECRET_WIFI_PASS       "YourPassword"
#define TH_SECRET_LLM_API_KEY     "sk-xxxxxxxxxxxxxxxxxxxx"
#define TH_SECRET_LLM_MODEL       "qwen3.5-plus"
#define TH_SECRET_LLM_PROVIDER    "openai"
#define TH_SECRET_LLM_BASE_URL    "https://coding.dashscope.aliyuncs.com/v1"
```

### Step 2 — 一键烧录（Windows）

```powershell
.\tools\deploy_esp32c5.ps1 -Port COM9
```

其他平台：

```bash
idf.py set-target esp32c5
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
```

### Step 3 — 启动验证

串口监视器看到：

```
I (xxx) tinyhermes: chip: esp32c5 rev 1.0, 1 core @ 240MHz
I (xxx) tinyhermes: flash: 16384 KB, psram: 8192 KB
I (xxx) th_skills: preset skills: imported=10
=== TinyHermes Ready ===
```

直接在 `>` 提示符下输入：

```
> 你是谁？
TinyHermes: 我是 TinyHermes，运行在 ESP32-C5 上的 AI 助手……
```

---

## 🔑 配置说明

### A. 必填配置

| 宏 | 来源 | 示例 |
|---|---|---|
| `TH_SECRET_WIFI_SSID` | 家庭路由器 | `"YourWiFi"` |
| `TH_SECRET_WIFI_PASS` | 家庭路由器 | `"password123"` |
| `TH_SECRET_LLM_API_KEY` | LLM 服务商 | `"sk-..."` |
| `TH_SECRET_LLM_BASE_URL` | LLM 服务商 | `"https://coding.dashscope.aliyuncs.com/v1"` |
| `TH_SECRET_LLM_MODEL` | LLM 服务商 | `"qwen3.5-plus"` / `"gpt-4o-mini"` |

### B. 选填配置

| 功能 | 宏 | 不填的后果 |
|---|---|---|
| QQ 机器人 | `TH_SECRET_QQ_APP_ID` + `TH_SECRET_QQ_APP_SECRET` | QQ 通道关闭 |
| 飞书机器人 | `TH_SECRET_FEISHU_APP_ID` + `TH_SECRET_FEISHU_APP_SECRET` | 飞书通道关闭 |
| 网页搜索 | `TH_SECRET_TAVILY_KEY` 或 `TH_SECRET_BRAVE_SEARCH_KEY` | `web_search` 不可用 |

### C. 支持的 LLM 服务商

```c
/* 阿里百炼 Coding (推荐中国大陆)  */ "https://coding.dashscope.aliyuncs.com/v1"
/* DeepSeek                         */ "https://api.deepseek.com/v1"
/* Moonshot                         */ "https://api.moonshot.cn/v1"
/* OpenAI                           */ "https://api.openai.com/v1"
/* Anthropic                        */ "https://api.anthropic.com/v1"
/* OpenRouter                       */ "https://openrouter.ai/api/v1"
```

---

## 🧩 22 个内置工具

| 分类 | 工具 | 说明 |
|------|------|------|
| **系统** | `get_current_time` | 获取当前时间 |
| | `sysinfo` | 芯片/内存信息 |
| **文件** | `file_read` / `file_write` / `file_list` | SPIFFS 文件操作 |
| **网络** | `http_get` | HTTP GET 请求 |
| | `web_search` | Tavily/Brave 搜索 |
| | `webpage_fetch` | 网页内容抓取 |
| **GPIO** | `gpio_set` / `gpio_get` | GPIO 控制（有黑名单保护） |
| **记忆** | `memory` | 写入长期记忆 |
| | `memory_search` | 搜索记忆 |
| | `session_search` | 搜索历史会话 |
| **技能** | `skills_list` | 列出技能 |
| | `skill_view` | 查看技能详情 |
| | `skill_invoke` | 执行技能 |
| | `skill_manage` | 创建/修改/删除技能 |
| | `skill_learn` | 从对话中学习新技能 |
| **定时** | `cron_add` / `cron_list` / `cron_remove` | 定时任务管理 |
| **待办** | `todo` | 待办事项管理 |

---

## 🪄 10 个预置技能

1. **web-search** - 网络搜索助手
2. **weather** - 天气查询
3. **gpio-control** - GPIO 控制向导
4. **daily-briefing** - 每日简报
5. **news-digest** - 新闻摘要
6. **decision-1-3-1** - 决策框架
7. **systematic-debug** - 系统化调试
8. **creative-ideation** - 创意构思
9. **skill-creator** - 技能创建向导
10. **smart-home** - 智能家居控制

---

## 🧠 记忆与会话

### 记忆文件

| 文件 | 用途 |
|------|------|
| `MEMORY.md` | 长期记忆，Agent 自动维护 |
| `SOUL.md` | Agent 人格定义 |
| `USER.md` | 用户信息与偏好 |
| `sessions/<chat_id>.json` | 按聊天 ID 隔离的会话历史 |

### 会话管理

- 每个 `chat_id` 独立维护最多 20 条消息
- 跨会话可通过 `session_search` 工具检索
- 重启后会话历史保留

---

## 🧬 自我进化

### 工作原理

1. **周期性反思**：每 3600 秒（可配置）触发一次
2. **LLM 分析**：评估最近的对话质量和工具使用效果
3. **生成建议**：提出改进方案（配置/技能/提示词）
4. **风险评估**：按 benefit/risk 阈值过滤
5. **自动应用**：通过则自动修改配置并记录历史

### 配置项

```c
#define TH_EVOLUTION_INTERVAL_S      3600   // 反思间隔
#define TH_EVOLUTION_MIN_TURNS       10     // 最少对话轮数
#define TH_EVOLUTION_MAX_SUGGESTIONS 5      // 最多建议数
#define TH_EVOLUTION_MIN_BENEFIT     0.5f   // 最低收益阈值
#define TH_EVOLUTION_MAX_RISK        0.5f   // 最高风险阈值
```

---

## ⏰ 定时任务与 Heartbeat

### Cron 调度

```json
[
  {
    "id": "morning_brief",
    "schedule": "0 8 * * *",
    "prompt": "生成今日简报，包括天气和待办事项",
    "channel": "cli"
  }
]
```

支持的字段：
- `minute hour day month weekday`（标准 cron 语法简化版）
- `prompt`：到时发送给 Agent 的自然语言指令
- `channel`：发送渠道（cli/qq/feishu）

### Heartbeat

- 每 30 分钟写入 `HEARTBEAT.md`
- 记录运行时长、内存状态、最近活动
- 促进 Agent 在空闲期进行自我反思

---

## 🔧 部署指南

详见 [DEPLOY.md](DEPLOY.md)

### 快速命令

```powershell
# 首次部署
.\tools\deploy_esp32c5.ps1 -Port COM9 -Erase

# 日常更新
.\tools\deploy_esp32c5.ps1 -Port COM9

# 只查看日志
.\tools\deploy_esp32c5.ps1 -MonitorOnly -Port COM9
```

---

## 📚 更多文档

| 文档 | 内容 |
|------|------|
| [DEPLOY.md](DEPLOY.md) | 详细部署指南 |
| [CONFIG.md](CONFIG.md) | 所有配置项说明 |
| [USAGE.md](USAGE.md) | 使用手册与对话示例 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统架构详解 |
| [ESP32C5_MEMORY_OPTIMIZATION.md](ESP32C5_MEMORY_OPTIMIZATION.md) | 内存优化指南 |

---

## 🖥️ 硬件规格

| 项目 | 规格 |
|------|------|
| **芯片** | ESP32-C5 (RISC-V 单核) |
| **CPU 频率** | 240 MHz |
| **内部 SRAM** | ~400 KB |
| **外部 PSRAM** | 8 MB (Octal-SPI @ 80MHz) |
| **Flash** | 16 MB (QIO @ 80MHz) |
| **WiFi** | 802.11 b/g/n/ax (WiFi 6) |
| **可用 SPIFFS** | ~12.6 MB |

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！详见 [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

**让 AI 跑在 ESP32-C5 上！** 🚀