Feishu ↔ dot Bridge

让不同用户把自己的飞书私聊，安全地绑定到各自现有的 personal dot。

状态：可运行的实验性开源 MVP。 已完成本地 MOCK 集成与安全回归测试，尚未完成真实飞书 + ChatGPT/dot 的端到端验收。不是官方 OpenAI 或飞书项目，不应直接当作已审计的生产服务。源码采用 MIT 许可；使用时请遵守许可及依赖义务。

English summary · 部署 · 安全边界 · 协议与证据 · 上线验收

它如何工作

1. 每个人在自己的 dot 中连接本服务的 OAuth 插件账号

2. dot 调用 begin_binding，用户把一次性 /bind … 命令发到飞书机器人私聊

3. 桥接器用飞书验证过的 (app_id, tenant_key, open_id) 与 OAuth 的 (issuer, subject) 建立一对一关系

4. 用户让自己的 dot 订阅 feishu.message.created，并明确批准如何回复

5. 飞书文字消息经过持久化队列，通过 MCP Events 发给该 dot 所在订阅

6. dot 调用 reply_to_feishu，服务只能回复该账号收到的原始消息，不能任意指定收件人

这是事件订阅 + MCP 工具回传，不依赖假想的 “dot chat REST API”，也不启动另一个模型冒充用户原来的 dot。处理节奏由 dot 决定，不保证即时对话延迟。

Related MCP server: lark-cli-mcp

当前支持

• 多用户各自绑定、各自订阅、各自回复；每个 OAuth 账号一条有效绑定，每条绑定一个有效订阅

• 多个显式配置的飞书/Lark 企业自建应用；每个 app ID 固定一个已核实的 tenant key

• MVP 只处理用户发给机器人的 p2p 文字消息

• 官方 MCP v2 SDK @modelcontextprotocol/server@2.3.0，协议 2026-07-28

• 外部 OAuth2.1 身份提供商，JWT/JWKS 验证，scope bridge:use

• 飞书入站可选加密签名 webhook（默认）或官方 SDK WebSocket；两者都校验 tenant/app，忽略机器人与群消息

• SQLite 持久化绑定、收件箱、订阅、发件队列；message_id 去重，按队列保持投递顺序，有限重试

• Standard Webhooks 签名与 challenge；callback HTTPS、明确主机白名单、公共 IP 校验、连接时 DNS 固定、拒绝重定向

• 取消绑定会取消未开始的任务；只读 delivery_status 区分 pending/sent/dead/uncertain

不包含： 飞书应用商店 ISV 安装授权/跨企业 token 管理、群聊映射、文件/图片/卡片、音频转写、原生实时语音通话、公开账号管理后台、多副本 worker、高可用数据库、完整监控和自动化 IdP 撤销通知。AudioAdapter 只是未来扩展接口，没有启用音频功能。

五分钟跑本地演示

需要 Node.js 24+ 和 npm。

npm ci --ignore-scripts
npm test
npm run demo

演示完全离线，使用明确标为 MOCK 的 dot 接收器和飞书发送器，不需要 API Key，不会访问真实账号或发送消息。31 项测试覆盖多用户路由、绑定、越权、JWT、SSRF、飞书签名、重放、轮换、取消、持久化和实际 MCP2 HTTP 契约；以当前 npm test 输出为准。

运行真实服务需要什么

cp .env.example .env
mkdir -p config
cp examples/feishu-apps.json config/feishu-apps.json
# 编辑本地配置；生成 STORAGE_KEY；通过秘密管理器提供真实密钥
npm ci --ignore-scripts
npm run build
node --env-file=.env dist/src/main.js

启动会拒绝缺失配置。没有 “跳过 OAuth” 或 “生产 mock mode” 开关。

你还需要自行准备：

• 一个域名、可信 HTTPS 与持久化磁盘

• 已开启机器人的飞书企业自建应用，以及事件订阅和最小消息权限（webhook 模式另需加密密钥）

