打开「一语控物」,还没连接任何硬件,屏幕上已经有一台云台: 会转身、会扫描、会在 Canvas 上画出点云、会报温度——它不存在,是纯本地 JS 模拟。 但这个项目的 README 里专门写了一句话:虚拟设备不是「跳过协议」的假实现。 这篇讲一台「诚实」的虚拟设备要满足什么条件,以及它反过来教会了真实现什么。

01什么才算「不是假实现」

很多 Demo 里的模拟设备长这样:界面按钮直接改一个 JS 对象的属性,动画照播。 快,但它验证不了任何东西——协议、校验、状态机全被绕过去了。

这个项目的虚拟设备走的是完整链路:

虚拟模式的指令往返
指令 → encode(序列化成 DAP 帧)→ decode(反序列化)
         → 虚拟设备 handle(校验 + 执行 + 生成状态)
         → encode(回执序列化)→ decode → UI 更新

传输层是本地函数调用,但 codec 和参数校验一个字节都不少。 于是虚拟模式本身就成了协议实现的真实测试环境: 帧格式写错、参数范围漏校验、状态机转移漏分支,在虚拟设备上全部会暴露。 「断网可演示」不只是演示噱头——它意味着整条协议链路在没有任何硬件、 任何网络的情况下被反复执行过。

这一切的架构基础是一个统一契约:虚拟设备和真机实现同一个 IDapDevice 接口(注册 handler、统一 handle 入口、 能力上报、状态快照);ESP32 侧的 SDK 提供 API 语义等价的同名注册式接口。 虚拟与真实之间只隔一个传输层。

02合成点云:确定性随机种子

扫描功能要有东西可画,点云是合成的:一个 3200×4000mm 的虚拟房间 + 射线求交生成距离数据。技术上最关键的决策是确定性随机种子。

  • 每次扫描的房间布局、障碍物位置可复现——动画不会每帧抖动;
  • 单测可以断言具体数值(第 45 帧的 distance 是多少毫米);
  • 调试渲染问题时,输入是固定的,排除了「数据变了还是画错了」的怀疑。

非确定性的随机在演示里是「生动」,在工程里是「不可断言」。 种子固定之后,两者兼得:布局可以精心设计出层次感, 测试可以写成 expect(frame.points[3][0]).toBe(1180)。

扫描的分帧推送
{"v":1, "id":"cmd_20260912_000124", "type":"pointcloud",
     "seq":3, "total":90, "unit":"mm",
     "points":[[1200,0],[1180,45],[0,0]]}
    // distance=0 表示该角度无回波(超量程)——超量程是数据,不是异常

03能力表是设计出来的考卷

虚拟设备有一张容易被忽略的隐藏用途:给能力边界做考卷。 标准能力集里,virtual-gimbal 被刻意设计成没有灯—— 尽管实现一个灯只要十行代码。

为什么?因为验收项 V-3「能力边界不幻觉」需要一个天然的负样本: 对这台云台说「开灯」,系统必须回复「该设备不支持灯。它支持:转动、回中、 扫描、读传感器」。如果所有虚拟设备能力齐全,这条路径永远走不到正样本, 边界话术就成了没有测试覆盖的死代码。

虚拟设备能力存在的意义
virtual-gimbal无 light.setV-3 能力边界的负样本
virtual-light只有灯单一能力设备的最小样本
virtual-car车+灯+传感器复合,无云台动作触发词仲裁(「停车」归谁)的考卷

同样思路还落在复合设备上:virtual-car 同时有 drive 和 light 却没有云台动作——对它说「归位」应该被拒。共享触发词的仲裁逻辑 (设备能力表说了算)全靠这几台「故意残缺」的设备才能被测到。

04诚实的边界:报「未实现」,不报「假成功」

虚拟设备之外,项目对「还没做的东西」有一个统一的态度: 诚实抛出,绝不返回假数据。几个例子:

  • WSS 云中转还没部署中转服务 → 未注入 socket 工厂时诚实报错,不静默失败;
  • 设备自动发现的 mDNS 在小程序里不可用 → 诚实标注「UDP 广播方案,待真机验证」, 不假装发现了设备;
  • 云端 AI 通道未启用 → isAvailable() 永远返回 false, 路由器根本不出网。

反面教材是那种「假装实现了」的代码:返回空数组当成功、返回写死的 -50 当信号强度 还不标注是模拟值。短期看演示更漂亮,长期看它污染的是所有下游判断—— 你没法区分「真的没设备」和「假的空列表」。 诚实的未实现是有信息量的:它把问题暴露在正确的位置, 而不是让它变成三周后一次莫名其妙的「偶现 bug」。

05虚拟设备反过来约束了真实现

最后是这次设计里最有意思的收获:虚拟设备成了真实现的质量标准。 因为虚拟设备走完整协议链路,任何「真机上才处理」的特殊逻辑都会在虚拟模式先暴露。 几个实际的例子:

  1. 回执里设备必须返回执行后的绝对角——虚拟设备先这么做了, 客户端的相对计算基准才有了稳定约定;
  2. ack.state 的字段缺失时客户端要用默认值补齐—— 虚拟设备模拟「老固件少报字段」的做法倒逼出了这个容错;
  3. 扫描结束的判定依据 seq === total 而不是固定延时—— 分帧推送的协议语义在虚拟设备上先跑通了,真机 SDK 照抄即可。

顺序值得记一下:不是「真机做完,虚拟机配合演示」, 而是「虚拟先行,把协议语义跑通,真机按同一契约实现」。 一台不存在的设备,反而是整条链路里最早开始干活的那台。

关于本文
整理自「一语控物」的虚拟设备设计(core/virtual/、 docs/01 §2.2 原则 P1、docs/02 §6.1 标准能力集)。
2026.10.23 整理
如果只留一句话,是这句:模拟的价值不在于像,而在于它逼真实现 说清了自己的契约。种子固定、能力残缺、诚实报未实现—— 三件事看着都是「故意不把模拟做好」,其实全是把工程做扎实。