pcb-pilot · 嘉立创EDA 电路板助手

让 AI agent 直接操控**嘉立创EDA专业版（EasyEDA Pro）**画原理图和 PCB。

给 Claude Code / Codex / DeepSeek Harness / Qoder 等 agent 装上一双「画板的手」：通过 MCP 调用 typed action，真实地建工程、搜立创商城器件、放件、连线、布局布线、跑 DRC、导出 Gerber/BOM。

仅支持专业版桌面客户端（标准版/网页版没有扩展 API）。面向离线/本地工程模式。daemon / CLI / MCP 支持 Windows、macOS、Linux（三平台 CI 矩阵已在 GitHub Actions 首跑通过，含 POSIX 专属权限用例）；EDA 真机联调目前只在 Windows 上做，macOS/Linux 请按 docs/platforms.md 自行验证。

架构

┌─────────────┐   MCP (stdio)   ┌──────────┐   loopback HTTP   ┌──────────┐   WebSocket    ┌──────────────────┐
│ Claude Code │◄───────────────►│ pcb-pilot│◄─────────────────►│  daemon  │◄──────────────►│ EDA .eext 桥接扩展│
│ Codex / DSH │                 │  mcp     │                   │          │                │ (eda.* 官方 API) │
│ Qoder       │                 └──────────┘                   └────┬─────┘                └──────────────────┘
└─────────────┘                                                     │
                                                  ~/.pcb-pilot/{token, audit.jsonl, output/}

• daemon：独占 WS 端口（默认 49630）+ 本机 RPC（49631），动作串行执行，写审计日志。

• MCP 适配器：40 个动作 + status 工具，stdio 接入任意 MCP 客户端。

• .eext 扩展：在 EDA 内运行，用官方 eda.* API 执行动作，写动作回传 readback。

• Skill：告诉 agent 怎么读工程、选器件、画图、自检、出制造文件。

Related MCP server: a2n-easyeda-mcp

5 分钟上手

# 0. 平台特有的客户端准备（macOS Gatekeeper、Linux 无固定安装目录）见 docs/platforms.md

# 1. 安装 CLI（Node >= 20.17）
npm i -g pcb-pilot

# 2. 安装 Agent Skill，并打印 MCP 注册命令
pcb-pilot install

# 3. 在 agent 客户端注册 MCP（按 install 输出执行），例如：
claude mcp add pcb-pilot -- npx -y pcb-pilot mcp
# 或
codex mcp add pcb-pilot -- npx -y pcb-pilot mcp

# 4. 启动 daemon 并查看配对 token 路径
pcb-pilot start
pcb-pilot status

# 4.5 环境不对时一条命令自愈：补齐 token、安装 Skill、拉起 daemon
pcb-pilot doctor --fix

# 5. 在嘉立创EDA专业版里：
#    a. 扩展管理器安装 GitHub Release 里的 pcb-pilot-bridge_v*.eext 并启用
#    b. 打开「允许外部交互」
#    c. 打开一个原理图/PCB 文档
#    d. 菜单 PCB Pilot → 设置 Token，粘贴第 4 步显示的 token
#    e. 菜单 PCB Pilot → 重连

# 6. 自检全绿
pcb-pilot doctor

然后在 agent 里说话：

帮我建一个新工程，用 ESP32-C3 + AMS1117-3.3 做一个温湿度传感器板：I2C 接 SHT30，板载 WS2812 指示灯，按 2.54mm 网格画原理图并做 DRC。

Agent 会按 Skill 的工作流读现状、搜库选型、放件、连线、读回校验、导入 PCB、布局布线、DRC、导出制造文件。

客户端注册

多个客户端可以同时连接同一个 daemon；agent 重启不会断开 EDA 桥。

离线/本地工程模式

v1 面向离线/本地工程：project.create 不依赖云端 team，工程落在本地。器件库搜索能力受客户端离线模式限制——搜索不到时 Skill 会提示用户，而不是臆造器件。

平台说明

三平台共用一个数据目录 ~/.pcb-pilot/（POSIX 上 token 与 audit.jsonl 收紧为 0600，本工具新建的目录为 0700），daemon 端口 127.0.0.1:49630/49631。EDA 客户端位置按 PCBP_EDA_DIR → 各平台默认目录 → PATH 里的 lceda-pro 顺序探测；探不到只算提示（!），不会让 doctor 判失败——扩展连上 daemon 才是可用信号。细节（Gatekeeper 放行、Linux zip 解压即用、切换在线/离线模式后需重新导入 .eext）见 docs/platforms.md。

自愈：agent 调动作时如果 daemon 根本没在跑，客户端会先自动拉起再重试一次（仅在确认 daemon 未运行时重放；进程活着但不响应时写动作绝不重放）；pcb-pilot doctor --fix 一次性补齐 token、Skill 与 daemon，扩展连接仍需你到 EDA 里操作。

安全模型

• 所有监听只绑 127.0.0.1，不外网。

• 扩展连接需要配对 token（~/.pcb-pilot/token，首次启动自动生成）。

• 没有任意 JS 执行通道：只有白名单 typed action，协议层 zod 校验。

• 写动作必须带 readback（含 projectUuid）；工程中途切换会返回 READBACK_MISMATCH 并停止写入。

• 所有动作写审计日志 ~/.pcb-pilot/audit.jsonl。

• 制造文件落盘到 ~/.pcb-pilot/output/，文件名做了目录穿越防护。

开发

npm install
npm run build && npm test          # daemon / MCP / CLI / 协议
npm install --prefix extension
npm test --prefix extension        # 扩展 dispatcher / ws-client（stub eda）
npm run build --prefix extension   # 产出 extension/build/dist/*.eext（需 Node >= 24）

真机联调清单见 docs/smoke-test.md。

商标与许可

• 本项目使用 Apache-2.0 许可。extension/ 内构建脚本 vendor 自 easyeda/pro-api-sdk（Apache-2.0），已保留来源注释。

• 「嘉立创EDA」「EasyEDA」为嘉立创科技集团股份有限公司商标，本项目与官方无隶属关系，商标仅用于描述兼容性。

• 本项目不会代替你下单；Gerber/BOM 请自行核对后再送厂。

路线图

• macOS / Linux 支持（代码、探测、权限与三平台 CI 矩阵均已通过；EDA 真机验证待用户/社区按 docs/platforms.md 反馈）

• 多 EDA 实例

• 铺铜编辑、差分对/等长规则动作

• 官方扩展商店上架