导读： 大多数 agent 教学项目教的是"一个人在终端里和 AI 对话"。但生产级 agent 要面对多平台并发、跨重启记忆、自我进化。本文从真实可运行的 Hermes 教学仓库出发，拆解一个生产级自主 agent 的五层架构，并带你走完一条消息从入口到持久化的完整旅程，为整个系列画好全局地图。
你学过的 agent 教程，可能漏掉了最重要的事
先问自己一个问题：你见过的 agent 项目，是不是长这样？
一个 while True 循环，里面调模型、调工具、再调模型。看起来挺对，但一旦你要把它部署到 Telegram 上，同时服务 100 个用户，再让它跨重启记住昨天聊了什么，这个"循环+工具"的架构就崩了。
Hermes Agent 从一开始就没走这条路。它是一套跨平台的自主 agent：同一套核心循环可以挂在 Telegram、Discord、微信、飞书等 15+ 平台；命令可以在 Docker、SSH、云端执行；对话持久化到 SQLite，支持全文搜索。更特别的是，agent 能自己创建编辑技能文件，每 10 轮自动 fork 一个后台副本审视对话、更新记忆。模型接入走 OpenAI 兼容接口，支持 200+ 家提供商。
这套能力的背后，是一张清晰的分层架构。
五层架构：从上到下，每层只干一件事
生产级 agent 由五层组成，从上到下各司其职。
第一层：入口层------用户从哪里来
CLI、Telegram、Discord、微信......每个入口的交互方式完全不同，但它们都做同一件事：把用户输入统一成同一种内部格式，交给核心循环。
第二层：核心循环层------agent 的大脑
模型思考 → 调工具 → 结果回写 → 继续。这是整个系统的心脏。注意一个细节：核心循环是同步的，异步工具通过事件循环桥接。
第三层：工具与智能层------能力目录
工具自注册、记忆、技能、审批。这一层最大的特点是添加新工具不需要修改核心循环代码。工具文件被导入时自动登记到注册表，核心循环只认注册表。
第四层：执行环境层------命令在哪里跑
本地、Docker、SSH、云端。这一层是抽象接口，对上层完全透明。上层只管说"执行这条命令"，至于命令跑在哪，由环境层决定。
第五层：持久化层------跨重启存活
SQLite 会话、MEMORY.md、技能文件。对话记录、长期记忆、技能定义，全部落盘。agent 重启后，一切照旧。
一条消息的完整旅程：CLI 场景 8 步
光看架构图不够，我们跟着一条消息走一遍完整流程。
假设你在终端输入了一句话，接下来发生这些事：
- 用户在终端输入一句话
- CLI 创建 AIAgent 实例
- AIAgent 组装 system prompt：SOUL.md（人设）+ MEMORY.md / USER.md（记忆）+ HERMES.md 或 AGENTS.md（项目配置）+ 工具定义和技能清单
- messages + system prompt + tools 一起发给模型 API（OpenAI SDK，所有提供商同一个接口）
- 模型返回：纯文本 → 显示结束；tool_calls → 继续
- 对每个 tool_call：查工具注册表 → 危险命令检测 → 执行 → 结果以 tool 角色写回
- 回到第 4 步，继续下一轮
- 循环结束后，整个会话持久化到 SQLite
注意第 5 步里的"危险命令检测"：生产级 agent 不会让你在终端里随便执行 rm -rf /。
Gateway 场景：同一个核心，不同入口
那 Telegram 上的消息怎么走？区别只在入口和出口。
Gateway 场景下：适配器收到消息 → 转统一格式 → Gateway 按 chat_id 找到或创建会话 → 创建 AIAgent 实例 → 后面和 CLI 完全一样 → 回复经适配器发回。
区别只在入口和出口，核心循环完全一样。这正是分层的价值：核心逻辑写一遍，就能挂到所有平台。
五个关键设计决策：为什么这样做
1. OpenAI SDK 作为唯一 API 客户端
不同提供商只是不同的 base_url。从 OpenRouter 切到 Anthropic 或本地端点，不改一行代码，只改配置。所有消息统一用 OpenAI 格式（role / tool_calls / tool_call_id）。
2. 核心循环是同步的
大部分工具（文件读写、终端命令）本身是同步的。同步循环错误处理和调试简单。少量异步工具通过持久化事件循环桥接。模式可以概括为：同步主体 + 异步桥接。
3. 工具用自注册，而非中心配置
工具文件被导入时自动调用注册表 register() 登记。导入链：注册表不依赖工具 → 工具依赖注册表 → 编排层导入所有工具触发注册 → 核心循环使用编排层。
加新工具，只写一个文件，什么都不用改。
4. SQLite 而非文件系统
Gateway 场景下，多平台消息可能同时到达。WAL 模式支持并发读写，FTS5 支持全文搜索历史会话。
5. agent 能改自己
这是区别于 LangChain / AutoGen 的核心。三个机制：
- Background Review：每 N 轮 fork 后台副本审视对话，自动更新 MEMORY.md / USER.md 或创建 skill
- Skill 创作闭环：skill_manager_tool 创建、编辑、补丁自己的 skill
- Trajectory + RL 流水线：对话轨迹压缩成训练数据
运行时生效（学习）+ 离线生效（进化）= 用 → 记 → 抽象 → 训练 → 更好地用。
关键状态存在哪里
理解 agent 架构，最重要的是知道每个状态存在哪。
- messages → 当前对话（运行时）
- session → 对话持久化（SQLite）
- memory → 跨会话知识（文件 MEMORY.md / USER.md）
- config → 运行配置（YAML + 环境变量）
- 工具注册表 → 能力目录（工具名 → 处理函数映射）
- SOUL.md / MEMORY.md / HERMES.md → 长期上下文（人设 / 记忆 / 项目配置）
- 执行环境 → 命令在哪跑（抽象接口，对上层透明）
把这四层分清，就不会把"当前对话"和"长期记忆"混为一谈。
五阶段学习路径：从能跑的单 agent 到自我进化
这个仓库把整个学习过程拆成五个阶段，共 27 章（s01~s27），其中 26 章配有可运行的 Python 参考实现（s24 插件架构仅有文档，可独立阅读）。
| 阶段 | 章节 | 目标 |
|---|---|---|
| 1 | s01-s06 | 做出能跑的单 agent：对话循环、工具注册、SQLite 持久化、提示词组装、上下文压缩、错误恢复 |
| 2 | s07-s11 | 补智能和安全：记忆、技能管理、危险命令审批、子 agent 委派、配置系统 |
| 3 | s12-s15 | 接入多平台：Gateway 架构、平台适配器、终端后端抽象、定时任务 |
| 4 | s16-s19 | 高级能力：MCP、浏览器自动化、语音视觉、CLI 与 Web 界面 |
| 5 | s20-s24 | 自我进化与生产化：后台审视、技能创作闭环、Hook 系统、trajectory 与 RL、Plugin 架构 |
怎么读这个仓库？关键在"累进式快照"：agents/sXX.py 是完整可运行的，每章都包含前面所有章节的代码。你不用翻前面的文件，直接看最新的即可。
learn-hermes-agent/
├── agents/ # 每章一个可运行的 Python 参考实现（s01~s27）
├── docs/zh/ # 中文主线文档
├── docs/en/ # 英文文档
├── illustrations/ # 每章配套黑板风格概念插图
├── tests/ # 冒烟测试
├── web/ # Web 教学平台（可选）
├── .env.example
└── requirements.txt # 仅 4 个依赖：openai / PyYAML / fastapi / uvicorn依赖只有 4 个，跑起来不会有什么环境噩梦。
避坑：三个最容易卡住的地方
Gateway 和 CLI 是竞争关系吗？
不是。它们是同一个核心循环的两个不同入口，这一点想通了，分层架构的核心价值也就理解了。
工具、技能、MCP 有什么区别？
- 工具：硬编码在代码里的能力
- 技能：agent 运行时可创建编辑的能力文件
- MCP：通过外部协议接入的第三方能力
三者是不同层级的扩展机制，不是一回事。
为什么这么多配置来源？
不同场景需要不同配置：CLI 开发、Telegram 生产、Docker 隔离。用优先级链合并，而不是硬编码。
小结：架构的价值，在于应对复杂性
回到开头的问题。为什么不是"一个循环+一堆工具"？
因为生产环境是复杂的：多平台并发、跨重启记忆、自我进化、安全审批，都不是一个循环能解决的。五层架构让每一层只关心自己的事，层与层之间通过清晰的接口协作。
下一篇逐行拆解百行的 Agent Loop（run_conversation 同步循环），看看核心循环到底是怎么写的。如果你正在从零搭建自己的 agent，或者想理解 LangChain 这类框架底层到底封装了什么，欢迎在评论区聊聊你目前卡在哪一步。
参考文献
- Hermes Agent 教学仓库：
docs/zh/s00-architecture-overview.md（架构总览，本文主要素材） - Hermes Agent 教学仓库：
README-zh.md（学习路径与章节索引） - Hermes Agent 教学仓库：
docs/zh/data-structures.md（messages / session / memory / config 四层状态）
需要源码在如下链接下载：