Skip to content

makoshan/vibehw-stack

v0.3.8MIT

The agent engineering stack for real hardware (inspired by pstack): from breadboard to schematic, JLCPCB/LCSC basic parts selection, KiCad autoroute & DFM gates, to 3D-printed enclosure fit.

vibehw-stack

CI License: MIT

我是 Mako。在 Lauren Tan 的 pstack 把软件工程纪律带进 AI Agent 之后,我遇到了下一个问题:当 AI 开始画原理图、摆 PCB、选嘉立创料号、导出 Gerber、切 3D 打印外壳时,「代码能跑 / DRC 为 0」距离「实物能点亮、能装进去」还差十万八千里。

商品图的尺寸不等于卡尺量出来的包络;嘉立创 EDA 报着 3 条 DRC 照样允许导出下单;一颗没锁 C 号的 7.68kΩ 电阻会在贴片匹配页多收你 ¥20 换料费;STEP 水密且两两干涉为 0 的外壳,排线座子朝向反了照样装不进去。

vibehw-stack 是我的答案。 这套技能诞生于我一个人 + 一群 AI Agent(Claude Code / Codex / Cursor)从零做出智能手表与 2 / 8 / 16 通道肌电手环(OpenEMG)的实战:39 版 3D 打印外壳、多代载板与双面 4/6 层高密度采集/主控板、真实嘉立创 PCB+SMT 打样与三维猴树脂外发。

它不教 AI 空谈电子学,而是把从想法到实物的七段路、每一段的硬门禁(Done 谓词)、以及**嘉立创生态(LCSC 基础库选料、Gerber/BOM/CPL 物理事实与背面镜像核查、KiCad 与嘉立创 EDA 专业版 .epro/.epro2 双栈审查、外壳装入与翻盖动态包络检验)**写死成可执行的脚本与 Skill。


安装(Install)

一键脚本安装(Claude Code / Codex / Agent Skills 通用)

git clone https://github.com/makoshan/vibehw-stack.git ~/.local/share/vibehw-stack
bash ~/.local/share/vibehw-stack/scripts/install.sh

# 可选:同时下载 pcb-reference 开源硬件与立创 C 号参考库(6197 块板 / 34.5 万器件 / 5.6 万带 C 号,压缩包 54 MB)
bash ~/.local/share/vibehw-stack/scripts/install.sh --with-pcbdb

