四个工具剖面

本章核心源码：tools/terminal_tool.py（1627 行）、tools/file_tools.py（835 行）、tools/browser_tool.py（2178 行）、tools/mcp_tool.py（2186 行）

定位：本章不平均讲全部工具，而是挑最能体现设计思想的四类做深度剖面：Terminal（执行环境抽象）、File（读写防护）、Browser（资源生命周期）、MCP（外部能力热更新）。 前置依赖：第 6 章（工具系统）。适用场景：想理解具体工具如何实现，或准备开发新工具。

为什么选这四个

在数十个工具相关文件中，大多数都遵循相同的模式：定义 schema → 实现 handler → 调用 registry.register()。但有四个工具代表了四种不同的设计问题：

剖面一：Terminal — 六种执行后端的统一抽象

tools/terminal_tool.py 是项目中最复杂的工具之一。它的核心问题不是"怎么执行命令"，而是"怎么让同一个 execute_command 工具在本地、Docker、SSH、Daytona、Singularity 和 Modal 六种环境中透明运行"。

后端架构

六种后端实现在 tools/environments/ 目录下，每种继承自 BaseEnvironment：

tools/environments/
├── base.py              # BaseEnvironment ABC
├── local.py             # 本地执行
├── docker.py            # Docker 容器
├── ssh.py               # SSH 远程执行
├── daytona.py           # Daytona serverless（环境休眠/唤醒）
├── singularity.py       # Singularity/Apptainer（HPC 场景）
├── modal.py             # Modal 直连（GPU 云）
├── managed_modal.py     # Modal 托管模式
└── persistent_shell.py  # 持久 shell 会话（SSH/本地复用）

后端选择通过环境变量 TERMINAL_ENV 或 config.yaml 的 terminal.backend 配置。一旦选定，对模型和编排层完全透明，模型不知道自己在调用本地 shell 还是远程 Docker 容器。

环境生命周期管理

每个后端实例有生命周期。terminal_tool.py 的后台清理线程每 60 秒检查一次（tools/terminal_tool.py:715）：

# tools/terminal_tool.py（清理逻辑简化）
# 每 60 秒检查一次
if inactive_seconds > TERMINAL_LIFETIME_SECONDS:  # 默认 300 秒
    # 检查 process_registry 中是否有活跃后台进程
    if not has_active_background_processes():
        cleanup_environment(env)

关键细节：清理前会检查 process_registry 中是否有活跃的后台进程。如果 agent 启动了一个长时间运行的 build 任务，环境不会被过早清理。

危险命令检测

_is_destructive_command()（run_agent.py:254）在执行前检查命令模式（详见第 6 章）。匹配到的命令通过 clarify_callback 请求用户确认。

设计哲学：在执行处设门，而非在思考处设门 Hermes 不阻止模型建议危险命令——它让模型自由思考，然后在执行处通过审批设门。这是纵深防御：在思考阶段过滤（通过 prompt 指令）是不可靠的，因为模型不总是遵循指令。在执行边界过滤（通过对实际命令字符串的正则匹配）是确定性的。团队信任模型可以建议任何东西，然后在边界处强制安全。来源：tools/approval.py:64-126。

设计要点

Terminal 工具最有价值的设计决策是让执行环境成为正交关注点。添加新后端（比如未来的 Kubernetes Pod）只需要：

1. 在 tools/environments/ 下实现 BaseEnvironment 的子类
2. 在 terminal_tool.py 的配置解析中添加一个新的后端名称

不需要修改编排层、工具系统或任何其他工具。

剖面二：File — 读写防护与结果控制

tools/file_tools.py 注册了 4 个工具：read_file、write_file、patch、search_files。它的设计问题不是"怎么读写文件"，而是"怎么防止 agent 的文件操作失控"。

结果大小控制

# tools/file_tools.py:832-835
registry.register(name="read_file", ..., max_result_size_chars=float('inf'))  # 无限
registry.register(name="write_file", ..., max_result_size_chars=100_000)       # 100K
registry.register(name="patch", ..., max_result_size_chars=100_000)            # 100K
registry.register(name="search_files", ..., max_result_size_chars=100_000)     # 100K

read_file 的 max_result_size_chars 设为 float('inf')——允许读取任意大小的文件。但这不意味着无限制：read_file_tool 有自己的 offset 和 limit 参数（tools/file_tools.py:280），默认只返回前 500 行。模型需要显式请求更多内容。

write_file 和 patch 则设置了 100K 字符的硬上限。超过这个限制的结果会被截断并写入临时文件，返回文件路径让模型按需读取。

并发安全

