v0.6.0

0.6.0

本轮把"加一块新硬件"从"改代码"变成"从权威来源推导"，并让真机状态进入 3D 场景。

新能力

• hw_scan_board_pins —— 从本机 PlatformIO 的权威文件推导引脚表草稿：
  boards/<board>.json → build.variant → variants/<variant>/pins_arduino.h
  （编译器实际用的那份映射）。list:true 列出本机能找到的板子（本机实测 242 块）。
  ★★ 它给的是草稿 + 缺口清单（缺：物理排布 / 电气语义 / 丝印），不是成品。
• esp32-s3-devkitc-1 型号定义（44 脚） —— 由 Espressif 官方文档机械提取（脚位/丝印/电气类型/GPIO）。
• 真机状态画进 3D 场景：被观察的器件按状态着色高亮 —— 🟢 在线 / 🟠 真机离线 / 🔴 我们查不到 / 🔵 服务端没有这台设备。
• 两个维护工具随包发：tools/crosscheck-model-pins.mjs（型号 ↔ 权威 variant 一致性检查）、tools/extract-devkit-header.mjs（官方文档 → 型号定义，换块 devkit 直接能用）。

修复 / 加固

• LICENSE（BSD-3-Clause） —— 之前只在 package.json 里声明，仓库没有许可证文件（GitHub 因此显示"无许可证"）。
• 定义只能存在一份：包内有了就删掉用户目录副本，否则每次启动都会报"与另一条外部定义重复"。

已知限制（如实）

• esp32-s3-devkitc-1 的 size 是按排针几何推算的，不是官方外形尺寸（官方只有 DXF/PDF：DXF 里外形不是 LINE/LWPOLYLINE 实体、产品页 403）。推算过程与"这不是官方值"写在定义的 _source 字段里。
• 型号定义的引脚表来源需要人/AI 去查；插件不替来源负责（错的引脚表比没有更坏）。
• 真机观察的真机验证仍需真板 + 服务端（本机目前无 COM 口、服务端未起）。
• 第三方模型仍不分发；随包只有自产 4 个模型。

测试：356 项全绿；host / client tsc --noEmit 均通过。

v0.5.0

0.5.0

两块新能力，都是让插件的硬件覆盖面可以扩展，而不是写死的。

型号定义：现在可以让 agent 来写

• 新工具 hw_save_model_definition —— agent 能直接写并装上一条型号定义（校验通过才落盘，落盘后立即生效）。
• 界面 ③ 面板新增 ✎ 让 agent 帮我写（填型号名即可），提示词走官方聊天通道（与你自己敲一句同一条路）。
• ★★ 纪律写死在工具描述与提示词里：引脚表必须有权威来源（厂商数据手册 / PlatformIO 的 variants/<board>/pins_arduino.h / 项目自己的 platformio.ini、.ioc、sdkconfig）；找不到就停下来问用户，不许凭记忆编。
  理由：手打错的引脚表比没有更坏 —— 它会产出"看起来对但接错脚"的校验，而没人能发现。
• 安装逻辑与界面路由共用同一段实现（不会出现"界面能装、agent 报错方式不同"）。

真机观察：界面上看得见

• 新面板 ④ 真机观察：显示正在观察的真机、五种状态分开措辞、读数、轮询/失败次数，并能从界面开始/停止。
• 轮询真机的只有宿主（墙钟、间隔下限 2 秒），面板只读宿主缓存 ⇒ 不会把对方服务器打两遍。

文档

• README.zh.md / README.md：新增两节详解 —— 外观与引脚数据是两件事（模型库给外观，引脚数据库里没有：连 SnapEDA 的符号库都"不含总线协议与电压"）；error 与 stale 为什么不能混。
• skill/SKILL.md：同样内容给 agent（随插件注册的技能）。
• 悬浮提示改成具体而不是更长。

已知限制（未变）

• 真机观察的真机验证需要真板 + 服务端（本机目前无 COM 口、服务端未起）。
• 型号定义的引脚表来源需要人/AI 去查；插件不会替来源负责。
• 项目列表默认是空的；第三方模型仍不分发（随包只有自产 4 个）。

v0.4.2

0.4.2

修社区列表维护者复核 npm 安装路径时发现的安装阻塞。

修复

