VenueLink VLAgent Electron / Node SDK

适用于 Electron 主进程或 Node 的展项接入 SDK。第一次对接请先看仓库里的 VLAgent SDK集成指南。

当前 0.1.0 提供：

• MQTT TCP 连接与自动重连
• 连接后发布 register（IP / MAC / 端口 / hostname）
• retained 在线心跳
• reportState / clearState：上报业务运行态（进度、音量等）
• 正常退出 online:false
• 异常退出 LWT online:false
• 读取 vlagent.json 配置

不提供：业务 cmd/ack、TCP/HTTP Server、设置页面、Server→Pad 转发。运行在 Electron 主进程或 Node，不要在渲染进程直接引用。

引用

展项工程：

pnpm add @venuelink/vlagent

未发 npm、或要改 SDK 源码时，也可用本地路径："@venuelink/vlagent": "file:../path/to/VL/packages/VLAgent.JS"（需先在该目录 pnpm build）。

Electron 主进程：

import { loadConfig, VLAgentClient } from "@venuelink/vlagent";
import { join } from "node:path";
import { app } from "electron";

const config = loadConfig(join(app.getAppPath(), "vlagent.json"));
const agent = new VLAgentClient(config);
await agent.start();

配置

创建 一份 vlagent.json。SDK 读它连中控；展项自己的通信代码（TCP/HTTP 监听、回执）也必须读同一份文件，不要另写一套 IP/端口。

{
  "deviceId": "",
  "brokerHost": "192.168.1.10",
  "brokerPort": 1883,
  "heartbeatIntervalMs": 3000,
  "reconnectDelayMs": 2000,
  "advertisePort": 9000
}

| 字段 | 谁填 | 含义 | |---|---|---| | deviceId | 中控签发 | 未入库可留空（SDK 生成临时 sessionId）。确认后写入正式 id。身份：待确认 agent-pending-{sessionId}，已入库 agent-{deviceId}。 | | mqttPassword | 确认入库后 | 中控签发；未入库留空。确认后与 deviceId 一并写回。 | | brokerHost / brokerPort | 人工 | 中控 VLServer 的地址，不是展项自己的地址。本机联调用 127.0.0.1；现场填中控局域网 IP，端口默认 1883。 | | advertisePort | 人工 | 展项程序真正监听、收中控指令的 TCP 端口。SDK 不会帮你开这个端口。展项通信代码必须读这个字段再 Listen。 | | heartbeatIntervalMs / reconnectDelayMs | 一般不用改 | 心跳间隔、断线重连等待。 |

IP / MAC 不用写进 JSON。 SDK 启动时会自动探测：选一张「能访问到 brokerHost」的本机网卡，把该网卡的 IPv4 和 MAC 上报给中控。

开发时怎么用这份配置

1. SDK：loadConfig("vlagent.json") 后 new VLAgentClient(config).start()。
2. 展项通信：同样读 advertisePort 再监听。
3. 中控设备档案若是 FixedTcp：目标就是「确认时的 IP + advertisePort」。两边不一致，指令发不到展项。

现场必须核对 IP

中控「待确认 Agent」里看到的 IP 只是 SDK 自动采到的候选，不是最终答案。

机器有多块网卡、VPN、虚拟网卡时，采到的 IP 可能 不是 展项程序对外收指令用的那张网。管理员确认前要问清楚：

• 展项 TCP/HTTP 实际绑在哪张网、哪个 IP？
• 中控能否访问这个 IP + advertisePort？

对不上就在确认界面改成通信用的 IP，再点确认。确认后中控才按这个地址发指令。

使用

import { loadConfig, VLAgentClient } from "@venuelink/vlagent";

const config = loadConfig("./vlagent.json");
const agent = new VLAgentClient(config);
await agent.start();

await agent.reportRegister();
await agent.reportState({
  mode: "manual",
  media: { id: "intro", playing: true, positionMs: 125000, durationMs: 600000 },
  audio: { volume: 0.6, muted: false }
});

await agent.stop();

本机示例：

cd packages/VLAgent.JS
pnpm example

先起 VLServer（MQTT 1883），再跑示例。把 examples/basic/vlagent.example.json 改成现场 deviceId / 中控 IP / 展项监听端口。

测试

dotnet build tests/VLAgent.Unity.BrokerHost
cd packages/VLAgent.JS
pnpm test

传输与兼容性

• Node 18+
• MQTT：TCP，默认端口 1883
• mqtt.js 5.x（与 VLClient 同类）