@classicicn/codex-transfer 0.2.0 → 0.3.1

package/README.en.md

@@ -0,0 +1,397 @@
+# codex-transfer
+
+**English** | [中文](./README.md)
+
+> Responses API ↔ Chat Completions translation bridge — use DeepSeek, Kimi, Qwen, and other OpenAI-compatible providers with Codex CLI.
+
+## Overview
+
+Codex CLI communicates using OpenAI's **Responses API**, while most third-party LLM providers (DeepSeek, Moonshot, Qwen, etc.) only implement the earlier **Chat Completions API**. These two APIs differ significantly in request format, response structure, streaming event sequences, and tool call representation.
+
+`codex-transfer` runs a local HTTP proxy that transparently translates Responses API requests from Codex CLI into Chat Completions API requests, and reverse-translates upstream responses back into Responses API format — so Codex CLI never notices the difference.
+
+```
+Codex CLI (Responses API)  →  codex-transfer (:4444)  →  Third-party Provider (Chat Completions API)
+```
+
+- **Zero runtime dependencies**: esbuild bundles everything into a single `dist/codex-transfer.mjs` file — run via `npx` instantly
+- **Stateless by design**: in-process session management, no external database required
+- **~1500 lines of TypeScript**: lightweight and auditable
+
+---
+
+## Quick Start
+
+```bash
+# One-shot run (no install needed)
+npx @classicicn/codex-transfer -k
+
+# Specify upstream provider
+npx @classicicn/codex-transfer -k -u https://api.deepseek.com/v1 --api-key sk-xxx
+
+# Global install
+npm install -g @classicicn/codex-transfer
+codex-transfer -k
+```
+
+---
+
+## CLI Options
+
+```
+codex-transfer [options]
+
+Options:
+  -p, --port PORT        Listen port (default: 4444)
+  -u, --upstream URL     Upstream Chat Completions base URL
+      --api-key KEY      API key for upstream
+  -m, --model MODEL      Force override model name (highest priority)
+  -c, --config PATH      Path to config file (JSON)
+  -k, --insecure         Skip TLS certificate verification
+      --no-reasoning-effort  Don't send reasoning_effort to upstream
+  -d, --daemon           Run in background, logs to logs/ directory
+  -h, --help             Show this help
+```
+
+### Daemon Mode
+
+```bash
+codex-transfer -d -k -u https://api.deepseek.com/v1 --api-key sk-xxx
+
+# Output:
+# codex-transfer started in background (PID: 12345)
+# Log file: ~/.codex-transfer/logs/codex-transfer-20260507-143022.log
+# PID file: ~/.codex-transfer/logs/codex-transfer.pid
+# Stop:   kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
+```
+
+In daemon mode, all `console` output is redirected to timestamped log files. Logs auto-rotate when a single file exceeds **10MB**, keeping up to **5 historical files**.
+
+---
+
+## Configuration
+
+### Priority
+
+```
+CLI args > environment variables > config file > defaults
+```
+
+### Config File
+
+Create a JSON config file at one of these locations (searched in order):
+
+1. Explicit `--config` path or `CODEX_TRANSFER_CONFIG` env var
+2. `./codex-transfer.json` (current directory)
+3. `~/.codex-transfer/config.json` (user home)
+
+```json
+{
+  "port": 4446,
+  "upstream": "https://api.deepseek.com/v1",
+  "apiKey": "sk-your-key-here",
+  "insecure": false,
+  "reasoningEffort": true,
+  "modelMap": {
+    "*": "deepseek-v4-pro",
+    "codex-auto-review": "deepseek-v4-pro"
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_TRANSFER_PORT` | `4444` | Listen port |
+| `CODEX_TRANSFER_UPSTREAM` | `https://openrouter.ai/api/v1` | Upstream Chat Completions base URL |
+| `CODEX_TRANSFER_API_KEY` | _(empty)_ | API key forwarded to upstream |
+| `CODEX_TRANSFER_CONFIG` | _(auto)_ | Path to config file |
+| `CODEX_TRANSFER_INSECURE` | `false` | Set to `"1"` or `"true"` to skip TLS verification |
+| `CODEX_TRANSFER_REASONING_EFFORT` | `true` | Set to `"0"` or `"false"` to disable sending reasoning_effort |
+
+### Model Name Mapping
+
+Codex CLI may send non-standard model names (e.g. `codex-auto-review`) that upstream providers don't recognize. Use `modelMap` to translate them:
+
+```json
+{
+  "modelMap": {
+    "*": "deepseek-v4-pro",
+    "codex-auto-review": "deepseek-v4-pro"
+  }
+}
+```
+
+**Lookup order**: exact key match → wildcard `"*"` → original name passthrough.
+
+The `--model` / `-m` flag takes precedence over `modelMap`, overriding all model names.
+
+---
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/health` | Health check — tests upstream `/models` connectivity, returns diagnostics |
+| `GET` | `/v1/models` | Model catalog proxy — transparently forwards upstream model list |
+| `POST` | `/v1/responses` | **Core endpoint** — receives Responses API requests, translates and forwards upstream |
+
+### `/v1/responses` Request Flow
+
+```
+Codex request arrives
+  → JSON parse & validate
+  → resolveModel() model name mapping
+  → Load message history (via previous_response_id)
+  → toChatRequest() protocol translation
+  → Branch:
+     ├─ stream=true  → translateStream() SSE generator → text/event-stream
+     └─ stream=false → fetch upstream → fromChatResponse() → JSON
+```
+
+---
+
+## Features in Detail
+
+### Protocol Translation
+
+Full bidirectional translation between Responses API and Chat Completions API:
+
+- **Request translation**: `input` array (`function_call` / `function_call_output` / regular messages) → Chat Completions `messages[]` array
+- **Response translation**: Chat Completions `choices[0].message` → Responses API `output[]` structure
+- **System prompt**: `instructions` (Codex CLI field) → Chat Completions `system` role
+- **Role mapping**: `developer` → `system`
+
+### Streaming Translation (SSE)
+
+Upstream Chat Completions SSE delta stream is translated chunk-by-chunk into the standard Responses API event sequence:
+
+```
+response.created
+  → response.output_item.added (message)
+  → response.output_text.delta × N
+  → response.output_item.done
+  → [if tool calls present]
+     response.output_item.added (function_call)
+     → response.function_call_arguments.delta
+     → response.output_item.done
+  → response.completed
+```
+
+**Design notes**:
+- Text deltas are forwarded in real time; tool call deltas are batched after stream completion (Chat Completions scatters tool calls across multiple chunks by index)
+- Top-level error fallback: even if upstream disconnects unexpectedly, a `response.failed` event is emitted, preventing Codex CLI from hanging
+
+### Token Usage Details
+
+Codex CLI relies on the usage fields in Responses API to calculate context window utilization. `codex-transfer` automatically extracts token usage from upstream responses and maps them to the Responses API format, handling differences between OpenAI and DeepSeek upstream formats:
+
+| Responses API Output | OpenAI Upstream Field | DeepSeek Upstream Field |
+|---|---|---|
+| `input_tokens` | `prompt_tokens` | `prompt_tokens` |
+| `output_tokens` | `completion_tokens` | `completion_tokens` |
+| `total_tokens` | `total_tokens` | `total_tokens` |
+| `input_tokens_details.cached_tokens` | `prompt_tokens_details.cached_tokens` | `prompt_cache_hit_tokens` |
+| `output_tokens_details.reasoning_tokens` | `completion_tokens_details.reasoning_tokens` | `completion_tokens_details.reasoning_tokens` |
+
+**Auto-detection**: The upstream format is automatically detected based on which fields are present in the response — no configuration needed. `cached_tokens` prefers the OpenAI nested field, falling back to the DeepSeek top-level field; `reasoning_tokens` uses the same path in both formats. Detail objects are omitted when the corresponding fields are absent.
+
+Both non-streaming and streaming paths share the same mapping logic.
+
+### Reasoning Effort Mapping
+
+Codex CLI controls model reasoning intensity via `reasoning.effort` (none/low/medium/high/xhigh), but providers implement this differently. `codex-transfer` automatically maps the Responses API reasoning effort to provider-specific parameters:
+
+| Codex Level | Responses API Value | DeepSeek | MiMo / Kimi / GLM |
+|---|---|---|---|
+| Minimal | `none` | `thinking: {type: "disabled"}` | `thinking: {type: "disabled"}` |
+| Low | `low` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| Medium | `medium` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| High | `high` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| Ultra | `xhigh` | `thinking: {type: "enabled"}, reasoning_effort: "max"` | `thinking: {type: "enabled"}` |
+
+**Compatibility strategy**: The `thinking` toggle is always sent (supported by all providers). `reasoning_effort` is sent by default (natively supported by DeepSeek); if the upstream doesn't support this field, it can be disabled via the `--no-reasoning-effort` CLI flag or `"reasoningEffort": false` in the config file.
+
+### Session Management
+
+Codex CLI uses `previous_response_id` for multi-turn conversations. `SessionStore` maintains the full message history for each session in memory, making every Chat Completions call **self-contained** (no dependency on upstream context caching).
+
+```
+┌─────────────────────────────────┐
+│  SessionStore (in-memory)        │
+│                                 │
+│  history:  Map<response_id,     │
+│                 ChatMessage[]>   │
+│                                 │
+│  reasoning: Map<call_id,        │
+│                 reasoning_text>  │
+│                                 │
+│  turnReasoning: Map<            │
+│    SHA256(content),              │
+│    reasoning_text>               │
+│  )                              │
+└─────────────────────────────────┘
+```
+
+### Reasoning Model Support (DeepSeek-R1 / Kimi-K2.6)
+
+Reasoning models produce `reasoning_content` (chain of thought) that must be **round-tripped verbatim** across turns — otherwise the model may reject the request or behave incorrectly.
+
+`codex-transfer` uses a **dual-index cache** to recover reasoning content:
+
+| Index method | Use case | Implementation |
+|-------------|----------|----------------|
+| **call_id exact match** | Codex uses `previous_response_id` + tool call replay | `Map<call_id, reasoning>` |
+| **Content SHA256 fingerprint** | Codex replays full `input[]` without `previous_response_id` | `Map<SHA256(content), reasoning>` |
+
+The two mechanisms complement each other, covering both conversation replay modes of Codex CLI.
+
+### Tool Call Handling
+
+- **Tool filtering**: Automatically filters OpenAI-proprietary built-in tools (`web_search`, `file_search`, `computer`, etc.), keeping only `type: "function"` custom tools to prevent upstream rejection
+- **Format conversion**: Responses API flat format `{type, name, description, parameters}` ↔ Chat Completions nested format `{type, function: {name, description, parameters}}`
+- **Parallel tool calls**: Consecutive `function_call` input items are merged into a single assistant message with multiple `tool_calls` entries
+- **Message reordering**: Codex may interleave other messages between `function_call` and `function_call_output` items, but providers like DeepSeek strictly require `assistant(tool_calls)` immediately followed by matching `tool` messages. `reorderForToolCalls()` handles this automatically, synthesizing empty output for orphaned tool calls
+
+### Health Check
+
+```
+GET /health → 200 OK
+{
+  "upstream": "https://api.deepseek.com/v1",
+  "apiKeySet": true,
+  "apiKeyPrefix": "sk-abc…",
+  "upstreamStatus": 200,
+  "upstreamOk": true
+}
+```
+
+---
+
+## Supported Providers
+
+Any provider implementing the OpenAI Chat Completions API format is supported.
+
+| Provider | Base URL |
+|----------|----------|
+| DeepSeek | `https://api.deepseek.com/v1` |
+| Xiaomi MiMo | `https://api.xiaomimimo.com/v1` |
+| Kimi (Moonshot) | `https://api.moonshot.cn/v1` |
+| Qwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| OpenRouter | `https://openrouter.ai/api/v1` |
+
+> Any OpenAI API-compatible provider should work in principle. If you find a working provider not listed here, PRs are welcome.
+
+---
+
+## Codex CLI Configuration
+
+Add to `~/.codex/config.toml`:
+
+```toml
+model = "deepseek-v4-pro"
+model_provider = "deepseek-transfer"
+
+[model_providers.deepseek-transfer]
+name = "DeepSeek"
+base_url = "http://127.0.0.1:4446/v1"
+wire_api = "responses"
+```
+
+> **Note**: The `base_url` port must match the `codex-transfer` listen port, and `wire_api` must be `"responses"`.
+
+---
+
+## Project Structure
+
+```
+src/
+├── cli.ts         CLI entry — argument parsing, daemon process management, log rotation
+├── server.ts      HTTP server — Hono route registration, request dispatch, proxy instance creation
+├── config.ts      Configuration — multi-source merging, priority control, config file discovery
+├── session.ts     Session state — message history storage, dual-index reasoning cache
+├── translate.ts   Protocol translation — Responses ↔ Chat Completions bidirectional conversion
+├── stream.ts      SSE translation — streaming chunk parsing, event sequence generation, error fallback
+└── types.ts       Type definitions — complete TypeScript types for both APIs
+build.mjs          Build script — esbuild single-file bundling
+```
+
+### Dependency Graph
+
+```
+cli.ts → server.ts → translate.ts + stream.ts → session.ts + types.ts
+                  → config.ts
+```
+
+### Data Flow
+
+```
+                    ┌─────────────┐
+                    │   Config    │ ◄── CLI / ENV / File
+                    └──────┬──────┘
+                           │
+  Codex ──POST──► Server ──┼──► toChatRequest() ──► fetch ──► Upstream
+    ▲              │       │                                    │
+    │              │   SessionStore                             │
+    └──SSE/JSON────┘   (history +                               │
+                        reasoning)  ◄── translateStream() ──────┘
+                                    ◄── fromChatResponse()
+```
+
+---
+
+## Build
+
+```bash
+git clone https://github.com/Icicno/codex-transfer.git
+cd codex-transfer
+npm install
+npm run build        # esbuild bundle + tsc type check
+node dist/codex-transfer.mjs -k
+
+# Or link as a global command
+npm link
+codex-transfer -k
+```
+
+---
+
+## Programmatic Usage
+
+```typescript
+import { createTransfer } from "./src/server.js";
+
+const { app, port } = createTransfer({
+  configPath: "./codex-transfer.json",
+  port: 4446,
+  upstream: "https://api.deepseek.com/v1",
+  apiKey: "sk-...",
+  disableTlsVerify: true,
+});
+```
+
+---
+
+## Changelog
+
+### v0.3.0 (2026-05-08)
+
+- **Token usage**: Extract usage from upstream streaming responses — Codex now correctly displays context utilization (fixes 0% display issue)
+- **Usage details**: Auto-map `cached_tokens` and `reasoning_tokens`, compatible with both OpenAI and DeepSeek upstream formats
+- **Reasoning effort**: Map `reasoning.effort` to DeepSeek `thinking`/`reasoning_effort` and MiMo/Kimi/GLM `thinking` toggle
+- **Config-driven control**: New `--no-reasoning-effort` / `reasoningEffort` option to strip reasoning effort parameters on demand
+
+### v0.2.0 (2026-05-07)
+
+- First npm release
+- Responses API ↔ Chat Completions bidirectional protocol translation
+- Streaming SSE event generation, session management, reasoning model support
+- Model name mapping, daemon mode, log rotation
+- TLS certificate bypass, config file support
+
+---
+
+## License
+
+MIT

