fix(feishu): render markdown tables and code blocks via CardKit 2.0 cards

[huangyoje]

Closes #9549. Closes #19035. Supersedes #23861.

Problem

Feishu's post-type md element does not render GFM tables and truncates multi-line fenced code blocks. The current behaviour (#20275, force-text fallback) avoids the blank-message symptom but leaks raw markdown source to the user — pipes, separators and code fences are visible as plain text.

#23861 partially addressed this by routing tables/code blocks to CardKit 2.0, but it does not handle the per-card table count limit (see below) and stalled in review. This PR is a more complete take.

Approach

Route content containing GFM tables or multi-line fenced code blocks to CardKit 2.0 interactive messages (schema: 2.0, tag: markdown), which render both natively. Plain markdown without tables/code stays in post/md as before.

Falls back to plain text when the interactive card is rejected (bot lacks card permission, malformed payload, etc.) so failures degrade gracefully — no regression vs current behaviour for misconfigured bots.

ErrCode 11310: per-card table cap

CardKit 2.0 caps the total number of GFM tables across an entire card at 5. Exceeding this triggers ErrCode 11310 (card table number over limit) and the API rejects the whole card.

The cap is per-CARD, not per-element — verified empirically against the live Feishu API on 2026-05-27:

layout	result
1 element × 5 tables	✓
1 element × 6 tables	✗ 11310
2 elements × (4+2) tables	✗ 11310
2 elements × (5+1) tables	✗ 11310
5 elements × 1 table each	✓
8 elements × 1 table each	✗ 11310

When content has more than 5 tables, _build_outbound_messages() splits it into multiple cards and send() iterates the resulting (msg_type, payload) list. Splits cut at section boundaries — the first paragraph break after the previous table block ends — so each table's heading and lead-in prose travel into the same card as the table itself, rather than being orphaned in the previous chunk.

Tests

tests/gateway/test_feishu.py::TestCardTableLimitSplitting (7 cases):

• table content routes to interactive card (not text)
• single card for ≤5 tables
• two cards for 6 tables (5 + 1)
• three cards for 12 tables (5 + 5 + 2)
• non-table content keeps post/text routing untouched
• prose between tables stays with the following table at split points
• multi-line fenced code block routes to interactive card

Full test suite (tests/gateway/test_feishu.py): 208 passed.

Migration notes

• Bots without card-send permission silently fall back to plain text (existing fallback path, extended for the interactive case). No new permission required vs post/md.
• edit_message remains on the single-payload path; streaming edits do not currently produce > 5 tables in a single chunk in practice.
• The single-content-line code block case (e.g. ```json\n{"x":1}\n```) intentionally stays in post/md because it renders fine there — only blocks with two or more code lines route to the interactive card. This preserves the existing test_send_splits_fenced_code_blocks_into_separate_post_rows behaviour.

[huangyoje]

Cross-linking #32488 (h/t @haozicnm), which targets the same issue (#9549) via the same Schema 2.0 markdown element approach. Wanted to surface the relationship and key trade-offs so reviewers can pick a direction.

Where this PR overlaps with #32488

Both route GFM tables / multi-line code blocks from force-text to a Schema 2.0 interactive card with a markdown element.

Where it differs

Table-count handling — load-bearing user-visible difference

	#32488	this PR (#33310)
Per-card limit	3	5
Excess tables	Wrapped into fenced code blocks (markdown source becomes user-visible)	Split into multiple cards (every table renders normally)
Limit source	"verified 2026-03 by openclaw + cc-haha" (no API trace)	Empirical against live Feishu API on 2026-05-27

I just re-ran the test against the live API:

N=3:  code=0   success
N=4:  code=0   success
N=5:  code=0   success
N=6:  code=230099  ErrCode 11310 'card table number over limit'

So the real per-card cap is 5, and #32488's _FEISHU_CARD_TABLE_LIMIT = 3 is overly conservative — it forces tables 4-5 to render as raw markdown source even though the API would accept them.