• 去掉发布包里的 postinstall —— 维护者在隔离 profile 里实跑
  dsh plugin --profile web add @noob-stupid/dsh-breadboard 得到 exit 1：
  pnpm 拦下了这个包的 postinstall，往 profile 的 pnpm-workspace.yaml 写了一条待决的
  allowBuilds，用户手工放行之前这条命令不会成功；未决期间该 profile 的后续插件安装也会一起失败。
  他抽了索引里 13 个 npm 包，只有我们这个带 postinstall。

  这个脚本只做一件事：把宿主依赖 junction 进 node_modules —— 那是源码检出开发期的便利
  （scripts/build.sh 自己就会跑同一段逻辑），而发布包里 lib/ 已预构建，装上它没有任何收益。
  ⇒ 删除；源码检出流程改为在 README 里写明（npm install 后手动 npm run link）。

验证

• 解开 tgz 确认 scripts 里已无 postinstall。
• 其余不变：dependencies 只有 ws（没有未发布的包）。

v0.4.1

0.4.1

修社区列表维护者复核时指出的两条（都属"不会报错但会静默失效"那一类）。

修复

• dsh.client.inject 里删掉 @deepseek-ai/dsh-client-runtime —— 0.2.0-rc.2 的宿主模块表并不提供它（npm 上只到 0.1.1-rc.2）。缺了它不会报错，只会静默失效：界面少个东西、日志里什么都没有。
  ⚠️ peerDependencies 里的同名条目故意保留 —— 那是兼容门控读的（声明能与哪个版本协作），删了才是真改行为。

新增

• dsh.engines.dsh: ">=0.2.0-rc.2" —— 把"我们是对着哪个宿主版本构建的"写明，而不是靠默认。
• 可失败断言（已接进 npm test，跳过不了）：dsh.client.inject 里每个词都必须落在提供清单 scripts/host-client-modules.json 里。
  · 该清单是有出处的转录（维护者给的宿主模块表 + 本机实测），出处与"宿主升版时要更新"都写在文件里；
  · ⚠️ 我第一版是扫 node_modules 推导的，那是错的：@deepseek-ai/dsh-client-* 是宿主运行时提供的模块标识、不是 node_modules 里的包，磁盘上没有可枚举的表。那一版会把 dsh-client-ui-slots 也判成不存在 —— 而面板正是用它渲染的、它明明工作正常。一个因为假理由挡住发版的断言，比没有断言更坏。
  · 双向验过：清单正常时通过；清空清单时失败；清单读不到时也失败（不把"读不到"当成"没东西要查"）。

内容

• 与 0.4.0 功能集相同；随包自带 4 个自产模型（bme280 / esp32-seat-sensor / hc-sr501 / led-5v），第三方模型不分发。
• npm 包名不变：@noob-stupid/dsh-breadboard

v0.4.0

0.4.0

第一次发布到 npm：npm i @noob-stupid/dsh-breadboard

为什么要发 npm

社区列表的条目在没有 npm 字段时会按仓库 URL 做 git 安装，而本仓 lib/ 是刻意不入库的
（构建产物不进版本库），prepare 又依赖 bash scripts/build.sh ⇒ 后者需要机器上有 DSH 源码检出。
在没有该检出的机器上，安装会得到一个没有入口的插件（ERR_MODULE_NOT_FOUND）。
⇒ 改为发布到 npm：安装路径不再依赖构建环境。

内容

• 与 0.3.1 功能集相同（本次是发行方式的变化，不是新功能）。
• 随包附带自产 4 个模型（bme280 / esp32-seat-sensor / hc-sr501 / led-5v）；第三方模型仍不分发。
• 附带 skill/SKILL.md（随插件注册的技能说明）与 docs/。

已知限制

• 项目列表默认是空的（不预置别人的项目）。
• 建模组以单个 .json 搬运（几何 base64 内嵌），整套大小随模型数量增长。

v0.3.1 — 修复换装模型列表溢出与多余的建模组文件夹导入

0.3.1

两个用户报的界面问题，均为修复，无新功能。

修复

• 「换装模型」的型号列表不再溢出面板：型号行原先直接摊在面板里，型号一多就顶出面板下边界。现在它们有自己的滚动容器（maxHeight: 260px）；并带 overscrollBehavior: contain —— 没有它，滚到列表尽头后滚轮会漏给 3D 场景，用户以为在滚列表、实际把相机缩放了。
• 删掉多余的「导入建模组（选文件夹）」：它与「换装模型」里单型号的「导入」是同一件事，还额外要求用户手工摆好 <型号键>/model.glb 的目录结构。整套建模的搬运现在只走 .json 那一条路（一个文件装走、一个文件导回）。顺带修掉按钮标签里被字面显示的 ** 星号（按钮文本不渲染 markdown）。

已知限制

• 建模的整套搬运只有 .json 一种形态；导入仍以 base64 内嵌几何，整套体积随模型数量增长。

验证

• 测试 314 项全绿；host / client 两侧 tsc --noEmit 均通过。
• 界面观感与滚动行为未经我人工确认，需刷新页面后由用户实际查看。

