Web profile 插件 —— 宿主半 + 浏览器半。

> English: README.md | 中文: README.zh.md

DSH 硬件沙盒

给 DSH 的 3D 硬件沙盒：把装配摆出来、接上线，然后让你自己项目的代码跑在虚拟硬件上。

<!-- 收录徽章位：awesome-dsh-plugin / DSH 社区列表 / dsh.so / dsh-plugin.org / …（收录通过后逐个补上官方徽章；徽章图片本身不自制） -->

安装（从 GitHub 源码装；本包未发布到 npm）

dsh plugin --profile web add github:Noob-stupid/dsh-breadboard

装完刷新页面即可。沙盒注册进 main 槽（3D 视图）与 sidebar.panellist 槽（各面板）；
skill/SKILL.md 随插件一起注册，装了这个插件的 agent 已经知道该怎么用它。

喜欢的话：在插件管理里打开这个插件的详情页，内容最下方靠右有一行小字，可以到
GitHub 点个 Star。它就是透明的一行字
—— 没有底色、没有边框、没有阴影，也只在本插件自己的页面上出现。

这一行能生效靠三件事，三件都在本仓库里：

这是什么 / 解决什么问题

一个软硬件项目里，只有真机能试的那几段，是接线本身、传感器在寄存器层的语义、以及出错时的处理。
本插件把它们搬进一个真能跑起来的虚拟场景：

• 3D 装配 —— 从内置模型库放器件（ESP32、树莓派 4B、BME280、HC-SR501 PIR、LED 模块、
  MPL3115A2、面包板），按端口逐个连线，得到一份活的 SSOT（唯一真相）装配状态，带拓扑与电气校验。
• 项目级硬件在环 —— 一个真实 Python 进程跑你自己项目的代码。Python shim 拦截它的
  smbus/I2C 访问，由虚拟设备应答，所以被测项目读到的是寄存器级的值
  （例如它自己拿虚拟芯片的数据做真正的 BME280 补偿计算）。
• 联网设备模拟（并列的第二类虚拟硬件）—— 一台按真实节拍主动向你的外部 HTTP 后端
  上报的设备：注册 → 拉配置 → 周期上报。已在真实的智能选座系统上全链路验证
  （设备 → HTTP → 服务端状态机 → 数据库）。
• 故障注入 —— 拔线、返回 NACK、强制读数、让设备掉线，然后看项目的异常处理到底抓没抓住。
• 项目级便利 —— 扫描一个真实项目文件夹，得出它需要哪些硬件；再一键换掉整套硬件。

依赖 DSH 的 web profile 与 webServer、tools、subprocess 三个服务。宿主半把它们声明为
硬 inject 依赖（刻意如此）：缺任何一个，插件根本不激活，而不是"激活了但工具没注册 /
界面空白 / 仿真起不来"。

没有真实项目也想看效果

examples/zhizuo-virtual-esp32/ 是虚拟 ESP32 座位传感器的独立脚本版。
hw_list_projects 会列出内置演示项目（zhizuo-seat-node）以及它当前是否软硬件连通；
hw_import_project 一次把它的器件、连线与联网绑定摆好。

界面导览

界面目前只有中文，下表用的就是屏幕上那行字。

其中两条要点名：

• 「扫描需求」只是界面按钮。 它没有对应的 agent 工具 —— agent 侧没有这一步。agent 能做的是
  它后面的事：摆器件、连线、建项目图纸、跑仿真。
• 删除项目只删掉项目定义（那一份 JSON）。它不动场景，所以删项目永远不会把你眼前的硬件清掉。

快速上手：三步

1. 导入项目本体 —— 点 ＋ 导入项目本体（选文件夹），选一个完整的项目文件夹
   （前后端 + 硬件代码）。它不带建模；宿主读它来判断需要哪些硬件。
