🍟 薯条卡片 (hermes-fry-cards)

🍟 Hermes Gateway 飞书流式卡片插件 — CardKit v2.0 实时流式消息

• English · 安装指南 · 文档目录 · 优化方案

✨ 核心特性

🏗️ 架构总览

🚀 快速安装

AI Agent 一键安装

curl https://raw.githubusercontent.com/techysy/hermes-fry-cards/main/INSTALL.md

手动安装

# GitHub（主仓库）
git clone https://github.com/techysy/hermes-fry-cards.git
# 或国内 Gitee 镜像（更快）
git clone https://gitee.com/techysy/hermes-fry-cards.git

cd hermes-fry-cards
HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m pip install -e .
$HERMES_PYTHON -m hermes_fry_cards verify
$HERMES_PYTHON -m hermes_fry_cards install
hermes gateway restart

⚙️ 配置

streaming:
  enabled: true
  header:
    enabled: true
  footer:
    enabled: false
    fields:
      - [status, elapsed, model, context]
display:
  platforms:
    feishu:
      show_tool_use: true        # 展示工具调用面板
      show_reasoning: false      # 展示推理过程
      show_context: true         # 统一面板 header 显示上下文窗口
      context_display_mode: text # text / bar / text_bar
      max_reasoning_panels: 3    # 最多保留的独立推理面板数（超出后合并，防元素溢出）
      unified_panel_min_duration: 5  # 统一面板最小展示耗时（秒）
      truncate_model_name: true  # 截断模型名（nvidia/moonshotai/kimi-k3 → ⇲kimi-k3）

上下文显示格式

开启 show_context 后，统一面板 header 会显示上下文窗口使用量：

block / block_text 样式在桌面端/移动端显示不一致，已废弃，自动回落到 bar / text_bar。

配置项一览

模型别名配置

独立于 config.yaml，别名写在 ~/.hermes/model_aliases.json：

{
  "longcat": "哈基米",
  "gemini": "哈基米"
}

• 匹配：key 对完整模型名做大小写不敏感子串匹配（longcat → or/lc/LongCat-2.0 命中）
• 优先级：别名命中 → 显示别名；未命中 → 回落截断逻辑
• 热更新：每次渲染重读，改完文件即生效，无需重启网关

完整路径：~/.hermes/model_aliases.json
| 模型别名 | ~/.hermes/model_aliases.json 子串匹配，命中优先于截断 | 无 |

样式效果示例

统一面板 header 的完整形态（完成态卡片底部折叠面板标题）：

header 各部分含义：🍟 模型名 · 💭n 推理轮次 · 🔧n 工具调用数 · 上下文窗口 · ⏱️ 耗时。

无工具调用或回复 ≤ unified_panel_min_duration 秒时，整个统一面板（含 header）不显示。

🖥️ CLI 命令

HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m hermes_fry_cards verify     # 验证兼容性
$HERMES_PYTHON -m hermes_fry_cards install    # 注入 hook
$HERMES_PYTHON -m hermes_fry_cards uninstall  # 移除 hook
$HERMES_PYTHON -m hermes_fry_cards status     # 查看状态

📝 更新 / 卸载

更新

cd hermes-fry-cards && git pull
HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m pip install -e .
$HERMES_PYTHON -m hermes_fry_cards uninstall
$HERMES_PYTHON -m hermes_fry_cards install
hermes gateway restart

卸载

HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m hermes_fry_cards uninstall
$HERMES_PYTHON -m pip uninstall hermes-fry-cards

🧠 工作原理

用户发送消息
  → 创建卡片会话
  → 流式更新（工具状态、文本增量 — 节流调度）
  → 图片 URL 异步解析替换
  → 终态卡片（token/耗时/上下文）

🛡️ 稳定性保障（v0.1.1）

• session 生命周期统一管理：注册/清理单一入口、幂等可重入；中断接管不误删新会话映射；异常残留的终态会话允许重建，不再需要重启网关恢复
• flush 竞态防护：完成标记与刷新请求交叉时不会误触发多余 CardKit 调用；同一份数据不会被重复刷新
• 失败原因可追溯：卡片失败时记录首次失败原因（mark_failed(reason=...)），回退网关纯文本是统一决策点

