2 · 两个系统的宏观定位与架构总图
2.1 用一句话说清各自的定位
一个把「单次终端会话的 token 效率」压榨到极限的编程助手。
它所有那些乍看之下莫名其妙的设计 —— 缓存编辑、五级上下文治理阶梯、工具清单分区排序、错误扣留机制 —— 追根溯源都指向同一个目标：在不丢失任何上下文信息的前提下，让提示词缓存的命中率尽可能高、让每一轮要重发的输入 token 尽可能少。
（「提示词缓存」和「输入 token」这两个概念如果还不清楚，请回看第 1.8 节和第 1.2 节。）
一个长期在线的、可以从任意聊天软件被找到的、能自我演化的自主智能体。
它的核心设计 —— 多身份隔离、统一入口网关、上下文引擎与记忆系统的插件化、全息记忆 —— 都指向另一个目标：让一个智能体实例长期活着、跨越多次会话记住事情、并且能被任何人从任何渠道叫醒。
2.2 架构总图
下面两张图分别是两个系统的整体结构。如果你没看过这类图，先读一下怎么看：
这两张图该怎么看
- 横向的一条条虚线框叫做「层」。数据从最上面一层进来，一层一层往下穿，处理完再往上返回。每层只跟相邻的层打交道，这样改动一层不会影响其他层。
- 框里的圆角矩形是具体的软件模块。名字通常就是源代码里真实的文件名或类名。
- 实线箭头表示「同步调用」—— 调用方会停下来等结果。虚线箭头表示「异步返回」或「旁路」—— 不阻塞主流程。
- 颜色不代表技术类型，代表「角色」。比如所有和数据存储有关的模块都是紫色，不管它用的是数据库还是文件。
- 发光加粗的那个模块是整个系统的核心。图上只有一到两个。
Claude Code 的六层结构
逐层解释这张图上的每个名词：
| 层 | 模块名 | 它负责什么 |
|---|---|---|
| L6 入口层 把人的意图变成一次程序调用 |
REPL |
Read-Eval-Print Loop 的缩写，意思是「读取-求值-打印 循环」。就是你在终端里看到的那个可以持续对话的交互界面。 |
print -p | 「无头模式」。不显示交互界面，直接给一个问题、拿一个答案就退出。适合写在脚本里自动化调用。 | |
Agent SDK | SDK 是 Software Development Kit（软件开发工具包）的缩写。让别的程序可以把 Claude Code 当成一个库来调用。 | |
IDE Bridge | IDE 是 Integrated Development Environment（集成开发环境）的缩写，指 VS Code、JetBrains 这类编程软件。这个模块负责和它们对接。 | |
| L5 会话层 管一整场对话的状态 |
QueryEngine |
「查询引擎」。一场对话对应一个它的实例。它持有这场对话的全部消息记录、累计花费、读过哪些文件、被拒绝过哪些操作。用户提问多少次，它就被调用多少次，但它本身只创建一次。 |
| L4 循环层 ★ 整个系统的心脏 |
queryLoop |
智能体主循环。这里实现了第 1.5 节讲的那个「调模型 → 执行工具 → 再调模型」的往复过程，以及所有的错误恢复逻辑。它是一个状态机，有 7 条命名好的恢复路径。第 4 章整章讲它。 |
Context Ladder |
「上下文阶梯」。每次调用模型之前，负责把上下文压缩到能塞进上下文窗口。分五级，从免费的到最贵的依次尝试。第 6 章整章讲它。 | |
| L3 工具执行层 | Orchestrator |
「编排器」。模型一次可能写好几张便条（工具调用），这个模块决定哪些可以同时执行、哪些必须排队一个个来。 |
Permissions | 「权限系统」。判断某个工具调用该不该被允许执行。有一条 10 步的判定链。第 7 章整章讲它。 | |
Hooks | 「钩子」。让用户可以在特定时机（比如工具执行前、执行后）插入自己的脚本。 | |
| L2 供应商层 | Anthropic API |
负责实际的网络通信：把上下文发给 Anthropic 公司的服务器、处理网络失败重试、标记缓存分界点、在主模型过载时切换到备用模型。 |
| L1 持久化层 | Transcript |
「对话记录」。把整场对话写到磁盘上的文件里，格式是 JSONL（每行一条 JSON 记录）。这样程序崩溃或用户关掉窗口后还能恢复。 |
memdir | 「记忆目录」。存放跨会话的长期记忆，都是人类可读的纯文本文件。CLAUDE.md 是其中最主要的一个，里面写项目规范和用户偏好。 |
Hermes 的六层结构
| 层 | 模块名 | 它负责什么 |
|---|---|---|
| 入口层 22 个平台 |
Slack / Telegram / Discord / 飞书 / 企业微信 / … |
这些都是常见的聊天软件。Hermes 支持从其中任何一个给智能体发消息。CLI 是 Command Line Interface（命令行界面）的缩写，ACP 是它和编程软件对接用的协议。 |
| 网关层 ★ Claude Code 没有这一层 |
Gateway |
「网关」。一个长期不关闭的后台进程。它把 22 个平台的差异抹平，做统一的会话路由、用户授权、定时任务触发。 它带来的能力是：你在电脑上用 Slack 和智能体聊到一半，出门换成手机上的 Telegram 继续聊，对话上下文完全连续。因为对智能体来说，这始终是同一场会话，只是消息的进出口换了。 PlatformAdapter ABC 里的 ABC 就是第 1.9 节讲的「抽象基类」—— 它规定了「任何一个聊天平台想接进来，必须提供哪些功能」。 |
| 循环层 | run_conversation |
Hermes 的智能体主循环，对应 Claude Code 的 queryLoop。第 4 章会把两者对照着讲。 |
ContextEngine |
「上下文引擎」。这是一个抽象基类，也就是一个可以被整体替换掉的插座。Claude Code 把上下文治理策略写死在代码里，Hermes 则把它定义成接口交给第三方去实现。这是两个系统最根本的架构差异，第 6 章详谈。 | |
| 工具层 | TOOLSETS |
「工具集」。它不是工具的实现，而是工具的投放策略 —— 规定「在什么场景下让模型看到哪些工具」。这是 Hermes 最值得借鉴的一个设计，第 3 章详谈。 |
157 tools | 157 个工具模块的实际实现。 | |
approval | 「审批」。用 59 条正则表达式拦截危险命令。第 7 章详谈。 | |
environments | 「执行环境」。工具实际在哪里跑：本机、Docker 容器、云端沙箱、远程主机等 7 种可选。 | |
| 供应商层 | Provider Adapters |
「供应商适配器」。把 Anthropic、OpenAI、Google Gemini、亚马逊 Bedrock、本地 Ollama 等十几种不同服务的接口差异抹平，让上层代码不用关心用的是哪家。 |
| 状态层 | hermes_state |
状态与记忆的存储。用 SQLite（一个轻量级数据库）保存，配合 FTS5（SQLite 的全文搜索功能）做检索，另外还有一套叫 HRR 的向量记忆。第 9 章详谈。 |
2.3 关键数字对照
| 维度 | Claude Code | Hermes |
|---|---|---|
| 编程语言 / 运行环境 | TypeScript / Bun | Python 3.11 / uv |
| 代码总量 | 51.2 万行 · 1,902 个文件 | 191.8 万行 · 4,772 个文件 |
| 最大的单个文件 | screens/REPL.tsx 875 KB | gateway/run.py 1.55 MB |
| 内建工具数量 | 约 40 个 | 约 157 个模块，按工具集分组 |
| 界面形态 | 终端文字界面，用 React Ink 框架写的 146 个界面组件 | 22 个聊天平台适配器 + 网页版 + 终端版 + 桌面应用 |
| 工具并发上限 | 10 个 环境变量 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY |
10 个 常量 _DEFAULT_MAX_CONCURRENT_CHILDREN |
| 子智能体嵌套深度 | 子智能体不允许再创建子智能体（只有 1 层） | MAX_DEPTH = 1，默认也是扁平的一层 |
| 上下文压缩策略 | 写死的五级流水线，不可替换 | 定义成抽象基类，可整体替换 |
| 记忆机制 | 会话内消息记录 + memdir/ 纯文本文件 |
HRR 向量 + SQLite 全文索引 + 8 种可选的外部记忆服务 |
| 危险操作隔离 | 操作系统级沙箱（macOS 的 sandbox-exec）+ 权限规则 | 7 种可切换的执行环境 + 正则表达式红线 |
| 扩展方式 | 技能 / 插件 / MCP / 钩子（10 类事件） | 插件（3 个发现来源）/ 技能 / MCP / 钩子 / 工具集 |
表格里出现的 MCP 是 Model Context Protocol（模型上下文协议）的缩写，一个让智能体接入外部工具服务的开放标准。第 9 章会讲。
2.4 第一个值得记住的洞察
Hermes 的代码量是 Claude Code 的 3.7 倍（191.8 万行 对 51.2 万行）。
但是，两个系统的智能体核心循环体量几乎相同。Claude Code 的主循环文件 query.ts 是 1,730 行；Hermes 的主循环文件 conversation_loop.py 是 8,676 行 —— 考虑到 Python 写同样的逻辑通常比 TypeScript 更啰嗦，两者其实是同一个量级。
那 3.7 倍的差距全在外围：Hermes 的 22 个聊天平台适配器、十几种模型供应商适配、插件系统、长驻网关进程 —— 这些加起来占了它体量的绝大部分。
结论：智能体的「聪明程度」不在代码量里。真正决定一个智能体好不好用的，是那一两千行的循环逻辑和上下文策略；剩下的都是集成工程量。
这句话在面试里很好用 —— 它能说明你真的读过代码，而不是数了数 GitHub 上的收藏数。