Files
vibemake-pcb-studio/backend/easyeda_backend/docs/codex_python.md
T
2026-11-10 19:04:27 +08:00

8.9 KiB
Raw Blame History

Python 对接 Codex App Server

本阶段实现本机 Python 基础接入,不启动网站服务,不依赖 Docker,不操作嘉立创工程。入口为 codex_client.py,可复用库为 codex_bridge/。Python部分只用标准库,要求Python 3.10+;另需已安装并完成认证的Codex CLI。

已实现

  • Python拥有独立App Server子进程,以stdio JSONL通信;握手一次、请求ID关联、并发RPC、通知订阅。
  • 创建会话、跨进程恢复会话、真实模型调用、流式事件、终态与最终回答提取。
  • 模型分页发现、认证是否存在的检查;不输出账户邮箱或凭据。
  • 服务端反向请求处理;默认拒绝额外命令/文件权限,空权限授权,取消无交互输入,未知方法返回协议错误。可通过库注入自己的async处理器。
  • 请求/轮次超时、主动中断请求、异常退出、订阅溢出及本进程拥有的子进程清理。
  • 原子状态文件与独占锁;记录thread/turn ID,未知结果禁止自动重发;按历史回读恢复最终结果。
  • 可选PCB工作流入口和文件摘要装载;后续恢复检测工作流文件变化。

completed只表示模型轮次结束,不保证它成功完成业务任务。模型可能解释“资料不足”或“工具失败”;上层必须检查结构化结果、工程证据及实际产物。

安装和认证

使用已安装的Codex CLI,无需复制当前电脑的可执行文件或登录文件。新机器按官方安装和认证文档准备CLI。先检查:

codex --version
codex app-server --help
python3 codex_client.py doctor

脚本按以下优先级查找:显式 --codex → 环境变量 AI_PCB_CODEX_EXECUTABLE → PATH中的codex → 已知Linux桌面安装位置 /usr/lib/chatgpt/resources/codex。不修改系统PATH,也不自动安装软件。显式配置错误时直接报错,不静默换用另一个程序。doctor会返回实际使用的executable。

自动查找未覆盖的安装位置,可显式指定:

python3 codex_client.py --codex /absolute/path/to/codex doctor

doctor不发起模型推理;会访问账户/模型信息接口。account_present与requires_openai_auth只是诊断,最终可调用性以真实轮次为准;第三方提供商配置可能不依赖OpenAI账户。

本机默认继承Codex的现有认证和配置,不新建或修改全局配置,不复制密钥。管理员可以使用 --config 'key=value' 传入显式受信任覆盖项;不要把网站用户字符串传给该选项。密钥不要放命令行、版本库、日志或交付ZIP。实际模型提供商、计费和网络由部署环境决定。

运行一次与恢复上下文

以下命令在交付包目录运行;workspace目录必须事先存在。状态文件与模型成果放在独立工作目录:

python3 codex_client.py run \
  --workspace ../projects/my-board \
  --state ../projects/my-board/work/codex-session.json \
  --prompt '先分析需求,不绘图。' \
  --pcb-workflow \
  --events ../projects/my-board/work/codex-events-001.jsonl \
  --timeout 300

python3 codex_client.py resume \
  --state ../projects/my-board/work/codex-session.json \
  --prompt '继续讨论刚才的方案。' \
  --timeout 300

长输入使用 --prompt-file /path/to/prompt.txt,与 --prompt 二选一。可在run时用 --model 显式选择doctor返回的可用model;不指定则遵循部署配置。run不会覆盖已有state,事件日志也不会覆盖已有文件。

默认sandbox为read-only。需要在已授权项目内写入时,创建会话时显式指定 --sandbox workspace-write;本CLI不提供danger-full-access快捷选项。工作目录不是完整的多租户隔离边界,继承的MCP/插件和用户级配置也可能拥有独立权限;本模块仅供可信本机基础接入,后续服务端必须增加执行环境和工具权限隔离。

--pcb-workflow会提供README、两份Skill、设计准则、输入协议、文件协议、参考检索流程的绝对路径和版本摘要。它不等于已经完成参考检索或已经获得绘图授权。文件改变时拒绝直接恢复旧工作流会话,应审阅变更并创建新会话。整体搬家后路径与本机Codex会话存储不能假定仍有效,应重新初始化。

