Hermes Agent 源码解析 · 第 3 讲
Hermes Agent 源码解析 第 3 讲：工具系统深度解析——ToolRegistry、ToolSet、自注册机制与 check_fn 探针 基于 Hermes Agent v0.16.0 源码 · 2026-06-16 一、工具系统：Agent 的"四肢" 前两讲我们建立了全局架构地图并深入了对话循环。这一讲我们聚焦 Hermes 最活跃的代码区域之一—— 工具系统 （Tool System）。工具是 Agent 与外部世界交互的唯一通道：执行命令、读写文件、搜索网页、操控浏览器、调度定时任务……每一轮对话中，LLM 看到的"工具列表"就是 Agent 的能力边界。 📦 源码仓库 https://github.com/NousResearch/hermes-agent 本地源码： ~/.hermes/hermes-agent/ 本讲核心文件： tools/registry.py （589 行）— 注册中心 toolsets.py （912 行）— 工具集定义 model_tools.py （1229 行）— 编排层 tools/tool_search.py （735 行）— 渐进式工具披露 二、整体架构：三层分离设计 Hermes 工具系统采用经典的 三层架构 ，每层职责清晰、互不耦合： +--------------------------------------------------------------+ | 第 1 层：工具实现层 | | | | tools/terminal_tool.py 动态导入 | | • check_fn TTL cache: 30s 缓存外部探针结果 | | • _generation 计数器: 变更感知 + 缓存失效 | | • dispatch(): 统一分发入口，async 桥接 | | • get_definitions(): 按需产出 OpenAI 格式 schema | +--------------------------------------------------------------+ | 第 3 层：编排层 (Orchestration) | | | | toolsets.py — 工具集定义与解析 | | • TOOLSETS dict: 60+ 预定义工具集 (hermes-cli, hermes-…) | | • resolve_toolset(): 递归解析，含循环检测 | | • _HERMES_CORE_TOOLS: 核心工具白名单 (~55 个) | | | | model_tools.py — 公共 API + 分发流水线 | | • get_tool_definitions(): 过滤 + 缓存 + 动态 schema 注入 | | • handle_function_call(): 参数修正 > 中间件 > 分发 > 后处理 | | • _run_async(): 线程安全的 async 桥接 | | • coerce_tool_args(): LLM 参数类型修正 | | • tool_search 集成: 渐进式工具披露 | +--------------------------------------------------------------+ 导入链 (循环导入安全): tools/registry.py (零外部依赖) ↑ tools/*.py (导入 registry.register) ↑ model_tools.py (导入 registry + 所有工具模块) ↑ run_agent.py, cli.py, gateway/run.py 设计哲学： 注册中心不依赖任何工具模块，工具模块只依赖注册中心，编排层最后导入一切。这个"V 字形"导入链彻底消除了循环导入——5000+ 行代码无需 if TYPE_CHECKING 或延迟导入。 三、自注册机制：AST 扫描 + 模块级注册 1. discover_builtin_tools() — 零配置发现 启动时，Hermes 不需要配置文件来声明"有哪些工具"。它通过 AST 静态分析 自动发现： 📄 tools/registry.py (第 29-74 行) def _i…