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 中），但只有在你明确启用后才会加载：

hermes plugins enable disk-cleanup

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

plugins:
  enabled:
    - disk-cleanup

这与用户安装的插件使用的机制相同。捆绑插件永远不会自动启用——无论是全新安装，还是现有用户升级到较新版本的 Hermes。你总是需要明确选择加入。

要再次关闭捆绑插件：

hermes plugins disable disk-cleanup
## 或者：从 config.yaml 的 plugins.enabled 中移除它

当前提供的插件

仓库在 plugins/ 下提供了以下捆绑插件。所有插件都是选择加入的——通过 hermes plugins enable <name> 启用。

内存提供者（plugins/memory/*）和上下文引擎（plugins/context_engine/*）分别在 内存提供者 中列出——它们分别通过 hermes memory 和 hermes plugins 管理。以下是对两个基于 hooks 的长期运行插件的详细说明。

disk-cleanup

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

工作原理：

删除规则：

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

/disk-cleanup status                     # 细分 + 前 10 大文件
/disk-cleanup dry-run                    # 预览而不删除
/disk-cleanup quick                      # 立即运行安全清理
/disk-cleanup deep                       # quick + 列出需要确认的项目
/disk-cleanup track <path> <category>    # 手动跟踪
/disk-cleanup forget <path>              # 停止跟踪（不删除）

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

安全性 — 清理仅触及 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。

security-guidance

对文件写入进行快速模式匹配的安全警告。当智能体的 write_file / patch / skill_manage 调用包含匹配已知危险代码模式的内容时——pickle.load、yaml.load 未使用 SafeLoader、eval(、os.system、subprocess(..., shell=True)、JS child_process.exec、React dangerouslySetInnerHTML、原始 .innerHTML = / .outerHTML = / document.write、Node crypto.createCipher、AES ECB 模式、TLS 验证禁用、易受 XXE 攻击的 xml.etree / minidom 解析器、<script src="//..." > 未使用 SRI、torch.load 未使用 weights_only=True、GitHub Actions ${{ github.event.* }} 注入——该插件会在工具结果后附加一个 ⚠️ 安全指导 块。

文件仍然会被写入。模型会在下一轮的工具消息中读取警告，并可以修复代码或说明为什么该构造在此上下文中是安全的。模式匹配存在一定的误报率，因此默认是警告（而非阻止）。

覆盖范围： 共 25 条规则，涵盖不安全的反序列化、命令注入、XSS 接收器、加密陷阱、XXE、供应链（SRI）和 CI/CD 工作流注入。模式数据是 Anthropic 的 claude-plugins-official 的逐字 Apache-2.0 分支——请参阅插件的 LICENSE 和 NOTICE 文件以获取归属信息。

模式：

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

再次禁用： hermes plugins disable security-guidance。

它目前不做什么： 上游 Anthropic 插件还有两层——一个在每次智能体轮次（涉及文件修改）时进行的 LLM diff 审查，以及一个在提交时进行的智能体审查，用于追踪跨文件的数据流。两者均未移植。智能体已经可以通过 delegate_task 按需运行这些审查。

observability/langfuse

将 Hermes 的对话轮次、LLM 调用和工具调用追踪到 Langfuse——一个开源的 LLM 可观测性平台。每个对话轮次一个 span，每个 API 调用一个 generation，每个工具调用一个 tool observation。使用量总计、按类型划分的 token 计数和成本估算来自 Hermes 的规范 agent.usage_pricing 数字，因此 Langfuse 仪表盘会看到与 hermes logs 中相同的细分（输入/输出/cache_read_input_tokens/cache_creation_input_tokens/reasoning_tokens）。

该插件是故障开放的：未安装 SDK、缺少凭据或 Langfuse 临时错误——所有这些都会在 hook 中静默地变为无操作。智能体循环永远不会受到影响。

设置（交互式——推荐）：

hermes tools          # → Langfuse Observability → Cloud 或 Self-Hosted

向导会收集你的密钥，pip install 安装 langfuse SDK，并将 observability/langfuse 添加到 plugins.enabled 中。重启 Hermes，下一轮就会发送一个 trace。

设置（手动）：

pip install langfuse
hermes plugins enable observability/langfuse

然后将凭据放入 ~/.hermes/.env：

HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com   # 或你的自托管 URL

工作原理：

会话分组基于 Hermes 会话 ID（或子智能体的任务 ID），通过 langfuse.propagate_attributes 实现，因此单个 hermes chat 会话中的所有内容都位于一个 Langfuse 会话下。

验证：

hermes plugins list                 # observability/langfuse 应显示 "enabled"
hermes chat -q "hello"              # 在 Langfuse UI 中检查 "Hermes turn" trace

可选调优（在 .env 中）：

Hermes 前缀和标准 SDK 环境变量（LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASE_URL）均被接受——当两者都设置时，Hermes 前缀的变量优先。

性能： Langfuse 客户端在第一次 hook 调用后被缓存。如果凭据或 SDK 缺失，该决定也会被缓存——后续的 hook 会快速返回，无需重新检查环境变量或重新加载配置。

禁用： hermes plugins disable observability/langfuse。插件模块仍会被发现，但直到你重新启用之前，不会运行任何模块代码。

google_meet

让智能体加入、转录和参与 Google Meet 通话——为会议做笔记，之后总结对话，跟进特定要点，并（可选地）通过 TTS 将回复说回通话中。

它增加了什么：

• 一个无头的虚拟参与者，使用浏览器自动化加入 Meet URL
• 通过配置的 STT 提供者对会议音频进行实时转录
• 智能体调用的 meet_summarize / meet_speak / meet_followup 工具集，用于对其听到的内容采取行动
• 会后产物（转录、按发言者归类的笔记、行动项）保存在 ~/.hermes/cache/google_meet/<meeting_id>/ 下

设置：

hermes plugins enable google_meet
## 首次使用时，会提示你通过插件的 OAuth 流程登录——
## 需要一个具有 Meet 访问权限的 Google 帐户。如果会议强制要求“仅限受邀参与者加入”，则可能需要主持人批准。

从聊天中使用：

"加入 meet.google.com/abc-defg-hij 并做笔记。通话结束后，给我一份包含行动项的摘要。"

智能体会启动会议加入，在通话进行时将转录流式传输回其上下文，并在会议结束时（或当你告诉它停止时）生成结构化摘要。

何时使用： 定期站会，你希望机器人转录并为异步参与者总结；面试场景，你希望结构化笔记；任何你原本需要 Fireflies / Otter / Grain 的情况。当你不想让 AI 监听时——不要启用它。

禁用： hermes plugins disable google_meet。任何缓存的转录和录音会保留在 ~/.hermes/cache/google_meet/ 中，直到你手动删除。

hermes-achievements

在仪表盘中添加一个Steam 风格的成就标签——60 多个可收集、分级的徽章，基于你真实的 Hermes 会话历史生成。工具链壮举、调试模式、编程冲刺、技能/内存使用、模型/提供者多样性、生活方式怪癖（周末和夜间会话）。最初由 @PCinkusz 作为外部插件编写；现在纳入树内，以便与 Hermes 功能变更保持同步。

工作原理：

• 在仪表盘后端扫描你整个 ~/.hermes/state.db 会话历史
• 每个会话的统计信息通过 (started_at, last_active) 指纹缓存，因此后续扫描只重新分析新的或已更改的会话
• 首次扫描在后台线程中运行——仪表盘永远不会等待它，即使数据库中有数千个会话
• 解锁状态持久化到 $HERMES_HOME/plugins/hermes-achievements/state.json

等级 progression： 铜 → 银 → 金 → 钻石 → 奥林匹亚。每个卡片都显示一个“计数内容”部分，列出正在跟踪的具体指标。

成就状态：

API — 路由挂载在 /api/plugins/hermes-achievements/ 下：

状态文件 — 位于 $HERMES_HOME/plugins/hermes-achievements/ 下：

性能说明：

• 对约 8,000 个会话的冷扫描需要几分钟。它在第一个仪表盘请求时在后台线程中运行；UI 会看到一个待定占位符并轮询 /scan-status。
• 冷扫描期间的增量结果 — 扫描器每约 250 个会话发布一个部分快照，因此每次仪表盘刷新都会显示更多已解锁的徽章。不会出现长时间盯着零的情况。
• 热重新扫描会重用每个会话的统计信息，只要该会话的 started_at + last_active 指纹与检查点匹配——即使历史记录很大，也能在几秒钟内完成。
• 内存快照的 TTL 为 120 秒；过期的请求会立即提供旧快照并触发后台刷新。你永远不会因为 TTL 过期而等待旋转器。

启用： 无需启用——hermes-achievements 是一个仅限仪表盘的插件（没有生命周期钩子，没有模型可见的工具）。它在首次启动时自动注册为 hermes dashboard 中的一个标签。plugins.enabled 配置仅控制生命周期/工具插件；仪表盘插件仅通过其 dashboard/manifest.json 被发现。

选择退出： 删除或重命名 plugins/hermes-achievements/dashboard/manifest.json，或者用 ~/.hermes/plugins/hermes-achievements/ 中一个同名的用户插件覆盖它，该插件不提供仪表盘。插件的状态文件（位于 $HERMES_HOME/plugins/hermes-achievements/ 下）会保留——重新安装会保留你的解锁历史。

添加一个捆绑插件

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

• 目录位于 <repo>/plugins/<name>/ 而不是 ~/.hermes/plugins/<name>/
• 清单源在 hermes plugins list 中报告为 bundled
• 同名的用户插件会覆盖捆绑版本

当满足以下条件时，插件适合捆绑：

• 它没有可选依赖项（或者它们已经是 pip install .[all] 的依赖项）
• 该行为对大多数用户有益，并且是选择退出而非选择加入
• 逻辑与生命周期钩子相关联，否则智能体必须记住调用这些钩子
• 它补充了核心功能，而不会扩展模型可见的工具表面

反例——应保持为用户可安装插件而非捆绑的内容：需要 API 密钥的第三方集成、小众工作流、大型依赖树、任何会显著改变智能体默认行为的内容。