04. 项目结构：从目录看懂 Hermes

这篇解决什么问题

Hermes 的目录很多。

如果只是 find . -name "*.py" 一路看，很快就会迷路。这篇先把源码目录按职责分组。

以下基于当前源码目录：/usr/local/lib/hermes-agent。

先看顶层

关键目录大致是：

agent/          Agent 主循环、prompt、模型适配、记忆、压缩、上下文
tools/          具体工具实现和工具注册
hermes_cli/     CLI 子命令、配置、auth、profile、cron 命令等
cli.py          交互式 CLI 主入口之一
run_agent.py    AIAgent 主类和兼容入口
cron/           定时任务存储、调度、输出
gateway/        多平台消息入口和投递
acp_adapter/    ACP/IDE 集成相关适配
apps/           桌面应用相关代码
docs/           项目内部文档

你第一次读源码，优先看：

agent/
tools/
toolsets.py
hermes_cli/
cron/
gateway/

三层模型

可以把 Hermes 分成三层：

入口层：cli.py / hermes_cli/ / gateway/ / cron/
运行层：run_agent.py / agent/
能力层：tools/ / skills / memory / mcp / delegation

入口层负责“消息从哪里来”。

运行层负责“怎么把消息变成一轮 Agent 执行”。

能力层负责“Agent 可以做什么”。

agent/ 目录

agent/ 是主干。

里面有几个关键文件：

conversation_loop.py       一轮对话主循环
tool_executor.py           工具调用执行
prompt_builder.py          构建系统提示词和环境提示
memory_manager.py          记忆上下文
context_compressor.py      上下文压缩
credential_pool.py         多 credential 管理
*_adapter.py               不同 provider / API 适配

源码注释里明确说：conversation_loop.py 是从 run_agent.AIAgent 中拆出来的主循环，run_agent.py 仍保留薄转发和兼容入口。

tools/ 和 toolsets.py

tools/ 里每个工具文件负责一个具体能力。

tools/registry.py 是中央工具注册表。工具文件通过 registry.register() 声明：

工具名
所属 toolset
schema
handler
check_fn
依赖环境变量

toolsets.py 则负责把工具分组，例如：

web
terminal
file
browser
skills
cronjob
memory
delegation

这两个文件连起来看，才能理解“为什么这个会话里有这些工具”。

gateway/ 目录

gateway/ 处理外部消息平台。

你可以把它理解成：

平台消息
→ 会话路由
→ 调用 Agent
→ 格式化和投递回复

具体平台适配在 gateway/platforms/ 下面。

cron/ 目录

cron/ 负责定时任务。

关键文件：

cron/jobs.py       job 存储、读写、状态更新
cron/scheduler.py 触发和执行调度

源码里写得很清楚：job 存在 ~/.hermes/cron/jobs.json，输出在 ~/.hermes/cron/output/{job_id}/{timestamp}.md。

读源码顺序

建议按这个顺序：

1. README.md
2. cli.py / hermes_cli/main.py
3. run_agent.py
4. agent/conversation_loop.py
5. agent/prompt_builder.py
6. agent/tool_executor.py
7. tools/registry.py
8. toolsets.py
9. 随便挑一个具体 tool 看实现
10. cron/ 或 gateway/ 按需要看

不要从 node_modules、apps/desktop、所有平台适配开始。

下一篇看什么

下一篇看 CLI 入口。

入口看懂以后，再看 Agent 主循环，会更自然。