Hermes Agent · 中文源码精读教程

Hermes Agent · 中文源码精读教程

双循环:拆解一个"自我改进的 AI Agent"——内循环跑会话,外循环让它越用越强

这本教程讲什么

这是一份带读源码的 Hermes Agent 精读教程。

Hermes Agent 是 Nous Research 开源的自我改进 AI Agent(self-improving AI agent),MIT 协议,版本 0.20.5。它不止是一个"能调工具的 agent"——它内置完整的学习闭环:从经验中创建技能(skills)、在使用中改进技能、持久化记忆、跨会话搜索历史对话。用得越多,它越强。

这个项目是真正的巨兽:Python 约 183 万行(生产约 97 万 + 测试 86 万)+ TypeScript 约 58 万行;133 个工具、28 个工具集、82 个内置技能 + 117 个可选技能、8 种可插拔记忆后端、34 个消息平台(含微信/飞书/钉钉/QQ 机器人/企微/元宝)、37 个模型 provider(含 DeepSeek/Kimi/Qwen/GLM/MiniMax)、30 个 CI 工作流、915 页官方文档。工程成熟度属于开源 agent 项目的第一梯队。

💡 核心心法:理解 Hermes 的钥匙是双循环——**内循环(Inner Loop)**是 agent 的会话循环(run_agent.py 的 AIAgent:接收消息→组装 prompt→调 LLM→执行工具→循环),这是所有 agent 都有的部分;**外循环(Outer Loop)**是自我改进循环(技能创建→curator 策展→使用中改进→learning_graph 沉淀→跨会话记忆),这是 Hermes 区别于普通 agent 的灵魂。本教程围绕这两个循环组织:先解剖内循环骨架,再讲行动器官(工具)、学习器官(技能★+记忆)、上下文工程(缓存铁律),然后展开社交器官(34 平台网关)、协作器官(多 Agent),最后是进化数据(训练管线)与工程纪律。

一个对中文读者极友好的事实:Hermes 原生支持微信/飞书/钉钉/QQ/企微/元宝接入,模型层原生支持 DeepSeek/Kimi/Qwen/GLM,甚至有 SQLite FTS5 的中文分词 C 扩展——本教程会用专门章节讲这些中文生态集成。

⚠️ 与官方文档的关系:官方已有中文 README 与约 44% 的中文文档站翻译(偏使用手册)。本教程定位代码级原理深挖——agent loop 源码走读、工具 registry 机制、压缩算法、curator 生命周期,这些是官方文档的空白。

双循环架构图

十章双循环路径

第 1 章 Hermes 全貌与双循环架构 ── 定位/巨型体量切片/两个循环预览
第 2 章 内循环:Agent Loop 全解剖 ── run_agent.py 9215 行
第 3 章 行动器官:工具系统 ── 133 工具/28 toolsets/审批安全
第 4 章 外循环★:技能自我改进 ── SKILL.md/curator/learning_graph
第 5 章 记忆器官 ── 有界策展+8 provider+FTS5 中文分词
第 6 章 上下文工程 ── micro-compaction/prompt caching 神圣不可侵犯
第 7 章 社交器官:34 平台网关 ── 含微信/飞书/钉钉/QQ
第 8 章 协作器官:多 Agent ── subagent/kanban 工作队列/MoA
第 9 章 中文生态与模型 provider ── DeepSeek/Kimi/Qwen+CJK 扩展
第 10 章 研究管线与工程纪律 ── 轨迹生成压缩/供应链安全/全书回顾
​

章节目录

第 1 章 Hermes 全貌与双循环架构
Hermes 是什么(Nous Research/self-improving/v0.20.5);巨型体量的分层切片(生产 97 万行 Python + 58 万行 TS 怎么读);内循环预览(AIAgent 会话循环);外循环预览(技能自我改进);与 OpenClaw/Claude Code 的谱系(hermes claw migrate/import-agent 迁移)。

第 2 章 内循环:Agent Loop 全解剖
run_agent.py(9215 行)AIAgent 类;~60 个构造参数;同步 while 循环 + 可中断 API 调用;三种 API 模式收敛(chat_completions/codex_responses/anthropic_messages 统一到 OpenAI 消息格式);消息交替规则;迭代预算(父子共享)与优雅退出;prompt 组装(agent/prompt_builder)。

