bandianliancha/feishu-workspace-bridge

飞书工作区桥接

CI
npm
npm downloads
License: MIT

把 DSH 工作区与飞书群一一对应，并在 DSH 会话和飞书群之间实时双向同步消息。

English · npm · Releases

Feishu Workspace Bridge 演示

离开电脑后，直接在飞书群里继续推进 DSH 工作区任务。无需公网回调地址，也不会读取历史消息。

插件只做三件事：

- 绑定一个飞书企业自建应用机器人。
- 工作区第一次产生需要同步的消息时，按需创建对应的飞书私有群并邀请你加入。
- 在当前 DSH 会话和对应飞书群之间双向同步消息。

工作方式

sequenceDiagram
participant DSH as DSH 会话
participant Bridge as Workspace Bridge
participant Feishu as 飞书私有群

DSH->>Bridge: 助手完成一次回复
Bridge->>Feishu: 按需建群并发送回复
Feishu->>Bridge: 用户发送群消息
Bridge->>DSH: 按顺序加入会话队列
Bridge->>Feishu: 添加 OK 表情确认接收

- 一个工作区最多绑定一个群。
- 群由机器人创建，默认是私有群，群信息仅允许群主或管理员修改。
- 工作区改名后，群名自动同步。
- 工作区删除后，对应飞书群自动解散。
- 如果群被手动解散，下一次同步时会自动重建。
- DSH 正在处理任务时，来自飞书的新消息使用 queue 模式排队，不会打断当前任务。
- 每条消息都会记录“已入队、投递中、失败、已送达”状态；临时失败会指数退避重试，进程重启后继续处理。
- Markdown 会使用飞书 lark_md 消息发送；长消息会分段发送，不会静默截断。
- 插件只消费实时事件，不读取或回放历史消息。

环境要求

- Node.js 20 或更高版本
- DeepSeek Harness（DSH）
- 飞书企业自建应用，并启用机器人能力

兼容性

| 项目 | 已验证范围 |
|---|---|
| DSH | 0.1.7-alpha.1 实机双向收发与生命周期验证 |
| Node.js | 20、22、24 持续集成测试 |
| macOS | 实机运行；App Secret 使用系统钥匙串 |
| Linux | Ubuntu CI 全量测试；App Secret 使用 0600 本机凭证文件 |
| 飞书 | 企业自建应用、机器人、长连接事件订阅 |

DSH 当前仍处于开发者预览阶段。上游接口出现兼容性变化时，请提交 Issue 并附上 DSH 版本和诊断页错误信息。

安装

dsh plugin --profile web add dsh-plugin-feishu-workspace

也可以直接从 GitHub 主分支安装开发版本：

dsh plugin --profile web add github:bandianliancha/feishu-workspace-bridge

安装后重启 DSH Web：

dsh web --no-open

打开 DSH 设置中的“飞书机器人”，填写：

- App ID
- App Secret
- 你的飞书 Open ID，格式为 ou_...

点击“保存并验证”。插件会在保存前检查机器人、事件订阅和全部必需权限。验证失败时不会覆盖已有配置。

已经保存过 App Secret 后，可以留空并重新执行权限验证。

飞书配置

在飞书开放平台完成以下配置。

1. 启用机器人

进入“添加应用能力”，添加机器人能力。

2. 使用长连接接收事件

在“事件与回调”中选择“使用长连接接收事件”，并订阅：

im.message.receive_v1

本地运行不需要公网回调地址。

3. 开通应用身份权限

| 权限 | Scope | 用途 |
|---|---|---|
| 创建群聊 | im:chat:create | 首次同步时创建工作区群 |
| 获取与更新群组信息 | im:chat | 邀请成员、改群名、改为私有群和解散群 |
| 以应用身份发消息 | im:message:send_as_bot | 将 DSH 回复同步到群 |
| 接收群聊消息 | im:message.group_msg | 将群消息同步到 DSH |
| 添加消息表情回复 | im:message.reactions:write_only | 接收成功后添加 OK 表情 |
| 管理应用自身信息 | application:application:self_manage | 验证已发布事件订阅 |

插件不使用企业自定义群标签权限，因此无需申请群标签审核。

数据与安全

- macOS 上的 App Secret 保存在系统钥匙串中，不写入 SQLite，也不会返回浏览器。
- 其他系统会回退到权限为 0600 的本机凭证文件 ~/.dsh/feishu-workspace-bridge.secrets.json。
- 升级后首次启动会自动把旧版 SQLite 中的 App Secret 迁移到新的凭证存储，并删除数据库中的明文。
- 凭证只保存一份，不会复制到各工作区记录。
- 默认数据库位置：~/.dsh/feishu-workspace-bridge.sqlite。
- 可通过 FEISHU_WORKSPACE_BRIDGE_DB 指定其他数据库路径。
- 入站和出站消息使用消息 ID 去重；已送达记录保留 30 天后自动清理，尚未送达的记录不会被定期清除。
- 飞书出站消息使用稳定 UUID，部分分段已经发送后重试也不会重复创建相同消息。
- HTTP 请求有 15 秒超时，飞书租户 token 会缓存并在过期前刷新。

群生命周期

群不会在创建空工作区时立即生成。只有该工作区第一次产生需要同步的助手消息时才会建群，避免创建大量空群。

已有工作区不需要手工迁移。插件启动后会检查已经绑定的群，补同步群名和私有群配置。

运行诊断

DSH 设置中的“飞书机器人”页面提供运行诊断，显示：

- 飞书长连接状态和最近一次事件时间。
- 已绑定及正常工作的工作区群数量。
- 最近一次飞书入站和出站消息时间。
- 消息投递状态、重试次数和最近错误。
- App Secret 当前使用的凭证存储。
- 机器人、事件订阅和权限的实时检查结果。

诊断数据不包含 App Secret、访问令牌或消息正文。点击“重试失败消息”可以立即重试持久化队列中的失败消息。

故障排查

DSH 能发到飞书，但飞书消息进不了 DSH

检查：

1. 应用是否订阅 im.message.receive_v1。
2. 事件接收方式是否为长连接。
3. 最新应用版本是否已经发布。
4. DSH 启动日志中是否出现 ws client ready。
5. 机器人是否仍在对应工作区群内。

保存时提示权限不足

按照错误信息中的 scope 在飞书开发者后台开通权限，并发布新版本，然后再次点击“保存并验证”。

群消息已经进入 DSH，但没有 OK 表情

检查 im:message.reactions:write_only 是否已经随最新应用版本发布。

修改代码后 DSH 没有生效

DSH 只在启动时加载服务端插件。修改插件后需要重启 dsh web。

开发

npm install
npm run check

测试覆盖权限门禁、按需建群、私有群配置、成员邀请、双向消息、Markdown 分段、消息确认、失败重试、重启恢复、幂等发送、工作区删除联动、凭证迁移和去重清理。

贡献

提交改动前请阅读 CONTRIBUTING.md，安全问题请按照 SECURITY.md 私下报告。

License

MIT © bandianliancha