用图数据库做电路体检：CircuitDoctor 如何提前发现接线错误

电路设计中，一个看似合理的原理图可能隐藏着电源与地短路、显示屏缺少供电、信号引脚接反等问题。对于电子初学者来说，定位这些错误往往需要追踪连接关系，理解元件之间的关联，门槛不低。开发者 Nayanjyoti 在 Graph Hacks 黑客松中构建了 CircuitDoctor，利用 FalkorDB 图数据库帮助用户在连接硬件之前检查 KiCad 电路的接线问题。

电路本身就是一张图

CircuitDoctor 的核心洞察很直接：电路天然适合用图建模。元件有引脚，引脚通过网络（net）连接。在 FalkorDB 中，这一关系被表示为 Component ──HAS_PIN──> Pin ──ON_NET──> Net。每次上传的电路都会生成独立的图，方便在修改前后进行版本对比。

对于支持的两脚电阻，系统还会在引脚之间创建 THROUGH 关系，让路径查询能够穿过电阻追踪连接。共享网络和穿过元件是两种不同的关系，模型将它们分开表示，避免混淆。这种建模方式让后续的连通性查询变得自然且高效。

网表（Netlist）与 KiCad 文件格式

CircuitDoctor 处理的 .net 文件是电子设计自动化（EDA）中的网表文件，它用文本形式描述电路中各元件及其引脚之间的连接关系，而不包含元件的物理布局或封装细节。KiCad 作为开源 EDA 工具，其网表通常由原理图导出，包含元件标识、引脚编号和网络名称等信息。CircuitDoctor 正是基于网表解析出“元件—引脚—网络”的图结构，因此它只能验证逻辑连接，无法获知实际 PCB 走线或元件内部电路。理解网表与原理图、PCB 布局之间的区别，有助于明确工具的能力边界：网表是连接关系的抽象，不描述电流路径或信号完整性。

FalkorDB 在幕后做了什么

FalkorDB 为 CircuitDoctor 的检查和解释提供连接数据。查询会识别共享同一网络的引脚，结合已验证的元件信息，标记出支持的接线冲突，包括电源对地短路和电压轨冲突。

用户选择两个引脚后，Cypher 的 shortestPath 查询会在 ON_NET 和 THROUGH 关系上搜索路径，如果找到路线，就在电路图上高亮显示。此外，应用使用 algo.WCC（弱连通分量）识别电路结构图中的独立分组——独立分组不一定是故障，但能提示用户注意可能值得检查的地方。

针对支持的开发板和显示屏，还有额外检查覆盖电源、地和 I2C 连接。这些功能基于上传的电路运行，而非绑定某个预定义示例。

Cypher 查询语言与图算法

Cypher 是面向属性图数据库的声明式查询语言，使用类似 ASCII 艺术的模式匹配语法，例如 (a)-[:ON_NET]->(b) 表示两个节点通过 ON_NET 关系相连。shortestPath 是 Cypher 内置的路径查找函数，可在指定关系类型上搜索两节点间的最短路径。algo.WCC 则指弱连通分量（Weakly Connected Components）算法，用于将图中相互可达的节点划分为独立子图。在电路场景中，WCC 能把通过导线或电阻连通的引脚归为一组，帮助识别电气上隔离的模块。这些查询能力使得 CircuitDoctor 无需遍历全部连接，即可快速定位关键路径和分组结构。

让查询结果可理解

拿到连接数据只是工作的一半，如何清晰呈现同样重要。开发期间原始查询结果很有用，但检查电路时，用户需要知道哪条连接关键、在哪里找到它。

CircuitDoctor 将发现的问题与交互式电路图并排展示，用户可以高亮相关引脚、追踪路线，无需阅读数据库输出。Gemini 则提供对话式探索：用户询问两个引脚如何连接，或请求解释某个警告时，Gemini 调用工具查询 FalkorDB 中的电路，再用返回的证据解释结果。目标是让解释可追溯到用户自己的文件。

Gemini 的工具调用（Function Calling）机制

Gemini 的对话式解释依赖工具调用能力：当用户提出“这两个引脚如何连接”等问题时，模型不会凭空生成答案，而是生成结构化查询请求，调用预先定义的工具函数（此处为查询 FalkorDB 的接口），获取图数据库返回的连接证据，再基于证据组织自然语言解释。这种模式将大语言模型的推理能力与图数据库的精确查询结合，既避免了模型幻觉，又让每条解释都能追溯到用户上传的网表数据。工具调用的参数和返回结果通常以 JSON 格式交换，模型根据结果决定是否需要进一步查询或直接回答。

验证修复是否生效

修改电路后，用户可以上传更新后的 .net 文件。两个版本分别在独立的 FalkorDB 图中检查，Python 随后比较发现结果和连接数据，展示哪些警告已清除、哪些仍然存在、是否出现新警告、哪些连线发生了变化。

这带来一个关键的界面挑战：电路图和状态必须描述同一版本。查看早期电路时应显示其原始发现，查看更新电路时应显示修订后的连接和结果。缺少这种一致性，即使比较逻辑正确，用户也会困惑。网站还提供一对可下载的示例文件，让用户无需先创建 KiCad 项目就能体验完整流程。

构建过程中的经验

图查询让连通性问题更容易表达——共享连接、引脚间路线、独立分组都很契合模型。另一个教训是关系要在正确的阶段准备：CircuitDoctor 在上传时创建电阻遍历链接，使路径查找保持为读操作。

视觉清晰度需要单独投入。高亮一条线只有在用户能跟随它并读取周围标签时才有用，电路视图和比较流程需要与检查逻辑同步打磨。最重要的经验是区分事实与假设：网表告诉应用哪些引脚相连，但不描述物理模块的所有内部细节，也不能证明模块通电后的行为。

明确工具边界

CircuitDoctor 是接线检查工具，不模拟电流、不测量电阻、不建模元件时序。通用连接探索使用上传的图，元件特定检查依赖已识别的部件和验证过的规格，目前支持 Arduino Uno R3、经典 Nano 和部分显示屏。连接追踪沿导线和支持的电阻进行，不会推断穿过每个元件的内部路径。

清除警告意味着对应检查在修订文件中不再发现该问题，但不保证完整物理电路一定能工作。开发者使用 Codex 和 Claude Code 等 AI 编程助手构建，并通过自动化测试和浏览器检查验证实现，文章本身也有 AI 辅助起草和编辑。

未来计划扩展元件覆盖范围，但这一版本聚焦于一个有用流程：上传电路、理解连接、检查问题、核对修订文件。对于 KiCad 用户，CircuitDoctor 提供了一个在通电前发现接线隐患的轻量方案。

电路仿真与接线检查的区别

电路仿真工具（如 SPICE）通过求解元件方程来预测电压、电流和时序行为，需要元件模型参数和激励信号；而接线检查仅验证网表中的连接关系是否符合设计规则或预期拓扑，不涉及数值计算。CircuitDoctor 明确不模拟电流、不测量电阻，意味着它不能发现诸如电阻值选错、电源功率不足或信号时序冲突等问题。它擅长的是结构性错误：电源与地短路、引脚接反、缺少供电网络等。将接线检查视为设计流程中的静态规则验证环节，而非仿真替代品，有助于用户正确理解“清除警告”的含义——它只表示连接逻辑在检查范围内无误，不保证电路功能正常。