Device Core 主机 SDK

[English]

@esp-vision/device-core 是 ESP-VISION EV-MUX v4 固件对应的无 UI JavaScript 主机 SDK。IDE、Agent、CLI 和自定义主机应用共用它的字节协议、会话所有权、保活、Python、文件与图像能力。Apache-2.0 许可源码在固件仓库 host/device-core 维护，IDE/Agent 通过独立版本的 npm 包使用它。

安装与兼容性

npm install --save-exact @esp-vision/device-core@0.4.0
# Optional Node LAN discovery adapter:
npm install multicast-dns

本页示例面向 SDK 0.4.0；确认 registry 已发布后再安装该版本，源码、MR 和 dry run 不等于发布。Node 主机基线为 Node.js 22；浏览器需要打包器/import map，并由宿主提供 Web Serial 或二进制 WebSocket 字节连接。仅支持 EV-MUX v4，v3 设备必须升级固件。包版本、固件版本与 IDE 版本相互独立。

架构与使用入口

主机应用、Device Core、EV-MUX 与固件 — IDE / Agent / CLI / 自定义工具 → Device Core → EV-MUX → 固件

本图与项目 README、系统架构章节复用同一 SVG。主机应用负责设备选择及界面/流程策略，Device Core 负责共享 API、协议和会话状态，EV-MUX 定义与固件的运行时通信；字节适配器提供串口/socket I/O，不维护另一套协议栈。图中代表性 API 不替代完整参考；发现与 ROM 烧写各有独立生命周期，ROM loader 不通过 EV-MUX 写镜像。

根入口只导出 createDevice，返回设备对象，不提供公开的 Device 构造函数。所有应用方法、选项、返回值和事件见应用 API 完整参考；其余包导出及公开类方法完整列于高级导出 API 完整参考，供集成维护者查阅。这些子路径不包含 Agent 插件或 IDE UI。

import { createDevice } from '@esp-vision/device-core'

// transport is supplied by the host; its complete contract is in api.
const device = createDevice({ transport })
const off = device.on('python.output', text => console.log(text))
try {
  await device.connect({ role: 'usb' })
  console.log(await device.python.execute({ source: 'print(1 + 2)' }))
} finally {
  try { await device.disconnect() } finally { off() }
}

可直接运行的 Node TCP 与浏览器 Web Serial 适配示例见 Device Core npm 包对接。帧格式、路由、所有权见 index，统一真机测试入口见 validation。

许可证

npm 包及 ESP-VISION 自有贡献采用 Apache-2.0，与固件一致。包内包含 LICENSE 与 NOTICE；NOTICE 保留历史 MIT 版权与许可原文，第三方依赖仍遵守各自许可证。项目清单见许可证。

0.1.1 新增 @esp-vision/device-core/node 适配器，并随包提供单元测试和真机检查。本源码正在准备尚未发布的 0.4.0，新增浏览器 ROM、不可变发布快照和单 BIN 应用升级；发布后安装，也可先验证本地 tarball。0.1.0 缺少这些导出/检查资源。安装后可执行 npm --prefix node_modules/@esp-vision/device-core test 和 npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --help；缺少测试或空测试集将失败。应用 discover() 与 provider list() 的关系见 Device Core npm 包对接。