If you use Hermes in Feishu, you definitely need to install this plugin. It converts Hermes responses into beautiful Feishu cards. Without it, Feishu’s own markdown support isn’t great—it can’t render tables, for example. In short, it’s a very useful plugin; just hand it to Hermes for installation. https://github.com/baileyh8/hermes-feishu-streaming-card…

baileyh8/hermes-feishu-streaming-card Source: https://github.com/baileyh8/hermes-feishu-streaming-card

Hermes Feishu Streaming Card Plugin 中文 | English

Hermes Feishu Streaming Card cover

The Hermes Feishu Streaming Card Plugin turns Hermes Agent Gateway’s Feishu/Lark replies into a continuously updated interactive card: thinking process, tool calls, final answer, authorization confirmation, option selection, and runtime statistics all converge in a single Feishu card, rather than being split into spamming gray native messages.

It specifically addresses the most common pain points when connecting Feishu with Hermes: missing/out-of-order streaming content, long tables and code blocks rendered as raw markdown, invisible tool call process, approval/clarify requiring manual replies, difficult sidecar troubleshooting, complex multi-bot/multi-profile operations, and uncertain hook compatibility after Hermes upgrades.

Feishu streaming card real effect screenshot

Project Highlights

• Streaming card experience: thinking.delta, answer.delta, tool.updated, message.completed are aggregated into a single Feishu card, reducing spam and context fragmentation.
• In-card interaction: Hermes approval / clarify choices are rendered as Feishu buttons. After clicking, the original task continues and the original card keeps updating.
• Better long content handling: Long Markdown tables and fenced code blocks are split along structural boundaries, reducing issues with Feishu raw markdown and truncated code fences.
• Multi-bot / multi-profile: Supports multiple Feishu bots, multiple Hermes profiles, group chat binding, bot/profile titles, and route diagnostics.
• Sidecar-only architecture: Hermes hook fail-open; Feishu sending/updating, state machine, retry, and health checks all run independently in the sidecar.
• Installation and release friendly: Supports one-line installation, release packages, doctor diagnostics, start/status/stop process management, and safe restore/uninstall.

Real Pain Points Solved

V3.6.1 Compatibility Patch

V3.6.1 fixes issue #47: When the Hermes VERSION file is written with a semver without a v prefix (e.g., 0.15.1), doctor --explain will no longer falsely report “unsupported”. 0.15.x / v0.15.x will continue to follow the new Hermes gateway_run_013_plus path, provided the necessary anchor in gateway/run.py still exists.

Full release notes at V3.6.1 release notes.

V3.6.0 Operations Enhancement

V3.6.0 addresses real-world troubleshooting and maintenance scenarios after online use: when Hermes upgrades, hook state anomalies, media/file messages enter a conversation, or one sidecar serves multiple profiles/bots, users can quickly determine “what’s broken, can it auto-repair, which route to verify”.

• Diagnostics readable and machine-parseable: doctor --explain gives a human-readable troubleshooting summary; doctor --json outputs config, sidecar, Hermes, streaming, install_state, and recommendations.
• Install state self-recovery: Added repair --hermes-dir ... --yes and setup --repair to fix only verifiable manifest/backup states; refuses to overwrite user changes.
• Media/files safer: Recognizes Hermes structured attachments / files / media_files / image/audio/video objects; card retains summary while not suppressing Hermes native media/file delivery path.
• Multi-Profile better troubleshooting: smoke-feishu-card --profile-id, bots test --profile-id, CLI status, and /health.routing.profiles all display routing state per profile.
• Compatibility matrix clearer: Automated coverage of Hermes v2026.4.23, v2026.5.7, v2026.5.16+, v2026.5.29, 0.13.x, 0.14.x, 0.15.x and versions with/without v prefix hook strategy.

Full release notes at V3.6.0 release notes; historical roadmap at docs/roadmap-v3.6.0.md.

What V3.6.0 Solves

V3.5.x Feature Baseline

Interaction Capabilities