2. 扫描需要哪些硬件 —— ③ 面板里的 扫描需求 按钮（界面专属，见上）。报告会列出每个候选
   型号键，并给出证据（在哪几个文件里看到的），让你自己判断对不对；扫描时如果做了采样，
   它会说出来，而不会让你以为整个项目都扫过了。
3. 导入建模组 —— 点 ＋ 导入建模组（选文件夹），布局是 <型号键>/model.glb。
   没补的型号继续渲染为占位盒。

或者干脆跳过 1–3：把系统用话讲给 agent，让它用 hw_save_project 写成图纸，
再用 hw_import_project 一次把器件、连线、联网绑定全部摆好。

Agent 工具：16 个 hw_*

以下是实际注册的清单（未增未删）。「什么时候用」这一列才是表格的意义 —— 这些工具并不通用互换。

项目

装配

仿真

联网设备

型号定义（数据驱动）

真机在环（只读观察）

原因码与对策

装配操作的失败都带原因码（契约的 WarningCode，共 12 项，见 src/contracts/assembly.ts）。

照着码改对应的那件事。不要盲试。

三条值得留下的说明：

• port_occupied 与 already_connected 是刻意分开的两个码。 合成一个，用户会去找一根不存在的线。
• 多个不同端口接到同一个端口是合法的（那是 I2C 总线），不报 already_connected。
• ok: true 不等于效果发生了。 每次写入之后都应该再读一次装配确认。

型号定义：让插件认识一块新硬件

先说清两件不同的事（这是最容易混的一处）：

⇒ 外观来自库；引脚数据靠型号定义。 没有定义，插件不认识这块板子（摆上去也只是占位方块）。

一条定义里写什么

{
"key": "stm32f103c8t6",          // 型号键（小写字母/数字/连字符）；不能与内置型号同名
"label": "STM32F103C8T6（Blue Pill）",
"size": { "x": 0.0533, "y": 0.011, "z": 0.0229 },   // 包围盒，单位【米】
"powerDrawW": 0, "powerSupplyW": 0,
"ports": [
// portId = 身份（连线用它，必须唯一）；name = 丝印（人看的那行字，可重复）
{ "portId": "P1", "name": "VBAT",   "protocol": "power", "voltage": 3.3, "direction": "in" },
{ "portId": "P2", "name": "PC13",   "protocol": "gpio",  "voltage": 3.3, "direction": "io" }
],
// 排布：贴哪条边、间距、几排（双排排针用 rows/rowPitch）
"portLayout": { "edge": "+z", "pitch": 0.00254, "count": 40, "inset": 0.001, "rows": 2, "rowPitch": 0.02292 }
}

三条容易踩的：
1. portId 是身份、name 是丝印 —— 一块板有多个 GND，用功能名当身份会撞号，而撞号的后果是静默的（两根线分不清）。
2. voltage: 0 是合法的 —— 那是 GND 的电压，不是"没填"。
3. 端口要么每个给 position、要么给 portLayout —— 两者都缺会被拒绝（不是给个默认值假装能用）。

三条获取路径（按可靠性排序）

★★ 一条纪律（写进工具描述里的）

引脚表必须有权威来源（厂商数据手册 / PlatformIO variant / CubeMX 数据库 / 项目自己的工程文件）。
手打错的引脚表比没有更坏 —— 它会产出"看起来对但接错脚"的校验，而没人能发现。
⇒ 所以插件宁可拒绝、宁可让你补来源，也不给一个"看起来合理"的默认值。

内置型号不可被覆盖：撞名会被拒绝并说明原因 —— 否则别人发一个 rpi-4b 定义就能悄悄改掉所有用户的引脚表。

真机观察：把真机状态读进场景

让场景里的器件反映真实硬件的状态：真机 → 服务端 → 插件（只读）。

hw_watch_device({ action:'start', componentId:'c1', deviceId:'AA:BB:CC:11:22:33',
endpoint:'http://127.0.0.1:5800', intervalMs:5000, cookie:'…' })
hw_watch_device({ action:'status' })     // 看现在是什么状态
hw_watch_device({ action:'stop', componentId:'c1' })

