🧠 个人知识库

Hermes飞书流式卡片插件部署与运维SOP

Properties1
tagshermes, 飞书, 运维

4 min read

Hermes 飞书流式卡片插件 (hermes-feishu-streaming-card) 部署与运维 SOP

本卡片记录开源项目 baileyh8/hermes-feishu-streaming-card（简称 HFC 插件）在 Hermes Agent 宿主机上的部署原理、安全备份 SOP、真实安装坑点解决、流式卡片激活及灾备恢复 SOP。

一、 第一性原理与架构解耦

  1. 解决核心痛点：
    • 原生飞书适配器在 Agent 执行复杂任务时会发送多条散落的灰色消息（思考过程、工具调用、最终答案分开），导致聊天框刷屏。
    • HFC 插件通过在 Gateway 层注入事件钩子（Hook），将 思考过程 (thinking.delta) + 工具调用 Timeline (tool.updated) + 最终答案 (answer.delta) + 授权确认按钮 统一收束在同一张实时动态更新的飞书交互卡片中。
  2. 对现有系统的零干扰隔离：
    • 不影响后台 Python 独立 Cron 脚本（如 run_scheduler.py 跑步提醒、finews_check.py 早报）直连飞书 OpenAPI 的消息推送。
    • 替代了原先低效的手动美化卡片技能（已彻底卸载 feishu-card-sender-beautify）。

二、 阶段一：高风险操作前的安全备份 SOP (必做)

由于 HFC 插件需要修改 Hermes 网关入口文件 /usr/local/lib/hermes-agent/gateway/run.py，安装前必须执行严格的文件级物理备份：

# 1. 创建安全备份目录
mkdir -p ~/hermes_pre_hfc_backup
 
# 2. 备份 Hermes 核心 Gateway 代码
cp /usr/local/lib/hermes-agent/gateway/run.py ~/hermes_pre_hfc_backup/run.py.bak
 
# 3. 备份全局配置文件与凭证
cp ~/.hermes/config.yaml ~/hermes_pre_hfc_backup/config.yaml.bak
cp ~/.hermes/.env ~/hermes_pre_hfc_backup/.env.bak 2>/dev/null || true

三、 阶段二：真实安装避坑与激活步骤 (实战 SOP)

1. 核心坑点防范：显式指定源码路径 HERMES_DIR

  • 坑点说明：安装脚本默认会去 ~/.hermes/hermes-agent 找代码，如果系统源码在 /usr/local/lib/hermes-agent，不加环境变量会导致 reason: gateway/run.py missing 报错。
  • 正确安装指令：
export HERMES_DIR=/usr/local/lib/hermes-agent
curl -fsSL https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/main/install.sh | bash

2. 开启飞书流式卡片渲染开关

安装完成后，必须显式开启流式开关，否则卡片无法进行打字机流式更新：

hermes config set display.platforms.feishu.streaming true

3. 重启 Hermes 网关使 Hook 生效

# 重启网关以激活代码 Hook
hermes gateway restart

4. 探针连通性自检

# 运行 HFC 探针自检（确认 readiness: ready & status: running）
python3 -m hermes_feishu_card.cli status --config ~/.hermes/config.yaml

四、 阶段三：故障排查与一键还原 SOP (Disaster Recovery)

如果遇到 Hermes 官方升级（hermes update）覆盖了 gateway/run.py，或飞书卡片显示异常，按以下流程排查或还原：

1. 官方升级后的自愈修复

# 若 Hermes 升级后 Hook 被覆盖，执行一键修复
python3 -m hermes_feishu_card.cli repair --config ~/.hermes/config.yaml --hermes-dir /usr/local/lib/hermes-agent
hermes gateway restart

2. 一键秒级还原 (物理回滚)

若需彻底卸载并恢复原状，直接恢复阶段一的备份：

# 1. 恢复 gateway/run.py 入口
cp ~/hermes_pre_hfc_backup/run.py.bak /usr/local/lib/hermes-agent/gateway/run.py
 
# 2. 恢复主配置文件
cp ~/hermes_pre_hfc_backup/config.yaml.bak ~/.hermes/config.yaml
 
# 3. 重启网关恢复原状
hermes gateway restart

Graph View

Backlinks