Files
vibemake-pcb-studio/CODEX-SESSION.md
T
admin e7f19ff493
CI / typecheck + test + build (push) Has been cancelled
部署更改
2026-11-13 17:20:03 +08:00

14 KiB
Raw Blame History

Persistent Codex PCB service

The PCB entry now uses codex_pcb.app, a new service with no imports of the legacy PCB backend. The old backend/ sources are retained for traceability but are not the design execution path. vibemake-pcb2-api.service is disabled. Do not use it for new designs.

User flow

Open https://192.168.1.200:15182/pcb/?ai=1, describe a design, review its proposal, and add comments as needed. Approval binds the current proposal revision and SHA-256. Unsubmitted comments disable the approval button. Planning, revisions, production and recovery retain one native Codex thread ID.

Review has no Shell or EDA editing access. Production starts the same thread with native Shell, file editing, web search and a task-specific EasyEDA tool. No structured response schema constrains the agent's normal reasoning/output. The service never chooses a circuit, generates connectivity, places components or routes a board. Codex authors its own scripts and uses actual observed results. It may use installed Java/Freerouting and Blender as general utilities.

Runtime

  • Model: PCB_MODEL (default gpt-6.1-sol), reasoning PCB_REASONING_EFFORT (default high); no automatic model substitution. API projects must have access to the configured model.
  • Service: vibemake-pcb2-session.service, FastAPI on loopback 8003.
  • Web: vibemake-pcb2-web.service, HTTPS 15182, /pcb/pcb-api/ proxy.
  • Source: the installed checkout's codex_pcb/ directory.
  • Persistent runtime: PCB_SESSION_ROOT (default ~/.local/share/vibemake-pcb; use a persistent mount such as /data in a container).
  • Dedicated Codex home: PCB_CODEX_HOME (default $PCB_SESSION_ROOT/codex-home) stores native session history. Authentication can use a server-side OpenAI API key or an existing Codex login; credentials are not sent to the browser or copied into the repository.
  • Each task owns a workspace, native EDA session, full EDA scripts/results and Codex event evidence. Official standalone EDA API references come from the installed ~/.codex/skills/easyeda-api; no legacy design workflow is loaded.
  • The original ~/auto_pcb service and user-opened EDA windows are not modified.

Continuation and evidence

Browser connections are not job lifetimes. Server restart resumes unfinished work in the same persisted thread. Transient transport failures reconnect rather than reconstructing a short context summary. Unknown native mutations must be inspected by the agent before replay. Cancellation is available during production; already-executed native changes remain in the draft.

When an agent turn ends without accepted delivery, the service asks the same session to continue. Three successive turns without EDA progress and without delivery stop as a recorded failure; a concrete blocker remains visible instead of a false success. A disappeared EDA session is reported explicitly, with the saved workspace preserved.

At approval the service hashes its Python source and instructions. Any subsequent change blocks production tool calls/resume. Therefore an acceptance run cannot silently continue with a patched backend. A new version requires a new task/run.

The approval hash also covers non-secret runtime settings, including the model, reasoning effort, provider and executable paths. Rotating an API key does not change this hash. An existing thread cannot be switched between the login and API providers; create a new task after changing provider/model settings. Deploy source changes only after active tasks have finished; already-approved tasks from an earlier source version cannot be resumed by rewriting their hash.

Portable paths and OpenAI API authentication

For the backend-only Docker/1Panel upload bundle, build commands and EDA mount layout, see codex_pcb/DEPLOY.md. Generate the bundle with python3 scripts/package-pcb-backend.py.

Backend settings are documented in codex_pcb/.env.example; they are separate from the frontend/proxy's .env.pcb.example. Copy the backend example to an ignored .env.local, fill in the key on the server, and inject it into the backend process using Compose env_file, systemd EnvironmentFile, or Uvicorn --env-file (requires python-dotenv). Merely creating an env file does not load it.

Existing installations must explicitly keep PCB_SESSION_ROOT pointing at their original runtime to retain access to task records and Codex history; the new portable default does not migrate old directories.

