飞书机器人桥接fengs2021/dsh-feishu-bridge

dsh-feishu-bridge

通过飞书（Lark）机器人与 DeepSeek Harness (DSH) 对话。你发送给机器人的消息会进入 DSH 会话；回复以流式交互卡片的形式返回——推理、正文和工具链分列于不同区块，并带有打字机效果。无需公网 webhook（使用飞书开放平台长连接）。

通过飞书机器人与 DeepSeek Harness（DSH）对话的桥接插件。回复以流式交互卡片实时发回（思维链/正文/工具链分区、打字机效果），无需公网 webhook。

English

Features

| Capability | Description |
|---|---|
| Direct chat | messages to the bot reach DSH with multi-turn context |
| Group @ | respond when @-mentioned in groups (needs botOpenId) |
| Streaming cards | CardKit 2.0 cards update in real time: reasoning + body + tool chain sections, token-level typewriter; native collapsible panels (collapsed when done) |
| Multi-turn context | same Feishu chat reuses the same DSH session; auto-resume after DSH restart (agents.resume) |
| Slash commands | /help, /reset, /status |
| Long-reply chunking | >8000 chars auto-splits into follow-up text messages |
| Reconnect | consume subprocess auto-backoff reconnects (2s → 30s cap) |
| Allowlist | only specified open_ids may chat |
| Idempotent dedup | per message_id dedup against event replays |
| Channel direct-send | registers a feishu channel in DSH's global registry (globalThis.__dshChannelNotify), so de_channel_send / de_notify can push text/images/files to Feishu (defaults to the most recent chat; target: 'p2p:oc_xxx' supported) |

Architecture

Feishu App ──long connection──> lark-cli event consume im.message.receive_v1 --as bot (child process)
│ NDJSON (chat_id / sender_id / content / mentions …)
▼
feishu-bridge plugin (DSH host process, cordis)
│ agents.create / agents.resume (chat_id → sessionId)
▼
DSH agent session (same models/tools as GUI)
│ llm/stream waterfall (per sessionId, token deltas)
▼
streaming accumulator (text / reasoning / tool-call deltas)
│ throttled PATCH (default ≥1.2s)
▼
lark-cli api patch im/v1/messages/:id ──▶ interactive card updates
└── turn end ──▶ final card (✅ done) + sessions.flush

- Event listening: lark-cli event consume im.message.receive_v1 --as bot (long-connection WebSocket, no public network required)
- Streaming hook: DSH's llm/stream waterfall events, matched per sessionId
- Card updates: PATCH /open-apis/im/v1/messages/:message_id with the card JSON string
- 会话映射：（默认 ~/.dsh/plugins/dsh-feishu-bridge/state.json），chat_id → sessionId

前置条件

- DeepSeek Harness 正在运行 dsh web（插件在宿主进程中运行）
- 已安装 lark-cli 并配置飞书应用（~/.lark-cli/config.json），机器人身份可用
- 一个具备机器人能力的飞书自建应用，权限范围覆盖目标用户/群组

npm install -g @larksuite/cli
lark-cli auth login          # 选择机器人身份（tenant_access_token）
lark-cli auth status         # bot: ready

应用需要 im:message 权限；事件通过长连接订阅接收——无需回调 URL。

安装

git clone https://github.com/fengs2021/dsh-feishu-bridge.git ~/.dsh/plugins/dsh-feishu-bridge
cd ~/.dsh/plugins/dsh-feishu-bridge && npm install

注册到 web profile：
dependencies += "dsh-feishu-bridge": "link:/root/.dsh/plugins/dsh-feishu-bridge"
dsh.profile.bundles += "dsh-feishu-bridge"
cd ~/.dsh/profiles/web && pnpm install

systemctl restart dsh-web

在飞书中给机器人发送一条消息——收到卡片回复即表示成功。

配置（全部可选，cordis.patch.yml）

- id: feishu-bridge
config:
botOpenId: 'ou_xxxxxx'     # 机器人 open_id（群内 @ 检测）
allowlist: ['ou_xxxxxx']   # open_id 白名单；留空 = 所有人
cwd: '~'                   # 新会话的工作目录
enableGroup: true          # 响应群内 @提及
maxReplyChars: 3500        # 文本模式回复上限（超出则分块）
typingHint: true           # 文本模式下的“正在输入”提示
replyMarkdown: true        # 文本模式下的 markdown 格式化
streamCard: true           # 流式卡片模式（默认开启）
cardPollMs: 600            # 流式轮询间隔（回合结束回退）
cardMinIntervalMs: 1200    # 卡片最小更新间隔（限流保护）
maxTurnMs: 600000          # 每回合最大等待时间
larkBin: 'lark-cli'        # lark-cli 可执行文件
stateFile: '~/.dsh/plugins/dsh-feishu-bridge/state.json'

