mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-31 04:12:10 +03:00
i18n(zh-CN): translate CHANGELOG entries and section headings (#6043)
Adopt zh-CN as a translated locale: translate CHANGELOG + supporting docs. Integrated into release/v3.8.44.
This commit is contained in:
Devin
File diff suppressed because it is too large
Load Diff
@@ -9,134 +9,131 @@
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
npm install # 安装依赖（从 .env.example 自动生成 .env）
|
||||
npm run dev # 开发服务器在 http://localhost:20128
|
||||
npm run build # 生产构建（Next.js 16 独立版）
|
||||
npm run lint # ESLint（预期 0 个错误；警告为先前存在）
|
||||
npm run typecheck:core # TypeScript 检查（应为干净）
|
||||
npm install # 安装依赖（自动从 .env.example 生成 .env）
|
||||
npm run dev # 开发服务器，地址为 http://localhost:20128
|
||||
npm run build # 生产构建（Next.js 16 standalone）
|
||||
npm run lint # ESLint（预期 0 错误；警告为已有）
|
||||
npm run typecheck:core # TypeScript 检查（应无错误）
|
||||
npm run typecheck:noimplicit:core # 严格检查（无隐式 any）
|
||||
npm run test:coverage # 单元测试 + 覆盖门槛（75/75/75/70 — 语句/行/函数/分支）
|
||||
npm run check # lint + 测试组合
|
||||
npm run test:coverage # 单元测试 + 覆盖率门禁（60/60/60/60 — 语句/行/函数/分支）
|
||||
npm run check # lint + test 组合
|
||||
npm run check:cycles # 检测循环依赖
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 单个测试文件（Node.js 原生测试运行器 — 大多数测试）
|
||||
# 运行单个测试文件（Node.js 原生测试运行器 — 大部分测试）
|
||||
node --import tsx/esm --test tests/unit/your-file.test.ts
|
||||
|
||||
# Vitest（MCP 服务器，autoCombo，缓存）
|
||||
# Vitest（MCP 服务器、autoCombo、缓存）
|
||||
npm run test:vitest
|
||||
|
||||
# 所有测试套件
|
||||
# 全部测试套件
|
||||
npm run test:all
|
||||
```
|
||||
|
||||
有关完整的测试矩阵，请参见 `CONTRIBUTING.md` → "运行测试"。有关深层架构，请参见 `AGENTS.md`。
|
||||
完整测试矩阵见 `CONTRIBUTING.md` → "Running Tests"。深度架构见 `AGENTS.md`。
|
||||
|
||||
---
|
||||
|
||||
## 项目概览
|
||||
|
||||
**OmniRoute** — 统一的 AI 代理/路由器。一个端点，160+ LLM 提供者，自动回退。
|
||||
**OmniRoute** — 统一的 AI 代理/路由。一个端点接入 236 家 LLM 服务商，自动容灾。
|
||||
|
||||
| 层级 | 位置 | 目的 |
|
||||
| ---------- | ----------------------- | ---------------------------------------------------------------- |
|
||||
| API 路由 | `src/app/api/v1/` | Next.js 应用路由 — 入口点 |
|
||||
| 处理程序 | `open-sse/handlers/` | 请求处理（聊天、嵌入等） |
|
||||
| 执行器 | `open-sse/executors/` | 特定提供者的 HTTP 调度 |
|
||||
| 转换器 | `open-sse/translator/` | 格式转换（OpenAI↔Claude↔Gemini） |
|
||||
| 转换器 | `open-sse/transformer/` | 响应 API ↔ 聊天完成 |
|
||||
| 服务 | `open-sse/services/` | 组合路由、速率限制、缓存等 |
|
||||
| 数据库 | `src/lib/db/` | SQLite 域模块（45+ 文件，55 次迁移） |
|
||||
| 域/策略 | `src/domain/` | 策略引擎、成本规则、回退逻辑 |
|
||||
| MCP 服务器 | `open-sse/mcp-server/` | 37 个工具（30 基础 + 3 内存 + 4 技能），3 个传输，大约 13 个范围 |
|
||||
| A2A 服务器 | `src/lib/a2a/` | JSON-RPC 2.0 代理协议 |
|
||||
| 技能 | `src/lib/skills/` | 可扩展的技能框架 |
|
||||
| 内存 | `src/lib/memory/` | 持久化对话内存 |
|
||||
| 层级 | 位置 | 用途 |
|
||||
| ------------ | ----------------------- | ------------------------------------------------------------------------------------ |
|
||||
| API 路由 | `src/app/api/v1/` | Next.js App Router — 入口点 |
|
||||
| 处理器 | `open-sse/handlers/` | 请求处理（对话、嵌入等） |
|
||||
| 执行器 | `open-sse/executors/` | 服务商特定的 HTTP 分发 |
|
||||
| 翻译器 | `open-sse/translator/` | 格式转换（OpenAI↔Claude↔Gemini） |
|
||||
| 转换器 | `open-sse/transformer/` | Responses API ↔ Chat Completions |
|
||||
| 服务 | `open-sse/services/` | Combo 路由、速率限制、缓存等 |
|
||||
| 数据库 | `src/lib/db/` | SQLite 领域模块（94 个文件，106 个迁移） |
|
||||
| 领域/策略 | `src/domain/` | 策略引擎、成本规则、容灾逻辑 |
|
||||
| MCP 服务器 | `open-sse/mcp-server/` | 94 个工具（34 个基础 + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin 模块），3 种传输（stdio / SSE / Streamable HTTP），30 个权限域 |
|
||||
| A2A 服务器 | `src/lib/a2a/` | JSON-RPC 2.0 代理协议 |
|
||||
| 技能 | `src/lib/skills/` | 可扩展技能框架 |
|
||||
| 记忆 | `src/lib/memory/` | 持久化对话记忆 |
|
||||
|
||||
Monorepo: `src/`（Next.js 16 应用），`open-sse/`（流媒体引擎工作区），`electron/`（桌面应用），`tests/`，`bin/`（CLI 入口点）。
|
||||
Monorepo：`src/`（Next.js 16 应用）、`open-sse/`（流式引擎 workspace）、`electron/`（桌面应用）、`tests/`、`bin/`（CLI 入口点）。
|
||||
|
||||
---
|
||||
|
||||
## 请求管道
|
||||
## 请求管线
|
||||
|
||||
```
|
||||
客户端 → /v1/chat/completions (Next.js 路由)
|
||||
→ CORS → Zod 验证 → 认证? → 策略检查 → 提示注入保护
|
||||
Client → /v1/chat/completions (Next.js 路由)
|
||||
→ CORS → Zod 校验 → 鉴权？ → 策略检查 → 提示注入安全护栏
|
||||
→ handleChatCore() [open-sse/handlers/chatCore.ts]
|
||||
→ 缓存检查 → 速率限制 → 组合路由?
|
||||
→ resolveComboTargets() → 针对每个目标调用 handleSingleModel()
|
||||
→ 缓存检查 → 速率限制 → Combo 路由？
|
||||
→ resolveComboTargets() → 每个目标调用 handleSingleModel()
|
||||
→ translateRequest() → getExecutor() → executor.execute()
|
||||
→ fetch() 上游 → 重试 w/ 回退
|
||||
→ 响应翻译 → SSE 流或 JSON
|
||||
→ 如果是 Responses API: responsesTransformer.ts TransformStream
|
||||
→ 向上游发送 fetch() → 带退避重试
|
||||
→ 响应转换 → SSE 流或 JSON
|
||||
→ 如果是 Responses API：responsesTransformer.ts TransformStream
|
||||
```
|
||||
|
||||
API 路由遵循一致的模式：`路由 → CORS 预检 → Zod 请求体验证 → 可选认证 (extractApiKey/isValidApiKey) → API 密钥策略执行 → 处理程序委派 (open-sse)`。没有全局的 Next.js 中间件 — 拦截是路由特定的。
|
||||
API 路由遵循一致的模式：`路由 → CORS 预检 → Zod 请求体校验 → 可选鉴权（extractApiKey/isValidApiKey）→ API Key 策略执行 → 处理器委派（open-sse）`。没有全局 Next.js 中间件 — 拦截在路由级别进行。
|
||||
|
||||
**组合路由** (`open-sse/services/combo.ts`): 14 种策略（优先级、加权、优先填充、轮询、P2C、随机、最少使用、成本优化、重置感知、严格随机、自动、lkgp、上下文优化、上下文中继）。每个目标调用 `handleSingleModel()`，该函数用每个目标的错误处理和电路断路器检查包装 `handleChatCore()`。有关 9 因子自动组合评分的信息，请参见 `docs/routing/AUTO-COMBO.md`，有关 3 层弹性的信息，请参见 `docs/architecture/RESILIENCE_GUIDE.md`。
|
||||
**Combo 路由** (`open-sse/services/combo.ts`)：17 种策略（priority、weighted、fill-first、round-robin、P2C、random、least-used、cost-optimized、reset-aware、reset-window、headroom、strict-random、auto、lkgp、context-optimized、context-relay、fusion）。每个目标调用 `handleSingleModel()`，该函数封装了 `handleChatCore()` 并附带逐目标的错误处理和熔断器检查。`fusion` 策略是一个例外：它并行扇出到一组模型面板，然后由裁判模型综合出一个最终答案 (`open-sse/services/fusion.ts`)。关于 12 因子 Auto-Combo 评分及完整策略表，见 `docs/routing/AUTO-COMBO.md`；关于 3 层容灾机制，见 `docs/architecture/RESILIENCE_GUIDE.md`。
|
||||
|
||||
---
|
||||
|
||||
## 弹性运行时状态
|
||||
## 容灾运行时状态
|
||||
|
||||
OmniRoute 有三种相关但不同的临时故障机制。在调试路由行为时，请保持它们的范围分开。请参见
|
||||
[3 层弹性图](./docs/diagrams/exported/resilience-3layers.svg)
|
||||
（来源: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)）
|
||||
以获取一目了然的地图。
|
||||
OmniRoute 有三个彼此相关但各自独立的临时故障机制。调试路由行为时请保持它们的作用域分离。快速概览参见 [3 层容灾示意图](./docs/diagrams/exported/resilience-3layers.svg)（源文件：[docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)）。
|
||||
|
||||
### 提供者电路断路器
|
||||
### 服务商熔断器
|
||||
|
||||
**范围**: 整个提供者，例如 `glm`、`openai`、`anthropic`。
|
||||
**作用域**：整个服务商，例如 `glm`、`openai`、`anthropic`。
|
||||
|
||||
**目的**: 停止向一个在上游/服务级别反复失败的提供者发送流量，以便一个不健康的提供者不会减慢每个请求的速度。
|
||||
**目的**：当一个服务商在上游/服务层面反复失败时，停止向其发送流量，避免一个不健康的服务商拖慢所有请求。
|
||||
|
||||
**实现**:
|
||||
**实现**：
|
||||
|
||||
- 核心类: `src/shared/utils/circuitBreaker.ts`
|
||||
- 聊天门控/执行连接: `src/sse/handlers/chatHelpers.ts`，`src/sse/handlers/chat.ts`
|
||||
- 运行时状态 API: `src/app/api/monitoring/health/route.ts`
|
||||
- 共享包装器: `open-sse/services/accountFallback.ts`
|
||||
- 持久化状态表: `domain_circuit_breakers`
|
||||
- 核心类：`src/shared/utils/circuitBreaker.ts`
|
||||
- 对话门禁/执行接线：`src/sse/handlers/chatHelpers.ts`、`src/sse/handlers/chat.ts`
|
||||
- 运行时状态 API：`src/app/api/monitoring/health/route.ts`
|
||||
- 共享封装：`open-sse/services/accountFallback.ts`
|
||||
- 持久化状态表：`domain_circuit_breakers`
|
||||
|
||||
**状态**:
|
||||
**状态**：
|
||||
|
||||
- `CLOSED`: 允许正常流量。
|
||||
- `OPEN`: 提供者暂时被阻止；调用者会收到提供者电路打开的响应，或者组合路由跳过到另一个目标。
|
||||
- `HALF_OPEN`: 重置超时已过；允许探测请求。成功关闭断路器，失败再次打开。
|
||||
- `CLOSED`：允许正常流量。
|
||||
- `OPEN`：服务商被暂时阻断；调用方收到 provider-circuit-open 响应，或 Combo 路由跳转到其他目标。
|
||||
- `HALF_OPEN`：重置超时已过；允许一次探测请求。成功则闭合熔断器，失败则重新打开。
|
||||
|
||||
**默认值** (`open-sse/config/constants.ts`):
|
||||
**默认值** (`open-sse/config/constants.ts`)：
|
||||
|
||||
- OAuth 提供者: 阈值 `3`，重置超时 `60s`。
|
||||
- API 密钥提供者: 阈值 `5`，重置超时 `30s`。
|
||||
- 本地提供者: 阈值 `2`，重置超时 `15s`。
|
||||
- OAuth 服务商：阈值 `3`，重置超时 `60s`。
|
||||
- API Key 服务商：阈值 `5`，重置超时 `30s`。
|
||||
- 本地服务商：阈值 `2`，重置超时 `15s`。
|
||||
|
||||
只有提供者级别的故障状态应该触发提供者断路器：
|
||||
仅服务商级别的失败状态才应触发服务商熔断器：
|
||||
|
||||
```ts
|
||||
(408, 500, 502, 503, 504);
|
||||
```
|
||||
|
||||
不要因正常的账户/密钥/模型错误（如大多数 `401`、`403` 或 `429` 情况）而触发整个提供者断路器。这些通常属于连接冷却或模型锁定。除非被归类为终端提供者/账户错误，否则通用 API 密钥提供者的 `403` 应该是可恢复的。
|
||||
不要为普通的账户/密钥/模型错误（如大多数 `401`、`403` 或 `429` 情况）触发整个服务商的熔断器。这些通常归属于连接冷却或模型锁定。通用 API Key 服务商的 `403` 应该是可恢复的，除非被归类为终端服务商/账户错误。
|
||||
|
||||
断路器使用懒惰恢复，而不是后台定时器。当 `OPEN` 过期时，像 `getStatus()`、`canExecute()` 和 `getRetryAfterMs()` 这样的读取会将状态刷新为 `HALF_OPEN`，以便仪表板和组合候选构建器不会永远排除一个过期的提供者。
|
||||
熔断器采用惰性恢复，而不是后台定时器。当 `OPEN` 过期时，对 `getStatus()`、`canExecute()` 和 `getRetryAfterMs()` 的读取会将状态刷新为 `HALF_OPEN`，这样仪表盘和 Combo 候选构建器就不会无限期地排除已过期的服务商。
|
||||
|
||||
### 连接冷却
|
||||
|
||||
**范围**: 一个提供者连接/账户/密钥。
|
||||
**作用域**：单个服务商连接/账户/密钥。
|
||||
|
||||
**目的**: 暂时跳过一个坏的密钥/账户，同时允许同一提供者的其他连接继续处理请求。
|
||||
**目的**：暂时跳过一个有问题的密钥/账户，同时让同一服务商的其他连接继续处理请求。
|
||||
|
||||
**实现**:
|
||||
**实现**：
|
||||
|
||||
- 写入/更新路径: `src/sse/services/auth.ts::markAccountUnavailable()`
|
||||
- 账户选择/过滤: `src/sse/services/auth.ts::getProviderCredentials...`
|
||||
- 冷却计算: `open-sse/services/accountFallback.ts::checkFallbackError()`
|
||||
- 设置: `src/lib/resilience/settings.ts`
|
||||
- 写入/更新路径：`src/sse/services/auth.ts::markAccountUnavailable()`
|
||||
- 账户选择/过滤：`src/sse/services/auth.ts::getProviderCredentials...`
|
||||
- 冷却计算：`open-sse/services/accountFallback.ts::checkFallbackError()`
|
||||
- 设置：`src/lib/resilience/settings.ts`
|
||||
|
||||
提供者连接上的重要字段：
|
||||
服务商连接上的重要字段：
|
||||
|
||||
```ts
|
||||
rateLimitedUntil;
|
||||
@@ -147,247 +144,359 @@ errorCode;
|
||||
backoffLevel;
|
||||
```
|
||||
|
||||
在账户选择期间，当以下条件成立时，连接会被跳过：
|
||||
在选择账户期间，满足以下条件时连接被跳过：
|
||||
|
||||
```ts
|
||||
new Date(rateLimitedUntil).getTime() > Date.now();
|
||||
```
|
||||
|
||||
冷却也是懒惰的：当 `rateLimitedUntil` 在过去时，连接再次变得合格。在成功使用时，`clearAccountError()` 会清除 `testStatus`、`rateLimitedUntil`、错误字段和 `backoffLevel`。
|
||||
冷却同样是惰性的：当 `rateLimitedUntil` 已过期时，连接重新变为可用。成功使用后，`clearAccountError()` 会清除 `testStatus`、`rateLimitedUntil`、错误字段和 `backoffLevel`。
|
||||
|
||||
默认连接冷却行为：
|
||||
|
||||
- OAuth 基础冷却: `5s`。
|
||||
- API 密钥基础冷却: `3s`。
|
||||
- API 密钥 `429` 应优先考虑上游重试提示（`Retry-After`、重置头或可解析的重置文本），如果可用。
|
||||
- 重复的可恢复故障使用指数回退：
|
||||
- OAuth 基础冷却：`5s`。
|
||||
- API Key 基础冷却：`3s`。
|
||||
- API Key 的 `429` 应优先使用上游重试提示（`Retry-After`、重置头或可解析的重置文本），如果可用的话。
|
||||
- 连续的可恢复失败采用指数退避：
|
||||
|
||||
```ts
|
||||
baseCooldownMs * 2 ** failureIndex;
|
||||
```
|
||||
|
||||
反雷霆集群保护防止同一连接上的并发故障反复延长冷却或双重增加 `backoffLevel`。
|
||||
防惊群效应守卫阻止同一连接上的并发失败反复延长冷却时间或重复递增 `backoffLevel`。
|
||||
|
||||
终端状态不是冷却状态。`banned`、`expired` 和 `credits_exhausted` 旨在保持不可用，直到凭据/设置更改或操作员重置它们。不要用瞬态冷却状态覆盖终端状态。
|
||||
终端状态不是冷却行为。`banned`、`expired` 和 `credits_exhausted` 应当保持不可用，直到凭据/设置发生变化或运维人员手动重置。不要用临时冷却状态覆盖终端状态。
|
||||
|
||||
### 模型锁定
|
||||
|
||||
**范围**: 提供者 + 连接 + 模型。
|
||||
**作用域**：服务商 + 连接 + 模型。
|
||||
|
||||
**目的**: 避免在只有一个模型不可用或配额限制的情况下禁用整个连接。
|
||||
**目的**：当只有一个模型不可用或被该连接配额限制时，避免禁用整个连接。
|
||||
|
||||
示例：
|
||||
|
||||
- 每模型配额提供者返回 `429`。
|
||||
- 本地提供者因缺少一个模型返回 `404`。
|
||||
- 提供者特定的模式/模型权限失败，例如选择的 Grok 模式。
|
||||
- 按模型配额的服务商返回 `429`。
|
||||
- 本地服务商对某个缺失模型返回 `404`。
|
||||
- 服务商特定的模式/模型权限失败，例如选定的 Grok 模式。
|
||||
|
||||
模型锁定位于 `open-sse/services/accountFallback.ts`，允许同一连接继续处理其他模型。
|
||||
模型锁定位于 `open-sse/services/accountFallback.ts` 中，允许同一连接继续为其他模型提供服务。
|
||||
|
||||
### 调试指导
|
||||
|
||||
- 如果一个提供者的所有密钥都被跳过，请检查提供者断路器状态和每个连接的 `rateLimitedUntil`/`testStatus`。
|
||||
- 如果一个提供者在重置窗口后似乎被永久排除，请检查代码是否在读取原始 `state` 而不是使用 `getStatus()`/`canExecute()`。
|
||||
- 如果一个提供者密钥失败但其他密钥应该有效，请优先考虑连接冷却而不是提供者断路器。
|
||||
- 如果只有一个模型失败，请优先考虑模型锁定而不是连接冷却。
|
||||
- 如果一个状态应该自我恢复，它应该有一个未来的时间戳/重置超时和一个读取路径来刷新过期状态。永久状态需要手动凭据或配置更改。
|
||||
- 如果某个服务商的所有密钥都被跳过，检查服务商熔断器状态和每个连接的 `rateLimitedUntil`/`testStatus`。
|
||||
- 如果某个服务商在重置窗口后似乎被永久排除，检查代码是否在直接读取原始的 `state`，而不是使用 `getStatus()`/`canExecute()`。
|
||||
- 如果某个服务商的一个密钥失败但其他密钥应该可用，优先采用连接冷却而非服务商熔断器。
|
||||
- 如果只有一个模型失败，优先采用模型锁定而非连接冷却。
|
||||
- 如果一个状态应该自动恢复，它应该有一个未来的时间戳/重置超时，以及一个能刷新过期状态的读取路径。永久状态需要手动修改凭据或配置。
|
||||
|
||||
---
|
||||
|
||||
## 关键约定
|
||||
|
||||
### 代码风格
|
||||
|
||||
- **2个空格**，分号，双引号，100字符宽度，es5尾随逗号（通过lint-staged和Prettier强制执行）
|
||||
- **导入**：外部 → 内部（`@/`，`@omniroute/open-sse`）→ 相对
|
||||
- **命名**：文件=camelCase/kebab，组件=PascalCase，常量=UPPER_SNAKE
|
||||
- **ESLint**：`no-eval`，`no-implied-eval`，`no-new-func` = 在任何地方都报错；`no-explicit-any` = 在`open-sse/`和`tests/`中警告
|
||||
- **TypeScript**：`strict: false`，目标ES2022，模块esnext，解析器为打包器。优先使用显式类型。
|
||||
- **2 空格**，分号，双引号，100 字符宽度，es5 尾逗号（由 lint-staged 通过 Prettier 强制执行）
|
||||
- **导入顺序**：外部 → 内部 (`@/`、`@omniroute/open-sse`) → 相对路径
|
||||
- **命名规范**：文件=camelCase/kebab、组件=PascalCase、常量=UPPER_SNAKE
|
||||
- **ESLint**：`no-eval`、`no-implied-eval`、`no-new-func` 在所有位置均为 error；`no-explicit-any` 在 `open-sse/` 和 `tests/` 中为 warn
|
||||
- **TypeScript**：`strict: false`，目标 ES2022，模块 esnext，解析策略 bundler。首选显式类型。
|
||||
|
||||
### 数据库
|
||||
|
||||
- **始终**通过`src/lib/db/`域模块 — **绝不**在路由或处理程序中编写原始SQL
|
||||
- **绝不**在`src/lib/localDb.ts`中添加逻辑（仅为重新导出层）
|
||||
- **绝不**从`localDb.ts`进行桶导入 — 而是导入特定的`db/`模块
|
||||
- DB单例：`getDbInstance()`来自`src/lib/db/core.ts`（WAL日志记录）
|
||||
- 迁移：`src/lib/db/migrations/` — 版本化的SQL文件，幂等，在事务中运行
|
||||
- **始终**通过 `src/lib/db/` 领域模块操作 — **绝不**在路由或处理器中直接编写 SQL
|
||||
- **绝不**向 `src/lib/localDb.ts` 添加逻辑（仅作为再导出层）
|
||||
- **绝不**从 `localDb.ts` 做 barrel 导入 — 应导入具体的 `db/` 模块
|
||||
- 数据库单例：`getDbInstance()`，来自 `src/lib/db/core.ts`（WAL 日志）
|
||||
- 迁移：`src/lib/db/migrations/` — 版本化的 SQL 文件，幂等，在事务中运行
|
||||
|
||||
### 错误处理
|
||||
|
||||
- 使用特定错误类型的try/catch，使用pino上下文记录
|
||||
- 在SSE流中绝不吞噬错误 — 使用中止信号进行清理
|
||||
- 返回适当的HTTP状态码（4xx/5xx）
|
||||
- 使用 try/catch 并指定错误类型，通过 pino 上下文记录日志
|
||||
- 绝不在 SSE 流中静默吞掉错误 — 使用 abort 信号进行清理
|
||||
- 返回正确的 HTTP 状态码（4xx/5xx）
|
||||
|
||||
### 安全性
|
||||
### 安全
|
||||
|
||||
- **绝不**使用`eval()`，`new Function()`或隐式eval
|
||||
- 使用Zod模式验证所有输入
|
||||
- 在静态存储中加密凭据（AES-256-GCM）
|
||||
- 上游头部拒绝列表：`src/shared/constants/upstreamHeaders.ts` — 编辑时保持清理、Zod模式和单元测试一致
|
||||
- **公共上游凭据**（Gemini/Antigravity/Windsurf风格的OAuth client_id/secret + 从公共CLI提取的Firebase Web密钥）：**必须**通过`resolvePublicCred()`嵌入，来自`open-sse/utils/publicCreds.ts` — **绝不**作为字符串字面量。请参见`docs/security/PUBLIC_CREDS.md`以获取强制模式。
|
||||
- **错误响应**（HTTP / SSE / 执行器 / MCP处理程序）：**必须**通过`buildErrorBody()`或`sanitizeErrorMessage()`路由，来自`open-sse/utils/error.ts` — **绝不**将原始`err.stack`或`err.message`放入响应体中。请参见`docs/security/ERROR_SANITIZATION.md`。
|
||||
- **从变量构建的Shell命令**：在调用`exec()`/`spawn()`时，如果脚本需要运行时值，通过`env`选项传递（自动进行Shell转义） — **绝不**将不受信任/外部路径字符串插入脚本体中。参考：`src/mitm/cert/install.ts::updateNssDatabases`。
|
||||
- **默认安全库**（[tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)）：在添加新的安全敏感表面时，优先使用Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink，而不是自定义实现。
|
||||
- **绝不**使用 `eval()`、`new Function()` 或隐式 eval
|
||||
- 使用 Zod Schema 校验所有输入
|
||||
- 静态加密凭据（AES-256-GCM）
|
||||
- 上游请求头黑名单：`src/shared/constants/upstreamHeaders.ts` — 编辑时保持 sanitize、Zod Schema 和单元测试一致
|
||||
- **公开的上游凭据**（Gemini/Antigravity/Windsurf 风格的 OAuth client_id/secret + 从公开 CLI 提取的 Firebase Web 密钥）：**必须**通过 `open-sse/utils/publicCreds.ts` 中的 `resolvePublicCred()` 嵌入 — **绝不**使用字符串字面量。强制性模式见 `docs/security/PUBLIC_CREDS.md`。
|
||||
- **错误响应**（HTTP / SSE / 执行器 / MCP 处理器）：**必须**通过 `open-sse/utils/error.ts` 中的 `buildErrorBody()` 或 `sanitizeErrorMessage()` 传递 — **绝不**在响应体中放入原始的 `err.stack` 或 `err.message`。详见 `docs/security/ERROR_SANITIZATION.md`。
|
||||
- **由变量构建的 Shell 命令**：当使用需要运行时值的脚本调用 `exec()`/`spawn()` 时，通过 `env` 选项传递（自动 shell 转义）— **绝不**将不受信任的外部路径字符串插值到脚本体中。参考：`src/mitm/cert/install.ts::updateNssDatabases`。
|
||||
- **安全优先的库**（[tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)）：在添加新的安全性敏感功能时，优先选择 Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink，而非自定义实现。
|
||||
|
||||
---
|
||||
|
||||
## 常见修改场景
|
||||
|
||||
### 添加新提供者
|
||||
### 新增服务商
|
||||
|
||||
1. 在`src/shared/constants/providers.ts`中注册（加载时进行Zod验证）
|
||||
2. 如果需要自定义逻辑，则在`open-sse/executors/`中添加执行器（扩展`BaseExecutor`）
|
||||
3. 如果是非OpenAI格式，则在`open-sse/translator/`中添加翻译器
|
||||
4. 如果基于OAuth，则在`src/lib/oauth/constants/oauth.ts`中添加OAuth配置 — 如果上游CLI提供公共client_id/secret，则通过`resolvePublicCred()`嵌入（见`docs/security/PUBLIC_CREDS.md`），**绝不**作为字面量
|
||||
5. 在`open-sse/config/providerRegistry.ts`中注册模型
|
||||
6. 在`tests/unit/`中编写测试（如果添加了新的嵌入默认，则包括publicCreds形状断言）
|
||||
1. 在 `src/shared/constants/providers.ts` 中注册（加载时使用 Zod 校验）
|
||||
2. 如果存在自定义逻辑，在 `open-sse/executors/` 中添加执行器（继承 `BaseExecutor`）
|
||||
3. 如果非 OpenAI 格式，在 `open-sse/translator/` 中添加翻译器
|
||||
4. 如果是基于 OAuth 的，在 `src/lib/oauth/constants/oauth.ts` 中添加 OAuth 配置 — 如果上游 CLI 附带公开的 client_id/secret，通过 `resolvePublicCred()` 嵌入（参见 `docs/security/PUBLIC_CREDS.md`），**绝不**使用字面量
|
||||
5. 在 `open-sse/config/providerRegistry.ts` 中注册模型
|
||||
6. 在 `tests/unit/` 中编写测试（如果添加了新的嵌入式默认值，请包含 publicCreds 形态断言）
|
||||
|
||||
### 添加新API路由
|
||||
### 新增 API 路由
|
||||
|
||||
1. 在`src/app/api/v1/your-route/`下创建目录
|
||||
2. 创建`route.ts`，包含`GET`/`POST`处理程序
|
||||
3. 遵循模式：CORS → Zod主体验证 → 可选身份验证 → 处理程序委托
|
||||
4. 处理程序放在`open-sse/handlers/`中（从那里导入，而不是内联）
|
||||
5. 错误响应使用`buildErrorBody()` / `errorResponse()`来自`open-sse/utils/error.ts`（自动清理 — 绝不将`err.stack`或`err.message`原样放入主体中）。请参见`docs/security/ERROR_SANITIZATION.md`。
|
||||
6. 添加测试 — 包括至少一个断言，确保错误响应不泄露堆栈跟踪（`!body.error.message.includes("at /")`）
|
||||
1. 在 `src/app/api/v1/your-route/` 下创建目录
|
||||
2. 创建 `route.ts`，包含 `GET`/`POST` 处理器
|
||||
3. 遵循模式：CORS → Zod 请求体校验 → 可选鉴权 → 处理器委派
|
||||
4. 处理器放在 `open-sse/handlers/` 中（从那里导入，不要内联）
|
||||
5. 错误响应使用 `open-sse/utils/error.ts` 中的 `buildErrorBody()` / `errorResponse()`（自动脱敏 — 绝不在响应体中放入原始的 `err.stack` 或 `err.message`）。详见 `docs/security/ERROR_SANITIZATION.md`。
|
||||
6. 添加测试 — 包含至少一个断言，验证错误响应不会泄露堆栈跟踪 (`!body.error.message.includes("at /")`)
|
||||
|
||||
### 添加新DB模块
|
||||
### 新增数据库模块
|
||||
|
||||
1. 创建`src/lib/db/yourModule.ts` — 从`./core.ts`导入`getDbInstance`
|
||||
2. 导出您的域表的CRUD函数
|
||||
3. 如果需要新表，则在`src/lib/db/migrations/`中添加迁移
|
||||
4. 从`src/lib/localDb.ts`重新导出（仅添加到重新导出列表中）
|
||||
1. 创建 `src/lib/db/yourModule.ts` — 从 `./core.ts` 导入 `getDbInstance`
|
||||
2. 为你的领域表导出 CRUD 函数
|
||||
3. 如果需要新表，在 `src/lib/db/migrations/` 中添加迁移
|
||||
4. 从 `src/lib/localDb.ts` 再导出（仅添加到再导出列表）
|
||||
5. 编写测试
|
||||
|
||||
### 添加新MCP工具
|
||||
### 新增 MCP 工具
|
||||
|
||||
1. 在`open-sse/mcp-server/tools/`中添加工具定义，包含Zod输入模式 + 异步处理程序
|
||||
2. 在工具集中注册（通过`createMcpServer()`连接）
|
||||
3. 分配给适当的范围
|
||||
4. 编写测试（工具调用记录到`mcp_audit`表中）
|
||||
1. 在 `open-sse/mcp-server/tools/` 中添加工具定义，包含 Zod 输入 Schema + async 处理器
|
||||
2. 在工具集中注册（由 `createMcpServer()` 连接）
|
||||
3. 分配到适当的权限域
|
||||
4. 编写测试（工具调用记录到 `mcp_audit` 表）
|
||||
|
||||
### 添加新A2A技能
|
||||
### 新增 A2A 技能
|
||||
|
||||
1. 在`src/lib/a2a/skills/`中创建技能（已有5个：智能路由、配额管理、提供者发现、成本分析、健康报告）
|
||||
1. 在 `src/lib/a2a/skills/` 中创建技能（已有 5 个：smart-routing、quota-management、provider-discovery、cost-analysis、health-report）
|
||||
2. 技能接收任务上下文（消息、元数据）→ 返回结构化结果
|
||||
3. 在`src/lib/a2a/taskExecution.ts`中的`A2A_SKILL_HANDLERS`中注册
|
||||
4. 在`src/app/.well-known/agent.json/route.ts`中公开（代理卡）
|
||||
5. 在`tests/unit/`中编写测试
|
||||
6. 在`docs/frameworks/A2A-SERVER.md`技能表中记录
|
||||
3. 在 `src/lib/a2a/taskExecution.ts` 的 `A2A_SKILL_HANDLERS` 中注册
|
||||
4. 在 `src/app/.well-known/agent.json/route.ts`（Agent Card）中暴露
|
||||
5. 在 `tests/unit/` 中编写测试
|
||||
6. 在 `docs/frameworks/A2A-SERVER.md` 技能表中记录
|
||||
|
||||
### 添加新云代理
|
||||
### 新增云代理
|
||||
|
||||
1. 在`src/lib/cloudAgent/agents/`中创建代理类，扩展`CloudAgentBase`（已有3个：codex-cloud、devin、jules）
|
||||
2. 实现`createTask`、`getStatus`、`approvePlan`、`sendMessage`、`listSources`
|
||||
3. 在`src/lib/cloudAgent/registry.ts`中注册
|
||||
4. 如果需要，添加OAuth/凭据处理（`src/lib/oauth/providers/`）
|
||||
5. 测试 + 在`docs/frameworks/CLOUD_AGENT.md`中记录
|
||||
1. 在 `src/lib/cloudAgent/agents/` 中创建代理类，继承 `CloudAgentBase`（已有 3 个：codex-cloud、devin、jules）
|
||||
2. 实现 `createTask`、`getStatus`、`approvePlan`、`sendMessage`、`listSources`
|
||||
3. 在 `src/lib/cloudAgent/registry.ts` 中注册
|
||||
4. 如需要，添加 OAuth/凭据处理 (`src/lib/oauth/providers/`)
|
||||
5. 编写测试并在 `docs/frameworks/CLOUD_AGENT.md` 中记录
|
||||
|
||||
### 添加新护栏 / 评估 / 技能 / Webhook事件
|
||||
### 新增嵌入式服务
|
||||
|
||||
- 护栏：`src/lib/guardrails/` → 文档：`docs/security/GUARDRAILS.md`
|
||||
1. 在 `src/lib/services/installers/{name}.ts` 中参照 `ninerouter.ts` 创建安装器（使用 `installers/utils.ts` 中的 `runNpm` — 无 shell 插值，硬规则 #13）。
|
||||
2. 在 `src/lib/services/bootstrap.ts` 中注册该服务（添加到 `SERVICES[]` 数组并扩展 `buildSpawnArgsFactory()`）。
|
||||
3. 在 `src/lib/db/migrations/` 中为新服务添加数据库种子行（`version_manager` 表，`status='not_installed'`，`auto_start=0`）。
|
||||
4. 在 `src/app/api/services/{name}/` 下创建 7 个 API 端点（`_lib.ts`、`install`、`start`、`stop`、`restart`、`update`、`status`、`auto-start`）。所有错误通过 `createErrorResponse()` 委托。共享的 `logs` 端点已通过 `[name]/logs/route.ts` 连接。
|
||||
5. 确认 `/api/services/` 在 `src/server/authz/routeGuard.ts` 的 `LOCAL_ONLY_API_PREFIXES` 中；如果添加了新的前缀，添加一个测试断言 `isLocalOnlyPath()` 返回 `true`（硬规则 #17）。
|
||||
6. 在 `src/app/(dashboard)/dashboard/providers/services/tabs/` 中添加 UI 标签页，复用 `ServiceStatusCard`、`ServiceLifecycleButtons`、`ServiceLogsPanel`。
|
||||
7. 在 `docs/frameworks/EMBEDDED-SERVICES.md`（更新 §1 服务表 + §4 API 参考）和 `docs/openapi.yaml` 中记录。
|
||||
8. 编写测试：单元测试 (`tests/unit/services/`)、集成测试 (`tests/integration/services/`，由 `RUN_SERVICES_INT=1` 门控），并更新 `docs/ops/RELEASE_CHECKLIST.md` 的冒烟测试章节。
|
||||
|
||||
### 新增安全护栏 / 评估 / 技能 / Webhook 事件
|
||||
|
||||
- 安全护栏：`src/lib/guardrails/` → 文档：`docs/security/GUARDRAILS.md`
|
||||
- 评估套件：`src/lib/evals/` → 文档：`docs/frameworks/EVALS.md`
|
||||
- 技能（沙盒）：`src/lib/skills/` → 文档：`docs/frameworks/SKILLS.md`
|
||||
- Webhook事件：`src/lib/webhookDispatcher.ts` → 文档：`docs/frameworks/WEBHOOKS.md`
|
||||
- 技能（沙箱）：`src/lib/skills/` → 文档：`docs/frameworks/SKILLS.md`
|
||||
- Webhook 事件：`src/lib/webhookDispatcher.ts` → 文档：`docs/frameworks/WEBHOOKS.md`
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
对于任何非平凡的更改，请先阅读相应的深入分析：
|
||||
对于任何非平凡修改，请先阅读对应的深度文档：
|
||||
|
||||
| 领域 | 文档 |
|
||||
| ------------------------------- | ----------------------------------------------------------------- |
|
||||
| 仓库导航 | `docs/architecture/REPOSITORY_MAP.md` |
|
||||
| 架构 | `docs/architecture/ARCHITECTURE.md` |
|
||||
| 工程参考 | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
|
||||
| 自动组合（9因子评分，14种策略） | `docs/routing/AUTO-COMBO.md` |
|
||||
| 弹性（3种机制） | `docs/architecture/RESILIENCE_GUIDE.md` |
|
||||
| 推理重放 | `docs/routing/REASONING_REPLAY.md` |
|
||||
| 技能框架 | `docs/frameworks/SKILLS.md` |
|
||||
| 内存系统（FTS5 + Qdrant） | `docs/frameworks/MEMORY.md` |
|
||||
| 云代理 | `docs/frameworks/CLOUD_AGENT.md` |
|
||||
| 保护措施（PII / 注入 / 视觉） | `docs/security/GUARDRAILS.md` |
|
||||
| 公共上游凭证（Gemini等） | `docs/security/PUBLIC_CREDS.md` |
|
||||
| 错误信息清理 | `docs/security/ERROR_SANITIZATION.md` |
|
||||
| 评估 | `docs/frameworks/EVALS.md` |
|
||||
| 合规 / 审计 | `docs/security/COMPLIANCE.md` |
|
||||
| Webhooks | `docs/frameworks/WEBHOOKS.md` |
|
||||
| 授权管道 | `docs/architecture/AUTHZ_GUIDE.md` |
|
||||
| 隐身（TLS / 指纹） | `docs/security/STEALTH_GUIDE.md` |
|
||||
| 代理协议（A2A / ACP / 云） | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |
|
||||
| MCP 服务器 | `docs/frameworks/MCP-SERVER.md` |
|
||||
| A2A 服务器 | `docs/frameworks/A2A-SERVER.md` |
|
||||
| API 参考 + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
|
||||
| 提供者目录（自动生成） | `docs/reference/PROVIDER_REFERENCE.md` |
|
||||
| 发布流程 | `docs/ops/RELEASE_CHECKLIST.md` |
|
||||
| 领域 | 文档 |
|
||||
| --------------------------------------- | -------------------------------------------------------- |
|
||||
| 仓库导航 | `docs/architecture/REPOSITORY_MAP.md` |
|
||||
| 架构 | `docs/architecture/ARCHITECTURE.md` |
|
||||
| 工程参考 | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
|
||||
| Auto-Combo（12 因子评分，17 种策略） | `docs/routing/AUTO-COMBO.md` |
|
||||
| 容灾（3 种机制） | `docs/architecture/RESILIENCE_GUIDE.md` |
|
||||
| 推理重播 | `docs/routing/REASONING_REPLAY.md` |
|
||||
| 技能框架 | `docs/frameworks/SKILLS.md` |
|
||||
| 记忆系统（FTS5 + Qdrant） | `docs/frameworks/MEMORY.md` |
|
||||
| 云代理 | `docs/frameworks/CLOUD_AGENT.md` |
|
||||
| 安全护栏（PII / 注入 / 视觉） | `docs/security/GUARDRAILS.md` |
|
||||
| 公开上游凭据（Gemini 等） | `docs/security/PUBLIC_CREDS.md` |
|
||||
| 错误消息脱敏 | `docs/security/ERROR_SANITIZATION.md` |
|
||||
| 评估 | `docs/frameworks/EVALS.md` |
|
||||
| 合规 / 审计 | `docs/security/COMPLIANCE.md` |
|
||||
| Webhook | `docs/frameworks/WEBHOOKS.md` |
|
||||
| 授权管线 | `docs/architecture/AUTHZ_GUIDE.md` |
|
||||
| 隐身（TLS / 指纹） | `docs/security/STEALTH_GUIDE.md` |
|
||||
| 代理协议（A2A / ACP / Cloud） | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |
|
||||
| MCP 服务器 | `docs/frameworks/MCP-SERVER.md` |
|
||||
| A2A 服务器 | `docs/frameworks/A2A-SERVER.md` |
|
||||
| API 参考 + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` |
|
||||
| 服务商目录（自动生成） | `docs/reference/PROVIDER_REFERENCE.md` |
|
||||
| 发布流程 | `docs/ops/RELEASE_CHECKLIST.md` |
|
||||
| 嵌入式服务 | `docs/frameworks/EMBEDDED-SERVICES.md` |
|
||||
| 质量门禁（约 48 个脚本，允许列表策略） | `docs/architecture/QUALITY_GATES.md` |
|
||||
|
||||
---
|
||||
|
||||
## 测试
|
||||
|
||||
| 内容 | 命令 |
|
||||
| ----------------------- | --------------------------------------------------------- |
|
||||
| 单元测试 | `npm run test:unit` |
|
||||
| 单个文件 | `node --import tsx/esm --test tests/unit/file.test.ts` |
|
||||
| Vitest (MCP, autoCombo) | `npm run test:vitest` |
|
||||
| E2E (Playwright) | `npm run test:e2e` |
|
||||
| 协议 E2E (MCP+A2A) | `npm run test:protocols:e2e` |
|
||||
| 生态系统 | `npm run test:ecosystem` |
|
||||
| 覆盖门限 | `npm run test:coverage` (75/75/75/70 — 语句/行/函数/分支) |
|
||||
| 覆盖报告 | `npm run coverage:report` |
|
||||
| 类型 | 命令 |
|
||||
| ----------------------- | ---------------------------------------------------------------------------- |
|
||||
| 单元测试 | `npm run test:unit` |
|
||||
| 单个文件 | `node --import tsx/esm --test tests/unit/file.test.ts` |
|
||||
| Vitest（MCP, autoCombo）| `npm run test:vitest` |
|
||||
| E2E（Playwright） | `npm run test:e2e` |
|
||||
| 协议 E2E（MCP+A2A） | `npm run test:protocols:e2e` |
|
||||
| 生态兼容 | `npm run test:ecosystem` |
|
||||
| 覆盖率门禁 | `npm run test:coverage`（60/60/60/60 — 语句/行/函数/分支） |
|
||||
| 覆盖率报告 | `npm run coverage:report` |
|
||||
|
||||
**PR 规则**：如果您更改了 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码，您必须在同一 PR 中包含或更新测试。
|
||||
**PR 规则**：如果你修改了 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码，必须在同一个 PR 中包含或更新测试。
|
||||
|
||||
**测试层级偏好**：单元测试优先 → 集成测试（多模块或数据库状态） → E2E（仅限 UI/工作流）。在修复之前或同时将错误重现编码为自动化测试。
|
||||
**测试层级偏好**：单元测试优先 → 集成测试（多模块或数据库状态）→ E2E（仅 UI/工作流）。在修复 bug 之前或同时，将 bug 复现编码为自动化测试。
|
||||
|
||||
**Copilot 覆盖政策**：当 PR 更改生产代码且覆盖率低于 75%（语句/行/函数）或 70%（分支）时，不仅仅报告 — 添加或更新测试，重新运行覆盖门限，然后请求确认。在 PR 报告中包含运行的命令、已更改的测试文件和最终覆盖结果。
|
||||
**两个测试运行器都必须通过**：`npm run test:unit`（Node 原生 — 大部分测试）和 `npm run test:vitest`（MCP 服务器、autoCombo、缓存）覆盖**不重叠的文件**。两者均在 CI 中连接（jobs `test-unit` 和 `test-vitest`），合并前必须都通过。一个只有单一套件通过的 PR 可能悄无声息地引入有问题的 MCP 工具或路由回退。
|
||||
|
||||
**Bug 修复 / Issue 分类协议（硬规则 #18）**：每个针对已报告 Issue 的修复必须通过以下之一验证 — 无例外：
|
||||
|
||||
1. **TDD（首选）** — 编写复现 bug 的失败测试 → 修复 → 确认测试通过。该测试成为永久回归守卫。只修改测试能证明需要修改的文件，不多改。
|
||||
2. **真实环境测试（当 TDD 不可行时）** — 部署到生产 VPS (`root@192.168.0.15`)，执行有文档记录的真实测试。在 PR 描述中记录确切的命令和结果。适用于：OAuth 上游流程、Cloudflare/WS 上游行为、仅 UI 回退、硬件相关行为。
|
||||
3. "本地跑通但未写测试"不算数。没有测试或 VPS 验证记录的修复不算修复 — 只是猜测。
|
||||
|
||||
为什么这一点很重要：修复 bug A 的同时引入 bug B 比不修复更糟。TDD/VPS 门禁强制控制变更范围 — 你只改动失败测试证明有问题的地方。曾经见效的案例：#3090 (claude-web 403)、#3113 (WS HTTP fallback)、#3052 (heap-guard auto-calibration)。
|
||||
|
||||
**Copilot 覆盖率策略**：当 PR 修改了生产代码且覆盖率低于 60%（语句/行/函数/分支）时，不要只是报告 — 请添加或更新测试，重新运行覆盖率门禁，然后请求确认。在 PR 报告中包含运行的命令、修改的测试文件和最终覆盖率结果。
|
||||
|
||||
---
|
||||
|
||||
## 规划与调研产物（superpowers、deep-research）
|
||||
|
||||
`_tasks/` 是一个**独立的隔离 git 仓库**，被主仓库的 `.gitignore` 忽略（`.gitignore` → `_tasks/`）。它是工作产物的规范存放地 — 计划、方案/设计、调研、交接 — 让它们**在自己的仓库中享受版本控制**，而不是污染主 OmniRoute 树。
|
||||
|
||||
**硬规则 — 绝不要将 superpowers / 规划 / 调研的输出写入 `docs/` 或仓库根目录。** superpowers 技能附带的默认值指向 `docs/…`（`writing-plans` → `docs/superpowers/plans/`，`brainstorming` → `docs/superpowers/specs/`）。这些默认值**在此处被覆盖**。每当你在此项目中调用 superpowers（或任何计划/方案/调研生成器）时，改为保存到 `_tasks/`，使用相同的文件名约定：
|
||||
|
||||
| 产物（技能） | 默认（不要用） | 保存到这里 |
|
||||
| --------------------------------- | ------------------------- | -------------------------------------------------------------- |
|
||||
| 计划 (`writing-plans`) | `docs/superpowers/plans/` | `_tasks/superpowers/plans/YYYY-MM-DD-<feature>.md` |
|
||||
| 方案 / 设计 (`brainstorming`) | `docs/superpowers/specs/` | `_tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md` |
|
||||
| 调研 (`deep-research`, 临时) | `docs/research/` | `_tasks/research/…` |
|
||||
| 交接 (`/handoff`) | — | `_tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/` |
|
||||
|
||||
当 superpowers 技能通告一个路径如 "saved to `docs/superpowers/plans/…`" 时，在写入前改写为 `_tasks/…` 等效路径。在 `_tasks/` 仓库内部提交这些产物 (`git -C _tasks …`)，绝不在主仓库中提交。
|
||||
|
||||
## Git 工作流
|
||||
|
||||
```bash
|
||||
# 永远不要直接提交到 main
|
||||
# 绝不要直接提交到 main
|
||||
git checkout -b feat/your-feature
|
||||
git commit -m "feat: 描述您的更改"
|
||||
git commit -m "feat: describe your change"
|
||||
git push -u origin feat/your-feature
|
||||
```
|
||||
|
||||
**分支前缀**：`feat/`、`fix/`、`refactor/`、`docs/`、`test/`、`chore/`
|
||||
|
||||
**提交格式**（传统提交）：`feat(db): 添加电路断路器` — 范围：`db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`
|
||||
**Commit 格式**（约定式提交）：`feat(db): add circuit breaker` — 作用域：`db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`
|
||||
|
||||
**Husky 钩子**：
|
||||
|
||||
- **pre-commit**：lint-staged + `check-docs-sync` + `check:any-budget:t11`
|
||||
- **pre-push**：`npm run test:unit`
|
||||
- **pre-push**：快速确定性门禁（`check:any-budget:t11` + `check:tracked-artifacts`）；故意排除 `test:unit`（太慢 — 由 CI `test-unit` job 覆盖）。于 2026-06-13 激活（质量门禁 Fase 6A.12）。
|
||||
|
||||
### Worktree 隔离（每次开发任务必做）
|
||||
|
||||
多个会话/代理并行操作此仓库。主工作区是**共享的**，因此在其上进行 `git checkout`/分支切换会静默丢弃另一个会话的未提交工作，并将在运行中的任何其他内容从分支上拉走（事故：2026-06-05、2026-06-13）。
|
||||
|
||||
**规则：绝不在共享的主工作区上进行开发。每个任务有其自己的专属分支的独立 git worktree，且必须在创建之前与运维人员确认基础分支。**
|
||||
|
||||
1. **先问 — 从哪个基础分支？** 在创建任何内容之前，通过 `AskUserQuestion` 询问运维人员（除非他们已经告诉你了）新 worktree/分支应该从哪个分支切出。不要假设 `main` 或"我现在在哪个分支上" — 通常是活跃的 `release/vX.Y.Z`，但也可能是其他 feature/release 分支。需要明确获取基础分支。
|
||||
2. **基于该基础分支创建隔离的 worktree + 分支**（绝不复用主工作区）。
|
||||
**🔴 强制路径：每个 worktree 必须位于 `.claude/worktrees/` 下 — 且不得放在任何其他位置。**
|
||||
这是唯一规范的位置（与原生 `EnterWorktree` 工具使用的目录相同）。该目录被 gitignore，也在 `tsconfig.json` / `.dockerignore` 排除列表中，因此 worktree 绝不会泄漏到构建范围内。**绝不**使用 `.worktrees/`、仓库根目录或任何其他路径 — 位于 `.claude/worktrees/` 之外的 worktree (a) 逃脱了构建范围的排除，会毒化 `next build`（`tsconfig` 的 `include: **/*` 将 glob 扩展约 70 倍 → OOM；事故 2026-06-25），且 (b) 将 worktree 分散在两个目录中。
|
||||
|
||||
```bash
|
||||
BASE_BRANCH="release/vX.Y.Z" # ← 运维人员在步骤 1 中确认的分支
|
||||
TASK="feat/your-feature" # feat/ fix/ refactor/ docs/ test/ chore/
|
||||
git fetch origin "$BASE_BRANCH"
|
||||
git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH"
|
||||
cd ".claude/worktrees/${TASK##*/}"
|
||||
# 从主工作区符号链接 node_modules，省去每个 worktree 的 npm install：
|
||||
ln -s "$(git -C <main_checkout> rev-parse --show-toplevel)/node_modules" node_modules
|
||||
```
|
||||
|
||||
在 Claude Code 中优先使用原生的 `EnterWorktree` 工具（它已经在 `.claude/worktrees/` 下创建 worktree）：先用上述命令创建 worktree，然后用其 `path` 调用 `EnterWorktree`。
|
||||
|
||||
3. **工作、提交、推送、发起 PR — 全部在 worktree 内部完成。** 绝不在另一个会话可能共享的 worktree 内 `git checkout` 不同分支。
|
||||
4. **完成后仅拆除你自己的** worktree + 分支，从主工作区执行：
|
||||
`git worktree remove .claude/worktrees/<dir>` 然后 `git branch -D <task>`。绝不要通配删除 `fix/*`/`feat/*` — 其他会话保留自己的分支；只按名称删除你创建的分支。
|
||||
5. **绝不要触碰其他会话的 worktree、分支或未提交的更改。** 如果 `git worktree list` 显示了你未创建的 worktree，请不要动它们。每次会话结束时，将主工作区恢复到开始时所在的分支（活跃的 `release/vX.Y.Z`，绝不是 `main`）。
|
||||
|
||||
---
|
||||
|
||||
## 环境
|
||||
|
||||
- **运行时**：Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
|
||||
- **TypeScript**：5.9+，目标 ES2022，模块 esnext，解析器 bundler
|
||||
- **运行时**：Node.js ≥22.0.0 <23 || ≥24.0.0 <27，ES Modules
|
||||
- **TypeScript**：6.0+，目标 ES2022，模块 esnext，解析策略 bundler
|
||||
- **路径别名**：`@/*` → `src/`，`@omniroute/open-sse` → `open-sse/`，`@omniroute/open-sse/*` → `open-sse/*`
|
||||
- **默认端口**：20128（API + 仪表板在同一端口）
|
||||
- **数据目录**：`DATA_DIR` 环境变量，默认为 `~/.omniroute/`
|
||||
- **默认端口**：20128（API + 仪表盘在同一端口）
|
||||
- **数据目录**：`DATA_DIR` 环境变量，默认 `~/.omniroute/`
|
||||
- **关键环境变量**：`PORT`、`JWT_SECRET`、`API_KEY_SECRET`、`INITIAL_PASSWORD`、`REQUIRE_API_KEY`、`APP_LOG_LEVEL`
|
||||
- 设置：`cp .env.example .env` 然后生成 `JWT_SECRET` (`openssl rand -base64 48`) 和 `API_KEY_SECRET` (`openssl rand -hex 32`)
|
||||
- 设置：`cp .env.example .env`，然后生成 `JWT_SECRET`（`openssl rand -base64 48`）和 `API_KEY_SECRET`（`openssl rand -hex 32`）
|
||||
|
||||
---
|
||||
|
||||
## 硬性规则
|
||||
## 质量门禁与棘轮
|
||||
|
||||
1. 永远不要提交秘密或凭据
|
||||
2. 永远不要在 `localDb.ts` 中添加逻辑
|
||||
3. 永远不要使用 `eval()` / `new Function()` / 隐式 eval
|
||||
4. 永远不要直接提交到 `main`
|
||||
5. 永远不要在路由中编写原始 SQL — 使用 `src/lib/db/` 模块
|
||||
6. 永远不要在 SSE 流中静默吞噬错误
|
||||
7. 始终使用 Zod 模式验证输入
|
||||
8. 更改生产代码时始终包含测试
|
||||
9. 覆盖率必须保持在 ≥75%（语句、行、函数）/ ≥70%（分支）。当前测量：~82%。
|
||||
10. 在没有明确操作员批准的情况下，永远不要绕过 Husky 钩子（`--no-verify`，`--no-gpg-sign`）。
|
||||
11. 永远不要将公共上游 OAuth client_id/secret 或 Firebase Web 密钥作为字符串文字嵌入 — 始终通过 `resolvePublicCred()` 处理（`open-sse/utils/publicCreds.ts`）。参见 `docs/security/PUBLIC_CREDS.md`。
|
||||
12. 永远不要在 HTTP / SSE / 执行器响应中返回原始 `err.stack` / `err.message` — 始终通过 `buildErrorBody()` 或 `sanitizeErrorMessage()` 路由（`open-sse/utils/error.ts`）。参见 `docs/security/ERROR_SANITIZATION.md`。
|
||||
13. 永远不要将外部路径或运行时值字符串插值到传递给 `exec()`/`spawn()` 的 shell 脚本中 — 应通过 `env` 选项传递。参考：`src/mitm/cert/install.ts::updateNssDatabases`。
|
||||
14. 永远不要在没有 (a) 首先检查上述模式文档以查看帮助程序是否适用，以及 (b) 在驳回评论中记录技术理由的情况下驳回 CodeQL / Secret-Scanning 警报。先例：在已经通过 `sanitizeErrorMessage()` 路由的调用站点上引发的 `js/stack-trace-exposure` 是已知的 CodeQL 限制（自定义清理程序未被识别） — 驳回为 `false positive`，引用 `docs/security/ERROR_SANITIZATION.md`。
|
||||
15. 永远不要暴露生成子进程的路由（`/api/mcp/`、`/api/cli-tools/runtime/`），而不在 `src/server/authz/routeGuard.ts` 中进行 `isLocalOnlyPath()` 分类。回环强制执行在任何身份验证检查之前无条件发生 — 通过隧道泄露的 JWT 不能触发进程生成。参见 `docs/security/ROUTE_GUARD_TIERS.md`。
|
||||
16. 切勿在提交消息中包含将 AI 助手、LLM 或自动化账户作为作者的 `Co-Authored-By` 尾部（例如包含 "Claude"、"GPT"、"Copilot"、"Bot" 的名称；`anthropic.com` / `openai.com` / 机器人拥有的 `noreply.github.com` 地址上的电子邮件）。这类尾部会将 commit 归属路由到 GitHub 上的机器人账户，从而在 PR 历史中隐藏真正的作者 (`diegosouzapw`)。人类协作者——包括 upstream PR 作者和被移植到 OmniRoute 的 issue 报告者——可以并且应该使用标准的 `Co-authored-by: Name <email>` 尾部进行署名；upstream-port 工作流（`/port-upstream-features`、`/port-upstream-issues`）依赖于此。
|
||||
OmniRoute 有**约 48 个质量门禁脚本**（`scripts/check/` + `scripts/quality/`），分布在
|
||||
`.github/workflows/ci.yml` 的 **9 个门禁执行 job**（`lint`、`quality-gate`、
|
||||
`quality-extended`、`docs-sync-strict`、`i18n-ui-coverage`、`i18n`、`pr-test-policy`、
|
||||
`test-vitest`、`sonarqube`）中，外加 `quality.yml` 快速门禁 job（PR→`release/**`）和
|
||||
3 个夜间工作流（`nightly-property`、`nightly-resilience`、`nightly-llm-security`；
|
||||
`nightly-mutation` 合并后加入）。完整清单、按 job 分解和操作流程见 [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)。
|
||||
|
||||
**快速参考：**
|
||||
|
||||
- `lint` + `docs-sync-strict` job 中的门禁：通过/失败策略门禁 —
|
||||
修复违规，或在带有理由注释 + 跟踪 Issue 的情况下添加到允许列表。
|
||||
- `quality-gate` job 中的门禁：棘轮 — 指标（ESLint 警告、代码覆盖率、重复率、复杂度）不得相对于 `quality-baseline.json` 回退。当某个指标确实改善时，通过 `npm run quality:ratchet -- --update` 更新。
|
||||
- Job `test-vitest` 运行 `npm run test:vitest`（MCP 工具、autoCombo、缓存）— 阻断性。
|
||||
`test:vitest:ui` 在 UI 组件测试分类完成前为咨询性。
|
||||
|
||||
**允许列表策略（简短版）：** 修复原因；仅在无法在同一 PR 中修复已有违规时使用允许列表。添加带理由和 Issue 编号的注释。陈旧的允许列表条目（抑制不再存在的违规）将被 Fase 6A.3 添加的陈旧检测捕获。
|
||||
|
||||
---
|
||||
|
||||
## 硬规则
|
||||
|
||||
1. 绝不要提交密钥或凭据
|
||||
2. 绝不要向 `localDb.ts` 添加逻辑
|
||||
3. 绝不要使用 `eval()` / `new Function()` / 隐式 eval
|
||||
4. 绝不要直接提交到 `main`
|
||||
5. 绝不要在路由中编写原始 SQL — 使用 `src/lib/db/` 模块
|
||||
6. 绝不要在 SSE 流中静默吞掉错误
|
||||
7. 始终用 Zod Schema 校验输入
|
||||
8. 修改生产代码时始终包含测试
|
||||
9. 覆盖率不得回退到 `quality-baseline.json` 中冻结的基线以下（棘轮）；绝对下限为 60%（语句/行/函数/分支）。仅当覆盖率确实改善时通过 `npm run quality:ratchet -- --update` 更新基线。见 `docs/architecture/QUALITY_GATES.md`。
|
||||
10. 绝不要在未经运维人员明确批准的情况下绕过 Husky 钩子（`--no-verify`、`--no-gpg-sign`）。
|
||||
11. 绝不要将公开的上游 OAuth client_id/secret 或 Firebase Web 密钥作为字符串字面量嵌入 — 始终通过 `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`)。见 `docs/security/PUBLIC_CREDS.md`。
|
||||
12. 绝不要在 HTTP / SSE / 执行器响应中返回原始的 `err.stack` / `err.message` — 始终通过 `buildErrorBody()` 或 `sanitizeErrorMessage()` (`open-sse/utils/error.ts`)。见 `docs/security/ERROR_SANITIZATION.md`。
|
||||
13. 绝不要将外部路径或运行时值字符串插值到传递给 `exec()`/`spawn()` 的 Shell 脚本中 — 应通过 `env` 选项传递。参考：`src/mitm/cert/install.ts::updateNssDatabases`。
|
||||
14. 绝不要在不检查 (a) 上述模式文档是否适用辅助工具，以及 (b) 在驳回注释中记录技术理由的情况下，驳回 CodeQL / Secret-Scanning 告警。先例：`js/stack-trace-exposure` 对已通过 `sanitizeErrorMessage()` 传递的调用点报告 — 这是已知的 CodeQL 局限性（无法识别自定义脱敏器）— 以 `false positive` 驳回，引用 `docs/security/ERROR_SANITIZATION.md`。
|
||||
15. 绝不要在未在 `src/server/authz/routeGuard.ts` 中进行 `isLocalOnlyPath()` 分类的情况下暴露会派生子进程的路由（`/api/mcp/`、`/api/cli-tools/runtime/`）。loopback 强制在所有鉴权检查之前无条件执行 — 通过隧道泄露的 JWT 无法触发派生子进程。见 `docs/security/ROUTE_GUARD_TIERS.md`。
|
||||
16. **绝不在任何 commit/PR 元数据中标注或宣传 AI 助手、LLM 或自动化账户。** 两种被禁止的形式，两者等效 — 它们将署名归给机器人账户（或宣传 AI 作者身份），隐藏真实作者 (`diegosouzapw`)：**(a)** 命名 AI/机器人的 `Co-Authored-By` 尾注（例如包含 "Claude"、"GPT"、"Copilot"、"Bot" 的名称；使用 `anthropic.com` / `openai.com` / 机器人拥有的 `noreply.github.com` 地址的电子邮件）；**(b)** commit 消息、PR 标题/正文或 CHANGELOG 中任何位置的 AI 生成页脚或描述 — 例如 `🤖 Generated with [Claude Code]`、"Generated with Claude Code"、"Made with <AI tool>"，或任何 `Co-authored-by: Claude/GPT/Copilot` 行。此规则**覆盖任何自动追加此类页脚的框架、模板或工具默认行为**（例如 Claude Code PR 正文/commit 的默认页脚）— 在推送前将其剥离；不要让它进入 commit、PR 或 CHANGELOG。人类协作者 — 包括上游 PR 作者和被移植到 OmniRoute 的 Issue 报告者 — 可以且应该使用标准的 `Co-authored-by: Name <email>` 尾注署名；上游移植工作流（`/port-upstream-features`、`/port-upstream-issues`）依赖于此。
|
||||
17. 绝不要在未在 `src/server/authz/routeGuard.ts` 中进行 `isLocalOnlyPath()` 分类的情况下暴露 `/api/services/` 或 `/dashboard/providers/services/*/embed/` 下的路由。这些路由可以派生子进程（`npm install`、`node`）。loopback 强制在所有鉴权检查之前无条件执行 — 通过隧道泄露的 JWT 无法触发派生子进程。见 `docs/security/ROUTE_GUARD_TIERS.md`。
|
||||
18. 每个 Bug 修复必须在交付前验证：一个失败后通过的单元/集成测试（TDD）或一份有文档记录的生产 VPS (192.168.0.15) 真实测试。两者都缺失的修复不会被合并。见测试 → "Bug 修复 / Issue 分类协议"了解完整决策树。
|
||||
19. 绝不在共享的主工作区上进行开发。每次开发任务运行在属于自己的专属分支的独立 git worktree 中，且必须在创建 worktree/分支之前与运维人员确认基础分支（例如通过 `AskUserQuestion`）— 绝不要假设 `main` 或当前检出的分支。在共享工作区中的 `git checkout` 会静默销毁其他会话的未提交工作。只拆除你创建的 worktree/分支（按名称，绝不使用 `fix/*`/`feat/*` 通配符），不要动其他会话的 worktree，结束时回到开始所在的分支（活跃的 `release/vX.Y.Z`，绝不是 `main`）。见 Git 工作流 → "Worktree 隔离"。
|
||||
20. PII 脱敏/净化是**主动选择加入 — 绝不要默认开启**。OmniRoute 为自托管/本地 LLM 做代理，运维人员拥有数据所有权，因此默认修改请求/响应载荷会悄无声息地损坏合法流量。两个会修改数据的 PII 功能标志**必须**在 `src/shared/constants/featureFlagDefinitions.ts` 中保持 `defaultValue: "false"`：`PII_REDACTION_ENABLED`（请求侧）和 `PII_RESPONSE_SANITIZATION`（响应 + 流式）。三个应用位置 — `src/lib/guardrails/piiMasker.ts`（请求安全护栏）、`src/lib/piiSanitizer.ts`（响应）、`src/lib/streamingPiiTransform.ts`（SSE）— 均受这些标志门控；两者均关闭时，`pii-masker` 安全护栏仍会运行但不会修改载荷（数据不变地通过）。将任何一个默认值翻转为 `"true"` 需要运维人员的明确批准。回归守卫是 `tests/unit/pii-opt-in-default.test.ts`（断言两个定义默认值 + 行为透传）。选择加入是每位运维人员通过环境变量或设置/DB 覆盖 (`src/lib/db/featureFlags.ts`) 进行，绝不是静默的默认行为。见 `docs/security/GUARDRAILS.md`。
|
||||
21. **发布冻结 — 当 `/generate-release` 运行时，发布分支冻结，不接受 campaign 合并。** `/generate-release` 在开始协调时（Phase 0a）创建一个标记为 `release-freeze` 的标记 Issue，在 release PR 被 squash-merge 到 `main` 后关闭。在将**任何** PR 合并到活跃的 `release/vX.Y.Z` 分支之前，每个 campaign 工作流（`/review-issues`、`/review-prs`、`/implement-features`、`/green-prs`、`/port-upstream-*`）**必须**检查 `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — 如果冻结激活，**暂停合并**（保留 PR 处于 ready 和 open 状态；不要合并到 release 分支），告知运维人员，待冻结解除后再继续。这是一个**协调信号，而非权限锁**：release captain 和 campaign 会话共享 `diegosouzapw` 身份，因此 GitHub 分支保护锁无法区分二者 — 只有这个被遵循的标记能防止 v3.8.40/v3.8.41 中强制进行完整 CHANGELOG 重新协调的中间 release 提交冲突（并行 campaign 在运行过程中将 `release/vX.Y.Z` 推进了 34 个提交）。release captain 自己的协调/周期打开推送是豁免的 — 那些本身就是 release。必须在冻结期间落地的修复（例如 homologation 发现的问题）遵循合并后只读规则：先通过 `fix/release-vX.Y.Z-*` 落地到 `main`。
|
||||
|
||||
---
|
||||
|
||||
## PII 与流脱敏经验教训
|
||||
|
||||
### 1. 正则安全性（ReDoS）
|
||||
|
||||
所有匹配变长字符串的正则模式（例如 IPv6 地址、信用卡号）必须使用严格有界、不重叠的序列（例如用有界范围 `{1,7}` 限制出现次数），以防止在处理不受信任的输入时发生灾难性回溯。
|
||||
|
||||
### 2. SSE 快照处理
|
||||
|
||||
在解析流式 LLM 响应（例如 Responses API）时，检查数据块是否代表最终快照（`done` 或 `completed` 事件）。快照文本必须作为独立字符串直接脱敏处理（绕过滚动增量缓冲区），以防止在流末尾出现文本重复。
|
||||
|
||||
### 3. 测试中的数据库句柄
|
||||
|
||||
确保任何触发数据库迁移或建立 SQLite 连接的单元测试都调用 `resetDbInstance()` 并在 `test.after(...)` 钩子中正确清理和关闭所有数据库句柄。未能释放数据库连接句柄将导致 Node 的原生测试运行器无限挂起。
|
||||
|
||||
@@ -4,129 +4,82 @@
|
||||
|
||||
---
|
||||
|
||||
## Our Pledge
|
||||
## 我们的承诺
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, religion, or sexual identity
|
||||
and orientation.
|
||||
我们作为成员、贡献者和领导者，承诺让社区参与对每个人来说都是一种无骚扰的体验，无论年龄、体型、可见或不可见的残疾、民族、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、个人外貌、种族、宗教或性取向如何。
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
我们承诺以有助于营造开放、热情、多元、包容和健康的社区的方式行事和互动。
|
||||
|
||||
## Our Standards
|
||||
## 我们的标准
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
有助于为我们的社区营造积极环境的行为示例包括：
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the
|
||||
overall community
|
||||
- 对他人表现出同理心和善意
|
||||
- 尊重不同的意见、观点和经历
|
||||
- 给出并优雅地接受建设性反馈
|
||||
- 承担责任，向因我们的错误而受到影响的人道歉，并从中吸取经验
|
||||
- 关注不仅对我们个人最有利，也对整个社区最有利的事情
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
不可接受的行为示例包括：
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or
|
||||
advances of any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email
|
||||
address, without their explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
- 使用带有性暗示的语言或图像，以及任何形式的性关注或性挑逗
|
||||
- 挑衅、侮辱或贬损性评论，以及人身或政治攻击
|
||||
- 公开或私下骚扰
|
||||
- 未经明确许可，发布他人的私人信息，例如物理地址或电子邮件地址
|
||||
- 在专业环境中可被合理视为不当的其他行为
|
||||
|
||||
## Enforcement Responsibilities
|
||||
## 执行责任
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of
|
||||
acceptable behavior and will take appropriate and fair corrective action in
|
||||
response to any behavior that they deem inappropriate, threatening, offensive,
|
||||
or harmful.
|
||||
社区领导者负责明确和执行我们的可接受行为标准，并将对任何被视为不当、威胁、冒犯或有害的行为采取适当且公正的纠正措施。
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
社区领导者有权并有责任删除、编辑或拒绝与本行为准则不符的评论、提交、代码、Wiki 编辑、议题和其他贡献，并将在适当时传达审核决定的理由。
|
||||
|
||||
## Scope
|
||||
## 适用范围
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when
|
||||
an individual is officially representing the community in public spaces.
|
||||
Examples of representing our community include using an official e-mail address,
|
||||
posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event.
|
||||
本行为准则适用于所有社区空间，也适用于个人在公共空间正式代表社区的情况。代表我们社区的行为示例包括使用官方电子邮件地址、通过官方社交媒体账号发布信息，或作为指定代表在线上或线下活动中行事。
|
||||
|
||||
## Enforcement
|
||||
## 执行
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement at
|
||||
.
|
||||
All complaints will be reviewed and investigated promptly and fairly.
|
||||
可通过以下方式向负责执行的社区领导者举报辱骂、骚扰或其他不可接受的行为：在 <https://github.com/diegosouzapw/OmniRoute/security/advisories/new> 创建私人安全建议，或发送电子邮件至维护者 diegosouza.pw@outlook.com。
|
||||
对于安全敏感事件，请参阅 [`SECURITY.md`](SECURITY.md)。
|
||||
所有投诉将得到及时和公正的审查和调查。
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
reporter of any incident.
|
||||
所有社区领导者都有义务尊重事件举报者的隐私和安全。
|
||||
|
||||
## Enforcement Guidelines
|
||||
## 执行准则
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining
|
||||
the consequences for any action they deem in violation of this Code of Conduct:
|
||||
社区领导者在确定其认为违反本行为准则的任何行为的后果时，将遵循以下社区影响准则：
|
||||
|
||||
### 1. Correction
|
||||
### 1. 纠正
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed
|
||||
unprofessional or unwelcome in the community.
|
||||
**社区影响**：使用不当语言或其他被视为不专业或不受社区欢迎的行为。
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing
|
||||
clarity around the nature of the violation and an explanation of why the
|
||||
behavior was inappropriate. A public apology may be requested.
|
||||
**后果**：社区领导者发出私下的书面警告，明确说明违规的性质以及行为为何不当。可能会要求公开道歉。
|
||||
|
||||
### 2. Warning
|
||||
### 2. 警告
|
||||
|
||||
**Community Impact**: A violation through a single incident or series
|
||||
of actions.
|
||||
**社区影响**：通过单次事件或一连串行为造成的违规。
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No
|
||||
interaction with the people involved, including unsolicited interaction with
|
||||
those enforcing the Code of Conduct, for a specified period of time. This
|
||||
includes avoiding interactions in community spaces as well as external channels
|
||||
like social media. Violating these terms may lead to a temporary or
|
||||
permanent ban.
|
||||
**后果**：发出带有持续行为后果的警告。在指定时间内不得与相关人员互动，包括不得主动与执行本行为准则的人员互动。这包括避免在社区空间以及社交媒体等外部渠道进行互动。违反这些条款可能导致临时或永久封禁。
|
||||
|
||||
### 3. Temporary Ban
|
||||
### 3. 临时封禁
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including
|
||||
sustained inappropriate behavior.
|
||||
**社区影响**：严重违反社区标准，包括持续的不当行为。
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public
|
||||
communication with the community for a specified period of time. No public or
|
||||
private interaction with the people involved, including unsolicited interaction
|
||||
with those enforcing the Code of Conduct, is allowed during this period.
|
||||
Violating these terms may lead to a permanent ban.
|
||||
**后果**：在指定时间内禁止与社区进行任何类型的互动或公开交流。在此期间，不得与相关人员公开或私下互动，包括不得主动与执行本行为准则的人员互动。违反这些条款可能导致永久封禁。
|
||||
|
||||
### 4. Permanent Ban
|
||||
### 4. 永久封禁
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
**社区影响**：表现出违反社区标准的行为模式，包括持续的不当行为、骚扰个人，或对某类人群的侵犯或贬损。
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within
|
||||
the community.
|
||||
**后果**：永久禁止在社区内进行任何形式的公开互动。
|
||||
|
||||
## Attribution
|
||||
## 来源
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.0, available at
|
||||
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
|
||||
本行为准则改编自 [Contributor Covenant][homepage] 2.1 版，详见 https://www.contributor-covenant.org/version/2/1/code_of_conduct.html。
|
||||
|
||||
Community Impact Guidelines were inspired by [Mozilla's code of conduct
|
||||
enforcement ladder](https://github.com/mozilla/diversity).
|
||||
社区影响准则的灵感来自 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity)。
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at
|
||||
https://www.contributor-covenant.org/faq. Translations are available at
|
||||
https://www.contributor-covenant.org/translations.
|
||||
关于本行为准则的常见问题解答，请访问 https://www.contributor-covenant.org/faq。翻译版本可在 https://www.contributor-covenant.org/translations 获取。
|
||||
|
||||
@@ -4,19 +4,19 @@
|
||||
|
||||
---
|
||||
|
||||
Thank you for your interest in contributing! This guide covers everything you need to get started.
|
||||
感谢你对 OmniRoute 的关注！本文档将引导你从零开始参与项目贡献。
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
## 开发环境搭建
|
||||
|
||||
### Prerequisites
|
||||
### 前置条件
|
||||
|
||||
- **Node.js** >= 18 < 24 (recommended: 22 LTS)
|
||||
- **Node.js** `>=22.22.3 <23` 或 `>=24.0.0 <27`（推荐：24 LTS）
|
||||
- **npm** 10+
|
||||
- **Git**
|
||||
|
||||
### Clone & Install
|
||||
### 克隆与安装
|
||||
|
||||
```bash
|
||||
git clone https://github.com/diegosouzapw/OmniRoute.git
|
||||
@@ -24,288 +24,350 @@ cd OmniRoute
|
||||
npm install
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
### 环境变量
|
||||
|
||||
```bash
|
||||
# Create your .env from the template
|
||||
# 根据模板创建 .env 文件
|
||||
cp .env.example .env
|
||||
|
||||
# Generate required secrets
|
||||
# 生成必需的密钥
|
||||
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
|
||||
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
|
||||
```
|
||||
|
||||
Key variables for development:
|
||||
开发环境关键变量：
|
||||
|
||||
| Variable | Development Default | Description |
|
||||
| ---------------------- | ------------------------ | --------------------- |
|
||||
| `PORT` | `20128` | Server port |
|
||||
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend |
|
||||
| `JWT_SECRET` | (generate above) | JWT signing secret |
|
||||
| `INITIAL_PASSWORD` | `CHANGEME` | First login password |
|
||||
| `APP_LOG_LEVEL` | `info` | Log verbosity level |
|
||||
| 变量 | 开发环境默认值 | 说明 |
|
||||
| ------------------------ | ------------------------ | ------------------ |
|
||||
| `PORT` | `20128` | 服务器端口 |
|
||||
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | 前端 Base URL |
|
||||
| `JWT_SECRET` | （通过上方命令生成） | JWT 签名密钥 |
|
||||
| `INITIAL_PASSWORD` | `CHANGEME` | 首次登录密码 |
|
||||
| `APP_LOG_LEVEL` | `info` | 日志详细级别 |
|
||||
|
||||
### Dashboard Settings
|
||||
### 控制台设置
|
||||
|
||||
The dashboard provides UI toggles for features that can also be configured via environment variables:
|
||||
控制台为部分功能提供了界面开关，这些功能也可通过环境变量配置：
|
||||
|
||||
| Setting Location | Toggle | Description |
|
||||
| ------------------- | ------------------ | ------------------------------ |
|
||||
| Settings → Advanced | Debug Mode | Enable debug request logs (UI) |
|
||||
| Settings → General | Sidebar Visibility | Show/hide sidebar sections |
|
||||
| 设置位置 | 开关 | 说明 |
|
||||
| -------------- | ------------------ | ---------------------------- |
|
||||
| 设置 → 高级 | 调试模式 | 启用调试请求日志（界面端） |
|
||||
| 设置 → 常规 | 侧边栏可见性 | 显示/隐藏侧边栏分区 |
|
||||
|
||||
These settings are stored in the database and persist across restarts, overriding env var defaults when set.
|
||||
这些设置存储在数据库中，重启后仍然有效，设置后会覆盖环境变量的默认值。
|
||||
|
||||
### Running Locally
|
||||
### 本地运行
|
||||
|
||||
```bash
|
||||
# Development mode (hot reload)
|
||||
# 开发模式（热重载）
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
# 生产构建
|
||||
npm run build # next build → .build/next/ 然后 assembleStandalone → dist/
|
||||
npm run start
|
||||
|
||||
# Common port configuration
|
||||
# 发布构建（清理重建 + HEAD 哨兵 — 部署必需）
|
||||
npm run build:release # rm -rf .build dist && build + 写入 dist/BUILD_SHA
|
||||
|
||||
# 常用端口配置
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
Default URLs:
|
||||
### 构建产物布局
|
||||
|
||||
- **Dashboard**: `http://localhost:20128/dashboard`
|
||||
- **API**: `http://localhost:20128/v1`
|
||||
| 目录 | 内容 | 版本追踪 |
|
||||
| --------- | ---------------------------------------------------------------------------- | -------- |
|
||||
| `src/` | 应用源码（TypeScript / TSX） | 是 |
|
||||
| `.build/` | 中间产物 — `next build` 输出（已 gitignore，`distDir = .build/next`） | 否 |
|
||||
| `dist/` | 可交付的打包产物 — 由 `assembleStandalone` 组装（已 gitignore） | 否 |
|
||||
|
||||
构建流水线为单次执行：
|
||||
|
||||
```
|
||||
npm run build
|
||||
└─ next build → .build/next/standalone （Next.js 输出）
|
||||
└─ assembleStandalone() （复制 standalone + static + public + 本地原生资产）
|
||||
└─ 输出: dist/ （server.js, .next/static/, public/, node_modules/）
|
||||
```
|
||||
|
||||
`npm run build:release` 会额外清理上述两个目录，并写入
|
||||
`dist/BUILD_SHA`（= `git rev-parse --short HEAD`）作为部署完整性哨兵。
|
||||
|
||||
> **VPS 部署说明：** 远程镜像目录 `/usr/lib/node_modules/omniroute/app/`
|
||||
> 保持不变。部署脚本会将 `dist/` 的内容 rsync 到该目录中。
|
||||
> 仅仓库内的构建输出路径发生了变动（`app/` → `dist/`）。
|
||||
|
||||
默认地址：
|
||||
|
||||
- **控制台**：`http://localhost:20128/dashboard`
|
||||
- **API**：`http://localhost:20128/v1`
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
## Git 工作流
|
||||
|
||||
> ⚠️ **NEVER commit directly to `main`.** Always use feature branches.
|
||||
> ⚠️ **切勿直接提交到 `main` 分支。** 始终使用功能分支。
|
||||
|
||||
```bash
|
||||
git checkout -b feat/your-feature-name
|
||||
# ... make changes ...
|
||||
git commit -m "feat: describe your change"
|
||||
# ... 进行修改 ...
|
||||
git commit -m "feat: 描述你的改动"
|
||||
git push -u origin feat/your-feature-name
|
||||
# Open a Pull Request on GitHub
|
||||
# 在 GitHub 上发起 Pull Request
|
||||
```
|
||||
|
||||
### Branch Naming
|
||||
### 分支命名
|
||||
|
||||
| Prefix | Purpose |
|
||||
| ----------- | ------------------------- |
|
||||
| `feat/` | New features |
|
||||
| `fix/` | Bug fixes |
|
||||
| `refactor/` | Code restructuring |
|
||||
| `docs/` | Documentation changes |
|
||||
| `test/` | Test additions/fixes |
|
||||
| `chore/` | Tooling, CI, dependencies |
|
||||
| 前缀 | 用途 |
|
||||
| ----------- | ---------------------- |
|
||||
| `feat/` | 新功能 |
|
||||
| `fix/` | Bug 修复 |
|
||||
| `refactor/` | 代码重构 |
|
||||
| `docs/` | 文档修改 |
|
||||
| `test/` | 测试新增/修复 |
|
||||
| `chore/` | 工具链、CI、依赖项 |
|
||||
|
||||
### Commit Messages
|
||||
### 提交信息
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||||
|
||||
```
|
||||
feat: add circuit breaker for provider calls
|
||||
fix: resolve JWT secret validation edge case
|
||||
docs: update SECURITY.md with PII protection
|
||||
test: add observability unit tests
|
||||
refactor(db): consolidate rate limit tables
|
||||
feat: 为服务商调用添加熔断器
|
||||
fix: 解决 JWT 密钥校验的边界情况
|
||||
docs: 更新 SECURITY.md 增加 PII 保护内容
|
||||
test: 添加可观测性单元测试
|
||||
refactor(db): 合并速率限制相关数据表
|
||||
```
|
||||
|
||||
Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.
|
||||
作用域（v3.8）：`db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`、`cloud-agent`、`guardrails`、`compression`、`auto-combo`、`resilience`、`providers`、`executors`、`translator`、`domain`、`authz`。
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
## 运行测试
|
||||
|
||||
```bash
|
||||
# All tests (unit + vitest + ecosystem + e2e)
|
||||
# 全部测试（unit + vitest + ecosystem + e2e）
|
||||
npm run test:all
|
||||
|
||||
# Single test file (Node.js native test runner — most tests use this)
|
||||
# 单个测试文件（Node.js 原生测试运行器 — 大多数测试使用此方式）
|
||||
node --import tsx/esm --test tests/unit/your-file.test.ts
|
||||
|
||||
# Vitest (MCP server, autoCombo, cache)
|
||||
# Vitest（MCP server、autoCombo、缓存）
|
||||
npm run test:vitest
|
||||
|
||||
# E2E tests (requires Playwright)
|
||||
# E2E 测试（需要 Playwright）
|
||||
npm run test:e2e
|
||||
|
||||
# Protocol clients E2E (MCP transports, A2A)
|
||||
# 协议客户端 E2E（MCP 传输、A2A）
|
||||
npm run test:protocols:e2e
|
||||
|
||||
# Ecosystem compatibility tests
|
||||
# 生态兼容性测试
|
||||
npm run test:ecosystem
|
||||
|
||||
# Coverage (60% min statements/lines/functions/branches)
|
||||
# 覆盖率关卡：60% 语句/行/函数/分支
|
||||
npm run test:coverage
|
||||
npm run coverage:report
|
||||
|
||||
# Lint + format check
|
||||
# 代码检查 + 格式检查
|
||||
npm run lint
|
||||
npm run check
|
||||
|
||||
# 关卡验证的线上 Combo 冒烟测试（需要 VPS 访问权限 + 真实服务商积分）
|
||||
# 会打到真实服务商 — 会产生少量费用。不在 CI 中运行。缺少关卡条件时优雅跳过。
|
||||
# 需要：ssh root@192.168.0.15 访问权限（从 VPS 拉取只读数据库快照）。
|
||||
RUN_COMBO_LIVE=1 npm run test:combo:live
|
||||
|
||||
# 第三阶段 VPS 线上冒烟 — 纯 Node ESM 脚本，直接打到线上 .15 服务器。
|
||||
# 需要：ssh root@192.168.0.15 访问权限（通过 SSH sqlite 创建/销毁 Combo）。
|
||||
# 会打到真实服务商（少量费用）。仅创建/删除 __live_test__* 开头的 Combo。不在 CI 中运行。
|
||||
# .15 上 REQUIRE_API_KEY=false 所以无需 API Key，但会遵循 COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY 设置。
|
||||
npm run test:combo:live:vps # 7 个 HTTP 场景（priority/round-robin/weighted/cost/fusion/auto + health）
|
||||
npm run test:combo:live:vps:failover # 额外增加跨服务商容灾切换场景（共 8 个）
|
||||
```
|
||||
|
||||
Coverage notes:
|
||||
覆盖率说明：
|
||||
|
||||
- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
|
||||
- Pull requests must keep the overall coverage gate at **60% or higher** for statements, lines, functions, and branches
|
||||
- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must add or update automated tests in the same PR
|
||||
- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
|
||||
- `npm run test:coverage:legacy` preserves the older metric for historical comparison
|
||||
- See `docs/ops/COVERAGE_PLAN.md` for the phased coverage improvement roadmap
|
||||
- `npm run test:coverage` 衡量主要单元测试套件的源码覆盖率，排除 `tests/**`，包含 `open-sse/**`
|
||||
- Pull Request 必须将覆盖率关口维持在 **60%+**（语句/行/函数/分支）
|
||||
- 如果 PR 修改了 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码，必须在同一 PR 中添加或更新自动化测试
|
||||
- `npm run coverage:report` 打印最近一次覆盖率运行后的逐文件详细报告
|
||||
- `npm run test:coverage:legacy` 保留旧版指标，用于历史对比
|
||||
- 分阶段覆盖率提升路线图请参阅 `docs/ops/COVERAGE_PLAN.md`
|
||||
|
||||
### Pull Request Requirements
|
||||
### Pull Request 要求
|
||||
|
||||
Before opening or merging a PR:
|
||||
发起或合并 PR 前：
|
||||
|
||||
- Run `npm run test:unit`
|
||||
- Run `npm run test:coverage`
|
||||
- Ensure the coverage gate stays at **60%+** for all metrics
|
||||
- Include the changed or added test files in the PR description when production code changed
|
||||
- Check the SonarQube result on the PR when the project secrets are configured in CI
|
||||
- 运行 `npm run test:unit`
|
||||
- 运行 `npm run test:coverage`
|
||||
- 确保覆盖率关口维持在 **60%+**（语句/行/函数/分支）
|
||||
- 涉及生产代码变更时，在 PR 描述中包含新增或修改的测试文件
|
||||
- 在 CI 中配置了项目密钥的情况下，检查 PR 上的 SonarQube 结果
|
||||
|
||||
Current test status: **122 unit test files** covering:
|
||||
当前测试状态：**122 个单元测试文件**，覆盖范围包括：
|
||||
|
||||
- Provider translators and format conversion
|
||||
- Rate limiting, circuit breaker, and resilience
|
||||
- Semantic cache, idempotency, progress tracking
|
||||
- Database operations and schema (21 DB modules)
|
||||
- OAuth flows and authentication
|
||||
- API endpoint validation (Zod v4)
|
||||
- MCP server tools and scope enforcement
|
||||
- Memory and Skills systems
|
||||
- 服务商翻译器与格式转换
|
||||
- 速率限制、熔断器与容灾
|
||||
- 语义缓存、幂等性、进度追踪
|
||||
- 数据库操作与 Schema（21 个 DB 模块）
|
||||
- OAuth 流程与认证
|
||||
- API 端点校验（Zod v4）
|
||||
- MCP Server 工具与权限域管控
|
||||
- 记忆与技能系统
|
||||
|
||||
---
|
||||
|
||||
## Code Style
|
||||
## 代码风格
|
||||
|
||||
- **ESLint** — Run `npm run lint` before committing
|
||||
- **Prettier** — Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas)
|
||||
- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`)
|
||||
- **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
|
||||
- **Zod validation** — Use Zod v4 schemas for all API input validation
|
||||
- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE
|
||||
- **ESLint** — 提交前运行 `npm run lint`
|
||||
- **Prettier** — 提交时通过 `lint-staged` 自动格式化（2 空格、分号、双引号、100 字符宽、es5 尾逗号）
|
||||
- **TypeScript** — 所有 `src/` 代码使用 `.ts`/`.tsx`；`open-sse/` 使用 `.ts`/`.js`；用 TSDoc 编写文档（`@param`、`@returns`、`@throws`）
|
||||
- **禁止 `eval()`** — ESLint 执行 `no-eval`、`no-implied-eval`、`no-new-func` 规则
|
||||
- **Zod 校验** — 所有 API 输入校验使用 Zod v4 Schema
|
||||
- **命名规范**：文件 = camelCase/kebab-case，组件 = PascalCase，常量 = UPPER_SNAKE
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
src/ # TypeScript (.ts / .tsx)
|
||||
src/ # TypeScript（.ts / .tsx）
|
||||
├── app/ # Next.js 16 App Router
|
||||
│ ├── (dashboard)/ # Dashboard pages (23 sections)
|
||||
│ ├── api/ # API routes (51 directories)
|
||||
│ └── login/ # Auth pages (.tsx)
|
||||
├── domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.)
|
||||
├── lib/ # Core business logic (.ts)
|
||||
│ ├── a2a/ # Agent-to-Agent v0.3 protocol server
|
||||
│ ├── acp/ # Agent Communication Protocol registry
|
||||
│ ├── compliance/ # Compliance policy engine
|
||||
│ ├── db/ # SQLite database layer (21 modules + 16 migrations)
|
||||
│ ├── memory/ # Persistent conversational memory
|
||||
│ ├── oauth/ # OAuth providers, services, and utilities
|
||||
│ ├── skills/ # Extensible skill framework
|
||||
│ ├── usage/ # Usage tracking and cost calculation
|
||||
│ └── localDb.ts # Re-export layer only — never add logic here
|
||||
├── middleware/ # Request middleware (promptInjectionGuard)
|
||||
├── mitm/ # MITM proxy (cert, DNS, target routing)
|
||||
│ ├── (dashboard)/ # 控制台页面（23 个分区）
|
||||
│ ├── api/ # API 路由（51 个目录）
|
||||
│ └── login/ # 认证页面（.tsx）
|
||||
├── domain/ # 策略引擎（policyEngine、comboResolver、costRules 等）
|
||||
├── lib/ # 核心业务逻辑（.ts）
|
||||
│ ├── a2a/ # Agent-to-Agent v0.3 协议服务器
|
||||
│ ├── acp/ # Agent Communication Protocol 注册中心
|
||||
│ ├── compliance/ # 合规策略引擎
|
||||
│ ├── db/ # SQLite 数据库层（21 个模块 + 16 次迁移）
|
||||
│ ├── memory/ # 持久化会话记忆
|
||||
│ ├── oauth/ # OAuth 服务商、服务与工具
|
||||
│ ├── skills/ # 可扩展技能框架
|
||||
│ ├── usage/ # 用量追踪与成本计算
|
||||
│ └── localDb.ts # 仅作 re-export 层 — 切勿在此添加逻辑
|
||||
├── middleware/ # 请求中间件（promptInjectionGuard）
|
||||
├── mitm/ # MITM 代理（证书、DNS、目标路由）
|
||||
├── shared/
|
||||
│ ├── components/ # React components (.tsx)
|
||||
│ ├── constants/ # Provider definitions (60+), MCP scopes, routing strategies
|
||||
│ ├── utils/ # Circuit breaker, sanitizer, auth helpers
|
||||
│ └── validation/ # Zod v4 schemas
|
||||
└── sse/ # SSE proxy pipeline
|
||||
│ ├── components/ # React 组件（.tsx）
|
||||
│ ├── constants/ # 服务商定义（177 个）、MCP 权限域、14 种路由策略
|
||||
│ ├── utils/ # 熔断器、清洗器、认证辅助函数
|
||||
│ └── validation/ # Zod v4 Schema
|
||||
└── sse/ # SSE 代理流水线
|
||||
|
||||
open-sse/ # @omniroute/open-sse workspace
|
||||
├── executors/ # 14 provider-specific request executors
|
||||
├── handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.)
|
||||
├── mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes)
|
||||
├── services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.)
|
||||
├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
|
||||
├── transformer/ # Responses API transformer
|
||||
└── utils/ # 22 utility modules (stream, TLS, proxy, logging)
|
||||
open-sse/ # @omniroute/open-sse 工作区
|
||||
├── executors/ # 14 个服务商专用请求执行器
|
||||
├── handlers/ # 11 个请求处理器（chat、responses、embeddings、images 等）
|
||||
├── mcp-server/ # MCP Server（25 个工具、3 种传输、10 个权限域）
|
||||
├── services/ # 36+ 个服务（combo、autoCombo、rateLimitManager 等）
|
||||
├── translator/ # 格式翻译器（OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama）
|
||||
├── transformer/ # Responses API 变换器
|
||||
└── utils/ # 22 个工具模块（stream、TLS、proxy、logging）
|
||||
|
||||
electron/ # Electron desktop app (cross-platform)
|
||||
electron/ # Electron 桌面应用（跨平台）
|
||||
|
||||
tests/
|
||||
├── unit/ # Node.js test runner (122 test files)
|
||||
├── integration/ # Integration tests
|
||||
├── e2e/ # Playwright tests
|
||||
├── security/ # Security tests
|
||||
├── translator/ # Translator-specific tests
|
||||
└── load/ # Load tests
|
||||
├── unit/ # Node.js 测试运行器（1,574 个测试文件）
|
||||
├── integration/ # 集成测试
|
||||
├── e2e/ # Playwright 测试
|
||||
├── security/ # 安全测试
|
||||
├── translator/ # 翻译器专项测试
|
||||
└── load/ # 负载测试
|
||||
|
||||
docs/ # Documentation
|
||||
├── ARCHITECTURE.md # System architecture
|
||||
├── API_REFERENCE.md # All endpoints
|
||||
├── USER_GUIDE.md # Provider setup, CLI integration
|
||||
├── TROUBLESHOOTING.md # Common issues
|
||||
├── MCP-SERVER.md # MCP server (25 tools)
|
||||
├── A2A-SERVER.md # A2A agent protocol
|
||||
├── AUTO-COMBO.md # Auto-combo engine
|
||||
├── CLI-TOOLS.md # CLI tools integration
|
||||
├── COVERAGE_PLAN.md # Test coverage improvement plan
|
||||
├── openapi.yaml # OpenAPI specification
|
||||
└── adr/ # Architecture Decision Records
|
||||
docs/
|
||||
├── adr/ # 架构决策记录
|
||||
├── architecture/ # 系统架构与容灾
|
||||
├── comparison/ # OmniRoute 与竞品对比
|
||||
├── compression/ # 压缩指南与规则
|
||||
├── dev/ # 开发指南
|
||||
├── diagrams/ # 架构图
|
||||
├── frameworks/ # MCP、A2A、OpenCode、记忆、技能
|
||||
├── guides/ # 用户指南、Docker、配置、故障排查
|
||||
├── i18n/ # 国际化 README 翻译
|
||||
├── marketing/ # 营销材料
|
||||
├── ops/ # 部署、代理、覆盖率、发布
|
||||
├── providers/ # 服务商文档
|
||||
├── reference/ # API 参考、环境变量、CLI 工具、免费层
|
||||
├── releases/ # 发布说明
|
||||
├── routing/ # Auto-Combo 引擎、推理回放
|
||||
├── screenshots/ # 控制台截图
|
||||
├── security/ # 安全护栏、合规、隐身、Token
|
||||
└── specs/ # 设计规格
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Provider
|
||||
## 添加新服务商
|
||||
|
||||
### Step 1: Register Provider Constants
|
||||
### 步骤一：注册服务商常量
|
||||
|
||||
Add to `src/shared/constants/providers.ts` — Zod-validated at module load.
|
||||
在 `src/shared/constants/providers.ts` 中添加条目 — 模块加载时通过 Zod 校验。
|
||||
|
||||
### Step 2: Add Executor (if custom logic needed)
|
||||
### 步骤二：添加执行器（如需自定义逻辑）
|
||||
|
||||
Create executor in `open-sse/executors/your-provider.ts` extending the base executor.
|
||||
在 `open-sse/executors/your-provider.ts` 中创建执行器，继承基础执行器。
|
||||
|
||||
### Step 3: Add Translator (if non-OpenAI format)
|
||||
### 步骤三：添加翻译器（如非 OpenAI 格式）
|
||||
|
||||
Create request/response translators in `open-sse/translator/`.
|
||||
在 `open-sse/translator/` 中创建请求/响应翻译器。
|
||||
|
||||
### Step 4: Add OAuth Config (if OAuth-based)
|
||||
### 步骤四：添加 OAuth 配置（如为 OAuth 类服务商）
|
||||
|
||||
Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`.
|
||||
在 `src/lib/oauth/constants/oauth.ts` 中添加 OAuth 凭证，在 `src/lib/oauth/services/` 中添加服务。
|
||||
|
||||
### Step 5: Register Models
|
||||
如果上游服务商在其公开的 CLI / 浏览器打包产物中分发了公开的 OAuth client_id/secret 或 Firebase Web API Key，**不要**将其作为字符串字面量嵌入代码。应使用 `open-sse/utils/publicCreds.ts` 中的 `resolvePublicCred()`，并在 `EMBEDDED_DEFAULTS` 中添加掩码字节条目。完整的强制工作流程参见 [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)。
|
||||
|
||||
Add model definitions in `open-sse/config/providerRegistry.ts`.
|
||||
在处理器/执行器内部，发往客户端的错误消息必须经过 `open-sse/utils/error.ts` 中的 `buildErrorBody()` / `sanitizeErrorMessage()` 处理 — 切勿在 Response body 中放入原始的 `err.stack` 或 `err.message`。参见 [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md)。
|
||||
|
||||
### Step 6: Add Tests
|
||||
### 步骤五：注册模型
|
||||
|
||||
Write unit tests in `tests/unit/` covering at minimum:
|
||||
在 `open-sse/config/providerRegistry.ts` 中添加模型定义。
|
||||
|
||||
- Provider registration
|
||||
- Request/response translation
|
||||
- Error handling
|
||||
### 步骤六：添加测试
|
||||
|
||||
在 `tests/unit/` 中编写单元测试，至少覆盖：
|
||||
|
||||
- 服务商注册
|
||||
- 请求/响应翻译
|
||||
- 错误处理
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Checklist
|
||||
## Pull Request 检查清单
|
||||
|
||||
- [ ] Tests pass (`npm test`)
|
||||
- [ ] Linting passes (`npm run lint`)
|
||||
- [ ] Build succeeds (`npm run build`)
|
||||
- [ ] TypeScript types added for new public functions and interfaces
|
||||
- [ ] No hardcoded secrets or fallback values
|
||||
- [ ] All inputs validated with Zod schemas
|
||||
- [ ] CHANGELOG updated (if user-facing change)
|
||||
- [ ] Documentation updated (if applicable)
|
||||
- [ ] 测试通过（`npm test`）
|
||||
- [ ] 代码检查通过（`npm run lint`）
|
||||
- [ ] 构建成功（`npm run build`）
|
||||
- [ ] 为新增的公开函数与接口添加了 TypeScript 类型
|
||||
- [ ] 无硬编码的密钥或兜底值
|
||||
- [ ] 公开的上游凭证通过 `resolvePublicCred()` 嵌入（参见 [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)），严禁字面量形式
|
||||
- [ ] 错误响应通过 `buildErrorBody()` / `sanitizeErrorMessage()` 处理 — Response body 中不含原始堆栈信息（参见 [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md)）
|
||||
- [ ] Shell 命令（`exec` / `spawn`）通过 `env` 传递运行时值，禁止使用字符串插值
|
||||
- [ ] 所有输入使用 Zod Schema 校验
|
||||
- [ ] CHANGELOG 已更新（如有面向用户的变更）
|
||||
- [ ] 文档已更新（如适用）
|
||||
- [ ] 未新增 CodeQL / 密钥扫描告警，或每条告警均已附技术说明予以忽略，并引用相关的 `docs/security/` 文档
|
||||
- [ ] 产生子进程的路由（`/api/mcp/`、`/api/cli-tools/runtime/`）已在 `src/server/authz/routeGuard.ts` 中分类为 `isLocalOnlyPath()` — 参见 [Hard Rule #15](docs/security/ROUTE_GUARD_TIERS.md)
|
||||
- [ ] 提交信息中不含 `Co-Authored-By` 尾部字段 — 提交必须仅出现在仓库所有者的 Git 身份下（Hard Rule #16）
|
||||
|
||||
---
|
||||
|
||||
## Releasing
|
||||
## 发布
|
||||
|
||||
Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
|
||||
发布通过 `/generate-release` 工作流管理。当新的 GitHub Release 创建时，包会通过 GitHub Actions **自动发布到 npm**。
|
||||
|
||||
VPS 部署时，请使用 `npm run build:release`（而非 `npm run build`）— 它会执行清理重建，
|
||||
将打包产物组装到 `dist/`，并写入 `dist/BUILD_SHA` 哨兵文件。
|
||||
然后使用 `/deploy-vps-*-cc` 技能，将 `dist/` rsync 到远端 `app/` 目录。
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
## 获取帮助
|
||||
|
||||
- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)
|
||||
- **API Reference**: See [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **ADRs**: See `docs/adr/` for architectural decision records
|
||||
- **架构**：参见 [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)
|
||||
- **API 参考**：参见 [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md)
|
||||
- **安全文档**：[`docs/security/CLI_TOKEN.md`](docs/security/CLI_TOKEN.md)、[`docs/security/ROUTE_GUARD_TIERS.md`](docs/security/ROUTE_GUARD_TIERS.md)、[`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md)、[`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)
|
||||
- **运维文档**：[`docs/ops/SQLITE_RUNTIME.md`](docs/ops/SQLITE_RUNTIME.md)
|
||||
- **问题反馈**：[github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **架构决策记录**：参见 `docs/adr/` 目录
|
||||
|
||||
@@ -1,25 +1,54 @@
|
||||
# Security and Cleanliness Rules for AI Assistants (中文 (简体))
|
||||
# AI 助手的安全与整洁规范 (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../GEMINI.md) · 🇸🇦 [ar](../ar/GEMINI.md) · 🇧🇬 [bg](../bg/GEMINI.md) · 🇧🇩 [bn](../bn/GEMINI.md) · 🇨🇿 [cs](../cs/GEMINI.md) · 🇩🇰 [da](../da/GEMINI.md) · 🇩🇪 [de](../de/GEMINI.md) · 🇪🇸 [es](../es/GEMINI.md) · 🇮🇷 [fa](../fa/GEMINI.md) · 🇫🇮 [fi](../fi/GEMINI.md) · 🇫🇷 [fr](../fr/GEMINI.md) · 🇮🇳 [gu](../gu/GEMINI.md) · 🇮🇱 [he](../he/GEMINI.md) · 🇮🇳 [hi](../hi/GEMINI.md) · 🇭🇺 [hu](../hu/GEMINI.md) · 🇮🇩 [id](../id/GEMINI.md) · 🇮🇹 [it](../it/GEMINI.md) · 🇯🇵 [ja](../ja/GEMINI.md) · 🇰🇷 [ko](../ko/GEMINI.md) · 🇮🇳 [mr](../mr/GEMINI.md) · 🇲🇾 [ms](../ms/GEMINI.md) · 🇳🇱 [nl](../nl/GEMINI.md) · 🇳🇴 [no](../no/GEMINI.md) · 🇵🇭 [phi](../phi/GEMINI.md) · 🇵🇱 [pl](../pl/GEMINI.md) · 🇵🇹 [pt](../pt/GEMINI.md) · 🇧🇷 [pt-BR](../pt-BR/GEMINI.md) · 🇷🇴 [ro](../ro/GEMINI.md) · 🇷🇺 [ru](../ru/GEMINI.md) · 🇸🇰 [sk](../sk/GEMINI.md) · 🇸🇪 [sv](../sv/GEMINI.md) · 🇰🇪 [sw](../sw/GEMINI.md) · 🇮🇳 [ta](../ta/GEMINI.md) · 🇮🇳 [te](../te/GEMINI.md) · 🇹🇭 [th](../th/GEMINI.md) · 🇹🇷 [tr](../tr/GEMINI.md) · 🇺🇦 [uk-UA](../uk-UA/GEMINI.md) · 🇵🇰 [ur](../ur/GEMINI.md) · 🇻🇳 [vi](../vi/GEMINI.md) · 🇨🇳 [zh-CN](../zh-CN/GEMINI.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. File Placement & Organization
|
||||
> **适用范围：** 面向 Gemini 智能体的规则。Claude Code 相关规则见 `CLAUDE.md`，其他 AI 助手相关规则见 `AGENTS.md`。
|
||||
|
||||
- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
|
||||
- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside the `scripts/` directory or `scripts/scratch/` for temporary one-offs. NEVER dump loose scripts in the project root (`/`).
|
||||
## 1. 文件放置与组织
|
||||
|
||||
**The Project Root MUST ONLY CONTAIN:**
|
||||
- **测试文件**：所有单元测试、集成测试、生态测试或 Vitest 文件必须严格放在 `tests/` 目录内（例如 `tests/unit/`、`tests/integration/`）。严禁在项目根目录（`/`）创建测试文件。
|
||||
- **脚本和工具**：所有维护、调试、生成或实验性脚本（`.cjs`、`.mjs`、`.js`、`.ts`）必须严格放在 `scripts/` 子文件夹（`build/`、`dev/`、`check/`、`docs/`、`i18n/`、`ad-hoc/`）之中。一次性或实验性代码放入 `scripts/ad-hoc/`。严禁将零散脚本丢在项目根目录（`/`）或顶层 `scripts/` 文件夹中。
|
||||
|
||||
- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
|
||||
- Dependency files (`package.json`, `package-lock.json`)
|
||||
- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
|
||||
- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
|
||||
**项目根目录只能包含：**
|
||||
|
||||
When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
|
||||
- 配置文件（`vitest.config.ts`、`next.config.mjs`、`eslint.config.mjs`、`tsconfig*.json`、`playwright.config.ts`、`prettier.config.mjs`、`postcss.config.mjs`、`sonar-project.properties`、`fly.toml`、`docker-compose*.yml`、`Dockerfile`）
|
||||
- 依赖文件（`package.json`、`package-lock.json`）
|
||||
- 文档文件（`README.md`、`CHANGELOG.md`、`LICENSE`、`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`、`llm.txt`、`Tuto_Qdrant.md`）
|
||||
- CI/CD 文件和忽略定义（`.gitignore`、`.dockerignore`、`.npmignore`、`.npmrc`、`.node-version`、`.nvmrc`、`.env.example`）
|
||||
|
||||
## 2. VPS Dashboard Credentials
|
||||
创建_任何_验证测试或一次性逻辑脚本时，根据目标默认使用 `scripts/ad-hoc/` 或 `tests/unit/` 目录。不要污染根目录（`/`）。
|
||||
|
||||
| Environment | URL | Password |
|
||||
| ----------- | ------------------------- | -------- |
|
||||
| Local VPS | http://192.168.0.15:20128 | 123456 |
|
||||
## 2. 硬规则（镜像自 `CLAUDE.md`）
|
||||
|
||||
1. **严禁提交密钥或凭证。** 使用 `.env`（从 `.env.example` 自动生成）或密钥保管库。密码、OAuth 密钥、API Key 和 Cookie 值不得出现在已提交的文件中。
|
||||
2. **严禁在 `src/lib/localDb.ts` 中添加逻辑。** 该文件仅为重新导出的桶文件。
|
||||
3. **严禁使用 `eval()`、`new Function()` 或任何形式的隐式 eval。** ESLint 强制执行此规则。
|
||||
4. **严禁直接向 `main` 分支提交。** 使用 `feat/`、`fix/`、`refactor/`、`docs/`、`test/` 或 `chore/` 分支。
|
||||
5. **严禁在路由中编写原始 SQL 语句** — 始终通过 `src/lib/db/` 领域模块进行操作。
|
||||
6. **严禁静默吞掉 SSE 流中的错误** — 应向上传播错误或干净地中止流。
|
||||
7. **未经运维人员明确批准，严禁绕过 Husky hooks**（`--no-verify`、`--no-gpg-sign`）。
|
||||
8. **始终使用 `src/shared/validation/schemas.ts` 中的 Zod Schema 校验输入。**
|
||||
9. **修改生产代码时必须附带测试**（`src/`、`open-sse/`、`electron/`、`bin/`）。
|
||||
10. **覆盖率必须保持** ≥ 75% 语句 / 75% 行 / 75% 函数 / 70% 分支（实际测量值：~82%）。
|
||||
|
||||
## 3. 代码库导航
|
||||
|
||||
| 任务 | 先行阅读 |
|
||||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 了解代码库 | `docs/architecture/REPOSITORY_MAP.md` |
|
||||
| 架构概览 | `docs/architecture/ARCHITECTURE.md` |
|
||||
| 工程参考 | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
|
||||
| 添加功能 | `CONTRIBUTING.md` + 对应领域的 `docs/<area>.md` |
|
||||
| 各领域深入文档 | `docs/frameworks/SKILLS.md`、`docs/frameworks/MEMORY.md`、`docs/frameworks/EVALS.md`、`docs/security/GUARDRAILS.md`、`docs/security/COMPLIANCE.md`、`docs/frameworks/CLOUD_AGENT.md`、`docs/frameworks/MCP-SERVER.md`、`docs/frameworks/A2A-SERVER.md`、`docs/architecture/AUTHZ_GUIDE.md`、`docs/architecture/RESILIENCE_GUIDE.md`、`docs/routing/AUTO-COMBO.md`、`docs/frameworks/WEBHOOKS.md`、`docs/routing/REASONING_REPLAY.md`、`docs/security/STEALTH_GUIDE.md`、`docs/ops/TUNNELS_GUIDE.md`、`docs/guides/ELECTRON_GUIDE.md`、`docs/reference/PROVIDER_REFERENCE.md` |
|
||||
| 发布流程 | `docs/ops/RELEASE_CHECKLIST.md` |
|
||||
|
||||
## 4. 本地开发访问
|
||||
|
||||
管理面板可通过运维人员指定的 URL/端口访问（默认 `http://localhost:20128`）。凭证信息由运维人员管理：
|
||||
|
||||
- **初始管理员密码**在首次安装时从 `INITIAL_PASSWORD` 环境变量读取（在 `.env.example` 中默认为 `CHANGEME`；首次登录后应立即更换）。
|
||||
- **本地 VPS / 共享开发环境**：向运维人员索取 URL 和当前凭证 — 这些信息存放于其个人密钥保管库中，不在本仓库内。
|
||||
|
||||
> 本文档旧版本中观察到的任何凭证均为非生产环境的演示值；应将其视为已泄露且不可复用。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,138 +1,155 @@
|
||||
# Security Policy (中文 (简体))
|
||||
# 安全策略 (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇧🇩 [bn](../bn/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇮🇷 [fa](../fa/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇮🇳 [gu](../gu/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇮🇳 [mr](../mr/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇰🇪 [sw](../sw/SECURITY.md) · 🇮🇳 [ta](../ta/SECURITY.md) · 🇮🇳 [te](../te/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇵🇰 [ur](../ur/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md)
|
||||
|
||||
---
|
||||
|
||||
## Reporting Vulnerabilities
|
||||
## 报告漏洞
|
||||
|
||||
If you discover a security vulnerability in OmniRoute, please report it responsibly:
|
||||
若您在 OmniRoute 中发现安全漏洞，请负责任地报告：
|
||||
|
||||
1. **DO NOT** open a public GitHub issue
|
||||
2. Use [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
|
||||
3. Include: description, reproduction steps, and potential impact
|
||||
1. **切勿**在 GitHub 上创建公开 issue
|
||||
2. 使用 [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
|
||||
3. 包含：漏洞描述、复现步骤和潜在影响
|
||||
|
||||
## Response Timeline
|
||||
## 响应时间
|
||||
|
||||
| Stage | Target |
|
||||
| ------------------- | --------------------------- |
|
||||
| Acknowledgment | 48 hours |
|
||||
| Triage & Assessment | 5 business days |
|
||||
| Patch Release | 14 business days (critical) |
|
||||
| 阶段 | 目标 |
|
||||
| ------------ | -------------------------- |
|
||||
| 确认收到 | 48 小时 |
|
||||
| 分类与评估 | 5 个工作日 |
|
||||
| 补丁发布 | 14 个工作日（严重漏洞） |
|
||||
|
||||
## Supported Versions
|
||||
## 支持的版本
|
||||
|
||||
| Version | Support Status |
|
||||
| ------- | -------------- |
|
||||
| 3.6.x | ✅ Active |
|
||||
| 3.5.x | ✅ Security |
|
||||
| < 3.5.0 | ❌ Unsupported |
|
||||
| 版本 | 支持状态 |
|
||||
| ------- | ------------ |
|
||||
| 3.8.x | ✅ 活跃支持 |
|
||||
| 3.7.x | ✅ 安全维护 |
|
||||
| < 3.7.0 | ❌ 不再支持 |
|
||||
|
||||
---
|
||||
|
||||
## Security Architecture
|
||||
## 安全架构
|
||||
|
||||
OmniRoute implements a multi-layered security model:
|
||||
OmniRoute 实现了多层安全模型：
|
||||
|
||||
```
|
||||
Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider
|
||||
Request → CORS → Authz pipeline (classify → policies → enforce)
|
||||
→ Guardrails (PII masker, prompt injection, vision bridge)
|
||||
→ Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider
|
||||
```
|
||||
|
||||
### 🔐 Authentication & Authorization
|
||||
### 🔐 认证与授权
|
||||
|
||||
| Feature | Implementation |
|
||||
| -------------------- | ---------------------------------------------------------- |
|
||||
| **Dashboard Login** | Password-based auth with JWT tokens (HttpOnly cookies) |
|
||||
| **API Key Auth** | HMAC-signed keys with CRC validation |
|
||||
| **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) |
|
||||
| **Token Refresh** | Automatic OAuth token refresh before expiry |
|
||||
| **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments |
|
||||
| **MCP Scopes** | 10 granular scopes for MCP tool access control |
|
||||
| 特性 | 实现 |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **管理面板登录** | 基于密码的认证，使用 JWT Token（HttpOnly Cookie） |
|
||||
| **API Key 认证** | 带 CRC 校验的 HMAC 签名密钥 |
|
||||
| **OAuth 2.0 + PKCE** | 14 个服务商（Claude、Codex、GitHub、Cursor、Antigravity、Gemini、Kimi Coding、Kilo Code、Cline、Qwen、Kiro、Qoder、Windsurf、GitLab Duo） |
|
||||
| **Token 刷新** | OAuth Token 到期前自动刷新 |
|
||||
| **安全 Cookie** | HTTPS 环境设置 `AUTH_COOKIE_SECURE=true` |
|
||||
| **授权管线** | 路由分类（PUBLIC / CLIENT_API / MANAGEMENT）— 参见 `docs/architecture/AUTHZ_GUIDE.md` |
|
||||
| **路由防护层级** | 管理路由的三层模型（LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT）— 参见 `docs/security/ROUTE_GUARD_TIERS.md` |
|
||||
| **Manage 权限域 MCP** | 远程 `/api/mcp/*` 访问受拥有 `manage` 权限域的 API Key 管控；`/api/cli-tools/runtime/*` 保持严格 loopback。参见 ROUTE_GUARD_TIERS |
|
||||
| **MCP 权限域** | 约 13 个细粒度权限域（read:health、write:combos、execute:completions 等）— 参见 `docs/frameworks/MCP-SERVER.md` |
|
||||
|
||||
### 🛡️ Encryption at Rest
|
||||
### 🛡️ 静态加密
|
||||
|
||||
All sensitive data stored in SQLite is encrypted using **AES-256-GCM** with scrypt key derivation:
|
||||
所有存储在 SQLite 中的敏感数据均使用 **AES-256-GCM** 加密，配合 scrypt 密钥派生：
|
||||
|
||||
- API keys, access tokens, refresh tokens, and ID tokens
|
||||
- Versioned format: `enc:v1:<iv>:<ciphertext>:<authTag>`
|
||||
- Passthrough mode (plaintext) when `STORAGE_ENCRYPTION_KEY` is not set
|
||||
- API Key、访问 Token、刷新 Token 和 ID Token
|
||||
- 版本化格式：`enc:v1:<iv>:<ciphertext>:<authTag>`
|
||||
- 未设置 `STORAGE_ENCRYPTION_KEY` 时采用直通模式（明文）
|
||||
|
||||
```bash
|
||||
# Generate encryption key:
|
||||
# 生成加密密钥：
|
||||
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||||
```
|
||||
|
||||
### 🧠 Prompt Injection Guard
|
||||
### 🛡️ 安全护栏框架
|
||||
|
||||
Middleware that detects and blocks prompt injection attacks in LLM requests:
|
||||
OmniRoute 附带一个支持热重载的**安全护栏注册表**（`src/lib/guardrails/`），包含 3 个内置安全护栏，按优先级排序：
|
||||
|
||||
| Pattern Type | Severity | Example |
|
||||
| ------------------- | -------- | ---------------------------------------------- |
|
||||
| System Override | High | "ignore all previous instructions" |
|
||||
| Role Hijack | High | "you are now DAN, you can do anything" |
|
||||
| Delimiter Injection | Medium | Encoded separators to break context boundaries |
|
||||
| DAN/Jailbreak | High | Known jailbreak prompt patterns |
|
||||
| Instruction Leak | Medium | "show me your system prompt" |
|
||||
| 安全护栏 | 优先级 | 用途 |
|
||||
| ------------------ | ------ | -------------------------------------------------------------------------- |
|
||||
| `vision-bridge` | 5 | 为不支持视觉的模型提供图片感知描述；对图片 URL 提供 SSRF 防护 |
|
||||
| `pii-masker` | 10 | 调用前后的 PII 脱敏（邮箱、电话、CPF、CNPJ、信用卡、SSN） |
|
||||
| `prompt-injection` | 20 | 检测指令覆盖/角色劫持/越狱/泄露模式 |
|
||||
|
||||
Configure via dashboard (Settings → Security) or `.env`:
|
||||
自定义安全护栏通过 `registerGuardrail(new MyGuardrail())` 注册。模型采用 fail-open 策略（异常不会阻断流量）。可通过 `x-omniroute-disabled-guardrails` 请求头按请求单独退出。→ 参见 [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)。
|
||||
|
||||
### 🧠 提示注入防护
|
||||
|
||||
检测并阻止 LLM 请求中提示注入攻击的中间件：
|
||||
|
||||
| 攻击类型 | 严重程度 | 示例 |
|
||||
| -------------- | -------- | ------------------------------------------------ |
|
||||
| 系统指令覆盖 | 高 | "ignore all previous instructions" |
|
||||
| 角色劫持 | 高 | "you are now DAN, you can do anything" |
|
||||
| 分隔符注入 | 中 | 使用编码分隔符破坏上下文边界 |
|
||||
| DAN/越狱 | 高 | 已知的越狱提示模式 |
|
||||
| 指令泄露 | 中 | "show me your system prompt" |
|
||||
|
||||
可通过管理面板（Settings → Security）或 `.env` 配置：
|
||||
|
||||
```env
|
||||
INPUT_SANITIZER_ENABLED=true
|
||||
INPUT_SANITIZER_MODE=block # warn | block | redact
|
||||
```
|
||||
|
||||
### 🔒 PII Redaction
|
||||
### 🔒 PII 脱敏
|
||||
|
||||
Automatic detection and optional redaction of personally identifiable information:
|
||||
自动检测并可选择性脱敏个人身份信息：
|
||||
|
||||
| PII Type | Pattern | Replacement |
|
||||
| ------------- | --------------------- | ------------------ |
|
||||
| Email | `user@domain.com` | `[EMAIL_REDACTED]` |
|
||||
| CPF (Brazil) | `123.456.789-00` | `[CPF_REDACTED]` |
|
||||
| CNPJ (Brazil) | `12.345.678/0001-00` | `[CNPJ_REDACTED]` |
|
||||
| Credit Card | `4111-1111-1111-1111` | `[CC_REDACTED]` |
|
||||
| Phone | `+55 11 99999-9999` | `[PHONE_REDACTED]` |
|
||||
| SSN (US) | `123-45-6789` | `[SSN_REDACTED]` |
|
||||
| PII 类型 | 匹配模式 | 替换文本 |
|
||||
| ------------- | --------------------- | -------------------- |
|
||||
| 邮箱 | `user@domain.com` | `[EMAIL_REDACTED]` |
|
||||
| CPF（巴西） | `123.456.789-00` | `[CPF_REDACTED]` |
|
||||
| CNPJ（巴西） | `12.345.678/0001-00` | `[CNPJ_REDACTED]` |
|
||||
| 信用卡 | `4111-1111-1111-1111` | `[CC_REDACTED]` |
|
||||
| 电话 | `+55 11 99999-9999` | `[PHONE_REDACTED]` |
|
||||
| SSN（美国） | `123-45-6789` | `[SSN_REDACTED]` |
|
||||
|
||||
```env
|
||||
PII_REDACTION_ENABLED=true
|
||||
```
|
||||
|
||||
### 🌐 Network Security
|
||||
### 🌐 网络安全
|
||||
|
||||
| Feature | Description |
|
||||
| ------------------------ | ---------------------------------------------------------------- |
|
||||
| **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
|
||||
| **IP Filtering** | Allowlist/blocklist IP ranges in dashboard |
|
||||
| **Rate Limiting** | Per-provider rate limits with automatic backoff |
|
||||
| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s |
|
||||
| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection |
|
||||
| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures |
|
||||
| 特性 | 描述 |
|
||||
| ------------------ | ------------------------------------------------------------------ |
|
||||
| **CORS** | 显式跨域白名单（`CORS_ALLOWED_ORIGINS`；旧版为 `CORS_ORIGIN`） |
|
||||
| **IP 过滤** | 管理面板中配置 IP 范围白名单/黑名单 |
|
||||
| **速率限制** | 按服务商的速率限制，带自动退避 |
|
||||
| **防惊群效应** | 互斥锁 + 按连接锁定，防止级联 502 错误 |
|
||||
| **TLS 指纹伪装** | 模拟浏览器 TLS 指纹，降低机器人检测 |
|
||||
| **CLI 指纹伪装** | 按服务商定制请求头/正文顺序，匹配原生 CLI 签名 |
|
||||
|
||||
### 🔌 Resilience & Availability
|
||||
### 🔌 容灾与可用性
|
||||
|
||||
| Feature | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------ |
|
||||
| **Circuit Breaker** | 3-state (Closed → Open → Half-Open) per provider, SQLite-persisted |
|
||||
| **Request Idempotency** | 5-second dedup window for duplicate requests |
|
||||
| **Exponential Backoff** | Automatic retry with increasing delays |
|
||||
| **Health Dashboard** | Real-time provider health monitoring |
|
||||
| 特性 | 描述 |
|
||||
| ---------------- | -------------------------------------------------------------- |
|
||||
| **熔断器** | 每个服务商的三态（Closed → Open → Half-Open），持久化到 SQLite |
|
||||
| **请求幂等** | 5 秒去重窗口，防止重复请求 |
|
||||
| **指数退避** | 自动重试，延迟时间逐次增加 |
|
||||
| **健康面板** | 服务商实时健康监控 |
|
||||
|
||||
### 📋 Compliance
|
||||
### 📋 合规
|
||||
|
||||
| Feature | Description |
|
||||
| ------------------ | ----------------------------------------------------------- |
|
||||
| **Log Retention** | Automatic cleanup after `CALL_LOG_RETENTION_DAYS` |
|
||||
| **No-Log Opt-out** | Per API key `noLog` flag disables request logging |
|
||||
| **Audit Log** | Administrative actions tracked in `audit_log` table |
|
||||
| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls |
|
||||
| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load |
|
||||
| 特性 | 描述 |
|
||||
| ------------------ | ---------------------------------------------------------- |
|
||||
| **日志保留** | 按 `CALL_LOG_RETENTION_DAYS` 自动清理 |
|
||||
| **无日志退出选项** | 可按 API Key 通过 `noLog` 标志禁用请求日志 |
|
||||
| **审计日志** | 管理操作记录在 `audit_log` 表中 |
|
||||
| **MCP 审计** | 基于 SQLite 的审计日志，覆盖所有 MCP 工具调用 |
|
||||
| **Zod 校验** | 所有 API 输入在模块加载时通过 Zod v4 Schema 校验 |
|
||||
|
||||
---
|
||||
|
||||
## Required Environment Variables
|
||||
## 必需的环境变量
|
||||
|
||||
All secrets must be set before starting the server. The server will **fail fast** if they are missing or weak.
|
||||
所有密钥必须在启动服务器前设置。若密钥缺失或强度不足，服务器将**立即终止**。
|
||||
|
||||
```bash
|
||||
# REQUIRED — server will not start without these:
|
||||
@@ -143,17 +160,17 @@ API_KEY_SECRET=$(openssl rand -hex 32) # min 16 chars
|
||||
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||||
```
|
||||
|
||||
The server actively rejects known-weak values like `changeme`, `secret`, or `password`.
|
||||
服务器会主动拒绝已知的弱值，如 `changeme`、`secret` 或 `password`。
|
||||
|
||||
---
|
||||
|
||||
## Docker Security
|
||||
## Docker 安全
|
||||
|
||||
- Use non-root user in production
|
||||
- Mount secrets as read-only volumes
|
||||
- Never copy `.env` files into Docker images
|
||||
- Use `.dockerignore` to exclude sensitive files
|
||||
- Set `AUTH_COOKIE_SECURE=true` when behind HTTPS
|
||||
- 生产环境使用非 root 用户
|
||||
- 将密钥挂载为只读卷
|
||||
- 严禁将 `.env` 文件复制到 Docker 镜像中
|
||||
- 使用 `.dockerignore` 排除敏感文件
|
||||
- 在 HTTPS 反向代理后设置 `AUTH_COOKIE_SECURE=true`
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
@@ -170,10 +187,56 @@ docker run -d \
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
## 依赖管理
|
||||
|
||||
- Run `npm audit` regularly
|
||||
- Keep dependencies updated
|
||||
- The project uses `husky` + `lint-staged` for pre-commit checks
|
||||
- CI pipeline runs ESLint security rules on every push
|
||||
- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
|
||||
- 定期运行 `npm audit`（`npm run audit:deps` 覆盖主项目 + Electron）
|
||||
- 保持依赖项更新
|
||||
- 项目使用 `husky` + `lint-staged` 进行预提交检查（lint-staged + check-docs-sync + check:any-budget:t11）
|
||||
- CI 管线每次推送时运行 ESLint 安全规则（`no-eval`、`no-implied-eval`、`no-new-func` = error）
|
||||
- 服务商常量在模块加载时通过 Zod 校验（`src/shared/validation/schemas.ts`）
|
||||
- 使用安全默认的库：`dompurify` / `isomorphic-dompurify`（XSS 防护）、`jose`（JWT）、`better-sqlite3`（参数化查询，无 SQL 注入风险）、`bcryptjs`（密码哈希）
|
||||
|
||||
## 硬安全规则
|
||||
|
||||
以下规则由工具链和代码审查人强制执行：
|
||||
|
||||
1. **严禁提交密钥** — `.env` 已被 gitignore；`.env.example` 为模板（仅注释，无字面值 — 参见下方 PUBLIC_CREDS.md）
|
||||
2. **严禁使用 `eval()`、`new Function()` 或隐式 eval** — ESLint 强制执行
|
||||
3. **未经运维人员明确批准，严禁绕过 Husky hooks**（`--no-verify`、`--no-gpg-sign`）
|
||||
4. **严禁在路由中编写原始 SQL** — 始终通过 `src/lib/db/` 操作（参数化查询）
|
||||
5. **始终使用 Zod 校验输入** — `src/shared/validation/schemas.ts`
|
||||
6. **始终清理上游请求头** — 黑名单位于 `src/shared/constants/upstreamHeaders.ts`
|
||||
7. **静态加密凭证** — 通过 `src/lib/db/encryption.ts` 使用 AES-256-GCM
|
||||
8. **通过 `resolvePublicCred()` 处理公开上游 OAuth 标识** — 严禁在源码中硬编码 `AIza…` / `GOCSPX-…` / `…apps.googleusercontent.com` 字面值。参见 [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)。
|
||||
9. **错误响应通过 `buildErrorBody()` / `sanitizeErrorMessage()` 处理** — 严禁在 HTTP / SSE / executor / MCP 响应体中暴露原始的 `err.stack` / `err.message`。参见 [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md)。
|
||||
10. **`exec()` / `spawn()` 的运行时值通过 `env` 选项传递** — 严禁将外部路径或不可信值通过字符串插值传入 Shell 脚本。参考：`src/mitm/cert/install.ts::updateNssDatabases`。
|
||||
11. **优先使用安全默认的库** — 参见 [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。在自行实现之前先查找这些现有方案。
|
||||
|
||||
## 供应链扫描器检测项（Socket.dev / Snyk / 类似工具）
|
||||
|
||||
已发布的 `omniroute` npm 制品包含 Next.js `output: "standalone"` 构建输出，这意味着所有路由处理器 — 包括已记录的特权功能（MITM、Zed 导入、Cloud Sync、嵌入式服务监管）— 都会出现在 `.next/server/*.js` 压缩块中。启发式供应链扫描器经常将这些压缩块的模式匹配为恶意软件签名。
|
||||
|
||||
对于每个检测类别，我们维护了一份逐项的维护者声明：
|
||||
|
||||
- **[`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)** —
|
||||
逐项映射表：源文件 ↔ 被标记的代码块 ↔ 行为 ↔ v3.8.6 中已应用的缓解措施。
|
||||
- 在源码中被标记的函数处，均包含 `SECURITY-AUDITOR-NOTE:` 注释块，指向同一文档。
|
||||
|
||||
对于无法放宽警报的管线，可使用以下方式构建：
|
||||
`OMNIROUTE_BUILD_PROFILE=minimal npm run build`。此方式将四个
|
||||
敏感模块替换为桩代码，运行时返回 HTTP 503 `feature-disabled`，
|
||||
从而使特权代码路径从构建产物中物理消失。
|
||||
参见 [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md) 了解发布方法。
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — 授权管线
|
||||
- [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — 安全护栏框架
|
||||
- [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — 审计日志与保留策略
|
||||
- [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) — 公开上游凭证的**强制**使用模式
|
||||
- [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md) — 错误响应的**强制**处理模式
|
||||
- [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md) — 供应链扫描器检测的维护者声明
|
||||
- [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — 熔断器 + 冷却 + 锁定
|
||||
- [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS 指纹伪装（法律/道德声明）
|
||||
- [`CLAUDE.md`](CLAUDE.md) — AI 智能体的硬规则
|
||||
- [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — 精选的安全默认库
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,106 +1,106 @@
|
||||
# Guia Completo: Cloudflare Tunnel & Zero Trust (Split-Port) (中文（简体）)
|
||||
# 完整指南：Cloudflare Tunnel 与 Zero Trust (Split-Port) (中文（简体）)
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/cloudflare-zero-trust-guide.md) · 🇪🇸 [es](../../es/docs/cloudflare-zero-trust-guide.md) · 🇫🇷 [fr](../../fr/docs/cloudflare-zero-trust-guide.md) · 🇩🇪 [de](../../de/docs/cloudflare-zero-trust-guide.md) · 🇮🇹 [it](../../it/docs/cloudflare-zero-trust-guide.md) · 🇷🇺 [ru](../../ru/docs/cloudflare-zero-trust-guide.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/cloudflare-zero-trust-guide.md) · 🇯🇵 [ja](../../ja/docs/cloudflare-zero-trust-guide.md) · 🇰🇷 [ko](../../ko/docs/cloudflare-zero-trust-guide.md) · 🇸🇦 [ar](../../ar/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [hi](../../hi/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [in](../../in/docs/cloudflare-zero-trust-guide.md) · 🇹🇭 [th](../../th/docs/cloudflare-zero-trust-guide.md) · 🇻🇳 [vi](../../vi/docs/cloudflare-zero-trust-guide.md) · 🇮🇩 [id](../../id/docs/cloudflare-zero-trust-guide.md) · 🇲🇾 [ms](../../ms/docs/cloudflare-zero-trust-guide.md) · 🇳🇱 [nl](../../nl/docs/cloudflare-zero-trust-guide.md) · 🇵🇱 [pl](../../pl/docs/cloudflare-zero-trust-guide.md) · 🇸🇪 [sv](../../sv/docs/cloudflare-zero-trust-guide.md) · 🇳🇴 [no](../../no/docs/cloudflare-zero-trust-guide.md) · 🇩🇰 [da](../../da/docs/cloudflare-zero-trust-guide.md) · 🇫🇮 [fi](../../fi/docs/cloudflare-zero-trust-guide.md) · 🇵🇹 [pt](../../pt/docs/cloudflare-zero-trust-guide.md) · 🇷🇴 [ro](../../ro/docs/cloudflare-zero-trust-guide.md) · 🇭🇺 [hu](../../hu/docs/cloudflare-zero-trust-guide.md) · 🇧🇬 [bg](../../bg/docs/cloudflare-zero-trust-guide.md) · 🇸🇰 [sk](../../sk/docs/cloudflare-zero-trust-guide.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/cloudflare-zero-trust-guide.md) · 🇮🇱 [he](../../he/docs/cloudflare-zero-trust-guide.md) · 🇵🇭 [phi](../../phi/docs/cloudflare-zero-trust-guide.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/cloudflare-zero-trust-guide.md) · 🇨🇿 [cs](../../cs/docs/cloudflare-zero-trust-guide.md) · 🇹🇷 [tr](../../tr/docs/cloudflare-zero-trust-guide.md)
|
||||
|
||||
---
|
||||
|
||||
Este guia documenta o padrão ouro de infraestrutura de rede para proteger o **OmniRoute** e expor sua aplicação de forma segura para a internet, **sem abrir nenhuma porta (Zero Inbound)**.
|
||||
本指南记录了保护 **OmniRoute** 并将应用安全暴露到互联网的网络基础设施黄金标准，**无需开放任何端口（Zero Inbound）**。
|
||||
|
||||
## O que foi feito na sua VM?
|
||||
## 您的虚拟机上做了什么？
|
||||
|
||||
Nós ativamos o OmniRoute em modo **Split-Port** através do PM2:
|
||||
我们通过 PM2 以 **Split-Port** 模式启动了 OmniRoute：
|
||||
|
||||
- **Porta \`20128\`:** Roda **apenas a API** `/v1`.
|
||||
- **Porta \`20129\`:** Roda **apenas o Dashboard** Administrativo visual.
|
||||
- **端口 `20128`：** 仅运行 **API** `/v1`。
|
||||
- **端口 `20129`：** 仅运行可视化管理 **Dashboard**。
|
||||
|
||||
Além disso, o serviço interno exige \`REQUIRE_API_KEY=true\`, o que significa que nenhum agente pode consumir os endpoints da API sem enviar um "Bearer Token" legítimo gerado na aba API Keys do Painel.
|
||||
此外，内部服务要求 `REQUIRE_API_KEY=true`，这意味着任何代理程序都必须发送在管理面板 API Keys 标签页中生成的有效 "Bearer Token" 才能访问 API 端点。
|
||||
|
||||
Isso nos permite criar duas regras completamente independentes na rede. É aqui que entra o **Cloudflare Tunnel (cloudflared)**.
|
||||
这使我们能够在网络中创建两条完全独立的规则。这就是 **Cloudflare Tunnel（cloudflared）** 发挥作用的地方。
|
||||
|
||||
---
|
||||
|
||||
## 1. Como Criar o Túnel na Cloudflare
|
||||
## 1. 如何在 Cloudflare 上创建隧道
|
||||
|
||||
O utilitário \`cloudflared\` já está instalado na sua máquina. Siga os passos na nuvem:
|
||||
`cloudflared` 工具已安装在您的机器上。请按以下云端步骤操作：
|
||||
|
||||
1. Acesse seu painel **Cloudflare Zero Trust** (One.dash.cloudflare.com).
|
||||
2. No menu à esquerda, vá em **Networks > Tunnels**.
|
||||
3. Clique em **Add a Tunnel**, escolha **Cloudflared** e dê o nome \`OmniRoute-VM\`.
|
||||
4. Ele vai gerar um comando na tela chamado "Install and run a connector". **Você só precisa copiar o Token (a string longa após `--token`)**.
|
||||
5. Logue via SSH na sua máquina virtual (ou Terminal do Proxmox) e execute:
|
||||
\`\`\`bash
|
||||
# Inicia e amarra o túnel permanentemente à sua conta
|
||||
cloudflared service install SEU_TOKEN_GIGANTE_AQUI
|
||||
\`\`\`
|
||||
1. 访问您的 **Cloudflare Zero Trust** 面板（One.dash.cloudflare.com）。
|
||||
2. 在左侧菜单中，前往 **Networks > Tunnels**。
|
||||
3. 点击 **Add a Tunnel**，选择 **Cloudflared**，命名为 `OmniRoute-VM`。
|
||||
4. 屏幕会生成一个名为 "Install and run a connector" 的命令。**您只需复制 Token（`--token` 后面的长字符串）**。
|
||||
5. 通过 SSH 登录您的虚拟机（或 Proxmox 终端），执行：
|
||||
```bash
|
||||
# 启动并永久绑定隧道到您的账户
|
||||
cloudflared service install YOUR_HUGE_TOKEN_HERE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Configurando o Roteamento (Public Hostnames)
|
||||
## 2. 配置路由（Public Hostnames）
|
||||
|
||||
Ainda na tela do Tunnel recém-criado, vá para a aba **Public Hostnames** e adicione as **duas** rotas, aproveitando a separação que fizemos:
|
||||
在新创建隧道的界面中，进入 **Public Hostnames** 标签页，利用我们做的端口分离，添加 **两条** 路由：
|
||||
|
||||
### Rota 1: API Segura (Limitada)
|
||||
### 路由 1：安全 API（受限）
|
||||
|
||||
- **Subdomain:** \`api\`
|
||||
- **Domain:** \`seuglobal.com.br\` (escolha seu domínio real)
|
||||
- **Service Type:** \`HTTP\`
|
||||
- **URL:** \`127.0.0.1:20128\` _(Porta interna da API)_
|
||||
- **Subdomain：** `api`
|
||||
- **Domain：** `yourdomain.com`（选择您的实际域名）
|
||||
- **Service Type：** `HTTP`
|
||||
- **URL：** `127.0.0.1:20128` _（API 内部端口）_
|
||||
|
||||
### Rota 2: Painel Zero Trust (Fechado)
|
||||
### 路由 2：Zero Trust 管理面板（封闭）
|
||||
|
||||
- **Subdomain:** \`omniroute\` ou \`painel\`
|
||||
- **Domain:** \`seuglobal.com.br\`
|
||||
- **Service Type:** \`HTTP\`
|
||||
- **URL:** \`127.0.0.1:20129\` _(Porta interna do App/Visual)_
|
||||
- **Subdomain：** `omniroute` 或 `panel`
|
||||
- **Domain：** `yourdomain.com`
|
||||
- **Service Type：** `HTTP`
|
||||
- **URL：** `127.0.0.1:20129` _（App/可视化内部端口）_
|
||||
|
||||
Neste momento, a conectividade "Física" está resolvida. Agora vamos blindar de verdade.
|
||||
此时，"物理"连接已经解决。现在我们要真正加固它。
|
||||
|
||||
---
|
||||
|
||||
## 3. Blindando o Painel com Zero Trust (Access)
|
||||
## 3. 使用 Zero Trust（Access）加固管理面板
|
||||
|
||||
Nenhuma senha local protege melhor o seu painel do que remover totalmente o acesso a ele da internet aberta.
|
||||
比起在本地设置密码，更好地保护管理面板的方式是将它完全从开放互联网中移除。
|
||||
|
||||
1. No painel Zero Trust, vá em **Access > Applications > Add an application**.
|
||||
2. Selecione **Self-hosted**.
|
||||
3. Em **Application name**, coloque \`Painel OmniRoute\`.
|
||||
4. Em **Application domain**, coloque \`omniroute.seuglobal.com.br\` (O mesmo que você fez na "Rota 2").
|
||||
5. Clique em **Next**.
|
||||
6. Em **Rule action**, escolha \`Allow\`. Em nome da Rule coloque \`Admin Apenas\`.
|
||||
7. Em **Include**, no seletor de "Selector" escolha \`Emails\` e digite o seu email, por exemplo \`admin@spgeo.com.br\`.
|
||||
8. Salve (`Add application`).
|
||||
1. 在 Zero Trust 面板中，前往 **Access > Applications > Add an application**。
|
||||
2. 选择 **Self-hosted**。
|
||||
3. 在 **Application name** 中，填入 `OmniRoute Panel`。
|
||||
4. 在 **Application domain** 中，填入 `omniroute.yourdomain.com`（与"路由 2"中设置的一致）。
|
||||
5. 点击 **Next**。
|
||||
6. 在 **Rule action** 中选择 `Allow`。在 Rule 名称中填入 `Admin Only`。
|
||||
7. 在 **Include** 中，"Selector" 选择 `Emails`，输入您的邮箱，例如 `admin@example.com`。
|
||||
8. 保存（`Add application`）。
|
||||
|
||||
> **O que isso fez:** Se você tentar abrir \`omniroute.seuglobal.com.br\`, não cai mais na sua aplicação OmniRoute! Cai numa tela elegante da Cloudflare pedindo para digitar seu email. Somente se você (ou o email que você botou) for digitado lá, ele recebe no Outlook/Gmail um código de 6 dígitos temporário que libera o túnel até a porta \`20129\`.
|
||||
> **效果：** 如果您尝试打开 `omniroute.yourdomain.com`，将不再直接进入您的 OmniRoute 应用！而是跳转到一个精美的 Cloudflare 页面，要求输入邮箱地址。只有您（或您填写的邮箱）输入后，Outlook/Gmail 会收到一个 6 位临时验证码，验证通过后才会解除隧道限制，允许访问 `20129` 端口。
|
||||
|
||||
---
|
||||
|
||||
## 4. Limitando e Protegendo a API com Rate Limit (WAF)
|
||||
## 4. 使用速率限制（WAF）限制并保护 API
|
||||
|
||||
O Dashboard do Zero Trust não se aplica à rota da API (\`api.seuglobal.com.br\`), porque é um acesso programático via ferramentas automatizadas (agentes) sem navegador. Para ele, usaremos o Firewall principal (WAF) da Cloudflare.
|
||||
Zero Trust Dashboard 不适用于 API 路由（`api.yourdomain.com`），因为这是通过自动化工具（代理程序）进行的编程访问，无需浏览器。对于这种情况，我们将使用 Cloudflare 的主防火墙（WAF）。
|
||||
|
||||
1. Acesse o **Painel Normal** da Cloudflare (dash.cloudflare.com) e entre no seu Domínio.
|
||||
2. No menu esquerdo, vá em **Security > WAF > Rate limiting rules**.
|
||||
3. Clique em **Create rule**.
|
||||
4. **Name:** \`Anti-Abuso OmniRoute API\`
|
||||
1. 访问 Cloudflare **常规面板**（dash.cloudflare.com），进入您的域名。
|
||||
2. 在左侧菜单中，前往 **Security > WAF > Rate limiting rules**。
|
||||
3. 点击 **Create rule**。
|
||||
4. **Name：** `Anti-Abuse OmniRoute API`
|
||||
5. **If incoming requests match...**
|
||||
- Escolha em Field: \`Hostname\`
|
||||
- Operator: \`equals\`
|
||||
- Value: \`api.seuglobal.com.br\`
|
||||
6. Em **With the same characteristics:** Mantenha \`IP\`.
|
||||
7. Nos limites (Limit):
|
||||
- **When requests exceed:** \`50\`
|
||||
- **Period:** \`1 minute\`
|
||||
8. No final, em **Action**: \`Block\` (Bloquear) e decida se o bloqueio dura por 1 minuto ou 1 hora.
|
||||
9. **Deploy**.
|
||||
- Field 选择：`Hostname`
|
||||
- Operator：`equals`
|
||||
- Value：`api.yourdomain.com`
|
||||
6. **With the same characteristics：** 保持 `IP`。
|
||||
7. 限制条件（Limit）：
|
||||
- **When requests exceed：** `50`
|
||||
- **Period：** `1 minute`
|
||||
8. 最后，在 **Action** 中选择 `Block`，并决定阻止持续 1 分钟还是 1 小时。
|
||||
9. **Deploy**。
|
||||
|
||||
> **O que isso fez:** Ninguém pode mandar mais de 50 requisições num período de 60 segundos na sua URL de API. Como você roda vários agentes e os consumos por trás já batem rate limit e já rastreiam tokens, isso é apenas uma medida na Borda da Internet (Edge Layer) que protege sua Instância On-Premises de cair por estresse térmico antes mesmo do tráfego descer pelo túnel.
|
||||
> **效果：** 在 60 秒内，任何人都不能向您的 API URL 发送超过 50 次请求。由于您运行着多个代理程序，其背后的消费已经受到速率限制和 Token 追踪，这只是互联网边缘层（Edge Layer）的一项措施，在流量进入隧道之前就保护您的本地部署实例免受压力过载。
|
||||
|
||||
---
|
||||
|
||||
## Finalização
|
||||
## 完成
|
||||
|
||||
1. A sua VM **não possui nenhuma porta exposta** em `/etc/ufw`.
|
||||
2. O OmniRoute só conversa HTTPS saindo (\`cloudflared\`) e não recebendo TCP direto do mundo.
|
||||
3. Seus requets pro OpenAI são ofuscados porque configuramos eles globalmente pra passar em um Proxy SOCKS5 (A nuvem não liga pro SOCKS5 porque ela vem Inbound).
|
||||
4. Seu painel web tem 2-Factor com Email.
|
||||
5. Sua API está ratelimitada na borda pela Cloudflare e só trafega Bearer Tokens.
|
||||
1. 您的虚拟机 **没有任何端口暴露** 在 `/etc/ufw` 中。
|
||||
2. OmniRoute 仅通过 `cloudflared` 进行 HTTPS 出站通信，不直接接收来自外部的 TCP 连接。
|
||||
3. 您的 OpenAI 请求已混淆处理，因为我们已全局配置通过 SOCKS5 代理发送（云端不关心 SOCKS5，因为流量是入站的）。
|
||||
4. 您的 Web 管理面板具有邮件两步验证。
|
||||
5. 您的 API 在边缘层受 Cloudflare 速率限制，且仅传输 Bearer Token。
|
||||
|
||||
@@ -1,65 +1,57 @@
|
||||
# Context Relay (中文（简体）)
|
||||
# Context Relay（上下文中继）(中文（简体）)
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../../docs/features/context-relay.md) · 🇪🇸 [es](../../../es/docs/features/context-relay.md) · 🇫🇷 [fr](../../../fr/docs/features/context-relay.md) · 🇩🇪 [de](../../../de/docs/features/context-relay.md) · 🇮🇹 [it](../../../it/docs/features/context-relay.md) · 🇷🇺 [ru](../../../ru/docs/features/context-relay.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/features/context-relay.md) · 🇯🇵 [ja](../../../ja/docs/features/context-relay.md) · 🇰🇷 [ko](../../../ko/docs/features/context-relay.md) · 🇸🇦 [ar](../../../ar/docs/features/context-relay.md) · 🇮🇳 [hi](../../../hi/docs/features/context-relay.md) · 🇮🇳 [in](../../../in/docs/features/context-relay.md) · 🇹🇭 [th](../../../th/docs/features/context-relay.md) · 🇻🇳 [vi](../../../vi/docs/features/context-relay.md) · 🇮🇩 [id](../../../id/docs/features/context-relay.md) · 🇲🇾 [ms](../../../ms/docs/features/context-relay.md) · 🇳🇱 [nl](../../../nl/docs/features/context-relay.md) · 🇵🇱 [pl](../../../pl/docs/features/context-relay.md) · 🇸🇪 [sv](../../../sv/docs/features/context-relay.md) · 🇳🇴 [no](../../../no/docs/features/context-relay.md) · 🇩🇰 [da](../../../da/docs/features/context-relay.md) · 🇫🇮 [fi](../../../fi/docs/features/context-relay.md) · 🇵🇹 [pt](../../../pt/docs/features/context-relay.md) · 🇷🇴 [ro](../../../ro/docs/features/context-relay.md) · 🇭🇺 [hu](../../../hu/docs/features/context-relay.md) · 🇧🇬 [bg](../../../bg/docs/features/context-relay.md) · 🇸🇰 [sk](../../../sk/docs/features/context-relay.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/features/context-relay.md) · 🇮🇱 [he](../../../he/docs/features/context-relay.md) · 🇵🇭 [phi](../../../phi/docs/features/context-relay.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/features/context-relay.md) · 🇨🇿 [cs](../../../cs/docs/features/context-relay.md) · 🇹🇷 [tr](../../../tr/docs/features/context-relay.md)
|
||||
|
||||
---
|
||||
|
||||
`context-relay` is a combo strategy that keeps session continuity when the active account
|
||||
rotates before the conversation is finished.
|
||||
`context-relay` 是一种 Combo 策略，可在活跃账户在对话结束前轮换时保持会话连续性。
|
||||
|
||||
The current runtime behaves like priority routing for model selection, then adds a
|
||||
handoff layer on top:
|
||||
当前运行时在模型选择上表现为优先级路由，并在此基础上增加了一个交接层：
|
||||
|
||||
- before the active account is exhausted, OmniRoute generates a compact structured summary
|
||||
- after authentication selects a different account for the same session, OmniRoute injects
|
||||
that summary as a system message into the next request
|
||||
- once the handoff is consumed successfully, it is removed from storage
|
||||
- 在活跃账户耗尽之前，OmniRoute 生成一份紧凑的结构化摘要
|
||||
- 身份认证为同一会话选择了不同账户后，OmniRoute 将该摘要作为系统消息注入下一次请求
|
||||
- 交接被成功消费后，将从存储中移除
|
||||
|
||||
## When To Use It
|
||||
## 适用场景
|
||||
|
||||
Use `context-relay` when all of the following are true:
|
||||
在以下条件全部满足时使用 `context-relay`：
|
||||
|
||||
- the combo is expected to rotate between multiple accounts of the same provider
|
||||
- losing short-term conversational continuity would hurt task quality
|
||||
- the provider exposes enough quota information to predict an approaching account limit
|
||||
- Combo 预期会在同一服务商的多个账户之间轮换
|
||||
- 丢失短期会话连续性会损害任务质量
|
||||
- 服务商暴露了足够的配额信息以预测即将达到的账户限制
|
||||
|
||||
This is most useful for long-running coding or research sessions that may outlive a single
|
||||
account window.
|
||||
这对于可能超出单个账户窗口的长时间编程或研究会话最为有用。
|
||||
|
||||
## Runtime Flow
|
||||
## 运行时流程
|
||||
|
||||
The current behavior is intentionally split across two runtime layers.
|
||||
当前行为有意分为两个运行时层。
|
||||
|
||||
### 0% to 84% quota used
|
||||
### 配额用量 0% 到 84%
|
||||
|
||||
No handoff is generated. Requests behave like normal priority routing.
|
||||
不生成交接。请求行为与普通优先级路由一致。
|
||||
|
||||
### 85% to 94% quota used
|
||||
### 配额用量 85% 到 94%
|
||||
|
||||
If the active provider is enabled in `handoffProviders`, OmniRoute generates a structured
|
||||
handoff summary in the background before the account is fully exhausted.
|
||||
如果活跃服务商在 `handoffProviders` 中已启用，OmniRoute 将在账户完全耗尽前在后台生成一份结构化的交接摘要。
|
||||
|
||||
Important details:
|
||||
重要细节：
|
||||
|
||||
- the default warning threshold is `0.85`
|
||||
- the hard stop for generation is `0.95`
|
||||
- only one in-flight handoff generation is allowed per `sessionId + comboName`
|
||||
- if an active handoff already exists for that session/combo, no duplicate summary is generated
|
||||
- 默认警告阈值为 `0.85`
|
||||
- 生成的硬停止线为 `0.95`
|
||||
- 每个 `sessionId + comboName` 只允许一个进行中的交接生成
|
||||
- 如果该会话/Combo 已有活跃交接，则不会生成重复摘要
|
||||
|
||||
### 95% or more quota used
|
||||
### 配额用量 95% 或以上
|
||||
|
||||
No new handoff is generated. At this point the system is already in or near exhaustion and
|
||||
the runtime avoids scheduling another summary request.
|
||||
不再生成新交接。此时系统已处于或接近耗尽状态，运行时会避免调度另一个摘要请求。
|
||||
|
||||
### After account rotation
|
||||
### 账户轮换后
|
||||
|
||||
When the next request for the same session resolves to a different authenticated account,
|
||||
OmniRoute prepends the stored handoff as a system message. Injection happens only after the
|
||||
real account switch is known.
|
||||
当同一会话的下一次请求解析到不同的认证账户时，OmniRoute 将存储的交接作为系统消息前置注入。注入仅在实际账户切换被确认后发生。
|
||||
|
||||
## Handoff Payload
|
||||
## 交接载荷
|
||||
|
||||
The persisted handoff payload is stored in `context_handoffs` and includes:
|
||||
持久化的交接载荷存储在 `context_handoffs` 中，包含：
|
||||
|
||||
- `sessionId`
|
||||
- `comboName`
|
||||
@@ -74,57 +66,51 @@ The persisted handoff payload is stored in `context_handoffs` and includes:
|
||||
- `generatedAt`
|
||||
- `expiresAt`
|
||||
|
||||
The summary model is instructed to return a JSON object with this structure:
|
||||
摘要模型被指示返回一个包含以下结构的 JSON 对象：
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": "Dense summary of what matters for continuity",
|
||||
"keyDecisions": ["Decision 1", "Decision 2"],
|
||||
"taskProgress": "What is done, what is pending, and the next step",
|
||||
"activeEntities": ["fileA.ts", "feature X", "provider Y"]
|
||||
"summary": "对连续性重要内容的紧凑摘要",
|
||||
"keyDecisions": ["决策 1", "决策 2"],
|
||||
"taskProgress": "已完成项、待完成项以及下一步",
|
||||
"activeEntities": ["fileA.ts", "功能 X", "服务商 Y"]
|
||||
}
|
||||
```
|
||||
|
||||
At injection time, OmniRoute converts that payload into a `<context_handoff>` system
|
||||
message so the next account can continue with the correct local context.
|
||||
在注入时，OmniRoute 将该载荷转换为 `<context_handoff>` 系统消息，使下一个账户能够在正确的本地上下文中继续。
|
||||
|
||||
## 配置
|
||||
|
||||
`context-relay` supports these config fields:
|
||||
`context-relay` 支持以下配置字段：
|
||||
|
||||
- `handoffThreshold`: warning threshold for summary generation, default `0.85`
|
||||
- `handoffModel`: optional model override used only for summary generation
|
||||
- `handoffProviders`: allowlist of providers allowed to trigger handoff generation
|
||||
- `handoffThreshold`：摘要生成的警告阈值，默认 `0.85`
|
||||
- `handoffModel`：可选的模型覆盖，仅用于摘要生成
|
||||
- `handoffProviders`：允许触发交接生成的服务商白名单
|
||||
|
||||
Global defaults can be configured in Settings, and combo-specific values can override them
|
||||
in the Combos page.
|
||||
全局默认值可在设置中配置，Combo 特定值可在 Combos 页面中覆盖。
|
||||
|
||||
## Architectural Note
|
||||
## 架构说明
|
||||
|
||||
The current implementation does not use a standalone `handleContextRelayCombo` handler.
|
||||
当前实现不采用独立的 `handleContextRelayCombo` 处理器。
|
||||
|
||||
Instead:
|
||||
相反：
|
||||
|
||||
- `open-sse/services/combo.ts` decides whether a successful turn should generate a handoff
|
||||
- `src/sse/handlers/chat.ts` injects the handoff only after authentication resolves the
|
||||
actual account used for the request
|
||||
- `open-sse/services/combo.ts` 决定成功的回合是否应生成交接
|
||||
- `src/sse/handlers/chat.ts` 仅在身份认证解析了请求实际使用的账户后注入交接
|
||||
|
||||
This split is intentional in the current codebase because the combo loop alone does not know
|
||||
whether the request stayed on the same account or actually switched accounts.
|
||||
在当前代码库中，这种分离是刻意的，因为 Combo 循环本身不知道请求是停留在同一账户上还是实际切换了账户。
|
||||
|
||||
## Limitations
|
||||
## 局限性
|
||||
|
||||
- Effective runtime support is currently centered on `codex` quota rotation.
|
||||
- `handoffProviders` is already modeled as a config surface, but real handoff generation
|
||||
still depends on provider-specific quota plumbing.
|
||||
- The summary is intentionally compact and recent-history based; it is not a full transcript
|
||||
replay mechanism.
|
||||
- Handoffs are scoped by `sessionId + comboName` and expire automatically.
|
||||
- If the session does not switch accounts, the stored handoff is not injected.
|
||||
- 有效运行时支持目前集中于 `codex` 配额轮换。
|
||||
- `handoffProviders` 已建模为配置界面，但实际交接生成仍依赖于特定服务商的配额管道。
|
||||
- 摘要刻意保持紧凑并基于近期历史；它不是完整的对话回放机制。
|
||||
- 交接范围限定于 `sessionId + comboName`，并自动过期。
|
||||
- 如果会话未切换账户，存储的交接不会被注入。
|
||||
|
||||
## Recommended Usage Pattern
|
||||
## 推荐使用模式
|
||||
|
||||
- use multiple accounts from the same provider
|
||||
- keep stable `sessionId` values across the session
|
||||
- set `handoffThreshold` early enough to leave room for the background summary request
|
||||
- treat the feature as continuity assistance, not as a replacement for persistent memory
|
||||
- 使用同一服务商的多个账户
|
||||
- 在整个会话中保持稳定的 `sessionId` 值
|
||||
- 将 `handoffThreshold` 设置得足够早，为后台摘要请求留出空间
|
||||
- 将此功能视为连续性辅助工具，而非持久记忆的替代品
|
||||
|
||||
@@ -4,35 +4,48 @@
|
||||
|
||||
---
|
||||
|
||||
> Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent
|
||||
> Agent-to-Agent Protocol v0.3 — OmniRoute 作为智能路由代理
|
||||
|
||||
## Agent Discovery
|
||||
A2A 层有两个入口：
|
||||
|
||||
- **JSON-RPC 2.0** 位于 `POST /a2a`（正式入口，定义在 `src/app/a2a/route.ts`）。
|
||||
- **REST** 位于 `/api/a2a/*`，用于仪表盘和工具操作（状态、任务列表、取消）。
|
||||
|
||||
任务由 `A2ATaskManager`（`src/lib/a2a/taskManager.ts`，默认 5 分钟 TTL）跟踪。技能通过 `src/lib/a2a/taskExecution.ts` 中的 `A2A_SKILL_HANDLERS` 派发。
|
||||
|
||||
## 代理发现
|
||||
|
||||
```bash
|
||||
curl http://localhost:20128/.well-known/agent.json
|
||||
```
|
||||
|
||||
Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements.
|
||||
返回 Agent Card，其中描述 OmniRoute 的能力、技能和认证要求。
|
||||
|
||||
Agent Card 的 `version` 字段取自 `process.env.npm_package_version`（参见 `src/app/.well-known/agent.json/route.ts:13`），因此每次发布时都与 `package.json` 自动保持同步。
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
## 认证
|
||||
|
||||
All `/a2a` requests require an API key via the `Authorization` header:
|
||||
所有 `/a2a` 请求均需通过 `Authorization` 请求头提供 API Key：
|
||||
|
||||
```
|
||||
Authorization: Bearer YOUR_OMNIROUTE_API_KEY
|
||||
```
|
||||
|
||||
If no API key is configured on the server, authentication is bypassed.
|
||||
如果服务器未配置 API Key，认证将被跳过。
|
||||
|
||||
## 启用
|
||||
|
||||
A2A 通过 **端点 → A2A** 开关控制，默认禁用。禁用时，`GET /api/a2a/status` 返回 `status: "disabled"` 和 `online: false`；对 `POST /a2a` 的 JSON-RPC 调用返回 HTTP 503，附带 JSON-RPC 错误码 `-32000`。
|
||||
|
||||
---
|
||||
|
||||
## 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 +63,7 @@ curl -X POST http://localhost:20128/a2a \
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -71,9 +84,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 +103,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 +113,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 +122,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 +133,93 @@ 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. |
|
||||
OmniRoute 暴露了 6 个 A2A 技能，连接到 `src/lib/a2a/taskExecution.ts::A2A_SKILL_HANDLERS`。每个技能模块位于 `src/lib/a2a/skills/`。
|
||||
|
||||
| 技能 | ID | 描述 | 标签 | 示例 |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| Smart Routing | `smart-routing` | 通过 OmniRoute 的 Combo 引擎与评分，将提示路由到最优服务商/Combo | routing, 服务商 | "通过最佳模型路由此提示" |
|
||||
| Quota Management | `quota-management` | 报告每个服务商的配额状态，帮助调用方决定何时限流/切换 | 配额, 服务商 | "检查 anthropic 的配额" |
|
||||
| Provider Discovery | `provider-discovery` | 列出已安装的服务商及其能力、免费层标志、OAuth 状态 | 服务商, 发现 | "有哪些可用服务商？" |
|
||||
| Cost Analysis | `cost-analysis` | 根据目录和近期用量估算请求/对话的成本 | 成本, 用量 | "估算本次对话的成本" |
|
||||
| Health Report | `health-report` | 聚合每个服务商的熔断器、冷却、锁定状态 | 健康, 容灾 | "显示所有服务商的健康状态" |
|
||||
| List Capabilities | `list-capabilities` | 返回完整的 42 项代理技能目录，以 Markdown 表格形式列出，附带原始 SKILL.md URL 用于上下文注入 | 目录, 发现, 技能 | "列出所有 OmniRoute 能力" |
|
||||
|
||||
> 注意：Agent Card 描述目前宣传 "36+ providers"（`src/app/.well-known/agent.json/route.ts:26` 和 `:55`）。实际目录已增长至 180+ 个服务商——该字符串应在后续变更中更新（作为单独的文档/代码 TODO 跟踪；此处不作修改）。
|
||||
|
||||
### `list-capabilities` 技能详情
|
||||
|
||||
`list-capabilities` 技能对于需要在发送 API 调用前了解 OmniRoute 暴露了哪些内容的外部代理尤为有用。它返回结构化的 Markdown 表格 artifact：
|
||||
|
||||
```
|
||||
| ID | Name | Category | Area | Endpoints/Commands | Raw URL |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| omni-auth | Auth & Sessions | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... |
|
||||
...
|
||||
```
|
||||
|
||||
每行包含 `rawUrl` 列，以便代理可以立即获取完整的 SKILL.md。`metadata.totalSkills` 字段始终为 `42`。实现：`src/lib/a2a/skills/listCapabilities.ts`。另见 [AGENT-SKILLS.md](./AGENT-SKILLS.md)。
|
||||
|
||||
---
|
||||
|
||||
## Task Lifecycle
|
||||
## REST API（辅助）
|
||||
|
||||
JSON-RPC 端点 `/a2a` 是 A2A 的正式入口。以下 REST 端点提供仪表盘和外部工具的辅助访问：
|
||||
|
||||
| 端点 | 方法 | 描述 | 认证 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `/api/a2a/status` | GET | 服务器状态、已注册技能 | （公开） |
|
||||
| `/api/a2a/tasks` | GET | 列出任务（支持过滤） | 管理 |
|
||||
| `/api/a2a/tasks/[id]` | GET | 按 ID 获取任务 | 管理 |
|
||||
| `/api/a2a/tasks/[id]/cancel` | POST | 取消运行中的任务 | 管理 |
|
||||
| `/.well-known/agent.json` | GET | Agent Card（A2A 发现） | （公开, 缓存 3600s） |
|
||||
|
||||
---
|
||||
|
||||
## 添加新技能
|
||||
|
||||
1. **创建技能文件：** `src/lib/a2a/skills/<your-skill>.ts`
|
||||
|
||||
导出一个异步函数 `(task: A2ATask) => Promise<{ artifacts, metadata }>`。参照现有技能如 `smartRouting.ts` 的结构。
|
||||
|
||||
2. **注册处理器：** 在 `src/lib/a2a/taskExecution.ts` 中，向 `A2A_SKILL_HANDLERS` 添加一项：
|
||||
|
||||
```typescript
|
||||
export const A2A_SKILL_HANDLERS = {
|
||||
// ...existing skills
|
||||
"your-skill": async (task) => {
|
||||
const skillModule = await import("./skills/yourSkill");
|
||||
return skillModule.executeYourSkill(task);
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
3. **在 Agent Card 中暴露：** 在 `src/app/.well-known/agent.json/route.ts` 中，追加到 `skills` 数组：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "your-skill",
|
||||
"name": "Your Skill",
|
||||
"description": "Brief, intent-focused description",
|
||||
"tags": ["routing", "quota"],
|
||||
"examples": ["Sample natural-language invocation"]
|
||||
}
|
||||
```
|
||||
|
||||
4. **编写测试：** `tests/unit/a2a-<your-skill>.test.ts`。覆盖正常路径和错误路径。
|
||||
|
||||
5. 在本文档的`可用技能`表格中**记录**新技能。
|
||||
|
||||
---
|
||||
|
||||
## 任务 TTL
|
||||
|
||||
任务在 `ttlMinutes`（默认 5 分钟）后过期——可在 `src/lib/a2a/taskManager.ts:82` 的 `A2ATaskManager` 构造函数中配置。如需自定义，可复刻 `A2ATaskManager` 的实例化并传入不同值（例如 `new A2ATaskManager(15)` 设置 15 分钟 TTL）。后台定时器每 60 秒清理一次过期任务。
|
||||
|
||||
---
|
||||
|
||||
## 任务生命周期
|
||||
|
||||
```
|
||||
submitted → working → completed
|
||||
@@ -137,25 +227,26 @@ submitted → working → completed
|
||||
→ cancelled
|
||||
```
|
||||
|
||||
- Tasks expire after 5 minutes (configurable)
|
||||
- Terminal states: `completed`, `failed`, `cancelled`
|
||||
- Event log tracks every state transition
|
||||
- 任务默认在 5 分钟后过期（参见[任务 TTL](#task-ttl)）
|
||||
- 终态：`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 |
|
||||
| Code | 含义 |
|
||||
| :--- | :--- |
|
||||
| -32700 | 解析错误（JSON 无效） |
|
||||
| -32600 | 无效请求 / 未授权 |
|
||||
| -32601 | 方法或技能未找到 |
|
||||
| -32602 | 参数无效 |
|
||||
| -32603 | 内部错误 |
|
||||
| -32000 | A2A 端点已禁用 |
|
||||
|
||||
---
|
||||
|
||||
## Integration Examples
|
||||
## 集成示例
|
||||
|
||||
### Python (requests)
|
||||
|
||||
|
||||
@@ -1,87 +1,403 @@
|
||||
# OmniRoute MCP Server Documentation (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/MCP-SERVER.md) · 🇸🇦 [ar](../../ar/docs/MCP-SERVER.md) · 🇧🇬 [bg](../../bg/docs/MCP-SERVER.md) · 🇧🇩 [bn](../../bn/docs/MCP-SERVER.md) · 🇨🇿 [cs](../../cs/docs/MCP-SERVER.md) · 🇩🇰 [da](../../da/docs/MCP-SERVER.md) · 🇩🇪 [de](../../de/docs/MCP-SERVER.md) · 🇪🇸 [es](../../es/docs/MCP-SERVER.md) · 🇮🇷 [fa](../../fa/docs/MCP-SERVER.md) · 🇫🇮 [fi](../../fi/docs/MCP-SERVER.md) · 🇫🇷 [fr](../../fr/docs/MCP-SERVER.md) · 🇮🇳 [gu](../../gu/docs/MCP-SERVER.md) · 🇮🇱 [he](../../he/docs/MCP-SERVER.md) · 🇮🇳 [hi](../../hi/docs/MCP-SERVER.md) · 🇭🇺 [hu](../../hu/docs/MCP-SERVER.md) · 🇮🇩 [id](../../id/docs/MCP-SERVER.md) · 🇮🇹 [it](../../it/docs/MCP-SERVER.md) · 🇯🇵 [ja](../../ja/docs/MCP-SERVER.md) · 🇰🇷 [ko](../../ko/docs/MCP-SERVER.md) · 🇮🇳 [mr](../../mr/docs/MCP-SERVER.md) · 🇲🇾 [ms](../../ms/docs/MCP-SERVER.md) · 🇳🇱 [nl](../../nl/docs/MCP-SERVER.md) · 🇳🇴 [no](../../no/docs/MCP-SERVER.md) · 🇵🇭 [phi](../../phi/docs/MCP-SERVER.md) · 🇵🇱 [pl](../../pl/docs/MCP-SERVER.md) · 🇵🇹 [pt](../../pt/docs/MCP-SERVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/MCP-SERVER.md) · 🇷🇴 [ro](../../ro/docs/MCP-SERVER.md) · 🇷🇺 [ru](../../ru/docs/MCP-SERVER.md) · 🇸🇰 [sk](../../sk/docs/MCP-SERVER.md) · 🇸🇪 [sv](../../sv/docs/MCP-SERVER.md) · 🇰🇪 [sw](../../sw/docs/MCP-SERVER.md) · 🇮🇳 [ta](../../ta/docs/MCP-SERVER.md) · 🇮🇳 [te](../../te/docs/MCP-SERVER.md) · 🇹🇭 [th](../../th/docs/MCP-SERVER.md) · 🇹🇷 [tr](../../tr/docs/MCP-SERVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/MCP-SERVER.md) · 🇵🇰 [ur](../../ur/docs/MCP-SERVER.md) · 🇻🇳 [vi](../../vi/docs/MCP-SERVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/MCP-SERVER.md)
|
||||
|
||||
---
|
||||
title: "OmniRoute MCP Server Documentation"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
> Model Context Protocol server with 16 intelligent tools
|
||||
# OmniRoute MCP 服务器文档
|
||||
|
||||
> 包含 94 个工具的 MCP 服务器，覆盖路由、缓存、压缩、记忆、技能、代理、连接池和上下文源操作。
|
||||
>
|
||||
> 数据来源：`open-sse/mcp-server/schemas/tools.ts`（34 个基础工具）+ `memoryTools.ts`（3）+ `skillTools.ts`（4）+ `agentSkillTools.ts`（3）+ `poolTools.ts`（6）+ `gamificationTools.ts`（8）+ `pluginTools.ts`（8）+ `notionTools.ts`（6）+ `obsidianTools.ts`（22）= **94**（`TOTAL_MCP_TOOL_COUNT`）。工具注册和权限域绑定逻辑见 `open-sse/mcp-server/server.ts`。
|
||||
|
||||
|
||||
|
||||
> 来源：[diagrams/mcp-tools-94.mmd](../diagrams/mcp-tools-94.mmd)（通过 `npm run docs:render-diagrams` 重新生成）。
|
||||
|
||||
## 安装
|
||||
|
||||
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 streamable 传输（端口 20130）
|
||||
omniroute --dev # MCP 自动在 /mcp 端点启动
|
||||
```
|
||||
|
||||
## IDE Configuration
|
||||
## 传输
|
||||
|
||||
See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
|
||||
MCP 服务器提供三种传输方式，均基于同一个 `createMcpServer()` 工厂：
|
||||
|
||||
| 传输 | 位置 | 适用场景 |
|
||||
| :----------------- | :------------------------------------------- | :---------------------------------------------------- |
|
||||
| `stdio` | `open-sse/mcp-server/server.ts` | IDE 集成（Claude Desktop、Cursor 等） |
|
||||
| `sse` | `POST/GET /api/mcp/sse`，通过 `httpTransport` | 需要事件流的浏览器/代理客户端 |
|
||||
| `streamable-http` | `POST/GET/DELETE /api/mcp/stream` | 多会话 HTTP 客户端（`mcp-session-id` 头） |
|
||||
|
||||
当前生效的 HTTP 传输（`sse` 或 `streamable-http`）由 `mcpTransport` 设置选择。切换传输方式会关闭另一传输上的现有会话。
|
||||
|
||||
### 远程访问（manage 权限域绕过）
|
||||
|
||||
`/api/mcp/*` 位于 LOCAL_ONLY 层级（`src/server/authz/routeGuard.ts`）——默认只有 loopback 主机（`localhost`、`127.0.0.1`、`::1`）可以访问。自 v3.8.2 起，非 loopback 客户端如果提供携带 `manage` 权限域的 `Authorization: Bearer <api-key>`，即可连接。这是通过隧道、反向代理或公网主机名访问远程 MCP 服务器的唯一方式。
|
||||
|
||||
```bash
|
||||
# 授予 manage 权限域：打开仪表盘 API Keys 页面，为该 Key 开启
|
||||
# "Management Access" 开关，或在创建时 POST scopes:["manage"]。
|
||||
|
||||
# 然后从远程 MCP 客户端连接：
|
||||
curl -i \
|
||||
-H "Host: your-public-host.example" \
|
||||
-H "Authorization: Bearer sk-…" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Accept: application/json, text/event-stream" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0"}}}' \
|
||||
https://your-public-host.example/api/mcp/stream
|
||||
```
|
||||
|
||||
非 manage 的 Key（或缺少 Bearer）返回 `403 LOCAL_ONLY`。同级前缀 `/api/cli-tools/runtime/*` 禁止被绕过——详见[路由守卫层级 — manage 权限域豁免](../security/ROUTE_GUARD_TIERS.md#manage-scope-carve-out)。
|
||||
|
||||
## IDE 配置
|
||||
|
||||
Claude Desktop、Cursor、Cline 及其他兼容 MCP 客户端的配置，参见 [MCP 客户端配置](../guides/SETUP_GUIDE.md#mcp-client-configuration)。
|
||||
|
||||
---
|
||||
|
||||
## Essential Tools (8)
|
||||
## 核心工具（8）— 阶段 1
|
||||
|
||||
| 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` | `read:health` | 运行时间、内存、熔断器、速率限制、缓存统计 |
|
||||
| `omniroute_list_combos` | `read:combos` | 所有已配置 Combo 及其策略（可选指标） |
|
||||
| `omniroute_get_combo_metrics` | `read:combos` | 指定 Combo 的性能指标 |
|
||||
| `omniroute_switch_combo` | `write:combos` | 激活或停用 Combo |
|
||||
| `omniroute_check_quota` | `read:quota` | 已用/总配额、剩余百分比、重置时间、Token 健康状态 |
|
||||
| `omniroute_route_request` | `execute:completions` | 通过 OmniRoute 路由发送聊天补全请求 |
|
||||
| `omniroute_cost_report` | `read:usage` | 按时间段（会话/天/周/月）的费用报告 |
|
||||
| `omniroute_list_models_catalog` | `read:models` | 完整模型目录，包含能力、状态、定价 |
|
||||
|
||||
## Advanced Tools (8)
|
||||
## 阶段 1 — 搜索
|
||||
|
||||
| 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 via a real upstream request |
|
||||
| `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_web_search` | `execute:search` | 通过 OmniRoute 搜索网关进行 Web 搜索（Serper/Brave/Perplexity/Exa/Tavily/Google PSE/Linkup/SearchAPI/SearXNG），支持容灾 |
|
||||
|
||||
## Authentication
|
||||
## 高级工具（11）— 阶段 2
|
||||
|
||||
MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :----------------------------------- | :------------------------------------- | :------------------------------------------------------------------- |
|
||||
| `omniroute_simulate_route` | `read:health`、`read:combos` | 包含容灾树的演习路由仿真 |
|
||||
| `omniroute_set_budget_guard` | `write:budget` | 会话预算，支持降级/阻断/告警动作 |
|
||||
| `omniroute_set_routing_strategy` | `write:combos` | 在运行时更新 Combo 策略（priority/weighted/auto 等） |
|
||||
| `omniroute_set_resilience_profile` | `write:resilience` | 应用 `aggressive` / `balanced` / `conservative` 容灾预设文件 |
|
||||
| `omniroute_test_combo` | `execute:completions`、`read:combos` | 使用真实上游调用对 Combo 中的每个服务商进行实时测试 |
|
||||
| `omniroute_get_provider_metrics` | `read:health` | 每个服务商的指标，含 p50/p95/p99 延迟和熔断器状态 |
|
||||
| `omniroute_best_combo_for_task` | `read:combos`、`read:health` | 根据任务类型推荐 Combo，含预算/延迟约束 |
|
||||
| `omniroute_explain_route` | `read:health`、`read:usage` | 解释某次请求的路由决策依据（评分因子 + 容灾路径） |
|
||||
| `omniroute_get_session_snapshot` | `read:usage` | 完整会话快照：费用、Token、热门模型/服务商、错误、预算守卫 |
|
||||
| `omniroute_db_health_check` | `read:health`、`write:resilience` | 诊断（并可自动修复）数据库异常，如损坏的 Combo 引用/孤儿行 |
|
||||
| `omniroute_sync_pricing` | `pricing:write` | 从外部源（LiteLLM）同步定价数据；支持 `dryRun` |
|
||||
|
||||
| Scope | Tools |
|
||||
| :------------- | :----------------------------------------------- |
|
||||
| `read:health` | get_health, get_provider_metrics |
|
||||
| `read:combos` | list_combos, get_combo_metrics |
|
||||
| `write:combos` | switch_combo |
|
||||
| `read:quota` | check_quota |
|
||||
| `write:route` | route_request, simulate_route, test_combo |
|
||||
| `read:usage` | cost_report, get_session_snapshot, explain_route |
|
||||
| `write:config` | set_budget_guard, set_resilience_profile |
|
||||
| `read:models` | list_models_catalog, best_combo_for_task |
|
||||
## 缓存工具（2）
|
||||
|
||||
## Audit Logging
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :------------------------ | :-------------- | :--------------------------------------- |
|
||||
| `omniroute_cache_stats` | `read:cache` | 语义缓存、提示缓存和幂等性统计 |
|
||||
| `omniroute_cache_flush` | `write:cache` | 全局或按签名/模型刷新缓存 |
|
||||
|
||||
Every tool call is logged to `mcp_tool_audit` with:
|
||||
## 压缩工具（5）
|
||||
|
||||
- Tool name, arguments, result
|
||||
- Duration (ms), success/failure
|
||||
- API key hash, timestamp
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :------------------------------------ | :-------------------- | :--------------------------------------------------------------------------------------------------------- |
|
||||
| `omniroute_compression_status` | `read:compression` | 压缩设置、分析摘要和缓存感知统计（含 `analytics.mcpDescriptionCompression` 元数据） |
|
||||
| `omniroute_compression_configure` | `write:compression` | 配置压缩模式、阈值、目标比例、系统提示保留、MCP 描述压缩开关 |
|
||||
| `omniroute_set_compression_engine` | `write:compression` | 选择活跃引擎（off/caveman/rtk/stacked）及 Caveman/RTK 强度 |
|
||||
| `omniroute_list_compression_combos` | `read:compression` | 列出已命名的压缩 Combo 及其引擎流水线 |
|
||||
| `omniroute_compression_combo_stats` | `read:compression` | 按压缩 Combo 和引擎分组的分析数据 |
|
||||
|
||||
## Files
|
||||
`omniroute_compression_status` 将 MCP 描述压缩数据单独报告在 `analytics.mcpDescriptionCompression` 下。这些值是 MCP 可列表描述（`tools`、`prompts`、`resources` 和 `resourceTemplates`）的元数据大小估算；不是服务商用量记录，标记为 `source: "mcp_metadata_estimate"`。
|
||||
|
||||
| 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 |
|
||||
### MCP 无障碍树过滤器（v3.8.0）
|
||||
|
||||
除了上述 5 个压缩工具，OmniRoute 还包含一个执行后过滤器，在 MCP 浏览器/无障碍工具的**工具结果**返回给代理之前对其进行压缩。此过滤器本身不是工具——它对任何包含冗长的无障碍树或浏览器快照文本（≥2000 字符）的工具结果透明运行。
|
||||
|
||||
关键行为：
|
||||
|
||||
- 将 ≥30 个连续重复的同类行折叠为头部 + 尾部摘要
|
||||
- 保留 Playwright/计算机操作所需的 `[ref=eXX]` 锚点
|
||||
- 对超大文本（>50,000 字符）进行硬截断，附导航提示
|
||||
- 预期节省：浏览器快照载荷 **60–80%**
|
||||
|
||||
配置：全局设置中的 `compression.mcpAccessibility`（迁移 056）。
|
||||
实现：`open-sse/services/compression/engines/mcpAccessibility/`。
|
||||
完整文档：[压缩引擎 — MCP 无障碍树过滤器](../compression/COMPRESSION_ENGINES.md#mcp-accessibility-tree-filter)。
|
||||
|
||||
这些工具背后的运行时压缩模型参见[压缩引擎](../compression/COMPRESSION_ENGINES.md)和 [RTK 压缩](../compression/RTK_COMPRESSION.md)。
|
||||
|
||||
## 1Proxy 工具（3）
|
||||
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :---------------------------- | :--------------- | :--------------------------------------------------------------------------------- |
|
||||
| `omniroute_oneproxy_fetch` | `read:proxies` | 从 1proxy 市场获取免费代理（支持协议/国家/质量/数量筛选） |
|
||||
| `omniroute_oneproxy_rotate` | `read:proxies` | 按策略获取下一个可用代理（`random` / `quality` / `sequential`） |
|
||||
| `omniroute_oneproxy_stats` | `read:proxies` | 连接池统计、同步状态、按协议和国家分布 |
|
||||
|
||||
## 记忆工具（3）
|
||||
|
||||
定义在 `open-sse/mcp-server/tools/memoryTools.ts`。认证/权限域通过标准 MCP 权限域管线强制执行。
|
||||
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :-------------------------- | :--------------- | :------------------------------------------------------------------------- |
|
||||
| `omniroute_memory_search` | `read:memory` | 按查询/类型/API Key 搜索记忆，强制 Token 预算 |
|
||||
| `omniroute_memory_add` | `write:memory` | 添加新的记忆条目（`factual` / `episodic` / `procedural` / `semantic`） |
|
||||
| `omniroute_memory_clear` | `write:memory` | 清除某 API Key 的记忆，可选按类型或 `olderThan` 时间戳过滤 |
|
||||
|
||||
## 技能工具（4）
|
||||
|
||||
定义在 `open-sse/mcp-server/tools/skillTools.ts`。由 `src/lib/skills/registry` + `src/lib/skills/executor` 支撑。
|
||||
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :------------------------------ | :----------------- | :----------------------------------------------------------------------- |
|
||||
| `omniroute_skills_list` | `read:skills` | 列出已注册的技能，支持按 API Key、名称或启用状态过滤 |
|
||||
| `omniroute_skills_enable` | `write:skills` | 按 ID 启用或禁用某个技能 |
|
||||
| `omniroute_skills_execute` | `execute:skills` | 以给定输入执行技能，返回执行记录 |
|
||||
| `omniroute_skills_executions` | `read:skills` | 列出近期的技能执行历史 |
|
||||
|
||||
## Notion 上下文源（6）
|
||||
|
||||
定义在 `open-sse/mcp-server/tools/notionTools.ts`。Token 通过 `src/lib/db/notion.ts` 存储在 `key_value` 表。REST 客户端见 `src/lib/notion/api.ts`。设置 API 见 `src/app/api/settings/notion/route.ts`。仪表盘界面见 `src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx`。
|
||||
|
||||
从端点仪表盘的**上下文源**标签页配置 Notion 集成 Token，或通过 REST API：
|
||||
|
||||
```bash
|
||||
# 设置 Token
|
||||
curl -X POST http://localhost:20128/api/settings/notion \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "ntn_..."}'
|
||||
|
||||
# 检查状态
|
||||
curl http://localhost:20128/api/settings/notion
|
||||
|
||||
# 断开连接
|
||||
curl -X DELETE http://localhost:20128/api/settings/notion
|
||||
```
|
||||
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :----------------------------- | :--------------- | :--------------------------------------------------- |
|
||||
| `notion_search` | `read:notion` | 跨所有页面和数据库的全文搜索 |
|
||||
| `notion_get_page` | `read:notion` | 按 ID 获取页面及其属性 |
|
||||
| `notion_list_block_children` | `read:notion` | 列出页面或块的子块 |
|
||||
| `notion_query_database` | `read:notion` | 查询数据库，支持筛选、排序和分页 |
|
||||
| `notion_get_database` | `read:notion` | 按 ID 获取数据库 Schema |
|
||||
| `notion_append_blocks` | `write:notion` | 向父块追加子块（每次请求最多 100 个） |
|
||||
|
||||
## 代理技能目录工具（3）
|
||||
|
||||
定义在 `open-sse/mcp-server/tools/agentSkillTools.ts`。由 `src/lib/agentSkills/catalog` 支撑。这些工具将 42 条目代理技能文档目录暴露给 MCP 客户端和外部代理。权限域：`read:catalog`。
|
||||
|
||||
| 工具 | 权限域 | 描述 |
|
||||
| :---------------------------------- | :--------------- | :-------------------------------------------------------------------------------------------------------- |
|
||||
| `omniroute_agent_skills_list` | `read:catalog` | 列出全部 42 个代理技能，支持可选的 `category`（api\|cli）和 `area` 过滤；返回元数据 + 覆盖情况 |
|
||||
| `omniroute_agent_skills_get` | `read:catalog` | 按规范 `id` 获取单个技能的完整元数据 + SKILL.md 内容 |
|
||||
| `omniroute_agent_skills_coverage` | `read:catalog` | 覆盖统计：22 个 API 技能和 20 个 CLI 技能中，哪些在文件系统上有 SKILL.md 文件 vs 目录总计 |
|
||||
|
||||
完整目录及外部代理如何消费，参见 [AGENT-SKILLS.md](./AGENT-SKILLS.md)。
|
||||
|
||||
## 关联框架（v3.8.0）
|
||||
|
||||
上述 MCP 工具清单（94 个工具 = 34 核心 + 3 记忆 + 4 技能 + 3 代理技能 + 6 连接池 + 8 游戏化 + 8 插件 + 6 Notion + 22 Obsidian）有意限定于运行时路由/缓存/压缩/记忆/技能/代理/上下文源操作。两个相邻框架随 MCP 服务器在 v3.8.0 中一同发布，并有独立的文档：
|
||||
|
||||
### 云代理
|
||||
|
||||
云代理是外部 AI 编程代理（codex-cloud、devin、jules），通过与大语言模型服务商相同的连接模型接入 OmniRoute。它们通过自己的 REST 接口（`/api/v1/agents/*`）暴露，**不**属于 MCP 工具目录——调用云代理不消耗 MCP 权限域。
|
||||
|
||||
- 实现：`src/lib/cloudAgent/`（`registry.ts`、`agents/codex-cloud.ts`、`agents/devin.ts`、`agents/jules.ts`）。
|
||||
- 生命周期：`createTask`、`getStatus`、`approvePlan`、`sendMessage`、`listSources`。
|
||||
- 文档：[docs/frameworks/CLOUD_AGENT.md](./CLOUD_AGENT.md)。
|
||||
|
||||
### 安全护栏
|
||||
|
||||
安全护栏是前置/后置执行过滤器（vision-bridge、pii-masker、prompt-injection），在聊天管线内部生效。它们在请求到达 MCP 工具/路由层之前运行，并向审计管线输出结构化的违规记录；它们不作为 MCP 工具调用。
|
||||
|
||||
- 实现：`src/lib/guardrails/`。
|
||||
- 文档：[docs/security/GUARDRAILS.md](../security/GUARDRAILS.md)。
|
||||
|
||||
调试被阻的 MCP 调用时，检查 MCP 审计日志（`scope_denied:*` 条目）和安全护栏审计追踪——请求可能在到达 MCP 权限域执行层**之前**就被安全护栏拒绝了。
|
||||
|
||||
---
|
||||
|
||||
## REST API 端点
|
||||
|
||||
| 端点 | 方法 | 描述 | 认证 |
|
||||
| :----------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------- | :------------------------- |
|
||||
| `/api/mcp/status` | `GET` | 服务器状态：心跳、HTTP 传输状态、审计活动摘要 | 管理（session/admin） |
|
||||
| `/api/mcp/tools` | `GET` | 工具目录（名称、描述、权限域、阶段、源端点） | 管理 |
|
||||
| `/api/mcp/sse` | `GET` / `POST` | SSE 传输端点（由 `mcpEnabled` + `mcpTransport === "sse"` 控制） | API Key + 权限域 |
|
||||
| `/api/mcp/stream` | `POST`/`GET`/`DELETE` | Streamable HTTP 传输（使用 `mcp-session-id` 头；`DELETE` 结束会话） | API Key + 权限域 |
|
||||
| `/api/mcp/audit` | `GET` | 来自 `mcp_tool_audit` 的审计日志条目（过滤参数：`limit`、`offset`、`tool`、`success`、`apiKeyId`） | 管理 |
|
||||
| `/api/mcp/audit/stats` | `GET` | 聚合审计统计（`totalCalls`、`successRate`、`avgDurationMs`、top 工具） | 管理 |
|
||||
|
||||
源文件：`src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts`。
|
||||
|
||||
SSE 和 Streamable HTTP 两种传输均在设置中启用 MCP 服务器（`mcpEnabled`）并选择了适当的 `mcpTransport` 后才会放行。如果配置了错误的传输，路由返回 HTTP 400 并提示切换设置。
|
||||
|
||||
---
|
||||
|
||||
## 认证与权限域
|
||||
|
||||
MCP 工具通过 API Key 权限域进行认证。权限域执行集中在 `open-sse/mcp-server/scopeEnforcement.ts`。每个工具需要特定的权限域：
|
||||
|
||||
| 权限域 | 工具 |
|
||||
| :---------------------- | :------------------------------------------------------------------------------------------------------------------ |
|
||||
| `read:health` | `get_health`、`get_provider_metrics`、`simulate_route`、`explain_route`、`best_combo_for_task`、`db_health_check` |
|
||||
| `read:combos` | `list_combos`、`get_combo_metrics`、`simulate_route`、`best_combo_for_task`、`test_combo` |
|
||||
| `write:combos` | `switch_combo`、`set_routing_strategy` |
|
||||
| `read:quota` | `check_quota` |
|
||||
| `read:usage` | `cost_report`、`get_session_snapshot`、`explain_route` |
|
||||
| `read:models` | `list_models_catalog` |
|
||||
| `execute:completions` | `route_request`、`test_combo` |
|
||||
| `execute:search` | `web_search` |
|
||||
| `write:budget` | `set_budget_guard` |
|
||||
| `write:resilience` | `set_resilience_profile`、`db_health_check` |
|
||||
| `pricing:write` | `sync_pricing` |
|
||||
| `read:cache` | `cache_stats` |
|
||||
| `write:cache` | `cache_flush` |
|
||||
| `read:compression` | `compression_status`、`list_compression_combos`、`compression_combo_stats` |
|
||||
| `write:compression` | `compression_configure`、`set_compression_engine` |
|
||||
| `read:proxies` | `oneproxy_fetch`、`oneproxy_rotate`、`oneproxy_stats` |
|
||||
| `read:notion` | `notion_search`、`notion_list_databases`、`notion_get_database`、`notion_query_database`、`notion_read` |
|
||||
| `write:notion` | `notion_append_blocks` |
|
||||
| `read:memory` | `memory_search` |
|
||||
| `write:memory` | `memory_add`、`memory_clear` |
|
||||
| `read:skills` | `skills_list`、`skills_executions` |
|
||||
| `write:skills` | `skills_enable` |
|
||||
| `execute:skills` | `skills_execute` |
|
||||
| `read:catalog` | `agent_skills_list`、`agent_skills_get`、`agent_skills_coverage` |
|
||||
|
||||
支持通配符权限域：`read:*` 授予全部读权限域，`*` 授予完整访问。
|
||||
|
||||
---
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 默认值 | 用途 |
|
||||
| :---------------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `OMNIROUTE_BASE_URL` | `http://localhost:20128` | MCP 服务器调用 OmniRoute 内部 API 时使用的基础 URL |
|
||||
| `OMNIROUTE_API_KEY` | （空） | 转发为 `Authorization: Bearer` 给内部 API 调用的 API Key |
|
||||
| `OMNIROUTE_MCP_ENFORCE_SCOPES` | `false`（仅 `"true"` 启用） | 启用后，缺少权限域时拒绝工具调用并在审计日志中记录 `scope_denied:<reason>` |
|
||||
| `OMNIROUTE_MCP_SCOPES` | （空） | 逗号分隔的权限域白名单，视为默认"可用"（当调用方不提供自身权限域时使用） |
|
||||
| `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS` | （不设置 = 开启） | 设置为 `0/false/off/no` 时，禁用注册时的 MCP 描述压缩 |
|
||||
| `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION` | （不设置 = 开启） | 与上文相同开关的别名 |
|
||||
| `MCP_TOOL_DENY` | （不设置 = 无过滤） | 逗号分隔的工具名称，从 `tools/list` 中移除（工具基数精简 — 见下文） |
|
||||
| `MCP_TOOL_ALLOW` | （不设置 = 无过滤） | 逗号分隔的工具名称，仅保留这些工具（白名单模式 — 见下文） |
|
||||
| `DATA_DIR` | `~/.omniroute` | 心跳文件写入 `${DATA_DIR}/runtime/mcp-heartbeat.json` |
|
||||
|
||||
---
|
||||
|
||||
## 描述压缩
|
||||
|
||||
MCP 工具、提示和资源注册表可以在注册/列表时压缩描述，以减少暴露给客户端的元数据体积（进而降低提示上下文成本）。实现位于 `open-sse/mcp-server/descriptionCompressor.ts`，在 `createMcpServer()` 中通过 `compressMcpRegistryMetadata` 接入 MCP 服务器。
|
||||
|
||||
- 压缩在描述文本上运行，使用 Caveman 规则集（`getRulesForContext("all", "full")`），并进行保留块提取（代码段、围栏块等），因此结构化内容不会被修改。
|
||||
- 按部署级别通过 `key_value` 设置表中的 `compression.mcpDescriptionCompressionEnabled` 值切换开关（默认：启用）——在界面中暴露为 **Analytics → MCP description compression**。
|
||||
- 按进程级别通过 `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS=false` 或 `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION=false` 切换。
|
||||
- 实时统计通过 `omniroute_compression_status` 在 `analytics.mcpDescriptionCompression` 下呈现，标记为 `source: "mcp_metadata_estimate"` 以区别于实际服务商用量记录。
|
||||
|
||||
---
|
||||
|
||||
## 工具基数精简（F4.3）
|
||||
|
||||
描述压缩缩小了每个工具的元数据；**工具基数精简**更进一步，减少了_宣布_的工具数量。在 `tools/list` 清单中宣布更少的工具，可降低客户端模型为工具目录支付的每请求 Token 成本（"第 5 层"压缩）。实现为 `open-sse/mcp-server/toolCardinality.ts` 中的纯无状态过滤器（`reduceToolManifest`），接入 `createMcpServer()`（`open-sse/mcp-server/server.ts`）中的注册循环。
|
||||
|
||||
**需主动开启，默认关闭。** 仅当设置了两个环境变量中的至少一个时，过滤器才会运行；两者都不设置时，全部 94 个工具按原样宣布。
|
||||
|
||||
| 变量 | 模式 |
|
||||
| :----------------- | :-------------------------------------------------------------------------------- |
|
||||
| `MCP_TOOL_DENY` | 黑名单 — 逗号分隔的工具名称，始终从 `tools/list` 中移除 |
|
||||
| `MCP_TOOL_ALLOW` | 白名单 — 逗号分隔的工具名称；仅保留这些，其余全部移除 |
|
||||
|
||||
`deny` 优先于 `allow`。名称以逗号分隔，去除首尾空格，空条目被忽略。示例：
|
||||
|
||||
```bash
|
||||
# 从目录中移除两个工具
|
||||
MCP_TOOL_DENY="omniroute_get_health,omniroute_list_combos" omniroute --mcp
|
||||
|
||||
# 仅宣布路由 + 配额工具（白名单模式）
|
||||
MCP_TOOL_ALLOW="omniroute_route_request,omniroute_check_quota" omniroute --mcp
|
||||
```
|
||||
|
||||
**已过滤工具的移除方式：** 注册始终成功；被配置淘汰的工具会在 MCP SDK 句柄上执行 `.disable()`，因此它不会出现在 `tools/list` 中，但连接保持完整（干净启用/禁用，无需重新注册）。配置解析器为 `readMcpToolProfileFromEnv(process.env)`，当两个变量均为空时返回 `null`（无过滤）。
|
||||
|
||||
`reduceToolManifest` 背后的更丰富 `ToolProfile` 结构也支持权限域交集过滤（`allowScopes`，含 `read:*` 风格的通配符匹配）和确定性 `maxTools` 上限，但这两个参数在注册时需要完整清单，目前**不**通过环境变量暴露（`tools/list` 级别的 hook 是后续跟进项）。`estimateManifestTokens()` 可用于比较精简前后的清单 Token 成本。
|
||||
|
||||
---
|
||||
|
||||
## 运行时心跳
|
||||
|
||||
stdio 传输每 5 秒将存活状态持久化到 `${DATA_DIR}/runtime/mcp-heartbeat.json`。仪表盘（`/api/mcp/status`）读取此文件加上 PID 存活来推导 `online`。HTTP 传输则通过进程内 `getMcpHttpStatus()` 报告状态（无需写入文件）。
|
||||
|
||||
心跳快照包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"pid": 12345,
|
||||
"startedAt": "2026-05-13T12:34:56.000Z",
|
||||
"lastHeartbeatAt": "2026-05-13T12:35:01.000Z",
|
||||
"version": "1.8.1",
|
||||
"transport": "stdio",
|
||||
"scopesEnforced": false,
|
||||
"allowedScopes": [],
|
||||
"toolCount": 43
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 审计日志
|
||||
|
||||
每次工具调用通过 `open-sse/mcp-server/audit.ts` 记录到 SQLite `mcp_tool_audit` 表：
|
||||
|
||||
- 工具名称、参数（根据每个工具的 `auditLevel` 进行哈希/截断）、结果
|
||||
- 耗时（毫秒）、成功/失败标记、错误消息（如适用）
|
||||
- API Key 哈希、时间戳
|
||||
- 权限域拒绝记录为 `scope_denied:<reason>`，附带缺失的权限域列表
|
||||
|
||||
使用仪表盘或 `/api/mcp/audit` 和 `/api/mcp/audit/stats` REST 端点检查近期调用。
|
||||
|
||||
---
|
||||
|
||||
## 文件
|
||||
|
||||
| 文件 | 用途 |
|
||||
| :------------------------------------------------------------------------- | :--------------------------------------------------------------- |
|
||||
| `open-sse/mcp-server/server.ts` | MCP 服务器工厂、stdio 入口点、按权限域的工具注册 |
|
||||
| `open-sse/mcp-server/httpTransport.ts` | SSE + Streamable HTTP 传输（会话管理） |
|
||||
| `open-sse/mcp-server/scopeEnforcement.ts` | 工具权限域评估和调用方解析 |
|
||||
| `open-sse/mcp-server/audit.ts` | 工具调用审计日志（`mcp_tool_audit`） |
|
||||
| `open-sse/mcp-server/runtimeHeartbeat.ts` | stdio 心跳写入器（`mcp-heartbeat.json`） |
|
||||
| `open-sse/mcp-server/descriptionCompressor.ts` | 工具/提示/资源注册表的描述压缩 |
|
||||
| `open-sse/mcp-server/schemas/tools.ts` | Zod Schema + 工具注册表（`MCP_TOOLS`，34 条目） |
|
||||
| `open-sse/mcp-server/tools/advancedTools.ts` | 阶段 2 + 缓存 + 1proxy 工具处理器 |
|
||||
| `open-sse/mcp-server/tools/compressionTools.ts` | 压缩工具处理器 |
|
||||
| `open-sse/mcp-server/tools/memoryTools.ts` | 记忆工具定义（3 工具） |
|
||||
| `open-sse/mcp-server/tools/skillTools.ts` | 技能工具定义（4 工具） |
|
||||
| `open-sse/mcp-server/tools/notionTools.ts` | Notion 上下文源工具定义（6 工具） |
|
||||
| `open-sse/mcp-server/tools/gamificationTools.ts` | 游戏化工具定义（8 工具） |
|
||||
| `open-sse/mcp-server/tools/pluginTools.ts` | 插件注册和管理工具（8 工具） |
|
||||
| `src/app/api/mcp/status/route.ts` | `/api/mcp/status` 端点 |
|
||||
| `src/app/api/mcp/tools/route.ts` | `/api/mcp/tools` 端点 |
|
||||
| `src/app/api/mcp/sse/route.ts` | `/api/mcp/sse` SSE 传输路由 |
|
||||
| `src/app/api/mcp/stream/route.ts` | `/api/mcp/stream` Streamable HTTP 传输路由 |
|
||||
| `src/app/api/mcp/audit/route.ts` | `/api/mcp/audit` 审计日志查询 |
|
||||
| `src/app/api/mcp/audit/stats/route.ts` | `/api/mcp/audit/stats` 聚合审计指标 |
|
||||
| `src/lib/notion/api.ts` | Notion REST API 客户端（重试、超时、错误分类） |
|
||||
| `src/lib/db/notion.ts` | Notion Token 持久化（`key_value` 表） |
|
||||
| `src/app/api/settings/notion/route.ts` | Notion 设置 API（GET/POST/DELETE） |
|
||||
| `src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx` | Notion Token 管理界面 |
|
||||
| `tests/unit/notion-api.test.ts` | Notion API 客户端测试（7） |
|
||||
| `tests/unit/notion-tools.test.ts` | Notion 工具权限域执行测试（10） |
|
||||
| `tests/unit/db/notion.test.mjs` | Notion 数据库模块测试（3） |
|
||||
|
||||
@@ -1,269 +1,328 @@
|
||||
# OmniRoute — Dashboard Features Gallery (中文 (简体))
|
||||
---
|
||||
title: "OmniRoute — 控制台功能画廊"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇧🇩 [bn](../../bn/docs/FEATURES.md) · 🇨🇿 [cs](../../cs/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇮🇷 [fa](../../fa/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇮🇳 [gu](../../gu/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇮🇳 [hi](../../hi/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇮🇳 [mr](../../mr/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇰🇪 [sw](../../sw/docs/FEATURES.md) · 🇮🇳 [ta](../../ta/docs/FEATURES.md) · 🇮🇳 [te](../../te/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇹🇷 [tr](../../tr/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇵🇰 [ur](../../ur/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md)
|
||||
# OmniRoute — 控制台功能画廊
|
||||
|
||||
🌐 **Main README translations:** 🇺🇸 [English](../../guides/FEATURES.md) | 🇧🇷 [Português (Brasil)](../../i18n/pt-BR/docs/guides/FEATURES.md) | 🇪🇸 [Español](../../i18n/es/docs/guides/FEATURES.md) | 🇫🇷 [Français](../../i18n/fr/docs/guides/FEATURES.md) | 🇮🇹 [Italiano](../../i18n/it/docs/guides/FEATURES.md) | 🇷🇺 [Русский](../../i18n/ru/docs/guides/FEATURES.md) | 🇨🇳 [中文 (简体)](../../i18n/zh-CN/docs/guides/FEATURES.md) | 🇩🇪 [Deutsch](../../i18n/de/docs/guides/FEATURES.md) | 🇮🇳 [हिन्दी](../../i18n/in/docs/guides/FEATURES.md) | 🇹🇭 [ไทย](../../i18n/th/docs/guides/FEATURES.md) | 🇺🇦 [Українська](../../i18n/uk-UA/docs/guides/FEATURES.md) | 🇸🇦 [العربية](../../i18n/ar/docs/guides/FEATURES.md) | 🇯🇵 [日本語](../../i18n/ja/docs/guides/FEATURES.md) | 🇻🇳 [Tiếng Việt](../../i18n/vi/docs/guides/FEATURES.md) | 🇧🇬 [Български](../../i18n/bg/docs/guides/FEATURES.md) | 🇩🇰 [Dansk](../../i18n/da/docs/guides/FEATURES.md) | 🇫🇮 [Suomi](../../i18n/fi/docs/guides/FEATURES.md) | 🇮🇱 [עברית](../../i18n/he/docs/guides/FEATURES.md) | 🇭🇺 [Magyar](../../i18n/hu/docs/guides/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../../i18n/id/docs/guides/FEATURES.md) | 🇰🇷 [한국어](../../i18n/ko/docs/guides/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../../i18n/ms/docs/guides/FEATURES.md) | 🇳🇱 [Nederlands](../../i18n/nl/docs/guides/FEATURES.md) | 🇳🇴 [Norsk](../../i18n/no/docs/guides/FEATURES.md) | 🇵🇹 [Português (Portugal)](../../i18n/pt/docs/guides/FEATURES.md) | 🇷🇴 [Română](../../i18n/ro/docs/guides/FEATURES.md) | 🇵🇱 [Polski](../../i18n/pl/docs/guides/FEATURES.md) | 🇸🇰 [Slovenčina](../../i18n/sk/docs/guides/FEATURES.md) | 🇸🇪 [Svenska](../../i18n/sv/docs/guides/FEATURES.md) | 🇵🇭 [Filipino](../../i18n/phi/docs/guides/FEATURES.md) | 🇨🇿 [Čeština](../../i18n/cs/docs/guides/FEATURES.md)
|
||||
|
||||
OmniRoute 控制台各功能区的可视化指南。
|
||||
|
||||
> 📅 **最近更新：** 2026-06-28 — **v3.8.40**
|
||||
|
||||
---
|
||||
|
||||
Visual guide to every section of the OmniRoute dashboard.
|
||||
## ✨ v3.8.0 亮点
|
||||
|
||||
v3.7.x → v3.8.0 版本周期引入了零配置自动路由、新的服务商、OAuth 流程、更深度的容灾能力，以及大幅增强的 CLI 体验。以下是主要功能——完整细节见下文及链接的规范文档。
|
||||
|
||||
- 🤖 **Auto Combo / 零配置自动路由** — 使用 `auto/coding`、`auto/fast`、`auto/cheap`、`auto/offline`、`auto/smart`、`auto/lkgp` 前缀。背后是 9 因子评分引擎和 4 个精选**模式包**（快速交付、成本优先、质量优先、离线友好）
|
||||
- 🆕 **Command Code 服务商** (#2199) — 一线注册，含模型目录和配额追踪
|
||||
- 🆕 **Z.AI 服务商** — 新增免费层服务商，带配额标签
|
||||
- 🎬 **KIE 媒体扩展** — 扩展目录，包含视频生成模型
|
||||
- 🔐 **Windsurf + Devin CLI OAuth 流程** (#2168) — 端到端浏览器登录
|
||||
- 🆓 **9 个新的免费服务商** — LLM7、Lepton、Kluster、UncloseAI、BazaarLink、Completions、Enally、FreeTheAi、Command Code
|
||||
- 🎯 **Manifest 感知层级路由 W1–W4** — 服务商 Manifest 驱动加权层级选择
|
||||
- 🎨 **Cursor 完全兼容 OpenAI 格式** — 工具调用、流式传输、会话管理端到端打通
|
||||
- 📊 **Cursor Pro 计划用量** — 配额和周期数据在服务商限制控制台中展示
|
||||
- ⚡ **服务层级细分 / Codex 快速层分析** — 按层级的用量可见性
|
||||
- 📌 **按会话粘性路由** — Codex 会话在轮次之间固定到同一账户
|
||||
- 🔊 **Inworld TTS 增强** — 语音目录、流式传输和延迟改进
|
||||
- 🔑 **Kiro 无头认证** — 通过本地 `kiro-cli` SQLite 存储登录，无需浏览器
|
||||
- 📉 **DeepSeek 配额和限制监控** — 通过控制台暴露每日/每月用量
|
||||
- 🔄 **Reset 感知路由策略** — Combo 现在优先选择配额窗口最早重置的账户
|
||||
- ⏱️ **`fallbackDelayMs`** 和**动态工具限制检测** — 更精细的容灾时机 + 按服务商的工具数限制
|
||||
- 🔧 **后台模式降级（Responses API）** — 当上游不支持后台轮询时，以结构化警告降级到同步模式
|
||||
- 🚦 **按服务商的 429 分类** + `useUpstream429BreakerHints` 开关 — 利用上游速率限制提示实现更精细的熔断行为
|
||||
- 🩺 **模型冷却控制台** — 观察每个模型的锁定状态，并通过 UI 手动恢复
|
||||
- 🔒 **MITM 动态 Linux 证书检测** — 跨 Debian/Ubuntu、Fedora/RHEL、Arch 等发行版
|
||||
- 💻 **CLI 增强套件** — 20+ 命令，包括 `omniroute providers`、`omniroute combos`、`omniroute doctor`、`omniroute setup`
|
||||
- 🔍 **Qdrant 嵌入模型发现** — 自动探测向量存储模型
|
||||
- 🔑 **带 `manage` 权限域的 API Key / Bearer Key** — 通过 API 以编程方式执行管理操作
|
||||
- 🏥 **Combo 目标健康分析** + **结构化 Combo 构建器** — 按目标健康分析 + UI 构建器，用于组装 `(服务商, 模型, 连接)` 步骤
|
||||
- 🤝 **GitLab Duo OAuth 服务商** — 使用 GitLab 凭据登录
|
||||
- 🧠 **推理回放缓存** — 混合内存 + SQLite 持久化推理痕迹
|
||||
|
||||
📚 **相关文档：** [技能框架](../frameworks/SKILLS.md) · [记忆系统](../frameworks/MEMORY.md) · [云代理](../frameworks/CLOUD_AGENT.md) · [Webhook](../frameworks/WEBHOOKS.md) · [推理回放缓存](../routing/REASONING_REPLAY.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Providers
|
||||
## 🔌 服务商
|
||||
|
||||
管理 AI 服务商连接：OAuth 服务商（Claude Code、Codex）、API Key 服务商（Groq、DeepSeek、OpenRouter）和免费服务商（Qoder、Qwen、Kiro）。Kiro 账户包含积分余额追踪——剩余积分、总额度和续期日期可在 控制台 → 用量 中查看。
|
||||
|
||||
|
||||
OpenRouter 连接可以在 高级设置 中存储每个连接的 `preset`。设置后，除非客户端请求已提供自己的 `preset`，否则 OmniRoute 会将其作为 OpenRouter 的顶层请求字段发送，例如 `"preset": "email-copywriter"`。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Combos
|
||||
## 🎨 Combo
|
||||
|
||||
Create model routing combos with 13 strategies: priority, weighted, round-robin, random, least-used, cost-optimized, strict-random, auto, fill-first, p2c, lkgp, context-optimized, and **context-relay**. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
|
||||
使用 17 种策略创建模型路由 Combo：priority、weighted、fill-first、round-robin、p2c（power-of-two-choices）、random、least-used、cost-optimized、reset-aware、reset-window、headroom、strict-random、auto、lkgp（last-known-good-provider）、context-optimized、context-relay，以及 **fusion**（并行扇出到一组模型，然后通过评判模型合成一个答案）。每个 Combo 将多个模型串联起来，具备自动容灾能力，并包含快速模板和就绪检查。
|
||||
|
||||
Recent combo improvements:
|
||||
最近的 Combo 改进：
|
||||
|
||||
- **Structured combo builder** — create each step by selecting provider, model, and exact account/connection
|
||||
- **Repeated provider support** — reuse the same provider many times in one combo as long as the `(provider, model, connection)` tuple is unique
|
||||
- **Combo target health** — analytics and health surfaces now distinguish individual combo targets/steps instead of collapsing everything into model strings
|
||||
- **Composite tier ordering** — `defaultTier -> fallbackTier` now influences runtime execution/fallback order for top-level combo steps
|
||||
- **结构化 Combo 构建器** — 通过选择服务商、模型和具体账户/连接来创建每个步骤
|
||||
- **重复服务商支持** — 同一个服务商可以在一个 Combo 中多次使用，只要 `(服务商, 模型, 连接)` 元组唯一即可
|
||||
- **Combo 目标健康** — 分析和健康数据面现在区分单独的 Combo 目标/步骤，而非将所有内容折叠为模型字符串
|
||||
- **复合层级排序** — `defaultTier -> fallbackTier` 现在影响顶层 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, provider circuit breaker states, active quota-monitored sessions, and combo target health.
|
||||
实时监控：运行时长、内存、版本、延迟百分位数（p50/p95/p99）、缓存统计、服务商熔断器状态、活跃的配额监控会话，以及 Combo 目标健康。
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Translator Playground
|
||||
## 🔧 翻译器 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+)_
|
||||
## 🎮 模型 Playground _(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:
|
||||
全面的设置面板，包含 **7 个选项卡**：
|
||||
|
||||
- **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, **Context Relay** handoff threshold and summary model configuration
|
||||
- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
|
||||
- **通用** — 系统存储、备份管理（导出/导入数据库）
|
||||
- **外观** — 主题选择器（深色/浅色/系统）、配色主题预设和自定义颜色、健康日志可见性、侧边栏项目和分组分隔线可见性控制、端点隧道可见性控制
|
||||
- **AI** — AI 助手功能、默认路由预设（Auto Combo `auto/coding`、`auto/fast`、`auto/cheap`、`auto/smart`）、推理回放缓存，以及技能/记忆开关
|
||||
- **安全** — API 端点保护、自定义服务商屏蔽、IP 过滤、会话信息
|
||||
- **路由** — 模型别名、后台任务降级、Manifest 感知层级路由（W1–W4）、`fallbackDelayMs`、按会话粘性路由
|
||||
- **容灾** — 速率限制持久化、熔断器调优、自动禁用被禁账户、服务商过期监控、**Context Relay** 交接阈值和摘要模型配置、按服务商的 429 分类与 `useUpstream429BreakerHints` 开关、模型冷却
|
||||
- **高级** — 配置覆盖、配置审计追踪、容灾降级模式、Responses API 的后台模式降级
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 CLI Tools
|
||||
## 🔧 CLI 工具
|
||||
|
||||
One-click configuration for AI coding tools: Claude Code, Codex 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、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 17 built-in agents (Codex, Claude, Goose, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp, **Windsurf**, **Devin CLI**, **Kimi Coding**, **Command Code**) with:
|
||||
CLI 智能体发现与管理控制台。以网格形式展示 17 个内置智能体（Codex、Claude、Goose、OpenClaw、Aider、OpenCode、Cline、Qwen Code、ForgeCode、Amazon Q、Open Interpreter、Cursor CLI、Warp、**Windsurf**、**Devin CLI**、**Kimi Coding**、**Command Code**），提供：
|
||||
|
||||
- **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
|
||||
- **安装状态** — 已安装 / 未找到，含版本检测
|
||||
- **协议 Badge** — stdio、HTTP 等
|
||||
- **自定义智能体** — 通过表单注册任意 CLI 工具（名称、二进制文件、版本命令、启动参数）
|
||||
- **CLI 指纹匹配** — 按服务商切换，匹配原生 CLI 请求签名，降低封禁风险同时保留代理 IP
|
||||
- **OAuth 支持的智能体** — Windsurf 与 Devin CLI 现使用浏览器 OAuth 流程进行认证（v3.8.0+）
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Context Relay _(v3.5.5+)_
|
||||
|
||||
A combo strategy that preserves session continuity when account rotation happens mid-conversation. Before the active account is exhausted, OmniRoute generates a structured handoff summary in the background. After the next request resolves to a different account, the summary is injected as a system message so the new account continues with full context.
|
||||
一种 Combo 策略，在会话中途发生账户轮换时保持连续性。活跃账户配额耗尽前，OmniRoute 在后台生成结构化的交接摘要。后续请求切换到其他账户后，摘要以系统消息形式注入，使新账户以完整上下文继续服务。
|
||||
|
||||
Configurable via combo-level or global settings:
|
||||
支持 Combo 级别或全局配置：
|
||||
|
||||
- **Handoff Threshold** — Quota usage percentage that triggers summary generation (default 85%)
|
||||
- **Max Messages For Summary** — How much recent history to condense
|
||||
- **Summary Model** — Optional override model for generating the handoff summary
|
||||
- **交接阈值** — 触发摘要生成的配额使用百分比（默认 85%）
|
||||
- **最近消息摘要数量限制** — 压缩多少最近的历史记录
|
||||
- **摘要模型** — 可选，用于生成交接摘要的覆盖模型
|
||||
|
||||
Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md).
|
||||
目前支持 Codex 账户轮换。详见 [Context Relay 文档](../architecture/ARCHITECTURE.md)。
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Proxy Hardening _(v3.5.5+)_
|
||||
## 🗜️ 提示压缩 _(v3.7.9+)_
|
||||
|
||||
Comprehensive proxy configuration enforcement across the entire request pipeline:
|
||||
Context & Cache 现在为 Caveman、RTK 和压缩 Combo 提供专属页面：
|
||||
|
||||
- **Token Health Check** — Background OAuth refresh now resolves proxy config per connection, preventing failures in proxy-required environments
|
||||
- **API Key Validation** — Provider key validation (`POST /api/providers/validate`) routes through `runWithProxyContext`, honoring provider-level and global proxy settings
|
||||
- **undici Dispatcher Fix** — Proxy dispatchers use undici's own fetch implementation instead of Node's built-in fetch, resolving `invalid onRequestStart method` errors on Node.js 22
|
||||
- **Node.js Version Detection** — Login page proactively detects incompatible Node.js versions (24+) and displays a warning banner with instructions to use Node 22 LTS
|
||||
- **Caveman** — 语言感知规则包、预览、输出模式控制和用量分析
|
||||
- **RTK** — 命令感知压缩，适用 shell、git、测试、构建、包管理、Docker、基础设施、JSON 和堆栈跟踪输出
|
||||
- **压缩 Combo** — 命名管道，如 `rtk -> caveman`，可分配给路由 Combo；默认级联压缩在两个引擎同时生效时达到 **~89%** 平均节省率和 **78–95%** 合格上下文节省率
|
||||
- **原始输出恢复** — 可选 RTK 脱敏原始输出指针，用于调试压缩失败
|
||||
|
||||
详见 [压缩指南](../compression/COMPRESSION_GUIDE.md)、[RTK 压缩](../compression/RTK_COMPRESSION.md) 和 [压缩引擎](../compression/COMPRESSION_ENGINES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 📧 Email Privacy Masking _(v3.5.6+)_
|
||||
## 🛡️ 代理加固 _(v3.5.5+)_
|
||||
|
||||
OAuth account emails are now masked in the provider dashboard (e.g. `di*****@g****.com`) to prevent accidental exposure when sharing screenshots or recording demos. The full email address remains accessible via hover tooltip (`title` attribute).
|
||||
全请求链路的代理配置强制执行：
|
||||
|
||||
- **Token 健康检查** — 后台 OAuth 刷新现按连接解析代理配置，避免代理必需环境下认证失败
|
||||
- **API Key 校验** — 服务商 Key 校验（`POST /api/providers/validate`）通过 `runWithProxyContext` 路由，遵循服务商级和全局代理设置
|
||||
- **undici Dispatcher 修复** — 代理 Dispatcher 使用 undici 自带的 fetch 实现替代 Node 内置 fetch，解决 Node.js 22 上的 `invalid onRequestStart method` 错误
|
||||
- **Node.js 版本检测** — 登录页主动检测不兼容的 Node.js 版本（24+），并显示警告横幅，引导用户使用 Node 22 LTS
|
||||
|
||||
---
|
||||
|
||||
## 👁️ Model Visibility Toggle _(v3.5.6+)_
|
||||
## 📧 邮箱隐私脱敏 _(v3.5.6+)_
|
||||
|
||||
The provider page model list now includes:
|
||||
|
||||
- **Real-time search/filter bar** — Quickly find specific models
|
||||
- **Per-model visibility toggle** (👁 icon) — Hidden models are grayed out and excluded from the `/v1/models` catalog
|
||||
- **Active-count badge** (`N/M active`) — Shows at a glance how many models are enabled vs total
|
||||
OAuth 账户邮箱默认脱敏显示（例如 `di*****@g****.com`），防止截图或录屏时意外暴露。使用 设置 → 外观 → 账户邮箱可见性 可在服务商、Combo、日志、配额和 Playground 页中全局显示或隐藏完整邮箱。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 OAuth Env Repair _(v3.6.1+)_
|
||||
## 👁️ 模型可见性切换 _(v3.5.6+)_
|
||||
|
||||
One-click "Repair env" action for OAuth providers that restores missing environment variables and fixes broken auth state. Accessible from `Dashboard → Providers → [OAuth Provider] → Repair env`. Automatically detects and repairs:
|
||||
服务商页面模型列表新增：
|
||||
|
||||
- Missing OAuth client credentials
|
||||
- Corrupted env file entries
|
||||
- Backup path sanitization
|
||||
- **实时搜索/过滤栏** — 快速查找特定模型
|
||||
- **单个模型可见性切换**（👁 图标）— 隐藏的模型置灰并从 `/v1/models` 目录中排除
|
||||
- **活跃数 Badge**（`N/M active`）— 一目了然地显示启用模型数 vs 总数
|
||||
|
||||
---
|
||||
|
||||
## 🗑️ Uninstall / Full Uninstall _(v3.6.2+)_
|
||||
## 🔧 OAuth 环境修复 _(v3.6.1+)_
|
||||
|
||||
Clean removal scripts for all installation methods:
|
||||
OAuth 服务商的一键"环境修复"操作，恢复缺失的环境变量并修复损坏的认证状态。入口：`控制台 → 服务商 → [OAuth 服务商] → 环境修复`。自动检测并修复：
|
||||
|
||||
| Command | Action |
|
||||
| ------------------------ | ----------------------------------------------------------------------------------- |
|
||||
| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
|
||||
| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
|
||||
- 缺失的 OAuth 客户端凭据
|
||||
- 损坏的 env 文件条目
|
||||
- 备份路径清理
|
||||
|
||||
---
|
||||
|
||||
## 🖼️ Media _(v2.0.3+)_
|
||||
## 🗑️ 卸载 / 完全卸载 _(v3.6.2+)_
|
||||
|
||||
Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
|
||||
面向所有安装方式的清理卸载脚本：
|
||||
|
||||
| 命令 | 操作 |
|
||||
| ------------------------ | ------------------------------------------------------------------- |
|
||||
| `npm run uninstall` | 移除系统应用，但**保留数据库和配置**在 `~/.omniroute`。 |
|
||||
| `npm run uninstall:full` | 移除应用，并永久**清除所有配置、密钥和数据库**。 |
|
||||
|
||||
---
|
||||
|
||||
## 📝 Request Logs
|
||||
## 🖼️ 媒体 _(v2.0.3+)_
|
||||
|
||||
Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
|
||||
|
||||
|
||||
从控制台生成图像、视频和音乐。支持 OpenAI、xAI、Together、Hyperbolic、SD WebUI、ComfyUI、AnimateDiff、Stable Audio Open 和 MusicGen。
|
||||
|
||||
---
|
||||
|
||||
## 🌐 API Endpoint
|
||||
## 📝 请求日志
|
||||
|
||||
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 Key 筛选。显示状态码、Token 用量、延迟和响应详情。
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔑 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 端点及其能力概览：Chat Completions、Responses API、Embeddings、Image Generation、Reranking、Audio Transcription、Text-to-Speech、Moderations 和已注册的 API Key。支持 Cloudflare Quick Tunnel、Tailscale Funnel、ngrok Tunnel 和云代理，实现远程访问。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📋 Audit Log
|
||||
## 🔑 API Key 管理
|
||||
|
||||
Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
|
||||
创建、划分权限域和撤销 API Key。每个 Key 可限制到特定模型/服务商，支持完全访问或只读权限。可视化密钥管理，附带用量追踪。
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ 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.
|
||||
管理操作追踪，支持按操作类型、执行人、目标、IP 地址和时间戳筛选。完整的安全事件历史。
|
||||
|
||||
Key features:
|
||||
---
|
||||
|
||||
- Server readiness polling (no blank screen on cold start)
|
||||
- System tray with port management
|
||||
## 🖥️ 桌面应用
|
||||
|
||||
面向 Windows、macOS 和 Linux 的原生 Electron 桌面应用。以独立应用程序形式运行 OmniRoute，集成系统托盘、离线支持、自动更新和一键安装。
|
||||
|
||||
关键功能：
|
||||
|
||||
- 服务器就绪轮询（冷启动不白屏）
|
||||
- 带端口管理的系统托盘
|
||||
- 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+)
|
||||
- **Graceful shutdown** — Electron `before-quit` shuts down Next.js cleanly, preventing SQLite WAL database locks (v3.6.2+)
|
||||
- 单实例锁
|
||||
- 重启时自动更新
|
||||
- 平台自适应 UI（macOS 红绿灯、Windows/Linux 默认标题栏）
|
||||
- 加固的 Electron 构建打包 — 独立包中符号链接的 `node_modules` 在打包前被检测并拒绝，防止对构建机器的运行时依赖（v2.5.5+）
|
||||
- **优雅关闭** — Electron `before-quit` 干净关闭 Next.js，防止 SQLite WAL 数据库锁定（v3.6.2+）
|
||||
|
||||
📖 See [`electron/README.md`](../electron/README.md) for full documentation.
|
||||
📖 详见 [`electron/README.md`](../../../electron/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 🌐 V1 WebSocket Bridge _(v3.6.6+)_
|
||||
|
||||
OmniRoute now supports **OpenAI-compatible WebSocket clients** via the `/v1/ws` upgrade endpoint. The custom `scripts/v1-ws-bridge.mjs` server wraps Next.js and upgrades WS connections to full bidirectional streaming sessions. Authentication uses the same API key or session cookie as HTTP requests.
|
||||
OmniRoute 现通过 `/v1/ws` 升级端点支持 OpenAI 兼容的 WebSocket 客户端。自定义 `scripts/dev/v1-ws-bridge.mjs` 服务器包装 Next.js，将 WS 连接升级为全双工流式会话。认证使用与 HTTP 请求相同的 API Key 或会话 Cookie。
|
||||
|
||||
Key behaviours:
|
||||
关键行为：
|
||||
|
||||
- WS upgrade validated by `src/lib/ws/handshake.ts` before the connection is established
|
||||
- Streams terminated cleanly on session close or upstream error
|
||||
- Works alongside the existing HTTP+SSE streaming path simultaneously
|
||||
- WS 升级在连接建立前经过 `src/lib/ws/handshake.ts` 校验
|
||||
- 会话关闭或上游错误时干净终止流
|
||||
- 与现有 HTTP+SSE 流式路径同时运行
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Sync Tokens & Config Bundle _(v3.6.6+)_
|
||||
## 🔑 同步 Token 与配置包 _(v3.6.6+)_
|
||||
|
||||
Multi-device and external operator access is now possible via **scoped sync tokens**:
|
||||
通过限域同步 Token 实现多设备和外部运维访问：
|
||||
|
||||
- **`POST /api/sync/tokens`** — Issue a new sync token (scoped, with optional expiry)
|
||||
- **`DELETE /api/sync/tokens/:id`** — Revoke a token
|
||||
- **`GET /api/sync/bundle`** — Download a versioned, ETag-keyed JSON snapshot of all non-sensitive settings (passwords redacted)
|
||||
- **`POST /api/sync/tokens`** — 签发新的同步 Token（限域，可选过期时间）
|
||||
- **`DELETE /api/sync/tokens/:id`** — 撤销 Token
|
||||
- **`GET /api/sync/bundle`** — 下载带版本号、ETag 键控的 JSON 快照，包含所有非敏感设置（密码已脱敏）
|
||||
|
||||
The config bundle is built by `src/lib/sync/bundle.ts`. Consumers compare the `ETag` response header to detect changes without re-downloading the full payload.
|
||||
配置包由 `src/lib/sync/bundle.ts` 构建。消费者比较 `ETag` 响应头即可检测变更，无需重新下载完整载荷。
|
||||
|
||||
---
|
||||
|
||||
## 🧠 GLM Thinking Preset _(v3.6.6+)_
|
||||
## 🧠 GLM Thinking 预设 _(v3.6.6+)_
|
||||
|
||||
**GLM Thinking (`glmt`)** is now a registered first-class provider: 65 536 max output tokens, 24 576 thinking budget, 900 s default timeout, Claude-compatible API format, and shared usage sync with the GLM family.
|
||||
**GLM Thinking（`glmt`）** 现作为一线服务商注册：最大输出 Token 65,536、Thinking 预算 24,576、默认超时 900 秒、Claude 兼容 API 格式，并与 GLM 系列共享用量同步。
|
||||
|
||||
**Hybrid token counting** also lands in v3.6.6: when a Claude-compatible provider exposes `/messages/count_tokens`, OmniRoute calls it before large requests with graceful estimation fallback.
|
||||
**混合 Token 计数**也在 v3.6.6 中落地：当 Claude 兼容的服务商暴露 `/messages/count_tokens` 端点时，OmniRoute 在大请求前调用该端点，并提供优雅的估算回退。
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Safe Outbound Fetch & SSRF Guard _(v3.6.6+)_
|
||||
## 🛡️ 安全外发请求与 SSRF 防护 _(v3.6.6+)_
|
||||
|
||||
All provider validation and model discovery calls now go through a two-layer outbound guard:
|
||||
所有服务商校验和模型发现调用现经过两层外发防护：
|
||||
|
||||
1. **URL guard** (`src/shared/network/outboundUrlGuard.ts`) — Blocks private/loopback/link-local IP ranges before the socket is opened.
|
||||
2. **Safe fetch wrapper** (`src/shared/network/safeOutboundFetch.ts`) — Applies the URL guard, normalises timeouts, and retries transient errors with exponential backoff.
|
||||
1. **URL guard**（`src/shared/network/outboundUrlGuard.ts`）— 在套接字打开前拦截 private/loopback/link-local IP 范围。
|
||||
2. **Safe fetch wrapper**（`src/shared/network/safeOutboundFetch.ts`）— 应用 URL guard、标准化超时并以指数退避重试瞬时错误。
|
||||
|
||||
Guard violations surface as HTTP 422 (`URL_GUARD_BLOCKED`) and are written to the compliance audit log via `providerAudit.ts`.
|
||||
防护违规通过 HTTP 422（`URL_GUARD_BLOCKED`）暴露，并写入合规审计日志（`providerAudit.ts`）。
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Cooldown-Aware Retries _(v3.6.6+)_
|
||||
## 🔄 冷却感知重试 _(v3.6.6+)_
|
||||
|
||||
Chat requests now **automatically retry** when an upstream provider returns a model-scoped cooldown. Configurable via `REQUEST_RETRY` (default: 2) and `MAX_RETRY_INTERVAL_SEC` (default: 30 s). Rate-limit header learning improved across `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`, and `Retry-After` — per-model cooldown state is visible in the Resilience dashboard.
|
||||
当上游服务商返回模型级冷却时，聊天请求现自动重试。通过 `REQUEST_RETRY`（默认：2）和 `MAX_RETRY_INTERVAL_SEC`（默认：30 秒）配置。速率限制头学习能力在 `x-ratelimit-reset-requests`、`x-ratelimit-reset-tokens` 和 `Retry-After` 间改进——每个模型的冷却状态在容灾控制台中可见。
|
||||
|
||||
---
|
||||
|
||||
## 📋 Compliance Audit v2 _(v3.6.6+)_
|
||||
## 📋 合规审计 v2 _(v3.6.6+)_
|
||||
|
||||
The audit log has been expanded with cursor-based pagination, request context enrichment (request ID, user agent, IP), structured auth events, provider CRUD events with diff context, and SSRF-blocked validation logging. New events emitted by `src/lib/compliance/providerAudit.ts`.
|
||||
审计日志新增基于游标的分页、请求上下文增强（请求 ID、User-Agent、IP）、结构化认证事件、带差异上下文的服务商 CRUD 事件，以及 SSRF 拦截日志。新事件由 `src/lib/compliance/providerAudit.ts` 触发。
|
||||
|
||||
@@ -1,90 +1,143 @@
|
||||
# i18n — Internationalization Guide (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/I18N.md) · 🇸🇦 [ar](../../ar/docs/I18N.md) · 🇧🇬 [bg](../../bg/docs/I18N.md) · 🇧🇩 [bn](../../bn/docs/I18N.md) · 🇨🇿 [cs](../../cs/docs/I18N.md) · 🇩🇰 [da](../../da/docs/I18N.md) · 🇩🇪 [de](../../de/docs/I18N.md) · 🇪🇸 [es](../../es/docs/I18N.md) · 🇮🇷 [fa](../../fa/docs/I18N.md) · 🇫🇮 [fi](../../fi/docs/I18N.md) · 🇫🇷 [fr](../../fr/docs/I18N.md) · 🇮🇳 [gu](../../gu/docs/I18N.md) · 🇮🇱 [he](../../he/docs/I18N.md) · 🇮🇳 [hi](../../hi/docs/I18N.md) · 🇭🇺 [hu](../../hu/docs/I18N.md) · 🇮🇩 [id](../../id/docs/I18N.md) · 🇮🇹 [it](../../it/docs/I18N.md) · 🇯🇵 [ja](../../ja/docs/I18N.md) · 🇰🇷 [ko](../../ko/docs/I18N.md) · 🇮🇳 [mr](../../mr/docs/I18N.md) · 🇲🇾 [ms](../../ms/docs/I18N.md) · 🇳🇱 [nl](../../nl/docs/I18N.md) · 🇳🇴 [no](../../no/docs/I18N.md) · 🇵🇭 [phi](../../phi/docs/I18N.md) · 🇵🇱 [pl](../../pl/docs/I18N.md) · 🇵🇹 [pt](../../pt/docs/I18N.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/I18N.md) · 🇷🇴 [ro](../../ro/docs/I18N.md) · 🇷🇺 [ru](../../ru/docs/I18N.md) · 🇸🇰 [sk](../../sk/docs/I18N.md) · 🇸🇪 [sv](../../sv/docs/I18N.md) · 🇰🇪 [sw](../../sw/docs/I18N.md) · 🇮🇳 [ta](../../ta/docs/I18N.md) · 🇮🇳 [te](../../te/docs/I18N.md) · 🇹🇭 [th](../../th/docs/I18N.md) · 🇹🇷 [tr](../../tr/docs/I18N.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/I18N.md) · 🇵🇰 [ur](../../ur/docs/I18N.md) · 🇻🇳 [vi](../../vi/docs/I18N.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/I18N.md)
|
||||
|
||||
---
|
||||
title: "i18n — 国际化指南"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
OmniRoute supports **30 languages** with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew.
|
||||
# i18n — 国际化指南
|
||||
|
||||
## Quick Reference
|
||||
OmniRoute 支持 **42 种语言**，提供完整的控制台 UI 翻译、文档翻译，以及阿拉伯语和希伯来语的 RTL 支持。
|
||||
|
||||
| Task | Command |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------- |
|
||||
| Generate translations | `node scripts/i18n/generate-multilang.mjs messages` |
|
||||
| Translate docs (LLM) | `python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |
|
||||
| Validate a locale | `python3 scripts/validate_translation.py quick -l cs` |
|
||||
| Check code keys | `python3 scripts/check_translations.py` |
|
||||
| Generate QA report | `node scripts/i18n/generate-qa-checklist.mjs` |
|
||||
| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs` |
|
||||
🌐 **Languages:** 🇺🇸 [English](../../guides/I18N.md) | 🇧🇷 [Português (Brasil)](../../i18n/pt-BR/docs/guides/I18N.md) | 🇪🇸 [Español](../../i18n/es/docs/guides/I18N.md) | 🇫🇷 [Français](../../i18n/fr/docs/guides/I18N.md) | 🇩🇪 [Deutsch](../../i18n/de/docs/guides/I18N.md) | 🇮🇹 [Italiano](../../i18n/it/docs/guides/I18N.md) | 🇷🇺 [Русский](../../i18n/ru/docs/guides/I18N.md) | 🇨🇳 [中文 (简体)](../../i18n/zh-CN/docs/guides/I18N.md) | 🇯🇵 [日本語](../../i18n/ja/docs/guides/I18N.md) | 🇰🇷 [한국어](../../i18n/ko/docs/guides/I18N.md) | 🇸🇦 [العربية](../../i18n/ar/docs/guides/I18N.md) | 🇮🇳 [हिन्दी](../../i18n/hi/docs/guides/I18N.md) | 🇹🇭 [ไทย](../../i18n/th/docs/guides/I18N.md) | 🇹🇷 [Türkçe](../../i18n/tr/docs/guides/I18N.md) | 🇺🇦 [Українська](../../i18n/uk-UA/docs/guides/I18N.md) | 🇻🇳 [Tiếng Việt](../../i18n/vi/docs/guides/I18N.md) | 🇧🇬 [Български](../../i18n/bg/docs/guides/I18N.md) | 🇩🇰 [Dansk](../../i18n/da/docs/guides/I18N.md) | 🇫🇮 [Suomi](../../i18n/fi/docs/guides/I18N.md) | 🇮🇱 [עברית](../../i18n/he/docs/guides/I18N.md) | 🇭🇺 [Magyar](../../i18n/hu/docs/guides/I18N.md) | 🇮🇩 [Bahasa Indonesia](../../i18n/id/docs/guides/I18N.md) | 🇲🇾 [Bahasa Melayu](../../i18n/ms/docs/guides/I18N.md) | 🇳🇱 [Nederlands](../../i18n/nl/docs/guides/I18N.md) | 🇳🇴 [Norsk](../../i18n/no/docs/guides/I18N.md) | 🇵🇹 [Português (Portugal)](../../i18n/pt/docs/guides/I18N.md) | 🇷🇴 [Română](../../i18n/ro/docs/guides/I18N.md) | 🇵🇱 [Polski](../../i18n/pl/docs/guides/I18N.md) | 🇸🇰 [Slovenčina](../../i18n/sk/docs/guides/I18N.md) | 🇸🇪 [Svenska](../../i18n/sv/docs/guides/I18N.md) | 🇵🇭 [Filipino](../../i18n/phi/docs/guides/I18N.md) | 🇨🇿 [Čeština](../../i18n/cs/docs/guides/I18N.md)
|
||||
|
||||
## 翻译管道（推荐 — v3.8.0）
|
||||
|
||||
OmniRoute 使用基于哈希的增量文档翻译器，后端为 OpenAI 兼容的 LLM 端点（通常通过 OmniRoute Cloud 使用 `cx/gpt-5.4-mini`）：
|
||||
|
||||
```bash
|
||||
# 运行翻译（增量模式 — 仅处理变更的源文件）
|
||||
npm run i18n:run
|
||||
|
||||
# 限定到单个语言/地区
|
||||
npm run i18n:run -- --locale=pt-BR
|
||||
|
||||
# 指定文件（逗号分隔，仓库相对路径）
|
||||
npm run i18n:run -- --files=CLAUDE.md,docs/architecture/ARCHITECTURE.md
|
||||
|
||||
# 强制全部重新翻译（开销大）
|
||||
npm run i18n:run -- --force
|
||||
|
||||
# 预览将执行的操作（无 API 调用，无文件写入）
|
||||
npm run i18n:run:dry
|
||||
|
||||
# CI 门禁 — 状态漂移时返回非零退出码
|
||||
npm run i18n:check
|
||||
```
|
||||
|
||||
**唯一数据源。** `config/i18n.json` 列出每个语言/地区（UI + 文档），以及 RTL 集合和 `docsExcluded` 代码。运行时配置 `src/i18n/config.ts` 是该 JSON 的薄适配层。
|
||||
|
||||
**后端。** 通过 env 配置（在 `.env` 中设置，永不提交）：
|
||||
|
||||
| 变量 | 用途 |
|
||||
| ----------------------------------- | -------------------------------------------- |
|
||||
| `OMNIROUTE_TRANSLATION_API_URL` | OpenAI 兼容的 base URL，例如 `…/v1` |
|
||||
| `OMNIROUTE_TRANSLATION_API_KEY` | bearer Token（日志中脱敏） |
|
||||
| `OMNIROUTE_TRANSLATION_MODEL` | 模型 ID，例如 `cx/gpt-5.4-mini` |
|
||||
| `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | 可选，默认 `60000` |
|
||||
| `OMNIROUTE_TRANSLATION_CONCURRENCY` | 可选，默认 `4` |
|
||||
|
||||
**状态追踪。** `.i18n-state.json`（已提交）按源文件 + 按语言/地区维护 SHA-256 哈希。漂移检测自动且确定性 — `i18n:check` 无需 API 调用。
|
||||
|
||||
**输出格式。** 每个翻译文件包含顶层 `# <标题> (<本地名称>)` 行、`🌐 Languages: …` 条、`---` 分隔符和翻译后的正文。此布局与 `scripts/check/check-docs-sync.mjs` 已为 `llm.txt` 和 `CHANGELOG.md` 镜像强制执行的格式一致。
|
||||
|
||||
### 旧版脚本（已弃用）
|
||||
|
||||
较旧的 Python 脚本（`scripts/i18n/i18n_autotranslate.py`）和基于 Google Translate 的生成器（`scripts/i18n/generate-multilang.mjs`）仍然存在但带有弃用标头，将在 v3.10 中移除。`generate-multilang.mjs` 的 `messages` 和 `readme` 模式（UI 字符串 + 根 README 变体）尚未被新管道处理，仍在使用。
|
||||
|
||||
## 快速参考
|
||||
|
||||
| 任务 | 命令 |
|
||||
| ------------------------ | ----------------------------------------------------------- |
|
||||
| 翻译文档（LLM） | `npm run i18n:run`（推荐 — 增量，基于哈希） |
|
||||
| 翻译 UI 字符串 | `node scripts/i18n/generate-multilang.mjs messages` |
|
||||
| 检查翻译漂移 | `npm run i18n:check` |
|
||||
| 校验一个语言/地区 | `python3 scripts/i18n/validate_translation.py quick -l cs` |
|
||||
| 检查代码中的 Key | `python3 scripts/i18n/check_translations.py` |
|
||||
| 生成 QA 报告 | `node scripts/i18n/generate-qa-checklist.mjs` |
|
||||
| 视觉 QA（Playwright） | `node scripts/i18n/run-visual-qa.mjs` |
|
||||
|
||||
## 架构
|
||||
|
||||
### Source of Truth
|
||||
|
||||
|
||||
- **UI strings**: `src/i18n/messages/en.json` (English source, ~2800 keys)
|
||||
- **Locale files**: `src/i18n/messages/{locale}.json` (30 translations)
|
||||
- **Framework**: `next-intl` with cookie-based locale resolution
|
||||
- **Config**: `src/i18n/config.ts` — defines all 30 locales, language names, flags
|
||||
> 源文件：[diagrams/i18n-flow.mmd](../../diagrams/i18n-flow.mmd)
|
||||
|
||||
### Runtime Flow
|
||||
### 唯一数据源
|
||||
|
||||
1. User selects language → `NEXT_LOCALE` cookie set
|
||||
2. `src/i18n/request.ts` resolves locale: cookie → `Accept-Language` header → fallback `en`
|
||||
3. Dynamic import loads `messages/{locale}.json`
|
||||
4. Components use `useTranslations("namespace")` and `t("key")`
|
||||
- **UI 字符串**：`src/i18n/messages/en.json`（英文源，约 2800 个 Key）
|
||||
- **语言/地区文件**：`src/i18n/messages/{locale}.json`（30 种翻译）
|
||||
- **框架**：`next-intl`，基于 Cookie 的语言/地区解析
|
||||
- **配置**：`src/i18n/config.ts` — 定义全部 30 个语言/地区、语言名称、旗帜
|
||||
|
||||
### Supported Locales
|
||||
### 运行时流程
|
||||
|
||||
| Code | Language | RTL | Google Translate Code |
|
||||
| ------- | -------------------- | --- | --------------------- |
|
||||
| `ar` | العربية | Yes | `ar` |
|
||||
| `bg` | Български | No | `bg` |
|
||||
| `cs` | Čeština | No | `cs` |
|
||||
| `da` | Dansk | No | `da` |
|
||||
| `de` | Deutsch | No | `de` |
|
||||
| `es` | Español | No | `es` |
|
||||
| `fi` | Suomi | No | `fi` |
|
||||
| `fr` | Français | No | `fr` |
|
||||
| `he` | עברית | Yes | `iw` |
|
||||
| `hi` | हिन्दी | No | `hi` |
|
||||
| `hu` | Magyar | No | `hu` |
|
||||
| `id` | Bahasa Indonesia | No | `id` |
|
||||
| `it` | Italiano | No | `it` |
|
||||
| `ja` | 日本語 | No | `ja` |
|
||||
| `ko` | 한국어 | No | `ko` |
|
||||
| `ms` | Bahasa Melayu | No | `ms` |
|
||||
| `nl` | Nederlands | No | `nl` |
|
||||
| `no` | Norsk | No | `no` |
|
||||
| `phi` | Filipino | No | `tl` |
|
||||
| `pl` | Polski | No | `pl` |
|
||||
| `pt` | Português (Portugal) | No | `pt` |
|
||||
| `pt-BR` | Português (Brasil) | No | `pt` |
|
||||
| `ro` | Română | No | `ro` |
|
||||
| `ru` | Русский | No | `ru` |
|
||||
| `sk` | Slovenčina | No | `sk` |
|
||||
| `sv` | Svenska | No | `sv` |
|
||||
| `th` | ไทย | No | `th` |
|
||||
| `tr` | Türkçe | No | `tr` |
|
||||
| `uk-UA` | Українська | No | `uk` |
|
||||
| `vi` | Tiếng Việt | No | `vi` |
|
||||
| `zh-CN` | 中文 (简体) | No | `zh-CN` |
|
||||
1. 用户选择语言 → 设置 `NEXT_LOCALE` Cookie
|
||||
2. `src/i18n/request.ts` 解析语言/地区：Cookie → `Accept-Language` 头 → 回退 `en`
|
||||
3. 动态 import 加载 `messages/{locale}.json`
|
||||
4. 组件使用 `useTranslations("namespace")` 和 `t("key")`
|
||||
|
||||
## Adding a New Language
|
||||
### 支持的语言/地区
|
||||
|
||||
### 1. Register the Locale
|
||||
| 代码 | 语言 | RTL | Google Translate 代码 |
|
||||
| ------- | ---------------- | --- | --------------------- |
|
||||
| `ar` | العربية | 是 | `ar` |
|
||||
| `bg` | Български | 否 | `bg` |
|
||||
| `cs` | Čeština | 否 | `cs` |
|
||||
| `da` | Dansk | 否 | `da` |
|
||||
| `de` | Deutsch | 否 | `de` |
|
||||
| `es` | Español | 否 | `es` |
|
||||
| `fi` | Suomi | 否 | `fi` |
|
||||
| `fr` | Français | 否 | `fr` |
|
||||
| `he` | עברית | 是 | `iw` |
|
||||
| `hi` | हिन्दी | 否 | `hi` |
|
||||
| `hu` | Magyar | 否 | `hu` |
|
||||
| `id` | Bahasa Indonesia | 否 | `id` |
|
||||
| `it` | Italiano | 否 | `it` |
|
||||
| `ja` | 日本語 | 否 | `ja` |
|
||||
| `ko` | 한국어 | 否 | `ko` |
|
||||
| `ms` | Bahasa Melayu | 否 | `ms` |
|
||||
| `nl` | Nederlands | 否 | `nl` |
|
||||
| `no` | Norsk | 否 | `no` |
|
||||
| `phi` | Filipino | 否 | `tl` |
|
||||
| `pl` | Polski | 否 | `pl` |
|
||||
| `pt` | Português (Portugal) | 否 | `pt` |
|
||||
| `pt-BR` | Português (Brasil) | 否 | `pt` |
|
||||
| `ro` | Română | 否 | `ro` |
|
||||
| `ru` | Русский | 否 | `ru` |
|
||||
| `sk` | Slovenčina | 否 | `sk` |
|
||||
| `sv` | Svenska | 否 | `sv` |
|
||||
| `th` | ไทย | 否 | `th` |
|
||||
| `tr` | Türkçe | 否 | `tr` |
|
||||
| `uk-UA` | Українська | 否 | `uk` |
|
||||
| `vi` | Tiếng Việt | 否 | `vi` |
|
||||
| `zh-CN` | 中文 (简体) | 否 | `zh-CN` |
|
||||
|
||||
Edit `src/i18n/config.ts`:
|
||||
## 添加新语言
|
||||
|
||||
### 1. 注册语言/地区
|
||||
|
||||
编辑 `src/i18n/config.ts`：
|
||||
|
||||
```ts
|
||||
// Add to LOCALES array
|
||||
// 添加到 LOCALES 数组
|
||||
"xx",
|
||||
// Add to LANGUAGES array
|
||||
// 添加到 LANGUAGES 数组
|
||||
{ code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },
|
||||
```
|
||||
|
||||
### 2. Add to Generator
|
||||
### 2. 添加到生成器
|
||||
|
||||
Edit `scripts/i18n/generate-multilang.mjs` — add entry to `LOCALE_SPECS`:
|
||||
编辑 `scripts/i18n/generate-multilang.mjs` — 在 `LOCALE_SPECS` 中添加条目：
|
||||
|
||||
```js
|
||||
{
|
||||
@@ -98,193 +151,261 @@ Edit `scripts/i18n/generate-multilang.mjs` — add entry to `LOCALE_SPECS`:
|
||||
},
|
||||
```
|
||||
|
||||
### 3. Generate Initial Translation
|
||||
### 3. 生成初始翻译
|
||||
|
||||
```bash
|
||||
node scripts/i18n/generate-multilang.mjs messages
|
||||
```
|
||||
|
||||
This creates `src/i18n/messages/xx.json` auto-translated from `en.json` via Google Translate.
|
||||
此命令通过 Google Translate 从 `en.json` 自动翻译生成 `src/i18n/messages/xx.json`。
|
||||
|
||||
### 4. Review & Fix Auto-Translations
|
||||
### 4. 审查并修正自动翻译
|
||||
|
||||
Auto-translations are a starting point. Review manually for:
|
||||
自动翻译是起点。手动审查以下方面：
|
||||
|
||||
- Technical accuracy
|
||||
- Context-appropriate terminology
|
||||
- Proper handling of placeholders (`{count}`, `{value}`, etc.)
|
||||
- 技术准确性
|
||||
- 语境适宜的术语
|
||||
- 占位符的正确处理（`{count}`、`{value}` 等）
|
||||
|
||||
### 5. Validate
|
||||
### 5. 校验
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_translation.py quick -l xx
|
||||
python3 scripts/validate_translation.py diff common -l xx
|
||||
python3 scripts/i18n/validate_translation.py quick -l xx
|
||||
python3 scripts/i18n/validate_translation.py diff common -l xx
|
||||
```
|
||||
|
||||
### 6. Generate Translated Documentation
|
||||
### 6. 生成翻译后的文档
|
||||
|
||||
```bash
|
||||
node scripts/i18n/generate-multilang.mjs docs
|
||||
```
|
||||
|
||||
## Auto-Translation Pipeline
|
||||
## 自动翻译管道
|
||||
|
||||
### generate-multilang.mjs (Google Translate)
|
||||
### generate-multilang.mjs（Google Translate）
|
||||
|
||||
**Primary auto-translation engine** — uses Google Translate free API to generate translations for UI strings, READMEs, and documentation.
|
||||
**主要自动翻译引擎** — 使用 Google Translate 免费 API 为 UI 字符串、README 和文档生成翻译。
|
||||
|
||||
```bash
|
||||
node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]
|
||||
```
|
||||
|
||||
| Mode | What it does |
|
||||
| ---------- | ----------------------------------------------------------------------------- |
|
||||
| `messages` | Translates missing keys in `src/i18n/messages/{locale}.json` from `en.json` |
|
||||
| `readme` | Translates `README.md` into all locales as `README.{code}.md` in project root |
|
||||
| `docs` | Translates `DOC_SOURCE_FILES` into `docs/i18n/{locale}/{docName}` |
|
||||
| `all` | Runs all three modes |
|
||||
| 模式 | 功能 |
|
||||
| ---------- | ------------------------------------------------------------------------------ |
|
||||
| `messages` | 从 `en.json` 翻译 `src/i18n/messages/{locale}.json` 中缺失的 Key |
|
||||
| `readme` | 将 `README.md` 翻译为所有语言/地区，生成根目录下的 `README.{code}.md` |
|
||||
| `docs` | 将 `DOC_SOURCE_FILES` 翻译到 `docs/i18n/{locale}/{docName}` |
|
||||
| `all` | 运行以上全部三种模式 |
|
||||
|
||||
**Features:**
|
||||
**功能特性：**
|
||||
|
||||
- **Text protection**: Masks code blocks (` ``` `), inline code (`` ` ``), markdown links/images (`[text](url)`), HTML tags, tables, and ICU placeholders (`{count}`, `{value}`, `{total}`, etc.) before translation, then restores them
|
||||
- **Chunked batching**: Joins multiple strings with `__OMNIROUTE_I18N_SEPARATOR__` delimiters to minimize API calls (max 1800 chars per request)
|
||||
- **In-memory cache**: Avoids redundant API calls for repeated strings within a session
|
||||
- **Retry logic**: Exponential backoff (up to 5 attempts with 300ms × attempt delay) for 429/5xx errors
|
||||
- **Timeout**: 20 seconds per request
|
||||
- **Skip existing**: If target file already exists, it is NOT overwritten
|
||||
- **文本保<EFBFBD><EFBFBD><EFBFBD>**：翻译前脱敏代码块（` ``` `）、内联代码（`` ` ``）、Markdown 链接/图片（`[text](url)`）、HTML 标签、表格和 ICU 占位符（`{count}`、`{value}`、`{total}` 等），翻译后还原
|
||||
- **分块批处理**：使用 `__OMNIROUTE_I18N_SEPARATOR__` 分隔符合并多个字符串，最小化 API 调用（每次请求最多 1800 字符）
|
||||
- **内存缓存**：避免同一会话中重复字符串的冗余 API 调用
|
||||
- **重试逻辑**：对 429/5xx 错误使用指数退避（最多 5 次尝试，延迟 300ms × 尝试次数）
|
||||
- **超时**：每次请求 20 秒
|
||||
- **跳过已有**：若目标文件已存在，不覆盖
|
||||
|
||||
**Important behaviors:**
|
||||
**重要行为：**
|
||||
|
||||
- `docs/i18n/README.md` is **regenerated** each run — it's an auto-generated index of all docs
|
||||
- Root `README.{code}.md` files are only created if they don't exist (skips locales in `EXISTING_README_CODES`)
|
||||
- Language bars (`🌐 **Languages:** ...`) are automatically inserted/updated in all translated docs
|
||||
- `docs/i18n/README.md` 每次运行会**重新生成** — 它是自动生成的全部文档索引
|
||||
- 根目录 `README.{code}.md` 文件仅在不存在时创建（跳过 `EXISTING_README_CODES` 中的语言/地区）
|
||||
- 语言条（`🌐 **Languages:** ...`）在所有翻译后的文档中自动插入/更新
|
||||
|
||||
### i18n_autotranslate.py (LLM-based)
|
||||
### i18n_autotranslate.py（基于 LLM）
|
||||
|
||||
**Secondary translator** — uses any OpenAI-compatible LLM API (including OmniRoute itself) to translate existing `docs/i18n/` markdown files. Best for polishing or re-translating docs with better quality than Google Translate.
|
||||
**辅助翻译器** — 使用任意 OpenAI 兼容的 LLM API（包括 OmniRoute 自身）翻译已有的 `docs/i18n/` Markdown 文件。适用于优化或重新翻译文档，质量优于 Google Translate。
|
||||
|
||||
```bash
|
||||
python3 scripts/i18n_autotranslate.py \
|
||||
python3 scripts/i18n/i18n_autotranslate.py \
|
||||
--api-url http://localhost:20128/v1 \
|
||||
--api-key sk-your-key \
|
||||
--model gpt-4o
|
||||
```
|
||||
|
||||
**Features:**
|
||||
**功能特性：**
|
||||
|
||||
- Scans `docs/i18n/` markdown files for English paragraphs
|
||||
- Skips code blocks, tables, and already-translated content
|
||||
- Sends paragraphs to LLM with technical translation system prompt
|
||||
- Supports all 30 languages
|
||||
- 扫描 `docs/i18n/` 中的 Markdown 文件，定位英文段落
|
||||
- 跳过代码块、表格和已翻译内容
|
||||
- 向 LLM 发送段落及技术翻译系统提示
|
||||
- 支持全部 42 种语言
|
||||
|
||||
## Validation & QA
|
||||
## CLI i18n
|
||||
|
||||
`omniroute` CLI 拥有独立的 i18n 层，与 Next.js 控制台分离。
|
||||
|
||||
### 工作原理
|
||||
|
||||
- CLI 命令中的每个用户可见字符串都通过 `bin/cli/i18n.mjs` 中的 `t("module.key", vars)` 处理。
|
||||
- 翻译目录是 `bin/cli/locales/` 中的 JSON 文件 — 预置 42 个语言/地区。
|
||||
- 缺失 Key 时回退到 `en`，因此部分翻译也是有效的。
|
||||
- 可用语言/地区的唯一数据源是 `config/i18n.json`（与控制台共享）。
|
||||
|
||||
### 语言/地区选择
|
||||
|
||||
检测顺序（优先匹配）：
|
||||
|
||||
| 优先级 | 来源 | 示例 |
|
||||
| ------ | ------------------------ | -------------------------------------- |
|
||||
| 1 | `--lang` 标志 | `omniroute --lang de status` |
|
||||
| 2 | `OMNIROUTE_LANG` 环境变量 | `OMNIROUTE_LANG=ja omniroute providers` |
|
||||
| 3 | `LC_ALL` 系统环境变量 | 从终端语言/地区自动检测 |
|
||||
| 4 | `LC_MESSAGES` 系统环境变量 | 从终端语言/地区自动检测 |
|
||||
| 5 | `LANG` 系统环境变量 | 从终端语言/地区自动检测 |
|
||||
| 6 | 回退 | `en` |
|
||||
|
||||
含下划线的语言/地区代码（`pt_BR`）规范化为连字符形式（`pt-BR`）。
|
||||
语言/地区代码通过 `/^[a-zA-Z0-9-]+$/` 校验 — 路径穿越将被拒绝。
|
||||
|
||||
### 保存语言偏好
|
||||
|
||||
```bash
|
||||
# 设置语言并保存到 ~/.omniroute/.env（跨会话持久化）
|
||||
omniroute config lang set pt-BR
|
||||
|
||||
# 查看当前语言
|
||||
omniroute config lang get
|
||||
|
||||
# 列出全部 42 种可用语言
|
||||
omniroute config lang list
|
||||
|
||||
# JSON 输出
|
||||
omniroute config lang list --output json
|
||||
```
|
||||
|
||||
保存的偏好以原子方式写入 `~/.omniroute/.env`，并在 CLI 引导阶段加载，先于任何命令执行。
|
||||
|
||||
### 单次覆盖
|
||||
|
||||
```bash
|
||||
# 仅覆盖单条命令（不持久化）
|
||||
omniroute --lang de providers list
|
||||
```
|
||||
|
||||
注意：`--lang` 标志不写入 env 文件 — 它仅影响当前调用。使用 `config lang set` 持久化。
|
||||
|
||||
### 可用语言/地区
|
||||
|
||||
`bin/cli/locales/` 中预置 42 个语言/地区文件。完整翻译：`en`、`pt-BR`。
|
||||
仅骨架（所有 Key 回退到 `en`）：`bn`、`gu`、`he`、`in`、`mr`、`ms`、`phi`、`sw`、`ta`、`te`、`ur`。
|
||||
其余 29 个语言/地区已翻译 `common` + `program` Key。
|
||||
|
||||
### 添加新的 CLI 语言/地区
|
||||
|
||||
1. 在 `config/i18n.json` 中添加语言/地区条目。
|
||||
2. 运行 `node bin/cli/scripts/generate-locales.mjs` — 创建语言/地区文件。
|
||||
3. 翻译 Key（或留空 `{}` 以使用 en 回退骨架）。
|
||||
4. PR 必须向 `en.json` 和 `pt-BR.json` 添加字符串；其他文件尽力而为。
|
||||
|
||||
## 校验与 QA
|
||||
|
||||
### validate_translation.py
|
||||
|
||||
**Translation validator** — compares any locale JSON against `en.json` and reports issues.
|
||||
**翻译校验器** — 将任意语言/地区的 JSON 与 `en.json` 对比并报告问题。
|
||||
|
||||
```bash
|
||||
# Quick check (counts only)
|
||||
python3 scripts/validate_translation.py quick -l cs
|
||||
# Output:
|
||||
# 快速检查（仅统计数量）
|
||||
python3 scripts/i18n/validate_translation.py quick -l cs
|
||||
# 输出：
|
||||
# Missing: 0
|
||||
# Untranslated: 0
|
||||
# Ignored (UNTRANSLATABLE_KEYS): 236
|
||||
|
||||
# Detailed diff by category
|
||||
python3 scripts/validate_translation.py diff common -l cs
|
||||
python3 scripts/validate_translation.py diff settings -l cs
|
||||
# 按类别的详细差异
|
||||
python3 scripts/i18n/validate_translation.py diff common -l cs
|
||||
python3 scripts/i18n/validate_translation.py diff settings -l cs
|
||||
|
||||
# Export to CSV
|
||||
python3 scripts/validate_translation.py csv -l cs > report.csv
|
||||
# 导出为 CSV
|
||||
python3 scripts/i18n/validate_translation.py csv -l cs > report.csv
|
||||
|
||||
# Export to Markdown
|
||||
python3 scripts/validate_translation.py md -l cs > report.md
|
||||
# 导出为 Markdown
|
||||
python3 scripts/i18n/validate_translation.py md -l cs > report.md
|
||||
|
||||
# Full report (default)
|
||||
python3 scripts/validate_translation.py -l cs
|
||||
# 完整报告（默认）
|
||||
python3 scripts/i18n/validate_translation.py -l cs
|
||||
```
|
||||
|
||||
**Detects:**
|
||||
**检测内容：**
|
||||
|
||||
- **Missing keys** — keys in `en.json` but not in locale file
|
||||
- **Extra keys** — keys in locale file but not in `en.json`
|
||||
- **Untranslated keys** — keys where locale value equals English source (excluding allowlist)
|
||||
- **Placeholder mismatches** — ICU placeholders that don't match between source and translation
|
||||
- **缺失的 Key** — Key 存在于 `en.json` 但不在语言/地区文件中
|
||||
- **多余的 Key** — Key 存在于语言/地区文件但不在 `en.json` 中
|
||||
- **未翻译的 Key** — 语言/地区值与英文源相同（排除允许清单）
|
||||
- **占位符不匹配** — ICU 占位符在源与翻译间不匹配
|
||||
|
||||
**Exit codes:**
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | OK |
|
||||
| 1 | Generic error |
|
||||
| 2 | Missing strings (hard error) |
|
||||
| 3 | Untranslated warning (soft) |
|
||||
**退出码：**
|
||||
|
||||
**Environment:** Set `TRANSLATION_LANG=cs` or use `-l cs` flag.
|
||||
| 代码 | 含义 |
|
||||
| ---- | ---------------------- |
|
||||
| 0 | 正常 |
|
||||
| 1 | 一般错误 |
|
||||
| 2 | 缺失字符串（硬错误） |
|
||||
| 3 | 未翻译警告（软错误） |
|
||||
|
||||
**环境变量：** 设置 `TRANSLATION_LANG=cs` 或使用 `-l cs` 标志。
|
||||
|
||||
### check_translations.py
|
||||
|
||||
**Code-to-JSON key checker** — scans `src/**/*.tsx` and `src/**/*.ts` for `useTranslations()` calls and verifies all referenced keys exist in `en.json`.
|
||||
**代码到 JSON Key 检查器** — 扫描 `src/**/*.tsx` 和 `src/**/*.ts` 中的 `useTranslations()` 调用，验证所有引用的 Key 是否存在于 `en.json`。
|
||||
|
||||
```bash
|
||||
# Basic check
|
||||
python3 scripts/check_translations.py
|
||||
# 基本检查
|
||||
python3 scripts/i18n/check_translations.py
|
||||
|
||||
# Verbose output
|
||||
python3 scripts/check_translations.py --verbose
|
||||
# 详细输出
|
||||
python3 scripts/i18n/check_translations.py --verbose
|
||||
|
||||
# Auto-fix (adds missing keys to en.json)
|
||||
python3 scripts/check_translations.py --fix
|
||||
# 自动修复（将缺失的 Key 添加到 en.json）
|
||||
python3 scripts/i18n/check_translations.py --fix
|
||||
```
|
||||
|
||||
### generate-qa-checklist.mjs
|
||||
|
||||
**Static analysis QA** — scans Next.js page files for i18n risk metrics and generates a Markdown report.
|
||||
**静态分析 QA** — 扫描 Next.js 页面文件以获取 i18n 风险指标，生成 Markdown 报告。
|
||||
|
||||
```bash
|
||||
node scripts/i18n/generate-qa-checklist.mjs
|
||||
```
|
||||
|
||||
**Checks:**
|
||||
**检查内容：**
|
||||
|
||||
- Fixed-width class usage (overflow risk)
|
||||
- Directional left/right classes (RTL risk)
|
||||
- Clipping-prone patterns
|
||||
- Locale parity (missing/extra keys vs `en.json`)
|
||||
- README language selector bars in priority locales (`es`, `fr`, `de`, `ja`, `ar`)
|
||||
- 固定宽度类使用（溢出风险）
|
||||
- 方向性的 left/right 类（RTL 风险）
|
||||
- 易截断的模式
|
||||
- 语言/地区一致性（vs `en.json` 的缺失/多余 Key）
|
||||
- 优先语言/地区的 README 语言选择器条（`es`、`fr`、`de`、`ja`、`ar`）
|
||||
|
||||
**Output:** `docs/reports/i18n-qa-checklist-{date}.md`
|
||||
**输出：** `docs/reports/i18n-qa-checklist-{date}.md`
|
||||
|
||||
### run-visual-qa.mjs
|
||||
|
||||
**Visual QA via Playwright** — takes screenshots of all dashboard routes in multiple locales and viewports, then evaluates page health.
|
||||
**通过 Playwright 进行视觉 QA** — 对多种语言/地区和视口尺寸下的所有控制台路由截图，然后评估页面健康。
|
||||
|
||||
```bash
|
||||
# Default: es, fr, de, ja, ar on localhost:20128
|
||||
# 默认：es、fr、de、ja、ar，访问 localhost:20128
|
||||
node scripts/i18n/run-visual-qa.mjs
|
||||
|
||||
# Custom base URL and locales
|
||||
# 自定义基础 URL 和语言/地区
|
||||
QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs
|
||||
|
||||
# Custom routes
|
||||
# 自定义路由
|
||||
QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs
|
||||
```
|
||||
|
||||
**Detects:**
|
||||
**检测内容：**
|
||||
|
||||
- Text overflow
|
||||
- Element clipping
|
||||
- RTL layout mismatches
|
||||
- 文本溢出
|
||||
- 元素截断
|
||||
- RTL 布局不匹配
|
||||
|
||||
**Output:** `docs/reports/i18n-visual-qa-{date}.md` + JSON report
|
||||
**输出：** `docs/reports/i18n-visual-qa-{date}.md` + JSON 报告
|
||||
|
||||
## Managing Untranslatable Keys
|
||||
## 管理不可翻译的 Key
|
||||
|
||||
### untranslatable-keys.json
|
||||
|
||||
**File:** `scripts/i18n/untranslatable-keys.json`
|
||||
**文件：** `scripts/i18n/untranslatable-keys.json`
|
||||
|
||||
Allowlist of keys that should remain identical to English source. Used by `validate_translation.py` to avoid false-positive "untranslated" warnings.
|
||||
允许保留英文的 Key 清单，供 `validate_translation.py` 使用，避免误报"未翻译"警告。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -298,36 +419,36 @@ Allowlist of keys that should remain identical to English source. Used by `valid
|
||||
}
|
||||
```
|
||||
|
||||
**What belongs here:**
|
||||
**适用内容：**
|
||||
|
||||
- Brand/product names: `landing.brandName`, `common.social-github`
|
||||
- Technical terms/acronyms: `health.cpu`, `mcpDashboard.pid`, `settings.ai`
|
||||
- ICU/format strings: `apiManager.modelsCount`, `health.millisecondsShort`
|
||||
- Placeholder values: `providers.openaiBaseUrlPlaceholder`, `cliTools.baseUrlPlaceholder`
|
||||
- Protocol names: `common.http`, `common.oauth`, `providers.oauth2Label`
|
||||
- Navigation sections: `sidebar.primarySection`, `sidebar.cliSection`
|
||||
- 品牌/产品名：`landing.brandName`、`common.social-github`
|
||||
- 技术术语/缩写：`health.cpu`、`mcpDashboard.pid`、`settings.ai`
|
||||
- ICU/格式字符串：`apiManager.modelsCount`、`health.millisecondsShort`
|
||||
- 占位符值：`providers.openaiBaseUrlPlaceholder`、`cliTools.baseUrlPlaceholder`
|
||||
- 协议名：`common.http`、`common.oauth`、`providers.oauth2Label`
|
||||
- 导航分组：`sidebar.primarySection`、`sidebar.cliSection`
|
||||
|
||||
**To add a key:** Edit the `keys` array in `scripts/i18n/untranslatable-keys.json` and re-run validation.
|
||||
**添加 Key：** 编辑 `scripts/i18n/untranslatable-keys.json` 中的 `keys` 数组，然后重新运行校验。
|
||||
|
||||
## CI Integration
|
||||
## CI 集成
|
||||
|
||||
### GitHub Actions (`.github/workflows/ci.yml`)
|
||||
### GitHub Actions（`.github/workflows/ci.yml`）
|
||||
|
||||
The CI pipeline validates all locales on every push and PR:
|
||||
CI 管道在每次 push 和 PR 时校验所有语言/地区：
|
||||
|
||||
1. **`i18n-matrix` job** — dynamically discovers all locale files (excluding `en.json`)
|
||||
2. **`i18n` job** — runs `validate_translation.py quick -l '<lang>'` for each locale in parallel
|
||||
3. **`ci-summary` job** — aggregates results into a dashboard summary
|
||||
1. **`i18n-matrix` 任务** — 动态发现所有语言/地区文件（排除 `en.json`）
|
||||
2. **`i18n` 任务** — 对每个语言/地区并行运行 `validate_translation.py quick -l '<lang>'`
|
||||
3. **`ci-summary` 任务** — 聚合结果到控制台摘要
|
||||
|
||||
```yaml
|
||||
# i18n-matrix: discovers languages
|
||||
# i18n-matrix：发现语言
|
||||
LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')
|
||||
|
||||
# i18n: validates each language
|
||||
python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
|
||||
# i18n：校验每种语言
|
||||
python3 scripts/i18n/validate_translation.py quick -l '${{ matrix.lang }}'
|
||||
```
|
||||
|
||||
**Dashboard output:**
|
||||
**控制台输出：**
|
||||
|
||||
```
|
||||
## 🌍 Translations
|
||||
@@ -339,103 +460,105 @@ python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
|
||||
✅ All translations complete
|
||||
```
|
||||
|
||||
## File Structure
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
src/i18n/
|
||||
├── config.ts # Locale definitions (30 locales, RTL config)
|
||||
├── request.ts # Runtime locale resolution
|
||||
├── config.ts # 语言/地区定义（30 个语言/地区，RTL 配置）
|
||||
├── request.ts # 运行时语言/地区解析
|
||||
└── messages/
|
||||
├── en.json # Source of truth (~2800 keys)
|
||||
├── cs.json # Czech translation
|
||||
├── de.json # German translation
|
||||
└── ... # 30 locale files total
|
||||
├── en.json # 唯一数据源（约 2800 个 Key）
|
||||
├── cs.json # 捷克语翻译
|
||||
├── de.json # 德语翻译
|
||||
└── ... # 共计 30 个语言/地区文件
|
||||
|
||||
scripts/
|
||||
├── i18n/
|
||||
│ ├── generate-multilang.mjs # Auto-translation engine (Google Translate, 888 lines)
|
||||
│ ├── generate-qa-checklist.mjs # Static analysis QA
|
||||
│ ├── run-visual-qa.mjs # Playwright visual QA
|
||||
│ └── untranslatable-keys.json # Allowlist for validation (236 keys)
|
||||
├── validate_translation.py # Translation validator
|
||||
├── check_translations.py # Code-to-JSON key checker
|
||||
└── i18n_autotranslate.py # LLM-based doc translator
|
||||
│ ├── generate-multilang.mjs # 自动翻译引擎（Google Translate，888 行）
|
||||
│ ├── generate-qa-checklist.mjs # 静态分析 QA
|
||||
│ ├── run-visual-qa.mjs # Playwright 视觉 QA
|
||||
│ └── untranslatable-keys.json # 校验允许清单（236 个 Key）
|
||||
├── validate_translation.py # 翻译校验器
|
||||
├── check_translations.py # 代码到 JSON Key 检查器
|
||||
└── i18n_autotranslate.py # 基于 LLM 的文档翻译器
|
||||
|
||||
.github/workflows/
|
||||
└── ci.yml # i18n validation in CI matrix
|
||||
└── ci.yml # CI 矩阵中的 i18n 校验
|
||||
|
||||
docs/
|
||||
├── I18N.md # This file — i18n toolchain documentation
|
||||
├── I18N.md # 本文件 — i18n 工具链文档
|
||||
├── i18n/
|
||||
│ ├── README.md # Auto-generated language index
|
||||
│ ├── cs/ # Czech docs
|
||||
│ ├── README.md # 自动生成的语言索引
|
||||
│ ├── cs/ # 捷克语文档
|
||||
│ │ └── docs/
|
||||
│ │ ├── I18N.md # Czech translation of this file
|
||||
│ │ ├── I18N.md # 本文件的捷克语翻译
|
||||
│ │ └── ...
|
||||
│ ├── de/ # German docs
|
||||
│ └── ... # 30 locale directories
|
||||
│ ├── de/ # 德语文档
|
||||
│ └── ... # 30 个语言/地区目录
|
||||
└── reports/
|
||||
├── i18n-qa-checklist-*.md # Static analysis reports
|
||||
└── i18n-visual-qa-*.md # Visual QA reports
|
||||
├── i18n-qa-checklist-*.md # 静态分析报告
|
||||
└── i18n-visual-qa-*.md # 视觉 QA 报告
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
## 优秀实践
|
||||
|
||||
### When Editing Translations
|
||||
### 编辑翻译时
|
||||
|
||||
1. **Always edit `en.json` first** — it's the source of truth
|
||||
2. **Run `generate-multilang.mjs messages`** to propagate new keys to all locales
|
||||
3. **Review auto-translations** — Google Translate is a starting point, not final
|
||||
4. **Validate before committing** — `python3 scripts/validate_translation.py quick -l <lang>`
|
||||
5. **Update `untranslatable-keys.json`** if a key should remain in English
|
||||
1. **始终先编辑 `en.json`** — 它是唯一数据源
|
||||
2. **运行 `generate-multilang.mjs messages`** 将新的 Key 传播到所有语言/地区
|
||||
3. **审查自动翻译** — Google Translate 是起点，不是最终结果
|
||||
4. **提交前校验** — `python3 scripts/i18n/validate_translation.py quick -l <lang>`
|
||||
5. **更新 `untranslatable-keys.json`** 如果某个 Key 应保留为英文
|
||||
|
||||
### Placeholder Safety
|
||||
### 占位符安全
|
||||
|
||||
- ICU placeholders (`{count}`, `{value}`, `{total}`, `{seconds}`) must be preserved exactly
|
||||
- Plural formats (`{count, plural, one {# model} other {# models}}`) must maintain structure
|
||||
- The validator detects placeholder mismatches automatically
|
||||
- ICU 占位符（`{count}`、`{value}`、`{total}`、`{seconds}`）必须精确保留
|
||||
- 复数格式（`{count, plural, one {# model} other {# models}}`）必须维持结构
|
||||
- 校验器会自动检测占位符不匹配
|
||||
|
||||
### Adding New Translation Keys in Code
|
||||
### 在代码中添加新的翻译 Key
|
||||
|
||||
```tsx
|
||||
// Use namespaced keys
|
||||
// 使用命名空间 Key
|
||||
const t = useTranslations("settings");
|
||||
t("cacheSettings"); // maps to settings.cacheSettings in JSON
|
||||
t("cacheSettings"); // 映射到 JSON 中的 settings.cacheSettings
|
||||
|
||||
// Run check_translations.py to verify keys exist
|
||||
python3 scripts/check_translations.py --verbose
|
||||
// 运行 check_translations.py 验证 Key 存在
|
||||
python3 scripts/i18n/check_translations.py --verbose
|
||||
```
|
||||
|
||||
### RTL Considerations
|
||||
### RTL 注意事项
|
||||
|
||||
- Arabic (`ar`) and Hebrew (`he`) are RTL locales
|
||||
- Avoid hardcoded `left`/`right` CSS — use `start`/`end` logical properties
|
||||
- Visual QA catches RTL layout mismatches via `run-visual-qa.mjs`
|
||||
- 阿拉伯语（`ar`）和希伯来语（`he`）是 RTL 语言/地区
|
||||
- 避免硬编码 `left`/`right` CSS — 使用 `start`/`end` 逻辑属性
|
||||
- 视觉 QA 通过 `run-visual-qa.mjs` 捕获 RTL 布局不匹配
|
||||
|
||||
## Known Issues & History
|
||||
## 已知问题与历史
|
||||
|
||||
### `in.json` → `hi.json` Fix
|
||||
### `in.json` → `hi.json` 修复
|
||||
|
||||
The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This created an orphaned `in.json` duplicate of `hi.json`. Fixed by changing `code: "in"` to `code: "hi"` in `generate-multilang.mjs` and removing the orphaned file.
|
||||
生成器最初对印地语使用 `code: "in"`（已弃用的 Google Translate 代码），而非正确的 ISO 639-1 `hi`。这导致创建了 `hi.json` 的孤立副本 `in.json`。通过将 `generate-multilang.mjs` 中的 `code: "in"` 改为 `code: "hi"` 并删除孤立文件完成修复。
|
||||
|
||||
### `docs/i18n/README.md` Is Auto-Generated
|
||||
> ⚠️ **审计（2026-05-13）：** `docs/i18n/in/` 目录在磁盘上仍然存在（`hi/` 的完整副本）。翻译生成器不再向其写入，但历史目录树未被清理。确认无外部链接引用旧路径后，可使用 `rm -rf docs/i18n/in/` 安全删除。
|
||||
|
||||
The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
|
||||
### `docs/i18n/README.md` 是自动生成的
|
||||
|
||||
### External Untranslatable Keys List
|
||||
`docs/i18n/README.md` 文件由 `generate-multilang.mjs docs` 完全重新生成。任何手动编辑都会丢失。如需持久化的手写文档，请使用 `docs/guides/I18N.md`（本文件）。
|
||||
|
||||
The `untranslatable-keys.json` allowlist was moved from an inline Python set in `validate_translation.py` to an external JSON file for easier maintenance. The validator loads it at runtime.
|
||||
### 外部不可翻译 Key 列表
|
||||
|
||||
### `generate-multilang.mjs` Hindi Code Fix
|
||||
`untranslatable-keys.json` 允许清单从 `validate_translation.py` 中的内联 Python set 迁移到外部 JSON 文件，以便维护。校验器在运行时加载该清单。
|
||||
|
||||
The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This was introduced in upstream commit `952b0b22c` by `diegosouzapw`. Fixed by changing `code: "in"` to `code: "hi"` in the `LOCALE_SPECS` array and removing the orphaned `in.json` file.
|
||||
### `generate-multilang.mjs` 印地语代码修复
|
||||
|
||||
### `validate_translation.py` Ignored Count Output
|
||||
生成器最初对印地语使用 `code: "in"`（已弃用的 Google Translate 代码），而非正确的 ISO 639-1 `hi`。该问题由上版本 `952b0b22c`（作者 `diegosouzapw`）引入。通过将 `LOCALE_SPECS` 数组中的 `code: "in"` 修改为 `code: "hi"` 并删除孤立的 `in.json` 文件完成修复。
|
||||
|
||||
The `quick` check now displays the count of ignored keys from `untranslatable-keys.json`:
|
||||
### `validate_translation.py` 被忽略 Key 的计数输出
|
||||
|
||||
`quick` 检查现在显示来自 `untranslatable-keys.json` 的被忽略 Key 数：
|
||||
|
||||
```
|
||||
Missing: 0
|
||||
Untranslated: 0
|
||||
Ignored (UNTRANSLATABLE_KEYS): 236
|
||||
Ignored (UNTRANSLATABLE_KEYS): <各版本数量不同>
|
||||
```
|
||||
|
||||
@@ -1,72 +1,102 @@
|
||||
# Troubleshooting (中文 (简体))
|
||||
---
|
||||
title: "故障排除"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/TROUBLESHOOTING.md) · 🇸🇦 [ar](../../ar/docs/TROUBLESHOOTING.md) · 🇧🇬 [bg](../../bg/docs/TROUBLESHOOTING.md) · 🇧🇩 [bn](../../bn/docs/TROUBLESHOOTING.md) · 🇨🇿 [cs](../../cs/docs/TROUBLESHOOTING.md) · 🇩🇰 [da](../../da/docs/TROUBLESHOOTING.md) · 🇩🇪 [de](../../de/docs/TROUBLESHOOTING.md) · 🇪🇸 [es](../../es/docs/TROUBLESHOOTING.md) · 🇮🇷 [fa](../../fa/docs/TROUBLESHOOTING.md) · 🇫🇮 [fi](../../fi/docs/TROUBLESHOOTING.md) · 🇫🇷 [fr](../../fr/docs/TROUBLESHOOTING.md) · 🇮🇳 [gu](../../gu/docs/TROUBLESHOOTING.md) · 🇮🇱 [he](../../he/docs/TROUBLESHOOTING.md) · 🇮🇳 [hi](../../hi/docs/TROUBLESHOOTING.md) · 🇭🇺 [hu](../../hu/docs/TROUBLESHOOTING.md) · 🇮🇩 [id](../../id/docs/TROUBLESHOOTING.md) · 🇮🇹 [it](../../it/docs/TROUBLESHOOTING.md) · 🇯🇵 [ja](../../ja/docs/TROUBLESHOOTING.md) · 🇰🇷 [ko](../../ko/docs/TROUBLESHOOTING.md) · 🇮🇳 [mr](../../mr/docs/TROUBLESHOOTING.md) · 🇲🇾 [ms](../../ms/docs/TROUBLESHOOTING.md) · 🇳🇱 [nl](../../nl/docs/TROUBLESHOOTING.md) · 🇳🇴 [no](../../no/docs/TROUBLESHOOTING.md) · 🇵🇭 [phi](../../phi/docs/TROUBLESHOOTING.md) · 🇵🇱 [pl](../../pl/docs/TROUBLESHOOTING.md) · 🇵🇹 [pt](../../pt/docs/TROUBLESHOOTING.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) · 🇷🇴 [ro](../../ro/docs/TROUBLESHOOTING.md) · 🇷🇺 [ru](../../ru/docs/TROUBLESHOOTING.md) · 🇸🇰 [sk](../../sk/docs/TROUBLESHOOTING.md) · 🇸🇪 [sv](../../sv/docs/TROUBLESHOOTING.md) · 🇰🇪 [sw](../../sw/docs/TROUBLESHOOTING.md) · 🇮🇳 [ta](../../ta/docs/TROUBLESHOOTING.md) · 🇮🇳 [te](../../te/docs/TROUBLESHOOTING.md) · 🇹🇭 [th](../../th/docs/TROUBLESHOOTING.md) · 🇹🇷 [tr](../../tr/docs/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) · 🇵🇰 [ur](../../ur/docs/TROUBLESHOOTING.md) · 🇻🇳 [vi](../../vi/docs/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md)
|
||||
# 故障排除
|
||||
|
||||
> **致用户**：想快速解决问题？请参阅下方的[快速参考](#快速参考)。
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/guides/TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/guides/TROUBLESHOOTING.md) | 🇪🇸 [Español](../../es/docs/guides/TROUBLESHOOTING.md) | 🇫🇷 [Français](../../fr/docs/guides/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../../it/docs/guides/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../../ru/docs/guides/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/guides/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../../de/docs/guides/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../../in/docs/guides/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../../th/docs/guides/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../../uk-UA/docs/guides/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../../ar/docs/guides/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../../ja/docs/guides/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/guides/TROUBLESHOOTING.md) | 🇧🇬 [Български](../../bg/docs/guides/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../../da/docs/guides/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../../fi/docs/guides/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../../he/docs/guides/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../../hu/docs/guides/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/guides/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../../ko/docs/guides/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/guides/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../../nl/docs/guides/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../../no/docs/guides/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/guides/TROUBLESHOOTING.md) | 🇷🇴 [Română](../../ro/docs/guides/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../../pl/docs/guides/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../../sk/docs/guides/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../../sv/docs/guides/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../../phi/docs/guides/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](../../cs/docs/guides/TROUBLESHOOTING.md)
|
||||
|
||||
OmniRoute 常见问题及解决方案。
|
||||
|
||||
---
|
||||
|
||||
Common problems and solutions for OmniRoute.
|
||||
## 快速参考
|
||||
|
||||
**刚接触 OmniRoute？** 从这里开始 —— 以下内容可解决 90% 的问题：
|
||||
|
||||
| 你看到的提示 | 含义 | 解决方法 |
|
||||
| ----------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
|
||||
| "Can't connect" | OmniRoute 未运行 | 运行 `omniroute` 或 `docker restart omniroute` |
|
||||
| "Invalid API key" | API 密钥错误或已过期 | 从服务商网站重新复制密钥 |
|
||||
| "Rate limit exceeded" | 请求频率过高 | 等待 1 分钟，或使用 `model: "auto"` 自动容灾 |
|
||||
| "Quota exceeded" | 免费/付费配额已用尽 | 接入更多服务商，或使用免费服务商（Kiro、Pollinations） |
|
||||
| "Slow responses" | 服务商繁忙或距离较远 | 使用 `model: "auto/fast"` 或接入速度更快的服务商（Groq、Cerebras） |
|
||||
| "Wrong provider used" | `auto` 选择了其他服务商 | 这是正常现象！`auto` 会选取最优服务商。如需指定，使用 `model: "openai/gpt-4o"` |
|
||||
| "502 Bad Gateway" | 服务商宕机 | 等待重试，或使用 `model: "auto"` 切换服务商 |
|
||||
| "401 Unauthorized" | 凭据有误 | 检查 API 密钥或通过 OAuth 重新认证 |
|
||||
| "429 Too Many Requests" | 触发速率限制 | 等待 1 分钟，或接入更多服务商 |
|
||||
|
||||
**还是不行？** 请参阅下方的[详细故障排除](#详细故障排除)，或前往 [Discord](https://discord.gg/EkzRkpzKYt) 提问。
|
||||
|
||||
---
|
||||
|
||||
## 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 logs written to disk | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled |
|
||||
| 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) |
|
||||
| Login crash / blank page | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below |
|
||||
| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below |
|
||||
| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below |
|
||||
## 详细故障排除
|
||||
|
||||
---
|
||||
|
||||
## Node.js Compatibility
|
||||
## 快速修复
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 首次登录无法使用 | 在 `.env` 中设置 `INITIAL_PASSWORD`（无硬编码默认值） |
|
||||
| 仪表盘打开的端口不对 | 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
|
||||
| 没有日志写入磁盘 | 设置 `APP_LOG_TO_FILE=true` 并确认已启用调用日志捕获 |
|
||||
| EACCES: permission denied | 设置 `DATA_DIR=/path/to/writable/dir` 覆盖 `~/.omniroute` |
|
||||
| 路由策略无法保存 | 更新至最新 v3.x 版本（早期版本中已修复 settings 持久化的 Zod Schema 问题） |
|
||||
| 登录崩溃 / 空白页面 | 检查 Node.js 版本 —— 参见下方的 [Node.js 兼容性](#nodejs-兼容性) |
|
||||
| `dlopen` / `slice is not valid mach-o file` (macOS) | 运行 `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` —— 参见下方的 [macOS 原生模块重新编译](#macos-原生模块重新编译) |
|
||||
| 代理 "fetch failed" | 请确认代理配置已设置在正确的层级 —— 参见下方的[代理问题](#代理问题) |
|
||||
|
||||
---
|
||||
|
||||
## Node.js 兼容性
|
||||
|
||||
<a name="nodejs-compatibility"></a>
|
||||
|
||||
### Login page crashes or shows "Module self-registration" error
|
||||
### 登录页面崩溃或显示 "Module self-registration" 错误
|
||||
|
||||
**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.
|
||||
**原因：** 你使用的 Node.js 版本不在 OmniRoute 批准的安全运行时范围内。最常见的情况是运行的 Node.js 22 或 24 补丁版本过低，未达到 OmniRoute 所需的安全补丁基线。
|
||||
|
||||
**Symptoms:**
|
||||
**症状：**
|
||||
|
||||
- Login page shows a blank screen or a server error
|
||||
- Console shows `Error: Module did not self-register` or similar native binding errors
|
||||
- The login page shows an **orange warning banner** with your Node version if the runtime is outside the supported secure policy
|
||||
- 登录页面显示空白或服务器报错
|
||||
- 控制台显示 `Error: Module did not self-register` 或类似的原生绑定错误
|
||||
- 如果运行时不在支持的安全策略范围内，登录页面会显示一个**橙色警告横幅**，标明你的 Node 版本
|
||||
|
||||
**Fix:**
|
||||
**修复：**
|
||||
|
||||
1. Install a supported Node.js LTS release (recommended: Node.js 24.x):
|
||||
1. 安装受支持的 Node.js LTS 版本（推荐：Node.js 24.x）：
|
||||
```bash
|
||||
nvm install 24
|
||||
nvm use 24
|
||||
```
|
||||
2. Verify your version: `node --version` should show `v24.0.0` or newer on the 24.x LTS line
|
||||
3. Reinstall OmniRoute: `npm install -g omniroute`
|
||||
4. Restart: `omniroute`
|
||||
2. 验证版本：`node --version` 应显示 `v24.0.0` 或 24.x LTS 线上的更高版本
|
||||
3. 重新安装 OmniRoute：`npm install -g omniroute`
|
||||
4. 重启：`omniroute`
|
||||
|
||||
> **Supported secure versions:** `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`. Node.js 24.x LTS (Krypton) is fully supported.
|
||||
> **受支持的安全版本：** `>=22.22.2 <23` 或 `>=24.0.0 <27`。Node.js 24.x LTS (Krypton) 和 Node.js 26 完全支持。
|
||||
|
||||
### macOS: `dlopen` / "slice is not valid mach-o file"
|
||||
### macOS：`dlopen` / "slice is not valid mach-o file"
|
||||
|
||||
<a name="macos-native-module-rebuild"></a>
|
||||
|
||||
**Cause:** After a global `npm install -g omniroute`, the `better-sqlite3` native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment.
|
||||
**原因：** 执行全局 `npm install -g omniroute` 后，包内的 `better-sqlite3` 原生二进制文件可能被编译为与你本地运行环境不同的架构或 Node.js ABI。这在 macOS 上很常见（Apple Silicon 和 Intel 均如此），当预编译的二进制文件与你的环境不匹配时就会发生。
|
||||
|
||||
**Symptoms:**
|
||||
**症状：**
|
||||
|
||||
- Server fails immediately on startup with a `dlopen` error
|
||||
- Error contains `slice is not valid mach-o file`
|
||||
- Full example:
|
||||
- 服务器启动时立即报出 `dlopen` 错误
|
||||
- 错误信息包含 `slice is not valid mach-o file`
|
||||
- 完整示例：
|
||||
|
||||
```
|
||||
dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
|
||||
```
|
||||
|
||||
**Fix — rebuild for your local environment (no Node.js downgrade required):**
|
||||
**修复 —— 针对本地环境重新编译（无需降级 Node.js）：**
|
||||
|
||||
```bash
|
||||
cd $(npm root -g)/omniroute/app
|
||||
@@ -74,98 +104,114 @@ npm rebuild better-sqlite3
|
||||
omniroute
|
||||
```
|
||||
|
||||
> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is **`>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`** (`engines` field in `package.json`). Node.js 24.x LTS (Krypton) is fully supported with `better-sqlite3` v12.x.
|
||||
> **说明：** 这会针对你的本地 Node.js 版本和 CPU 架构重新编译原生绑定，解决二进制不匹配问题。官方支持的运行时范围为 **`>=22.22.2 <23` 或 `>=24.0.0 <27`**（`src/shared/utils/nodeRuntimeSupport.ts` 中的 `SUPPORTED_NODE_RANGE`，与 `package.json` 的 `engines` 字段一致）。Node.js 24.x LTS (Krypton) 和 Node.js 26 在 `better-sqlite3` v12.x 下完全支持。
|
||||
|
||||
---
|
||||
|
||||
## Proxy Issues
|
||||
## 代理问题
|
||||
|
||||
<a name="proxy-issues"></a>
|
||||
|
||||
### Provider validation shows "fetch failed"
|
||||
### 服务商验证提示 "fetch failed"
|
||||
|
||||
**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing.
|
||||
**原因：** API 密钥验证端点（`POST /api/providers/validate`）之前绕过了代理配置，导致在需要代理路由的环境中验证失败。
|
||||
|
||||
**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically.
|
||||
**修复（v3.5.5+）：** 已修复。服务商验证现在通过 `runWithProxyContext` 路由，自动遵循服务商级别和全局代理设置。
|
||||
|
||||
### Token health check fails with "fetch failed"
|
||||
### Token 健康检查报错 "fetch failed"
|
||||
|
||||
**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection.
|
||||
**原因：** 后台 OAuth Token 刷新未解析每个连接对应的代理配置。
|
||||
|
||||
**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.
|
||||
**修复（v3.5.5+）：** Token 健康检查调度器现在在尝试刷新之前会按连接解析代理配置。请更新至 v3.5.5+。
|
||||
|
||||
### SOCKS5 proxy returns "invalid onRequestStart method"
|
||||
### SOCKS5 代理返回 "invalid onRequestStart method"
|
||||
|
||||
**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation.
|
||||
**原因：** 在 Node.js 22 上，undici@8 调度器与 Node 内置的 `fetch()` 实现不兼容。
|
||||
|
||||
**Fix (v3.5.5+):** OmniRoute now uses undici's own `fetch()` function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.
|
||||
**修复（v3.5.5+）：** OmniRoute 现在在代理调度器激活时使用 undici 自身的 `fetch()` 函数，确保行为一致。请更新至 v3.5.5+。
|
||||
|
||||
### WSL 下的 MITM 代理：Windows 主机上的桌面应用未被拦截
|
||||
|
||||
**原因：** MITM 代理及其 CA 证书安装在 OmniRoute 运行的环境中。在 WSL 下，该环境是 Linux 客户机，而 AI 桌面应用（Kiro、Trae、Copilot、Zed 等）运行在 Windows 主机上。主机应用不信任客户机的证书存储，也不会通过客户机的系统代理路由，因此桌面拦截不会在那里生效。
|
||||
|
||||
**建议：** 将 OmniRoute 以原生方式运行在与你想要拦截的桌面应用相同的操作系统上（Windows 应用在 Windows 上运行；macOS/Linux 同理）。将 OmniRoute 留在 WSL 内同时针对主机应用，需要手动在 Windows 主机上信任生成的 CA 证书，并将每个主机应用的网络/代理设置指向 WSL 代理端点 —— 这是一种不受支持、脆弱的配置方案。
|
||||
|
||||
---
|
||||
|
||||
## 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. 使用包含容灾层级的 Combo
|
||||
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. 仪表盘 → 服务商 → 重新连接
|
||||
2. 删除并重新添加该服务商连接
|
||||
|
||||
### Kiro 多账号：第二个账号使第一个失效
|
||||
|
||||
**原因：** Kiro 后端强制每个 OIDC 客户端注册仅允许一个活跃会话。当两个账号共享同一个注册客户端（v3.8.0 之前导入的连接）时，刷新一个账号的 Token 会使另一个账号的 refresh token 失效。
|
||||
|
||||
**修复（v3.8.0+）：** 重新导入受影响的连接。从 v3.8.0 开始，每个通过 **Import Token**、**Google/GitHub 社交登录**或 **Auto-Import** 创建的 Kiro 新连接，都会自动注册自己的独立 OIDC 客户端。因此每个连接完全隔离，刷新一个账号对其他账号没有影响。
|
||||
|
||||
在 v3.8.0 之前导入的连接没有携带每个连接独立的客户端注册。这些连接继续使用共享的社交认证刷新端点。要获得隔离，请从仪表盘 → 服务商中删除旧连接，然后通过三种导入流程之一重新添加。
|
||||
|
||||
详细信息和添加两个 Kiro 账号的逐步说明，请参阅 [`docs/guides/KIRO_SETUP.md`](./KIRO_SETUP.md)。
|
||||
|
||||
---
|
||||
|
||||
## 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. 运行云端同步：启用 Cloud → Sync Now
|
||||
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}'
|
||||
@@ -175,166 +221,279 @@ 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. Set cost budgets per API key: Dashboard → API Keys → Budget
|
||||
1. 在仪表盘 → Usage 中查看用量统计
|
||||
2. 将主模型切换到 GLM/MiniMax
|
||||
3. 对非关键任务使用免费层级（Qoder、Kiro）
|
||||
4. 按 API 密钥设置费用预算：仪表盘 → API Keys → Budget
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
## 调试
|
||||
|
||||
### Enable Log Files
|
||||
### 启用日志文件
|
||||
|
||||
Set `APP_LOG_TO_FILE=true` in your `.env` file. Application logs are written under `logs/`.
|
||||
Request artifacts are stored under `${DATA_DIR}/call_logs/` when the call log pipeline is
|
||||
enabled in settings.
|
||||
在 `.env` 文件中设置 `APP_LOG_TO_FILE=true`。应用日志将写入 `logs/` 目录。当调用日志流水线在设置中启用时，请求产物存储在 `${DATA_DIR}/call_logs/` 下。当流水线捕获启用时，可设置 `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false` 来省略流式分块载荷，或调整 `CALL_LOG_PIPELINE_MAX_SIZE_KB` 来修改产物上限（单位 KB）。
|
||||
|
||||
### 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}/call_logs/`
|
||||
- Application logs: `<repo>/logs/...` (when `APP_LOG_TO_FILE=true`)
|
||||
- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled
|
||||
- 主状态：`${DATA_DIR}/storage.sqlite`（服务商、Combo、别名、密钥、设置）
|
||||
- 用量：`storage.sqlite` 中的 SQLite 表（`usage_history`、`call_logs`、`proxy_logs`）+ 可选的 `${DATA_DIR}/call_logs/`
|
||||
- 应用日志：`<repo>/logs/...`（当 `APP_LOG_TO_FILE=true` 时）
|
||||
- 调用日志产物：当调用日志流水线启用时为 `${DATA_DIR}/call_logs/YYYY-MM-DD/...`
|
||||
|
||||
请求日志页面的 **Clean history** 操作会清除 `call_logs`、旧版 `request_detail_logs` 以及本地 `${DATA_DIR}/call_logs/` 产物目录。
|
||||
|
||||
---
|
||||
|
||||
## 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. 前往 **仪表盘 → 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. 在 **仪表盘 → 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`
|
||||
- 在 **仪表盘 → 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:
|
||||
使用 **仪表盘 → 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** | 发送实时消息并检查完整的请求/响应载荷，包括 headers |
|
||||
| **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 预算设置
|
||||
- **工具调用丢失** —— 部分格式转换可能会去除不支持的字段；在 Playground 模式下验证
|
||||
- **系统提示丢失** —— Claude 和 Gemini 处理系统提示的方式不同；检查转换输出
|
||||
- **SDK 返回原始字符串而非对象** —— 已在 v1.x 修复；响应清理器现在会去除导致 OpenAI SDK Pydantic 校验失败的非标准字段（`x_groq`、`usage_breakdown` 等）。如果在 v3.x+ 上仍遇到此问题，请提交 issue
|
||||
- **GLM/ERNIE 拒绝 `system` 角色** —— 已在 v1.x 修复；角色规范化器对不兼容模型自动将系统消息合并到用户消息中。如果在 v3.x+ 上仍遇到此问题，请提交 issue
|
||||
- **`developer` 角色不被识别** —— 已在 v1.x 修复；对非 OpenAI 服务商自动转换为 `system`。如果在 v3.x+ 上仍遇到此问题，请提交 issue
|
||||
- **`json_schema` 在 Gemini 上不生效** —— 已在 v1.x 修复；`response_format` 现在会转换为 Gemini 的 `responseMimeType` + `responseSchema`。如果在 v3.x+ 上仍遇到此问题，请提交 issue
|
||||
|
||||
---
|
||||
|
||||
## 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` header
|
||||
|
||||
### 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 许可文本资源，定义了 16 种常见的 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 中的路由或服务商 Combo
|
||||
- 下游使用的任何 RAG 上下文（检索到的文档、工具调用等）
|
||||
2. 将该事件映射到一个或两个 WFGY ProblemMap 编号（`No.1` … `No.16`）。
|
||||
3. 将编号存储在你自己的仪表盘、runbook 或事件追踪器中，紧邻 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?
|
||||
## v3.8.0 已知问题
|
||||
|
||||
v3.8.0 版本特有的问题及其当前临时方案。如果后续补丁中得到了修复，对应条目将更新或移除。
|
||||
|
||||
### Windsurf OAuth 流程报 401
|
||||
|
||||
**症状：**
|
||||
|
||||
- 从仪表盘完成 Windsurf OAuth 流程时出现 "401 unauthorized"
|
||||
- OAuth 回调后 Windsurf 服务商卡片持续显示"需要重新连接"状态
|
||||
|
||||
**原因：**
|
||||
|
||||
- `WINDSURF_FIREBASE_API_KEY` 环境变量缺失或为空
|
||||
- `WINDSURF_API_KEY` 配置错误或指向了过期的 Token
|
||||
- 本地防火墙/代理阻止了 OAuth 回调
|
||||
|
||||
**修复：**
|
||||
|
||||
1. 验证 `.env` 中已设置 `WINDSURF_FIREBASE_API_KEY` 和 `WINDSURF_API_KEY`
|
||||
2. 重启 OmniRoute 使新的环境变量生效
|
||||
3. 从 **仪表盘 → Providers → Windsurf → Reconnect** 重新运行 OAuth 流程
|
||||
|
||||
### Devin CLI 认证失败
|
||||
|
||||
**症状：**
|
||||
|
||||
- 调用 Devin 支持的工具时出现 "Devin CLI not found" 或 "auth failed"
|
||||
- CLI 运行时检查报告 `installed=false`
|
||||
|
||||
**原因：**
|
||||
|
||||
- `CLI_DEVIN_BIN` 指向的路径不存在
|
||||
- 主机上未安装 Devin CLI
|
||||
|
||||
**修复：**
|
||||
|
||||
1. 为你的平台安装 Devin CLI
|
||||
2. 在 `.env` 中设置 `CLI_DEVIN_BIN=/usr/local/bin/devin`（或实际路径）
|
||||
3. 重启 OmniRoute 并从 **仪表盘 → CLI Tools** 重新测试
|
||||
|
||||
### 模型冷却卡住（手动重置）
|
||||
|
||||
**症状：**
|
||||
|
||||
- 即便过期时间已过，某模型仍然显示在冷却列表中
|
||||
- Combo 路由在时间戳已过期的情况下仍然跳过该模型
|
||||
|
||||
**手动重置：**
|
||||
|
||||
- **仪表盘：** **Settings → Model Cooldowns** → 点击受影响卡片上的 **Re-enable**
|
||||
- **API：** 使用管理认证 headers 调用 `DELETE /api/resilience/model-cooldowns`
|
||||
|
||||
### Command Code 服务商连接返回 403
|
||||
|
||||
**症状：**
|
||||
|
||||
- 测试 Command Code 服务商连接时返回 403
|
||||
- 新添加后服务商卡片显示 "unauthorized"
|
||||
|
||||
**原因：** OAuth 流程未完成（未收到回调或 Token 未持久化）。
|
||||
|
||||
**修复：**
|
||||
|
||||
- 从 CLI 运行 `omniroute providers` 重新触发 OAuth 流程，或
|
||||
- 从 **仪表盘 → Providers → Command Code → Reconnect** 重新运行 OAuth
|
||||
|
||||
### ModelScope 返回过于激进的 429 冷却
|
||||
|
||||
**症状：**
|
||||
|
||||
- ModelScope 在少量请求后触发极短或立即的冷却
|
||||
- Combo 路由比预期更早地跳过 ModelScope
|
||||
|
||||
**原因：** ModelScope 会发出服务商专用的 `Retry-After` header。v3.8.0 对这些 header 进行了专门处理，而旧版本会将其误读为通用速率限制提示。
|
||||
|
||||
**修复：**
|
||||
|
||||
- 确认你使用的是 v3.8.0 或更高版本
|
||||
- 验证 **Settings → Resilience** 下的 `useUpstream429BreakerHints` 开关已启用
|
||||
|
||||
### 生产环境缺少 OMNIROUTE_WS_BRIDGE_SECRET
|
||||
|
||||
**症状：**
|
||||
|
||||
- 在远程生产主机上运行时，每个 Codex/Responses WebSocket bridge 请求都返回 401
|
||||
- WebSocket bridge 握手在连接后立即关闭
|
||||
|
||||
**原因：** 生产环境中缺少 `OMNIROUTE_WS_BRIDGE_SECRET` 环境变量。
|
||||
|
||||
**修复：**
|
||||
|
||||
1. 生成一个随机密钥：`openssl rand -hex 32`
|
||||
2. 在生产服务器环境中设置 `OMNIROUTE_WS_BRIDGE_SECRET=<random-secret>`（以及任何与该 bridge 通信的客户端）
|
||||
3. 重启 OmniRoute
|
||||
|
||||
### Responses API：后台模式降级为同步
|
||||
|
||||
**症状：**
|
||||
|
||||
- 日志警告：`background mode degraded to synchronous`
|
||||
- `background: true` 的请求返回了普通同步响应，而非后台任务句柄
|
||||
|
||||
**原因：** v3.8.0 有意将 Responses API 上的 `background: true` 降级为同步执行，同时发出警告。完整的异步后台执行是未来的交付内容。
|
||||
|
||||
**修复：**
|
||||
|
||||
- 调整客户端调用时不带 `background`，或
|
||||
- 等待后续版本提供完整的异步后台模式（关注更新日志）
|
||||
|
||||
---
|
||||
|
||||
## 仍然卡住了？
|
||||
|
||||
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
|
||||
- **API Reference**: See [`docs/reference/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/ARCHITECTURE.md`](../../../../docs/architecture/ARCHITECTURE.md)
|
||||
- **API 参考**：所有端点请参见 [`docs/reference/API_REFERENCE.md`](../../../../docs/reference/API_REFERENCE.md)
|
||||
- **健康仪表盘**：在 **仪表盘 → Health** 中查看实时系统状态
|
||||
- **格式转换器**：使用 **仪表盘 → Translator** 调试格式问题
|
||||
|
||||
@@ -1,56 +1,60 @@
|
||||
# OmniRoute — Uninstall Guide (中文 (简体))
|
||||
---
|
||||
title: "OmniRoute — 卸载指南"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/UNINSTALL.md) · 🇸🇦 [ar](../../ar/docs/UNINSTALL.md) · 🇧🇬 [bg](../../bg/docs/UNINSTALL.md) · 🇧🇩 [bn](../../bn/docs/UNINSTALL.md) · 🇨🇿 [cs](../../cs/docs/UNINSTALL.md) · 🇩🇰 [da](../../da/docs/UNINSTALL.md) · 🇩🇪 [de](../../de/docs/UNINSTALL.md) · 🇪🇸 [es](../../es/docs/UNINSTALL.md) · 🇮🇷 [fa](../../fa/docs/UNINSTALL.md) · 🇫🇮 [fi](../../fi/docs/UNINSTALL.md) · 🇫🇷 [fr](../../fr/docs/UNINSTALL.md) · 🇮🇳 [gu](../../gu/docs/UNINSTALL.md) · 🇮🇱 [he](../../he/docs/UNINSTALL.md) · 🇮🇳 [hi](../../hi/docs/UNINSTALL.md) · 🇭🇺 [hu](../../hu/docs/UNINSTALL.md) · 🇮🇩 [id](../../id/docs/UNINSTALL.md) · 🇮🇹 [it](../../it/docs/UNINSTALL.md) · 🇯🇵 [ja](../../ja/docs/UNINSTALL.md) · 🇰🇷 [ko](../../ko/docs/UNINSTALL.md) · 🇮🇳 [mr](../../mr/docs/UNINSTALL.md) · 🇲🇾 [ms](../../ms/docs/UNINSTALL.md) · 🇳🇱 [nl](../../nl/docs/UNINSTALL.md) · 🇳🇴 [no](../../no/docs/UNINSTALL.md) · 🇵🇭 [phi](../../phi/docs/UNINSTALL.md) · 🇵🇱 [pl](../../pl/docs/UNINSTALL.md) · 🇵🇹 [pt](../../pt/docs/UNINSTALL.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/UNINSTALL.md) · 🇷🇴 [ro](../../ro/docs/UNINSTALL.md) · 🇷🇺 [ru](../../ru/docs/UNINSTALL.md) · 🇸🇰 [sk](../../sk/docs/UNINSTALL.md) · 🇸🇪 [sv](../../sv/docs/UNINSTALL.md) · 🇰🇪 [sw](../../sw/docs/UNINSTALL.md) · 🇮🇳 [ta](../../ta/docs/UNINSTALL.md) · 🇮🇳 [te](../../te/docs/UNINSTALL.md) · 🇹🇭 [th](../../th/docs/UNINSTALL.md) · 🇹🇷 [tr](../../tr/docs/UNINSTALL.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/UNINSTALL.md) · 🇵🇰 [ur](../../ur/docs/UNINSTALL.md) · 🇻🇳 [vi](../../vi/docs/UNINSTALL.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/UNINSTALL.md)
|
||||
# OmniRoute — 卸载指南
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/guides/UNINSTALL.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/guides/UNINSTALL.md) | 🇪🇸 [Español](../../es/docs/guides/UNINSTALL.md) | 🇫🇷 [Français](../../fr/docs/guides/UNINSTALL.md) | 🇮🇹 [Italiano](../../it/docs/guides/UNINSTALL.md) | 🇷🇺 [Русский](../../ru/docs/guides/UNINSTALL.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/guides/UNINSTALL.md) | 🇩🇪 [Deutsch](../../de/docs/guides/UNINSTALL.md) | 🇮🇳 [हिन्दी](../../in/docs/guides/UNINSTALL.md) | 🇹🇭 [ไทย](../../th/docs/guides/UNINSTALL.md) | 🇺🇦 [Українська](../../uk-UA/docs/guides/UNINSTALL.md) | 🇸🇦 [العربية](../../ar/docs/guides/UNINSTALL.md) | 🇯🇵 [日本語](../../ja/docs/guides/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/guides/UNINSTALL.md) | 🇧🇬 [Български](../../bg/docs/guides/UNINSTALL.md) | 🇩🇰 [Dansk](../../da/docs/guides/UNINSTALL.md) | 🇫🇮 [Suomi](../../fi/docs/guides/UNINSTALL.md) | 🇮🇱 [עברית](../../he/docs/guides/UNINSTALL.md) | 🇭🇺 [Magyar](../../hu/docs/guides/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/guides/UNINSTALL.md) | 🇰🇷 [한국어](../../ko/docs/guides/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/guides/UNINSTALL.md) | 🇳🇱 [Nederlands](../../nl/docs/guides/UNINSTALL.md) | 🇳🇴 [Norsk](../../no/docs/guides/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/guides/UNINSTALL.md) | 🇷🇴 [Română](../../ro/docs/guides/UNINSTALL.md) | 🇵🇱 [Polski](../../pl/docs/guides/UNINSTALL.md) | 🇸🇰 [Slovenčina](../../sk/docs/guides/UNINSTALL.md) | 🇸🇪 [Svenska](../../sv/docs/guides/UNINSTALL.md) | 🇵🇭 [Filipino](../../phi/docs/guides/UNINSTALL.md) | 🇨🇿 [Čeština](../../cs/docs/guides/UNINSTALL.md)
|
||||
|
||||
本指南介绍如何从系统中彻底移除 OmniRoute。
|
||||
|
||||
---
|
||||
|
||||
This guide covers how to cleanly remove OmniRoute from your system.
|
||||
## 快速卸载（v3.6.2+）
|
||||
|
||||
---
|
||||
OmniRoute 提供两个内置脚本用于干净移除：
|
||||
|
||||
## Quick Uninstall (v3.6.2+)
|
||||
|
||||
OmniRoute provides two built-in scripts for clean removal:
|
||||
|
||||
### Keep Your Data
|
||||
### 保留数据
|
||||
|
||||
```bash
|
||||
npm run uninstall
|
||||
```
|
||||
|
||||
This removes the OmniRoute application but **preserves** your database, configurations, API keys, and provider settings in `~/.omniroute/`. Use this if you plan to reinstall later and want to keep your setup.
|
||||
此命令移除 OmniRoute 应用程序，但**保留** `~/.omniroute/` 中的数据库、配置、API Key 和服务商设置。如果你计划稍后重装并希望保留现有配置，请使用此方式。
|
||||
|
||||
### Full Removal
|
||||
### 完全移除
|
||||
|
||||
```bash
|
||||
npm run uninstall:full
|
||||
```
|
||||
|
||||
This removes the application **and permanently erases** all data:
|
||||
此命令移除应用程序并**永久删除**所有数据：
|
||||
|
||||
- Database (`storage.sqlite`)
|
||||
- Provider configurations and API keys
|
||||
- Backup files
|
||||
- Log files
|
||||
- All files in the `~/.omniroute/` directory
|
||||
- 数据库（`storage.sqlite`）
|
||||
- 服务商配置和 API Key
|
||||
- 备份文件
|
||||
- 日志文件
|
||||
- `~/.omniroute/` 目录下的所有文件
|
||||
|
||||
> ⚠️ **Warning:** `npm run uninstall:full` is irreversible. All your provider connections, combos, API keys, and usage history will be permanently deleted.
|
||||
> ⚠️ **警告：** `npm run uninstall:full` 不可逆。所有服务商连接、Combo、API Key 和用量历史将被永久删除。
|
||||
|
||||
---
|
||||
|
||||
## Manual Uninstall
|
||||
## 手动卸载
|
||||
|
||||
### NPM Global Install
|
||||
### npm 全局安装
|
||||
|
||||
```bash
|
||||
# Remove the global package
|
||||
# 移除全局包
|
||||
npm uninstall -g omniroute
|
||||
|
||||
# (Optional) Remove data directory
|
||||
# （可选）删除数据目录
|
||||
rm -rf ~/.omniroute
|
||||
```
|
||||
|
||||
### pnpm Global Install
|
||||
### pnpm 全局安装
|
||||
|
||||
```bash
|
||||
pnpm uninstall -g omniroute
|
||||
@@ -60,97 +64,97 @@ rm -rf ~/.omniroute
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# Stop and remove the container
|
||||
# 停止并移除容器
|
||||
docker stop omniroute
|
||||
docker rm omniroute
|
||||
|
||||
# Remove the volume (deletes all data)
|
||||
# 移除卷（删除所有数据）
|
||||
docker volume rm omniroute-data
|
||||
|
||||
# (Optional) Remove the image
|
||||
# （可选）移除镜像
|
||||
docker rmi diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
# Stop and remove containers
|
||||
# 停止并移除容器
|
||||
docker compose down
|
||||
|
||||
# Also remove volumes (deletes all data)
|
||||
# 同时移除卷（删除所有数据）
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
### Electron Desktop App
|
||||
### Electron 桌面应用
|
||||
|
||||
**Windows:**
|
||||
**Windows：**
|
||||
|
||||
- Open `Settings → Apps → OmniRoute → Uninstall`
|
||||
- Or run the NSIS uninstaller from the install directory
|
||||
- 打开 `设置 → 应用 → OmniRoute → 卸载`
|
||||
- 或从安装目录运行 NSIS 卸载程序
|
||||
|
||||
**macOS:**
|
||||
**macOS：**
|
||||
|
||||
- Drag `OmniRoute.app` from `/Applications` to Trash
|
||||
- Remove data: `rm -rf ~/Library/Application Support/omniroute`
|
||||
- 将 `OmniRoute.app` 从 `/Applications` 拖入废纸篓
|
||||
- 删除数据：`rm -rf ~/Library/Application Support/omniroute`
|
||||
|
||||
**Linux:**
|
||||
**Linux：**
|
||||
|
||||
- Remove the AppImage file
|
||||
- Remove data: `rm -rf ~/.omniroute`
|
||||
- 删除 AppImage 文件
|
||||
- 删除数据：`rm -rf ~/.omniroute`
|
||||
|
||||
### Source Install (git clone)
|
||||
### 源码安装（git clone）
|
||||
|
||||
```bash
|
||||
# Remove the cloned directory
|
||||
# 删除克隆目录
|
||||
rm -rf /path/to/omniroute
|
||||
|
||||
# (Optional) Remove data directory
|
||||
# （可选）删除数据目录
|
||||
rm -rf ~/.omniroute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Directories
|
||||
## 数据目录
|
||||
|
||||
OmniRoute stores data in the following locations by default:
|
||||
OmniRoute 默认将数据存储在以下位置：
|
||||
|
||||
| Platform | Default Path | Override |
|
||||
| 平台 | 默认路径 | 覆盖方式 |
|
||||
| ------------- | ----------------------------- | ------------------------- |
|
||||
| Linux | `~/.omniroute/` | `DATA_DIR` env var |
|
||||
| macOS | `~/.omniroute/` | `DATA_DIR` env var |
|
||||
| Windows | `%APPDATA%/omniroute/` | `DATA_DIR` env var |
|
||||
| Docker | `/app/data/` (mounted volume) | `DATA_DIR` env var |
|
||||
| XDG-compliant | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` env var |
|
||||
| Linux | `~/.omniroute/` | `DATA_DIR` 环境变量 |
|
||||
| macOS | `~/.omniroute/` | `DATA_DIR` 环境变量 |
|
||||
| Windows | `%APPDATA%/omniroute/` | `DATA_DIR` 环境变量 |
|
||||
| Docker | `/app/data/`（挂载卷） | `DATA_DIR` 环境变量 |
|
||||
| XDG 兼容 | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` 环境变量 |
|
||||
|
||||
### Files in the data directory
|
||||
### 数据目录中的文件
|
||||
|
||||
| File/Directory | Description |
|
||||
| -------------------- | ------------------------------------------------- |
|
||||
| `storage.sqlite` | Main database (providers, combos, settings, keys) |
|
||||
| `storage.sqlite-wal` | SQLite write-ahead log (temporary) |
|
||||
| `storage.sqlite-shm` | SQLite shared memory (temporary) |
|
||||
| `call_logs/` | Request payload archives |
|
||||
| `backups/` | Automatic database backups |
|
||||
| `log.txt` | Legacy request log (optional) |
|
||||
| 文件/目录 | 说明 |
|
||||
| --------------------- | -------------------------------------------------- |
|
||||
| `storage.sqlite` | 主数据库（服务商、Combo、设置、Key） |
|
||||
| `storage.sqlite-wal` | SQLite 预写日志（临时文件） |
|
||||
| `storage.sqlite-shm` | SQLite 共享内存（临时文件） |
|
||||
| `call_logs/` | 请求载荷归档 |
|
||||
| `backups/` | 自动数据库备份 |
|
||||
| `log.txt` | 旧版请求日志（可选） |
|
||||
|
||||
---
|
||||
|
||||
## Verify Complete Removal
|
||||
## 验证完全移除
|
||||
|
||||
After uninstalling, verify there are no remaining files:
|
||||
卸载后，确认没有残留文件：
|
||||
|
||||
```bash
|
||||
# Check for global npm package
|
||||
# 检查全局 npm 包
|
||||
npm list -g omniroute 2>/dev/null
|
||||
|
||||
# Check for data directory
|
||||
# 检查数据目录
|
||||
ls -la ~/.omniroute/ 2>/dev/null
|
||||
|
||||
# Check for running processes
|
||||
# 检查运行中的进程
|
||||
pgrep -f omniroute
|
||||
```
|
||||
|
||||
If any process is still running, stop it:
|
||||
如果有进程仍在运行，停止它：
|
||||
|
||||
```bash
|
||||
pkill -f omniroute
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,170 +1,181 @@
|
||||
# Test Coverage Plan (中文 (简体))
|
||||
# 测试覆盖计划 (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/COVERAGE_PLAN.md) · 🇸🇦 [ar](../../ar/docs/COVERAGE_PLAN.md) · 🇧🇬 [bg](../../bg/docs/COVERAGE_PLAN.md) · 🇧🇩 [bn](../../bn/docs/COVERAGE_PLAN.md) · 🇨🇿 [cs](../../cs/docs/COVERAGE_PLAN.md) · 🇩🇰 [da](../../da/docs/COVERAGE_PLAN.md) · 🇩🇪 [de](../../de/docs/COVERAGE_PLAN.md) · 🇪🇸 [es](../../es/docs/COVERAGE_PLAN.md) · 🇮🇷 [fa](../../fa/docs/COVERAGE_PLAN.md) · 🇫🇮 [fi](../../fi/docs/COVERAGE_PLAN.md) · 🇫🇷 [fr](../../fr/docs/COVERAGE_PLAN.md) · 🇮🇳 [gu](../../gu/docs/COVERAGE_PLAN.md) · 🇮🇱 [he](../../he/docs/COVERAGE_PLAN.md) · 🇮🇳 [hi](../../hi/docs/COVERAGE_PLAN.md) · 🇭🇺 [hu](../../hu/docs/COVERAGE_PLAN.md) · 🇮🇩 [id](../../id/docs/COVERAGE_PLAN.md) · 🇮🇹 [it](../../it/docs/COVERAGE_PLAN.md) · 🇯🇵 [ja](../../ja/docs/COVERAGE_PLAN.md) · 🇰🇷 [ko](../../ko/docs/COVERAGE_PLAN.md) · 🇮🇳 [mr](../../mr/docs/COVERAGE_PLAN.md) · 🇲🇾 [ms](../../ms/docs/COVERAGE_PLAN.md) · 🇳🇱 [nl](../../nl/docs/COVERAGE_PLAN.md) · 🇳🇴 [no](../../no/docs/COVERAGE_PLAN.md) · 🇵🇭 [phi](../../phi/docs/COVERAGE_PLAN.md) · 🇵🇱 [pl](../../pl/docs/COVERAGE_PLAN.md) · 🇵🇹 [pt](../../pt/docs/COVERAGE_PLAN.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) · 🇷🇴 [ro](../../ro/docs/COVERAGE_PLAN.md) · 🇷🇺 [ru](../../ru/docs/COVERAGE_PLAN.md) · 🇸🇰 [sk](../../sk/docs/COVERAGE_PLAN.md) · 🇸🇪 [sv](../../sv/docs/COVERAGE_PLAN.md) · 🇰🇪 [sw](../../sw/docs/COVERAGE_PLAN.md) · 🇮🇳 [ta](../../ta/docs/COVERAGE_PLAN.md) · 🇮🇳 [te](../../te/docs/COVERAGE_PLAN.md) · 🇹🇭 [th](../../th/docs/COVERAGE_PLAN.md) · 🇹🇷 [tr](../../tr/docs/COVERAGE_PLAN.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) · 🇵🇰 [ur](../../ur/docs/COVERAGE_PLAN.md) · 🇻🇳 [vi](../../vi/docs/COVERAGE_PLAN.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md)
|
||||
|
||||
---
|
||||
|
||||
Last updated: 2026-03-28
|
||||
最后更新：2026-06-28
|
||||
|
||||
## Baseline
|
||||
> 状态（2026-05-13 测量）：行覆盖率 82.58%，语句覆盖率 82.58%，函数覆盖率 84.23%，分支覆盖率 75.22%。第 1-5 阶段已完成。当前聚焦第 6 阶段（>=85%）和第 7 阶段（>=90%）。
|
||||
|
||||
There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful.
|
||||
## 基线
|
||||
|
||||
| Metric | Scope | Statements / Lines | Branches | Functions | Notes |
|
||||
| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- |
|
||||
| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` |
|
||||
| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` |
|
||||
| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve |
|
||||
覆盖率数据因报告计算方式而异，存在多种口径。对于规划而言，仅其中一个有参考价值。
|
||||
|
||||
The recommended baseline is the number to optimize against.
|
||||
| 指标 | 范围 | 语句 / 行 | 分支 | 函数 | 说明 |
|
||||
| -------- | -------------------------------------------------- | --------: | -----: | -----: | -------------------------------------------- |
|
||||
| 旧版 | 旧版 `npm run test:coverage` | 79.42% | 75.15% | 67.94% | 虚高：统计了测试文件且排除了 `open-sse` |
|
||||
| 诊断 | 仅源码，排除测试且排除 `open-sse` | 68.16% | 63.55% | 64.06% | 仅用于隔离 `src/**` |
|
||||
| 推荐基线 | 仅源码，排除测试且包含 `open-sse` | 82.58% | 75.22% | 84.23% | 这是需要提升的项目级覆盖率基线 |
|
||||
|
||||
## Rules
|
||||
推荐基线是优化工作的目标数值。
|
||||
|
||||
- Coverage targets apply to source files, not to `tests/**`.
|
||||
- `open-sse/**` is part of the product and must remain in scope.
|
||||
- New code should not reduce coverage in touched areas.
|
||||
- Prefer testing behavior and branch outcomes over implementation details.
|
||||
- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`.
|
||||
## 规则
|
||||
|
||||
## Current command set
|
||||
- 覆盖率目标针对源文件，不针对 `tests/**`。
|
||||
- `open-sse/**` 是产品的一部分，必须纳入统计范围。
|
||||
- 新增代码不应降低其影响范围内的覆盖率。
|
||||
- 优先测试行为和分支结果，而非实现细节。
|
||||
- 对 `src/lib/db/**`，优先使用临时 SQLite 数据库和小型 fixture，而非宽泛的 mock。
|
||||
|
||||
## 当前命令集
|
||||
|
||||
- `npm run test:coverage`
|
||||
- Main source coverage gate for the unit test suite
|
||||
- Generates `text-summary`, `html`, `json-summary`, and `lcov`
|
||||
- 单元测试套件的主源码覆盖率门禁
|
||||
- 生成 `text-summary`、`html`、`json-summary` 和 `lcov`
|
||||
- `npm run coverage:report`
|
||||
- Detailed file-by-file report from the latest run
|
||||
- 基于最近一次运行的逐文件详细报告
|
||||
- `npm run test:coverage:legacy`
|
||||
- Historical comparison only
|
||||
- 仅用于历史对比
|
||||
|
||||
## Milestones
|
||||
## 里程碑
|
||||
|
||||
| Phase | Target | Focus |
|
||||
| ------- | ---------------------: | ------------------------------------------------- |
|
||||
| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage |
|
||||
| Phase 2 | 65% statements / lines | DB and route foundations |
|
||||
| Phase 3 | 70% statements / lines | Provider validation and usage analytics |
|
||||
| Phase 4 | 75% statements / lines | `open-sse` translators and helpers |
|
||||
| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches |
|
||||
| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites |
|
||||
| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet |
|
||||
| 阶段 | 目标 | 焦点 | 状态 |
|
||||
| -------- | ---------------------: | ---------------------------------------- | -------- |
|
||||
| 第 1 阶段 | 60% 语句 / 行 | 速赢项和低风险工具函数覆盖 | ✅ 已完成 |
|
||||
| 第 2 阶段 | 65% 语句 / 行 | 数据库和路由基础 | ✅ 已完成 |
|
||||
| 第 3 阶段 | 70% 语句 / 行 | 服务商校验和用量分析 | ✅ 已完成 |
|
||||
| 第 4 阶段 | 75% 语句 / 行 | `open-sse` 翻译器与辅助函数 | ✅ 已完成 |
|
||||
| 第 5 阶段 | 80% 语句 / 行 | `open-sse` 处理器和执行器分支 | ✅ 已完成 |
|
||||
| 第 6 阶段 | 85% 语句 / 行 | 高难度边界情况、分支欠账、回归套件 | 进行中 |
|
||||
| 第 7 阶段 | 90% 语句 / 行 | 最终扫尾、填补缺口、严格递增 | 待开始 |
|
||||
|
||||
Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines.
|
||||
每个阶段都应推动分支和函数覆盖率递增，但主要硬性目标是语句 / 行覆盖率。
|
||||
|
||||
## Priority hotspots
|
||||
## 优先热点
|
||||
|
||||
These files or areas offer the best return for the next phases:
|
||||
以下文件当前行覆盖率最低（< 60%），在第 6-7 阶段性价比最高。数据来自 2026-05-13 的 `coverage/coverage-summary.json`：
|
||||
|
||||
1. `open-sse/handlers`
|
||||
- `chatCore.ts` at 7.57%
|
||||
- Overall directory at 29.07%
|
||||
2. `open-sse/translator/request`
|
||||
- Overall directory at 36.39%
|
||||
- Many translators are still near single-digit coverage
|
||||
3. `open-sse/translator/response`
|
||||
- Overall directory at 8.07%
|
||||
4. `open-sse/executors`
|
||||
- Overall directory at 36.62%
|
||||
5. `src/lib/db`
|
||||
- `models.ts` at 20.66%
|
||||
- `registeredKeys.ts` at 34.46%
|
||||
- `modelComboMappings.ts` at 36.25%
|
||||
- `settings.ts` at 46.40%
|
||||
- `webhooks.ts` at 33.33%
|
||||
6. `src/lib/usage`
|
||||
- `usageHistory.ts` at 21.12%
|
||||
- `usageStats.ts` at 9.56%
|
||||
- `costCalculator.ts` at 30.00%
|
||||
7. `src/lib/providers`
|
||||
- `validation.ts` at 41.16%
|
||||
8. Low-risk utility and API files for early gains
|
||||
- `src/shared/utils/upstreamError.ts`
|
||||
- `src/shared/utils/apiAuth.ts`
|
||||
- `src/lib/api/errorResponse.ts`
|
||||
- `src/app/api/settings/require-login/route.ts`
|
||||
- `src/app/api/providers/[id]/models/route.ts`
|
||||
| # | 文件 | 行 % |
|
||||
| --- | ------------------------------------------------------------ | -----: |
|
||||
| 1 | `open-sse/services/compression/validation.ts` | 7.87% |
|
||||
| 2 | `src/app/api/v1/batches/route.ts` | 9.67% |
|
||||
| 3 | `src/app/docs/components/FeedbackWidget.tsx` | 9.80% |
|
||||
| 4 | `open-sse/services/compression/toolResultCompressor.ts` | 10.00% |
|
||||
| 5 | `src/app/docs/components/DocCodeBlocks.tsx` | 10.63% |
|
||||
| 6 | `open-sse/services/compression/engines/rtk/lineFilter.ts` | 10.96% |
|
||||
| 7 | `open-sse/services/specificityRules.ts` | 11.28% |
|
||||
| 8 | `src/mitm/systemCommands.ts` | 12.19% |
|
||||
| 9 | `open-sse/services/compression/aggressive.ts` | 12.77% |
|
||||
| 10 | `src/app/api/v1/batches/[id]/cancel/route.ts` | 12.98% |
|
||||
| 11 | `open-sse/services/compression/progressiveAging.ts` | 13.26% |
|
||||
| 12 | `open-sse/services/compression/engines/rtk/smartTruncate.ts` | 13.43% |
|
||||
| 13 | `open-sse/services/compression/engines/rtk/deduplicator.ts` | 13.51% |
|
||||
| 14 | `src/lib/cloudAgent/agents/jules.ts` | 13.52% |
|
||||
| 15 | `open-sse/services/compression/lite.ts` | 14.46% |
|
||||
| 16 | `src/app/api/v1/rerank/route.ts` | 14.94% |
|
||||
| 17 | `open-sse/services/compression/preservation.ts` | 15.07% |
|
||||
| 18 | `src/lib/cloudAgent/agents/codex.ts` | 15.54% |
|
||||
| 19 | `open-sse/services/tierResolver.ts` | 16.66% |
|
||||
| 20 | `src/app/docs/components/DocsLazyWrapper.tsx` | 16.66% |
|
||||
|
||||
## Execution checklist
|
||||
第 6-7 阶段的主题：
|
||||
|
||||
### Phase 1: 56.95% -> 60%
|
||||
- `open-sse/services/compression/**` 是低覆盖率最密集的聚类，占据了剩余缺口的大部分。
|
||||
- 批量处理和重排序 API 路由（`src/app/api/v1/batches/**`、`src/app/api/v1/rerank/route.ts`）需要处理器级测试。
|
||||
- 云代理适配器（`src/lib/cloudAgent/agents/jules.ts`、`codex.ts`）和 `tierResolver.ts` 需要场景测试。
|
||||
- 文档界面组件和 `src/mitm/systemCommands.ts` 优先级较低，但属于低成本的分支覆盖收益。
|
||||
|
||||
- [x] Fix coverage metric so it reflects source code instead of test files
|
||||
- [x] Keep a legacy coverage script for comparison
|
||||
- [x] Record the baseline and hotspots in-repo
|
||||
- [ ] Add focused tests for low-risk utilities:
|
||||
## 执行检查清单
|
||||
|
||||
### 第 1 阶段：56.95% -> 60%
|
||||
|
||||
- [x] 修复覆盖率指标，使其反映源码而非测试文件
|
||||
- [x] 保留旧版覆盖率脚本用于对比
|
||||
- [x] 在仓库中记录基线和热点
|
||||
- [ ] 为低风险工具函数添加专项测试：
|
||||
- `src/shared/utils/upstreamError.ts`
|
||||
- `src/shared/utils/fetchTimeout.ts`
|
||||
- `src/lib/api/errorResponse.ts`
|
||||
- `src/shared/utils/apiAuth.ts`
|
||||
- `src/lib/display/names.ts`
|
||||
- [ ] Add route tests for:
|
||||
- [ ] 为以下路由添加测试：
|
||||
- `src/app/api/settings/require-login/route.ts`
|
||||
- `src/app/api/providers/[id]/models/route.ts`
|
||||
|
||||
### Phase 2: 60% -> 65%
|
||||
### 第 2 阶段：60% -> 65%
|
||||
|
||||
- [ ] Add DB-backed tests for:
|
||||
- [ ] 为以下模块添加数据库驱动测试：
|
||||
- `src/lib/db/modelComboMappings.ts`
|
||||
- `src/lib/db/settings.ts`
|
||||
- `src/lib/db/registeredKeys.ts`
|
||||
- [ ] Cover branch behavior in:
|
||||
- [ ] 覆盖以下模块的分支行为：
|
||||
- `src/lib/providers/validation.ts`
|
||||
- `src/app/api/v1/embeddings/route.ts`
|
||||
- `src/app/api/v1/moderations/route.ts`
|
||||
|
||||
### Phase 3: 65% -> 70%
|
||||
### 第 3 阶段：65% -> 70%
|
||||
|
||||
- [ ] Add usage analytics tests for:
|
||||
- [ ] 为以下模块添加用量分析测试：
|
||||
- `src/lib/usage/usageHistory.ts`
|
||||
- `src/lib/usage/usageStats.ts`
|
||||
- `src/lib/usage/costCalculator.ts`
|
||||
- [ ] Expand route coverage for proxy management and settings branches
|
||||
- [ ] 扩展代理管理和设置的分支路由覆盖
|
||||
|
||||
### Phase 4: 70% -> 75%
|
||||
### 第 4 阶段：70% -> 75%
|
||||
|
||||
- [ ] Cover translator helpers and central translation paths:
|
||||
- [ ] 覆盖翻译器辅助函数和核心翻译路径：
|
||||
- `open-sse/translator/index.ts`
|
||||
- `open-sse/translator/helpers/*`
|
||||
- `open-sse/translator/request/*`
|
||||
- `open-sse/translator/response/*`
|
||||
|
||||
### Phase 5: 75% -> 80%
|
||||
### 第 5 阶段：75% -> 80%
|
||||
|
||||
- [ ] Add handler-level tests for:
|
||||
- [ ] 为以下模块添加处理器级测试：
|
||||
- `open-sse/handlers/chatCore.ts`
|
||||
- `open-sse/handlers/responsesHandler.js`
|
||||
- `open-sse/handlers/imageGeneration.js`
|
||||
- `open-sse/handlers/embeddings.js`
|
||||
- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides
|
||||
- [ ] 添加针对服务商特定认证、重试和端点覆盖的执行器分支覆盖
|
||||
|
||||
### Phase 6: 80% -> 85%
|
||||
### 第 6 阶段：80% -> 85%
|
||||
|
||||
- [ ] Merge more edge-case suites into the main coverage path
|
||||
- [ ] Increase function coverage for DB modules with weak constructor/helper coverage
|
||||
- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers
|
||||
- [ ] 将更多边界情况套件合并到主覆盖路径
|
||||
- [ ] 提升构造函数/辅助函数覆盖率较弱的数据库模块的函数覆盖
|
||||
- [ ] 填补 `settings.ts`、`registeredKeys.ts`、`validation.ts` 和翻译器辅助函数中的分支缺口
|
||||
|
||||
### Phase 7: 85% -> 90%
|
||||
### 第 7 阶段：85% -> 90%
|
||||
|
||||
- [ ] Treat the remaining low-coverage files as blockers
|
||||
- [ ] Add regression tests for every uncovered production bug fixed during the push to 90%
|
||||
- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs
|
||||
- [ ] 将剩余低覆盖率文件视为阻塞项
|
||||
- [ ] 为冲刺 90% 期间修复的所有未覆盖生产缺陷添加回归测试
|
||||
- [ ] 仅在本地基线至少连续两次运行稳定后，再提升 CI 中的覆盖率门禁
|
||||
|
||||
## Ratchet policy
|
||||
## 递增策略
|
||||
|
||||
Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer.
|
||||
仅在项目实际以充裕余量超越下一里程碑后，才更新 `npm run test:coverage` 的阈值。
|
||||
|
||||
Recommended ratchet sequence:
|
||||
**当前门禁：** `npm run test:coverage` 执行 **60 语句 / 60 行 / 60 函数 / 60 分支** 的标准（该指标在 Quality-Gates Fase 6A.1 中重新校准 — 此前 82.58% 的基线虚高，因为它统计了测试文件且排除了 `open-sse`）。`test:coverage:legacy` 命令保留了旧的 50/50/50 指标用于历史对比。
|
||||
|
||||
若要基于最新报告进行临时阈值检查，请使用：
|
||||
|
||||
```bash
|
||||
node scripts/check/test-report-summary.mjs --threshold 75
|
||||
```
|
||||
|
||||
推荐递增序列（顺序为 `语句-行 / 分支 / 函数`）：
|
||||
|
||||
1. 55/60/55
|
||||
2. 60/62/58
|
||||
3. 65/64/62
|
||||
4. 70/66/66
|
||||
5. 75/70/72
|
||||
5. 75/70/72 <-- 当前门禁 (75/70/75)
|
||||
6. 80/75/78
|
||||
7. 85/80/84
|
||||
8. 90/85/88
|
||||
|
||||
Order is `statements-lines / branches / functions`.
|
||||
下一递增目标为 `80/75/78`，待分支覆盖率连续两次运行保持在 78% 以上时生效。
|
||||
|
||||
## Known gap
|
||||
## 已知缺口
|
||||
|
||||
The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb.
|
||||
当前覆盖率命令测量的是主 Node 单元套件，并包含由其触达的源码（包括 `open-sse`）。它尚未将 Vitest 覆盖率合并到统一的报告中。这一合并值得后续完成，但不构成从 60% 向 80% 冲刺的阻塞项。
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# OmniRoute Fly.io 部署指南 (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md)
|
||||
|
||||
---
|
||||
title: "OmniRoute Fly.io 部署指南"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
# OmniRoute Fly.io 部署指南
|
||||
|
||||
本文档记录 OmniRoute 在 Fly.io 上的实际部署方法，适用于两类场景：
|
||||
|
||||
@@ -143,6 +145,7 @@ flyctl deploy
|
||||
- `JWT_SECRET`
|
||||
- `MACHINE_ID_SALT`
|
||||
- `NEXT_PUBLIC_BASE_URL`
|
||||
- `OMNIROUTE_WS_BRIDGE_SECRET` (生产环境必需 / required in production / obrigatório em produção — 用于 WebSocket 桥接鉴权 / used for WebSocket bridge authentication)
|
||||
- `STORAGE_ENCRYPTION_KEY`
|
||||
|
||||
### 5.2 关于 `INITIAL_PASSWORD`
|
||||
@@ -166,14 +169,15 @@ flyctl deploy
|
||||
|
||||
建议放入 Fly Secrets：
|
||||
|
||||
| 变量名 | 是否推荐 | 说明 |
|
||||
| ------------------------ | -------- | ------------------------------ |
|
||||
| `API_KEY_SECRET` | 必需 | API Key 生成与校验使用 |
|
||||
| `JWT_SECRET` | 必需 | 登录态和 JWT 签名使用 |
|
||||
| `STORAGE_ENCRYPTION_KEY` | 强烈推荐 | 加密存储敏感连接信息 |
|
||||
| `MACHINE_ID_SALT` | 推荐 | 生成稳定机器标识 |
|
||||
| `INITIAL_PASSWORD` | 可选 | 首次部署时直接指定后台初始密码 |
|
||||
| OAuth/API 私密凭证 | 按需 | 各类外部平台鉴权配置 |
|
||||
| 变量名 | 是否推荐 | 说明 |
|
||||
| ---------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `API_KEY_SECRET` | 必需 | API Key 生成与校验使用 |
|
||||
| `JWT_SECRET` | 必需 | 登录态和 JWT 签名使用 |
|
||||
| `OMNIROUTE_WS_BRIDGE_SECRET` | 生产必需 (required / obrigatório) | WebSocket 桥接鉴权密钥 (WebSocket bridge auth / chave de autenticação da ponte WebSocket) |
|
||||
| `STORAGE_ENCRYPTION_KEY` | 强烈推荐 | 加密存储敏感连接信息 |
|
||||
| `MACHINE_ID_SALT` | 推荐 | 生成稳定机器标识 |
|
||||
| `INITIAL_PASSWORD` | 可选 | 首次部署时直接指定后台初始密码 |
|
||||
| OAuth/API 私密凭证 | 按需 | 各类外部平台鉴权配置 |
|
||||
|
||||
### 6.2 当前项目推荐值
|
||||
|
||||
@@ -187,6 +191,32 @@ flyctl deploy
|
||||
- `DATA_DIR=/data` 非常关键，必须与 Fly Volume 挂载点一致
|
||||
- `NEXT_PUBLIC_BASE_URL` 用于调度器和前端回调等场景
|
||||
|
||||
### 6.3 OAuth 回调地址配置 (OAuth callback URL / URL de callback OAuth)
|
||||
|
||||
如果你需要在 Fly.io 部署上启用 OAuth 登录类的服务商（例如 Antigravity、Gemini、Cursor 等），必须确保以下两点：
|
||||
(If you need to enable OAuth-based providers — e.g. Antigravity, Gemini, Cursor — on the Fly.io deployment, make sure of the following two points. / Se precisar habilitar providers via OAuth — p.ex. Antigravity, Gemini, Cursor — na implantação Fly.io, garanta os dois pontos abaixo.)
|
||||
|
||||
1. **设置 `NEXT_PUBLIC_BASE_URL` 指向你公开的 HTTPS 域名 (set `NEXT_PUBLIC_BASE_URL` to the public HTTPS domain / defina `NEXT_PUBLIC_BASE_URL` para o domínio HTTPS público)**
|
||||
|
||||
```powershell
|
||||
flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute
|
||||
```
|
||||
|
||||
如果你使用了自定义域名 (if using a custom domain / se usar um domínio personalizado)，请替换为对应域名 (e.g. `https://omniroute.yourdomain.com`)。
|
||||
|
||||
2. **在服务商控制台配置回调 URL (configure the callback URL on the provider console / configure a URL de callback no painel do provider)**
|
||||
|
||||
所有 OAuth 服务商共用同一个回调路径 `/callback`，不带服务商段 (all OAuth providers share the single callback path `/callback` — there is NO per-provider callback route / todos os providers OAuth usam o mesmo callback `/callback`, sem segmento por provider)：
|
||||
|
||||
```text
|
||||
<NEXT_PUBLIC_BASE_URL>/callback
|
||||
```
|
||||
|
||||
例如 (e.g. / p.ex.)，无论是 Gemini、Antigravity、Cursor 还是 GitLab Duo (regardless of Gemini / Antigravity / Cursor / GitLab Duo, etc.)：
|
||||
- `https://omniroute.fly.dev/callback`
|
||||
|
||||
如果 `NEXT_PUBLIC_BASE_URL` 与服务商控制台中注册的回调 URL 不一致，OAuth 流程会在浏览器回跳阶段失败 (mismatch between `NEXT_PUBLIC_BASE_URL` and the registered callback URL will cause OAuth to fail at the browser redirect step / divergência entre `NEXT_PUBLIC_BASE_URL` e a URL de callback registrada quebra o OAuth no redirect do navegador)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一键设置参数
|
||||
@@ -203,17 +233,29 @@ $apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Min
|
||||
$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
|
||||
$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
|
||||
$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
|
||||
$wsBridgeSecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
|
||||
|
||||
flyctl secrets set `
|
||||
API_KEY_SECRET=$apiKeySecret `
|
||||
JWT_SECRET=$jwtSecret `
|
||||
MACHINE_ID_SALT=$machineIdSalt `
|
||||
STORAGE_ENCRYPTION_KEY=$storageKey `
|
||||
OMNIROUTE_WS_BRIDGE_SECRET=$wsBridgeSecret `
|
||||
DATA_DIR=/data `
|
||||
NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
|
||||
-a omniroute
|
||||
```
|
||||
|
||||
在 Linux / macOS 上，也可以直接用 `openssl rand -hex 32` 生成 (on Linux / macOS, you can also use `openssl rand -hex 32` / em Linux / macOS, também é possível usar `openssl rand -hex 32`)：
|
||||
|
||||
```bash
|
||||
flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute
|
||||
```
|
||||
|
||||
说明 (notes / observações)：
|
||||
|
||||
- `OMNIROUTE_WS_BRIDGE_SECRET` 在生产环境必需，缺失会导致 WebSocket 桥接握手失败 (required in production; missing it breaks WebSocket bridge handshake / obrigatório em produção; sem ele o handshake da ponte WebSocket falha)
|
||||
|
||||
如果你还要加初始密码：
|
||||
|
||||
```powershell
|
||||
@@ -286,6 +328,8 @@ git describe --tags --always
|
||||
git show --no-patch --oneline v3.4.7
|
||||
```
|
||||
|
||||
> 注 (note / nota)：当前项目版本为 `v3.8.0` (current project version is `v3.8.0` / a versão atual do projeto é `v3.8.0`)。下文中的 `v3.4.7` 仅为历史示例 (the `v3.4.7` references below are kept as historical examples only / as referências a `v3.4.7` abaixo são apenas exemplos históricos)；实际发布时请使用 `:latest` 或当前版本标签 (e.g. `:v3.8.0`) (use `:latest` or the current version tag — e.g. `:v3.8.0` — for actual releases / use `:latest` ou a tag da versão atual — p.ex. `:v3.8.0` — em releases reais)。
|
||||
|
||||
如果你想合并上游最新 `main`，并强制保留 fork 当前的 `fly.toml`，可按下面流程执行：
|
||||
|
||||
```powershell
|
||||
@@ -323,7 +367,7 @@ git merge-base --is-ancestor v3.4.7 upstream/main
|
||||
6. `flyctl status -a omniroute`
|
||||
7. `flyctl logs --no-tail -a omniroute`
|
||||
|
||||
这就是当前项目升级到 `v3.4.7` 时使用的实际流程。
|
||||
这就是当前项目升级到 `v3.4.7` 时使用的实际流程 (示例为历史版本，当前实际版本是 `v3.8.0` / example refers to a historical version; the current actual version is `v3.8.0` / o exemplo refere-se a uma versão histórica; a versão atual é `v3.8.0`)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,44 +1,326 @@
|
||||
# Release Checklist (中文 (简体))
|
||||
---
|
||||
title: "发布清单"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../../ar/docs/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../../bg/docs/RELEASE_CHECKLIST.md) · 🇧🇩 [bn](../../bn/docs/RELEASE_CHECKLIST.md) · 🇨🇿 [cs](../../cs/docs/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../../da/docs/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../../de/docs/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../../es/docs/RELEASE_CHECKLIST.md) · 🇮🇷 [fa](../../fa/docs/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../../fi/docs/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../../fr/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [gu](../../gu/docs/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../../he/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [hi](../../hi/docs/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../../hu/docs/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../../id/docs/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../../it/docs/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../../ja/docs/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../../ko/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [mr](../../mr/docs/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../../ms/docs/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../../nl/docs/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../../no/docs/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../../phi/docs/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../../pl/docs/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../../pt/docs/RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../../ro/docs/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../../ru/docs/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../../sk/docs/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../../sv/docs/RELEASE_CHECKLIST.md) · 🇰🇪 [sw](../../sw/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [ta](../../ta/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [te](../../te/docs/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../../th/docs/RELEASE_CHECKLIST.md) · 🇹🇷 [tr](../../tr/docs/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) · 🇵🇰 [ur](../../ur/docs/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../../vi/docs/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md)
|
||||
# 发布清单
|
||||
|
||||
> **最后更新：** 2026-06-28 — v3.8.40
|
||||
> 精简的发布流程，利用 Claude Code 技能实现自动化。
|
||||
>
|
||||
> **Manter a fila/branch verdes entre releases:** veja [RELEASE_GREEN.md](./RELEASE_GREEN.md)
|
||||
> (família `/green-prs` + `npm run check:release-green` + `/babysit` + nightly). Rodar
|
||||
> periodicamente — e principalmente **antes** deste checklist — faz a release PR nascer verde.
|
||||
|
||||
## 概述
|
||||
|
||||
```bash
|
||||
# 1. 更新版本号 + 生成变更日志（技能）
|
||||
/version-bump-cc patch # 或 minor / major
|
||||
|
||||
# 2. 本地运行质量门禁
|
||||
npm run check # lint + 测试
|
||||
npm run test:coverage # 完整覆盖率门禁（60/60/60/60）
|
||||
|
||||
# 3. 构建与冒烟测试
|
||||
npm run build
|
||||
npm run test:e2e # 可选但推荐
|
||||
|
||||
# 4. 生成 Release（技能）
|
||||
/generate-release-cc
|
||||
|
||||
# 5. 部署（技能）
|
||||
/deploy-vps-both-cc # 或 akamai-cc / local-cc
|
||||
|
||||
# 6. 采集发布凭据（技能）
|
||||
/capture-release-evidences-cc
|
||||
```
|
||||
|
||||
## 详细清单
|
||||
|
||||
### 发布前
|
||||
|
||||
- [ ] 目标版本的所有 PR 已合并到 `release/vX.Y.0`
|
||||
- [ ] 该版本的所有 Linear/issue 事项已关闭或推迟到下一里程碑
|
||||
- [ ] `release/vX.Y.0` 分支 CI 状态为绿色
|
||||
- [ ] 代码中无 `TODO(release)` 标记：`grep -r "TODO(release)" src/ open-sse/`
|
||||
- [ ] Docker 基础镜像已更新到最新（当前为 `node:24.15.0-trixie-slim`）
|
||||
|
||||
### 版本与变更日志
|
||||
|
||||
- [ ] 运行 `/version-bump-cc <patch|minor|major>`（Claude Code 技能）
|
||||
- 更新 `package.json`、`electron/package.json`
|
||||
- 根据上次 tag 以来的 git 提交重新生成 `CHANGELOG.md`
|
||||
- 更新 README.md badges
|
||||
- [ ] 人工审查 CHANGELOG.md 并按需清理提交信息
|
||||
- [ ] 确保 `CHANGELOG.md` 中最新 semver 版本节与 `package.json` 的版本一致
|
||||
- [ ] 将 `## [Unreleased]` 保留为变更日志的第一节，供后续开发使用
|
||||
- [ ] 更新 `docs/openapi.yaml` → `info.version` 必须等于 `package.json` 的版本
|
||||
|
||||
### 代码质量
|
||||
|
||||
- [ ] `npm run lint` — 0 错误（警告为已有问题）
|
||||
- [ ] `npm run typecheck:core` — 通过
|
||||
- [ ] `npm run typecheck:noimplicit:core` — 通过（严格模式）
|
||||
- [ ] `npm run check:cycles` — 无循环依赖
|
||||
- [ ] `npm run check:any-budget:t11` — 在预算范围内
|
||||
- [ ] `npm run check:route-validation:t06` — 通过
|
||||
- [ ] `npm run check:node-runtime` — 支持的运行时下限已满足（`>=22.22.2 <23`、`>=24.0.0 <27`，依据 `src/shared/utils/nodeRuntimeSupport.ts` 中的 `SUPPORTED_NODE_RANGE`；与 `package.json` `engines` 对齐）
|
||||
|
||||
### 测试
|
||||
|
||||
- [ ] `npm run test:unit` — 通过
|
||||
- [ ] `npm run test:vitest` — 通过（MCP 服务端、Auto-Combo、缓存）
|
||||
- [ ] `npm run test:coverage` — 门禁 60/60/60/60 达标（语句/行/函数/分支）
|
||||
- [ ] `npm run test:integration` — 通过（若变更涉及数据库 / 处理器）
|
||||
- [ ] `npm run test:combo:matrix` — 通过（Combo 策略矩阵：确定性验证全部 17 种路由策略的选择决策；在修改 Combo 路由、策略解析或容灾逻辑时必须运行）
|
||||
- [ ] `RUN_COMBO_LIVE=1 npm run test:combo:live` — **可选/手动**（带门控的真实上游冒烟测试；从 VPS `root@192.168.0.15` 拉取只读数据库快照；实际调用服务商，消耗积分；不在 CI 中运行；无门控时直接跳过）
|
||||
- [ ] `npm run test:combo:live:vps` — **可选/手动**（Phase-3 VPS 实时冒烟测试：7 个 HTTP 场景通过纯 Node ESM 对线上 `.15` 服务器执行；需要 `ssh root@192.168.0.15`；仅创建/删除 `__live_test__*` Combo；实际调用服务商；不在 CI 中运行）
|
||||
- [ ] `npm run test:e2e` — 通过（UI 变更时）
|
||||
- [ ] `npm run test:protocols:e2e` — 通过（MCP/A2A 变更时）
|
||||
- [ ] `npm run test:ecosystem` — 通过
|
||||
|
||||
### Hooks（Husky 验证）
|
||||
|
||||
Husky hooks 位于 `.husky/` 目录，在 git 操作时自动运行。
|
||||
|
||||
- **pre-commit：** `npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11`
|
||||
- **pre-push：** 快速确定性门禁 — `npm run check:any-budget:t11 && npm run check:tracked-artifacts`（2026-06-13 启用）。有意不包含 `test:unit`（耗时较长；由 CI `test-unit` 任务覆盖）。
|
||||
- 在推送发布分支前手动运行 `npm run test:unit`。
|
||||
|
||||
若 hook 失败：修复根本问题，不要用 `--no-verify` 绕过。
|
||||
|
||||
### 约定式提交
|
||||
|
||||
所有发布相关提交必须遵循 `type(scope): subject` 格式。
|
||||
|
||||
**有效 type：** `feat`、`fix`、`refactor`、`docs`、`test`、`chore`、`perf`、`style`、`ci`
|
||||
|
||||
**有效 scope：** `db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`、`cloud-agent`、`guardrails`、`compression`、`auto-combo`、`resilience`、`providers`、`executors`、`translator`、`domain`、`authz`
|
||||
|
||||
破坏性变更：在 scope 后添加 `BREAKING CHANGE:` 脚注或 `!`（如 `feat(api)!: drop /v0`）。
|
||||
|
||||
### 文档
|
||||
|
||||
- [ ] `npm run check:docs-sync` 通过（由 pre-commit 自动运行）
|
||||
- [ ] `npm run check:docs-all` 通过（总检查：docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links）
|
||||
- [ ] `npm run check:env-doc-sync` 退出码 0 — 代码 ↔ `.env.example` ↔ `docs/reference/ENVIRONMENT.md` 环境变量契约完整
|
||||
- [ ] `npm run check:doc-links` 退出码 0 — 重构后无中断的内部 Markdown 引用
|
||||
- [ ] `docs/architecture/ARCHITECTURE.md` 已审查存储/运行时偏差
|
||||
- [ ] `docs/guides/TROUBLESHOOTING.md` 已审查环境变量和运维偏差
|
||||
- [ ] 若 `.env.example` 有变更：`docs/reference/ENVIRONMENT.md` 已更新
|
||||
- [ ] 若新增功能含 UI：`docs/guides/USER_GUIDE.md` 已提及
|
||||
- [ ] 若新增功能含 API：`docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` 已更新
|
||||
- [ ] 若新增功能为模块：已创建专属 `docs/<MODULE>.md`
|
||||
- [ ] 若有破坏性变更：`docs/guides/TROUBLESHOOTING.md` 包含迁移说明
|
||||
|
||||
### i18n
|
||||
|
||||
- [ ] `npm run i18n:check` 退出码 0 — 翻译状态（`.i18n-state.json`）与源文档同步（严格模式下无漂移源文件；warn 级别的建议可接受用于最后一刻的文档完善，但打 tag 前必须为 0）
|
||||
- [ ] `npm run i18n:check-ui-coverage` 退出码 0 — 所有 UI 语言的覆盖率不低于 80%
|
||||
- [ ] `npm run i18n:sync-ui:dry` 报告跨 42 个语言 0 个缺失 key
|
||||
- [ ] 若英文源文档有变更，打 tag 前运行 `npm run i18n:run`（需要 `.env` 中设置 `OMNIROUTE_TRANSLATION_API_KEY`）
|
||||
- [ ] 翻译贡献可推迟到下一版本（若改动较小，在 CHANGELOG 中标注）
|
||||
|
||||
### 数据库迁移
|
||||
|
||||
- [ ] 若 `src/lib/db/migrations/` 有新增文件：
|
||||
- [ ] 每个迁移是幂等的（使用 `CREATE TABLE IF NOT EXISTS` 等）
|
||||
- [ ] 迁移包裹在事务中
|
||||
- [ ] 编号正确（序列中无间隙）
|
||||
- [ ] 全新安装测试：删除 `~/.omniroute/omniroute.db` 并运行 `npm run dev`
|
||||
- [ ] 已有安装测试：备份数据库，运行迁移，验证 Schema
|
||||
- [ ] 若迁移重写数据表，WAL 文件（`-wal`、`-shm`）处理正确
|
||||
|
||||
### 服务商目录（Zod 验证）
|
||||
|
||||
- [ ] `src/shared/constants/providers.ts` 加载时 Zod Schema 有效
|
||||
- [ ] 所有服务商具备必需字段（`id`、`label`、`kind` 等）
|
||||
- [ ] 新增免费服务商已提供 `freeNote`
|
||||
- [ ] OAuth 服务商已在 `src/lib/oauth/constants/oauth.ts` 中注册 `oauthConfig`
|
||||
- [ ] 若新增服务商：`open-sse/executors/` 中有对应的 executor
|
||||
- [ ] 若非 OpenAI 格式：`open-sse/translator/` 中有对应的 translator
|
||||
- [ ] 模型已在 `open-sse/config/providerRegistry.ts` 中注册
|
||||
- [ ] `tests/unit/` 中的单元测试覆盖服务商分类和路由
|
||||
|
||||
### 桌面应用（Electron）
|
||||
|
||||
若 `electron/` 有变更：
|
||||
|
||||
- [ ] `npm run electron:smoke:packaged` 通过
|
||||
- [ ] 至少测试了一种平台的构建（`:win`、`:mac`、`:linux`）
|
||||
- [ ] 代码签名证书未过期（若启用签名）
|
||||
- [ ] `electron/package.json` 版本与根 `package.json` 一致
|
||||
- [ ] 若发布到 `stable`，自动更新通道指针已更新
|
||||
|
||||
### 构建布局
|
||||
|
||||
仓库使用三个不同的输出目录 — 切勿混淆：
|
||||
|
||||
| 目录 | 用途 | 是否追踪？ |
|
||||
| ---------- | -------------------------------------------------------- | --------------- |
|
||||
| `src/` | 应用源码（TypeScript / TSX） | 是 |
|
||||
| `.build/` | 构建中间产物 — `next build` 输出（`distDir`） | 否（gitignored） |
|
||||
| `dist/` | 可分发的 npm 包 — 由 `assembleStandalone` 组装 | 否（gitignored） |
|
||||
|
||||
> **运维说明：** 远程 VPS 镜像目录仍为 `/usr/lib/node_modules/omniroute/app/`。
|
||||
> 仅**仓库内**的构建输出路径有变化（`app/` → `dist/`）。部署技能将 `dist/` 内容
|
||||
> rsync 到远程 `app/` 目录 — 无需更改 VPS 路径。
|
||||
|
||||
**单次构建流程：**
|
||||
|
||||
```
|
||||
npm run build:release
|
||||
└─ rm -rf .build dist （清理）
|
||||
└─ next build → .build/next/ （中间产物）
|
||||
└─ assembleStandalone （拷贝 standalone + static + public + natives → dist/）
|
||||
└─ writes dist/BUILD_SHA （HEAD 哨兵）
|
||||
```
|
||||
|
||||
部署时不要先运行 `npm run build` 再单独运行 `npm run build:cli` — 应使用
|
||||
`npm run build:release`，它会在一条命令中完成清理重建 + 哨兵写入。
|
||||
|
||||
### 产物验证
|
||||
|
||||
- [ ] `npm run build:release` 成功且 `dist/BUILD_SHA` == `git rev-parse --short HEAD`
|
||||
- [ ] `npm run check:pack-artifact` 通过 — 无 `app.__qa_backup`、`scripts/scratch`、`package-lock.json` 等本地残留
|
||||
- [ ] 构建后 `dist/server.js` 存在
|
||||
|
||||
### 打标签与发布
|
||||
|
||||
- [ ] 运行 `/generate-release-cc`（Claude Code 技能）：
|
||||
- 创建 tag `vX.Y.Z`
|
||||
- 推送 tag 和分支
|
||||
- 创建 GitHub Release 并填入变更日志内容
|
||||
- 附加 Electron 安装包（若已构建）
|
||||
- [ ] 或手动操作：
|
||||
```bash
|
||||
git tag -a vX.Y.Z -m "Release vX.Y.Z"
|
||||
git push origin vX.Y.Z
|
||||
gh release create vX.Y.Z --notes-from-tag
|
||||
```
|
||||
|
||||
### 部署
|
||||
|
||||
部署技能使用轻量 rsync 流程 — 无需 `npm pack`、无需 `npm i -g`：
|
||||
|
||||
- [ ] 使用与目标匹配的部署技能：
|
||||
- `/deploy-vps-local-cc` — 本地 VPS（192.168.0.15）
|
||||
- `/deploy-vps-akamai-cc` — Akamai VPS（69.164.221.35）
|
||||
- `/deploy-vps-both-cc` — 两者
|
||||
- [ ] 部署前确认 `dist/BUILD_SHA` == `git rev-parse --short HEAD`
|
||||
- [ ] 构建必须在 `node_modules` 为真实目录的环境中进行（主工作区或 `npm ci` 过的 worktree — 不能是符号链接的 worktree）
|
||||
- [ ] 对已部署实例执行冒烟测试：
|
||||
- 打开 `/dashboard/health` → 检查版本号与 Release 一致
|
||||
- 针对已知服务商运行 `/v1/chat/completions` 请求
|
||||
- 验证 `/api/monitoring/health` 返回 `CLOSED` 状态的熔断器
|
||||
- 确认 MCP 传输层响应正常（`/mcp` HTTP、`/mcp-sse` SSE）
|
||||
|
||||
### 发布后
|
||||
|
||||
- [ ] 运行 `/capture-release-evidences-cc`（Claude Code 技能）
|
||||
- 采集新功能的 WebP 截图/录屏
|
||||
- 附加到 Release 说明 / 博客文章
|
||||
- [ ] 在 GitHub Discussions / Discord 发布版本公告
|
||||
- [ ] 为下一版本开启里程碑
|
||||
- [ ] 若为关键版本：置顶讨论或在 `news.json` 中推送应用内 banner
|
||||
|
||||
## 内嵌服务冒烟测试（v3.8.4+）
|
||||
|
||||
在发布包含内嵌服务变更的任何版本前，验证：
|
||||
|
||||
### 首次数据库启动（捕获迁移冲突 — 自 v3.8.4 hotfix 后新增）
|
||||
|
||||
- [ ] `DATA_DIR=$(mktemp -d) npm start &` — 等待 10 秒启动
|
||||
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` 返回 `"9router"`（不是 404、不是 500）。确认迁移 `071_services.sql` 已应用 + 行已写入。
|
||||
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at"` 返回 3 行。
|
||||
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted"` 返回 2 行（验证 `070_webhooks_kind_metadata.sql` 已应用）。
|
||||
- [ ] `node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts` 通过 — 防止未来冲突。
|
||||
|
||||
### 9Router
|
||||
|
||||
- [ ] `POST /api/services/9router/install` 在 2 分钟内返回 200 及 `installedVersion`
|
||||
- [ ] `POST /api/services/9router/start` 在 30 秒内返回 200 及 `state: "running"`
|
||||
- [ ] `GET /api/services/9router/status` 报告 `health: "healthy"`
|
||||
- [ ] `POST /v1/chat/completions` 使用 `"model": "9router/auto/..."` 返回 200（通过 9Router 端到端路由）
|
||||
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` 在代理内渲染 9Router 原生 UI（非直接 `127.0.0.1:port` iframe）
|
||||
- [ ] `POST /api/services/9router/rotate-key` 返回 `{ keyRotated: true }` 且服务干净重启
|
||||
- [ ] `POST /api/services/9router/stop` 返回 200 及 `state: "stopped"`
|
||||
- [ ] `GET /api/services/9router/logs?tail=50` 返回 SSE 流，`snapshot` 事件包含最近行
|
||||
- [ ] 在无 `npm` 的 PATH 环境中安装时返回 500 及友好的（非堆栈追踪）错误信息
|
||||
|
||||
### CLIProxyAPI
|
||||
|
||||
- [ ] `POST /api/services/cliproxy/install` 在 2 分钟内返回 200
|
||||
- [ ] `POST /api/services/cliproxy/start` 在 30 秒内返回 200 及 `state: "running"`
|
||||
- [ ] `GET /api/services/cliproxy/status` 报告 `health: "healthy"`
|
||||
- [ ] `POST /api/services/cliproxy/stop` 返回 200 及 `state: "stopped"`
|
||||
- [ ] `GET /api/services/cliproxy/logs?tail=50` 返回 SSE 流
|
||||
|
||||
### 安全回归测试
|
||||
|
||||
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start` 返回 `403 LOCAL_ONLY`
|
||||
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start` 返回 `403 LOCAL_ONLY`
|
||||
- [ ] `/api/services/*` 的错误响应不包含 `err.stack` 或绝对文件路径
|
||||
|
||||
## v3.8.0+ 检查项
|
||||
|
||||
发布任何 v3.8.x 版本前，验证以下附加项：
|
||||
|
||||
- [ ] `omniroute --tray` 在 macOS 上启动（systray2 安装到 `~/.omniroute/runtime/`）
|
||||
- [ ] `omniroute --tray` 在 Linux 上启动（需要 DISPLAY；未设置时优雅报错）
|
||||
- [ ] `omniroute --tray` 在 Windows 上启动（PowerShell NotifyIcon，无额外二进制文件）
|
||||
- [ ] `omniroute config tray enable` 创建自启动条目；disable 则移除
|
||||
- [ ] `npm install -g omniroute@<this-version>` 运行 postinstall 无致命退出
|
||||
- [ ] 更新路径保留可选依赖：`omniroute update --apply` 以及自动更新器
|
||||
运行 `npm install -g … --include=optional` 以确保 `optionalDependencies`（better-sqlite3、
|
||||
keytar、tls-client 以及 llmlingua SLM 栈：`@atjsh/llmlingua-2`、
|
||||
`@huggingface/transformers@3.5.2`、`@tensorflow/tfjs`、`js-tiktoken`）在更新后仍然存在。
|
||||
`@huggingface/transformers` 保持为可选依赖，这样其 `onnxruntime-node` CUDA provider postinstall
|
||||
不会在 CUDA 11 主机上中断安装。Ultra 模式的 `modelPath` SLM 层还需要
|
||||
tinybert 模型，首次使用时自动下载到 `${DATA_DIR}/models/llmlingua`。postinstall
|
||||
（`scripts/build/colocateOptionals.mjs`）随后将 SLM 可选依赖闭包共置到
|
||||
`dist/node_modules`，使 Worker 解析单一的 `@huggingface/transformers` 3.5.2
|
||||
可选实例 — standalone trace 仅打包 transformers，不包含动态导入的
|
||||
可选依赖，否则 Worker 会基于根目录的 transformers 加载 llmlingua-2，
|
||||
SLM 层将静默失效。
|
||||
- [ ] `omniroute status` 在无 `.env` 的情况下正常工作（CLI Token 路径，仅 loopback）
|
||||
- [ ] `curl http://localhost:20128/api/shutdown` 返回 401（始终受保护的路由）
|
||||
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` 返回 401（loopback 防护）
|
||||
- [ ] SQLite 运行时首次运行时解析为 `bundled`（内嵌二进制文件对当前平台有效）
|
||||
- [ ] 删除 `node_modules/better-sqlite3` 后 SQLite 运行时回退到 `runtime`
|
||||
- [ ] 智能 MCP 过滤器压缩真实 `playwright-mcp browser_snapshot` 输出（压缩率 ≥50%）
|
||||
- [ ] 全部 10 个 `skills/omniroute*/SKILL.md` 文件可通过 GitHub raw URL 公开访问
|
||||
- [ ] 全新安装时引导向导显示"How It Works"服务商层级介绍步骤
|
||||
- [ ] 首页仪表盘服务商层级覆盖率组件显示已配置/活跃数量
|
||||
|
||||
---
|
||||
|
||||
Use this checklist before tagging or publishing a new OmniRoute release.
|
||||
## 回滚
|
||||
|
||||
## Version and Changelog
|
||||
若 Release 出现严重问题：
|
||||
|
||||
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:
|
||||
- `## [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.
|
||||
1. `gh release edit vX.Y.Z --prerelease`（标记为非最新版本）
|
||||
2. `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z`（仅限用户尚未采用时）
|
||||
3. 或：在 `release/vX.Y.0` 上做 hotfix → 发布补丁版本 `vX.Y.(Z+1)`
|
||||
4. 立即在 GitHub Discussions 和 Discord 中沟通
|
||||
|
||||
## API Docs
|
||||
## 硬性规则
|
||||
|
||||
1. Update `docs/reference/openapi.yaml`:
|
||||
- `info.version` must equal `package.json` version.
|
||||
2. Validate endpoint examples if API contracts changed.
|
||||
- 切勿直接提交到 `main`
|
||||
- 切勿对 `main` 或 `release/*` 分支使用 `git push --force`
|
||||
- 切勿跳过 Husky hooks（`--no-verify`）
|
||||
- 切勿提交密钥、凭证或 `.env` 文件
|
||||
- 覆盖率必须保持 ≥60/60/60/60（语句/行/函数/分支）
|
||||
- 修改 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码时，始终包含或更新测试
|
||||
|
||||
## Runtime Docs
|
||||
## 自动同步检查
|
||||
|
||||
1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
|
||||
2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
|
||||
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
|
||||
- `>=20.20.2 <21` or `>=22.22.2 <23`
|
||||
- `npm run check:node-runtime`
|
||||
4. Validate the npm publish artifact after building the standalone package:
|
||||
- `npm run build:cli`
|
||||
- `npm run check:pack-artifact`
|
||||
- confirm no `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, or other local residue
|
||||
5. Update localized docs if source docs changed significantly.
|
||||
|
||||
## 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 任务）中运行此检查。
|
||||
|
||||
@@ -1,130 +1,138 @@
|
||||
# OmniRoute — Deployment Guide on VM with Cloudflare (中文 (简体))
|
||||
---
|
||||
title: "OmniRoute — 在虚拟机上通过 Cloudflare 部署指南"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md)
|
||||
# OmniRoute — 在虚拟机上通过 Cloudflare 部署指南
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](../../es/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](../../fr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](../../it/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](../../ru/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](../../de/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](../../in/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](../../th/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](../../uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](../../ar/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](../../ja/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](../../bg/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](../../da/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](../../fi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](../../he/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](../../hu/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](../../ko/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](../../nl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](../../no/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](../../ro/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](../../pl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](../../sk/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](../../sv/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](../../phi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](../../cs/docs/ops/VM_DEPLOYMENT_GUIDE.md)
|
||||
|
||||
在虚拟机 (VPS) 上安装并配置 OmniRoute 并通过 Cloudflare 管理域名的完整指南。
|
||||
|
||||
---
|
||||
|
||||
Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare.
|
||||
## 前提条件
|
||||
|
||||
| 项目 | 最低配置 | 推荐配置 |
|
||||
| ------------ | ------------------------- | ----------------- |
|
||||
| **CPU** | 1 vCPU | 2 vCPU |
|
||||
| **RAM** | 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<69><6C><EFBFBD>
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
## 1. 配置虚拟机
|
||||
|
||||
| Item | Minimum | Recommended |
|
||||
| ---------- | ------------------------ | ---------------- |
|
||||
| **CPU** | 1 vCPU | 2 vCPU |
|
||||
| **RAM** | 1 GB | 2 GB |
|
||||
| **Disk** | 10 GB SSD | 25 GB SSD |
|
||||
| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
|
||||
| **Domain** | Registered on Cloudflare | — |
|
||||
| **Docker** | Docker Engine 24+ | Docker 27+ |
|
||||
### 1.1 创建实例
|
||||
|
||||
**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
|
||||
在你选择的 VPS 服务商上：
|
||||
|
||||
---
|
||||
- 选择 Ubuntu 24.04 LTS
|
||||
- 选择最低配置方案 (1 vCPU / 1 GB RAM)
|
||||
- 设置强 root 密码或配置 SSH 密钥
|
||||
- 记下 **公网 IP**（例如 `203.0.113.10`）
|
||||
|
||||
## 1. Configure the VM
|
||||
|
||||
### 1.1 Create the instance
|
||||
|
||||
On your preferred VPS provider:
|
||||
|
||||
- Choose Ubuntu 24.04 LTS
|
||||
- Select the minimum plan (1 vCPU / 1 GB RAM)
|
||||
- Set a strong root password or configure SSH key
|
||||
- Note the **public IP** (e.g., `203.0.113.10`)
|
||||
|
||||
### 1.2 Connect via SSH
|
||||
### 1.2 通过 SSH 连接
|
||||
|
||||
```bash
|
||||
ssh root@203.0.113.10
|
||||
```
|
||||
|
||||
### 1.3 Update the system
|
||||
### 1.3 更新系统
|
||||
|
||||
```bash
|
||||
apt update && apt upgrade -y
|
||||
```
|
||||
|
||||
### 1.4 Install Docker
|
||||
### 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
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo “$VERSION_CODENAME”) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
apt update
|
||||
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
```
|
||||
|
||||
### 1.5 Install nginx
|
||||
### 1.5 安装 nginx
|
||||
|
||||
```bash
|
||||
apt install -y nginx
|
||||
```
|
||||
|
||||
### 1.6 Configure Firewall (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
|
||||
```
|
||||
|
||||
> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section.
|
||||
> **提示**：为获得最高安全性，将 80 和 443 端口仅限 Cloudflare IP 访问。参见[高级安全](#6-高级安全)部分。
|
||||
|
||||
---
|
||||
|
||||
## 2. Install OmniRoute
|
||||
## 2. 安装 OmniRoute
|
||||
|
||||
### 2.1 Create configuration directory
|
||||
### 2.1 创建配置目录
|
||||
|
||||
```bash
|
||||
mkdir -p /opt/omniroute
|
||||
```
|
||||
|
||||
### 2.2 Create environment variables file
|
||||
### 2.2 创建环境变量文件
|
||||
|
||||
```bash
|
||||
cat > /opt/omniroute/.env << ‘EOF’
|
||||
# === Security ===
|
||||
cat > /opt/omniroute/.env << 'EOF'
|
||||
# === 安全 ===
|
||||
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
|
||||
INITIAL_PASSWORD=YourSecurePassword123!
|
||||
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
|
||||
STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
|
||||
STORAGE_ENCRYPTION_KEY_VERSION=v1
|
||||
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
|
||||
OMNIROUTE_WS_BRIDGE_SECRET=REPLACE-WITH-WS-BRIDGE-SECRET # 生产环境必需：Codex Responses WS 桥接使用
|
||||
|
||||
# === App ===
|
||||
# === 应用 ===
|
||||
PORT=20128
|
||||
NODE_ENV=production
|
||||
HOSTNAME=0.0.0.0
|
||||
DATA_DIR=/app/data
|
||||
STORAGE_DRIVER=sqlite
|
||||
APP_LOG_TO_FILE=true
|
||||
AUTH_COOKIE_SECURE=false
|
||||
AUTH_COOKIE_SECURE=true
|
||||
REQUIRE_API_KEY=false
|
||||
|
||||
# === Domain (change to your domain) ===
|
||||
BASE_URL=https://llms.seudominio.com
|
||||
# === URL（替换为你的域名）===
|
||||
# 计划任务 / 内部自调用所使用的内部服务端到服务端 URL。
|
||||
BASE_URL=http://127.0.0.1:20128
|
||||
# OAuth 回调、控制台链接及同源校验所面向浏览器的 URL。
|
||||
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
|
||||
# 可选：显式覆盖生成的公开资源 URL。
|
||||
# OMNIROUTE_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
|
||||
```
|
||||
|
||||
> ⚠️ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key.
|
||||
> ⚠️ **重要**：请生成唯一的密钥！对每个密钥使用 `openssl rand -hex 32`。
|
||||
|
||||
### 2.3 Start the container
|
||||
### 2.3 启动容器
|
||||
|
||||
```bash
|
||||
docker pull diegosouzapw/omniroute:latest
|
||||
@@ -138,45 +146,45 @@ docker run -d \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### 2.4 Verify that it is running
|
||||
### 2.4 验证运行状态
|
||||
|
||||
```bash
|
||||
docker ps | grep omniroute
|
||||
docker logs omniroute --tail 20
|
||||
```
|
||||
|
||||
It should display: `[DB] SQLite database ready` and `listening on port 20128`.
|
||||
应显示：`[DB] SQLite database ready` 和 `listening on port 20128`。
|
||||
|
||||
---
|
||||
|
||||
## 3. Configure nginx (Reverse Proxy)
|
||||
## 3. 配置 nginx（反向代理）
|
||||
|
||||
### 3.1 Generate SSL certificate (Cloudflare Origin)
|
||||
### 3.1 生成 SSL 证书（Cloudflare 源服务器）
|
||||
|
||||
In the Cloudflare dashboard:
|
||||
在 Cloudflare 控制台中：
|
||||
|
||||
1. Go to **SSL/TLS → Origin Server**
|
||||
2. Click **Create Certificate**
|
||||
3. Keep the defaults (15 years, \*.yourdomain.com)
|
||||
4. Copy the **Origin Certificate** and the **Private Key**
|
||||
1. 前往 **SSL/TLS → 源服务器**
|
||||
2. 点击 **创建证书**
|
||||
3. 保留默认设置（15 年，\*.yourdomain.com）
|
||||
4. 复制 **源证书** 和 **私钥**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 3.2 Nginx Configuration
|
||||
### 3.2 nginx 配置
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/sites-available/omniroute << ‘NGINX’
|
||||
# Default server — blocks direct access via IP
|
||||
cat > /etc/nginx/sites-available/omniroute << 'NGINX'
|
||||
# 默认 server — 阻止通过 IP 的直接访问
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
@@ -192,7 +200,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;
|
||||
@@ -203,16 +211,17 @@ server {
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:20128;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
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”;
|
||||
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 600s;
|
||||
@@ -220,7 +229,7 @@ server {
|
||||
}
|
||||
}
|
||||
|
||||
# HTTP → HTTPS redirect
|
||||
# HTTP → HTTPS 跳转
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
@@ -230,59 +239,59 @@ server {
|
||||
NGINX
|
||||
```
|
||||
|
||||
Keep reverse-proxy stream timeouts aligned with your OmniRoute timeout env vars. If you raise
|
||||
`FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`, raise `proxy_read_timeout` / `proxy_send_timeout`
|
||||
above the same threshold.
|
||||
请确保反向代理的流超时与 OmniRoute 超时环境变量保持一致。如果提高了 `FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`，则将 `proxy_read_timeout` / `proxy_send_timeout` 同步提高到同一阈值以上。
|
||||
|
||||
### 3.3 Enable and Test
|
||||
OmniRoute 使用 `NEXT_PUBLIC_BASE_URL` 作为 OAuth、公开链接及控制台变更域名校验的正规浏览器来源。上述 `X-Forwarded-*` 标头仍然是有效的路由元数据，但不能替代设置显式公开 URL。仅在 OmniRoute 客户端无法直接访问且你的代理剥离/重建了传入转发标头时，才启用 `OMNIROUTE_TRUST_PROXY`。
|
||||
|
||||
### 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. Configure Cloudflare DNS
|
||||
## 4. 配置 Cloudflare DNS
|
||||
|
||||
### 4.1 Add DNS record
|
||||
### 4.1 添加 DNS 记录
|
||||
|
||||
In the Cloudflare dashboard → DNS:
|
||||
在 Cloudflare 控制台 → DNS：
|
||||
|
||||
| Type | Name | Content | Proxy |
|
||||
| ---- | ------ | ---------------------- | ---------- |
|
||||
| A | `llms` | `203.0.113.10` (VM IP) | ✅ Proxied |
|
||||
| 类型 | 名称 | 内容 | 代理 |
|
||||
| ---- | ------ | ------------------------ | ---------- |
|
||||
| A | `llms` | `203.0.113.10`（虚拟机 IP） | ✅ 已代理 |
|
||||
|
||||
### 4.2 Configure SSL
|
||||
### 4.2 配置 SSL
|
||||
|
||||
Under **SSL/TLS → Overview**:
|
||||
在 **SSL/TLS → 概览** 下：
|
||||
|
||||
- Mode: **Full (Strict)**
|
||||
- 模式：**完全（严格）**
|
||||
|
||||
Under **SSL/TLS → Edge Certificates**:
|
||||
在 **SSL/TLS → 边缘证书** 下：
|
||||
|
||||
- Always Use HTTPS: ✅ On
|
||||
- Minimum TLS Version: TLS 1.2
|
||||
- Automatic HTTPS Rewrites: ✅ On
|
||||
- 始终使用 HTTPS：✅ 开启
|
||||
- 最低 TLS 版本：TLS 1.2
|
||||
- 自动 HTTPS 重写：✅ 开启
|
||||
|
||||
### 4.3 Testing
|
||||
### 4.3 测试
|
||||
|
||||
```bash
|
||||
curl -sI https://llms.seudominio.com/health
|
||||
# Should return HTTP/2 200
|
||||
# 应返回 HTTP/2 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Operations and Maintenance
|
||||
## 5. 运维管理
|
||||
|
||||
### Upgrade to a new version
|
||||
### 升级到新版本
|
||||
|
||||
```bash
|
||||
docker pull diegosouzapw/omniroute:latest
|
||||
@@ -294,42 +303,42 @@ docker run -d --name omniroute --restart unless-stopped \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### View logs
|
||||
### 查看日志
|
||||
|
||||
```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 行
|
||||
```
|
||||
|
||||
### Manual database backup
|
||||
### 手动数据库备份
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Restore from backup
|
||||
### 从备份恢复
|
||||
|
||||
```bash
|
||||
docker stop omniroute
|
||||
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
|
||||
alpine sh -c “rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /”
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
|
||||
docker start omniroute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Advanced Security
|
||||
## 6. 高级安全
|
||||
|
||||
### Restrict nginx to Cloudflare IPs
|
||||
### 限制 nginx 仅允许 Cloudflare IP
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/cloudflare-ips.conf << ‘CF’
|
||||
# Cloudflare IPv4 ranges — update periodically
|
||||
cat > /etc/nginx/cloudflare-ips.conf << 'CF'
|
||||
# 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;
|
||||
@@ -350,58 +359,58 @@ real_ip_header CF-Connecting-IP;
|
||||
CF
|
||||
```
|
||||
|
||||
Add the following to `nginx.conf` inside the `http {}` block:
|
||||
在 `nginx.conf` 的 `http {}` 代码块中加入以下内容：
|
||||
|
||||
```nginx
|
||||
include /etc/nginx/cloudflare-ips.conf;
|
||||
```
|
||||
|
||||
### Install fail2ban
|
||||
### 安装 fail2ban
|
||||
|
||||
```bash
|
||||
apt install -y fail2ban
|
||||
systemctl enable fail2ban
|
||||
systemctl start fail2ban
|
||||
|
||||
# Check status
|
||||
# 检查状态
|
||||
fail2ban-client status sshd
|
||||
```
|
||||
|
||||
### Block direct access to the Docker port
|
||||
### 阻止直接访问 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Deploy to Cloudflare Workers (Optional)
|
||||
## 7. 部署到 Cloudflare Workers（可选）
|
||||
|
||||
For remote access via Cloudflare Workers (without exposing the VM directly):
|
||||
通过 Cloudflare Workers 实现远程访问（无需直接暴露虚拟机）：
|
||||
|
||||
```bash
|
||||
# In the local repository
|
||||
# 在本地仓库中
|
||||
cd omnirouteCloud
|
||||
npm install
|
||||
npx wrangler login
|
||||
npx wrangler deploy
|
||||
```
|
||||
|
||||
See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md).
|
||||
另请参阅 [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md) 了解仓库内的 Cloudflare 隧道操作指南。独立的 `omnirouteCloud/` worker 位于单独的配套仓库中。
|
||||
|
||||
---
|
||||
|
||||
## Port Summary
|
||||
## 端口汇总
|
||||
|
||||
| Port | Service | Access |
|
||||
| ----- | ----------- | -------------------------- |
|
||||
| 22 | SSH | Public (with fail2ban) |
|
||||
| 80 | nginx HTTP | Redirect → HTTPS |
|
||||
| 443 | nginx HTTPS | Via Cloudflare Proxy |
|
||||
| 20128 | OmniRoute | Localhost only (via nginx) |
|
||||
| 端口 | 服务 | 访问方式 |
|
||||
| ------ | ------------- | ---------------------------- |
|
||||
| 22 | SSH | 公开（配合 fail2ban） |
|
||||
| 80 | nginx HTTP | 跳转 → HTTPS |
|
||||
| 443 | nginx HTTPS | 通过 Cloudflare 代理 |
|
||||
| 20128 | OmniRoute | 仅本地（通过 nginx） |
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,86 +1,269 @@
|
||||
# CLI Tools Setup Guide — OmniRoute (中文 (简体))
|
||||
---
|
||||
title: "CLI 工具 — OmniRoute"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇧🇩 [bn](../../bn/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇮🇷 [fa](../../fa/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇮🇳 [gu](../../gu/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇮🇳 [mr](../../mr/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇰🇪 [sw](../../sw/docs/CLI-TOOLS.md) · 🇮🇳 [ta](../../ta/docs/CLI-TOOLS.md) · 🇮🇳 [te](../../te/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇵🇰 [ur](../../ur/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)
|
||||
# CLI 工具 — OmniRoute
|
||||
|
||||
最后更新：2026-06-28
|
||||
|
||||
OmniRoute 与三类 CLI 工具集成，分布在三个专用的 dashboard 页面中：
|
||||
|
||||
| 页面 | 路由 | 概念 | 数量 |
|
||||
| ---------------- | ------------------------ | --------------------------------------------------------------------------- | ------------ |
|
||||
| **CLI Code's** | `/dashboard/cli-code` | 指向 OmniRoute 的编程工具（客户端 → CLI → OmniRoute → 服务商） | 19 |
|
||||
| **CLI Agents** | `/dashboard/cli-agents` | 指向 OmniRoute 的自主代理（相同流程，更广泛的范围） | 6 |
|
||||
| **ACP Agents** | `/dashboard/acp-agents` | OmniRoute 通过 stdio/ACP 作为后端启动的 CLI（反向流程） | 见注册表 |
|
||||
|
||||
旧路由通过 308 重定向：`/dashboard/cli-tools` → `/dashboard/cli-code`，`/dashboard/agents` → `/dashboard/acp-agents`。
|
||||
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
|
||||
CLI Code's / CLI Agents（消费流程）：
|
||||
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
|
||||
│
|
||||
▼ (all point to OmniRoute)
|
||||
▼ （全部指向 OmniRoute）
|
||||
http://YOUR_SERVER:20128/v1
|
||||
│
|
||||
▼ (OmniRoute routes to the right provider)
|
||||
▼ （OmniRoute 路由到合适的服务商）
|
||||
Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
|
||||
|
||||
ACP Agents（反向启动流程）：
|
||||
客户端请求 → OmniRoute → 通过 stdio/ACP 启动 CLI → 响应
|
||||
```
|
||||
|
||||
**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 Key 管理所有工具
|
||||
- 在 dashboard 中追踪所有 CLI 的成本
|
||||
- 无需重新配置每个工具即可切换模型
|
||||
- 在本地和远程服务器（VPS、Docker、Akamai、Cloudflare Tunnel）均可使用
|
||||
|
||||
---
|
||||
|
||||
## Supported Tools (Dashboard Source of Truth)
|
||||
## 使用 `setup-*` 自动配置
|
||||
|
||||
The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.
|
||||
Current list (v3.0.0-rc.16):
|
||||
无需手动编写每个工具的配置。OmniRoute 为每个支持的 CLI 提供对应的 `setup-*` 命令，该命令从运行中的 OmniRoute（本地或远程）读取**实时**模型目录并将工具的配置写入你的机器：
|
||||
|
||||
| Tool | ID | Command | Setup Mode | Install Method |
|
||||
| ------------------ | ------------- | ---------- | ---------- | -------------- |
|
||||
| **Claude Code** | `claude` | `claude` | env | npm |
|
||||
| **OpenAI Codex** | `codex` | `codex` | custom | npm |
|
||||
| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |
|
||||
| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |
|
||||
| **Cursor** | `cursor` | app | guide | desktop app |
|
||||
| **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 | desktop/CLI |
|
||||
| **Qwen Code** | `qwen` | `qwen` | custom | npm |
|
||||
```bash
|
||||
omniroute setup-codex omniroute setup-claude omniroute setup-opencode
|
||||
omniroute setup-cline omniroute setup-kilo omniroute setup-continue
|
||||
omniroute setup-cursor omniroute setup-roo omniroute setup-crush
|
||||
omniroute setup-goose omniroute setup-qwen omniroute setup-aider
|
||||
```
|
||||
|
||||
### CLI fingerprint sync (Agents + Settings)
|
||||
每个命令接受 `--remote <url> --api-key <key>`（针对远程 OmniRoute 配置本地工具）、`--dry-run`（预览不写入）和 `--port`。不支持模型自动发现的工具（Cline、Kilo、Roo、Goose、Qwen、Aider、Gemini）接受 `--model <id>`（以及用于非交互式运行的 `--yes`）。启动器 `omniroute launch`（Claude Code）和 `omniroute launch-codex`（Codex）在注入正确的环境变量后启动 CLI，不写入任何配置。
|
||||
|
||||
`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.
|
||||
This keeps provider IDs aligned with CLI cards and legacy IDs.
|
||||
|
||||
| CLI ID | Fingerprint Provider ID |
|
||||
| ---------------------------------------------------------------------------------------------------- | ----------------------- |
|
||||
| `kilo` | `kilocode` |
|
||||
| `copilot` | `github` |
|
||||
| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |
|
||||
|
||||
Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.
|
||||
> **完整参考：** 主表 — 每个命令写入的内容、所有标志、本地 vs 远程，以及哪些工具需要 `/v1` 后缀 — 在 **[CLI Integrations](../guides/CLI-INTEGRATIONS.md)** 中。
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Get an OmniRoute API Key
|
||||
## 数据源
|
||||
|
||||
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
|
||||
统一目录位于 `src/shared/constants/cliTools.ts`，定义为 `CLI_TOOLS: Record<string, CliCatalogEntry>`。
|
||||
|
||||
> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
|
||||
每个条目包含以下字段（定义在 `src/shared/schemas/cliCatalog.ts`）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------- |
|
||||
| `category` | `"code" \| "agent"` | 工具显示的页面 |
|
||||
| `vendor` | `string` | 工具来源（"Anthropic"、"OSS (P. Gauthier)"） |
|
||||
| `acpSpawnable` | `boolean` | 也可作为 ACP Agent 使用（显示徽章） |
|
||||
| `baseUrlSupport` | `"full" \| "partial" \| "none"` | 自定义端点支持级别。`"none"` = MITM 待办列表 |
|
||||
| `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | 配置机制 |
|
||||
| `id`、`name`、`color`、`description`、`docsUrl` | 标准字段 | 核心显示字段 |
|
||||
|
||||
`baseUrlSupport: "none"` 的条目**不会显示**在 dashboard 页面中 — 它们注册在 MITM 待办列表中，供 plan 11 使用（参见 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`）。
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Install CLI Tools
|
||||
## 1. CLI Code's 目录（19 个工具）
|
||||
|
||||
All npm-based tools require Node.js 18+:
|
||||
支持自定义 base URL 并出现在 `/dashboard/cli-code` 中的工具：
|
||||
|
||||
| id | name | vendor | baseUrlSupport | configType | acpSpawnable |
|
||||
|----|------|--------|---------------|-----------|-------------|
|
||||
| claude | Claude Code | Anthropic | full | env | true |
|
||||
| codex | OpenAI Codex CLI | OpenAI | full | custom | true |
|
||||
| cline | Cline | OSS (ex-Claude Dev) | full | custom | true |
|
||||
| kilo | Kilo Code | Kilo-Org | full | custom | false |
|
||||
| roo | Roo Code | Roo (OSS) | full | guide | false |
|
||||
| continue | Continue | continue.dev | full | guide | false |
|
||||
| qwen | Qwen Code | Alibaba | full | guide | true |
|
||||
| aider | Aider | OSS (P. Gauthier) | full | guide | true |
|
||||
| forge | ForgeCode | Antinomy HQ | full | custom | true |
|
||||
| jcode | jcode | 1jehuang (OSS) | full | custom | false |
|
||||
| deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false |
|
||||
| opencode | OpenCode | Anomaly (ex-SST) | full | guide | true |
|
||||
| droid | Factory Droid | Factory AI | partial | guide | false |
|
||||
| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false |
|
||||
| cursor-cli | Cursor CLI | Anysphere | partial | guide | true |
|
||||
| smelt | Smelt | leonardcser (OSS) | full | custom | false |
|
||||
| pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false |
|
||||
| custom | Custom CLI | — | full | custom-builder | false |
|
||||
|
||||
`baseUrlSupport: "partial"` 的工具在 dashboard 卡片中显示徽章 "⚠ Base URL parcial"。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI Agents 目录（6 个工具）
|
||||
|
||||
出现在 `/dashboard/cli-agents` 中的自主代理：
|
||||
|
||||
| id | name | vendor | baseUrlSupport | acpSpawnable |
|
||||
| ------------ | ---------------- | ------------------------ | -------------- | ------------ |
|
||||
| hermes-agent | Hermes Agent | Nous Research | full | false |
|
||||
| openclaw | OpenClaw | OSS (P. Steinberger) | full | true |
|
||||
| goose | Goose | Block / Linux Foundation | full | true |
|
||||
| interpreter | Open Interpreter | OSS | full | true |
|
||||
| warp | Warp AI | Warp Inc. | partial | true |
|
||||
| agent-deck | Agent Deck | asheshgoplani (OSS) | full | false |
|
||||
|
||||
---
|
||||
|
||||
## 3. ACP Agents（/dashboard/acp-agents）
|
||||
|
||||
此页面（从 `/dashboard/agents` 重命名而来）显示 OmniRoute 可以通过 stdio/ACP 协议**启动**为后端执行引擎的 CLI。目录在 `src/lib/acp/registry.ts` 中单独维护，**不同于** `CLI_TOOLS`。
|
||||
|
||||
---
|
||||
|
||||
## 4. MITM 待办列表（不在 dashboard 中显示）
|
||||
|
||||
以下 CLI 原生不支持自定义 base URL，因此**不会**在 CLI Code's 或 CLI Agents 页面中列出。它们是 plan 11 中 MITM 拦截的候选项：
|
||||
|
||||
| CLI | 原因 |
|
||||
| ------------------- | ------------------------------------------------------------- |
|
||||
| windsurf | BYOK 限于部分 Claude 模型 + 企业 URL/Token |
|
||||
| amp | 封闭生态系统（Sourcegraph） |
|
||||
| amazon-q / kiro-cli | AWS SSO 认证，无自定义 URL |
|
||||
| cowork | Anthropic Desktop，无可配置端点 |
|
||||
|
||||
完整对照参见 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 批量检测 API
|
||||
|
||||
所有工具检测通过单个端点聚合：
|
||||
|
||||
**`GET /api/cli-tools/all-statuses`**
|
||||
|
||||
- 认证：`requireCliToolsAuth(request)`（与其他 `/api/cli-tools/` 路由相同）
|
||||
- 返回：`Record<toolId, ToolBatchStatus>`（类型：`src/shared/types/cliBatchStatus.ts`）
|
||||
- 策略：对全部工具执行 `Promise.all`，每个工具 5 秒超时
|
||||
- 缓存：以配置文件 `mtime` 为索引的内存 LRU 缓存。当 mtime 变化时缓存失效。服务器重启时重置。
|
||||
|
||||
每个工具的响应结构：
|
||||
|
||||
```ts
|
||||
interface ToolBatchStatus {
|
||||
detection: {
|
||||
installed: boolean;
|
||||
runnable: boolean;
|
||||
version?: string;
|
||||
command?: string;
|
||||
commandPath?: string;
|
||||
reason?: string;
|
||||
};
|
||||
config: {
|
||||
status: "configured" | "not_configured" | "not_installed" | "unknown" | "other";
|
||||
endpoint?: string | null;
|
||||
lastConfiguredAt?: string | null;
|
||||
};
|
||||
error?: string; // 已脱敏，无堆栈跟踪
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 新工具的 Settings 处理器
|
||||
|
||||
`configType: "custom"` 的新工具具有专用的 settings API 路由：
|
||||
|
||||
| 路由 | 工具 |
|
||||
| -------------------------------------------- | -------------------------------- |
|
||||
| `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) |
|
||||
| `POST /api/cli-tools/jcode-settings` | jcode (--base-url 标志) |
|
||||
| `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL) |
|
||||
| `POST /api/cli-tools/smelt-settings` | Smelt |
|
||||
| `POST /api/cli-tools/pi-settings` | Pi coding agent |
|
||||
|
||||
所有路由均使用 `sanitizeErrorMessage()` 处理错误响应（Hard Rule #12）。
|
||||
|
||||
---
|
||||
|
||||
## 7. Dashboard 页面架构
|
||||
|
||||
### CLI Code's（`/dashboard/cli-code`）
|
||||
|
||||
- `src/app/(dashboard)/dashboard/cli-code/page.tsx` — 服务端组件
|
||||
- `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — 客户端网格
|
||||
- `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — 工具详情页
|
||||
- `src/app/(dashboard)/dashboard/cli-code/components/` — 12 个专用工具卡片 + `ToolDetailClient.tsx`
|
||||
|
||||
### CLI Agents（`/dashboard/cli-agents`）
|
||||
|
||||
- `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — 服务端组件
|
||||
- `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — 客户端网格
|
||||
- `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — 复用 `ToolDetailClient`
|
||||
|
||||
### ACP Agents（`/dashboard/acp-agents`）
|
||||
|
||||
- `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — 服务端组件（从 `agents/` 迁移而来）
|
||||
|
||||
### 共享 UI 组件（`src/shared/components/cli/`）
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ------------------------- | --------------------------------------------------- |
|
||||
| `CliToolCard.tsx` | 智能状态卡片（检测 + 配置 + 端点） |
|
||||
| `CliConceptCard.tsx` | 每页概念说明卡片 |
|
||||
| `CliComparisonCard.tsx` | 三类 CLI 对比卡 |
|
||||
| `BaseUrlSelect.tsx` | 端点下拉选择（本地/云端/自定义） |
|
||||
| `ApiKeySelect.tsx` | API Key 选择器 |
|
||||
| `ManualConfigModal.tsx` | 可复制的配置片段弹窗 |
|
||||
|
||||
### 共享 Hook（`src/shared/hooks/cli/`）
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --------------------------- | --------------------------------------------------------------------- |
|
||||
| `useToolBatchStatuses.ts` | 获取 `/api/cli-tools/all-statuses`，管理 loading/refresh 状态 |
|
||||
|
||||
---
|
||||
|
||||
## 8. i18n
|
||||
|
||||
在 plan 14 F9 中添加的新命名空间：
|
||||
|
||||
| 命名空间 | 用途 |
|
||||
| ----------- | ---------------------------------------------------------------------------- |
|
||||
| `cliCommon` | 共享字符串（卡片标签、概念/对比文本、详情页标签） |
|
||||
| `cliCode` | CLI Code's 页面字符串 |
|
||||
| `cliAgents` | CLI Agents 页面字符串 |
|
||||
| `acpAgents` | ACP Agents 页面字符串 |
|
||||
|
||||
提供完整的 PT-BR 和 EN 翻译。其余 39 个语言环境通过 `src/i18n/request.ts` 中的命名空间级合并自动回退到 EN。
|
||||
|
||||
---
|
||||
|
||||
## 9. 快速开始
|
||||
|
||||
### 步骤 1 — 获取 OmniRoute API Key
|
||||
|
||||
1. 打开 `/dashboard/api-manager` → **创建 API Key**
|
||||
2. 为其命名（例如 `cli-tools`）并选择所有权限
|
||||
3. 复制 Key — 以下所有 CLI 都会用到
|
||||
|
||||
> 你的 Key 格式为：`sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
|
||||
|
||||
---
|
||||
|
||||
### 步骤 2 — 安装 CLI 工具
|
||||
|
||||
所有基于 npm 的工具需要 Node.js 22.22.2+ 或 24.x：
|
||||
|
||||
```bash
|
||||
# Claude Code (Anthropic)
|
||||
@@ -98,66 +281,74 @@ npm install -g cline
|
||||
# KiloCode
|
||||
npm install -g kilocode
|
||||
|
||||
# Kiro CLI (Amazon — requires curl + unzip)
|
||||
apt-get install -y unzip # on Debian/Ubuntu
|
||||
curl -fsSL https://cli.kiro.dev/install | bash
|
||||
export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc
|
||||
```
|
||||
# Qwen Code (Alibaba)
|
||||
npm install -g @qwen-code/qwen-code
|
||||
|
||||
**Verify:**
|
||||
# Aider
|
||||
pip install aider-chat
|
||||
|
||||
```bash
|
||||
claude --version # 2.x.x
|
||||
codex --version # 0.x.x
|
||||
opencode --version # x.x.x
|
||||
cline --version # 2.x.x
|
||||
kilocode --version # x.x.x (or: kilo --version)
|
||||
kiro-cli --version # 1.x.x
|
||||
# Smelt
|
||||
cargo install smelt # Rust 编写
|
||||
|
||||
# Pi coding agent
|
||||
# 安装参见 https://github.com/zechnerj/pi-coding-agent
|
||||
|
||||
# jcode
|
||||
# 安装参见 https://github.com/1jehuang/jcode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Set Global Environment Variables
|
||||
### 步骤 3 — 通过 Dashboard 配置
|
||||
|
||||
Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:
|
||||
1. 访问 `http://localhost:20128/dashboard/cli-code`
|
||||
2. 在网格中找到你的工具
|
||||
3. 点击卡片进入工具详情页
|
||||
4. 选择你的 API Key 和 base URL
|
||||
5. 点击**应用配置**或复制手动配置片段
|
||||
|
||||
---
|
||||
|
||||
### 步骤 4 — 设置全局环境变量
|
||||
|
||||
```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"
|
||||
export ANTHROPIC_API_KEY="sk-your-omniroute-key"
|
||||
export ANTHROPIC_BASE_URL="http://localhost:20128"
|
||||
export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key"
|
||||
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://<your-server-ip>:20128`。
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Configure Each Tool
|
||||
### 步骤 4 — 配置每个工具
|
||||
|
||||
### Claude Code
|
||||
#### Claude Code
|
||||
|
||||
```bash
|
||||
# Via 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",
|
||||
"apiKey": "sk-your-omniroute-key"
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://localhost:20128",
|
||||
"ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `claude "say hello"`
|
||||
Claude Code 使用统一的 Anthropic 网关根路径。不要在这里添加 `/v1`。
|
||||
|
||||
**测试：** `claude "say hello"`
|
||||
|
||||
---
|
||||
|
||||
### OpenAI Codex
|
||||
#### OpenAI Codex
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF
|
||||
@@ -167,27 +358,45 @@ apiBaseUrl: http://localhost:20128/v1
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `codex "what is 2+2?"`
|
||||
**测试：** `codex "what is 2+2?"`
|
||||
|
||||
---
|
||||
|
||||
### OpenCode
|
||||
#### OpenCode
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF
|
||||
[provider.openai]
|
||||
base_url = "http://localhost:20128/v1"
|
||||
api_key = "sk-your-omniroute-key"
|
||||
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF
|
||||
{
|
||||
"\$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"omniroute": {
|
||||
"npm": "@ai-sdk/openai-compatible",
|
||||
"name": "OmniRoute",
|
||||
"options": {
|
||||
"baseURL": "http://localhost:20128/v1",
|
||||
"apiKey": "sk-your-omniroute-key"
|
||||
},
|
||||
"models": {
|
||||
"claude-sonnet-4-5": { "name": "claude-sonnet-4-5" },
|
||||
"claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
|
||||
"gemini-3-flash": { "name": "gemini-3-flash" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**Test:** `opencode`
|
||||
**测试：** `opencode`
|
||||
|
||||
> 使用 `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`
|
||||
> 发送 thinking 变体。
|
||||
|
||||
---
|
||||
|
||||
### Cline (CLI or VS Code)
|
||||
#### Cline（CLI 或 VS Code）
|
||||
|
||||
**CLI mode:**
|
||||
**CLI 模式：**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
|
||||
@@ -199,22 +408,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 dashboard → **CLI Tools → Cline → 应用配置**。
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
{
|
||||
@@ -223,13 +432,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 dashboard → **CLI Tools → KiloCode → 应用配置**。
|
||||
|
||||
---
|
||||
|
||||
### Continue (VS Code Extension)
|
||||
#### Continue（VS Code 扩展）
|
||||
|
||||
Edit `~/.continue/config.yaml`:
|
||||
编辑 `~/.continue/config.yaml`：
|
||||
|
||||
```yaml
|
||||
models:
|
||||
@@ -241,28 +450,75 @@ models:
|
||||
default: true
|
||||
```
|
||||
|
||||
Restart VS Code after editing.
|
||||
编辑后重启 VS Code。
|
||||
|
||||
---
|
||||
|
||||
### Kiro CLI (Amazon)
|
||||
#### VS Code Insiders（`chatLanguageModels.json`）
|
||||
|
||||
当 VS Code Insiders 配置了自定义端点模型，且你希望 OmniRoute 在不使用自定义请求头字段的情况下工作时使用。
|
||||
|
||||
**推荐位置：**
|
||||
|
||||
- Linux：`~/.config/Code - Insiders/User/chatLanguageModels.json`
|
||||
- Windows：`%APPDATA%/Code - Insiders/User/chatLanguageModels.json`
|
||||
|
||||
**使用 Token 化 OmniRoute 别名的示例：**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"vendor": "customendpoint",
|
||||
"id": "auto",
|
||||
"name": "OmniRoute Auto",
|
||||
"family": "gpt-4",
|
||||
"version": "1.0.0",
|
||||
"url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions",
|
||||
"modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models",
|
||||
"requestFormat": "openai-chat-completions",
|
||||
"contextWindow": 256000,
|
||||
"maxOutputTokens": 32768,
|
||||
"auth": {
|
||||
"type": "none"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**说明：**
|
||||
|
||||
- 将 `sk-your-omniroute-key` 替换为在 OmniRoute 中创建的 API Key。
|
||||
- `url` 字段应指向 `/api/v1/vscode/{token}/chat/completions`。
|
||||
- `modelsUrl` 字段应指向 `/api/v1/vscode/{token}/models`。
|
||||
- 只要客户端支持自定义请求头，应优先使用正常的 `/v1` + Bearer 请求头流程。
|
||||
- URL 嵌入的 Token 是兼容性回退方案，可能出现在编辑器日志或代理历史中。
|
||||
|
||||
---
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
对于 **Kiro IDE** 桌面应用，使用 OmniRoute 通过 `/dashboard/cli-tools → Kiro` 暴露的 MITM 端点。
|
||||
|
||||
---
|
||||
|
||||
### Qwen Code (Alibaba)
|
||||
#### Qwen Code（Alibaba）
|
||||
|
||||
Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.
|
||||
Qwen Code 通过环境变量或 `settings.json` 支持 OpenAI 兼容的 API 端点。
|
||||
|
||||
**Option 1: Environment variables (`~/.qwen/.env`)**
|
||||
> Qwen OAuth 免费层已于 2026-04-15 停用。改为使用 OmniRoute 搭配
|
||||
> `bailian-coding-plan` / `alibaba` / `alibaba-cn` / `openrouter` / `anthropic` /
|
||||
> `gemini` 服务商。
|
||||
|
||||
**选项 1：环境变量（`~/.qwen/.env`）**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF
|
||||
@@ -272,29 +528,25 @@ OPENAI_MODEL="auto"
|
||||
EOF
|
||||
```
|
||||
|
||||
**Option 2: `settings.json` with model providers**
|
||||
**选项 2：`settings.json` 配合 `security.auth`**
|
||||
|
||||
```json
|
||||
// ~/.qwen/settings.json
|
||||
{
|
||||
"env": {
|
||||
"OPENAI_API_KEY": "sk-your-omniroute-key",
|
||||
"OPENAI_BASE_URL": "http://localhost:20128/v1"
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "openai",
|
||||
"apiKey": "sk-your-omniroute-key",
|
||||
"baseUrl": "http://localhost:20128/v1"
|
||||
}
|
||||
},
|
||||
"modelProviders": {
|
||||
"openai": [
|
||||
{
|
||||
"id": "omniroute-default",
|
||||
"name": "OmniRoute (Auto)",
|
||||
"envKey": "OPENAI_API_KEY",
|
||||
"baseUrl": "http://localhost:20128/v1"
|
||||
}
|
||||
]
|
||||
"model": {
|
||||
"name": "claude-sonnet-4-6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option 3: Inline CLI flags**
|
||||
**选项 3：内联 CLI 标志**
|
||||
|
||||
```bash
|
||||
OPENAI_BASE_URL="http://localhost:20128/v1" \
|
||||
@@ -303,96 +555,172 @@ OPENAI_MODEL="auto" \
|
||||
qwen
|
||||
```
|
||||
|
||||
> For a **remote server** replace `localhost:20128` with the server IP or domain.
|
||||
|
||||
**Test:** `qwen "say hello"`
|
||||
|
||||
### Cursor (Desktop App)
|
||||
|
||||
> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
|
||||
> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.
|
||||
|
||||
Via GUI: **Settings → Models → OpenAI API Key**
|
||||
|
||||
- Base URL: `https://your-domain.com/v1`
|
||||
- API Key: your OmniRoute key
|
||||
> 对于**远程服务器**，将 `localhost:20128` 替换为服务器的 IP 或域名。
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Auto-Configuration
|
||||
## 10. OmniRoute 内置 CLI
|
||||
|
||||
The OmniRoute dashboard automates configuration for most tools:
|
||||
`omniroute` 二进制文件提供服务端生命周期、设置、诊断和服务商管理的命令。入口点：`bin/omniroute.mjs`。
|
||||
|
||||
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
|
||||
```bash
|
||||
omniroute # 启动服务器（默认端口 20128）
|
||||
omniroute setup # 交互式设置向导
|
||||
omniroute doctor # 检查配置、数据库、端口、运行时
|
||||
omniroute providers list # 已配置的服务商连接
|
||||
omniroute providers test-all # 测试所有活跃连接
|
||||
omniroute reset-password # 重置管理员密码
|
||||
omniroute logs # 流式输出请求日志
|
||||
omniroute health # 详细健康状态（熔断器、缓存、内存）
|
||||
omniroute --version # 输出版本号
|
||||
omniroute --help # 显示所有命令
|
||||
```
|
||||
|
||||
### 设置与初始化
|
||||
|
||||
```bash
|
||||
omniroute setup # 交互式设置向导
|
||||
omniroute setup --non-interactive # CI/自动化模式（读取环境变量 + 标志）
|
||||
omniroute setup --password '<value>' # 直接设置管理员密码
|
||||
omniroute setup --add-provider \
|
||||
--provider openai \
|
||||
--api-key '<value>' \
|
||||
--test-provider # 一步添加并测试服务商
|
||||
```
|
||||
|
||||
非交互式设置识别的环境变量：
|
||||
|
||||
| 变量 | 用途 |
|
||||
| ------------------- | ----------------------------------------------------------- |
|
||||
| `OMNIROUTE_API_KEY` | 服务商 API Key（通过 Commander `.env()` 绑定到 `--api-key`） |
|
||||
| `DATA_DIR` | 覆盖 OmniRoute 数据目录 |
|
||||
|
||||
其他所有非交互式输入通过标志传入，而非环境变量：
|
||||
`--password`、`--provider`、`--provider-name`、`--provider-base-url`、`--default-model`
|
||||
（参见上述 `omniroute setup` 选项）。
|
||||
|
||||
### 诊断
|
||||
|
||||
```bash
|
||||
omniroute doctor # 检查配置、数据库、端口、运行时、内存、存活状态
|
||||
omniroute doctor --json # 机器可读的 JSON
|
||||
omniroute doctor --no-liveness # 跳过 HTTP 健康探测
|
||||
omniroute doctor --host 0.0.0.0 # 覆盖存活探测的主机
|
||||
omniroute doctor --liveness-url <url> # 完全覆盖健康端点 URL
|
||||
```
|
||||
|
||||
doctor 运行以下检查：`Config`、`Database`、`Storage/encryption`、`Port availability`、`Node runtime`、`Native binary`（better-sqlite3）、`Memory` 和 `Server liveness`。任何检查为 `fail` 时以非零退出码退出。
|
||||
|
||||
### 服务商管理
|
||||
|
||||
```bash
|
||||
omniroute providers available # OmniRoute 服务商目录
|
||||
omniroute providers available --search openai # 按 id/name/alias/category 过滤目录
|
||||
omniroute providers available --category api-key # 按分类过滤（api-key、oauth、free 等）
|
||||
omniroute providers available --json # 机器可读的 JSON
|
||||
|
||||
omniroute providers list # 已配置的服务商连接
|
||||
omniroute providers list --json
|
||||
|
||||
omniroute providers test <id|name> # 测试一个已配置的连接
|
||||
omniroute providers test-all # 测试所有活跃连接
|
||||
omniroute providers validate # 仅本地结构校验
|
||||
```
|
||||
|
||||
> `providers available` 读取 OmniRoute 目录；`providers list/test/test-all/validate`
|
||||
> 直接读取本地 SQLite 数据库，不需要服务器运行。
|
||||
|
||||
### 恢复与重置
|
||||
|
||||
```bash
|
||||
omniroute reset-password # 重置管理员密码（旧别名仍然可用）
|
||||
omniroute reset-encrypted-columns # 显示加密凭证重置的警告 + 干运行
|
||||
omniroute reset-encrypted-columns --force # 实际在 SQLite 中将加密凭证设为 null
|
||||
```
|
||||
|
||||
### 其他子命令
|
||||
|
||||
以下命令假定 OmniRoute 服务器正在运行（另有说明除外）：
|
||||
|
||||
```bash
|
||||
omniroute status # 全面的运行时状态
|
||||
omniroute logs # 流式输出请求日志（--json、--search、--follow）
|
||||
omniroute config show # 显示当前配置
|
||||
|
||||
omniroute provider list # 列出可用服务商（providers list 的别名）
|
||||
omniroute provider add # 将 OmniRoute 注册为某个工具的服务商
|
||||
omniroute keys add | list | remove # 管理 API Key
|
||||
omniroute models [provider] # 列出模型（--json、--search）
|
||||
omniroute combo list | switch | create | delete
|
||||
|
||||
omniroute backup # 快照配置 + 数据库
|
||||
omniroute restore # 从之前的快照恢复
|
||||
|
||||
omniroute health # 详细健康状态（熔断器、缓存、内存）
|
||||
omniroute quota # 服务商配额用量
|
||||
omniroute cache # 缓存状态
|
||||
omniroute cache clear # 清除语义 + 签名缓存
|
||||
|
||||
omniroute mcp status | restart # MCP 服务器状态 / 重启
|
||||
omniroute a2a status | card # A2A 服务器状态 / agent card
|
||||
|
||||
omniroute tunnel list | create | stop # 管理隧道（cloudflare/tailscale/ngrok）
|
||||
omniroute env show | get <k> | set <k> <v> # 检查 / 设置环境变量（临时）
|
||||
|
||||
omniroute test # 服务商连通性冒烟测试
|
||||
omniroute update # 检查更新
|
||||
omniroute completion # 生成 shell 补全
|
||||
```
|
||||
|
||||
### 通用标志
|
||||
|
||||
| 标志 | 说明 |
|
||||
| ------------------- | ------------------------------------------------------ |
|
||||
| `--no-open` | 启动时不自动打开浏览器 |
|
||||
| `--port <n>` | 覆盖 API 端口（默认 20128） |
|
||||
| `--mcp` | 以 MCP 服务器通过 stdio 运行（供 IDE 使用） |
|
||||
| `--non-interactive` | CI 模式（无交互提示；从 env/flags 读取） |
|
||||
| `--json` | 机器可读的 JSON 输出（doctor、providers 等） |
|
||||
| `--help`、`-h` | 显示命令特定的帮助 |
|
||||
| `--version`、`-v` | 输出版本号 |
|
||||
|
||||
---
|
||||
|
||||
## Built-in Agents: Droid & OpenClaw
|
||||
## 可用 API 端点
|
||||
|
||||
**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.
|
||||
| 端点 | 说明 | 用途 |
|
||||
| ---------------------------- | ------------------------------ | -------------------------- |
|
||||
| `/v1/chat/completions` | 标准聊天（所有服务商） | 所有现代工具 |
|
||||
| `/v1/responses` | Responses API（OpenAI 格式） | Codex、代理工作流 |
|
||||
| `/v1/completions` | 旧版文本补全 | 使用 `prompt:` 的旧工具 |
|
||||
| `/v1/embeddings` | 文本嵌入 | RAG、搜索 |
|
||||
| `/v1/images/generations` | 图像生成 | GPT-Image、Flux 等 |
|
||||
| `/v1/audio/speech` | 文本转语音 | ElevenLabs、OpenAI TTS |
|
||||
| `/v1/audio/transcriptions` | 语音转文本 | Deepgram、AssemblyAI |
|
||||
|
||||
- Access: `http://localhost:20128/dashboard/agents`
|
||||
- Configure: same combos and providers as all other tools
|
||||
- No API key or CLI install required
|
||||
可直接粘贴的示例（使用 Token 化 OmniRoute URL）：
|
||||
|
||||
---
|
||||
```txt
|
||||
Token 示例：sk-a3ab3c080beaee3a-69f4a4-070d71af
|
||||
|
||||
## Available API Endpoints
|
||||
|
||||
| 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 | GPT-Image, Flux, etc. |
|
||||
| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |
|
||||
| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |
|
||||
标准 OpenAI base：http://localhost:20128/v1
|
||||
VS Code 模型：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models
|
||||
VS Code 聊天：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions
|
||||
VS Code Responses：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses
|
||||
Ollama 标签：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags
|
||||
Ollama 聊天：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
| 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"` |
|
||||
|
||||
---
|
||||
|
||||
## Quick Setup Script (One Command)
|
||||
|
||||
```bash
|
||||
# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
|
||||
OMNIROUTE_URL="http://localhost:20128/v1"
|
||||
OMNIROUTE_KEY="sk-your-omniroute-key"
|
||||
|
||||
npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code
|
||||
|
||||
# Kiro CLI
|
||||
apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
|
||||
|
||||
# Write configs
|
||||
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 >> ~/.bashrc << EOF
|
||||
export OPENAI_BASE_URL="$OMNIROUTE_URL"
|
||||
export OPENAI_API_KEY="$OMNIROUTE_KEY"
|
||||
export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
|
||||
export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
|
||||
EOF
|
||||
|
||||
source ~/.bashrc
|
||||
echo "✅ All CLIs installed and configured for OmniRoute"
|
||||
```
|
||||
| 错误 | 原因 | 修复方法 |
|
||||
| --------------------------------------------- | ------------------------ | ------------------------------------------------- |
|
||||
| `Connection refused` | OmniRoute 未运行 | `omniroute serve` |
|
||||
| `401 Unauthorized` | API Key 错误 | 在 `/dashboard/api-manager` 中检查 |
|
||||
| `No combo configured` | 无活跃的路由 Combo | 在 `/dashboard/combos` 中设置 |
|
||||
| CLI 显示 "not installed" | 二进制文件不在 PATH 中 | 检查 `which <command>` |
|
||||
| Dashboard 安装后显示 "not detected" | 缓存过期 | 点击 dashboard 中的 "⟳ 刷新检测" |
|
||||
| 旧链接 `/dashboard/cli-tools` | v3.8.6 之前的书签 | 自动重定向到 `/dashboard/cli-code`（308） |
|
||||
| 旧链接 `/dashboard/agents` | v3.8.6 之前的书签 | 自动重定向到 `/dashboard/acp-agents`（308） |
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,67 +1,579 @@
|
||||
# OmniRoute Auto-Combo Engine (中文 (简体))
|
||||
|
||||
🌐 **Languages:** 🇺🇸 [English](../../../../docs/AUTO-COMBO.md) · 🇸🇦 [ar](../../ar/docs/AUTO-COMBO.md) · 🇧🇬 [bg](../../bg/docs/AUTO-COMBO.md) · 🇧🇩 [bn](../../bn/docs/AUTO-COMBO.md) · 🇨🇿 [cs](../../cs/docs/AUTO-COMBO.md) · 🇩🇰 [da](../../da/docs/AUTO-COMBO.md) · 🇩🇪 [de](../../de/docs/AUTO-COMBO.md) · 🇪🇸 [es](../../es/docs/AUTO-COMBO.md) · 🇮🇷 [fa](../../fa/docs/AUTO-COMBO.md) · 🇫🇮 [fi](../../fi/docs/AUTO-COMBO.md) · 🇫🇷 [fr](../../fr/docs/AUTO-COMBO.md) · 🇮🇳 [gu](../../gu/docs/AUTO-COMBO.md) · 🇮🇱 [he](../../he/docs/AUTO-COMBO.md) · 🇮🇳 [hi](../../hi/docs/AUTO-COMBO.md) · 🇭🇺 [hu](../../hu/docs/AUTO-COMBO.md) · 🇮🇩 [id](../../id/docs/AUTO-COMBO.md) · 🇮🇹 [it](../../it/docs/AUTO-COMBO.md) · 🇯🇵 [ja](../../ja/docs/AUTO-COMBO.md) · 🇰🇷 [ko](../../ko/docs/AUTO-COMBO.md) · 🇮🇳 [mr](../../mr/docs/AUTO-COMBO.md) · 🇲🇾 [ms](../../ms/docs/AUTO-COMBO.md) · 🇳🇱 [nl](../../nl/docs/AUTO-COMBO.md) · 🇳🇴 [no](../../no/docs/AUTO-COMBO.md) · 🇵🇭 [phi](../../phi/docs/AUTO-COMBO.md) · 🇵🇱 [pl](../../pl/docs/AUTO-COMBO.md) · 🇵🇹 [pt](../../pt/docs/AUTO-COMBO.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) · 🇷🇴 [ro](../../ro/docs/AUTO-COMBO.md) · 🇷🇺 [ru](../../ru/docs/AUTO-COMBO.md) · 🇸🇰 [sk](../../sk/docs/AUTO-COMBO.md) · 🇸🇪 [sv](../../sv/docs/AUTO-COMBO.md) · 🇰🇪 [sw](../../sw/docs/AUTO-COMBO.md) · 🇮🇳 [ta](../../ta/docs/AUTO-COMBO.md) · 🇮🇳 [te](../../te/docs/AUTO-COMBO.md) · 🇹🇭 [th](../../th/docs/AUTO-COMBO.md) · 🇹🇷 [tr](../../tr/docs/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) · 🇵🇰 [ur](../../ur/docs/AUTO-COMBO.md) · 🇻🇳 [vi](../../vi/docs/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/AUTO-COMBO.md)
|
||||
|
||||
---
|
||||
title: "OmniRoute Auto-Combo Engine"
|
||||
version: 3.8.40
|
||||
lastUpdated: 2026-06-28
|
||||
---
|
||||
|
||||
> Self-managing model chains with adaptive scoring
|
||||
# OmniRoute Auto-Combo 引擎
|
||||
|
||||
## How It Works
|
||||
> **面向用户**：想要快速上手？参见 [Auto-Combo 用户指南](../getting-started/AUTO-COMBO-GUIDE.md)，其中有简明的说明和示例。
|
||||
|
||||
The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**:
|
||||
> 自适应评分的自管理模型链路 + 零配置自动路由
|
||||
|
||||
| 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 |
|
||||
## 零配置自动路由（`auto/` 前缀）
|
||||
|
||||
## Mode Packs
|
||||
> **新特性：** 无需创建 Combo。在任何客户端中直接使用 `auto/` 前缀。
|
||||
|
||||
| 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 |
|
||||
### 快速示例
|
||||
|
||||
## Self-Healing
|
||||
| 模型 ID | 变体 | 行为 |
|
||||
| -------------- | -------- | ------------------------------------------------------------------------ |
|
||||
| `auto` | 默认 | 所有已连接服务商，LKGP 策略，均衡权重 |
|
||||
| `auto/coding` | coding | 质量优先权重，适合代码生成 |
|
||||
| `auto/fast` | fast | 低延迟加权选择 |
|
||||
| `auto/cheap` | cheap | 成本优先路由（最便宜优先） |
|
||||
| `auto/offline` | offline | 偏好配额余量最高的服务商 |
|
||||
| `auto/smart` | smart | 质量优先 + 更高探索率（10%）以获得更好的模型发现 |
|
||||
| `auto/lkgp` | lkgp | 显式 LKGP（与默认 `auto` 相同） |
|
||||
|
||||
- **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
|
||||
### 类别 × 层级组合（`auto/<category>:<tier>`）
|
||||
|
||||
## Bandit Exploration
|
||||
OpenRouter 风格的后缀将**什么类型的路由**（类别）与**如何优化它**（层级）分开，让你可以自由组合（#4235 Phase B，`open-sse/services/autoCombo/suffixComposition.ts`）：
|
||||
|
||||
5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode.
|
||||
- **类别**（按能力筛选候选池）：`coding` · `reasoning` · `vision` · `chat` · `multimodal`。`vision`/`multimodal` 保留具备视觉能力的模型；`reasoning` 保留推理/思考模型。
|
||||
- **层级**（选择评分权重 / 池过滤器）：`fast`（ship-fast）· `cheap`（别名 `floor`，cost-saver）· `reliable`（熔断器健康 + 延迟稳定性）· `free` / `pro`（通过 `classifyTier` 按模型层级筛选池——免费层 vs. 高级层）。
|
||||
|
||||
| 示例 | 解析为 |
|
||||
| ----------------------- | ------------------------------------------------------ |
|
||||
| `auto/coding:fast` | coding 池，低延迟权重 |
|
||||
| `auto/coding:cheap` | coding 池，成本优先（别名 `auto/coding:floor`） |
|
||||
| `auto/reasoning:pro` | 仅推理/思考模型，高级层 |
|
||||
| `auto/vision` | 具备视觉能力的模型（无层级 → 均衡权重） |
|
||||
| `auto/multimodal:free` | 具备多模态能力的模型，仅免费层 |
|
||||
|
||||
任何有效的 `auto/<category>[:<tier>]` 都按需解析；精选子集通过 `/v1/models` 和仪表盘宣传（`AUTO_SUFFIX_VARIANTS`，见 `open-sse/services/autoCombo/builtinCatalog.ts`）。过滤策略为**失效开放（fail-open）** ——如果约束条件未匹配到任何已连接的模型，则使用全量池，确保路由永不中断。核心评分器（`combo.ts`）保持不变；类别/层级过滤器在 `buildAutoCandidates` 中应用。
|
||||
|
||||
> **实时模型智能：** 当 `ARENA_ELO_SYNC_ENABLED` 开关打开时，自动路由的适配度由实时的 **Arena ELO** 排名 + **models.dev** 层级数据驱动（否则回退到静态适配度映射表）。
|
||||
|
||||
**使用方法：**
|
||||
|
||||
```bash
|
||||
# 任何支持 OpenAI 格式的 IDE 或 CLI 工具
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: <your-endpoint-key>
|
||||
|
||||
# 在代码/配置中，将 model 设置为：
|
||||
model: "auto" # 均衡默认
|
||||
model: "auto/coding" # 代码任务最佳
|
||||
model: "auto/fast" # 最快可用
|
||||
model: "auto/cheap" # 每 Token 最便宜
|
||||
```
|
||||
|
||||
**执行流程：**
|
||||
|
||||
1. OmniRoute 在 `src/sse/handlers/chat.ts` 中检测 `auto/` 前缀
|
||||
2. 从数据库查询所有**活跃的服务商连接**
|
||||
3. 过滤出具备有效凭据的（API Key 或 OAuth Token）
|
||||
4. 确定每个连接的模型（`connection.defaultModel` 或服务商的第一个模型）
|
||||
5. 在内存中构建**虚拟 Combo**（不存入数据库）
|
||||
6. 使用所选变体的权重配置 + LKGP 策略进行路由
|
||||
|
||||
**核心特性：**
|
||||
|
||||
- ✅ **始终在线：** 无需切换、无需创建 Combo、无需任何配置
|
||||
- ✅ **动态：** 自动反映当前已连接的服务商
|
||||
- ✅ **会话粘性：** LKGP 确保优先使用上一次成功的服务商
|
||||
- ✅ **多账号感知：** 每个服务商连接都成为独立的候选
|
||||
- ✅ **无数据库写入：** 虚拟 Combo 仅存在于请求期间，零持久化开销
|
||||
|
||||
**底层机制：**
|
||||
|
||||
```txt
|
||||
Request: { model: "auto/coding" }
|
||||
↓
|
||||
src/sse/handlers/chat.ts 检测前缀
|
||||
↓
|
||||
createVirtualAutoCombo('coding') → 从活跃连接构建候选池
|
||||
↓
|
||||
handleComboChat（与持久化 Combo 相同的引擎）
|
||||
↓
|
||||
自动评分为每次请求选择最佳服务商/模型
|
||||
```
|
||||
|
||||
**实现文件：**
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------------------------------------------- | ---------------------------------------- |
|
||||
| `open-sse/services/autoCombo/autoPrefix.ts` | 前缀解析器（`parseAutoPrefix`） |
|
||||
| `open-sse/services/autoCombo/virtualFactory.ts` | 创建虚拟 `AutoComboConfig` 对象 |
|
||||
| `open-sse/services/autoCombo/providerRegistryAccessor.ts` | 模拟服务商注册表的测试 hook |
|
||||
| `src/sse/handlers/chat.ts` | 集成：auto 前缀短路 |
|
||||
| `src/shared/constants/providers.ts` | `SYSTEM_PROVIDERS.auto` 系统条目 |
|
||||
|
||||
## 工作原理（持久化 Auto-Combo）
|
||||
|
||||
Auto-Combo 引擎使用**12 因子评分函数**（定义在 `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`）为每次请求动态选择最佳服务商/模型。所有权重之和为 **1.0**。
|
||||
|
||||
|
||||
|
||||
> 来源：[diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd)（通过 `npm run docs:render-diagrams` 重新生成）。
|
||||
|
||||
| 因子 | 默认权重 | 描述 |
|
||||
| :---------------------- | :------- | :--------------------------------------------------------------------------------------------- |
|
||||
| `health` | 0.20 | 来自熔断器的健康评分（CLOSED=1.0，HALF_OPEN=0.5，OPEN=0.0） |
|
||||
| `quota` | 0.15 | 剩余配额 / 速率限制余量 [0..1] |
|
||||
| `costInv` | 0.15 | 反向**混合**成本（60% 输入 + 40% 输出 Token 价格，归一化）——越便宜得分越高 |
|
||||
| `latencyInv` | 0.12 | 反向 p95 延迟，按池归一化——越快得分越高 |
|
||||
| `taskFit` | 0.08 | 任务类型适配度（coding、review、planning、analysis、debugging、docs） |
|
||||
| `stability` | 0.05 | 基于方差的稳定性（低延迟标准差 / 错误率） |
|
||||
| `tierPriority` | 0.05 | 账号层级优先级——Ultra=1.0，Pro=0.67，Standard=0.33，Free=0.0 |
|
||||
| `tierAffinity` | 0.05 | 候选层级与清单推荐层级之间的亲和度 |
|
||||
| `specificityMatch` | 0.05 | 请求特异性（清单提示）与模型层级之间的匹配度 |
|
||||
| `contextAffinity` | 0.05 | 请求上下文窗口需求与模型上下文窗口之间的亲和度 |
|
||||
| `connectionDensity` | 0.05 | 将负载分散到同一服务商的不同连接上（反集中） |
|
||||
| `resetWindowAffinity` | 0.00 | 偏向配额重置窗口有利的连接（默认禁用） |
|
||||
|
||||
**总和：** `0.20 + 0.15 + 0.15 + 0.12 + 0.08 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.00 = 1.0`（由 `validateWeights()` 校验）。
|
||||
|
||||
## 模式包
|
||||
|
||||
`open-sse/services/autoCombo/modePacks.ts` 中定义了四种预置的权重配置文件。每种模式包覆盖默认权重，以将选择偏向特定目标。以下是**每种模式包的完整权重表**（每行之和为 1.0）。
|
||||
|
||||
| 因子 | ship-fast | cost-saver | quality-first | offline-friendly |
|
||||
| :------------- | :-------- | :--------- | :------------ | :--------------- |
|
||||
| quota | 0.14 | 0.14 | 0.10 | **0.37** |
|
||||
| health | 0.28 | 0.19 | 0.18 | 0.28 |
|
||||
| costInv | 0.05 | **0.37** | 0.05 | 0.10 |
|
||||
| latencyInv | **0.32** | 0.05 | 0.05 | 0.05 |
|
||||
| taskFit | 0.10 | 0.10 | **0.37** | 0.00 |
|
||||
| stability | 0.00 | 0.05 | 0.15 | 0.10 |
|
||||
| tierPriority | 0.05 | 0.05 | 0.05 | 0.05 |
|
||||
|
||||
说明：
|
||||
|
||||
- `tierAffinity` 和 `specificityMatch` 不在模式包中设置——`calculateScore()` 在缺席时当作 `?? 0` 处理。
|
||||
- 每种模式包的核心侧重一览：
|
||||
- **ship-fast** → latencyInv 0.32 + health 0.28（低延迟、健康的连接）
|
||||
- **cost-saver** → costInv 0.37（最便宜的 Token 获胜）
|
||||
- **quality-first** → taskFit 0.37 + stability 0.15（最适合任务的模型，稳定一致）
|
||||
- **offline-friendly** → quota 0.37 + health 0.28（最大余量，不论速度/成本）
|
||||
|
||||
## 全部路由策略
|
||||
|
||||
OmniRoute 的 Combo 引擎支持 **17 种路由策略**（声明在 `src/shared/constants/routingStrategies.ts` → `ROUTING_STRATEGY_VALUES`）。Auto Combo 引擎本身以 `auto` 策略对外暴露；其余策略供持久化 Combo 使用。
|
||||
|
||||
| 策略 | 描述 |
|
||||
| :-------------------- | :----------------------------------------------------------------------------------------- |
|
||||
| `priority` | 带显式优先级的首个目标顺序列表 |
|
||||
| `weighted` | 按每目标权重的加权随机 |
|
||||
| `round-robin` | 按顺序轮流遍历目标 |
|
||||
| `context-relay` | 跨目标交接上下文（长对话） |
|
||||
| `fill-first` | 填满每个目标的配额后再移到下一个 |
|
||||
| `p2c` | Power-of-2-choices 随机负载均衡 |
|
||||
| `random` | 均匀随机选择 |
|
||||
| `least-used` | 选择当前负载最低的目标 |
|
||||
| `cost-optimized` | 根据目录定价最小化每次请求的 $ |
|
||||
| `reset-aware` ⭐ | 按配额重置时间优先——较短的重置窗口排名更高 |
|
||||
| `reset-window` | 偏好配额窗口最快重置的目标 |
|
||||
| `headroom` | 选择剩余配额余量最多的目标 |
|
||||
| `strict-random` | 无去重重复的随机选择 |
|
||||
| `auto` | 使用 Auto Combo 评分（9 因子）——**推荐** |
|
||||
| `lkgp` | 上一次成功路径（粘性路由到上次成功的目标） |
|
||||
| `context-optimized` | 选择最适合当前上下文大小的目标 |
|
||||
| `fusion` 🧬 | 并行扩散到一组评审团模型，然后通过裁判模型合成一个答案（见下文） |
|
||||
|
||||
⭐ = v3.8.0 新增 · 🧬 = v3.8.36 新增
|
||||
|
||||
## Fusion 策略
|
||||
|
||||
`fusion` 是唯一**不**选择单个目标的策略。它将提示**并行扩散给每个评审团模型**，然后由可配置的**裁判模型**从所有评审团响应中合成为一个最终答案。从上游 `decolua/9router`（OpenRouter 的 Fusion 设计）移植；实现在 `open-sse/services/fusion.ts`。
|
||||
|
||||
工作方式：
|
||||
|
||||
1. **扩散**——提示同时发送给每个评审团模型，强制非流式，且剥离工具（裁判模型需要完整的文本来合成）。
|
||||
2. **法定-宽限收集**——一旦 `minPanel` 个答案到达，启动短暂的宽限计时器等待落后者，然后以收集到的内容进行融合。这为最慢的模型设置了对墙上时间的惩罚上限，并受硬超时限制。
|
||||
3. **裁判合成**——评审团答案被匿名化（`Source 1`、`Source 2`、……——这样裁判看重的是内容质量而非模型品牌），提交给裁判模型，由它分析共识/矛盾/部分覆盖/独特洞察/盲点，然后撰写**一个**权威答案。裁判调用保留客户端的原始 `stream` 标志 + 工具，因此流式传输和下游工具使用仍然有效。
|
||||
4. **优雅降级**——0 个评审团答案 → `503`；恰好 1 个幸存者 → 直接返回该答案（无物可融合）；单模型评审团直接回答。
|
||||
|
||||
### 配置
|
||||
|
||||
在 Combo 的 `config` blob 上配置（无需 Schema 迁移——复用现有的 `combos` 表）：
|
||||
|
||||
| 字段 | 类型 | 默认值 | 用途 |
|
||||
| :---------------------------------------- | :------- | :----------------- | :-------------------------------------------------------------------------------- |
|
||||
| `config.judgeModel` | `string` | 第一个评审团模型 | 合成最终答案的模型 |
|
||||
| `config.fusionTuning.minPanel` | `number` | `2` | 宽限计时器启动前需要的成功答案数（限制在 `[2, panelSize]` 范围内） |
|
||||
| `config.fusionTuning.stragglerGraceMs` | `number` | `8000` | 达到法定人数后等待落后者的时长 |
|
||||
| `config.fusionTuning.panelHardTimeoutMs` | `number` | `90000` | 绝对上限，防止一个挂起的模型阻塞整个请求 |
|
||||
|
||||
默认值见 `FUSION_DEFAULTS`（`open-sse/services/fusion.ts`）。
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/api/combos \
|
||||
-H "Authorization: Bearer <key>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "fusion-panel",
|
||||
"strategy": "fusion",
|
||||
"targets": [
|
||||
{ "model": "cc/claude-opus-4-7" },
|
||||
{ "model": "cx/gpt-5.5" },
|
||||
{ "model": "glm/glm-5.1" }
|
||||
],
|
||||
"config": {
|
||||
"judgeModel": "cc/claude-opus-4-7",
|
||||
"fusionTuning": { "minPanel": 2, "stragglerGraceMs": 8000, "panelHardTimeoutMs": 90000 }
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
然后像任何 Combo 一样调用：`{"model":"fusion-panel","messages":[...]}`。
|
||||
|
||||
## 虚拟 Auto-Combo 工厂
|
||||
|
||||
Auto Combo 引擎不需要预定义的 Combo。相反，`open-sse/services/autoCombo/virtualFactory.ts` 动态构建候选：
|
||||
|
||||
1. 拉取 `getProviderConnections({ isActive: true })`（所有已启用的连接）
|
||||
2. 过滤出具备有效凭据的（API Key 或未过期的 OAuth Token，通过 `hasUsableOAuthToken()`）
|
||||
3. 与 `getProviderRegistry()` 交叉引用以获取模型可用性 + 定价
|
||||
4. 为每个 `(provider, model, connection)` 元组建构 `VirtualAutoComboCandidate`
|
||||
5. 选取 `connection.defaultModel`（或注册表中的第一个模型）作为调度目标
|
||||
6. 使用 9 因子 `scorePool()` 和变体的权重包对每个候选评分
|
||||
7. 将生成的仅内存 `AutoComboConfig` 返回给 `handleComboChat()`——从不持久化到数据库
|
||||
|
||||
这意味着**添加一个启用 `auto/*` 的新服务商会自动扩展候选池**——无需手动修改 Combo。虚拟 Combo 按请求重建，因此新增或新恢复健康的连接会立即被识别。
|
||||
|
||||
## 自愈
|
||||
|
||||
- **临时排除：** 评分 < 0.2 → 排除 5 分钟（渐进退避，最长 30 分钟）
|
||||
- **熔断器感知：** OPEN → 自动排除；HALF_OPEN → 探测请求
|
||||
- **事故模式：** >50% OPEN → 禁用探索，最大化稳定性
|
||||
- **冷却恢复：** 排除后，第一个请求作为"探测"，缩短超时
|
||||
|
||||
## Bandit 探索
|
||||
|
||||
5% 的请求（可配置）路由到随机服务商进行探索。事故模式下禁用。
|
||||
|
||||
## API
|
||||
|
||||
```bash
|
||||
# Create 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"}'
|
||||
**没有专用的 `POST /api/combos/auto` 端点**——Auto-Combo 通过两种方式消费：
|
||||
|
||||
# List auto-combos
|
||||
curl http://localhost:20128/api/combos/auto
|
||||
1. **零配置（推荐）：** 发送任何带 `model: "auto"` 或 `model: "auto/<variant>"` 的聊天补全请求。虚拟工厂按请求构建 Combo——无需持久化，无需 API 调用。
|
||||
|
||||
2. **使用 `strategy: "auto"` 的持久化 Combo：** 通过 `POST /api/combos` 创建常规 Combo，设置 `strategy: "auto"` 加上 `config.auto.weights` / `config.auto.candidatePool`。使用相同的评分引擎；Combo 存入 `combos` 表，按 ID 复用。
|
||||
|
||||
对于发现，`GET /api/combos/auto` 列出每个变体及其已解析的候选池，加上 `context_length` / `max_output_tokens`——取候选池窗口的 MAX 值。客户端（如 opencode 插件）必须宣传这些值而不是 `0`：上下文为零会完全禁用 opencode 的自动压缩，导致会话持续增长直到网关的历史记录清理销毁上下文。宣传 MAX 值是安全的，因为 auto-combo 上下文预过滤器会将超大请求路由到大窗口候选。
|
||||
|
||||
```bash
|
||||
# 零配置用法（无需创建 Combo）
|
||||
curl -X POST http://localhost:20128/v1/chat/completions \
|
||||
-H "Authorization: Bearer <key>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"auto/coding","messages":[{"role":"user","content":"Hello"}]}'
|
||||
|
||||
# 通过常规 Combo 端点创建持久化 Auto Combo
|
||||
curl -X POST http://localhost:20128/api/combos \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"id":"my-auto","name":"Auto Coder","strategy":"auto","config":{"auto":{"candidatePool":["anthropic","google","openai"],"weights":{"quota":0.15,"health":0.3,"costInv":0.05,"latencyInv":0.35,"taskFit":0.1,"stability":0,"tierPriority":0.05}}}}'
|
||||
```
|
||||
|
||||
## Task Fitness
|
||||
### Auto Router 策略
|
||||
|
||||
30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score).
|
||||
持久化的 `strategy: "auto"` Combo 可以设置 `config.routerStrategy`（或旧版 `config.auto.routerStrategy`）为以下之一：
|
||||
|
||||
## Files
|
||||
- `rules` — 默认加权评分
|
||||
- `cost` / `eco` — 选择最便宜的健康服务商
|
||||
- `latency` / `fast` — 选择最低 p95 延迟且带可靠性惩罚的服务商
|
||||
- `sla-aware` / `sla` — 偏好满足 p95 延迟、错误率和可选的成本 SLO 的候选
|
||||
- `lkgp` — 优先使用上一次成功路径的服务商
|
||||
|
||||
| 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 |
|
||||
### Router 策略详解
|
||||
|
||||
Auto-Combo 引擎暴露了 5 个可插拔的 **RouterStrategy** 实现，可通过 `config.routerStrategy`（或旧版 `config.auto.routerStrategy`）切换。每个策略从候选池中选取一个服务商，依据 `RoutingContext`（任务类型、工具/视觉提示、Token 估算、可选的 SLA 策略、可选的上次成功路径服务商）。
|
||||
|
||||
#### 1. `rules`（默认）— 6 因子加权评分
|
||||
|
||||
封装现有的评分引擎。过滤掉 `OPEN` 熔断器候选，然后使用当前任务类型和 `getTaskFitness()` 运行 `scorePool()`，选择得分最高的服务商。
|
||||
|
||||
```ts
|
||||
class RulesStrategyImpl implements RouterStrategy {
|
||||
readonly name = "rules";
|
||||
readonly description =
|
||||
"6-factor weighted scoring: quota, health, cost, latency, taskFit, stability";
|
||||
|
||||
select(pool, context) {
|
||||
const eligible = pool.filter((c) => c.circuitBreakerState !== "OPEN");
|
||||
const ranked = scorePool(
|
||||
eligible.length > 0 ? eligible : pool,
|
||||
context.taskType,
|
||||
undefined,
|
||||
getTaskFitness
|
||||
);
|
||||
return { provider: ranked[0].provider /* ... */ };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：默认。在所有信号之间寻求均衡权衡。
|
||||
|
||||
**别名**：`rules`（无别名）
|
||||
|
||||
---
|
||||
|
||||
#### 2. `cost` / `eco` — 选择最便宜的健康服务商
|
||||
|
||||
按 `costPer1MTokens`（升序）排序候选池，选择最便宜的。先过滤掉 `OPEN` 候选。
|
||||
|
||||
```ts
|
||||
class CostStrategyImpl implements RouterStrategy {
|
||||
readonly name = "cost";
|
||||
readonly description = "Always selects cheapest available provider";
|
||||
|
||||
select(pool, context) {
|
||||
const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
|
||||
const sorted = [...healthy].sort((a, b) => a.costPer1MTokens - b.costPer1MTokens);
|
||||
return { provider: sorted[0].provider /* ... */ };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：成本敏感的工作负载、批量处理或后台任务。
|
||||
|
||||
**别名**：`cost`、`eco`
|
||||
|
||||
---
|
||||
|
||||
#### 3. `latency` / `fast` — 最低 p95 延迟，带可靠性惩罚
|
||||
|
||||
按 `p95LatencyMs + (errorRate * 1000)` 排序。错误率惩罚确保即使名义延迟低的不可靠服务商排名也更靠后。
|
||||
|
||||
```ts
|
||||
class LatencyStrategyImpl implements RouterStrategy {
|
||||
readonly name = "latency";
|
||||
readonly description = "Prioritizes lowest p95 latency with reliability weighting";
|
||||
|
||||
select(pool, context) {
|
||||
const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
|
||||
const sorted = [...healthy].sort(
|
||||
(a, b) => a.p95LatencyMs + a.errorRate * 1000 - (b.p95LatencyMs + b.errorRate * 1000)
|
||||
);
|
||||
return { provider: sorted[0].provider /* ... */ };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：延迟敏感的工作负载，如实时聊天、自动补全或交互式编程助手。
|
||||
|
||||
**别名**：`latency`、`fast`
|
||||
|
||||
---
|
||||
|
||||
#### 4. `sla-aware` / `sla` — 延迟/错误/成本 SLO 合规
|
||||
|
||||
按候选满足已配置 SLO 策略的程度评分：
|
||||
|
||||
| 因子 | 权重 | 公式 |
|
||||
| ----------------- | ---- | ------------------------------------------------- |
|
||||
| 延迟评分 | 35% | `threshold / max(value, ε)` |
|
||||
| 错误评分 | 35% | `threshold / max(value, ε)` |
|
||||
| 健康评分 | 15% | `1.0`（CLOSED）/ `0.5`（HALF_OPEN）/ `0.0`（OPEN） |
|
||||
| 成本评分 | 10% | `threshold / max(value, ε)` 或反向归一化 |
|
||||
| 稳定性评分 | 5% | 反向归一化延迟标准差 |
|
||||
|
||||
当 `hardConstraints: true` 时，候选主要按**违规评分**（超出任何 SLO 的程度）排序，然后按综合评分。否则仅按综合评分。
|
||||
|
||||
```ts
|
||||
class SLAStrategyImpl implements RouterStrategy {
|
||||
readonly name = "sla-aware";
|
||||
readonly description =
|
||||
"Selects the provider most likely to satisfy latency, error-rate, and cost SLOs";
|
||||
|
||||
select(pool, context) {
|
||||
// ... 针对策略对每个候选评分：{ targetP95Ms, maxErrorRate, maxCostPer1MTokens, hardConstraints }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**SLA 字段**（在 Combo 配置上设置）：
|
||||
|
||||
```json
|
||||
{
|
||||
"strategy": "auto",
|
||||
"config": {
|
||||
"routerStrategy": "sla-aware",
|
||||
"slaTargetP95Ms": 1500,
|
||||
"slaMaxErrorRate": 0.05,
|
||||
"slaMaxCostPer1MTokens": 5,
|
||||
"slaHardConstraints": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：对延迟、错误率或成本预算有严格要求的线上工作负载。
|
||||
|
||||
**别名**：`sla-aware`、`sla`
|
||||
|
||||
---
|
||||
|
||||
#### 5. `lkgp` — 首先使用上一次成功路径的服务商
|
||||
|
||||
首先尝试**上一次成功路径的服务商**（如果设置），然后回退到 `rules` 策略。适用于会话粘性——同一服务商处理同一对话中的后续请求。
|
||||
|
||||
```ts
|
||||
class LKGPStrategyImpl implements RouterStrategy {
|
||||
readonly name = "lkgp";
|
||||
readonly description = "Tries last known good provider first, then falls back to rules";
|
||||
|
||||
select(pool, context) {
|
||||
if (context.lkgpEnabled === false) {
|
||||
return getStrategy("rules").select(pool, context);
|
||||
}
|
||||
|
||||
if (context.lastKnownGoodProvider) {
|
||||
const candidates = pool.filter(
|
||||
(c) => c.provider === context.lastKnownGoodProvider && c.circuitBreakerState !== "OPEN"
|
||||
);
|
||||
if (candidates.length > 0) {
|
||||
return { provider: candidates[0].provider /* ... */ };
|
||||
}
|
||||
}
|
||||
|
||||
// 回退到 rules 策略
|
||||
return getStrategy("rules").select(pool, context);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：希望同一服务商处理后续请求的多轮对话（例如为了缓存、上下文连续性或定价一致性）。
|
||||
|
||||
**别名**：`lkgp`（无别名）
|
||||
|
||||
---
|
||||
|
||||
### 自定义 Router 策略
|
||||
|
||||
你可以通过公共 API 注册自己的 `RouterStrategy` 实现：
|
||||
|
||||
```ts
|
||||
import {
|
||||
registerStrategy,
|
||||
type RouterStrategy,
|
||||
} from "@omniroute/open-sse/services/autoCombo/routerStrategy";
|
||||
|
||||
class MyCustomStrategy implements RouterStrategy {
|
||||
readonly name = "my-custom";
|
||||
readonly description = "My custom routing strategy";
|
||||
|
||||
select(pool, context) {
|
||||
// 你的路由逻辑
|
||||
return {
|
||||
provider: pool[0].provider,
|
||||
model: pool[0].model,
|
||||
strategy: this.name,
|
||||
reason: "MyCustomStrategy: ...",
|
||||
candidatesConsidered: pool.length,
|
||||
finalScore: 1.0,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
registerStrategy("my-custom", new MyCustomStrategy());
|
||||
```
|
||||
|
||||
然后使用它：
|
||||
|
||||
```json
|
||||
{
|
||||
"strategy": "auto",
|
||||
"config": {
|
||||
"routerStrategy": "my-custom"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Router 策略选择指南
|
||||
|
||||
| 使用场景 | 策略 | 原因 |
|
||||
| ------------ | ----------- | ---------------------------------- |
|
||||
| 均衡工作负载 | `rules` | 默认——考虑所有因素 |
|
||||
| 最小化成本 | `cost` | 始终选择最便宜的 |
|
||||
| 最小化延迟 | `latency` | 选择最快且可靠的服务商 |
|
||||
| 严格 SLO | `sla-aware` | 按 p95/错误/成本阈值过滤 |
|
||||
| 多轮聊天 | `lkgp` | 会话粘性 |
|
||||
|
||||
SLA-aware 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"strategy": "auto",
|
||||
"config": {
|
||||
"routerStrategy": "sla-aware",
|
||||
"slaTargetP95Ms": 1500,
|
||||
"slaMaxErrorRate": 0.05,
|
||||
"slaMaxCostPer1MTokens": 5,
|
||||
"slaHardConstraints": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 任务适配度
|
||||
|
||||
30+ 个模型在 6 种任务类型（`coding`、`review`、`planning`、`analysis`、`debugging`、`documentation`）中评分。支持通配符模式（例如 `*-coder` → 高 coding 评分）。
|
||||
|
||||
## Auto 变体总览
|
||||
|
||||
包括裸 `auto`（默认）加上 `autoPrefix.ts` 中声明的 6 个 `AutoVariant` 值，共有 **7 个可调用的模型 ID**：
|
||||
|
||||
`auto`、`auto/coding`、`auto/fast`、`auto/cheap`、`auto/offline`、`auto/smart`、`auto/lkgp`
|
||||
|
||||
（`AutoVariant` 本身枚举 6 个值；第 7 个选项是"无变体"——裸 `auto`——由 `parseAutoPrefix()` 处理为 `variant: undefined`。）
|
||||
|
||||
## 层级如何融入 Auto-Combo
|
||||
|
||||
12 因子评分函数（`open-sse/services/autoCombo/scoring.ts`）将层级归属作为两个信号：`tierPriority`（0.05）和 `tierAffinity`（0.05）。完整 `DEFAULT_WEIGHTS` 集合见上文[规范评分因子表](#工作原理持久化-auto-combo)——各模式包的覆盖（ship-fast/cost-saver/quality-first/offline-friendly）列在"每种模式包的权重"表中。
|
||||
|
||||
仅凭层级**不**强制 Tier 1 优先——如果 Tier 1 延迟不佳或成本性价比不理想，Tier 2 胜出。要强制按层级排序，使用 Combo 策略 `priority` 并按层级排列服务商。
|
||||
|
||||
要强烈偏向 Tier 1（订阅层），增大 `tierPriority` 权重：
|
||||
|
||||
```json
|
||||
{
|
||||
"strategy": "auto",
|
||||
"config": { "auto": { "weights": { "tierPriority": 0.3, "costInv": 0.05 } } }
|
||||
}
|
||||
```
|
||||
|
||||
层级定义和服务商分类参见 `docs/marketing/TIERS.md`。
|
||||
|
||||
## 测试与覆盖率
|
||||
|
||||
### 确定性路由决策矩阵（`npm run test:combo:matrix`）
|
||||
|
||||
`tests/integration/combo-matrix/*.test.ts` 通过完整的 Combo 管线以端到端方式（使用模拟上游）验证了全部 17 种公开策略的路由**决策**。覆盖范围包括：
|
||||
|
||||
- 全部 17 种 `ROUTING_STRATEGY_VALUES` 策略（ordered、weighted、cost、context、fusion 等）。
|
||||
- `quota-share`（内部）端到端：通过真实的 `selectQuotaShareTarget` 接缝（`registerQuotaFetcher` / `setLKGP` / `__setHeadroomSaturationFetcherForTests`）验证 DRR 公平性 + 饱和降优。
|
||||
- `context-relay` 在所有目标数量上通用的跨上下文交换覆盖。
|
||||
|
||||
该测试套件在 CI 中运行（`test:integration` 任务），使用 `--test-concurrency=1` 和 `--test-force-exit`，因此是确定性的且不需要真实凭据。
|
||||
|
||||
### 有人值守的实时冒烟测试（非 CI —— 真实服务商）
|
||||
|
||||
| 命令 | 功能 |
|
||||
| :-------------------------------------- | :------------------------------------------------------------------------------- |
|
||||
| `npm run test:combo:live` | 进程内真实路由，`RUN_COMBO_LIVE=1`；对活跃的 OmniRoute 数据库做快照 |
|
||||
| `npm run test:combo:live:vps` | 针对活跃的 OmniRoute 服务器进行 HTTP 调用（设置 `COMBO_LIVE_BASE_URL`） |
|
||||
| `npm run test:combo:live:vps:failover` | 同上，包含预定的容灾方案场景 |
|
||||
|
||||
这些冒烟测试演练了真实的网络路径（Combo → 服务商 → 补全）。它们被特地从 CI 中排除，因为需要真实凭据和 VPS 访问。
|
||||
|
||||
---
|
||||
|
||||
## 文件
|
||||
|
||||
| 文件 | 用途 |
|
||||
| :---------------------------------------------------------- | :------------------------------------------------------------------------ |
|
||||
| `open-sse/services/autoCombo/scoring.ts` | 9 因子评分函数、`DEFAULT_WEIGHTS`、池归一化 |
|
||||
| `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 种权重配置（ship-fast、cost-saver、quality-first、offline-friendly） |
|
||||
| `open-sse/services/autoCombo/autoPrefix.ts` | `auto/` 前缀解析器 + 6 种变体 |
|
||||
| `open-sse/services/autoCombo/virtualFactory.ts` | 从活跃连接构建仅内存的 `AutoComboConfig` |
|
||||
| `open-sse/services/autoCombo/providerRegistryAccessor.ts` | 模拟服务商注册表的测试 hook |
|
||||
| `src/shared/constants/routingStrategies.ts` | `ROUTING_STRATEGY_VALUES`（17 种策略） |
|
||||
| `src/sse/handlers/chat.ts` | 集成：auto 前缀短路 |
|
||||
|
||||
@@ -177,12 +177,15 @@ function checkI18nChangelogFile(sourcePath) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Verify body size is within 25% tolerance of source (translations may
|
||||
// expand or shrink, but drastic size differences indicate stale content)
|
||||
const sizeDiff = Math.abs(normalizedBody.length - sourceBody.length) / sourceBody.length;
|
||||
// Verify body line count is within 25% tolerance of source (translations
|
||||
// should preserve structure — drastic line-count differences indicate
|
||||
// stale or missing content)
|
||||
const sourceLines = sourceBody.split("\n").length;
|
||||
const targetLines = normalizedBody.split("\n").length;
|
||||
const sizeDiff = Math.abs(targetLines - sourceLines) / sourceLines;
|
||||
if (sizeDiff > 0.25) {
|
||||
fail(
|
||||
`docs/i18n/${locale}/${fileName} body size differs by ${(sizeDiff * 100).toFixed(0)}% from root (expected within 25%)`
|
||||
`docs/i18n/${locale}/${fileName} body line count differs by ${(sizeDiff * 100).toFixed(0)}% from root (expected within 25%)`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user