内容
<div align="center">
<img src="docs/screenshot.png" alt="Hermes Lite — 智能助理" width="100%">
<br/>
# Hermes Lite
**中文:** 是一款运行在个人电脑上的智能助理，连接 12 个专业代理获取真实数据 — 健康、公共合同、GitHub、任务、PDF 文件。具备实时流媒体、自动执行、Telegram 集成和 MCP 服务器，支持 Cursor/Claude Desktop。不是一个通用的聊天系统：每个代理都有自己的上下文、工具和 LLM 模型，并自动选择。
**<br/>**
[](https://python.org)
[](https://flask.palletsprojects.com)
[](https://groq.com)
[](https://aistudio.google.com)
[](https://ollama.ai)
[](https://supabase.com)
[](https://github.com/simoesleandro/hermes-lite/commits)
[](https://github.com/simoesleandro/hermes-lite/issues)
<br/>
[📖 完整文档](docs/GUIA-HERMES-LITE.md) ·
[🐛 反馈问题](https://github.com/simoesleandro/hermes-lite/issues) ·
[💡 建议功能](https://github.com/simoesleandro/hermes-lite/issues)
</div>
---
## 📋 目录 / Table of Contents
- [关于](#-关于--about)
- [代理](#-代理--agents)
- [架构](#-架构--architecture)
- [模型路由](#-模型路由--model-router)
- [功能](#-功能--features)
- [MCP 服务器](#-mcp-服务器-cursor--claude-desktop)
- [Cronos](#️-cronos--调度器)
- [Vigia](#️-vigia--系统监视器)
- [技术栈](#-技术栈)
- [安装](#-安装--setup)
- [环境变量](#-环境变量--environment-variables)
- [Windows 服务](#-windows-服务-winsw)
- [项目结构](#-项目结构)
- [测试](#-测试--tests)
- [路线图](#-路线图)
- [作者](#-作者--author)
---
## 📌 关于 / About
**中文:**
Hermes Lite 是一款个人智能助理，运行在您的电脑上，连接 12 个专业代理获取真实数据 — 健康、公共合同、GitHub、任务、PDF 文件。具备实时流媒体、自动执行、Telegram 集成和 MCP 服务器，支持 Cursor/Claude Desktop。不是一个通用的聊天系统：每个代理都有自己的上下文、工具和 LLM 模型，并自动选择。
---
## 🤖 代理 / Agents
| 代理 | 专家领域 | LLM 级别 | 数据 / 工具 |
|--------|--------------|----------|---------------------|
| **知识** | 通用问题、研究、技术 | 中级 | `user_facts` 记忆，RAG 上下文 |
| **开发** | 代码、错误、架构、Git | 中级 | `git_status`、`git_diff`、`git_log` |
| **健康** | 营养、水分、体重、穿戴设备 | 简单 | Supabase sys-health — 通过聊天记录水和体重 |
| **训练** | 健身、跑步、Hevy、Amazfit | 中级 | sys-health: 训练、分析、睡眠 |
| **生产力** | GTD、任务、焦点 | 中级 | `tasks` 表（收件箱 / 今日 / 本周 / 已完成） |
| **监察** | 公共合同 RJ、PNCP、警报 | 中级 | SQLite Sentinela RJ |
| **法律** | 行政法、法律 14.133/2021 | 高级 | 从调查员接收任务 |
| **调查员** | 多源档案，ReAct 模式 | 高级 | CNPJ、合同、警报、网络搜索 |
| **阅读器** | PDF — 总结和问题 | 高级 | 上传 PDF（最高 10 MB，100 页） |
| **分析师** | SQL、Python、内联图表 | 高级 | 沙盒 pandas/matplotlib/plotly |
| **运维** | Windows 服务（Hermes、Cronos、Vigia） | 简单 | `sc start/stop`，HTTP 健康检查 |
| **雷达** | GitHub 开源项目精选 | 中级 | GitHub Search API — 每日摘要，0-10 评分 |
---
## 🏗 架构 / Architecture
```
输入通道：
Web UI（端口 5050） → AgentHub → 模型路由 → LLM
Telegram 机器人 → AgentHub → 模型路由 → LLM
MCP 服务器（stdio） → AgentHub → 模型路由 → LLM
外部数据：
sys-health（Supabase PostgreSQL） — 个人健康
Sentinela RJ（SQLite） — 公共合同
GitHub API — 雷达和收件箱
自动化：
Cronos（调度器） → Telegram / Discord
Vigia（监视器） → Discord
```
---
## ⚡ 模型路由
三级自动降级 — 用户无感切换：
```
简单 → Gemma 4 12B（本地 Ollama） → Groq → Gemini
中级 → Groq（llama-3.3-70b） → Gemini → Gemma 4
高级 → Gemini 2.5 Flash → Groq → Gemma 4
```
- **本地 Gemma 4** 通过 Ollama — 零成本，无外部数据发送
- 如果一个提供商宕机，则自动尝试下一个
- UI 上的徽章显示哪个 LLM 响应（gemma / groq / gemini）以及延迟
---
## ✨ 功能 / Features
- ✅ **12 个专业代理**，具备关键词自动路由
- ✅ **模型路由，3 级降级**，无感切换
- ✅ **本地 Gemma 4 12B** 通过 Ollama — 零成本，完全隐私
- ✅ **持久记忆** — 从对话中自动提取 `user_facts`
- ✅ **RAG** — 具备语义搜索的知识库（Gemini 嵌入）
- ✅ **GTD** — 通过聊天和 API 实现任务管理
- ✅ **MCP 服务器** — 为 Cursor 和 Claude Desktop 提供 30+ 工具
- ✅ **双向 Telegram** — 完整聊天、操作按钮、PDF/图像上传
- ✅ **持续工作流** — 持久化 Investigador → Jurídico 工作流
- ✅ **GitHub 雷达** — 开源项目精选，每日 0-10 评分
- ✅ **GitHub 收件箱** — PR、评论、问题、CI 晨报
- ✅ **CI Webhook** — CI 失败时通知 Telegram
- ✅ **SSE 流媒体** — 实时接收 token
- ✅ **全文搜索** — 所有对话均支持全文搜索
- ✅ **Markdown 导出** — 任意对话导出
- ✅ **内联图表** — 分析师代理生成并在聊天中显示 PNG
- ✅ **自动备份** — Cronos 在 03:00 进行数据库备份（保留 14 天）
- ✅ **136 测试** — 覆盖代理、路由、事实、仪表盘和 Webhook
---
## 🔌 MCP 服务器 (Cursor / Claude Desktop)
```bash
python mcp_server.py
```
**30+ 工具**，适用于 Cursor 和 Claude Desktop：
| 类别 | 工具 |
|-----------|-------------|
| 核心 | `hermes_chat`、`list_agents`、`classify_message`、`hermes_health` |
| 监察 | 总结、警报、供应商搜索、统计、顶级合同 |
| sys-health | 每日总结、记录水、记录体重 |
| 调查员 | CNPJ、合同、警报、网络搜索 |
| GTD | 列表、创建、更新任务 |
| 知识 | RAG 搜索、列出文档 |
| Git | 状态、差异、日志 |
| 事实 | 列表、更新、删除、批准待处理 |
| 工作流 | `workflow_investigacao_parecer`、Sentinela↔Investigador↔Jurídico 交接 |
| GitHub | 收件箱、雷达运行/最新 |
| Telegram | `telegram_notify` |
> 配置：复制 `mcp-config.example.json` 到 Cursor。
---
## 🕐 Cronos — 调度器
Windows 服务 `HermesCronos`，通过 Telegram 或 Discord 通知：
| 任务 | 时间（BRT） | 通道 |
|--------|---------------|-------|
| ☀️ 晨报 | 07:30 每天 | Telegram / Discord |
| 📊 健康总结 | 22:00 每天 | Telegram / Discord |
| 🔎 Sentinela 报告 | 09:30 每周一 | Telegram / Discord |
| 💾 数据库备份 | 03:00 每天 | — |
| 🧠 用户事实审查 | 10:00 每周日 | Telegram |
```bash
python -m cronos.cronos
python -m cronos.cronos --test # 立即触发所有任务
```
---
## 👁️ Vigia — 系统监视器
每 **5 分钟** 检查一次，并在状态变化时通过 Discord 警报：
| 服务 | 检查 |
|---------|-------------|
| Hermes Lite | HTTP localhost:5050 |
| sys-health | Supabase 连接 |
| Gemma 4 | Ollama 响应 |
| Cronos | Windows 服务活动 |
```bash
python -m vigia.vigia
```
---
## 🛠 技术栈
| 层 | 技术 |
|--------|------------|
| 后端 | Python 3.11+ · Flask · Waitress |
| 前端 | HTML/CSS/JS 纯净 · glassmorphism 暗黑主题 |
| 流媒体 | SSE（服务器发送事件） |
| 本地数据库 | SQLite (`db/hermes.db`) |
| 本地 LLM | Gemma 4 12B 通过 Ollama |
| 远程 LLM | Groq（llama-3.3-70b）· Gemini 2.5 Flash |
| 健康 | Supabase PostgreSQL（sys-health） |
| IDE | MCP 服务器 stdio — Cursor / Claude Desktop |
| 自动化 | Cronos（APScheduler）· Vigia（监视器） |
| 测试 | pytest — 136 测试 |
---
## 🚀 安装 / Setup
### 要求 / Prerequisites
- Python 3.11+
- [Ollama](https://ollama.ai) 搭配 `gemma4:12b` — `ollama pull gemma4:12b`
- Groq 免费密钥，[console.groq.com](https://console.groq.com)
- Gemini 免费密钥，[aistudio.google.com](https://aistudio.google.com)
- 配置 Supabase（sys-health）— 可选
### 安装 / Installation
```bash
# 克隆仓库
git clone https://github.com/simoesleandro/hermes-lite
cd hermes-lite
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 使用您的密钥编辑 .env
# 运行项目
python app.py
# → http://localhost:5050
```
---
## 🔐 环境变量 / Environment Variables
| 变量 | 描述 | 默认值 |
|----------|-----------|--------|
| `GROQ_API_KEY` | Groq — 中级 | — |
| `GEMINI_API_KEY` | Gemini Flash — 高级 | — |
| `OLLAMA_GEMMA_MODEL` | 本地 Ollama 模型 | `gemma4:12b` |
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase URL（sys-health） | — |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase 服务角色密钥 | — |
| `SENTINELA_DB_PATH` | SQLite Sentinela RJ | — |
| `GITHUB_TOKEN` | GitHub 雷达 + 收件箱 | — |
| `GITHUB_USER` | GitHub 用户 | — |
| `TELEGRAM_BOT_TOKEN` | Telegram 机器人 | — |
| `TELEGRAM_CHAT_ID` | 目标聊天 ID | — |
| `NOTIFY_CHANNEL` | Cronos 通道 | `telegram` |
| `KNOWLEDGE_RAG` | 启用 RAG | `0` |
| `USER_FACTS_AUTO` | 自动提取事实 | `0` |
> 完整列表：[`.env.example`](.env.example)
---
## 🪟 Windows 服务 (WinSW)
| 服务 | XML | 端口 |
|---------|-----|-------|
| HermesLite | `hermes-lite-service.xml` | 5050 |
| HermesCronos | `cronos-service.xml` | — |
| hermes-vigia | `vigia-service.xml` | — |
---
## 📁 项目结构
```
hermes-lite/
├── app.py # UI 入口（:5050）
├── api_server.py # CORS 入口
├── app_factory.py # Flask 工厂 — 所有路由
├── model_router.py # 提供商之间的路由和降级
├── mcp_server.py # MCP 服务器 — 30+ 工具
├── agents/ # 12 个专业代理
├── services/ # 外部客户端、Telegram、RAG、工作流
├── db/ # hermes.db + 数据库类
├── cronos/ # 调度器 + 任务
├── vigia/ # 系统监视器
├── static/ # Web UI（HTML/CSS/JS）
├── tests/ # 136 个 pytest 测试
├── exports/ # 意见、雷达 Markdown
└── backups/ # 自动夜间备份
```
**主流程：
```
用户消息（Web / Telegram / MCP）
↓
classify_agent() — 正则表达式 + LLM 降级
↓
专业代理注入真实数据
↓
模型路由 → Gemma4 / Groq / Gemini
↓
通过 SSE 流媒体响应
```
---
## 🧪 测试 / Tests
```bash
# 运行所有测试
pytest
# 覆盖率
pytest --cov=agents --cov-report=term-missing
# 特定测试
pytest tests/test_classify_agent.py -v
```
> **136 测试**，覆盖路由、事实、仪表盘、Webhook、sys-health、备份和工作流。
---
## 🗺 路線圖
- [x] 12 个专业代理，具备自动路由
- [x] 具备 3 级降级的模型路由
- [x] 通过 Ollama 实现本地 Gemma 4 12B（零成本）
- [x] 具备 30+ 工具的 MCP 服务器
- [x] 持久记忆，具备 `user_facts`
- [x] 具备语义搜索的 RAG
- [x] 通过聊天和 API 实现 GTD
- [x] 双向 Telegram，具备操作按钮
- [x] Investigador → Jurídico 持久工作流
- [x] GitHub 雷达和收件箱
- [x] Cronos 调度器，具备 5 个自动任务
- [x] Vigia 监视器，具备 Discord 警报
- [ ] 原生移动界面（PWA）
- [ ] 电子邮件代理（Gmail MCP）
- [ ] 具备身份验证的公共部署
---
## 👤 作者 / Author
<div align="center">
**Leandro Simões**
[](https://linkedin.com/in/leandro-sim%C3%B5es-7a0b3537b)
[](https://github.com/simoesleandro)
[](https://simoesleandro.github.io/portfolio)
*全栈 · 应用智能 · 民间科技*
</div>
---
<div align="center">
在 🇧🇷 里约热内卢使用 ☕ 和 AI 制作 / Made with ☕ and AI in 🇧🇷 Rio de Janeiro
</div>