package/README.md

@@ -1,51 +1,89 @@
 # codex-transfer
 
-Responses API ↔ Chat Completions translation bridge for Codex CLI (TypeScript implementation)
+[English](./README.en.md) | **中文**
 
-## Overview
+> Responses API ↔ Chat Completions 协议翻译桥接 — 让 Codex CLI 无缝对接 DeepSeek、Kimi、Qwen 等任意 OpenAI 兼容厂商。
 
-A lightweight proxy that translates the OpenAI **Responses API** (used by Codex CLI) into the **Chat Completions API**, letting Codex work with any OpenAI-compatible provider — DeepSeek, Kimi, Qwen, Mistral, Groq, xAI, OpenRouter, and more.
+## 概述
+
+Codex CLI 使用 OpenAI 的 **Responses API** 作为通信协议，而市面上大多数第三方大模型厂商（DeepSeek、Moonshot、Qwen 等）仅实现了早期的 **Chat Completions API**。这两种 API 在请求格式、响应结构、流式事件序列、工具调用表达等方面存在显著差异。
+
+`codex-transfer` 在本地启动一个 HTTP 代理服务，透明地将 Codex CLI 发出的 Responses API 请求翻译为 Chat Completions API 请求，并将上游响应逆向翻译回 Responses API 格式，使 Codex CLI"察觉不到"协议差异。
 
 ```
-Codex CLI (Responses API) → codex-transfer → DeepSeek (Chat Completions API)
+Codex CLI (Responses API)  →  codex-transfer (:4444)  →  第三方厂商 (Chat Completions API)
 ```
 
