第10篇：内置插件——开箱即用的增强包

嘿，朋友们！今天咱们聊点轻松的——内置插件。你可能已经发现了，Hermes Agent 自带了不少好东西，不用额外装啥，开箱即用。这篇就把最实用的几个给你捋一捋，尤其是那个能让你“后悔药自由”的 Checkpoints / /rollback。

先说说 Checkpoints 是啥

简单讲，就是 Hermes 会在一些“危险操作”之前，自动给你的项目拍一张快照。万一 AI 改坏了，你一句 /rollback 就能回到操作之前的状态，像游戏存档一样。

不过注意，这功能在 v2 里是默认关闭的，得手动开。为啥？因为快照存多了也占地方，不是所有人都需要。

开启方式有两种：

临时开启（当前会话）：

hermes chat --checkpoints

永久开启（改配置文件 ~/.hermes/config.yaml）：

checkpoints:
  enabled: true

什么时候会自动拍快照？

主要在两类操作前：

文件工具：比如 write_file、patch
危险终端命令：rm、mv、sed -i、git reset 这类会改东西的命令

而且 Hermes 很聪明，每个目录每轮对话最多拍一次，不会疯狂刷屏。

怎么用？超简单

在会话里直接敲：

命令	作用
`/rollback`	列出所有快照
`/rollback 3`	恢复到第 3 个快照（保留你手动改的东西）
`/rollback 3 --all`	完全恢复，连你手改的也覆盖
`/rollback diff 3`	看看当前和第 3 个快照差了多少
`/rollback 3 config.py`	只恢复某个文件

快照存在哪？

放心，不会动你项目的 .git。Hermes 把所有快照都放在一个共享的隐藏仓库里：

~/.hermes/checkpoints/store/

所有项目共用这一个仓库，靠 git 的去重机制，省空间又高效。

命令行管理工具

不想进会话？直接在终端操作：

hermes checkpoints            # 查看总大小、项目数
hermes checkpoints prune      # 手动清理过期/孤儿快照
hermes checkpoints clear      # 全部清空（会先问你）

配置项一览

在 config.yaml 里可以精细控制：

checkpoints:
  enabled: false          # 总开关
  max_snapshots: 20       # 每个项目最多 20 个快照
  max_total_size_mb: 500  # 总大小上限 500MB
  max_file_size_mb: 10    # 超过 10MB 的文件不拍
  auto_prune: true        # 自动清理旧快照
  retention_days: 7       # 保留 7 天

顺带一提：其他内置插件

除了 Checkpoints，仓库里还打包了几个插件，比如 disk-cleanup（自动清理临时文件）、security-guidance（写文件时给危险代码模式加安全警告）等等。它们默认都是关着的，想用就 hermes plugins enable <名字> 开一下，或者去 hermes plugins 界面里勾选。

注意：observability/langfuse 和 spotify 已经不在内置插件列表里了，详见下文。

想接 Langfuse？它已经搬到插件目录了

Langfuse 追踪不再随 Hermes 内置，而是作为官方 langfuse 目录插件发布，hooks、HERMES_LANGFUSE_* 环境变量和采集模式都和以前一样：

hermes plugins install langfuse

之前启用过 observability/langfuse 的 profile，hermes update（或更新后首次启动）会自动帮你装好并启用该插件，继续上报到同一个 Langfuse 项目。安装、调优和采集模式的细节见插件 README。

NeMo Relay 现在怎么配？

NeMo Relay 已经不再是内置插件了，别再去 enable 它。Hermes 核心现在自己接管了 Relay 的会话和工具生命周期，想接中间件或导出器的话，得自己写一个标准的 Relay plugins.toml。

Hermes 会先加载 Relay 的用户配置 ~/.config/nemo-relay/plugins.toml，再加载机器级的系统配置 /etc/nemo-relay/plugins.toml（Windows 上是 %ProgramData%\nemo-relay\plugins.toml）。系统配置优先级更高。只有在你想用一个明确的文件替换掉用户配置时，才需要在启动 Hermes 前设置 HERMES_NEMO_RELAY_PLUGINS_TOML——注意系统配置依然会覆盖它。这个策略对该 Hermes 进程托管的所有 profile 都生效。

想知道到底哪些文件生效了？跑一下 hermes doctor 就能看到。ATOF、ATIF、OpenTelemetry 这些选项的细节，可以看 NeMo Relay observability configuration。

另外提醒一句：老的 HERMES_NEMO_RELAY_ATOF_* 和 HERMES_NEMO_RELAY_ATIF_* 变量已经不再配置导出器了。当 HERMES_NEMO_RELAY_PLUGINS_TOML 没设置时，网关会警告你还留着这些旧变量，hermes doctor 也会把它们报出来。不过别担心，独立发现的 Relay 用户级或系统级导出器依然照常生效。

现在 hermes update（或者 hermes migrate relay，想覆盖所有 profile home 就用 hermes migrate relay --all-profiles）会自动帮你迁移：把旧变量转成 <hermes home>/relay-plugins.toml，在该 profile 的 .env 里设好 HERMES_NEMO_RELAY_PLUGINS_TOML，并把旧变量那几行注释掉（不删）。多路复用网关下，每个 profile home 都会拿到自己的文件。生成的文件在写入前会先过一遍 Relay 校验，产出的形状大致是这样（注意 sink 的 type = "file" 判别字段——少了它会被拒）：

version = 1

[[components]]
kind = "observability"
enabled = true

[components.config]
version = 4
enable_full_payloads = false

[components.config.atof]
enabled = true

[[components.config.atof.sinks]]
type = "file"
output_directory = "/home/you/.hermes/telemetry/nemo-relay/atof"
filename = "hermes-atof.jsonl"
mode = "append"

[components.config.atif]
enabled = true
agent_name = "Hermes Agent"
model_name = "unknown"
output_directory = "/home/you/.hermes/telemetry/nemo-relay/atif"
filename_template = "trajectory-{session_id}.json"

[components.config.opentelemetry]
enabled = false
endpoints = []

[components.config.policy]
unknown_component = "warn"
unknown_field = "warn"
unsupported_value = "error"

然后把 HERMES_NEMO_RELAY_PLUGINS_TOML=/home/you/.hermes/relay-plugins.toml 加进 .env，重启网关即可。

长会话的 span 分段

Relay 是在 scope 关闭时才导出 span 的。一个持续运行的网关会话可能好几天都不关，session span 就一直挂着，虽然每轮的 turn span 照常导出。可选的 segmentation 只在轮次边界上轮换 session scope：

gateway:
  telemetry:
    session_segments:
      on_compaction: false  # 上下文压缩后轮换
      max_turns: 0          # 0 = 不限；N = 每 N 轮轮换一次

键	默认值	行为
`on_compaction`	`false`	压缩完成后，在下一个轮次边界轮换。
`max_turns`	`0`	每完成 N 轮就轮换；`0` 表示不设上限。

两个默认值都会让整个会话保持同一个 session scope。轮换后的 span 保留相同的 session_id，并额外带上 hermes.session.segment 和 hermes.session.segment_reason（compaction 或 max_turns）。

小结

Checkpoints 就是个安全网，让你敢让 AI 放手去改代码。虽然默认关着，但强烈建议你开起来——万一哪次 AI 手滑，你还能一键回到过去。

下篇咱们聊聊别的内置插件，敬请期待！