codex_backend/main.cjs.md

index.cjs 说明

文件作用

这个文件启动本地 Express 服务，为前端提供 Codex 登录管理、普通聊天和流式聊天 API。它把 HTTP 请求转换成对 codexClient.cjs 的函数调用，并负责错误转换、CORS、JSON 解析和 SSE 输出。

服务配置

• PORT：默认 8787，可通过环境变量 PORT 覆盖。
• HOST：默认 127.0.0.1，可通过环境变量 HOST 覆盖。
• 使用 cors 只允许本地来源。
• 使用 express.json({ limit: '2mb' }) 解析 JSON 请求体。

主要函数

isAllowedOrigin(origin)

判断请求来源是否允许：

• 没有 origin 时允许，方便非浏览器或同源请求。
• 只允许 hostname 为 localhost、127.0.0.1、::1 的来源。
• URL 解析失败时拒绝。

writeSse(res, eventName, data)

向响应写入一条 SSE 事件：

• 写入 event: 事件名。
• 写入 JSON 序列化后的 data:。
• 用空行结束事件。

toHttpStatus(error)

从错误对象中读取 status 或 statusCode。如果是合法 4xx/5xx 状态码就返回它，否则返回 500。

toErrorMessage(error)

把错误对象转换为可返回给前端的字符串。优先使用 error.message，没有错误时返回未知错误文案。

API 路由

GET /api/health

健康检查接口，返回 { ok: true, provider: 'codex-sdk' }。

GET /api/codex/status

强制刷新 Codex 登录状态，调用 getAuthStatus({ force: true })。失败时返回标准错误 JSON。

GET /api/codex/login-log

返回当前或最近一次 Codex 登录进程状态，数据来自 getLoginState()。

POST /api/codex/login

启动 Codex 登录流程。请求体中的 deviceAuth 控制是否使用设备码登录。接口返回 202 和登录状态。

POST /api/codex/logout

执行 Codex 退出登录。命令成功时返回 200，命令失败时返回 500。

POST /api/chat

普通非流式聊天接口：

• 为请求创建 AbortController。
• 监听响应 close，如果客户端提前断开则中止 Codex 运行。
• 调用 runCodexOnce(req.body, controller.signal)。
• 成功时返回 JSON 结果，失败时返回错误 JSON。

POST /api/chat/stream

流式聊天接口：

• 创建 AbortController 并监听客户端断开。
• 设置 text/event-stream、禁用缓存和保持连接。
• 调用 runCodexStream。
• onDelta 时写入 delta SSE 事件。
• onError 时写入 error SSE 事件。
• 正常完成时写入 done SSE 事件并结束响应。
• 异常时写入 error 事件并结束响应。

依赖关系

该文件从 codexClient.cjs 引入 Codex 相关能力。前端 src/utils/api.js 会调用这里暴露的 API。