飞书卡片 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。

第一步：卡片模板

下拉菜单 + 按钮组合

typescript
// ✅ 正确：普通 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 用于路由
}

独立按钮（无下拉）

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

反模式（不要这样做）

typescript
// ❌ 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

第二步：EventDispatcher 注册

在 WSClient 启动时，将 card.action.trigger 和消息事件一起注册到 EventDispatcher：

typescript
import * as lark from "@larksuiteoapi/node-sdk";

// select 值缓存（放在模块顶层）
const selectCache = new Map<string, { value: string; expiresAt: number }>();

function cacheSelect(operatorId: string, key: string, value: string): void {
  selectCache.set(`${operatorId}:${key}`, { value, expiresAt: Date.now() + 600_000 });
}

function getCachedSelect(operatorId: string, key: string): string | null {
  const entry = selectCache.get(`${operatorId}:${key}`);
  if (!entry || Date.now() > entry.expiresAt) return null;
  return entry.value;
}

// EventDispatcher 注册
const handlers: Record<string, (data: unknown) => Promise<unknown>> = {
  "im.message.receive_v1": async (data) => {
    // 消息处理逻辑
  },

  "card.action.trigger": async (data) => {
    const d = data as any;
    const action = d?.action ?? {};
    const operator = d?.operator ?? {};
    const tag = action.tag ?? "";
    const operatorId = operator?.open_id ?? "";

    // 1. 下拉选择：缓存值，返回 undefined
    if (tag === "select_static") {
      const selectName = (action.value as any)?.action ?? action.name ?? "";
      const selectedOption = action.option ?? "";
      if (selectName && selectedOption) {
        cacheSelect(operatorId, selectName, selectedOption);
      }
      return undefined;  // 不要返回 {} — 会导致 WS 断连
    }

    // 2. 非按钮交互：静默忽略
    if (tag !== "button") {
      return undefined;
    }

    // 3. 按钮点击：注入缓存值 + 业务处理
    const actionValue = { ...(action.value ?? {}) };
    // 注入所有需要的缓存 select 值
    const cached = getCachedSelect(operatorId, "my_select_key");
    if (cached) actionValue["my_select_key"] = cached;

    // 路由到业务 handler...
    const actionName = (actionValue as any).action ?? action.name ?? "";
    // dispatch(actionName, actionValue, operatorId)

    // 4. 只返回 toast（不返回 card 更新）
    return { toast: { type: "success", content: "操作成功" } };
  },
};

const dispatcher = new lark.EventDispatcher({
  encryptKey: config.encryptKey
}).register(handlers as any);  // as any 因为 SDK 类型不包含 card.action.trigger

const wsClient = new lark.WSClient({
  appId: config.appId,
  appSecret: config.appSecret,
  loggerLevel: lark.LoggerLevel.info
});

// 不要传 cardActionHandler — SDK 会忽略它
wsClient.start({ eventDispatcher: dispatcher });

关键点：

• as any 是必须的，因为 SDK 的 TypeScript 类型定义不包含 card.action.trigger 作为合法事件类型
• select_static 必须返回 undefined（不是 {}），否则 SDK 会 base64 编码一个空对象发回去，导致 WS 断连
• button 处理只返回 { toast: {...} }，不返回 { card: {...} }

第三步：业务 Handler

Handler 只返回 toast，不返回卡片更新：

typescript
// ✅ 正确：返回 toast
async function handleOpenPeriod(num: number): Promise<CardActionResult> {
  await lifecycle.openNewPeriod(num);
  return { toast: { type: "success", content: `✅ 第 ${num} 期已开启` } };
}

// ❌ 错误：返回卡片更新 — 导致 200672
async function handleOpenPeriod(num: number): Promise<CardActionResult> {
  await lifecycle.openNewPeriod(num);
  return { newCardJson: buildNewCard() };  // 这会导致 200672
}

如果需要更新卡片内容，让用户重新发送关键词拉起新卡片，或者用飞书 API 主动发送新卡片消息。

第四步：权限控制

每个 handler 开头检查操作者权限。卡片发送到群聊后所有人可见，但按钮回调中 operatorOpenId 是实际点击者：

typescript
function requireAdmin(repo: Repo, openId: string): CardActionResult | null {
  const member = repo.findMemberByOpenId(openId);
  if (!member) {
    return { toast: { type: "error", content: "未找到对应成员" } };
  }
  if (member.roleType !== "operator" && member.roleType !== "trainer") {
    return { toast: { type: "error", content: "仅管理员可执行此操作" } };
  }
  return null; // null = 权限通过
}

