Breadboard Studio 打开编辑器

Agent 使用指南（不依赖浏览器）

CLI 入口：pnpm bb <命令>（等价于 node packages/cli/bin/bb.mjs）。所有命令支持 --json 输出稳定 JSON；错误时退出码非零。由程序解析 JSON 时请直接调用 node packages/cli/bin/bb.mjs …：pnpm 在子命令非零退出时会往 stdout 追加一行 [ELIFECYCLE] Command failed…，会破坏 JSON。

退出码 含义
0 成功（validate 时表示没有 error）
1 设计存在 error / 文件无效 / 补丁被拒绝
2 用法或 IO 错误
3 revision / hash 冲突（并发修改保护）

MCP server（工具通道）

bb mcp 在 stdio 上启动一个 MCP server。它不重新实现任何东西：每个工具都是上面 CLI 命令的数据层，返回体就是同一个 --json 载荷，所以 shell 与 MCP 两条路不会出现两套语义。stdout 只有协议流量（没有横幅、没有日志），日志一律走 stderr。

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

{
  "mcpServers": {
    "breadboard": { "command": "node", "args": ["/path/to/breadboard-studio/packages/cli/bin/bb.mjs", "mcp"] }
  }
}
工具 写文件 对应命令 / 说明
catalog_list / catalog_inspect 否 catalog list / catalog inspect：引脚角色、reserved 保留标记、参数 schema、证据状态
design_inspect 否 inspect：元数据、revision/hash、板、引脚落孔、导线、网络、程序
design_validate 否 validate：全部规则与逐条建议
connectivity 否 connectivity：导通组、网络、导通集合
build_steps 否 steps：逐线搭建步骤
list_programs 否 programs：程序列表与仿真配置（不含源码）
list_ops 否 ops：补丁操作类型与字段
export_design 否 export：SVG / 规范化 JSON，内容直接返回（不落盘）
autowire 默认 dry-run autowire：按引脚角色规划布线；write: true 才写
apply_patch 默认 dry-run apply：原子补丁；write: true 才写

三条约定：

命令

pnpm bb catalog list --json                       # 可用面包板与元件（含证据状态）
pnpm bb catalog inspect xiao_esp32s3_sense@1 --json
pnpm bb new design.breadboard.json --name "我的节点"
pnpm bb inspect examples/environment_node.breadboard.json --json     # 引脚落孔、导线、网络、hash
pnpm bb validate examples/environment_node.breadboard.json --json    # 全部规则
pnpm bb connectivity examples/environment_node.breadboard.json --from bb_a.a7 --json
pnpm bb autowire design.breadboard.json --host mcu --components sht41,bmp390 --dry-run --json
pnpm bb apply design.breadboard.json --patch edits.json --dry-run --json
pnpm bb apply design.breadboard.json --patch edits.json --out revised.breadboard.json --expect-revision 2
pnpm bb export revised.breadboard.json --format svg --out layout.svg
pnpm bb steps revised.breadboard.json --json
pnpm bb programs design.breadboard.json --json                                   # 程序列表与仿真配置
pnpm bb program export design.breadboard.json program_main --out main.ts         # 源码原样写出
pnpm bb program import design.breadboard.json program_main --source main.ts --target mcu --activate --json
pnpm bb schema          # 设计 JSON Schema
pnpm bb ops             # apply 支持的操作

补丁格式

