文档 02
架构 · 模块 · 文件结构
五层运行时架构全景、核心模块职责拆解、工具系统与 Plugin 机制，以及完整的文件树与命名规范。
A — 架构 · 模块 · 组件
五层运行时架构
用户入口层
↓
核心 Agent 层
↓
模型路由层
↓
工具执行层
↓
持久化层
核心模块详解
入口层
HermesCLI
cli.py — 12,043 行
交互式 CLI 主体。prompt_toolkit 输入区、Rich 渲染、KawaiiSpinner 动画、Skin Engine 主题系统、历史、自动补全、Slash 命令处理。
入口层
Gateway
gateway/run.py — 14,152 行
多平台消息网关，完全 asyncio 架构。22 个平台适配器，每个会话独立 AIAgent 实例，通过 asyncio.to_thread 桥接同步 Agent。
入口层
ACP Server
acp_adapter/ · acp_server.py
Agent Control Protocol HTTP 服务端，提供程序化接口。支持任务提交、状态查询、结果流式推送。
Agent 层
AIAgent
run_agent.py — 14,123 行
核心对话循环：while iterations < max → LLM → tool_calls? → 并发执行 → append results → continue。同步主循环 + ThreadPoolExecutor 并发工具调用。
Agent 层
PromptBuilder
agent/prompt_builder.py
动态构建 system prompt，注入 Skill 内容、记忆摘要、工具描述、上下文约束。基于 Jinja2 模板渲染。
Agent 层
ContextCompressor
agent/context_compressor.py
Token 阈值触发自动压缩。使用 LLM 对历史消息做摘要，保留最近 N 轮完整消息 + 历史摘要。CPU 密集型，是 Rust 化 ROI 最高的模块。
Agent 层
MemoryManager
agent/memory_manager.py
跨会话记忆读写，支持多种后端（文件 / Mem0 / Honcho / Supermemory）。会话结束时自动提取关键信息写入记忆。
Agent 层
CredentialPool
agent/credential_pool.py
多 API Key 轮转池。自动在多个 Key 之间均衡负载，支持按速率限制状态动态切换，避免单 Key 耗尽。
Agent 层
SkillCommands
agent/skill_commands.py
Skill SKILL.md 文件发现、加载、解析，通过 /skill 命令动态注入 PromptBuilder。支持内置 skills 和用户自定义 skills。
路由层
Transports
agent/transports/
每个 provider 一个 transport 模块。统一接口：send_message(messages, tools) → stream。处理 SSE 流式输出、function calling 格式差异、错误分类与重试。
路由层
RateLimitTracker
agent/rate_limit_tracker.py
追踪各 provider 的速率限制状态（429 响应、Retry-After header），在 CredentialPool 中协同工作自动切换 Key 或 provider。
路由层
ErrorClassifier
agent/error_classifier.py
将 LLM API 错误分类为：可重试（网络超时/速率限制）、不可重试（认证错误/参数错误）、需用户介入。配合 tenacity 做指数退避重试。
工具层
Tool Registry
tools/registry.py
工具自动注册中心。各 tools/*.py 在模块级调用 registry.register()，Python 导入时自动触发，无需手动维护工具列表。
工具层
ModelTools
model_tools.py
汇聚工具注册 + handle_function_call()。接收 LLM 返回的 tool_call，路由到对应工具函数，处理并发互斥锁（交互工具串行，文件工具并行）。
工具层
Environments
tools/environments/
工具执行环境适配：local（直接调用）/ docker（容器沙箱）/ ssh（远程服务器）/ modal（Serverless）/ daytona（开发容器服务）。
模块依赖链
tools/registry.py← 无外部依赖，最底层节点
↑
tools/*.py← 各自调用 registry.register()，模块导入时自动注册
↑
model_tools.py← 汇聚所有工具 + handle_function_call()
↑
agent/transports/*.py← LLM provider 适配，返回 tool_calls
↑
run_agent.py← AIAgent 核心循环，同步；依赖 agent/* 全部模块
↑ ↑
cli.py← 交互 CLI，同步gateway/run.py← 多平台网关，asyncio
工具系统（69 个工具）
工具通过 registry.register() 自动注册，分为以下功能类别：
系统与终端 ~8个
terminal_tool
background_process
pty_tool
process_manager
cronjob_tools
env_tool
文件操作 ~10个
file_tools
file_read
file_write
file_search
file_patch
directory_tool
archive_tool
网络与 HTTP ~6个
web_fetch
web_search
http_request
browser_tool
screenshot_tool
Agent 协作 ~5个
delegate_tool
send_message_tool
mcp_tool
ask_human
notify_tool
记忆与知识 ~4个
memory_tool
knowledge_tool
note_tool
calendar_tool
代码与开发 ~8个
code_analysis
git_tool
test_runner
lint_tool
docker_tool
k8s_tool
数据与 AI ~6个
image_gen_tool
image_vision
audio_tool
pdf_tool
data_analysis
平台集成 ~12个
github_tool
jira_tool
notion_tool
slack_tool
email_tool
calendar_api
stripe_tool
Plugin 系统
通过 Python 包发现机制（entry_points）加载，运行时动态注入。每个 plugin 可替换对应的核心模块实现。
plugins/memory/
记忆后端替换
Honcho · Mem0 · Supermemory · Zep · 自定义
plugins/context_engine/
上下文引擎替换
自定义压缩策略 · GraphRAG 检索
plugins/image_gen/
图像生成后端
DALL-E · Stable Diffusion · Midjourney
plugins/kanban/
任务看板集成
Linear · Jira · Trello · GitHub Projects
plugins/observability/
可观测性后端
OpenTelemetry · Langfuse · Arize
plugins/platforms/
额外平台适配器
自定义消息平台 · 企业 IM 系统
B — 文件结构 · 命名规范
完整文件树
■ 核心 Agent
■ 工具文件
■ Agent 内部模块
■ Gateway
■ 测试
■ 配置
hermes-agent/
├── run_agent.py ← AIAgent 核心循环 (14,123行)
├── cli.py ← HermesCLI 交互入口 (12,043行)
├── model_tools.py ← 工具注册汇聚 + handle_function_call()
├── hermes_state.py ← SQLite+FTS5 会话持久化
├── hermes_constants.py ← profile-aware 路径系统
├── pyproject.toml ← 依赖声明 (openai/anthropic/httpx/rich...)
│
├── agent/ ← ~50个内部模块
│ ├── prompt_builder.py ← System prompt 构建 + Jinja2 模板
│ ├── context_compressor.py ← Token阈值触发自动压缩
│ ├── memory_manager.py ← 跨会话记忆读写
│ ├── credential_pool.py ← 多API Key轮转池
│ ├── skill_commands.py ← SKILL.md 加载 + /skill 命令
│ ├── model_metadata.py ← 各模型 context_length/价格元数据
│ ├── rate_limit_tracker.py ← provider 速率限制追踪
│ ├── error_classifier.py ← 错误分类 + 重试策略
│ ├── title_generator.py ← 自动生成会话标题
│ ├── display.py ← KawaiiSpinner + 活动流渲染
│ ├── skin_engine.py ← 数据驱动主题系统
│ └── transports/ ← LLM provider 协议适配
│ ├── chat_completions.py ← OpenAI-compatible (53 providers)
│ ├── anthropic.py ← Anthropic native API
│ ├── codex.py ← OpenAI Codex
│ ├── bedrock.py ← AWS Bedrock
│ ├── gemini_native.py ← Google Gemini native
│ └── copilot_acp.py ← GitHub Copilot ACP
│
├── tools/ ← 69个工具文件
│ ├── registry.py ← 工具自动注册中心（最底层）
│ ├── terminal_tool.py ← Shell命令 前台/后台/PTY
│ ├── file_tools.py ← 文件读写搜索patch
│ ├── delegate_tool.py ← 子Agent派发
│ ├── mcp_tool.py ← MCP服务器集成
│ ├── memory_tool.py ← 跨会话记忆工具接口
│ ├── browser_tool.py ← 浏览器自动化 (CDP)
│ ├── send_message_tool.py ← 跨平台消息发送
│ ├── cronjob_tools.py ← 定时任务调度
│ ├── web_fetch.py ← HTTP请求+网页抓取
│ ├── ...56 more tools
│ └── environments/ ← 执行环境适配
│ ├── local.py ← 直接本地执行
│ ├── docker.py ← 容器沙箱执行
│ ├── ssh.py ← 远程SSH执行
│ ├── modal.py ← Modal Serverless
│ └── daytona.py ← Daytona 开发容器
│
├── gateway/ ← 多平台消息网关
│ ├── run.py ← 网关主体 (14,152行) asyncio
│ ├── telegram.py ← Telegram 适配器
│ ├── discord.py ← Discord 适配器
│ ├── slack.py ← Slack 适配器
│ ├── whatsapp.py ← WhatsApp 适配器
│ ├── matrix.py ← Matrix (E2EE) 适配器
│ └── ...17 more platforms
│
├── plugins/ ← 可替换插件系统
│ ├── memory/ ← 记忆后端 (Mem0/Honcho/Supermemory)
│ ├── context_engine/ ← 上下文引擎替换
│ ├── image_gen/ ← 图像生成后端
│ ├── kanban/ ← 任务看板集成
│ ├── observability/ ← 可观测性后端
│ └── platforms/ ← 额外平台适配器
│
├── acp_adapter/ ← ACP Server HTTP接口
├── ui-tui/ ← TUI 前端 (React/Ink, TypeScript)
│
└── tests/ ← 927个测试文件
├── test_agent.py
├── test_tools.py
└── ...
文件命名规范
| 模式 | 位置 | 含义 | 示例 |
|---|---|---|---|
| *_tool.py | tools/ | 单一功能工具文件，自动注册 | terminal_tool.py · browser_tool.py |
| *_tools.py | tools/ | 同类工具集合（多个相关工具） | file_tools.py · cronjob_tools.py |
| *_manager.py | agent/ | 有状态的管理器，跨请求维护状态 | memory_manager.py |
| *_builder.py | agent/ | 构建/生成型模块，无副作用 | prompt_builder.py |
| *_compressor.py | agent/ | 数据转换/压缩处理器 | context_compressor.py |
| *_classifier.py | agent/ | 分类/路由决策模块 | error_classifier.py |
| *_tracker.py | agent/ | 状态追踪，带副作用 | rate_limit_tracker.py |
| *_pool.py | agent/ | 资源池，管理多个同类资源 | credential_pool.py |
| hermes_*.py | 根目录 | 框架级全局基础设施文件 | hermes_state.py · hermes_constants.py |
| run_*.py | 根目录 | 可直接运行的主入口文件 | run_agent.py |