@classicicn/codex-transfer 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cbq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# codex-transfer
+
+Responses API ↔ Chat Completions translation bridge for Codex CLI (TypeScript implementation)
+
+## Overview
+
+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 (Responses API) → codex-transfer → DeepSeek (Chat Completions API)
+```
+
+## Quick Start
+
+```bash
+# Install from npm
+npm install -g @classicicn/codex-transfer
+
+# Run
+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
+  -d, --daemon           Run in background, logs to logs/ directory
+  -h, --help             Show this help
+```
+
+## Configuration
+
+Priority: CLI args > environment variables > config file > defaults
+
+### Config File
+
+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`
+
+```json
+{
+  "port": 4446,
+  "upstream": "https://api.deepseek.com/v1",
+  "apiKey": "sk-your-key-here",
+  "insecure": false,
+  "modelMap": {
+    "*": "deepseek-v4-pro"
+  }
+}
+```
+
+### Model Name Mapping
+
+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:
+
+```json
+{
+  "modelMap": {
+    "*": "deepseek-v4-pro",
+    "codex-auto-review": "deepseek-v4-pro"
+  }
+}
+```
+
+Lookup order: exact key match → wildcard `"*"` → original name (passthrough).
+
+Or use `--model` CLI flag to force-override all model names:
+
+```bash
+codex-transfer --model deepseek-v4-pro -k
+```
+
+### 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
+
+```bash
+node dist/codex-transfer.mjs -k -p 4446 -u https://api.deepseek.com/v1
+```
+
+### Method 2: npm link (global command)
+
+```bash
+npm link
+# Then run directly
+codex-transfer -k
+```
+
+### Method 3: npx
+
+```bash
+npx @classicicn/codex-transfer -k
+```
+
+### 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)
+
+# View logs
+tail -f ~/.codex-transfer/logs/codex-transfer.log
+
+# Stop
+kill $(cat ~/.codex-transfer/logs/codex-transfer.pid)
+```
+
+### Method 5: As a library (from source only)
+
+> **Note:** The npm package contains only the CLI bundle. To use as a library, clone the repo and import from source.
+
+```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 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"
+```
+
+## Supported Providers
+
+| 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` |
+
+## 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
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,205 @@
+# 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