• Added Feishu button interaction loop: interaction.requested renders buttons, /card/actions records selection, Hermes hook polls /interactions/{interaction_id} then continues execution.
• Authorization/option buttons use Feishu JSON 2.0 button + behaviors.callback to avoid old-style action container update failures.
• approval / clarify hook transparently passes through Hermes event loop; interaction requests and streaming deltas share the same message send lock, reducing event out-of-order.

Streaming Stability

• Fixed issue #41: multiple replies and new Hermes streaming flow continue card updates; final answer no longer falls back to native text from the second message.
• Fixed issue #39: when message.completed.answer is empty, no longer clears content already shown via answer.delta; cards after DeepSeek V4 Pro tool calls no longer end up empty.
• Fixed issue #31: PATCH serialization for the same Feishu card prevents old snapshots overwriting new content.
• Fixed issue #25: Hermes v2026.5.7’s event_message_id used as explicit message_id ensures message.started and message.completed land on the same fallback card.
• HTTP event sending for the same message is locked by message id; sequences from multi-threaded Hermes callbacks do not step on each other.
• answer.delta / thinking.delta preserve original boundary spaces, avoiding broken Chinese, English, and code fragments.
• thinking.delta(mode=append_block) appends complete thinking fragments, fixing missing words, truncation, and concatenation in the thinking process.
• Sidecar quickly ACKs non-terminal events; card PATCH merge updates with refresh interval reduced to 0.2s; terminal events get priority card landing.
• Suppress native resend after queued follow-up completion to avoid “card done but gray native message appears below”.

Long Content & Rendering

• Long Markdown tables exceeding MAIN_CONTENT_CHUNK_CHARS are split with repeated table headers, maintaining valid table structure.
• Fenced code blocks that are too long are split into multiple complete fenced blocks, avoiding half-code fences in Feishu.
• Retains V3.3.0’s Feishu 5-table limit protection: automatically truncates and prompts when exceeded.

Compatibility & Installation

• Hermes 0.13.0+/0.14.0/0.15.x, v2026.5.16+ use gateway_run_013_plus.
• Older Hermes (v2026.4.23 to v2026.4.x / 0.12.x) continue using legacy_gateway_run.
• doctor outputs version_source, version, hook_strategy, compatibility, anchor/anchors, and reason for pre-install confirmation.
• After upgrading the plugin, hooks must be reinstalled: run install --hermes-dir ... --yes so Hermes uses the hook matching the current version.
• Handles PR #42: cron card routing prioritizes job['deliver'] and scheduler-parsed Feishu target.
• Multi-profile/multi-bot experience completed: issue #23, per-bot/profile title, cron final cards, attachment summaries + native media delivery, reply card context.
• V3.6.0 further added profile-specific smoke, routing profile diagnostics, structured attachment summaries, and safe repair.

Configuration & Operational Safety

• When a .env file exists in the same directory as the --config configuration file, it is automatically read for FEISHU_APP_ID, FEISHU_APP_SECRET, HERMES_FEISHU_CARD_HOST, HERMES_FEISHU_CARD_PORT.
• Real process environment variables take precedence over .env in the same directory.
• Multi-profile mode requires each profile to explicitly configure Feishu credentials; top-level environment variables do not override profile credentials.
• Without credentials, sidecar uses a no-op client that only maintains local state and does not send real Feishu cards; /health.routing.bot_count can confirm whether real bots are loaded.

One-Line Installation

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

The install script will automatically install/upgrade the plugin, read or prompt for Feishu credentials, write ~/.hermes/.env, and call the integrated installer:

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

After installation, you can check the sidecar status:

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

Common environment variables:

You can also download hermes-feishu-card--macos.tar.gz, hermes-feishu-card--linux.tar.gz, or hermes-feishu-card--windows.zip from Release, extract, and run the included install.sh / install.ps1. Full installation package instructions at README-install.md.

Manual Installation

git clone https://github.com/baileyh8/hermes-feishu-streaming-card.git
cd hermes-feishu-streaming-card
pip install -e ".[test]"
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx
python3 -m hermes_feishu_card.cli setup --hermes-dir ~/.hermes/hermes-agent --yes

setup is an integrated installer: auto-generates config, checks Hermes version and code anchors, installs hook, starts sidecar, and performs health checks. It supports older Hermes from v2026.4.23, as well as Hermes 0.13.0+/0.14.0/0.15.x and v2026.5.16+ new anchors; Hermes VERSION can include or omit the v prefix.

