打开「一语控物」,还没连接任何硬件,屏幕上已经有一台云台: 会转身、会扫描、会在 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.set | V-3 能力边界的负样本 |
| virtual-light | 只有灯 | 单一能力设备的最小样本 |
| virtual-car | 车+灯+传感器复合,无云台动作 | 触发词仲裁(「停车」归谁)的考卷 |
同样思路还落在复合设备上:virtual-car 同时有 drive 和 light
却没有云台动作——对它说「归位」应该被拒。共享触发词的仲裁逻辑
(设备能力表说了算)全靠这几台「故意残缺」的设备才能被测到。
04诚实的边界:报「未实现」,不报「假成功」
虚拟设备之外,项目对「还没做的东西」有一个统一的态度: 诚实抛出,绝不返回假数据。几个例子:
- WSS 云中转还没部署中转服务 → 未注入 socket 工厂时诚实报错,不静默失败;
- 设备自动发现的 mDNS 在小程序里不可用 → 诚实标注「UDP 广播方案,待真机验证」, 不假装发现了设备;
- 云端 AI 通道未启用 →
isAvailable()永远返回 false, 路由器根本不出网。
反面教材是那种「假装实现了」的代码:返回空数组当成功、返回写死的 -50 当信号强度 还不标注是模拟值。短期看演示更漂亮,长期看它污染的是所有下游判断—— 你没法区分「真的没设备」和「假的空列表」。 诚实的未实现是有信息量的:它把问题暴露在正确的位置, 而不是让它变成三周后一次莫名其妙的「偶现 bug」。
05虚拟设备反过来约束了真实现
最后是这次设计里最有意思的收获:虚拟设备成了真实现的质量标准。 因为虚拟设备走完整协议链路,任何「真机上才处理」的特殊逻辑都会在虚拟模式先暴露。 几个实际的例子:
- 回执里设备必须返回执行后的绝对角——虚拟设备先这么做了, 客户端的相对计算基准才有了稳定约定;
ack.state的字段缺失时客户端要用默认值补齐—— 虚拟设备模拟「老固件少报字段」的做法倒逼出了这个容错;- 扫描结束的判定依据
seq === total而不是固定延时—— 分帧推送的协议语义在虚拟设备上先跑通了,真机 SDK 照抄即可。
顺序值得记一下:不是「真机做完,虚拟机配合演示」, 而是「虚拟先行,把协议语义跑通,真机按同一契约实现」。 一台不存在的设备,反而是整条链路里最早开始干活的那台。
- 关于本文
- 整理自「一语控物」的虚拟设备设计(core/virtual/、 docs/01 §2.2 原则 P1、docs/02 §6.1 标准能力集)。
- 2026.10.23 整理
- 如果只留一句话,是这句:模拟的价值不在于像,而在于它逼真实现 说清了自己的契约。种子固定、能力残缺、诚实报未实现—— 三件事看着都是「故意不把模拟做好」,其实全是把工程做扎实。
留言
正在载入留言…