Hermes 飞书流式卡片插件

在飞书里，看见 Hermes 正在做什么，直接确认下一步，完整读到最终答案。

本插件（HFC）把 Hermes Agent Gateway 的飞书/Lark 回复变成持续更新的交互式卡片。普通问答保持原卡；需要审批或澄清时，可以直接点选，后续输出按顺序续答，过程与结果都方便回看。

它适合已经在使用、或准备把 Hermes Agent 接入飞书的用户。模型、工具和任务仍由 Hermes 执行，HFC 负责卡片展示、交互和投递。

为什么使用 HFC

你关心的事	卡片里的体验
知道任务有没有在推进	实时显示当前工具动作、过程记录和答案；区分运行、等待、失败与完成
少打字，也少刷屏	审批、澄清支持按钮或表单；系统提示集中展示，减少重复消息
长回答读得清楚	正文与思考/工具过程分区，支持 Markdown、代码和表格；可选阅读预设
交互前后内容连贯	审批后按实际输出创建续答卡，保留此前正文和操作回执
适配自己的使用方式	支持私聊、群聊、话题、多 bot / 多 profile；指定会话可使用原生消息
出问题有线索	提供状态检查、兼容性诊断、安全修复和恢复命令

/model 与 Hermes CLI 使用同一 Provider/模型列表，按 Provider → Model 两级选择；/resume 可选择历史会话。页脚可显示模型、耗时、Token 和上下文用量，具体字段取决于 Hermes 提供的数据。

看看实际效果

运行中：当前动作与过程	等待：直接在卡片操作

展开查看失败、完成与命令交互示例

失败：保留已有内容	完成：阅读最终答案

截图来自已发布版本的真实飞书验收；不同客户端、版本与配置的外观可能不同。

快速安装

准备好： 已安装的 Hermes Agent、Python 3.9+，以及已接入 Hermes 的飞书/Lark 机器人（App ID / App Secret）。初次接入、权限与环境说明见安装手册。

macOS / Linux

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

Windows PowerShell

irm https://raw.githubusercontent.com/baileyh8/hermes-feishu-streaming-card/main/install.ps1 | iex

脚本默认解析最新稳定 Release，安装到 Hermes 使用的环境，读取或提示凭据并写入本地 .env，再完成配置、hook 安装和 sidecar 启动。已有包也可手动运行整合安装器（将路径替换为实际路径）：

python3 -m hermes_feishu_card.cli setup --hermes-dir ~/.hermes/hermes-agent --config ~/.hermes/config.yaml --yes
python3 -m hermes_feishu_card.cli status --config ~/.hermes/config.yaml
python3 -m hermes_feishu_card.cli doctor --config ~/.hermes/config.yaml --hermes-dir ~/.hermes/hermes-agent --explain

按安装输出启动或重启 Hermes Gateway，再给机器人发一条消息，确认卡片能从运行态更新到最终答案。status 表示服务状态；实际发卡仍需这一步确认。

Linux： systemd user manager 与 linger 就绪时，setup 默认启用常驻服务；否则警告后临时启动。--transient 可显式选择临时运行。
macOS： 默认临时运行，enable 不支持 macOS。登录自启动可自行配置 LaunchAgent，以 RunAtLoad=true 执行一次 start，不要设置 KeepAlive=true。详见安装安全。
Docker： 在已有 Hermes 容器中，使用仓库内的安装脚本：

export FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx HFC_VERSION=v4.6.10
bash install-docker.sh

默认 HERMES_DIR=/opt/hermes、HFC_CONFIG=/opt/data/config.yaml、HFC_ENV_FILE=/opt/data/.env。详见容器安装与 Compose 示例；示例不是官方镜像。

配置方法

setup 会准备配置。需要手动调整时，参考 config.yaml.example，编辑安装时选中的 --config 文件；不要直接覆盖已有 Hermes 配置。

1. 开启 Hermes 流式输出

在 Hermes 配置中设置 streaming.enabled，使用 edit transport：

streaming:
  enabled: true
  transport: edit

