Hermes Gateway 飞书流式卡片插件 — 基于 CardKit v2.0 的进程内流式消息卡片。
灵感来源于 openclaw-lark 和 hermes-feishu-streaming-card。
- 流式输出 — AI 回复实时显示在交互卡片中，打字机效果
- 流式卡片 — 按事件顺序在单张卡片内动态渲染思考、工具调用、回答内容
- 思考过程 — 显示模型的推理/思考内容
- 工具调用 — 实时展示工具调用状态和进度，含标准图标和结果/错误块
- CardKit v2.0 — 使用飞书 CardKit 流式 API；卡片创建失败时交回 Hermes Gateway 默认回复
- 终态卡片 — 完成后展示完整结果，含 token 用量、耗时、上下文信息
- 卡片样式 — 可配置卡片 header、footer 显示开关及正文字字大小
- 消息保护 — 消息被删除/撤回后自动终止更新，避免无效 API 调用
- 图片解析 — 自动识别 markdown 图片引用，下载上传后替换为飞书 img_key
- 中断处理 — 处理
/stop命令和消息打断，展示中断状态卡片并自动开启新会话 - Cron 卡片推送 — 定时任务结果以飞书卡片形式推送，保留 Markdown 渲染
- 后台任务卡片推送 —
/background（/btw）任务完成后以卡片形式推送，支持话题内回复 - 多语言 — 卡片文本（状态、工具面板、思考标签等）内置中英双语，根据飞书客户端语言自动切换
插件按事件到达顺序在卡片内动态渲染思考、工具调用、回答元素，多轮对话内容按实际顺序展示。
当长对话或工具调用步骤过多导致卡片元素接近飞书 200 上限时，自动拆分为多张卡片：旧卡片封存（数据完整），新卡片继续输出，仅最后一张卡片带页脚。单个工具面板步骤过多时也会按步骤边界拆分。
- Hermes
>= 0.14.0（2026.5.16）已安装并配置飞书平台 Python >= 3.11lark-oapi >= 1.4.0— 飞书/Lark 官方 Python SDKPyYAML >= 6.0— YAML 解析库- 飞书应用权限：消息卡片（CardKit）读写、消息发送与回复、图片上传
完整安装步骤见 INSTALL.md。
让 Hermes 对接的 AI agent 读取安装指南后自动执行：
curl https://raw.githubusercontent.com/Cheerwhy/hermes-lark-streaming/main/INSTALL.md
在 ~/.hermes/config.yaml 中添加：
streaming:
enabled: true凭据按以下顺序解析：
| 优先级 | 来源 | 变量 |
|---|---|---|
| 1 | 环境变量 | FEISHU_APP_ID / FEISHU_APP_SECRET（或 LARK_APP_ID / LARK_APP_SECRET） |
| 2 | 配置文件 | ~/.hermes/config.yaml 中的 feishu 或 lark 区段 |
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx通过以下配置项自定义流式卡片和完成态卡片的外观：
streaming:
enabled: true
width_mode: default # 卡片宽度模式：default / compact / fill，默认 default
header:
enabled: true # 卡片 header，默认 false
body:
text_size: normal_v2 # 回答正文文字大小，默认 normal_v2
footer:
enabled: true # 卡片 footer，默认 true
text_size: notation # Footer 文字大小，默认 notation
fields:
- [status, elapsed, context, model]
show_label: false
panel_expanded: false # 完成态面板保持展开，默认 false
display:
platforms:
feishu:
show_tool_use: true # 展示流式和完成态卡片中的工具调用面板，默认 trueHeader（streaming.header.enabled）：控制卡片是否显示顶部状态栏。开启后根据状态自动着色 — 流式中蓝色、完成绿色、中断/错误红色。默认关闭。
Footer（streaming.footer.enabled）：控制完成态卡片是否显示底部元数据栏。默认开启。
文字大小（body.text_size / footer.text_size）：有效值包括 heading、normal、normal_v2、notation 等。详见飞书文档。
Footer 字段（footer.fields）：二维数组，每个子数组为一行，字段间用 · 连接。
| 字段 | 说明 | 有标签 | 无标签 |
|---|---|---|---|
status |
完成状态 | ✅ Completed |
✅ Completed |
elapsed |
耗时 | Elapsed 12.3s |
12.3s |
model |
模型名称 | deepseek-v4-flash |
deepseek-v4-flash |
tokens |
Token 用量 | ↑ 1.2K ↓ 500 |
↑ 1.2K ↓ 500 |
context |
上下文窗口用量 | Context 50K/200K (25%) |
50K/200K (25%) |
显示标签（footer.show_label）：是否展示字段标签（如 "Elapsed"、"Context"）。默认：false。
面板展开（panel_expanded）：完成态卡片中推理面板和工具面板默认折叠，设为 true 保持展开。
卡片宽度（streaming.width_mode）：控制卡片宽度模式，可选 default、compact、fill。默认：default。
工具调用面板（display.platforms.feishu.show_tool_use）：控制是否展示工具调用面板。平台级配置优先于全局 display.show_tool_use，默认：true。该配置会在运行时重新读取。
HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m hermes_lark_streaming verify # 验证兼容性（不修改文件）
$HERMES_PYTHON -m hermes_lark_streaming install # 注入 hook
$HERMES_PYTHON -m hermes_lark_streaming uninstall # 移除 hook
$HERMES_PYTHON -m hermes_lark_streaming restore # 从备份恢复原始文件
$HERMES_PYTHON -m hermes_lark_streaming status # 查看状态（含 Hermes Python/安装目录检测）cd hermes-lark-streaming
git pull
HERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m pip install -e .
$HERMES_PYTHON -m hermes_lark_streaming uninstall # 先移除旧注入
$HERMES_PYTHON -m hermes_lark_streaming verify
$HERMES_PYTHON -m hermes_lark_streaming install
hermes gateway restartHERMES_PYTHON=~/.hermes/hermes-agent/venv/bin/python3
$HERMES_PYTHON -m hermes_lark_streaming uninstall
$HERMES_PYTHON -m pip uninstall hermes-lark-streaming插件通过 AST 注入在 gateway/run.py 和 cron/scheduler.py 插入 hook 调用，所有业务逻辑在 hermes_lark_streaming 包内完成。
消息处理流程：
用户发送消息
→ 创建卡片会话
→ 流式更新（工具状态、文本增量 — 节流调度）
→ 图片 URL 异步解析替换
→ 终态卡片（token/耗时/上下文）
若消息被删除/撤回，自动终止后续更新。
中断处理：
/stop终止 — 用户主动停止，卡片展示中断状态：
- 消息打断 — 用户发送新消息打断正在处理的回复，旧卡片展示中断状态，并自动为新消息创建新的流式卡片：
install会修改~/.hermes/hermes-agent/gateway/run.py和cron/scheduler.py，自动创建.hermes_lark.bak备份- Hermes 更新后需重新运行
verify+install - 插件与 Hermes 内置飞书适配器互补工作：插件负责流式卡片，内置适配器负责消息收发
- 仅对飞书平台生效，其他平台不受影响
感谢以下贡献者的 Issue 和 PR：
