Files
vibemake-pcb-studio/backend/README.md
T
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

18 KiB
Raw Blame History

auto_pcb_2 运行说明

当前工作区默认使用 Codex GPT-6.1 Sol。本站入口、15182/8003 端口、独立数据目录、强制方案审核和 STEP 导出,以 PCB-SERVICE.md 为准。

下面保留迁入后端的历史说明,涉及旧工作区路径、DeepSeek 默认值及 15180/8000 端口的段落不适用于本次部署。


DeepSeek → 嘉立创 EDA Pro 生成服务

启动时先用只读 doctor 检查 EDA。Linux 显示/授权失效时,从当前用户的 systemd 桌面环境恢复 DISPLAY 和本人拥有的 XAUTHORITY 后重试检查,不使用固定的临时授权文件名。如果桥接未运行,自动启动嘉立创应用并等待连接,不创建项目或绘板任务。无可用桌面会话时给出明确错误;本机制不会自行创建虚拟桌面。编辑器启动日志在运行数据目录的 logs/eda-startup.log。普通 EDA 写命令不会因输出解析失败自动重放。

新任务默认使用嘉立创 EDA Pro(AI_PCB_EDA_BACKEND=easyeda)。默认 DeepSeek 直接调用现有服务端凭据,保留 max 推理、327680 输出 token 预算、每次 1800 秒超时及一次有界重试,DeepSeek 模式不运行 Codex CLI;Codex 模式见下文。嘉立创在线库负责真实器件搜索;不存在“必须预先登记少量型号才能使用”的门槛。

启动与依赖

后台主机需要 Python 3.11+(含 venv)、嘉立创 EDA Pro 桌面版及可用的 CLI 桥接、Java 17+、Blender;Linux 需要可用的图形会话或虚拟显示,并向服务提供正确的 DISPLAY。当前服务器已连接的版本为 4.1.78.34f5b8d9。其他版本需核对 CLI/API 兼容性。需要读取 PDF 附件时安装 Poppler(pdftotext);文本提取有 12 页/16000 字符上限,图像最多 3 张,完整附件仍保留供下载。

cd backend
cp .env.example .env.local
# 在 .env.local 配置自己的 DEEPSEEK_API_KEY,或引用仓库外的 AI_PCB_CODEX_HOME。
# Linux 按实际会话设置 DISPLAY,AI_PCB_EDA_EXECUTABLE 可指定嘉立创程序路径。
./start.sh

启动自动安装 api/requirements.lock 的 Python 依赖,并下载和校验 Freerouting 到忽略的 .cache/。启动前检查嘉立创连接、Java 和 Blender。只开发网站时只需 Node/npm 和可达后台,根目录运行 ./start.sh,无需本机安装 EDA。

后台可单独只读检查连接(Linux 示例):

DISPLAY=:1 lceda-pro doctor --no-sandbox

嘉立创客户端应在后台主机持续运行并能访问在线器件库。浏览器关闭或访问端断网不取消后台任务;服务器及客户端仍需运行和联网。AI_PCB_EDA_EXTRA_ARGS 默认为 --no-sandbox,按部署环境可覆盖。

可配置 KICAD_CLI、KICAD_PYTHON、KICAD_SYMBOL_DIR、KICAD_FOOTPRINT_DIR、KICAD_3DMODEL_DIR、AI_PCB_FREEROUTING_JAR。资源路径应与 KiCad 实际安装匹配。当前完整生成验收平台为 Linux;浏览器客户端不受此限制。

macOS 本地启动旧版 KiCad 后台

安装 KiCad 10、Python 3.11+ 和 Java 17+ 后,在 backend/.env.local 中配置 DeepSeek 密钥,并设置 KiCad 应用内的 CLI、Python 和库目录:

AI_PCB_EDA_BACKEND=kicad
AI_PCB_API_HOST=127.0.0.1
AI_PCB_API_PORT=8000
KICAD_CLI=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli
KICAD_PYTHON=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3
KICAD_SYMBOL_DIR=/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols
KICAD_FOOTPRINT_DIR=/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints
KICAD_3DMODEL_DIR=/Applications/KiCad/KiCad.app/Contents/SharedSupport/3dmodels

在已登录的 macOS 桌面会话中运行 ./start.sh。布线器使用 Java 原生桌面,不要求 Xvfb;Linux 仍使用隔离的 Xvfb 显示。旧版 API 默认监听 http://127.0.0.1:8000;它不兼容当前持久化会话入口,不能用来替代 8003 上的新服务。macOS 已验证 KiCad 环境检查与小型板的 DSN/SES 布线,完整设计生成仍需单独验收。

