前言¶
DeepSeek Harness（DSH）把智能体能力拆成可插拔模块；要在 IM 里对话，常见做法是自建 Webhook、暴露公网端口或做内网穿透。团队已经在用飞书 / Lark 时，再维护一套入站回调往往成本高，也不利于在共享机器上隔离会话与文件权限。
下面介绍社区插件 dsh-plugin-feishu（维护者 wooxi，分类：联网工具）：它把 DSH 接到飞书频道，通过出站 WebSocket 长连接收事件，无需公网 IP、Webhook 地址或端口转发。卡片侧支持 CardKit 2.0 流式更新、思考折叠、工具调用进度与多模态收发；配置集中在 DSH Web 设置页，而不是手写配置文件。
这是什么¶
dsh-plugin-feishu 是 DSH 的 Feishu / Lark 频道（channel）插件：在飞书客户端里与你的 Harness 智能体对话，答案以单张卡片随推理与工具执行逐步填充，而不是等到结束时才丢一大段纯文本。
- 仓库：wooxi/dsh-plugin-feishu
- 社区目录：skillhub.cn 插件页
- 许可证：MIT（以仓库说明为准）
- 运行环境：DSH
0.2.x、Web profile；Node>=20；需自建飞书应用并启用长连接事件订阅
社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行查看源码与许可证。插件以当前 DSH 进程权限运行，可读写你配置的工作目录并执行智能体调用的命令，部署前请确认机器与账号边界。
核心能力¶
流式卡片与对话体验¶
发送消息后，飞书内会打开一张卡片并实时更新：
- 工具调用跟踪：搜索、Shell、读文件等工具以状态行展示，含参数与耗时。
- 思考折叠：推理内容在折叠区流式展示；正式回答开始后折叠收起，避免卡片过长。
- 页脚统计：一行汇总状态、墙钟时间、模型名、Token 与缓存命中率（示例格式：
✅ 已完成 · 24s · … · 33.0k tokens · 缓存 90%）。 - Markdown 渲染：标题、列表、链接、代码块与表格按预期排版。
- 线程回复：每条回答回复原消息，而不是另起一条游离消息。
图形化设置，而非改配置文件¶
在 DSH Settings → Feishu Channel 中完成凭证、Owner、目录与功能开关：
- Save & verify：保存后对飞书鉴权、发送真实测试消息并 provisioning 工作区。
- 二维码配对：飞书 App 扫码后自动填入 Open ID。
- 密钥留在服务端：App Secret 不回传浏览器，界面仅显示掩码。
功能开关（README 表格）：
| 开关 | 作用 |
|---|---|
| CardKit 2.0 streaming | 流式更新卡片，而非纯文本回复 |
| Thinking folds | 可折叠展示推理 |
| Tool tracker | 以状态行展示工具调用 |
| Multimodal I/O | 接收图片并回传本地图片 |
| Group chat | 允许在群聊中 @ 机器人 |
面向共享机器的设计¶
- 单一 Owner：机器人可动文件与命令，仅绑定一个飞书账号；Owner 留空时，首个发消息者会被绑定并提示，之后其他人会被拒绝。
- 独立工作区：飞书会话归入专用 workspace，不与浏览器会话混用，重启后仍保留。
- 独立目录：附件、智能体产物与消息审计日志集中在你指定的文件夹。
- 无入站端口：连接仅为出站方向。
安装与启用¶
官方安装步骤如下。先添加插件，再以 Web profile 启动 DSH：
dsh plugin --profile web add dsh-plugin-feishu
dsh --profile web
然后在 DSH Settings → Feishu Channel 粘贴飞书应用的 App ID、App Secret，点击 Save & verify。
飞书开放平台配置¶
在飞书开放平台的自建应用中：
- 权限：
im:message、im:message.p2p_msg:readonly、im:resource；若开启群聊，另加im:message.group_at_msg:readonly。 - 事件：订阅模式选 「通过长连接接收事件 / Receive events through long connection」，并添加
im.message.receive_v1与card.action.trigger。 - 发布：变更权限或事件后需发布版本。
README 指出：第 2 步常被遗漏；若「能发不能收」，优先检查是否仍为 Webhook 模式而非长连接。
典型用法流程¶
- 按上一节在飞书开放平台完成权限、长连接事件与发布。
- 在 DSH 中安装插件并以
dsh --profile web运行。 - 在 Feishu Channel 设置页填写凭证，Save & verify；按需扫码绑定 Owner、选择数据目录并打开 CardKit / 思考折叠 / 工具跟踪等开关。
- 在飞书私聊（或开启群聊开关后在群内 @ 机器人）发消息；观察卡片流式更新、工具行与折叠推理，并在同一线程内收到最终回答。
多模态开关打开后，可收发图片；具体行为以插件当前版本实现为准。
适用场景与注意事项¶
更适合：团队已用飞书协作、希望在不暴露公网入口的前提下，把 DSH 智能体接到 IM；需要在卡片里直观看到工具进度与推理过程；机器可能被多人共用，但需要严格限定「谁能让机器人动文件与命令」。
务必注意：
- 依赖 DSH Web profile 与 Node 20+；与 DSH
0.3.x的兼容范围以package.json的engines.dsh为准（当前资料为>=0.2.0 <0.3.0）。 - 插件权限等于 DSH 进程权限；Owner 机制是安全边界，不要随意留空后在生产环境长期开放「首绑即用」。
- 若在 provisioning 之前已有会话，可能仍落在「未分组」；对新环境执行一次 Save & verify 可创建工作区（历史会话位置不变）。
故障排查（资料摘录）¶
ERR_PNPM_IGNORED_BUILDS: protobufjs：pnpm 阻止了飞书 SDK 传递依赖的 postinstall。在对应 profile 的 pnpm-workspace.yaml 中允许构建后重装：
# ~/.dsh/profiles/<profile>/pnpm-workspace.yaml
allowBuilds:
protobufjs: true
消息能收到但没有回复：事件订阅仍为 Webhook；改为长连接并发布版本。
会话落在 Ungrouped：执行一次 Save & verify 以 provisioning 工作区。
结尾¶
dsh-plugin-feishu 把 DSH 智能体搬进飞书：出站长连接免去公网回调，CardKit 流式卡片承载工具进度、思考折叠与 Markdown 回答，设置与验连通都在 Web UI 完成。进一步了解实现与版本说明，见 GitHub 仓库与 SkillHub 目录页。
