内置插件

Hermes 附带一组预装的插件，这些插件位于仓库内的 <repo>/plugins/<name>/ 目录中，并会与用户安装的插件（位于 ~/.hermes/plugins/）一同自动加载。它们使用与第三方插件相同的插件接口——钩子、工具、斜杠命令等，只是由项目团队直接维护。

有关插件系统的通用信息，请参阅 Plugins 页面；如需编写自己的插件，请参考 构建 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/ 被有意排除在内置插件扫描之外。这两个目录使用独立的发现路径，因为内存提供者和上下文引擎是单选型组件，通过配置文件中的 hermes memory setup / context.engine 进行设置。

内置插件为可选启用

内置插件默认处于禁用状态。虽然发现机制能识别它们（它们会在 hermes plugins list 列表中显示，并出现在交互式 hermes plugins UI 中），但只有在你明确启用后才会加载：

```bash
hermes plugins enable disk-cleanup

或通过 ``~/.hermes/config.yaml`` 命令：

```bash
```yaml
plugins:
  enabled:
    - disk-cleanup

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

若要再次关闭某个内置插件：

```bash
```bash
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 和网关会话中均可用：

```bash
/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>/
• 插件清单中的来源报告为 bundled，可在 hermes plugins list 中查看
• 若用户插件与内置插件同名，则用户版本将覆盖内置版本

适合打包进内置插件的插件应满足以下条件：

• 无可选依赖（或其依赖已作为 pip install .[all] 的依赖存在）
• 功能对大多数用户有益，且为“可关闭”而非“可开启”
• 逻辑与生命周期钩子紧密绑定，避免代理必须手动调用
• 补充核心能力，但不增加模型可见的工具表面

反例——不应内置而应保持为用户可安装的插件包括：需要 API 密钥的第三方集成、小众工作流、大型依赖树、任何会显著改变代理默认行为的功能。