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.pyAgent 核心层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.py2. 核心执行链说明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 命令交互。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.tomlPython 包定义、依赖、extras、脚本入口。package.json根 Node 依赖主要服务浏览器工具。hermes轻量启动器。run_agent.pyAIAgent核心逻辑。model_tools.py工具发现、过滤与统一派发。toolsets.py工具分组定义。cli.py传统交互式 CLI 主逻辑。hermes_state.pySQLite 会话数据库。hermes_constants.py统一常量和HERMES_HOME路径逻辑。hermes_logging.py集中式日志初始化。batch_runner.py批量运行 Agent偏研究/数据生成。mcp_serve.pyMCP 相关服务入口。mini_swe_runner.py更轻量的 SWE/任务运行器。setup-hermes.shUnix/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.pyAnthropic prompt caching 支持。model_metadata.py模型上下文长度、token 估算、模型元数据探测。models_dev.pyprovider-aware 模型目录/上下文支持。smart_model_routing.py智能模型路由策略。auxiliary_client.py辅助模型调用如视觉、摘要等。display.pyCLI 展示、spinner、tool preview。skill_commands.py技能相关 slash command 逻辑。skill_utils.py技能扫描、frontmatter、索引辅助。trajectory.py轨迹保存与转换。usage_pricing.py使用量和成本估算。retry_utils.pyAPI 重试与退避。error_classifier.pyAPI 错误分类与回退依据。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.pypatch 解析。tool_backend_helpers.py工具后端选择与公共逻辑。6.2 主要能力型工具文件作用web_tools.pyWeb 搜索/提取/爬取。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.pyHome Assistant 集成。skills_tool.py/skill_manager_tool.py技能列表、查看、管理。mixture_of_agents_tool.py高级推理/多代理融合能力。rl_training_tool.pyRL 训练相关工具。6.3tools/environments/这是终端后端实现不要和仓库根目录environments/混淆。文件作用local.py本地执行。docker.pyDocker 环境。ssh.pySSH 远程环境。modal.py/managed_modal.pyModal 云环境。daytona.pyDaytona 环境。singularity.pySingularity 环境。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.pyTelegram 适配。discord.pyDiscord 适配。slack.pySlack 适配。whatsapp.pyWhatsApp 适配。signal.pySignal 适配。matrix.pyMatrix 适配。email.pyEmail 适配。homeassistant.pyHome Assistant 适配。webhook.pyWebhook 适配。api_server.pyOpenAI 兼容 API Server 适配器。8.hermes_cli/目录详解这是“命令与配置中枢”偏控制面。关键文件文件作用main.pyCLI 统一主入口与命令树。config.py配置默认值、迁移、配置文件路径。setup.py交互式安装向导。commands.pyslash 命令注册表。auth.pyProvider 凭证解析。gateway.pyCLI 对网关管理命令的包装。doctor.py诊断命令。status.py状态汇总命令。model_switch.py模型切换流程。models.py模型目录。skills_hub.py技能 Hub 命令面。skills_config.py技能启用/禁用配置。tools_config.py工具启用/禁用配置。skin_engine.py皮肤/主题系统。web_server.pyWeb 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.tsxTUI 前端入口。src/app.tsx主 UI 状态与组件装配。src/gatewayClient.ts启动 Python 子进程并通过 stdio JSON-RPC 通信。9.2tui_gateway/这是 TUI 的 Python 后端。文件作用entry.pystdio JSON-RPC 入口。server.py请求处理、session 管理、Agent 调用。render.py可选 ANSI 渲染桥。slash_worker.py持久化 slash 命令子进程。10.acp_adapter/作用把 Hermes 作为 ACP Agent 暴露给编辑器。让编辑器通过协议和 Hermes 交互而不只是启动一个命令行。关键文件文件作用entry.pyACP 入口。server.pyACP Agent 服务器实现。session.pyACP 会话管理。tools.pyACP 可暴露的工具。permissions.py权限控制。events.py事件处理。auth.py认证。11.cron/作用管理定时任务定义、调度与执行。关键文件文件作用jobs.py定时任务存取。scheduler.py周期性扫描并执行 due jobs。12.environments/这个目录是研究/RL 环境不是普通用户日常 CLI 的终端后端。关键文件文件作用hermes_base_env.pyRL 环境基类。agent_loop.py面向环境的 Agent 循环。tool_context.py工具上下文桥接。web_research_env.pyWeb 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。它已经具备“平台型代码库”特征因此理解时必须按子系统切分而不能按单文件线性阅读。