feishu-card-ws

飞书卡片 WS 长连接配置指南

适用范围

本 skill 适用于使用 @larksuiteoapi/node-sdk 通过 WebSocket 长连接模式接收 飞书交互式卡片回调的场景。这套模式经过 2026-04-12 的实战验证，是目前唯一稳定可用的方案。

核心约束（先读这里）

Lark Node SDK v1.60.0 的 WSClient 有以下已确认的限制：

限制	影响	应对
WSClient 不支持 CardActionHandler	start() 只接受 eventDispatcher 参数	用 EventDispatcher 注册 card.action.trigger
card 更新响应导致 200672	{ card: {...} } 经 base64 编码后飞书无法解析	所有操作只返回 toast
form_submit 按钮事件不到达	action_type: "form_submit" 走不同协议路径	使用普通 button，服务端缓存 select 值
monkey-patch handleEventData 破坏消息投递	干扰 SDK 内部分片合并逻辑	不要 monkey-patch

架构总览

用户发关键词 → im.message.receive_v1 → EventDispatcher → 发送卡片
用户选下拉   → card.action.trigger(select_static) → 缓存值 → return undefined
用户点按钮   → card.action.trigger(button) → 注入缓存值 → 业务处理 → return toast

三种交互全部通过同一个 EventDispatcher 路由，不需要任何 SDK 扩展或 monkey-patch。

---

第一步：卡片模板

下拉菜单 + 按钮组合

// ✅ 正确：普通 button + select_static，不用 form 容器
{
  tag: "select_static",
  name: "my_select_key",                          // 用于服务端缓存的 key
  placeholder: { tag: "plain_text", content: "请选择" },
  value: { action: "my_select_key" },              // value.action 也用于识别
  options: [
    { text: { tag: "plain_text", content: "选项1" }, value: "1" },
    { text: { tag: "plain_text", content: "选项2" }, value: "2" },
  ],
}

{
  tag: "button",
  name: "my_action_name",                          // 按钮名称
  text: { tag: "plain_text", content: "🟢 执行操作" },
  type: "primary",
  value: { action: "my_action_name" },             // value.action 用于路由
}

独立按钮（无下拉）

{
  tag: "button",
  name: "my_simple_action",
  text: { tag: "plain_text", content: "🔄 刷新" },
  type: "default",
  value: { action: "my_simple_action" },
}

反模式（不要这样做）

// ❌ form_container — form_submit 事件不通过 WS 到达
{ tag: "form", name: "myForm", elements: [select, { tag: "button", action_type: "form_submit" }] }

// ❌ action_type: "form_submit" — 事件完全不到达服务端
{ tag: "button", action_type: "form_submit", ... }

// ❌ 只靠 name 不设 value — 按钮的 action routing 依赖 value.action
{ tag: "button", name: "my_action" }  // 缺少 value