拆解方法与范围
我们在看什么版本
本文档基于工作区提供的 hermes-agent-main 源码快照，不假设它拥有 Git 历史；版本号取自 pyproject.toml 的 0.19.1。快照中的 Python 主工程约 8,237 个文件，其中核心实现包括：agent/ 177 个 Python 文件、tools/ 127 个、gateway/ 86 个、hermes_cli/ 255 个、tests/ 约 2,625 个。数字用于建立规模感，不代表上游未来版本的固定 API。
源码引用使用 path/to/file.py:Lx-Ly。行号是快照行号；如果上游发生重构，应优先用函数名和模块职责定位，再回到行号核对。
参考 Pi-Agent 拆解的写法
refs/dg-ai-notes/pi-agent/docs 的有效之处不在于章节数量，而在于每章都重复回答三层问题：
- 是什么：先把概念边界说清楚，例如 Trace、Turn、Tool、Context。
- 怎么做：沿着真实数据流看入口、状态、分支、异常与持久化。
- 为什么这样做：把代码选择翻译成可迁移的工程原则。
Hermes 的规模远大于 Pi-Agent，因此本拆解选择“主链路优先”：每章只深挖一个能解释大量功能的枢纽，再提供源码地图，避免把数百个外围集成逐个改写成目录。
读者应该如何验证
推荐的验证顺序：
# 进入上游快照
cd hermes-agent-main
# 先看入口和核心符号
rg -n "class AIAgent|def run_conversation|class ToolRegistry" run_agent.py agent tools
# 再看某个边界的调用者
rg -n "ContextCompressor|MemoryManager|execute_tool_calls|SessionStore" .
# 最后用测试确认行为契约
rg -n "compaction|tool|gateway|session|memory|delegat" tests
阅读源码时不要从 cli.py 的一万多行开始硬读。先用本拆解建立“谁拥有状态、谁拥有副作用、谁负责恢复”的地图，再按源码索引跳转。
明确不做的事情
- 不复制上游代码、依赖、用户数据或密钥配置。
- 不把产品 README 中的能力列表直接当成架构结论；关键结论必须能落到源码入口或测试命名。
- 不声称所有 provider 和平台都拥有完全相同的语义；它们共享的是生命周期契约，细节仍由适配器实现。
- 不把当前快照的行为推断为未来版本的稳定承诺。
术语表
| 术语 | 本文中的含义 |
|---|---|
| Agent Loop | 处理一条用户输入、模型响应、工具调用并决定是否继续的循环 |
| Turn | 一次用户输入驱动的模型/工具交互；一个 turn 可包含多个 API call |
| Session | 可恢复的会话身份、消息历史、上下文状态和运行元数据 |
| Toolset | 按能力或运行环境分组的一组工具；不是单个函数 |
| Context Engine | 决定当前 API 请求看见哪些消息，以及何时压缩/裁剪的策略层 |
| Gateway | 把外部平台消息转换为 Hermes session，并把流式结果投递回去的长期进程 |
| Relay | 对模型调用、生命周期和共享指标做统一承载的可选运行时边界 |