For >5 tables, #32488 keeps the first 3 as tables and dumps the rest as code blocks; this PR splits the content into N cards so every table still renders. Users get the same visual output regardless of how many tables the LLM produces.

Scope

This PR is intentionally narrow — one regex + table-count split + interactive→text fallback. #32488 also bundles three orthogonal changes that I think deserve separate PRs:

• HTML escape (& < >) for card content
• A markdown optimisation pipeline (heading downgrade, <br> spacing, blank-line compression)
• A rewrite of _build_markdown_post_rows to switch from tag: md to tag: text + inline parser

I tested HTML escape against a live card today — Feishu's CardKit 2.0 markdown element does not interpret <script>, <template>, or stray < / > as HTML; they all render as literal text without escaping. So the escape pass is defensive but not strictly required for safety on the outbound path.

Happy to defer

If maintainers prefer #32488's bundled approach, this PR can close. If a narrower fix is preferred, this one's ready. The single thing I'd advocate for either way is _FEISHU_CARD_TABLE_LIMIT = 5, not 3 — the 3 cap visibly degrades UX for content the API would otherwise accept.

[haozicnm]

Thanks for the thorough testing! I've confirmed your findings against the live API:

N=3: code=0   success
N=4: code=0   success
N=5: code=0   success
N=6: code=230099  card table number over limit

Updated #32488 to _FEISHU_CARD_TABLE_LIMIT = 5. Also fixed a bug where _build_table_card_payload was using the pre-sanitisation escaped variable instead of optimised, which meant the excess-table-to-codeblock conversion was silently discarded.

Agree on HTML escaping being defensive — Feishu's CardKit 2.0 markdown element treats </> as literal text. Keeping it for belt-and-suspenders since it's zero-cost.

Happy to coordinate on whichever approach maintainers prefer.

[huangyoje]

Rebased onto the latest main (no conflicts). Just noting this is still awaiting review — happy to address any feedback. The _FEISHU_CARD_TABLE_LIMIT = 5 finding has been independently confirmed by @haozicnm above and matches larksuite/openclaw-lark#46.

[teknium1]

Thanks for the focused investigation and for documenting the live five-table limit.

Problems

• The premise remains valid on current main: plugins/platforms/feishu/adapter.py:4524-4530 still routes detected GFM tables to a plain text payload. However, the PR changes gateway/platforms/feishu.py, which was moved to plugins/platforms/feishu/adapter.py by 5600105478ffde29d7566b45421b100eaa29c4ef.
• In the proposed multi-card loop, the interactive fallback uses the original chunk (gateway/platforms/feishu.py:1808 in this diff), not the failed card’s segment. A failure on a later card would resend the complete original response as plain text, duplicating earlier cards.

Suggested changes

• Port the change to the bundled plugin and pair each generated card with its source segment so fallback is per-card.
• Add a test where a later card in a >5-table response is rejected and verify its fallback contains only that card’s content.

Automated hermes-sweeper review.

[teknium1]

This fallback uses the full original chunk, even though the enclosing loop sends individual card payloads. If a later card from a >5-table response is rejected, this resends all earlier tables as raw text. Keep the source segment alongside each (msg_type, payload) result and fall back from that segment only.

[huangyoje]

Closing in favor of the post tag:md approach.

After running both solutions locally for a few weeks, post tag:md is the better fit for this codebase:

1. Feishu's server-side md renderer now handles GFM tables correctly — the original comment in the code ("post-type md elements do not render markdown tables") is outdated. Tables render fine via tag:md on current Feishu.
2. Streaming edit compatibility — hermes-agent uses message edit for streaming output. interactive cards don't support edit, which breaks the streaming UX or requires complex type-switching logic.
3. Quote/reply behavior — post messages show readable text when quoted; interactive cards only show "[Card message]", which degrades multi-turn conversations.
4. Simplicity — the fix is a 3-line routing change vs. building card JSON, handling per-card limits, multi-card splitting, and dedicated fallback paths.

The post tag:md approach has several community PRs in progress (#53453, #53355, #36877). Leaving this space to them.