Hermes 源码拆解|L4 工具:`tools/` + `model_tools.py` + `toolsets.py`

源码拆解 ｜ Hermes Agent

55+工具、13个核心模块、7道安全防线、40+场景工具集。

读完这篇，你会明白：为什么有的 Agent 只能聊天，有的却能真的「干活」。

🎯 一句话定位

如果把 LLM 比作大脑，那 Hermes 的 L4 工具层就是四肢 + 五感——让 AI 真正能摸到世界：开浏览器、跑命令、读写文件、搜网页、调用 API、委派子任务。

没有 L4，Agent 只是聊天机器人。有了 L4，才是生产级 AI 员工。

🔥 核心痛点

🏗️ 架构全景

L2 主循环 → `model_tools.py` + `toolsets.py` → `tools/registry.py`（483行）→ 分发到 60+ 工具实现文件。一个工具调用的生命周期：LLM 产出 tool_call → 参数纠错 → 插件 pre_tool_call → registry.dispatch() → 插件 post_tool_call → 返回 JSON → 追加到 messages → 继续主循环。

🔧 13 个核心模块

① registry.py — 工具报到处 + 派单中心 📋

像滴滴司机平台：司机上线报到 → 平台记录 → 乘客发单 → 平台派单。6 个巧妙设计：AST 按需发现、注册冲突保护、线程安全 snapshot、统一 OpenAI schema、check_fn 延迟求值 + 去重、tool_error/tool_result 便捷函数。

② model_tools.py — 工具派单薄封装 📨

解决三个坑：参数类型自动纠错（LLM 常把数字写成字符串，这里自动转换）；动态 schema 重写（防止模型幻觉调用未启用的工具）；三级 async 桥接（Python 生产级 sync/async 混写的黄金模板）。

③ toolsets.py — 场景化套餐菜单 📒

像电信套餐：基础语音(web)、国际漫游(browser)、家庭组合(cli)、学生套餐(safe)。三层结构：基础层按工具类型 → 组合层（research = web + vision + search）→ 场景层（cli / telegram / editor / safe）。产品价值：把「技术工具」翻译成「产品套餐」——Free = safe，Pro = full_stack，企业版 = 全量。

④ terminal_tool.py — 沙盒任意门 💻

6 种后端：local / docker / modal / SSH / singularity / daytona。关键安全特性：Sudo rewrite（重写为审批）、Destructive detection（`rm/dd/git reset –hard` 触发检查点）、Approval callback、Interrupt handling（Ctrl+C 立即杀子进程）、Disk warning（超 500GB 告警）。process 工具管理后台进程——`npm run dev` 可以 nohup 到后台查/杀。

⑤ file_tools.py — 文件系统四把军刀 📁

read_file 的 7 层保护：设备文件 guard、二进制 guard、内部路径 guard、Dedup cache、字符数上限、Redaction（读后擦除 API key）、Large file hint。write_file：敏感路径检查 + stale read warning。patch 模糊匹配（4 级）：精确 → 去空白 → normalize 换行符 → 编辑距离阈值。

⑥ browser_tool.py — 带勇气的浏览器自动化 🌍

10 个工具：navigate / snapshot / click / type / scroll / back / press / get_images / vision / console / cdp。3 种后端：Playwright headless / Camofox / Cloud。5 层安全防护：Secret exfil（URL 含密钥直接拒）、SSRF 防护、Website policy 黑白名单、URL decoding 防绕过、OSV 恶意域名检测。Accessibility-tree-first：返回结构化树，token 省 10×。

⑦ code_execution_tool.py — PTC 架构 🐍

让 LLM 直接写 Python 脚本而不是发一堆 tool_call，一次 API 调用完成多步逻辑。传统 tool_call = 客人一道一道点菜（10 道菜 10 轮），PTC = 客人把菜谱写给主厨（一次性完成）。沙箱白名单仅 7 个工具，故意排除 browser/delegate/memory 防深层嵌套。资源限制：5 分钟超时 / 50 次工具调用。产品价值：延迟从 N×T 降到 1×T'，API 成本降 N 倍——革命性优化。

⑧ delegate_tool.py — 外包给子 Agent 🤖

