前言¶
把 DeepSeek Harness 的 Agent 會話接到飛書聊天裏，常見的問題是：機器人怎麼收發消息、Agent 執行過程怎麼展示、工具調用結果怎麼呈現，以及沒有公網地址時如何保持連接。
下面介紹的 dsh-feishucard 是一個面向 DSH 的飛書橋接插件。它使用官方 SDK 的 WebSocket 長連接收發飛書消息，無需公網 IP、域名或隧道；在飛書卡片裏流式展示回覆過程，併爲每個聊天維護獨立會話。
這是什麼¶
dsh-feishucard 是 cmfok 維護的 DeepSeek Harness 與飛書（Lark）之間的自研橋接插件，許可證爲 MIT。
它解決的問題比較集中：
- 通過飛書官方 SDK 長連接接收和發送消息
- 在飛書卡片中流式更新 Agent 回覆
- 爲每個飛書聊天維護獨立 Agent 會話
- 提供基本聊天命令、處理中表情回執、主動發消息工具和審批卡片
- 支持多機器人配置和運行保活
單包內包含三類內容：Host 插件、長連接 helper 子進程，以及自動註冊 bundle 補丁。
核心功能¶
長連接收發¶
插件通過官方 SDK WebSocket 長連接接收飛書消息，再把消息注入 Agent 會話，並以交互卡片回覆同一會話。
這條鏈路不需要公網 IP、域名或隧道，適合本地或內網環境使用。
流式回覆卡片¶
飛書回覆採用卡片形式，支持：
- 即時
PATCH更新 - 過程話語內聯顯示
- 工具調用摺疊面板
- 限流、退避、熔斷和純文本兜底
當卡片鏈路不可用時，可以降級爲純文本回復。
每個聊天獨立會話¶
每個飛書聊天對應獨立的專屬 Agent 會話，會話狀態會持久化，並在重啓後恢復。
聊天內支持以下命令：
/new [名稱]
/switch <序號>
/list
/help
處理中表情回執¶
消息到達後，插件可以添加處理中表情回執。默認是 OnIt，也可配置爲 none 關閉。
模型工具¶
插件提供 feishu_send 模型工具，支持 Agent 主動發消息。
審批卡片¶
當會話需要審批時，飛書側會給出交互卡片，包含“允許一次”和“拒絕”按鈕。
審批卡片有以下行爲：
- 5 分鐘超時自動拒絕
- 會話取消時自動取消審批
多機器人支持¶
一個實例可以配置多個飛書機器人，每個機器人可以綁定各自的工作區。
保活機制¶
插件包含以下保活能力：
- helper 崩潰後自動重啓，並有
5s冷卻 - 憑據變更時自動重連
- 使用 SDK 自帶重連能力
安裝與啓用¶
使用以下命令安裝插件，然後重啓 dsh web：
dsh plugin --profile web add dsh-feishucard
dsh web
首次安裝時，如果 pnpm 攔截 protobufjs 構建腳本，並在日誌中出現 ERR_PNPM_IGNORED_BUILDS，需要允許該構建腳本。
將對應 profile 的 pnpm-workspace.yaml 中 allowBuilds.protobufjs 設爲 true：
allowBuilds:
protobufjs: true
然後重跑安裝命令：
dsh plugin --profile web add dsh-feishucard
本地開發安裝時，也可以使用本包目錄：
dsh plugin --profile web add <本包目錄>
或使用 file: 協議：
dsh plugin --profile web add file:<本包目錄>
飛書開放平臺配置¶
在飛書開放平臺側，需要完成一次性配置：
- 創建企業自建應用，並啓用機器人能力。
- 添加所需權限。
- 在事件與回調中訂閱長連接事件
im.message.receive_v1。 - 創建版本併發布。
需要配置的權限包括：
im:message.p2p_msg:readonly
im:message.group_at_msg:readonly
im:message:send_as_bot
im:message.reaction
其中 im:message.reaction 爲可選權限。
配置示例¶
插件配置獨立存放於：
~/.dsh-feishucard/feishu.config.json
配置文件與倉庫解耦。示例如下：
{
"bots": [
{
"name": "我的機器人",
"workspace": "C:\\path\\to\\workspace",
"appId": "cli_xxxxxxxxxxxxxxxx",
"appSecret": "your_app_secret",
"reactionEmoji": "OnIt"
}
]
}
配置支持熱更新，輪詢週期爲 10 秒，改完配置後無需重啓。
會話狀態持久化在：
~/.dsh-feishucard/state-<appId>.json
如果檢測到舊生態路徑：
~/.cc-connect/
且其中存在配置，插件首次啓動時會自動遷移一次。
典型用法¶
安裝並配置機器人後，在飛書聊天中可以直接使用：
/new
創建新會話。
/new 訂單排查
創建帶名稱的新會話。
/list
查看會話列表。
switch 2
或：
/switch 2
切換到第 2 個會話。
/help
查看幫助。
需要主動發消息時，可以由 Agent 調用 feishu_send 工具。需要審批時，按飛書卡片中的按鈕進行“允許一次”或“拒絕”。
開發與排障¶
本地開發時可以先安裝依賴：
npm i
語法檢查：
npm run check
冒煙測試：
npm run smoke
插件的依賴要求包括：
"@deepseek-ai/dsh-tools": "^0.1.0-rc.5"
以及：
"@larksuiteoapi/node-sdk": "^1.73.0"
在 Windows 下使用 file: 依賴安裝時，profile 中的 node_modules/dsh-feishucard 可能是實體副本，而不是軟鏈。修改源文件後，需要同步副本，或重新執行安裝命令後再重啓。
適用場景與注意¶
這個插件適合以下場景：
- 想在飛書裏直接使用 DSH Agent 會話
- 希望看到 Agent 的過程話語和工具調用面板
- 不想依賴公網 IP、域名或隧道
- 需要每個聊天獨立會話和重啓後恢復
- 需要審批卡片和主動發消息工具
使用前需要注意：
- 不要與其他 DSH 飛書插件同時安裝。同一飛書 App 的 WS 長連接會互踢。
- 插件以當前
dsh進程權限運行。安裝前應檢查源碼與許可證。 - 飛書開放平臺需要正確配置權限、事件訂閱和版本發佈。
- 首次安裝可能遇到
ERR_PNPM_IGNORED_BUILDS，需要允許protobufjs構建腳本。 - 本地開發使用
file:安裝時，注意 Windows 下副本同步問題。
鏈接¶
GitHub 地址：
