SDK 接入
SDK 接入用于把真实硬件接入设备智能体。设备端连接 MQTT 后，可以按设备规格上报状态和事件、响应命令，并作为真实设备出现在设备列表中。文档和代码包中出现的 namespace 表示当前运行空间，默认值为 default。
选择接入方式
在设备智能体工作区中点击 接入设备，控制台会提供三种入口：
| 方式 | 适合场景 |
|---|---|
| SDK 工程 | 需要一个可运行的设备端工程，再补充硬件逻辑 |
| 智能体适配和增强 SDK | 基于 SDK 工程生成设备端业务逻辑，下载后继续微调或直接运行 |
| 已有设备 | 已经有固件、网关或后端服务，只需要按 MQTT 主题和消息体约定适配 |
前两种入口都会生成设备端代码包；已有设备入口不会生成代码，而是给出接入参数和消息示例。
SDK 工程
SDK 工程是一套可运行的设备端代码。它已经接好 MQTT、设备身份、命令响应、状态上报和事件上报，真实硬件逻辑在设备业务入口中补充。
不同语言的文件名会略有差异，但整体结构相同：
SDK 工程
├── .env.example 连接配置：MQTT、namespace、productId、deviceId
├── device-spec.json 当前设备规格：命令、遥测、事件
├── README.md 安装、配置、运行和开发说明
├── src/
│ ├── main.* 启动入口：加载配置并连接 MQTT
│ └── device.* 业务逻辑入口：处理命令、更新状态、上报事件
├── 语音代码 通过 /ws/voice 接入设备端语音对话
├── 视觉代码 上传图像并发起拍照识别
└── SDK 运行层 订阅命令、发送响应、上报在线状态、遥测和事件device-spec.json 是设备端实现依据。命令名、参数名、遥测字段和事件字段都应与它保持一致。
语音和视觉代码
SDK 工程除了 MQTT 接入，也包含可选的语音和视觉代码。它们用于把真实设备上的麦克风、扬声器、摄像头或图像来源接入设备智能体。
- 语音：设备端通过
/ws/voice建立 WebSocket 连接，发送 16 kHz 单声道 Int16LE PCM 音频，并接收识别文本、智能体回复和 TTS 音频。 - 视觉：用于拍照识别类命令。设备端获取一张图片，上传到
/api/vision/frames，再把返回的visionRefs带到/api/chat获取识别结果。
.env.example 中的 VOICE_CHAT_HOST 是语音和视觉接口的统一主机入口。语音、视觉不会替代 MQTT 设备控制；MQTT 仍然负责命令、状态、遥测和事件。
| 语言 | 语音代码 | 视觉代码 |
|---|---|---|
| C | voice_client.h、voice_client.c、examples/voice_chat.c | vision_client.h、vision_client.c |
| Python | src/voice_client.py | src/main.py 中的拍照识别命令处理 |
| Node.js | VoiceClient | VisionClient 和 captureLocalVisionImage() |
下载 SDK 工程
创建 SDK 工程时需要确认：
- 开发语言：当前控制台支持 C、Node.js 和 Python。
- 设备名称：用于在控制台中识别设备，可以后续调整。
- 设备 ID：真实设备的唯一标识，同一个设备智能体下不要重复。
下载后先按 README 启动，确认设备能上线；再把默认逻辑替换为真实传感器、执行器或业务服务调用。代码包会保留 device-spec.json、README.md 和 .env.example。Node.js 工程还包含 AGENTS.md、CLAUDE.md 和设备实现说明，可用于 Claude Code、Cursor 或 Codex 继续开发。
常见运行步骤是：
- 解压代码包。
- 根据
.env.example配置连接信息。 - 安装依赖或编译工程。
- 启动设备端程序。
设备启动并完成首次状态上报后，会自动出现在当前设备智能体的设备列表中。
不同语言的 SDK 使用方式见：
使用智能体适配和增强 SDK
智能体适配和增强 SDK 适合设备端业务逻辑还没有写好的场景。它会先生成 SDK 工程，再基于补充描述生成状态上报、命令处理、事件触发和设备端流程。
你可以补充这些信息：
- 设备端逻辑，例如如何读取温湿度、如何控制继电器、如何触发告警事件。
- 业务要求，例如上报频率、阈值事件、命令执行后的状态更新方式。
- 可选的硬件信息，例如芯片、系统、驱动文档链接、接口文档或硬件协议文件。
提交后，设备智能体会在对话中返回可下载的代码包。生成结果不符合预期时，可以继续要求调整，例如补充驱动调用、修改事件触发条件，或简化状态上报逻辑。
接入已有设备
如果设备固件、网关或后端服务已经存在，可以选择 已有设备。这个入口不会生成 SDK 代码，而是给出 MQTT 服务地址、设备身份、主题和消息体示例，方便已有系统直接适配。
已有设备接入的核心是按 MQTT 约定订阅命令、响应命令、上报状态和事件。完整说明见 MQTT 接入。
运行并验证
设备端程序启动后，回到设备智能体工作区确认：
- 设备列表中出现新的真实设备。
- 设备状态为在线。
- 当前数据能看到设备上报的遥测字段。
- 通过对话下发控制命令后，设备端能收到命令并返回结果。
- 如果设备会上报事件，可以在最近上报事件中看到事件记录。
如果设备没有出现，先检查设备端是否已连接 MQTT、productId 和 deviceId 是否正确、是否已经上报状态或遥测。更多配置项见 配置。