用 Litefuse 追踪 Hermes Agent

Hermes Agent 是 Nous Research 的终端 AI 助手，采用可插拔的工具调用和网关架构。本集成以 Hermes 插件 形式安装到 ~/.hermes/plugins/litefuse/。插件在 Hermes 的 Python 解释器中以同进程方式运行，订阅生命周期 hook 事件（pre_llm_call、post_api_request、pre_tool_call、post_tool_call、post_llm_call 等），为每个用户回合生成一条 Litefuse trace，使用真实的 wall-clock 逐事件时间戳。

该插件适用于 Hermes 的所有界面 —— CLI（hermes chat -q）、Gateway（飞书、Discord、Slack、Telegram、WhatsApp、IRC），以及（在合并了 PR #24237 之后的）TUI。

给 AI —— 自动安装

如果你正在和 Hermes Agent 对话，把下面这段 prompt 粘贴过去，Agent 会端到端完成整个安装：

Read https://litefuse.ai/SKILL.md and follow the instructions to install and configure Litefuse for Hermes Agent.

skill 会向你索取 Litefuse 的 API Key（如果还没有账号，会引导你注册），然后在本地完成全部配置。如果你想手工一步步配置，请继续往下看。

会捕获哪些数据

Trace 结构

一个典型的多工具回合产生的 trace 形如：