界面上对应 ④ 真机观察 面板（填器件 / 真机标识 / 地址 / 间隔 → 开始观察（只读））。

★★ 五种状态分开（这是这一层最重要的设计）

⚠️ 把 error 说成"设备离线"是本项目最怕的那种错：结论看起来合理、实际完全错误，还会让人去拔插硬件，而真正的问题在我们这边（地址写错 / 没登录）。

两条硬约束

1. 轮询走墙钟（真机按真实时间走，不能加速），间隔下限 2 秒 —— 这是保护对方服务器的硬约束，不是建议值。
2. 只有宿主在轮询：界面只读宿主的缓存（不会把对方服务器打两遍，也不会出现两份不一致的状态）。

⚠️ 一个真实的陷阱（源码里挖出来的）

不要用 GET /api/sensor/device_config 做观察 —— 智座那条路由会把 last_seen 刷成当前时间（它本来是给设备拉配置用的）。
用它做观察 = 我们一查，离线设备就变在线 ⇒ 得出"设备在线"而设备根本没插电。

⇒ 观察只用 /api/admin/sensor/devices（只读），这条有断言钉死。

建模组格式

交给 ＋ 导入建模组 的文件夹（也是导出与导入往返的同一套布局）是：

<型号键>/
model.glb      模型本体
meta.json      可选元信息

• 渲染只加载 GLB / GLTF。 导入侧的格式判定认内容不认扩展名，接受
  glb / gltf / stl / obj / ply / 3mf / dae / fbx / wrl；但 STEP / IGES 会被明确拒绝，而不是静默存下 ——
  three.js 没有对应 loader，存下来的 STEP 永远渲染不出来。
• 内部每个模型是一个目录 <型号键>/{model.bin, meta.json}，model.bin 装几何字节
  （meta.json 记 format / nodes / bytes / generator）。用中性文件名存字节是刻意的：
  布局里没有扩展名歧义，meta 与它的字节绑在一起。导出的建模组用上面的
  <型号键>/model.glb 形式，所以导出与导入是同一套布局。
• 随包分发（启动时补进用户模型目录，只补缺的键 —— 你自己导入过的模型绝不会被覆盖）：

为什么这么分：四个自产模型是我们的，可以随包发，所以插件开箱即用
（演示装配就是 esp32-seat-sensor + 2 × hc-sr501，全在包里）。第三方模型是别人的资产、有它自己的条款，
所以插件不分发它们 —— 界面给搜索入口，文件你自己导。端口语义（I2C 地址、协议、电压、方向）
一律自产，因为没有哪个模型库卖这个 —— 详见 docs/05。

墙钟陷阱：联网设备为什么不用虚拟时间

虚拟时钟是加速的：advance(60) 会把 60 个虚拟秒在几十毫秒内跑完。被动等被读的总线设备挂上去没问题
（确定性、纯同步）；联网设备不行 —— 它是主动周期上报的，一次快进会朝别人的后端打出几十次
真实 HTTP 请求，把对方打爆。

所以联网设备一律按墙钟（真实节拍）走，与虚拟时钟解耦；它的快照里带 wallClockDriven: true，
加速模式对它们没有意义。两个推论：

• 加速模式对联网设备不适用。 它们始终按真实间隔上报。
• 设备被添加后停在 idle，必须显式 start —— 默认完全不产生外部副作用。
  这是本插件的一条结构性纪律：默认行为不许伸到机器外面去。

构建与开发

# 1. 安装（同时链接构建所需的框架 peer）
npm install

# 2. 构建：src/ -> lib/（需要 bash 与一份 DSH 源码 checkout）
$env:DSH_CHECKOUT='D:\dsh\deepseek-harness'; bash scripts/build.sh

