Toolsets 工具集 —— 30+ 工具启用管理、hermes tools 命令、工具开关与依赖检查

简介

上一篇我们深入探讨了 Hermes Agent 的 Provider 配置体系，实现了 20+ 模型提供商的自由切换。有了强大的模型支持后，Agent 还需要"手脚"去执行实际操作——这就是 Toolsets（工具集） 的核心价值。

Hermes Agent 内置 30+ 工具，覆盖文件操作、Shell 执行、网络请求、代码分析、Git 管理、浏览器自动化等几乎所有开发场景。但工具不是越多越好——合适的工具开关、精确的依赖管理、高效的工具发现才是让 Agent 真正高效的关键。

本文将带你全面掌握 Hermes Agent 的工具集体系：

工具全景：30+ 内置工具分类速查
hermes tools 命令：工具查询、启用、禁用、依赖检查
工具开关策略：按任务类型动态加载工具
依赖管理：自动检测外部依赖并提示安装
自定义工具：注册你自己的工具

工具集的核心原则：不是让 Agent 拥有所有工具，而是让 Agent 在每次任务中只加载需要的工具。

30+ 内置工具全景

Hermes Agent 的工具按功能分为七大类别，每个工具都有清晰的描述和参数定义，模型可以自动理解工具用途并正确调用。

text

┌─────────────────────────────────────────────────────────────────┐
│                    Hermes Agent 工具集全景                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  📁 文件操作 (6)                                                 │
│  ├── read_file      - 读取文件内容                              │
│  ├── write_file     - 写入/创建文件                             │
│  ├── patch          - 精确查找替换编辑文件                       │
│  ├── list_directory - 列出目录内容                              │
│  ├── file_info      - 获取文件元信息                            │
│  └── file_search    - 按名称/模式搜索文件                       │
│                                                                 │
│  💻 Shell 执行 (4)                                               │
│  ├── terminal       - 执行 Shell 命令                           │
│  ├── process        - 管理后台进程                              │
│  ├── shell_session  - 持久 Shell 会话                           │
│  └── exec           - 快速单次命令执行                           │
│                                                                 │
│  🔍 代码分析 (5)                                                 │
│  ├── code_search    - 代码内容搜索 (Ripgrep)                    │
│  ├── file_find      - 文件查找 (Find/Glob)                      │
│  ├── ast_parse      - AST 语法树解析                            │
│  ├── dependency_map - 依赖关系分析                              │
│  └── lint_check     - 代码质量检查                              │
│                                                                 │
│  🌐 网络与 API (4)                                               │
│  ├── http_request   - HTTP 请求（GET/POST/PUT/DELETE）          │
│  ├── web_fetch      - 网页内容抓取                              │
│  ├── browser_automate - 浏览器自动化（Playwright）              │
│  └── api_test       - API 接口测试                              │
│                                                                 │
│  📦 Git 管理 (4)                                                 │
│  ├── git_status     - 查看 Git 状态                             │
│  ├── git_diff       - 查看变更差异                              │
│  ├── git_commit     - 提交变更                                  │
│  └── git_push       - 推送分支                                  │
│                                                                 │
│  🧪 测试与调试 (4)                                               │
│  ├── test_run       - 运行测试套件                              │
│  ├── debug_attach   - 调试器附加                                │
│  ├── log_analyze    - 日志分析                                  │
│  └── benchmark      - 性能基准测试                              │
│                                                                 │
│  🔧 系统工具 (5+)                                                │
│  ├── system_info    - 系统信息查询                              │
│  ├── env_check      - 环境变量检查                              │
│  ├── package_install - 包安装管理                               │
│  ├── cron_manager   - 定时任务管理                              │
│  └── skill_runner   - 技能脚本执行                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

工具清单速查表

类别	工具名	用途	是否需要外部依赖
文件操作	read_file	读取文件	否
文件操作	write_file	写入文件	否
文件操作	patch	精确编辑	否
文件操作	list_directory	列目录	否
Shell	terminal	执行命令	否
Shell	process	进程管理	否
代码分析	code_search	代码搜索	内置 ripgrep
代码分析	dependency_map	依赖分析	否
网络	http_request	HTTP 请求	否
网络	browser_automate	浏览器自动化	Playwright
Git	git_status	Git 状态	Git CLI
Git	git_commit	Git 提交	Git CLI
测试	test_run	运行测试	对应测试框架
系统	package_install	包安装	npm/pip/apt
系统	cron_manager	定时任务	系统 cron

