前言¶
在 DeepSeek Harness（DSH）裏跑智能體，常見入口是 Web UI 或 Webhook。若希望用戶在微信、QQ、郵箱、5G 消息、飛書等現成渠道里連續對話，往往需要自建轉發層，還要自己保證「每個聊天有獨立上下文、進程重啓不斷話、回覆走回原通道」。重複實現這些細節，維護成本很高。
下面介紹社區插件 dsh-im-gateway（維護者 fuqiang-lab）：在 DSH（Cordis）進程內做多通道入站、按聊天映射持久 Agent、再按 rpcId 從全局會話事件流取回回覆並下發。插件在 GitHub 上爲 MIT 許可，當前 package.json 版本爲 0.1.0，分類上常被標爲模型推理相關能力（GitHub 約 1 star，2026-11-10）。
這是什麼¶
dsh-im-gateway 是 DSH 的 IM 網關插件，一句話概括：外部 IM → 網關通道 → 與工作區綁定的持久 Harness Agent → 同一通道回傳助手回覆。
它同時提供遺留的單 HTTP Webhook，以及在 DSH 插件 頁本 bundle 卡片上的多通道配置界面，覆蓋六類通道：微信（ilink bot）、QQ（官方 bot）、郵箱 Email（SMTP/IMAP）、中國移動 5G 消息（WebSocket）、飛書（官方 bot）、通用 HTTP 回調。
核心功能¶
入站、橋接、出站¶
- Inbound：多通道網關接收各 IM 平臺消息（Webhook / WebSocket / IMAP / QQ bot / ilink 等）。
- Bridge：每條消息注入與外部聊天穩定映射的 持久 Harness Agent，同聊天跨消息保留上下文，不同聊天、不同通道彼此隔離。
- Outbound：助手回覆通過全局
session/event流上的 rpcId claiming 採集，並經 收到該消息的同一通道 送回（有界重試）。
README 中的數據流示意如下：
external IM --POST--> [channel transport] -> [workspace-attached Agent/session per chat]
^ |
| global session/event stream (rpcId claim)
+-- <-- same channel delivers <-- [collected reply]
Agent 與會話：與 DSH Webhook 路徑對齊¶
- 真實工作區掛載：會話掛在真實 Harness workspace（顯式
cwd，否則插件默認~/.dsh/im-workspace），避免與_no-cwd持久日誌衝突。 - 模型與預設：
installModelSelection優先用通道顯式 provider/model，否則用 DSH 運行時當前模型；掛載配置的 agent preset，並固定部署默認 permission preset。 - 跨重啓續聊：重啓後通過
sessionQuery.observeSession探測已有 stable session，用agents.resume(...)恢復；僅全新 id 走agents.create(...)。 - 回覆採集：入站消息攜帶不透明
rpcId；每輪等待器訂閱全局session/event，認領該輪的user/message → assistant/message → turn/end，避免競態與whenIdle()輪詢。
會話鍵與隔離¶
每個聊天對應穩定 session id，形如 im-<sha1(f"{channel}:{chat_id}")[0:16]>；若配置了工作目錄（通道 cwd 或設置卡「全局默認工作目錄」），則鍵中納入 cwd。
- 通道參與鍵：同一外部
chat_id經不同通道（如郵件與 5G 消息）不會共用會話。 - 工作目錄參與鍵：DSH 在創建時固定
cwd，改目錄即在新 workspace 開啓新對話，舊會話仍在 Web UI 可打開。 - generation（
im/im-g<N>）：/new可讓同聊天開啓新輪次而不銷燬舊會話。
網關內置保護¶
資料中明確列出的機制包括：可選 allowlist 發送方控制；5 秒內相同 chat + text 去重；每會話串行一輪對話；來源變化時注入 <dsh_im_source>；回覆最多 2 次投遞嘗試；Web UI 已打開同會話時複用 live agent（createOrAdopt 語義）；失敗時在同聊天返回可見錯誤（含 60s agent 獲取超時）；微信 / CMCC / QQ 等通道的誠實連接狀態與錯誤碼處理。
IM 側審批與用戶追問¶
對網關創建/恢復的 Agent，會安裝 bridge answerer：DSH 的 approval/request、user-questions/request 可通過同一 IM 通道向用戶提問；IM 不可達時 next() 回退到 Web answerer，避免純 Web 會話被誤傷。
聊天內斜槓命令¶
在成爲模型 prompt 之前，網關自行處理下列命令（不進入模型上下文）：
| 命令 | 作用 |
|---|---|
/status |
會話 id、generation、工作目錄、live agent、permission preset |
/new [工作目錄] |
爲本聊天開新會話，可選絕對路徑；舊會話保留 |
/perm [preset] |
查看或切換 permission preset |
/help |
命令列表 |
/new 帶相對路徑會被拒絕；generation 游標爲進程內內存，重啓後各聊天回到配置目錄所決定的會話。
安裝與啓用¶
插件以 bundle（推薦）或本地源碼 overlay（開發）兩種形式分發。bundle 加載已提交的 lib/index.js，安裝時不運行 prepare/postinstall。
README 給出的 bundle 安裝示例（請將 demo 換成你的 profile 名，將 you 換成你要添加的 Git 倉庫 owner；本插件上游倉庫爲 fuqiang-lab/dsh-im-gateway）：
dsh plugin --profile demo add github:you/dsh-im-gateway
也可在構建產物目錄執行 pnpm pack 後安裝 tgz（README 示例）：
dsh plugin --profile demo add ./dsh-im-gateway-.tgz
運行環境要求（來自 package.json）：Node ^22.19.0 || >=24.0.0；peer 依賴由當前 DSH 環境解析，無需自行重複安裝 @deepseek-ai/cordis 等。
安裝後，bundle 通過 cordis.patch.yml 插入 im-gateway 行；可在 profile 自己的 cordis.patch.yml 中覆蓋配置（後加載層按行覆蓋，需 restate 全部鍵）。
典型用法¶
在插件頁配置通道¶
- 打開 DSH 側邊欄 插件。
- 在 已安裝 中進入
dsh-im-gateway卡片。 - 在包描述與通道列表之間的管理 UI 中新增通道；各類型帶有預填模板，一般只需補全密鑰、賬號或掃碼（微信 ilink 掃碼綁定等）。
各通道需填寫項與傳輸方式見 README 表格（如 QQ 需 q.qq.com 創建的 AppID/AppSecret，飛書 SDK 已 vendored 至 lib/vendor/ 等）。
與 Agent 對話¶
用戶在外部 IM 中發送普通文本即可觸發一輪模型回覆；需要工具審批或追問時，按上文 bridge answerer 在 IM 中交互。運維可用 /status 確認當前會話與工作目錄，用 /new 在同聊天切換工作區或重新開始一代對話。
遺留 HTTP Webhook¶
除多通道 UI 外，插件仍保留單 HTTP Webhook 路徑，適合已有回調集成；細節以 README「Usage」及通道專節爲準。
適用場景與注意¶
適合誰：已在 DSH 上部署 Cordis 插件體系、希望用國內常見 IM 或郵件作智能體前端，且需要按聊天持久上下文、與 Web UI 會話可並存操作的團隊或個人。
權限與安全：插件與當前 dsh 進程同一權限 運行，可訪問其所配置的工作目錄與模型憑證。安裝前請閱讀源碼與 MIT 許可證，按需配置 allowlist、secret 與網絡暴露面；空 allowlist 表示允許所有發送方，需依賴密鑰或內網隔離。
生態說明：DeepSeek Harness 主張「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係，不宜當作官方應用商店。
開發 overlay：本地迭代可對 src/ 使用 --patch（見 README「Load the local source overlay」）；修改 src/ 後須 pnpm build 並提交 lib/，否則 Git 安裝不會自動構建。
結尾¶
dsh-im-gateway 把多通道 IM 收發、會話鍵隔離、rpcId 回覆認領和 IM 側審批橋接收斂進一個 DSH 插件，降低「聊天軟件裏用 Harness Agent」的集成工作量。進一步瞭解可看社區目錄頁與倉庫 README：
