Node.js SDK

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

先看文件	用途
`src/device.ts`	编写命令处理、状态更新和事件逻辑
`package.json` / `README.md`	查看依赖、脚本和运行方式

.env、runtime-model.json 和 device-spec.json 的用途与修改规则见 SDK 工程文件。

当前接入方式的工程

本页示例用于由 Device Agent 直接管理的设备。不同平台的扩展回调可能不同，使用包内 README 指定的接口。平台支持可写状态时，除命令处理外，还需实现状态更新回调，并在硬件应用成功后上报实际值。

安装和启动

下载并解压代码包，进入代码包根目录。
检查生成的 .env，确认连接地址和设备身份；文件缺失时才从 .env.example 创建并补齐配置。
使用 npm 安装代码包依赖。
在 src/device.ts 中接入真实设备或业务服务。
启动程序，回到设备智能体工作区验证。

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

bash

test -f .env || cp .env.example .env
npm install
npm run start

Bun 工程使用 bun install 和 bun run start。

src/index.ts 负责读取 .env 和创建设备实例，src/device.ts 负责命令、状态与事件。packages/device-sdk、packages/iot-platform 和 packages/shared 是代码包内的本地依赖。

实现命令、状态和事件

生成的 GeneratedDevice 继承 RuntimeDevice。模型校验通过后，命令进入 onRuntimeCommand() 或通过 onCommand() 注册的回调。保留这条执行路径，不要覆写底层 handleCommand() 绕过校验。

在 src/device.ts 的 GeneratedDevice 类中扩展现有 onRuntimeCommand()，保留生成的视觉处理分支。示例要求模型声明带数值参数 value 的 set_target_temperature(value)，以及属性 target_temperature，与定义设备智能体一致。在同一文件中实现 setTargetTemperature()，执行硬件写入并返回实际状态；硬件失败时抛出错误：

protected override async onRuntimeCommand(
  context: RuntimeCommandContext<GeneratedDeviceState>,
): Promise<DeviceResponseInit> {
  const { message, params } = context;
  if (this.shouldHandleVisionCommand(message.cmd)) {
    return this.handleVisionRecognitionCommand(message, params);
  }
  if (message.cmd !== "set_target_temperature") {
    return { code: 501, msg: "Command not implemented" };
  }
  const actualState = await setTargetTemperature(Number(params.value));
  await this.reportState(actualState);
  return { code: 0, msg: "ok" };
}

保留生成的视觉辅助方法，并为其他需要的动作补充处理逻辑。通过 onCommand() 注册的回调会优先于 onRuntimeCommand() 执行，必须覆盖所有需要的动作。未实现的命令应返回失败，避免把默认确认当成真实硬件成功。

用途	接口
校验并上报当前状态	`await device.reportState(patch)`
校验并上报已定义事件	`await device.emitRuntimeEvent(eventName, payload)`
处理已声明命令	`device.onCommand(handler)` 或 `onRuntimeCommand()`
应用模型支持的期望状态	`device.onUpdateDeviceState(handler)`

命令参数、状态和事件字段必须匹配当前模型。期望状态回调负责执行硬件写入；状态快照表示设备报告的结果，不应在硬件失败时报告成功。

接入语音和视觉

语音

从 @device-agent/device-sdk 导入 VoiceClient，显式传入 wsUrl，再把麦克风采集、扬声器播放和事件监听接到客户端。VoiceClient 需要全局 WebSocket，可使用 Node.js 22 及以上版本或 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 接入

IM 接入

配置

Node.js SDK

当前接入方式的工程

安装和启动

实现命令、状态和事件

接入语音和视觉

语音

视觉

Node.js SDK ​

当前接入方式的工程 ​

安装和启动 ​

实现命令、状态和事件 ​

接入语音和视觉 ​

语音 ​

视觉 ​

Node.js SDK

当前接入方式的工程

安装和启动

实现命令、状态和事件

接入语音和视觉

语音

视觉