File 工具的 read_file 在第 6 章的 _PARALLEL_SAFE_TOOLS 集合中，可以安全并行。write_file 和 patch 在 _PATH_SCOPED_TOOLS 中——只有当目标路径不重叠时才允许并行。

剖面三：Browser — 有状态资源的生命周期管理

tools/browser_tool.py（2178 行）是工具系统里最大的实现文件之一。它的核心设计问题是：浏览器会话是有状态的外部资源，怎么防止泄漏？

三层清理防线

graph TD
    A["第 1 层：超时清理线程<br/>每 30 秒检查不活跃会话"] --> D["会话释放"]
    B["第 2 层：atexit 紧急清理<br/>进程退出时触发"] --> D
    C["第 3 层：Provider 级 emergency_cleanup<br/>单个会话强制释放"] --> D

第 1 层：后台守护线程（tools/browser_tool.py:367）每 30 秒检查一次，清理超过 BROWSER_SESSION_INACTIVITY_TIMEOUT（默认 300 秒）不活跃的会话。

第 2 层：atexit.register(_emergency_cleanup_all_sessions)（tools/browser_tool.py:407）在进程退出时触发紧急清理。使用 _cleanup_done 标志防止重复执行。

第 3 层：每个 browser provider（Browserbase、Firecrawl、browser_use）实现自己的 emergency_cleanup(session_id) 方法，处理 provider 级别的资源释放。

为什么不用 SIGTERM handler

tools/browser_tool.py:401-404 的注释解释了为什么不用信号处理器：

Previous versions installed SIGINT/SIGTERM handlers, but this corrupts the coroutine state and makes the process unkillable. atexit is safer.

信号处理器在 asyncio 环境中会破坏协程状态——而浏览器工具的底层大量使用 asyncio（Playwright、CDP 连接等）。atexit 更安全，因为它在 Python 解释器正常退出流程中被调用。

设计要点

Browser 工具的教训是：有状态外部资源必须有多层清理防线。单一清理机制（比如只靠超时）在进程崩溃时会失效。三层防线（超时 + atexit + provider 级清理）确保了在正常退出、异常退出、甚至 provider 内部错误三种场景下都能释放资源。

剖面四：MCP — 外部能力的动态接入

tools/mcp_tool.py（2186 行）实现了 Model Context Protocol 的客户端。它的设计问题是：怎么让外部进程的工具像内置工具一样被发现、注册和调度？

发现流程

# model_tools.py:172-177
from tools.mcp_tool import discover_mcp_tools
discover_mcp_tools()

discover_mcp_tools()（tools/mcp_tool.py:1950）读取 config.yaml 中的 MCP server 配置，为每个 server 启动进程，通过 MCP 协议获取工具列表，然后为每个工具调用 registry.register()。

MCP 工具的名称会添加 server 前缀以避免冲突（如 mcp_github_create_issue）。

热更新：tools/list_changed

MCP 协议支持 server 端通知 client 工具列表变化。Hermes 的处理（tools/mcp_tool.py:755）：

# tools/mcp_tool.py（简化）
# 收到 notifications/tools/list_changed
# 1. Deregister 该 server 所有旧工具
for prefixed_name in old_tool_names:
    registry.deregister(prefixed_name)
# 2. 重新获取工具列表
new_tools = await server.list_tools()
# 3. 注册新工具
for tool in new_tools:
    registry.register(prefixed_name, ...)

这个 deregister → re-fetch → register 的模式让 MCP server 可以在运行时添加/移除工具，Hermes 会自动跟上——不需要重启。

设计要点

MCP 工具展示了 ToolRegistry 设计的灵活性：deregister() 方法的存在让动态工具管理成为可能。如果 registry 只支持 register() 不支持 deregister()，MCP 热更新就无法实现。

四个剖面的共同启示

第 8 章将转向技能系统——Hermes "self-improving" 理念的核心实现。

设计赌注回扣：Terminal 的六种后端直接服务于 Run Anywhere（从本地到 Modal GPU 集群透明切换）；MCP 的动态接入服务于 Learning Loop（agent 可以通过 MCP 扩展自己的能力边界，不受核心代码库限制）。

版本演化说明

本章核心分析基于 Hermes Agent v0.8.0（2026 年 4 月）。 终端后端、browser 清理和 MCP 动态发现都不是同一个 release 一次做完的。可以明确确认的是：Daytona 已在 v0.3.0 发布窗口出现，notifications/tools/list_changed 驱动的 MCP 热更新在 v0.6.0 发布窗口出现；其余隔离与清理策略则在后续几个 release 中持续收紧。