Hermes Agent 架构全景与设计哲学

📐 1. 核心设计：“沙漏”与极窄“腰部”（Narrow Waist）

在设计工业级的 LLM 智能体时，初学者最容易犯的错误就是“贪多”——不断给核心系统增加接口、工具和特设规则。然而，在 LLM 体系中，每一次 API 请求都必须发送所有可用工具的 Schema。工具越多，消耗的上下文和 Token 越多，推理速度就越慢，且模型产生逻辑幻觉的几率会成倍攀升。

基于此，Hermes 贯彻了“极窄腰部（Narrow Waist）”的设计哲学，其形态如同沙漏：

• 最少的核心工具集（Core Toolset）：只有最根本的、无法被替代的基础设施级工具（如 read_file, terminal, web_search, browser_navigate）才能进入 Core Toolset。在 toolsets.py 中由 _HERMES_CORE_TOOLS 列表静态锁定。
• 能力向边缘释放（Edges Layer）：绝大多数新能力应通过 CLI 子命令、独立 Skills、插件扩展（Memory Provider, Inference Backend）或外部独立进程接入，绝不污染 Core Layer。

🧬 2. 核心大板块与系统职责映射

正如全景架构图所示，Hermes-Agent 由六个高内聚的系统模块与协议层级组成，保障了架构的稳定与灵活：

📁 3. 极简代码目录与文件职责指南

在开始深入研究代码前，请牢记核心源文件的存放地址与具体职责分工。这能帮初学者快速建立代码映射：

🧠 Agent 核心逻辑区

• run_agent.py：定义主大脑 AIAgent 类。它是智能体生命周期的源头，包含对话决策主循环、Token预算控制以及 Kanban 派发逻辑。
• agent/conversation_loop.py：承载了 run_conversation 单个 Turn 内具体的 LLM 请求打包、中断信号拦截、重试逻辑等底层会话支撑。
• agent/conversation_compression.py：上下文压缩核心。包含 compress_context()，负责调用辅助小模型生成历史摘要，对 state.db 对话数据进行在线切除和合并。

🛠️ 工具与校验层

• model_tools.py：定义核心工具管理器与分发拦截逻辑。负责在启动时执行 discover_builtin_tools()。
• tools/registry.py：核心工具注册表，包含 @registry.register 装饰器，负责利用 inspect 内省自动反射生成大模型调用的 schema 元数据。
• agent/message_sanitization.py：输入净化与容错黑科技，包含 _repair_tool_call_arguments() 自动修复损坏的 JSON 格式，过滤非规范字符。

💾 状态与数据管理

• hermes_state.py：包含会话状态数据库 SessionDB 类。管理事务，支持 WAL 降级、Jitter Retry 重试避堵锁、及 schema 在线修复。

🔌 网关、协议与并发层

• gateway/run.py：网关核心进程。管理 GatewayRunner，用于轮询及接收外部通讯请求，支持并发去重，防止消息重入。
• acp_adapter/：编辑器适配器目录。基于 LSP 协议和标准 MCP 协议实现本地编辑器（VSCode, Zed）与 Hermes 执行引擎的桥接。
• batch_runner.py：高并发批量任务引擎。基于线程池隔离执行任务切片，聚合统计 Token 消耗并安全并发回写数据库。

📺 终端交互（TUI）

• tui_gateway/server.py：JSON-RPC websocket 服务端，映射并执行来自终端 UI 的一切交互控制操作。
• tui_gateway/slash_worker.py：提供后台工作线程，用于排队处理 TUI 中耗时且带有锁开销的斜杠快捷指令（如 /compress）。

🔗 本章子任务深入剖析专栏

为深度掌握系统全景，推荐阅读以下子配置专题，直达源码解析：

• Profile 常量定义与日志分流 (hermes_constants.py & hermes_logging.py)
• 计费追踪与额度耗尽强力拦截 (credits_tracker.py 与 API 超支保护)