171 lines
5.2 KiB
Markdown
171 lines
5.2 KiB
Markdown
# 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 路由调用。
|