流程与数据

需求确认后,模型搜索真实器件并提出有界的原理图器件操作;服务器检查 API 签名、脚本语法与目标身份,再交给持久化工位执行。连线、PCB 搬运、布局、Freerouting 布线、铺铜、保存重开、网络比对和导出由固定代码负责。失败先对账并自动恢复,有界重试耗尽后明确失败,不要求用户 SSH 排障,也不会把失败检查改成通过。

嘉立创源码和执行规范均在 easyeda_backend/,不依赖服务器旧 deliver_pack。默认参考目录为空,可用 AI_PCB_REFERENCE_ROOT 指向已授权的外部参考库;空目录不阻塞在线器件搜索。参考索引的用途限制、许可与允许入口仍生效,未随代码收集或上传历史工程。

成果包含嘉立创原生 .epro2、网页兼容 .epro、原理图/PCB 预览、BOM、真实元器件 OBJ 与渲染、检查记录。冻结制造包只有完整校验通过后才进入审核放行;未通过的草稿明确显示问题,允许下载已有草稿资料。网页的编辑副本仍由原有 KiCad 浏览器编辑器处理 .epro 导入;后端生成引擎与网页编辑器是不同组件。

任务持久化 eda_engine:新任务走 EasyEDA,历史 KiCad 任务继续读取各自引擎,不改写冻结成果。重启只恢复有已提交操作证据的未结束任务,不批量重跑历史失败任务。历史 KiCad 的主动继续/重新处理仍需要对应 KiCad 依赖;历史文件下载不需要 KiCad 程序。KiCad 工具说明存于 kicad_backend/README.md。

运行数据默认在仓库外 ~/.local/share/vibemake-pcb,可通过 AI_PCB_API_DATA 覆盖。DeepSeek key 放环境变量或仓库外私有配置;.env.local、数据库、工位日志、模型响应和任务历史不得提交。网页流程资料导出、复制/粘贴、原有审核摘要与权限校验继续保留。

不调用真实模型的验证

PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -p 'test_easyeda_dispatch.py' -v

这些检查使用临时目录和替代模型,不发起真实绘板任务或模型请求。第三方依赖和来源见 THIRD-PARTY.md 与 easyeda_backend/SOURCES_AND_SCOPE.md。

仅服务端切换 DeepSeek / Codex

网页没有模型选择器,公开命令拒绝 provider、model、model_binding 等覆盖字段。需求文本不能修改服务器模型配置。两种模型共用嘉立创执行流程、PCB 规范、检查与审核门禁。

  • DeepSeek:原有 deepseek-flash,max 推理、327680 输出预算、现有凭据保持独立。
  • Codex:Codex app-server,固定 gpt-6.1-sol、medium 推理。角色输出为结构化设计数据;关闭命令、网页、插件和子代理工具,使用只读沙箱及 never 审批策略。模型不直接修改 EDA 或等待网页用户批准工具。

在后台主机执行:

cd backend
.venv/bin/python providerctl.py status
.venv/bin/python providerctl.py doctor codex
.venv/bin/python providerctl.py use codex
.venv/bin/python providerctl.py use deepseek

use 检查所选配置后原子写入仓库外的 model-provider.json,立即影响后续新任务,无需重启 API。已创建任务把 provider/model/effort 保存在私有 task.json.model_binding,从方案生成到修复一直使用同一配置;旧任务无此字段时继续使用 DeepSeek。不会自动跨提供商降级,也不会重跑失败历史。Codex 和 DeepSeek 缓存包含模型标识,互不冒用输出。

当前个人研发验证

显式设置 AI_PCB_CODEX_AUTH=chatgpt,并将 AI_PCB_CODEX_LOGIN_HOME 指向后台主机本人已登录的 Codex 目录(通常 ~/.codex)。仅用于个人本地/内部研发验证;不复制登录凭据进仓库、不读取 DeepSeek 的专用 profile。CLI 缺失或模型目录过旧时运行 ./install-codex.sh 安装固定版本到忽略的 .cache/codex-cli,或设置 AI_PCB_CODEX_EXECUTABLE。项目安装脚本固定版本为 codex-cli 0.166.0;其他安装通过 doctor 核对协议及模型目录。

doctor 执行初始化、认证状态读取、model/list 和一次无推理的临时会话参数确认,不启动 turn 或推理;返回 inference_verified=false,目录可见不代表已通过实际推理验收。ChatGPT 登录模式启用 Codex 前,还必须在当前客户端的官方模型目录中看到所选型号;会话参数回读成功本身不能证明推理可用。旧目录缺少目标型号时,更新客户端并刷新官方目录,不手工伪造条目或替换型号。凭据过期或配额不足会保留诊断并按有界策略结束,不弹出要求网页用户登录或操作服务器。

