feat(feishu): add Card V2 format for rich text+image messages

[YvanJiang]

Summary

Add Feishu Card V2 (Schema 2.0) support for rich messages combining text and images.

Relationship with existing features

• PR feat(Feishu): display the markdown table in the form of message cards #1009: `build_interactive_content()` for markdown table rendering
• This PR: Card V2 for combined text+image messages
• Both can coexist for different use cases

Changes

• `_build_card_v2_content()` - Build Card V2 structure with schema 2.0
• `_send_card_v2()` - Send Card V2 messages via interactive type
• `send_text()` - Updated to use Card V2 format
• `send_content_parts()` - Updated to use Card V2 for text+image responses
• `send()` - Updated to use Card V2 format

Benefits

• Better visual presentation for responses containing both text and images
• Configurable header colors (green, red, blue, orange, indigo, grey)
• Support for multiple images in a single card

Note

This PR modifies `channel.py` and may conflict with other PRs touching the same file. Suggest merging PR #3 first.

Related

Split from PR #1063

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[Leirunlin]

@YvanJiang Hi! Just a quick check:

• You mean suggest merging PR feat(feishu): add webhook support with signature verification #1230 before feat(feishu): add Card V2 format for rich text+image messages #1231 and feat(feishu): add simple HTTP notification endpoint #1232 right?
• Could you provide any test inputs that help quickly verify these newly added functions? I'm reviewing 1230, 1231, 1232 now. You can comment here or in each corresponding pr.

Thanks for your time.

[Leirunlin]

And please pass the checks and test. I will review these pr as soon as possible.

Thanks!

[YvanJiang]

Hi @Leirunlin, thanks for reviewing these PRs!

Merge Order Clarification:
You are correct - I meant PR #1230 → #1231 → #1232. There is no PR #3; that was a typo in my earlier message.

Dependency Chain:

• PR feat(feishu): add webhook support with signature verification #1230 (Webhook): Independent - adds `handle_webhook_event()` method
• PR feat(feishu): add Card V2 format for rich text+image messages #1231 (Card V2): Independent - modifies send methods only
• PR feat(feishu): add simple HTTP notification endpoint #1232 (Notify): Depends on BOTH feat(feishu): add webhook support with signature verification #1230 and feat(feishu): add Card V2 format for rich text+image messages #1231

Test Verification for Card V2 (PR #1231):

1. Configure Feishu channel with card header color:
   ```json
   {
   "channels": {
   "feishu": {
   "card_header_color": "blue"
   }
   }
   }
   ```
   Or via environment variable: `FEISHU_CHANNEL_CARD_HEADER_COLOR=blue`

2. Send a message with image to the bot:

   • Text: "Please analyze this image"
   • Attach any image

3. Expected result: Response appears as a Card V2 message with:

   • Blue header (configurable: green/red/blue/orange/indigo/grey)
   • Text content
   • Image displayed inline

Regarding the failing "run" check on #1231:
I've investigated and the pre-commit issues appear to be in unrelated files (`tests/unit/providers/test_openai_stream_toolcall_compat.py`). The Feishu channel code passes all checks.

I've also added comprehensive unit tests for the Card V2 methods (7 new tests covering `_build_card_v2_content`, `_send_card_v2`, and various template/color combinations). All 37 tests pass.

Suggested merge order:

1. Merge feat(feishu): add webhook support with signature verification #1230 first (webhook foundation)
2. Then feat(feishu): add Card V2 format for rich text+image messages #1231 (Card V2 format) - this PR
3. Finally feat(feishu): add simple HTTP notification endpoint #1232 (notification endpoint that uses both)

Please let me know if you need any additional information or changes!

[Leirunlin]

@YvanJian Hi! Thanks for your follow-up.

After discussion, we’ve decided not to merge #1229, #1230, #1232 right now. We’ll keep them open and continue discussing how best to introduce them into copaw, which will take more time and review.

As for 1231, it seem like features that can be merged sooner. We’re currently reviewing them and expect to provide feedback shortly.

[Leirunlin]

Just to confirm, I ran this PR locally and noticed:

• The background is white ✅
• The bullet points are blue ✅
• However, the title and subtitle are not showing ❌
• Currently, the key card_header_color is not set properly in config.json. As a result, once the service is restarted or any feishu-related setting is modified, the header_color config is lost.
• User can not choose the card format, so V2 become the only choice.

Is this expected behavior in your local testing? And if you don't mind, could you share some screenshots or conversation examples from your environment so I can try to reproduce your expectation?

[YvanJiang]

Review Comments Addressed

Hi reviewers, I've implemented the fixes for the Card V2 configuration issues:

Issues Fixed

1. Title/subtitle not showing ✅

   • Added card_header_enabled switch in the UI to control header display
   • Users can now explicitly enable/disable the card header

2. card_header_color config not persisted ✅

   • Fixed the backend put_channel() endpoint to use partial updates instead of full replacement
   • Previously, fields not included in the request were reset to defaults
   • Now the new config is merged with existing config, preserving all fields

3. Users cannot choose card format ✅

   • Added card_v2_enabled switch (default: true) allowing users to toggle between Card V2 and original format

UI Changes

Added a new "Card V2 Configuration" section in the Feishu channel drawer with:

• Enable Card V2 - Toggle rich card format
• Enable Card Header - Toggle header with title/color
• Header Title - Custom title input
• Header Color - Color selector (blue/green/red/orange/indigo/grey)

Backend Changes

Modified src/copaw/app/routers/config.py:

# Get existing config for merge (preserve fields not provided in request)
existing_config = getattr(config.channels, channel_name, None)
...
# Merge existing with new config
merged_config = {}
if isinstance(existing_config, dict):
    merged_config.update(existing_config)
elif hasattr(existing_config, "model_dump"):
    merged_config.update(existing_config.model_dump())
merged_config.update(single_channel_config)

This ensures backward compatibility and fixes the persistence issue for all channel types, not just Feishu.

Please review the changes. Thanks!

[Leirunlin]

Hi @YvanJiang,

It looks like the update hasn't been committed yet. If possible, could you please commit it based on the latest version of copaw? Also, attaching some expected outcome screenshots would be helpful for easier review.

Thanks!