For API authentication set PCB_CODEX_AUTH=apikey and either OPENAI_API_KEY or OPENAI_API_KEY_FILE. The environment value takes precedence; the file is useful with Docker secrets. The service configures a dedicated Codex provider using the OpenAI Responses API at https://api.openai.com/v1, with env_key=OPENAI_API_KEY. It passes the key only to the Codex process, without adding it to CLI arguments or writing an auth.json. No interactive Codex login is required in this mode. Existing login credentials are not used as a fallback. API use is billed to the OpenAI API project; authentication does not guarantee access to the configured model.

To retain the earlier login setup, explicitly set PCB_CODEX_AUTH=chatgpt (also the default for compatibility) and provision the service's PCB_CODEX_HOME with the existing login. This mode removes API keys from the Codex process environment. Use a dedicated service home rather than your IDE's session directory. Both thread/start and thread/resume select the same provider.

Set PCB_CODEX_BIN, PCB_EDA_BIN and PCB_BLENDER_BIN to installed executables, or leave them unset to search PATH for codex, lceda-pro and blender. Set PCB_FREEROUTING_JAR when the JAR is outside $PCB_SESSION_ROOT/resources/freerouting.jar; both the production prompt and standalone launcher honor it. EDA subprocesses preserve an explicitly configured XDG_RUNTIME_DIR and DISPLAY; neither setting starts a display server. Create a private runtime directory owned by the service user with mode 0700, and start/configure Xvfb separately on headless servers. The EDA application, Java, Xvfb/xauth and Blender still need to be installed and validated.

For example, after injecting the settings, start one backend instance from the checkout root:

python -m uvicorn codex_pcb.app:app --host 0.0.0.0 --port 8003 --workers 1

Persist PCB_SESSION_ROOT, any separately configured PCB_CODEX_HOME, and the native EDA application's user/project data. A key alone does not install CAD dependencies. A successful /api/health checks the HTTP service, not API billing/model permissions or native EDA execution; validate with a new proposal and a real approved design. Never use a key pasted into chat; revoke it and supply a replacement only through server-side configuration.

See Codex authentication and provider configuration.

Delivery

The agent supplies real native project, schematic, routed layout, extracted assembled STEP and 3D render, plus optional BOM/reports. Delivery independently focuses the supplied native documents, saves them, exports native netlists and runs schematic/PCB checks. Both native gate booleans must be true. Basic file signatures and path boundaries are checked, then files are copied to a separate delivery directory with hashes and a ZIP. Downloads verify hashes again.

These software checks do not establish hardware/thermal/RF performance; native DRC is not a replacement for an engineering review. ESP32 acceptance additionally checks model readability, exported previews and electrical intent evidence. Backend validation never alters circuit or layout to obtain a pass.

New STEP deliveries must preserve the native assembly's surface colors. The appearance check follows applied STEP style references and rejects missing or uniform palettes before native delivery verification; the tool returns repair feedback to the same running agent, without marking the task failed or complete. Native geometry and electrical checks remain mandatory. When rebuilding XCAF assemblies, the agent must preserve color attributes alongside shape/face and instance transforms, then reopen the final exported file to verify appearance. A colored render is not evidence that the STEP is colored.

Existing deliveries are immutable. For historical colorless STEP files, the website can load a checksum-verified companion OBJ/MTL archive for colored appearance, clearly labeled separately from the original STEP used for mechanical measurements. Optional archive failures fall back to the original STEP and preserve all downloads. The viewer never invents colors. New tasks are instructed to include the genuine final OBJ/MTL archive when available.

Operations

systemctl --user status vibemake-pcb2-session.service vibemake-pcb2-web.service
journalctl --user -u vibemake-pcb2-session.service -f
curl http://127.0.0.1:8003/api/health

The root start.sh --services starts the new systemd services on a configured Linux server. Without this flag, start.sh builds/serves the frontend and proxies its API to the separately running backend (default 127.0.0.1:8003). All requests are asynchronous and the UI polls task state/events. The service binds loopback; the web proxy retains its same-origin write checks.

Acceptance protocol

  1. Pass permission, revision, cancellation, path and delivery boundary tests.
  2. Verify actual native Codex Shell + dynamic tools across process restart with one thread ID.
  3. Verify native EDA session and exported-file transport independently.
  4. Build the website, check browser input/review and prepare an ESP32 request through the UI.
  5. Review/comment/approve in the UI; record source hash and approval.
  6. Observe only. No developer design scripts, prompt steering or backend edits after approval. Agent-authored script fixes are allowed and recorded.
  7. Collect terminal outcome, source hash comparison, native checks, downloadable files, independent STEP parse and visual review. Failed runs are retained and reported honestly. A backend correction requires a new numbered run.

