核心用法
feishu-bridge 是一款面向开发者与团队管理员的飞书（Lark）机器人桥接工具，核心解决「无公网服务器条件下部署飞书 AI 助手」的痛点。其架构采用双向 WebSocket 设计：飞书 SDK 主动 outbound 连接飞书云，本地 bridge 模块再通过内网 WebSocket 与 Clawdbot Gateway 通信，全程无需开放入站端口、域名或 ngrok 隧道。
部署流程四步走：在飞书开放平台创建自建应用并开启机器人能力 → 配置 im:message 等事件订阅与 WebSocket 长连接投递模式 → 将 App Secret 写入本地受权目录 → 启动 bridge 服务。macOS 用户可额外调用 setup-service.mjs 生成 launchd plist，实现开机自启与崩溃重启。
群聊场景支持智能降噪：仅当消息 @ 机器人、以问号结尾、含请求动词（帮/请/分析/总结）或直呼 bot 名时才触发回复，避免无关对话干扰上下文。
显著优点
1. 零公网依赖：纯 outbound 连接，内网穿透成本归零，安全合规性高
2. 轻量无状态：单文件 Node.js 服务，重启后通过 feishu:<chatId> 会话标识自动续接上下文
3. 原生 macOS 集成：launchd 方案优于传统 cron，支持日志轮转与自动保活
4. 可定制响应策略：shouldRespondInGroup() 函数开放修改，适配不同企业文化
潜在局限
- 单点部署：bridge 为本地单机运行，无集群高可用机制，断网即失联
- 权限门槛：需企业管理员审批飞书应用发布，个人开发者可能受限于组织流程
- Node.js 依赖：对非技术用户存在环境配置成本，且 npm 生态潜在供应链风险
- 仅限 WebSocket：若企业防火墙阻断出站 WS/WSS，方案失效（需额外 proxy 配置）
适合人群
- 已拥有 Clawdbot Gateway 的企业开发者与 DevOps 工程师
- 希望为团队快速搭建「私域 AI 助手」而无预算采购公网服务器的中小团队
- macOS 重度用户，追求与系统级服务管理（launchd）无缝集成
常规风险
- 凭证泄露：App Secret 以明文存储于
~/.clawdbot/secrets/，需确保目录权限 600 且排除备份同步 - 会话标识伪造：bridge 仅做简单前缀
feishu:拼接，若 Gateway 未校验 token，存在 chatId 碰撞或伪造风险 - 日志持久化：错误日志默认落盘于用户目录，长期使用需配合
logrotate避免磁盘占满 - 飞书平台策略变更：长连接模式与事件订阅规则受飞书开放平台版本迭代影响，需关注官方变更公告