不要设置 display.platforms.feishu.streaming: false；不要把 display.show_reasoning 当作插件必需开关。HFC 直接处理流式思考与答案。

2. 配置凭据与卡片

最小配置示例（凭据优先放 .env）：

server:
  host: 127.0.0.1
  port: 8765
feishu:
  app_id: ""
  app_secret: ""
card:
  title: Hermes Agent
  table_overflow_mode: compact
  footer_fields: [duration, model, input_tokens, output_tokens, context]
bindings:
  native_chats: []
integrity:
  mode: safe
service:
  manager: auto

配置同目录的 .env：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_CONNECTION_MODE=websocket
FEISHU_HOME_CHANNEL=oc_xxx

优先级：YAML < 配置同目录 .env < --env-file 显式文件 < 进程环境。setup / start --env-file ... 读取选定文件，不自动回退到全局 .env。缺凭据会报告 degraded / noop，不会真正发卡。

3. 选择阅读方式（可选）

card:
  reading_preset: focused

预设	适合的阅读方式
缺省 / `classic`	保持现有展示方式，过程面板折叠
`focused`	重点看答案；思考放在面板，正常完成后精简成功工具行
`detailed`	展开思考与工具过程，便于追踪任务

同层显式字段优先于预设。若从完整示例复制了旧显示开关，预设可能被覆盖；用 hermes-feishu-card card-config --config <配置路径> 检查有效值，重启 sidecar 后生效。更多选项见阅读预设。

想调整什么	配置 / 文档
实时思考不进入正文	`card.stream_thinking_to_body: false`
完成后精简成功工具行	`card.hide_completed_tool_activity: true`，保留异常工具
字号、页脚与订阅额度	`card.text_sizes`、`card.footer_fields`；可选 `subscription_usage`
指定会话使用原生回复	`bindings.native_chats` 精确匹配；多 profile 在对应 profile 下配置
多机器人、群聊与 profile	配置与路由
可选 CardKit 流式更新	开关与权限要求

旧配置缺少 integrity 时保持 notify，不会静默开启自动修复。完整配置及边界见安全控制与排障。

日常使用与排障

入口	用途
飞书 `/hfc status`	查看当前会话与群聊绑定状态
飞书 `/hfc doctor`	查看诊断与可用的修复操作
CLI `status` / `doctor --explain`	核对进程、实际加载版本与 Hermes 兼容性
CLI `card-config`	查看最终生效的阅读配置及来源
CLI `repair` / `restore`	按诊断修复可验证状态，或恢复原始受管文件
CLI `start --config ...` / `stop --config ...`，`enable` / `disable`	分别管理临时 sidecar 与 Linux 常驻服务

CLI 命令均以 hermes-feishu-card 为前缀，并使用实际配置路径。Hermes 升级后先运行 doctor --explain，按诊断给出的命令恢复；不要手改安装目录里的 gateway/run.py。兼容性取决于实际源码和能力检测，不只看版本号。

HFC 采用 sidecar-only 架构：Hermes 运行任务，安装器管理必要 hook，独立 sidecar 处理卡片状态、投递和更新。更多内容见使用手册、架构、维护 Wiki和测试说明。

More technical documentation / 更多技术文档

Architecture / 架构：中文 · English
Event protocol / 事件协议：中文 · English
Installer safety / 安装安全：中文 · English
Migration / 迁移：中文 · English
E2E verification / 端到端验收：中文 · English
Release readiness / 发布检查：中文 · English
Testing / 测试：中文 · English

近期更新

版本	重点
v4.6.10	Hermes 0.21.5 适配、PM 运行环境安装与跟进卡片隔离
v4.6.9	群聊并发卡片隔离、紧凑单选按钮与新手 README
v4.6.8	macOS 安装与恢复提示，明确自主管理登录启动和未知进程归属
v4.6.7	保留可编辑心跳，紧凑审批按钮与完整正文
v4.6.6	审批回执确认后精简重复、运行工具可见与原生通知自动收尾
v4.6.5	重启通知持久归属、工具调用去重、可选时间线显示与模型报错去重
v4.6.4	首次按钮接线、顺序续答、可选阅读预设与作用域通知清理
v4.6.3	实时思考正文开关、工具耗时与中断用量
v4.6.2	原生插件共存维护证明与可选终态工具区
v4.6.1	Hermes 0.21.3 hook、状态撤回和审批展示修复

