如果你在飞书中使用 Hermes，那么一定要装一下这个插件 它可以把 Hermes 的回答转换成飞书卡片，非常漂亮

飞书里 Hermes 回复总刷屏？这个 sidecar 插件把一切塞进一张持续更新的卡片

你用 Hermes Agent Gateway 接飞书，结果思考过程、工具调用、中间结果散落在十几条灰色消息里，代码块切一半，长表格直接 raw markdown，用户点个 approval 还得手动敲编号。等最终答案出来，上下文已经断得不成样子。很多人以为这是飞书平台的“宿命”，但这个开源插件直接把问题翻转了：它用 sidecar 模式把 Hermes 的各种 delta 事件聚合到一张交互式卡片里，思考、工具、答案、按钮、统计全在同一张卡片里实时更新，几乎不漏字、不乱序。

早年接企业 IM 时也为流式输出和交互闭环头疼过。Hermes 本身能力强，但飞书适配层在长内容和交互上容易翻车。这个 hermes-feishu-streaming-card 插件正是针对这些真实场景做的补丁，它不是简单包装 API，而是从 hook、状态机、渲染切分到运维诊断都下了功夫。核心结论是：对飞书重度用户来说，它让 Hermes 的体验从“勉强能用”变成“舒服到想一直开着”。 普通人能直观感受到聊天窗口干净多了，技术同学则能看到它在兼容性和可观测性上的细节处理。

为什么一张卡片比一堆消息强这么多

飞书消息流很容易失控。模型思考时发 thinking.delta，调用工具时 tool.updated，最后 answer.delta 和 completed 事件接踵而至。原生适配可能导致内容乱序、漏字，或者完成后再冒出一条灰色原生消息，用户体验直接崩盘。普通读者可以这么想：就像外卖骑手每送一单都发一条语音告诉你“已取餐”“路上堵”“快到了”“已送达”，你手机叮叮当当响个不停，关键信息反而淹没其中。

这个插件把这些事件聚合到同一张飞书卡片，通过 PATCH 更新实现流式效果。结果就是思考过程可见，工具进度实时刷新，最终答案自然接上，不再有断裂感。更重要的是，它保留了 Hermes 的 approval 和 clarify 机制，但转成了卡片内的按钮。用户点一下就能继续任务，卡片继续更新，无需切换输入框手动回复。

对同行来说，这背后是 per-message 顺序保证、PATCH 合并串行化、终态优先和原生 resend 抑制等机制。同一消息的 HTTP 事件用 message id 加锁，避免多线程 callback 踩踏；answer.delta 和 thinking.delta 保留原始边界空格，防止中英文、代码片段粘连或截断。thinking.delta 还支持 append_block 模式，确保思考句子完整。

我之前总觉得飞书卡片更新频率高了会出问题，但实际跑下来，sidecar 非终态事件快速 ACK，刷新间隔能到 0.2s，同时终态事件优先落卡。这套处理让流式既稳又快。当然，边界条件要说清楚：极长内容还是会分块，飞书本身有 5 个表格限制，插件会自动截断并提示，这不是万能的，但比 raw markdown 好太多。

长内容渲染和多 bot/profile 的真实运维解法

长表格和 fenced code block 是飞书 Markdown 渲染的经典雷区。插件的 Markdown-aware split 按结构边界切分，长表格重复表头分块，长代码块拆成多个完整 fence，避免半截围栏。普通场景下，你发个几百行代码或复杂对比表，用户打开卡片就能看清结构，不会一脸懵。

技术上，它还兼容 DeepSeek 的 标签过滤，保留 V3.3.0 的表格保护逻辑。这些细节看似小，但积累起来就是稳定性。假设你在生产环境跑多 profile、多 bot 场景，一个 sidecar 服务多个 Hermes profile，用 profile_id:message_id 隔离 session，bot 级标题优先，群聊绑定通过 bindings.chats 路由。路由诊断 endpoint 如 /health.routing.profiles 能直接看到 bot 数、群聊绑定、last_route 和错误，排查起来清晰很多。

这里我得自我纠正一下：早些时候我以为 sidecar-only 架构会增加延迟，但实际 Hermes hook fail-open，飞书发送/更新、重试、健康检查全在 sidecar 里独立跑，反而降低了主流程风险。唯一需要注意的，是升级 Hermes 后必须重新 install hook，让它匹配当前版本的 gateway_run_013_plus 或 legacy 策略。V3.6.1 还专门修复了 VERSION 文件无 v 前缀时的误报，0.15.x 版本处理更稳。

多 profile 下配置凭据要每个 profile 显式写，顶层 env 不会覆盖，这避免了隐蔽 bug。无凭据时 sidecar 走 no-op client，只做本地状态，适合测试。

安装和诊断上手：一行命令解决大部分问题

实际操作比听起来简单。先用一行安装脚本：

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/main/install.sh | bash

Windows 用 PowerShell 等价命令。脚本会处理凭据、hook 安装、sidecar 启动。手动模式也清晰：clone 仓库，pip install -e ".[test]"，export 凭据，然后跑 setup。

⚠️ 注意： setup 前确认 Hermes 目录和 config.yaml 路径，升级后记得 doctor + install hook。

跑完 python3 -m hermes_feishu_card.cli status 就能看到 sidecar 状态。doctor --explain 给人工摘要，--json 输出机器可解析信息，包括 config、compatibility、recommendations。遇到 hook 异常或媒体文件，repair 命令能自救，只修复可验证部分，不会乱覆盖用户改动。

我测试过类似流程，doctor 这一步特别实用。它直接告诉你 version_source、hook_strategy 和 anchors 是否匹配，普通用户看摘要就能知道下一步，运维同学直接 copy json 排查。媒体文件处理也聪明：卡片显示摘要，原生投递路径保留，不丢上下文。

整个安装包还支持 Release 下载跨平台 tar/zip，包含 doctor、start/stop 等 CLI，发布友好度高。

用起来后你会发现的那些小惊喜

插件在 V3.6.x 重点补了运维：cron 卡片、附件摘要、profile 定向 smoke 测试、routing 诊断。这些在真实线上场景里能省不少时间。sidecar 架构让 Hermes 主流程 fail-open，即使卡片侧出问题也不卡死任务。

当然，不是所有场景都完美。极短交互或特定 Hermes 版本 anchor 变动时，可能还需要手动验证 hook。但整体来看，它把飞书接入 Hermes 的体验拉到了一个新高度。

你跑 Hermes 飞书时，最烦的是哪块卡片/流式问题？试完这个插件后，欢迎说说你的路由诊断结果。💬

如果你觉得这篇内容对你有启发，欢迎在留言区聊聊你的看法。

关注我，我会持续分享高质量的技术与思考干货。👇

原文地址: https://mp.weixin.qq.com/s?__biz=MzcwNjA1ODkxOQ==&mid=2247489086&idx=1&sn=9943cc92544d35769823be3a3fa7a83d&chksm=f5de19664ee2760a9085ad155ec48d7902d20cb3fcc5df20c3798e122d0b109340e0465a3854&mpshare=1&scene=1&srcid=0729XzgsuelSS4MLR4i4M9vv&sharer_shareinfo=af6b24c5af3bfb6cb3cf8afecb0ddb14&sharer_shareinfo_first=af6b24c5af3bfb6cb3cf8afecb0ddb14#rd