前言¶
在 DeepSeek Harness（DSH）裏跑 agent，若要把對話和工具結果推到飛書，常見做法是簡單橋接：文本能發出去，但 Markdown 表格會變成豎線串，代碼塊容易被吞，標題層級也會塌成一段。入站若只靠輪詢或短連接，任務執行中晚到的消息往往只能排隊，體驗和上下文連續性都差一截。
dsh-hermes-feishu 是社區維護的 DSH 客戶端類插件（維護者 lishuaibing521），把出站渲染、入站 WebSocket 長連接、13 個飛書操作工具、Web 設置頁、語音與媒體、以及模型故障轉移鏈收進一個 bundle。下面按安裝、配置和實際能力說明用法與約束。
這是什麼¶
一句話：DeepSeek Harness 的飛書 / Lark 通道——出站支持圖文卡片與原生表格組件，入站走長連接；附帶 Web 配置界面與一組飛書 API 工具。
插件 manifest 依賴 dsh.bundle.patch，通過 dsh plugin add 識別爲可安裝 bundle。運行時依賴 @deepseek-ai/schemastery 與 @larksuiteoapi/node-sdk；渲染、消息路由、卡片構建與媒體處理在插件內自研，未引入第三方 Markdown 渲染庫。許可證爲 MIT（package.json 版本 1.0.0）。
出站與入站分別解決什麼¶
出站按內容類型拆開發送，避免「全當純文本」：
- 普通文本 → 飛書
text消息 - Markdown → Schema 2.0 交互卡片（
wide_screen_mode） - Markdown 表格 → 飛書原生
table組件（columns+rows），不是 markdown 字符串 ##及更深標題 → 轉成粗體（飛書卡片不認多級標題）- 代碼塊 → 單獨成行，降低被吞的概率
入站走 WebSocket 長連接。agent 正在執行任務時，新到的消息不會排隊等待下一輪，而是插入當前這一輪繼續執行。
核心功能¶
Web 設置頁¶
安裝後在 dsh「設置 → 插件配置」中可見六個分組：
- 飛書應用 — App ID / Secret、服務區域（飛書 vs Lark）
- Agent 與模型 — 主模型與備用模型鏈（兩級聯動下拉）
- 進度氣泡 — 思考內容與工具調用的實時顯示、工具預覽截斷長度
- 媒體 — 圖片生成與識別的 provider / 模型
- 語音 — STT / TTS 的 provider、語言、音色、語速、音調、音量
- 聯網搜索 — search provider、fetch provider
各 provider 運行時從已註冊插件動態讀取，只列出已配好的項；密鑰僅在服務端讀取，不下發前端。
13 個飛書工具¶
| 工具 | 作用 |
|---|---|
feishu_send_message |
主發送入口，按內容自動判定 text / 卡片 |
feishu_send_card |
強制發交互卡片（含表格渲染） |
feishu_send_file |
發文件，按擴展名路由（如 ogg→語音、mp4→視頻） |
feishu_send_image |
發圖片 |
feishu_send_voice |
文本合成語音氣泡 |
feishu_reply |
回覆某條消息 |
feishu_edit_message |
編輯已發消息（可用於進度更新） |
feishu_delete_message |
撤回消息 |
feishu_download |
下載消息中的圖片 / 文件 |
feishu_transcribe |
語音轉文字 |
feishu_bot_info |
查詢機器人身份 |
feishu_render_preview |
只渲染不發送，調試卡片結構 |
feishu_parse_message |
歸一化一條入站消息 |
可靠性與交互¶
- 模型故障轉移：主模型失敗時按備用鏈依次切換，走 dsh 原生
agent/requestwaterfall，不重建 agent、不重放消息。 - 審批兜底：工具需人工確認時發飛書卡片，用戶點「允許 / 拒絕」；否則 dsh 會 fail-closed，任務可能無聲失敗。
- 進度氣泡：思考與工具調用在同一條氣泡裏更新，減少刷屏；思考過程默認關閉（
thinkingEnabled默認false），需在「進度氣泡」分組中開啓。 - 會話持久化：會話映射落盤，dsh 重啓後可接續上下文。
安裝與啓用¶
DSH 生態裏是「一切皆插件」；社區目錄頁在 SkillHub，與 DeepSeek / 幻方無官方從屬關係。安裝前建議自行查看 GitHub 源碼與 MIT 許可證——插件以當前 dsh 進程權限運行。
先做插件安裝（官方 README 命令，需 --profile web）：
dsh plugin --profile web add github:lishuaibing521/dsh-hermes-feishu
裝完重啓 dsh web（將 <你的 dsh 目錄> 換成本機路徑）：
powershell -ExecutionPolicy Bypass -File <你的 dsh 目錄>/start-dsh-hidden.ps1 -Target web
飛書開放平臺側需開啓應用的機器人能力，以及在事件訂閱裏啓用長連接模式。僅開出站能力時仍可用工具發消息，但收不到入站消息。
配置¶
憑據通過環境變量配置，寫在 ~/.dsh/.env：
| 變量 | 說明 |
|---|---|
FEISHU_PLUGIN_APP_ID |
飛書應用 App ID |
FEISHU_PLUGIN_APP_SECRET |
飛書應用 App Secret |
FEISHU_PLUGIN_DOMAIN |
feishu（國內）或 lark（國際），默認 feishu |
FEISHU_PLUGIN_CHAT_ID |
默認發送目標（oc_ 羣或 ou_ 用戶） |
FEISHU_PLUGIN_BOT_NAME |
卡片標題中的機器人名 |
變量名不能使用 DSH_ 前綴——dsh 會把 DSH_* 視爲僅可由啓動環境設置的 bootstrap 變量，寫入 .env 會導致啓動失敗。同類限制還包括 XDG_、DYLD_、BASH_FUNC_ 前綴，以及 PATH、HOME、NODE_OPTIONS、GIT_* 等具體名字。
多數設置在 Web 設置頁保存後即時生效；App ID、Secret、域名等與長連接綁定的項修改後需重啓 dsh web。
典型用法與自測¶
日常對話與 agent 輸出會經通道自動路由到 text 或卡片；需要強制卡片或調試結構時，agent 可調用 feishu_send_card 或 feishu_render_preview。入站消息經長連接進入 DSH 後，由 feishu_parse_message 等工具配合會話映射處理。
倉庫內測試腳本（README 原文）：
node test/run.mjs # 渲染 / 入站 / 路由 / 音頻解析
node test/load.mjs # 插件加載與工具註冊契約
node test/probe.mjs # 真機：token / 機器人身份 / 會話 / 渲染鏈路
node test/e2e.mjs # 端到端：構建 → 實發 → 讀回 → 撤回
probe 與 e2e 會真實連接飛書，需先配好上述環境變量。
適用場景與注意¶
適合：已在 DSH web profile 上跑 agent、希望飛書作爲雙向通道（含表格與卡片質量、進度氣泡、工具審批）的團隊或個人。
務必留意的約束（來自 README「已知約束」）：
chat_id必須是機器人已在的會話，否則發送可能報230002。- 音頻時長解析僅認 OGG/Opus；其他格式時長回 0。
- 語音識別與合成依賴獨立 dsh 插件（如
dsh-baidu-stt/dsh-baidu-tts）；未安裝時下拉爲空，文字鏈路仍可用。 - 同一飛書應用同時只能有一條長連接；若其他工具已佔用同一應用，此處無法連上。
結尾¶
經過上面的步驟，你可以在 DSH 裏用一條長連接收飛書消息，並把 agent 輸出按類型發到 text、卡片或原生表格，同時用 Web 頁配模型鏈、語音與媒體 provider。目錄與源碼：
- 社區目錄：https://www.skillhub.cn/plugins/lishuaibing521/dsh-hermes-feishu
- GitHub：https://github.com/lishuaibing521/dsh-hermes-feishu
