参考来源与版本锚定
本页正文由本站独立撰写，目标不是做产品介绍，而是把 Hermes Agent 拆成适合我们自己工程阅读的结构地图。
官方来源：hermes-agent.ai、NousResearch/hermes-agent、官方文档 Architecture / Memory / Gateway 相关页面。
本地锚点：reference/reference_agent/hermes-agent/README.md、run_agent.py、tools/registry.py、tools/memory_tool.py、tools/skills_tool.py、tools/delegate_tool.py、gateway/run.py、gateway/session.py、cron/scheduler.py。
01 · 为什么 Hermes 值得放进庖丁解牛专题
它不是普通的"另一个终端 agent"。从 README 和官方架构页看，Hermes 同时把 CLI、消息平台 gateway、记忆、技能、计划/待办、定时任务、环境后端 放进一个统一运行体里。也就是说，它讨论的已经不是"这一轮怎么回答"，而是"一个 agent 如何长期在线、跨会话工作、跨平台送达、再把经验写回自己体内"。
这和我们在 庖丁解牛专题想抓的主线正好对上：不是看市场文案，而是看控制点到底落在哪些层。Hermes 的价值在于它把控制点拆得很实：run_agent.py 里的 AIAgent 是主循环，tools/registry.py 是执行面入口，gateway/ 是平台入口，cron/ 是调度时间轴，tools/memory_tool.py 与技能工具则把"会不会长记性"和"会不会把经验固化"拉进了同一套系统里。
02 · 先拆成六层：Hermes 到底在拼什么
入口壳
CLI / Gateway 双入口 +关键锚点：hermes_cli/、README 的 CLI / Gateway 双入口
子组件：
hermes_cli/main.py— 终端入口与 REPL 循环gateway/run.py— 消息网关主服务gateway/adapters/— Telegram / Discord / Slack / WhatsApp / Signal 平台适配器
解决的问题：用户是从终端进入，还是从消息平台进入。
控制面
AIAgent 主循环 +关键锚点：run_agent.py 的 AIAgent
子组件：
AIAgent.run_conversation()— 主对话循环prompt_builder— 系统提示词组装runtime_provider— 模型 provider 选择model_tools.handle_function_call()— 工具调用处理- 压缩、重试、持久化、background review
解决的问题：模型调用、提示词拼装、工具回环、压缩、重试、持久化。
工具执行面
工具注册与分派 +关键锚点：model_tools.py、tools/registry.py
子组件：
tools/registry.py— 工具注册中心（schema、handler、toolset 关系）model_tools.py— 本轮可用工具筛选tools/terminal_tool.py— 终端执行抽象tools/delegate_tool.py— 子代理委派
解决的问题：工具如何被注册、筛选、分派到不同 toolset。
长期记忆层
Memory / User Profile +关键锚点：tools/memory_tool.py、agent/memory_manager.py
子组件：
MemoryStore— 文件落盘 + 冻结快照agent/memory_manager.py— provider orchestration 层_turns_since_memory— 记忆写入节流计数- background review 线程 — 判断是否值得写入 memory
解决的问题：会话之外还能记住什么，何时刷回 memory / user profile。
技能层
Skills / Skill Manager +关键锚点：tools/skills_tool.py、tools/skill_manager_tool.py
子组件：
skills_list/skill_view— 渐进披露skill_manage— 创建和改写 skill_iters_since_skill— 技能写入节流计数- learning loop — 经验沉淀为可复用 skill
解决的问题：把经验沉淀为可复用 skill，而不是只留在聊天记录里。
平台与时间轴
Gateway / Cron / Environment +关键锚点：gateway/、cron/scheduler.py、environments/
子组件：
gateway/session.py— session key、identity、reset policycron/scheduler.py— 定时任务调度environments/— Local / Docker / SSH / Daytona / Singularity / Modal 后端SessionStore— SQLite + JSONL 双轨历史
解决的问题：消息从哪里进来、任务何时触发、执行落在哪个环境。
所以 Hermes 不只是"Agent 本体"，它更接近一个长期运行的 agent OS / agent operations layer。
[插图提示词]
用途：画出 Hermes 的六层总图，帮助读者先建立"入口壳 → 控制面 → 工具面 → 记忆/技能 → gateway/cron → 环境后端"的分层心智。
形式：分层结构图；优先 Mermaid。
提示词：画一个 Hermes Agent 六层架构图，顶部是 CLI 与 Messaging Gateway 双入口，中间是 AIAgent 控制面与 Tool Registry，左侧是 Memory / User Profile，右侧是 Skills / Skill Manager，底部是 Gateway adapters、Cron scheduler、Environment backends，箭头标出消息进入、工具调用、记忆写回、定时触发、平台回送。
Mermaid 更适合：是。
02B · Agent 循环步进
从消息进入、会话构建、AIAgent 主循环、工具调用、记忆审查到响应送出——一条完整的 Hermes Agent 运行链路。
下方为讲解型步进演示（数据来自 site/data/hermes-loop-steps.json）：可点步骤标签、播放/暂停、倍速与键盘 ← →、Space（点播放后也会自动聚焦面板）。步骤条下方彩色细条为下一帧倒计时；末步点播放会先回到第 1 步再自动翻页。非真实运行时遥测。
02B · 架构关系图谱
Treemap 适合看各层规模与归属，知识图谱更适合看谁驱动谁、谁依赖谁。这里把六层架构的关键组件串成一张关系网：块内结构看每个架构层下挂了哪些核心模块；块间交互看 gateway 如何创建 AIAgent、AIAgent 如何调用工具与记忆、Cron 如何定时触发、执行最终落在哪个后端。
图谱里块内结构来自六层架构拆分；块间交互是教学向归纳，不是严格的静态 import 图。它的作用是帮你判断“先看哪里、再看哪里、哪些模块要连在一起读”。
02C · 核心组件速览
下面是 Hermes Agent 的六个核心组件卡片。点击卡片可展开查看每个组件的职责边界、关键源码锚点，以及对我们当前栈的参考价值。
卡片数据来自 site/data/hermes-feature-cards.json；样式复用 .cc-feature-cards 组件合约。
03 · 控制面到底在哪：不是 gateway，而是 AIAgent
最容易误判的一点，是把 Hermes 的"平台能力"当成主脑。实际上从 run_agent.py 看，真正像控制面的还是 AIAgent。它负责 provider 选择、系统提示词组装、工具循环、压缩、会话保存、background review，以及对 memory / skill nudges 的时机控制。官方 Architecture 页也把它定义成同步 orchestration engine。
这意味着 gateway/ 更像 ingress layer：把 Telegram、Discord、Slack、WhatsApp、Signal 等消息转成统一事件，再为每条消息创建带 session history 的 AIAgent。控制面不在平台壳，而在这个 agent loop 本身。对我们来说，这一点和 Claude Code / Like Code 的讨论很接近：不要把壳误认成脑，真正的脑在那条循环与状态机里。
进一步看，tools/registry.py 把工具声明、schema、handler、toolset 关系集中到一个注册中心；model_tools.py 再决定哪些工具真正进入本轮可用面。这说明 Hermes 的控制面不是"所有功能散落在命令里"，而是通过一层显式注册表去管理执行面。
03B · 工具系统目录
从 tools/registry.py 看，Hermes 把工具声明、schema、handler、toolset 关系集中到一个注册中心；model_tools.py 再决定哪些工具真正进入本轮可用面。下面是按职能分组的工具地图。
工具注册名与 schema 随官方版本变化；上方为读源码时常用的代表项。数据来自 site/data/hermes-tools.json；样式复用 .cc-tool-tiles 组件合约。
04 · Hermes 的关键差异：它把记忆和技能放进了主循环
README 最强调的卖点是 built-in learning loop。这不是一句 marketing phrase，因为本地代码里确实能找到对应锚点：AIAgent 在初始化阶段会装 memory store、memory provider、skills config，并维护 _turns_since_memory、_iters_since_skill 这样的节流计数；后面还有 background review 线程专门审查当前对话是否值得写入 memory 或 skill。
这和很多"带记忆"的 agent 不太一样。很多系统把记忆当外挂检索层，技能当外部提示词包；Hermes 则更进一步，把"什么时候提醒自己保存记忆"和"什么时候把经验固化成 skill"拉进了主循环内部。对我们自己栈的启发很直接：如果真想做长期运行 agent，记忆和技能不能只是静态文件夹，而要变成 loop 内的一等公民。
| 层 | 关键锚点 | 边界到底在哪 |
|---|---|---|
| Memory Store | tools/memory_tool.py 的 MemoryStore | 把 MEMORY.md / USER.md 做成文件落盘 + 冻结快照；当前会话写入磁盘，但 system prompt 要到下一会话才刷新。 |
| Memory Manager | agent/memory_manager.py | 协调内建 memory 与外部 memory provider；说明 Hermes 不是只有一份本地记忆文件，而是预留了 provider orchestration 层。 |
| Skills Surface | tools/skills_tool.py、tools/skill_manager_tool.py | skills_list / skill_view 负责渐进披露，skill_manage 负责真正创建和改写 skill。 |
| Nudges | run_agent.py 中的 _turns_since_memory、_iters_since_skill、background review | 不是每轮都写，而是由 loop 内节流和审查线程决定什么时候值得沉淀。 |
[插图提示词]
用途：说明 Hermes 的 closed learning loop，不只是对话，还有 memory / skill review 与写回。
形式：闭环流程图；优先 Mermaid。
提示词：画一个 Hermes Agent learning loop 闭环：user message 进入 AIAgent，模型调用工具完成任务，conversation 结束后触发 background review，判断是否写入 memory、user profile 或 skill，随后这些内容回到下一轮 system prompt，形成持续学习闭环。
Mermaid 更适合：是。
05 · Gateway、Cron、Environment：它怎么从"会聊天"走到"长期在线"
Hermes 另一条值得拆的线，是它把"入口平台"和"时间触发"做成了正式层。官方架构页的数据流很明确：Gateway message 会先经过 adapter 和 session 解析，再生成新的 AIAgent；Cron job 则由 scheduler tick 拉起 fresh agent、注入技能上下文、跑 prompt、再把结果送回目标平台。
这让 Hermes 不只是一个 REPL，而是一个可以挂在时间轴上、也可以挂在消息总线上运行的系统。与此同时，README 还列出本地、Docker、SSH、Daytona、Singularity、Modal 等环境后端，说明它把"跑在哪"也当成正式抽象层，而不是默认永远跑在开发者当前 shell 里。
对我们来说，这一层最值得学的不是"支持的平台越多越好"，而是：当一个 agent 不再只存在于当前终端，它的 session key、delivery path、environment backend、job scheduler 就必须进入系统设计主线。
如果再往下拆，gateway/session.py 其实定义了一个很关键的边界：平台消息如何被折叠成"同一条会话"，以及哪些上下文进入 system prompt、哪些只做本轮临时注入。这决定了 Hermes 的 gateway 不是第二个大脑，而是把平台噪声收束成稳定会话语义的一层。
| 边界层 | 关键锚点 | 真正负责什么 |
|---|---|---|
| Session Identity | gateway/session.py 的 build_session_key() | 把 DM、group、thread、per-user isolation 编码成稳定 key；也就是说，Hermes 先决定"谁和谁共享同一条脑内上下文"，再谈 agent 运行。 |
| Session Lifetime | SessionStore.get_or_create_session()、_should_reset() | 按 idle / daily reset policy 切 session，并把旧 session 结束、新 session 建档；长期在线不是无限同一上下文，而是受策略约束的连续会话。 |
| Prompt Boundary | build_session_context_prompt()、run_agent.py 的 ephemeral user context 注释 | 平台来源、home channel、delivery options 进入系统提示；而插件临时上下文只挂在当前 user message，不持久写回 session DB。 |
| Kernel Reuse | gateway/run.py 的 _agent_cache / session_key | gateway 以 session_key 复用缓存的 AIAgent，保持 frozen prompt 和 tool schema 的缓存收益；说明平台层服务的是 kernel 复用，而不是自带另一套推理脑。 |
| Transcript Persistence | SessionStore.append_to_transcript()、load_transcript() | SQLite + JSONL 双轨保存会话历史；gateway 管的是历史与回送，不是把业务逻辑散落在 adapter 里。 |
[插图提示词]
用途：把 Hermes 的 gateway / session seam 画清楚，说明"平台消息 → session key → session context / reset policy → cached AIAgent → transcript / delivery"的边界。
形式：结构流图；优先 Mermaid。
提示词：画一个 Hermes gateway session boundary 图。左侧是 Telegram / Discord / Slack adapter 输入消息，中间是 build_session_key 与 SessionStore，标出 reset policy、session context prompt、history load/save，右侧是 cached AIAgent kernel，底部是 transcript persistence 与 delivery router。强调 gateway 负责 ingress、session identity、history、delivery，而不是替代 AIAgent 控制面。
Mermaid 更适合：是。
再往下一层，tools/terminal_tool.py 和 environments/README.md 说明 Hermes 其实把"执行边界"也做成了正式抽象，而不是把 shell 默认绑死在当前机器。这里最值得注意的不是支持 Local / Docker / SSH / Daytona / Singularity / Modal 六种 backend，而是 同一个 agent loop 可以把 terminal 工具路由到不同执行面，同时用同一套 task / session 语义维持状态。
| 执行边界 | 关键锚点 | 真正说明了什么 |
|---|---|---|
| Backend Selection | tools/terminal_tool.py 的 TERMINAL_ENV / create_environment() | 模型看到的是统一 terminal tool，但真实执行可以落到 local、docker、ssh、daytona、singularity、modal；这说明 backend 是控制面参数，不是工具接口分叉。 |
| Persistence Contract | terminal_tool.py 顶部说明、run_agent.py 的 _cleanup_task_resources() | Hermes 明确区分 persistent filesystem 和 live sandbox：文件状态可以跨重建保留，但长进程不保证永存；persistent backend 会跳过每轮 cleanup_vm()，交给 idle reaper 按 lifetime_seconds 回收。 |
| Task-Scoped State | environments/README.md 的 ToolContext 说明 | 同一个 task_id 会复用同一终端 / 浏览器状态，reward verifier 看到的正是模型刚才操作过的那份环境；这让 Hermes 的执行面不仅能跑工具，还能被训练和评测系统复用。 |
| Research Reuse | environments/hermes_base_env.py 与 environments/README.md | Atropos 环境层直接通过 TERMINAL_ENV 接入 Hermes tool stack，说明 Hermes 的 backend 抽象不是 UI 附件，而是可被 RL / benchmark pipeline 复用的运行层。 |
[插图提示词]
用途：解释 Hermes 的执行边界，说明 agent kernel、terminal tool、backend selector、persistent filesystem、idle reaper 之间的关系。
形式：执行路径图；优先 Mermaid。
提示词：画一个 Hermes execution boundary 图。顶部是 AIAgent 与 terminal tool，中间是 TERMINAL_ENV backend selector，下面分成 local、docker、ssh、daytona、singularity、modal 六个执行后端。旁边标出 task_id 复用、persistent filesystem、idle reaper、lifetime_seconds、ToolContext verifier，强调"统一工具接口，多种执行面，状态按 task/session 管理"。
Mermaid 更适合：是。
05B · Gateway 适配器与执行后端目录
Hermes 把"支持哪些平台入口"和"能落到哪些执行面"做成了正式的系统设计。这里把 gateway 适配器和 environment backend 压成一张可视目录，方便快速判断平台覆盖面和部署选项。
目录为教学向归纳：左列是消息平台适配器（6 个），右列是执行后端（6 个），底部是核心入口链路。数据来源 site/data/hermes-component-catalog.json，样式复用 .cc-pill-wall 组件合约。
05C · API 面 / 协议 / 后端 对照表
Hermes 的 API 面、协议支持与执行后端不是"全连接"的，而是按组件职责分层收敛。下表把核心组件与它们实际触及的协议/平台、执行后端压成一张映射，方便判断"某个功能到底依赖哪些基础设施"。
| 组件 / API 面 | 协议 / 平台覆盖 | 执行后端 | 核心职责 |
|---|---|---|---|
AIAgent 内核run_agent.py | —（与入口解耦） | All 6 Local / Docker / SSH / Daytona / Singularity / Modal | 主循环、推理、工具调度、会话状态 |
gateway/run.pygateway/session.py | Telegram / Discord / Slack / WhatsApp / Signal / QQ | —（纯 ingress 层） | 消息入口、session key、历史回送、delivery router |
cron/scheduler.py | —（时间触发） | All 6 | 定时 tick、jobs.json 解析、触发 fresh AIAgent |
tools/terminal_tool.py | — | All 6 TERMINAL_ENV 路由 | 统一终端接口、backend selector、task-scoped state |
tools/memory_tool.py | — | SQLite + JSONL | 跨会话持久化、FTS5 检索、user profile |
tools/skills_tool.py | — | —（纯控制面） | 技能创建、自改进、agentskills.io 兼容 |
tools/delegate_tool.py | — | All 6 | 子代理委托、并行工作流、RPC collapsing |
tools/registry.py | — | All 6 | 工具发现、调用分发、toolset 管理 |
表格为教学向归纳："All 6" 指 Local / Docker / SSH / Daytona / Singularity / Modal；gateway 层不直接绑定后端，只负责 ingress 与 delivery；AIAgent 内核与工具层才是真正使用后端执行面的地方。
06 · 三条运行链路复盘：CLI、Gateway、Cron 到底怎么汇进同一套脑子
官方 Architecture 页最有价值的部分，不是目录树，而是三条数据流。它明确告诉我们：Hermes 虽然入口很多，但最后都会汇进同一套 AIAgent 控制面。这一点非常值得拿来和我们自己的 Claude Code / codex-loop 讨论对照。
| 入口链路 | 关键代码路径 | 真正说明了什么 |
|---|---|---|
| CLI Session | hermes_cli/main.py → AIAgent.run_conversation() → prompt_builder → runtime_provider → model_tools.handle_function_call() | 终端只是入口，真正的循环仍然在同一个 agent 内核里。 |
| Gateway Message | gateway/run.py → adapter on_message() → session key → fresh AIAgent + history → adapter delivery | 多平台不是多个脑，而是多个 ingress + 一个共享控制面。 |
| Cron Job | cron/scheduler.py tick → jobs.json → fresh AIAgent → skills context → target delivery | 定时任务不是旁路脚本，而是同一套 agent 内核的"时间触发模式"。 |
这三条链路共同说明：Hermes 真正珍贵的，不是"支持很多入口"，而是把不同入口统一收敛到同一套 agent kernel，再把 session、delivery、skills、memory 和 tool loop 一起接进去。这也是它和单纯聊天机器人或普通终端助手拉开差距的地方。
07 · 对 Claude Code / Like Code / codex-loop 值得学什么
第一，要把控制面和入口壳分开。Hermes 的真正主脑在 AIAgent，不是在 CLI 或 gateway adapter；我们自己的栈也该继续坚持"线程 / UI 只是入口，主脑仍在 loop"。
第二，要把记忆和技能放进正式运行结构，而不是只靠散落资料夹。Hermes 用 review + writeback 做内建沉淀；我们即使继续采用 repo 外置记忆，也该保证 plans、skills、handoff 和长期知识之间有稳定回写路径。
第三，要把时间轴、delivery 和 session seam 当成控制面的一部分。codex-loop 现在已经有推进链路，但 Hermes 提醒我们：真正的长期在线 agent 还要显式回答"谁在接消息、哪条 session 复用上下文、结果回送到哪里"。
第四，要把执行后端视为正式运行层，而不是工具附属物。Hermes 把 backend selector、task-scoped state、idle reaper 全部写进系统设计；这意味着我们后续如果做 Like Code / agent stack，也要尽量把 environment contract 说清，而不是隐含在 shell 默认值里。
一句话收尾：Superset 教我们外层工作台如何编排多个 worker；Hermes 则进一步提醒我们，长期在线 agent 还必须把 session、memory、skills、delivery 和 execution contract 一起纳入控制面。
08 · 放回我们自己的栈：Hermes 和 Claude Code / Like Code / codex-loop 到底哪里相像，哪里不同
如果把 Hermes 完全当成"另一个竞品 agent"来读，其实价值会被低估。对我们更有用的读法，是把它当作一份长期运行控制层样本，然后拿它反照自己当前的栈：Claude Code / Like Code 负责高质量交互式主脑，codex-loop 负责定时推进和任务持续性，站点与专题页负责把这些经验沉淀成可教学的结构化内容。
| 层次 | Hermes | 我们当前的栈 | 真正差别 |
|---|---|---|---|
| 主脑 / Control Plane | AIAgent 把 provider、prompt、tool loop、memory/skills nudges 拉进一个内核 | Claude Code / Like Code 的会话主脑 + repo 内显式计划与执行节奏 | Hermes 更强调"长期在线一体化内核"；我们更强调"强主脑 + 外置流程纪律"。 |
| 入口层 | CLI + gateway adapters | CLI / Codex thread / 站点内容入口 | Hermes 统一消息平台入口；我们当前更偏工程工作台和内容工作台。 |
| 持续推进 | Cron scheduler 直接触发 fresh AIAgent | codex-loop 通过 plan + evolution note 驱动下一轮 | Hermes 是产品内建调度；我们是显式 plan-driven orchestration，审计性更强。 |
| 记忆 / 技能 | 内建 memory、skills、review loop | 更多依赖 repo 文档、skills、plans、handoff prompt | Hermes 把沉淀放进内核；我们把沉淀放进 repo 与技能系统，便于版本化和复查。 |
| 执行面 | 统一 terminal tool + 多 backend | Claude Code / Codex 工具链 + repo 自动化脚本 | Hermes 把 backend abstraction 做成正式运行层；我们目前更偏"本地工程环境 + 针对性自动化"。 |
如果把"哪里已经有对应物、哪里还只是隐含约定"再压得更具体一点，可以得到一张更实用的映射表：
| Hermes 概念 | Hermes 的正式落点 | 我们当前最近的承接层 | 还缺什么 |
|---|---|---|---|
| session seam | gateway/session.py、SessionStore、session_key | codex-loop thread + plan / handoff + 人工切换的工作区语义 | 还缺一个正式写下来的 session identity / reset policy，而不是靠操作习惯默认成立。 |
| delivery path | gateway adapters + home channel / callback route | 站点、仓库、终端、知乎这几条分散出口 | 还缺统一 delivery contract，说明一次结果应该回送到哪个面、以什么形态落地。 |
| memory / skills writeback | built-in review + memory / skill manager | repo 内 skills / plans / docs / handoff 的外置沉淀链 | 我们已经有可版本化优势，但还缺更明确的"何时升级成 skill、何时只写进 plan"规则。 |
| execution contract | TERMINAL_ENV + backend lifecycle + verifier | 本地工程环境 + 定向自动化脚本 | 还缺更显式的 environment contract，让"哪些状态可复用、哪些只是本轮临时上下文"不再只靠经验判断。 |
所以最值得学的不是"把 Hermes 整套产品形态搬过来"，而是它提醒我们：长期运行 agent 需要一条清楚的控制面主线。我们完全可以继续保留 Claude Code / Like Code 作为高质量交互主脑，把 codex-loop 当调度层，把 repo 内 skills / plans / docs 当外置长期记忆层；但与此同时，session seam、delivery path、environment contract 这些边界就该被写得更显式。
换句话说，Hermes 更像"把一切都内置进产品"；我们当前路线更像"把主脑、调度、知识沉淀拆开，但用明确接口把它们重新编排起来"。这两条路并不矛盾。真正的结论是：我们的下一代 stack 不必复制 Hermes 的产品壳，但应该吸收它在控制面、会话边界和执行边界上的工程纪律。
[插图提示词]
用途：把 Hermes 与我们当前 stack 的对照压成一张"同层对照，不同落点"的教学图，方便后续做知乎或站内导读改编。
形式：左右对照结构图。
提示词：画一张左右对照的信息图。左侧是 Hermes Agent：AIAgent control plane、gateway/session seam、built-in memory/skills writeback、cron scheduler、TERMINAL_ENV execution backends。右侧是我们的当前 stack：Claude Code / Like Code 交互主脑、codex-loop plan/evolution 调度、repo 内 skills/plans/docs 外置长期记忆、site/repo/terminal/知乎 多出口 delivery path、本地工程环境与定向自动化脚本。中间用四条对照箭头强调 session seam、delivery path、memory/skills writeback、execution contract 分别在哪一侧是正式内建、在哪一侧还是外置 contract。
Mermaid 更适合：否。
参考与原始链接
- Hermes Agent 官网
- NousResearch/hermes-agent
- 官方文档 · Architecture
- 官方文档 · Memory
reference/reference_agent/hermes-agent/run_agent.pyreference/reference_agent/hermes-agent/tools/registry.pyreference/reference_agent/hermes-agent/gateway/run.pyreference/reference_agent/hermes-agent/cron/scheduler.py