KiCad AI Agent

基于大模型与多工具协作的智能电子元器件库生成系统：输入元件型号，自动搜索 Datasheet、AI 分析引脚/封装/NC 信息，并生成 KiCad 原理图符号、PCB 封装与 3D 模型。

项目简介

在电子设计中，为元器件手工绘制 KiCad 符号与封装是一项重复且易错的工作。本项目将这一过程自动化：系统接收元件型号（或本地 Datasheet PDF），通过在线搜索与 PDF 解析获取权威数据，调用大模型抽取结构化的引脚定义、封装参数与 NC（无连接）引脚信息，经质量评估后生成可直接使用的 KiCad 库文件，并支持基于对话的交互式修正。

系统以 LLM 意图识别驱动的 Agent 架构组织：大模型负责理解用户输入意图并路由，工具链按"搜索 → 下载 → 分析 → 评估 → 生成"的流水线协作，多轮对话状态在内存中保持，实现从型号到库文件的一站式生成。

功能特性

• 在线搜索：从 datasheets.com、alldatasheet.com 获取封装参数
• PDF 解析：自动下载 Datasheet PDF，提取引脚表、NC 引脚信息
• AI 分析：调用大模型提取结构化 JSON（引脚定义、封装变体、NC 映射）
• 文件生成：自动生成 .kicad_sym（符号）、.kicad_mod（封装）、.wrl（3D 模型）
• 质量评估：引脚-PDF 交叉验证、NC 引脚校验、数据源可信度评分，生成 Markdown 评估报告
• 交互修正：支持对话式修改引脚名、封装类型、NC 引脚等
• 双入口：同时提供 Web 界面（Gradio）与命令行两种使用方式

技术栈

• 语言：Python 3.10+
• 界面：Gradio 6.x（Web）、标准命令行（CLI）
• 大模型接口：OpenAI 兼容 API
• PDF 处理：pdfplumber（文本提取）、pytesseract + Pillow（可选 OCR）
• 配置管理：python-dotenv（.env）
• 输出格式：KiCad .kicad_sym / .kicad_mod / .wrl

环境要求

• Python 3.10 及以上
• 可访问的 OpenAI 兼容大模型 API

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置 API

API 配置可通过以下两种方式之一进行，配置项含义相同：

方式一：Web 界面填写

启动后打开 http://127.0.0.1:7860，点击 ⚙️ 设置，在 API Key 框内填入 key 并点「保存并应用」。

该方式将配置保存在当前运行进程的内存中，进程重启后配置失效，需重新填写（或改用方式二以持久化）。

方式二：.env 文件

在本地将其复制为 .env 并填入实际配置：

cp .env.example .env

API_KEY=your-api-key
BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-v4-flash
LLM_TIMEOUT_SECONDS=120
ANALYSIS_MAX_TOKENS=12000
USE_ANALYSIS_CACHE=1

两种方式的关系：

• Web 界面填写的值会覆盖内存中的配置；进程重启后若未使用 .env，配置恢复为空。
• 命令行入口（main.py）仅读取 .env，无法获取 Web 界面内填写的值。
• .env 中的配置在进程重启后依然保留。

3. 运行

Web 界面：

python app.py

浏览器打开 http://127.0.0.1:7860，输入型号（如 PIC16C774）即可生成。

命令行：

python main.py -m PIC16C774              # 按型号生成
python main.py path/to/your-datasheet.pdf   # 按本地 PDF 生成（提供你自己的 datasheet）
python main.py -m PIC16C774 -i           # 多轮对话模式

API 连通性检查：

python check_api.py

项目结构

├── app.py                  # Gradio Web 界面入口
├── main.py                 # 命令行入口
├── agent_core.py           # Agent 核心：意图识别 + 路由 + 流水线
├── check_api.py            # API 连通性检查工具
├── config/
│   └── settings.py         # 全局配置（API、模型参数、System Prompt）
├── tools/
│   ├── search_tools.py     # 在线搜索 + PDF 下载
│   ├── analyze_tools.py    # AI 分析 + 缓存 + NC 后处理
│   ├── assess_tools.py     # 质量评估
│   └── generate_tools.py   # KiCad 文件生成
├── models/
│   ├── symbol_generator.py     # 原理图符号生成
│   ├── footprint_generator.py  # PCB 封装生成
│   └── model3d_generator.py    # 3D 模型生成
├── utils/
│   ├── llm_client.py       # LLM 客户端（重试、限流、流式）
│   ├── part_search.py      # 元件搜索（datasheets.com / alldatasheet.com）
│   ├── pdf_parser.py       # PDF 文本提取
│   ├── assessment.py       # 评估引擎（交叉验证、NC 校验）
│   ├── report_generator.py # Markdown 报告生成
│   ├── json_parser.py      # JSON 容错解析
│   ├── dialogue_engine.py  # 多轮对话引擎
│   ├── image_ocr.py        # 图片 OCR（可选）
│   └── logger.py           # 日志配置
├── data/                   # 缓存、下载的 PDF
├── output/                 # 生成的 KiCad 文件
├── logs/                   # 运行日志
└── .env                    # API 配置（不入库）

系统架构（Agent）

系统是一个基于 LLM 意图识别的多工具协作 Agent，具备「感知 → 推理 → 行动 → 记忆」的闭环。核心实现位于 agent_core.py 的 KiCadAgent 类。

