Files
likang 3cbf7bda9a
CI / typecheck + test + build (push) Has been cancelled
Merge updated AI PCB session workflow into main
Integrate origin/main, including feature/new-ai-gate, with the saved local PCB work. Preserve project covers, packaging, platform authentication, macOS KiCad support and the AI disable switch. Mount only the new session workspace, align proxy defaults with port 8003, and resolve cross-platform and test integration issues.
2026-11-12 18:47:28 +08:00
..
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00
2026-11-10 19:04:27 +08:00

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 并按器件记录具体原因,不能用“未在登记表”代替诊断。