Hermes 101｜00｜Reading Guide
Hermes 101 的读者路线图：这不是代码阅读笔记，而是一套 Agent Runtime 学习路径。
Hermes 101 适合把 Agent 当工程系统来理解的读者。它不是“怎样安装 Hermes”的教程，也不是按文件顺序展开的代码笔记，而是用 Hermes 作为一个足够完整的样本，拆解一个长期可用的 Agent Runtime 应该包含哪些机制。
如果你已经能写一个最小 function-calling demo，这个系列要回答的是下一层问题：demo 之外，真实 Agent 为什么还需要 session、context builder、compaction、skills、gateway、cron、delegation、provider runtime 和 observability。
这个系列适合谁
适合：
- 想从 toy agent 走向可长期运行 Agent 的工程师
- 想理解 Claude Code、Codex、OpenCode、Hermes 这类 Agent 工具内部结构的读者
- 想自己实现一个 mini-agent-harness 的学习者
- 关心工具权限、上下文、记忆、调度和多入口运行时的人
不适合：
- 只想找安装命令或配置参数的人
- 只想看某个模型评测的人
- 期待按代码文件顺序讲解的人
推荐阅读路线
| 阶段 | 篇章 | 你在学习什么 |
|---|---|---|
| Runtime 主路径 | 01–04 | Agent 怎样从入口进入核心循环，怎样调用工具，怎样保存会话 |
| 上下文工程 | 05–07 | 模型每轮能看到什么，历史太长怎么办，经验如何变成 Skill |
| 扩展与诊断 | 08–09 | 能力怎样外接，运行过程怎样被观测和复盘 |
| 长期运行 | 10–12 | 跨 session 记忆、跨平台入口、定时唤醒 |
| 多 Agent 与多模型 | 13–14 | 子 Agent 分工，以及 provider/model/runtime 如何统一 |
贯穿案例
为了避免概念漂浮，建议带着同一个任务读完整个系列：
用户说：“帮我修复这个 repo 里的 failing tests。”
这句话在不同章节里会被拆成不同问题：
- Agent Runtime：这个请求从哪个入口进来，最终由谁执行？
- Agent Loop：模型、工具、结果、下一轮模型调用如何循环？
- Tool Runtime：读文件、跑测试、改代码、提交结果分别如何受控执行？
- Session Tree：这次排查过程怎样保存，明天怎样恢复？
- Context Builder：模型这一轮应该看到哪些项目规则、历史和工具？
- Compaction：跑了很多轮之后，哪些信息必须留下？
- Skills：这次修测试的经验怎样沉淀成下次可复用流程？
- Observability：如果失败了，怎样知道卡在模型、工具、上下文还是权限？
- Gateway / Cron / Delegation：同一任务如何跨入口、按时间、或拆给子 Agent 执行？
- Provider Runtime：模型切换、fallback、API 协议差异怎样不污染主循环？
核心术语速查
| 术语 | 在本系列里的意思 |
|---|---|
| Agent Runtime | 包住模型调用的完整运行时：loop、tools、context、session、memory、policy、provider 等 |
| Agent Loop | 模型调用、工具执行、工具结果回填、继续或终止的状态机 |
| Tool Runtime | 把模型提出的 tool_call 变成受控副作用的执行层 |
| Context Builder | 决定模型本轮能看到什么、以什么顺序看到的组装层 |
| Compaction | 把长历史压成可继续执行的状态，而不只是写摘要 |
| Skill | 可复用流程、坑点和验证方法的程序化经验包 |
| Gateway | 把同一 Agent Runtime 接到 Telegram、Discord、Slack、Webhook 等入口的适配层 |
| Delegation | 父 Agent 把独立子任务交给隔离上下文里的子 Agent，并只取回最终摘要 |
| Provider Runtime | 把 provider、model、base_url、api_mode、凭证和 fallback 解析成一次可执行模型调用 |
怎样读这套文章
每篇文章都可以按三个问题阅读：
- 这个机制解决什么真实工程问题？
- Hermes 给出的设计边界是什么？
- 如果我要写一个 mini-agent-harness，最小可迁移实现是什么？
读完之后，你不一定要照搬 Hermes 的代码结构，但应该能画出一套自己的 Agent Runtime 骨架，并知道每个机制为什么存在。