前言¶
DeepSeek Harness (DSH) 基於 Cordis 架構，其核心設計理念是“一切皆插件”。在構建多渠道智能體應用時，直接對接外部 IM 平臺（如微信、QQ、郵件等）通常涉及複雜的 Webhook 管理、會話上下文維護以及消息迴路的處理。dsh-im-gateway 旨在解決這一問題，它作爲 DSH 的一個插件，負責將外部 IM 消息橋接到 Harness 內部，並利用 DSH 的 Agent 機制處理邏輯，最後將回復路由回原渠道。
它是什麼¶
這是一個 DeepSeek Harness (DSH) 插件，由開發者 masquerator-coder 維護。它是一個開源工具（MIT 許可證），核心功能是實現一個多通道網關，支持將外部 IM 消息統一接入，併爲每個外部會話創建持久化的 Agent，從而保持對話上下文，同時確保不同渠道和會話之間的隔離。
核心功能¶
該插件主要提供以下能力：
* 多通道網關：支持 5G 消息、郵件、飛書、微信、QQ 和 HTTP 回調等多種接入方式。
* 持久化 Agent：爲每個外部聊天會話映射一個穩定的 Harness Agent，支持跨消息的上下文保持。
* 回覆路由：通過 rpcId 機制從全局會話流中獲取 Agent 回覆，並路由回原始發送渠道。
* 會話鍵控與隔離：基於 channel 和 chat_id 生成唯一的會話 ID，確保不同渠道或同一 ID 的不同消息來源不會互相干擾。
* 內置網關防護：包含訪問控制、去重、序列化、重試限制等安全與穩定性機制。
* IM 端確認：支持工具審批 (approval) 和用戶提問 (user-questions) 的 Agent 作用域水合事件。
安裝與前置條件¶
當前資料中未找到官方提供的自動安裝命令。該插件作爲獨立代碼庫存在，需根據環境要求進行配置。
環境要求¶
- Node.js:
^22.19.0或>=24.0.0 - 包管理器:
pnpm版本@11.25.0 - 依賴項:
@deepseek-ai/cordis(版本^4.0.4)@deepseek-ai/dsh-agent(版本>=0.1.0-rc.8 <0.2.0)@deepseek-ai/dsh-agent-default-model(版本>=0.1.0-rc.8 <0.2.0)
代碼結構¶
插件包含以下核心文件：
* lib/, src/: 核心源碼
* cordis.patch.yml: Cordis 補丁配置
* README.md: 說明文檔
* LICENSE: MIT 許可證
典型用法與邏輯¶
工作流程¶
外部 IM 平臺通過相應的通道傳輸（Webhook/WS/IMAP/Bot API）將消息發送給網關，網關將其注入到綁定了 Workspace 的持久化 Agent 中。Agent 的回覆通過 rpcId 聲明機制從全局會話流中獲取，並由網關通過同一條渠道發送回用戶。
會話鍵控與隔離¶
爲了確保會話的穩定性，插件使用哈希算法生成會話 ID：
SessionId = im-<sha1(f"{channel}:{chat_id}")[0:16]>
如果配置了顯式的工作目錄 (cwd)，鍵值會包含該目錄：
SessionId = im-<sha1(f"{channel}:{chat_id}@{cwd}")[0:16]>
這種設計使得同一個外部 chat_id 通過不同渠道（如郵件和 5G）到達時，會被視爲不同的會話。此外，cwd 也被納入鍵值，確保 Agent 始終運行在特定的 Workspace 中。
Agent 組成方式¶
DSH 網關中的 Agent 按照以下方式組合：
1. Real workspace attach：每個會話綁定到一個真實的 Harness Workspace（顯式 cwd 或插件的默認路徑），避免與持久化的 _no-cwd 日誌衝突。
2. Webhook-aligned composition：優先使用通道配置的模型提供者/模型，否則使用 DSH 運行時當前激活的模型；掛載配置好的 Agent 預設，並固定部署默認權限預設。
3. Cross-restart continuation：進程重啓時，通過 sessionQuery.observeSession 探測已存在的會話並恢復；僅新 ID 走 agents.create，重啓不會創建衝突。
4. rpcId reply claiming：每個用戶消息攜帶 rpcId，訂閱全局 session/event 流並精確獲取對應輪次的回覆序列。
內置網關防護¶
插件內置了一套防護機制，以保證消息處理的健壯性：
* 發送者訪問控制：配置 allowlist 後，僅白名單 senderId 可驅動 Agent，未授權消息在 Agent 介入前被拒絕。
* 入站去重：相同 chat + text 在 5 秒內重複發送會被抑制，防止平臺重放導致重複觸發模型調用。
* 會話級序列化：每個會話同一時間最多隻能有一個進行中的輪次，併發消息會排隊而非覆蓋。
* 來源元數據注入：僅在會話發送者或渠道變更時注入 <dsh_im_source> 標籤到 Prompt，避免歷史記錄中標籤氾濫。
* 有界投遞重試：回覆推送失敗時最多重試 2 次，每次失敗均記錄日誌，最終放棄時明確記錄 reply NOT delivered。
* 活躍會話複用：防止與已存在的 Agent 衝突。如果 Agent 已在 Web UI 中被打開，網關會複用該 Agent 而非重新創建或靜默失敗。
* 失敗永不靜默：Agent 獲取失敗、超時、模型錯誤或回覆爲空時，錯誤信息會回傳至原 IM 渠道（如 ⚠️ 處理失敗，未能回覆。原因：…）。
* 誠實連接狀態：
* 微信：依賴 getupdates 輪次，連續 10 次失敗（約 15 秒）將狀態降級爲錯誤。
* 中國移動 5G：獨立看門狗監控 Socket 狀態及 Ping/Pong 新鮮度，半開連接會被強制重連。
* QQ：僅在收到 READY/RESUMED 響應後才視爲啓動成功；遇到不可重試關閉碼（如 4013）會停止重連循環。
適用場景與注意事項¶
該插件適合需要在 DeepSeek Harness 中集成多渠道即時通訊能力的開發者。使用時需注意：
* 插件以當前 DSH 進程的權限運行，涉及文件系統操作，安裝前建議檢查源碼與許可證。
* 網關模塊使用 cordis.patch.yml 進行集成，需確保 DSH 環境兼容。
* 不同渠道（如 QQ 和微信）的配置需在 DSH 的 Plugins 頁面通過多通道設置 UI 進行配置。
總結¶
dsh-im-gateway 提供了一套從外部 IM 到 DeepSeek Harness 的完整鏈路方案，通過持久化 Agent 和嚴格的會話隔離機制，解決了多渠道接入時的上下文管理和消息路由問題。其內置的防護機制有效避免了消息丟失和狀態不同步，是構建企業級 IM 智能體網關的有力工具。
- 項目地址: https://github.com/masquerator-coder/dsh-im-gateway
- 插件目錄: https://www.skillhub.cn/plugins/masquerator-coder/dsh-im-gateway
