codex_backend/codexClient.cjs.md

codexClient.cjs 说明

文件作用

这个文件是后端与本机 Codex CLI / @openai/codex-sdk 的适配层。它负责检查登录状态、启动登录、退出登录、构造 Codex 请求线程、执行普通回复和流式回复，并把这些能力导出给 Express 路由使用。

主要常量和状态

• PROJECT_ROOT：项目根目录。
• CODEX_WORKSPACE：专门给 Codex SDK 使用的工作目录 .codex-chat-workspace。
• DEFAULT_MODEL：来自环境变量 CODEX_MODEL 的默认模型。
• DEFAULT_REASONING_EFFORT：来自环境变量 CODEX_REASONING_EFFORT 的默认推理强度。
• AUTH_STATUS_CACHE_MS：登录状态缓存时间。
• sdkPromise：缓存动态导入的 Codex SDK。
• authStatusCache：缓存最近一次登录状态。
• loginState：保存当前或最近一次登录命令的运行状态和日志。

文件加载时会创建 CODEX_WORKSPACE 目录。

主要函数

getCodexBin()

查找 Codex CLI 可执行文件。优先使用项目内 node_modules/.bin/codex，找不到时回退到全局 codex 命令。

getCodexHomeHint()

返回 Codex 本地配置目录提示。优先使用 CODEX_HOME 环境变量，否则使用用户目录下的 .codex。

appendLoginLine(chunk)

把登录命令输出追加到 loginState.lines。它会跳过空行，并且只保留最近 120 行，避免日志无限增长。

runCodexCommand(args, options)

执行 Codex CLI 命令的通用封装：

• 使用 spawn 启动命令。
• 在 CODEX_WORKSPACE 下运行。
• 收集 stdout 和 stderr。
• 支持传入 stdin。
• 支持超时，超时后终止子进程。
• 最终返回退出码、信号、输出和错误对象。

它主要用于登录状态检查和退出登录。

loadCodexSdk()

动态导入 @openai/codex-sdk，并用 sdkPromise 缓存导入结果，避免重复加载。

normalizeInput(input)

清洗前端传入的消息数组：

• 只保留对象类型且有字符串 role 的项。
• 将 content 转为字符串。
• 去掉空内容消息。

roleTitle(role)

把请求角色转换成写入提示词的标题：

• developer 或 system 显示为开发者指令。
• assistant 显示为 assistant。
• 其他角色显示为 user。

buildCodexPrompt(input)

把结构化消息数组转换成单个 Codex prompt：

• 先标准化输入。
• 将每条消息转换成 ### 角色标题 加正文的文本块。
• 在开头加入本地网页聊天工具的约束说明。
• 要求模型只回复最后一条 user 消息，不混入其他会话上下文。

normalizeModel(model)

合并请求体模型名和环境变量默认模型，并返回修剪后的字符串。

normalizeReasoningEffort(value)

校验推理强度，只允许 minimal、low、medium、high、xhigh。非法值会回退到 medium。

createThreadOptions(body)

创建 Codex SDK thread 运行选项：

• 使用只读沙箱。
• 禁用审批。
• 固定工作目录为 CODEX_WORKSPACE。
• 跳过 Git 仓库检查。
• 禁用网络和 Web 搜索。
• 透传推理强度和可选模型。

这些设置降低本地聊天代理对用户文件和网络的影响范围。

createCodexClient()

创建 Codex SDK 客户端，并关闭原始 agent reasoning 输出，让前端只展示面向用户的最终回答。

hasUsableAuth(status)

判断 Codex 是否可用：既要安装 CLI，也要处于已登录状态。

getAuthStatus(options)

检查 Codex 登录状态：

• 默认使用短期缓存，force 为真时强制刷新。
• 执行 codex login status。
• 根据退出码判断是否已登录。
• 返回安装状态、登录状态、认证模式输出、提示消息、Codex home 和检查时间。

ensureLoggedIn()

在执行聊天请求前校验 Codex 可用性。CLI 未安装时抛出 503 错误；未登录时抛出 401 错误。

startLogin(options)

启动 Codex 登录流程：

• 如果已有登录进程在跑，直接返回当前登录状态。
• 默认启动 codex login。
• deviceAuth 为真时追加 --device-auth。
• 保存进程 pid、开始时间、结束时间、退出码、信号和输出日志。
• 登录进程结束后清空认证状态缓存。

getLoginState()

返回当前登录状态快照，供前端轮询展示。

logoutCodex()

执行 codex logout，清空认证状态缓存，并返回命令结果。

runCodexOnce(body, signal)

执行一次性聊天请求：

• 先确认 Codex 已登录。
• 用 buildCodexPrompt 生成 prompt。
• prompt 为空时抛出 400 错误。
• 创建 Codex client 和 thread。
• 调用 thread.run(prompt, { signal })。
• 返回最终文本、thread id 和 usage。

runCodexStream(body, signal, handlers)

执行流式聊天请求：

• 校验登录和 prompt。
• 调用 thread.runStreamed(prompt, { signal })。
• 遍历 SDK 返回的事件流。
• 对 agent message 计算增量文本，并调用 handlers.onDelta(delta)。
• 记录 turn.completed 的 usage。
• 遇到 SDK 错误事件时抛出后端错误。
• 返回完整文本、thread id 和 usage。

导出接口

该文件导出：

• getAuthStatus
• getLoginState
• logoutCodex
• runCodexOnce
• runCodexStream
• startLogin

这些函数由 server/index.cjs 的 API 路由调用。