飞书双向桥接yangwuan55/dsh-feishu-integration

dsh-feishu-integration

中文优先 / Chinese first

将飞书与 DeepSeek Harness 双向连接：

- DSH 会话完成后，把总结发送到飞书；
- 在飞书中回复某条总结，自动路由回产生该总结的 DSH 会话；
- 支持 p2p 和群聊的固定会话延续；
- 在 DSH 设置页查看绑定状态、扫码绑定、重连、断开和解绑；
- 提供二维码 provisioning 和 fsum-admin CLI 管理入口；
- 支持飞书 Feishu 域和国际版 Lark 域。

安全默认值

公开安装包默认使用 takeoverInbound: false。这样安装时不会自动和已有的飞书长连接插件竞争事件流。

只有在同一个 DSH profile 中禁用其他飞书长连接插件后，才应启用入站接管：

- id: xmanrui-dsh-feishu
disabled: true

- id: dsh-feishu-integration
config:
takeoverInbound: true

飞书长连接使用集群式事件分发；同一个应用同时运行多个长连接客户端可能导致事件随机分流。

安装

在目标 DSH profile 中安装 GitHub 仓库：

dsh plugin --profile web add github:yangwuan55/dsh-feishu-integration

其他 profile 例如：

dsh plugin --profile headless add github:yangwuan55/dsh-feishu-integration

安装完成后重启对应的 DSH profile。插件自带 dsh.bundle.patch，会自动进入 profile；默认不会开启入站长连接。

安装后可在：

设置 → 插件 → 飞书

查看当前绑定状态并扫码绑定。绑定状态和二维码由 DSH 设置页提供，不要求先使用 CLI。

启用入站回复路由

如果需要“回复飞书总结 → 路由回对应 DSH 会话”，先确认旧飞书长连接插件已禁用，再在 profile patch 中覆盖配置：

- id: xmanrui-dsh-feishu
disabled: true

- id: dsh-feishu-integration
config:
takeoverInbound: true
replyTimeoutMs: 600000

配置文件通常是：

$DSH_HOME/profiles/web/cordis.patch.yml

也可以使用全局 patch：

$DSH_HOME/cordis.patch.yml

修改 patch 后可热重载配置；插件代码或依赖变化需要重启 DSH Web。

CLI 管理

设置页是推荐入口。CLI 仍然保留，方便自动化和无 UI 环境：

fsum-admin list
fsum-admin bind
fsum-admin bind --app-id cli_xxx --app-secret xxx --owner ou_xxx
fsum-admin verify --app-id cli_xxx
fsum-admin set-owner --app-id cli_xxx --open-id ou_xxx
fsum-admin unbind --app-id cli_xxx

二维码绑定使用飞书 SDK 的设备授权流程。凭据优先通过 DSH loopback credentials RPC 写入；在 DSH Web 未运行时才回退到本地 credential 文件。

数据与兼容性

插件保留旧 @xmanrui/dsh-feishu 的本地数据布局，以便迁移时延续已有绑定和固定会话：

$DSH_HOME/integrations/dsh-feishu/config.json
$DSH_HOME/integrations/dsh-feishu/reply-map.json
$DSH_HOME/integrations/dsh-feishu/bots//state.json

敏感的 app_secret 使用 DSH credential store，不写入公开配置文件。

路由行为

1. DSH 完成一次会话回合；
2. 插件向飞书发送文本总结；
3. 插件记录 message_id → sessionId 映射；
4. 用户在飞书中回复该总结；
5. 插件根据 parent_id/root_id 查找映射；
6. 命中后先立即在原飞书线程回复“已转发到哪个空间、哪个 DSH 会话”，其中包含 workspace 路径、会话标题和 session ID；
7. 再以 queue 模式把文本注入对应 DSH session；
8. 最终回答回帖到原飞书线程。

即时回执的 message_id 也会写入同一个 sessionId 映射，因此用户继续回复这条确认消息时，仍会回到同一个 DSH 会话。

发送重试：总结直发内置有界重试——最多 10 次尝试，指数退避（1s 起、30s 封顶、±20% 抖动）；重试等待期间用 DNS 探测 open.feishu.cn 做可达性门控，断网时顺延等待（不消耗尝试次数），总截止 10 分钟。每次逻辑发送携带飞书消息幂等 uuid，「已送达但响应丢失」不会重复投递。重试全部放弃时写入死信 ~/.dsh/integrations/dsh-feishu/pending-summaries.jsonl 供排查（不自动补发）。

等待回答超时（默认 600s）时插件保持静默：不追发「处理失败」回帖、不追加错误表情——转发回执本身已被视为送达确认，超时仅记录在 host 日志中。其他真实错误仍会回帖提示。

由飞书回复触发的 DSH 回合带有 fsum- RPC 标记，不会再次生成总结，从而避免回环。

会话提问转接（answerFromFeishu）

DSH 会话执行中调用 ask_user_question 暂停等待用户回答时，回合不会结束，飞书侧原本收不到任何通知。takeoverInbound=true 且 answerFromFeishu=true（默认）时，提问桥打通双向链路：

1. 插件经本机 WebSocket（/api/events.mux 下行流）收到 question/requested；
2. 问题与选项格式化后发到该会话最近使用过的飞书线程（无历史线程则落到总结目的地）；多问题批次逐题串行：先发第 1 题，回答后自动发下一题，全部答完一次性提交；
3. 用户在飞书回帖：数字选选项（multiSelect 可「1、3」组合）、选项原文精确匹配、其余文本作为自定义回答；回复「取消」放弃整批（等价网页端取消）；
4. 插件组装结构化作答 POST /api/respond，成功后在原帖回「✅ 已把全部回答提交给会话」（含逐题回显），会话继续执行；
5. 网页端抢先作答时插件收到 accepted:false，静默补一条说明；问题被取消同理。

