Breadboard Studio

在浏览器里拼面包板或洞洞板、摆元件、自动接线，再按图搭建你的电路。

Breadboard Studio 是一个开源的面包板布局工具：你可以直接操作画布，也可以让 AI Agent 通过 CLI 和 JSON 设计文件参与搭建。两种方式共用孔位、导通关系和校验规则。

在线体验 · 快速开始 · 贡献元件 · 反馈问题 · English

环境节点示例。截图中的部分元件来自示例目录；元件库默认展示精选型号，其余内置型号按类目折叠。

先试一试

打开 在线演示，无需安装或登录，建议使用电脑浏览器。

1. 在左上角「项目」菜单中载入一个示例，直接查看完整接线。
2. 点击面包板孔位，观察同组孔和导通网络的高亮。
3. 移动元件、调整导线，查看下方校验提示；可以随时撤销。
4. 打开「搭建」标签，按线号逐根接线，或导出 SVG / PNG 分享布局。

想从零开始？从元件库添加面包板与元件，按 R 旋转后点击孔位放置。多选一个主控与外设，即可在右侧选择线材并自动排线。

设计会自动保存在当前浏览器中，也可以导出 .breadboard.json 备份、分享或在另一台设备上继续编辑。

当前版本提供布局、布线和静态校验，也可以为主控编写程序并运行：代码在隔离沙箱里真实执行，能驱动板载 RGB、打印串口、经真实 I²C 总线把画面写进 OLED，并按虚拟时间暂停与单步。见仿真器方案与实施计划。

可以怎么玩

按实物结构拼板

支持一体式 400 / 830 孔面包板、完全拆开的中间接线板与 +/− 电源条，也支持 5×7 cm / 7×9 cm 洞洞板。板件可以独立移动、旋转和复制；可拆面包板模块还支持机械拼接。

• 一体式 400 孔板上下拼接，当前模型支持 ESP32-S3 N16R8 跨上板 j / 下板 a 行。
• 可拆拼装式由 300 孔中间板和 2×25 孔电源条组成；两块中间板之间夹一条电源条，支持跨 h / b 行。
• 拼接只改变物理位置；相邻板件的电源轨不会自动导通。
• 洞洞板的每个镀锡焊盘默认独立不导通；元件可直接焊在孔位，导线或焊锡桥接任意两个孔。画布可切换元件面与焊接面。

引脚随锚点落孔，编辑器会区分占用孔与板体遮挡区域，并报告脱格、同孔冲突和板体碰撞。不同实物型号的尺寸仍需核对。

选择线材，让工具帮你接线

多选一个主控或电源主板与多个外设，自动排线会根据引脚角色规划电源、GND、I²C 和 GPIO 连线。它会利用电源轨、尝试缩短走线，并报告无法连接的引脚；整批操作可以一次撤销。

I²C 地址冲突时，规划器可根据型号能力分配另一条总线或调整地址配置，并提醒你核对硬件和固件。搜索范围、优化策略与 CLI 选项见 Agent 指南。

看清元件，也能自己修改外观

悬停元件库条目，即可查看模型预览、尺寸、引脚数量和简介。默认展示的精选型号由定义里的 featured 决定：

有反面绘图的元件会在悬停详情里并排展示正面和反面；旧元件仍只显示正面。N16R8 板载 RGB 灯支持输入 RGB 值，OLED 支持白色或蓝色显示外观；这些目前是外观属性。

选中元件后打开「编辑外观绘图…」，可以移动、复制、旋转和删除绘图中的小部件，也可以叠加实物照片对位。板子画错了就用「写回元件库」（本地 pnpm dev 下可用），直接覆盖 packages/catalog/src/definitions/ 里的定义，所有项目一次改好；只想让当前项目长得不一样，用「保存到本项目」。

目录里剩下的型号（LED、电阻、XIAO、各类传感器转接板、供电模块、原厂 DevKit 模板等）没有从库里消失，而是折叠在每个类目的「更多内置型号」里，点开即可添加；搜索框始终覆盖整个目录。卡片上的「几何近似 / 电气近似 / 未知」徽标说明这份定义有多少证据支撑——徽标不是禁用，未知的型号照样能放，只是提醒你按实物核对。你也可以在元件库导入自定义定义，无需修改应用代码，详见元件建模说明。

从屏幕走到实物

导通高亮帮助你检查连接关系；校验面板区分错误、警告和待审核事项。右侧「接线向导」按线号列出两端孔位与颜色，并保存完成进度。

顶栏分三区：左边是项目与导出，中间是当前模式下的工具，右边是视图与状态。画布上显示什么（孔号、针脚名、导通高亮、聚焦选中、元件面/焊接面）都在「视图」里；接线时的线色与走线方式在「接线选项」里，按钮上的色点就是当前线色。窗口较窄（≤1480px）时字标会让位给工具。