获取 botOpenId：启动时自动探测（/open-apis/bot/v3/info）；或在群内 @ 机器人并查看日志（learned botOpenId=ou_xxx from group mention）；或查看飞书控制台 → 应用 → 机器人。

使用

1. 在飞书中打开机器人会话（或将机器人添加到群组）
2. 直接给它发消息；在群组中 @ 机器人
3. 命令：/help、/reset、/status

通道直发（DSH → 飞书）：de_channel_send channels=feishu content=...；附件通过 attachments=[{kind:'image'|'file', path|url|base64, fileName?}]；目标默认为最近的飞书会话，或显式指定 target: 'p2p:oc_xxx'。实现位于 lib/channel-registry.js（独立，对通知模块零依赖）。

常见问题要点

- 卡片卡在“thinking” → 检查 bridge.log：patchCard failed = 应用权限问题；target=miss = 会话映射问题
- stream is not async iterable → 旧版本的已知 bug；升级到 1.0.0（⚠️ 该监听器会影响所有 LLM 调用——不要改回 async）
- 群组 @ 无响应 → 检查 botOpenId + 应用权限范围
- 卡片更新 230001/230099 → 必须使用 PATCH /open-apis/im/v1/messages/:id 并携带卡片 JSON 请求体（切勿使用 PUT + msg_type）
- 重启后上下文丢失 → 插件自动 agents.resume；恢复失败则在收到下一条消息时重建

开发

npm test          # 纯函数单元测试
npm run check     # 静态检查

面向贡献者的设计说明：所有纯函数均已导出（collectReply / buildCard / createStreamAccumulator / toolSummary / splitChunks / cleanContent / shouldHandle）；llm/stream 是 cordis 的 waterfall 事件——监听器必须是同步函数并返回 AsyncIterable（将分块透传，切勿吞掉异常）；所有 lark-cli 调用都经过 runLark()（超时 + 输出捕获，降级路径）；同一会话上的并发 resume 由每会话的 promise 锁进行协调。

中文

通过飞书机器人与 DeepSeek Harness（DSH） 对话的桥接插件。

在飞书里给机器人发消息 → 消息进入 DSH 会话由 AI 处理 → 回复以流式交互卡片实时发回：思维链、正文、工具链分区展示，打字机效果逐字更新。无需公网 webhook（使用飞书开放平台长连接）。

效果示例（交互卡片，随生成实时更新）：

┌──────────────────────────────────┐
│ 🤖 DSH 助手                        │
├──────────────────────────────────┤
│ ▶ 🧠 思维链 · 212 字（点击展开）    │
│ 用户想查 /root/dsh 目录…            │
│ ──────────────────────────────── │
│ 好的，我来查看一下目录内容…          │
│ ──────────────────────────────── │
│ 🔧 工具链（2）                      │
│ - ✅ bash  ls -la /root/dsh        │
│ - ✅ memory 写入今日日志            │
│ ──────────────────────────────── │
│ ✅ 已完成                          │
└──────────────────────────────────┘

功能特性

| 能力 | 说明 |
|------|------|
| 私聊对话 | 与机器人单聊，消息直达 DSH，多轮上下文连续 |
| 群聊 @ | 群聊中 @ 机器人即响应（需配置 botOpenId） |
| 流式卡片 | CardKit 2.0 交互卡片实时更新：思维链 + 正文 + 工具链分区，token 级打字机效果；思维链/工具链为原生折叠面板（完结后默认收起，点击展开） |
| 多轮上下文 | 同一飞书会话固定复用同一 DSH 会话；DSH 重启后自动恢复（agents.resume） |
| 斜杠命令 | /help 帮助、/reset 清空上下文、/status 会话状态 |
| 长回复分段 | 超过卡片预览上限（8000 字）自动补发文本消息 |
| 断线重连 | consume 子进程异常退出自动退避重连（2s 起、30s 封顶） |
| 白名单 | 只允许指定 open_id 对话 |
| 幂等去重 | 按 message_id 去重，避免事件重放导致重复处理 |
| 渠道直发 | 注册 feishu 渠道到 DSH 全局注册表（globalThis.__dshChannelNotify），de_channel_send / de_notify 可直接把文本/图片/文件发到飞书（默认发往最近交互的会话，也支持 target: 'p2p:oc_xxx' 显式指定） |