hermes tools 命令详解

hermes tools 是管理工具集的命令行入口。通过它，你可以查询、启用、禁用工具，检查依赖，以及查看工具状态。

查看所有工具

bash

# 列出所有工具（含状态）
hermes tools list

# 输出示例：
# ═══════════════════════════════════════════════════
#  Hermes Agent 工具集状态
# ═══════════════════════════════════════════════════
#  总工具数:    32
#  已启用:      28
#  已禁用:      4
#  依赖缺失:    2
# ═══════════════════════════════════════════════════
#
#  ┌──────┬─────────────────────┬────────┬──────────┬──────────┐
#  │ 状态 │ 工具名               │ 类别    │ 依赖     │ 描述     │
#  ├──────┼─────────────────────┼────────┼──────────┼──────────┤
#  │ ✅   │ read_file           │ 文件   │ -        │ 读取文件 │
#  │ ✅   │ write_file          │ 文件   │ -        │ 写入文件 │
#  │ ✅   │ patch               │ 文件   │ -        │ 精确编辑 │
#  │ ✅   │ list_directory      │ 文件   │ -        │ 列目录   │
#  │ ✅   │ terminal            │ Shell  │ -        │ 执行命令 │
#  │ ✅   │ process             │ Shell  │ -        │ 进程管理 │
#  │ ✅   │ code_search         │ 分析   │ ripgrep  │ 代码搜索 │
#  │ ⚠️   │ browser_automate    │ 网络   │ playwright│ 浏览器  │
#  │ ✅   │ git_status          │ Git    │ git      │ Git状态  │
#  │ ❌   │ cron_manager        │ 系统   │ crontab  │ 定时任务 │
#  │ ...  │ (其余 22 个工具)     │ ...    │ ...      │ ...      │
#  └──────┴─────────────────────┴────────┴──────────┴──────────┘
#
#  状态说明: ✅ 就绪  ⚠️ 依赖缺失  ❌ 已禁用  ⏳ 加载中

按类别查看工具

bash

# 只查看某类别的工具
hermes tools list --category shell

# 输出：
# Shell 工具 (4):
# ✅ terminal       - 执行 Shell 命令
# ✅ process        - 管理后台进程
# ✅ shell_session  - 持久 Shell 会话
# ✅ exec           - 快速单次命令执行

hermes tools list --category git

# 输出：
# Git 工具 (4):
# ✅ git_status     - 查看 Git 状态
# ✅ git_diff       - 查看变更差异
# ✅ git_commit     - 提交变更
# ✅ git_push       - 推送分支

查看工具详情

bash

# 查看某个工具的详细信息
hermes tools info terminal

# 输出：
# ═══════════════════════════════════════════════════
#  工具详情: terminal
# ═══════════════════════════════════════════════════
#  名称:        terminal
#  类别:        Shell
#  状态:        ✅ 已启用
#  依赖:        无
#  沙箱:        支持 (read-only / full / restricted)
#
#  描述:
#  执行 Shell 命令并返回输出。支持前台和后台两种模式。
#  前台模式：命令执行完毕后返回结果（最长等待 timeout 秒）。
#  后台模式：启动后返回 session_id，用于后续管理。
#
#  参数:
#  ├── command      (string, required)   - 要执行的命令
#  ├── background   (boolean, default: false) - 是否后台运行
#  ├── timeout      (integer, default: 180)   - 超时秒数
#  ├── workdir      (string, optional)        - 工作目录
#  └── pty          (boolean, default: false) - 是否使用 PTY
#
#  返回:
#  ├── stdout       - 标准输出
#  ├── stderr       - 标准错误
#  ├── exit_code    - 退出码
#  └── session_id   - 后台会话 ID（仅后台模式）
#
#  使用示例:
#  terminal("ls -la", workdir="/opt/data/my-project")
#  terminal("npm run build", background=true, notify_on_complete=true)

工具启用与禁用

并非所有工具都需要常驻启用。根据任务类型动态加载工具，可以减少 Token 消耗、提高响应速度、降低误操作风险。

禁用不需要的工具

bash

# 禁用单个工具
hermes tools disable browser_automate

# 输出：
# ✅ 已禁用工具: browser_automate
#    原因: 依赖 playwright 未安装
#    提示: 运行 'hermes tools install browser_automate' 安装依赖后重新启用

# 禁用整个类别
hermes tools disable --category network

