前言¶

在 DeepSeek Harness（DSH）生態中，智能體通常需要通過即時通訊（IM）平臺與用戶交互。如果爲每個平臺（如飛書、Telegram、Discord）單獨開發適配邏輯，會造成大量代碼重複。dsh-messaging 插件旨在解決這一問題，它提供了一套統一的接口，允許開發者配置一次，即可在飛書、Telegram、Discord 和企業微信之間切換。

核心能力¶

該插件基於插件架構設計，具備以下核心功能：

1. MessagePlatform abstraction：提供統一的平臺抽象層，屏蔽底層協議差異。
2. Plugin architecture：採用適配器模式，每個平臺作爲獨立的適配器接入。
3. Capability degradation：當平臺不支持某項功能時，自動觸發降級處理並提示用戶。
4. Markdown auto-downgrade：對於不支持 Markdown 渲染的平臺（如飛書），自動將 Markdown 轉換爲純文本。
5. Production-hardened：包含消息去重、逐聊序列化、自動 Token 刷新等生產環境特性。
6. CapabilitySet：允許智能體在執行前查詢當前平臺的能力列表。
7. Streaming buffer：將流式輸出的文本緩衝至回覆完成後再發送，避免出現殘缺消息。
8. Retry with backoff：內置重試機制，支持指數退避策略，並處理 Telegram 和飛書的限流響應。
9. Per-chat serialization：確保同一會話內的消息按順序處理。
10. Message dedup：通過 TTL 和上限機制過濾飛書等平臺的重複事件。

安裝與啓用¶

安裝插件需要使用 DSH 的插件命令。該插件由 andiven 維護，遵循 MIT 許可證。

dsh plugin --profile web add github:andiven/dsh-messaging

安裝完成後，需要在配置文件中啓用插件。插件通過 cordis.patch.yml 注入到 DSH 實例中。

典型用法¶

配置示例（以飛書爲例）：

# cordis.patch.yml
- id: messaging
  name: '@dsh-messaging/messaging'
  config:
    platform: feishu
    feishu:
      appId: env:FEISHU_APP_ID
      appSecret: env:FEISHU_APP_SECRET
      mode: websocket
    autoConnect: true

平臺配置要求¶

不同平臺需要不同的憑證和權限：

• Feishu：需在開放平臺創建自建應用，啓用 im:message 權限，訂閱 im.message.receive_v1 長連接，併發布應用。
• Telegram：通過 @BotFather 創建機器人並獲取 Token。
• Discord：在開發者門戶創建應用並添加 Bot，啓用“消息內容”權限意圖，使用 bot scope 邀請至服務器，獲取 Token。
• WeCom：在管理後臺創建自建應用，記錄 Corp ID、Secret 和 AgentId。入站消息需在後臺註冊 HTTP 回調 URL（若僅需發送消息可省略回調配置）。

適用場景與注意¶

該插件適合需要在單一 DSH 實例中集成多 IM 平臺的智能體項目。

已知限制：
* 飛書媒體發送：圖片、音頻、視頻和文件的發送功能尚未實現。
* 卡片消息降級：Telegram 和企業微信的卡片消息會降級爲格式化文本；Discord 的卡片消息會降級爲 Embed。
* 重連機制：Discord 網關重連爲盡力而爲模式，非可恢復關閉時會重新發起連接；無重連狀態保留機制，重啓可能導致隊列中的更新丟失。
* 單實例單平臺：每個 DSH 實例當前僅支持配置一種平臺。
* 無測試覆蓋：項目暫無測試套件。

短結尾¶

dsh-messaging 通過統一接口和自動降級機制，降低了多平臺 IM 對接的複雜度。開發者可訪問 GitHub 查看源碼或提交 Issue。