架构原理

飞书 App ──长连接──> lark-cli event consume im.message.receive_v1 --as bot（子进程）
│ NDJSON（chat_id / sender_id / content / mentions …）
▼
feishu-bridge 插件（DSH host 进程内，cordis 插件）
│ agents.create / agents.resume（chat_id → sessionId 映射）
▼
DSH agent 会话（模型、工具与 GUI 同款）
│ llm/stream waterfall（按 sessionId 匹配，token 级 delta）
▼
流式累积器（text-delta / reasoning-delta / tool-call-delta）
│ 节流 PATCH（默认 ≥1.2s 一次）
▼
lark-cli api patch im/v1/messages/:id ──> 交互卡片实时更新（打字机效果）
│
└── turn 结束 ──> 最终态卡片（✅ 已完成）+ sessions.flush 持久化

- 事件监听：lark-cli event consume im.message.receive_v1 --as bot（飞书长连接 WebSocket，无公网要求）
- 流式接入：DSH 的 llm/stream waterfall 事件（每次模型调用都会经过），按请求携带的 sessionId 匹配到飞书 turn，拦截增量 chunk
- 卡片更新：PATCH /open-apis/im/v1/messages/:message_id，content 为交互卡片 JSON 字符串
- 会话映射：（默认 ~/.dsh/plugins/dsh-feishu-bridge/state.json），记录 chat_id → sessionId

前置条件

| 依赖 | 说明 |
|------|------|
| DeepSeek Harness | 已安装并运行 dsh web（插件运行在 host 进程内） |
| lark-cli | 已安装并完成飞书应用配置（~/.lark-cli/config.json），bot 身份可用 |
| 飞书自建应用 | 具备机器人能力，可用范围包含目标用户/群 |

lark-cli 安装与授权：

npm install -g @larksuite/cli
lark-cli auth login          # 选择 bot 身份（tenant_access_token）
lark-cli auth status         # bot: ready

bot 身份要求应用具备 im:message（收发消息）权限；消息事件走长连接订阅，无需在开放平台配置回调地址。

安装

1. 获取插件源码（二选一）
git clone https://github.com/fengs2021/dsh-feishu-bridge.git ~/.dsh/plugins/dsh-feishu-bridge
或手动放置到 ~/.dsh/plugins/dsh-feishu-bridge/

2. 安装插件依赖（@deepseek-ai/dsh-agent 等）
cd ~/.dsh/plugins/dsh-feishu-bridge
npm install

3. 注册进 web profile
cd ~/.dsh/profiles/web
编辑 package.json：
- dependencies 增加  "dsh-feishu-bridge": "link:/root/.dsh/plugins/dsh-feishu-bridge"
- dsh.profile.bundles 数组增加 "dsh-feishu-bridge"
pnpm install

4. 重启 dsh web（插件在 host 进程内启动 consume 子进程）
systemctl restart dsh-web      # systemd 托管
或手动重启你的 dsh web 进程

安装成功后，在飞书中给机器人发一条消息测试；回复以卡片形式出现即成功。
若 ~/.dsh/plugins/ 下已有其他插件（如 dsh-novel-studio），参照其安装方式即可。

配置

在 ~/.dsh/profiles/web/cordis.patch.yml 中覆盖配置（全部可选，均有默认值）：

- id: feishu-bridge
config:
botOpenId: 'ou_xxxxxx'     # 机器人 open_id（群聊 @ 判断用；见下方获取方式）
allowlist: ['ou_xxxxxx']   # open_id 白名单；空数组 = 允许所有人
cwd: '~'                   # 新会话工作目录（默认用户主目录）
enableGroup: true          # 是否响应群聊中 @ 机器人的消息
maxReplyChars: 3500        # 文本模式单条回复上限（超出分段）
typingHint: true           # 文本模式下收到先回「思考中」提示
replyMarkdown: true        # 文本模式回复使用 markdown 排版
streamCard: true           # 流式卡片模式（默认开；关闭则退回文本分段回复）
cardPollMs: 600            # 流式轮询间隔（毫秒，兜底检测 turn 结束）
cardMinIntervalMs: 1200    # 卡片更新最小间隔（毫秒，飞书接口限频保护）
maxTurnMs: 600000          # 单轮最长等待（毫秒），超时停止更新并提示
larkBin: 'lark-cli'        # lark-cli 可执行文件路径
stateFile: '~/.dsh/plugins/dsh-feishu-bridge/state.json'