像项目经理派活：主 Agent 规划，子 Agent 执行。关键约束：深度限制 `MAX_DEPTH = 2`、并发限制（默认 5）、子 Agent 不能有 `delegate_task`、独立 IterationBudget。成本优化：主 Agent 用 Opus，子 Agent 用 Haiku——成本砍 10 倍。

⑨ mcp_tool.py — 万能 USB 接口 🔌

把任何 MCP 外部服务动态注册成工具。读 config.yaml → 连接 server → 发现 tools/resources/prompts → schema 转换 → 描述扫描（防 prompt injection）→ 加 server 前缀 → registry.register → 订阅 list_changed 动态增删。产品价值：Cursor/Claude Desktop 的 MCP server，Hermes 也能用——生态指数级扩展。

⑩ memory_tool + session_search — 长期记忆双子座 🧠

• memory_tool
  
  ：管理 `MEMORY.md` + `USER.md`，自动去重 + 文件锁

• session_search
  
  ：SQLite 全文搜索历史会话，语义摘要

分工：不变事实 → memory_tool（每次系统提示加载）；特定任务结果 → session_search（按需召回）。产品价值：产品粘性 = 记忆 × 时间——越用越懂你。

⑪ skills_tool + skills_hub — 经验沉淀系统 🎭

三个工具：`skills_list` / `skill_view` / `skill_manage`。

skills_hub.py (3053 行)：技能市场——从官方 hub 下载社区技能，本地与 hub 双向同步。

skills_guard 加载时扫描 prompt injection。周期性 nudge 每 10 次迭代提醒模型「是否沉淀为技能？」。

产品价值：Agent 从「工具」升级到「学徒」——时间越长越有价值。

⑫ Meta 工具 — 元能力全家桶 📋

⑬ 安全工具层 — 七道防线 🛡️

关键洞察：安全不是一次性「架构决策」，而是分散在工具层的无数小守门员。每个工具内部都要检查边界——不能指望主循环统一鉴权。

🔀 四个关键设计权衡

1. 注册表：单例 vs 依赖注入——Hermes 选全局单例，工具 import 时自动注册，零配置，加文件即生效。单例适合 CLI/单进程，长期托管 SaaS 需额外设计。

2. 工具粒度：精细 vs 合并——Hermes 选精细派（`browser_click/browser_type` 独立 10 个工具），schema 更清晰，description 更精准。工具数量 > token 数量——有足够上下文时，精细粒度对 LLM 更友好。

3. 执行模型：sync-first vs async-first——Hermes 选 sync-first + async 桥接。工具大量涉及 subprocess、文件 I/O，天然 sync；`_run_async` 提供干净逃生口。

4. 可扩展性分层：Registry（内建工具）→ Plugin system（一等公民插件）→ MCP（协议级外挂）。成熟项目需要分层扩展。

💡 AI 产品经理特别洞察

可直接搬走的设计

Hermes 做对的差异化

局限与边界

• 工具数量上限
  
  55+ 工具 schema 占 10-15K tokens，64K 上下文模型上占 20%

• 并发安全「尽力而为」
  
  用户自写 MCP 工具不遵守协议仍可能踩踏

• PTC 沙箱限制死
  
  7 个白名单工具，无法调 delegate/browser/memory

🌟 结语

LLM 的能力上限已经很高了，但产品能跑多远，取决于工具层有多扎实。

L2 是「心脏」，L3 是「神经」，L4 才是 Agent 能不能真正干活的手脚。

55+ 工具 + 3 层扩展机制 + 7 道安全防线 + 40+ 场景套餐——这决定了 Hermes 不只是一个「LLM 封装器」，而是一个「生产级 AI 员工平台」。

当你评估「要不要基于 LangChain / AutoGen / Hermes 起步」时，L4 的完备度是关键指标——你愿意为哪些工具从零写起？答案就是差距。

而 Hermes 的开放性（plugin + MCP + registry），意味着它不仅是产品，更是生态基础设施——你可以往上加自己的工具、技能、provider，而不被框架绑死。

这，就是 Hermes 值得被反复研读的原因。

点击左下方“阅读原文”查看完整拆解内容