# 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。