14 KiB
DeepSeek → 原生 KiCad 生成服务
本目录包含网页任务 API、DeepSeek 调用器、器件库检索、原理图生成、布局、Freerouting 布线、KiCad 检查和交付打包。新任务不再依赖嘉立创 EDA、Codex CLI、浏览器操作或私有 deliver_pack 源码。前端启动方式见根目录 PCB-SERVICE.md。
运行环境
目前在 Ubuntu 24.04、Python 3.12、KiCad 10.0.7 上验收。自建完整后台需要:
- Python 3.11+、venv/pip;API 依赖固定在
api/requirements.lock。 - KiCad 10.x CLI、同版本可
import pcbnew的系统 Python、标准 symbols/footprints/packages3d 库。Ubuntu 包名为kicad、kicad-symbols、kicad-footprints、kicad-packages3d。升级 KiCad 后应先跑原生集成测试。 - Java 17+、Xvfb。路由器使用独立虚拟显示,不依赖人工登录桌面。Ubuntu 可安装
openjdk-21-jre-headless xvfb。 python3-venv;上传 PDF 需poppler-utils中的 pdftotext。- DeepSeek API 凭据和外网连接;首次下载依赖及固定版本布线器也需要外网。
仅开发网页需要 Node.js 22+、npm、Git、Bash,以及可访问的后台;不需要在每位开发者电脑上安装 KiCad 或提供模型 key。
启动完整后台
cd backend
cp .env.example .env.local
# 在被忽略的 .env.local 中填入自己的 DEEPSEEK_API_KEY;禁止提交真实凭据。
./start.sh
启动脚本创建虚拟环境、按锁文件安装依赖、下载并核对 Freerouting SHA-256,默认监听 127.0.0.1:8000。由反向代理或仓库前端代理访问;此 API 目前是内部共享工作台,并非具备用户隔离的公网多租户服务。长驻部署应由 systemd 等进程管理器运行。
原服务器可继续设置 AI_PCB_CODEX_HOME=/home/wpz/.config/ai-pcb-codex,只读取其中原有 DeepSeek provider 凭据,不启动 Codex。显式 DEEPSEEK_API_KEY 优先。密钥不返回浏览器。默认运行数据在 ~/.local/share/vibemake-pcb,也可用 AI_PCB_API_DATA 指定仓库外目录。
模型默认 deepseek-flash,通过 DeepSeek /responses 直接调用。需求与方案、器件选型、电路生成和修复统一使用 reasoning.effort=max;单次输出上限为 327680 tokens(含推理),调用记录中保存实际档位。缓存包含思考强度和输出预算,修改配置后不会沿用之前低强度的缓存。规划与电路数据均有结构约束、真实库引脚校验和有限自动修复;不让模型临时编写执行脚本。调用记录和任务历史放在运行目录,不能纳入 Git。
高强度推理默认每次请求允许 30 分钟(AI_PCB_MODEL_TIMEOUT=1800,可调至最多 2 小时),超时及临时网络错误自动重试一次,每次尝试重新计时;不会自动降低 max 推理强度。连续 5 分钟无网络数据会按连接超时重试(AI_PCB_MODEL_IDLE_TIMEOUT=300),持续心跳不会触发此空闲限制。进入设计后的总预算默认 3 小时(AI_PCB_TASK_SECONDS=10800,最多 24 小时);外层命令保护默认 6 小时(AI_PCB_COMMAND_TIMEOUT=21600,最多 48 小时)。扩大预算时外层命令时限应覆盖方案生成及设计预算。这些是最长等待预算,不是每单固定耗时。模型失败尝试的类型、时长与预算写入任务 calls 目录;只对临时错误做有限重试,预算耗尽仍会明确结束。
可配置 KICAD_CLI、KICAD_PYTHON、KICAD_SYMBOL_DIR、KICAD_FOOTPRINT_DIR、KICAD_3DMODEL_DIR、AI_PCB_FREEROUTING_JAR。后三类资源路径应与 KiCad 实际安装匹配。非 Linux 平台的后台需要另外适配系统 Python 和虚拟显示,当前完整生成验收平台为 Linux;浏览器客户端不受此限制。
生成、检查和审核
需求补充和方案确认发生在设计开始前。进入设计后,原理图修复、布局重试和布线均由服务器在时间/次数预算内自动执行,不进入等待用户调试的操作态。断开浏览器不取消任务;服务重启会恢复未完成检查点,恢复预算耗尽时明确结束并保存原因。
DeepSeek 提供器件、引脚网络和功能意图;程序从安装库解析真实引脚和封装,写出原生 .kicad_pro/.kicad_sch/.kicad_pcb。确定性布局使用真实本体/禁布边界,USB 开口朝板外,GPIO 排针分布在边缘,去耦和晶振靠近对应引脚。固定尺寸不会被静默扩大。开发板默认引出烧录接口和可用 GPIO,并核对 UART/SPI/I2C 引脚复用;需要 CAN、485、EtherCAT 的物理接口必须包含相应收发器/控制器,不能用裸排针冒充。
PCB 通过 DSN/SES 交给固定版本 Freerouting,在有限预算内选择原生 DRC 更好的候选。电源线宽会在细间距器件处收窄,具体实际线宽记录在检查报告;这些是原型规则,不能被当成额定载流能力保证。
连接器机械门禁独立于电气 DRC:支持的卧式 XT60PW-M 根据真实封装 -Y 插合轴在左边缘旋转 90°,插合面贴到板外,并保留 20mm 宽、25mm 深的插头操作通道;这些净空值是保守设计假设,不是厂家公差。立式 XT30UPB-F 沿 +Z 插合,保留本体周围 1mm 的操作净空。任何其他器件或插头包络都不能占用这些区域;固定板框放不下时明确失败,不允许挤压净空或静默扩板。未知侧插连接器画像阻止制造放行。
检查从实际保存、重开的 PCB 读取坐标和旋转角,在导出及审核时分别执行,不能凭模型文字承诺或电气 DRC 通过替代。缺失连接器 3D 模型会记录在机械报告中,焊盘/丝印预览不能充当完整 3D 碰撞验收。支持的 AMASS 封装极性以实际厂家图与封装标记为准,pin 1 为负、pin 2 为正,不能按通用连接器符号猜测。
交付门禁包括:原生 ERC、原理图与 PCB 字段/引脚网络一致性、原生 DRC(含未连接)、真实铜区重建、保存重开后的再次检查、布局和走线检查。不存在、未确认或解析失败的检查均不能当作通过。完整保存 JSON 报告、警告和排除项。
- delivery_ready:完整检查通过,原生工程、Gerber、钻孔、BOM 和报告已预先打包。用户确认当前摘要后立即开放下载,不在点击审核时重新生成。
- draft_ready / failed:自动预算内未完成;提供检查原因和可用草稿,不能用审核按钮绕过制造门禁。
- SHA-256 绑定审核修订与文件,拒绝旧摘要或被篡改的文件。导入网页编辑器会创建单独的未验证副本,修改后需要重新检查。
软件验收只能证明已执行检查的结果,不能证明电气功能、热、EMC、高速信号质量和实际器件可采购。复杂开发板仍可能超过自动生成能力,需要后续针对更多真实板型扩展规则和测试。
独立检查已有工程
cd backend
/usr/bin/python3 -m kicad_backend doctor
/usr/bin/python3 -m kicad_backend process \
--project /absolute/input/design.kicad_pro \
--output /absolute/output/new-run
输入应包含同名原理图和 PCB 以及项目本地库。输入保持原样,输出必须是全新目录;拒绝符号链接,不打包 .kicad_prl、历史和密钥。退出码 0 为全部检查通过,2 为失败或运行错误。该独立 worker 仅使用标准库,不需要模型凭据。
测试
cd backend
PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -v
KICAD_NATIVE_TESTS=1 PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -v
# 显式运行真实 DeepSeek/API 验收,会产生模型费用;输出放仓库外:
.venv/bin/python tests/acceptance_live.py --api http://127.0.0.1:8000 \
--description '30x30mm 小电流一入两出分电板,2pin排针,1正2负,无其他器件' \
--output /absolute/private/acceptance-run
原生负例包括删掉走线、改错焊盘网络,必须被拦截;正确工程必须导出制造文件。API 测试覆盖摘要审核、排队隔离、状态粘性、幂等与非法请求。真实验收脚本另外验证审核前无制造文件、旧摘要拒绝、审核后 ZIP 内容及下载摘要。测试数据均不属于可提交源码。
KiCad 10 的系统 Python SWIG 绑定用于确定性 PCB 操作;检查和导出由 CLI 执行。10.0.7 绑定有 PROPERTY_ENUM 启动日志,原生日志保留。升级到 KiCad 11 前需替换/验证此兼容层。第三方路由器的来源与校验见 THIRD-PARTY.md。
元器件三维预览
生成 PCB 时会解析封装的真实 3D 模型,并将可用的 STEP/WRL 文件复制到工程 models/,改用 ${KIPRJMOD} 相对路径,随原生工程和下载包交付。服务器标准库缺失的 HRO USB-C、AMASS XT60PW-M 与 XT30UPB-F 使用仓库内固定版本、校验摘要的真实 STEP 模型;来源、许可与安装变换见 assets/3dmodels/MODEL-SOURCES.md。不会把不匹配型号的模型套用到器件上。
检查记录包含 model_coverage:总器件数、有模型的器件数及缺失清单;缺失模型会进入成果提示。三维外观帮助检查结构,不取代连接器插拔空间检查和电气 DRC。补充历史任务的三维预览不改写冻结工程,也不解除原有制造限制。
原理图局部修复与功能保护
初次生成完整电路后,修复阶段只接收 CIRCUIT_PATCH:逐引脚声明修改前网络、目标网络及电气理由。ERC 的类型、严重程度、具体器件/引脚条目、引脚名称/电气类型及当前网络会完整传给模型;编译器电源标记另行标识。只有报错涉及的真实引脚允许修改,原生网表与目标电路不一致不能通过改目标电路掩盖。
服务器锁定器件清单、数值、无关引脚、原有网络名称/类型、外部供电声明和接口复用表。补丁没有删器件或把已连接引脚改成 NC 的操作,禁止借用无关电阻、隔离电源输出凑 ERC 通过,并检查原有通信/烧录映射(含串联电阻通路)是否仍连通。局部补丁不能任意跨电源网络改接供电引脚,必须核对真实电气约束,不能猜测完成。
每轮重新执行完整语义检查及适用的原生 ERC/网表核对。已知错误须减少且不能引入新错误;初次通过语义检查后才能观测到的 ERC 问题作为下一检查阶段处理。被拒绝的补丁不替换上一版电路,具体拒绝证据会传给下一轮。初次生成加两次修复的预算保持不变;需要改 BOM/数值或缺少器件专用依据时保留原电路和明确未解决原因,不降低检查门槛。任务工作目录记录 repair-*-context.json、repair-*-decision.json 和 repair-baseline.json,不纳入仓库。
流程资料下载
左侧 PCB 生成流程提供全部资料 ZIP、流程说明 Markdown、完整执行记录 CSV。需求尚未提交时可下载当前填写的需求;已有任务无论生成中、失败或完成均可导出已有资料的快照。执行记录从服务端完整读取,不受页面最近 16 条显示限制。ZIP 包含用户需求/补充、方案、真实器件选型、诊断与检查/修复记录、模型调用统计、参考附件及已开放下载的工程成果;不会绕过制造包审核、路径限制或文件摘要检查,不包含服务凭据。CSV 使用 UTF-8 BOM 并防止单元格公式注入。
只读下载接口为 GET /api/v1/tasks/{task_id}/workflow-export?format=zip|md|json|csv,沿用现有会话认证。全部资料限制 256MiB,超出时提示分项下载,不默默截断。导出不会启动绘板、调用模型、改变任务状态或修改冻结成果。
需求输入框支持原生文字粘贴及剪贴板截图/图片粘贴。图片通过现有附件上传接口发送,在需求中作为附件引用;上传期间不能开始分析或切换任务。使用粘贴事件读取剪贴板文件,不依赖仅 HTTPS 可用的主动剪贴板读取接口。
AI 工作台通过 data-native-text-shortcuts 声明浏览器文字快捷键归属:全局 CAD 快捷键捕获器对该区域及其文字选区让行,复制事件优先写入选中文字,避免底层原理图/PCB 复制处理覆盖内容。支持 Ctrl+C、macOS 的 Cmd+C 及 Ctrl+C;局域网 HTTP 使用用户触发的原生 copy 事件,不依赖主动剪贴板权限。
器件检索与实际预检
kicad_backend/part_catalog.json 以及常用器件示例仅用于检索提示和候选排序,不是允许使用的型号清单。未登记、没有别名、没有同名专用符号、登记表缺失或失效均不是拒绝器件的理由;新增型号不需要先改这份文件。实际库检索独立运行,提示不能隐藏实际可用候选。
真实型号优先精确检索,也允许采用功能、引脚与实物封装相符的通用符号或系列符号。完整厂商型号及订购后缀保留在 BOM 中,不自动替换型号、合并电压/存储差异或假定引脚功能相同。选型校验范围记录在 selection_validation.scope,符号/焊盘匹配不等于已经确认所有厂商变体特性。
方案展示前仍核对实际符号引脚、封装焊盘、真实封装兼容性、源文件摘要,并由 KiCad 加载全部封装。缺少实际库文件、编号不匹配、功能/电气证据冲突等具体问题仍须纠正。模型只从本次检索和校验生成的候选对中消歧;这个动态候选集不是静态型号白名单。选型纠正仅修改报错器件的符号/封装查询,器件型号、数量、数值、功能、接口和板框保持原意。
选型证据保存在 project/work/selection/,可以随流程资料下载。符号及封装索引保持缓存以减少重复扫描;电路语义、原生 ERC/DRC、机械检查和审核放行要求继续执行。选型失败时保留候选 BOM 并按器件记录具体原因,不能用“未在登记表”代替诊断。