中文 | English

Hermes 飞书流式卡片插件把 Hermes Agent Gateway 的飞书/Lark 回复变成一张持续更新的交互式卡片。思考过程、工具调用、最终答案、授权确认、选项选择、系统提示和运行统计会收束在卡片内，而不是散落成多条灰色原生消息。

它面向真实飞书使用场景：流式内容漏字/乱序、长表格和代码块变成 raw markdown、工具过程不可见、approval/clarify 需要手工回复、话题里卡片不更新、多 bot / 多 profile 难排查，以及 Hermes 升级后 hook 兼容不确定。

运行中	等待用户
失败	已完成

运行时 Header 跟随 Hermes 的真实工具动作更新，公开阶段输出继续在正文流式呈现；完成后只保留飞书原生回复引用，不再叠加一层 Hermes Agent 卡片标题。

• 一张持续更新的飞书卡片：thinking.delta、answer.delta、tool.updated、message.completed 会合并到同一张卡片。
• 运行态 Header 看见当前动作：Header title 保留用户自定义标题（默认 Hermes Agent），subtitle 将工具名与 tool.updated.detail 整理为实时动作摘要；完整命令留在 timeline。
• 主答案和过程分区：最终答案留在正文区，pre-tool answer、工具调用、系统 notice 进入“思考与工具” timeline。
• 卡片内交互：approval / clarify choices 渲染为按钮；/new、/reset、/undo、/model 等独立命令使用原生 interactive card。V4 的 /model 与 Hermes CLI 使用同一 Provider/模型列表，按 Provider → Model 两级选择，不再把全部模型挤进一个下拉框。
• 飞书话题一致体验：话题里的后续流式事件通过 reply_to_message_id 回到原卡片，系统提示不再重复外溢。
• 群聊诊断更清楚：/hfc status 会提示群内 chat binding 状态、绑定命令和 slash command 行为边界。
• 运维卡有明确边界：/hfc doctor 可给出诊断、两步安全修复和重启确认；私聊不比较操作者，群聊只允许发起者确认。运维卡不可用时继续使用 CLI，不改变普通流式卡的 layout 或 footer。
• 长内容保护：长 Markdown 表格、fenced code block 按结构边界拆分，降低 raw markdown 和半截围栏问题。
• 可诊断、可恢复：doctor、/hfc status、/health metrics、runtime import 检查、safe repair/restore/uninstall 覆盖常见故障。

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

安装脚本会安装或升级插件、读取/提示飞书凭据、写入本地 .env，并调用整合安装器：

python3 -m hermes_feishu_card.cli setup \
  --hermes-dir ~/.hermes/hermes-agent \
  --config ~/.hermes/config.yaml \
  --yes

安装完成后检查 sidecar：

python3 -m hermes_feishu_card.cli status --config ~/.hermes/config.yaml

更完整的安装包、Release 下载、Docker 和 PEP 668/uv 说明见 README-install.md 与 详细使用手册。

复制 config.yaml.example 到本地使用，不要提交真实凭据。

server:
  host: 127.0.0.1
  port: 8765
feishu:
  app_id: ""
  app_secret: ""
card:
  title: Hermes Agent
  footer_fields: [duration, model, input_tokens, output_tokens, context]

需要显示 Codex 订阅剩余额度时，把 subscription_usage 加入 footer_fields。插件仅在显式启用后，通过 Hermes 原生 fetch_account_usage("openai-codex") 查询；旧 Hermes、未登录或网络失败时静默隐藏，不影响卡片完成。

飞书凭据也可以放在配置同目录 .env：

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

多 bot、群聊绑定、bindings.chats、multi profile、profile-aware routing、footer 字段和 no-op client 说明见 详细使用手册。

确认 streaming.enabled 为 true，并让 Hermes 使用 edit transport。

确保 Hermes config.yaml 中启用流式编辑：

streaming:
  enabled: true
  transport: edit

不要设置 display.platforms.feishu.streaming: false。也不要把 display.show_reasoning 当成本插件必需开关；它可能把 reasoning 追加到最终回复里，反而干扰卡片流式体验。插件会直接处理 Hermes 的 thinking.delta / answer.delta。

Hermes v2026.4.23 起的旧版和 Hermes 0.13.0+/0.14.0/0.15.x/0.17.x/0.18.x 均有兼容策略；doctor 会优先读取 VERSION 或 Git tag v2026.4.23+，也会在版本 metadata 不完整或不可解析时用 gateway/run.py anchors 兜底。升级 Hermes 或插件后建议重新执行 setup 或 install --hermes-dir ... --yes。

已有 Hermes 容器优先使用：

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

默认路径：

docker-compose.example.yml 是适配示例，不是官方镜像。V3.8.6 起，Docker/source-stripped Hermes 缺少 VERSION 和 .git 时也会用 Gateway anchors 兜底判断 gateway_run_013_plus。

高频流式调优通常不需要改。遇到 DeepSeek burst、token-by-token 或长上下文压力时再看：

完整版本历史见 CHANGELOG.md，更长的历史说明保留在 详细使用手册。

Hermes Gateway
  -> minimal hook in gateway/run.py
     -> hermes_feishu_card.hook_runtime
        -> HTTP POST /events
           -> sidecar server
              -> CardSession state
              -> Feishu CardKit send/update
              -> retry / coalescing / metrics / /health

这是 sidecar-only 设计：Hermes hook 保持 fail-open，飞书发送、更新、状态机、重试、诊断都在 sidecar 中运行。历史 V2 实现归档在 legacy/，不是 active runtime。

• 详细使用手册：中文 / English
• 安装包说明：README-install.md
• 架构说明：中文 / English
• 事件协议：中文 / English
• 安装安全：中文 / English
• 迁移说明：中文 / English
• 端到端验证：中文 / English
• 发布准备：中文 / English
• 测试说明：中文 / English
• 项目维护 Wiki：docs/wiki

• gischuck - PR #12 Accept-Encoding 修复
• gischuck - PR #76 思考与工具 timeline 体验建议与实现探索
• fengs2021 - PR #17 锁架构优化与更新间隔改进
• colinaaa - PR #87 WebSocket interaction.select clarify/approval 卡片交互支持
• colinaaa - PR #88 话题群 message_id 复用下第二轮消息新卡片修复
• colinaaa - PR #91 cron 结果回到飞书话题群原线程的 thread_id 路由修复
• zayn-0101 - PR #77 cron deliver=origin/all 路由意图卡片投递修复
• Zanetach - PR #84 卡片 progress-status 路由与 .env 白名单扩展的 profile 环境支持（V3.9.0）
• colinaaa - PR #93 打断任务后将旧卡片可靠收束为终态；PR #97 保留完整完成答案（V3.9.1）
• charles5g - PR #98 模型选择回调异步化与原卡片状态更新（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.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 生产诊断与修复

不要把 App Secret、tenant token、真实 chat_id、未脱敏截图提交到仓库。效果图仅用于展示卡片体验，生产凭据应保存在本机配置或环境变量中。

MIT License，详见 LICENSE。