Freerouting 无交互部署注意事项(2026-11-11)

已验证版本:Freerouting 1.9.0(build-date 2023-10-30)。本服务使用通用启动入口 codex_pcb/freerouting.py;它只处理参数、进程和输出文件,不指定电路、布局或布线算法。

两类弹窗的原因

  • “Select the design file / Neither the design file nor the directory were specified”:1.9.0 只支持 -help,不支持 --help。直接执行 java -jar freerouting.jar --help 会忽略错误参数并进入等待选文件的窗口。它不是计算进度窗口,也不会自行完成绘板。不要无输入启动 JAR 来探测用法;启动入口的 --help 使用 Python 直接输出帮助,不启动 Java。
  • “Autorouter confirmation / Start Now”:原生程序默认倒计时 20 秒。启动入口固定加入 -dct 0,直接启动布线而不显示此确认框。手动运行时可以点击 Start Now;Cancel 或关闭确认框不会启动这一轮布线。
  • 不要用 -Djava.awt.headless=true 替代虚拟显示:该版本仍访问 Java AWT 屏幕和窗口,会抛出 HeadlessException。默认通过独立的 xvfb-run 运行,既保持 GUI 依赖,又不打扰服务器桌面。--visible 只用于人工诊断,仍然跳过倒计时。

新服务器部署与使用

  1. 安装 Python 3、可运行此 JAR 的 Java(1.9.0 官方要求 Java 17)、xvfb 和 xauth。Debian/Ubuntu 可以安装 openjdk-17-jre xvfb xauth;若已有兼容 Java,可保留现有版本。
  2. 将已验证的 JAR 放到 $PCB_SESSION_ROOT/resources/freerouting.jar,或使用 PCB_FREEROUTING_JAR / --jar 指定绝对路径。未配置运行根目录时默认使用 ~/.local/share/vibemake-pcb;容器中应显式设置为持久化挂载路径,例如 /data。
  3. 生产会话应使用批准消息提供的启动命令。下面路径需要按目标服务器替换:
python3 /path/to/vibemake-pcb-studio/codex_pcb/freerouting.py --help
python3 /path/to/vibemake-pcb-studio/codex_pcb/freerouting.py \
  --input /path/to/task/board.dsn \
  --output /path/to/task/route-01.ses \
  --jar /path/to/runtime/resources/freerouting.jar \
  --timeout 900 -- -mp 30 -mt 1 > /path/to/task/router-01.log 2>&1

-- 后传递已支持的版本参数,例如 -mp/-mt/-oit/-us/-hr/-is/-inc/-dr/-l 和 -im/-da。AI 仍可选择布线参数和超时;输入、输出、倒计时和帮助参数由启动入口统一管理,未知参数直接报错。默认超时 900 秒,不意味着布线需要固定等待 900 秒。

入口拒绝缺失输入和已有输出。每次尝试使用新的 SES 文件名,避免把旧结果误当成功;临时输入和 Java/Xvfb 缓存放在输出目录下,结束后清理。输入副本与旧 .rules/快照隔离,防止额外恢复确认;需要规则文件时显式传入 -dr。超时或取消只清理本次进程组,不执行 pkill java 等全局操作,不发布半成品 SES。正常完成后核对 SES 标识并发布到指定路径。

  1. 部署检查:帮助命令应立即退出且不弹窗;缺失输入应立即报错;用隔离的 DSN 副本完成一次真实布线,确认日志没有 20 秒启动等待、桌面没有新增 Freerouting 窗口、SES 能读回。运行 python3 -m unittest discover -s codex_pcb/tests -p test_freerouting.py -v 检查启动边界。
  2. 路由器成功退出不代表整板布通,仍需由会话导入 SES、检查未连网络、运行嘉立创原生 DRC 和最终交付验证。

更新运行说明或 Python 源码会改变生产冻结哈希。先确认没有活动任务再部署并重启 vibemake-pcb2-session.service;旧版本已批准但未完成的任务不能通过改写哈希强行续跑,应保留记录并新建任务。

版本升级时重新核对参数和弹窗行为,不将 1.9.0 的命令行约定直接套到其他版本。

依据:1.9.0 命令行说明、参数解析、确认框与自动启动。