当前位置：首页 > news >正文

Hermes Agent 项目深度解析与学习教程

news 2026/6/30 6:43:37

Hermes Agent 项目深度解析与学习教程

源代码：https://github.com/NousResearch/hermes-agent

一、项目整体架构分析

核心定位

Hermes Agent 是一个自我进化的 AI Agent 框架，由 Nous Research 构建。最大特点：

🧠 **学习闭环**：自动从任务中创建 Skills，跨 Session 保存记忆
🌐 **多平台统一入口**：CLI、Telegram、Discord、Slack、WhatsApp 共用同一个 Agent Core
🔧 **可扩展工具系统**：40+ 内置工具，支持 Plugin/MCP 扩展
⚡ **Prompt Cache 优先**：整个架构围绕缓存不失效设计

项目目录核心结构

hermes-agent/ ├── run_agent.py ← 最核心：AIAgent 类，驱动整个对话循环 ├── model_tools.py ← 工具注册/分发层（Tool Orchestration） ├── toolsets.py ← 工具集配置 ├── cli.py ← HermesCLI 类，交互式命令行界面 ├── hermes_state.py ← SQLite 会话存储（FTS5 全文搜索） ├── agent/ │ ├── conversation_loop.py ← 核心对话循环（约 3900 行） │ ├── system_prompt.py ← System Prompt 三层组装 │ ├── memory_manager.py ← 记忆管理 │ └── transports/ ← 多模型后端适配器 ├── tools/ │ ├── registry.py ← 工具注册中心（核心） │ ├── terminal_tool.py ← 终端执行 │ ├── browser_tool.py ← 浏览器自动化 │ └── environments/ ← 终端后端（local/docker/ssh/modal） ├── gateway/ ← 消息网关（20+ 平台适配器） ├── plugins/ ← 插件系统 ├── skills/ ← 内置技能 └── cron/ ← 定时任务调度器

核心数据流

