Feishu Interactive Cards

核心功能

Feishu Interactive Cards 是一个专为飞书（Lark）设计的交互卡片工具，核心理念是：当回复飞书消息且存在任何不确定性时，发送交互卡片而非纯文本。通过按钮、表单、投票等富UI元素，让用户通过点击而非输入来完成交互。

显著优点

1. 交互效率提升：用户通过点击按钮即可完成选择，无需手动输入，显著降低交互成本
2. 自动回调处理：内置长轮询回调服务器，无需公网IP即可接收用户交互事件
3. 多场景覆盖：支持确认对话框、待办清单、投票调查、表单收集等多种卡片模板
4. Agent原生集成：提供JavaScript SDK，方便在智能体中直接调用发送卡片
5. 状态自动携带：按钮value字段可携带完整状态信息，避免额外查询

潜在局限性

1. 外部依赖重：依赖飞书开放平台API和OpenClaw Gateway，任一服务异常都会影响功能
2. 配置复杂度高：需要正确配置appId/appSecret、网关token等多项参数
3. 本地服务依赖：回调服务器需本地持续运行，断开后无法接收交互事件
4. 仅支持飞书生态：无法迁移至其他IM平台（如钉钉、企业微信）

适合人群

• 构建飞书办公自动化（OA）系统的开发者
• 需要人机交互确认环节的企业AI Agent项目
• 飞书企业用户中的IT管理员和技术团队

常规风险

• 凭证泄露风险：appSecret和gateway token需妥善保管
• 长轮询稳定性：网络波动可能导致回调接收中断
• 用户体验一致性：过度使用卡片可能造成界面臃肿

功能概述

feishu-interactive-cards 是一套专为飞书（Lark）设计的交互式消息卡片工具，核心目标是"凡有不确定性，皆用卡片而非纯文本"。通过按钮、表单、投票、待办清单等富UI元素，让用户以点击代替输入，大幅降低交互摩擦。

核心能力

| 场景 | 卡片类型 | 典型用途 |

|------|---------|---------|

| 确认决策 | Confirmation Card | 删除文件、执行危险操作前的二次确认 |

| 多选决策 | Poll Card | 团队活动投票、方案选择 |

| 任务管理 | Todo Card | 任务分配、进度跟踪、状态更新 |

| 信息收集 | Form Card | 参数配置、反馈收集 |

| 自定义场景 | Custom Card | 复杂业务逻辑的灵活适配 |

技术架构亮点

1. 长轮询回调机制：无需公网IP，通过 Feishu 长轮询自动接收用户点击事件
2. 本地 Gateway 集成：回调数据自动转发至 OpenClaw Gateway，无缝接入 Agent 工作流
3. 状态内嵌设计：按钮 value 携带完整上下文，避免额外查询

显著优点

• 交互效率：用户从"阅读理解→打字回复"简化为"直接点击"
• 容错增强：确认环节阻断误操作，支持超时提醒和重复点击防护（3秒去重）
• 视觉清晰：卡片结构化呈现信息，减少认知负荷
• 异步友好：长耗时操作可后台执行，卡片实时更新状态

潜在局限

• 配置依赖：需预置 ~/.openclaw/openclaw.json 的飞书应用凭证和 Gateway Token
• 学习成本：卡片 JSON 结构有一定复杂度，需参考模板
• 网络要求：Callback Server 需持续运行，断连后自动重连但存在瞬时延迟
• T3来源：社区项目级别，无官方背书，更新维护依赖个人开发者

适合人群

• 使用 OpenClaw/Claude 等 AI 代理对接飞书的企业开发者
• 需要构建人机协作工作流（审批、运维、客服）的技术团队
• 希望降低飞书 Bot 使用门槛、提升交互体验的产品团队

常规风险

1. 凭证泄露：openclaw.json 包含飞书 App Secret 和 Gateway Token，需严格设置文件权限（建议 chmod 600）
2. 本地暴露：Gateway 默认监听 localhost:18789，若部署在共享环境需确认 Token 强度
3. 回调延迟：长轮询模式在高频场景下可能存在秒级延迟，非实时应用
4. 依赖维护：仅依赖 axios 和官方 SDK，但需关注飞书 API 变更的兼容性更新