前言¶
在 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 目录页。
