Datasheet 生成 KiCad Symbol

Datasheet 生成 KiCad Symbol

项目地址：https://github.com/LNfromNorth/DatasheetReader

最近我在整理一个自己的小项目，叫 DatasheetReader。它做的事情很简单：尽量把芯片 datasheet 里那些又长又密的引脚表、封装信息和功能描述，转换成可以在 KiCad 里继续检查和使用的 symbol 初稿。

我不是想做一个“完全替代工程师”的工具。相反，我更想解决的是一个很具体、也很折磨人的问题：画 symbol 这件事太机械了，但一旦机械劳动太多，人就很容易犯错。

我遇到的困境

做硬件设计时，从 datasheet 画 symbol 经常是这样：

先打开 PDF，找到 pin assignment，再找到 pin description，再确认 package drawing，然后开始一行一行搬引脚。电源脚、复位脚、时钟脚、USB、SPI、GPIO、模拟输入，信息散在不同页面里。搬完之后还要核对 pin number、pin name、pin type、封装和 footprint。

几十个引脚还能忍，到了上百个引脚就很痛苦。更麻烦的是，很多 datasheet 并不是“一个 PDF 对应一个器件”。

比如 STM32F40x 这一类 family datasheet，同一份 PDF 里可能同时包含 WLCSP90、LQFP64、LQFP100、LQFP144、LQFP176、UFBGA 等多个封装。再比如 VL817 这类 USB Hub 芯片，同一份文档里也可能包含不同型号和不同 QFN 封装。

这时候如果工具只假设“一份 datasheet 只有一个目标器件”，就会出问题：它可能把多个封装的 pinout 混在一起，也可能抽取了一个型号的引脚，却拿另一个型号的封装去匹配。表面上看生成了 symbol，实际上后面审核会非常难受。

这就是我开始做 DatasheetReader 的原因。

这个项目想做什么

DatasheetReader 的目标不是直接给出一个“你可以无脑相信”的最终库，而是把 datasheet 处理成一组可检查、可追溯的中间结果。

它大概会做几件事：

1. 先从 datasheet 中识别可能存在的目标器件和封装。
2. 根据选定目标，筛出真正相关的证据页面。
3. 从证据页中抽取引脚、封装、pin type 和功能描述。
4. 生成 KiPart CSV 和 KiCad symbol。
5. 匹配可能合适的 KiCad footprint。
6. 输出 review report，让我知道哪些地方通过了，哪些地方还需要人工确认。

我比较在意的一点是：它不是只吐一个.kicad_sym文件就结束。它会保留part.json、pins.csv、pins.kipart.csv、footprint 候选、证据页和审查报告。这样我可以回头检查每个结论来自哪里，而不是面对一个黑盒结果猜它到底怎么来的。

多目标 datasheet 是核心问题

我用 STM32F40x datasheet 做过一次测试。项目能先识别出这一份 PDF 里有多个可选目标，例如：

这个步骤对我来说非常关键。因为在真实工作里，我并不是“要生成 STM32F40x 的某个抽象 symbol”，而是要生成一个明确目标，比如STM32F405xx/STM32F407xx + LQFP64。

一旦目标明确，后面的抽取才有意义。否则看起来很智能，实际上只是把 datasheet 里的多个世界搅在一起。

VL817 的测试也类似。它能识别出类似VL817-Q7 QFN-76和VL817-Q5 QFN-56这样的候选目标。对于这种一个系列多个封装的文档，先选目标再生成 symbol，比直接让模型“读完整本 PDF 然后生成一个结果”可靠得多。

实际生成效果

我拿 STM32F40x 的 LQFP64 做了一次完整生成。结果里抽取出了 64 个引脚，识别到了 LQFP、64 pins、0.5 mm pitch、10 x 10 mm 这些封装信息，并且选出了 3 页关键证据：pin assignment、pinout diagram 和 mechanical drawing。

自动审查报告里，几个关键项都通过了：

PASS Extracted 64 pins PASS Pin numbers are unique PASS Selected 3 evidence pages PASS Generated pins.kipart.csv PASS Generated symbol.kicad_sym PASS KiCad CLI exported primary symbol SVG PASS Found 10 footprint candidates

footprint 匹配的第一候选是：

Package_QFP:LQFP-64_10x10mm_P0.5mm