断线自动重连（1s→30s 退避），重放帧按 rpcId 去重不会重复发帖。该通道为纯下行 WebSocket + HTTP 上行，不占用也不影响飞书长连接数量约束。

验证

dsh web --dump-config
node --check lib/index.js
node --check lib/client.js

检查启动后的 Web 页面 window.__DSH_BOOT__.entries 是否包含 dsh-feishu-integration。如果设置页没有「飞书」，优先检查：

1. package.json 是否保留 exports["./package.json"]；
2. 旧飞书插件是否被禁用；
3. DSH profile 是否已经重启；
4. dsh web --dump-config 是否包含新插件 entry。

目录结构

lib/index.js        组装根：config 解析 + 模块装配（无业务细节）
lib/host/           host 侧领域模块：bot 存储 / reply-map / 飞书 API /
总结推送 / session 网关 / 单 bot 入站运行时 / 设置页 RPC
lib/shared/         纯函数与常量（findReplyMapping 等测试缝）
client-src/         浏览器设置页源码（api / styles / index）
lib/client.js       由 client-src 构建生成的浏览器 bundle（勿手改）
scripts/            build-client.mjs：esbuild 打包出 ModuleLoader 包装产物
test/               node:test 回归（路由映射 / 回执文案 / 入站顺序）

约束：一个 bot 只允许一个飞书长连接（集群模式多 client 会随机分流事件）；
parent_id/root_id → reply-map → DSH session 的路由语义与 fsum- 防回环前缀不可变。

开发

git clone https://github.com/yangwuan55/dsh-feishu-integration.git
cd dsh-feishu-integration
pnpm install
pnpm build          # client-src/ → lib/client.js（改前端源码后必须重建）
pnpm test           # node:test 全量回归
node --check lib/index.js

改 host 侧逻辑直接编辑 lib/host/*.js，无需构建；改设置页 UI 编辑 client-src/，
然后 pnpm build 重新生成 lib/client.js。发布包只含 lib/、bin/ 与文档。

English

dsh-feishu-integration 双向连接飞书/Lark 与 DeepSeek Harness：

- 将已完成的 DSH 回合总结发送到飞书；
- 将针对某条总结的回复路由回产生它的 DSH 会话；
- 为未匹配的消息保留固定的 p2p/群组会话；
- 提供一个 DSH 设置标签页，包含绑定状态、扫码绑定、重连、断开连接和删除操作；
- 支持扫码配置和 fsum-admin CLI；
- 同时支持飞书和 Lark 域名。

当入站消息被路由到已映射的 DSH 会话时，插件会立即在同一飞书线程中回复工作区路径、会话标题和会话 ID。该确认消息被映射到同一会话，因此后续回复会在同一对话中继续。

如果超时前未收到回答（默认 600 秒），插件在飞书中保持静默——不发送失败消息，也不添加错误表情回应。路由确认消息已经充当了送达回执；超时仅在 host 侧记录日志。真正的错误仍会收到失败回复。

会话问题中继（answerFromFeishu）

当 DSH 会话在 ask_user_question 处暂停时，该回合永远不会结束，因此飞书以前什么也听不到。启用 takeoverInbound: true 和 answerFromFeishu: true（默认）后，问题桥接会闭合这一环路：
1. 插件通过本地 WebSocket 下行链路（/api/events.mux）接收 question/requested 帧；
2. 问题和选项会被发送到该会话最近的飞书话题串（若不存在则发送到摘要目标）；多问题批次按顺序分轮进行——先发送问题 1，每次回答后发送下一个问题，全部回答完毕后一次性提交；
3. 话题回复的解析方式为：选项编号（multiSelect 允许多个，如“1、3”）、精确的选项标签，或作为自定义答案的自由文本；回复“取消”会取消整个批次（等同于在 Web UI 中取消）；
4. 插件通过 POST /api/respond 提交结构化答案，并在话题串内以逐题回顾的形式进行确认；如果 Web UI 先完成了回答（accepted:false），则改为发布一条简短说明；
5. 重连时会重放待处理的帧——按 rpcId 去重可防止重复发布。

开发

宿主侧模块位于 lib/host/ 和 lib/shared/（纯 ESM，无需构建步骤）。设置界面源码位于 client-src/，通过 esbuild 打包进 lib/client.js——编辑后请运行 pnpm build。pnpm test 会运行回归测试套件（路由映射、确认文案、使用模拟 Lark SDK 的入站排序）。

安全默认值

该包默认 takeoverInbound: false。只有在禁用同一配置文件中所有其他飞书长连接插件后，才能启用入站接管：

- id: xmanrui-dsh-feishu
disabled: true

- id: dsh-feishu-integration
config:
takeoverInbound: true

飞书长连接使用集群化事件投递。为同一应用运行多个客户端可能会导致事件不可预测地分流。

安装

dsh plugin --profile web add github:yangwuan55/dsh-feishu-integration

该包附带一个 dsh.bundle.patch，因此会自动挂载到配置文件中。安装后重启 DSH，然后打开：

Settings → Plugins → Feishu

设置界面是查看绑定状态和扫描二维码的首选方式。

CLI

fsum-admin list
fsum-admin bind
fsum-admin verify --app-id cli_xxx
fsum-admin unbind --app-id cli_xxx

兼容性

该插件有意将旧版本地数据路径保留在 $DSH_HOME/integrations/dsh-feishu/ 下，以便在迁移期间复用现有的绑定、回复映射和固定会话状态。

官方发现

DeepSeek Harness 目前建议发布一个公开的 GitHub 仓库，并添加 dsh-plugin 话题以便被发现。本仓库遵循该约定。

许可证

MIT。参见 LICENSE。