feishu-bridge

核心用法

Feishu Bridge 是一款专为飞书（Feishu/Lark）生态设计的本地桥接工具，通过 WebSocket 长连接技术实现飞书机器人与 Clawdbot Gateway 的双向通信。用户无需部署公网服务器、申请域名或配置内网穿透（如 ngrok），仅需在本地运行桥接脚本即可完成整套集成。

部署流程分为四个阶段：首先在飞书开放平台创建自建应用并启用机器人能力，配置 im:message 等必要权限及 WebSocket 事件订阅；其次将 App Secret 安全存储于本地文件系统；然后通过 npm 安装依赖并启动桥接服务；最后可选配置 macOS launchd 实现开机自启。桥接器会自动将飞书会话映射为 Clawdbot 会话（格式为 feishu:<chatId>>），支持单聊与群聊两种场景。

群聊场景下，桥接器内置智能响应策略：仅当用户 @ 提及机器人、消息以问号结尾、包含请求动词（如"帮/请/分析/总结"）或直接呼叫机器人名称时才会触发回复，有效避免群聊刷屏。

显著优点

零公网暴露架构是该技能最大亮点。传统 IM 机器人集成通常需要公网服务器接收平台回调，而 Feishu Bridge 采用反向 WebSocket 设计——本地服务主动连接飞书云端，彻底消除端口暴露风险，大幅降低部署门槛与安全攻击面。

企业级安全实践贯穿设计：敏感凭证与代码分离存储，支持自定义密钥路径；文档明确建议使用 chmod 600 限制文件权限；消息去重机制（10 分钟 TTL）防止重复处理；日志与配置分离，避免凭证泄露。

运维友好性体现在完善的诊断体系：launchctl 服务管理、实时日志追踪、自动重启机制一应俱全。FEISHU_THINKING_THRESHOLD_MS 环境变量可配置"思考中"提示阈值，优化长响应场景的用户体验。

潜在缺点与局限性

平台绑定性较强：当前仅支持飞书生态，未提供钉钉、企业微信等其他国内 IM 平台的适配能力。若企业使用多平台协同，需部署多套桥接方案。

macOS 中心化的自动化配置略显局限。setup-service.mjs 专为 macOS launchd 设计，Linux 用户需手动编写 systemd 服务，Windows 用户缺乏官方支持，跨平台一致性不足。

网络依赖单一：桥接器同时依赖飞书云端 API 与本地 Clawdbot Gateway 的可用性，任一链路中断都会导致服务中断。虽支持自动重连，但无内置的降级或缓存机制。

群聊智能过滤的误判风险：基于关键词和标点的启发式规则可能漏检复杂请求，或误触发非目标消息，需用户根据实际群聊语境调整 shouldRespondInGroup()() 逻辑。

适合的目标群体

该技能主要面向三类用户：中小企业技术团队希望快速为飞书组织接入 AI 能力，但缺乏专职运维人员或公网服务器资源；个人开发者与 AI 爱好者构建私有化 AI 助手，注重数据隐私与部署成本控制；Clawdbot 生态现有用户扩展消息触达渠道，实现"一个 Gateway，多端接入"的架构目标。

对金融、医疗等强合规行业，零公网暴露特性尤其契合数据不出域的安全要求。但需注意，群聊场景的消息内容仍经飞书云端传输，非完全端到端私有化。

使用风险

凭证管理风险：App Secret 以明文形式存储于本地文件，若设备丢失或遭受物理访问，可能导致机器人身份被盗用。建议配合磁盘加密与定期轮换策略。

日志隐私泄露：日志文件默认记录消息内容，长期累积可能形成敏感信息沉淀。需配置日志轮转与定期清理，避免合规风险。

服务持久化副作用：launchd 自动启动虽提升便利性，但若配置错误（如错误的 Gateway 地址）可能导致无限重试日志膨胀，或僵尸进程占用资源。

依赖项供应链风险：虽当前依赖（@larksuiteoapi/node-sdk、、ws`）均为官方/社区广泛验证的包，但未来版本升级需关注 CVE 漏洞公告。