docs: Translate the Chinese version of the document
This commit is contained in:
gmw
@@ -1,38 +1,36 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md)
|
||||
# OmniRoute A2A 服务器文档
|
||||
|
||||
---
|
||||
🌐 **语言:** 🇺🇸 [English](../../A2A-SERVER.md) · 🇧🇷 [pt-BR](../pt-BR/A2A-SERVER.md) · 🇪🇸 [es](../es/A2A-SERVER.md) · 🇫🇷 [fr](../fr/A2A-SERVER.md) · 🇩🇪 [de](../de/A2A-SERVER.md) · 🇮🇹 [it](../it/A2A-SERVER.md) · 🇷🇺 [ru](../ru/A2A-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/A2A-SERVER.md) · 🇯🇵 [ja](../ja/A2A-SERVER.md) · 🇰🇷 [ko](../ko/A2A-SERVER.md) · 🇸🇦 [ar](../ar/A2A-SERVER.md) · 🇮🇳 [in](../in/A2A-SERVER.md) · 🇹🇭 [th](../th/A2A-SERVER.md) · 🇻🇳 [vi](../vi/A2A-SERVER.md) · 🇮🇩 [id](../id/A2A-SERVER.md) · 🇲🇾 [ms](../ms/A2A-SERVER.md) · 🇳🇱 [nl](../nl/A2A-SERVER.md) · 🇵🇱 [pl](../pl/A2A-SERVER.md) · 🇸🇪 [sv](../sv/A2A-SERVER.md) · 🇳🇴 [no](../no/A2A-SERVER.md) · 🇩🇰 [da](../da/A2A-SERVER.md) · 🇫🇮 [fi](../fi/A2A-SERVER.md) · 🇵🇹 [pt](../pt/A2A-SERVER.md) · 🇷🇴 [ro](../ro/A2A-SERVER.md) · 🇭🇺 [hu](../hu/A2A-SERVER.md) · 🇧🇬 [bg](../bg/A2A-SERVER.md) · 🇸🇰 [sk](../sk/A2A-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/A2A-SERVER.md) · 🇮🇱 [he](../he/A2A-SERVER.md) · 🇵🇭 [phi](../phi/A2A-SERVER.md) · 🇨🇿 [cs](../cs/A2A-SERVER.md)
|
||||
|
||||
# OmniRoute A2A Server Documentation
|
||||
> Agent-to-Agent Protocol v0.3 — OmniRoute 作为智能路由代理
|
||||
|
||||
> Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent
|
||||
|
||||
## Agent Discovery
|
||||
## 代理发现
|
||||
|
||||
```bash
|
||||
curl http://localhost:20128/.well-known/agent.json
|
||||
```
|
||||
|
||||
Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements.
|
||||
返回描述 OmniRoute 能力、技能和身份验证要求的 Agent Card。
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
## 身份验证
|
||||
|
||||
All `/a2a` requests require an API key via the `Authorization` header:
|
||||
所有 `/a2a` 请求需要通过 `Authorization` 头部提供 API 密钥：
|
||||
|
||||
```
|
||||
Authorization: Bearer YOUR_OMNIROUTE_API_KEY
|
||||
```
|
||||
|
||||
If no API key is configured on the server, authentication is bypassed.
|
||||
如果服务器未配置 API 密钥，则跳过身份验证。
|
||||
|
||||
---
|
||||
|
||||
## JSON-RPC 2.0 Methods
|
||||
## JSON-RPC 2.0 方法
|
||||
|
||||
### `message/send` — Synchronous Execution
|
||||
### `message/send` — 同步执行
|
||||
|
||||
Sends a message to a skill and waits for the complete response.
|
||||
向技能发送消息并等待完整响应。
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/a2a \
|
||||
@@ -50,7 +48,7 @@ curl -X POST http://localhost:20128/a2a \
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
**响应:**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -71,9 +69,9 @@ curl -X POST http://localhost:20128/a2a \
|
||||
}
|
||||
```
|
||||
|
||||
### `message/stream` — SSE Streaming
|
||||
### `message/stream` — SSE 流式传输
|
||||
|
||||
Same as `message/send` but returns Server-Sent Events for real-time streaming.
|
||||
与 `message/send` 相同，但返回 Server-Sent Events 进行实时流式传输。
|
||||
|
||||
```bash
|
||||
curl -N -X POST http://localhost:20128/a2a \
|
||||
@@ -90,7 +88,7 @@ curl -N -X POST http://localhost:20128/a2a \
|
||||
}'
|
||||
```
|
||||
|
||||
**SSE Events:**
|
||||
**SSE 事件:**
|
||||
|
||||
```
|
||||
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}
|
||||
@@ -100,7 +98,7 @@ data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","s
|
||||
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
|
||||
```
|
||||
|
||||
### `tasks/get` — Query Task Status
|
||||
### `tasks/get` — 查询任务状态
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/a2a \
|
||||
@@ -109,7 +107,7 @@ curl -X POST http://localhost:20128/a2a \
|
||||
-d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'
|
||||
```
|
||||
|
||||
### `tasks/cancel` — Cancel a Task
|
||||
### `tasks/cancel` — 取消任务
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/a2a \
|
||||
@@ -120,16 +118,16 @@ curl -X POST http://localhost:20128/a2a \
|
||||
|
||||
---
|
||||
|
||||
## Available Skills
|
||||
## 可用技能
|
||||
|
||||
| Skill | Description |
|
||||
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. |
|
||||
| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. |
|
||||
| 技能 | 描述 |
|
||||
| :----------------- | :---------------------------------------------------------------------------------------------- |
|
||||
| `smart-routing` | 通过 OmniRoute 的智能管道路由提示。返回带有路由说明、成本和弹性追踪的响应。 |
|
||||
| `quota-management` | 回答关于服务商配额的自然语言查询，建议免费组合，并提供配额排名。 |
|
||||
|
||||
---
|
||||
|
||||
## Task Lifecycle
|
||||
## 任务生命周期
|
||||
|
||||
```
|
||||
submitted → working → completed
|
||||
@@ -137,25 +135,25 @@ submitted → working → completed
|
||||
→ cancelled
|
||||
```
|
||||
|
||||
- Tasks expire after 5 minutes (configurable)
|
||||
- Terminal states: `completed`, `failed`, `cancelled`
|
||||
- Event log tracks every state transition
|
||||
- 任务在 5 分钟后过期（可配置）
|
||||
- 终止状态：`completed`、`failed`、`cancelled`
|
||||
- 事件日志跟踪每个状态转换
|
||||
|
||||
---
|
||||
|
||||
## Error Codes
|
||||
## 错误代码
|
||||
|
||||
| Code | Meaning |
|
||||
| :----- | :----------------------------- |
|
||||
| -32700 | Parse error (invalid JSON) |
|
||||
| -32600 | Invalid request / Unauthorized |
|
||||
| -32601 | Method or skill not found |
|
||||
| -32602 | Invalid params |
|
||||
| -32603 | Internal error |
|
||||
| 代码 | 含义 |
|
||||
| :----- | :-------------------------- |
|
||||
| -32700 | 解析错误（无效 JSON） |
|
||||
| -32600 | 无效请求 / 未授权 |
|
||||
| -32601 | 方法或技能未找到 |
|
||||
| -32602 | 无效参数 |
|
||||
| -32603 | 内部错误 |
|
||||
|
||||
---
|
||||
|
||||
## Integration Examples
|
||||
## 集成示例
|
||||
|
||||
### Python (requests)
|
||||
|
||||
|
||||
+215
-207
@@ -1,26 +1,22 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/API_REFERENCE.md) · 🇪🇸 [es](../es/API_REFERENCE.md) · 🇫🇷 [fr](../fr/API_REFERENCE.md) · 🇩🇪 [de](../de/API_REFERENCE.md) · 🇮🇹 [it](../it/API_REFERENCE.md) · 🇷🇺 [ru](../ru/API_REFERENCE.md) · 🇨🇳 [zh-CN](../zh-CN/API_REFERENCE.md) · 🇯🇵 [ja](../ja/API_REFERENCE.md) · 🇰🇷 [ko](../ko/API_REFERENCE.md) · 🇸🇦 [ar](../ar/API_REFERENCE.md) · 🇮🇳 [in](../in/API_REFERENCE.md) · 🇹🇭 [th](../th/API_REFERENCE.md) · 🇻🇳 [vi](../vi/API_REFERENCE.md) · 🇮🇩 [id](../id/API_REFERENCE.md) · 🇲🇾 [ms](../ms/API_REFERENCE.md) · 🇳🇱 [nl](../nl/API_REFERENCE.md) · 🇵🇱 [pl](../pl/API_REFERENCE.md) · 🇸🇪 [sv](../sv/API_REFERENCE.md) · 🇳🇴 [no](../no/API_REFERENCE.md) · 🇩🇰 [da](../da/API_REFERENCE.md) · 🇫🇮 [fi](../fi/API_REFERENCE.md) · 🇵🇹 [pt](../pt/API_REFERENCE.md) · 🇷🇴 [ro](../ro/API_REFERENCE.md) · 🇭🇺 [hu](../hu/API_REFERENCE.md) · 🇧🇬 [bg](../bg/API_REFERENCE.md) · 🇸🇰 [sk](../sk/API_REFERENCE.md) · 🇺🇦 [uk-UA](../uk-UA/API_REFERENCE.md) · 🇮🇱 [he](../he/API_REFERENCE.md) · 🇵🇭 [phi](../phi/API_REFERENCE.md)
|
||||
# API 参考
|
||||
|
||||
🌐 **语言:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) | 🇨🇿 [Čeština](../cs/API_REFERENCE.md)
|
||||
|
||||
所有 OmniRoute API 端点的完整参考。
|
||||
|
||||
---
|
||||
|
||||
# API Reference
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md)
|
||||
|
||||
Complete reference for all OmniRoute API endpoints.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
## 目录
|
||||
|
||||
- [Chat Completions](#chat-completions)
|
||||
- [Embeddings](#embeddings)
|
||||
- [Image Generation](#image-generation)
|
||||
- [List Models](#list-models)
|
||||
- [Compatibility Endpoints](#compatibility-endpoints)
|
||||
- [Semantic Cache](#semantic-cache)
|
||||
- [Dashboard & Management](#dashboard--management)
|
||||
- [Request Processing](#request-processing)
|
||||
- [Authentication](#authentication)
|
||||
- [图像生成](#图像生成)
|
||||
- [模型列表](#模型列表)
|
||||
- [兼容性端点](#兼容性端点)
|
||||
- [语义缓存](#语义缓存)
|
||||
- [Dashboard 与管理](#dashboard-与管理)
|
||||
- [请求处理](#请求处理)
|
||||
- [认证](#认证)
|
||||
|
||||
---
|
||||
|
||||
@@ -40,17 +36,22 @@ Content-Type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Headers
|
||||
### 自定义请求头
|
||||
|
||||
| Header | Direction | Description |
|
||||
| ------------------------ | --------- | --------------------------------- |
|
||||
| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache |
|
||||
| `X-OmniRoute-Progress` | Request | Set to `true` for progress events |
|
||||
| `Idempotency-Key` | Request | Dedup key (5s window) |
|
||||
| `X-Request-Id` | Request | Alternative dedup key |
|
||||
| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) |
|
||||
| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated |
|
||||
| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on |
|
||||
| 请求头 | 方向 | 描述 |
|
||||
| ------------------------ | ------ | ------------------------------------- |
|
||||
| `X-OmniRoute-No-Cache` | 请求 | 设为 `true` 绕过缓存 |
|
||||
| `X-OmniRoute-Progress` | 请求 | 设为 `true` 启用进度事件 |
|
||||
| `X-Session-Id` | 请求 | 用于外部会话亲和性的粘性会话密钥 |
|
||||
| `x_session_id` | 请求 | 下划线变体也被接受（直接 HTTP） |
|
||||
| `Idempotency-Key` | 请求 | 去重密钥（5秒窗口） |
|
||||
| `X-Request-Id` | 请求 | 备用去重密钥 |
|
||||
| `X-OmniRoute-Cache` | 响应 | `HIT` 或 `MISS`（非流式） |
|
||||
| `X-OmniRoute-Idempotent` | 响应 | 如果已去重则为 `true` |
|
||||
| `X-OmniRoute-Progress` | 响应 | 如果启用进度追踪则为 `enabled` |
|
||||
| `X-OmniRoute-Session-Id` | 响应 | OmniRoute 使用的有效会话 ID |
|
||||
|
||||
> **Nginx 注意**: 如果您依赖下划线请求头（例如 `x_session_id`），请启用 `underscores_in_headers on;`。
|
||||
|
||||
---
|
||||
|
||||
@@ -67,16 +68,16 @@ Content-Type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
|
||||
可用提供商：Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA。
|
||||
|
||||
```bash
|
||||
# List all embedding models
|
||||
# 列出所有 Embedding 模型
|
||||
GET /v1/embeddings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Image Generation
|
||||
## 图像生成
|
||||
|
||||
```bash
|
||||
POST /v1/images/generations
|
||||
@@ -90,42 +91,42 @@ Content-Type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
|
||||
可用提供商：OpenAI (DALL-E)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI。
|
||||
|
||||
```bash
|
||||
# List all image models
|
||||
# 列出所有图像模型
|
||||
GET /v1/images/generations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List Models
|
||||
## 模型列表
|
||||
|
||||
```bash
|
||||
GET /v1/models
|
||||
Authorization: Bearer your-api-key
|
||||
|
||||
→ Returns all chat, embedding, and image models + combos in OpenAI format
|
||||
→ 以 OpenAI 格式返回所有 chat、embedding 和 image 模型 + combos
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compatibility Endpoints
|
||||
## 兼容性端点
|
||||
|
||||
| Method | Path | Format |
|
||||
| ------ | --------------------------- | ---------------------- |
|
||||
| POST | `/v1/chat/completions` | OpenAI |
|
||||
| POST | `/v1/messages` | Anthropic |
|
||||
| POST | `/v1/responses` | OpenAI Responses |
|
||||
| POST | `/v1/embeddings` | OpenAI |
|
||||
| POST | `/v1/images/generations` | OpenAI |
|
||||
| GET | `/v1/models` | OpenAI |
|
||||
| POST | `/v1/messages/count_tokens` | Anthropic |
|
||||
| GET | `/v1beta/models` | Gemini |
|
||||
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
|
||||
| POST | `/v1/api/chat` | Ollama |
|
||||
| 方法 | 路径 | 格式 |
|
||||
| ---- | --------------------------- | -------------------- |
|
||||
| POST | `/v1/chat/completions` | OpenAI |
|
||||
| POST | `/v1/messages` | Anthropic |
|
||||
| POST | `/v1/responses` | OpenAI Responses |
|
||||
| POST | `/v1/embeddings` | OpenAI |
|
||||
| POST | `/v1/images/generations` | OpenAI |
|
||||
| GET | `/v1/models` | OpenAI |
|
||||
| POST | `/v1/messages/count_tokens` | Anthropic |
|
||||
| GET | `/v1beta/models` | Gemini |
|
||||
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
|
||||
| POST | `/v1/api/chat` | Ollama |
|
||||
|
||||
### Dedicated Provider Routes
|
||||
### 专用提供商路由
|
||||
|
||||
```bash
|
||||
POST /v1/providers/{provider}/chat/completions
|
||||
@@ -133,21 +134,21 @@ POST /v1/providers/{provider}/embeddings
|
||||
POST /v1/providers/{provider}/images/generations
|
||||
```
|
||||
|
||||
The provider prefix is auto-added if missing. Mismatched models return `400`.
|
||||
如果缺少提供商前缀则自动添加。模型不匹配时返回 `400`。
|
||||
|
||||
---
|
||||
|
||||
## Semantic Cache
|
||||
## 语义缓存
|
||||
|
||||
```bash
|
||||
# Get cache stats
|
||||
GET /api/cache
|
||||
# 获取缓存统计
|
||||
GET /api/cache/stats
|
||||
|
||||
# Clear all caches
|
||||
DELETE /api/cache
|
||||
# 清除所有缓存
|
||||
DELETE /api/cache/stats
|
||||
```
|
||||
|
||||
Response example:
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -166,164 +167,171 @@ Response example:
|
||||
|
||||
---
|
||||
|
||||
## Dashboard & Management
|
||||
## Dashboard 与管理
|
||||
|
||||
### Authentication
|
||||
### 认证
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ----------------------------- | ------- | --------------------- |
|
||||
| `/api/auth/login` | POST | Login |
|
||||
| `/api/auth/logout` | POST | Logout |
|
||||
| `/api/settings/require-login` | GET/PUT | Toggle login required |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ----------------------------- | ------- | ---------------- |
|
||||
| `/api/auth/login` | POST | 登录 |
|
||||
| `/api/auth/logout` | POST | 登出 |
|
||||
| `/api/settings/require-login` | GET/PUT | 切换是否需要登录 |
|
||||
|
||||
### Provider Management
|
||||
### 提供商管理
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------------- | --------------- | ------------------------ |
|
||||
| `/api/providers` | GET/POST | List / create providers |
|
||||
| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider |
|
||||
| `/api/providers/[id]/test` | POST | Test provider connection |
|
||||
| `/api/providers/[id]/models` | GET | List provider models |
|
||||
| `/api/providers/validate` | POST | Validate provider config |
|
||||
| `/api/provider-nodes*` | Various | Provider node management |
|
||||
| `/api/provider-models` | GET/POST/DELETE | Custom models |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ---------------------------- | --------------- | ---------------- |
|
||||
| `/api/providers` | GET/POST | 列出/创建提供商 |
|
||||
| `/api/providers/[id]` | GET/PUT/DELETE | 管理提供商 |
|
||||
| `/api/providers/[id]/test` | POST | 测试提供商连接 |
|
||||
| `/api/providers/[id]/models` | GET | 列出提供商模型 |
|
||||
| `/api/providers/validate` | POST | 验证提供商配置 |
|
||||
| `/api/provider-nodes*` | 多种 | 提供商节点管理 |
|
||||
| `/api/provider-models` | GET/POST/DELETE | 自定义模型 |
|
||||
|
||||
### OAuth Flows
|
||||
### OAuth 流程
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| -------------------------------- | ------- | ----------------------- |
|
||||
| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| -------------------------------- | ----- | ------------------ |
|
||||
| `/api/oauth/[provider]/[action]` | 多种 | 提供商特定的 OAuth |
|
||||
|
||||
### Routing & Config
|
||||
### 路由与配置
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------- | -------- | ----------------------------- |
|
||||
| `/api/models/alias` | GET/POST | Model aliases |
|
||||
| `/api/models/catalog` | GET | All models by provider + type |
|
||||
| `/api/combos*` | Various | Combo management |
|
||||
| `/api/keys*` | Various | API key management |
|
||||
| `/api/pricing` | GET | Model pricing |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------------- | -------- | -------------------------- |
|
||||
| `/api/models/alias` | GET/POST | 模型别名 |
|
||||
| `/api/models/catalog` | GET | 按提供商 + 类型的所有模型 |
|
||||
| `/api/combos*` | 多种 | Combo 管理 |
|
||||
| `/api/keys*` | 多种 | API 密钥管理 |
|
||||
| `/api/pricing` | GET | 模型定价 |
|
||||
|
||||
### Usage & Analytics
|
||||
### 用量与分析
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | -------------------- |
|
||||
| `/api/usage/history` | GET | Usage history |
|
||||
| `/api/usage/logs` | GET | Usage logs |
|
||||
| `/api/usage/request-logs` | GET | Request-level logs |
|
||||
| `/api/usage/[connectionId]` | GET | Per-connection usage |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------------------- | ---- | ---------------- |
|
||||
| `/api/usage/history` | GET | 用量历史 |
|
||||
| `/api/usage/logs` | GET | 用量日志 |
|
||||
| `/api/usage/request-logs` | GET | 请求级别日志 |
|
||||
| `/api/usage/[connectionId]` | GET | 按连接的用量 |
|
||||
|
||||
### Settings
|
||||
### 设置
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------------------------- | ------- | ---------------------- |
|
||||
| `/api/settings` | GET/PUT | General settings |
|
||||
| `/api/settings/proxy` | GET/PUT | Network proxy config |
|
||||
| `/api/settings/proxy/test` | POST | Test proxy connection |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
|
||||
| `/api/settings/system-prompt` | GET/PUT | Global system prompt |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ------------------------------- | ------------- | ------------------ |
|
||||
| `/api/settings` | GET/PUT/PATCH | 常规设置 |
|
||||
| `/api/settings/proxy` | GET/PUT | 网络代理配置 |
|
||||
| `/api/settings/proxy/test` | POST | 测试代理连接 |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP 白名单/黑名单 |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | 推理 token 预算 |
|
||||
| `/api/settings/system-prompt` | GET/PUT | 全局系统提示词 |
|
||||
|
||||
### Monitoring
|
||||
### 监控
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------------------ | ---------- | ----------------------- |
|
||||
| `/api/sessions` | GET | Active session tracking |
|
||||
| `/api/rate-limits` | GET | Per-account rate limits |
|
||||
| `/api/monitoring/health` | GET | Health check |
|
||||
| `/api/cache` | GET/DELETE | Cache stats / clear |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ------------------------ | ---------- | ----------------------------------------------------------- |
|
||||
| `/api/sessions` | GET | 活跃会话追踪 |
|
||||
| `/api/rate-limits` | GET | 每账户速率限制 |
|
||||
| `/api/monitoring/health` | GET | 健康检查 + 提供商摘要（`catalogCount`、`configuredCount`、`activeCount`、`monitoredCount`） |
|
||||
| `/api/cache/stats` | GET/DELETE | 缓存统计 / 清除 |
|
||||
|
||||
### Backup & Export/Import
|
||||
### 备份与导出/导入
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | --------------------------------------- |
|
||||
| `/api/db-backups` | GET | List available backups |
|
||||
| `/api/db-backups` | PUT | Create a manual backup |
|
||||
| `/api/db-backups` | POST | Restore from a specific backup |
|
||||
| `/api/db-backups/export` | GET | Download database as .sqlite file |
|
||||
| `/api/db-backups/import` | POST | Upload .sqlite file to replace database |
|
||||
| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------------------- | ---- | ------------------------------ |
|
||||
| `/api/db-backups` | GET | 列出可用备份 |
|
||||
| `/api/db-backups` | PUT | 创建手动备份 |
|
||||
| `/api/db-backups` | POST | 从特定备份恢复 |
|
||||
| `/api/db-backups/export` | GET | 下载数据库为 .sqlite 文件 |
|
||||
| `/api/db-backups/import` | POST | 上传 .sqlite 文件替换数据库 |
|
||||
| `/api/db-backups/exportAll` | GET | 下载完整备份为 .tar.gz 归档 |
|
||||
|
||||
### Cloud Sync
|
||||
### 云同步
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------- | ------- | --------------------- |
|
||||
| `/api/sync/cloud` | Various | Cloud sync operations |
|
||||
| `/api/sync/initialize` | POST | Initialize sync |
|
||||
| `/api/cloud/*` | Various | Cloud management |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ---------------------- | ----- | ------------ |
|
||||
| `/api/sync/cloud` | 多种 | 云同步操作 |
|
||||
| `/api/sync/initialize` | POST | 初始化同步 |
|
||||
| `/api/cloud/*` | 多种 | 云管理 |
|
||||
|
||||
### CLI Tools
|
||||
### 隧道
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------------------- | ------ | ------------------- |
|
||||
| `/api/cli-tools/claude-settings` | GET | Claude CLI status |
|
||||
| `/api/cli-tools/codex-settings` | GET | Codex CLI status |
|
||||
| `/api/cli-tools/droid-settings` | GET | Droid CLI status |
|
||||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status |
|
||||
| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| -------------------------- | ---- | ----------------------------------------------------------- |
|
||||
| `/api/tunnels/cloudflared` | GET | 读取 Dashboard 使用的 Cloudflare Quick Tunnel 安装/运行状态 |
|
||||
| `/api/tunnels/cloudflared` | POST | 启用或禁用 Cloudflare Quick Tunnel（`action=enable/disable`） |
|
||||
|
||||
CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
|
||||
### CLI 工具
|
||||
|
||||
### ACP Agents
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ---------------------------------- | ---- | ---------------- |
|
||||
| `/api/cli-tools/claude-settings` | GET | Claude CLI 状态 |
|
||||
| `/api/cli-tools/codex-settings` | GET | Codex CLI 状态 |
|
||||
| `/api/cli-tools/droid-settings` | GET | Droid CLI 状态 |
|
||||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI 状态|
|
||||
| `/api/cli-tools/runtime/[toolId]` | GET | 通用 CLI 运行时 |
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ----------------- | ------ | -------------------------------------------------------- |
|
||||
| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status |
|
||||
| `/api/acp/agents` | POST | Add custom agent or refresh detection cache |
|
||||
| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param |
|
||||
CLI 响应包括：`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason`。
|
||||
|
||||
GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
|
||||
### ACP 代理
|
||||
|
||||
### Resilience & Rate Limits
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ----------------- | ------ | ---------------------------------------------- |
|
||||
| `/api/acp/agents` | GET | 列出所有检测到的代理（内置 + 自定义）及状态 |
|
||||
| `/api/acp/agents` | POST | 添加自定义代理或刷新检测缓存 |
|
||||
| `/api/acp/agents` | DELETE | 通过 `id` 查询参数删除自定义代理 |
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ----------------------- | ------- | ------------------------------- |
|
||||
| `/api/resilience` | GET/PUT | Get/update resilience profiles |
|
||||
| `/api/resilience/reset` | POST | Reset circuit breakers |
|
||||
| `/api/rate-limits` | GET | Per-account rate limit status |
|
||||
| `/api/rate-limit` | GET | Global rate limit configuration |
|
||||
GET 响应包括 `agents[]`（id、name、binary、version、installed、protocol、isCustom）和 `summary`（total、installed、notFound、builtIn、custom）。
|
||||
|
||||
### Evals
|
||||
### 弹性与速率限制
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------ | -------- | --------------------------------- |
|
||||
| `/api/evals` | GET/POST | List eval suites / run evaluation |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ----------------------- | ------- | ---------------------- |
|
||||
| `/api/resilience` | GET/PUT | 获取/更新弹性配置文件 |
|
||||
| `/api/resilience/reset` | POST | 重置熔断器 |
|
||||
| `/api/rate-limits` | GET | 每账户速率限制状态 |
|
||||
| `/api/rate-limit` | GET | 全局速率限制配置 |
|
||||
|
||||
### Policies
|
||||
### 评估
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------- | --------------- | ----------------------- |
|
||||
| `/api/policies` | GET/POST/DELETE | Manage routing policies |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| ------------ | -------- | ------------------------ |
|
||||
| `/api/evals` | GET/POST | 列出评估套件/运行评估 |
|
||||
|
||||
### Compliance
|
||||
### 策略
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | ----------------------------- |
|
||||
| `/api/compliance/audit-log` | GET | Compliance audit log (last N) |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------- | --------------- | -------------- |
|
||||
| `/api/policies` | GET/POST/DELETE | 管理路由策略 |
|
||||
|
||||
### v1beta (Gemini-Compatible)
|
||||
### 合规
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| -------------------------- | ------ | --------------------------------- |
|
||||
| `/v1beta/models` | GET | List models in Gemini format |
|
||||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------------------- | ---- | -------------------------- |
|
||||
| `/api/compliance/audit-log` | GET | 合规审计日志（最后 N 条） |
|
||||
|
||||
These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
|
||||
### v1beta（Gemini 兼容）
|
||||
|
||||
### Internal / System APIs
|
||||
| 端点 | 方法 | 描述 |
|
||||
| -------------------------- | ---- | --------------------------- |
|
||||
| `/v1beta/models` | GET | 以 Gemini 格式列出模型 |
|
||||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` 端点 |
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------- | ------ | ---------------------------------------------------- |
|
||||
| `/api/init` | GET | Application initialization check (used on first run) |
|
||||
| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) |
|
||||
| `/api/restart` | POST | Trigger graceful server restart |
|
||||
| `/api/shutdown` | POST | Trigger graceful server shutdown |
|
||||
这些端点镜像 Gemini 的 API 格式，用于期望原生 Gemini SDK 兼容性的客户端。
|
||||
|
||||
> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
|
||||
### 内部/系统 API
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
| --------------- | ---- | ------------------------------------------------ |
|
||||
| `/api/init` | GET | 应用初始化检查（首次运行时使用） |
|
||||
| `/api/tags` | GET | Ollama 兼容的模型标签（用于 Ollama 客户端） |
|
||||
| `/api/restart` | POST | 触发优雅的服务器重启 |
|
||||
| `/api/shutdown` | POST | 触发优雅的服务器关闭 |
|
||||
|
||||
> **注意：** 这些端点由系统内部使用或用于 Ollama 客户端兼容性。终端用户通常不需要调用它们。
|
||||
|
||||
---
|
||||
|
||||
## Audio Transcription
|
||||
## 音频转录
|
||||
|
||||
```bash
|
||||
POST /v1/audio/transcriptions
|
||||
@@ -331,9 +339,9 @@ Authorization: Bearer your-api-key
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
Transcribe audio files using Deepgram or AssemblyAI.
|
||||
使用 Deepgram 或 AssemblyAI 转录音频文件。
|
||||
|
||||
**Request:**
|
||||
**请求：**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||||
@@ -342,7 +350,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||||
-F "model=deepgram/nova-3"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -353,36 +361,36 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||||
}
|
||||
```
|
||||
|
||||
**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
|
||||
**支持的提供商：** `deepgram/nova-3`、`assemblyai/best`。
|
||||
|
||||
**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
|
||||
**支持的格式：** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。
|
||||
|
||||
---
|
||||
|
||||
## Ollama Compatibility
|
||||
## Ollama 兼容性
|
||||
|
||||
For clients that use Ollama's API format:
|
||||
用于使用 Ollama API 格式的客户端：
|
||||
|
||||
```bash
|
||||
# Chat endpoint (Ollama format)
|
||||
# Chat 端点（Ollama 格式）
|
||||
POST /v1/api/chat
|
||||
|
||||
# Model listing (Ollama format)
|
||||
# 模型列表（Ollama 格式）
|
||||
GET /api/tags
|
||||
```
|
||||
|
||||
Requests are automatically translated between Ollama and internal formats.
|
||||
请求会自动在 Ollama 和内部格式之间转换。
|
||||
|
||||
---
|
||||
|
||||
## Telemetry
|
||||
## 遥测
|
||||
|
||||
```bash
|
||||
# Get latency telemetry summary (p50/p95/p99 per provider)
|
||||
# 获取延迟遥测摘要（每提供商的 p50/p95/p99）
|
||||
GET /api/telemetry/summary
|
||||
```
|
||||
|
||||
**Response:**
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -395,13 +403,13 @@ GET /api/telemetry/summary
|
||||
|
||||
---
|
||||
|
||||
## Budget
|
||||
## 预算
|
||||
|
||||
```bash
|
||||
# Get budget status for all API keys
|
||||
# 获取所有 API 密钥的预算状态
|
||||
GET /api/usage/budget
|
||||
|
||||
# Set or update a budget
|
||||
# 设置或更新预算
|
||||
POST /api/usage/budget
|
||||
Content-Type: application/json
|
||||
|
||||
@@ -414,13 +422,13 @@ Content-Type: application/json
|
||||
|
||||
---
|
||||
|
||||
## Model Availability
|
||||
## 模型可用性
|
||||
|
||||
```bash
|
||||
# Get real-time model availability across all providers
|
||||
# 获取所有提供商的实时模型可用性
|
||||
GET /api/models/availability
|
||||
|
||||
# Check availability for a specific model
|
||||
# 检查特定模型的可用性
|
||||
POST /api/models/availability
|
||||
Content-Type: application/json
|
||||
|
||||
@@ -431,25 +439,25 @@ Content-Type: application/json
|
||||
|
||||
---
|
||||
|
||||
## Request Processing
|
||||
## 请求处理
|
||||
|
||||
1. Client sends request to `/v1/*`
|
||||
2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
|
||||
3. Model is resolved (direct provider/model or alias/combo)
|
||||
4. Credentials selected from local DB with account availability filtering
|
||||
5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
|
||||
6. Provider executor sends upstream request
|
||||
7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
|
||||
8. Usage/logging recorded
|
||||
9. Fallback applies on errors according to combo rules
|
||||
1. 客户端向 `/v1/*` 发送请求
|
||||
2. 路由处理器调用 `handleChat`、`handleEmbedding`、`handleAudioTranscription` 或 `handleImageGeneration`
|
||||
3. 解析模型（直接 provider/model 或 alias/combo）
|
||||
4. 从本地数据库选择凭据，并过滤账户可用性
|
||||
5. 对于 chat：`handleChatCore` — 格式检测、翻译、缓存检查、幂等性检查
|
||||
6. 提供商执行器发送上游请求
|
||||
7. 响应翻译回客户端格式（chat）或直接返回（embeddings/images/audio）
|
||||
8. 记录用量/日志
|
||||
9. 根据 combo 规则在错误时应用后备
|
||||
|
||||
Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
|
||||
完整架构参考：[`ARCHITECTURE.md`](ARCHITECTURE.md)
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
## 认证
|
||||
|
||||
- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
|
||||
- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
|
||||
- `requireLogin` toggleable via `/api/settings/require-login`
|
||||
- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`
|
||||
- Dashboard 路由（`/dashboard/*`）使用 `auth_token` cookie
|
||||
- 登录使用保存的密码哈希；回退到 `INITIAL_PASSWORD`
|
||||
- `requireLogin` 可通过 `/api/settings/require-login` 切换
|
||||
- 当 `REQUIRE_API_KEY=true` 时，`/v1/*` 路由可选地需要 Bearer API 密钥
|
||||
|
||||
+464
-439
File diff suppressed because it is too large
Load Diff
@@ -1,67 +1,67 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../AUTO-COMBO.md) · 🇧🇷 [pt-BR](../pt-BR/AUTO-COMBO.md) · 🇪🇸 [es](../es/AUTO-COMBO.md) · 🇫🇷 [fr](../fr/AUTO-COMBO.md) · 🇩🇪 [de](../de/AUTO-COMBO.md) · 🇮🇹 [it](../it/AUTO-COMBO.md) · 🇷🇺 [ru](../ru/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../zh-CN/AUTO-COMBO.md) · 🇯🇵 [ja](../ja/AUTO-COMBO.md) · 🇰🇷 [ko](../ko/AUTO-COMBO.md) · 🇸🇦 [ar](../ar/AUTO-COMBO.md) · 🇮🇳 [in](../in/AUTO-COMBO.md) · 🇹🇭 [th](../th/AUTO-COMBO.md) · 🇻🇳 [vi](../vi/AUTO-COMBO.md) · 🇮🇩 [id](../id/AUTO-COMBO.md) · 🇲🇾 [ms](../ms/AUTO-COMBO.md) · 🇳🇱 [nl](../nl/AUTO-COMBO.md) · 🇵🇱 [pl](../pl/AUTO-COMBO.md) · 🇸🇪 [sv](../sv/AUTO-COMBO.md) · 🇳🇴 [no](../no/AUTO-COMBO.md) · 🇩🇰 [da](../da/AUTO-COMBO.md) · 🇫🇮 [fi](../fi/AUTO-COMBO.md) · 🇵🇹 [pt](../pt/AUTO-COMBO.md) · 🇷🇴 [ro](../ro/AUTO-COMBO.md) · 🇭🇺 [hu](../hu/AUTO-COMBO.md) · 🇧🇬 [bg](../bg/AUTO-COMBO.md) · 🇸🇰 [sk](../sk/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../uk-UA/AUTO-COMBO.md) · 🇮🇱 [he](../he/AUTO-COMBO.md) · 🇵🇭 [phi](../phi/AUTO-COMBO.md)
|
||||
|
||||
---
|
||||
|
||||
# OmniRoute Auto-Combo Engine
|
||||
# OmniRoute Auto-Combo 引擎
|
||||
|
||||
> Self-managing model chains with adaptive scoring
|
||||
> 具有自适应评分的自管理模型链
|
||||
|
||||
## How It Works
|
||||
## 工作原理
|
||||
|
||||
The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**:
|
||||
Auto-Combo 引擎使用 **6 因子评分函数** 为每个请求动态选择最佳服务商/模型：
|
||||
|
||||
| Factor | Weight | Description |
|
||||
| :--------- | :----- | :---------------------------------------------- |
|
||||
| Quota | 0.20 | Remaining capacity [0..1] |
|
||||
| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 |
|
||||
| CostInv | 0.20 | Inverse cost (cheaper = higher score) |
|
||||
| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) |
|
||||
| TaskFit | 0.10 | Model × task type fitness score |
|
||||
| Stability | 0.10 | Low variance in latency/errors |
|
||||
| 因子 | 权重 | 描述 |
|
||||
| :--------- | :--- | :--------------------------------------- |
|
||||
| Quota | 0.20 | 剩余容量 [0..1] |
|
||||
| Health | 0.25 | 熔断器状态：CLOSED=1.0, HALF=0.5, OPEN=0.0 |
|
||||
| CostInv | 0.20 | 成本倒数（越便宜得分越高） |
|
||||
| LatencyInv | 0.15 | p95 延迟倒数（越快得分越高） |
|
||||
| TaskFit | 0.10 | 模型 × 任务类型适配度 |
|
||||
| Stability | 0.10 | 延迟/错误率的低方差 |
|
||||
|
||||
## Mode Packs
|
||||
## 模式包
|
||||
|
||||
| Pack | Focus | Key Weight |
|
||||
| :---------------------- | :----------- | :--------------- |
|
||||
| 🚀 **Ship Fast** | Speed | latencyInv: 0.35 |
|
||||
| 💰 **Cost Saver** | Economy | costInv: 0.40 |
|
||||
| 🎯 **Quality First** | Best model | taskFit: 0.40 |
|
||||
| 📡 **Offline Friendly** | Availability | quota: 0.40 |
|
||||
| 模式包 | 侧重点 | 关键权重 |
|
||||
| :---------------------- | :----- | :--------------- |
|
||||
| 🚀 **Ship Fast** | 速度 | latencyInv: 0.35 |
|
||||
| 💰 **Cost Saver** | 经济 | costInv: 0.40 |
|
||||
| 🎯 **Quality First** | 最优模型 | taskFit: 0.40 |
|
||||
| 📡 **Offline Friendly** | 可用性 | quota: 0.40 |
|
||||
|
||||
## Self-Healing
|
||||
## 自愈能力
|
||||
|
||||
- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min)
|
||||
- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests
|
||||
- **Incident mode**: >50% OPEN → disable exploration, maximize stability
|
||||
- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout
|
||||
- **临时排除**：评分 < 0.2 → 排除 5 分钟（渐进退避，最长 30 分钟）
|
||||
- **熔断器感知**：OPEN → 自动排除；HALF_OPEN → 探测请求
|
||||
- **事故模式**：>50% OPEN → 禁用探索，最大化稳定性
|
||||
- **冷却恢复**：排除结束后，首个请求为"探测"请求，使用缩短的超时时间
|
||||
|
||||
## Bandit Exploration
|
||||
## Bandit 探索
|
||||
|
||||
5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode.
|
||||
5% 的请求（可配置）会被路由到随机服务商进行探索。在事故模式下禁用。
|
||||
|
||||
## API
|
||||
|
||||
```bash
|
||||
# Create auto-combo
|
||||
# 创建 auto-combo
|
||||
curl -X POST http://localhost:20128/api/combos/auto \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'
|
||||
|
||||
# List auto-combos
|
||||
# 列出 auto-combos
|
||||
curl http://localhost:20128/api/combos/auto
|
||||
```
|
||||
|
||||
## Task Fitness
|
||||
## 任务适配度
|
||||
|
||||
30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score).
|
||||
30+ 个模型在 6 种任务类型（`coding`、`review`、`planning`、`analysis`、`debugging`、`documentation`）上进行评分。支持通配符模式（例如 `*-coder` → 高编码得分）。
|
||||
|
||||
## Files
|
||||
## 文件
|
||||
|
||||
| File | Purpose |
|
||||
| :------------------------------------------- | :------------------------------------ |
|
||||
| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization |
|
||||
| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup |
|
||||
| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap |
|
||||
| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode |
|
||||
| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles |
|
||||
| `src/app/api/combos/auto/route.ts` | REST API |
|
||||
| 文件 | 用途 |
|
||||
| :------------------------------------------- | :------------------------ |
|
||||
| `open-sse/services/autoCombo/scoring.ts` | 评分函数 & 池归一化 |
|
||||
| `open-sse/services/autoCombo/taskFitness.ts` | 模型 × 任务适配度查询 |
|
||||
| `open-sse/services/autoCombo/engine.ts` | 选择逻辑、bandit、预算上限 |
|
||||
| `open-sse/services/autoCombo/selfHealing.ts` | 排除、探测、事故模式 |
|
||||
| `open-sse/services/autoCombo/modePacks.ts` | 4 种权重配置 |
|
||||
| `src/app/api/combos/auto/route.ts` | REST API |
|
||||
|
||||
+1286
-1232
File diff suppressed because it is too large
Load Diff
+125
-132
@@ -1,68 +1,81 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../CLI-TOOLS.md) · 🇧🇷 [pt-BR](../pt-BR/CLI-TOOLS.md) · 🇪🇸 [es](../es/CLI-TOOLS.md) · 🇫🇷 [fr](../fr/CLI-TOOLS.md) · 🇩🇪 [de](../de/CLI-TOOLS.md) · 🇮🇹 [it](../it/CLI-TOOLS.md) · 🇷🇺 [ru](../ru/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../zh-CN/CLI-TOOLS.md) · 🇯🇵 [ja](../ja/CLI-TOOLS.md) · 🇰🇷 [ko](../ko/CLI-TOOLS.md) · 🇸🇦 [ar](../ar/CLI-TOOLS.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../CLI-TOOLS.md) · 🇧🇷 [pt-BR](../pt-BR/CLI-TOOLS.md) · 🇪🇸 [es](../es/CLI-TOOLS.md) · 🇫🇷 [fr](../fr/CLI-TOOLS.md) · 🇩🇪 [de](../de/CLI-TOOLS.md) · 🇮🇹 [it](../it/CLI-TOOLS.md) · 🇷🇺 [ru](../ru/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../zh-CN/CLI-TOOLS.md) · 🇯🇵 [ja](../ja/CLI-TOOLS.md) · 🇰🇷 [ko](../ko/CLI-TOOLS.md) · 🇸🇦 [ar](../ar/CLI-TOOLS.md)
|
||||
|
||||
# CLI 工具配置指南 — OmniRoute
|
||||
|
||||
本指南说明如何安装和配置所有支持的 AI CLI 工具，以使用 **OmniRoute** 作为统一后端。
|
||||
|
||||
This guide explains how to install and configure all supported AI coding CLI tools
|
||||
to use **OmniRoute** as the unified backend, giving you centralized key management,
|
||||
cost tracking, model switching, and request logging across every tool.
|
||||
本指南说明如何安装和配置所有支持的 AI 编程 CLI 工具，以使用 **OmniRoute** 作为统一后端，为您提供集中化的密钥管理、成本跟踪、模型切换以及所有工具的请求日志记录。
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI
|
||||
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
|
||||
│
|
||||
▼ (all point to OmniRoute)
|
||||
▼ (所有工具指向 OmniRoute)
|
||||
http://YOUR_SERVER:20128/v1
|
||||
│
|
||||
▼ (OmniRoute routes to the right provider)
|
||||
▼ (OmniRoute 路由到正确的服务商)
|
||||
Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
**优势:**
|
||||
|
||||
- One API key to manage all tools
|
||||
- Cost tracking across all CLIs in the dashboard
|
||||
- Model switching without reconfiguring every tool
|
||||
- Works locally and on remote servers (VPS)
|
||||
- 一个 API 密钥管理所有工具
|
||||
- 在仪表盘中跨所有 CLI 跟踪成本
|
||||
- 无需重新配置每个工具即可切换模型
|
||||
- 本地和远程服务器 (VPS) 均可使用
|
||||
|
||||
---
|
||||
|
||||
## Supported Tools
|
||||
## 支持的工具（以仪表盘为准）
|
||||
|
||||
| Tool | Command | Type | Install Method |
|
||||
| ---------------- | ------------------- | ----------------- | -------------- |
|
||||
| **Claude Code** | `claude` | CLI | npm |
|
||||
| **OpenAI Codex** | `codex` | CLI | npm |
|
||||
| **Gemini CLI** | `gemini` | CLI | npm |
|
||||
| **OpenCode** | `opencode` | CLI | npm |
|
||||
| **Cline** | `cline` | CLI + VS Code ext | npm |
|
||||
| **KiloCode** | `kilocode` / `kilo` | CLI + VS Code ext | npm |
|
||||
| **Continue** | guide-based | VS Code ext | VS Code |
|
||||
| **Kiro CLI** | `kiro-cli` | CLI | curl installer |
|
||||
| **Cursor** | `cursor` | Desktop app | Download |
|
||||
| **Droid** | web-based | Built-in agent | OmniRoute |
|
||||
| **OpenClaw** | web-based | Built-in agent | OmniRoute |
|
||||
仪表盘中 `/dashboard/cli-tools` 的卡片由 `src/shared/constants/cliTools.ts` 生成。
|
||||
当前列表 (v3.0.0-rc.16):
|
||||
|
||||
| 工具 | ID | 命令 | 配置模式 | 安装方式 |
|
||||
| ----------------- | ------------- | ------------ | -------- | ------------ |
|
||||
| **Claude Code** | `claude` | `claude` | env | npm |
|
||||
| **OpenAI Codex** | `codex` | `codex` | custom | npm |
|
||||
| **Factory Droid** | `droid` | `droid` | custom | 内置/CLI |
|
||||
| **OpenClaw** | `openclaw` | `openclaw` | custom | 内置/CLI |
|
||||
| **Cursor** | `cursor` | app | guide | 桌面应用 |
|
||||
| **Cline** | `cline` | `cline` | custom | npm |
|
||||
| **Kilo Code** | `kilo` | `kilocode` | custom | npm |
|
||||
| **Continue** | `continue` | extension | guide | VS Code |
|
||||
| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |
|
||||
| **GitHub Copilot**| `copilot` | extension | custom | VS Code |
|
||||
| **OpenCode** | `opencode` | `opencode` | guide | npm |
|
||||
| **Kiro AI** | `kiro` | app/cli | mitm | 桌面/CLI |
|
||||
|
||||
### CLI 指纹同步（代理 + 设置）
|
||||
|
||||
`/dashboard/agents` 和 `Settings > CLI Fingerprint` 使用 `src/shared/constants/cliCompatProviders.ts`。
|
||||
这确保服务商 ID 与 CLI 卡片和旧版 ID 保持一致。
|
||||
|
||||
| CLI ID | 指纹服务商 ID |
|
||||
| ------ | ------------- |
|
||||
| `kilo` | `kilocode` |
|
||||
| `copilot` | `github` |
|
||||
| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | 相同 ID |
|
||||
|
||||
为兼容性保留的旧版 ID：`copilot`、`kimi-coding`、`qwen`。
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Get an OmniRoute API Key
|
||||
## 第 1 步 — 获取 OmniRoute API 密钥
|
||||
|
||||
1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)
|
||||
2. Click **Create API Key**
|
||||
3. Give it a name (e.g. `cli-tools`) and select all permissions
|
||||
4. Copy the key — you'll need it for every CLI below
|
||||
1. 打开 OmniRoute 仪表盘 → **API Manager** (`/dashboard/api-manager`)
|
||||
2. 点击 **Create API Key**
|
||||
3. 命名（例如 `cli-tools`）并选择所有权限
|
||||
4. 复制密钥 — 下面的每个 CLI 都需要使用
|
||||
|
||||
> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
|
||||
> 密钥格式类似：`sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Install CLI Tools
|
||||
## 第 2 步 — 安装 CLI 工具
|
||||
|
||||
All npm-based tools require Node.js 18+:
|
||||
所有基于 npm 的工具需要 Node.js 18+：
|
||||
|
||||
```bash
|
||||
# Claude Code (Anthropic)
|
||||
@@ -71,9 +84,6 @@ npm install -g @anthropic-ai/claude-code
|
||||
# OpenAI Codex
|
||||
npm install -g @openai/codex
|
||||
|
||||
# Gemini CLI (Google)
|
||||
npm install -g @google/gemini-cli
|
||||
|
||||
# OpenCode
|
||||
npm install -g opencode-ai
|
||||
|
||||
@@ -81,34 +91,33 @@ npm install -g opencode-ai
|
||||
npm install -g cline
|
||||
|
||||
# KiloCode
|
||||
npm install -g kilecode
|
||||
npm install -g kilocode
|
||||
|
||||
# Kiro CLI (Amazon — requires curl + unzip)
|
||||
apt-get install -y unzip # on Debian/Ubuntu
|
||||
# Kiro CLI (Amazon — 需要 curl + unzip)
|
||||
apt-get install -y unzip # Debian/Ubuntu
|
||||
curl -fsSL https://cli.kiro.dev/install | bash
|
||||
export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc
|
||||
export PATH="$HOME/.local/bin:$PATH" # 添加到 ~/.bashrc
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
**验证:**
|
||||
|
||||
```bash
|
||||
claude --version # 2.x.x
|
||||
codex --version # 0.x.x
|
||||
gemini --version # 0.x.x
|
||||
opencode --version # x.x.x
|
||||
cline --version # 2.x.x
|
||||
kilocode --version # x.x.x (or: kilo --version)
|
||||
kilocode --version # x.x.x (或: kilo --version)
|
||||
kiro-cli --version # 1.x.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Set Global Environment Variables
|
||||
## 第 3 步 — 设置全局环境变量
|
||||
|
||||
Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:
|
||||
添加到 `~/.bashrc`（或 `~/.zshrc`），然后运行 `source ~/.bashrc`：
|
||||
|
||||
```bash
|
||||
# OmniRoute Universal Endpoint
|
||||
# OmniRoute 统一端点
|
||||
export OPENAI_BASE_URL="http://localhost:20128/v1"
|
||||
export OPENAI_API_KEY="sk-your-omniroute-key"
|
||||
export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
|
||||
@@ -117,20 +126,20 @@ export GEMINI_BASE_URL="http://localhost:20128/v1"
|
||||
export GEMINI_API_KEY="sk-your-omniroute-key"
|
||||
```
|
||||
|
||||
> For a **remote server** replace `localhost:20128` with the server IP or domain,
|
||||
> e.g. `http://192.168.0.15:20128`.
|
||||
> 对于**远程服务器**，将 `localhost:20128` 替换为服务器 IP 或域名，
|
||||
> 例如 `http://192.168.0.15:20128`。
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Configure Each Tool
|
||||
## 第 4 步 — 配置各工具
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
# Via CLI:
|
||||
# 通过 CLI:
|
||||
claude config set --global api-base-url http://localhost:20128/v1
|
||||
|
||||
# Or create ~/.claude/settings.json:
|
||||
# 或创建 ~/.claude/settings.json:
|
||||
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
|
||||
{
|
||||
"apiBaseUrl": "http://localhost:20128/v1",
|
||||
@@ -139,7 +148,7 @@ mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `claude "say hello"`
|
||||
**测试:** `claude "say hello"`
|
||||
|
||||
---
|
||||
|
||||
@@ -153,22 +162,7 @@ apiBaseUrl: http://localhost:20128/v1
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `codex "what is 2+2?"`
|
||||
|
||||
---
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF
|
||||
{
|
||||
"apiKey": "sk-your-omniroute-key",
|
||||
"baseUrl": "http://localhost:20128/v1"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `gemini "hello"`
|
||||
**测试:** `codex "what is 2+2?"`
|
||||
|
||||
---
|
||||
|
||||
@@ -182,13 +176,13 @@ api_key = "sk-your-omniroute-key"
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `opencode`
|
||||
**测试:** `opencode`
|
||||
|
||||
---
|
||||
|
||||
### Cline (CLI or VS Code)
|
||||
### Cline (CLI 或 VS Code)
|
||||
|
||||
**CLI mode:**
|
||||
**CLI 模式:**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
|
||||
@@ -200,22 +194,22 @@ mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
|
||||
EOF
|
||||
```
|
||||
|
||||
**VS Code mode:**
|
||||
Cline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`
|
||||
**VS Code 模式:**
|
||||
Cline 扩展设置 → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`
|
||||
|
||||
Or use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.
|
||||
或使用 OmniRoute 仪表盘 → **CLI Tools → Cline → Apply Config**。
|
||||
|
||||
---
|
||||
|
||||
### KiloCode (CLI or VS Code)
|
||||
### KiloCode (CLI 或 VS Code)
|
||||
|
||||
**CLI mode:**
|
||||
**CLI 模式:**
|
||||
|
||||
```bash
|
||||
kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
|
||||
```
|
||||
|
||||
**VS Code settings:**
|
||||
**VS Code 设置:**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -224,13 +218,13 @@ kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
|
||||
}
|
||||
```
|
||||
|
||||
Or use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.
|
||||
或使用 OmniRoute 仪表盘 → **CLI Tools → KiloCode → Apply Config**。
|
||||
|
||||
---
|
||||
|
||||
### Continue (VS Code Extension)
|
||||
### Continue (VS Code 扩展)
|
||||
|
||||
Edit `~/.continue/config.yaml`:
|
||||
编辑 `~/.continue/config.yaml`:
|
||||
|
||||
```yaml
|
||||
models:
|
||||
@@ -242,103 +236,102 @@ models:
|
||||
default: true
|
||||
```
|
||||
|
||||
Restart VS Code after editing.
|
||||
编辑后重启 VS Code。
|
||||
|
||||
---
|
||||
|
||||
### Kiro CLI (Amazon)
|
||||
|
||||
```bash
|
||||
# Login to your AWS/Kiro account:
|
||||
# 登录您的 AWS/Kiro 账户:
|
||||
kiro-cli login
|
||||
|
||||
# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.
|
||||
# Use kiro-cli alongside OmniRoute for other tools.
|
||||
# CLI 使用自有认证 — Kiro CLI 本身不需要 OmniRoute 作为后端。
|
||||
# 将 kiro-cli 与其他工具的 OmniRoute 一起使用。
|
||||
kiro-cli status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cursor (Desktop App)
|
||||
### Cursor (桌面应用)
|
||||
|
||||
> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
|
||||
> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.
|
||||
> **注意:** Cursor 通过其云端路由请求。对于 OmniRoute 集成，
|
||||
> 在 OmniRoute Settings 中启用 **Cloud Endpoint** 并使用您的公共域名 URL。
|
||||
|
||||
Via GUI: **Settings → Models → OpenAI API Key**
|
||||
通过 GUI: **Settings → Models → OpenAI API Key**
|
||||
|
||||
- Base URL: `https://your-domain.com/v1`
|
||||
- API Key: your OmniRoute key
|
||||
- API Key: 您的 OmniRoute 密钥
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Auto-Configuration
|
||||
## 仪表盘自动配置
|
||||
|
||||
The OmniRoute dashboard automates configuration for most tools:
|
||||
OmniRoute 仪表盘可自动配置大多数工具：
|
||||
|
||||
1. Go to `http://localhost:20128/dashboard/cli-tools`
|
||||
2. Expand any tool card
|
||||
3. Select your API key from the dropdown
|
||||
4. Click **Apply Config** (if tool is detected as installed)
|
||||
5. Or copy the generated config snippet manually
|
||||
1. 前往 `http://localhost:20128/dashboard/cli-tools`
|
||||
2. 展开任意工具卡片
|
||||
3. 从下拉菜单选择您的 API 密钥
|
||||
4. 点击 **Apply Config**（如果检测到工具已安装）
|
||||
5. 或手动复制生成的配置片段
|
||||
|
||||
---
|
||||
|
||||
## Built-in Agents: Droid & OpenClaw
|
||||
## 内置代理：Droid & OpenClaw
|
||||
|
||||
**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.
|
||||
They run as internal routes and use OmniRoute's model routing automatically.
|
||||
**Droid** 和 **OpenClaw** 是直接内置于 OmniRoute 的 AI 代理 — 无需安装。
|
||||
它们作为内部路由运行，自动使用 OmniRoute 的模型路由。
|
||||
|
||||
- Access: `http://localhost:20128/dashboard/agents`
|
||||
- Configure: same combos and providers as all other tools
|
||||
- No API key or CLI install required
|
||||
- 访问：`http://localhost:20128/dashboard/agents`
|
||||
- 配置：与所有其他工具使用相同的组合和服务商
|
||||
- 无需 API 密钥或 CLI 安装
|
||||
|
||||
---
|
||||
|
||||
## Available API Endpoints
|
||||
## 可用 API 端点
|
||||
|
||||
| Endpoint | Description | Use For |
|
||||
| -------------------------- | ----------------------------- | --------------------------- |
|
||||
| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |
|
||||
| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |
|
||||
| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |
|
||||
| `/v1/embeddings` | Text embeddings | RAG, search |
|
||||
| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. |
|
||||
| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |
|
||||
| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |
|
||||
| 端点 | 描述 | 用途 |
|
||||
| -------------------------- | ------------------------ | -------------------------- |
|
||||
| `/v1/chat/completions` | 标准聊天（所有服务商） | 所有现代工具 |
|
||||
| `/v1/responses` | Responses API（OpenAI 格式）| Codex、代理工作流 |
|
||||
| `/v1/completions` | 旧版文本补全 | 使用 `prompt:` 的旧工具 |
|
||||
| `/v1/embeddings` | 文本嵌入 | RAG、搜索 |
|
||||
| `/v1/images/generations` | 图像生成 | DALL-E、Flux 等 |
|
||||
| `/v1/audio/speech` | 文本转语音 | ElevenLabs、OpenAI TTS |
|
||||
| `/v1/audio/transcriptions` | 语音转文字 | Deepgram、AssemblyAI |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
## 故障排除
|
||||
|
||||
| Error | Cause | Fix |
|
||||
| ------------------------- | ----------------------- | ------------------------------------------ |
|
||||
| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |
|
||||
| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |
|
||||
| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |
|
||||
| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |
|
||||
| CLI shows "not installed" | Binary not in PATH | Check `which <command>` |
|
||||
| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` |
|
||||
| 错误 | 原因 | 解决方案 |
|
||||
| ------------------------- | --------------------- | ------------------------------------------ |
|
||||
| `Connection refused` | OmniRoute 未运行 | `pm2 start omniroute` |
|
||||
| `401 Unauthorized` | API 密钥错误 | 在 `/dashboard/api-manager` 检查 |
|
||||
| `No combo configured` | 无活动路由组合 | 在 `/dashboard/combos` 设置 |
|
||||
| `invalid model` | 模型不在目录中 | 使用 `auto` 或检查 `/dashboard/providers` |
|
||||
| CLI 显示 "not installed" | 二进制文件不在 PATH 中| 检查 `which <command>` |
|
||||
| `kiro-cli: not found` | 不在 PATH 中 | `export PATH="$HOME/.local/bin:$PATH"` |
|
||||
|
||||
---
|
||||
|
||||
## Quick Setup Script (One Command)
|
||||
## 快速设置脚本（一条命令）
|
||||
|
||||
```bash
|
||||
# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
|
||||
# 安装所有 CLI 并为 OmniRoute 配置（替换为您的密钥和服务器 URL）
|
||||
OMNIROUTE_URL="http://localhost:20128/v1"
|
||||
OMNIROUTE_KEY="sk-your-omniroute-key"
|
||||
|
||||
npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode
|
||||
npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode
|
||||
|
||||
# Kiro CLI
|
||||
apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
|
||||
|
||||
# Write configs
|
||||
mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue
|
||||
# 写入配置
|
||||
mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue
|
||||
|
||||
cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
|
||||
cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
|
||||
cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}"
|
||||
cat >> ~/.bashrc << EOF
|
||||
export OPENAI_BASE_URL="$OMNIROUTE_URL"
|
||||
export OPENAI_API_KEY="$OMNIROUTE_KEY"
|
||||
@@ -347,5 +340,5 @@ export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
|
||||
EOF
|
||||
|
||||
source ~/.bashrc
|
||||
echo "✅ All CLIs installed and configured for OmniRoute"
|
||||
echo "✅ 所有 CLI 已安装并配置为使用 OmniRoute"
|
||||
```
|
||||
|
||||
@@ -1,44 +1,40 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../es/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../fr/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../de/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../it/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../ru/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../ja/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../ko/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../ar/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [in](../in/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../th/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../vi/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../id/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../ms/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../nl/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../pl/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../sv/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../no/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../da/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../fi/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../pt/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../ro/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../hu/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../bg/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../sk/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../he/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../phi/CODEBASE_DOCUMENTATION.md)
|
||||
# OmniRoute — 代码库文档
|
||||
|
||||
🌐 **语言:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) | 🇨🇿 [Čeština](../cs/CODEBASE_DOCUMENTATION.md)
|
||||
|
||||
> **OmniRoute** 多提供商 AI 代理路由器的全面新手友好指南。
|
||||
|
||||
---
|
||||
|
||||
# omniroute — Codebase Documentation
|
||||
## 1. OmniRoute 是什么？
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md)
|
||||
OmniRoute 是一个**代理路由器**，位于 AI 客户端（Claude CLI、Codex、Cursor IDE 等）和 AI 提供商（Anthropic、Google、OpenAI、AWS、GitHub 等）之间。它解决了一个大问题：
|
||||
|
||||
> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
|
||||
> **不同的 AI 客户端使用不同的"语言"（API 格式），不同的 AI 提供商也期望不同的"语言"。** OmniRoute 自动在它们之间进行翻译。
|
||||
|
||||
可以把它想象成联合国的万能翻译员 — 任何代表都可以说任何语言，翻译员会为任何其他代表进行转换。
|
||||
|
||||
---
|
||||
|
||||
## 1. What Is omniroute?
|
||||
|
||||
omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
|
||||
|
||||
> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
|
||||
|
||||
Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture Overview
|
||||
## 2. 架构概述
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Clients
|
||||
subgraph Clients[客户端]
|
||||
A[Claude CLI]
|
||||
B[Codex]
|
||||
C[Cursor IDE]
|
||||
D[OpenAI-compatible]
|
||||
D[OpenAI 兼容]
|
||||
end
|
||||
|
||||
subgraph omniroute
|
||||
E[Handler Layer]
|
||||
F[Translator Layer]
|
||||
G[Executor Layer]
|
||||
H[Services Layer]
|
||||
subgraph omniroute[OmniRoute]
|
||||
E[处理器层]
|
||||
F[翻译器层]
|
||||
G[执行器层]
|
||||
H[服务层]
|
||||
end
|
||||
|
||||
subgraph Providers
|
||||
subgraph Providers[提供商]
|
||||
I[Anthropic Claude]
|
||||
J[Google Gemini]
|
||||
K[OpenAI / Codex]
|
||||
@@ -65,90 +61,90 @@ graph LR
|
||||
H -.-> G
|
||||
```
|
||||
|
||||
### Core Principle: Hub-and-Spoke Translation
|
||||
### 核心原则：中心辐射翻译
|
||||
|
||||
All format translation passes through **OpenAI format as the hub**:
|
||||
所有格式翻译都通过 **OpenAI 格式作为中心** 进行：
|
||||
|
||||
```
|
||||
Client Format → [OpenAI Hub] → Provider Format (request)
|
||||
Provider Format → [OpenAI Hub] → Client Format (response)
|
||||
客户端格式 → [OpenAI 中心] → 提供商格式 （请求）
|
||||
提供商格式 → [OpenAI 中心] → 客户端格式 （响应）
|
||||
```
|
||||
|
||||
This means you only need **N translators** (one per format) instead of **N²** (every pair).
|
||||
这意味着你只需要 **N 个翻译器**（每种格式一个）而不是 **N²**（每对格式一个）。
|
||||
|
||||
---
|
||||
|
||||
## 3. Project Structure
|
||||
## 3. 项目结构
|
||||
|
||||
```
|
||||
omniroute/
|
||||
├── open-sse/ ← Core proxy library (portable, framework-agnostic)
|
||||
│ ├── index.js ← Main entry point, exports everything
|
||||
│ ├── config/ ← Configuration & constants
|
||||
│ ├── executors/ ← Provider-specific request execution
|
||||
│ ├── handlers/ ← Request handling orchestration
|
||||
│ ├── services/ ← Business logic (auth, models, fallback, usage)
|
||||
│ ├── translator/ ← Format translation engine
|
||||
│ │ ├── request/ ← Request translators (8 files)
|
||||
│ │ ├── response/ ← Response translators (7 files)
|
||||
│ │ └── helpers/ ← Shared translation utilities (6 files)
|
||||
│ └── utils/ ← Utility functions
|
||||
├── src/ ← Application layer (Express/Worker runtime)
|
||||
│ ├── app/ ← Web UI, API routes, middleware
|
||||
│ ├── lib/ ← Database, auth, and shared library code
|
||||
│ ├── mitm/ ← Man-in-the-middle proxy utilities
|
||||
│ ├── models/ ← Database models
|
||||
│ ├── shared/ ← Shared utilities (wrappers around open-sse)
|
||||
│ ├── sse/ ← SSE endpoint handlers
|
||||
│ └── store/ ← State management
|
||||
├── data/ ← Runtime data (credentials, logs)
|
||||
│ └── provider-credentials.json (external credentials override, gitignored)
|
||||
└── tester/ ← Test utilities
|
||||
├── open-sse/ ← 核心代理库（可移植，框架无关）
|
||||
│ ├── index.js ← 主入口点，导出所有内容
|
||||
│ ├── config/ ← 配置和常量
|
||||
│ ├── executors/ ← 提供商特定的请求执行
|
||||
│ ├── handlers/ ← 请求处理编排
|
||||
│ ├── services/ ← 业务逻辑（认证、模型、后备、用量）
|
||||
│ ├── translator/ ← 格式翻译引擎
|
||||
│ │ ├── request/ ← 请求翻译器（8 个文件）
|
||||
│ │ ├── response/ ← 响应翻译器（7 个文件）
|
||||
│ │ └── helpers/ ← 共享翻译工具（6 个文件）
|
||||
│ └── utils/ ← 工具函数
|
||||
├── src/ ← 应用层（Express/Worker 运行时）
|
||||
│ ├── app/ ← Web UI、API 路由、中间件
|
||||
│ ├── lib/ ← 数据库、认证和共享库代码
|
||||
│ ├── mitm/ ← 中间人代理工具
|
||||
│ ├── models/ ← 数据库模型
|
||||
│ ├── shared/ ← 共享工具（open-sse 的包装器）
|
||||
│ ├── sse/ ← SSE 端点处理器
|
||||
│ └── store/ ← 状态管理
|
||||
├── data/ ← 运行时数据（凭证、日志）
|
||||
│ └── provider-credentials.json （外部凭证覆盖，已 gitignore）
|
||||
└── tester/ ← 测试工具
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Module-by-Module Breakdown
|
||||
## 4. 模块逐一分解
|
||||
|
||||
### 4.1 Config (`open-sse/config/`)
|
||||
### 4.1 配置（`open-sse/config/`）
|
||||
|
||||
The **single source of truth** for all provider configuration.
|
||||
所有提供商配置的**单一事实来源**。
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
|
||||
| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. |
|
||||
| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. |
|
||||
| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). |
|
||||
| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. |
|
||||
| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). |
|
||||
| 文件 | 用途 |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `constants.ts` | `PROVIDERS` 对象，包含每个提供商的基础 URL、OAuth 凭证（默认值）、请求头和默认系统提示词。还定义了 `HTTP_STATUS`、`ERROR_TYPES`、`COOLDOWN_MS`、`BACKOFF_CONFIG` 和 `SKIP_PATTERNS`。 |
|
||||
| `credentialLoader.ts` | 从 `data/provider-credentials.json` 加载外部凭证，并合并覆盖 `PROVIDERS` 中的硬编码默认值。在保持向后兼容性的同时将密钥保持在源代码控制之外。 |
|
||||
| `providerModels.ts` | 中央模型注册表：将提供商别名映射到模型 ID。函数如 `getModels()`、`getProviderByAlias()`。 |
|
||||
| `codexInstructions.ts` | 注入到 Codex 请求中的系统指令（编辑约束、沙箱规则、审批策略）。 |
|
||||
| `defaultThinkingSignature.ts` | Claude 和 Gemini 模型的默认"thinking"签名。 |
|
||||
| `ollamaModels.ts` | 本地 Ollama 模型的模式定义（名称、大小、家族、量化）。 |
|
||||
|
||||
#### Credential Loading Flow
|
||||
#### 凭证加载流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
|
||||
B --> C{"data/provider-credentials.json\nexists?"}
|
||||
C -->|Yes| D["credentialLoader reads JSON"]
|
||||
C -->|No| E["Use hardcoded defaults"]
|
||||
D --> F{"For each provider in JSON"}
|
||||
F --> G{"Provider exists\nin PROVIDERS?"}
|
||||
G -->|No| H["Log warning, skip"]
|
||||
G -->|Yes| I{"Value is object?"}
|
||||
I -->|No| J["Log warning, skip"]
|
||||
I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
|
||||
A["应用启动"] --> B["constants.ts 定义 PROVIDERS\n使用硬编码默认值"]
|
||||
B --> C{"data/provider-credentials.json\n存在？"}
|
||||
C -->|是| D["credentialLoader 读取 JSON"]
|
||||
C -->|否| E["使用硬编码默认值"]
|
||||
D --> F{"对于 JSON 中的每个提供商"}
|
||||
F --> G{"提供商存在于\nPROVIDERS 中？"}
|
||||
G -->|否| H["记录警告，跳过"]
|
||||
G -->|是| I{"值是对象？"}
|
||||
I -->|否| J["记录警告，跳过"]
|
||||
I -->|是| K["合并 clientId、clientSecret、\ntokenUrl、authUrl、refreshUrl"]
|
||||
K --> F
|
||||
H --> F
|
||||
J --> F
|
||||
F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
|
||||
F -->|完成| L["PROVIDERS 准备好\n使用合并后的凭证"]
|
||||
E --> L
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Executors (`open-sse/executors/`)
|
||||
### 4.2 执行器（`open-sse/executors/`）
|
||||
|
||||
Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
|
||||
执行器使用**策略模式**封装**提供商特定逻辑**。每个执行器根据需要覆盖基类方法。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
@@ -198,161 +194,161 @@ classDiagram
|
||||
BaseExecutor <|-- GithubExecutor
|
||||
```
|
||||
|
||||
| Executor | Provider | Key Specializations |
|
||||
| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh |
|
||||
| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers |
|
||||
| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
|
||||
| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing |
|
||||
| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters |
|
||||
| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh |
|
||||
| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking |
|
||||
| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation |
|
||||
| `index.ts` | — | Factory: maps provider name → executor class, with default fallback |
|
||||
| 执行器 | 提供商 | 关键特性 |
|
||||
| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------ |
|
||||
| `base.ts` | — | 抽象基类：URL 构建、请求头、重试逻辑、凭证刷新 |
|
||||
| `default.ts` | Claude、Gemini、OpenAI、GLM、Kimi、MiniMax | 标准提供商的通用 OAuth Token 刷新 |
|
||||
| `antigravity.ts` | Google Cloud Code | 项目/会话 ID 生成、多 URL 后备、从错误消息解析自定义重试（"reset after 2h7m23s"） |
|
||||
| `cursor.ts` | Cursor IDE | **最复杂**：SHA-256 校验和认证、Protobuf 请求编码、二进制 EventStream → SSE 响应解析 |
|
||||
| `codex.ts` | OpenAI Codex | 注入系统指令、管理 Thinking 级别、移除不支持的参数 |
|
||||
| `gemini-cli.ts` | Google Gemini CLI | 自定义 URL 构建（`streamGenerateContent`）、Google OAuth Token 刷新 |
|
||||
| `github.ts` | GitHub Copilot | 双 Token 系统（GitHub OAuth + Copilot Token）、模拟 VSCode 请求头 |
|
||||
| `kiro.ts` | AWS CodeWhisperer | AWS EventStream 二进制解析、AMZN 事件帧、Token 估算 |
|
||||
| `index.ts` | — | 工厂：将提供商名称映射到执行器类，带默认后备 |
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Handlers (`open-sse/handlers/`)
|
||||
### 4.3 处理器（`open-sse/handlers/`）
|
||||
|
||||
The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
|
||||
**编排层** — 协调翻译、执行、流式传输和错误处理。
|
||||
|
||||
| File | Purpose |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
|
||||
| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. |
|
||||
| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. |
|
||||
| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. |
|
||||
| 文件 | 用途 |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `chatCore.ts` | **中央编排器**（约 600 行）。处理完整的请求生命周期：格式检测 → 翻译 → 执行器调度 → 流式/非流式响应 → Token 刷新 → 错误处理 → 用量日志。 |
|
||||
| `responsesHandler.ts` | OpenAI Responses API 适配器：将 Responses 格式 → Chat Completions → 发送到 `chatCore` → 将 SSE 转换回 Responses 格式。 |
|
||||
| `embeddings.ts` | Embedding 生成处理器：解析 Embedding 模型 → 提供商，调度到提供商 API，返回 OpenAI 兼容的 Embedding 响应。支持 6+ 个提供商。 |
|
||||
| `imageGeneration.ts` | 图像生成处理器：解析图像模型 → 提供商，支持 OpenAI 兼容、Gemini-image（Antigravity）和后备（Nebius）模式。返回 base64 或 URL 图像。 |
|
||||
|
||||
#### Request Lifecycle (chatCore.ts)
|
||||
#### 请求生命周期（chatCore.ts）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Client as 客户端
|
||||
participant chatCore
|
||||
participant Translator
|
||||
participant Executor
|
||||
participant Provider
|
||||
participant Translator as 翻译器
|
||||
participant Executor as 执行器
|
||||
participant Provider as 提供商
|
||||
|
||||
Client->>chatCore: Request (any format)
|
||||
chatCore->>chatCore: Detect source format
|
||||
chatCore->>chatCore: Check bypass patterns
|
||||
chatCore->>chatCore: Resolve model & provider
|
||||
chatCore->>Translator: Translate request (source → OpenAI → target)
|
||||
chatCore->>Executor: Get executor for provider
|
||||
Executor->>Executor: Build URL, headers, transform request
|
||||
Executor->>Executor: Refresh credentials if needed
|
||||
Executor->>Provider: HTTP fetch (streaming or non-streaming)
|
||||
Client->>chatCore: 请求（任何格式）
|
||||
chatCore->>chatCore: 检测源格式
|
||||
chatCore->>chatCore: 检查 bypass 模式
|
||||
chatCore->>chatCore: 解析模型和提供商
|
||||
chatCore->>Translator: 翻译请求（源 → OpenAI → 目标）
|
||||
chatCore->>Executor: 获取提供商的执行器
|
||||
Executor->>Executor: 构建 URL、请求头、转换请求
|
||||
Executor->>Executor: 如需要则刷新凭证
|
||||
Executor->>Provider: HTTP fetch（流式或非流式）
|
||||
|
||||
alt Streaming
|
||||
Provider-->>chatCore: SSE stream
|
||||
chatCore->>chatCore: Pipe through SSE transform stream
|
||||
Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
|
||||
chatCore-->>Client: Translated SSE stream
|
||||
else Non-streaming
|
||||
Provider-->>chatCore: JSON response
|
||||
chatCore->>Translator: Translate response
|
||||
chatCore-->>Client: Translated JSON
|
||||
alt 流式传输
|
||||
Provider-->>chatCore: SSE 流
|
||||
chatCore->>chatCore: 通过 SSE 转换流管道
|
||||
Note over chatCore: 转换流翻译<br/>每个块：目标 → OpenAI → 源
|
||||
chatCore-->>Client: 已翻译的 SSE 流
|
||||
else 非流式传输
|
||||
Provider-->>chatCore: JSON 响应
|
||||
chatCore->>Translator: 翻译响应
|
||||
chatCore-->>Client: 已翻译的 JSON
|
||||
end
|
||||
|
||||
alt Error (401, 429, 500...)
|
||||
chatCore->>Executor: Retry with credential refresh
|
||||
chatCore->>chatCore: Account fallback logic
|
||||
alt 错误 (401, 429, 500...)
|
||||
chatCore->>Executor: 带凭证刷新重试
|
||||
chatCore->>chatCore: 账户后备逻辑
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Services (`open-sse/services/`)
|
||||
### 4.4 服务（`open-sse/services/`）
|
||||
|
||||
Business logic that supports the handlers and executors.
|
||||
支持处理器和执行器的业务逻辑。
|
||||
|
||||
| File | Purpose |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
|
||||
| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. |
|
||||
| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). |
|
||||
| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. |
|
||||
| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. |
|
||||
| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). |
|
||||
| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. |
|
||||
| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. |
|
||||
| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. |
|
||||
| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. |
|
||||
| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. |
|
||||
| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. |
|
||||
| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. |
|
||||
| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. |
|
||||
| 文件 | 用途 |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider.ts` | **格式检测**（`detectFormat`）：分析请求体结构以识别 Claude/OpenAI/Gemini/Antigravity/Responses 格式（包括 Claude 的 `max_tokens` 启发式）。还有：URL 构建、请求头构建、Thinking 配置规范化。支持 `openai-compatible-*` 和 `anthropic-compatible-*` 动态提供商。 |
|
||||
| `model.ts` | 模型字符串解析（`claude/model-name` → `{provider: "claude", model: "model-name"}`）、带冲突检测的别名解析、输入清理（拒绝路径遍历/控制字符）、以及支持异步别名获取器的模型信息解析。 |
|
||||
| `accountFallback.ts` | 速率限制处理：指数退避（1s → 2s → 4s → 最大 2 分钟）、账户冷却管理、错误分类（哪些错误触发后备，哪些不触发）。 |
|
||||
| `tokenRefresh.ts` | **每个提供商**的 OAuth Token 刷新：Google（Gemini、Antigravity）、Claude、Codex、Qwen、Qoder、GitHub（OAuth + Copilot 双 Token）、Kiro（AWS SSO OIDC + 社交认证）。包括进行中 Promise 去重缓存和指数退避重试。 |
|
||||
| `combo.ts` | **Combo 模型**：后备模型链。如果模型 A 因可后备错误失败，尝试模型 B，然后 C，依此类推。返回实际的上游状态码。 |
|
||||
| `usage.ts` | 从提供商 API 获取配额/用量数据（GitHub Copilot 配额、Antigravity 模型配额、Codex 速率限制、Kiro 用量明细、Claude 设置）。 |
|
||||
| `accountSelector.ts` | 智能账户选择与评分算法：考虑优先级、健康状态、轮询位置和冷却状态，为每个请求选择最优账户。 |
|
||||
| `contextManager.ts` | 请求上下文生命周期管理：创建和追踪带有元数据（请求 ID、时间戳、提供商信息）的每请求上下文对象，用于调试和日志。 |
|
||||
| `ipFilter.ts` | 基于 IP 的访问控制：支持白名单和黑名单模式。在处理 API 请求前根据配置规则验证客户端 IP。 |
|
||||
| `sessionManager.ts` | 带客户端指纹的会话追踪：使用哈希客户端标识符追踪活动会话、监控请求计数、提供会话指标。 |
|
||||
| `signatureCache.ts` | 基于请求签名的去重缓存：通过缓存近期请求签名并在时间窗口内为相同请求返回缓存响应来防止重复请求。 |
|
||||
| `systemPrompt.ts` | 全局系统提示词注入：在所有请求前置或追加可配置的系统提示词，带每提供商兼容性处理。 |
|
||||
| `thinkingBudget.ts` | 推理 Token 预算管理：支持 passthrough（透传）、auto（剥离 Thinking 配置）、custom（固定预算）和 adaptive（复杂度缩放）模式来控制 Thinking/推理 Token。 |
|
||||
| `wildcardRouter.ts` | 通配符模型模式路由：根据可用性和优先级将通配符模式（如 `*/claude-*`）解析为具体的提供商/模型对。 |
|
||||
|
||||
#### Token Refresh Deduplication
|
||||
#### Token 刷新去重
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R1 as Request 1
|
||||
participant R2 as Request 2
|
||||
participant R1 as 请求 1
|
||||
participant R2 as 请求 2
|
||||
participant Cache as refreshPromiseCache
|
||||
participant OAuth as OAuth Provider
|
||||
participant OAuth as OAuth 提供商
|
||||
|
||||
R1->>Cache: getAccessToken("gemini", token)
|
||||
Cache->>Cache: No in-flight promise
|
||||
Cache->>OAuth: Start refresh
|
||||
Cache->>Cache: 无进行中 Promise
|
||||
Cache->>OAuth: 开始刷新
|
||||
R2->>Cache: getAccessToken("gemini", token)
|
||||
Cache->>Cache: Found in-flight promise
|
||||
Cache-->>R2: Return existing promise
|
||||
OAuth-->>Cache: New access token
|
||||
Cache-->>R1: New access token
|
||||
Cache-->>R2: Same access token (shared)
|
||||
Cache->>Cache: Delete cache entry
|
||||
Cache->>Cache: 找到进行中 Promise
|
||||
Cache-->>R2: 返回现有 Promise
|
||||
OAuth-->>Cache: 新访问 Token
|
||||
Cache-->>R1: 新访问 Token
|
||||
Cache-->>R2: 相同访问 Token（共享）
|
||||
Cache->>Cache: 删除缓存条目
|
||||
```
|
||||
|
||||
#### Account Fallback State Machine
|
||||
#### 账户后备状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
Active --> Error: Request fails (401/429/500)
|
||||
Error --> Cooldown: Apply backoff
|
||||
Cooldown --> Active: Cooldown expires
|
||||
Active --> Active: Request succeeds (reset backoff)
|
||||
Active --> Error: 请求失败 (401/429/500)
|
||||
Error --> Cooldown: 应用退避
|
||||
Cooldown --> Active: 冷却过期
|
||||
Active --> Active: 请求成功（重置退避）
|
||||
|
||||
state Error {
|
||||
[*] --> ClassifyError
|
||||
ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
|
||||
ClassifyError --> NoFallback: 400 Bad Request
|
||||
ClassifyError --> ShouldFallback: 速率限制 / 认证 / 瞬态
|
||||
ClassifyError --> NoFallback: 400 错误请求
|
||||
}
|
||||
|
||||
state Cooldown {
|
||||
[*] --> ExponentialBackoff
|
||||
ExponentialBackoff: Level 0 = 1s
|
||||
ExponentialBackoff: Level 1 = 2s
|
||||
ExponentialBackoff: Level 2 = 4s
|
||||
ExponentialBackoff: Max = 2min
|
||||
ExponentialBackoff: 级别 0 = 1s
|
||||
ExponentialBackoff: 级别 1 = 2s
|
||||
ExponentialBackoff: 级别 2 = 4s
|
||||
ExponentialBackoff: 最大 = 2min
|
||||
}
|
||||
```
|
||||
|
||||
#### Combo Model Chain
|
||||
#### Combo 模型链
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Request with\ncombo model"] --> B["Model A"]
|
||||
B -->|"2xx Success"| C["Return response"]
|
||||
B -->|"429/401/500"| D{"Fallback\neligible?"}
|
||||
D -->|Yes| E["Model B"]
|
||||
D -->|No| F["Return error"]
|
||||
E -->|"2xx Success"| C
|
||||
E -->|"429/401/500"| G{"Fallback\neligible?"}
|
||||
G -->|Yes| H["Model C"]
|
||||
G -->|No| F
|
||||
H -->|"2xx Success"| C
|
||||
H -->|"Fail"| I["All failed →\nReturn last status"]
|
||||
A["带 Combo 模型的请求"] --> B["模型 A"]
|
||||
B -->|"2xx 成功"| C["返回响应"]
|
||||
B -->|"429/401/500"| D{"可后备？"}
|
||||
D -->|是| E["模型 B"]
|
||||
D -->|否| F["返回错误"]
|
||||
E -->|"2xx 成功"| C
|
||||
E -->|"429/401/500"| G{"可后备？"}
|
||||
G -->|是| H["模型 C"]
|
||||
G -->|否| F
|
||||
H -->|"2xx 成功"| C
|
||||
H -->|"失败"| I["全部失败 →\n返回最后状态"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Translator (`open-sse/translator/`)
|
||||
### 4.5 翻译器（`open-sse/translator/`）
|
||||
|
||||
The **format translation engine** using a self-registering plugin system.
|
||||
使用自注册插件系统的**格式翻译引擎**。
|
||||
|
||||
#### Architecture
|
||||
#### 架构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
@@ -378,40 +374,40 @@ graph TD
|
||||
end
|
||||
```
|
||||
|
||||
| Directory | Files | Description |
|
||||
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. |
|
||||
| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. |
|
||||
| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
|
||||
| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. |
|
||||
| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. |
|
||||
| 目录 | 文件数 | 描述 |
|
||||
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `request/` | 8 个翻译器 | 在不同格式之间转换请求体。每个文件在导入时通过 `register(from, to, fn)` 自注册。 |
|
||||
| `response/` | 7 个翻译器 | 在不同格式之间转换流式响应块。处理 SSE 事件类型、thinking 块、工具调用。 |
|
||||
| `helpers/` | 6 个辅助工具 | 共享工具：`claudeHelper`（系统提示词提取、thinking 配置）、`geminiHelper`（parts/contents 映射）、`openaiHelper`（格式过滤）、`toolCallHelper`（ID 生成、缺失响应注入）、`maxTokensHelper`、`responsesApiHelper`。 |
|
||||
| `index.ts` | — | 翻译引擎：`translateRequest()`、`translateResponse()`、状态管理、注册表。 |
|
||||
| `formats.ts` | — | 格式常量：`OPENAI`、`CLAUDE`、`GEMINI`、`ANTIGRAVITY`、`KIRO`、`CURSOR`、`OPENAI_RESPONSES`。 |
|
||||
|
||||
#### Key Design: Self-Registering Plugins
|
||||
#### 关键设计：自注册插件
|
||||
|
||||
```javascript
|
||||
// Each translator file calls register() on import:
|
||||
// 每个翻译器文件在导入时调用 register()：
|
||||
import { register } from "../index.js";
|
||||
register("claude", "openai", translateClaudeToOpenAI);
|
||||
|
||||
// The index.js imports all translator files, triggering registration:
|
||||
import "./request/claude-to-openai.js"; // ← self-registers
|
||||
// index.js 导入所有翻译器文件，触发注册：
|
||||
import "./request/claude-to-openai.js"; // ← 自注册
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Utils (`open-sse/utils/`)
|
||||
### 4.6 工具 (`open-sse/utils/`)
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. |
|
||||
| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. |
|
||||
| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). |
|
||||
| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. |
|
||||
| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. |
|
||||
| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. |
|
||||
| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. |
|
||||
| 文件 | 用途 |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `error.ts` | 错误响应构建（OpenAI 兼容格式）、上游错误解析、从错误消息中提取 Antigravity 重试时间、SSE 错误流式传输。 |
|
||||
| `stream.ts` | **SSE 转换流** — 核心流式管道。两种模式：`TRANSLATE`（完整格式转换）和 `PASSTHROUGH`（规范化 + 提取用量）。处理块缓冲、用量估算、内容长度追踪。每流独立的 encoder/decoder 实例避免共享状态。 |
|
||||
| `streamHelpers.ts` | 底层 SSE 工具：`parseSSELine`（容忍空白）、`hasValuableContent`（过滤 OpenAI/Claude/Gemini 的空块）、`fixInvalidId`、`formatSSE`（感知格式的 SSE 序列化，清理 `perf_metrics`）。 |
|
||||
| `usageTracking.ts` | 从任何格式提取 Token 用量（Claude/OpenAI/Gemini/Responses），使用独立的工具/消息字符-token 比率估算，添加缓冲（2000 token 安全边际），格式特定字段过滤，带 ANSI 颜色的控制台日志。 |
|
||||
| `requestLogger.ts` | 基于文件的请求日志（通过 `ENABLE_REQUEST_LOGS=true` 启用）。创建带编号文件的会话文件夹：`1_req_client.json` → `7_res_client.txt`。所有 I/O 异步（fire-and-forget）。遮蔽敏感请求头。 |
|
||||
| `bypassHandler.ts` | 拦截 Claude CLI 的特定模式（标题提取、预热、计数）并返回假响应而不调用任何提供商。支持流式和非流式。有意限制在 Claude CLI 范围内。 |
|
||||
| `networkProxy.ts` | 为给定提供商解析出站代理 URL，优先级：提供商特定配置 → 全局配置 → 环境变量（`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`）。支持 `NO_PROXY` 排除。配置缓存 30 秒。 |
|
||||
|
||||
#### SSE Streaming Pipeline
|
||||
#### SSE 流管道
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -433,161 +429,161 @@ flowchart TD
|
||||
style M fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
#### Request Logger Session Structure
|
||||
#### 请求日志器会话结构
|
||||
|
||||
```
|
||||
logs/
|
||||
└── claude_gemini_claude-sonnet_20260208_143045/
|
||||
├── 1_req_client.json ← Raw client request
|
||||
├── 2_req_source.json ← After initial conversion
|
||||
├── 3_req_openai.json ← OpenAI intermediate format
|
||||
├── 4_req_target.json ← Final target format
|
||||
├── 5_res_provider.txt ← Provider SSE chunks (streaming)
|
||||
├── 5_res_provider.json ← Provider response (non-streaming)
|
||||
├── 6_res_openai.txt ← OpenAI intermediate chunks
|
||||
├── 7_res_client.txt ← Client-facing SSE chunks
|
||||
└── 6_error.json ← Error details (if any)
|
||||
├── 1_req_client.json ← 原始客户端请求
|
||||
├── 2_req_source.json ← 初始转换后
|
||||
├── 3_req_openai.json ← OpenAI 中间格式
|
||||
├── 4_req_target.json ← 最终目标格式
|
||||
├── 5_res_provider.txt ← 提供商 SSE 块（流式）
|
||||
├── 5_res_provider.json ← 提供商响应（非流式）
|
||||
├── 6_res_openai.txt ← OpenAI 中间块
|
||||
├── 7_res_client.txt ← 面向客户端的 SSE 块
|
||||
└── 6_error.json ← 错误详情（如有）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.7 Application Layer (`src/`)
|
||||
### 4.7 应用层（`src/`）
|
||||
|
||||
| Directory | Purpose |
|
||||
| ------------- | ---------------------------------------------------------------------- |
|
||||
| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers |
|
||||
| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared |
|
||||
| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic |
|
||||
| `src/models/` | Database model definitions |
|
||||
| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) |
|
||||
| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes |
|
||||
| `src/store/` | Application state management |
|
||||
| 目录 | 用途 |
|
||||
| ------------- | ---------------------------------------------------- |
|
||||
| `src/app/` | Web UI、API 路由、Express 中间件、OAuth 回调处理器 |
|
||||
| `src/lib/` | 数据库访问（`localDb.ts`、`usageDb.ts`）、认证、共享 |
|
||||
| `src/mitm/` | 用于拦截提供商流量的中间人代理工具 |
|
||||
| `src/models/` | 数据库模型定义 |
|
||||
| `src/shared/` | open-sse 函数的包装器（provider、stream、error 等） |
|
||||
| `src/sse/` | 将 open-sse 库连接到 Express 路由的 SSE 端点处理器 |
|
||||
| `src/store/` | 应用状态管理 |
|
||||
|
||||
#### Notable API Routes
|
||||
#### 重要 API 路由
|
||||
|
||||
| Route | Methods | Purpose |
|
||||
| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
|
||||
| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider |
|
||||
| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
|
||||
| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) |
|
||||
| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency |
|
||||
| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation |
|
||||
| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation |
|
||||
| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) |
|
||||
| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests |
|
||||
| `/api/sessions` | GET | Active session tracking and metrics |
|
||||
| `/api/rate-limits` | GET | Per-account rate limit status |
|
||||
| 路由 | 方法 | 用途 |
|
||||
| --------------------------------------------- | --------------- | ----------------------------------------------------------------- |
|
||||
| `/api/provider-models` | GET/POST/DELETE | 每提供商自定义模型的 CRUD |
|
||||
| `/api/models/catalog` | GET | 按提供商分组的所有模型（聊天、Embedding、图像、自定义）的聚合目录 |
|
||||
| `/api/settings/proxy` | GET/PUT/DELETE | 分层出站代理配置（`global/providers/combos/keys`） |
|
||||
| `/api/settings/proxy/test` | POST | 验证代理连接并返回公共 IP/延迟 |
|
||||
| `/v1/providers/[provider]/chat/completions` | POST | 带模型验证的专用每提供商聊天完成 |
|
||||
| `/v1/providers/[provider]/embeddings` | POST | 带模型验证的专用每提供商 Embedding |
|
||||
| `/v1/providers/[provider]/images/generations` | POST | 带模型验证的专用每提供商图像生成 |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP 白名单/黑名单管理 |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | 推理 Token 预算配置（passthrough/auto/custom/adaptive） |
|
||||
| `/api/settings/system-prompt` | GET/PUT | 所有请求的全局系统提示词注入 |
|
||||
| `/api/sessions` | GET | 活动会话追踪和指标 |
|
||||
| `/api/rate-limits` | GET | 每账户速率限制状态 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Design Patterns
|
||||
## 5. 关键设计模式
|
||||
|
||||
### 5.1 Hub-and-Spoke Translation
|
||||
### 5.1 中心辐射翻译
|
||||
|
||||
All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
|
||||
所有格式都通过 **OpenAI 格式作为中心** 进行翻译。添加新提供商只需要编写**一对**翻译器（到/从 OpenAI），而不是 N 对。
|
||||
|
||||
### 5.2 Executor Strategy Pattern
|
||||
### 5.2 执行器策略模式
|
||||
|
||||
Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
|
||||
每个提供商都有一个继承自 `BaseExecutor` 的专用执行器类。`executors/index.ts` 中的工厂在运行时选择正确的执行器。
|
||||
|
||||
### 5.3 Self-Registering Plugin System
|
||||
### 5.3 自注册插件系统
|
||||
|
||||
Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
|
||||
翻译器模块在导入时通过 `register()` 自注册。添加新翻译器只需创建文件并导入它。
|
||||
|
||||
### 5.4 Account Fallback with Exponential Backoff
|
||||
### 5.4 带指数退避的账户后备
|
||||
|
||||
When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
|
||||
当提供商返回 429/401/500 时，系统可以切换到下一个账户，应用指数冷却（1s → 2s → 4s → 最大 2min）。
|
||||
|
||||
### 5.5 Combo Model Chains
|
||||
### 5.5 Combo 模型链
|
||||
|
||||
A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
|
||||
"Combo"组合多个 `provider/model` 字符串。如果第一个失败，自动后备到下一个。
|
||||
|
||||
### 5.6 Stateful Streaming Translation
|
||||
### 5.6 有状态流式翻译
|
||||
|
||||
Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
|
||||
响应翻译通过 `initState()` 机制在 SSE 块之间维护状态（Thinking 块追踪、工具调用累积、内容块索引）。
|
||||
|
||||
### 5.7 Usage Safety Buffer
|
||||
### 5.7 用量安全缓冲
|
||||
|
||||
A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
|
||||
在报告的用量中添加 2000 Token 缓冲，以防止客户端因系统提示词和格式翻译开销而达到上下文窗口限制。
|
||||
|
||||
---
|
||||
|
||||
## 6. Supported Formats
|
||||
## 6. 支持的格式
|
||||
|
||||
| Format | Direction | Identifier |
|
||||
| ----------------------- | --------------- | ------------------ |
|
||||
| OpenAI Chat Completions | source + target | `openai` |
|
||||
| OpenAI Responses API | source + target | `openai-responses` |
|
||||
| Anthropic Claude | source + target | `claude` |
|
||||
| Google Gemini | source + target | `gemini` |
|
||||
| Google Gemini CLI | target only | `gemini-cli` |
|
||||
| Antigravity | source + target | `antigravity` |
|
||||
| AWS Kiro | target only | `kiro` |
|
||||
| Cursor | target only | `cursor` |
|
||||
| 格式 | 方向 | 标识符 |
|
||||
| ----------------------- | --------- | ------------------ |
|
||||
| OpenAI Chat Completions | 源 + 目标 | `openai` |
|
||||
| OpenAI Responses API | 源 + 目标 | `openai-responses` |
|
||||
| Anthropic Claude | 源 + 目标 | `claude` |
|
||||
| Google Gemini | 源 + 目标 | `gemini` |
|
||||
| Google Gemini CLI | 仅目标 | `gemini-cli` |
|
||||
| Antigravity | 源 + 目标 | `antigravity` |
|
||||
| AWS Kiro | 仅目标 | `kiro` |
|
||||
| Cursor | 仅目标 | `cursor` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Supported Providers
|
||||
## 7. 支持的提供商
|
||||
|
||||
| Provider | Auth Method | Executor | Key Notes |
|
||||
| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
|
||||
| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header |
|
||||
| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header |
|
||||
| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint |
|
||||
| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing |
|
||||
| OpenAI | API key | Default | Standard Bearer auth |
|
||||
| Codex | OAuth | Codex | Injects system instructions, manages thinking |
|
||||
| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking |
|
||||
| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing |
|
||||
| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums |
|
||||
| Qwen | OAuth | Default | Standard auth |
|
||||
| Qoder | OAuth (Basic + Bearer) | Default | Dual auth header |
|
||||
| OpenRouter | API key | Default | Standard Bearer auth |
|
||||
| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` |
|
||||
| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint |
|
||||
| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint |
|
||||
| 提供商 | 认证方法 | 执行器 | 关键说明 |
|
||||
| ------------------------ | ----------------------- | ----------- | --------------------------------- |
|
||||
| Anthropic Claude | API 密钥或 OAuth | Default | 使用 `x-api-key` 请求头 |
|
||||
| Google Gemini | API 密钥或 OAuth | Default | 使用 `x-goog-api-key` 请求头 |
|
||||
| Google Gemini CLI | OAuth | GeminiCLI | 使用 `streamGenerateContent` 端点 |
|
||||
| Antigravity | OAuth | Antigravity | 多 URL 后备，自定义重试解析 |
|
||||
| OpenAI | API 密钥 | Default | 标准 Bearer 认证 |
|
||||
| Codex | OAuth | Codex | 注入系统指令，管理 Thinking |
|
||||
| GitHub Copilot | OAuth + Copilot Token | Github | 双 Token，模拟 VSCode 请求头 |
|
||||
| Kiro (AWS) | AWS SSO OIDC 或社交 | Kiro | 二进制 EventStream 解析 |
|
||||
| Cursor IDE | 校验和认证 | Cursor | Protobuf 编码，SHA-256 校验和 |
|
||||
| Qwen | OAuth | Default | 标准认证 |
|
||||
| Qoder | OAuth（Basic + Bearer） | Default | 双认证请求头 |
|
||||
| OpenRouter | API 密钥 | Default | 标准 Bearer 认证 |
|
||||
| GLM、Kimi、MiniMax | API 密钥 | Default | Claude 兼容，使用 `x-api-key` |
|
||||
| `openai-compatible-*` | API 密钥 | Default | 动态：任何 OpenAI 兼容端点 |
|
||||
| `anthropic-compatible-*` | API 密钥 | Default | 动态：任何 Claude 兼容端点 |
|
||||
|
||||
---
|
||||
|
||||
## 8. Data Flow Summary
|
||||
## 8. 数据流摘要
|
||||
|
||||
### Streaming Request
|
||||
### 流式请求
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Client"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\nsource → OpenAI → target"]
|
||||
C --> D["Executor\nbuildUrl + buildHeaders"]
|
||||
A["客户端"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\n源 → OpenAI → 目标"]
|
||||
C --> D["执行器\nbuildUrl + buildHeaders"]
|
||||
D --> E["fetch(providerURL)"]
|
||||
E --> F["createSSEStream()\nTRANSLATE mode"]
|
||||
E --> F["createSSEStream()\nTRANSLATE 模式"]
|
||||
F --> G["parseSSELine()"]
|
||||
G --> H["translateResponse()\ntarget → OpenAI → source"]
|
||||
G --> H["translateResponse()\n目标 → OpenAI → 源"]
|
||||
H --> I["extractUsage()\n+ addBuffer"]
|
||||
I --> J["formatSSE()"]
|
||||
J --> K["Client receives\ntranslated SSE"]
|
||||
J --> K["客户端接收\n已翻译的 SSE"]
|
||||
K --> L["logUsage()\nsaveRequestUsage()"]
|
||||
```
|
||||
|
||||
### Non-Streaming Request
|
||||
### 非流式请求
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Client"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\nsource → OpenAI → target"]
|
||||
A["客户端"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\n源 → OpenAI → 目标"]
|
||||
C --> D["Executor.execute()"]
|
||||
D --> E["translateResponse()\ntarget → OpenAI → source"]
|
||||
E --> F["Return JSON\nresponse"]
|
||||
D --> E["translateResponse()\n目标 → OpenAI → 源"]
|
||||
E --> F["返回 JSON\n响应"]
|
||||
```
|
||||
|
||||
### Bypass Flow (Claude CLI)
|
||||
### Bypass 流程（Claude CLI）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Claude CLI request"] --> B{"Match bypass\npattern?"}
|
||||
B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
|
||||
B -->|"No match"| D["Normal flow"]
|
||||
C --> E["Translate to\nsource format"]
|
||||
E --> F["Return without\ncalling provider"]
|
||||
A["Claude CLI 请求"] --> B{"匹配 bypass\n模式？"}
|
||||
B -->|"标题/预热/计数"| C["生成假\nOpenAI 响应"]
|
||||
B -->|"无匹配"| D["正常流程"]
|
||||
C --> E["翻译为\n源格式"]
|
||||
E --> F["返回而不\n调用提供商"]
|
||||
```
|
||||
|
||||
+54
-58
@@ -1,147 +1,143 @@
|
||||
# OmniRoute — Dashboard Features Gallery (中文（简体）)
|
||||
# OmniRoute — 仪表盘功能展示
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../FEATURES.md) · 🇧🇷 [pt-BR](../pt-BR/FEATURES.md) · 🇪🇸 [es](../es/FEATURES.md) · 🇫🇷 [fr](../fr/FEATURES.md) · 🇩🇪 [de](../de/FEATURES.md) · 🇮🇹 [it](../it/FEATURES.md) · 🇷🇺 [ru](../ru/FEATURES.md) · 🇨🇳 [zh-CN](../zh-CN/FEATURES.md) · 🇯🇵 [ja](../ja/FEATURES.md) · 🇰🇷 [ko](../ko/FEATURES.md) · 🇸🇦 [ar](../ar/FEATURES.md) · 🇮🇳 [in](../in/FEATURES.md) · 🇹🇭 [th](../th/FEATURES.md) · 🇻🇳 [vi](../vi/FEATURES.md) · 🇮🇩 [id](../id/FEATURES.md) · 🇲🇾 [ms](../ms/FEATURES.md) · 🇳🇱 [nl](../nl/FEATURES.md) · 🇵🇱 [pl](../pl/FEATURES.md) · 🇸🇪 [sv](../sv/FEATURES.md) · 🇳🇴 [no](../no/FEATURES.md) · 🇩🇰 [da](../da/FEATURES.md) · 🇫🇮 [fi](../fi/FEATURES.md) · 🇵🇹 [pt](../pt/FEATURES.md) · 🇷🇴 [ro](../ro/FEATURES.md) · 🇭🇺 [hu](../hu/FEATURES.md) · 🇧🇬 [bg](../bg/FEATURES.md) · 🇸🇰 [sk](../sk/FEATURES.md) · 🇺🇦 [uk-UA](../uk-UA/FEATURES.md) · 🇮🇱 [he](../he/FEATURES.md) · 🇵🇭 [phi](../phi/FEATURES.md) · 🇨🇿 [cs](../cs/FEATURES.md)
|
||||
|
||||
> 🇺🇸 [English](../../../docs/FEATURES.md)
|
||||
OmniRoute 仪表盘各部分的可视化指南。
|
||||
|
||||
---
|
||||
|
||||
Visual guide to every section of the OmniRoute dashboard.
|
||||
## 🔌 服务商
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Providers
|
||||
|
||||
Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
|
||||
管理 AI 服务商连接：OAuth 服务商（Claude Code、Codex、Gemini CLI）、API 密钥服务商（Groq、DeepSeek、OpenRouter）以及免费服务商（Qoder、Qwen、Kiro）。Kiro 账户包含额度余额跟踪 — 剩余额度、总配额和续期日期可在 Dashboard → Usage 中查看。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Combos
|
||||
## 🎨 组合
|
||||
|
||||
Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
|
||||
创建具有 6 种策略的模型路由组合：优先级、加权、轮询、随机、最少使用和成本优化。每个组合可链接多个模型并支持自动回退，还包括快速模板和就绪检查。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 Analytics
|
||||
## 📊 分析
|
||||
|
||||
Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
|
||||
全面的使用分析，包括 token 消耗、成本估算、活动热力图、每周分布图表以及按服务商细分。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 System Health
|
||||
## 🏥 系统健康
|
||||
|
||||
Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
|
||||
实时监控：运行时间、内存、版本、延迟百分位数（p50/p95/p99）、缓存统计和服务商熔断器状态。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Translator Playground
|
||||
## 🔧 翻译器测试场
|
||||
|
||||
Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
|
||||
四种调试 API 翻译的模式：**Playground**（格式转换器）、**Chat Tester**（实时请求）、**Test Bench**（批量测试）和 **Live Monitor**（实时流）。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Model Playground _(v2.0.9+)_
|
||||
## 🎮 模型测试场 _(v2.0.9+)_
|
||||
|
||||
Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
|
||||
直接从仪表盘测试任何模型。选择服务商、模型和端点，使用 Monaco Editor 编写提示，实时流式响应，可中途中止，并查看计时指标。
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Themes _(v2.0.5+)_
|
||||
## 🎨 主题 _(v2.0.5+)_
|
||||
|
||||
Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
|
||||
整个仪表盘可自定义颜色主题。可从 7 种预设颜色（珊瑚色、蓝色、红色、绿色、紫罗兰色、橙色、青色）中选择，或通过选择任何十六进制颜色创建自定义主题。支持浅色、深色和跟随系统模式。
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Settings
|
||||
## ⚙️ 设置
|
||||
|
||||
Comprehensive settings panel with tabs:
|
||||
全面的设置面板，包含以下标签页：
|
||||
|
||||
- **General** — System storage, backup management (export/import database)
|
||||
- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
|
||||
- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
|
||||
- **Routing** — Model aliases, background task degradation
|
||||
- **Resilience** — Rate limit persistence, circuit breaker tuning
|
||||
- **Advanced** — Configuration overrides
|
||||
- **通用** — 系统存储、备份管理（导出/导入数据库）
|
||||
- **外观** — 主题选择器（深色/浅色/跟随系统）、颜色主题预设和自定义颜色、健康日志可见性、侧边栏项目可见性控制
|
||||
- **安全** — API 端点保护、自定义服务商屏蔽、IP 过滤、会话信息
|
||||
- **路由** — 模型别名、后台任务降级
|
||||
- **弹性** — 速率限制持久化、熔断器调优、自动禁用被封禁账户、服务商过期监控
|
||||
- **高级** — 配置覆盖、配置审计追踪、回退降级模式
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 CLI Tools
|
||||
## 🔧 CLI 工具
|
||||
|
||||
One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
|
||||
一键配置 AI 编程工具：Claude Code、Codex CLI、Gemini CLI、OpenClaw、Kilo Code、Antigravity、Cline、Continue、Cursor 和 Factory Droid。具备自动化配置应用/重置、连接配置文件和模型映射功能。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🤖 CLI Agents _(v2.0.11+)_
|
||||
## 🤖 CLI 代理 _(v2.0.11+)_
|
||||
|
||||
Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
|
||||
发现和管理 CLI 代理的仪表盘。显示 14 个内置代理（Codex、Claude、Goose、Gemini CLI、OpenClaw、Aider、OpenCode、Cline、Qwen Code、ForgeCode、Amazon Q、Open Interpreter、Cursor CLI、Warp）的网格视图，具有：
|
||||
|
||||
- **Installation status** — Installed / Not Found with version detection
|
||||
- **Protocol badges** — stdio, HTTP, etc.
|
||||
- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
|
||||
- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
|
||||
- **安装状态** — 已安装 / 未找到，带版本检测
|
||||
- **协议徽章** — stdio、HTTP 等
|
||||
- **自定义代理** — 通过表单注册任何 CLI 工具（名称、二进制文件、版本命令、启动参数）
|
||||
- **CLI 指纹匹配** — 按服务商切换以匹配原生 CLI 请求签名，在保持代理 IP 的同时降低封禁风险
|
||||
|
||||
---
|
||||
|
||||
## 🖼️ Media _(v2.0.3+)_
|
||||
## 🖼️ 媒体 _(v2.0.3+)_
|
||||
|
||||
Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
|
||||
从仪表盘生成图像、视频和音乐。支持 OpenAI、xAI、Together、Hyperbolic、SD WebUI、ComfyUI、AnimateDiff、Stable Audio Open 和 MusicGen。
|
||||
|
||||
---
|
||||
|
||||
## 📝 Request Logs
|
||||
## 📝 请求日志
|
||||
|
||||
Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
|
||||
实时请求日志，支持按服务商、模型、账户和 API 密钥过滤。显示状态码、token 使用量、延迟和响应详情。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 API Endpoint
|
||||
## 🌐 API 端点
|
||||
|
||||
Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access.
|
||||
您的统一 API 端点，包含能力分解：Chat Completions、Responses API、Embeddings、Image Generation、Reranking、Audio Transcription、Text-to-Speech、Moderations 以及已注册的 API 密钥。支持 Cloudflare Quick Tunnel 集成和云代理进行远程访问。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔑 API Key Management
|
||||
## 🔑 API 密钥管理
|
||||
|
||||
Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
|
||||
创建、限定范围和撤销 API 密钥。每个密钥可限制为特定模型/服务商，具有完全访问或只读权限。可视化密钥管理及使用跟踪。
|
||||
|
||||
---
|
||||
|
||||
## 📋 Audit Log
|
||||
## 📋 审计日志
|
||||
|
||||
Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
|
||||
管理操作跟踪，支持按操作类型、操作者、目标、IP 地址和时间戳过滤。完整的安全事件历史记录。
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ Desktop Application
|
||||
## 🖥️ 桌面应用
|
||||
|
||||
Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
|
||||
适用于 Windows、macOS 和 Linux 的原生 Electron 桌面应用。将 OmniRoute 作为独立应用运行，具有系统托盘集成、离线支持、自动更新和一键安装。
|
||||
|
||||
Key features:
|
||||
主要特性：
|
||||
|
||||
- Server readiness polling (no blank screen on cold start)
|
||||
- System tray with port management
|
||||
- Content Security Policy
|
||||
- Single-instance lock
|
||||
- Auto-update on restart
|
||||
- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
|
||||
- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
|
||||
- 服务器就绪轮询（冷启动时无白屏）
|
||||
- 带端口管理的系统托盘
|
||||
- 内容安全策略
|
||||
- 单实例锁定
|
||||
- 重启时自动更新
|
||||
- 平台条件化 UI（macOS 红绿灯、Windows/Linux 默认标题栏）
|
||||
- 强化的 Electron 构建打包 — 独立包中的符号链接 `node_modules` 会在打包前被检测并拒绝，防止对构建机器的运行时依赖 (v2.5.5+)
|
||||
|
||||
📖 See [`electron/README.md`](../electron/README.md) for full documentation.
|
||||
📖 完整文档请参阅 [`electron/README.md`](../electron/README.md)。
|
||||
|
||||
@@ -1,63 +1,63 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../MCP-SERVER.md) · 🇧🇷 [pt-BR](../pt-BR/MCP-SERVER.md) · 🇪🇸 [es](../es/MCP-SERVER.md) · 🇫🇷 [fr](../fr/MCP-SERVER.md) · 🇩🇪 [de](../de/MCP-SERVER.md) · 🇮🇹 [it](../it/MCP-SERVER.md) · 🇷🇺 [ru](../ru/MCP-SERVER.md) · 🇨🇳 [zh-CN](../zh-CN/MCP-SERVER.md) · 🇯🇵 [ja](../ja/MCP-SERVER.md) · 🇰🇷 [ko](../ko/MCP-SERVER.md) · 🇸🇦 [ar](../ar/MCP-SERVER.md) · 🇮🇳 [in](../in/MCP-SERVER.md) · 🇹🇭 [th](../th/MCP-SERVER.md) · 🇻🇳 [vi](../vi/MCP-SERVER.md) · 🇮🇩 [id](../id/MCP-SERVER.md) · 🇲🇾 [ms](../ms/MCP-SERVER.md) · 🇳🇱 [nl](../nl/MCP-SERVER.md) · 🇵🇱 [pl](../pl/MCP-SERVER.md) · 🇸🇪 [sv](../sv/MCP-SERVER.md) · 🇳🇴 [no](../no/MCP-SERVER.md) · 🇩🇰 [da](../da/MCP-SERVER.md) · 🇫🇮 [fi](../fi/MCP-SERVER.md) · 🇵🇹 [pt](../pt/MCP-SERVER.md) · 🇷🇴 [ro](../ro/MCP-SERVER.md) · 🇭🇺 [hu](../hu/MCP-SERVER.md) · 🇧🇬 [bg](../bg/MCP-SERVER.md) · 🇸🇰 [sk](../sk/MCP-SERVER.md) · 🇺🇦 [uk-UA](../uk-UA/MCP-SERVER.md) · 🇮🇱 [he](../he/MCP-SERVER.md) · 🇵🇭 [phi](../phi/MCP-SERVER.md)
|
||||
|
||||
---
|
||||
|
||||
# OmniRoute MCP Server Documentation
|
||||
# OmniRoute MCP 服务器文档
|
||||
|
||||
> Model Context Protocol server with 16 intelligent tools
|
||||
> Model Context Protocol 服务器，包含 16 个智能工具
|
||||
|
||||
## Installation
|
||||
## 安装
|
||||
|
||||
OmniRoute MCP is built-in. Start it with:
|
||||
OmniRoute MCP 已内置。使用以下命令启动：
|
||||
|
||||
```bash
|
||||
omniroute --mcp
|
||||
```
|
||||
|
||||
Or via the open-sse transport:
|
||||
或通过 open-sse 传输方式：
|
||||
|
||||
```bash
|
||||
# HTTP streamable transport (port 20130)
|
||||
omniroute --dev # MCP auto-starts on /mcp endpoint
|
||||
# HTTP 可流式传输 (端口 20130)
|
||||
omniroute --dev # MCP 在 /mcp 端点自动启动
|
||||
```
|
||||
|
||||
## IDE Configuration
|
||||
## IDE 配置
|
||||
|
||||
See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
|
||||
请参阅 [IDE Configs](integrations/ide-configs.md) 了解 Antigravity、Cursor、Copilot 和 Claude Desktop 的设置方法。
|
||||
|
||||
---
|
||||
|
||||
## Essential Tools (8)
|
||||
## 基础工具 (8 个)
|
||||
|
||||
| Tool | Description |
|
||||
| :------------------------------ | :--------------------------------------- |
|
||||
| `omniroute_get_health` | Gateway health, circuit breakers, uptime |
|
||||
| `omniroute_list_combos` | All configured combos with models |
|
||||
| `omniroute_get_combo_metrics` | Performance metrics for a specific combo |
|
||||
| `omniroute_switch_combo` | Switch active combo by ID/name |
|
||||
| `omniroute_check_quota` | Quota status per provider or all |
|
||||
| `omniroute_route_request` | Send a chat completion through OmniRoute |
|
||||
| `omniroute_cost_report` | Cost analytics for a time period |
|
||||
| `omniroute_list_models_catalog` | Full model catalog with capabilities |
|
||||
| 工具 | 描述 |
|
||||
| :------------------------------ | :-------------------------------- |
|
||||
| `omniroute_get_health` | 网关健康状态、熔断器、运行时间 |
|
||||
| `omniroute_list_combos` | 所有已配置的组合及其模型 |
|
||||
| `omniroute_get_combo_metrics` | 特定组合的性能指标 |
|
||||
| `omniroute_switch_combo` | 通过 ID/名称切换活动组合 |
|
||||
| `omniroute_check_quota` | 按服务商或全部查询配额状态 |
|
||||
| `omniroute_route_request` | 通过 OmniRoute 发送聊天完成请求 |
|
||||
| `omniroute_cost_report` | 指定时间段的成本分析 |
|
||||
| `omniroute_list_models_catalog` | 完整模型目录及能力说明 |
|
||||
|
||||
## Advanced Tools (8)
|
||||
## 高级工具 (8 个)
|
||||
|
||||
| Tool | Description |
|
||||
| :--------------------------------- | :---------------------------------------------- |
|
||||
| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree |
|
||||
| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions |
|
||||
| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset |
|
||||
| `omniroute_test_combo` | Live-test all models in a combo |
|
||||
| `omniroute_get_provider_metrics` | Detailed metrics for one provider |
|
||||
| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives |
|
||||
| `omniroute_explain_route` | Explain a past routing decision |
|
||||
| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors |
|
||||
| 工具 | 描述 |
|
||||
| :--------------------------------- | :------------------------------------ |
|
||||
| `omniroute_simulate_route` | 带有回退树的路由模拟（空跑） |
|
||||
| `omniroute_set_budget_guard` | 会话预算及降级/阻止/告警操作 |
|
||||
| `omniroute_set_resilience_profile` | 应用保守/平衡/激进预设 |
|
||||
| `omniroute_test_combo` | 实时测试组合中的所有模型 |
|
||||
| `omniroute_get_provider_metrics` | 单个服务商的详细指标 |
|
||||
| `omniroute_best_combo_for_task` | 任务适配推荐及替代方案 |
|
||||
| `omniroute_explain_route` | 解释历史路由决策 |
|
||||
| `omniroute_get_session_snapshot` | 完整会话状态：成本、token、错误 |
|
||||
|
||||
## Authentication
|
||||
## 身份验证
|
||||
|
||||
MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
|
||||
MCP 工具通过 API 密钥作用域进行身份验证。每个工具需要特定的作用域：
|
||||
|
||||
| Scope | Tools |
|
||||
| 作用域 | 工具 |
|
||||
| :------------- | :----------------------------------------------- |
|
||||
| `read:health` | get_health, get_provider_metrics |
|
||||
| `read:combos` | list_combos, get_combo_metrics |
|
||||
@@ -68,20 +68,20 @@ MCP tools are authenticated via API key scopes. Each tool requires specific scop
|
||||
| `write:config` | set_budget_guard, set_resilience_profile |
|
||||
| `read:models` | list_models_catalog, best_combo_for_task |
|
||||
|
||||
## Audit Logging
|
||||
## 审计日志
|
||||
|
||||
Every tool call is logged to `mcp_tool_audit` with:
|
||||
每个工具调用都会记录到 `mcp_tool_audit`，包含：
|
||||
|
||||
- Tool name, arguments, result
|
||||
- Duration (ms), success/failure
|
||||
- API key hash, timestamp
|
||||
- 工具名称、参数、结果
|
||||
- 耗时（毫秒）、成功/失败状态
|
||||
- API 密钥哈希值、时间戳
|
||||
|
||||
## Files
|
||||
## 文件
|
||||
|
||||
| File | Purpose |
|
||||
| :------------------------------------------- | :------------------------------------------ |
|
||||
| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations |
|
||||
| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport |
|
||||
| `open-sse/mcp-server/auth.ts` | API key + scope validation |
|
||||
| `open-sse/mcp-server/audit.ts` | Tool call audit logging |
|
||||
| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers |
|
||||
| 文件 | 用途 |
|
||||
| :------------------------------------------- | :-------------------------------- |
|
||||
| `open-sse/mcp-server/server.ts` | MCP 服务器创建 + 16 个工具注册 |
|
||||
| `open-sse/mcp-server/transport.ts` | Stdio + HTTP 传输 |
|
||||
| `open-sse/mcp-server/auth.ts` | API 密钥 + 作用域验证 |
|
||||
| `open-sse/mcp-server/audit.ts` | 工具调用审计日志 |
|
||||
| `open-sse/mcp-server/tools/advancedTools.ts` | 8 个高级工具处理器 |
|
||||
|
||||
+1021
-991
File diff suppressed because it is too large
Load Diff
@@ -1,37 +1,37 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../es/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../fr/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../de/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../it/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../ru/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../ja/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../ko/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../ar/RELEASE_CHECKLIST.md) · 🇮🇳 [in](../in/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../th/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../vi/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../id/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../ms/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../nl/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../pl/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../sv/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../no/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../da/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../fi/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../pt/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../ro/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../hu/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../bg/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../sk/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../he/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../phi/RELEASE_CHECKLIST.md)
|
||||
|
||||
---
|
||||
|
||||
# Release Checklist
|
||||
# 发布检查清单
|
||||
|
||||
Use this checklist before tagging or publishing a new OmniRoute release.
|
||||
在打标签或发布新的 OmniRoute 版本之前，请使用此检查清单。
|
||||
|
||||
## Version and Changelog
|
||||
## 版本和变更日志
|
||||
|
||||
1. Bump `package.json` version (`x.y.z`) in the release branch.
|
||||
2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section:
|
||||
1. 在发布分支中更新 `package.json` 的版本号（`x.y.z`）。
|
||||
2. 将发布说明从 `CHANGELOG.md` 中的 `## [Unreleased]` 移动到带日期的章节：
|
||||
- `## [x.y.z] — YYYY-MM-DD`
|
||||
3. Keep `## [Unreleased]` as the first changelog section for upcoming work.
|
||||
4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version.
|
||||
3. 保留 `## [Unreleased]` 作为变更日志的第一个章节，用于后续工作。
|
||||
4. 确保 `CHANGELOG.md` 中最新的语义化版本章节与 `package.json` 的版本号一致。
|
||||
|
||||
## API Docs
|
||||
## API 文档
|
||||
|
||||
1. Update `docs/openapi.yaml`:
|
||||
- `info.version` must equal `package.json` version.
|
||||
2. Validate endpoint examples if API contracts changed.
|
||||
1. 更新 `docs/openapi.yaml`：
|
||||
- `info.version` 必须与 `package.json` 的版本号一致。
|
||||
2. 如果 API 契约发生变化，请验证端点示例。
|
||||
|
||||
## Runtime Docs
|
||||
## 运行时文档
|
||||
|
||||
1. Review `docs/ARCHITECTURE.md` for storage/runtime drift.
|
||||
2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift.
|
||||
3. Update localized docs if source docs changed significantly.
|
||||
1. 检查 `docs/ARCHITECTURE.md` 是否存在存储/运行时偏移。
|
||||
2. 检查 `docs/TROUBLESHOOTING.md` 是否存在环境变量和操作偏移。
|
||||
3. 如果源文档发生重大变更，请更新本地化文档。
|
||||
|
||||
## Automated Check
|
||||
## 自动化检查
|
||||
|
||||
Run the sync guard locally before opening PR:
|
||||
在开启 PR 之前，在本地运行同步检查：
|
||||
|
||||
```bash
|
||||
npm run check:docs-sync
|
||||
```
|
||||
|
||||
CI also runs this check in `.github/workflows/ci.yml` (lint job).
|
||||
CI 也会在 `.github/workflows/ci.yml`（lint 作业）中运行此检查。
|
||||
|
||||
+139
-141
@@ -1,91 +1,89 @@
|
||||
🌐 **Languages:** 🇺🇸 [English](../../README.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../TROUBLESHOOTING.md) · 🇧🇷 [pt-BR](../pt-BR/TROUBLESHOOTING.md) · 🇪🇸 [es](../es/TROUBLESHOOTING.md) · 🇫🇷 [fr](../fr/TROUBLESHOOTING.md) · 🇩🇪 [de](../de/TROUBLESHOOTING.md) · 🇮🇹 [it](../it/TROUBLESHOOTING.md) · 🇷🇺 [ru](../ru/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../zh-CN/TROUBLESHOOTING.md) · 🇯🇵 [ja](../ja/TROUBLESHOOTING.md) · 🇰🇷 [ko](../ko/TROUBLESHOOTING.md) · 🇸🇦 [ar](../ar/TROUBLESHOOTING.md) · 🇮🇳 [in](../in/TROUBLESHOOTING.md) · 🇹🇭 [th](../th/TROUBLESHOOTING.md) · 🇻🇳 [vi](../vi/TROUBLESHOOTING.md) · 🇮🇩 [id](../id/TROUBLESHOOTING.md) · 🇲🇾 [ms](../ms/TROUBLESHOOTING.md) · 🇳🇱 [nl](../nl/TROUBLESHOOTING.md) · 🇵🇱 [pl](../pl/TROUBLESHOOTING.md) · 🇸🇪 [sv](../sv/TROUBLESHOOTING.md) · 🇳🇴 [no](../no/TROUBLESHOOTING.md) · 🇩🇰 [da](../da/TROUBLESHOOTING.md) · 🇫🇮 [fi](../fi/TROUBLESHOOTING.md) · 🇵🇹 [pt](../pt/TROUBLESHOOTING.md) · 🇷🇴 [ro](../ro/TROUBLESHOOTING.md) · 🇭🇺 [hu](../hu/TROUBLESHOOTING.md) · 🇧🇬 [bg](../bg/TROUBLESHOOTING.md) · 🇸🇰 [sk](../sk/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../uk-UA/TROUBLESHOOTING.md) · 🇮🇱 [he](../he/TROUBLESHOOTING.md) · 🇵🇭 [phi](../phi/TROUBLESHOOTING.md)
|
||||
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
# 故障排除
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md)
|
||||
|
||||
Common problems and solutions for OmniRoute.
|
||||
OmniRoute 常见问题及解决方案。
|
||||
|
||||
---
|
||||
|
||||
## Quick Fixes
|
||||
## 快速修复
|
||||
|
||||
| Problem | Solution |
|
||||
| ----------------------------- | ------------------------------------------------------------------ |
|
||||
| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) |
|
||||
| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
|
||||
| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` |
|
||||
| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` |
|
||||
| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) |
|
||||
| 问题 | 解决方案 |
|
||||
| --------------------------- | ------------------------------------------------------------------ |
|
||||
| 首次登录无法使用 | 在 `.env` 中设置 `INITIAL_PASSWORD`（无硬编码默认值） |
|
||||
| 仪表盘在错误端口打开 | 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
|
||||
| `logs/` 下无请求日志 | 设置 `ENABLE_REQUEST_LOGS=true` |
|
||||
| EACCES: 权限被拒绝 | 设置 `DATA_DIR=/path/to/writable/dir` 以覆盖 `~/.omniroute` |
|
||||
| 路由策略未保存 | 更新到 v1.4.11+（Zod schema 设置持久化修复） |
|
||||
|
||||
---
|
||||
|
||||
## Provider Issues
|
||||
## 服务商问题
|
||||
|
||||
### "Language model did not provide messages"
|
||||
|
||||
**Cause:** Provider quota exhausted.
|
||||
**原因:** 服务商配额耗尽。
|
||||
|
||||
**Fix:**
|
||||
**解决方案:**
|
||||
|
||||
1. Check dashboard quota tracker
|
||||
2. Use a combo with fallback tiers
|
||||
3. Switch to cheaper/free tier
|
||||
1. 检查仪表盘配额跟踪器
|
||||
2. 使用带有回退层级的组合
|
||||
3. 切换到更便宜/免费的层级
|
||||
|
||||
### Rate Limiting
|
||||
### 速率限制
|
||||
|
||||
**Cause:** Subscription quota exhausted.
|
||||
**原因:** 订阅配额耗尽。
|
||||
|
||||
**Fix:**
|
||||
**解决方案:**
|
||||
|
||||
- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
- Use GLM/MiniMax as cheap backup
|
||||
- 添加回退：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
- 使用 GLM/MiniMax 作为廉价备份
|
||||
|
||||
### OAuth Token Expired
|
||||
### OAuth Token 过期
|
||||
|
||||
OmniRoute auto-refreshes tokens. If issues persist:
|
||||
OmniRoute 会自动刷新 token。如果问题持续：
|
||||
|
||||
1. Dashboard → Provider → Reconnect
|
||||
2. Delete and re-add the provider connection
|
||||
1. 仪表盘 → Provider → Reconnect
|
||||
2. 删除并重新添加服务商连接
|
||||
|
||||
---
|
||||
|
||||
## Cloud Issues
|
||||
## 云端问题
|
||||
|
||||
### Cloud Sync Errors
|
||||
### 云同步错误
|
||||
|
||||
1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
|
||||
2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
|
||||
3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
|
||||
1. 验证 `BASE_URL` 指向您的运行实例（例如 `http://localhost:20128`）
|
||||
2. 验证 `CLOUD_URL` 指向您的云端点（例如 `https://omniroute.dev`）
|
||||
3. 保持 `NEXT_PUBLIC_*` 值与服务器端值一致
|
||||
|
||||
### Cloud `stream=false` Returns 500
|
||||
### 云端 `stream=false` 返回 500
|
||||
|
||||
**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
|
||||
**症状:** 非流式调用在云端点返回 `Unexpected token 'd'...`。
|
||||
|
||||
**Cause:** Upstream returns SSE payload while client expects JSON.
|
||||
**原因:** 上游返回 SSE 负载，而客户端期望 JSON。
|
||||
|
||||
**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
|
||||
**解决方法:** 对云端直接调用使用 `stream=true`。本地运行时包含 SSE→JSON 回退。
|
||||
|
||||
### Cloud Says Connected but "Invalid API key"
|
||||
### 云端显示已连接但 "Invalid API key"
|
||||
|
||||
1. Create a fresh key from local dashboard (`/api/keys`)
|
||||
2. Run cloud sync: Enable Cloud → Sync Now
|
||||
3. Old/non-synced keys can still return `401` on cloud
|
||||
1. 从本地仪表盘创建新密钥 (`/api/keys`)
|
||||
2. 运行云同步：启用云 → 立即同步
|
||||
3. 旧的/未同步的密钥在云端仍可能返回 `401`
|
||||
|
||||
---
|
||||
|
||||
## Docker Issues
|
||||
## Docker 问题
|
||||
|
||||
### CLI Tool Shows Not Installed
|
||||
### CLI 工具显示未安装
|
||||
|
||||
1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
|
||||
2. For portable mode: use image target `runner-cli` (bundled CLIs)
|
||||
3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
|
||||
4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
|
||||
1. 检查运行时字段：`curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
|
||||
2. 便携模式：使用镜像目标 `runner-cli`（捆绑 CLI）
|
||||
3. 主机挂载模式：设置 `CLI_EXTRA_PATHS` 并以只读方式挂载主机 bin 目录
|
||||
4. 如果 `installed=true` 且 `runnable=false`：找到二进制文件但健康检查失败
|
||||
|
||||
### Quick Runtime Validation
|
||||
### 快速运行时验证
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
|
||||
@@ -95,164 +93,164 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
|
||||
|
||||
---
|
||||
|
||||
## Cost Issues
|
||||
## 成本问题
|
||||
|
||||
### High Costs
|
||||
### 高成本
|
||||
|
||||
1. Check usage stats in Dashboard → Usage
|
||||
2. Switch primary model to GLM/MiniMax
|
||||
3. Use free tier (Gemini CLI, Qoder) for non-critical tasks
|
||||
4. Set cost budgets per API key: Dashboard → API Keys → Budget
|
||||
1. 在 Dashboard → Usage 检查使用统计
|
||||
2. 将主要模型切换到 GLM/MiniMax
|
||||
3. 对非关键任务使用免费层（Gemini CLI、Qoder）
|
||||
4. 为每个 API 密钥设置成本预算：Dashboard → API Keys → Budget
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
## 调试
|
||||
|
||||
### Enable Request Logs
|
||||
### 启用请求日志
|
||||
|
||||
Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
|
||||
在 `.env` 文件中设置 `ENABLE_REQUEST_LOGS=true`。日志出现在 `logs/` 目录下。
|
||||
|
||||
### Check Provider Health
|
||||
### 检查服务商健康状态
|
||||
|
||||
```bash
|
||||
# Health dashboard
|
||||
# 健康仪表盘
|
||||
http://localhost:20128/dashboard/health
|
||||
|
||||
# API health check
|
||||
# API 健康检查
|
||||
curl http://localhost:20128/api/monitoring/health
|
||||
```
|
||||
|
||||
### Runtime Storage
|
||||
### 运行时存储
|
||||
|
||||
- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings)
|
||||
- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/`
|
||||
- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
|
||||
- 主要状态：`${DATA_DIR}/storage.sqlite`（服务商、组合、别名、密钥、设置）
|
||||
- 使用量：`storage.sqlite` 中的 SQLite 表（`usage_history`、`call_logs`、`proxy_logs`）+ 可选 `${DATA_DIR}/log.txt` 和 `${DATA_DIR}/call_logs/`
|
||||
- 请求日志：`<repo>/logs/...`（当 `ENABLE_REQUEST_LOGS=true` 时）
|
||||
|
||||
---
|
||||
|
||||
## Circuit Breaker Issues
|
||||
## 熔断器问题
|
||||
|
||||
### Provider stuck in OPEN state
|
||||
### 服务商卡在 OPEN 状态
|
||||
|
||||
When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
|
||||
当服务商的熔断器处于 OPEN 状态时，请求会被阻止直到冷却期结束。
|
||||
|
||||
**Fix:**
|
||||
**解决方案:**
|
||||
|
||||
1. Go to **Dashboard → Settings → Resilience**
|
||||
2. Check the circuit breaker card for the affected provider
|
||||
3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
|
||||
4. Verify the provider is actually available before resetting
|
||||
1. 前往 **Dashboard → Settings → Resilience**
|
||||
2. 检查受影响服务商的熔断器卡片
|
||||
3. 点击 **Reset All** 清除所有熔断器，或等待冷却期结束
|
||||
4. 重置前验证服务商确实可用
|
||||
|
||||
### Provider keeps tripping the circuit breaker
|
||||
### 服务商反复触发熔断器
|
||||
|
||||
If a provider repeatedly enters OPEN state:
|
||||
如果服务商反复进入 OPEN 状态：
|
||||
|
||||
1. Check **Dashboard → Health → Provider Health** for the failure pattern
|
||||
2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
|
||||
3. Check if the provider has changed API limits or requires re-authentication
|
||||
4. Review latency telemetry — high latency may cause timeout-based failures
|
||||
1. 检查 **Dashboard → Health → Provider Health** 了解故障模式
|
||||
2. 前往 **Settings → Resilience → Provider Profiles** 增加故障阈值
|
||||
3. 检查服务商是否更改了 API 限制或需要重新认证
|
||||
4. 查看延迟遥测 — 高延迟可能导致基于超时的故障
|
||||
|
||||
---
|
||||
|
||||
## Audio Transcription Issues
|
||||
## 音频转录问题
|
||||
|
||||
### "Unsupported model" error
|
||||
### "Unsupported model" 错误
|
||||
|
||||
- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
|
||||
- Verify the provider is connected in **Dashboard → Providers**
|
||||
- 确保使用正确的前缀：`deepgram/nova-3` 或 `assemblyai/best`
|
||||
- 在 **Dashboard → Providers** 验证服务商已连接
|
||||
|
||||
### Transcription returns empty or fails
|
||||
### 转录返回空或失败
|
||||
|
||||
- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
|
||||
- Verify file size is within provider limits (typically < 25MB)
|
||||
- Check provider API key validity in the provider card
|
||||
- 检查支持的音频格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`
|
||||
- 验证文件大小在服务商限制内（通常 < 25MB）
|
||||
- 在服务商卡片中检查 API 密钥有效性
|
||||
|
||||
---
|
||||
|
||||
## Translator Debugging
|
||||
## 翻译器调试
|
||||
|
||||
Use **Dashboard → Translator** to debug format translation issues:
|
||||
使用 **Dashboard → Translator** 调试格式翻译问题：
|
||||
|
||||
| Mode | When to Use |
|
||||
| ---------------- | -------------------------------------------------------------------------------------------- |
|
||||
| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates |
|
||||
| **Chat Tester** | Send live messages and inspect the full request/response payload including headers |
|
||||
| **Test Bench** | Run batch tests across format combinations to find which translations are broken |
|
||||
| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues |
|
||||
| 模式 | 使用场景 |
|
||||
| ----------------- | ------------------------------------------------------------------------------- |
|
||||
| **Playground** | 并排比较输入/输出格式 — 粘贴失败的请求查看其翻译结果 |
|
||||
| **Chat Tester** | 发送实时消息并检查完整的请求/响应负载（包括头部） |
|
||||
| **Test Bench** | 跨格式组合运行批量测试以找出哪些翻译有问题 |
|
||||
| **Live Monitor** | 观察实时请求流以捕获间歇性翻译问题 |
|
||||
|
||||
### Common format issues
|
||||
### 常见格式问题
|
||||
|
||||
- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
|
||||
- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
|
||||
- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
|
||||
- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
|
||||
- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
|
||||
- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
|
||||
- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
|
||||
- **Thinking 标签未显示** — 检查目标服务商是否支持 thinking 及 thinking budget 设置
|
||||
- **工具调用丢失** — 某些格式翻译可能剥离不支持的字段；在 Playground 模式验证
|
||||
- **系统提示缺失** — Claude 和 Gemini 处理系统提示的方式不同；检查翻译输出
|
||||
- **SDK 返回原始字符串而非对象** — v1.1.0 已修复：响应清理器现在会剥离导致 OpenAI SDK Pydantic 验证失败的非标准字段（`x_groq`、`usage_breakdown` 等）
|
||||
- **GLM/ERNIE 拒绝 `system` 角色** — v1.1.0 已修复：角色归一化器自动将系统消息合并到不兼容模型的用户消息中
|
||||
- **`developer` 角色不被识别** — v1.1.0 已修复：对非 OpenAI 服务商自动转换为 `system`
|
||||
- **`json_schema` 对 Gemini 不起作用** — v1.1.0 已修复：`response_format` 现在会转换为 Gemini 的 `responseMimeType` + `responseSchema`
|
||||
|
||||
---
|
||||
|
||||
## Resilience Settings
|
||||
## 弹性设置
|
||||
|
||||
### Auto rate-limit not triggering
|
||||
### 自动速率限制未触发
|
||||
|
||||
- Auto rate-limit only applies to API key providers (not OAuth/subscription)
|
||||
- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
|
||||
- Check if the provider returns `429` status codes or `Retry-After` headers
|
||||
- 自动速率限制仅适用于 API 密钥服务商（不适用于 OAuth/订阅）
|
||||
- 验证 **Settings → Resilience → Provider Profiles** 已启用自动速率限制
|
||||
- 检查服务商是否返回 `429` 状态码或 `Retry-After` 头部
|
||||
|
||||
### Tuning exponential backoff
|
||||
### 调整指数退避
|
||||
|
||||
Provider profiles support these settings:
|
||||
服务商配置文件支持以下设置：
|
||||
|
||||
- **Base delay** — Initial wait time after first failure (default: 1s)
|
||||
- **Max delay** — Maximum wait time cap (default: 30s)
|
||||
- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
|
||||
- **Base delay** — 首次失败后的初始等待时间（默认：1s）
|
||||
- **Max delay** — 最大等待时间上限（默认：30s）
|
||||
- **Multiplier** — 每次连续失败后延迟增加的倍数（默认：2x）
|
||||
|
||||
### Anti-thundering herd
|
||||
### 防惊群效应
|
||||
|
||||
When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
|
||||
当多个并发请求命中速率受限的服务商时，OmniRoute 使用互斥锁 + 自动速率限制来序列化请求并防止级联故障。这对 API 密钥服务商是自动的。
|
||||
|
||||
---
|
||||
|
||||
## Optional RAG / LLM failure taxonomy (16 problems)
|
||||
## 可选 RAG / LLM 故障分类（16 个问题）
|
||||
|
||||
Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
|
||||
一些 OmniRoute 用户将网关放在 RAG 或代理堆栈前面。在这些设置中，常见一种奇怪的模式：OmniRoute 看起来健康（服务商运行中、路由配置正常、无速率限制告警），但最终答案仍然是错误的。
|
||||
|
||||
In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
|
||||
实际上，这些事件通常来自下游 RAG 管道，而非网关本身。
|
||||
|
||||
If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
|
||||
如果您想要描述这些故障的共享词汇，可以使用 WFGY ProblemMap，这是一个外部 MIT 许可的文本资源，定义了十六种反复出现的 RAG / LLM 故障模式。在高层次上，它涵盖：
|
||||
|
||||
- retrieval drift and broken context boundaries
|
||||
- empty or stale indexes and vector stores
|
||||
- embedding versus semantic mismatch
|
||||
- prompt assembly and context window issues
|
||||
- logic collapse and overconfident answers
|
||||
- long chain and agent coordination failures
|
||||
- multi agent memory and role drift
|
||||
- deployment and bootstrap ordering problems
|
||||
- 检索漂移和断裂的上下文边界
|
||||
- 空的或过时的索引和向量存储
|
||||
- 嵌入与语义不匹配
|
||||
- 提示组装和上下文窗口问题
|
||||
- 逻辑崩溃和过度自信的答案
|
||||
- 长链和代理协调故障
|
||||
- 多代理记忆和角色漂移
|
||||
- 部署和启动顺序问题
|
||||
|
||||
The idea is simple:
|
||||
想法很简单：
|
||||
|
||||
1. When you investigate a bad response, capture:
|
||||
- user task and request
|
||||
- route or provider combo in OmniRoute
|
||||
- any RAG context used downstream (retrieved documents, tool calls, etc)
|
||||
2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
|
||||
3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
|
||||
4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
|
||||
1. 当您调查错误响应时，记录：
|
||||
- 用户任务和请求
|
||||
- OmniRoute 中的路由或服务商组合
|
||||
- 下游使用的任何 RAG 上下文（检索的文档、工具调用等）
|
||||
2. 将事件映射到一个或两个 WFGY ProblemMap 编号（`No.1` … `No.16`）。
|
||||
3. 在您自己的仪表盘、运行手册或事件跟踪器中将该编号存储在 OmniRoute 日志旁边。
|
||||
4. 使用相应的 WFGY 页面来决定是否需要更改您的 RAG 堆栈、检索器或路由策略。
|
||||
|
||||
Full text and concrete recipes live here (MIT license, text only):
|
||||
完整文本和具体方案在此处（MIT 许可，仅文本）：
|
||||
|
||||
[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
|
||||
|
||||
You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
|
||||
如果您不在 OmniRoute 后面运行 RAG 或代理管道，可以忽略此部分。
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
## 仍然卡住？
|
||||
|
||||
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
|
||||
- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
|
||||
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
|
||||
- **Translator**: Use **Dashboard → Translator** to debug format issues
|
||||
- **架构**: 参见 [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) 了解内部细节
|
||||
- **API 参考**: 参见 [`docs/API_REFERENCE.md`](API_REFERENCE.md) 了解所有端点
|
||||
- **健康仪表盘**: 检查 **Dashboard → Health** 了解实时系统状态
|
||||
- **翻译器**: 使用 **Dashboard → Translator** 调试格式问题
|
||||
|
||||
+364
-351
File diff suppressed because it is too large
Load Diff
@@ -1,36 +1,36 @@
|
||||
# OmniRoute — 使用 Cloudflare 在虚拟机上部署指南
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](../es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](../fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](../ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](../in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](../th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](../ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](../ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](../bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](../he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](../ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](../ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](../cs/VM_DEPLOYMENT_GUIDE.md)
|
||||
🌐 **语言:** 🇺🇸 [English](../../VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](../es/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](../fr/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](../ru/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](../in/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](../th/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](../ar/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](../ja/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](../bg/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](../he/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](../ko/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](../ro/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](../cs/VM_DEPLOYMENT_GUIDE.md)
|
||||
|
||||
在通过 Cloudflare 管理域的 VM (VPS) 上安装和配置 OmniRoute 的完整指南。
|
||||
在通过 Cloudflare 管理域名的 VM (VPS) 上安装和配置 OmniRoute 的完整指南。
|
||||
|
||||
---
|
||||
|
||||
## 先决条件
|
||||
|
||||
| 项目 | 最低 | 推荐 |
|
||||
| ------------ | -------------------- | --------------------------------- | ---------------- |
|
||||
| **CPU** | 1 个虚拟CPU | 2 个虚拟CPU |
|
||||
| **内存** | 1 GB | 2GB |
|
||||
| **磁盘** | 10 GB 固态硬盘 | 25 GB 固态硬盘 |
|
||||
| **操作系统** | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
|
||||
| **域名** | 在 Cloudflare 上注册 | — |
|
||||
| **码头工人** | Docker 引擎 24+ | Docker 27+ |
|
||||
| 项目 | 最低要求 | 推荐 |
|
||||
| ------------ | -------------------- | ------------------ |
|
||||
| **CPU** | 1 vCPU | 2 vCPU |
|
||||
| **内存** | 1 GB | 2 GB |
|
||||
| **磁盘** | 10 GB SSD | 25 GB SSD |
|
||||
| **操作系统** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
|
||||
| **域名** | 在 Cloudflare 上注册 | — |
|
||||
| **Docker** | Docker Engine 24+ | Docker 27+ |
|
||||
|
||||
**经过测试的提供商**：Akamai (Linode)、DigitalOcean、Vultr、Hetzner、AWS Lightsail。
|
||||
**已测试的服务商**：Akamai (Linode)、DigitalOcean、Vultr、Hetzner、AWS Lightsail。
|
||||
|
||||
---
|
||||
|
||||
## 1.配置虚拟机
|
||||
## 1. 配置虚拟机
|
||||
|
||||
### 1.1 创建实例
|
||||
|
||||
在您首选的 VPS 提供商上：
|
||||
在您首选的 VPS 服务商上：
|
||||
|
||||
- 选择 Ubuntu 24.04 LTS
|
||||
- 选择最低计划（1 vCPU / 1 GB RAM）
|
||||
- 设置强root密码或配置SSH密钥
|
||||
- 记下 **公共 IP**（例如 `203.0.113.10`）
|
||||
- 选择最低配置（1 vCPU / 1 GB RAM）
|
||||
- 设置强 root 密码或配置 SSH 密钥
|
||||
- 记下**公网 IP**（例如 `203.0.113.10`）
|
||||
|
||||
### 1.2 通过 SSH 连接
|
||||
|
||||
@@ -47,10 +47,10 @@ apt update && apt upgrade -y
|
||||
### 1.4 安装 Docker
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
# 安装依赖
|
||||
apt install -y ca-certificates curl gnupg
|
||||
|
||||
# Add official Docker repository
|
||||
# 添加官方 Docker 仓库
|
||||
install -m 0755 -d /etc/apt/keyrings
|
||||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
||||
chmod a+r /etc/apt/keyrings/docker.gpg
|
||||
@@ -59,24 +59,24 @@ apt update
|
||||
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
```
|
||||
|
||||
### 1.5 安装nginx
|
||||
### 1.5 安装 nginx
|
||||
|
||||
```bash
|
||||
apt install -y nginx
|
||||
```
|
||||
|
||||
### 1.6 配置防火墙（UFW）
|
||||
### 1.6 配置防火墙 (UFW)
|
||||
|
||||
```bash
|
||||
ufw default deny incoming
|
||||
ufw default allow outgoing
|
||||
ufw allow 22/tcp # SSH
|
||||
ufw allow 80/tcp # HTTP (redirect)
|
||||
ufw allow 80/tcp # HTTP（重定向）
|
||||
ufw allow 443/tcp # HTTPS
|
||||
ufw enable
|
||||
```
|
||||
|
||||
> **提示**：为了获得最大的安全性，请将端口 80 和 443 仅限制为 Cloudflare IP。请参阅 [Advanced Security](#advanced-security) 部分。
|
||||
> **提示**：为获得最高安全性，请将端口 80 和 443 仅限制为 Cloudflare IP。参见[高级安全](#6-高级安全性)部分。
|
||||
|
||||
---
|
||||
|
||||
@@ -92,7 +92,7 @@ mkdir -p /opt/omniroute
|
||||
|
||||
```bash
|
||||
cat > /opt/omniroute/.env << ‘EOF’
|
||||
# === Security ===
|
||||
# === 安全配置 ===
|
||||
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
|
||||
INITIAL_PASSWORD=YourSecurePassword123!
|
||||
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
|
||||
@@ -100,7 +100,7 @@ STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
|
||||
STORAGE_ENCRYPTION_KEY_VERSION=v1
|
||||
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
|
||||
|
||||
# === App ===
|
||||
# === 应用配置 ===
|
||||
PORT=20128
|
||||
NODE_ENV=production
|
||||
HOSTNAME=0.0.0.0
|
||||
@@ -110,11 +110,11 @@ ENABLE_REQUEST_LOGS=true
|
||||
AUTH_COOKIE_SECURE=false
|
||||
REQUIRE_API_KEY=false
|
||||
|
||||
# === Domain (change to your domain) ===
|
||||
# === 域名（修改为您的域名） ===
|
||||
BASE_URL=https://llms.seudominio.com
|
||||
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
|
||||
|
||||
# === Cloud Sync (optional) ===
|
||||
# === 云同步（可选） ===
|
||||
# CLOUD_URL=https://cloud.omniroute.online
|
||||
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
|
||||
EOF
|
||||
@@ -136,35 +136,35 @@ docker run -d \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### 2.4 验证其是否正在运行
|
||||
### 2.4 验证运行状态
|
||||
|
||||
```bash
|
||||
docker ps | grep omniroute
|
||||
docker logs omniroute --tail 20
|
||||
```
|
||||
|
||||
它应显示：`[DB] SQLite database ready` 和 `listening on port 20128`。
|
||||
应显示：`[DB] SQLite database ready` 和 `listening on port 20128`。
|
||||
|
||||
---
|
||||
|
||||
## 3.配置nginx（反向代理）
|
||||
## 3. 配置 nginx（反向代理）
|
||||
|
||||
### 3.1 生成 SSL 证书（Cloudflare Origin）
|
||||
|
||||
在 Cloudflare 仪表板中：
|
||||
|
||||
1. 转到 **SSL/TLS → 源服务器**
|
||||
2. 单击**创建证书**
|
||||
3. 保留默认值（15 年，\*.yourdomain.com）
|
||||
4. 复制**原始证书**和**私钥**
|
||||
1. 前往 **SSL/TLS → Origin Server**
|
||||
2. 点击 **Create Certificate**
|
||||
3. 保持默认设置（15 年，\*.yourdomain.com）
|
||||
4. 复制 **Origin Certificate** 和 **Private Key**
|
||||
|
||||
```bash
|
||||
mkdir -p /etc/nginx/ssl
|
||||
|
||||
# Paste the certificate
|
||||
# 粘贴证书
|
||||
nano /etc/nginx/ssl/origin.crt
|
||||
|
||||
# Paste the private key
|
||||
# 粘贴私钥
|
||||
nano /etc/nginx/ssl/origin.key
|
||||
|
||||
chmod 600 /etc/nginx/ssl/origin.key
|
||||
@@ -174,7 +174,7 @@ chmod 600 /etc/nginx/ssl/origin.key
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/sites-available/omniroute << ‘NGINX’
|
||||
# Default server — blocks direct access via IP
|
||||
# 默认服务器 — 阻止通过 IP 直接访问
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
@@ -190,7 +190,7 @@ server {
|
||||
server {
|
||||
listen 443 ssl;
|
||||
listen [::]:443 ssl;
|
||||
server_name llms.yourdomain.com; # Change to your domain
|
||||
server_name llms.yourdomain.com; # 修改为您的域名
|
||||
|
||||
ssl_certificate /etc/nginx/ssl/origin.crt;
|
||||
ssl_certificate_key /etc/nginx/ssl/origin.key;
|
||||
@@ -205,12 +205,12 @@ server {
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# WebSocket support
|
||||
# WebSocket 支持
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection “upgrade”;
|
||||
|
||||
# SSE (Server-Sent Events) — streaming AI responses
|
||||
# SSE (Server-Sent Events) — AI 流式响应
|
||||
proxy_buffering off;
|
||||
proxy_cache off;
|
||||
proxy_read_timeout 300s;
|
||||
@@ -218,7 +218,7 @@ server {
|
||||
}
|
||||
}
|
||||
|
||||
# HTTP → HTTPS redirect
|
||||
# HTTP → HTTPS 重定向
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
@@ -231,50 +231,50 @@ NGINX
|
||||
### 3.3 启用和测试
|
||||
|
||||
```bash
|
||||
# Remove default configuration
|
||||
# 删除默认配置
|
||||
rm -f /etc/nginx/sites-enabled/default
|
||||
|
||||
# Enable OmniRoute
|
||||
# 启用 OmniRoute
|
||||
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
|
||||
|
||||
# Test and reload
|
||||
# 测试并重载
|
||||
nginx -t && systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4.配置 Cloudflare DNS
|
||||
## 4. 配置 Cloudflare DNS
|
||||
|
||||
### 4.1 添加DNS记录
|
||||
### 4.1 添加 DNS 记录
|
||||
|
||||
在 Cloudflare 仪表板 → DNS 中：
|
||||
|
||||
| 类型 | 名称 | 内容 | 代理 |
|
||||
| ---- | ------ | --------------------------- | ------- |
|
||||
| 一个 | `llms` | `203.0.113.10`（虚拟机 IP） | ✅ 代理 |
|
||||
| 类型 | 名称 | 内容 | 代理 |
|
||||
| ---- | ------ | ---------------------- | --------- |
|
||||
| A | `llms` | `203.0.113.10`（VM IP）| ✅ Proxied |
|
||||
|
||||
### 4.2 配置SSL
|
||||
### 4.2 配置 SSL
|
||||
|
||||
在 **SSL/TLS → 概述** 下：
|
||||
在 **SSL/TLS → Overview** 下：
|
||||
|
||||
- 模式：**完全（严格）**
|
||||
- 模式：**Full (Strict)**
|
||||
|
||||
在**SSL/TLS → 边缘证书**下：
|
||||
在 **SSL/TLS → Edge Certificates** 下：
|
||||
|
||||
- 始终使用 HTTPS： ✅ 打开
|
||||
- 最低 TLS 版本：TLS 1.2
|
||||
- 自动 HTTPS 重写： ✅ 开启
|
||||
- Always Use HTTPS：✅ 开启
|
||||
- Minimum TLS Version：TLS 1.2
|
||||
- Automatic HTTPS Rewrites：✅ 开启
|
||||
|
||||
### 4.3 测试
|
||||
|
||||
```bash
|
||||
curl -sI https://llms.seudominio.com/health
|
||||
# Should return HTTP/2 200
|
||||
# 应返回 HTTP/2 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 操作与维护
|
||||
## 5. 运维与维护
|
||||
|
||||
### 升级到新版本
|
||||
|
||||
@@ -291,17 +291,17 @@ docker run -d --name omniroute --restart unless-stopped \
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
docker logs -f omniroute # Real-time stream
|
||||
docker logs omniroute --tail 50 # Last 50 lines
|
||||
docker logs -f omniroute # 实时流
|
||||
docker logs omniroute --tail 50 # 最后 50 行
|
||||
```
|
||||
|
||||
### 手动数据库备份
|
||||
|
||||
```bash
|
||||
# Copy data from the volume to the host
|
||||
# 从卷复制数据到主机
|
||||
docker cp omniroute:/app/data ./backup-$(date +%F)
|
||||
|
||||
# Or compress the entire volume
|
||||
# 或压缩整个卷
|
||||
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
|
||||
alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
|
||||
```
|
||||
@@ -323,7 +323,7 @@ docker start omniroute
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/cloudflare-ips.conf << ‘CF’
|
||||
# Cloudflare IPv4 ranges — update periodically
|
||||
# Cloudflare IPv4 范围 — 定期更新
|
||||
# https://www.cloudflare.com/ips-v4/
|
||||
set_real_ip_from 173.245.48.0/20;
|
||||
set_real_ip_from 103.21.244.0/22;
|
||||
@@ -344,31 +344,31 @@ real_ip_header CF-Connecting-IP;
|
||||
CF
|
||||
```
|
||||
|
||||
将以下内容添加到 `http {}` 块内的 `nginx.conf` 中：
|
||||
将以下内容添加到 `nginx.conf` 的 `http {}` 块中：
|
||||
|
||||
```nginx
|
||||
include /etc/nginx/cloudflare-ips.conf;
|
||||
```
|
||||
|
||||
### 安装fail2ban
|
||||
### 安装 fail2ban
|
||||
|
||||
```bash
|
||||
apt install -y fail2ban
|
||||
systemctl enable fail2ban
|
||||
systemctl start fail2ban
|
||||
|
||||
# Check status
|
||||
# 检查状态
|
||||
fail2ban-client status sshd
|
||||
```
|
||||
|
||||
### 阻止直接访问 Docker 端口
|
||||
|
||||
```bash
|
||||
# Prevent direct external access to port 20128
|
||||
# 防止外部直接访问端口 20128
|
||||
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
|
||||
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
|
||||
|
||||
# Persist the rules
|
||||
# 持久化规则
|
||||
apt install -y iptables-persistent
|
||||
netfilter-persistent save
|
||||
```
|
||||
@@ -377,25 +377,25 @@ netfilter-persistent save
|
||||
|
||||
## 7. 部署到 Cloudflare Workers（可选）
|
||||
|
||||
对于通过 Cloudflare Workers 进行远程访问（无需直接公开 VM）：
|
||||
通过 Cloudflare Workers 进行远程访问（无需直接暴露 VM）：
|
||||
|
||||
```bash
|
||||
# In the local repository
|
||||
# 在本地仓库中
|
||||
cd omnirouteCloud
|
||||
npm install
|
||||
npx wrangler login
|
||||
npx wrangler deploy
|
||||
```
|
||||
|
||||
请参阅 [omnirouteCloud/README.md](../omnirouteCloud/README.md) 处的完整文档。
|
||||
完整文档请参见 [omnirouteCloud/README.md](../omnirouteCloud/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 端口总结
|
||||
## 端口汇总
|
||||
|
||||
| 港口 | 服务 | 访问 |
|
||||
| ----- | --------------- | ------------------------ |
|
||||
| 22 | 22 SSH | 公共（带有fail2ban） |
|
||||
| 80 | nginx HTTP | 重定向 → HTTPS |
|
||||
| 443 | 443 nginx HTTPS | 通过 Cloudflare 代理 |
|
||||
| 20128 | 20128全方位路线 | 仅本地主机（通过 nginx） |
|
||||
| 端口 | 服务 | 访问 |
|
||||
| ----- | ----------- | -------------------------- |
|
||||
| 22 | SSH | 公开（配合 fail2ban） |
|
||||
| 80 | nginx HTTP | 重定向 → HTTPS |
|
||||
| 443 | nginx HTTPS | 通过 Cloudflare 代理 |
|
||||
| 20128 | OmniRoute | 仅本地（通过 nginx） |
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# OmniRoute — Dashboard Features Gallery (中文（简体）)
|
||||
# OmniRoute — Dashboard 功能画廊
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
|
||||
🌐 **语言：** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
|
||||
|
||||
---
|
||||
|
||||
Visual guide to every section of the OmniRoute dashboard.
|
||||
OmniRoute 仪表盘各个页面的可视化导览。
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Providers
|
||||
## 🔌 提供商
|
||||
|
||||
Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
|
||||
管理 AI 提供商连接：包括 OAuth 提供商（Claude Code、Codex、Gemini CLI）、API Key 提供商（Groq、DeepSeek、OpenRouter）以及免费提供商（Qoder、Qwen、Kiro）。Kiro 账户还支持额度余额跟踪，可在 Dashboard → Usage 中查看剩余额度、总额度和续期日期。
|
||||
|
||||
|
||||
|
||||
@@ -18,128 +18,128 @@ Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI)
|
||||
|
||||
## 🎨 Combos
|
||||
|
||||
Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
|
||||
创建模型路由 Combo，支持 6 种策略：priority、weighted、round-robin、random、least-used 和 cost-optimized。每个 Combo 都可以串联多个模型并自动回退，同时提供快捷模板和就绪检查。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 Analytics
|
||||
## 📊 分析
|
||||
|
||||
Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
|
||||
完整的用量分析能力，包括 token 消耗、成本估算、活动热力图、每周分布图和按提供商拆分的数据。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 System Health
|
||||
## 🏥 系统健康
|
||||
|
||||
Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
|
||||
实时监控：运行时长、内存、版本、延迟分位数（p50/p95/p99）、缓存统计以及提供商熔断器状态。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Translator Playground
|
||||
## 🔧 翻译器实验场
|
||||
|
||||
Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
|
||||
提供 4 种 API 翻译调试模式：**Playground**（格式转换器）、**Chat Tester**（实时请求）、**Test Bench**（批量测试）和 **Live Monitor**（实时流监视）。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Model Playground _(v2.0.9+)_
|
||||
## 🎮 模型实验场 _(v2.0.9+)_
|
||||
|
||||
Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
|
||||
直接在仪表盘中测试任意模型。可以选择提供商、模型和端点，使用 Monaco Editor 编写提示词，实时流式查看响应、中途终止请求，并查看耗时指标。
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Themes _(v2.0.5+)_
|
||||
## 🎨 主题 _(v2.0.5+)_
|
||||
|
||||
Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
|
||||
为整个仪表盘自定义颜色主题。可从 7 种预设颜色（Coral、Blue、Red、Green、Violet、Orange、Cyan）中选择，也可以通过任意 hex 颜色创建自定义主题。支持浅色、深色和跟随系统。
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Settings
|
||||
## ⚙️ 设置
|
||||
|
||||
Comprehensive settings panel with tabs:
|
||||
完整的设置面板，包含以下标签页：
|
||||
|
||||
- **General** — System storage, backup management (export/import database)
|
||||
- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
|
||||
- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
|
||||
- **Routing** — Model aliases, background task degradation
|
||||
- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring
|
||||
- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
|
||||
- **General** — 系统存储、备份管理（导出/导入数据库）
|
||||
- **Appearance** — 主题选择器（dark/light/system）、颜色主题预设和自定义颜色、健康日志可见性、侧边栏项目可见性控制
|
||||
- **Security** — API 端点保护、自定义提供商屏蔽、IP 过滤、会话信息
|
||||
- **Routing** — 模型别名、后台任务降级
|
||||
- **Resilience** — 速率限制持久化、熔断器调优、自动禁用被封账户、提供商过期监控
|
||||
- **Advanced** — 配置覆盖、配置审计轨迹、回退降级模式
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 CLI Tools
|
||||
## 🔧 CLI 工具
|
||||
|
||||
One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
|
||||
为 AI 编程工具提供一键配置：Claude Code、Codex CLI、Gemini CLI、OpenClaw、Kilo Code、Antigravity、Cline、Continue、Cursor 和 Factory Droid。支持自动应用/重置配置、连接配置文件和模型映射。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🤖 CLI Agents _(v2.0.11+)_
|
||||
## 🤖 CLI 代理 _(v2.0.11+)_
|
||||
|
||||
Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
|
||||
用于发现和管理 CLI agents 的仪表盘。会以网格展示 14 个内置 agent（Codex、Claude、Goose、Gemini CLI、OpenClaw、Aider、OpenCode、Cline、Qwen Code、ForgeCode、Amazon Q、Open Interpreter、Cursor CLI、Warp），包括：
|
||||
|
||||
- **Installation status** — Installed / Not Found with version detection
|
||||
- **Protocol badges** — stdio, HTTP, etc.
|
||||
- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
|
||||
- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
|
||||
- **安装状态** — Installed / Not Found，并带版本检测
|
||||
- **协议徽标** — stdio、HTTP 等
|
||||
- **自定义 agents** — 可通过表单注册任意 CLI 工具（名称、二进制、版本命令、启动参数）
|
||||
- **CLI Fingerprint Matching** — 按提供商开关，以匹配原生 CLI 请求特征，在保留代理 IP 的同时降低封禁风险
|
||||
|
||||
---
|
||||
|
||||
## 🖼️ Media _(v2.0.3+)_
|
||||
## 🖼️ 媒体 _(v2.0.3+)_
|
||||
|
||||
Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
|
||||
从仪表盘生成图像、视频和音乐。支持 OpenAI、xAI、Together、Hyperbolic、SD WebUI、ComfyUI、AnimateDiff、Stable Audio Open 和 MusicGen。
|
||||
|
||||
---
|
||||
|
||||
## 📝 Request Logs
|
||||
## 📝 请求日志
|
||||
|
||||
Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
|
||||
实时请求日志，支持按提供商、模型、账户和 API Key 过滤。可查看状态码、token 用量、延迟和响应详情。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 API Endpoint
|
||||
## 🌐 API 端点
|
||||
|
||||
Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
|
||||
统一 API 端点页面，按能力拆分展示：Chat Completions、Responses API、Embeddings、Image Generation、Reranking、Audio Transcription、Text-to-Speech、Moderations，以及已注册 API Keys。还集成了 Cloudflare Quick Tunnel 和云代理支持，方便远程访问。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔑 API Key Management
|
||||
## 🔑 API 密钥管理
|
||||
|
||||
Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
|
||||
创建、限定范围并撤销 API Keys。每个 key 都可以限制到特定模型或提供商，并支持 full access 或 read-only 权限。提供可视化密钥管理和用量跟踪。
|
||||
|
||||
---
|
||||
|
||||
## 📋 Audit Log
|
||||
## 📋 审计日志
|
||||
|
||||
Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
|
||||
用于跟踪管理操作，支持按操作类型、执行者、目标、IP 地址和时间戳过滤，可查看完整的安全事件历史。
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ Desktop Application
|
||||
## 🖥️ 桌面应用
|
||||
|
||||
Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
|
||||
适用于 Windows、macOS 和 Linux 的原生 Electron 桌面应用。可以将 OmniRoute 作为独立应用运行，支持系统托盘、离线模式、自动更新和一键安装。
|
||||
|
||||
Key features:
|
||||
主要特性：
|
||||
|
||||
- Server readiness polling (no blank screen on cold start)
|
||||
- System tray with port management
|
||||
- 服务器就绪轮询（冷启动时不再白屏）
|
||||
- 带端口管理的系统托盘
|
||||
- Content Security Policy
|
||||
- Single-instance lock
|
||||
- Auto-update on restart
|
||||
- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
|
||||
- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
|
||||
- 单实例锁
|
||||
- 重启时自动更新
|
||||
- 按平台适配的界面（macOS traffic lights、Windows/Linux 默认标题栏）
|
||||
- 加固的 Electron 打包流程：会在打包前检测并拒绝 standalone bundle 中符号链接的 `node_modules`，防止运行时依赖构建机环境（v2.5.5+）
|
||||
|
||||
📖 See [`electron/README.md`](../electron/README.md) for full documentation.
|
||||
📖 完整文档见 [`electron/README.md`](../electron/README.md)。
|
||||
|
||||
Reference in New Issue
Block a user