Hermes Agent 架构设计与目录结构解析
jiayong23
Hermes Agent 架构与目录详解
1. 总体架构
从主执行链来看，这个项目可以概括成下面这条主线：
用户入口 -> hermes / hermes_cli.main -> 选择 CLI / TUI / Gateway / ACP / Dashboard / 其他子命令 -> 构造或恢复 AIAgent -> AIAgent.run_conversation() -> model_tools.get_tool_definitions() -> tools.registry + tools/* -> 模型返回 tool calls / text -> 工具执行结果回灌消息历史 -> 会话/记忆/日志/状态落盘
关键架构分层：
- 入口层
hermeshermes_cli/main.py
- Agent 核心层
run_agent.pyagent/
- 工具层
model_tools.pytoolsets.pytools/
- 状态层
hermes_state.py~/.hermes/config.yaml~/.hermes/.env
- 交互层
cli.pyui-tui/tui_gateway/gateway/acp_adapter/hermes_cli/web_server.py
2. 核心执行链说明
2.1 统一入口
hermes- 只是一个极薄的启动包装器。
- 真正入口是
hermes_cli.main:main。
hermes_cli/main.py- 项目总调度入口。
- 负责：
- profile 提前注入
- 读取
.env - 初始化日志
- 构建 argparse 子命令树
- 分发到
setup / gateway / dashboard / cron / doctor / acp / skills / sessions ...
2.2 Agent 核心
run_agent.py- 项目最重要的核心文件。
- 定义
AIAgent。 - 负责：
- 系统提示词拼接
- 工具清单获取
- 与 LLM 交互
- 处理 tool calls
- 上下文压缩
- 记忆注入
- 会话持久化
- 中断/重试/回退
- 轨迹保存
2.3 工具调度
model_tools.py- 是工具编排层，不直接实现工具。
- 负责：
- 自动发现
tools/*.py - 生成 tool schema
- 过滤不可用工具
- 统一派发执行
- 同步/异步桥接
- 自动发现
tools/registry.py- 工具注册中心。
- 每个工具文件在 import 时通过
registry.register(...)自注册。
toolsets.py- 定义工具集合。
- 例如
web、file、terminal、browser、delegation、hermes-cli、hermes-telegram等。
2.4 多入口交互
cli.py- 传统 CLI 的交互壳。
ui-tui/- React + Ink 的 TUI 前端。
tui_gateway/- TUI 的 Python 后端，负责和
AIAgent、会话、slash 命令交互。
- TUI 的 Python 后端，负责和
gateway/- 消息平台网关。
- 一个 Agent 可以挂到多个聊天平台上。
acp_adapter/- 编辑器/ACP 协议接入。
hermes_cli/web_server.py- 本地 Web Dashboard 后端。
3. 顶层目录作用
下表覆盖仓库顶层主要目录：
| 目录 | 作用 |
|---|---|
.github/ | CI、Issue/PR 模板、GitHub 工作流配置。 |
.idea/ | 本地 IDE 配置，不属于核心业务代码。 |
.plans/ | 内部计划文档，偏研发过程资料。 |
acp_adapter/ | ACP 协议适配器，给 VS Code / Zed / JetBrains 等编辑器集成使用。 |
acp_registry/ | ACP 相关元数据与图标。 |
agent/ | Agent 内部能力模块，负责提示词、压缩、记忆、模型元数据、显示等。 |
assets/ | README 或产品展示图片等静态资源。 |
cron/ | 定时任务与调度器。 |
datagen-config-examples/ | 数据生成/训练相关配置样例。 |
docker/ | Docker 运行支持文件。 |
docs/ | 开发文档、设计文档、迁移文档、计划文档。 |
environments/ | RL/训练环境，不是普通运行时 tools/environments/。 |
gateway/ | 消息网关主系统。 |
hermes_cli/ | CLI 命令、配置、安装向导、状态管理、dashboard 启动等。 |
nix/ | Nix/NixOS 打包与环境定义。 |
optional-skills/ | 可选技能库，按领域拆分。 |
packaging/ | 包管理与发布支持，当前可见 Homebrew 打包。 |
plans/ | 计划文档、实现方案。 |
plugins/ | 插件机制相关内容，如 memory provider、dashboard 插件等。 |
scripts/ | 安装、测试、发布、桥接等脚本。 |
skills/ | 内置技能库。 |
tests/ | pytest 测试。 |
tinker-atropos/ | RL 训练相关子模块。 |
tools/ | Agent 工具实现层。 |
tui_gateway/ | TUI 的 Python JSON-RPC 后端。 |
ui-tui/ | TUI 前端，React + Ink。 |
web/ | Web Dashboard 前端，Vite + React。 |
website/ | Docusaurus 文档站，不是运行时产品 UI。 |
4. 根目录关键文件说明
| 文件 | 作用 |
|---|---|
README.md | 对外总说明，包含安装、能力、快速开始。 |
AGENTS.md | 仓库级开发/协作说明，给 AI 助手和开发者使用。 |
pyproject.toml | Python 包定义、依赖、extras、脚本入口。 |
package.json | 根 Node 依赖，主要服务浏览器工具。 |
hermes | 轻量启动器。 |
run_agent.py | AIAgent 核心逻辑。 |
model_tools.py | 工具发现、过滤与统一派发。 |
toolsets.py | 工具分组定义。 |
cli.py | 传统交互式 CLI 主逻辑。 |
hermes_state.py | SQLite 会话数据库。 |
hermes_constants.py | 统一常量和 HERMES_HOME 路径逻辑。 |
hermes_logging.py | 集中式日志初始化。 |
batch_runner.py | 批量运行 Agent，偏研究/数据生成。 |
mcp_serve.py | MCP 相关服务入口。 |
mini_swe_runner.py | 更轻量的 SWE/任务运行器。 |
setup-hermes.sh | Unix/WSL/macOS 开发安装脚本。 |
requirements.txt | 辅助依赖列表。 |
5.agent/目录详解
agent/ 是把原本塞在 run_agent.py 的辅助能力拆出来后的核心模块集。
关键文件：
| 文件 | 作用 |
|---|---|
prompt_builder.py | 组装系统提示词，注入身份、技能、上下文文件、平台提示等。 |
context_compressor.py | 长会话压缩器，避免上下文超限。 |
context_engine.py | 上下文引擎抽象层。 |
memory_manager.py | 统一调度内置记忆和外部记忆 provider。 |
memory_provider.py | 记忆 provider 抽象。 |
prompt_caching.py | Anthropic prompt caching 支持。 |
model_metadata.py | 模型上下文长度、token 估算、模型元数据探测。 |
models_dev.py | provider-aware 模型目录/上下文支持。 |
smart_model_routing.py | 智能模型路由策略。 |
auxiliary_client.py | 辅助模型调用，如视觉、摘要等。 |
display.py | CLI 展示、spinner、tool preview。 |
skill_commands.py | 技能相关 slash command 逻辑。 |
skill_utils.py | 技能扫描、frontmatter、索引辅助。 |
trajectory.py | 轨迹保存与转换。 |
usage_pricing.py | 使用量和成本估算。 |
retry_utils.py | API 重试与退避。 |
error_classifier.py | API 错误分类与回退依据。 |
credential_pool.py | 多凭证池管理。 |
title_generator.py | 会话标题生成。 |
redact.py | 脱敏。 |
整体作用：
- 让
AIAgent不至于把所有辅助逻辑都塞在一个文件里。 - 但目前
run_agent.py仍然非常大，说明拆分还未彻底完成。
6.tools/目录详解
tools/ 是项目执行能力的真正落地点。
6.1 核心基础设施文件
| 文件 | 作用 |
|---|---|
registry.py | 工具注册中心。 |
terminal_tool.py | 终端执行工具，支持多后端。 |
file_tools.py | 读写/搜索/patch 文件。 |
process_registry.py | 后台进程管理。 |
tool_result_storage.py | 工具结果落盘与预算控制。 |
approval.py | 危险命令检测与审批。 |
interrupt.py | 中断信号。 |
path_security.py | 路径安全控制。 |
patch_parser.py | patch 解析。 |
tool_backend_helpers.py | 工具后端选择与公共逻辑。 |
6.2 主要能力型工具
| 文件 | 作用 |
|---|---|
web_tools.py | Web 搜索/提取/爬取。 |
browser_tool.py | 浏览器自动化。 |
vision_tools.py | 图像理解。 |
image_generation_tool.py | 图片生成。 |
code_execution_tool.py | 在沙箱里执行可调用工具的 Python。 |
delegate_tool.py | 生成子代理执行子任务。 |
mcp_tool.py | 外部 MCP server 工具接入。 |
memory_tool.py | 记忆工具。 |
todo_tool.py | 待办/计划工具。 |
session_search_tool.py | 历史会话搜索。 |
send_message_tool.py | 跨平台消息发送。 |
cronjob_tools.py | 定时任务管理。 |
tts_tool.py | 文本转语音。 |
transcription_tools.py | 语音转文本。 |
homeassistant_tool.py | Home Assistant 集成。 |
skills_tool.py / skill_manager_tool.py | 技能列表、查看、管理。 |
mixture_of_agents_tool.py | 高级推理/多代理融合能力。 |
rl_training_tool.py | RL 训练相关工具。 |
6.3tools/environments/
这是终端后端实现，不要和仓库根目录 environments/ 混淆。
| 文件 | 作用 |
|---|---|
local.py | 本地执行。 |
docker.py | Docker 环境。 |
ssh.py | SSH 远程环境。 |
modal.py / managed_modal.py | Modal 云环境。 |
daytona.py | Daytona 环境。 |
singularity.py | Singularity 环境。 |
file_sync.py | 跨环境文件同步。 |
base.py | 终端后端抽象。 |
7.gateway/目录详解
gateway/ 是一个完整子系统，作用是把 Hermes 暴露到聊天平台。
关键文件：
| 文件 | 作用 |
|---|---|
run.py | 网关主循环与生命周期管理。 |
config.py | 平台配置模型。 |
session.py | 平台会话上下文与会话路由。 |
session_context.py | 会话变量和上下文注入。 |
delivery.py | 消息投递路由。 |
status.py | 网关状态。 |
pairing.py | 配对和权限控制。 |
hooks.py | 网关事件钩子。 |
restart.py | 平滑重启逻辑。 |
stream_consumer.py | 流式输出消费。 |
channel_directory.py | 平台频道/房间目录解析。 |
7.1gateway/platforms/
这里是一组平台适配器。
代表性文件：
base.py- 平台适配器基类。
telegram.py- Telegram 适配。
discord.py- Discord 适配。
slack.py- Slack 适配。
whatsapp.py- WhatsApp 适配。
signal.py- Signal 适配。
matrix.py- Matrix 适配。
email.py- Email 适配。
homeassistant.py- Home Assistant 适配。
webhook.py- Webhook 适配。
api_server.py- OpenAI 兼容 API Server 适配器。
8.hermes_cli/目录详解
这是“命令与配置中枢”，偏控制面。
关键文件：
| 文件 | 作用 |
|---|---|
main.py | CLI 统一主入口与命令树。 |
config.py | 配置默认值、迁移、配置文件路径。 |
setup.py | 交互式安装向导。 |
commands.py | slash 命令注册表。 |
auth.py | Provider 凭证解析。 |
gateway.py | CLI 对网关管理命令的包装。 |
doctor.py | 诊断命令。 |
status.py | 状态汇总命令。 |
model_switch.py | 模型切换流程。 |
models.py | 模型目录。 |
skills_hub.py | 技能 Hub 命令面。 |
skills_config.py | 技能启用/禁用配置。 |
tools_config.py | 工具启用/禁用配置。 |
skin_engine.py | 皮肤/主题系统。 |
web_server.py | Web Dashboard 的 FastAPI 服务。 |
profiles.py | 多 profile 支持。 |
plugins.py | 插件发现与调用。 |
memory_setup.py | 记忆后端安装与配置。 |
logs.py | 日志查看命令。 |
backup.py | 备份与恢复。 |
9.ui-tui/与tui_gateway/
这两个目录共同组成新的 TUI 体系。
9.1ui-tui/
这是前端界面层，React + Ink。
ui-tui/src/ 主要子目录：
| 子目录 | 作用 |
|---|---|
app/ | TUI 主状态机、事件处理、slash 处理。 |
components/ | Ink 组件。 |
domain/ | 领域对象与纯逻辑。 |
hooks/ | 输入、队列、补全、历史等 hooks。 |
lib/ | RPC、消息、文本、OSC52 等工具函数。 |
protocol/ | 与后端交互协议辅助。 |
types/ | 类型定义。 |
__tests__/ | TUI 单元测试。 |
关键文件：
src/entry.tsx- TUI 前端入口。
src/app.tsx- 主 UI 状态与组件装配。
src/gatewayClient.ts- 启动 Python 子进程并通过 stdio JSON-RPC 通信。
9.2tui_gateway/
这是 TUI 的 Python 后端。
| 文件 | 作用 |
|---|---|
entry.py | stdio JSON-RPC 入口。 |
server.py | 请求处理、session 管理、Agent 调用。 |
render.py | 可选 ANSI 渲染桥。 |
slash_worker.py | 持久化 slash 命令子进程。 |
10.acp_adapter/
作用：
- 把 Hermes 作为 ACP Agent 暴露给编辑器。
- 让编辑器通过协议和 Hermes 交互，而不只是启动一个命令行。
关键文件：
| 文件 | 作用 |
|---|---|
entry.py | ACP 入口。 |
server.py | ACP Agent 服务器实现。 |
session.py | ACP 会话管理。 |
tools.py | ACP 可暴露的工具。 |
permissions.py | 权限控制。 |
events.py | 事件处理。 |
auth.py | 认证。 |
11.cron/
作用：
- 管理定时任务定义、调度与执行。
关键文件：
| 文件 | 作用 |
|---|---|
jobs.py | 定时任务存取。 |
scheduler.py | 周期性扫描并执行 due jobs。 |
12.environments/
这个目录是研究/RL 环境，不是普通用户日常 CLI 的终端后端。
关键文件：
| 文件 | 作用 |
|---|---|
hermes_base_env.py | RL 环境基类。 |
agent_loop.py | 面向环境的 Agent 循环。 |
tool_context.py | 工具上下文桥接。 |
web_research_env.py | Web Research 环境。 |
agentic_opd_env.py | 代理型 OPD 环境。 |
README.md | 训练环境说明。 |
子目录：
benchmarks/- benchmark 配置。
hermes_swe_env/- SWE 类环境。
terminal_test_env/- 终端测试环境。
tool_call_parsers/- 工具调用解析器。
13.skills/、optional-skills/、plugins/
13.1skills/
内置技能库，按领域划分，例如：
software-development/research/productivity/github/apple/smart-home/creative/data-science/mcp/
每个技能通常包含：
SKILL.md- 可选
references/ - 可选
scripts/ - 可选
templates/
13.2optional-skills/
可选技能包，说明这些技能不一定默认启用，偏扩展或专业领域。
13.3plugins/
当前可见主要是：
memory/- 多种记忆后端 provider。
context_engine/- 上下文引擎插件。
example-dashboard/- dashboard 插件示例。
14.web/与website/的区别
这两个目录容易混淆。
web/
- 运行时 Web Dashboard 前端。
- Vite + React。
- 配合
hermes_cli/web_server.py工作。
website/
- Docusaurus 文档站。
- 用于发布官网文档，不是用户运行时控制台。
15.tests/
tests/ 数量很多，说明项目工程化程度较高。
特点：
- 大量
gateway/测试，说明消息平台是重点能力。 - 有
tui_gateway/、平台适配器、API server、session、config、memory、tools 等测试。 - 仓库明确要求优先用
scripts/run_tests.sh跑测试，以保持和 CI 一致。
16. 架构总结
这个项目的目录结构体现出 3 个非常鲜明的事实：
- 它不是一个单体 CLI，而是一个多入口代理平台。
- 其核心价值不在 UI，而在
AIAgent + Tools + Session + Gateway。 - 它已经具备“平台型代码库”特征，因此理解时必须按子系统切分，而不能按单文件线性阅读。
到此这篇关于Hermes Agent 架构设计与目录结构解析的文章就介绍到这了,更多相关Hermes Agent 架构内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！