OpenClaw Feishu Card Callback Bridge

一个独立的 OpenClaw 插件，把飞书卡片按钮点击和表单提交回调注入回事件来源会话。它只处理通用回调逻辑：解析 action、渲染模板、toast、follow-up 或编辑卡片。具体 payload 的业务处理由 companion 插件通过共享 action registry 注册，例如 openclaw-feishu-card-callback-business-handle。

它解决什么问题

OpenClaw 飞书通道可以接收 card.action.trigger，但业务插件需要显式注册 interactive handler 才能消费按钮或表单回调。本插件注册一个可配置的 namespace handler，把卡片交互转换成会话中的机器人消息，让当前会话里的 AI 或用户能看到交互结果。

典型流程：

飞书用户点击卡片按钮 / 提交表单
  -> openclaw-lark 收到 card.action.trigger
  -> 本插件按 value.action 的 namespace 接管
  -> 按 payload 查询共享 action registry
  -> 有业务 handler 时调用 handler，没有时走通用模板
  -> respond.followUp / editMessage 回写到原会话

安装

前置：本机已安装并能运行 OpenClaw，Node.js >= 22。

cd /Users/chenzeping/go/src/code.byted.org/epscp/fde-skills/common/plugins/openclaw-feishu-card-callback-bridge
npm install --no-package-lock --silent
npm run build
openclaw plugins install "$(pwd)"

安装后检查：

openclaw plugins list

输出里应能看到 openclaw-feishu-card-callback-bridge。

构建产物及打包

本仓库根目录 .gitignore 会忽略插件下的 node_modules/ 和 dist/。仓库只保存 TypeScript 源码、manifest、README 和验证脚本；安装、发布或交付前需要在本地生成 dist/。

cd /Users/chenzeping/go/src/code.byted.org/epscp/fde-skills/common/plugins/openclaw-feishu-card-callback-bridge
npm install --no-package-lock --silent
npm run build
npm run verify:registry
npm pack --dry-run

构建成功后会生成：

dist/
├── action-registry.js
├── action_handler.js
└── index.js

package.json 的 openclaw.extensions 指向 ./dist/index.js，所以 dist/ 缺失时不能直接按本地路径安装运行时插件。

交付前确认：

• npm run build 已通过。
• npm run verify:registry 已通过。
• dist/index.js 存在。
• npm pack --dry-run 输出包含 dist/、openclaw.plugin.json、README.md、package.json。
• 不要提交 node_modules/、dist/ 或 *.tgz。

配置

最小配置：

{
  "plugins": {
    "openclaw-feishu-card-callback-bridge": {
      "namespaces": ["custom-button"],
      "echoMode": "message",
      "clickTemplate": "{senderMention} 点击了 {actionLabel}",
      "messageTemplate": "{senderMention} 刚提交了表单：{formSummary}",
      "toastContent": "已收到"
    }
  }
}

Action Registry

Bridge 会在收到回调时按 ctx.payload 查询共享 action registry：

value.action = "custom-button:close"
namespace = "custom-button"
payload = "close"

如果 registry 中存在 close handler，bridge 会调用 handler，并用 handler 返回的 messageTemplate 渲染回写内容。如果不存在 handler，bridge 会走通用模板：

• 普通按钮：clickTemplate
• 表单提交：messageTemplate

业务 handler 推荐由 openclaw-feishu-card-callback-business-handle 这类 companion 插件注册。bridge 不直接依赖具体业务后端。

配置项

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | namespaces | string[] | ["custom-button"] | 要注册的回调命名空间，卡片 value.action 必须是 <namespace>:<payload> | | echoMode | "message" \| "card" \| "silent" | "message" | message 发 followUp，card 编辑原卡片，silent 只 toast | | clickTemplate | string | {senderMention} 点击了 {actionLabel} | 普通按钮点击回显模板 | | messageTemplate | string | {senderMention} 刚提交了表单：{formSummary} | 表单提交回显模板 | | toastContent | string | 已收到 | 点击者看到的 toast | | botOpenId | string | "" | 可选机器人 open_id；留空时尝试从飞书账号配置自动探测 | | senderMentionLabel | string | "" | {senderMention} 的 fallback label | | botMentionLabel | string | "Bot" | {botMention} 的 fallback label | | fieldLabels | Record<string,string> | {} | 表单字段名到展示名的映射 | | actionLabels | Record<string,string> | {} | payload 或完整 action 到展示名的映射 |

模板支持：{action}、{namespace}、{payload}、{senderId}、{conversationId}、{messageId}、{formValue}、{formSummary}、{actionLabel}、{senderMention}、{botMention}。

卡片按钮协议

按钮的 behaviors[].type 必须是 callback，value.action 必须使用 <namespace>:<payload>。

{
  "tag": "button",
  "text": { "tag": "plain_text", "content": "关闭" },
  "behaviors": [
    {
      "type": "callback",
      "value": {
        "action": "custom-button:close",
        "alarm_id": "alarm-1"
      }
    }
  ]
}

表单提交按钮需要放在 tag: "form" 容器内，并设置 form_action_type: "submit"：

{
  "tag": "button",
  "name": "submit_btn",
  "text": { "tag": "plain_text", "content": "提交" },
  "form_action_type": "submit",
  "behaviors": [
    {
      "type": "callback",
      "value": { "action": "custom-button:submit" }
    }
  ]
}

文件结构

openclaw-feishu-card-callback-bridge/
├── README.md
├── action-registry.ts         # 共享 payload handler registry
├── action_handler.ts          # 通用回调上下文、模板渲染、消息发送
├── index.ts                   # OpenClaw 插件入口和 lark 兼容 patch
├── openclaw.plugin.json       # 插件 manifest 和配置 schema
├── package.json
├── scripts/verify-registry.mjs
└── tsconfig.json

故障排查

| 现象 | 排查方向 | | --- | --- | | 点击后没有回写消息 | 检查插件是否安装、namespaces 是否包含 action 前缀、飞书回调是否到达 OpenClaw | | 只看到 toast 没有消息 | 检查 echoMode 是否为 silent | | 业务 handler 没有执行 | 检查 companion 插件是否安装并启动、payload 是否注册、value.action 是否为 <namespace>:<payload> | | 构建失败找不到 OpenClaw SDK | 运行 npm install --no-package-lock --silent 后再 npm run build |

与 business-handle 的关系

openclaw-feishu-card-callback-business-handle 负责注册 PipeChina 等 payload handler。bridge 可以单独运行；没有 business-handle 时，只输出通用点击或表单提交消息。