-## Quick Start
+- **零运行时依赖**：esbuild 打包为单文件 `dist/codex-transfer.mjs`，`npx` 一键运行
+- **无状态**：进程内维护会话，无需外部数据库
+- **约 1500 行 TypeScript**：轻量、可审计
+
+---
+
+## 快速开始
 
 ```bash
-# Install from npm
-npm install -g @classicicn/codex-transfer
+# 一键运行（无需安装）
+npx @classicicn/codex-transfer -k
 
-# Run
+# 指定上游厂商
+npx @classicicn/codex-transfer -k -u https://api.deepseek.com/v1 --api-key sk-xxx
+
+# 全局安装后使用
+npm install -g @classicicn/codex-transfer
 codex-transfer -k
 ```
 
-## CLI Options
+---
+
+## CLI 选项
 
 ```
 codex-transfer [options]
 
-Options:
-  -p, --port PORT        Listen port (default: 4444)
-  -u, --upstream URL     Upstream Chat Completions base URL
-      --api-key KEY      API key for upstream
-  -m, --model MODEL      Force override model name (highest priority)
-  -c, --config PATH      Path to config file (JSON)
-  -k, --insecure         Skip TLS certificate verification
-  -d, --daemon           Run in background, logs to logs/ directory
-  -h, --help             Show this help
+选项：
+  -p, --port PORT        监听端口（默认：4444）
+  -u, --upstream URL     上游 Chat Completions 基础 URL
+      --api-key KEY      上游 API Key
+  -m, --model MODEL      强制覆盖模型名称（最高优先级）
+  -c, --config PATH      配置文件路径（JSON 格式）
+  -k, --insecure         跳过 TLS 证书验证（企业代理/自签证书场景）
+      --no-reasoning-effort  不向上传递 reasoning_effort 参数
+  -d, --daemon           后台运行，日志写入 logs/ 目录
+  -h, --help             显示帮助信息
+```
+
+### 后台运行（Daemon 模式）
+
+```bash
+codex-transfer -d -k -u https://api.deepseek.com/v1 --api-key sk-xxx
+
+# 输出：
+# codex-transfer started in background (PID: 12345)
+# Log file: ~/.codex-transfer/logs/codex-transfer-20260507-143022.log
+# PID file: ~/.codex-transfer/logs/codex-transfer.pid
+# Stop:   kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
 ```
 
-## Configuration
+Daemon 模式自动将 `console` 输出重定向到带时间戳的日志文件，单文件超过 **10MB** 自动轮转，最多保留 **5 个历史文件**。
+
+---
+
+## 配置
+
+### 优先级
+
+```
+CLI 参数 > 环境变量 > 配置文件 > 默认值
+```
 
-Priority: CLI args > environment variables > config file > defaults
+### 配置文件
 
