# auto_pcb_2 运行说明 当前工作区默认使用 Codex GPT-6.1 Sol。本站入口、15182/8003 端口、独立数据目录、强制方案审核和 STEP 导出,以 [PCB-SERVICE.md](../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 张,完整附件仍保留供下载。 ```bash 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 示例): ```bash 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 和库目录: ```dotenv 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](kicad_backend/README.md)。 运行数据默认在仓库外 `~/.local/share/vibemake-pcb`,可通过 `AI_PCB_API_DATA` 覆盖。DeepSeek key 放环境变量或仓库外私有配置;`.env.local`、数据库、工位日志、模型响应和任务历史不得提交。网页流程资料导出、复制/粘贴、原有审核摘要与权限校验继续保留。 ## 不调用真实模型的验证 ```bash PYTHONPATH=.:api .venv/bin/python -m unittest discover -s tests -p 'test_easyeda_dispatch.py' -v ``` 这些检查使用临时目录和替代模型,不发起真实绘板任务或模型请求。第三方依赖和来源见 [THIRD-PARTY.md](THIRD-PARTY.md) 与 [easyeda_backend/SOURCES_AND_SCOPE.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 或等待网页用户批准工具。 在后台主机执行: ```bash 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 文档](https://learn.chatgpt.com/docs/app-server) 说明个人 app-server 登录不用于商业或托管服务;对外部署必须改用服务端 API 凭据或另行集成获准的 Sign in with ChatGPT 流程。模型与 medium 档位见 [GPT-6.1 Sol 文档](https://developers.openai.com/api/docs/models/gpt-6.1-sol)。 离线回归检查(不调用真实模型、不创建生产绘板任务): ```bash 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 单元启动,后台在当前终端运行: ```bash 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/.log`,默认不截断工程文本。 开发日志可能较大,需要按运行情况归档。设置 `AI_PCB_DEV_LOG=0` 关闭完整详情。 HTTP 访问日志默认关闭,设置 `AI_PCB_HTTP_ACCESS_LOG=1` 可重新开启。 上述设置在新启动的后台进程生效,不热重启正在设计的任务。 不重启后台查看旧进程正在执行的任务,可在另一个终端运行只读查看器: ```bash ./backend/.venv/bin/python backend/watch-debug.py --task pcb-实际任务编号 ``` 它从现有任务文件持续读取最近的模型提问、答案、新增执行记录及状态,历史记录会标注“已保存”。 不会创建任务、恢复任务或修改工程,Ctrl+C 仅退出查看器。旧进程尚未记录的底层 CLI 详情无法补录。 需要检查一次后退出时加 `--once`。新进程的完整详情也可直接 `tail -f` 对应日志文件。