Skip to content

Commit 2fb7529

Browse files
239573049239573049
committed
docs: add open source readmes
1 parent 6a0551a commit 2fb7529

2 files changed

Lines changed: 382 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# CodexSwitch
2+
3+
[English](README.md) | [简体中文](README.zh-CN.md)
4+
5+
[![GitHub stars](https://img.shields.io/github/stars/AIDotNet/CodexSwitch?style=social)](https://github.com/AIDotNet/CodexSwitch/stargazers)
6+
[![CI](https://github.com/AIDotNet/CodexSwitch/actions/workflows/ci.yml/badge.svg)](https://github.com/AIDotNet/CodexSwitch/actions/workflows/ci.yml)
7+
[![.NET 10](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/)
8+
[![Avalonia](https://img.shields.io/badge/Avalonia-12.0.3-8B44AC)](https://avaloniaui.net/)
9+
10+
CodexSwitch is a cross-platform Avalonia desktop app that turns Codex into a local, switchable AI provider workstation. It runs an OpenAI Responses-compatible proxy on your machine, writes a managed Codex configuration, routes requests across multiple upstream providers, converts protocol dialects when needed, and keeps local usage and cost records.
11+
12+
The default local endpoint is:
13+
14+
```text
15+
http://127.0.0.1:12785/v1
16+
```
17+
18+
## What It Does
19+
20+
Codex talks to CodexSwitch as if it were an OpenAI Responses API endpoint. CodexSwitch then selects the right provider for the requested model, rewrites model and service-tier settings, converts requests and streaming responses for providers that use different APIs, and records token usage in a local JSONL log.
21+
22+
```mermaid
23+
flowchart LR
24+
Codex["Codex client"] --> Proxy["CodexSwitch local /v1 proxy"]
25+
Proxy --> Router["Provider and model routing"]
26+
Router --> OpenAI["OpenAI Responses"]
27+
Router --> Chat["OpenAI-compatible Chat"]
28+
Router --> Anthropic["Anthropic Messages"]
29+
OpenAI --> Usage["Usage and cost log"]
30+
Chat --> Usage
31+
Anthropic --> Usage
32+
```
33+
34+
## Features
35+
36+
- Local proxy with `/health`, `/v1/models`, and `/v1/responses` endpoints.
37+
- One-click active provider switching from the desktop UI.
38+
- Built-in provider templates for RoutinAI, RoutinAI Plan, OpenAI Official, Anthropic Messages, DeepSeek, and Xiaomi MiMo.
39+
- Dedicated Codex OAuth login flow for the ChatGPT Codex backend, including multi-account management.
40+
- Custom provider support with configurable base URL, API key, protocol, model routes, upstream model names, and service tiers.
41+
- Protocol adapters for OpenAI Responses, OpenAI-compatible Chat Completions, and Anthropic Messages.
42+
- Streaming support with Responses-style SSE events where the upstream protocol allows it.
43+
- Model routing by requested model, including aliases and upstream model remapping.
44+
- Local model pricing catalog with tiered pricing, cache-read pricing, Claude cache-creation billing, and fast-mode multipliers.
45+
- Usage dashboard with request logs, provider statistics, model statistics, 24-hour, 7-day, and 30-day trends.
46+
- Managed Codex config and auth file writing with backup and restore support.
47+
- Light, dark, and system themes with localized UI resources.
48+
- GitHub Release update checks from inside the app.
49+
50+
## Supported Protocols
51+
52+
| Provider protocol | Upstream endpoint | Notes |
53+
| --- | --- | --- |
54+
| `OpenAiResponses` | `/responses` | Passes Responses requests through with model, service-tier, and request override handling. |
55+
| `OpenAiChat` | `/chat/completions` | Converts inbound Responses requests to Chat Completions and converts the result back to Responses shape. |
56+
| `AnthropicMessages` | `/messages` | Converts inbound Responses requests to Anthropic Messages, including tool calls, thinking/reasoning mapping, and usage normalization where supported. |
57+
58+
CodexSwitch currently exposes Responses-style inbound routes. It does not expose `/v1/chat/completions` as a public inbound API.
59+
60+
## Built-In Providers
61+
62+
| Provider | Default protocol | Example default model |
63+
| --- | --- | --- |
64+
| RoutinAI | OpenAI Responses | `gpt-5.5` |
65+
| RoutinAI Plan | OpenAI Responses | `gpt-5.5` |
66+
| OpenAI Official | OpenAI Responses | `gpt-5.5` |
67+
| Anthropic Messages | Anthropic Messages | `claude-sonnet-4-5` |
68+
| DeepSeek | OpenAI Chat | `deepseek-v4-flash` |
69+
| Xiaomi MiMo | OpenAI Chat | `mimo-v2.5-pro` |
70+
| Codex OAuth | OpenAI Responses | `gpt-5.1-codex` |
71+
72+
You can add custom providers when an upstream service is OpenAI Responses-compatible, OpenAI Chat-compatible, or Anthropic Messages-compatible.
73+
74+
## Installation
75+
76+
Download published builds from [GitHub Releases](https://github.com/AIDotNet/CodexSwitch/releases) when release artifacts are available.
77+
78+
Current CI publish targets are:
79+
80+
- `win-x64`
81+
- `linux-x64`
82+
- `osx-x64`
83+
- `osx-arm64`
84+
85+
## Run From Source
86+
87+
Prerequisite: .NET SDK `10.0.203`, as pinned by `global.json`.
88+
89+
```powershell
90+
git clone https://github.com/AIDotNet/CodexSwitch.git
91+
cd CodexSwitch
92+
dotnet restore CodexSwitch.Tests/CodexSwitch.Tests.csproj
93+
dotnet run --project CodexSwitch/CodexSwitch.csproj
94+
```
95+
96+
## First Run
97+
98+
1. Open CodexSwitch.
99+
2. Choose a built-in provider template or create a custom provider.
100+
3. Add the provider API key, or use the Codex OAuth login button for the Codex OAuth provider.
101+
4. Set the provider as active.
102+
5. Keep the local proxy enabled. Codex clients can use `http://127.0.0.1:12785/v1`.
103+
104+
When the proxy starts, CodexSwitch writes a managed Codex profile to the user's `.codex` directory. When the proxy stops, the original Codex files are restored from the local backup state.
105+
106+
## Local Files
107+
108+
CodexSwitch stores application state in the user's application data folder.
109+
110+
On Windows, the main files are:
111+
112+
| File | Purpose |
113+
| --- | --- |
114+
| `%APPDATA%\CodexSwitch\config.json` | Providers, routing, UI, proxy, OAuth account metadata, and local settings. |
115+
| `%APPDATA%\CodexSwitch\model-pricing.json` | Editable pricing catalog used for cost estimates. |
116+
| `%APPDATA%\CodexSwitch\usage-log.jsonl` | Local request usage log. |
117+
| `%APPDATA%\CodexSwitch\icons\` | Cached provider and model icons. |
118+
| `%APPDATA%\CodexSwitch\backups\` | Backups made before Codex config/auth writes. |
119+
| `%APPDATA%\CodexSwitch\codex-restore-state.json` | State used to restore the original Codex files. |
120+
| `%USERPROFILE%\.codex\config.toml` | Managed Codex config while the proxy is enabled. |
121+
| `%USERPROFILE%\.codex\auth.json` | Managed Codex auth while the proxy is enabled. |
122+
123+
Treat the config files as sensitive because they can contain API keys and OAuth tokens.
124+
125+
## Development
126+
127+
Restore, build, and test:
128+
129+
```powershell
130+
dotnet restore CodexSwitch.Tests/CodexSwitch.Tests.csproj
131+
dotnet build CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release --no-restore
132+
dotnet test CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release --no-build --no-restore
133+
```
134+
135+
Publish a self-contained build:
136+
137+
```powershell
138+
dotnet publish CodexSwitch/CodexSwitch.csproj -c Release -r win-x64 --self-contained true
139+
```
140+
141+
Validate the changelog before release work:
142+
143+
```powershell
144+
./build/Validate-Changelog.ps1
145+
```
146+
147+
## Project Structure
148+
149+
```text
150+
CodexSwitch/
151+
Controls/ Reusable Avalonia controls
152+
I18n/ Runtime localization services and markup extension
153+
Models/ App config, provider, pricing, and usage models
154+
Proxy/ Local proxy host, routing, protocol adapters, payload builders
155+
Services/ Config storage, Codex config writing, usage, pricing, icons, updates
156+
Styles/ Avalonia theme and component styles
157+
ViewModels/ Main desktop application state and commands
158+
Views/ Windows, pages, dialogs, and shell components
159+
CodexSwitch.Tests/ xUnit coverage for routing, pricing, config writing, usage, i18n, and updates
160+
build/ Release and validation scripts
161+
docs/ Release process notes
162+
```
163+
164+
## CI and Release Flow
165+
166+
The `ci` workflow validates the changelog, restores packages, builds the test project, runs xUnit tests, and publishes zipped artifacts for Windows, Linux, and macOS runners. GitHub Releases are created manually using the artifacts produced by CI. See [docs/release.md](docs/release.md).
167+
168+
## Current Scope
169+
170+
- The Claude Code page exists, but this build does not write Claude-specific local configuration yet.
171+
- Keep the proxy host on `127.0.0.1` unless you intentionally want to expose it beyond your machine.
172+
- Cost estimates depend on the local pricing catalog and should be treated as estimates, not billing statements.
173+
174+
## Contributing
175+
176+
Issues and pull requests are welcome. For changes that affect routing, protocol conversion, pricing, usage accounting, or config writing, please include focused tests in `CodexSwitch.Tests`.
177+
178+
Before opening a pull request:
179+
180+
```powershell
181+
dotnet test CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release
182+
./build/Validate-Changelog.ps1
183+
```
184+
185+
## License
186+
187+
This repository does not currently declare a license. Add a `LICENSE` file before distributing the project as open-source software or accepting external contributions.
188+
189+
## Star History
190+
191+
[![Star History Chart](https://api.star-history.com/svg?repos=AIDotNet/CodexSwitch&type=Date)](https://www.star-history.com/#AIDotNet/CodexSwitch&Date)

‎README.zh-CN.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# CodexSwitch
2+
3+
[English](README.md) | [简体中文](README.zh-CN.md)
4+
5+
[![GitHub stars](https://img.shields.io/github/stars/AIDotNet/CodexSwitch?style=social)](https://github.com/AIDotNet/CodexSwitch/stargazers)
6+
[![CI](https://github.com/AIDotNet/CodexSwitch/actions/workflows/ci.yml/badge.svg)](https://github.com/AIDotNet/CodexSwitch/actions/workflows/ci.yml)
7+
[![.NET 10](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/)
8+
[![Avalonia](https://img.shields.io/badge/Avalonia-12.0.3-8B44AC)](https://avaloniaui.net/)
9+
10+
CodexSwitch 是一个跨平台 Avalonia 桌面应用，用来把 Codex 变成一个可视化、可切换、可统计的本地 AI Provider 工作台。它会在本机运行一个兼容 OpenAI Responses 的代理服务，写入受管理的 Codex 配置，把请求路由到不同上游供应商，在需要时转换协议，并在本地记录 token 用量和成本估算。
11+
12+
默认本地端点是：
13+
14+
```text
15+
http://127.0.0.1:12785/v1
16+
```
17+
18+
## 它解决什么问题
19+
20+
Codex 会把 CodexSwitch 当成一个 OpenAI Responses API 端点来访问。CodexSwitch 收到请求后，会根据模型和路由配置选择供应商，重写模型名和 service tier，把请求转换成上游供应商需要的协议，再把响应和流式事件转换回 Responses 形态，同时把用量写入本地 JSONL 日志。
21+
22+
```mermaid
23+
flowchart LR
24+
Codex["Codex 客户端"] --> Proxy["CodexSwitch 本地 /v1 代理"]
25+
Proxy --> Router["供应商与模型路由"]
26+
Router --> OpenAI["OpenAI Responses"]
27+
Router --> Chat["OpenAI 兼容 Chat"]
28+
Router --> Anthropic["Anthropic Messages"]
29+
OpenAI --> Usage["用量与成本日志"]
30+
Chat --> Usage
31+
Anthropic --> Usage
32+
```
33+
34+
## 功能特性
35+
36+
- 本地代理服务，提供 `/health`、`/v1/models`、`/v1/responses` 端点。
37+
- 在桌面界面中一键切换当前激活供应商。
38+
- 内置 RoutinAI、RoutinAI Plan、OpenAI Official、Anthropic Messages、DeepSeek、Xiaomi MiMo 等供应商模板。
39+
- 提供专门的 Codex OAuth 登录流程，可连接 ChatGPT Codex 后端，并支持多账号管理。
40+
- 支持自定义供应商，可配置 base URL、API key、协议、模型路由、上游模型名和 service tier。
41+
- 支持 OpenAI Responses、OpenAI 兼容 Chat Completions、Anthropic Messages 三类上游协议。
42+
- 在上游协议允许时支持流式响应，并输出 Responses 风格的 SSE 事件。
43+
- 按请求模型自动路由，支持模型别名和上游模型映射。
44+
- 本地模型价格目录，支持阶梯价格、缓存读取价格、Claude 缓存创建计费和 fast mode 倍率。
45+
- 用量仪表盘，包含请求日志、供应商统计、模型统计、24 小时、7 天、30 天趋势。
46+
- 自动写入受管理的 Codex 配置和 auth 文件，并支持备份与恢复。
47+
- 支持浅色、深色、跟随系统主题，以及本地化 UI 资源。
48+
- 应用内可检查 GitHub Release 更新。
49+
50+
## 支持的协议
51+
52+
| Provider 协议 | 上游端点 | 说明 |
53+
| --- | --- | --- |
54+
| `OpenAiResponses` | `/responses` | 直接转发 Responses 请求，并处理模型、service tier 和请求覆盖配置。 |
55+
| `OpenAiChat` | `/chat/completions` | 把入站 Responses 请求转换成 Chat Completions，再把结果转换回 Responses 形态。 |
56+
| `AnthropicMessages` | `/messages` | 把入站 Responses 请求转换成 Anthropic Messages，并在支持的范围内处理工具调用、thinking/reasoning 映射和用量归一化。 |
57+
58+
CodexSwitch 当前对外暴露的是 Responses 风格的入站接口，不提供 `/v1/chat/completions` 作为公开入站 API。
59+
60+
## 内置供应商
61+
62+
| 供应商 | 默认协议 | 默认模型示例 |
63+
| --- | --- | --- |
64+
| RoutinAI | OpenAI Responses | `gpt-5.5` |
65+
| RoutinAI Plan | OpenAI Responses | `gpt-5.5` |
66+
| OpenAI Official | OpenAI Responses | `gpt-5.5` |
67+
| Anthropic Messages | Anthropic Messages | `claude-sonnet-4-5` |
68+
| DeepSeek | OpenAI Chat | `deepseek-v4-flash` |
69+
| Xiaomi MiMo | OpenAI Chat | `mimo-v2.5-pro` |
70+
| Codex OAuth | OpenAI Responses | `gpt-5.1-codex` |
71+
72+
如果某个上游服务兼容 OpenAI Responses、OpenAI Chat 或 Anthropic Messages，也可以作为自定义供应商接入。
73+
74+
## 安装
75+
76+
当 Release 产物发布后，可以从 [GitHub Releases](https://github.com/AIDotNet/CodexSwitch/releases) 下载。
77+
78+
当前 CI 会发布这些目标平台的自包含构建产物：
79+
80+
- `win-x64`
81+
- `linux-x64`
82+
- `osx-x64`
83+
- `osx-arm64`
84+
85+
## 从源码运行
86+
87+
前置要求：`global.json` 中固定的 .NET SDK `10.0.203`。
88+
89+
```powershell
90+
git clone https://github.com/AIDotNet/CodexSwitch.git
91+
cd CodexSwitch
92+
dotnet restore CodexSwitch.Tests/CodexSwitch.Tests.csproj
93+
dotnet run --project CodexSwitch/CodexSwitch.csproj
94+
```
95+
96+
## 首次使用
97+
98+
1. 打开 CodexSwitch。
99+
2. 选择一个内置供应商模板，或创建自定义供应商。
100+
3. 填入供应商 API key；如果使用 Codex OAuth 供应商，则点击 Codex OAuth 登录按钮。
101+
4. 将供应商设置为当前激活。
102+
5. 保持本地代理启用。Codex 客户端可以使用 `http://127.0.0.1:12785/v1`。
103+
104+
代理启动时，CodexSwitch 会向用户的 `.codex` 目录写入受管理的 Codex 配置。代理停止时，会根据本地备份状态恢复原始 Codex 文件。
105+
106+
## 本地文件
107+
108+
CodexSwitch 会把应用状态保存在用户的应用数据目录中。
109+
110+
在 Windows 上，主要文件包括：
111+
112+
| 文件 | 用途 |
113+
| --- | --- |
114+
| `%APPDATA%\CodexSwitch\config.json` | 供应商、路由、UI、代理、OAuth 账号元数据和本地设置。 |
115+
| `%APPDATA%\CodexSwitch\model-pricing.json` | 可编辑的模型价格目录，用于成本估算。 |
116+
| `%APPDATA%\CodexSwitch\usage-log.jsonl` | 本地请求用量日志。 |
117+
| `%APPDATA%\CodexSwitch\icons\` | 缓存的供应商和模型图标。 |
118+
| `%APPDATA%\CodexSwitch\backups\` | 写入 Codex 配置和 auth 文件前创建的备份。 |
119+
| `%APPDATA%\CodexSwitch\codex-restore-state.json` | 用于恢复原始 Codex 文件的状态。 |
120+
| `%USERPROFILE%\.codex\config.toml` | 代理启用时写入的受管理 Codex 配置。 |
121+
| `%USERPROFILE%\.codex\auth.json` | 代理启用时写入的受管理 Codex auth 文件。 |
122+
123+
这些配置文件可能包含 API key 和 OAuth token，请按敏感文件处理。
124+
125+
## 开发
126+
127+
还原、构建和测试：
128+
129+
```powershell
130+
dotnet restore CodexSwitch.Tests/CodexSwitch.Tests.csproj
131+
dotnet build CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release --no-restore
132+
dotnet test CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release --no-build --no-restore
133+
```
134+
135+
发布一个自包含构建：
136+
137+
```powershell
138+
dotnet publish CodexSwitch/CodexSwitch.csproj -c Release -r win-x64 --self-contained true
139+
```
140+
141+
发布前验证 changelog：
142+
143+
```powershell
144+
./build/Validate-Changelog.ps1
145+
```
146+
147+
## 项目结构
148+
149+
```text
150+
CodexSwitch/
151+
Controls/ 可复用 Avalonia 控件
152+
I18n/ 运行时本地化服务和 markup extension
153+
Models/ 应用配置、供应商、价格和用量模型
154+
Proxy/ 本地代理、路由、协议适配器、payload 构建器
155+
Services/ 配置存储、Codex 配置写入、用量、价格、图标、更新检查
156+
Styles/ Avalonia 主题和组件样式
157+
ViewModels/ 桌面应用主状态和命令
158+
Views/ 窗口、页面、弹窗和 shell 组件
159+
CodexSwitch.Tests/ xUnit 测试，覆盖路由、价格、配置写入、用量、i18n 和更新检查
160+
build/ 发布和验证脚本
161+
docs/ 发布流程说明
162+
```
163+
164+
## CI 与发布流程
165+
166+
`ci` 工作流会验证 changelog、还原依赖、构建测试项目、运行 xUnit 测试，并为 Windows、Linux、macOS runner 发布 zip 产物。GitHub Releases 仍然是手动创建，使用 CI 生成的产物。详情见 [docs/release.md](docs/release.md)。
167+
168+
## 当前范围
169+
170+
- Claude Code 页面已经存在，但当前版本尚未写入 Claude 专用本地配置。
171+
- 除非明确需要对外暴露，否则建议保持代理 host 为 `127.0.0.1`。
172+
- 成本统计依赖本地价格目录，应视为估算值，而不是正式账单。
173+
174+
## 贡献
175+
176+
欢迎提交 issue 和 pull request。涉及路由、协议转换、价格计算、用量统计或配置写入的改动，请在 `CodexSwitch.Tests` 中补充聚焦测试。
177+
178+
提交 pull request 前建议运行：
179+
180+
```powershell
181+
dotnet test CodexSwitch.Tests/CodexSwitch.Tests.csproj -c Release
182+
./build/Validate-Changelog.ps1
183+
```
184+
185+
## 许可证
186+
187+
当前仓库尚未声明许可证。正式以开源项目分发或接受外部贡献前，建议先添加 `LICENSE` 文件。
188+
189+
## Star 趋势
190+
191+
[![Star History Chart](https://api.star-history.com/svg?repos=AIDotNet/CodexSwitch&type=Date)](https://www.star-history.com/#AIDotNet/CodexSwitch&Date)

0 commit comments

Comments
 (0)