搭建、仿真与实机

顶栏右侧的开关把界面分成三块，各自的职责不重叠：

从「仿真」切走会结束当前会话——这正是开关的承诺：在搭建里设计总是可改的，在仿真里总是冻结的。会话进行中仍可改的，只有引擎本来就允许的那些：程序源码与仿真参数（改源码会让会话因快照过期而停止）。

「实机」不是仿真，也没有注册成仿真后端：真板的引脚接的是你桌上的真元件，画布上模拟的 OLED 与传感器不在那个电路里，一颗真实 MCU 也没法暂停、单步或回放。它只做两件小而真的事——把串口的字节按行显示出来，以及按自动复位电路的时序拉一下 EN（走原生 USB 口的板子没有这条电路，所以按钮说的是「复位脉冲」而不是「已重启」）。烧录固件还没有做。需要 Chromium 系浏览器的 Web Serial 与 https/localhost；不满足时面板会写明原因，而不是给一个按了没反应的按钮。离开「实机」会挂断串口。

快速开始

本地开发需要 Node.js ≥ 20.19 和 pnpm 11，仓库指定版本见 package.json。

git clone https://github.com/7dul2/breadboard-studio.git
cd breadboard-studio
npm install -g pnpm@11.25.0
pnpm install
pnpm dev

打开 http://localhost:5173。运行 pnpm build 后，静态站点输出到 apps/web/dist，可部署到自己的服务器。

pnpm test                              # 核心、目录、渲染与 CLI 测试
pnpm typecheck                         # 类型检查
pnpm exec playwright install chromium  # 首次运行浏览器测试前安装
pnpm test:e2e                          # 浏览器关键流程
pnpm build                            # 构建静态站点
pnpm perf                             # 4 板 / 20 模块 / 100 线性能样本

让 Agent 参与搭建

Agent 可以直接读取型号、检查设计、应用补丁和生成布线，不需要通过截图猜测孔位。同一份 .breadboard.json 可以在人和 Agent 之间交接。

# 查看模型和校验已有示例
pnpm bb catalog inspect esp32s3_n16r8_dual_usb@1 --json
pnpm bb validate examples/environment_node.breadboard.json --json

# 为自己的项目试算布线（mcu、oled 是项目中的实例 ID）
pnpm bb autowire design.breadboard.json --host mcu --components oled --dry-run --json

# 检查补丁，并导出布局图
pnpm bb apply design.breadboard.json --patch edits.json --dry-run --json
pnpm bb export design.breadboard.json --format svg --out layout.svg

补丁原子执行，结构错误会阻止整批应用；revision / hash 检查可避免并发覆盖。若由程序直接解析 JSON，使用 node packages/cli/bin/bb.mjs 入口，避免 pnpm 的错误日志混入输出。

Agent 也可以用 MCP 直接调用同一个引擎，连 shell 都不需要：

claude mcp add breadboard -- node packages/cli/bin/bb.mjs mcp

bb mcp 在 stdio 上暴露九个只读工具加两个默认 dry-run 的写工具（autowire、apply_patch），返回体与 CLI 的 --json 完全一致；写文件必须显式 write: true。工具清单与错误约定见 Agent 指南。

完整命令、补丁示例与自动排线规则见 Agent 指南和设计文件格式。

示例项目

当前边界与后续方向

当前模型适合规划布局和辅助接线。内置几何尚未全部实测，针序、排距和电源轨分段需要与你的实物一致；没有错误提示不代表电路已经验证可安全上电。

• 支持 2.54 mm 栅格和 90° 倍数旋转，暂不支持任意针距及三维碰撞分析。
• 静态检查支持 I²C 上拉缺失/未知/并联提示，以及 strapping、USB、JTAG 复用风险；自动排线优先避让复用脚，拒绝 reserved 存储器脚。总线电容、上升时间、固件/eFuse 状态仍需实物核对。
• 定义升级 verified 需要可追溯 evidence 与人工复核，几何还需要实测；当前内置定义没有 verified 项。无需写代码也能按 实测指南 提交尺寸、针序、轨道或上拉报告。
• 自动排线依赖型号数据，复杂布局可能需要手动整理；大网络的优化包含启发式搜索。
• 设计数据保存在浏览器本地，暂无云同步和多人协作；建议定期导出 JSON。

