circuitsnap

拍下它，仿真它。 将电路图纸——照片、草图，或仅仅一段描述——变成 Falstad's CircuitJS1 中的实时仿真。

以 MCP 服务器（让 Claude 和其他助手能够构建电路）、CLI 和库的形式提供。

$ circuitsnap build rc.json
https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgo...

$ 1 0.000005 10.20027730826997 50 5 50
v 128 64 192 64 0 0 40 5 0 0 0.5
r 384 64 448 64 0 10000
c 128 176 192 176 0 0.000001 0 0
...

打开 URL，电路即开始运行。

为什么

让语言模型直接编写 CircuitJS1 的文件格式是行不通的。该格式基于位置且毫不宽容——v 128 64 192 64 0 0 40 5 0 0 0.5 有六个尾部参数，其顺序、单位和标志位只能通过阅读模拟器的 Java 源码才能发现。一次错误猜测会产生一个能顺利加载却仿真错误的电路，这是最糟糕的失败：用户无法察觉。

circuitsnap 将这项工作移入经过测试的代码。模型只描述什么连接到什么；格式、几何、转义和编码都由这个库处理。

Related MCP server: circuit-sim-mcp

安装

npm install -g circuitsnap

作为 MCP 服务器

{
  "mcpServers": {
    "circuitsnap": { "command": "npx", "args": ["-y", "circuitsnap-mcp"] }
  }
}

（circuitsnap 是 CLI；circuitsnap-mcp 是 stdio 服务器。如果你更喜欢单个二进制文件，circuitsnap mcp 也可以运行服务器。）

对于 Claude Code，还要将 skills/circuitsnap/ 复制到 .claude/skills/ 中，以获得 /circuitsnap 工作流，它涵盖读取图纸和验证结果。

用法

将电路描述为网表——元件和网络名称，不需要坐标：

{
  "title": "RC lowpass",
  "components": [
    { "id": "V1", "kind": "voltage",   "nodes": ["gnd", "in"],  "value": 5 },
    { "id": "R1", "kind": "resistor",  "nodes": ["in", "out"],  "value": "10k" },
    { "id": "C1", "kind": "capacitor", "nodes": ["out", "gnd"], "value": "1uF" }
  ]
}

共享同一网络名称的端子即相连。这就是全部模型。

circuitsnap build rc.json          # URL + circuit text
circuitsnap build rc.json --url    # just the URL
circuitsnap elements               # pin order and parameters for every kind
circuitsnap decode "<share-url>"   # read someone else's circuit

作为库使用：

import { snap } from 'circuitsnap';

const { url, text, diagnostics } = snap({
  components: [
    { id: 'V1', kind: 'voltage',  nodes: ['gnd', 'in'], value: 5 },
    { id: 'R1', kind: 'resistor', nodes: ['in', 'gnd'], value: '1k' },
  ],
});
console.log(url.url);

数值

工程记数法，按照人在原理图上的书写方式：

M 是兆，m 是毫——这是原理图惯例。SPICE 中 M 表示毫，这会把手工标注的“10M 电阻”变成 10 毫欧。

元件

wire, resistor, capacitor, inductor, voltage, rail, ground, switch, diode, led, current, labeledNode, transistor, opamp, output, probe, text。

运行 circuitsnap elements 可查看引脚顺序、参数、单位和默认值。引脚顺序很重要：晶体管是 [base, collector, emitter]，运算放大器是 [minus, plus, out]。

接地

使用网络名称 gnd（或 ground、0、vss）。这些端子会获得真正的接地符号，而不是标签——名为“gnd”的标记节点不携带 0 V 参考点，会让求解器失去基准。如果电路完全没有接地，circuitsnap 会发出警告。

工作原理

流程是 网表 -> 验证 -> 布局 -> 生成 -> URL，其中只有读取图纸这一步需要模型。有两个决策值得了解：

• 网络通过命名标签连接，而不是布线。 一个 95% 正确的自动布线器会生成看起来正确但仿真错误的电路。引脚旁的标签是可验证的。输出读起来像层次化原理图。

• 我们生成的是旧版文本格式，而非 XML。 当前上游写入 XML，但仍然读取文本，因此文本是唯一能在新旧版本上都能加载的编码。

有关理由，请参阅 docs/ARCHITECTURE.md；有关文件格式参考（源自上游源码并附行号引用），请参阅 docs/FORMAT.md。

正确性

该格式是逆向工程得来的，因此正确性至关重要：

• 372 个上游电路经过解析器往返后字节完全一致。

• 生成的输出会检查端点重合、转义以及上游强制开启的标志位。

• 实时验证：将生成的电路加载到真实模拟器中，并读回节点电压。多引脚几何结构就是这样验证的——运算放大器跟随器必须真正跟随，晶体管必须报告 fwd active，且 Ic/Ib = β。

npm run reference:fetch   # clone upstream (not vendored; see docs/LICENSING.md)
npm test

测试套件不发起任何网络请求。

许可证

circuitsnap 采用 MIT 许可证。CircuitJS1 由 Paul Falstad 和 Iain Sharp 编写，采用 GPL-2.0-or-later 许可证，此处既不捆绑也不修改它——circuitsnap 生成其格式的文件并打开其 URL。完整理由请参阅 docs/LICENSING.md，其中还说明了本项目如何处理 falstad.com 的 AI 爬虫信号（简而言之：不爬取、不抓取，测试完全离线，--base-url 可让你指向自己的自托管副本）。

与 CircuitJS1 作者无关联，也未获得其认可。