第 3 章 行动器官:工具系统
一工具一文件(133 个工具文件);中央 registry 与 schema 收集(model_tools.py);28 个 toolset 分组与平台预设(toolsets.py);危险命令审批(approval);路径安全(path_security/threat_patterns);代表工具精读(terminal/browser 五后端/computer_use/file/delegate)。

第 4 章 外循环★:技能自我改进(全书高潮)
SKILL.md 开放标准(agentskills.io);82 内置 + 117 可选技能;curator 生命周期(创建→评审→启用→退役);skill_ledger/usage/provenance 记账;使用中自改进(技能被使用后迭代);learning_graph 学习图谱;从经验创建技能的完整链路。

第 5 章 记忆器官
有界策展式记忆(MEMORY.md 2200 字符/USER.md 1375 字符);memory_manager;8 种可插拔记忆 provider(honcho/mem0/hindsight/holographic/retaindb/byterover/supermemory/openviking 横向对比);FTS5 会话搜索;native/fts5_cjk 中文分词 C 扩展。

第 6 章 上下文工程
prompt caching 神圣不可侵犯的设计铁律(prompt_caching);prompt 组装流水线(官方 prompt-assembly.md);上下文压缩(context_engine/compressor);micro-compaction 微压缩(docs/micro-compaction);token 估算。

第 7 章 社交器官:34 平台网关
单进程 34 平台网关(gateway/ 11.4 万行);telegram/discord/slack/whatsapp/signal/matrix;国内平台(微信 weixin/飞书 feishu/钉钉 dingtalk/QQ 机器人 qqbot/企微 wecom/元宝 yuanbao);跨平台会话连续性;语音转写。

第 8 章 协作器官:多 Agent
subagent_lifecycle(委派子 agent 隔离并行);迭代预算父子共享;kanban 多 Agent 工作队列(配 kanban 教程 10 连图);MoA(mixture-of-agents);verification 引擎(子 agent 结果验证)。

第 9 章 中文生态与模型 provider
37 个模型 provider 插件(plugins/);国内模型(deepseek/kimi/minimax/qwen/xiaomi/zai-GLM/alibaba);5 种 provider 适配器(anthropic/gemini native/bedrock/vertex/codex responses);profile 路由(docs/profile-routing);CLI 17 语言本地化(含 zh.yaml)。

第 10 章 研究管线与工程纪律
batch_runner 批量轨迹生成;trajectory_compressor(保护首尾轮次/压缩中间/替换摘要——训练工具调用模型);evals 基准;供应链安全(精确锁版==X.Y.Z 应对 2026 PyPI 攻击/OSV 扫描/supply-chain-audit);mcp_serve(Hermes 作为 MCP server);UI 三件套概览(cli.py 2.1 万行 TUI/TS TUI/Electron);全书回顾。

适合读者

• 想理解"自我改进 agent"完整闭环的 AI 工程师/研究者
• 要构建长生命周期、跨会话记忆的 agent 的开发者
• 对多平台网关(尤其国内微信/飞书/钉钉/QQ)接入感兴趣的全栈工程师
• 研究技能系统、上下文压缩、多 Agent 编排的架构师

前置知识:Python 进阶(能读大文件/异步/hooks 概念);agent 基本概念(LLM/tool calling/会话);可选:SQL(FTS5)/TS(UI 部分)。

注意事项

• 双循环主线:每章标注属于内循环/外循环/器官/生态哪一层
• 源码带行号引用如 run_agent.py:1234
• > 💡 **循环要点**:... 标注每节精华
• > ⚠️ **注意**:... 标注巨型代码库的导航提示/版本陷阱/安全边界

⚠️ 重要说明:Hermes 体量巨大(生产约 155 万行),本教程聚焦双循环主线与核心器官的代码级原理,不可能逐文件精读;官方 915 页文档(44% 有中文)是使用层补充。

关于源码版本

对照源码来自 hermes-agent-main(MIT,Nous Research),版本 0.20.5(2026-08 快照)。核心引擎为根目录巨型文件风格(run_agent.py 9215 行/cli.py 2.1 万行/hermes_state.py 1.5 万行),器官在 agent//tools//plugins//gateway//skills/ 等目录。