# 3. 测试与类型检查（2026-10-11 实测）
npm test                  # node --test，308 项，0 失败
npm run typecheck         # tsc -p tsconfig.json --noEmit          -> exit 0
npm run typecheck:client  # tsc -p tsconfig.client.json --noEmit   -> exit 0

scripts/build.sh 除了编译还做三件事：链接构建依赖（scripts/link-deps.mjs，同时挂在 postinstall 上，
因为 npm install 会清掉它不认识的 junction）、把 project-shim/ 复制进 lib/project-shim/、
写出 lib/build-stamp.json。那次复制是功能性步骤，不是打包细节 ——
SimEngine 把 Python 进程的 PYTHONPATH 指向 shim（smbus + RPi.GPIO + sitecustomize），
而 package.json 的 files 只发 lib，不做这一步就等于发布一个跑不起来的包。

scripts/prepare.mjs 让 git 装法也能用：lib/ 被 gitignore，所以 git 装出来会没有入口。
它只在 lib/index.js 缺失时才构建，而且构建失败只警告（exit 0） ——
构建失败大概率是这台机器缺 bash 或缺 devDependencies，让整个 install 失败只会把锅甩给 npm。

发布产物：npm pack → 一个 .tgz，内含 lib、cordis.patch.yml、skill、docs、models、scripts。

活体自检：线上跑的是你以为的那次构建吗？

curl http://127.0.0.1:<端口>/@noob-stupid/dsh-breadboard/api/capabilities

所有界面与 API 都挂在路由前缀 /@noob-stupid/dsh-breadboard/ 下。GET …/api/capabilities
返回 build（当前活着的那份代码的构建时间戳）与 simTools（实际注册成功的工具名）。
觉得哪里不对就先看它：工具注册失败是完全静默的 —— 模型只会说"我没这个能力"，界面上看不出任何异常；
而热重载可能报成功、实际还是旧模块在服务。

已知限制

诚实清单；下面没有一条被"看着像默认值"的东西掩盖。

• 本包未发布到 npm。 从 GitHub 装。有一个预构建的 tgz 作为发布产物，但没有 npm install 这一行可给。
• 界面只有中文。 面板里今天没有语言切换，也没有英文界面文案可以承诺。
• 项目 Python 代码读 GPIO 尚未实现。 hw_set_occlusion 会把遮挡沿实际接线传导进联网设备的读数，
  但反方向 —— 项目代码经 shim 调 RPi.GPIO.input() —— 会抛 NotImplementedError，
  桥接层的 gpio_read / gpio_write 在契约里已声明、行为未实现（"已定义协议但行为模型尚未实现"）。
  所以"固件轮询引脚再上报"这条路今天还走不通；"固件直接 HTTP 上报"这条路可以。
• 联网设备还没画进 3D 场景。 它们已在 SSOT 里（transport: 'network'）、工具也完全能驱动，
  但前端还没渲染它们。
• 只声称验证过的路径。 联网设备那条链在真实后端上验证过；I2C 形态的真实项目还没有适配过 ——
  I2C 那一半目前由本仓库自带的测试项目验证。
• 模型尺寸 vs 几何保真是待决的二选一（见 docs/06 §6）：把导入模型缩放到声明的真板 size
  会让它轻微变形。今天的做法是保留真机尺寸、端口按变形后的间距对齐。
• hw_set_occlusion 只够得着联网设备。 若被遮挡的器件接到的对端不是带 pinMap 的联网设备，
  什么都传导不过去 —— 这时工具会在 reason 里说出来，而不是静默成功。
• 部分导入模型的端口数还在收敛（例如树莓派排针有几个脚落在 PCB 上而非引脚 mesh 上）。
  端口可用，但少数锚点有零点几毫米的偏差。

文档

这些文档是中文的工作文档（翻译它们会多出一份需要同步的副本）。本文件与 README.md 是成对维护的。

许可证

BSD-3-Clause。

dsh-breadboard