前言¶
如果你已經在本地運行 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