# 输出：
# ✅ 已禁用 4 个网络工具:
#    - http_request
#    - web_fetch
#    - browser_automate
#    - api_test

启用工具

bash

# 启用单个工具
hermes tools enable browser_automate

# 启用整个类别
hermes tools enable --category git

# 启用所有工具
hermes tools enable --all

查看当前启用的工具

bash

hermes tools enabled

# 输出：
# 当前已启用 28 个工具：
# read_file, write_file, patch, list_directory, file_info, file_search,
# terminal, process, shell_session, exec,
# code_search, file_find, ast_parse, dependency_map, lint_check,
# http_request, web_fetch,
# git_status, git_diff, git_commit, git_push,
# test_run, debug_attach, log_analyze, benchmark,
# system_info, env_check, package_install

配置文件中的工具管理

除了命令行，你也可以在配置文件中永久设定工具的启用状态：

yaml

# config.yaml
toolsets:
  # 默认启用所有工具
  default: enabled

  # 显式禁用的工具列表
  disabled:
    - browser_automate    # 不需要浏览器自动化
    - cron_manager        # 不需要定时任务
    - debug_attach        # 不需要调试器

  # 工具类别开关
  categories:
    shell: enabled
    file: enabled
    git: enabled
    network: restricted   # 受限模式：只允许 GET 请求
    analysis: enabled
    test: enabled
    system: enabled

  # 工具参数默认值
  defaults:
    terminal:
      timeout: 300
      sandbox: restricted
    http_request:
      max_redirects: 5
      timeout: 30
      allowed_domains:
        - "api.github.com"
        - "registry.npmjs.org"

依赖检查与自动安装

部分工具依赖外部程序或库。Hermes Agent 提供了完善的依赖检测和自动安装机制。

检查所有工具依赖

bash

# 检查所有工具的依赖状态
hermes tools check-deps

# 输出：
# ═══════════════════════════════════════════════════
#  工具依赖检查报告
# ═══════════════════════════════════════════════════
#
#  ✅ Git 工具依赖
#  ├── git              ✅ 已安装 (v2.43.0)
#  └── git commit-msg   ✅ 已配置
#
#  ✅ 代码分析依赖
#  ├── ripgrep          ✅ 已安装 (v14.1.0)
#  └── tree-sitter      ✅ 已安装
#
#  ⚠️ 浏览器自动化依赖
#  ├── playwright       ❌ 未安装
#  │   安装命令: npx playwright install --with-deps
#  │   需要空间: ~400MB
#  └── chromium         ❌ 未安装 (随 playwright 一起安装)
#
#  ⚠️ 测试工具依赖
#  ├── pytest           ❌ 未安装
#  │   安装命令: pip install pytest
#  └── jest             ✅ 已安装 (v29.7.0)
#
#  ✅ 系统工具依赖
#  ├── curl             ✅ 已安装
#  ├── jq               ✅ 已安装
#  └── crontab          ⚠️ 不可用 (当前用户无 cron 权限)
#
#  总结: 2 个依赖缺失, 1 个权限受限

自动安装依赖

bash

# 安装所有缺失的依赖
hermes tools install --all

# 安装特定工具的依赖
hermes tools install browser_automate

# 输出：
# ═══════════════════════════════════════════════════
#  正在安装 browser_automate 依赖...
# ═══════════════════════════════════════════════════
#
#  [1/2] 安装 Playwright...
#  $ npx playwright install --with-deps
#  ✓ Chromium 121.0.6167.57 已安装
#  ✓ Firefox 121.0 已安装
#  ✓ WebKit 17.4 已安装
#  ✓ 系统依赖已安装
#
#  [2/2] 验证安装...
#  ✓ Playwright 测试通过
#
#  ✅ 所有依赖安装完成！
#    工具 browser_automate 已自动启用

依赖缓存与离线模式

bash

# 查看依赖缓存
hermes tools cache status

# 输出：
# 依赖缓存: ~/.cache/hermes/tools/
# 缓存大小: 1.2GB
# ├── ripgrep        ✅ 已缓存 (v14.1.0)
# ├── tree-sitter    ✅ 已缓存 (v0.22.6)
# └── playwright     ⏳ 下载中 (78%)

# 清除缓存
hermes tools cache clean

# 离线模式：使用缓存安装
hermes tools install --offline

工具开关策略

按任务类型动态加载

Hermes Agent 支持根据任务类型自动加载相关工具集：

bash