-### Config File
+创建一个 JSON 配置文件，放置在以下任一位置（按搜索顺序）：
 
-Create a JSON config file at one of these locations:
-- `./codex-transfer.json` (current directory)
-- `~/.codex-transfer/config.json` (user home)
-- Custom path via `--config` or `CODEX_TRANSFER_CONFIG`
+1. `--config` 显式路径 或 `CODEX_TRANSFER_CONFIG` 环境变量
+2. `./codex-transfer.json`（当前目录）
+3. `~/.codex-transfer/config.json`（用户主目录）
 
 ```json
 {
@@ -53,15 +91,28 @@ Create a JSON config file at one of these locations:
   "upstream": "https://api.deepseek.com/v1",
   "apiKey": "sk-your-key-here",
   "insecure": false,
+  "reasoningEffort": true,
   "modelMap": {
-    "*": "deepseek-v4-pro"
+    "*": "deepseek-v4-pro",
+    "codex-auto-review": "deepseek-v4-pro"
   }
 }
 ```
 
-### Model Name Mapping
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `CODEX_TRANSFER_PORT` | `4444` | 监听端口 |
+| `CODEX_TRANSFER_UPSTREAM` | `https://openrouter.ai/api/v1` | 上游 Chat Completions 基础 URL |
+| `CODEX_TRANSFER_API_KEY` | _(空)_ | 转发给上游的 API Key |
+| `CODEX_TRANSFER_CONFIG` | _(自动)_ | 配置文件路径 |
+| `CODEX_TRANSFER_INSECURE` | `false` | 设为 `"1"` 或 `"true"` 跳过 TLS 验证 |
+| `CODEX_TRANSFER_REASONING_EFFORT` | `true` | 设为 `"0"` 或 `"false"` 关闭 reasoning_effort 传递 |
+
+### 模型名称映射
 
-Codex CLI may send non-standard model names (e.g. `codex-auto-review`) that the upstream provider doesn't recognize. Use `modelMap` to translate them:
+Codex CLI 可能发送非标准模型名（如 `codex-auto-review`），上游厂商无法识别。使用 `modelMap` 进行翻译：
 
 ```json
 {
@@ -72,68 +123,241 @@ Codex CLI may send non-standard model names (e.g. `codex-auto-review`) that the
 }
 ```
 
-Lookup order: exact key match → wildcard `"*"` → original name (passthrough).
+**查找顺序**：精确键匹配 → 通配符 `"*"` → 原名称透传。
 
-Or use `--model` CLI flag to force-override all model names:
+`--model` / `-m` 参数优先级高于 `modelMap`，可强制覆盖所有模型名。
+
+---
+
+## API 端点
+
+| 方法 | 路径 | 功能 |
+|------|------|------|
+| `GET` | `/health` | 健康检查 — 测试上游 `/models` 连通性，返回诊断信息 |
+| `GET` | `/v1/models` | 模型列表代理 — 透明转发上游模型目录 |
+| `POST` | `/v1/responses` | **核心端点** — 接收 Responses API 请求，翻译后转发上游 |
+
+### `/v1/responses` 处理流程
 
-```bash
-codex-transfer --model deepseek-v4-pro -k
+```
+Codex 请求到达
+  → JSON 解析 & 校验
+  → resolveModel() 模型名映射
+  → 加载历史消息（通过 previous_response_id）
+  → toChatRequest() 协议翻译
+  → 分流：
+     ├─ stream=true  → translateStream() SSE 生成器 → text/event-stream
+     └─ stream=false → fetch 上游 → fromChatResponse() → JSON
 ```
 
-### Environment Variables
+---
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CODEX_TRANSFER_PORT` | `4444` | Listen port |
-| `CODEX_TRANSFER_UPSTREAM` | `https://openrouter.ai/api/v1` | Upstream Chat Completions base URL |
-| `CODEX_TRANSFER_API_KEY` | _(empty)_ | API key forwarded to upstream |
-| `CODEX_TRANSFER_CONFIG` | _(auto)_ | Path to config file |
-| `CODEX_TRANSFER_INSECURE` | `false` | Skip TLS certificate verification |
+## 功能详解
 
-## Usage
+### 协议翻译
 
-### Method 1: Direct execution
+完整实现 Responses API 与 Chat Completions API 之间的双向转换：
 
-```bash
-node dist/codex-transfer.mjs -k -p 4446 -u https://api.deepseek.com/v1
+- **请求翻译**：`input` 数组（`function_call` / `function_call_output` / 普通消息）→ Chat Completions `messages[]` 数组
+- **响应翻译**：Chat Completions `choices[0].message` → Responses API `output[]` 结构
+- **系统提示**：`instructions`（Codex CLI 字段）→ Chat Completions `system` 角色
+- **角色映射**：`developer` → `system`
+
+### 流式翻译（SSE）
+
+上游 Chat Completions 的 SSE 增量流被逐 chunk 翻译为 Responses API 标准事件序列：
+
+```
+response.created
+  → response.output_item.added (message)
+  → response.output_text.delta × N
+  → response.output_item.done
+  → [如有工具调用]
+     response.output_item.added (function_call)
+     → response.function_call_arguments.delta
+     → response.output_item.done
+  → response.completed
 ```
 
-### Method 2: npm link (global command)
+**设计要点**：
+- 文本 delta 实时透传，工具调用 delta 在流结束后批量封装（因 Chat Completions 的 tool call 按 index 散落在多个 chunk 中）
+- 顶层异常兜底：即使上游异常断开，也会产出 `response.failed` 事件，确保 Codex CLI 不会挂起等待
+
+### Token 用量详情
+
+Codex CLI 依赖 Responses API 中的 usage 字段计算上下文占用率。`codex-transfer` 自动提取上游响应中的用量信息并映射到 Responses API 格式，同时兼容 OpenAI 和 DeepSeek 两种上游格式差异：
+
+| Responses API 输出 | OpenAI 上游字段 | DeepSeek 上游字段 |
+|---|---|---|
+| `input_tokens` | `prompt_tokens` | `prompt_tokens` |
+| `output_tokens` | `completion_tokens` | `completion_tokens` |
+| `total_tokens` | `total_tokens` | `total_tokens` |
+| `input_tokens_details.cached_tokens` | `prompt_tokens_details.cached_tokens` | `prompt_cache_hit_tokens` |
+| `output_tokens_details.reasoning_tokens` | `completion_tokens_details.reasoning_tokens` | `completion_tokens_details.reasoning_tokens` |
+
+**自动格式检测**：根据上游响应中实际存在的字段自动判断格式，无需配置。`cached_tokens` 优先取 OpenAI 嵌套字段，无则取 DeepSeek 顶层字段；`reasoning_tokens` 两者路径一致直接取值。字段不存在时不会输出对应的 `details` 对象。
+
+非流式和流式路径共享同一套映射逻辑。
+
+### 推理强度映射（Reasoning Effort）
+
+Codex CLI 通过 `reasoning.effort` 控制模型推理强度（极低/低/中/高/超高），但各厂商的实现方式不同。`codex-transfer` 自动将 Responses API 的推理强度映射为各厂商可识别的参数：
+
+| Codex 等级 | Responses API 值 | DeepSeek | MiMo / Kimi / GLM |
+|---|---|---|---|
+| 极低 | `none` | `thinking: {type: "disabled"}` | `thinking: {type: "disabled"}` |
+| 低 | `low` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| 中 | `medium` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| 高 | `high` | `thinking: {type: "enabled"}, reasoning_effort: "high"` | `thinking: {type: "enabled"}` |
+| 超高 | `xhigh` | `thinking: {type: "enabled"}, reasoning_effort: "max"` | `thinking: {type: "enabled"}` |
+
+**兼容策略**：`thinking` 参数始终发送（所有厂商支持）。`reasoning_effort` 默认发送（DeepSeek 原生支持）；如果上游不支持该字段，可通过 `--no-reasoning-effort` CLI 参数或配置文件 `"reasoningEffort": false` 关闭。
+
+### 会话管理
+
+Codex CLI 通过 `previous_response_id` 实现多轮对话。`SessionStore` 在内存中维护每个会话的完整消息历史，使得每次 Chat Completions 调用都是**自包含**的（无需依赖上游的上下文缓存）。
 
-```bash
-npm link
-# Then run directly
-codex-transfer -k
+```
+┌─────────────────────────────────┐
+│  SessionStore (内存)             │
+│                                 │
+│  history:  Map<response_id,     │
+│                 ChatMessage[]>   │
+│                                 │
+│  reasoning: Map<call_id,        │
+│                 reasoning_text>  │
+│                                 │
+│  turnReasoning: Map<            │
+│    SHA256(content),              │
+│    reasoning_text>               │
+│  )                              │
+└─────────────────────────────────┘
 ```
 
