前言¶
如果你已经在本地运行 DeepSeek Harness（DSH）agent，希望从飞书（Lark）里直接提问、跟进长任务，而不是只在 Web UI 里操作，下面介绍一个 DSH 插件：@kriskwok/dsh-feishu-gateway。
它把飞书消息路由到 DSH agent，并支持持久会话、Markdown 回复、流式进度卡、原生 Typing reaction、审批 / 问答点击卡，以及可选的主动推送接口。
这是什么¶
kriskwok/dsh-feishu-gateway 是一个 DeepSeek Harness-native 的飞书 gateway 插件。
它通过飞书长连接接入，不需要公网 webhook URL。飞书私聊消息或群内 @bot 消息可以进入 DSH session，DSH agent 的回复会以 Markdown 富文本形式发回飞书。
仓库地址是：
https://github.com/kriskwok/dsh-feishu-gateway
核心能力¶
该插件主要提供以下能力：
1、从飞书与 DSH agent 对话，支持私聊和群内 @bot。
2、使用飞书长连接接入，不需要公网 webhook URL。
3、持久会话：飞书对话或群 topic/thread 会映射到 DSH session，会话映射在重启后保留。
4、支持 /new 开始新会话，也支持“另起会话”“新会话”“重新开始”“换个话题”等说法。
5、Markdown 富文本回复，使用 post message 和 md tag，可呈现加粗、行内代码、列表、链接等内容。
6、处理过程中显示原生 Typing reaction；失败时会换为 CrossMark。
7、长任务流式进度卡片，支持 stream 和 final 模式。
8、审批和 ask_user_question 的点击回答卡片，可以点击按钮完成允许 / 拒绝或选择选项。
9、可选管理 HTTP API /api/push，可主动推送文本、Markdown、卡片。
10、Web-only 的 dsh-ui interactive fences 在飞书端会降级为一行可读提示，而不是输出原始 JSON。
前置条件¶
使用这个插件前，需要准备：
1、已安装并构建 DeepSeek Harness，也就是 dsh CLI 可用。
2、已配置 DEEPSEEK_API_KEY。
3、飞书开放平台自建应用，并启用 bot capability。
4、飞书权限：
im:message
im:message:send_as_bot
可选权限：
im:message:send_as_bot:readonly
该权限用于读取内容。配置完成后需要发布版本。
5、在 Events & callbacks 中选择 long connection，并订阅：
im.message.receive_v1
卡片按钮点击事件也通过长连接下发：
card.action.trigger
6、Node 版本要求来自 package.json：
^22.19.0 || >=24.0.0
安装与启用¶
资料中说明，这个插件的安装不是单一的 dsh plugin add 命令，而是基于 npm/pnpm profile 的手动安装。
推荐做法是把 gateway 挂载到 web profile。这样 DSH Web UI 启动时，也会启动飞书 gateway，并且共用同一个 DSH agent。
1、修改 web profile 的 package.json¶
编辑：
~/.dsh/profiles/web/package.json
添加 @kriskwok/dsh-feishu-gateway 依赖，并把它加入 DSH bundle 列表。
示例结构如下：
{
"name": "dsh-profile-web",
"private": true,
"dependencies": {
"@kriskwok/dsh-feishu-gateway": "^0.2.0"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"@kriskwok/dsh-feishu-gateway"
]
}
}
}
这一步的作用是让 web profile 知道要加载飞书 gateway bundle。
2、安装依赖¶
进入 web profile 目录并安装依赖：
cd ~/.dsh/profiles/web && pnpm install
3、填写飞书应用配置¶
编辑：
~/.dsh/profiles/web/cordis.patch.yml
填入飞书应用凭据。示例配置如下：
- id: feishu-gateway
config:
feishu:
appId: cli_xxxxxxxxxxxxxxxx
appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
http:
port: 3100
token: your-token
其中 feishu.appId 和 feishu.appSecret 是必填项。http 部分用于可选管理 API。
4、启动 web profile¶
启动或重启：
dsh --profile web
也可以运行仓库脚本，默认挂载到 web profile：
./scripts/create-profile.sh
如果需要创建独立 feishu profile，可以使用：
./scripts/create-profile.sh --standalone
典型用法¶
私聊或群聊接入¶
在飞书私聊中直接向 bot 发消息，或者在群内 @bot 发消息，消息会被路由到 DSH agent。
开始新会话¶
发送：
/new
也可以发送：
另起会话
新会话
重新开始
换个话题
这些说法都会开始新的 DSH session。
群内 topic 隔离¶
在飞书群中，每个 topic/thread 对应一个独立的 DSH session。该 topic 内的消息会保持在同一个 session 中，直到发送 /new。
控制群内回复策略¶
可设置：
feishu.replyMode: at
或：
feishu.replyMode: all
at 是默认值，表示群内仅在被 @ 时回复。all 表示回复群内每条消息。
控制长任务进度展示¶
可设置：
reporting.mode: stream
或：
reporting.mode: final
stream 是默认值，表示使用流式进度卡。final 表示只接收最终结果。
审批与问答¶
DSH agent 的权限审批或 ask_user_question 可以渲染为飞书互动卡片。用户可以点击按钮完成允许、拒绝或选项回答。
Web-only 组件降级¶
某些 dsh-ui interactive fences 只在 Web UI 中渲染。在飞书端，它们会被降级为一行可读提示，避免直接输出原始 JSON。
适用场景与注意¶
适合以下场景：
1、你已经在本地运行 DSH agent，并希望在飞书中继续对话。
2、你希望飞书群里的不同 topic/thread 对应不同 DSH session。
3、你需要在飞书中查看长任务的流式进度。
4、你希望审批和 ask_user_question 可以通过卡片按钮完成。
5、你希望不暴露公网 webhook URL，使用飞书长连接接入。
需要注意：
1、该插件会挂载到 DSH profile，并随 dsh 进程运行，因此会以当前 dsh 进程权限执行。安装前建议检查源码、依赖和配置。
2、仓库许可证为 MIT。
3、Typing reaction 和卡片按钮需要 bot 能交互消息，依赖 im:message 权限。如果 reaction API 被拒绝，gateway 会回退到 hintText 消息。
结尾¶
kriskwok/dsh-feishu-gateway 的价值，是把飞书变成一个不需要公网 webhook 的 DSH agent 入口：私聊、群聊、topic 隔离、长任务进度、审批点击和 Markdown 回复都落在飞书消息流里。
仓库地址：
https://github.com/kriskwok/dsh-feishu-gateway