后续重点是补充并实测元件、改进布线体验，以及把交互式仿真做完整。仿真器已完成阶段 1 到阶段 3：用户代码在 QuickJS 沙箱里真实执行，可驱动 ESP32-S3 的 GPIO 与板载 RGB，支持暂停、单步、复位与倍速；触摸键与 BOOT/RST 可以直接在画布上按；I²C 是控制器级的真实总线，SSD1315 OLED 的画面由程序一字节一字节写进去——断线、错地址、没供电各自报出不同的诊断，而不是屏幕默默不亮。分立 LED 也能点亮了：电阻在导通图里是真正的二端元件，GPIO → 电阻 → LED → GND 会按预期发光，而电源与地之间的电阻会报出估算电流而不是被误判成短路。SHT4x 温湿度传感器可以读了：在仿真面板拖动温度滑杆，程序下一次测量就会读到新值——命令、转换延时、CRC 一样不少，忘记等待转换完成会像实物一样收到 NACK。LTR390 光照/紫外与 SEN66 空气质量模块也能读了，三种 I²C 寻址形态（命令字、寄存器指针、16 位命令 + 每字 CRC）都建了模。BMP390 还没有驱动。仿真面板下方多了一条时间线：每条网络的电平跳变都画成方波，点一下网络名就在它下次跳变时暂停。操作还会被录下来：每一次按键或拖动都带着它生效的虚拟时刻，点「回放本次」就能从头重跑同一场景，也可以导出成文件复现问题。BMP390 气压传感器也做完了，阶段 4 至此完成：它报的是原始 ADC 值，程序得自己读标定块、跑数据手册的补偿多项式才能得到压强——照真实库写的代码在这里算出来的就是滑杆上的那个数。阶段 5「真实固件后端」按计划先做了 RFC 与技术验证，结论是已调查并谢绝：浏览器里没有任何东西能编译 Xtensa，ESP32-S3 的 QEMU 模型恰好缺 GPIO 与 I²C，理由与证据见 docs/PHASE5_RFC.md。这次调查里唯一站得住的那部分被改名做成了独立功能「实机」：用 Web Serial 连一块真板看它的串口输出，并按自动复位电路的时序拉一下 EN——它不冒充仿真，也没有注册成仿真后端。

一起完善它

你不必会写代码才能参与：实物尺寸、引脚核对、接线示例、使用反馈都能帮助项目变得更准确。

• 报告问题：附上复现步骤和可分享的设计文件。
• 请求或补充元件：提供型号、尺寸、针序与资料来源。
• 提出功能建议，或按贡献指南提交 PR。
• 如果你用它搭出了作品，欢迎在 Issues 分享布局与实物照片。

感谢所有贡献者。如果这个工具对你有帮助，欢迎给仓库一个 Star，或把在线演示分享给一起玩电子的朋友。

更多文档

架构与坐标约定 · 设计文件格式 · CLI / Agent · 元件建模 · 进度与验证记录 · 仿真器方案 · 可执行仿真实施计划 · 洞洞板体验需求

也可以直接在站点上阅读：在线文档

MIT 许可证，见 LICENSE。第三方声明见 THIRD_PARTY_NOTICES.md。

English

Plan your breadboard circuit in the browser, route its wires, and follow the layout at your workbench.

Breadboard Studio is an open-source layout editor for people and AI agents. It includes modular breadboards, independent-pad perfboards, pin-to-hole placement, manual and automatic routing, copy/paste that drops parts into the holes under your pointer, connectivity highlighting, static validation, an artwork editor, and wire-by-wire build instructions. A switch in the toolbar splits the app in three: 搭建 (build) edits the circuit, 仿真 (simulate) runs it — leaving 仿真 ends the session, so the design is always editable on the build side and always frozen on the other — and 实机 (real board) opens a Web Serial connection to actual hardware to read its log, which is deliberately not a simulation backend. Export your project as JSON, SVG, or PNG.

Try the online demo without an account. Load an example from the Project menu to explore a complete design. Projects are saved locally in your browser; JSON export lets you back them up or share them.

The CLI and browser share the same geometry, connectivity graph, and transaction engine. Agents can inspect and edit .breadboard.json files directly, or call the same engine as tools over MCP (bb mcp; its write tools stay dry-run until asked to write). See the Agent guide for commands, MCP setup, and patch examples.

Programs now run: user code executes in an isolated QuickJS sandbox on a deterministic virtual clock, driving the board's on-board RGB, the serial console and — over a real controller-level I²C bus — the SSD1315 OLED, with pause, single-step, reset and playback speed. Buttons and touch input work on the canvas and reach the program through the real wiring. Cut a wire, use the wrong address or leave the panel unpowered and each fails differently, with a diagnostic that names the fix. Current checks do not replace verification of the actual hardware. Contributions of component definitions, measurements, examples, and fixes are welcome. MIT licensed.

视图与线色操作

导线工具和属性面板可直接点选 12 种线色，也可用取色器自定义。缩放按钮支持键盘单击和按住连续缩放；Ctrl/⌘ + 滚轮连续缩放。视图旋转按钮左键顺时针 90°、右键反向，旋转后可用「适应全部」重新居中；只改变视图，不修改元件位置或导出设计。