内置插件

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

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

发现机制的工作原理

PluginManager 会按顺序扫描以下四个来源：

1. 内置 (Bundled) —— <repo>/plugins/<name>/（本页记录的内容）
2. 用户 (User) —— ~/.hermes/plugins/<name>/
3. 项目 (Project) —— ./.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
# 或者：从 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 —— 包含任务、评论、扇出（Fan-out）、看板切换。参见 “看板多代理”。

记忆提供商 (plugins/memory/*) 和上下文引擎 (plugins/context_engine/*) 在 “记忆提供商” 页面单独列出 —— 它们分别通过 hermes memory 和 hermes plugins 进行管理。以下是两个基于钩子的长期运行插件的详细信息。

disk-cleanup

自动跟踪并移除会话期间创建的临时文件 —— 如测试脚本、临时输出、定时任务日志、过期的 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 —— 查看明细 + 前 10 个最大的文件
/disk-cleanup dry-run —— 预览而不实际删除
/disk-cleanup quick —— 立即运行安全清理
/disk-cleanup deep —— 运行快速清理 + 列出需要确认的项目
/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），每一次工具调用生成一个工具观测记录。使用总量、各类型 Token 计数及成本估算均来自 Hermes 权威的 agent.usage_pricing 数据，因此 Langfuse 仪表盘看到的细分数据（输入 / 输出 / cache_read_input_tokens / cache_creation_input_tokens / reasoning_tokens）与 hermes logs 中显示的一致。

该插件采用 故障开放（Fail-open） 策略：如果没有安装 SDK、没有凭据或出现瞬时 Langfuse 错误，钩子（Hook）将静默地不执行任何操作，代理循环（Agent loop）绝不会受到影响。

设置：

pip install langfuse
hermes plugins enable observability/langfuse

或者在交互式的 hermes plugins UI 中勾选该复选框。然后将凭据放入 ~/.hermes/.env 文件中：

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

工作原理：

钩子名称	行为
pre_api_request / pre_llm_call	开启（或复用）一个名为 “Hermes turn” 的每轮对话根跨度。为此 API 调用启动一个 “生成” 子观测记录，并将序列化的近期消息作为输入。
post_api_request / post_llm_call	关闭生成记录，附加 usage_details、cost_details、finish_reason、助手输出及工具调用信息。如果没有工具调用且内容不为空，则关闭该对话轮次。
pre_tool_call	启动一个 “工具” 子观测记录，包含脱敏后的参数（args）。
post_tool_call	关闭工具观测记录，包含脱敏后的结果（result）。read_file 的负载会被摘要化（显示头部+尾部+省略行数），以确保大文件读取内容保持在 HERMES_LANGFUSE_MAX_CHARS 限制之下。

会话分组通过 langfuse.propagate_attributes 关联 Hermes 会话 ID（或子代理的任务 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

允许代理 加入、转录并参与 Google Meet 会议 —— 记录会议笔记、在结束后总结互动内容、跟进特定要点，并（可选地）通过 TTS（语音合成）将回复说回会议中。

功能点：

• 通过浏览器自动化技术，以无头虚拟参与者的身份加入 Meet 链接。
• 通过配置的 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 会话历史生成的。成就涵盖了工具链壮举、调试模式、氛围编码（vibe-coding）连胜、技能/记忆使用情况、模型/提供商多样性，以及生活方式怪癖（周末和深夜会话）。该插件最初由 @PCinkusz 作为外部插件开发，现已并入内置代码库，以便与 Hermes 的功能变更保持同步。

工作原理：

• 在仪表盘后端扫描您整个 ~/.hermes/state.db 会话历史。
• 每条会话的统计数据通过 (started_at, last_active) 指纹进行缓存，因此在后续扫描中，只有新增或变动的会话会重新分析。
• 首次扫描在后台线程运行 —— 即使数据库中有数千个会话，仪表盘也绝不会阻塞等待。
• 解锁状态持久化存储在 $HERMES_HOME/plugins/hermes-achievements/state.json 中。

等级晋升：青铜 → 白银 → 黄金 → 钻石 → 奥林匹亚。每张卡片都有一个 “达成条件” 部分，列出了正在追踪的具体指标。

成就状态：

状态	含义
已解锁 (Unlocked)	至少达成了一个等级
已发现 (Discovered)	已知成就，进度可见，但尚未获得
隐藏成就 (Secret)	保持隐藏，直到 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 时，清单来源（Manifest source）将被报告为 bundled。
• 同名的用户插件会覆盖内置版本。

当插件满足以下条件时，它是并入内置插件（Bundling）的理想选择：

• 没有可选依赖项（或者其依赖项已包含在 pip install .[all] 中）。
• 其功能能让大多数用户受益，且倾向于“由用户选择关闭”而非“由用户选择开启”。
• 其逻辑与生命周期钩子（Lifecycle hooks）深度绑定，否则代理程序必须记住手动调用这些功能。
• 它对核心能力起到补充作用，且不会显著扩大模型可见的工具集（Tool surface）。

反面案例 —— 以下内容应作为用户自行安装的插件，而不应内置：需要 API 密钥的第三方集成、小众工作流、庞大的依赖树，以及任何默认情况下会显著改变代理行为的功能。