交付后的 OpenAI API 模式

设置 AI_PCB_CODEX_AUTH=apikey,在后台私有环境提供 OPENAI_API_KEY 或 OPENAI_API_KEY_FILE,默认端点为 https://api.openai.com/v1。更换认证模式/凭据环境后重启后台;模型日常切换不需要重启。此模式使用独立 Codex 目录(可由 AI_PCB_OPENAI_CODEX_HOME 配置,与研发登录目录独立)和 vibemake_openai Responses provider,明确使用 API key,不借用个人 ChatGPT 登录。两种认证模式共享完全相同的模型、结构化调用接口和网页协议。

官方 app-server 文档 说明个人 app-server 登录不用于商业或托管服务;对外部署必须改用服务端 API 凭据或另行集成获准的 Sign in with ChatGPT 流程。模型与 medium 档位见 GPT-6.1 Sol 文档。

离线回归检查(不调用真实模型、不创建生产绘板任务):

PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -p 'test_provider_switch.py' -v

2026-11-05 模型访问修复

服务器原 ~/.codex/config.toml 用 model_catalog_json 强制加载旧手工目录,遮蔽官方更新;后台同时固定使用 0.154.0-alpha.6.2,其官方版本目录也不提供 gpt-6.1-sol。已备份并移除旧覆盖,改用项目缓存中的 0.166.0,保留账号登录及 DeepSeek 配置。官方账号目录已返回 gpt-6.1-sol / medium,并通过该客户端完成一次最小真实 JSON 推理。验证记录位于仓库外;未创建 PCB 测试任务。

providerctl.py use codex 在 ChatGPT 模式会检查登录和实际客户端目录。若手工设置了本地 model_catalog_json,应确认其必要性;该设置会阻止远端目录获取。目录可见仍不等于真实推理验收,客户端升级后的真实调用应由明确授权的最小连通性验证确认。

Codex 结构化输出兼容

providers/schema.py 将原始校验 schema 转换成 OpenAI 严格结构化输出支持的子集。uniqueItems、字符串长度等未传入模型的约束仍由原始 JSON Schema 在服务器端验收,失败进入有界修复;不删除原始约束,也不绕过 PCB 检查。const 转成单值 enum,未知结构表达式在提交前明确报错。每次调用保存原 schema、实际 wire schema 和转换记录,缓存包含适配版本。

离线回归:PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -p test_schema_compat.py -v。它覆盖真实需求、方案和设计 schema,并验证重复附件编号仍被本地校验拒绝。

原理图自动扩纸

新原理图默认 A3。在固定排版放不下时,自动扩至 A2/A1/A0;仍不足则继续增大自定义画布。原生接口改纸后会保存、读回实际宽高,并核对器件身份和位置未因改纸而改变。排版继续使用相同器件与网络,不改变 PCB 尺寸。扩纸记录和最终布局报告随流程资料导出。

机械几何与未完成布线恢复

布线输入包含真实工程库封装的开槽、定位孔、禁布区及板边退让(计入板框线宽),导入及倒角后再次检查机械间距。选型完成前,自动检查封装本身与当前制造规则的兼容性;冲突反馈具体器件/焊盘,限定 AI 更换兼容器件,不修改加工规则。USB 合并引脚同时写入原生原理图并核对原始逻辑网表,明确未用引脚添加 NC 标记。

Freerouting 在同一预算内保留并继续最优结果;剩余连接由有界固定补线处理,AI_PCB_ROUTE_FINISH_SECONDS 默认 35 秒、最多 90 秒。补线保留现有线宽、焊盘网络、实际过孔尺寸及机械间距。可证明的普通焊盘与闭合直线多边形优先按实际坐标导出布线输入,避免原生 DSN 对合并焊盘的坐标舍入;单层有铜的镀通钻孔保留反面钻孔避让,不虚构反面焊盘。导入后重建原生连接索引,逐项验证器件、焊盘、钻孔、线宽和铜线几何未改变;允许嘉立创将等价共线段拆分,以及把 270° 表示为 −90°。铜线和网络变化仍拒绝放行。

超时和未连接仍作为真实失败/草稿发现记录,不自动转换为制造通过。启动阶段卡住会保留线程诊断,避免用户只能看到通用的超时提示。

自动修复与续跑(EasyEDA)

