SDK 接入

SDK 将真实硬件或设备端服务连接到已有设备记录，以该记录的设备 ID 连接 MQTT、上线，并按设备规格上报状态和事件、响应命令。新开发或改造设备端程序时使用 SDK；已有 IoT 平台设备可直接完成IoT 平台集成，无需为使用 Agent 重新运行设备客户端。

选择接入方式

在设备智能体工作区中创建或选择一条设备记录，再点击该记录的 下载接入包 操作。控制台会为所选记录提供三种设备端接入方式：

方式	适合场景
SDK 工程	需要一个可运行的设备端工程，再补充硬件逻辑
Agent 增强	基于 SDK 工程生成设备端业务逻辑，下载后继续微调或直接运行
已有设备	已经有固件、网关或后端服务，只需要按 MQTT 主题和消息体约定适配

生成包对应所选设备和当前模型。不同 IoT 平台可能使用不同设备凭证、主题和消息体；使用生成结果，不要把另一种接入方式的主题或凭证直接套用。

下载 SDK 工程

1. 选择目标设备，确认名称和设备标识。
2. 选择页面提供的 C、Python、Node.js 或 Bun 等语言。
3. 下载并解压，先阅读包内 README.md。
4. 检查生成的 .env，确认服务地址在设备运行环境中可访问。
5. 安装依赖或编译后启动，再回到工作区验证。

接入包可能包含设备专属凭证。保留已生成的 .env，只有文件缺失时才从 .env.example 创建并补齐配置。设备端只使用自己的接入凭证；平台管理凭证留在服务端。修改连接地址时，保持设备身份与所选记录一致。

认识工程文件

文件	用途
.env	当前设备生成的运行配置，可能包含设备凭证
.env.example	不含完整敏感凭证的配置参考
runtime-model.json	当前原生模型解析出的接入能力、状态、动作和事件
device-spec.json	生成代码用于校验和字段映射的只读模型投影
README.md	当前语言与接入方式的安装、启动和开发说明

设备端实现以 runtime-model.json 为语义依据。它包含选定的 Provider、能力、上报与期望状态、动作、事件、Agent 工具和 SDK 支持信息。生成代码通过 device-spec.json 确定性兼容投影读取这些信息；不要修改这两个文件。需要修改字段或动作时，先修改原生模型，再重新生成工程，并把已完成的硬件逻辑合并到新工程中。

动作名、参数名、状态字段、事件名和 JSON 类型必须与模型一致。数值枚举使用数值，字符串使用字符串，布尔值使用 true 或 false；显示名称不能替代实际协议值。结构和数组保留原生模型的子字段与元素类型。SDK 支持的约束由当前适配决定，编写校验或硬件调用前先检查生成包 README。

语言	主要修改位置	运行环境
C	src/main.c	CMake、网关或嵌入式 Linux
Python	src/main.py	uv、网关或已有 Python 服务
Node.js	src/device.ts 和初始化回调	npm、TypeScript 或 JavaScript 服务
Bun	src/device.ts 和初始化回调	Bun、TypeScript 或 JavaScript 服务

补充真实设备逻辑

先让工程完成连接与初次上报，再逐项替换示例行为：

• 动作处理：执行对应驱动或业务接口，按真实结果返回成功或失败。
• 可写状态：接收期望状态后应用到硬件，再上报实际状态；是否支持由物模型和当前适配决定。
• 状态上报：读取真实传感器和执行器状态，使用工程提供的上报接口。
• 事件上报：在告警、按键或业务变化发生时上报已定义的事件数据。

保留生成代码中的模型校验和请求关联逻辑。默认模拟状态变化只能用于验证交互，不能作为硬件已完成动作的依据。每种接入方式的扩展位置以生成包 README 和代码为准。

单独检查 SDK 的示例行为。ThingsNeural 包在 device-spec.json 中包含已声明的模拟效果；由 Device Agent 直接管理的设备所用的 SDK 工程和 Fleets 工程使用各自生成的示例处理。用于真实控制前，将示例效果替换为硬件执行与实际状态上报。

使用智能体适配和增强 SDK

设备端业务逻辑还没有写好时，选择 Agent 增强。它会先生成 SDK 工程，再基于补充描述生成状态上报、命令处理、事件触发和设备端流程。

你可以补充这些信息：

• 设备端逻辑，例如如何读取温湿度、如何控制继电器、如何触发告警事件。
• 业务要求，例如上报频率、阈值事件、命令执行后的状态更新方式。
• 可选的硬件信息，例如芯片、系统、驱动文档链接、接口文档或硬件协议文件。

每 30 秒读取温度并上报。设置目标温度时调用现有控制接口，成功后上报实际目标值；读取失败时返回错误，不要写入模拟值。

提交后，设备智能体会在对话中返回可下载的代码包。生成结果不符合预期时，可以继续要求调整，例如补充驱动调用、修改事件触发条件，或简化状态上报逻辑。

接入已有设备

如果设备固件、网关或后端服务已经存在，可以选择 已有设备。这个入口不会生成 SDK 代码，而是给出 MQTT 服务地址、设备身份、主题和消息体示例，方便已有系统直接适配。

按 MQTT 约定订阅命令、返回命令响应，并上报状态和事件。完整说明见 MQTT 接入。

语音和视觉

部分工程提供语音或视觉示例。是否可用取决于接入方式、模型和工程内容。按生成包 README 连接麦克风、扬声器或摄像头，再参考语音交互与摄像头与视觉识别。

设备数据连接成功不代表语音和视觉服务已经配置完成，应分别验证对应服务地址、认证和输入输出。

运行并验证

设备端程序启动后，回到设备智能体工作区确认：

1. 同一条设备记录显示为在线。
2. 当前连接来自设备端客户端，而不是浏览器模拟会话。
3. 当前数据能看到设备上报的属性字段。
4. 通过对话下发控制命令后，设备端能收到命令并返回结果。
5. 如果设备会上报事件，可以在最近上报事件中看到事件记录。

如果记录没有上线，先检查设备端是否已连接 MQTT、productId 和 deviceId 是否正确、是否已经上报状态或遥测。配置项见 配置。浏览器模拟器不能与真实客户端同时使用同一身份，切换前先断开。