这个结果对我来说已经很有价值。它不代表我可以完全不检查，但它把原来最枯燥、最容易漏项的整理工作，压缩成了“检查结构化结果是否合理”。

VL817 的测试结果也比较有意思。它抽取出了 77 个 pin 条目，识别到了 QFN76 和 QFN56 两类封装信息，footprint 候选里也能找到类似下面这样的高匹配项：

Package_DFN_QFN:QFN-76-1EP_9x9mm_P0.4mm_EP3.8x3.8mm

这说明它不只是为 MCU 写死的流程。只要 datasheet 中有相对明确的 pin table、pin description 或 package drawing，它就可以尝试把这些内容整理成统一的中间表示，再交给 KiCad 后端处理。

一些输出长什么样

为了让这个项目看起来不只是“概念上可行”，我也把本地跑出来的一些结果放在这里。它的输出不是只有最后那个 symbol 文件，而是一整包可以慢慢检查的材料。

下面是 STM32F40x LQFP64 的流水线日志摘要。我比较喜欢这种日志，因为它不是只告诉我“成功了”，而是把每一步到底做了什么、用了什么证据、产出了什么文件都记下来。

start local datasheetreader ingest ai PyMuPDF + LLM filter extract ai deepseek:deepseek-chat symbol-decision ai AI decision symbol local kicad footprint local kicad review local kicad

其中ingest阶段会把 PDF 页面先索引出来，再按角色分类。STM32F40x 这份 datasheet 一共索引了 206 页，里面能看到很多候选页面其实都和封装、pinout、机械尺寸有关：

pages_indexed: 206 role_counts: pin_description: 30 pinout_diagram: 61 package_reference: 61 mechanical_drawing: 63 land_pattern: 4

这张是被挑出来的 STM32F40x LQFP64 证据页之一。对我来说，保留这种 evidence 很重要，因为后面如果 symbol 有疑问，我可以直接回到原始 datasheet 页面核对。

生成出来的 KiCad symbol 也会导出成 SVG，方便不用打开 KiCad 也能快速看一眼大概效果。

审查报告会把一些我最关心的点直接列出来。比如 STM32F40x LQFP64 这次，pin 数、pin 编号唯一性、symbol 生成、SVG 导出和 footprint 候选都通过了：

PASS Extracted 64 pins PASS Pin numbers are unique PASS Selected 3 evidence pages PASS Generated pins.kipart.csv PASS Generated symbol.kicad_sym PASS KiCad CLI exported primary symbol SVG PASS KiCad CLI exported symbol_split symbol SVG PASS Found 10 footprint candidates

VL817-Q5 的输出也能看到同样的结构。它会先保存 datasheet 里的证据页面，再生成 symbol 预览：

这里我最在意的不是它把图片做得多漂亮，而是它能让我从“最终 symbol”一路反查到“使用了哪些 datasheet 页面”和“审查过程通过了哪些检查”。这比只给一个生成结果让我放心很多。

我觉得它最有用的地方

第一个优势是减少重复劳动。

手工画 symbol 最痛苦的部分，并不是“我不会画”，而是我明知道自己只是在搬表格，却还必须高度集中注意力。DatasheetReader 能把这部分工作先做成草稿，我再检查草稿，这个体验完全不同。

第二个优势是结果可追溯。

我不喜欢那种只输出一个最终文件的 AI 工具。因为硬件库文件一旦错了，后果可能很麻烦。所以这个项目会尽量保留证据页、结构化 JSON、CSV、review report 和 footprint 匹配分数。它生成了什么，我可以看；它为什么这么生成，我也有线索可以追。

第三个优势是能处理多目标文档。

很多真实 datasheet 都不是教科书式的单一器件文档。一个系列、多个型号、多种封装、共享引脚描述，这些情况非常常见。这个项目现在把“先识别 target，再围绕 target 生成”的流程放在了前面，至少不会一开始就走错方向。

第四个优势是后端比较容易扩展。

目前它主要面向 KiCad，会生成 KiPart CSV、KiCad symbol，并做 footprint 候选匹配。但内部并不是把所有逻辑都揉在一起，而是分成了模型 provider、PDF 证据筛选、中间 IR、EDA backend 等部分。以后如果要接新的模型，或者支持别的 EDA 输出，理论上不需要推翻整个流程。