这是「飞书对接」小专题的第2篇共5篇从《MCP实战手记十一MCP接飞书从机器人到事件订阅的三层深度接入》延伸对应正文第2层自建应用卡片消息。第1层群机器人只能POST一段文本店长看到的是一行字。但零售场景里店长要的是一张能看的卡销售数字、库存水位、补货按钮。文本到富卡片是飞书对接从能通知到能用的跨越。卡片怎么搭、按钮回调怎么接、以及生产最容易翻车的出站频控一次性讲清。卡片1.0还是2.0飞书卡片有两套协议字段结构不同卡片1.0顶层configheaderelements文本用text.tag lark_md。兼容最广本文实测跑通用这套。卡片2.0schema: 2.0body.elements文本用text.tag markdown。新项目可用迁移时注意字段差异。本篇示例用1.0先把链路跑通最重要。一张门店数据卡怎么搭把Tool查回来的结果渲染成 interactive card店长一眼看到重点还能直接点按钮{config:{wide_screen_mode:true},header:{title:{tag:plain_text,content:门店助手·查询成功},template:green},elements:[{tag:div,text:{tag:lark_md,content:**指令**查库存ST001\n\nSKU-1001库存23安全线50}},{tag:action,actions:[{tag:button,text:{tag:plain_text,content:补货},value:{sku:SKU-1001}}]}]}wide_screen_mode宽屏更适配桌面飞书template: green是卡片头配色action里的button带value点下去会把sku回传回去。按钮回调怎么接店长点补货飞书会发一个卡片回调事件action 触发服务端要处理它。两层都要配应用后台登记卡片回调地址和事件订阅同一个长连接/回调通道。handler 里读action.value按sku调补货工具再回一张新卡。// 卡片action回调节选自 dispatchif(补货.equals(action.getActionTag())){Stringskuaction.getValue().get(sku);// 取回按钮带的 skuRestockResultrstoreService.suggestRestock(storeCode,sku);apiClient.im().message().reply(buildCard(补货建议,r));// 回一张新卡}关键点按钮的value是状态通道别在卡片里塞大段业务数据——只带最小标识sku/storeCode真查还在服务端做。出站频控 退避重试生产必加飞书消息发送不是无限发有频控失败重试语义。裸发容易踩RateLimitException。技术4.4要求生产加退避重试// 退避重试飞书频控 瞬时失败指数退避 随机抖动intattempt0;while(attempt3){try{apiClient.im().message().send(req);break;}catch(RateLimitExceptione){longbase(1Lattempt)*500;// 0.5s / 1s / 2slongjitterThreadLocalRandom.current().nextLong(0,500);// 抖动错开重试Thread.sleep(basejitter);attempt;}}指数退避抖动是标配第1次等0.5s、第2次1s、第3次2s避免重试把飞书打得更限流。三个坑坑一卡片回调地址没配。按钮点了没反应多半是应用后台卡片回调地址没登记或和事件订阅通道没打通。坑二文本 tag 写错。1.0用lark_md、2.0用markdown写反了飞书直接按纯文本渲染markdown 符号全暴露。坑三卡片太长被截断。门店数据一多就堆宽屏模式也救不了超长内容。卡片是摘要视图细节走链接或二次查询别把整张报表塞进去。小结文本能通知卡片才能用。把Tool结果渲染成富卡片按钮回调店长从看一行字变成看卡点按钮办事。生产别忘了出站频控与退避重试——否则大促一波推送就能把你限流到掉消息。同专题推荐本文是「飞书对接」小专题的第2篇共5篇飞书长连接事件订阅实战个人本机 5 分钟跑通生产要补两块飞书卡片消息构建实战从文本到可交互富卡片← 当前这篇飞书用户身份与多租户数据隔离店长只看自己门店链接待补飞书事件安全签名校验与消息加解密链接待补钉钉接入实战与平台横向差距链接待补相关阅读《MCP实战手记十一MCP接飞书从机器人到事件订阅的三层深度接入》《MCP实战手记系列九生产化 MCP Server 的 6 层安全防护》身份透传底座《MCP实战手记系列八无状态之后的生产落地清单》Server 无状态可水平扩展《MCP实战手记系列十MCP Server 高可用实战》6工具复用 StoreService配套代码https://gitee.com/ethanliang2016/mcp-in-action模块11-feishutagv11