| name | feishu-interactive-cards |
| description | Interactive cards for confirm dialogs, input forms, and multi-step progress trackers.
Use it when:
You need to acquire consent for dangerous/non-recoverable operations;
Structural information are to be acquired from user or sensitive information;
Entering Multistage task or complex plan and you need to provide realtime update.
|
Interactive Cards
Three card types — each sends a card that updates itself inline after the user interacts.
Confirm Card — feishu_im_send_confirm
Present a yes/no decision. Use blocking=true to wait for the click before continuing; blocking=false (default) returns immediately and the result arrives in the next feishu_im_watch as card_callbacks[].action ("confirm" / "cancel").
Watch-loop warning: Do NOT use blocking=true inside the watch loop — it will block all incoming messages while waiting. Always use blocking=false and handle the callback in the next feishu_im_watch cycle.
| Param | Default | Notes |
|---|
title | required | Card heading |
body | — | Markdown body text |
confirm_label | 确认 | Confirm button text |
cancel_label | 取消 | Cancel button text |
blocking | false | Wait for click before returning |
timeout_seconds | 3600 | Card expires after N seconds |
Form Card — feishu_im_send_form
Collect structured input via text fields. Use blocking=true to wait for submission; blocking=false delivers form_value in the next feishu_im_watch as card_callbacks[].form_value.
Each field: name (result key), label, placeholder?, required?, hidden? (password input — shows ****** after submit).
| Param | Default | Notes |
|---|
title | required | Card heading |
body | — | Markdown text above the fields |
fields | required | Array of field definitions (min 1) |
submit_label | 提交 | Submit button text |
blocking | false | Wait for submission before returning |
timeout_seconds | 3600 | Card expires after N seconds |
Progress Card — feishu_im_send_progress + feishu_im_patch_progress
Show a multi-step task with a live progress bar and a Stop button. Send once, then patch after each step. Pass current_step = steps.length to mark complete (green header, 100%).
Each step: label + optional detail (expandable summary — useful to fill in on patch once a step is done).
feishu_im_send_progress params:
| Param | Notes |
|---|
receive_id | Destination (ou_xxx or oc_xxx) |
title | Card heading (cached server-side — do not repeat on patch) |
steps | Ordered array of { label, detail? } (cached server-side — do not repeat on patch) |
current_step | 0-based active step; default 0 |
feishu_im_patch_progress params — title and steps are cached; only pass what changes:
| Param | Notes |
|---|
message_id | Returned by feishu_im_send_progress |
current_step | 0-based active step; steps.length = completed |
step_updates | Optional [{ index, detail }] — update detail text on specific steps |
Stop button: The card shows a red Stop button while in progress. If the user presses it:
- The card immediately updates to grey "已停止"
- The stop event is queued for
feishu_im_watch
- The next
feishu_im_patch_progress call returns { result: "User asked to stop — abort the task." } — abort and inform the user
Lifecycle
| Card | Active | After interaction | Timeout |
|---|
| Confirm | Blue, two buttons | Buttons removed, action shown | Grey 已失效 |
| Form | Blue, input fields | Fields disabled, values shown | Grey 已失效 |
| Progress | Blue, step list + bar + Stop button | Patched manually; Stop → grey 已停止 | No auto-expiry |
Custom Raw Cards
Do not write raw card JSON manually — it is error-prone. Instead, find a working example in cards-package/CARDS-REFERENCE.md, then check field details in cards-package/LARK-CARD-SCHEMA.md. (Both files are in the same directory as this SKILL.md.)
