内置插件（Built-in Plugins）

Hermes 随附了一小批与代码仓库捆绑在一起的插件（Plugin）。它们位于 <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）提供商和上下文引擎是通过 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> 启用它们。

插件	类型	用途
disk-cleanup	钩子 + 斜杠命令	自动跟踪临时文件并在会话结束时清理
observability/langfuse	钩子	将轮次/LLM 调用/工具追踪到 Langfuse
spotify	后端（7 个工具）	原生 Spotify 播放控制、队列、搜索、播放列表、专辑、媒体库
google_meet	独立	加入 Meet 通话、实时字幕转录、可选实时双向音频
image_gen/openai	图像后端	OpenAI gpt-image-2 图像生成后端（FAL 的替代方案）
image_gen/openai-codex	图像后端	通过 Codex OAuth 的 OpenAI 图像生成
image_gen/xai	图像后端	xAI grok-2-image 后端
hermes-achievements	仪表盘标签页	根据你真实的 Hermes 会话历史生成的类 Steam 可收藏徽章
kanban/dashboard	仪表盘标签页	多智能体调度器的看板 UI —— 任务、评论、扇出、看板切换。参见看板多智能体。

记忆（Memory）提供商（plugins/memory/*）和上下文引擎（plugins/context_engine/*）单独列在记忆提供商上——它们分别通过 hermes memory 和 hermes plugins 管理。下面是两个基于钩子的长运行插件的详细说明。

disk-cleanup

自动跟踪和删除会话期间创建的临时文件——测试脚本、临时输出、定时任务日志、过期的 Chrome 配置文件——无需 Agent 记得调用工具。

工作原理：

钩子（Hook）	行为
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 的文件	从不自动	始终（仅深度模式）

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

/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/：

文件	内容
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。

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 暂时性错误——所有这些都变成钩子中的静默空操作。Agent 循环不受影响。

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

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

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

设置（手动）：

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

工作原理：

钩子（Hook）	行为
pre_api_request / pre_llm_call	打开（或复用）每轮次的根 span "Hermes turn"。为此 API 调用启动一个 generation 子 observation，将最近的序列化消息作为输入。
post_api_request / post_llm_call	关闭 generation，附加 usage_details、cost_details、finish_reason、助手输出 + 工具调用。如果没有工具调用且有非空内容，关闭轮次。
pre_tool_call	启动带有经过清理的 args 的 tool 子 observation。
post_tool_call	用经过清理的 result 关闭工具 observation。read_file 有效负载会被摘要（头部 + 尾部 + 省略行计数），使大文件读取保持在 HERMES_LANGFUSE_MAX_CHARS 以内。

会话分组通过 langfuse.propagate_attributes 使用 Hermes 会话 ID（或子 Agent 的任务 ID），因此单个 hermes chat 会话中的所有内容都在一个 Langfuse 会话下。

验证：

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

可选调优（在 .env 中）：

变量	默认值	用途
HERMES_LANGFUSE_ENV	—	追踪上的环境标签（production、staging 等）
HERMES_LANGFUSE_RELEASE	—	发布/版本标签
HERMES_LANGFUSE_SAMPLE_RATE	1.0	传递给 SDK 的采样率（0.0–1.0）
HERMES_LANGFUSE_MAX_CHARS	12000	消息内容/工具参数/工具结果的每字段截断
HERMES_LANGFUSE_DEBUG	false	详细插件日志到 agent.log

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

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

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

google_meet

让 Agent 加入、转录和参与 Google Meet 通话——记录会议笔记、之后总结来回讨论、跟进特定要点，以及（可选）通过 TTS 将回复朗读到通话中。

添加的功能：

• 通过浏览器自动化加入 Meet URL 的无头虚拟参与者
• 通过配置的 STT 提供商实时转录会议音频
• Agent 用于根据所听内容采取行动的 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 并记笔记。通话结束后，给我发一份带行动项目的摘要。"

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

适用场景： 你想要机器人转录 + 为异步参与者总结的定期站会；需要结构化笔记的访谈；任何你本来需要 Fireflies / Otter / Grain 的情况。如果你不想让 AI 参与监听——不要启用它。

禁用： hermes plugins disable google_meet。任何缓存的转录和录音都留在 ~/.hermes/cache/google_meet/ 直到你删除它们。

hermes-achievements

在仪表盘中添加类 Steam 成就标签页——根据你真实的 Hermes 会话历史生成的 60+ 可收藏、分级徽章。工具链壮举、调试模式、vibe-coding 连胜、技能/记忆使用、模型/提供商多样性、生活方式怪癖（周末和夜晚会话）。最初由 @PCinkusz 作为外部插件创作；被纳入代码仓库以与 Hermes 功能变化保持同步。

工作原理：

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

等级进阶： 铜 → 银 → 金 → 钻石 → 奥林匹克。每张卡片都有"计算内容"部分，列出被跟踪的确切指标。

成就状态：

状态	含义
已解锁	至少达到一个等级
已发现	已知成就，进度可见，尚未获得
秘密	隐藏，直到 Hermes 在你的历史中检测到第一个相关信号

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

端点	用途
GET /achievements	包含每个徽章解锁状态的完整目录（第一次冷扫描运行时返回待处理占位符）
GET /scan-status	后台扫描仪的状态：idle / running / failed，最后持续时间，运行次数
GET /recent-unlocks	最近解锁的 20 个徽章，最新的在前
GET /sessions/{id}/badges	主要在一个特定会话中获得的徽章
POST /rescan	手动同步重新扫描（阻塞；当用户点击重新扫描按钮时使用）
POST /reset-state	清除解锁历史和缓存快照

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

文件	内容
state.json	解锁历史：你获得了哪些徽章以及何时获得。跨 Hermes 更新稳定。
scan_snapshot.json	最后完成的扫描有效负载（仪表盘加载时立即提供）
scan_checkpoint.json	按指纹键入的每会话统计缓存（使温暖重新扫描快速）

性能说明：

• 约 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] 依赖）
• 该行为对大多数用户有益，是可选退出而非可选启用
• 逻辑融入了 Agent 否则需要记住调用的生命周期钩子
• 补充核心能力而不扩展模型可见工具接口

反例——应该作为用户可安装插件而非捆绑的内容：带有 API 密钥的第三方集成、小众工作流、大型依赖树、任何会默认改变 Agent 行为的内容。