第 1 章 · 01 Hermes 定位与巨型体量切片

第 1 章 · 01 Hermes 定位与巨型体量切片

本节摘要:本节是全书第一行代码之前的地基——先说清 Hermes Agent 的定位:Nous Research 开源的自我改进 AI Agent(v0.20.5,MIT 协议,官网 hermes-agent.nousresearch.com),再交代它与 OpenClaw/Claude Code 的谱系(hermes claw migrate 与 hermes import-agent 两条迁移通道),然后直面这个项目最令人生畏的事实——巨型体量(Python 约 183 万行 = 生产 97 万 + 测试 86 万,TypeScript 约 58 万行,133 工具,28 toolsets,82+117 技能,8 记忆 provider,34 平台,37 模型 provider,30 CI 工作流,915 页文档)。体量数字不是吓唬人,而是引出本教程的核心方法:分层切片读法——根目录巨型文件是骨架,器官目录是血肉,只精读双循环主线。

内容来源:原项目源码 README.zh-CN.md、website/docs/developer-guide/architecture.md、根目录文件清单与 hermes_cli/subcommands/import_agent.py。

⚠️ 注意:不要试图"从头到尾读完"Hermes。生产 Python 约 97 万行,即使每天精读 1000 行也要两年半。本教程的读法是沿双循环主线切片——每章只打开 2~4 个文件的关键段落,行号引用如 run_agent.py:2017,其余代码当作"已存在的外围设施"。

学习目标

阅读完本节,你应当能够:

1. 一句话说清 Hermes 的定位:Nous Research 的自我改进 agent,v0.20.5,MIT 协议。
2. 复述 Hermes 的谱系:从 OpenClaw 迁移(hermes claw migrate),从 Claude Code/Codex 导入(hermes import-agent)。
3. 盘点巨型体量的关键数字(183 万行 Python、58 万行 TS、133 工具、34 平台等)。
4. 区分"根目录巨型文件"与"器官目录"两种代码组织形态,并说出各自的代表文件。
5. 掌握分层切片读法:先架构文档,再主线巨型文件,后器官目录。
6. 对照官方 learning-path.md 的三级学习路径,定位本教程在其中的位置。

一、Hermes 是什么:一个自我改进的 Agent

打开 README.zh-CN.md,第一段就给出定位:

由 Nous Research 构建的自进化 AI 代理。它是唯一内置学习闭环的智能代理——从经验中创建技能,
在使用中改进技能,主动持久化知识,搜索过往对话,并在跨会话中逐步构建对你的深度理解。
可以在 $5 的 VPS 上运行,也可以在 GPU 集群上运行。
​

拆开这句话,能看到 Hermes 的四根支柱:

模型层完全开放:Nous Portal、OpenRouter(200+ 模型)、Kimi/Moonshot、z.ai/GLM、MiniMax、小米 MiMo、DeepSeek、Qwen、OpenAI 或自定义端点,用 hermes model 一条命令切换。对中文读者特别友好的三点:原生支持微信/飞书/钉钉/QQ 机器人/企微/元宝接入;模型层原生支持 DeepSeek/Kimi/Qwen/GLM;SQLite FTS5 有专门的中文分词 C 扩展(native/fts5_cjk)。第 7 章与第 9 章会专门展开。

⚠️ 注意:README 中的"唯一内置学习闭环"是项目方的宣传口径。客观地说:闭环学习设计得如此系统化(技能创建→策展→改进→沉淀的完整生命周期)确实是 Hermes 区别于 smolagents/OpenHands 这类框架的显著特征,但"唯一"二字请读者自行判断。本教程的立场是:双循环架构值得逐行精读,这正是本书主线。

二、谱系:从 OpenClaw 迁移,从 Claude Code/Codex 导入

Hermes 不是凭空出现的。它的用户群有相当比例来自 OpenClaw(OpenClaw/Clawdbot 一系的开源个人 agent),因此 Hermes 把"搬迁"做成了一等公民功能。README.zh-CN.md 的迁移章节:

hermes claw migrate              # 交互式迁移(完整预设)
hermes claw migrate --dry-run    # 预览将要迁移的内容
hermes claw migrate --preset user-data   # 仅迁移用户数据,不含密钥
hermes claw migrate --overwrite  # 覆盖已有冲突
​

导入内容包括:SOUL.md 人格文件、MEMORY.md/USER.md 记忆、用户技能(落到 ~/.hermes/skills/openclaw-imports/)、命令白名单(审批模式)、平台配置、白名单 API 密钥、TTS 资产与工作区 AGENTS.md。安装向导 hermes setup 会自动检测 ~/.openclaw 并主动提供迁移选项——这是典型的"从竞品无缝搬家"策略。

另一条谱系通道面向 Claude Code 与 Codex 用户。hermes_cli/subcommands/import_agent.py 的参数定义:

def build_import_agent_parser(subparsers):
    ...
    parser.add_argument(
        "--from",
        dest="source_agent",
        choices=["claude-code", "codex"],
        help="Which agent to import from (default: auto-detect ~/.claude or ~/.codex)",
    )
    parser.add_argument(
        "--source",
        help="Path to the agent's config directory (default: ~/.claude or ~/.codex)",
    )
​