If you use Hermes default directory, you can also put credentials in ~/.hermes/.env:

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

Then use:

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

V3.6.1 will continue to automatically read ~/.hermes/.env from the same directory as ~/.hermes/config.yaml.

Upgrade

Upgrading from V3.2.x/V3.3.0/V3.4.x/V3.5.x/V3.6.0 to V3.6.1 is backward compatible; single-profile configuration requires no changes. If upgrading from V3.6.0 to V3.6.1, typically just update the plugin and re-run doctor; only reinstall hook if the hook strategy changes.

# 1. Stop sidecar
python3 -m hermes_feishu_card.cli stop --config ~/.hermes_feishu_card/config.yaml

# 2. Update code
cd /path/to/hermes-feishu-streaming-card
git checkout v3.6.1
pip install -e ".[test]" --upgrade

# 3. Diagnose Hermes hook strategy and anchors
python3 -m hermes_feishu_card.cli doctor \
  --config ~/.hermes_feishu_card/config.yaml \
  --hermes-dir ~/.hermes/hermes-agent

# 4. Reinstall hook
python3 -m hermes_feishu_card.cli install --hermes-dir ~/.hermes/hermes-agent --yes

# 5. Start sidecar
python3 -m hermes_feishu_card.cli start --config ~/.hermes_feishu_card/config.yaml

doctor determines Hermes support from VERSION or Git tag v2026.4.23+. Hermes 0.13.0+/0.14.0/0.15.x and v2026.5.16+ should hit gateway_run_013_plus; older Hermes should hit legacy_gateway_run. If doctor --explain indicates auto-repair possible, run repair --hermes-dir ... --yes first, then reinstall hook.

Core Features

• Feishu streaming card: message.started, thinking.delta, answer.delta, tool.updated, message.completed, message.failed converge in a single card.
• Authorization/option buttons: Hermes approval and clarify choices displayed as buttons within the same card; clicking continues the original task.
• Multi-bot and group chat binding: bots.items registers multiple Feishu bots; bindings.chats routes by chat_id; group_rules reserves group chat strategy.
• Multi-profile in-process isolation: One sidecar serves multiple Hermes profiles, using profile_id:message_id to isolate sessions.
• Profile / Bot card title: Titles can be set globally, per profile, or per bot; bot level takes precedence.
• Cron final cards and reply context: Cron tasks can send final cards; reply card context retains necessary context.
• Attachment summaries and native media delivery: Card shows attachment summaries; hook does not suppress Hermes native media/file delivery path.
• DeepSeek reasoning chain compatibility: Filters ``` / ` `` and / tags.
• Tool call tracking: Accumulates tool call count and current status of each tool.
• Runtime statistics footer: Shows duration, model, token, context ratio; non-terminal cards show rotating “generating” state.
• Fault isolation: When sidecar is unavailable, hook fails open; Hermes native text continues to run.
• Safe install/restore: Installer fails closed; restore/uninstall detects file changes and refuses to overwrite.

Configuration

Copy config.yaml.example to local use; do not commit real credentials.

Single Profile Minimal Configuration

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]

Single Profile + Multi-Bot / Group Chat

server:
  host: 127.0.0.1
  port: 8765
feishu:
  app_id: ""
  app_secret: ""  # fallback
bots:
  default: default
  items:
    sales:
      app_id: "cli_sales_xxx"
      app_secret: "xxx"
    support:
      app_id: "cli_support_yyy"
      app_secret: "yyy"
bindings:
  fallback_bot: default
  chats:
    oc_5cc6a25d8815790fa890dd0226005e83: sales
group_rules:
  enabled: false
card:
  title: Hermes Agent
  footer_fields: [duration, model, input_tokens, output_tokens, context]

Multi-Profile

server:
  host: 127.0.0.1
  port: 8765