脚本会将 skills/* 下的 23 个硬件技能软链到 ~/.claude/skills、~/.codex/skills 与 ~/.agents/skills。

Cursor / Claude Code 插件市场安装

仓库根目录自带符合 Agent Plugins 规范的 plugin.json 与 .cursor-plugin/plugin.json:

/add-plugin vibehw-stack

快速开始(Get Started)

任何硬件任务开工前,直接调用总控入口 /vibehw-stack:

/vibehw-stack 我想用 nRF52840 + ADS1298 做一块 8 通道肌电采集板,走嘉立创 4 层经济型 SMT,先过选型和基础库料号。

/vibehw-stack 会按当前所处阶段,自动调度下面七段路里的子技能,并在每段结束时执行对应的门禁脚本。


0. 硬件四条铁律(Core Principles)

铁律含义与实测反例
1. 实物为准商品图尺寸 ≠ 卡尺实测外包络;ERC 0 / DRC 0 ≠ 板能用;STEP 水密 + 两两干涉 0 ≠ 装得进去(必须验装入路径、焊点高度、排线弯折半径与插头深度)。
2. Agent 不碰钱打样、SMT 贴片、3D 打印外发、面板与元件采购,全部停在付款前。付款、地址与账号登录永远由人完成。
3. 通电前先断电核对供电/背光电流未确认前禁止点屏;满电 4.2V 锂电禁直连 3V3;焊接全程断电,焊完目视 + 万用表通断,锂电永远最后接。
4. 门禁是自己的,平台不会拦你嘉立创 EDA 带着未解决的 DRC 照样能导出下单。每次外发前必须跑通物理事实脚本并生成放行审核单(写清过了什么、缺什么、哪几条等实物)。

1. 从零到实物的七段路与 23 个子技能(The Seven Stages)

阶段做什么主力 Skill门禁(Done 谓词)
0. 总控路由判断当前阶段、派发子技能、守住四条铁律vibehw-stack阶段门禁通过 + 证据落盘
① 拆解与参考选型查真实开源板怎么接、芯片常配什么外围与立创 C 号pcb-reference · schematik · fcc-teardown拿到原厂 Datasheet 与真板接法,真机/开发板跑通
② 原理图、嘉立创选料与 PCB 布线设计时锁死立创基础库 C 号、KiCad/嘉立创/Altium 布局布线、高速与模拟分区jlc-basic-parts · pcb-design · pcb-autoroute · pcb-high-speed-layout · altium-mcpbom_rules.py 0 错 + floorplan_si_audit.py / basic_gate.py / layout_gate.py 全绿
③ 打板与 SMT 下单门禁独立核对 Gerber/Drill/BOM/CPL 物理事实、背面旋转约定、钢网开窗与面板丝印jlc-order · panel-artworkfab_facts.py + review_gate.py 通过 + 放行签字
④ 结构、外壳与 3D 打印参数化建模、验证板壳装入路径/连接器动态包络与限高、FDM/三维猴切片下单product-structure-design · hardware-structure-design · pcb-enclosure-fit · mako-cad-fit · ai-cad-pipeline · fdm-slicing · bambu-x2d-slice · jlc-3dpstep_export_check.py + interface_gate.py + fitprobe.py 通过 + 切片配合窗 0 支撑
⑤ 到板检验、标注、渲染与尺寸图实拍板卡引脚标注、影棚级 3D 渲染、Apple 风格工程尺寸图pcb-photo-annotate · product-render · dimensional-drawing · dimensional-drawing-motion实物万用表通断与供电验收通过

2. 嘉立创(JLCPCB / LCSC)工具链亮点

  1. jlc-basic-parts(设计期锁死基础库 C 号)
    • 优先选用嘉立创 SMT 基础库(免换料费),扩展库每种料号加收 ¥20。
    • 自带 bom_rules.py(检查重号、缺封装/值、同 MPN 不同封装、缺 C 号)与 bom_diff.py(版本间 BOM 变更对比)。
  2. jlc-order(Gerber / BOM / CPL 出厂门禁)
    • 自带 fab_facts.py 与 review_gate.py:从导出的制造包直接反读板框尺寸、层数、最小孔径、内层孤铜、封装 courtyard 间距,并绑定 Git commit hash 防篡改。
  3. pcb-reference(6,197 块开源真板 + 5.6 万立创 C 号共现查询)
    • 自带只读查询器 query.py:按芯片型号查开源真板最常搭配的外围阻容、封装与作者实选的立创 C 号(按 lift 去重排序)。
  4. 跨 .epro2 / .kicad_pcb 架构预审与「装得进、接得上」门禁
    • floorplan_si_audit.py:跨嘉立创 .epro2/.epcb2 与 KiCad .kicad_pcb 检查多脚芯片顶底同坐标硬叠、射频馈线超长/打孔、USB 差分偏斜与手绘板框微斜边。
    • interface_gate.py 与 fitprobe.py:声明式核查连接器开口朝向、三维翻转脚序、插头胶壳扫掠、滑入路径与浮动件限位。

3. 环境变量与可选外部依赖(Configuration & Not Shipped Here)

本仓库不包含任何硬编码私有地址。如需使用跨机算力卸载(Windows EDA / 远程 Linux),可通过环境变量覆盖:

环境变量默认值用途
MSTACK_WIN_HOST / WIN_HOSTthursday-win运行 Windows 版 KiCad / Altium / Freerouting 的 SSH 主机别名
PCBDB~/go/202609/vibe-hw/work/pcbdb/pcb.dbpcb-reference 的本地 SQLite 数据库路径(约 489 MB,不随 Git 分发)

推荐配合使用的上游开源 Skill(各自独立安装):

  • pstack(Lauren Tan 的通用软件工程 Skill 栈)
  • easyeda-eprj3-skill / easyeda-pro-format-skill(嘉立创 EDA 专业版官方 MIT 格式生成与校验 Skill)

4. 自检与测试(Verification)

在仓库根目录运行全套自检与单元测试:

bash scripts/check-no-pkill.sh
python3 -B scripts/check-bash32-cjk.py
python3 -B skills/jlc-basic-parts/scripts/test_bom_tools.py
python3 -B skills/jlc-order/scripts/test_fab_facts.py
python3 -B skills/jlc-order/scripts/test_review_gate.py
python3 -B skills/pcb-design/scripts/placement/floorplan_si_audit.py --self-test
PYTHONPATH=skills/pcb-autoroute/scripts python3 -B -m unittest discover -s skills/pcb-autoroute/scripts -p 'test_*_gate.py'
PYTHONPATH=skills/pcb-enclosure-fit/scripts python3 -B -m unittest discover -s skills/pcb-enclosure-fit/scripts -p 'test_*.py'

License

MIT © Mako Shan