跳到主要内容

内置插件

Hermes 随代码库附带了一小组插件。它们位于 <repo>/plugins/<name>/ 目录下，并与 ~/.hermes/plugins/ 中用户安装的插件一起自动加载。它们使用与第三方插件相同的插件接口——钩子（hooks）、工具、斜杠命令——只是在代码库内部进行维护。

有关通用插件系统的信息，请参阅 插件 页面；若要编写自己的插件，请参阅 构建 Hermes 插件。

发现机制的工作原理​

PluginManager 按顺序扫描四个来源：

  1. 内置 — <repo>/plugins/<name>/（本页文档所述）
  2. 用户 — ~/.hermes/plugins/<name>/
  3. 项目 — ./.hermes/plugins/<name>/（需要设置 HERMES_ENABLE_PROJECT_PLUGINS=1）
  4. Pip 入口点 — hermes_agent.plugins

当名称冲突时，后发现的来源优先——例如，名为 disk-cleanup 的用户插件将替换内置版本。

plugins/memory/ 和 plugins/context_engine/ 被刻意排除在内置扫描之外。这些目录使用各自的发现路径，因为内存提供者（memory providers）和上下文引擎（context engines）是通过配置中的 hermes memory setup / context.engine 配置的单选提供者。

内置插件需手动启用​

内置插件默认处于禁用状态。发现机制可以找到它们（它们会出现在 hermes plugins list 和交互式 hermes plugins UI 中），但在你明确启用之前，没有任何插件会被加载：

hermes plugins enable disk-cleanup

或者通过 ~/.hermes/config.yaml 配置：

plugins:
  enabled:
    - disk-cleanup

这与用户安装插件使用的机制相同。内置插件永远不会自动启用——无论是全新安装，还是现有用户升级到较新版本的 Hermes。你始终需要显式选择启用。

若要再次禁用内置插件：

hermes plugins disable disk-cleanup
# or: remove it from plugins.enabled in config.yaml

当前发布的插件​

disk-cleanup​

自动跟踪并删除会话期间创建的临时文件——测试脚本、临时输出、cron 日志、过期的 Chrome 配置文件——无需代理记住调用工具。

工作原理：

钩子行为
post_tool_call当 write_file / terminal / patch 在 HERMES_HOME 或 /tmp/hermes-* 内创建匹配 test_*、tmp_* 或 *.test.* 的文件时，将其静默跟踪为 test / temp / cron-output。
on_session_end如果在本轮对话中自动跟踪了任何测试文件，则运行安全的 quick 清理并记录一行摘要。否则保持静默。

删除规则：

类别阈值确认要求
test每次会话结束从不
temp自跟踪起超过 7 天从不
cron-output自跟踪起超过 14 天从不
HERMES_HOME 下的空目录始终从不
research超过 30 天，且超出最新的 10 个文件始终（仅深度清理）
chrome-profile自跟踪起超过 14 天始终（仅深度清理）
大于 500 MB 的文件从不自动清理始终（仅深度清理）

斜杠命令 — /disk-cleanup 在 CLI 和网关会话中均可用：

/disk-cleanup status                     # breakdown + top-10 largest
/disk-cleanup dry-run                    # preview without deleting
/disk-cleanup quick                      # run safe cleanup now
/disk-cleanup deep                       # quick + list items needing confirmation
/disk-cleanup track <path> <category>    # manual tracking
/disk-cleanup forget <path>              # stop tracking (does not delete)

状态 — 所有内容均位于 $HERMES_HOME/disk-cleanup/：

文件内容
tracked.json被跟踪的路径，包含类别、大小和时间戳
tracked.json.bak上述文件的原子写入备份
cleanup.log追加模式的审计日志，记录每次跟踪/跳过/拒绝/删除操作

安全性 — 清理操作仅触及 HERMES_HOME 或 /tmp/hermes-* 下的路径。Windows 挂载点（/mnt/c/...）会被拒绝。知名的顶层状态目录（logs/、memories/、sessions/、cron/、cache/、skills/、plugins/、disk-cleanup/ 本身）即使为空也不会被删除——因此全新安装在第一次会话结束时不会被清空。

启用： hermes plugins enable disk-cleanup（或在 hermes plugins 中勾选复选框）。

再次禁用： hermes plugins disable disk-cleanup。

添加内置插件​

内置插件的编写方式与任何其他 Hermes 插件完全相同——参见 构建 Hermes 插件。唯一区别在于：

  • 目录位于 <repo>/plugins/<name>/ 而非 ~/.hermes/plugins/<name>/
  • 在 hermes plugins list 中，清单来源显示为 bundled
  • 同名的用户插件会覆盖内置版本

适合打包为内置插件的条件包括：

  • 没有可选依赖项（或其依赖项已包含在 pip install .[all] 中）
  • 其行为惠及大多数用户，且默认启用（opt-out）而非默认禁用（opt-in）
  • 其逻辑融入了生命周期钩子，否则代理必须记住手动调用
  • 它补充了核心功能，而未扩大模型可见的工具表面

反面示例——应保留为用户可安装插件而非内置插件的情况：需要 API 密钥的第三方集成、小众工作流、庞大的依赖树、任何会显著改变代理默认行为的内容。