Hermes 飞书流式卡片插件

中文 | English

!Hermes Feishu Streaming Card 封面

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

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

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

快速安装 · 配置方法 · 近期更新 · 使用手册 · 贡献者

发行版本：v4.7.4。 支持独立侧车环境，隔离 Gateway/Desktop 心跳，并核验进程退出后回收残留。见发行说明。

为什么使用 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.7.4
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
  width_mode: default  # default | compact | fill
  table_overflow_mode: compact
  footer_fields: [duration, model, input_tokens, output_tokens, context]
bindings:
  native_chats: []
integrity:
  mode: safe
service:
  manager: auto

card.width_mode 支持 default、compact、fill（自适应聊天窗口宽度），仅作用于 JSON 2.0 卡片；默认保持原布局，支持 profile/bot 覆盖，显式 default 可重置继承值。JSON 1.0 审批卡不变，最终尺寸仍由客户端决定。详见卡片宽度配置。

配置同目录的 .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 | 展开思考与工具过程，便于追踪任务 | | task（4.7.0） | 状态和动作集中展示，正文优先，过程折叠，统计简洁 |

4.7.0 新增可选 task 布局与九种状态的离线预览。启用方式、配置来源和回退见任务卡片。订阅周额度仅在实际使用 openai-codex 的 GPT 回合显示，其他模型或来源不明时隐藏。

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

| 想调整什么 | 配置 / 文档 | | --- | --- | | 实时思考不进入正文 | card.stream_thinking_to_body: false | | 正文只看最新思考 | card.thinking_body_tail_chars: 2400（默认 0 不截断） | | 完成后精简成功工具行 | 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和测试说明。

近期更新

| 版本 | 重点 | |---|---| | v4.7.4 | 独立侧车环境、心跳归属隔离与退出残留回收 | | v4.7.3 | 缺心跳扫描降频、健康接口响应与恢复说明 | | v4.7.2 | 更新停机保护、SDK 按钮回调、完整性恢复与配置地图 | | v4.7.1 | 命令确认回调修复与结果卡刷新 | | v4.7.0 | 任务布局、离线预览、额度归属与交互状态修复 | | v4.6.13 | 控制凭据移出命令行与最新 Hermes 源码验证 | | v4.6.12 | 可选卡片宽度与 Hermes 回复计时契约适配 | | v4.6.11 | 可选思考尾部窗口、后台任务观测信息与 CodeQL 更新 | | v4.6.10 | Hermes 0.21.5 适配、PM 运行环境安装与跟进卡片隔离 | | v4.6.9 | 群聊并发卡片隔离、紧凑单选按钮与新手 README |

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

贡献者

• V4.7.3: lanx214（#378）提供性能故障证据；ywarmy（#372）提供现场复测和恢复文档建议。
• V4.7.2: Nevoker (PR #373); DaveWang888 (#375), ffdxdynotable (#374), ywarmy (#372), jackwude (#370). 分别贡献 Python 3.14 修复、故障证据和配置引导建议；保留原提交作者。

• V4.7.1：baileyh8 根据用户提供的日志修复命令确认回调，见 PR #371；报告者尚未提供可公开署名。

• V4.7.0：延续 jackwude 在 #328 和 leavrcn 在 #333 提出的阅读体验需求。本轮提交作者为 baileyh8；保留全部历史代码作者、方案和现场证据记录。

• V4.6.13: 感谢 ffdxdynotable 在 #367 报告控制 token 的命令行暴露，提供 Termux 现场证据与私有文件方案。

• V4.6.12: 感谢 cbatbj / chenbing1 通过 PR #351 贡献分层卡片宽度配置与回归测试，保留原始提交和全部历史贡献。

• V4.6.11：感谢 leavrcn 在 #362 提供长思考复现与尾部窗口补丁方案；感谢 mouyong 的 #361 后台等待现场证据，以及 Dependabot 的 PR #363。保留代码作者与全部历史贡献记录。

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

安全与 License

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

MIT License。