// 在每个 handler 开头调用
const denied = requireAdmin(deps.repo, ctx.operatorOpenId);
if (denied) return denied;

部署检查清单

每次修改卡片相关代码后，按此顺序验证：

1. 编译检查：npm run build 退出码必须为 0

• 不要用 npm run build | tail（管道吞掉非零退出码）
• 使用 set -euo pipefail 确保错误传播
• 检查 unused import（TS6133 导致编译失败）

1. 服务重启：systemctl restart ai-seed-project

1. 等待 WS 就绪：确认日志出现 ws client ready

• 频繁重启后等 2-3 分钟让飞书路由事件到新连接

1. 回归测试：用户发关键词确认卡片能弹出

• 这是最重要的验证步骤，每次必做

1. 功能测试：选择下拉 → 点按钮 → 确认 toast 显示

常见问题排查

| 现象 | 根因 | 解决 | |------|------|------| | 200672 错误 | 返回了 card 更新而非 toast | 改为返回 toast | | 按钮点击后无反应 | 用了 form_submit | 改为普通 button | | 下拉值未传递到按钮 | 无 form_container 支持 | 用服务端缓存 | | "管理"拉不起卡片 | monkey-patch 破坏消息投递 | 移除 monkey-patch | | WS 连接断开 | 返回 {} 给 card.action.trigger | 改为 return undefined | | 编译后功能不变 | tsc 失败但管道吞掉退出码 | 用 pipefail 验证 | | UNIQUE constraint | 重复创建已存在的记录 | 先查后插 | | 重启后事件不到达 | 飞书路由延迟 | 等 2-3 分钟 |

Toast 状态提示最佳实践

操作成功后的 toast 应包含当前系统状态，让管理员了解上下文：

typescript
// ✅ 好：包含操作结果 + 当前状态
return {
  toast: { type: "success", content: `✅ 第 ${num} 期已开启 | 当前活跃：第${num}期 | 窗口:W2` },
};

// ✅ 好：已存在的操作返回 info 而非 success
return {
  toast: { type: "info", content: `第 ${num} 期已存在 | 当前活跃：第3期` },
};

// ❌ 差：只有操作结果，没有上下文
return {
  toast: { type: "success", content: "操作成功" },
};

操作后获取当前状态的方法：

typescript
const state = await buildCurrentState(lifecycle, deps);
const periodInfo = state.activePeriod ? `第${state.activePeriod.number}期` : "无";
const windowInfo = state.activeWindow?.code ?? "无";

幂等性设计

开期/开窗操作必须幂等 — 重复执行同一操作不应产生副作用：

typescript
// ✅ 先查后插，已存在则 early return（不执行窗口关联等后续逻辑）
const existing = repo.findPeriodByNumber(campId, number);
if (existing) {
  return { periodId: existing.id, assignedWindowId: null, shouldSettleWindowId: null };
}
// 真正的新建逻辑...

// ❌ 先查后插但继续执行后续逻辑 — 会导致窗口重复关联
const existing = repo.findPeriodByNumber(campId, number);
if (!existing) { repo.insertPeriod({...}); }
// 窗口关联逻辑仍然跑... ← BUG

部署注意事项

国内服务器 git pull 超时问题

国内服务器直连 GitHub 不稳定。当 git pull 超时时：

1. 小文件（<10KB）：用 Base64 直写 echo '<b64>' | base64 -d > file
2. 大文件（>10KB）：tsc build 后直接 patch dist JS（用 node -e 脚本）
3. 验证：patch 后跑 node -c dist/xxx.js 确认语法正确

dist JS 直接 patch 的模式

bash
node -e "
const fs = require('fs');
const f = 'dist/my-file.js';
let c = fs.readFileSync(f, 'utf8');
const old = 'exact old code';
const rep = 'exact new code';
if (c.includes(old)) {
  c = c.replace(old, rep);
  fs.writeFileSync(f, c);
  console.log('PATCHED');
} else {
  console.log('MARKER_NOT_FOUND');
}
"
node -c dist/my-file.js  # 验证语法

新增卡片的完整流程

1. 设计卡片模板（用普通 button，不用 form_container）
2. 给每个 select 和 button 设置唯一的 name 和 value.action
3. 在 EventDispatcher 的 card.action.trigger handler 中添加 select 缓存 key
4. 编写业务 handler，只返回 toast（含当前状态）
5. 确保操作幂等（先查后插，已存在 early return）
6. 注册 handler 到 CardActionDispatcher
7. 编译、部署、回归测试（发关键词确认卡片弹出 + 测试按钮）