用户确认方案后,设计异常进入持久化恢复循环,使用服务端 Codex 绑定诊断。 不设修复总次数或总时长上限;每次调用和 EDA 操作仍保留超时,并在失败后退避 5–60 秒。 用户取消仍有效。模型权限、原生身份守卫、器件与引脚校验、制造放行检查保持有效。 恢复决策只能选择器件、连线、PCB 构建、校验、导出阶段,不可跳过失败阶段。 连线修改限制在诊断指定的引脚,禁止断开已有功能。器件修复作者禁止删除已有器件。 保存阶段检查点和原生语义指纹,现场变化则使相关下游检查点失效。 导出失败复用已核验结果;布线失败增加下次布线进程的时间和轮次,不降低间距规则。 project/work/recovery-N.json 保存完整异常;任务记录保存修复方案、历史和检查点,流程资料可下载诊断。 服务重启使用原生执行日志对账后继续;结果未知的写入不能直接重放。 本机制不授权模型修改共享服务代码。缺少运行依赖、模型权限失效、固定算法缺陷等可能持续重试, 需要运维修复后再恢复;无限预算不等于保证所有电路最终可实现。

无进展循环处理

封装换件保留当前封装的全部拒绝原因(包含型号与供应商料号别名)。同一冲突仅询问一次模型, 随后改为实时库分页搜索并逐项执行原有兼容性检查。重复候选记录跳过原因,不再产生无说明的空结果。 完成一轮库检索仍无合格候选时保留工程,间隔五分钟刷新,不重复询问同一问题。 泛化修复对错误、需求和原生电路状态取指纹。首次策略无效后要求不同策略,工程证据未改变且 再次无效时转为等待新证据,不将旧错误重新包装成新的模型任务。任务不会因此标记失败或释放制造包。 这不是修复总预算:新工程证据可触发新修复;取消入口保持有效。没有合格候选或运行环境未修复时, 界面明确显示等待状态,不能保证任务单凭等待就完成。服务保持运行时定期检查;停服后需恢复服务。

终端中文进度日志

前台运行 backend/start.sh,每条设计事件立即输出到标准错误,格式为 [年-月-日 时:分:秒 +08:00] [任务ID] 中文进度,时区为 Asia/Shanghai。 覆盖需求、模型调用、器件搜索、连线、布局布线、校验、交付和恢复事件。 执行器超过 30 秒没有新事件时输出最近阶段和等待时长,明确区分等待与实际进展。 简要进度与下述开发详情同时输出,认证凭据仍会隐藏。子进程 JSON 通信格式不变。 如需保存终端日志,可使用 ./start.sh 2>&1 | tee -a /绝对路径/pcb-console.log。

当前内网服务器在仓库根目录执行以下命令,前端由既有 systemd 单元启动,后台在当前终端运行:

systemctl --user start vibemake-pcb-lan.service
./backend/start.sh

浏览器访问 https://192.168.1.200:15180/pcb/。后台启动会恢复已保存的未完成任务。 此 systemd 单元与 HTTPS 证书是当前服务器配置;其他机器按前面的通用部署说明配置。 关闭终端或 Ctrl+C 会停止前台后台进程,长任务期间应保留终端或在 tmux 中运行。

完整开发详情日志

默认启用 AI_PCB_DEV_LOG=1。后台终端打印模型角色、模型配置、完整系统指令、输入上下文、 输出 JSON Schema、模型返回答案、生成脚本、实际 EDA CLI 调用与脚本输入、完整执行结果及错误。 日志区分“准备执行”“提交”“返回/失败”,生成了脚本不等于已经成功执行。 工程事件附带完整数据,包含候选拒绝原因、修复方案和检查结果。模型未公开的内部思考不在日志中。 二进制附件仅记录引用,API key、登录令牌和密码隐藏,不输出认证环境。

详情同时追加到 AI_PCB_API_DATA/logs/debug/<task_id>.log,默认不截断工程文本。 开发日志可能较大,需要按运行情况归档。设置 AI_PCB_DEV_LOG=0 关闭完整详情。 HTTP 访问日志默认关闭,设置 AI_PCB_HTTP_ACCESS_LOG=1 可重新开启。 上述设置在新启动的后台进程生效,不热重启正在设计的任务。

不重启后台查看旧进程正在执行的任务,可在另一个终端运行只读查看器:

./backend/.venv/bin/python backend/watch-debug.py --task pcb-实际任务编号

它从现有任务文件持续读取最近的模型提问、答案、新增执行记录及状态,历史记录会标注“已保存”。 不会创建任务、恢复任务或修改工程,Ctrl+C 仅退出查看器。旧进程尚未记录的底层 CLI 详情无法补录。 需要检查一次后退出时加 --once。新进程的完整详情也可直接 tail -f 对应日志文件。