# 启动时指定工作模式
hermes --mode coding       # 编程模式：文件 + Shell + Git + 代码分析
hermes --mode analysis     # 分析模式：代码分析 + 文件搜索
hermes --mode deploy       # 部署模式：Shell + 网络 + 系统工具
hermes --mode full         # 全工具模式

yaml

# config.yaml - 任务模式配置
toolsets:
  modes:
    coding:
      enabled_categories:
        - file
        - shell
        - git
        - analysis
      disabled_tools:
        - browser_automate
        - cron_manager

    analysis:
      enabled_categories:
        - file
        - analysis
      disabled_tools:
        - terminal
        - git_commit
        - http_request

    deploy:
      enabled_categories:
        - shell
        - network
        - system
      disabled_tools:
        - patch
        - ast_parse

    full:
      # 启用所有工具
      enabled_categories: all

最小化工具集

在资源受限的环境中，你可以使用最小化配置：

bash

# 仅启用核心工具
hermes tools minimal

# 等价于只启用 6 个核心工具：
# read_file, write_file, patch, terminal, code_search, list_directory

运行时动态切换

在 Agent 运行过程中，也可以动态调整工具：

python

# 在 Agent 会话中动态加载工具
from hermes.tools import ToolManager

# 加载特定类别
ToolManager.load_category("git")

# 临时禁用某个工具
ToolManager.disable("browser_automate", reason="当前任务不需要浏览器")

# 查看当前可用工具
available = ToolManager.list_available()
print(f"当前可用工具: {len(available)} 个")

工具执行流程与沙箱控制

工具调用流程

text

用户请求
    │
    ▼
┌──────────────┐
│  意图识别    │  Agent 理解用户需要什么
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  工具选择    │  从已启用工具中匹配
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  权限检查    │  沙箱规则 + 用户确认策略
└──────┬───────┘
       │
    ┌──┴──┐
    │需要确认?│
    └──┬──┘
  是 ↙  ↘ 否
┌──────┐  ┌──────────┐
│用户确认│  │  自动执行 │
└──┬───┘  └────┬─────┘
   │           │
   ▼           ▼
┌──────────────────┐
│   工具执行       │  沙箱环境 / 超时控制
└──────┬───────────┘
       │
       ▼
┌──────────────┐
│  结果处理    │  输出解析 + 错误重试
└──────┬───────┘
       │
       ▼
   返回给用户

沙箱控制级别

yaml

# config.yaml - 沙箱配置
toolsets:
  sandbox:
    # 默认沙箱级别
    default: restricted

    # 各工具级别的沙箱策略
    levels:
      full:
        # 完全访问：无限制
        tools: []  # 默认不设置任何工具为 full

      restricted:
        # 受限访问：限制路径和命令
        tools:
          - terminal
          - write_file
        rules:
          # 文件写入限制
          write_paths:
            - "/opt/data/**"
            - "~/projects/**"
          # 禁止的命令
          blocked_commands:
            - "rm -rf /"
            - "mkfs"
            - "dd if=/dev/zero"
            - ":(){ :|:& };:"
          # 网络限制
          blocked_ports:
            - 22
            - 23
            - 3389

      read-only:
        # 只读：不允许修改
        tools:
          - read_file
          - list_directory
          - code_search
          - file_find

自定义工具注册

除了内置工具，你还可以注册自定义工具。

通过配置文件注册

yaml

# config.yaml
toolsets:
  custom:
    - name: docker_manage
      description: "Docker 容器管理工具"
      command: "docker"
      args:
        - action: "string (start|stop|restart|logs)"
        - container: "string (容器名)"
      sandbox: restricted
      category: system

    - name: database_query
      description: "数据库查询工具"
      command: "psql"
      args:
        - query: "string (SQL 查询)"
        - database: "string (数据库名)"
      sandbox: restricted
      category: database

通过 Python 注册

python

# custom_tools.py
from hermes.tools import register_tool, Tool

@register_tool(
    name="weather_fetch",
    description="获取指定城市的天气信息",
    category="network",
)
class WeatherTool(Tool):
    def execute(self, city: str, unit: str = "celsius") -> dict:
        """获取天气数据"""
        import requests
        response = requests.get(
            f"https://api.weather.com/v1/{city}",
            params={"unit": unit}
        )
        return response.json()

    def validate(self, city: str) -> bool:
        """参数验证"""
        if not city or len(city) > 100:
            return False
        return True

注册后，在配置中加载：

yaml

toolsets:
  custom_tools:
    - custom_tools.py