v0.3.0

0.3.0

新增

• 导出建模组（一个 .json 装走整套）：把当前模型库里的全部几何打包成单个 .json（几何以 base64 内嵌），保存位置由系统对话框选；下次「导入建模组（.json）」原样导回。
• 项目建模台账：项目可带 requiredModels（省略时由 parts 推导），切换项目即可看到该项目 ✅ 有几何 / ❌ 待建（场景里是占位盒），并点名缺哪些。
• 导入建模组「只补缺」：勾上则已有几何的型号跳过不动 —— 给 B 项目补缺口不会误伤 A 已建好的同键模型（默认仍是覆盖换装）。
• 文档：skill/SKILL.md 补齐台账、.json 建模组、只补缺、以及 agent 侧「需求 → 缺口 → 建/导」闭环。

修复

• 打包产物 .tgz 未进 .gitignore 的漏洞（旧规则写的是改名前的包名，改名后失配）。

已知限制

• 建模组导出/导入用 base64 内嵌几何，整套大小会随模型数量增长（当前自产 4 个模型约 150KB 级）。
• 项目列表默认是空的（别人的项目不预置）；模型只随包发自产 4 个，第三方模型需自行导入。

测试：314 项全绿；host / client tsc --noEmit 均通过。

v0.2.1 — Star 入口移到官方插件详情页（内容最下方靠右）

这一版改了什么

把 Star 入口挪到它该在的地方 —— 官方插件管理里本插件自己的详情页，内容最下方靠右一行小字。

上一版（v0.2.0）把它做在面包板面板右下角，方向错了：那是沙盒自己的 3D 界面，不是"别人了解这个插件"的地方。现在它落在官方 @deepseek-ai/dsh-client-ui-plugin-manager 的插件详情页上（plugins.detail.section 槽，渲染成页面内容最下方），只在讲述本插件的那一页出现 —— 别的插件的页、官方条目页、本插件的子项页都不渲染。

观感（上一版被打回的地方）

没有底色、没有边框、没有阴影，不做吸附/悬浮：就是正文流里右对齐的一行小字。
上一版用了主题底色 + box-shadow 做滚动遮挡，视觉上成了"一个灰块/满宽色带"；这一版显式 transparent，因此也不需要吸附，不会糊住上面的正文。窄宽度只换行，不撑宽页面。

内容

内联的 GitHub mark（16×16，currentColor 跟随文字色）＋「喜欢这个插件？去 GitHub 点个 Star」，
整行是一个 <a target="_blank" rel="noreferrer noopener"> 指向本仓库。不引外链图片、字体或第三方脚本。

验证

• npm test 314 项全绿（308 → 314，新增 6 项针对这个钩子）
• tsc -p tsconfig.json 与 tsc -p tsconfig.client.json 均为 0
• 新增断言覆盖：条件渲染（满足才渲染 / 其它 subject 一律 null）、href 指向本仓、内联 <svg> 且全树无 img/script/link、样式对象无任何会画出底色/边框/阴影的取值、以及"客户端入口真的把它注册进了 plugins.detail.section"
• 可失败性验证：分别改坏（判据、底色、href、槽名）四处 ⇒ 测试各自 exit 1；还原后重新全绿

安装

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

装完刷新页面。已经装着的直接在插件管理里更新即可。

v0.2.0 — 改名 @noob-stupid/dsh-breadboard，面板加 Star 钩子

0.2.0 —— 改名为 @noob-stupid/dsh-breadboard ＋ 面板右下角 Star 钩子

一、改名（身份变更，仓库地址不变）

