| name | tier0-sdk-mq |
| version | 0.1.0 |
| description | Tier0 SDK MQ 模块 — MQTT over WebSocket 消息队列封装。支持懒连接、自动重连、断连重订阅、QoS 1、通配符 #/+. triggers: Tier0, SDK, MQ, MQTT, WebSocket, 消息队列, 订阅, 发布 |
| metadata | {"requires":{"npm":["@tier0/sdk"]},"hermes":{"tags":["sdk","mq","mqtt","websocket","subscribe","publish"]}} |
tier0-sdk-mq — 消息队列(MQTT over WebSocket)
何时使用本 Skill
应该使用
- 需要实时订阅 Tier0 UNS 数据点(温度、状态、告警等)
- 需要向设备或系统下发指令(写数据点、触发动作)
- 需要接收 Flow(Node-RED)发布的事件消息
- 前端项目需要 WebSocket 实时推送
不应该使用
- 查询历史数据或当前快照 → 走
openapi/SKILL.md(REST API 更适合查询场景)
- 管理 Flow/UNS 节点元数据 → 走
openapi/SKILL.md
- 非 MQTT 协议通信 → MQ 模块仅支持 MQTT over WebSocket
不可违反规则
- URL 和认证从环境变量读取 — 代码中不直接传
url / password,除非覆盖
- 订阅 QoS 固定为 1 — 内部自动使用
qos: 1,publish 默认 qos: 0(可覆盖)
- handler 接收 (topic, payload) 字符串 — payload 已由 Buffer 转为 string,JSON 需自行
JSON.parse
- 通配符只支持 # 和 + —
# 匹配多层,+ 匹配单层,不支持其他通配符
- 断连后自动重订阅 — 依赖 mqtt.js 自动重连 + SDK 在 connect 回调中恢复订阅,无需手动处理
子技能路由
| 意图 | 加载文件 | 说明 |
|---|
| 快速开始与配置 | references/quickstart.md | 环境变量、订阅、发布、事件监听 |
环境变量
| 变量 | 必需 | 说明 |
|---|
TIER0_MQTT_URL / VITE_TIER0_MQTT_URL | 是 | MQTT WebSocket 地址,如 wss://mqtt.tier0.cloud |
TIER0_API_KEY / VITE_TIER0_API_KEY | 是 | 认证密钥(作为 MQTT password) |
核心概念
| 概念 | 说明 |
|---|
| Topic | MQTT 主题路径,如 Plant/Line1/Metric/Temperature |
| Handler | 回调函数 (topic: string, payload: string) => void,payload 为字符串 |
| QoS | 服务质量:订阅固定 QoS 1,发布默认 QoS 0 |
| 通配符 # | 匹配多层,如 home/room/# 匹配 home/room/temp、home/room/living/light |
| 通配符 + | 匹配单层,如 home/+/temp 匹配 home/bedroom/temp 但不匹配 home/bedroom/living/temp |
快速示例
订阅实时数据(极简)
import { Tier0MQClient } from '@tier0/sdk/mq';
const client = new Tier0MQClient();
client.subscribe('Plant/Line1/Metric/Temperature', (topic, payload) => {
const data = JSON.parse(payload);
console.log(topic, data);
});
发布指令
import { Tier0MQClient } from '@tier0/sdk/mq';
const client = new Tier0MQClient();
await client.publish('Device/PLC1/Cmd', {
action: 'start',
param: { speed: 100 },
});
事件监听
const client = new Tier0MQClient();
client.on('connect', () => console.log('已连接'));
client.on('disconnect', () => console.log('已断开'));
client.on('error', (err) => console.error('错误:', err));