feat(feishu): CardKit streaming cards and SSE hang fixes (#287)

[39499740]

Summary

Implements CardKit streaming card API for smooth typewriter-style output in Feishu (Lark), and fixes multiple SSE stream hanging issues that caused the bot to become unresponsive.

Closes #287

What's New

CardKit Streaming Card Integration

• create_card_entity() — Create CardKit card entities for streaming
• send_card_by_card_id() — Send cards by card_id via IM API
• stream_card_content() — Element-level streaming content push (500ms refresh interval)
• set_card_streaming_mode() — Enable/disable streaming mode on cards
• update_cardkit_card() — Full card content update after streaming completes

Dual-Path Design with Graceful Degradation

1. CardKit path (preferred): create → stream → close streaming → final update
2. IM Patch path (fallback): send interactive card → patch updates
3. Plain text (last resort): simple text message

Streaming Flush Control

• asyncio.Lock-protected _flush_stream() — prevents sequence conflicts
• _SerialPatchQueue — serializes IM patch requests to prevent out-of-order overwrites
• Heartbeat refresh task — periodic card updates during tool execution

Bug Fixes

1. Anthropic SSE Stream Hang (Root Cause)

AnthropicClient.stream() waited indefinitely for a message_stop event that Zhipu's Anthropic-compatible API never sends. After receiving message_delta with stop_reason, the aiter_lines() loop hung forever.

Fix: Break immediately on stop_reason in message_delta, before waiting for message_stop.

2. CancelledError Not Caught in Heartbeat Cleanup

In Python 3.9+, asyncio.CancelledError inherits from BaseException, not Exception. The except Exception: pass block in the heartbeat task cleanup did not catch it, causing the exception to propagate and skip the final card update entirely.

Fix: Changed to except (Exception, asyncio.CancelledError).

3. httpx System Proxy Interference

httpx.AsyncClient auto-detects macOS system proxy settings, which can interfere with long-lived SSE connections to LLM APIs.

Fix: Added proxy=None to all httpx.AsyncClient constructors.

4. httpx aclose() Indefinite Blocking

When a streaming connection was terminated early (via break), httpx.AsyncClient.aclose() could hang indefinitely waiting for the server to finish sending.

Fix: Wrapped aclose() in asyncio.wait_for(..., timeout=5.0) for all client classes.

5. OpenAI/Gemini SSE Stream Termination

• OpenAICompatibleClient: Only broke on [DONE], not on finish_reason. If a provider sends finish_reason without [DONE], the stream hangs.
• GeminiClient: [DONE] was only continued (not breaking), and finishReason was recorded but never acted on. The client relied solely on HTTP connection close.

Fix: Added finish_reason break protection to both clients, matching the Anthropic client's defensive pattern.

Files Changed

File	Changes
backend/app/api/feishu.py	CardKit streaming integration, flush control, CancelledError fix
backend/app/api/websocket.py	Stream return logging
backend/app/services/feishu_service.py	5 new CardKit API methods
backend/app/services/feishu_ws.py	WebSocket proxy bypass
backend/app/services/llm_client.py	SSE break protection (all 3 clients), proxy=None, aclose timeout

Testing

Provider	Mode	Model	Result
Zhipu	Anthropic-compatible	GLM	✅ Streaming cards work end-to-end
Zhipu	OpenAI-compatible	GLM	✅ Streaming cards work end-to-end
Google	Gemini native	Gemini 2.5 Flash	✅ Streaming cards work end-to-end

[wisdomqin]

Great work! The CardKit streaming integration is well-structured with a solid 3-tier fallback design (CardKit -> IM Patch -> plain text), and the SSE hang fixes address real root causes across all three LLM clients. Approving for merge.

We will address the following in a follow-up commit after merge:

1. Add lark-oapi to requirements.txt
2. Scope the websockets proxy patch (avoid global monkey-patch)
3. Add tool call status display to the CardKit streaming path
4. Add a size cap to _lark_clients cache to prevent unbounded growth