项目	旧	新
npm 包名	@dsh-breadboard/dsh-hardware-sandbox	@noob-stupid/dsh-breadboard
插件名 / PLUGIN_ID	同上	同步改名
cordis.patch.yml 的 entry name	同上	同步改名（entry id 未动）
路由前缀	/@dsh-breadboard/dsh-hardware-sandbox/**	/@noob-stupid/dsh-breadboard/**
Skill 名	dsh-hardware-sandbox	dsh-breadboard
面板 id / 侧栏 key	hardware-sandbox	breadboard

仓库地址不变：仍是 https://github.com/Noob-stupid/dsh-breadboard——
已投的收录条目按 url / id 索引，因此无需改动。

二、老用户怎么迁（0.1.x → 0.2.0）

1. profile 里的两处名字要换（~/.dsh/profiles/<你的 profile>/package.json）：
   • dependencies：把 "@dsh-breadboard/dsh-hardware-sandbox" 换成 "@noob-stupid/dsh-breadboard"（link: 或版本号都照原样保留）
   • dsh.profile.bundles（若你原来还写了 dsh.bundles，同样）里的旧名换成新名
     然后在该 profile 目录跑一次 install 重建依赖链接，刷新/重启 DSH。
   • 全新安装不用手工改：dsh plugin --profile <profile> add github:Noob-stupid/dsh-breadboard
2. Skill 名和面板 key 都变了：以前写 skill dsh-hardware-sandbox 的提示词/文档要改成 dsh-breadboard；
   重启后侧栏面板会以新 key 注册（旧的注册项随旧 bundle 一起消失）。
3. 你的数据不动：导入的模型与项目本体仍在 ~/.dsh/dsh-hardware-sandbox/。
   这个目录刻意保留旧名 —— 改它等于让老用户的数据"凭空消失"，比名字不一致糟得多。
4. 旧版本原样保留：v0.1.0 / v0.1.1 的 tag 与 Release 都没动，随时可以回退。

三、这一版新加的东西：面板右下角 Star 钩子

• 3D 沙盒面板右下角（在既有「拖动组件＝移动…」操作提示上方）增加一行：
  「喜欢这个插件？去 GitHub 点个 Star」。
• 图标是内联 GitHub mark（SVG），不引外链图片、不引第三方脚本或字体；链接指向本仓库，
  新标签页打开并带 rel="noreferrer noopener"。
• 纯展示：不读装配快照、不发动作、不参与仿真；面板既有子项一个没动，只在最后追加一项，
  窄宽度下不会溢出（容器宽度上限 = 面板宽度 − 左右各 12px）。
• skill/SKILL.md 末尾也补了一句同样的提示（点不点都不影响功能）。

四、已知限制（不夸大）

• 界面文案仍然只有中文，钩子也只有中文一句。
• 随包的 4 个模型（bme280 / esp32-seat-sensor / hc-sr501 / led-5v，均为自产）的二进制里，
  生成器标记仍写着旧名 —— 未重新生成模型，不影响使用。
• ~/.dsh/dsh-hardware-sandbox/ 目录名保留旧名，没有做自动迁移。
• 本包仍未发布到 npm：从 GitHub 安装，或直接下载本页的 tgz。
• .gitignore 里那条 tgz 忽略规则仍写成旧的文件名前缀，npm pack 的产物名（noob-stupid-…）
  不在其覆盖范围内 —— 纯属开发期整洁问题，不影响功能。

五、验证

• npm test：310 项全绿（基线 308 ＋ 新增 2 项）。
  新增的两项是本次需求点名的断言：Star 钩子的事实层（目标仓库 / 内联 mark / 两个 rel token），
  以及面板渲染后右下角钩子存在且 href 指向本仓 ——
  用仓库自带的 react 替身（tests/doubles/react.ts）在 node --test 里真渲染一次面板，不引任何新依赖。
• 两个 tsc（宿主半 tsconfig.json / 前端半 tsconfig.client.json）均通过；bash scripts/build.sh 产出 lib/ ＋ lib/client.js。
• 包内清单（npm pack）：135 项 —— lib/（含 client.js 与 project-shim/）、cordis.patch.yml、
  skill/、docs/、models/（仅上述 4 个自产）、scripts/；无第三方模型、无 tests/、无 src/。
• 产物：noob-stupid-dsh-breadboard-0.2.0.tgz，1,409,698 字节，
  sha256 56263e6f05a5196103fb03752b85778c0e875c985c108795977b05e747da063b。
• ⚠️ 未在真实浏览器里目视那个钩子的位置与外观（只做了渲染断言与构建产物检查）——
  打开面板看一眼即可确认。

v0.1.1

纯粹文档/资产回订小版本，基于工作树 v0.1.0 的文档修正（基点 master 7242782）：

「SKILL 的原因码表从 8 项补全为契约的全部 12 项」：补上 bad_params、direction_conflict、protocol_mismatch、port_occupied、voltage_mismatch、power_exceeded、i2c_address_conflict、i2c_pullup_missing、unconnected_port、unknown_hardware_model、component_pinned、already_connected —— 对 master 7242782 的修正在发布包内生效（v0.1.0 发布包内的 SKILL.md 当时还是 8 项）。

与 0.1.0 的关系：除 package.json 版本号外，代码零变更 —— 比对 v0.1.0 与 v0.1.1 两个 tgz，cordis.patch.yml、models/*（8 个文件）、README、scripts 逐文件 sha256 一致；lib 全量重新构建。

附件：dsh-breadboard-dsh-hardware-sandbox-0.1.1.tgz（1.39 MB，134 条目）
sha256: 01411aa2182405956aa28ed28ef182982fa91cde3331510e8bd697f89b61adf5