botOpenId 获取方式

1. 插件启动时自动探测（/open-apis/bot/v3/info；部分应用权限下返回为空）；
2. 在任意群里 @ 机器人发一条消息，插件日志会打印
learned botOpenId=ou_xxx from group mention，填入配置即可；
3. 飞书开放平台后台 → 应用 → 机器人，查看机器人 open_id。

使用

1. 在飞书中搜索并打开机器人会话（或让管理员把机器人拉进群聊）；
2. 直接发消息即可对话；群聊中需 @ 机器人；
渠道直发（DSH → 飞书）
插件在 apply 时把主动发送能力登记到 DSH 渠道注册表（与 dsh-memory-evolve 通知模块的 globalThis.__dshChannelNotify 约定一致），因此 DSH 的 de_channel_send / de_notify 工具可直接发到飞书：

- 文本：de_channel_send channels=feishu content=...
- 附件：attachments=[{kind:'image'|'file', path|url|base64, fileName?}]（本地路径/base64 经临时目录 + 相对路径发送；图片走 --image，其余走 --file）
- 目标：缺省 = 最近交互的飞书会话（插件 state 记录）；显式传 target: 'p2p:oc_xxx'
- 实现：lib/channel-registry.js（独立模块，零依赖通知模块）

3. 命令：
- /help — 帮助
- /reset — 清空当前对话上下文，重新开始
- /status — 查看会话状态（sessionId / 模型 / 已处理消息数）

运维

| 事项 | 说明 |
|------|------|
| 插件日志 | ~/.dsh/plugins/dsh-feishu-bridge/bridge.log（事件接收 / 会话创建 / 流式匹配 / 错误） |
| 会话映射 | state.json；删除某条映射并重启即与该飞书会话「断连」（也可在飞书里发 /reset） |
| consume 异常 | 子进程自动退避重连；kill -9 可能泄漏服务端订阅，勿用 |
| 卸载 | 从 profile package.json 的 dependencies/bundles 移除，pnpm install 后重启 |
| 升级 | git -C ~/.dsh/plugins/dsh-feishu-bridge pull 后重启 dsh web |

常见问题（FAQ）

Q：飞书里一直显示「思考中」，卡片不更新？
检查 bridge.log：若出现 patchCard failed，确认飞书应用权限与卡片消息是否可更新；
若出现 target=miss，确认消息对应会话的 sessionId 与 state.json 一致（重启后会自动恢复）。

Q：收到「stream is not async iterable」？
历史版本的已知 bug（llm/stream listener 误用 async 函数），升级到 1.0.0 即可。
⚠️ 该 listener 影响所有 LLM 调用，请勿改回 async 函数。

Q：群聊里 @ 机器人没反应？
确认 botOpenId 已配置正确（见上文获取方式），且应用已在群内、可用范围包含该群。

Q：卡片更新失败（230001 / 230099）？
卡片更新接口固定为 PATCH /open-apis/im/v1/messages/:id（body 为
{"content": ""}）；不要改用 PUT + msg_type（会返回 230001）。

Q：重启 DSH 后上下文丢失？
重启后插件会 agents.resume 恢复持久化会话（日志可见 preloaded session ...）。
若 resume 失败（如会话文件损坏），映射会被保留，下次消息到来时自动重建。

开发

单元测试（纯函数：流式累积器 / 事件聚合 / 卡片构建 / 辅助函数）
npm test

静态检查
npm run check

目录结构

dsh-feishu-bridge/
├── lib/index.js            # 插件主体（cordis 插件）
├── cordis.patch.yml        # bundle patch（插入 web profile roster）
├── test/functions.test.mjs # 纯函数单元测试
├── package.json
├── README.md
├── CHANGELOG.md
└── LICENSE

设计要点（贡献者必读）

- lib/index.js 导出全部纯函数（collectReply / buildCard / createStreamAccumulator /
toolSummary / splitChunks / cleanContent / shouldHandle），便于测试与复用；
- llm/stream 是 cordis waterfall 事件：listener 必须为同步函数且返回
AsyncIterable（包装流时逐 chunk yield 透传，不得吞异常）；
- 所有 lark-cli 子进程调用走 runLark()（超时 + 输出捕获），失败均有降级路径；
- 同一持久化会话的并发 resume 通过 per-session promise 协调锁去重。

许可证

MIT

相关项目

- DeepSeek Harness — 本插件运行的宿主
- @larksuite/cli — 飞书开放平台 CLI（事件订阅 / 消息收发 / 卡片更新）