-### Method 3: npx
+### 推理模型支持（DeepSeek-R1 / Kimi-K2.6）
 
-```bash
-npx @classicicn/codex-transfer -k
+推理模型会产出 `reasoning_content`（思考过程），该字段需要在多轮对话中**原样回传**，否则模型会拒绝或行为异常。
+
+`codex-transfer` 使用**双索引缓存**来恢复推理内容：
+
+| 索引方式 | 适用场景 | 实现 |
+|----------|---------|------|
+| **call_id 精确匹配** | Codex 使用 `previous_response_id` + tool call 重放 | `Map<call_id, reasoning>` |
+| **内容 SHA256 指纹** | Codex 完整重放 `input[]` 而不使用 `previous_response_id` | `Map<SHA256(content), reasoning>` |
+
+两种机制互为补充，覆盖 Codex CLI 的两种对话重放模式。
+
+### 工具调用处理
+
+- **工具过滤**：自动过滤 `web_search`、`file_search`、`computer` 等 OpenAI 专有内置工具，仅保留 `type: "function"` 的自定义工具，避免第三方厂商拒绝请求
+- **格式转换**：Responses API 扁平格式 `{type, name, description, parameters}` ↔ Chat Completions 嵌套格式 `{type, function: {name, description, parameters}}`
+- **并行工具调用**：连续多个 `function_call` 输入项合并为一条 assistant 消息中的多个 `tool_calls` 条目
+- **消息重排序**：Codex 可能在 `function_call` 和 `function_call_output` 之间插入其他消息，但 DeepSeek 等厂商严格要求 `assistant(tool_calls)` 后紧跟匹配的 `tool` 消息。`reorderForToolCalls()` 自动重排，孤立的 tool call 自动合成空输出
+
+### 健康检查
+
+```
+GET /health → 200 OK
+{
+  "upstream": "https://api.deepseek.com/v1",
+  "apiKeySet": true,
+  "apiKeyPrefix": "sk-abc…",
+  "upstreamStatus": 200,
+  "upstreamOk": true
+}
 ```
 
-### Method 4: Background (daemon) mode
+---
 
-```bash
-# Start as background process (logs → config_dir/logs/)
-node dist/codex-transfer.mjs -d -k
+## 支持的厂商
 
-# Output:
-# codex-transfer started in background (PID: 12345)
-# Log file: ~/.codex-transfer/logs/codex-transfer.log
-# PID file: ~/.codex-transfer/logs/codex-transfer.pid
-# Stop:   kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
+任意实现 OpenAI Chat Completions API 格式的厂商均可使用。
+
+| 厂商 | 基础 URL |
+|------|----------|
+| DeepSeek | `https://api.deepseek.com/v1` |
+| 小米 MiMo | `https://api.xiaomimimo.com/v1` |
+| Kimi (Moonshot) | `https://api.moonshot.cn/v1` |
+| Qwen (通义千问) | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| OpenRouter | `https://openrouter.ai/api/v1` |
 
-# View logs
-tail -f ~/.codex-transfer/logs/codex-transfer.log
+> 任何 OpenAI API 兼容的厂商理论上均可正常工作。如果发现未列出的可用厂商，欢迎提交 PR。
 
-# Stop
-kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
+---
+
+## Codex CLI 配置
+
+在 `~/.codex/config.toml` 中添加：
+
+```toml
+model = "deepseek-v4-pro"
+model_provider = "deepseek-transfer"
+
+[model_providers.deepseek-transfer]
+name = "DeepSeek"
+base_url = "http://127.0.0.1:4446/v1"
+wire_api = "responses"
 ```
 
-### Method 5: As a library (from source only)
+> **注意**：`base_url` 端口需与 `codex-transfer` 监听端口一致，`wire_api` 必须为 `"responses"`。
+
+---
 