更早版本见历史更新；完整记录见 CHANGELOG 与 GitHub Releases。

贡献者

感谢每一位提供代码、方案、问题复现与现场验证的贡献者。历史署名与关联 PR / Issue 完整保留在下方。

展开全部贡献记录

V4.6.10: Nevoker (PR #355), shichenshuo-star (PR #358); leavrcn (#359), lanx214 (#352), kite40 (#353), ywarmy and mslchy (#354), Love4yzp (PR #355 deployment evidence). 保留 PR 原始代码作者；感谢问题报告者的复现与诊断证据。
V4.6.9: 感谢 cainiaozp 在 #348 提供群聊并发复现与根因线索；感谢 mouyong 在 PR #349提供紧凑单选布局实现与测试，保留原始代码作者。
V4.6.8：感谢 coder-zhw 的 PR #347，提供 macOS 安装、未知 pidfile 与登录启动提示的现场分析、实现和回归测试。
V4.6.6: 感谢 mouyong 在 PR #338 / PR #339 的通知、阅读与审批方案，以及 #337 / #340的现场证据；本版以投递确认、有界清理和保留默认的方式适配，保留真实代码署名。同时感谢 tidytorch 的 PR #342 延迟交互确认修复；保留原作者提交，并补强总等待预算与真实 HTTP 丢响应回归。
V4.6.4：感谢 sthnow 在 #335 提供冷启动按钮与交互后排序证据，以及补丁作者 babypanda 的 eager-hook 实现；适配部分保留 Co-authored-by。感谢 mouyong 的 PR #331 续答与通知生命周期方案、代码贡献及 #330 提交前验证需求；本轮按子项吸收，不等于整 PR 合并。可选阅读预设继续回应 jackwude 的 #328 与 leavrcn 的 #333。保留以下全部历史贡献记录。
V4.6.3：感谢 leavrcn 的 #333 长思考复现与配置建议；适配 mouyong 的 PR #331 工具排序、耗时与中断用量实现，保留代码署名；通知撤回等其余改动仍独立审查。
V4.6.2：感谢 jackwude 提出 #328，并补记其对 4.6.1 #329 的复现贡献；mouyong 在 PR #331 提供 hide_completed_tool_activity 配置方案。本版仅适配这一功能，保留默认显示并覆盖 completed/failed；#331 其余改动仍待审查。
V4.6.1：感谢 mouyong 的 PR #325 与 #326 定位，保留原始提交。
V4.6.0：感谢 mouyong 的 PR #310 新增修复及 #320 现场证据；zhangzq 提供 #319 结构化思考诊断；qqqq560204-maker 定位 #323 自定义 profile 撤回路由。保留 PR 原作者。
V4.5.1–V4.5.2：感谢 mouyong 的 PR #310，以及 #282、#304、#305、#307、#311–#314、#318/#321 的现场反馈、复测及排队结果、心跳撤回修复；lanx214 的 Issue #316 和 PR #317 提供 Hermes clarify 抽取兼容修复；qqqq560204-maker 与 7360403-coder 在 Issue #306 提供 CardKit 300301 诊断线索。两项 PR 保留原始提交作者，维护者补充安全边界与回归验证。#282 已按报告者意愿关闭，未认定手机问题已修复。
V4.4.5–V4.4.6: tidytorch (#286/#291), Jentlezhi (#292), sp960817, Cyber-Yichen, shichenshuo-star, ywarmy (#288/#294/#296), 7360403-coder (#298), mouyong (#276/#280/#282/#289/#301). 感谢代码、测试和现场证据；保留 #291/#292 原始提交作者身份。

V4.4.3

mouyong：#268 的 multiplex 生产反馈与 #269 的空 timeline 体验建议。#268 尚待报告者真实多 bot 环境复验。

V4.4.2

ywarmy: #261, Hermes 0.21 completion-marker report.
Ricadre: #265, stale integrity migration reproduction.
mouyong: #83, #263, #264, #266, Docker/source-only and multiplex evidence; #258, approval readability feedback.

V4.4.1

liooil：PR #257 提供 Hermes facade 拆分适配实现；Clarence-G：PR #251 提供话题后续投递、queue/redirect 与 cron 相关修复。原始代码提交和作者身份予以保留。
mouyong：#83、#252、#253、#258、#259 的单进程 profile、话题和阅读体验反馈；shiboyumm：#83 最初的配置问题；Boer2333：#250 的 provider 展示需求。
sp960817：#254、Kevin32623：#255、shichenshuo-star：#256 的 Hermes 0.21 兼容性报告；hnzwx 与 leavrcn：#254 的复现与兼容性审查；micah928：#73 的历史无卡片诊断证据，该环境仍待新版复测。
Dependabot 提供 PR #247 和 PR #248 的 CodeQL 依赖更新。
历史署名补全：lanx214 在 Issue #240 提供 Linux 复现（V4.3.7）；Lite-G 报告、复现、测试并实现 PR #235 的 Feishu edit fallback 修复（V4.3.5）；lyp88997 提供 toast-only 200673 修复方向及跨环境更新观察（V4.3.2）。这些是此前版本的贡献，本轮恢复遗漏的历史署名。

这里同时记录代码、PR 方案、Issue 复现和真实环境复测贡献。GitHub 的 Contributors 图按进入 Git 历史的 commit 统计；只提供 Issue、评论、日志或复测证据的贡献者可能不会出现在图中，但仍在这里保留署名。

gischuck - PR #12 Accept-Encoding 修复；PR #76 思考与工具 timeline 体验建议与实现探索
fengs2021 - PR #17 锁架构优化与更新间隔改进
colinaaa - PR #87 WebSocket interaction.select clarify/approval 卡片交互支持；PR #88 话题群 message_id 复用下第二轮消息新卡片修复；PR #91 cron 结果回到飞书话题群原线程的 thread_id 路由修复
zayn-0101 - PR #77 cron deliver=origin/all 路由意图卡片投递修复；PR #196 非阻塞 slash-confirm；Cassius0924 - PR #199 多选与自定义回答表单
Zanetach - PR #84 / @Zanetach：卡片 progress-status 路由与 .env 白名单扩展的 profile 环境支持（V3.9.0）
colinaaa - PR #93 打断任务后将旧卡片可靠收束为终态；PR #97 保留完整完成答案（V3.9.1）
wjiemin49-ux - PR #52 loopback 健康检查代理问题的诊断与修复方向（V3.9.1 采用）
colinaaa - Issue #94 裸 /resume 原生会话选择器的需求、交互流程与安全边界（V3.10.0）
charles5g / jackmim - PR #98 模型选择回调异步化、原卡片状态更新与 footer 语义色创意；主线实现补充 HTML 转义并保持布局不变（V3.9.1–V3.10.0）
tianqiii - Issue #107 Codex 订阅配额 footer 的需求、Hermes 原生接口方案与展示格式（V4.0.2）
sthnow - Issue #110 Markdown 代码中的 MEDIA: 字面量误解析复现、根因与期望边界（V4.0.4）
zkyken - Issue #112 lark SDK 预绑定 callback 下交互按钮失效的日志、根因线索与修复方向（V4.0.4）
ShakuOvO / blakejia - Issue #106 与 #111 图片回答灰色正文重复的报告、复测与截图（V4.0.1–V4.0.3）；另感谢 blakejia 在 #115 提供 Gateway venv 旧版本证据、完整升级步骤与复测指标（V4.0.5）；感谢 nasvip / hzy / lRoccoon 贡献 V4.0.6 的 Hermes 升级恢复复现、background 通知卡片实现，以及 Hermes 0.18.x completion hook 生产诊断与修复；V4.0.7 继续感谢 nasvip 的 Issue #125 systemd/Python 环境完整证据，以及 hzy 的 PR #124 自我改进通知卡片实现与回归测试；V4.0.8 感谢 zyq2552899783-lgtm 报告 Issue #127 的 cron 附件只显示文件名问题；V4.0.9 感谢 Jasonsun77 在 Issue #130 提供 Linux crash-loop A/B、完整时间线、SDK 版本与上游 reconnect 关联证据
V3.4–V3.8 历史 PR：感谢 wzgrx（PR #30/#35/#36/#38）、zsfjim（PR #33）、atop0914（PR #42）、0269chaoup（PR #49）、dominofeng-maker（PR #50）、coder-zhw（PR #51）、x-giraffee（PR #54）、jackwude（PR #72）与 bestkxt（PR #85）提交版本检测、进度事件、cron/话题路由、session 回收、配置、Hermes venv、同步脚本与投递策略方案；感谢 Thomas0x1f 的 PR #143 多选交互探索。部分方案由主线以更严格边界重新实现，并非全部逐字合并。
V4.0.10–V4.0.21：感谢 tianxia3111（Issue #133/#153/#155）、nasvip（Issue #136）、ati121（Issue #141/#142）与 Cassius0924（Issue #147）提供 compaction、systemd 凭据、工具展示、长任务重复卡片、notice 投递和内容完整性证据。
V4.1.x：感谢 shutdown-awa（Issue #157）、Redeemer-w（Issue #159）、Cyber-Yichen（PR #156）、wholegale39（PR #160）、dake6767（PR #168）、foras910521-lab（Issue #169）与 simon881（Issue #171）贡献聊天排除、表格截断、systemd、Hermes 新入口、answer-delta、TurnRunner 与 Windows 迁移的方案或现场证据。
V4.2.x：感谢 Cassius0924（PR #177/#199/#205/#206）、mslchy（PR #180/#181）、ati121（Issue #187）、xingdongcai（Issue #188）、Cyber-Yichen（Issue #189）、createpjf（PR #190）、Crystalxd（Issue #192）、simon881（Issue #193）、jdysya（Issue #197）、AnyNice（Issue #198）、Timeral（Issue #202）、chinakids（Issue #208）与 yuqianma（Issue #183）贡献话题卡、Windows runner、重复交互、终态正文、Hermes 0.20、引用摘要、旧卡收束、plugin-style runtime 与自启动的实现、复现和复测。
V4.3.x：感谢 leavrcn（Issue #210/#211/#212/#221/#237）、jsuper（Issue #214）、nasvip（Issue #215/#244）、mouyong（Issue #217）、Timeral（Issue #245）、Cassius0924（PR #213/#220/#228）、PureWhiteWu（PR #242）与 L261173157（Issue #222 / PR #223）贡献 Hybrid runtime、交互状态、常驻服务、升级恢复、授权、话题投递、HTTP proxy 与 callback 重试的关键证据或方案；感谢 saulgoodmanngabriel 和 zhangzq 在 Issue #216 提供真实 Hermes 0.20 / 飞书 WebSocket 点击与流式恢复证据；感谢 RanHuang 的 PR #226 揭示 persistent service identity、systemd WorkingDirectory 与 tokenless health 对账缺口。
另感谢 Akes119（PR #184）和 yaoge103（PR #185/#186）提交完成通知与 interaction identity 的替代实现。相关补丁没有按原样合入，因为会造成重复完成通知或削弱 profile/sequence fencing，但这些探索仍作为公开技术讨论保留。

参与开发请先阅读 AGENTS.md 与测试说明。提交问题时请附 Hermes/HFC 版本、复现步骤及脱敏日志。

安全与 License

默认仅监听 127.0.0.1。非回环部署需要显式开启与 HMAC 鉴权，并自行配置 TLS；不要提交 App Secret、token、真实聊天标识或未脱敏截图。详见安装安全。

MIT License。

可选服务与赞助披露

ScrapingAnt 是可选网页抓取服务，不是本插件的依赖。此链接为 Affiliate link；符合条件的首次付费订阅可能为项目带来佣金。

commie70/hermes-feishu-streaming-card

README