排查问题时可直接按以下标准化日志事件在 ~/.hermes/logs/agent.log 中检索：

📄 文档与报告入口

• 优化方案 — 稳定性与维护性优化方案
• 卡片设置指南 — 全部配置项与常用场景
• 排障指南 — 与 hfc 插件冲突、卡片不显示、hook 未生效等常见问题
• 文档目录 — 项目文档入口
• 测试报告目录 — 报告存放规范与入口
• 核心汉化补丁：skills/hermes-core-zh-localization/（仓库内附带，安装方式见 SKILL.md）

说明：测试报告建议统一保存在 tests/reports/，并按日期/主题命名，便于后续回归对比和审计。

🔄 热更新 & 网关重启说明

本插件通过 AST 注入 hook 到 Hermes 的 gateway/run.py 和 cron/scheduler.py。部分配置支持热更新（无需重启），但插件代码改动和部分结构类配置需要重启网关才能生效。

✅ 支持热更新（改 config.yaml 后下一条消息即生效）

以下 display 显示 / 样式类配置项，每次渲染都会从磁盘重读，无需重启：

⚠️ 需要重启网关（hermes gateway restart）

以下改动必须重启，运行中的进程不会热加载：

• 插件代码修改（git pull 更新、改源码）
• streaming.enabled 开关
• streaming.header / footer / body / width_mode 等 streaming 结构类配置
• 飞书凭据 app_id / app_secret

hermes gateway restart

⚠️ 注意：hermes gateway restart 需要在 gateway 进程之外的独立 shell 中执行。
若从 gateway 进程内部（如通过 AI 对话让 agent 执行）触发，SIGTERM 会传播到子进程，
重启命令本身会被杀掉。请在本地终端手动运行。

✅ 重启不会损坏任何东西，可放心反复执行（可以无限重启）。

重启后的效果验证：hermes_fry_cards status 显示所有 hook installed，飞书渠道连接正常即可。

故障排查

📦 镜像仓库

• GitHub 主仓库：techysy/hermes-fry-cards
• Gitee 国内镜像：techysy/hermes-fry-cards — 国内访问更快，与 GitHub 同步

🔗 相关项目

🔄 与上游 hermes-lark-streaming 的差异

本项目基于 Cheerwhy/hermes-lark-streaming v0.12.0 独立开发。核心流式引擎沿用上游 AST hook 注入架构，在此之上做了三层增强：

✨ 新增功能

行为默认值：show_reasoning 默认 true（上游默认 false）。

🔧 关键修复（上游存在的坑）

• 300305 元素超限强制拆卡恢复 — 卡片实际元素总数超飞书硬上限时，自动封印旧卡、未创建 segment 迁移新卡续流，不再永久卡「处理中」
• 远程图片 URL 过滤 — 规避 CardKit 拒绝远程 URL（200570 invalid image keys），无法上传的引用先 strip 并包代码围栏
• 完成态 Duplicate ID 修复体系 — reasoning text_el_id 全链路复用 + 带索引唯一 ID 兜底；上游完成态用固定 reasoning_text 会与流式阶段元素冲突，导致卡片卡 loading
• seal/complete 失败清理 loading 图标 — 收尾失败不再残留「处理中」状态

🏛️ 内部稳定性重构（v0.1.1）

• session 生命周期统一入口（注册/清理幂等）、interrupt 后不误删新会话映射、终态会话可重建
• FlushController 竞态防护：完成态快照防误重刷、遗留 timer 取消防双刷
• mark_failed(reason=...) 失败原因可追溯 + 结构化日志事件 + _yield_to_gateway 单一回落决策点
• 测试规模 15 个文件、新增 9 个稳定性回归测试；配套 CONFIGURATION / TROUBLESHOOTING 文档

📄 归属说明

灵感来自 hermes-lark-streaming（作者 Cheerwhy），原项目使用 MIT 协议。本项目为独立开发版本，已进行架构重写和功能重构。

📄 许可证

MIT