用户输入 → HermesCLI / Gateway 平台适配器 ↓ AIAgent.run_conversation() ↓ while iterations < max: 1. 组装 messages + tools schema ← system_prompt.py 2. 调用 LLM API ← agent/transports/ 3. 解析 tool_calls 4. handle_function_call() ← model_tools.py → tools/*.py 5. 追加 tool_result 到 messages 6. 无 tool_calls → 返回最终响应 ↓ post-turn hooks（记忆更新、技能学习建议）

二、五大核心设计亮点

亮点1：工具自注册 + 自发现系统（Registry Pattern）

tools/registry.py实现了自动发现 + 自注册的工具系统。每个工具文件只需在模块级别调用一次registry.register()，就能被自动发现。支持条件可用（check_fn）——例如 Home Assistant 工具只在HASS_TOKEN存在时才出现在 LLM 的工具列表中，完全不占 schema 空间。

亮点2：System Prompt 三层架构

层级内容更新频率

|------|------|---------|

stable身份（SOUL.md）、工具指南、Skills 提示 Session 内永不变

context项目上下文（AGENTS.md / .cursorrules）Session 内永不变

volatile记忆快照、用户画像、时间戳每 turn 可更新

亮点3：Prompt Cache 优先的工程哲学

整个架构铁律：System Prompt 在一个对话内字节级别稳定。任何会导致 System Prompt 中间重建的设计都被拒绝，直接节省约 70% 的 API 成本。

亮点4：技能学习闭环（Skills System）

Agent 完成复杂任务后，自动建议创建 Skill（可复用的过程记忆），存储在~/.hermes/skills/下的 Markdown 文件。下次遇到类似任务时，直接把对应 Skill 的 Markdown 注入 System Prompt，实现真正的跨会话学习。

亮点5：多平台 Gateway 架构

所有平台（Telegram/Discord/Slack/WhatsApp 等 20+）都继承自gateway/platforms/base.py，通过统一的session.py接入同一个AIAgent，真正做到"一个 Agent，处处可用"。

三、从零构建自己 Agent 的学习路线图

Phase 1：基础知识（Week 1-2）

必学概念：

**LLM Tool Calling 机制** - OpenAI Function Calling 规范，理解 messages role 交替
**Python 异步编程** - async/await 基础、事件循环管理、线程安全
**Prompt Engineering 基础** - System Prompt 设计、Chain of Thought

🎬 B站中文视频推荐：

主题视频标题UP主播放量链接

|------|---------|------|--------|------|

Function Calling【Function calling技术详解】13集保姆级讲解大模型博士-先知~566万 ⭐[BV1SJm8YtETd](https://www.bilibili.com/video/BV1SJm8YtETd/)

Function Calling【保姆级教程】Function calling功能详解赋范课堂~63万[BV1Rv411c7Qy](https://www.bilibili.com/video/BV1Rv411c7Qy/)

Prompt Engineering【吴恩达】2025提示词工程教程吴恩达深度学习~28.6万[BV1173jzNELG](https://www.bilibili.com/video/BV1173jzNELG/)

Python asyncioPython异步编程 asyncio 小白速通IT先驱者~806万 ⭐⭐[BV1WA411n7Vx](https://www.bilibili.com/video/BV1WA411n7Vx/)

asyncio 进阶3小时学会Python asyncio高性能异步编程北京艾雷克斯~91万[BV1Fv411T7qS](https://www.bilibili.com/video/BV1Fv411T7qS/)

AI Agent 全貌【全网炸裂】3天速通大模型（Prompt+LangChain+RAG+Agent）大模型--~485万 ⭐⭐[BV1hy5YzaErV](https://www.bilibili.com/video/BV1hy5YzaErV/)

Phase 2：构建最小可用 Agent（Week 3-4）

Step 1：最小 Agent Loop

from openai import OpenAI import json client = OpenAI(api_key="YOUR_KEY") def run_agent(user_message: str, tools: list, handlers: dict) -> str: messages = [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": user_message} ] while True: response = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools ) msg = response.choices[0].message if not msg.tool_calls: return msg.content # 最终回答 messages.append(msg) for tc in msg.tool_calls: result = handlers[tc.function.name](**json.loads(tc.function.arguments)) messages.append({"role": "tool", "tool_call_id": tc.id, "content": str(result)})

Step 2：工具注册系统（参考 tools/registry.py）

class ToolRegistry: def __init__(self): self._tools = {} def register(self, name, schema, handler, check_fn=None): self._tools[name] = {"schema": schema, "handler": handler, "check_fn": check_fn} def get_schemas(self): return [t["schema"] for t in self._tools.values() if not t["check_fn"] or t["check_fn"]()] def dispatch(self, name, args): return self._tools[name]["handler"](**args) registry = ToolRegistry()

Step 3：持久化记忆（参考 hermes_state.py）

import sqlite3, json class SessionStore: def __init__(self, db_path="agent.db"): self.conn = sqlite3.connect(db_path) self.conn.execute( "CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, messages TEXT)" ) def save(self, session_id, messages): self.conn.execute( "INSERT OR REPLACE INTO sessions VALUES (?, ?)", (session_id, json.dumps(messages)) ) self.conn.commit() def load(self, session_id): row = self.conn.execute( "SELECT messages FROM sessions WHERE id=?", (session_id,) ).fetchone() return json.loads(row[0]) if row else []

🎬 B站中文视频推荐（Phase 2）：

主题视频UP主播放量链接

|------|------|------|--------|------|

SQLite + Python使用python操作sqlite数据库太阳照常升起233~3.6万[BV1LW4y1S7L1](https://www.bilibili.com/video/BV1LW4y1S7L1/)

SQLite 完整版SQLite数据库全套教程罗方炜lfw2565295~65.3万[BV1pY4y1v78u](https://www.bilibili.com/video/BV1pY4y1v78u/)

RAG 知识库一文读懂大模型RAG，LLM应用开发实战卢菁博士_北大AI博士后~96.1万 ⭐[BV1dJ4m137hv](https://www.bilibili.com/video/BV1dJ4m137hv/)

LangChain AgentAI大模型应用开发：Langchain从零入门到实战IT技能树~2.2万[BV1eMXKYjEbi](https://www.bilibili.com/video/BV1eMXKYjEbi/)

Phase 3：多工具 + 多平台（Week 5-6）

接入 Telegram Bot：

from telegram.ext import Application, MessageHandler, filters async def handle_message(update, context): response = await your_agent.chat(update.message.text) await update.message.reply_text(response) app = Application.builder().token("YOUR_BOT_TOKEN").build() app.add_handler(MessageHandler(filters.TEXT, handle_message)) app.run_polling()

🎬 B站中文视频推荐（Phase 3）：

主题视频UP主播放量链接

|------|------|------|--------|------|

Telegram Bot【CS dojo】如何用Python写一个Telegram BotMarkfuGod~1.95万[BV1k64y1a795](https://www.bilibili.com/video/BV1k64y1a795/)

企业级 AgentAI大模型企业级应用：WorkFlow+Agent+LangChain+RAG马士兵老师~19.6万[BV1F89JYYEeQ](https://www.bilibili.com/video/BV1F89JYYEeQ/)

完整 Agent从零RAG入门与大模型知识库问答系统开发实战九天Hector~3.8万[BV1m682ziE9b](https://www.bilibili.com/video/BV1m682ziE9b/)

Phase 4：生产部署（Week 7-8）

Docker 容器化（参考项目 `Dockerfile` 和 `docker-compose.yml`）
VPS 部署（Hetzner $3.99/月，配合 systemd 管理进程）

🎬 B站中文视频推荐（Phase 4）：

主题视频UP主播放量链接

|------|------|------|--------|------|

Docker 部署 Python手把手教你用Docker部署Python全栈应用AIDeepCoder~2.27万[BV14zsozJEiV](https://www.bilibili.com/video/BV14zsozJEiV/)

nginx+docker 实战【Python项目部署实战】nginx+docker+部署具身智能官方教程~9880[BV1Nb4y1y7Av](https://www.bilibili.com/video/BV1Nb4y1y7Av/)

四、推荐技术栈

层次选型说明

|------|------|------|

后端语言Python 3.11+Agent 主体Web 框架FastAPIAPI 服务LLM 接入OpenRouter统一多模型入口，省钱存储SQLite → PostgreSQL起步 → 生产部署Docker + VPSHetzner $3.99/月起消息平台Telegram Bot最容易上手

五、8 周实施计划

周次目标关键成果

|------|------|---------|

Week 1环境搭建 + Tool Calling 基础能跑通一个带工具的对话Week 2实现工具注册系统自动发现 + 分发Week 3Session 持久化SQLite 存储对话历史Week 4System Prompt 优化三层结构 + 缓存友好Week 5实现 5+ 实用工具搜索/文件/Shell 等Week 6Skills 系统Markdown 注入过程记忆Week 7Telegram 接入手机可以对话Week 8Docker 部署VPS 上稳定运行