• 能完成 ChatGPT OAuth2.1 连接的身份提供商；本项目是资源服务器，不是 OAuth 授权服务器

• 支持 MCP Events 的 dot/工作区权限，手动配置并连接本 MCP 插件

• 来自实际 ChatGPT 订阅的 callback 主机名白名单；不要填猜测地址或 *

完整步骤与配置说明见 部署指南。不要把 ChatGPT 密码、会话 cookie、OpenAI API Key 或飞书 App Secret 发到聊天里。

已有飞书应用使用长连接？

可为该应用显式设置 ingress: "websocket"，继续使用官方 Node SDK 长连接接收消息，无需改成 HTTP 回调，也不修改飞书应用的安全设置。示例见 WebSocket 配置 和 部署指南。未设置 ingress 时保持原来的 webhook 模式。

先确认消费者归属： 同 app 多条长连接按集群分发，不是广播。已有消费者仍在运行时，不要启动第二条桥接连接。应用如果同时承担其他事件/卡片功能，应把导出的文字消息处理器与原 im.message.receive_v1 handler 组合执行，并保留所有其它处理器；直接再次 register 同一事件会覆盖原handler。只有确认本服务是该 app 的唯一消费者且其它事件无需它处理时，才可设置 websocketExclusiveConsumer: true；示例默认 false，会拒绝启动。

WS 只替换飞书入站，MCP 的公网 HTTPS、OAuth 和 dot 订阅仍然需要配置。当前 WS 握手、真实收发和其它事件共存没有完成实网验收。

用户配对步骤

1. 在自己的 dot 中连接此插件，用自己的桥接账号完成 OAuth

2. 对 dot 说：“帮我绑定飞书，生成配对命令”

3. 只在目标飞书机器人私聊粘贴 dot 给出的命令；5 分钟内有效，一次使用，不要转发

4. 回到 dot 说：“检查我的飞书绑定状态”。MVP 不自动向飞书发送配对确认消息

5. 对 dot 说：“订阅我已绑定飞书的文字消息，并按我的要求通过原会话回复”。由你决定回复范围；敏感行动仍需要相应确认

6. 发一条非敏感测试消息，确认原来的 dot 收到事件，再检查飞书回复及 delivery_status

更换绑定应先请求 unlink_binding。同一个飞书身份不能被另一账号抢占。绑定码泄漏可能导致错误配对，应立即停止使用该码并在 dot 重新生成。

MCP 接口

• POST /mcp：工具与事件方法，共用 OAuth 认证；只接受现代 MCP2 请求

• GET /.well-known/oauth-protected-resource/mcp：OAuth 资源元数据

• POST /feishu/events/<appId>：仅 webhook 应用的飞书加密事件；WebSocket 应用此路由返回404

• GET /healthz：仅进程健康，不代表外部服务已连通

工具：begin_binding、binding_status、unlink_binding、reply_to_feishu、delivery_status

事件：feishu.message.created，订阅参数 { "binding_id": "..." }

可靠性说明

pending 只表示入队，sent 表示对端已接受；dot callback 的 2xx 不代表 dot 已完成回复。消息采用至少一次投递，不能保证跨服务绝对 exactly-once。Feishu 回复使用稳定 uuid，并在首次发送 55 分钟后停止自动重试，防止超出上游去重窗口后盲目重发；uncertain 必须人工核实。

只支持单进程/单 worker 使用一个数据库，不能启动多个副本。队列保持每个订阅的投递顺序，以及回复入队顺序；不承诺 dot 异步任务完成顺序。事件没有协议级历史 replay（cursor 为 null），未订阅或订阅已过期时的消息不会在以后补推。

贡献与发布

先跑 npm test、npm run demo，遵循 贡献说明。仓库已提供 GitHub Actions 和 Docker 配置。公开源码不代表服务已部署或完成真实账号联调。仓库不包含真实账号密钥。

投入真实使用前请完成 验收清单，并保留 MIT 许可 要求的版权及许可声明。