hermes import-agent --from claude-code(或 codex)会自动探测 ~/.claude/~/.codex 目录,把人格、记忆与配置搬进 Hermes。这条谱系信息对读码的价值在于:Hermes 的很多设计能在 OpenClaw 与 Claude Code 中找到对应物(SOUL.md 人格、命令审批白名单、AGENTS.md 上下文文件),但把这些设计真正代码化、系统化的是 Hermes 自己——例如审批从"白名单"进化成了 5714 行的 tools/approval.py 三层防线(第 3 章精读)。

三、巨型体量切片:97 万行生产 Python 怎么读

先直面数字。以下为 0.20.5 快照的体量盘点:

website/docs/developer-guide/architecture.md 给出的目录结构(节选)是最好的切片地图:

hermes-agent/
├── run_agent.py              # AIAgent — core conversation loop (large file)
├── cli.py                    # HermesCLI — interactive terminal UI (large file)
├── model_tools.py            # Tool discovery, schema collection, dispatch
├── toolsets.py               # Tool groupings and platform presets
├── hermes_state.py           # SQLite session/state database with FTS5
├── batch_runner.py           # Batch trajectory generation
│
├── agent/                    # Agent internals(循环的协作者:prompt/压缩/预算/策展)
├── hermes_cli/               # CLI subcommands and setup
├── tools/                    # Tool implementations (one file per tool)
├── gateway/                  # Messaging platform gateway(34 平台)
├── plugins/                  # platform/memory/context_engine/provider 插件
├── skills/                   # Bundled skills(外循环的技能库)
├── optional-skills/          # Official optional skills
└── website/                  # Docusaurus 文档站
​

这张地图揭示 Hermes 特立独行的代码组织:核心引擎采用"根目录巨型文件"风格;而器官采用独立目录。两条路线的分工与体量对照如下:

值得注意的是,根目录巨型文件近年来也在持续"减重":AIAgent.__init__ 已变成转发器,真正逻辑在 agent/agent_init.py(3070 行),主循环本体也搬到了 agent/conversation_loop.py(8598 行)——本教程按现行结构讲解,行号引用以 0.20.5 快照为准。

读码顺序因此清晰了:

1. 先读官方架构文档(architecture.md 与 agent-loop.md,合计约 500 行)建立坐标。
2. 再读主线巨型文件的关键段落:第 2 章解剖 run_agent.py 主循环,第 3 章解剖 model_tools.py/toolsets.py。
3. 后按器官下钻:技能(第 4 章)、记忆(第 5 章)、上下文(第 6 章)、网关(第 7 章)、协作(第 8 章)。
4. 测试当规格书读:86 万行测试是行为的精确定义,例如 tests/agent/test_anthropic_thinking_block_order.py 直接解释了消息格式转换的一条铁律。

官方 website/docs/getting-started/learning-path.md 提供了使用层的三级路径:Beginner(安装→快速开始→CLI→配置,约 1 小时)、Intermediate(会话→消息平台→工具→技能→记忆→cron,约 23 小时)、Advanced(架构→添加工具→创建技能→贡献,约 46 小时)。本教程位于 Advanced 路径的更深处——官方文档讲"怎么用、怎么加",本教程讲"为什么这样实现":agent loop 的可中断调用、registry 的自注册发现、审批的三层防线,这些是官方文档的空白。

💡 循环要点:巨型体量本身就是 Hermes 的一件"作品"——133 个工具、34 个平台、8 种记忆后端能共存,靠的不是天才的直觉,而是几条贯穿全库的纪律:一工具一文件+自注册(第 3 章)、三种 API 模式收敛到统一消息格式(第 2 章)、平台差异留在入口层而核心 AIAgent 平台无关(architecture.md 的 Platform-agnostic core 原则)。读巨兽,先读它的纪律。

本节要点回顾

1. Hermes 是 Nous Research 开源的自我改进 AI Agent,v0.20.5,MIT 协议,官网 hermes-agent.nousresearch.com。
2. 四根支柱:会话与工具(run_agent.py)、闭环学习(skills+curator)、持久记忆(SQLite+FTS5+8 provider)、随处运行(34 平台+6 终端后端)。
3. 谱系双通道:hermes claw migrate 从 OpenClaw 迁移(含 SOUL.md/记忆/技能/白名单/密钥);hermes import-agent --from claude-code|codex 从 Claude Code/Codex 导入。
4. 体量:Python 约 183 万行(生产 97 万+测试 86 万)+TS 约 58 万行;133 工具/28 toolsets/82+117 技能/8 记忆 provider/34 平台/37 模型 provider/30 CI/915 页文档。
5. 代码组织:根目录巨型文件(run_agent.py 9215 行/cli.py 21663 行/hermes_state.py 14637 行)+器官目录(agent/tools/plugins/gateway/skills)。
6. 分层切片读法:架构文档→主线巨型文件关键段→器官下钻→测试当规格书。
7. 官方 learning-path.md 三级(Beginner 约 1 小时/Intermediate 约 23 小时/Advanced 约 46 小时),本教程是 Advanced 的代码级深化。

下一节把地图升级为心智模型:内循环(会话)与外循环(自我改进)——这两条循环是全书十章的组织轴,也是 Hermes 区别于普通 agent 的灵魂。