为什么读这本书¶

官方文档已经很好了,为什么还需要这个¶

hermes-agent.nousresearch.com/docs 是一份高质量的英文文档。它详尽、权威、结构清晰。如果你英语流利、时间充足、只是想查命令参考 —— 去看官方文档,不要看这本书。

这本书存在,是因为官方文档解决不了三个问题:

问题一:中文读者的第一公里¶

英文文档的知识点都在,但读者脑子里的知识网络是自己拼的。对中文母语者来说,拼接的成本远高于阅读的成本 —— 读懂每一句不难,但看完三篇后脑子里是碎的,而不是一张图。

这本书的目标是:让你在读完前言 + 第一部之后,脑子里有一张清晰的 Hermes 世界观图景。然后再读官方文档时,你在查「这个功能叫什么」,而不是在拼「它是怎么构成一个整体的」。

问题二:「精通」这条路没人带¶

官方文档是参考型(reference-oriented)的 —— 功能 A 是什么、参数 B 是什么。但它不告诉你: - 什么时候该用哪个(比如 skills vs memory vs context files) - 为什么这样设计(比如为什么 slash 命令要走 user message 而不是 system prompt) - 边界在哪(比如 prompt caching 为什么不能中途改 toolsets) - 踩过的坑(比如 simple_term_menu 在 tmux 下的 ghosting)

这些是教程型(tutorial-oriented)+ 解说型(explanation-oriented)的内容,官方文档不会写,因为它会让文档变长变主观。但这正是「从会用到精通」的那条桥。

问题三:大而全的项目没有合适的读法¶

Hermes 是一个横跨 CLI、TUI、本地 Web Dashboard、16+ 消息平台、6 种终端后端、40+ 工具、MCP 集成、Nous Tool Gateway、RL 训练的巨大项目。把它所有入口平铺在你面前,你会溺水。

这本书的组织原则是按掌握深度分层(五大支柱 → 入门 → 日常 → 精通 → 内核 → 研究),每一层都能独立停下来用。你用到哪里学到哪里,不用担心「是不是错过了什么」—— 更深的层只有在你需要时才打开。

这本书的写作原则¶

为了让这本书不变成「官方文档的翻译缩水版」,我给自己定了几条硬规则:

必做

每章先画心智模型图。如果我不能用一张图说明白一个子系统,说明我自己还没懂。
每章有最小可跑通示例。读者复制粘贴就能见效,不搞「理论上应该可以」。
坑点独立成段,用 !!! warning 高亮。踩过的坑比好用的功能更值钱。
版本锚定。每篇 frontmatter 标注 hermes_version,升级后作者会回来核对。

不做

不罗列所有参数。参数表去查官方 reference,这里只讲「你通常该用哪些」。
不翻译官方文档。翻译价值不大;这本书是重组 + 补白 + 讲故事。
不回避主观判断。该推荐就推荐,该吐槽就吐槽 —— 但标注清楚是观点还是事实。
不追求完备。覆盖 80% 的使用场景,剩下 20% 通过链接指向官方文档。

如果你读完这本书¶

你应该能做到:

在 $5 VPS 上部署一个 Hermes,通过 Telegram 指挥它
设置一个每天早 7 点自动发送工作简报的 cron 任务
给 Hermes 写一个自定义技能,让它记住你们团队的术语
接入一个 MCP 服务器扩展 Hermes 的能力
读懂 run_agent.py 的 agent loop,能加一个自己的工具
理解 prompt caching 的边界,不会写出破坏缓存的改动
知道 Profile 如何隔离多实例,什么时候需要用

如果其中哪一条你已经能做到了,跳过对应章节即可。

下一步:怎么读这本书 →