前言¶
DeepSeek Harness (DSH) 採用插件化架構，旨在爲各類智能體提供統一的開發與運行環境。開發者在使用 DSH 開發應用時，往往需要對接多種消息渠道。dsh-weixin 是一款基於騰訊 iLink Bot API 的渠道插件，它允許 DSH 直接通過個人微信收發消息，從而繞過複雜的第三方網關配置。
插件概覽¶
該插件由維護者 5havv 開發，採用 MIT 許可證。它通過 npm 包的形式集成，與騰訊官方的 openclaw-weixin 及 Hermes 的微信適配器同源同協議。插件目前處於 v0.2 / M1–M4 階段，實現了掃碼登錄、長輪詢以及基本的消息收發能力。
核心功能¶
基於 iLink Bot API，該插件提供以下核心能力：
- 消息收發：支持文本、圖片、文件、語音和視頻的收發。入站媒體會自動下載解密並緩存，圖片可直接交給視覺模型，語音會收到騰訊後端下發的轉寫文本。
- 獨立會話：支持
per-peer模式，即每個聯繫人擁有獨立的 agent/session，互不干擾。 - 工具調用：註冊了
weixin_send工具，允許 agent 主動向特定聯繫人發送消息。 - 登錄方式：支持終端掃碼登錄，無需公網地址或 WebSocket。
- 憑證複用：支持從 Hermes 導入同號憑證，避免重複掃碼。
安裝與啓用¶
插件安裝後，DSH 會加載兩個獨立的 Cordis 插件組件：weixin（負責渠道服務與工具）和 weixin-bridge（負責消息路由與編排）。
官方安裝命令¶
dsh plugin --profile web add @5havv/dsh-weixin
開發期覆蓋層（可選）¶
若需本地調試，可以使用覆蓋層模式，但需先構建項目：
npm run build
dsh --profile web --patch ./examples/cordis.dev.yml
典型用法¶
安裝完成後，可以通過 npm scripts 進行基礎的連通性測試。
掃碼登錄¶
npm run smoke -- login
此命令會生成終端二維碼，掃碼後保存賬號信息。
消息監聽與收發¶
# 監聽並打印入站消息（含媒體下載解密）
npm run smoke -- listen
# 向指定賬號發送文本
npm run smoke -- send <accountId> <toUserId> 'hello'
# 發送本地文件
npm run smoke -- sendfile <accountId> <toUserId> ./photo.png '看圖'
適用場景與注意事項¶
適用場景¶
- 私聊場景：該插件使用個人微信 / iLink bot 身份。多數賬號類型無法接收普通微信羣消息，僅私聊穩定可用。
系統限制¶
- 單實例：同一 token 同時只能有一個消費者在線。本插件使用文件鎖機制保證這一點，若兩個實例同時啓動會報錯。
- 會話刷新：若聯繫人長期未發消息，
context_token會失效。此時發送消息會自動降級重試，若仍失敗需對方先發一條消息激活會話。 - 運行環境：插件依賴 Node.js 環境，要求版本 >= 22。
安全說明¶
插件註冊的 weixin_send 工具允許模型調用本地文件路徑。爲防止數據外泄，該路徑被限制在 mediaSendRoots 白名單內。默認值爲進程工作目錄和媒體緩存目錄。若微信號可能收到不可信消息，建議將其收窄至專用目錄。
總結¶
dsh-weixin 爲 DSH 生態提供了原生的微信連接能力，適合需要在微信環境中運行 DSH 智能體的開發者。通過掃碼登錄和工具集成，它可以快速搭建起基於微信的自動化服務。