自定义工具示例：项目脚手架生成器

python

from hermes.tools import register_tool, Tool
from pathlib import Path
import shutil

@register_tool(
    name="scaffold_project",
    description="从模板生成新项目脚手架",
    category="system",
)
class ScaffoldProjectTool(Tool):
    def execute(self, template: str, name: str, dest: str) -> dict:
        """
        参数:
          template: 模板名称 (fastapi, flask, django, cli)
          name: 项目名称
          dest: 目标路径
        """
        templates_dir = Path(__file__).parent / "templates"
        template_path = templates_dir / template

        if not template_path.exists():
            return {
                "error": f"模板不存在: {template}",
                "available_templates": [
                    d.name for d in templates_dir.iterdir() if d.is_dir()
                ]
            }

        dest_path = Path(dest) / name
        if dest_path.exists():
            return {"error": f"目标路径已存在: {dest_path}"}

        shutil.copytree(template_path, dest_path)

        # 替换模板变量
        for file_path in dest_path.rglob("*"):
            if file_path.is_file():
                content = file_path.read_text()
                content = content.replace("{{PROJECT_NAME}}", name)
                file_path.write_text(content)

        return {
            "status": "success",
            "project_path": str(dest_path),
            "message": f"项目 {name} 已从模板 {template} 生成"
        }

最佳实践

1. 按需启用，最小化攻击面

yaml

# 开发环境
toolsets:
  default: full

# 生产/CI 环境
toolsets:
  default: restricted
  disabled:
    - browser_automate
    - cron_manager
    - debug_attach

2. 定期清理未使用的工具依赖

bash

# 查看哪些工具的依赖安装了但工具被禁用
hermes tools check-deps --unused

# 清理未使用的依赖
hermes tools cache clean --unused

3. 工具调用日志审计

bash

# 查看工具调用历史
hermes tools log

# 输出：
# 工具调用历史 (最近 50 条):
# ┌─────┬──────────────────┬──────────┬───────────┬───────┐
# │ 时间 │ 工具名            │ 参数摘要   │ 耗时      │ 状态  │
# ├─────┼──────────────────┼──────────┼───────────┼───────┤
# │14:32│ read_file        │ path:... │ 0.02s     │ ✅    │
# │14:32│ terminal         │ npm i... │ 12.5s     │ ✅    │
# │14:33│ patch            │ path:... │ 0.01s     │ ✅    │
# │14:33│ git_commit       │ msg:...  │ 0.8s      │ ✅    │
# │14:34│ browser_automate │ url:...  │ -         │ ❌跳过 │
# └─────┴──────────────────┴──────────┴───────────┴───────┘

4. 工具组合使用模式

bash

# 典型代码修改流程
1. read_file          → 读取目标文件
2. patch              → 精确修改代码
3. lint_check         → 检查代码质量
4. test_run           → 运行相关测试
5. git_diff           → 查看变更
6. git_commit         → 提交变更

# 典型部署流程
1. terminal           → 构建项目
2. terminal           → 运行测试
3. system_info        → 检查系统状态
4. http_request       → 调用部署 API
5. log_analyze        → 检查部署日志

总结

本文全面介绍了 Hermes Agent 的工具集体系：

30+ 内置工具：覆盖文件操作、Shell 执行、代码分析、网络请求、Git 管理、测试调试、系统工具七大类别
hermes tools 命令：list/info/enable/disable/check-deps/install，一站式工具管理
工具开关策略：按任务类型动态加载（coding/analysis/deploy/full），减少 Token 消耗
依赖检查与安装：自动检测外部依赖（Git/ripgrep/Playwright/pytest），一键安装
沙箱控制：full/restricted/read-only 三级权限，保障安全
自定义工具注册：通过配置文件或 Python 代码扩展工具能力
工具调用审计：完整的调用日志和性能追踪

核心原则：

最小化工具集：每次任务只加载需要的工具，降低 Token 成本和误操作风险
依赖可管理：清晰了解每个工具的外部依赖，按需安装
沙箱必开启：任何可写可执行的工具都应该有沙箱保护
审计不能少：保留工具调用日志，便于回溯和调试

📌 下篇预告

Skills 技能系统 —— 安装、搜索、管理 Skills，Hub 技能与本地技能，平台级技能启用。当掌握了工具集后，如何让 Agent 具备更高级的"专业技能"？下一篇将深入 Hermes Agent 的 Skills 系统，学习如何让 Agent 从通用助手变成领域专家。