{
  "expected_revision": 2,
  "ops": [
    { "op": "add_board", "board": { "id": "bb_b", "model": "breadboard_400@1", "attach_to": { "board_id": "bb_a", "side": "right", "grid_align": true } } },
    { "op": "add_component", "component": { "id": "sht41", "model": "sht41_breakout@1", "placement": { "kind": "board", "board_id": "bb_a", "anchor_hole": "j12", "anchor_pin": "VCC", "rotation_deg": 0 }, "config": { "i2c_address": 68 } } },
    { "op": "add_wire", "wire": { "from": { "pin": "mcu.D4" }, "to": { "pin": "sht41.SDA" }, "color": "blue", "route": "elevated" } },
    { "op": "add_net_intent", "net_intent": { "id": "n_sda", "name": "SDA", "endpoints": ["mcu.D4", "sht41.SDA"] } },
    { "op": "update_property", "id": "sht41", "path": "config.i2c_address", "value": 69 },
    { "op": "add_program", "program": { "id": "program_main", "name": "读取温湿度", "target_component_id": "mcu", "source": "import { Serial, sleep } from '@bbs/runtime';\nexport async function loop() { Serial.println('tick'); await sleep(1000); }\n" } },
    { "op": "set_simulation_config", "patch": { "active_program_id": "program_main", "speed": 1 } }
  ]
}

操作清单：add_board、remove_board、move_board、rotate_board、resize_board、add_component、remove_component、move_component、rotate_component、add_wire、remove_wire、update_wire、update_property、add_net_intent、remove_net_intent、update_net_intent、add_constraint、remove_constraint、set_metadata、replace_design、add_definition、remove_definition、auto_wire、add_program、update_program、remove_program、set_simulation_config。字段见 pnpm bb ops。

resize_board 按孔距缩放已有板件：{ op: "resize_board", id: "bb_1", columns: 40, rows: 5 }。以原型号为模板派生一份新定义（id_custom + version+1），内嵌进 embedded_catalog；不改内置型号。列数整数 5–120，行数 1–原行数（面包板按每块接线块的行数算，洞洞板按整板物理行数算）；越界拒绝（不是 clamp），裁掉仍被元件/导线/net_intent 引用的孔位时也拒绝并报出孔号。同一块板再次调整仍从原型号重新派生，所以一次尺寸编辑 = 一次事务 = 一次撤销。

autowire / auto_wire 按目录中的引脚角色连接一个主控或电源主板与多个外设：

程序与仿真

schema 1.1 起，设计文件可以带 programs[]（主控实例的 Studio TS 源码）和 simulation（启动程序、倍速、随机种子、USB 供电主板），格式见 设计文件格式。源码是设计内容：修改走 add_program / update_program / remove_program / set_simulation_config，每次都是一次事务（revision +1、参与 hash、可撤销），目标元件必须存在，删除主控需要 cascade 才会连程序一起删。bb programs 列出程序与配置（inspect 也包含 programs/simulation），bb program export 把源码原样写出，bb program import 从源码文件新建（需要 --target）或更新程序，--activate 同时设为启动程序；它与 apply 一样支持 --dry-run、--out、--expect-revision/--expect-hash（冲突退出码 3），失败时不写文件。CLI 不执行代码：没有任何命令会运行仿真；代码在浏览器的 QuickJS 沙箱里真实执行，详见 SIMULATOR_DESIGN.md。目标定义缺少 simulation.driver 时 bb validate 报 program_target_unsupported（警告），不是错误。

结果格式

每条规则结果：

{ "severity": "error", "code": "power_ground_short", "category": "net", "blocking": false, "message": "…", "objects": ["mcu"], "endpoints": ["mcu.3V3_1", "mcu.GND_1"], "suggestion": "…" }

severity ∈ error | warning | needs_review | info；category ∈ schema | placement | board | wire | net | interface | evidence。needs_review 表示证据不足（模型未实测、供电能力未知、地址未知、电平未知），没有 error 不等于可以安全上电。

推荐工作流

  1. catalog list 选择型号，catalog inspect 查看引脚名、参数与状态。
  2. new 创建文件；用 apply 逐步添加板、元件、导线与网络意图（用 --dry-run 先看结果）。
  3. validate 直到没有 error；逐条处理 needs_review：在 config 中填写实测/资料数据后重新校验。
  4. connectivity 检查关键网络；export --format svg 出图；steps 生成接线步骤。
  5. 交给人在浏览器里打开同一文件继续编辑（“项目 → 导入”），双方共用同一套规则与事务引擎。

浏览器编辑器同样暴露 window.__bbs.apply(ops) 供自动化测试使用。