前言¶
在 DeepSeek Harness（DSH）裏做物聯網或消息驅動調試時，常見做法是另開 Mosquitto、MQTTX 或腳本，智能體側再單獨寫訂閱發佈邏輯。連接配置、消息日誌和 Agent 工具往往不在同一處，改 Broker 地址或重連時要來回切換。
dsh-mqtt-tools 把 MQTT 客戶端、本機可啓動的內嵌 Broker，以及九個 mqtt_* 智能體工具收進同一個插件：側邊欄 MQTT 面板負責人工操作，智能體與面板共用同一套連接與消息引擎。
這是什麼¶
維護者 GodLike2020，分類爲客戶端類 DSH 插件；倉庫 godlike2020/dsh-mqtt-tools，npm 包名 dsh-mqtt-tools（資料中當前版本 0.3.13，許可證 MIT，要求 Node ≥ 20）。
一句話定位：給 DeepSeek Harness 用的 MQTT 客戶端和內嵌 MQTT Broker——一個面板、九個 mqtt_* Agent 工具。
核心功能¶
面板：客戶端與服務端兩個標籤頁¶
客戶端標籤頁：管理命名連接、聊天式消息流、底部常駐發佈區（主題一行、消息框、發送；回車發送，Shift+回車換行；中文輸入法組字時的回車不會誤發）。支持 URL、clientId、賬號密碼、keepalive、clean session、重連間隔、協議 3.1 / 3.1.1 / 5.0；按 QoS 訂閱/退訂，QoS 0–2 發佈、retain、通配符、保留消息、斷線重連。改地址或賬號後點「連接」會先保存草稿再撥號；在線時改地址再保存會先斷開舊會話，避免界面顯示新地址卻仍在向舊 Broker 發消息。
服務端標籤頁：內嵌 Broker、在線客戶端列表、事件日誌；底部發布卡片與客戶端同款。可配置 host/端口、匿名或用戶表、隨 DSH 自啓動；支持 3.1 / 3.1.1 / 5.0、保留消息、持久會話、$SYS 開關、每客戶端訂閱列表。保留消息隨配置持久化，重啓後重放；可查看保留條數並一鍵清除。
消息日誌與主題¶
日誌帶方向、主題、UTF-8 或 base64 內容、QoS、retain、時間戳；支持分頁（默認從最新 100 條起）、過濾、暫停。界面支持亮/暗色，底色隨當前文字色推導。
九個智能體工具¶
與面板共用引擎：界面裏配好的連接智能體可直接用；智能體建的連接在界面裏也能看到。
| 工具 | 作用 |
|---|---|
mqtt_list |
列出連接與 Broker 狀態 |
mqtt_connect |
連接已保存連接或用 url 新建並連接 |
mqtt_disconnect |
斷開 |
mqtt_subscribe / mqtt_unsubscribe |
訂閱 / 退訂（持久保存） |
mqtt_publish |
經客戶端連接或內嵌 Broker 發佈 |
mqtt_messages |
讀最近消息，可按連接/來源/方向/主題過濾 |
mqtt_wait |
等待匹配消息（類似 mosquitto_sub），帶回溯窗口 |
mqtt_broker |
查看/啓動/停止/保存內嵌 Broker |
HTTP API（與面板同級）¶
面板沒有額外特權，與本機其他調用方走同一 API：
| 方法 | 路徑 | 作用 |
|---|---|---|
GET |
/dsh-mqtt-tools/api/state |
狀態與最近消息/事件 |
POST |
/dsh-mqtt-tools/api/command |
單條命令（需 x-dsh-mqtt-tools: 1 與同源校驗） |
GET |
/dsh-mqtt-tools/api/events |
SSE 推送 |
密碼字段只寫不讀（返回 hasPassword，不返回值）。
協議與內嵌 Broker 限制¶
內嵌 Broker 基於 aedes，原生 MQTT 3.1.1；3.1 與 5.0 在同一端口接入（5.0 經轉換層與 3.1.1 語義對齊，MQTT 5 獨有特性不實現）。各協議版本可在服務端頁簽單獨關閉。
內嵌 Broker 目前僅 明文 MQTT over TCP，無 WebSocket/TLS 監聽；暴露到局域網需自行放行防火牆。默認資源上限包括：maxConnections 200、connectTimeoutMs 10000、maxPayloadBytes 1 MiB、maxRetainedMessages 1000（可在服務端「資源上限」或 mqtt_broker save / API 修改）。
狀態持久化在 $DSH_HOME/dsh-mqtt-tools.json（默認 ~/.dsh/dsh-mqtt-tools.json），含連接配置（含密碼，權限等同系統賬號）、Broker 設置、$SYS 開關。
安裝與啓用¶
插件是 DSH Bundle（package.json 含 dsh.bundle.patch），已發佈到 npm。Bundle 安裝與 patch 走 DSH 安裝器，不會手改 profile 的 package.json / cordis.patch.yml。
下面介紹推薦方式：從 npm 安裝。
# 1. 讓 DSH 從 npm 裝上這個包（plugin_manager → install_bundle → target: dsh-mqtt-tools）
plugin_manager install_bundle { "target": "dsh-mqtt-tools" }
# 2. DSH 列出 “MQTT 工具” 後啓用它
若習慣自行管理 profile 依賴，資料中也給出：
dsh plugin add dsh-mqtt-tools
裝完重載一次 DSH，側邊欄出現 MQTT；無需額外配置即可打開空面板。
從源碼安裝時，可在本機目錄 npm install 後，通過 設置 → 插件 → 安裝 Bundle → 目標：本目錄，或 plugin_manager install_bundle 的絕對路徑目標（詳見倉庫 README）。
與舊版 DSH 的兼容性¶
DSH 0.1.7-rc.2 … 0.2.2-alpha.2（含桌面 0.2.1-rc.5）存在 profile 解析器與 readable-stream@4.x 相關的加載失敗問題。dsh-mqtt-tools 從 0.3.13 起在啓動時預載規避層（READABLE_STREAM=disable）；已修復的 DSH 上無害。不受影響的是未依賴 readable-stream@4.x 的插件，以及已修復的 DSH 版本。
典型用法¶
面板操作¶
- 客戶端 → 新建連接：填寫名稱與 URL，例如
mqtt://127.0.0.1:1883或mqtts://broker.example.com:8883（TLS 用 Node 默認證書鏈；自簽證書可在連接裏關閉rejectUnauthorized），按需填寫賬號、clientId、keepalive、協議版本。 - 連接後添加訂閱（如
sensors/+/temperature、#）。 - 在底部輸入框填主題與內容，回車發送；消息在輸入框上方滾動，最新在下。
- 服務端 → 啓動本機 Broker，其他設備連
mqtt://<本機>:1883；關閉匿名訪問時在頁籤添加用戶，客戶端連接表單填寫相同賬號。
智能體串聯示例¶
資料中的典型流程如下：
mqtt_broker start
mqtt_connect url=mqtt://127.0.0.1:1883 name=local
mqtt_subscribe connection=local topic="sensors/#" qos=1
mqtt_wait connection=local topic="sensors/#" timeoutMs=10000
mqtt_publish via=client connection=local topic="devices/lamp/set" payload="on" qos=1
內容能 UTF-8 解碼則返回文本，否則 base64；mqtt_publish 可傳 encoding: "base64" 發送二進制。
適用場景與注意¶
適合誰：在 DSH 內調試 MQTT 設備、主題與 QoS；需要本機快速起一個 Broker 做聯調；希望智能體通過 mqtt_wait / mqtt_publish 等工具參與自動化測試或運維腳本，且與 GUI 共用連接狀態。
運行與安全：插件在當前 DSH 進程權限下運行；狀態文件含明文密碼，權限取決於你的系統賬號。安裝前應閱讀倉庫源碼與 MIT 許可證，確認依賴（如 mqtt、aedes）符合你的合規要求。社區目錄 SkillHub 插件頁 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係，並非官方應用商店。
其他說明：$SYS/broker/... 默認不進消息日誌，可在服務端開關；界面語言跟隨 Harness 中英文設置。
結尾¶
dsh-mqtt-tools 把 MQTT 客戶端、內嵌 Broker、消息日誌和九個 mqtt_* 工具收斂到 DSH 側邊欄一塊麪板，減少「工具在外、Agent 在內」的割裂。進一步瞭解實現與更新，見 GitHub 倉庫 與 SkillHub 目錄頁。