Hermes Agent — Turn 7                (SPAN, root, real duration)
├── user message                     (EVENT, flushes trace metadata immediately)
├── api: MiniMax-M2.7 #1             (GENERATION, usage_details, real latency)
├── tool: web_search (#1)            (TOOL, real duration)
├── api: MiniMax-M2.7 #2             (GENERATION, usage_details)
├── tool: web_extract (#2)           (TOOL, real duration)
├── api: MiniMax-M2.7 #3             (GENERATION, usage_details)
└── assistant response               (GENERATION, final answer)

设计说明：

• 真实 wall-clock 时间戳。 每个 observation 的 start/end 都来自 hook 回调触发的那一刻，所以 Litefuse 时间线反映真实的 LLM 延迟、工具执行时间和调用之间的间隔 —— 没有合成网格。
• 唯一根父节点。 容器 span 是唯一的 trace 根；每个 api / tool / response observation 都嵌套在它下面。即便回合超过 50 步，时间线视图也保持整洁。
• Trace header 稳定。 Trace 名称 / input / session_id 在回合 START 时就刷新到 Litefuse（通过带真实 wall-clock end 的 user message event + lf.flush()），并且不会在新 observation 到达时被中途覆盖。
• 工具编号。 tool: observation 名称上的 (#N) 后缀消除同一个工具在一回合内被多次调用的歧义。
• 命名空间化的 metadata。 所有 Hermes 专属字段都放在 metadata.hermes_agent.* 下，让顶层 metadata 字典只保留 Litefuse 标准 key。

快速开始

~/.hermes/hermes-agent/venv/bin/pip install 'langfuse>=4,<5'
 
# Verify
~/.hermes/hermes-agent/venv/bin/python3 -c "import langfuse; print(langfuse.__version__)"
# Expect: 4.x.y

mkdir -p ~/.hermes/plugins/litefuse
curl -fsSL https://litefuse.ai/integrations/hermes-agent/plugin.yaml \
  -o ~/.hermes/plugins/litefuse/plugin.yaml
curl -fsSL https://litefuse.ai/integrations/hermes-agent/__init__.py \
  -o ~/.hermes/plugins/litefuse/__init__.py

cat >> ~/.hermes/.env <<'EOF'
 
# Litefuse observability
LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_HOST=https://litefuse.cloud
EOF

hermes plugins enable litefuse
hermes plugins list   # confirm: status = enabled

hermes gateway restart  # only if you have `hermes gateway` running

hermes chat -q "say hello in five words exactly"
tail -3 ~/.hermes/state/litefuse_plugin.log
# Expected: "turn complete session=YYYYMMDD_HHMMSS_xxxxxx turn=1 api_calls=1 tool_calls=0"

环境变量

工作原理

插件通过 ctx.register_hook(...) 订阅九个 Hermes 插件 hook 事件：

该插件是 fail-open 的：任何意外错误都会写入 ~/.hermes/state/litefuse_plugin.log，回调静默返回，所以永远不会阻塞 Hermes 的主循环。一个 Langfuse 客户端在模块级状态中跨 Hermes 进程整个生命周期保留（gateway 守护进程、CLI 调用、TUI 子进程），并由线程锁保护，多个并发的 gateway 会话可以安全共享。

Trace metadata 参考

Trace 级 metadata（位于 metadata.hermes_agent.*）：

• turn_number —— 从 1 开始，按 session 生命周期单调递增
• platform —— cli、gateway、tui、feishu 等（由 Hermes 设置）
• model —— 回合开始时的模型名称
• is_first_turn、history_messages —— 回合在 session 中的位置

Generation observation 元数据（api: ...，位于 metadata.hermes_agent.*）：

• provider、base_url、api_mode、response_model —— provider 配置
• api_call_count、api_duration、finish_reason、message_count —— 单次调用的统计
• assistant_content_chars、assistant_tool_call_count —— 输出形态
• step_index —— (#N) 步骤计数

Tool observation 元数据（位于 metadata.hermes_agent.*）：

• tool_name、task_id、tool_call_id
• duration_ms、is_error
• step_index

故障排查

Litefuse 中没有出现 trace。 用 tail 查看 ~/.hermes/state/litefuse_plugin.log：

tail -20 ~/.hermes/state/litefuse_plugin.log

期望：启动时出现 "litefuse plugin registered (9 hooks)"，每个回合出现 "Litefuse client ready" 和 "turn complete session=... turn=N api_calls=N tool_calls=N"。如果文件是空的，说明插件没加载。

hermes plugins list           # confirm: litefuse → enabled
hermes plugins enable litefuse  # if not enabled
hermes gateway restart        # if gateway is running

插件日志显示 Litefuse credentials not set。 插件没在 os.environ 中找到 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY。把它们加到 ~/.hermes/.env：

cat >> ~/.hermes/.env <<'EOF'
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://litefuse.cloud
EOF

然后重新执行任何 hermes chat -q "..." 或重启 gateway。

插件日志显示 langfuse SDK not importable。 Langfuse SDK 没装在 Hermes 的 venv 中：

~/.hermes/hermes-agent/venv/bin/pip install --upgrade 'langfuse>=4,<5'

长回合中 trace 名称 / session / input 没出现。 这是我们修复过的真实 bug，办法是发出一个小的 user message observation（类型为 event，结构上像一个 span，让 Langfuse 传播 AS_ROOT + TRACE_* 属性），并在回合开始时强制 flush。如果你看到这种现象，很可能在用旧版本的 __init__.py —— 从 https://litefuse.ai/integrations/hermes-agent/__init__.py 重新拉取。

TUI 会话不产生 trace。 Hermes v0.12 在 TUI 进程中不加载插件（tui_gateway/entry.py）。可以选择：

• 升级到合并了 PR #24237 的 Hermes 版本，或
• 在本地给 ~/.hermes/hermes-agent/tui_gateway/entry.py 打一个三行的补丁（hermes update 时会被覆盖 —— 每次更新后再打一次）。

CLI（hermes chat -q、hermes -z）和 Gateway（飞书、Slack、Discord、Telegram 等）不打补丁也能工作。

hermes -z "..."（oneshot 模式）也不产生 trace。 同样的根因 —— oneshot 的入口没有调用 discover_plugins。请改用 hermes chat -q "..."（完整的 CLI 路径，会加载插件），或者给 hermes_cli/oneshot.py 打同样的三行补丁。我们会为此再提一个配套 PR。

局限

• 不会捕获助手的 reasoning。 Hermes 插件 hook 回调不直接暴露模型的 reasoning / chain-of-thought 文本 —— post_api_request 只给我们 assistant_content_chars（字符数）。思考文本存在于 Hermes 的对话历史中，但要采集它需要订阅当前还不可用的逐消息事件。
• 不汇总图片 block。 如果回合涉及图片输入，插件会把它们以 JSON 扁平化的文本形式写入 trace 输入；不会单独把媒体类型或数量作为 metadata 暴露出来。

资源

• Hermes Agent hooks 用户指南
• Hermes Agent 插件参考
• Langfuse Python SDK v4
• Litefuse Cloud
• 插件源码：plugin.yaml · __init__.py
• TUI 插件发现的上游 Hermes Agent PR：NousResearch/hermes-agent#24237