会话恢复、超时与进程生命周期

python3 codex_client.py inspect --state ../projects/my-board/work/codex-session.json
python3 codex_client.py recover --state ../projects/my-board/work/codex-session.json

inspect只读会话元数据。recover按已知turn_id查历史,不重新提交原输入,核实终态后恢复可继续状态及最终回答;历史分页不会只读第一页。

状态文件的状态为creating_thread、ready、starting、running、completed、failed、interrupted或outcome_unknown。请求超时不代表服务器没有执行,尤其thread/start、turn/start可能已成功。没有收到ID时不猜“最新会话/最新轮次”是当前任务,需人工核对。

轮次超时或Ctrl+C会尽力向当前连接发送turn/interrupt;收到中断RPC响应不等于轮次已经结束,仍保留outcome_unknown并要求recover。SDK调用方可以在同一个活动AppServer实例中发送 turn/interrupt,并等待对应turn/completed。不能靠另开一个进程盲目中断其他实例的轮次。

子进程正常退出、强制终止或协议异常会通知所有等待者。退出先关闭stdin,再有界等待,必要时终止本客户端创建的App Server PID;不会按进程名或端口杀用户的桌面Codex/嘉立创。没有自动重连重放有副作用操作。

独占锁在正常退出时删除;硬崩溃可能留下.lock文件,其内容包含PID和主机。必须先确认原进程不再运行,才可手动移走锁,然后inspect/recover;不自动按时间删除锁。仅保护本状态文件的协作调用,不能阻止其他客户端直接操作同一Codex会话。远程NFS/多机锁不在本阶段支持范围。

供后续服务调用的Python接口

import asyncio
from pathlib import Path
from codex_bridge import AppServer
from codex_bridge.session import Journal, run_turn

async def main():
    async with AppServer() as client:
        with Journal(Path('/absolute/work/session.json')) as journal:
            if journal.data:
                raise RuntimeError('Use the resume/recovery path for existing state')
            journal.save(status='creating_thread')
            reply = await client.request('thread/start', {
                'cwd': '/absolute/project',
                'sandbox': 'read-only',
                'approvalPolicy': 'on-request',
                'approvalsReviewer': 'user',
            })
            journal.save(status='ready', thread_id=reply['thread']['id'])
            result = await run_turn(client, journal, '分析这份需求', timeout=300)
            print(result)

asyncio.run(main())

client.request(method, params)返回RPC result,错误抛RpcError;client.subscribe()返回独立通知队列,必须在发送turn/start前订阅,避免完成事件先于RPC响应到达。慢消费者队列溢出会明确报错,不静默漏掉完成事件。请求处理器与事件消费者不能阻塞stdout读取循环。

run_turn(..., event_callback=async_callback)提供经过方法过滤的公开进度事件;私有reasoning项不进入此回调。底层subscribe面向受信任集成代码,不保证所有原始通知都适合发给用户。未来网站适配层必须进一步白名单化和鉴权,不能原样转发。

CLI可选events JSONL只记录序号、阶段、项目/轮次标识、item类型及助手公开文本增量,不保存命令参数、工具输出、私有推理或stderr。文件可能仍包含用户设计信息,需按私有数据管理;state也包含最终回答和绝对路径。POSIX新文件使用0600,Windows需另外设置ACL。状态原子替换用于单机崩溃恢复,不替代数据库事务或审批签名。

测试与边界

离线回归:

python3 -m unittest discover -s tests/codex_bridge -v

测试fixture明确为模拟服务,不调用模型、不画板。真实调用记录见 docs/codex_validation.json;本地原始状态不打包进交付包。CLI版本不同可能改变协议,升级时先导出其Schema并重复验收:

codex app-server generate-json-schema --out /temporary/schema-directory

网站鉴权和HTTPS/SSE服务器不在本项目范围。本地设计编排与制造包确认入口现见 design_service.md,真实PCB端到端验收待下一轮进行。本地SQLite队列、EDA Worker和检查点恢复现已另行实现,见 eda_runtime.md;可用全局参数 --eda-root 与 --eda-scope 给本次App Server加载作用域受限的EDA工具。恢复会话需带相同配置。无需Docker。

官方资料:https://developers.openai.com/codex/app-server、https://developers.openai.com/codex/auth。协议以安装版本导出的Schema及实测为准。