第四部 · 内核

目标:读懂 Hermes 的源码结构、核心循环、扩展机制,能给项目加工具、加命令、加平台,或 fork 一份深度改造。

写代码前必读

在你动任何代码之前,先通读这两章:

• 27. Prompt Caching 的边界 —— 破坏缓存 = 成本暴涨
• 31. 已知坑点与防御 —— 项目维护者已经踩过的坑,别再踩

这两章是用代价换来的经验,能让你少几个月弯路。

这部分包含什么

• 22. 项目结构总览

  ---

  目录树 + 文件依赖链 + 核心入口点,搭建源码地图。

• 23. AIAgent 类详解

  ---

  run_agent.py 源码走读,agent loop 完整生命周期。

• 24. 工具注册机制

  ---

  加一个自己的工具的 3 文件改动模式。

• 25. Slash 命令系统

  ---

  COMMAND_REGISTRY 单源头设计,怎么加一条跨 CLI + gateway 的命令。

• 26. 消息网关架构

  ---

  BasePlatform 抽象,加一个新平台适配器。

• 27. Prompt Caching 的边界

  ---

  什么能动、什么不能动 —— 写代码前必读。

• 28. Profile 工作原理

  ---

  _apply_profile_override 源码,HERMES_HOME 如何传染一切。

• :material-compress: 29. Context Compression 算法

  ---

  context_compressor.py 详解,摘要模板设计、tail 保护、递归压缩。

• 30. 测试策略

  ---

  3000+ 测试怎么组织,_isolate_hermes_home fixture,怎么写新测试。

• 31. 已知坑点与防御

  ---

  项目维护者踩过的坑全集,写代码前必扫。

读完这部分,你应该能做到

• 打开 hermes-agent/ 仓库能认识 20+ 关键文件各自做什么
• 追踪一次 hermes 启动 → 对话 → 工具调用 的完整代码路径
• 给 Hermes 加一个自己的工具(3 文件改动)
• 给 Hermes 加一个 slash 命令(CLI + gateway 都工作)
• 给 Hermes 加一个新的消息平台适配器
• 理解 prompt caching 的边界,不写破坏性代码
• 写 profile-safe 的新代码(正确用 get_hermes_home())
• 为你的改动写 pytest 测试,跑过 3000 测试套件不 fail

准备好了,从 22. 项目结构总览 → 开始。