Node.js SDK

Node.js SDK 适合 TypeScript 或 JavaScript 设备程序、网关和边缘服务，也便于接入已有 Node.js 服务或业务 API。生成包基于 @device-agent/device-sdk 和 BaseDevice，主要在 src/device.ts 中补充真实设备逻辑。

先看文件	用途
src/device.ts	编写命令处理、状态更新和事件逻辑
device-spec.json	核对命令、属性和事件定义
.env.example	配置 MQTT 地址和设备身份
package.json / README.md	查看依赖、脚本和运行方式

安装和启动

1. 下载并解压代码包，进入代码包根目录。
2. 将 .env.example 复制为 .env，填写连接信息。
3. 使用 npm 安装代码包依赖。
4. 在 src/device.ts 中接入真实设备或业务服务。
5. 启动程序，回到设备智能体工作区验证。

最小安装和启动命令如下：

cp .env.example .env
npm install
npm run start

src/index.ts 负责读取 .env 和创建设备实例，src/device.ts 负责命令、状态与事件。packages/device-sdk 和 packages/shared 是代码包内的本地依赖。命令名、参数名、属性字段和事件名必须与 device-spec.json 保持一致。

实现命令、状态和事件

src/device.ts 中的设备类继承 BaseDevice。命令会进入 handleCommand()；执行真实动作后，更新状态并发布快照：

protected override async handleCommand(command: DeviceCommandMessage) {
  if (command.cmd === "set_temperature") {
    const target = Number(command.params?.target_temperature);

    await thermostatClient.setTargetTemperature(target);
    this.patchState({ target_temperature: target });
    await this.publishStateSnapshot();

    return { code: 0, msg: "ok", data: { target_temperature: target } };
  }

  return { code: 404, msg: `Unknown command: ${command.cmd}` };
}

BaseDevice 负责 MQTT 连接、命令订阅和响应发布。三类数据的用途不同：

类型	作用	Node.js API
当前状态	更新设备的最新属性值	patchState()
状态快照	上报在线状态和最新属性	publishStateSnapshot()
事件	上报告警、按键等独立事件	sendEvent()

事件名和数据字段应已在 device-spec.json 中定义：

await this.sendEvent("temperature_alarm", {
  current_temperature: 32.5,
  level: "warning",
});

接入语音和视觉

语音

从 @device-agent/device-sdk 导入 VoiceClient，显式传入 wsUrl，再把麦克风采集、扬声器播放和事件监听接到客户端。VoiceClient 需要全局 WebSocket，可使用 Node.js 21 及以上版本或 Bun。代码包中的示例可以读取 VOICE_WS_URL：

import { VoiceClient } from "@device-agent/device-sdk";

const voice = new VoiceClient({
  wsUrl: process.env.VOICE_WS_URL ?? "ws://127.0.0.1:3001/ws/voice",
  deviceId: process.env.DEVICE_ID ?? "device-001",
  productId: process.env.PRODUCT_ID ?? "agent-001",
});

voice.on("agentReply", (text) => console.log(text));

await voice.connect();
voice.startListening("manual");
voice.sendAudio(pcmChunk);
voice.stopListening();

完整示例位于 packages/device-sdk/examples/voice-chat.ts。

视觉

VOICE_CHAT_HOST 用于配置生成设备的视觉上传和对话服务。src/device.ts 包含生成包预置的单次拍照识别流程，具体触发命令见生成包 README。真实设备可以覆写 captureLocalVisionImage()，从摄像头、截图或图像文件返回一张图片：

protected override async captureLocalVisionImage() {
  return {
    mimeType: "image/jpeg",
    imageBase64: await readCameraFrameAsBase64(),
    source: "sdk-camera",
  };
}

生成代码会把识别结果作为命令响应返回。

完整的语音和视觉配置见 语音交互 和 摄像头与视觉识别。启动后，按 SDK 接入 中的检查项验证设备上线、状态、命令和事件。