-> **Note:** The npm package contains only the CLI bundle. To use as a library, clone the repo and import from source.
+## 项目结构
+
+```
+src/
+├── cli.ts         CLI 入口 — 参数解析、daemon 进程管理、日志轮转
+├── server.ts      HTTP 服务 — Hono 路由注册、请求调度、创建代理实例
+├── config.ts      配置管理 — 多来源合并、优先级控制、配置文件搜索
+├── session.ts     会话状态 — 消息历史存储、推理内容双索引缓存
+├── translate.ts   协议翻译 — Responses ↔ Chat Completions 双向转换
+├── stream.ts      SSE 翻译 — 流式 chunk 解析、事件序列生成、错误兜底
+└── types.ts       类型定义 — 两套 API 的完整 TypeScript 类型
+build.mjs          构建脚本 — esbuild 打包为单文件
+```
+
+### 依赖关系
+
+```
+cli.ts → server.ts → translate.ts + stream.ts → session.ts + types.ts
+                  → config.ts
+```
+
+### 数据流
+
+```
+                    ┌─────────────┐
+                    │   Config    │ ◄── CLI / ENV / File
+                    └──────┬──────┘
+                           │
+  Codex ──POST──► Server ──┼──► toChatRequest() ──► fetch ──► Upstream
+    ▲              │       │                                    │
+    │              │   SessionStore                             │
+    └──SSE/JSON────┘   (history +                               │
+                        reasoning)  ◄── translateStream() ──────┘
+                                    ◄── fromChatResponse()
+```
+
+---
+
+## 构建
+
+```bash
+git clone https://github.com/Icicno/codex-transfer.git
+cd codex-transfer
+npm install
+npm run build        # esbuild 打包 + tsc 类型检查
+node dist/codex-transfer.mjs -k
+
+# 或链接为全局命令
+npm link
+codex-transfer -k
+```
+
+---
+
+## 程序化使用
 
 ```typescript
 import { createTransfer } from "./src/server.js";
@@ -147,58 +371,26 @@ const { app, port } = createTransfer({
 });
 ```
 
-## Codex Configuration
+---
 
-Add to `~/.codex/config.toml`:
+## 更新日志
 
-```toml
-model = "deepseek-v4-pro"
-model_provider = "deepseek-transfer"
+### v0.3.0 (2026-05-08)
 
-[model_providers.deepseek-transfer]
-name = "DeepSeek"
-base_url = "http://127.0.0.1:4446/v1"
-wire_api = "responses"
-```
+- **Token 用量**：从上游流式响应中提取 usage，Codex 可正确显示上下文占用率（修复 0% 问题）
+- **用量详情**：自动映射 `cached_tokens` 和 `reasoning_tokens`，兼容 OpenAI 和 DeepSeek 两种上游格式
+- **推理强度**：映射 `reasoning.effort` 到 DeepSeek `thinking`/`reasoning_effort`、MiMo/Kimi/GLM `thinking` 开关
+- **配置化控制**：新增 `--no-reasoning-effort` / `reasoningEffort` 配置项，按需剥离推理强度参数
 
-## Supported Providers
+### v0.2.0 (2026-05-07)
 
-| Provider | Base URL |
-|----------|----------|
-| DeepSeek | `https://api.deepseek.com/v1` |
-| Kimi (Moonshot) | `https://api.moonshot.cn/v1` |
-| Qwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-| Mistral | `https://api.mistral.ai/v1` |
-| Groq | `https://api.groq.com/openai/v1` |
-| xAI | `https://api.x.ai/v1` |
-| OpenRouter | `https://openrouter.ai/api/v1` |
+- 首次 npm 发布
+- Responses API ↔ Chat Completions 双向协议翻译
+- 流式 SSE 事件序列生成、会话管理、推理模型支持
+- 模型名称映射、Daemon 模式、日志轮转
+- TLS 证书跳过、配置文件支持
 
-## Features
-
-- **Single-file bundle** — `dist/codex-transfer.mjs` has zero runtime dependencies
-- **Streaming** — full SSE streaming with correct event sequencing
-- **Tool calls** — accumulates streaming deltas and emits structured function_call items
-- **Parallel tool calls** — consecutive function_call input items merged into one assistant message
-- **Tool call message ordering** — automatically reorders messages to ensure `assistant(tool_calls)` is immediately followed by matching `tool` messages (required by DeepSeek and other strict providers)
-- **Model name mapping** — maps non-standard Codex model names (e.g. `codex-auto-review`) to upstream provider models via `modelMap` config or `--model` flag
-- **Reasoning models** — preserves `reasoning_content` across turns (DeepSeek, kimi-k2.6)
-- **Model catalog** — proxies `/v1/models` from the upstream provider
-- **Health check** — `GET /health` diagnostic endpoint
-- **TLS skip** — supports corporate proxy / self-signed certificate scenarios
-- **Daemon mode** — `--daemon` runs in background with logs to `logs/` directory next to config file
-
-## Project Structure
-
-| File | Description |
-|------|-------------|
-| `src/types.ts` | Responses/Chat Completions API type definitions |
-| `src/config.ts` | Configuration loading (file + env vars) |
-| `src/session.ts` | Session store and reasoning content cache |
-| `src/translate.ts` | Request/response translation logic |
-| `src/stream.ts` | SSE stream translation |
-| `src/server.ts` | HTTP server (Hono) |
-| `src/cli.ts` | CLI entry point |
-| `build.mjs` | esbuild bundler script |
+---
 
 ## License
 

package/dist/codex-transfer.mjs

@@ -2975,13 +2975,26 @@ function toChatRequest(req, history, sessions) {
   }
   const filteredTools = (req.tools ?? []).filter((t) => t.type === "function").map(convertTool);
   const reordered = reorderForToolCalls(messages);
+  const reasoningFields = mapReasoningEffort(req.reasoning?.effort);
   return {
     model: req.model,
     messages: reordered,
     ...filteredTools.length > 0 ? { tools: filteredTools } : {},
     ...req.temperature != null ? { temperature: req.temperature } : {},
     ...req.max_output_tokens != null ? { max_tokens: req.max_output_tokens } : {},
-    stream: req.stream ?? false
+    stream: req.stream ?? false,
+    ...reasoningFields
+  };
+}
+function mapReasoningEffort(effort) {
+  if (!effort) return {};
+  if (effort === "none") {
+    return { thinking: { type: "disabled" } };
+  }
+  const reasoningEffort = effort === "xhigh" ? "max" : "high";
+  return {
+    thinking: { type: "enabled" },
+    reasoning_effort: reasoningEffort
   };
 }
 function convertTool(tool) {
@@ -3013,11 +3026,7 @@ function fromChatResponse(id, model, chat) {
       content: [{ type: "output_text", text }]
     }
   ];
-  const respUsage = {
-    input_tokens: usage.prompt_tokens,
-    output_tokens: usage.completion_tokens,
-    total_tokens: usage.total_tokens
-  };
+  const respUsage = mapUsage(usage);
   const response = {
     id,
     object: "response",
@@ -3027,6 +3036,22 @@ function fromChatResponse(id, model, chat) {
   };
   return { response, assistantMessage: choice.message };
 }
