dsh-plugin-feishu

dsh-plugin-feishu

DeepSeek Harness（DSH）的飞书插件 —— 把 DSH 会话接进飞书 / Lark 长连接，回复以流式卡片回写。

• 这是 DSH 插件（cordis 插件包），装进 DSH 的 profile 后由 DSH 进程加载，不需要另起守护进程、不需要公网回调地址。
• 收发都走飞书长连接（WebSocket），只要求本机出网；也没有 ngrok / 反向代理这些事。
• 与 [pi-feishu-bridge](https://github.com/suveng/pi-feishu-bridge) 的关系：那个是给 pi 用的独立桥接进程，本插件是它的 DSH 版思路 —— 直接嵌进宿主进程，用 DSH 自己的 Agent API 驱动会话。

能力

| 能力 | 说明 |

| --- | --- |

| 单聊 / 群聊 / 话题 | 一个飞书会话一个 DSH 会话，话题（thread）单独成会话 |

| 流式卡片 | 边生成边往卡片里写，飞书客户端逐步展开；轮次结束卡片转终态 |

| 会话保持 | 飞书会话 ↔ DSH 会话映射落盘，DSH 重启后接着聊；网页端正开着的同一条会话会被直接复用（真恢复不了才新建） |

| 消息串行 | 同一会话连发多条按顺序处理，不会两条消息抢同一个轮次 |

| 权限白名单 | 只认指定 open_id；留空则谁都能用（建议自用场景也配一下） |

| 斜杠命令 | /new /stop /status /cwd /whoami /help，不进模型上下文 |

| 提问人身份 | 每条消息首行带 【飞书 · 群聊|单聊 · 张三(90abcdef)】，模型一眼看到是谁、从哪来；详细字段走 feishu_identity 工具 |

| 飞书工具 | 只在飞书发起的轮次里可见：feishu_identity（查提问人）、feishu_send（主动补发一条文本）、feishu_learn_approval_submit / feishu_learn_approval_status（建审批单 / 查审批状态） |

| 选择题 | 模型用 ask_user_question 提问时，问题以卡片发到飞书：点按钮即答，也可以在卡片输入框自由输入（最多 200 字），或直接回文字 |

| 飞书审批 | 模型调用飞书审批应用建单、用实例号查状态：典型用法是 /learn 进化前拿到 APPROVED 再动文件；审批定义号在插件页「审批」分组配置 |

| 执行过程 | 工具调用在卡片顶部的「执行过程」折叠面板里逐条显示：正在跑哪一步、成没成、耗时多少 —— 长任务不再是黑箱 |

| 子agent 唤醒轮 | 子agent 异步跑完把主 agent 叫醒时，这一轮的回复同样回传飞书：新开一张「子agent 回来了 · 」卡，执行过程面板照常；网页端轮次不受影响 |

| 正文模式 | 默认只把本轮最终回复写进卡片正文；中间步骤的旁白、思考自动收进「执行过程」面板，不再和答案混在一起（replyBodyMode=live 可退回旧行为） |

| 停止按钮 | 回复中的卡片末尾有「停止」，点一下中断本轮（等价于 /stop），卡片转「已停止」 |

| 表情回执 | 收到消息先挂「收到」表情；跑完换成 DONE，失败换成 CRY（可关，可换收到时的表情） |

| 引用展开 | 回复某条消息时，插件会读出被引用内容并以 [Quoted message] 前缀附在正文前，模型知道「这个」指的是什么 |

| 内容去重 | 同一会话 5 秒内完全相同的一条文字只处理一次（飞书偶发重投换 message_id、手抖连发都在此列） |

工作原理

飞书客户端
   │  长连接（WSClient，事件 im.message.receive_v1）
   ▼
FeishuBridge ── 归一化/去重/白名单 ── 每会话串行队列
   │
   ├─ 斜杠命令 ──► 插件内部处理（直接回文本）
   │
   └─ 普通消息 ──► AgentPool（飞书会话键 → DSH Agent）
                        │  agent.followup(用户消息)
                        ▼
                   DSH Agent 跑一轮
                        │  agent/assistant-stream（text-delta）
                        ▼
                   ReplyCard ── CardKit 局部更新 ──► 飞书卡片
                        ▲
   DSH session/event ───┘（tool/call、tool/result → 卡片里的「执行过程」面板）

环境要求

• Node.js >= 22
• DSH（DeepSeek Harness）>= 0.2.1-rc.2，< 0.3.0
• 一个飞书自建应用（企业自建应用），并开启下面的权限与事件

一、飞书开发者后台配置

1. 在 [飞书开放平台](https://open.feishu.cn/app) 创建企业自建应用，拿到 App ID / App Secret。

2. 权限管理里开通：

| 权限 | 用途 |

| --- | --- |

| im:message（获取与发送单聊、群组消息） | 收消息、发消息 |

| im:message:send_as_bot（以应用身份发消息） | 发卡片与文本回复 |

| im:chat:readonly（获取群组信息） | 读取群 / 话题会话信息 |

| im:message.p2p_msg:readonly | 接收单聊消息 |

| contact:user.base:readonly（建议开） | 把提问人姓名显示在消息首行；没开也能用，只是首行显示 open_id 尾号 |

群里不 @ 机器人也要响应时，额外开「获取群组中所有消息」（im:message.group_msg），

并把插件配置 requireMentionInGroup 设为 false。

3. 事件与回调 → 事件配置：订阅方式选使用长连接接收事件，添加事件 im.message.receive_v1（接收消息 v2.0）。

4. 事件与回调 → 回调配置：订阅方式同样选使用长连接，添加回调 card.action.trigger（卡片回传交互）。

不开这一步，飞书里的选择题卡片点了没反应，只能靠直接回文字。

5. 应用功能 → 机器人：启用机器人。