profiles:
  engineering:
    feishu:
      app_id: "cli_eng_xxx"
      app_secret: "xxx"
    bots:
      default: default
      items:
        default:
          app_id: "cli_eng_xxx"
          app_secret: "xxx"
    bindings:
      fallback_bot: default
      chats: {}
  sales:
    feishu:
      app_id: "cli_sales_xxx"
      app_secret: "xxx"
    bots:
      default: default
      items:
        default:
          app_id: "cli_sales_xxx"
          app_secret: "xxx"
    bindings:
      fallback_bot: default
      chats: {}
card:
  title: Hermes Agent
  footer_fields: [duration, model, input_tokens, output_tokens, context]

In multi-profile mode, FEISHU_APP_ID / FEISHU_APP_SECRET do not override feishu configuration within profiles. footer_fields supports duration, model, input_tokens, output_tokens, context.

Feishu App Configuration

export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx
# Real Feishu smoke test
python3 -m hermes_feishu_card.cli smoke-feishu-card \
  --config config.yaml.example \
  --chat-id oc_xxx

If credentials are not configured, the sidecar uses a no-op client; suitable for local unit tests, but will not send real Feishu cards. Before actual integration testing, check:

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

Confirm /health.routing.bot_count is greater than 0 and last_route_error is empty.

Hermes Gateway Streaming Configuration

Ensure streaming is enabled in Hermes config.yaml:

streaming:
  enabled: true
  transport: edit

Do not set display.platforms.feishu.streaming: false. Also, do not treat display.show_reasoning as a required switch for this plugin; it may append reasoning code blocks in the final reply, interfering with the card streaming experience. If the model only returns a final answer without thinking deltas, the card will directly show the final answer.

CLI Commands

Architecture

Hermes Gateway
└─ minimal hook in gateway/run.py
   └─ hermes_feishu_card.hook_runtime
      └─ HTTP POST /events ——→ sidecar server
         ├─ CardSession state machine
         ├─ render_card() card rendering
         ├─ Feishu CardKit HTTP client (implemented)
         ├─ tenant token / send / update
         ├─ throttling, merging, retry, lock, diagnostics
         └─ /health metrics

Hermes hook forwards events to sidecar with fail-open behavior. The sidecar holds the full session state and Feishu boundaries, allowing independent testing, restart, and diagnostics. Historical implementations are archived in legacy/ (installer_v2.py, gateway_run_patch.py, patch_feishu.py, etc.) and are not active runtime; the current main line is hermes_feishu_card/. Migration notes at docs/migration.md.

FAQ

• Card has no thinking / not streaming: Check streaming.enabled: true and streaming.transport: edit; confirm the model actually outputs thinking.delta.
• No card in real Feishu: Check if credentials are loaded into sidecar; without credentials, it’s a no-op client. V3.6.1 reads .env from config’s directory; real environment variables still take precedence.
• Card stuck on “thinking…”: Look at /health.diagnostics.last_terminal_event and feishu_update_failures to see if terminal event arrived and Feishu PATCH succeeded.
• Gray native text appearing: Usually indicates sidecar did not successfully receive or update terminal state; V3.5.x added queued follow-up suppression and terminal priority update.
• Missing words/truncation in thinking process: V3.5.x fixed with ordered send, append_block, PATCH merge, and terminal priority; if still occurring, first check /health.metrics.feishu_update_failures.
• Long tables/code showing as raw markdown: V3.5.x structurally splits them; if still abnormal, reduce single table column width or code block length.
• Duplicate cards: Check /health metrics (events_received, events_applied, feishu_send_successes). In multi-profile, session key is profile_id:message_id.
• Multi-profile routing uncertain: Run status --config ... and check routing.last_route, profile..events, profile..last_profile_source; then use smoke-feishu-card --profile-id ... or bots test --profile-id ... for targeted verification.
• No cards after Hermes 0.13.0+/0.14.0/0.15.x upgrade: First run doctor --config ... --hermes-dir ... to confirm hook_strategy is gateway_run_013_plus; then reinstall hook as needed.
• Restore fails: restore/uninstall will refuse to overwrite if file changes are detected. First run doctor --explain to see manifest/backup/run.py state; if auto-repair is indicated, run repair --hermes-dir ... --yes; otherwise, back up first then manually confirm differences.
• Just want to test local sidecar: Can use no-op client for tests; real Feishu smoke requires real App ID/Secret and chat id.

Version History