+function mapUsage(usage) {
+  const cachedTokens = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens;
+  const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens;
+  const result = {
+    input_tokens: usage.prompt_tokens,
+    output_tokens: usage.completion_tokens,
+    total_tokens: usage.total_tokens
+  };
+  if (cachedTokens != null) {
+    result.input_tokens_details = { cached_tokens: cachedTokens };
+  }
+  if (reasoningTokens != null) {
+    result.output_tokens_details = { reasoning_tokens: reasoningTokens };
+  }
+  return result;
+}
 function valueToText(v) {
   if (v == null) return "";
   if (typeof v === "string") return v;
@@ -3147,6 +3172,7 @@ async function* translateStream(args2, signal) {
     const toolCalls = /* @__PURE__ */ new Map();
     let emittedMessageItem = false;
     let done = false;
+    let streamUsage;
     const reader = upstream.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -3187,6 +3213,9 @@ async function* translateStream(args2, signal) {
               if (err) {
                 console.error(`[transfer] upstream error in stream:`, err);
               }
+              if (chunk.usage) {
+                streamUsage = chunk.usage;
+              }
               for (const choice of chunk.choices ?? []) {
                 const rc = choice.delta?.reasoning_content;
                 if (rc) {
@@ -3350,7 +3379,7 @@ async function* translateStream(args2, signal) {
         status: "completed",
         model,
         output: outputItems,
-        usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 }
+        usage: streamUsage ? mapUsage(streamUsage) : { input_tokens: 0, output_tokens: 0, total_tokens: 0 }
       }
     });
     console.log(`[transfer] stream completed: ${accumulatedText.length} chars, ${toolCalls.size} tool calls`);
@@ -3387,7 +3416,8 @@ var DEFAULT_CONFIG = {
   upstream: "https://openrouter.ai/api/v1",
   apiKey: "",
   insecure: false,
-  modelMap: {}
+  modelMap: {},
+  reasoningEffort: true
 };
 function loadConfig(configPath) {
   const fileConfig = loadConfigFile(configPath);
@@ -3398,7 +3428,10 @@ function loadConfig(configPath) {
     insecure: parseBool(
       process.env.CODEX_TRANSFER_INSECURE ?? fileConfig.insecure
     ),
-    modelMap: fileConfig.modelMap ?? DEFAULT_CONFIG.modelMap
+    modelMap: fileConfig.modelMap ?? DEFAULT_CONFIG.modelMap,
+    reasoningEffort: parseBool(
+      process.env.CODEX_TRANSFER_REASONING_EFFORT ?? fileConfig.reasoningEffort ?? true
+    )
   };
 }
 function loadConfigFile(explicitPath) {
@@ -3422,7 +3455,8 @@ function loadConfigFile(explicitPath) {
           upstream: typeof parsed.upstream === "string" ? parsed.upstream : void 0,
           apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
           insecure: typeof parsed.insecure === "boolean" ? parsed.insecure : void 0,
-          modelMap: typeof parsed.modelMap === "object" && parsed.modelMap !== null ? parsed.modelMap : void 0
+          modelMap: typeof parsed.modelMap === "object" && parsed.modelMap !== null ? parsed.modelMap : void 0,
+          reasoningEffort: typeof parsed.reasoningEffort === "boolean" ? parsed.reasoningEffort : void 0
         };
       } catch {
       }
@@ -3527,6 +3561,9 @@ function createTransfer(options = {}) {
     const history = req.previous_response_id ? sessions.getHistory(req.previous_response_id) : [];
     const chatReq = toChatRequest(req, history, sessions);
     chatReq.model = model;
+    if (!fileConfig.reasoningEffort) {
+      delete chatReq.reasoning_effort;
+    }
     const url = `${upstream}/chat/completions`;
     if (req.stream) {
       const responseId = sessions.newId();
@@ -3637,6 +3674,8 @@ for (let i = 0; i < args.length; i++) {
     overrides.configPath = args[++i];
   } else if ((a === "--model" || a === "-m") && args[i + 1]) {
     overrides.model = args[++i];
+  } else if (a === "--no-reasoning-effort") {
+    overrides.reasoningEffort = "false";
   } else if (a === "--help" || a === "-h") {
     console.log(`
 codex-transfer \u2014 Responses API \u2194 Chat Completions bridge
@@ -3651,6 +3690,7 @@ Options:
   -m, --model MODEL      Override model name (highest priority model mapping)
   -c, --config PATH      Path to config file (JSON)
   -k, --insecure         Skip TLS certificate verification
+      --no-reasoning-effort  Don't send reasoning_effort to upstream
   -d, --daemon           Run in background, logs to logs/ directory
   -h, --help             Show this help
 
@@ -3660,6 +3700,7 @@ Environment variables:
   CODEX_TRANSFER_API_KEY      Same as --api-key
   CODEX_TRANSFER_CONFIG       Same as --config
   CODEX_TRANSFER_INSECURE     Set to "1" to skip TLS verification
+  CODEX_TRANSFER_REASONING_EFFORT  Set to "0" to disable reasoning_effort
 
 Config file options:
   modelMap               Model name mapping, e.g. {"*": "deepseek-v4-pro"}
@@ -3735,6 +3776,9 @@ if (logFile) {
 }
 var rotateIfNeeded2;
 var logWrite2;
+if (overrides.reasoningEffort) {
+  process.env.CODEX_TRANSFER_REASONING_EFFORT = overrides.reasoningEffort;
+}
 var { app, port } = createTransfer({
   configPath: overrides.configPath,
   port: overrides.port ? Number(overrides.port) : void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classicicn/codex-transfer",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Responses API ↔ Chat Completions translation bridge for Codex — use DeepSeek, Kimi, Qwen, and other providers with Codex",
   "type": "module",
   "main": "dist/codex-transfer.mjs",
@@ -10,7 +10,7 @@
   "files": [
     "dist/codex-transfer.mjs",
     "README.md",
-    "README.zh-CN.md",
+    "README.en.md",
     "LICENSE"
   ],
   "scripts": {

package/README.zh-CN.md

@@ -1,205 +0,0 @@
-# codex-transfer
-
-Responses API ↔ Chat Completions 转换桥（TypeScript 实现）
-
-## 概述
-
-一个轻量级代理，用于将 OpenAI **Responses API**（Codex CLI 使用）转换为 **Chat Completions API**，让 Codex 能够与任何 OpenAI 兼容的提供商配合使用——DeepSeek、Kimi、Qwen、Mistral、Groq、xAI、OpenRouter 等。
-
-```
-Codex CLI (Responses API) → codex-transfer → DeepSeek (Chat Completions API)
-```
-
-## 快速开始
-
-```bash
-# 从 npm 安装
-npm install -g @classicicn/codex-transfer
-
-# 启动
-codex-transfer -k
-```
-
-## 命令行参数
-
-```
-codex-transfer [options]
-
-Options:
-  -p, --port PORT        监听端口（默认 4444）
-  -u, --upstream URL     上游 Chat Completions 地址
-      --api-key KEY      上游 API 密钥
-  -m, --model MODEL      强制覆盖模型名（最高优先级）
-  -c, --config PATH      配置文件路径（JSON）
-  -k, --insecure         跳过 TLS 证书验证
-  -d, --daemon           后台运行，日志输出到 logs/ 目录
-  -h, --help             显示帮助
-```
-
-## 配置
-
-配置优先级：CLI 参数 > 环境变量 > 配置文件 > 默认值
-
-### 配置文件
-
-在以下位置之一创建 JSON 配置文件：
-- `./codex-transfer.json`（当前目录）
-- `~/.codex-transfer/config.json`（用户主目录）
-- 通过 `--config` 或 `CODEX_TRANSFER_CONFIG` 指定
-
-```json
-{
-  "port": 4446,
-  "upstream": "https://api.deepseek.com/v1",
-  "apiKey": "sk-your-key-here",
-  "insecure": false,
-  "modelMap": {
-    "*": "deepseek-v4-pro"
-  }
-}
-```
-
-### 模型名映射
-
-Codex CLI 可能发送上游不识别的模型名（如 `codex-auto-review`）。使用 `modelMap` 进行转换：
-
-```json
-{
-  "modelMap": {
-    "*": "deepseek-v4-pro",
-    "codex-auto-review": "deepseek-v4-pro"
-  }
-}
-```
-
-查找顺序：精确匹配 key → 通配符 `"*"` → 原始模型名（直接透传）。
-
-也可使用 `--model` CLI 参数强制覆盖所有模型名：
-
-```bash
-codex-transfer --model deepseek-v4-pro -k
-```
-
-### 环境变量
-
-| 变量名 | 默认值 | 说明 |
-|--------|--------|------|
-| `CODEX_TRANSFER_PORT` | `4444` | 监听端口 |
-| `CODEX_TRANSFER_UPSTREAM` | `https://openrouter.ai/api/v1` | 上游 Chat Completions 地址 |
-| `CODEX_TRANSFER_API_KEY` | _(空)_ | 上游 API 密钥 |
-| `CODEX_TRANSFER_CONFIG` | _(自动)_ | 配置文件路径 |
-| `CODEX_TRANSFER_INSECURE` | `false` | 跳过 TLS 验证 |
-
-## 使用方式
-
-### 方式一：直接运行打包产物
-
-```bash
-node dist/codex-transfer.mjs -k -p 4446 -u https://api.deepseek.com/v1
-```
-
-### 方式二：npm link（全局命令）
-
-```bash
-npm link
-# 之后可直接执行
-codex-transfer -k
-```
-
-### 方式三：npx
-
-```bash
-npx @classicicn/codex-transfer -k
-```
-
-### 方式四：后台运行
-
-```bash
-# 启动后台进程（日志输出到配置文件同级 logs/ 目录）
-node dist/codex-transfer.mjs -d -k
-
-# 输出示例：
-# codex-transfer started in background (PID: 12345)
-# Log file: ~/.codex-transfer/logs/codex-transfer.log
-# PID file: ~/.codex-transfer/logs/codex-transfer.pid
-# Stop:   kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
-
-# 查看日志
-tail -f ~/.codex-transfer/logs/codex-transfer.log
-
-# 停止
-kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
-```
-
-### 方式五：作为库使用（仅限源码）
-
-> **注意：** npm 包仅包含 CLI 打包产物。如需作为库使用，请 clone 仓库后从源码导入。
-
-```typescript
-import { createTransfer } from "./src/server.js";
-
-const { app, port } = createTransfer({
-  configPath: "./codex-transfer.json",
-  port: 4446,
-  upstream: "https://api.deepseek.com/v1",
-  apiKey: "sk-...",
-  disableTlsVerify: true,
-});
-```
-
-## Codex 配置
-
-在 `~/.codex/config.toml` 中添加：
-
-```toml
-model = "deepseek-v4-pro"
-model_provider = "deepseek-transfer"
-
-[model_providers.deepseek-transfer]
-name = "DeepSeek"
-base_url = "http://127.0.0.1:4446/v1"
-wire_api = "responses"
-```
-
-## 支持的提供商
-
-| 提供商 | 基础 URL |
-|--------|----------|
-| DeepSeek | `https://api.deepseek.com/v1` |
-| Kimi (Moonshot) | `https://api.moonshot.cn/v1` |
-| Qwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-| Mistral | `https://api.mistral.ai/v1` |
-| Groq | `https://api.groq.com/openai/v1` |
-| xAI | `https://api.x.ai/v1` |
-| OpenRouter | `https://openrouter.ai/api/v1` |
-
-## 功能特性
-
-- **单文件打包** — `dist/codex-transfer.mjs` 无外部依赖，拷贝即用
-- **流式传输** — 完整的 SSE 流式传输，正确的事件排序
-- **工具调用** — 累积流式增量并发出结构化的 function_call 项目
-- **并行工具调用** — 连续的 function_call 输入项目合并为单个 assistant 消息
-- **工具调用消息排序** — 自动重排消息，确保 `assistant(tool_calls)` 后紧跟对应的 `tool` 消息（DeepSeek 等严格提供商要求）
-- **模型名映射** — 将 Codex 非标准模型名（如 `codex-auto-review`）映射到上游提供商模型，支持 `modelMap` 配置或 `--model` 参数
-- **推理模型** — 跨轮次保留 `reasoning_content`（DeepSeek、kimi-k2.6）
-- **模型目录** — 代理上游的 `/v1/models` 端点
-- **健康检查** — `GET /health` 诊断上游连接状态
-- **TLS 跳过** — 支持企业代理/自签名证书场景
-- **后台运行** — `--daemon` 后台运行，日志输出到配置文件同级 `logs/` 目录
-
-## 项目架构
-
-| 文件 | 说明 |
-|------|------|
-| `src/types.ts` | Responses/Chat Completions API 类型定义 |
-| `src/config.ts` | 配置加载（配置文件 + 环境变量） |
-| `src/session.ts` | 会话存储与推理内容缓存 |
-| `src/translate.ts` | 请求/响应转换逻辑 |
-| `src/stream.ts` | SSE 流式转换 |
-| `src/server.ts` | HTTP 服务（Hono） |
-| `src/cli.ts` | CLI 入口 |
-| `build.mjs` | esbuild 打包脚本 |
-
-## 许可证
-
-MIT