Agent 核心要素

要素	实现	说明
感知（Perception）	handle(user_input)	接收用户自然语言输入作为 Agent 入口
推理（Reasoning）	_classify_intent()	调用 LLM 将输入归类为 generate / modify / ask / new_part / chat，并带规则兜底 _fallback_intent()
行动（Action / Tools）	_do_search_part / _do_download_datasheet / _do_ai_analyze / _do_assess / _do_generate	搜索、下载 PDF、AI 分析、质量评估、文件生成五个工具
记忆（Memory）	KiCadAgent 实例状态 + 磁盘存档	在单次运行会话内跨多轮保持上下文；重启后若输入提及的型号在 output/{型号}/_final_data.json 存在，则仅回填结构化数据实现轻量恢复（不加载聊天历史）
编排（Orchestration）	handle() 主循环	意图识别 → 路由 → 执行；批量输入自动拆分为多个型号顺序处理

架构范式

属于意图路由式 Agent（Intent Router Agent）：LLM 负责"理解意图"，工具调度走一条相对固定的流水线（搜索 → 下载 → 分析 → 评估 → 生成，其中搜索与下载并行执行）。

┌─────────────────────────────────────────────────────────────┐
│                       KiCadAgent (agent_core.py)             │
│                                                               │
│   用户输入 ──▶ _classify_intent()  ──▶ 意图路由                │
│   (感知)       (LLM 意图识别)      (generate/modify/ask/...)  │
│                    │                            │            │
│                    ▼                            ▼            │
│            ┌─────────────── 多轮记忆状态 ───────────────┐    │
│            │ _part_number / _collected_data / _has_data │    │
│            └────────────────────────────────────────────┘    │
│                    │                            │            │
│        generate/new_part                  modify / ask / chat │
│            ▼                            ▼                     │
│   _run_pipeline()  ── 并行 ──▶ 搜索 + 下载 PDF                │
│       │                          │                           │
│       ▼                          ▼                           │
│   _do_ai_analyze (LLM) ──▶ _do_assess ──▶ _do_generate      │
│   (工具调用: Action)        (质量评估)      (生成 KiCad 文件)  │
└─────────────────────────────────────────────────────────────┘

交互能力

• 生成：输入型号（如 PIC16C774）自动跑完整流水线
• 批量：一句话含多个型号时自动逐个生成
• 修正：对话式修改引脚名、封装类型、NC 引脚（直接改写内存数据，提示「重新生成」更新文件）
• 询问：基于已生成数据摘要用 LLM 流式回答元件相关问题
• 切换：输入新型号自动重置并启动新任务

工作流程

用户输入型号
    │
    ├─ 搜索封装信息（datasheets.com + alldatasheet.com）
    ├─ 下载 Datasheet PDF
    │        ↕ 并行执行
    ├─ AI 分析（LLM 提取引脚/封装/NC → JSON）
    │   ├─ PDF 文本精简（保留引脚/封装关键页）
    │   ├─ NC 引脚 PDF 后处理（从 NC 表修正 AI 输出）
    │   └─ 结果缓存（含 prompt 版本校验）
    ├─ 质量评估（引脚-PDF 交叉验证 + NC 校验 + 数据源评分）
    └─ 生成文件（符号 + 封装 + 3D 模型 + 评估报告）

输出文件

所有产物按元件型号分目录存放于 output/{型号}/ 下：

文件	说明
output/{型号}/{型号}.kicad_sym	KiCad 原理图符号
output/{型号}/{型号}_{封装}.kicad_mod	KiCad PCB 封装（每个封装变体一个）
output/{型号}/{型号}_{封装}.wrl	3D 模型
output/{型号}/{型号}_ai_response.json	AI 原始返回 + 解析数据
output/{型号}/{型号}_评估报告.md	质量评估报告（含复核项）
output/{型号}/{型号}_final_data.json	最终结构化数据
output/{型号}/{型号}_dialogue_history.json	多轮对话历史

技术说明

• LLM 调用：通过 OpenAI 兼容接口，支持模型回退、指数退避重试、流式输出
• 缓存机制：分析结果按型号缓存，prompt 变更后自动失效
• NC 引脚处理：区分"封装多出的 NC 焊盘"与"小封装缺失的符号引脚"两种场景
• JSON 截断修复：LLM 输出被 max_tokens 截断时自动补全闭合括号
• 上下文持久化（轻量恢复）：每次生成或修改成功后，结构化数据写入 output/{型号}/_final_data.json；重启服务后，若用户再次提及该型号，Agent 回填该结构化数据（不重新灌入聊天历史），使 modify / ask 等后续指令仍可继续，避免上下文膨胀

支持的封装类型

当前系统面向标准通孔 / 表面贴装封装的元件库生成，已在实测中覆盖以下典型封装：

• 通孔类：DIP / PDIP
• 表贴类：SOP / SOIC / QFP / TQFP / QFN
• 多封装变体芯片（如同一型号同时提供 PDIP-40、SOIC-28、TQFP-44）可一次性生成全部封装变体

对于 BGA、超细间距 QFN、非标准 / 定制封装等复杂场景，系统可基于 Datasheet 解析生成，但对引脚密度极高或缺少标准引脚图的元件，质量评估会标注 needs_review 交由人工复核。对该类元件的专项支持正在持续扩展中。