From 8c25188aab6349211fa32478049b158fb7c8ef5a Mon Sep 17 00:00:00 2001 From: DevinZeng Date: Fri, 3 Jul 2026 01:34:25 +0800 Subject: [PATCH 1/4] docs(i18n): complete Chinese (Simplified) translation of all docs Translate all 26 documentation files under docs/i18n/zh-CN/: - Top-level: README, CHANGELOG, CLAUDE, CONTRIBUTING, CODE_OF_CONDUCT, GEMINI, SECURITY, llm.txt - Architecture: ARCHITECTURE, CODEBASE_DOCUMENTATION - Frameworks: MCP-SERVER, A2A-SERVER - Routing: AUTO-COMBO - Guides: USER_GUIDE, FEATURES, I18N, TROUBLESHOOTING, UNINSTALL, CLI-TOOLS - Operations: COVERAGE_PLAN, FLY_IO, VM_DEPLOYMENT, RELEASE_CHECKLIST - Reference: API_REFERENCE, ENVIRONMENT - Features: context-relay, cloudflare-zero-trust Translation principles: faithful, expressive, and elegant Chinese. Key branding terms (Combo/Token/MCP/A2A) kept untranslated. Chinese active-voice sentences preferred over passive constructions. --- docs/i18n/zh-CN/CHANGELOG.md | 674 ++++---- docs/i18n/zh-CN/CLAUDE.md | 549 ++++--- docs/i18n/zh-CN/CODE_OF_CONDUCT.md | 135 +- docs/i18n/zh-CN/CONTRIBUTING.md | 418 ++--- docs/i18n/zh-CN/GEMINI.md | 57 +- docs/i18n/zh-CN/README.md | 717 ++++----- docs/i18n/zh-CN/SECURITY.md | 255 ++-- .../zh-CN/docs/architecture/ARCHITECTURE.md | 1278 ++++++++++------ .../architecture/CODEBASE_DOCUMENTATION.md | 1215 +++++++++------ .../zh-CN/docs/cloudflare-zero-trust-guide.md | 132 +- .../i18n/zh-CN/docs/features/context-relay.md | 128 +- docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md | 157 +- docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md | 452 +++++- docs/i18n/zh-CN/docs/guides/FEATURES.md | 299 ++-- docs/i18n/zh-CN/docs/guides/I18N.md | 599 +++++--- .../i18n/zh-CN/docs/guides/TROUBLESHOOTING.md | 509 ++++--- docs/i18n/zh-CN/docs/guides/UNINSTALL.md | 132 +- docs/i18n/zh-CN/docs/guides/USER_GUIDE.md | 953 +++++++----- docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md | 219 +-- .../zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md | 70 +- docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md | 338 +++- .../zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md | 241 +-- .../zh-CN/docs/reference/API_REFERENCE.md | 1320 +++++++++++++--- docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md | 696 ++++++--- docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md | 1356 +++++++++++------ docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md | 600 +++++++- docs/i18n/zh-CN/llm.txt | 858 +++++------ 27 files changed, 9293 insertions(+), 5064 deletions(-) diff --git a/docs/i18n/zh-CN/CHANGELOG.md b/docs/i18n/zh-CN/CHANGELOG.md index c7bae62a6feb..fb9f7c4a5387 100644 --- a/docs/i18n/zh-CN/CHANGELOG.md +++ b/docs/i18n/zh-CN/CHANGELOG.md @@ -8,89 +8,89 @@ ## [3.8.42] — 2026-06-30 -### ✨ New Features +### ✨ 新功能 -- **compression (pipeline):** add an honest default-on **inflation guard** to the stacked compression pipeline (T02 / Headroom H1). If the fully-stacked engines produce a body that did not actually shrink — its token count is `>=` the original — the compressed body is discarded and the verbatim original request is sent upstream instead, with a `pipeline-inflation-guard` warning recorded in the compression stats. This is safe by construction (the only fallback is the unmodified original, always a valid payload) and complements the existing opt-in per-step TV1 bail-out, which governs step-to-step advancement rather than the final output. New `open-sse/services/compression/pipelineGuards.ts`; wired at the single `finalizeStackedResult` choke point shared by the sync and async stacked paths. Regression guards (incl. an inflating-engine integration test) in `tests/unit/compression-pipeline-inflation-guard.test.ts`. +- **compression (pipeline):** 为级联压缩管线（T02 / Headroom H1）新增默认启用的**膨胀防护**。如果完全级联的引擎产生的输出实际上没有缩小——其 Token 数量 `>=` 原始值——则丢弃压缩结果，改为向上游发送原始请求，并在压缩统计中记录 `pipeline-inflation-guard` 警告。这通过构造保证了安全（唯一的回退是未修改的原始请求，始终是有效载荷），并补充了现有的可选每步 TV1 退出机制（后者控制步骤间的推进而非最终输出）。新增 `open-sse/services/compression/pipelineGuards.ts`；在同步和异步级联路径共享的单一 `finalizeStackedResult` 关键点接入。回归测试（含膨胀引擎集成测试）在 `tests/unit/compression-pipeline-inflation-guard.test.ts`。 -- **compression (caveman):** complete the German, French, and Japanese rule packs with the `dedup` (repeated-context collapsing) and `ultra` (abbreviation / terse) categories they were missing — these three languages previously shipped only `context`/`filler`/`structural`, while `en`/`es`/`id`/`pt-BR` had all five. So a de/fr/ja conversation compressed at higher intensities now collapses repeated boilerplate ("wie bereits besprochen" → "Siehe oben.", "comme mentionné précédemment" → "Voir ci-dessus.", "前述のとおり" → "（上記参照）") and abbreviates dense technical vocabulary (`Datenbank`→`DB`, `Authentifizierung`→`Auth`; `base de données`→`BD`, `authentification`→`auth`; `データベース`→`DB`, `アプリケーション`→`app`). Patterns mirror the existing `es` pack and stay ReDoS-safe (bounded literal alternations; the CJK pack uses no `\b` since Japanese has no word boundaries). Regression guard: `tests/unit/caveman-packs-de-fr-ja.test.ts` (packs load + validate + shrink a representative sample). gaps v3.8.42 — T05/C2. +- **compression (caveman):** 补齐德语、法语和日语规则包的 `dedup`（重复上下文折叠）和 `ultra`（缩写/精简）类别——这三种语言之前仅提供 `context`/`filler`/`structural`，而 `en`/`es`/`id`/`pt-BR` 拥有全部五种。因此以更高强度压缩的 de/fr/ja 对话现在会折叠重复的样板文本（"wie bereits besprochen" → "Siehe oben."、"comme mentionné précédemment" → "Voir ci-dessus."、"前述のとおり" → "（上記参照）"），并缩写密集的技术词汇（`Datenbank`→`DB`、`Authentifizierung`→`Auth`；`base de données`→`BD`、`authentification`→`auth`；`データベース`→`DB`、`アプリケーション`→`app`）。模式与现有的 `es` 包一致，并保持 ReDoS 安全（有界字面量交替；CJK 包不使用 `\b`，因为日语没有词边界）。回归测试：`tests/unit/caveman-packs-de-fr-ja.test.ts`（包加载 + 验证 + 压缩代表性样本）。gaps v3.8.42 — T05/C2。 -- **compression (caveman):** add a **Chinese (zh / wenyan 文言) input-side rule pack** — the counterpart of the existing output-side `terse-cjk` style. New `rules/zh/{dedup,filler,ultra}.json` collapse repeated context ("如前所述" → "见上。"), drop pleasantries/hedging ("请帮我…/谢谢/我觉得"), strip sentence-final modal particles ("吗/呢/吧"), and abbreviate dense technical terms ("数据库"→"DB", "应用程序"→"app"). Chinese is now auto-detected: `detectCompressionLanguage` distinguishes zh from ja by Han-without-kana (kana is Japanese-exclusive, so a Han-heavy Japanese sentence still resolves to `ja`), and `zh` is listed in `listSupportedCompressionLanguages`. Patterns are ReDoS-safe (bounded literal alternations, no `\b` since CJK has no word boundaries). Regression guard: `tests/unit/caveman-packs-zh-wenyan.test.ts` (packs load + validate + shrink; zh/ja/non-CJK detection). gaps v3.8.42 — T05/C6. +- **compression (caveman):** 新增**中文（zh / wenyan 文言）输入侧规则包**——对应已有的输出侧 `terse-cjk` 风格。新增 `rules/zh/{dedup,filler,ultra}.json`，折叠重复上下文（"如前所述" → "见上。"）、删除客套/犹豫用语（"请帮我…/谢谢/我觉得"）、去除句末语气助词（"吗/呢/吧"），并缩写密集技术术语（"数据库"→"DB"、"应用程序"→"app"）。中文现已支持自动检测：`detectCompressionLanguage` 通过"含汉字但不含假名"来区分 zh 和 ja（假名是日语专属，因此含大量汉字的日语语句仍会解析为 `ja`），`zh` 已列入 `listSupportedCompressionLanguages`。模式保持 ReDoS 安全（有界字面量交替，CJK 无语边界因此不使用 `\b`）。回归测试：`tests/unit/caveman-packs-zh-wenyan.test.ts`（包加载 + 验证 + 压缩；zh/ja/非 CJK 检测）。gaps v3.8.42 — T05/C6。 -- **compression (RTK):** add **Gradle** and **.NET CLI (`dotnet`)** to the RTK tool-output filter catalog. Tool output for `gradle`/`gradlew` and `dotnet build|test|restore|publish` is now recognized (both by command and by output content) and compressed: Gradle daemon/welcome banners and no-op `> Task … UP-TO-DATE/SKIPPED/FROM-CACHE` lines are dropped while `BUILD SUCCESSFUL/FAILED`, "What went wrong", and stack traces are preserved; the .NET build banner, copyright, and `Determining projects to restore`/`Restored …` chatter are dropped while `Build succeeded/FAILED`, `error CS####`/`warning CS####`, and test summaries are preserved. New builtin filters `engines/rtk/filters/{gradle,dotnet}.json` (with inline tests run by the catalog gate) plus `gradle`/`dotnet` entries in the command detector. Regression guard: `tests/unit/rtk-gradle-dotnet-filters.test.ts`. gaps v3.8.42 — T07/R9. +- **compression (RTK):** 将 **Gradle** 和 **.NET CLI（`dotnet`）** 添加到 RTK 工具输出过滤器目录。`gradle`/`gradlew` 和 `dotnet build|test|restore|publish` 的工具输出现在可被识别（通过命令和输出内容双重方式）并压缩：Gradle 守护进程/欢迎横幅和无效 `> Task … UP-TO-DATE/SKIPPED/FROM-CACHE` 行被丢弃，而 `BUILD SUCCESSFUL/FAILED`、"What went wrong" 和堆栈跟踪被保留；.NET 构建横幅、版权声明以及 `Determining projects to restore`/`Restored …` 等杂项被丢弃，而 `Build succeeded/FAILED`、`error CS####`/`warning CS####` 和测试摘要被保留。新增内置过滤器 `engines/rtk/filters/{gradle,dotnet}.json`（含由目录门控运行的内联测试），以及命令检测器中的 `gradle`/`dotnet` 条目。回归测试：`tests/unit/rtk-gradle-dotnet-filters.test.ts`。gaps v3.8.42 — T07/R9。 -### 🔧 Bug Fixes +### 🔧 问题修复 -- **providers (chatgpt-web):** fix `502 ChatGPT sentinel failed: Digest method not supported` on the **Electron desktop app**, which made every `chatgpt-web/*` request fail. The sentinel proof-of-work hashed with native `createHash("sha3-512")`, but Electron's Node is built against **BoringSSL, which does not implement the SHA-3 family** (electron/electron#30530), so the digest threw at construction — the provider was unusable on the desktop build (works under plain Node/OpenSSL). The PoW now hashes through a new runtime-portable helper (`open-sse/utils/sha3-512.ts`) that prefers the native digest and transparently falls back to a dependency-free pure-JS Keccak-f[1600] when native SHA-3 is absent. The fallback is validated bit-for-bit against native `createHash("sha3-512")` (300 random inputs) and the published FIPS-202 known-answer vectors. Regression guards in `tests/unit/chatgpt-web-sha3-boringssl-5531.test.ts`. ([#5531](https://github.com/diegosouzapw/OmniRoute/issues/5531)) +- **providers (chatgpt-web):** 修复在 **Electron 桌面应用**上出现的 `502 ChatGPT sentinel failed: Digest method not supported`，该错误导致所有 `chatgpt-web/*` 请求失败。哨兵工作量证明原本使用原生 `createHash("sha3-512")` 进行哈希，但 Electron 的 Node 是基于 **BoringSSL 构建的，而 BoringSSL 未实现 SHA-3 系列算法**（electron/electron#30530），因此摘要计算在构造阶段就抛出异常——该服务商在桌面版本中完全不可用（在纯 Node/OpenSSL 环境下正常工作）。PoW 现在通过一个新的运行时可移植辅助函数（`open-sse/utils/sha3-512.ts`）来计算哈希，优先使用原生摘要，当原生 SHA-3 不可用时透明回退到无依赖的纯 JS Keccak-f[1600] 实现。回退方案已针对原生 `createHash("sha3-512")`（300 个随机输入）和已发布的 FIPS-202 已知答案向量进行了逐位验证。回归测试：`tests/unit/chatgpt-web-sha3-boringssl-5531.test.ts`。([#5531](https://github.com/diegosouzapw/OmniRoute/issues/5531)) -- **providers (bytez):** fix Bytez key validation ("Provider validation endpoint not supported") and the chat base URL, verified live with a real key. Bytez **is** OpenAI-compatible at `…/models/v2/openai/v1`, but the registry stored the bare `…/models/v2` base, so the validation chat-probe hit `…/models/v2/chat/completions` → `404` → the misleading "endpoint not supported". Two parts: (1) the registry `baseUrl` now carries the full OpenAI-compat chat path (`…/models/v2/openai/v1/chat/completions`); (2) key validation no longer uses a chat probe — a Bytez account only serves models explicitly added to its catalog, so even valid keys 404 on any model id. A dedicated `validateBytezProvider` instead probes the **auth-only** `GET …/models/v2/list/tasks` endpoint (`200` ⇒ valid, `401/403` ⇒ invalid), which is independent of catalog provisioning. Regression guard: `tests/unit/bytez-validation-5422.test.ts`. ([#5422](https://github.com/diegosouzapw/OmniRoute/issues/5422)) +- **providers (bytez):** 修复 Bytez 密钥校验（"Provider validation endpoint not supported"）及聊天基础 URL，已使用真实密钥在线验证。Bytez **确实**是 OpenAI 兼容的（基础路径为 `…/models/v2/openai/v1`），但注册表中存储的是裸的 `…/models/v2` 路径，导致校验对话探测请求访问了 `…/models/v2/chat/completions` → `404` → 产生误导性的"不支持端点"错误。修复分两部分：(1) 注册表中的 `baseUrl` 现在携带完整的 OpenAI 兼容聊天路径（`…/models/v2/openai/v1/chat/completions`）；(2) 密钥校验不再使用对话探测——Bytez 账户仅提供显式添加到其目录中的模型，因此即使有效的密钥对任何模型 ID 都会返回 404。改为通过专门的 `validateBytezProvider` 探测**仅用于认证的** `GET …/models/v2/list/tasks` 端点（`200` ⇒ 有效，`401/403` ⇒ 无效），该端点独立于目录配置。回归测试：`tests/unit/bytez-validation-5422.test.ts`。([#5422](https://github.com/diegosouzapw/OmniRoute/issues/5422)) -- **dashboard (provider add):** two provider-add UX fixes. (1) #5420 — the "Import Models" button now stays hidden for **tool-only providers** (web search / web fetch), not just `*-search` ids: `firecrawl` and `jina-reader` (declared `serviceKinds: ["webFetch"]`) previously showed an Import button that hit the `400 "does not support models listing"` route. A new capability check (`providerLacksModelListing` over the resolved serviceKinds) gates the section without ever hiding an LLM/media provider. (2) #5426 — Coze key validation no longer leaks the raw upstream envelope (`{code,msg,logId,from}`) into the UI; the Coze-shaped error becomes a friendly `Coze rejected the key: (code )` message (scoped to `provider === "coze"` so no other provider is affected). Regression guards: `tests/unit/model-listing-capability-5420.test.ts`, `tests/unit/coze-validation-error-5426.test.ts`. ([#5420](https://github.com/diegosouzapw/OmniRoute/issues/5420), [#5426](https://github.com/diegosouzapw/OmniRoute/issues/5426)) +- **dashboard (provider add):** 两项添加服务商 UI 修复。(1) #5420 — "导入模型"按钮现在也对**工具专用服务商**（网页搜索 / 网页抓取）保持隐藏，而不仅仅是 `*-search` ID：`firecrawl` 和 `jina-reader`（声明了 `serviceKinds: ["webFetch"]`）之前会显示导入按钮，点击后会触发 `400 "does not support models listing"` 路由。新增能力检查（`providerLacksModelListing`，基于已解析的 serviceKinds）来控制该区域，不会隐藏 LLM/媒体服务商。(2) #5426 — Coze 密钥校验不再向 UI 泄露原始上游响应包（`{code,msg,logId,from}`）；Coze 格式的错误现在转换为友好的 `Coze rejected the key: (code )` 消息（限定在 `provider === "coze"` 范围内，不影响其他服务商）。回归测试：`tests/unit/model-listing-capability-5420.test.ts`、`tests/unit/coze-validation-error-5426.test.ts`。([#5420](https://github.com/diegosouzapw/OmniRoute/issues/5420), [#5426](https://github.com/diegosouzapw/OmniRoute/issues/5426)) -- **providers (friendliai, novita):** fix two provider registry endpoints that rejected valid keys (verified live with real keys). **FriendliAI** pointed at `…/dedicated/v1/chat/completions`, which `403 Forbidden`s a serverless `flp_*` token — switched to `…/serverless/v1/chat/completions` (+ a serverless `modelsUrl`). **Novita** pointed at the legacy `…/v3/…` base with a typo'd model id `ai-ai/llama-3.1-8b-instruct` (both `404`) — switched to the OpenAI-compatible `…/openai/v1/…` base + the valid `meta-llama/llama-3.1-8b-instruct` id. Regression guard: `tests/unit/provider-endpoints-friendliai-novita.test.ts`. ([#5430](https://github.com/diegosouzapw/OmniRoute/issues/5430), [#5455](https://github.com/diegosouzapw/OmniRoute/issues/5455)) +- **providers (friendliai, novita):** 修复两个拒绝有效密钥的服务商注册表端点（已使用真实密钥在线验证）。**FriendliAI** 指向 `…/dedicated/v1/chat/completions`，这会对无服务器 `flp_*` Token 返回 `403 Forbidden`——已切换到 `…/serverless/v1/chat/completions`（+ 无服务器 `modelsUrl`）。**Novita** 指向旧的 `…/v3/…` 基础路径，且模型 ID 存在拼写错误 `ai-ai/llama-3.1-8b-instruct`（两者均 `404`）——已切换到 OpenAI 兼容的 `…/openai/v1/…` 基础路径 + 正确的 `meta-llama/llama-3.1-8b-instruct` ID。回归测试：`tests/unit/provider-endpoints-friendliai-novita.test.ts`。([#5430](https://github.com/diegosouzapw/OmniRoute/issues/5430), [#5455](https://github.com/diegosouzapw/OmniRoute/issues/5455)) -- **providers (muse-spark):** align the Muse Spark Web (Meta AI) cookie copy with the live cookie name. The default session cookie migrated from the retired `abra_sess` to `ecto_1_sess` (`META_AI_DEFAULT_COOKIE`), but the provider form hint and one 401 auth-failure message still told users to paste `abra_sess` — a cookie that no longer exists. Both strings now name `ecto_1_sess`. Regression guard: `tests/unit/muse-spark-cookie-copy-5449.test.ts`. ([#5449](https://github.com/diegosouzapw/OmniRoute/issues/5449)) +- **providers (muse-spark):** 将 Muse Spark Web（Meta AI）Cookie 文案与实际 Cookie 名称对齐。默认会话 Cookie 已从已退役的 `abra_sess` 迁移到 `ecto_1_sess`（`META_AI_DEFAULT_COOKIE`），但服务商表单提示和一条 401 认证失败消息仍然提示用户粘贴 `abra_sess`——一个已不存在的 Cookie。两处字符串现在均使用 `ecto_1_sess`。回归测试：`tests/unit/muse-spark-cookie-copy-5449.test.ts`。([#5449](https://github.com/diegosouzapw/OmniRoute/issues/5449)) -- **dashboard (provider add):** fix three rough edges in the Add-API-Key / model-import flow reported across the provider-catalog audit. (1) The **Validation Model** and **Account ID** form fields shipped untranslated i18n stub copy (`"Validation Model Id Label"`, `"Account Id Placeholder"`, …) that surfaced verbatim in the modal — replaced with real labels/placeholders/hints in `en.json`. (2) Model import **silently fell back to the cached/local catalog**: the route already returned a `warning` ("API unavailable — using local catalog"), but `useModelImportHandlers` only read `models`/`error` and dropped it, so the user got local models with no indication — the warning is now surfaced as an import log line (new pure helper `extractImportWarning`). (3) The required connection-**name** field defaulted to `""`, which let browser autofill inject garbage (e.g. `wiw`) — it now defaults to `"main"`. Regression guard: `tests/unit/provider-add-ux-i18n-import-warning.test.ts`. ([#5421](https://github.com/diegosouzapw/OmniRoute/issues/5421), [#5428](https://github.com/diegosouzapw/OmniRoute/issues/5428), [#5429](https://github.com/diegosouzapw/OmniRoute/issues/5429), [#5431](https://github.com/diegosouzapw/OmniRoute/issues/5431), [#5435](https://github.com/diegosouzapw/OmniRoute/issues/5435)) +- **dashboard (provider add):** 修复在整个服务商目录审计中报告的三项"添加 API 密钥"/模型导入流程的粗糙之处。(1) **校验模型**和**账户 ID** 表单字段使用了未翻译的 i18n 占位文案（`"Validation Model Id Label"`、`"Account Id Placeholder"` 等），这些文案直接显示在模态框中——已替换为 `en.json` 中的真实标签/占位符/提示。(2) 模型导入**静默回退到缓存/本地目录**：路由已经返回了 `warning`（"API unavailable — using local catalog"），但 `useModelImportHandlers` 只读取 `models`/`error` 而丢弃了它，因此用户获得本地模型却没有任何提示——警告现在以导入日志行的形式呈现（新增纯辅助函数 `extractImportWarning`）。(3) 必填的连接**名称**字段默认值为 `""`，导致浏览器自动填充可能注入垃圾数据（例如 `wiw`）——现在默认为 `"main"`。回归测试：`tests/unit/provider-add-ux-i18n-import-warning.test.ts`。([#5421](https://github.com/diegosouzapw/OmniRoute/issues/5421), [#5428](https://github.com/diegosouzapw/OmniRoute/issues/5428), [#5429](https://github.com/diegosouzapw/OmniRoute/issues/5429), [#5431](https://github.com/diegosouzapw/OmniRoute/issues/5431), [#5435](https://github.com/diegosouzapw/OmniRoute/issues/5435)) -- **services (installer):** fix `spawn EINVAL` when installing an embedded service (9Router / CLIProxy) on **Windows + Node.js 24+**. Node 24 stopped letting `child_process.execFile()` run `.cmd` batch files without a shell (nodejs/node#52554), and npm on Windows is `npm.cmd`, so `runNpm()` threw `EINVAL` the moment a user clicked **Install**. `runNpm` now enables `shell` on win32 only. To keep Hard Rule #13 intact under a shell — where the shell, not `execFile`, parses argv — the install `--prefix` (a `DATA_DIR` path that can legitimately contain spaces, e.g. `C:\Users\John Doe\.omniroute\…`) is now passed via the `npm_config_prefix` **environment variable** instead of an argv path, and the user-supplied install `version` is constrained to a dist-tag/semver shape (`SERVICE_VERSION_PATTERN`) at the route boundary so it can never carry shell metacharacters. With the prefix in the environment and the version validated, every remaining argv entry is a static flag. Regression guards: `tests/unit/services/installers/runNpm-shell-5379.test.ts` (+ existing `ninerouter.test.ts` aligned to npm's `npm_config_prefix` env). ([#5379](https://github.com/diegosouzapw/OmniRoute/issues/5379)) +- **services (installer):** 修复在 **Windows + Node.js 24+** 上安装内嵌服务（9Router / CLIProxy）时出现的 `spawn EINVAL`。Node 24 不再允许 `child_process.execFile()` 在没有 Shell 的情况下运行 `.cmd` 批处理文件（nodejs/node#52554），而 Windows 上的 npm 是 `npm.cmd`，因此用户点击**安装**时 `runNpm()` 立即抛出 `EINVAL`。`runNpm` 现在仅在 win32 上启用 `shell`。为了在第 13 号硬规则下安全启用 Shell（Shell 而非 `execFile` 来解析 argv），安装 `--prefix`（`DATA_DIR` 路径，可能包含空格，例如 `C:\Users\John Doe\.omniroute\…`）现在通过 `npm_config_prefix` **环境变量**传递，代替 argv 路径参数，并且用户提供的安装 `version` 在路由边界处受限于 dist-tag/semver 格式（`SERVICE_VERSION_PATTERN`），因此永远不会携带 Shell 元字符。prefix 在环境变量中、version 经过校验，其余每个 argv 条目都是静态标志。回归测试：`tests/unit/services/installers/runNpm-shell-5379.test.ts`（+ 现有的 `ninerouter.test.ts` 已对齐到 npm 的 `npm_config_prefix` 环境变量）。([#5379](https://github.com/diegosouzapw/OmniRoute/issues/5379)) -- **cli (serve):** restore `dist/tls-options.mjs` to the npm tarball — the opt-in native HTTPS/TLS sidecar (#5361) was copied into the staged `dist/` by the build but then **pruned** by the prepublish allowlist step, so `omniroute serve` crashed on the published 3.8.41 with `ERR_MODULE_NOT_FOUND` (`dist/server-ws.mjs` imports `./tls-options.mjs`). Added `tls-options.mjs` to `APP_STAGING_ALLOWED_EXACT_PATHS` (survives the prune) and `dist/tls-options.mjs` to `PACK_ARTIFACT_REQUIRED_PATHS` (the `check:pack-artifact` gate now fails loudly if it ever vanishes again — same guard pattern as `webdav-handler.mjs`). Regression guards in `tests/unit/pack-artifact-policy.test.ts`. ([#5452](https://github.com/diegosouzapw/OmniRoute/issues/5452) — thanks @KooshaPari for the parallel fix [#5494](https://github.com/diegosouzapw/OmniRoute/pull/5494)) +- **cli (serve):** 恢复 `dist/tls-options.mjs` 到 npm 包中——可选的原生 HTTPS/TLS 边车（#5361）在构建时被复制到暂存区 `dist/` 中，但随后在预发布白名单步骤中被**裁剪移除**，导致 `omniroute serve` 在已发布的 3.8.41 版本上因 `ERR_MODULE_NOT_FOUND` 崩溃（`dist/server-ws.mjs` 导入了 `./tls-options.mjs`）。已将 `tls-options.mjs` 添加到 `APP_STAGING_ALLOWED_EXACT_PATHS`（通过裁剪检查）和 `dist/tls-options.mjs` 添加到 `PACK_ARTIFACT_REQUIRED_PATHS`（`check:pack-artifact` 门控现在如果该文件再次消失会响亮失败——与 `webdav-handler.mjs` 使用相同的防护模式）。回归测试：`tests/unit/pack-artifact-policy.test.ts`。([#5452](https://github.com/diegosouzapw/OmniRoute/issues/5452) — 感谢 @KooshaPari 的并行修复 [#5494](https://github.com/diegosouzapw/OmniRoute/pull/5494)) -- **dashboard:** fix the **Add Provider / onboarding wizard** button silently doing nothing. The `/dashboard/providers/new` route was a redirect stub (it bounced straight back to `/dashboard/providers`), so every "Add Provider" button and dashboard widget link opened nothing, and the fully-built `ProviderOnboardingWizard` component stayed orphaned (never rendered by any route). The route now renders the wizard directly; auth is enforced centrally by the `(dashboard)` layout, same as the sibling provider routes. Regression guard in `tests/unit/onboarding-wizard-route-5427.test.ts`. ([#5427](https://github.com/diegosouzapw/OmniRoute/issues/5427)) +- **dashboard:** 修复**添加服务商/引导向导**按钮点击后无反应的 bug。`/dashboard/providers/new` 路由是一个重定向桩（直接跳回 `/dashboard/providers`），因此每个"添加服务商"按钮和仪表盘小部件链接都打开了空白页，完整构建的 `ProviderOnboardingWizard` 组件被孤立（从未被任何路由渲染）。该路由现在直接渲染向导；认证由 `(dashboard)` 布局集中执行，与其他同级服务商路由相同。回归测试：`tests/unit/onboarding-wizard-route-5427.test.ts`。([#5427](https://github.com/diegosouzapw/OmniRoute/issues/5427)) -- **db (import):** fix `EBUSY: resource busy or locked` when importing a database on **Windows**. The import route deleted the live `storage.sqlite` + WAL/`-shm`/`-journal` sidecars with a plain `fs.unlinkSync` immediately after `resetDbInstance()`, but Windows releases the SQLite file handle asynchronously after `close()` (mmap / antivirus), so the unlink raced and threw `EBUSY`. The route now deletes via `unlinkFileWithRetry` (EBUSY/EPERM backoff) — the same helper the restore path already uses. Regression guard in `tests/unit/db-import-ebusy-5406.test.ts`. ([#5406](https://github.com/diegosouzapw/OmniRoute/issues/5406), consolidated under [#5161](https://github.com/diegosouzapw/OmniRoute/issues/5161)) +- **db (import):** 修复在 **Windows** 上导入数据库时出现的 `EBUSY: resource busy or locked`。导入路由在 `resetDbInstance()` 之后立即使用普通 `fs.unlinkSync` 删除活动的 `storage.sqlite` + WAL/`-shm`/`-journal` 边车文件，但 Windows 在 `close()` 之后异步释放 SQLite 文件句柄（mmap / 杀毒软件），导致 unlink 竞态并抛出 `EBUSY`。路由现在通过 `unlinkFileWithRetry`（EBUSY/EPERM 退避）来删除——与恢复路径已经使用的辅助函数相同。回归测试：`tests/unit/db-import-ebusy-5406.test.ts`。([#5406](https://github.com/diegosouzapw/OmniRoute/issues/5406)，合并至 [#5161](https://github.com/diegosouzapw/OmniRoute/issues/5161)) -- **build:** keep `ioredis` out of the client/CLI bundle — a dast-smoke regression revealed the module was being pulled into browser/Electron client-side chunks; adding it to the `SPAWN_CAPABLE_PREFIXES` leaf excludes it from client bundles while keeping it available on the server path. ([#5546](https://github.com/diegosouzapw/OmniRoute/pull/5546)) +- **build:** 将 `ioredis` 排除在客户端/CLI 打包之外——一项 dast-smoke 回归测试发现该模块被引入浏览器/Electron 客户端侧代码块；将其添加到 `SPAWN_CAPABLE_PREFIXES` 叶子节点可在服务端路径上保持可用，同时从客户端打包中排除。([#5546](https://github.com/diegosouzapw/OmniRoute/pull/5546)) -- **providers (mimocode):** route per-account traffic through SOCKS5 proxy dispatchers — each mimocode account's requests are now dispatched via its configured SOCKS5 proxy rather than the default direct connection. ([#5521](https://github.com/diegosouzapw/OmniRoute/pull/5521) — thanks @pizzav-xyz) +- **providers (mimocode):** 通过 SOCKS5 代理调度器路由每个账户的流量——每个 mimocode 账户的请求现在通过其配置的 SOCKS5 代理而非默认直连来发送。([#5521](https://github.com/diegosouzapw/OmniRoute/pull/5521) — 感谢 @pizzav-xyz) -- **providers:** persist the **Configured** provider filter selection across page reloads — the filter was resetting to "All" on every navigation. ([#5510](https://github.com/diegosouzapw/OmniRoute/pull/5510) — thanks @KooshaPari) +- **providers:** 在页面刷新时持久化**已配置**服务商过滤器选项——之前的过滤器在每次导航时都会重置为"All"。([#5510](https://github.com/diegosouzapw/OmniRoute/pull/5510) — 感谢 @KooshaPari) -- **providers (chatgpt-web):** support **GPT-5.5 Pro** model handoff — adds the model mapping and handoff routing needed for the GPT-5.5 Pro tier. ([#5536](https://github.com/diegosouzapw/OmniRoute/pull/5536) — thanks @Thinkscape) +- **providers (chatgpt-web):** 支持 **GPT-5.5 Pro** 模型交接——增加了 GPT-5.5 Pro 层级所需的模型映射和交接路由。([#5536](https://github.com/diegosouzapw/OmniRoute/pull/5536) — 感谢 @Thinkscape) -- **dashboard:** keep onboarding schemas browser-safe — the schema module imported a server-side `db` reference that crashed the browser bundle; it is now imported only on the server path. ([#5525](https://github.com/diegosouzapw/OmniRoute/pull/5525) — thanks @KooshaPari) +- **dashboard:** 保持引导 Schema 的浏览器安全性——Schema 模块导入了服务端的 `db` 引用，导致浏览器打包崩溃；现在仅在服务端路径上导入。([#5525](https://github.com/diegosouzapw/OmniRoute/pull/5525) — 感谢 @KooshaPari) -- **routing (bifrost):** add auto-fallback cooldown for bifrost targets — prevents rapid re-selection of a failing bifrost backend within the cooldown window, complementing the existing circuit-breaker mechanism. ([#5519](https://github.com/diegosouzapw/OmniRoute/pull/5519) — thanks @KooshaPari) +- **routing (bifrost):** 为 bifrost 目标添加自动容灾冷却期——在冷却窗口内防止快速重新选择失败的 bifrost 后端，与现有的熔断器机制互补。([#5519](https://github.com/diegosouzapw/OmniRoute/pull/5519) — 感谢 @KooshaPari) -- **providers (opencode-plugin):** bump the opencode plugin to **v0.2.0** and wire auto-publish on release so the plugin package tracks OmniRoute releases automatically. ([#5363](https://github.com/diegosouzapw/OmniRoute/pull/5363) — thanks @herjarsa) +- **providers (opencode-plugin):** 将 opencode 插件升级到 **v0.2.0** 并在发布时接入自动发布功能，使插件包自动跟踪 OmniRoute 发布节奏。([#5363](https://github.com/diegosouzapw/OmniRoute/pull/5363) — 感谢 @herjarsa) -- **rate-limit:** normalize queue refresh settings — aligns the queue-refresh interval configuration across rate-limit strategies so stale queues are released on a consistent schedule. ([#5499](https://github.com/diegosouzapw/OmniRoute/pull/5499) — thanks @KooshaPari) +- **rate-limit:** 规范化队列刷新设置——在各速率限制策略间对齐队列刷新间隔配置，使过期队列按一致的节奏释放。([#5499](https://github.com/diegosouzapw/OmniRoute/pull/5499) — 感谢 @KooshaPari) -- **fallback:** normalize provider error-rule header extraction — ensures fallback retry decisions correctly read all response headers regardless of casing, fixing cases where a provider's `Retry-After` or custom error header was silently dropped. ([#5473](https://github.com/diegosouzapw/OmniRoute/pull/5473) — thanks @KooshaPari) +- **fallback:** 规范化服务商错误规则头提取——确保容灾重试决策能正确读取所有响应头（不区分大小写），修复服务商的 `Retry-After` 或自定义错误头被静默丢弃的问题。([#5473](https://github.com/diegosouzapw/OmniRoute/pull/5473) — 感谢 @KooshaPari) -- **routing:** gate Claude adaptive-thinking defaults behind the feature flag — prevents the thinking budget from being injected into requests for models that do not support the extended-thinking parameter, avoiding upstream `400` errors on non-thinking Claude variants. ([#5480](https://github.com/diegosouzapw/OmniRoute/pull/5480) — thanks @KooshaPari) +- **routing:** 将 Claude 自适应思考默认值放在功能标志之后——防止思考预算被注入到不支持扩展思考参数的模型请求中，避免对非思考型 Claude 变体产生上游 `400` 错误。([#5480](https://github.com/diegosouzapw/OmniRoute/pull/5480) — 感谢 @KooshaPari) -- **ci:** fix post-merge CI regressions introduced by the dead-code sweep — restores test imports and type references broken when the ratchet landed before downstream consumers were updated. ([#5467](https://github.com/diegosouzapw/OmniRoute/pull/5467) — thanks @KooshaPari) +- **ci:** 修复由死代码清理引入的合并后 CI 回归——恢复了在 ratchet 先于下游消费者登陆时损坏的测试导入和类型引用。([#5467](https://github.com/diegosouzapw/OmniRoute/pull/5467) — 感谢 @KooshaPari) -- **sse:** treat terminal stream cancels as complete — an aborted SSE stream was being left in a partial state, causing downstream consumers to wait indefinitely for a final event that would never arrive. ([#5491](https://github.com/diegosouzapw/OmniRoute/pull/5491) — thanks @JxnLexn) +- **sse:** 将终端流取消视为完成——被中止的 SSE 流会被留在部分状态，导致下游消费者无限等待一个永远不会到达的最终事件。([#5491](https://github.com/diegosouzapw/OmniRoute/pull/5491) — 感谢 @JxnLexn) -- **api:** fix framing of non-streaming JSON responses — `stream: false` chat-completions responses were returned without correct content-length framing, causing some clients to misparse the response body. ([#5416](https://github.com/diegosouzapw/OmniRoute/pull/5416) — thanks @rdself) +- **api:** 修复非流式 JSON 响应的帧封装——`stream: false` 的聊天补全响应返回时缺少正确的 content-length 帧封装，导致某些客户端错误解析响应体。([#5416](https://github.com/diegosouzapw/OmniRoute/pull/5416) — 感谢 @rdself) -- **dashboard (tests):** protect dynamic dashboard endpoint tests with CSRF validation — the test suite was exercising dashboard API routes without CSRF tokens, masking a coverage gap for those endpoints. ([#5405](https://github.com/diegosouzapw/OmniRoute/pull/5405) — thanks @rdself) +- **dashboard (tests):** 使用 CSRF 校验保护动态仪表盘端点测试——测试套件在没有 CSRF Token 的情况下测试仪表盘 API 路由，掩盖了这些端点的覆盖率缺口。([#5405](https://github.com/diegosouzapw/OmniRoute/pull/5405) — 感谢 @rdself) -- **providers:** remove the dead **Phind** provider (service shut down) and deduplicate the **HuggingChat** catalog listing that had accumulated a stale duplicate entry. ([#5530](https://github.com/diegosouzapw/OmniRoute/pull/5530) — thanks @backryun) +- **providers:** 移除已关闭的 **Phind** 服务商（服务已停止运营），并清理 **HuggingChat** 目录列表中累积的过期重复条目。([#5530](https://github.com/diegosouzapw/OmniRoute/pull/5530) — 感谢 @backryun) -- **providers (longcat):** correct the LongCat free tier — **LongCat-2.0** is now GA; the one-time 10M-token promo (KYC required) is correctly reflected in the catalog, replacing the stale legacy beta entry. ([#5508](https://github.com/diegosouzapw/OmniRoute/pull/5508) — thanks @backryun) +- **providers (longcat):** 更正 LongCat 免费层——**LongCat-2.0** 现已正式发布；一次性 1000 万 Token 推广活动（需 KYC）已在目录中正确反映，替换了过时的旧版测试条目。([#5508](https://github.com/diegosouzapw/OmniRoute/pull/5508) — 感谢 @backryun) -### 📝 Maintenance +### 📝 维护 -- **dashboard (refactor):** consolidate the duplicate caveman on/off toggle from the compression settings tab onto the single-source panel (T11), eliminating the stale off-sync copy. ([#5524](https://github.com/diegosouzapw/OmniRoute/pull/5524)) +- **dashboard (refactor):** 将压缩设置标签页中重复的 caveman 开关整合到单一来源面板 (T11)，消除过时的不同步副本。([#5524](https://github.com/diegosouzapw/OmniRoute/pull/5524)) -- **tests:** add quota guard for Claude-Code identity version lockstep (Phase 2) — asserts that the Claude-Code version reported in quota accounting stays in sync with the deployed version, preventing silent drift. ([#5514](https://github.com/diegosouzapw/OmniRoute/pull/5514)) +- **tests:** 添加 Claude-Code 身份版本同步的配额守护（第二阶段）——断言配额记账中报告的 Claude-Code 版本与已部署版本保持同步，防止静默漂移。([#5514](https://github.com/diegosouzapw/OmniRoute/pull/5514)) -- **docs:** add relay backend strategy guide documenting supported relay backend types, selection criteria, and configuration patterns. ([#5547](https://github.com/diegosouzapw/OmniRoute/pull/5547)) +- **docs:** 添加中继后端策略指南，文档化支持的中继后端类型、选择标准和配置模式。([#5547](https://github.com/diegosouzapw/OmniRoute/pull/5547)) -- **docs:** clarify bifrost relay backend environment variables — documents which env vars control bifrost's relay backend selection and failover behavior. ([#5520](https://github.com/diegosouzapw/OmniRoute/pull/5520) — thanks @KooshaPari) +- **docs:** 说明 bifrost 中继后端环境变量——文档化哪些环境变量控制 bifrost 的中继后端选择和容灾行为。([#5520](https://github.com/diegosouzapw/OmniRoute/pull/5520) — 感谢 @KooshaPari) -- **tests:** add relay routing fallback header behavior tests — regression guard asserting that fallback-triggered relay requests carry the correct forwarded headers through the routing layer. ([#5526](https://github.com/diegosouzapw/OmniRoute/pull/5526) — thanks @KooshaPari) +- **tests:** 添加中继路由容灾头行为测试——回归防护，断言容灾触发的中继请求通过路由层携带正确的转发头。([#5526](https://github.com/diegosouzapw/OmniRoute/pull/5526) — 感谢 @KooshaPari) -- **ci:** add npm `fetch-retry` configuration and codify the release-freeze protocol (Hard Rule #21) — reduces transient npm registry fetch failures in CI and establishes the documented procedure for freezing releases. ([#5506](https://github.com/diegosouzapw/OmniRoute/pull/5506)) +- **ci:** 添加 npm `fetch-retry` 配置并规范化发布冻结协议（第 21 号硬规则）——减少 CI 中瞬态的 npm 注册表拉取失败，并建立文档化的发布冻结流程。([#5506](https://github.com/diegosouzapw/OmniRoute/pull/5506)) -- **deps:** bump 11 production dependencies to their latest compatible versions. ([#5414](https://github.com/diegosouzapw/OmniRoute/pull/5414)) +- **deps:** 将 11 个生产依赖升级到最新兼容版本。([#5414](https://github.com/diegosouzapw/OmniRoute/pull/5414)) -- **deps:** bump Electron from 42.4.1 to 42.5.1 in `/electron`. ([#5413](https://github.com/diegosouzapw/OmniRoute/pull/5413)) +- **deps:** 将 `/electron` 中的 Electron 从 42.4.1 升级到 42.5.1。([#5413](https://github.com/diegosouzapw/OmniRoute/pull/5413)) -- **deps:** bump the development dependency group with 9 updates. ([#5415](https://github.com/diegosouzapw/OmniRoute/pull/5415)) +- **deps:** 将开发依赖组升级，共 9 项更新。([#5415](https://github.com/diegosouzapw/OmniRoute/pull/5415)) - **maintenance (dead-code):** repo-wide sweep of unused exported symbols, types, and schemas — removes 35 no-longer-referenced exports across cloud-agent, a2a, SSE, memory, quota, skills, gamification, codex, qdrant, playground, provider catalog, and combo modules, reducing the exported API surface and eliminating stale misleading types. ([#5372](https://github.com/diegosouzapw/OmniRoute/pull/5372), [#5373](https://github.com/diegosouzapw/OmniRoute/pull/5373), [#5374](https://github.com/diegosouzapw/OmniRoute/pull/5374), [#5375](https://github.com/diegosouzapw/OmniRoute/pull/5375), [#5376](https://github.com/diegosouzapw/OmniRoute/pull/5376), [#5377](https://github.com/diegosouzapw/OmniRoute/pull/5377), [#5378](https://github.com/diegosouzapw/OmniRoute/pull/5378), [#5380](https://github.com/diegosouzapw/OmniRoute/pull/5380), [#5381](https://github.com/diegosouzapw/OmniRoute/pull/5381), [#5382](https://github.com/diegosouzapw/OmniRoute/pull/5382), [#5383](https://github.com/diegosouzapw/OmniRoute/pull/5383), [#5384](https://github.com/diegosouzapw/OmniRoute/pull/5384), [#5385](https://github.com/diegosouzapw/OmniRoute/pull/5385), [#5386](https://github.com/diegosouzapw/OmniRoute/pull/5386), [#5387](https://github.com/diegosouzapw/OmniRoute/pull/5387), [#5388](https://github.com/diegosouzapw/OmniRoute/pull/5388), [#5389](https://github.com/diegosouzapw/OmniRoute/pull/5389), [#5390](https://github.com/diegosouzapw/OmniRoute/pull/5390), [#5391](https://github.com/diegosouzapw/OmniRoute/pull/5391), [#5392](https://github.com/diegosouzapw/OmniRoute/pull/5392), [#5393](https://github.com/diegosouzapw/OmniRoute/pull/5393), [#5395](https://github.com/diegosouzapw/OmniRoute/pull/5395), [#5396](https://github.com/diegosouzapw/OmniRoute/pull/5396), [#5397](https://github.com/diegosouzapw/OmniRoute/pull/5397), [#5398](https://github.com/diegosouzapw/OmniRoute/pull/5398), [#5399](https://github.com/diegosouzapw/OmniRoute/pull/5399), [#5400](https://github.com/diegosouzapw/OmniRoute/pull/5400), [#5401](https://github.com/diegosouzapw/OmniRoute/pull/5401), [#5402](https://github.com/diegosouzapw/OmniRoute/pull/5402), [#5403](https://github.com/diegosouzapw/OmniRoute/pull/5403), [#5404](https://github.com/diegosouzapw/OmniRoute/pull/5404), [#5463](https://github.com/diegosouzapw/OmniRoute/pull/5463), [#5464](https://github.com/diegosouzapw/OmniRoute/pull/5464), [#5466](https://github.com/diegosouzapw/OmniRoute/pull/5466), [#5468](https://github.com/diegosouzapw/OmniRoute/pull/5468) — thanks @JxnLexn) @@ -100,31 +100,31 @@ ## [3.8.41] — 2026-06-29 -### ✨ New Features +### ✨ 新功能 -- **feat(relay): selectable relay backend (TS / Bifrost / `auto`)** — the OpenAI-compatible relay endpoint can now route its hot path through a native Bifrost sidecar without clients changing URLs. `OMNIROUTE_RELAY_BACKEND` / `RELAY_ROUTING_BACKEND` = `ts | bifrost | auto`: defaults to the existing TypeScript relay; `auto` selects Bifrost when `BIFROST_BASE_URL` is set (and `BIFROST_ENABLED` ≠ `0`) and falls back to TS automatically if the sidecar is unreachable; `bifrost` keeps strict failure behavior. Auth, per-IP/token rate limits, prompt-injection checks, and model allowlists still run in the Next relay route before dispatch (control plane stays in the app); responses carry `X-Routing-Backend` / `X-Routing-Fallback`. Regression guards: `tests/unit/api/v1/relay-routing-backend.test.ts`, `tests/unit/api/v1/bifrost-sidecar.test.ts`. ([#5315](https://github.com/diegosouzapw/OmniRoute/pull/5315), #5316 — thanks @KooshaPari) +- **feat(relay): 可选择的中继后端（TS / Bifrost / `auto`）** — OpenAI 兼容的中继端点现在可以通过原生 Bifrost 边车路由其热路径，客户端无需更改 URL。`OMNIROUTE_RELAY_BACKEND` / `RELAY_ROUTING_BACKEND` = `ts | bifrost | auto`：默认使用现有的 TypeScript 中继；`auto` 在 `BIFROST_BASE_URL` 已设置（且 `BIFROST_ENABLED` ≠ `0`）时选择 Bifrost，并在边车不可达时自动回退到 TS；`bifrost` 保持严格的失败行为。认证、每 IP/Token 速率限制、提示注入检查和模型白名单仍在 Next 中继路由中于调度前运行（控制平面保留在应用内）；响应携带 `X-Routing-Backend` / `X-Routing-Fallback`。回归测试：`tests/unit/api/v1/relay-routing-backend.test.ts`、`tests/unit/api/v1/bifrost-sidecar.test.ts`。([#5315](https://github.com/diegosouzapw/OmniRoute/pull/5315), #5316 — 感谢 @KooshaPari) -### 🔧 Bug Fixes +### 🔧 问题修复 -- **translator (claude):** synthesize a minimal `user` turn when an OpenAI→Claude request carries **only** `system`/`developer` messages, so the request stops failing with `[400]: messages: at least one message is required`. `openaiToClaudeRequest` hoists every system/developer turn into Claude's top-level `system` field and filters them out of `messages`; an all-system input (OpenCode compaction / title-generation requests) left `messages: []`, which the Messages API rejects — surfacing in OpenCode as a mid-task `stream error` that drops the conversation. The guard fires only when `messages` would otherwise be empty (system instructions still drive the response), so non-empty requests are unaffected. ([#5342](https://github.com/diegosouzapw/OmniRoute/pull/5342) — thanks @wild-feather) -- **providers (gemini):** drop retired Google AI Studio model ids and align the catalog to what the live GenAI API actually serves (verified 2026-06-29 against the official deprecations page). Removes long-retired `gemini-1.5-pro`/`gemini-1.5-flash`, the shut-down `gemini-2.0-flash`/`gemini-2.0-flash-lite`, and dead experimentals; renames `gemini-3.1-flash-lite-preview` → the GA `gemini-3.1-flash-lite`; swaps the retired `text-embedding-004` for the live `gemini-embedding-001`/`gemini-embedding-2`; and adds graceful `modelDeprecation` forwards so legacy/renamed ids redirect to the GA model instead of 404ing. Native AI-Studio-direct image/video/music registration is intentionally out of scope (needs real executor work; those models stay reachable via Antigravity/Vertex/aggregators). ([#5337](https://github.com/diegosouzapw/OmniRoute/pull/5337) — thanks @backryun) -- **services (dashboard):** fix the embedded-services dashboard failures (#5298) — service supervisors are now lazily initialized from `/api/services/[name]/logs` so `cliproxy`/`9router` logs no longer 404 before bootstrap registers a supervisor; lifecycle buttons send JSON (empty install bodies default to `version: "latest"`, malformed JSON still returns `400 Invalid JSON body`); lifecycle and log-stream failures surface as actionable UI errors instead of silently showing no logs; Tailscale CGNAT `100.64.0.0/10` peers count as private-LAN local for local-only service access; a parent `/dashboard/context` → `/dashboard/context/settings` redirect stops RSC prefetch 404s; and `/api/v1/providers/{cliproxyapi,9router}/models` return synced embedded-service models instead of `invalid_provider`. ([#5299](https://github.com/diegosouzapw/OmniRoute/pull/5299), #5298 — thanks @KooshaPari) -- **thinking (claude):** fix three independent defects in Claude adaptive-thinking on the OpenAI-compatible path (Cursor → Claude OAuth). **(A)** the dashboard Thinking-Budget setting was dropped on every restart — `setThinkingBudgetConfig` was never called at boot, so a saved `{mode:"adaptive"…}` silently reverted to passthrough; it's now hydrated from settings in `server-init`. **(B)** the Claude executor force-injected adaptive thinking _after_ translation, ignoring the operator's budget — it now honors `mode:"auto"` (strip) while keeping the default (passthrough) behavior byte-identical so native Claude Code is unaffected, and remaps an operator `thinking.type:"enabled"` to the `adaptive` shape Opus 4.7/4.8 require (`enabled` → 400). **(D)** on replay, signature-less `reasoning_content` was reconstructed as a `thinking` block carrying a fabricated signature → Anthropic `400 "Invalid signature in thinking block"`; it now emits a signature-less `redacted_thinking` block (real signatures are still preserved verbatim). Regression guards: `tests/unit/thinking-budget-hydration-5312.test.ts`, `base-thinking-budget-config-5312.test.ts`, `openai-to-claude-redacted-replay-5312.test.ts` (existing #5123/#4479/#2454 suites stay green). The `` content-marker channel mismatch (RC-C, shared with #5245) is tracked as a follow-up pending a live Anthropic validation. ([#5312](https://github.com/diegosouzapw/OmniRoute/issues/5312) — thanks @vitalNohj) -- **opencode (proxy pool):** the OpenCode Free per-account proxy modal now offers the global **Proxy Pool dropdown** (by-id reference) instead of forcing manual Host/Port/credentials on every account — Gap 1 of #5217. A **Saved / Custom** toggle: "Saved" picks a pre-saved proxy from `GET /api/settings/proxies` and stores `{fingerprint, proxyId}`, so updating that pool proxy applies to every account using it; "Custom" keeps the manual inputs (stored inline) as an escape hatch. Resolution happens server-side (`resolveAccountProxiesFromRegistry`) so the executor still receives a resolved proxy unchanged; existing inline entries keep working and an unknown/deleted `proxyId` degrades safely to direct. Regression guards: `tests/unit/noauth-proxy-resolution.test.ts`, `tests/unit/ui/noauth-account-card.test.tsx`. ([#5217](https://github.com/diegosouzapw/OmniRoute/issues/5217) Gap 1 — thanks @daniij) -- **thinking (claude):** let reasoning_content-native clients (e.g. Cursor) opt out of the `` close-marker so it no longer leaks an orphan `` into visible `content` (RC-C of #5312, shared with #5245). The marker-suppression machinery already existed (UA allowlist, #5348) but Cursor's UA was deliberately excluded; this adds an explicit request header `x-omniroute-thinking-marker: off` (also `on`/`keep` to force-keep) that overrides the UA policy. With the header absent the behavior is byte-identical — Claude Code/Cursor-composer clients that scan `content` for the marker (#4633) still receive it. Regression guard: `tests/unit/think-close-marker-suppress-5245.test.ts` (#5123 case-b + #4479 stay green). ([#5312](https://github.com/diegosouzapw/OmniRoute/issues/5312), [#5245](https://github.com/diegosouzapw/OmniRoute/issues/5245) — thanks @vitalNohj, @wild-feather) -- **cors:** browser/Electron clients (e.g. Wayland AI) can now use OmniRoute as an OpenAI-compatible provider out-of-the-box. The token-authenticated API surface (`/v1/*`, `/v1beta/*`) now returns a permissive `Access-Control-Allow-Origin` (echoes the request `Origin`, `*` when absent) by default — matching 9router and the OpenAI-compatible ecosystem — so a renderer `fetch` can read the response instead of failing CORS-blocked as "site not found" / empty catalog (while `curl`, which sends no preflight, worked). This is **safe**: those routes auth via `Authorization`/`x-api-key` headers browsers never auto-attach (no credentialed-session/CSRF exposure), and `Access-Control-Allow-Credentials` is never paired with the echo/wildcard. Cookie-authed **MANAGEMENT/dashboard routes stay exactly fail-closed**; `CORS_ALLOW_ALL`/`CORS_ALLOWED_ORIGINS` still take precedence. Regression guards: `tests/unit/cors/origins.test.ts`, `tests/unit/authz/pipeline.test.ts`. (Bug 2 of [#5242](https://github.com/diegosouzapw/OmniRoute/issues/5242) — thanks @jonlwheat2-gif) -- **grok-web:** forward the Cloudflare clearance cookies and stop mislabeling IP-reputation blocks as a bad cookie. "Check cookie" returned `Invalid SSO cookie` even with a valid, complete browser session — but the cookie parser was never the problem (it robustly extracts `sso`/`sso-rw` from a full DevTools header). Two real gaps fixed: **(1)** `buildGrokCookieHeader` now forwards `cf_clearance` and `__cf_bm` when pasted (it dropped them before; AIClient2API forwards them too) — strictly additive, a bare `sso` blob still yields exactly `sso=…`; **(2)** when the user supplied a `cf_clearance`, a 401 / invalid-credentials-403 from grok.com is now surfaced as an IP-reputation/anti-bot block (cf_clearance is IP+TLS+UA-pinned and can't be replayed from a different machine) instead of the misleading "Invalid SSO cookie — re-paste". A bare cookie with no clearance still gets the re-paste hint. Regression guards in `web-cookie-auth.test.ts` + `provider-validation-specialty.test.ts`. ([#5350](https://github.com/diegosouzapw/OmniRoute/issues/5350) — thanks @SeaXen) -- **cli (serve):** opt-in native **HTTPS/TLS** for `omniroute serve` — so strict-CSP Electron apps and browsers can reach OmniRoute over `https://` instead of plain `http://localhost`. Provide `--tls-cert --tls-key ` (or `OMNIROUTE_TLS_CERT`/`OMNIROUTE_TLS_KEY`) and the standalone server terminates TLS on the same listener (no extra port/proxy); WebSocket upgrade (live dashboard + `/v1` streaming) works over `wss://` unchanged since `https.Server extends http.Server`. With no TLS flags the HTTP path is byte-identical to before; only one of cert/key, or an unreadable path, logs a warning and stays HTTP (never half-enables, never crashes). Auto-generated self-signed certs for localhost are a follow-up; for now provide an explicit cert/key (or front OmniRoute with a TLS terminator). Regression guard: `tests/unit/tls-options.test.ts`. (Bug 1C of [#5242](https://github.com/diegosouzapw/OmniRoute/issues/5242) — thanks @jonlwheat2-gif) -- **opencode/observability:** make OpenCode Free account/proxy rotation visible and fix two real defects surfaced alongside it. **(1)** the per-request rotation selection log (`dispatch via account … through proxy …`) was `debug` (hidden at default `APP_LOG_LEVEL=info`) — promoted to `info` so the shuffle/cooldown lifecycle is auditable (token stays masked). **(2)** `[ProxyEgress]` reported `proxy=direct` even when an account proxy was applied, because the egress logger ran outside the executor's nested proxy context — the effective applied proxy is now captured (via an applied-proxy sink threaded through the proxy AsyncLocalStorage) and reflected in the egress log. **(3)** `[callLogs] too many SQL variables` — `deleteCallLogRowsByIds` deleted up to 5000 ids in one `IN (…)`, exceeding SQLite's ~999 bound-param cap and aborting log trimming/retention; ids are now chunked (≤500 per statement). Regression guards: `tests/unit/call-log-trim-sql-vars-5217.test.ts`, `apply-executor-proxy-info-5217.test.ts`, extended `opencode-proxy-rotation-4954.test.ts`. The Proxy Pool dropdown (by-id) UI (Gap 1) is a follow-up requiring browser validation. ([#5217](https://github.com/diegosouzapw/OmniRoute/issues/5217) — thanks @daniij) -- **chatgpt-web:** wire tool/function calling into the `chatgpt-web` provider. It was the only web-session executor that never read `body.tools` — both response builders hardcoded `finish_reason:"stop"` and emitted only content, so tool calls were silently dropped (the model answered in prose). It now uses the shared `webTools` prompt-emulation shim (a ``-contract system message + `{…}` response parsing) exactly like its 9 sibling executors (qwen-web, perplexity-web, …) — it was simply omitted from the #3259 rollout. Tool mode buffers and emits `tool_calls` + `finish_reason:"tool_calls"` (gated off the image-gen path); plain chat is unchanged. Regression guard: `tests/unit/chatgpt-web-tools-5240.test.ts`. ([#5240](https://github.com/diegosouzapw/OmniRoute/issues/5240) — thanks @Rougler) -- **oauth/dashboard:** fix the persistent/false Antigravity "Token Expired" badge (continuation of #3679/#3850). Two causes: **(1)** new OAuth connections never set `tokenExpiresAt` (only `expiresAt`), so the dashboard badge — which prefers `tokenExpiresAt || expiresAt` — fell back to the original grant clock and could flash a false "Token Expired" until the first background refresh. Creation now mirrors `expiresAt` into `tokenExpiresAt` across all 5 OAuth create paths (a shared `buildOAuthConnectionCreatePayload`), consistent with every refresh path which already writes both. **(2)** when a refresh-capable connection has no usable refresh token, the health-check sweep silently skipped it, leaving `testStatus="active"` forever while the cosmetic badge showed expired; it now surfaces a terminal `testStatus="expired"` ("needs re-auth"), tightly gated so it never clobbers non-refresh providers or already-terminal/cooldown states. Regression guards: `tests/unit/oauth-connection-tokenexpiresat-5326.test.ts`, `tests/unit/token-health-no-refresh-token-expired-5326.test.ts`. ([#5326](https://github.com/diegosouzapw/OmniRoute/issues/5326)) -- **routing:** auto-disable a depleted API key on upstream `402 "Insufficient account balance"` for API Key Round-Robin connections (multiple keys in one connection's `extraApiKeys`). The per-connection path already terminalized 402 (→ `credits_exhausted`), but the per-KEY health tracker (`recordKeyHealthStatus`) only recorded failures for `401`, so a 402-depleted key stayed in rotation and kept getting retried. Now a 402 marks the current key invalid immediately (terminal — balance won't recover mid-session) via a new `recordKeyTerminal`, so the rotator skips it and falls over to the next healthy key; the state persists across restarts. Also added `insufficient balance`/`insufficient_balance`/`insufficient account balance` to the credits-exhausted body signals so non-402 out-of-credit responses terminalize too. Regression guard: `tests/unit/key-health-402-disable-5239.test.ts`. ([#5239](https://github.com/diegosouzapw/OmniRoute/issues/5239) — thanks @muflifadla38) -- **cli:** `omniroute serve` no longer discards a user-set `NODE_OPTIONS=--max-old-space-size=…`. It used to unconditionally overwrite `NODE_OPTIONS` (and pass an explicit `--max-old-space-size` CLI arg) with the calibrated default, so a user who exported `--max-old-space-size=8192` still ran at the old cap and OOM'd (#5238 reporter set 8192, crashed at ~505MB). Now it mirrors the Electron and standalone launchers: if `NODE_OPTIONS` already pins the heap, that value wins (and the duplicate CLI arg is suppressed); otherwise the calibrated `--max-old-space-size` is appended, preserving unrelated flags. Regression guard: `tests/unit/serve-node-options-preserve-5238.test.ts`. (Defect C of [#5238](https://github.com/diegosouzapw/OmniRoute/issues/5238); the `b.mask`/OOM-root parts are tracked separately.) -- **dashboard:** restore the `{active}/{total} active` model-count badge in a provider's **Available Models** toolbar (provider detail page). It was dropped during the v3.8.13 god-file decomposition (#3327) — the `ModelVisibilityToolbar` still received `activeCount`/`totalCount` but they were orphaned as unused `_`-prefixed params and the rendering `` was never carried over (the `modelsActiveCount` i18n key stayed). Re-wired the existing props to the existing key; zero data-layer or i18n change. Regression guard: `modelVisibilityToolbarActiveCount.test.tsx`. ([#5264](https://github.com/diegosouzapw/OmniRoute/issues/5264)) -- **rerank:** `/v1/rerank` no longer rejects SiliconFlow and DeepInfra Qwen3-Reranker models with `400 "Invalid rerank model"` even though `/v1/models` lists them. The model-ID parser was never the problem (it already splits on the first slash, so `siliconflow/Qwen/Qwen3-Reranker-8B` parses correctly) — `siliconflow` and `deepinfra` were just missing from the rerank provider registry. Added both: SiliconFlow as Cohere-compatible, DeepInfra via a new `deepinfra` adapter (model in the URL path `POST /v1/inference/`, `{queries,documents}` request, positional `{scores}` response mapped to Cohere `results[]`). Regression guard: `tests/unit/rerank-providers-5332.test.ts`. ([#5332](https://github.com/diegosouzapw/OmniRoute/issues/5332) — thanks @maikokan) -- **authz/dashboard:** stop rejecting every dashboard mutation with `403 INVALID_ORIGIN` when the dashboard is reached over a LAN IP / non-localhost host. The origin-pinning check (#5278) only accepted the configured `*_PUBLIC_BASE_URL` (typically `http://localhost:20128`) plus the internal `request.url` origin — which Next.js standalone reports as the bind host, not the real `Host`. So opening the dashboard at e.g. `http://192.168.0.15:20128` made the browser's same-origin `Origin` match no candidate, and **every** POST/PUT/DELETE (save API key, save provider, test connection) failed while GETs still worked. Two fixes: **(a)** the request `Host` (or a trusted `X-Forwarded-Host`) is now accepted as a valid mutation origin, gated by two independent checks — the token-stamped socket peer must be loopback/private-LAN **and** the Host itself must be a loopback/private-LAN IP literal, so a DNS-rebinding domain (which classifies as `remote`) can never become a trusted origin and the protocol is pinned to the actual connection; **(b)** the `INVALID_ORIGIN` response now carries an actionable message (set `OMNIROUTE_PUBLIC_BASE_URL`) and the dashboard surfaces API error `.message` via a shared `extractApiErrorMessage` helper instead of rendering the raw error object. Regression guards: `tests/unit/authz/public-origin.test.ts` (direct LAN/loopback + DNS-rebinding defense), `tests/unit/api-error-message-5340.test.ts`. ([#5340](https://github.com/diegosouzapw/OmniRoute/issues/5340)) +- **translator (claude):** 当 OpenAI→Claude 请求**仅**包含 `system`/`developer` 消息时，合成一个最小化的 `user` 轮次，使请求不再因 `[400]: messages: at least one message is required` 而失败。`openaiToClaudeRequest` 将所有 system/developer 轮次提升到 Claude 的顶层 `system` 字段并从 `messages` 中过滤掉；纯 system 输入（OpenCode 压缩/标题生成请求）会导致 `messages: []`，Messages API 会拒绝——在 OpenCode 中表现为丢失对话的任务中途 `stream error`。该防护仅在 `messages` 原本为空时触发（system 指令仍然驱动响应），因此非空请求不受影响。([#5342](https://github.com/diegosouzapw/OmniRoute/pull/5342) — 感谢 @wild-feather) +- **providers (gemini):** 移除已退役的 Google AI Studio 模型 ID，并使目录与实际运行的 GenAI API 对齐（2026-06-29 根据官方弃用页面验证）。移除长期退役的 `gemini-1.5-pro`/`gemini-1.5-flash`、已关闭的 `gemini-2.0-flash`/`gemini-2.0-flash-lite` 和无效实验版；将 `gemini-3.1-flash-lite-preview` 重命名为 GA 版 `gemini-3.1-flash-lite`；将退役的 `text-embedding-004` 替换为实际运行中的 `gemini-embedding-001`/`gemini-embedding-2`；并添加优雅的 `modelDeprecation` 转发，使旧版/重命名的 ID 重定向到 GA 模型而非 404。原生 AI-Studio 直连的图像/视频/音乐注册有意不在本次范围内（需要实际的执行器工作；这些模型仍可通过 Antigravity/Vertex/聚合器访问）。([#5337](https://github.com/diegosouzapw/OmniRoute/pull/5337) — 感谢 @backryun) +- **services (dashboard):** 修复内嵌服务仪表盘故障 (#5298) — 服务监控器现在从 `/api/services/[name]/logs` 延迟初始化，因此 `cliproxy`/`9router` 日志在引导注册监控器之前不再 404；生命周期按钮发送 JSON（空安装体默认 `version: "latest"`，格式错误的 JSON 仍返回 `400 Invalid JSON body`）；生命周期和日志流故障现在以可操作的 UI 错误呈现，而非静默显示无日志；Tailscale CGNAT `100.64.0.0/10` 对等节点被视为私有 LAN 本地网络，用于仅限本地的服务访问；父路由 `/dashboard/context` → `/dashboard/context/settings` 重定向停止 RSC 预取 404；`/api/v1/providers/{cliproxyapi,9router}/models` 返回同步的内嵌服务模型而非 `invalid_provider`。([#5299](https://github.com/diegosouzapw/OmniRoute/pull/5299), #5298 — 感谢 @KooshaPari) +- **thinking (claude):** 修复 OpenAI 兼容路径（Cursor → Claude OAuth）上 Claude 自适应思考的三个独立缺陷。**(A)** 仪表盘思考预算设置在每次重启时被丢弃——`setThinkingBudgetConfig` 从未在启动时调用，因此保存的 `{mode:"adaptive"…}` 静默回退到透传模式；现在在 `server-init` 中从设置中恢复。**(B)** Claude 执行器在翻译_之后_强制注入自适应思考，忽略了运维人员的预算——现在遵循 `mode:"auto"`（剥离），同时保持默认（透传）行为逐字节不变，因此原生 Claude Code 不受影响，并将运维人员的 `thinking.type:"enabled"` 重新映射为 Opus 4.7/4.8 所需的 `adaptive` 形状（`enabled` → 400）。**(D)** 在回放时，无签名的 `reasoning_content` 被重建为携带伪造签名的 `thinking` 块 → Anthropic `400 "Invalid signature in thinking block"`；现在发出无签名的 `redacted_thinking` 块（真实签名仍然逐字保留）。回归测试：`tests/unit/thinking-budget-hydration-5312.test.ts`、`base-thinking-budget-config-5312.test.ts`、`openai-to-claude-redacted-replay-5312.test.ts`（现有 #5123/#4479/#2454 套件仍通过）。`` 内容标记通道不匹配（RC-C，与 #5245 共享）作为后续任务待 Anthropic 在线验证。([#5312](https://github.com/diegosouzapw/OmniRoute/issues/5312) — 感谢 @vitalNohj) +- **opencode (proxy pool):** OpenCode Free 每账户代理模态框现在提供全局**代理池下拉菜单**（按 ID 引用），而不是强制在每个账户上手动填写 Host/Port/凭证——#5217 缺口 1。**已保存/自定义**切换开关："已保存"从 `GET /api/settings/proxies` 中选择预保存的代理并存储 `{fingerprint, proxyId}`，因此更新该池代理会应用到使用它的所有账户；"自定义"保留手动输入（内联存储）作为退路。解析在服务端进行（`resolveAccountProxiesFromRegistry`），因此执行器仍然收到不变的已解析代理；现有的内联条目继续有效，未知/已删除的 `proxyId` 安全降级为直连。回归测试：`tests/unit/noauth-proxy-resolution.test.ts`、`tests/unit/ui/noauth-account-card.test.tsx`。([#5217](https://github.com/diegosouzapw/OmniRoute/issues/5217) 缺口 1 — 感谢 @daniij) +- **thinking (claude):** 让原生 reasoning_content 客户端（如 Cursor）可以退出 `` 关闭标记，使其不再将孤立的 `` 泄漏到可见的 `content` 中（#5312 的 RC-C，与 #5245 共享）。标记抑制机制已存在（UA 白名单，#5348），但 Cursor 的 UA 被有意排除在外；此次添加了显式请求头 `x-omniroute-thinking-marker: off`（也支持 `on`/`keep` 强制保留）来覆盖 UA 策略。未携带此头时行为逐字节不变——扫描 `content` 中标记的 Claude Code/Cursor-composer 客户端（#4633）仍然会收到它。回归测试：`tests/unit/think-close-marker-suppress-5245.test.ts`（#5123 case-b + #4479 仍通过）。([#5312](https://github.com/diegosouzapw/OmniRoute/issues/5312), [#5245](https://github.com/diegosouzapw/OmniRoute/issues/5245) — 感谢 @vitalNohj, @wild-feather) +- **cors:** 浏览器/Electron 客户端（如 Wayland AI）现在可以开箱即用地将 OmniRoute 作为 OpenAI 兼容的服务商使用。Token 认证的 API 面（`/v1/*`、`/v1beta/*`）现在默认返回宽松的 `Access-Control-Allow-Origin`（回显请求中的 `Origin`，无时使用 `*`）——与 9router 和 OpenAI 兼容生态系统保持一致——因此渲染进程的 `fetch` 可以读取响应，而不是因 CORS 阻止而失败为"站点未找到"/空目录（而 `curl` 不发送预检请求，可以正常工作）。这是**安全的**：这些路由通过浏览器永远不会自动附加的 `Authorization`/`x-api-key` 头进行认证（无凭证会话/CSRF 暴露），并且 `Access-Control-Allow-Credentials` 永远不与回显/通配符配对。Cookie 认证的 **MANAGEMENT/dashboard 路由保持严格失败关闭**；`CORS_ALLOW_ALL`/`CORS_ALLOWED_ORIGINS` 仍然优先。回归测试：`tests/unit/cors/origins.test.ts`、`tests/unit/authz/pipeline.test.ts`。（Bug 2 [#5242](https://github.com/diegosouzapw/OmniRoute/issues/5242) — 感谢 @jonlwheat2-gif） +- **grok-web:** 转发 Cloudflare 验证 Cookie，停止将 IP 信誉拦截误标为错误 Cookie。"检测 Cookie"即使使用有效的完整浏览器会话也返回 `Invalid SSO cookie`——但 Cookie 解析器从来没有问题（它能从完整的 DevTools 头中稳健提取 `sso`/`sso-rw`）。修复了两个实际问题：**(1)** `buildGrokCookieHeader` 现在粘贴时会转发 `cf_clearance` 和 `__cf_bm`（之前会丢弃它们；AIClient2API 也会转发）——严格增量，裸 `sso` blob 仍然产生完全相同的 `sso=…`；**(2)** 当用户提供了 `cf_clearance` 时，来自 grok.com 的 401 / invalid-credentials-403 现在会显示为 IP 信誉/反机器人拦截（cf_clearance 与 IP+TLS+UA 绑定，无法从不同机器重放），而不是误导性的"无效 SSO Cookie——请重新粘贴"。没有 clearance 的裸 Cookie 仍然获得重新粘贴提示。回归测试：`web-cookie-auth.test.ts` + `provider-validation-specialty.test.ts`。([#5350](https://github.com/diegosouzapw/OmniRoute/issues/5350) — 感谢 @SeaXen) +- **cli (serve):** `omniroute serve` 可选的原生 **HTTPS/TLS**——使严格 CSP 的 Electron 应用和浏览器可以通过 `https://` 访问 OmniRoute，而非纯 `http://localhost`。提供 `--tls-cert --tls-key `（或 `OMNIROUTE_TLS_CERT`/`OMNIROUTE_TLS_KEY`），独立服务器在同一监听端口上终止 TLS（无需额外端口/代理）；WebSocket 升级（实时仪表盘 + `/v1` 流式传输）通过 `wss://` 正常工作，因为 `https.Server extends http.Server`。无 TLS 标志时 HTTP 路径与之前逐字节相同；仅提供 cert 或 key 其中之一、或路径不可读时，记录警告并保持 HTTP（永不会半启用，永不会崩溃）。本地主机的自动生成自签名证书作为后续任务；目前请提供显式的 cert/key（或在 OmniRoute 前部署 TLS 终结器）。回归测试：`tests/unit/tls-options.test.ts`。（Bug 1C [#5242](https://github.com/diegosouzapw/OmniRoute/issues/5242) — 感谢 @jonlwheat2-gif） +- **opencode/observability:** 使 OpenCode Free 账户/代理轮换可见，并修复两个伴随发现的实际缺陷。**(1)** 每请求轮换选择日志（`dispatch via account … through proxy …`）级别为 `debug`（在默认 `APP_LOG_LEVEL=info` 下被隐藏）——提升为 `info`，使洗牌/冷却生命周期可审核（Token 保持脱敏）。**(2)** `[ProxyEgress]` 即使应用了账户代理也报告 `proxy=direct`，因为出口日志器位于执行器的嵌套代理上下文之外运行——现在有效应用的代理通过线程化到 proxy AsyncLocalStorage 的应用代理接收器来捕获，并反映在出口日志中。**(3)** `[callLogs] too many SQL variables`——`deleteCallLogRowsByIds` 在单个 `IN (…)` 中删除多达 5000 个 ID，超过 SQLite 的 ~999 绑定参数上限，导致日志裁剪/保留操作中断；ID 现在分块处理（每语句 ≤500）。回归测试：`tests/unit/call-log-trim-sql-vars-5217.test.ts`、`apply-executor-proxy-info-5217.test.ts`、扩展的 `opencode-proxy-rotation-4954.test.ts`。([#5217](https://github.com/diegosouzapw/OmniRoute/issues/5217) — 感谢 @daniij) +- **chatgpt-web:** 将工具/函数调用接入 `chatgpt-web` 服务商。它是唯一从未读取 `body.tools` 的 Web 会话执行器——两个响应构建器都硬编码 `finish_reason:"stop"` 并仅输出内容，因此工具调用被静默丢弃（模型用散文回答）。现在使用共享的 `webTools` 提示模拟适配层（`` 约定的 system 消息 + `{…}` 响应解析），完全与其他 9 个同级执行器一致（qwen-web、perplexity-web 等）——它只是被 #3259 发布所遗漏。工具模式缓冲并输出 `tool_calls` + `finish_reason:"tool_calls"`（与图像生成路径隔离）；纯聊天不变。回归测试：`tests/unit/chatgpt-web-tools-5240.test.ts`。([#5240](https://github.com/diegosouzapw/OmniRoute/issues/5240) — 感谢 @Rougler) +- **oauth/dashboard:** 修复持久化/错误的 Antigravity "Token 已过期"徽章（#3679/#3850 的延续）。两个原因：**(1)** 新的 OAuth 连接从未设置 `tokenExpiresAt`（仅 `expiresAt`），因此仪表盘徽章——优先使用 `tokenExpiresAt || expiresAt`——回退到原始授权时钟，可能在首次后台刷新前闪烁错误的"Token 已过期"。现在创建时在所有 5 个 OAuth 创建路径中都将 `expiresAt` 镜像到 `tokenExpiresAt`（共享的 `buildOAuthConnectionCreatePayload`），与每个已经写入两者的刷新路径保持一致。**(2)** 当可刷新的连接没有可用的刷新 Token 时，健康检查扫描会静默跳过它，导致 `testStatus="active"` 永远保持而外观徽章却显示过期；现在会输出终止性的 `testStatus="expired"`（"需要重新认证"），严格设置门控，永不会覆盖不可刷新的服务商或已终止/冷却状态。回归测试：`tests/unit/oauth-connection-tokenexpiresat-5326.test.ts`、`tests/unit/token-health-no-refresh-token-expired-5326.test.ts`。([#5326](https://github.com/diegosouzapw/OmniRoute/issues/5326)) +- **routing:** 对 API 密钥轮询连接（一个连接中有多个密钥的 `extraApiKeys`）在遇到上游 `402 "Insufficient account balance"` 时自动禁用已耗尽的 API Key。每个连接的路径已经将 402 终止化（→ `credits_exhausted`），但每个 KEY 的健康跟踪器（`recordKeyHealthStatus`）仅记录 `401` 的失败，因此 402 耗尽的密钥仍留在轮换中并不断重试。现在 402 通过新的 `recordKeyTerminal` 将当前密钥立即标记为无效（终止态——余额在会话中间不会恢复），因此轮换器跳过它并切换到下一个健康密钥；状态跨重启持久化。同时还向余额耗尽体信号中添加了 `insufficient balance`/`insufficient_balance`/`insufficient account balance`，使非 402 的余额不足响应也能终止化。回归测试：`tests/unit/key-health-402-disable-5239.test.ts`。([#5239](https://github.com/diegosouzapw/OmniRoute/issues/5239) — 感谢 @muflifadla38) +- **cli:** `omniroute serve` 不再丢弃用户设置的 `NODE_OPTIONS=--max-old-space-size=…`。之前无条件地覆盖 `NODE_OPTIONS`（并传递显式的 `--max-old-space-size` CLI 参数）使用校准默认值，导致导出 `--max-old-space-size=8192` 的用户仍然以旧的限制运行并发生 OOM（#5238 报告者设置 8192，在约 505MB 时崩溃）。现在与 Electron 和独立启动器行为一致：如果 `NODE_OPTIONS` 已经固定了堆内存，该值优先（并抑制重复的 CLI 参数）；否则追加校准的 `--max-old-space-size`，保留不相关的标志。回归测试：`tests/unit/serve-node-options-preserve-5238.test.ts`。（缺陷 C [#5238](https://github.com/diegosouzapw/OmniRoute/issues/5238)；`b.mask`/OOM-root 部分单独跟踪。） +- **dashboard:** 恢复服务商的**可用模型**工具栏中的 `{active}/{total} active` 模型数量徽章（服务商详情页）。它在 v3.8.13 的神文件分解（#3327）中被删除——`ModelVisibilityToolbar` 仍然接收 `activeCount`/`totalCount`，但它们被孤立为未使用的 `_` 前缀参数，渲染 `` 从未被迁移过来（`modelsActiveCount` i18n 键仍然保留）。重新连接现有 props 到现有键；零数据层或 i18n 更改。回归测试：`modelVisibilityToolbarActiveCount.test.tsx`。([#5264](https://github.com/diegosouzapw/OmniRoute/issues/5264)) +- **rerank:** `/v1/rerank` 不再以 `400 "Invalid rerank model"` 拒绝 SiliconFlow 和 DeepInfra 的 Qwen3-Reranker 模型，即使 `/v1/models` 已列出它们。模型 ID 解析器从来不是问题（它已经在第一个斜杠处分割，因此 `siliconflow/Qwen/Qwen3-Reranker-8B` 解析正确）——`siliconflow` 和 `deepinfra` 只是缺失了 rerank 服务商注册。已添加两者：SiliconFlow 作为 Cohere 兼容，DeepInfra 通过新的 `deepinfra` 适配器（模型在 URL 路径中 `POST /v1/inference/`，`{queries,documents}` 请求，位置 `{scores}` 响应映射为 Cohere `results[]`）。回归测试：`tests/unit/rerank-providers-5332.test.ts`。([#5332](https://github.com/diegosouzapw/OmniRoute/issues/5332) — 感谢 @maikokan) +- **authz/dashboard:** 当通过局域网 IP/非 localhost 主机访问仪表盘时，不再以 `403 INVALID_ORIGIN` 拒绝所有仪表盘变更操作。源绑定检查（#5278）只接受配置的 `*_PUBLIC_BASE_URL`（通常为 `http://localhost:20128`）加上内部的 `request.url` 源——而 Next.js standalone 报告的是绑定主机而非真实的 `Host`。因此在 `http://192.168.0.15:20128` 打开仪表盘会使浏览器的同源 `Origin` 无法匹配任何候选项，导致**所有** POST/PUT/DELETE（保存 API Key、保存服务商、测试连接）都失败，而 GET 仍能正常工作。两个修复：**(a)** 请求 `Host`（或受信任的 `X-Forwarded-Host`）现在被接受为有效的变更操作源，由两个独立检查控制——Token 标记的 socket 对端必须是 loopback/私有局域网**且** Host 本身也必须是 loopback/私有局域网 IP 字面量，因此 DNS 重绑定域名（分类为 `remote`）永远不能成为受信任的源，协议绑定到实际连接；(b) `INVALID_ORIGIN` 响应现在携带可操作的消息（设置 `OMNIROUTE_PUBLIC_BASE_URL`），仪表盘通过共享的 `extractApiErrorMessage` 辅助函数显示 API 错误 `.message`，而不是渲染原始错误对象。回归测试：`tests/unit/authz/public-origin.test.ts`（直接 LAN/loopback + DNS 重绑定防御）、`tests/unit/api-error-message-5340.test.ts`。([#5340](https://github.com/diegosouzapw/OmniRoute/issues/5340)) -### 📝 Maintenance +### 📝 维护 - **chore(dead-code):** repo-wide sweep of unused exported symbols and a matching dead-code baseline ratchet — trimmed unused exported helpers, validation/settings/encryption-config schemas, utility/domain/static-constant/formatting helpers, runtime test helpers, the request-timeout fetch wrapper, event-bus, semantic-cache (maintenance + expiry), correlation-middleware, MCP-scope, service-registry, build-profile, api-key-format, authz-class, models.dev-context, embedding-cache, provider-limits-scheduler, search-validator, webhook-example, agent-skills-repo-URL and command-code-auth-cleanup exports. Pure dead-code removal validated by `typecheck:core` (no remaining referencing site) — no behavior change. ([#5321](https://github.com/diegosouzapw/OmniRoute/pull/5321), [#5322](https://github.com/diegosouzapw/OmniRoute/pull/5322), [#5324](https://github.com/diegosouzapw/OmniRoute/pull/5324), [#5325](https://github.com/diegosouzapw/OmniRoute/pull/5325), [#5328](https://github.com/diegosouzapw/OmniRoute/pull/5328), [#5329](https://github.com/diegosouzapw/OmniRoute/pull/5329), [#5330](https://github.com/diegosouzapw/OmniRoute/pull/5330), [#5331](https://github.com/diegosouzapw/OmniRoute/pull/5331), [#5333](https://github.com/diegosouzapw/OmniRoute/pull/5333), [#5334](https://github.com/diegosouzapw/OmniRoute/pull/5334), [#5335](https://github.com/diegosouzapw/OmniRoute/pull/5335), [#5336](https://github.com/diegosouzapw/OmniRoute/pull/5336), [#5338](https://github.com/diegosouzapw/OmniRoute/pull/5338), [#5339](https://github.com/diegosouzapw/OmniRoute/pull/5339), [#5353](https://github.com/diegosouzapw/OmniRoute/pull/5353), [#5354](https://github.com/diegosouzapw/OmniRoute/pull/5354), [#5355](https://github.com/diegosouzapw/OmniRoute/pull/5355), [#5356](https://github.com/diegosouzapw/OmniRoute/pull/5356), [#5357](https://github.com/diegosouzapw/OmniRoute/pull/5357), [#5359](https://github.com/diegosouzapw/OmniRoute/pull/5359), [#5362](https://github.com/diegosouzapw/OmniRoute/pull/5362), [#5364](https://github.com/diegosouzapw/OmniRoute/pull/5364), [#5365](https://github.com/diegosouzapw/OmniRoute/pull/5365), [#5366](https://github.com/diegosouzapw/OmniRoute/pull/5366), [#5368](https://github.com/diegosouzapw/OmniRoute/pull/5368), [#5369](https://github.com/diegosouzapw/OmniRoute/pull/5369), [#5371](https://github.com/diegosouzapw/OmniRoute/pull/5371) — thanks @JxnLexn) @@ -138,28 +138,28 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.39] — 2026-06-28 -### ✨ New Features +### ✨ 新功能 -- **feat(oauth): remote Antigravity login via local helper + paste-credentials** — Antigravity (and other Google "native/desktop" OAuth providers) use Google's `firstparty/nativeapp` consent, which only releases the auth code when the loopback redirect (`127.0.0.1:`) is reachable from the approving browser. On a remote VPS install that loopback lives on the server, so the consent hangs forever and never emits a code — the "paste the callback URL" fallback has nothing to paste (a Google-side constraint, identical in upstream 9router). A new `omniroute login antigravity` CLI helper runs the OAuth on the user's **own** machine (where 127.0.0.1 works), exchanges the code, and prints a single-line `omniroute-cred-v1.…` credential blob; the dashboard's Antigravity Connect → Step 2 field now accepts that blob (alongside callback URLs) and persists the connection via a new `paste-credentials` action (server-side onboarding, provider-allowlisted, with the blob's embedded provider required to match the route). The SSH local-forward tunnel is documented as a zero-tooling alternative. See [`docs/guides/REMOTE-MODE.md`](docs/guides/REMOTE-MODE.md). ([#5203](https://github.com/diegosouzapw/OmniRoute/pull/5203)) -- **feat(agent-bridge): graceful cert-install fallback for containers / headless** — when the MITM root CA can't be installed into the system trust store automatically (Docker / headless / no sudo / read-only trust store), the Agent Bridge no longer hard-fails on start with a generic "Certificate install failed". It now starts in skip mode and the dashboard surfaces a platform-specific **manual-install guide** (plus a CA download link) so the operator can trust the certificate by hand. The trust-cert endpoints return a structured `{ skippable, manualGuide }` response (HTTP 200) for environment failures instead of a 500; an explicit user cancellation is still reported distinctly. ([#4546](https://github.com/diegosouzapw/OmniRoute/issues/4546) — thanks @phuchptty) -- **feat(compression): CCR ranged/grep/stats retrieval (ReDoS-safe, backward-compat)** — extends the `omniroute_ccr_retrieve` MCP tool and `/api/compression/retrieve` endpoint with optional `range` (byte/line slice), `grep` (ReDoS-safe literal or bounded-pattern match against stored lines), and `stats` (byte/line/word counts) parameters so agents pull exactly the slice or summary they need instead of re-expanding the entire stored block. All parameters are optional — no parameters returns the full block byte-identical to the existing behavior; the CCR store written by ionizer/fuzzy/headroom is fully compatible. Sixth item of the compression roadmap. ([#5187](https://github.com/diegosouzapw/OmniRoute/pull/5187)) -- **feat(compression): TOON best-of-N candidate encoder + encoder A/B table** — adds `@toon-format/toon` as a candidate encoder in the headroom compression engine via a best-of-N scheme: both GCF and TOON run per prompt and the shorter result is kept, rather than hard-swapping encoders (GCF already encodes the headroom block and TOON is not a lossless universal win). An encoder A/B comparison table (GCF vs TOON vs JSON — bytes and cl100k tokens) is now surfaced in the compression studio. Fifth item of the compression feature-extraction roadmap (bench: [#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080), gate: [#5127](https://github.com/diegosouzapw/OmniRoute/pull/5127), fuzzy/gate: [#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143), ionizer: [#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148)). ([#5163](https://github.com/diegosouzapw/OmniRoute/pull/5163)) +- **feat(oauth): 远程 Antigravity 登录 —— 本地助手 + 粘贴凭证** — Antigravity（及其他 Google "原生/桌面" OAuth 服务商）使用 Google 的 `firstparty/nativeapp` 授权页面，只有当 loopback 重定向（`127.0.0.1:`）可从授权浏览器访问时才释放认证码。在远程 VPS 安装中，该 loopback 存在于服务器上，因此授权页面永远挂起，从不发出认证码——"粘贴回调 URL"的退路方案无法使用（这是 Google 端的限制，上游 9router 同样存在）。新增 `omniroute login antigravity` CLI 助手在用户**本地**机器上运行 OAuth（127.0.0.1 可用），交换认证码，并打印一行 `omniroute-cred-v1.…` 凭证 blob；仪表盘的 Antigravity 连接 → 第 2 步字段现在接受该 blob（以及回调 URL），并通过新的 `paste-credentials` 操作持久化该连接（服务端引导，服务商白名单化，blob 中内嵌的服务商必须与路由匹配）。SSH 本地转发隧道作为零工具替代方案已被文档化。参见 [`docs/guides/REMOTE-MODE.md`](docs/guides/REMOTE-MODE.md)。([#5203](https://github.com/diegosouzapw/OmniRoute/pull/5203)) +- **feat(agent-bridge): 容器/无头环境下的优雅证书安装回退** — 当 MITM 根 CA 无法自动安装到系统信任存储时（Docker / 无头 / 无 sudo / 只读信任存储），Agent Bridge 不再在启动时以通用"Certificate install failed"硬失败。它现在以跳过模式启动，仪表盘展示平台特定的**手动安装指南**（加上 CA 下载链接），运维人员可以手动信任证书。([#4546](https://github.com/diegosouzapw/OmniRoute/issues/4546) — 感谢 @phuchptty) +- **feat(compression): CCR 范围/grep/统计检索（ReDoS 安全、向后兼容）** — 为 `omniroute_ccr_retrieve` MCP 工具和 `/api/compression/retrieve` 端点扩展 `range`（字节/行切片）、`grep`（ReDoS 安全的字面量或有界模式匹配）和 `stats`（字节/行/词计数）参数，代理可以精确获取需要的切片或摘要。所有参数均可选——无参数时返回完整块，行为与现有行为逐字节相同；CCR 存储完全兼容。压缩路线图第六项。([#5187](https://github.com/diegosouzapw/OmniRoute/pull/5187)) +- **feat(compression): TOON 最优 N 候选编码器 + 编码器 A/B 对比表** — 将 `@toon-format/toon` 作为候选编码器通过最优 N 方案添加到 headroom 压缩引擎：每个提示同时运行 GCF 和 TOON，保留较短结果。压缩工作室中展示编码器 A/B 对比表（GCF/TOON/JSON——字节数和 cl100k Token）。压缩特性提取路线图第五项。([#5163](https://github.com/diegosouzapw/OmniRoute/pull/5163)) -### 🔧 Bug Fixes +### 🔧 问题修复 -- **fix(oauth): Antigravity refresh no longer nulls the stored refresh_token on an empty upstream response** — Google's OAuth token endpoint uses non-rotating refresh tokens: a refresh response normally OMITS `refresh_token` and occasionally returns it as an empty string. The Antigravity executor's `refreshCredentials` used `typeof tokens.refresh_token === "string" ? tokens.refresh_token : credentials.refreshToken`, and because `typeof "" === "string"` is true, an empty-string response overwrote the good token with `""` — nulling it on first refresh. The check now treats a non-string **or empty** value as absent and preserves the stored token, matching the canonical `refreshGoogleToken` (`tokens.refresh_token || refreshToken`) semantics. ([#3850](https://github.com/diegosouzapw/OmniRoute/issues/3850) — thanks @3xa228148) -- **fix(api): LAN/Tailscale dashboard access — `ws:` CSP scheme, GET-exempt version route, surface combo field errors** — three failures when opening the dashboard from a non-loopback host: (1) CSP `connect-src` allowed the `ws:` scheme only for loopback origins, blocking the dashboard's `ws://:*` Live WebSocket from LAN/Tailscale clients; the bare `ws:` scheme is now permitted (symmetric with the bare `wss:` already allowed), kept declarative in `next.config.mjs` with no global middleware (the project has none by design); (2) `GET /api/system/version` was blocked by `LOCAL_ONLY_API_PREFIXES` for all methods despite only `POST` spawning child processes (git/npm/pm2) — a new `LOCAL_ONLY_API_GET_EXEMPTIONS` set exempts safe read methods for this path while keeping `POST`/`PUT`/`PATCH`/`DELETE` strictly loopback-only; (3) `COMBO_002` validation errors only surfaced the generic message — `firstField`/`firstMessage` are now extracted from the first Zod issue and included in the response body. ([#5083](https://github.com/diegosouzapw/OmniRoute/issues/5083) — thanks @KooshaPari for the diagnosis and original PR #5084) -- **fix(sse): defer `` close so it never leaks before `tool_calls` in Claude→OpenAI streaming** — when a Claude thinking block was followed by a tool_use block, the translator unconditionally emitted a `content: ""` chunk at `content_block_stop`, injecting a spurious assistant text chunk immediately before the `tool_calls` delta and corrupting OpenAI-compatible clients (e.g. Kimi Coding). The close marker is now deferred: it is flushed at the first `text_delta` that follows the thinking block (preserving the #4633 / decolua/9router#454 behavior for Claude Code / Cursor) or at stream finish when no tool_calls were collected. Tool-use streams never get a `text_delta` after the thinking block, so `` is never emitted into content before `tool_calls`. ([#5123](https://github.com/diegosouzapw/OmniRoute/issues/5123)) -- **fix(sse): normalize array user-message content in the Command Code executor to prevent upstream 400** — when a client sends a user turn whose `content` is an array of content parts (e.g. `[{type:"text",text:"…"}, …]`), the raw array was forwarded verbatim to the Command Code upstream, which requires `messages[N].content` for the `user` role to be a plain string — resulting in `expected string, received array` / HTTP 400 on DeepSeek V4-Pro and other Command Code models. The user branch of `convertMessages` now calls `normalizeContentText()` (already used by system, assistant, and tool branches) so multi-part user content is joined to a string before dispatch. Partially addresses ([#5166](https://github.com/diegosouzapw/OmniRoute/issues/5166)); the 0-output-token symptom on reasoning-only models is tracked separately. -- **fix(mcp): return HTTP 404 (not 400) for an unknown/expired Streamable HTTP session id** — when an MCP session is terminated or idles out and the client reuses the stale `Mcp-Session-Id` header, the Streamable HTTP transport replied with HTTP 400. The MCP spec (2025-03-26 and 2025-11-25, Session Management) mandates HTTP 404 Not Found in that case, and spec-compliant clients only re-initialize a session on 404 — so the 400 was non-recoverable. The handler now returns 404 for a present-but-unknown session id, while a _missing_ session id on a non-initialize request correctly stays 400. ([#5169](https://github.com/diegosouzapw/OmniRoute/issues/5169) — thanks @czer323) -- **fix(api): blocking "Auto (Zero-Config)" in Security settings now removes `auto/*` from `/v1/models`** — the built-in `auto/*` combo advertiser (#4164 / #4235) at the top of the models catalog ignored `settings.blockedProviders`, so checking **Auto (Zero-Config)** under Security → Blocked Providers had no effect and the model picker kept listing every `auto/*` entry. The injection loop now skips the entire `auto/*` block when the system provider `auto` (its id and alias are both `auto`) is blocked, consistent with how every other provider is filtered from the catalog. ([#5192](https://github.com/diegosouzapw/OmniRoute/issues/5192) — thanks @WslzGmzs) -- **fix(cli): auto-calibrate the server V8 heap from physical RAM instead of a fixed 512MB default** — the server was spawned with a hard-coded `--max-old-space-size=512` (`omniroute serve`) or with no heap flag at all (Electron desktop, which then inherited the runtime's low ~512MB default), so RAM-rich machines still OOM-crashed under load (`FATAL ERROR: Ineffective mark-compacts near heap limit … ~500MB` at code=134) with many providers/accounts and large model catalogs (one report: 16GB RAM, 65 providers, ~100 accounts, ~2600 models). A new `calibrateHeapFallbackMb(os.totalmem())` helper derives the default heap as ~35% of physical RAM, clamped to `[512, 4096]`, and is wired into both `bin/cli/commands/serve.mjs` and `electron/main.js`. An explicit `OMNIROUTE_MEMORY_MB` (or a pre-set `--max-old-space-size`) still wins, so the #2939 override contract is unchanged. ([#5172](https://github.com/diegosouzapw/OmniRoute/issues/5172), [#5160](https://github.com/diegosouzapw/OmniRoute/issues/5160), [#5152](https://github.com/diegosouzapw/OmniRoute/issues/5152) — thanks @manchairwang, @Xyzjesus) +- **fix(oauth): Antigravity 刷新不再因上游空响应将存储的 refresh_token 置空** — Google 的 OAuth Token 端点使用非轮换刷新 Token：刷新响应通常不包含 `refresh_token`，偶尔会返回空字符串。Antigravity 执行器的 `refreshCredentials` 使用了 `typeof tokens.refresh_token === "string" ? tokens.refresh_token : credentials.refreshToken`，而 `typeof "" === "string"` 为真，因此空字符串响应将有效 Token 覆盖为空——首次刷新即将其置空。现在将非字符串**或空值**视为缺失，保留存储的 Token，与规范的 `refreshGoogleToken`（`tokens.refresh_token || refreshToken`）语义一致。([#3850](https://github.com/diegosouzapw/OmniRoute/issues/3850) — 感谢 @3xa228148) +- **fix(api): LAN/Tailscale 仪表盘访问——`ws:` CSP 方案、版本路由 GET 豁免、展示 combo 字段错误** — 从非 loopback 主机打开仪表盘时的三个故障：(1) CSP `connect-src` 仅对 loopback 源允许 `ws:` 方案，阻止了 LAN/Tailscale 客户端的实时 WebSocket 连接；现在允许裸 `ws:`（与已允许的 `wss:` 对称）；(2) `GET /api/system/version` 被 `LOCAL_ONLY_API_PREFIXES` 阻止——新增豁免白名单；(3) `COMBO_002` 校验错误现在在响应中包含首个 Zod 问题的字段和消息。([#5083](https://github.com/diegosouzapw/OmniRoute/issues/5083) — 感谢 @KooshaPari) +- **fix(sse): 延迟 `` 关闭以防止其在 Claude→OpenAI 流式传输中泄漏到 `tool_calls` 之前** — 思考块后跟 tool_use 块时翻译器会注入伪造的助手文本区块。关闭标记现在推迟到第一个 `text_delta` 或流结束时刷新。([#5123](https://github.com/diegosouzapw/OmniRoute/issues/5123)) +- **fix(sse): 规范化 Command Code 执行器中数组类型的用户消息内容以防止上游 400** — 用户消息 content 为数组时被逐字转发（Command Code 要求字符串），现在调用 `normalizeContentText()` 合并为字符串。([#5166](https://github.com/diegosouzapw/OmniRoute/issues/5166)) +- **fix(mcp): 对未知/过期�� Streamable HTTP 会话 ID 返回 HTTP 404（而非 400）** — MCP 规范要求 404 以便客户端重新初始化。缺少会话 ID 的非初始化请求仍正确返回 400。([#5169](https://github.com/diegosouzapw/OmniRoute/issues/5169) — 感谢 @czer323) +- **fix(api): 安全设置屏蔽"自动（零配置）"现在从 `/v1/models` 移除 `auto/*`** — 内置 `auto/*` 公告商忽略了 `settings.blockedProviders`。注入循环现在在 `auto` 被屏蔽时跳过整个 `auto/*` 块。([#5192](https://github.com/diegosouzapw/OmniRoute/issues/5192) — 感谢 @WslzGmzs) +- **fix(cli): 根据物理 RAM 而非固定 512MB 默认值自动校准服务器 V8 堆内存** — 新 `calibrateHeapFallbackMb` 按物理 RAM ~35% 推导默认堆大小，限制 `[512, 4096]`。`OMNIROUTE_MEMORY_MB` 仍优先。([#5172](https://github.com/diegosouzapw/OmniRoute/issues/5172) — 感谢 @manchairwang, @Xyzjesus) -- **fix(oauth): Antigravity login no longer hangs — fire-and-forget onboarding + bounded post-exchange** — the dashboard's Antigravity OAuth login spun indefinitely because `postExchange` awaited the `onboardUser` retry loop inline (up to 10 × 5 s per attempt, each fetch with no timeout), blocking the `/exchange` response forever. Matching the upstream 9router web flow: `onboardUser` now runs fire-and-forget in a background task; the `/exchange` endpoint is bounded by a 10 s hard timeout so it always returns; a progress endpoint lets the dashboard poll onboarding completion state. ([#5193](https://github.com/diegosouzapw/OmniRoute/pull/5193)) -- **fix(antigravity): retry Antigravity accounts by quota family before escalating the combo** — when one Antigravity account returns a quota or rate-limit `429` for a Gemini model (e.g. `gemini-3.5-flash-medium`), combo orchestration could prematurely advance to the next combo model instead of trying other eligible Antigravity accounts for the same quota family. Antigravity quota-family awareness is now added to the fallback path so a `429` on one account triggers a bounded same-model retry across other Antigravity accounts sharing that quota bucket before the combo degrades to a lower-tier model. ([#5180](https://github.com/diegosouzapw/OmniRoute/pull/5180) — thanks @Ardem2025) -- **fix(translator): accept Claude Messages shape in the non-stream malformed-200 guard** — when a Claude client (e.g. Claude Code) is routed to a non-Claude provider, the translated non-streaming response body is in Claude Messages shape (`type: "message", content[]`) produced by `convertOpenAINonStreamingToClaude`. `detectMalformedNonStream` only recognized OpenAI `choices[].message` and Responses API `output[]`, so this shape fell through to `empty_choices` → 502. The guard now recognizes the Claude Messages shape: text, tool_use, and thinking blocks carrying a `signature` count as valid output, while a genuinely empty `content: []` is still flagged. ([#5156](https://github.com/diegosouzapw/OmniRoute/pull/5156) — thanks @NomenAK) -- **fix(sse): resolve nameless deepseek-web `` blocks via parameter-schema match** — when `chat.deepseek.com` emits a `` block with no `` child, no JSON body `name`/`type` key, and no tag suffix, every name-resolution path in `extractCall` returned `null` and the raw XML leaked to the client as plain text. A conservative schema-based fallback now compares the block's extracted parameter names against each declared tool's schema keys; if exactly one tool matches, its name is used. Zero or ambiguous (>1) matches still return `null` so no calls are misattributed. ([#5154](https://github.com/diegosouzapw/OmniRoute/issues/5154), [#5173](https://github.com/diegosouzapw/OmniRoute/pull/5173)) -- **fix(stream): normalize provider safety finish reasons to `content_filter`** — Gemini and Antigravity can return safety/prohibited terminal reasons (`SAFETY`, `RECITATION`, `BLOCKLIST`, `PROHIBITED_CONTENT`) that OpenAI-compatible downstream clients do not recognize. A shared finish-reason normalization helper now maps these to the standard `content_filter` value, applied in both the streaming and JSON collection paths for both providers. ([#5197](https://github.com/diegosouzapw/OmniRoute/pull/5197) — thanks @rdself) +- **fix(oauth): Antigravity 登录不再卡死——fire-and-forget 引导 + 有界 post-exchange** — `postExchange` 内联等待 `onboardUser` 重试循环导致登录无限旋转。现在 `onboardUser` 后台 fire-and-forget，`/exchange` 受 10 秒硬超时限制。([#5193](https://github.com/diegosouzapw/OmniRoute/pull/5193)) +- **fix(antigravity): 在升级 combo 之前按配额族重试 Antigravity 账户** — 一个账户返回 429 时，combo 编排可能过早升级。现在先在同一配额族的其他账户重试。([#5180](https://github.com/diegosouzapw/OmniRoute/pull/5180) — 感谢 @Ardem2025) +- **fix(translator): 在非流式 malformed-200 防护中接受 Claude Messages 格式** — 当 Claude 客户端路由到非 Claude 服务商时，翻译后的响应体为 Claude Messages 格式，防护层未识别该格式而返回 502。现在可识别 text/tool_use/thinking 块。([#5156](https://github.com/diegosouzapw/OmniRoute/pull/5156) — 感谢 @NomenAK) +- **fix(sse): 通过参数 schema 匹配解析无名称的 deepseek-web `` 块** — 当 `chat.deepseek.com` 发出无名称 `` 块时，基于 schema 的退路方案将提取的参数名与各工具 schema 键进行比较以匹配名称。([#5154](https://github.com/diegosouzapw/OmniRoute/issues/5154)) +- **fix(stream): 将服务商安全 finish_reason 规范化为 `content_filter`** — Gemini/Antigravity 可返回 SAFETY/RECITATION/BLOCKLIST 等，不再被下游识别。现在统一映射为标准 `content_filter`。([#5197](https://github.com/diegosouzapw/OmniRoute/pull/5197) — 感谢 @rdself) - **fix(responses): normalize non-array Responses API `input` before routing** — the OpenAI Responses API accepts `input` as a string, object, or list, but OmniRoute only handled list-shaped payloads; a string or object `input` was silently dropped on the Responses→Chat Completions path. The translator now normalizes `input` to a list before dispatch; the Codex-native Responses path also normalizes before forwarding (preventing upstream `400 Input must be a list`); and the prompt-injection and PII sanitizer extraction paths are guarded against object-valued `input` so security checks do not throw. ([#5204](https://github.com/diegosouzapw/OmniRoute/pull/5204) — thanks @wilsonicdev) - **fix(zenmux): normalize vendor-prefixed GLM system roles for Z.AI models** — ZenMux exposes Z.AI GLM via vendor-prefixed OpenAI-compatible IDs such as `z-ai/glm-5.2`. The existing GLM detection only matched bare `glm-*`/`glm` ids, so `zenmux/z-ai/glm-5.2` kept system messages in place; Z.AI rejects compressed histories ending with a system turn before `assistant(tool_calls) → tool` sequences. The fix extends GLM detection to cover `z-ai/glm-*` prefixes and routes them through the existing `normalizeSystemRole` path. ([#5158](https://github.com/diegosouzapw/OmniRoute/pull/5158) — thanks @Thinkscape) - **fix(xai): add OAuth connection test probe + normalize xAI reasoning effort aliases** — xAI rejects unsupported reasoning effort values (`max`, `xhigh`) with HTTP 400 after a provider update; the xAI translator now maps `max` and `xhigh` to `high` before forwarding. Additionally, xAI OAuth connections had no dashboard test configuration, so provider tests returned `"Provider test not supported"`; a dedicated OAuth test probe is now wired for xAI accounts with regression coverage for the effort normalization. ([#5157](https://github.com/diegosouzapw/OmniRoute/pull/5157) — thanks @nguyenxvotanminh3) @@ -175,7 +175,7 @@ _In development — bullets added per PR; finalized at release._ - **fix(request-logger): never render a negative percentage in the compression badge** — when every prompt token was compressed (`totalIn = 0, compressed > 0`), the compression pill displayed `(-100%)` because the badge format hard-coded a leading `-` before the percentage value. The badge now omits the negative sign in this case, correctly representing the saving as a positive ratio. ([#5201](https://github.com/diegosouzapw/OmniRoute/pull/5201) — thanks @KooshaPari) - **fix(dashboard): use amber for home update-step warning icon** — the warning-state icon in the home update steps (`HomePageClient.tsx`) used `text-yellow-500` (Tailwind `#eab308`), which has poor contrast on light backgrounds (~1.9:1, below WCAG AA) and is inconsistent with the `amber` warning convention used by every sibling element in the same component. Switched to `text-amber-500` — a one-line `className` change with no behavior change. ([#5176](https://github.com/diegosouzapw/OmniRoute/pull/5176)) -### 📝 Maintenance +### 📝 维护 - **test(combo): deterministic context-relay universal-handoff coverage** — covers the universal (provider-agnostic) session-handoff path in `context-relay` (`combo.ts:2099–2139`), which previously had only a definition-order assertion and a `TODO(phase-2)`. The test drives the real pipeline via session seams (`x-session-id` → `relayOptions.sessionId` → `maybeGenerateUniversalHandoff`) without live infrastructure. ([#5168](https://github.com/diegosouzapw/OmniRoute/pull/5168)) - **test(combo): end-to-end quota-share DRR routing-decision coverage (matrix parity)** — adds the missing E2E test for the `quota-share` strategy, driving the real `handleChat` → chatCore → `selectQuotaShareTarget` → executor pipeline via in-process seams and asserting which connection is dispatched. The DRR selector already had 29 unit tests; this closes the E2E gap and brings quota-share to parity with the 17-strategy public matrix. ([#5179](https://github.com/diegosouzapw/OmniRoute/pull/5179)) @@ -191,7 +191,7 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.38] — 2026-06-27 -### ✨ New Features +### ✨ 新功能 - **feat(sidebar): colored menu icons** — sidebar menu icons now render with a per-item accent color: curated colors for known items (`SIDEBAR_ICON_ACCENTS`) plus a deterministic hash-based fallback (`getSidebarIconAccent`) so every item gets a stable, distinct color across sessions. ([#3812](https://github.com/diegosouzapw/OmniRoute/pull/3812) — thanks @rafacpti23) - **feat(providers): add Factory (factory.ai) as a subscription gateway provider** — `factory` (Factory Droids' hosted gateway) is now a first-class routing provider on the OpenAI-compatible `https://api.factory.ai/v1` endpoint with Bearer apikey auth; the key is supplied from the Dashboard connection (not env). ([#5065](https://github.com/diegosouzapw/OmniRoute/pull/5065) — thanks @KooshaPari) @@ -214,7 +214,7 @@ _In development — bullets added per PR; finalized at release._ - **feat(mcp): web-session robustness — cookie dedup + browser-pool observability** — the MCP web-session path now de-duplicates cookies when (re)hydrating a session (avoiding conflicting duplicate `Cookie` headers) and exposes browser-pool observability (pool size / in-use / acquisition metrics) for the headless web providers. ([#5121](https://github.com/diegosouzapw/OmniRoute/pull/5121), builds on [#3368](https://github.com/diegosouzapw/OmniRoute/issues/3368)) - **feat(compression): Ionizer engine — lossy JSON-array sampling reversible via CCR** — a new compression engine that down-samples large JSON arrays to a representative subset and records a Compact Change Representation (CCR) so the omitted rows can be reconstructed, trading exactness for a large token reduction on tabular/array-heavy payloads. ([#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148)) -### 🔧 Bug Fixes +### 🔧 问题修复 - **fix(proxy): make the SOCKS5 handshake timeout operator-tunable (`SOCKS_HANDSHAKE_TIMEOUT_MS`)** — under high concurrency against a single residential gateway host, the SOCKS5 connect handshake could exceed the hardcoded 10s even though the proxy was reachable, surfacing as a false `[Proxy Fast-Fail] Proxy unreachable` (the pool size is already tunable via `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS`). The handshake timeout now reads `SOCKS_HANDSHAKE_TIMEOUT_MS` (default unchanged at `10000`, capped at `120000`) so a concurrency-heavy deployment can raise it without a code change. Mitigation for #5109 (the full concurrency-100 collapse still needs the reporter's live load-test confirmation). ([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109)) - **fix(api): resolve `GET /v1/models/{id}` case-insensitively** — clients that normalise the model id (e.g. OpenCode requesting `minimax/minimax-m3` for the canonical catalog entry `minimax/MiniMax-M3`) missed the single-model lookup, which is case-sensitive, and fell back to advertising `context_length: 0`. `findModelById` now prefers an exact-case match and falls back to a case-insensitive match, so the real entry (and its context window) is returned regardless of casing. ([#5082](https://github.com/diegosouzapw/OmniRoute/issues/5082)) @@ -261,11 +261,11 @@ _In development — bullets added per PR; finalized at release._ - **fix(sse): preserve non-stream reasoning fields for compatible clients** — non-streaming responses now keep the upstream reasoning fields (`reasoning` / `reasoning_content` and OpenRouter/Gemini `reasoning_details`) instead of stripping them in `responseSanitizer`, so clients that render reasoning on buffered responses no longer lose it. ([#5155](https://github.com/diegosouzapw/OmniRoute/pull/5155) — thanks @rdself) - **fix(i18n): add missing English UI labels** — fills in untranslated English strings that were surfacing as raw keys in the dashboard. ([#5153](https://github.com/diegosouzapw/OmniRoute/pull/5153) — thanks @rdself) -### 🔒 Security +### 🔒 安全 - **fix(security): exact-host Anthropic `baseUrl` check** — the Anthropic base-URL guard used a substring match that a crafted host could partially satisfy; it now requires an exact host match (resolves CodeQL `js/incomplete-url-substring-sanitization` alert #674). ([#5130](https://github.com/diegosouzapw/OmniRoute/pull/5130)) -### 📝 Maintenance +### 📝 维护 - **refactor(store): remove dead legacy store modules** — salvaged cleanup of unused legacy store code. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @JxnLexn / @diegosouzapw) - **test(combo): deterministic routing-decision matrix for all 17 strategies** — a deterministic E2E matrix pins the routing decision of every combo strategy. ([#5146](https://github.com/diegosouzapw/OmniRoute/pull/5146)) @@ -276,7 +276,7 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.37] — 2026-06-26 -### ✨ New Features +### ✨ 新功能 - **feat(providers):** add DGrid AI gateway provider — OpenAI-compatible gateway at `api.dgrid.ai/v1` (alias `dgrid`, API-key auth, passthrough models). Free router tier (10 RPM / 100 RPD); a $5 lifetime top-up raises limits to 20 RPM / 1,000 RPD. ([#4931](https://github.com/diegosouzapw/OmniRoute/pull/4931) — thanks @dgridOP) @@ -304,7 +304,7 @@ _In development — bullets added per PR; finalized at release._ - **feat(api):** add the `MiniMax-M3` pricing row (canonical + lowercase alias) so the new MiniMax default model gets accurate per-request cost accounting instead of falling back to a zero/default rate. ([#4814](https://github.com/diegosouzapw/OmniRoute/pull/4814) — thanks @octo-patch) -### 🔧 Bug Fixes +### 🔧 问题修复 - **fix(sse):** dense, deterministic `response.output` ordering in `response.completed` — items are now sorted by their actual `output_index` (via a recorded-as-emitted accumulator + stable sort) instead of being rebuilt from unordered state dicts; `normalizeOutputIndex` replaces fragile `parseInt` calls for robust index coercion; superseded tool calls (replaced at the same index mid-stream) are excluded from the final output array. ([#4906](https://github.com/diegosouzapw/OmniRoute/pull/4906) — thanks @Marco9113) @@ -408,7 +408,7 @@ _In development — bullets added per PR; finalized at release._ - **fix(providers):** require a Default Model in the compatible-provider API-key setup flow. ([#4641](https://github.com/diegosouzapw/OmniRoute/pull/4641) — thanks @arden1601) -### 🔒 Security +### 🔒 安全 - **fix(auth):** only trust forwarding headers (`X-Forwarded-For` / `X-Real-IP`) from loopback TCP peers, so a non-loopback client can't spoof its origin to bypass local-only route guards. ([#4689](https://github.com/diegosouzapw/OmniRoute/pull/4689) — thanks @Jordannst / @diegosouzapw) @@ -416,7 +416,7 @@ _In development — bullets added per PR; finalized at release._ - **fix(oauth):** classify `/api/oauth/cursor/auto-import` as a local-only route in the route guard, so the loopback-enforced process-spawning endpoint can't be reached through a tunneled/leaked JWT (Hard Rule #17). ([#5070](https://github.com/diegosouzapw/OmniRoute/pull/5070) — thanks @diegosouzapw) -### 📝 Maintenance +### 📝 维护 - **chore(ci):** harden the release flow — decouple the Quality Ratchet from coverage-shard flakes (`if: !cancelled()` + `--allow-missing`), add fast-path drift gates (`check:complexity`, `check:cognitive-complexity`, `check:pack-policy`, `check:build-scope`), and raise the default build heap to 8 GB. ([#5054](https://github.com/diegosouzapw/OmniRoute/pull/5054) — thanks @diegosouzapw) @@ -432,7 +432,7 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.36] — 2026-06-25 -### ✨ New Features +### ✨ 新功能 **Quota-Share system** @@ -470,7 +470,7 @@ _In development — bullets added per PR; finalized at release._ --- -### 🔧 Bug Fixes +### 🔧 问题修复 **Translator** @@ -563,7 +563,7 @@ _In development — bullets added per PR; finalized at release._ --- -### 🔒 Security +### 🔒 安全 - **fix(security):** block SSRF allowlist bypass via `x-relay-path` header manipulation on Deno/Vercel relays. ([#4899](https://github.com/diegosouzapw/OmniRoute/pull/4899)) - **fix(security):** pin image-fetch DNS resolution to prevent SSRF DNS-rebinding attacks (GHSA-cmhj-wh2f-9cgx). ([#4634](https://github.com/diegosouzapw/OmniRoute/pull/4634)) @@ -573,7 +573,7 @@ _In development — bullets added per PR; finalized at release._ --- -### 📝 Maintenance +### 📝 维护 **God-file decomposition (continued, #3501)** @@ -607,12 +607,12 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.35] — 2026-06-23 -### ✨ New Features +### ✨ 新功能 - **Adaptive context compression (Phase 4)**: a four-layer compression upgrade landed across stacked PRs — an **Output Styles** registry (`terse-prose` / `less-code` / `terse-cjk`) ([#4694](https://github.com/diegosouzapw/OmniRoute/pull/4694) — thanks @diegosouzapw), an opt-in **SLM `ultra` tier** (two-tier LLMLingua with heuristic fallback) ([#4707](https://github.com/diegosouzapw/OmniRoute/pull/4707) — thanks @diegosouzapw), a **context-budget adaptive dial** (reserve-output ladder + floor) ([#4716](https://github.com/diegosouzapw/OmniRoute/pull/4716) — thanks @diegosouzapw), and an **offline evaluation harness** (PII-gated corpus, self-test judge, gold-grader, real-pipeline runner behind a `ModelClient` seam) ([#4720](https://github.com/diegosouzapw/OmniRoute/pull/4720) — thanks @diegosouzapw). All four layers share a single `CompressionRunTelemetry` contract. - **Redoc-rendered API docs**: a consolidated OpenAPI spec now lives at `docs/openapi.yaml` and is served as interactive Redoc documentation at `/api/docs`. ([#4781](https://github.com/diegosouzapw/OmniRoute/pull/4781) — thanks @KooshaPari / @diegosouzapw) -### 🔧 Bug Fixes +### 🔧 问题修复 - **db-backups**: make the database-import size cap configurable via `OMNIROUTE_DB_IMPORT_MAX_MB` (default 100 MB, 4 GB ceiling) so backups larger than 100 MB can be restored; error message now points to the env var and to VACUUM ([#4757](https://github.com/diegosouzapw/OmniRoute/pull/4757) — closes #4719, thanks @diegosouzapw). - **Onboarding**: add the missing `onboarding.tiers` step-title translation so the setup wizard no longer crashes with `MISSING_MESSAGE: onboarding.tiers` ([#4755](https://github.com/diegosouzapw/OmniRoute/pull/4755) — closes #4698, thanks @diegosouzapw). @@ -623,7 +623,7 @@ _In development — bullets added per PR; finalized at release._ - **Tiers**: no-auth providers are now counted as free, and the free-tier filter returns an empty set instead of falling through to every provider ([#4753](https://github.com/diegosouzapw/OmniRoute/pull/4753) — thanks @megamen32 / @diegosouzapw). - **Combos**: auto-promote `zeroLatencyOptimizationsEnabled` so legacy configs (pre-3.8.33 `fallbackCompressionMode="lite"`) round-trip cleanly on the first GUI edit ([#4774](https://github.com/diegosouzapw/OmniRoute/pull/4774) — thanks @KooshaPari / @diegosouzapw). -### 📝 Maintenance +### 📝 维护 - **chatCore (#3501)**: continued the incremental decomposition of `executeProviderRequest` and the streaming/non-streaming hooks into pure leaf modules — top-level helpers + 6 pure leaves ([#4571](https://github.com/diegosouzapw/OmniRoute/pull/4571)), `resolveExecutorWithProxy` + `getExecutionCredentials` ([#4646](https://github.com/diegosouzapw/OmniRoute/pull/4646)), Claude message transforms ([#4708](https://github.com/diegosouzapw/OmniRoute/pull/4708)), `persistAttemptLogs` ([#4717](https://github.com/diegosouzapw/OmniRoute/pull/4717)), `stageTrace` + `compressionUsageReceipt` ([#4721](https://github.com/diegosouzapw/OmniRoute/pull/4721)), `prepareUpstreamBody` ([#4730](https://github.com/diegosouzapw/OmniRoute/pull/4730)), parse + non-streaming usage-stats ([#4762](https://github.com/diegosouzapw/OmniRoute/pull/4762)), `recordContextEditingTelemetryHook` ([#4779](https://github.com/diegosouzapw/OmniRoute/pull/4779)), `scheduleQuotaShareConsumption` ([#4780](https://github.com/diegosouzapw/OmniRoute/pull/4780)), `emitRequestGamificationEvent` ([#4776](https://github.com/diegosouzapw/OmniRoute/pull/4776)), `runPluginOnResponseHook` ([#4782](https://github.com/diegosouzapw/OmniRoute/pull/4782)), `scheduleStreamingQuotaShareConsumption` ([#4784](https://github.com/diegosouzapw/OmniRoute/pull/4784)), `recordCompressionCacheStats` ([#4792](https://github.com/diegosouzapw/OmniRoute/pull/4792)), `writeCavemanOutputAnalytics` ([#4794](https://github.com/diegosouzapw/OmniRoute/pull/4794)), `recordStreamingUsageStats` ([#4791](https://github.com/diegosouzapw/OmniRoute/pull/4791)), and `recordStreamingCost` ([#4790](https://github.com/diegosouzapw/OmniRoute/pull/4790)). (thanks @diegosouzapw) - **Quality**: expand `check:release-green` to reproduce the full release-PR gate set locally ([#4758](https://github.com/diegosouzapw/OmniRoute/pull/4758) — thanks @diegosouzapw). @@ -637,7 +637,7 @@ _In development — bullets added per PR; finalized at release._ ## [3.8.34] — 2026-06-23 -### ✨ New Features +### ✨ 新功能 - **feat(executors): Microsoft 365 Copilot pure framing + connection helpers** — adds the request/response framing and connection helpers to support `m365.cloud.microsoft/chat` for individual M365 plans. ([#4696](https://github.com/diegosouzapw/OmniRoute/pull/4696) — thanks @skyzea1 / @diegosouzapw) - **feat(compression): per-request `x-omniroute-compression` header (Phase 3)** — a request header now overrides the compression plan with the highest precedence (`request-header > routing > profile > auto-trigger > Default > off`), accepting `off` / `default` / `engine:` / ``. The response echoes `X-OmniRoute-Compression: ; source=`. ([#4645](https://github.com/diegosouzapw/OmniRoute/pull/4645) — thanks @diegosouzapw) @@ -682,7 +682,7 @@ _In development — bullets added per PR; finalized at release._ - **fix(dashboard): surface manual config CTA when Open Claw CLI auto-detect fails** — shows a manual-config call-to-action on the Open Claw CLI card when auto-detection fails. ([#4562](https://github.com/diegosouzapw/OmniRoute/pull/4562) — thanks @diegosouzapw) - **fix(oauth): update Qwen OAuth URLs from `chat.qwen.ai` to `qwen.ai`** — refreshes the Qwen OAuth endpoints (port of decolua/9router#683). ([#4561](https://github.com/diegosouzapw/OmniRoute/pull/4561) — thanks @diegosouzapw) -### 📝 Maintenance +### 📝 维护 - **refactor(imageGeneration): extract 8 provider families to co-located files** — splits the image-generation module into eight co-located per-provider files with no behavioral change. ([#4609](https://github.com/diegosouzapw/OmniRoute/pull/4609) — thanks @KooshaPari) - **deps: bump production + development groups; migrate js-yaml to v5 (ESM)** — dependency bumps plus a `js-yaml` v4→v5 migration to the ESM-only namespace import. ([#4697](https://github.com/diegosouzapw/OmniRoute/pull/4697) — thanks @diegosouzapw) @@ -703,7 +703,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.31] — 2026-06-20 -### ✨ New Features +### ✨ 新功能 - **perf(dashboard): combos UI leaf-split, Next.js config tuning, 1-click Redis & Bifrost sidecar** — delivers four of the five performance/UX tracks from the #3932 thread: the combos dashboard page is split into focused leaf components (smaller bundles, faster reloads), `next.config` is tuned for the standalone build, Redis can be provisioned in one click, and a Bifrost sidecar option is wired in. (The fifth track — chatLogHelpers extraction — was already covered upstream and dropped.) ([#4381](https://github.com/diegosouzapw/OmniRoute/pull/4381) — thanks @KooshaPari) @@ -728,12 +728,12 @@ _See English CHANGELOG for v3.8.32 details._ - **fix(api): persist `max_input_tokens` / `max_output_tokens` when adding a custom model** — `POST /api/provider-models` silently dropped the per-model token limits set in the "add custom model" form: the handler destructured the rest of the body but never read `max_input_tokens` / `max_output_tokens`, and `addCustomModel()` had no parameter for them, so the values were thrown away on write. The DB layer (`inputTokenLimit` / `outputTokenLimit`) and the `/v1/models` catalog already round-trip these fields — only the write path was missing. The validation schema now accepts the two optional limits, the handler forwards them, and `addCustomModel()` persists them so a custom model's context/output window survives into the catalog. ([#4349](https://github.com/diegosouzapw/OmniRoute/pull/4349) — thanks @codename-zen) - **fix(plugin): the OpenCode static-catalog plugin prefixes combo/raw model keys with the provider id** — OpenCode's static-catalog reader misdetected the `omniroute` provider: combo keys emitted as `combo/MASTER` were parsed as provider `combo` ("No credentials for provider: omniroute"), while a bare-`MASTER` form was misread as a model with no resolvable provider, and mixed `omniroute/MASTER` + bare-raw keys were rejected by OpenCode's schema. The plugin now emits every combo and raw model key prefixed with the `omniroute` provider id, emits the provider id explicitly, and drops the legacy `combo/` prefix — so the static-catalog reader detects the provider and the auth loader returns the right credentials (the catalog-fetch timeout was also raised so a cold-start server doesn't publish an empty stub). ([#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) — thanks @herjarsa) -### 🔒 Security +### 🔒 安全 - **fix(security): scope the OAuth callback `postMessage` to a trusted-origin allowlist** — the OAuth callback at `/callback` previously posted `{ code, state, … }` to `window.opener.postMessage(…, "*")` whenever the opener was cross-origin, so a hostile page that opened the well-known redirect URI in a popup could receive the OAuth code/state and complete the flow as the user. The wildcard fallback is replaced with iteration over a fixed allowlist (same-origin + Codex's `localhost:1455` / `127.0.0.1:1455` loopback helper); the browser silently drops `postMessage` to any opener whose origin isn't listed. ([#4372](https://github.com/diegosouzapw/OmniRoute/pull/4372) — ported from 9router#998, thanks @aeonframework / @diegosouzapw) - **fix(mitm): exact host membership in the MITM hosts test (CodeQL false positive)** — `tests/unit/mitm-tool-hosts.test.ts` checked host membership with `Array.includes(host)`, which CodeQL's `js/incomplete-url-substring-sanitization` heuristic misreads as a `String.includes()` URL-substring sanitization test (HIGH false positive). Switched to `.some((h) => h === host)` — identical semantics, no flagged pattern. ([#4386](https://github.com/diegosouzapw/OmniRoute/pull/4386)) -### 📝 Maintenance +### 📝 维护 - **docs: one-time feature-documentation catch-up (v3.8.20 → v3.8.30)** — reconciled the docs with every user-facing feature shipped since v3.8.20: a new README **✨ What's New** section; new guides for [CLI integrations](docs/guides/CLI-INTEGRATIONS.md), [MITM TPROXY transparent decrypt](docs/security/MITM-TPROXY-DECRYPT.md) and [delegated Anthropic Context Editing](docs/compression/CONTEXT_EDITING.md); refreshed AUTO-COMBO (`auto/:` + Arena-ELO), API_REFERENCE (`x-omniroute-no-memory`), MEMORY (int8 quantization, off-by-default), RESILIENCE (model-lockout success-decay), RTK, AGENTBRIDGE, TRAFFIC_INSPECTOR, GUARDRAILS, CLOUD_AGENT, ENVIRONMENT; regenerated PROVIDER_REFERENCE (231 providers) and synced the provider count in README/CLAUDE/AGENTS. Going forward this runs every release (generate-release step 6b). ([#4391](https://github.com/diegosouzapw/OmniRoute/pull/4391)) - **refactor(chatCore): extract the `checkHeapPressureGuard` leaf (god-file decomposition start)** — first increment of decomposing `chatCore.ts` (~5127 LOC, the hottest path — every chat request flows through `handleChatCore`). The V8 heap-pressure guard at the top of `handleChatCore` (rejects with 503 when `heapUsed` exceeds the shed threshold) is moved to a self-contained, co-located `utils/heapPressure.ts::checkHeapPressureGuard(...)` with no behavior change. ([#4371](https://github.com/diegosouzapw/OmniRoute/pull/4371) — thanks @diegosouzapw) @@ -748,7 +748,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.30] — 2026-06-20 -### ✨ New Features +### ✨ 新功能 - **feat(dashboard): category (media serviceKind) filter on the providers page** — `/dashboard/providers` gains a media-category filter row (Image / Video / Music / Text→Speech / Speech→Text / Embedding) that composes with the existing search, free-only and "show configured only" filters. Membership is derived from the backend media registries (a provider that serves a kind is surfaced even if it never declared `serviceKinds`), keeping the UI in lockstep with the backend. ([#4240](https://github.com/diegosouzapw/OmniRoute/issues/4240)) - **feat(combo): per-step account allowlist — scope a round-robin/weighted step to a subset of a provider's connections** — a combo model step can now carry a first-class account allowlist so a round-robin (or weighted) strategy is scoped to a chosen subset of a provider's connections (e.g. only `foo1`+`foo2` out of `foo1..foo4`) without hand-pinning one step per account. Empty = the whole active pool (unchanged). When a step both has an allowlist and is tag-routed, the two intersect (most-restrictive wins); a single pinned account still takes precedence. The combo builder's Precision step editor gains an optional "Restrict to accounts" picker. ([#3266](https://github.com/diegosouzapw/OmniRoute/issues/3266)) @@ -812,7 +812,7 @@ _See English CHANGELOG for v3.8.32 details._ - **test: align two tests left red by merged PRs** — re-aligns the db-rules classification count (#4335) and the LMArena split-cookie metadata test (#4271) after concurrent merges. ([#4346](https://github.com/diegosouzapw/OmniRoute/pull/4346)) - **test(ci): reconcile the release/v3.8.30 baseline + test drift** — reconciles quality baselines and drifted tests accumulated on the release branch. ([#4276](https://github.com/diegosouzapw/OmniRoute/pull/4276)) -### 📝 Maintenance +### 📝 维护 - **refactor(combo): `ComboContext` + extract `phaseComboSetup` (god-file split, phase 1)** — begins decomposing the combo god-file by extracting combo setup into a context object, without touching dispatch/semaphore logic. ([#4326](https://github.com/diegosouzapw/OmniRoute/pull/4326)) - **feat(quality): cap test-file size — anti-reinflation Layer 1** — freezes the existing god-tests and caps new test files at 800 lines to stop re-inflation. ([#4273](https://github.com/diegosouzapw/OmniRoute/pull/4273)) @@ -828,11 +828,11 @@ _See English CHANGELOG for v3.8.32 details._ - **docs: ban AI-generation footers in commits/PRs/CHANGELOG (Hard Rule #16)** — codifies the prohibition on AI-generation footers and bot co-author trailers. ([#4328](https://github.com/diegosouzapw/OmniRoute/pull/4328)) - **docs(design): add the OmniRoute design system and visual identity specification** — adds the design-system / visual-identity specification document. (thanks @diegosouzapw) -### 🔒 Security +### 🔒 安全 - **fix(sse): harden the DuckDuckGo lite scraper sanitization (CodeQL)** — closes four HIGH CodeQL alerts in the no-key web-search scraper: `decodeEntities` now resolves `&` **last** so an already-escaped entity (e.g. `&lt;`) survives as literal text instead of being double-unescaped (`js/double-escaping`); `stripTags` decodes entities first, then strips tags in a loop to a fixpoint and drops any trailing unclosed `<…`, so entity-encoded markup like `<script>` can never reach the LLM/client as a live tag (`js/incomplete-multi-character-sanitization`); and the host checks in the search tests use `new URL().hostname` equality instead of substring `.includes` (`js/incomplete-url-substring-sanitization`). ([#4356](https://github.com/diegosouzapw/OmniRoute/pull/4356)) -### 🔧 Dependencies +### 🔧 依赖 - **fix(deps): bump undici to 7.28.0 and dompurify to 3.4.11 (security)** — addresses the undici SOCKS5-TLS / cache advisories and the dompurify advisory. ([#4306](https://github.com/diegosouzapw/OmniRoute/pull/4306)) - **chore(deps): bump actions/checkout from 4 to 7** — CI checkout-action update. ([#4297](https://github.com/diegosouzapw/OmniRoute/pull/4297)) @@ -842,7 +842,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.29] — 2026-06-19 -### ✨ New Features +### ✨ 新功能 - **feat(cloud-agent): Cursor Cloud Agent via the official API-key REST API (no IDE-OAuth ban risk)** — adds a `cursor-cloud` cloud agent that drives Cursor's Background / Cloud Agents through the official REST API (`api.cursor.com`) authenticated with a user or service-account API key — the safer, first-party alternative to re-using the Cursor IDE's OAuth session (the existing `cursor` provider, which carries a ban-risk warning). Implemented as a plain REST adapter mirroring the Devin/Jules agents (`createTask`/`getStatus`/`sendMessage`/`listSources`), so it does **not** pull in the `@cursor/sdk` package and its per-platform native binaries (Cursor's SDK is itself a thin wrapper over this REST API). Cursor's UPPERCASE status enums (`CREATING`/`RUNNING`/`FINISHED`/`ERROR`) are mapped explicitly to the shared `CloudAgentStatus`, and `baseUrl` is overridable per-credential. Credentials are stored encrypted via the existing `cloud_agent_credentials` table; no schema change. ([#4227](https://github.com/diegosouzapw/OmniRoute/issues/4227) — thanks @MRDGH2821) - **feat(routing): OpenRouter-style `auto/:` combos** — auto-routing now understands suffixed combos that separate the _category_ (what kind of route) from the _tier_ (how to optimize): `auto/coding:fast`, `auto/coding:cheap` (alias `:floor`), `auto/coding:free`, `auto/coding:pro`, `auto/coding:reliable`, plus the new category roots `auto/reasoning`, `auto/vision`, `auto/multimodal`. The **tier** picks the scoring weights — `:fast` → ship-fast, `:cheap`/`:floor` → cost-saver, `:reliable` → a new reliability-first pack (circuit-breaker health + latency stability) — while `:free`/`:pro` filter the candidate pool by model tier (`classifyTier`: free-tier vs. premium models). The **category** filters the pool by capability (`vision`/`multimodal` → vision-capable models, `reasoning` → reasoning/thinking models). Any valid `auto/:` resolves on demand; a curated set is advertised in `/v1/models` and the dashboard. Filtering is fail-open — if a constraint matches no connected models the full pool is used so routing never breaks. All composition lives in the new `open-sse/services/autoCombo/suffixComposition.ts`; the core combo scorer (`combo.ts`) is untouched. Second slice of #4235 (premium account-tier weighting is a later follow-up). ([#4235](https://github.com/diegosouzapw/OmniRoute/issues/4235) — thanks @MRDGH2821) @@ -944,7 +944,7 @@ _See English CHANGELOG for v3.8.32 details._ - **test(db,sse): de-flake db-backup + chatcore streaming timing assertions** — stabilizes two timing-sensitive tests (fire-and-forget backup completion + a streaming race). ([#4132](https://github.com/diegosouzapw/OmniRoute/pull/4132)) - **test: align stale integration tests surfaced post-v3.8.28 on main** — realigns integration tests that drifted after the v3.8.28 merge. ([#4129](https://github.com/diegosouzapw/OmniRoute/pull/4129)) -### 📝 Maintenance +### 📝 维护 - **refactor(sse): split chatCore.ts pure helpers into chatCore/ modules (−561 LOC)** — extracts pure helpers out of the chatCore god-file into dedicated modules (Onda 3). ([#4159](https://github.com/diegosouzapw/OmniRoute/pull/4159)) - **refactor(chatcore): extract passthrough/header/telemetry helpers (QG v2 Fase 9 T5 C2-C3-C5)** — further chatCore decomposition. ([#4188](https://github.com/diegosouzapw/OmniRoute/pull/4188)) @@ -970,7 +970,7 @@ _See English CHANGELOG for v3.8.32 details._ - **docs(readme): expand Acknowledgments into a themed, star-counted credits hall** — reworks the README acknowledgments section. ([#4195](https://github.com/diegosouzapw/OmniRoute/pull/4195)) - **style(dashboard): shrink the identity grid cell 46px → 32px (~30% smaller)** — tightens the identity grid density. ([#4143](https://github.com/diegosouzapw/OmniRoute/pull/4143)) -### 🔧 Dependencies +### 🔧 依赖 - **deps: bump the production group with 5 updates** — routine production-dependency bumps. ([#4121](https://github.com/diegosouzapw/OmniRoute/pull/4121)) - **chore(deps): bump github/codeql-action from 3 to 4** — CI action update. ([#4120](https://github.com/diegosouzapw/OmniRoute/pull/4120)) @@ -980,7 +980,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.28] — 2026-06-17 -### ✨ New Features +### ✨ 新功能 - **feat(providers): add OrcaRouter (OpenAI-compatible routing gateway)** — OrcaRouter is now registered as an API-key provider. Its adaptive router is exposed as `orcarouter/auto` (smart routing across 150+ upstream models), alongside a curated flagship set (GPT-5.5, Gemini 3.5 Flash, Claude Opus 4.8, Grok 4.3, DeepSeek V4 Pro, MiniMax M2.7, Qwen3.7 Max). `passthroughModels` is enabled so any OrcaRouter model id works. OpenAI-compatible endpoint (`https://api.orcarouter.ai/v1`), Bearer (`sk-orca-…`) auth — no custom executor or translator required. ([#4070](https://github.com/diegosouzapw/OmniRoute/pull/4070) — thanks @jinhaosong-source) - **feat(providers): add Wafer AI (Anthropic-compatible, Bearer auth)** — Wafer AI is now a built-in provider speaking the Anthropic Messages format with Bearer authentication, registered with its model catalog so it works out of the box. ([#4098](https://github.com/diegosouzapw/OmniRoute/pull/4098) — thanks @diegosouzapw) @@ -1021,14 +1021,14 @@ _See English CHANGELOG for v3.8.32 details._ - **fix(combo): detach the per-target listener from the shared hedge abort signal** — combo hedging attached a per-target listener to a shared abort signal without detaching it, leaking listeners across requests; the listener is now detached. ([#4116](https://github.com/diegosouzapw/OmniRoute/pull/4116) — thanks @artickc) - **fix(timers): unref background interval timers so they don't block clean shutdown** — long-lived background interval timers kept the event loop alive and blocked a clean process exit; they are now `unref`'d. ([#4117](https://github.com/diegosouzapw/OmniRoute/pull/4117) — thanks @artickc) -### ⚡ Performance +### ⚡ 性能优化 - **perf(registry): precompute the model→provider index in `parseModelFromRegistry`** — model→provider lookups now use a precomputed index instead of scanning the registry on every call. ([#4110](https://github.com/diegosouzapw/OmniRoute/pull/4110) — thanks @artickc) - **perf(obfuscation): cache per-word regexes instead of recompiling every request** — the obfuscation pass now caches its per-word regexes rather than recompiling them on each request. ([#4109](https://github.com/diegosouzapw/OmniRoute/pull/4109) — thanks @artickc) - **perf(stream): use `structuredClone` instead of a JSON round-trip for per-chunk reasoning split** — the per-chunk reasoning split now clones with `structuredClone` rather than `JSON.parse(JSON.stringify(...))`. ([#4108](https://github.com/diegosouzapw/OmniRoute/pull/4108) — thanks @artickc) - **perf(gemini): cache the reasoning close-tag regex instead of recompiling per token** — the Gemini reasoning close-tag regex is now compiled once and reused instead of per token. ([#4106](https://github.com/diegosouzapw/OmniRoute/pull/4106) — thanks @artickc) -### 📝 Maintenance +### 📝 维护 - **ci(quality): flip the TIA impacted-unit-tests gate from advisory to blocking (Fase 9)** — the test-impact-analysis gate that runs the unit tests impacted by a diff is now blocking on PRs. ([#4069](https://github.com/diegosouzapw/OmniRoute/pull/4069) — thanks @diegosouzapw) - **ci(quality): dedup the doubly-run `check:docs-sync` + record the validated ROI backlog (Fase 9)** — `check:docs-sync` was running twice in CI; the duplicate was removed and the validated quality-gate ROI backlog recorded. ([#4099](https://github.com/diegosouzapw/OmniRoute/pull/4099) — thanks @diegosouzapw) @@ -1040,7 +1040,7 @@ _See English CHANGELOG for v3.8.32 details._ - **chore(docs): update the Discord invite link to a non-expiring one** — replaces the expiring Discord invite with a permanent link. ([#4067](https://github.com/diegosouzapw/OmniRoute/pull/4067) — thanks @diegosouzapw) - **chore(docs): document the new MITM env vars + reconcile the env-doc contract** — documents `MITM_IDLE_TIMEOUT_MS` and `MITM_VERBOSE` in `.env.example` + `ENVIRONMENT.md`, allowlists the framework-internal `TURBOPACK` and the Claude Code `ANTHROPIC_AUTH_TOKEN`, and relocates/prunes stale provider/guide docs. (thanks @diegosouzapw) -### 🔧 Dependencies +### 🔧 依赖 - **deps: bump the development group with 10 updates** — routine dependabot dev-dependency bumps. ([#4051](https://github.com/diegosouzapw/OmniRoute/pull/4051)) - **deps(electron): bump electron 42.4.0 → 42.4.1** — ([#4049](https://github.com/diegosouzapw/OmniRoute/pull/4049)) @@ -1054,7 +1054,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.27] — 2026-06-17 -### ✨ New Features +### ✨ 新功能 - **feat(combos): advertise combo capabilities (multimodal / reasoning / caching) on the import surfaces** — importing a combo package into a client (LobeHub / OpenCode / VS Code, via `/v1/combos` and the VS Code combo catalog) no longer requires manually enabling multimodal/image-input, reasoning, and caching afterwards. `projectCombo` now attaches a registry-derived `capabilities` block, gated conservatively: `multimodal`/`reasoning` are advertised only when **every** concrete model step proves the capability (an unprovable nested combo-ref drops them, since the strategy may route to any member), and `caching` reflects the combo's explicit Context-Cache-Protection setting (no surprise prompt-cache cost). The public `/v1/combos` default projection (#2300) is unchanged unless the caller opts in. ([#3979](https://github.com/diegosouzapw/OmniRoute/issues/3979) — thanks @xenstar) - **feat(sse): delegated Anthropic Context Editing for Claude (`clear_tool_uses`)** — Claude requests can now offload context trimming to Anthropic's server-side context-management API (beta `context-management-2025-06-27`, `clear_tool_uses_20250919`), pruning stale tool-use turns upstream instead of locally. Claude-only by nature (the edit runs server-side); multi-provider context trimming remains the job of the local compression engines. ([#4021](https://github.com/diegosouzapw/OmniRoute/pull/4021) — thanks @diegosouzapw) @@ -1093,7 +1093,7 @@ _See English CHANGELOG for v3.8.32 details._ - **fix(dashboard): refine the provider quota card display** — the provider quota card layout was refined for clearer quota/usage presentation. ([#3969](https://github.com/diegosouzapw/OmniRoute/pull/3969) — thanks @rdself) - **fix(dashboard): refine compression settings, storage labels, and sidebar grouping** — polishes the compression-settings UI, clarifies storage labels, and tidies the sidebar grouping. ([#4033](https://github.com/diegosouzapw/OmniRoute/pull/4033) — thanks @rdself) -### 🔒 Security & Hardening +### 🔒 安全 & Hardening - **fix(security): eliminate a polynomial ReDoS in the combo `` tag regex** — `comboAgentMiddleware`'s cache-tag pattern wrapped the tag in an unbounded newline run (`(?:\n|\r)*`), making `.test()` / `.replace()` run in O(n²) on inputs with many newlines (CodeQL `js/polynomial-redos`). The detection pattern now matches only the core `…` and the global strip pattern bounds the surrounding newline runs, keeping it linear; detection / extraction / multi-tag stripping behavior is unchanged. ([#3982](https://github.com/diegosouzapw/OmniRoute/pull/3982) — thanks @diegosouzapw) - **ci(security): harden workflows — artipacked `persist-credentials`, cache-poisoning, SC2086** — GitHub Actions workflows were hardened against the artipacked `persist-credentials` leak and cache-poisoning, and shell-quoting (`SC2086`) issues were fixed. ([#3965](https://github.com/diegosouzapw/OmniRoute/pull/3965) — thanks @diegosouzapw) @@ -1120,7 +1120,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.26] — 2026-06-15 -### ✨ New Features +### ✨ 新功能 - **feat(media): Vertex AI (Google) speech, transcription, music & video generation** — Vertex AI's Google media models are now routable through dynamic discovery: speech synthesis, audio transcription, music generation, and video generation. ([#3929](https://github.com/diegosouzapw/OmniRoute/pull/3929) — thanks @artickc) - **feat(glm): add GLM-5.2 with effort-tier routing (high/max)** — GLM-5.2 is registered with high/max effort-tier routing. ([#3885](https://github.com/diegosouzapw/OmniRoute/pull/3885) — thanks @dhaern) @@ -1149,7 +1149,7 @@ _See English CHANGELOG for v3.8.32 details._ - **fix(models): correct the generate-models alias lookup** — alias resolution during model generation was corrected so aliased model ids resolve to their canonical entry. ([#3870](https://github.com/diegosouzapw/OmniRoute/pull/3870) — thanks @YunyunZhai) - **fix(combo): guard the candidate pool against an empty array** — combo candidate-pool selection no longer throws when the pool resolves to an empty array. ([#3871](https://github.com/diegosouzapw/OmniRoute/pull/3871) — thanks @YunyunZhai) -### 🔒 Security & Hardening +### 🔒 安全 & Hardening - **fix(security): bump form-data + vite (2 HIGH), harden workflow template-injection & allowlist guarded `workflow_run`** — two HIGH Dependabot advisories (`form-data`, `vite`) were upgraded; GitHub Actions workflows were hardened against `${{ }}` template-injection (untrusted values now passed via `env:`); and the guarded `workflow_run` trigger was allowlisted. ([#3949](https://github.com/diegosouzapw/OmniRoute/pull/3949) — thanks @diegosouzapw) @@ -1179,7 +1179,7 @@ _See English CHANGELOG for v3.8.32 details._ ## [3.8.25] — 2026-06-14 -### ✨ New Features +### ✨ 新功能 - **feat(compression): pluggable compression engines + async pipeline + Compression Studios** — a new prompt-compression subsystem with selectable engines (Lite / Aggressive / Ultra), an asynchronous compression pipeline wired into the chat core, and "Compression Studios" tooling for inspecting and tuning compression. ([#3848](https://github.com/diegosouzapw/OmniRoute/pull/3848)) - **feat(compression-ui): unified compression configuration UI** — a Compression Hub with per-engine pages (Lite / Aggressive / Ultra), a combos editor, a dedicated sidebar entry, and live-WS default-on. ([#3860](https://github.com/diegosouzapw/OmniRoute/pull/3860)) @@ -1220,7 +1220,7 @@ _See English CHANGELOG for v3.8.32 details._ - **fix(ui): expand the request log table with a vertical resize handle** — the request log table now shows ~10 rows and can be resized vertically. ([#3820](https://github.com/diegosouzapw/OmniRoute/pull/3820) — thanks @rafacpti23) - **fix(i18n): translate the missing `embeddedServices` keys across 37 locales** — the `embeddedServices` strings showed `__MISSING__` in 37 locales; they are now translated. ([#3819](https://github.com/diegosouzapw/OmniRoute/pull/3819) — thanks @rafacpti23) -### 🔒 Security & Hardening +### 🔒 安全 & Hardening - **fix(security): CCR cross-tenant IDOR — per-principal scope store + bounded memory** — the compression CCR scope store was shared across principals, allowing cross-tenant reads; it is now scoped per-principal with bounded memory. ([#3859](https://github.com/diegosouzapw/OmniRoute/pull/3859)) - **feat(supply-chain): build provenance, SBOM, Trivy scan & OpenSSF Scorecard (advisory)** — added npm build provenance, a CycloneDX SBOM, Trivy image scanning, and an OpenSSF Scorecard workflow (Quality Gates Fase 8 · Bloco A, advisory). ([#3824](https://github.com/diegosouzapw/OmniRoute/pull/3824)) @@ -1550,13 +1550,13 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.7] — 2026-05-29 -### ✨ New Features +### ✨ 新功能 - **api (self-service):** add `GET /api/v1/me/status` so a delegated API key can view its own usage (USD used, budget percent, token totals) and optional shared Codex account quota, backed by migration `075_api_key_self_service_usage_scopes` (#2908 — thanks @guanbear). - **analytics:** roll up usage logs to `daily_usage_summary` before raw log cleanup, and query a SQL `UNION` of raw and rolled-up data to prevent analytics history data loss (#2904 — thanks @unitythemaker). - **perf (RAM):** reduce server memory footprint by capping 11 in-memory caches, limiting SQLite page cache, lazy-loading provider registries via Proxy, and optimizing Next.js startup database probes (#2903 — thanks @soyelmismo). -### 🔧 Bug Fixes +### 🔧 问题修复 - **token-accounting:** prefer `prompt_tokens` over compatibility `input_tokens` for Anthropic Claude streams to avoid double-counting cached tokens (#2904 — thanks @unitythemaker). @@ -1570,13 +1570,13 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **log-export:** `GET /api/logs/export?type=proxy-logs` returns raw SQLite rows whose IP field is still named `public_ip` (the historical column name). This differs from the `clientIp` field exposed by `GET /api/usage/proxy-logs`. The two endpoints are intentionally inconsistent for now and will be aligned in a future migration (#2880). -### ✨ New Features +### ✨ 新功能 - **usage:** add per-API-key token limits scoped to model/provider/global with two-tier inline enforcement and in-memory cache accelerator (#2888 — thanks @mugnimaestra). - **providers:** audit web cookie providers, fix 4 missing registry entries, and add DuckDuckGo AI Chat provider (#2862 — thanks @oyi77). - **compression:** expand pt-BR pack with 34 new rules inspired by the troglodita project (#2818 — thanks @leninejunior). -### 🔧 Bug Fixes +### 🔧 问题修复 - **oauth:** hotfix Windsurf login — drop dead PKCE flow, promote import-token, and resolve SQLite bind type errors (#2884 — thanks @yunaamelia). - **models:** prune stale synced available models for inactive connections and dynamically map Antigravity MITM aliases loop-safely (#2886 — thanks @herjarsa). @@ -1606,11 +1606,11 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.5] — 2026-05-26 -### 🔒 Security +### 🔒 安全 - **authz:** redirect `/home` and `/home/:path*` to `/login` when unauthenticated (#2712) -### 🔧 Bug Fixes +### 🔧 问题修复 - **mcp:** break callLogs ↔ compliance ESM cycle that deadlocks the bundled MCP server on Node.js 24 (#2650) - **deepseek:** guard PoW solver Web Worker handler under Node strict mode (#2724) @@ -1631,9 +1631,9 @@ must be a response to a preceding message with 'tool_calls'` when a Codex --- -### ✨ New Features +### ✨ 新功能 -### 🔧 Bug Fixes +### 🔧 问题修复 --- @@ -1647,7 +1647,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.3] — 2026-05-24 -### ✨ New Features +### ✨ 新功能 - **feat(combos):** universal context handoff for cross-model conversation continuity — structured XML summary system (``) that preserves conversation continuity and handles state transfer when combo routing switches models. ([#2653](https://github.com/diegosouzapw/OmniRoute/pull/2653) — thanks @herjarsa) - **feat(docs):** migrate `/docs` to Fumadocs MDX with nested routes — replaces the custom docs engine with Fumadocs, adding `[...slug]` catch-all routing, search API at `/docs/api/search`, `source.config.ts` content configuration, and `meta.json` navigation files across 8 doc sections (`architecture/`, `compression/`, `frameworks/`, `guides/`, `ops/`, `reference/`, `routing/`, `security/`). Includes 50+ URL redirects for backward compatibility via `next.config.mjs`. ([#2614](https://github.com/diegosouzapw/OmniRoute/pull/2614) — thanks @ovehbe) @@ -1660,7 +1660,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **feat(adapta):** integrate Adapta Org (`adapta-web`) provider with automatic Clerk authentication refresh and custom onboarding tutorial modal. ([#2643](https://github.com/diegosouzapw/OmniRoute/pull/2643) — thanks @df4p) - **feat(i18n):** complete translations for Simplified Chinese — translates 1220 missing keys bringing UI coverage to 98.8% with 0 placeholders. ([#2655](https://github.com/diegosouzapw/OmniRoute/pull/2655) — thanks @L-aros) -### 🔧 Bug Fixes +### 🔧 问题修复 - **fix(settings):** Require Login modal Cancel button text and dismissal — modal now renders localized cancel label via the `common` namespace and closes correctly without modifying settings when cancelled. ([#2649](https://github.com/diegosouzapw/OmniRoute/pull/2649) — thanks @Chewji9875) - **fix(deepseek-web):** re-apply SSE parser, prompt format, and error handling fixes — handles all 3 DeepSeek SSE stream formats (initial fragments, APPEND operations, bare string tokens), uses non-greedy regex for markdown image stripping, simplifies prompt to single-turn, checks `json.code` before token extraction, and uses `accessToken` fallback for session cache eviction on auth errors. ([#2616](https://github.com/diegosouzapw/OmniRoute/pull/2616) — thanks @ovehbe) @@ -1680,7 +1680,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **fix(translator):** enable Claude extended thinking for Copilot Responses-API requests — handles reasoning budget and translations for Copilot. ([#2647](https://github.com/diegosouzapw/OmniRoute/pull/2647) — thanks @ivan-mezentsev) - **fix(tests):** remove duplicate assertion in schema coercion & fix(cli): ignore system vars in env check. (thanks @diegosouzapw) -### 📝 Maintenance +### 📝 维护 - **chore(config):** ignore additional agent workflow command files (`.agents/commands/`). (thanks @diegosouzapw) - **chore(config):** ignore `memory-bank` and Cursor agent rules from tracking. (thanks @ovehbe) @@ -1689,7 +1689,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.2] — 2026-05-22 -### ✨ New Features +### ✨ 新功能 - **feat(@omniroute/opencode-plugin):** upstream-provider suffix in model display name — appends provider label to enriched names (e.g. `Claude Opus 4.7 · Claude` vs `Claude Opus 4.7 · Kiro`) so the OC TUI model picker can differentiate same-id models routed through different upstream connections. Default-on, opt-out via `features.providerTag: false`. ([#2602](https://github.com/diegosouzapw/OmniRoute/pull/2602) — thanks @mrmm) - **feat(@omniroute/opencode-plugin):** provider-tag becomes a prefix + traffic-light compression emoji — provider label now prepends (`Claude - Claude Opus 4.7`) for better TUI column grouping, with smart abbreviation for long labels (`GitHub Models` → `GHM`). Compression pipelines render intensity as emoji (🟢🟡🟠🔴). ([#2604](https://github.com/diegosouzapw/OmniRoute/pull/2604) — thanks @mrmm) @@ -1713,7 +1713,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **feat(providers):** add api-airforce free provider with 55 models. ([#2587](https://github.com/diegosouzapw/OmniRoute/pull/2587) — thanks @oyi77) - **feat(dashboard):** configurable sidebar — presets, drag-and-drop ordering, smart-grouping, and new Settings → Sidebar page. ([#2581](https://github.com/diegosouzapw/OmniRoute/pull/2581) — thanks @Gi99lin) -### 🔧 Bug Fixes +### 🔧 问题修复 - **fix(validation):** stop appending a second `/models` when the Gemini base URL already ends in `/models` — Google AI Studio connections using the default base URL were validating against `.../v1beta/models/models` and failing with `404` for every connection. ([#2545](https://github.com/diegosouzapw/OmniRoute/issues/2545)) - **fix(cloudflare-ai):** flatten OpenAI content-part arrays to plain strings for the Workers AI (`cf/`) executor — Workers AI's `/ai/v1/chat/completions` rejects `content: [{type:"text",...}]` with HTTP 400, so requests with array content now have their text parts joined into a string. ([#2539](https://github.com/diegosouzapw/OmniRoute/issues/2539)) @@ -1798,7 +1798,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **i18n(all):** translate freeTier provider strings across 41 locales — replaces `__MISSING__:Free Tier Providers` placeholders with proper translations in both `common` and `providers` namespaces. ([#2609](https://github.com/diegosouzapw/OmniRoute/pull/2609) — thanks @leninejunior) - **i18n(pt-BR):** eliminate all 1270 remaining `__MISSING__` markers — completes pt-BR translation across 41 namespaces to true 100% coverage. ([#2610](https://github.com/diegosouzapw/OmniRoute/pull/2610) — thanks @leninejunior) -### 📝 Maintenance +### 📝 维护 - **chore:** remove Akamai VPS deploy from release workflow and skills. - **chore(deps):** bump `actions/setup-node` from v4 to v6 + `randomBytes` security fix for cloud agent task IDs. ([#2589](https://github.com/diegosouzapw/OmniRoute/pull/2589)) @@ -1811,7 +1811,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.1] — 2026-05-21 -### ✨ New Features +### ✨ 新功能 - **feat(settings):** Feature Flags Settings Page (Card Grid + DB overrides) — fully implements the feature flags UI dashboard using Variant A (Card Grid) with Glassmorphism, complete with global `GET/PUT/DELETE` API routes, Zod validation, debounced search, category filters, and full 30+ locale i18n support. Resolves priority hierarchy to DB > ENV > Defaults. ([#2457](https://github.com/diegosouzapw/OmniRoute/pull/2457)) - **feat(db):** multi-driver SQLite abstraction layer — new `SqliteAdapter` interface with 3 concrete adapters (`betterSqliteAdapter`, `nodeSqliteAdapter`, `sqljsAdapter`) and a `driverFactory` that cascades `better-sqlite3` → `node:sqlite` → `sql.js (WASM)`. Enables OmniRoute to run on any JavaScript runtime (Node.js, Bun, Deno, Cloudflare Workers) without native binary dependencies. `better-sqlite3` moved to `optionalDependencies`. ([#2447](https://github.com/diegosouzapw/OmniRoute/pull/2447)) @@ -1821,7 +1821,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **feat:** enhance `extractBearer` to support `x-api-key` for Anthropic API style auth. ([#2436](https://github.com/diegosouzapw/OmniRoute/pull/2436) — thanks @thedtvn) - **feat(memory):** wire `createMemory` to `upsertSemanticMemoryPoint` (Qdrant). ([#2439](https://github.com/diegosouzapw/OmniRoute/pull/2439) — thanks @NomenAK) -### 🔧 Bug Fixes & Refactors +### 🔧 问题修复 & Refactors - **fix(deepseek-web):** rewrite auth to userToken Bearer + WASM PoW solver. ([#2452](https://github.com/diegosouzapw/OmniRoute/pull/2452) — thanks @ovehbe) - **chore:** update node dependencies and runtime support. ([#2453](https://github.com/diegosouzapw/OmniRoute/pull/2453) — thanks @backryun) @@ -1836,7 +1836,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **docs(agentrouter):** recommend native provider as the simple path — guide now prefers the built-in AgentRouter provider instead of manual OpenAI-compatible configuration. ([#2429](https://github.com/diegosouzapw/OmniRoute/pull/2429) — thanks @leninejunior) - **feat(settings):** surface Codex Fast Tier toggle in Settings › AI — companion UI toggle for the Codex Fast Tier feature. ([#2440](https://github.com/diegosouzapw/OmniRoute/pull/2440) — thanks @NomenAK) -### 🔒 Security Fixes +### 🔒 安全 Fixes - **fix(security):** replace `execSync` string-template with `spawnSync` arg-array in `plugin.mjs` — eliminates shell command injection via malicious plugin names. - **fix(security):** gate Electron CSP `unsafe-eval` on `!app.isPackaged` instead of URL substring match — was leaking `unsafe-eval` into production builds; merged duplicate `connect-src` directives. @@ -2230,7 +2230,7 @@ Thanks also to **@app/dependabot** for keeping our dependency tree current via # ### Detalhes completos — features e fixes do lançamento (2026-05-06 a 2026-05-14) -#### ✨ New Features +#### ✨ 新功能 - **feat(providers):** add Command Code provider (#2199 — thanks @ddarkr) - **feat(providers):** add ModelScope provider-specific 429 handling and retry logic (#2202 — thanks @InkshadeWoods) @@ -2277,7 +2277,7 @@ Thanks also to **@app/dependabot** for keeping our dependency tree current via # - **feat(antigravity):** support custom Google Cloud project ID for Antigravity provider (#2227 — thanks @nickwizard) - **feat(cli):** CLI Integration Suite — 5 new management commands (`config`, `status`, `logs`, `update`, `provider`), 3 API endpoints, config generators for 6 tools (Claude, Cline, Codex, Continue, KiloCode, OpenCode), zero-config `auto/` routing, and `@omniroute/opencode-provider` npm package (#2240 — thanks @oyi77) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(pricing):** make `getPricingForModel` fully case-insensitive to ensure custom prices correctly reflect in new incoming requests cost calculations - **fix(gemini):** prevent `functionDeclarations` from being dropped by the sanitizer when `googleSearch` tool is present (#2077) @@ -2365,14 +2365,14 @@ Thanks also to **@app/dependabot** for keeping our dependency tree current via # - **fix(api):** validate model cooldown delete payload - **fix(ci):** run coverage gate serially, align resilience and thinking checks, align cloud code thinking and model catalog tests -### 🔒 Security +### 🔒 安全 - **fix(security):** remediate CodeQL vulnerabilities (ReDoS, cryptographic bias, stack trace exposure, and weak password hashing) (#216, #215, #211, #208, #206, #210) - **fix(security):** sanitize error messages in API routes to prevent stack trace exposure (CodeQL js/stack-trace-exposure) (#2209) - **fix(security):** remediate regex validation backtracking path in core compression cleanup (#1990) - **fix(core):** harden input handling and stabilization for prompt compression edge cases -### 📝 Documentation +### 📝 文档 - **docs:** add competitive marketing tables and SEO/AEO optimizations to README (#2091) - **docs:** refresh providers, model catalogs, and docs for v3.8.0 (#2088) @@ -2469,7 +2469,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 ## [3.7.9] — 2026-05-03 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2496,7 +2496,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 - **feat(usage):** DeepSeek V4 native cache token extraction (#1930 — thanks @smartenok-ops) - **feat(cost):** enhance cost formatting and add Codex GPT-5.5 pricing support (#1944 — thanks @JxnLexn) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(auth):** implement session affinity sticky routing logic - **fix(dashboard):** derive display base URL from origin instead of hardcoding localhost (#1960 — thanks @jeanfbrito) @@ -2535,7 +2535,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 - **chore(provider):** Add reka models list (#1956 — thanks @backryun) - **chore(model):** Update new models, Delete Deprecated models (#1949 — thanks @backryun) -### 📝 Documentation +### 📝 文档 - **docs(compression):** document RTK+Caveman stacked savings ranges @@ -2547,7 +2547,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 ## [3.7.8] — 2026-05-01 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2561,7 +2561,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 - **feat(providers):** add muse-spark-web provider with multiple models and reasoning support (#1843) - **feat(1proxy):** integrate 1proxy free proxy marketplace with dashboard management and new MCP tools (closes #1788) (#1847) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(codex):** sanitize Responses replay state to prevent internal assistant commentary from leaking (#1868 — thanks @dhaern) - **fix(cli):** add capture-backed Gemini CLI fingerprint (#1866) @@ -2586,7 +2586,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 ## [3.7.7] — 2026-04-30 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2600,7 +2600,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 - **Compression Caching & MCP:** Added caching-aware strategy adjustments to the compression pipeline, alongside new MCP tools for status and configuration (#1758) - **Analytics Custom Filters:** Added custom date range selection, API key filtering, and NULL key analytics backfilling to the Costs Dashboard (#1830) -### 🐛 Bug Fixes +### 🐛 问题修复 - **Combo Routing:** Fixed an issue where Gemini `-preview` models were incorrectly normalized to their canonical names, causing 404 errors during combo routing (#1834) - **Codex Native Passthrough:** Added support for Cursor 5.5 sending `messages` arrays to the `responses/compact` endpoint, preventing upstream rejections with empty requests (#1832) @@ -2618,7 +2618,7 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 ## [3.7.6] — 2026-04-30 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2634,11 +2634,11 @@ Thank you to all **55+ community contributors** who made v3.8.0 possible! 🎉 - **feat(db):** auto-restore probe-failed database on startup to prevent data loss after failed upgrades (#1810) - **feat(analytics):** add cost-based usage insights and activity streaks in the analytics dashboard -### 🔒 Security +### 🔒 安全 - **fix(security):** resolve ReDoS vulnerability in Codex executor regex patterns (#1797, #1789) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(stability):** resolve codex input validation, enable combo circuit breaker, and fix broken unit tests (#1804, #1805) - **fix(stability):** safely cast inputs to strings before calling `.trim()` to avoid crashes on numeric fields in proxy modal (#1825) @@ -2721,7 +2721,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.5] — 2026-04-29 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2732,7 +2732,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(tunnels):** integrate native ngrok tunnel support with dashboard UI parity (#1753) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(dashboard):** add manual 'Clear All' button to terminate stalled long-running requests in Active Requests panel (#1799) - **fix(schema):** remove empty string values from optional tool parameters to prevent upstream validation errors (#1674) @@ -2773,7 +2773,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.4] — 2026-04-28 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2787,11 +2787,11 @@ We identified that **155 community PRs** across the entire project history (from - **feat(proxy):** implement bulk proxy import via pipe-delimited parser with update-or-create (upsert) logic and real-time preview table - **feat(pwa):** add fullscreen installable PWA with manifest, service worker, and cross-platform app icons (#1728) -### 🔒 Security +### 🔒 安全 - **security:** replace insecure `Math.random` with `crypto.getRandomValues` for fallback UUID generation to resolve CodeQL CWE-338 finding (#182) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(cc-compatible):** fix CC-compatible relay format and UI copy (#1742) - **fix(codex):** normalize max reasoning effort for Codex routing (#1744) @@ -2816,7 +2816,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.3] — 2026-04-28 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(claude):** strip existing billing headers from system array before injecting to prevent Anthropic prompt cache misses — stacked `x-anthropic-billing-header` blocks invalidated prefix matching, causing ~100% cache_create instead of cache_read (#1712) - **fix(claude):** strip `output_config.format` for non-Anthropic Claude-compatible providers during passthrough — third-party Claude endpoints (MiniMax, DeepSeek via aggregators) reject structured output fields with 400 errors (#1719) @@ -2836,7 +2836,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.2] — 2026-04-28 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2851,7 +2851,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(codex):** enable native Codex websocket responses on beta-gated models (#1658) - **feat(muse-spark-web):** continue the same meta.ai conversation across turns (#1673) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(responses):** sanitize empty string placeholders from tool-call optional arguments in stream delta accumulation to avoid breaking strict clients (#1674) - **fix(codex):** prevent unexpected protocol leakage and fabricated instructions on bare chat completion requests without tools (#1686) @@ -2912,7 +2912,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.1] — 2026-04-26 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -2925,7 +2925,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(cli):** Add `omniroute reset-encrypted-columns` recovery command — nulls encrypted credential columns (`api_key`, `access_token`, `refresh_token`, `id_token`) in `provider_connections` while preserving provider metadata, giving users affected by #1622 a clean recovery path without losing configurations. - **feat(i18n):** Expand locale coverage with nine new language packs (Bengali, Farsi, Gujarati, Indonesian, Marathi, Swahili, Tamil, Telugu, Urdu), bringing total language support from 32 to 41 locales. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(rate-limit):** Add per-model rate limiting for GitHub Copilot provider — a 429 on one model (e.g. `gpt-5.1-codex-max`) no longer locks the entire connection, matching the existing Gemini per-model quota pattern (#1624 — thanks @slewis3600). - **fix(cli-tools):** Preserve existing OpenCode configuration (MCP servers, custom providers, comments) when saving OmniRoute settings — uses `jsonc-parser` for tree-preserving edits instead of destructive JSON roundtrip. Fix API key clipboard copy to use raw keys instead of masked placeholders. Add theme-aware OpenCode light/dark SVG logos (#1626 — thanks @JasonLandbridge). @@ -2952,7 +2952,7 @@ We identified that **155 community PRs** across the entire project history (from - **fix(transport):** Prevent memory bloat and database exhaustion from large, fragmented streaming responses. Implemented `ByteQueue` in `kiro.ts` for zero-copy binary accumulation, refactored `antigravity.ts` for incremental SSE parsing, and enforced a strict 512KB tiered truncation limit (`MAX_CALL_LOG_ARTIFACT_BYTES`) on stream request logs and call artifacts (#1647). - **chore(ci):** Update build environment dependencies — bump Node to `24.15.0`, `actions/checkout@v6`, `docker/build-push-action@v7`, pin `actions/setup-python` to major tag (#1646 — thanks @backryun). -### 📝 Documentation +### 📝 文档 - **docs(env):** Add `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` to `.env.example` with documentation for LM Studio and other local provider use cases (#1623). @@ -2960,7 +2960,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.7.0] — 2026-04-26 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3009,7 +3009,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(providers):** Register Codex auto review and expand icon coverage. - **feat(tunnels):** Add Tailscale tunnel management routes and runtime helpers for install, login, daemon start, enable/disable, and health checks. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3125,7 +3125,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.9] — 2026-04-19 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3145,7 +3145,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(providers):** Derive Claude CLI model defaults dynamically from provider registry to stay current with upstream API changes (#1393) - **feat(core):** Implement persistent API key, backup pruning, and GPU optimization (#1350, #1367, #1369) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3214,7 +3214,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.8] — 2026-04-17 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3244,7 +3244,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(providers):** Expand image provider registry with extended model support including SD3.5, FLUX, and DALL-E 3 HD configurations - **feat(combos):** Add new routing strategies and full i18n support for agent features section across 31 languages -### 🔒 Security +### 🔒 安全 - **security:** Resolve 18 GitHub CodeQL scan alerts including ReDoS, incomplete sanitization, and bad HTML filtering regexp patterns - **fix(auth):** Seal privilege escalation vector by enforcing JWT session checking exclusively on `/api/keys` management endpoints (#1353) @@ -3258,7 +3258,7 @@ We identified that **155 community PRs** across the entire project history (from - **ci:** Bump GitHub Actions CI node-version to Node.js 24 natively - **fix(types):** Resolve TypeScript compilation errors in `claudeCodeCompatible.ts` (type predicates, `cache_control` index access) and `proxyFetch.ts` (`signal` nullability) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3301,7 +3301,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.6] — 2026-04-15 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3332,7 +3332,7 @@ We identified that **155 community PRs** across the entire project history (from - **feat(oauth):** Supports `cursor-agent` CLI as a native Cursor credential source alongside the standard configuration (#1258). - **feat(models):** Custom and imported models now merge correctly into filter lists for all available global providers (#1191). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3384,7 +3384,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.5] — 2026-04-13 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3410,7 +3410,7 @@ We identified that **155 community PRs** across the entire project history (from - **Stabilization Settings:** Added persistence support for `lkgpEnabled` and `backgroundDegradation` settings, integrated into `instrumentation-node.ts` for improved lifecycle awareness (#1212) - **xxhash-wasm dependency:** Added `xxhash-wasm@^1.1.0` for CCH signing (xxHash64 with seed `0x6E52736AC806831E`) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3446,7 +3446,7 @@ We identified that **155 community PRs** across the entire project history (from - **Combo Error Response Normalization:** Empty combo targets now return 404 (`comboModelNotFoundResponse`) instead of generic 503, improving client-side error differentiation - **Dependency Updates:** Bumps `typescript-eslint` to `8.58.2` (dev), `axios` to `1.15.0` (prod), and `next` to `16.2.2` (prod) (#1224, #1225) -### ⚠️ Breaking Changes +### ⚠️ 破坏性变更 - **`DELETE /api/settings/codex-service-tier` removed:** This endpoint no longer exists. Codex Service Tier configuration has moved to per-connection `providerSpecificData.requestDefaults`. Existing connections are migrated automatically on first startup after upgrade. Any external scripts or integrations that call this endpoint should be updated — use `PUT /api/providers/:id` with `providerSpecificData.requestDefaults.serviceTier` instead (#1176). - **CCH signing on CC-compatible providers:** All requests to `anthropic-compatible-cc-*` providers now include an xxHash64 integrity token (`cch=...`) in the billing header. Providers that do not validate CCH will ignore it (no behavioral change), but any custom middleware inspecting the billing header should expect a 5-character hex token instead of the `00000` placeholder @@ -3455,7 +3455,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.4] — 2026-04-12 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3484,12 +3484,12 @@ We identified that **155 community PRs** across the entire project history (from - **LKGP Standalone Strategy:** Implemented `lkgp` (Last Known Good Provider) as a fully functional standalone combo strategy. Previously, `lkgp` as a combo strategy silently fell through to `priority` ordering — the LKGP lookup only ran inside the `auto` engine. Now `strategy: "lkgp"` correctly queries the LKGP state, moves the last successful provider to the top of the target list, and saves the LKGP state after each successful request. Falls back to priority ordering when no LKGP state exists - **Unified Routing Rules & Model Aliases:** Consolidated the routing rules and model alias management controls into the Settings page, reducing fragmentation across the dashboard -### ⚡ Performance +### ⚡ 性能优化 - **Middleware Lazy Loading:** Refactored `src/proxy.ts` to lazy-import `apiAuth`, `db/settings`, and `modelSyncScheduler` modules, reducing middleware cold-start overhead. Added inline `isPublicApiRoute()` to avoid loading the full auth module for public routes - **E2E Auth Bypass:** Added `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` environment flag to bypass authentication gates for dashboard and management API routes during Playwright E2E test runs -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3511,7 +3511,7 @@ We identified that **155 community PRs** across the entire project history (from - **Duplicate `auto` in Combo Strategy Schema:** Removed duplicate `"auto"` entry from `comboStrategySchema` (was listed on both line 104 and 108). Harmless to Zod runtime but cleaned up to avoid confusion. Schema now has exactly 13 unique strategy values - **Legacy Combo Refs Normalization:** Fixed combo step normalization to preserve legacy string combo references during CRUD operations, preventing data loss when editing combos created before the v2 step architecture -### 🔒 Security +### 🔒 安全 - **Auth Bypass on Backup Routes (Critical):** Added `isAuthenticated` guards to `/api/db-backups/exportAll` (full database export) and `/api/db-backups` (list, create, and restore backups) — both were previously accessible without authentication - **Auth Guard on Translator Save:** Added `isAuthenticated` guard to `/api/translator/save` for defense-in-depth consistency @@ -3562,7 +3562,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.3] — 2026-04-11 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3580,7 +3580,7 @@ We identified that **155 community PRs** across the entire project history (from - **OpenAI-Compatible Loose Validation:** Empty API keys can now be naturally submitted and saved for any `openai-compatible-*` providers (e.g. Pollinations, localized routes) directly in the UI instead of blocking save actions (#1152) - **Cloudflare Configuration:** Updated the provider schema and UI integration for Cloudflare AI to officially expose and support the backend `accountId` field securely without overrides (#1150) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3607,7 +3607,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.2] — 2026-04-11 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3627,7 +3627,7 @@ We identified that **155 community PRs** across the entire project history (from - **Documentation Refresh:** Updated README, ARCHITECTURE, FEATURES, AGENTS.md, and API_REFERENCE for v3.6.2 with accurate provider counts (100+), new executor list, and system API documentation - **Uninstall Guide:** Created comprehensive `docs/guides/UNINSTALL.md` covering clean uninstallation for all deployment methods (npm, Docker, Electron, source) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3646,7 +3646,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.1] — 2026-04-10 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3663,7 +3663,7 @@ We identified that **155 community PRs** across the entire project history (from - **OAuth Env Repair Action:** Added a "Repair env" button to the OAuth Providers dashboard that detects and restores missing OAuth client IDs from `.env.example` — with timestamped backup and append-only safety. Includes full 33-language i18n support and sanitized API responses (#1116, by @yart) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3682,7 +3682,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.6.0] — 2026-04-10 -### ✨ New Features & Analytics +### ✨ 新功能 & Analytics - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3699,7 +3699,7 @@ We identified that **155 community PRs** across the entire project history (from - **Combo Smoke Test:** Raised the default token budget to 2048 to prevent truncation of thinking models during preflight checks, and fully randomized the arithmetic probe prompt to bypass deterministic caching from upstream relays (#1105) -### 🐛 Bug Fixes & Compliance +### 🐛 问题修复 & Compliance - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3719,7 +3719,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.9] — 2026-04-09 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3737,7 +3737,7 @@ We identified that **155 community PRs** across the entire project history (from - **Persistent Combo Ordering:** Drag combo cards by handle to reorder them in the dashboard; order is persisted to SQLite via a new `sort_order` column and `POST /api/combos/reorder` endpoint. Includes DB migration `020_combo_sort_order.sql` and JSON import preservation (#1095) - **Sidebar Group Reorder:** Moved "Logs" before "Health" in the System section and "Limits & Quotas" after "Cache" in the Primary section for a more logical navigation flow (#1095) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3759,7 +3759,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.8] — 2026-04-09 -### ✨ New Features & Analytics +### ✨ 新功能 & Analytics - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3776,7 +3776,7 @@ We identified that **155 community PRs** across the entire project history (from - **Analytics Layout Redesign:** Replaced flat metrics with a responsive `CompactStatGrid`, grouping data visually across sections (#1089) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3792,7 +3792,7 @@ We identified that **155 community PRs** across the entire project history (from - **Provider Quarantine:** Introduces model/provider circuit-breakers with adaptive TTL exponential backoff for recurring upstream errors (#1090) - **Oauth Keep-Alive:** Safely protects authenticated active accounts against spontaneous dropping from router due to transient token refresh failures (#1085) -### 🔒 Security & Maintenance +### 🔒 安全 & Maintenance - **Dependabot:** bumped axios from 1.14.0 to 1.15.0 addressing SSRF flags (#1088) @@ -3800,7 +3800,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.7] — 2026-04-09 -### 🐛 Bug Fixes & Security +### 🐛 问题修复 & Security - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3818,7 +3818,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.6] — 2026-04-09 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3840,7 +3840,7 @@ We identified that **155 community PRs** across the entire project history (from - **Environment Auto-Sync:** Added `sync-env.mjs` to auto-generate and append `.env` from `.env.example` during installation, automatically generating cryptographic secrets on first run. - **Source Mode Dashboard Update:** Fixed real-time Source (git-checkout) updating in the dashboard, enabling secure, real-time update pipelines for non-NPM installations. -### 🐛 Bug Fixes & Security +### 🐛 问题修复 & Security - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3871,7 +3871,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.5] — 2026-04-08 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3890,7 +3890,7 @@ We identified that **155 community PRs** across the entire project history (from - **Context Relay Combo Strategy:** Added the new `context-relay` combo strategy with priority-style routing, structured handoff summary generation once quota usage reaches the warning threshold, and handoff injection after the next real account switch. - **Global Context Relay Defaults:** Added global Settings defaults plus combo-level configuration for `handoffThreshold`, `handoffModel`, and `handoffProviders`, so new or unconfigured combos can inherit the feature consistently. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3925,7 +3925,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.4] — 2026-04-07 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -3945,7 +3945,7 @@ We identified that **155 community PRs** across the entire project history (from - **Non-Stream Aliases:** Added API support for explicit non-streaming aliases (`non_stream`, `disable_stream`, `disable_streaming`, `streaming=false`), normalized at the boundary before provider translation (#1036 — thanks @wlfonseca). - **Russian Dashboard Localization:** Comprehensive Russian translation for the dashboard UI, including fixes for 2 Ukrainian locale keys (#1003 — thanks @mercs2910). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -3965,11 +3965,11 @@ We identified that **155 community PRs** across the entire project history (from - **macOS Desktop App Startup:** Stabilized packaged macOS app launch by excluding desktop artifacts from the standalone bundle and improving launch path detection (#1004 — thanks @mercs2910). - **macOS Sidebar Layout:** Fixed macOS traffic light overlap, sidebar spacing, and button overflow in the Electron desktop app (#1001 — thanks @mercs2910). -### ⚡ Performance +### ⚡ 性能优化 - **Analytics Page Load:** Dramatically reduced analytics page load times (30s→1-2s for 50K entries) via date-filtered DB queries, parallel `Promise.all()` cost calculations, and merged 6 COUNT queries into a single CASE WHEN aggregate (#1038 — thanks @oyi77). -### 🔒 Security & Dependencies +### 🔒 安全 & Dependencies - **Node Base Image:** Upgraded Docker base from `22-bookworm-slim` to `22.22.2-trixie-slim` (#1011 — Snyk). - **Production Dependencies:** Bumped 5 production dependencies (#1044 — Dependabot). @@ -4020,7 +4020,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.2] — 2026-04-05 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4039,7 +4039,7 @@ We identified that **155 community PRs** across the entire project history (from - **Resilience Engine Overhaul:** Integrated context overflow graceful fallbacks, proactive OAuth token detection, and empty-content emission prevention (#990). - **Context-Optimized Routing Strategy:** Added new intelligent routing capability to natively maximize context windows in automated combo deployments (#990). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4059,7 +4059,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.1] — 2026-04-04 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4078,7 +4078,7 @@ We identified that **155 community PRs** across the entire project history (from - **Provider Native Capabilities:** Added support for declaring and checking native API features (e.g. `systemInstructions_supported`) preventing failures by sanitizing invalid roles. Currently configured for Gemini Base and Antigravity OAuth providers. - **API Provider Advanced Settings:** Added per-connection custom `User-Agent` overrides for API-key provider connections. The override is stored in `providerSpecificData.customUserAgent` and now applies to validation probes and upstream execution requests. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4094,7 +4094,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.5.0] — 2026-04-03 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4116,7 +4116,7 @@ We identified that **155 community PRs** across the entire project history (from - **MCP Extensibility:** Added and successfully registered the new `omniroute_web_search` MCP framework tool out of beta into production schemas (#951). - **Tokens Buffer Logic:** Added runtime configuration limits extending configurable input/output token buffers for precise Usage Tracking metrics (#959). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4205,7 +4205,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.4.6] - 2026-04-02 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4224,7 +4224,7 @@ We identified that **155 community PRs** across the entire project history (from - **Dashboard UI:** Added standalone sidebar navigation for the new Memory and Skills modules (#926). - **i18n:** Added translation strings and layout mappings across 30 languages for the Memory and Skills namespaces. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4246,7 +4246,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.4.5] - 2026-04-02 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4265,7 +4265,7 @@ We identified that **155 community PRs** across the entire project history (from - **Qoder PAT Support:** Integrated Personal Access Tokens (PAT) support directly via the local `qodercli` transport instead of legacy remote `.cn` browser configurations (#913). - **Gemini 3.1 Pro Preview (GitHub):** Added `gemini-3.1-pro-preview` canonical explicit model support natively into the GitHub Copilot provider while preserving older routing aliases (#924). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4288,7 +4288,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.4.4] - 2026-04-02 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4315,7 +4315,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.4.3] - 2026-04-02 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4339,7 +4339,7 @@ We identified that **155 community PRs** across the entire project history (from - **Model Enhancements:** Added explicit `contextLength` for all opencode-zen models. - **i18n & translations:** Integrated 33 language translations natively, including placeholder CI validations and Chinese documentation updates (#873, #869). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4382,7 +4382,7 @@ We identified that **155 community PRs** across the entire project history (from > **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** > On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4405,7 +4405,7 @@ We identified that **155 community PRs** across the entire project history (from - **Opencode-Zen Models:** Added 4 free models to opencode-zen registry (#854) - **Tests:** Added unit and E2E tests for settings toggles and bug fixes (#850) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4428,7 +4428,7 @@ We identified that **155 community PRs** across the entire project history (from - **Claude Code/Codex Translations:** Protected non-streaming payload conversions against empty responses from upstream Codex tools, avoiding catastrophic TypeErrors (#866) - **NVIDIA NIM Rendering:** Conditionally stripped identical provider prefixes dynamically pushed by audio models, eliminating duplicate `nim/nim` tag structures throwing 404 on the Media Playground (#872) -### ⚠️ Breaking Changes +### ⚠️ 破坏性变更 - **Request Log Layout:** Removed the old multi-file `DATA_DIR/logs/` request log sessions and the `DATA_DIR/log.txt` summary file. New requests are written as single JSON artifacts in `DATA_DIR/call_logs/YYYY-MM-DD/`. - **Logging Environment Variables:** Replaced `LOG_*`, `ENABLE_REQUEST_LOGS`, `CALL_LOGS_MAX`, `CALL_LOG_PAYLOAD_MODE`, and `PROXY_LOG_MAX_ENTRIES` with the new `APP_LOG_*` and `CALL_LOG_RETENTION_DAYS` configuration model. @@ -4451,7 +4451,7 @@ We identified that **155 community PRs** across the entire project history (from - **Model Registry Update:** Injected `gpt-5.4-mini` into the Codex provider's array of models (#756) - **Provider Limit Tracking:** Track and display when provider rate limits were last refreshed per account (#843) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4478,7 +4478,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.9] - 2026-03-31 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4502,7 +4502,7 @@ We identified that **155 community PRs** across the entire project history (from - **Qoder Integration:** Native integration for Qoder AI natively replacing the legacy iFlow platform mappings (#660) - **Prompt Cache Tracking:** Added tracking capabilities and frontend visualization (Stats card) for semantic and prompt caching in the Dashboard UI -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4524,7 +4524,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.7] - 2026-03-30 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4543,7 +4543,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.6] - 2026-03-30 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4563,7 +4563,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.5] - 2026-03-30 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4581,7 +4581,7 @@ We identified that **155 community PRs** across the entire project history (from - **Gemini Quota Tracking:** Added real-time Gemini CLI quota tracking via the `retrieveUserQuota` API (PR #825) - **Cache Dashboard:** Enhanced the Cache Dashboard to display prompt cache metrics, 24h trends, and estimated cost savings (PR #824) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4600,7 +4600,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.4] - 2026-03-30 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4623,7 +4623,7 @@ We identified that **155 community PRs** across the entire project history (from - **Provider Diversity:** Implemented provider diversity scoring via Shannon entropy to improve load distribution. - **Auto-Disable Bounds:** Added an Auto-Disable Banned Accounts setting toggle to the Resilience dashboard. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4647,7 +4647,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.3] - 2026-03-29 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4668,7 +4668,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.2] - 2026-03-29 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4686,7 +4686,7 @@ We identified that **155 community PRs** across the entire project history (from - **Cloudflare Tunnels:** Cloudflare Quick Tunnel integration with dashboard controls (PR #772). - **Diagnostics:** Semantic cache bypass for combo live tests (PR #773). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4706,7 +4706,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.3.1] - 2026-03-29 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4731,7 +4731,7 @@ We identified that **155 community PRs** across the entire project history (from - **Release Stabilization** — Finalized v3.2.9 release (combo diagnostics, quality gates, Gemini tool fix) and created missing git tag. Consolidated all staged changes into a single atomic release commit. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4755,7 +4755,7 @@ We identified that **155 community PRs** across the entire project history (from - **Combo Diagnostics** — Introduced a live test bypass flag (`forceLiveComboTest`) allowing administrators to execute real upstream health checks that bypass all local circuit-breaker and cooldown state mechanisms, enabling precise diagnostics during rolling outages (PR #759) - **Quality Gates** — Added automated response quality validation for combos and officially integrated `claude-4.6` model support into the core routing schemas (PR #762) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4778,7 +4778,7 @@ We identified that **155 community PRs** across the entire project history (from - **Docker Auto-Update UI** — Integrated a detached background update process for Docker Compose deployments. The Dashboard UI now seamlessly tracks update lifecycle events combining JSON REST responses with SSE streaming progress overlays for robust cross-environment reliability. - **Cache Analytics** — Repaired zero-metrics visualization mapping by migrating Semantic Cache telemetry logs directly into the centralized tracking SQLite module. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4815,7 +4815,7 @@ We identified that **155 community PRs** across the entire project history (from - **Strict Combo Testing (#735)** — Hardened the combo health check endpoint to require live text responses from models instead of just soft reachability signals. - **Streamed Detailed Logs (#734)** — Switched detailed request logging for SSE streams to reconstruct the final payload, saving immense amounts of SQLite database size and significantly cleaning up the UI. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4843,7 +4843,7 @@ We identified that **155 community PRs** across the entire project history (from - **Qoder AI Migration (#660)** — Completely migrated the legacy `iFlow` core provider onto `Qoder AI` maintaining stable API routing capabilities. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4865,7 +4865,7 @@ We identified that **155 community PRs** across the entire project history (from - **Provider Limits Quota UI (#728)** — Normalized quota limit logic and data labeling inside the Limits interface. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4885,7 +4885,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.2.2] — 2026-03-29 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4902,7 +4902,7 @@ We identified that **155 community PRs** across the entire project history (from - **Four-Stage Request Log Pipeline (#705)** — Refactored log persistence to save comprehensive payloads at four distinct pipeline stages: Client Request, Translated Provider Request, Provider Response, and Translated Client Response. Introduced `streamPayloadCollector` for robust SSE stream truncation and payload serialization. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4920,7 +4920,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.2.1] — 2026-03-29 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4937,7 +4937,7 @@ We identified that **155 community PRs** across the entire project history (from - **Global Fallback Provider (#689)** — When all combo models are exhausted (502/503), OmniRoute now attempts a configurable global fallback model before returning the error. Set `globalFallbackModel` in settings to enable. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4959,7 +4959,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.2.0] — 2026-03-28 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -4978,7 +4978,7 @@ We identified that **155 community PRs** across the entire project history (from - **GLM Quota Tracking** — Added real-time usage and session quota tracking for the GLM Coding (Z.AI) provider (PR #698 by @christopher-s) - **Detailed Log Payloads** — Wired full four-stage pipeline payload capturing (original, translated, provider-response, streamed-deltas) directly into the UI (PR #705 by @rdself) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -4995,13 +4995,13 @@ We identified that **155 community PRs** across the entire project history (from - **Fix #718** — Rebuilt badge rendering in Provider Limits UI preventing bad quota boundaries overlap (PR #718 by @rdself) - **Fix #704** — Fixed Combo Fallbacks breaking on HTTP 400 content-policy errors preventing model-rotation dead-routing (PR #704 by @rdself) -### 🔒 Security & Dependencies +### 🔒 安全 & Dependencies - Bumped \`path-to-regexp\` to \`8.4.0\` resolving dependabot vulnerabilities (PR #715) ## [3.1.10] — 2026-03-28 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5020,7 +5020,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.9] — 2026-03-28 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5041,7 +5041,7 @@ We identified that **155 community PRs** across the entire project history (from - **Codex Auth Export** — Added Codex `auth.json` export and apply-local buttons for seamless CLI integration. - **Windsurf BYOK Notes** — Added official limitation warnings to the Windsurf CLI tool card documenting BYOK constraints. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5075,7 +5075,7 @@ We identified that **155 community PRs** across the entire project history (from | `tests/unit/t40-opencode-cli-tools-integration.test.mjs` | CLI tool integration tests | | `COVERAGE_PLAN.md` | Test coverage planning document | -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5091,7 +5091,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.8] - 2026-03-27 -### 🐛 Bug Fixes & Features +### 🐛 问题修复 & Features - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5107,7 +5107,7 @@ We identified that **155 community PRs** across the entire project history (from - **Stability:** Patched streaming crashes related to the native Antigravity provider integration failing due to unhandled undefined state arrays (#684). - **Localization Sync:** Deployed a fully overhauled `i18n` synchronizer detecting missing nested JSON properties and retro-fitting 30 locales sequentially (#685).## [3.1.7] - 2026-03-27 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5126,7 +5126,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.6] — 2026-03-27 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5145,7 +5145,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.5] — 2026-03-27 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5167,7 +5167,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.4] — 2026-03-27 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5199,7 +5199,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.2] — 2026-03-26 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5222,7 +5222,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.1] — 2026-03-26 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5240,7 +5240,7 @@ We identified that **155 community PRs** across the entire project history (from - **Vision Capability Metadata**: Added `capabilities.vision`, `input_modalities`, and `output_modalities` to `/v1/models` entries for vision-capable models (PR #646) - **Gemini 3.1 Models**: Added `gemini-3.1-pro-preview` and `gemini-3.1-flash-lite-preview` to the Antigravity provider (#645) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5263,7 +5263,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.1.0] — 2026-03-26 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5281,7 +5281,7 @@ We identified that **155 community PRs** across the entire project history (from - **GitHub Issue Templates**: Added standardized bug report, feature request, and config/proxy issue templates (#641) - **Clear All Models**: Added a "Clear All Models" button to the provider detail page with i18n support in 29 languages (#634) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5307,7 +5307,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.9] — 2026-03-26 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5322,7 +5322,7 @@ We identified that **155 community PRs** across the entire project history (from - **NaN tokens in Claude Code / client responses (#617):** - `sanitizeUsage()` now cross-maps `input_tokens`→`prompt_tokens` and `output_tokens`→`completion_tokens` before the whitelist filter, fixing responses showing NaN/0 token counts when providers return Claude-style usage field names -### 🔒 Security +### 🔒 安全 - Updated `yaml` package to fix stack overflow vulnerability (GHSA-48c2-rrv3-qjmp) @@ -5337,7 +5337,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.8] — 2026-03-25 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5360,7 +5360,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.7] — 2026-03-25 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5378,7 +5378,7 @@ We identified that **155 community PRs** across the entire project history (from - **Proxy Fallback:** Added automatic retry without proxy when SOCKS5 relay fails - **Proxy Test:** Test endpoint now resolves real credentials from DB via proxyId -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5405,7 +5405,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.6] — 2026-03-25 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5421,7 +5421,7 @@ We identified that **155 community PRs** across the entire project history (from - **CI:** Fixed integration test `v1/models` assertion failure in CI environments without provider connections - **Settings:** Proxy test button now shows success/failure results immediately (previously hidden behind health data) -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5446,7 +5446,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.5] — 2026-03-25 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5467,7 +5467,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.4] — 2026-03-25 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5488,7 +5488,7 @@ We identified that **155 community PRs** across the entire project history (from ## [3.0.3] — 2026-03-25 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5505,7 +5505,7 @@ We identified that **155 community PRs** across the entire project history (from - **Auto-Sync Models:** Added a UI toggle and `sync-models` endpoint to automatically synchronise model lists per provider using a scheduled interval scheduler (PR #597) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5537,7 +5537,7 @@ We identified that **155 community PRs** across the entire project history (from - Untagged connections appear first without a header, followed by tagged groups in alphabetical order. - The tag grouping automatically applies to the Codex/Copilot/Antigravity Limits section since toggles exist inside connection rows. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5715,7 +5715,7 @@ Full media generation playground at `/dashboard/media`: Image Generation, Video, --- -### 🔒 Security & CI/CD +### 🔒 安全 & CI/CD - **CodeQL remediation** — Fixed 10+ alerts: 6 polynomial-redos, 1 insecure-randomness (`Math.random()` → `crypto.randomUUID()`), 1 shell-command-injection - **Route validation** — Zod schemas + `validateBody()` on **176/176 API routes** — CI enforced @@ -5725,7 +5725,7 @@ Full media generation playground at `/dashboard/media`: Image Generation, Video, --- -### 🐛 Bug Fixes (40+) +### 🐛 问题修复 (40+) - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5903,7 +5903,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.17] — 2026-03-24 -### 🔒 Security & CI/CD +### 🔒 安全 & CI/CD - **CodeQL remediation** — Fixed 10+ alerts: - 6 polynomial-redos in `provider.ts` / `chatCore.ts` (replaced `(?:^|/)` alternation patterns with segment-based matching) @@ -5913,7 +5913,7 @@ docker pull diegosouzapw/omniroute:3.0.0 - `model-combo-mappings` (POST, PUT), `webhooks` (POST, PUT), `openapi/try` (POST) - CI `check:route-validation:t06` now passes: **176/176 routes validated** -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -5940,7 +5940,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.16] — 2026-03-24 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5962,7 +5962,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.15] — 2026-03-24 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -5998,7 +5998,7 @@ docker pull diegosouzapw/omniroute:3.0.0 - **SVG fallback**: `ProviderIcon` component updated with 4-tier strategy: Lobehub → PNG → SVG → Generic icon - **Agents fingerprinting**: Synced with CLI tools — added droid, openclaw, copilot, opencode to fingerprint list (14 total) -### 🔒 Security +### 🔒 安全 - **CVE fix**: Resolved dompurify XSS vulnerability (GHSA-v2wj-7wpq-c8vv) via npm overrides forcing `dompurify@^3.3.2` - `npm audit` now reports **0 vulnerabilities** @@ -6026,7 +6026,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.13] — 2026-03-23 -### 🔧 Bug Fixes +### 🔧 问题修复 - **config:** resolve real API key from `keyId` in CLI settings routes (`codex-settings`, `droid-settings`, `kilo-settings`) to prevent writing masked strings (#549) @@ -6043,7 +6043,7 @@ docker pull diegosouzapw/omniroute:3.0.0 | **#544** | @k0valik | fix(cli): secure CLI tool detection via known installation paths (8 tools) with symlink validation, file-type checks, size bounds, minimal env in healthcheck | | **#542** | @rdself | fix(ui): improve light mode contrast — add missing CSS theme variables (`bg-primary`, `bg-subtle`, `text-primary`) and fix dark-only colors in log detail | -### 🔧 Bug Fixes +### 🔧 问题修复 - **TDZ fix in `cliRuntime.ts`** — `validateEnvPath` was used before initialization at module startup by `getExpectedParentPaths()`. Reordered declarations to fix `ReferenceError`. - **Build fixes** — Added `pino` and `pino-pretty` to `serverExternalPackages` to prevent Turbopack from breaking Pino's internal worker loading. @@ -6056,7 +6056,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.10] — 2026-03-23 -### 🔧 Bug Fixes +### 🔧 问题修复 - **#509 / #508** — Electron build regression: downgraded Next.js from `16.1.x` to `16.0.10` to eliminate Turbopack module-hashing instability that caused blank screens in the Electron desktop bundle. - **Unit test fixes** — Corrected two stale test assertions (`nanobanana-image-handler` aspect ratio/resolution, `thinking-budget` Gemini `thinkingConfig` field mapping) that had drifted after recent implementation changes. @@ -6066,7 +6066,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.9] — 2026-03-23 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6093,7 +6093,7 @@ docker pull diegosouzapw/omniroute:3.0.0 ## [3.0.0-rc.8] — 2026-03-23 -### 🔧 Bug Fixes & Improvements (Fallback, Quota & Budget) +### 🔧 问题修复 & Improvements (Fallback, Quota & Budget) - **T24** — `503` cooldown await fix + `406` mapping: mapped `406 Not Acceptable` to `503 Service Unavailable` with proper cooldown intervals. - **T25** — Provider validation fallback: graceful fallback to standard validation models when a specific `validationModelId` is not present. @@ -6120,7 +6120,7 @@ Both providers use the new `OpencodeExecutor` with multi-format routing (`/chat/ --- -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6174,7 +6174,7 @@ OmniRoute now automatically refreshes model lists for connected providers every --- -### 🔧 Bug Fixes +### 🔧 问题修复 #### OAuth & Auth @@ -6241,7 +6241,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.6] - 2026-03-23 -### 🔧 Bug Fixes & Improvements (sub2api Gap Analysis — T01–T15) +### 🔧 问题修复 & Improvements (sub2api Gap Analysis — T01–T15) - **T01** — `requested_model` column in `call_logs` (migration 009): track which model the client originally requested vs the actual routed model. Enables fallback rate analytics. - **T02** — Strip empty text blocks from nested `tool_result.content`: prevents Anthropic 400 errors (`text content blocks must be non-empty`) when Claude Code chains tool results. @@ -6262,7 +6262,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.5] - 2026-03-22 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6292,7 +6292,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.4] - 2026-03-22 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6315,7 +6315,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.3] - 2026-03-22 -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6333,7 +6333,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **#529** — Provider icons now use [@lobehub/icons](https://github.com/lobehub/lobe-icons) with graceful PNG fallback and a `ProviderIcon` component (130+ providers supported) - **#488** — Auto-update model lists every 24h via `modelSyncScheduler` (configurable via `MODEL_SYNC_INTERVAL_HOURS`) -### 🔧 Bug Fixes +### 🔧 问题修复 - **#537** — Gemini CLI OAuth: now shows clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker/self-hosted deployments @@ -6341,7 +6341,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.2] - 2026-03-22 -### 🔧 Bug Fixes +### 🔧 问题修复 - **#536** — LongCat AI key validation: fixed baseUrl (`api.longcat.chat/openai`) and authHeader (`Authorization: Bearer`) - **#535** — Pinned model override: `body.model` is now set to `pinnedModel` when context-cache protection detects a pinned model @@ -6351,7 +6351,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [3.0.0-rc.1] - 2026-03-22 -### 🔧 Bug Fixes +### 🔧 问题修复 - **#521** — Login no longer gets stuck after skipping password setup (redirects to onboarding) - **#522** — API Manager: Removed misleading "Copy masked key" button (replaced with lock icon tooltip) @@ -6376,7 +6376,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: New OpenCode providers, embedding credentials fix, CLI masked key bug, CACHE_TAG_PATTERN fix. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6406,7 +6406,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Bug fixes — preserve Codex prompt cache key, fix tagContent JSON escaping, sync expired token status to DB. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6458,7 +6458,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(executors/cloudflare-ai)**: New `CloudflareAIExecutor` — dynamic URL construction requires `accountId` in provider credentials - **feat(executors)**: Register `pollinations`, `pol`, `cloudflare-ai`, `cf` executor mappings -### 📝 Documentation +### 📝 文档 - **docs(readme)**: Expanded free combo stack to 11 providers ($0 forever) - **docs(readme)**: Added 4 new free provider sections (LongCat, Pollinations, Cloudflare AI, Scaleway) with model tables @@ -6476,7 +6476,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Fix media transcription (Deepgram/HuggingFace Content-Type, language detection) and TTS error display. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6531,7 +6531,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Cross-platform machineId fix, per-API-key rate limits, streaming context cache, Alibaba DashScope, search analytics, ZWS v5, and 8 issues closed. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -6551,7 +6551,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(api)**: Per-API-key request-count limits — `max_requests_per_day` and `max_requests_per_minute` columns with in-memory sliding-window enforcement returning HTTP 429 (#452) - **feat(dev)**: ZWS v5 — HMR leak fix (485 DB connections → 1), memory 2.4GB → 195MB, `globalThis` singletons, Edge Runtime warning fix (@zhangqiang8vip) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6770,7 +6770,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(dashboard)**: Response-first layout in request log detail UI (#470) - **feat(i18n)**: Improved Chinese (zh-CN) translation — complete retranslation (#475, @only4copilot) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6812,7 +6812,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(providers)**: Added Alibaba Cloud Coding Plan support with two OpenAI-compatible endpoints — `alicode` (China) and `alicode-intl` (International), each with 8 models (#465, @dtk1985) - **feat(providers)**: Added dedicated `kimi-coding-apikey` provider path — API-key-based Kimi Coding access is no longer forced through OAuth-only `kimi-coding` route. Includes registry, constants, models API, config, and validation test (#463, @Mind-Dragon) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6836,7 +6836,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(codex)**: Native responses subpath passthrough for Codex — natively routes `POST /v1/responses/compact` to Codex upstream, maintaining Claude Code compatibility without stripping the `/compact` suffix (#457) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6857,7 +6857,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Budget save bug + combo agent features UI + omniModel tag security fix. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6882,7 +6882,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Docker pino crash, Codex CLI responses worker fix, package-lock sync. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6907,7 +6907,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: UX improvements and Windows CLI healthcheck fix. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6937,7 +6937,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - Local provider_nodes routing for `/v1/rerank` - 30+ i18n keys in search namespace -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6960,7 +6960,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Codex direct API quota fallback fix. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -6983,7 +6983,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Light mode UI contrast fixes. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7005,7 +7005,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: Unified web search routing (POST /v1/search) with 5 providers + Next.js 16.1.7 security fixes (6 CVEs). -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7028,7 +7028,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - DB migration: `request_type` column on `call_logs` for non-chat request tracking - Zod validation (`v1SearchSchema`), auth-gated, cost recorded via `recordCost()` -### 🔒 Security +### 🔒 安全 - **deps**: Next.js 16.1.6 → 16.1.7 — fixes 6 CVEs: - **Critical**: CVE-2026-29057 (HTTP request smuggling via http-proxy) @@ -7088,7 +7088,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(migrations)**: New column `latency_p50` in `combo_metrics` table — zero-breaking, safe for existing users -### 🐛 Bug Fixes / Closures +### 🐛 问题修复 / Closures - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7108,7 +7108,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Windows fix: better-sqlite3 prebuilt download without node-gyp/Python/MSVC (#426). -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7128,7 +7128,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > CI fixes (t11 any-budget), bug fix #409 (file attachments via Copilot+Claude), release workflow correction. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7180,7 +7180,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(audio)**: Route TTS/STT to local `provider_nodes` — `buildDynamicAudioProvider()` with SSRF protection (#416, @Regis-RCR) - **feat(proxy)**: Proxy registry, management APIs, and quota-limit generalization (#429, @Regis-RCR) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7211,7 +7211,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Hotfix: Turbopack/Docker compatibility — remove `node:` protocol from all `src/` imports. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7232,7 +7232,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: reasoning model param filtering, local provider 404 fix, Kilo Gateway provider, dependency bumps. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7249,7 +7249,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **feat(api)**: Added **Kilo Gateway** (`api.kilo.ai`) as a new API Key provider (alias `kg`) — 335+ models, 6 free models, 3 auto-routing models (`kilo-auto/frontier`, `kilo-auto/balanced`, `kilo-auto/free`). Passthrough models supported via `/api/gateway/models` endpoint. (PR #408 by @Regis-RCR) -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7275,7 +7275,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [2.6.4] — 2026-03-17 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7300,7 +7300,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: zod/pino hash-strip baked into build pipeline, Synthetic provider added, VPS PM2 path corrected. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7330,7 +7330,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Sprint: module hashing fully fixed, 2 PRs merged (Anthropic tools filter + custom endpoint paths), Alibaba Cloud DashScope provider added, 3 stale issues closed. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7362,7 +7362,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Critical startup fix: v2.6.0 global npm installs crashed with a 500 error due to a Turbopack/webpack module-name hashing bug in the Next.js 16 instrumentation hook. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7387,7 +7387,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Issue resolution sprint: 4 bugs fixed, logs UX improved, Kiro credit tracking added. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7418,7 +7418,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Codex native passthrough fix + route body validation hardening. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7440,7 +7440,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Build fix: restore VPS connectivity broken by v2.5.7 incomplete publish. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7460,7 +7460,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Media playground error handling fixes. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7482,7 +7482,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Critical security/auth fixes: Antigravity OAuth broken + JWT sessions lost after restart. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7503,7 +7503,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Model list dedup fix, Electron standalone build hardening, and Kiro credit tracking. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7518,7 +7518,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **fix(models) #380**: `GET /api/models` now includes provider aliases when building the active-provider filter — models for `claude` (alias `cc`) and `github` (alias `gh`) were always shown regardless of whether a connection was configured, because `PROVIDER_MODELS` keys are aliases but DB connections are stored under provider IDs. Fixed by expanding each active provider ID to also include its alias via `PROVIDER_ID_TO_ALIAS`. Closes #353. - **fix(electron) #379**: New `scripts/prepare-electron-standalone.mjs` stages a dedicated `/.next/electron-standalone` bundle before Electron packaging. Aborts with a clear error if `node_modules` is a symlink (electron-builder would ship a runtime dependency on the build machine). Cross-platform path sanitization via `path.basename`. By @kfiramar. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7539,7 +7539,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Logger startup fix, login bootstrap security fix, and dev HMR reliability improvement. CI infrastructure hardened. -### 🐛 Bug Fixes (PRs #374, #375, #376 by @kfiramar) +### 🐛 问题修复 (PRs #374, #375, #376 by @kfiramar) - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7565,7 +7565,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Critical bugfixes: DB schema migration, startup env loading, provider error state clearing, and i18n tooltip fix. Code quality improvements on top of each PR. -### 🐛 Bug Fixes (PRs #369, #371, #372, #373 by @kfiramar) +### 🐛 问题修复 (PRs #369, #371, #372, #373 by @kfiramar) - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7590,7 +7590,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Codex account quota policy with auto-rotation, fast tier toggle, gpt-5.4 model, and analytics label fix. -### ✨ New Features (PRs #366, #367, #368) +### ✨ 新功能 (PRs #366, #367, #368) - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7609,7 +7609,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **Codex Fast Tier Toggle (PR #367)**: Dashboard → Settings → Codex Service Tier. Default-off toggle injects `service_tier: "flex"` only for Codex requests, reducing cost ~80%. Full stack: UI tab + API endpoint + executor + translator + startup restore. - **gpt-5.4 Model (PR #368)**: Adds `cx/gpt-5.4` and `codex/gpt-5.4` to the Codex model registry. Regression test included. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7625,7 +7625,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Major release: strict-random routing strategy, API key access controls, connection groups, external pricing sync, and critical bug fixes for thinking models, combo testing, and tool name validation. -### ✨ New Features (PRs #363 & #365) +### ✨ 新功能 (PRs #363 & #365) - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7646,7 +7646,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **External Pricing Sync (LiteLLM)**: 3-tier pricing resolution (user overrides → synced → defaults). Opt-in via `PRICING_SYNC_ENABLED=true`. MCP tool `omniroute_sync_pricing`. 23 new tests. - **i18n**: 30 languages updated with strict-random strategy, API key management strings. pt-BR fully translated. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7668,7 +7668,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > API Key Round-Robin support for multi-key provider setups, and confirmation of wildcard routing and quota window rolling already in place. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7692,7 +7692,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > UI polish, routing strategy additions, and graceful error handling for usage limits. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7711,7 +7711,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **Free Stack Preset Models**: Creating a combo with the Free Stack template now auto-fills 7 best-in-class free provider models (Gemini CLI, Kiro, Qoder×2, Qwen, NVIDIA NIM, Groq). Users just activate the providers and get a $0/month combo out-of-the-box. - **Wider Combo Modal**: Create/Edit combo modal now uses `max-w-4xl` for comfortable editing of large combos. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7729,7 +7729,7 @@ OmniRoute now automatically refreshes model lists for connected providers every > Multiple improvements from community issue analysis, new provider support, bug fixes for token tracking, model routing, and streaming reliability. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7753,7 +7753,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **Round-Robin State Management (PR #349)**: Enhanced round-robin logic to handle excluded accounts and maintain rotation state correctly. - **Clipboard UX (PR #360)**: Hardened clipboard operations with fallback for non-secure contexts; Claude tool normalization improvements. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7833,7 +7833,7 @@ OmniRoute now automatically refreshes model lists for connected providers every ## [2.3.14] - 2026-03-13 -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. @@ -7859,7 +7859,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **Tier Scoring (API + Validation)**: Added `tierPriority` (weight `0.05`) to the `ScoringWeights` Zod schema and the `combos/auto` API route — the 7th scoring factor is now fully accepted by the REST API and validated on input. `stability` weight adjusted from `0.10` to `0.05` to keep total sum = `1.0`. -### ✨ New Features +### ✨ 新功能 - **feat(docs):** integrate multi-page documentation into OmniRoute dashboard (#1969) - **feat(settings):** add request body limit setting (#1968) @@ -7879,7 +7879,7 @@ OmniRoute now automatically refreshes model lists for connected providers every - **Configurable API Bridge Timeout**: `API_BRIDGE_PROXY_TIMEOUT_MS` env var lets operators tune the proxy timeout (default 30s). Fixes 504 errors on slow upstream responses. (#332) - **Star History**: Replaced star-history.com widget with starchart.cc (`?variant=adaptive`) in all 30 READMEs — adapts to light/dark theme, real-time updates. -### 🐛 Bug Fixes +### 🐛 问题修复 - **fix(mitm):** Compile MITM utilities as NodeNext ESM during prepublish, copy the CommonJS MITM server into the standalone artifact, and resolve MITM data paths without relying on Next.js aliases in packaged runtime. - **fix(build):** Move the local `.tmp/wine32` Wine prefix out of the isolated Next.js build path so Windows Electron packaging artifacts cannot trigger `EACCES` scans during Node 24 builds. diff --git a/docs/i18n/zh-CN/CLAUDE.md b/docs/i18n/zh-CN/CLAUDE.md index 5f350111e67a..7be013f07218 100644 --- a/docs/i18n/zh-CN/CLAUDE.md +++ b/docs/i18n/zh-CN/CLAUDE.md @@ -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 提供者，自动回退。 - -| 层级 | 位置 | 目的 | -| ---------- | ----------------------- | ---------------------------------------------------------------- | -| 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/` | 持久化对话内存 | - -Monorepo: `src/`（Next.js 16 应用），`open-sse/`（流媒体引擎工作区），`electron/`（桌面应用），`tests/`，`bin/`（CLI 入口点）。 +**OmniRoute** — 统一的 AI 代理/路由。一个端点接入 236 家 LLM 服务商，自动容灾。 + +| 层级 | 位置 | 用途 | +| ------------ | ----------------------- | ------------------------------------------------------------------------------------ | +| 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/`（流式引擎 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事件 +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` 的冒烟测试章节。 -- 护栏：`src/lib/guardrails/` → 文档：`docs/security/GUARDRAILS.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 中包含或更新测试。 + +**测试层级偏好**：单元测试优先 → 集成测试（多模块或数据库状态）→ E2E（仅 UI/工作流）。在修复 bug 之前或同时，将 bug 复现编码为自动化测试。 + +**两个测试运行器都必须通过**：`npm run test:unit`（Node 原生 — 大部分测试）和 `npm run test:vitest`（MCP 服务器、autoCombo、缓存）覆盖**不重叠的文件**。两者均在 CI 中连接（jobs `test-unit` 和 `test-vitest`），合并前必须都通过。一个只有单一套件通过的 PR 可能悄无声息地引入有问题的 MCP 工具或路由回退。 + +**Bug 修复 / Issue 分类协议（硬规则 #18）**：每个针对已报告 Issue 的修复必须通过以下之一验证 — 无例外： -**PR 规则**：如果您更改了 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码，您必须在同一 PR 中包含或更新测试。 +1. **TDD（首选）** — 编写复现 bug 的失败测试 → 修复 → 确认测试通过。该测试成为永久回归守卫。只修改测试能证明需要修改的文件，不多改。 +2. **真实环境测试（当 TDD 不可行时）** — 部署到生产 VPS (`root@192.168.0.15`)，执行有文档记录的真实测试。在 PR 描述中记录确切的命令和结果。适用于：OAuth 上游流程、Cloudflare/WS 上游行为、仅 UI 回退、硬件相关行为。 +3. "本地跑通但未写测试"不算数。没有测试或 VPS 验证记录的修复不算修复 — 只是猜测。 -**测试层级偏好**：单元测试优先 → 集成测试（多模块或数据库状态） → E2E（仅限 UI/工作流）。在修复之前或同时将错误重现编码为自动化测试。 +为什么这一点很重要：修复 bug A 的同时引入 bug B 比不修复更糟。TDD/VPS 门禁强制控制变更范围 — 你只改动失败测试证明有问题的地方。曾经见效的案例：#3090 (claude-web 403)、#3113 (WS HTTP fallback)、#3052 (heap-guard auto-calibration)。 -**Copilot 覆盖政策**：当 PR 更改生产代码且覆盖率低于 75%（语句/行/函数）或 70%（分支）时，不仅仅报告 — 添加或更新测试，重新运行覆盖门限，然后请求确认。在 PR 报告中包含运行的命令、已更改的测试文件和最终覆盖结果。 +**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-.md` | +| 方案 / 设计 (`brainstorming`) | `docs/superpowers/specs/` | `_tasks/superpowers/specs/YYYY-MM-DD--design.md` | +| 调研 (`deep-research`, 临时) | `docs/research/` | `_tasks/research/…` | +| 交接 (`/handoff`) | — | `_tasks/hands-off/__v_sess-/` | + +当 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 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/` 然后 `git branch -D `。绝不要通配删除 `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`） + +--- + +## 质量门禁与棘轮 + +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 模式验证输入 -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 ` 尾部进行署名；upstream-port 工作流（`/port-upstream-features`、`/port-upstream-issues`）依赖于此。 +## 硬规则 + +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 "，或任何 `Co-authored-by: Claude/GPT/Copilot` 行。此规则**覆盖任何自动追加此类页脚的框架、模板或工具默认行为**（例如 Claude Code PR 正文/commit 的默认页脚）— 在推送前将其剥离；不要让它进入 commit、PR 或 CHANGELOG。人类协作者 — 包括上游 PR 作者和被移植到 OmniRoute 的 Issue 报告者 — 可以且应该使用标准的 `Co-authored-by: Name ` 尾注署名；上游移植工作流（`/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 的原生测试运行器无限挂起。 diff --git a/docs/i18n/zh-CN/CODE_OF_CONDUCT.md b/docs/i18n/zh-CN/CODE_OF_CONDUCT.md index 595a165a16bb..61f3ac91139a 100644 --- a/docs/i18n/zh-CN/CODE_OF_CONDUCT.md +++ b/docs/i18n/zh-CN/CODE_OF_CONDUCT.md @@ -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. +可通过以下方式向负责执行的社区领导者举报辱骂、骚扰或其他不可接受的行为：在 创建私人安全建议，或发送电子邮件至维护者 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 获取。 diff --git a/docs/i18n/zh-CN/CONTRIBUTING.md b/docs/i18n/zh-CN/CONTRIBUTING.md index 59ed06cb8a59..a1d9d66669db 100644 --- a/docs/i18n/zh-CN/CONTRIBUTING.md +++ b/docs/i18n/zh-CN/CONTRIBUTING.md @@ -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: +### 构建产物布局 + +| 目录 | 内容 | 版本追踪 | +| --------- | ---------------------------------------------------------------------------- | -------- | +| `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/`）。 -- **Dashboard**: `http://localhost:20128/dashboard` -- **API**: `http://localhost:20128/v1` +默认地址： + +- **控制台**：`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 - -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) - -electron/ # Electron desktop app (cross-platform) +│ ├── components/ # React 组件（.tsx） +│ ├── constants/ # 服务商定义（177 个）、MCP 权限域、14 种路由策略 +│ ├── utils/ # 熔断器、清洗器、认证辅助函数 +│ └── validation/ # Zod v4 Schema +└── sse/ # SSE 代理流水线 + +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 桌面应用（跨平台） 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 - -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 +├── unit/ # Node.js 测试运行器（1,574 个测试文件） +├── integration/ # 集成测试 +├── e2e/ # Playwright 测试 +├── security/ # 安全测试 +├── translator/ # 翻译器专项测试 +└── load/ # 负载测试 + +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 +--- -- [ ] 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) +## Pull Request 检查清单 + +- [ ] 测试通过（`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 +## 发布 + +发布通过 `/generate-release` 工作流管理。当新的 GitHub Release 创建时，包会通过 GitHub Actions **自动发布到 npm**。 -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. +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/` 目录 diff --git a/docs/i18n/zh-CN/GEMINI.md b/docs/i18n/zh-CN/GEMINI.md index d800e588ab04..2a4b3d29efc9 100644 --- a/docs/i18n/zh-CN/GEMINI.md +++ b/docs/i18n/zh-CN/GEMINI.md @@ -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/.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 和当前凭证 — 这些信息存放于其个人密钥保管库中，不在本仓库内。 + +> 本文档旧版本中观察到的任何凭证均为非生产环境的演示值；应将其视为已泄露且不可复用。 diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index deb166045fd4..69f3e991d081 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -6,23 +6,23 @@
-OmniRoute 仪表板 +OmniRoute 控制台
# 🚀 OmniRoute — 免费 AI 网关 -### 永远不要停止开发。通过一个端点，将每个 AI 工具连接到 **231 个供应商** — **50+ 免费**。 +### 编码，永无止境。通过一个端点，让所有 AI 工具直连 **236 家服务商** — **50+ 家免费**。 -**将 Claude Code、Codex、Cursor、Cline、Copilot 和 Antigravity 连接到免费的 Claude / GPT / Gemini。自动故障转移。** +**将 Claude Code、Codex、Cursor、Cline、Copilot 和 Antigravity 接入免费的 Claude / GPT / Gemini。自动容灾，无感切换。**
-**RTK + Caveman 压缩可节省 15–95% 的 Token。永远不会达到限制。** +**RTK + Caveman 压缩引擎，Token 节省 15–95%。从此告别用量限制。**
-**~1.6B 有记录的免费 Token/月** — 首月通过注册奖励最高可达 **~2.1B** — 聚合所有免费层的配额，再加上永久免费、无上限的供应商，而上述压缩进一步延长每一分 Token。([统计方法 →](../../reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate)) +**约 1.6B 可统计免费 Token / 月** — 计入注册奖励后，首月最高可达 **~2.1B** — 聚合各家免费层配额，外加一众永久免费、不限量的服务商；再叠加上述压缩引擎，每一枚 Token 都物超所值。([统计方法 →](../../reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))
@@ -42,7 +42,7 @@ [![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) [![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI) -**问题、供应商技巧、路线图和支持 → [Discord](https://discord.gg/EkzRkpzKYt) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 全球](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 巴西](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)** +**疑难解答、服务商攻略、路线图与支持 → [Discord](https://discord.gg/EkzRkpzKYt) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 全球](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 巴西](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)**
@@ -66,9 +66,9 @@
-[**🚀 快速开始**](#-quick-start) • [**🎯 组合策略**](#-combos--the-flagship) • [**🌐 供应商**](#-231-ai-providers--50-free) • [**🔌 CLI 与 MCP**](#-full-cli--a2a--mcp) • [**🗜️ 压缩**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 网站**](https://omniroute.online) +[**🚀 快速开始**](#-quick-start) • [**🎯 Combo**](#-combos--the-flagship) • [**🌐 服务商**](#-231-ai-providers--50-free) • [**🔌 CLI 与 MCP**](#-full-cli--a2a--mcp) • [**🗜️ 压缩**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 官网**](https://omniroute.online) -[💥 承诺](#-the-promise) • [🤔 为什么](#-why-omniroute) • [🏆 优势](#-what-sets-omniroute-apart) • [🤖 兼容 CLI](#-compatible-clis--coding-agents) • [🖥️ 运行平台](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 隐私](#-private--local-first) • [🎬 实际演示](#-omniroute-in-action) • [📚 探索更多](#-explore-more) • [📧 支持](#-support--community) +[💥 我们的承诺](#-the-promise) • [🤔 为什么选择 OmniRoute](#-why-omniroute) • [🏆 核心优势](#-what-sets-omniroute-apart) • [🤖 兼容的编程工具](#-compatible-clis--coding-agents) • [🖥️ 运行平台](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 隐私优先](#-private--local-first) • [🎬 实机演示](#-omniroute-in-action) • [📚 探索更多](#-explore-more) • [📧 支持](#-support--community)
@@ -121,41 +121,41 @@
-# 💰 ~1.6B 免费 Token/月 +# 💰 约 1.6B 免费 Token / 月
-> 手动堆叠免费层很痛苦 — 数十个 SDK、数十个速率限制，且不清楚自己到底有多少配额。OmniRoute 将 **40+ 供应商池 / 500+ 模型**的**有记录**免费层聚合为一个真实数字，并在仪表板上实时展示 (`/dashboard/free-tiers`)。 - -- **~1.6B 免费 Token/月**（稳定） — 首月通过注册奖励最高可达 **~2.1B**。 -- **池去重，诚实** — 每个共享免费池只计算**一次**，因此标题不会被速率限制上限所夸大。（如果按全天候速率限制计算，可能会显示 ~10B；我们不发布那个数字。） -- **加上不可计数的** — 永久免费、无 Token 上限的供应商（SiliconFlow、Z.AI GLM-Flash、Kilo、OpenCode Zen…）以及 **$10 OpenRouter 充值**可解锁 **+24M/月**，两者分别列示，不会夸大标题数字。 -- **按模型细分**，当月**已用/剩余**实时显示，以及每个供应商的透明**条款标志**。 +> 手动凑各家免费额度有多痛苦 — 数十套 SDK、数十个速率限制，根本搞不清到底还剩多少。OmniRoute 将 **40+ 服务商池 / 500+ 模型**的**可核实**免费层聚合为一个真实的统一数字，并在控制台实时展示 (`/dashboard/free-tiers`)。 +> +> - **约 1.6B 免费 Token / 月**（稳定值） — 注册奖励加持下，首月最高约 **2.1B**。 +> - **去重统计，诚实透明** — 每个共享免费池只计**一次**，标题数字不被速率上限注水。若以全天候速率上限累算会得出 ~10B 的虚假数据，我们从不发布此类数字。 +> - **外加不可计数的部分** — 永久免费、无 Token 上限的服务商（SiliconFlow、Z.AI GLM-Flash、Kilo、OpenCode Zen…）以及 **$10 的 OpenRouter 充值**可解锁 **+24M/月**，二者独立列示，绝不混入标题数字。 +> - **逐模型明细**、当月**已用 / 剩余**实时显示，以及每家服务商的透明**条款标注**。 ![Free-Tier Budget card (preview mockup)](../../screenshots/free-tier-budget-card.svg) -> 预览模型 — 实际截图将在 `/dashboard/free-tiers` 页面验证后上线。完整方法（池去重、信用层级、供应商条款）：**[docs/reference/FREE_TIERS.md](../../reference/FREE_TIERS.md)**。 +> 示例预览 — 待 `/dashboard/free-tiers` 页面验证后替换为真实截图。完整统计方法（池去重、额度层级、服务商条款）：**[docs/reference/FREE_TIERS.md](../../reference/FREE_TIERS.md)**。
-# 💥 承诺 +# 💥 我们的承诺
-> 一个端点。**231 个供应商。** 永远不要停止构建 — 让 OmniRoute 选择最便宜且有效的方案。 +> 一个端点。**236 家服务商。** 编码不止步 — 让 OmniRoute 帮你选出最便宜且可用的那个。 - - - + + + - - - + + +
🚫 永远不会达到限制
跨 231 个供应商毫秒级自动故障转移。配额用尽？下一个供应商立即接管 — 零停机。		💸 节省高达 95% 的 Token
RTK + Caveman 堆叠压缩可削减 15–95% 的合格 Token（工具密集型会话平均约 89%）。		🆓 零成本开始
50+ 供应商提供免费层，11 个永久免费（Kiro、Qoder、Pollinations、LongCat…）。无需信用卡。		🚫 永不触达限制
横跨 236 家服务商的毫秒级自动切换。配额耗尽？下一家即刻接管 — 零停机。		💸 Token 节省高达 95%
RTK + Caveman 级联压缩可削减 15–95% 的可压缩 Token（工具密集型会话平均约 89%）。		🆓 零元起步
50+ 家服务商提供免费层，其中 11 家永久免费（Kiro、Qoder、Pollinations、LongCat…）。无需绑卡。
🔌 每个工具都兼容
16+ 编码代理 — Claude Code、Codex、Cursor、Cline、Copilot、Antigravity — 通过一个配置即可使用。		🧩 一个端点
OpenAI ↔ Claude ↔ Gemini ↔ Responses API 转换。将任何工具指向 /v1 即可使用。		🛡️ 生产级别
断路器、TLS 隐身、MCP（87 工具）、A2A、记忆、护栏、评估。14,965 个测试。		🔌 所有工具一网打尽
16+ 款编程助手 — Claude Code、Codex、Cursor、Cline、Copilot、Antigravity — 一套配置全搞定。		🧩 一个端点通吃
OpenAI ↔ Claude ↔ Gemini ↔ Responses API 无缝翻译。任意工具指向 /v1 即开即用。		🛡️ 生产级品质
熔断器、TLS 指纹伪装、MCP（87 工具）、A2A、记忆系统、安全护栏、评估框架。14,965 项测试。
@@ -168,36 +168,36 @@ -> 告别管理 10 个仪表板、失效的 API 密钥和意外账单的烦恼。 +> 告别在十个控制台之间疲于奔命、处理失效的 API 密钥和天降账单的日子。 -| ❌ 日常痛点 | ✅ OmniRoute 的解决方案 | +| ❌ 日常痛点 | ✅ OmniRoute 如何解决 | |---|---| -| 📉 订阅配额每月用不完就浪费 | **最大化订阅** — 追踪配额，在重置前用尽每个 Token | -| 🛑 速率限制中断编码 | **4 层自动故障转移** — 订阅 → API → 廉价 → 免费，毫秒级切换 | -| 🔥 工具输出消耗大量 Token | **RTK + Caveman 压缩** — 每次请求节省 15–95% 合格 Token | -| 💸 昂贵的 API（每个供应商 $20–50/月） | **成本优化路由** — 自动路由到最便宜的可行模型 | -| 🧰 每个 AI 工具需要不同的设置 | **一个端点，所有工具，一个仪表板** | -| 🌍 所在国家/地区封锁 AI | **3 层代理** + TLS 指纹隐身 — 从任何地方使用 AI | +| 📉 每月订阅配额用不完就浪费 | **压榨订阅价值** — 追踪配额，在重置前用尽每一枚 Token | +| 🛑 写到一半被限速打断 | **四层自动切换** — 订阅 → API Key → 廉价 → 免费，毫秒级接续 | +| 🔥 工具输出（`git diff`、`grep`、日志）狂烧 Token | **RTK + Caveman 压缩** — 每次请求可省 15–95% 可压缩 Token | +| 💸 昂贵的 API（每服务商 $20–50/月） | **成本优先路由** — 自动导向性价比最高的可用模型 | +| 🧰 每款 AI 工具各有一套繁琐配置 | **一个端点、一套配置、一个控制台** | +| 🌍 所在国家/地区封锁 AI | **三级代理** + TLS 指纹伪装 — 无论身在何方，AI 任你用 |
``` ┌──────────────────────────────────────────────────────────┐ -│ Your IDE / CLI (Claude Code, Cursor, Cline…) │ +│ 你的 IDE / CLI (Claude Code, Cursor, Cline…) │ └─────────────────────────┬──────────────────────────────────┘ │ http://localhost:20128/v1 ▼ ┌──────────────────────────────────────────────────────────┐ -│ OmniRoute — Smart Router │ -│ RTK + Caveman compression · 17 routing strategies │ -│ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │ +│ OmniRoute — 智能路由中枢 │ +│ RTK + Caveman 压缩 · 17 种路由策略 │ +│ 熔断器 · TLS 指纹伪装 · MCP · A2A · 安全护栏 │ └─────────────────────────┬──────────────────────────────────┘ ┌─────────────┬────┴────────┬─────────────┐ - ▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4 - SUBSCRIPTION API KEY CHEAP FREE + ▼ 第一梯队 ▼ 第二梯队 ▼ 第三梯队 ▼ 第四梯队 + 订阅 API Key 廉价 免费 Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder, Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations - quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on + 配额耗尽？ ───▶ 预算触顶？ ─▶ 预算触顶？ ─▶ 永久在线 ```
@@ -206,118 +206,119 @@
-# 🎯 Combo — 旗舰功能 +# 🎯 Combo — 招牌功能
-> **Combo** 是 OmniRoute **自动**路由的模型链。配额用尽、供应商失败或成本飙升 — Combo 自动滑动到下一个模型。**这就是 OmniRoute 不可中断的原因。** 🛡️ +> **Combo** 是 OmniRoute **自动**路由的模型接力链路。配额耗尽、服务商宕机或成本飙升 — Combo 自动滑向下一个模型，无声无息。**正是它让 OmniRoute 坚不可摧。** 🛡️ -### ⚡ 零配置 — 只需使用 `auto` +### ⚡ 零配置 — 只需设为 `auto` -无需创建 Combo。将模型设置为 `auto`（或变体），OmniRoute 会根据您连接的供应商实时评分构建虚拟 Combo： +无需预先配置 Combo。将模型 ID 设为 `auto`（或其变体），OmniRoute 会基于你已连接的服务商实时评分，自动构建虚拟 Combo： | 模型 ID | 优化目标 | |---|---| -| `auto` | 🎯 平衡默认（LKGP — 沿用上次好的供应商） | -| `auto/coding` | 🧑‍💻 代码生成优先质量权重 | +| `auto` | 🎯 均衡默认（LKGP — 沿用上次表现最好的服务商） | +| `auto/coding` | 🧑‍💻 代码质量优先 | | `auto/fast` | ⚡ 最低延迟优先 | -| `auto/cheap` | 💰 每 Token 最低价优先 | -| `auto/offline` | 🔋 最多配额/速率限制余量优先 | -| `auto/smart` | 🔭 质量优先 + 10% 探索以发现更好模型 | +| `auto/cheap` | 💰 单位 Token 成本最低优先 | +| `auto/offline` | 🔋 配额 / 限速余量最充裕优先 | +| `auto/smart` | 🔭 质量优先 + 10% 探索度以发现更优模型 | ## -### 🔀 或自行构建 — 17 种路由策略 +### 🔀 或亲手定制 — 17 种路由策略 -| 目标 | 策略 / Combo | +| 目标 | 对应策略 / 组合 | |---|---| -| 🥇 先用完订阅再付费 | `priority` / `fill-first` | -| ⚖️ 跨账户分散负载 | `round-robin` · `weighted` · `p2c` · `least-used` | -| 💸 始终选最便宜的可行模型 | `cost-optimized` · `auto/cheap` | -| 🧠 模型间移交长上下文 | `context-relay` · `context-optimized` | -| 🎲 随机/隐私路由 | `random` · `strict-random` | -| 🧬 分发到专家组 + 裁判合成 | `fusion` | +| 🥇 榨干订阅额度再用付费 | `priority` / `fill-first` | +| ⚖️ 跨账号均衡负载 | `round-robin` · `weighted` · `p2c` · `least-used` | +| 💸 永远选最便宜的可行模型 | `cost-optimized` · `auto/cheap` | +| 🧠 模型间接力传递长上下文 | `context-relay` · `context-optimized` | +| 🎲 随机 / 隐私路由 | `random` · `strict-random` | +| 🧬 多模型并行 + 裁判裁决 | `fusion` | | 📊 按剩余配额余量路由 | `reset-window` · `headroom` | -| 🤖 智能路由 | `auto`（9 因素评分）· `lkgp` · `reset-aware` | +| 🤖 智能自动 | `auto`（9 维度评分）· `lkgp` · `reset-aware` | -Auto-Combo 引擎根据 **9 个因素**（健康度、配额、成本、延迟、成功率、新鲜度…）为每个候选模型评分 — 参见 [`docs/routing/AUTO-COMBO.md`](../../routing/AUTO-COMBO.md)。 +Auto-Combo 引擎基于 **9 个维度**（健康度、配额、成本、延迟、成功率、新鲜度…）逐候选打分 — 详见 [`docs/routing/AUTO-COMBO.md`](../../routing/AUTO-COMBO.md)。 ## -### 🧱 内置弹性（3 个独立层） +### 🧱 内置三层容灾 -| 层 | 范围 | 作用 | +| 层级 | 作用范围 | 机制 | |---|---|---| -| 🔌 **断路器** | 整个供应商 | 停止重复调用上游失败的供应商；自动探测恢复 | -| 💤 **连接冷却** | 一个账户/密钥 | 跳过速率受限的密钥，其他密钥继续提供服务 | -| 🎯 **模型锁定** | 供应商 + 模型 | 仅隔离配额受限的模型，不影响整个连接 | +| 🔌 **熔断器** | 整家服务商 | 停止向上游持续失败的服务商发送请求；自动探测恢复 | +| 💤 **连接冷却** | 单个账号 / 密钥 | 跳过快触达速率上限的密钥，其余密钥继续服务 | +| 🎯 **模型隔离** | 服务商 + 模型 | 仅隔离单一配额耗尽的模型，不影响该服务商的其他连接 | ``` -Combo: "always-on" Strategy: priority - 1. cc/claude-opus-4-7 ← subscription (use it fully) - 2. cx/gpt-5.5 ← second subscription - 3. glm/glm-5.1 ← cheap backup ($0.5/1M) - 4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails) -Result: 4 layers of fallback = zero downtime +Combo: "always-on" 策略: priority + 1. cc/claude-opus-4-7 ← 订阅（先用满） + 2. cx/gpt-5.5 ← 第二订阅 + 3. glm/glm-5.1 ← 廉价备选 ($0.5/1M) + 4. kr/claude-sonnet-4.5 ← 免费、无限（永不断线） +结论: 四层容灾 = 零停机 ``` -📖 [Auto-Combo Engine](../../routing/AUTO-COMBO.md) · [Resilience Guide](../../architecture/RESILIENCE_GUIDE.md) +📖 [Auto-Combo 引擎](../../routing/AUTO-COMBO.md) · [容灾指南](../../architecture/RESILIENCE_GUIDE.md)
-# 🏆 OmniRoute 的独特优势 +# 🏆 OmniRoute 何以脱颖而出
-| 功能 | OmniRoute | 其他路由器 | +| 功能 | OmniRoute | 其他路由方案 | |---|---|---| -| 🌐 供应商数量 | **231** | 20–100 | -| 🆓 免费供应商 | **50+（11 个永久免费）** | 1–5 | -| 🔀 路由策略 | **17 种**（优先级、加权、成本优化、上下文中继、融合…） | 1–3 | -| 🗜️ Token 压缩 | **RTK + Caveman 堆叠（15–95%）** | 无 / 20–40% | -| 🧰 内置 MCP 服务器 | **87 个工具、3 种传输、30 个范围** | 少有 | +| 🌐 服务商数量 | **231** | 20–100 | +| 🆓 免费服务商 | **50+ （其中 11 家永久免费）** | 1–5 | +| 🔀 路由策略 | **17 种**（优先级、加权、成本优先、上下文中继、融合…） | 1–3 | +| 🗜️ Token 压缩 | **RTK + Caveman 级联（15–95%）** | 无 / 20–40% | +| 🧰 内置 MCP 服务器 | **87 个工具、3 种传输、30 个权限域** | 少见 | | 🤝 A2A 代理协议 | **6 项技能、JSON-RPC 2.0** | 无 | -| 🧠 记忆（FTS5 + 向量） | **支持** | 少有 | -| 🛡️ 护栏（PII、注入、视觉） | **支持** | 少有 | +| 🧠 记忆系统（FTS5 + 向量） | **原生支持** | 少见 | +| 🛡️ 安全护栏（PII、注入、视觉） | **原生支持** | 少见 | | ☁️ 云代理 | **Codex、Devin、Jules** | 无 | -| 🥷 TLS 指纹隐身 | **JA3/JA4 通过 wreq-js** | 无 | +| 🥷 TLS 指纹伪装 | **JA3/JA4 基于 wreq-js** | 无 | | 🖥️ 多平台 | **Web · 桌面 · Termux · PWA** | 仅 Web | -| 🌍 国际化 | **42 种语言环境** | 0–4 | +| 🌍 国际化 | **42 种语言** | 0–4 | -📊 与 LiteLLM、OpenRouter 和 Portkey 的详细比较 → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](../../comparison/OMNIROUTE_VS_ALTERNATIVES.md) +📊 与 LiteLLM、OpenRouter、Portkey 的详细对比 → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](../../comparison/OMNIROUTE_VS_ALTERNATIVES.md)
-# ✨ 新功能 +# ✨ 近期更新
-> **v3.8.20 → v3.8.38** 重点更新。完整记录见 [`CHANGELOG.md`](../../CHANGELOG.md)。 +> **v3.8.20 → v3.8.41** 重点更新。完整日志见 [`CHANGELOG.md`](../../CHANGELOG.md)。 -- **⚖️ Quota-Share 路由** — 一个专用的 Combo 策略，按可用配额跨账户分配负载：Deficit-Round-Robin 调度、每连接 `max_concurrent` 配合冷却等待队列、多窗口使用量桶（5h / 7d / 每模型）、每(密钥,模型)上限、会话粘性确保提示缓存完整性，以及基于上游 Token 使用标头的主动饱和检测。→ [Resilience Guide](../../architecture/RESILIENCE_GUIDE.md) -- **🛰️ 远程模式** — 通过范围访问令牌从任何机器驱动远程 OmniRoute（`omniroute connect` / `omniroute contexts` / `omniroute tokens`）。→ [Remote Mode](../../guides/REMOTE-MODE.md) -- **🧭 更智能的自动路由** — OpenRouter 风格的 `auto/:` Combo（如 `auto/coding:fast`、`auto/reasoning:pro`）、**Fusion** 策略（第 16 种 — 并行分发到多个模型，然后通过裁判合成）、**任务感知路由**（按任务类型选择最佳连接）、每请求 `X-Route-Model` 覆盖、实时 Arena-ELO + models.dev 模型智能、每步骤账户允许列表、供应商通配符 Combo 步骤、嵌套 Combo 引用执行、粘性加权选择以及 `web_search` 感知路由。→ [Auto-Combo](../../routing/AUTO-COMBO.md) -- **🗜️ 可插拔压缩** — **9 个可组合引擎**的异步流水线，带 Compression Studios、LLMLingua-2 ONNX 引擎和启发式/SLM 双层 **Ultra**、RTK、委托式 Anthropic 上下文编辑、**输出样式**（输出轴控制：简洁文章 / 少代码 / 简洁 CJK）、**自适应上下文预算拨盘**（仅扩展到适合上下文窗口所需的最低限度）、每请求 `x-omniroute-compression` 控制、可选的离线评估工具、仪表板上一键 **Headroom** 代理生命周期管理（支持 Docker 边车）、合成**压缩游乐场**（Play 赛道 + A/B 比较，附 USD 上限保真度判定）、可选的**每步骤保真度门控**（在损失性引擎降低提示质量前拒绝它），以及统一面板带命名配置文件 + 活动配置文件选择器。→ [Compression](../../compression/COMPRESSION_ENGINES.md) -- **🕵️ 透明 MITM 解密（TPROXY）** — 捕获并转换忽略代理环境变量的 CLI 流量，带每 SNI 证书颁发机构和信任存储安装程序。→ [MITM/TPROXY](../../security/MITM-TPROXY-DECRYPT.md) -- **💸 全方位成本遥测** — 每个端点上的 `X-OmniRoute-*` 成本/使用量标头（包括媒体）、非 Token 成本引擎、缓存命中 `X-OmniRoute-Cost-Saved` 标头，以及每密钥美元花费配额。→ [API Reference](../../reference/API_REFERENCE.md) -- **🧠 可控记忆** — 可选的 int8 向量量化（Qdrant + sqlite-vec）、默认关闭记忆、每请求 `x-omniroute-no-memory` 标头。→ [Memory](../../frameworks/MEMORY.md) -- **🛡️ 安全** — 所有 LLM 路由的提示注入防护（由红队套件支持），加上免费的 DuckDuckGo 最终手段网页搜索。→ [Guardrails](../../security/GUARDRAILS.md) -- **🤝 更多供应商和代理** — Cursor Cloud Agent（第 4 个云代理）、CodeBuddy CN（`copilot.tencent.com`）、Google Flow 视频生成供应商、新网关 **DGrid** 和 **Pioneer AI**（Fastino Labs）、入站 **xAI Grok** 转换器加 **Grok Build (xAI)**（带 OAuth 导入令牌流程）、GitHub Copilot 供应商上的 GPT-4 / GPT-4o-mini、多模型 **Factory Droid**、**ZenMux Free**（会话 Cookie 免费层）、**Alibaba DashScope** 文本转视频（`wan2.7-t2v`）、刷新后的 231 供应商目录（OrcaRouter、Wafer AI、OpenAdapter、dit.ai、TokenRouter…）、Vertex AI 媒体生成（语音/转录/音乐/视频），以及一键从 CLIProxyAPI 导入账户（`~/.cli-proxy-api/`）。→ [Providers](../../reference/PROVIDER_REFERENCE.md) -- **⚡ 本地性能与基础设施** — 一键本地 Redis 启动器（`omniroute redis up`，加仪表板 Redis 面板）、一键 **Cloudflare Workers** 和 **Deno Deploy** 中继部署器（连接到代理池），以及可选的 Bifrost Go 边车（卸载最热的中继路径，`BIFROST_BASE_URL`，超时时自动回退到 TypeScript 路径）。→ [Environment](../../reference/ENVIRONMENT.md) +- **⚖️ Quota-Share 路由** — 专用 Combo 策略，按可用配额跨账号分配负载：Deficit-Round-Robin 调度、每连接 `max_concurrent` 配合冷却等待队列、多时间窗口用量桶（5 小时 / 7 天 / 每模型）、每 (密钥, 模型) 用量上限、会话粘性保障 Prompt 缓存完整性，以及基于上游 Token 用量头的主动饱和检测。→ [容灾指南](../../architecture/RESILIENCE_GUIDE.md) +- **🤖 一键 CLI/Agent 配置** — 专用 `setup-*` 命令为各编程工具一键配置 OmniRoute 路由（Claude Code、Codex、Cline、Continue、Cursor、Roo Code、Kilo Code、Crush、Goose、Qwen Code、Aider、OpenCode）；`omniroute launch` / `omniroute launch-codex` 为零配置启动器。→ [CLI 集成](../../guides/CLI-INTEGRATIONS.md) +- **🛰️ 远程模式** — 通过授权范围 Token 从任意机器操控远程 OmniRoute（`omniroute connect` / `omniroute contexts` / `omniroute tokens`）；另附 `omniroute login antigravity` 辅助命令，在你的本机运行 Google "native/desktop" OAuth 后将凭证 blob 粘贴至远程/VPS 安装实例（因远程环境无法接收 loopback 回调）。→ [远程模式](../../guides/REMOTE-MODE.md) +- **🧭 更智能的自动路由** — OpenRouter 风格的 `auto/:` Combo（如 `auto/coding:fast`、`auto/reasoning:pro`）、**Fusion** 策略（并行分发至多模型面板后由裁判合成最优结果）、**任务感知路由**（按任务类型匹配最佳连接）、每请求 `X-Route-Model` 覆盖、实时 Arena-ELO + models.dev 模型智能评分、每步骤账号白名单、服务商通配符策略步骤、嵌套Combo引用执行、粘性加权选择以及 `web_search` 感知路由。→ [Auto-Combo](../../routing/AUTO-COMBO.md) +- **🗜️ 可插拔压缩体系** — **9 大可组合引擎**的异步流水线，含 Compression Studios、LLMLingua-2 ONNX 引擎和启发式/SLM 双层 **Ultra**、RTK、委托式 Anthropic 上下文编辑、**输出风格**（输出轴调控：简洁文章 / 少代码 / 简洁文言）、**自适应上下文预算旋钮**（仅推进到刚好适应上下文窗口的程度）、每请求 `x-omniroute-compression` 控制、可选离线评估套件、控制台一键 **Headroom** 代理生命周期管理（支持 Docker 边车）、合成**压缩演练场**（Play 通道 + A/B 对比，附 USD 上限保真度判定）、可选**每步保真度门控**（在有损引擎降低 Prompt 质量前将其拦截）、**Best-of-N 候选编码器**（GCF vs TOON — 取更短者，Studio 中附 A/B 字节/Token 对照表）、**CCR 范围/grep/统计检索**（直接拉取储存块的精确字节/行切片或摘要而无需全量展开），以及统一面板含命名配置文件 + 活动配置文件选择器。→ [压缩](../../compression/COMPRESSION_ENGINES.md) +- **🕵️ 透明 MITM 解密（TPROXY）** — 捕获并翻译忽略代理环境变量的 CLI 流量，含每 SNI 证书颁发机构和信任存储安装器。→ [MITM/TPROXY](../../security/MITM-TPROXY-DECRYPT.md) +- **💸 全方位成本遥测** — 每个端点上的 `X-OmniRoute-*` 成本/用量响应头（含媒体端点）、非 Token 成本引擎、缓存命中 `X-OmniRoute-Cost-Saved` 响应头，以及每密钥美元消费配额。→ [API 参考](../../reference/API_REFERENCE.md) +- **🧠 完全可控的记忆系统** — 可选 int8 向量量化（Qdrant + sqlite-vec）、默认关闭记忆、每请求 `x-omniroute-no-memory` 响应头。→ [记忆系统](../../frameworks/MEMORY.md) +- **🛡️ 安全** — 所有 LLM 路由的提示注入防护（后台有红队测试套件），外加免费的 DuckDuckGo 兜底网页搜索。→ [安全护栏](../../security/GUARDRAILS.md) +- **🤝 更多服务商与代理** — Cursor Cloud Agent（第四云代理）、CodeBuddy CN（`copilot.tencent.com`）、Google Flow 视频生成服务商、新网关 **DGrid** 和 **Pioneer AI**（Fastino Labs）、入站 **xAI Grok** 翻译器加 **Grok Build (xAI)**（含 OAuth 导入 Token 流程）、GitHub Copilot 服务商的 GPT-4 / GPT-4o-mini、多模型 **Factory Droid**、**ZenMux Free**（会话 Cookie 免费层）、**阿里云 DashScope** 文生视频（`wan2.7-t2v`）、刷新至 236 家服务商的目录（OrcaRouter、Wafer AI、OpenAdapter、dit.ai、TokenRouter…）、Vertex AI 媒体生成（语音/转录/音乐/视频），以及一键从 CLIProxyAPI 导入账号（`~/.cli-proxy-api/`）。→ [服务商](../../reference/PROVIDER_REFERENCE.md) +- **⚡ 本地性能与基础设施** — 一键本地 Redis 启动器（`omniroute redis up`，含控制台 Redis 面板）、一键 **Cloudflare Workers** 和 **Deno Deploy** 中继部署器（接入代理池），以及可选 Bifrost Go 边车将最热中继路径卸载至 Go 侧（`BIFROST_BASE_URL`，超时自动回退 TypeScript 路径）— 现支持中继后端选择器（`OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto`），`/v1/relay` 端点保持对外稳定接口的同时内部自动择取最快后端。→ [环境配置](../../reference/ENVIRONMENT.md)
-# 🤖 兼容的 CLI 和编码代理 +# 🤖 兼容的 CLI 与编程助手
-> 一个配置 — `http://localhost:20128/v1` — 每个 AI IDE 或 CLI 都可以在免费和低成本模型上运行。 +> 一个配置 — `http://localhost:20128/v1` — 所有 AI IDE 或 CLI 都能跑在免费与低成本模型上。
@@ -340,34 +341,34 @@ Result: 4 layers of fallback = zero downtime
-＋ 也可搭配 · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · 任何兼容 OpenAI 的工具 +＋ 同样兼容 · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · 任意兼容 OpenAI 格式的工具
-📖 所有 16+ 工具的逐个设置 → [`docs/reference/CLI-TOOLS.md`](../../reference/CLI-TOOLS.md) · 🧩 OpenCode 插件 → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider) +📖 16+ 款工具的逐项配置指南 → [`docs/reference/CLI-TOOLS.md`](../../reference/CLI-TOOLS.md) · 🧩 OpenCode 插件 → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)
-# 🌐 231 个 AI 供应商 — 50+ 免费 +# 🌐 231 家 AI 服务商 — 50+ 家免费
-> 最完整的开源路由器目录：**231 个供应商**、**50+ 具有免费层**、**11 个永久免费**。 +> 开源路由方案中最完整的服务商目录：**236 家服务商**、**50+ 家含免费层**、**11 家永久免费**。
-### 🆓 永久免费 — $0，无需信用卡 +### 🆓 永久免费 — 零元，无需绑卡
- - - - + + + + - + @@ -380,76 +381,76 @@ Result: 4 layers of fallback = zero downtime
-# 🖥️ OmniRoute 的运行平台 — 无处不在 +# 🖥️ OmniRoute 运行平台 — 无处不在
-> 相同的应用，您的机器，您的规则。从全局 npm 安装到通过 Termux **在手机上**运行。 +> 同一套应用，你的机器，你的规则。从全局 `npm install` 到**你的手机**（通过 Termux），无所不跑。 | 平台 | 安装方式 | 亮点 | |---|---|---| -| 📦 **npm（全局）** | `npm install -g omniroute` | 一条命令，任何操作系统 | -| 🐳 **Docker** | `docker run … diegosouzapw/omniroute` | 多架构 AMD64 + ARM64 | -| 🖥️ **桌面（Electron）** | `npm run electron:build` | 原生窗口 + 系统托盘 — Windows / macOS / Linux | -| 💪 **ARM** | 原生 `arm64` | Raspberry Pi、ARM 服务器、Apple Silicon | -| 📱 **Android（Termux）** | `pkg install nodejs-lts && npx -y omniroute` | **在手机上**运行，24/7，无需 Root | +| 📦 **npm（全局）** | `npm install -g omniroute` | 一行命令，任意 OS | +| 🐳 **Docker** | `docker run … diegosouzapw/omniroute` | 多架构 **AMD64 + ARM64** | +| 🖥️ **桌面（Electron）** | `npm run electron:build` | 原生窗口 + 系统托盘 — **Windows / macOS / Linux** | +| 💪 **ARM** | 原生 `arm64` | 树莓派、ARM 服务器、Apple Silicon | +| 📱 **Android（Termux）** | `pkg install nodejs && npx -y omniroute` | **在手机上** 7×24 运行，无需 Root | | 📲 **PWA** | "添加到主屏幕" | 全屏、离线、可从浏览器安装 | | 🧩 **OpenCode 插件** | `@omniroute/opencode-provider` | 原生 OpenCode 集成 | -| 🛠️ **从源码构建** | `npm install && npm run dev` | 参与开发 | +| 🛠️ **源码构建** | `npm install && npm run dev` | 动手改造，贡献代码 | -📖 [Docker Guide](../../guides/DOCKER_GUIDE.md) · [Desktop](../../electron/README.md) · [Termux](../../guides/TERMUX_GUIDE.md) · [PWA](../../guides/PWA_GUIDE.md) · [OpenCode](../../frameworks/OPENCODE.md) +📖 [Docker 指南](../../guides/DOCKER_GUIDE.md) · [桌面端](../../electron/README.md) · [Termux](../../guides/TERMUX_GUIDE.md) · [PWA](../../guides/PWA_GUIDE.md) · [OpenCode](../../frameworks/OPENCODE.md)
-# 🔒 私有与本地优先 +# 🔒 隐私优先，数据本地
-> 您的密钥、您的机器、您的数据。OmniRoute 是**本地代理** — 从不向外部报告。 +> 你的密钥、你的机器、你的数据。OmniRoute 是**本地代理** — 绝不会向外回传。 -- 🏠 **100% 在您的硬件上运行** — npm、Docker、桌面或手机。请求路径中不经过任何 OmniRoute 云。 -- 🔐 **凭证静态加密** — API 密钥和 OAuth 令牌使用 **AES-256-GCM** 加密。 -- 🚫 **默认零遥测** — 您的提示仅发送给您选择的供应商，不发送到其他地方。 -- 🛡️ **强化网关** — API 密钥范围限制、IP 过滤、速率限制、提示注入防护、仅回环进程路由。 -- 📜 **MIT 许可且完全开源** — 审计每一行代码，永久自托管。 +- 🏠 **100% 运行在本地硬件上** — npm、Docker、桌面端或你的手机。请求链路中不存在任何 OmniRoute 云端节点。 +- 🔐 **凭据静态加密** — API 密钥与 OAuth 令牌以 **AES-256-GCM** 封存。 +- 🚫 **默认零遥测** — 你的提示只发送给你选定的服务商，别无他处。 +- 🛡️ **网关加固** — API 密钥权限域、IP 过滤、速率限制、提示注入防护、仅限 loopback 的进程路由。 +- 📜 **MIT 协议、完全开源** — 逐行可审计，永久可自托管。 -📖 [Authorization](../../architecture/AUTHZ_GUIDE.md) · [Guardrails](../../security/GUARDRAILS.md) · [Compliance](../../security/COMPLIANCE.md) +📖 [授权管理](../../architecture/AUTHZ_GUIDE.md) · [安全护栏](../../security/GUARDRAILS.md) · [合规体系](../../security/COMPLIANCE.md)
-# 🔌 完整 CLI + A2A 和 MCP +# 🔌 完整 CLI + A2A 与 MCP
-> OmniRoute 不仅仅是服务器 — 它拥有 **60+ 命令**的**完整命令行控制台**，以及开放的代理协议，AI 代理可以**自行**驱动 OmniRoute。 +> OmniRoute 不只是一台服务器 — 它是拥有 **60+ 命令**的**全功能命令行驾驶舱**，外加开放的代理协议，让 AI 代理**自主**操控 OmniRoute。 -### ⌨️ 真正的 CLI（不仅仅是 `start`） +### ⌨️ 真正的 CLI（不止 `start`） ```bash -omniroute # 启动网关 + 仪表板（端口 20128） +omniroute # 启动网关 + 控制台（端口 20128） omniroute chat # 交互式 TUI 聊天客户端（斜杠命令：/model /combo /skill /memory） -omniroute setup # 引导式首次运行向导 -omniroute doctor # 诊断供应商、端口、原生依赖 +omniroute setup # 引导式首次设置向导 +omniroute doctor # 诊断服务商、端口、原生依赖 ``` -### 🛰️ 远程模式 — 在此处运行 CLI，OmniRoute 在 VPS 上 +### 🛰️ 远程模式 — CLI 在本地，OmniRoute 在远端的 VPS -OmniRoute 在服务器上？通过**相同的 CLI** 从笔记本电脑驱动它。登录一次，使用范围访问令牌；每个命令随后都指向远程。 +OmniRoute 跑在服务器上？用**同一套 CLI** 从笔记本远程操控。登录一次，绑定授权范围 Token；后续所有命令自动指向远端。 ```bash -omniroute connect 192.168.0.15 # 密码 → 范围令牌，保存为上下文 -omniroute models list # ← 在远程服务器上运行 -omniroute configure codex # ← 选择远程模型，写入本地 Codex 配置文件 -omniroute tokens create --name ci --scope read # 为其他机器铸造更窄范围的令牌 -omniroute contexts use default # ← 切换回本地服务器 +omniroute connect 192.168.0.15 # 密码 → 范围 Token，保存为上下文 +omniroute models list # ← 在远端服务器上执行 +omniroute configure codex # ← 选择远端模型，写入本地 Codex 配置文件 +omniroute tokens create --name ci --scope read # 为其他机器签发更窄范围的 Token +omniroute contexts use default # ← 切回本机服务器 ``` -令牌范围为 `read` / `write` / `admin`；生成进程的路由保持仅回环。 -📖 [Remote Mode](../../guides/REMOTE-MODE.md) +Token 权限域为 `read` / `write` / `admin`；涉及进程启动的路由仅限 loopback 执行。 +📖 [远程模式](../../guides/REMOTE-MODE.md)
@@ -457,107 +458,107 @@ omniroute contexts use default # ← 切换回本地服务器
-### 🤝 连接代理 — 代理自行控制 OmniRoute +### 🤝 接入 AI 代理 — 让代理自主操控 OmniRoute -通过 **MCP** 或 **A2A** 暴露 OmniRoute，任何有能力的代理都能获得整个网关的密钥 — 路由、供应商、Combo、缓存、压缩、记忆 — 自主运作。 +通过 **MCP** 或 **A2A** 协议暴露 OmniRoute，任何智能代理都能获得网关的完整控制权 — 路由、服务商、Combo、缓存、压缩、记忆 — 全自主运行。 | 协议 | 端点 | 用途 | |---|---|---| -| 🧰 **MCP（stdio）** | `omniroute --mcp` | 接入 Claude Desktop、Cursor 等 MCP 客户端 | -| 🌊 **MCP（HTTP）** | `http://localhost:20128/api/mcp/stream` | 远程 MCP — **87 个工具**、30 个范围、完整审计跟踪 | +| 🧰 **MCP（stdio）** | `omniroute --mcp` | 接入 Claude Desktop、Cursor 等各种 MCP 客户端 | +| 🌊 **MCP（HTTP）** | `http://localhost:20128/api/mcp/stream` | 远程 MCP — **87 个工具**、30 个权限域、完整审计追踪 | | 📡 **MCP（SSE）** | `http://localhost:20128/api/mcp/sse` | 流式 MCP 传输 | -| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | 代理间通信，**JSON-RPC 2.0** + SSE、6 项技能 | +| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | 代理间通信，**JSON-RPC 2.0** + SSE，6 项技能 | ```bash -# 给 Claude Code 完整的 OmniRoute 工具集，通过 MCP： +# 通过 MCP 将 OmniRoute 完整工具集赋予 Claude Code： claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream ``` -📖 [MCP Server](../../frameworks/MCP-SERVER.md) · [A2A Server](../../frameworks/A2A-SERVER.md) · [Agent Protocols](../../frameworks/AGENT_PROTOCOLS_GUIDE.md) +📖 [MCP 服务器](../../frameworks/MCP-SERVER.md) · [A2A 服务器](../../frameworks/A2A-SERVER.md) · [代理协议](../../frameworks/AGENT_PROTOCOLS_GUIDE.md)
-# 🗜️ 自动节省 15–95% 的 Token +# 🗜️ 自动节省 15–95% Token
-> **为什么用很多 Token 而不用少量 Token？** 每个请求**透明地**通过 OmniRoute 的压缩流水线 — 无需更改客户端。它现在是**9 个可组合引擎的堆栈**，按顺序运行并按路由 Combo 混合搭配 — 基于 [RTK](https://github.com/rtk-ai/rtk)、[Caveman](https://github.com/JuliusBrussee/caveman)（⭐ 51K+）、[LLMLingua-2](https://github.com/microsoft/LLMLingua) 和 [Troglodita](https://github.com/leninejunior/troglodita)（PT-BR）的理念构建。 +> **Token 够用就好，何必铺张浪费？** 每个请求**透明地**通过 OmniRoute 压缩流水线 — 客户端无需任何改动。现已升级为 **9 大可组合引擎**的级联体系，按 Combo 自由排列组合 — 凝聚了 [RTK](https://github.com/rtk-ai/rtk)、[Caveman](https://github.com/JuliusBrussee/caveman)（⭐ 51K+）、[LLMLingua-2](https://github.com/microsoft/LLMLingua) 和 [Troglodita](https://github.com/leninejunior/troglodita)（PT-BR）的技术精华。 -### 🧱 9 引擎堆栈 +### 🧱 九引擎级联体系 -引擎按流水线顺序运行；每个引擎可独立切换并按 Combo 配置： +引擎按流水线顺序执行；每个引擎均可独立启停，按 Combo 粒度配置： | # | 引擎 | 作用 | |---|---|---| -| 1 | **Session-Dedup** | 删除跨轮次重复的内容（内容寻址、跨轮次） | -| 2 | **CCR** | 将大块内容归档到检索标记后，按需获取 | -| 3 | **RTK** | 智能工具结果过滤、去重和截断（命令感知） | -| 4 | **Headroom** | 同构 JSON 数组的无损表格压缩（~30%+） | -| 5 | **Caveman** | 基于规则的文章压缩（输出约 65–75%） | -| 6 | **LLMLingua-2** | 通过 MobileBERT ONNX 进行 ML 语义剪枝 — 代码安全、异步 | -| 7 | **Lite** | 空白字符和图片 URL 修剪（低延迟基准） | -| 8 | **Aggressive** | 摘要 + 逐步淘汰旧轮次 | +| 1 | **Session-Dedup** | 剔除跨轮次重复的内容（基于内容寻址，跨轮次比对） | +| 2 | **CCR** | 将大文本块归档到检索标记后，按需拉取 | +| 3 | **RTK** | 智能工具输出过滤、去重与截断（理解命令语义） | +| 4 | **Headroom** | 同构 JSON 数组的无损表格式压缩（~30%+） | +| 5 | **Caveman** | 基于规则的叙述性文本压缩（输出端约 65–75%） | +| 6 | **LLMLingua-2** | 基于 MobileBERT ONNX 的 ML 语义剪枝 — 代码安全、异步 | +| 7 | **Lite** | 空白符 + 图片 URL 精简（低延迟基线） | +| 8 | **Aggressive** | 摘要浓缩 + 老旧轮次渐进式老化 | | 9 | **Ultra** | 启发式 Token 剪枝 + 可选小模型（SLM）层 | -代码块、URL 和结构化数据**始终按字节完美保留**。**一键预设**组合引擎： +代码块、URL 和结构化数据**永远逐字节原样保留**。**一键预设**快速组合引擎： -| 模式 | 节省比例 | 最佳用途 | +| 模式 | 节省比例 | 最佳场景 | |---|---|---| -| 🪶 **Lite** | ~15% | 始终开启的安全默认 | -| 🪨 **Standard（Caveman）** | ~30% | 日常编码 | +| 🪶 **Lite** | ~15% | 常驻开启的安全默认 | +| 🪨 **标准（Caveman）** | ~30% | 日常编码 | | ⚡ **Aggressive** | ~50% | 长时间工具密集型会话 | -| 🔥 **Ultra** | ~75% | 最大节省 | +| 🔥 **Ultra** | ~75% | 最大化节省 | | 🧰 **RTK** | 60–90% | Shell/测试/构建/Git 输出 | -| 🔗 **堆叠（RTK → Caveman）** | **78–95%** | 混合提示 + 工具日志 | +| 🔗 **级联（RTK → Caveman）** | **78–95%** | 混合提示 + 工具日志 | -**真实示例 — Standard 模式：** +**真实案例 — 标准模式：** -> **Before（69 Token）：** _"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."_ +> **压缩前（69 Token）：** _"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."_ > -> **After（19 Token）：** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_ +> **压缩后（19 Token）：** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_ > -> **相同的回答。减少了 72% 的 Token。精度零损失。** ✅ +> **同样的回答。节省 72% Token。精度毫无损失。** ✅ -**PT-BR 示例 — [Troglodita](https://github.com/leninejunior/troglodita) 模式：** +**PT-BR 案例 — [Troglodita](https://github.com/leninejunior/troglodita) 模式：** -> **Antes（42 Token）：** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_ +> **压缩前（42 Token）：** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_ > -> **Depois（12 Token）：** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_ +> **压缩后（12 Token）：** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_ > -> **相同的回答。~70% 更少的 Token。技术精度完整保留。** ✅ +> **同样的回答。约 70% 更少 Token。技术精度完好无损。** ✅
-### 📖 工作原理 — 流水线、架构与节省计算 +### 📖 工作原理 — 流水线、架构与节省量计算 ``` Client (10,000 tok) ──▶ OmniRoute Compression (9 engines) ──▶ Provider (~1,080 tok, 节省高达 95%) ``` -默认堆叠组合运行 `RTK → Caveman`。当两者同时作用于相同的工具/上下文负载时，节省效果叠加： +默认级联组合为 `RTK → Caveman`。当二者作用于同一工具/上下文负载时，节省效果叠加： ```txt -combined = 1 − (1 − RTK) × (1 − Caveman_input) -average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2% -range = 78.4 – 94.6% +组合节省率 = 1 − (1 − RTK) × (1 − Caveman_input) +平均值 = 1 − (1 − 0.80) × (1 − 0.46) = 89.2% +区间 = 78.4 – 94.6% ``` -代码块、URL、JSON 和结构化数据**始终受到**保留引擎的保护。 +代码块、URL、JSON 和结构化数据**始终受到**保护引擎的保全。 -### 🎚️ 超越引擎 — 输出样式、自适应拨盘与每请求控制 +### 🎚️ 引擎之外 — 输出风格、自适应旋钮与逐请求控制 -上面 9 个引擎缩小**输入**。还有三个更多层塑造**如何**、**何时**以及输出什么： +上述 9 大引擎负责压缩**输入**端。还有三个额外层面，分别控制**如何压**、**何时压**以及输出端的**效果**： -- **🪄 输出样式** _（输出轴控制）_ — 注入确定性、缓存安全的响应塑形指令；可组合，每个在 `lite` / `full` / `ultra` 强度。添加样式只需一行注册： - - **简洁文章** — 去掉填充词/冠词/含糊语；保持技术内容精确。 - - **少代码** — "懒惰高级开发者" YAGNI：最小可行更改，不请求不添加脚手架。 - - **简洁 CJK（文言）** — 文言文超简洁风格（仅限于 `zh` 语言环境）。 -- **🎯 自适应上下文预算** _（拨盘）_ — 不再使用单一的打开/关闭 Token 阈值，而是仅升级最便宜、无损的引擎，刚好到**适合模型的上下文窗口**所需程度。策略：`reserve-output`（默认，模型感知）· `percentage` · `absolute`。模式：`floor`（保证适合）· `replace-autotrigger`（您的明确选择优先）· `off`（传统阈值）。 -- **🎛️ 压缩决策位置** _（优先级，高 → 低）_ — 每请求 `x-omniroute-compression` 标头 › 路由 Combo 覆盖 › 活动命名配置文件 › 自适应/自动触发 › 面板默认 › 关闭。应用的方案在 `X-OmniRoute-Compression: ; source=` 响应标头中回显。 +- **🪄 输出风格** _（输出轴调控）_ — 注入确定性强、缓存友好的响应结构指令；可组合使用，每项提供 `lite` / `full` / `ultra` 三个强度档。添加风格只需一行注册代码： + - **简明文章** — 剔除填充词/冠词/暧昧语；技术实质精确传达。 + - **少即是多** — "经验丰富的高级开发" YAGNI 风格：最小化可用改动，不主动添加脚手架。 + - **文言简雅** — 仿文言文的极致简洁风格（区域锁定至 `zh`）。 +- **🎯 自适应上下文预算** _（调节旋钮）_ — 取代简单的开/关阈值，改为渐次递进：从最轻量、最无损的引擎开始，仅推进到刚好**适配目标模型上下文窗口**的程度。策略：`reserve-output`（默认，模型感知）· `percentage` · `absolute`。模式：`floor`（确保适配）· `replace-autotrigger`（你的显式选择优先）· `off`（传统阈值模式）。 +- **🎛️ 压缩决策的优先链路** _（从高到低）_ — 逐请求 `x-omniroute-compression` 头 › Combo 覆写 › 活动命名配置 › 自适应/自动触发 › 面板默认 › 关闭。最终采用的压缩方案会通过 `X-OmniRoute-Compression: ; source=` 响应头回显。 -通过 Token 阈值自动触发、拨动自适应拨盘、固定命名配置文件、为每个请求设置一次性压缩，或为每个路由 Combo 分配流水线 — 任选最适合工作负载的方式。可选的离线**评估工具**（`npm run eval:compression`）在固定语料库上评分保真度与节省效果，然后在您推广更改前使用。 +可依阈值自动触发、旋钮自适应调节、固定命名配置文件、逐请求一次性压缩，或为每条Combo 专属分配流水线 — 工作负载千差万别，总有一种适配。可选离线**评估套件**（`npm run eval:compression`）在固定语料集上量化评分，助你在推广变更前验证保真度与节省效果。 📖 [`COMPRESSION_GUIDE.md`](../../compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](../../compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](../../compression/COMPRESSION_ENGINES.md) @@ -576,40 +577,40 @@ npm install -g omniroute omniroute ``` -仪表板：`http://localhost:20128` · API：`http://localhost:20128/v1` +控制台：`http://localhost:20128` · API：`http://localhost:20128/v1` -**2) 连接免费供应商（无需注册）** +**2) 连接免费服务商（无需注册）** -仪表板 → **Providers** → 连接 **Kiro AI**（免费 Claude，约 50 积分/月/账户）或 **OpenCode Free**（无需认证）→ 完成。 +控制台 → **Providers** → 连接 **Kiro AI**（免费 Claude，约 50 积分/月/账号）或 **OpenCode Free**（无需认证）→ 完成。 -**3) 配置您的编码工具** +**3) 配置你的编程工具** ```txt Base URL: http://localhost:20128/v1 -API Key: [从仪表板 → Endpoints 复制] -Model: auto （零配置智能路由 — 或任何供应商/模型） +API Key: [从 控制台 → Endpoints 复制] +Model: auto （零配置智能路由 — 也可指定任意服务商/模型） ``` -**4) 验证是否正常工作** +**4) 验证链路** ```bash -curl http://localhost:20128/v1/models -H "Authorization: Bearer *** +curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY" ``` -您应该能看到已连接的模型列表。🎉 搞定了 — 开始编码，OmniRoute 会自动路由和故障转移。 +你应该能看到已连接模型的列表。🎉 至此大功告成 — 开始编码，OmniRoute 自动路由、自动容灾。 -如果您的客户端无法发送自定义标头，OmniRoute 还提供令牌化兼容别名： +如果你的客户端无法发送自定义请求头，OmniRoute 也提供 Token 化兼容别名： ```txt -OpenAI 目录： http://localhost:20128/vscode/YOUR_KEY/ -OpenAI 模型： http://localhost:20128/vscode/YOUR_KEY/models -OpenAI 聊天： http://localhost:20128/vscode/YOUR_KEY/chat/completions -OpenAI 响应： http://localhost:20128/vscode/YOUR_KEY/responses -Ollama 聊天： http://localhost:20128/vscode/YOUR_KEY/api/chat -Ollama 标签： http://localhost:20128/vscode/YOUR_KEY/api/tags +OpenAI 模型目录： http://localhost:20128/vscode/YOUR_KEY/ +OpenAI 模型列表： http://localhost:20128/vscode/YOUR_KEY/models +OpenAI 聊天： http://localhost:20128/vscode/YOUR_KEY/chat/completions +OpenAI 响应： http://localhost:20128/vscode/YOUR_KEY/responses +Ollama 聊天： http://localhost:20128/vscode/YOUR_KEY/api/chat +Ollama 标签： http://localhost:20128/vscode/YOUR_KEY/api/tags ``` -仅用于无法附加 `Authorization: Bearer ***` 标头的客户端。标头认证是首选方式。 +仅限无法附带 `Authorization: Bearer ...` 头的客户端使用。标准请求头认证始终是推荐方式。
@@ -622,7 +623,7 @@ docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` -**🛠️ 从源码构建** +**🛠️ 源码构建** ```bash cp .env.example .env && npm install @@ -652,7 +653,7 @@ npm run dev devbox run npm run dev ``` -📖 [Docker Guide](../../guides/DOCKER_GUIDE.md) — Compose 配置文件、Caddy HTTPS、Cloudflare 隧道。 +📖 [Docker 指南](../../guides/DOCKER_GUIDE.md) — Compose 配置、Caddy HTTPS、Cloudflare 隧道。 **🦭 Podman** @@ -660,7 +661,7 @@ devbox run npm run dev # 1. 构建镜像 podman build --target runner-base -t omniroute:base . -# 2. 修复无 Root Podman 的数据目录权限 +# 2. 修复无 Root 权限 Podman 的数据目录权限 mkdir -p data && podman unshare chown 1000:1000 ./data # 3. 在 .env 中设置运行时，然后运行（参见 contrib/podman/ 中的 Quadlet） @@ -668,13 +669,13 @@ echo "CONTAINER_HOST=podman" >> .env podman compose --profile base up -d ``` -📖 [Podman Guide](../../contrib/podman/README.md) — Quadlet 设置、podman-compose、Quadlet。 +📖 [Podman 指南](../../contrib/podman/README.md) — Quadlet 设置、podman-compose、Quadlet。
-# 🎬 OmniRoute 实际演示 +# 🎬 实机演示
@@ -699,7 +700,7 @@ podman compose --profile base up -d
-> 🎬 **制作了关于 OmniRoute 的视频？** 通过链接打开 [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) 或 [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) — 我们会在这里展示它。 +> 🎬 **制作了关于 OmniRoute 的视频？** 通过链接创建 [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) 或 [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) — 我们将在本节予以展示。
@@ -711,106 +712,106 @@ podman compose --profile base up -d
-💰 价格一览与 $0 免费堆栈（11 个供应商） +💰 费用一览与零元免费栈（11 家服务商）
-| 层级 | 示例 | 成本 | +| 层次 | 举例 | 成本 | |---|---|---| -| 💳 **订阅** | Claude Code Pro / Codex / Copilot | $10–200/月 | -| 🔑 **API 密钥（免费层）** | NVIDIA NIM、Cerebras、Groq | **免费** | +| 💳 **订阅制** | Claude Code Pro / Codex / Copilot | $10–200/月 | +| 🔑 **API Key（含免费层）** | NVIDIA NIM、Cerebras、Groq | **免费** | | 💰 **廉价** | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | 几分钱 | | 🆓 **永久免费** | Kiro、Qoder、Qwen、Pollinations、LongCat | **$0** | -**$0 免费堆栈 — 组合成一个不可中断的 Combo：** +**零元免费栈 — 合并为一条坚不可摧的 Combo：** -| 供应商 | 前缀 | 免费模型 | 配额 | +| 服务商 | 前缀 | 免费模型 | 配额 | |---|---|---|---| | **Kiro** | `kr/` | Claude Sonnet 4.5、Haiku 4.5、Opus 4.6 | 50 积分/月 | | **Qoder** | `if/` | kimi-k2-thinking、qwen3-coder-plus、deepseek-r1 | ♾️ 无限 | | **Qwen** | `qw/` | qwen3-coder-plus/flash/next | ♾️ 无限 | | **Pollinations** | `pol/` | GPT-5、Claude、Gemini、DeepSeek、Llama 4 | 无需密钥 | -| **LongCat** | `lc/` | LongCat-Flash-Lite | 5 千万 Token/天 🔥 | -| **Cloudflare AI** | `cf/` | 50+ 模型 | 1 万神经元/天 | +| **LongCat** | `lc/` | LongCat-2.0 | 一次性 10M (需 KYC) | +| **Cloudflare AI** | `cf/` | 50+ 模型 | 10K 神经元/天 | | **NVIDIA NIM** | `nvidia/` | 129 个模型 | ~40 RPM | | **Cerebras** | `cerebras/` | Qwen3 235B、GPT-OSS 120B | 1M Token/天 | -> 💡 仪表板上的"成本"是**节省追踪器**，不是账单 — OmniRoute 从不向您收费。使用免费模型显示的"$290 总成本"意味着**节省了 $290**。 +> 💡 控制台上的"费用"是**节省追踪器**，而非账单 — OmniRoute 从不向你收费。显示"$290 总费用"意味着你使用免费模型**省下了 $290**。 -📖 完整免费目录 → [`docs/reference/FREE_TIERS.md`](../../reference/FREE_TIERS.md) — 25+ 供应商、配额、基本 URL。 +📖 完整免费服务商目录 → [`docs/reference/FREE_TIERS.md`](../../reference/FREE_TIERS.md) — 25+ 家服务商、配额、Base URL。
-🎯 用例 — 现成 Combo 剧本 +🎯 实用场景 — 即拿即用的 Combo 配方
-**$0 永久免费：** +**永久零元：** ``` -1. kr/claude-sonnet-4.5 (Kiro — ~50 积分/月/账户) +1. kr/claude-sonnet-4.5 (Kiro — ~50 积分/月/账号) 2. if/kimi-k2-thinking (Qoder — 无限) 3. pol/gpt-5 (Pollinations — 无需密钥) -4. lc/longcat-flash-lite (5 千万 Token/天 备用) -压缩：aggressive (~50%) → 翻倍您的免费配额 · 成本：$0/月 +4. lc/LongCat-2.0 (一次性 10M 备用，需 KYC) +压缩方案: aggressive (~50%) → 免费额度翻倍 · 成本: $0/月 ``` -**24/7 无中断：** 串联 2 个订阅 → 廉价 → 免费，5 层故障转移。 -**被封锁地区：** 免费供应商 + 全局/每供应商代理 → 从任何国家访问 AI。 -**最大节省：** 订阅 + 廉价备用 + `ultra` 压缩（~75%）→ 重度用户每月节省 ~$150–300。 +**7×24 无中断：** 串联 2 个订阅 → 廉价 → 免费，五层容灾。 +**地理封锁区：** 免费服务商 + 全局/按服务商代理 → 从任何国家访问 AI。 +**最大化节省：** 订阅 + 廉价备用 + `ultra` 压缩（~75%）→ 重度用户每月节省约 $150–300。
-🌍 绕过地理封锁 — 3 层代理 + 隐身 +🌍 绕过地理封锁 — 三级代理 + 隐身
-🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 在被封锁的地区？OmniRoute 的 **3 层代理**（全局/每供应商/每连接）代理 API 请求、OAuth 流程、连接测试、Token 刷新和模型同步。 +🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 身处受限地区？OmniRoute 的**三级代理体系**（全局 / 按服务商 / 按连接）代理 API 请求、OAuth 流程、连通性测试、Token 刷新和模型同步。 -- **协议：** HTTP/HTTPS、SOCKS5、认证代理 +- **协议：** HTTP/HTTPS、SOCKS5、需认证代理 - **🆓 1proxy 市场** — 数百个免费验证代理、质量评分、自动轮换 -- **反检测** — TLS 指纹欺骗（`wreq-js`）、CLI 指纹匹配、代理 IP 保持 +- **反检测** — TLS 指纹伪装（`wreq-js`）、CLI 指纹匹配、代理 IP 保持 📖 [`docs/ops/PROXY_GUIDE.md`](../../ops/PROXY_GUIDE.md)
-✨ 完整功能列表 — 30+ 能力（记忆、评估、可观测性） +✨ 完整功能清单 — 30+ 核心能力（记忆、评估、可观测性）
**路由：** 15 种策略 · 任务感知智能路由 · 思考预算控制 · 通配符路由 · 系统提示注入。 -**兼容性：** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · 自动 OAuth 刷新（PKCE、8 个供应商）· 多账户轮询 · Batch + Files API · 实时 OpenAPI 3.0。 -**协议：** MCP（87 工具、3 种传输、30 个范围）· A2A（JSON-RPC 2.0、SSE、6 项技能）· ACP · 云代理（Codex、Devin、Jules）。 -**插件：** 自定义插件市场（系统配置的注册 URL，带 SSRF 保护获取）· 安装/启用/禁用 · Notion + Obsidian 知识库集成（WebDAV 文件服务器、库搜索、笔记 CRUD）。 -**嵌入式服务：** 一键安装和生命周期管理本地边车服务（CLIProxy、NineRouter）。 -**质量与运维：** 内置 **Evals**（黄金集：精确/包含/正则/自定义）· 护栏（PII、注入、视觉）· 健康仪表板 · p50/p95/p99 遥测 · Webhooks · 合规审计。 -**AI 代理技能：** 即插即用 markdown 清单 — 将任何代理指向 `skills/*/SKILL.md` 清单。43 个可用技能。 +**兼容性：** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · 自动 OAuth 刷新（PKCE，8 家服务商）· 多账号轮询 · Batch + Files API · 实时 OpenAPI 3.0。 +**协议：** MCP（87 工具、3 种传输、30 个权限域）· A2A（JSON-RPC 2.0、SSE、6 项技能）· ACP · 云代理（Codex、Devin、Jules）。 +**插件：** 自定义插件市场（系统配置的注册 URL，带 SSRF 防护拉取）· 安装/启用/禁用 · Notion + Obsidian 知识库集成（WebDAV 文件服务器、仓库搜索、笔记 CRUD）。 +**嵌入式服务：** 一键安装与生命周期管理本地边车服务（CLIProxy、NineRouter）。 +**质量与运维：** 内置 **Evals** 评估框架（黄金标准集：精确匹配/包含/正则/自定义）· 安全护栏（PII 脱敏、注入防护、视觉桥接）· 健康监控面板 · p50/p95/p99 遥测 · Webhooks · 合规审计。 +**AI Agent 技能：** 即插即用的 Markdown 技能清单 — 将任意代理指向 `skills/*/SKILL.md` 清单。43 项可用技能。 -📖 [MCP Server](../../open-sse/mcp-server/README.md) · [A2A Server](../../src/lib/a2a/README.md) · [Resilience Guide](../../architecture/RESILIENCE_GUIDE.md) · [Features Gallery](../../guides/FEATURES.md) +📖 [MCP 服务器](../../open-sse/mcp-server/README.md) · [A2A 服务器](../../src/lib/a2a/README.md) · [容灾指南](../../architecture/RESILIENCE_GUIDE.md) · [功能画廊](../../guides/FEATURES.md)
-📖 设置、环境变量与 FAQ +📖 环境变量、设置与常见问题
| 环境变量 | 默认值 | 用途 | |---|---|---| -| `PORT` | `20128` | API + 仪表板端口 | -| `REQUIRE_API_KEY` | `false` | 是否需要 API 密钥 | -| `DATA_DIR` | `~/.omniroute` | 数据库和配置存储 | +| `PORT` | `20128` | API + 控制台端口 | +| `REQUIRE_API_KEY` | `false` | 是否要求所有请求携带 API Key | +| `DATA_DIR` | `~/.omniroute` | 数据库与配置存储路径 | -**OmniRoute 会向我收费吗？** 不会 — 它是免费的开源软件，运行在您的机器上。您只直接向付费供应商付款。OmniRoute 没有计费系统。 -**免费供应商真的无限吗？** 基本上是的 — Qoder、Pollinations、LongCat 和 Cloudflare 免费且无每账户信用上限。Kiro 也免费但限制为每月约 50 积分/账户。在 Combo 中堆叠多个免费供应商，自动故障转移让您可以以 $0 持续服务。 -**压缩会损害质量吗？** 不会 — 它只压缩**输入**；代码、URL、JSON 始终受到保护。 -**在被封锁 AI 的地区能用吗？** 可以 — 3 层代理 + 1proxy 市场可覆盖所有 231 个供应商。 +**OmniRoute 会向我收费吗？** 不会 — 它是运行在你本机的免费开源软件。你只直接向付费服务商付款。OmniRoute 不含任何计费系统。 +**免费服务商真的无限使用吗？** 绝大多数是 — Qoder、Pollinations、LongCat 和 Cloudflare 免费且无单账号额度上限。Kiro 也是免费，但每月每账号约 50 积分封顶。在 Combo 中叠加多家免费服务商，自动容灾确保零元持续可用。 +**压缩会影响输出质量吗？** 不会 — 它仅压缩**输入**端；代码、URL、JSON 永远保留不损。 +**AI 服务被封锁的地区能用吗？** 能 — 三级代理 + 1proxy 市场可覆盖全部 236 家服务商。 -📖 [User Guide](../../guides/USER_GUIDE.md) · [API Reference](../../reference/API_REFERENCE.md) · [Environment Config](../../reference/ENVIRONMENT.md) +📖 [用户指南](../../guides/USER_GUIDE.md) · [API 参考](../../reference/API_REFERENCE.md) · [环境配置](../../reference/ENVIRONMENT.md)
@@ -819,21 +820,21 @@ podman compose --profile base up -d
-| 问题 | 快速修复 | +| 问题 | 快速解决方案 | |---|---| -| "Language model did not provide messages" | 供应商配额用尽 → 使用 Combo 故障转移 | -| 速率限制（429） | 添加故障转移：`cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` | -| OAuth Token 过期 | 自动刷新；如果卡住，在 Providers 中删除并重新认证 | +| "Language model did not provide messages" | 服务商配额耗尽 → 使用 Combo 自动切换 | +| 速率限制（429） | 设置容灾链路：`cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` | +| OAuth Token 过期 | 自动刷新；若卡住，在 Providers 页面删除后重新认证 | | `unsupported_country_region_territory` | 在设置 → 代理中配置代理 | -| Docker SQLite 锁定 | 使用 `--stop-timeout 40` 进行干净的 WAL 检查点 | +| Docker SQLite 锁定 | 使用 `--stop-timeout 40` 确保干净的 WAL 检查点 | | Node 运行时错误 | 使用 Node `>=22.0.0 <23` 或 `>=24.0.0 <27` | -🐛 **报告 Bug？** 运行 `npm run system-info` 并附上 `system-info.txt`。📖 [`docs/guides/TROUBLESHOOTING.md`](../../guides/TROUBLESHOOTING.md) +🐛 **报告 Bug？** 运行 `npm run system-info` 并附上生成的 `system-info.txt`。📖 [`docs/guides/TROUBLESHOOTING.md`](../../guides/TROUBLESHOOTING.md)
-📸 仪表板截图 +📸 控制台截图
@@ -852,12 +853,12 @@ podman compose --profile base up -d # 📧 支持与社区 -> 💬 **与社区聊天** — Discord、Telegram 和 WhatsApp（🌍 / 🇧🇷）链接在 [本 README 顶部](#-加入社区)。 +> 💬 **与社区交流** — Discord、Telegram 和 WhatsApp（🌍 / 🇧🇷）链接详见 [本 README 顶部](#-加入社区)。 -- 🌍 **网站**：[omniroute.online](https://omniroute.online) +- 🌍 **官网**：[omniroute.online](https://omniroute.online) - 🐙 **GitHub**：[github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -- 🐛 **Issues**：[报告 Bug](https://github.com/diegosouzapw/OmniRoute/issues)（请附上 `npm run system-info` 输出） -- 🤝 **贡献**：参见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 或选择 `good first issue` +- 🐛 **Issues**：[报告 Bug](https://github.com/diegosouzapw/OmniRoute/issues)（请附上 `npm run system-info` 的输出结果） +- 🤝 **贡献**：参见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 或选取 `good first issue` @@ -871,20 +872,20 @@ podman compose --profile base up -d - **运行时**：Node.js 22.x 或 24.x LTS（推荐 24 LTS）— `>=22.0.0 <23 || >=24.0.0 <27` -- **语言**：TypeScript 6.0 — 跨 `src/` 和 `open-sse/` **100% TypeScript**（自 v2.0 起核心模块零 `any`） +- **语言**：TypeScript 6.0 — 跨 `src/` 和 `open-sse/` **100% TypeScript**（核心模块自 v2.0 起零 `any`） - **框架**：Next.js 16 + React 19 + Tailwind CSS 4 -- **数据库**：better-sqlite3 (SQLite) + LowDB（JSON 旧版）— 域状态、代理日志、MCP 审计、路由决策、记忆、技能 -- **架构**：Zod（MCP 工具 I/O 验证、API 合约） +- **数据库**：better-sqlite3 (SQLite) + LowDB（JSON 兼容）— 域状态、代理日志、MCP 审计、路由决策、记忆、技能 +- **模式校验**：Zod（MCP 工具 I/O 校验、API 合约） - **协议**：MCP（stdio/HTTP）+ A2A v0.3（JSON-RPC 2.0 + SSE） - **流式传输**：服务器推送事件（SSE）+ WebSocket 桥接（`/v1/ws`） -- **认证**：OAuth 2.0（PKCE）+ JWT + API 密钥 + MCP 范围授权 -- **测试**：Node.js 测试运行器 + Vitest（**14,965 个测试用例**，跨 517 个文件 — 单元、集成、E2E、安全、生态） -- **平台**：桌面（Electron）、Android（Termux）、PWA（任何浏览器） -- **CI/CD**：GitHub Actions（发布时自动 npm 发布 + Docker Hub） -- **网站**：[omniroute.online](https://omniroute.online) -- **包**：[npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **认证**：OAuth 2.0（PKCE）+ JWT + API Key + MCP 权限域授权 +- **测试**：Node.js 原生测试运行器 + Vitest（**14,965 个测试用例**，覆盖 517 个文件 — 单元、集成、E2E、安全、生态） +- **平台**：桌面端（Electron）、Android（Termux）、PWA（任意浏览器） +- **CI/CD**：GitHub Actions（Release 时自动发布至 npm + Docker Hub） +- **官网**：[omniroute.online](https://omniroute.online) +- **npm 包**：[npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) - **Docker**：[hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) -- **弹性**：断路器、指数退避、反惊群效应、TLS 欺骗、自动 Combo 自愈 +- **容灾**：熔断器、指数退避、防惊群效应、TLS 伪装、Auto-Combo 自愈
@@ -898,72 +899,72 @@ podman compose --profile base up -d | 文档 | 说明 | |---|---| -| [User Guide](../../guides/USER_GUIDE.md) | 供应商、Combo、CLI 集成、部署 | -| [Setup Guide](../../guides/SETUP_GUIDE.md) | 完整安装方法、CLI 工具配置、协议设置、超时调优 | -| [CLI Tools Guide](../../reference/CLI-TOOLS.md) | Claude Code、Codex、Cursor、Cline、OpenClaw、Kilo、Copilot 逐个工具设置 | -| [Remote Mode](../../guides/REMOTE-MODE.md) | 通过范围访问令牌从笔记本电脑 CLI 驱动远程 OmniRoute（VPS） | -| [Claude Code Config](../../guides/CLAUDE-CODE-CONFIGURATION.md) | 使用 `launch` + 每模型配置文件将 Claude Code 指向 OmniRoute | -| [Quick Start](../../README.md#-quick-start) | 3 步安装 → 连接 → 配置 | +| [用户指南](../../guides/USER_GUIDE.md) | 服务商、Combo、CLI 集成、部署 | +| [设置指南](../../guides/SETUP_GUIDE.md) | 全安装方法、CLI 工具配置、协议设置、超时调优 | +| [CLI 工具指南](../../reference/CLI-TOOLS.md) | Claude Code、Codex、Cursor、Cline、OpenClaw、Kilo、Copilot 逐工具配置 | +| [远程模式](../../guides/REMOTE-MODE.md) | 通过授权范围 Token 从笔记本 CLI 操控远端 OmniRoute（VPS） | +| [Claude Code 配置](../../guides/CLAUDE-CODE-CONFIGURATION.md) | 使用 `launch` + 按模型配置文件将 Claude Code 指向 OmniRoute（本地/远程） | +| [快速开始](../../README.md#-quick-start) | 三步搞定：安装 → 连接 → 配置 | ### 🔧 运维与部署 | 文档 | 说明 | |---|---| -| [Docker Guide](../../guides/DOCKER_GUIDE.md) | Docker 运行、Compose 配置文件、Caddy HTTPS、隧道、镜像标签 | -| [Podman Guide](../../contrib/podman/README.md) | Quadlet systemd 集成、podman-compose、SELinux | -| [VM Deployment](../../ops/VM_DEPLOYMENT_GUIDE.md) | 完整指南：VM + nginx + Cloudflare 设置 | -| [Fly.io Deployment](../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) | 部署到 Fly.io，带持久存储 | -| [Termux Guide](../../guides/TERMUX_GUIDE.md) | 在 Android 上通过 Termux 运行 OmniRoute | -| [PWA Guide](../../guides/PWA_GUIDE.md) | 渐进式 Web 应用安装、缓存、架构 | -| [Uninstall Guide](../../guides/UNINSTALL.md) | 所有安装方式的干净移除 | -| [Environment Config](../../reference/ENVIRONMENT.md) | 完整的 `.env` 变量和参考 | +| [Docker 指南](../../guides/DOCKER_GUIDE.md) | Docker 运行、Compose 配置、Caddy HTTPS、隧道、镜像标签 | +| [Podman 指南](../../contrib/podman/README.md) | Quadlet systemd 集成、podman-compose、SELinux | +| [虚拟机部署](../../ops/VM_DEPLOYMENT_GUIDE.md) | 完整指南：VM + nginx + Cloudflare 配置 | +| [Fly.io 部署](../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) | 部署至 Fly.io，含持久化存储 | +| [Termux 指南](../../guides/TERMUX_GUIDE.md) | 通过 Termux 在 Android 上运行 OmniRoute | +| [PWA 指南](../../guides/PWA_GUIDE.md) | 渐进式 Web 应用安装、缓存、架构 | +| [卸载指南](../../guides/UNINSTALL.md) | 所有安装方式的干净移除 | +| [环境配置](../../reference/ENVIRONMENT.md) | 完整 `.env` 变量与参考 | ### 🧠 功能与架构 | 文档 | 说明 | |---|---| -| [Architecture](../../architecture/ARCHITECTURE.md) | 系统架构、数据流和内部结构 | -| [Compression Guide](../../compression/COMPRESSION_GUIDE.md) | 7 选项流水线：off / lite / standard / aggressive / ultra / RTK / stacked | -| [RTK Compression](../../compression/RTK_COMPRESSION.md) | 命令输出压缩、过滤器、信任、验证、原始输出恢复 | -| [Compression Engines](../../compression/COMPRESSION_ENGINES.md) | Caveman、RTK、堆叠流水线、仪表板/API/MCP 界面 | -| [Compression Rules Format](../../compression/COMPRESSION_RULES_FORMAT.md) | Caveman 和 RTK 过滤器的 JSON 规则包架构 | -| [Compression Language Packs](../../compression/COMPRESSION_LANGUAGE_PACKS.md) | 语言检测和 Caveman 规则包创作 | -| [Resilience Guide](../../architecture/RESILIENCE_GUIDE.md) | 断路器、冷却、队列、反惊群效应、TLS 欺骗 | -| [Auto-Combo Engine](../../routing/AUTO-COMBO.md) | 9 因素评分、模式包、自愈 | -| [Proxy Guide](../../ops/PROXY_GUIDE.md) | 3 层代理系统、1proxy 市场、注册 CRUD | -| [Free Tiers](../../reference/FREE_TIERS.md) | 25+ 免费 API 供应商合并目录 | -| [Features Gallery](../../guides/FEATURES.md) | 带截图的视觉仪表板导览 | -| [Codebase Documentation](../../architecture/CODEBASE_DOCUMENTATION.md) | 新手友好的代码库介绍 | +| [架构](../../architecture/ARCHITECTURE.md) | 系统架构、数据流与内部机制 | +| [压缩指南](../../compression/COMPRESSION_GUIDE.md) | 七级选项流水线：off / lite / standard / aggressive / ultra / RTK / stacked | +| [RTK 压缩](../../compression/RTK_COMPRESSION.md) | 命令输出压缩、过滤器、信任、验证、原始输出恢复 | +| [压缩引擎](../../compression/COMPRESSION_ENGINES.md) | Caveman、RTK、级联流水线、控制台/API/MCP 操作界面 | +| [压缩规则格式](../../compression/COMPRESSION_RULES_FORMAT.md) | Caveman 和 RTK 过滤器的 JSON 规则包 Schema | +| [压缩语言包](../../compression/COMPRESSION_LANGUAGE_PACKS.md) | 语言检测与 Caveman 规则包编写 | +| [容灾指南](../../architecture/RESILIENCE_GUIDE.md) | 熔断器、冷却、队列、防惊群效应、TLS 伪装 | +| [Auto-Combo 引擎](../../routing/AUTO-COMBO.md) | 九维度评分、模式包、自愈 | +| [代理指南](../../ops/PROXY_GUIDE.md) | 三级代理体系、1proxy 市场、注册 CRUD | +| [免费服务商](../../reference/FREE_TIERS.md) | 25+ 家免费 API 服务商统一目录 | +| [功能画廊](../../guides/FEATURES.md) | 带截图的控制台视觉导览 | +| [代码库文档](../../architecture/CODEBASE_DOCUMENTATION.md) | 新手友好的代码库导览 | ### 🤖 协议与 API | 文档 | 说明 | |---|---| -| [API Reference](../../reference/API_REFERENCE.md) | 所有端点及示例 | -| [OpenAPI Spec](../../openapi.yaml) | OpenAPI 3.0 规范 | -| [MCP Server](../../open-sse/mcp-server/README.md) | 87 个 MCP 工具、IDE 配置、Python/TS/Go 客户端 | -| [MCP Server Guide](../../frameworks/MCP-SERVER.md) | MCP 安装、传输和工具参考 | -| [A2A Server](../../src/lib/a2a/README.md) | JSON-RPC 2.0 协议、技能、流式传输、任务管理 | -| [A2A Server Guide](../../frameworks/A2A-SERVER.md) | A2A 代理卡片、任务、技能和流式传输 | +| [API 参考](../../reference/API_REFERENCE.md) | 全端点含示例 | +| [OpenAPI 规范](../../openapi.yaml) | OpenAPI 3.0 规格 | +| [MCP 服务器](../../open-sse/mcp-server/README.md) | 87 个 MCP 工具、IDE 配置、Python/TS/Go 客户端 | +| [MCP 服务器指南](../../frameworks/MCP-SERVER.md) | MCP 安装、传输与工具参考 | +| [A2A 服务器](../../src/lib/a2a/README.md) | JSON-RPC 2.0 协议、技能、流式传输、任务管理 | +| [A2A 服务器指南](../../frameworks/A2A-SERVER.md) | A2A Agent Card、任务、技能与流式传输 | ### 📋 项目与质量 | 文档 | 说明 | |---|---| -| [Contributing](../../CONTRIBUTING.md) | 开发设置和指南 | -| [Changelog](../../CHANGELOG.md) | 完整的每版本发布历史 | -| [Security Policy](../../SECURITY.md) | 漏洞报告和安全实践 | -| [i18n Guide](../../guides/I18N.md) | 40+ 语言支持、翻译工作流、RTL | -| [Release Checklist](../../ops/RELEASE_CHECKLIST.md) | 发布前验证步骤 | -| [Coverage Plan](../../ops/COVERAGE_PLAN.md) | 测试覆盖策略和 14,965 测试套件 | +| [贡献指南](../../CONTRIBUTING.md) | 开发环境设置与规范 | +| [更新日志](../../CHANGELOG.md) | 完整按版本发布历史 | +| [安全策略](../../SECURITY.md) | 漏洞报告与安全实践 | +| [i18n 指南](../../guides/I18N.md) | 40+ 语言支持、翻译流程、RTL | +| [发布检查清单](../../ops/RELEASE_CHECKLIST.md) | 发布前验证步骤 | +| [测试覆盖计划](../../ops/COVERAGE_PLAN.md) | 测试覆盖策略与 14,965 测试套件 |
-# ⭐ 顶级贡献者 +# ⭐ 核心贡献者 -> OmniRoute 由充满激情的开源社区塑造。以下个人做出了卓越贡献，直接影响了项目的质量、稳定性和影响力。**感谢你们。** +> OmniRoute 由充满热情的开源社区共同塑造。以下同仁做出了卓越贡献，直接影响着项目的质量、稳定性与影响力。**衷心感谢。**
AgentRouter
GPT-5, Claude, Gemini
$100 免费额度		Qoder AI
Kimi-K2, DeepSeek-R1
无限免费		Pollinations
GPT-5, Claude, Llama 4
无需密钥		LongCat
Flash-Lite
5 千万 Token/天 🔥		AgentRouter
GPT-5、Claude、Gemini
$100 免费额度		Qoder AI
Kimi-K2、DeepSeek-R1
无限免费		Pollinations
GPT-5、Claude、Llama 4
无需密钥		LongCat
LongCat-2.0
一次性 10M Token (需 KYC) 🔑
Cloudflare AI
50+ 模型
1 万神经元/天		Cloudflare AI
50+ 模型
10K 神经元/天		 NVIDIA NIM
129 个模型
~40 RPM 免费		 Cerebras
Qwen3 235B
1M Token/天
@@ -972,7 +973,7 @@ podman compose --profile base up -d oyi77
oyi77
- 🥇 190 次提交 • +72K 行
+ 🥇 190 次提交 · +72K 行
分析引擎、SQL 聚合、
代理市场、测试覆盖
@@ -980,23 +981,23 @@ podman compose --profile base up -d Chris Staley
Chris Staley
- 🥈 72 次提交 • +5.7K 行
- SSE 流加固、Responses API、
Gemini 分页、测试回归修复 + 🥈 72 次提交 · +5.7K 行
+ SSE 流加固、Responses API、
Gemini 分页、回归修复 		zenobit
zenobit
- 🥉 62 次提交 • +24K 行
- CI/CD 流水线、33 种语言的 i18n、
Void Linux 包、平台修复 + 🥉 62 次提交 · +24K 行
+ CI/CD 流水线、33 种语言 i18n、
Void Linux 包、跨平台修复 		R.D. & Randi
R.D. & Randi
- 🏅 107 次提交 • +28K 行
+ 🏅 107 次提交 · +28K 行
Endpoints 页面、隧道集成、
Docker 工作流、A2A 状态、压缩 UI 		@@ -1004,13 +1005,13 @@ podman compose --profile base up -d benzntech
benzntech
- 🏅 20 次提交 • +7.5K 行
+ 🏅 20 次提交 · +7.5K 行
Electron 桌面应用、自动更新、
发布构建工作流、跨平台 CI
-> 🙏 这些贡献者的功能、Bug 修复和基础设施改进是 OmniRoute 可靠且功能丰富的**核心部分**。每个 Pull Request、每个测试用例、每个 i18n 翻译文件都很重要。开源由像他们这样的人构建。 +> 🙏 这些贡献者的功能、Bug 修复和基础设施改进，是 OmniRoute 可靠且功能丰富的**核心支柱**。每一个 Pull Request、每一个测试用例、每一个 i18n 翻译文件都意义重大。开源正是由他们这样的人建造的。
@@ -1028,18 +1029,18 @@ podman compose --profile base up -d ### 如何贡献 -1. Fork 仓库 +1. Fork 本仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 提交更改（`git commit -m 'Add amazing feature'`） -4. 推送到分支（`git push origin feature/amazing-feature`） +4. 推送分支（`git push origin feature/amazing-feature`） 5. 创建 Pull Request -参见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 获取详细指南。 +详见 [CONTRIBUTING.md](../../CONTRIBUTING.md) 获取完整开发指南。 ### 发布新版本 ```bash -# 创建发布 — npm 发布自动进行 +# 创建 Release — npm 发布将自动触发 gh release create v3.8.2 --title "v3.8.2" --generate-notes ``` @@ -1047,7 +1048,7 @@ gh release create v3.8.2 --title "v3.8.2" --generate-notes -OmniRoute 站在巨人的肩膀上。它始于 **[9router](https://github.com/decolua/9router)** 的一个 Fork 和 Go 项目 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** 的 TypeScript 移植 — 从此，下面的每个子系统都受到了先行开源项目的启发。每个项目都塑造了 OmniRoute 的具体部分。这是我们对所有项目的感谢。🙏 +OmniRoute 是站在巨人肩膀上的作品。它始于 **[9router](https://github.com/decolua/9router)** 的一个 Fork 以及 Go 项目 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** 的 TypeScript 移植 — 自此，以下每个子系统均受惠于先行者的开源成果。每一个项目都在 OmniRoute 中留下了具体印记。这是我们对所有项目的由衷感谢。🙏 -> ⭐ 星标数为 2026 年 6 月数据 — 去给这些项目加个星吧。 +> ⭐ 星标数为 2026 年 6 月数据 — 请给这些项目点颗星。 ### 🧬 渊源与网关 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| -| **[9router](https://github.com/decolua/9router)** · decolua | 17.9k | 此 Fork 所基于的原始项目 — 在此扩展了多模态 API 和完整的 TypeScript 重写。 | -| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 37.8k | 启发此 JavaScript/TypeScript 移植的 Go 实现。 | -| **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 50.8k | AI 网关，其公开定价数据集为我们的成本追踪同步提供数据，其供应商规范化模型启发了我们的路由。 | +| **[9router](https://github.com/decolua/9router)** · decolua | 17.9k | 此 Fork 所基于的原型项目 — 此处扩展了多模态 API 并完成了全面 TypeScript 重写。 | +| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 37.8k | 启发本 JavaScript/TypeScript 移植版的 Go 语言实现。 | +| **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 50.8k | AI 网关，其公开定价数据集为我们提供成本同步数据，其服务商规范化模型启发了我们的路由体系。 | ### 🗜️ 上下文与 Token 压缩 — 引擎 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| -| **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 74.5k | "为什么用很多 Token 而不用少量 Token" 的爆款项目 — 其原始人语言哲学驱动我们的标准压缩模式和 30+ 填充词/浓缩规则。 | -| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai | 63.6k | 高性能命令输出压缩 — 启发了我们的 RTK 引擎、JSON 过滤器 DSL、原始输出恢复和堆叠 RTK → Caveman 流水线。 | -| **[headroom](https://github.com/chopratejas/headroom)** · chopratejas | 33.6k | 可逆上下文压缩（SmartCrusher）— 启发了我们的 `headroom` 引擎和 `ccr` 检索标记模式。 | -| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.3k | 提示压缩研究（LLMLingua / LLMLingua-2）— 启发了我们的异步、代码安全、失败开放 `llmlingua` 引擎。 | -| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 27 | JS/ONNX 移植（MobileBERT / XLM-RoBERTa），用作我们 LLMLingua 引擎的工作线程后端。 | -| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 15 | PT-BR Token 压缩 — 驱动我们的 pt-BR 语言包：针对巴西葡萄牙语语法优化的赘语减少和填充词移除。 | -| **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 51.4k | "懒惰高级开发者" YAGNI 编码技能 — 启发了我们的 **少代码** 输出样式：最小工作更改引导，减少生成代码。 | +| **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 74.5k | "Token 够用就好"爆款项目 — 其原始人风格哲学驱动着我们的标准压缩模式及 30+ 条填充词/凝练规则。 | +| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai | 63.6k | 高性能命令输出压缩 — 启发了我们的 RTK 引擎、JSON 过滤器 DSL、原始输出恢复及 RTK → Caveman 级联流水线。 | +| **[headroom](https://github.com/chopratejas/headroom)** · chopratejas | 33.6k | 可逆上下文压缩（SmartCrusher）— 启发了我们的 `headroom` 引擎及 `ccr` 检索标记模式。 | +| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.3k | 提示压缩研究（LLMLingua / LLMLingua-2）— 启发了我们的异步、代码安全、Fail-Open 的 `llmlingua` 引擎。 | +| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 27 | JS/ONNX 移植（MobileBERT / XLM-RoBERTa），用作我们 LLMLingua 引擎的 Worker Thread 后端。 | +| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 15 | PT-BR Token 压缩 — 驱动我们的 pt-BR 语言包：针对巴西葡萄牙语语法调优的赘语消减与填充词移除。 | +| **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 51.4k | "经验丰富的高级开发" YAGNI 编码技能 — 启发了我们的**少即是多**输出风格：最小化可用改动引导，减少生成代码量。 | ### 🧩 紧凑格式、Token 研究与代码感知工具 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| -| **[TOON](https://github.com/toon-format/toon)** · toon-format | 24.6k | Token 导向对象表示法 — 其列式、表头加行模型塑造了我们的表格压缩阶段。 | -| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 11 | 架构感知的"LLM 版 JSON"表示法 — 共同启发了我们使用 `[N rows]` 标记的无损同构数组压缩。 | -| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 6.1k | TypeScript 编译器 API 工具包 — 启发了我们基于解析器的注释移除，保留字符串、模板和正则字面量。 | +| **[TOON](https://github.com/toon-format/toon)** · toon-format | 24.6k | Token 导向对象表示法 — 其列式、表头加行的数据模型塑造了我们的表格式压缩阶段。 | +| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 11 | 模式感知的"LLM 专用 JSON"表示法 — 共同启发了我们带 `[N rows]` 标记的无损同构数组压缩。 | +| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples | 409 | Brotli/SQLite 缓存 + 按会话上下文增量 — 启发了我们的 `session-dedup` 引擎。 | +| **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 993 | Bash 输出压缩 + MCP 配置文件 — 启发了我们的压缩安全回退机制及 MCP 工具清单简化。 | +| **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 103 | 内容感知、按文件类型输出压缩及故障感知回退 — 验证了我们的按类型分发和最低收益跳过策略。 | +| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh | 1.4k | "发现隐藏 Token" — 其卸载+可恢复句柄模式启发了我们的 CCR 卸载思路。 | +| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 1 | 会话图 + 跨轮次行去重蓝图，启发了我们的 session-dedup 设计。 | +| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas | 2 | Rust 列式 JSON + 内容寻址检索 + 跨消息去重 — 验证了我们 `headroom`/`ccr`/`session-dedup` 引擎设计及"压缩形态位置无关"的缓存稳定不变量。 | +| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs | 80 | MCP 工具 Schema/描述压缩 — 启发了我们的 MCP 工具清单基数缩减。 | +| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 182 | Aider 风格仓库地图排序 — 启发了我们的仓库地图/检索排序探索。 | +| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson | 4 | 基于 MCP 的声明式 Shell 输出缩减 — 验证了我们的声明式 Bash 输出压缩。 | +| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 6.1k | TypeScript 编译器 API 工具包 — 启发了我们基于解析器的注释移除，完整保留字符串、模板和正则字面量。 | ### 🧠 记忆与 RAG | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| | **[Mem0](https://github.com/mem0ai/mem0)** · mem0ai | 58.9k | 通用记忆层 — 其代理即写入/读取边界模型塑造了我们的记忆架构。 | -| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.4k | 具有分层记忆的有状态代理 — 启发了我们的上下文控制与恢复（CCR）分层模型。 | +| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.4k | 具备分层记忆的有状态代理 — 启发了我们的上下文控制与恢复（CCR）分层模型。 | +| **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 1.8k | 16 种常见 RAG/LLM 失效模式的 ProblemMap 分类法 — 构成了我们故障排除指南的共享词汇。 | ### 🛰️ 流量检查、MITM 与透明代理 | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| -| **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** · chouzz | 46 | 编码助手 ↔ LLM 流量的 MITM 拦截/分析 — 我们的流量检查器移植了其 SSE 合并、对话归一化、主机穿透和秘密掩码。 | -| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.1k | 透明的每进程代理路由 — 启发了我们的崩溃安全 MITM 拆卸、套接字空闲超时、`/proc` 进程归属和 TPROXY 捕获。 | +| **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** · chouzz | 46 | 编码助手 ↔ LLM 流量 MITM 拦截/分析 — 我们的流量检查器移植了其 SSE 合并、对话归一化、主机透传及密钥掩码方案。 | +| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.1k | 透明每进程代理路由 — 启发了我们崩溃安全的 MITM 拆卸、Socket 空闲超时、`/proc` 进程归因及 TPROXY 捕获。 | ### 📚 模型数据、可观测性与 UI | 项目 | ⭐ | 对 OmniRoute 的启发 | |---|---|---| -| **[models.dev](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 5.1k | AI 模型规格、定价和能力的开放数据库 — 原生同步到我们的模型目录。 | -| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.1k | 驱动我们实时 Compression Studio 和 Combo/Routing Studio 的基于节点的图形库。 | +| **[models.dev](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 5.1k | AI 模型规格、定价与能力的开放数据库 — 原生同步至我们的模型目录。 | +| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.1k | 驱动我们实时 Compression Studio 及 Combo/Routing Studio 的基于节点的图形库。 | +| **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 35.1k | LangGraph Studio 的实时工作流图形可视化启发了我们 Studios 的实时级联视图。 | | **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 29.3k | 其 trace → span → generation 可观测性模型塑造了我们的 Compression Studio 瀑布图。 | -| **[lobe-icons](https://github.com/lobehub/lobe-icons)** · LobeHub | 2.1k | 在仪表板上渲染供应商图标的 AI/LLM 品牌徽标。 | +| **[Kiali](https://github.com/kiali/kiali)** · Kiali | 3.6k | Istio 服务网格可观测性 — 启发了我们 Routing/Combo Studio 中的熔断器徽章和错误边界可视化。 | +| **[lobe-icons](https://github.com/lobehub/lobe-icons)** · LobeHub | 2.1k | AI/LLM 品牌图标，渲染控制台中各服务商标识。 | + +### 🛡️ 安全 + +| 项目 | ⭐ | 对 OmniRoute 的启发 | +|---|---|---| +| **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** · tldrsec | 708 | 一份精选的安全默认库清单，指导我们的安全技术选型（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。 | ## ❤️ 支持 -OmniRoute 是免费且开源的，在公开环境中构建和维护。如果它为您节省了时间或金钱，请考虑支持其开发： +OmniRoute 是免费开源项目，在公开环境中持续构建与维护。如果它帮你节省了时间或金钱，请考虑以以下方式支持开发： -- ⭐ **为仓库加星** — 这确实有助于提高能见度 -- 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — 资助持续维护和新供应商 -- 🐛 **在 [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions) 中报告 Bug 和分享反馈** +- ⭐ **为本仓库加颗 Star** — 这确确实实能帮我们提升可见度 +- 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — 资助持续维护和新服务商接入 +- 🐛 **在 [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions) 中反馈 Bug 和分享意见** ## 📄 许可证 -MIT 许可证 — 详情见 [LICENSE](../../LICENSE)。 +MIT 协议 — 详见 [LICENSE](../../LICENSE)。 ---
-**[⬆ 返回顶部](#-omniroute)** · 为开源 AI 社区用心构建。 +**[⬆ 返回顶部](#-omniroute)** · 用 ❤️ 为开源 AI 社区构建。 OmniRoute v3.8.24 · Node ≥22.0.0 · MIT License · omniroute.online diff --git a/docs/i18n/zh-CN/SECURITY.md b/docs/i18n/zh-CN/SECURITY.md index 1aaed8f3d57b..a4ce8ea52a76 100644 --- a/docs/i18n/zh-CN/SECURITY.md +++ b/docs/i18n/zh-CN/SECURITY.md @@ -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:::` -- Passthrough mode (plaintext) when `STORAGE_ENCRYPTION_KEY` is not set +- API Key、访问 Token、刷新 Token 和 ID Token +- 版本化格式：`enc:v1:::` +- 未设置 `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) — 精选的安全默认库 diff --git a/docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md b/docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md index 7d91fd6ad72a..98d801e5a3f2 100644 --- a/docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md +++ b/docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md @@ -1,122 +1,162 @@ -# OmniRoute Architecture (中文 (简体)) +--- +title: "OmniRoute 架构" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- + +# OmniRoute 架构 🌐 **Languages:** 🇺🇸 [English](../../../../docs/ARCHITECTURE.md) · 🇸🇦 [ar](../../ar/docs/ARCHITECTURE.md) · 🇧🇬 [bg](../../bg/docs/ARCHITECTURE.md) · 🇧🇩 [bn](../../bn/docs/ARCHITECTURE.md) · 🇨🇿 [cs](../../cs/docs/ARCHITECTURE.md) · 🇩🇰 [da](../../da/docs/ARCHITECTURE.md) · 🇩🇪 [de](../../de/docs/ARCHITECTURE.md) · 🇪🇸 [es](../../es/docs/ARCHITECTURE.md) · 🇮🇷 [fa](../../fa/docs/ARCHITECTURE.md) · 🇫🇮 [fi](../../fi/docs/ARCHITECTURE.md) · 🇫🇷 [fr](../../fr/docs/ARCHITECTURE.md) · 🇮🇳 [gu](../../gu/docs/ARCHITECTURE.md) · 🇮🇱 [he](../../he/docs/ARCHITECTURE.md) · 🇮🇳 [hi](../../hi/docs/ARCHITECTURE.md) · 🇭🇺 [hu](../../hu/docs/ARCHITECTURE.md) · 🇮🇩 [id](../../id/docs/ARCHITECTURE.md) · 🇮🇹 [it](../../it/docs/ARCHITECTURE.md) · 🇯🇵 [ja](../../ja/docs/ARCHITECTURE.md) · 🇰🇷 [ko](../../ko/docs/ARCHITECTURE.md) · 🇮🇳 [mr](../../mr/docs/ARCHITECTURE.md) · 🇲🇾 [ms](../../ms/docs/ARCHITECTURE.md) · 🇳🇱 [nl](../../nl/docs/ARCHITECTURE.md) · 🇳🇴 [no](../../no/docs/ARCHITECTURE.md) · 🇵🇭 [phi](../../phi/docs/ARCHITECTURE.md) · 🇵🇱 [pl](../../pl/docs/ARCHITECTURE.md) · 🇵🇹 [pt](../../pt/docs/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) · 🇷🇴 [ro](../../ro/docs/ARCHITECTURE.md) · 🇷🇺 [ru](../../ru/docs/ARCHITECTURE.md) · 🇸🇰 [sk](../../sk/docs/ARCHITECTURE.md) · 🇸🇪 [sv](../../sv/docs/ARCHITECTURE.md) · 🇰🇪 [sw](../../sw/docs/ARCHITECTURE.md) · 🇮🇳 [ta](../../ta/docs/ARCHITECTURE.md) · 🇮🇳 [te](../../te/docs/ARCHITECTURE.md) · 🇹🇭 [th](../../th/docs/ARCHITECTURE.md) · 🇹🇷 [tr](../../tr/docs/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) · 🇵🇰 [ur](../../ur/docs/ARCHITECTURE.md) · 🇻🇳 [vi](../../vi/docs/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) --- -_Last updated: 2026-04-15_ - -## Executive Summary - -OmniRoute is a local AI routing gateway and dashboard built on Next.js. -It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. - -Core capabilities: - -- OpenAI-compatible API surface for CLI/tools (100+ providers, 16 executors) -- Request/response translation across provider formats -- Model combo fallback (multi-model sequence) -- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers` -- Account-level fallback (multi-account per provider) -- Quota preflight and quota-aware P2C account selection in the main chat path -- OAuth + API-key provider connection management (13 OAuth modules) -- Embedding generation via `/v1/embeddings` (6 providers, 9 models) -- Image generation via `/v1/images/generations` (10+ providers, 20+ models) -- Audio transcription via `/v1/audio/transcriptions` (7 providers) -- Text-to-speech via `/v1/audio/speech` (10 providers) -- Video generation via `/v1/videos/generations` (ComfyUI + SD WebUI) -- Music generation via `/v1/music/generations` (ComfyUI) -- Web search via `/v1/search` (5 providers) -- Moderations via `/v1/moderations` -- Reranking via `/v1/rerank` -- Think tag parsing (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developer→system, system→user) for cross-provider compatibility -- Structured output conversion (json_schema → Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing (26 DB modules) -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: cost rules, fallback policy, lockout policy -- Context Relay: session handoff summaries for account rotation continuity -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout → budget → fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Combo target telemetry and historical combo target health via `combo_execution_key` / `combo_step_id` -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Health dashboard with real-time provider circuit breaker status -- MCP Server (25 tools) with 3 transports (stdio/SSE/Streamable HTTP) -- A2A Server (JSON-RPC 2.0 + SSE) with skills and task lifecycle -- Memory system (extraction, injection, retrieval, summarization) -- Skills system (registry, executor, sandbox, built-in skills) -- MITM proxy with certificate management and DNS handling -- Prompt injection guard middleware -- ACP (Agent Communication Protocol) registry -- Modular OAuth providers (13 individual modules under `src/lib/oauth/providers/`) -- Uninstall/full-uninstall scripts -- OAuth environment repair action -- WebSocket bridge for OpenAI-compatible WS clients (`/v1/ws`) -- Sync token management (issue/revoke, ETag-versioned config bundle download) -- GLM Thinking (`glmt`) first-class provider preset -- Hybrid token counting (provider-side `/messages/count_tokens` with estimation fallback) -- Model alias auto-seeding (30+ cross-proxy dialect normalizations at startup) -- Safe outbound fetch with SSRF guard, private URL blocking, and configurable retry -- Cooldown-aware chat retries with configurable `requestRetry` and `maxRetryIntervalSec` -- Runtime environment validation with Zod at startup -- Compliance audit v2 with pagination, provider CRUD events, and SSRF-blocked validation logging - -Primary runtime model: - -- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs -- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage - -## Scope and Boundaries - -### In Scope - -- Local gateway runtime -- Dashboard management APIs -- Provider authentication and token refresh -- Request translation and SSE streaming -- Local state + usage persistence -- Optional cloud sync orchestration - -### Out of Scope - -- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` -- Provider SLA/control plane outside local process -- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) - -## Dashboard Surface (Current) - -Main pages under `src/app/(dashboard)/dashboard/`: - -- `/dashboard` — quick start + provider overview -- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs -- `/dashboard/providers` — provider connections and credentials -- `/dashboard/combos` — combo strategies, templates, step-based builder, model routing rules, manual persisted ordering -- `/dashboard/costs` — cost aggregation and pricing visibility -- `/dashboard/analytics` — usage analytics, evaluations, combo target health -- `/dashboard/limits` — quota/rate controls -- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation -- `/dashboard/agents` — detected ACP agents + custom agent registration -- `/dashboard/media` — image/video/music playground -- `/dashboard/search-tools` — search provider testing and history -- `/dashboard/health` — uptime, circuit breakers, rate limits, quota-monitored sessions -- `/dashboard/logs` — request/proxy/audit/console logs -- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.) -- `/dashboard/api-manager` — API key lifecycle and model permissions - -## High-Level System Context +_最后更新：2026-06-28_ + +## 概述 + +OmniRoute 是基于 Next.js 构建的本地 AI 路由网关和控制台。 +它提供一个统一的 OpenAI 兼容端点（`/v1/*`），将流量路由至多个上游服务商，并支持格式转换、容灾、Token 刷新和用量追踪。 + +核心能力： + +- OpenAI 兼容的 API 接口，供 CLI/工具使用（237 个服务商、68 个执行器） +- 跨服务商格式的请求/响应转换 +- 模型 Combo 容灾（多模型序列） +- 结构化 Combo 步骤（`服务商 + 模型 + 连接`），通过 `compositeTiers` 在运行时排序 +- 帐户级容灾（每服务商多帐户） +- 配额预检，以及主聊通路中基于配额感知的 P2C 帐户选择 +- OAuth + API Key 服务商连接管理（17 个 OAuth 服务商模块） +- 通过 `/v1/embeddings` 生成向量嵌入（6 个服务商、9 个模型） +- 通过 `/v1/images/generations` 生成图片（10+ 个服务商、20+ 个模型） +- 通过 `/v1/audio/transcriptions` 进行音频转录（7 个服务商） +- 通过 `/v1/audio/speech` 进行文本转语音（10 个服务商） +- 通过 `/v1/videos/generations` 生成视频（ComfyUI + SD WebUI） +- 通过 `/v1/music/generations` 生成音乐（ComfyUI） +- 通过 `/v1/search` 进行网页搜索（5 个服务商） +- 通过 `/v1/moderations` 进行内容审核 +- 通过 `/v1/rerank` 进行重排序 +- 推理模型的 `...` 标签解析 +- 响应净化，确保与 OpenAI SDK 严格兼容 +- 角色归一化（developer→system, system→user），跨服务商兼容 +- 结构化输出转换（json_schema → Gemini responseSchema） +- 服务商、API Key、别名、Combo、设置、定价的本地持久化（26 个 DB 模块） +- 用量/成本追踪和请求日志 +- 可选的云端同步，支持多设备/状态同步 +- IP 白名单/黑名单，控制 API 访问 +- Thinking Budget 管理（passthrough/auto/custom/adaptive） +- 全局系统提示注入 +- 会话追踪和指纹识别 +- 增强的每帐户速率限制，含服务商专属配置 +- 熔断器模式，保障服务商容灾 +- 互斥锁防惊群效应保护 +- 基于签名的请求去重缓存 +- 域层：成本规则、容灾策略、锁定策略 +- Context Relay：会话交接摘要，确保帐户轮换连续性 +- 域状态持久化（基于 SQLite 的写穿式缓存，存储容灾、预算、锁定、熔断器状态） +- 策略引擎，集中评估请求（锁定 → 预算 → 容灾） +- 请求遥测，含 p50/p95/p99 延迟聚合 +- Combo 目标遥测，以及通过 `combo_execution_key` / `combo_step_id` 记录 Combo 目标历史健康状态 +- 关联 ID（X-Request-Id），支持端到端追踪 +- 合规审计日志，支持按 API Key 选择退出 +- 评估框架，用于 LLM 质量保证 +- 健康看板，实时显示服务商熔断器状态 +- MCP 服务端（87 个工具），支持 3 种传输方式（stdio/SSE/Streamable HTTP） +- A2A 服务端（JSON-RPC 2.0 + SSE），含技能和任务生命周期 +- 记忆系统（提取、注入、检索、摘要） +- 技能系统（注册表、执行器、沙箱、内置技能） +- MITM 代理，含证书管理和 DNS 处理 +- 提示注入防护中间件 +- 提示压缩管线，含 Caveman、RTK、级联管线、压缩 Combo、语言包和分析 +- ACP（Agent Communication Protocol）注册表 +- 模块化 OAuth 服务商（`src/lib/oauth/providers/` 下 16 个独立模块） +- 卸载/完全卸载脚本 +- OAuth 环境修复操作 +- OpenAI 兼容 WebSocket 客户端的 WebSocket 桥接（`/v1/ws`） +- 同步 Token 管理（签发/撤销，基于 ETag 版本控制的配置包下载） +- GLM Thinking（`glmt`）一等服务商预设 +- 混合 Token 计数（服务商侧 `/messages/count_tokens` + 估算容灾） +- 模型别名自动播种（启动时 30+ 跨代理方言归一化） +- 安全出站 fetch，含 SSRF 防护、私有 URL 拦截和可配置重试 +- 冷却感知的聊重试机制，支持可配置的 `requestRetry` 和 `maxRetryIntervalSec` +- 启动时通过 Zod 进行运行时环境校验 +- 合规审计 v2，含分页、服务商 CRUD 事件和 SSRF 拦截校验日志 + +主要运行时模型： + +- `src/app/api/*` 下的 Next.js 应用路由同时实现控制台 API 和兼容 API +- `src/sse/*` + `open-sse/*` 中的共享 SSE/路由核心处理服务商执行、格式转换、流式传输、容灾和用量追踪 + +## 参考架构图 + +v3.8.0 平台的权威版本控制 Mermaid 源文件位于 +[`docs/diagrams/`](../diagrams/README.md)。以下展示其中两幅以供概览； +其余图表可从各自领域指南中获取。 + +![请求管线 (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg) + +> 源文件：[diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd) + +![三层容灾模型](../diagrams/exported/resilience-3layers.svg) + +> 源文件：[diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd) — 另见 +> [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) 和 `CLAUDE.md` 中的容灾参考。 + +## 范围与边界 + +### 范围内 + +- 本地网关运行时 +- 控制台管理 API +- 服务商认证与 Token 刷新 +- 请求格式转换和 SSE 流式传输 +- 本地状态 + 用量持久化 +- 可选的云端同步编排 + +### 范围外 + +- `NEXT_PUBLIC_CLOUD_URL` 背后的云端服务实现 +- 本地进程之外的服务商 SLA/控制面 +- 外部 CLI 二进制程序本身（Claude Code、Codex CLI 等） + +## 控制台界面（当前） + +`src/app/(dashboard)/dashboard/` 下的主要页面： + +- `/dashboard` — 快速开始 + 服务商概览 +- `/dashboard/endpoint` — 端点代理 + MCP + A2A + API 端点标签页 +- `/dashboard/providers` — 服务商连接和凭据 +- `/dashboard/combos` — Combo 策略、模板、基于步骤的构建器、模型路由规则、手动持久化排序 +- `/dashboard/auto-combo` — Auto Combo 引擎：评分权重、模式包、虚拟工厂预设、遥测 +- `/dashboard/costs` — 成本聚合和定价可视化 +- `/dashboard/analytics` — 用量分析、评估、Combo 目标健康状态 +- `/dashboard/limits` — 配额/速率控制 +- `/dashboard/cli-tools` — CLI 接入引导、运行时检测、配置生成 +- `/dashboard/agents` — 已检测的 ACP 代理 + 自定义代理注册 +- `/dashboard/cloud-agents` — 云端托管代理任务（Codex Cloud、Devin、Jules）和任务生命周期 +- `/dashboard/skills` — A2A 技能注册表、沙箱执行、内置技能目录 +- `/dashboard/memory` — 持久化会话记忆查看和检索 +- `/dashboard/webhooks` — 出站 Webhook 订阅、密钥轮换、重试统计 +- `/dashboard/batch` — 批量任务提交和进度 +- `/dashboard/cache` — 读穿式缓存和推理缓存统计、淘汰控制 +- `/dashboard/playground` — 针对任意配置 Combo/模型的交互式对话演练 +- `/dashboard/changelog` — 应用内更新日志查看器（渲染 `CHANGELOG.md`） +- `/dashboard/system` — 运行时诊断、版本信息、环境校验界面 +- `/dashboard/onboarding` — 新装首次运行设置向导 +- `/dashboard/media` — 图片/视频/音乐演练 +- `/dashboard/search-tools` — 搜索服务商测试和历史 +- `/dashboard/health` — 运行时间、熔断器、速率限制、配额监控会话 +- `/dashboard/logs` — 请求/代理/审计/控制台日志 +- `/dashboard/settings` — 系统设置标签页（常规、路由、Combo 默认值等） +- `/dashboard/context/caveman` — Caveman 压缩规则、语言包、预览和输出模式 +- `/dashboard/context/rtk` — RTK 命令输出过滤器、预览和运行时安全设置 +- `/dashboard/context/combos` — 分配给路由 Combo 的命名压缩管线 +- `/dashboard/translator` — 翻译器查看和请求格式转换预览 +- `/dashboard/audit` — 合规审计日志浏览器，含分页和结构化元数据 +- `/dashboard/usage` — 关联 `usage_history` 的每请求用量浏览器 +- `/dashboard/compression` — 压缩分析、统计和管线分配 +- `/dashboard/api-manager` — API Key 生命周期和模型权限 + +## 高层系统上下文 ```mermaid flowchart LR @@ -164,168 +204,354 @@ flowchart LR DASH --> CLOUD ``` -## Core Runtime Components +## 核心运行时组件 -## 1) API and Routing Layer (Next.js App Routes) +## 1) API 与路由层（Next.js App Routes） -Main directories: +主要目录： -- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs -- `src/app/api/*` for management/configuration APIs -- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` +- `src/app/api/v1/*` 和 `src/app/api/v1beta/*` — 兼容 API +- `src/app/api/*` — 管理/配置 API +- `next.config.mjs` 中的 Next.js 重写规则将 `/v1/*` 映射到 `/api/v1/*` -Important compatibility routes: +重要的兼容路由： - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` -- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) -- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — 包含标记为 `custom: true` 的自定义模型 +- `src/app/api/v1/embeddings/route.ts` — 向量嵌入生成（6 个服务商） +- `src/app/api/v1/images/generations/route.ts` — 图片生成（4+ 个服务商，含 Antigravity/Nebius） - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — 专用每服务商聊 +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — 专用每服务商向量嵌入 +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — 专用每服务商图片生成 - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Management domains: - -- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` -- Providers/connections: `src/app/api/providers*` -- Provider nodes: `src/app/api/provider-nodes*` -- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) -- Model catalog: `src/app/api/models/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) — request queue, connection cooldown, provider breaker, wait-for-cooldown config -- Resilience reset: `src/app/api/resilience/reset` (POST) — reset provider breakers -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET, with pagination + structured metadata) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) -- Sync tokens: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE) -- Config bundle: `src/app/api/sync/bundle` (GET, ETag-versioned snapshot of settings/providers/combos/keys) -- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade handler for OpenAI-compatible WS clients - -## 2) SSE + Translation Core - -Main flow modules: - -- Entry: `src/sse/handlers/chat.ts` -- Core orchestration: `open-sse/handlers/chatCore.ts` -- Provider execution adapters: `open-sse/executors/*` -- Format detection/provider config: `open-sse/services/provider.ts` -- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Account fallback logic: `open-sse/services/accountFallback.ts` -- Translation registry: `open-sse/translator/index.ts` -- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` -- Think tag parser: `open-sse/utils/thinkTagParser.ts` -- Embedding handler: `open-sse/handlers/embeddings.ts` -- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` -- Image generation handler: `open-sse/handlers/imageGeneration.ts` -- Image provider registry: `open-sse/config/imageRegistry.ts` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.ts` - -Services (business logic): - -- Account selection/scoring: `open-sse/services/accountSelector.ts` -- Context lifecycle management: `open-sse/services/contextManager.ts` -- IP filter enforcement: `open-sse/services/ipFilter.ts` -- Session tracking: `open-sse/services/sessionManager.ts` -- Request deduplication: `open-sse/services/signatureCache.ts` -- System prompt injection: `open-sse/services/systemPrompt.ts` -- Thinking budget management: `open-sse/services/thinkingBudget.ts` -- Wildcard model routing: `open-sse/services/wildcardRouter.ts` -- Rate limit management: `open-sse/services/rateLimitManager.ts` -- Circuit breaker: `open-sse/services/circuitBreaker.ts` -- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy -- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions -- Cooldown-aware retry: `src/sse/services/cooldownAwareRetry.ts` — per-model cooldown retries with configurable `requestRetry` / `maxRetryIntervalSec` -- Safe outbound fetch: `src/shared/network/safeOutboundFetch.ts` — guarded provider/model fetch with SSRF guard, private-URL blocking, retry, and timeout -- Outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — validates provider URLs against private/localhost CIDR ranges -- Provider request defaults: `open-sse/services/providerRequestDefaults.ts` — provider-level `maxTokens`, `temperature`, `thinkingBudgetTokens` defaults -- GLM provider constants: `open-sse/config/glmProvider.ts` — shared GLM models, quota URLs, GLMT timeout/defaults -- Antigravity upstream: `open-sse/config/antigravityUpstream.ts` — base URL and discovery path constants -- Codex client constants: `open-sse/config/codexClient.ts` — versioned user-agent and client-version values -- Model alias seed: `src/lib/modelAliasSeed.ts` — seeds 30+ cross-proxy dialect aliases at startup - -Domain layer modules: - -- Cost rules/budgets: `src/lib/domain/costRules.ts` -- Fallback policy: `src/lib/domain/fallbackPolicy.ts` -- Combo resolver: `src/lib/domain/comboResolver.ts` -- Lockout policy: `src/lib/domain/lockoutPolicy.ts` -- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation -- Error codes catalog: `src/lib/domain/errorCodes.ts` -- Request ID: `src/lib/domain/requestId.ts` -- Fetch timeout: `src/lib/domain/fetchTimeout.ts` -- Request telemetry: `src/lib/domain/requestTelemetry.ts` -- Compliance/audit: `src/lib/domain/compliance/index.ts` -- Eval runner: `src/lib/domain/evalRunner.ts` -- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers - -OAuth provider modules (13 individual files under `src/lib/oauth/providers/`): - -- Registry index: `src/lib/oauth/providers/index.ts` -- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules - -## 3) Persistence Layer - -Primary state DB (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` — CRUD operations for domain state -- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start - -## 4) Auth + Security Surfaces - -- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API key generation/verification: `src/shared/utils/apiKey.ts` -- Provider secrets persisted in `providerConnections` entries -- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -- SSRF / outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — blocks private/loopback/link-local ranges for all provider calls -- Runtime env validation: `src/lib/env/runtimeEnv.ts` — Zod schema for all environment variables, surfaced as startup errors/warnings -- Sync tokens: `src/lib/db/syncTokens.ts` — scoped tokens for config bundle download endpoints; backed by `sync_tokens` SQLite table (migration `024_create_sync_tokens.sql`) -- WebSocket handshake auth: `src/lib/ws/handshake.ts` — validates WS upgrade requests via API key or session cookie - -## 5) Cloud Sync - -- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts` -- Periodic task: `src/shared/services/cloudSyncScheduler.ts` -- Periodic task: `src/shared/services/modelSyncScheduler.ts` -- Control route: `src/app/api/sync/cloud/route.ts` - -## Request Lifecycle (`/v1/chat/completions`) +管理领域： + +- 认证/设置：`src/app/api/auth/*`, `src/app/api/settings/*` +- 服务商/连接：`src/app/api/providers*` +- 服务商节点：`src/app/api/provider-nodes*` +- 自定义模型：`src/app/api/provider-models` (GET/POST/DELETE) +- 模型目录：`src/app/api/models/route.ts` (GET) +- 代理配置：`src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth：`src/app/api/oauth/*` +- API Key/别名/Combo/定价：`src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- 用量：`src/app/api/usage/*` +- 同步/云端：`src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI 工具辅助：`src/app/api/cli-tools/*` +- IP 过滤：`src/app/api/settings/ip-filter` (GET/PUT) +- Thinking Budget：`src/app/api/settings/thinking-budget` (GET/PUT) +- 系统提示：`src/app/api/settings/system-prompt` (GET/PUT) +- 压缩：`src/app/api/settings/compression`, `src/app/api/compression/*` 和 + `src/app/api/context/*` +- 会话：`src/app/api/sessions` (GET) +- 速率限制：`src/app/api/rate-limits` (GET) +- 容灾：`src/app/api/resilience` (GET/PATCH) — 请求队列、连接冷却、服务商熔断器、等待冷却配置 +- 容灾重置：`src/app/api/resilience/reset` (POST) — 重置服务商熔断器 +- 缓存统计：`src/app/api/cache/stats` (GET/DELETE) +- 遥测：`src/app/api/telemetry/summary` (GET) +- 预算：`src/app/api/usage/budget` (GET/POST) +- 容灾链：`src/app/api/fallback/chains` (GET/POST/DELETE) +- 合规审计：`src/app/api/compliance/audit-log` (GET, 含分页 + 结构化元数据) +- 评估：`src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- 策略：`src/app/api/policies` (GET/POST) +- 同步 Token：`src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE) +- 配置包：`src/app/api/sync/bundle` (GET, ETag 版本控制的设置/服务商/Combo/Key 快照) +- WebSocket：`src/app/api/v1/ws/route.ts` — OpenAI 兼容 WS 客户端的 Upgrade 处理 + +## 2) SSE + 格式转换核心 + +主流模块： + +- 入口：`src/sse/handlers/chat.ts` +- 核心编排：`open-sse/handlers/chatCore.ts` +- 服务商执行适配器：`open-sse/executors/*` +- 格式检测/服务商配置：`open-sse/services/provider.ts` +- 模型解析/解析：`src/sse/services/model.ts`, `open-sse/services/model.ts` +- 帐户容灾逻辑：`open-sse/services/accountFallback.ts` +- 翻译器注册表：`open-sse/translator/index.ts` +- 流转换：`open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- 用量提取/归一化：`open-sse/utils/usageTracking.ts` +- Think 标签解析器：`open-sse/utils/thinkTagParser.ts` +- 向量嵌入处理器：`open-sse/handlers/embeddings.ts` +- 向量嵌入服务商注册表：`open-sse/config/embeddingRegistry.ts` +- 图片生成处理器：`open-sse/handlers/imageGeneration.ts` +- 图片服务商注册表：`open-sse/config/imageRegistry.ts` +- 响应净化：`open-sse/handlers/responseSanitizer.ts` +- 角色归一化：`open-sse/services/roleNormalizer.ts` + +服务（业务逻辑）： + +- 帐户选择/评分：`open-sse/services/accountSelector.ts` +- 上下文生命周期管理：`open-sse/services/contextManager.ts` +- IP 过滤执行：`open-sse/services/ipFilter.ts` +- 会话追踪：`open-sse/services/sessionManager.ts` +- 请求去重：`open-sse/services/signatureCache.ts` +- 系统提示注入：`open-sse/services/systemPrompt.ts` +- Thinking Budget 管理：`open-sse/services/thinkingBudget.ts` +- 通配符模型路由：`open-sse/services/wildcardRouter.ts` +- 速率限制管理：`open-sse/services/rateLimitManager.ts` +- 熔断器：`src/shared/utils/circuitBreaker.ts` +- 上下文交接：`open-sse/services/contextHandoff.ts` — 为 context-relay 策略生成和注入交接摘要 +- 压缩：`open-sse/services/compression/*` — 在服务商翻译之前执行的主动压缩； + 含 Caveman 规则、RTK 过滤器、级联管线、压缩 Combo、统计和校验 +- Codex 配额获取器：`open-sse/services/codexQuotaFetcher.ts` — 获取 Codex 配额，用于 context-relay 交接决策 +- 冷却感知重试：`src/sse/services/cooldownAwareRetry.ts` — 每模型冷却重试，支持可配置的 `requestRetry` / `maxRetryIntervalSec` +- 安全出站 fetch：`src/shared/network/safeOutboundFetch.ts` — 带 SSRF 防护、私有 URL 拦截、重试和超时的服务商/模型 fetch +- 出站 URL 守卫：`src/shared/network/outboundUrlGuard.ts` — 校验服务商 URL 是否指向私有/localhost CIDR 范围 +- 服务商请求默认值：`open-sse/services/providerRequestDefaults.ts` — 服务商级 `maxTokens`、`temperature`、`thinkingBudgetTokens` 默认值 +- GLM 服务商常量：`open-sse/config/glmProvider.ts` — 共享 GLM 模型、配额 URL、GLMT 超时/默认值 +- Antigravity 上游：`open-sse/config/antigravityUpstream.ts` — 基础 URL 和发现路径常量 +- Codex 客户端常量：`open-sse/config/codexClient.ts` — 带版本号的 user-agent 和 client-version 值 +- 模型别名播种：`src/lib/modelAliasSeed.ts` — 启动时播种 30+ 跨代理方言别名 + +域层模块： + +- 成本规则/预算：`src/domain/costRules.ts` +- 容灾策略：`src/domain/fallbackPolicy.ts` +- Combo 解析器：`src/domain/comboResolver.ts` +- 锁定策略：`src/domain/lockoutPolicy.ts` +- 策略引擎：`src/domain/policyEngine.ts` — 集中式 锁定 → 预算 → 容灾 评估 +- 错误码目录：`src/shared/constants/errorCodes.ts` +- 请求 ID：`src/shared/utils/requestId.ts` +- Fetch 超时：`src/shared/utils/fetchTimeout.ts` +- 请求遥测：`src/shared/utils/requestTelemetry.ts` +- 合规/审计：`src/lib/compliance/index.ts` +- 评估运行器：`src/lib/evals/evalRunner.ts` +- 域状态持久化：`src/lib/db/domainState.ts` — SQLite CRUD，管理容灾链、预算、成本历史、锁定状态、熔断器 + +OAuth 服务商模块（`src/lib/oauth/providers/` 下 16 个独立文件）： + +- 注册表索引：`src/lib/oauth/providers/index.ts` +- 独立服务商：`claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `agy.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`, `windsurf.ts`, `gitlab-duo.ts`, `trae.ts` +- 薄封装层：`src/lib/oauth/providers.ts` — 从独立模块重新导出 + +## 5) 嵌入式服务（v3.8.4） + +OmniRoute 可以安装、监管并路由到本地运行的 AI 工具进程，称为**嵌入式服务**。 +v3.8.4 中发布了两项：9Router 和 CLIProxyAPI。 + +架构层级： + +- **UI** (`/dashboard/providers/services`) — 双标签页页面，含生命周期控制、 + 实时日志流式传输、API Key 管理，以及（针对 9Router）通过内部反向代理提供嵌入式原生 UI。 +- **API** (`/api/services/{name}/*`) — 9Router 8 个端点，CLIProxyAPI 7 个端点， + 均归类为 **LOCAL_ONLY**（硬规则 #17）。共享的 `GET /api/services/[name]/logs` + SSE 端点同时服务于两者。 +- **监管进程** (`src/lib/services/`) — 泛型 `ServiceSupervisor` 类封装了 + `child_process.spawn`，持有一个 5 MB 环形缓冲区用于 SSE 日志流式传输、一个健康 + 探测循环、一个原子操作锁，以及 SIGTERM→SIGKILL 优雅关闭流程。 + `bootstrap.ts` 在进程启动时自动配置所有已启用的服务。 +- **服务商/执行器** (`open-sse/executors/ninerouter.ts`) — 9Router 作为 + 真实服务商对外暴露。模型前缀为 `9router/{sub}/{model}`，每 5 分钟从 9Router 的 + `/v1/models` 端点同步一次。 + +深入阅读：`docs/frameworks/EMBEDDED-SERVICES.md` + +## 主要子系统（v3.8.0） + +### A. Auto Combo 引擎 + +Auto Combo 在请求时动态评分和选择路由目标，而非依赖静态的 Combo 定义。 +它驱动 `auto/*` 模型前缀系列。 + +- 引擎入口：`open-sse/services/autoCombo/`（`autoComboEngine.ts`、 + `scoringEngine.ts`、`virtualFactory.ts`、`modePacks.ts`） +- 解析器：`src/domain/comboResolver.ts`（自动检测 `auto/` 前缀） +- 控制台页面：`/dashboard/auto-combo` +- 遥测：`auto_combo_decisions` SQLite 表 + +关键能力： + +- **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**，外加一条容灾路径）— + auto 是 v3.8.0 的重点新增策略；`fusion`（panel 分散请求 + judge 合成， + `open-sse/services/fusion.ts`）是 v3.8.36 新增。 +- **9 个评分因子**：成本、p95 延迟、成功率、配额余量、锁定距离、 + 熔断器状态、近期失败次数、模型可用性、标签亲和度。 +- **虚拟工厂**在不存在匹配的命名 Combo 时，从健康的活跃服务商连接 + 中实时构建临时 Combo。 +- **Auto 前缀**：`auto/coding`、`auto/cheap`、`auto/fast`、`auto/offline`、 + `auto/smart`、`auto/lkgp` — 各自由一个调优过的权重配置支持。 +- **4 个模式包**：coding、fast、cheap、smart — 作为预设权重 + 配置发布，可从控制台调用。 + +完整算法细节（因子公式、权重调优）参见 +[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md)。 + +### B. 云代理 + +Cloud Agents 将第三方托管代码代理平台（Codex Cloud、Devin、 +Jules）封装在统一的基于 DB 的任务生命周期之后。所有任务创建/查看 +端点均需要管理认证。 + +- 模块根目录：`src/lib/cloudAgent/`（`baseAgent.ts`、`registry.ts`、`api.ts`、 + `types.ts`、`db.ts`，以及 `agents/` 下每个代理的子目录） +- 每代理实现：`agents/codex/`、`agents/devin/`、`agents/jules/` +- 公开端点：`/api/v1/agents/tasks/*`（list/create/get/cancel） +- 管理端点：`/api/cloud/*`（配置、状态、批量） +- 控制台页面：`/dashboard/cloud-agents` +- 存储：`cloud_agent_tasks` 表 + +每代理配置和 OAuth 细节参见 +[`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md)。 + +### C. 安全护栏 + +安全护栏模块是一个热重载的中间件层，检查请求 +和响应中的 PII、提示注入和不安全视觉内容。违规 +通过 HTTP **503** 加上结构化错误码立即拦截请求， +下游调用方可以据此重试或分支处理。 + +- 模块根目录：`src/lib/guardrails/`（`base.ts`、`registry.ts`、`piiMasker.ts`、 + `promptInjection.ts`、`visionBridge.ts`、`visionBridgeHelpers.ts`） +- 热重载：注册表监控配置变更并在原地重建处理链 +- 接入点：聊处理器入口、图片生成处理器、响应净化器 +- HTTP 协议：违规以 `503` + `error.code = "GUARDRAIL_VIOLATION"` 呈现 + +规则集编写和阈值调优参见 +[`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md)。 + +### D. 域层 + +`src/domain/` 命名空间集中管理策略决策，路由处理器无需自行 +处理锁定/预算/容灾逻辑。 + +- 策略引擎：`src/domain/policyEngine.ts` — 统一入口， + 执行前评估（锁定 → 预算 → 容灾排序） +- 成本规则：`src/domain/costRules.ts` +- 容灾策略：`src/domain/fallbackPolicy.ts` +- 锁定策略：`src/domain/lockoutPolicy.ts` +- 标签路由：`src/domain/tagRouter.ts` +- Combo 解析器：`src/domain/comboResolver.ts` — 将 Combo 名称、auto/* 前缀 + 和通配符模型目标解析为具体执行计划 +- 连接/模型规则连接器：`src/domain/connectionModelRules.ts` +- 模型可用性快照：`src/domain/modelAvailability.ts` +- 服务商过期追踪：`src/domain/providerExpiration.ts` +- 配额缓存：`src/domain/quotaCache.ts` +- 降级状态：`src/domain/degradation.ts` +- 配置审计：`src/domain/configAudit.ts` +- OmniRoute 响应元数据构建器：`src/domain/omnirouteResponseMeta.ts` +- 评估子系统：`src/domain/assessment/` — 周期性评估任务 + +### E. 授权管线 + +授权管线对每个进入的请求进行分类，并在分发前应用 +相应的策略链。 + +- 管线入口：`src/server/authz/pipeline.ts` +- 请求分类器：`src/server/authz/classify.ts` — 区分公开兼容路由和管理路由 +- 公开路由清单：`src/shared/constants/publicApiRoutes.ts` +- 策略：`src/server/authz/policies/` — 可组合的断言条件 + （`requireApiKey`、`requireManagement`、`requireFreshAuth` 等） +- Header 工具：`src/server/authz/headers.ts` +- 断言辅助：`src/server/authz/assertAuth.ts` +- 请求上下文：`src/server/authz/context.ts` + +公开路由和管理路由之间是硬边界：代理/冷却 API 和 +服务商变更操作要求管理认证（缺失时返回 HTTP 401）。 + +完整路由分类规则参见 +[`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md)。 + +### F. 工作流 FSM 与任务感知路由器 + +在 Combo 选择之上叠加的有限状态机驱动路由器， +根据检测到的工作流阶段（规划、执行、 +审核）和后台任务亲和度引导流量走向。 + +- 工作流 FSM：`open-sse/services/workflowFSM.ts` +- 任务感知路由器：`open-sse/services/taskAwareRouter.ts` +- 后台任务检测器：`open-sse/services/backgroundTaskDetector.ts` +- 意图分类器：`open-sse/services/intentClassifier.ts` + +FSM 状态转换反馈到 Auto Combo 的评分中，使后台/自动化任务偏向 +更便宜的模型，交互式规划/审核轮次偏向更强的模型。 + +### G. 服务商专属容灾 + +多个服务商内置了专用的容灾和隐身模块，这些模块 +基于全局熔断器 / 连接冷却 / 模型锁定层运行： + +- Antigravity 429 引擎：`open-sse/services/antigravity429Engine.ts`（轮换 + 身份、清洗响应头，通过 `antigravityCredits.ts`、`antigravityHeaderScrub.ts`、 + `antigravityHeaders.ts`、`antigravityIdentity.ts`、`antigravityObfuscation.ts`、 + `antigravityVersion.ts` 驱动积分/版本追踪） +- ModelScope 配额策略：`open-sse/services/modelscopePolicy.ts` +- Claude Code CCH（兼容通道握手）：`open-sse/services/claudeCodeCCH.ts`， + 外加 `claudeCodeCompatible.ts`、`claudeCodeConstraints.ts`、`claudeCodeExtraRemap.ts`、 + `claudeCodeToolRemapper.ts` +- Claude Code 指纹塑造：`open-sse/services/claudeCodeFingerprint.ts` +- Claude Code 混淆：`open-sse/services/claudeCodeObfuscation.ts` +- ChatGPT TLS 客户端：`open-sse/services/chatgptTlsClient.ts`（为 ChatGPT-Web 会话 + 提供 curl-impersonate 风格的 TLS 指纹） +- ChatGPT 图片缓存：`open-sse/services/chatgptImageCache.ts` + +完整隐身策略和操作指南参见 +[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md)。 + +### H. Webhook、推理缓存、读缓存 + +- **Webhook** — 服务商/帐户/任务事件的出站分发。 + - 分发器：`src/lib/webhookDispatcher.ts` + - 存储：`webhooks` SQLite 表（通过 `src/lib/db/webhooks.ts`） + - 控制台页面：`/dashboard/webhooks`（订阅、密钥、重试历史） + - 事件分类和重试语义参见 [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md)。 +- **推理缓存** — 对生成思考 Token 的服务商（Claude、GLMT 等） + 保存可回放的推理块，让连续轮次可以跳过重新思考。 + - DB 层：`src/lib/db/reasoningCache.ts` + - 服务层：`open-sse/services/reasoningCache.ts` + - 回放语义参见 [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md)。 +- **读缓存** — 按签名索引的短生命周期响应缓存，用于 + 消除上游 SDK 的错误重复请求。 + - DB 层：`src/lib/db/readCache.ts` + - 统计端点：`GET /api/cache/stats`，控制台页面 `/dashboard/cache` + +## 3) 持久化层 + +主状态数据库（SQLite）： + +- 核心基础设施：`src/lib/db/core.ts`（better-sqlite3、数据迁移、WAL） +- 重新导出门面：`src/lib/localDb.ts`（供调用方使用的薄兼容层） +- 文件：`${DATA_DIR}/storage.sqlite`（或设置了 `$XDG_CONFIG_HOME` 时为 `$XDG_CONFIG_HOME/omniroute/storage.sqlite`，否则为 `~/.omniroute/storage.sqlite`） +- 实体（表 + KV 命名空间）：providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +用量持久化： + +- 门面：`src/lib/usageDb.ts`（拆解后的模块位于 `src/lib/usage/*`） +- `storage.sqlite` 中的 SQLite 表：`usage_history`、`call_logs`、`proxy_logs` +- 可选的文件工件保留以便兼容/调试（`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/`、`/logs/...`） +- 存在旧 JSON 文件时，启动迁移会将其迁移到 SQLite + +域状态数据库（SQLite）： + +- `src/lib/db/domainState.ts` — 域状态的 CRUD 操作 +- 表（在 `src/lib/db/core.ts` 中创建）：`domain_fallback_chains`、`domain_budgets`、`domain_cost_history`、`domain_lockout_state`、`domain_circuit_breakers` +- 写穿式缓存模式：运行时以内存 Map 为权威数据源；变更同步写入 SQLite；冷启动时从数据库恢复状态 + +## 4) 认证与安全界面 + +- 控制台 Cookie 认证：`src/proxy.ts`、`src/app/api/auth/login/route.ts` +- API Key 生成/验证：`src/shared/utils/apiKey.ts` +- 服务商密钥持久化存储在 `providerConnections` 条目中 +- 出站代理支持：`open-sse/utils/proxyFetch.ts`（环境变量）和 `open-sse/utils/networkProxy.ts`（可按服务商或全局配置） +- SSRF / 出站 URL 守卫：`src/shared/network/outboundUrlGuard.ts` — 拦截所有服务商调用的私有/loopback/本地链路范围目标 +- 运行时环境校验：`src/lib/env/runtimeEnv.ts` — 用于所有环境变量的 Zod Schema，在启动时以错误/警告形式呈现 +- 同步 Token：`src/lib/db/syncTokens.ts` — 为配置包下载端点签发的带权限域 Token；后端使用 `sync_tokens` SQLite 表（迁移文件 `024_create_sync_tokens.sql`） +- WebSocket 握手认证：`src/lib/ws/handshake.ts` — 通过 API Key 或会话 Cookie 校验 WS 升级请求 + +## 5) 云端同步 + +- 调度器初始化：`src/lib/initCloudSync.ts`、`src/shared/services/initializeCloudSync.ts`、`src/shared/services/modelSyncScheduler.ts` +- 周期任务：`src/shared/services/cloudSyncScheduler.ts` +- 周期任务：`src/shared/services/modelSyncScheduler.ts` +- 控制路由：`src/app/api/sync/cloud/route.ts` + +## 请求生命周期 (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -372,7 +598,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Account Fallback Flow +## Combo + 帐户容灾流程 ```mermaid flowchart TD @@ -402,9 +628,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. +容灾决策由 `open-sse/services/accountFallback.ts` 根据状态码和错误消息启发式算法驱动。Combo 路由增加了一层额外保护：服务商级 400 错误（如上游内容拦截和角色校验失败）会被视为模型局部故障，后续 Combo 目标仍可继续执行。 -## OAuth Onboarding and Token Refresh Lifecycle +## OAuth 接入和 Token 刷新生命周期 ```mermaid sequenceDiagram @@ -434,9 +660,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. +实时流量中的 Token 刷新在 `open-sse/handlers/chatCore.ts` 内通过执行器的 `refreshCredentials()` 完成。 -## Cloud Sync Lifecycle (Enable / Sync / Disable) +## 云端同步生命周期（启用 / 同步 / 禁用） ```mermaid sequenceDiagram @@ -468,9 +694,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. +当云端同步启用时，由 `CloudSyncScheduler` 触发周期同步。 -## Data Model and Storage Map +## 数据模型与存储映射 ```mermaid erDiagram @@ -571,14 +797,14 @@ erDiagram } ``` -Physical storage files: +物理存储文件： -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` +- 主运行时数据库：`${DATA_DIR}/storage.sqlite` +- 请求日志行：`${DATA_DIR}/log.txt`（兼容/调试工件） +- 结构化调用载荷存档：`${DATA_DIR}/call_logs/` +- 可选的翻译器/请求调试会话：`/logs/...` -## Deployment Topology +## 部署拓扑 ```mermaid flowchart LR @@ -609,281 +835,331 @@ flowchart LR Next --> SyncCloud ``` -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) -- `src/app/api/sync/tokens`: sync token CRUD (GET/POST) -- `src/app/api/sync/tokens/[id]`: sync token get/delete (GET/DELETE) -- `src/app/api/sync/bundle`: config bundle download (GET, ETag versioning) -- `src/app/api/v1/ws`: WebSocket upgrade handler for OpenAI-compatible WS clients - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider | -| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | -| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Custom auth and protocol handling | -| `CloudflareAiExecutor` | Cloudflare Workers AI | Account ID injection, Neurons-based usage tracking | -| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | -| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | -| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | -| `OpenCodeExecutor` | OpenCode | AI SDK compatible provider setup | -| `PollinationsExecutor` | Pollinations AI | No API key required, rate-limited requests | -| `PuterExecutor` | Puter | Browser-based provider integration | -| `QoderExecutor` | Qoder AI | PAT and OAuth support, multi-model free tier | -| `VertexExecutor` | Google Vertex AI | Service account auth, region-based endpoints | - -All other providers (including custom compatible nodes) use the `DefaultExecutor`. - -## Provider Compatibility Matrix - -| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | -| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | -| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | -| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | -| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | -| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | -| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | -| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request | -| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ | -| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ | -| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ | -| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ | -| Pollinations | openai | None (no key) | ✅ | ✅ | ❌ | ❌ | -| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Ollama Cloud | openai | API Key (optional) | ✅ | ✅ | ❌ | ❌ | -| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Puter | openai | API Key | ✅ | ✅ | ❌ | ❌ | - -## Format Translation Coverage - -Detected source formats include: +## 模块映射（决策关键） + +### 路由与 API 模块 + +- `src/app/api/v1/*`、`src/app/api/v1beta/*`：兼容 API +- `src/app/api/v1/providers/[provider]/*`：专用每服务商路由（聊、向量嵌入、图片） +- `src/app/api/providers*`：服务商 CRUD、校验、测试 +- `src/app/api/provider-nodes*`：自定义兼容节点管理 +- `src/app/api/provider-models`：自定义模型管理（CRUD） +- `src/app/api/models/route.ts`：模型目录 API（别名 + 自定义模型） +- `src/app/api/oauth/*`：OAuth/设备码流程 +- `src/app/api/keys*`：本地 API Key 生命周期 +- `src/app/api/models/alias`：别名管理 +- `src/app/api/combos*`：容灾 Combo 管理 +- `src/app/api/pricing`：成本计算的定价覆盖 +- `src/app/api/settings/proxy`：代理配置 (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`：出站代理连通性测试 (POST) +- `src/app/api/usage/*`：用量和日志 API +- `src/app/api/sync/*` + `src/app/api/cloud/*`：云端同步和云端辅助 +- `src/app/api/cli-tools/*`：本地 CLI 配置写入/检查 +- `src/app/api/settings/ip-filter`：IP 白名单/黑名单 (GET/PUT) +- `src/app/api/settings/thinking-budget`：思考 Token 预算配置 (GET/PUT) +- `src/app/api/settings/system-prompt`：全局系统提示 (GET/PUT) +- `src/app/api/settings/compression`：全局压缩设置 (GET/PUT) +- `src/app/api/compression/*`：压缩预览、规则元数据和语言包 +- `src/app/api/context/caveman/config`：Caveman 设置别名 (GET/PUT) +- `src/app/api/context/rtk/*`：RTK 配置、过滤器目录、测试端点、原始输出恢复 +- `src/app/api/context/combos*`：压缩 Combo CRUD 和路由 Combo 分配 +- `src/app/api/context/analytics`：压缩分析别名 +- `src/app/api/sessions`：活跃会话列表 (GET) +- `src/app/api/rate-limits`：每帐户速率限制状态 (GET) +- `src/app/api/sync/tokens`：同步 Token CRUD (GET/POST) +- `src/app/api/sync/tokens/[id]`：同步 Token 获取/删除 (GET/DELETE) +- `src/app/api/sync/bundle`：配置包下载 (GET, ETag 版本控制) +- `src/app/api/v1/ws`：OpenAI 兼容 WS 客户端的 WebSocket 升级处理 + +### 路由与执行核心 + +- `src/sse/handlers/chat.ts`：请求解析、Combo 处理、帐户选择循环 +- `open-sse/handlers/chatCore.ts`：格式转换、执行器分发、重试/刷新处理、流设置 + +### 翻译器注册表与格式转换器 + +- `open-sse/translator/index.ts`：翻译器注册表与编排 +- 请求翻译器：`open-sse/translator/request/*`（9 个模块 — `antigravity-to-openai`、`claude-to-gemini`、`claude-to-openai`、`gemini-to-openai`、`openai-responses`、`openai-to-claude`、`openai-to-cursor`、`openai-to-gemini`、`openai-to-kiro`） +- 响应翻译器：`open-sse/translator/response/*`（8 个模块 — `claude-to-openai`、`cursor-to-openai`、`gemini-to-claude`、`gemini-to-openai`、`kiro-to-openai`、`openai-responses`、`openai-to-antigravity`、`openai-to-claude`） +- 辅助模块：`open-sse/translator/helpers/*`（8 个模块 — `claudeHelper`、`geminiHelper`、`geminiToolsSanitizer`、`maxTokensHelper`、`openaiHelper`、`responsesApiHelper`、`schemaCoercion`、`toolCallHelper`） +- 格式常量：`open-sse/translator/formats.ts` +- 启动加载与注册表：`open-sse/translator/bootstrap.ts`、`open-sse/translator/registry.ts` +- 图片格式辅助：`open-sse/translator/image/` + +### 持久化 + +- `src/lib/db/*`：SQLite 上的持久化配置/状态和域持久化 +- `src/lib/localDb.ts`：DB 模块的兼容性重新导出 +- `src/lib/usageDb.ts`：SQLite 表之上的用量历史/调用日志门面 + +## 服务商执行器覆盖（策略模式） + +每个服务商都有一个继承 `BaseExecutor`（在 `open-sse/executors/base.ts` 中）的专用执行器，该基类提供了 URL 构建、Header 构造、带指数退避的重试、凭据刷新钩子以及 `execute()` 编排方法。 + +| 执行器 | 服务商 | 特殊处理 | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA 等 | 每服务商动态 URL/Header 配置 | +| `AntigravityExecutor` | Google Antigravity | 自定义项目/会话 ID、Retry-After 解析、429 混淆 | +| `AzureOpenAIExecutor` | Azure OpenAI | 基于部署的路由、api-version 查询参数强制执行 | +| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Web 会话反向 + TLS 指纹模拟 | +| `ChatGPTWebExecutor` | ChatGPT web | TLS 客户端 + 会话 Cookie 管理（`chatgptTlsClient.ts`）| +| `ClaudeIdentityExecutor` | Claude.ai (CCH 通道) | 约束 + Tool 重映射管线、指纹塑造 | +| `CliProxyApiExecutor` | CLIProxyAPI 兼容服务商 | 自定义认证和协议处理 | +| `CloudflareAiExecutor` | Cloudflare Workers AI | 帐户 ID 注入、基于 Neurons 的用量追踪 | +| `CodexExecutor` | OpenAI Codex | 注入系统指令、强制推理力度 | +| `CommandCodeExecutor` | Command Code | OAuth + 每会话 Header 轮换 | +| `CursorExecutor` | Cursor IDE | ConnectRPC 协议、Protobuf 编码、基于校验和的请求签名| +| `DevinCliExecutor` | Devin CLI | Devin 任务生命周期桥接（通过云代理模块） | +| `GithubExecutor` | GitHub Copilot | Copilot Token 刷新、VSCode 模仿 Header | +| `GitlabExecutor` | GitLab Duo | GitLab OAuth + 项目级路由 | +| `GlmExecutor` | Z.AI GLM（含 `glmt` 预设） | Thinking Budget 感知、GLMT 预设常量 | +| `GrokWebExecutor` | xAI Grok web | Web 会话反向、模式选择（think/standard） | +| `KieExecutor` | KIE | 自定义 Token 签发 + 轮换会话锚点 | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream 二进制格式 → SSE 转换 | +| `MuseSparkWebExecutor` | Muse Spark (web) | Web 会话反向 + 图片消息桥接 | +| `NlpCloudExecutor` | NLP Cloud | 服务商专属请求体形状 | +| `OpenCodeExecutor` | OpenCode | AI SDK 兼容服务商初始化 | +| `PerplexityWebExecutor` | Perplexity web | Web 会话反向，用于聊延续 | +| `PetalsExecutor` | Petals distributed inference | 去中心化集群路由 | +| `PollinationsExecutor` | Pollinations AI | 无需 API Key、带速率限制的请求 | +| `PuterExecutor` | Puter | 基于浏览器的服务商集成 | +| `QoderExecutor` | Qoder AI | PAT 和 OAuth 支持、多模型免费层 | +| `VertexExecutor` | Google Vertex AI | 服务帐户认证、基于区域的端点 | +| `WindsurfExecutor` | Windsurf (Codeium) | Codeium OAuth + 会话 Token 刷新 | + +其余所有服务商（含自定义兼容节点）使用 `DefaultExecutor`。 + +## 服务商兼容性矩阵 + +> **注意：** 下表是 OmniRoute v3.8.0 中 237 个已注册服务商的代表性样本。 +> 完整且持续更新的列表请参阅 +> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md)（自动生成）或数据源头 +> `src/shared/constants/providers.ts`（加载时通过 Zod 校验）。 + +| 服务商 | 格式 | 认证 | 流式 | 非流式 | Token 刷新 | 用量 API | +| ----------------- | ---------------- | --------------------- | -------------- | ---------- | ----------- | ----------------- | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ 仅管理员 | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ 完整配额 API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ 强制 | ❌ | ✅ | ✅ 速率限制 | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ 配额快照 | +| Cursor | cursor | 自定义校验和 | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream)| ❌ | ✅ | ✅ 用量限制 | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 | +| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 | +| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ | +| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ | +| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cloudflare AI | openai | API Token + 帐户 ID | ✅ | ✅ | ❌ | ❌ | +| Pollinations | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ | +| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Ollama Cloud | openai | API Key（可选） | ✅ | ✅ | ❌ | ❌ | +| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Vertex AI | gemini | 服务帐户 | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Puter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 | +| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ | +| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ 每请求 | +| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ | +| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Windsurf | openai | OAuth (Codeium) | ✅ | ✅ | ✅ | ⚠️ 每请求 | +| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ | +| Devin CLI | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任务 API | +| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ 速率限制 | +| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任务 API | +| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| ChatGPT-Web | openai | 会话 Cookie + TLS | ✅ | ✅ | ❌ | ❌ | +| Grok-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ | +| Perplexity-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ | +| BlackBox-Web | openai | 会话 Cookie + TLS | ✅ | ✅ | ❌ | ❌ | +| Muse-Spark-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ | +| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ 配额策略 | +| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Petals | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ | +| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 | +| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ | +| CLIProxyAPI | openai | 自定义 | ✅ | ✅ | ❌ | ❌ | + +## 格式转换覆盖 + +检测到的源格式包括： - `openai` - `openai-responses` - `claude` - `gemini` -Target formats include: +目标格式包括： - OpenAI chat/Responses - Claude -- Gemini/Antigravity envelope +- Gemini/Antigravity 封装 - Kiro - Cursor -Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: +格式转换采用 **OpenAI 作为中枢格式** — 所有转换都经过 OpenAI 作为中间格式： ``` -Source Format → OpenAI (hub) → Target Format +源格式 → OpenAI（中枢）→ 目标格式 ``` -Translations are selected dynamically based on source payload shape and provider target format. +格式转换根据源载荷形态和服务商目标格式动态选择。 -Additional processing layers in the translation pipeline: +格式转换管线中的额外处理层： -- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field -- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` +- **响应净化** — 从 OpenAI 格式响应中剥离非标准字段（流式和非流式），确保严格的 SDK 兼容性 +- **角色归一化** — 将 `developer` 转换为 `system`（面向非 OpenAI 目标）；将 `system` 合并为 `user`（针对拒绝 system 角色的模型，如 GLM、ERNIE） +- **Think 标签提取** — 将内容中的 `...` 块解析为 `reasoning_content` 字段 +- **结构化输出** — 将 OpenAI 的 `response_format.json_schema` 转换为 Gemini 的 `responseMimeType` + `responseSchema` -## Supported API Endpoints +## 支持的 API 端点 -| Endpoint | Format | Handler | -| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | -| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Model listing | API route | -| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Model listing | API route | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | -| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | -| `POST /v1/messages/count_tokens` | Claude Token Count | API route | -| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | -| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | -| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | -| `GET/POST/DELETE /api/provider-models` | Provider Models | Provider model metadata backing custom and managed available models | +| 端点 | 格式 | 处理器 | +| --------------------------------------------------- | ------------------ | ----------------------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | 同一处理器（自动检测） | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | 模型列表 | API 路由 | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | 模型列表 | API 路由 | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | 带模型校验的专用每服务商路由 | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | 带模型校验的专用每服务商路由 | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | 带模型校验的专用每服务商路由 | +| `POST /v1/messages/count_tokens` | Claude Token Count | API 路由 | +| `GET /v1/models` | OpenAI Models 列表 | API 路由（聊 + 向量嵌入 + 图片 + 自定义模型） | +| `GET /api/models/catalog` | 目录 | 按服务商 + 类型分组的所有模型 | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API 路由 | +| `GET/PUT/DELETE /api/settings/proxy` | 代理配置 | 网络代理配置 | +| `POST /api/settings/proxy/test` | 代理连通性 | 代理健康/连通性测试端点 | +| `GET/POST/DELETE /api/provider-models` | 服务商模型 | 服务商模型元数据，支撑自定义和管理可用模型 | -## Bypass Handler +## 旁路处理器 -The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. +旁路处理器（`open-sse/utils/bypassHandler.ts`）拦截来自 Claude Code CLI 的已知"一次性"请求 — 预热 ping、标题提取和 Token 计数 — 并返回**伪响应**，不消耗上游服务商 Token。仅当 `User-Agent` 包含 `claude-cli` 时触发。 -## Request Logging and Artifacts +## 请求日志与工件 -The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for -legacy compatibility. The current runtime contract uses: +旧版基于文件的请求日志记录器（`open-sse/utils/requestLogger.ts`）仅为 +旧版兼容而保留。当前运行时使用： -- `APP_LOG_TO_FILE=true` for application and audit logs written under `/logs/` -- SQLite-backed call log records in `call_logs` -- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled +- `APP_LOG_TO_FILE=true` 则将应用和审计日志写入 `/logs/` 下 +- `call_logs` 中基于 SQLite 的调用日志记录 +- 当调用日志管线启用时，`${DATA_DIR}/call_logs/YYYY-MM-DD/...` 工件 -## Failure Modes and Resilience +## 故障模式与容灾 -## 1) Account/Provider Availability +## 1) 帐户/服务商可用性 -- connection cooldown on retryable upstream failures -- account fallback before failing request -- combo model fallback when current model/provider path is exhausted +- 可在重试时有上游故障时执行连接冷却 +- 在请求失败前进行帐户容灾 +- 当前模型/服务商路径耗尽时的 Combo 模型容灾 -## 2) Token Expiry +## 2) Token 过期 -- pre-check and refresh with retry for refreshable providers -- 401/403 retry after refresh attempt in core path +- 对可刷新服务商进行预检查和刷新重试 +- 核心路径中在刷新尝试后重试 401/403 -## 3) Stream Safety +## 3) 流安全性 -- disconnect-aware stream controller -- translation stream with end-of-stream flush and `[DONE]` handling -- usage estimation fallback when provider usage metadata is missing +- 连接断开感知的流控制器 +- 带流结束刷新的转换流和 `[DONE]` 处理 +- 服务商用量元数据缺失时的用量估算容灾 -## 4) Cloud Sync Degradation +## 4) 云端同步降级 -- sync errors are surfaced but local runtime continues -- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default +- 同步错误会暴露出来，但本地运行继续 +- 调度器具有可重试的逻辑，但周期执行默认调用单次同步 -## 5) Data Integrity +## 5) 数据完整性 -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON → SQLite migration compatibility path +- SQLite Schema 迁移和启动时自动升级钩子 +- 旧 JSON → SQLite 迁移兼���路径 -## 6) SSRF / Outbound URL Guard +## 6) SSRF / 出站 URL 守卫 -- `src/shared/network/outboundUrlGuard.ts` blocks all private/loopback/link-local target URLs before they reach provider executors -- Provider model discovery and validation routes use `src/shared/network/safeOutboundFetch.ts` which applies the guard before every outbound request -- Guard errors surface as `URL_GUARD_BLOCKED` with HTTP 422 and are logged to the compliance audit trail via `providerAudit.ts` +- `src/shared/network/outboundUrlGuard.ts` 在请求到达服务商执行器之前拦截所有私有/loopback/本地链路目标 URL +- 服务商模型发现和校验路由使用 `src/shared/network/safeOutboundFetch.ts`，每次出站请求前施加守卫 +- 守卫错误以 `URL_GUARD_BLOCKED` + HTTP 422 呈现，并通过 `providerAudit.ts` 记录到合规审计追踪中 -## Observability and Operational Signals +## 可观测性与运维信号 -Runtime visibility sources: +运行时可见性来源： -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` -- textual request status log in `log.txt` (optional/compat) -- optional application log files under `logs/` when `APP_LOG_TO_FILE=true` -- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled -- dashboard usage endpoints (`/api/usage/*`) for UI consumption +- `src/sse/utils/logger.ts` 的控制台日志 +- SQLite 中的每请求用量聚合（`usage_history`、`call_logs`、`proxy_logs`） +- 当 `settings.detailed_logs_enabled=true` 时 SQLite 中的四阶段详细载荷捕获（`request_detail_logs`） +- `log.txt` 中的文本请求状态日志（可选/兼容） +- 当 `APP_LOG_TO_FILE=true` 时 `logs/` 下的可选应用日志文件 +- 当调用日志管线启用时 `${DATA_DIR}/call_logs/` 下的可选请求工件 +- 控制台用量端点（`/api/usage/*`）供 UI 消费 -Detailed request payload capture stores up to four JSON payload stages per routed call: +详细请求载荷捕获为每个路由调用存储最多四个 JSON 载荷阶段： -- raw request received from the client -- translated request actually sent upstream -- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata -- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form +- 从客户端接收的原始请求 +- 实际发送到上游的翻译后请求 +- 以 JSON 重构的服务商响应；流式响应压缩为最终摘要加流元数据 +- OmniRoute 返回的最终客户端响应；流式响应以相同压缩摘要形式存储 -## Security-Sensitive Boundaries +## 安全敏感边界 -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics +- JWT 密钥（`JWT_SECRET`）保护控制台会话 Cookie 验证/签名 +- 初始密码引导（`INITIAL_PASSWORD`）用于首次运行配置时显式设定 +- API Key HMAC 密钥（`API_KEY_SECRET`）保护生成的本地 API Key 格式 +- 服务商密钥（API Key/Token）持久化存储在本地数据库中，应在文件系统层面加以保护 +- 云端同步端点依赖 API Key 认证 + 机器 ID 语义 -## Environment and Runtime Matrix +## 环境与运行时矩阵 -Environment variables actively used by code: +代码中活跃使用的环境变量： -- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` -- Storage: `DATA_DIR` -- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` -- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS` -- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants -- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- 应用/认证：`JWT_SECRET`、`INITIAL_PASSWORD` +- 存储：`DATA_DIR` +- 兼容节点行为：`ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- 可选存储基础路径覆盖（Linux/macOS，`DATA_DIR` 未设置时）：`XDG_CONFIG_HOME` +- 安全哈希：`API_KEY_SECRET`、`MACHINE_ID_SALT` +- 日志：`APP_LOG_TO_FILE`、`APP_LOG_RETENTION_DAYS`、`CALL_LOG_RETENTION_DAYS` +- 同步/云 URL：`NEXT_PUBLIC_BASE_URL`、`NEXT_PUBLIC_CLOUD_URL` +- 出站代理：`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` 及小写变体 +- SOCKS5 特性开关：`ENABLE_SOCKS5_PROXY`、`NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- 平台/运行时辅助（非应用特定配置）：`APPDATA`、`NODE_ENV`、`PORT`、`HOSTNAME` -## Known Architectural Notes +## 已知架构说明 -1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 7 tabs: General, Appearance, AI, Security, Routing, Resilience, Advanced. The Resilience page only configures request queue, connection cooldown, provider breaker, and wait-for-cooldown behavior; live breaker runtime state is shown on the Health page. -9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed. -10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22. -11. **Node.js runtime policy detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime falls outside the supported secure Node.js lines. +1. `usageDb` 和 `localDb` 共享相同的基础目录策略（`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`），并有旧文件迁移机制。 +2. `/api/v1/route.ts` 委托给 `/api/v1/models`（`src/app/api/v1/models/catalog.ts`）使用的同一统一目录构建器，避免语义漂移。 +3. 请求日志记录器在启用时写入完整的 Header 和 Body；应将日志目录视为敏感信息。 +4. 云端行为取决于正确的 `NEXT_PUBLIC_BASE_URL` 和云端端点可达性。 +5. `open-sse/` 目录作为 `@omniroute/open-sse` **npm workspace 包**发布。源码通过 `@omniroute/open-sse/...` 导入（由 Next.js 的 `transpilePackages` 解析）。本文档中的文件路径为了一致性仍使用目录名 `open-sse/`。 +6. 控制台图表使用 **Recharts**（基于 SVG），提供可访问的交互式分析可视化（模型用量柱状图、带成功率的服务商分组表）。 +7. E2E 测试使用 **Playwright**（`tests/e2e/`），通过 `npm run test:e2e` 运行。单元测试使用 **Node.js 测试运行器**（`tests/unit/`），通过 `npm run test:unit` 运行。`src/` 下的源码为 **TypeScript**（`.ts`/`.tsx`）；`open-sse/` workspace 保留 JavaScript（`.js`）。 +8. 设置页面分为 7 个标签页：通用、外观、AI、安全、路由、容灾、高级。容灾页面仅配置请求队列、连接冷却、服务商熔断器和等待冷却行为；熔断器的实时运行时状态显示在健康页面。 +9. **Context Relay** 策略（`context-relay`）分布在两个层中：`combo.ts` 决定是否应生成交接信息，`chat.ts` 在帐户解析后注入交接信息。交接数据存储在 `context_handoffs` SQLite 表中。这种分离是故意的，因为只有 `chat.ts` 知道实际帐户是否发生了变更。 +10. **代理执行**现已全面覆盖：`tokenHealthCheck.ts` 按连接解析代理，`/api/providers/validate` 使用 `runWithProxyContext`，`proxyFetch.ts` 使用 `undici.fetch()` 以在 Node 22 上保持 dispatcher 兼容性。 +11. **Node.js 运行时策略检测**：`/api/settings/require-login` 返回 `nodeVersion` 和 `nodeCompatible` 字段。当运行时不在支持的 Node.js 安全版本范围内时，登录页面会渲染警告横幅。 -## Operational Verification Checklist +## 运维验证清单 -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: +- 从源码构建：`npm run build` +- 构建 Docker 镜像：`docker build -t omniroute .` +- 启动服务并验证： - `GET /api/settings` - `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` +- 当 `PORT=20128` 时，CLI 目标基 URL 应为 `http://:20128/v1` diff --git a/docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md b/docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md index 47814034d842..44baf063a1d6 100644 --- a/docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md @@ -1,587 +1,800 @@ -# omniroute — Codebase Documentation (中文 (简体)) +# OmniRoute 代码库文档（中文 (简体)） -🌐 **Languages:** 🇺🇸 [English](../../../../docs/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../bn/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../da/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../de/docs/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../es/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../fa/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../gu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../he/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../hi/docs/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../id/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../it/docs/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../mr/docs/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../no/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../sw/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../ta/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../te/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../th/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../tr/docs/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../ur/docs/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](../../../../docs/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../bn/docs/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../da/docs/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../de/docs/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../es/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../fa/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../gu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../he/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../hi/docs/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../id/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../it/docs/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../mr/docs/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../no/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../sw/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../ta/docs/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../te/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../th/docs/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../tr/docs/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) · `... [other locales]` --- -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. +> OmniRoute 代码库工程参考文档，面向贡献者和集成开发者。 --- -## 1. What Is omniroute? +## 1. 技术栈 -omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: +| 关注领域 | 技术选型 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------- | +| Web 框架 | **Next.js 16**（App Router，独立输出，无全局中间件） | +| 语言 | **TypeScript 6.0+** — 目标 `ES2022`，`module: esnext`，`moduleResolution: bundler`，`strict: false` | +| 运行时 | **Node.js** `>=22.22.2 <23` 或 `>=24.0.0 <27`（通过 `engines` + `SUPPORTED_NODE_RANGE` 强制） | +| 数据库 | **SQLite**，基于 `better-sqlite3`（单例，WAL 日志模式） | +| 桌面端 | **Electron 41** + `electron-builder` 26.10（独立工作空间 `electron/`） | +| 测试 | **Node 原生测试运行器**（单元/集成）、**Vitest**（MCP、autoCombo、缓存）、**Playwright**（端到端 + 协议端到端） | +| 构建 | Next.js 独立模式，通过 `scripts/build/build-next-isolated.mjs` | +| 代码检查 | ESLint flat 配置 + Prettier（Husky pre-commit 触发 `lint-staged`） | +| 模块系统 | 全局 ESM（`"type": "module"`） | +| 工作空间 | npm workspace — `open-sse` 是唯一的子工作空间 | -> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. +路径别名（`tsconfig.json`）： -Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. +- `@/*` → `src/*` +- `@omniroute/open-sse` → `open-sse/index.ts` +- `@omniroute/open-sse/*` → `open-sse/*` + +默认 HTTP 端口：**`20128`**（API 和仪表盘共享同一进程）。数据目录由 `DATA_DIR` 环境变量指定，默认为 `~/.omniroute/`。 --- -## 2. Architecture Overview - -```mermaid -graph LR - subgraph Clients - A[Claude CLI] - B[Codex] - C[Cursor IDE] - D[OpenAI-compatible] - end - - subgraph omniroute - E[Handler Layer] - F[Translator Layer] - G[Executor Layer] - H[Services Layer] - end - - subgraph Providers - I[Anthropic Claude] - J[Google Gemini] - K[OpenAI / Codex] - L[GitHub Copilot] - M[AWS Kiro] - N[Antigravity] - O[Cursor API] - end - - A --> E - B --> E - C --> E - D --> E - E --> F - F --> G - G --> I - G --> J - G --> K - G --> L - G --> M - G --> N - G --> O - H -.-> E - H -.-> G +## 2. 仓库布局 + +``` +OmniRoute/ +├── src/ Next.js 应用（App Router、库、领域层、服务端、共享模块） +├── open-sse/ 流式传输引擎工作空间（@omniroute/open-sse） +├── electron/ 桌面端封装（Electron 41 主进程 + preload） +├── bin/ CLI 入口点（omniroute、reset-password） +├── tests/ 单元、集成、端到端、协议端到端、翻译器、安全、测试夹具 +├── scripts/ 构建、同步、检查、迁移及运行时辅助脚本 +├── docs/ 公开文档（本目录） +├── public/ 静态资源、PWA manifest、Service Worker +├── config/ 运行时配置示例 +├── images/ 市场/截图资源 +├── _ideia/, _references/, _mono_repo/, _tasks/ 内部草稿/规划（不发布） +├── CLAUDE.md 面向 Claude Code 的仓库规则 +├── AGENTS.md 面向 Agent 的深层架构参考 +├── package.json v3.8.0，工作空间根目录 +└── tsconfig.json 路径别名 + 核心编译选项 ``` -### Core Principle: Hub-and-Spoke Translation +--- -All format translation passes through **OpenAI format as the hub**: +## 3. `src/` — Next.js 应用 ``` -Client Format → [OpenAI Hub] → Provider Format (request) -Provider Format → [OpenAI Hub] → Client Format (response) +src/ +├── app/ App Router 页面 + API 路由 +├── lib/ 核心库（DB、auth、OAuth、技能、记忆系统等） +├── domain/ 纯领域层（策略、容灾、成本、锁定等） +├── server/ 服务端专用模块（authz、cors、auth） +├── shared/ 类型、常量、校验、契约、工具（跨边界安全） +├── mitm/ 面向 CLI 集成的中间人代理辅助工具 +├── models/ 本地模型元数据/别名 +├── sse/ 仍在 src/ 下的旧版 SSE 处理器（非 open-sse/） +├── store/ 客户端状态存储 +├── middleware/ 路由级中间件工具（非 Next.js 全局中间件） +├── scripts/ 可被应用代码导入的树内脚本 +├── types/ 环境类型和共享 TS 类型 +├── i18n/ 语言包 +├── instrumentation.ts Next.js instrumentation 钩子 +├── instrumentation-node.ts +├── server-init.ts 进程级引导（环境变量、DB、任务、同步） +└── proxy.ts 顶层代理引导辅助 ``` -This means you only need **N translators** (one per format) instead of **N²** (every pair). +### 3.1 `src/app/` — App Router ---- +App Router 同时暴露仪表盘 UI 和公开/管理 HTTP API。**不存在全局中间件** — 拦截在路由级别完成。 -## 3. Project Structure +`src/app/` 下的顶层段： -``` -omniroute/ -├── open-sse/ ← Core proxy library (portable, framework-agnostic) -│ ├── index.js ← Main entry point, exports everything -│ ├── config/ ← Configuration & constants -│ ├── executors/ ← Provider-specific request execution -│ ├── handlers/ ← Request handling orchestration -│ ├── services/ ← Business logic (auth, models, fallback, usage) -│ ├── translator/ ← Format translation engine -│ │ ├── request/ ← Request translators (8 files) -│ │ ├── response/ ← Response translators (7 files) -│ │ └── helpers/ ← Shared translation utilities (6 files) -│ └── utils/ ← Utility functions -├── src/ ← Application layer (Express/Worker runtime) -│ ├── app/ ← Web UI, API routes, middleware -│ ├── lib/ ← Database, auth, and shared library code -│ ├── mitm/ ← Man-in-the-middle proxy utilities -│ ├── models/ ← Database models -│ ├── shared/ ← Shared utilities (wrappers around open-sse) -│ ├── sse/ ← SSE endpoint handlers -│ └── store/ ← State management -├── data/ ← Runtime data (credentials, logs) -│ └── provider-credentials.json (external credentials override, gitignored) -└── tester/ ← Test utilities -``` +| 路径 | 用途 | +| ------------------------------------------------------------------------------ | --------------------------------- | +| `api/` | 所有 HTTP API 路由（详见下文分解）| +| `a2a/` | A2A JSON-RPC 2.0 端点（`POST /a2a`）| +| `.well-known/agent.json/` | A2A Agent Card 发现文档 | +| `(dashboard)/` | 仪表盘 UI（路由组，无 URL 前缀） | +| `auth/`、`login/`、`forgot-password/`、`callback/` | 认证流程 | +| `landing/` | 市场/落地页 | +| `docs/` | 嵌入式 API 文档查看器 | +| `status/`、`maintenance/`、`offline/` | 运维页面 | +| `privacy/`、`terms/` | 法律页面 | +| `400/`、`401/`、`403/`、`408/`、`429/`、`500/`、`502/`、`503/` | 静态错误页面 | +| `error.tsx`、`global-error.tsx`、`not-found.tsx`、`forbidden/`、`loading.tsx` | 框架错误/加载边界 | +| `layout.tsx`、`page.tsx`、`globals.css`、`manifest.ts` | 根外壳 | ---- +#### 3.1.1 `src/app/(dashboard)/dashboard/` — UI 页面 -## 4. Module-by-Module Breakdown - -### 4.1 Config (`open-sse/config/`) - -The **single source of truth** for all provider configuration. - -| File | Purpose | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | -| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | -| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | -| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | - -#### Credential Loading Flow - -```mermaid -flowchart TD - A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] - B --> C{"data/provider-credentials.json\nexists?"} - C -->|Yes| D["credentialLoader reads JSON"] - C -->|No| E["Use hardcoded defaults"] - D --> F{"For each provider in JSON"} - F --> G{"Provider exists\nin PROVIDERS?"} - G -->|No| H["Log warning, skip"] - G -->|Yes| I{"Value is object?"} - I -->|No| J["Log warning, skip"] - I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] - K --> F - H --> F - J --> F - F -->|Done| L["PROVIDERS ready with\nmerged credentials"] - E --> L -``` +`agents`、`analytics`、`api-manager`、`audit`、`auto-combo`、`batch`、`cache`、 +`changelog`、`cli-tools`、`cloud-agents`、`combos`、`compression`、`context`、 +`costs`、`endpoint`、`health`、`limits`、`logs`、`memory`、`onboarding`、 +`playground`、`providers`、`search-tools`、`settings`、`skills`、`system`、 +`translator`、`usage`、`webhooks`，外加根目录 `page.tsx`、`HomePageClient.tsx`、 +`BootstrapBanner.tsx`。 ---- +#### 3.1.2 `src/app/api/` — 顶层 API 分组 -### 4.2 Executors (`open-sse/executors/`) - -Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. - -```mermaid -classDiagram - class BaseExecutor { - +buildUrl(model, stream, options) - +buildHeaders(credentials, stream, body) - +transformRequest(body, model, stream, credentials) - +execute(url, options) - +shouldRetry(status, error) - +refreshCredentials(credentials, log) - } - - class DefaultExecutor { - +refreshCredentials() - } - - class AntigravityExecutor { - +buildUrl() - +buildHeaders() - +transformRequest() - +shouldRetry() - +refreshCredentials() - } - - class CursorExecutor { - +buildUrl() - +buildHeaders() - +transformRequest() - +parseResponse() - +generateChecksum() - } - - class KiroExecutor { - +buildUrl() - +buildHeaders() - +transformRequest() - +parseEventStream() - +refreshCredentials() - } - - BaseExecutor <|-- DefaultExecutor - BaseExecutor <|-- AntigravityExecutor - BaseExecutor <|-- CursorExecutor - BaseExecutor <|-- KiroExecutor - BaseExecutor <|-- CodexExecutor - BaseExecutor <|-- GithubExecutor +``` +src/app/api/ +├── a2a/{status, tasks} +├── acp/ +├── admin/ +├── analytics/ +├── assess/ +├── auth/ +├── batches/ +├── cache/ +├── cli-tools/ +├── cloud/{codex-responses-ws} +├── combos/ +├── compliance/ +├── compression/ +├── context/ +├── db/, db-backups/ +├── evals/ +├── fallback/ +├── files/ +├── health/ +├── init/ +├── internal/{concurrency} +├── keys/ +├── logs/ +├── mcp/{audit, sse, status, stream, tools} +├── memory/{health, [id]/, route.ts} +├── model-combo-mappings/ +├── models/ +├── monitoring/ +├── oauth/ +├── openapi/ +├── policies/ +├── pricing/ +├── provider-metrics/, provider-models/, provider-nodes/ +├── providers/ +├── rate-limit/, rate-limits/ +├── resilience/ +├── restart/, shutdown/ +├── search/ +├── sessions/ +├── settings/ +├── skills/{executions, [id], install, marketplace, route.ts, skillssh} +├── storage/ +├── sync/, synced-available-models/ +├── system/ +├── tags/ +├── telemetry/ +├── token-health/ +├── translator/ +├── tunnels/ +├── services/ 嵌入式服务管理（9router、cliproxy）— LOCAL_ONLY +├── upstream-proxy/ +├── usage/ +├── v1/ OpenAI 兼容公开 API +├── v1beta/ Gemini 风格兼容 +├── version-manager/ +└── webhooks/ ``` -| Executor | Provider | Key Specializations | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | -| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | -| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | -| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | -| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | -| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | +#### 3.1.2a `src/app/api/services/` — 嵌入式服务管理 ---- +用于安装、启动、停止和监控 9Router 与 CLIProxyAPI 的路由。 +所有路径均分类为 **LOCAL_ONLY**（仅 loopback，硬规则 #17），因为它们可能调用 `npm install` 并生成子进程。 -### 4.3 Handlers (`open-sse/handlers/`) - -The **orchestration layer** — coordinates translation, execution, streaming, and error handling. - -| File | Purpose | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | -| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | -| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | -| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | - -#### Request Lifecycle (chatCore.ts) - -```mermaid -sequenceDiagram - participant Client - participant chatCore - participant Translator - participant Executor - participant Provider - - Client->>chatCore: Request (any format) - chatCore->>chatCore: Detect source format - chatCore->>chatCore: Check bypass patterns - chatCore->>chatCore: Resolve model & provider - chatCore->>Translator: Translate request (source → OpenAI → target) - chatCore->>Executor: Get executor for provider - Executor->>Executor: Build URL, headers, transform request - Executor->>Executor: Refresh credentials if needed - Executor->>Provider: HTTP fetch (streaming or non-streaming) - - alt Streaming - Provider-->>chatCore: SSE stream - chatCore->>chatCore: Pipe through SSE transform stream - Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source - chatCore-->>Client: Translated SSE stream - else Non-streaming - Provider-->>chatCore: JSON response - chatCore->>Translator: Translate response - chatCore-->>Client: Translated JSON - end - - alt Error (401, 429, 500...) - chatCore->>Executor: Retry with credential refresh - chatCore->>chatCore: Account fallback logic - end +``` +src/app/api/services/ +├── 9router/ +│ ├── _lib.ts getOrInitSupervisor() 辅助函数 +│ ├── install/route.ts POST — 通过 execFile 执行 npm install +│ ├── start/route.ts POST — supervisor.start() +│ ├── stop/route.ts POST — supervisor.stop() +│ ├── restart/route.ts POST — supervisor.restart() +│ ├── update/route.ts POST — npm install 更新版本 +│ ├── rotate-key/route.ts POST — 生成新的 API Key 并重启 +│ ├── status/route.ts GET — 实时 + DB 状态 + 版本元数据 +│ └── auto-start/route.ts POST — 切换 auto_start 标志 +├── cliproxy/ +│ ├── _lib.ts getOrInitSupervisor() 辅助函数 +│ ├── install/route.ts POST — npm install +│ ├── start/route.ts POST — supervisor.start() +│ ├── stop/route.ts POST — supervisor.stop() +│ ├── restart/route.ts POST — supervisor.restart() +│ ├── update/route.ts POST — npm install 更新版本 +│ ├── status/route.ts GET — 实时 + DB 状态 + 版本元数据 +│ └── auto-start/route.ts POST — 切换 auto_start 标志 +└── [name]/ + └── logs/route.ts GET — SSE 日志尾部（所有服务共享） ``` ---- +对应仪表盘 UI： +`src/app/(dashboard)/dashboard/providers/services/` — 双标签页（CLIProxyAPI + 9Router）。 +9Router 嵌入式 UI 的反向代理： +`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[...path]/route.ts` -### 4.4 Services (`open-sse/services/`) - -Business logic that supports the handlers and executors. - -| File | Purpose | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | -| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | -| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | -| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | -| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | -| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | -| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | -| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | -| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | -| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | -| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | -| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | -| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | -| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | - -#### Token Refresh Deduplication - -```mermaid -sequenceDiagram - participant R1 as Request 1 - participant R2 as Request 2 - participant Cache as refreshPromiseCache - participant OAuth as OAuth Provider - - R1->>Cache: getAccessToken("gemini", token) - Cache->>Cache: No in-flight promise - Cache->>OAuth: Start refresh - R2->>Cache: getAccessToken("gemini", token) - Cache->>Cache: Found in-flight promise - Cache-->>R2: Return existing promise - OAuth-->>Cache: New access token - Cache-->>R1: New access token - Cache-->>R2: Same access token (shared) - Cache->>Cache: Delete cache entry -``` +深入阅读：`docs/frameworks/EMBEDDED-SERVICES.md` -#### Account Fallback State Machine - -```mermaid -stateDiagram-v2 - [*] --> Active - Active --> Error: Request fails (401/429/500) - Error --> Cooldown: Apply backoff - Cooldown --> Active: Cooldown expires - Active --> Active: Request succeeds (reset backoff) - - state Error { - [*] --> ClassifyError - ClassifyError --> ShouldFallback: Rate limit / Auth / Transient - ClassifyError --> NoFallback: 400 Bad Request - } - - state Cooldown { - [*] --> ExponentialBackoff - ExponentialBackoff: Level 0 = 1s - ExponentialBackoff: Level 1 = 2s - ExponentialBackoff: Level 2 = 4s - ExponentialBackoff: Max = 2min - } +#### 3.1.3 `src/app/api/v1/` — OpenAI 兼容公开 API + +``` +v1/ +├── accounts/[id]/ 账户查询 +├── agents/tasks/[id]/, agents/tasks/ A2A 风格的任务端点 +├── api/ v1/api 下暴露的内部 API 辅助工具 +├── audio/{speech, transcriptions}/ TTS + STT +├── batches/[id]/{cancel}, batches/ OpenAI Batches API +├── chat/completions/ 对话补全（主要端点） +├── chatgpt-web/ ChatGPT-Web 兼容 +├── completions/ 旧版文本补全 +├── embeddings/ 嵌入 +├── files/[id]/, files/ Files API +├── _helpers/ 共享路由辅助工具（无公开 URL） +├── images/{edits, generations}/ 图像生成 + 编辑 +├── issues/ 诊断辅助端点 +├── management/{proxies}/ v1 内的管理权限域路由 +├── messages/{count_tokens}/ Anthropic 风格消息兼容 +├── models/ 模型列表（`route.ts`、`catalog.ts`） +├── moderations/ 内容审核 +├── music/ 音乐生成 +├── providers/[provider]/ 按服务商操作 +├── quotas/{check} 配额探测 +├── registered-keys/ 注册 Key 管理 +├── rerank/ 重排序 +├── responses/[...path]/ OpenAI Responses API（通配路由） +├── search/ 网页搜索 +├── videos/ 视频生成 +├── ws/ WebSocket 桥接 +└── route.ts 索引处理器 ``` -#### Combo Model Chain - -```mermaid -flowchart LR - A["Request with\ncombo model"] --> B["Model A"] - B -->|"2xx Success"| C["Return response"] - B -->|"429/401/500"| D{"Fallback\neligible?"} - D -->|Yes| E["Model B"] - D -->|No| F["Return error"] - E -->|"2xx Success"| C - E -->|"429/401/500"| G{"Fallback\neligible?"} - G -->|Yes| H["Model C"] - G -->|No| F - H -->|"2xx Success"| C - H -->|"Fail"| I["All failed →\nReturn last status"] +每个路由文件遵循相同模式： + +``` +路由 → CORS 预检 → Zod 请求体验证 → 可选认证 + → API Key 策略执行 → 处理器委托（open-sse） ``` ---- +`v1beta/` 是 Gemini 风格兼容层（一个薄封装，翻译后进入相同的 `open-sse/handlers/` 管道）。 + +### 3.2 `src/lib/` — 核心库 + +始终通过这些模块导入数据、同步、OAuth、技能、记忆等。下表按实际目录和重要顶层文件分组。 + +| 模块 | 用途 | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `a2a/` | A2A 协议服务器：`taskManager.ts`、`streaming.ts`、`taskExecution.ts`、`routingLogger.ts`、`skills/`（6 个技能：成本分析、健康报告、服务商发现、配额管理、智能路由、列出能力） | +| `acp/` | Agent-Control-Protocol：`index.ts`、`manager.ts`、`registry.ts` | +| `api/` | 内部 API 辅助工具：`requireManagementAuth.ts`、`requireCliToolsAuth.ts`、`errorResponse.ts` | +| `auth/` | `managementPassword.ts`（密码重置/哈希） | +| `batches/` | OpenAI Batches API 服务（`service.ts`） | +| `catalog/` | OpenRouter 目录同步（`openrouterCatalog.ts`） | +| `cloudAgent/` | 云代理注册表：`api.ts`、`baseAgent.ts`、`db.ts`、`index.ts`、`registry.ts`、`types.ts`、`agents/{codex, devin, jules}.ts` | +| `combos/` | Combo 解析辅助工具 | +| `compliance/` | 审计 + 服务商审计：`index.ts`、`providerAudit.ts` | +| `config/` | 运行时配置粘合层 | +| `db/` | SQLite 领域模块（见 §3.2.1） | +| `display/` | API 响应使用的 UI/展示辅助工具 | +| `embeddings/` | 嵌入服务注册表 | +| `env/` | 环境变量加载 + 自检 | +| `evals/` | 评估框架运行时 | +| `guardrails/` | `piiMasker.ts`、`promptInjection.ts`、`visionBridge.ts`、`visionBridgeHelpers.ts`、`registry.ts`、`base.ts` | +| `jobs/` | 后台任务（`autoUpdate.ts` 等） | +| `memory/` | 持久化记忆：`store.ts`、`cache.ts`、`retrieval.ts`、`summarization.ts`、`extraction.ts`、`injection.ts`、`qdrant.ts`、`settings.ts`、`verify.ts`、`schemas.ts`、`types.ts` | +| `monitoring/` | `observability.ts` | +| `oauth/` | OAuth 服务商（14 个）：`antigravity`、`claude`、`cline`、`codex`、`cursor`、`gemini`、`github`、`gitlab-duo`、`kilocode`、`kimi-coding`、`kiro`、`qoder`、`qwen`、`windsurf`，以及 `services/`、`utils/{pkce, server, banner, codexAuthFile, ui}`、`constants/oauth.ts` | +| `plugins/` | 插件加载器（`index.ts`） | +| `promptCache/` | `prefixAnalyzer.ts`、`index.ts` | +| `providerModels/` | 托管模型生命周期：`modelDiscovery.ts`、`managedModelImport.ts`、`managedAvailableModels.ts`、`cursorAgent.ts` | +| `providers/` | 服务商辅助工具：`catalog.ts`、`validation.ts`、`imageValidation.ts`、`claudeExtraUsage.ts`、`codexConnectionDefaults.ts`、`codexFastTier.ts`、`webCookieAuth.ts`、`managedAvailableModels.ts`、`requestDefaults.ts` | +| `resilience/` | `settings.ts` — 熔断器、冷却、锁定的设置 | +| `runtime/` | 运行时特性检测 | +| `search/` | `executeWebSearch.ts` | +| `services/` | 嵌入式服务框架：`ServiceSupervisor.ts`（通用子进程管理器，带操作锁、环形缓冲区、健康检查器）、`bootstrap.ts`（进程级注册和自动启动）、`registry.ts`（工具 → 管理器映射）、`apiKey.ts`（AES-256-GCM Key 存储）、`modelSync.ts`（定期模型同步）、`ringBuffer.ts`（5 MB 环形日志缓冲）、`healthCheck.ts`（HTTP 健康探测）、`types.ts`、`embedWsProxy.ts`（WebSocket 代理）、`installers/{ninerouter,cliproxy}.ts`。详见 `docs/frameworks/EMBEDDED-SERVICES.md` | +| `agentSkills/` | Agent Skills 目录 + 生成器：`catalog.ts`（getCatalog/getSkillById/filterCatalog/computeCoverage）、`generator.ts`（generateAgentSkills → 写入 `skills/{id}/SKILL.md`）、`openapiParser.ts`（从 OpenAPI 规范提取 REST 端点）、`cliRegistryParser.ts`（从 bin/cli-registry 提取 CLI 子命令）、`schemas.ts`（Zod：AgentSkillSchema、SkillCoverageSchema、ListQuerySchema、GenerateBodySchema）、`types.ts`（AgentSkill、SkillCoverage、SkillMarkdown、GeneratorReport）。被 REST 路由（`/api/agent-skills/*`）、MCP 工具（`omniroute_agent_skills_*`）和 A2A 技能 `list-capabilities` 消费。参见 [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md)。 | +| `skills/` | 技能框架：`registry.ts`、`executor.ts`、`interception.ts`、`injection.ts`、`sandbox.ts`、`custom.ts`、`hybrid.ts`、`builtins.ts`、`a2a.ts`、`providerSettings.ts`、`schemas.ts`、`skillssh.ts`、`types.ts`，以及 `builtin/browser.ts` | +| `spend/` | `batchWriter.ts`（写后缓冲） | +| `sync/` | `bundle.ts`、`tokens.ts`（云同步） | +| `system/` | 系统级辅助工具 | +| `translator/` | 顶层翻译器粘合层（委托到 `open-sse/translator/`） | +| `usage/` | 用量核算：`costCalculator.ts`、`tokenAccounting.ts`、`usageHistory.ts`、`aggregateHistory.ts`、`usageStats.ts`、`callLogs.ts`、`callLogArtifacts.ts`、`fetcher.ts`、`providerLimits.ts`、`migrations.ts` | +| `versionManager/` | 自动更新 + 版本清单 | +| `ws/` | WebSocket 桥接 | +| `zed-oauth/` | Zed 编辑器 OAuth 流程 | + +`src/lib/` 中的顶层文件： + +- `localDb.ts` — 仅作重新导出层。**切勿**在此添加逻辑。 +- `proxyHealth.ts`、`proxyLogger.ts`、`tokenHealthCheck.ts`、`localHealthCheck.ts` +- `oneproxyRotator.ts`、`oneproxySync.ts` +- `apiBridgeServer.ts`、`cacheLayer.ts`、`semanticCache.ts`、`settingsCache.ts` +- `cloudSync.ts`、`initCloudSync.ts` +- `cloudflaredTunnel.ts`、`ngrokTunnel.ts`、`tailscaleTunnel.ts` +- `consoleInterceptor.ts`、`container.ts`、`gracefulShutdown.ts`、`idempotencyLayer.ts` +- `ipUtils.ts`、`logEnv.ts`、`logPayloads.ts`、`logRotation.ts` +- `modelAliasSeed.ts`、`modelCapabilities.ts`、`modelMetadataRegistry.ts`、`modelsDevSync.ts` +- `piiSanitizer.ts`、`pricingSync.ts` +- `apiKeyExposure.ts`、`cacheControlSettings.ts`、`dataPaths.ts`、`toolPolicy.ts` +- `translatorEvents.ts`、`usageDb.ts`、`usageAnalytics.ts`、`webhookDispatcher.ts` + +#### 3.2.1 `src/lib/db/` + +单例 SQLite 数据库（`core.ts` 中的 `getDbInstance()`，WAL 日志模式）。 +**切勿在路由或处理器中直接写 SQL** — 应通过这些模块访问。 + +![数据库 Schema 概览（精选核心表）](../diagrams/exported/db-schema-overview.svg) + +> 来源：[diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd) + +领域模块（每个模块拥有一张或多张表）：`apiKeys.ts`、`backup.ts`、 +`batches.ts`、`cleanup.ts`、`cliToolState.ts`、`combos.ts`、 +`commandCodeAuth.ts`、`compression.ts`、`compressionAnalytics.ts`、 +`compressionCacheStats.ts`、`compressionCombos.ts`、`compressionScheduler.ts`、 +`contextHandoffs.ts`、`core.ts`、`creditBalance.ts`、`databaseSettings.ts`、 +`detailedLogs.ts`、`domainState.ts`、`encryption.ts`、`evals.ts`、`files.ts`、 +`healthCheck.ts`、`jsonMigration.ts`、`migrationRunner.ts`、 +`modelComboMappings.ts`、`models.ts`、`oneproxy.ts`、`prompts.ts`、 +`providers.ts`、`providerLimits.ts`、`proxies.ts`、`quotaSnapshots.ts`、 +`readCache.ts`、`reasoningCache.ts`、`registeredKeys.ts`、`secrets.ts`、 +`sessionAccountAffinity.ts`、`settings.ts`、`stateReset.ts`、`stats.ts`、 +`syncTokens.ts`、`tierConfig.ts`、`upstreamProxy.ts`、`versionManager.ts`、 +`webhooks.ts`。 + +`migrations/` 包含 55 个带版本号的 `.sql` 文件（幂等、事务性），由 `migrationRunner.ts` 在启动时执行。 + +所有迁移中创建的表（52 张总计）： + +`a`、`account_key_limits`、`api_keys`、`batches`、`call_logs`、 +`combo_adaptation_state`、`combos`、`command_code_auth_sessions`、 +`compression_analytics`、`compression_cache_stats`、 +`compression_combo_assignments`、`compression_combos`、`context_handoffs`、 +`daily_usage_summary`、`db_meta`、`domain_budgets`、`domain_circuit_breakers`、 +`domain_cost_history`、`domain_fallback_chains`、`domain_lockout_state`、 +`eval_cases`、`eval_runs`、`eval_suites`、`files`、`hourly_usage_summary`、 +`key_value`、`mcp_tool_audit`、`memories`、`model_combo_mappings`、 +`provider_connections`、`provider_key_limits`、`provider_nodes`、 +`proxy_assignments`、`proxy_logs`、`proxy_registry`、`quota_snapshots`、 +`reasoning_cache`、`registered_keys`、`request_detail_logs`、 +`routing_decisions`、`semantic_cache`、`session_account_affinity`、 +`skill_executions`、`skills`、`sync_tokens`、`tier_assignments`、 +`tier_config`、`upstream_proxy_config`、`usage_history`、`version_manager`、 +`webhooks`（以及用于记忆搜索的 FTS5 虚拟表）。 + +### 3.3 `src/domain/` — 领域层 + +纯业务逻辑，无 I/O。被路由和处理器导入。 + +| 文件 | 用途 | +| -------------------------------------------- | --------------------------------- | +| `policyEngine.ts` | 顶层策略解析器 | +| `fallbackPolicy.ts` | 容灾决策树 | +| `costRules.ts` | 成本计算规则 | +| `lockoutPolicy.ts` | 模型锁定决策 | +| `tagRouter.ts` | 基于标签的路由 | +| `comboResolver.ts` | Combo 解析（请求 → 目标列表） | +| `connectionModelRules.ts` | 按连接过滤模型 | +| `modelAvailability.ts` | 模型可用性检查 | +| `degradation.ts` | 降级模式切换 | +| `providerExpiration.ts` | 过期账户/Key 检测 | +| `quotaCache.ts` | 缓存配额决策 | +| `responses.ts`、`omnirouteResponseMeta.ts` | 响应格式辅助工具 | +| `configAudit.ts` | 配置变更审计 | +| `assessment/` | 模型评估（按 RFC，部分实现） | +| `types.ts` | 共享领域类型 | + +### 3.4 `src/server/` — 服务端专用 + +不可从客户端组件导入。 -### 4.5 Translator (`open-sse/translator/`) - -The **format translation engine** using a self-registering plugin system. - -#### 架构 - -```mermaid -graph TD - subgraph "Request Translation" - A["Claude → OpenAI"] - B["Gemini → OpenAI"] - C["Antigravity → OpenAI"] - D["OpenAI Responses → OpenAI"] - E["OpenAI → Claude"] - F["OpenAI → Gemini"] - G["OpenAI → Kiro"] - H["OpenAI → Cursor"] - end - - subgraph "Response Translation" - I["Claude → OpenAI"] - J["Gemini → OpenAI"] - K["Kiro → OpenAI"] - L["Cursor → OpenAI"] - M["OpenAI → Claude"] - N["OpenAI → Antigravity"] - O["OpenAI → Responses"] - end +``` +server/ +├── auth/loginGuard.ts +├── authz/ +│ ├── classify.ts 将路由分类为公开 vs 管理 +│ ├── assertAuth.ts 断言辅助工具 +│ ├── context.ts 按请求的 authz 上下文 +│ ├── headers.ts +│ ├── pipeline.ts Authz 管道 +│ ├── policies/ 具体策略 +│ └── types.ts +└── cors/origins.ts CORS 来源白名单 ``` -| Directory | Files | Description | -| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | -| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | -| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | -| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +### 3.5 `src/shared/` — 安全共享模块 + +划分为聚焦的子目录： + +- `constants/` — `providers.ts`（经 Zod 校验的服务商目录）、`models.ts`、 + `modelSpecs.ts`、`modelCompat.ts`、`pricing.ts`、`cliTools.ts`、 + `cliCompatProviders.ts`、`routingStrategies.ts`、`comboConfigMode.ts`、 + `headers.ts`、`upstreamHeaders.ts`（拒绝名单）、`mcpScopes.ts`、 + `errorCodes.ts`、`publicApiRoutes.ts`、`batch.ts`、`batchEndpoints.ts`、 + `bodySize.ts`、`colors.ts`、`appConfig.ts`、`config.ts`、 + `sidebarVisibility.ts`、`visionBridgeDefaults.ts`。 +- `validation/` — `schemas.ts`（约 80 个 Zod Schema）、`compressionConfigSchemas.ts`、 + `oneproxySchemas.ts`、`providerSchema.ts`、`settingsSchemas.ts`、`helpers.ts`。 +- `contracts/` — 发布到 npm 的公开 API 契约。 +- `types/` — 共享 TS 类型。 +- `utils/` — `circuitBreaker.ts`、`apiAuth.ts`、`apiKey.ts`、`apiKeyPolicy.ts`、 + `apiResponse.ts`、`api.ts`、`classify429.ts`、`cliCompat.ts`、`clipboard.ts`、 + `cloud.ts`、`cn.ts`、`cors.ts`、`costEstimator.ts`、`featureFlags.ts`、 + `fetchTimeout.ts`、`formatting.ts`、`inputSanitizer.ts`、`logger.ts`、 + `machine.ts`、`machineId.ts`、`maskEmail.ts`、`modelCatalogSearch.ts`、 + `nodeRuntimeSupport.ts`、`parseApiKeys.ts`、`providerHints.ts`、 + `providerModelAliases.ts`、`rateLimiter.ts`、`releaseNotes.ts`、 + `a11yAudit.ts`，以及 `services/`、`network/`、 + `middleware/`、`schemas/`、`hooks/`、`components/` 下的仪表盘钩子/组件。 + +--- -#### Key Design: Self-Registering Plugins +## 4. `open-sse/` — 流式传输引擎工作空间 -```javascript -// Each translator file calls register() on import: -import { register } from "../index.js"; -register("claude", "openai", translateClaudeToOpenAI); +独立的 npm workspace，发布为 `@omniroute/open-sse`。负责请求处理、执行器、翻译器、服务、转换器和 MCP 服务器。 -// The index.js imports all translator files, triggering registration: -import "./request/claude-to-openai.js"; // ← self-registers ``` +open-sse/ +├── index.ts 公开导出 +├── package.json 工作空间清单 +├── tsconfig.json +├── types.d.ts +├── config/ 服务商注册表、请求头配置、身份标识等 +├── handlers/ 请求处理器（对话、嵌入、音频、图像等） +├── executors/ 45 个服务商专用 HTTP 执行器 +├── translator/ 格式转换（OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro） +├── transformer/ Responses API ↔ Chat Completions 流式转换器 +├── services/ 80+ 服务模块（Combo、容灾、配额、身份等） +├── utils/ 流式传输辅助、TLS 客户端、AWS SigV4、代理 fetch 等 +└── mcp-server/ MCP 服务器（3 种传输、30 个权限域、94 个工具） +``` + +### 4.1 `open-sse/handlers/` + +| 处理器 | 用途 | +| ------------------------- | ------------------------------------------ | +| `chatCore.ts` | 主对话管道（缓存、速率限制、Combo 路由、执行器调度）| +| `responsesHandler.ts` | OpenAI Responses API 入口 | +| `embeddings.ts` | 嵌入 | +| `imageGeneration.ts` | 图像生成 | +| `audioSpeech.ts` | Text-to-speech | +| `audioTranscription.ts` | Speech-to-text | +| `videoGeneration.ts` | 视频生成 | +| `musicGeneration.ts` | 音乐生成 | +| `rerank.ts` | 重排序 | +| `moderations.ts` | 内容审核 | +| `search.ts` | 网页搜索 | +| `sseParser.ts` | SSE 事件解析器 | +| `usageExtractor.ts` | 从上游流中提取 Token 计数 | +| `responseSanitizer.ts` | 去除服务商专用噪音 | +| `responseTranslator.ts` | 服务商响应与翻译器层之间的粘合 | + +### 4.2 `open-sse/executors/` + +68 个服务商执行器，各自扩展 `BaseExecutor`（`base.ts`）： + +`antigravity`、`azure-openai`、`blackbox-web`、`chatgpt-web`、`cliproxyapi`、 +`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、 +`muse-spark-web`、`nlpcloud`、`opencode`、`perplexity-web`、`petals`、 +`pollinations`、`puter`、`qoder`、`vertex`、`windsurf`，以及 `claudeIdentity.ts` +（共享身份标识辅助）和 `index.ts`（注册表）。 + +> 注意：未在此列出的服务商由 `default.ts` 通过通用 OpenAI 兼容执行器提供服务。完整的服务商目录（237 条目）位于 `src/shared/constants/providers.ts`。 + +### 4.3 `open-sse/translator/` + +中枢辐射式翻译（OpenAI 为中枢）。 + +- **9 个请求翻译器**（`translator/request/`）： + `antigravity-to-openai`、`claude-to-gemini`、`claude-to-openai`、 + `gemini-to-openai`、`openai-responses`、`openai-to-claude`、 + `openai-to-cursor`、`openai-to-gemini`、`openai-to-kiro`。 +- **9 个响应翻译器**（`translator/response/`）： + `claude-to-openai`、`cursor-to-openai`、`gemini-to-claude`、`gemini-to-openai`、 + `kiro-to-openai`、`openai-responses`、`openai-to-antigravity`、 + `openai-to-claude`。 +- **9 个辅助工具**（`translator/helpers/`）： + `claudeHelper`、`geminiHelper`、`geminiToolsSanitizer`、`maxTokensHelper`、 + `openaiHelper`、`responsesApiHelper`、`schemaCoercion`、`toolCallHelper`，以及 + 辅助工具测试。 +- **图片辅助工具**（`translator/image/sizeMapper.ts`）。 +- 顶层：`bootstrap.ts`、`formats.ts`、`registry.ts`、`index.ts`。 + +### 4.4 `open-sse/transformer/` + +- `responsesTransformer.ts` — 基于 `TransformStream` 的 Responses API ↔ Chat + Completions 转换器（被 `responses/` 通配路由使用）。 + +### 4.5 `open-sse/services/` + +重点关注（完整列表见 `open-sse/services/`）： + +| 关注领域 | 文件 | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Combo 路由 | `combo.ts`（17 种策略）、`comboConfig.ts`、`comboMetrics.ts`、`comboManifestMetrics.ts`、`comboAgentMiddleware.ts` | +| Auto Combo 引擎 | `autoCombo/` — `engine.ts`、`scoring.ts`、`taskFitness.ts`、`virtualFactory.ts`、`modePacks.ts`、`autoPrefix.ts`、`persistence.ts`、`providerDiversity.ts`、`providerRegistryAccessor.ts`、`routerStrategy.ts`、`selfHealing.ts`、`index.ts` | +| 容灾 | `accountFallback.ts`（冷却 + 锁定）、`errorClassifier.ts`、`emergencyFallback.ts`、`rateLimitManager.ts`、`rateLimitSemaphore.ts`、`accountSemaphore.ts`、`accountSelector.ts` | +| 配额 | `quotaMonitor.ts`、`quotaPreflight.ts`、`bailianQuotaFetcher.ts`、`codexQuotaFetcher.ts`、`deepseekQuotaFetcher.ts`、`crofUsageFetcher.ts`、`antigravityCredits.ts` | +| 缓存 | `reasoningCache.ts`、`searchCache.ts`、`signatureCache.ts`、`requestDedup.ts` | +| 路由智能 | `intentClassifier.ts`、`taskAwareRouter.ts`、`backgroundTaskDetector.ts`、`volumeDetector.ts`、`wildcardRouter.ts`、`workflowFSM.ts`、`specificityDetector.ts`、`specificityRules.ts`、`specificityTypes.ts` | +| 模型处理 | `modelCapabilities.ts`、`modelDeprecation.ts`、`modelFamilyFallback.ts`、`modelStrip.ts`、`model.ts`、`provider.ts`、`providerRequestDefaults.ts`、`providerCostData.ts`、`payloadRules.ts` | +| 压缩 | `compression/` — 完整的压缩引擎接线 | +| Token + 会话 | `tokenRefresh.ts`、`sessionManager.ts`、`apiKeyRotator.ts`、`contextManager.ts`、`contextHandoff.ts`、`systemPrompt.ts`、`roleNormalizer.ts`、`responsesInputSanitizer.ts`、`toolSchemaSanitizer.ts`、`toolLimitDetector.ts`、`thinkingBudget.ts` | +| 层级 / 清单 | `tierResolver.ts`、`tierConfig.ts`、`tierDefaults.json`、`tierTypes.ts`、`manifestAdapter.ts` | +| IP / 网络 | `ipFilter.ts`、`webSearchFallback.ts` | +| 批次 | `batchProcessor.ts` | +| 用量 | `usage.ts` | + +### 4.6 `open-sse/mcp-server/` + +- **31 个已注册工具**，在 `server.ts` 中接线（12 个在 `schemas/tools.ts` 下分配了权限域，5 个压缩工具、3 个记忆工具、4 个技能工具，外加通过 `advancedTools.ts` 添加的高级工具）。 +- **3 种传输**：stdio、HTTP Streamable、SSE。 +- **13 个权限域**在 `src/shared/constants/mcpScopes.ts` 中声明。 +- 审计表：`mcp_tool_audit`（由 `audit.ts` 填充）。 +- 文件：`server.ts`、`index.ts`、`httpTransport.ts`、`audit.ts`、`scopeEnforcement.ts`、 + `runtimeHeartbeat.ts`、`descriptionCompressor.ts`、`schemas/{tools, a2a, audit, index}.ts`、 + `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`， + 以及 `__tests__/` 下的测试。 +- 完整工具目录见 [MCP-SERVER.md](../frameworks/MCP-SERVER.md)。 + +### 4.7 `open-sse/config/` + +服务商注册表（`providerRegistry.ts`、`providerModels.ts`、 +`providerHeaderProfiles.ts`）、按格式的模型注册表（`audioRegistry.ts`、 +`embeddingRegistry.ts`、`imageRegistry.ts`、`moderationRegistry.ts`、 +`musicRegistry.ts`、`rerankRegistry.ts`、`searchRegistry.ts`、`videoRegistry.ts`）、 +身份辅助工具（`codexIdentity.ts`、`codexInstructions.ts`、 +`anthropicHeaders.ts`、`antigravityUpstream.ts`、`antigravityModelAliases.ts`、 +`cliFingerprints.ts`、`toolCloaking.ts`、`defaultThinkingSignature.ts`）、 +凭据辅助工具（`credentialLoader.ts`、`codexClient.ts`）以及云适配器 +（`azureAi.ts`、`bedrock.ts`、`datarobot.ts`、`glmProvider.ts`、 +`maritalk.ts`、`oci.ts`、`petals.ts`、`runway.ts`、`sap.ts`、`watsonx.ts`、 +`ollamaModels.ts`、`errorConfig.ts`、`constants.ts`、`registryUtils.ts`）。 + +### 4.8 `open-sse/utils/` + +流式传输基础和服务商辅助工具：`stream.ts`、`streamHandler.ts`、 +`streamHelpers.ts`、`streamPayloadCollector.ts`、`streamReadiness.ts`、 +`sseHeartbeat.ts`、`proxyFetch.ts`、`proxyDispatcher.ts`、`tlsClient.ts`、 +`networkProxy.ts`、`awsSigV4.ts`、`cacheControlPolicy.ts`、 +`cursorChecksum.ts`、`cursorAgentProtobuf.ts`、`cursorVersionDetector.ts`、 +`comfyuiClient.ts`、`kieTask.ts`、`bypassHandler.ts`、`aiSdkCompat.ts`、 +`thinkTagParser.ts`、`urlSanitize.ts`、`usageTracking.ts`、`requestLogger.ts`、 +`progressTracker.ts`、`cors.ts`、`error.ts`、`logger.ts`、`sleep.ts`、 +`ollamaTransform.ts`。 --- -### 4.6 Utils (`open-sse/utils/`) - -| File | Purpose | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | -| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | -| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | -| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | -| `requestLogger.ts` | Legacy file-based request logging helper kept for compatibility. Current deployments should prefer `APP_LOG_TO_FILE` for application logs and the call log pipeline for persisted request artifacts. | -| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | -| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | - -#### SSE Streaming Pipeline - -```mermaid -flowchart TD - A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] - B --> C["Buffer lines\n(split on newline)"] - C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] - D --> E{"Mode?"} - E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] - E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] - F --> H["hasValuableContent()\nfilter empty chunks"] - G --> H - H -->|"Has content"| I["extractUsage()\ntrack token counts"] - H -->|"Empty"| J["Skip chunk"] - I --> K["formatSSE()\nserialize + clean perf_metrics"] - K --> L["TextEncoder\n(per-stream instance)"] - L --> M["Enqueue to\nclient stream"] - - style A fill:#f9f,stroke:#333 - style M fill:#9f9,stroke:#333 +## 5. `electron/` — 桌面端封装 + ``` +electron/ +├── main.js Electron 主进程 +├── preload.js Preload 桥接（contextIsolation 已启用） +├── types.d.ts +├── package.json electron-builder 配置，版本 3.8.0 +├── README.md +├── assets/ 构建资源（图标、权限声明等） +├── node_modules/ 专用 node_modules（better-sqlite3、electron-updater） +└── dist-electron/ 构建输出（不提交） +``` + +工作空间根目录下五个 npm 脚本：`electron:dev`、`electron:build`、 +`electron:build:{win,mac,linux}`、`electron:smoke:packaged`。自动更新通过 +`electron-updater` 指向 GitHub Release 源实现。 -#### Request Logger Session Structure +--- + +## 6. `bin/` — CLI ``` -logs/ -└── claude_gemini_claude-sonnet_20260208_143045/ - ├── 1_req_client.json ← Raw client request - ├── 2_req_source.json ← After initial conversion - ├── 3_req_openai.json ← OpenAI intermediate format - ├── 4_req_target.json ← Final target format - ├── 5_res_provider.txt ← Provider SSE chunks (streaming) - ├── 5_res_provider.json ← Provider response (non-streaming) - ├── 6_res_openai.txt ← OpenAI intermediate chunks - ├── 7_res_client.txt ← Client-facing SSE chunks - └── 6_error.json ← Error details (if any) +bin/ +├── omniroute.mjs 主 CLI 入口（Node ESM） +├── reset-password.mjs 通过 CLI 重置管理密码 +├── mcp-server.mjs MCP 服务器启动器（stdio） +├── nodeRuntimeSupport.mjs Node 版本守卫 +└── cli/ + ├── program.mjs Commander 程序构建器 + ├── runtime.mjs withRuntime 辅助（优先服务器/回退到 DB） + ├── output.mjs 输出格式化器（json/jsonl/table/csv） + ├── i18n.mjs t() 辅助，带语言包 + ├── api.mjs API fetch 辅助 + ├── data-dir.mjs + ├── encryption.mjs + ├── sqlite.mjs + └── commands/ + ├── registry.mjs 命令注册 + ├── setup.mjs + ├── doctor.mjs + ├── providers.mjs + └── ... 每个命令/组一个文件 ``` +`package.json` → `bin` 中暴露两个二进制文件： + +- `omniroute` → `bin/omniroute.mjs` +- `omniroute-reset-password` → `bin/reset-password.mjs` + +--- + +## 7. `tests/` + +| 目录 | 类型 | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| `tests/unit/` | Node 原生测试运行器的单元测试（1821 个文件，含 `api/`、`auth/`、`authz/` 子目录）| +| `tests/integration/` | 跨模块 + DB 状态测试 | +| `tests/e2e/` | Playwright UI 测试 | +| `tests/protocols-e2e/` | MCP/A2A 协议端到端 | +| `tests/translator/` | 翻译器专用测试 | +| `tests/security/` | 安全回归测试 | +| `tests/load/` | 负载 / 压力测试 | +| `tests/golden-set/` | 翻译器回归参考输出 | +| `tests/helpers/`、`tests/fixtures/`、`tests/manual/`、`tests/scratch_test.mjs` | 支撑 | + +常用命令： + +| 命令 | 运行内容 | +| --------------------------------------------------------- | -------------------------------------------------------------- | +| `npm run test:unit` | `tests/unit/*.test.ts` 全部（Node 测试运行器，并发 10） | +| `npm run test:vitest` | Vitest 套件（MCP、autoCombo、缓存） | +| `npm run test:e2e` | Playwright UI 套件 | +| `npm run test:protocols:e2e` | MCP + A2A 协议端到端 | +| `npm run test:coverage` | 覆盖率门槛（行/语句/函数/分支 ≥ 60%） | +| `node --import tsx/esm --test tests/unit/.test.ts` | 单文件运行 | + --- -### 4.7 Application Layer (`src/`) - -| Directory | Purpose | -| ------------- | ---------------------------------------------------------------------- | -| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | -| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | -| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | -| `src/models/` | Database model definitions | -| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | -| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | -| `src/store/` | Application state management | - -#### Notable API Routes - -| Route | Methods | Purpose | -| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | -| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | -| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | -| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | -| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | -| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | -| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | -| `/api/sessions` | GET | Active session tracking and metrics | -| `/api/rate-limits` | GET | Per-account rate limit status | +## 8. `scripts/` + +按用途分为 6 个子文件夹。 + +- **`scripts/build/`** — `build-next-isolated.mjs`、`prepublish.ts`、 + `prepare-electron-standalone.mjs`、`pack-artifact-policy.ts`、 + `validate-pack-artifact.ts`、`postinstall.mjs`、`postinstallSupport.mjs`、 + `uninstall.mjs`、`bootstrap-env.mjs`、`runtime-env.mjs`、 + `native-binary-compat.mjs`。 +- **`scripts/dev/`** — `run-next.mjs`、`run-next-playwright.mjs`、 + `run-standalone.mjs`、`standalone-server-ws.mjs`、`responses-ws-proxy.mjs`、 + `v1-ws-bridge.mjs`、`smoke-electron-packaged.mjs`、 + `run-playwright-tests.mjs`、`run-ecosystem-tests.mjs`、 + `run-protocol-clients-tests.mjs`、`sync-env.mjs`、`healthcheck.mjs`、 + `system-info.mjs`。 +- **`scripts/check/`** — `check-cycles.mjs`、`check-docs-sync.mjs`、 + `check-docs-counts-sync.mjs`、`check-env-doc-sync.mjs`、 + `check-deprecated-versions.mjs`、`check-route-validation.mjs`、 + `check-t11-any-budget.mjs`、`check-pr-test-policy.mjs`、 + `check-supported-node-runtime.ts`、`test-report-summary.mjs`。 +- **`scripts/docs/`** — `generate-docs-index.mjs`、`gen-provider-reference.ts`。 +- **`scripts/i18n/`** — `generate-multilang.mjs`、`run-visual-qa.mjs`、 + `generate-qa-checklist.mjs`、`apply-priority-overrides.mjs`、 + `validate_translation.py`、`check_translations.py`、`i18n_autotranslate.py`、 + `untranslatable-keys.json`。 +- **`scripts/ad-hoc/`** — `cursor-tap.cjs`、`sync-cursor-models.mjs`、 + `migrate-env.mjs`、`dbsetup.js`。 --- -## 5. Key Design Patterns +## 9. 请求管道（摘要） + +![请求管道（/v1/chat/completions）](../diagrams/exported/request-pipeline.svg) -### 5.1 Hub-and-Spoke Translation +> 来源：[diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd) -All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. +``` +客户端请求 + → /v1/chat/completions (route.ts) + CORS 预检 + Zod 校验（shared/validation/schemas.ts 中的 chatCompletionsSchema） + 认证（extractApiKey + isValidApiKey 或 requireManagementAuth） + 策略引擎（src/server/authz/pipeline.ts） + 安全护栏（PII 脱敏、提示注入、视觉桥接） + → handleChatCore()（open-sse/handlers/chatCore.ts） + 缓存检查（语义缓存 + 读取缓存） + 速率限制（rateLimitManager、accountSemaphore） + Combo 路由（若模型解析为 Combo） + comboResolver → 逐目标循环 → handleSingleModel() + translateRequest()（open-sse/translator/request/*） + getExecutor(providerId).execute()（open-sse/executors/*） + 获取上游 → 通过 accountFallback 重试/退避 + translateResponse()（open-sse/translator/response/*） + SSE 流 或 JSON 响应 + 若为 Responses API：通过 open-sse/transformer/responsesTransformer.ts 的 TransformStream + → 合规审计（src/lib/compliance/） + → 响应到客户端 +``` -### 5.2 Executor Strategy Pattern +### 容灾运行时状态（三种机制） -Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. +| 机制 | 范围 | 位置 | +| -------------- | ------------------ | -------------------------------------------------------------------------------------------------- | +| 服务商熔断器 | 整个服务商 | `src/shared/utils/circuitBreaker.ts`，持久化于 `domain_circuit_breakers` | +| 连接冷却 | 单个账户/Key | `src/sse/services/auth.ts` 中的 `markAccountUnavailable()`；由 `accountFallback.checkFallbackError()` 消费 | +| 模型锁定 | 服务商 + 连接 + 模型| `open-sse/services/accountFallback.ts`，持久化于 `domain_lockout_state` | -### 5.3 Self-Registering Plugin System +参见 [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) 和 [CLAUDE.md](../../CLAUDE.md) 中的专门章节。 -Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. +--- -### 5.4 Account Fallback with Exponential Backoff +## 10. 贡献指南 -When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). +### 添加新服务商 -### 5.5 Combo Model Chains +1. 在 `src/shared/constants/providers.ts` 中注册（加载时 Zod 校验）。 +2. 若需自定义逻辑，在 `open-sse/executors/` 中添加执行器（扩展 `BaseExecutor`）。 +3. 若不使用 OpenAI 格式，在 `open-sse/translator/` 中添加翻译器。 +4. 若基于 OAuth，在 `src/lib/oauth/providers/` 和 `src/lib/oauth/services/` 下添加配置。 +5. 在 `open-sse/config/providerRegistry.ts`（或 `open-sse/config/` 下按格式的注册表）中注册模型。 +6. 在 `tests/unit/` 下编写测试。 -A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. +### 添加新 API 路由 -### 5.6 Stateful Streaming Translation +1. 创建 `src/app/api/your-route/route.ts`。 +2. 遵循模式：CORS → Zod 请求体验证 → 认证 → 处理器委托。 +3. 若是新请求格式：在 `src/shared/validation/schemas.ts` 中添加 Zod Schema。 +4. 仅管理端点：将路径添加到 `src/shared/constants/publicApiRoutes.ts`（公开 API 层拒绝名单）。 +5. 在 `tests/unit/` 下添加测试。 +6. 更新 `docs/reference/API_REFERENCE.md` 和 `docs/openapi.yaml`。 -Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. +### 添加新 DB 模块 -### 5.7 Usage Safety Buffer +1. 创建 `src/lib/db/yourModule.ts`，从 `./core.ts` 导入 `getDbInstance()`。 +2. 导出你领域的 CRUD 函数。 +3. 若需新表：在 `src/lib/db/migrations/` 下添加迁移文件，按序编号，幂等、事务性。 +4. 从 `src/lib/localDb.ts` 重新导出（仅限重新导出 — **无逻辑**）。 +5. 在 `tests/unit/` 下添加测试。 -A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. +### 添加新 MCP 工具 ---- +1. 在 `open-sse/mcp-server/tools/` 下添加工具定义（或扩展 `open-sse/mcp-server/schemas/tools.ts`）。 +2. 在 `src/shared/constants/mcpScopes.ts` 中分配适当的权限域。 +3. 在 `open-sse/mcp-server/server.ts` 中注册该工具。 +4. 在 `open-sse/mcp-server/__tests__/` 下添加测试。 +5. 更新 [MCP-SERVER.md](../frameworks/MCP-SERVER.md)。 -## 6. Supported Formats +### 添加新 A2A 技能 -| Format | Direction | Identifier | -| ----------------------- | --------------- | ------------------ | -| OpenAI Chat Completions | source + target | `openai` | -| OpenAI Responses API | source + target | `openai-responses` | -| Anthropic Claude | source + target | `claude` | -| Google Gemini | source + target | `gemini` | -| Antigravity | source + target | `antigravity` | -| AWS Kiro | target only | `kiro` | -| Cursor | target only | `cursor` | +参见 [A2A-SERVER.md § 添加新技能](../frameworks/A2A-SERVER.md)。技能位于 `src/lib/a2a/skills/`，通过 A2A 任务管理器注册。 --- -## 7. Supported Providers - -| Provider | Auth Method | Executor | Key Notes | -| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | -| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | -| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | -| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | -| OpenAI | API key | Default | Standard Bearer auth | -| Codex | OAuth | Codex | Injects system instructions, manages thinking | -| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | -| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | -| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | -| Qwen | OAuth | Default | Standard auth | -| Qoder | OAuth (Basic + Bearer) | Default | Dual auth header | -| OpenRouter | API key | Default | Standard Bearer auth | -| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | -| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | -| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | +## 11. 约定 + +- **代码风格**：2 空格缩进，双引号，100 字符宽度，强制分号， + `es5` 尾逗号 — 由 Prettier 通过 `lint-staged` 强制执行。 +- **导入**：外部 → 内部（`@/`、`@omniroute/open-sse`）→ 相对路径。 +- **命名**：文件 `camelCase` 或 `kebab-case`，组件 `PascalCase`， + 常量 `UPPER_SNAKE`。 +- **ESLint**：`no-eval`、`no-implied-eval`、`no-new-func` = 全局 `error`； + `no-explicit-any` = `open-sse/` 和 `tests/` 中 `warn`，其他位置 `error`。 +- **TypeScript**：`strict: false`（历史遗留）。跨模块边界优先显式类型而非类型推断。 +- **数据库**：切勿在路由或处理器中直接写 SQL — 始终通过 `src/lib/db/` 模块。切勿向 `src/lib/localDb.ts` 添加逻辑。 +- **错误处理**：try/catch 使用具体错误类型，以 pino 上下文记录日志。切勿在 SSE 流中静默吞噬错误；使用 abort signal 进行清理。 +- **安全**：切勿使用 `eval()` / `new Function()` / 隐式 eval。所有输入以 Zod 校验。凭据使用 AES-256-GCM 静态加密。保持 `src/shared/constants/upstreamHeaders.ts` 拒绝名单与清洗/校验层对齐。 +- **提交**：Conventional Commits — `feat(scope): subject`。允许的 scope：`db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`。 +- **分支**：前缀 `feat/`、`fix/`、`refactor/`、`docs/`、`test/`、 + `chore/`。切勿直接提交到 `main`。 +- **Husky**：pre-commit 运行 `lint-staged` + `check:docs-sync` + `check:any-budget:t11`；pre-push 运行 `check:any-budget:t11` + `check:tracked-artifacts`（快速门禁；不含 `test:unit`）。 --- -## 8. Data Flow Summary - -### Streaming Request - -```mermaid -flowchart LR - A["Client"] --> B["detectFormat()"] - B --> C["translateRequest()\nsource → OpenAI → target"] - C --> D["Executor\nbuildUrl + buildHeaders"] - D --> E["fetch(providerURL)"] - E --> F["createSSEStream()\nTRANSLATE mode"] - F --> G["parseSSELine()"] - G --> H["translateResponse()\ntarget → OpenAI → source"] - H --> I["extractUsage()\n+ addBuffer"] - I --> J["formatSSE()"] - J --> K["Client receives\ntranslated SSE"] - K --> L["logUsage()\nsaveRequestUsage()"] -``` - -### Non-Streaming Request +## 12. 硬规则（来自 CLAUDE.md） -```mermaid -flowchart LR - A["Client"] --> B["detectFormat()"] - B --> C["translateRequest()\nsource → OpenAI → target"] - C --> D["Executor.execute()"] - D --> E["translateResponse()\ntarget → OpenAI → source"] - E --> F["Return JSON\nresponse"] -``` +1. 切勿提交机密或凭据。 +2. 切勿向 `src/lib/localDb.ts` 添加逻辑。 +3. 切勿使用 `eval()` / `new Function()` / 隐式 eval。 +4. 切勿直接提交到 `main`。 +5. 切勿在路由中直接写 SQL — 始终通过 `src/lib/db/` 模块。 +6. 切勿在 SSE 流中静默吞噬错误。 +7. 始终以 Zod Schema 校验输入。 +8. 修改生产代码时始终包含测试。 +9. 覆盖率必须保持 ≥ 60%（语句、行、函数、分支）。 -### Bypass Flow (Claude CLI) +--- -```mermaid -flowchart LR - A["Claude CLI request"] --> B{"Match bypass\npattern?"} - B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] - B -->|"No match"| D["Normal flow"] - C --> E["Translate to\nsource format"] - E --> F["Return without\ncalling provider"] -``` +## 13. 参见 + +- [ARCHITECTURE.md](./ARCHITECTURE.md) — 高层架构及模块职责。 +- [API_REFERENCE.md](../reference/API_REFERENCE.md) — 公开 + 管理 API 参考。 +- [FEATURES.md](../guides/FEATURES.md) — 功能矩阵及版本亮点。 +- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — 熔断器、冷却、锁定深入解析。 +- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — Auto Combo 评分与策略。 +- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — 完整 MCP 工具目录 + 传输。 +- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — A2A 协议技能与发现。 +- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — RTK + Caveman 压缩。 +- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — CLI 集成。 +- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md)（如果存在）、[DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md)、[FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md)、[VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md)、[TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md)、[PWA_GUIDE.md](../guides/PWA_GUIDE.md) — 部署目标。 +- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — 常见运维问题。 +- [CONTRIBUTING.md](../../CONTRIBUTING.md) — 贡献者工作流。 +- [CLAUDE.md](../../CLAUDE.md) — 面向 Claude Code 的仓库规则（上述约定的权威来源）。 +- [AGENTS.md](../../AGENTS.md) — 面向 Agent 的深层架构参考。 diff --git a/docs/i18n/zh-CN/docs/cloudflare-zero-trust-guide.md b/docs/i18n/zh-CN/docs/cloudflare-zero-trust-guide.md index 34540894a652..29ea35a50581 100644 --- a/docs/i18n/zh-CN/docs/cloudflare-zero-trust-guide.md +++ b/docs/i18n/zh-CN/docs/cloudflare-zero-trust-guide.md @@ -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**. - -> **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. + - 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**。 + +> **效果：** 在 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。 diff --git a/docs/i18n/zh-CN/docs/features/context-relay.md b/docs/i18n/zh-CN/docs/features/context-relay.md index b8098143bc5e..ac6896570f69 100644 --- a/docs/i18n/zh-CN/docs/features/context-relay.md +++ b/docs/i18n/zh-CN/docs/features/context-relay.md @@ -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 `` system -message so the next account can continue with the correct local context. +在注入时，OmniRoute 将该载荷转换为 `` 系统消息，使下一个账户能够在正确的本地上下文中继续。 ## 配置 -`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` 设置得足够早，为后台摘要请求留出空间 +- 将此功能视为连续性辅助工具，而非持久记忆的替代品 diff --git a/docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md b/docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md index a3b8e073d7bb..11cc354481db 100644 --- a/docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md +++ b/docs/i18n/zh-CN/docs/frameworks/A2A-SERVER.md @@ -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 +## 可用技能 + +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)。 + +--- + +## 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/.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-.test.ts`。覆盖正常路径和错误路径。 + +5. 在本文档的`可用技能`表格中**记录**新技能。 + +--- + +## 任务 TTL -| 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. | +任务在 `ttlMinutes`（默认 5 分钟）后过期——可在 `src/lib/a2a/taskManager.ts:82` 的 `A2ATaskManager` 构造函数中配置。如需自定义，可复刻 `A2ATaskManager` 的实例化并传入不同值（例如 `new A2ATaskManager(15)` 设置 15 分钟 TTL）。后台定时器每 60 秒清理一次过期任务。 --- -## Task Lifecycle +## 任务生命周期 ``` 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) diff --git a/docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md b/docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md index c8f424fab080..9508bf830411 100644 --- a/docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md +++ b/docs/i18n/zh-CN/docs/frameworks/MCP-SERVER.md @@ -1,87 +1,403 @@ -# OmniRoute MCP Server Documentation (中文 (简体)) +--- +title: "OmniRoute MCP Server Documentation" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- -🌐 **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) +# 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`。 + +![MCP tool inventory (94 tools by category)](../diagrams/exported/mcp-tools-94.svg) -> Model Context Protocol server with 16 intelligent tools +> 来源：[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 传输（端口 20130） +omniroute --dev # MCP 自动在 /mcp 端点启动 +``` + +## 传输 + +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 `，即可连接。这是通过隧道、反向代理或公网主机名访问远程 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)。 + +--- + +## 核心工具（8）— 阶段 1 + +| 工具 | 权限域 | 描述 | +| :-------------------------------- | :---------------------- | :----------------------------------------------------------- | +| `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` | 完整模型目录，包含能力、状态、定价 | + +## 阶段 1 — 搜索 + +| 工具 | 权限域 | 描述 | +| :--------------------- | :----------------- | :------------------------------------------------------------------------------------ | +| `omniroute_web_search` | `execute:search` | 通过 OmniRoute 搜索网关进行 Web 搜索（Serper/Brave/Perplexity/Exa/Tavily/Google PSE/Linkup/SearchAPI/SearXNG），支持容灾 | + +## 高级工具（11）— 阶段 2 + +| 工具 | 权限域 | 描述 | +| :----------------------------------- | :------------------------------------- | :------------------------------------------------------------------- | +| `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` | + +## 缓存工具（2） + +| 工具 | 权限域 | 描述 | +| :------------------------ | :-------------- | :--------------------------------------- | +| `omniroute_cache_stats` | `read:cache` | 语义缓存、提示缓存和幂等性统计 | +| `omniroute_cache_flush` | `write:cache` | 全局或按签名/模型刷新缓存 | + +## 压缩工具（5） + +| 工具 | 权限域 | 描述 | +| :------------------------------------ | :-------------------- | :--------------------------------------------------------------------------------------------------------- | +| `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 和引擎分组的分析数据 | + +`omniroute_compression_status` 将 MCP 描述压缩数据单独报告在 `analytics.mcpDescriptionCompression` 下。这些值是 MCP 可列表描述（`tools`、`prompts`、`resources` 和 `resourceTemplates`）的元数据大小估算；不是服务商用量记录，标记为 `source: "mcp_metadata_estimate"`。 + +### 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:` | +| `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 -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint +# 从目录中移除两个工具 +MCP_TOOL_DENY="omniroute_get_health,omniroute_list_combos" omniroute --mcp + +# 仅宣布路由 + 配额工具（白名单模式） +MCP_TOOL_ALLOW="omniroute_route_request,omniroute_check_quota" omniroute --mcp ``` -## IDE Configuration +**已过滤工具的移除方式：** 注册始终成功；被配置淘汰的工具会在 MCP SDK 句柄上执行 `.disable()`，因此它不会出现在 `tools/list` 中，但连接保持完整（干净启用/禁用，无需重新注册）。配置解析器为 `readMcpToolProfileFromEnv(process.env)`，当两个变量均为空时返回 `null`（无过滤）。 -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. +`reduceToolManifest` 背后的更丰富 `ToolProfile` 结构也支持权限域交集过滤（`allowScopes`，含 `read:*` 风格的通配符匹配）和确定性 `maxTools` 上限，但这两个参数在注册时需要完整清单，目前**不**通过环境变量暴露（`tools/list` 级别的 hook 是后续跟进项）。`estimateManifestTokens()` 可用于比较精简前后的清单 Token 成本。 --- -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo 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 | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| 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 | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | +## 运行时心跳 + +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:`，附带缺失的权限域列表 + +使用仪表盘或 `/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） | diff --git a/docs/i18n/zh-CN/docs/guides/FEATURES.md b/docs/i18n/zh-CN/docs/guides/FEATURES.md index 90a8d6b1245f..29635bf8a5d9 100644 --- a/docs/i18n/zh-CN/docs/guides/FEATURES.md +++ b/docs/i18n/zh-CN/docs/guides/FEATURES.md @@ -1,269 +1,328 @@ -# OmniRoute — Dashboard Features Gallery (中文 (简体)) +--- +title: "OmniRoute — 控制台功能画廊" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- + +# OmniRoute — 控制台功能画廊 -🌐 **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) +🌐 **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"`。 -![Providers Dashboard](screenshots/01-providers.png) +![服务商控制台](../../screenshots/01-providers.png) --- -## 🎨 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 步骤的运行时执行/容灾顺序 -![Combos Dashboard](screenshots/02-combos.png) +![Combo 控制台](../../screenshots/02-combos.png) --- -## 📊 Analytics +## 📊 分析 -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. +全面的用量分析，包括 Token 消耗、费用估算、活跃度热力图、周分布图和按服务商的细分视图。 -![Analytics Dashboard](screenshots/03-analytics.png) +![分析控制台](../../screenshots/03-analytics.png) --- -## 🏥 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 目标健康。 -![Health Dashboard](screenshots/04-health.png) +![健康控制台](../../screenshots/04-health.png) --- -## 🔧 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**（实时流监控）。 -![Translator Playground](screenshots/05-translator.png) +![翻译器 Playground](../../screenshots/05-translator.png) --- -## 🎮 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 的后台模式降级 -![Settings Dashboard](screenshots/06-settings.png) +![设置控制台](../../screenshots/06-settings.png) --- -## 🔧 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 Tools Dashboard](screenshots/07-cli-tools.png) +![CLI 工具控制台](../../screenshots/07-cli-tools.png) --- -## 🤖 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 在后台生成结构化的交接摘要。后续请求切换到其他账户后，摘要以系统消息形式注入，使新账户以完整上下文继续服务。 + +支持 Combo 级别或全局配置： + +- **交接阈值** — 触发摘要生成的配额使用百分比（默认 85%） +- **最近消息摘要数量限制** — 压缩多少最近的历史记录 +- **摘要模型** — 可选，用于生成交接摘要的覆盖模型 + +目前支持 Codex 账户轮换。详见 [Context Relay 文档](../architecture/ARCHITECTURE.md)。 + +--- + +## 🗜️ 提示压缩 _(v3.7.9+)_ -Configurable via combo-level or global settings: +Context & Cache 现在为 Caveman、RTK 和压缩 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 +- **Caveman** — 语言感知规则包、预览、输出模式控制和用量分析 +- **RTK** — 命令感知压缩，适用 shell、git、测试、构建、包管理、Docker、基础设施、JSON 和堆栈跟踪输出 +- **压缩 Combo** — 命名管道，如 `rtk -> caveman`，可分配给路由 Combo；默认级联压缩在两个引擎同时生效时达到 **~89%** 平均节省率和 **78–95%** 合格上下文节省率 +- **原始输出恢复** — 可选 RTK 脱敏原始输出指针，用于调试压缩失败 -Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md). +详见 [压缩指南](../compression/COMPRESSION_GUIDE.md)、[RTK 压缩](../compression/RTK_COMPRESSION.md) 和 [压缩引擎](../compression/COMPRESSION_ENGINES.md)。 --- -## 🛡️ Proxy Hardening _(v3.5.5+)_ +## 🛡️ 代理加固 _(v3.5.5+)_ -Comprehensive proxy configuration enforcement across the entire request pipeline: +全请求链路的代理配置强制执行： -- **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 +- **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 --- -## 📧 Email Privacy Masking _(v3.5.6+)_ +## 📧 邮箱隐私脱敏 _(v3.5.6+)_ -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). +OAuth 账户邮箱默认脱敏显示（例如 `di*****@g****.com`），防止截图或录屏时意外暴露。使用 设置 → 外观 → 账户邮箱可见性 可在服务商、Combo、日志、配额和 Playground 页中全局显示或隐藏完整邮箱。 --- -## 👁️ 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 +- **实时搜索/过滤栏** — 快速查找特定模型 +- **单个模型可见性切换**（👁 图标）— 隐藏的模型置灰并从 `/v1/models` 目录中排除 +- **活跃数 Badge**（`N/M active`）— 一目了然地显示启用模型数 vs 总数 --- -## 🔧 OAuth Env Repair _(v3.6.1+)_ +## 🔧 OAuth 环境修复 _(v3.6.1+)_ -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: +OAuth 服务商的一键"环境修复"操作，恢复缺失的环境变量并修复损坏的认证状态。入口：`控制台 → 服务商 → [OAuth 服务商] → 环境修复`。自动检测并修复： -- Missing OAuth client credentials -- Corrupted env file entries -- Backup path sanitization +- 缺失的 OAuth 客户端凭据 +- 损坏的 env 文件条目 +- 备份路径清理 --- -## 🗑️ Uninstall / Full Uninstall _(v3.6.2+)_ +## 🗑️ 卸载 / 完全卸载 _(v3.6.2+)_ -Clean removal scripts for all installation methods: +面向所有安装方式的清理卸载脚本： -| 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**. | +| 命令 | 操作 | +| ------------------------ | ------------------------------------------------------------------- | +| `npm run uninstall` | 移除系统应用，但**保留数据库和配置**在 `~/.omniroute`。 | +| `npm run uninstall:full` | 移除应用，并永久**清除所有配置、密钥和数据库**。 | --- -## 🖼️ Media _(v2.0.3+)_ +## 🖼️ 媒体 _(v2.0.3+)_ -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. +从控制台生成图像、视频和音乐。支持 OpenAI、xAI、Together、Hyperbolic、SD WebUI、ComfyUI、AnimateDiff、Stable Audio Open 和 MusicGen。 --- -## 📝 Request Logs +## 📝 请求日志 -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. +实时请求日志，支持按服务商、模型、账户和 API Key 筛选。显示状态码、Token 用量、延迟和响应详情。 -![Usage Logs](screenshots/08-usage.png) +![用量日志](../../screenshots/08-usage.png) --- -## 🌐 API Endpoint +## 🌐 API 端点 -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access. +统一 API 端点及其能力概览：Chat Completions、Responses API、Embeddings、Image Generation、Reranking、Audio Transcription、Text-to-Speech、Moderations 和已注册的 API Key。支持 Cloudflare Quick Tunnel、Tailscale Funnel、ngrok Tunnel 和云代理，实现远程访问。 -![Endpoint Dashboard](screenshots/09-endpoint.png) +![端点控制台](../../screenshots/09-endpoint.png) --- -## 🔑 API Key Management +## 🔑 API Key 管理 -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 Key。每个 Key 可限制到特定模型/服务商，支持完全访问或只读权限。可视化密钥管理，附带用量追踪。 --- -## 📋 Audit Log +## 📋 审计日志 -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. +管理操作追踪，支持按操作类型、执行人、目标、IP 地址和时间戳筛选。完整的安全事件历史。 --- -## 🖥️ Desktop Application +## 🖥️ 桌面应用 -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. +面向 Windows、macOS 和 Linux 的原生 Electron 桌面应用。以独立应用程序形式运行 OmniRoute，集成系统托盘、离线支持、自动更新和一键安装。 -Key features: +关键功能： -- Server readiness polling (no blank screen on cold start) -- System tray with port management +- 服务器就绪轮询（冷启动不白屏） +- 带端口管理的系统托盘 - Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) -- **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` 触发。 diff --git a/docs/i18n/zh-CN/docs/guides/I18N.md b/docs/i18n/zh-CN/docs/guides/I18N.md index d613d8db7241..c3dfddf0bb41 100644 --- a/docs/i18n/zh-CN/docs/guides/I18N.md +++ b/docs/i18n/zh-CN/docs/guides/I18N.md @@ -1,90 +1,143 @@ -# i18n — Internationalization Guide (中文 (简体)) +--- +title: "i18n — 国际化指南" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- -🌐 **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) +# i18n — 国际化指南 ---- +OmniRoute 支持 **42 种语言**，提供完整的控制台 UI 翻译、文档翻译，以及阿拉伯语和希伯来语的 RTL 支持。 + +🌐 **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 -OmniRoute supports **30 languages** with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew. +# 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` 镜像强制执行的格式一致。 -## Quick Reference +### 旧版脚本（已弃用） -| Task | Command | -| ---------------------- | --------------------------------------------------------------------------------------- | -| Generate translations | `node scripts/i18n/generate-multilang.mjs messages` | -| Translate docs (LLM) | `python3 scripts/i18n_autotranslate.py --api-url --api-key --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` | +较旧的 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 - -### 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")` - -### 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` | - -## Adding a New Language - -### 1. Register the Locale - -Edit `src/i18n/config.ts`: +![基于哈希的增量 i18n 管道](../../diagrams/exported/i18n-flow.svg) + +> 源文件：[diagrams/i18n-flow.mmd](../../diagrams/i18n-flow.mmd) + +### 唯一数据源 + +- **UI 字符串**：`src/i18n/messages/en.json`（英文源，约 2800 个 Key） +- **语言/地区文件**：`src/i18n/messages/{locale}.json`（30 种翻译） +- **框架**：`next-intl`，基于 Cookie 的语言/地区解析 +- **配置**：`src/i18n/config.ts` — 定义全部 30 个语言/地区、语言名称、旗帜 + +### 运行时流程 + +1. 用户选择语言 → 设置 `NEXT_LOCALE` Cookie +2. `src/i18n/request.ts` 解析语言/地区：Cookie → `Accept-Language` 头 → 回退 `en` +3. 动态 import 加载 `messages/{locale}.json` +4. 组件使用 `useTranslations("namespace")` 和 `t("key")` + +### 支持的语言/地区 + +| 代码 | 语言 | 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` | + +## 添加新语言 + +### 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 +- **文本保���**：翻译前脱敏代码块（` ``` `）、内联代码（`` ` ``）、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:** +**功能特性：** + +- 扫描 `docs/i18n/` 中的 Markdown 文件，定位英文段落 +- 跳过代码块、表格和已翻译内容 +- 向 LLM 发送段落及技术翻译系统提示 +- 支持全部 42 种语言 + +## CLI i18n + +`omniroute` CLI 拥有独立的 i18n 层，与 Next.js 控制台分离。 + +### 工作原理 -- 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 +- CLI 命令中的每个用户可见字符串都通过 `bin/cli/i18n.mjs` 中的 `t("module.key", vars)` 处理。 +- 翻译目录是 `bin/cli/locales/` 中的 JSON 文件 — 预置 42 个语言/地区。 +- 缺失 Key 时回退到 `en`，因此部分翻译也是有效的。 +- 可用语言/地区的唯一数据源是 `config/i18n.json`（与控制台共享）。 -## Validation & QA +### 语言/地区选择 + +检测顺序（优先匹配）： + +| 优先级 | 来源 | 示例 | +| ------ | ------------------------ | -------------------------------------- | +| 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 ''` 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 ''` +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 ` -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 ` +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 注意事项 + +- 阿拉伯语（`ar`）和希伯来语（`he`）是 RTL 语言/地区 +- 避免硬编码 `left`/`right` CSS — 使用 `start`/`end` 逻辑属性 +- 视觉 QA 通过 `run-visual-qa.mjs` 捕获 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` +## 已知问题与历史 -## Known Issues & History +### `in.json` → `hi.json` 修复 -### `in.json` → `hi.json` Fix +生成器最初对印地语使用 `code: "in"`（已弃用的 Google Translate 代码），而非正确的 ISO 639-1 `hi`。这导致创建了 `hi.json` 的孤立副本 `in.json`。通过将 `generate-multilang.mjs` 中的 `code: "in"` 改为 `code: "hi"` 并删除孤立文件完成修复。 -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. +> ⚠️ **审计（2026-05-13）：** `docs/i18n/in/` 目录在磁盘上仍然存在（`hi/` 的完整副本）。翻译生成器不再向其写入，但历史目录树未被清理。确认无外部链接引用旧路径后，可使用 `rm -rf docs/i18n/in/` 安全删除。 -### `docs/i18n/README.md` Is Auto-Generated +### `docs/i18n/README.md` 是自动生成的 -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` 文件由 `generate-multilang.mjs docs` 完全重新生成。任何手动编辑都会丢失。如需持久化的手写文档，请使用 `docs/guides/I18N.md`（本文件）。 -### External Untranslatable Keys List +### 外部不可翻译 Key 列表 -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. +`untranslatable-keys.json` 允许清单从 `validate_translation.py` 中的内联 Python set 迁移到外部 JSON 文件，以便维护。校验器在运行时加载该清单。 -### `generate-multilang.mjs` Hindi Code Fix +### `generate-multilang.mjs` 印地语代码修复 -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. +生成器最初对印地语使用 `code: "in"`（已弃用的 Google Translate 代码），而非正确的 ISO 639-1 `hi`。该问题由上版本 `952b0b22c`（作者 `diegosouzapw`）引入。通过将 `LOCALE_SPECS` 数组中的 `code: "in"` 修改为 `code: "hi"` 并删除孤立的 `in.json` 文件完成修复。 -### `validate_translation.py` Ignored Count Output +### `validate_translation.py` 被忽略 Key 的计数输出 -The `quick` check now displays the count of ignored keys from `untranslatable-keys.json`: +`quick` 检查现在显示来自 `untranslatable-keys.json` 的被忽略 Key 数： ``` Missing: 0 Untranslated: 0 -Ignored (UNTRANSLATABLE_KEYS): 236 +Ignored (UNTRANSLATABLE_KEYS): <各版本数量不同> ``` diff --git a/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md b/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md index 476aa0bd9c52..f0cac7dbbaa5 100644 --- a/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md +++ b/docs/i18n/zh-CN/docs/guides/TROUBLESHOOTING.md @@ -1,72 +1,102 @@ -# Troubleshooting (中文 (简体)) +--- +title: "故障排除" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- + +# 故障排除 + +> **致用户**：想快速解决问题？请参阅下方的[快速参考](#快速参考)。 + +🌐 **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) -🌐 **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) +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 | +--- + +## 快速修复 + +| 问题 | 解决方案 | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| 首次登录无法使用 | 在 `.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 Compatibility +## Node.js 兼容性 -### 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" -**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//.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 +## 代理问题 -### Provider validation shows "fetch failed" +### 服务商验证提示 "fetch failed" + +**原因：** API 密钥验证端点（`POST /api/providers/validate`）之前绕过了代理配置，导致在需要代理路由的环境中验证失败。 + +**修复（v3.5.5+）：** 已修复。服务商验证现在通过 `runWithProxyContext` 路由，自动遵循服务商级别和全局代理设置。 -**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing. +### Token 健康检查报错 "fetch failed" -**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically. +**原因：** 后台 OAuth Token 刷新未解析每个连接对应的代理配置。 -### Token health check fails with "fetch failed" +**修复（v3.5.5+）：** Token 健康检查调度器现在在尝试刷新之前会按连接解析代理配置。请更新至 v3.5.5+。 -**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection. +### SOCKS5 代理返回 "invalid onRequestStart method" -**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+. +**原因：** 在 Node.js 22 上，undici@8 调度器与 Node 内置的 `fetch()` 实现不兼容。 -### SOCKS5 proxy returns "invalid onRequestStart method" +**修复（v3.5.5+）：** OmniRoute 现在在代理调度器激活时使用 undici 自身的 `fetch()` 函数，确保行为一致。请更新至 v3.5.5+。 -**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation. +### WSL 下的 MITM 代理：Windows 主机上的桌面应用未被拦截 -**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+. +**原因：** 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. +**原因：** 服务商配额耗尽。 + +**修复：** + +1. 检查仪表盘配额追踪器 +2. 使用包含容灾层级的 Combo +3. 切换到更便宜/免费的层级 + +### 速率限制 -**Fix:** +**原因：** 订阅配额耗尽。 -1. Check dashboard quota tracker -2. Use a combo with fallback tiers -3. Switch to cheaper/free tier +**修复：** -### Rate Limiting +- 添加容灾：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- 使用 GLM/MiniMax 作为廉价备用 -**Cause:** Subscription quota exhausted. +### OAuth Token 过期 -**Fix:** +OmniRoute 会自动刷新 Token。如果问题持续： -- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Use GLM/MiniMax as cheap backup +1. 仪表盘 → 服务商 → 重新连接 +2. 删除并重新添加该服务商连接 -### OAuth Token Expired +### Kiro 多账号：第二个账号使第一个失效 -OmniRoute auto-refreshes tokens. If issues persist: +**原因：** Kiro 后端强制每个 OIDC 客户端注册仅允许一个活跃会话。当两个账号共享同一个注册客户端（v3.8.0 之前导入的连接）时，刷新一个账号的 Token 会使另一个账号的 refresh token 失效。 -1. Dashboard → Provider → Reconnect -2. Delete and re-add the provider connection +**修复（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 +### 运行时存储 + +- 主状态：`${DATA_DIR}/storage.sqlite`（服务商、Combo、别名、密钥、设置） +- 用量：`storage.sqlite` 中的 SQLite 表（`usage_history`、`call_logs`、`proxy_logs`）+ 可选的 `${DATA_DIR}/call_logs/` +- 应用日志：`/logs/...`（当 `APP_LOG_TO_FILE=true` 时） +- 调用日志产物：当调用日志流水线启用时为 `${DATA_DIR}/call_logs/YYYY-MM-DD/...` -- 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: `/logs/...` (when `APP_LOG_TO_FILE=true`) -- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled +请求日志页面的 **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 或代理流水线，可以忽略本节。 + +--- + +## 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=`（以及任何与该 bridge 通信的客户端） +3. 重启 OmniRoute + +### Responses API：后台模式降级为同步 + +**症状：** + +- 日志警告：`background mode degraded to synchronous` +- `background: true` 的请求返回了普通同步响应，而非后台任务句柄 + +**原因：** v3.8.0 有意将 Responses API 上的 `background: true` 降级为同步执行，同时发出警告。完整的异步后台执行是未来的交付内容。 + +**修复：** + +- 调整客户端调用时不带 `background`，或 +- 等待后续版本提供完整的异步后台模式（关注更新日志） --- -## Still Stuck? +## 仍然卡住了？ - **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** 调试格式问题 diff --git a/docs/i18n/zh-CN/docs/guides/UNINSTALL.md b/docs/i18n/zh-CN/docs/guides/UNINSTALL.md index 387fc12498a3..c5b48661c05b 100644 --- a/docs/i18n/zh-CN/docs/guides/UNINSTALL.md +++ b/docs/i18n/zh-CN/docs/guides/UNINSTALL.md @@ -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) -This guide covers how to cleanly remove OmniRoute from your system. +本指南介绍如何从系统中彻底移除 OmniRoute。 --- -## Quick Uninstall (v3.6.2+) +## 快速卸载（v3.6.2+） -OmniRoute provides two built-in scripts for clean removal: +OmniRoute 提供两个内置脚本用于干净移除： -### 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 | - -### 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) | +| 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` 环境变量 | + +### 数据目录中的文件 + +| 文件/目录 | 说明 | +| --------------------- | -------------------------------------------------- | +| `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 diff --git a/docs/i18n/zh-CN/docs/guides/USER_GUIDE.md b/docs/i18n/zh-CN/docs/guides/USER_GUIDE.md index c4c7fd6c83d9..b5f1f9b09e40 100644 --- a/docs/i18n/zh-CN/docs/guides/USER_GUIDE.md +++ b/docs/i18n/zh-CN/docs/guides/USER_GUIDE.md @@ -1,116 +1,126 @@ -# User Guide (中文 (简体)) - -🌐 **Languages:** 🇺🇸 [English](../../../../docs/USER_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/USER_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/USER_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/USER_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/USER_GUIDE.md) · 🇩🇰 [da](../../da/docs/USER_GUIDE.md) · 🇩🇪 [de](../../de/docs/USER_GUIDE.md) · 🇪🇸 [es](../../es/docs/USER_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/USER_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/USER_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/USER_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/USER_GUIDE.md) · 🇮🇱 [he](../../he/docs/USER_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/USER_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/USER_GUIDE.md) · 🇮🇩 [id](../../id/docs/USER_GUIDE.md) · 🇮🇹 [it](../../it/docs/USER_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/USER_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/USER_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/USER_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/USER_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/USER_GUIDE.md) · 🇳🇴 [no](../../no/docs/USER_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/USER_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/USER_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/USER_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/USER_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/USER_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/USER_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/USER_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/USER_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/USER_GUIDE.md) · 🇮🇳 [te](../../te/docs/USER_GUIDE.md) · 🇹🇭 [th](../../th/docs/USER_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/USER_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/USER_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/USER_GUIDE.md) - --- - -Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. - +title: "用户指南" +version: 3.8.40 +lastUpdated: 2026-06-28 --- -## Table of Contents +# 用户指南 -- [Pricing at a Glance](#-pricing-at-a-glance) -- [Use Cases](#-use-cases) -- [Provider Setup](#-provider-setup) -- [CLI Integration](#-cli-integration) -- [Deployment](#-deployment) -- [Available Models](#-available-models) -- [Advanced Features](#-advanced-features) +配置服务商、创建 Combo、集成 CLI 工具和部署 OmniRoute 的完整指南。 --- -## 💰 Pricing at a Glance - -| Tier | Provider | Cost | Quota Reset | Best For | -| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | -| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | -| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | -| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | -| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | -| | Groq | Pay per use | None | Ultra-fast inference | -| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | -| | Mistral | Pay per use | None | EU-hosted models | -| | Perplexity | Pay per use | None | Search-augmented | -| | Together AI | Pay per use | None | Open-source models | -| | Fireworks AI | Pay per use | None | Fast FLUX images | -| | Cerebras | Pay per use | None | Wafer-scale speed | -| | Cohere | Pay per use | None | Command R+ RAG | -| | NVIDIA NIM | Pay per use | None | Enterprise models | -| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | -| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | -| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | -| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free | -| | Qwen | $0 | Unlimited | 3 models free | -| | Kiro | $0 | Unlimited | Claude free | +## 目录 + +- [定价概览](#-pricing-at-a-glance) +- [典型场景](#-use-cases) +- [服务商配置](#-provider-setup) +- [CLI 集成](#-cli-integration) +- [部署](#-deployment) +- [可用模型](#-available-models) +- [高级功能](#-advanced-features) +- [自动路由（零配置）](#-auto-routing-zero-config) +- [MCP 与 A2A 集成](#-mcp--a2a-integration) +- [技能系统](#-skills-system) +- [记忆系统](#-memory-system) +- [Webhook](#-webhooks) +- [云代理](#-cloud-agents) +- [编程式管理](#-programmatic-management) +- [内置 CLI](#-internal-cli) +- [桌面应用 (Electron)](#-desktop-application-electron) +--- + +## 💰 定价概览 + +| 级别 | 服务商 | 费用 | 配额重置 | 最佳用途 | +| ------------------------ | ----------------- | ----------- | ------------- | --------------------- | +| **💳 订阅制** | Claude Code (Pro) | $20/月 | 5 小时 + 每周 | 已有订阅 | +| | Codex (Plus/Pro) | $20-200/月 | 5 小时 + 每周 | OpenAI 用户 | +| | GitHub Copilot | $10-19/月 | 每月 | GitHub 用户 | +| **🔑 API Key** | DeepSeek | 按量付费 | 无 | 低成本推理 | +| | Groq | 按量付费 | 无 | 超高速推理 | +| | xAI (Grok) | 按量付费 | 无 | Grok 4 推理 | +| | Mistral | 按量付费 | 无 | 欧盟托管模型 | +| | Perplexity | 按量付费 | 无 | 搜索增强 | +| | Together AI | 按量付费 | 无 | 开源模型 | +| | Fireworks AI | 按量付费 | 无 | 快速 FLUX 图像生成 | +| | Cerebras | 按量付费 | 无 | 晶圆级速度 | +| | Cohere | 按量付费 | 无 | Command R+ RAG | +| | NVIDIA NIM | 按量付费 | 无 | 企业级模型 | +| **💰 经济型** | GLM-4.7 | $0.6/1M | 每日 10:00 | 预算备用 | +| | MiniMax M2.1 | $0.2/1M | 5 小时滑动窗口 | 最便宜选项 | +| | Kimi K2 | $9/月 固定 | 10M Token/月 | 费用可预测 | +| **🆓 免费** | Qoder | $0 | 无限制 | 8 个模型免费 | +| | Qwen | $0 | 无限制 | 3 个模型免费 | +| | Kiro | $0 | ~50 积分/月 | Claude 免费 | --- -## 🎯 Use Cases +## 🎯 典型场景 -### Case 1: "I have Claude Pro subscription" +### 场景 1：「我已订阅 Claude Pro」 -**Problem:** Quota expires unused, rate limits during heavy coding +**问题：** 配额过期浪费，高强度编码时触发速率限制 ``` Combo: "maximize-claude" - 1. cc/claude-opus-4-7 (use subscription fully) - 2. glm/glm-4.7 (cheap backup when quota out) - 3. if/kimi-k2-thinking (free emergency fallback) + 1. cc/claude-opus-4-7 (充分利用订阅) + 2. glm/glm-4.7 (配额耗尽时的经济备用) + 3. if/kimi-k2 (免费应急容灾) -Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total -vs. $20 + hitting limits = frustration +每月费用：$20（订阅）+ ~$5（备用）= 共 $25 +对比 $20 + 触发限制 = 挫败感 ``` -### Case 2: "I want zero cost" +### 场景 2：「我想零成本使用」 -**Problem:** Can't afford subscriptions, need reliable AI coding +**问题：** 无法承担订阅费用，需要可靠的 AI 编程辅助 ``` Combo: "free-forever" - 1. if/kimi-k2-thinking (unlimited free) - 2. qw/qwen3-coder-plus (unlimited free) + 1. if/kimi-k2 (无限免费) + 2. qw/qwen3-coder-plus (无限免费) -Monthly cost: $0 -Quality: Production-ready models +每月费用：$0 +质量：生产级模型 ``` -### Case 3: "I need 24/7 coding, no interruptions" +### 场景 3：「我需要 7×24 编程，不能中断」 -**Problem:** Deadlines, can't afford downtime +**问题：** 赶截止日期，不能容忍停机 ``` Combo: "always-on" - 1. cc/claude-opus-4-7 (best quality) - 2. cx/gpt-5.2-codex (second subscription) - 3. glm/glm-4.7 (cheap, resets daily) - 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) - 5. if/kimi-k2-thinking (free unlimited) - -Result: 5 layers of fallback = zero downtime -Monthly cost: $20-200 (subscriptions) + $10-20 (backup) + 1. cc/claude-opus-4-7 (最佳质量) + 2. cx/gpt-5.5 (第二个订阅) + 3. glm/glm-4.7 (经济型，每日重置) + 4. minimax/MiniMax-M2.1 (最经济，5 小时重置) + 5. if/kimi-k2 (免费无限) + +结果：5 层容灾 = 零停机 +每月费用：$20-200（订阅）+ $10-20（备用） ``` -### Case 4: "I want FREE AI in OpenClaw" +### 场景 4：「我想在 OpenClaw 中使用免费的 AI」 -**Problem:** Need AI assistant in messaging apps, completely free +**问题：** 需要在即时通讯应用中使用 AI 助手，完全免费 ``` Combo: "openclaw-free" - 1. if/glm-4.7 (unlimited free) - 2. if/minimax-m2.1 (unlimited free) - 3. if/kimi-k2-thinking (unlimited free) + 1. if/qwen3-coder-plus (无限免费) + 2. if/deepseek-r1 (无限免费) + 3. if/kimi-k2 (无限免费) -Monthly cost: $0 -Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +每月费用：$0 +访问途径：WhatsApp, Telegram, Slack, Discord, iMessage, Signal... ``` --- -## 📖 Provider Setup +## 📖 服务商配置 -### 🔐 Subscription Providers +### 🔐 订阅制服务商 #### Claude Code (Pro/Max) @@ -121,11 +131,13 @@ Dashboard → Providers → Connect Claude Code Models: cc/claude-opus-4-7 - cc/claude-sonnet-4-5-20250929 + cc/claude-sonnet-4-6 cc/claude-haiku-4-5-20251001 ``` -**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! +**技巧：** 复杂任务用 Opus，追求速度用 Sonnet。OmniRoute 为每个模型单独追踪配额！ + +Claude 和 Claude Code 兼容路由对 Opus 和 Sonnet 模型保留 `max` 思考级别。Haiku 模型不接受 `max` 级别，OmniRoute 会在发送到上游之前将该请求降级为较高的思考预算。 #### OpenAI Codex (Plus/Pro) @@ -135,12 +147,12 @@ Dashboard → Providers → Connect Codex → 5-hour + weekly reset Models: - cx/gpt-5.2-codex - cx/gpt-5.1-codex-max + cx/gpt-5.5 + cx/gpt-5.4 + cx/gpt-5.3-codex + cx/gpt-5.3-codex-spark ``` - - #### GitHub Copilot ```bash @@ -149,68 +161,71 @@ Dashboard → Providers → Connect GitHub → Monthly reset (1st of month) Models: - gh/gpt-5 - gh/claude-4.5-sonnet + gh/gpt-5.5 + gh/gpt-5.4 + gh/claude-sonnet-4.6 + gh/claude-opus-4.7 gh/gemini-3.1-pro-preview ``` -### 💰 Cheap Providers +### 💰 经济型服务商 -#### GLM-4.7 (Daily reset, $0.6/1M) +#### GLM-4.7（每日重置，$0.6/1M） -1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) -2. Get API key from Coding Plan -3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` +1. 注册：[智谱 AI](https://open.bigmodel.cn) +2. 从 Coding Plan 获取 API Key +3. Dashboard → Add API Key：Provider: `glm`，API Key: `your-key` -**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. +**使用：** `glm/glm-4.7` — **技巧：** Coding Plan 提供 3 倍配额，仅需 1/7 成本！每日 10:00 重置。 -#### MiniMax M2.1 (5h reset, $0.20/1M) +#### MiniMax M2.1（5 小时重置，$0.20/1M） -1. Sign up: [MiniMax](https://www.minimax.io/) -2. Get API key → Dashboard → Add API Key +1. 注册：[MiniMax](https://www.minimax.io) +2. 获取 API Key → Dashboard → Add API Key -**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! +**使用：** `minimax/MiniMax-M2.1` — **技巧：** 长上下文（1M Token）场景下最经济的选择！ -#### Kimi K2 ($9/month flat) +#### Kimi K2（$9/月 固定费用） -1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) -2. Get API key → Dashboard → Add API Key +1. 订阅：[月之暗面](https://platform.moonshot.ai) +2. 获取 API Key → Dashboard → Add API Key -**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! +**使用：** `kimi/kimi-k2.5` — **技巧：** 固定 $9/月享受 10M Token，相当于 $0.90/1M！ -### 🆓 FREE Providers +#### Baidu Qianfan / ERNIE -#### Qoder (8 FREE models) +1. 注册：[百度智能云千帆](https://cloud.baidu.com/product/wenxinworkshop) +2. 创建千帆 API Key → Dashboard → Add API Key：Provider: `qianfan` -```bash -Dashboard → Connect Qoder → OAuth login → Unlimited usage +**使用：** `qianfan/ernie-5.1`、`qianfan/ernie-x1.1` 或其他千帆 OpenAI 兼容模型 ID。 -Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 -``` +### 🆓 免费服务商 -#### Qwen (3 FREE models) +无需认证的免费服务商在其服务商页面上有一个「No authentication required」开关。关闭该开关将禁用该服务商，从已配置/紧凑视图中移除，并从 `/v1/models` 中移除其模型。 + +#### Qoder（8 个免费模型） ```bash -Dashboard → Connect Qwen → Device code auth → Unlimited usage +Dashboard → Connect Qoder → OAuth login → Unlimited usage -Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +Models: if/kimi-k2, if/qwen3-coder-plus, if/qwen3-max, if/qwen3-235b, if/deepseek-r1, if/deepseek-v3.2 ``` -#### Kiro (Claude FREE) +#### Kiro（免费 Claude） ```bash -Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → ~50 credits/month Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 ``` --- -## 🎨 Combos +## 🎨 Combo -You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload. +你可以在 **Dashboard → Combos** 中通过拖拽每张卡片的把手直接调整 Combo 卡片顺序。顺序存储在 SQLite 中，重新加载后恢复。 -### Example 1: Maximize Subscription → Cheap Backup +### 示例 1：最大化订阅 → 经济备用 ``` Dashboard → Combos → Create New @@ -219,25 +234,25 @@ Name: premium-coding Models: 1. cc/claude-opus-4-7 (Subscription primary) 2. glm/glm-4.7 (Cheap backup, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + 3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.3/1M) Use in CLI: premium-coding ``` -### Example 2: Free-Only (Zero Cost) +### 示例 2：纯免费（零成本） ``` Name: free-combo Models: - 1. if/kimi-k2-thinking (unlimited) - 2. qw/qwen3-coder-plus (unlimited) + 1. if/kimi-k2 (unlimited) + 2. qw/coder-model (unlimited) Cost: $0 forever! ``` --- -## 🔧 CLI Integration +## 🔧 CLI 集成 ### Cursor IDE @@ -250,15 +265,19 @@ Settings → Models → Advanced: ### Claude Code -Edit `~/.claude/config.json`: +编辑 `~/.claude/settings.json`： ```json { - "anthropic_api_base": "http://localhost:20128/v1", - "anthropic_api_key": "your-omniroute-api-key" + "env": { + "ANTHROPIC_BASE_URL": "http://localhost:20128", + "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key" + } } ``` +此处使用 Claude 兼容的根端点。不要在 `ANTHROPIC_BASE_URL` 后追加 `/v1`。 + ### Codex CLI ```bash @@ -269,13 +288,13 @@ codex "your prompt" ### OpenClaw -Edit `~/.openclaw/openclaw.json`: +编辑 `~/.openclaw/openclaw.json`： ```json { "agents": { "defaults": { - "model": { "primary": "omniroute/if/glm-4.7" } + "model": { "primary": "omniroute/if/kimi-k2" } } }, "models": { @@ -284,14 +303,14 @@ Edit `~/.openclaw/openclaw.json`: "baseUrl": "http://localhost:20128/v1", "apiKey": "your-omniroute-api-key", "api": "openai-completions", - "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + "models": [{ "id": "if/kimi-k2", "name": "kimi-k2" }] } } } } ``` -**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config +**或使用 Dashboard：** CLI Tools → OpenClaw → Auto-config ### Cline / Continue / RooCode @@ -304,9 +323,9 @@ Model: cc/claude-opus-4-7 --- -## 部署 +## 🚀 部署 -### Global npm install (Recommended) +### 全局 npm 安装（推荐） ```bash npm install -g omniroute @@ -323,20 +342,20 @@ omniroute omniroute --port 3000 ``` -The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. +CLI 自动从 `~/.omniroute/.env` 或 `./.env` 加载环境变量。 -### Uninstalling +### 卸载 -When you no longer need OmniRoute, we provide two quick scripts for a clean removal: +当你不再需要 OmniRoute 时，我们提供了两个快速脚本来干净地移除： -| 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**. | +| 命令 | 作用 | +| ------------------------- | ---------------------------------------------------------------- | +| `npm run uninstall` | 移除系统应用，但**保留 `~/.omniroute` 中的数据库和配置** | +| `npm run uninstall:full` | 移除应用并**永久删除���有配置、密钥和数据库** | -> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`. +> 注意：运行这些命令需要进入 OmniRoute 项目目录（如果你 clone 了项目）。如果全局安装，直接运行 `npm uninstall -g omniroute` 即可。 -### VPS Deployment +### VPS 部署 ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -355,9 +374,9 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### PM2 Deployment (Low Memory) +### PM2 部署（低内存） -For servers with limited RAM, use the memory limit option: +对于内存有限的服务器，可使用内存限制选项： ```bash # With 512MB limit (default) @@ -370,7 +389,7 @@ OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start pm2 start ecosystem.config.js ``` -Create `ecosystem.config.js`: +创建 `ecosystem.config.js`： ```javascript module.exports = { @@ -402,19 +421,19 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -For host-integrated mode with CLI binaries, see the Docker section in the main docs. +关于集成了 CLI 二进制文件的主机集成模式，请参阅主文档中的 Docker 章节。 ### Void Linux (xbps-src) -Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings. +Void Linux 用户可使用 `xbps-src` 交叉编译框架原生打包安装 OmniRoute。这种方式可自动化完成 Node.js 独立构建及所需的 `better-sqlite3` 原生绑定。
-View xbps-src template +查看 xbps-src 模板 ```bash # Template file for 'omniroute' pkgname=omniroute -version=3.2.4 +version=3.8.0 revision=1 hostmakedepends="nodejs python3 make" depends="openssl" @@ -504,107 +523,120 @@ post_install() {
-### Environment Variables - -| Variable | Default | Description | -| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | -| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync | -| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | -| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | -| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | - -For the full environment variable reference, see the [README](../README.md). +### 环境变量 + +| 变量 | 默认值 | 说明 | +| --------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 签名密钥（**生产环境必须修改**） | +| `INITIAL_PASSWORD` | `CHANGEME` | 首次登录密码 | +| `DATA_DIR` | `~/.omniroute` | 数据目录（数据库、用量、日志） | +| `PORT` | 框架默认 | 服务端口（示例中使用 `20128`） | +| `HOSTNAME` | 框架默认 | 绑定主机（Docker 默认为 `0.0.0.0`） | +| `NODE_ENV` | 运行时默认 | 部署时设为 `production` | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | 面向前端和服务器公开的基础 URL（替代旧版 `BASE_URL`） | +| `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | Cloud Sync 端点基础 URL（替代旧版 `CLOUD_URL`） | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成 API Key 的 HMAC 密钥 | +| `REQUIRE_API_KEY` | `false` | 对 `/v1/*` 强制使用 Bearer API Key | +| `ALLOW_API_KEY_REVEAL` | `false` | 允许已认证的 Dashboard 用户按需显示完整 API Key 值 | +| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | 缓存的 Provider Limits 数据服务端刷新周期；UI 刷新按钮仍可触发手动同步 | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | 禁用在写入/导入/恢复前的自动 SQLite 快照；手动备份仍可使用 | +| `APP_LOG_TO_FILE` | `true` | 启用应用和审计日志写入磁盘 | +| `AUTH_COOKIE_SECURE` | `false` | 强制 `Secure` auth Cookie（在 HTTPS 反向代理之后） | +| `CLOUDFLARED_BIN` | 未设置 | 使用已有的 `cloudflared` 二进制文件，而非托管下载 | +| `CLOUDFLARED_PROTOCOL` | `http2` | 托管 Quick Tunnel 的传输协议（`http2`、`quic` 或 `auto`） | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆内存上限（MB） | +| `PROMPT_CACHE_MAX_SIZE` | `50` | 提示缓存条目上限 | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | 语义缓存条目上限 | + +完整环境变量参考见 [README](../README.md)。 --- -## 📊 Available Models +## 📊 可用模型
-View all available models +查看所有可用模型 + +> 以下列表基于 v3.8.0 的 `open-sse/config/providerRegistry.ts` 整理。云服务目录（Gemini、OpenRouter 等）会动态同步 — 完整实时目录请打开 **Dashboard → Providers → [provider] → Available Models** 或调用 `GET /api/models/catalog`。 + +**Claude Code (`cc/`)** — Pro/Max OAuth: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Codex (`cx/`)** — Plus/Pro OAuth: `cx/gpt-5.5`（+ 级别：`gpt-5.5-xhigh`、`gpt-5.5-high`、`gpt-5.5-medium`、`gpt-5.5-low`）、`cx/gpt-5.4`、`cx/gpt-5.4-mini`、`cx/gpt-5.3-codex`、`cx/gpt-5.3-codex-spark` -**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime` -**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Kiro (`kr/`)** — FREE OAuth: `kr/auto-kiro`, `kr/claude-opus-4.7`, `kr/claude-opus-4.6`, `kr/claude-sonnet-4.6`, `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`, `kr/deepseek-3.2`, `kr/minimax-m2.5`, `kr/minimax-m2.1`, `kr/glm-5`, `kr/qwen3-coder-next` +**Qoder (`if/`)** — FREE OAuth: `if/kimi-k2-0905`, `if/kimi-k2`, `if/qwen3-coder-plus`, `if/qwen3-max`, `if/qwen3-max-preview`, `if/qwen3-vl-plus`, `if/qwen3-32b`, `if/qwen3-235b-a22b-thinking-2507`, `if/qwen3-235b-a22b-instruct`, `if/qwen3-235b`, `if/deepseek-v3.2`, `if/deepseek-v3`, `if/deepseek-r1`, `if/qoder-rome-30ba3b` -**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**Qwen (`qw/`)** — FREE OAuth (chat.qwen.ai): `qw/coder-model`, `qw/vision-model` -**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` +**GLM (`glm/`、`glm-cn/`、`zai/`、`glmt/`)** — $0.2–0.6/1M: `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air` -**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`、`minimax-cn/`)** — $0.2/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed` -**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**Kimi (`kimi/`、`kimi-coding/`、`kimi-coding-apikey/`)** — $9/月 固定或按量: `kimi/kimi-k2.6`, `kimi/kimi-k2.5` -**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**DeepSeek (`ds/`)** — API key: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash` -**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Groq (`groq/`)** — 超高速: `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b` -**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` +**xAI (`xai/`)** — Grok 原生: `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning` -**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Mistral (`mistral/`)** — 欧盟托管: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest` -**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` +**Perplexity (`pplx/`)** — 搜索增强: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar` -**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Together AI (`together/`)** — 开源: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (free), `together/meta-llama/Llama-Vision-Free`, `together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`, `together/deepseek-ai/DeepSeek-R1`, `together/Qwen/Qwen3-235B-A22B`, `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` -**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Fireworks AI (`fireworks/`)** — 快速推理: `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro` -**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Cerebras (`cerebras/`)** — 晶圆级: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b` -**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Cohere (`cohere/`)** — RAG 导向: `cohere/command-a-reasoning-08-2025`, `cohere/command-a-vision-07-2025`, `cohere/command-a-03-2025`, `cohere/command-r-08-2024` -**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` +**NVIDIA NIM (`nvidia/`)** — 企业级: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b` -**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1` -**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` +**Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:397b` + +**Gemini (Google Cloud `gemini/`)**: 按 API Key 从 Google 实时同步 — 无静态列表。在 **Dashboard → Providers** 中连接 Key，然后使用 **Available Models** 导入当前目录（例如 `gemini/gemini-3-pro`、`gemini/gemini-3-flash`）。 + +**其他兼容服务商**（精选）: `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (via `aws-bedrock`), `azure-ai`, `openrouter`（透传目录）, `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`。每个服务商在 `providerRegistry.ts` 中维护各自的模型列表，当服务商暴露 `/models` 端点时可自动同步。 + +**模型 ID 说明：** OmniRoute 使用服务商原生的 ID（`claude-opus-4-8`、`gpt-5.5`、`glm-5.1`、`MiniMax-M2.7`、`kimi-k2.5`、`grok-4.20-0309-reasoning`）。部分 ID 带有带点版本号，这是因为上游 API 要求如此。如果某模型未在上方列出，运行 `omniroute models --search ` 或调用 `GET /api/models/catalog` 确认可用性。
--- -## 🧩 Advanced Features +## 🧩 高级功能 -### Custom Models +### 自定义模型 -Add any model ID to any provider without waiting for an app update: +添加任意模型 ID 到任意服务商，无需等待应用更新： ```bash # Via API curl -X POST http://localhost:20128/api/provider-models \ -H "Content-Type: application/json" \ - -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}' # List: curl http://localhost:20128/api/provider-models?provider=openai -# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2" ``` -Or use Dashboard: **Providers → [Provider] → Custom Models**. +或使用 Dashboard：**Providers → [Provider] → Custom Models**。 -Notes: +注意事项： -- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. -- The **Custom Models** section is intended for providers that do not expose managed available-model imports. +- OpenRouter 和 OpenAI/Anthropic 兼容服务商仅通过 **Available Models** 管理。手动添加、导入和自动同步都汇总到同一个可用模型列表，因此这些服务商不显示单独的 Custom Models 区域。 +- **Custom Models** 区域适用于不暴露托管模型导入功能的服务商。 -### Dedicated Provider Routes +### 专用服务商路由 -Route requests directly to a specific provider with model validation: +将请求直接路由到特定服务商，并附带模型校验： ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -612,9 +644,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -The provider prefix is auto-added if missing. Mismatched models return `400`. +服务商前缀在缺失时自动添加。模型不匹配返回 `400`。 -### Network Proxy Configuration +### 网络代理配置 ```bash # Set global proxy @@ -630,157 +662,175 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. +**优先级：** Key 级 → Combo 级 → 服务商级 → 全局 → 环境变量。 -### Model Catalog API +### 模型目录 API ```bash curl http://localhost:20128/api/models/catalog ``` -Returns models grouped by provider with types (`chat`, `embedding`, `image`). +按服务商分组返回模型，并标注类型（`chat`、`embedding`、`image`）。 ### Cloud Sync -- Sync providers, combos, and settings across devices -- Automatic background sync with timeout + fail-fast -- Prefer server-side `BASE_URL`/`CLOUD_URL` in production +- 跨设备同步服务商、Combo 和设置 +- 自动后台同步，带超时和快速失败机制 +- 生产环境建议使用服务端 `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` ### Cloudflare Quick Tunnel -- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments -- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint -- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary -- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed -- Tunnel URLs are ephemeral and change every time you stop/start the tunnel -- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers -- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice -- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download +- 在 Docker 和其他自托管部署中，前往 **Dashboard → Endpoints** 使用 +- 创建一个临时的 `https://*.trycloudflare.com` URL，将流量转发到当前的 OpenAI 兼容 `/v1` 端点 +- 首次启用时按需安装 `cloudflared`；后续重启复用同一托管二进制文件 +- Quick Tunnel 在 OmniRoute 或容器重启后不会自动恢复；需要时从 Dashboard 重新启用 +- Tunnel URL 是临时的，每次停止/启动 Tunnel 都会变化 +- 托管 Quick Tunnel 默认使用 HTTP/2 传输，以避免在受限容器中产生 QUIC UDP 缓冲区噪音 +- 如需覆盖托管传输选择，设置 `CLOUDFLARED_PROTOCOL=quic` 或 `auto` +- 如需使用预装的 `cloudflared` 二进制文件而非托管下载，设置 `CLOUDFLARED_BIN` +- Cloudflare Quick Tunnel、Tailscale Funnel 和 ngrok Tunnel 面板可在 **Settings → Appearance** 中显示或隐藏。隐藏面板不会停止正在运行的 Tunnel。 -### LLM Gateway Intelligence (Phase 9) +### LLM 网关智能（Phase 9） -- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header -- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header +- **语义缓存** — 自动缓存非流式、temperature=0 的响应（通过 `X-OmniRoute-No-Cache: true` 绕过） +- **请求幂等** — 通过 `Idempotency-Key` 或 `X-Request-Id` 头在 5 秒内对请求去重 +- **进度追踪** — 通过 `X-OmniRoute-Progress: true` 头选择加入 SSE `event: progress` 事件 --- -### Translator Playground +### 翻译器实验场 -Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. +通过 **Dashboard → Translator** 访问。调试和可视化 OmniRoute 如何在服务商之间转换 API 请求。 -| Mode | Purpose | -| ---------------- | -------------------------------------------------------------------------------------- | -| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | -| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | -| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | -| **Live Monitor** | Watch real-time translations as requests flow through the proxy | +| 模式 | 用途 | +| ---------------- | ------------------------------------------------------------------------- | +| **Playground** | 选择源/目标格式，粘贴请求，即时查看翻译后的输出 | +| **Chat Tester** | 通过代理发送实时聊天消息，并检查完整的请求/响应周期 | +| **Test Bench** | 跨多个格式组合运行批量测试，验证翻译正确性 | +| **Live Monitor** | 实时观察请求流经代理时的翻译过程 | -**Use cases:** +**用途：** -- Debug why a specific client/provider combination fails -- Verify that thinking tags, tool calls, and system prompts translate correctly -- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats +- 调试特定客户端/服务商组合失败的原因 +- 验证 thinking 标签、工具调用和系统提示翻译是否正确 +- 对比 OpenAI、Claude、Gemini 和 Responses API 格式之间的差异 --- -### Routing Strategies +### 路由策略 + +通过 **Dashboard → Settings → Routing** 配置。Dashboard 展示六种最常用的策略；Combo 和自动路由器内部支持更多策略。 + +**Dashboard 可见策略（账户级路由）：** + +| 策略 | 说明 | +| ------------------------------- | ---------------------------------------------------------- | +| **Fill First** | 按优先级顺序使用账户 — 主账户处理所有请求，直到不可用 | +| **Round Robin** | 循环遍历所有账户，可配置粘性限制（默认：每账户 3 次调用） | +| **P2C (Power of Two Choices)** | 随机选择 2 个账户，路由到更健康的那个 — 兼顾负载与健康感知 | +| **Random** | 使用 Fisher-Yates 洗牌为每次请求随机选择账户 | +| **Least Used** | 路由到 `lastUsedAt` 时间戳最早的账户，均匀分配流量 | +| **Cost Optimized** | 路由到优先级值最低的账户，优先选择成本最低的服务商 | -Configure via **Dashboard → Settings → Routing**. +**高级 Combo 和自动策略**（可按 Combo 配置或通过 `auto/*` 前缀 — 详见 [AUTO-COMBO.md](../routing/AUTO-COMBO.md)）： -| Strategy | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------ | -| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | -| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | -| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | -| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | -| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | -| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | +- `priority` — 严格顺序，不轮询 +- `weighted` — 按模型权重分配流量比例 +- `fill-first` — 将第一个模型用至限制后才切换 +- `round-robin` / `strict-random` / `random` +- `p2c` (Power of Two Choices) +- `least-used` 和 `cost-optimized` +- `auto` — 在所有候选中按得分驱动 +- `lkgp` (Last Known Good Provider) — 每次会话固定使用上一次成功的模型 +- `context-optimized` — 选择可用上下文窗口最大的模型 +- `context-relay` — 串联长上下文模型用于后续轮次 -#### External Sticky Session Header +#### 外部粘性会话头 -For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send: +对于外部会话亲和性（例如反向代理后的 Claude Code/Codex 代理），发送： ```http X-Session-Id: your-session-key ``` -OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`. +OmniRoute 也接受 `x_session_id`，并在 `X-OmniRoute-Session-Id` 中返回生效的会话 Key。 -If you use Nginx and send underscore-form headers, enable: +如果你使用 Nginx 发送下划线形式的头，启用： ```nginx underscores_in_headers on; ``` -#### Wildcard Model Aliases +#### 通配符模型别名 -Create wildcard patterns to remap model names: +创建通配符模式来重新映射模型名称： ``` -Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 -Pattern: gpt-* → Target: gh/gpt-5.1-codex +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6 +Pattern: gpt-* → Target: gh/gpt-5.3-codex ``` -Wildcards support `*` (any characters) and `?` (single character). +通配符支持 `*`（任意字符）和 `?`（单个字符）。 -#### Fallback Chains +#### 容灾链 -Define global fallback chains that apply across all requests: +定义应用于所有请求的全局容灾链： ``` Chain: production-fallback 1. cc/claude-opus-4-7 - 2. gh/gpt-5.1-codex + 2. gh/gpt-5.3-codex 3. glm/glm-4.7 ``` --- -### Resilience & Circuit Breakers +### 容灾与熔断器 -Configure via **Dashboard → Settings → Resilience**. +通过 **Dashboard → Settings → Resilience** 配置。 -OmniRoute implements provider-level resilience with five components: +OmniRoute 通过五个组件实现服务商级容灾： -1. **Request Queue & Pacing** — System-level request shaping: - - **Requests Per Minute (RPM)** — Maximum requests per minute per account - - **Min Time Between Requests** — Minimum gap in milliseconds between requests - - **Max Concurrent Requests** — Maximum simultaneous requests per account +1. **请求队列与限流** — 系统级请求整形： + - **每分钟请求数 (RPM)** — 每个账户每分钟最大请求数 + - **请求最小间隔** — 请求之间的最小间隔（毫秒） + - **最大并发请求数** — 每个账户同时处理的最大请求数 -2. **Connection Cooldown** — Per-auth-type configuration for a single connection after retryable failures: - - **Base Cooldown** — Default cooldown window for retryable upstream failures - - **Use Upstream Retry Hints** — Honors authoritative `Retry-After` or reset hints when provided - - **Max Backoff Steps** — Maximum exponential backoff level for repeated failures +2. **连接冷却** — 在发生可重试故障后，对单条连接按认证类型配置： + - **基础冷却** — 可重试上游故障后的默认冷却窗口 + - **使用上游重试提示** — 当上游提供 `Retry-After` 或重置提示时予以遵循 + - **最大退避步数** — 重复故障时的最大指数退避级别 -3. **Provider Circuit Breaker** — Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached: - - **Failure Threshold** — Consecutive provider failures before opening the breaker - - **Reset Timeout** — Time window before the provider is tested again - - **CLOSED** (Healthy) — Requests flow normally - - **OPEN** — Provider is temporarily blocked after repeated failures - - **HALF_OPEN** — Testing if provider has recovered +3. **服务商熔断器** — 追踪端到端服务商故障，在达到配置的警告阈值时将服务商标记为降级，在达到配置的故障阈值时断开熔断器： + - **降级阈值** — 服务商进入 `DEGRADED` 状态前的连续故障数 + - **故障阈值** — 服务商进入 `OPEN` 状态前的连续故障数 + - **重置超时** — 重新测试服务商之前的时间窗口 + - **CLOSED**（健康）— 请求正常流通 + - **DEGRADED** — 请求继续流通，同时追踪升高的故障率 + - **OPEN** — 服务商在重复故障后被暂时阻断 + - **HALF_OPEN** — 测试服务商是否已恢复 - Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker. + 连接级 `429` 速率限制仅计入**连接冷却**，不计入服务商熔断器。 - The provider breaker runtime state is shown on **Dashboard → Health** only. + 服务商熔断器运行时状态仅在 **Dashboard → Health** 上显示。 -4. **Wait For Cooldown** — If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically. +4. **等待冷却** — 如果所有候选连接都已在冷却中，OmniRoute 可以等待最早完成的冷却，然后自动重试同一个客户端请求。 -5. **Rate Limit Auto-Detection** — When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled. +5. **速率限制自动检测** — 当上游服务商返回明确的等待窗口时，如果该设置已启用，这些提示会覆盖本地连接冷却。 -**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration. +**技巧：** 在发生故障后，使用 **Health** 页面检查和重置实时的服务商熔断器。Resilience 页面仅用于修改配置。 --- -### Database Export / Import +### 数据库导出/导入 -Manage database backups in **Dashboard → Settings → System & Storage**. +在 **Dashboard → Settings → System & Storage** 中管理数据库备份。 -| Action | Description | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | -| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | -| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` | +| 操作 | 说明 | +| ------------------------- | --------------------------------------------------------------------------------------------- | +| **导出数据库** | 下载当前 SQLite 数据库为 `.sqlite` 文件 | +| **全部导出 (.tar.gz)** | 下载完整备份归档，包含：数据库、设置、Combo、服务商连接（不含凭据）、API Key 元数据 | +| **导入数据库** | 上传 `.sqlite` 文件以替换当前数据库。导入前会自动创建备份，除非设置 `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -794,39 +844,42 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). +**导入验证：** 导入的文件需通过完整性校验（SQLite pragma 检查）、必要表检查（`provider_connections`、`provider_nodes`、`combos`、`api_keys`）和大小限制（最大 100MB）。 -**Use Cases:** +**用途：** -- Migrate OmniRoute between machines -- Create external backups for disaster recovery -- Share configurations between team members (export all → share archive) +- 在机器之间迁移 OmniRoute +- 为灾难恢复创建外部备份 +- 在团队成员之间共享配置（全部导出 → 分享归档） --- -### Settings Dashboard +### 设置面板 -The settings page is organized into 6 tabs for easy navigation: +设置页面分为 **7 个标签页**，方便导航： -| Tab | Contents | -| -------------- | -------------------------------------------------------------------------------------------- | -| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | -| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | -| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | -| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior | -| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | -| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | +| 标签页 | 内容 | +| ---------------- | ------------------------------------------------------------------------------------------------- | +| **General** | 系统存储工具、默认行为、Endpoint 隧道可见性 | +| **Appearance** | 主题控制（浅色/深色/系统）、侧边栏可见性、Cloudflare/Tailscale/ngrok 隧道卡片的面板开关 | +| **AI** | 思考预算配置、全局系统提示注入、提示缓存统计 | +| **Security** | 登录/密码设置、IP 访问控制、`/models` 的 API 认证、服务商屏蔽、提示注入安全护栏 | +| **Routing** | 全局路由策略、通配符模型别名、容灾链、Combo 默认值 | +| **Resilience** | 请求队列、连接冷却、服务商熔断器配置及等待冷却行为 | +| **Advanced** | 全局代理配置（HTTP/SOCKS5）、按服务商的代理覆盖 | + +General 标签页不再重复显示只读的日志和缓存说明。数据库保留和优化设置通过 `/api/settings/database` 持久化；手动清除缓存使用 `DELETE /api/cache`。请求和代理日志行数上限由 `CALL_LOGS_TABLE_MAX_ROWS` 和 `PROXY_LOGS_TABLE_MAX_ROWS` 控制。 --- -### Costs & Budget Management +### 费用与预算管理 -Access via **Dashboard → Costs**. +通过 **Dashboard → Costs** 访问。 -| Tab | Purpose | -| ----------- | ---------------------------------------------------------------------------------------- | -| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | -| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | +| 标签页 | 用途 | +| ------------ | --------------------------------------------------------------- | +| **Budget** | 为每个 API Key 设置日/周/月预算上限，实时追踪消费 | +| **Pricing** | 查看和编辑模型定价条目 — 各服务商每 1K 输入/输出 Token 的费用 | ```bash # API: Set a budget @@ -838,13 +891,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. +**费用追踪：** 每次请求记录 Token 用量并使用定价表计算费用。在 **Dashboard → Usage** 中按服务商、模型和 API Key 查看明细。 --- -### Audio Transcription +### 音频转录 -OmniRoute supports audio transcription via the OpenAI-compatible endpoint: +OmniRoute 通过 OpenAI 兼容端点支持音频转录： ```bash POST /v1/audio/transcriptions @@ -858,49 +911,259 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +**语音转文字（转录）** 服务商： + +- `openai/` (whisper-compatible) +- `groq/` (Groq Whisper Turbo) +- `deepgram/` (Nova family) +- `assemblyai/` +- `nvidia/` (Parakeet, Canary) +- `huggingface/` (whisper variants) +- `qwen/` + +**文字转语音 (`POST /v1/audio/speech`)** 服务商： + +- `openai/` (tts-1, tts-1-hd) +- `hyperbolic/` +- `deepgram/` (Aura) +- `nvidia/` (Magpie TTS) +- `elevenlabs/` +- `huggingface/` +- `inworld/` +- `cartesia/` +- `playht/` +- `kie/` +- `aws-polly/` +- `xiaomi-mimo/` +- `coqui/`, `tortoise/` +- `qwen/` + +转录支持的音频格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。TTS 输出格式取决于服务商（mp3、wav、opus、pcm、mulaw）。 + +--- + +### Combo 负载均衡策略 + +在 **Dashboard → Combos → Create/Edit → Strategy** 中按 Combo 配置负载均衡。 + +| 策略 | 说明 | +| ------------------ | ------------------------------------------------ | +| **Round-Robin** | 按顺序轮询模型 | +| **Priority** | 始终先尝试第一个模型，仅在出错时容灾切换 | +| **Random** | 每次请求从 Combo 中随机选择一个模型 | +| **Weighted** | 按每个模型分配的权重比例路由 | +| **Least-Used** | 路由到最近请求最少的模型（使用 Combo 指标） | +| **Cost-Optimized** | 路由到当前可用的最廉价模型（使用定价表） | + +全局 Combo 默认值可在 **Dashboard → Settings → Routing → Combo Defaults** 中设置。 +Combo 目标超时默认继承当前请求超时。仅在需要更短的按目标限制以触发更快容灾切换时，才在 Combo 默认值或单个 Combo 上使用 **Target timeout (seconds)**。 + +零延时 Combo 优化是可选功能。保持 **Zero-latency optimizations** 禁用可避免这些延时特性竞跑容灾目标、基于 TTFT 历史跳过目标或压缩容灾请求；启用后允许配置的对冲、预测性 TTFT 跳过和主动容灾压缩，以路由/请求的保真度换取更低的尾部延时。 + +当上游服务商要求严格的 `max_tokens`/`maxOutputTokens` 限制时，禁用 **Reasoning token buffer**。启用后，Combo 路由仅对已知输出上限的模型添加推理模型 Headroom，当安全的缓冲值超出客户端 Token 限制时保持其不变。如果客户端限制已高于已知上限，OmniRoute 在发送上游请求前会将其限制到该上限。 + +--- + +### 健康面板 + +通过 **Dashboard → Health** 访问。实时系统健康概览，包含 6 张卡片： + +| 卡片 | 显示内容 | +| --------------------- | ---------------------------------------- | +| **System Status** | 运行时间、版本、内存用量、数据目录 | +| **Provider Health** | 全局服务商熔断器运行时状态 | +| **Rate Limits** | 每账户活跃的连接冷却及剩余时间 | +| **Active Lockouts** | 活跃的模型级封锁和临时排除 | +| **Signature Cache** | 去重缓存统计（活跃 Key、命中率） | +| **Latency Telemetry** | 各服务商的 p50/p95/p99 延时聚合 | + +**技巧：** Health 页面每 10 秒自动刷新。使用熔断器卡片识别哪些服务商正在发生问题。 + +--- + +## 🤖 自动路由（零配置） + +OmniRoute 内置了一个**得分驱动的自动路由器**，可跨所有已连接的服务商为每个请求选择最佳模型 — 无需维护 Combo。只需使用 `auto/*` 前缀发送请求，OmniRoute 即可即时构建虚拟 Combo，按延时、费用、成功率、上下文适配度、任务匹配度、近期故障、配额和熔断器状态对候选模型进行评分。 + +| 前缀 | 优化目标 | +| -------------- | -------------------------------------------------------------------------- | +| `auto` | 均衡默认值（延时 × 费用 × 成功率） | +| `auto/coding` | 编码任务：优先 Claude、GPT-5、GLM、Kimi、Qwen Coder、DeepSeek 编码模型 | +| `auto/cheap` | 最低 $/Token，接受较高延时 | +| `auto/fast` | 最低延时，忽略费用 | +| `auto/offline` | 仅本地服务商（Ollama、vLLM、llama.cpp）— 适用于离线环境 | +| `auto/smart` | 推理质量优先（Opus、GPT-5 xhigh、R1、GLM 5.1 reasoning） | +| `auto/lkgp` | "最后已知成功服务商" — 粘性路由到最近一次成功的目标 | + +示例： + +```bash +curl -X POST http://localhost:20128/v1/chat/completions \ + -H "Authorization: Bearer $OMNIROUTE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "auto/coding", + "messages": [{ "role": "user", "content": "Refactor this Python function" }], + "stream": true + }' +``` + +自动路由器的完整说明见 [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — 包括如何调整评分权重、屏蔽服务商，以及通过 **Dashboard → Auto Combo** 检查路由决策。 -Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +--- + +## 🔌 MCP 与 A2A 集成 + +OmniRoute 同时是一个 **MCP 服务端**（Model Context Protocol）和一个 **A2A 服务端**（Agent-to-Agent JSON-RPC 2.0）。任何兼容 MCP 的 IDE 或代理主机都可以直接调用 OmniRoute 工具 — 无需额外包装。 + +### MCP 传输方式 + +- **SSE**: `http://localhost:20128/api/mcp/sse` +- **Streamable HTTP**: `http://localhost:20128/api/mcp/stream` +- **stdio**: `omniroute --mcp`（适用于偏好 stdio 的 IDE 插件） + +### 连接 Claude Desktop + +编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 Windows/Linux 的对应路径： + +```json +{ + "mcpServers": { + "omniroute": { + "command": "omniroute", + "args": ["--mcp"] + } + } +} +``` + +### 连接 Cursor / Continue / VS Code MCP + +使用 SSE URL `http://localhost:20128/api/mcp/sse` 和在 **Dashboard → API Keys** 中生成的 Bearer API Key。 + +### 权限域 + +MCP 工具分为 10 个权限域：`analytics`、`auth`、`billing`、`combos`、`health`、`keys`、`memory`、`models`、`providers`、`system`。每个 Bearer Key 可限制到特定权限域 — 完整工具目录见 [MCP-SERVER.md](../frameworks/MCP-SERVER.md)，JSON-RPC Schema 见 [A2A-SERVER.md](../frameworks/A2A-SERVER.md)。 + +--- + +## 🧠 技能系统 + +OmniRoute 暴露一个可扩展的**技能框架** (`src/lib/skills/`)，使代理和 A2A 端点可以运行领域特定的例程（如 `code-review`、`summarize`、`extract-facts`、`web-research`）。 + +- **市场 UI** — 通过 **Dashboard → Skills** 浏览和安装技能 +- **按 Key 的权限域** — 限制哪些 API Key 可调用哪些技能 +- **自定义技能** — 将 TypeScript 文件放入 `src/lib/a2a/skills/`，注册后即可通过 A2A 立即调用 + +完整参考：[SKILLS.md](../frameworks/SKILLS.md)。 + +--- + +## 💾 记忆系统 + +OmniRoute 通过混合检索持久化**长期对话记忆**： + +- **SQLite FTS5** 用于对历史轮次进行关键词搜索 +- **Qdrant 向量存储**（可选）用于语义召回 +- **自动事实提取** — 每次会话后汇总实体、偏好和决策，存入 `memory_facts` 表 +- 记忆按 API Key 和会话进行隔离 + +通过 **Dashboard → Memory** 管理记忆（搜索、编辑、导出、清除）。HTTP 接口 (`/api/memory/*`) 允许代理以编程方式推送和查询事实 — 详见 [MEMORY.md](../frameworks/MEMORY.md)。 + +--- + +## 🔔 Webhook + +订阅 OmniRoute 事件，实现实时监控和自动化。 + +- 在 **Dashboard → Webhooks** 中创建 Webhook，配置目标 URL 和 HMAC 签名密钥 +- 可用事件：`request.completed`、`request.failed`、`provider.unavailable`、`budget.exceeded`、`combo.switched`、`circuit_breaker.opened`、`circuit_breaker.closed` +- 每个载荷包含 `X-OmniRoute-Signature`（HMAC-SHA256）供验证 +- 重试：3 次尝试，指数退避，然后进入死信队列 + +完整 Schema 见 [WEBHOOKS.md](../frameworks/WEBHOOKS.md)。 + +--- + +## ☁️ 云代理 + +OmniRoute 集成了云编程代理（**OpenAI Codex Cloud**、**Devin**、**Jules**、**Antigravity**），使你能够在处理本地路由的同一 Dashboard 中派发长时间运行的任务。 + +- 在 **Dashboard → Cloud Agents** 中创建任务，或通过 `POST /api/v1/agents/tasks` +- 按任务追踪状态、日志和产物 +- 每个服务商使用自备 API Key — 凭据永不离开 OmniRoute 实例 + +完整参考：[CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md)。 --- -### Combo Balancing Strategies +## 🛠️ 编程式管理 -Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. +你可以通过 HTTP，使用具有 `manage` 权限域的 **Bearer Key** 来管理 OmniRoute 的每一项资源（服务商、Combo、Key、设置）。 -| Strategy | Description | -| ------------------ | ------------------------------------------------------------------------ | -| **Round-Robin** | Rotates through models sequentially | -| **Priority** | Always tries the first model; falls back only on error | -| **Random** | Picks a random model from the combo for each request | -| **Weighted** | Routes proportionally based on assigned weights per model | -| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | -| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | +在 **Dashboard → API Keys → New Key → Scope: manage** 中生成 Key，然后： -Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. +```bash +# List providers +curl http://localhost:20128/api/providers \ + -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" + +# Add a provider connection +curl -X POST http://localhost:20128/api/providers \ + -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }' + +# Create a combo +curl -X POST http://localhost:20128/api/combos \ + -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ + -H "Content-Type: application/json" \ + -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }' + +# List/create API keys +curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" +curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ + -d '{ "name": "ci-bot", "scopes": ["chat"] }' +``` + +完整端点目录和请求/响应 Schema 见 [API_REFERENCE.md](../reference/API_REFERENCE.md)。 --- -### Health Dashboard +## 💻 内置 CLI -Access via **Dashboard → Health**. Real-time system health overview with 6 cards: +OmniRoute 内置了 CLI 工具（`omniroute …`），用于设置、诊断和运行时控制。这与 Dashboard 中的「CLI Tools」页面是**分开的**，后者用于配置第三方 CLI（Claude Code、Cursor、Codex、Cline 等）使之能够对接 OmniRoute。 -| Card | What It Shows | -| --------------------- | ----------------------------------------------------------- | -| **System Status** | Uptime, version, memory usage, data directory | -| **Provider Health** | Global provider circuit breaker runtime state | -| **Rate Limits** | Active connection cooldowns per account with remaining time | -| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions | -| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | -| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | +```bash +omniroute setup # 交互式向导（密码、服务商、Combo） +omniroute setup --non-interactive # 适合 CI 环境 +omniroute doctor # 健康诊断（数据目录、数据库、服务商、端口） +omniroute providers available # 列出支持的服务商 +omniroute providers list # 列出已配置的连接 +omniroute providers test # 实时测试服务商连接 +omniroute combos list # 列出 Combo +omniroute combos switch # 设置默认 Combo +omniroute models # 列出可用模型（--json、--search） +omniroute keys add | list | remove # 从终端管理 API Key +omniroute backup # 快照配置 + 数据库 +omniroute restore [] # 从快照恢复 +omniroute health # 详细健康信息（熔断器、缓存、内存） +omniroute quota # 服务商配额用量 +omniroute mcp status # MCP 服务端状态 +omniroute a2a status # A2A 服务端状态 +omniroute tunnel list|create|stop # Cloudflare/Tailscale/ngrok 隧道 +omniroute reset-password # 重置管理员密码 +omniroute --mcp # 通过 stdio 启动 MCP 服务端 +omniroute --port 3000 # 在自定义端口启动服务端 +``` -**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. +提示：将 `omniroute doctor --json` 与你的监控工具结合，用于对不健康的服务商连接发出告警。 --- -## 🖥️ Desktop Application (Electron) +## 🖥️ 桌面应用 (Electron) -OmniRoute is available as a native desktop application for Windows, macOS, and Linux. +OmniRoute 提供适用于 Windows、macOS 和 Linux 的原生桌面应用。 ### 安装 @@ -916,34 +1179,34 @@ npm run dev npm start ``` -### Building Installers +### 构建安装包 ```bash cd electron -npm run build # Current platform +npm run build # 当前平台 npm run build:win # Windows (.exe NSIS) npm run build:mac # macOS (.dmg universal) npm run build:linux # Linux (.AppImage) ``` -Output → `electron/dist-electron/` +输出 → `electron/dist-electron/` -### Key Features +### 核心特性 -| Feature | Description | -| --------------------------- | ---------------------------------------------------- | -| **Server Readiness** | Polls server before showing window (no blank screen) | -| **System Tray** | Minimize to tray, change port, quit from tray menu | -| **Port Management** | Change server port from tray (auto-restarts server) | -| **Content Security Policy** | Restrictive CSP via session headers | -| **Single Instance** | Only one app instance can run at a time | -| **Offline Mode** | Bundled Next.js server works without internet | +| 特性 | 说明 | +| ----------------------------- | ------------------------------------------- | +| **Server Readiness** | 显示窗口前轮询服务端（无白屏） | +| **System Tray** | 最小化到托盘，从托盘菜单切换端口、退出 | +| **Port Management** | 从托盘切换服务端端口（自动重启服务端） | +| **Content Security Policy** | 通过会话头启用严格 CSP | +| **Single Instance** | 同一时间只能运行一个应用实例 | +| **Offline Mode** | 内置 Next.js 服务端，无需联网即可运行 | -### Environment Variables +### 环境变量 -| Variable | Default | Description | -| --------------------- | ------- | -------------------------------- | -| `OMNIROUTE_PORT` | `20128` | Server port | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | +| 变量 | 默认值 | 说明 | +| --------------------- | -------- | --------------------------- | +| `OMNIROUTE_PORT` | `20128` | 服务端端口 | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆内存上限（64–16384 MB） | -📖 Full documentation: [`electron/README.md`](../electron/README.md) +📖 完整文档：[`electron/README.md`](../../electron/README.md) diff --git a/docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md b/docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md index b91e8b537779..9e255ed21efa 100644 --- a/docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md +++ b/docs/i18n/zh-CN/docs/ops/COVERAGE_PLAN.md @@ -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 | - -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: - -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` - -## Execution checklist - -### Phase 1: 56.95% -> 60% - -- [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 阶段 | 60% 语句 / 行 | 速赢项和低风险工具函数覆盖 | ✅ 已完成 | +| 第 2 阶段 | 65% 语句 / 行 | 数据库和路由基础 | ✅ 已完成 | +| 第 3 阶段 | 70% 语句 / 行 | 服务商校验和用量分析 | ✅ 已完成 | +| 第 4 阶段 | 75% 语句 / 行 | `open-sse` 翻译器与辅助函数 | ✅ 已完成 | +| 第 5 阶段 | 80% 语句 / 行 | `open-sse` 处理器和执行器分支 | ✅ 已完成 | +| 第 6 阶段 | 85% 语句 / 行 | 高难度边界情况、分支欠账、回归套件 | 进行中 | +| 第 7 阶段 | 90% 语句 / 行 | 最终扫尾、填补缺口、严格递增 | 待开始 | + +每个阶段都应推动分支和函数覆盖率递增，但主要硬性目标是语句 / 行覆盖率。 + +## 优先热点 + +以下文件当前行覆盖率最低（< 60%），在第 6-7 阶段性价比最高。数据来自 2026-05-13 的 `coverage/coverage-summary.json`： + +| # | 文件 | 行 % | +| --- | ------------------------------------------------------------ | -----: | +| 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% | + +第 6-7 阶段的主题： + +- `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` 优先级较低，但属于低成本的分支覆盖收益。 + +## 执行检查清单 + +### 第 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 +- [ ] 添加针对服务商特定认证、重试和端点覆盖的执行器分支覆盖 + +### 第 6 阶段：80% -> 85% + +- [ ] 将更多边界情况套件合并到主覆盖路径 +- [ ] 提升构造函数/辅助函数覆盖率较弱的数据库模块的函数覆盖 +- [ ] 填补 `settings.ts`、`registeredKeys.ts`、`validation.ts` 和翻译器辅助函数中的分支缺口 + +### 第 7 阶段：85% -> 90% -### Phase 6: 80% -> 85% +- [ ] 将剩余低覆盖率文件视为阻塞项 +- [ ] 为冲刺 90% 期间修复的所有未覆盖生产缺陷添加回归测试 +- [ ] 仅在本地基线至少连续两次运行稳定后，再提升 CI 中的覆盖率门禁 -- [ ] 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 +## 递增策略 -### Phase 7: 85% -> 90% +仅在项目实际以充裕余量超越下一里程碑后，才更新 `npm run test:coverage` 的阈值。 -- [ ] 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 +**当前门禁：** `npm run test:coverage` 执行 **60 语句 / 60 行 / 60 函数 / 60 分支** 的标准（该指标在 Quality-Gates Fase 6A.1 中重新校准 — 此前 82.58% 的基线虚高，因为它统计了测试文件且排除了 `open-sse`）。`test:coverage:legacy` 命令保留了旧的 50/50/50 指标用于历史对比。 -## Ratchet policy +若要基于最新报告进行临时阈值检查，请使用： -Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. +```bash +node scripts/check/test-report-summary.mjs --threshold 75 +``` -Recommended ratchet sequence: +推荐递增序列（顺序为 `语句-行 / 分支 / 函数`）： 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% 冲刺的阻塞项。 diff --git a/docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md index a663ec91c59a..b5ff2809bf1d 100644 --- a/docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md @@ -1,9 +1,11 @@ -# 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 上的实际部署方法，适用于两类场景： - 首次把当前项目部署到 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 + /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`)。 --- diff --git a/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md b/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md index 5f60e672834e..1d7e7a7ed81e 100644 --- a/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md +++ b/docs/i18n/zh-CN/docs/ops/RELEASE_CHECKLIST.md @@ -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 `（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/.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`）处理正确 -Use this checklist before tagging or publishing a new OmniRoute release. +### 服务商目录（Zod 验证） -## Version and Changelog +- [ ] `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@` 运行 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"服务商层级介绍步骤 +- [ ] 首页仪表盘服务商层级覆盖率组件显示已配置/活跃数量 + +--- -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. +## 回滚 -## API Docs +若 Release 出现严重问题： -1. Update `docs/reference/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. +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 中沟通 -## 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. +- 切勿直接提交到 `main` +- 切勿对 `main` 或 `release/*` 分支使用 `git push --force` +- 切勿跳过 Husky hooks（`--no-verify`） +- 切勿提交密钥、凭证或 `.env` 文件 +- 覆盖率必须保持 ≥60/60/60/60（语句/行/函数/分支） +- 修改 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生产代码时，始终包含或更新测试 -## 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 任务）中运行此检查。 diff --git a/docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md index 4df4ceb1c57b..4dcfdd446668 100644 --- a/docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md @@ -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) -Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. +在虚拟机 (VPS) 上安装并配置 OmniRoute 并通过 Cloudflare 管理域名的完整指南。 --- -## Prerequisites +## 前提条件 -| 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+ | +| 项目 | 最低配置 | 推荐配置 | +| ------------ | ------------------------- | ----------------- | +| **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+ | -**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. +**已验证的服务商**：Akamai (Linode)、DigitalOcean、Vultr、Hetzner、AWS Lightsail��� --- -## 1. Configure the VM +## 1. 配置虚拟机 -### 1.1 Create the instance +### 1.1 创建实例 -On your preferred VPS provider: +在你选择的 VPS 服务商上： -- 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`) +- 选择 Ubuntu 24.04 LTS +- 选择最低配置方案 (1 vCPU / 1 GB RAM) +- 设置强 root 密码或配置 SSH 密钥 +- 记下 **公网 IP**（例如 `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` 同步提高到同一阈值以上。 + +OmniRoute 使用 `NEXT_PUBLIC_BASE_URL` 作为 OAuth、公开链接及控制台变更域名校验的正规浏览器来源。上述 `X-Forwarded-*` 标头仍然是有效的路由元数据，但不能替代设置显式公开 URL。仅在 OmniRoute 客户端无法直接访问且你的代理剥离/重建了传入转发标头时，才启用 `OMNIROUTE_TRUST_PROXY`。 -### 3.3 Enable and Test +### 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） | diff --git a/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md b/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md index 209cb5d7bb86..927e0b8921ee 100644 --- a/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md +++ b/docs/i18n/zh-CN/docs/reference/API_REFERENCE.md @@ -1,24 +1,44 @@ -# API Reference (中文 (简体)) +--- +title: "API Reference" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- -🌐 **Languages:** 🇺🇸 [English](../../../../docs/API_REFERENCE.md) · 🇸🇦 [ar](../../ar/docs/API_REFERENCE.md) · 🇧🇬 [bg](../../bg/docs/API_REFERENCE.md) · 🇧🇩 [bn](../../bn/docs/API_REFERENCE.md) · 🇨🇿 [cs](../../cs/docs/API_REFERENCE.md) · 🇩🇰 [da](../../da/docs/API_REFERENCE.md) · 🇩🇪 [de](../../de/docs/API_REFERENCE.md) · 🇪🇸 [es](../../es/docs/API_REFERENCE.md) · 🇮🇷 [fa](../../fa/docs/API_REFERENCE.md) · 🇫🇮 [fi](../../fi/docs/API_REFERENCE.md) · 🇫🇷 [fr](../../fr/docs/API_REFERENCE.md) · 🇮🇳 [gu](../../gu/docs/API_REFERENCE.md) · 🇮🇱 [he](../../he/docs/API_REFERENCE.md) · 🇮🇳 [hi](../../hi/docs/API_REFERENCE.md) · 🇭🇺 [hu](../../hu/docs/API_REFERENCE.md) · 🇮🇩 [id](../../id/docs/API_REFERENCE.md) · 🇮🇹 [it](../../it/docs/API_REFERENCE.md) · 🇯🇵 [ja](../../ja/docs/API_REFERENCE.md) · 🇰🇷 [ko](../../ko/docs/API_REFERENCE.md) · 🇮🇳 [mr](../../mr/docs/API_REFERENCE.md) · 🇲🇾 [ms](../../ms/docs/API_REFERENCE.md) · 🇳🇱 [nl](../../nl/docs/API_REFERENCE.md) · 🇳🇴 [no](../../no/docs/API_REFERENCE.md) · 🇵🇭 [phi](../../phi/docs/API_REFERENCE.md) · 🇵🇱 [pl](../../pl/docs/API_REFERENCE.md) · 🇵🇹 [pt](../../pt/docs/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/API_REFERENCE.md) · 🇷🇴 [ro](../../ro/docs/API_REFERENCE.md) · 🇷🇺 [ru](../../ru/docs/API_REFERENCE.md) · 🇸🇰 [sk](../../sk/docs/API_REFERENCE.md) · 🇸🇪 [sv](../../sv/docs/API_REFERENCE.md) · 🇰🇪 [sw](../../sw/docs/API_REFERENCE.md) · 🇮🇳 [ta](../../ta/docs/API_REFERENCE.md) · 🇮🇳 [te](../../te/docs/API_REFERENCE.md) · 🇹🇭 [th](../../th/docs/API_REFERENCE.md) · 🇹🇷 [tr](../../tr/docs/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/API_REFERENCE.md) · 🇵🇰 [ur](../../ur/docs/API_REFERENCE.md) · 🇻🇳 [vi](../../vi/docs/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/API_REFERENCE.md) +# API 参考 ---- +🌐 **Languages:** 🇺🇸 [English](../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../../es/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../../fr/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../../it/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../../ru/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../../de/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../../in/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../../th/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../../uk-UA/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../../ar/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../../ja/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../../bg/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../../da/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../../fi/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../../he/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../../hu/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../../ko/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../../nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../../no/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../../ro/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../../pl/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../../sk/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../../sv/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../../phi/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../../cs/docs/reference/API_REFERENCE.md) -Complete reference for all OmniRoute API endpoints. +OmniRoute 所有 API 端点的完整参考。 --- -## Table of Contents +## 目录 - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) -- [Image Generation](#image-generation) -- [List Models](#list-models) -- [Compatibility Endpoints](#compatibility-endpoints) -- [Semantic Cache](#semantic-cache) -- [Dashboard & Management](#dashboard--management) -- [Request Processing](#request-processing) -- [Authentication](#authentication) +- [图像生成](#图像生成) +- [模型列表](#模型列表) +- [兼容性端点](#兼容性端点) +- [Files API](#files-api) +- [Batches API](#batches-api) +- [Search API](#search-api) +- [WebSocket 流式传输](#websocket-流式传输) +- [配额与问题报告](#配额与问题报告) +- [语义缓存](#语义缓存) +- [Dashboard 与管理](#dashboard-与管理) +- [Combo 管理](#combo-管理) +- [Webhooks](#webhooks) +- [注册 Key（自动管理）](#注册-key自动管理) +- [Agents 协议](#agents-协议) +- [管理代理](#管理代理) +- [容灾（扩展）](#容灾扩展) +- [Skills](#skills) +- [Memory](#memory) +- [MCP Server](#mcp-server) +- [A2A Server](#a2a-server) +- [Cloud、评估与诊断](#cloud评估与诊断) +- [请求处理](#请求处理) +- [认证](#认证) --- @@ -38,22 +58,56 @@ Content-Type: application/json } ``` -### Custom Headers +### 自定义请求头 + +| 请求头 | 方向 | 说明 | +| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | +| `X-OmniRoute-No-Cache` | 请求 | 设为 `true` 以绕过缓存 | +| `x-omniroute-no-memory` | 请求 | 设为 `true` 以跳过本请求的记忆 + 技能注入（与 no-cache 镜像；避免每次调用的 Token/成本开销） | +| `X-OmniRoute-Progress` | 请求 | 设为 `true` 以接收进度事件 | +| `X-Session-Id` | 请求 | 粘性会话 Key，用于外部会话绑定 | +| `x_session_id` | 请求 | 下划线变体同样接受（直接 HTTP） | +| `Idempotency-Key` | 请求 | 去重 Key（5 秒窗口） | +| `X-Request-Id` | 请求 | 备用去重 Key | +| `X-OmniRoute-Cache` | 响应 | 缓存 `HIT` 或 `MISS`（非流式） | +| `X-OmniRoute-Idempotent` | 响应 | 去重命中时为 `true` | +| `X-OmniRoute-Progress` | 响应 | 进度跟踪开启时为 `enabled` | +| `X-OmniRoute-Session-Id` | 响应 | OmniRoute 使用的有效会话 ID | +| `X-OmniRoute-Request-Id` | 响应 | 请求关联 ID（已知时） | +| `X-OmniRoute-Version` | 响应 | OmniRoute 构建版本号（始终返回） | +| `X-OmniRoute-Cost-Saved` | 响应 | 缓存命中时节省的 USD 金额（仅缓存命中时） | + +> Nginx 提示：如果依赖下划线请求头（如 `x_session_id`），请启用 `underscores_in_headers on;`。 + +> **成本遥测请求头：** 非流式成功响应还会携带 `X-OmniRoute-*` 成本遥测系列 — `X-OmniRoute-Response-Cost`（USD，固定 10 位小数；免费/无定价时为 `0.0000000000`）、`X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`、`X-OmniRoute-Model`、`X-OmniRoute-Provider`、`X-OmniRoute-Latency-Ms`、`X-OmniRoute-Cache-Hit` 以及 `X-OmniRoute-Fallback-Attempts`（仅在 >0 时返回），外加 `X-OmniRoute-Request-Id` 和 `X-OmniRoute-Version`。这些请求头由 chat completions、`/v1/responses`、`/v1/messages` **以及媒体端点**发出 — `/v1/embeddings`、`/v1/images/generations`、`/v1/audio/speech`、`/v1/audio/transcriptions`、`/v1/rerank`、`/v1/videos/generations`、`/v1/music/generations` 和 `/v1/moderations`（成本始终为 `0`）。媒体成本按模态计算（按图片、按秒、按字符、按搜索单元），仅在定价可用时计算，否则为 `0`（fail-open）。 + +> **缓存命中成本语义：** 语义缓存命中时（`X-OmniRoute-Cache-Hit: true`），不会发起上游调用，因此 `X-OmniRoute-Response-Cost` 为 `0.0000000000`（即命中的**增量**成本）。原始/本应产生的成本单独在 `X-OmniRoute-Cost-Saved` 中报告。计费消费者应累加 `X-OmniRoute-Response-Cost`（命中成本为零）；缓存分析可聚合 `X-OmniRoute-Cost-Saved`。 + +### `x-omniroute-compression` + +按请求覆盖压缩计划。优先级最高 — 高于路由 Combo 覆盖、活动配置、自动触发和面板 Default。取值： + +| 值 | 效果 | +| ------------- | -------------------------------------------------------- | +| `off` | 本请求不压缩。 | +| `default` | 面板生成的 Default 配置（忽略活动配置）。 | +| `engine:` | 启用时的单个引擎，如 `engine:rtk`。 | +| `` | 按名称匹配的命名 Combo（不区分大小写），其次按 id 匹配。 | + +说明： -| Header | Direction | Description | -| ------------------------ | --------- | ------------------------------------------------ | -| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | -| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | -| `X-Session-Id` | Request | Sticky session key for external session affinity | -| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | -| `Idempotency-Key` | Request | Dedup key (5s window) | -| `X-Request-Id` | Request | Alternative dedup key | -| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | -| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | -| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | -| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | +- 未知值将被忽略（绝不会因此拒绝请求）；解析回退到常规优先级顺序。 +- 若多个 Combo 共享同一名称，请传入 Combo **id** 以获得确定性匹配。 +- 名称为 `off` 或 `default` 的 Combo 无法按名称选择（这些关键词优先解释）；请通过 id 引用此类 Combo。 +- 主压缩开关是硬门控：全局禁用压缩时，本请求头无法启用。 -> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`. +应用的计划会回显在响应请求头中： + +``` +X-OmniRoute-Compression: ; source= +``` + +其中 `` 为以下之一：`request-header`、`routing-override`、`active-profile`、`auto-trigger`、`default` 或 `off`。 --- @@ -70,16 +124,16 @@ Content-Type: application/json } ``` -Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**. +可用服务商：Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、**OpenRouter**、**GitHub Models**。 ```bash -# List all embedding models +# 列出所有嵌入模型 GET /v1/embeddings ``` --- -## Image Generation +## 图像生成 ```bash POST /v1/images/generations @@ -93,42 +147,87 @@ Content-Type: application/json } ``` -Available providers: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local). +可用服务商：OpenAI (GPT Image 2)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI、Nebius (FLUX)、Hyperbolic、NanoBanana、**OpenRouter**、SD WebUI (本地)、ComfyUI (本地)。 ```bash -# List all image models +# 列出所有图像模型 GET /v1/images/generations ``` --- -## List Models +## 模型列表 ```bash GET /v1/models Authorization: Bearer your-api-key -→ Returns all chat, embedding, and image models + combos in OpenAI format +→ 以 OpenAI 格式返回所有 chat、embedding 和 image 模型 + Combo +``` + +### No-thinking 模型变体 + +对于支持 thinking 的 Claude 模型，`/v1/models` 还会列出一个 **no-thinking** 变体，其 id 前缀为 `claude-3-omniroute-no-thinking/`： + ``` +claude-3-omniroute-no-thinking// +``` + +选择此 id（例如在始终附加 `thinking` 块的 Claude Code 配置中）会解析回真实的 `/`，并抑制推理功能 — 在 `/v1/messages` 路径上使用 `thinking:{type:"disabled"}`，或在 `/v1/chat/completions` 路径上丢弃 `reasoning`/`reasoning_effort` 字段。此变体仅列出给支持 thinking **且**接受 `disabled` 的 Claude 系列模型（因此，仅支持 adaptive 模式且拒绝 `disabled` 的模型不会被列出）。管理员可通过 `ModelSpec.noThinkingAlias` 按模型强制开启或关闭此变体。 --- -## Compatibility Endpoints +## 兼容性端点 + +| 方法 | 路径 | 格式 | +| ----- | ------------------------------------------- | -------------------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI Images | +| POST | `/v1/images/edits` | OpenAI Images (编辑/修补) | +| POST | `/v1/videos/generations` | OpenAI 风格视频生成 | +| POST | `/v1/music/generations` | OpenAI 风格音乐生成 | +| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | +| POST | `/v1/audio/speech` | OpenAI TTS (返回音频内容) | +| POST | `/v1/rerank` | Cohere/Voyage 风格重排序 | +| POST | `/v1/moderations` | OpenAI Moderations | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | +| GET | `/api/v1/vscode/{token}/` | OpenAI 目录别名 | +| GET | `/api/v1/vscode/{token}/models` | OpenAI 模型别名 | +| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI Token 化别名 | +| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses Token 化别名 | +| POST | `/api/v1/vscode/{token}/api/chat` | Ollama Token 化别名 | +| GET | `/api/v1/vscode/{token}/api/tags` | Ollama 标签 Token 化别名 | + +所有 POST 路由遵循同一模式：`Bearer your-api-key` + 经 Zod 校验的 JSON 请求体（`v1RerankSchema`、`v1ModerationSchema`、`v1AudioSpeechSchema` 等，参见 `src/shared/validation/schemas.ts`）。Schema 校验失败返回 4xx。 + +对于无法附加 `Authorization: Bearer ...` 的客户端，OmniRoute 也接受通过 URL 传入 API Key：查询字符串兼容方式（`?token=...`、`?apiKey=...`、`?api_key=...`、`?key=...`）或下文介绍的专用 `/api/v1/vscode/{token}/...` 端点。 -| Method | Path | Format | -| ------ | --------------------------- | ---------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Anthropic | -| POST | `/v1/responses` | OpenAI Responses | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| GET | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Anthropic | -| GET | `/v1beta/models` | Gemini | -| POST | `/v1beta/models/{...path}` | Gemini generateContent | -| POST | `/v1/api/chat` | Ollama | +```bash +# 重排序 +POST /v1/rerank { "model": "cohere/rerank-3", "query": "...", "documents": ["..."] } + +# 内容审核 +POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } + +# TTS — 返回 audio/mpeg（或指定格式）内容 +POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } + +# 图像编辑 (multipart) +POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png + +# 视频 / 音乐生成 (带服务商前缀的模型 id) +POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } +POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } +``` -### Dedicated Provider Routes +### 专用服务商路由 ```bash POST /v1/providers/{provider}/chat/completions @@ -136,204 +235,340 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -The provider prefix is auto-added if missing. Mismatched models return `400`. +服务商前缀缺少时会自动添加。模型不匹配时返回 `400`。 --- -## Semantic Cache +## Files API -```bash -# Get cache stats -GET /api/cache/stats +OpenAI 兼容的文件端点，用于批量输入/输出和按用途上传文件。 -# Clear all caches -DELETE /api/cache/stats -``` +| 方法 | 路径 | 说明 | +| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------- | +| POST | `/v1/files` | 上传文件（multipart: `file`、`purpose`、`expires_after[anchor]`、`expires_after[seconds]`）— 最大 512 MiB | +| GET | `/v1/files` | 列出当前认证 API Key 下的文件 | +| GET | `/v1/files/[id]` | 查询文件元数据 | +| DELETE | `/v1/files/[id]` | 删除文件 | +| GET | `/v1/files/[id]/content` | 流式返回原始文件内容 | -Response example: +**认证：** Bearer API Key — 文件通过 `getApiKeyRequestScope` 按 API Key 隔离。 -```json -{ - "semanticCache": { - "memorySize": 42, - "memoryMaxSize": 500, - "dbSize": 128, - "hitRate": 0.65 - }, - "idempotency": { - "activeKeys": 3, - "windowMs": 5000 - } -} -``` +--- + +## Batches API + +OpenAI 兼容的批量处理。 + +| 方法 | 路径 | 说明 | +| ------ | --------------------------- | ------------------------------------------------------------------------------------------- | +| POST | `/v1/batches` | 创建批次 — 请求体经 `v1BatchCreateSchema` 校验（`input_file_id`、`endpoint`、`completion_window`） | +| GET | `/v1/batches` | 列出批次 | +| GET | `/v1/batches/[id]` | 查询批次状态 + `request_counts` | +| DELETE | `/v1/batches/[id]` | 删除已完成/已失败的批次 | +| POST | `/v1/batches/[id]/cancel` | 取消进行中的批次 | + +**认证：** Bearer API Key。批次按 API Key 隔离。 + +--- + +## Search API + +Web/搜索服务商抽象层（Tavily、Brave、Exa、Serper 等）。 + +| 方法 | 路径 | 说明 | +| ---- | ------------------------ | ------------------------------------------------------------------------------ | +| GET | `/v1/search` | 列出已配置的搜索服务商 + 能力信息 | +| POST | `/v1/search` | 执行搜索查询 — 请求体经 `v1SearchSchema` 校验，支持缓存/合并 | +| GET | `/v1/search/analytics` | 按服务商的命中/延迟/缓存统计数据 | + +**认证：** Bearer API Key（`extractApiKey` + `isValidApiKey`）。搜索策略通过 `enforceApiKeyPolicy` 强制执行。 --- -## Dashboard & Management +## WebSocket 流式传输 + +```bash +GET /v1/ws?handshake=1 +``` + +验证 WebSocket 升级握手并返回协议示例消息（`request`、`cancel`）。实际 WS 帧由内建的 WS 服务器在 Next.js 路由表之外处理。 + +**认证：** 握手期间使用 Bearer API Key。 -### Authentication +### 通过 WebSocket 的 Responses API（仅限 codex） -| Endpoint | Method | Description | -| ----------------------------- | ------- | --------------------- | -| `/api/auth/login` | POST | Login | -| `/api/auth/logout` | POST | Logout | -| `/api/settings/require-login` | GET/PUT | Toggle login required | +```bash +# 与 HTTP API 相同的主机:端口（默认 20128）；升级连接： +wscat -c "ws://localhost:20128/v1/responses?api_key=" +# (或： -H "Authorization: Bearer ") -### Provider Management +# 第一帧必须是 response.create： +{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } +``` -| Endpoint | Method | Description | -| ---------------------------- | --------------------- | ---------------------------------------------- | -| `/api/providers` | GET/POST | List / create providers | -| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | -| `/api/providers/[id]/test` | POST | Test provider connection | -| `/api/providers/[id]/models` | GET | List provider models | -| `/api/providers/validate` | POST | Validate provider config | -| `/api/provider-nodes*` | Various | Provider node management | -| `/api/provider-models` | GET/POST/PATCH/DELETE | Custom models (add, update, hide/show, delete) | +Responses-API-over-WebSocket 代理**仅绑定到 `codex`**（ChatGPT 后端）。它监听与 API/dashboard 相同的端口，路径包括 `/v1/responses`、`/responses` 和 `/api/v1/responses`。在收到首个 `response.create` 帧后，通过内部 `codex-responses-ws` 桥接进行认证和准备，选择一个 codex OAuth 连接，并通过 `wreq-js` 传输隧道化至 `wss://chatgpt.com/backend-api/codex/responses`。**非 codex 模型将被拒绝**（`codex_ws_provider_required`）。如需配额共享路由，使用 `model: "qtSd//codex/"`。实现在 `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`。 -### OAuth Flows +**认证：** 握手期间使用 Bearer API Key。内建的 HTTP 服务器（`server-ws.mjs`）必须是活动入口（当 `app/server-ws.mjs` 存在时默认为此入口）。 -| Endpoint | Method | Description | -| -------------------------------- | ------- | ----------------------- | -| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | +#### 模型 id：使用裸 ChatGPT id（不用 `codex/` 前缀） -### Routing & Config +OpenAI **Codex CLI** 在 `supports_websockets = true` 时会在客户端侧校验模型名称，并**拒绝带服务商前缀的 id**，如 `codex/gpt-5.5`（`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`）。请发送**裸** id（如 `gpt-5.5`）。OmniRoute 的桥接仅限 codex，因此会通过 `resolveCodexWsModelInfo` 将裸 id 重新解析为 codex 模型后隧道化到上游 — 尽管裸的 `gpt-5.5` 在 HTTP 下会路由到其他服务商。 -| Endpoint | Method | Description | -| --------------------- | -------- | ----------------------------- | -| `/api/models/alias` | GET/POST | Model aliases | -| `/api/models/catalog` | GET | All models by provider + type | -| `/api/combos*` | Various | Combo management | -| `/api/keys*` | Various | API key management | -| `/api/pricing` | GET | Model pricing | +#### 配置 OpenAI Codex CLI -### Usage & Analytics +通过在 `~/.codex/config.toml` 中添加支持 WebSocket 的自定义服务商，将 Codex CLI 指向 OmniRoute（使用单独的 `CODEX_HOME` 以避免覆盖已有配置）： -| Endpoint | Method | Description | -| --------------------------- | ------ | -------------------- | -| `/api/usage/history` | GET | Usage history | -| `/api/usage/logs` | GET | Usage logs | -| `/api/usage/request-logs` | GET | Request-level logs | -| `/api/usage/[connectionId]` | GET | Per-connection usage | +```toml +model = "gpt-5.5" # 裸 id — 不要用 "codex/gpt-5.5" +model_provider = "omniroute" -### Settings +[model_providers.omniroute] +name = "OmniRoute (WS)" +base_url = "http://localhost:20128/v1" # 不要加尾部斜杠；WS URL 由此派生（生产环境使用 https/wss） +wire_api = "responses" # 自 2026 年 2 月起仅支持该值 +supports_websockets = true # 启用 Responses-over-WS 传输 +env_key = "OMNIROUTE_API_KEY" # 持有 OmniRoute API Key（Bearer） +``` -| Endpoint | Method | Description | -| ------------------------------- | ------------- | ---------------------- | -| `/api/settings` | GET/PUT/PATCH | General settings | -| `/api/settings/proxy` | GET/PUT | Network proxy config | -| `/api/settings/proxy/test` | POST | Test proxy connection | -| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | -| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | -| `/api/settings/system-prompt` | GET/PUT | Global system prompt | +```bash +export OMNIROUTE_API_KEY=sk-... # 一个 OmniRoute API Key（若 REQUIRE_API_KEY=false 则任意 Key） +codex exec "Responda apenas: PONG" +``` -### Monitoring +CLI 将 `base_url + /responses` 升级为 WebSocket，OmniRoute 将其隧道化到选定的 codex OAuth 连接。已对本地服务器完成端到端验证：ChatGPT 返回 `codex.rate_limits` + `response.created` 并流式传输补全结果。 -| Endpoint | Method | Description | -| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | -| `/api/sessions` | GET | Active session tracking | -| `/api/rate-limits` | GET | Per-account rate limits | -| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | -| `/api/cache/stats` | GET/DELETE | Cache stats / clear | +--- -### Backup & Export/Import +## 配额与问题报告 -| Endpoint | Method | Description | -| --------------------------- | ------ | --------------------------------------- | -| `/api/db-backups` | GET | List available backups | -| `/api/db-backups` | PUT | Create a manual backup | -| `/api/db-backups` | POST | Restore from a specific backup | -| `/api/db-backups/export` | GET | Download database as .sqlite file | -| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | -| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | +| 方法 | 路径 | 说明 | +| ---- | --------------------- | ----------------------------------------------------------------------------- | +| GET | `/v1/quotas/check` | 在发放注册 Key 之前预先校验指定 `provider` + `accountId` 的配额 | +| POST | `/v1/issues/report` | 向 GitHub 报告配额/Key 发放失败（需要 `GITHUB_ISSUES_REPO` + Token） | -### Cloud Sync +**认证：** Bearer API Key（`isAuthenticated`）。 -| Endpoint | Method | Description | -| ---------------------- | ------- | --------------------- | -| `/api/sync/cloud` | Various | Cloud sync operations | -| `/api/sync/initialize` | POST | Initialize sync | -| `/api/cloud/*` | Various | Cloud management | +--- -### Tunnels +## 语义缓存 -| Endpoint | Method | Description | -| -------------------------- | ------ | ----------------------------------------------------------------------- | -| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | -| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | +```bash +# 获取缓存统计 +GET /api/cache/stats -### CLI Tools +# 清空所有缓存 +DELETE /api/cache/stats +``` -| Endpoint | Method | Description | -| ---------------------------------- | ------ | ------------------- | -| `/api/cli-tools/claude-settings` | GET | Claude CLI status | -| `/api/cli-tools/codex-settings` | GET | Codex CLI status | -| `/api/cli-tools/droid-settings` | GET | Droid CLI status | -| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | -| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | - -CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +响应示例： + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Dashboard 与管理 + +### 认证 + +| 端点 | 方法 | 说明 | +| ------------------------------- | ------- | ------------------ | +| `/api/auth/login` | POST | 登录 | +| `/api/auth/logout` | POST | 登出 | +| `/api/settings/require-login` | GET/PUT | 切换登录要求 | + +### 服务商管理 + +| 端点 | 方法 | 说明 | +| ---------------------------- | --------------------- | ------------------------------------ | +| `/api/providers` | GET/POST | 列出 / 创建服务商 | +| `/api/providers/[id]` | GET/PUT/DELETE | 管理服务商 | +| `/api/providers/[id]/test` | POST | 测试服务商连接 | +| `/api/providers/[id]/models` | GET | 列出服务商模型 | +| `/api/providers/validate` | POST | 校验服务商配置 | +| `/api/provider-nodes*` | Various | 服务商节点管理 | +| `/api/provider-models` | GET/POST/PATCH/DELETE | 自定义模型（添加、更新、隐藏/显示、删除） | + +### OAuth 流程 + +| 端点 | 方法 | 说明 | +| ---------------------------------- | ------- | ---------------------- | +| `/api/oauth/[provider]/[action]` | Various | 服务商特定的 OAuth | + +### 路由与配置 + +| 端点 | 方法 | 说明 | +| ------------------- | --------- | -------------------------------- | +| `/api/models/alias` | GET/POST | 模型别名 | +| `/api/models/catalog` | GET | 按服务商+类型列出所有模型 | +| `/api/combos*` | Various | Combo 管理 | +| `/api/keys*` | Various | API Key 管理 | +| `/api/pricing` | GET | 模型定价 | + +### 用量与分析 + +| 端点 | 方法 | 说明 | +| --------------------------- | --------------- | -------------------------------- | +| `/api/usage/history` | GET | 用量历史 | +| `/api/usage/logs` | GET | 用量日志 | +| `/api/usage/request-logs` | GET | 请求级日志 | +| `/api/usage/[connectionId]` | GET | 按连接的用量 | +| `/api/usage/token-limits` | GET/POST/DELETE | 按 API Key 的 Token 额度预算 | + +### 设置 + +| 端点 | 方法 | 说明 | +| ------------------------------------- | ------------- | -------------------------------------- | +| `/api/settings` | GET/PUT/PATCH | 通用设置 | +| `/api/settings/proxy` | GET/PUT | 网络代理配置 | +| `/api/settings/proxy/test` | POST | 测试代理连接 | +| `/api/settings/ip-filter` | GET/PUT | IP 允许/阻止列表 | +| `/api/settings/thinking-budget` | GET/PUT | 推理 Token 预算 | +| `/api/settings/system-prompt` | GET/PUT | 全局系统提示 | +| `/api/settings/compression` | GET/PUT | 全局压缩配置 | +| `/api/settings/purge-request-history` | POST | 清除请求日志行及本地调用日志产物 | + +### 上下文与压缩 + +| 端点 | 方法 | 说明 | +| ---------------------------------------- | -------------- | ----------------------------------------------------------------------- | +| `/api/compression/preview` | POST | 预览 off/lite/standard/aggressive/ultra/RTK/stacked 压缩效果 | +| `/api/compression/language-packs` | GET | 列出可用的 Caveman 语言包 | +| `/api/compression/rules` | GET | 列出 Caveman 规则元数据 | +| `/api/context/caveman/config` | GET/PUT | Caveman 特定设置别名 | +| `/api/context/rtk/config` | GET/PUT | RTK 特定设置，包括自定义过滤器和原始输出保留 | +| `/api/context/rtk/filters` | GET | RTK 过滤器目录和自定义过滤器诊断 | +| `/api/context/rtk/test` | POST | 对文本载荷运行 RTK 预览/测试 | +| `/api/context/rtk/raw-output/[id]` | GET | 按指针 id 读取保存的脱敏原始输出 | +| `/api/context/combos` | GET/POST | 压缩 Combo 列表/创建 | +| `/api/context/combos/[id]` | GET/PUT/DELETE | 压缩 Combo 详情/更新/删除 | +| `/api/context/combos/[id]/assignments` | GET/PUT | 将压缩 Combo 分配给路由 Combo | +| `/api/context/analytics` | GET | 压缩分析别名 | + +### 监控 + +| 端点 | 方法 | 说明 | +| -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- | +| `/api/sessions` | GET | 活跃会话跟踪 | +| `/api/rate-limits` | GET | 按账户的速率限制 | +| `/api/monitoring/health` | GET | 健康检查 + 服务商摘要（`catalogCount`、`configuredCount`、`activeCount`、`monitoredCount`） | +| `/api/cache/stats` | GET/DELETE | 缓存统计 / 清空 | + +### 备份与导出/导入 + +| 端点 | 方法 | 说明 | +| ----------------------------- | ---- | -------------------------------------- | +| `/api/db-backups` | GET | 列出可用的备份 | +| `/api/db-backups` | PUT | 创建手动备份 | +| `/api/db-backups` | POST | 从指定备份恢复 | +| `/api/db-backups/export` | GET | 下载数据库 .sqlite 文件 | +| `/api/db-backups/import` | POST | 上传 .sqlite 文件替换数据库 | +| `/api/db-backups/exportAll` | GET | 下载完整备份 .tar.gz 归档 | + +### 云同步 + +| 端点 | 方法 | 说明 | +| ---------------------- | ------- | ------------------ | +| `/api/sync/cloud` | Various | 云同步操作 | +| `/api/sync/initialize` | POST | 初始化同步 | +| `/api/cloud/*` | Various | 云管理 | + +### 隧道 + +| 端点 | 方法 | 说明 | +| ---------------------------- | ---- | ---------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | 读取 Cloudflare Quick Tunnel 安装/运行状态（供 dashboard） | +| `/api/tunnels/cloudflared` | POST | 启用或禁用 Cloudflare Quick Tunnel（`action=enable/disable`）| +| `/api/tunnels/ngrok` | GET | 读取 ngrok Tunnel 运行状态（供 dashboard） | +| `/api/tunnels/ngrok` | POST | 启用或禁用 ngrok Tunnel（`action=enable/disable`） | + +### CLI 工具 + +| 端点 | 方法 | 说明 | +| ------------------------------------ | ---- | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI 状态 | +| `/api/cli-tools/codex-settings` | GET | Codex CLI 状态 | +| `/api/cli-tools/droid-settings` | GET | Droid CLI 状态 | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI 状态 | +| `/api/cli-tools/runtime/[toolId]` | GET | 通用 CLI 运行状态 | + +CLI 响应包括：`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason`。 ### ACP Agents -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | +| 端点 | 方法 | 说明 | +| ----------------- | ------ | -------------------------------------------------------------- | +| `/api/acp/agents` | GET | 列出所有检测到的代理（内置 + 自定义）及其状态 | +| `/api/acp/agents` | POST | 添加自定义代理或刷新检测缓存 | +| `/api/acp/agents` | DELETE | 按 `id` 查询参数删除自定义代理 | + +GET 响应包含 `agents[]`（id、name、binary、version、installed、protocol、isCustom）和 `summary`（total、installed、notFound、builtIn、custom）。 -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). +### 容灾与速率限制 -### Resilience & Rate Limits +| 端点 | 方法 | 说明 | +| ----------------------------------- | --------- | ------------------------------------------------------------------------------------ | +| `/api/resilience` | GET/PATCH | 获取/更新请求队列、连接冷却、服务商熔断器及等待设置 | +| `/api/resilience/reset` | POST | 重置服务商熔断器 | +| `/api/resilience/model-cooldowns` | GET | 列出活跃的按(服务商, 连接, 模型)锁定的状态，按剩余时间排序 | +| `/api/resilience/model-cooldowns` | DELETE | 清除模型锁定 — 请求体 `{provider, model}` 或 `{all: true}` 以清除全部 | +| `/api/rate-limits` | GET | 按账户的速率限制状态 | +| `/api/rate-limit` | GET | 全局速率限制配置 | -| Endpoint | Method | Description | -| ----------------------- | --------- | ---------------------------------------------------------------------------------- | -| `/api/resilience` | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings | -| `/api/resilience/reset` | POST | Reset provider circuit breakers | -| `/api/rate-limits` | GET | Per-account rate limit status | -| `/api/rate-limit` | GET | Global rate limit configuration | +> 所有四个 `/api/resilience/*` 路由都需要**管理认证**（`requireManagementAuth`）。关于服务商熔断器 vs 连接冷却 vs 模型锁定的完整说明，参阅 [容灾（扩展）](#容灾扩展)。 ### Evals -| Endpoint | Method | Description | -| ------------ | -------- | --------------------------------- | -| `/api/evals` | GET/POST | List eval suites / run evaluation | +| 端点 | 方法 | 说明 | +| ------------ | --------- | -------------------------------- | +| `/api/evals` | GET/POST | 列出评估套件 / 运行评估 | ### Policies -| Endpoint | Method | Description | -| --------------- | --------------- | ----------------------- | -| `/api/policies` | GET/POST/DELETE | Manage routing policies | +| 端点 | 方法 | 说明 | +| --------------- | --------------- | -------------------- | +| `/api/policies` | GET/POST/DELETE | 管理路由策略 | ### Compliance -| Endpoint | Method | Description | -| --------------------------- | ------ | ----------------------------- | -| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | +| 端点 | 方法 | 说明 | +| ----------------------------- | ---- | -------------------------- | +| `/api/compliance/audit-log` | GET | 合规审计日志（最近 N 条） | -### v1beta (Gemini-Compatible) +### v1beta（Gemini 兼容） -| Endpoint | Method | Description | -| -------------------------- | ------ | --------------------------------- | -| `/v1beta/models` | GET | List models in Gemini format | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | +| 端点 | 方法 | 说明 | +| ---------------------------- | ---- | -------------------------------- | +| `/v1beta/models` | GET | 以 Gemini 格式列出模型 | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` 端点 | -These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. +这些端点镜像 Gemini 的 API 格式，供期望原生 Gemini SDK 兼容的客户端使用。 -### Internal / System APIs +### 内部 / 系统 API -| Endpoint | Method | Description | -| ------------------------ | ------ | ---------------------------------------------------- | -| `/api/init` | GET | Application initialization check (used on first run) | -| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | -| `/api/restart` | POST | Trigger graceful server restart | -| `/api/shutdown` | POST | Trigger graceful server shutdown | -| `/api/system/env/repair` | POST | Repair OAuth provider environment variables | -| `/api/system-info` | GET | Generate system diagnostics report | +| 端点 | 方法 | 说明 | +| -------------------------- | ---- | ------------------------------------------------------ | +| `/api/init` | GET | 应用初始化检查（用于首次运行） | +| `/api/tags` | GET | Ollama 兼容的模型标签（供 Ollama 客户端） | +| `/api/restart` | POST | 触发优雅重启 | +| `/api/shutdown` | POST | 触发优雅关闭 | +| `/api/system/env/repair` | POST | 修复 OAuth 服务商环境变量 | -> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. +> **注意：** 这些端点供系统内部使用或 Ollama 客户端兼容，终端用户通常无需调用。 -### OAuth Environment Repair _(v3.6.1+)_ +### OAuth 环境修复 _(v3.6.1+)_ ```bash POST /api/system/env/repair @@ -344,7 +579,7 @@ Content-Type: application/json } ``` -Repairs missing or corrupted OAuth environment variables for a specific provider. Returns: +修复特定服务商缺失或损坏的 OAuth 环境变量。返回： ```json { @@ -364,9 +599,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcribe audio files using Deepgram or AssemblyAI. +使用 Deepgram 或 AssemblyAI 转录音频文件。 -**Request:** +**请求：** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -375,7 +610,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Response:** +**响应：** ```json { @@ -386,36 +621,69 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. +**支持的服务商：** `deepgram/nova-3`、`assemblyai/best`。 -**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**支持的格式：** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 --- -## Ollama Compatibility +## Ollama 兼容性 -For clients that use Ollama's API format: +适用于使用 Ollama API 格式的客户端： ```bash -# Chat endpoint (Ollama format) +# Chat 端点（Ollama 格式） POST /v1/api/chat -# Model listing (Ollama format) +# 模型列表（Ollama 格式） GET /api/tags ``` -Requests are automatically translated between Ollama and internal formats. +请求在 Ollama 与内部格式之间自动转换。 + +## Token 化 VS Code / 无请求头别名 + +当集成无法注入 `Authorization` 请求头、需要将 API Key 嵌入 base URL 时，请使用这些别名。 + +```bash +# OpenAI 风格目录别名 +GET /api/v1/vscode/{token}/ +GET /api/v1/vscode/{token}/models + +# OpenAI 风格 chat 别名 +POST /api/v1/vscode/{token}/chat/completions +POST /api/v1/vscode/{token}/responses + +# Ollama 风格别名 +POST /api/v1/vscode/{token}/api/chat +GET /api/v1/vscode/{token}/api/tags +``` + +示例： + +```bash +curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models +curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}' +``` + +说明： + +- Token 化别名复用与 `/v1/*` 和 `/api/tags` 相同的处理器；响应格式保持一致。 +- 只要客户端支持自定义请求头，应优先使用 `Authorization: Bearer ...`。 +- 基于 URL 的 Token 可能出现在反向代理日志、浏览器历史和 OmniRoute 之外的遥测中。将其作为兼容选项而不是默认的认证方式。 --- ## Telemetry ```bash -# Get latency telemetry summary (p50/p95/p99 per provider) +# 获取延迟遥测摘要（按服务商的 p50/p95/p99） GET /api/telemetry/summary ``` -**Response:** +**响应：** ```json { @@ -428,42 +696,642 @@ GET /api/telemetry/summary --- -## Budget +## 预算 ```bash -# Get budget status for all API keys +# 获取所有 API Key 的预算状态 GET /api/usage/budget -# Set or update a budget +# 设置或更新预算 POST /api/usage/budget Content-Type: application/json { - "keyId": "key-123", - "limit": 50.00, - "period": "monthly" + "apiKeyId": "key-123", + "dailyLimitUsd": 5.00, + "weeklyLimitUsd": 30.00, + "monthlyLimitUsd": 100.00, + "warningThreshold": 0.8, + "resetInterval": "monthly" +} +``` + +> **Schema 说明**（`setBudgetSchema`）：`apiKeyId` 为必填字段；`dailyLimitUsd`、`weeklyLimitUsd` 或 `monthlyLimitUsd` 中至少有一项必须大于零。可选字段：`warningThreshold`（0–1）、`resetInterval`（`daily` | `weekly` | `monthly`）、`resetTime`（`HH:MM`）。旧的 `{keyId, limit, period}` 格式将返回 `400 Bad Request`。 + +## Token 限制 + +按 API Key 的 **Token 用量**预算（与上述基于 USD 的预算不同）。在请求路径上内联执行：当某个 Key 当前窗口用量达到限制时，请求将被拒绝并返回 `429 Too Many Requests`。限制可作用于特定 `model`、`provider` 或按 Key 全局（`global`）应用；当多个限制同时匹配时，取最严格的一个。 + +```bash +# 列出某个 Key 的 Token 限制（含实时窗口用量） +GET /api/usage/token-limits?apiKeyId=key-123 + +# 创建或更新 Token 限制 +POST /api/usage/token-limits +Content-Type: application/json + +{ + "apiKeyId": "key-123", + "scopeType": "model", + "scopeValue": "openai/gpt-4o", + "tokenLimit": 1000000, + "resetInterval": "monthly", + "enabled": true +} + +# 按 id 删除 Token 限制 +DELETE /api/usage/token-limits?id=tl-abc +``` + +> **Schema 说明**（`setTokenLimitSchema`）：`apiKeyId` 和 `scopeType`（`model` | `provider` | `global`）为必填字段。`scopeValue` 在 `scopeType` 非 `global` 时为必填（如 `model` 作用域填模型 id，`provider` 作用域填服务商 id）。`tokenLimit` 必须为正整数（从字符串强制转换）。可选字段：`id`（省略为创建，提供为更新）、`resetInterval`（`daily` | `weekly` | `monthly`，默认 `monthly`）、`resetTime`（`HH:MM`）、`enabled`（默认 `true`）。`GET` 响应会为每个限制附加 `tokensUsed`、`remaining`、`windowStart`、`periodStartAt` 和 `nextResetAt`。此为管理级端点（认证由 authz 管道集中执行）。 + +## 请求处理 + +1. 客户端向 `/v1/*` 发送请求 +2. 路由处理器调用 `handleChat`、`handleEmbedding`、`handleAudioTranscription` 或 `handleImageGeneration` +3. 解析模型（直接指定 服务商/模型 或别名/Combo） +4. 从本地数据库选择凭证，并过滤账户可用性 +5. 对于 chat：`handleChatCore` 检查语义/签名缓存并解析 Combo 压缩设置 +6. 启用时，在服务商转换前执行主动压缩（`lite`、Caveman、RTK 或 stacked） +7. 服务商执行器发送上游请求 +8. 响应转换回客户端格式（chat）或原样返回（embeddings/images/audio） +9. 记录用量、压缩分析和请求日志 +10. 错误时按 Combo 规则应用容灾 + +完整架构参考：[`ARCHITECTURE.md`](../../architecture/ARCHITECTURE.md) + +--- + +## Combo 管理 + +更高层的路由 Combo（已在 `/api/combos*` 下概述）也可以从模型 id 模式进行 1:1 映射，从而将 OpenAI 风格的模型 id 透明重定向到 Combo。 + +| 方法 | 路径 | 说明 | +| ------ | ---------------------------------- | ---------------------------------------------------------------------------- | +| GET | `/api/model-combo-mappings` | 列出所有模型→Combo 映射 | +| POST | `/api/model-combo-mappings` | 创建映射 — 请求体：`{pattern, comboId, priority?, enabled?, description?}` | +| GET | `/api/model-combo-mappings/[id]` | 查询单个映射 | +| PUT | `/api/model-combo-mappings/[id]` | 更新已有映射的字段 | +| DELETE | `/api/model-combo-mappings/[id]` | 删除映射 | + +**认证：** 管理会话/API Key（`requireManagementAuth`）。 + +--- + +## Webhooks + +OmniRoute 事件（请求完成、配额耗尽、Key 轮换等）的出站 Webhook 订阅。 + +| 方法 | 路径 | 说明 | +| ------ | --------------------------- | ------------------------------------------------------------- | +| GET | `/api/webhooks` | 列出 Webhook（secret 脱敏显示为 `...`） | +| POST | `/api/webhooks` | 创建 Webhook — 请求体：`{url, events?: ["*"], secret?, description?}` | +| GET | `/api/webhooks/[id]` | 查询 Webhook | +| PUT | `/api/webhooks/[id]` | 更新 url/events/secret/description | +| DELETE | `/api/webhooks/[id]` | 删除 Webhook | +| POST | `/api/webhooks/[id]/test` | 向 Webhook URL 发送测试载荷并返回投递状态 | + +**认证：** 管理会话/API Key（`requireManagementAuth`）。 + +--- + +## 注册 Key（自动管理） + +由自动 Key 管理子系统使用，用于向支持的服务商/账户发放和轮换 API Key，并设有每日/每小时配额。 + +| 方法 | 路径 | 说明 | +| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | `/api/v1/registered-keys` | 列出注册 Key（仅显示脱敏前缀） | +| POST | `/api/v1/registered-keys` | 发放新的注册 Key — 请求体：`{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`。**仅返回一次**原始 Key。配额拒绝时返回 `429`。 | +| GET | `/api/v1/registered-keys/[id]` | 查询注册 Key 的元数据（不含原始密钥） | +| DELETE | `/api/v1/registered-keys/[id]` | 吊销注册 Key | +| POST | `/api/v1/registered-keys/[id]/revoke` | 显式吊销端点（与 DELETE 效果相同） | + +**认证：** Bearer API Key（`isAuthenticated`）。另见 `/v1/quotas/check` 和 `/v1/issues/report`。 + +--- + +## Agents 协议 + +Cloud Agent 任务（Claude Code、Codex Cloud、OpenHands 等）代表 OmniRoute 用户远程执行。 + +| 方法 | 路径 | 说明 | +| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| GET | `/api/v1/agents/tasks` | 列出任务 — 可选 `?provider=`、`?status=`、`?limit=`（1–500，默认 50） | +| POST | `/api/v1/agents/tasks` | 创建任务 — 请求体经 `CreateCloudAgentTaskSchema` 校验（`providerId`、`prompt`、`source`、`options?`）。返回 `201` 和任务信封 | +| DELETE | `/api/v1/agents/tasks?id=...` | 删除任务 | +| GET | `/api/v1/agents/tasks/[id]` | 读取任务 — 当 `external_id` 已设置时，同步刷新来自上游云代理的状态 | +| POST | `/api/v1/agents/tasks/[id]` | 区分动作：`{action: "approve"}`、`{action: "message", message}` 或 `{action: "cancel"}` | +| DELETE | `/api/v1/agents/tasks/[id]` | 按 id 删除特定任务 | + +> **认证：** 所有方法都需要管理认证（`requireCloudAgentManagementAuth`）。v3.8.0 之前这些端点未做认证 — 参见 commit `588a0333` 了解重大变更。 + +```bash +# 创建 Claude Code 云任务 +curl -X POST http://localhost:20128/api/v1/agents/tasks \ + -H "Authorization: Bearer your-management-key" \ + -H "Content-Type: application/json" \ + -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}' +``` + +--- + +## 管理代理 + +可分配给服务商、账户或全局的出站 HTTP(S)/SOCKS 代理。 + +| 方法 | 路径 | 说明 | +| ------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | `/api/v1/management/proxies` | 列出代理（加 `?id=` 返回单个；加 `?id=&where_used=1` 返回分配图） | +| POST | `/api/v1/management/proxies` | 创建代理 — 请求体经 `createProxyRegistrySchema` 校验 | +| PATCH | `/api/v1/management/proxies` | 更新代理 — 请求体经 `updateProxyRegistrySchema` 校验（需要 `id`） | +| DELETE | `/api/v1/management/proxies?id=...&force=1` | 删除代理（使用 `force=1` 解除分配） | +| GET | `/api/v1/management/proxies/assignments` | 列出分配 — 可按 `proxy_id`、`scope`、`scope_id` 过滤；传入 `resolve_connection_id=` 解析连接的活跃代理 | +| PUT | `/api/v1/management/proxies/assignments` | 分配 — 请求体经 `proxyAssignmentSchema` 校验（`{scope, scopeId?, proxyId?}`）。清除调度器缓存 | +| PUT | `/api/v1/management/proxies/bulk-assign` | 批量分配 — 请求体经 `bulkProxyAssignmentSchema` 校验（`{scope, scopeIds[], proxyId?}`） | +| GET | `/api/v1/management/proxies/health?hours=24` | 指定窗口内的聚合代理健康状态（成功/失败次数、延迟） | + +**认证：** 所有路由均需管理会话/API Key（`requireManagementAuth`）。 + +> 任务描述中的 `POST /api/v1/management/proxies/[id]/assignments` 和 `POST /api/v1/management/proxies/[id]/health` 由上述扁平的 `/assignments` 和 `/health` 路由提供服务 — 代码库中不存在按 id 的子路由。 + +--- + +## 容灾（扩展） + +OmniRoute 公开三个独立的临时故障机制；以下管理端点允许管理员读取和覆盖它们： + +| 范围 | 状态存储 | 读取 | 重置 / 清除 | +| ------------------ | --------------------------------------------- | ----------------------------------------- | ------------------------------------------- | +| 服务商熔断器 | `domain_circuit_breakers` + 内存 | `/api/monitoring/health` | `POST /api/resilience/reset` | +| 连接冷却 | 服务商连接的 `rateLimitedUntil` | `/api/rate-limits`、`/api/providers/[id]` | （延迟自动恢复；通过服务商 PUT 清除） | +| 模型锁定 | 内存中的模型可用性注册表 | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | + +`PATCH /api/resilience` 通过 `providerBreaker.oauth` 和 `providerBreaker.apikey` 接受服务商熔断器覆盖。每种配置支持 `degradationThreshold`、`failureThreshold` 和 `resetTimeoutMs`；相同字段在 Dashboard → Settings → Resilience 中可见。 + +```bash +# 清除单个模型锁定 +curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ + -H "Cookie: auth_token=..." \ + -H "Content-Type: application/json" \ + -d '{"provider":"openai","model":"gpt-4o-mini"}' + +# 清除所有锁定 +curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ + -H "Cookie: auth_token=..." \ + -d '{"all":true}' +``` + +完整概念参考和熔断器默认值：参见 [`CLAUDE.md`](../../../CLAUDE.md) → "Resilience Runtime State"。 + +--- + +## Skills + +用于通过自定义可执行处理器扩展 OmniRoute 的技能框架，以及市场集成。 + +| 方法 | 路径 | 说明 | +| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| GET | `/api/skills` | 列出已安装的技能 — 可按 `?q=`、`?mode=on\|off\|auto`、`?source=skillsmp\|skillssh\|local` 过滤，支持分页 | +| GET | `/api/skills/[id]` | 查询单个技能 | +| PUT | `/api/skills/[id]` | 更新技能（name、description、mode、schema、handler、tags） | +| DELETE | `/api/skills/[id]` | 卸载技能 | +| POST | `/api/skills/install` | 从原始清单安装技能 — 请求体：`{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | +| GET | `/api/skills/executions` | 列出最近的技能执行记录（审计追踪，含 inputs/outputs/duration） | +| GET | `/api/skills/marketplace?q=...` | 从 SkillsMP 市场搜索/热门列表（需要 `skillsmpApiKey` 设置） | +| POST | `/api/skills/marketplace/install` | 从 SkillsMP 按 id 安装技能 | +| GET | `/api/skills/skillssh?q=&limit=` | 搜索 skills.sh 注册表 | +| POST | `/api/skills/skillssh/install` | 从 skills.sh 按 id 安装技能 | + +**认证：** 管理会话/API Key。市场搜索路由接受管理认证或 Bearer API Key（`isAuthenticated`）。 + +--- + +## Memory + +持久化的会话/事实记忆存储，按 API Key / 会话隔离。 + +| 方法 | 路径 | 说明 | +| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- | +| GET | `/api/memory` | 列出记忆 — `?apiKeyId=`、`?type=`、`?sessionId=`、`?q=`，支持 `offset/limit` 或 `page/limit` 分页 | +| POST | `/api/memory` | 创建记忆 — 请求体经 Zod 校验：`{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | +| GET | `/api/memory/[id]` | 查询单个记忆 | +| DELETE | `/api/memory/[id]` | 删除记忆 | +| GET | `/api/memory/health` | 记忆子系统健康状态（数据库连接、embeddings 后端、向量索引状态） | + +**认证：** 管理会话/API Key（`requireManagementAuth`）。`type` 枚举：`FACTUAL`、`EPISODIC`、`SEMANTIC`、`PROCEDURAL`（参见 `src/lib/memory/types.ts` 中的 `MemoryType`）。 + +--- + +## MCP Server + +OmniRoute 内置一个 Model Context Protocol 服务器，支持 3 种传输方式（stdio、SSE、streamable-http）及权限域划分的工具。以下 dashboard 端点用于读取状态/审计数据并代理 HTTP 传输。 + +| 方法 | 路径 | 说明 | +| ------ | ------------------------ | -------------------------------------------------------------------------------------------------- | +| GET | `/api/mcp/status` | 心跳、传输方式、在线状态、上次调用、Top 工具、24 小时成功率 | +| GET | `/api/mcp/tools` | MCP 工具列表，含 `name`、`description`、`scopes`、`phase`、`auditLevel`、`sourceEndpoints` | +| GET | `/api/mcp/sse` | 打开 SSE 传输的 SSE 流（MCP 禁用或传输方式不匹配时返回 `503`） | +| POST | `/api/mcp/sse` | 在 SSE 传输上发送 JSON-RPC 帧 | +| GET | `/api/mcp/stream` | 打开 Streamable HTTP 传输的 SSE 侧（服务端发起的消息） | +| POST | `/api/mcp/stream` | 在 Streamable HTTP 传输上发送 JSON-RPC 帧 | +| DELETE | `/api/mcp/stream` | 结束 Streamable HTTP 会话 | +| GET | `/api/mcp/audit` | 查询审计日志 — `?limit=`、`?offset=`、`?tool=`、`?success=true\|false`、`?apiKeyId=` | +| GET | `/api/mcp/audit/stats` | 聚合审计统计（总数、成功率、平均耗时、Top 工具） | + +**认证：** `sse`/`stream` 传输遵循 MCP 特定的认证面（Bearer API Key 需包含 `mcp` 权限域）；`status`/`tools`/`audit*` 路由可从 dashboard 读取（无需额外认证，只需能访问 dashboard 主机即可）。 + +> 两种 HTTP 传输均受 `settings.mcpEnabled` 和 `settings.mcpTransport` 限制 — 传输方式不匹配返回 `400`，MCP 禁用状态返回 `503`。 + +--- + +## A2A Server + +OmniRoute 暴露一个 A2A（Agent-to-Agent）JSON-RPC 2.0 端点，并提供 REST 包装以供检查/dashboard 使用。 + +### JSON-RPC + +```bash +POST /a2a +Authorization: Bearer your-api-key # 可选，除非设置了 OMNIROUTE_API_KEY +Content-Type: application/json + +{ + "jsonrpc": "2.0", + "id": 1, + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Route this coding task"}] + } } ``` -## Request Processing +支持的方法（均受 `settings.a2aEnabled` 限制）： + +| 方法 | 说明 | +| ---------------- | ---------------------------------------------------------- | +| `message/send` | 同步技能执行；返回 `{task, artifacts, metadata}` | +| `message/stream` | 相同技能集的流式 SSE 执行 | +| `tasks/get` | 按 `taskId` 获取任务 | +| `tasks/cancel` | 按 `taskId` 取消任务 | + +内置技能：`smart-routing`、`quota-management`、`provider-discovery`、`cost-analysis`、`health-report`。 + +### Agent Card + +```bash +GET /.well-known/agent.json +``` -1. Client sends request to `/v1/*` -2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` -3. Model is resolved (direct provider/model or alias/combo) -4. Credentials selected from local DB with account availability filtering -5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check -6. Provider executor sends upstream request -7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) -8. Usage/logging recorded -9. Fallback applies on errors according to combo rules +返回公开的 A2A agent card（名称、描述、能力、技能目录、认证方案）— 公开缓存 1 小时。无需认证。 -Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) +### REST 辅助方法 + +| 方法 | 路径 | 说明 | +| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | +| GET | `/api/a2a/status` | A2A 启用状态 + 任务统计 + 缓存的 agent card 摘要 | +| GET | `/api/a2a/tasks` | 列出任务 — `?state=submitted\|working\|completed\|failed\|cancelled`、`?skill=`、`?limit=`（≤200）、`?offset=` | +| POST | `/api/a2a/tasks` | （未作为 REST 辅助方法实现 — 通过 JSON-RPC `message/send` 创建） | +| GET | `/api/a2a/tasks/[id]` | 查询单个任务 | +| POST | `/api/a2a/tasks/[id]/cancel` | 取消任务 | + +**认证：** REST 辅助方法无需管理认证即可运行（dashboard 可读）；JSON-RPC `/a2a` 路由在配置后使用 Bearer `OMNIROUTE_API_KEY`。 + +--- + +## Cloud、评估与诊断 + +| 方法 | 路径 | 说明 | +| ---- | --------------------------------- | ---------------------------------------------------------------------------------------------- | +| POST | `/api/cloud/auth` | 验证 Bearer Key 并返回脱敏的服务商连接 + 模型别名，供云同步客户端使用 | +| POST | `/api/cloud/credentials/update` | 更新云同步服务商的加密凭证 | +| POST | `/api/cloud/model/resolve` | 使用本地路由表将逻辑模型 id 解析为具体的服务商/模型 | +| GET | `/api/cloud/models/alias` | 列出开放给云同步的模型别名 | +| GET | `/api/assess` | 读取最新诊断分类（按 服务商/模型） | +| POST | `/api/assess` | 运行诊断 — 请求体：`{scope: {type:"all"} \| {type:"provider", providerId} \| {type:"model", modelId}, trigger?}` | +| GET | `/api/evals` | 列出内置评估套件 + 最近运行记录 | +| POST | `/api/evals` | 触发评估运行 | +| POST | `/api/evals/suites` | 创建自定义评估套件 — 请求体经 `evalSuiteSaveSchema` 校验 | +| GET | `/api/evals/suites/[id]` | 查询自定义评估套件 | + +**认证：** `/api/cloud/auth` 直接验证 Bearer Key；其他 `/api/cloud/*`、`/api/evals/*` 和 `/api/assess` 路由需要管理会话/API Key。`/api/assess` POST 使用 `validateBody` 和区分联合的 scope schema。 + +--- + +## ACP（Agent Client Protocol）管理 + +ACP 代理作为子进程运行。以下端点管理 ACP 代理检测和自定义代理注册。 + +| 方法 | 路径 | 说明 | +| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------- | +| GET | `/api/acp/agents` | 列出所有已知的 CLI 代理（内置 + 自定义），含安装状态、版本、二进制文件 | +| POST | `/api/acp/agents` | 注册自定义 ACP 代理或刷新缓存 — 请求体：`{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` 或 `{action: "refresh"}` | +| DELETE | `/api/acp/agents` | 删除自定义 ACP 代理 — 查询参数：`?id=` | + +**响应示例**（`GET /api/acp/agents`）： + +```json +{ + "agents": [ + { + "id": "claude", + "name": "Claude Code CLI", + "binary": "claude", + "version": "1.0.45", + "installed": true, + "protocol": "stdio", + "providerAlias": "claude", + "isCustom": false + }, + { + "id": "my-custom-cli", + "name": "My Custom CLI", + "installed": false, + "protocol": "stdio", + "providerAlias": "my-provider", + "isCustom": true + } + ], + "cacheTtlMs": 60000, + "cacheAge": 1234 +} +``` + +**认证：** 需要管理会话（dashboard `auth_token` cookie）或管理权限域的 API Key。 + +完整细节参见 [ACP Framework](../frameworks/ACP.md)。 --- -## Authentication +## 分析与可观测性 + +用于监控路由、压缩和服务商多样性的实时分析端点。这些端点驱动 `/dashboard/analytics/*` 页面。 + +### 自动路由分析 + +| 方法 | 路径 | 说明 | +| ---- | -------------------------------------- | ---------------------------------------------------------------------------------------- | +| GET | `/api/analytics/auto-routing` | 聚合自动路由统计：总调用次数、策略分布、层级分布、Top 服务商 | +| GET | `/api/analytics/auto-routing?days=7` | 按时间窗口统计（默认 24 小时） | + +**响应示例**： + +```json +{ + "window": "24h", + "totalCalls": 1234, + "strategyBreakdown": { + "rules": 800, + "cost": 200, + "latency": 150, + "sla-aware": 50, + "lkgp": 34 + }, + "tierBreakdown": { + "ultra": 100, + "pro": 500, + "standard": 400, + "free": 234 + }, + "topProviders": [ + { "provider": "openai", "calls": 500, "avgLatencyMs": 850 }, + { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 } + ] +} +``` + +### 压缩分析 + +| 方法 | 路径 | 说明 | +| ---- | ------------------------------ | -------------------------------------------------------------------------------- | +| GET | `/api/analytics/compression` | 聚合压缩统计：Token 节省量、节省百分比、模式分布、引擎用量 | + +**响应示例**： + +```json +{ + "window": "24h", + "totalOriginalTokens": 5000000, + "totalCompressedTokens": 3500000, + "totalSavings": 1500000, + "savingsPct": 30.0, + "modeBreakdown": { + "lite": 400, + "standard": 600, + "aggressive": 100, + "ultra": 50, + "rtk": 84 + }, + "engineBreakdown": { + "caveman": 800, + "rtk": 434 + } +} +``` + +### 服务商多样性追踪 + +| 方法 | 路径 | 说明 | +| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------- | +| GET | `/api/analytics/diversity` | 基于 Shannon 熵的多样性跟踪：通过衡量服务商分布来防止单点故障 | + +**响应示例**： + +```json +{ + "window": "24h", + "shannonEntropy": 2.45, + "maxEntropy": 3.17, + "diversityRatio": 0.77, + "providerUsage": { + "openai": 0.4, + "anthropic": 0.25, + "google": 0.2, + "kiro": 0.15 + }, + "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"] +} +``` + +**认证：** 需要管理会话或管理权限域的 API Key。 + +--- + +## 管理操作 + +管理员专属端点，用于运营管理。 + +| 方法 | 路径 | 说明 | +| ---- | -------------------------- | --------------------------------------------------------------------------------------- | +| GET | `/api/admin/concurrency` | 读取当前并发限制（全局 + 按服务商） | +| POST | `/api/admin/concurrency` | 更新并发限制 — 请求体：`{global?: number, perProvider?: Record}` | + +**认证：** 需要含 admin 权限域的管理会话。 + +--- + +## CLI 工具管理 + +管理与 OmniRoute 集成的 CLI 工具（antigravity、chipotle、commandCode、devin-cli 等）。完整列表参见 [Provider Reference](./PROVIDER_REFERENCE.md)。 + +| 方法 | 路径 | 说明 | +| ---- | ----------------------------------------- | -------------------------------------------------------------------------------------------- | +| GET | `/api/cli-tools/all-statuses` | 所有 CLI 工具的状态（已安装、版本、上次检测） | +| GET | `/api/cli-tools/[id]/status` | 特定 CLI 工具的状态（id 可为：antigravity、chipotle、commandCode、devin-cli 等） | +| POST | `/api/cli-tools/apply` | 将 CLI 工具配置应用到服务商连接 | +| GET | `/api/cli-tools/backups` | 列出 CLI 工具配置备份 | +| POST | `/api/cli-tools/backups` | 创建所有 CLI 工具配置的备份 | +| POST | `/api/cli-tools/[id]/restore` | 从备份恢复 CLI 工具 | +| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM 代理状态（"antigravity-mitm" CLI 工具） | +| POST | `/api/cli-tools/antigravity-mitm/alias` | 配置 antigravity-mitm 别名 | + +**认证：** 需要管理会话。 + +--- + +## Agent Skills + +管理 AI 代理技能（类似 OpenAI 的自定义 GPT，但面向代理）。 + +| 方法 | 路径 | 说明 | +| ------ | ------------------------------ | ------------------------------------------------------------------------------ | +| GET | `/api/agent-skills` | 列出所有代理技能（内置 + 自定义） | +| GET | `/api/agent-skills/[id]` | 获取特定代理技能 | +| POST | `/api/agent-skills` | 创建自定义代理技能 — 请求体：`{name, description, prompt, model?, temperature?}` | +| PUT | `/api/agent-skills/[id]` | 更新自定义代理技能 | +| DELETE | `/api/agent-skills/[id]` | 删除自定义代理技能 | +| GET | `/api/agent-skills/[id]/raw` | 获取原始提示 + 元数据（不执行） | +| POST | `/api/agent-skills/generate` | AI 从自然语言描述生成新技能 | + +**认证：** 需要管理会话或管理权限域的 API Key。 + +--- + +## 缓存管理 + +管理语义缓存和推理缓存。 + +| 方法 | 路径 | 说明 | +| ------ | ------------------------ | ------------------------------------------------------------------------------------------------ | +| GET | `/api/cache` | 缓存概览：条目总数、命中率、磁盘占用 | +| GET | `/api/cache/entries` | 列出缓存条目（支持分页） | +| DELETE | `/api/cache/entries` | 删除缓存条目（按查询参数过滤） | +| GET | `/api/cache/stats` | 详细缓存统计（按服务商、按模型） | +| GET | `/api/cache/reasoning` | 推理缓存状态（用于推理回放） | +| DELETE | `/api/cache/reasoning` | 清除推理缓存 — 查询参数：`?toolCallId=`（单个）或 `?provider=

` 或不传参数（全部） | + +**认证：** 需要管理会话。 + +--- + +## 记忆系统 + +管理持久化记忆（FTS5 + 向量嵌入）。 + +| 方法 | 路径 | 说明 | +| ------ | ---------------------- | ------------------------------------------------------------------ | +| GET | `/api/memory` | 列出记忆条目（按作用域、类型、搜索查询过滤） | +| POST | `/api/memory` | 创建新记忆条目 — 请求体：`{scope, type, content, metadata?}` | +| GET | `/api/memory/[id]` | 获取特定记忆条目 | +| PUT | `/api/memory/[id]` | 更新记忆条目 | +| DELETE | `/api/memory/[id]` | 删除记忆条目 | +| GET | `/api/memory/search` | 搜索记忆（FTS5 + 向量） | +| POST | `/api/memory/clear` | 清除记忆条目（支持过滤器） | +| GET | `/api/memory/stats` | 记忆统计（总条目数、嵌入覆盖率等） | + +**认证：** 需要管理会话或管理权限域的 API Key。 + +--- + +## Webhooks + +管理事件 Webhook 订阅。 + +| 方法 | 路径 | 说明 | +| ------ | --------------------------------- | ------------------------------------------------------------------ | +| GET | `/api/webhooks` | 列出所有 Webhook 订阅 | +| POST | `/api/webhooks` | 创建 Webhook 订阅 — 请求体：`{url, events[], secret?, active?}` | +| GET | `/api/webhooks/[id]` | 获取特定 Webhook 订阅 | +| PUT | `/api/webhooks/[id]` | 更新 Webhook 订阅 | +| DELETE | `/api/webhooks/[id]` | 删除 Webhook 订阅 | +| GET | `/api/webhooks/events` | 列出所有可用的 Webhook 事件类型 | +| GET | `/api/webhooks/[id]/deliveries` | 列出 Webhook 投递历史（成功/失败日志） | +| POST | `/api/webhooks/[id]/test` | 向 Webhook 发送测试事件 | + +**认证：** 需要管理会话。 + +完整事件类型参见 [Webhooks Framework](../frameworks/WEBHOOKS.md)。 + +--- + +## Skills 框架 + +管理 Skills（代理扩展框架）。 + +| 方法 | 路径 | 说明 | +| ------ | -------------------------- | --------------------------------------------------------------------------------- | +| GET | `/api/skills` | 列出所有已安装的技能（内置 + 自定义） | +| POST | `/api/skills/install` | 从本地路径或 URL 安装技能 | +| DELETE | `/api/skills/[id]` | 卸载技能 | +| PUT | `/api/skills/[id]` | 启用或禁用技能 — 请求体：`{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | +| POST | `/api/skills/executions` | 执行技能 — 请求体：`{skillName, apiKeyId, input?, sessionId?}` | +| GET | `/api/skills/executions` | 列出所有技能的执行历史（可按 `?apiKeyId=` 过滤） | + +**认证：** 需要管理会话或管理权限域的 API Key。 + +完整细节参见 [Skills Framework](../frameworks/SKILLS.md)。 + +--- + +## 插件 + +管理 OmniRoute 插件（第三方扩展）。 + +| 方法 | 路径 | 说明 | +| ------ | ---------------------------------- | ------------------------------------ | +| GET | `/api/plugins` | 列出已安装的插件 | +| POST | `/api/plugins/install` | 从本地路径或 URL 安装插件 | +| DELETE | `/api/plugins/[name]` | 卸载插件 | +| POST | `/api/plugins/[name]/activate` | 激活插件 | +| POST | `/api/plugins/[name]/deactivate` | 停用插件 | +| GET | `/api/plugins/[name]/config` | 获取插件配置 | +| PUT | `/api/plugins/[name]/config` | 更新插件配置 | + +**认证：** 需要管理会话。 + +完整细节参见 [Plugins Framework](../frameworks/PLUGIN_SDK.md)。 + +--- + +## Shadow Routing + +服务商的 Shadow / A-B 对比**不是独立的 REST 面** — 通过 Combo 路由配置（参见 [Auto-Combo](../routing/AUTO-COMBO.md)）。按 Combo 的对比指标通过 `GET /api/combos/metrics` 提供。 + +--- + +## 安全护栏 + +检查运行时安全护栏（PII 检测、提示注入检测、视觉桥接）。安全护栏在每次请求中运行；按调用退出通过 `x-omniroute-disabled-guardrails` 请求头实现 — 没有持久化的启用/禁用地表。 + +| 方法 | 路径 | 说明 | +| ---- | ------------------------ | -------------------------------------------------------------------------------------- | +| GET | `/api/guardrails` | 列出已注册的安全护栏及其状态（名称 / 启用 / 优先级） | +| POST | `/api/guardrails/test` | 对示例输入干运行调用前管线 — 请求体：`{input, disabledGuardrails?}` | + +**认证：** 需要管理会话。 + +完整细节参见 [Security > Guardrails](../security/GUARDRAILS.md)。 + +--- + +--- + +## 认证 + +- Dashboard 路由（`/dashboard/*`）使用 `auth_token` cookie +- 登录使用保存的密码哈希；回退到 `INITIAL_PASSWORD` +- `requireLogin` 可通过 `/api/settings/require-login` 切换 +- `/v1/*` 路由在 `REQUIRE_API_KEY=true` 时可选要求 Bearer API Key -- Dashboard routes (`/dashboard/*`) use `auth_token` cookie -- Login uses saved password hash; fallback to `INITIAL_PASSWORD` -- `requireLogin` toggleable via `/api/settings/require-login` -- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` +> **重大变更（v3.8.0）** — `/api/v1/agents/tasks/*` 和冷却管理端点现在需要**管理认证**（dashboard `auth_token` cookie 或管理权限域的 API Key）。此前无需认证即可调用这些路由的客户端将收到 `401 Unauthorized`。参见 commit `588a0333`（`fix(auth): require management auth for agent and cooldown APIs`）。 diff --git a/docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md b/docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md index 70734552b698..e0eca4cc8c20 100644 --- a/docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md +++ b/docs/i18n/zh-CN/docs/reference/CLI-TOOLS.md @@ -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 页面中： -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. +| 页面 | 路由 | 概念 | 数量 | +| ---------------- | ------------------------ | --------------------------------------------------------------------------- | ------------ | +| **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`。 --- -## 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 → 响应 +``` + +**优势：** + +- 一个 API Key 管理所有工具 +- 在 dashboard 中追踪所有 CLI 的成本 +- 无需重新配置每个工具即可切换模型 +- 在本地和远程服务器（VPS、Docker、Akamai、Cloudflare Tunnel）均可使用 + +--- + +## 使用 `setup-*` 自动配置 + +无需手动编写每个工具的配置。OmniRoute 为每个支持的 CLI 提供对应的 `setup-*` 命令，该命令从运行中的 OmniRoute（本地或远程）读取**实时**模型目录并将工具的配置写入你的机器： + +```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 ``` -**Benefits:** +每个命令接受 `--remote --api-key `（针对远程 OmniRoute 配置本地工具）、`--dry-run`（预览不写入）和 `--port`。不支持模型自动发现的工具（Cline、Kilo、Roo、Goose、Qwen、Aider、Gemini）接受 `--model `（以及用于非交互式运行的 `--yes`）。启动器 `omniroute launch`（Claude Code）和 `omniroute launch-codex`（Codex）在注入正确的环境变量后启动 CLI，不写入任何配置。 + +> **完整参考：** 主表 — 每个命令写入的内容、所有标志、本地 vs 远程，以及哪些工具需要 `/v1` 后缀 — 在 **[CLI Integrations](../guides/CLI-INTEGRATIONS.md)** 中。 -- 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) +--- + +## 数据源 + +统一目录位于 `src/shared/constants/cliTools.ts`，定义为 `CLI_TOOLS: Record`。 + +每个条目包含以下字段（定义在 `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`）。 --- -## Supported Tools (Dashboard Source of Truth) +## 1. CLI Code's 目录（19 个工具） + +支持自定义 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"。 + +--- -The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. -Current list (v3.0.0-rc.16): +## 2. CLI Agents 目录（6 个工具） -| 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 | +出现在 `/dashboard/cli-agents` 中的自主代理： -### CLI fingerprint sync (Agents + Settings) +| 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 | -`/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 | +## 3. ACP Agents（/dashboard/acp-agents） -Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. +此页面（从 `/dashboard/agents` 重命名而来）显示 OmniRoute 可以通过 stdio/ACP 协议**启动**为后端执行引擎的 CLI。目录在 `src/lib/acp/registry.ts` 中单独维护，**不同于** `CLI_TOOLS`。 --- -## Step 1 — Get an OmniRoute API Key +## 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`。 -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 +--- -> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` +## 5. 批量检测 API + +所有工具检测通过单个端点聚合： + +**`GET /api/cli-tools/all-statuses`** + +- 认证：`requireCliToolsAuth(request)`（与其他 `/api/cli-tools/` 路由相同） +- 返回：`Record`（类型：`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; // 已脱敏，无堆栈跟踪 +} +``` --- -## Step 2 — Install CLI Tools +## 6. 新工具的 Settings 处理器 + +`configType: "custom"` 的新工具具有专用的 settings API 路由： -All npm-based tools require Node.js 18+: +| 路由 | 工具 | +| -------------------------------------------- | -------------------------------- | +| `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 配置 + +1. 访问 `http://localhost:20128/dashboard/cli-code` +2. 在网格中找到你的工具 +3. 点击卡片进入工具详情页 +4. 选择你的 API Key 和 base URL +5. 点击**应用配置**或复制手动配置片段 -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: +--- + +### 步骤 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://: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 通过环境变量或 `settings.json` 支持 OpenAI 兼容的 API 端点。 -Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`. +> Qwen OAuth 免费层已于 2026-04-15 停用。改为使用 OmniRoute 搭配 +> `bailian-coding-plan` / `alibaba` / `alibaba-cn` / `openrouter` / `anthropic` / +> `gemini` 服务商。 -**Option 1: Environment variables (`~/.qwen/.env`)** +**选项 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. +> 对于**远程服务器**，将 `localhost:20128` 替换为服务器的 IP 或域名。 -**Test:** `qwen "say hello"` +--- -### Cursor (Desktop App) +## 10. OmniRoute 内置 CLI -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. +`omniroute` 二进制文件提供服务端生命周期、设置、诊断和服务商管理的命令。入口点：`bin/omniroute.mjs`。 -Via GUI: **Settings → Models → OpenAI API Key** +```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 # 显示所有命令 +``` -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key +### 设置与初始化 ---- +```bash +omniroute setup # 交互式设置向导 +omniroute setup --non-interactive # CI/自动化模式（读取环境变量 + 标志） +omniroute setup --password '' # 直接设置管理员密码 +omniroute setup --add-provider \ + --provider openai \ + --api-key '' \ + --test-provider # 一步添加并测试服务商 +``` -## Dashboard Auto-Configuration +非交互式设置识别的环境变量： -The OmniRoute dashboard automates configuration for most tools: +| 变量 | 用途 | +| ------------------- | ----------------------------------------------------------- | +| `OMNIROUTE_API_KEY` | 服务商 API Key（通过 Commander `.env()` 绑定到 `--api-key`） | +| `DATA_DIR` | 覆盖 OmniRoute 数据目录 | -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually +其他所有非交互式输入通过标志传入，而非环境变量： +`--password`、`--provider`、`--provider-name`、`--provider-base-url`、`--default-model` +（参见上述 `omniroute setup` 选项）。 ---- +### 诊断 -## Built-in Agents: Droid & OpenClaw +```bash +omniroute doctor # 检查配置、数据库、端口、运行时、内存、存活状态 +omniroute doctor --json # 机器可读的 JSON +omniroute doctor --no-liveness # 跳过 HTTP 健康探测 +omniroute doctor --host 0.0.0.0 # 覆盖存活探测的主机 +omniroute doctor --liveness-url # 完全覆盖健康端点 URL +``` -**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. +doctor 运行以下检查：`Config`、`Database`、`Storage/encryption`、`Port availability`、`Node runtime`、`Native binary`（better-sqlite3）、`Memory` 和 `Server liveness`。任何检查为 `fail` 时以非零退出码退出。 -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required +### 服务商管理 ---- +```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 -## Available API Endpoints +omniroute providers list # 已配置的服务商连接 +omniroute providers list --json -| 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 | +omniroute providers test # 测试一个已配置的连接 +omniroute providers test-all # 测试所有活跃连接 +omniroute providers validate # 仅本地结构校验 +``` ---- +> `providers available` 读取 OmniRoute 目录；`providers list/test/test-all/validate` +> 直接读取本地 SQLite 数据库，不需要服务器运行。 -## 故障排除 +### 恢复与重置 -| 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 ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | +```bash +omniroute reset-password # 重置管理员密码（旧别名仍然可用） +omniroute reset-encrypted-columns # 显示加密凭证重置的警告 + 干运行 +omniroute reset-encrypted-columns --force # 实际在 SQLite 中将加密凭证设为 null +``` ---- +### 其他子命令 -## Quick Setup Script (One Command) +以下命令假定 OmniRoute 服务器正在运行（另有说明除外）： ```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" +omniroute status # 全面的运行时状态 +omniroute logs # 流式输出请求日志（--json、--search、--follow） +omniroute config show # 显示当前配置 -npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code +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 -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash +omniroute backup # 快照配置 + 数据库 +omniroute restore # 从之前的快照恢复 -# Write configs -mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue +omniroute health # 详细健康状态（熔断器、缓存、内存） +omniroute quota # 服务商配额用量 +omniroute cache # 缓存状态 +omniroute cache clear # 清除语义 + 签名缓存 -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 +omniroute mcp status | restart # MCP 服务器状态 / 重启 +omniroute a2a status | card # A2A 服务器状态 / agent card + +omniroute tunnel list | create | stop # 管理隧道（cloudflare/tailscale/ngrok） +omniroute env show | get | set # 检查 / 设置环境变量（临时） -source ~/.bashrc -echo "✅ All CLIs installed and configured for OmniRoute" +omniroute test # 服务商连通性冒烟测试 +omniroute update # 检查更新 +omniroute completion # 生成 shell 补全 ``` + +### 通用标志 + +| 标志 | 说明 | +| ------------------- | ------------------------------------------------------ | +| `--no-open` | 启动时不自动打开浏览器 | +| `--port ` | 覆盖 API 端口（默认 20128） | +| `--mcp` | 以 MCP 服务器通过 stdio 运行（供 IDE 使用） | +| `--non-interactive` | CI 模式（无交互提示；从 env/flags 读取） | +| `--json` | 机器可读的 JSON 输出（doctor、providers 等） | +| `--help`、`-h` | 显示命令特定的帮助 | +| `--version`、`-v` | 输出版本号 | + +--- + +## 可用 API 端点 + +| 端点 | 说明 | 用途 | +| ---------------------------- | ------------------------------ | -------------------------- | +| `/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 | + +可直接粘贴的示例（使用 Token 化 OmniRoute URL）： + +```txt +Token 示例：sk-a3ab3c080beaee3a-69f4a4-070d71af + +标准 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 +``` + +--- + +## 故障排除 + +| 错误 | 原因 | 修复方法 | +| --------------------------------------------- | ------------------------ | ------------------------------------------------- | +| `Connection refused` | OmniRoute 未运行 | `omniroute serve` | +| `401 Unauthorized` | API Key 错误 | 在 `/dashboard/api-manager` 中检查 | +| `No combo configured` | 无活跃的路由 Combo | 在 `/dashboard/combos` 中设置 | +| CLI 显示 "not installed" | 二进制文件不在 PATH 中 | 检查 `which ` | +| Dashboard 安装后显示 "not detected" | 缓存过期 | 点击 dashboard 中的 "⟳ 刷新检测" | +| 旧链接 `/dashboard/cli-tools` | v3.8.6 之前的书签 | 自动重定向到 `/dashboard/cli-code`（308） | +| 旧链接 `/dashboard/agents` | v3.8.6 之前的书签 | 自动重定向到 `/dashboard/acp-agents`（308） | diff --git a/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md b/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md index 53908cfe622b..9dd8f61069fe 100644 --- a/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md +++ b/docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md @@ -1,500 +1,708 @@ -# Environment Variables Reference (中文 (简体)) - -🌐 **Languages:** 🇺🇸 [English](../../../../docs/ENVIRONMENT.md) · 🇸🇦 [ar](../../ar/docs/ENVIRONMENT.md) · 🇧🇬 [bg](../../bg/docs/ENVIRONMENT.md) · 🇧🇩 [bn](../../bn/docs/ENVIRONMENT.md) · 🇨🇿 [cs](../../cs/docs/ENVIRONMENT.md) · 🇩🇰 [da](../../da/docs/ENVIRONMENT.md) · 🇩🇪 [de](../../de/docs/ENVIRONMENT.md) · 🇪🇸 [es](../../es/docs/ENVIRONMENT.md) · 🇮🇷 [fa](../../fa/docs/ENVIRONMENT.md) · 🇫🇮 [fi](../../fi/docs/ENVIRONMENT.md) · 🇫🇷 [fr](../../fr/docs/ENVIRONMENT.md) · 🇮🇳 [gu](../../gu/docs/ENVIRONMENT.md) · 🇮🇱 [he](../../he/docs/ENVIRONMENT.md) · 🇮🇳 [hi](../../hi/docs/ENVIRONMENT.md) · 🇭🇺 [hu](../../hu/docs/ENVIRONMENT.md) · 🇮🇩 [id](../../id/docs/ENVIRONMENT.md) · 🇮🇹 [it](../../it/docs/ENVIRONMENT.md) · 🇯🇵 [ja](../../ja/docs/ENVIRONMENT.md) · 🇰🇷 [ko](../../ko/docs/ENVIRONMENT.md) · 🇮🇳 [mr](../../mr/docs/ENVIRONMENT.md) · 🇲🇾 [ms](../../ms/docs/ENVIRONMENT.md) · 🇳🇱 [nl](../../nl/docs/ENVIRONMENT.md) · 🇳🇴 [no](../../no/docs/ENVIRONMENT.md) · 🇵🇭 [phi](../../phi/docs/ENVIRONMENT.md) · 🇵🇱 [pl](../../pl/docs/ENVIRONMENT.md) · 🇵🇹 [pt](../../pt/docs/ENVIRONMENT.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ENVIRONMENT.md) · 🇷🇴 [ro](../../ro/docs/ENVIRONMENT.md) · 🇷🇺 [ru](../../ru/docs/ENVIRONMENT.md) · 🇸🇰 [sk](../../sk/docs/ENVIRONMENT.md) · 🇸🇪 [sv](../../sv/docs/ENVIRONMENT.md) · 🇰🇪 [sw](../../sw/docs/ENVIRONMENT.md) · 🇮🇳 [ta](../../ta/docs/ENVIRONMENT.md) · 🇮🇳 [te](../../te/docs/ENVIRONMENT.md) · 🇹🇭 [th](../../th/docs/ENVIRONMENT.md) · 🇹🇷 [tr](../../tr/docs/ENVIRONMENT.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ENVIRONMENT.md) · 🇵🇰 [ur](../../ur/docs/ENVIRONMENT.md) · 🇻🇳 [vi](../../vi/docs/ENVIRONMENT.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ENVIRONMENT.md) +# 环境变量参考 (中文 (简体)) +--- +title: "Environment Variables Reference" +version: 3.8.40 +lastUpdated: 2026-06-28 --- -> Complete reference for every environment variable recognized by OmniRoute. -> For a quick-start template, see [`.env.example`](../.env.example). +🌐 **语言：** 🇺🇸 [English](../../../../docs/reference/ENVIRONMENT.md) · 🇸🇦 [العربية](../../ar/docs/reference/ENVIRONMENT.md) · 🇧🇬 [Български](../../bg/docs/reference/ENVIRONMENT.md) · 🇧🇩 [বাংলা](../../bn/docs/reference/ENVIRONMENT.md) · 🇨🇿 [Čeština](../../cs/docs/reference/ENVIRONMENT.md) · 🇩🇰 [Dansk](../../da/docs/reference/ENVIRONMENT.md) · 🇩🇪 [Deutsch](../../de/docs/reference/ENVIRONMENT.md) · 🇪🇸 [Español](../../es/docs/reference/ENVIRONMENT.md) · 🇮🇷 [فارسی](../../fa/docs/reference/ENVIRONMENT.md) · 🇫🇮 [Suomi](../../fi/docs/reference/ENVIRONMENT.md) · 🇫🇷 [Français](../../fr/docs/reference/ENVIRONMENT.md) · 🇮🇳 [ગુજરાતી](../../gu/docs/reference/ENVIRONMENT.md) · 🇮🇱 [עברית](../../he/docs/reference/ENVIRONMENT.md) · 🇮🇳 [हिन्दी](../../hi/docs/reference/ENVIRONMENT.md) · 🇭🇺 [Magyar](../../hu/docs/reference/ENVIRONMENT.md) · 🇮🇩 [Indonesia](../../id/docs/reference/ENVIRONMENT.md) · 🇮🇹 [Italiano](../../it/docs/reference/ENVIRONMENT.md) · 🇯🇵 [日本語](../../ja/docs/reference/ENVIRONMENT.md) · 🇰🇷 [한국어](../../ko/docs/reference/ENVIRONMENT.md) · 🇮🇳 [मराठी](../../mr/docs/reference/ENVIRONMENT.md) · 🇲🇾 [Bahasa Melayu](../../ms/docs/reference/ENVIRONMENT.md) · 🇳🇱 [Nederlands](../../nl/docs/reference/ENVIRONMENT.md) · 🇳🇴 [Norsk](../../no/docs/reference/ENVIRONMENT.md) · 🇵🇭 [Filipino](../../phi/docs/reference/ENVIRONMENT.md) · 🇵🇱 [Polski](../../pl/docs/reference/ENVIRONMENT.md) · 🇵🇹 [Português](../../pt/docs/reference/ENVIRONMENT.md) · 🇧🇷 [Português Brasileiro](../../pt-BR/docs/reference/ENVIRONMENT.md) · 🇷🇴 [Română](../../ro/docs/reference/ENVIRONMENT.md) · 🇷🇺 [Русский](../../ru/docs/reference/ENVIRONMENT.md) · 🇸🇰 [Slovenčina](../../sk/docs/reference/ENVIRONMENT.md) · 🇸🇪 [Svenska](../../sv/docs/reference/ENVIRONMENT.md) · 🇰🇪 [Kiswahili](../../sw/docs/reference/ENVIRONMENT.md) · 🇮🇳 [தமிழ்](../../ta/docs/reference/ENVIRONMENT.md) · 🇮🇳 [తెలుగు](../../te/docs/reference/ENVIRONMENT.md) · 🇹🇭 [ไทย](../../th/docs/reference/ENVIRONMENT.md) · 🇹🇷 [Türkçe](../../tr/docs/reference/ENVIRONMENT.md) · 🇺🇦 [Українська](../../uk-UA/docs/reference/ENVIRONMENT.md) · 🇵🇰 [اردو](../../ur/docs/reference/ENVIRONMENT.md) · 🇻🇳 [Tiếng Việt](../../vi/docs/reference/ENVIRONMENT.md) --- -## Table of Contents +> OmniRoute 全部环境变量的完整参考。如需快速上手模板，请参阅 [`.env.example`](../../../.env.example)。 + +> [!IMPORTANT] +> 本文档中记录的每个变量也必须出现在 `.env.example` 中， +> 反之亦然。`npm run check:env-doc-sync` 将在提交时和 CI 中强制执行此规则。 +> 如需有意省略某个变量，请将其添加到 `scripts/check/check-env-doc-sync.mjs` +> 中的 allowlist 内。 + +--- -- [1. Required Secrets](#1-required-secrets) -- [2. Storage & Database](#2-storage--database) -- [3. Network & Ports](#3-network--ports) -- [4. Security & Authentication](#4-security--authentication) -- [5. Input Sanitization & PII Protection](#5-input-sanitization--pii-protection) -- [6. Tool & Routing Policies](#6-tool--routing-policies) -- [7. URLs & Cloud Sync](#7-urls--cloud-sync) -- [8. Outbound Proxy](#8-outbound-proxy) -- [9. CLI Tool Integration](#9-cli-tool-integration) -- [10. Internal Agent & MCP Integrations](#10-internal-agent--mcp-integrations) -- [11. OAuth Provider Credentials](#11-oauth-provider-credentials) -- [12. Provider User-Agent Overrides](#12-provider-user-agent-overrides) -- [13. CLI Fingerprint Compatibility](#13-cli-fingerprint-compatibility) -- [14. API Key Providers](#14-api-key-providers) -- [15. Timeout Settings](#15-timeout-settings) -- [16. Logging](#16-logging) -- [17. Memory Optimization](#17-memory-optimization) -- [18. Pricing Sync](#18-pricing-sync) -- [19. Model Sync (Dev)](#19-model-sync-dev) -- [20. Provider-Specific Settings](#20-provider-specific-settings) -- [21. Proxy Health](#21-proxy-health) -- [22. Debugging](#22-debugging) -- [23. GitHub Integration](#23-github-integration) -- [Deployment Scenarios](#deployment-scenarios) -- [Audit: Removed / Dead Variables](#audit-removed--dead-variables) +## 目录 + +- [1. 必需的密钥](#1-必需的密钥) +- [2. 存储与数据库](#2-存储与数据库) +- [3. 网络与端口](#3-网络与端口) +- [4. 安全与认证](#4-安全与认证) +- [5. 输入净化与 PII 保护](#5-输入净化与-pii-保护) +- [6. 工具与路由策略](#6-工具与路由策略) +- [7. URL 与云同步](#7-url-与云同步) +- [8. 出口代理](#8-出口代理) +- [9. CLI 工具集成](#9-cli-工具集成) +- [10. 内部 Agent 与 MCP 集成](#10-内部-agent-与-mcp-集成) +- [11. OAuth 服务商凭证](#11-oauth-服务商凭证) +- [12. 服务商 User-Agent 覆盖](#12-服务商-user-agent-覆盖) +- [13. CLI 指纹兼容](#13-cli-指纹兼容) +- [14. API Key 服务商](#14-api-key-服务商) +- [15. 超时设置](#15-超时设置) +- [16. 日志](#16-日志) +- [17. 内存优化](#17-内存优化) +- [18. 价格同步](#18-价格同步) +- [19. 模型同步（开发）](#19-模型同步开发) +- [20. 服务商特定设置](#20-服务商特定设置) +- [21. 代理健康](#21-代理健康) +- [22. 调试](#22-调试) +- [23. GitHub 集成](#23-github-集成) +- [24. 技能沙箱（v3.8.0+）](#24-技能沙箱v380) +- [部署场景](#部署场景) +- [审计：已移除/废弃的变量](#审计已移除废弃的变量) --- -## 1. Required Secrets +## 1. 必需的密钥 -These **must** be set before the first run. Without them, the application will either refuse to start or operate with insecure defaults. +这些变量 **必须** 在首次运行前设置。不设置则应用将拒绝启动，或使用不安全的默认值运行。 -| Variable | Required | Default | Source File | Description | -| ------------------ | -------- | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `JWT_SECRET` | **Yes** | _(none)_ | `src/lib/auth` | Signs/verifies all dashboard session cookies (JWT). Generate with `openssl rand -base64 48`. | -| `API_KEY_SECRET` | **Yes** | _(none)_ | `src/lib/db/apiKeys.ts` | AES encryption key for API key values at rest in SQLite. Generate with `openssl rand -hex 32`. | -| `INITIAL_PASSWORD` | **Yes** | `123456` | Bootstrap script | Sets the initial admin dashboard password. **Change before first use.** After login, change via Dashboard → Settings → Security. | +| 变量 | 必需 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | --- | +| `JWT_SECRET` | **是** | _(无)_ | `src/lib/auth` | 签名/校验所有 Dashboard 会话 Cookie（JWT）。使用 `openssl rand -base64 48` 生成。 | +| `API_KEY_SECRET` | **是** | _(无)_ | `src/lib/db/apiKeys.ts` | SQLite 中 API key 静态加密的 AES 密钥。使用 `openssl rand -hex 32` 生成。 | +| `INITIAL_PASSWORD` | **是** | `CHANGEME` | 引导脚本 | 设置初始管理员 Dashboard 密码（与 `.env.example` 默认值一致 — 故意保持不安全以强制更换）。**首次使用前请修改。** 登录后，请通过 Dashboard → Settings → Security 修改。 | +| `OMNIROUTE_WS_BRIDGE_SECRET` | **是**（生产环境） | _(未设置)_ | `src/app/api/internal/codex-responses-ws/route.ts` | 内部 Codex Responses WebSocket 桥接的共享密钥。用于认证 Electron/浏览器 WS 中继与 OmniRoute 之间的桥接请求。⚠️ **生产环境必须设置 — 未设置时所有 WS 桥接请求都会被拒绝。** 使用 `openssl rand -base64 32` 生成。 | +| `OMNIROUTE_PEER_STAMP_TOKEN` | 否（自动） | _(每次启动自动生成)_ | `src/server/authz/policies/management.ts` | 每个进程的密钥，用于证明可信的对等 IP 戳记来自 OmniRoute 自身的 HTTP 服务器（`scripts/dev/peer-stamp.mjs`）。authz 中间件仅在戳记携带此 Token 时才信任请求的本地性（对 LOCAL_ONLY 路由进行 loopback/LAN 门控）。每次启动自动生成 — 保持未设置；仅在必须共享戳记的多进程场景下固定此值。 | -### Generation Commands +### 生成命令 ```bash -# Generate all three secrets at once: +# 一次性生成全部四个密钥： echo "JWT_SECRET=$(openssl rand -base64 48)" echo "API_KEY_SECRET=$(openssl rand -hex 32)" echo "INITIAL_PASSWORD=$(openssl rand -base64 16)" +echo "OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -base64 32)" ``` > [!CAUTION] -> Never commit `.env` files with real secrets to version control. The `.gitignore` already excludes `.env`, but verify before pushing. +> 切勿将包含真实密钥的 `.env` 文件提交到版本控制。`.gitignore` 已排除 `.env`，但推送前请确认。 --- -## 2. Storage & Database - -OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These variables control data location, encryption, and lifecycle. - -| Variable | Default | Source File | Description | -| -------------------------------- | -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | Root directory for SQLite DB, backups, and data files. Override for Docker volumes or custom paths. | -| `STORAGE_ENCRYPTION_KEY` | _(empty = disabled)_ | `src/lib/db/encryption.ts` | AES key for full SQLite database encryption at rest. Generate with `openssl rand -hex 32`. | -| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/bootstrap-env.mjs`, `electron/main.js` | Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. | -| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | When `true`, skips the automatic database backup that runs before migrations on every startup. | -| `OMNIROUTE_CRYPT_KEY` | _(unset)_ | `src/lib/db/encryption.ts` | **Legacy alias** for `STORAGE_ENCRYPTION_KEY`. Accepted as a fallback when the primary variable is absent. | -| `OMNIROUTE_API_KEY_BASE64` | _(unset)_ | `src/lib/db/encryption.ts` | **Legacy alias** (Base64-encoded form) accepted as a fallback. Decoded automatically before use. | - -### Scenarios - -| Scenario | Configuration | -| --------------------- | -------------------------------------------------------------------------------- | -| **Local development** | Leave all defaults. DB lives at `~/.omniroute/omniroute.db`. | -| **Docker** | `DATA_DIR=/data` + mount a volume at `/data`. | -| **Encrypted at rest** | Set `STORAGE_ENCRYPTION_KEY` + keep backups of the key! Losing it = losing data. | -| **CI/Testing** | `DATA_DIR=/tmp/omniroute-test` — ephemeral, no encryption needed. | +## 2. 存储与数据库 + +OmniRoute 使用 **SQLite**（通过 `better-sqlite3`）进行所有持久化存储。以下变量控制数据位置、加密和生命周期。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | SQLite 数据库、备份和数据文件的根目录。在 Docker 卷或自定义路径中可覆盖。 | +| `STORAGE_ENCRYPTION_KEY` | _(空 = 禁用)_ | `src/lib/db/encryption.ts` | 用于 SQLite 数据库静态全量加密的 AES 密钥。使用 `openssl rand -hex 32` 生成。 | +| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | 加密密钥的版本标签。进行密钥轮换时递增，以支持解密旧备份。 | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | 设为 `true` 时，跳过每次启动前迁移时运行的自动数据库备份。 | +| `OMNIROUTE_CRYPT_KEY` | _(未设置)_ | `src/lib/db/encryption.ts` | `STORAGE_ENCRYPTION_KEY` 的**旧版别名**。主变量缺失时作为回退被接受。 | +| `OMNIROUTE_API_KEY_BASE64` | _(未设置)_ | `src/lib/db/encryption.ts` | **旧版别名**（Base64 编码形式），作为回退被接受。使用前自动解码。 | +| `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` | _(未设置)_ | `src/lib/db/core.ts` | 覆盖定期 SQLite 健康检查的间隔（毫秒）。未设置时根据 `NODE_ENV` 推导默认值。 | +| `OMNIROUTE_SKIP_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts`, `src/lib/db/healthCheck.ts` | 设为 `1` 可在启动时完全跳过数据库健康检查。适用于短生命周期任务和集成测试。 | +| `OMNIROUTE_FORCE_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts` | 设为 `1` 可强制开启数据库健康检查循环，即使正常会被跳过（如短生命周期任务）。 | +| `OMNIROUTE_SKIP_POSTINSTALL` | `0` | `scripts/postinstall.mjs` | 设为 `1` 可在 `npm install` 期间跳过原生运行时预热。适用于 CI/无头安装，此时 sqlite 已构建好。 | +| `OMNIROUTE_MIGRATIONS_DIR` | _(自动检测)_ | `src/lib/db/migrationRunner.ts` | 覆盖迁移运行器扫描的目录。在自定义构建中打包迁移文件时很有用。 | +| `OMNIROUTE_MAX_PENDING_MIGRATIONS` | `50` | `src/lib/db/migrationRunner.ts` | 大量待处理迁移的安全阈值（#3416）。如果现有数据库上有超过此数量的待处理迁移，启动将中止（防止跟踪表被清空）。恢复旧备份时提高此值；设为 `0` 可禁用检查。 | +| `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 批量消费/成本写入器的刷新间隔（毫秒）。值越小写合并越少；值越大数据库争用越少。 | +| `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 强制刷新前的最大缓存消费条目数。在高 QPS 部署中提高；在内存受限场景下降低。 | +| `OMNIROUTE_PROXY_FETCH_DEBUG` | _(未设置)_ | `open-sse/utils/proxyFetch.ts` | 设为 `"true"` 可在 Vercel 中继路径上发出 `[ProxyFetch]` 调试日志。默认关闭以避免泄露路由提示。 | +| `BATCH_RETRY_DURATION_MS` | `86400000`（24小时） | `open-sse/services/batchProcessor.ts` | 单个批次项的最大重试窗口（毫秒）。超过此时间的项被标记为失败。 | +| `BATCH_BACKOFF_BASE_MS` | `5000` | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的基础延迟（毫秒）。 | +| `BATCH_BACKOFF_MAX_MS` | `3600000`（1小时） | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的上限（毫秒）。 | +| `BATCH_MAX_CONCURRENT` | `1` | `open-sse/services/batchProcessor.ts` | 并发处理的批次最大数量。提高以增加吞吐量；保持低值以避免速率限制风暴。 | + +### 场景 + +| 场景 | 配置 | +| --- | --- | +| **本地开发** | 保留所有默认值。数据库位于 `~/.omniroute/omniroute.db`。 | +| **Docker** | `DATA_DIR=/data` + 挂载卷到 `/data`。 | +| **静态加密** | 设置 `STORAGE_ENCRYPTION_KEY` + 备份密钥！丢失密钥 = 丢失数据。 | +| **CI/测试** | `DATA_DIR=/tmp/omniroute-test` — 临时目录，无需加密。 | --- -## 3. Network & Ports - -| Variable | Default | Source File | Description | -| --------------------- | ------------ | -------------------------- | -------------------------------------------------------------------------------------- | -| `PORT` | `20128` | `src/lib/runtime/ports.ts` | Primary port for both Dashboard UI and API endpoints (single-port mode). | -| `API_PORT` | _(unset)_ | `src/lib/runtime/ports.ts` | When set, serves the `/v1/*` proxy API on this separate port. | -| `API_HOST` | `0.0.0.0` | `src/lib/runtime/ports.ts` | Bind address for the API port. | -| `DASHBOARD_PORT` | _(unset)_ | `src/lib/runtime/ports.ts` | When set, serves the Dashboard UI on this separate port. | -| `PROD_DASHBOARD_PORT` | `20130` | `docker-compose.prod.yml` | Host-side published port for the Dashboard in Docker production mode. | -| `PROD_API_PORT` | `20131` | `docker-compose.prod.yml` | Host-side published port for the API in Docker production mode. | -| `OMNIROUTE_PORT` | _(unset)_ | `src/lib/runtime/ports.ts` | Takes precedence over `PORT` when running inside Electron or other wrappers. | -| `NODE_ENV` | `production` | Next.js core | Controls logging verbosity, caching, error detail exposure, and Next.js optimizations. | - -### Port Modes +## 3. 网络与端口 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `PORT` | `20128` | `src/lib/runtime/ports.ts` | Dashboard UI 和 API 端点共用的主端口（单端口模式）。 | +| `API_PORT` | _(未设置)_ | `src/lib/runtime/ports.ts` | 设置时，在另外的端口上提供 `/v1/*` 代理 API。 | +| `API_HOST` | `0.0.0.0` | `src/lib/runtime/ports.ts` | API 端口的绑定地址。 | +| `DASHBOARD_PORT` | _(未设置)_ | `src/lib/runtime/ports.ts` | 设置时，在另外的端口上提供 Dashboard UI。 | +| `PROD_DASHBOARD_PORT` | `20130` | `docker-compose.prod.yml` | Docker 生产模式下 Dashboard 的主机侧发布端口。 | +| `PROD_API_PORT` | `20131` | `docker-compose.prod.yml` | Docker 生产模式下 API 的主机侧发布端口。 | +| `OMNIROUTE_PORT` | _(未设置)_ | `src/lib/runtime/ports.ts` | 在 Electron 或其他包装器中运行时优先于 `PORT`。 | +| `LIVE_WS_PORT` | `20129` | `src/server/ws/liveServer.ts` | 实时 WebSocket 监控服务器的端口。 | +| `LIVE_WS_HOST` | `127.0.0.1` | `src/server/ws/liveServer.ts` | 实时 WebSocket 服务器的绑定地址。设为 `0.0.0.0` 可暴露到 LAN（还需配置 `LIVE_WS_ALLOWED_ORIGINS`）。 | +| `LIVE_WS_ALLOWED_ORIGINS` | _(未设置)_ | `src/server/ws/liveServer.ts` | 逗号分隔的额外允许打开实时 WebSocket 的源。loopback Dashboard 源已默认允许。 | +| `OMNIROUTE_ENABLE_LIVE_WS` | `true` | `src/server/ws/liveServer.ts` | 设为 `0` 或 `false` 可禁用实时 WebSocket 服务器（默认启用，绑定 loopback）。 | +| `OMNIROUTE_DISABLE_LIVE_WS` | `false` | `scripts/start-ws-server.mjs` | CI/测试工具开关，禁用独立的实时 WebSocket 辅助脚本。 | +| `RELAY_IP_PER_MINUTE` | `30` | `src/app/api/v1/relay/chat/completions/route.ts` | 每个 (Token, IP) 的中继速率限制，请求数/分钟。基于内存，每个实例独立。`0` 或负数可禁用 IP 维度门控（每个 Token 的数据库限制仍然生效）。 | +| `NODE_ENV` | `production` | Next.js 核心 | 控制日志详细程度、缓存、错误详情暴露和 Next.js 优化。 | +| `OMNIROUTE_USE_TURBOPACK` | `1`（`.env.example` 中默认值） | `package.json` / Next.js 16 | 在 `npm run dev` 和 `npm run build` 中切换 Next.js 16 Turbopack 打包器。在 Windows 或遇到原生绑定不兼容时设为 `0`。 | +| `OMNIROUTE_SKIP_DB_HEALTHCHECK` | _(未设置)_ | `src/lib/db/core.ts` / `src/lib/db/healthCheck.ts` | 设为 `1` 可跳过启动时的 SQLite 完整性健康检查。适用于大型数据库需要更快启动时。 | +| `CREDENTIAL_HEALTH_CHECK_INTERVAL` | `300000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/scheduler.ts` | 后台凭证健康检查调度器的间隔（毫秒）。最低：10000（10 秒）。 | +| `CREDENTIAL_HEALTH_CACHE_TTL` | `300000` | `open-sse/config/constants.ts` / `src/lib/credentialHealth/cache.ts` | 凭证健康状态缓存的 TTL（毫秒）。 | +| `OMNIROUTE_DISABLE_CREDENTIAL_HEALTH_CHECK` | `false` | `src/lib/credentialHealth/scheduler.ts` | 设为 `1` 或 `true` 可禁用后台定期服务商连接测试。 | +| `HOST` | `0.0.0.0` | `scripts/dev/run-next.mjs` | Next.js 开发/启动服务器的绑定地址。设置时覆盖默认的 `0.0.0.0`。 | +| `HOSTNAME` | `127.0.0.1` | `scripts/dev/run-next-playwright.mjs` | Playwright 启动 Next.js 时使用的绑定地址。默认为 `127.0.0.1` 以确保测试隔离。 | + +### 端口模式 ``` -┌─────────────────────────── Single Port (default) ──────────────────────────┐ -│ PORT=20128 │ -│ → Dashboard: http://localhost:20128 │ -│ → API: http://localhost:20128/v1/chat/completions │ -└─────────────────────────────────────────────────────────────────────────────┘ - -┌─────────────────────────── Split Ports ─────────────────────────────────────┐ -│ DASHBOARD_PORT=20128 │ -│ API_PORT=20129 │ -│ API_HOST=0.0.0.0 │ -│ → Dashboard: http://localhost:20128 │ -│ → API: http://0.0.0.0:20129/v1/chat/completions │ -│ Use case: Expose API to LAN while restricting Dashboard to localhost. │ -└─────────────────────────────────────────────────────────────────────────────┘ - -┌─────────────────────────── Docker Production ──────────────────────────────┐ -│ PROD_DASHBOARD_PORT=443 PROD_API_PORT=8443 │ -│ → Maps container ports to host ports in docker-compose.prod.yml. │ -└─────────────────────────────────────────────────────────────────────────────┘ +┌─────────────────────────── 单端口（默认）──────────────────────────┐ +│ PORT=20128 │ +│ → Dashboard: http://localhost:20128 │ +│ → API: http://localhost:20128/v1/chat/completions │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────── 分离端口 ────────────────────────────────┐ +│ DASHBOARD_PORT=20128 │ +│ API_PORT=20129 │ +│ API_HOST=0.0.0.0 │ +│ → Dashboard: http://localhost:20128 │ +│ → API: http://0.0.0.0:20129/v1/chat/completions │ +│ 用例：将 API 暴露给 LAN，同时限制 Dashboard 仅可本地访问。 │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────── Docker 生产 ─────────────────────────────┐ +│ PROD_DASHBOARD_PORT=443 PROD_API_PORT=8443 │ +│ → 将容器端口映射到 docker-compose.prod.yml 中的主机端口。 │ +└─────────────────────────────────────────────────────────────────────┘ ``` --- -## 4. Security & Authentication - -| Variable | Default | Source File | Description | -| ----------------------------- | --------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | `src/lib/auth` | Salt combined with hardware identifiers for machine fingerprinting. Change per-deployment for isolation. | -| `AUTH_COOKIE_SECURE` | `false` | `src/lib/auth` | Sets the `Secure` flag on session cookies. **Must be `true`** when running behind HTTPS. | -| `REQUIRE_API_KEY` | `false` | API middleware | When `true`, all `/v1/*` proxy requests must include a valid API key. | -| `ALLOW_API_KEY_REVEAL` | `false` | Dashboard providers page | Allows revealing full API key values in the Dashboard UI. Security risk on shared instances. | -| `NO_LOG_API_KEY_IDS` | _(empty)_ | `src/lib/compliance/index.ts` | Comma-separated API key IDs that bypass request logging (GDPR compliance). | -| `MAX_BODY_SIZE_BYTES` | `10485760` (10 MB) | `src/shared/middleware/bodySizeGuard.ts` | Maximum allowed request body size. Rejects payloads exceeding this limit. | -| `CORS_ORIGIN` | `*` | Next.js middleware | CORS `Access-Control-Allow-Origin` value. Restrict for production. | -| `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuard.ts` | Block provider calls targeting private/loopback/link-local IP ranges. Disable only in isolated test envs. | - -### Hardening Checklist +## 4. 安全与认证 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `MACHINE_ID_SALT` | `endpoint-proxy-salt` | `src/lib/auth` | 与硬件标识符组合用于机器指纹的盐值。按部署修改以实现隔离。 | +| `OMNIROUTE_CLI_SALT` | `omniroute-cli-auth-v1` | `src/lib/machineToken.ts` | 用于派生本地 CLI 认证 Token 的 HMAC 盐值。修改此值将轮换机器上的所有 CLI Token。参阅 `docs/security/CLI_TOKEN.md`。 | +| `AUTH_COOKIE_SECURE` | `false` | `src/lib/auth` | 设置会话 Cookie 的 `Secure` 标志。运行在 HTTPS 背后时 **必须设为 `true`**。 | +| `REQUIRE_API_KEY` | `false` | API 中间件 | 设为 `true` 后，所有 `/v1/*` 代理请求必须包含有效的 API key。 | +| `ALLOW_API_KEY_REVEAL` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | 允许在 Dashboard UI 中显示完整 API key 值。可从 Dashboard Feature Flags 配置；共享实例上有安全风险。 | +| `NO_LOG_API_KEY_IDS` | _(空)_ | `src/lib/compliance/index.ts` | 逗号分隔的 API key ID 列表，其请求将绕过日志记录（GDPR 合规）。 | +| `DEFAULT_RATE_LIMIT_PER_DAY` | `1000` | `src/shared/utils/apiKeyPolicy.ts` | 应用于 `rate_limits` 列为 null 的 API key 的回退每日请求预算。默认（未设置/空/格式错误）保持传统的 1000/天、5000/周、20000/月 窗口。显式设为 `0` 可选择退出（无限制）。任意正整数 N 则启用 N/天、5N/周、20N/月。Zod 校验；无效值记录警告并使用传统默认值。 | +| `MAX_BODY_SIZE_BYTES` | `10485760`（10 MB） | `src/shared/middleware/bodySizeGuard.ts` | 允许的最大请求体大小。拒绝超限载荷。 | +| `CORS_ORIGIN` | _(未设置)_ | `src/server/cors/origins.ts` | 旧版单一源 CORS 允许列表。新部署推荐使用 `CORS_ALLOWED_ORIGINS`。CORS 仅用于跨源浏览器 API 客户端；反向代理后的同源 Dashboard 请求使用 `NEXT_PUBLIC_BASE_URL` / 公共源校验。 | +| `CORS_ALLOWED_ORIGINS` | _(未设置)_ | `src/server/cors/origins.ts` | 逗号分隔的 CORS 允许列表。除非显式配置 `CORS_ALLOW_ALL=true`，否则不发送通配符。 | +| `CORS_ALLOW_ALL` | `false` | `src/server/cors/origins.ts` | 仅供开发使用的逃生口，可回显任意浏览器 `Origin`。不要在共享或生产部署中启用。 | +| `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuard.ts` | 阻止目标为私有/loopback/链路本地 IP 范围的服务商调用。仅在隔离的测试环境中禁用。 | +| `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` | `false` | `src/shared/network/outboundUrlGuard.ts` | 允许指向私有/本地网络（localhost、192.168.x.x、10.x.x.x 等）的服务商 URL。**自托管服务商必需**（LM Studio、Ollama、vLLM、Llamafile、Triton、SearXNG）。设为 `false` 时，Dashboard 拒绝校验本地 URL。 | +| `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` | `true` | `src/shared/network/outboundUrlGuard.ts` | 允许在本地/私有地址上添加/校验服务商（127.0.0.1、localhost、LAN、私有范围）— 仅影响服务商校验路径。**默认 `true`**（本地优先）；设为 `false` 可强制严格的仅公网阻断。云元数据端点（169.254.169.254, metadata.google.internal）始终被阻断。（#5066） | + +### 加固清单 ```bash -# Production security minimum: -AUTH_COOKIE_SECURE=true # Requires HTTPS -REQUIRE_API_KEY=true # Authenticate all proxy calls -ALLOW_API_KEY_REVEAL=false # Never expose keys in UI -CORS_ORIGIN=https://your.domain.com -MAX_BODY_SIZE_BYTES=5242880 # 5 MB limit +# 生产环境安全最低要求： +AUTH_COOKIE_SECURE=true # 需要 HTTPS +REQUIRE_API_KEY=true # 认证所有代理调用 +ALLOW_API_KEY_REVEAL=false # 绝不在 UI 中暴露密钥 +CORS_ALLOWED_ORIGINS=https://your.domain.com +MAX_BODY_SIZE_BYTES=5242880 # 5 MB 限制 ``` --- -## 5. Input Sanitization & PII Protection +## 5. 输入净化与 PII 保护 -OmniRoute provides a two-layer defense: request-side injection scanning and response-side PII stripping. +OmniRoute 提供两层防护：请求侧的注入扫描和响应侧的 PII 脱敏。 -### Request-Side: Prompt Injection Guard +### 请求侧：提示注入安全护栏 -| Variable | Default | Source File | Description | -| ------------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------- | -| `INPUT_SANITIZER_ENABLED` | `false` | `src/middleware/promptInjectionGuard.ts` | Enable scanning of incoming messages for prompt injection patterns. | -| `INPUT_SANITIZER_MODE` | `warn` | `src/middleware/promptInjectionGuard.ts` | `warn` = log only, `block` = reject request with 400, `redact` = strip suspicious patterns. | -| `INJECTION_GUARD_MODE` | _(unset)_ | `src/middleware/promptInjectionGuard.ts` | Legacy alias for `INPUT_SANITIZER_MODE` — same behavior. | -| `PII_REDACTION_ENABLED` | `false` | `src/middleware/promptInjectionGuard.ts` | Detect PII (emails, phones, SSNs) in incoming requests. | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `INPUT_SANITIZER_ENABLED` | `true` | `src/middleware/promptInjectionGuard.ts` | 启用扫描传入消息中的提示注入模式。 | +| `INPUT_SANITIZER_MODE` | `warn` | `src/middleware/promptInjectionGuard.ts` | `warn` = 仅记录日志，`block` = 以 400 拒绝请求，`redact` = 脱敏可疑模式。 | +| `INJECTION_GUARD_MODE` | _(未设置)_ | `src/middleware/promptInjectionGuard.ts` | `INPUT_SANITIZER_MODE` 的旧版别名 — 行为相同。 | +| `PII_REDACTION_ENABLED` | `false` | `src/middleware/promptInjectionGuard.ts` | 检测传入请求中的 PII（邮箱、电话、社会安全号码等）。 | -### Response-Side: PII Sanitizer +### 响应侧：PII 脱敏器 -| Variable | Default | Source File | Description | -| -------------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------- | -| `PII_RESPONSE_SANITIZATION` | `false` | `src/lib/piiSanitizer.ts` | Scan LLM responses for leaked PII before returning to client. | -| `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = mask PII, `warn` = log only, `block` = drop entire response. | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `PII_RESPONSE_SANITIZATION` | `false` | `src/lib/piiSanitizer.ts` | 在返回给客户端之前扫描大语言模型响应中的泄露 PII。 | +| `PII_RESPONSE_SANITIZATION_MODE` | `redact` | `src/lib/piiSanitizer.ts` | `redact` = 脱敏 PII，`warn` = 仅记录日志，`block` = 丢弃整个响应。 | -### Scenarios +### VS Code Token 化路由上下文净化器 -| Scenario | Configuration | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **Enterprise compliance** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=block`, `PII_REDACTION_ENABLED=true`, `PII_RESPONSE_SANITIZATION=true` | -| **Monitoring only** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — logs but never blocks | -| **Personal use** | Leave all disabled — zero overhead | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_VSCODE_SANITIZE_CONTEXT` | `1` | `src/app/api/v1/vscode/contextSanitizer.ts` | 从 `/v1/vscode/[token]/*` 请求中剥离隐式的活跃编辑器上下文（`editorContext`, `activeEditor`, `currentFile`, `selection`, `openTabs`...），并脱敏显式附加的敏感文件内容。安全默认启用；设为 `0` 可禁用。 | ---- +### 场景 -## 6. Tool & Routing Policies - -| Variable | Default | Source File | Description | -| ------------------ | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | Controls LLM tool/function-calling access. `allowlist` = only listed tools, `denylist` = all except listed, `disabled` = no restrictions. | +| 场景 | 配置 | +| --- | --- | +| **企业合规** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=block`, `PII_REDACTION_ENABLED=true`, `PII_RESPONSE_SANITIZATION=true` | +| **仅监控** | `INPUT_SANITIZER_ENABLED=true`, `INPUT_SANITIZER_MODE=warn` — 记录日志但永不阻断 | +| **个人使用** | 全部禁用 — 零开销 | --- -## 7. URLs & Cloud Sync - -| Variable | Default | Source File | Description | -| ----------------------- | ------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | Server-side URL for internal sync jobs to call `/api/sync/cloud`. | -| `CLOUD_URL` | _(empty)_ | `src/lib/cloudSync.ts` | Cloud relay endpoint URL (premium feature). | -| `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | HTTP timeout for cloud sync requests. | -| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth, Dashboard, sync | Public-facing URL for OAuth redirect_uri, Dashboard links. **Must match your public URL behind reverse proxy.** | -| `NEXT_PUBLIC_CLOUD_URL` | _(empty)_ | Client-side | Client-side mirror of `CLOUD_URL`. | -| `NEXT_PUBLIC_APP_URL` | _(unset)_ | `src/shared/services/cloudSyncScheduler.ts` | Legacy fallback for `NEXT_PUBLIC_BASE_URL`. | +## 6. 工具与路由策略 -> [!IMPORTANT] -> When deploying behind a reverse proxy (nginx, Caddy), `NEXT_PUBLIC_BASE_URL` **must** be set to your public URL (e.g., `https://omniroute.example.com`). Without this, OAuth callbacks will fail because the redirect_uri won't match. +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `TOOL_POLICY_MODE` | `disabled` | `src/lib/toolPolicy.ts` | 控制大语言模型的工具/函数调用访问。`allowlist` = 仅允许列表中的工具，`denylist` = 除列表外全部允许，`disabled` = 无限制。 | +| `OMNIROUTE_PAYLOAD_RULES_PATH` | `./config/payloadRules.json` | `open-sse/services/payloadRules.ts` | 载荷操作规则 JSON 文件路径（按模型/协议进行上游调整）。 | +| `OMNIROUTE_PAYLOAD_RULES_RELOAD_MS` | `5000` | `open-sse/services/payloadRules.ts` | 热加载载荷规则文件的重载间隔（毫秒）。最低 `1000`。 | +| `OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS` | `false` | `open-sse/services/model.ts` | 启用后：将来自 Claude Code 客户端的无前缀 `claude-*` 模型 ID 通过 Claude Code OAuth 账户路由，而非要求服务商前缀。显式服务商前缀优先级更高。也可通过 Dashboard 中 Claude 服务商页面的开关配置。 | --- -## 8. Outbound Proxy - -Route upstream LLM provider calls through an HTTP or SOCKS5 proxy for egress control, geo-routing, or IP masking. +## 7. URL 与云同步 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | 内部同步任务调用 `/api/sync/cloud` 的服务器端 URL。即使应用被公共代理，也保持为 loopback/容器 URL。 | +| `CLOUD_URL` | _(空)_ | `src/lib/cloudSync.ts` | 云中继端点 URL（高级功能）。 | +| `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | 云同步请求的 HTTP 超时。 | +| `OMNIROUTE_BUILD_PROFILE` | `full` | Webpack 构建配置 | 构建时配置文件（设为 `minimal` 可物理排除特权模块不打包）。 | +| `OMNIROUTE_CLOUD_SYNC_SECRET` | _(空)_ | `src/lib/cloudSync.ts` | 用于校验云同步响应 HMAC-SHA256 签名的共享密钥。 | +| `OMNIROUTE_CLOUD_SYNC_SECRETS` | `false` | `src/lib/cloudSync.ts` | 设为 `true` 允许云同步端点覆盖本地凭证。默认 `false`。 | +| `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP` | `false` | `src/app/api/providers/zed/import/route.ts` | 设为 `true` 可回退到 v3.8.5 的一步式"导入全部"行为，无需用户确认。 | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth、Dashboard、同步 | 面向公共的 URL，用于 OAuth redirect_uri、Dashboard 链接、生成的公共 URL 以及同源浏览器变更检查。**在反向代理背后时，必须匹配你的公共 URL。** | +| `NEXT_PUBLIC_CLOUD_URL` | _(空)_ | 客户端侧 | `CLOUD_URL` 的客户端镜像。 | +| `NEXT_PUBLIC_APP_URL` | _(未设置)_ | `src/shared/services/cloudSyncScheduler.ts` | `NEXT_PUBLIC_BASE_URL` 的旧版回退。 | +| `OMNIROUTE_PUBLIC_BASE_URL` | _(未设置)_ | 公共源解析器、图片 URL | 最高优先级的浏览器侧 OmniRoute 源，用于公共 URL 生成和源校验（例如 `/v1/chatgpt-web/image/`）。当 OpenWebUI 或其他中继通过内部 URL 访问 OmniRoute，但用户浏览器必须从 LAN、隧道或公共源获取图片时设置。**不要**包含 `/v1`。 | +| `OMNIROUTE_TRUST_PROXY` | _(未设置)_ | `src/server/origin/publicOrigin.ts` | 可选的转发公共源头信任模式。未设置 = 出于安全考虑不信任 `Forwarded` / `X-Forwarded-*`。`true` / `loopback` 仅信任来自经过 Token 戳记的 loopback 代理的转发 host/proto。`private` / `lan` 还信任私有 LAN 代理对端。生产环境中推荐显式设置 `NEXT_PUBLIC_BASE_URL`。 | +| `OMNIROUTE_CGPT_WEB_IMAGE_TIMEOUT_MS` | `180000`（3 分钟） | `open-sse/executors/chatgpt-web.ts` | 等待异步 chatgpt-web 图片通过 Celsius WebSocket 到达的最大时间。在上游排队窗口较长时提高此值。 | +| `OMNIROUTE_CGPT_WEB_IMAGE_CACHE_MAX_MB` | `256` | `open-sse/services/chatgptImageCache.ts` | 为 `/v1/chatgpt-web/image/` 提供服务的 chatgpt-web 图片缓存的内存预算总额（MB）。在内存受限的主机上降低；图片生成量大且客户端争抢 30 分钟 TTL 时提高。 | +| `OMNIROUTE_CGPT_WEB_PRO_TIMEOUT_MS` | `1200000`（20 分钟） | `open-sse/executors/chatgpt-web.ts` | chatgpt-web GPT-5.5 Pro 后台轮询交接的总体等待预算。Pro 推理在带外完成，OmniRoute 轮询直到结果到达或预算耗尽。如果 Pro 请求完成前超时，请提高此值。 | +| `OMNIROUTE_CGPT_WEB_PRO_POLL_INTERVAL_MS` | `4000`（4 秒） | `open-sse/executors/chatgpt-web.ts` | chatgpt-web GPT-5.5 Pro 后台轮询尝试的间隔。降低可更快完成但增加上游轮询；提高可减少请求量。 | +| `THEOLDLLM_NAV_TIMEOUT_MS` | `30000`（30 秒） | `open-sse/executors/theoldllm.ts` | 浏览器端 Token 捕获（The Old LLM (theoldllm) 免费服务商使用）的 Playwright 导航超时（毫秒）。如果中继页面加载慢，可在慢速网络上提高。 | +| `KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 异步 kie.ai 任务的公共回调 URL。优先级高于 `OMNIROUTE_KIE_CALLBACK_URL` 和 `OMNIROUTE_PUBLIC_URL`。 | +| `OMNIROUTE_KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | `KIE_CALLBACK_URL` 的替代写法。主变量未设置时的回退。 | +| `OMNIROUTE_PUBLIC_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 用于组合异步回调 URL 的公共源。kie.ai 回调的最低优先级回退；也用作其他中继的通用公共 URL。 | +| `OMNIROUTE_CROF_USAGE_URL` | `https://crof.ai/usage_api/` | `open-sse/services/usage.ts` | Usage 页面使用的 CrofAI 配额查询端点。可覆盖为中继/测试固定件。 | +| `OMNIROUTE_OPENCODE_QUOTA_URL` | `https://opencode.ai/zen/go/v1/quota` | `open-sse/services/opencodeQuotaFetcher.ts` | Usage 页面使用的 OpenCode (zen/go) 配额查询端点。可覆盖为中继/测试固定件。 | +| `OMNIROUTE_OPENCODE_GO_QUOTA_URL` | `https://api.z.ai/api/monitor/usage/quota/limit` | `open-sse/services/usage.ts` | Usage 页面使用的 OpenCode Go 配额查询端点。可覆盖为中继/测试固定件。 | +| `OMNIROUTE_OPENCODE_GO_DASHBOARD_URL` | `https://opencode.ai/workspace` | `open-sse/services/usage.ts` | 配置了 workspace ID 和 auth Cookie 时用于配额抓取的 OpenCode Go Dashboard 基础 URL。可覆盖为中继/测试固定件。 | +| `OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go workspace ID。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OMNIROUTE_OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go workspace ID 环境变量的备选名，在较短的别名之前使用。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go `auth` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OMNIROUTE_OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go `auth` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OMNIROUTE_OLLAMA_CLOUD_USAGE_URL` | `https://ollama.com/settings` | `open-sse/services/usage.ts` | 用于配额抓取的 Ollama Cloud settings URL。可覆盖为中继/测试固定件。 | +| `OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于设置页面配额抓取的 Ollama Cloud `__Secure-session` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OLLAMA_CLOUD_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OMNIROUTE_OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 | +| `OMNIROUTE_CODEWHISPERER_BASE_URL` | `https://codewhisperer.us-east-1.amazonaws.com` | `open-sse/services/usage.ts` | CodeWhisperer (AWS Kiro) 用量限制端点。可覆盖为中继/测试固定件。 | -| Variable | Default | Source File | Description | -| --------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------- | -| `ENABLE_SOCKS5_PROXY` | `true` | `open-sse/executors` | Enable SOCKS5 proxy agent for upstream calls. | -| `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true` | Client-side | Client-side awareness of SOCKS5 availability. | -| `HTTP_PROXY` | _(unset)_ | Node.js standard | HTTP proxy for upstream calls. | -| `HTTPS_PROXY` | _(unset)_ | Node.js standard | HTTPS proxy for upstream calls. | -| `ALL_PROXY` | _(unset)_ | Node.js standard | Universal proxy (supports `socks5://`). | -| `NO_PROXY` | _(unset)_ | Node.js standard | Comma-separated hostnames/IPs to bypass the proxy. | -| `ENABLE_TLS_FINGERPRINT` | `false` | `open-sse/executors` | Spoof TLS fingerprint using wreq-js (mimics Chrome 124). Counters JA3/JA4 blocking. | - -### Scenarios - -| Scenario | Configuration | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| **SOCKS5 through SSH tunnel** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true` | -| **Corporate HTTP proxy** | `HTTP_PROXY=http://proxy.corp.com:3128`, `HTTPS_PROXY=http://proxy.corp.com:3128`, `NO_PROXY=localhost,internal.corp.com` | -| **Anti-fingerprint** | `ENABLE_TLS_FINGERPRINT=true` — requires `wreq-js` (included) | +> [!IMPORTANT] +> 当部署在反向代理（nginx、Caddy）之后时，**必须**将 `NEXT_PUBLIC_BASE_URL` 设置为你的公共 URL（例如 `https://omniroute.example.com`）。否则 OAuth 回调可能因 redirect_uri 不匹配而失败，生成的公共链接可能指向内部容器源，同源 Dashboard 变更可能被浏览器源检查拒绝。 +> +> 对于服务器到服务器的任务，保持 `BASE_URL` 为内部 loopback/容器 URL。不要为携带凭证的内部自调用使用浏览器 `Origin` 或公共主机名。 +> +> OmniRoute 集中处理公共源校验：显式的公共 URL 环境变量优先被信任；原始的 `Forwarded` / `X-Forwarded-*` 头默认被忽略，除非启用了 `OMNIROUTE_TRUST_PROXY` 且直接代理对端经过 Token 戳记为可信。不要用 CORS 设置来修复同源 Dashboard 请求；CORS 仅用于跨源浏览器客户端。 --- -## 9. CLI Tool Integration +## 8. 出口代理 + +将上游大语言模型服务商调用通过 HTTP 或 SOCKS5 代理路由，以实现出口控制、异地路由或 IP 掩码。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `ENABLE_SOCKS5_PROXY` | `true` | `open-sse/executors` | 启用上游调用的 SOCKS5 代理代理。可用 `false` 退出。 | +| `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` | `true` | 客户端侧 | 客户端对 SOCKS5 可用性的感知。 | +| `HTTP_PROXY` | _(未设置)_ | Node.js 标准 | 上游调用的 HTTP 代理。 | +| `HTTPS_PROXY` | _(未设置)_ | Node.js 标准 | 上游调用的 HTTPS 代理。 | +| `ALL_PROXY` | _(未设置)_ | Node.js 标准 | 通用代理（支持 `socks5://`）。 | +| `NO_PROXY` | _(未设置)_ | Node.js 标准 | 逗号分隔的绕过代理的主机名/IP。 | +| `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS` | `32` | `open-sse/utils/proxyDispatcher.ts` | 每个缓存的 HTTP/SOCKS 代理调度器的最大并发套接字数。长连接 SSE 流（如 Codex `/v1/responses`）在多个请求共享同一账户级代理时需要不止一个连接。超过 `256` 的值会被截断。 | +| `SOCKS_HANDSHAKE_TIMEOUT_MS` | `10000` | `open-sse/utils/socksConnectorWithFamily.ts` | SOCKS5 握手（连接）超时，毫秒。当单个住宅网关主机高并发（如 100 个并发请求）时提高 — 在池饱和情况下实际握手可能超过 10 秒，即使代理可达，否则会显示为虚假的 `[Proxy Fast-Fail] Proxy unreachable`。上限为 `120000`。 | +| `PROXY_FAIL_OPEN` | `false` | `src/sse/handlers/chatHelpers.ts` | 设为 `false`（默认）时，代理解析失败的请求会被**拒绝（fail-closed）**，而不会回退到直连 — 防止真实 IP 泄露。设为 `true` 可恢复旧版的 DIRECT 回退。 | +| `ENABLE_TLS_FINGERPRINT` | `false` | `open-sse/executors` | 使用 wreq-js 伪装 TLS 指纹（模拟 Chrome 124）。对抗 JA3/JA4 阻断。 | +| `OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS` | `false` | `open-sse/services/claudeTurnstileSolver.ts` | 允许 Claude Turnstile 的 Playwright 浏览器上下文忽略 HTTPS 证书错误。 | + +### 场景 + +| 场景 | 配置 | +| --- | --- | +| **通过 SSH 隧道走 SOCKS5** | `ALL_PROXY=socks5://127.0.0.1:7890`, `ENABLE_SOCKS5_PROXY=true` | +| **企业 HTTP 代理** | `HTTP_PROXY=http://proxy.corp.com:3128`, `HTTPS_PROXY=http://proxy.corp.com:3128`, `NO_PROXY=localhost,internal.corp.com` | +| **反指纹** | `ENABLE_TLS_FINGERPRINT=true` — 需要 `wreq-js`（已包含） | +| **出口受控 / 无直连访问** | 保持 `PROXY_FAIL_OPEN=false`（默认）。代理不可用时请求直接失败，不会通过直连泄露。 | +| **旧版/开发 — 允许直连回退** | `PROXY_FAIL_OPEN=true`。恢复加固前行为：代理解析失败时使用直连连接。 | + +> **注意（NVIDIA 校验绕过 — #3226）：** NVIDIA 的 API Key 校验端点 +> 在通过全局代理/TLS 修补 fetch（undici dispatcher → 504）路由时会卡住。 +> `src/lib/providers/validation.ts::directHttpsRequest()` 有意识地绕过该 +> 代理修补，使用 `safeOutboundFetch({ bypassProxyPatch: true })` 处理那个单独的校验调用。 +> 这是一个有文档记录、范围受限的例外 — 它 **不会** 影响聊天/用量出口。 +> 绕过范围由 `tests/unit/proxy-bypass-scope-guard-3226.test.ts` 固定。 -Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, etc.). - -| Variable | Default | Source File | Description | -| ------------------------- | ---------- | ----------------------------------- | -------------------------------------------------------------------------- | -| `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | `auto` = search system PATH; `manual` = use explicit paths only. | -| `CLI_EXTRA_PATHS` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Additional PATH entries for CLI binary discovery (colon-separated). | -| `CLI_CONFIG_HOME` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Override home directory for reading CLI configs (`~/.claude`, `~/.codex`). | -| `CLI_ALLOW_CONFIG_WRITES` | `false` | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data). | -| `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Custom path to Claude CLI binary. | -| `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Custom path to Codex CLI binary. | -| `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Custom path to Droid CLI binary. | -| `CLI_OPENCLAW_BIN` | `openclaw` | `src/shared/services/cliRuntime.ts` | Custom path to OpenClaw CLI binary. | -| `CLI_CURSOR_BIN` | `agent` | `src/shared/services/cliRuntime.ts` | Custom path to Cursor agent binary. | -| `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Custom path to Cline CLI binary. | -| `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Custom path to Continue CLI binary. | -| `CLI_QODER_BIN` | `qoder` | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary. | +--- -### Docker Example +## 9. CLI 工具集成 + +控制 OmniRoute 如何发现和启动 CLI sidecar（Claude Code、Codex 等）。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | `auto` = 搜索系统 PATH；`manual` = 仅使用显式路径。 | +| `CLI_EXTRA_PATHS` | _(未设置)_ | `src/shared/services/cliRuntime.ts` | 用于 CLI 二进制文件发现的额外 PATH 条目（冒号分隔）。 | +| `CLI_CONFIG_HOME` | _(未设置)_ | `src/shared/services/cliRuntime.ts` | 覆盖读取 CLI 配置（`~/.claude`、`~/.codex`）的主目录。 | +| `CLI_ALLOW_CONFIG_WRITES` | `false` | `src/shared/services/cliRuntime.ts` | 允许 OmniRoute 写入 CLI 配置文件（Token 刷新、会话数据）。 | +| `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Claude CLI 二进制文件的自定义路径。 | +| `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Codex CLI 二进制文件的自定义路径。 | +| `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Droid CLI 二进制文件的自定义路径。 | +| `CLI_OPENCLAW_BIN` | `openclaw` | `src/shared/services/cliRuntime.ts` | OpenClaw CLI 二进制文件的自定义路径。 | +| `CLI_CURSOR_BIN` | `agent` | `src/shared/services/cliRuntime.ts` | Cursor agent 二进制文件的自定义路径。 | +| `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Cline CLI 二进制文件的自定义路径。 | +| `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Continue CLI 二进制文件的自定义路径。 | +| `CLI_QODER_BIN` | `qoder` | `src/shared/services/cliRuntime.ts` | Qoder CLI 二进制文件的自定义路径。 | +| `CLI_QWEN_BIN` | `qwen` | `src/shared/services/cliRuntime.ts` | Qwen Code CLI 二进制文件的自定义路径。 | +| `CLI_DEVIN_BIN` | `devin` | `open-sse/executors/devin-cli.ts` | Devin CLI 二进制文件的自定义路径（v3.8.0）。由 Windsurf/Devin executor 使用。 | +| `HERMES_HOME` | `~/.hermes` | `src/lib/cli-helper/config-generator/hermesHome.ts` | Hermes Agent 主目录，OmniRoute 从此处读取/写入 Hermes CLI 配置。与 Hermes PowerShell 安装程序在 Windows 上设置的环境变量（`%LOCALAPPDATA%\hermes`）一致。 | + +### Docker 示例 ```bash -# Mount host binaries into the container and tell OmniRoute where they are: +# 将主机二进制文件挂载到容器中，并告诉 OmniRoute 它们的位置： CLI_EXTRA_PATHS=/host-cli/bin CLI_CONFIG_HOME=/root CLI_ALLOW_CONFIG_WRITES=true CLI_CLAUDE_BIN=/host-cli/bin/claude ``` +### CLI 二进制文件（`omniroute`）辅助变量 + +以下变量调优 `omniroute` CLI 二进制文件自身的行为（而非上面的 sidecar 检测）。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_LANG` | _(系统)_ | `bin/cli/i18n.mjs` | 强制 CLI 输出语言。BCP-47 locale（如 `en`、`pt-BR`）。覆盖系统 locale 环境变量（LC_ALL, LC_MESSAGES）。 | +| `OMNIROUTE_SHOW_LOG` | _(未设置)_ | `bin/cli/runtime/processSupervisor.mjs` | 设为 `1` 可在受监管模式下将服务器 stdout/stderr 转发到终端。等同于 `omniroute serve` 的 `--log` 标志。 | +| `OMNIROUTE_CLI_TOKEN` | _(未设置)_ | `bin/cli/api.mjs` | 作为 `x-omniroute-cli-token` 头注入的机器认证 Token。在任务 8.12 中自动生成。 | +| `OMNIROUTE_HTTP_TIMEOUT_MS` | `30000` | `bin/cli/api.mjs` | CLI → 服务器请求的单次尝试 HTTP 超时（毫秒）。 | +| `OMNIROUTE_VERBOSE` | `0` | `bin/cli/api.mjs` | 设为 `1` 可在 CLI 命令期间将重试/退避诊断信息打印到 stderr。 | +| `OMNIROUTE_PLUGIN_PATH` | _(未设置)_ | `bin/cli/plugins.mjs` | CLI 插件发现的自定义目录（`omniroute-cmd-*` 包）。未设置时默认为 `~/.omniroute/plugins/`。 | +| `OMNIROUTE_PLUGINS_ALLOW_EXEC` | `0` | `src/lib/plugins/pluginWorker.ts` | 设为 `1` 允许插件请求 `exec` 权限（从 Worker 沙箱中生成子进程）。仅供本地运维人员。 | + --- -## 10. Internal Agent & MCP Integrations - -| Variable | Default | Source File | Description | -| --------------------------------------- | ----------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `OMNIROUTE_BASE_URL` | auto-detect | `open-sse/mcp-server/server.ts` | Explicit URL for MCP/A2A tools to reach OmniRoute. Overrides localhost auto-detection. | -| `OMNIROUTE_API_KEY` | _(unset)_ | MCP/A2A modules | API key for internal MCP tool and A2A skill calls. | -| `OMNIROUTE_API_KEY_ID` | _(unset)_ | `open-sse/mcp-server/audit.ts` | Key ID for MCP audit log attribution. | -| `ROUTER_API_KEY` | _(unset)_ | Legacy | Legacy alias for `OMNIROUTE_API_KEY`. | -| `OMNIROUTE_MCP_ENFORCE_SCOPES` | `false` | `open-sse/mcp-server/server.ts` | Enforce scope-based access control on MCP tool calls. | -| `OMNIROUTE_MCP_SCOPES` | _(all)_ | `open-sse/mcp-server/server.ts` | Comma-separated scopes: `admin`, `combos`, `health`, `models`, `routing`, `budget`, `metrics`, `pricing`, `memory`, `skills`. | -| `MODEL_SYNC_INTERVAL_HOURS` | `24` | `src/shared/services/modelSyncScheduler.ts` | Model catalog sync interval in hours. | -| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | `src/server-init.ts` | Provider rate-limit and quota polling interval. | -| `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false` | `src/instrumentation-node.ts` | Disable all background services (sync, pricing, model refresh). Useful for CI/test. | -| `OMNIROUTE_BOOTSTRAPPED` | `false` | `src/app/(dashboard)/dashboard/page.tsx` | Set `true` by bootstrap script after initial setup. Controls setup wizard visibility. | -| `OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE` | `0` | `open-sse/executors/antigravity.ts` | Escape hatch: allow request body to override the Antigravity project field. | - -### OAuth CLI Bridge (Internal) - -| Variable | Default | Source File | Description | -| ------------------- | ----------- | ------------------------------- | ----------------------------------------- | -| `OMNIROUTE_SERVER` | auto-detect | `src/lib/oauth/config/index.ts` | Server URL for CLI↔OmniRoute auth bridge. | -| `OMNIROUTE_TOKEN` | _(unset)_ | `src/lib/oauth/config/index.ts` | Auth token for CLI bridge. | -| `OMNIROUTE_USER_ID` | `cli` | `src/lib/oauth/config/index.ts` | User ID for CLI bridge sessions. | -| `SERVER_URL` | _(unset)_ | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_SERVER`. | -| `CLI_TOKEN` | _(unset)_ | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_TOKEN`. | -| `CLI_USER_ID` | _(unset)_ | `src/lib/oauth/config/index.ts` | Legacy alias for `OMNIROUTE_USER_ID`. | - ---- - -## 11. OAuth Provider Credentials - -Built-in credentials for **localhost development**. For remote deployments, register your own at each provider's developer console. - -| Variable | Provider | Notes | -| --------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | -| `CLAUDE_OAUTH_CLIENT_ID` | Claude Code (Anthropic) | Public client — no secret needed. | -| `CLAUDE_CODE_REDIRECT_URI` | Claude Code | Override redirect URI. Default: `https://platform.claude.com/oauth/code/callback` | -| `CODEX_OAUTH_CLIENT_ID` | Codex / OpenAI | Public client. | -| `GEMINI_OAUTH_CLIENT_ID` | Gemini (Google) | Requires matching `_SECRET`. | -| `GEMINI_OAUTH_CLIENT_SECRET` | Gemini (Google) | — | -| `QWEN_OAUTH_CLIENT_ID` | Qwen (Alibaba) | Public client. | -| `KIMI_CODING_OAUTH_CLIENT_ID` | Kimi Coding (Moonshot) | Public client. | -| `ANTIGRAVITY_OAUTH_CLIENT_ID` | Antigravity (Google) | Requires matching `_SECRET`. | -| `ANTIGRAVITY_OAUTH_CLIENT_SECRET` | Antigravity (Google) | — | -| `GITHUB_OAUTH_CLIENT_ID` | GitHub Copilot | Public client. | -| `QODER_OAUTH_CLIENT_SECRET` | Qoder | — | -| `QODER_OAUTH_AUTHORIZE_URL` | Qoder | Set to enable Qoder OAuth. | -| `QODER_OAUTH_TOKEN_URL` | Qoder | — | -| `QODER_OAUTH_USERINFO_URL` | Qoder | — | -| `QODER_OAUTH_CLIENT_ID` | Qoder | — | -| `QODER_PERSONAL_ACCESS_TOKEN` | Qoder | Direct API key fallback (bypasses OAuth). | -| `QODER_CLI_WORKSPACE` | Qoder | Workspace ID for Qoder CLI. | -| `OMNIROUTE_QODER_WORKSPACE` | Qoder | Alias for `QODER_CLI_WORKSPACE`. | +## 10. 内部 Agent 与 MCP 集成 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_BASE_URL` | 自动检测 | `open-sse/mcp-server/server.ts` | MCP/A2A 工具访问 OmniRoute 的显式 URL。覆盖 localhost 自动检测。 | +| `OMNIROUTE_API_KEY` | _(未设置)_ | MCP/A2A 模块 | 内部 MCP 工具和 A2A 技能调用的 API key。 | +| `OMNIROUTE_API_KEY_ID` | _(未设置)_ | `open-sse/mcp-server/audit.ts` | 用于 MCP 审计日志归属的 Key ID。 | +| `ROUTER_API_KEY` | _(未设置)_ | 旧版 | `OMNIROUTE_API_KEY` 的旧版别名。 | +| `OMNIROUTE_CONTEXT` | _(活跃上下文)_ | `bin/cli/program.mjs`, `bin/cli/api.mjs` | `omniroute` 命令的 CLI 远程模式上下文/配置文件；覆盖本地上下文存储中的活跃上下文。等同于 `--context `。 | +| `OMNIROUTE_MCP_ENFORCE_SCOPES` | `true` | `open-sse/mcp-server/server.ts` | 对 MCP 工具调用强制执行基于权限域的访问控制。 | +| `OMNIROUTE_MCP_SCOPES` | _(全部)_ | `open-sse/mcp-server/server.ts` | 逗号分隔的权限域：`admin`、`combos`、`health`、`models`、`routing`、`budget`、`metrics`、`pricing`、`memory`、`skills`。 | +| `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS` | `false` | `open-sse/mcp-server/descriptionCompressor.ts` | 在序列化清单之前压缩 MCP 工具描述。启用值：`1`、`true`、`on`。 | +| `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION` | `rtk` | `open-sse/mcp-server/descriptionCompressor.ts` | 压缩算法/配置文件。禁用值：`0`、`false`、`off`。 | +| `MODEL_SYNC_INTERVAL_HOURS` | `24` | `src/shared/services/modelSyncScheduler.ts` | 模型目錄同步间隔，小时。 | +| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | `src/server-init.ts` | 服务商速率限制和配额轮询间隔。 | +| `PROVIDER_LIMITS_SYNC_SPACING_MS` | `1500` | `src/lib/usage/providerLimits.ts` | 批量同步中连续 OAuth 配额获取之间的间隔（毫秒）；OAuth 连接逐个获取以避免冲击上游。`0` 表示退出（并发）。 | +| `PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS` | `5000` | `src/lib/usage/providerLimits.ts` | 真实用量事件后刷新服务商限制前的延迟（毫秒），给上游配额 API 时间记录消费。 | +| `OMNIROUTE_DISABLE_BACKGROUND_SERVICES` | `false` | `src/instrumentation-node.ts` | 禁用所有后台服务（同步、价格、模型刷新）。适用于 CI/测试。 | +| `OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS` | _(未设置)_ | `src/lib/config/runtimeSettings.ts` | 在自动测试检测下强制运行后台任务。设为 `1` 可覆盖测试推断。 | +| `OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS` | `600000` | `src/lib/jobs/budgetResetJob.ts` | 预算重置检查频率（毫秒）。最低 `10000`。 | +| `OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS` | `60000` | `src/lib/quota/connectionRecovery.ts` | 主动连接冷却恢复频率（毫秒）：对瞬态 `rate_limited_until` 已过期的连接进行重新校验，脱离请求热路径。最低 `5000`。 | +| `OMNIROUTE_DISABLE_CONNECTION_RECOVERY` | `false` | `src/lib/quota/connectionRecovery.ts` | 禁用主动连接冷却恢复调度器（`getProviderCredentials` 中的惰性恢复仍然生效）。 | +| `OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS` | `1800000` | `src/lib/jobs/reasoningCacheCleanupJob.ts` | 推理缓存清理频率（毫秒）。最低 `60000`。 | +| `OMNIROUTE_CONFIG_HOT_RELOAD_MS` | `5000` | `src/lib/config/hotReload.ts` | 配置热加载的轮询间隔（毫秒）。低于 `1000` 会被拒绝。 | +| `OMNIROUTE_DISABLE_REDIS_AUTH_CACHE` | _(启用)_ | `src/lib/db/apiKeys.ts` | 设为 `1` 可绕过 Redis 支持的 API Key 认证缓存（强制走数据库读取）。 | +| `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | `0` | `open-sse/services/compression/engines/rtk/filterLoader.ts` | 信任用户管理的 RTK 项目过滤器规则，无需严格的签名检查。 | +| `OMNIROUTE_BOOTSTRAPPED` | `false` | `src/app/(dashboard)/dashboard/page.tsx` | 引导脚本在初始设置后设为 `true`。控制设置向导的可见性。 | +| `OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE` | `0` | `open-sse/executors/antigravity.ts` | 逃生口：允许请求体覆盖 Antigravity 项目字段。 | +| `ANTIGRAVITY_CREDITS` | _(未设置)_ | `open-sse/services/antigravityCredits.ts` | 覆盖 Antigravity 的广告剩余积分（测试/强制值）。 | +| `AGY_TOKEN_FILE` | `~/.gemini/antigravity-cli/antigravity-oauth-token` | `src/app/api/providers/agy-auth/apply-local/route.ts` | 覆盖自动检测本地登录导入的 Antigravity CLI (agy) Token 文件路径。 | + +### OAuth CLI 桥接（内部） + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_SERVER` | 自动检测 | `src/lib/oauth/config/index.ts` | CLI↔OmniRoute 认证桥接的服务器 URL。 | +| `OMNIROUTE_TOKEN` | _(未设置)_ | `src/lib/oauth/config/index.ts` | CLI 桥接的认证 Token。 | +| `OMNIROUTE_USER_ID` | `cli` | `src/lib/oauth/config/index.ts` | CLI 桥接会话的用户 ID。 | +| `SERVER_URL` | _(未设置)_ | `src/lib/oauth/config/index.ts` | `OMNIROUTE_SERVER` 的旧版别名。 | +| `CLI_TOKEN` | _(未设置)_ | `src/lib/oauth/config/index.ts` | `OMNIROUTE_TOKEN` 的旧版别名。 | +| `CLI_USER_ID` | _(未设置)_ | `src/lib/oauth/config/index.ts` | `OMNIROUTE_USER_ID` 的旧版别名。 | + +--- + +## 11. OAuth 服务商凭证 + +用于 **localhost 开发** 的内置凭证。对于远程部署，请在各个服务商的开发者控制台中注册你自己的凭证。 + +| 变量 | 服务商 | 备注 | +| --- | --- | --- | +| `CLAUDE_OAUTH_CLIENT_ID` | Claude Code (Anthropic) | 公共客户端 — 无需 secret。 | +| `CLAUDE_CODE_REDIRECT_URI` | Claude Code | 覆盖重定向 URI。默认值：`https://platform.claude.com/oauth/code/callback` | +| `CODEX_OAUTH_CLIENT_ID` | Codex / OpenAI | 公共客户端。 | +| `GEMINI_OAUTH_CLIENT_ID` | Gemini (Google) | 需要匹配的 `_SECRET`。 | +| `GEMINI_OAUTH_CLIENT_SECRET` | Gemini (Google) | — | +| `QWEN_OAUTH_CLIENT_ID` | Qwen (Alibaba) | 公共客户端。 | +| `KIMI_CODING_OAUTH_CLIENT_ID` | Kimi Coding (Moonshot) | 公共客户端。 | +| `ANTIGRAVITY_OAUTH_CLIENT_ID` | Antigravity (Google) | 需要匹配的 `_SECRET`。 | +| `ANTIGRAVITY_OAUTH_CLIENT_SECRET` | Antigravity (Google) | — | +| `GITHUB_OAUTH_CLIENT_ID` | GitHub Copilot | 公共客户端。 | +| `WINDSURF_FIREBASE_API_KEY` | Windsurf / Devin (v3.8) | Windsurf 安全 Token 服务用于刷新的公共 Firebase Web API key。客户端凭证（非密钥）。长期导入 Token 完全跳过此步骤。来源：从 Devin CLI 二进制文件中提取。 | +| `WINDSURF_API_KEY` | Windsurf / Devin (v3.8) | 无每个连接凭证时 `open-sse/executors/devin-cli.ts` 使用的 API key 回退。可选。 | +| `CLI_DEVIN_BIN` | Devin CLI (v3.8) | Devin CLI 二进制文件（`devin`）的自定义路径。由 `open-sse/executors/devin-cli.ts` 解析。 | +| `GITLAB_DUO_OAUTH_CLIENT_ID` | GitLab Duo (v3.8) | GitLab Duo 的 OAuth client ID。在 `https://gitlab.com/-/profile/applications` 注册应用，redirect URI 为 `/callback`，权限域为 `api, read_user, openid, profile, email`。回退到 `GITLAB_OAUTH_CLIENT_ID`。 | +| `GITLAB_DUO_OAUTH_CLIENT_SECRET` | GitLab Duo (v3.8) | GitLab Duo 的 OAuth client secret。可选 — PKCE 流程不需要 secret。回退到 `GITLAB_OAUTH_CLIENT_SECRET`。 | +| `GITLAB_DUO_BASE_URL` | GitLab Duo (v3.8) | 覆盖 GitLab 基础 URL（自托管 GitLab）。默认为 `https://gitlab.com`。回退到 `GITLAB_BASE_URL`。 | +| `GITLAB_BASE_URL` | GitLab Duo (v3.8) | `GITLAB_DUO_BASE_URL` 的旧版回退。在 `_DUO_` 变体未设置时使用。 | +| `GITLAB_OAUTH_CLIENT_ID` | GitLab Duo (v3.8) | `GITLAB_DUO_OAUTH_CLIENT_ID` 的旧版回退，由 `src/lib/oauth/constants/oauth.ts` 使用。 | +| `GITLAB_OAUTH_CLIENT_SECRET` | GitLab Duo (v3.8) | `GITLAB_DUO_OAUTH_CLIENT_SECRET` 的旧版回退，由 `src/lib/oauth/constants/oauth.ts` 使用。 | +| `QODER_OAUTH_CLIENT_SECRET` | Qoder | — | +| `QODER_OAUTH_AUTHORIZE_URL` | Qoder | 设置以启用 Qoder OAuth。 | +| `QODER_OAUTH_TOKEN_URL` | Qoder | — | +| `QODER_OAUTH_USERINFO_URL` | Qoder | — | +| `QODER_OAUTH_CLIENT_ID` | Qoder | — | +| `QODER_PERSONAL_ACCESS_TOKEN` | Qoder | 直接 API key 回退（绕过 OAuth）。 | +| `QODER_CLI_WORKSPACE` | Qoder | Qoder CLI 的 workspace ID。 | +| `OMNIROUTE_QODER_WORKSPACE` | Qoder | `QODER_CLI_WORKSPACE` 的别名。 | +| `BLACKBOX_WEB_VALIDATED_TOKEN` | Blackbox Web | 作为 `validated` 发送到 `/api/chat` 的前端 `tk` Token。当 Blackbox 强制 Token 匹配时必需；否则 OmniRoute 回退到随机 UUID。参阅 issue #2252。 | +| `VISION_BRIDGE_BASE_URL` | Vision Bridge 安全护栏 | 非 Anthropic 视觉桥接调用的 OpenAI 兼容基础 URL。默认为旧版 OpenAI URL 或 api.openai.com。指向 OmniRoute 的 `/v1` 自循环或任意 OpenAI 兼容端点（Gemini OpenAI-compat、OpenRouter）。Issue #2232。 | +| `VISION_BRIDGE_API_KEY` | Vision Bridge 安全护栏 | 上面 URL 的 API key。对于非 Anthropic 视觉桥接调用，覆盖每个服务商的 OpenAI / Google 环境变量。Anthropic 模型保留其专用的 Anthropic key 路径。Issue #2232。 | > [!WARNING] > -> 1. Go to [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials) -> 2. Create an OAuth 2.0 Client ID (type: "Web application") -> 3. Add your server URL as Authorized redirect URI -> 4. Replace the credential values in `.env`. +> 1. 前往 [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials) +> 2. 创建一个 OAuth 2.0 Client ID（类型："Web application"） +> 3. 将你的服务器 URL 添加为授权的 redirect URI +> 4. 在 `.env` 中替换凭证值。 --- -## 12. Provider User-Agent Overrides +## 12. 服务商 User-Agent 覆盖 -Override the `User-Agent` header sent to each upstream provider. This is dynamically resolved at runtime by the executor base class: +覆盖发送到每个上游服务商的 `User-Agent` 头。由 executor 基类在运行时动态解析： ``` process.env[`${PROVIDER_ID}_USER_AGENT`] ``` -> **Source:** `open-sse/executors/base.ts` → `buildHeaders()` - -| Variable | Default Value | When to Update | -| ------------------------ | --------------------------------------------- | ------------------------------------------------------------- | -| `CLAUDE_USER_AGENT` | `claude-cli/2.1.145 (external, cli)` | When Anthropic releases a new CLI version | -| `CODEX_USER_AGENT` | `codex-cli/0.132.0 (Windows 10.0.26200; x64)` | When OpenAI updates the Codex CLI | -| `CODEX_CLIENT_VERSION` | `0.131.0` | Override Codex client version independently of full UA string | -| `GITHUB_USER_AGENT` | `GitHubCopilotChat/0.45.1` | When GitHub Copilot Chat updates | -| `ANTIGRAVITY_USER_AGENT` | `antigravity/2.0.1 darwin/arm64` | When Antigravity IDE updates | -| `KIRO_USER_AGENT` | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0` | When Kiro IDE updates | -| `QODER_USER_AGENT` | `Qoder-Cli` | When Qoder CLI updates | -| `QWEN_USER_AGENT` | `QwenCode/0.15.11 (linux; x64)` | When Qwen Code updates | -| `CURSOR_USER_AGENT` | `connect-es/1.6.1` | When Cursor updates | +> **来源：** `open-sse/executors/base.ts` → `buildHeaders()` + +| 变量 | 默认值 | 何时更新 | +| --- | --- | --- | +| `CLAUDE_USER_AGENT` | `claude-cli/2.1.195 (external, cli)` | Anthropic 发布新的 CLI 版本时 | +| `CLAUDE_DISABLE_TOOL_NAME_CLOAK` | `false` | `executors/base.ts` + `executors/cliproxyapi.ts` | 设为 `1`/`true` 可将第三方测试工具的工具名称原封不动地转发到 Anthropic 的两条绑定路径上（原生 OAuth 和 CLIProxyAPI）。默认情况下 executor 会将非 Claude Code 的工具名称确定性别名化（Claude Code 存在规范映射的用规范映射，否则用 PascalCase），并通过 `_toolNameMap` 在响应中还原，从而确保带 snake_case 工具的测试工具不会被视为指纹化第三方客户端而被拒绝。仅供调试。 | +| `CODEX_USER_AGENT` | `codex-cli/0.142.0 (Windows 10.0.26200; x64)` | OpenAI 更新 Codex CLI 时 | +| `CODEX_CLIENT_VERSION` | `0.131.0` | 独立于完整 UA 字符串覆盖 Codex 客户端版本 | +| `GITHUB_USER_AGENT` | `GitHubCopilotChat/0.54.0` | GitHub Copilot Chat 更新时 | +| `ANTIGRAVITY_USER_AGENT` | `antigravity/2.0.1 darwin/arm64` | Antigravity IDE 更新时 | +| `KIRO_USER_AGENT` | `AWS-SDK-JS/3.0.0 kiro-ide/1.0.0` | Kiro IDE 更新时 | +| `KIRO_OAUTH_CLIENT_ID` | `kiro-cli` | 覆盖 Kiro social device-code `clientId`（公共 ID） | +| `KIRO_VERIFY_FULL_CRC` | `false` | 启用：在 Kiro 事件流上全帧消息 CRC 校验（调试损坏的流） | +| `QODER_USER_AGENT` | `Qoder-Cli` | Qoder CLI 更新时 | +| `QWEN_USER_AGENT` | `QwenCode/0.19.3 (linux; x64)` | Qwen Code 更新时 | +| `CURSOR_USER_AGENT` | `Cursor/3.3` | Cursor 更新时 | > [!TIP] -> You can add User-Agent overrides for **any** provider using the pattern `{PROVIDER_ID}_USER_AGENT`. The executor dynamically constructs the env var name. +> 你可以通过 `{PROVIDER_ID}_USER_AGENT` 模式为 **任意** 服务商添加 User-Agent 覆盖。Executor 会动态构建环境变量名。 --- -## 13. CLI Fingerprint Compatibility +## 13. CLI 指纹兼容 -When enabled, OmniRoute reorders HTTP headers and JSON body fields to match the exact signature of official CLI tools. This reduces the risk of account flagging while preserving your proxy IP. +启用后，OmniRoute 会重排 HTTP 头和 JSON body 字段以匹配官方 CLI 工具的精确签名。在保留代理 IP 的同时，降低账户被标记的风险。 -**Source:** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts` +**来源：** `open-sse/config/cliFingerprints.ts`, `open-sse/executors/base.ts` -### Per-Provider +### 按服务商 -| Variable | Effect | -| -------------------------- | --------------------------------------- | -| `CLI_COMPAT_CODEX=1` | Mimics Codex CLI request signature | -| `CLI_COMPAT_CLAUDE=1` | Mimics Claude Code request signature | -| `CLI_COMPAT_GITHUB=1` | Mimics GitHub Copilot request signature | -| `CLI_COMPAT_ANTIGRAVITY=1` | Mimics Antigravity request signature | -| `CLI_COMPAT_KIRO=1` | Mimics Kiro IDE request signature | -| `CLI_COMPAT_CURSOR=1` | Mimics Cursor request signature | -| `CLI_COMPAT_KIMI_CODING=1` | Mimics Kimi Coding request signature | -| `CLI_COMPAT_KILOCODE=1` | Mimics Kilo Code request signature | -| `CLI_COMPAT_CLINE=1` | Mimics Cline request signature | -| `CLI_COMPAT_QWEN=1` | Mimics Qwen Code request signature | +| 变量 | 激活方式 | 效果 | +| --- | --- | --- | +| `CLI_COMPAT_CODEX` | `=1` | 模拟 Codex CLI 请求签名 | +| `CLI_COMPAT_CLAUDE` | `=1` | 模拟 Claude Code 请求签名 | +| `CLI_COMPAT_GITHUB` | `=1` | 模拟 GitHub Copilot 请求签名 | +| `CLI_COMPAT_ANTIGRAVITY` | `=1` | 模拟 Antigravity 请求签名 | +| `CLI_COMPAT_CURSOR` | `=1` | 模拟 Cursor 请求签名 | +| `CLI_COMPAT_KIMI_CODING` | `=1` | 模拟 Kimi Coding 请求签名 | +| `CLI_COMPAT_KILOCODE` | `=1` | 模拟 Kilo Code 请求签名 | +| `CLI_COMPAT_CLINE` | `=1` | 模拟 Cline 请求签名 | +| `CLI_COMPAT_QWEN` | `=1` | 模拟 Qwen Code 请求签名 | -### Global +### 全局 -| Variable | Effect | -| ------------------ | --------------------------------------------------------------- | -| `CLI_COMPAT_ALL=1` | Enable fingerprint compatibility for **all** providers at once. | +| 变量 | 激活方式 | 效果 | +| --- | --- | --- | +| `CLI_COMPAT_ALL` | `=1` | 一次性为**所有**服务商启用指纹兼容。 | + +### Kimi Coding CLI 身份标识覆盖 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `KIMI_CLI_VERSION` | `1.36.0` | `src/lib/oauth/providers/kimi-coding.ts` | 覆盖 OAuth/API 调用时发送的 Kimi CLI 版本。 | +| `KIMI_CODING_DEVICE_ID` | _(已捕获的默认值)_ | `src/lib/oauth/providers/kimi-coding.ts` | 覆盖客户端头中使用的已捕获 Kimi 设备 ID。 | > [!NOTE] -> This feature works alongside the User-Agent overrides (§12). The fingerprint system handles header ordering and body field ordering, while User-Agent overrides handle the specific UA string. Both can be enabled independently. +> 此功能与 User-Agent 覆盖（§12）协同工作。指纹系统处理头部排序和 body 字段排序，User-Agent 覆盖处理具体的 UA 字符串。两者可独立启用。 --- -## 14. API Key Providers +## 14. API Key 服务商 -API keys for providers that use direct authentication. **Preferred setup:** Dashboard → Providers → Add API Key. +使用直接认证的服务商的 API key。**推荐配置方式：** Dashboard → Providers → Add API Key。 -Setting via environment variables is an alternative for Docker or headless deployments. +通过环境变量设置是 Docker 或无头部署的替代方式。 -Recognized pattern: `{PROVIDER_ID}_API_KEY` +识别模式：`{PROVIDER_ID}_API_KEY` -| Variable | Provider | -| -------------------- | ------------------- | -| `DEEPSEEK_API_KEY` | DeepSeek | -| `GROQ_API_KEY` | Groq | -| `XAI_API_KEY` | xAI (Grok) | -| `MISTRAL_API_KEY` | Mistral AI | -| `PERPLEXITY_API_KEY` | Perplexity | -| `TOGETHER_API_KEY` | Together AI | -| `FIREWORKS_API_KEY` | Fireworks AI | -| `CEREBRAS_API_KEY` | Cerebras | -| `COHERE_API_KEY` | Cohere | -| `NVIDIA_API_KEY` | NVIDIA NIM | -| `NEBIUS_API_KEY` | Nebius (embeddings) | +| 变量 | 服务商 | +| --- | --- | +| `DEEPSEEK_API_KEY` | DeepSeek | +| `NVIDIA_API_KEY` | NVIDIA NIM | + +> [!NOTE] +> 在 v3.8.0 中移除了 Groq、xAI、Mistral、Perplexity、Together AI、Fireworks、Cerebras、Cohere、Nebius 和 Qianfan 的静态 `${PROVIDER}_API_KEY` 条目，因为运行时不再读取它们 — 这些服务商仅通过 Dashboard / `data/provider-credentials.json` / 加密数据库获取凭证。参阅本文档末尾的 _审计：已移除/废弃的变量_ 部分了解迁移路径。 > [!TIP] -> Keys set via the Dashboard are stored encrypted in SQLite and take precedence over environment variables. +> 通过 Dashboard 设置的 Key 会加密存储在 SQLite 中，优先级高于环境变量。 --- -## 15. Timeout Settings +## 15. 超时设置 -All values are in **milliseconds**. Centralized resolution in `src/shared/utils/runtimeTimeouts.ts`. +所有值均以 **毫秒** 为单位。集中解析在 `src/shared/utils/runtimeTimeouts.ts`。 -### Timeout Hierarchy +### 超时层级 ``` -REQUEST_TIMEOUT_MS (global override) -├─→ FETCH_TIMEOUT_MS (upstream provider calls, default: 600000) -│ ├─→ FETCH_HEADERS_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) -│ ├─→ FETCH_BODY_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) -│ ├─→ TLS_CLIENT_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS) -│ ├── FETCH_CONNECT_TIMEOUT_MS (independent, default: 30000) -│ └── FETCH_KEEPALIVE_TIMEOUT_MS (independent, default: 4000) -├─→ STREAM_IDLE_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000) -└─→ API_BRIDGE_PROXY_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000) - ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derived, default: 600000) - ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (default: 60000) - ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (default: 5000) - └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (default: 0 = disabled) +REQUEST_TIMEOUT_MS (全局覆盖) +├─→ FETCH_TIMEOUT_MS (上游服务商调用, 默认值: 600000) +│ ├─→ FETCH_HEADERS_TIMEOUT_MS (继承自 FETCH_TIMEOUT_MS) +│ ├─→ FETCH_BODY_TIMEOUT_MS (继承自 FETCH_TIMEOUT_MS) +│ ├─→ TLS_CLIENT_TIMEOUT_MS (继承自 FETCH_TIMEOUT_MS) +│ ├── FETCH_CONNECT_TIMEOUT_MS (独立, 默认值: 30000) +│ └── FETCH_KEEPALIVE_TIMEOUT_MS (独立, 默认值: 4000) +├─→ STREAM_IDLE_TIMEOUT_MS (继承自 REQUEST_TIMEOUT_MS, 默认值: 600000) +├─→ STREAM_READINESS_TIMEOUT_MS (继承自 REQUEST_TIMEOUT_MS, 默认值: 80000) +└─→ API_BRIDGE_PROXY_TIMEOUT_MS (继承自 REQUEST_TIMEOUT_MS, 默认值: 30000) + ├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (派生, 默认值: 300000) + ├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (默认值: 60000) + ├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (默认值: 5000) + └── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (默认值: 0 = 禁用) ``` -| Variable | Default | Description | -| ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------- | -| `REQUEST_TIMEOUT_MS` | _(unset)_ | Global shortcut — overrides both `FETCH_TIMEOUT_MS` and `STREAM_IDLE_TIMEOUT_MS` defaults. | -| `FETCH_TIMEOUT_MS` | `600000` | Total HTTP request timeout for upstream provider calls. | -| `STREAM_IDLE_TIMEOUT_MS` | `600000` | Max silence between SSE chunks before aborting. Extended-thinking models rarely pause >90s. | -| `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Time to receive response headers. | -| `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | Time to receive the full response body. | -| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | TCP connection establishment timeout. | -| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Keep-alive socket idle timeout. | -| `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | TLS fingerprint proxy (wreq-js) timeout. | -| `API_BRIDGE_PROXY_TIMEOUT_MS` | `600000` | Proxy hop timeout for `/v1` bridge requests. | -| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `600000` | Overall server request timeout for the bridge. | -| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Time to send response headers via the bridge. | -| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Bridge keep-alive idle timeout. | -| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Raw socket timeout (0 = disabled). | -| `SHUTDOWN_TIMEOUT_MS` | `30000` | Grace period on SIGTERM/SIGINT before force-exit. | - -### Scenarios - -| Scenario | Configuration | -| -------------------------------- | ------------------------------------------------------ | -| **Long-running code generation** | `REQUEST_TIMEOUT_MS=900000` (15 min) | -| **Fast-fail for production API** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000` | -| **Extended thinking models** | `STREAM_IDLE_TIMEOUT_MS=300000` (5 min between chunks) | - ---- - -## 16. Logging - -The logging system writes to both stdout and rotated log files. All configuration is read by `src/lib/logEnv.ts`. - -| Variable | Default | Description | -| --------------------------- | -------------------------- | ---------------------------------------------------------------------------- | -| `APP_LOG_LEVEL` | `info` | Minimum log level: `debug`, `info`, `warn`, `error`. | -| `APP_LOG_FORMAT` | `text` | Output format: `text` (human-readable) or `json` (structured). | -| `APP_LOG_TO_FILE` | `true` | Write logs to file alongside stdout. | -| `APP_LOG_FILE_PATH` | `logs/application/app.log` | Log file path (relative to project root or `DATA_DIR`). | -| `APP_LOG_MAX_FILE_SIZE` | `50M` | Max file size before rotation. Accepts: `50M`, `1G`, `512K`, or plain bytes. | -| `APP_LOG_RETENTION_DAYS` | `7` | Days to keep rotated application log files. | -| `APP_LOG_MAX_FILES` | `20` | Maximum rotated log file backups. | -| `CALL_LOG_RETENTION_DAYS` | `7` | Days to keep request/call log entries in the database. | -| `CALL_LOG_MAX_ENTRIES` | `10000` | Max call log entries in the in-memory buffer. | -| `CALL_LOGS_TABLE_MAX_ROWS` | `100000` | Max rows in the `call_logs` SQLite table before pruning. | -| `PROXY_LOGS_TABLE_MAX_ROWS` | `100000` | Max rows in the `proxy_logs` SQLite table before pruning. | - ---- - -## 17. Memory Optimization - -| Variable | Default | Description | -| -------------------------- | ------------------------------- | ---------------------------------------------------------------------- | -| `OMNIROUTE_MEMORY_MB` | `512` | Runtime V8 heap limit. Docker standalone and `omniroute serve` use it to set `--max-old-space-size`. | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max cached system prompt entries. | -| `PROMPT_CACHE_MAX_BYTES` | `2097152` (2 MB) | Max total prompt cache size. | -| `PROMPT_CACHE_TTL_MS` | `300000` (5 min) | Prompt cache entry TTL. | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max cached temperature=0 responses. | -| `SEMANTIC_CACHE_MAX_BYTES` | `4194304` (4 MB) | Max total semantic cache size. | -| `SEMANTIC_CACHE_TTL_MS` | `1800000` (30 min) | Semantic cache entry TTL. | -| `STREAM_HISTORY_MAX` | `50` | Max recent stream events in the Dashboard live view buffer. | -| `CONTEXT_LENGTH_DEFAULT` | `128000` | Global fallback max context length for models without explicit config. | -| `USAGE_TOKEN_BUFFER` | `100` | Extra token headroom reserved when tracking usage quotas. | - -### Low-RAM Docker Example +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `REQUEST_TIMEOUT_MS` | _(未设置)_ | 全局快捷方式 — 覆盖 `FETCH_TIMEOUT_MS` 和 `STREAM_IDLE_TIMEOUT_MS` 两者的默认值。 | +| `FETCH_TIMEOUT_MS` | `600000` | 上游服务商调用的 HTTP 请求总超时。 | +| `STREAM_IDLE_TIMEOUT_MS` | `600000` | SSE 块之间的最长静默时间，超时则中止。扩展推理模型很少暂停超过 90 秒。 | +| `STREAM_READINESS_TIMEOUT_MS` | `80000` | 接收第一个非 ping SSE 事件的超时时间。设置时继承 `REQUEST_TIMEOUT_MS`。 | +| `OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS` | _(关闭)_ | 剥离会导致 OpenAI SDK 的 `responses.stream()` 以 502 报错的非标准 `codex.*` SSE 事件（如 `codex.rate_limits`）。设为 `true`/`1`/`yes` 可启用。 | +| `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收响应头的超时时间。 | +| `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收完整响应体的超时时间。 | +| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | TCP 连接建立超时。 | +| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Keep-alive 套接字空闲超时。 | +| `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | TLS 指纹代理（wreq-js）超时。 | +| `API_BRIDGE_PROXY_TIMEOUT_MS` | `30000` | `/v1` 桥接请求的代理跳超时。 | +| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `300000` | 桥接的服务器请求总超时。 | +| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | 通过桥接发送响应头的超时时间。 | +| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | 桥接 keep-alive 空闲超时。 | +| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | 原始套接字超时（0 = 禁用）。 | +| `SHUTDOWN_TIMEOUT_MS` | `30000` | SIGTERM/SIGINT 后强制退出前的宽限期。 | +| `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | `FETCH_TIMEOUT_MS` 未设置时 `src/shared/utils/fetchTimeout.ts` 使用的回退值。 | +| `OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`chatgptTlsClient.ts`）。 | +| `OMNIROUTE_CHATGPT_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 | +| `OMNIROUTE_CHATGPT_STREAM_FIRST_BYTE_TIMEOUT_MS` | `30000`（30 秒） | ChatGPT TLS sidecar（`chatgptTlsClient.ts`）在中止死流前等待第一个流式字节的最大时间。如果上游冷启动超过窗口则提高。 | +| `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`claudeTlsClient.ts`）。 | +| `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 | +| `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`perplexityTlsClient.ts`）。 | +| `OMNIROUTE_PPLX_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 | +| `OMNIROUTE_GROK_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`grokTlsClient.ts`）。 | +| `OMNIROUTE_GROK_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 | +| `OMNIROUTE_BROWSER_POOL` | `on` | 用于浏览器端 Web Cookie 聊天的共享 Playwright 浏览器池（`browserPool.ts`）；设为 `off` 可禁用。 | +| `WEB_COOKIE_USE_BROWSER` | `0` | 将 Web Cookie 聊天请求选择进入浏览器端路径（`browserBackedChat.ts`）；`1` 启用。 | + +Combo 目标尝试继承已解析的上游请求超时（`FETCH_TIMEOUT_MS`，或当它提供 fetch 默认值时的 `REQUEST_TIMEOUT_MS`）。仅在 Combo 中设置 `targetTimeoutMs`、Combo 默认值或服务商覆盖值以加快 Combo 回退；超过当前上游超时的值会被截断到上游超时。 + +### 熔断器阈值 + +服务商级熔断器调优。默认值反映了 v3.6 以来用于 500+ 连接的缩放值。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD` | `8` | `open-sse/config/constants.ts` | OAuth 服务商的连续失败阈值，超过则熔断器跳开。 | +| `OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS` | `60000` | `open-sse/config/constants.ts` | OAuth 服务商熔断器的重置窗口（毫秒）。 | +| `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD` | `12` | `open-sse/config/constants.ts` | API-key 服务商的连续失败阈值。 | +| `OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS` | `30000` | `open-sse/config/constants.ts` | API-key 服务商熔断器的重置窗口（毫秒）。 | +| `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD` | `2` | `open-sse/config/constants.ts` | 本地服务商（Ollama、LM Studio 等）的连续失败阈值。 | +| `OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS` | `15000` | `open-sse/config/constants.ts` | 本地服务商熔断器的重置窗口（毫秒）。 | +| `PIN_DROP_BACKOFF_LEVEL` | `2` | `open-sse/services/combo.ts` | 退避深度，达到此值后上下文缓存 pin 的服务商被视为持续不健康，pin 被丢弃以进行故障转移。 | +| `PIN_DROP_GRACE_MS` | `20000` | `open-sse/services/combo.ts` | 防抖窗口（毫秒），在丢弃上下文缓存 pin 之前容忍短暂的瞬态冷却。 | + +### 场景 + +| 场景 | 配置 | +| --- | --- | +| **长时间代码生成** | `REQUEST_TIMEOUT_MS=900000`（15 分钟） | +| **生产 API 快速失败** | `API_BRIDGE_PROXY_TIMEOUT_MS=10000` | +| **扩展推理模型** | `STREAM_IDLE_TIMEOUT_MS=300000`（块间 5 分钟） | + +--- + +## 16. 日志 + +日志系统同时写入 stdout 和轮转日志文件。所有配置由 `src/lib/logEnv.ts` 读取。 + +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `APP_LOG_LEVEL` | `info` | 最低日志级别：`debug`、`info`、`warn`、`error`。 | +| `APP_LOG_FORMAT` | `text` | 输出格式：`text`（人类可读）或 `json`（结构化）。 | +| `APP_LOG_TO_FILE` | `true` | 同时写入日志文件和 stdout。 | +| `APP_LOG_FILE_PATH` | `logs/application/app.log` | 日志文件路径（相对于项目根目录或 `DATA_DIR`）。 | +| `APP_LOG_MAX_FILE_SIZE` | `50M` | 轮转前的最大文件大小。可接受：`50M`、`1G`、`512K` 或纯字节数。 | +| `APP_LOG_RETENTION_DAYS` | `7` | 保留轮转后应用日志文件的天数。 | +| `APP_LOG_MAX_FILES` | `20` | 最大轮转日志文件备份数。 | +| `CALL_LOG_RETENTION_DAYS` | `7` | 在数据库中保留请求/调用日志条目的天数。 | +| `CALL_LOG_MAX_ENTRIES` | `10000` | 内存缓冲区中最大调用日志条目数。 | +| `CALL_LOGS_TABLE_MAX_ROWS` | `100000` | `call_logs` SQLite 表在清理前的最大行数。 | +| `MAX_PENDING_REQUEST_AGE_MS` | `3600000`（1 小时） | 孤立活跃请求日志条目在内存清理前的最大生存时间。 | +| `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS` | `true` | 当 `call_log_pipeline_enabled=true` 时在 pipeline artifacts 中存储流块。 | +| `CALL_LOG_PIPELINE_MAX_SIZE_KB` | `512` | 当 `call_log_pipeline_enabled=true` 时的最大 pipeline 调用日志工件大小（KB）。 | +| `PROXY_LOGS_TABLE_MAX_ROWS` | `100000` | `proxy_logs` SQLite 表在清理前的最大行数。 | +| `APP_LOG_ROTATION_CHECK_INTERVAL_MS` | `60000`（1 分钟） | `src/lib/logRotation.ts` 重新检查活跃日志文件大小的频率。 | +| `CHAT_LOG_TEXT_LIMIT` | `65536` | 聊天日志工件中保留的最大字符串长度（默认 64 KB）。 | +| `CHAT_LOG_ARRAY_TAIL_ITEMS` | `24` | 截断聊天日志载荷时从尾部保留的数组项数量。 | +| `CHAT_LOG_MAX_DEPTH` | `6` | 聊天日志载荷被截断前的最大嵌套深度。 | +| `CHAT_DEBUG_FILE` | `false` | 设为 true 时，`serializeArtifactForStorage` 跳过基于大小的截断。仅供调试。 | + +--- + +## 17. 内存优化 + +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `OMNIROUTE_MEMORY_MB` | _自动_ | 运行时 V8 堆限制（MB）。未设置时动态校准（约 35% 系统内存，限制在 `[512, 4096]`）；`512` 仅是总内存不可读取时的下限。显式设置以覆盖。Docker 独立运行和 `omniroute serve` 用它设置 `--max-old-space-size`。 | +| `PROMPT_CACHE_MAX_SIZE` | `50` | 最大缓存系统提示条目数。 | +| `PROMPT_CACHE_MAX_BYTES` | `2097152`（2 MB） | 最大提示缓存总大小。 | +| `PROMPT_CACHE_TTL_MS` | `300000`（5 分钟） | 提示缓存条目 TTL。 | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | 最大缓存 temperature=0 响应数。 | +| `SEMANTIC_CACHE_MAX_BYTES` | `4194304`（4 MB） | 最大语义缓存总大小。 | +| `SEMANTIC_CACHE_TTL_MS` | `1800000`（30 分钟） | 语义缓存条目 TTL。 | +| `STREAM_HISTORY_MAX` | `50` | Dashboard 实时视图缓冲区中最大近期流事件数。 | +| `CONTEXT_LENGTH_DEFAULT` | `128000` | 没有显式配置的模型的全局回退最大上下文长度。 | +| `USAGE_TOKEN_BUFFER` | `100` | 跟踪用量配额时保留的额外 Token 余量。 | + +### 压缩 + +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | 未设置 | 无需 `.rtk/trust.json` 哈希即可信任项目 `.rtk/filters.json`。仅在受控的本地开发中使用。 | + +### 记忆引擎（plan 21） + +持久记忆子系统（`src/lib/memory/`）的嵌入层、向量存储和重排序开关。 + +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `MEMORY_EMBEDDING_CACHE_TTL_MS` | `300000`（5 分钟） | 内存嵌入缓存（每个源/模型/维度签名）的 TTL。 | +| `MEMORY_EMBEDDING_CACHE_MAX` | `1000` | 嵌入缓存中保留的最大 LRU 条目数。 | +| `MEMORY_TRANSFORMERS_MODEL` | `Xenova/all-MiniLM-L6-v2` | 用于可选的 `@huggingface/transformers` 本地 MiniLM 管线的 HF 仓库 ID（约 23 MB int8，约 400 MB RAM）。 | +| `MEMORY_STATIC_MODEL` | `minishlab/potion-base-8M` | 用于静态 potion/Model2Vec 查找表嵌入器的 HF 仓库 ID。懒加载下载到缓存目录。 | +| `MEMORY_STATIC_CACHE_DIR` | `/embeddings` | 用于缓存静态 potion 模型文件的目录。未设置时默认为 `DATA_DIR` 下。 | +| `MEMORY_VEC_TOP_K` | `20` | `src/lib/memory/vectorStore.ts` 内部 `sqlite-vec` 暴力向量搜索使用的默认 top-K。 | +| `MEMORY_RRF_K` | `60` | FTS5 + 向量混合检索的 Reciprocal Rank Fusion 常数 `k`（sqlite-vec 方案）。 | +| `HF_HUB_ENDPOINT` | `https://huggingface.co` | 覆盖 `staticPotion.ts` 使用的 Hugging Face Hub 基础 URL（如气隙环境下的镜像端点）。 | + +### 低内存 Docker 示例 ```bash OMNIROUTE_MEMORY_MB=128 @@ -507,85 +715,152 @@ STREAM_HISTORY_MAX=10 --- -## 18. Pricing Sync +## 18. 价格同步 -Automatic model pricing data synchronization from external sources. +从外部源自动同步模型价格数据。 -| Variable | Default | Source File | Description | -| ----------------------- | ------------- | ------------------------ | ----------------------------- | -| `PRICING_SYNC_ENABLED` | `false` | `src/lib/pricingSync.ts` | Opt-in periodic pricing sync. | -| `PRICING_SYNC_INTERVAL` | `86400` (24h) | `src/lib/pricingSync.ts` | Sync interval in seconds. | -| `PRICING_SYNC_SOURCES` | `litellm` | `src/lib/pricingSync.ts` | Comma-separated data sources. | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `PRICING_SYNC_ENABLED` | `false` | `src/lib/pricingSync.ts` | 可选的定期价格同步。 | +| `PRICING_SYNC_INTERVAL` | `86400`（24 小时） | `src/lib/pricingSync.ts` | 同步间隔，秒。 | +| `PRICING_SYNC_SOURCES` | `litellm` | `src/lib/pricingSync.ts` | 逗号分隔的数据源。 | --- -## 19. Model Sync (Dev) +## Arena ELO 同步 -| Variable | Default | Source File | Description | -| -------------------------- | ------------- | -------------------------- | -------------------------------------------------------- | -| `MODELS_DEV_SYNC_INTERVAL` | `86400` (24h) | `src/lib/modelsDevSync.ts` | Development-time model catalog sync interval in seconds. | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `ARENA_ELO_SYNC_ENABLED` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | 定期 Arena AI 排行榜 ELO 同步，可从 Dashboard Feature Flags 配置或设为 `false` 退出。 | +| `ARENA_ELO_SYNC_INTERVAL` | `86400`（24 小时） | `src/lib/arenaEloSync.ts` | 同步间隔，秒。 | --- -## 20. Provider-Specific Settings +## 19. 模型同步（开发） -| Variable | Default | Source File | Description | -| ----------------------------------------- | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------- | -| `OPENROUTER_CATALOG_TTL_MS` | `86400000` (24h) | `src/lib/catalog/openrouterCatalog.ts` | OpenRouter model catalog cache TTL. | -| `NANOBANANA_POLL_TIMEOUT_MS` | `120000` | `open-sse/handlers/imageGeneration.ts` | Max wait for NanoBanana image generation jobs. | -| `NANOBANANA_POLL_INTERVAL_MS` | `2500` | `open-sse/handlers/imageGeneration.ts` | NanoBanana job polling frequency. | -| `CLOUDFLARE_ACCOUNT_ID` | _(unset)_ | `open-sse/executors/cloudflare-ai.ts` | Account ID for Cloudflare Workers AI. | -| `CLOUDFLARED_BIN` | auto-detect | `src/lib/cloudflaredTunnel.ts` | Custom path to `cloudflared` binary. | -| `SEARCH_CACHE_TTL_MS` | `300000` (5 min) | `open-sse/services/searchCache.ts` | TTL for search API (Perplexity, Brave, etc.) response caching. | -| `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` | `false` | `src/app/api/providers/route.ts` | Allow multiple simultaneous connections per OpenAI-compatible provider. | -| `ENABLE_CC_COMPATIBLE_PROVIDER` | `false` | `src/shared/utils/featureFlags.ts` | Enable experimental Claude Code compatible provider endpoint. | -| `CLIPROXYAPI_HOST` | `127.0.0.1` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI bridge host (legacy integration). | -| `CLIPROXYAPI_PORT` | `5544` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI bridge port. | -| `CLIPROXYAPI_CONFIG_DIR` | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | CLIProxyAPI config directory. | -| `LOCAL_HOSTNAMES` | _(empty)_ | `open-sse/config/providerRegistry.ts` | Comma-separated additional hostnames treated as "local" (Docker service names, etc.). | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `MODELS_DEV_SYNC_INTERVAL` | `86400`（24 小时） | `src/lib/modelsDevSync.ts` | 开发时的模型目錄同步间隔，秒。 | --- -## 21. Proxy Health +## 20. 服务商特定设置 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OPENROUTER_CATALOG_TTL_MS` | `86400000`（24 小时） | `src/lib/catalog/openrouterCatalog.ts` | OpenRouter 模型目錄缓存 TTL。 | +| `MODEL_CATALOG_INCLUDE_NAMES` | `true` | `src/shared/constants/featureFlagDefinitions.ts` | 在 `/v1/models` 响应中包含显示友好的 `name` 字段。对于只需要 ID 的客户端可禁用。 | +| `NANOBANANA_POLL_TIMEOUT_MS` | `120000` | `open-sse/handlers/imageGeneration.ts` | NanoBanana 图片生成任务的最大等待时间。 | +| `NANOBANANA_POLL_INTERVAL_MS` | `2500` | `open-sse/handlers/imageGeneration.ts` | NanoBanana 任务轮询频率。 | +| `AWS_REGION` | _(未设置)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | 用于构建 AWS Bedrock 端点的区域（Kiro、音频）。 | +| `AWS_DEFAULT_REGION` | _(未设置)_ | `src/lib/providers/validation.ts`, `open-sse/handlers/audioSpeech.ts` | `AWS_REGION` 未设置时的回退。 | +| `CLOUDFLARE_ACCOUNT_ID` | _(未设置)_ | `open-sse/executors/cloudflare-ai.ts` | Cloudflare Workers AI 的 Account ID。 | +| `CLOUDFLARE_API_BASE` | `https://api.cloudflare.com/client/v4` | `src/app/api/settings/proxy/cloudflare-deploy/route.ts` | 覆盖代理池 Workers 中继部署器使用的 Cloudflare REST API 基础 URL（#4640 / 9router#1360）。 | +| `NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT` | `omniroute-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx` | 代理池"Deploy Relay"弹窗中建议的默认 worker 项目名。 | +| `NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | 设为 `false` 可从 Proxy Pool 选项卡中隐藏 Cloudflare Workers 中继选项。 | +| `CLOUDFLARED_BIN` | 自动检测 | `src/lib/cloudflaredTunnel.ts` | `cloudflared` 二进制文件的自定义路径。 | +| `DENO_DEPLOY_API_BASE` | `https://api.deno.com/v2` | `src/app/api/settings/proxy/deno-deploy/route.ts` | 覆盖代理池中继部署器使用的 Deno Deploy REST API 基础 URL（#4643 / 9router#1437）。 | +| `NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT` | `omniroute-deno-relay` | `src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx` | 代理池"Deploy Relay"弹窗中建议的默认 Deno Deploy 应用名。 | +| `NEXT_PUBLIC_DENO_RELAY_ENABLED` | `true` | `src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx` | 设为 `false` 可从 Proxy Pool 选项卡中隐藏 Deno Deploy 中继选项。 | +| `SEARCH_CACHE_TTL_MS` | `300000`（5 分钟） | `open-sse/services/searchCache.ts` | 搜索 API（Perplexity、Brave 等）响应缓存的 TTL。 | +| `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` | `false` | `src/app/api/providers/route.ts` | 允许每个 OpenAI 兼容服务商同时建立多个连接。 | +| `ENABLE_CC_COMPATIBLE_PROVIDER` | `false` | `src/shared/utils/featureFlags.ts` | 为仅 Claude Code 中继显示实验性 CC 兼容服务商 UI。 | +| `NINEROUTER_HOST` | `127.0.0.1` | `open-sse/executors/ninerouter.ts` | 覆盖嵌入式 9router 实例监听的主机。 | +| `NINEROUTER_PORT` | `20130` | `open-sse/executors/ninerouter.ts` | 覆盖嵌入式 9router 实例监听的端口。 | +| `EMBED_WS_PROXY_HOST` | `127.0.0.1` | `src/lib/services/embedWsProxy.ts` | 嵌入式服务 WebSocket 代理的绑定主机（默认仅 loopback）。 | +| `EMBED_WS_PROXY_PORT` | `20131` | `src/lib/services/embedWsProxy.ts` | 嵌入式服务 WebSocket 代理服务器的端口。 | +| `CLIPROXYAPI_HOST` | `127.0.0.1` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI 桥接主机（旧版集成）。 | +| `CLIPROXYAPI_PORT` | `5544` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI 桥接端口。 | +| `CLIPROXYAPI_CONFIG_DIR` | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | CLIProxyAPI 配置目录。 | +| `LOCAL_HOSTNAMES` | _(空)_ | `open-sse/config/providerRegistry.ts` | 逗号分隔的额外被视为"本地"的主机名（Docker 服务名称等）。 | + +`ENABLE_CC_COMPATIBLE_PROVIDER` 仅适用于接受 Claude Code 客户端的第三方中继。 +OmniRoute 会重写请求以使这些中继接受。如果你只想使用 +Claude Code CLI，或者不确定这些中继是什么，请保持此项禁用并添加一个普通的 +Anthropic 兼容服务商。 -| Variable | Default | Source File | Description | -| ---------------------------- | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000` | `src/lib/proxyHealth.ts` | Fast-fail health check timeout. | -| `PROXY_HEALTH_CACHE_TTL_MS` | `30000` | `src/lib/proxyHealth.ts` | Health check result cache TTL. | -| `RATE_LIMIT_MAX_WAIT_MS` | `120000` (2 min) | `open-sse/services/rateLimitManager.ts` | Max time to wait on a 429 before failing the request. | -| `REQUEST_RETRY` | `2` | `src/sse/services/cooldownAwareRetry.ts` | Number of automatic retries on model-scoped cooldown responses before returning error to client. | -| `MAX_RETRY_INTERVAL_SEC` | `30` | `src/sse/services/cooldownAwareRetry.ts` | Max backoff interval (seconds) between cooldown retries. Capped by this value regardless of upstream `Retry-After`. | +--- + +## 21. 代理健康 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `PROXY_FAST_FAIL_TIMEOUT_MS` | `2000` | `src/lib/proxyHealth.ts` | 快速失败健康检查超时。 | +| `PROXY_HEALTH_CACHE_TTL_MS` | `30000` | `src/lib/proxyHealth.ts` | 健康检查结果缓存 TTL。 | +| `PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS` | `2000` | `src/lib/proxyHealth.ts` | 代理健康探测失败的缓存 TTL。保持在低于 `PROXY_HEALTH_CACHE_TTL_MS` 的值，以便高并发下的瞬态代理超时能快速重试，同时不会为真正死掉的代理禁用快速失败。 | +| `OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK` | `false` | `src/shared/constants/featureFlagDefinitions.ts` | 允许 OAuth 和服务商校验流程在代理可达性预检失败时绕过固定代理直接连接。有效优先级为 Feature Flags DB 覆盖 > 环境变量 > 默认值。 | +| `RATE_LIMIT_MAX_WAIT_MS` | `120000`（2 分钟） | `open-sse/services/rateLimitManager.ts` | 在请求失败前等待 429 的最长时间。 | +| `RATE_LIMIT_AUTO_ENABLE` | _(未设置)_ | `open-sse/services/rateLimitManager.ts` | 强制打开/关闭自动启用速率限制安全网，不管持久化的 Dashboard 设置。接受 `true`/`1`/`on` 强制开启，`false`/`0`/`off` 强制关闭。 | +| `PROVIDER_COOLDOWN_ENABLED` | _(未设置 → 关闭)_ | `open-sse/services/providerCooldownTracker.ts` | 启用全局跨请求服务商/连接冷却跟踪。默认关闭（与 Connection Cooldown / Provider Circuit Breaker 重叠）。接受 `true`/`1`/`on` 启用。 | +| `PROVIDER_COOLDOWN_MIN_MS` | `5000` | `open-sse/services/providerCooldownTracker.ts` | 失败的服务商/连接重试前的最短冷却时间（毫秒）。随连续失败次数指数级增长。仅在 `PROVIDER_COOLDOWN_ENABLED` 时使用。 | +| `PROVIDER_COOLDOWN_MAX_MS` | `300000`（5 分钟） | `open-sse/services/providerCooldownTracker.ts` | 失败的服务商/连接重试前的最大冷却上限（毫秒）。仅在 `PROVIDER_COOLDOWN_ENABLED` 时使用。 | +| `STREAM_RECOVERY_ENABLED` | _(未设置 → 关闭)_ | `src/lib/resilience/settings.ts`（种子） → `open-sse/services/streamRecovery.ts`（逻辑） | **这是什么：** 透明恢复被截断的上游流（free-claude-code 端口）。将打开 SSE 窗口保持最多 `STREAM_RECOVERY.HOLDBACK_MS`（750 毫秒），使得 _提交前_ 截断 — 即任何字节到达客户端之前 — 被透明地重新打开和重试。**何时启用：** 频繁在流开始时 0 字节截断的不稳定上游；如果无法承受每个流最多 750 毫秒的首 Token 延迟增加，请保持关闭。接受 `true`/`1`/`on`。为持久化容灾设置提供种子；Dashboard 设置一旦设置即生效。 | +| `STREAM_RECOVERY_MIDSTREAM_ENABLED` | _(未设置 → 关闭)_ | `src/lib/resilience/settings.ts`（种子） → `open-sse/services/streamRecovery.ts`（逻辑） | **这是什么：** 流中续传（Fase 4.4）— _提交后_ 截断（字节已到达客户端）之后，用部分文本作为 assistant 预填充重新请求，拼接缺失的后缀。仅限纯文本 OpenAI 兼容流；有工具调用在进行时永不触发。**何时启用：** 长生成被中途截断，且你接受恢复的后缀以一次性爆发而非逐 Token 到达。独立于 `STREAM_RECOVERY_ENABLED`（不同的风险特征）。接受 `true`/`1`/`on`。 | +| `HEALTHCHECK_STAGGER_MS` | `3000` | `src/lib/tokenHealthCheck.ts` | 启动时服务商 Token 健康检查之间的错开间隔（毫秒）。 | +| `REQUEST_RETRY` | `2` | `src/sse/services/cooldownAwareRetry.ts` | 模型作用域冷却响应上的自动重试次数，之后将错误返回给客户端。 | +| `MAX_RETRY_INTERVAL_SEC` | `30` | `src/sse/services/cooldownAwareRetry.ts` | 冷却重试之间的最大退避间隔（秒）。不管上游 `Retry-After` 如何，均受此值限制。 | +| `HEADROOM_URL` | `http://localhost:8787` | `src/lib/headroom/detect.ts` | Headroom Token 节省器代理 URL。Dashboard 生命周期（`api/headroom/*`）默认在 loopback 上启动本地 `headroom-ai` CLI；覆盖以指向外部 Docker sidecar 代理。 | + +### 流恢复调优常量（非环境变量） + +上面的两个 `STREAM_RECOVERY_*` 开关是唯一的面向运维人员的开关。 +恢复行为其余部分由 `open-sse/config/constants.ts`（`STREAM_RECOVERY`）中的硬编码常量调优，在此列出仅供参考 — +修改它们需要代码编辑，而非环境变量： + +- `STREAM_RECOVERY.HOLDBACK_MS = 750` — 打开 SSE 窗口保持多长时间， + 以便在任何字节提交给客户端之前可重试早期截断。 +- `STREAM_RECOVERY.BUFFER_MAX_BYTES = 65536` — 保持窗口的硬上限；一旦 + 累积这么多字节就提交（刷新 + 透传），不管计时器。 +- `STREAM_RECOVERY.EARLY_RETRY_MAX = 4` — 保持未提交期间上游流的最多透明重开次数。 + +> **每个服务商的滑动窗口速率限制（无环境变量）：** FCC 迁移的 +> 每个服务商滑动窗口速率限制 _回退_ 存在于代码中 +> （`open-sse/services/providerDefaultRateLimit.ts`，通过 +> `open-sse/services/rateLimitManager.ts` 连接），但附带了一个**空的默认 Map** +> 且目前**没有运维人员环境变量** — 它仅通过测试钩子/ +> 代码编辑启用。有意不在上述表格中列出。确实有开关的 +> 每个 `(token, IP)` 中继限制器是 `RELAY_IP_PER_MINUTE`（§3 网络与端口）。 --- -## 22. Debugging +## 22. 调试 > [!CAUTION] -> These variables produce **verbose output** and may leak sensitive data. **Never enable in production.** - -| Variable | Default | Source File | Description | -| -------------------------------- | --------- | ----------------------------------------- | -------------------------------------------------------------- | -| `CURSOR_PROTOBUF_DEBUG` | _(unset)_ | `open-sse/utils/cursorProtobuf.ts` | Set `1` to dump Cursor protobuf decode/encode details. | -| `CURSOR_STREAM_DEBUG` | _(unset)_ | `open-sse/executors/cursor.ts` | Set `1` to dump raw Cursor SSE stream data. | -| `DEBUG_RESPONSES_SSE_TO_JSON` | _(unset)_ | `open-sse/handlers/responseTranslator.ts` | Set `true` to log Responses API SSE→JSON translation details. | -| `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(unset)_ | E2E test harness | Set `true` to enable E2E test mode (relaxed auth, test hooks). | +> 这些变量会产生**详细输出**，并可能泄露敏感数据。**切勿在生产环境中启用。** + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `CURSOR_DEBUG` | _(未设置)_ | `open-sse/executors/cursor.ts` | 设为 `1` 可启用详细的 Cursor executor 日志（解码的 SSE 块等）。 | +| `CURSOR_STREAM_DEBUG` | _(未设置)_ | `open-sse/executors/cursor.ts` | `CURSOR_DEBUG` 的向后兼容别名。 | +| `CURSOR_DUMP_FILE` | _(未设置)_ | `open-sse/executors/cursor.ts` | 当 `CURSOR_DEBUG=1` 时，接收原始解码 Cursor 块的可选文件路径。 | +| `CURSOR_STREAM_TIMEOUT_MS` | `300000` | `open-sse/executors/cursor.ts` | Cursor executor 的流空闲超时（毫秒）。 | +| `CURSOR_TOOL_DIRECTIVE` | 启用 (`!== "0"`) | `open-sse/executors/cursor.ts` | 使 composer-2.5 可靠发出工具调用的工具提交指令。设为 `0` 可禁用。 | +| `CURSOR_IMAGE_FETCH_TIMEOUT_MS` | `15000` | `open-sse/utils/cursorImages.ts` | 远程 `image_url` 视觉输入的单张图片获取超时（毫秒）。 | +| `CURSOR_STATE_DB_PATH` | _(探测)_ | `open-sse/utils/cursorVersionDetector.ts` | 覆盖版本检测使用的 Cursor 状态数据库查询。 | +| `CURSOR_TOKEN` | _(未设置)_ | `scripts/ad-hoc/cursor-tap.cjs` | 开发工具使用的直接 Cursor bearer Token。 | +| `OMNIROUTE_LOG_REQUEST_SHAPE` | 启用 (`!== "0"`) | `src/app/api/v1/chat/completions/route.ts` | 记录大型聊天载荷的 content-type/length 标记。设为 `"0"` 可静默。 | +| `DEBUG_RESPONSES_SSE_TO_JSON` | _(未设置)_ | `open-sse/handlers/responseTranslator.ts` | 设为 `true` 可记录 Responses API SSE→JSON 转换详情。 | +| `NEXT_PUBLIC_OMNIROUTE_E2E_MODE` | _(未设置)_ | E2E 测试工具 | 设为 `true` 可启用 E2E 测试模式（放宽认证、测试钩子）。 | --- -## 23. GitHub Integration +## 23. GitHub 集成 -Allow users to report issues directly from the Dashboard. +允许用户直接从 Dashboard 报告问题。 -| Variable | Default | Source File | Description | -| --------------------- | --------- | --------------------------------------- | ------------------------------------------------------- | -| `GITHUB_ISSUES_REPO` | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | Repository in `owner/repo` format. | -| `GITHUB_ISSUES_TOKEN` | _(unset)_ | `src/app/api/v1/issues/report/route.ts` | GitHub Personal Access Token with `issues:write` scope. | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `GITHUB_ISSUES_REPO` | _(未设置)_ | `src/app/api/v1/issues/report/route.ts` | 仓库，`owner/repo` 格式。 | +| `GITHUB_ISSUES_TOKEN` | _(未设置)_ | `src/app/api/v1/issues/report/route.ts` | 具有 `issues:write` 权限域的 GitHub Personal Access Token。 | +| `GITHUB_TOKEN` | _(未设置)_ | issue 分类 / 云代理辅助 | 通用 GitHub 访问 Token，用作 `GITHUB_ISSUES_TOKEN` 的回退，并被 `src/lib/cloudAgent/*` 中的云代理辅助使用。 | --- -## Deployment Scenarios +## 部署场景 -### Minimal Local Development +中继后端 SRE 指南（ts/bifrost/auto 行为、9router vs CLIProxyAPI 部署以及高吞吐量回退策略）请参阅 [Relay Backend Strategy](/docs/reference/RELAY_BACKEND_STRATEGY.md)。 + +### 最小本地开发 ```bash JWT_SECRET=$(openssl rand -base64 48) @@ -595,7 +870,7 @@ PORT=20128 NODE_ENV=development ``` -### Docker Production +### Docker 生产 ```bash JWT_SECRET= @@ -614,7 +889,7 @@ OMNIROUTE_MEMORY_MB=512 CORS_ORIGIN=https://your-frontend.example.com ``` -### Air-Gapped / CI +### 气隙 / CI ```bash JWT_SECRET=test-jwt-secret-for-ci @@ -625,7 +900,7 @@ OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true APP_LOG_TO_FILE=false ``` -### VPS with Reverse Proxy (nginx + Cloudflare) +### 带反向代理的 VPS（nginx + Cloudflare） ```bash JWT_SECRET= @@ -643,23 +918,198 @@ CLI_COMPAT_ALL=1 --- -## Audit: Removed / Dead Variables +## 24. 技能沙箱（v3.8.0+） + +技能框架（`src/lib/skills/`）在沙箱环境中执行用户定义自动化时应用的限制和安全开关。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `SKILLS_SANDBOX_TIMEOUT_MS` | `10000`（10 秒） | `src/lib/skills/builtins.ts` | 沙箱技能代码的每次执行挂钟超时时间。硬限制；超时则杀死。 | +| `SKILLS_EXECUTION_TIMEOUT_MS` | _(回退到 `SKILLS_SANDBOX_TIMEOUT_MS`)_ | `src/lib/skills/` | 高级技能编排超时。设为高于 `SKILLS_SANDBOX_TIMEOUT_MS` 以允许多步工作流。 | +| `SKILLS_MAX_FILE_BYTES` | `1048576`（1 MB） | `src/lib/skills/builtins.ts` | 技能可从单个沙箱文件读取的最大字节数。 | +| `SKILLS_MAX_HTTP_RESPONSE_BYTES` | `256000`（250 KB） | `src/lib/skills/builtins.ts` | 技能内从单个 HTTP 响应捕获的最大字节数。 | +| `SKILLS_MAX_SANDBOX_OUTPUT_CHARS` | `100000` | `src/lib/skills/builtins.ts` | 沙箱调用返回的 stdout/stderr 字符硬上限。 | +| `SKILLS_SANDBOX_NETWORK_ENABLED` | `false` | `src/lib/skills/builtins.ts` | 设为 `1`/`true` 允许沙箱内部向外联网。默认**隔离**以确保安全。 | +| `SKILLS_ALLOWED_SANDBOX_IMAGES` | _(空)_ | `src/lib/skills/builtins.ts` | 逗号分隔的允许用于沙箱执行的容器镜像允许列表。空意味着仅使用内置默认值。 | +| `SKILLS_SANDBOX_DOCKER_IMAGE` | _(内置默认值)_ | `src/lib/skills/` | 启动 Docker 沙箱时使用的容器镜像。覆盖以固定自定义加固的基础镜像。 | + +> [!CAUTION] +> 启用 `SKILLS_SANDBOX_NETWORK_ENABLED=true` 会打开任意技能代码的出口路径。在共享部署中请搭配 `OUTBOUND_SSRF_GUARD_ENABLED=true` 和严格的 `CORS_ORIGIN`/代理策略。 + +--- + +## 25. 服务商配额、隧道、备份与杂项运行时 + +服务商配额端点、网络隧道（Tailscale、Ngrok、MITM 调试代理）、1Proxy 出口池、数据库备份以及 executor 层或脚本引用的小型按功能覆盖。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `REDIS_URL` | `redis://localhost:6379` | `src/shared/utils/rateLimiter.ts` | 速率限制器后端的 Redis 连接字符串。 | +| `ALIBABA_CODING_PLAN_HOST` | _(生产主机)_ | `open-sse/services/bailianQuotaFetcher.ts` | 覆盖用于获取阿里巴巴 Bailian coding-plan 配额的主机。 | +| `ALIBABA_CODING_PLAN_QUOTA_URL` | 派生自主机 | `open-sse/services/bailianQuotaFetcher.ts` | 阿里巴巴 Bailian 的完整配额 URL 覆盖。 | +| `CONTEXT_RESERVE_TOKENS` | `1024` | `open-sse/services/contextManager.ts` | 计算提示预算时为补全输出保留的 Token 数。 | +| `MODEL_ALIAS_COMPAT_ENABLED` | 启用 | `open-sse/services/model.ts` | 切换旧客户端使用的旧版模型别名兼容层。 | +| `OMNIROUTE_EMERGENCY_FALLBACK` | 启用 | `open-sse/services/emergencyFallback.ts` | 设为 `false`（或 `0`）可禁用紧急预算耗尽回退，该回退将失败的请求重新路由到免费 `nvidia`/`openai/gpt-oss-120b` 模型。有效优先级为 Feature Flags DB 覆盖 > 环境变量 > 默认值；如果不可用，服务回退到原始环境变量值。 | +| `COMMAND_CODE_CALLBACK_PORT` | _(未设置)_ | `src/app/api/providers/command-code/auth/shared.ts` | Command Code CLI 辅助使用的 OAuth 风格回调的本地端口。 | +| `COMMAND_CODE_VERSION` | `0.33.2` | `open-sse/executors/commandCode.ts` | 作为 `x-command-code-version` 头发送到 Command Code 上游的值。覆盖以升级 CLI 版本。 | +| `MITM_LOCAL_PORT` | `443` | `src/mitm/server.cjs` | MITM 调试代理的本地绑定端口。 | +| `MITM_DISABLE_TLS_VERIFY` | `0` | `src/mitm/server.cjs` | 设为 `1` 可禁用上游 TLS 校验（仅限开发）。 | +| `MITM_IDLE_TIMEOUT_MS` | `60000` | `src/mitm/socketTimeouts.ts`, `src/mitm/server.cjs` | 代理连接的空闲套接字超时（毫秒）；超过该时间的空闲套接字会被拆除，避免泄露半打开隧道。 | +| `MITM_VERBOSE` | `1` | `src/mitm/server.cjs`, `src/mitm/_internal/bypass.cjs` | 路由决策日志详细程度：`0` 静默，值越大记录越多 bypass/路由决策。 | +| `ONEPROXY_ENABLED` | `true` | `src/lib/oneproxySync.ts` | 启用 1Proxy 出口池同步。 | +| `ONEPROXY_API_URL` | `https://1proxy-api.aitradepulse.com` | `src/lib/oneproxySync.ts` | 1Proxy 服务 API URL 覆盖。 | +| `ONEPROXY_MAX_PROXIES` | `500` | `src/lib/oneproxySync.ts` | 每次同步导入的最大代理数。 | +| `ONEPROXY_MIN_QUALITY_THRESHOLD` | `50` | `src/lib/oneproxySync.ts` | 导入代理的最低质量分。 | +| `FREE_PROXY_1PROXY_ENABLED` | `true` | `src/lib/freeProxyProviders/oneproxy.ts` | 启用 1proxy 免费代理源。设为 `false` 可禁用。 | +| `FREE_PROXY_1PROXY_API_URL` | _(见 oneproxy.ts)_ | `src/lib/freeProxyProviders/oneproxy.ts` | 1proxy API URL 覆盖。 | +| `FREE_PROXY_1PROXY_MAX` | `500` | `src/lib/freeProxyProviders/oneproxy.ts` | 从 1proxy 每次同步获取的最大代理数。 | +| `FREE_PROXY_1PROXY_MIN_QUALITY` | `50` | `src/lib/freeProxyProviders/oneproxy.ts` | 1proxy 导入的最低质量分阈值。 | +| `FREE_PROXY_PROXIFLY_ENABLED` | `true` | `src/lib/freeProxyProviders/proxifly.ts` | 启用 Proxifly 免费代理源。设为 `false` 可禁用。 | +| `FREE_PROXY_PROXIFLY_QUANTITY` | `100` | `src/lib/freeProxyProviders/proxifly.ts` | 每次 Proxifly 同步获取的代理数量。 | +| `FREE_PROXY_PROXIFLY_ANONYMITY` | `elite` | `src/lib/freeProxyProviders/proxifly.ts` | Proxifly 的匿名级别过滤（`elite`、`anonymous`、`transparent`）。 | +| `FREE_PROXY_IPLOCATE_ENABLED` | `false` | `src/lib/freeProxyProviders/iplocate.ts` | 启用 IPLocate 免费代理源。仅手动启用。 | +| `FREE_PROXY_IPLOCATE_BASE_URL` | `https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols` | `src/lib/freeProxyProviders/iplocate.ts` | IPLocate 代理列表基础 URL 覆盖。 | +| `NEXT_PUBLIC_VERCEL_RELAY_ENABLED` | `true` | `src/app/(dashboard)/…/ProxyPoolTab.tsx` | 在 Proxy Pool 选项卡中显示/隐藏 Deploy Vercel Relay 按钮。 | +| `VERCEL_API_BASE` | `https://api.vercel.com` | `src/app/api/settings/proxy/vercel-deploy/route.ts` | Vercel API 基础 URL 覆盖（用于测试）。 | +| `NEXT_PUBLIC_VERCEL_RELAY_DEFAULT_PROJECT` | `omniroute-relay` | `src/app/(dashboard)/…/VercelRelayModal.tsx` | Vercel Relay 部署弹窗中预填的默认项目名。 | +| `TAILSCALE_BIN` | _(自动检测)_ | `src/lib/tailscaleTunnel.ts` | `tailscale` 二进制文件的显式路径。 | +| `TAILSCALED_BIN` | _(自动检测)_ | `src/lib/tailscaleTunnel.ts` | `tailscaled` 守护进程二进制文件的显式路径。 | +| `TAILSCALE_AUTHKEY` | _(未设置)_ | `src/lib/tailscaleTunnel.ts` | 非交互式/无头 `tailscale up` 的预共享 Tailscale 认证密钥（通过 `--auth-key=` 传递）。未设置时，登录回退到交互式浏览器认证 URL。 | +| `NGROK_AUTHTOKEN` | _(未设置)_ | `src/lib/ngrokTunnel.ts` | 认证出口 ngrok 隧道。 | +| `DB_BACKUP_MAX_FILES` | `20` | `src/lib/db/backup.ts` | 磁盘上保留的最大 SQLite 备份文件数。覆盖从 Settings → Database backup retention 保存的值。 | +| `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts` | 保留备份的最大天数。`0` 禁用基于时间的清理。覆盖从 Settings → Database backup retention 保存的值。 | +| `OMNIROUTE_TLS_PROXY_URL` | _(未设置)_ | `open-sse/services/chatgptTlsClient.ts` | 覆盖测试用的 TLS sidecar URL。生产环境应保持未设置。 | +| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | 入口点权限检查的容器运行时提示。在无根 Podman 下设为 `podman`，以便修复指令使用 `podman unshare chown` 而非 `sudo chown`。 | +| `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | 配额共享消费存储后端：`sqlite`（默认）或 `redis`。 | +| `QUOTA_STORE_REDIS_URL` | _(未设置)_ | `src/lib/quota/storeFactory.ts` | `QUOTA_STORE_DRIVER=redis` 时使用的 Redis 连接字符串（如 `redis://localhost:6379`）。 | +| `QUOTA_SATURATION_THRESHOLD` | `0.5` | `src/lib/quota/enforce.ts` | 池饱和比率（0..1）；达到或超过该值时池进入严格模式（不允许借用）。 | +| `QUOTA_SOFT_DEPRIORITIZE_FACTOR` | `0.7` | `open-sse/services/combo.ts` | 软配额策略降低目标优先级时应用的分数乘数（0..1）。 | +| `STATUS_SOFT_DEPRIORITIZE_FACTOR` | `0.5` | `open-sse/services/combo/autoStrategy.ts` | 预检配额截止关闭时（#4540），在 auto-combo 评分中对已耗尽的服务商（`credits_exhausted`/`rate_limited`）应用的分数乘数（0..1）。 | +| `QUOTA_CONSUMPTION_RETENTION_DAYS` | `14` | `src/lib/db/quotaConsumption.ts` | `quota_consumption` 桶在 GC（`gcQuotaConsumption`）前的保留窗口（天）。 | +| `QUOTA_PREFLIGHT_CUTOFF_ENABLED` | `false` | `src/lib/resilience/settings.ts` | 启用（默认关闭）：在评分前丢弃低配额候选项的自动路由硬配额截止。 | +| `OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL` | `false` | `open-sse/services/autoCombo/virtualFactory.ts` | 启用（默认关闭）：当 `auto/:` 过滤器没有匹配到已连接候选项时，恢复旧版回退到完整（未过滤）池的行为，而非返回空池。默认关闭使 `:free` 意为"仅免费层"。 | +| `AGENTBRIDGE_UPSTREAM_CA_CERT` | _(未设置)_ | `src/mitm/manager.ts` | AgentBridge 上游 TLS 连接信任的额外 CA 证书（PEM）。 | +| `INSPECTOR_BUFFER_SIZE` | `1000` | `src/mitm/inspector/buffer.ts` | Traffic Inspector 环形缓冲区中保留的最大捕获请求数。 | +| `INSPECTOR_MAX_BODY_KB` | `1024` | `src/mitm/inspector/buffer.ts` | 截断前捕获的请求/响应体最大大小（KB）。 | +| `INSPECTOR_HTTP_PROXY_PORT` | `8080` | `src/mitm/inspector/httpProxyServer.ts` | Traffic Inspector HTTP 代理的本地端口。 | +| `INSPECTOR_HTTP_PROXY_AUTOSTART` | `false` | `src/mitm/inspector/httpProxyServer.ts` | 启动时自动启动 inspector HTTP 代理。 | +| `INSPECTOR_TLS_INTERCEPT` | `false` | `src/lib/inspector/captureState.ts` | 对捕获的 HTTPS 流量启用 TLS 拦截（MITM）。 | +| `INSPECTOR_LLM_HOSTS_EXTRA` | _(未设置)_ | `src/lib/inspector/captureState.ts` | 额外的主机名（逗号分隔），被视为大语言模型端点以进行捕获。 | +| `INSPECTOR_MASK_SECRETS` | `true` | `src/mitm/inspector/buffer.ts` | 在捕获流量中脱敏（认证头 / API key）。 | +| `INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES` | `30` | `src/app/api/tools/traffic-inspector/capture-modes/system-proxy/route.ts` | 系统代理安全护栏自动还原操作系统代理设置前的分钟数。 | +| `INSPECTOR_INTERNAL_INGEST_TOKEN` | _(自动)_ | `src/app/api/tools/traffic-inspector/internal/ingest/route.ts` | 认证进入 inspector 的内部捕获摄入的 Token。 | +| `PLAYGROUND_COMPARE_MAX_COLUMNS` | `4` | `src/app/(dashboard)/dashboard/playground/` | Playground 比较模式下的最大并排列数。 | +| `PLAYGROUND_IMPROVE_PROMPT_DEFAULT_MODEL` | _(未设置)_ | `src/app/(dashboard)/dashboard/playground/` | Playground 'improve prompt' 操作的默认模型（未设置时回退到活跃模型）。 | +| `BIFROST_ENABLED` | `1` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | bifrost sidecar 代理的主开关。设为 `0` 时，路由返回 503 并带 `X-Bifrost-Killswitch` 头，运维人员被弹回 TS 路径。无需重新部署即可禁用 sidecar（tier-1 路由事件、密钥轮换）。 | +| `BIFROST_BASE_URL` | _(未设置)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | 设置时，Bifrost sidecar 代理路由将 `/v1/chat/completions` 流量转发到此 Go 网关而非 TS 中继处理器。未设置 → 503-with-fallback。尾部斜杠会被剥离。 | +| `BIFROST_API_KEY` | _(未设置)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | Bifrost 网关的 API key（作为 `Authorization: Bearer ...` 发送）。未设置时，路由期望请求携带有效的 OmniRoute API key；此 key 仅用于网关侧认证。 | +| `BIFROST_STREAMING_ENABLED` | `true` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | 设为 true 时，Bifrost sidecar 路由通过网关以 SSE 流式返回响应，而非 TS 流式 executor。设为 `0` 可强制通过网关返回非流式 JSON 响应。 | +| `BIFROST_TIMEOUT_MS` | `30000` | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | 代理到 Bifrost 网关时的每个请求超时（毫秒）。超时时路由通过 `X-Bifrost-Fallback` 头返回 TS 中继路径。 | +| `OMNIROUTE_BIFROST_KEY` | _(未设置)_ | `src/app/api/v1/relay/chat/completions/bifrost/route.ts` | `BIFROST_API_KEY` 的别名（供通过 `OMNIROUTE_*` 读取环境变量的脚本使用）。两者同时设置时 `BIFROST_API_KEY` 优先。 | +| `OMNIROUTE_RELAY_BACKEND` | `ts` / `auto` | `src/app/api/v1/relay/chat/completions/routingBackend.ts` | `/api/v1/relay/chat/completions` 的中继后端：`ts | bifrost | auto`。`ts` = TypeScript 中继（未配置 Bifrost 时的默认值）；`auto` 在 `BIFROST_BASE_URL` 已设置且 `BIFROST_ENABLED` ≠ `0` 时选择 Bifrost，若 sidecar 不可达则自动回退到 TS；`bifrost` 强制 Bifrost（严格，无回退）。认证/速率限制/注入安全护栏/allowlist 始终在 Next 路由中首先运行。响应携带 `X-Routing-Backend` / `X-Routing-Fallback`。 | +| `RELAY_ROUTING_BACKEND` | _(未设置)_ | `src/app/api/v1/relay/chat/completions/routingBackend.ts` | `OMNIROUTE_RELAY_BACKEND` 的已接受别名（相同的 `ts | bifrost | auto` 值）。两者同时设置时 `OMNIROUTE_RELAY_BACKEND` 优先。 | +| `OMNIROUTE_BIFROST_FAILURE_COOLDOWN_MS` | `5000` | `src/app/api/v1/relay/chat/completions/bifrostCooldown.ts` | 在 `auto` 模式下 Bifrost sidecar 跳失败后的冷却时间（毫秒），在此期间中继重新尝试 sidecar 之前直接走 TS 路径；冷却过后再次探测。`0` 禁用。仅在 `OMNIROUTE_RELAY_BACKEND=auto` 时生效。 | +| `OMNIROUTE_TLS_CERT` | _(未设置)_ | `bin/cli/commands/serve.mjs` | PEM TLS 证书路径，用于 `omniroute serve` 通过 HTTPS 提供服务（等同于 `--tls-cert`）。必须与 `OMNIROUTE_TLS_KEY` 配对；独立服务器随后在同一监听器上终止 TLS（`wss://` 工作不变）。未设置 → 纯 HTTP。仅提供证书或密钥中的一个，或路径不可读，会记录警告并保持 HTTP。 | +| `OMNIROUTE_TLS_KEY` | _(未设置)_ | `bin/cli/commands/serve.mjs` | `omniroute serve` HTTPS 的 PEM TLS 私钥路径（等同于 `--tls-key`）。必须与 `OMNIROUTE_TLS_CERT` 配对。参阅 `OMNIROUTE_TLS_CERT`。 | +| `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED` | `0` | `src/lib/security/localEndpoints.ts` | `/api/local/*` 路由的主开关。未设置或设为 `0` 时，所有 `/api/local/*` 路由在生产环境中返回 503。在非 loopback 部署中必须设为 `1` 才能启用 Redis 启动器及类似的一键本地服务启动器。与 `isLocalOnlyPath()` 路由守卫分类（`src/server/authz/routeGuard.ts` 中的 `LOCAL_ONLY_API_PREFIXES`）构成双保险。 | +| `OMNIROUTE_LOCAL_ENDPOINTS_TOKEN` | _(未设置)_ | `src/lib/security/localEndpoints.ts` | 非 loopback 上的 `/api/local/*` 调用者的 Bearer Token（如桌面应用）。设置时，来自非 loopback IP 的请求必须携带 `Authorization: Bearer `。在非 loopback 部署中且 `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1` 时必需。 | +| `OMNIROUTE_REDIS_CONTAINER_NAME` | `omniroute-redis` | `bin/cli/commands/redis.mjs` | 一键 Redis 启动器（`omniroute redis up`）的容器名。CLI 和 `RedisLauncherPanel` GUI 均使用。 | +| `OMNIROUTE_REDIS_HOST_PORT` | `6379` | `bin/cli/commands/redis.mjs` | 一键 Redis 启动器的主机端口。如果主机已绑定 6379 则提升。容器内部端口保持 6379。 | +| `OMNIROUTE_REDIS_IMAGE` | `redis:7-alpine` | `bin/cli/commands/redis.mjs` | 一键 Redis 启动器使用的 Redis 镜像。根据需要覆盖为 `redis:8-alpine` 或私有注册表镜像。 | +| `QDRANT_HOST` | `qdrant` | _(可选集群配置文件)_ | `--profile memory` 活跃时 Qdrant sidecar 的主机名。默认指向网内 qdrant 服务名；覆盖为外部部署。仅在代码中 `qdrantEnabled` 为 `true` 时使用（`src/lib/memory/vectorStore.ts:108`）。 | +| `QDRANT_PORT` | `6333` | _(可选集群配置文件)_ | Qdrant sidecar 的 REST 端口。 | +| `QDRANT_GRPC_PORT` | `6334` | _(可选集群配置文件)_ | Qdrant sidecar 的 gRPC 端口。偏好在流式操作中使用 gRPC 而非 REST 的客户端库使用。 | +| `QDRANT_API_KEY` | _(未设置)_ | _(可选集群配置文件)_ | Qdrant Cloud 或认证的本地实例的可选 API key。空 → 不发送 `api-key` 头。 | +| `QDRANT_COLLECTION` | `omniroute-memory` | _(可选集群配置文件)_ | OmniRoute 的对话记忆嵌入的 collection 名称。首次运行时以 `QDRANT_VECTOR_SIZE` 维度创建。 | +| `QDRANT_EMBEDDING_MODEL` | `text-embedding-3-small` | _(可选集群配置文件)_ | Qdrant collection 元数据中记录的默认嵌入模型名称。实际嵌入由 OmniRoute 设置中 `embeddingModel` 字段指向的任意服务商生成。 | +| `QDRANT_VECTOR_SIZE` | `1536` | _(可选集群配置文件)_ | 嵌入向量维度。必须与用于嵌入的模型匹配（text-embedding-3-small → 1536；ada-002 → 1536；nomic-embed-text → 768）。 | +| `QDRANT_HNSW_EF_CONSTRUCT` | `128` | _(可选集群配置文件)_ | HNSW 索引构建时精度。值越高构建越慢、搜索越快。 | + +--- + +## 26. 测试与 E2E 工具 + +由 `scripts/dev/run-next-playwright.mjs`、`scripts/dev/smoke-electron-packaged.mjs`、 +`scripts/dev/run-ecosystem-tests.mjs` 和 `scripts/build/uninstall.mjs` 使用。 +在生产部署中保持下面所有值未设置。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_E2E_BOOTSTRAP_MODE` | `auth` | `scripts/dev/run-next-playwright.mjs` | Playwright 运行器的 E2E 引导模式（`auth`、`fresh`、`reuse`）。 | +| `OMNIROUTE_E2E_PASSWORD` | 回退到 `INITIAL_PASSWORD` | `scripts/dev/run-next-playwright.mjs` | 注入到 Playwright 环境的管理员密码。 | +| `OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | Playwright 运行期间禁用本地健康检查轮询。 | +| `OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK` | `true` | `scripts/dev/run-next-playwright.mjs` | 测试期间禁用 OAuth Token 健康检查循环。 | +| `OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS` | _(未设置)_ | `src/lib/tokenHealthCheck.ts` | 逗号分隔的排除在主动 Token 刷新扫除之外的服务商（如 `codex,openai`）。完全禁用健康检查的目标替代方案 — 短 TTL 的服务商保持刷新，级联服务商保持仅响应式。 | +| `OMNIROUTE_HIDE_HEALTHCHECK_LOGS` | `true` | `scripts/dev/run-next-playwright.mjs` | Playwright stdout 中的健康检查日志静默。 | +| `OMNIROUTE_PLAYWRIGHT_SKIP_BUILD` | `0` | `scripts/dev/run-next-playwright.mjs` | Playwright 启动前跳过 Next.js 生产构建（CI 优化）。 | +| `OMNIROUTE_SKIP_UNINSTALL_HOOK` | `0` | `scripts/build/uninstall.mjs` | 跳过 OmniRoute 卸载钩子（CI 用，保持 `node_modules` 完整）。 | +| `ECOSYSTEM_SERVER_WAIT_MS` | `180000` | `scripts/dev/run-ecosystem-tests.mjs` | 服务器在运行生态系统/协议测试前变为健康的等待时间（毫秒）。 | +| `ELECTRON_SMOKE_URL` | `http://127.0.0.1:20128/login` | `scripts/dev/smoke-electron-packaged.mjs` | Electron 烟雾测试工具期望打包应用提供服务的 URL。 | +| `ELECTRON_SMOKE_TIMEOUT_MS` | `45000` | `scripts/dev/smoke-electron-packaged.mjs` | 烟雾测试工具放弃前的总超时时间（毫秒）。 | +| `ELECTRON_SMOKE_SETTLE_MS` | `2000` | `scripts/dev/smoke-electron-packaged.mjs` | 页面加载后的稳定窗口（毫秒）。 | +| `ELECTRON_SMOKE_APP_EXECUTABLE` | _(自动)_ | `scripts/dev/smoke-electron-packaged.mjs` | 打包的 Electron 可执行文件的显式路径。 | +| `ELECTRON_SMOKE_DATA_DIR` | _(临时目录)_ | `scripts/dev/smoke-electron-packaged.mjs` | Electron 烟雾测试运行的数据目录。 | +| `ELECTRON_SMOKE_KEEP_DATA` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | 设为 `1` 可在运行后保留烟雾测试数据目录。 | +| `ELECTRON_SMOKE_STREAM_LOGS` | `0` | `scripts/dev/smoke-electron-packaged.mjs` | 设为 `1` 可在运行期间将 Electron 日志流式输出到 stdout。 | +| `CLI_DEVIN_BIN` | _(PATH 查找)_ | `open-sse/executors/devin-cli.ts` | 覆盖 Devin CLI 二进制文件路径。 | + +### 文档翻译管线 + +由 `scripts/i18n/run-translation.mjs`（`npm run i18n:run` 命令）使用。 +所有五个变量默认未设置 — 仅在能够运行文档翻译器的机器上的 `.env` 中设置。 + +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_TRANSLATION_API_URL` | _(未设置)_ | `scripts/i18n/run-translation.mjs` | 翻译后端的 OpenAI 兼容基础 URL。 | +| `OMNIROUTE_TRANSLATION_API_KEY` | _(未设置)_ | `scripts/i18n/run-translation.mjs` | 翻译后端的 Bearer Token（永不被记录）。 | +| `OMNIROUTE_TRANSLATION_MODEL` | _(未设置)_ | `scripts/i18n/run-translation.mjs` | 模型 ID，如 `gpt-4o-mini` 或 `cx/gpt-5.4-mini`。 | +| `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | `60000` | `scripts/i18n/run-translation.mjs` | 每个请求的超时，毫秒。 | +| `OMNIROUTE_TRANSLATION_CONCURRENCY` | `4` | `scripts/i18n/run-translation.mjs` | 跨多个文件/locale 运行时的并行翻译请求数。 | + +--- + +## 审计：已移除/废弃的变量 + +以下变量出现在旧版 `.env.example` 中，但在当前代码库中**没有运行时引用**。它们已被移除： + +| 变量 | 原因 | +| --- | --- | +| `STORAGE_DRIVER=sqlite` | 任何源文件均未读取。SQLite 是唯一支持的驱动 — 无需选择。 | +| `INSTANCE_NAME=omniroute` | 存在于旧文档/环境模板中但运行时未使用。可能在未来多实例功能中回归。 | +| `SQLITE_MAX_SIZE_MB=2048` | 源代码中未引用。数据库大小未被人为限制。 | +| `SQLITE_CLEAN_LEGACY_FILES=true` | 源代码中未引用。旧版清理可能已被移除。 | +| `CLI_ROO_BIN` | 未在 `src/shared/services/cliRuntime.ts` 中注册。 | +| `CLI_KIMI_CODING_BIN` | 未在 `src/shared/services/cliRuntime.ts` 中注册（Kimi Coding 使用 OAuth，而非 CLI 二进制文件）。 | +| `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | 源代码中任何地方均未引用。 | +| `CEREBRAS_API_KEY` / `COHERE_API_KEY` / `FIREWORKS_API_KEY` / `GROQ_API_KEY` / `MISTRAL_API_KEY` / `NEBIUS_API_KEY` / `PERPLEXITY_API_KEY` / `TOGETHER_API_KEY` / `XAI_API_KEY` | 在 v3.8.0 中移除。运行时不再读取这些环境变量 — 凭证来自 Dashboard / `data/provider-credentials.json` / 加密数据库。 | +| `CURSOR_PROTOBUF_DEBUG` | 在 v3.8.0 中移除。Cursor executor 使用 `CURSOR_DEBUG` / `CURSOR_STREAM_DEBUG`（参阅 §22）。 | +| `CLI_COMPAT_KIRO` | 在 v3.8.0 中移除。Kiro 在 `CLI_COMPAT_OMITTED_PROVIDER_IDS` 中 — 其开关无效。 | +| `QIANFAN_API_KEY` | 在 v3.8.0 中随其他未使用的服务商 API key 桩一起移除。 | + +### 默认值修正 + +| 变量 | 旧 `.env.example` 值 | 实际代码默认值 | 修正 | +| --- | --- | --- | --- | +| `APP_LOG_RETENTION_DAYS` | `90` | `7` | ✅ 已移除误导性值；记录 `7` 为默认值 | +| `CALL_LOG_RETENTION_DAYS` | `90` | `7` | ✅ 已移除误导性值；记录 `7` 为默认值 | + +### OpenCode 配置重新生成（临时工具） + +由 `scripts/ad-hoc/regen-opencode-config.ts` 用于重新生成 `opencode.json`， +其中包含从运行中的 OmniRoute 实例拉取的准确的 `limit.context` 和 `limit.output` 值。 +这些变量都不是正常运行所需的 — 该脚本仅供开发者工具使用。 -The following variables appeared in previous versions of `.env.example` but have **no runtime references** in the current codebase. They have been removed: +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_URL` | `http://localhost:20128` | `scripts/ad-hoc/regen-opencode-config.ts` | 查询 `/v1/models` 的 OmniRoute 实例基础 URL。 | +| `OMNIROUTE_KEY` | _(未设置)_ | `scripts/ad-hoc/regen-opencode-config.ts` | 认证 OmniRoute `/v1/models` 端点的 API key。未设置时回退到 `OPENCODE_API_KEY`。 | +| `OPENCODE_API_KEY` | _(未设置)_ | `scripts/ad-hoc/regen-opencode-config.ts` | 写入重新生成的 `opencode.json` 的 OpenCode 风格 API key (`sk-...`)。未设置时回退到 `OMNIROUTE_KEY`。 | -| Variable | Reason | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `STORAGE_DRIVER=sqlite` | Never read by any source file. SQLite is the only supported driver — no selection needed. | -| `INSTANCE_NAME=omniroute` | Present in old docs/env templates but unused at runtime. May return in a future multi-instance feature. | -| `SQLITE_MAX_SIZE_MB=2048` | Not referenced in source code. Database size is not artificially limited. | -| `SQLITE_CLEAN_LEGACY_FILES=true` | Not referenced in source code. Legacy cleanup was likely removed. | -| `CLI_ROO_BIN` | Not registered in `src/shared/services/cliRuntime.ts`. | -| `CLI_KIMI_CODING_BIN` | Not registered in `src/shared/services/cliRuntime.ts` (Kimi Coding uses OAuth, not a CLI binary). | -| `IFLOW_OAUTH_CLIENT_ID` / `IFLOW_OAUTH_CLIENT_SECRET` | Not referenced anywhere in source code. | +### 压缩离线评估工具（临时工具） -### Default Value Corrections +由离线压缩评估 CLI `scripts/compression-eval/index.ts` 使用。 +正常运行不需要 — 仅供开发者工具使用。 -| Variable | Old `.env.example` Value | Actual Code Default | Fixed | -| ------------------------- | ------------------------ | ------------------- | ------------------------------------------------------ | -| `APP_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Removed misleading value; documented `7` as default | -| `CALL_LOG_RETENTION_DAYS` | `90` | `7` | ✅ Removed misleading value; documented `7` as default | +| 变量 | 默认值 | 源文件 | 说明 | +| --- | --- | --- | --- | +| `OMNIROUTE_EVAL_CREDENTIALS` | `{}`（空） | `scripts/compression-eval/index.ts` | 运维人员提供的 JSON 凭证，供离线压缩评估 CLI 使用的服务商使用（通过 `JSON.parse` 解析）。未设置时进行试运行。 | \ No newline at end of file diff --git a/docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md b/docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md index 700609046b32..bade1bc28cbe 100644 --- a/docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md +++ b/docs/i18n/zh-CN/docs/routing/AUTO-COMBO.md @@ -1,67 +1,579 @@ -# OmniRoute Auto-Combo Engine (中文 (简体)) +--- +title: "OmniRoute Auto-Combo Engine" +version: 3.8.40 +lastUpdated: 2026-06-28 +--- -🌐 **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) +# OmniRoute Auto-Combo 引擎 ---- +> **面向用户**：想要快速上手？参见 [Auto-Combo 用户指南](../getting-started/AUTO-COMBO-GUIDE.md)，其中有简明的说明和示例。 + +> 自适应评分的自管理模型链路 + 零配置自动路由 + +## 零配置自动路由（`auto/` 前缀） + +> **新特性：** 无需创建 Combo。在任何客户端中直接使用 `auto/` 前缀。 + +### 快速示例 + +| 模型 ID | 变体 | 行为 | +| -------------- | -------- | ------------------------------------------------------------------------ | +| `auto` | 默认 | 所有已连接服务商，LKGP 策略，均衡权重 | +| `auto/coding` | coding | 质量优先权重，适合代码生成 | +| `auto/fast` | fast | 低延迟加权选择 | +| `auto/cheap` | cheap | 成本优先路由（最便宜优先） | +| `auto/offline` | offline | 偏好配额余量最高的服务商 | +| `auto/smart` | smart | 质量优先 + 更高探索率（10%）以获得更好的模型发现 | +| `auto/lkgp` | lkgp | 显式 LKGP（与默认 `auto` 相同） | + +### 类别 × 层级组合（`auto/:`） + +OpenRouter 风格的后缀将**什么类型的路由**（类别）与**如何优化它**（层级）分开，让你可以自由组合（#4235 Phase B，`open-sse/services/autoCombo/suffixComposition.ts`）： + +- **类别**（按能力筛选候选池）：`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/[:]` 都按需解析；精选子集通过 `/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: + +# 在代码/配置中，将 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**。 + +![Auto-Combo 12-factor scoring](../diagrams/exported/auto-combo-12factor.svg) + +> 来源：[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（最大余量，不论速度/成本） -> Self-managing model chains with adaptive scoring +## 全部路由策略 -## How It Works +OmniRoute 的 Combo 引擎支持 **17 种路由策略**（声明在 `src/shared/constants/routingStrategies.ts` → `ROUTING_STRATEGY_VALUES`）。Auto Combo 引擎本身以 `auto` 策略对外暴露；其余策略供持久化 Combo 使用。 -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: +| 策略 | 描述 | +| :-------------------- | :----------------------------------------------------------------------------------------- | +| `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` 🧬 | 并行扩散到一组评审团模型，然后通过裁判模型合成一个答案（见下文） | -| 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 | +⭐ = v3.8.0 新增 · 🧬 = v3.8.36 新增 -## Mode Packs +## Fusion 策略 -| 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 | +`fusion` 是唯一**不**选择单个目标的策略。它将提示**并行扩散给每个评审团模型**，然后由可配置的**裁判模型**从所有评审团响应中合成为一个最终答案。从上游 `decolua/9router`（OpenRouter 的 Fusion 设计）移植；实现在 `open-sse/services/fusion.ts`。 -## Self-Healing +工作方式： -- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests -- **Incident mode**: >50% OPEN → disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout +1. **扩散**——提示同时发送给每个评审团模型，强制非流式，且剥离工具（裁判模型需要完整的文本来合成）。 +2. **法定-宽限收集**——一旦 `minPanel` 个答案到达，启动短暂的宽限计时器等待落后者，然后以收集到的内容进行融合。这为最慢的模型设置了对墙上时间的惩罚上限，并受硬超时限制。 +3. **裁判合成**——评审团答案被匿名化（`Source 1`、`Source 2`、……——这样裁判看重的是内容质量而非模型品牌），提交给裁判模型，由它分析共识/矛盾/部分覆盖/独特洞察/盲点，然后撰写**一个**权威答案。裁判调用保留客户端的原始 `stream` 标志 + 工具，因此流式传输和下游工具使用仍然有效。 +4. **优雅降级**——0 个评审团答案 → `503`；恰好 1 个幸存者 → 直接返回该答案（无物可融合）；单模型评审团直接回答。 -## Bandit Exploration +### 配置 -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. +在 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 " \ + -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 +**没有专用的 `POST /api/combos/auto` 端点**——Auto-Combo 通过两种方式消费： + +1. **零配置（推荐）：** 发送任何带 `model: "auto"` 或 `model: "auto/"` 的聊天补全请求。虚拟工厂按请求构建 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 -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ +# 零配置用法（无需创建 Combo） +curl -X POST http://localhost:20128/v1/chat/completions \ + -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + -d '{"model":"auto/coding","messages":[{"role":"user","content":"Hello"}]}' -# List auto-combos -curl http://localhost:20128/api/combos/auto +# 通过常规 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 策略 + +持久化的 `strategy: "auto"` Combo 可以设置 `config.routerStrategy`（或旧版 `config.auto.routerStrategy`）为以下之一： + +- `rules` — 默认加权评分 +- `cost` / `eco` — 选择最便宜的健康服务商 +- `latency` / `fast` — 选择最低 p95 延迟且带可靠性惩罚的服务商 +- `sla-aware` / `sla` — 偏好满足 p95 延迟、错误率和可选的成本 SLO 的候选 +- `lkgp` — 优先使用上一次成功路径的服务商 + +### 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 /* ... */ }; + } +} +``` -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score). +**适用场景**：成本敏感的工作负载、批量处理或后台任务。 + +**别名**：`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 访问。 + +--- -## Files +## 文件 -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | +| 文件 | 用途 | +| :---------------------------------------------------------- | :------------------------------------------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | 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 前缀短路 | diff --git a/docs/i18n/zh-CN/llm.txt b/docs/i18n/zh-CN/llm.txt index 4d3f47bfefc0..1a030a700d2d 100644 --- a/docs/i18n/zh-CN/llm.txt +++ b/docs/i18n/zh-CN/llm.txt @@ -4,511 +4,511 @@ --- -> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app. +> OmniRoute 是一个免费、开源的 AI 网关，为多个大语言模型服务商提供通用 API 代理。通过单一 OpenAI 兼容端点，提供智能路由、自动容灾、负载均衡和格式转换功能，覆盖 177 个 AI 服务商。内置 MCP Server（37 个工具）、A2A v0.3 协议、记忆/技能系统、云代理（Codex Cloud、Devin、Jules）、安全护栏框架，以及 Electron 桌面应用。 -## Overview +## 概述 -OmniRoute solves the problem of managing multiple AI provider subscriptions, quotas, and rate limits. It sits between your AI-powered tools (IDE agents, CLI tools) and AI providers, routing requests intelligently through a 4-tier fallback system: Subscription → API Key → Cheap → Free. +OmniRoute 解决了管理多个 AI 服务商订阅、配额和速率限制的问题。它位于你的 AI 驱动工具（IDE 编程助手、CLI 工具）与 AI 服务商之间，通过 4 层容灾体系智能路由请求：订阅 → API Key → 低成本 → 免费。 -**Key value:** One endpoint (`http://localhost:20128/v1`), unlimited models, zero downtime, minimal cost. +**核心价值：** 一个端点（`http://localhost:20128/v1`），无限模型，零停机，最低成本。 -**Current version:** 3.8.8 +**当前版本：** 3.8.8 -## Tech Stack +## 技术栈 -- **Runtime:** Node.js `>=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`) -- **Framework:** Next.js 16 (App Router) with TypeScript 5.9 -- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations) -- **State management:** Zustand (client), SQLite (server persistence) -- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons -- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth -- **Schemas:** Zod v4 for all API / MCP input validation -- **Background jobs:** Custom token health check scheduler, 24h model auto-sync -- **Streaming:** Server-Sent Events (SSE) for real-time proxy responses -- **Proxy engine:** Custom pipeline with format translation, circuit breaker, rate limiting, auto-combo engine -- **i18n:** next-intl with 40+ languages -- **Desktop:** Electron (cross-platform: Windows, macOS, Linux) -- **Package:** Published on npm (`omniroute`) and Docker Hub (`diegosouzapw/omniroute`) +- **运行时：** Node.js `>=22.22.2 <23 || >=24.0.0 <27`，ES Modules（`"type": "module"`） +- **框架：** Next.js 16（App Router）+ TypeScript 5.9 +- **数据库：** SQLite + better-sqlite3（本地、零配置、55 个迁移） +- **状态管理：** Zustand（客户端），SQLite（服务端持久化） +- **UI：** React 19、Tailwind CSS 4、Recharts（分析图表）、@lobehub/icons（130+ 服务商 SVG 图标） +- **认证：** 服务商侧 OAuth 2.0（PKCE），本地用户侧 bcrypt +- **Schema：** Zod v4（所有 API / MCP 输入校验） +- **后台任务：** 自定义 Token 健康检查调度、24 小时模型自动同步 +- **流式传输：** Server-Sent Events（SSE）实时代理响应 +- **代理引擎：** 自定义管线，包含格式转换、熔断器、速率限制、Auto-Combo 引擎 +- **国际化：** next-intl，40+ 种语言 +- **桌面：** Electron（跨平台：Windows、macOS、Linux） +- **包发布：** npm（`omniroute`）和 Docker Hub（`diegosouzapw/omniroute`） -## Project Structure +## 项目结构 ``` / -├── src/ # Main application source -│ ├── app/ # Next.js App Router pages and API routes -│ │ ├── (dashboard)/ # Dashboard UI pages +├── src/ # 主应用源码 +│ ├── app/ # Next.js App Router 页面和 API 路由 +│ │ ├── (dashboard)/ # 仪表盘 UI 页面 │ │ │ └── dashboard/ -│ │ │ ├── agents/ # ACP Agents dashboard (CLI agent detection + custom agents) -│ │ │ ├── analytics/ # Usage analytics and charts -│ │ │ ├── api-manager/ # API key management -│ │ │ ├── audit/ # Audit logs -│ │ │ ├── auto-combo/ # Auto-combo engine dashboard -│ │ │ ├── cache/ # Cache dashboard (semantic cache stats) -│ │ │ ├── cli-tools/ # CLI tool configuration (Claude Code, Codex, etc.) -│ │ │ ├── combos/ # Model combo management (14 strategies + 4 templates) -│ │ │ ├── costs/ # Cost tracking per provider/model -│ │ │ ├── endpoint/ # Unified: Endpoint Proxy, MCP, A2A, API Endpoints tabs -│ │ │ ├── health/ # System health (uptime, circuit breakers, latency) -│ │ │ ├── limits/ # Rate limits dashboard -│ │ │ ├── logs/ # Request, Proxy, Audit, Console logs (tabbed) -│ │ │ ├── media/ # Image/video/music generation + transcription -│ │ │ ├── memory/ # Memory system dashboard -│ │ │ ├── onboarding/ # Onboarding wizard -│ │ │ ├── playground/ # Model playground (Monaco editor, streaming) -│ │ │ ├── providers/ # Provider management (OAuth + API key + free) -│ │ │ ├── search-tools/ # Search tools configuration -│ │ │ ├── settings/ # Settings tabs (General, Appearance, Security, Routing, Resilience, Advanced) -│ │ │ ├── skills/ # Skills system dashboard -│ │ │ ├── translator/ # Format translator + debug tools -│ │ │ └── usage/ # Usage history -│ │ ├── api/ # REST API endpoints (51 route directories) -│ │ │ ├── v1/ # OpenAI-compatible API (chat, completions, models, embeddings, -│ │ │ │ # images, audio, videos, music, moderations, rerank, search, -│ │ │ │ # responses, messages, registered-keys, quotas, accounts) -│ │ │ ├── v1beta/ # Gemini-compatible API -│ │ │ ├── a2a/ # A2A agent management API -│ │ │ ├── acp/ # ACP agent management API -│ │ │ ├── oauth/ # OAuth flows per provider -│ │ │ ├── providers/ # Provider CRUD and batch testing -│ │ │ ├── models/ # Dashboard model listing and aliases -│ │ │ ├── combos/ # Combo CRUD (multi-model fallback chains) -│ │ │ ├── memory/ # Memory system API -│ │ │ ├── skills/ # Skills system API -│ │ │ ├── evals/ # Eval runner API -│ │ │ ├── mcp/ # MCP HTTP transport API -│ │ │ ├── search/ # Search provider API -│ │ │ ├── webhooks/ # Webhook management -│ │ │ ├── tunnels/ # Cloudflare tunnel management -│ │ │ └── ... # Other endpoints (usage, logs, health, settings, pricing, etc.) -│ │ ├── landing/ # Landing page -│ │ ├── login/ # Login page -│ │ ├── forgot-password/ # Password recovery -│ │ ├── status/ # Status page -│ │ └── docs/ # In-app documentation -│ ├── domain/ # Domain types and policy engine -│ │ ├── policyEngine.ts # Central policy engine -│ │ ├── comboResolver.ts # Combo resolution logic -│ │ ├── costRules.ts # Cost calculation rules -│ │ ├── degradation.ts # Graceful degradation -│ │ ├── fallbackPolicy.ts # Fallback behavior -│ │ ├── lockoutPolicy.ts # Account lockout logic -│ │ ├── modelAvailability.ts # Model availability checks -│ │ ├── providerExpiration.ts # Provider credential expiration -│ │ ├── quotaCache.ts # Quota caching layer -│ │ ├── configAudit.ts # Configuration auditing -│ │ └── responses.ts # Domain response types -│ ├── i18n/ # Internationalization -│ │ └── messages/ # 40+ language JSON files -│ ├── lib/ # Core libraries -│ │ ├── a2a/ # Agent-to-Agent v0.3 protocol server -│ │ │ ├── skills/ # A2A skills (quotaManagement, smartRouting) -│ │ │ ├── taskManager.ts # Task lifecycle with TTL cleanup -│ │ │ └── streaming.ts # SSE streaming for A2A -│ │ ├── acp/ # Agent Communication Protocol registry and manager -│ │ ├── compliance/ # Compliance policy engine -│ │ ├── db/ # SQLite database layer (21 modules + migrations) -│ │ │ ├── core.ts # Database initialization, connection, schema -│ │ │ ├── providers.ts # Provider connection CRUD -│ │ │ ├── models.ts # Model catalog management -│ │ │ ├── combos.ts # Combo configuration -│ │ │ ├── apiKeys.ts # API key management -│ │ │ ├── settings.ts # Settings persistence -│ │ │ ├── backup.ts # Database backup/restore -│ │ │ ├── proxies.ts # Proxy registry -│ │ │ ├── prompts.ts # Prompt templates -│ │ │ ├── webhooks.ts # Webhook subscriptions -│ │ │ ├── detailedLogs.ts # Detailed request logging -│ │ │ ├── domainState.ts # Domain state persistence -│ │ │ ├── registeredKeys.ts # Registered API keys with quotas -│ │ │ ├── quotaSnapshots.ts # Quota snapshot history -│ │ │ ├── modelComboMappings.ts # Model-to-combo mappings -│ │ │ ├── cliToolState.ts # CLI tool state tracking -│ │ │ ├── encryption.ts # Data encryption -│ │ │ ├── readCache.ts # Read-through cache layer -│ │ │ ├── secrets.ts # Secrets management -│ │ │ ├── stateReset.ts # State reset utilities -│ │ │ ├── migrationRunner.ts # Schema migration runner -│ │ │ └── migrations/ # 16 SQL migration files -│ │ ├── evals/ # Eval runner and scheduler -│ │ ├── memory/ # Persistent conversational memory -│ │ │ ├── extraction.ts # Memory extraction from conversations -│ │ │ ├── injection.ts # Memory injection into context -│ │ │ ├── retrieval.ts # Memory retrieval/search -│ │ │ ├── store.ts # Memory persistence layer -│ │ │ └── summarization.ts # Memory summarization -│ │ ├── oauth/ # OAuth providers, services, and utilities -│ │ │ ├── constants/ # Default OAuth credentials (overridable via env) -│ │ │ ├── providers/ # Provider-specific OAuth configs -│ │ │ ├── services/ # Provider-specific token exchange logic -│ │ │ └── utils/ # PKCE, callback server, token helpers -│ │ ├── plugins/ # Plugin system -│ │ ├── skills/ # Extensible skill framework -│ │ │ ├── registry.ts # Skill registration -│ │ │ ├── executor.ts # Skill execution engine -│ │ │ ├── sandbox.ts # Skill sandbox environment -│ │ │ ├── builtin/ # Built-in skills -│ │ │ ├── interception.ts # Skill request interception -│ │ │ └── injection.ts # Skill context injection -│ │ ├── usage/ # Usage tracking system -│ │ │ ├── callLogs.ts # Call log persistence -│ │ │ ├── costCalculator.ts # Cost calculation engine -│ │ │ └── usageHistory.ts # Usage history queries -│ │ ├── cloudSync.ts # Cloud sync via Cloudflare Workers -│ │ ├── cloudflaredTunnel.ts # Cloudflare tunnel management -│ │ ├── pricingSync.ts # LiteLLM pricing data sync -│ │ ├── semanticCache.ts # Semantic caching layer -│ │ ├── tokenHealthCheck.ts # Background OAuth token refresh scheduler -│ │ ├── webhookDispatcher.ts # Webhook event dispatcher -│ │ └── localDb.ts # Unified re-export layer for all DB modules -│ ├── middleware/ # Request middleware -│ │ └── promptInjectionGuard.ts # Prompt injection detection -│ ├── mitm/ # MITM proxy capability -│ │ ├── cert/ # Certificate management -│ │ ├── dns/ # DNS handling -│ │ ├── targets/ # Target routing -│ │ └── manager.ts # MITM proxy manager -│ ├── shared/ # Shared utilities, components, and constants -│ │ ├── components/ # Reusable UI components (Card, Badge, Button, Modal, Sidebar, ProviderIcon, etc.) -│ │ ├── constants/ # Provider definitions (160+), model lists, pricing, routing strategies, MCP scopes -│ │ ├── contracts/ # Shared API contracts -│ │ ├── hooks/ # React hooks -│ │ ├── middleware/ # Shared middleware utilities -│ │ ├── schemas/ # Shared Zod schemas -│ │ ├── services/ # Shared services -│ │ ├── types/ # Shared TypeScript types -│ │ ├── validation/ # Zod schemas (settings, providers, routes) -│ │ └── utils/ # Helpers (auth, CORS, error codes, machine ID) -│ ├── sse/ # SSE proxy pipeline -│ │ ├── services/ # Auth resolution, format translation, response handling -│ │ └── middleware/ # Rate limiting, circuit breaker, caching, idempotency -│ ├── store/ # Zustand client-side stores (theme, providers, etc.) -│ └── types/ # TypeScript type definitions -├── open-sse/ # Standalone SSE server (npm workspace) -│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video, -│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models) -│ ├── executors/ # Provider-specific request executors (31 executors) -│ │ ├── base.ts # Base executor with shared logic -│ │ ├── default.ts # Default OpenAI-compatible executor -│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum) +│ │ │ ├── agents/ # ACP 代理仪表盘（CLI 编程助手检测 + 自定义代理） +│ │ │ ├── analytics/ # 用量分析和图表 +│ │ │ ├── api-manager/ # API Key 管理 +│ │ │ ├── audit/ # 审计日志 +│ │ │ ├── auto-combo/ # Auto-Combo 引擎仪表盘 +│ │ │ ├── cache/ # 缓存仪表盘（语义缓存统计） +│ │ │ ├── cli-tools/ # CLI 工具配置（Claude Code、Codex 等） +│ │ │ ├── combos/ # 模型 Combo 管理（14 种策略 + 4 个模板） +│ │ │ ├── costs/ # 按服务商/模型统计成本 +│ │ │ ├── endpoint/ # 统一入口：端点代理、MCP、A2A、API 端点（选项卡） +│ │ │ ├── health/ # 系统健康（运行时长、熔断器、延迟） +│ │ │ ├── limits/ # 速率限制仪表盘 +│ │ │ ├── logs/ # 请求、代理、审计、控制台日志（选项卡） +│ │ │ ├── media/ # 图像/视频/音乐生成 + 语音转录 +│ │ │ ├── memory/ # 记忆系统仪表盘 +│ │ │ ├── onboarding/ # 入门向导 +│ │ │ ├── playground/ # 模型游乐场（Monaco 编辑器、流式响应） +│ │ │ ├── providers/ # 服务商管理（OAuth + API Key + 免费） +│ │ │ ├── search-tools/ # 搜索工具配置 +│ │ │ ├── settings/ # 设置选项卡（常规、外观、安全、路由、容灾、高级） +│ │ │ ├── skills/ # 技能系统仪表盘 +│ │ │ ├── translator/ # 格式转换器 + 调试工具 +│ │ │ └── usage/ # 用量历史 +│ │ ├── api/ # REST API 端点（51 个路由目录） +│ │ │ ├── v1/ # OpenAI 兼容 API（chat、completions、models、embeddings、 +│ │ │ │ # images、audio、videos、music、moderations、rerank、search、 +│ │ │ │ # responses、messages、registered-keys、quotas、accounts） +│ │ │ ├── v1beta/ # Gemini 兼容 API +│ │ │ ├── a2a/ # A2A 代理管理 API +│ │ │ ├── acp/ # ACP 代理管理 API +│ │ │ ├── oauth/ # 各服务商 OAuth 流程 +│ │ │ ├── providers/ # 服务商 CRUD 和批量测试 +│ │ │ ├── models/ # 仪表盘模型列表和别名 +│ │ │ ├── combos/ # Combo CRUD（多模型容灾链路） +│ │ │ ├── memory/ # 记忆系统 API +│ │ │ ├── skills/ # 技能系统 API +│ │ │ ├── evals/ # 评估运行器 API +│ │ │ ├── mcp/ # MCP HTTP 传输 API +│ │ │ ├── search/ # 搜索服务商 API +│ │ │ ├── webhooks/ # Webhook 管理 +│ │ │ ├── tunnels/ # Cloudflare 隧道管理 +│ │ │ └── ... # 其他端点（用量、日志、健康、设置、定价等） +│ │ ├── landing/ # 着陆页 +│ │ ├── login/ # 登录页 +│ │ ├── forgot-password/ # 密码找回 +│ │ ├── status/ # 状态页 +│ │ └── docs/ # 应用内文档 +│ ├── domain/ # 领域类型和策略引擎 +│ │ ├── policyEngine.ts # 中央策略引擎 +│ │ ├── comboResolver.ts # Combo 解析逻辑 +│ │ ├── costRules.ts # 成本计算规则 +│ │ ├── degradation.ts # 优雅降级 +│ │ ├── fallbackPolicy.ts # 容灾行为 +│ │ ├── lockoutPolicy.ts # 账户锁定逻辑 +│ │ ├── modelAvailability.ts # 模型可用性检查 +│ │ ├── providerExpiration.ts # 服务商凭证过期 +│ │ ├── quotaCache.ts # 配额缓存层 +│ │ ├── configAudit.ts # 配置审计 +│ │ └── responses.ts # 领域响应类型 +│ ├── i18n/ # 国际化 +│ │ └── messages/ # 40+ 语言 JSON 文件 +│ ├── lib/ # 核心库 +│ │ ├── a2a/ # Agent-to-Agent v0.3 协议服务器 +│ │ │ ├── skills/ # A2A 技能（quotaManagement、smartRouting） +│ │ │ ├── taskManager.ts # 任务生命周期管理 + TTL 清理 +│ │ │ └── streaming.ts # A2A SSE 流式传输 +│ │ ├── acp/ # Agent Communication Protocol 注册表和管理器 +│ │ ├── compliance/ # 合规策略引擎 +│ │ ├── db/ # SQLite 数据库层（21 个模块 + 迁移） +│ │ │ ├── core.ts # 数据库初始化、连接、Schema +│ │ │ ├── providers.ts # 服务商连接 CRUD +│ │ │ ├── models.ts # 模型目录管理 +│ │ │ ├── combos.ts # Combo 配置 +│ │ │ ├── apiKeys.ts # API Key 管理 +│ │ │ ├── settings.ts # 设置持久化 +│ │ │ ├── backup.ts # 数据库备份/恢复 +│ │ │ ├── proxies.ts # 代理注册表 +│ │ │ ├── prompts.ts # 提示模板 +│ │ │ ├── webhooks.ts # Webhook 订阅 +│ │ │ ├── detailedLogs.ts # 详细请求日志 +│ │ │ ├── domainState.ts # 领域状态持久化 +│ │ │ ├── registeredKeys.ts # 已注册 API Key（含配额） +│ │ │ ├── quotaSnapshots.ts # 配额快照历史 +│ │ │ ├── modelComboMappings.ts # 模型到 Combo 映射 +│ │ │ ├── cliToolState.ts # CLI 工具状态追踪 +│ │ │ ├── encryption.ts # 数据加密 +│ │ │ ├── readCache.ts # 读穿透缓存层 +│ │ │ ├── secrets.ts # 密钥管理 +│ │ │ ├── stateReset.ts # 状态重置工具 +│ │ │ ├── migrationRunner.ts # Schema 迁移运行器 +│ │ │ └── migrations/ # 16 个 SQL 迁移文件 +│ │ ├── evals/ # 评估运行器和调度器 +│ │ ├── memory/ # 持久化对话记忆 +│ │ │ ├── extraction.ts # 对话记忆提取 +│ │ │ ├── injection.ts # 上下文中注入记忆 +│ │ │ ├── retrieval.ts # 记忆检索/搜索 +│ │ │ ├── store.ts # 记忆持久层 +│ │ │ └── summarization.ts # 记忆摘要 +│ │ ├── oauth/ # OAuth 服务商、服务和工具 +│ │ │ ├── constants/ # OAuth 默认凭证（可通过环境变量覆盖） +│ │ │ ├── providers/ # 各服务商 OAuth 配置 +│ │ │ ├── services/ # 各服务商 Token 交换逻辑 +│ │ │ └── utils/ # PKCE、回调服务器、Token 辅助工具 +│ │ ├── plugins/ # 插件系统 +│ │ ├── skills/ # 可扩展技能框架 +│ │ │ ├── registry.ts # 技能注册 +│ │ │ ├── executor.ts # 技能执行引擎 +│ │ │ ├── sandbox.ts # 技能沙箱环境 +│ │ │ ├── builtin/ # 内置技能 +│ │ │ ├── interception.ts # 技能请求拦截 +│ │ │ └── injection.ts # 技能上下文注入 +│ │ ├── usage/ # 用量追踪系统 +│ │ │ ├── callLogs.ts # 调用日志持久化 +│ │ │ ├── costCalculator.ts # 成本计算引擎 +│ │ │ └── usageHistory.ts # 用量历史查询 +│ │ ├── cloudSync.ts # Cloudflare Workers 云端同步 +│ │ ├── cloudflaredTunnel.ts # Cloudflare 隧道管理 +│ │ ├── pricingSync.ts # LiteLLM 定价数据同步 +│ │ ├── semanticCache.ts # 语义缓存层 +│ │ ├── tokenHealthCheck.ts # 后台 OAuth Token 刷新调度 +│ │ ├── webhookDispatcher.ts # Webhook 事件分发器 +│ │ └── localDb.ts # 所有 DB 模块的统一再导出层 +│ ├── middleware/ # 请求中间件 +│ │ └── promptInjectionGuard.ts # 提示注入检测 +│ ├── mitm/ # MITM 代理能力 +│ │ ├── cert/ # 证书管理 +│ │ ├── dns/ # DNS 处理 +│ │ ├── targets/ # 目标路由 +│ │ └── manager.ts # MITM 代理管理器 +│ ├── shared/ # 共享工具、组件和常量 +│ │ ├── components/ # 可复用 UI 组件（Card、Badge、Button、Modal、Sidebar、ProviderIcon 等） +│ │ ├── constants/ # 服务商定义（160+）、模型列表、定价、路由策略、MCP 权限域 +│ │ ├── contracts/ # 共享 API 契约 +│ │ ├── hooks/ # React Hooks +│ │ ├── middleware/ # 共享中间件工具 +│ │ ├── schemas/ # 共享 Zod Schema +│ │ ├── services/ # 共享服务 +│ │ ├── types/ # 共享 TypeScript 类型 +│ │ ├── validation/ # Zod Schema（设置、服务商、路由） +│ │ └── utils/ # 辅助工具（认证、CORS、错误码、机器 ID） +│ ├── sse/ # SSE 代理管线 +│ │ ├── services/ # 认证解析、格式转换、响应处理 +│ │ └── middleware/ # 速率限制、熔断器、缓存、幂等 +│ ├── store/ # Zustand 客户端状态（主题、服务商等） +│ └── types/ # TypeScript 类型定义 +├── open-sse/ # 独立 SSE 服务器（npm workspace） +│ ├── config/ # 模型注册表（providerRegistry、embedding、image、audio、video、 +│ │ # music、rerank、moderation、search、CLI 指纹、Ollama 模型） +│ ├── executors/ # 各服务商请求执行器（31 个执行器） +│ │ ├── base.ts # 基础执行器（共享逻辑） +│ │ ├── default.ts # 默认 OpenAI 兼容执行器 +│ │ ├── cursor.ts # Cursor IDE（protobuf + checksum） │ │ ├── codex.ts # OpenAI Codex CLI │ │ ├── antigravity.ts # Antigravity IDE │ │ ├── github.ts # GitHub Copilot │ │ ├── kiro.ts # Kiro AI │ │ ├── qoder.ts # Qoder AI -│ │ ├── vertex.ts # Vertex AI (Service Account JSON) +│ │ ├── vertex.ts # Vertex AI（Service Account JSON） │ │ ├── cloudflare-ai.ts # Cloudflare Workers AI │ │ ├── opencode.ts # OpenCode Zen/Go │ │ ├── pollinations.ts # Pollinations AI │ │ └── puter.ts # Puter AI -│ ├── handlers/ # Request handlers per API type (11 handlers) -│ │ ├── chatCore.ts # Main chat completions handler -│ │ ├── responsesHandler.ts # OpenAI Responses API handler -│ │ ├── embeddings.ts # Embedding generation -│ │ ├── imageGeneration.ts # Image generation (GPT-Image, FLUX, SD, etc.) -│ │ ├── videoGeneration.ts # Video generation -│ │ ├── musicGeneration.ts # Music generation -│ │ ├── audioSpeech.ts # Text-to-speech -│ │ ├── audioTranscription.ts # Speech-to-text (Whisper, Deepgram, AssemblyAI) -│ │ ├── moderations.ts # Content moderation +│ ├── handlers/ # 各 API 类型的请求处理器（11 个处理器） +│ │ ├── chatCore.ts # 主 Chat Completions 处理器 +│ │ ├── responsesHandler.ts # OpenAI Responses API 处理器 +│ │ ├── embeddings.ts # Embedding 生成 +│ │ ├── imageGeneration.ts # 图像生成（GPT-Image、FLUX、SD 等） +│ │ ├── videoGeneration.ts # 视频生成 +│ │ ├── musicGeneration.ts # 音乐生成 +│ │ ├── audioSpeech.ts # 文本转语音 +│ │ ├── audioTranscription.ts # 语音转文本（Whisper、Deepgram、AssemblyAI） +│ │ ├── moderations.ts # 内容审核 │ │ ├── rerank.ts # Reranking API -│ │ └── search.ts # Web search API -│ ├── mcp-server/ # Built-in MCP server (29 tools, 3 transports: stdio/SSE/streamable-HTTP) -│ │ ├── server.ts # MCP server core (tool registration, scope enforcement) -│ │ ├── tools/ # Tool implementations (advancedTools, memoryTools, skillTools) -│ │ ├── schemas/ # Zod input schemas (tools, audit, a2a) -│ │ ├── scopeEnforcement.ts # Scope-based access control (10 scopes) -│ │ ├── audit.ts # Tool call audit logging -│ │ ├── runtimeHeartbeat.ts # MCP runtime heartbeat -│ │ └── httpTransport.ts # HTTP transport handler -│ ├── services/ # 36+ service modules -│ │ ├── combo.ts # Core routing engine -│ │ ├── usage.ts # Usage tracking -│ │ ├── tokenRefresh.ts # OAuth token refresh -│ │ ├── rateLimitManager.ts # Rate limit management -│ │ ├── accountFallback.ts # Multi-account fallback -│ │ ├── sessionManager.ts # Session management -│ │ ├── wildcardRouter.ts # Wildcard model routing -│ │ ├── autoCombo/ # Auto-combo engine (6-factor scoring, bandit exploration) -│ │ ├── intentClassifier.ts # Request intent classification -│ │ ├── taskAwareRouter.ts # Task-aware routing -│ │ ├── thinkingBudget.ts # Thinking budget management -│ │ ├── contextManager.ts # Context window management -│ │ ├── modelDeprecation.ts # Model deprecation handling -│ │ ├── modelFamilyFallback.ts # Intra-family model fallback -│ │ ├── emergencyFallback.ts # Emergency fallback -│ │ ├── workflowFSM.ts # Workflow state machine -│ │ ├── backgroundTaskDetector.ts # Background task detection -│ │ ├── ipFilter.ts # IP-based access control -│ │ ├── signatureCache.ts # CLI signature caching -│ │ ├── volumeDetector.ts # Request volume detection -│ │ ├── contextHandoff.ts # Context relay handoff generation and injection -│ │ ├── codexQuotaFetcher.ts # Codex quota fetching for context-relay -│ │ └── ... # Additional services (14 more modules) -│ ├── transformer/ # Responses API transformer +│ │ └── search.ts # 网页搜索 API +│ ├── mcp-server/ # 内置 MCP Server（29 个工具，3 种传输：stdio/SSE/streamable-HTTP） +│ │ ├── server.ts # MCP Server 核心（工具注册、权限域强制） +│ │ ├── tools/ # 工具实现（advancedTools、memoryTools、skillTools） +│ │ ├── schemas/ # Zod 输入 Schema（工具、审计、A2A） +│ │ ├── scopeEnforcement.ts # 基于权限域的访问控制（10 个权限域） +│ │ ├── audit.ts # 工具调用审计日志 +│ │ ├── runtimeHeartbeat.ts # MCP 运行时心跳 +│ │ └── httpTransport.ts # HTTP 传输处理器 +│ ├── services/ # 36+ 个服务模块 +│ │ ├── combo.ts # 核心路由引擎 +│ │ ├── usage.ts # 用量追踪 +│ │ ├── tokenRefresh.ts # OAuth Token 刷新 +│ │ ├── rateLimitManager.ts # 速率限制管理 +│ │ ├── accountFallback.ts # 多账户容灾 +│ │ ├── sessionManager.ts # 会话管理 +│ │ ├── wildcardRouter.ts # 通配符模型路由 +│ │ ├── autoCombo/ # Auto-Combo 引擎（6 因子评分、bandit 探索） +│ │ ├── intentClassifier.ts # 请求意图分类 +│ │ ├── taskAwareRouter.ts # 任务感知路由 +│ │ ├── thinkingBudget.ts # 思考预算管理 +│ │ ├── contextManager.ts # 上下文窗口管理 +│ │ ├── modelDeprecation.ts # 模型弃用处理 +│ │ ├── modelFamilyFallback.ts # 模型族内容灾 +│ │ ├── emergencyFallback.ts # 紧急容灾 +│ │ ├── workflowFSM.ts # 工作流状态机 +│ │ ├── backgroundTaskDetector.ts # 后台任务检测 +│ │ ├── ipFilter.ts # 基于 IP 的访问控制 +│ │ ├── signatureCache.ts # CLI 签名缓存 +│ │ ├── volumeDetector.ts # 请求量检测 +│ │ ├── contextHandoff.ts # 上下文中继交接生成与注入 +│ │ ├── codexQuotaFetcher.ts # Codex 配额获取（用于 context-relay） +│ │ └── ... # 其他服务（另有 14 个模块） +│ ├── transformer/ # Responses API 转换器 │ │ └── responsesTransformer.ts -│ ├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek) -│ │ ├── request/ # Request translators per provider -│ │ ├── response/ # Response translators per provider -│ │ ├── helpers/ # Translation helpers -│ │ └── image/ # Image format translation -│ └── utils/ # 22 utility modules (stream, TLS, proxy, logging, etc.) -├── electron/ # Electron desktop app (cross-platform) -│ ├── main.js # Electron main process -│ ├── preload.js # Preload script (IPC bridge) -│ └── assets/ # App icons and assets -├── tests/ # Test suites -│ ├── unit/ # 122 unit test files -│ ├── integration/ # Integration tests -│ ├── e2e/ # Playwright E2E tests -│ ├── security/ # Security tests -│ ├── translator/ # Translator-specific tests -│ └── load/ # Load tests -├── docs/ # Documentation -│ ├── i18n/ # 30-language translated docs -│ ├── ARCHITECTURE.md # Full architecture documentation -│ ├── API_REFERENCE.md # API reference -│ ├── USER_GUIDE.md # User guide -│ ├── CODEBASE_DOCUMENTATION.md # Codebase overview -│ ├── CLI-TOOLS.md # CLI tools integration guide -│ ├── A2A-SERVER.md # A2A agent protocol documentation -│ ├── AUTO-COMBO.md # Auto-combo engine (6-factor scoring) -│ ├── MCP-SERVER.md # MCP server (29 tools) -│ ├── TROUBLESHOOTING.md # Troubleshooting guide -│ ├── VM_DEPLOYMENT_GUIDE.md # VPS deployment guide -│ ├── openapi.yaml # OpenAPI specification -│ └── screenshots/ # Dashboard screenshots -├── bin/ # CLI entry points (omniroute, reset-password) -├── scripts/ # Build and utility scripts -└── .env.example # Environment variable template +│ ├── translator/ # 格式转换器（OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek） +│ │ ├── request/ # 各服务商请求转换器 +│ │ ├── response/ # 各服务商响应转换器 +│ │ ├── helpers/ # 转换辅助工具 +│ │ └── image/ # 图像格式转换 +│ └── utils/ # 22 个工具模块（流、TLS、代理、日志等） +├── electron/ # Electron 桌面应用（跨平台） +│ ├── main.js # Electron 主进程 +│ ├── preload.js # 预加载脚本（IPC 桥接） +│ └── assets/ # 应用图标和资源 +├── tests/ # 测试套件 +│ ├── unit/ # 122 个单元测试文件 +│ ├── integration/ # 集成测试 +│ ├── e2e/ # Playwright E2E 测试 +│ ├── security/ # 安全测试 +│ ├── translator/ # 转换器专项测试 +│ └── load/ # 负载测试 +├── docs/ # 文档 +│ ├── i18n/ # 30 语言翻译文档 +│ ├── ARCHITECTURE.md # 完整架构文档 +│ ├── API_REFERENCE.md # API 参考 +│ ├── USER_GUIDE.md # 用户指南 +│ ├── CODEBASE_DOCUMENTATION.md # 代码库概述 +│ ├── CLI-TOOLS.md # CLI 工具集成指南 +│ ├── A2A-SERVER.md # A2A 代理协议文档 +│ ├── AUTO-COMBO.md # Auto-Combo 引擎（6 因子评分） +│ ├── MCP-SERVER.md # MCP Server（29 个工具） +│ ├── TROUBLESHOOTING.md # 故障排除指南 +│ ├── VM_DEPLOYMENT_GUIDE.md # VPS 部署指南 +│ ├── openapi.yaml # OpenAPI 规范 +│ └── screenshots/ # 仪表盘截图 +├── bin/ # CLI 入口点（omniroute、reset-password） +├── scripts/ # 构建和工具脚本 +└── .env.example # 环境变量模板 ``` -## Key Features (v3.8.8) - -### Core Proxy -- **177 AI providers** with automatic format translation -- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible) -- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8) -- **4-tier fallback**: Subscription → API Key → Cheap → Free -- **Context Relay strategy**: Session handoff summaries on account rotation for continuity -- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown -- **Semantic caching** with cache hit/miss headers -- **Idempotency** with configurable dedup window -- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout -- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback -- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers -- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement -- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization -- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills -- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management -- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered) -- **MITM Proxy**: Certificate management, DNS handling, and target routing -- **Cloudflare Tunnels**: Managed tunnel creation for remote access -- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%) - -### Security -- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots. -- **CodeQL security**: Fixed 10+ CodeQL alerts (polynomial-redos, insecure-randomness, shell-injection, SSRF, incomplete URLs) -- **Web Crypto session IDs**: `generateSessionId` uses `crypto.getRandomValues()` instead of `Math.random()` -- **Route validation**: All API routes validated with Zod v4 schemas + `validateBody()` -- **omniModel tag sanitization**: Internal `` tags never leak to clients in SSE streams -- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint to reduce bot detection -- **CLI Fingerprint Matching** — Per-provider request signature matching -- **Prompt injection guard** — Request middleware detection -- **Provider constants validated at module load** via Zod (`src/shared/validation/providerSchema.ts`) -- **PII sanitizer** — Sensitive data scrubbing in logs - -### Dashboard Pages (23 sections) -- **Providers** — OAuth, API key, and free provider management with ProviderIcon SVG icons -- **Combos** — Multi-model combo builder with 4 templates (Free Stack, High Availability, Cost Saver, Balanced) + 14 strategies -- **Auto-Combo** — Auto-combo engine dashboard with scoring metrics -- **Analytics** — Token consumption, cost, heatmaps, distributions -- **Health** — Uptime, memory, latency percentiles, circuit breakers -- **Logs** — Request, Proxy, Audit, Console (tabbed) -- **Audit** — Audit trail and compliance logging -- **Costs** — Cost tracking per provider/model -- **Limits** — Rate limit monitoring -- **Cache** — Semantic cache statistics and management -- **CLI Tools** — One-click configuration for 10+ AI CLI tools -- **CLI Agents** — Grid of 14+ built-in agents with ProviderIcon and install detection + custom agent registration -- **Playground** — Test any model with Monaco editor, streaming responses -- **Media** — Image/video/music generation (GPT-Image, FLUX, etc.) + audio transcription (up to 2GB files) -- **Search Tools** — Search provider configuration and testing -- **Memory** — Memory system management and visualization -- **Skills** — Skills framework management and execution -- **Translator** — Format debugging: playground, chat tester, test bench, live monitor -- **Settings** — General, Appearance (7 color themes), Security (TLS/CLI fingerprint, IP filter), Routing, Resilience, Advanced -- **Endpoint** — Unified: Endpoint Proxy, MCP Server, A2A Server, API Endpoints (tabbed) -- **Onboarding** — Setup wizard for new users -- **Usage** — Usage history and analytics -- **API Manager** — API key management with scoped permissions - -### Protocol Support -- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech`, `/v1/moderations`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` -- **Anthropic** — `/v1/messages`, `/v1/messages/count_tokens` +## 核心功能（v3.8.8） + +### 核心代理 +- **177 个 AI 服务商**，自动格式转换 +- **4 类服务商**：免费（5）、OAuth（14）、API Key（123+）、自托管（8+）、自定义（OpenAI/Anthropic 兼容） +- **14 种路由策略**：priority、weighted、round-robin、fill-first、p2c、random、least-used、cost-optimized、strict-random、auto、lkgp、context-optimized、context-relay、**reset-aware**（v3.8） +- **4 层容灾**：订阅 → API Key → 低成本 → 免费 +- **Context Relay 策略**：账户轮换时生成会话交接摘要，确保连续性 +- **Auto-Combo 引擎**：自修复路由优化，**9 因子评分**（health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity）、bandit 探索、渐进式冷却 +- **语义缓存**，带缓存命中/未命中响应头 +- **幂等**，支持可配置的去重窗口 +- **3 层容灾**：服务商熔断器 / 连接冷却 / 模型锁定 +- **服务商图标**：130+ 服务商 Logo，通过 `@lobehub/icons`（SVG）+ PNG 降级 +- **模型自动同步**：24 小时调度任务，刷新 16 个服务商的模型列表 +- **已注册 Key API**：通过 `POST /api/v1/registered-keys` 自动发放 API Key，带配额强制 +- **记忆系统**：持久化对话记忆，支持提取、注入、检索和摘要 +- **技能系统**：可扩展技能框架，含注册表、执行器、沙箱、内置和自定义技能 +- **云代理**：Codex Cloud、Devin、Jules — 自主编程代理，带任务生命周期管理 +- **安全护栏框架**：热重载注册表，含 vision-bridge、pii-masker、prompt-injection（按优先级排序） +- **MITM 代理**：证书管理、DNS 处理和目标路由 +- **Cloudflare 隧道**：托管隧道创建，支持远程访问 +- **覆盖率门禁**：75% statements/lines/functions，70% branches（实测约 82%） + +### 安全 +- **数据丢失防护**：SQLite 迁移安全检查会在大规模 Schema 危险覆盖时中止启动。迁移前执行 `VACUUM INTO` 备份，隔离回滚快照。 +- **CodeQL 安全**：修复 10+ CodeQL 告警（多项式 ReDoS、不安全随机数、Shell 注入、SSRF、不完整 URL） +- **Web Crypto 会话 ID**：`generateSessionId` 使用 `crypto.getRandomValues()` 而非 `Math.random()` +- **路由校验**：所有 API 路由通过 Zod v4 Schema + `validateBody()` 校验 +- **omniModel 标签清理**：内部 `` 标签绝不会在 SSE 流中泄露给客户端 +- **TLS 指纹伪装** — 模拟浏览器 TLS 指纹，降低机器人检测 +- **CLI 指纹匹配** — 各服务商请求签名匹配 +- **提示注入检测** — 请求中间件检测 +- **服务商常量在模块加载时校验**，通过 Zod（`src/shared/validation/providerSchema.ts`） +- **PII 脱敏** — 日志中的敏感数据擦除 + +### 仪表盘页面（23 个板块） +- **服务商** — OAuth、API Key 和免费服务商管理，带 ProviderIcon SVG 图标 +- **Combo** — 多模型 Combo 构建器，含 4 个模板（免费栈、高可用、成本节约、均衡）+ 14 种策略 +- **Auto-Combo** — Auto-Combo 引擎仪表盘，展示评分指标 +- **分析** — Token 消耗、成本、热力图、分布 +- **健康** — 运行时长、内存、延迟百分位数、熔断器 +- **日志** — 请求、代理、审计、控制台（选项卡） +- **审计** — 审计追踪和合规日志 +- **成本** — 按服务商/模型统计成本 +- **限制** — 速率限制监控 +- **缓存** — 语义缓存统计和管理 +- **CLI 工具** — 10+ AI CLI 工具一键配置 +- **CLI 代理** — 14+ 内置代理网格，带 ProviderIcon 和安装检测 + 自定义代理注册 +- **游乐场** — Monaco 编辑器测试任意模型，流式响应 +- **媒体** — 图像/视频/音乐生成（GPT-Image、FLUX 等）+ 语音转录（最高 2GB 文件） +- **搜索工具** — 搜索服务商配置和测试 +- **记忆** — 记忆系统管理和可视化 +- **技能** — 技能框架管理和执行 +- **转换器** — 格式调试：游乐场、对话测试器、测试台、实时监控 +- **设置** — 常规、外观（7 种颜色主题）、安全（TLS/CLI 指纹、IP 过滤）、路由、容灾、高级 +- **端点** — 统一入口：端点代理、MCP Server、A2A Server、API 端点（选项卡） +- **入门** — 新用户配置向导 +- **用量** — 用量历史和分析 +- **API 管理** — API Key 管理，带权限域授权 + +### 协议支持 +- **OpenAI 兼容** — `/v1/chat/completions`、`/v1/models`、`/v1/embeddings`、`/v1/images/generations`、`/v1/audio/transcriptions`、`/v1/audio/speech`、`/v1/moderations`、`/v1/rerank`、`/v1/videos/generations`、`/v1/music/generations` +- **Anthropic** — `/v1/messages`、`/v1/messages/count_tokens` - **OpenAI Responses** — `/v1/responses` -- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}` -- **Ollama** — `/v1/api/chat`, `/api/tags` -- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily) -- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP) -- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report) -- **ACP** — Agent Communication Protocol registry and manager +- **Gemini** — `/v1beta/models`、`/v1beta/models/{...path}` +- **Ollama** — `/v1/api/chat`、`/api/tags` +- **搜索** — `/v1/search`（Perplexity、Serper、Brave、Exa、Tavily） +- **MCP** — 37 工具 MCP Server，带基于权限域的认证（3 种传输：stdio、SSE、streamable HTTP） +- **A2A** — Agent-to-Agent v0.3 协议（JSON-RPC 2.0，5 个技能：smart-routing、quota-management、provider-discovery、cost-analysis、health-report） +- **ACP** — Agent Communication Protocol 注册表和管理器 -### MCP Server (37 Tools) -| Category | Tools | -|------------|-------| -| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/frameworks/MCP-SERVER.md` for full inventory) | -| Memory (3) | `memory_search`, `memory_add`, `memory_clear` | -| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` | +### MCP Server（37 个工具） +| 分类 | 工具 | +|------|------| +| 核心（30） | `get_health`、`list_combos`、`get_combo_metrics`、`switch_combo`、`check_quota`、`route_request`、`cost_report`、`list_models_catalog`、`web_search`、`simulate_route`、`set_budget_guard`、`set_routing_strategy`、`set_resilience_profile`、`test_combo`、`get_provider_metrics`、`best_combo_for_task`、`explain_route`、`get_session_snapshot`、`db_health_check`、`sync_pricing`、`cache_stats`、`cache_flush`，以及高级路由/诊断工具（完整清单见 `docs/frameworks/MCP-SERVER.md`） | +| 记忆（3） | `memory_search`、`memory_add`、`memory_clear` | +| 技能（4） | `skills_list`、`skills_enable`、`skills_execute`、`skills_executions` | -**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/frameworks/MCP-SERVER.md`. +**MCP 认证权限域（约 13 个）：** `read:health`、`read:combos`、`write:combos`、`read:quota`、`read:usage`、`read:models`、`execute:completions`、`execute:search`、`write:budget`、`write:resilience`，以及记忆/技能权限域 — 完整列表见 `docs/frameworks/MCP-SERVER.md`。 -### Provider Categories +### 服务商分类 -**Free Providers (4):** Qoder AI, Qwen Code (deprecated), Kiro AI, Windsurf +**免费服务商（4 个）：** Qoder AI、Qwen Code（已弃用）、Kiro AI、Windsurf -**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo +**OAuth 服务商（14 个）：** Claude Code、Antigravity、OpenAI Codex、GitHub Copilot、Cursor IDE、Kimi Coding、Kilo Code、Cline、Qwen、Kiro、Qoder、Gemini、Windsurf、GitLab Duo -**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba, Alibaba (China), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Alibaba Coding Plan +**API Key 服务商（48+）：** OpenAI、Anthropic、Gemini (Google AI Studio)、DeepSeek、Groq、xAI (Grok)、Mistral、Perplexity、Together AI、Fireworks AI、Cerebras、Cohere、NVIDIA NIM、Nebius AI、SiliconFlow、Hyperbolic、HuggingFace、OpenRouter、Vertex AI、Cloudflare Workers AI、Scaleway AI、AI/ML API、Pollinations AI、Puter AI、LongCat AI、Alibaba、Alibaba (China)、Kimi、Kimi Coding (API Key)、Minimax、Minimax (China)、Blackbox AI、Synthetic、Kilo Gateway、Z.AI、GLM Coding、Deepgram、AssemblyAI、ElevenLabs、Cartesia、PlayHT、Inworld、NanoBanana、SD WebUI、ComfyUI、Ollama Cloud、Perplexity Search、Serper Search、Brave Search、Exa Search、Tavily Search、OpenCode Zen、OpenCode Go、Alibaba Coding Plan -**Custom Providers:** OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) with custom base URLs +**自定义服务商：** OpenAI 兼容（`openai-compatible-*`）和 Anthropic 兼容（`anthropic-compatible-*`），支持自定义基础 URL -### Internationalization -- 40+ languages for UI (all dashboard pages) -- 40 translated documentation sets in docs/i18n/ -- Language switcher in documentation +### 国际化 +- 40+ 种 UI 语言（覆盖全部仪表盘页面） +- 40 套翻译文档，位于 docs/i18n/ +- 文档内置语言切换器 -## Key Architectural Decisions +## 关键架构决策 -1. **OpenAI-compatible API surface:** All incoming requests follow the OpenAI API format. This makes OmniRoute a drop-in replacement for any tool that supports custom OpenAI endpoints. +1. **OpenAI 兼容 API 接口：** 所有入站请求遵循 OpenAI API 格式。这使 OmniRoute 可以作为任何支持自定义 OpenAI 端点工具的直接替代。 -2. **Provider abstraction via format translators:** Each AI provider has a translator in `open-sse/translator/` that converts between OpenAI format and the provider's native format transparently. +2. **通过格式转换器抽象服务商：** 每个 AI 服务商在 `open-sse/translator/` 中都有一个转换器，透明地在 OpenAI 格式和该服务商原生格式之间转换。 -3. **Connection-based provider model:** Providers are stored as "connections" in SQLite. Each connection has an `id`, `provider`, `authType` (oauth/apikey/free), `isActive` flag, and credentials. Multiple connections per provider for multi-account rotation. +3. **基于连接的服务商模型：** 服务商以"连接"形式存储在 SQLite 中。每个连接有 `id`、`provider`、`authType`（oauth/apikey/free）、`isActive` 标志和凭证。同一服务商可创建多个连接，用于多账户轮换。 -4. **Combo system for fallback:** Users create "combos" — ordered lists of `provider/model` pairs. The proxy tries each in order until one succeeds. Supports 14 strategies including auto-combo with self-healing and context-relay for session continuity. +4. **Combo 系统实现容灾：** 用户创建"Combo"——即 `服务商/模型` 对的有序列表。代理按顺序尝试每个选项，直到成功。支持 14 种策略，包括带自修复的 Auto-Combo 和用于会话连续性的 Context Relay。 -5. **SSE proxy pipeline:** The proxy pipeline is middleware-based: request → auth resolution → rate limiting → circuit breaker → format translation → upstream call → response translation → SSE streaming back to client. +5. **SSE 代理管线：** 代理管线基于中间件：请求 → 认证解析 → 速率限制 → 熔断器 → 格式转换 → 上游调用 → 响应转换 → SSE 流返回客户端。 -6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys, memory, skills) stored in a single SQLite database via 21 domain-specific modules. All DB operations go through `src/lib/db/` modules, never raw SQL in routes. +6. **SQLite 持久化：** 所有状态（服务商、Combo、日志、设置、API Key、记忆、技能）通过 21 个领域专用模块存储在单一 SQLite 数据库中。所有数据库操作均通过 `src/lib/db/` 模块进行，路由中绝不出现裸 SQL。 -7. **OAuth with PKCE:** OAuth flows use PKCE for security. Token refresh handled by background job (`tokenHealthCheck.ts`). +7. **OAuth + PKCE：** OAuth 流程使用 PKCE 保障安全。Token 刷新由后台任务（`tokenHealthCheck.ts`）处理。 -8. **ProviderIcon component:** Unified icon system using `@lobehub/icons` (130+ SVG) with PNG fallback and generic icon fallback chain. Used on providers, dashboard, and agents pages. +8. **ProviderIcon 组件：** 统一图标系统，使用 `@lobehub/icons`（130+ SVG）+ PNG 降级 + 通用图标降级链。在服务商、仪表盘和代理页面上使用。 -9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in 21 `src/lib/db/` modules with 16 SQL migrations. +9. **数据库架构：** `localDb.ts` 仅为再导出层——真正的逻辑位于 21 个 `src/lib/db/` 模块和 16 个 SQL 迁移中。 -10. **Upstream headers:** Custom headers merged in executors after default auth; same header name replaces executor value. Forbidden header names in `src/shared/constants/upstreamHeaders.ts`. +10. **上游响应头：** 自定义响应头在执行器中合并，位于默认认证之后；相同响应头名称会替换执行器值。禁用的响应头名称定义在 `src/shared/constants/upstreamHeaders.ts`。 -11. **Memory/Skills cross-cutting systems:** Memory and Skills affect the MCP tools, request pipeline, and A2A skills. Memory provides persistent context across sessions; Skills provide extensible tool execution with sandbox isolation. +11. **记忆/技能跨系统：** 记忆和技能影响 MCP 工具、请求管线和 A2A 技能。记忆提供跨会话的持久上下文；技能提供带沙箱隔离的可扩展工具执行。 -12. **Domain policy engine:** `src/domain/` contains policy engine modules (policyEngine, comboResolver, costRules, degradation, fallbackPolicy, lockoutPolicy, modelAvailability, providerExpiration, quotaCache, configAudit) that govern routing decisions independently from the pipeline. +12. **领域策略引擎：** `src/domain/` 包含策略引擎模块（policyEngine、comboResolver、costRules、degradation、fallbackPolicy、lockoutPolicy、modelAvailability、providerExpiration、quotaCache、configAudit），独立于管线管控路由决策。 -13. **Provider constants validated at load:** All provider definitions validated via Zod schemas at module load time (`src/shared/validation/providerSchema.ts`). Invalid providers fail fast. +13. **服务商常量加载时校验：** 所有服务商定义在模块加载时通过 Zod Schema 校验（`src/shared/validation/providerSchema.ts`）。无效的服务商会立刻暴露。 -## Main Flows +## 主要流程 -### Proxy Request Flow -1. Client sends OpenAI-format request to `/v1/chat/completions` -2. API key validation -3. Model resolution: direct model or combo lookup -4. For combos: iterate through models with selected strategy -5. Auth resolution: get credentials for the target provider -6. Format translation: OpenAI → provider native format -7. CLI fingerprint matching (if enabled for provider) -8. Upstream request with circuit breaker and rate limiting -9. Response translation: provider → OpenAI format -10. omniModel tag sanitization (strip internal tags) -11. SSE streaming back to client -12. Memory extraction (if memory system enabled) -13. Usage logging and cost calculation +### 代理请求流程 +1. 客户端向 `/v1/chat/completions` 发送 OpenAI 格式请求 +2. API Key 校验 +3. 模型解析：直接模型查询或 Combo 查询 +4. 对于 Combo：按选定策略遍历模型 +5. 认证解析：获取目标服务商的凭证 +6. 格式转换：OpenAI → 服务商原生格式 +7. CLI 指纹匹配（若对该服务商启用） +8. 上游请求，带熔断器和速率限制 +9. 响应转换：服务商 → OpenAI 格式 +10. omniModel 标签清理（剥离内部标签） +11. SSE 流式返回客户端 +12. 记忆提取（若记忆系统启用） +13. 用量日志记录和成本计算 -### OAuth Flow -1. Dashboard initiates `/api/oauth/[provider]/authorize` -2. User completes OAuth login in browser -3. Callback hits `/api/oauth/[provider]/exchange` -4. Tokens stored as a provider connection in SQLite -5. Background job refreshes tokens before expiry +### OAuth 流程 +1. 仪表盘发起 `/api/oauth/[provider]/authorize` +2. 用户在浏览器中完成 OAuth 登录 +3. 回调命中 `/api/oauth/[provider]/exchange` +4. Token 作为服务商连接存储在 SQLite 中 +5. 后台任务在过期前刷新 Token -## Important Notes for LLMs +## LLM 重要注意事项 -1. **Two model endpoints exist:** `/api/models` (dashboard, all models) and `/v1/models` (OpenAI-compatible, active only). +1. **存在两个模型端点：** `/api/models`（仪表盘，全部模型）和 `/v1/models`（OpenAI 兼容，仅活跃模型）。 -2. **Provider IDs vs aliases:** Providers have both an ID (`claude`, `github`) and a short alias (`cc`, `gh`). Models are referenced as `alias/model-name` (e.g., `cc/claude-opus-4-6`). +2. **服务商 ID 与别名：** 服务商同时有 ID（`claude`、`github`）和短别名（`cc`、`gh`）。模型引用格式为 `alias/model-name`（如 `cc/claude-opus-4-6`）。 -3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, executors, translators, and services. +3. **`open-sse/` 目录是独立的 npm workspace**，拥有自己的配置、处理器、执行器、转换器和服务。 -4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. +4. **环境变量：** 所有配置位于 `.env`（来自 `.env.example`）。关键变量：`PORT`、`NEXT_PUBLIC_BASE_URL`、`API_KEY`、`ADMIN_PASSWORD`。 -5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module. +5. **数据库层：** 操作通过 `src/lib/db/` 模块（45+ 个领域专用文件，55 个迁移）进行。`localDb.ts` 仅做再导出——新增函数请加到正确的 `db/*.ts` 模块。 -6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches. +6. **测试** 使用 Node.js 内置测试运行器 + Vitest。运行 `npm test`。MCP/autoCombo 用 Vitest（`npm run test:vitest`）。E2E 用 Playwright（`npm run test:e2e`）。覆盖率门禁：75% statements/lines/functions，70% branches。 -7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes. +7. **MCP 和 A2A 页面是嵌入到 `/dashboard/endpoint` 内的选项卡**，不是独立路由。 -8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB. +8. **ACP 代理** 位于 `src/lib/acp/registry.ts`，有检测缓存。自定义代理通过设置 DB 存储。 -9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown. +9. **Auto-Combo 引擎** 位于 `open-sse/services/autoCombo/` — **9 因子评分**（health 0.22、quota 0.17、costInv 0.17、latencyInv 0.13、taskFit 0.08、specificityMatch 0.08、stability 0.05、tierPriority 0.05、tierAffinity 0.05），4 种模式包，bandit 探索，渐进式冷却。 -10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130). +10. **Docker：** Dockerfile 有两个目标：`runner-base` 和 `runner-cli`。`docker-compose.yml` 用于开发（3 个 profile），`docker-compose.prod.yml` 用于生产（端口 20130）。 -11. **Electron desktop app** in `electron/` with main.js and preload.js. Build with `npm run electron:build` (supports Windows, macOS, Linux). +11. **Electron 桌面应用** 位于 `electron/`，含 main.js 和 preload.js。通过 `npm run electron:build` 构建（支持 Windows、macOS、Linux）。 -12. **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`. Use `sync_pricing` MCP tool or API endpoint. +12. **定价数据** 从 LiteLLM 同步至 `src/lib/pricingSync.ts`。使用 `sync_pricing` MCP 工具或 API 端点。 -13. **Memory system** in `src/lib/memory/` provides extraction, injection, retrieval, summarization, and persistent store. Exposed via MCP memory tools and `/api/memory/ API. +13. **记忆系统** 位于 `src/lib/memory/`，提供提取、注入、检索、摘要和持久存储。通过 MCP 记忆工具和 `/api/memory/` API 对外暴露。 -14. **Skills system** in `src/lib/skills/` provides registry, executor, sandbox isolation, built-in skills, custom skill support, request interception, and context injection. Exposed via MCP skill tools and `/api/skills/` API. +14. **技能系统** 位于 `src/lib/skills/`，提供注册表、执行器、沙箱隔离、内置技能、自定义技能支持、请求拦截和上下文注入。通过 MCP 技能工具和 `/api/skills/` API 对外暴露。 -15. **Zod v4** is used for all validation. Import from `zod` package. Provider schemas validated at module load time. +15. **所有校验使用 Zod v4**。从 `zod` 包导入。服务商 Schema 在模块加载时校验。 -16. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated after a successful turn; `chat.ts` injects the handoff only after account resolution. Handoff data lives in `context_handoffs` SQLite table. Config: `handoffThreshold`, `handoffModel`, `handoffProviders`. +16. **Context Relay 策略**（`context-relay`）分两层实现：`combo.ts` 决定在成功轮次后是否生成交接；`chat.ts` 在账户解析后才注入交接信息。交接数据存储在 `context_handoffs` SQLite 表中。配置项：`handoffThreshold`、`handoffModel`、`handoffProviders`。 -17. **Proxy enforcement** is now comprehensive: token health checks resolve proxy per connection, provider validation wraps in `runWithProxyContext`, and proxy dispatchers use `undici.fetch()` instead of the Node built-in `fetch()` to avoid dispatcher incompatibilities on Node 22. +17. **代理强制全面覆盖**：Token 健康检查按连接解析代理，服务商校验在 `runWithProxyContext` 中包装，代理分发器使用 `undici.fetch()` 而非 Node 内置 `fetch()` 以避免 Node 22 上的分发器不兼容问题。 -18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false. +18. **Node.js 24+ 兼容性**：登录页面（`/api/settings/require-login`）检测 Node.js 版本，发送 `nodeVersion`/`nodeCompatible` 字段。当 `nodeCompatible` 为 false 时，登录 UI 渲染警告横幅。 -19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth. +19. **云代理** 位于 `src/lib/cloudAgent/` — 三个外部自主编程代理（Codex Cloud、Devin、Jules），任务生命周期端点位于 `/api/v1/agents/tasks/`。须使用管理认证，而非客户端认证。 -20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header. +20. **安全护栏框架** 位于 `src/lib/guardrails/` — 热重载注册表。内置（按优先级）：`vision-bridge`（5）→ `pii-masker`（10）→ `prompt-injection`（20）。Fail-open 模式：异常绝不阻塞流量。可通过 `x-omniroute-disabled-guardrails` 头进行逐请求关闭。 -21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/architecture/AUTHZ_GUIDE.md`. +21. **授权管线**（`src/server/authz/`）：每个请求被分类为 `PUBLIC`、`CLIENT_API` 或 `MANAGEMENT`，然后经过策略 + 强制执行阶段。见 `docs/architecture/AUTHZ_GUIDE.md`。 -22. **Three resilience layers** are distinct (do not conflate them): - - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope. - - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope. - - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope. +22. **三种容灾层各司其职**（请勿混淆）： + - **服务商熔断器**（`src/shared/utils/circuitBreaker.ts`）— 整个服务商范围。 + - **连接冷却**（`src/sse/services/auth.ts::markAccountUnavailable`）— 单个密钥/账户范围。 + - **模型锁定**（`open-sse/services/accountFallback.ts`）— 服务商 + 连接 + 模型范围。 -## v3.8.0 Highlights +## v3.8.0 亮点 -- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement -- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection -- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions) -- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest -- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report -- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes -- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo -- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82% -- **Reasoning replay** (`docs/routing/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams -- **Compliance + Evals + Webhooks** documentation introduced -- **Stealth guide** (`docs/security/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration -- **Tunnels guide** (`docs/ops/TUNNELS_GUIDE.md`) — Cloudflare tunnel management -- **Electron guide** (`docs/guides/ELECTRON_GUIDE.md`) — desktop app build + signing +- **云代理**（Codex Cloud、Devin、Jules），带任务生命周期管理和管理认证强制 +- **安全护栏框架**：热重载注册表，含 vision-bridge、pii-masker、prompt-injection +- **9 因子 Auto-Combo 评分**（早期版本为 6 因子） +- **`reset-aware` 路由策略**（第 14 种）— 选择配额即将重置的账户 +- **A2A 协议扩展至 5 个技能**：smart-routing、quota-management、provider-discovery、cost-analysis、health-report +- **MCP Server 扩展至 37 个工具**（30 个基础 + 3 个记忆 + 4 个技能），约 13 个权限域 +- **OAuth 服务商扩展至 14 个**：新增 Qwen、Kiro、Qoder、Gemini、Windsurf、GitLab Duo +- **覆盖率门禁提升至 75/75/75/70**（此前为全面 60%）— 实测约 82% +- **推理回放**（`docs/routing/REASONING_REPLAY.md`）— 捕获和检查服务商推理流 +- **合规 + 评估 + Webhook** 文档引入 +- **隐身指南**（`docs/security/STEALTH_GUIDE.md`）— TLS / CLI 指纹配置 +- **隧道指南**（`docs/ops/TUNNELS_GUIDE.md`）— Cloudflare 隧道管理 +- **Electron 指南**（`docs/guides/ELECTRON_GUIDE.md`）— 桌面应用构建 + 签名 -## Links +## 链接 -- Repository: https://github.com/diegosouzapw/OmniRoute -- Website: https://omniroute.online -- npm: https://www.npmjs.com/package/omniroute -- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute -- Documentation: See `/docs/` directory +- 仓库：https://github.com/diegosouzapw/OmniRoute +- 网站：https://omniroute.online +- npm：https://www.npmjs.com/package/omniroute +- Docker Hub：https://hub.docker.com/r/diegosouzapw/omniroute +- 文档：参见 `/docs/` 目录 -### Documentation Index +### 文档索引 -- **Architecture & Reference**: `docs/architecture/ARCHITECTURE.md`, `docs/architecture/CODEBASE_DOCUMENTATION.md`, `docs/architecture/REPOSITORY_MAP.md`, `docs/reference/API_REFERENCE.md`, `docs/reference/PROVIDER_REFERENCE.md`, `docs/reference/openapi.yaml` -- **Operator guides**: `docs/guides/USER_GUIDE.md`, `docs/reference/CLI-TOOLS.md`, `docs/guides/TROUBLESHOOTING.md`, `docs/ops/COVERAGE_PLAN.md` -- **Protocols**: `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`, `docs/frameworks/CLOUD_AGENT.md` -- **Routing & resilience**: `docs/routing/AUTO-COMBO.md`, `docs/architecture/RESILIENCE_GUIDE.md` -- **Security**: `docs/architecture/AUTHZ_GUIDE.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/security/STEALTH_GUIDE.md` -- **Extensibility**: `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md` -- **Platform**: `docs/guides/ELECTRON_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md` -- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` +- **架构与参考**：`docs/architecture/ARCHITECTURE.md`、`docs/architecture/CODEBASE_DOCUMENTATION.md`、`docs/architecture/REPOSITORY_MAP.md`、`docs/reference/API_REFERENCE.md`、`docs/reference/PROVIDER_REFERENCE.md`、`docs/reference/openapi.yaml` +- **运维指南**：`docs/guides/USER_GUIDE.md`、`docs/reference/CLI-TOOLS.md`、`docs/guides/TROUBLESHOOTING.md`、`docs/ops/COVERAGE_PLAN.md` +- **协议**：`docs/frameworks/MCP-SERVER.md`、`docs/frameworks/A2A-SERVER.md`、`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`、`docs/frameworks/CLOUD_AGENT.md` +- **路由与容灾**：`docs/routing/AUTO-COMBO.md`、`docs/architecture/RESILIENCE_GUIDE.md` +- **安全**：`docs/architecture/AUTHZ_GUIDE.md`、`docs/security/GUARDRAILS.md`、`docs/security/COMPLIANCE.md`、`docs/security/STEALTH_GUIDE.md` +- **扩展性**：`docs/frameworks/SKILLS.md`、`docs/frameworks/MEMORY.md`、`docs/frameworks/EVALS.md`、`docs/frameworks/WEBHOOKS.md`、`docs/routing/REASONING_REPLAY.md` +- **平台**：`docs/guides/ELECTRON_GUIDE.md`、`docs/ops/TUNNELS_GUIDE.md` +- **AI 代理**：`CLAUDE.md`、`AGENTS.md`、`GEMINI.md` From 806cea8e5e34fde9988cff79ea95468bbf7b740a Mon Sep 17 00:00:00 2001 From: DevinZeng Date: Fri, 3 Jul 2026 11:41:52 +0800 Subject: [PATCH 2/4] i18n(zh-CN): translate CHANGELOG entries and section headings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Translate feature/fix entries across 3.8.0–3.8.42 releases - Translate section headings (Features, Fixes, Security, etc.) - Fix docs-sync check: use line count instead of byte size for CHANGELOG i18n validation (CJK translations compress 30-50%) - Sync llm.txt zh-CN mirror body to match root --- docs/i18n/zh-CN/CHANGELOG.md | 10382 ++++++++++++++-------------- docs/i18n/zh-CN/llm.txt | 858 +-- scripts/check/check-docs-sync.mjs | 11 +- 3 files changed, 5619 insertions(+), 5632 deletions(-) diff --git a/docs/i18n/zh-CN/CHANGELOG.md b/docs/i18n/zh-CN/CHANGELOG.md index fb9f7c4a5387..0c0c8c0da4b3 100644 --- a/docs/i18n/zh-CN/CHANGELOG.md +++ b/docs/i18n/zh-CN/CHANGELOG.md @@ -92,9 +92,9 @@ - **deps:** 将开发依赖组升级，共 9 项更新。([#5415](https://github.com/diegosouzapw/OmniRoute/pull/5415)) -- **maintenance (dead-code):** repo-wide sweep of unused exported symbols, types, and schemas — removes 35 no-longer-referenced exports across cloud-agent, a2a, SSE, memory, quota, skills, gamification, codex, qdrant, playground, provider catalog, and combo modules, reducing the exported API surface and eliminating stale misleading types. ([#5372](https://github.com/diegosouzapw/OmniRoute/pull/5372), [#5373](https://github.com/diegosouzapw/OmniRoute/pull/5373), [#5374](https://github.com/diegosouzapw/OmniRoute/pull/5374), [#5375](https://github.com/diegosouzapw/OmniRoute/pull/5375), [#5376](https://github.com/diegosouzapw/OmniRoute/pull/5376), [#5377](https://github.com/diegosouzapw/OmniRoute/pull/5377), [#5378](https://github.com/diegosouzapw/OmniRoute/pull/5378), [#5380](https://github.com/diegosouzapw/OmniRoute/pull/5380), [#5381](https://github.com/diegosouzapw/OmniRoute/pull/5381), [#5382](https://github.com/diegosouzapw/OmniRoute/pull/5382), [#5383](https://github.com/diegosouzapw/OmniRoute/pull/5383), [#5384](https://github.com/diegosouzapw/OmniRoute/pull/5384), [#5385](https://github.com/diegosouzapw/OmniRoute/pull/5385), [#5386](https://github.com/diegosouzapw/OmniRoute/pull/5386), [#5387](https://github.com/diegosouzapw/OmniRoute/pull/5387), [#5388](https://github.com/diegosouzapw/OmniRoute/pull/5388), [#5389](https://github.com/diegosouzapw/OmniRoute/pull/5389), [#5390](https://github.com/diegosouzapw/OmniRoute/pull/5390), [#5391](https://github.com/diegosouzapw/OmniRoute/pull/5391), [#5392](https://github.com/diegosouzapw/OmniRoute/pull/5392), [#5393](https://github.com/diegosouzapw/OmniRoute/pull/5393), [#5395](https://github.com/diegosouzapw/OmniRoute/pull/5395), [#5396](https://github.com/diegosouzapw/OmniRoute/pull/5396), [#5397](https://github.com/diegosouzapw/OmniRoute/pull/5397), [#5398](https://github.com/diegosouzapw/OmniRoute/pull/5398), [#5399](https://github.com/diegosouzapw/OmniRoute/pull/5399), [#5400](https://github.com/diegosouzapw/OmniRoute/pull/5400), [#5401](https://github.com/diegosouzapw/OmniRoute/pull/5401), [#5402](https://github.com/diegosouzapw/OmniRoute/pull/5402), [#5403](https://github.com/diegosouzapw/OmniRoute/pull/5403), [#5404](https://github.com/diegosouzapw/OmniRoute/pull/5404), [#5463](https://github.com/diegosouzapw/OmniRoute/pull/5463), [#5464](https://github.com/diegosouzapw/OmniRoute/pull/5464), [#5466](https://github.com/diegosouzapw/OmniRoute/pull/5466), [#5468](https://github.com/diegosouzapw/OmniRoute/pull/5468) — thanks @JxnLexn) +- **maintenance (dead-code):** 全仓库清理未使用的导出符号、类型和 Schema — 移除了 cloud-agent、a2a、SSE、memory、quota、skills、gamification、codex、qdrant、playground、服务商目录和 Combo 模块中 35 个不再被引用的导出，减少了导出 API 面并消除了过时误导性类型。([#5372](https://github.com/diegosouzapw/OmniRoute/pull/5372), [#5373](https://github.com/diegosouzapw/OmniRoute/pull/5373), [#5374](https://github.com/diegosouzapw/OmniRoute/pull/5374), [#5375](https://github.com/diegosouzapw/OmniRoute/pull/5375), [#5376](https://github.com/diegosouzapw/OmniRoute/pull/5376), [#5377](https://github.com/diegosouzapw/OmniRoute/pull/5377), [#5378](https://github.com/diegosouzapw/OmniRoute/pull/5378), [#5380](https://github.com/diegosouzapw/OmniRoute/pull/5380), [#5381](https://github.com/diegosouzapw/OmniRoute/pull/5381), [#5382](https://github.com/diegosouzapw/OmniRoute/pull/5382), [#5383](https://github.com/diegosouzapw/OmniRoute/pull/5383), [#5384](https://github.com/diegosouzapw/OmniRoute/pull/5384), [#5385](https://github.com/diegosouzapw/OmniRoute/pull/5385), [#5386](https://github.com/diegosouzapw/OmniRoute/pull/5386), [#5387](https://github.com/diegosouzapw/OmniRoute/pull/5387), [#5388](https://github.com/diegosouzapw/OmniRoute/pull/5388), [#5389](https://github.com/diegosouzapw/OmniRoute/pull/5389), [#5390](https://github.com/diegosouzapw/OmniRoute/pull/5390), [#5391](https://github.com/diegosouzapw/OmniRoute/pull/5391), [#5392](https://github.com/diegosouzapw/OmniRoute/pull/5392), [#5393](https://github.com/diegosouzapw/OmniRoute/pull/5393), [#5395](https://github.com/diegosouzapw/OmniRoute/pull/5395), [#5396](https://github.com/diegosouzapw/OmniRoute/pull/5396), [#5397](https://github.com/diegosouzapw/OmniRoute/pull/5397), [#5398](https://github.com/diegosouzapw/OmniRoute/pull/5398), [#5399](https://github.com/diegosouzapw/OmniRoute/pull/5399), [#5400](https://github.com/diegosouzapw/OmniRoute/pull/5400) — 感谢 @JxnLexn) -- **maintenance (DRY):** DRY consolidation of shared helpers — extracts 17 duplicated utilities into single shared modules: vscode metadata helpers, proxy route handlers, auth zip extractors, combo-builder model options, vscode tokenized-request helpers, quota strategy ranking helpers, recharts donut card, provider-specific validation, batch response formatter, Redis runtime helpers, version-manager request parsing, media-generation route helpers, service install helpers, settings transform schemas, relay stream finalizer, machine-id fallback, and node SQLite adapter. ([#5471](https://github.com/diegosouzapw/OmniRoute/pull/5471), [#5472](https://github.com/diegosouzapw/OmniRoute/pull/5472), [#5475](https://github.com/diegosouzapw/OmniRoute/pull/5475), [#5477](https://github.com/diegosouzapw/OmniRoute/pull/5477), [#5479](https://github.com/diegosouzapw/OmniRoute/pull/5479), [#5482](https://github.com/diegosouzapw/OmniRoute/pull/5482), [#5484](https://github.com/diegosouzapw/OmniRoute/pull/5484), [#5485](https://github.com/diegosouzapw/OmniRoute/pull/5485), [#5488](https://github.com/diegosouzapw/OmniRoute/pull/5488), [#5490](https://github.com/diegosouzapw/OmniRoute/pull/5490), [#5492](https://github.com/diegosouzapw/OmniRoute/pull/5492), [#5493](https://github.com/diegosouzapw/OmniRoute/pull/5493), [#5495](https://github.com/diegosouzapw/OmniRoute/pull/5495), [#5496](https://github.com/diegosouzapw/OmniRoute/pull/5496), [#5497](https://github.com/diegosouzapw/OmniRoute/pull/5497), [#5498](https://github.com/diegosouzapw/OmniRoute/pull/5498), [#5500](https://github.com/diegosouzapw/OmniRoute/pull/5500) — thanks @JxnLexn) +- **maintenance (DRY):** 共享辅助函数的 DRY 整合 — 将 17 个重复的工具函数提取到单一共享模块中：vscode 元数据辅助函数、代理路由处理器、auth zip 提取器、Combo 构建器模型选项、vscode Token 化请求辅助函数、配额策略排序辅助函数、recharts 环形图卡片、服务商特定校验、批次响应格式化器、Redis 运行时辅助函数、版本管理器请求解析、媒体生成路由辅助函数、服务安装辅助函数、设置转换 Schema、中继流终结器、machine-id 回退和 node SQLite 适配器。([#5471](https://github.com/diegosouzapw/OmniRoute/pull/5471), [#5472](https://github.com/diegosouzapw/OmniRoute/pull/5472), [#5475](https://github.com/diegosouzapw/OmniRoute/pull/5475), [#5477](https://github.com/diegosouzapw/OmniRoute/pull/5477), [#5479](https://github.com/diegosouzapw/OmniRoute/pull/5479), [#5482](https://github.com/diegosouzapw/OmniRoute/pull/5482), [#5484](https://github.com/diegosouzapw/OmniRoute/pull/5484), [#5485](https://github.com/diegosouzapw/OmniRoute/pull/5485), [#5488](https://github.com/diegosouzapw/OmniRoute/pull/5488), [#5490](https://github.com/diegosouzapw/OmniRoute/pull/5490), [#5492](https://github.com/diegosouzapw/OmniRoute/pull/5492), [#5493](https://github.com/diegosouzapw/OmniRoute/pull/5493), [#5495](https://github.com/diegosouzapw/OmniRoute/pull/5495), [#5496](https://github.com/diegosouzapw/OmniRoute/pull/5496), [#5497](https://github.com/diegosouzapw/OmniRoute/pull/5497), [#5498](https://github.com/diegosouzapw/OmniRoute/pull/5498), [#5500](https://github.com/diegosouzapw/OmniRoute/pull/5500) — 感谢 @JxnLexn) --- @@ -126,7 +126,7 @@ ### 📝 维护 -- **chore(dead-code):** repo-wide sweep of unused exported symbols and a matching dead-code baseline ratchet — trimmed unused exported helpers, validation/settings/encryption-config schemas, utility/domain/static-constant/formatting helpers, runtime test helpers, the request-timeout fetch wrapper, event-bus, semantic-cache (maintenance + expiry), correlation-middleware, MCP-scope, service-registry, build-profile, api-key-format, authz-class, models.dev-context, embedding-cache, provider-limits-scheduler, search-validator, webhook-example, agent-skills-repo-URL and command-code-auth-cleanup exports. Pure dead-code removal validated by `typecheck:core` (no remaining referencing site) — no behavior change. ([#5321](https://github.com/diegosouzapw/OmniRoute/pull/5321), [#5322](https://github.com/diegosouzapw/OmniRoute/pull/5322), [#5324](https://github.com/diegosouzapw/OmniRoute/pull/5324), [#5325](https://github.com/diegosouzapw/OmniRoute/pull/5325), [#5328](https://github.com/diegosouzapw/OmniRoute/pull/5328), [#5329](https://github.com/diegosouzapw/OmniRoute/pull/5329), [#5330](https://github.com/diegosouzapw/OmniRoute/pull/5330), [#5331](https://github.com/diegosouzapw/OmniRoute/pull/5331), [#5333](https://github.com/diegosouzapw/OmniRoute/pull/5333), [#5334](https://github.com/diegosouzapw/OmniRoute/pull/5334), [#5335](https://github.com/diegosouzapw/OmniRoute/pull/5335), [#5336](https://github.com/diegosouzapw/OmniRoute/pull/5336), [#5338](https://github.com/diegosouzapw/OmniRoute/pull/5338), [#5339](https://github.com/diegosouzapw/OmniRoute/pull/5339), [#5353](https://github.com/diegosouzapw/OmniRoute/pull/5353), [#5354](https://github.com/diegosouzapw/OmniRoute/pull/5354), [#5355](https://github.com/diegosouzapw/OmniRoute/pull/5355), [#5356](https://github.com/diegosouzapw/OmniRoute/pull/5356), [#5357](https://github.com/diegosouzapw/OmniRoute/pull/5357), [#5359](https://github.com/diegosouzapw/OmniRoute/pull/5359), [#5362](https://github.com/diegosouzapw/OmniRoute/pull/5362), [#5364](https://github.com/diegosouzapw/OmniRoute/pull/5364), [#5365](https://github.com/diegosouzapw/OmniRoute/pull/5365), [#5366](https://github.com/diegosouzapw/OmniRoute/pull/5366), [#5368](https://github.com/diegosouzapw/OmniRoute/pull/5368), [#5369](https://github.com/diegosouzapw/OmniRoute/pull/5369), [#5371](https://github.com/diegosouzapw/OmniRoute/pull/5371) — thanks @JxnLexn) +- **chore(dead-code):** 全仓库清理未使用的导出符号，并设置对应的死代码基线递增门禁 — 修剪了未使用的导出辅助函数、校验/设置/加密配置 Schema、工具/domain/静态常量/格式化辅助函数、运行时测试辅助函数、请求超时 fetch 包装器、event-bus、semantic-cache（维护 + 过期）、correlation-middleware、MCP-scope、service-registry、build-profile、api-key-format、authz-class、models.dev-context、embedding-cache、provider-limits-scheduler、search-validator、webhook-example、agent-skills-repo-URL 和 command-code-auth-cleanup 导出。纯死代码移除，由 `typecheck:core` 验证（无剩余引用点）——无行为变更。([#5321](https://github.com/diegosouzapw/OmniRoute/pull/5321), [#5322](https://github.com/diegosouzapw/OmniRoute/pull/5322), [#5324](https://github.com/diegosouzapw/OmniRoute/pull/5324), [#5325](https://github.com/diegosouzapw/OmniRoute/pull/5325), [#5328](https://github.com/diegosouzapw/OmniRoute/pull/5328), [#5329](https://github.com/diegosouzapw/OmniRoute/pull/5329), [#5330](https://github.com/diegosouzapw/OmniRoute/pull/5330), [#5331](https://github.com/diegosouzapw/OmniRoute/pull/5331), [#5333](https://github.com/diegosouzapw/OmniRoute/pull/5333), [#5334](https://github.com/diegosouzapw/OmniRoute/pull/5334), [#5335](https://github.com/diegosouzapw/OmniRoute/pull/5335), [#5336](https://github.com/diegosouzapw/OmniRoute/pull/5336), [#5338](https://github.com/diegosouzapw/OmniRoute/pull/5338), [#5339](https://github.com/diegosouzapw/OmniRoute/pull/5339), [#5353](https://github.com/diegosouzapw/OmniRoute/pull/5353), [#5354](https://github.com/diegosouzapw/OmniRoute/pull/5354), [#5355](https://github.com/diegosouzapw/OmniRoute/pull/5355), [#5356](https://github.com/diegosouzapw/OmniRoute/pull/5356), [#5357](https://github.com/diegosouzapw/OmniRoute/pull/5357), [#5359](https://github.com/diegosouzapw/OmniRoute/pull/5359), [#5362](https://github.com/diegosouzapw/OmniRoute/pull/5362) — 感谢 @JxnLexn / @diegosouzapw) --- @@ -160,32 +160,32 @@ _In development — bullets added per PR; finalized at release._ - **fix(translator): 在非流式 malformed-200 防护中接受 Claude Messages 格式** — 当 Claude 客户端路由到非 Claude 服务商时，翻译后的响应体为 Claude Messages 格式，防护层未识别该格式而返回 502。现在可识别 text/tool_use/thinking 块。([#5156](https://github.com/diegosouzapw/OmniRoute/pull/5156) — 感谢 @NomenAK) - **fix(sse): 通过参数 schema 匹配解析无名称的 deepseek-web `` 块** — 当 `chat.deepseek.com` 发出无名称 `` 块时，基于 schema 的退路方案将提取的参数名与各工具 schema 键进行比较以匹配名称。([#5154](https://github.com/diegosouzapw/OmniRoute/issues/5154)) - **fix(stream): 将服务商安全 finish_reason 规范化为 `content_filter`** — Gemini/Antigravity 可返回 SAFETY/RECITATION/BLOCKLIST 等，不再被下游识别。现在统一映射为标准 `content_filter`。([#5197](https://github.com/diegosouzapw/OmniRoute/pull/5197) — 感谢 @rdself) -- **fix(responses): normalize non-array Responses API `input` before routing** — the OpenAI Responses API accepts `input` as a string, object, or list, but OmniRoute only handled list-shaped payloads; a string or object `input` was silently dropped on the Responses→Chat Completions path. The translator now normalizes `input` to a list before dispatch; the Codex-native Responses path also normalizes before forwarding (preventing upstream `400 Input must be a list`); and the prompt-injection and PII sanitizer extraction paths are guarded against object-valued `input` so security checks do not throw. ([#5204](https://github.com/diegosouzapw/OmniRoute/pull/5204) — thanks @wilsonicdev) -- **fix(zenmux): normalize vendor-prefixed GLM system roles for Z.AI models** — ZenMux exposes Z.AI GLM via vendor-prefixed OpenAI-compatible IDs such as `z-ai/glm-5.2`. The existing GLM detection only matched bare `glm-*`/`glm` ids, so `zenmux/z-ai/glm-5.2` kept system messages in place; Z.AI rejects compressed histories ending with a system turn before `assistant(tool_calls) → tool` sequences. The fix extends GLM detection to cover `z-ai/glm-*` prefixes and routes them through the existing `normalizeSystemRole` path. ([#5158](https://github.com/diegosouzapw/OmniRoute/pull/5158) — thanks @Thinkscape) -- **fix(xai): add OAuth connection test probe + normalize xAI reasoning effort aliases** — xAI rejects unsupported reasoning effort values (`max`, `xhigh`) with HTTP 400 after a provider update; the xAI translator now maps `max` and `xhigh` to `high` before forwarding. Additionally, xAI OAuth connections had no dashboard test configuration, so provider tests returned `"Provider test not supported"`; a dedicated OAuth test probe is now wired for xAI accounts with regression coverage for the effort normalization. ([#5157](https://github.com/diegosouzapw/OmniRoute/pull/5157) — thanks @nguyenxvotanminh3) -- **fix(serve): honour `HOSTNAME` from `.env` instead of hardcoding `0.0.0.0`** — `bin/cli/commands/serve.mjs` spread `process.env` into the child-process environment but immediately overwrote `HOSTNAME` with a literal `"0.0.0.0"`, silently discarding any user-configured bind address even though `HOSTNAME` is documented in `.env.example` and `docs/reference/ENVIRONMENT.md`. `dist/server.js` already read `process.env.HOSTNAME` correctly; only the CLI wrapper was overriding it. The fix applies `process.env.HOSTNAME || "0.0.0.0"` so the env value takes effect. ([#5134](https://github.com/diegosouzapw/OmniRoute/issues/5134), [#5170](https://github.com/diegosouzapw/OmniRoute/pull/5170) — thanks @anki1kr / @Angelo90810) -- **fix(cli): force `NODE_ENV` to match dev/start run mode in the custom Next server** — when `.env.example` ships `NODE_ENV=production`, starting `npm run dev` via `scripts/dev/run-next.mjs` forwarded that value to the programmatic `next()` entry, which — unlike the `next` CLI — does not normalize it to match the run mode. The resulting production flag caused PostCSS to skip Tailwind's CSS transform, surfacing as `Module parse failed: Unexpected character '@'` on `globals.css`. The custom server now explicitly forces `NODE_ENV=development` for the `dev` path and `NODE_ENV=production` for the `start` path regardless of `.env`. ([#5189](https://github.com/diegosouzapw/OmniRoute/pull/5189) — thanks @backryun) -- **fix(cli): raise dev server Node heap limit to 8 GB to prevent OOM** — `npm run dev` crashed with `FATAL ERROR: Ineffective mark-compacts near heap limit — Allocation failed - JavaScript heap out of memory` while compiling heavy dashboard routes because `node scripts/dev/run-next.mjs` ran on V8's ~4 GB default with no `--max-old-space-size` flag. The `dev` npm script now passes `--max-old-space-size=8192` at invocation time (the only point where this flag can be set for that process). ([#5198](https://github.com/diegosouzapw/OmniRoute/pull/5198) — thanks @backryun) -- **fix(cli): re-enable Turbopack as the default `npm run dev` bundler** — PR #4092 forced webpack because an earlier Turbopack 16.2.x panic (`internal error: entered unreachable code: there must be a path to a root` in `turbopack-core/module_graph`) blocked the OmniRoute module graph. That panic no longer reproduces on the pinned Next 16.2.9, so `OMNIROUTE_USE_TURBOPACK` is flipped from `0` to `1` in `.env.example`, aligning it with `docs/reference/ENVIRONMENT.md` which had already documented the default as `1`. ([#5206](https://github.com/diegosouzapw/OmniRoute/pull/5206) — thanks @backryun) -- **fix(auth): allow synthetic no-auth fallback for mimocode** — mimocode connections without explicit credentials were blocked before reaching the executor. The auth layer now permits a synthetic no-auth fallback for the mimocode provider so credential-free access patterns work as intended. ([#5205](https://github.com/diegosouzapw/OmniRoute/pull/5205) — thanks @KooshaPari) -- **fix(combo): reject empty Responses API `output: []` as a fail-over trigger** — a non-streaming Responses API body with `object: "response"` and `output: []` was accepted as a valid HTTP 200 by the combo response-quality validator, allowing a combo target to stop rather than fail over to the next leg. The non-stream validator now inspects Responses-API-shaped bodies before the generic `output` shortcut and rejects an empty `output: []` as `empty_choices`; structural non-empty output (e.g. `function_call`) remains valid. ([#5207](https://github.com/diegosouzapw/OmniRoute/pull/5207) — thanks @KooshaPari) -- **fix(proxy): close cached dispatchers when clearing the proxy cache** — cached proxy and direct-retry dispatchers were not closed on cache clear, leaking open connection handles. The cache-clear path now calls `close()` on all evicted dispatchers; dispatcher cache and lifecycle helpers have been extracted from the oversized proxy-dispatcher module into a dedicated helper for reuse. ([#5202](https://github.com/diegosouzapw/OmniRoute/pull/5202) — thanks @KooshaPari) -- **fix(proxy): coalesce concurrent fast-fail health probes per proxy URL** — under high concurrency each simultaneous request opened its own TCP health probe for the same proxy URL, creating a thundering-herd burst. Concurrent proxy fast-fail checks are now coalesced so only one TCP probe runs per proxy URL at a time; the completed-result health cache is preserved so subsequent same-URL checks return immediately. ([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109), [#5208](https://github.com/diegosouzapw/OmniRoute/pull/5208) — thanks @KooshaPari) -- **fix(pwa): prefer cached navigation before showing the offline page** — the service worker was too eager to display `/offline` on transient navigation failures. It now caches successful navigation responses and consults the cached route or app shell before falling back to `/offline`; `/offline` remains the final fallback when no cached navigation or app shell exists. ([#5165](https://github.com/diegosouzapw/OmniRoute/issues/5165), [#5209](https://github.com/diegosouzapw/OmniRoute/pull/5209) — thanks @KooshaPari) -- **fix(request-logger): never render a negative percentage in the compression badge** — when every prompt token was compressed (`totalIn = 0, compressed > 0`), the compression pill displayed `(-100%)` because the badge format hard-coded a leading `-` before the percentage value. The badge now omits the negative sign in this case, correctly representing the saving as a positive ratio. ([#5201](https://github.com/diegosouzapw/OmniRoute/pull/5201) — thanks @KooshaPari) -- **fix(dashboard): use amber for home update-step warning icon** — the warning-state icon in the home update steps (`HomePageClient.tsx`) used `text-yellow-500` (Tailwind `#eab308`), which has poor contrast on light backgrounds (~1.9:1, below WCAG AA) and is inconsistent with the `amber` warning convention used by every sibling element in the same component. Switched to `text-amber-500` — a one-line `className` change with no behavior change. ([#5176](https://github.com/diegosouzapw/OmniRoute/pull/5176)) +- **fix(responses): 在路由前规范化非数组 Responses API `input`** — OpenAI Responses API 接受 `input` 为字符串、对象或列表，但 OmniRoute 仅处理列表形式的载荷；字符串或对象 `input` 在 Responses→Chat Completions 路径上被静默丢弃。翻译器现在在调度前将 `input` 规范化为列表；Codex 原生 Responses 路径在转发前也进行规范化（防止上游 `400 Input must be a list`）；并且提示注入和 PII 脱敏提取路径对对象值 `input` 进行了防护，使安全检查不会抛出异常。([#5204](https://github.com/diegosouzapw/OmniRoute/pull/5204) — 感谢 @wilsonicdev) +- **fix(zenmux): 规范化 Z.AI 模型的服务商前缀 GLM 系统角色** — ZenMux 通过服务商前缀的 OpenAI 兼容 ID（如 `z-ai/glm-5.2`）暴露 Z.AI GLM。现有的 GLM 检测仅匹配裸 `glm-*`/`glm` ID，因此 `zenmux/z-ai/glm-5.2` 保持了系统消息不变；而 Z.AI 会拒绝以系统轮次结束的压缩历史（在 `assistant(tool_calls) → tool` 序列之前）。修复扩展了 GLM 检测以覆盖 `z-ai/glm-*` 前缀，并将其路由到现有的 `normalizeSystemRole` 路径。([#5158](https://github.com/diegosouzapw/OmniRoute/pull/5158) — 感谢 @Thinkscape) +- **fix(xai): 添加 OAuth 连接测试探针 + 规范化 xAI 推理强度别名** — xAI 在服务商更新后对不支持的推理强度值（`max`、`xhigh`）返回 HTTP 400；xAI 翻译器现在在转发前将 `max` 和 `xhigh` 映射为 `high`。此外，xAI OAuth 连接缺少仪表盘测试配置，导致服务商测试返回 `"Provider test not supported"`；现在为 xAI 账户配置了专用的 OAuth 测试探针，并对强度规范化进行了回归覆盖。([#5157](https://github.com/diegosouzapw/OmniRoute/pull/5157) — 感谢 @nguyenxvotanminh3) +- **fix(serve): honour `HOSTNAME` from `.env` instead of hardcoding `0.0.0.0`** — `bin/cli/commands/serve.mjs` spread `process.env` into the child-process environment but immediately overwrote `HOSTNAME` with a literal `"0.0.0.0"`, silently discarding any user-configured bind address even though `HOSTNAME` is documented in `.env.example` and `docs/reference/ENVIRONMENT.md`. `dist/server.js` already read `process.env.HOSTNAME` correctly; only the CLI wrapper was overriding it. The fix applies `process.env.HOSTNAME || "0.0.0.0"` so the env value takes effect. ([#5134](https://github.com/diegosouzapw/OmniRoute/issues/5134), [#5170](https://github.com/diegosouzapw/OmniRoute/pull/5170) — 感谢 @anki1kr / @Angelo90810) +- **fix(cli): 强制 `NODE_ENV` 匹配自定义 Next 服务器中的 dev/start 运行模式** — 当 `.env.example` 设置 `NODE_ENV=production` 时，通过 `scripts/dev/run-next.mjs` 启动 `npm run dev` 会将该值转发给编程式 `next()` 入口，而该入口——为 `next` CLI 不同——不会将其规范化为匹配运行模式。由此产生的 production 标志导致 PostCSS 跳过 Tailwind 的 CSS 转换，在 `globals.css` 上表现为 `Module parse failed: Unexpected character @ sign`。自定义服务器现在显式强制 `dev` 路径使用 `NODE_ENV=development`，`start` 路径使用 `NODE_ENV=production`，忽略 `.env`。([#5189](https://github.com/diegosouzapw/OmniRoute/pull/5189) — 感谢 @backryun) +- **fix(cli): 将开发服务器 Node 堆内存限制提升至 8 GB 以防止 OOM** — `npm run dev` 在编译重型仪表盘路由时因 `node scripts/dev/run-next.mjs` 使用 V8 默认的约 4 GB 堆内存（无 `--max-old-space-size` 标志）而崩溃，报错 `FATAL ERROR: Ineffective mark-compacts near heap limit — Allocation failed - JavaScript heap out of memory`。`dev` npm 脚本现在在调用时传递 `--max-old-space-size=8192`（这是为该进程设置此标志的唯一时机）。([#5198](https://github.com/diegosouzapw/OmniRoute/pull/5198) — 感谢 @backryun) +- **fix(cli): re-enable Turbopack as the default `npm run dev` bundler** — PR #4092 forced webpack because an earlier Turbopack 16.2.x panic (`internal error: entered unreachable code: there must be a path to a root` in `turbopack-core/module_graph`) blocked the OmniRoute module graph. That panic no longer reproduces on the pinned Next 16.2.9, so `OMNIROUTE_USE_TURBOPACK` is flipped from `0` to `1` in `.env.example`, aligning it with `docs/reference/ENVIRONMENT.md` which had already documented the default as `1`. ([#5206](https://github.com/diegosouzapw/OmniRoute/pull/5206) — 感谢 @backryun) +- **fix(auth): 允许 mimocode 使用合成无认证回退** — mimocode 连接在无显式凭证时会在到达执行器之前被阻止。认证层现在允许 mimocode 服务商的合成无认证回退，使无凭证访问模式按预期工作。([#5205](https://github.com/diegosouzapw/OmniRoute/pull/5205) — 感谢 @KooshaPari) +- **fix(combo): 将空 Responses API `output: []` 视为容灾触发而拒绝** — 非流式 Responses API 体带有 `object: "response"` 和 `output: []` 时，被 Combo 响应质量校验器接受为有效 HTTP 200，导致 Combo 目标停止而非容灾到下一个分支。非流式校验器现在在通用 `output` 快捷方式之前检查 Responses-API 形状的响应体，并将空 `output: []` 拒绝为 `empty_choices`；结构性非空输出（如 `function_call`）仍然有效。([#5207](https://github.com/diegosouzapw/OmniRoute/pull/5207) — 感谢 @KooshaPari) +- **fix(proxy): 在清除代理缓存时关闭缓存的调度器** — 缓存的代理和直连重试调度器在清除缓存时未被关闭，导致连接句柄泄漏。缓存清除路径现在对所有被逐出的调度器调用 `close()`；调度器缓存和生命周期辅助函数已从过度膨胀的 proxy-dispatcher 模块中提取到专用辅助模块以供复用。([#5202](https://github.com/diegosouzapw/OmniRoute/pull/5202) — 感谢 @KooshaPari) +- **fix(proxy): 合并每个代理 URL 的并发快速失败健康探测** — 在高并发下，每个同时到达的请求都会为同一代理 URL 打开自己的 TCP 健康探测，造成惊群效应。并发代理快速失败检查现在被合并，每个代理 URL 同时只运行一个 TCP 探测；已完成的健康结果缓存被保留，使后续相同 URL 的检查立即返回。([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109), [#5208](https://github.com/diegosouzapw/OmniRoute/pull/5208) — 感谢 @KooshaPari) +- **fix(pwa): 在显示离线页面之前优先使用缓存的导航** — Service Worker 在临时导航失败时过于急切地显示 `/offline`。现在它会缓存成功的导航响应，并在回退到 `/offline` 之前查询缓存的路由或应用壳；`/offline` 仅在无缓存导航或应用壳时作为最终回退保留。([#5165](https://github.com/diegosouzapw/OmniRoute/issues/5165), [#5209](https://github.com/diegosouzapw/OmniRoute/pull/5209) — 感谢 @KooshaPari) +- **fix(request-logger): 永远不在压缩徽章中渲染负百分比** — 当每个提示 Token 都被压缩时（`totalIn = 0, compressed > 0`），压缩药丸徽章显示 `(-100%)`，因为徽章格式在百分比值前硬编码了前导 `-`。徽章现在在这种情况下省略负号，正确地将节省量表示为正向比例。([#5201](https://github.com/diegosouzapw/OmniRoute/pull/5201) — 感谢 @KooshaPari) +- **fix(dashboard): 首页更新步骤警告图标使用 amber 色** — 首页更新步骤中的警告状态图标（`HomePageClient.tsx`）使用 `text-yellow-500`（Tailwind `#eab308`），在浅色背景上对比度很差（~1.9:1，低于 WCAG AA），且与同组件中所有同级元素使用的 `amber` 警告惯例不一致。切换为 `text-amber-500`——单行 `className` 变更，无行为变化。([#5176](https://github.com/diegosouzapw/OmniRoute/pull/5176)) ### 📝 维护 -- **test(combo): deterministic context-relay universal-handoff coverage** — covers the universal (provider-agnostic) session-handoff path in `context-relay` (`combo.ts:2099–2139`), which previously had only a definition-order assertion and a `TODO(phase-2)`. The test drives the real pipeline via session seams (`x-session-id` → `relayOptions.sessionId` → `maybeGenerateUniversalHandoff`) without live infrastructure. ([#5168](https://github.com/diegosouzapw/OmniRoute/pull/5168)) -- **test(combo): end-to-end quota-share DRR routing-decision coverage (matrix parity)** — adds the missing E2E test for the `quota-share` strategy, driving the real `handleChat` → chatCore → `selectQuotaShareTarget` → executor pipeline via in-process seams and asserting which connection is dispatched. The DRR selector already had 29 unit tests; this closes the E2E gap and brings quota-share to parity with the 17-strategy public matrix. ([#5179](https://github.com/diegosouzapw/OmniRoute/pull/5179)) -- **test(combo): deterministic context-relay codex quota-handoff coverage (closes last gap)** — covers the codex-specific handoff block of `context-relay` (`combo.ts:2143–2183`), which #5168 left documented-but-untested because it requires a `codex` connection. All seams (`fetchCodexQuota`, handoff generation, session relay) are mocked deterministically without live infra. ([#5195](https://github.com/diegosouzapw/OmniRoute/pull/5195)) -- **test(ci): wire antigravity-quota-family test under `test:vitest` (fix test-discovery orphan)** — `open-sse/services/__tests__/antigravity-quota-family.test.ts` (introduced by #5180) was not collected by any active runner, causing `check:test-discovery` to report a new orphan and gate every subsequent PR on the release branch. The file is now added to `vitest.mcp.config.ts` `include` and the corresponding orphan-allowlist entry is removed. ([#5196](https://github.com/diegosouzapw/OmniRoute/pull/5196)) -- **test(security): regression guard — PII redaction stays opt-in (default off) + Hard Rule #20** — adds a test asserting both `PII_REDACTION_ENABLED` and `PII_RESPONSE_SANITIZATION` feature-flag `defaultValue` fields are `"false"` and that data passes through all three application points (`piiMasker`, `piiSanitizer`, `streamingPiiTransform`) untouched when both flags are off, encoding Hard Rule #20 as a CI-enforced contract and fixing a misleading doc implication that PII masking was on by default. ([#5159](https://github.com/diegosouzapw/OmniRoute/pull/5159)) -- **docs(i18n): add Traditional Chinese (zh-TW) README + update zh-CN** — adds a new Traditional Chinese translation (`docs/i18n/zh-TW/README.md`) and updates the Simplified Chinese README to the current English baseline; the language index (`docs/i18n/README.md`) and root `README.md` badge row are updated accordingly. ([#5162](https://github.com/diegosouzapw/OmniRoute/pull/5162) — thanks @lunkerchen) -- **docs(i18n): full sync of zh-TW and zh-CN README to canonical English v3.8.39** — brings both translations to full parity, adding the complete What's New section, compression real-token examples, and all sections updated in the v3.8.38/39 English README. ([#5171](https://github.com/diegosouzapw/OmniRoute/pull/5171) — thanks @lunkerchen) -- **docs(combo): sync combo/routing-strategy docs to current state + document test coverage** — removes a stale ordinal from the Fusion bullet in `README.md`; adds a new **Testing & Coverage** section to `docs/routing/AUTO-COMBO.md` documenting the deterministic strategy matrix (`npm run test:combo:matrix`), quota-share DRR E2E coverage, and context-relay handoff tests delivered across the v3.8.39 cycle. ([#5185](https://github.com/diegosouzapw/OmniRoute/pull/5185)) -- **fix(docker):** copy the `open-sse` workspace manifest before `npm ci` so workspace-only deps install — the Dockerfile copied only the root `package*.json`, so `npm ci` skipped `safe-regex` and `@toon-format/toon` (declared in `open-sse/package.json`, not hoisted to root), breaking the multi-arch image build with `Module not found` during `npm run build`. (thanks @diegosouzapw) +- **test(combo): 确定性 context-relay 通用交接覆盖** — 覆盖 `context-relay` 中通用的（与服务商无关的）会话交接路径（`combo.ts:2099–2139`），该路径此前仅有定义顺序断言和一个 `TODO(phase-2)`。测试通过会话接缝（`x-session-id` → `relayOptions.sessionId` → `maybeGenerateUniversalHandoff`）驱动真实管线，无需实时基础设施。([#5168](https://github.com/diegosouzapw/OmniRoute/pull/5168)) +- **test(combo): 端到端 quota-share DRR 路由决策覆盖（矩阵对齐）** — 为 `quota-share` 策略添加缺失的 E2E 测试，通过进程内接缝驱动真实的 `handleChat` → chatCore → `selectQuotaShareTarget` → executor 管线，并断言分发的连接。DRR 选择器已有 29 个单元测试；此次补全了 E2E 缺口，使 quota-share 与 17 策略公开矩阵保持一致。([#5179](https://github.com/diegosouzapw/OmniRoute/pull/5179)) +- **test(combo): 确定性 context-relay codex 配额交接覆盖（补全最后缺口）** — 覆盖 `context-relay` 中 codex 特定的交接块（`combo.ts:2143–2183`），该块在 #5168 中有记录但未经测试，因为需要 `codex` 连接。所有接缝（`fetchCodexQuota`、交接生成、会话中继）均以确定性方式 mock，无需实时基础设施。([#5195](https://github.com/diegosouzapw/OmniRoute/pull/5195)) +- **test(ci): 将 antigravity-quota-family 测试纳入 `test:vitest`（修复测试发现孤儿）** — `open-sse/services/__tests__/antigravity-quota-family.test.ts`（由 #5180 引入）未被任何活跃运行器收集，导致 `check:test-discovery` 报告新的孤儿并阻塞发布分支上的每个后续 PR。该文件现已添加到 `vitest.mcp.config.ts` 的 `include` 中，对应的孤儿允许列表条目已移除。([#5196](https://github.com/diegosouzapw/OmniRoute/pull/5196)) +- **test(security): 回归守护 — PII 脱敏保持可选（默认关闭）+ 第 20 号硬规则** — 添加测试断言 `PII_REDACTION_ENABLED` 和 `PII_RESPONSE_SANITIZATION` 特性标志的 `defaultValue` 字段均为 `"false"`，且两个标志均关闭时数据在三个应用点（`piiMasker`、`piiSanitizer`、`streamingPiiTransform`）中均未修改地通过，将第 20 号硬规则编码为 CI 强制执行的契约，并修复了 PII 脱敏默认开启的误导性文档表述。([#5159](https://github.com/diegosouzapw/OmniRoute/pull/5159)) +- **docs(i18n): 添加繁体中文（zh-TW）README + 更新简体中文** — 新增繁体中文翻译（`docs/i18n/zh-TW/README.md`），并将简体中文 README 更新到当前英文基线；语言索引（`docs/i18n/README.md`）和根 `README.md` 徽章行相应更新。([#5162](https://github.com/diegosouzapw/OmniRoute/pull/5162) — 感谢 @lunkerchen) +- **docs(i18n): zh-TW 和 zh-CN README 与标准英文 v3.8.39 全面同步** — 使两个翻译版本达到完全对齐，添加了完整的新功能章节、压缩真实 Token 示例以及 v3.8.38/39 英文 README 中更新的所有章节。([#5171](https://github.com/diegosouzapw/OmniRoute/pull/5171) — 感谢 @lunkerchen) +- **docs(combo): 将 Combo/路由策略文档同步到当前状态 + 记录测试覆盖率** — 从 `README.md` 的 Fusion 条目中删除过时的序号；在 `docs/routing/AUTO-COMBO.md` 中新增**测试与覆盖率**章节，记录确定性策略矩阵（`npm run test:combo:matrix`）、quota-share DRR E2E 覆盖率和 v3.8.39 周期中交付的 context-relay 交接测试。([#5185](https://github.com/diegosouzapw/OmniRoute/pull/5185)) +- **fix(docker):** 在 `npm ci` 之前复制 `open-sse` 工作区清单以确保仅工作区的依赖能够安装 — Dockerfile 仅复制了根目录的 `package*.json`，因此 `npm ci` 跳过了 `safe-regex` 和 `@toon-format/toon`（声明在 `open-sse/package.json` 中，未提升到根目录），导致多架构镜像构建在 `npm run build` 期间因 `Module not found` 而失败。感谢 @diegosouzapw --- @@ -193,84 +193,84 @@ _In development — bullets added per PR; finalized at release._ ### ✨ 新功能 -- **feat(sidebar): colored menu icons** — sidebar menu icons now render with a per-item accent color: curated colors for known items (`SIDEBAR_ICON_ACCENTS`) plus a deterministic hash-based fallback (`getSidebarIconAccent`) so every item gets a stable, distinct color across sessions. ([#3812](https://github.com/diegosouzapw/OmniRoute/pull/3812) — thanks @rafacpti23) -- **feat(providers): add Factory (factory.ai) as a subscription gateway provider** — `factory` (Factory Droids' hosted gateway) is now a first-class routing provider on the OpenAI-compatible `https://api.factory.ai/v1` endpoint with Bearer apikey auth; the key is supplied from the Dashboard connection (not env). ([#5065](https://github.com/diegosouzapw/OmniRoute/pull/5065) — thanks @KooshaPari) -- **feat(providers): add Grok Build (xAI) provider with OAuth import-token flow** — `grok-cli` (alias `gc`) routes through Grok's CLI chat proxy; users paste their `~/.grok/auth.json` (or the JWT), with automatic `refresh_token` rotation. The public xAI client_id is embedded via `resolvePublicCred("grok_id")` (Hard Rule #11), never a literal. ([#5020](https://github.com/diegosouzapw/OmniRoute/pull/5020) — thanks @fulorgnas) -- **feat(dashboard): click-to-edit model alias in the provider page** — click an alias to edit it inline (Enter/blur saves, Escape cancels), instead of only being able to delete and re-add it. ([#5119](https://github.com/diegosouzapw/OmniRoute/pull/5119) — thanks @waguriagentic) -- **feat(providers): add ZenMux Free (session-cookie free-tier) provider** — `zenmux-free` (alias `zmf`) with a dedicated executor translating ZenMux's Anthropic-style SSE to OpenAI format; ships 12 free-tier models (DeepSeek V3.2, GLM 4.7 Flash Free, etc.). ([#5105](https://github.com/diegosouzapw/OmniRoute/pull/5105) — thanks @mrnasil) -- **feat(providers): allow local/private provider URLs by default (`Allow Local Provider URLs` flag)** — adding/validating an OpenAI-compatible provider on a loopback/LAN address (e.g. `http://127.0.0.1:3264/api`) was rejected by the SSRF guard with "Blocked private or local provider URL", even though OmniRoute is local-first. A new `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` feature flag (default **ON**, toggle in Settings → Feature Flags) now scopes the provider-validation guard to allow local/private hosts while still blocking cloud-metadata endpoints (169.254.169.254, metadata.google.internal). Disable it to restore strict public-only blocking. Webhook/remote-image SSRF defaults are unchanged. ([#5066](https://github.com/diegosouzapw/OmniRoute/issues/5066), thanks @daniij) -- **feat(blackbox):** refresh provider model catalog with latest models. (thanks @ptkelanatechsolutions) -- **kiro**: inline `` stream splitter — when `enabled` is present, `assistantResponseEvent` content is now split into separate `delta.content` / `delta.reasoning_content` SSE chunks (new `open-sse/executors/kiroThinking.ts` module wired into `KiroExecutor.transformEventStreamToSSE`). -- **feat(cursor):** parse Cursor Composer DeepSeek-style inline tool calls — Composer `cu/composer-2.5*` models embed tool invocations in their visible text using `<｜tool▁calls▁begin｜>…<｜tool▁calls▁end｜>` markers instead of structured protobuf frames; a new streaming parser (`composerToolCalls.ts`) intercepts these in both streaming and non-streaming paths, suppresses the markers from the client-visible content, and emits proper OpenAI `tool_calls` deltas so downstream clients handle them natively. (thanks @noestelar) -- **feat(proxy):** support auth-less `host:port` batch import and surface proxy-test failures. (thanks @dimaslanjaka) -- **feat(video): Alibaba DashScope video provider (`wan2.7-t2v`)** — adds the `alibaba` video provider (DashScope async task → poll → MP4) wired through the standard apikey credential path, so text-to-video requests can route to Alibaba's `wan2.7-t2v` model. (thanks @josevictorferreira) -- **feat(cc): per-connection "summarized thinking display" toggle for Claude-Code-compatible providers** — exposes a connection-level toggle that drives the existing Copilot summarized-thinking marker, so operators can opt a CC-compatible connection into summarized reasoning display from the UI (schema + request defaults + provider modals, with i18n). (thanks @rdself) -- **feat(compression): compression playground in the studio (Play + Compare tabs)** — `/dashboard/compression/studio` gains a synthetic playground: paste text → per-engine **lanes** (each deterministic engine run alone via `/api/compression/preview`) plus a **combined waterfall** ordered by `stackPriority`, and a free **A/B Compare** grid with on-demand, **USD-capped** fidelity verdicts (`/api/compression/compare` + `compare/verify`). The preview route now uses the real cl100k tokenizer, returns `engineBreakdown`, and accepts an ordered `pipeline[]`; new `compare` / `compare/verify` / `retrieve` routes; the live WS feed moved to `/dashboard/compression/live`. Management-only. ([#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080)) -- **feat(dashboard): expose Fusion `judgeModel` + `fusionTuning` in the combo editor** — the Fusion strategy editor now surfaces the judge model (synthesizes the panel answers; defaults to the first panel model) plus the quorum-grace tuning fields (`minPanel`, `stragglerGraceMs`, `panelHardTimeoutMs`) that `open-sse/services/fusion.ts` already reads. Schema-validated + bounded; empty tuning is never persisted. ([#5074](https://github.com/diegosouzapw/OmniRoute/pull/5074)) -- **feat(compression): opt-in per-step fidelity gate for the stacked pipeline** — each compression step can now be guarded by a pure fidelity checker (4 invariants, fail-open) so a lossy engine that would degrade the prompt past a threshold is rejected and its lane skipped instead of silently shipping. Configurable via `fidelityGate` (advanced thresholds intentionally API-omitted), with a per-lane rejection breakdown surfaced in the studio playground toggle. ([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143)) -- **feat(compression): fuzzy near-duplicate dedup (session-dedup 2nd pass)** — the session-dedup engine gains a second fuzzy pass that collapses near-duplicate (not just byte-identical) segments, with a playground toggle to compare on/off. ([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143)) -- **feat(quota): opt-in Codex/Claude auto-ping keepalive** — an opt-in background keepalive can periodically ping Codex/Claude connections to keep their session/quota state warm, reducing cold-start failures on the first real request. ([#5102](https://github.com/diegosouzapw/OmniRoute/pull/5102)) -- **feat(ops): SRE playbooks + ops helper scripts** — salvaged from a closed stale PR; adds operator runbooks and ops helper scripts. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @KooshaPari / @diegosouzapw) -- **feat(mcp): web-session robustness — cookie dedup + browser-pool observability** — the MCP web-session path now de-duplicates cookies when (re)hydrating a session (avoiding conflicting duplicate `Cookie` headers) and exposes browser-pool observability (pool size / in-use / acquisition metrics) for the headless web providers. ([#5121](https://github.com/diegosouzapw/OmniRoute/pull/5121), builds on [#3368](https://github.com/diegosouzapw/OmniRoute/issues/3368)) -- **feat(compression): Ionizer engine — lossy JSON-array sampling reversible via CCR** — a new compression engine that down-samples large JSON arrays to a representative subset and records a Compact Change Representation (CCR) so the omitted rows can be reconstructed, trading exactness for a large token reduction on tabular/array-heavy payloads. ([#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148)) +- **feat(sidebar): 彩色菜单图标** — 侧边栏菜单图标现在以每项主题色渲染：已知项使用精选颜色（`SIDEBAR_ICON_ACCENTS`），再加上基于哈希的确定性回退方案（`getSidebarIconAccent`），使每项在会话间获得稳定、独特的颜色。([#3812](https://github.com/diegosouzapw/OmniRoute/pull/3812) — 感谢 @rafacpti23) +- **feat(providers): 新增 Factory (factory.ai) 订阅网关服务商** — `factory`（Factory Droids 的托管网关）现已成为 OpenAI 兼容端点 `https://api.factory.ai/v1` 上的一级路由服务商，使用 Bearer apikey 认证；密钥从仪表盘连接中提供（而非环境变量）。([#5065](https://github.com/diegosouzapw/OmniRoute/pull/5065) — 感谢 @KooshaPari) +- **feat(providers): add Grok Build (xAI) provider with OAuth import-token flow** — `grok-cli` (alias `gc`) routes through Grok's CLI chat proxy; users paste their `~/.grok/auth.json` (or the JWT), with automatic `refresh_token` rotation. The public xAI client_id is embedded via `resolvePublicCred("grok_id")` (Hard Rule #11), never a literal. ([#5020](https://github.com/diegosouzapw/OmniRoute/pull/5020) — 感谢 @fulorgnas) +- **feat(dashboard): 服务商页面中的模型别名支持点击编辑** — 点击别名即可内联编辑（Enter/失焦保存，Escape 取消），而不只能删除再重新添加。([#5119](https://github.com/diegosouzapw/OmniRoute/pull/5119) — 感谢 @waguriagentic) +- **feat(providers): 新增 ZenMux Free（会话 Cookie 免费层）服务商** — `zenmux-free`（别名 `zmf`），配备专用执行器，将 ZenMux 的 Anthropic 风格 SSE 翻译为 OpenAI 格式；包含 12 个免费层模型（DeepSeek V3.2、GLM 4.7 Flash Free 等）。([#5105](https://github.com/diegosouzapw/OmniRoute/pull/5105) — 感谢 @mrnasil) +- **feat(providers): 默认允许本地/私有服务商 URL（`Allow Local Provider URLs` 标志）** — 在 loopback/LAN 地址（如 `http://127.0.0.1:3264/api`）上添加/校验 OpenAI 兼容服务商时，会被 SSRF 守卫以 "Blocked private or local provider URL" 拒绝，尽管 OmniRoute 是本机优先的。新增 `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` 特性标志（默认**开启**，在设置 → 特性标志中切换），限定服务商校验守卫的范围：允许本地/私有主机，同时仍然阻止云元数据端点（169.254.169.254、metadata.google.internal）。禁用它可恢复到严格的仅公网模式。Webhook/远端镜像 SSRF 默认值不变。([#5066](https://github.com/diegosouzapw/OmniRoute/issues/5066)，感谢 @daniij) +- **feat(blackbox):** 刷新服务商模型目录，更新为最新模型。（感谢 @ptkelanatechsolutions） +- **kiro**: 内联 `` 流分割器 — 当 `enabled` 存在时，`assistantResponseEvent` 内容现在被分割为独立的 `delta.content` / `delta.reasoning_content` SSE 块（新增 `open-sse/executors/kiroThinking.ts` 模块，接入 `KiroExecutor.transformEventStreamToSSE`）。 +- **feat(cursor):** 解析 Cursor Composer DeepSeek 风格的内联工具调用 — Composer `cu/composer-2.5*` 模型使用 `<｜tool▁calls▁begin｜>…<｜tool▁calls▁end｜>` 标记而非结构化 protobuf 帧来嵌入工具调用；新的流式解析器（`composerToolCalls.ts`）在流式和非流式路径中拦截这些标记，从客户端可见内容中去除标记，并发出符合标准的 OpenAI `tool_calls` delta 供下游客户端原生处理。感谢 @noestelar +- **feat(proxy):** 支持无认证的 `host:port` 批量导入，并展示代理测试失败信息。感谢 @dimaslanjaka +- **feat(video): 阿里云 DashScope 视频服务商（`wan2.7-t2v`）** — 新增 `alibaba` 视频服务商（DashScope 异步任务 → 轮询 → MP4），通过标准 apikey 凭证路径接入，使文本转视频请求可路由到阿里的 `wan2.7-t2v` 模型。感谢 @josevictorferreira +- **feat(cc): Claude-Code 兼容服务商的每连接"摘要思考显示"开关** — 暴露连接级别的开关，驱动现有的 Copilot 摘要思考标记，使运维人员可从 UI 将 CC 兼容连接配置为摘要推理显示（Schema + 请求默认值 + 服务商模态框，含 i18n）。感谢 @rdself +- **feat(compression): 工作室中的压缩游乐场（Play + Compare 标签页）** — `/dashboard/compression/studio` 新增合成游乐场：粘贴文本 → 按引擎的**通道**（每个确定性引擎通过 `/api/compression/preview` 单独运行）以及按 `stackPriority` 排序的**组合瀑布流**，以及带有按需、**USD 上限**保真度评分的自由 **A/B Compare** 网格（`/api/compression/compare` + `compare/verify`）。预览路由现在使用真实的 cl100k tokenizer，返回 `engineBreakdown`，并接受有序的 `pipeline[]` 参数；新增 `compare` / `compare/verify` / `retrieve` 路由；实时 WS 订阅迁移至 `/dashboard/compression/live`。仅限管理权限。([#5080](https://github.com/diegosouzapw/OmniRoute/pull/5080)) +- **feat(dashboard): 在 Combo 编辑器中暴露 Fusion `judgeModel` + `fusionTuning`** — Fusion 策略编辑器现在展示裁判模型（综合评审团答案；默认为第一个评审团模型）以及 quorum-grace 调优字段（`minPanel`、`stragglerGraceMs`、`panelHardTimeoutMs`），这些字段 `open-sse/services/fusion.ts` 已经读取。Schema 验证 + 有界；空调优永不持久化。([#5074](https://github.com/diegosouzapw/OmniRoute/pull/5074)) +- **feat(compression): 级联管线的可选每步保真度门禁** — 每个压缩步骤现在可以由纯保真度检查器守护（4 个不变量，敞开后效），因此如果某个有损引擎会使提示降级超过阈值，则拒绝该步骤并跳过其通道，而不是静默输出。通过 `fidelityGate` 配置（高级阈值有意排除在 API 之外），并在工作室 Playground 开关中展示每个通道的拒绝明细。([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143)) +- **feat(compression): 模糊近似去重（session-dedup 第二遍）** — session-dedup 引擎增加第二遍模糊匹配，折叠近似重复（而非仅字节完全相同）的片段，并提供工作室开关对比开启/关闭效果。([#5143](https://github.com/diegosouzapw/OmniRoute/pull/5143)) +- **feat(quota): 可选的 Codex/Claude 自动 ping 保活** — 可选的后台保活功能可定期 ping Codex/Claude 连接以保持其会话/配额状态预热，减少首次真实请求的冷启动失败。([#5102](https://github.com/diegosouzapw/OmniRoute/pull/5102)) +- **feat(ops): SRE 运维手册 + 运维辅助脚本** — 从已关闭的过期 PR 中抢救而来；新增运维 Runbook 和运维辅助脚本。([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — 感谢 @KooshaPari / @diegosouzapw) +- **feat(mcp): Web 会话健壮性——Cookie 去重 + 浏览器池可观测性** — MCP Web 会话路径现在在（重新）加载会话时对 Cookie 进行去重（避免冲突的重复 `Cookie` 头），并为无头 Web 服务商暴露浏览器池可观测性（池大小 / 使用中 / 获取指标）。([#5121](https://github.com/diegosouzapw/OmniRoute/pull/5121)，基于 [#3368](https://github.com/diegosouzapw/OmniRoute/issues/3368)) +- **feat(compression): Ionizer 引擎——有损 JSON 数组采样，可通过 CCR 恢复** — 新的压缩引擎，将大型 JSON 数组下采样为代表性子集，并记录紧凑变更表示（CCR），以便可以重建被省略的行，在表格/数组密集型载荷上以精确性换取大幅 Token 减少。([#5148](https://github.com/diegosouzapw/OmniRoute/pull/5148)) ### 🔧 问题修复 -- **fix(proxy): make the SOCKS5 handshake timeout operator-tunable (`SOCKS_HANDSHAKE_TIMEOUT_MS`)** — under high concurrency against a single residential gateway host, the SOCKS5 connect handshake could exceed the hardcoded 10s even though the proxy was reachable, surfacing as a false `[Proxy Fast-Fail] Proxy unreachable` (the pool size is already tunable via `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS`). The handshake timeout now reads `SOCKS_HANDSHAKE_TIMEOUT_MS` (default unchanged at `10000`, capped at `120000`) so a concurrency-heavy deployment can raise it without a code change. Mitigation for #5109 (the full concurrency-100 collapse still needs the reporter's live load-test confirmation). ([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109)) -- **fix(api): resolve `GET /v1/models/{id}` case-insensitively** — clients that normalise the model id (e.g. OpenCode requesting `minimax/minimax-m3` for the canonical catalog entry `minimax/MiniMax-M3`) missed the single-model lookup, which is case-sensitive, and fell back to advertising `context_length: 0`. `findModelById` now prefers an exact-case match and falls back to a case-insensitive match, so the real entry (and its context window) is returned regardless of casing. ([#5082](https://github.com/diegosouzapw/OmniRoute/issues/5082)) -- **fix(services): embed WS proxy honours `LIVE_WS_HOST`; reject empty `messages` early** — two headless/Docker deployment fixes (#5110). The embed WebSocket proxy (`:20131`) only read `EMBED_WS_PROXY_HOST`, so behind a reverse proxy/tunnel it stayed bound to `127.0.0.1` even with `LIVE_WS_HOST=0.0.0.0` set and the Live dashboard showed "WebSocket disconnected"; it now falls back to `LIVE_WS_HOST` (default still loopback). Separately, a request with an explicitly empty `messages: []` array was forwarded upstream and bounced back as a confusing raw `400/502`; `handleChat` now rejects it up front with a clear `messages: at least one message is required` (Responses-API `input` requests are unaffected). ([#5110](https://github.com/diegosouzapw/OmniRoute/issues/5110)) -- **fix(proxy): repair one-click Deno & Cloudflare relay deployments** — the `/api/settings/proxy/test` endpoint only recognized the `vercel` relay type, so testing a deployed Deno or Cloudflare relay returned `proxy.type must be http, https, or socks5` and never reached the relay; it now routes all relay types through `isRelayType()`. On installs with `STORAGE_ENCRYPTION_KEY` the relay-auth token is read via `extractRelayAuth` (encrypted `relayAuthEnc` form), fixing the silent `401` that left `publicIp` null. The Cloudflare Worker upload now sends the script part as `application/javascript` (the API rejects `application/javascript+module`; ES-module semantics come from `main_module`), and the proxy-registry schema accepts the `deno`/`cloudflare` types + `deno-relay`/`cloudflare-relay` sources so editing a deployed relay no longer 400s. ([#5128](https://github.com/diegosouzapw/OmniRoute/issues/5128)) -- **fix(kiro): retire `claude-sonnet-4.5` from the Kiro catalog + pin the exact Kiro 400 error** — `claude-sonnet-4.5` left the Kiro free-tier lineup (current active models: Opus 4.8/4.7/4.6, Sonnet 4.6, Haiku 4.5), so it is removed from the Kiro registry entry and the free-model catalog. A regression test now pins Kiro's verbatim `[400] Invalid model. Please select a different model to continue.` to the `isModelUnavailableError` model-unavailable classification. A 400 on every model (including current ones) points to a server-side Kiro tier/region gate, not an OmniRoute catalog bug. ([#5140](https://github.com/diegosouzapw/OmniRoute/pull/5140), closes [#4484](https://github.com/diegosouzapw/OmniRoute/issues/4484)) -- **fix(dashboard): preserve every rendered field when loading/saving Resilience settings** — `ResilienceTab` renders `comboCooldownWait` and `quotaShareConcurrencyLimit`, but both the initial-load and save paths rewrote component state without those fields, so after a successful `/api/resilience` response the cards received `undefined` and the page fell back to the generic "failed to load" state. A shared `toResilienceResponse()` mapper now keeps all rendered fields, and `PATCH /api/resilience` returns `quotaShareConcurrencyLimit` to match GET and the UI contract. ([#5139](https://github.com/diegosouzapw/OmniRoute/pull/5139) — thanks @rdself) -- **fix(quota): hydrate the in-memory quota cache from snapshots + scope auto-combo candidates** — after a restart the quota cache was empty, so a known-exhausted connection looked healthy until re-queried; `isAccountQuotaExhausted` now lazily hydrates from persisted `quota_snapshots`. Auto-combo candidate expansion is also scoped to the connections each combo target actually allows, instead of pulling in every connection for the provider. ([#5015](https://github.com/diegosouzapw/OmniRoute/pull/5015) — thanks @JxnLexn) -- **fix(resilience): harden quota cutoff, Gemini audio MIME, and model-lockout cooldown** — stored quota hard-cutoff values are no longer coerced to `enabled=true` from arbitrary strings; Gemini audio input parts have their MIME type validated/normalized before forwarding; and model lockout now honours the configured `maxCooldownMs` ceiling. ([#5093](https://github.com/diegosouzapw/OmniRoute/pull/5093) — thanks @KooshaPari) -- **fix(streaming): harden long OpenAI-compatible SSE streams** — a late pipeline-wind-down error can no longer overwrite an already-recorded successful stream (`streamCompletionRecorded` guard), client disconnects finalize as `499 client_disconnected` instead of poisoning provider/account failure state, JSON bodies that are actually SSE (wrong `application/json` content-type) are sniffed and re-streamed, and reasoning fields (`reasoning`/`reasoning_content` + OpenRouter/Gemini encrypted `reasoning_details`) are preserved through the JSON-as-SSE fallback. ([#5124](https://github.com/diegosouzapw/OmniRoute/pull/5124) — thanks @rdself) -- **fix(usage): dedupe request-usage logging and debounce stats events** — `saveRequestUsage` now guards against duplicate inserts (natural key: timestamp + provider + model + connection + api-key + token counts), back-fills a missing `endpoint`, and only emits `usageRecorded` when a row was actually inserted; stats `update`/`pending` event bursts are collapsed into a single debounced notification to reduce churn. ([#4940](https://github.com/diegosouzapw/OmniRoute/pull/4940) — thanks @nguyenxvotanminh3) -- **fix(sse): convert the native Gemini request body to OpenAI format in the Antigravity MITM handler** — `contents` / `systemInstruction` / `generationConfig` / `thinkingConfig` are now translated to OpenAI chat-completions format before forwarding to `/v1/chat/completions`, so thinking-capable models (e.g. `ag/claude-opus-4-6-thinking`) no longer fail with provider-side 400 "invalid argument" errors. ([#4845](https://github.com/diegosouzapw/OmniRoute/pull/4845) — thanks @anuragg-saxenaa) -- **fix(db): translate the two pt-BR SQLite driver-fallback log lines to English** — `[DB] Pré-inicializando sql.js WASM…` and `[DB] Drivers síncronos indisponíveis…` were the only non-English server log strings, mixing languages in the logs. Now `[DB] Pre-initializing sql.js WASM (synchronous drivers unavailable)…` / `[DB] Synchronous drivers unavailable — falling back to sql.js (WASM)`, guarded by a test that scans the driver path for accented log strings. ([#5103](https://github.com/diegosouzapw/OmniRoute/issues/5103)) -- **fix(diagnostics): non-streaming Claude responses no longer false-502 as `empty_choices`** — the v3.8.37 malformed-200 detector (#4942) only understood OpenAI `choices` and Responses-API `output` shapes, so a `/v1/messages` response that stays in Claude shape (`{type:"message", content:[…]}`) fell through to `empty_choices` → 502 (cascading to "All models failed" in a combo). Most visibly, an extended-thinking turn whose buffered body is a single **empty thinking block with a valid `signature`** (Claude Code's non-streaming Bash classifier) 502'd on every call. `detectMalformedNonStream` now understands the Claude shape: text/tool_use blocks and thinking blocks carrying a signature count as valid output, while a genuinely empty `content:[]` is still flagged. ([#5108](https://github.com/diegosouzapw/OmniRoute/issues/5108), thanks @insoln) -- **fix(combo): empty-content 502 now fails over within the same request instead of exhausting the provider** — a leg that answers HTTP 200 with no usable completion is rewritten to `502 "Provider returned empty content"`, but the combo exhaustion classifier treated that synthetic 502 as a connection-level failure (`#1731v2`) and marked the whole provider/connection exhausted, skipping every remaining **same-provider** leg in that request. The connection is actually healthy (it just returned an empty body), so empty-content 502s are now classified as model-level transient failures: the request advances to the next leg and the rest of that provider's legs stay eligible. Genuine gateway 502s still trip connection exhaustion. ([#5085](https://github.com/diegosouzapw/OmniRoute/issues/5085), thanks @andrea-kingautomation) -- **fix(dashboard): surface the detailed credential-validation error instead of a bare "invalid" badge** — the inline "Check" in the Add-Connection modal discarded the `error` message returned by `/api/providers/validate` and showed only an `invalid` badge. For web providers (claude-web / chatgpt-web) the real cause is often an environment error the backend already reports (e.g. `TLS impersonation client failed to start: EACCES … mkdir tls-client-node/bin`), so users were left guessing. The modal now renders the full reason next to the badge. ([#5088](https://github.com/diegosouzapw/OmniRoute/issues/5088), thanks @tkhs101) -- **fix(executors): strip `client_metadata` from forwarded body for Cerebras and Mistral** — Cerebras returns 400 (`wrong_api_format`) and Mistral returns 422 (`extra_forbidden`) when the passthrough body carries `client_metadata` (an OpenAI Codex / Claude CLI field with no equivalent on these upstreams). The default executor now drops it for these two providers before sending downstream; other providers (notably `openai`/`codex`) keep it. (thanks @saurabh321gupta) -- **fix(codebuddy):** only send reasoning params when the client requests reasoning. (thanks @anki1kr) -- **fix(sse):** keep streaming for forceStream providers when a JSON client requests it. Providers marked `forceStream:true` reject `stream:false` upstream (HTTP 400); `resolveStreamFlag` now guards against this so stream-only providers keep streaming even when the client sends `Accept: application/json` or `stream:false`. (thanks @anki1kr) -- **fix(sse):** prevent non-JSON SSE lines and duplicate `[DONE]` from breaking clients. (thanks @qianze0628) -- **fix(sse):** dedupe case-variant Anthropic headers in the executor `buildHeaders` path — Node/undici's `fetch` merges `anthropic-version` and `Anthropic-Version` into a single `"v, v"` value that the Anthropic API rejects, so both case variants are now collapsed to one canonical lowercase header (same for `anthropic-beta`). (thanks @Delcado19) -- **oauth(kiro):** support Kiro IDC (organization) token import — when the `~/.aws/sso/cache` token carries a `clientIdHash`, auto-import now reads the linked client registration file to obtain `clientId`/`clientSecret`, probes the Kiro IDE `profile.json` for `profileArn` (ARN region normalized to `us-east-1` for the runtime gateway), and refreshes via the regional AWS OIDC endpoint instead of the social path; the import schema and modal forward these credentials so manual imports also work for IDC tokens. (thanks @enjoyer-hub) -- **fix(translator):** preserve client `cache_control` breakpoints when routing Claude-format requests (e.g. Claude Code) to Alibaba DashScope's OpenAI-compatible providers (`alibaba` / `alibaba-cn`). The Claude→OpenAI translation previously stripped the markers from the system and message text blocks, so DashScope's explicit caching never engaged and every request was a cache miss. Cache hints now survive when preservation is requested for caching-capable OpenAI-format providers. (thanks @sacrtap) -- **fix(tts):** resolve Gemini TTS models from catalog and add `gemini-3.1-flash-tts-preview` as the new default Vertex TTS model. (thanks @nguyenha935) -- **fix(sse): don't cool down a healthy connection on a self-inflicted upstream timeout (504)** — when OmniRoute's own deadline elapses (surfaced as `TimeoutError`/`BodyTimeoutError` → 504), the connection is no longer disabled/failed-over, so a slow-but-healthy provider isn't penalised for our timeout. Genuine upstream 5xx/429 still trigger cooldown; antigravity keeps its own policy. (thanks @costaeder) -- **fix(translator):** forward image `tool_result` blocks as `image_url` instead of stringifying base64. (thanks @alican532) -- **fix(sse): robust Anthropic `/v1/messages` streaming — real ping keepalive + client-disconnect guard** — slow first tokens on reasoning models could trip strict clients' idle-read watchdog; the route now keeps the stream warm with a real `event: ping` (Anthropic clients ignore SSE comments) from the very first frame, and a client disconnect (AbortError / controller-closed) no longer counts as a provider failure (no failover/cooldown). (thanks @costaeder) -- **fix: preserve model hidden flags (`isHidden`) across model sync** — `replaceCustomModels` pruned the compat-override list to the new custom-model ids, silently wiping the `isHidden` flag of eye-hidden SYNCED models on every periodic sync / import (all hidden models turned back on). The redundant cleanup is removed (per-model removal already handles its own compat cleanup), so eye-hidden models stay hidden across re-sync. ([#5086](https://github.com/diegosouzapw/OmniRoute/pull/5086) — thanks @herjarsa) -- **fix(models): derive model-discovery config from the registry `modelsUrl`** — providers absent from the hardcoded `PROVIDER_MODELS_CONFIG` but carrying a registry `modelsUrl` (e.g. MiniMax) now get an auto-derived Bearer `/v1/models` discovery config, so "discover models" works instead of returning nothing. (thanks @herjarsa) -- **fix(compression): resolve worker + rule/filter assets via runtime anchors (standalone bundle)** — the LLMLingua worker and the RTK rule/filter loaders relied on `fileURLToPath(import.meta.url)`, which the standalone bundle freezes to the build-machine path, so the worker never spawned and rule/filter packs failed to resolve. They now anchor on `process.cwd()`/`argv[1]` (with `pathToFileURL` for the worker URL). (thanks @fulorgnas) -- **fix(api): sanitize error responses on seven management routes (Rule #12 hardening)** — `cli-tools/backups`, `cli-tools/guide-settings/[toolId]`, `logs/export`, `models/catalog`, `providers/test-batch`, `settings/import-json` and `usage/proxy-logs` no longer return raw `error.message`; they wrap caught errors in `sanitizeErrorMessage(...)`, and the routes are removed from the `check-error-helper` allowlist. (thanks @JxnLexn) -- **fix(sse): keep `output_text`-only Responses bodies from being dropped/false-502'd** — some upstreams return a shorthand Responses body whose answer is only in `output_text` with an empty `output[]`. `sanitizeResponsesApiResponse` discarded the text, so the response then tripped the malformed-200 guard. The sanitizer now synthesizes an `output[]` message item from a non-empty `output_text` (complements the Claude-native fix in #5108; both stem from #4942). -- **fix(executors): preserve a lone caller-supplied `Anthropic-Version` header casing** — the case-variant dedupe (#4846) unconditionally rewrote `Anthropic-Version`/`Anthropic-Beta` to lowercase even when only one variant was present, clobbering the caller's header. Dedupe now runs only when both case variants coexist (the actual undici-merge collision it was meant to fix). -- **fix(responses):** default `text.format` to `{ type: "text" }` for openai-compatible **responses** providers — some Responses-compatible upstreams (e.g. LM Studio) reject a `text` object missing `text.format` with a 400 `missing_required_parameter`; the default executor now fills the Responses-API default before forwarding (guarded to `openai-compatible-*responses*`, never overwriting an existing format). (thanks @StevanusPangau) -- **fix(translator): stop stripping client-provided `reasoning_content` for reasoning-replay providers** — the #4849 agentic-context strip (which drops `reasoning_content` from tool-call assistant turns to avoid O(n²) token growth) ran unconditionally, so replay providers (DeepSeek V4, Kimi K2, Qwen-Thinking, etc.) lost the client's reasoning and the reasoning-replay cache then overwrote it with a stale cached value (and such upstreams 400 without the original reasoning). The strip now skips reasoning-replay targets while non-reasoning providers keep the O(n²) protection. ([#5122](https://github.com/diegosouzapw/OmniRoute/pull/5122)) -- **fix(providers): add MiniMax M3 & Nemotron 3 Ultra to the Cline catalog** — the two models were missing from Cline's provider catalog and could not be selected; both are now registered. ([#5136](https://github.com/diegosouzapw/OmniRoute/pull/5136), closes [#3321](https://github.com/diegosouzapw/OmniRoute/issues/3321)) -- **fix(dashboard): key model-visibility toggle on the canonical `providerId`** — the per-model visibility toggle keyed off a display id, so toggling a model on one provider alias could mis-target another; it now keys on the canonical `providerId`. ([#5091](https://github.com/diegosouzapw/OmniRoute/pull/5091) — thanks @Theadd) -- **fix(diagnostics): recognize the Claude API format in `detectMalformedNonStream`** — salvaged null-guard so a Claude-shaped non-streaming body is no longer misclassified. ([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — thanks @herjarsa / @diegosouzapw) -- **fix(logging): track the final connection IDs in failover logs** — failover log lines now record the connection that actually served (or last failed) the request, instead of only the first attempt. ([#5016](https://github.com/diegosouzapw/OmniRoute/pull/5016) — thanks @JxnLexn) -- **fix(sse): ignore disconnect races during in-band stream error handling** — a client disconnect that races with in-band upstream error handling no longer surfaces as a spurious provider failure. ([#5007](https://github.com/diegosouzapw/OmniRoute/pull/5007) — thanks @JxnLexn) -- **fix(dashboard): surface the server error on `handleToggleCombo` failure** — a failed combo toggle now shows the backend error instead of silently no-op'ing. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @KooshaPari / @diegosouzapw) -- **fix(quota): track provider quota reset windows + enrich the Codex playground** — observed quota reset windows are tracked and surfaced, and the Codex playground gains the enriched quota metadata. ([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — thanks @Witroch4 / @diegosouzapw) -- **fix(sidebar): drop the orphan `settings` accent color** — removed a dangling accent-color entry that broke `typecheck:core`. ([#5142](https://github.com/diegosouzapw/OmniRoute/pull/5142)) -- **fix(sse): preserve non-stream reasoning fields for compatible clients** — non-streaming responses now keep the upstream reasoning fields (`reasoning` / `reasoning_content` and OpenRouter/Gemini `reasoning_details`) instead of stripping them in `responseSanitizer`, so clients that render reasoning on buffered responses no longer lose it. ([#5155](https://github.com/diegosouzapw/OmniRoute/pull/5155) — thanks @rdself) -- **fix(i18n): add missing English UI labels** — fills in untranslated English strings that were surfacing as raw keys in the dashboard. ([#5153](https://github.com/diegosouzapw/OmniRoute/pull/5153) — thanks @rdself) +- **fix(proxy): 使 SOCKS5 握手超时可运维调整（`SOCKS_HANDSHAKE_TIMEOUT_MS`）** — 在针对同一住宅网关主机的高并发下，SOCKS5 连接握手可能超过硬编码的 10 秒，即使代理可达，也会表现为虚假的 `[Proxy Fast-Fail] Proxy unreachable`（池大小已可通过 `OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS` 调整）。握手超时现在读取 `SOCKS_HANDSHAKE_TIMEOUT_MS`（默认值保持 `10000`，上限 `120000`），使高并发部署可以无需代码更改提高此值。对 #5109 的缓解措施（完整的 concurrency-100 崩溃仍需报告者的现场压力测试确认）。([#5109](https://github.com/diegosouzapw/OmniRoute/issues/5109)) +- **fix(api): 不区分大小写地解析 `GET /v1/models/{id}`** — 规范化模型 id 的客户端（如 OpenCode 请求 `minimax/minimax-m3` 查找标准目录条目 `minimax/MiniMax-M3`）会错过区分大小写的单模型查询，回退到显示 `context_length: 0`。`findModelById` 现在优先精确大小写匹配，回退到不区分大小写匹配，因此无论大小写如何都返回真实条目（及其上下文窗口）。([#5082](https://github.com/diegosouzapw/OmniRoute/issues/5082)) +- **fix(services): 内嵌 WS 代理遵循 `LIVE_WS_HOST`；早期拒绝空 `messages`** — 两个无头/Docker 部署修复（#5110）。内嵌 WebSocket 代理（`:20131`）仅读取 `EMBED_WS_PROXY_HOST`，因此在反向代理/隧道后即使设置了 `LIVE_WS_HOST=0.0.0.0` 仍然绑定在 `127.0.0.1`，实时仪表盘显示"WebSocket disconnected"；现在回退到 `LIVE_WS_HOST`（默认仍为 loopback）。此外，显式空 `messages: []` 数组的请求此前被转发到上游并以混乱的原始 `400/502` 返回；`handleChat` 现在以明确的 `messages: at least one message is required` 预先拒绝（Responses-API `input` 请求不受影响）。([#5110](https://github.com/diegosouzapw/OmniRoute/issues/5110)) +- **fix(proxy): 修复一键 Deno 和 Cloudflare 中继部署** — `/api/settings/proxy/test` 端点仅识别 `vercel` 中继类型，因此测试已部署的 Deno 或 Cloudflare 中继会返回 `proxy.type must be http, https, or socks5` 而从未到达中继；现在通过 `isRelayType()` 路由所有中继类型。在有 `STORAGE_ENCRYPTION_KEY` 的安装中，中继认证 Token 通过 `extractRelayAuth`（加密的 `relayAuthEnc` 形式）读取，修复了导致 `publicIp` 为 null 的静默 `401`。Cloudflare Worker 上传现在将脚本部分作为 `application/javascript` 发送（API 拒绝 `application/javascript+module`；ES 模块语义来自 `main_module`），且代理注册表 Schema 接受 `deno`/`cloudflare` 类型和 `deno-relay`/`cloudflare-relay` 来源，使编辑已部署的中继不再返回 400。([#5128](https://github.com/diegosouzapw/OmniRoute/issues/5128)) +- **fix(kiro): 从 Kiro 目录中移除 `claude-sonnet-4.5` + 精确匹配 Kiro 400 错误** — `claude-sonnet-4.5` 已离开 Kiro 免费层阵容（当前活跃模型：Opus 4.8/4.7/4.6、Sonnet 4.6、Haiku 4.5），因此从 Kiro 注册表条目和免费模型目录中移除。回归测试现在将 Kiro 的字面 `[400] Invalid model. Please select a different model to continue.` 精确匹配到 `isModelUnavailableError` 模型不可用分类。所有模型（包括当前模型）都返回 400 则指向服务端 Kiro 层级/区域门禁，而非 OmniRoute 目录错误。([#5140](https://github.com/diegosouzapw/OmniRoute/pull/5140)，关闭 [#4484](https://github.com/diegosouzapw/OmniRoute/issues/4484)) +- **fix(dashboard): preserve every rendered field when loading/saving Resilience settings** — `ResilienceTab` renders `comboCooldownWait` and `quotaShareConcurrencyLimit`, but both the initial-load and save paths rewrote component state without those fields, so after a successful `/api/resilience` response the cards received `undefined` and the page fell back to the generic "failed to load" state. A shared `toResilienceResponse()` mapper now keeps all rendered fields, and `PATCH /api/resilience` returns `quotaShareConcurrencyLimit` to match GET and the UI contract. ([#5139](https://github.com/diegosouzapw/OmniRoute/pull/5139) — 感谢 @rdself) +- **fix(quota): 从快照中加载内存配额缓存 + 限定 Auto-Combo 候选范围** — 重启后配额缓存为空，因此已知已耗尽的连接在重新查询前看起来是健康的；`isAccountQuotaExhausted` 现在从持久化的 `quota_snapshots` 中延迟加载。Auto-Combo 候选扩展也限定为每个 Combo 目标实际允许的连接，而不是拉入该服务商的所有连接。([#5015](https://github.com/diegosouzapw/OmniRoute/pull/5015) — 感谢 @JxnLexn) +- **fix(resilience): 加固配额截断、Gemini 音频 MIME 和模型锁定冷却** — 存储的配额硬截断值不再从任意字符串强制转换为 `enabled=true`；Gemini 音频输入部分在转发前对其 MIME 类型进行校验/规范化；模型锁定现在遵循配置的 `maxCooldownMs` 上限。([#5093](https://github.com/diegosouzapw/OmniRoute/pull/5093) — 感谢 @KooshaPari) +- **fix(streaming): 加固长时间的 OpenAI 兼容 SSE 流** — 管线末尾阶段结束的错误不再覆盖已记录的流成功状态（`streamCompletionRecorded` 守卫），客户端断开连接最终化为 `499 client_disconnected` 而非污染服务商/账户失败状态，实际上是 SSE 的 JSON 体（错误的 `application/json` content-type）被嗅探并重新流式传输，推理字段（`reasoning`/`reasoning_content` + OpenRouter/Gemini 加密的 `reasoning_details`）通过 JSON-as-SSE 回退得以保留。([#5124](https://github.com/diegosouzapw/OmniRoute/pull/5124) — 感谢 @rdself) +- **fix(usage): 对请求用量日志去重并防抖统计事件** — `saveRequestUsage` 现在防止重复插入（自然键：timestamp + provider + model + connection + api-key + token 计数），补全缺失的 `endpoint`，并仅在实际插入行时才发出 `usageRecorded`；统计 `update`/`pending` 事件突发被折叠为单次防抖通知以减少抖动。([#4940](https://github.com/diegosouzapw/OmniRoute/pull/4940) — 感谢 @nguyenxvotanminh3) +- **fix(sse): 在 Antigravity MITM 处理器中将原生 Gemini 请求体转换为 OpenAI 格式** — `contents` / `systemInstruction` / `generationConfig` / `thinkingConfig` 现在在转发到 `/v1/chat/completions` 之前被翻译为 OpenAI chat-completions 格式，使支持思考的模型（如 `ag/claude-opus-4-6-thinking`）不再因服务商返回 400 "invalid argument" 错误而失败。([#4845](https://github.com/diegosouzapw/OmniRoute/pull/4845) — 感谢 @anuragg-saxenaa) +- **fix(db): 将两条 pt-BR SQLite 驱动回退日志行翻译为英文** — `[DB] Pré-inicializando sql.js WASM…` 和 `[DB] Drivers síncronos indisponíveis…` 是唯一的非英文服务器日志字符串，导致日志中语言混用。现在改为 `[DB] Pre-initializing sql.js WASM (synchronous drivers unavailable)…` / `[DB] Synchronous drivers unavailable — falling back to sql.js (WASM)`，并通过扫描驱动路径中带重音符号的日志字符串的测试来守护。([#5103](https://github.com/diegosouzapw/OmniRoute/issues/5103)) +- **fix(diagnostics): 非流式 Claude 响应不再因 `empty_choices` 而被误判为 502** — v3.8.37 的畸形 200 检测器（#4942）仅理解 OpenAI `choices` 和 Responses-API `output` 形状，因此保持 Claude 形状（`{type:"message", content:[…]}`）的 `/v1/messages` 响应落入 `empty_choices` → 502（在 Combo 中级联为 "All models failed"）。最明显的是，扩展思考轮次中缓冲体为单个**携带有效 `signature` 的空思考块**（Claude Code 的非流式 Bash 分类器）在每次调用时都返回 502。`detectMalformedNonStream` 现在理解 Claude 形状：text/tool_use 块和携带签名的思考块计为有效输出，而真正空的 `content:[]` 仍被标记。([#5108](https://github.com/diegosouzapw/OmniRoute/issues/5108)，感谢 @insoln) +- **fix(combo): 空内容 502 现在在同一请求内容灾，而不是耗尽服务商** — 返回 HTTP 200 但无可用于完成正文的分支被重写为 `502 "Provider returned empty content"`，但 Combo 耗尽分类器将该合成 502 视为连接级故障（`#1731v2`）并将整个服务商/连接标记为已耗尽，跳过该请求中所有剩余的**同服务商**分支。连接实际上是健康的（只是返回了空内容），因此空内容 502 现在被分类为模型级瞬态故障：请求推进到下一个分支，该服务商其余分支仍保持可选。真正的网关 502 仍然触发连接耗尽。([#5085](https://github.com/diegosouzapw/OmniRoute/issues/5085)，感谢 @andrea-kingautomation) +- **fix(dashboard): 展示详细的凭证校验错误，而非仅仅显示"invalid"徽章** — 添加连接模态框中的内联"检查"丢弃了 `/api/providers/validate` 返回的 `error` 消息，只显示一个 `invalid` 徽章。对于 Web 服务商（claude-web / chatgpt-web），真正的原因往往是后端已报告的环境错误（如 `TLS impersonation client failed to start: EACCES … mkdir tls-client-node/bin`），因此用户只能猜测。模态框现在在徽章旁边渲染完整的原因文本。([#5088](https://github.com/diegosouzapw/OmniRoute/issues/5088)，感谢 @tkhs101) +- **fix(executors): 从转发给 Cerebras 和 Mistral 的请求体中剥离 `client_metadata`** — 当透传请求体包含 `client_metadata`（OpenAI Codex / Claude CLI 字段，这些上游无对应项）时，Cerebras 返回 400（`wrong_api_format`），Mistral 返回 422（`extra_forbidden`）。默认执行器现在在向下游发送前为这两个服务商移除该字段；其他服务商（特别是 `openai`/`codex`）保留它。（感谢 @saurabh321gupta） +- **fix(codebuddy):** 仅在客户端请求推理时才发送推理参数。（感谢 @anki1kr） +- **fix(sse):** 当 JSON 客户端请求时，为强制流式传输服务商保持流式传输。被标记为 `forceStream:true` 的服务商拒绝 `stream:false` 上游（HTTP 400）；`resolveStreamFlag` 现在对此进行防护，使仅支持流式的服务商即使在客户端发送 `Accept: application/json` 或 `stream:false` 时也保持流式传输。（感谢 @anki1kr） +- **fix(sse):** 防止非 JSON SSE 行和重复 `[DONE]` 破坏客户端。（感谢 @qianze0628） +- **fix(sse):** 在执行器 `buildHeaders` 路径中对大小写变体的 Anthropic 头去重 — Node/undici 的 `fetch` 将 `anthropic-version` 和 `Anthropic-Version` 合并为单个 `"v, v"` 值，Anthropic API 会拒绝该值，因此两种大小写变体现在折叠为一个规范的小写头（`anthropic-beta` 同理）。（感谢 @Delcado19） +- **oauth(kiro):** 支持 Kiro IDC（组织）Token 导入 — 当 `~/.aws/sso/cache` Token 携带 `clientIdHash` 时，自动导入现在读取链接的客户端注册文件以获取 `clientId`/`clientSecret`，探测 Kiro IDE `profile.json` 中的 `profileArn`（ARN 区域规范化为 `us-east-1` 用于运行时网关），并通过区域 AWS OIDC 端点而非社交路径进行刷新；导入 Schema 和模态框转发这些凭证，因此手动导入也适用于 IDC Token。感谢 @enjoyer-hub +- **fix(translator):** 当将 Claude 格式请求（如 Claude Code）路由到阿里云 DashScope 的 OpenAI 兼容服务商（`alibaba` / `alibaba-cn`）时，保留客户端 `cache_control` 断点。Claude→OpenAI 翻译之前从系统和消息文本块中剥离了这些标记，因此 DashScope 的显式缓存从未启用，每次请求都是缓存未命中。现在当为支持缓存能力的 OpenAI 格式服务商请求保留时，缓存提示得以保留。（感谢 @sacrtap） +- **fix(tts):** 从目录中解析 Gemini TTS 模型，并添加 `gemini-3.1-flash-tts-preview` 作为新的默认 Vertex TTS 模型。（感谢 @nguyenha935） +- **fix(sse): 不要在自身上游超时（504）导致健康连接进入冷却** — 当 OmniRoute 自身的截止时间到达时（表现为 `TimeoutError`/`BodyTimeoutError` → 504），连接不再被禁用/容灾切换，因此缓慢但健康的服务商不会因我们的超时而受惩罚。真正的上游 5xx/429 仍触发冷却；Antigravity 保持自己的策略。感谢 @costaeder +- **fix(translator):** 将图像 `tool_result` 块作为 `image_url` 转发，而不是将 base64 字符串化。（感谢 @alican532） +- **fix(sse): 稳健的 Anthropic `/v1/messages` 流式传输——真实 ping 保活 + 客户端断开守卫** — 推理模型缓慢的首个 Token 可能触发严格客户端的空闲读看门狗；该路由现在从第一帧开始以真实的 `event: ping`（Anthropic 客户端忽略 SSE 注释）保持流连接活跃，且客户端断开（AbortError / controller-closed）不再被计为服务商故障（无容灾/冷却）。感谢 @costaeder +- **fix: 在模型同步期间保留模型隐藏标志（`isHidden`）** — `replaceCustomModels` 将兼容覆盖列表修剪为新的自定义模型 ID，在每次定期同步/导入时静默擦除已隐藏的同步模型的 `isHidden` 标志（所有隐藏模型重新变为可见）。移除了冗余清理（每个模型的删除已经处理其自身的兼容清理），因此隐藏模型在重新同步期间保持隐藏。([#5086](https://github.com/diegosouzapw/OmniRoute/pull/5086) — 感谢 @herjarsa) +- **fix(models): 从注册表 `modelsUrl` 推导模型发现配置** — 不在硬编码 `PROVIDER_MODELS_CONFIG` 中但携带注册表 `modelsUrl` 的服务商（如 MiniMax），现在自动获得 Bearer `/v1/models` 发现配置，因此"发现模型"能正常工作而不是返回空。感谢 @herjarsa +- **fix(compression): 通过运行时锚点解析 Worker + 规则/过滤器资源文件（独立打包）** — LLMLingua Worker 和 RTK 规则/过滤器加载器依赖 `fileURLToPath(import.meta.url)`，而独立打包会将其冻结为构建机器路径，因此 Worker 永不启动、规则/过滤器包无法解析。现在基于 `process.cwd()`/`argv[1]` 进行锚定（Worker URL 使用 `pathToFileURL`）。感谢 @fulorgnas +- **fix(api): 对 7 个管理路由的错误响应进行脱敏处理（第 12 号硬规则加固）** — `cli-tools/backups`、`cli-tools/guide-settings/[toolId]`、`logs/export`、`models/catalog`、`providers/test-batch`、`settings/import-json` 和 `usage/proxy-logs` 不再返回原始 `error.message`；它们将捕获的错误包装在 `sanitizeErrorMessage(...)` 中，且这些路由已从 `check-error-helper` 白名单中移除。（感谢 @JxnLexn） +- **fix(sse): 防止仅 `output_text` 的 Responses 正文被丢弃/误判为 502** — 某些上游返回简写的 Responses 正文，其答案仅在 `output_text` 中，`output[]` 为空。`sanitizeResponsesApiResponse` 丢弃了文本，导致响应随后触发了畸形 200 守卫。脱敏器现在从非空 `output_text` 合成一个 `output[]` 消息项（补充 #5108 中的 Claude 原生修复；两者均源自 #4942）。 +- **fix(executors): 保留调用者单一大写的 `Anthropic-Version` 头** — 大小写变体去重（#4846）无条件地将 `Anthropic-Version`/`Anthropic-Beta` 重写为小写，即使只有一个变体存在，破坏了调用者的头部。去重现在仅在两种大小写变体同时存在时运行（该功能原本要修复的 undici-merge 冲突场景）。 +- **fix(responses):** 为 openai-compatible **responses** 服务商默认设置 `text.format` 为 `{ type: "text" }` — 某些 Responses 兼容上游（如 LM Studio）会以 400 `missing_required_parameter` 拒绝缺少 `text.format` 的 `text` 对象；默认执行器现在在转发前填充 Responses-API 默认值（限定于 `openai-compatible-*responses*`，永不覆盖已有格式）。感谢 @StevanusPangau +- **fix(translator): 停止对推理重放服务商剥离客户端提供的 `reasoning_content`** — #4849 的 agentic-context 剥离（从工具调用助手轮次中删除 `reasoning_content` 以避免 O(n²) Token 增长）无条件运行，因此重放服务商（DeepSeek V4、Kimi K2、Qwen-Thinking 等）丢失了客户端的推理，推理重放缓存随后用过期的缓存值覆盖它（此类上游在缺少原始推理时会返回 400）。剥离现在跳过推理重放目标，非推理服务商保持 O(n²) 保护。([#5122](https://github.com/diegosouzapw/OmniRoute/pull/5122)) +- **fix(providers): 将 MiniMax M3 和 Nemotron 3 Ultra 添加到 Cline 目录** — 这两个模型在 Cline 的服务商目录中缺失且无法选择；两者现在已注册。([#5136](https://github.com/diegosouzapw/OmniRoute/pull/5136)，关闭 [#3321](https://github.com/diegosouzapw/OmniRoute/issues/3321)) +- **fix(dashboard): 基于标准 `providerId` 的模型可见性开关** — 每个模型的可见性开关此前基于显示 ID，因此在一个服务商别名上切换模型可能会误操作到另一个；现在基于标准 `providerId`。([#5091](https://github.com/diegosouzapw/OmniRoute/pull/5091) — 感谢 @Theadd) +- **fix(diagnostics): 在 `detectMalformedNonStream` 中识别 Claude API 格式** — 抢救性添加 null 守卫，使 Claude 形状的非流式正文不再被错误分类。([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — 感谢 @herjarsa / @diegosouzapw) +- **fix(logging): 在容灾日志中跟踪最终的连接 ID** — 容灾日志行现在记录实际服务（或最后失败）该请求的连接，而不仅仅是首次尝试。([#5016](https://github.com/diegosouzapw/OmniRoute/pull/5016) — 感谢 @JxnLexn) +- **fix(sse): 在带内流错误处理期间忽略断开竞争** — 与带内上游错误处理竞争的客户端断开连接，不再表现为虚假的服务商故障。([#5007](https://github.com/diegosouzapw/OmniRoute/pull/5007) — 感谢 @JxnLexn) +- **fix(dashboard): 在 `handleToggleCombo` 失败时展示服务端错误** — Combo 切换失败现在显示后端错误，而不是静默无操作。([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — 感谢 @KooshaPari / @diegosouzapw) +- **fix(quota): 跟踪服务商配额重置窗口 + 充实 Codex 工作室** — 观察到的配额重置窗口被跟踪并展示，Codex 工作室获得丰富的配额元数据。([#5141](https://github.com/diegosouzapw/OmniRoute/pull/5141) — 感谢 @Witroch4 / @diegosouzapw) +- **fix(sidebar): 删除孤立的 `settings` 主题色** — 移除一个导致 `typecheck:core` 失败的悬空主题色条目。([#5142](https://github.com/diegosouzapw/OmniRoute/pull/5142)) +- **fix(sse): 为兼容客户端保留非流式推理字段** — 非流式响应现在保留上游推理字段（`reasoning` / `reasoning_content` 和 OpenRouter/Gemini `reasoning_details`），而不是在 `responseSanitizer` 中剥离它们，使渲染缓冲响应推理的客户端不再丢失推理内容。([#5155](https://github.com/diegosouzapw/OmniRoute/pull/5155) — 感谢 @rdself) +- **fix(i18n): 添加缺失的英文 UI 标签** — 补全在仪表盘中以原始键名显示的未翻译英文字符串。([#5153](https://github.com/diegosouzapw/OmniRoute/pull/5153) — 感谢 @rdself) ### 🔒 安全 -- **fix(security): exact-host Anthropic `baseUrl` check** — the Anthropic base-URL guard used a substring match that a crafted host could partially satisfy; it now requires an exact host match (resolves CodeQL `js/incomplete-url-substring-sanitization` alert #674). ([#5130](https://github.com/diegosouzapw/OmniRoute/pull/5130)) +- **fix(security): 精确主机名的 Anthropic `baseUrl` 检查** — Anthropic base-URL 守卫使用了子串匹配，精心构造的主机可以部分满足条件；现在要求精确主机匹配（解决 CodeQL `js/incomplete-url-substring-sanitization` 告警 #674）。([#5130](https://github.com/diegosouzapw/OmniRoute/pull/5130)) ### 📝 维护 -- **refactor(store): remove dead legacy store modules** — salvaged cleanup of unused legacy store code. ([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — thanks @JxnLexn / @diegosouzapw) -- **test(combo): deterministic routing-decision matrix for all 17 strategies** — a deterministic E2E matrix pins the routing decision of every combo strategy. ([#5146](https://github.com/diegosouzapw/OmniRoute/pull/5146)) +- **refactor(store): 移除死代码中的旧版 store 模块** — 抢救性清理未使用的旧版 store 代码。([#5138](https://github.com/diegosouzapw/OmniRoute/pull/5138) — 感谢 @JxnLexn / @diegosouzapw) +- **test(combo): 全部 17 策略的确定性路由决策矩阵** — 确定性 E2E 矩阵固定了每个 Combo 策略的路由决策。([#5146](https://github.com/diegosouzapw/OmniRoute/pull/5146)) - **chore:** baseline reconciliations (complexity / file-size / cognitive), golden-snapshot + apikey-count alignment for new providers, orphan-test relocation, release base-red repairs, CHANGELOG i18n mirror sync, and an `actions/cache` 5→6 bump. ([#5145](https://github.com/diegosouzapw/OmniRoute/pull/5145), [#5144](https://github.com/diegosouzapw/OmniRoute/pull/5144), [#5125](https://github.com/diegosouzapw/OmniRoute/pull/5125), [#5126](https://github.com/diegosouzapw/OmniRoute/pull/5126), [#5120](https://github.com/diegosouzapw/OmniRoute/pull/5120), [#5117](https://github.com/diegosouzapw/OmniRoute/pull/5117), [#5112](https://github.com/diegosouzapw/OmniRoute/pull/5112)) -- **test:** gated live smoke for combo strategies (in-process + VPS HTTP) and refreshed release expectations to match current code. ([#5151](https://github.com/diegosouzapw/OmniRoute/pull/5151), [#5150](https://github.com/diegosouzapw/OmniRoute/pull/5150) — thanks @KooshaPari / @diegosouzapw) +- **test:** 带门控的 Combo 策略实况冒烟测试（进程内 + VPS HTTP）并刷新发布期望以匹配当前代码。([#5151](https://github.com/diegosouzapw/OmniRoute/pull/5151), [#5150](https://github.com/diegosouzapw/OmniRoute/pull/5150) — 感谢 @KooshaPari / @diegosouzapw) --- @@ -278,155 +278,155 @@ _In development — bullets added per PR; finalized at release._ ### ✨ 新功能 -- **feat(providers):** add DGrid AI gateway provider — OpenAI-compatible gateway at `api.dgrid.ai/v1` (alias `dgrid`, API-key auth, passthrough models). Free router tier (10 RPM / 100 RPD); a $5 lifetime top-up raises limits to 20 RPM / 1,000 RPD. ([#4931](https://github.com/diegosouzapw/OmniRoute/pull/4931) — thanks @dgridOP) +- **feat(providers):** 新增 DGrid AI 网关服务商 — OpenAI 兼容网关，位于 `api.dgrid.ai/v1`（别名 `dgrid`，API-key 认证，透传模型）。免费路由层（10 RPM / 100 RPD）；$5 终身充值将限制提升至 20 RPM / 1,000 RPD。([#4931](https://github.com/diegosouzapw/OmniRoute/pull/4931) — 感谢 @dgridOP) -- **feat(providers):** add Pioneer AI (Fastino Labs) provider — OpenAI-compatible chat completions at `api.pioneer.ai/v1`. Registered with alias `pn`, `X-API-Key` auth, and a catalog of 10 open-tier serverless models (Qwen3, Llama 3.1/3.2, Gemma 3, SmolLM3). Free $75 credits, no credit card required. Gated enterprise models (Claude/GPT/Gemini) require prior fine-tuning on the Pioneer platform and are intentionally excluded from the catalog. ([#4909](https://github.com/diegosouzapw/OmniRoute/pull/4909) — thanks @HikiNarou) +- **feat(providers):** 新增 Pioneer AI（Fastino Labs）服务商 — OpenAI 兼容的聊天补全，位于 `api.pioneer.ai/v1`。注册别名 `pn`，`X-API-Key` 认证，包含 10 个开放层无服务器模型目录（Qwen3、Llama 3.1/3.2、Gemma 3、SmolLM3）。免费 $75 积分，无需信用卡。企业模型（Claude/GPT/Gemini）需要先在 Pioneer 平台上进行微调，有意排除在目录之外。([#4909](https://github.com/diegosouzapw/OmniRoute/pull/4909) — 感谢 @HikiNarou) -- **feat(providers):** add xAI Grok inbound translators and a thinking patcher — Grok requests are now translated on the inbound path and reasoning is normalized so Grok modes behave consistently across clients. ([#4910](https://github.com/diegosouzapw/OmniRoute/pull/4910) — thanks @mugnimaestra) +- **feat(providers):** 新增 xAI Grok 入站翻译器和思考修补器 — Grok 请求现在在入站路径上被翻译，推理被规范化，使 Grok 模式在不同客户端间行为一致。([#4910](https://github.com/diegosouzapw/OmniRoute/pull/4910) — 感谢 @mugnimaestra) -- **feat(oauth):** Codex bulk-import endpoint — `POST /api/oauth/codex/import` accepts multiple Codex OAuth credentials in one call for fast multi-account onboarding. ([#4914](https://github.com/diegosouzapw/OmniRoute/pull/4914) — thanks @beaaan) +- **feat(oauth):** Codex 批量导入端点 — `POST /api/oauth/codex/import` 接受一次调用多个 Codex OAuth 凭证，实现快速多账户接入。([#4914](https://github.com/diegosouzapw/OmniRoute/pull/4914) — 感谢 @beaaan) -- **feat(embeddings):** add a `dimensions` override field to embedding combos so an embedding combo can pin the output vector size per target. ([#4913](https://github.com/diegosouzapw/OmniRoute/pull/4913) — thanks @wenzetan) +- **feat(embeddings):** 为嵌入 Combo 添加 `dimensions` 覆盖字段，使嵌入 Combo 可以按目标固定输出向量大小。([#4913](https://github.com/diegosouzapw/OmniRoute/pull/4913) — 感谢 @wenzetan) -- **feat(sse):** auto-promote successful combo model — a new opt-in `comboAutoPromoteEnabled` setting reorders a combo's persisted model list so that, when a combo model responds successfully, it is moved to position #1 for future requests. ([#4852](https://github.com/diegosouzapw/OmniRoute/pull/4852) — thanks @arssnndr) +- **feat(sse):** 成功 Combo 模型自动提升 — 新的可选 `comboAutoPromoteEnabled` 设置重新排序 Combo 持久化的模型列表，当 Combo 模型成功响应时，它会被移到未来请求的第 #1 位置。([#4852](https://github.com/diegosouzapw/OmniRoute/pull/4852) — 感谢 @arssnndr) -- **feat(sse):** add toggleable tool-source diagnostics — an opt-in switch surfaces where each tool definition originated when debugging tool-routing issues. ([#4856](https://github.com/diegosouzapw/OmniRoute/pull/4856) — thanks @DuyPrX) +- **feat(sse):** 添加可切换的工具来源诊断 — 可选开关在调试工具路由问题时显示每个工具定义的来源。([#4856](https://github.com/diegosouzapw/OmniRoute/pull/4856) — 感谢 @DuyPrX) -- **feat(headroom):** proxy lifecycle management + dashboard UI — start/stop/monitor a Headroom compression proxy from the dashboard, with Docker sidecar support. ([#4649](https://github.com/diegosouzapw/OmniRoute/pull/4649) — thanks @diegosouzapw / @carmelogunsroses) +- **feat(headroom):** 代理生命周期管理 + 仪表盘 UI — 从仪表盘启动/停止/监控 Headroom 压缩代理，支持 Docker sidecar。([#4649](https://github.com/diegosouzapw/OmniRoute/pull/4649) — 感谢 @diegosouzapw / @carmelogunsroses) -- **feat(sse):** `x-omniroute-strip-reasoning` request header to drop `reasoning_content` from upstream responses (opt-in, preserving reasoning-aware clients). ([#4678](https://github.com/diegosouzapw/OmniRoute/pull/4678) — thanks @anuragg-saxenaa / @diegosouzapw) +- **feat(sse):** `x-omniroute-strip-reasoning` 请求头用于忽略上游响应中的 `reasoning_content`（可选，保留推理感知客户端）。([#4678](https://github.com/diegosouzapw/OmniRoute/pull/4678) — 感谢 @anuragg-saxenaa / @diegosouzapw) -- **feat(cli):** multi-model support for the Factory Droid CLI integration. ([#4682](https://github.com/diegosouzapw/OmniRoute/pull/4682) — thanks @anuragg-saxenaa / @diegosouzapw) +- **feat(cli):** Factory Droid CLI 集成的多模型支持。([#4682](https://github.com/diegosouzapw/OmniRoute/pull/4682) — 感谢 @anuragg-saxenaa / @diegosouzapw) -- **feat(sse):** parse Gemini CLI 429 `retryDelay` from the structured `RetryInfo` payload so cooldowns honor the upstream-provided backoff. ([#4738](https://github.com/diegosouzapw/OmniRoute/pull/4738) — thanks @NoxzRCW) +- **feat(sse):** 从结构化 `RetryInfo` 载荷解析 Gemini CLI 429 `retryDelay`，使冷却遵循上游提供的退避时间。([#4738](https://github.com/diegosouzapw/OmniRoute/pull/4738) — 感谢 @NoxzRCW) -- **feat(sse):** add GPT-4 and GPT-4o mini to the GitHub Copilot provider catalog. ([#4798](https://github.com/diegosouzapw/OmniRoute/pull/4798), [#4797](https://github.com/diegosouzapw/OmniRoute/pull/4797) — thanks @decolua) +- **feat(sse):** 将 GPT-4 和 GPT-4o mini 添加到 GitHub Copilot 服务商目录。([#4798](https://github.com/diegosouzapw/OmniRoute/pull/4798), [#4797](https://github.com/diegosouzapw/OmniRoute/pull/4797) — 感谢 @decolua) -- **feat(api):** add the `MiniMax-M3` pricing row (canonical + lowercase alias) so the new MiniMax default model gets accurate per-request cost accounting instead of falling back to a zero/default rate. ([#4814](https://github.com/diegosouzapw/OmniRoute/pull/4814) — thanks @octo-patch) +- **feat(api):** 添加 `MiniMax-M3` 定价行（标准名称 + 小写别名），使新的 MiniMax 默认模型获得准确的每次请求成本核算，而非回退到零/默认费率。([#4814](https://github.com/diegosouzapw/OmniRoute/pull/4814) — 感谢 @octo-patch) ### 🔧 问题修复 -- **fix(sse):** dense, deterministic `response.output` ordering in `response.completed` — items are now sorted by their actual `output_index` (via a recorded-as-emitted accumulator + stable sort) instead of being rebuilt from unordered state dicts; `normalizeOutputIndex` replaces fragile `parseInt` calls for robust index coercion; superseded tool calls (replaced at the same index mid-stream) are excluded from the final output array. ([#4906](https://github.com/diegosouzapw/OmniRoute/pull/4906) — thanks @Marco9113) +- **fix(sse):** `response.completed` 中稠密、确定性的 `response.output` 排序 — 项目现在按其实际 `output_index` 排序（通过记录已发出的累加器 + 稳定排序），而不是从无序状态字典重建；`normalizeOutputIndex` 替换了脆弱的 `parseInt` 调用以实现稳健的索引转换；流中同一索引被替换的工具调用被排除在最终输出数组之外。([#4906](https://github.com/diegosouzapw/OmniRoute/pull/4906) — 感谢 @Marco9113) -- **fix(sse):** normalize Codex custom/freeform tools (`apply_patch`, `type:"custom"` with no `parameters`) to a `{ input: string }` function schema instead of an empty schema — the empty schema made models invoke `apply_patch` with `{}`, breaking the Codex runtime which expects `{ input: string }`. Also maps `custom_tool_call` / `custom_tool_call_output` input items and streams `apply_patch` tool calls via `custom_tool_call_input.delta`/`.done` events. ([#4862](https://github.com/diegosouzapw/OmniRoute/pull/4862) — thanks @nstung463) +- **fix(sse):** 将 Codex 自定义/自由格式工具（`apply_patch`、无 `parameters` 的 `type:"custom"`）规范化为 `{ input: string }` 函数 Schema 而非空 Schema — 空 Schema 使模型使用 `{}` 调用 `apply_patch`，破坏了期望 `{ input: string }` 的 Codex 运行时。还将 `custom_tool_call` / `custom_tool_call_output` 输入项映射，并通过 `custom_tool_call_input.delta`/`.done` 事件流式传输 `apply_patch` 工具调用。([#4862](https://github.com/diegosouzapw/OmniRoute/pull/4862) — 感谢 @nstung463) -- **fix(sse):** preserve the `required` array when translating Draft 2020-12 antigravity tool schemas (e.g. from OpenCode), stripping unsupported JSON Schema meta keywords while keeping mandatory arguments required so the model no longer calls tools without them. ([#4843](https://github.com/diegosouzapw/OmniRoute/pull/4843) — thanks @anuragg-saxenaa) +- **fix(sse):** 在翻译 Draft 2020-12 Antigravity 工具 Schema（如来自 OpenCode）时保留 `required` 数组，剥离不受支持的 JSON Schema 元关键词，同时保留必需参数使模型不再在调用工具时不带必需参数。([#4843](https://github.com/diegosouzapw/OmniRoute/pull/4843) — 感谢 @anuragg-saxenaa) -- **fix(sse):** Kiro tool-schema sanitizer — strip unsupported JSON-Schema keywords (`anyOf`/`$ref`/`if`-`then`, etc.) and hash-truncate tool names >64 chars before dispatch, mapping the streamed tool-call name back for the client, so Kiro no longer rejects tool calls with `400 "Improperly formed request"`. ([#4847](https://github.com/diegosouzapw/OmniRoute/pull/4847) — thanks @smarthomeblack) +- **fix(sse):** Kiro 工具 Schema 脱敏器 — 在调度前剥离不受支持的 JSON Schema 关键词（`anyOf`/`$ref`/`if`-`then` 等），并将超 64 字符的工具名哈希截断，将流式工具调用名映射回客户端，使 Kiro 不再以 `400 "Improperly formed request"` 拒绝工具调用。([#4847](https://github.com/diegosouzapw/OmniRoute/pull/4847) — 感谢 @smarthomeblack) -- **fix(sse):** make the `anthropic-version` default-guard case-insensitive for `anthropic-compatible-*` providers, so a caller/operator-supplied `Anthropic-Version` (any casing) is no longer clobbered by a second lowercase `anthropic-version: 2023-06-01` header. ([#4823](https://github.com/diegosouzapw/OmniRoute/pull/4823) — thanks @zakirkun) +- **fix(sse):** 使 `anthropic-compatible-*` 服务商的 `anthropic-version` 默认守卫不���分大小写，使调用者/运维人员提供的 `Anthropic-Version`（任意大小写）不再被第二个小写的 `anthropic-version: 2023-06-01` 头覆盖。([#4823](https://github.com/diegosouzapw/OmniRoute/pull/4823) — 感谢 @zakirkun) -- **fix(db):** validate HuggingFace API tokens via the `whoami-v2` endpoint as a pure auth probe so fine-grained Inference-Provider tokens (valid even when model/task endpoints reject them) are no longer falsely marked invalid; only 401/403 means an invalid key, other non-OK statuses surface as transient upstream errors. ([#4819](https://github.com/diegosouzapw/OmniRoute/pull/4819) — thanks @Delcado19) +- **fix(db):** 通过 `whoami-v2` 端点作为纯认证探针校验 HuggingFace API Token，使细粒度 Inference-Provider Token（即使模型/任务端点拒绝它们也有效）不再被错误标记为无效；仅 401/403 表示无效密钥，其他非 OK 状态表现为瞬态上游错误。([#4819](https://github.com/diegosouzapw/OmniRoute/pull/4819) — 感谢 @Delcado19) -- **fix(sse):** reject the Anthropic-only `[1m]` context-1m suffix in `buildKiroPayload` before it reaches AWS Bedrock — Kiro is Bedrock-backed and cannot honor the beta, so a forwarded `kr/*[1m]` model id was malformed upstream; callers now get a clear error pointing them at a direct-Anthropic provider for 1M-context routing. ([#4816](https://github.com/diegosouzapw/OmniRoute/pull/4816) — thanks @Delcado19) +- **fix(sse):** 在 `buildKiroPayload` 中拒绝仅 Anthropic 的 `[1m]` context-1m 后缀，在其到达 AWS Bedrock 之前阻止 — Kiro 由 Bedrock 支持且无法使用该 beta 功能，因此转发的 `kr/*[1m]` 模型 ID 在上游格式错误；调用者现在获得明确的错误，引导其使用直接 Anthropic 服务商进行 1M 上下文路由。([#4816](https://github.com/diegosouzapw/OmniRoute/pull/4816) — 感谢 @Delcado19) -- **fix(dashboard):** align the Engine Combos editor engines with the API schema — the named-combos pipeline dropdown offered four engines (`headroom`, `session-dedup`, `ccr`, `llmlingua`) that `PUT /api/context/combos/[id]` rejects, so selecting one made the save return 400 while the UI swallowed the error. The dropdown is now sourced from a single canonical engine map shared with `stackedPipelineStepSchema` (parity guarded by a unit test), and the editor surfaces save errors plus empty-name/empty-pipeline validation instead of failing quietly. ([#5062](https://github.com/diegosouzapw/OmniRoute/pull/5062) — closes #4955) +- **fix(dashboard): 使引擎 Combo 编辑器引擎与 API Schema 对齐** — 命名 Combo 管线下拉菜单提供了四个引擎（`headroom`、`session-dedup`、`ccr`、`llmlingua`），而 `PUT /api/context/combos/[id]` 会拒绝它们，因此选择一个会导致保存返回 400，同时 UI 静默吞噬了错误。下拉菜单现在从与 `stackedPipelineStepSchema` 共享的单一标准引擎映射中获取数据（由单元测试守护一致性），编辑器展示保存错误及空名称/空管线校验，而不是静默失败。([#5062](https://github.com/diegosouzapw/OmniRoute/pull/5062) — 关闭 #4955) -- **fix(sse):** surface malformed HTTP-200 upstream responses instead of treating them as success, so combo fallback can trigger. ([#4942](https://github.com/diegosouzapw/OmniRoute/pull/4942) — thanks @haipham22) +- **fix(sse):** 将畸形的 HTTP-200 上游响应展示为错误而非视为成功，使 Combo 容灾可以触发。([#4942](https://github.com/diegosouzapw/OmniRoute/pull/4942) — 感谢 @haipham22) -- **fix(antigravity):** retry transient upstream failures rather than failing the request outright. ([#4941](https://github.com/diegosouzapw/OmniRoute/pull/4941) — thanks @Jordannst) +- **fix(antigravity):** 对瞬态上游故障进行重试，而非直接使请求失败。([#4941](https://github.com/diegosouzapw/OmniRoute/pull/4941) — 感谢 @Jordannst) -- **fix(sse):** exclude WS-bridge controller-closed errors from the provider circuit breaker so a client disconnect no longer trips the whole provider. ([#4870](https://github.com/diegosouzapw/OmniRoute/pull/4870) — closes #4602, thanks @huohua-dev) +- **fix(sse):** 将 WS 桥接控制器关闭错误排除在服务商熔断器之外，使客户端断开连接不再触发整个服务商。([#4870](https://github.com/diegosouzapw/OmniRoute/pull/4870) — 关闭 #4602，感谢 @huohua-dev) -- **fix(sse):** resolve custom combos by id and case-insensitive name. ([#4869](https://github.com/diegosouzapw/OmniRoute/pull/4869) — closes #4446, thanks @herjarsa) +- **fix(sse):** 通过 ID 和不区分大小写的名称解析自定义 Combo。([#4869](https://github.com/diegosouzapw/OmniRoute/pull/4869) — 关闭 #4446，感谢 @herjarsa) -- **fix(sse):** forward AI SDK image parts in the Responses translator. ([#4859](https://github.com/diegosouzapw/OmniRoute/pull/4859) — thanks @mugnimaestra) +- **fix(sse):** 在 Responses 翻译器中转发 AI SDK 图像部分。([#4859](https://github.com/diegosouzapw/OmniRoute/pull/4859) — 感谢 @mugnimaestra) -- **fix(sse):** emit valid concatenable Kiro `tool_calls.arguments` deltas. ([#4855](https://github.com/diegosouzapw/OmniRoute/pull/4855) — thanks @wahyuzero) +- **fix(sse):** 发出有效可拼接的 Kiro `tool_calls.arguments` delta。([#4855](https://github.com/diegosouzapw/OmniRoute/pull/4855) — 感谢 @wahyuzero) -- **fix(sse):** strip `temperature` for Claude models with extended thinking enabled (the upstream rejects it). ([#4853](https://github.com/diegosouzapw/OmniRoute/pull/4853) — thanks @noestelar) +- **fix(sse):** 对启用扩展思考的 Claude 模型剥离 `temperature`（上游会拒绝它）。([#4853](https://github.com/diegosouzapw/OmniRoute/pull/4853) — 感谢 @noestelar) -- **fix(sse):** unwrap the Qoder HTTP-200 SSE error envelope so combo fallback can trigger. ([#4850](https://github.com/diegosouzapw/OmniRoute/pull/4850) — thanks @vianlearns) +- **fix(sse):** 解开 Qoder HTTP-200 SSE 错误信封，使 Combo 容灾可以触发。([#4850](https://github.com/diegosouzapw/OmniRoute/pull/4850) — 感谢 @vianlearns) -- **fix(sse):** strip reasoning blobs from agentic context to prevent O(n²) token growth across multi-turn agent loops. ([#4849](https://github.com/diegosouzapw/OmniRoute/pull/4849) — thanks @GodrezJr2) +- **fix(sse):** 从 agentic 上下文中剥离推理块，防止跨多轮代理循环的 O(n²) Token 增长。([#4849](https://github.com/diegosouzapw/OmniRoute/pull/4849) — 感谢 @GodrezJr2) -- **fix(sse):** close the reasoning block before message content in the Responses stream so clients render reasoning and answer in the right order. ([#4848](https://github.com/diegosouzapw/OmniRoute/pull/4848) — thanks @kwanLeeFrmVi) +- **fix(sse):** 在 Responses 流中消息内容之前关闭推理块，使客户端按正确顺序渲染推理和回答。([#4848](https://github.com/diegosouzapw/OmniRoute/pull/4848) — 感谢 @kwanLeeFrmVi) -- **fix(config):** sync the full SiliconFlow model list into the registry. ([#4844](https://github.com/diegosouzapw/OmniRoute/pull/4844) — thanks @letanphuc) +- **fix(config):** 将完整的 SiliconFlow 模型列表同步到注册表。([#4844](https://github.com/diegosouzapw/OmniRoute/pull/4844) — 感谢 @letanphuc) -- **fix(sse):** strip Composer `<｜final｜>` sentinel markers that leaked after Composer reasoning. ([#4842](https://github.com/diegosouzapw/OmniRoute/pull/4842) — thanks @noestelar) +- **fix(sse):** 剥离 Composer `<｜final｜>` 哨兵标记，该标记在 Composer 推理后泄漏。([#4842](https://github.com/diegosouzapw/OmniRoute/pull/4842) — 感谢 @noestelar) -- **fix(build):** trace-include `sql.js`'s `sql-wasm.wasm` in the standalone bundle so SQLite-WASM works in the packaged build. ([#4839](https://github.com/diegosouzapw/OmniRoute/pull/4839) — thanks @Delcado19) +- **fix(build):** 在独立打包中追踪包含 `sql.js` 的 `sql-wasm.wasm`，使 SQLite-WASM 在打包构建中正常工作。([#4839](https://github.com/diegosouzapw/OmniRoute/pull/4839) — 感谢 @Delcado19) -- **fix(cli):** persist lazily-installed native runtime deps (`better-sqlite3`, `systray2`) to the shared runtime `package.json` with `--save-exact` instead of `--no-save`, so installing one no longer prunes the other as "extraneous" — fixing a "No SQLite driver available" failure after a `--tray` install. ([#4841](https://github.com/diegosouzapw/OmniRoute/pull/4841) — thanks @omartuhintvs) +- **fix(cli):** 将延迟安装的原生运行时依赖（`better-sqlite3`、`systray2`）以 `--save-exact` 而非 `--no-save` 持久化到共享运行时 `package.json`，因此安装一个不再将另一个修剪为"extraneous"——修复了 `--tray` 安装后的 "No SQLite driver available" 故障。([#4841](https://github.com/diegosouzapw/OmniRoute/pull/4841) — 感谢 @omartuhintvs) -- **fix(sse):** resolve bare model names to a connection's `defaultModel` before upstream calls. ([#4825](https://github.com/diegosouzapw/OmniRoute/pull/4825) — thanks @anuragg-saxenaa) +- **fix(sse):** 在上游调用前将裸模型名解析为连接的 `defaultModel`。([#4825](https://github.com/diegosouzapw/OmniRoute/pull/4825) — 感谢 @anuragg-saxenaa) -- **fix(api):** surface a Docker-localhost hint on provider-node validation connection errors. ([#4822](https://github.com/diegosouzapw/OmniRoute/pull/4822) — thanks @anuragg-saxenaa) +- **fix(api):** 在服务商节点校验连接错误时展示 Docker localhost 提示。([#4822](https://github.com/diegosouzapw/OmniRoute/pull/4822) — 感谢 @anuragg-saxenaa) -- **fix(sse):** strip Gemini built-in tools when `functionDeclarations` are present in the Antigravity envelope (the two are mutually exclusive upstream). ([#4821](https://github.com/diegosouzapw/OmniRoute/pull/4821) — thanks @vanszs) +- **fix(sse):** 当 Antigravity 信封中存在 `functionDeclarations` 时剥离 Gemini 内置工具（两者在上游互斥）。([#4821](https://github.com/diegosouzapw/OmniRoute/pull/4821) — 感谢 @vanszs) -- **fix(sse):** strip `X-Stainless-*` headers and normalize the SDK `User-Agent` for OpenAI-compatible endpoints. ([#4820](https://github.com/diegosouzapw/OmniRoute/pull/4820) — thanks @anuragg-saxenaa) +- **fix(sse):** 剥离 `X-Stainless-*` 头并规范化 OpenAI 兼容端点的 SDK `User-Agent`。([#4820](https://github.com/diegosouzapw/OmniRoute/pull/4820) — 感谢 @anuragg-saxenaa) -- **fix(oauth):** allow a per-connection refresh lead-time override via `providerSpecificData.refreshLeadMs`. ([#4818](https://github.com/diegosouzapw/OmniRoute/pull/4818) — thanks @anuragg-saxenaa) +- **fix(oauth):** 允许通过 `providerSpecificData.refreshLeadMs` 进行每个连接的刷新提前量覆盖。([#4818](https://github.com/diegosouzapw/OmniRoute/pull/4818) — 感谢 @anuragg-saxenaa) -- **fix(dashboard):** resolve passthrough model aliases by `providerId` in `ModelSelectModal`. ([#4815](https://github.com/diegosouzapw/OmniRoute/pull/4815) — thanks @anuragg-saxenaa) +- **fix(dashboard): 在 `ModelSelectModal` 中通过 `providerId` 解析透传模型别名。([#4815](https://github.com/diegosouzapw/OmniRoute/pull/4815) — 感谢 @anuragg-saxenaa) -- **fix(sse):** strip `enumDescriptions` from Antigravity tool schemas. ([#4813](https://github.com/diegosouzapw/OmniRoute/pull/4813), [#4740](https://github.com/diegosouzapw/OmniRoute/pull/4740) — thanks @anuragg-saxenaa) +- **fix(sse):** 从 Antigravity 工具 Schema 中剥离 `enumDescriptions`。([#4813](https://github.com/diegosouzapw/OmniRoute/pull/4813), [#4740](https://github.com/diegosouzapw/OmniRoute/pull/4740) — 感谢 @anuragg-saxenaa) -- **fix(dashboard):** keep the desktop sidebar visible via an explicit CSS class. ([#4812](https://github.com/diegosouzapw/OmniRoute/pull/4812) — thanks @Delcado19) +- **fix(dashboard): 通过显式 CSS 类保持桌面侧边栏可见。([#4812](https://github.com/diegosouzapw/OmniRoute/pull/4812) — 感谢 @Delcado19) -- **fix(sse):** filter nameless hosted tools when converting Responses API to Chat format. ([#4789](https://github.com/diegosouzapw/OmniRoute/pull/4789) — upstream, thanks Владимир Акимов) +- **fix(sse):** 在将 Responses API 转换为聊天格式时过滤无名托管工具。([#4789](https://github.com/diegosouzapw/OmniRoute/pull/4789) — 上游，感谢 Владимир Акимов) -- **fix(sse):** stream-writer mock `abort()` now returns a Promise (test-stability fix). ([#4788](https://github.com/diegosouzapw/OmniRoute/pull/4788) — thanks @decolua) +- **fix(sse):** 流写入器 mock 的 `abort()` 现在返回 Promise（测试稳定性修复）。([#4788](https://github.com/diegosouzapw/OmniRoute/pull/4788) — 感谢 @decolua) -- **fix(sse):** use the WorkOS auth-token shape for Cline. ([#4787](https://github.com/diegosouzapw/OmniRoute/pull/4787) — thanks @apeltekci) +- **fix(sse):** 为 Cline 使用 WorkOS 认证 Token 形状。([#4787](https://github.com/diegosouzapw/OmniRoute/pull/4787) — 感谢 @apeltekci) -- **fix(api):** fall back to the existing access token for any OAuth provider when a refresh fails. ([#4786](https://github.com/diegosouzapw/OmniRoute/pull/4786) — thanks @decolua) +- **fix(api):** 当刷新失败时，为任何 OAuth 服务商回退到现有访问 Token。([#4786](https://github.com/diegosouzapw/OmniRoute/pull/4786) — 感谢 @decolua) -- **fix(sse):** read Antigravity usage from the `response.usageMetadata` envelope. ([#4785](https://github.com/diegosouzapw/OmniRoute/pull/4785) — thanks @decolua) +- **fix(sse):** 从 `response.usageMetadata` 信封中读取 Antigravity 用量。([#4785](https://github.com/diegosouzapw/OmniRoute/pull/4785) — 感谢 @decolua) -- **fix(oauth):** verify Cursor installation on Linux before auto-import. ([#4770](https://github.com/diegosouzapw/OmniRoute/pull/4770) — upstream, thanks Ibrahim Ryan) +- **fix(oauth):** 在自动导入前验证 Linux 上的 Cursor 安装。([#4770](https://github.com/diegosouzapw/OmniRoute/pull/4770) — 上游，感谢 Ibrahim Ryan) -- **fix(cli):** fall back to the default data dir when `DATA_DIR` is not writable. ([#4767](https://github.com/diegosouzapw/OmniRoute/pull/4767) — upstream, thanks Thiên Toán) +- **fix(cli):** 当 `DATA_DIR` 不可写时回退到默认数据目录。([#4767](https://github.com/diegosouzapw/OmniRoute/pull/4767) — 上游，感谢 Thiên Toán) -- **fix(sse):** `json_schema` fallback for OpenAI-compatible providers that don't support structured outputs. ([#4766](https://github.com/diegosouzapw/OmniRoute/pull/4766) — thanks @mustafabozkaya) +- **fix(sse):** 为不支持结构化输出的 OpenAI 兼容服务商提供 `json_schema` 回退。([#4766](https://github.com/diegosouzapw/OmniRoute/pull/4766) — 感谢 @mustafabozkaya) -- **fix(cli):** verify launchd registration and skip self-SIGTERM in macOS autostart. ([#4765](https://github.com/diegosouzapw/OmniRoute/pull/4765) — thanks @ntdung6868) +- **fix(cli):** 在 macOS 自启动中验证 launchd 注册并跳过自身 SIGTERM。([#4765](https://github.com/diegosouzapw/OmniRoute/pull/4765) — 感谢 @ntdung6868) -- **fix(sse):** finalize the `tool_calls` `finish_reason` on early stream end in the OpenAI Responses translator. ([#4764](https://github.com/diegosouzapw/OmniRoute/pull/4764) — thanks @decolua) +- **fix(sse):** 在 OpenAI Responses 翻译器中，早期流结束时完成 `tool_calls` 的 `finish_reason`。([#4764](https://github.com/diegosouzapw/OmniRoute/pull/4764) — 感谢 @decolua) -- **fix(sse):** gate Kiro image attachments behind a Claude-capability check. ([#4763](https://github.com/diegosouzapw/OmniRoute/pull/4763) — thanks @decolua) +- **fix(sse):** 在 Claude 能力检查之后才允许 Kiro 图像附件。([#4763](https://github.com/diegosouzapw/OmniRoute/pull/4763) — 感谢 @decolua) -- **fix(sse):** track Ollama streaming usage from raw NDJSON chunks. ([#4754](https://github.com/diegosouzapw/OmniRoute/pull/4754) — thanks @fresent) +- **fix(sse):** 从原始 NDJSON 块跟踪 Ollama 流式用量。([#4754](https://github.com/diegosouzapw/OmniRoute/pull/4754) — 感谢 @fresent) -- **fix(sse):** include low-level cause details in `formatProviderError`. ([#4741](https://github.com/diegosouzapw/OmniRoute/pull/4741) — thanks @decolua) +- **fix(sse):** 在 `formatProviderError` 中包含低级原因详情。([#4741](https://github.com/diegosouzapw/OmniRoute/pull/4741) — 感谢 @decolua) -- **fix(executors):** `anthropic-compatible-*` gateways now get a `Bearer` token alongside `x-api-key`. ([#4729](https://github.com/diegosouzapw/OmniRoute/pull/4729) — thanks @hodtien) +- **fix(executors):** `anthropic-compatible-*` 网关现在在 `x-api-key` 之外同时获得 `Bearer` Token。([#4729](https://github.com/diegosouzapw/OmniRoute/pull/4729) — 感谢 @hodtien) -- **fix(translator):** strip the `x-anthropic-billing-header` in the claude-to-openai path. ([#4728](https://github.com/diegosouzapw/OmniRoute/pull/4728) — thanks @weimaozhen) +- **fix(translator):** 在 claude-to-openai 路径中剥离 `x-anthropic-billing-header`。([#4728](https://github.com/diegosouzapw/OmniRoute/pull/4728) — 感谢 @weimaozhen) -- **fix(translator):** preserve `reasoning_effort` for non-Copilot Responses clients. ([#4688](https://github.com/diegosouzapw/OmniRoute/pull/4688) — thanks @ryanngit / @diegosouzapw) +- **fix(translator):** 为非 Copilot Responses 客户端保留 `reasoning_effort`。([#4688](https://github.com/diegosouzapw/OmniRoute/pull/4688) — 感谢 @ryanngit / @diegosouzapw) -- **fix(codex):** treat an OAuth 401 as an unrecoverable refresh failure (stop retrying a dead token). ([#4686](https://github.com/diegosouzapw/OmniRoute/pull/4686) — thanks @sacwooky / @diegosouzapw) +- **fix(codex):** 将 OAuth 401 视为不可恢复的刷新失败（停止重试已失效的 Token）。([#4686](https://github.com/diegosouzapw/OmniRoute/pull/4686) — 感谢 @sacwooky / @diegosouzapw) -- **fix(translator):** coerce tool descriptions to strings in OpenAI normalization. ([#4675](https://github.com/diegosouzapw/OmniRoute/pull/4675) — thanks @East-rayyy / @diegosouzapw) +- **fix(translator):** 在 OpenAI 规范化中将工具描述强制转换为字符串。([#4675](https://github.com/diegosouzapw/OmniRoute/pull/4675) — 感谢 @East-rayyy / @diegosouzapw) -- **fix(dashboard):** stop double-masking an already-masked API key in the list view (E2E 3/9 regression). ([#4671](https://github.com/diegosouzapw/OmniRoute/pull/4671) — thanks @diegosouzapw) +- **fix(dashboard): 停止在列表视图中对已脱敏的 API Key 进行二次脱敏（E2E 3/9 回归）。([#4671](https://github.com/diegosouzapw/OmniRoute/pull/4671) — 感谢 @diegosouzapw) -- **fix(combo):** flatten Anthropic tool messages + tool history to prevent an upstream 503. ([#4648](https://github.com/diegosouzapw/OmniRoute/pull/4648) — thanks @warelik / @diegosouzapw) +- **fix(combo): 展平 Anthropic 工具消息 + 工具历史以防止上游 503。([#4648](https://github.com/diegosouzapw/OmniRoute/pull/4648) — 感谢 @warelik / @diegosouzapw) -- **fix(providers):** require a Default Model in the compatible-provider API-key setup flow. ([#4641](https://github.com/diegosouzapw/OmniRoute/pull/4641) — thanks @arden1601) +- **fix(providers): 在兼容服务商 API-key 设置流程中要求设置默认模型。([#4641](https://github.com/diegosouzapw/OmniRoute/pull/4641) — 感谢 @arden1601) ### 🔒 安全 -- **fix(auth):** only trust forwarding headers (`X-Forwarded-For` / `X-Real-IP`) from loopback TCP peers, so a non-loopback client can't spoof its origin to bypass local-only route guards. ([#4689](https://github.com/diegosouzapw/OmniRoute/pull/4689) — thanks @Jordannst / @diegosouzapw) +- **fix(auth):** 仅信任来自 loopback TCP 对端的转发头（`X-Forwarded-For` / `X-Real-IP`），使非 loopback 客户端无法伪造来源以绕过仅限本地路由的守卫。([#4689](https://github.com/diegosouzapw/OmniRoute/pull/4689) — 感谢 @Jordannst / @diegosouzapw) -- **fix(sse):** redact the API key from the AUTH debug log in the chat handler. ([#4858](https://github.com/diegosouzapw/OmniRoute/pull/4858) — thanks @sacwooky) +- **fix(sse):** 在聊天处理器的 AUTH 调试日志中脱敏 API Key。([#4858](https://github.com/diegosouzapw/OmniRoute/pull/4858) — 感谢 @sacwooky) -- **fix(oauth):** classify `/api/oauth/cursor/auto-import` as a local-only route in the route guard, so the loopback-enforced process-spawning endpoint can't be reached through a tunneled/leaked JWT (Hard Rule #17). ([#5070](https://github.com/diegosouzapw/OmniRoute/pull/5070) — thanks @diegosouzapw) +- **fix(oauth):** 在路由守卫中将 `/api/oauth/cursor/auto-import` 分类为仅限本地路由，使需要 loopback 执行的进程启动端点无法通过隧道/泄漏的 JWT 访问（第 17 号硬规则）。([#5070](https://github.com/diegosouzapw/OmniRoute/pull/5070) — 感谢 @diegosouzapw) ### 📝 维护 -- **chore(ci):** harden the release flow — decouple the Quality Ratchet from coverage-shard flakes (`if: !cancelled()` + `--allow-missing`), add fast-path drift gates (`check:complexity`, `check:cognitive-complexity`, `check:pack-policy`, `check:build-scope`), and raise the default build heap to 8 GB. ([#5054](https://github.com/diegosouzapw/OmniRoute/pull/5054) — thanks @diegosouzapw) +- **chore(ci):** 加固发布流程 — 将质量递增门禁与覆盖率分片波动解耦（`if: !cancelled()` + `--allow-missing`），添加快速路径偏差门禁（`check:complexity`、`check:cognitive-complexity`、`check:pack-policy`、`check:build-scope`），并将默认构建堆内存提升至 8 GB。([#5054](https://github.com/diegosouzapw/OmniRoute/pull/5054) — 感谢 @diegosouzapw) -- **docs(routing):** sync the combo strategy docs for Fusion (17 strategies). ([#5067](https://github.com/diegosouzapw/OmniRoute/pull/5067) — thanks @diegosouzapw) +- **docs(routing):** 同步 Fusion 的 Combo 策略文档（17 策略）。([#5067](https://github.com/diegosouzapw/OmniRoute/pull/5067) — 感谢 @diegosouzapw) -- **test(sse):** golden-lock the `provider.ts` translate-path across all providers. ([#4734](https://github.com/diegosouzapw/OmniRoute/pull/4734) — thanks @diegosouzapw / @decolua) +- **test(sse):** 全网关锁定所有服务商的 `provider.ts` 翻译路径。([#4734](https://github.com/diegosouzapw/OmniRoute/pull/4734) — 感谢 @diegosouzapw / @decolua) -- **docs(env):** document `HEADROOM_URL` in `.env.example` + `ENVIRONMENT.md`. (thanks @diegosouzapw) +- **docs(env):** 在 `.env.example` + `ENVIRONMENT.md` 中记录 `HEADROOM_URL`。（感谢 @diegosouzapw） -- **chore(quality):** rebaseline the file-size ratchet across the rc17 PR-batch levas (leva2/leva3/leva4) to absorb cycle drift. (thanks @diegosouzapw) +- **chore(quality):** 在 rc17 PR 批次 leva（leva2/leva3/leva4）上重新校准文件大小门禁以吸收周期漂移。（感谢 @diegosouzapw） --- @@ -434,174 +434,174 @@ _In development — bullets added per PR; finalized at release._ ### ✨ 新功能 -**Quota-Share system** +**配额共享系统** -- **feat(quota):** introduce a dedicated `quota-share` combo strategy (Fase 3 #9) — Deficit Round Robin scheduling with per-model in-flight gating (P2C), automatic DB migration that promotes existing `qtSd/*` combos, and per-policy gating so invalid allocations cannot bleed `allow` to unintended connections. ([#4939](https://github.com/diegosouzapw/OmniRoute/pull/4939), [#4901](https://github.com/diegosouzapw/OmniRoute/pull/4901)) -- **feat(quota):** multi-window usage buckets, per-(key,model) caps, and session stickiness — connections now track consumption across 5 h, 7 d, and per-model windows; `quota_allocation_model_caps` enforces per-key/model limits; session stickiness preserves prompt-cache integrity across turns. ([#4928](https://github.com/diegosouzapw/OmniRoute/pull/4928), [#4927](https://github.com/diegosouzapw/OmniRoute/pull/4927), [#4929](https://github.com/diegosouzapw/OmniRoute/pull/4929)) -- **feat(quota):** headroom strategy + proactive saturation — new `headroom` combo strategy selects connections by available quota margin; universal proactive saturation via upstream token-usage response headers; real Claude quota saturation sourced from `/api/oauth/usage`. ([#4908](https://github.com/diegosouzapw/OmniRoute/pull/4908), [#4907](https://github.com/diegosouzapw/OmniRoute/pull/4907), [#4885](https://github.com/diegosouzapw/OmniRoute/pull/4885)) -- **feat(quota):** concurrency control + cooldown-wait (Fase 2.1) — `max_concurrent` is enforced at dispatch time; quota-share combos queue concurrent requests with a short cooldown-wait and re-dispatch on slot availability (Variant A); a cron heal proactively restores connections after their window resets. ([#4965](https://github.com/diegosouzapw/OmniRoute/pull/4965), [#4970](https://github.com/diegosouzapw/OmniRoute/pull/4970), [#4967](https://github.com/diegosouzapw/OmniRoute/pull/4967), [#4900](https://github.com/diegosouzapw/OmniRoute/pull/4900)) +- **feat(quota):** 引入专用的 `quota-share` Combo 策略（Fase 3 #9） — 带每模型飞行门控（P2C）的 Deficit Round Robin 调度、自动数据库迁移以升级现有 `qtSd/*` Combo，以及每策略门控使无效分配不会将 `allow` 泄漏到非目标连接。([#4939](https://github.com/diegosouzapw/OmniRoute/pull/4939), [#4901](https://github.com/diegosouzapw/OmniRoute/pull/4901)) +- **feat(quota):** 多窗口用量桶、每（key,model）上限和会话粘性 — 连接现在跟踪 5 小时、7 天和每模型窗口的消耗；`quota_allocation_model_caps` 强制执行每 key/模型限制；会话粘性在多轮对话中保持提示缓存完整性。([#4928](https://github.com/diegosouzapw/OmniRoute/pull/4928), [#4927](https://github.com/diegosouzapw/OmniRoute/pull/4927), [#4929](https://github.com/diegosouzapw/OmniRoute/pull/4929)) +- **feat(quota):** headroom 策略 + 主动饱和度 — 新的 `headroom` Combo 策略按可用配额余量选择连接；通过上游 Token 用量响应头进行通用主动饱和度计算；从 `/api/oauth/usage` 获取真实的 Claude 配额饱和度。([#4908](https://github.com/diegosouzapw/OmniRoute/pull/4908), [#4907](https://github.com/diegosouzapw/OmniRoute/pull/4907), [#4885](https://github.com/diegosouzapw/OmniRoute/pull/4885)) +- **feat(quota):** 并发控制 + 冷却等待（Fase 2.1） — `max_concurrent` 在调度时强制执行；quota-share Combo 通过短冷却等待对并发请求进行排队，并在槽位可用时重新调度（方案 A）；定时修复任务在窗口重置后主动恢复连接。([#4965](https://github.com/diegosouzapw/OmniRoute/pull/4965), [#4970](https://github.com/diegosouzapw/OmniRoute/pull/4970), [#4967](https://github.com/diegosouzapw/OmniRoute/pull/4967), [#4900](https://github.com/diegosouzapw/OmniRoute/pull/4900)) -**Combo routing** +**Combo 路由** -- **feat(combo):** task-aware routing strategy — routes requests to the best-fit connection based on task-type metadata, enabling per-task provider specialization within a combo. ([#4945](https://github.com/diegosouzapw/OmniRoute/pull/4945)) -- **feat(combo):** Fusion strategy (16th strategy) — fan out to a configurable panel of models in parallel, then synthesize results through a judge model. ([#4652](https://github.com/diegosouzapw/OmniRoute/pull/4652)) -- **feat(combos):** add an editable per-combo `description` field. The routing-combo form now has a Description input, persisted in the combo `data` blob via `/api/combos` (POST/PUT) and round-tripped through GET — no new DB column. ([#5005](https://github.com/diegosouzapw/OmniRoute/issues/5005)) -- **feat(routing):** honor `X-Route-Model` request header to override `body.model`, enabling per-request model switching without modifying the request body. ([#4863](https://github.com/diegosouzapw/OmniRoute/pull/4863) — thanks @costaeder) +- **feat(combo):** 任务感知路由策略 — 根据任务类型元数据将请求路由到最匹配的连接，实现在 Combo 内的每任务服务商专业化。([#4945](https://github.com/diegosouzapw/OmniRoute/pull/4945)) +- **feat(combo):** Fusion 策略（第 16 个策略） — 并行广播到可配置的模型评审团，然后通过裁判模型综合结果。([#4652](https://github.com/diegosouzapw/OmniRoute/pull/4652)) +- **feat(combos):** 添加可编辑的每 Combo `description` 字段。路由 Combo 表单现在有 Description 输入框，通过 `/api/combos`（POST/PUT）持久化在 Combo `data` blob 中，并通过 GET 往返 — 无新增数据库列。([#5005](https://github.com/diegosouzapw/OmniRoute/issues/5005)) +- **feat(routing):** 遵循 `X-Route-Model` 请求头以覆盖 `body.model`，实现在不修改请求体的情况下进行每请求模型切换。([#4863](https://github.com/diegosouzapw/OmniRoute/pull/4863) — 感谢 @costaeder) -**Providers & models** +**服务商与模型** -- **feat(providers):** update volcengine-ark model list, adding DeepSeek-V4-Flash and DeepSeek-V4-Pro. ([#4905](https://github.com/diegosouzapw/OmniRoute/pull/4905) — thanks @kenlin8827) -- **feat(provider):** add CodeBuddy CN (`copilot.tencent.com`) — full OAuth + executor + model catalog stack. ([#4664](https://github.com/diegosouzapw/OmniRoute/pull/4664)) -- **feat(opencode-go):** advertise `glm-5.2` and `kimi-k2.7-code` to align with official Go endpoints. ([#4711](https://github.com/diegosouzapw/OmniRoute/pull/4711)) -- **feat(sse):** add Google Flow video-generation provider. ([#4769](https://github.com/diegosouzapw/OmniRoute/pull/4769)) -- **feat(api/v1):** include alias-backed models in the `/v1/models` listing. ([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630)) +- **feat(providers):** 更新 volcengine-ark 模型列表，新增 DeepSeek-V4-Flash 和 DeepSeek-V4-Pro。([#4905](https://github.com/diegosouzapw/OmniRoute/pull/4905) — 感谢 @kenlin8827) +- **feat(provider):** 新增 CodeBuddy CN（`copilot.tencent.com`）— 完整的 OAuth + 执行器 + 模型目录栈。([#4664](https://github.com/diegosouzapw/OmniRoute/pull/4664)) +- **feat(opencode-go):** 通告 `glm-5.2` 和 `kimi-k2.7-code` 以与官方 Go 端点保持一致。([#4711](https://github.com/diegosouzapw/OmniRoute/pull/4711)) +- **feat(sse):** 新增 Google Flow 视频生成服务商。([#4769](https://github.com/diegosouzapw/OmniRoute/pull/4769)) +- **feat(api/v1):** 在 `/v1/models` 列表中纳入别名支持的模型。([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630)) -**Proxy pool** +**代理池** -- **feat(proxy-pool):** Cloudflare Workers proxy deployer + pool integration — deploy Cloudflare Workers relays directly from the dashboard and register them in the proxy pool. ([#4640](https://github.com/diegosouzapw/OmniRoute/pull/4640)) -- **feat(proxy-pool):** Deno Deploy relays + group action buttons — deploy Deno Deploy relay workers and manage proxy groups with new bulk-action controls. ([#4643](https://github.com/diegosouzapw/OmniRoute/pull/4643)) +- **feat(proxy-pool):** Cloudflare Workers 代理部署器 + 池集成 — 直接从控制台部署 Cloudflare Workers 中继并将其注册到代理池中。([#4640](https://github.com/diegosouzapw/OmniRoute/pull/4640)) +- **feat(proxy-pool):** Deno Deploy 中继 + 分组操作按钮 — 部署 Deno Deploy 中继工作线程，并使用新的批量操作控件管理代理分组。([#4643](https://github.com/diegosouzapw/OmniRoute/pull/4643)) -**Compression & infrastructure** +**压缩与基础设施** -- **feat(compression):** Kiro/CodeWhisperer tool-result compression engine — dedicated compressor for Kiro/CodeWhisperer tool outputs integrated into the streaming pipeline. ([#4635](https://github.com/diegosouzapw/OmniRoute/pull/4635)) -- **feat(endpoint):** per-endpoint custom system prompt injection. A toggle + text field in the Endpoint settings card lets users inject a custom system prompt into every model request, applied via the existing system-prompt engine. Stored in settings DB. ([#5022](https://github.com/diegosouzapw/OmniRoute/pull/5022) — thanks @whale9820) -- **feat(live-ws):** allow non-loopback clients via `LIVE_WS_ALLOWED_HOSTS` env var, enabling multi-host setups to access the live WebSocket API. ([#4877](https://github.com/diegosouzapw/OmniRoute/pull/4877) — thanks @KooshaPari) -- **feat(db):** track API endpoint dimension on `usage_history` for per-endpoint cost and usage analytics. ([#4676](https://github.com/diegosouzapw/OmniRoute/pull/4676)) +- **feat(compression):** Kiro/CodeWhisperer 工具结果压缩引擎 — 专用于 Kiro/CodeWhisperer 工具输出的压缩器，集成到流式传输管线中。([#4635](https://github.com/diegosouzapw/OmniRoute/pull/4635)) +- **feat(endpoint):** 每端点自定义系统提示注入。端点设置卡片中的开关 + 文本字段允许用户将自定义系统提示注入到每个模型请求中，通过现有的系统提示引擎应用。存储在设置数据库中。([#5022](https://github.com/diegosouzapw/OmniRoute/pull/5022) — 感谢 @whale9820) +- **feat(live-ws):** 通过 `LIVE_WS_ALLOWED_HOSTS` 环境变量允许非回环客户端，使多主机部署可以访问实时 WebSocket API。([#4877](https://github.com/diegosouzapw/OmniRoute/pull/4877) — 感谢 @KooshaPari) +- **feat(db):** 在 `usage_history` 上跟踪 API 端点维度，用于每端点成本和用量分析。([#4676](https://github.com/diegosouzapw/OmniRoute/pull/4676)) --- ### 🔧 问题修复 -**Translator** +**翻译器** -- **fix(translator):** regroup parallel tool results to be adjacent to their originating assistant turn, fixing tool-message ordering for providers that require strict interleaving. ([#4882](https://github.com/diegosouzapw/OmniRoute/pull/4882)) -- **fix(translator):** preserve literal empty-string tool arguments in OpenAI-to-Claude streaming — they were previously dropped, causing tool calls to arrive with missing parameters. ([#4959](https://github.com/diegosouzapw/OmniRoute/pull/4959)) -- **fix(translator):** normalize tools to Anthropic-native shape for non-Anthropic providers, ensuring tool definitions pass validation regardless of the format at the call site. ([#4650](https://github.com/diegosouzapw/OmniRoute/pull/4650)) -- **fix(translator):** provider thinking compatibility — correct thinking-block serialization for DeepSeek and Gemini providers. ([#4946](https://github.com/diegosouzapw/OmniRoute/pull/4946)) -- **fix(translator):** emit `` close marker for Anthropic thinking blocks, fixing truncated reasoning output in streamed responses. ([#4633](https://github.com/diegosouzapw/OmniRoute/pull/4633)) -- **fix(translator):** normalize `developer` role to `system` for OpenAI-format providers. ([#4625](https://github.com/diegosouzapw/OmniRoute/pull/4625)) -- **fix(translator):** strip top-level `client_metadata` on the OpenAI passthrough path (port from 9router#1157). ([#4624](https://github.com/diegosouzapw/OmniRoute/pull/4624)) -- **fix(translator):** replay `reasoning_content` on plain Xiaomi MiMo turns (port from 9router#1321). ([#4639](https://github.com/diegosouzapw/OmniRoute/pull/4639)) +- **fix(translator):** 将并行工具结果重新分组到其原始助手轮次附近，修复对需要严格交错排列的服务商的工具消息排序问题。([#4882](https://github.com/diegosouzapw/OmniRoute/pull/4882)) +- **fix(translator):** 在 OpenAI 到 Claude 的流式传输中保留字面空字符串工具参数 — 之前这些参数被丢弃，导致工具调用到达时缺少参数。([#4959](https://github.com/diegosouzapw/OmniRoute/pull/4959)) +- **fix(translator):** 将工具规范化为 Anthropic 原生格式，适用于非 Anthropic 服务商，确保工具定义无论调用点的格式如何都能通过校验。([#4650](https://github.com/diegosouzapw/OmniRoute/pull/4650)) +- **fix(translator):** 服务商思考兼容性 — 修正 DeepSeek 和 Gemini 服务商的思考块序列化。([#4946](https://github.com/diegosouzapw/OmniRoute/pull/4946)) +- **fix(translator):** 为 Anthropic 思考块发出 `` 关闭标记，修复流式响应中推理输出被截断的问题。([#4633](https://github.com/diegosouzapw/OmniRoute/pull/4633)) +- **fix(translator):** 将 `developer` 角色规范化为 `system`，适用于 OpenAI 格式的服务商。([#4625](https://github.com/diegosouzapw/OmniRoute/pull/4625)) +- **fix(translator):** 在 OpenAI 直通路径上剥离顶层 `client_metadata`（从 9router#1157 移植）。([#4624](https://github.com/diegosouzapw/OmniRoute/pull/4624)) +- **fix(translator):** 在纯 Xiaomi MiMo 轮次中重放 `reasoning_content`（从 9router#1321 移植）。([#4639](https://github.com/diegosouzapw/OmniRoute/pull/4639)) -**Copilot / GitHub executor** +**Copilot / GitHub 执行器** -- **fix(copilot):** never route Gemini/Claude model variants to the `/responses` endpoint — these models require the chat-completions path only. ([#4627](https://github.com/diegosouzapw/OmniRoute/pull/4627)) -- **fix(github):** route Copilot Codex models to `/responses` (port from 9router#102). ([#4626](https://github.com/diegosouzapw/OmniRoute/pull/4626)) -- **fix(copilot,antigravity):** cap `maxOutputTokens` at 16384 to stop "Invalid Argument" 400 errors on high-token requests. ([#4636](https://github.com/diegosouzapw/OmniRoute/pull/4636)) -- **fix(codex):** drop non-standard `codex.*` streaming events that break `responses.stream` consumers. ([#4715](https://github.com/diegosouzapw/OmniRoute/pull/4715) — thanks @jeffer1312) +- **fix(copilot):** 永远不要将 Gemini/Claude 模型变体路由到 `/responses` 端点 — 这些模型仅需要 chat-completions 路径。([#4627](https://github.com/diegosouzapw/OmniRoute/pull/4627)) +- **fix(github):** 将 Copilot Codex 模型路由到 `/responses`（从 9router#102 移植）。([#4626](https://github.com/diegosouzapw/OmniRoute/pull/4626)) +- **fix(copilot,antigravity):** 将 `maxOutputTokens` 上限设为 16384，以阻止高令牌请求出现 "Invalid Argument" 400 错误。([#4636](https://github.com/diegosouzapw/OmniRoute/pull/4636)) +- **fix(codex):** 丢弃破坏 `responses.stream` 消费者的非标准 `codex.*` 流式事件。([#4715](https://github.com/diegosouzapw/OmniRoute/pull/4715) — 感谢 @jeffer1312) **Claude / Anthropic** -- **fix(claude):** omit `adaptive_thinking` and `output_config.effort` for Haiku model variants, which reject those parameters. ([#4661](https://github.com/diegosouzapw/OmniRoute/pull/4661)) -- **fix(claude):** skip `mcp__` tool-name cloaking and guard against missing `connectionId` to prevent crashes on Claude-native MCP tool calls. ([#4861](https://github.com/diegosouzapw/OmniRoute/pull/4861) — thanks @costaeder) -- **fix(claude-oauth):** respect `429` backoff headers on the Claude OAuth usage endpoint to reduce polling spam during quota checks. ([#4655](https://github.com/diegosouzapw/OmniRoute/pull/4655)) +- **fix(claude):** 对 Haiku 模型变体省略 `adaptive_thinking` 和 `output_config.effort`，因为这些变体拒绝这些参数。([#4661](https://github.com/diegosouzapw/OmniRoute/pull/4661)) +- **fix(claude):** 跳过 `mcp__` 工具名伪装并防范缺失的 `connectionId`，以防止在 Claude 原生 MCP 工具调用时崩溃。([#4861](https://github.com/diegosouzapw/OmniRoute/pull/4861) — 感谢 @costaeder) +- **fix(claude-oauth):** 在 Claude OAuth 用量端点上遵循 `429` 退避头，以减少配额检查期间的轮询垃圾请求。([#4655](https://github.com/diegosouzapw/OmniRoute/pull/4655)) -**Routing & SSE** +**路由与 SSE** -- **fix(sse):** fail over on `400` responses that carry rate-limit text in the body, not just on canonical `429` status codes. ([#4986](https://github.com/diegosouzapw/OmniRoute/pull/4986)) -- **fix(sse):** honor per-account proxy and fingerprint-rotation settings in the opencode executor. ([#4989](https://github.com/diegosouzapw/OmniRoute/pull/4989)) -- **fix(sse):** soft-penalize exhausted providers in auto-combo scoring instead of hard-excluding them, improving fallback resilience. ([#4990](https://github.com/diegosouzapw/OmniRoute/pull/4990)) -- **fix(sse):** drop the CCP pin when the pinned provider is durably unhealthy, with anti-flap logic to prevent oscillation. ([#4864](https://github.com/diegosouzapw/OmniRoute/pull/4864) — thanks @costaeder) -- **fix(combo):** fetch models dynamically from custom provider endpoints instead of relying on a static list. ([#4860](https://github.com/diegosouzapw/OmniRoute/pull/4860)) -- **fix(combo):** propagate the selected connection ID to fallback error responses so model lockout applies to the correct connection rather than the wrong fallback target. ([#4809](https://github.com/diegosouzapw/OmniRoute/pull/4809) — thanks @Chewji9875) -- **fix(sse):** skip third-party tool-name cloaking for Anthropic-native server tools to prevent naming conflicts. ([#4808](https://github.com/diegosouzapw/OmniRoute/pull/4808) — thanks @NomenAK) +- **fix(sse):** 对携带速率限制文本的 `400` 响应进行容灾切换，而不仅仅是对标准的 `429` 状态码。([#4986](https://github.com/diegosouzapw/OmniRoute/pull/4986)) +- **fix(sse):** 在 opencode 执行器中遵循每账户代理和指纹轮换设置。([#4989](https://github.com/diegosouzapw/OmniRoute/pull/4989)) +- **fix(sse):** 在 auto-combo 评分中对已耗尽的服务商进行软惩罚而非硬排除，改善容灾弹性。([#4990](https://github.com/diegosouzapw/OmniRoute/pull/4990)) +- **fix(sse):** 当被钉选的服务商持续不健康时取消 CCP 钉选，并带有防抖动逻辑以防止振荡。([#4864](https://github.com/diegosouzapw/OmniRoute/pull/4864) — 感谢 @costaeder) +- **fix(combo):** 从自定义服务商端点动态获取模型，而不是依赖静态列表。([#4860](https://github.com/diegosouzapw/OmniRoute/pull/4860)) +- **fix(combo):** 将选定的连接 ID 传播到容灾错误响应，使模型锁定应用于正确的连接而非错误的容灾目标。([#4809](https://github.com/diegosouzapw/OmniRoute/pull/4809) — 感谢 @Chewji9875) +- **fix(sse):** 对 Anthropic 原生服务器工具跳过第三方工具名伪装，以防止命名冲突。([#4808](https://github.com/diegosouzapw/OmniRoute/pull/4808) — 感谢 @NomenAK) -**Quota** +**配额** -- **fix(quota):** quota-exclusive `qtSd/*` connections now appear in `/v1/models` listings; EPSILON-threshold check no longer falsely blocks under-budget allocations. ([#4830](https://github.com/diegosouzapw/OmniRoute/pull/4830)) -- **fix(quota):** migration 107 correctly activates the `quota-share` strategy on existing `qtSd/*` combos. ([#4962](https://github.com/diegosouzapw/OmniRoute/pull/4962)) +- **fix(quota):** 配额独占的 `qtSd/*` 连接现在出现在 `/v1/models` 列表中；EPSILON 阈值检查不再错误地阻止预算不足的分配。([#4830](https://github.com/diegosouzapw/OmniRoute/pull/4830)) +- **fix(quota):** 迁移 107 正确地在现有 `qtSd/*` Combo 上激活 `quota-share` 策略。([#4962](https://github.com/diegosouzapw/OmniRoute/pull/4962)) -**API / responses** +**API / 响应** -- **fix(api):** parse the `/v1/responses` request body once instead of 3–4 times on the hot path, reducing per-request overhead. ([#4958](https://github.com/diegosouzapw/OmniRoute/pull/4958)) -- **fix(api):** evict stale in-memory rate-limit windows to stop a slow heap leak on long-running instances. ([#4957](https://github.com/diegosouzapw/OmniRoute/pull/4957)) -- **fix(api):** require authentication on the compression `run-telemetry` endpoint; document `OMNIROUTE_EVAL_CREDENTIALS` env var. ([#4796](https://github.com/diegosouzapw/OmniRoute/pull/4796)) -- **fix(api):** stop `GET /api/system/env/repair` returning HTTP `500` on packaged installs (it broke the onboarding wizard). `createRequire(import.meta.url)` ran at module top-level; once webpack bundles the route into the standalone build, `import.meta.url` is frozen to the build-machine path and `createRequire` throws during evaluation, so the whole route failed to load. `createRequire` is now resolved lazily inside the guarded `better-sqlite3` block, root-dir resolution falls back to `process.cwd()`, and the route passes an explicit `rootDir`. ([#5028](https://github.com/diegosouzapw/OmniRoute/pull/5028)) +- **fix(api):** 在热路径上仅解析 `/v1/responses` 请求体一次，而非 3-4 次，减少每请求开销。([#4958](https://github.com/diegosouzapw/OmniRoute/pull/4958)) +- **fix(api):** 驱逐过期的内存中速率限制窗口，以阻止长时间运行实例的缓慢堆泄漏。([#4957](https://github.com/diegosouzapw/OmniRoute/pull/4957)) +- **fix(api):** 在压缩 `run-telemetry` 端点上要求认证；记录 `OMNIROUTE_EVAL_CREDENTIALS` 环境变量。([#4796](https://github.com/diegosouzapw/OmniRoute/pull/4796)) +- **fix(api):** 停止 `GET /api/system/env/repair` 在打包安装时返回 HTTP `500`（它破坏了入门向导）。`createRequire(import.meta.url)` 在模块顶层运行；一旦 webpack 将路由打包到独立构建中，`import.meta.url` 被冻结为构建机器路径，`createRequire` 在求值时抛出异常，因此整个路由加载失败。`createRequire` 现在在受保护的 `better-sqlite3` 块内惰性解析，根目录解析回退到 `process.cwd()`，并且路由传递显式的 `rootDir`。([#5028](https://github.com/diegosouzapw/OmniRoute/pull/5028)) -**Dashboard** +**仪表盘** -- **fix(dashboard):** show custom provider given-name instead of internal id across dashboard pages — cache, combo health, compression analytics, cost overview, health/autopilot, provider stats, route explainability, provider utilization, runtime. Adds shared `resolveProviderName` resolver and `useProviderNodeMap` hook. (#4603) -- **fix(dashboard):** on OAuth providers (e.g. GLM Coding), "Test all models" with auto-hide-failed now switches the model list to the "visible" filter after the run, so just-hidden failed models actually disappear on-screen — parity with the passthrough-provider path (#3610). Previously they were hidden in the DB but stayed visible under the "All" filter, so it looked like nothing was hidden. (#4887) -- **fix(dashboard):** restore the home-page provider topology card that was hidden by a default state change in #4596. ([#4963](https://github.com/diegosouzapw/OmniRoute/pull/4963)) -- **fix(dashboard):** proxy-pool success gating, sync-timestamp persistence, and opt-in Redis backend. ([#4988](https://github.com/diegosouzapw/OmniRoute/pull/4988)) -- **fix(dashboard):** show custom vision models in the LLM selector dropdown. ([#4653](https://github.com/diegosouzapw/OmniRoute/pull/4653)) +- **fix(dashboard):** 在仪表盘各页面显示自定义服务商的自定义名称而非内部 ID — 缓存、Combo 健康、压缩分析、成本概览、健康/自动驾驶、服务商统计、路由可解释性、服务商利用率、运行时。添加共享的 `resolveProviderName` 解析器和 `useProviderNodeMap` 钩子。(#4603) +- **fix(dashboard):** 在 OAuth 服务商（例如 GLM Coding）上，"测试所有模型" 并自动隐藏失败的模型现在在运行后将模型列表切换到 "可见" 过滤器，使刚隐藏的失败模型在屏幕上真正消失 — 与直通服务商路径保持一致 (#3610)。之前它们在数据库中被隐藏但在 "全部" 过滤器下仍然可见，因此看起来好像没有被隐藏。(#4887) +- **fix(dashboard):** 恢复因 #4596 中默认状态变更而被隐藏的首页服务商拓扑卡片。([#4963](https://github.com/diegosouzapw/OmniRoute/pull/4963)) +- **fix(dashboard):** 代理池成功门控、同步时间戳持久化以及可选的 Redis 后端。([#4988](https://github.com/diegosouzapw/OmniRoute/pull/4988)) +- **fix(dashboard):** 在 LLM 选择器下拉菜单中显示自定义视觉模型。([#4653](https://github.com/diegosouzapw/OmniRoute/pull/4653)) -**Providers** +**服务商** -- **fix(pollinations):** stop forcing `jsonMode` on every request. Pollinations treats `jsonMode=true` as "the model MUST return JSON" and rejects (HTTP 400 "messages must contain the word 'json'") any normal chat request whose messages don't mention "json", so all non-JSON chat was broken. `jsonMode` is now only enabled when the caller actually requests JSON output (`response_format.type` of `json_object` or `json_schema`). (#3981) -- **fix(antigravity):** default `safetySettings` to all-OFF for parity with the native Gemini paths. The Antigravity (Google Cloud Code) request builder set `safetySettings: undefined`, which `JSON.stringify` drops — so no safety settings reached Google and its server-side defaults false-flagged benign technical prompts as `prohibited_content` (HTTP 200 + blocked body, which combo failover treats as terminal). Now honors a caller-supplied value and otherwise defaults to `DEFAULT_SAFETY_SETTINGS`, matching the claude-to-gemini / openai-to-gemini paths. (#5003) -- **fix(antigravity):** exclude the standard Gemini rate-limit message from quota-exhaustion keyword matching to prevent false-positive saturation flags. ([#4810](https://github.com/diegosouzapw/OmniRoute/pull/4810) — thanks @Chewji9875) -- **fix(chatgpt-web):** map the advertised `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4-pro` and `gpt-5.2-pro` catalog ids to their dash-form ChatGPT backend slugs. They were missing from `MODEL_MAP`, so the executor sent the dot-form id verbatim, which the ChatGPT backend silently ignored and served the default Plus model instead of the requested one. Adds a drift guard asserting no advertised dot-form id reaches the backend verbatim. (#4665) -- **fix(gemini):** preserve the `pattern` field in the Antigravity tool schema sanitizer to avoid stripping valid regex constraints from tool definitions. ([#4651](https://github.com/diegosouzapw/OmniRoute/pull/4651)) -- **fix(opencode):** preserve DeepSeek reasoning content in streamed responses. ([#4631](https://github.com/diegosouzapw/OmniRoute/pull/4631)) -- **fix(perplexity):** validate API keys via the `/v1/models` endpoint instead of issuing a full chat request. ([#4654](https://github.com/diegosouzapw/OmniRoute/pull/4654)) -- **fix(qoder):** exchange PAT for `jt-*` job token before initiating Cosy chat, fixing auth failures after the Qoder credential format change. ([#4884](https://github.com/diegosouzapw/OmniRoute/pull/4884)) -- **fix(executors):** strip parameters unsupported by the target provider/model to prevent `400 Invalid parameter` errors on strict endpoints. ([#4658](https://github.com/diegosouzapw/OmniRoute/pull/4658)) -- **fix(executors):** preserve literal `reasoning_effort: "max"` for Ollama Cloud instead of normalizing to `xhigh`. Ollama Cloud accepts `high|medium|low|max|none` and rejects `xhigh` (`invalid reasoning value: 'xhigh'`); OpenRouter DeepSeek `max→xhigh` normalization is unaffected. ([#4993](https://github.com/diegosouzapw/OmniRoute/pull/4993) — thanks @Thinkscape) -- **fix(headroom):** translate openai-responses input through OpenAI for external compression. `adaptBodyForCompression` now serialises `function_call_output` items whose `output` field is a JSON object (not a string) so compression engines can process the content — previously those items were excluded from compression because `hasTextContent()` returned false for object values. ([#5023](https://github.com/diegosouzapw/OmniRoute/pull/5023) — thanks @anki1kr) -- **fix(proxy):** fan out direct dispatcher streams to all registered proxy endpoints. ([#4803](https://github.com/diegosouzapw/OmniRoute/pull/4803) — thanks @makcimbx) +- **fix(pollinations):** 停止对每个请求强制启用 `jsonMode`。Pollinations 将 `jsonMode=true` 视为"模型必须返回 JSON"并拒绝（HTTP 400 "messages must contain the word 'json'"）任何消息中不包含 "json" 的普通聊天请求，因此所有非 JSON 聊天均被破坏。`jsonMode` 现在仅在调用者实际请求 JSON 输出（`response_format.type` 为 `json_object` 或 `json_schema`）时才启用。(#3981) +- **fix(antigravity):** 将 `safetySettings` 默认设为全部关闭，与原生 Gemini 路径保持一致。Antigravity（Google Cloud Code）请求构建器将 `safetySettings` 设为 `undefined`，`JSON.stringify` 会将其丢弃 — 因此没有安全设置到达 Google，其服务器端默认值将无害的技术提示误标记为 `prohibited_content`（HTTP 200 + 被阻止的正文，Combo 容灾将其视为终端错误）。现在会遵循调用者提供的值，否则默认使用 `DEFAULT_SAFETY_SETTINGS`，与 claude-to-gemini / openai-to-gemini 路径保持一致。(#5003) +- **fix(antigravity):** 从配额耗尽关键词匹配中排除标准的 Gemini 速率限制消息，以防止误报饱和度标记。([#4810](https://github.com/diegosouzapw/OmniRoute/pull/4810) — 感谢 @Chewji9875) +- **fix(chatgpt-web):** 将通告的 `gpt-5.5`、`gpt-5.5-pro`、`gpt-5.4-pro` 和 `gpt-5.2-pro` 目录 ID 映射到其 dash 格式的 ChatGPT 后端标识。它们之前缺失于 `MODEL_MAP`，因此执行器逐字发送点号格式的 ID，ChatGPT 后端静默忽略并返回默认的 Plus 模型而非所请求的模型。添加了一个漂移守卫，断言没有任何通告的点号格式 ID 逐字到达后端。(#4665) +- **fix(gemini):** 在 Antigravity 工具 Schema 清理器中保留 `pattern` 字段，以避免从工具定义中剥离有效的正则约束。([#4651](https://github.com/diegosouzapw/OmniRoute/pull/4651)) +- **fix(opencode):** 在流式响应中保留 DeepSeek 推理内容。([#4631](https://github.com/diegosouzapw/OmniRoute/pull/4631)) +- **fix(perplexity):** 通过 `/v1/models` 端点验证 API 密钥，而非发起完整的聊天请求。([#4654](https://github.com/diegosouzapw/OmniRoute/pull/4654)) +- **fix(qoder):** 在发起 Cosy 聊天之前将 PAT 兑换为 `jt-*` 作业令牌，修复 Qoder 凭证格式变更后的认证失败。([#4884](https://github.com/diegosouzapw/OmniRoute/pull/4884)) +- **fix(executors):** 剥离目标服务商/模型不支持的参数，以防止在严格端点上出现 `400 Invalid parameter` 错误。([#4658](https://github.com/diegosouzapw/OmniRoute/pull/4658)) +- **fix(executors):** 对 Ollama Cloud 保留字面 `reasoning_effort: "max"` 而非规范化为 `xhigh`。Ollama Cloud 接受 `high|medium|low|max|none` 并拒绝 `xhigh`（`invalid reasoning value: 'xhigh'`）；OpenRouter DeepSeek 的 `max→xhigh` 规范化不受影响。([#4993](https://github.com/diegosouzapw/OmniRoute/pull/4993) — 感谢 @Thinkscape) +- **fix(headroom):** 通过 OpenAI 翻译 openai-responses 输入以进行外部压缩。`adaptBodyForCompression` 现在序列化其 `output` 字段为 JSON 对象（而非字符串）的 `function_call_output` 条目，使压缩引擎能够处理内容 — 之前这些条目因 `hasTextContent()` 对对象值返回 false 而被排除在压缩之外。([#5023](https://github.com/diegosouzapw/OmniRoute/pull/5023) — 感谢 @anki1kr) +- **fix(proxy):** 将直接调度器流扇出到所有已注册的代理端点。([#4803](https://github.com/diegosouzapw/OmniRoute/pull/4803) — 感谢 @makcimbx) -**Compression** +**压缩** -- **fix(compression):** eliminate ReDoS in the `math_inline` preservation regex — the previous pattern could catastrophically backtrack on untrusted input. ([#4838](https://github.com/diegosouzapw/OmniRoute/pull/4838)) -- **fix(compression):** stop RTK over-truncating file-read tool results — RTK now respects the full content length for file-read outputs. ([#4987](https://github.com/diegosouzapw/OmniRoute/pull/4987)) +- **fix(compression):** 消除 `math_inline` 保留正则中的 ReDoS — 之前的模式可能在不受信任的输入上发生灾难性回溯。([#4838](https://github.com/diegosouzapw/OmniRoute/pull/4838)) +- **fix(compression):** 停止 RTK 过度截断文件读取工具结果 — RTK 现在对文件读取输出尊重完整内容长度。([#4987](https://github.com/diegosouzapw/OmniRoute/pull/4987)) -**Build / CLI / infrastructure** +**构建 / CLI / 基础设施** -- **fix(build):** drop `@omniroute/open-sse` from `optimizePackageImports` to fix the Next.js build OOM crash. ([#4968](https://github.com/diegosouzapw/OmniRoute/pull/4968)) -- **fix(cli):** SIGKILL the systray child PID before closing the IPC channel to prevent macOS NSStatusItem orphan processes. ([#4732](https://github.com/diegosouzapw/OmniRoute/pull/4732)) -- **fix(cli):** bump `better-sqlite3` runtime pin to 12.10.1 for Node 26 compatibility. ([#4685](https://github.com/diegosouzapw/OmniRoute/pull/4685)) -- **fix(cli):** harden the systray2 tray runtime (port from 9router#1080). ([#4628](https://github.com/diegosouzapw/OmniRoute/pull/4628)) -- **fix(cli-tools):** tolerate JSONC (comments and trailing commas) in tool settings files. ([#4659](https://github.com/diegosouzapw/OmniRoute/pull/4659)) -- **fix(install):** make the `transformers` dependency optional so CUDA-host installs that lack Python bindings succeed. ([#4807](https://github.com/diegosouzapw/OmniRoute/pull/4807) — thanks @megamen32) -- **fix(db):** correct storage tuning settings to prevent WAL runaway on high-write workloads. ([#4834](https://github.com/diegosouzapw/OmniRoute/pull/4834) — thanks @rdself) -- **fix(image):** prevent compatible nodes from shadowing provider aliases in the image routing table. ([#4656](https://github.com/diegosouzapw/OmniRoute/pull/4656)) +- **fix(build):** 从 `optimizePackageImports` 中移除 `@omniroute/open-sse` 以修复 Next.js 构建 OOM 崩溃。([#4968](https://github.com/diegosouzapw/OmniRoute/pull/4968)) +- **fix(cli):** 在关闭 IPC 通道之前 SIGKILL systray 子进程 PID，以防止 macOS NSStatusItem 孤儿进程。([#4732](https://github.com/diegosouzapw/OmniRoute/pull/4732)) +- **fix(cli):** 将 `better-sqlite3` 运行时版本锁定提升至 12.10.1 以获得 Node 26 兼容性。([#4685](https://github.com/diegosouzapw/OmniRoute/pull/4685)) +- **fix(cli):** 加固 systray2 托盘运行时（从 9router#1080 移植）。([#4628](https://github.com/diegosouzapw/OmniRoute/pull/4628)) +- **fix(cli-tools):** 在工具设置文件中容忍 JSONC（注释和尾随逗号）。([#4659](https://github.com/diegosouzapw/OmniRoute/pull/4659)) +- **fix(install):** 使 `transformers` 依赖项变为可选，使缺乏 Python 绑定的 CUDA 主机安装能够成功。([#4807](https://github.com/diegosouzapw/OmniRoute/pull/4807) — 感谢 @megamen32) +- **fix(db):** 修正存储调优设置以防止高写入负载下 WAL 失控。([#4834](https://github.com/diegosouzapw/OmniRoute/pull/4834) — 感谢 @rdself) +- **fix(image):** 防止兼容节点在图像路由表中遮蔽服务商别名。([#4656](https://github.com/diegosouzapw/OmniRoute/pull/4656)) -**Plugin** +**插件** -- **fix(plugin):** opencode `auth.json` dual-key fallback for the auto-prefix migration. The config hook now looks up both the prefixed (`opencode-omniroute`) and bare (`omniroute`) keys, so users who authenticated before the `opencode-` prefix landed no longer need to re-auth. ([#5027](https://github.com/diegosouzapw/OmniRoute/pull/5027) — thanks @herjarsa) +- **fix(plugin):** opencode `auth.json` 双键容灾以支持自动前缀迁移。配置钩子现在同时查找带前缀的（`opencode-omniroute`）和裸的（`omniroute`）键，因此在 `opencode-` 前缀落地之前认证的用户不再需要重新认证。([#5027](https://github.com/diegosouzapw/OmniRoute/pull/5027) — 感谢 @herjarsa) --- ### 🔒 安全 -- **fix(security):** block SSRF allowlist bypass via `x-relay-path` header manipulation on Deno/Vercel relays. ([#4899](https://github.com/diegosouzapw/OmniRoute/pull/4899)) -- **fix(security):** pin image-fetch DNS resolution to prevent SSRF DNS-rebinding attacks (GHSA-cmhj-wh2f-9cgx). ([#4634](https://github.com/diegosouzapw/OmniRoute/pull/4634)) -- **fix(security):** do not trust the loopback socket as local-only when the server is behind a reverse proxy, closing a potential auth bypass path. ([#4632](https://github.com/diegosouzapw/OmniRoute/pull/4632)) -- **fix(security):** validate the Kiro region parameter to prevent SSRF via crafted region strings (GHSA-6mwv-4mrm-5p3m). ([#4629](https://github.com/diegosouzapw/OmniRoute/pull/4629)) -- **fix(copilot):** replace `execSync` shell interpolation with `execFile` in the `runOmniRouteCli` tool to prevent command injection. The user-supplied command is now split into an argv array and passed to `execFile` (no shell), so shell metacharacters are treated as literal text; error output is routed through `sanitizeErrorMessage()`. ([#5024](https://github.com/diegosouzapw/OmniRoute/pull/5024) — thanks @hamsa0x7) +- **fix(security):** 阻止通过 Deno/Vercel 中继上的 `x-relay-path` 头操纵绕过 SSRF 白名单。([#4899](https://github.com/diegosouzapw/OmniRoute/pull/4899)) +- **fix(security):** 固定图像获取 DNS 解析以防止 SSRF DNS 重新绑定攻击（GHSA-cmhj-wh2f-9cgx）。([#4634](https://github.com/diegosouzapw/OmniRoute/pull/4634)) +- **fix(security):** 当服务器位于反向代理之后时，不信任回环套接字为仅本地，堵住潜在的认证绕过路径。([#4632](https://github.com/diegosouzapw/OmniRoute/pull/4632)) +- **fix(security):** 验证 Kiro 区域参数以防止通过伪造的区域字符串进行 SSRF（GHSA-6mwv-4mrm-5p3m）。([#4629](https://github.com/diegosouzapw/OmniRoute/pull/4629)) +- **fix(copilot):** 在 `runOmniRouteCli` 工具中用 `execFile` 替换 `execSync` Shell 插值以防止命令注入。用户提供的命令现在被拆分为 argv 数组并传递给 `execFile`（无 Shell），因此 Shell 元字符被视为字面文本；错误输出通过 `sanitizeErrorMessage()` 路由。([#5024](https://github.com/diegosouzapw/OmniRoute/pull/5024) — 感谢 @hamsa0x7) --- ### 📝 维护 -**God-file decomposition (continued, #3501)** +**God-file 分解（持续进行，#3501）** -- **refactor(chatCore):** extracted 12 focused helpers from `chatCore.ts` covering the streaming pipeline (`assembleStreamingPipeline`), cache-store logic (`storeStreamingSemanticCacheResponse`, `storeSemanticCacheResponse`), response headers (`assembleStreamingResponseHeaders`, `buildNonStreamingResponseHeaders`), JSON→SSE bridge (`maybeConvertJsonBodyToSse`), guardrail context (`buildPostCallGuardrailContext`), usage buffer (`applyClientUsageBuffer`), plugin hook (`runPluginOnRequestHook`), analytics (`writeCompressionAnalytics`, `emitOutputStyleTelemetry`), and compression predicates/settings (`resolveCompressionSettings`, et al.). ([#4811](https://github.com/diegosouzapw/OmniRoute/pull/4811)–[#4837](https://github.com/diegosouzapw/OmniRoute/pull/4837)) -- **refactor(sse/db/api):** continued decomposition of `services/usage.ts` (extracted quota-core, scalar/format helpers, Antigravity/GLM/MiniMax usage families), `db/core.ts` (schema-column reconciliation, snake↔camel column-mapping), `db/apiKeys.ts` (row-parsers, model-permission matching), and `validation.ts` (URL/headers/transport leaf layer, web-cookie/Meta-AI validators, enterprise-cloud + probe, audio/speech/apikey, search/embedding/rerank, and OpenAI/Anthropic format validators). ([#4921](https://github.com/diegosouzapw/OmniRoute/pull/4921)–[#4956](https://github.com/diegosouzapw/OmniRoute/pull/4956)) -- **refactor(pricing/providers):** decomposed `pricing.ts` into shared tiers + partitioned `DEFAULT_PRICING` modules, and split the `providers.ts` catalog into semantic data modules organized by provider family. ([#4917](https://github.com/diegosouzapw/OmniRoute/pull/4917), [#4918](https://github.com/diegosouzapw/OmniRoute/pull/4918)) -- **refactor(open-sse):** extract `safeParseJSON` utility and dedup `tryParseJSON` call sites; extract and dedup the fallback `tool_call` ID generation helper. ([#4735](https://github.com/diegosouzapw/OmniRoute/pull/4735), [#4736](https://github.com/diegosouzapw/OmniRoute/pull/4736)) +- **refactor(chatCore):** 从 `chatCore.ts` 中提取了 12 个聚焦的辅助函数，涵盖流式管线（`assembleStreamingPipeline`）、缓存存储逻辑（`storeStreamingSemanticCacheResponse`、`storeSemanticCacheResponse`）、响应头（`assembleStreamingResponseHeaders`、`buildNonStreamingResponseHeaders`）、JSON→SSE 桥接（`maybeConvertJsonBodyToSse`）、护栏上下文（`buildPostCallGuardrailContext`）、用量缓冲（`applyClientUsageBuffer`）、插件钩子（`runPluginOnRequestHook`）、分析（`writeCompressionAnalytics`、`emitOutputStyleTelemetry`）以及压缩谓词/设置（`resolveCompressionSettings` 等）。([#4811](https://github.com/diegosouzapw/OmniRoute/pull/4811)–[#4837](https://github.com/diegosouzapw/OmniRoute/pull/4837)) +- **refactor(sse/db/api):** 持续分解 `services/usage.ts`（提取了配额核心、标量/格式辅助函数、Antigravity/GLM/MiniMax 用量系列）、`db/core.ts`（Schema-列对账、snake↔camel 列映射）、`db/apiKeys.ts`（行解析器、模型权限匹配）以及 `validation.ts`（URL/请求头/传输叶层、web-cookie/Meta-AI 校验器、企业云 + 探针、音频/语音/API 密钥、搜索/嵌入/重排序以及 OpenAI/Anthropic 格式校验器）。([#4921](https://github.com/diegosouzapw/OmniRoute/pull/4921)–[#4956](https://github.com/diegosouzapw/OmniRoute/pull/4956)) +- **refactor(pricing/providers):** 将 `pricing.ts` 分解为共享层级 + 分区的 `DEFAULT_PRICING` 模块，并将 `providers.ts` 目录拆分为按服务商系列组织的语义数据模块。([#4917](https://github.com/diegosouzapw/OmniRoute/pull/4917), [#4918](https://github.com/diegosouzapw/OmniRoute/pull/4918)) +- **refactor(open-sse):** 提取 `safeParseJSON` 工具函数并去重 `tryParseJSON` 调用点；提取并去重容灾 `tool_call` ID 生成辅助函数。([#4735](https://github.com/diegosouzapw/OmniRoute/pull/4735), [#4736](https://github.com/diegosouzapw/OmniRoute/pull/4736)) -**Quality & CI** +**质量与 CI** -- **chore(quality):** release base-red reconciliation + ratchet rebaselines — file-size, env-doc, and catalog baseline updates across multiple gates. ([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630), [#4879](https://github.com/diegosouzapw/OmniRoute/pull/4879), [#4886](https://github.com/diegosouzapw/OmniRoute/pull/4886), [#4915](https://github.com/diegosouzapw/OmniRoute/pull/4915), [#4961](https://github.com/diegosouzapw/OmniRoute/pull/4961), [#4973](https://github.com/diegosouzapw/OmniRoute/pull/4973)) -- **ci(quality):** shift heavy validation gates to the PR→release merge fast-path to accelerate the release cycle. ([#4857](https://github.com/diegosouzapw/OmniRoute/pull/4857)) -- **fix(ci):** include `coverage/lcov.info` in the coverage-report artifact so SonarQube can consume it. ([#4670](https://github.com/diegosouzapw/OmniRoute/pull/4670)) -- **fix(test):** validate Anthropic-compatible connections via `POST /v1/messages` for accurate connectivity testing. ([#4657](https://github.com/diegosouzapw/OmniRoute/pull/4657)) +- **chore(quality):** 发布基准-红色对账 + 棘轮基准重置 — 跨多个门控的文件大小、环境文档和目录基线更新。([#4630](https://github.com/diegosouzapw/OmniRoute/pull/4630), [#4879](https://github.com/diegosouzapw/OmniRoute/pull/4879), [#4886](https://github.com/diegosouzapw/OmniRoute/pull/4886), [#4915](https://github.com/diegosouzapw/OmniRoute/pull/4915), [#4961](https://github.com/diegosouzapw/OmniRoute/pull/4961), [#4973](https://github.com/diegosouzapw/OmniRoute/pull/4973)) +- **ci(quality):** 将重量级校验门控移至 PR→发布合并快速路径，以加速发布周期。([#4857](https://github.com/diegosouzapw/OmniRoute/pull/4857)) +- **fix(ci):** 在覆盖率报告产物中包含 `coverage/lcov.info`，以便 SonarQube 可以消费它。([#4670](https://github.com/diegosouzapw/OmniRoute/pull/4670)) +- **fix(test):** 通过 `POST /v1/messages` 验证 Anthropic 兼容连接，以获得准确的连接性测试。([#4657](https://github.com/diegosouzapw/OmniRoute/pull/4657)) -**Docs** +**文档** -- **docs(resilience):** document Quota-Share Concurrency Control — `max_concurrent` enforcement, serialization behavior, and cooldown-wait semantics. ([#4980](https://github.com/diegosouzapw/OmniRoute/pull/4980)) -- **docs(perf):** add per-endpoint p50/p95/p99 latency and cost budgets reference. ([#4867](https://github.com/diegosouzapw/OmniRoute/pull/4867) — thanks @KooshaPari) -- **docs(ops):** add canonical incident response runbook. ([#4868](https://github.com/diegosouzapw/OmniRoute/pull/4868) — thanks @KooshaPari) -- **docs(ops):** document the release-green family — `green-prs`, `check:release-green`, `babysit`, and nightly gate workflows. ([#4679](https://github.com/diegosouzapw/OmniRoute/pull/4679)) -- **docs(agentbridge):** document Electron `NODE_EXTRA_CA_CERTS`, real model IDs, and identity caveat for agent bridge integrations. ([#4718](https://github.com/diegosouzapw/OmniRoute/pull/4718)) -- **docs:** clarify Kiro provides ~50 credits/month per account, not unlimited. ([#4690](https://github.com/diegosouzapw/OmniRoute/pull/4690)) +- **docs(resilience):** 记录配额共享并发控制 — `max_concurrent` 强制执行、序列化行为以及冷却等待语义。([#4980](https://github.com/diegosouzapw/OmniRoute/pull/4980)) +- **docs(perf):** 添加每端点 p50/p95/p99 延迟和成本预算参考。([#4867](https://github.com/diegosouzapw/OmniRoute/pull/4867) — 感谢 @KooshaPari) +- **docs(ops):** 添加标准事件响应操作手册。([#4868](https://github.com/diegosouzapw/OmniRoute/pull/4868) — 感谢 @KooshaPari) +- **docs(ops):** 记录发布绿色系列 — `green-prs`、`check:release-green`、`babysit` 和夜间门控工作流。([#4679](https://github.com/diegosouzapw/OmniRoute/pull/4679)) +- **docs(agentbridge):** 记录 Electron `NODE_EXTRA_CA_CERTS`、真实模型 ID 以及代理桥接集成的身份注意事项。([#4718](https://github.com/diegosouzapw/OmniRoute/pull/4718)) +- **docs:** 澄清 Kiro 每账户每月提供约 50 积分，而非无限。([#4690](https://github.com/diegosouzapw/OmniRoute/pull/4690)) -**Misc** +**杂项** -- **chore(claude,codex):** bump pinned CLI identities — Claude `2.1.158 → 2.1.187`, Codex `0.132.0 → 0.142.0`. ([#4883](https://github.com/diegosouzapw/OmniRoute/pull/4883)) -- **chore(dashboard):** rename Qoder display label from "Qoder AI" to "Qoder". ([#4733](https://github.com/diegosouzapw/OmniRoute/pull/4733)) +- **chore(claude,codex):** 提升固定的 CLI 身份版本 — Claude `2.1.158 → 2.1.187`，Codex `0.132.0 → 0.142.0`。([#4883](https://github.com/diegosouzapw/OmniRoute/pull/4883)) +- **chore(dashboard):** 将 Qoder 显示标签从 "Qoder AI" 重命名为 "Qoder"。([#4733](https://github.com/diegosouzapw/OmniRoute/pull/4733)) --- @@ -609,29 +609,29 @@ _In development — bullets added per PR; finalized at release._ ### ✨ 新功能 -- **Adaptive context compression (Phase 4)**: a four-layer compression upgrade landed across stacked PRs — an **Output Styles** registry (`terse-prose` / `less-code` / `terse-cjk`) ([#4694](https://github.com/diegosouzapw/OmniRoute/pull/4694) — thanks @diegosouzapw), an opt-in **SLM `ultra` tier** (two-tier LLMLingua with heuristic fallback) ([#4707](https://github.com/diegosouzapw/OmniRoute/pull/4707) — thanks @diegosouzapw), a **context-budget adaptive dial** (reserve-output ladder + floor) ([#4716](https://github.com/diegosouzapw/OmniRoute/pull/4716) — thanks @diegosouzapw), and an **offline evaluation harness** (PII-gated corpus, self-test judge, gold-grader, real-pipeline runner behind a `ModelClient` seam) ([#4720](https://github.com/diegosouzapw/OmniRoute/pull/4720) — thanks @diegosouzapw). All four layers share a single `CompressionRunTelemetry` contract. -- **Redoc-rendered API docs**: a consolidated OpenAPI spec now lives at `docs/openapi.yaml` and is served as interactive Redoc documentation at `/api/docs`. ([#4781](https://github.com/diegosouzapw/OmniRoute/pull/4781) — thanks @KooshaPari / @diegosouzapw) +- **自适应上下文压缩（第四阶段）**：四层压缩升级通过堆叠式 PR 实现——**输出风格**注册表（`terse-prose` / `less-code` / `terse-cjk`）([#4694](https://github.com/diegosouzapw/OmniRoute/pull/4694) — 感谢 @diegosouzapw)，可选的 **SLM `ultra` 层级**（两级 LLMLingua 配合启发式容灾）([#4707](https://github.com/diegosouzapw/OmniRoute/pull/4707) — 感谢 @diegosouzapw)，**上下文预算自适应拨盘**（预留输出阶梯 + 下限）([#4716](https://github.com/diegosouzapw/OmniRoute/pull/4716) — 感谢 @diegosouzapw)，以及**离线评估工具集**（PII 门控语料库、自测评判器、黄金评分器、通过 `ModelClient` 接缝的真实管线运行器）([#4720](https://github.com/diegosouzapw/OmniRoute/pull/4720) — 感谢 @diegosouzapw)。四个层级共享同一 `CompressionRunTelemetry` 契约。 +- **Redoc 渲染的 API 文档**：合并后的 OpenAPI 规范现位于 `docs/openapi.yaml`，并作为交互式 Redoc 文档在 `/api/docs` 上提供。([#4781](https://github.com/diegosouzapw/OmniRoute/pull/4781) — 感谢 @KooshaPari / @diegosouzapw) ### 🔧 问题修复 -- **db-backups**: make the database-import size cap configurable via `OMNIROUTE_DB_IMPORT_MAX_MB` (default 100 MB, 4 GB ceiling) so backups larger than 100 MB can be restored; error message now points to the env var and to VACUUM ([#4757](https://github.com/diegosouzapw/OmniRoute/pull/4757) — closes #4719, thanks @diegosouzapw). -- **Onboarding**: add the missing `onboarding.tiers` step-title translation so the setup wizard no longer crashes with `MISSING_MESSAGE: onboarding.tiers` ([#4755](https://github.com/diegosouzapw/OmniRoute/pull/4755) — closes #4698, thanks @diegosouzapw). -- **deepseek-web**: fold `role:"tool"` results into the single-prompt transcript (`messagesToPrompt`) so tool outputs reach the model instead of being silently dropped when a follow-up turn omits the `tools[]` array ([#4756](https://github.com/diegosouzapw/OmniRoute/pull/4756) — closes #4712, thanks @diegosouzapw). -- **Dashboard**: remove the dead, unconditional `useLiveRequests()` call from `HomePageClient.tsx` — it crashed the `/home` page in production builds with `ReferenceError: useLiveRequests is not defined` (#4759, #4745) and opened the live-dashboard WebSocket even when Provider Topology was hidden (#4596). The live feed remains owned by the settings-gated `HomeProviderTopologySection` ([#4761](https://github.com/diegosouzapw/OmniRoute/pull/4761) — thanks @diegosouzapw). -- **Providers dashboard**: dedupe provider nodes by id when adding a compatible provider (`upsertProviderNodeById`) so the same provider can no longer appear twice and no-op adds don't invalidate the compatible-provider memo ([#4768](https://github.com/diegosouzapw/OmniRoute/pull/4768) — closes #4746, thanks @diegosouzapw). -- **Storage VACUUM**: the scheduled VACUUM job now follows the Storage page settings (`scheduledVacuum` / `vacuumHour`) as the single source of truth; the legacy env-flag control path was removed ([#4726](https://github.com/diegosouzapw/OmniRoute/pull/4726) — thanks @rdself). -- **Tiers**: no-auth providers are now counted as free, and the free-tier filter returns an empty set instead of falling through to every provider ([#4753](https://github.com/diegosouzapw/OmniRoute/pull/4753) — thanks @megamen32 / @diegosouzapw). -- **Combos**: auto-promote `zeroLatencyOptimizationsEnabled` so legacy configs (pre-3.8.33 `fallbackCompressionMode="lite"`) round-trip cleanly on the first GUI edit ([#4774](https://github.com/diegosouzapw/OmniRoute/pull/4774) — thanks @KooshaPari / @diegosouzapw). +- **db-backups**：通过 `OMNIROUTE_DB_IMPORT_MAX_MB`（默认 100 MB，上限 4 GB）使数据库导入大小上限可配置，以便恢复大于 100 MB 的备份；错误消息现在会指向该环境变量和 VACUUM（[#4757](https://github.com/diegosouzapw/OmniRoute/pull/4757) — 关闭 #4719，感谢 @diegosouzapw）。 +- **引导流程**：添加缺失的 `onboarding.tiers` 步骤标题翻译，使设置向导不再因 `MISSING_MESSAGE: onboarding.tiers` 而崩溃（[#4755](https://github.com/diegosouzapw/OmniRoute/pull/4755) — 关闭 #4698，感谢 @diegosouzapw）。 +- **deepseek-web**：将 `role:"tool"` 结果折叠到单提示转录（`messagesToPrompt`）中，使工具输出能到达模型，而不是在后续轮次省略 `tools[]` 数组时被静默丢弃（[#4756](https://github.com/diegosouzapw/OmniRoute/pull/4756) — 关闭 #4712，感谢 @diegosouzapw）。 +- **控制台**：从 `HomePageClient.tsx` 中移除无效且无条件的 `useLiveRequests()` 调用——它在生产构建中导致 `/home` 页面崩溃并报 `ReferenceError: useLiveRequests is not defined`（#4759, #4745），且即使隐藏了服务商拓扑也会打开 live WebSocket（#4596）。实时订阅现在由设置门控的 `HomeProviderTopologySection` 负责（[#4761](https://github.com/diegosouzapw/OmniRoute/pull/4761) — 感谢 @diegosouzapw）。 +- **服务商控制台**：添加兼容服务商时按 id 去重（`upsertProviderNodeById`），使同一服务商不再出现两次，且空操作添加不会使兼容服务商备忘录失效（[#4768](https://github.com/diegosouzapw/OmniRoute/pull/4768) — 关闭 #4746，感谢 @diegosouzapw）。 +- **存储 VACUUM**：定时 VACUUM 任务现在以存储页面设置（`scheduledVacuum` / `vacuumHour`）为唯一数据源；旧的环境变量控制路径已移除（[#4726](https://github.com/diegosouzapw/OmniRoute/pull/4726) — 感谢 @rdself）。 +- **Tiers**：免认证服务商现在计为免费，免费层级过滤器返回空集合而非穿透到所有服务商（[#4753](https://github.com/diegosouzapw/OmniRoute/pull/4753) — 感谢 @megamen32 / @diegosouzapw）。 +- **Combos**：自动提升 `zeroLatencyOptimizationsEnabled`，使旧配置（3.8.33 之前的 `fallbackCompressionMode="lite"`）在首次 GUI 编辑时能正常往返（[#4774](https://github.com/diegosouzapw/OmniRoute/pull/4774) — 感谢 @KooshaPari / @diegosouzapw）。 ### 📝 维护 -- **chatCore (#3501)**: continued the incremental decomposition of `executeProviderRequest` and the streaming/non-streaming hooks into pure leaf modules — top-level helpers + 6 pure leaves ([#4571](https://github.com/diegosouzapw/OmniRoute/pull/4571)), `resolveExecutorWithProxy` + `getExecutionCredentials` ([#4646](https://github.com/diegosouzapw/OmniRoute/pull/4646)), Claude message transforms ([#4708](https://github.com/diegosouzapw/OmniRoute/pull/4708)), `persistAttemptLogs` ([#4717](https://github.com/diegosouzapw/OmniRoute/pull/4717)), `stageTrace` + `compressionUsageReceipt` ([#4721](https://github.com/diegosouzapw/OmniRoute/pull/4721)), `prepareUpstreamBody` ([#4730](https://github.com/diegosouzapw/OmniRoute/pull/4730)), parse + non-streaming usage-stats ([#4762](https://github.com/diegosouzapw/OmniRoute/pull/4762)), `recordContextEditingTelemetryHook` ([#4779](https://github.com/diegosouzapw/OmniRoute/pull/4779)), `scheduleQuotaShareConsumption` ([#4780](https://github.com/diegosouzapw/OmniRoute/pull/4780)), `emitRequestGamificationEvent` ([#4776](https://github.com/diegosouzapw/OmniRoute/pull/4776)), `runPluginOnResponseHook` ([#4782](https://github.com/diegosouzapw/OmniRoute/pull/4782)), `scheduleStreamingQuotaShareConsumption` ([#4784](https://github.com/diegosouzapw/OmniRoute/pull/4784)), `recordCompressionCacheStats` ([#4792](https://github.com/diegosouzapw/OmniRoute/pull/4792)), `writeCavemanOutputAnalytics` ([#4794](https://github.com/diegosouzapw/OmniRoute/pull/4794)), `recordStreamingUsageStats` ([#4791](https://github.com/diegosouzapw/OmniRoute/pull/4791)), and `recordStreamingCost` ([#4790](https://github.com/diegosouzapw/OmniRoute/pull/4790)). (thanks @diegosouzapw) -- **Quality**: expand `check:release-green` to reproduce the full release-PR gate set locally ([#4758](https://github.com/diegosouzapw/OmniRoute/pull/4758) — thanks @diegosouzapw). -- **db**: re-export `compressionRunTelemetry` from `localDb` to satisfy the db-rules gate ([#4775](https://github.com/diegosouzapw/OmniRoute/pull/4775) — thanks @diegosouzapw). -- **Security docs**: add a canonical STRIDE-based threat model ([#4783](https://github.com/diegosouzapw/OmniRoute/pull/4783) — thanks @KooshaPari). -- **Tests**: add a smoke test for the home-client dashboard ([#4793](https://github.com/diegosouzapw/OmniRoute/pull/4793) — thanks @JxnLexn). -- **Docs**: credit **ponytail** and **OmniCompress** in the README inspiring-projects list and restore the `check:env-doc-sync` release-green by exempting the harness-only `OMNIROUTE_EVAL_CREDENTIALS` var ([#4799](https://github.com/diegosouzapw/OmniRoute/pull/4799) — thanks @diegosouzapw); declare the Phase 4 compression layers in the README + GUIDE ([#4801](https://github.com/diegosouzapw/OmniRoute/pull/4801) — thanks @diegosouzapw). -- **Quality**: trim `combo-config.test.ts` comments back under the file-size cap (follow-up to #4774) ([#4800](https://github.com/diegosouzapw/OmniRoute/pull/4800) — thanks @diegosouzapw). +- **chatCore (#3501)**：继续将 `executeProviderRequest` 和流式/非流式钩子增量分解为纯叶子模块——顶层辅助函数 + 6 个纯叶子（[#4571](https://github.com/diegosouzapw/OmniRoute/pull/4571)），`resolveExecutorWithProxy` + `getExecutionCredentials`（[#4646](https://github.com/diegosouzapw/OmniRoute/pull/4646)），Claude 消息转换（[#4708](https://github.com/diegosouzapw/OmniRoute/pull/4708)），`persistAttemptLogs`（[#4717](https://github.com/diegosouzapw/OmniRoute/pull/4717)），`stageTrace` + `compressionUsageReceipt`（[#4721](https://github.com/diegosouzapw/OmniRoute/pull/4721)），`prepareUpstreamBody`（[#4730](https://github.com/diegosouzapw/OmniRoute/pull/4730)），解析 + 非流式用量统计（[#4762](https://github.com/diegosouzapw/OmniRoute/pull/4762)），`recordContextEditingTelemetryHook`（[#4779](https://github.com/diegosouzapw/OmniRoute/pull/4779)），`scheduleQuotaShareConsumption`（[#4780](https://github.com/diegosouzapw/OmniRoute/pull/4780)），`emitRequestGamificationEvent`（[#4776](https://github.com/diegosouzapw/OmniRoute/pull/4776)），`runPluginOnResponseHook`（[#4782](https://github.com/diegosouzapw/OmniRoute/pull/4782)），`scheduleStreamingQuotaShareConsumption`（[#4784](https://github.com/diegosouzapw/OmniRoute/pull/4784)），`recordCompressionCacheStats`（[#4792](https://github.com/diegosouzapw/OmniRoute/pull/4792)），`writeCavemanOutputAnalytics`（[#4794](https://github.com/diegosouzapw/OmniRoute/pull/4794)），`recordStreamingUsageStats`（[#4791](https://github.com/diegosouzapw/OmniRoute/pull/4791)）和 `recordStreamingCost`（[#4790](https://github.com/diegosouzapw/OmniRoute/pull/4790)）。（感谢 @diegosouzapw） +- **质量**：扩展 `check:release-green` 以在本地复现完整的发布 PR 门控集合（[#4758](https://github.com/diegosouzapw/OmniRoute/pull/4758) — 感谢 @diegosouzapw）。 +- **db**：从 `localDb` 重新导出 `compressionRunTelemetry` 以满足 db-rules 门控要求（[#4775](https://github.com/diegosouzapw/OmniRoute/pull/4775) — 感谢 @diegosouzapw）。 +- **安全文档**：添加基于 STRIDE 的规范威胁模型（[#4783](https://github.com/diegosouzapw/OmniRoute/pull/4783) — 感谢 @KooshaPari）。 +- **测试**：为 home-client 控制台添加冒烟测试（[#4793](https://github.com/diegosouzapw/OmniRoute/pull/4793) — 感谢 @JxnLexn）。 +- **文档**：在 README 启发项目列表中注明 **ponytail** 和 **OmniCompress** 并修复 `check:env-doc-sync` release-green 检查（[#4799](https://github.com/diegosouzapw/OmniRoute/pull/4799) — 感谢 @diegosouzapw）；在 README + GUIDE 中声明第四阶段压缩层级（[#4801](https://github.com/diegosouzapw/OmniRoute/pull/4801) — 感谢 @diegosouzapw）。 +- **质量**：修剪 `combo-config.test.ts` 注释以保持在文件大小上限以下（#4774 的后续工作）（[#4800](https://github.com/diegosouzapw/OmniRoute/pull/4800) — 感谢 @diegosouzapw）。 --- @@ -639,55 +639,55 @@ _In development — bullets added per PR; finalized at release._ ### ✨ 新功能 -- **feat(executors): Microsoft 365 Copilot pure framing + connection helpers** — adds the request/response framing and connection helpers to support `m365.cloud.microsoft/chat` for individual M365 plans. ([#4696](https://github.com/diegosouzapw/OmniRoute/pull/4696) — thanks @skyzea1 / @diegosouzapw) -- **feat(compression): per-request `x-omniroute-compression` header (Phase 3)** — a request header now overrides the compression plan with the highest precedence (`request-header > routing > profile > auto-trigger > Default > off`), accepting `off` / `default` / `engine:` / ``. The response echoes `X-OmniRoute-Compression: ; source=`. ([#4645](https://github.com/diegosouzapw/OmniRoute/pull/4645) — thanks @diegosouzapw) -- **feat(audio): MiniMax T2A v2 TTS dispatch in `audioSpeech`** — adds MiniMax text-to-speech dispatch (port of upstream #1043). ([#4553](https://github.com/diegosouzapw/OmniRoute/pull/4553) — thanks @diegosouzapw) -- **feat(opencode): OpenCode Go DeepSeek reasoning variants** — registers the Go DeepSeek reasoning model variants. ([#4647](https://github.com/diegosouzapw/OmniRoute/pull/4647) — thanks @DevEstacion) -- **feat(quota): quota scraping for OpenCode Go and Ollama Cloud** — surfaces quota windows for the OpenCode Go and Ollama Cloud providers. ([#4642](https://github.com/diegosouzapw/OmniRoute/pull/4642) — thanks @JxnLexn) -- **feat(settings): expose stream recovery feature flags** — surfaces the stream-recovery toggles in settings. ([#4586](https://github.com/diegosouzapw/OmniRoute/pull/4586) — thanks @rdself) -- **feat(providers): optional model ID for custom API-key validation** — custom API-key connection tests can now specify the model ID used to validate the key. ([#4555](https://github.com/diegosouzapw/OmniRoute/pull/4555) — thanks @diegosouzapw) - -### 🐛 Fixed - -- **fix(db): scheduled cleanup actually runs + queries target the real tables (DB-bloat / OOM)** — `runAutoCleanup` was never scheduled, so retention cleanup never executed and tables (`compression_analytics`, `usage_history`, …) grew unbounded into multi-GB SQLite files driving high RSS. Worse, several cleanup queries referenced wrong table/column names (`call_logs.created_at`→`timestamp`, `compression_analytics.created_at`→`timestamp`, `mcp_audit_log`→`mcp_tool_audit`, `a2a_events`→`a2a_task_events`, `memory_entries`→`memories`), so even a manual run silently no-op'd or errored. Fixed the five queries to match the real schema, added `cleanupProxyLogs`, and wired a `startCleanupScheduler` (startup + every 6h, VACUUM after deletes) into `server-init` alongside the existing budget-reset and reasoning-cache jobs. ([#4691](https://github.com/diegosouzapw/OmniRoute/pull/4691), extracted from [#4428](https://github.com/diegosouzapw/OmniRoute/pull/4428) — thanks @oyi77 / @diegosouzapw) -- **fix(routing): include all noAuth models in auto-combos + add reka-flash + best-free template** — noAuth provider models are no longer skipped when building auto-combos, `reka-flash` is registered, and a `best-free` combo template is added. ([#4621](https://github.com/diegosouzapw/OmniRoute/pull/4621) — thanks @oyi77) -- **fix: noAuth provider validation + Kimi executor routing** — corrects noAuth provider membership checks and removes a mis-routed Kimi alias. (closes #4620) ([#4699](https://github.com/diegosouzapw/OmniRoute/pull/4699) — thanks @oyi77) -- **fix(executors): Firecrawl `web_fetch` 500 with `include_metadata=true`** — fixes a crash when Firecrawl web_fetch is invoked with metadata extraction enabled. ([#4692](https://github.com/diegosouzapw/OmniRoute/pull/4692) — thanks @ponkcore) -- **fix(proxy): apply `pipelining:0` + connections cap to the direct dispatcher** — same-provider concurrent requests no longer serialize behind a long/streaming request on the direct path. ([#4684](https://github.com/diegosouzapw/OmniRoute/pull/4684) — thanks @jeffer1312 / @diegosouzapw) -- **fix(telemetry): back off live-WS event forwarding when the sidecar is unreachable** — stops repeatedly attempting to connect to `LIVE_WS_PORT` when live monitoring is not configured. ([#4687](https://github.com/diegosouzapw/OmniRoute/pull/4687) — thanks @FikFikk / @diegosouzapw) -- **fix(api): serve `GET /v1/models/{model}` as JSON, not the HTML dashboard** — the per-model endpoint (IDs with slashes via a catch-all route) now returns JSON, unbreaking Claude Code. ([#4677](https://github.com/diegosouzapw/OmniRoute/pull/4677) — thanks @papajo / @diegosouzapw) -- **fix(executors): robust deepseek-web tool-call parsing and agentic context retention** — hardens DeepSeek-web tool-call parsing and preserves agentic context across turns. ([#4644](https://github.com/diegosouzapw/OmniRoute/pull/4644) — thanks @BugsBag) -- **fix(cli): authenticate `omniroute logs` and honor the active context** — the `logs` command now authenticates and respects the active context. ([#4638](https://github.com/diegosouzapw/OmniRoute/pull/4638) — thanks @Rahulsharma0810) -- **fix(stream): estimate input tokens when upstream reports `prompt_tokens=0`** — input token usage is estimated when the upstream omits it. ([#4615](https://github.com/diegosouzapw/OmniRoute/pull/4615) — thanks @adivekar-utexas) -- **fix(plugin): auto-prefix providerId with `opencode-` for OpenCode 1.17.8+ native gate** — adapts provider IDs to the OpenCode 1.17.8+ native provider gate. ([#4527](https://github.com/diegosouzapw/OmniRoute/pull/4527) — thanks @herjarsa) -- **fix(catalog): shorten no-thinking gateway prefix to `no-think/`** — renames the no-thinking gateway prefix. ([#4525](https://github.com/diegosouzapw/OmniRoute/pull/4525) — thanks @Rahulsharma0810) -- **fix(models): unknown max output limits no longer default to 8192** — models without synced/registry/static `maxOutputTokens` resolve the limit as unknown instead of a generic 8192 cap; clamping/injection only happens when a real cap is known. ([#4584](https://github.com/diegosouzapw/OmniRoute/pull/4584) — thanks @rdself) -- **fix(resilience): respect upstream retry-hint toggle** — honors the configured toggle for upstream retry hints. ([#4585](https://github.com/diegosouzapw/OmniRoute/pull/4585) — thanks @rdself) -- **fix(providers): show revealed connection API keys** — fixes revealing stored connection API keys in the UI. ([#4583](https://github.com/diegosouzapw/OmniRoute/pull/4583) — thanks @rdself) -- **fix(logs): make active-request stale sweep configurable** — exposes the stale-request sweep interval as a setting. ([#4599](https://github.com/diegosouzapw/OmniRoute/pull/4599) — thanks @rdself) -- **fix(resilience): retain provider cooldowns for the configured max window** — cooldowns persist for the configured maximum window. ([#4588](https://github.com/diegosouzapw/OmniRoute/pull/4588) — thanks @KooshaPari) -- **fix(resilience): reject invalid provider cooldown bounds** — validates cooldown bound configuration. ([#4589](https://github.com/diegosouzapw/OmniRoute/pull/4589) — thanks @KooshaPari) -- **fix(combo): preserve production combo metrics on shadow eviction** — shadow eviction no longer drops production combo metrics. ([#4590](https://github.com/diegosouzapw/OmniRoute/pull/4590) — thanks @KooshaPari) -- **fix(combo): exclude exhausted connections from auto scoring** — exhausted connections are no longer scored as auto-combo candidates. ([#4592](https://github.com/diegosouzapw/OmniRoute/pull/4592) — thanks @KooshaPari) -- **fix(relay): apply IP rate limit to the Bifrost sidecar** — extends IP rate limiting to the Bifrost relay sidecar. ([#4593](https://github.com/diegosouzapw/OmniRoute/pull/4593) — thanks @KooshaPari) -- **fix(bifrost): finalize SSE relay usage after stream** — finalizes relay usage accounting once the SSE stream completes. ([#4612](https://github.com/diegosouzapw/OmniRoute/pull/4612) — thanks @KooshaPari) -- **fix(quota): expose Bailian quota windows** — surfaces Bailian provider quota windows. ([#4610](https://github.com/diegosouzapw/OmniRoute/pull/4610) — thanks @KooshaPari) -- **fix(dashboard): gate home topology live-WS networking behind widget visibility** — the home dashboard no longer starts topology polling / live sockets when topology is hidden. ([#4618](https://github.com/diegosouzapw/OmniRoute/pull/4618), [#4606](https://github.com/diegosouzapw/OmniRoute/pull/4606) — thanks @KooshaPari) -- **fix(dashboard): isolate the quota widget refresh clock** — the quota widget refresh no longer drives unrelated re-renders. ([#4611](https://github.com/diegosouzapw/OmniRoute/pull/4611) — thanks @KooshaPari) -- **fix(dashboard): memoize compatible provider groups** — avoids recomputing compatible provider groups on every render. ([#4613](https://github.com/diegosouzapw/OmniRoute/pull/4613) — thanks @KooshaPari) -- **fix(cli): align `omniroute` data dir and env loading with the runtime** — the CLI's data-dir/env loading no longer drifts from the server runtime configuration. ([#4619](https://github.com/diegosouzapw/OmniRoute/pull/4619), [#4607](https://github.com/diegosouzapw/OmniRoute/pull/4607) — thanks @KooshaPari) -- **fix(api/settings): prevent cached `/api/settings` responses** — disables caching on the settings endpoint (port from 9router#951). ([#4566](https://github.com/diegosouzapw/OmniRoute/pull/4566) — thanks @diegosouzapw) -- **fix(executors): strip temperature for the GitHub Copilot gpt-5.4 family** — removes the unsupported `temperature` param for Copilot gpt-5.4 models (port from 9router#612). ([#4564](https://github.com/diegosouzapw/OmniRoute/pull/4564) — thanks @diegosouzapw) -- **fix(dashboard): keep play_arrow spinning on provider "Test All" buttons** — fixes the spinner state on the provider test buttons (port from 9router#715). ([#4563](https://github.com/diegosouzapw/OmniRoute/pull/4563) — thanks @diegosouzapw) -- **fix(dashboard): surface manual config CTA when Open Claw CLI auto-detect fails** — shows a manual-config call-to-action on the Open Claw CLI card when auto-detection fails. ([#4562](https://github.com/diegosouzapw/OmniRoute/pull/4562) — thanks @diegosouzapw) -- **fix(oauth): update Qwen OAuth URLs from `chat.qwen.ai` to `qwen.ai`** — refreshes the Qwen OAuth endpoints (port of decolua/9router#683). ([#4561](https://github.com/diegosouzapw/OmniRoute/pull/4561) — thanks @diegosouzapw) +- **feat(executors): Microsoft 365 Copilot 纯帧封装 + 连接辅助** — 新增请求/响应帧封装和连接辅助，支持 `m365.cloud.microsoft/chat` 用于个人 M365 计划。([#4696](https://github.com/diegosouzapw/OmniRoute/pull/4696) — 感谢 @skyzea1 / @diegosouzapw) +- **feat(compression): 按请求的 `x-omniroute-compression` 请求头（第 3 阶段）** — 请求头现在以最高优先级覆盖压缩方案（`请求头 > 路由 > profile > 自动触发 > 默认 > 关闭`），接受 `off` / `默认` / `引擎:` / ``。响应回显 `X-OmniRoute-Compression: ; source=`。([#4645](https://github.com/diegosouzapw/OmniRoute/pull/4645) — 感谢 @diegosouzapw) +- **feat(audio): MiniMax T2A v2 文本转语音调度接入 `audioSpeech`** — 新增 MiniMax 文本转语音调度（移植上游 #1043）。([#4553](https://github.com/diegosouzapw/OmniRoute/pull/4553) — 感谢 @diegosouzapw) +- **feat(opencode): OpenCode Go DeepSeek 推理变体** — 注册 Go DeepSeek 推理模型变体。([#4647](https://github.com/diegosouzapw/OmniRoute/pull/4647) — 感谢 @DevEstacion) +- **feat(quota): OpenCode Go 和 Ollama Cloud 配额抓取** — 展示 OpenCode Go 和 Ollama Cloud 服务商的配额窗口。([#4642](https://github.com/diegosouzapw/OmniRoute/pull/4642) — 感谢 @JxnLexn) +- **feat(settings): 暴露流式恢复功能开关** — 在设置中展示流式恢复开关。([#4586](https://github.com/diegosouzapw/OmniRoute/pull/4586) — 感谢 @rdself) +- **feat(providers): 自定义 API 密钥校验的可选模型 ID** — 自定义 API 密钥连接测试现在可指定用于校验密钥的模型 ID。([#4555](https://github.com/diegosouzapw/OmniRoute/pull/4555) — 感谢 @diegosouzapw) + +### 🐛 问题修复 + +- **fix(db): 定时清理真正运行 + 查询指向正确的表（数据库膨胀 / OOM）** — `runAutoCleanup` 从未被调度，导致保留清理从未执行，表（`compression_analytics`、`usage_history` 等）无限增长成数 GB 的 SQLite 文件，推高 RSS。更糟糕的是，多个清理查询引用了错误的表名/列名（`call_logs.created_at`→`timestamp`、`compression_analytics.created_at`→`timestamp`、`mcp_audit_log`→`mcp_tool_audit`、`a2a_events`→`a2a_task_events`、`memory_entries`→`memories`），因此即使手动运行也静默无操作或报错。修复了五条查询以匹配真实 schema，新增 `cleanupProxyLogs`，并将 `startCleanupScheduler`（启动时 + 每 6 小时，删除后执行 VACUUM）接入 `server-init`，与现有的预算重置和推理缓存任务并列运行。([#4691](https://github.com/diegosouzapw/OmniRoute/pull/4691)，提取自 [#4428](https://github.com/diegosouzapw/OmniRoute/pull/4428) — 感谢 @oyi77 / @diegosouzapw) +- **fix(routing): 自动 Combo 纳入所有 noAuth 模型 + 新增 reka-flash + 最佳免费模板** — 构建自动 Combo 时不再跳过 noAuth 服务商模型，注册 `reka-flash`，并新增 `best-free` Combo 模板。([#4621](https://github.com/diegosouzapw/OmniRoute/pull/4621) — 感谢 @oyi77) +- **fix: noAuth 服务商校验 + Kimi 执行器路由** — 修正 noAuth 服务商成员检查，移除错误路由的 Kimi 别名。（关闭 #4620）([#4699](https://github.com/diegosouzapw/OmniRoute/pull/4699) — 感谢 @oyi77) +- **fix(executors): Firecrawl `web_fetch` 携带 `include_metadata=true` 时返回 500** — 修复 Firecrawl web_fetch 在启用元数据提取时崩溃的问题。([#4692](https://github.com/diegosouzapw/OmniRoute/pull/4692) — 感谢 @ponkcore) +- **fix(proxy): 对直连调度器应用 `pipelining:0` + 连接数上限** — 同一服务商的并发请求不再因一个长时/流式传输请求而在直连路径上排队等待。([#4684](https://github.com/diegosouzapw/OmniRoute/pull/4684) — 感谢 @jeffer1312 / @diegosouzapw) +- **fix(telemetry): sidecar 不可达时退避实时 WebSocket 事件转发** — 当未配置实时监控时，停止反复尝试连接 `LIVE_WS_PORT`。([#4687](https://github.com/diegosouzapw/OmniRoute/pull/4687) — 感谢 @FikFikk / @diegosouzapw) +- **fix(api): `GET /v1/models/{model}` 返回 JSON 而非 HTML 仪表盘** — 按模型端点（通过通配路由支持含斜杠的 ID）现在返回 JSON，修复 Claude Code 兼容性问题。([#4677](https://github.com/diegosouzapw/OmniRoute/pull/4677) — 感谢 @papajo / @diegosouzapw) +- **fix(executors): 增强 deepseek-web 工具调用解析和代理上下文保留** — 加固 DeepSeek-web 工具调用解析，并在多轮对话中保留代理上下文。([#4644](https://github.com/diegosouzapw/OmniRoute/pull/4644) — 感谢 @BugsBag) +- **fix(cli): `omniroute logs` 认证并遵循当前上下文** — `logs` 命令现在进行认证并遵循当前上下文。([#4638](https://github.com/diegosouzapw/OmniRoute/pull/4638) — 感谢 @Rahulsharma0810) +- **fix(stream): 上游报告 `prompt_tokens=0` 时估算输入令牌** — 当上游省略输入令牌用量时进行估算。([#4615](https://github.com/diegosouzapw/OmniRoute/pull/4615) — 感谢 @adivekar-utexas) +- **fix(plugin): 为 OpenCode 1.17.8+ 原生网关自动添加 `opencode-` 前缀** — 适配服务商 ID 以对接 OpenCode 1.17.8+ 原生服务商网关。([#4527](https://github.com/diegosouzapw/OmniRoute/pull/4527) — 感谢 @herjarsa) +- **fix(catalog): 将无思考网关前缀缩短为 `no-think/`** — 重命名无思考网关前缀。([#4525](https://github.com/diegosouzapw/OmniRoute/pull/4525) — 感谢 @Rahulsharma0810) +- **fix(models): 未知最大输出限制不再默认设为 8192** — 没有同步/注册表/静态 `maxOutputTokens` 的模型将限制解析为未知，而非通用的 8192 上限；仅当已知真实上限时才执行钳制/注入。([#4584](https://github.com/diegosouzapw/OmniRoute/pull/4584) — 感谢 @rdself) +- **fix(resilience): 遵循上游重试提示开关** — 遵循配置的上游重试提示开关。([#4585](https://github.com/diegosouzapw/OmniRoute/pull/4585) — 感谢 @rdself) +- **fix(providers): 显示已保存连接的 API 密钥** — 修复在 UI 中显示已保存连接 API 密钥的功能。([#4583](https://github.com/diegosouzapw/OmniRoute/pull/4583) — 感谢 @rdself) +- **fix(logs): 使活跃请求过期清理可配置** — 将过期请求清理间隔暴露为设置项。([#4599](https://github.com/diegosouzapw/OmniRoute/pull/4599) — 感谢 @rdself) +- **fix(resilience): 在配置的最大窗口内保留服务商冷却状态** — 冷却状态在配置的最大窗口内持久保留。([#4588](https://github.com/diegosouzapw/OmniRoute/pull/4588) — 感谢 @KooshaPari) +- **fix(resilience): 拒绝无效的服务商冷却边界值** — 校验冷却边界配置。([#4589](https://github.com/diegosouzapw/OmniRoute/pull/4589) — 感谢 @KooshaPari) +- **fix(combo): 影子淘汰时保留生产 Combo 指标** — 影子淘汰不再丢弃生产 Combo 指标。([#4590](https://github.com/diegosouzapw/OmniRoute/pull/4590) — 感谢 @KooshaPari) +- **fix(combo): 自动评分排除已耗尽的连接** — 已耗尽的连接不再被评分为自动 Combo 候选。([#4592](https://github.com/diegosouzapw/OmniRoute/pull/4592) — 感谢 @KooshaPari) +- **fix(relay): 对 Bifrost sidecar 应用 IP 速率限制** — 将 IP 速率限制扩展到 Bifrost 中继 sidecar。([#4593](https://github.com/diegosouzapw/OmniRoute/pull/4593) — 感谢 @KooshaPari) +- **fix(bifrost): 流结束后完成 SSE 中继用量统计** — SSE 流完成后完成中继用量统计。([#4612](https://github.com/diegosouzapw/OmniRoute/pull/4612) — 感谢 @KooshaPari) +- **fix(quota): 展示 Bailian 配额窗口** — 展示 Bailian 服务商配额窗口。([#4610](https://github.com/diegosouzapw/OmniRoute/pull/4610) — 感谢 @KooshaPari) +- **fix(dashboard): 首页拓扑实时 WebSocket 网络受小部件可见性控制** — 首页控制台在拓扑隐藏时不再启动拓扑轮询/实时 socket 连接。([#4618](https://github.com/diegosouzapw/OmniRoute/pull/4618), [#4606](https://github.com/diegosouzapw/OmniRoute/pull/4606) — 感谢 @KooshaPari) +- **fix(dashboard): 隔离配额小部件刷新时钟** — 配额小部件刷新不再触发无关的重新渲染。([#4611](https://github.com/diegosouzapw/OmniRoute/pull/4611) — 感谢 @KooshaPari) +- **fix(dashboard): 缓存兼容服务商分组** — 避免每次渲染时重新计算兼容服务商分组。([#4613](https://github.com/diegosouzapw/OmniRoute/pull/4613) — 感谢 @KooshaPari) +- **fix(cli): `omniroute` 数据目录和环境加载与运行时对齐** — CLI 的数据目录/环境加载不再偏离服务器运行时配置。([#4619](https://github.com/diegosouzapw/OmniRoute/pull/4619), [#4607](https://github.com/diegosouzapw/OmniRoute/pull/4607) — 感谢 @KooshaPari) +- **fix(api/settings): 防止 `/api/settings` 响应被缓存** — 禁用设置端点的缓存（移植自 9router#951）。([#4566](https://github.com/diegosouzapw/OmniRoute/pull/4566) — 感谢 @diegosouzapw) +- **fix(executors): GitHub Copilot gpt-5.4 系列移除 temperature 参数** — 移除 Copilot gpt-5.4 模型不支持的 `temperature` 参数（移植自 9router#612）。([#4564](https://github.com/diegosouzapw/OmniRoute/pull/4564) — 感谢 @diegosouzapw) +- **fix(dashboard): 服务商"全部测试"按钮保持 play_arrow 旋转动画** — 修复服务商测试按钮的旋转状态（移植自 9router#715）。([#4563](https://github.com/diegosouzapw/OmniRoute/pull/4563) — 感谢 @diegosouzapw) +- **fix(dashboard): Open Claw CLI 自动检测失败时显示手动配置引导** — 在 Open Claw CLI 卡片上自动检测失败时显示手动配置引导按钮。([#4562](https://github.com/diegosouzapw/OmniRoute/pull/4562) — 感谢 @diegosouzapw) +- **fix(oauth): 更新 Qwen OAuth URL 从 `chat.qwen.ai` 到 `qwen.ai`** — 刷新 Qwen OAuth 端点（移植自 decolua/9router#683）。([#4561](https://github.com/diegosouzapw/OmniRoute/pull/4561) — 感谢 @diegosouzapw) ### 📝 维护 -- **refactor(imageGeneration): extract 8 provider families to co-located files** — splits the image-generation module into eight co-located per-provider files with no behavioral change. ([#4609](https://github.com/diegosouzapw/OmniRoute/pull/4609) — thanks @KooshaPari) -- **deps: bump production + development groups; migrate js-yaml to v5 (ESM)** — dependency bumps plus a `js-yaml` v4→v5 migration to the ESM-only namespace import. ([#4697](https://github.com/diegosouzapw/OmniRoute/pull/4697) — thanks @diegosouzapw) -- **chore(quality): release-green pre-flight validator + nightly signal** — new `npm run check:release-green` (`scripts/quality/validate-release-green.mjs`) reproduces the release-equivalent validation (full unit + vitest + ratchets + typecheck + lint, optional `--with-build` package-artifact) against the current working tree and classifies each red as **HARD** (real defect) vs **DRIFT** (ratchet, rebaselined at release) — purely diagnostic, never blocking contributors. A new `nightly-release-green` workflow runs it on the active release branch and opens/updates a tracking issue on hard failures. Closes the gap where the full gate (`ci.yml`) only ran on the release PR, so reds accrued silently on `release/**` and surfaced in layers at release time. ([#4622](https://github.com/diegosouzapw/OmniRoute/pull/4622) — thanks @diegosouzapw) -- **chore(quality): reconcile file-size baseline for #4644 (`deepseek-web.ts` 1117→1125)** — rebaselines the file-size gate after the deepseek-web hardening. ([#4695](https://github.com/diegosouzapw/OmniRoute/pull/4695) — thanks @diegosouzapw) +- **refactor(imageGeneration): 提取 8 个服务商系列到并列文件** — 将图像生成模块拆分为八个并列的按服务商文件，无行为变更。([#4609](https://github.com/diegosouzapw/OmniRoute/pull/4609) — 感谢 @KooshaPari) +- **deps: 升级生产 + 开发依赖组；迁移 js-yaml 到 v5 (ESM)** — 依赖升级，外加 `js-yaml` v4→v5 迁移到纯 ESM 命名空间导入。([#4697](https://github.com/diegosouzapw/OmniRoute/pull/4697) — 感谢 @diegosouzapw) +- **chore(quality): 发布绿灯预检校验器 + 夜间信号** — 新增 `npm run check:release-green`（`scripts/quality/validate-release-green.mjs`），针对当前工作树重现等效发布的校验（完整单元测试 + vitest + ratchets + typecheck + lint，可选 `--with-build` 构建产物），并将每个红色项分类为 **HARD**（真实缺陷）或 **DRIFT**（ratchet 漂移，发布时重新基线化）——纯诊断性质，永不阻止贡献者。新增 `nightly-release-green` 工作流，在活跃的发布分支上运行该校验，并在硬故障时打开/更新跟踪 issue。填补了完整门禁（`ci.yml`）仅在发布 PR 上运行、导致 `release/**` 上的红色项静默累积并在发布时分批暴露的空白。([#4622](https://github.com/diegosouzapw/OmniRoute/pull/4622) — 感谢 @diegosouzapw) +- **chore(quality): 为 #4644 调整文件大小基线（`deepseek-web.ts` 1117→1125）** — deepseek-web 加固后重新基线化文件大小门禁。([#4695](https://github.com/diegosouzapw/OmniRoute/pull/4695) — 感谢 @diegosouzapw) --- @@ -705,44 +705,44 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **perf(dashboard): combos UI leaf-split, Next.js config tuning, 1-click Redis & Bifrost sidecar** — delivers four of the five performance/UX tracks from the #3932 thread: the combos dashboard page is split into focused leaf components (smaller bundles, faster reloads), `next.config` is tuned for the standalone build, Redis can be provisioned in one click, and a Bifrost sidecar option is wired in. (The fifth track — chatLogHelpers extraction — was already covered upstream and dropped.) ([#4381](https://github.com/diegosouzapw/OmniRoute/pull/4381) — thanks @KooshaPari) - -### 🐛 Fixed - -- **fix(embeddings): NVIDIA NIM asymmetric embedding models inject the required `input_type`** — NVIDIA NIM asymmetric embedders (e.g. `nvidia/nv-embedqa-e5-v5`) reject requests without an `input_type` parameter with `400 "'input_type' parameter is required"`, but OmniRoute only forwarded `input_type` when the client supplied it — so callers (and OpenAI-style SDKs that don't emit the field) got a hard failure. The embedding registry now carries a model-level default (`input_type: "query"`) for the asymmetric NVIDIA model, and the embeddings handler injects a model's default params into the upstream body **only** when the client didn't already send them — a client-supplied `input_type` (e.g. `"passage"`) is respected unchanged, and symmetric models that carry no default are unaffected. ([#4341](https://github.com/diegosouzapw/OmniRoute/pull/4341) — thanks @hydraromania) -- **fix(api): migrate the deprecated Codex `[features].codex_hooks` flag to `[features].hooks`** — Codex renamed the `codex_hooks` feature flag to `hooks`; recent Codex CLI versions ignore the old key and print a deprecation notice. When OmniRoute rewrites an existing `~/.codex/config.toml` (configuring/resetting the Codex provider) it now carries the user's intent forward by renaming `[features].codex_hooks` → `[features].hooks` (preserving its value, never clobbering an already-present `hooks`) and dropping the deprecated key. No-op when the flag is absent. ([#4342](https://github.com/diegosouzapw/OmniRoute/pull/4342) — thanks @Bian-Sh) -- **fix(translator): same-format response path no longer leaks a `data: null` SSE event** — the streaming response translator's same-format fast path returned `[chunk]` unconditionally, so the end-of-stream null/flush signal (`chunk === null`) propagated as a literal `[null]`. Downstream this surfaced as an empty `data: null` SSE event between chunks and crashed strict clients (e.g. Factory Droid BYOK on `/v1/responses`). The fast path now drops the null flush (returns `[]`) while still passing real chunks through unchanged. ([#4344](https://github.com/diegosouzapw/OmniRoute/pull/4344) — thanks @thaitryhand) -- **fix(translator): strip client-only assistant echo fields on the OpenAI target path (Mistral 422)** — strict OpenAI-compatible upstreams (e.g. `mistral/codestral-latest`) reject client-only assistant "echo" fields sent back as input history with `422 extra_forbidden` (the report hit `messages[].assistant.reasoning_content` via Codex `/responses`). Only `reasoning_content` was being stripped on the OpenAI target path; the sibling echo fields `reasoning`, `refusal`, `annotations` and `cache_control` leaked through and tripped the 422. They are now all dropped on the non-reasoner OpenAI target path. `audio` is deliberately preserved (OpenAI audio models reference a prior assistant audio response by id on multi-turn; Mistral never emits audio, so nothing is lost there). ([#4350](https://github.com/diegosouzapw/OmniRoute/pull/4350) — thanks @xxy9468615) -- **fix(translator): accept AI SDK-style `{ type: "image", image: "data:…" }` content parts** — several OpenAI-input translators only recognized images shaped as `image_url.url` (or an object with `.source`/`.url`), so an AI SDK-style part where `image` is a bare data-URL **string** was silently dropped before reaching a vision provider (OpenCode is one affected client; the gap is generic). The OpenAI→Claude, OpenAI→Kiro and OpenAI→Gemini/Antigravity translators now parse a string `image` data URL into each provider's native image shape (Claude `{source:{type:"base64"}}`, Kiro `images[].source.bytes`, Gemini `inlineData`). ([#4345](https://github.com/diegosouzapw/OmniRoute/pull/4345) — thanks @mugnimaestra) -- **fix(translator): Gemini accepts HTTP/HTTPS image URLs instead of silently dropping them** — the OpenAI→Gemini request helper (`convertOpenAIContentToParts`) discarded remote `image_url` parts (emitting only a `console.warn`) because Gemini's `inlineData` needs base64 and the synchronous helper can't fetch+encode upstream. It now uses Gemini's native `fileData: { fileUri }` part for HTTP/HTTPS URLs (the model fetches the asset itself), so vision requests carrying a URL — not a `data:` URI — reach Gemini intact. ([#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) — ported from 9router#344, thanks @diegosouzapw) -- **fix(executors): strip `stream_options` for qwen non-streaming / thinking Claude-Code requests** — Claude-Code-compatible providers force the executor-level `stream` flag on while the outgoing body keeps the caller's original `stream: false`, so `DefaultExecutor.transformRequest` injected `stream_options: { include_usage: true }` onto a body that still said `stream: false`, and qwen rejected it with `400 "'stream_options' only set this when you set stream: true"`. The executor now strips `stream_options` whenever the body's effective `stream` is false. ([#4374](https://github.com/diegosouzapw/OmniRoute/pull/4374) — ported from 9router#663, thanks @anuragg-saxenaa / @diegosouzapw) -- **fix(executors): don't inject `thinking` when `tool_choice` forces a tool (native Claude)** — the Claude-Code wire-image emulation injects `thinking: { type: "adaptive" }` for non-Haiku Claude models, but Anthropic rejects `thinking` when `tool_choice` forces a specific tool (`{type:"any"|"tool"}`) with `400 "Thinking may not be enabled when tool_choice forces tool use."`. Any Opus/Sonnet call that pins a tool (e.g. Claude Code's `message_user`, or agent harnesses that force a tool) hit a hard 400; the injection is now suppressed when `tool_choice` forces a tool. ([#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) — thanks @NomenAK) -- **fix(codex): request reasoning summaries on Codex Responses requests** — Codex/OpenAI Responses can return reasoning-token accounting and empty reasoning items unless visible reasoning summaries are requested, so Codex CLI / pi.dev paths missed visible thinking text. OmniRoute now requests `reasoning.summary: "auto"` (and includes `reasoning.encrypted_content`) when reasoning is enabled — preserving an explicit client `reasoning.summary` and existing `include` entries, and skipping it for `reasoning.effort: "none"`. ([#4359](https://github.com/diegosouzapw/OmniRoute/pull/4359) — thanks @xz-dev) -- **fix(sse): default the combo per-target timeout to 120s for fast failover** — a combo's per-target timeout inherited the full `FETCH_TIMEOUT_MS` (600s default) when the combo didn't set `targetTimeoutMs`, so a single hung/slow target (e.g. an openai-compatible upstream returning 524/504) could stall the **whole** combo for up to 10 minutes before failing over. A new `DEFAULT_COMBO_TARGET_TIMEOUT_MS = 120_000` is used as the default-when-unset in `resolveComboTargetTimeoutMs` (backward-compatible 3rd arg, wired in `phaseComboSetup`); an explicit ceiling/opt-out is preserved. ([#4365](https://github.com/diegosouzapw/OmniRoute/pull/4365) — thanks @diegosouzapw) -- **fix(cli): Tailscale login honors `TAILSCALE_AUTHKEY` for non-interactive sign-in** — `startTailscaleLogin` built `tailscale up` without ever reading `process.env.TAILSCALE_AUTHKEY`, so on a pre-authenticated / headless daemon the login waited for an interactive auth URL and timed out (~15s). When `TAILSCALE_AUTHKEY` is set it is now passed via `--auth-key=` (as a spawn argv element — no shell interpolation) so the daemon authenticates non-interactively; when unset, behavior is unchanged. ([#4343](https://github.com/diegosouzapw/OmniRoute/pull/4343) — thanks @ipeterpetrus) -- **fix(dashboard): OAuth modal shows the real error on a non-JSON server response** — the OAuth connect/reauth modal called `await res.json()` unconditionally, so when a build/OAuth endpoint returned a plain-text error (e.g. a `500 Internal Server Error` page) the modal threw `Unexpected token 'I'…` and hid the real failure. Two shared helpers (`parseResponseBody` / `getErrorMessage` in `src/shared/utils/api.ts`) now read the body safely (JSON when it is JSON, raw text otherwise) and surface a clean message either way; all modal fetch sites use them. ([#4351](https://github.com/diegosouzapw/OmniRoute/pull/4351) — thanks @DNNYF) -- **fix(dashboard): a disabled connection's last error is now visible** — the provider card's error badge counts a disabled connection (`isActive === false`) that has an error (its effective status is still error/expired/unavailable), but the connection row hid the `lastError` text for disabled rows — so the operator saw the error count without being able to see what failed. The row now shows the error text whenever there is one, regardless of the active toggle. ([#4352](https://github.com/diegosouzapw/OmniRoute/pull/4352) — thanks @ntdung6868) -- **fix(providers): the "Test Connection One-by-One" OAuth probe can no longer hang the queue forever** — the OAuth connection-test path called bare `fetch(url, { method, headers })` with no `AbortController`/signal/timeout, so when a provider's probe endpoint accepted the socket but never responded, the awaited fetch never settled and the one-by-one test queue stalled indefinitely (the API-key path was already bounded via `validateProviderApiKey`'s `timeoutMs`). Both the initial probe and the post-refresh retry are now bounded with `AbortSignal.timeout(30s)` — matching the API-key path's 30s budget — and a timed-out probe resolves as a failure with a clear `Test timed out after 30s` message in the same shape as every other test error. ([#4347](https://github.com/diegosouzapw/OmniRoute/pull/4347) — thanks @ntdung6868) -- **fix(providers): a deactivated account is labeled distinctly from a revoked token** — a Codex connection whose OAuth refresh is fully healthy but whose ChatGPT account has been deactivated by the provider gets a `401` from the upstream API. The connection test labeled that the same as a bad credential (`Token invalid or revoked` → `upstream_auth_error`), so the operator couldn't tell a deactivated account from a revoked token. The test now reads the `401`/`403` body and, when it indicates account deactivation, classifies it as `account_deactivated` — which the dashboard already renders as "Account Deactivated". A plain auth `401` is unchanged. ([#4353](https://github.com/diegosouzapw/OmniRoute/pull/4353) — thanks @ntdung6868) -- **fix(db): cascade-delete orphaned model aliases when a provider is removed** — deleting a custom provider removed its connections and node but left behind the imported model-alias rows (stored as `key=`, `value="/"`). Those stale aliases then blocked re-importing the same provider — the import dedup treated them as "already exists", so no new models appeared. A new `deleteModelAliasesForProvider(providerId)` DB helper drops every alias whose stored value begins with `/` (leaving other providers and user-defined settings aliases untouched), and the provider-node DELETE handler now calls it after removing the connections and node, so a fresh import is unblocked. ([#4348](https://github.com/diegosouzapw/OmniRoute/pull/4348) — thanks @nguyenvanhuy0612) -- **fix(api): persist `max_input_tokens` / `max_output_tokens` when adding a custom model** — `POST /api/provider-models` silently dropped the per-model token limits set in the "add custom model" form: the handler destructured the rest of the body but never read `max_input_tokens` / `max_output_tokens`, and `addCustomModel()` had no parameter for them, so the values were thrown away on write. The DB layer (`inputTokenLimit` / `outputTokenLimit`) and the `/v1/models` catalog already round-trip these fields — only the write path was missing. The validation schema now accepts the two optional limits, the handler forwards them, and `addCustomModel()` persists them so a custom model's context/output window survives into the catalog. ([#4349](https://github.com/diegosouzapw/OmniRoute/pull/4349) — thanks @codename-zen) -- **fix(plugin): the OpenCode static-catalog plugin prefixes combo/raw model keys with the provider id** — OpenCode's static-catalog reader misdetected the `omniroute` provider: combo keys emitted as `combo/MASTER` were parsed as provider `combo` ("No credentials for provider: omniroute"), while a bare-`MASTER` form was misread as a model with no resolvable provider, and mixed `omniroute/MASTER` + bare-raw keys were rejected by OpenCode's schema. The plugin now emits every combo and raw model key prefixed with the `omniroute` provider id, emits the provider id explicitly, and drops the legacy `combo/` prefix — so the static-catalog reader detects the provider and the auth loader returns the right credentials (the catalog-fetch timeout was also raised so a cold-start server doesn't publish an empty stub). ([#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) — thanks @herjarsa) +- **perf(dashboard): 组合 UI 叶子组件拆分、Next.js 配置调优、一键 Redis 和 Bifrost sidecar** — 交付了 #3932 讨论串中五个性能/UX 轨道中的四个：组合 控制台 页面被拆分为专注的叶子组件（更小的打包体积、更快的重载速度），`next.配置` 针对独立构建进行了调优，Redis 可一键配置，Bifrost sidecar 选项也已接入。（第五个轨道 — chatLogHelpers 提取 — 已在上游完成，因此移除。）([#4381](https://github.com/diegosouzapw/OmniRoute/pull/4381) — 感谢 @KooshaPari) + +### 🐛 问题修复 + +- **fix(embeddings): NVIDIA NIM 非对称嵌入模型注入必需的 `input_type`** — NVIDIA NIM 非对称嵌入模型（如 `nvidia/nv-embedqa-e5-v5`）会拒绝没有 `input_type` 参数的请求，返回 `400 "'input_type' parameter is required"`，但 OmniRoute 仅在客户端提供 `input_type` 时才转发 — 因此调用方（以及不发送该字段的 OpenAI 风格 SDK）会遭遇硬性失败。嵌入注册表现在为 NVIDIA 非对���模型携带模型级默认值（`input_type: "query"`），嵌入处理器仅在客户端未发送时才会将模型默认参数注入上游请求体 — 客户端提供的 `input_type`（如 `"passage"`）将原样保留，而没有默认值的对称模型不受影响。([#4341](https://github.com/diegosouzapw/OmniRoute/pull/4341) — 感谢 @hydraromania) +- **fix(api): 将已弃用的 Codex `[features].codex_hooks` 标志迁移到 `[features].hooks`** — Codex 将 `codex_hooks` 功能标志重命名为 `hooks`；最近的 Codex CLI 版本会忽略旧键并打印弃用通知。当 OmniRoute 重写现有的 `~/.codex/config.toml`（配置/重置 Codex 服务商）时，现在会通过重命名 `[features].codex_hooks` → `[features].hooks`（保留其值，绝不覆盖已存在的 `hooks`）并丢弃已弃用的键来保留用户意图。当该标志不存在时无操作。([#4342](https://github.com/diegosouzapw/OmniRoute/pull/4342) — 感谢 @Bian-Sh) +- **fix(translator): 同格式响应路径不再泄露 `data: null` SSE 事件** — 流式传输 响应翻译器的同格式快速路径无条件返回 `[chunk]`，因此流结束时的 null/刷新信号（`chunk === null`）被原样传播为 `[null]`。在下游表现为 chunk 之间的空 `data: null` SSE 事件，导致严格客户端（如 Factory Droid BYOK 在 `/v1/responses` 上）崩溃。快速路径现在丢弃 null 刷新（返回 `[]`），同时仍原样传递真实 chunk。([#4344](https://github.com/diegosouzapw/OmniRoute/pull/4344) — 感谢 @thaitryhand) +- **fix(translator): 在 OpenAI 目标路径上剥离仅客户端使用的助手回显字段（修复 Mistral 422）** — 严格的 OpenAI 兼容上游（如 `mistral/codestral-latest`）会拒绝作为输入历史发送回去的仅客户端使用的助手"回显"字段，返回 `422 extra_forbidden`（报告中出现了通过 Codex `/responses` 发送的 `messages[].assistant.reasoning_content`）。此前仅在 OpenAI 目标路径上剥离了 `reasoning_content`；同级回显字段 `reasoning`、`refusal`、`annotations` 和 `cache_control` 泄露了出去并触发了 422。现在在非推理 OpenAI 目标路径上全部丢弃。`audio` 被特意保留（OpenAI 音频模型在多轮中通过 id 引用先前的助手音频响应；Mistral 从不发出音频，因此不会有任何损失）。([#4350](https://github.com/diegosouzapw/OmniRoute/pull/4350) — 感谢 @xxy9468615) +- **fix(translator): 接受 AI SDK 风格的 `{ type: "image", image: "data:…" }` 内容部分** — 多个 OpenAI 输入翻译器仅识别形状为 `image_url.url`（或带有 `.source`/`.url` 的对象）的图像，因此 AI SDK 风格的部分（其中 `image` 是裸 data-URL 字符串）在到达视觉服务商之前被静默丢弃（OpenCode 是受影响客户端之一；此问题具有普遍性）。OpenAI→Claude、OpenAI→Kiro 和 OpenAI→Gemini/Antigravity 翻译器现在将字符串 `image` data URL 解析为各服务商的原生图像格式（Claude `{source:{type:"base64"}}`、Kiro `images[].source.bytes`、Gemini `inlineData`）。([#4345](https://github.com/diegosouzapw/OmniRoute/pull/4345) — 感谢 @mugnimaestra) +- **fix(translator): Gemini 接受 HTTP/HTTPS 图像 URL 而非静默丢弃** — OpenAI→Gemini 请求辅助函数（`convertOpenAIContentToParts`）之前会丢弃远程 `image_url` 部分（仅发出 `console.warn`），因为 Gemini 的 `inlineData` 需要 base64，而同步辅助函数无法获取并编码上游资源。现在对 HTTP/HTTPS URL 使用 Gemini 原生的 `fileData: { fileUri }` 部分（模型自行获取资源），因此携带 URL（而非 `data:` URI）的视觉请求能完整到达 Gemini。([#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) — 从 9router#344 移植，感谢 @diegosouzapw) +- **fix(executors): 为 qwen 非流式/thinking Claude-Code 请求剥离 `stream_options`** — Claude-Code 兼容服务商在 executor 级别强制开启 `stream` 标志，而出站请求体保留了调用方原始的 `stream: false`，因此 `DefaultExecutor.transformRequest` 向仍声明 `stream: false` 的请求体注入了 `stream_options: { include_usage: true }`，qwen 拒绝并返回 `400 "'stream_options' only set this when you set stream: true"`。executor 现在在请求体实际 `stream` 为 false 时剥离 `stream_options`。([#4374](https://github.com/diegosouzapw/OmniRoute/pull/4374) — 从 9router#663 移植，感谢 @anuragg-saxenaa / @diegosouzapw) +- **fix(executors): 当 `tool_choice` 强制使用工具时不再注入 `thinking`（原生 Claude）** — Claude-Code 网络镜像模拟会为非 Haiku 的 Claude 模型注入 `thinking: { type: "adaptive" }`，但 Anthropic 在 `tool_choice` 强制使用特定工具（`{type:"any"|"tool"}`）时会拒绝 `thinking`，返回 `400 "Thinking may not be enabled when tool_choice forces tool use."`。任何固定工具的 Opus/Sonnet 调用（例如 Claude Code 的 `message_user`，或强制使用工具的代理工具）都会遇到硬性 400 错误；当 `tool_choice` 强制使用工具时，现在会抑制该注入。([#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) — 感谢 @NomenAK) +- **fix(codex): 在 Codex Responses 请求中请求推理摘要** — Codex/OpenAI Responses 会返回推理 token 统计信息和空推理项，除非请求了可见的推理摘要，因此 Codex CLI / pi.dev 路径会丢失可见的思考文本。OmniRoute 现在在启用推理时请求 `reasoning.summary: "auto"`（并包含 `reasoning.encrypted_content`）— 保留客户端显式设置的 `reasoning.summary` 和现有的 `include` 条目，并在 `reasoning.effort: "none"` 时跳过。([#4359](https://github.com/diegosouzapw/OmniRoute/pull/4359) — 感谢 @xz-dev) +- **fix(sse): 将组合的每目标超时默认设为 120s 以实现快速故障转移** — 当组合未设置 `targetTimeoutMs` 时，组合的每目标超时继承了完整的 `FETCH_TIMEOUT_MS`（默认 600s），因此单个挂起/缓慢的目标（例如返回 524/504 的 openai-compatible 上游）可能使**整个**组合停滞长达 10 分钟才能进行故障转移。现在使用新的 `DEFAULT_COMBO_TARGET_TIMEOUT_MS = 120_000` 作为 `resolveComboTargetTimeoutMs` 中未设置时的默认值（向后兼容的第三个参数，在 `phaseComboSetup` 中接入）；显式上限/退出选项得以保留。([#4365](https://github.com/diegosouzapw/OmniRoute/pull/4365) — 感谢 @diegosouzapw) +- **fix(cli): Tailscale 登录现在遵循 `TAILSCALE_AUTHKEY` 实现非交互式登录** — `startTailscaleLogin` 构建 `tailscale up` 时从未读取 `process.env.TAILSCALE_AUTHKEY`，因此在预先认证/无头守护进程上，登录会等待交互式认证 URL 并超时（约 15s）。当设置了 `TAILSCALE_AUTHKEY` 时，现在通过 `--auth-key=` 传递（作为 spawn argv 元素 — 不进行 shell 插值），守护进程可以非交互式认证；未设置时行为不变。([#4343](https://github.com/diegosouzapw/OmniRoute/pull/4343) — 感谢 @ipeterpetrus) +- **fix(dashboard): OAuth 模态框在非 JSON 服务器响应时显示真实错误** — OAuth 连接/重认证模态框无条件调用 `await res.json()`，因此当构建/OAuth 端点返回纯文本错误时（如 `500 Internal Server Error` 页面），模态框抛出 `Unexpected token 'I'…` 并隐藏了真实故障。两个共享辅助函数（`src/shared/utils/api.ts` 中的 `parseResponseBody` / `getErrorMessage`）现在安全地读取响应体（JSON 时按 JSON 解析，否则按原始文本处理），并在任何情况下都呈现清晰的消息；所有模态框的 fetch 调用点都使用了这些辅助函数。([#4351](https://github.com/diegosouzapw/OmniRoute/pull/4351) — 感谢 @DNNYF) +- **fix(dashboard): 已禁用连接的最近错误现在可见** — 服务商 卡片's 错误 徽章 counts a disabled 连接 (`isActive === false`) that has an 错误 (its effective status is still 错误/expired/unavailable), but the 连接 row hid the `lastError` text for disabled rows — so the operator saw the 错误 count without being able to see what failed. The row now shows the 错误 text whenever there is one, regardless of the active 开关. ([#4352](https://github.com/diegosouzapw/OmniRoute/pull/4352) — 感谢 @ntdung6868) +- **fix(providers): "逐一测试连接" OAuth 探测不再永久卡住队列** — OAuth 连接测试路径调用了裸 `fetch(url, { method, headers })`，没有 `AbortController`/signal/timeout，因此当服务商的探测端点接受 socket 但永不响应时，await 的 fetch 永远不会完成，逐一测试队列会无限期停滞（API-key 路径已通过 `validateProviderApiKey` 的 `timeoutMs` 设置了边界）。现在初始探测和刷新后的重试都设置了 `AbortSignal.timeout(30s)` 边界 — 与 API-key 路径的 30s 预算一致 — 超时探测会以失败形式返回，并附上清晰的 `Test timed out after 30s` 消息，格式与其他测试错误相同。([#4347](https://github.com/diegosouzapw/OmniRoute/pull/4347) — 感谢 @ntdung6868) +- **fix(providers): 已停用账户与已吊销 token 被区分标识** — 一个 OAuth 刷新完全正常但 ChatGPT 账户已被服务商停用的 Codex 连接会从上游 API 收到 `401`。连接测试将其与错误凭证等同标记（`Token invalid or revoked` → `upstream_auth_error`），因此操作者无法区分已停用账户和已吊销 token。现在测试会读取 `401`/`403` 的响应体，当表明账户停用时，将其归类为 `account_deactivated` — 控制台已将其呈现为"账户已停用"。普通认证 `401` 保持不变。([#4353](https://github.com/diegosouzapw/OmniRoute/pull/4353) — 感谢 @ntdung6868) +- **fix(db): 删除服务商时级联清理孤立的模型别名** — 删除自定义服务商时会移除其连接和节点，但会留下已导入的模型别名行（存储为 `key=`、`value="/<模型>"`）。这些过时的别名随后会阻止重新导入同一服务商 — 导入去重将它们视为"已存在"，因此不会出现新的模型。新的 `deleteModelAliasesForProvider(providerId)` DB 辅助函数会删除所有存储值以 `/` 开头的别名（不影响其他服务商和用户定义的 settings 别名），服务商节点 DELETE 处理器现在在移除连接和节点后调用该函数，确保重新导入不受阻碍。([#4348](https://github.com/diegosouzapw/OmniRoute/pull/4348) — 感谢 @nguyenvanhuy0612) +- **fix(api): 添加自定义模型时持久化 `max_input_tokens` / `max_output_tokens`** — `POST /api/provider-models` 静默丢弃了"添加自定义模型"表单中设置的每模型 token 限制：处理器解构了请求体的其余部分，但从未读取 `max_input_tokens` / `max_output_tokens`，且 `addCustomModel()` 没有对应参数，因此这些值在写入时被丢弃。DB 层（`inputTokenLimit` / `outputTokenLimit`）和 `/v1/models` 目录已经能对这些字段进行往返 — 只有写入路径缺失。验证 schema 现在接受这两个可选限制，处理器转发它们，`addCustomModel()` 持久化它们，使自定义模型的上下文/输出窗口能保留在目录中。([#4349](https://github.com/diegosouzapw/OmniRoute/pull/4349) — 感谢 @codename-zen) +- **fix(plugin): OpenCode 静态目录插件为组合/原始模型键添加服务商 ID 前缀** — OpenCode 的静态目录读取器错误检测了 `omniroute` 服务商：以 `combo/MASTER` 形式发出的组合键被解析为服务商 `combo`（"No credentials for provider: omniroute"），而裸 `MASTER` 形式被误读为无法解析服务商的模型，混合的 `omniroute/MASTER` + 裸原始键被 OpenCode 的 schema 拒绝。插件现在为每个组合和原始模型键添加 `omniroute` 服务商 ID 前缀，显式发出服务商 ID，并丢弃旧的 `combo/` 前缀 — 因此静态目录读取器能检测到服务商，认证加载器返回正确的凭证（目录获取超时也已提高，使冷启动服务器不会发布空存根）。([#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) — 感谢 @herjarsa) ### 🔒 安全 -- **fix(security): scope the OAuth callback `postMessage` to a trusted-origin allowlist** — the OAuth callback at `/callback` previously posted `{ code, state, … }` to `window.opener.postMessage(…, "*")` whenever the opener was cross-origin, so a hostile page that opened the well-known redirect URI in a popup could receive the OAuth code/state and complete the flow as the user. The wildcard fallback is replaced with iteration over a fixed allowlist (same-origin + Codex's `localhost:1455` / `127.0.0.1:1455` loopback helper); the browser silently drops `postMessage` to any opener whose origin isn't listed. ([#4372](https://github.com/diegosouzapw/OmniRoute/pull/4372) — ported from 9router#998, thanks @aeonframework / @diegosouzapw) -- **fix(mitm): exact host membership in the MITM hosts test (CodeQL false positive)** — `tests/unit/mitm-tool-hosts.test.ts` checked host membership with `Array.includes(host)`, which CodeQL's `js/incomplete-url-substring-sanitization` heuristic misreads as a `String.includes()` URL-substring sanitization test (HIGH false positive). Switched to `.some((h) => h === host)` — identical semantics, no flagged pattern. ([#4386](https://github.com/diegosouzapw/OmniRoute/pull/4386)) +- **fix(security): 将 OAuth 回调的 `postMessage` 限定为可信来源白名单** — `/callback` 处的 OAuth 回调此前在 opener 跨域时向 `window.opener.postMessage(…, "*")` 发送 `{ code, state, … }`，因此恶意页面如果以弹窗形式打开众所周知的回调 URI，就能接收 OAuth code/state 并以用户身份完成流程。通配符回退已被替换为遍历固定白名单（同源 + Codex 的 `localhost:1455` / `127.0.0.1:1455` loopback helper）；浏览器会静默丢弃向白名单外的任何 opener origin 发送的 `postMessage`。([#4372](https://github.com/diegosouzapw/OmniRoute/pull/4372) — 从 9router#998 移植，感谢 @aeonframework / @diegosouzapw) +- **fix(mitm): 在 MITM 主机测试中使用精确主机匹配（CodeQL 误报）** — `tests/unit/mitm-tool-hosts.test.ts` 使用 `Array.includes(host)` 检查主机成员，CodeQL 的 `js/incomplete-url-substring-sanitization` 启发式规则将其误读为 `String.includes()` URL 子串清理测试（严重误报）。切换为 `.some((h) => h === host)` — 语义相同，且不会触发标志模式。([#4386](https://github.com/diegosouzapw/OmniRoute/pull/4386)) ### 📝 维护 -- **docs: one-time feature-documentation catch-up (v3.8.20 → v3.8.30)** — reconciled the docs with every user-facing feature shipped since v3.8.20: a new README **✨ What's New** section; new guides for [CLI integrations](docs/guides/CLI-INTEGRATIONS.md), [MITM TPROXY transparent decrypt](docs/security/MITM-TPROXY-DECRYPT.md) and [delegated Anthropic Context Editing](docs/compression/CONTEXT_EDITING.md); refreshed AUTO-COMBO (`auto/:` + Arena-ELO), API_REFERENCE (`x-omniroute-no-memory`), MEMORY (int8 quantization, off-by-default), RESILIENCE (model-lockout success-decay), RTK, AGENTBRIDGE, TRAFFIC_INSPECTOR, GUARDRAILS, CLOUD_AGENT, ENVIRONMENT; regenerated PROVIDER_REFERENCE (231 providers) and synced the provider count in README/CLAUDE/AGENTS. Going forward this runs every release (generate-release step 6b). ([#4391](https://github.com/diegosouzapw/OmniRoute/pull/4391)) -- **refactor(chatCore): extract the `checkHeapPressureGuard` leaf (god-file decomposition start)** — first increment of decomposing `chatCore.ts` (~5127 LOC, the hottest path — every chat request flows through `handleChatCore`). The V8 heap-pressure guard at the top of `handleChatCore` (rejects with 503 when `heapUsed` exceeds the shed threshold) is moved to a self-contained, co-located `utils/heapPressure.ts::checkHeapPressureGuard(...)` with no behavior change. ([#4371](https://github.com/diegosouzapw/OmniRoute/pull/4371) — thanks @diegosouzapw) -- **refactor(combo): de-dup the exhausted-target skip predicate across both dispatchers** — the byte-identical `#1731`/`#1731v2` pre-check (skip a target already exhausted on the provider/connection within a request) lived in both combo dispatchers; extracted to a shared `combo/comboPredicates.ts` helper. ([#4362](https://github.com/diegosouzapw/OmniRoute/pull/4362) — thanks @diegosouzapw) -- **refactor(combo): de-dup the upstream-error exhaustion classification across both dispatchers** — both dispatchers ran a near-identical post-error block classifying the upstream error and updating the exhaustion Sets (`#1731` provider exhausted / `#1731v2` connection error / transient rate-limited); extracted to a shared `combo/targetExhaustion.ts::applyComboTargetExhaustion(...)`. ([#4366](https://github.com/diegosouzapw/OmniRoute/pull/4366) — thanks @diegosouzapw) -- **chore(cli): localize CLI / scraping copy and stabilize fetch, memory & coverage handling** — localizes CLI and scraping UX copy plus the Adapta onboarding tutorial (and corrects the CLI Code page title), makes fetch retries honor the start timeout, tightens SSE/response typing, respects configured memory token limits during search, and reduces CI coverage-merge memory by merging V8 data incrementally. ([#4383](https://github.com/diegosouzapw/OmniRoute/pull/4383) — thanks @JxnLexn) -- **test(combo): reset circuit breakers between stream-readiness cases (restore green)** — a stream-readiness fallback case failed on the release branch since the cycle-open tip due to test isolation: earlier combo-dispatch cases in the same file deliberately fail `glm` (tripping the module-level provider circuit breaker), and that OPEN state leaked into the next test so `combo.ts` skipped the model. The test now resets the circuit breakers between cases. ([#4396](https://github.com/diegosouzapw/OmniRoute/pull/4396) — thanks @diegosouzapw) -- **chore(quality): reconcile the complexity ratchet baseline (1896 → 1900)** — absorbs the small complexity-metric increase from the v3.8.31 `/review-prs` merge batch into `quality-baseline.json` so the ratchet reflects the shipped code (no production change). ([#4410](https://github.com/diegosouzapw/OmniRoute/pull/4410) — thanks @diegosouzapw) -- **test/gate: reconcile release-time drift surfaced by the full CI gate** — three already-merged changes left the release branch's full-CI gate red (the per-PR fast gates don't run it): the Gemini `convertOpenAIContentToParts` tests were realigned to the [#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) HTTP/HTTPS-URL `fileData` pass-through (they still asserted the old warn-and-drop behavior), the `t11` any-budget for `open-sse/executors/base.ts` was raised to 2 with a justification ([#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) compares `tool_choice` against the string literal `"any"`, not a TS `any` type), and the [#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) opencode-plugin combos test's net-assert reduction (dropping the obsolete `combo/` namespace) was allowlisted. No production behavior change. (thanks @diegosouzapw) +- **docs: 一次性功能文档补全（v3.8.20 → v3.8.30）** — 将所有自 v3.8.20 以来发布的面向用户功能与文档对齐：新增 README **✨ What's New** 章节；新增 [CLI 集成](docs/guides/CLI-INTEGRATIONS.md)、[MITM TPROXY 透明解密](docs/security/MITM-TPROXY-DECRYPT.md)和[代理 Anthropic 上下文编辑](docs/压缩/CONTEXT_EDITING.md)指南；刷新 AUTO-COMBO（`auto/:` + Arena-ELO）、API_REFERENCE（`x-omniroute-no-memory`）、MEMORY（int8 量化，默认关闭）、RESILIENCE（模型锁定成功衰减）、RTK、AGENTBRIDGE、TRAFFIC_INSPECTOR、GUARDRAILS、CLOUD_AGENT、ENVIRONMENT；重新生成 PROVIDER_REFERENCE（231 服务商）并同步 README/CLAUDE/AGENTS 中的服务商数量。今后每次发版都会运行此项（generate-release 步骤 6b）。([#4391](https://github.com/diegosouzapw/OmniRoute/pull/4391)) +- **refactor(chatCore): 提取 `checkHeapPressureGuard` 叶子函数（巨型文件分解的开始）** — 分解 `chatCore.ts`（约 5127 行，最热路径 — 每个聊天请求都经过 `handleChatCore`）的第一步。`handleChatCore` 顶部的 V8 堆内存压力守卫（当 `heapUsed` 超过丢弃阈值时拒绝并返回 503）被移至一个独立、同目录的 `utils/heapPressure.ts::checkHeapPressureGuard(...)`，行为无变化。([#4371](https://github.com/diegosouzapw/OmniRoute/pull/4371) — 感谢 @diegosouzapw) +- **refactor(combo): 在两个调度器中消除已耗尽目标跳过谓词的重复** — 字节完全相同的 `#1731`/`#1731v2` 预检查（跳过请求中已在服务商/连接上耗尽的目标）存在于两个组合调度器中；已提取为共享的 `Combo/comboPredicates.ts` 辅助函数。([#4362](https://github.com/diegosouzapw/OmniRoute/pull/4362) — 感谢 @diegosouzapw) +- **refactor(combo): 在两个调度器中消除上游错误耗尽分类的重复** — 两个调度器都运行了几乎相同的错误后处理代码块，对上游错误进行分类并更新耗尽集合（`#1731` 服务商耗尽 / `#1731v2` 连接错误 / 瞬时速率限制）；已提取为共享的 `Combo/targetExhaustion.ts::applyComboTargetExhaustion(...)`。([#4366](https://github.com/diegosouzapw/OmniRoute/pull/4366) — 感谢 @diegosouzapw) +- **chore(cli): 本地化 CLI / 抓取文案并稳定 fetch、内存和覆盖率处理** — 本地化 CLI 和抓取 UX 文案以及 Adapta 入门教程（并修正 CLI Code 页面标题），使 fetch 重试遵循启动超时，收紧 SSE/响应类型，在搜索期间遵循配置的内存 token 限制，并通过增量合并 V8 数据减少 CI 覆盖率合并内存开销。([#4383](https://github.com/diegosouzapw/OmniRoute/pull/4383) — 感谢 @JxnLexn) +- **test(combo): 在流就绪测试用例之间重置熔断器（恢复绿色状态）** — 一个流就绪回退用例在发版分支上失败，原因是测试隔离问题：同一文件中较早的组合调度用例故意使 `glm` 失败（触发模块级服务商熔断器），该 OPEN 状态泄露到了下一个测试，因此 `Combo.ts` 跳过了模型。测试现在在用例之间重置熔断器。([#4396](https://github.com/diegosouzapw/OmniRoute/pull/4396) — 感谢 @diegosouzapw) +- **chore(quality): 对齐复杂度基准线（1896 → 1900）** — 将 v3.8.31 `/review-prs` 合并批次带来的小幅复杂度指标增长吸收到 `quality-baseline.json` 中，使基准线反映已发布的代码（无生产变更）。([#4410](https://github.com/diegosouzapw/OmniRoute/pull/4410) — 感谢 @diegosouzapw) +- **test/gate: 对齐完整 CI 门禁发现的发版时漂移** — 三个已合并的变更导致发版分支的完整 CI 门禁变红（各 PR 的快速门禁不会运行）：Gemini `convertOpenAIContentToParts` 测试已与 [#4373](https://github.com/diegosouzapw/OmniRoute/pull/4373) 的 HTTP/HTTPS-URL `fileData` 透传对齐（它们之前仍断言旧的 warn-and-drop 行为），`open-sse/executors/base.ts` 的 `t11` any 预算提升至 2 并附有理由（[#4389](https://github.com/diegosouzapw/OmniRoute/pull/4389) 将 `tool_choice` 与字符串字面量 `"any"` 比较，而非 TS `any` 类型），[#4384](https://github.com/diegosouzapw/OmniRoute/pull/4384) 的 opencode 插件组合测试的网络断言减少（删除已废弃的 `Combo/` 命名空间）已加入白名单。无生产行为变更。（感谢 @diegosouzapw） --- @@ -750,93 +750,93 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(dashboard): category (media serviceKind) filter on the providers page** — `/dashboard/providers` gains a media-category filter row (Image / Video / Music / Text→Speech / Speech→Text / Embedding) that composes with the existing search, free-only and "show configured only" filters. Membership is derived from the backend media registries (a provider that serves a kind is surfaced even if it never declared `serviceKinds`), keeping the UI in lockstep with the backend. ([#4240](https://github.com/diegosouzapw/OmniRoute/issues/4240)) -- **feat(combo): per-step account allowlist — scope a round-robin/weighted step to a subset of a provider's connections** — a combo model step can now carry a first-class account allowlist so a round-robin (or weighted) strategy is scoped to a chosen subset of a provider's connections (e.g. only `foo1`+`foo2` out of `foo1..foo4`) without hand-pinning one step per account. Empty = the whole active pool (unchanged). When a step both has an allowlist and is tag-routed, the two intersect (most-restrictive wins); a single pinned account still takes precedence. The combo builder's Precision step editor gains an optional "Restrict to accounts" picker. ([#3266](https://github.com/diegosouzapw/OmniRoute/issues/3266)) -- **feat(providers): add OpenAdapter, dit.ai and TokenRouter as OpenAI-compatible providers** — three community-requested OpenAI-compatible aggregators now register as standard named OpenAI-style providers with live `/v1/models` discovery (the zenmux pattern), falling back to a seeded catalog when the upstream list is unavailable: **OpenAdapter** (`https://api.openadapter.in/v1`, free tier, 70+ open-source models — [#4239](https://github.com/diegosouzapw/OmniRoute/issues/4239)), **dit.ai** (`https://api.dit.ai/v1`, dynamic-pricing router/gateway — [#4155](https://github.com/diegosouzapw/OmniRoute/issues/4155)), and **TokenRouter** (`https://api.tokenrouter.com/v1`, free MiniMax model — [#3841](https://github.com/diegosouzapw/OmniRoute/issues/3841), thanks @FerLuisxd). No custom executor/translator — default OpenAI passthrough. -- **feat(api): `x-omniroute-no-memory` request header — per-request opt-out of memory/skills injection** — clients that manage their own context (e.g. their own RAG/memory) can send `x-omniroute-no-memory: true` (mirrors the existing `x-omniroute-no-cache` convention) to skip the gateway injecting up to `memorySettings.maxTokens` (~2k) tokens of memory **and** skills context into that chat request — avoiding the token/cost inflation it otherwise adds on every call. Absent the header, behavior is unchanged. (PRD-2026-06-19-no-memory-header) -- **feat(dashboard): MITM tool card lists the exact hosts-file entries to add manually** — the CLI-tools MITM card's "How it works" section now lists the full set of `127.0.0.1 ` lines for the selected tool (sourced from the canonical MITM target registry) instead of a single example domain. Users on locked-down machines — where the automatic, sudo-gated hosts-file edit isn't available — can now copy every required entry by hand. (thanks @mrcyclo) -- **feat(cli): `omniroute launch-codex` + `setup-codex` — run/configure the Codex CLI against OmniRoute** — a launcher and setup command that point the Codex CLI at an OmniRoute endpoint (remote-mode aware). ([#4270](https://github.com/diegosouzapw/OmniRoute/pull/4270)) -- **feat(cli): Claude Code launcher + setup — remote mode + profiles** — `omniroute launch`/`setup` for Claude Code with remote-mode support and named connection profiles. ([#4274](https://github.com/diegosouzapw/OmniRoute/pull/4274)) -- **feat(cli): OpenCode setup — OpenAI-compatible provider + remote-aware plugin** — `setup-opencode` registers OmniRoute as an OpenAI-compatible provider for OpenCode and installs a remote-aware plugin. ([#4277](https://github.com/diegosouzapw/OmniRoute/pull/4277)) -- **feat(cli): one-command setup for popular AI coding tools** — new `setup-*` commands that configure each tool to talk to OmniRoute: **Cline** ([#4280](https://github.com/diegosouzapw/OmniRoute/pull/4280)), **Kilo Code** ([#4284](https://github.com/diegosouzapw/OmniRoute/pull/4284)), **Continue** ([#4289](https://github.com/diegosouzapw/OmniRoute/pull/4289)), **Cursor** ([#4291](https://github.com/diegosouzapw/OmniRoute/pull/4291)), **Roo Code** ([#4292](https://github.com/diegosouzapw/OmniRoute/pull/4292)), **Crush** ([#4298](https://github.com/diegosouzapw/OmniRoute/pull/4298)), **Goose** ([#4300](https://github.com/diegosouzapw/OmniRoute/pull/4300)), **Qwen Code** ([#4301](https://github.com/diegosouzapw/OmniRoute/pull/4301)), **Aider** ([#4302](https://github.com/diegosouzapw/OmniRoute/pull/4302)) and the **Gemini CLI** (native `/v1beta`) ([#4303](https://github.com/diegosouzapw/OmniRoute/pull/4303)). -- **feat(providers): provider model sweep — live discovery, refreshed catalogs, dead-provider cleanup** — a broad sweep that enables live `/v1/models` discovery for more OpenAI-style providers (the zenmux pattern), refreshes the seeded catalogs with current models, and marks dead providers `deprecated`. ([#4324](https://github.com/diegosouzapw/OmniRoute/pull/4324)) -- **feat(mitm): translate Antigravity cloudcode end-to-end (Gap B)** — the MITM decrypt path now translates Antigravity `cloudcode` traffic end-to-end. ([#4299](https://github.com/diegosouzapw/OmniRoute/pull/4299)) -- **feat(keys): per-key USD usage quota controls** — an API key can now carry a USD spend quota that caps its usage once the threshold is reached. ([#4327](https://github.com/diegosouzapw/OmniRoute/pull/4327) — thanks @Witroch4) - -### 🔧 Changed - -- **change(memory): memory is now OFF by default** — `DEFAULT_MEMORY_SETTINGS.enabled` now defaults to `false`. Enabling memory injects up to ~2,000 tokens of retrieved context into **every** chat request (and that context is billed), which was a surprising default for new installs and for clients with their own context. Memory is now an explicit opt-in: installs that already enabled it keep it on; installs that never configured it default to off. The Settings → Memory panel now shows a token-cost warning when memory is enabled. (PRD-2026-06-19-no-memory-header) - -### 🐛 Fixed - -- **fix(translator): Gemini accepts HTTP/HTTPS image URLs (no longer silently dropped)** — OpenAI-style `image_url` parts whose URL was `http://…` or `https://…` reached `convertOpenAIContentToParts` (the OpenAI→Gemini request helper) and were dropped with only a `console.warn`, because Gemini's `inlineData` requires base64 and the helper is synchronous (it cannot fetch + encode). Gemini's `Part` schema, however, natively accepts `fileData: { fileUri }` for remote URIs — the model fetches the asset itself. The helper now emits a `fileData` part (`mimeType: "image/*"`, inferred upstream on fetch) instead of dropping, so vision requests that pass a URL — not a data: URI — now reach Gemini intact. `data:` URIs still go through `inlineData` unchanged; unsupported schemes (e.g. `ftp:`) are still skipped. (thanks @East-rayyy) -- **fix(security): OAuth callback page no longer relays `code`/`state` to a wildcard `postMessage` target** — the OAuth callback at `/callback` posted `{ code, state, ... }` to `window.opener.postMessage(..., "*")` whenever the opener was cross-origin (a fallback for the legitimate remote-dashboard + local-loopback callback scenario). A hostile page that opened the callback URL in a popup against the well-known redirect URI would therefore receive the OAuth code+state and could complete the OAuth flow as the user. The wildcard fallback is replaced with an iteration over a fixed allowlist of trusted target origins (same-origin + Codex's loopback helper at `localhost:1455` / `127.0.0.1:1455`); the browser silently drops the message for any opener whose origin is not in the list. Methods 2 (`BroadcastChannel`) and 3 (`localStorage`) — already in the page — still cover same-origin parents when the opener was severed by COOP. (thanks @aeonframework) -- **fix(compliance): startup cleanup honors the dashboard data-retention setting instead of always trimming to 7 days** — on every restart, `cleanupExpiredLogs()` (run at startup) read retention only from the `CALL_LOG_RETENTION_DAYS` / `APP_LOG_RETENTION_DAYS` env vars, which default to **7 days** when unset, and trimmed `usage_history` (the Usage Analysis data) before the dashboard-based `runAutoCleanup()` — which respects the configured retention — ever ran. So a dashboard "Data Retention" of 90 days was silently overridden and the Usage Analysis page only ever showed the last 7 days after a restart. Retention now follows the precedence **explicit env var → dashboard DB setting → 7-day default**, per table (`usage_history`→`usageHistory`, `call_logs`/`proxy_logs`/`request_detail_logs`→`callLogs`, `mcp_tool_audit`→`mcpAudit`); an operator who sets the env var still wins, and non-DB deployments still fall back to it. ([#4354](https://github.com/diegosouzapw/OmniRoute/issues/4354) — thanks @akbardwi) -- **fix(providers): bailian-coding-plan static fallback catalog matches the registry (10 models)** — the provider-model sweep (#4324) added four current Model Studio coding-plan models (`qwen3.7-plus`, `qwen3-coder-plus`, `qwen3-coder-next`, `glm-4.7`) to the `bailian-coding-plan` registry entry but missed the static fallback mirror in `staticModels.ts`, which still listed only the older six. The static catalog (served when live discovery is unavailable) therefore diverged from the registry, and the existing static↔registry parity test went red on the release branch (only surfacing when test-impact analysis happened to select it). The static mirror now carries all ten models in registry order, restoring parity. ([#4324](https://github.com/diegosouzapw/OmniRoute/pull/4324)) -- **fix(executors): ArenaLLM accepts LMArena's split Supabase SSR auth cookie** — LMArena migrated to `@supabase/ssr` chunked auth cookies: the single `arena-auth-prod-v1` cookie is now empty and the real session is split across `arena-auth-prod-v1.0`, `arena-auth-prod-v1.1`, … (ascending). A user who pasted the (now-empty) single cookie therefore sent an empty session and upstream rejected it as "invalid cookie". The LMArena executor now reconstructs the single cookie from its chunks — reading `.0`, `.1`, … in ascending numeric order until one is missing and concatenating their raw values (`@supabase/ssr`'s `combineChunks` rule: plain `join("")`, no base64-decode, no JSON-parse, the `base64-` prefix kept verbatim) — while preserving the rest of the pasted jar. A non-empty single cookie is still forwarded unchanged (back-compat). The credential UX now instructs pasting the **full Cookie header** and tracks the `.0`/`.1` storage keys. ([#4271](https://github.com/diegosouzapw/OmniRoute/issues/4271) — thanks @caussao) -- **fix(compression): preserve the cacheable prefix for automatic-cache providers** — OpenAI / Codex (and Azure-OpenAI) use _automatic_ prefix caching: the upstream caches the longest matching prefix of a request (system prompt + earliest messages) **without** any explicit `cache_control` markers in the body. The cache-aware compression guard only protected that prefix when the request carried explicit `cache_control`, so for automatic-cache providers the guard was skipped — and with compression enabled and `preserveSystemPrompt: false` (or a prefix-compressing mode like `aggressive`/`ultra`) it rewrote the system prompt / earliest messages, guaranteeing a cache miss and **higher** token spend through OmniRoute than going direct. The guard now treats a caching provider as sufficient on its own (`isCachingProvider` alone, independent of `cache_control`) to skip the system prompt and downgrade prefix-compressing modes, and OpenAI/Codex/Azure are now recognized as caching providers. Compression is still off by default — this only affects operators who enabled it with prefix preservation turned off. ([#3955](https://github.com/diegosouzapw/OmniRoute/issues/3955)) -- **fix(executors): DuckDuckGo AI Chat uses duckduckgo.com (fixes 400)** — the DuckDuckGo AI Chat executor fetched status/chat and set `Origin`/`Referer` against `https://duck.ai` while still sending `Sec-Fetch-Site: same-origin`, so the request's same-origin triplet (host + Origin + Referer) was inconsistent and the backend rejected it with HTTP 400. All current DDG reverse-engineering references — and the provider registry's own `baseUrl` — use `https://duckduckgo.com`; the executor now uses it consistently for the status URL, chat URL, `Origin`, and `Referer` (the same-origin header is now coherent). The `x-fe-version` scrape regex also required a 40-hex tail but the real served token has a 20-hex tail (e.g. `serp_20250401_100419_ET-19d438eb199b2bf7c300`), so it silently fell back to a hardcoded default; the pattern is relaxed to a bounded `{20,40}` tail (still ReDoS-safe). This addresses the DuckDuckGo half of the report; the separate Chipotle/`chipotle` upstream breakage is tracked independently. ([#4037](https://github.com/diegosouzapw/OmniRoute/issues/4037) — thanks @daniij) -- **fix(security): bound the prompt-injection scan to the first 16 KB (hot-path perf)** — the prompt-injection guard joined every message/system string into one buffer and ran several regexes over the **whole** thing on every chat request, with no size cap — so a 300 KB body (pasted code, RAG context) meant O(body) CPU scanning on the hot path, a self-inflicted latency/GC source under concurrency. Both detection call sites (`detectInjection` in `inputSanitizer.ts` and the custom-pattern scan in `promptInjection.ts`) now slice the joined text to the first **16 KB** (`MAX_INJECTION_SCAN_BYTES`) before the regex loop. Injection directives sit near the top of a prompt, so the generous cap preserves real detection while scanning only a bounded prefix; the existing 10 MB body-size cap (which protects ingestion) is unchanged. ([#3932](https://github.com/diegosouzapw/OmniRoute/issues/3932) — thanks @KooshaPari) -- **fix(sse): retry direct-connection socket failures on a fresh socket (fewer `502` bursts)** — the default direct-connection undici dispatcher pools keep-alive sockets for up to 4 s, but some edges (e.g. `nvidia`, `opencode-zen`) silently close idle keep-alive sockets within that window, so the next request reusing a pooled socket fails with `UND_ERR_SOCKET` ("other side closed") — in bursts. `proxyFetch` already retried once on such transient errors, but the retry reused the **same** pooled dispatcher and could grab another stale socket, then fell through to native fetch (which also pools) → the job sat in the rate-limit queue until the 30 s timeout → `502` + circuit-breaker open. The retry now uses a dedicated **no-keep-alive / no-pipelining** dispatcher so it opens a brand-new socket that can't be a dead pooled one; the first attempt still uses the pooled dispatcher (healthy keep-alive reuse is preserved). Complements the v3.8.29 diagnostics (`describeFetchCause`, #4281). ([#4252](https://github.com/diegosouzapw/OmniRoute/issues/4252) — thanks @klimadev) -- **fix(sse): combo now stops at the first body-specific 400 instead of trying every target** — the `#2101` guard that detects a body-specific 400 (context overflow / malformed / model-access-denied, e.g. "model is not supported when using Codex with a ChatGPT account") logged "stopping combo" but executed a bare `break`, which only exited the inner retry loop; `executeTarget` then returned `null` and the outer target loop treated that as "this target produced nothing" and advanced to the next model. A combo of N targets that all reject the same request body therefore marched through all N (the report shows a 143-model Codex combo iterating every target), wasting upstream calls and per-attempt work. The guard now surfaces the 400 via the `{ ok, response }` contract (mirroring the 499 client-disconnect path) so the combo resolves and stops immediately. ([#4279](https://github.com/diegosouzapw/OmniRoute/issues/4279)) -- **fix(sse): non-streaming combo over a Responses-API target no longer returns empty content** — a Responses-API target (codex/`cx`) streams from upstream even on `stream:false`, and its terminal `response.completed` snapshot can carry a non-empty `output` that lacks the assistant message item (e.g. only a `reasoning` item) while the streamed `output_text` deltas had reconstructed the full message. The SSE→JSON aggregator preferred the terminal `output` wholesale, dropping the reconstructed text → HTTP 200 with empty content (hit notably via n8n, which defaults to `stream:false`). The aggregator now falls back to the reconstructed delta output when the terminal output has no message item but the reconstruction does; the terminal snapshot still wins whenever it already carries the message. ([#3948](https://github.com/diegosouzapw/OmniRoute/issues/3948)) -- **fix(executors): preserve tool-name casing on native Claude OAuth (`read` no longer leaks back as `Read`)** — native Claude OAuth traffic runs through an anti-fingerprint tool-name cloak that renames a tool literally named `read` to `Read` on the wire and records the reverse alias on a non-enumerable `_toolNameMap`, which the response side uses to restore the client's original casing. Since v3.8.27 the executor returned a JSON-round-tripped copy of the body as `transformedBody`, and that round-trip dropped the non-enumerable map — so the restore saw an empty map and the cloaked `Read` streamed verbatim to the client, corrupting the tool name. The executor now re-attaches the cloak map onto the serialized body (mirroring the Antigravity executor), so tool-name casing round-trips correctly. ([#4307](https://github.com/diegosouzapw/OmniRoute/issues/4307) — thanks @dev-cj) -- **fix(api): cache-HIT `X-OmniRoute-Response-Cost` now reports the incremental cost (≈0), not the original** — on a semantic-cache HIT the gateway serves the stored response **without** an upstream call, but `X-OmniRoute-Response-Cost` was reporting the original call's full cost (recomputed from the cached `usage`). A consumer summing `response-cost` for billing was therefore charging for responses that cost ≈$0 to serve (and stale entries could inflate it). Cache hits now bill `X-OmniRoute-Response-Cost: 0.0000000000` (the real incremental cost), and the avoided cost is surfaced in a new **`X-OmniRoute-Cost-Saved`** header for cache analytics — mirroring the existing `tokens_saved` concept. The MISS path is unchanged. (PRD-2026-06-19-cache-hit-cost-reporting) -- **fix(models): imported vision-capable models keep their vision capability** — after importing a provider key, vision-capable models (e.g. OpenRouter models whose `architecture` declares image input, and other synced providers) were listed as text-only in `/v1/models` and the dashboard — even though image requests actually worked. Synced model records never captured the vision flag, and the catalog's OpenRouter live-enrichment (which derives vision from `architecture.input_modalities`) is skipped once a provider has synced models. Discovery now captures `supportsVision` at sync time (from `architecture.input_modalities`, the string `architecture.modality`, or a top-level `input_modalities`), mirroring the existing `supportsThinking` capture, and the catalog surfaces `capabilities.vision` for synced models. ([#4264](https://github.com/diegosouzapw/OmniRoute/issues/4264) — thanks @FerLuisxd) -- **fix(providers): Cloudflare Workers AI model discovery shows model names, not UUIDs** — importing a Cloudflare Workers AI key listed models with internal UUID identifiers (e.g. `429b9e8b-d99e-…`) instead of their usable slugs (`@cf/meta/llama-3.1-8b-instruct`). Cloudflare's `/ai/models/search` returns `{ id: "", name: "@cf/…" }`, and discovery was passing the raw objects through — so the UUID `id` became the callable model id. The `cloudflare-ai` discovery now maps each result's `name` → id, surfacing the real `@cf/…` model ids. ([#4259](https://github.com/diegosouzapw/OmniRoute/issues/4259) — thanks @FerLuisxd) -- **fix(translator): clamp Responses API `call_id` to 64 characters** — the OpenAI Responses API rejects `call_id` values longer than 64 characters with a 400. Long upstream tool-call ids (some clients emit ids well over the limit) are now clamped deterministically on both the `function_call` item and its matching `function_call_output`, so the pair stays matched through the orphaned-output filter and the request is accepted. (thanks @anuragg-saxenaa, @ngapngap) -- **fix(oauth): GitHub Copilot token refresh now sends the public client_id** — the `github` provider config never carried a `clientId`, so GitHub OAuth `refresh_token` exchanges either omitted `client_id` or sent the literal string `undefined` (and a bogus `client_secret=undefined`), which GitHub rejects — leaving a Copilot connection stuck once its short-lived token expired and the long-lived refresh path was needed. The provider now resolves its public device-flow `client_id` from the embedded public credential and omits `client_secret` entirely (GitHub's Copilot app is a public client with no secret). (thanks @baslr) -- **fix(translator): a tool property named `pattern` survives Gemini/Antigravity schema sanitization** — the Gemini schema sanitizer strips JSON-Schema constraint keywords Gemini rejects (`pattern`, `minLength`, …) at every nesting level, but it also deleted any tool **property** literally _named_ one of those keywords. glob/grep tools declare a property called `pattern`, so on `ag/*` (Antigravity) backends that argument (and its `required` entry) was silently dropped, breaking the tools. Keyword stripping is now position-aware: it only removes constraint keywords at the schema-node level and never against the user-defined names inside a `properties` map. A genuine string-level `pattern` _constraint_ is still stripped. (thanks @youthanh) -- **fix(translator): MCP `namespace` tools flatten to individual functions on the Responses→Chat path** — when a Codex CLI client routes a Responses-API request to a non-Codex backend (e.g. `kr/claude-opus-4.7`), each MCP server is declared as a `namespace` tool (`{ type:"namespace", name, tools:[…] }`). The Responses→Chat translator had no `namespace` branch, so the whole group collapsed into a single empty-schema function named `mcp____` and every MCP call returned `unsupported call: mcp____`, breaking all MCP-based workflows (context7, codegraph, custom MCPs) for that combination. The translator now expands a namespace into one Chat function per sub-tool (preserving each sub-tool's name and parameters); an empty namespace yields no tools instead of a broken placeholder. The native Codex passthrough path was already correct. (thanks @V13t4nh) -- **fix(cli): the active remote-context credential wins over an ambient `OMNIROUTE_API_KEY`** — when a remote context is selected, its scoped access token now takes precedence over an `OMNIROUTE_API_KEY` present in the environment, so the connected remote is targeted as expected. ([#4364](https://github.com/diegosouzapw/OmniRoute/pull/4364)) -- **fix(cli): wire the `contexts` command into the CLI program** — the `omniroute contexts` command (list/switch saved remote contexts) was implemented but never registered, so it was unreachable; it is now wired into the CLI program. ([#4369](https://github.com/diegosouzapw/OmniRoute/pull/4369)) -- **fix(mitm): mask bare `Bearer ` header values in the Traffic Inspector** — the inspector now redacts bare `Authorization: Bearer …` values so tokens don't leak into captured traffic. ([#4358](https://github.com/diegosouzapw/OmniRoute/pull/4358)) -- **fix(pricing): price the `gpt-5.x-pro` OpenAI models + align the opencode-go discovery test** — adds pricing for the gpt-5.x-pro models so cost telemetry reports a real cost instead of zero. ([#4355](https://github.com/diegosouzapw/OmniRoute/pull/4355)) -- **fix(sse): release the reader and cancel the stream on abort/error (no more Undici pool socket leak)** — on abort or a mid-stream error the response reader is released and the stream cancelled, preventing leaked pooled sockets that degraded later requests. ([#4309](https://github.com/diegosouzapw/OmniRoute/pull/4309) — thanks @Ardem2025) -- **fix(kiro): emit an early role-only start chunk to release the stream-readiness gate** — Kiro streams now send an initial role-only chunk so the stream-readiness gate releases promptly instead of stalling. ([#4311](https://github.com/diegosouzapw/OmniRoute/pull/4311) — thanks @artickc) -- **fix(dashboard): the proxy modal stops pre-filling new scopes with an unrelated proxy** — adding a new scope assignment no longer inherits a previously-selected proxy's configuration. ([#4312](https://github.com/diegosouzapw/OmniRoute/pull/4312)) -- **fix(open-sse): inner-ai stops silently rerouting unmatched models to `models[0]`** — an unmatched model id is no longer silently served by the first available model; the lookup now returns null and the request is handled explicitly. ([#4310](https://github.com/diegosouzapw/OmniRoute/pull/4310)) -- **fix(pollinations): handle auth-required premium models (claude, gemini, midjourney)** — premium Pollinations models that require authentication are now handled correctly instead of failing. ([#4266](https://github.com/diegosouzapw/OmniRoute/pull/4266) — thanks @oyi77) -- **fix(codex): isolate the Spark quota scope** — Codex Spark usage is tracked under its own quota scope so it no longer bleeds into other Codex quotas. ([#4293](https://github.com/diegosouzapw/OmniRoute/pull/4293) — thanks @xz-dev) -- **fix(dashboard): improve the API "try it" functionality** — fixes the request path used by the dashboard's API "try it" panel. ([#4296](https://github.com/diegosouzapw/OmniRoute/pull/4296) — thanks @edrickrenan) -- **fix: polyfill `crypto.randomUUID` for non-secure contexts** — restores UUID generation when the dashboard is served over a non-secure (plain-HTTP) origin where `crypto.randomUUID` is unavailable. ([#4287](https://github.com/diegosouzapw/OmniRoute/pull/4287) — thanks @pizzav-xyz) -- **fix(proxy): allow concurrent proxy dispatcher streams** — the proxy dispatcher no longer serializes streams, so concurrent requests through a proxied connection run in parallel. ([#4288](https://github.com/diegosouzapw/OmniRoute/pull/4288) — thanks @wilsonicdev) -- **fix(build): co-locate llmlingua SLM optionals into `dist/node_modules` (postinstall)** — the optional llmlingua SLM packages are co-located into the standalone build so the compression worker can actually spawn in production. ([#4286](https://github.com/diegosouzapw/OmniRoute/pull/4286)) -- **fix(mitm): surface AgentBridge traffic in the Traffic Inspector (D4 ingest)** — AgentBridge requests now appear in the Traffic Inspector. ([#4285](https://github.com/diegosouzapw/OmniRoute/pull/4285)) -- **fix(sse): surface undici `err.cause` on dispatcher failure** — dispatcher failures now flatten the cause chain (and `AggregateError`s) into the error detail for diagnosability. ([#4281](https://github.com/diegosouzapw/OmniRoute/pull/4281)) -- **fix(cli): harden `launch`/`launch-codex` with free-claude-code patterns** — the launchers adopt the hardened launch patterns ported from free-claude-code. ([#4278](https://github.com/diegosouzapw/OmniRoute/pull/4278)) -- **fix(compression): end-to-end audit — fixes across the whole compression flow** — a sweep of the compression pipeline fixing ultra/aggressive/lossless edge cases, accessibility-anchor handling, language detection, and mode decoupling. ([#4323](https://github.com/diegosouzapw/OmniRoute/pull/4323)) - -### 🧪 Tests - -- **test: align two tests left red by merged PRs** — re-aligns the db-rules classification count (#4335) and the LMArena split-cookie metadata test (#4271) after concurrent merges. ([#4346](https://github.com/diegosouzapw/OmniRoute/pull/4346)) -- **test(ci): reconcile the release/v3.8.30 baseline + test drift** — reconciles quality baselines and drifted tests accumulated on the release branch. ([#4276](https://github.com/diegosouzapw/OmniRoute/pull/4276)) +- **feat(dashboard): 服务商页面的媒体类别 (media serviceKind) 筛选器** — `/dashboard/providers` 新增媒体类别筛选行（Image / Video / Music / Text→Speech / Speech→Text / Embedding），与现有的搜索、仅显示免费和"仅显示已配置"筛选器组合使用。类别归属从后端媒体注册表推导（即使服务商未声明 `serviceKinds`，只要它实际提供某种媒体服务就会被列出），确保 UI 与后端保持同步。([#4240](https://github.com/diegosouzapw/OmniRoute/issues/4240)) +- **feat(combo): 按步骤的账户允许列表 — 将轮询/加权步骤范围限定到服务商连接的子集** — Combo 模型步骤现在可以携带一等公民的账户允许列表，这样轮询（或加权）策略可以限定到服务商连接的一个选定子集（例如只选择 `foo1`+`foo2` 而不是 `foo1..foo4`），而无需为每个账户手动固定一个步骤。留空 = 使用全部活跃池（行为不变）。当步骤同时具有允许列表和标签路由时，两者取交集（最严格者胜）；单个固定账户仍然优先。Combo 构建器的 Precision 步骤编辑器新增可选的"限制到特定账户"选择器。([#3266](https://github.com/diegosouzapw/OmniRoute/issues/3266)) +- **feat(providers): 新增 OpenAdapter、dit.ai 和 TokenRouter 作为 OpenAI 兼容服务商** — 三个社区请求的 OpenAI 兼容聚合器现在注册为标准命名的 OpenAI 风格服务商，支持实时 `/v1/模型` 发现（zenmux 模式），在上游列表不可用时回退到种子目录：**OpenAdapter**（`https://api.openadapter.in/v1`，免费层级，70+ 开源模型 — [#4239](https://github.com/diegosouzapw/OmniRoute/issues/4239)）、**dit.ai**（`https://api.dit.ai/v1`，动态定价路由器/网关 — [#4155](https://github.com/diegosouzapw/OmniRoute/issues/4155)）、**TokenRouter**（`https://api.tokenrouter.com/v1`，免费 MiniMax 模型 — [#3841](https://github.com/diegosouzapw/OmniRoute/issues/3841)，感谢 @FerLuisxd）。无需自定义执行器/翻译器 — 默认 OpenAI 直通。 +- **feat(api): `x-omniroute-no-memory` 请求头 — 按请求选择退出记忆/技能注入** — 自行管理上下文的客户端（例如自有的 RAG/记忆系统）可以发送 `x-omniroute-no-memory: true`（沿用现有的 `x-omniroute-no-缓存` 约定），跳过网关将最多 `memorySettings.maxTokens`（约 2k）tokens 的记忆**和**技能上下文注入到该聊天请求中——避免每次调用带来的 token/成本膨胀。不发送此头时行为不变。(PRD-2026-06-19-no-memory-头) +- **feat(dashboard): MITM 工具卡片列出需要手动添加的完整 hosts 文件条目** — CLI 工具的 MITM 卡片中"工作原理"部分现在列出所选工具的完整 `127.0.0.1 ` 行集合（源自规范的 MITM 目标注册表），而非仅显示单个示例域名。在锁定机器上 — 即自动的、需要 sudo 权限的 hosts 文件编辑不可用时 — 用户现在可以手动复制每个必需条目。(感谢 @mrcyclo) +- **feat(cli): `omniroute launch-codex` + `setup-codex` — 运行/配置 Codex CLI 对接 OmniRoute** — 启动器和设置命令，将 Codex CLI 指向 OmniRoute 端点（支持远程模式）。([#4270](https://github.com/diegosouzapw/OmniRoute/pull/4270)) +- **feat(cli): Claude Code 启动器 + 设置 — 远程模式 + 配置文件** — `omniroute launch`/`setup` 用于 Claude Code，支持远程模式和命名连接配置文件。([#4274](https://github.com/diegosouzapw/OmniRoute/pull/4274)) +- **feat(cli): OpenCode 设置 — OpenAI 兼容服务商 + 远程感知插件** — `setup-opencode` 将 OmniRoute 注册为 OpenCode 的 OpenAI 兼容服务商，并安装远程感知插件。([#4277](https://github.com/diegosouzapw/OmniRoute/pull/4277)) +- **feat(cli): 流行 AI 编码工具的一键设置命令** — 新增 `setup-*` 命令，配置各工具对接 OmniRoute：**Cline** ([#4280](https://github.com/diegosouzapw/OmniRoute/pull/4280))、**Kilo Code** ([#4284](https://github.com/diegosouzapw/OmniRoute/pull/4284))、**Continue** ([#4289](https://github.com/diegosouzapw/OmniRoute/pull/4289))、**Cursor** ([#4291](https://github.com/diegosouzapw/OmniRoute/pull/4291))、**Roo Code** ([#4292](https://github.com/diegosouzapw/OmniRoute/pull/4292))、**Crush** ([#4298](https://github.com/diegosouzapw/OmniRoute/pull/4298))、**Goose** ([#4300](https://github.com/diegosouzapw/OmniRoute/pull/4300))、**Qwen Code** ([#4301](https://github.com/diegosouzapw/OmniRoute/pull/4301))、**Aider** ([#4302](https://github.com/diegosouzapw/OmniRoute/pull/4302)) 以及 **Gemini CLI**（原生 `/v1beta`）([#4303](https://github.com/diegosouzapw/OmniRoute/pull/4303))。 +- **feat(providers): 服务商模型全面扫描 — 实时发现、刷新目录、清理失效服务商** — 一次大规模扫描，为更多 OpenAI 风格服务商启用实时 `/v1/模型` 发现（zenmux 模式），用最新模型刷新种子目录，并将失效服务商标记为 `deprecated`。([#4324](https://github.com/diegosouzapw/OmniRoute/pull/4324)) +- **feat(mitm): 端到端翻译 Antigravity cloudcode 流量（Gap B）** — MITM 解密路径现在端到端翻译 Antigravity `cloudcode` 流量。([#4299](https://github.com/diegosouzapw/OmniRoute/pull/4299)) +- **feat(keys): 按 API 密钥的美元使用配额控制** — API 密钥现在可以携带美元消费配额，在达到阈值后限制其使用。([#4327](https://github.com/diegosouzapw/OmniRoute/pull/4327) — 感谢 @Witroch4) + +### 🔧 变更 + +- **change(memory): 记忆功能现在默认关闭** — `DEFAULT_MEMORY_SETTINGS.enabled` 现在默认为 `false`。启用记忆功能会向**每个**聊天请求注入最多约 2,000 个 token 的检索上下文（该上下文会被计费），这对于新安装和拥有自己上下文的客户端来说是一个意外的默认行为。记忆功能现在需要显式选择启用：已启用它的安装保持不变；从未配置过的安装默认为关闭。设置 → 记忆面板现在在启用记忆功能时显示 token 成本警告。(PRD-2026-06-19-no-memory-header) + +### 🐛 问题修复 + +- **fix(translator): Gemini 接受 HTTP/HTTPS 图片 URL（不再静默丢弃）** — OpenAI 风格的 `image_url` 部分，当 URL 为 `http://…` 或 `https://…` 时，到达 `convertOpenAIContentToParts`（OpenAI→Gemini 请求助手）后仅输出 `console.warn` 就被丢弃，因为 Gemini 的 `inlineData` 需要 base64 编码，而该助手是同步的（无法获取并编码）。然而 Gemini 的 `Part` 模式原生支持远程 URI 的 `fileData: { fileUri }` — 模型会自行获取资源。该助手现在生成 `fileData` 部分（`mimeType: "image/*"`，在上游获取时推断）而不是丢弃，因此传递 URL（而非 data: URI）的视觉请求现在可以完整到达 Gemini。`data:` URI 仍然通过 `inlineData` 不变处理；不支持的协议（如 `ftp:`）仍然跳过。(感谢 @East-rayyy) +- **fix(security): OAuth 回调页面不再将 `code`/`state` 中继到通配符 `postMessage` 目标** — `/callback` 的 OAuth 回调在跨域打开窗口时（远程控制台 + 本地回环回调场景的容灾机制）将 `{ code, state, ... }` 发送到 `window.opener.postMessage(..., "*")`。因此，一个恶意的页面如果在已知的重定向 URI 的弹窗中打开回调 URL，就会收到 OAuth code+state，从而可以以用户身份完成 OAuth 流程。通配符容灾机制被替换为遍历固定的可信目标源允许列表（同源 + Codex 的回环助手 `localhost:1455` / `127.0.0.1:1455`）；浏览器对于源不在列表中的任何打开窗口静默丢弃消息。方法 2（`BroadcastChannel`）和方法 3（`localStorage`）— 已存在于页面中 — 在 COOP 切断打开窗口关系时仍然覆盖同源父窗口。(感谢 @aeonframework) +- **fix(compliance): 启动清理现在遵循控制台数据保留设置，而非总是修剪为 7 天** — 每次重启时，`cleanupExpiredLogs()`（启动时运行）仅从 `CALL_LOG_RETENTION_DAYS` / `APP_LOG_RETENTION_DAYS` 环境变量读取保留时间，未设置时默认为 **7 天**，并在控制台驱动的 `runAutoCleanup()`（遵循配置的保留设置）运行之前就修剪了 `usage_history`（使用分析数据）。因此控制台设置的"数据保留" 90 天被静默覆盖，使用分析页面在重启后只显示最近 7 天的数据。保留时间现在遵循优先级 **显式环境变量 → 控制台 DB 设置 → 7 天默认**，按表区分（`usage_history`→`usageHistory`、`call_logs`/`proxy_logs`/`request_detail_logs`→`callLogs`、`mcp_tool_audit`→`mcpAudit`）；设置环境变量的操作员仍然胜出，非 DB 部署仍然回退到它。([#4354](https://github.com/diegosouzapw/OmniRoute/issues/4354) — 感谢 @akbardwi) +- **fix(providers): bailian-coding-plan 静态回退目录与注册表匹配（10 个模型）** — 服务商-模型扫描（#4324）将四个当前的 Model Studio coding-plan 模型（`qwen3.7-plus`、`qwen3-coder-plus`、`qwen3-coder-next`、`glm-4.7`）添加到了 `bailian-coding-plan` 注册表条目中，但遗漏了 `staticModels.ts` 中的静态容灾镜像，后者仍然只列出了旧的六个。因此静态目录（在实时发现不可用时提供服务）与注册表不一致，现有的 static↔registry 一致性测试在发布分支上变红（仅在测试影响分析恰好选中它时才暴露）。静态镜像现在按注册表顺序包含全部十个模型，恢复了一致性。([#4324](https://github.com/diegosouzapw/OmniRoute/pull/4324)) +- **fix(executors): ArenaLLM 适配 LMArena 的分片 Supabase SSR 认证 Cookie** — LMArena 迁移到了 `@supabase/ssr` 分片认证 Cookie：单个 `arena-auth-prod-v1` Cookie 现在为空，实际会话被分割到 `arena-auth-prod-v1.0`、`arena-auth-prod-v1.1`……（递增）中。用户粘贴（现在为空的）单个 Cookie 时，因此发送了空会话，上游以"无效 Cookie"拒绝。LMArena 执行器现在从其分片中重建单个 Cookie——按递增数字顺序读取 `.0`、`.1`……直到缺失为止，并将它们的原始值拼接起来（`@supabase/ssr` 的 `combineChunks` 规则：纯 `join("")`，不进行 base64 解码，不进行 JSON 解析，`base64-` 前缀原样保留）——同时保留粘贴的 Cookie jar 中的其余内容。非空的单个 Cookie 仍然原样转发（向后兼容）。凭证 UX 现在指示粘贴**完整的 Cookie 请求头**并追踪 `.0`/`.1` 存储键。([#4271](https://github.com/diegosouzapw/OmniRoute/issues/4271) — 感谢 @caussao) +- **fix(compression): 为自动缓存服务商保留可缓存前缀** — OpenAI / Codex（以及 Azure-OpenAI）使用 _自动_ 前缀缓存：上游缓存请求的最长匹配前缀（系统提示 + 最早的消息），**无需**在请求体中添加任何显式的 `cache_control` 标记。缓存感知的压缩守卫仅在请求携带显式 `cache_control` 时保护该前缀，因此对于自动缓存服务商，该守卫被跳过——而在启用压缩且 `preserveSystemPrompt: false`（或使用 `aggressive`/`ultra` 等前缀压缩模式）时，它会重写系统提示 / 最早的消息，导致必然的缓存未命中，通过 OmniRoute 的令牌消耗**反而高于**直连。守卫现在将缓存服务商本身视为充分条件（仅凭 `isCachingProvider`，不依赖 `cache_control`）来跳过系统提示并降级前缀压缩模式，且 OpenAI/Codex/Azure 现在被识别为缓存服务商。压缩功能默认仍然关闭——这仅影响已启用压缩且关闭了前缀保留的操作者。([#3955](https://github.com/diegosouzapw/OmniRoute/issues/3955)) +- **fix(executors): DuckDuckGo AI Chat 使用 duckduckgo.com（修复 400 错误）** — DuckDuckGo AI Chat 执行器之前向 `https://duck.ai` 获取状态/聊天并设置 `Origin`/`Referer`，同时仍然发送 `Sec-Fetch-Site: same-origin`，因此请求的同源三元组（主机 + Origin + Referer）不一致，后端以 HTTP 400 拒绝。所有当前的 DDG 逆向工程参考——以及服务商注册表自身的 `baseUrl`——均使用 `https://duckduckgo.com`；执行器现在在状态 URL、聊天 URL、`Origin` 和 `Referer` 中一致使用它（同源请求头现在保持一致）。`x-fe-version` 抓取正则之前要求 40 位十六进制尾部，但实际提供的令牌具有 20 位十六进制尾部（例如 `serp_20250401_100419_ET-19d438eb199b2bf7c300`），因此它静默回退到硬编码的默认值；模式放宽为有界的 `{20,40}` 尾部（仍然 ReDoS 安全）。此修复解决了报告中的 DuckDuckGo 部分；独立的 Chipotle/`chipotle` 上游故障将另行跟踪。([#4037](https://github.com/diegosouzapw/OmniRoute/issues/4037) — 感谢 @daniij) +- **fix(security): 将提示注入扫描限制在前 16 KB（热路径性能优化）** — 提示注入守卫之前将每条消息/系统字符串合并到一个缓冲区中，并在每次聊天请求时对整个内容运行多个正则表达式，没有大小上限——因此 300 KB 的请求体（粘贴的代码、RAG 上下文）意味着在热路径上进行 O(body) CPU 扫描，成为并发场景下自我造成的延迟/GC 来源。两个检测调用点（`inputSanitizer.ts` 中的 `detectInjection` 和 `promptInjection.ts` 中的自定义模式扫描）现在在正则循环之前将合并文本截取到前 **16 KB**（`MAX_INJECTION_SCAN_BYTES`）。注入指令位于提示的顶部附近，因此慷慨的上限在仅扫描有界前缀的同时保留了真正的检测能力；现有的 10 MB 请求体大小上限（保护摄入）保持不变。([#3932](https://github.com/diegosouzapw/OmniRoute/issues/3932) — 感谢 @KooshaPari) +- **fix(sse): 在新 Socket 上重试直连 Socket 失败（减少 `502` 突发）** — 默认直连 undici 调度器池将 keep-alive Socket 保留最多 4 秒，但某些边缘节点（例如 `nvidia`、`opencode-zen`）在该窗口内静默关闭空闲的 keep-alive Socket，因此下一个重用池化 Socket 的请求会失败并报 `UND_ERR_SOCKET`（"对方已关闭"）——且是突发性的。`proxyFetch` 已经在此类瞬时错误上重试一次，但重试复用了**同一个**池化调度器，可能抓取到另一个过期 Socket，然后落到原生 fetch（也是池化的）→ 作业在速率限制队列中等待直到 30 秒超时 → `502` + 熔断器打开。重试现��使用专用的 **no-keep-alive / no-pipelining** 调度器，因此它打开一个全新的 Socket，不可能是一个已死的池化 Socket；第一次尝试仍然使用池化调度器（保留健康的 keep-alive 复用）。与 v3.8.29 的诊断功能（`describeFetchCause`，#4281）互补。([#4252](https://github.com/diegosouzapw/OmniRoute/issues/4252) — 感谢 @klimadev) +- **fix(sse): Combo 现在在遇到首个请求体特定的 400 错误时停止，而非尝试每个目标** — 检测请求体特定 400（上下文溢出 / 格式错误 / 模型访问被拒，例如"使用 Codex 与 ChatGPT 账户时不支持该模型"）的 `#2101` 守卫记录了"停止 Combo"但执行了一个裸 `break`，这仅退出了内部重试循环；`executeTarget` 随后返回 `null`，外部目标循环将其视为"此目标未产生任何内容"并推进到下一个模型。因此，一个所有 N 个目标都拒绝相同请求体的 Combo 会遍历全部 N 个目标（报告中显示一个 143 模型的 Codex Combo 迭代了每个目标），浪费了上游调用和每次尝试的工作。守卫现在通过 `{ ok, 响应 }` 契约（镜像 499 客户端断开路径）将 400 上浮，使 Combo 立即解析并停止。([#4279](https://github.com/diegosouzapw/OmniRoute/issues/4279)) +- **fix(sse): 通过 Responses-API 目标的非流式 Combo 不再返回空内容** — Responses-API 目标（codex/`cx`）即使在 `流:false` 时也从上游流式传输，其终端 `响应.completed` 快照可能携带一个非空的 `output`，但缺少助手消息项（例如仅有一个 `reasoning` 项），而流式传输的 `output_text` delta 已重建了完整消息。SSE→JSON 聚合器之前优先选择终端 `output` 整体，丢弃了重建的文本 → HTTP 200 但内容为空（尤其通过 n8n 触发，n8n 默认 `流:false`）。聚合器现在在终端输出没有消息项但重建有内容时回退到重建的 delta 输出；终端快照在已经携带消息时仍然优先。([#3948](https://github.com/diegosouzapw/OmniRoute/issues/3948)) +- **fix(executors): 保留原生 Claude OAuth 的工具名称大小写（`read` 不再泄漏为 `Read`）** — 原生 Claude OAuth 流量经过一个反指纹工具名称伪装，该伪装将字面名为 `read` 的工具在线上重命名为 `Read`，并在一个不可枚举的 `_toolNameMap` 上记录反向别名，响应端使用它来恢复客户端的原始大小写。自 v3.8.27 起，执行器返回请求体的 JSON 往返副本作为 `transformedBody`，该往返丢失了不可枚举的映射——因此恢复时看到空映射，伪装的 `Read` 原样流式传输给客户端，损坏了工具名称。执行器现在将伪装映射重新附加到序列化请求体上（镜像 Antigravity 执行器），因此工具名称大小写正确往返。([#4307](https://github.com/diegosouzapw/OmniRoute/issues/4307) — 感谢 @dev-cj) +- **fix(api): 缓存命中时 `X-OmniRoute-Response-Cost` 现在报告增量成本（≈0），而非原始成本** — 在语义缓存命中时，网关在**没有**上游调用的情况下提供存储的响应，但 `X-OmniRoute-Response-Cost` 报告的是原始调用的完整成本（从缓存的 `usage` 重新计算）。因此，对 `响应-成本` 求和的计费消费者在向服务成本 ≈$0 的响应收费（且过期条目可能夸大金额）。缓存命中现在计费 `X-OmniRoute-Response-Cost: 0.0000000000`（真正的增量成本），而避免的成本通过一个新的 **`X-OmniRoute-Cost-Saved`** 请求头暴露，用于缓存分析——镜像现有的 `tokens_saved` 概念。MISS 路径保持不变。(PRD-2026-06-19-缓存-hit-成本-reporting) +- **fix(models): 导入的视觉能力模型保留其视觉能力** — 导入服务商密钥后，视觉能力模型（例如 `architecture` 声明图像输入的 OpenRouter 模型，以及其他同步的服务商）在 `/v1/模型` 和控制台中被列为纯文本——尽管图像请求实际上可以工作。同步的模型记录从未捕获视觉标志，而目录的 OpenRouter 实时增强（从 `architecture.input_modalities` 推导视觉能力）在服务商有同步模型后会被跳过。发现过程现在在同步时捕获 `supportsVision`（从 `architecture.input_modalities`、字符串 `architecture.modality` 或顶层 `input_modalities`），镜像现有的 `supportsThinking` 捕获，且目录为同步模型展示 `capabilities.vision`。([#4264](https://github.com/diegosouzapw/OmniRoute/issues/4264) — 感谢 @FerLuisxd) +- **fix(providers): Cloudflare Workers AI 模型发现显示模型名称而非 UUID** — 导入 Cloudflare Workers AI 密钥时，模型以内部 UUID 标识符列出（例如 `429b9e8b-d99e-…`）而非其可用别名（`@cf/meta/llama-3.1-8b-instruct`）。Cloudflare 的 `/ai/模型/搜索` 返回 `{ id: "", name: "@cf/…" }`，发现过程直接将原始对象传递——因此 UUID `id` 成为了可调用的模型 ID。`cloudflare-ai` 发现现在将每个结果的 `name` → id 进行映射，展示真实的 `@cf/…` 模型 ID。([#4259](https://github.com/diegosouzapw/OmniRoute/issues/4259) — 感谢 @FerLuisxd) +- **fix(translator): 将 Responses API `call_id` 限制在 64 个字符** — OpenAI Responses API 拒绝长度超过 64 个字符的 `call_id` 值并返回 400。长上游工具调用 ID（某些客户端发出的 ID 远超此限制）现在在 `function_call` 项及其匹配的 `function_call_output` 上确定性截断，使配对通过孤立输出过滤器保持匹配且请求被接受。(感谢 @anuragg-saxenaa, @ngapngap) +- **fix(oauth): GitHub Copilot 令牌刷新现在发送公共 client_id** — `github` 服务商配置从未携带 `clientId`，因此 GitHub OAuth `refresh_token` 交换要么省略了 `client_id`，要么发送了字面字符串 `undefined`（以及伪造的 `client_secret=undefined`），GitHub 会拒绝——导致 Copilot 连接在其短期令牌过期且需要长期刷新路径时卡住。服务商现在从嵌入的公共凭证中解析其公共 device-flow `client_id`，并完全省略 `client_secret`（GitHub 的 Copilot 应用是没有 secret 的公共客户端）。(感谢 @baslr) +- **fix(translator): 名为 `pattern` 的工具属性在 Gemini/Antigravity Schema 清理后得以保留** — Gemini Schema 清理器在每个嵌套层级剥离 Gemini 拒绝的 JSON-Schema 约束关键字（`pattern`、`minLength`……），但它也删除了任何字面上以这些关键字**命名**的工具**属性**。glob/grep 工具声明了一个名为 `pattern` 的属性，因此在 `ag/*`（Antigravity）后端上，该参数（及其 `required` 条目）被静默丢弃，破坏了工具。关键字剥离现在是位置感知的：它仅在 Schema 节点级别移除约束关键字，而不会触及 `properties` 映射内的用户定义名称。真正的字符串级别 `pattern` _约束_ 仍然会被剥离。(感谢 @youthanh) +- **fix(translator): MCP `namespace` 工具在 Responses→Chat 路径上展开为单独函数** — 当 Codex CLI 客户端将 Responses-API 请求路由到非 Codex 后端（例如 `kr/claude-opus-4.7`）时，每个 MCP 服务器被声明为一个 `namespace` 工具（`{ type:"namespace", name, tools:[…] }`）。Responses→Chat 翻译器没有 `namespace` 分支，因此整个组折叠为一个名为 `mcp____` 的空 Schema 函数，每次 MCP 调用都返回 `unsupported call: mcp____`，破坏了该组合的所有基于 MCP 的工作流（context7、codegraph、自定义 MCP）。翻译器现在将命名空间展开为每个子工具一个 Chat 函数（保留每个子工具的名称和参数）；空命名空间不产生任何工具而非产生一个损坏的占位符。原生 Codex 直通路径此前已经正确。(感谢 @V13t4nh) +- **fix(cli): 活跃的远程上下文凭证优先于环境中的 `OMNIROUTE_API_KEY`** — 当选择了远程上下文时，其范围限定的访问令牌现在优先于环境中存在的 `OMNIROUTE_API_KEY`，使连接的远程目标按预期被选中。([#4364](https://github.com/diegosouzapw/OmniRoute/pull/4364)) +- **fix(cli): 将 `contexts` 命令接入 CLI 程序** — `omniroute contexts` 命令（列出/切换已保存的远程上下文）已实现但从未注册，因此无法访问；现已接入 CLI 程序。([#4369](https://github.com/diegosouzapw/OmniRoute/pull/4369)) +- **fix(mitm): 在流量检查器中屏蔽裸 `Bearer ` 请求头值** — 检查器现在遮盖裸 `Authorization: Bearer …` 值，防止令牌泄漏到捕获的流量中。([#4358](https://github.com/diegosouzapw/OmniRoute/pull/4358)) +- **fix(pricing): 为 `gpt-5.x-pro` OpenAI 模型定价 + 对齐 opencode-go 发现测试** — 为 gpt-5.x-pro 模型添加定价，使成本遥测报告真实成本而非零。([#4355](https://github.com/diegosouzapw/OmniRoute/pull/4355)) +- **fix(sse): 在中止/错误时释放读取器并取消流（不再有 Undici 池 Socket 泄漏）** — 在中止或流中错误时，响应读取器被释放且流被取消，防止泄漏的池化 Socket 降低后续请求的性能。([#4309](https://github.com/diegosouzapw/OmniRoute/pull/4309) — 感谢 @Ardem2025) +- **fix(kiro): 发送早期的仅角色起始块以释放流就绪门** — Kiro 流现在发送初始的仅角色块，使流就绪门及时释放而非停滞。([#4311](https://github.com/diegosouzapw/OmniRoute/pull/4311) — 感谢 @artickc) +- **fix(dashboard): 代理模态框停止将新范围预填充为无关代理** — 添加新范围分配不再继承之前选中的代理的配置。([#4312](https://github.com/diegosouzapw/OmniRoute/pull/4312)) +- **fix(open-sse): inner-ai 停止将未匹配模型静默重路由到 `models[0]`** — 未匹配的模型 ID 不再由第一个可用模型静默提供服务；查找现在返回 null，请求被显式处理。([#4310](https://github.com/diegosouzapw/OmniRoute/pull/4310)) +- **fix(pollinations): 处理需要认证的高级模型（claude、gemini、midjourney）** — 需要认证的高级 Pollinations 模型现在正确处理而非失败。([#4266](https://github.com/diegosouzapw/OmniRoute/pull/4266) — 感谢 @oyi77) +- **fix(codex): 隔离 Spark 配额范围** — Codex Spark 使用量现在在自己的配额范围内跟踪，不再混入其他 Codex 配额。([#4293](https://github.com/diegosouzapw/OmniRoute/pull/4293) — 感谢 @xz-dev) +- **fix(dashboard): 改进 API"试用"功能** — 修复控制台 API"试用"面板使用的请求路径。([#4296](https://github.com/diegosouzapw/OmniRoute/pull/4296) — 感谢 @edrickrenan) +- **fix: 为非安全上下文 polyfill `crypto.randomUUID`** — 当控制台通过非安全（纯 HTTP）来源提供服务且 `crypto.randomUUID` 不可用时，恢复 UUID 生成。([#4287](https://github.com/diegosouzapw/OmniRoute/pull/4287) — 感谢 @pizzav-xyz) +- **fix(proxy): 允许并发的代理调度器流** — 代理调度器不再序列化流，使通过代理连接的并发请求可以并行运行。([#4288](https://github.com/diegosouzapw/OmniRoute/pull/4288) — 感谢 @wilsonicdev) +- **fix(build): 将 llmlingua SLM 可选包共置到 `dist/node_modules`（postinstall）** — 可选的 llmlingua SLM 包被共置到独立构建中，使压缩 worker 可以在生产环境中实际启动。([#4286](https://github.com/diegosouzapw/OmniRoute/pull/4286)) +- **fix(mitm): 在流量检查器中展示 AgentBridge 流量（D4 摄取）** — AgentBridge 请求现在出现在流量检查器中。([#4285](https://github.com/diegosouzapw/OmniRoute/pull/4285)) +- **fix(sse): 在调度器失败时展示 undici `err.cause`** — 调度器失败现在将原因链（和 `AggregateError`）展平到错误详情中以供诊断。([#4281](https://github.com/diegosouzapw/OmniRoute/pull/4281)) +- **fix(cli): 使用 free-claude-code 模式加固 `launch`/`launch-codex`** — 启动器采用了从 free-claude-code 移植的加固启动模式。([#4278](https://github.com/diegosouzapw/OmniRoute/pull/4278)) +- **fix(compression): 端到端审计 — 修复整个压缩流程** — 对压缩管线进行全面扫描，修复 ultra/aggressive/lossless 边缘情况、无障碍锚点处理、语言检测和模式解耦。([#4323](https://github.com/diegosouzapw/OmniRoute/pull/4323)) + +### 🧪 测试 + +- **test: 对齐被合并 PR 遗留的两个红色测试** — 在并发合并后重新对齐 db-rules 分类计数（#4335）和 LMArena 分片 Cookie 元数据测试（#4271）。([#4346](https://github.com/diegosouzapw/OmniRoute/pull/4346)) +- **test(ci): 协调 release/v3.8.30 基线 + 测试漂移** — 协调发布分支上累积的质量基线和漂移测试。([#4276](https://github.com/diegosouzapw/OmniRoute/pull/4276)) ### 📝 维护 -- **refactor(combo): `ComboContext` + extract `phaseComboSetup` (god-file split, phase 1)** — begins decomposing the combo god-file by extracting combo setup into a context object, without touching dispatch/semaphore logic. ([#4326](https://github.com/diegosouzapw/OmniRoute/pull/4326)) -- **feat(quality): cap test-file size — anti-reinflation Layer 1** — freezes the existing god-tests and caps new test files at 800 lines to stop re-inflation. ([#4273](https://github.com/diegosouzapw/OmniRoute/pull/4273)) -- **feat(quality): seed per-module mutationScore floors + a blocking aggregation ratchet (T3)** — adds per-module mutation-score floors with a blocking aggregate gate. ([#4305](https://github.com/diegosouzapw/OmniRoute/pull/4305)) -- **feat(quality): make the a11y gate real (`@axe-core/playwright` in nightly)** — wires the previously-phantom accessibility gate into the nightly run with real baselines. ([#4321](https://github.com/diegosouzapw/OmniRoute/pull/4321)) -- **feat(quality): unblock R1 — test-redundancy measurement via `disableBail`** — enables the test-redundancy measurement that was previously blocked by fail-fast. ([#4322](https://github.com/diegosouzapw/OmniRoute/pull/4322)) -- **fix(quality): the complexity gate now covers `bin/` + `electron/`, and tracked-artifacts runs in pre-commit** — extends the complexity gate's scope and moves the tracked-artifacts check into the pre-commit hook. ([#4318](https://github.com/diegosouzapw/OmniRoute/pull/4318)) -- **fix(quality): restore release/v3.8.30 green — 3 latent reds from concurrent merges** — fixes three latent test reds surfaced by concurrent merges into the release branch. ([#4335](https://github.com/diegosouzapw/OmniRoute/pull/4335)) -- **fix(combo): keep `phaseComboSetup` under the complexity ceiling** — extracts a helper so the new combo setup phase stays under the complexity gate. ([#4338](https://github.com/diegosouzapw/OmniRoute/pull/4338)) -- **ci(mutation): split over-budget batches by range/pair so every batch fits the job cap** — re-splits the mutation batches so each fits the CI job budget. ([#4272](https://github.com/diegosouzapw/OmniRoute/pull/4272)) -- **chore(ci): align the electron audit gate to the root advisory policy** — the electron-workspace audit gate now follows the same advisory policy as the root. ([#4275](https://github.com/diegosouzapw/OmniRoute/pull/4275)) -- **chore(quality): reconcile the complexity/quality baselines across concurrent-merge drift** — rolls up the cycle's baseline reconciliations driven by concurrent merges into the release branch. ([#4330](https://github.com/diegosouzapw/OmniRoute/pull/4330), [#4336](https://github.com/diegosouzapw/OmniRoute/pull/4336), [#4370](https://github.com/diegosouzapw/OmniRoute/pull/4370)) -- **docs: ban AI-generation footers in commits/PRs/CHANGELOG (Hard Rule #16)** — codifies the prohibition on AI-generation footers and bot co-author trailers. ([#4328](https://github.com/diegosouzapw/OmniRoute/pull/4328)) -- **docs(design): add the OmniRoute design system and visual identity specification** — adds the design-system / visual-identity specification document. (thanks @diegosouzapw) +- **refactor(combo): `ComboContext` + 提取 `phaseComboSetup`（巨文件拆分，阶段 1）** — 开始分解 Combo 巨文件，将 Combo 设置提取到上下文对象中，不触及调度/信号量逻辑。([#4326](https://github.com/diegosouzapw/OmniRoute/pull/4326)) +- **feat(quality): 限制测试文件大小 — 反膨胀第 1 层** — 冻结现有巨测试并将新测试文件限制在 800 行以内以阻止重新膨胀。([#4273](https://github.com/diegosouzapw/OmniRoute/pull/4273)) +- **feat(quality): 设定每个模块的 mutationScore 下限 + 阻塞性聚合棘轮（T3）** — 添加每个模块的变异分数下限和阻塞性聚合门禁。([#4305](https://github.com/diegosouzapw/OmniRoute/pull/4305)) +- **feat(quality): 使 a11y 门禁真正生效（`@axe-core/playwright` 加入夜间运行）** — 将之前虚设的无障碍门禁接入夜间运行并使用真实基线。([#4321](https://github.com/diegosouzapw/OmniRoute/pull/4321)) +- **feat(quality): 解除 R1 阻塞 — 通过 `disableBail` 进行测试冗余度测量** — 启用之前被 fail-fast 阻塞的测试冗余度测量。([#4322](https://github.com/diegosouzapw/OmniRoute/pull/4322)) +- **fix(quality): 复杂度门禁现在覆盖 `bin/` + `electron/`，且 tracked-artifacts 在 pre-commit 中运行** — 扩展复杂度门禁的范围并将 tracked-artifacts 检查移入 pre-commit 钩子。([#4318](https://github.com/diegosouzapw/OmniRoute/pull/4318)) +- **fix(quality): 恢复 release/v3.8.30 绿色 — 3 个来自并发合并的潜在红色** — 修复三个因并发合并到发布分支而暴露的潜在测试红色。([#4335](https://github.com/diegosouzapw/OmniRoute/pull/4335)) +- **fix(combo): 保持 `phaseComboSetup` 在复杂度上限以下** — 提取辅助函数使新的 Combo 设置阶段保持在复杂度门禁以下。([#4338](https://github.com/diegosouzapw/OmniRoute/pull/4338)) +- **ci(mutation): 按范围/配对拆分超预算批次，使每个批次符合作业上限** — 重新拆分变异批次使每个批次符合 CI 作业预算。([#4272](https://github.com/diegosouzapw/OmniRoute/pull/4272)) +- **chore(ci): 将 electron 审计门禁对齐到根 advisory 策略** — electron 工作区审计门禁现在遵循与根相同的 advisory 策略。([#4275](https://github.com/diegosouzapw/OmniRoute/pull/4275)) +- **chore(quality): 协调并发合并漂移下的复杂度/质量基线** — 汇总该周期由并发合并驱动的基线协调，合并到发布分支。([#4330](https://github.com/diegosouzapw/OmniRoute/pull/4330), [#4336](https://github.com/diegosouzapw/OmniRoute/pull/4336), [#4370](https://github.com/diegosouzapw/OmniRoute/pull/4370)) +- **docs: 禁止在提交/PR/CHANGELOG 中使用 AI 生成页脚（硬规则 #16）** — 将禁止 AI 生成页脚和机器人共同作者尾注的规定编入规则。([#4328](https://github.com/diegosouzapw/OmniRoute/pull/4328)) +- **docs(design): 添加 OmniRoute 设计系统和视觉标识规范** — 添加设计系统 / 视觉标识规范文档。(感谢 @diegosouzapw) ### 🔒 安全 -- **fix(sse): harden the DuckDuckGo lite scraper sanitization (CodeQL)** — closes four HIGH CodeQL alerts in the no-key web-search scraper: `decodeEntities` now resolves `&` **last** so an already-escaped entity (e.g. `&lt;`) survives as literal text instead of being double-unescaped (`js/double-escaping`); `stripTags` decodes entities first, then strips tags in a loop to a fixpoint and drops any trailing unclosed `<…`, so entity-encoded markup like `<script>` can never reach the LLM/client as a live tag (`js/incomplete-multi-character-sanitization`); and the host checks in the search tests use `new URL().hostname` equality instead of substring `.includes` (`js/incomplete-url-substring-sanitization`). ([#4356](https://github.com/diegosouzapw/OmniRoute/pull/4356)) +- **fix(sse): 加固 DuckDuckGo lite 抓取器清理逻辑（CodeQL）** — 关闭无密钥网页搜索抓取器中的四个 HIGH 级别 CodeQL 告警：`decodeEntities` 现在**最后**解析 `&`，使已转义的实体（例如 `&lt;`）作为字面文本保留而非被双重反转义（`js/double-escaping`）；`stripTags` 先解码实体，然后循环剥离标签直至不动点并丢弃任何尾部未闭合的 `<…`，使实体编码的标记如 `<script>` 永远无法以活动标签形式到达 LLM/客户端（`js/incomplete-multi-character-sanitization`）；搜索测试中的主机检查使用 `new URL().hostname` 相等性而非子字符串 `.includes`（`js/incomplete-url-substring-sanitization`）。([#4356](https://github.com/diegosouzapw/OmniRoute/pull/4356)) ### 🔧 依赖 -- **fix(deps): bump undici to 7.28.0 and dompurify to 3.4.11 (security)** — addresses the undici SOCKS5-TLS / cache advisories and the dompurify advisory. ([#4306](https://github.com/diegosouzapw/OmniRoute/pull/4306)) -- **chore(deps): bump actions/checkout from 4 to 7** — CI checkout-action update. ([#4297](https://github.com/diegosouzapw/OmniRoute/pull/4297)) -- **fix(executors): strip `stream_options` for qwen non-streaming / thinking-mode Claude Code requests** — Claude-Code-compatible providers force the executor-level `stream` flag on via `upstreamStream = stream || isClaudeCodeCompatible` (`open-sse/handlers/chatCore.ts`), but the outgoing body keeps the caller's original `stream: false`. The shared `stream && targetFormat === "openai"` branch in `DefaultExecutor.transformRequest` then injected `stream_options: { include_usage: true }` onto a body that still said `stream: false`, and qwen upstream rejected it with `400 "'stream_options' only set this when you set stream: true"`. Same rejection when the body carries `thinking` / `enable_thinking`. The qwen branch now skips the injection (and strips any client-sent `stream_options`) when the body explicitly says `stream: false` or requests thinking, leaving regular qwen streaming requests with the usage injection intact. (thanks @anuragg-saxenaa) +- **fix(deps): 将 undici 升级到 7.28.0，dompurify 升级到 3.4.11（安全）** — 解决 undici SOCKS5-TLS / 缓存安全公告和 dompurify 安全公告。([#4306](https://github.com/diegosouzapw/OmniRoute/pull/4306)) +- **chore(deps): 将 actions/checkout 从 4 升级到 7** — CI checkout-action 更新。([#4297](https://github.com/diegosouzapw/OmniRoute/pull/4297)) +- **fix(executors): 为 qwen 非流式 / 思考模式 Claude Code 请求剥离 `stream_options`** — Claude-Code 兼容服务商通过 `upstreamStream = stream || isClaudeCodeCompatible`（`open-sse/handlers/chatCore.ts`）强制开启执行器级别的 `stream` 标志，但传出请求体保留调用者原始的 `stream: false`。`DefaultExecutor.transformRequest` 中共享的 `stream && targetFormat === "openai"` 分支随后将 `stream_options: { include_usage: true }` 注入到一个仍然声明 `stream: false` 的请求体上，qwen 上游以 `400 "'stream_options' only set this when you set stream: true"` 拒绝。当请求体携带 `thinking` / `enable_thinking` 时出现相同的拒绝。qwen 分支现在在请求体显式声明 `stream: false` 或请求思考模式时跳过注入（并剥离任何客户端发送的 `stream_options`），使常规 qwen 流式请求的 usage 注入保持不变。(感谢 @anuragg-saxenaa) --- @@ -844,137 +844,137 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(cloud-agent): Cursor Cloud Agent via the official API-key REST API (no IDE-OAuth ban risk)** — adds a `cursor-cloud` cloud agent that drives Cursor's Background / Cloud Agents through the official REST API (`api.cursor.com`) authenticated with a user or service-account API key — the safer, first-party alternative to re-using the Cursor IDE's OAuth session (the existing `cursor` provider, which carries a ban-risk warning). Implemented as a plain REST adapter mirroring the Devin/Jules agents (`createTask`/`getStatus`/`sendMessage`/`listSources`), so it does **not** pull in the `@cursor/sdk` package and its per-platform native binaries (Cursor's SDK is itself a thin wrapper over this REST API). Cursor's UPPERCASE status enums (`CREATING`/`RUNNING`/`FINISHED`/`ERROR`) are mapped explicitly to the shared `CloudAgentStatus`, and `baseUrl` is overridable per-credential. Credentials are stored encrypted via the existing `cloud_agent_credentials` table; no schema change. ([#4227](https://github.com/diegosouzapw/OmniRoute/issues/4227) — thanks @MRDGH2821) -- **feat(routing): OpenRouter-style `auto/:` combos** — auto-routing now understands suffixed combos that separate the _category_ (what kind of route) from the _tier_ (how to optimize): `auto/coding:fast`, `auto/coding:cheap` (alias `:floor`), `auto/coding:free`, `auto/coding:pro`, `auto/coding:reliable`, plus the new category roots `auto/reasoning`, `auto/vision`, `auto/multimodal`. The **tier** picks the scoring weights — `:fast` → ship-fast, `:cheap`/`:floor` → cost-saver, `:reliable` → a new reliability-first pack (circuit-breaker health + latency stability) — while `:free`/`:pro` filter the candidate pool by model tier (`classifyTier`: free-tier vs. premium models). The **category** filters the pool by capability (`vision`/`multimodal` → vision-capable models, `reasoning` → reasoning/thinking models). Any valid `auto/:` resolves on demand; a curated set is advertised in `/v1/models` and the dashboard. Filtering is fail-open — if a constraint matches no connected models the full pool is used so routing never breaks. All composition lives in the new `open-sse/services/autoCombo/suffixComposition.ts`; the core combo scorer (`combo.ts`) is untouched. Second slice of #4235 (premium account-tier weighting is a later follow-up). ([#4235](https://github.com/diegosouzapw/OmniRoute/issues/4235) — thanks @MRDGH2821) -- **feat(routing): advertise the `auto/cheap`, `auto/offline`, `auto/smart` combos (catalog ↔ README sync)** — the README lists `auto/cheap` (cheapest-per-token first), `auto/offline` (most quota/rate-limit headroom first) and `auto/smart` (quality-first + 10% exploration), and they already resolved at request time via `parseAutoPrefix` → `createVirtualAutoCombo`. But they were missing from `AUTO_TEMPLATE_VARIANTS`, so `/v1/models` and the dashboard combos list (which iterate that catalog) never showed them — the catalog drifted from the docs (visible in the issue's screenshots). Added the three entries so they're advertised everywhere alongside the other built-in `auto/*` combos. First slice of #4235 (OpenRouter-style `auto/:` suffixes + new categories follow). ([#4235](https://github.com/diegosouzapw/OmniRoute/issues/4235) — thanks @MRDGH2821) -- **feat(cli): remote mode — drive a remote OmniRoute with scoped access tokens** — a new CLI mode that connects to a remote OmniRoute instance using scoped access tokens, so a local CLI can drive a server you don't own a session on. ([#4256](https://github.com/diegosouzapw/OmniRoute/pull/4256)) -- **feat(api): cost-telemetry parity — `X-OmniRoute-*` headers on every endpoint + a non-token cost engine** — every endpoint now emits the `X-OmniRoute-*` cost/usage headers, backed by a cost engine that also prices non-token (media/request-based) usage. ([#4247](https://github.com/diegosouzapw/OmniRoute/pull/4247)) -- **feat(api): register Kimi K2.7 Code models (`kimi-k2.7-code` + `-highspeed`)** — the new Moonshot thinking-only coding models are registered (fixed sampling; `temperature`/`top_p` marked unsupported). ([#4183](https://github.com/diegosouzapw/OmniRoute/pull/4183)) -- **feat(catalog): add `kimi-k2.7-code` to the kmca catalog + qwen-web models discovery** — surfaces the new Kimi coding model in the kmca catalog and wires qwen-web into model discovery. ([#4185](https://github.com/diegosouzapw/OmniRoute/pull/4185)) -- **feat(api): expand the `zai` provider catalog with GLM-5.2 / GLM-4.7** — adds the real GLM-5.2, GLM-4.7 and GLM-4.7-flash model ids to the Anthropic-direct `zai` provider. ([#4201](https://github.com/diegosouzapw/OmniRoute/pull/4201)) -- **feat(api): no-thinking gateway model IDs (FCC port, Fase 8.1)** — gateway model id variants that force thinking off, ported from free-claude-code. ([#4145](https://github.com/diegosouzapw/OmniRoute/pull/4145)) -- **feat(sse): mid-stream continuation for truncated streams (FCC port, Task 4.4)** — when a stream is cut short, OmniRoute can transparently continue it, ported from free-claude-code. ([#4147](https://github.com/diegosouzapw/OmniRoute/pull/4147)) -- **feat(sse): per-provider sliding-window rate-limit fallback (FCC port, Fase 8.2)** — a per-provider sliding-window rate limiter as a fallback path, ported from free-claude-code. ([#4146](https://github.com/diegosouzapw/OmniRoute/pull/4146)) -- **feat(sse): transparent stream recovery (FCC port, Fase 4, opt-in)** — opt-in transparent recovery of interrupted upstream streams, ported from free-claude-code. ([#4131](https://github.com/diegosouzapw/OmniRoute/pull/4131)) -- **feat(search): free DuckDuckGo web search as a last-resort provider (FCC port, Fase 6)** — adds a no-key DuckDuckGo web-search provider used as a last resort, ported from free-claude-code. ([#4136](https://github.com/diegosouzapw/OmniRoute/pull/4136)) -- **feat(logging): credential-redaction safety net in the pino logger (FCC port, Fase 8.3)** — a logger-level redaction pass that scrubs credentials from log output, ported from free-claude-code. ([#4140](https://github.com/diegosouzapw/OmniRoute/pull/4140)) -- **feat(memory): opt-in Qdrant scalar int8 quantization (F4.4 Q1)** — opt-in int8 scalar quantization for Qdrant-backed memory vectors. ([#4187](https://github.com/diegosouzapw/OmniRoute/pull/4187)) -- **feat(memory): opt-in sqlite-vec int8 vector quantization (F4.4 Q2)** — opt-in int8 quantization for the sqlite-vec memory backend. ([#4190](https://github.com/diegosouzapw/OmniRoute/pull/4190)) -- **feat(deploy): keep optional deps on `update` (`--include=optional`)** — the in-place update path now passes `--include=optional` so native/optional packages aren't dropped on update. ([#4260](https://github.com/diegosouzapw/OmniRoute/pull/4260)) -- **feat(dashboard): unified visual identity — grid, primitives, tables, form controls (design phases 1-4)** — a sweeping design pass aligning the dashboard with the site: grid wallpaper, button/card/input primitives, theme-aware tables and form controls. ([#4122](https://github.com/diegosouzapw/OmniRoute/pull/4122)) -- **feat(dashboard): grid wallpaper on all standalone screens + fluid 4K layout** — the identity grid now backs every standalone screen and the layout scales fluidly to 4K. ([#4158](https://github.com/diegosouzapw/OmniRoute/pull/4158)) -- **feat(dashboard): make the identity grid visible + unify the focus ring on accent** — design follow-up making the grid actually visible and standardizing focus rings on the accent color. ([#4141](https://github.com/diegosouzapw/OmniRoute/pull/4141)) -- **feat(dashboard): import only free models + free-model list controls** — the model-import page can import just the free models, with controls to manage the free-model list. ([#4176](https://github.com/diegosouzapw/OmniRoute/pull/4176) — thanks @felipesartori) -- **feat(dashboard): compact grid layout for no-auth provider accounts** — a denser grid layout for provider accounts when auth is disabled. ([#4137](https://github.com/diegosouzapw/OmniRoute/pull/4137) — thanks @felipesartori) -- **feat(dashboard): derive media `serviceKinds` from the registries (surface MiniMax + the media catalog)** — `/media-providers/[kind]` now derives its service kinds from the registries instead of a hand-maintained list, surfacing ~48 previously-invisible media providers (incl. MiniMax TTS/video/music). ([#4212](https://github.com/diegosouzapw/OmniRoute/pull/4212)) -- **feat(traffic-inspector): live (in-flight) request filter (Gap 5)** — the Traffic Inspector can filter to in-flight requests as they happen. ([#4130](https://github.com/diegosouzapw/OmniRoute/pull/4130)) -- **feat(agent-bridge): maintenance & diagnostics dashboard controls** — adds maintenance and diagnostics controls for the Agent Bridge to the dashboard. ([#4127](https://github.com/diegosouzapw/OmniRoute/pull/4127)) -- **feat(mitm): TPROXY IP_TRANSPARENT native addon + conditional loader (Epic A)** — a native `IP_TRANSPARENT` addon with a conditional loader, the foundation for TPROXY capture. ([#4148](https://github.com/diegosouzapw/OmniRoute/pull/4148)) -- **feat(mitm): Fase 3 Epic A spike — TPROXY command builder** — a transactional builder for the iptables/TPROXY command set. ([#4139](https://github.com/diegosouzapw/OmniRoute/pull/4139)) -- **feat(mitm): TPROXY setup layer — transactional apply/revert (Epic A)** — applies and reverts the TPROXY routing setup transactionally. ([#4144](https://github.com/diegosouzapw/OmniRoute/pull/4144)) -- **feat(mitm): add `setSocketMark` to the TPROXY addon (anti-loop primitive)** — exposes `setSocketMark` so OmniRoute's own egress can be marked and skipped (anti-loop). ([#4160](https://github.com/diegosouzapw/OmniRoute/pull/4160)) -- **feat(mitm): TPROXY capture-mode listener + `connectMarked` (Epic A)** — the capture-mode listener plus a marked-connect primitive. ([#4169](https://github.com/diegosouzapw/OmniRoute/pull/4169)) -- **feat(mitm): dynamic per-SNI cert authority for TPROXY (TLS decrypt 1/N)** — a per-SNI on-the-fly certificate authority, the first slice of TLS decrypt. ([#4173](https://github.com/diegosouzapw/OmniRoute/pull/4173)) -- **feat(mitm): TLS-terminating capture for TPROXY (decrypt 2/N)** — terminates TLS to capture decrypted traffic. ([#4179](https://github.com/diegosouzapw/OmniRoute/pull/4179)) -- **feat(mitm): wire the TLS decrypt engine into TPROXY capture mode (decrypt 3/N)** — connects the decrypt engine to the capture-mode pipeline. ([#4200](https://github.com/diegosouzapw/OmniRoute/pull/4200)) -- **feat(mitm): TPROXY capture-mode manager (decrypt 4a/N)** — a manager coordinating the TPROXY capture lifecycle. ([#4208](https://github.com/diegosouzapw/OmniRoute/pull/4208)) -- **feat(mitm): local-only route + trust-store installer for TPROXY decrypt (4b/N)** — a loopback-only management route plus a CA trust-store installer for the decrypt CA. ([#4211](https://github.com/diegosouzapw/OmniRoute/pull/4211)) -- **feat(dashboard): TPROXY decrypt capture toggle in the Traffic Inspector (4c/N)** — a UI toggle to enable/disable decrypted capture. ([#4216](https://github.com/diegosouzapw/OmniRoute/pull/4216)) -- **feat(compression): replace the headroom tabular encoder with a vendored GCF** — swaps the tabular encoder for a vendored GCF implementation. ([#4167](https://github.com/diegosouzapw/OmniRoute/pull/4167) — thanks @blackwell-systems) -- **feat(compression): live per-engine streaming via `compression.step` (F3.3)** — streams per-engine compression progress through a `compression.step` event. ([#4217](https://github.com/diegosouzapw/OmniRoute/pull/4217)) -- **feat(compression): show an engine node for single-engine runs in the studio** — the Compression Studio now renders an engine node even when only one engine runs. ([#4210](https://github.com/diegosouzapw/OmniRoute/pull/4210)) -- **feat(compression): expose the WaterfallInspector via a Canvas/Waterfall toggle** — adds a Canvas/Waterfall view toggle that surfaces the WaterfallInspector. ([#4238](https://github.com/diegosouzapw/OmniRoute/pull/4238)) -- **feat(compression): make `mcpAccessibility` config reachable via a settings sub-route** — exposes the `mcpAccessibility` config under a dedicated settings sub-route. ([#4237](https://github.com/diegosouzapw/OmniRoute/pull/4237)) -- **feat(compression): runnable A/B benchmark CLI (F2.4)** — a CLI to run A/B compression benchmarks. ([#4220](https://github.com/diegosouzapw/OmniRoute/pull/4220)) -- **feat(compression): add a transcript loader to the replay harness** — the replay harness can now load real transcripts. ([#4246](https://github.com/diegosouzapw/OmniRoute/pull/4246)) -- **feat(compression): wire MCP tool-cardinality reduction (F4.3, opt-in)** — opt-in reduction of MCP tool-set cardinality to shrink prompts. ([#4221](https://github.com/diegosouzapw/OmniRoute/pull/4221)) -- **feat(compression): wire RTK comment-stripping config + honor `preserveDocstrings`** — RTK comment-stripping is now configurable and honors a `preserveDocstrings` flag. ([#4242](https://github.com/diegosouzapw/OmniRoute/pull/4242)) -- **feat(compression): honor the per-filter RTK `deduplicate` flag** — RTK filters now respect a per-filter `deduplicate` flag. ([#4231](https://github.com/diegosouzapw/OmniRoute/pull/4231)) -- **feat(compression): honor the registry `enabled` flag in the stacked loop** — the stacked compression loop now skips engines disabled in the registry. ([#4244](https://github.com/diegosouzapw/OmniRoute/pull/4244)) -- **feat(compression): persist RTK grouping config (unlock R5 `enableGrouping`)** — persists the RTK grouping configuration, unlocking the R5 `enableGrouping` rule. ([#4207](https://github.com/diegosouzapw/OmniRoute/pull/4207)) -- **feat(compression): wire ultra's `modelPath`/`slmFallbackToAggressive` to the LLMLingua SLM tier** — connects the ultra tier's small-language-model knobs to the LLMLingua SLM path. ([#4257](https://github.com/diegosouzapw/OmniRoute/pull/4257)) -- **feat(quality): Onda 2 mutation-gate tooling — radiography classifier (T1) + `mutationScore` ratchet (T3)** — new mutation-testing tooling: a survivor-radiography classifier and a `mutationScore` ratchet. ([#4234](https://github.com/diegosouzapw/OmniRoute/pull/4234)) -- **feat(ci): wire the F2.4 compression budget-gate ratchet** — adds a CI ratchet that gates compression budget regressions. ([#4232](https://github.com/diegosouzapw/OmniRoute/pull/4232)) - -### 🐛 Fixed - -- **fix(providers): qwen-web model discovery now lists the live catalog instead of nothing** — the `qwen-web` cookie provider had no entry in `PROVIDER_MODELS_CONFIG`, so its model-discovery page returned an empty/stale local catalog (the OAuth fallback at the top of the route only fires for `provider === "qwen"`, leaving `qwen-web` to fall through to the no-config branch). Added a `qwen-web` entry that fetches the **public** `https://chat.qwen.ai/api/v2/models` endpoint (no auth header) and parses the `{ data: { data: [{ id, name, owned_by }] } }` shape (with a flatter `{ data: [] }` fallback). This is Problem #3 of #3931 (diagnosed by @thezukiru); Problem #1 — validator bare-token false-positive — shipped earlier in #3958, and Problem #2 — empty stream from Qwen WAF bot-detection on the streaming endpoint — remains a separate upstream/stealth concern. ([#3931](https://github.com/diegosouzapw/OmniRoute/issues/3931) — thanks @thezukiru) -- **fix(providers): ZenMux model discovery now lists the live catalog (incl. the free models) instead of the stale 9-entry hardcoded list** — adding a ZenMux key validated fine, but the connection then showed `API unavailable — using local catalog` and was missing the free models ZenMux advertises (`z-ai/glm-5.2-free`, `moonshotai/kimi-k2.7-code-free`). Root cause: `zenmux` carries a correct `modelsUrl` in the registry, but — like `llm7`/`byteplus` before #3976 — it was not classified by any live-fetch branch of the model-import route (not `openai-compatible-*`, not self-hosted, not in `NAMED_OPENAI_STYLE_PROVIDERS`), so the route never probed the upstream `/models` and fell through to the registry's hardcoded `models[]`. Added `zenmux` to `NAMED_OPENAI_STYLE_PROVIDERS`, so the route probes `https://zenmux.ai/api/v1/models` (the `/chat/completions`-stripped `/models` candidate) and serves the live list, falling back to the local catalog only when the upstream fetch fails — import never breaks. ([#4202](https://github.com/diegosouzapw/OmniRoute/issues/4202) — thanks @mikmaneggahommie) -- **fix(providers): Vercel AI Gateway "import models" now loads the live catalog instead of nothing** — adding a Vercel AI Gateway key worked, but clicking **import** on the models page loaded nothing usable (manually adding the same models worked). Same class as #4202 (zenmux) / #3976 (llm7/byteplus): `vercel-ai-gateway` carries a real `baseUrl` (`https://ai-gateway.vercel.sh/v1/chat/completions`, format `openai`) in the registry, but was not classified by any live-fetch branch of the model-import route (not `openai-compatible-*`, not self-hosted, not in `NAMED_OPENAI_STYLE_PROVIDERS`), so the route never probed the upstream `/models` and fell through to the registry's tiny 5-entry hardcoded `models[]`. Added `vercel-ai-gateway` to `NAMED_OPENAI_STYLE_PROVIDERS`, so the route probes `https://ai-gateway.vercel.sh/v1/models` (the `/chat/completions`-stripped `/models` candidate) and serves the live list, falling back to the local catalog only when the upstream fetch fails — import never breaks. ([#4249](https://github.com/diegosouzapw/OmniRoute/issues/4249) — thanks @FerLuisxd) -- **fix(sse): clear error when the request queue drops a job (no more fake-upstream "This job timed out after Nms")** — under concurrent load, requests that exceed the per-connection rate-limit queue budget (`resilienceSettings.requestQueue.maxWaitMs`) were dropped by Bottleneck with its raw `This job timed out after ms.` message. That string is indistinguishable from an upstream gateway timeout, so the 502 body and call-log `last_error` looked like a provider outage across unrelated providers (TI:0\|TO:0) — an operator spent ~3h misdiagnosing local queue saturation as upstream failures. `withRateLimit` now rewrites that specific Bottleneck error into a clear, OmniRoute-owned message that names the knob (`requestQueue.maxWaitMs`, tunable in Settings → Resilience), explicitly disclaims an upstream timeout, preserves the original as `cause`, and tags `code: "RATE_LIMIT_QUEUE_TIMEOUT"`. Behavior is unchanged — the job is still dropped so combo falls back to the next target. ([#4165](https://github.com/diegosouzapw/OmniRoute/issues/4165) — thanks @KooshaPari) -- **fix(api): advertise the built-in `auto/*` combos in `/v1/models`** — OmniRoute ships a zero-setup `auto/*` catalog (`auto/best-coding`, `auto/pro-reasoning`, …, 16 variants) that the dashboard advertises and that resolve on demand, but the `/v1/models` listing only emitted persisted DB combos + provider models. Clients that build their model picker from `/v1/models` (e.g. Hermes Agent) never saw any `auto/*` option. The catalog now emits every `AUTO_TEMPLATE_VARIANTS` id (as `owned_by: "combo"`) at the top of the list, deduped against persisted combos. (Showing each `auto/*`'s dynamically-selected members is a separate enhancement.) ([#4164](https://github.com/diegosouzapw/OmniRoute/issues/4164) — thanks @MRDGH2821) -- **fix(sse): restore MCP / third-party tool names on the native Claude path (MCP dispatch broken in Claude Code)** — since 3.8.27, every MCP tool call routed through OmniRoute to a native Claude OAuth provider failed client-side with `Error: No such tool available: `: tool schemas arrived fine but the streamed `tool_use.name` reached Claude Code in its cloaked form (e.g. `McpN8nMcpSearchWorkflows` instead of the registered `mcp__n8n-mcp__search_workflows`). The native-Claude tool-name cloak stashes its per-request alias→original map as a **non-enumerable** `_toolNameMap` on the request body; the request-inspector capture added in 3.8.27 rebuilds the captured body from its serialized form (`JSON.parse(JSON.stringify(...))`), which drops non-enumerable properties, so `finalBody._toolNameMap` was empty and the response-side un-cloak silently fell back to the static built-in map — never restoring dynamic MCP / snake_case names. Built-in tools (Bash/Read/…) were unaffected (static map); cross-format paths were unaffected (they attach the map enumerably). The provider-request capture now re-attaches the per-request map (kept non-enumerable, so it still never re-serializes upstream) when the captured copy lost it, restoring MCP tool dispatch. ([#4091](https://github.com/diegosouzapw/OmniRoute/issues/4091) — thanks @pedrotecinf, @NakHalal) -- **fix(dashboard): Logs auto-refresh self-heals in embedded/proxied hosts that pin or mis-fire visibility** — a follow-up to #4054: the Request Logger still froze auto-refresh on some hosts (reported on 3.8.28 Docker, works on 3.8.24). #4054 made the initial visibility fail-open, but the pause is event-driven — a host that fires a one-shot `visibilitychange` → hidden and then keeps reporting `"hidden"` (or recovers without firing the event again) left the cached visibility flag stuck `false`, so the interval ticked but never polled (only the manual Refresh button worked). The poll tick now also re-checks the **live** `document.visibilityState`, and a **window `focus`** listener re-arms polling (a focused window is a reliable signal the page is actively viewed). A genuinely backgrounded browser tab still pauses (it reports `"hidden"` and never receives focus), preserving the #3109 network-saturation optimization. ([#4133](https://github.com/diegosouzapw/OmniRoute/issues/4133) — thanks @tjengbudi) -- **fix(capabilities): unify vision model-id detection into one shared source** — three code paths kept independent, drifting vision-model lists, so the same model id could get up to three different verdicts. Two concrete bugs: lite compression's gate was missing pixtral / llava / qwen-vl / glm-4v / kimi-vl / mistral-medium-3, so it **stripped images for those real vision models and blinded them** (same class as #4071 / #4012); and the `/v1/models` list was too broad, flagging text models (`gemma`, bare `kimi` like `kimi-k2`) as vision. All three (`modelCapabilities` routing fallback, `/v1/models` listing, lite image-strip gate) now delegate to a single conservative source `src/shared/constants/visionModels.ts`, which also restores `glm-4v` / `gemini-3` coverage and keeps the #3328 MiniMax M3 carve-out. ([#4072](https://github.com/diegosouzapw/OmniRoute/issues/4072) — thanks @diego-anselmo) -- **fix(sse): surface mid-stream Gemini errors instead of returning a truncated 200** — when an upstream Gemini SSE stream emitted some partial content and then a JSON error object (`{"error":{"code":503,"message":"…high demand…","status":"UNAVAILABLE"}}`) instead of a `candidates` payload, OmniRoute silently dropped it: the gemini→openai translator's no-candidate branch only handled `promptFeedback` (content-filter) and returned `null` for anything else, so the stream simply ended and the client got HTTP 200 with a truncated body and `finish_reason: "stop"` — masking the failure and skipping combo fallback. `geminiToOpenAIResponse` now detects an `error` object (optionally wrapped in `response`), records it as `state.upstreamError` (preserving the real status — 503/`UNAVAILABLE`, or 429 for `RESOURCE_EXHAUSTED`), and lets `stream.ts` error the stream out through the existing `onFailure`/`buildErrorBody`/`controller.error` path — the same mechanism the openai-responses translator already uses. ([#4177](https://github.com/diegosouzapw/OmniRoute/issues/4177) — thanks @hartmark) -- **fix(capabilities): resolve models.dev-synced vision metadata for Mistral `-latest` aliases** — root cause behind the #4071 heuristic: `getResolvedModelCapabilities("mistral/pixtral-12b-latest").supportsVision` resolved `null` (vision came only from the #4071 model-id heuristic, with `attachment` still `null`) even though models.dev exposes the model as multimodal. Confirmed against the live models.dev API: it catalogs Pixtral 12B under the **short** id `pixtral-12b` (with `attachment: true`, `modalities.input: ["text","image"]`), while requests use the Mistral API alias `pixtral-12b-latest`. The synced lookup tried the exact / raw / static-spec-canonical ids — all of which miss the short form — so it fell through to the heuristic. `getSyncedCapabilityForResolved` now adds a last-resort fallback that retries with a trailing `-latest` stripped, so synced metadata (`attachment` / image modalities) wins for these aliases; models whose `-latest` id is stored verbatim (e.g. `pixtral-large-latest`) keep resolving directly. Note: the models.dev sync is currently manual-only (Settings → models.dev) with no scheduled refresh, so a fresh instance still relies on the #4071 heuristic until that sync runs — a periodic-refresh cadence is left as a separate follow-up. ([#4073](https://github.com/diegosouzapw/OmniRoute/issues/4073) — thanks @diego-anselmo) -- **fix(sse): map Xiaomi MiMo reasoning control to its native `thinking:{type}` shape** — MiMo (`api.xiaomimimo.com`) controls chain-of-thought **only** via top-level `thinking:{type:"enabled"|"disabled"}` and does not understand OpenAI's `reasoning_effort`/`reasoning`, while its request validator is strict (`400 Param Incorrect`). OmniRoute's OpenAI path carried reasoning intent as `reasoning_effort`, and the claude→openai translator can leave a Claude-shaped `thinking:{type, budget_tokens}` — so the client's on/off choice was silently dropped and `budget_tokens`/`reasoning_effort` rode along as extra params the validator can reject. New `open-sse/services/mimoThinking.ts::normalizeMimoThinking` (wired in `chatCore` for `provider==="xiaomi-mimo"`) reduces any thinking object to just `{type}` (`disabled` stays; `enabled`/`adaptive`/other → `enabled`) and drops `reasoning_effort`/`reasoning`. It deliberately does **not** synthesize thinking from a bare `reasoning_effort` — `mimo-v2-omni` is non-thinking, so that could turn a silently-ignored param into a hard error. ([#4224](https://github.com/diegosouzapw/OmniRoute/pull/4224)) -- **fix(capabilities): Xiaomi MiMo `*-pro` chat models are text-only (no vision)** — only `mimo-v2.5` and `mimo-v2-omni` accept images per Xiaomi's docs; `mimo-v2.5-pro`/`mimo-v2-pro` are text-only, but `modelSpecs` marked them vision-capable and models.dev mislabels them ([hermes-agent#18884](https://github.com/NousResearch/hermes-agent/issues/18884)). Since `resolveVisionCapability` lets a synced `attachment:true` win first, an image request could be routed to a blind model (the #4071 failure mode). Corrected the specs **and** added a hard override in `resolveVisionCapability` (checked before the synced branch, anchored so `mimo-v2.5-pro` never matches the multimodal `mimo-v2.5`) that beats the wrong synced attachment. Also registered the missing native `mimo-v2-pro` chat model and the missing `mimo-v2-tts` speech model. ([#4224](https://github.com/diegosouzapw/OmniRoute/pull/4224)) -- **fix(sse): Claude Opus 4.7+/Fable 5 use adaptive thinking only (no more manual-budget 400s)** — Opus 4.7 and later (Opus 4.7/4.8, Fable 5) removed manual extended thinking: `thinking.type:"enabled"` or **any** `thinking.budget_tokens` now returns `400` ("Any request that tries to set a fixed thinking budget gets a 400" — Anthropic migration guide). Reasoning is adaptive-only, steered by `output_config.effort`. OmniRoute's OpenAI→Claude translator mapped `reasoning_effort` low/medium/high to a manual `thinking:{type:"enabled", budget_tokens}`, so those requests hard-400'd on the most-used provider (and a Claude-native passthrough client sending the legacy shape did too). A new `adaptiveThinkingOnly` model flag now drives two fixes: the translator maps `reasoning_effort` of **every** level to `{type:"adaptive"}` + `output_config.effort` (preserving the requested level, never a budget) for these models, and a `normalizeClaudeAdaptiveThinking` catch-all at the existing post-translation thinking-normalization chokepoint collapses any residual manual thinking (passthrough legacy shape, per-model defaults) to `{type:"adaptive"}`, keyed on the resolved upstream model so it covers every routing mode. Pre-4.7 models (Opus 4.6/4.5, Sonnet, Haiku) keep manual budgets unchanged. ([#4230](https://github.com/diegosouzapw/OmniRoute/pull/4230)) -- **fix(providers): strip non-default temperature/top_p/top_k for Claude Opus 4.7+/Fable 5 (fixed sampling → no 400)** — Opus 4.7 and later reject non-default `temperature`/`top_p`/`top_k` with a `400` (sampling is fixed; reasoning moved to `output_config.effort`). The translator forwarded client-supplied `temperature`/`top_p` unconditionally and the Claude registry models carried no `unsupportedParams`, so a plain OpenAI-format request with `temperature: 0.7` to `claude-opus-4-8` hard-400'd. Added `unsupportedParams: ["temperature","top_p","top_k"]` to the Opus 4.7+/Fable 5 ids in both the `claude` (dashed `claude-opus-4-8`) and `anthropic` (dotted `claude-opus-4.7`) registries, so they're stripped at the existing `getUnsupportedParams` dispatch chokepoint. Pre-4.7 Claude models still accept sampling params. ([#4230](https://github.com/diegosouzapw/OmniRoute/pull/4230)) -- **fix(providers): conditionally strip temperature/top_p for GPT-5 reasoning on the `openai` Chat Completions path (no 400 when an effort is active)** — GPT-5 reasoning models reject non-default `temperature`/`top_p` with a `400` whenever a reasoning effort is active, yet accept them again under `reasoning_effort:"none"` (the GPT-5.1+ default, i.e. non-reasoning mode). On the `openai` provider only `o3` carried `REASONING_UNSUPPORTED`; `gpt-5.5`/`gpt-5.4`/`gpt-5.4-mini`/`gpt-5.4-nano` carried no sampling guard, so a `temperature` + active-effort request hard-400'd. A static `unsupportedParams` list can't express the `none`-mode carve-out (it would over-strip the legitimate case), so the new `gpt5SamplingGuard` drops `temperature`/`top_p` only when the resolved effort is active — wired at the existing `getUnsupportedParams` chokepoint and scoped to the `openai` Chat Completions surface (the `codex` Responses path is already covered by the CodexExecutor allowlist; other providers are untouched). ([#4245](https://github.com/diegosouzapw/OmniRoute/pull/4245)) -- **fix(codex): stop silently dropping GPT-5 output verbosity (`verbosity` / `text.verbosity`)** — the GPT-5 series added an output-verbosity control: `verbosity` (low/medium/high) on Chat Completions, nested as `text.verbosity` on the Responses API. The CodexExecutor gates translated requests through an allowlist that had no `text` entry, so for the `codex` provider the hint was dropped before reaching upstream (the `openai` Chat path already forwarded it). `normalizeCodexVerbosity` now folds whichever shape arrived into a single validated `text:{verbosity}` before the allowlist (which now permits `text`), and the OpenAI Chat↔Responses request translators map `verbosity` across formats so the hint survives a format crossing for non-codex Responses backends too. Invalid/absent verbosity collapses to no `text` (status quo). ([#4245](https://github.com/diegosouzapw/OmniRoute/pull/4245)) -- **fix(sse): map `reasoning_effort` to DeepSeek V4's native `{high, max}` vocabulary** — DeepSeek V4 only understands `high`/`max` reasoning levels, so other `reasoning_effort` values are mapped onto its native vocabulary instead of being rejected. ([#4219](https://github.com/diegosouzapw/OmniRoute/pull/4219)) -- **fix(glm): default `max_tokens` and an extended timeout for GLM-5.2+ thinking** — GLM-5.2+ thinking responses are slow and need headroom, so OmniRoute now sets a sensible default `max_tokens` and a longer timeout for them. ([#4255](https://github.com/diegosouzapw/OmniRoute/pull/4255) — thanks @dhaern) -- **fix(antigravity): default `includeThoughts` for modern Gemini models** — modern Gemini models on the Antigravity path now default to including thoughts so reasoning isn't silently dropped. ([#4180](https://github.com/diegosouzapw/OmniRoute/pull/4180) — thanks @dhaern) -- **fix(provider-registry): add correct `contextLength` to theoldllm models** — fills in accurate context-window sizes for theoldllm's models. ([#4184](https://github.com/diegosouzapw/OmniRoute/pull/4184) — thanks @herjarsa) -- **fix(models): expose combo model token limits** — `/v1/models` now reports token limits for combo models. ([#4189](https://github.com/diegosouzapw/OmniRoute/pull/4189) — thanks @megamen32) -- **fix(combo): keep the passthrough quota fallback scoped** — prevents the passthrough quota fallback from leaking across unrelated targets. ([#4194](https://github.com/diegosouzapw/OmniRoute/pull/4194) — thanks @Svetznaniy33) -- **fix(combo): opt proactive-fallback compression into the TV1 bail-out (no silent target drop)** — proactive-fallback compression now participates in the TV1 bail-out so a target is never silently dropped. ([#4228](https://github.com/diegosouzapw/OmniRoute/pull/4228)) -- **fix(compression): show engine preview output** — the Compression Studio preview now renders the engine's output. ([#4128](https://github.com/diegosouzapw/OmniRoute/pull/4128) — thanks @megamen32) -- **fix(compression): harden engines against I/O failures and misconfig (F5.3)** — compression engines degrade gracefully on I/O errors and bad configuration instead of throwing. ([#4198](https://github.com/diegosouzapw/OmniRoute/pull/4198)) -- **fix(compression): harden RTK raw-output redaction + ReDoS guard for custom filters (F5.3)** — broadens RTK raw-output redaction and adds a ReDoS guard for user-supplied filter patterns. ([#4203](https://github.com/diegosouzapw/OmniRoute/pull/4203)) -- **fix(compression): bound `mcpAccessibility` `maxTextChars` on the live read path** — the live read path now clamps `maxTextChars` so a small value can't make tools disappear. ([#4206](https://github.com/diegosouzapw/OmniRoute/pull/4206)) -- **fix(dashboard): data tables paint an opaque surface so the grid doesn't bleed through** — data tables now render on an opaque surface, fixing the grid wallpaper showing through. ([#4233](https://github.com/diegosouzapw/OmniRoute/pull/4233)) -- **fix(dashboard): make the provider card hover visible (was ~1% opacity)** — the provider-card hover state was effectively invisible; it now has a visible surface. ([#4214](https://github.com/diegosouzapw/OmniRoute/pull/4214)) -- **fix(vscode): sanitize implicit editor context** — redacts sensitive filenames/keywords from the implicit VS Code editor context before it's sent upstream. ([#4124](https://github.com/diegosouzapw/OmniRoute/pull/4124) — thanks @zhiru) -- **fix(build): raise the Node heap for the local `next build` to stop OOM/stall** — bumps the build-time heap so the local production build no longer OOMs or stalls. ([#4171](https://github.com/diegosouzapw/OmniRoute/pull/4171)) -- **fix(mitm): TPROXY OUTPUT-based recipe for local traffic (validated e2e on VPS)** — switches the TPROXY rules to an OUTPUT-chain recipe so locally-originated traffic is captured; validated end-to-end on the VPS. ([#4156](https://github.com/diegosouzapw/OmniRoute/pull/4156)) -- **fix(mitm): forward anti-loop — put the bypass-marked socket on the Agent (decrypt 4d)** — places the bypass-marked socket on the HTTP Agent so OmniRoute's own forwarded traffic never re-enters the capture loop; VPS-validated. ([#4229](https://github.com/diegosouzapw/OmniRoute/pull/4229)) -- **fix(free-tiers): retire dead-tier `hasFree`, round the headline to ~1.6B, regenerate the per-provider table** — drops dead free tiers from the headline math and regenerates the per-provider free-tier table. ([#4142](https://github.com/diegosouzapw/OmniRoute/pull/4142)) -- **fix(free-tiers): retire 4 re-verified-dead free tiers, flag iflytek/sparkdesk ToS, clarify monsterapi one-time** — removes four confirmed-dead free tiers and annotates ToS/one-time caveats. ([#4152](https://github.com/diegosouzapw/OmniRoute/pull/4152)) - -### 🧪 Tests - -- **test(sse): guard the Antigravity `_toolNameMap` cloak map through the request-capture round-trip** — follow-up to #4091: the generic capture fix in `createPreparedRequestLogger().body()` (#4153) re-attaches the non-enumerable `_toolNameMap` that the request-inspector drops when it rebuilds the upstream body via `JSON.parse(JSON.stringify(...))`, but the only regression test covered the native-Claude OAuth cloak (PascalCase aliases). The Antigravity cloak differs — `cloakAntigravityToolPayload` suffixes custom tools with `_ide` (`workspace_read` → `workspace_read_ide`), leaves native tools untouched, and returns the reverse map separately — so a refactor of `providerRequestLogging.ts` or the executor could silently re-break Antigravity tool dispatch without tripping the Claude test. Adds a dedicated regression test driving the real `cloakAntigravityToolPayload` through the capture round-trip and asserting the `_ide` reverse map survives, stays non-enumerable (never re-serializes upstream), and that all-native traffic produces no spurious map (verified failing with the #4153 re-attach removed). No production change. ([#4181](https://github.com/diegosouzapw/OmniRoute/issues/4181) — thanks @hertznsk) -- **test(chatcore): dedicated unit tests for 6 leaves + wire into stryker mutate (QG v2 Fase 9 T5 Fase 3)** — adds focused unit tests for 6 chatCore leaf helpers and enrolls them in mutation testing. ([#4218](https://github.com/diegosouzapw/OmniRoute/pull/4218)) -- **test(chatcore): telemetry / memory-skills / semantic-cache tests + wire 2 into stryker (QG v2 Fase 9 T5 Fase 3)** — new tests for the telemetry, memory-skills and semantic-cache leaves, two of which are added to the mutation set. ([#4222](https://github.com/diegosouzapw/OmniRoute/pull/4222)) -- **test+ci(chatcore): semanticCache HIT-path fixture (15/15 mutate) + 350min budget headroom** — closes the semantic-cache HIT path to a full 15/15 mutation score and gives the nightly auth/accountFallback batches more budget headroom. ([#4225](https://github.com/diegosouzapw/OmniRoute/pull/4225)) -- **test(compression): close F5.1 coverage gaps (replay reducer, live accumulator, StatusDot)** — fills the remaining F5.1 compression coverage gaps. ([#4192](https://github.com/diegosouzapw/OmniRoute/pull/4192)) -- **test(db,sse): de-flake db-backup + chatcore streaming timing assertions** — stabilizes two timing-sensitive tests (fire-and-forget backup completion + a streaming race). ([#4132](https://github.com/diegosouzapw/OmniRoute/pull/4132)) -- **test: align stale integration tests surfaced post-v3.8.28 on main** — realigns integration tests that drifted after the v3.8.28 merge. ([#4129](https://github.com/diegosouzapw/OmniRoute/pull/4129)) +- **feat(cloud-agent): 通过官方 API 密钥 REST API 使用 Cursor Cloud Agent（无 IDE-OAuth 封禁风险）** — 新增 `cursor-cloud` 云代理，通过官方 REST API（`api.cursor.com`）驱动 Cursor 的后台/云代理，使用用户或服务账户 API 密钥进行认证 — 这是比复用 Cursor IDE 的 OAuth 会话（即现有的 `cursor` 服务商，带有封禁风险警告）更安全的第一方替代方案。实现为纯 REST 适配器，镜像 Devin/Jules 代理（`createTask`/`getStatus`/`sendMessage`/`listSources`），因此**不会**引入 `@cursor/sdk` 包及其各平台原生二进制文件（Cursor 的 SDK 本身只是此 REST API 的一个薄封装）。Cursor 的大写状态枚举（`CREATING`/`RUNNING`/`FINISHED`/`ERROR`）被显式映射到共享的 `CloudAgentStatus`，并且 `baseUrl` 可按凭证覆盖。凭证通过现有的 `cloud_agent_credentials` 表加密存储；无需 Schema 变更。([#4227](https://github.com/diegosouzapw/OmniRoute/issues/4227) — 感谢 @MRDGH2821) +- **feat(routing): OpenRouter 风格 `auto/:` 组合** — 自动路由现在支持带后缀的组合，将 _类别_（路由类型）与 _层级_（优化方式）分离：`auto/coding:fast`、`auto/coding:cheap`（别名 `:floor`）、`auto/coding:free`、`auto/coding:pro`、`auto/coding:reliable`，以及新的类别根 `auto/reasoning`、`auto/vision`、`auto/multimodal`。**层级**选择评分权重 — `:fast` → 快速发送，`:cheap`/`:floor` → 成本节省，`:reliable` → 新的可靠性优先方案（熔断器健康度 + 延迟稳定性）— 而 `:free`/`:pro` 按模型层级过滤候选池（`classifyTier`：免费层 vs. 高级模型）。**类别**按能力过滤候选池（`vision`/`multimodal` → 支持视觉的模型，`reasoning` → 推理/思考模型）。任何有效的 `auto/:` 均可按需解析；精选集合在 `/v1/模型` 和控制台中展示。过滤采用故障开放策略 — 如果约束条件未匹配到任何已连接的模型，则使用完整候选池，确保路由永不中断。所有组合逻辑位于新的 `open-sse/services/autoCombo/suffixComposition.ts` 中；核心 Combo 评分器（`Combo.ts`）保持不变。#4235 的第二部分（高级账户层级权重为后续跟进）。([#4235](https://github.com/diegosouzapw/OmniRoute/issues/4235) — 感谢 @MRDGH2821) +- **feat(routing): 展示 `auto/cheap`、`auto/offline`、`auto/smart` 组合（目录 ↔ README 同步）** — README 中列出了 `auto/cheap`（每令牌最便宜优先）、`auto/offline`（配额/速率限制余量最多优先）和 `auto/smart`（质量优先 + 10% 探索），它们在请求时已通过 `parseAutoPrefix` → `createVirtualAutoCombo` 正常解析。但它们之前缺失于 `AUTO_TEMPLATE_VARIANTS`，因此 `/v1/模型` 和控制台组合列表（遍历该目录）从未显示它们 — 目录与文档产生偏差（可在 issue 截图中看到）。新增这三个条目，使其与其它内置 `auto/*` 组合一起在所有位置展示。#4235 的第一部分（OpenRouter 风格 `auto/:` 后缀 + 新类别随后跟进）。([#4235](https://github.com/diegosouzapw/OmniRoute/issues/4235) — 感谢 @MRDGH2821) +- **feat(cli): 远程模式 — 使用作用域访问令牌驱动远程 OmniRoute** — 新增 CLI 模式，使用作用域访问令牌连接到远程 OmniRoute 实例，使本地 CLI 可以驱动你没有会话的服务器。([#4256](https://github.com/diegosouzapw/OmniRoute/pull/4256)) +- **feat(api): 成本遥测对齐 — 每个端点均输出 `X-OmniRoute-*` 请求头 + 非令牌成本引擎** — 每个端点现在均输出 `X-OmniRoute-*` 成本/用量请求头，由同样对非令牌（媒体/基于请求的）用量进行计价的成本引擎提供支持。([#4247](https://github.com/diegosouzapw/OmniRoute/pull/4247)) +- **feat(api): 注册 Kimi K2.7 Code 模型（`kimi-k2.7-code` + `-highspeed`）** — 新的 Moonshot 纯思考编码模型已注册（固定采样；`temperature`/`top_p` 标记为不支持）。([#4183](https://github.com/diegosouzapw/OmniRoute/pull/4183)) +- **feat(catalog): 将 `kimi-k2.7-code` 添加到 kmca 目录 + qwen-web 模型发现** — 在 kmca 目录中展示新的 Kimi 编码模型，并将 qwen-web 接入模型发现。([#4185](https://github.com/diegosouzapw/OmniRoute/pull/4185)) +- **feat(api): 扩展 `zai` 服务商目录，新增 GLM-5.2 / GLM-4.7** — 将真实的 GLM-5.2、GLM-4.7 和 GLM-4.7-flash 模型 ID 添加到 Anthropic 直连的 `zai` 服务商。([#4201](https://github.com/diegosouzapw/OmniRoute/pull/4201)) +- **feat(api): 无思考网关模型 ID（FCC 移植，Fase 8.1）** — 强制关闭思考的网关模型 ID 变体，从 free-claude-code 移植。([#4145](https://github.com/diegosouzapw/OmniRoute/pull/4145)) +- **feat(sse): 截断流的中流续传（FCC 移植，Task 4.4）** — 当流被截断时，OmniRoute 可以透明地继续它，从 free-claude-code 移植。([#4147](https://github.com/diegosouzapw/OmniRoute/pull/4147)) +- **feat(sse): 每服务商滑动窗口速率限制容灾（FCC 移植，Fase 8.2）** — 每服务商滑动窗口速率限制器作为容灾路径，从 free-claude-code 移植。([#4146](https://github.com/diegosouzapw/OmniRoute/pull/4146)) +- **feat(sse): 透明流恢复（FCC 移植，Fase 4，可选启用）** — 可选启用的中断上游流透明恢复，从 free-claude-code 移植。([#4131](https://github.com/diegosouzapw/OmniRoute/pull/4131)) +- **feat(search): 免费 DuckDuckGo 网页搜索作为最后手段服务商（FCC 移植，Fase 6）** — 新增无需密钥的 DuckDuckGo 网页搜索服务商，作为最后手段使用，从 free-claude-code 移植。([#4136](https://github.com/diegosouzapw/OmniRoute/pull/4136)) +- **feat(logging): pino 日志器中的凭证脱敏安全网（FCC 移植，Fase 8.3）** — 日志器级别的脱敏处理，从日志输出中清除凭证，从 free-claude-code 移植。([#4140](https://github.com/diegosouzapw/OmniRoute/pull/4140)) +- **feat(memory): 可选启用 Qdrant 标量 int8 量化（F4.4 Q1）** — 对 Qdrant 后端记忆向量进行可选启用的 int8 标量量化。([#4187](https://github.com/diegosouzapw/OmniRoute/pull/4187)) +- **feat(memory): 可选启用 sqlite-vec int8 向量量化（F4.4 Q2）** — 对 sqlite-vec 记忆后端进行可选启用的 int8 量化。([#4190](https://github.com/diegosouzapw/OmniRoute/pull/4190)) +- **feat(deploy): `update` 时保留可选依赖（`--include=optional`）** — 原地更新路径现在传递 `--include=optional`，使原生/可选包在更新时不会被丢弃。([#4260](https://github.com/diegosouzapw/OmniRoute/pull/4260)) +- **feat(dashboard): 统一视觉标识 — 网格、基础元素、表格、表单控件（设计阶段 1-4）** — 一次全面的设计调整，使控制台与主站对齐：网格壁纸、按钮/卡片/输入基础元素、主题感知表格和表单控件。([#4122](https://github.com/diegosouzapw/OmniRoute/pull/4122)) +- **feat(dashboard): 所有独立屏幕的网格壁纸 + 流畅 4K 布局** — 标识网格现在覆盖所有独立屏幕，布局可流畅缩放到 4K。([#4158](https://github.com/diegosouzapw/OmniRoute/pull/4158)) +- **feat(dashboard): 使标识网格可见 + 统一强调色焦点环** — 设计跟进，使网格实际可见并将焦点环标准化为强调色。([#4141](https://github.com/diegosouzapw/OmniRoute/pull/4141)) +- **feat(dashboard): 仅导入免费模型 + 免费模型列表控件** — 模型导入页面可以仅导入免费模型，并提供管理免费模型列表的控件。([#4176](https://github.com/diegosouzapw/OmniRoute/pull/4176) — 感谢 @felipesartori) +- **feat(dashboard): 无认证服务商账户的紧凑网格布局** — 认证禁用时，服务商账户使用更密集的网格布局。([#4137](https://github.com/diegosouzapw/OmniRoute/pull/4137) — 感谢 @felipesartori) +- **feat(dashboard): 从注册表派生媒体 `serviceKinds`（展示 MiniMax + 媒体目录）** — `/media-providers/[kind]` 现在从注册表派生其服务类型，而非手动维护的列表，展示约 48 个之前不可见的媒体服务商（包括 MiniMax TTS/视频/音乐）。([#4212](https://github.com/diegosouzapw/OmniRoute/pull/4212)) +- **feat(traffic-inspector): 实时（进行中）请求过滤（Gap 5）** — 流量检查器现在可以过滤进行中的请求。([#4130](https://github.com/diegosouzapw/OmniRoute/pull/4130)) +- **feat(agent-bridge): 维护与诊断仪表盘控件** — 为 Agent Bridge 向控制台添加维护和诊断控件。([#4127](https://github.com/diegosouzapw/OmniRoute/pull/4127)) +- **feat(mitm): TPROXY IP_TRANSPARENT 原生插件 + 条件加载器（Epic A）** — 原生 `IP_TRANSPARENT` 插件及条件加载器，为 TPROXY 捕获奠定基础。([#4148](https://github.com/diegosouzapw/OmniRoute/pull/4148)) +- **feat(mitm): Fase 3 Epic A 探索 — TPROXY 命令构建器** — iptables/TPROXY 命令集的事务式构建器。([#4139](https://github.com/diegosouzapw/OmniRoute/pull/4139)) +- **feat(mitm): TPROXY 设置层 — 事务式应用/回滚（Epic A）** — 以事务方式应用和回滚 TPROXY 路由设置。([#4144](https://github.com/diegosouzapw/OmniRoute/pull/4144)) +- **feat(mitm): 向 TPROXY 插件添加 `setSocketMark`（反循环原语）** — 暴露 `setSocketMark`，使 OmniRoute 自身的出口流量可以被标记并跳过（反循环）。([#4160](https://github.com/diegosouzapw/OmniRoute/pull/4160)) +- **feat(mitm): TPROXY 捕获模式监听器 + `connectMarked`（Epic A）** — 捕获模式监听器加上标记连接原语。([#4169](https://github.com/diegosouzapw/OmniRoute/pull/4169)) +- **feat(mitm): 针对 TPROXY 的动态每 SNI 证书颁发机构（TLS 解密 1/N）** — 每 SNI 即时证书颁发机构，TLS 解密的第一部分。([#4173](https://github.com/diegosouzapw/OmniRoute/pull/4173)) +- **feat(mitm): 针对 TPROXY 的 TLS 终结捕获（解密 2/N）** — 终结 TLS 以捕获解密流量。([#4179](https://github.com/diegosouzapw/OmniRoute/pull/4179)) +- **feat(mitm): 将 TLS 解密引擎接入 TPROXY 捕获模式（解密 3/N）** — 将解密引擎连接到捕获模式管线。([#4200](https://github.com/diegosouzapw/OmniRoute/pull/4200)) +- **feat(mitm): TPROXY 捕获模式管理器（解密 4a/N）** — 协调 TPROXY 捕获生命周期的管理器。([#4208](https://github.com/diegosouzapw/OmniRoute/pull/4208)) +- **feat(mitm): 本地专用路由 + 信任存储安装器，用于 TPROXY 解密（4b/N）** — 仅回环的管理路由加上解密 CA 的 CA 信任存储安装器。([#4211](https://github.com/diegosouzapw/OmniRoute/pull/4211)) +- **feat(dashboard): 流量检查器中的 TPROXY 解密捕获开关（4c/N）** — 用于启用/禁用解密捕获的 UI 开关。([#4216](https://github.com/diegosouzapw/OmniRoute/pull/4216)) +- **feat(compression): 用内置 GCF 替换余量表格编码器** — 将表格编码器替换为内置 GCF 实现。([#4167](https://github.com/diegosouzapw/OmniRoute/pull/4167) — 感谢 @blackwell-systems) +- **feat(compression): 通过 `compression.step` 实现每引擎实时流式传输（F3.3）** — 通过 `压缩.step` 事件流式传输每引擎压缩进度。([#4217](https://github.com/diegosouzapw/OmniRoute/pull/4217)) +- **feat(compression): 在 Studio 中为单引擎运行显示引擎节点** — 压缩 Studio 现在即使只有一个引擎运行时也会渲染引擎节点。([#4210](https://github.com/diegosouzapw/OmniRoute/pull/4210)) +- **feat(compression): 通过 Canvas/Waterfall 开关暴露 WaterfallInspector** — 新增 Canvas/Waterfall 视图开关，展示 WaterfallInspector。([#4238](https://github.com/diegosouzapw/OmniRoute/pull/4238)) +- **feat(compression): 通过设置子路由使 `mcpAccessibility` 配置可达** — 在专用设置子路由下暴露 `mcpAccessibility` 配置。([#4237](https://github.com/diegosouzapw/OmniRoute/pull/4237)) +- **feat(compression): 可运行的 A/B 基准测试 CLI（F2.4）** — 用于运行 A/B 压缩基准测试的 CLI。([#4220](https://github.com/diegosouzapw/OmniRoute/pull/4220)) +- **feat(compression): 向回放测试工具添加转录加载器** — 回放测试工具现在可以加载真实转录。([#4246](https://github.com/diegosouzapw/OmniRoute/pull/4246)) +- **feat(compression): 接入 MCP 工具基数削减（F4.3，可选启用）** — 可选启用的 MCP 工具集基数削减，以缩小提示。([#4221](https://github.com/diegosouzapw/OmniRoute/pull/4221)) +- **feat(compression): 接入 RTK 注释剥离配置 + 遵循 `preserveDocstrings`** — RTK 注释剥离现在可配置并遵循 `preserveDocstrings` 标志。([#4242](https://github.com/diegosouzapw/OmniRoute/pull/4242)) +- **feat(compression): 遵循每过滤器 RTK `deduplicate` 标志** — RTK 过滤器现在遵循每过滤器的 `deduplicate` 标志。([#4231](https://github.com/diegosouzapw/OmniRoute/pull/4231)) +- **feat(compression): 在堆叠循环中遵循注册表 `enabled` 标志** — 堆叠压缩循环现在跳过注册表中已禁用的引擎。([#4244](https://github.com/diegosouzapw/OmniRoute/pull/4244)) +- **feat(compression): 持久化 RTK 分组配置（解锁 R5 `enableGrouping`）** — 持久化 RTK 分组配置，解锁 R5 `enableGrouping` 规则。([#4207](https://github.com/diegosouzapw/OmniRoute/pull/4207)) +- **feat(compression): 将 ultra 的 `modelPath`/`slmFallbackToAggressive` 接入 LLMLingua SLM 层** — 将 ultra 层的小语言模型旋钮连接到 LLMLingua SLM 路径。([#4257](https://github.com/diegosouzapw/OmniRoute/pull/4257)) +- **feat(quality): Onda 2 变异门工具 — 射线分类器（T1）+ `mutationScore` 棘轮（T3）** — 新的变异测试工具：幸存者射线分类器和 `mutationScore` 棘轮。([#4234](https://github.com/diegosouzapw/OmniRoute/pull/4234)) +- **feat(ci): 接入 F2.4 压缩预算门棘轮** — 新增 CI 棘轮，防止压缩预算回退。([#4232](https://github.com/diegosouzapw/OmniRoute/pull/4232)) + +### 🐛 问题修复 + +- **fix(providers): qwen-web 模型发现现在列出实时目录而非空目录** — `qwen-web` cookie 服务商在 `PROVIDER_MODELS_CONFIG` 中没有条目，因此其模型发现页面返回空/过时的本地目录（路由顶部的 OAuth 容灾仅对 `服务商 === "qwen"` 生效，导致 `qwen-web` 落入无配置分支）。新增一个 `qwen-web` 条目，获取**公开**的 `https://chat.qwen.ai/api/v2/模型` 端点（无需认证请求头）并解析 `{ data: { data: [{ id, name, owned_by }] } }` 结构（带更扁平的 `{ data: [] }` 容灾）。这是 #3931 的问题 #3（由 @thezukiru 诊断）；问题 #1 — 校验器裸令牌误报 — 已在 #3958 中发布，问题 #2 — Qwen WAF 在流式传输端点的机器人检测导致空流 — 仍然是独立的上游/隐身问题。([#3931](https://github.com/diegosouzapw/OmniRoute/issues/3931) — 感谢 @thezukiru) +- **fix(providers): ZenMux 模型发现现在列出实时目录（含免费模型）而非过时的 9 条目硬编码列表** — 添加 ZenMux 密钥校验正常，但连接随后显示 `API unavailable — using local catalog` 并缺少 ZenMux 宣传的免费模型（`z-ai/glm-5.2-free`、`moonshotai/kimi-k2.7-code-free`）。根本原因：`zenmux` 在注册表中带有正确的 `modelsUrl`，但是 — 与 #3976 之前的 `llm7`/`byteplus` 一样 — 它未被模型导入路由的任何实时获取分支分类（不是 `openai-compatible-*`、不是自托管、不在 `NAMED_OPENAI_STYLE_PROVIDERS` 中），因此路由从未探测上游 `/模型` 并落入注册表的硬编码 `模型[]`。将 `zenmux` 添加到 `NAMED_OPENAI_STYLE_PROVIDERS`，使路由探测 `https://zenmux.ai/api/v1/模型`（去掉 `/chat/completions` 的 `/模型` 候选）并提供实时列表，仅在上游获取失败时回退到本地目录 — 导入永不中断。([#4202](https://github.com/diegosouzapw/OmniRoute/issues/4202) — 感谢 @mikmaneggahommie) +- **fix(providers): Vercel AI Gateway"导入模型"现在加载实时目录而非空目录** — 添加 Vercel AI Gateway 密钥有效，但在模型页面点击**导入**时没有加载任何可用内容（手动添加相同模型有效）。与 #4202（zenmux）/ #3976（llm7/byteplus）同类型：`vercel-ai-网关` 在注册表中带有真实的 `baseUrl`（`https://ai-网关.vercel.sh/v1/chat/completions`，格式 `openai`），但未被模型导入路由的任何实时获取分支分类（不是 `openai-compatible-*`、不是自托管、不在 `NAMED_OPENAI_STYLE_PROVIDERS` 中），因此路由从未探测上游 `/模型` 并落入注册表的 5 条目硬编码 `模型[]`。将 `vercel-ai-网关` 添加到 `NAMED_OPENAI_STYLE_PROVIDERS`，使路由探测 `https://ai-网关.vercel.sh/v1/模型`（去掉 `/chat/completions` 的 `/模型` 候选）并提供实时列表，仅在上游获取失败时回退到本地目录 — 导入永不中断。([#4249](https://github.com/diegosouzapw/OmniRoute/issues/4249) — 感谢 @FerLuisxd) +- **fix(sse): 请求队列丢弃任务时提供清晰错误（不再有伪造上游的"This job timed out after Nms"）** — 在并发负载下，超出每连接速率限制队列预算（`resilienceSettings.requestQueue.maxWaitMs`）的请求被 Bottleneck 以原始 `This job timed out after ms.` 消息丢弃。该字符串与上游网关超时无法区分，因此 502 响应体和调用日志 `last_error` 看起来像是跨无关服务商的服务商宕机（TI:0\|TO:0）— 一位运维人员花了约 3 小时将本地队列饱和误诊为上游故障。`withRateLimit` 现在将该特定 Bottleneck 错误重写为一条清晰的、OmniRoute 自有消息，指明可调参数（`requestQueue.maxWaitMs`，可在 Settings → Resilience 中调整），明确否认上游超时，保留原始错误作为 `cause`，并标记 `code: "RATE_LIMIT_QUEUE_TIMEOUT"`。行为不变 — 任务仍被丢弃，Combo 回退到下一个目标。([#4165](https://github.com/diegosouzapw/OmniRoute/issues/4165) — 感谢 @KooshaPari) +- **fix(api): 在 `/v1/models` 中展示内置 `auto/*` 组合** — OmniRoute 附带零配置 `auto/*` 目录（`auto/best-coding`、`auto/pro-reasoning`、…、16 个变体），仪表盘已展示并可按需解析，但 `/v1/models` 列表仅输出持久化的 DB 组合 + 服务商模型。从 `/v1/models` 构建模型选择器的客户端（如 Hermes Agent）从未看到任何 `auto/*` 选项。目录现在在列表顶部输出每个 `AUTO_TEMPLATE_VARIANTS` ID（作为 `owned_by: "combo"`），并与持久化组合去重。（显示每个 `auto/*` 的动态选定成员是单独的增强功能。）([#4164](https://github.com/diegosouzapw/OmniRoute/issues/4164) — 感谢 @MRDGH2821) +- **fix(sse): 在原生 Claude 路径上恢复 MCP / 第三方工具名称（Claude Code 中 MCP 调度中断）** — 自 3.8.27 起，通过 OmniRoute 路由到原生 Claude OAuth 服务商的每个 MCP 工具调用都在客户端失败，报错 `Error: No such tool available: `：工具 Schema 正常到达，但流式传输的 `tool_use.name` 以其伪装形式到达 Claude Code（例如 `McpN8nMcpSearchWorkflows` 而非注册的 `mcp__n8n-mcp__search_workflows`）。原生 Claude 工具名称伪装将其每请求别名→原始映射作为**不可枚举**的 `_toolNameMap` 存储在请求体上；3.8.27 中添加的请求检查器捕获从序列化形式（`JSON.parse(JSON.stringify(...))`）重建捕获体，这会丢弃不可枚举属性，因此 `finalBody._toolNameMap` 为空，响应端反伪装静默回退到静态内置映射 — 从不恢复动态 MCP / snake_case 名称。内置工具（Bash/Read/…）不受影响（静态映射）；跨格式路径不受影响（它们以可枚举方式附加映射）。服务商请求捕获现在在捕获副本丢失时重新附加每请求映射（保持不可枚举，因此仍不会重新序列化到上游），恢复 MCP 工具调度。([#4091](https://github.com/diegosouzapw/OmniRoute/issues/4091) — 感谢 @pedrotecinf, @NakHalal) +- **fix(dashboard): 日志自动刷新在嵌入/代理主机中自愈，这些主机会卡住或误触发可见性** — #4054 的后续：请求日志器在某些主机上仍然冻结自动刷新（3.8.28 Docker 上报，3.8.24 正常工作）。#4054 使初始可见性故障开放，但暂停是事件驱动的 — 主机触发一次性 `visibilitychange` → hidden 然后持续报告 `"hidden"`（或恢复但不再次触发事件），导致缓存的可见性标志卡在 `false`，因此间隔计时器在滴答但从不轮询（只有手动刷新按钮有效）。轮询滴答现在还会重新检查**实时** `document.visibilityState`，并且**窗口 `focus`** 监听器重新启用轮询（聚焦窗口是页面正在被查看的可靠信号）。真正处于后台的浏览器标签页仍然暂停（它报告 `"hidden"` 且从不接收焦点），保留 #3109 的网络饱和优化。([#4133](https://github.com/diegosouzapw/OmniRoute/issues/4133) — 感谢 @tjengbudi) +- **fix(capabilities): 将视觉模型 ID 检测统一到一个共享源** — 三个代码路径各自维护独立的、漂移的视觉模型列表，因此同一个模型 ID 可能得到最多三种不同的判定。两个具体缺陷：lite 压缩的门控缺失 pixtral / llava / qwen-vl / glm-4v / kimi-vl / mistral-medium-3，因此它**对这些真正的视觉模型剥离图像并使其致盲**（与 #4071 / #4012 同类型）；而 `/v1/模型` 列表过于宽泛，将文本模型（`gemma`、裸 `kimi` 如 `kimi-k2`）标记为视觉模型。所有三个（`modelCapabilities` 路由容灾、`/v1/模型` 列表、lite 图像剥离门控）现在委托给单一保守源 `src/shared/constants/visionModels.ts`，该源还恢复了 `glm-4v` / `gemini-3` 覆盖率并保留 #3328 MiniMax M3 的例外处理。([#4072](https://github.com/diegosouzapw/OmniRoute/issues/4072) — 感谢 @diego-anselmo) +- **fix(sse): 暴露中流 Gemini 错误，而非返回截断的 200** — 当上游 Gemini SSE 流发出部分内容后发出 JSON 错误对象（`{"错误":{"code":503,"message":"…high demand…","status":"UNAVAILABLE"}}`）而非 `candidates` 载荷时，OmniRoute 静默丢弃它：gemini→openai 翻译器的无候选分支仅处理 `promptFeedback`（内容过滤器），对其他情况返回 `null`，因此流直接结束，客户端收到 HTTP 200 及截断体和 `finish_reason: "stop"` — 掩盖故障并跳过 Combo 容灾。`geminiToOpenAIResponse` 现在检测 `错误` 对象（可选地包裹在 `响应` 中），将其记录为 `state.upstreamError`（保留真实状态 — 503/`UNAVAILABLE`，或 429 对应 `RESOURCE_EXHAUSTED`），并通过现有 `onFailure`/`buildErrorBody`/`controller.错误` 路径将流出错 — 与 openai-responses 翻译器已使用的机制相同。([#4177](https://github.com/diegosouzapw/OmniRoute/issues/4177) — 感谢 @hartmark) +- **fix(capabilities): 为 Mistral `-latest` 别名解析 models.dev 同步的视觉元数据** — #4071 启发式背后的根本原因：`getResolvedModelCapabilities("mistral/pixtral-12b-latest").supportsVision` 解析为 `null`（视觉仅来自 #4071 模型 ID 启发式，`attachment` 仍为 `null`），尽管模型.dev 将该模型列为多模态。经实时模型.dev API 确认：它将 Pixtral 12B 归类在**短** ID `pixtral-12b` 下（`attachment: true`、`modalities.input: ["text","image"]`），而请求使用 Mistral API 别名 `pixtral-12b-latest`。同步查询尝试了精确/原始/静态规范 ID — 全部错过短形式 — 因此落入启发式。`getSyncedCapabilityForResolved` 现在添加了最后手段容灾，去掉尾部 `-latest` 重试，使同步元数据（`attachment` / 图像模态）对这些别名生效；其 `-latest` ID 以完整形式存储的模型（如 `pixtral-large-latest`）继续直接解析。注意：模型.dev 同步目前仅支持手动（Settings → 模型.dev），没有定时刷新，因此新实例在同步运行前仍依赖 #4071 启发式 — 定期刷新节奏留作后续跟进。([#4073](https://github.com/diegosouzapw/OmniRoute/issues/4073) — 感谢 @diego-anselmo) +- **fix(sse): 将 Xiaomi MiMo 推理控制映射到其原生 `thinking:{type}` 形式** — MiMo（`api.xiaomimimo.com`）**仅**通过顶级 `thinking:{type:"enabled"|"disabled"}` 控制思维链，不理解 OpenAI 的 `reasoning_effort`/`reasoning`，而其请求校验器是严格的（`400 Param Incorrect`）。OmniRoute 的 OpenAI 路径将推理意图作为 `reasoning_effort` 携带，而 claude→openai 翻译器可能留下 Claude 形式的 `thinking:{type, budget_tokens}` — 因此客户端的开关选择被静默丢弃，`budget_tokens`/`reasoning_effort` 作为额外参数附带，校验器可能拒绝。新的 `open-sse/services/mimoThinking.ts::normalizeMimoThinking`（在 `chatCore` 中为 `provider==="xiaomi-mimo"` 接入）将任何 thinking 对象精简为仅 `{type}`（`disabled` 保留；`enabled`/`adaptive`/其他 → `enabled`）并丢弃 `reasoning_effort`/`reasoning`。它故意**不**从裸 `reasoning_effort` 合成 thinking — `mimo-v2-omni` 是非思考模型，因此这可能会将静默忽略的参数变成硬错误。([#4224](https://github.com/diegosouzapw/OmniRoute/pull/4224)) +- **fix(capabilities): Xiaomi MiMo `*-pro` 聊天模型仅支持文本（无视觉）** — 根据 Xiaomi 文档，仅 `mimo-v2.5` 和 `mimo-v2-omni` 接受图像；`mimo-v2.5-pro`/`mimo-v2-pro` 仅支持文本，但 `modelSpecs` 将其标记为支持视觉，且模型.dev 也错误标记（[hermes-agent#18884](https://github.com/NousResearch/hermes-agent/issues/18884)）。由于 `resolveVisionCapability` 让同步的 `attachment:true` 优先，图像请求可能被路由到不支持视觉的模型（#4071 故障模式）。修正了规格**并**在 `resolveVisionCapability` 中添加了硬覆盖（在同步分支之前检查，锚定使 `mimo-v2.5-pro` 永不匹配多模态 `mimo-v2.5`），覆盖错误的同步 attachment。还注册了缺失的原生 `mimo-v2-pro` 聊天模型和缺失的 `mimo-v2-tts` 语音模型。([#4224](https://github.com/diegosouzapw/OmniRoute/pull/4224)) +- **fix(sse): Claude Opus 4.7+/Fable 5 仅使用自适应思考（不再有手动预算 400）** — Opus 4.7 及更高版本（Opus 4.7/4.8、Fable 5）移除了手动扩展思考：`thinking.type:"enabled"` 或**任何** `thinking.budget_tokens` 现在返回 `400`（"Any request that tries to set a fixed thinking budget gets a 400" — Anthropic 迁移指南）。推理仅支持自适应，由 `output_config.effort` 控制。OmniRoute 的 OpenAI→Claude 翻译器将 `reasoning_effort` 低/中/高映射到手动 `thinking:{type:"enabled", budget_tokens}`，因此这些请求在最常用的服务商上硬 400（发送旧格式的 Claude 原生透传客户端也是如此）。新的 `adaptiveThinkingOnly` 模型标志现在驱动两项修复：翻译器将**每个**级别的 `reasoning_effort` 映射到 `{type:"adaptive"}` + `output_config.effort`（保留请求级别，永不设预算）用于这些模型，并且在现有翻译后思考规范化阻塞点的 `normalizeClaudeAdaptiveThinking` 兜底将任何残留的手动思考（透传旧格式、每模型默认值）折叠为 `{type:"adaptive"}`，以解析后的上游模型为键，覆盖所有路由模式。4.7 之前的模型（Opus 4.6/4.5、Sonnet、Haiku）保持手动预算不变。([#4230](https://github.com/diegosouzapw/OmniRoute/pull/4230)) +- **fix(providers): 为 Claude Opus 4.7+/Fable 5 剥离非默认 temperature/top_p/top_k（固定采样 → 无 400）** — Opus 4.7 及更高版本以 `400` 拒绝非默认 `temperature`/`top_p`/`top_k`（采样固定；推理移至 `output_config.effort`）。翻译器无条件转发客户端提供的 `temperature`/`top_p`，且 Claude 注册表模型没有 `unsupportedParams`，因此对 `claude-opus-4-8` 的普通 OpenAI 格式请求 `temperature: 0.7` 硬 400。将 `unsupportedParams: ["temperature","top_p","top_k"]` 添加到 `claude`（短横线 `claude-opus-4-8`）和 `anthropic`（点号 `claude-opus-4.7`）注册表中的 Opus 4.7+/Fable 5 ID，使其在现有 `getUnsupportedParams` 调度阻塞点被剥离。4.7 之前的 Claude 模型仍接受采样参数。([#4230](https://github.com/diegosouzapw/OmniRoute/pull/4230)) +- **fix(providers): 在 `openai` Chat Completions 路径上有条件剥离 GPT-5 推理的 temperature/top_p（推理激活时无 400）** — GPT-5 推理模型在推理激活时以 `400` 拒绝非默认 `temperature`/`top_p`，但在 `reasoning_effort:"none"`（GPT-5.1+ 默认值，即非推理模式）下又接受它们。在 `openai` 服务商上，仅 `o3` 带有 `REASONING_UNSUPPORTED`；`gpt-5.5`/`gpt-5.4`/`gpt-5.4-mini`/`gpt-5.4-nano` 没有采样守卫，因此 `temperature` + 激活推理请求硬 400。静态 `unsupportedParams` 列表无法表达 `none` 模式例外（会过度剥离合法情况），因此新的 `gpt5SamplingGuard` 仅在解析后的推理激活时丢弃 `temperature`/`top_p` — 接入现有 `getUnsupportedParams` 阻塞点，范围限定为 `openai` Chat Completions 接口（`codex` Responses 路径已由 CodexExecutor 允许列表覆盖；其他服务商不受影响）。([#4245](https://github.com/diegosouzapw/OmniRoute/pull/4245)) +- **fix(codex): 停止静默丢弃 GPT-5 输出详细程度（`verbosity` / `text.verbosity`）** — GPT-5 系列新增输出详细程度控制：Chat Completions 上的 `verbosity`（low/medium/high），嵌套为 Responses API 上的 `text.verbosity`。CodexExecutor 通过允许列表过滤翻译后的请求，该列表没有 `text` 条目，因此对于 `codex` 服务商，提示在到达上游前被丢弃（`openai` Chat 路径已经转发它）。`normalizeCodexVerbosity` 现在在允许列表（现在允许 `text`）之前将到达的任何形式折叠为单个经过校验的 `text:{verbosity}`，并且 OpenAI Chat↔Responses 请求翻译器跨格式映射 `verbosity`，使提示在非 codex Responses 后端的格式转换中也能保留。无效/缺失的详细程度折叠为无 `text`（现状）。([#4245](https://github.com/diegosouzapw/OmniRoute/pull/4245)) +- **fix(sse): 将 `reasoning_effort` 映射到 DeepSeek V4 的原生 `{high, max}` 词汇** — DeepSeek V4 仅理解 `high`/`max` 推理级别，因此其他 `reasoning_effort` 值被映射到其原生词汇而非被拒绝。([#4219](https://github.com/diegosouzapw/OmniRoute/pull/4219)) +- **fix(glm): 为 GLM-5.2+ 思考设置默认 `max_tokens` 和延长超时** — GLM-5.2+ 思考响应较慢且需要余量，因此 OmniRoute 现在为其设置合理的默认 `max_tokens` 和更长的超时。([#4255](https://github.com/diegosouzapw/OmniRoute/pull/4255) — 感谢 @dhaern) +- **fix(antigravity): 现代 Gemini 模型的默认 `includeThoughts`** — Antigravity 路径上的现代 Gemini 模型现在默认包含思考，使推理不会被静默丢弃。([#4180](https://github.com/diegosouzapw/OmniRoute/pull/4180) — 感谢 @dhaern) +- **fix(provider-registry): 为 theoldllm 模型添加正确的 `contextLength`** — 为 theoldllm 的模型填入准确的上下文窗口大小。([#4184](https://github.com/diegosouzapw/OmniRoute/pull/4184) — 感谢 @herjarsa) +- **fix(models): 暴露组合模型令牌限制** — `/v1/models` 现在报告组合模型的令牌限制。([#4189](https://github.com/diegosouzapw/OmniRoute/pull/4189) — 感谢 @megamen32) +- **fix(combo): 保持透传配额容灾的范围限制** — 防止透传配额容灾泄漏到无关目标。([#4194](https://github.com/diegosouzapw/OmniRoute/pull/4194) — 感谢 @Svetznaniy33) +- **fix(combo): 将主动容灾压缩纳入 TV1 逃生机制（无静默目标丢弃）** — 主动容灾压缩现在参与 TV1 逃生机制，确保目标永不静默丢弃。([#4228](https://github.com/diegosouzapw/OmniRoute/pull/4228)) +- **fix(compression): 显示引擎预览输出** — 压缩 Studio 预览现在渲染引擎的输出。([#4128](https://github.com/diegosouzapw/OmniRoute/pull/4128) — 感谢 @megamen32) +- **fix(compression): 加固引擎应对 I/O 故障和错误配置（F5.3）** — 压缩引擎在 I/O 错误和错误配置时优雅降级而非抛出异常。([#4198](https://github.com/diegosouzapw/OmniRoute/pull/4198)) +- **fix(compression): 加固 RTK 原始输出脱敏 + 自定义过滤器的 ReDoS 守卫（F5.3）** — 扩大 RTK 原始输出脱敏范围并为用户提供的过滤器模式添加 ReDoS 守卫。([#4203](https://github.com/diegosouzapw/OmniRoute/pull/4203)) +- **fix(compression): 在实时读取路径上限制 `mcpAccessibility` `maxTextChars`** — 实时读取路径现在钳制 `maxTextChars`，防止过小的值导致工具消失。([#4206](https://github.com/diegosouzapw/OmniRoute/pull/4206)) +- **fix(dashboard): 数据表格绘制不透明表面，防止网格透出** — 数据表格现在在不透明表面上渲染，修复网格壁纸透出的问题。([#4233](https://github.com/diegosouzapw/OmniRoute/pull/4233)) +- **fix(dashboard): 使服务商卡片悬停可见（之前约 1% 不透明度）** — 服务商卡片悬停状态之前几乎不可见；现在具有可见的表面。([#4214](https://github.com/diegosouzapw/OmniRoute/pull/4214)) +- **fix(vscode): 清理隐式编辑器上下文** — 在发送到上游之前，从隐式 VS Code 编辑器上下文中脱敏敏感文件名/关键词。([#4124](https://github.com/diegosouzapw/OmniRoute/pull/4124) — 感谢 @zhiru) +- **fix(build): 提高本地 `next build` 的 Node 堆内存以停止 OOM/卡顿** — 提高构建时堆内存，使本地生产构建不再 OOM 或卡顿。([#4171](https://github.com/diegosouzapw/OmniRoute/pull/4171)) +- **fix(mitm): 基于 OUTPUT 链的 TPROXY 方案用于本地流量（VPS 端到端验证）** — 将 TPROXY 规则切换为 OUTPUT 链方案，使本地发起的流量被捕获；在 VPS 上端到端验证。([#4156](https://github.com/diegosouzapw/OmniRoute/pull/4156)) +- **fix(mitm): 转发反循环 — 将绕过标记的套接字放在 Agent 上（解密 4d）** — 将绕过标记的套接字放在 HTTP Agent 上，使 OmniRoute 自身的转发流量永不重新进入捕获循环；VPS 验证。([#4229](https://github.com/diegosouzapw/OmniRoute/pull/4229)) +- **fix(free-tiers): 退役失效的 `hasFree` 层级，标题四舍五入为 ~1.6B，重新生成每服务商表格** — 从标题计算中移除失效的免费层级并重新生成每服务商免费层级表格。([#4142](https://github.com/diegosouzapw/OmniRoute/pull/4142)) +- **fix(free-tiers): 退役 4 个重新验证已失效的免费层级，标记 iflytek/sparkdesk ToS，澄清 monsterapi 一次性** — 移除四个确认已失效的免费层级并标注 ToS/一次性注意事项。([#4152](https://github.com/diegosouzapw/OmniRoute/pull/4152)) + +### 🧪 测试 + +- **test(sse): 通过请求捕获往返守卫 Antigravity `_toolNameMap` 伪装映射** — #4091 的后续：`createPreparedRequestLogger().body()`（#4153）中的通用捕获修复重新附加了请求检查器在通过 `JSON.parse(JSON.stringify(...))` 重建上游体时丢弃的不可枚举 `_toolNameMap`，但唯一的回归测试仅覆盖了原生 Claude OAuth 伪装（PascalCase 别名）。Antigravity 伪装不同 — `cloakAntigravityToolPayload` 为自定义工具添加 `_ide` 后缀（`workspace_read` → `workspace_read_ide`），保持原生工具不变，并单独返回反向映射 — 因此 `providerRequestLogging.ts` 或执行器的重构可能在不触发 Claude 测试的情况下静默重新破坏 Antigravity 工具调度。新增专用回归测试，驱动真实的 `cloakAntigravityToolPayload` 通过捕获往返，断言 `_ide` 反向映射存活、保持不可枚举（永不重新序列化到上游），并且全原生流量不产生伪映射（验证在移除 #4153 重新附加时失败）。无生产变更。([#4181](https://github.com/diegosouzapw/OmniRoute/issues/4181) — 感谢 @hertznsk) +- **test(chatcore): 6 个叶函数的专用单元测试 + 接入 stryker mutate（QG v2 Fase 9 T5 Fase 3）** — 为 6 个 chatCore 叶辅助函数添加聚焦单元测试并将其纳入变异测试。([#4218](https://github.com/diegosouzapw/OmniRoute/pull/4218)) +- **test(chatcore): 遥测 / 记忆技能 / 语义缓存测试 + 将 2 个接入 stryker（QG v2 Fase 9 T5 Fase 3）** — 遥测、记忆技能和语义缓存叶函数的新测试，其中两个被添加到变异集。([#4222](https://github.com/diegosouzapw/OmniRoute/pull/4222)) +- **test+ci(chatcore): semanticCache HIT 路径夹具（15/15 mutate）+ 350 分钟预算余量** — 将语义缓存 HIT 路径推进到完整的 15/15 变异分数，并为夜间认证/accountFallback 批次提供更多预算余量。([#4225](https://github.com/diegosouzapw/OmniRoute/pull/4225)) +- **test(compression): 填补 F5.1 覆盖率缺口（回放 reducer、实时累加器、StatusDot）** — 填补剩余的 F5.1 压缩覆盖率缺口。([#4192](https://github.com/diegosouzapw/OmniRoute/pull/4192)) +- **test(db,sse): 去抖动 db-backup + chatcore 流式传输时序断言** — 稳定两个时序敏感测试（即发即忘备份补全 + 流式传输竞态）。([#4132](https://github.com/diegosouzapw/OmniRoute/pull/4132)) +- **test: 对齐 v3.8.28 之后在 main 上浮现的过时集成测试** — 重新对齐 v3.8.28 合并后漂移的集成测试。([#4129](https://github.com/diegosouzapw/OmniRoute/pull/4129)) ### 📝 维护 -- **refactor(sse): split chatCore.ts pure helpers into chatCore/ modules (−561 LOC)** — extracts pure helpers out of the chatCore god-file into dedicated modules (Onda 3). ([#4159](https://github.com/diegosouzapw/OmniRoute/pull/4159)) -- **refactor(chatcore): extract passthrough/header/telemetry helpers (QG v2 Fase 9 T5 C2-C3-C5)** — further chatCore decomposition. ([#4188](https://github.com/diegosouzapw/OmniRoute/pull/4188)) -- **refactor(chatcore): extract combo/proxy context cache + semaphore helpers (QG v2 Fase 9 T5 C6-C7)** — continues the chatCore split. ([#4193](https://github.com/diegosouzapw/OmniRoute/pull/4193)) -- **refactor(combo): god-file split pilot — types + validateQuality + predicates (QG v2 Fase 9 T5 D1-D3)** — first slice of the combo.ts decomposition. ([#4162](https://github.com/diegosouzapw/OmniRoute/pull/4162)) -- **refactor(combo): god-file split part 2 — shadow + sorters + structure (QG v2 Fase 9 T5 D4-D6)** — continues the combo.ts split. ([#4175](https://github.com/diegosouzapw/OmniRoute/pull/4175)) -- **refactor(combo): god-file split part 3 — auto strategy (QG v2 Fase 9 T5 D8)** — extracts the auto strategy from combo.ts. ([#4186](https://github.com/diegosouzapw/OmniRoute/pull/4186)) -- **refactor(combo): extract round-robin sticky state to `combo/rrState.ts` (D7a)** — moves round-robin sticky state into its own module. ([#4196](https://github.com/diegosouzapw/OmniRoute/pull/4196)) -- **refactor(combo): extract the reset-aware quota block to `combo/quotaStrategies.ts` (D7b)** — moves the reset-aware quota strategies into their own module. ([#4204](https://github.com/diegosouzapw/OmniRoute/pull/4204)) -- **refactor(compression): remove vestigial SLM seam + dead deprecated alias** — drops dead compression code. ([#4253](https://github.com/diegosouzapw/OmniRoute/pull/4253)) -- **chore(compression): remove vestigial reconstructCcr/SessionDedup round-trip helpers** — removes unused round-trip helpers. ([#4226](https://github.com/diegosouzapw/OmniRoute/pull/4226)) -- **chore(compression): remove dead exports + fix stale llmlingua docs** — prunes dead exports and corrects stale LLMLingua docs. ([#4223](https://github.com/diegosouzapw/OmniRoute/pull/4223)) -- **chore(build): build + ship the TPROXY native addon in the standalone (prebuilds 4e)** — bundles the native TPROXY addon prebuilds into the standalone build. ([#4236](https://github.com/diegosouzapw/OmniRoute/pull/4236)) -- **chore(ci): add quota + 6 covered chatCore leaves to stryker mutate (QG v2 Fase 9 T5 Fase 3 follow-up)** — enrolls more covered leaves into mutation testing. ([#4209](https://github.com/diegosouzapw/OmniRoute/pull/4209)) -- **chore(ci): re-add 8 combo split leaves to stryker mutate + expand nightly batch-matrix 3→5 (QG v2 Fase 9 T5 Fase 3)** — restores mutation coverage for the split combo leaves and widens the nightly matrix. ([#4205](https://github.com/diegosouzapw/OmniRoute/pull/4205)) -- **chore(quality): close v3.8.28 cycle gate drift (re-baseline + nightly-mutation scope)** — reconciles quality-gate baselines after the v3.8.28 cycle. ([#4135](https://github.com/diegosouzapw/OmniRoute/pull/4135)) -- **ci(mutation): split nightly into 3 parallel batches to fit the 180min budget (QG v2 Fase 9 T0)** — parallelizes the nightly mutation run. ([#4150](https://github.com/diegosouzapw/OmniRoute/pull/4150)) -- **ci(mutation): restore cold-seed timeout headroom (a/b lost in #4225 squash) + extend to c/d/g/h** — restores and extends per-batch cold-seed timeouts. ([#4258](https://github.com/diegosouzapw/OmniRoute/pull/4258)) -- **ci(docs): harden the fabricated-docs checker + enforce `--strict` (QG v2 Fase 9 T9)** — tightens the anti-hallucination docs checker. ([#4149](https://github.com/diegosouzapw/OmniRoute/pull/4149)) -- **ci: derive the oasdiff base-ref from the package version + flag the mutation-toolchain regression** — fixes the OpenAPI-diff base-ref and surfaces a mutation-toolchain regression. ([#4134](https://github.com/diegosouzapw/OmniRoute/pull/4134)) -- **docs(ci): correct the mutation-gate note (no regression — `stryker -c` is `--concurrency`); record Task 12 GO** — corrects a misread of the stryker flag and records the spike GO. ([#4138](https://github.com/diegosouzapw/OmniRoute/pull/4138)) -- **docs(api): document the `/api/v1/ws` chat WebSocket endpoint in openapi.yaml** — adds the WebSocket chat endpoint to the OpenAPI spec. ([#4215](https://github.com/diegosouzapw/OmniRoute/pull/4215)) -- **docs(readme): expand Acknowledgments into a themed, star-counted credits hall** — reworks the README acknowledgments section. ([#4195](https://github.com/diegosouzapw/OmniRoute/pull/4195)) -- **style(dashboard): shrink the identity grid cell 46px → 32px (~30% smaller)** — tightens the identity grid density. ([#4143](https://github.com/diegosouzapw/OmniRoute/pull/4143)) +- **refactor(sse): 将 chatCore.ts 纯辅助函数拆分到 chatCore/ 模块（−561 LOC）** — 将纯辅助函数从 chatCore 上帝文件中提取到专用模块（Onda 3）。([#4159](https://github.com/diegosouzapw/OmniRoute/pull/4159)) +- **refactor(chatcore): 提取透传/请求头/遥测辅助函数（QG v2 Fase 9 T5 C2-C3-C5）** — 进一步 chatCore 分解。([#4188](https://github.com/diegosouzapw/OmniRoute/pull/4188)) +- **refactor(chatcore): 提取组合/代理上下文缓存 + 信号量辅助函数（QG v2 Fase 9 T5 C6-C7）** — 继续 chatCore 拆分。([#4193](https://github.com/diegosouzapw/OmniRoute/pull/4193)) +- **refactor(combo): 上帝文件拆分试点 — 类型 + validateQuality + 谓词（QG v2 Fase 9 T5 D1-D3）** — Combo.ts 分解的第一部分。([#4162](https://github.com/diegosouzapw/OmniRoute/pull/4162)) +- **refactor(combo): 上帝文件拆分第 2 部分 — shadow + 排序器 + 结构（QG v2 Fase 9 T5 D4-D6）** — 继续 Combo.ts 拆分。([#4175](https://github.com/diegosouzapw/OmniRoute/pull/4175)) +- **refactor(combo): 上帝文件拆分第 3 部分 — auto 策略（QG v2 Fase 9 T5 D8）** — 从 Combo.ts 中提取 auto 策略。([#4186](https://github.com/diegosouzapw/OmniRoute/pull/4186)) +- **refactor(combo): 将轮询粘性状态提取到 `combo/rrState.ts`（D7a）** — 将轮询粘性状态移到自己的模块中。([#4196](https://github.com/diegosouzapw/OmniRoute/pull/4196)) +- **refactor(combo): 将重置感知配额块提取到 `combo/quotaStrategies.ts`（D7b）** — 将重置感知配额策略移到自己的模块中。([#4204](https://github.com/diegosouzapw/OmniRoute/pull/4204)) +- **refactor(compression): 移除残留 SLM 接缝 + 已弃用的死别名** — 删除死压缩代码。([#4253](https://github.com/diegosouzapw/OmniRoute/pull/4253)) +- **chore(compression): 移除残留的 reconstructCcr/SessionDedup 往返辅助函数** — 移除未使用的往返辅助函数。([#4226](https://github.com/diegosouzapw/OmniRoute/pull/4226)) +- **chore(compression): 移除死导出 + 修复过时的 llmlingua 文档** — 修剪死导出并修正过时的 LLMLingua 文档。([#4223](https://github.com/diegosouzapw/OmniRoute/pull/4223)) +- **chore(build): 在独立构建中构建并打包 TPROXY 原生插件（预构建 4e）** — 将原生 TPROXY 插件预构建包打包到独立构建中。([#4236](https://github.com/diegosouzapw/OmniRoute/pull/4236)) +- **chore(ci): 将配额 + 6 个已覆盖的 chatCore 叶函数添加到 stryker mutate（QG v2 Fase 9 T5 Fase 3 后续）** — 将更多已覆盖叶函数纳入变异测试。([#4209](https://github.com/diegosouzapw/OmniRoute/pull/4209)) +- **chore(ci): 将 8 个组合拆分叶函数重新添加到 stryker mutate + 扩展夜间批次矩阵 3→5（QG v2 Fase 9 T5 Fase 3）** — 恢复拆分 Combo 叶函数的变异覆盖率并扩展夜间矩阵。([#4205](https://github.com/diegosouzapw/OmniRoute/pull/4205)) +- **chore(quality): 关闭 v3.8.28 周期门漂移（重新基线化 + 夜间变异范围）** — 调和 v3.8.28 周期后的质量门基线。([#4135](https://github.com/diegosouzapw/OmniRoute/pull/4135)) +- **ci(mutation): 将夜间任务拆分为 3 个并行批次以适应 180 分钟预算（QG v2 Fase 9 T0）** — 并行化夜间变异运行。([#4150](https://github.com/diegosouzapw/OmniRoute/pull/4150)) +- **ci(mutation): 恢复冷种子超时余量（a/b 在 #4225 合并中丢失）+ 扩展到 c/d/g/h** — 恢复并扩展每批次冷种子超时。([#4258](https://github.com/diegosouzapw/OmniRoute/pull/4258)) +- **ci(docs): 加固虚构文档检查器 + 强制执行 `--strict`（QG v2 Fase 9 T9）** — 收紧反幻觉文档检查器。([#4149](https://github.com/diegosouzapw/OmniRoute/pull/4149)) +- **ci: 从包版本派生 oasdiff base-ref + 标记变异工具链回归** — 修复 OpenAPI-diff base-ref 并暴露变异工具链回归。([#4134](https://github.com/diegosouzapw/OmniRoute/pull/4134)) +- **docs(ci): 更正变异门注释（无回归 — `stryker -c` 是 `--concurrency`）；记录 Task 12 GO** — 更正 stryker 标志的误读并记录探索 GO。([#4138](https://github.com/diegosouzapw/OmniRoute/pull/4138)) +- **docs(api): 在 openapi.yaml 中记录 `/api/v1/ws` 聊天 WebSocket 端点** — 将 WebSocket 聊天端点添加到 OpenAPI 规范中。([#4215](https://github.com/diegosouzapw/OmniRoute/pull/4215)) +- **docs(readme): 将 Acknowledgments 扩展为主题化、带星标的致谢大厅** — 重做 README 致谢部分。([#4195](https://github.com/diegosouzapw/OmniRoute/pull/4195)) +- **style(dashboard): 将标识网格单元格缩小 46px → 32px（约小 30%）** — 收紧标识网格密度。([#4143](https://github.com/diegosouzapw/OmniRoute/pull/4143)) ### 🔧 依赖 -- **deps: bump the production group with 5 updates** — routine production-dependency bumps. ([#4121](https://github.com/diegosouzapw/OmniRoute/pull/4121)) -- **chore(deps): bump github/codeql-action from 3 to 4** — CI action update. ([#4120](https://github.com/diegosouzapw/OmniRoute/pull/4120)) -- **chore(deps): bump actions/setup-python from 5 to 6** — CI action update. ([#4119](https://github.com/diegosouzapw/OmniRoute/pull/4119)) +- **deps: 将生产组更新 5 项** — 例行生产依赖更新。([#4121](https://github.com/diegosouzapw/OmniRoute/pull/4121)) +- **chore(deps): 将 github/codeql-action 从 3 更新到 4** — CI action 更新。([#4120](https://github.com/diegosouzapw/OmniRoute/pull/4120)) +- **chore(deps): 将 actions/setup-python 从 5 更新到 6** — CI action 更新。([#4119](https://github.com/diegosouzapw/OmniRoute/pull/4119)) --- @@ -982,63 +982,63 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(providers): add OrcaRouter (OpenAI-compatible routing gateway)** — OrcaRouter is now registered as an API-key provider. Its adaptive router is exposed as `orcarouter/auto` (smart routing across 150+ upstream models), alongside a curated flagship set (GPT-5.5, Gemini 3.5 Flash, Claude Opus 4.8, Grok 4.3, DeepSeek V4 Pro, MiniMax M2.7, Qwen3.7 Max). `passthroughModels` is enabled so any OrcaRouter model id works. OpenAI-compatible endpoint (`https://api.orcarouter.ai/v1`), Bearer (`sk-orca-…`) auth — no custom executor or translator required. ([#4070](https://github.com/diegosouzapw/OmniRoute/pull/4070) — thanks @jinhaosong-source) -- **feat(providers): add Wafer AI (Anthropic-compatible, Bearer auth)** — Wafer AI is now a built-in provider speaking the Anthropic Messages format with Bearer authentication, registered with its model catalog so it works out of the box. ([#4098](https://github.com/diegosouzapw/OmniRoute/pull/4098) — thanks @diegosouzapw) -- **feat(cli): `omniroute launch` — zero-config Claude Code launcher** — a new CLI subcommand that boots OmniRoute (if not already running) and launches Claude Code pre-wired to it, with no manual env/settings editing. ([#4097](https://github.com/diegosouzapw/OmniRoute/pull/4097) — thanks @diegosouzapw) -- **feat(api): exact offline token counting for the `count_tokens` fallback via tiktoken** — the local `count_tokens` fallback now uses a real tiktoken (BPE) tokenizer for exact offline counts instead of a heuristic estimate, so token budgeting is accurate even when no upstream count endpoint is reachable. ([#4087](https://github.com/diegosouzapw/OmniRoute/pull/4087) — thanks @diegosouzapw) -- **feat(sse): Claude Code quota-probe bypass + command meta-request helpers** — ported from free-claude-code: OmniRoute now recognizes Claude Code's quota-probe and command meta-requests and serves them locally instead of burning an upstream call, reducing wasted quota during CLI sessions. ([#4083](https://github.com/diegosouzapw/OmniRoute/pull/4083) — thanks @diegosouzapw) -- **feat(sse): generic 400 field-downgrade retry + Groq field stripping** — when an upstream rejects a request with `400` because of an unsupported field, OmniRoute now strips the offending field and retries (a generic downgrade path), with Groq-specific field stripping wired in. Aligned with the existing `context_management` retry handling. ([#4096](https://github.com/diegosouzapw/OmniRoute/pull/4096) — thanks @diegosouzapw) -- **feat(sse): delegated Anthropic Context Editing — relay coverage + 400-fallback** — extends the Claude server-side Context Editing delegation (#4021) with broader relay coverage and a `400`-fallback so a request the upstream rejects for the context-management beta degrades gracefully instead of failing. ([#4065](https://github.com/diegosouzapw/OmniRoute/pull/4065) — thanks @diegosouzapw) -- **feat(compression): record per-engine Context Editing telemetry** — the compression pipeline now records a `context-editing` engine entry so the dashboard attributes server-side Context Editing savings alongside the local compression engines. ([#4062](https://github.com/diegosouzapw/OmniRoute/pull/4062) — thanks @diegosouzapw) -- **feat(compression): RTK learn/discover (sample source + API + UI)** — the rule-based RTK compression engine gains a learn/discover workflow: sample a source, surface candidate rules through a new API, and review/apply them in the dashboard. ([#4088](https://github.com/diegosouzapw/OmniRoute/pull/4088) — thanks @diegosouzapw) -- **feat(dashboard): 2026-06-17 free-tier refresh — honest catalog, uncapped + boost tiers, Layout A budget table** — the free-tier page was refreshed with an honest, deep-researched catalog (pooled/realistic figures rather than inflated 24/7 RPM math), new `recurring-uncapped` and boost tiers, new providers, and a KPI + budget table (Layout A). ([#4089](https://github.com/diegosouzapw/OmniRoute/pull/4089) — thanks @diegosouzapw) -- **feat(dashboard): Combo Studio connection-cooldown badge (U1b Slice 2)** — the Combo Live cascade now surfaces each connection's cooldown state as a badge, complementing the circuit-breaker badge shipped in 3.8.27. ([#4068](https://github.com/diegosouzapw/OmniRoute/pull/4068) — thanks @diegosouzapw) -- **feat(mitm): attribute intercepted requests to the originating process (Gap 1)** — the Traffic Inspector now resolves each intercepted connection back to the originating local process (via `/proc`), so captured traffic can be attributed to the app that produced it. (ProxyBridge-inspired hardening.) ([#4085](https://github.com/diegosouzapw/OmniRoute/pull/4085) — thanks @diegosouzapw) -- **feat(mitm): capture-pipeline self-test route (Gap 12)** — a diagnostic route that exercises the MITM capture pipeline end-to-end so operators can confirm interception is working without crafting a real upstream call. ([#4093](https://github.com/diegosouzapw/OmniRoute/pull/4093) — thanks @diegosouzapw) -- **feat(mitm): loop-guard self-check + verbosity control in `server.cjs` (Gaps 14+15)** — the MITM proxy gains a self-referential loop guard (so it never proxies its own traffic into an infinite loop) and a `MITM_VERBOSE` routing-decision log level. ([#4101](https://github.com/diegosouzapw/OmniRoute/pull/4101) — thanks @diegosouzapw) -- **feat(agent-bridge): portable JSON import/export of config (Gap 4)** — the Agent Bridge / MITM configuration can now be exported to and imported from a portable JSON file, so a working setup can be backed up or moved between machines. ([#4094](https://github.com/diegosouzapw/OmniRoute/pull/4094) — thanks @diegosouzapw) - -### 🐛 Fixed - -- **fix(ws): start the LiveWS sidecar with `cwd` at the package root (global/systemd installs)** — the standalone LiveWS launcher (`scripts/start-ws-server.mjs`) re-spawns itself with `node --import tsx ` but did not set `cwd`. When the WebSocket sidecar was launched from outside the package directory — a global npm/homebrew install, or a `systemd`/`launchd` unit started from `$HOME` — Node could not resolve the `tsx` package (`ERR_MODULE_NOT_FOUND: Cannot find package 'tsx'`), and even from the package directory `tsx` could not resolve the tsconfig `@/*` path aliases (e.g. `@/types/databaseSettings`), so the sidecar never booted. The spawn now pins `cwd` to the package root (the directory above `scripts/`, where `package.json` + `tsconfig.json` live), which resolves both `tsx` discovery and the `@/*` aliases regardless of launch directory. ([#4055](https://github.com/diegosouzapw/OmniRoute/issues/4055) — thanks @Rahulsharma0810) -- **fix(dashboard): Logs page auto-refresh now works in embedded/proxied dashboards** — the Request Logger gated each auto-refresh tick on a static `document.visibilityState === "visible"` read. Hosts that report a permanent non-`"visible"` state without ever firing a `visibilitychange` event (Docker dashboard wrappers, embedded webviews) froze auto-refresh entirely — only the manual Refresh button worked, a regression from 3.8.24's unconditional polling. The pause is now event-driven and fail-open: polling starts enabled and only pauses after a real `visibilitychange` → hidden transition (still preserving the backgrounded-tab optimization for normal browser tabs). ([#4054](https://github.com/diegosouzapw/OmniRoute/issues/4054) — thanks @tjengbudi) -- **fix(docker): raise the build-stage Node heap to stop the production-build OOM** — the Docker `builder` stage ran `npm run build` with V8's default heap ceiling (~2 GB). After #4052 forced the heavier webpack engine (Turbopack panics on this Next.js version), the production optimization pass exceeded that ceiling and the build died with `FATAL ERROR: … JavaScript heap out of memory` at `[builder] npm run build`. The builder stage now sets `NODE_OPTIONS=--max-old-space-size` (default 4096 MB, overridable via `--build-arg OMNIROUTE_BUILD_MEMORY_MB=…`) before the build; the value propagates to the spawned `next build`. Build-only — the runtime heap (`OMNIROUTE_MEMORY_MB` on the runner stage) is unchanged. ([#4076](https://github.com/diegosouzapw/OmniRoute/issues/4076) — thanks @kamenkadmitry) -- **fix(dashboard): "Update Available" banner reappears reliably across Docker/npm/desktop installs** — the home-page banner is gated on `GET /api/system/version`'s `updateAvailable`, which derived the latest version ONLY from `npm info omniroute version --json` via the `npm` CLI binary. When that binary is absent from the runtime PATH (Docker/desktop/locked-down installs) or the registry is unreachable, the call returned `null` → `updateAvailable=false` → the banner silently never rendered even when a newer release existed. The route now resolves the latest version through `resolveLatestVersion()`: the fast `npm` CLI path first, then an npm-binary-free fallback over the registry HTTP API (`registry.npmjs.org/omniroute/latest`), and a logged warning instead of silent degradation when both fail. Version comparison was also hardened to tolerate `v`-prefixed and pre-release version strings. ([#4100](https://github.com/diegosouzapw/OmniRoute/issues/4100)) -- **fix(sse): route image requests only to confirmed-vision combo targets** — a combo could route an image-bearing request to a member that doesn't actually support vision. Routing now requires `supportsVision === true` (plus a model-id heuristic) before sending images to a target, so multimodal requests land only on members that can handle them. ([#4071](https://github.com/diegosouzapw/OmniRoute/pull/4071) — thanks @diego-anselmo) -- **fix(security): injection guard respects the `INJECTION_GUARD_MODE` DB feature flag** — the prompt-injection guard ignored the database feature-flag, so operators couldn't change its mode at runtime; it now reads the flag and honors the configured mode. ([#4077](https://github.com/diegosouzapw/OmniRoute/pull/4077) — thanks @zhiru) -- **fix(ws): proxy LAN `/live-ws` upgrades and warn on an unset `JWT_SECRET`** — WebSocket upgrade requests arriving over the LAN proxy path were not forwarded to the LiveWS sidecar; they are now proxied correctly, and the server logs a clear warning when `JWT_SECRET` is unset. ([#4079](https://github.com/diegosouzapw/OmniRoute/pull/4079) — thanks @Rahulsharma0810) -- **fix(dev): force webpack in the custom dev server (Turbopack 16.2.x panics)** — the custom dev server now forces the webpack engine because Turbopack panics on this Next.js version, so `npm run dev` boots reliably. ([#4092](https://github.com/diegosouzapw/OmniRoute/pull/4092) — thanks @chirag127) -- **fix(auto): resolve built-in `auto/*` catalog combos** — referencing a built-in `auto/*` combo returned a premature `400` because the catalog entry wasn't resolved; the built-in auto catalog is now resolved before validation so those combos work. ([#4058](https://github.com/diegosouzapw/OmniRoute/pull/4058) — thanks @megamen32) -- **fix(sse): friendly 413 message for ChatGPT-web payload-too-large** — an oversized ChatGPT-web payload returned an opaque error; it now returns a clear `413` with a human-readable message. ([#4080](https://github.com/diegosouzapw/OmniRoute/pull/4080) — thanks @diegosouzapw) -- **fix(ws): warm the SSE auth import on LiveWS startup; relocate the boot test to integration** — the LiveWS sidecar now pre-imports the SSE auth module at startup to avoid a first-request stall, and its boot test was moved to the integration suite. ([#4063](https://github.com/diegosouzapw/OmniRoute/pull/4063) — thanks @diegosouzapw) -- **fix(mitm): crash-safe system-state teardown + socket timeouts (ProxyBridge-inspired hardening)** — the MITM proxy could leave the host's system proxy settings applied if it crashed mid-teardown, and long-lived tunnels could leak as half-open sockets. Teardown is now crash-safe (system state is always restored) and proxied sockets get an idle timeout (`MITM_IDLE_TIMEOUT_MS`, default 60s). ([#4084](https://github.com/diegosouzapw/OmniRoute/pull/4084) — thanks @diegosouzapw) -- **fix(responses): clear the `/v1/responses` keep-alive timer on cancel/abort** — a cancelled or aborted `/v1/responses` stream left its keep-alive timer running, leaking a timer and burning CPU; the timer is now cleared on cancel/abort. ([#4105](https://github.com/diegosouzapw/OmniRoute/pull/4105) — thanks @artickc) -- **fix(usage): reap orphaned pending-request details (unbounded memory leak)** — pending-request detail entries whose request never completed accumulated without bound; they are now reaped, closing a slow memory leak. ([#4107](https://github.com/diegosouzapw/OmniRoute/pull/4107) — thanks @artickc) -- **fix(auth): prune expired entries from the login brute-force guard map (unbounded growth)** — the login brute-force guard map grew without bound because expired entries were never removed; expired entries are now pruned. ([#4111](https://github.com/diegosouzapw/OmniRoute/pull/4111) — thanks @artickc) -- **fix(logger): hard-cap the error-dedup map to bound memory under unique-message bursts** — a burst of unique error messages could grow the dedup map without limit; it is now hard-capped. ([#4113](https://github.com/diegosouzapw/OmniRoute/pull/4113) — thanks @artickc) -- **fix(circuit-breaker): enforce `MAX_REGISTRY_SIZE` (declared but never applied)** — the circuit-breaker registry declared a maximum size that was never enforced, so it could grow unbounded; the cap is now applied. ([#4114](https://github.com/diegosouzapw/OmniRoute/pull/4114) — thanks @artickc) -- **fix(webhook): clear the abort timer in `finally` to avoid dangling timers on fetch error** — a webhook dispatch that threw before clearing its abort timer left the timer dangling; it is now cleared in a `finally` block. ([#4115](https://github.com/diegosouzapw/OmniRoute/pull/4115) — thanks @artickc) -- **fix(combo): detach the per-target listener from the shared hedge abort signal** — combo hedging attached a per-target listener to a shared abort signal without detaching it, leaking listeners across requests; the listener is now detached. ([#4116](https://github.com/diegosouzapw/OmniRoute/pull/4116) — thanks @artickc) -- **fix(timers): unref background interval timers so they don't block clean shutdown** — long-lived background interval timers kept the event loop alive and blocked a clean process exit; they are now `unref`'d. ([#4117](https://github.com/diegosouzapw/OmniRoute/pull/4117) — thanks @artickc) +- **feat(providers): add OrcaRouter (OpenAI-compatible routing gateway)** — OrcaRouter 现已注册为 API-key 服务商。其自适应路由器以 `orcarouter/auto` 暴露（跨 150+ 上游模型的智能路由），以及精选旗舰模型系列（GPT-5.5、Gemini 3.5 Flash、Claude Opus 4.8、Grok 4.3、DeepSeek V4 Pro、MiniMax M2.7、Qwen3.7 Max）。已启用 `passthroughModels`，因此任何 OrcaRouter 模型 ID 均可使用。OpenAI 兼容端点（`https://api.orcarouter.ai/v1`），Bearer（`sk-orca-…`）认证 — 无需自定义 executor 或 translator。([#4070](https://github.com/diegosouzapw/OmniRoute/pull/4070) — 感谢 @jinhaosong-source) +- **feat(providers): add Wafer AI (Anthropic-compatible, Bearer auth)** — Wafer AI 现已成为内置服务商，使用 Anthropic Messages 格式和 Bearer 认证，已注册其模型目录，开箱即用。([#4098](https://github.com/diegosouzapw/OmniRoute/pull/4098) — 感谢 @diegosouzapw) +- **feat(cli): `omniroute launch` — 零配置 Claude Code launcher** — 新的 CLI 子命令，启动 OmniRoute（如果尚未运行）并启动预先配置好的 Claude Code，无需手动编辑 env/settings。([#4097](https://github.com/diegosouzapw/OmniRoute/pull/4097) — 感谢 @diegosouzapw) +- **feat(api): exact offline token counting for the `count_tokens` fallback via tiktoken** — 本地 `count_tokens` 容灾现在使用真正的 tiktoken（BPE）分词器进行精确离线计数，而非启发式估算，因此即使上游计数端点不可达，token 预算也能保持准确。([#4087](https://github.com/diegosouzapw/OmniRoute/pull/4087) — 感谢 @diegosouzapw) +- **feat(sse): Claude Code quota-probe bypass + command meta-request helpers** — 移植自 free-claude-code：OmniRoute 现在能识别 Claude Code 的配额探测和命令元请求，并在本地直接响应，而非消耗上游调用，从而减少 CLI 会话中的配额浪费。([#4083](https://github.com/diegosouzapw/OmniRoute/pull/4083) — 感谢 @diegosouzapw) +- **feat(sse): generic 400 field-downgrade retry + Groq field stripping** — 当上游因不支持的字段而返回 `400` 时，OmniRoute 现在会去除该字段并重试（通用降级路径），同时内置了 Groq 专用字段去除逻辑。与现有的 `context_management` 重试处理对齐。([#4096](https://github.com/diegosouzapw/OmniRoute/pull/4096) — 感谢 @diegosouzapw) +- **feat(sse): delegated Anthropic Context Editing — 中继覆盖率 + 400-容灾** — 扩展了 Claude 服务端 Context Editing 委托功能（#4021），提供更广泛的中继覆盖率和 `400`-容灾，使得上游因 context-management beta 而拒绝的请求能优雅降级而非直接失败。([#4065](https://github.com/diegosouzapw/OmniRoute/pull/4065) — 感谢 @diegosouzapw) +- **feat(compression): record per-engine Context Editing telemetry** — 压缩管线现在记录 `context-editing` 引擎条目，使控制台能将服务端 Context Editing 的节省量与本地压缩引擎一并归因显示。([#4062](https://github.com/diegosouzapw/OmniRoute/pull/4062) — 感谢 @diegosouzapw) +- **feat(compression): RTK learn/discover (sample source + API + UI)** — 基于规则的 RTK 压缩引擎新增 learn/discover 工作流：对源进行采样，通过新 API 展示候选规则，并在控制台中审查/应用它们。([#4088](https://github.com/diegosouzapw/OmniRoute/pull/4088) — 感谢 @diegosouzapw) +- **feat(dashboard): 2026-06-17 free-tier refresh — honest catalog, uncapped + boost tiers, Layout A 预算表** — 免费套餐页面已刷新，包含真实、深度调研的目录（共享池/实际数据而非夸大的 24/7 RPM 估算），新增 `recurring-uncapped` 和 boost 套餐层级、新服务商，以及 KPI + 预算表（Layout A）。([#4089](https://github.com/diegosouzapw/OmniRoute/pull/4089) — 感谢 @diegosouzapw) +- **feat(dashboard): Combo Studio connection-cooldown badge (U1b Slice 2)** — Combo Live 级联视图现在展示每个连接的冷却状态徽章，与 3.8.27 中发布的熔断器徽章互为补充。([#4068](https://github.com/diegosouzapw/OmniRoute/pull/4068) — 感谢 @diegosouzapw) +- **feat(mitm): attribute intercepted requests to the originating process (Gap 1)** — 流量检查器现在能将每个被拦截的连接追溯到原始本地进程（通过 `/proc`），使得捕获的流量可以归因到产生它的应用。（ProxyBridge 风格强化。）([#4085](https://github.com/diegosouzapw/OmniRoute/pull/4085) — 感谢 @diegosouzapw) +- **feat(mitm): capture-pipeline self-test route (Gap 12)** — 新增诊断路由，端到端地演练 MITM 捕获管线，使运维人员无需构造真实上游调用即可确认拦截功能正常。([#4093](https://github.com/diegosouzapw/OmniRoute/pull/4093) — 感谢 @diegosouzapw) +- **feat(mitm): loop-guard self-check + verbosity control in `server.cjs` (Gaps 14+15)** — MITM 代理新增自引用循环防护（确保不会将自身流量代理到无限循环中），以及 `MITM_VERBOSE` 路由决策日志级别控制。([#4101](https://github.com/diegosouzapw/OmniRoute/pull/4101) — 感谢 @diegosouzapw) +- **feat(agent-bridge): portable JSON import/export of config (Gap 4)** — Agent Bridge / MITM 配置现可导出并从便携 JSON 文件导入，方便备份工作设置或在机器间迁移。([#4094](https://github.com/diegosouzapw/OmniRoute/pull/4094) — 感谢 @diegosouzapw) + +### 🐛 问题修复 + +- **fix(ws): start the LiveWS sidecar with `cwd` at the package root (global/systemd installs)** — 独立 LiveWS 启动器（`scripts/start-ws-server.mjs`）通过 `node --import tsx ` 重新启动自身，但未设置 `cwd`。当 WebSocket sidecar 从包目录外部启动时 — 例如全局 npm/homebrew 安装，或 `systemd`/`launchd` 单元从 `$HOME` 启动 — Node 无法解析 `tsx` 包（`ERR_MODULE_NOT_FOUND: Cannot find package 'tsx'`），即便在包目录下 `tsx` 也无法解析 tsconfig 的 `@/*` 路径别名（如 `@/types/databaseSettings`），导致 sidecar 无法启动。spawn 现在将 `cwd` 固定为包根目录（`scripts/` 的上级目录，`package.json` + `tsconfig.json` 所在位置），从而无论从何处启动，都能解析 `tsx` 和 `@/*` 别名。([#4055](https://github.com/diegosouzapw/OmniRoute/issues/4055) — 感谢 @Rahulsharma0810) +- **fix(dashboard): Logs page auto-refresh now works in embedded/proxied dashboards** — 请求日志器曾将每次自动刷新 tick 依赖于静态的 `document.visibilityState === "visible"` 读取。那些报告永久非 `"visible"` 状态且从不触发 `visibilitychange` 事件的环境（Docker 控制台包装器、嵌入式 webview）会导致自动刷新完全冻结 — 只有手动刷新按钮有效，这是 3.8.24 无条件轮询的回归。暂停现在采用事件驱动和 fail-open 模式：轮询以启用状态启动，仅在真实的 `visibilitychange` → hidden 转换后才暂停（仍然保留对普通浏览器标签页的后台优化）。([#4054](https://github.com/diegosouzapw/OmniRoute/issues/4054) — 感谢 @tjengbudi) +- **fix(docker): raise the build-stage Node heap to stop the production-build OOM** — Docker `builder` 阶段运行 `npm run build` 时使用 V8 的默认堆上限（~2 GB）。自 #4052 强制使用更重的 webpack 引擎后（Turbopack 在此 Next.js 版本上会 panic），生产优化阶段超过了该上限，构建在 `[builder] npm run build` 处以 `FATAL ERROR: … JavaScript heap out of memory` 失败。builder 阶段现在在构建前设置 `NODE_OPTIONS=--max-old-space-size`（默认 4096 MB，可通过 `--build-arg OMNIROUTE_BUILD_MEMORY_MB=…` 覆盖）；该值会传递到启动的 `next build`。仅影响构建 — 运行时堆（runner 阶段的 `OMNIROUTE_MEMORY_MB`）保持不变。([#4076](https://github.com/diegosouzapw/OmniRoute/issues/4076) — 感谢 @kamenkadmitry) +- **fix(dashboard): "Update Available" banner reappears reliably across Docker/npm/desktop installs** — 首页 banner 依赖于 `GET /api/system/version` 的 `updateAvailable`，该值仅通过 `npm` CLI 二进制文件执行 `npm info omniroute version --json` 来获取最新版本。当该二进制文件在运行时 PATH 中不存在（Docker/desktop/受限安装）或注册表不可达时，调用返回 `null` → `updateAvailable=false` → banner 静默地从不显示，即便已有更新的版本。路由现在通过 `resolveLatestVersion()` 解析最新版本：优先走快速的 `npm` CLI 路径，然后通过注册表 HTTP API（`registry.npmjs.org/omniroute/latest`）进行无 npm 二进制的容灾，两者都失败时记录警告而非静默降级。版本比较也经过强化，能容忍 `v` 前缀和预发布版本字符串。([#4100](https://github.com/diegosouzapw/OmniRoute/issues/4100)) +- **fix(sse): route image requests only to confirmed-vision combo targets** — Combo 可能会将包含图像的请求路由到不支持视觉功能的成员。路由现在要求 `supportsVision === true`（加上模型 ID 启发式检查）后才向目标发送图像，确保多模态请求只落在能处理它们的成员上。([#4071](https://github.com/diegosouzapw/OmniRoute/pull/4071) — 感谢 @diego-anselmo) +- **fix(security): injection guard respects the `INJECTION_GUARD_MODE` DB feature flag** — 提示注入防护曾忽略数据库功能标志，导致运维人员无法在运行时更改其模式；现在它会读取该标志并遵循配置的模式。([#4077](https://github.com/diegosouzapw/OmniRoute/pull/4077) — 感谢 @zhiru) +- **fix(ws): proxy LAN `/live-ws` upgrades and warn on an unset `JWT_SECRET`** — 通过 LAN 代理路径到达的 WebSocket 升级请求未被转发到 LiveWS sidecar；现在已正确代理，且服务器在 `JWT_SECRET` 未设置时会记录明确的警告。([#4079](https://github.com/diegosouzapw/OmniRoute/pull/4079) — 感谢 @Rahulsharma0810) +- **fix(dev): force webpack in the custom dev server (Turbopack 16.2.x panics)** — 自定义 dev server 现在强制使用 webpack 引擎，因为 Turbopack 在此 Next.js 版本上会 panic，从而确保 `npm run dev` 可靠启动。([#4092](https://github.com/diegosouzapw/OmniRoute/pull/4092) — 感谢 @chirag127) +- **fix(auto): resolve built-in `auto/*` catalog combos** — 引用内置 `auto/*` Combo 时返回过早的 `400`，因为目录条目未被解析；内置 auto 目录现在在验证前完成解析，使这些 combo 正常工作。([#4058](https://github.com/diegosouzapw/OmniRoute/pull/4058) — 感谢 @megamen32) +- **fix(sse): friendly 413 message for ChatGPT-web payload-too-large** — 过大的 ChatGPT-web 载荷曾返回模糊的错误；现在返回清晰的 `413` 和人类可读的消息。([#4080](https://github.com/diegosouzapw/OmniRoute/pull/4080) — 感谢 @diegosouzapw) +- **fix(ws): warm the SSE auth import on LiveWS startup; relocate the boot test to integration** — the LiveWS sidecar now pre-imports the SSE 认证 module at startup to avoid a first-请求 stall, and its boot test was moved to the 集成 suite. ([#4063](https://github.com/diegosouzapw/OmniRoute/pull/4063) — 感谢 @diegosouzapw) +- **fix(mitm): crash-safe system-state teardown + socket timeouts (ProxyBridge-inspired hardening)** — the MITM 代理 could leave the host's system 代理 settings applied if it crashed mid-teardown, and long-lived tunnels could leak as half-open sockets. Teardown 现在 crash-safe (system state is always restored) and proxied sockets get an idle timeout (`MITM_IDLE_TIMEOUT_MS`, 默认 60s). ([#4084](https://github.com/diegosouzapw/OmniRoute/pull/4084) — 感谢 @diegosouzapw) +- **fix(responses): clear the `/v1/responses` keep-alive timer on cancel/abort** — 被取消或中止的 `/v1/responses` 流曾遗留 keep-alive 定时器运行，导致定时器泄漏和 CPU 浪费；定时器现在在 cancel/abort 时被清除。([#4105](https://github.com/diegosouzapw/OmniRoute/pull/4105) — 感谢 @artickc) +- **fix(usage): reap orphaned pending-request details (unbounded memory leak)** — 请求永不完成的待处理请求详情条目无限累积；现在它们被回收，修复了缓慢的内存泄漏。([#4107](https://github.com/diegosouzapw/OmniRoute/pull/4107) — 感谢 @artickc) +- **fix(auth): prune expired entries from the login brute-force guard map (unbounded growth)** — 登录暴力破解防护映射因过期条目从未被移除而无限制增长；过期条目现在被清理。([#4111](https://github.com/diegosouzapw/OmniRoute/pull/4111) — 感谢 @artickc) +- **fix(logger): hard-cap the error-dedup map to bound memory under unique-message bursts** — 唯一错误消息的突发可能导致去重映射无限制增长；现在已硬性限制上限。([#4113](https://github.com/diegosouzapw/OmniRoute/pull/4113) — 感谢 @artickc) +- **fix(circuit-breaker): enforce `MAX_REGISTRY_SIZE` (declared but never applied)** — 熔断器注册表声明了最大大小但从未强制执行，可能导致无限制增长；上限现在已生效。([#4114](https://github.com/diegosouzapw/OmniRoute/pull/4114) — 感谢 @artickc) +- **fix(webhook): clear the abort timer in `finally` to avoid dangling timers on fetch error** — webhook 分发在清除 abort 定时器之前抛出异常时，定时器会悬空；现在在 `finally` 块中清除。([#4115](https://github.com/diegosouzapw/OmniRoute/pull/4115) — 感谢 @artickc) +- **fix(combo): detach the per-target listener from the shared hedge abort signal** — Combo hedging 将每个目标的监听器附加到共享的 abort 信号上但未分离，导致跨请求的监听器泄漏；监听器现在被分离。([#4116](https://github.com/diegosouzapw/OmniRoute/pull/4116) — 感谢 @artickc) +- **fix(timers): unref background interval timers so they don't block clean shutdown** — 长时间运行的后台间隔定时器保持事件循环活跃，阻止了干净的进程退出；它们现在被 `unref` 了。([#4117](https://github.com/diegosouzapw/OmniRoute/pull/4117) — 感谢 @artickc) ### ⚡ 性能优化 -- **perf(registry): precompute the model→provider index in `parseModelFromRegistry`** — model→provider lookups now use a precomputed index instead of scanning the registry on every call. ([#4110](https://github.com/diegosouzapw/OmniRoute/pull/4110) — thanks @artickc) -- **perf(obfuscation): cache per-word regexes instead of recompiling every request** — the obfuscation pass now caches its per-word regexes rather than recompiling them on each request. ([#4109](https://github.com/diegosouzapw/OmniRoute/pull/4109) — thanks @artickc) -- **perf(stream): use `structuredClone` instead of a JSON round-trip for per-chunk reasoning split** — the per-chunk reasoning split now clones with `structuredClone` rather than `JSON.parse(JSON.stringify(...))`. ([#4108](https://github.com/diegosouzapw/OmniRoute/pull/4108) — thanks @artickc) -- **perf(gemini): cache the reasoning close-tag regex instead of recompiling per token** — the Gemini reasoning close-tag regex is now compiled once and reused instead of per token. ([#4106](https://github.com/diegosouzapw/OmniRoute/pull/4106) — thanks @artickc) +- **perf(registry): precompute the model→provider index in `parseModelFromRegistry`** — 模型→服务商查找现在使用预计算索引，而非每次调用时扫描注册表。([#4110](https://github.com/diegosouzapw/OmniRoute/pull/4110) — 感谢 @artickc) +- **perf(obfuscation): cache per-word regexes instead of recompiling every request** — 混淆阶段现在缓存每个单词的正则表达式，而非每次请求时重新编译。([#4109](https://github.com/diegosouzapw/OmniRoute/pull/4109) — 感谢 @artickc) +- **perf(stream): use `structuredClone` instead of JSON round-trip for per-chunk reasoning split** — 每个 chunk 的推理分割现在使用 `structuredClone` 而非 `JSON.parse(JSON.stringify(...))`。([#4108](https://github.com/diegosouzapw/OmniRoute/pull/4108) — 感谢 @artickc) +- **perf(gemini): cache the reasoning close-tag regex instead of recompiling per token** — Gemini 推理关闭标签的正则表达式现在只编译一次并复用，而非每个 token 都重新编译。([#4106](https://github.com/diegosouzapw/OmniRoute/pull/4106) — 感谢 @artickc) ### 📝 维护 -- **ci(quality): flip the TIA impacted-unit-tests gate from advisory to blocking (Fase 9)** — the test-impact-analysis gate that runs the unit tests impacted by a diff is now blocking on PRs. ([#4069](https://github.com/diegosouzapw/OmniRoute/pull/4069) — thanks @diegosouzapw) -- **ci(quality): dedup the doubly-run `check:docs-sync` + record the validated ROI backlog (Fase 9)** — `check:docs-sync` was running twice in CI; the duplicate was removed and the validated quality-gate ROI backlog recorded. ([#4099](https://github.com/diegosouzapw/OmniRoute/pull/4099) — thanks @diegosouzapw) -- **docs(quality-gates): reconcile the gate inventory with `ci.yml` + add the ROI rationalization backlog** — the quality-gate inventory doc was reconciled against the actual CI jobs and a rationalization backlog added. ([#4095](https://github.com/diegosouzapw/OmniRoute/pull/4095) — thanks @diegosouzapw) -- **test(infra): isolate `DATA_DIR` per test process; raise Stryker concurrency 1→4** — test processes now get an isolated `DATA_DIR` (no shared-DB cross-talk) and the mutation runner's concurrency was raised. ([#4078](https://github.com/diegosouzapw/OmniRoute/pull/4078) — thanks @diegosouzapw) -- **test(dashboard): smoke e2e for the Combo Live Studio page** — adds a Playwright smoke test covering the Combo Live Studio page. ([#4075](https://github.com/diegosouzapw/OmniRoute/pull/4075) — thanks @diegosouzapw) -- **docs(compression): document LLMLingua optional deps + on-demand install** — documents the optional LLMLingua dependencies and how they are installed on demand. ([#4061](https://github.com/diegosouzapw/OmniRoute/pull/4061) — thanks @diegosouzapw) -- **chore(deps): freeze `@huggingface/transformers` in dependabot (hard-pin)** — the transformers dependency is hard-pinned and frozen in dependabot to protect the VPS-validated LLMLingua + memory-embeddings stack from a breaking major bump. ([#4066](https://github.com/diegosouzapw/OmniRoute/pull/4066) — thanks @diegosouzapw) -- **chore(docs): update the Discord invite link to a non-expiring one** — replaces the expiring Discord invite with a permanent link. ([#4067](https://github.com/diegosouzapw/OmniRoute/pull/4067) — thanks @diegosouzapw) -- **chore(docs): document the new MITM env vars + reconcile the env-doc contract** — documents `MITM_IDLE_TIMEOUT_MS` and `MITM_VERBOSE` in `.env.example` + `ENVIRONMENT.md`, allowlists the framework-internal `TURBOPACK` and the Claude Code `ANTHROPIC_AUTH_TOKEN`, and relocates/prunes stale provider/guide docs. (thanks @diegosouzapw) +- **ci(quality): flip the TIA impacted-unit-tests gate from advisory to blocking (Fase 9)** — the test-impact-analysis gate that runs the unit tests impacted by a diff 现在 blocking on PRs. ([#4069](https://github.com/diegosouzapw/OmniRoute/pull/4069) — 感谢 @diegosouzapw) +- **ci(quality): dedup the doubly-run `check:docs-sync` + record the validated ROI backlog (Fase 9)** — `check:docs-sync` was running twice in CI; the duplicate was removed and the validated quality-gate ROI backlog recorded. ([#4099](https://github.com/diegosouzapw/OmniRoute/pull/4099) — 感谢 @diegosouzapw) +- **docs(quality-gates): reconcile the gate inventory with `ci.yml` + add the ROI rationalization backlog** — the quality-gate inventory doc was reconciled against the actual CI jobs and a rationalization backlog added. ([#4095](https://github.com/diegosouzapw/OmniRoute/pull/4095) — 感谢 @diegosouzapw) +- **test(infra): isolate `DATA_DIR` per test process; raise Stryker concurrency 1→4** — test processes now get an isolated `DATA_DIR` (no shared-DB cross-talk) and the mutation runner's concurrency was raised. ([#4078](https://github.com/diegosouzapw/OmniRoute/pull/4078) — 感谢 @diegosouzapw) +- **test(dashboard): smoke e2e for the Combo Live Studio page** — adds a Playwright smoke test covering the Combo Live Studio 页面. ([#4075](https://github.com/diegosouzapw/OmniRoute/pull/4075) — 感谢 @diegosouzapw) +- **docs(compression): document LLMLingua optional deps + on-demand install** — documents the optional LLMLingua dependencies and how they are installed on demand. ([#4061](https://github.com/diegosouzapw/OmniRoute/pull/4061) — 感谢 @diegosouzapw) +- **chore(deps): freeze `@huggingface/transformers` in dependabot (hard-pin)** — the transformers dependency is hard-pinned and frozen in dependabot to protect the VPS-validated LLMLingua + memory-embeddings stack from a breaking major bump. ([#4066](https://github.com/diegosouzapw/OmniRoute/pull/4066) — 感谢 @diegosouzapw) +- **chore(docs): update the Discord invite link to a non-expiring one** — replaces the expiring Discord invite with a permanent link. ([#4067](https://github.com/diegosouzapw/OmniRoute/pull/4067) — 感谢 @diegosouzapw) +- **chore(docs): document the new MITM env vars + reconcile the env-doc contract** — documents `MITM_IDLE_TIMEOUT_MS` and `MITM_VERBOSE` in `.env.example` + `ENVIRONMENT.md`, allowlists the framework-internal `TURBOPACK` and the Claude Code `ANTHROPIC_AUTH_TOKEN`, and relocates/prunes stale 服务商/guide docs. (thanks @diegosouzapw) ### 🔧 依赖 @@ -1056,65 +1056,65 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(combos): advertise combo capabilities (multimodal / reasoning / caching) on the import surfaces** — importing a combo package into a client (LobeHub / OpenCode / VS Code, via `/v1/combos` and the VS Code combo catalog) no longer requires manually enabling multimodal/image-input, reasoning, and caching afterwards. `projectCombo` now attaches a registry-derived `capabilities` block, gated conservatively: `multimodal`/`reasoning` are advertised only when **every** concrete model step proves the capability (an unprovable nested combo-ref drops them, since the strategy may route to any member), and `caching` reflects the combo's explicit Context-Cache-Protection setting (no surprise prompt-cache cost). The public `/v1/combos` default projection (#2300) is unchanged unless the caller opts in. ([#3979](https://github.com/diegosouzapw/OmniRoute/issues/3979) — thanks @xenstar) -- **feat(sse): delegated Anthropic Context Editing for Claude (`clear_tool_uses`)** — Claude requests can now offload context trimming to Anthropic's server-side context-management API (beta `context-management-2025-06-27`, `clear_tool_uses_20250919`), pruning stale tool-use turns upstream instead of locally. Claude-only by nature (the edit runs server-side); multi-provider context trimming remains the job of the local compression engines. ([#4021](https://github.com/diegosouzapw/OmniRoute/pull/4021) — thanks @diegosouzapw) -- **feat(sse): real LLMLingua-2 ONNX compression engine (stable)** — the LLMLingua-2 prompt-compression engine is now a real local ONNX model (TinyBERT default, transformers.js + tfjs), promoted to stable after VPS validation, replacing the previous placeholder. ([#4014](https://github.com/diegosouzapw/OmniRoute/pull/4014) — thanks @diegosouzapw) -- **feat(compression): capture per-engine analytics + Lite schema fix** — the compression pipeline now persists a per-engine breakdown for historical analytics so the dashboard can attribute savings to each engine in a stacked pipeline, and a Lite-schema mismatch was corrected. ([#4018](https://github.com/diegosouzapw/OmniRoute/pull/4018) — thanks @diegosouzapw) -- **feat(dashboard): real circuit-breaker state in the Combo Live cascade (U1b)** — the Combo Live cascade view now surfaces each provider's real circuit-breaker state (CLOSED / OPEN / HALF_OPEN) as a badge, read live from `/api/monitoring/health`, instead of inferring health from request outcomes. ([#4029](https://github.com/diegosouzapw/OmniRoute/pull/4029) — thanks @diegosouzapw) -- **feat(openai): honor a custom base URL in model discovery + complete openai/codex pricing** — OpenAI-format providers configured with a custom base URL now have that URL honored during model discovery (not just inference), and the openai/codex pricing table was completed. Discovery is routed through the SSRF-guarded outbound fetch. ([#4005](https://github.com/diegosouzapw/OmniRoute/pull/4005) — thanks @artickc) -- **feat(observability): capture actual upstream provider requests** — the request inspector now records the exact payload sent to the upstream provider (post-translation), so you can see what OmniRoute actually dispatched rather than only the client's original request. ([#3941](https://github.com/diegosouzapw/OmniRoute/pull/3941) — thanks @rdself) -- **feat(providers): provider auth visibility controls** — adds controls to show/hide provider auth details in the dashboard so credentials can be revealed only when needed. ([#3953](https://github.com/diegosouzapw/OmniRoute/pull/3953) — thanks @rdself) -- **feat(providers): model search filter on the provider dashboard** — the provider dashboard gains a search filter to quickly narrow a provider's model list. ([#3950](https://github.com/diegosouzapw/OmniRoute/pull/3950) — thanks @felipesartori) -- **feat(compression): Indonesian caveman rules + language pack** — adds an Indonesian "caveman" rule set and language pack to the rule-based compression engine. ([#3975](https://github.com/diegosouzapw/OmniRoute/pull/3975) — thanks @Veier04) -- **feat(dashboard): sidebar group separator toggles** — the dashboard sidebar can now toggle group separators for a cleaner navigation layout. ([#3971](https://github.com/diegosouzapw/OmniRoute/pull/3971) — thanks @rdself) -- **feat(api): local `@@om-usage` command for cached per-key usage** — API clients can send a message that is exactly `@@om-usage` to retrieve cached Claude-style usage data locally, without forwarding the prompt to an upstream provider. Gated by a new per-key allowance flag. ([#4034](https://github.com/diegosouzapw/OmniRoute/pull/4034) — thanks @Witroch4) - -### 🐛 Fixed - -- **fix(opencode): forward the OpenCode session id to the upstream regardless of how the user named the provider** — the `OpencodeExecutor` forwarded the `x-opencode-session/request/project/client` headers, but the OpenCode CLI only emits those when the configured `providerID` **starts with** `"opencode"`. A user who adds OmniRoute as a custom provider (e.g. `"omniroute"`) makes the CLI send `x-session-affinity` / `X-Session-Id` instead (both carry the same session id), which the executor never read — so the session-metadata forwarding was effectively dead code for the realistic provider-naming case. The opencode-family executor now falls back to `x-session-affinity` / `X-Session-Id` and maps it onto `x-opencode-session` when the client didn't send the header directly, so session continuity to the `opencode.ai` upstream works for any provider name (a direct `x-opencode-session` still wins). Scoped to this executor only — the generic `DefaultExecutor` intentionally does **not** do this, to avoid leaking the client session id to arbitrary third-party upstreams. ([#4022](https://github.com/diegosouzapw/OmniRoute/issues/4022) — thanks @pizzav-xyz) -- **fix(guardrails): Vision Bridge no longer drops the image when the describe call fails (Nvidia NIM "Image unavailable")** — the Vision Bridge is enabled by default and engages for any model whose vision capability OmniRoute can't prove from the registry (`supportsVision !== true`, which includes uncatalogued models that resolve to `null`). When the per-image describe call failed (e.g. no vision model configured), it replaced the image with the literal text `[Image N]: (unavailable)` and dropped the original `image_url` — so a genuinely vision-capable upstream (Nvidia NIM) received text only and answered "Image unavailable. Cannot provide description without visual data." A describe failure is no longer destructive: `replaceImageParts` now receives `null` for failed images and **preserves the original image part** so the upstream can still see it (successful describes still replace the image with the text description; `meta.descriptions` observability is unchanged). ([#4012](https://github.com/diegosouzapw/OmniRoute/issues/4012) — thanks @daniij) -- **fix(kiro): preserve `finish_reason: "tool_calls"` on the Kiro streaming path** — streaming tool-call requests through the Kiro (Responses API) provider had their terminal `finish_reason` reported as `"stop"` instead of `"tool_calls"`, so agent clients (Hermes) treated the tool-call turn as a finished turn, never ran the tool, and the next request failed with HTTP 400 on the incomplete tool state. `convertKiroToOpenAI`'s terminal `messageStopEvent`/`done` branch hardcoded `finish_reason: "stop"` regardless of whether the stream had emitted `toolUseEvent`s. The translator now records `state.sawToolUse` when a tool-use chunk is emitted and reports `finish_reason: "tool_calls"` on the terminal chunk (and in `state.finishReason`) whenever the stream produced tool calls. The non-streaming path was already correct. ([#3980](https://github.com/diegosouzapw/OmniRoute/issues/3980) — thanks @lordavadon2) -- **fix(resilience): respect connection cooldown stored as a numeric epoch** — the router kept dispatching to connections still inside their rate-limit cooldown because `rate_limited_until` (a `TEXT` column) was persisted as a raw epoch number, which SQLite coerced to a string like `"1781696905131.0"` that `new Date(...)` parsed as `NaN`, so the cooling connection was never skipped. The cooldown read predicates now normalize numeric-epoch strings via a shared `cooldownUntilMs()` helper; ISO behavior is unchanged. ([#3995](https://github.com/diegosouzapw/OmniRoute/pull/3995) — thanks @diegosouzapw) -- **fix(providers): fetch the live `/models` catalog for LLM7 and BytePlus** — importing an LLM7 or BytePlus key surfaced only a small, outdated hardcoded list because neither provider was classified by any live-fetch branch of the model-import route. Both are now in `NAMED_OPENAI_STYLE_PROVIDERS`, so the route probes `/models` with the key and serves the live catalog, falling back to the local catalog only when the upstream fetch fails. ([#3996](https://github.com/diegosouzapw/OmniRoute/pull/3996) — thanks @FerLuisxd / @diegosouzapw) -- **fix(dashboard): logs auto-refresh reads live visibility, not a stale mount ref** — the Logs page never auto-refreshed when the tab loaded in the background because the auto-refresh interval gated each tick on a visibility ref seeded once at mount; the tick now reads the live `document.visibilityState`, so polling self-heals as soon as the tab is visible while still pausing when genuinely hidden. ([#3997](https://github.com/diegosouzapw/OmniRoute/pull/3997) — thanks @tjengbudi / @diegosouzapw) -- **fix(combo): shuffle the strict-random fallback remainder to spread load** — with the `strict-random` strategy a persistently-failing model was retried on essentially every request because only the deck-selected slot 0 was shuffled while the fallback remainder stayed in fixed priority order; the remainder is now shuffled too, so fallback load (and recovery from a failing target) spreads evenly across healthy peers. ([#3998](https://github.com/diegosouzapw/OmniRoute/pull/3998) — thanks @KeNJiKunG / @diegosouzapw) -- **fix(claude): forward the client `tool-search-tool-2025-10-19` anthropic-beta on the Claude OAuth path** — with deferred tools active, Claude Code negotiates the `tool-search-tool-2025-10-19` beta, but OmniRoute dropped it on both Claude code paths, so the claude.ai backend rejected every deferred-tool request with `400 Tool reference not found`. A new allowlist-merge (`mergeClientAnthropicBeta`) now unions the client's negotiated beta into the outbound set on both paths, appending only allowlisted client betas (preserving the #3415 fix). ([#3999](https://github.com/diegosouzapw/OmniRoute/pull/3999) — thanks @huohua-dev / @diegosouzapw) -- **fix(executor): strip `stream_options` on non-streaming requests (NVIDIA NIM 400)** — clients that send `stream_options: { include_usage: true }` regardless of `stream` (e.g. the OpenAI Python SDK) had it passed through untouched on non-streaming calls, and NVIDIA NIM rejected it with `400 "Stream options can only be defined when stream=True"`. `DefaultExecutor.transformRequest` now strips `stream_options` whenever `stream` is false; the streaming injection path is unchanged. ([#4000](https://github.com/diegosouzapw/OmniRoute/pull/4000) — thanks @andrea-kingautomation / @daniij / @diegosouzapw) -- **fix(sse): guard model-less registry entries in `getUnsupportedParams` (mimocode)** — a registry entry without a model map (mimocode) threw when computing unsupported params; the lookup now guards the model-less case so request validation no longer crashes. ([#4015](https://github.com/diegosouzapw/OmniRoute/pull/4015) — thanks @diegosouzapw) -- **fix(perplexity-web): parse the schematized `diff_block` stream so answers aren't empty** — Perplexity web streamed its answer as RFC-6902 `diff_block` patches that OmniRoute didn't apply during the `PENDING` phase, so responses came back empty; the parser now applies the patches and materializes the text only on `COMPLETED`. ([#4001](https://github.com/diegosouzapw/OmniRoute/pull/4001) — thanks @artickc) -- **fix(default-executor): honor a custom `providerSpecificData.baseUrl` for OpenAI-format providers** — OpenAI-format providers configured with a custom base URL had it ignored on the inference path; the default executor now honors `providerSpecificData.baseUrl` so requests reach the configured endpoint. ([#4002](https://github.com/diegosouzapw/OmniRoute/pull/4002) — thanks @artickc) -- **fix(live-ws): bridge LiveWS sidecar events to the dashboard** — events emitted by the LiveWS sidecar were not reaching the dashboard; they are now bridged so live websocket activity is visible. (A cookie-auth regression in the sidecar's auth-token parsing was also corrected.) ([#4004](https://github.com/diegosouzapw/OmniRoute/pull/4004) — thanks @megamen32) -- **fix(qwen-web): cookie validation false-positive — check the response body for a user object** — Qwen web cookie validation reported a valid cookie as invalid; it now inspects the response body for the `user` object instead of relying on the status code alone. ([#3958](https://github.com/diegosouzapw/OmniRoute/pull/3958) — thanks @thezukiru) -- **fix(vision-bridge): force the bridge for tokenrouter deepseek models** — tokenrouter DeepSeek models are now forced through the Vision Bridge so image inputs are handled correctly. ([#3946](https://github.com/diegosouzapw/OmniRoute/pull/3946) — thanks @WormAlien) -- **fix(api): return 400 (not 500) for malformed JSON on `/api/auth/login`** — a malformed JSON body on the login endpoint returned an opaque 500; it now returns a proper 400. ([#4031](https://github.com/diegosouzapw/OmniRoute/pull/4031) — thanks @rdself) -- **fix(dashboard): Playground Compare tab loading + HTTP method guard** — the Playground Compare tab failed to load; the loading path was fixed and an HTTP method guard added. ([#4024](https://github.com/diegosouzapw/OmniRoute/pull/4024) — thanks @rdself) -- **fix(proxy): gate the control-plane proxy direct fallback behind a feature flag (fail-closed)** — the direct-connection fallback for control-plane ops when a pinned proxy is unreachable is now gated behind a feature flag and fails closed, so a pinned proxy is never silently bypassed unless explicitly allowed. ([#3963](https://github.com/diegosouzapw/OmniRoute/pull/3963) — thanks @rdself) -- **fix(db): persist backup retention days** — the backup retention-days setting was not persisted across restarts; it is now stored durably. ([#3970](https://github.com/diegosouzapw/OmniRoute/pull/3970) — thanks @rdself) -- **fix(dashboard): refine the provider quota card display** — the provider quota card layout was refined for clearer quota/usage presentation. ([#3969](https://github.com/diegosouzapw/OmniRoute/pull/3969) — thanks @rdself) -- **fix(dashboard): refine compression settings, storage labels, and sidebar grouping** — polishes the compression-settings UI, clarifies storage labels, and tidies the sidebar grouping. ([#4033](https://github.com/diegosouzapw/OmniRoute/pull/4033) — thanks @rdself) - -### 🔒 安全 & Hardening - -- **fix(security): eliminate a polynomial ReDoS in the combo `` tag regex** — `comboAgentMiddleware`'s cache-tag pattern wrapped the tag in an unbounded newline run (`(?:\n|\r)*`), making `.test()` / `.replace()` run in O(n²) on inputs with many newlines (CodeQL `js/polynomial-redos`). The detection pattern now matches only the core `…` and the global strip pattern bounds the surrounding newline runs, keeping it linear; detection / extraction / multi-tag stripping behavior is unchanged. ([#3982](https://github.com/diegosouzapw/OmniRoute/pull/3982) — thanks @diegosouzapw) -- **ci(security): harden workflows — artipacked `persist-credentials`, cache-poisoning, SC2086** — GitHub Actions workflows were hardened against the artipacked `persist-credentials` leak and cache-poisoning, and shell-quoting (`SC2086`) issues were fixed. ([#3965](https://github.com/diegosouzapw/OmniRoute/pull/3965) — thanks @diegosouzapw) -- **ci(quality): flip require-tighten + osv + Trivy to blocking (cycle-end)** — the per-module require-tighten check and the OSV / Trivy scanners moved from advisory to blocking for the v3.8.27 cycle close, so new dependency or coverage regressions fail CI. ([#3984](https://github.com/diegosouzapw/OmniRoute/pull/3984) — thanks @diegosouzapw) -- **chore(deps): dependabot security bumps + drop unused gray-matter** — applies a batch of Dependabot security bumps and removes the unused `gray-matter` dependency from the tree. ([#4036](https://github.com/diegosouzapw/OmniRoute/pull/4036) — thanks @diegosouzapw) -- **chore(deps): automated dependency bumps** — Dependabot upgraded the production dependency group (13 updates), `vite`, `form-data`, and the `npm_and_yarn` group. ([#3915](https://github.com/diegosouzapw/OmniRoute/pull/3915), [#3942](https://github.com/diegosouzapw/OmniRoute/pull/3942), [#3943](https://github.com/diegosouzapw/OmniRoute/pull/3943), [#3944](https://github.com/diegosouzapw/OmniRoute/pull/3944) — thanks @dependabot) - -### 🧹 Internal / Quality / Docs - -- **feat(ci): Quality Gate v2 — Onda 0 + Onda 1** — first two waves of the Quality Gate v2 program: gate flips, test-impact analysis (TIA), SAST, DAST-smoke, and mutation-testing infrastructure. ([#4016](https://github.com/diegosouzapw/OmniRoute/pull/4016) — thanks @diegosouzapw) -- **refactor: modularize the provider registry into individual provider plugins** — `providerRegistry.ts` was split into individual per-provider plugin modules (non-stacked). A forward-fix restored the `byteplus` + `mimocode` modules dropped by the move. ([#3993](https://github.com/diegosouzapw/OmniRoute/pull/3993) — thanks @oyi77 / @diegosouzapw) -- **refactor: modularize schemas (non-stacked)** — the request/response schema definitions were split into individual modules to reduce file size and improve maintainability. ([#3988](https://github.com/diegosouzapw/OmniRoute/pull/3988) — thanks @oyi77) -- **fix: restore unit regressions dropped by the lossy schema/registry modularizations** — the schema/registry modularizations (#3988, #3993) silently dropped internal logic covered by unit tests; this PR restores the regressed units. ([#4030](https://github.com/diegosouzapw/OmniRoute/pull/4030) — thanks @diegosouzapw) -- **refactor(dashboard): settings UI layout + API Keys naming** — the settings UI layout was reorganized and the "API Keys" naming clarified. ([#4020](https://github.com/diegosouzapw/OmniRoute/pull/4020) — thanks @rdself) -- **大量UI显示和i18n优化 (dashboard UI display + i18n improvements)** — a batch of dashboard UI-display refinements and i18n string improvements. ([#3973](https://github.com/diegosouzapw/OmniRoute/pull/3973) — thanks @rdself) -- **fix(ci): scope TIA to `node:test` unit files only** — test-impact analysis was matching files the `node:test` runner doesn't execute, producing 99 false failures; the TIA glob now mirrors the `test:unit` glob exactly. ([#4035](https://github.com/diegosouzapw/OmniRoute/pull/4035) — thanks @diegosouzapw) -- **fix(ci): electron-release publish-npm needs `contents: write`** — the reusable npm-publish job invoked by the electron release lacked `contents: write`, causing a v3.8.26 `startup_failure`; the permission was granted. ([#3966](https://github.com/diegosouzapw/OmniRoute/pull/3966) — thanks @diegosouzapw) -- **test(opencode-plugin): ESM default-export test (drop the stale CJS bundle test)** — replaces the stale CJS bundle test with an ESM default-export test, following up the #3883 ESM-only migration. ([#3967](https://github.com/diegosouzapw/OmniRoute/pull/3967) — thanks @diegosouzapw) -- **fix(ci): Fix promptfoo security-assertion parsing** — the promptfoo (DAST/security eval) assertion parser was corrected so security assertions are read reliably. ([#4032](https://github.com/diegosouzapw/OmniRoute/pull/4032) — thanks @rdself) -- **docs(troubleshooting): note that the MITM proxy cannot intercept Windows-host apps under WSL** — documents that the MITM proxy running inside WSL cannot intercept traffic from apps on the Windows host. ([#4003](https://github.com/diegosouzapw/OmniRoute/pull/4003) — thanks @diegosouzapw) -- **chore(quality): maintenance roll-up** — assorted quality-gate hygiene that does not change runtime behavior: re-baseline `validation.ts` for the #3958 qwen body-check, allowlist the `socks` dependency declared by #4004, ignore jscpd major bumps (the v5 Rust rewrite breaks the pinned duplication gate), untrack an accidentally-committed root `node_modules` symlink (and gitignore it), rehome the #3972 logs auto-refresh test so a runner collects it, and open the v3.8.27 development cycle. (thanks @diegosouzapw) +- **feat(combos): 在导入界面宣传 Combo 能力（多模态/推理/缓存）** — 将 Combo 包导入客户端（LobeHub / OpenCode / VS Code，通过 `/v1/combos` 和 VS Code Combo 目录）后不再需要手动启用多模态/图像输入、推理和缓存。`projectCombo` 现在附加注册表派生的 `capabilities` 块，采用保守策略：仅当**所有**具体模型步骤均证明该能力时才声明 `multimodal`/`reasoning`（无法证明的嵌套 Combo 引用会丢弃这些能力，因为策略可能路由到任意成员），`caching` 反映 Combo 显式的上下文缓存保护设置（不会产生意外的提示缓存成本）。公开的 `/v1/combos` 默认映射 (#2300) 保持不变，除非调用者主动选择。([#3979](https://github.com/diegosouzapw/OmniRoute/issues/3979) — 感谢 @xenstar) +- **feat(sse): 委托 Anthropic 上下文编辑支持 Claude (`clear_tool_uses`)** — Claude 请求现在可以将上下文裁剪卸载到 Anthropic 的服务端上下文管理 API（beta `context-management-2025-06-27`、`clear_tool_uses_20250919`），在上游而非本地修剪过期的工具调用轮次。该功能仅适用于 Claude（编辑在服务端执行）；多服务商上下文裁剪仍由本地压缩引擎处理。([#4021](https://github.com/diegosouzapw/OmniRoute/pull/4021) — 感谢 @diegosouzapw) +- **feat(sse): 真实的 LLMLingua-2 ONNX 压缩引擎（稳定版）** — LLMLingua-2 提示压缩引擎现在使用真实的本地 ONNX 模型（默认 TinyBERT、transformers.js + tfjs），经 VPS 验证后提升为稳定版，替换了之前的占位实现。([#4014](https://github.com/diegosouzapw/OmniRoute/pull/4014) — 感谢 @diegosouzapw) +- **feat(compression): 捕获每个引擎的分析数据 + Lite schema 修复** — 压缩管线现在为历史分析持久化每个引擎的详细数据，使控制台能将节省量归因到堆叠管线中的每个引擎，同时修复了 Lite schema 不匹配的问题。([#4018](https://github.com/diegosouzapw/OmniRoute/pull/4018) — 感谢 @diegosouzapw) +- **feat(dashboard): Combo Live 级联中显示真实熔断器状态 (U1b)** — Combo Live 级联视图现在将每个服务商的真实熔断器状态（CLOSED / OPEN / HALF_OPEN）以徽章形式展示，从 `/api/monitoring/health` 实时读取，而非从请求结果推断健康状态。([#4029](https://github.com/diegosouzapw/OmniRoute/pull/4029) — 感谢 @diegosouzapw) +- **feat(openai): 模型发现时遵循自定义 base URL + 补全 openai/codex 定价** — 配置了自定义 base URL 的 OpenAI 格式服务商现在在模型发现（不仅是推理）时也遵循该 URL，openai/codex 定价表已补全。发现请求通过 SSRF 保护的外部 fetch 路由。([#4005](https://github.com/diegosouzapw/OmniRoute/pull/4005) — 感谢 @artickc) +- **feat(observability): 捕获实际上游服务商请求** — 请求检查器现在记录发送到上游服务商的确切载荷（翻译后），使您能看到 OmniRoute 实际派发的内容，而非仅看到客户端原始请求。([#3941](https://github.com/diegosouzapw/OmniRoute/pull/3941) — 感谢 @rdself) +- **feat(providers): 服务商认证可见性控制** — 添加在控制台中显示/隐藏服务商认证详情的控制，使凭证仅在需要时可见。([#3953](https://github.com/diegosouzapw/OmniRoute/pull/3953) — 感谢 @rdself) +- **feat(providers): 服务商仪表盘的模型搜索过滤器** — 服务商控制台新增搜索过滤器，可快速筛选服务商的模型列表。([#3950](https://github.com/diegosouzapw/OmniRoute/pull/3950) — 感谢 @felipesartori) +- **feat(compression): 印尼语 caveman 规则 + 语言包** — 为基于规则的压缩引擎添加印尼语 "caveman" 规则集和语言包。([#3975](https://github.com/diegosouzapw/OmniRoute/pull/3975) — 感谢 @Veier04) +- **feat(dashboard): 侧边栏分组分隔符开关** — 控制台侧边栏现在可以开关分组分隔符，获得更简洁的导航布局。([#3971](https://github.com/diegosouzapw/OmniRoute/pull/3971) — 感谢 @rdself) +- **feat(api): 本地 `@@om-usage` 命令支持缓存的按 key 用量** — API 客户端可发送恰好为 `@@om-usage` 的消息，在本地检索缓存的 Claude 风格用量数据，无需将 prompt 转发到上游服务商。由新的按 key 许可标志控制。([#4034](https://github.com/diegosouzapw/OmniRoute/pull/4034) — 感谢 @Witroch4) + +### 🐛 问题修复 + +- **fix(opencode): 无论用户如何命名服务商，都将 OpenCode 会话 ID 转发到上游** — `OpencodeExecutor` 转发了 `x-opencode-会话/请求/project/client` 头，但 OpenCode CLI 仅在配置的 `providerID` **以** `"opencode"` 开头时才发送这些头。如果用户将 OmniRoute 添加为自定义服务商（如 `"omniroute"`），CLI 会发送 `x-会话-affinity` / `X-Session-Id`（两者携带相同的会话 ID），而执行器从未读取这些头——因此在实际的服务商命名场景下，会话元数据转发实际上是一段死代码。opencode 系列执行器现在回退到 `x-会话-affinity` / `X-Session-Id` 并映射到 `x-opencode-会话`（当客户端未直接发送该头时），使得对 `opencode.ai` 上游的会话连续性对任何服务商名称都有效（直接发送的 `x-opencode-会话` 仍然优先）。仅限于此执行器——通用 `DefaultExecutor` 故意**不**这样做，以避免将客户端会话 ID 泄漏到任意第三方上游。([#4022](https://github.com/diegosouzapw/OmniRoute/issues/4022) — 感谢 @pizzav-xyz) +- **fix(guardrails): Vision Bridge 在 describe 调用失败时不再丢弃图像（Nvidia NIM "Image unavailable"）** — Vision Bridge 默认启用，并对 OmniRoute 无法从注册表证明其视觉能力的任何模型生效（`supportsVision !== true`，包括解析为 `null` 的未编目模型）。当每图像 describe 调用失败时（如未配置视觉模型），它用文字 `[Image N]: (unavailable)` 替换图像并丢弃原始 `image_url`——因此真正具有视觉能力的上游（Nvidia NIM）只收到文本并回答 "Image unavailable. Cannot provide description without visual data."。describe 失败不再具有破坏性：`replaceImageParts` 现在对失败图像接收 `null` 并**保留原始图像部分**，使上游仍能看到它（成功的 describe 仍用文本描述替换图像；`meta.descriptions` 可观测性不变）。([#4012](https://github.com/diegosouzapw/OmniRoute/issues/4012) — 感谢 @daniij) +- **fix(kiro): 在 Kiro 流式路径上保留 `finish_reason: "tool_calls"`** — 通过 Kiro (Responses API) 服务商的流式 tool-call 请求，其终端 `finish_reason` 被报告为 `"stop"` 而非 `"tool_calls"`，因此 Agent 客户端（Hermes）将 tool-call 轮次视为已完成轮次，从未运行工具，下一个请求因不完整的工具状态而失败并返回 HTTP 400。`convertKiroToOpenAI` 的终端 `messageStopEvent`/`done` 分支硬编码了 `finish_reason: "stop"`，无论流是否发出了 `toolUseEvent`。翻译器现在在发出 tool-use 块时记录 `state.sawToolUse`，并在流产生了工具调用时在终端块（和 `state.finishReason`）中报告 `finish_reason: "tool_calls"`。非流式路径此前已正确。([#3980](https://github.com/diegosouzapw/OmniRoute/issues/3980) — 感谢 @lordavadon2) +- **fix(resilience): 正确处理以数字纪元形式存储的连接冷却期** — 路由器持续向仍在速率限制冷却期内的连接派发请求，因为 `rate_limited_until`（`TEXT` 列）以原始纪元数字持久化，SQLite 将其强制转换为字符串如 `"1781696905131.0"`，而 `new Date(...)` 将其解析为 `NaN`，因此冷却中的连接从未被跳过。冷却读取谓词现在通过共享的 `cooldownUntilMs()` 辅助函数规范化数字纪元字符串；ISO 行为不变。([#3995](https://github.com/diegosouzapw/OmniRoute/pull/3995) — 感谢 @diegosouzapw) +- **fix(providers): 为 LLM7 和 BytePlus 获取线上 `/models` 目录** — 导入 LLM7 或 BytePlus key 仅显示一个过时的小型硬编码列表，因为这两个服务商均未被模型导入路由的任何实时获取分支分类。两者现在均加入 `NAMED_OPENAI_STYLE_PROVIDERS`，因此路由使用该 key 探测 `/模型` 并提供线上目录，仅在上游获取失败时回退到本地目录。([#3996](https://github.com/diegosouzapw/OmniRoute/pull/3996) — 感谢 @FerLuisxd / @diegosouzapw) +- **fix(dashboard): 日志自动刷新读取实时可见性状态，而非过时的挂载引用** — 当标签页在后台加载时，日志页面从未自动刷新，因为自动刷新间隔在每个 tick 上受挂载时一次性播种的可见性引用控制；tick 现在读取实时的 `document.visibilityState`，因此轮询在标签页可见后立即自愈，同时真正隐藏时仍然暂停。([#3997](https://github.com/diegosouzapw/OmniRoute/pull/3997) — 感谢 @tjengbudi / @diegosouzapw) +- **fix(combo): 打乱 strict-random 容灾余量以分散负载** — 使用 `strict-random` 策略时，持续失败的模型几乎在每次请求上都重试，因为只有牌组选中的 slot 0 被洗牌，而容灾余量保持固定优先级顺序；余量现在也被洗牌，因此容灾负载（及从失败目标恢复）均匀分散到健康对等节点。([#3998](https://github.com/diegosouzapw/OmniRoute/pull/3998) — 感谢 @KeNJiKunG / @diegosouzapw) +- **fix(claude): 在 Claude OAuth 路径上转发客户端 `tool-search-tool-2025-10-19` anthropic-beta** — 启用延迟工具时，Claude Code 协商 `tool-搜索-tool-2025-10-19` beta，但 OmniRoute 在两个 Claude 代码路径上均将其丢弃，因此 claude.ai 后端以 `400 Tool reference not found` 拒绝每个延迟工具请求。新的白名单合并 (`mergeClientAnthropicBeta`) 现在在两个路径上将客户端协商的 beta 合并到出站集合中，仅追加白名单中的客户端 beta（保留 #3415 修复）。([#3999](https://github.com/diegosouzapw/OmniRoute/pull/3999) — 感谢 @huohua-dev / @diegosouzapw) +- **fix(executor): 在非流式请求中去除 `stream_options`（NVIDIA NIM 400）** — 无论 `流` 如何都发送 `stream_options: { include_usage: true }` 的客户端（如 OpenAI Python SDK）在非流式调用中将其原样传递，NVIDIA NIM 以 `400 "Stream options can only be defined when 流=True"` 拒绝。`DefaultExecutor.transformRequest` 现在在 `流` 为 false 时去除 `stream_options`；流式注入路径不变。([#4000](https://github.com/diegosouzapw/OmniRoute/pull/4000) — 感谢 @andrea-kingautomation / @daniij / @diegosouzapw) +- **fix(sse): 在 `getUnsupportedParams` (mimocode) 中保护无模型注册表条目** — 没有模型映射的注册表条目 (mimocode) 在计算不支持参数时抛出异常；查找现在保护无模型情况，使请求验证不再崩溃。([#4015](https://github.com/diegosouzapw/OmniRoute/pull/4015) — 感谢 @diegosouzapw) +- **fix(perplexity-web): 解析结构化 `diff_block` 流使答案不再为空** — Perplexity web 将其答案作为 RFC-6902 `diff_block` 补丁流式传输，OmniRoute 在 `PENDING` 阶段未应用这些补丁，因此响应返回为空；解析器现在应用补丁并在 `COMPLETED` 时物化文本。([#4001](https://github.com/diegosouzapw/OmniRoute/pull/4001) — 感谢 @artickc) +- **fix(default-executor): 遵循 OpenAI 格式服务商的自定义 `providerSpecificData.baseUrl`** — 配置了自定义 base URL 的 OpenAI 格式服务商在推理路径上被忽略；默认执行器现在遵循 `providerSpecificData.baseUrl`，使请求到达配置的端点。([#4002](https://github.com/diegosouzapw/OmniRoute/pull/4002) — 感谢 @artickc) +- **fix(live-ws): 将 LiveWS sidecar 事件桥接到控制台** — LiveWS sidecar 发出的事件未到达控制台；它们现在被桥接，使实时 websocket 活动可见。（sidecar 认证 Token 解析中的 cookie 认证回归也已修正。）([#4004](https://github.com/diegosouzapw/OmniRoute/pull/4004) — 感谢 @megamen32) +- **fix(qwen-web): cookie 验证误报 — 检查响应 body 中的用户对象** — Qwen web cookie 验证将有效 cookie 报告为无效；现在检查响应 body 中的 `user` 对象，而非仅依赖状态码。([#3958](https://github.com/diegosouzapw/OmniRoute/pull/3958) — 感谢 @thezukiru) +- **fix(vision-bridge): 强制 tokenrouter DeepSeek 模型使用桥接** — tokenrouter DeepSeek 模型现在强制通过 Vision Bridge，使图像输入得到正确处理。([#3946](https://github.com/diegosouzapw/OmniRoute/pull/3946) — 感谢 @WormAlien) +- **fix(api): 对 `/api/auth/login` 上格式错误的 JSON 返回 400（而非 500）** — 登录端点上的格式错误 JSON body 返回不透明的 500；现在返回正确的 400。([#4031](https://github.com/diegosouzapw/OmniRoute/pull/4031) — 感谢 @rdself) +- **fix(dashboard): Playground 对比标签页加载 + HTTP 方法守卫** — Playground 对比标签页加载失败；加载路径已修复并添加了 HTTP 方法守卫。([#4024](https://github.com/diegosouzapw/OmniRoute/pull/4024) — 感谢 @rdself) +- **fix(proxy): 在特性标志后控制控制平面代理直接回退（fail-closed）** — 当固定代理不可达时，控制平面操作的直接连接容灾现在受特性标志控制并 fail-closed，因此固定代理永远不会被静默绕过，除非显式允许。([#3963](https://github.com/diegosouzapw/OmniRoute/pull/3963) — 感谢 @rdself) +- **fix(db): 持久化备份保留天数** — 备份保留天数设置在重启后未持久化；现在被持久存储。([#3970](https://github.com/diegosouzapw/OmniRoute/pull/3970) — 感谢 @rdself) +- **fix(dashboard): 优化服务商配额卡片显示** — 服务商配额卡片布局经过优化，呈现更清晰的配额/用量��示。([#3969](https://github.com/diegosouzapw/OmniRoute/pull/3969) — 感谢 @rdself) +- **fix(dashboard): 优化压缩设置、存储标签和侧边栏分组** — 打磨压缩设置 UI、澄清存储标签、整理侧边栏分组。([#4033](https://github.com/diegosouzapw/OmniRoute/pull/4033) — 感谢 @rdself) + +### 🔒 安全与加固 + +- **fix(security): 消除 combo `` 标签正则中的多项式 ReDoS** — `comboAgentMiddleware` 的缓存标签模式将标签包裹在无界换行运行中 (`(?:\n|\r)*`)，使 `.test()` / `.replace()` 在大量换行的输入上以 O(n²) 运行（CodeQL `js/polynomial-redos`）。检测模式现在仅匹配核心 `…`，全局剥离模式限制周围的换行运行，保持线性；检测/提取/多标签剥离行为不变。([#3982](https://github.com/diegosouzapw/OmniRoute/pull/3982) — 感谢 @diegosouzapw) +- **ci(security): 加固工作流 — artipacked `persist-凭证`、缓存投毒、SC2086** — GitHub Actions 工作流针对 artipacked `persist-凭证` 泄漏和缓存投毒进行了加固，并修复了 shell 引用 (`SC2086`) 问题。([#3965](https://github.com/diegosouzapw/OmniRoute/pull/3965) — 感谢 @diegosouzapw) +- **ci(quality): 将 require-tighten + OSV + Trivy 转为阻断（周期结束）** — 每个模块的 require-tighten 检查和 OSV / Trivy 扫描器从建议转为阻断，用于 v3.8.27 周期收尾，使新的依赖或覆盖率回退导致 CI 失败。([#3984](https://github.com/diegosouzapw/OmniRoute/pull/3984) — 感谢 @diegosouzapw) +- **chore(deps): dependabot 安全升级 + 移除未使用的 gray-matter** — 应用一批 Dependabot 安全升级，并从依赖树中移除未使用的 `gray-matter`。([#4036](https://github.com/diegosouzapw/OmniRoute/pull/4036) — 感谢 @diegosouzapw) +- **chore(deps): 自动依赖升级** — Dependabot 升级了生产依赖组（13 个更新）、`vite`、`form-data` 和 `npm_and_yarn` 组。([#3915](https://github.com/diegosouzapw/OmniRoute/pull/3915), [#3942](https://github.com/diegosouzapw/OmniRoute/pull/3942), [#3943](https://github.com/diegosouzapw/OmniRoute/pull/3943), [#3944](https://github.com/diegosouzapw/OmniRoute/pull/3944) — 感谢 @dependabot) + +### 🧹 内部 / 质量 / 文档 + +- **feat(ci): Quality Gate v2 — Onda 0 + Onda 1** — Quality Gate v2 计划的前两波：门控翻转、测试影响分析 (TIA)、SAST、DAST-smoke 和变异测试基础设施。([#4016](https://github.com/diegosouzapw/OmniRoute/pull/4016) — 感谢 @diegosouzapw) +- **refactor: 将服务商注册表模块化为独立的服务商插件** — `providerRegistry.ts` 拆分为独立的按服务商插件模块（非堆叠）。后续修复恢复了迁移中丢失的 `byteplus` + `mimocode` 模块。([#3993](https://github.com/diegosouzapw/OmniRoute/pull/3993) — 感谢 @oyi77 / @diegosouzapw) +- **refactor: 模块化 schemas（非堆叠）** — 请求/响应 schema 定义拆分为独立模块，减少文件大小并提高可维护性。([#3988](https://github.com/diegosouzapw/OmniRoute/pull/3988) — 感谢 @oyi77) +- **fix: 恢复因 schema/注册表模块化导致的单元测试回归** — schema/注册表模块化 (#3988, #3993) 静默丢弃了被单元测试覆盖的内部逻辑；本 PR 恢复了受影响的单元测试。([#4030](https://github.com/diegosouzapw/OmniRoute/pull/4030) — 感谢 @diegosouzapw) +- **refactor(dashboard): 设置 UI 布局 + API Keys 命名** — 设置 UI 布局已重组，"API Keys" 命名已明确。([#4020](https://github.com/diegosouzapw/OmniRoute/pull/4020) — 感谢 @rdself) +- **大量UI显示和i18n优化 (dashboard UI display + i18n improvements)** — 一批控制台 UI 显示优化和 i18n 字符串改进。([#3973](https://github.com/diegosouzapw/OmniRoute/pull/3973) — 感谢 @rdself) +- **fix(ci): 将 TIA 作用域限制为仅 `node:test` 单元文件** — 测试影响分析匹配了 `node:test` 运行器不执行的文件，产生 99 个误报失败；TIA glob 现在与 `test:unit` glob 完全一致。([#4035](https://github.com/diegosouzapw/OmniRoute/pull/4035) — 感谢 @diegosouzapw) +- **fix(ci): electron-release publish-npm needs `contents: write`** — the reusable npm-publish job invoked by the electron release lacked `contents: write`, causing a v3.8.26 `startup_failure`; the permission was granted. ([#3966](https://github.com/diegosouzapw/OmniRoute/pull/3966) — 感谢 @diegosouzapw) +- **test(opencode-plugin): ESM default-export test (drop the stale CJS bundle test)** — replaces the stale CJS bundle test with an ESM 默认-export test, following up the #3883 ESM-only 迁移. ([#3967](https://github.com/diegosouzapw/OmniRoute/pull/3967) — 感谢 @diegosouzapw) +- **fix(ci): Fix promptfoo security-assertion parsing** — the promptfoo (DAST/security eval) 断言 parser was corrected so security assertions are read reliably. ([#4032](https://github.com/diegosouzapw/OmniRoute/pull/4032) — 感谢 @rdself) +- **docs(troubleshooting): note that the MITM proxy cannot intercept Windows-host apps under WSL** — documents that the MITM 代理 running inside WSL cannot intercept traffic from apps on the Windows host. ([#4003](https://github.com/diegosouzapw/OmniRoute/pull/4003) — 感谢 @diegosouzapw) +- **chore(quality): maintenance roll-up** — assorted quality-gate hygiene that 不 change runtime behavior: re-baseline `validation.ts` for the #3958 qwen body-check, allowlist the `socks` dependency declared by #4004, ignore jscpd major bumps (the v5 Rust rewrite breaks the pinned duplication gate), untrack an accidentally-committed root `node_modules` symlink (and gitignore it), rehome the #3972 logs auto-refresh test so a runner collects it, and open the v3.8.27 development cycle. (thanks @diegosouzapw) --- @@ -1122,58 +1122,58 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(media): Vertex AI (Google) speech, transcription, music & video generation** — Vertex AI's Google media models are now routable through dynamic discovery: speech synthesis, audio transcription, music generation, and video generation. ([#3929](https://github.com/diegosouzapw/OmniRoute/pull/3929) — thanks @artickc) -- **feat(glm): add GLM-5.2 with effort-tier routing (high/max)** — GLM-5.2 is registered with high/max effort-tier routing. ([#3885](https://github.com/diegosouzapw/OmniRoute/pull/3885) — thanks @dhaern) -- **feat(combo): add a sticky round-robin target limit** — round-robin combos can cap how many targets stay "sticky" within a session (`stickyRoundRobinLimit`), balancing stickiness against spread. ([#3846](https://github.com/diegosouzapw/OmniRoute/pull/3846) — thanks @adivekar-utexas) -- **feat(openrouter): connection presets** — OpenRouter connections support reusable presets (provider routing / sort / quantization preferences), selectable when adding a connection. ([#3878](https://github.com/diegosouzapw/OmniRoute/pull/3878) — thanks @rdself) - -### 🐛 Fixed - -- **fix(compression/memory): stop memory + compression from poisoning the upstream prompt cache** — with compression and/or memory enabled, requests to caching providers (Anthropic-family) missed the prompt cache on every turn, multiplying cost. Two root causes: (1) memory injection prepended the retrieved memories — which **vary per user query** — at index 0 of the message array, shifting the entire cacheable prefix every turn; memory is now inserted just before the last user message when the request carries `cache_control` breakpoints, keeping the cacheable prefix (system prompt + prior turns) byte-stable. (2) the cache-aware `skipSystemPrompt` flag computed by `getCacheAwareStrategy()` was dropped by `selectCompressionStrategy()` (which can only return a mode), so the system prompt could still be compressed under caching; a new `resolveCacheAwareConfig()` now forces `preserveSystemPrompt` on for caching requests. ([#3936](https://github.com/diegosouzapw/OmniRoute/pull/3936), closes [#3890](https://github.com/diegosouzapw/OmniRoute/issues/3890) — thanks @xenstar / @diegosouzapw) -- **fix(providers): register BytePlus ModelArk so its API key can be added** — adding a BytePlus (`ark-…`) key reported "invalid". `byteplus` was present in the provider catalog (`APIKEY_PROVIDERS`) but **never registered in the routing registry**, so key validation fell through to `{ unsupported: true }` → HTTP 400 → the UI rendered every key as invalid (and the provider was unusable for inference). Added a registry entry modeled on the existing Volcengine Ark provider: OpenAI-compatible format, base `https://ark.ap-southeast.bytepluses.com/api/v3` (region `ap-southeast-1`), `Authorization: Bearer` auth, seeded with the catalog's advertised models (Seed 2.0, Kimi K2 Thinking, GLM 4.7, GPT-OSS-120B). ([#3935](https://github.com/diegosouzapw/OmniRoute/pull/3935), closes [#3877](https://github.com/diegosouzapw/OmniRoute/issues/3877) — thanks @nikohd12 / @diegosouzapw) -- **fix(providers): Nous Research key validation no longer fails on a stale probe model** — adding a valid Nous Research API key reported "invalid" even though the same key worked via the portal's copy-shell `curl`. The validation probe sent `model: "nousresearch/hermes-4-70b"`, which Nous does not serve, so the API returned `400` and the validator (which only treated `200`/`429` as success) reported the key invalid. The probe now uses the real `Hermes-4-70B` slug, and any non-auth 4xx (`400`/`404`/`422`) is treated as a valid key (the request shape was wrong, not the credentials) — mirroring the longcat/nvidia validators so a future model rename can't re-break key validation. ([#3934](https://github.com/diegosouzapw/OmniRoute/pull/3934), closes [#3881](https://github.com/diegosouzapw/OmniRoute/issues/3881) — thanks @FerLuisxd / @diegosouzapw) -- **fix(stream): persist mid-stream upstream failures** — when an upstream stream fails partway through, the partial response and incremental usage are now finalized and persisted instead of lost; extracts a shared `streamFailureFinalization` path and merges incremental Claude usage (follow-up to #3879). ([#3937](https://github.com/diegosouzapw/OmniRoute/pull/3937) — thanks @rdself) -- **fix(perplexity-web): update the request payload to schema v2.18 (HTTP 400)** — Perplexity web requests started returning HTTP 400; the request payload was updated to Perplexity's v2.18 schema. ([#3938](https://github.com/diegosouzapw/OmniRoute/pull/3938) — thanks @artickc) -- **fix(stream): keep the in-flight request payload in sync** — the pending-by-id request record is now updated in place (`Object.assign`) so the in-flight payload stays consistent with what was dispatched (coexists with #3937). ([#3940](https://github.com/diegosouzapw/OmniRoute/pull/3940) — thanks @rdself) -- **fix: stabilize reasoning streams and request logs** — reasoning-token streaming and the request-log capture path were stabilized to avoid dropped/duplicated reasoning frames and inconsistent log entries. ([#3879](https://github.com/diegosouzapw/OmniRoute/pull/3879) — thanks @rdself) -- **fix(opencode-plugin): include nested combo-refs in the LCD context window** — the OpenCode plugin now follows nested combo references when computing the least-common-denominator context window, so a combo nested inside another no longer reports an inflated window. ([#3910](https://github.com/diegosouzapw/OmniRoute/pull/3910) — thanks @herjarsa) -- **fix(models): correct the failed-model auto-hide defaults** — the defaults governing when a failed model is auto-hidden were corrected, and auto-hide is now opt-in so models are no longer dropped unexpectedly. ([#3930](https://github.com/diegosouzapw/OmniRoute/pull/3930) — thanks @rdself) -- **fix(openrouter): show the preset field when editing a connection** — the connection-preset field appeared only when creating a connection, not when editing one; it now appears in both (follow-up to #3878). ([#3921](https://github.com/diegosouzapw/OmniRoute/pull/3921) — thanks @rdself) -- **fix(sse): announce the assistant role on the first delta (Responses→Chat)** — the first SSE delta of a Responses-API→Chat-Completions stream now carries `role: "assistant"`, which strict OpenAI-compatible clients expect before content deltas. ([#3911](https://github.com/diegosouzapw/OmniRoute/pull/3911) — thanks @diego-anselmo) -- **fix(vertex): add the generative-language scope so SA-JSON model discovery works** — Vertex service-account (SA-JSON) model discovery failed without the `generative-language` OAuth scope; the scope is now requested. ([#3922](https://github.com/diegosouzapw/OmniRoute/pull/3922) — thanks @artickc) -- **fix(proxy): direct-connection fallback for control-plane ops when a pinned proxy is unreachable** — control-plane operations (validation, discovery) now fall back to a direct connection when a connection's pinned proxy is unreachable, instead of failing outright. ([#3906](https://github.com/diegosouzapw/OmniRoute/pull/3906) — thanks @zhiru) -- **fix(providers): prevent zombie-socket hangs for zai/glm and tighten the default keepAlive** — zai/glm could hang on dead keep-alive sockets; the default keepAlive was tightened to evict zombie sockets. ([#3907](https://github.com/diegosouzapw/OmniRoute/pull/3907) — thanks @insoln) -- **fix(setup): remove the stale CJS bundle check from setup-open-code** — the OpenCode setup helper no longer checks for a CJS bundle that the now ESM-only plugin no longer ships. ([#3908](https://github.com/diegosouzapw/OmniRoute/pull/3908) — thanks @herjarsa) -- **fix(opencode-plugin): drop the CJS bundle to fix the OpenCode plugin loader** — the plugin is now ESM-only, fixing the OpenCode loader which failed on the dual CJS/ESM build. ([#3883](https://github.com/diegosouzapw/OmniRoute/pull/3883) — thanks @herjarsa) -- **fix(mcp): fall back to `node:sqlite` when the better-sqlite3 binding is missing** — the MCP server now falls back to Node's built-in `node:sqlite` when the native better-sqlite3 binding is unavailable, instead of crashing. ([#3887](https://github.com/diegosouzapw/OmniRoute/pull/3887) — thanks @megamen32) -- **fix(models): correct the generate-models alias lookup** — alias resolution during model generation was corrected so aliased model ids resolve to their canonical entry. ([#3870](https://github.com/diegosouzapw/OmniRoute/pull/3870) — thanks @YunyunZhai) -- **fix(combo): guard the candidate pool against an empty array** — combo candidate-pool selection no longer throws when the pool resolves to an empty array. ([#3871](https://github.com/diegosouzapw/OmniRoute/pull/3871) — thanks @YunyunZhai) - -### 🔒 安全 & Hardening - -- **fix(security): bump form-data + vite (2 HIGH), harden workflow template-injection & allowlist guarded `workflow_run`** — two HIGH Dependabot advisories (`form-data`, `vite`) were upgraded; GitHub Actions workflows were hardened against `${{ }}` template-injection (untrusted values now passed via `env:`); and the guarded `workflow_run` trigger was allowlisted. ([#3949](https://github.com/diegosouzapw/OmniRoute/pull/3949) — thanks @diegosouzapw) - -### 🧹 Internal / Quality / Docs - -- **fix(ci): grant `contents: write` to the npm publish job for SBOM attach** — the v3.8.25 TokenPermissions hardening set the npm-publish `publish` job to `contents: read`, but its "Attach SBOM to GitHub Release" step (`gh release upload`) needs `contents: write` and failed with HTTP 403 on the v3.8.25 release (npm / GitHub Packages / opencode-plugin / Docker / Electron all published fine; only the SBOM attach broke — the v3.8.25 SBOM was attached manually). ([#3874](https://github.com/diegosouzapw/OmniRoute/pull/3874) — thanks @diegosouzapw) -- **ci(quality): make zizmor / gitleaks / osv scanners functional + freeze advisory baselines** — the supply-chain scanners are now actually executed (correct install + invocation) with frozen advisory baselines so new findings surface as diffs. ([#3947](https://github.com/diegosouzapw/OmniRoute/pull/3947) — thanks @diegosouzapw) -- **ci(quality): fix scanner install + size-limit preset, promote `codeqlAlerts` to blocking** — corrected the scanner install and the size-limit preset, and promoted the `codeqlAlerts` ratchet from advisory to blocking. ([#3945](https://github.com/diegosouzapw/OmniRoute/pull/3945) — thanks @diegosouzapw) -- **ci(quality): wire Stryker mutation testing as an advisory nightly** — Stryker mutation testing runs nightly (advisory) — Quality Gates Fase 7 · Task 11. ([#3898](https://github.com/diegosouzapw/OmniRoute/pull/3898) — thanks @diegosouzapw) -- **ci(quality): freeze per-module coverage floors + wire require-tighten (advisory)** — per-module coverage floors are frozen with an advisory "require-tighten" check that flags modules drifting below their floor. ([#3901](https://github.com/diegosouzapw/OmniRoute/pull/3901) — thanks @diegosouzapw) -- **ci(quality): enforce the stale-allowlist check on `check-known-symbols`** — stale allowlist entries (suppressing a symbol that no longer exists) now fail the gate — Fase 6A.3 follow-up. ([#3899](https://github.com/diegosouzapw/OmniRoute/pull/3899) — thanks @diegosouzapw) -- **test(ci): de-flake pipeline-payloads via per-test re-seed + honest reset** — the pipeline-payloads suite now re-seeds per test and performs an honest cache reset, eliminating a cross-test ordering flake. ([#3893](https://github.com/diegosouzapw/OmniRoute/pull/3893) — thanks @diegosouzapw) -- **fix(ci): drop the `secrets`-in-job-`if` from nightly-llm-security** — referencing `secrets` in a job-level `if` caused a `startup_failure` on push; the gating was moved so the workflow starts cleanly. ([#3892](https://github.com/diegosouzapw/OmniRoute/pull/3892) — thanks @diegosouzapw) -- **test: reconcile the runtime-timeouts keepAlive baseline to 4000 after the #3907 source revert** — the keepAlive assertion was realigned to the source value (4000) after #3907's source-side revert. ([#3933](https://github.com/diegosouzapw/OmniRoute/pull/3933) — thanks @diegosouzapw) -- **chore(repo): nest quality-gate state under `config/quality`, declutter the repo root** — baselines / allowlists / metrics moved under `config/quality/`, trimming the tracked root file count. ([#3896](https://github.com/diegosouzapw/OmniRoute/pull/3896) — thanks @diegosouzapw) -- **docs: refresh the provider count to 226 + regenerate `PROVIDER_REFERENCE.md`** — the README advertised a stale `177 providers`; the canonical generator (`scripts/docs/gen-provider-reference.ts`) now reports **226 unique provider IDs**, so the README badges/anchors and the generated provider reference were brought in sync. Also adds a documentation audit/sync report. (thanks @diegosouzapw) -- **docs: sync all documentation to v3.8.24 + count-guard & wiki/prose CI** — a full documentation sync with a strict provider/locale count-guard plus Vale / markdownlint prose CI. ([#3804](https://github.com/diegosouzapw/OmniRoute/pull/3804) — thanks @diegosouzapw) -- **docs: regenerate stale counts to canonical values** — 226 providers / 87 MCP tools / 15 strategies / 42 locales. ([#3904](https://github.com/diegosouzapw/OmniRoute/pull/3904) — thanks @diegosouzapw) -- **docs(quality): correct the stale gate count + add an opt-in agent-lsp scaffold** — ([#3902](https://github.com/diegosouzapw/OmniRoute/pull/3902) — thanks @diegosouzapw) -- **docs(mcp): correct the MCP tool-inventory diagram source + text to 87 tools** — ([#3909](https://github.com/diegosouzapw/OmniRoute/pull/3909) — thanks @diegosouzapw) -- **docs: update the compression section to the 9-engine multi-layer stack** — ([#3894](https://github.com/diegosouzapw/OmniRoute/pull/3894) — thanks @diegosouzapw) -- **ci(docs): automate GitHub wiki sync (add missing pages + cover counts)** — ([#3900](https://github.com/diegosouzapw/OmniRoute/pull/3900) — thanks @diegosouzapw) -- **docs: require a dedicated git worktree + branch per development task (Hard Rule #19)** — codifies the worktree-isolation rule after the shared-checkout incidents. ([#3939](https://github.com/diegosouzapw/OmniRoute/pull/3939) — thanks @diegosouzapw) -- **fix(docs): add MDX frontmatter to `DOCUMENTATION_AUDIT_REPORT` so the fumadocs build passes** — the audit report lacked the `title:` frontmatter MDX pages require. (thanks @diegosouzapw) +- **feat(media): Vertex AI (Google) 语音合成、转录、音乐和视频生成** — Vertex AI 的 Google 媒体模型现在可通过动态发现进行路由：语音合成、音频转录、音乐生成和视频生成。([#3929](https://github.com/diegosouzapw/OmniRoute/pull/3929) — 感谢 @artickc) +- **feat(glm): 添加 GLM-5.2 的 effort-tier 路由 (high/max)** — GLM-5.2 已注册 high/max effort-tier 路由。([#3885](https://github.com/diegosouzapw/OmniRoute/pull/3885) — 感谢 @dhaern) +- **feat(combo): 添加粘性轮询目标限制** — 轮询 combo 可限制会话内保持 "粘性" 的目标数量 (`stickyRoundRobinLimit`)，在粘性和分散之间取得平衡。([#3846](https://github.com/diegosouzapw/OmniRoute/pull/3846) — 感谢 @adivekar-utexas) +- **feat(openrouter): 连接预设** — OpenRouter 连接支持可重用预设（服务商路由/排序/量化偏好），添加连接时可选择。([#3878](https://github.com/diegosouzapw/OmniRoute/pull/3878) — 感谢 @rdself) + +### 🐛 问题修复 + +- **fix(compression/memory): 停止记忆 + 压缩污染上游提示缓存** — 启用压缩和/或记忆时，对缓存服务商（Anthropic 系列）的请求在每个轮次上都错过提示缓存，导致成本倍增。两个根本原因：(1) 记忆注入将检索到的记忆（**因用户查询而异**）前置到消息数组的索引 0，使整个可缓存前缀在每个轮次上发生偏移；记忆现在在请求携带 `cache_control` 断点时，插入到最后一条用户消息之前，保持可缓存前缀（系统提示 + 先前轮次）字节稳定。(2) 由 `getCacheAwareStrategy()` 计算的缓存感知 `skipSystemPrompt` 标志被 `selectCompressionStrategy()` 丢弃（该函数只能返回模式），因此系统提示在缓存下仍可能被压缩；新的 `resolveCacheAwareConfig()` 现在强制为缓存请求开启 `preserveSystemPrompt`。([#3936](https://github.com/diegosouzapw/OmniRoute/pull/3936)，关闭 [#3890](https://github.com/diegosouzapw/OmniRoute/issues/3890) — 感谢 @xenstar / @diegosouzapw) +- **fix(providers): 注册 BytePlus ModelArk 使 API key 可添加** — 添加 BytePlus (`ark-…`) key 时报 "invalid"。`byteplus` 存在于服务商目录 (`APIKEY_PROVIDERS`) 中但**从未在路由注册表中注册**，因此 key 验证回退到 `{ unsupported: true }` → HTTP 400 → UI 将所有 key 渲染为无效（且该服务商无法用于推理）。新增注册表条目，仿照现有 Volcengine Ark 服务商：OpenAI 兼容格式、基础 URL `https://ark.ap-southeast.bytepluses.com/api/v3`（区域 `ap-southeast-1`）、`Authorization: Bearer` 认证，使用目录中公告的模型（Seed 2.0、Kimi K2 Thinking、GLM 4.7、GPT-OSS-120B）作为种子。([#3935](https://github.com/diegosouzapw/OmniRoute/pull/3935)，关闭 [#3877](https://github.com/diegosouzapw/OmniRoute/issues/3877) — 感谢 @nikohd12 / @diegosouzapw) +- **fix(providers): Nous Research key validation no longer fails on a stale probe model** — adding a valid Nous Research API Key reported "invalid" even though the same key worked via the portal's copy-shell `curl`. The validation probe sent `模型: "nousresearch/hermes-4-70b"`, which Nous 不 serve, so the API returned `400` and the validator (which only treated `200`/`429` as success) reported the key invalid. The probe now uses the real `Hermes-4-70B` slug, and any non-认证 4xx (`400`/`404`/`422`) is treated as a valid key (the 请求 shape was wrong, not the 凭证) — mirroring the longcat/nvidia validators so a future 模型 rename can't re-break key validation. ([#3934](https://github.com/diegosouzapw/OmniRoute/pull/3934), closes [#3881](https://github.com/diegosouzapw/OmniRoute/issues/3881) — 感谢 @FerLuisxd / @diegosouzapw) +- **fix(stream): 持久化流中途的上游失败** — 当上游流中途失败时，部分响应和增量用量现在被完成并持久化，而非丢失；提取了共享的 `streamFailureFinalization` 路径，并合并了增量 Claude 用量（#3879 的跟进）。([#3937](https://github.com/diegosouzapw/OmniRoute/pull/3937) — 感谢 @rdself) +- **fix(perplexity-web): 将请求载荷更新为 schema v2.18（HTTP 400）** — Perplexity web 请求开始返回 HTTP 400；请求载荷已更新为 Perplexity v2.18 schema。([#3938](https://github.com/diegosouzapw/OmniRoute/pull/3938) — 感谢 @artickc) +- **fix(stream): 保持进行中请求载荷同步** — 按 ID 挂起的请求记录现在原地更新 (`Object.assign`)，使进行中载荷与已派发的内容保持一致（与 #3937 共存）。([#3940](https://github.com/diegosouzapw/OmniRoute/pull/3940) — 感谢 @rdself) +- **fix: 稳定推理流和请求日志** — 推理 token 流式传输和请求日志捕获路径已稳定，避免丢弃/重复推理帧和不一致的日志条目。([#3879](https://github.com/diegosouzapw/OmniRoute/pull/3879) — 感谢 @rdself) +- **fix(opencode-plugin): 在 LCD 上下文窗口中包含嵌套 Combo 引用** — OpenCode 插件现在在计算最小公分母上下文窗口时跟随嵌套的 Combo 引用，使嵌套在其他 Combo 中的 Combo 不再报告膨胀的窗口。([#3910](https://github.com/diegosouzapw/OmniRoute/pull/3910) — 感谢 @herjarsa) +- **fix(models): 修正失败模型自动隐藏的默认值** — 控制失败模型何时自动隐藏的默认值已修正，自动隐藏现在为主动选择加入，使模型不再意外被隐藏。([#3930](https://github.com/diegosouzapw/OmniRoute/pull/3930) — 感谢 @rdself) +- **fix(openrouter): 编辑连接时显示预设字段** — 连接预设字段仅在创建连接时出现，编辑时不显示；现在两者均显示（#3878 的跟进）。([#3921](https://github.com/diegosouzapw/OmniRoute/pull/3921) — 感谢 @rdself) +- **fix(sse): 在首个 delta 上声明助手角色（Responses→Chat）** — Responses-API→Chat-Completions 流的首个 SSE delta 现在携带 `role: "assistant"`，严格的 OpenAI 兼容客户端在内容 delta 之前需要该字段。([#3911](https://github.com/diegosouzapw/OmniRoute/pull/3911) — 感谢 @diego-anselmo) +- **fix(vertex): 添加 generative-language 作用域使 SA-JSON 模型发现正常工作** — Vertex 服务账户 (SA-JSON) 模型发现在缺少 `generative-language` OAuth 作用域时失败；该作用域现在被请求。([#3922](https://github.com/diegosouzapw/OmniRoute/pull/3922) — 感谢 @artickc) +- **fix(proxy): 固定代理不可达时控制平面操作回退到直接连接** — 控制平面操作（验证、发现）现在在连接固定代理不可达时容灾到直接连接，而非直接失败。([#3906](https://github.com/diegosouzapw/OmniRoute/pull/3906) — 感谢 @zhiru) +- **fix(providers): 防止 zai/glm 僵尸 socket 挂起并收紧默认 keepAlive** — zai/glm 可能在失效的 keep-alive socket 上挂起；默认 keepAlive 已收紧以驱逐僵尸 socket。([#3907](https://github.com/diegosouzapw/OmniRoute/pull/3907) — 感谢 @insoln) +- **fix(setup): 从 setup-open-code 中移除过时的 CJS bundle 检查** — OpenCode 设置助手不再检查 CJS bundle，因为现在仅 ESM 的插件已不再包含它。([#3908](https://github.com/diegosouzapw/OmniRoute/pull/3908) — 感谢 @herjarsa) +- **fix(opencode-plugin): 移除 CJS bundle 以修复 OpenCode 插件加载器** — 插件现在仅 ESM，修复了因双 CJS/ESM 构建而失败的 OpenCode 加载器。([#3883](https://github.com/diegosouzapw/OmniRoute/pull/3883) — 感谢 @herjarsa) +- **fix(mcp): better-sqlite3 绑定缺失时回退到 `node:sqlite`** — MCP 服务器现在在原生的 better-sqlite3 绑定不可用时回退到 Node 内置的 `node:sqlite`，而非崩溃。([#3887](https://github.com/diegosouzapw/OmniRoute/pull/3887) — 感谢 @megamen32) +- **fix(models): 修正 generate-models 别名查找** — 模型生成期间的别名解析已修正，使别名模型 ID 能解析到其规范条目。([#3870](https://github.com/diegosouzapw/OmniRoute/pull/3870) — 感谢 @YunyunZhai) +- **fix(combo): 保护候选池防止空数组** — Combo 候选池选择在池解析为空数组时不再抛出异常。([#3871](https://github.com/diegosouzapw/OmniRoute/pull/3871) — 感谢 @YunyunZhai) + +### 🔒 安全与加固 + +- **fix(security): 升级 form-data + vite（2 个 HIGH），加固工作流模板注入并白名单守卫 `workflow_run`** — 两个 HIGH Dependabot 建议（`表单-data`、`vite`）已升级；GitHub Actions 工作流针对 `${{ }}` 模板注入进行了加固（不受信任的值现在通过 `env:` 传递）；受保护的 `workflow_run` 触发器已加入白名单。([#3949](https://github.com/diegosouzapw/OmniRoute/pull/3949) — 感谢 @diegosouzapw) + +### 🧹 内部 / 质量 / 文档 + +- **fix(ci): 为 npm 发布任务授予 `contents: write` 权限以附加 SBOM** — v3.8.25 TokenPermissions 加固将 npm-publish `publish` 任务设为 `contents: read`，但其 "Attach SBOM to GitHub Release" 步骤 (`gh release upload`) 需要 `contents: write`，在 v3.8.25 发布中因 HTTP 403 失败（npm / GitHub Packages / opencode-插件 / Docker / Electron 均正常发布；仅 SBOM 附加失败 — v3.8.25 SBOM 已手动附加）。([#3874](https://github.com/diegosouzapw/OmniRoute/pull/3874) — 感谢 @diegosouzapw) +- **ci(quality): 使 zizmor / gitleaks / OSV 扫描器功能可用 + 冻结建议基线** — 供应链扫描器现在实际执行（正确的安装 + 调用），并冻结建议基线，使新发现作为差异呈现。([#3947](https://github.com/diegosouzapw/OmniRoute/pull/3947) — 感谢 @diegosouzapw) +- **ci(quality): 修复扫描器安装 + size-limit 预设，将 `codeqlAlerts` 从建议提升为阻断** — 修正了扫描器安装和 size-limit 预设，将 `codeqlAlerts` 从建议提升为阻断。([#3945](https://github.com/diegosouzapw/OmniRoute/pull/3945) — 感谢 @diegosouzapw) +- **ci(quality): 接入 Stryker 变异测试（建议，每夜运行）** — Stryker 变异测试每夜运行（建议）— Quality Gates Fase 7 · Task 11。([#3898](https://github.com/diegosouzapw/OmniRoute/pull/3898) — 感谢 @diegosouzapw) +- **ci(quality): 冻结每个模块的覆盖率底线 + 接入 require-tighten（建议）** — 每个模块的覆盖率底线已冻结，建议的 "require-tighten" 检查标记低于底线的模块。([#3901](https://github.com/diegosouzapw/OmniRoute/pull/3901) — 感谢 @diegosouzapw) +- **ci(quality): 在 `check-known-symbols` 上强制执行过期白名单检查** — 过期的白名单条目（抑制不再存在的符号）现在使门控失败 — Fase 6A.3 跟进。([#3899](https://github.com/diegosouzapw/OmniRoute/pull/3899) — 感谢 @diegosouzapw) +- **test(ci): 通过每次测试重新播种 + 真实重置来消除管线载荷测试的不稳定性** — 管线载荷测试套件现在每次测试重新播种并执行真实的缓存重置，消除了跨测试顺序的不稳定性。([#3893](https://github.com/diegosouzapw/OmniRoute/pull/3893) — 感谢 @diegosouzapw) +- **fix(ci): 从 nightly-llm-security 中移除任务级 `if` 中的 `secrets` 引用** — 在任务级 `if` 中引用 `secrets` 导致推送时出现 `startup_failure`；门控已移动使工作流正常启动。([#3892](https://github.com/diegosouzapw/OmniRoute/pull/3892) — 感谢 @diegosouzapw) +- **test: 在 #3907 源端回退后将 runtime-timeouts keepAlive 基线调整为 4000** — keepAlive 断言在 #3907 源端回退后已与源值 (4000) 重新对齐。([#3933](https://github.com/diegosouzapw/OmniRoute/pull/3933) — 感谢 @diegosouzapw) +- **chore(repo): 将质量门控状态嵌套到 `config/quality` 下，清理仓库根目录** — 基线/白名单/指标移至 `配置/quality/` 下，减少根目录跟踪文件数量。([#3896](https://github.com/diegosouzapw/OmniRoute/pull/3896) — 感谢 @diegosouzapw) +- **docs: 将服务商计数刷新为 226 + 重新生成 `PROVIDER_REFERENCE.md`** — README 中声明了过时的 `177 服务商`；规范生成器 (`scripts/docs/gen-服务商-reference.ts`) 现在报告 **226 个唯一服务商 ID**，因此 README 徽章/锚点和生成的服务商参考已同步。同时添加了文档审计/同步报告。（感谢 @diegosouzapw） +- **docs: 将所有文档同步到 v3.8.24 + 计数守卫和 wiki/prose CI** — 完整文档同步，包含严格的服务商/语言包计数守卫以及 Vale / markdownlint prose CI。([#3804](https://github.com/diegosouzapw/OmniRoute/pull/3804) — 感谢 @diegosouzapw) +- **docs: 重新生成过时的计数为规范值** — 226 个服务商 / 87 个 MCP 工具 / 15 个策略 / 42 个语言。([#3904](https://github.com/diegosouzapw/OmniRoute/pull/3904) — 感谢 @diegosouzapw) +- **docs(quality): 修正过时的门控计数 + 添加可选的 agent-lsp 脚手架** — ([#3902](https://github.com/diegosouzapw/OmniRoute/pull/3902) — 感谢 @diegosouzapw) +- **docs(mcp): 修正 MCP 工具清单图表源 + 文本为 87 个工具** — ([#3909](https://github.com/diegosouzapw/OmniRoute/pull/3909) — 感谢 @diegosouzapw) +- **docs: 更新压缩章节为 9 引擎多层堆叠** — ([#3894](https://github.com/diegosouzapw/OmniRoute/pull/3894) — 感谢 @diegosouzapw) +- **ci(docs): 自动化 GitHub wiki 同步（添加缺失页面 + 覆盖计数）** — ([#3900](https://github.com/diegosouzapw/OmniRoute/pull/3900) — 感谢 @diegosouzapw) +- **docs: 要求每个开发任务使用独立的 git worktree + 分支（硬规则 #19）** — 在共享检出事故后，编撰了 worktree 隔离规则。([#3939](https://github.com/diegosouzapw/OmniRoute/pull/3939) — 感谢 @diegosouzapw) +- **fix(docs): 添加 MDX frontmatter 到 `DOCUMENTATION_AUDIT_REPORT` 使 fumadocs 构建通过** — 审计报告缺少 MDX 页面所需的 `title:` frontmatter。（感谢 @diegosouzapw） --- @@ -1181,59 +1181,59 @@ _See English CHANGELOG for v3.8.32 details._ ### ✨ 新功能 -- **feat(compression): pluggable compression engines + async pipeline + Compression Studios** — a new prompt-compression subsystem with selectable engines (Lite / Aggressive / Ultra), an asynchronous compression pipeline wired into the chat core, and "Compression Studios" tooling for inspecting and tuning compression. ([#3848](https://github.com/diegosouzapw/OmniRoute/pull/3848)) -- **feat(compression-ui): unified compression configuration UI** — a Compression Hub with per-engine pages (Lite / Aggressive / Ultra), a combos editor, a dedicated sidebar entry, and live-WS default-on. ([#3860](https://github.com/diegosouzapw/OmniRoute/pull/3860)) -- **feat(security): prompt-injection guard across every LLM route + red-team suite** — the prompt-injection guard now runs on all LLM routes (chat, responses, embeddings, images, audio, rerank, search, moderations, videos, music) with a shared input sanitizer and a promptfoo-based red-team suite (Quality Gates Fase 8 · Bloco D). ([#3857](https://github.com/diegosouzapw/OmniRoute/pull/3857)) -- **feat(kiro): live per-account model discovery** — Kiro now discovers each account/tier's entitled models via CodeWhisperer `ListAvailableModels` (region-matched, with a static-catalog fallback). ([#3836](https://github.com/diegosouzapw/OmniRoute/pull/3836) — thanks @artickc) -- **feat(gemini/vertex): surface Veo video models in dynamic discovery** — Veo video models (`predictLongRunning`) now appear in Gemini/Vertex dynamic model discovery. ([#3839](https://github.com/diegosouzapw/OmniRoute/pull/3839) — thanks @artickc) -- **feat(mimocode): per-account proxy for multi-account round-robin** — each mimocode account can route through its own proxy (resolved per account by fingerprint via `runWithProxyContext`), with a "Distribute proxies" UI helper. ([#3837](https://github.com/diegosouzapw/OmniRoute/pull/3837) — thanks @pizzav-xyz) -- **feat(intelligence): expose Arena ELO sync as a feature flag** — the LM Arena ELO leaderboard sync is now toggleable (`ARENA_ELO_SYNC_ENABLED`, DB-override + env fallback). ([#3821](https://github.com/diegosouzapw/OmniRoute/pull/3821) — thanks @rdself) - -### 🐛 Fixed - -- **test(oauth): prove refresh_token preservation for the real gemini-cli / antigravity dispatch** — the #3679/#3766 regression test used a synthetic provider that routes through the generic `tokenUrl` path, so the fix was never proven for the actual Google-family providers, which dispatch through `refreshGoogleToken()` against the hardcoded `OAUTH_ENDPOINTS.google.token`. Added a test that drives `checkConnection` through the real `gemini-cli`/`antigravity` path (redirecting the Google token endpoint to a local server returning `invalid_grant`) and asserts the `refresh_token` is preserved (not nulled) — confirming these connections are not spuriously destroyed on a failed refresh. ([#3850](https://github.com/diegosouzapw/OmniRoute/issues/3850) — thanks @3xa228148) -- **fix(oauth): clear setup message for GitLab Duo instead of "Internal server error"** — adding a GitLab Duo connection without a registered OAuth client returned an opaque `Internal server error` at the Add Connection step. `buildAuthUrl` **threw** when `GITLAB_DUO_OAUTH_CLIENT_ID` was missing, and the route swallowed it into a generic 500. It now returns `null` (mirroring the Qoder provider) and the authorize route surfaces an actionable message: register an OAuth app at `https://gitlab.com/-/profile/applications` with redirect URI `http://localhost:20128/callback` and scopes `ai_features read_user`, then set `GITLAB_DUO_OAUTH_CLIENT_ID`. ([#3861](https://github.com/diegosouzapw/OmniRoute/issues/3861) — thanks @sidinsearch) -- **fix(db): persist the "Keep latest backups" retention setting** — changing the backup-retention count in Settings → Database backup retention had no effect: it always snapped back to 20 on refresh (and editing `.env` post-start was ignored too, since `process.env` isn't reloaded). `getDbBackupMaxFiles()` only read the `DB_BACKUP_MAX_FILES` env var — there was no setter and no persisted value. The value now round-trips through a dedicated `key_value` store (`getDbBackupMaxFiles` precedence: env override → persisted UI value → default 20), and the "Clean old backups" action persists the chosen count. Existing installs keep the historical default of 20 until explicitly changed. ([#3834](https://github.com/diegosouzapw/OmniRoute/issues/3834) — thanks @netstratego) -- **fix(sse): clamp Gemini thinking budget to the model's real cap (`reasoning_effort`/`effort=high` 400)** — translating OpenAI `reasoning_effort=high` (and Claude-Code `output_config.effort=high`) to a Gemini target sent a hardcoded `thinkingBudget: 32768`, which exceeds Flash-tier Gemini's real max of 24576 → upstream HTTP 400 (the `thinkingLevel=high` path already used 24576 and worked on the same model). `gemini-2.5-flash` now declares its real `thinkingBudgetCap` (24576) so the existing `capThinkingBudget()` chokepoint actually clamps, and the Claude→Gemini `output_config.effort` path — which previously sent the raw value with no cap at all — now routes through the same clamp (pro-tier, real cap 32768, is left untouched). ([#3842](https://github.com/diegosouzapw/OmniRoute/issues/3842) — thanks @andrea-kingautomation) -- **fix(intelligence): run pricing + models.dev sync from the live startup path** — like the Arena ELO sync (v3.8.24), the external **pricing sync** (`PRICING_SYNC_ENABLED`) and the **models.dev capability sync** (Settings → AI toggle) were only initialized from `server-init.ts`, which the Next standalone runtime never executes — and models.dev had no caller at all. Their toggles were inert in production. Both are now initialized from `instrumentation-node.ts` (self-gated, opt-in preserved, non-blocking, never fatal). (thanks @diegosouzapw) -- **test(proxy): guard the per-connection 'direct' bypass over a global proxy + clearer label** — the per-connection "Proxy Off" toggle (`proxyEnabled: false`) already overrides a configured **global** proxy (`resolveProxyForConnection` short-circuits to `level: "direct"` before the global step). Added an explicit regression test proving the bypass beats a global assignment (and round-trips on re-enable), and relabeled the UI to "Direct (bypass proxy)" so operators recognize it. Closes the verification gap in [#2996](https://github.com/diegosouzapw/OmniRoute/issues/2996). (thanks @diegosouzapw) -- **feat(connections): per-connection "disable cooldown" opt-out** — a connection can now opt out of the transient cooldown (`providerSpecificData.disableCooling`, with a toggle in the Edit Connection modal). When set, a recoverable failure still records the error/backoff but does **not** take the connection out of rotation, so it stays eligible for selection — useful for a primary key you never want parked on a blip. Terminal states (banned / expired / credits_exhausted) still apply. ([#2997](https://github.com/diegosouzapw/OmniRoute/issues/2997) — thanks @diegosouzapw) -- **fix(combo): restore sessionless combo stickiness + reasoning-aware readiness (504 / TPS regression after v3.8.14)** — #3399 (v3.8.16) replaced the ``-tag combo pinning with a server-side context-cache pin gated on a client `sessionId`. Clients that send no session id (most OpenAI-compatible tools) lost combo stickiness, so combos re-ran strategy selection every turn → upstream prompt-cache misses → cold high-reasoning starts (~78s) → intermittent `[504] Upstream request did not return response headers` + TPS collapse (only on combos). The pin now falls back to a stable per-conversation fingerprint (`extractSessionAffinityKey(body)`) when no session id is present — **only when `context_cache_protection` is on**, so #3399's anti-leak behaviour is preserved. Separately, the stream-readiness window now grants the +30s reasoning budget **unconditionally** for high-reasoning Codex GPT-5.x (small high-reasoning prompts were 504-ing at the 80s base regardless of stickiness). ([#3825](https://github.com/diegosouzapw/OmniRoute/issues/3825) — thanks @bypanghu) -- **test(combo): cover the `skipProviderBreaker` consumer gate** — the producer was tested but the consumer (whether a failed combo target trips the whole-provider circuit breaker) was not; the breaker decision is now an exported pure predicate (`shouldRecordProviderBreakerFailure`, behaviour-identical) with direct tests asserting a `connection_cooldown` 503 does not trip the breaker while a plain 503 does. Closes another deferred test gap from [#2743](https://github.com/diegosouzapw/OmniRoute/issues/2743). (thanks @diegosouzapw) -- **fix(providers): surface the real Devin error + correct the Windsurf auth instructions** — Devin chat returned a generic 502 "Invalid SSE response for non-streaming request" that swallowed the real cause (e.g. "Devin CLI not found"): an error-only SSE chunk (no `choices`) is now propagated with its sanitized message. The Windsurf "Visit windsurf.com/show-auth-token" instruction (the bare URL shows no token without an IDE-supplied `?state=`) now directs users to the `Windsurf: Provide Auth Token` command-palette flow. ([#3324](https://github.com/diegosouzapw/OmniRoute/issues/3324) — thanks @mikmaneggahommie) -- **fix(grok-web): clearer 403 message for anti-bot / IP-reputation blocks** — a Grok Web subscription validating from a flagged datacenter/VPS IP got a 403 that read like an invalid cookie, sending users to chase a cookie that was actually fine. A non-auth 403 (Cloudflare challenge / anti-bot body) now returns a message stating the cookie is likely OK and the block is IP-reputation-based — retry from a residential IP or configure a proxy (auth-shaped 403s keep the re-paste guidance). ([#3474](https://github.com/diegosouzapw/OmniRoute/issues/3474) — thanks @friedtofu1608) -- **fix(db): make the mass-pending-migrations safety threshold env-overridable** — restoring a backup DB from an older version could trip "Detected N pending migrations … threshold is 50" with no way to override the hardcoded `50`. The threshold is now configurable via `OMNIROUTE_MAX_PENDING_MIGRATIONS` (resolved at startup; `0` disables the check). ([#3416](https://github.com/diegosouzapw/OmniRoute/issues/3416) — thanks @samuraiIT) -- **test(proxy): cover the Vercel-relay `proxyFetch` path** — net-new tests for `buildVercelRelayHeaders` and the `vercel`-type relay short-circuit (`x-relay-target`/`-path`/`-auth`, TCP-skip, missing-auth fail-closed), closing one of the deferred test gaps tracked in [#2743](https://github.com/diegosouzapw/OmniRoute/issues/2743). (thanks @diegosouzapw) -- **fix(cli): surface `omniroute runtime repair` in the native-module error messages** — after a Node major upgrade, `better-sqlite3`'s prebuilt binary mismatches the ABI and the service can crash-loop; the error only mentioned `npm rebuild better-sqlite3` (which fails for global / no-toolchain installs). The startup + SQLite error hints now also point to the existing self-heal command `omniroute runtime repair` (rebuilds into a user-writable runtime), and a top-level `omniroute repair` alias was added. ([#3476](https://github.com/diegosouzapw/OmniRoute/issues/3476) — thanks @Rahulsharma0810) -- **fix(antigravity): per-request Pro-family upstream-id fallback chain (`gemini-3.1-pro-high` 400)** — Antigravity silently renamed the Gemini 3.1 Pro-high upstream id, so `gemini-3.1-pro-high` started returning HTTP 400 (while `-low` still worked) and the live id can't be determined statically (competitor proxies disagree). The executor now retries alternative ids on a 400 (`gemini-3.1-pro-high` → `gemini-pro-agent` → `gemini-3-pro-high`, analogous for pro-low), bounded and only on a 400, with zero extra cost on the happy path; the 1:1 tier-passthrough invariant is preserved (the chain is request-time, not a static alias remap). ([#3786](https://github.com/diegosouzapw/OmniRoute/issues/3786) — thanks @aliaksandrsen) -- **fix(sse): retry once on an early stream close (`STREAM_EARLY_EOF`) for single-model requests** — flaky OpenAI-compatible upstreams (e.g. NVIDIA NIM with minimax-m3 / qwen3.5 / glm-5.1) intermittently send HTTP 200 then close the SSE with zero useful frames, surfacing as a 502 "Stream ended before producing useful content". Only Antigravity got an early-close retry; every other provider returned the 502 immediately on the non-combo single-model path. A bounded one-retry (early-close only — not readiness-timeout — and without marking the account unavailable) now generalizes it. (The separate qwen-web validation SSRF part of the same report was already fixed in v3.8.24, [#3767](https://github.com/diegosouzapw/OmniRoute/pull/3767).) ([#3758](https://github.com/diegosouzapw/OmniRoute/issues/3758) — thanks @Svatosalav) -- **fix(models): preserve eye-hidden models across auto-sync / import** — hiding models via the visibility (eye) toggle to keep only a combo's models was undone on every model import or auto-sync, which re-showed all of them. The sync re-import treated "hidden" identically to "deleted" and dropped both; a distinct `isDeleted` marker now separates the trash/delete path (still dropped on re-import, #3199) from the eye toggle (preserved as listed-but-hidden), and eye-hidden models are no longer re-aliased into the routable catalog on sync. ([#3782](https://github.com/diegosouzapw/OmniRoute/issues/3782) — thanks @xenstar) -- **fix(providers): correct the lmarena cookie hint (`session` → `arena-auth-prod-v1`)** — the lmarena credential hint asked for a cookie named `session`, but lmarena.ai's real auth cookie is `arena-auth-prod-v1`, so users who pasted only `session=…` hit validation failures. The credential name, placeholder and storage keys now use the correct name (the legacy `session` key is retained for back-compat with already-saved credentials). ([#3810](https://github.com/diegosouzapw/OmniRoute/issues/3810) — thanks @xspylol) -- **fix(reasoning): normalize OpenAI-compatible `max` effort to `xhigh` by default** — OpenAI-compatible providers do not accept literal `max`, but some upstreams (for example DeepSeek through OpenRouter) support `xhigh`; `max` now maps to `xhigh` unless the target model explicitly opts out of `xhigh`, with Claude alias variants still honoring the canonical Claude opt-out list. ([#3826](https://github.com/diegosouzapw/OmniRoute/pull/3826) — thanks @rdself) -- **fix(combo): return the replay response on the round-robin streaming path** — a round-robin combo with a streaming target returned a body already locked by the readiness peek, surfacing as a 500 "ReadableStream is locked"; the round-robin path now returns the replay clone like the priority path does. ([#3811](https://github.com/diegosouzapw/OmniRoute/pull/3811) — thanks @0xtbug) -- **fix(claude): strip the reasoning-effort suffix from Claude model ids** — Claude ids carrying an effort suffix (`…-low` … `…-max`) 404'd upstream and tripped the circuit breaker into a misleading "rate-limited" state; the suffix is now stripped before dispatch. ([#3807](https://github.com/diegosouzapw/OmniRoute/pull/3807) — thanks @zhiru) -- **fix(sse): flush routed SSE chunks promptly (ping/zombie readiness filter)** — combo stream-readiness now filters ping/zombie frames so routed SSE chunks stream out without waiting on the readiness window. ([#3759](https://github.com/diegosouzapw/OmniRoute/pull/3759) — thanks @rdself) -- **fix(models): don't auto-hide transient (rate-limited / timeout) failures on Test All** — a parallel Test All across many models could rate-limit an account and auto-hide every model that 429'd / timed out (dropping them from `/v1/models`); transient failures now surface an error state but stay visible. ([#3849](https://github.com/diegosouzapw/OmniRoute/pull/3849) — thanks @lukmanc405) -- **fix(quota): surface OpenCode Go's missing quota-API as a latched diagnostic** — OpenCode Go keys whose quota endpoints return 404/401 no longer hammer the dead endpoints; the gap is latched with a clear message and an `OMNIROUTE_OPENCODE_GO_QUOTA_URL` override hint. ([#3838](https://github.com/diegosouzapw/OmniRoute/pull/3838) — thanks @adivekar-utexas) -- **fix(pricing): add the missing Kiro model pricing rows** — Kiro models the registry serves (e.g. `claude-sonnet-4.6`) had no pricing row and reported $0.00; the rows were added. ([#3835](https://github.com/diegosouzapw/OmniRoute/pull/3835) — thanks @artickc) -- **fix(ui): render country flags via flagcdn SVGs for Windows compatibility** — Windows doesn't render regional-indicator flag emoji; flags now use flagcdn SVGs with an emoji fallback. ([#3814](https://github.com/diegosouzapw/OmniRoute/pull/3814) — thanks @rafacpti23) -- **fix(ui): expand the request log table with a vertical resize handle** — the request log table now shows ~10 rows and can be resized vertically. ([#3820](https://github.com/diegosouzapw/OmniRoute/pull/3820) — thanks @rafacpti23) -- **fix(i18n): translate the missing `embeddedServices` keys across 37 locales** — the `embeddedServices` strings showed `__MISSING__` in 37 locales; they are now translated. ([#3819](https://github.com/diegosouzapw/OmniRoute/pull/3819) — thanks @rafacpti23) - -### 🔒 安全 & Hardening - -- **fix(security): CCR cross-tenant IDOR — per-principal scope store + bounded memory** — the compression CCR scope store was shared across principals, allowing cross-tenant reads; it is now scoped per-principal with bounded memory. ([#3859](https://github.com/diegosouzapw/OmniRoute/pull/3859)) -- **feat(supply-chain): build provenance, SBOM, Trivy scan & OpenSSF Scorecard (advisory)** — added npm build provenance, a CycloneDX SBOM, Trivy image scanning, and an OpenSSF Scorecard workflow (Quality Gates Fase 8 · Bloco A, advisory). ([#3824](https://github.com/diegosouzapw/OmniRoute/pull/3824)) - -### 🧹 Internal / Quality / Docs - -- **Consolidate the email-privacy control into Settings → Appearance** — the per-page email-privacy toggles were replaced by a single global switch. ([#3822](https://github.com/diegosouzapw/OmniRoute/pull/3822) — thanks @rdself) -- **docs(ui): clarify the routing-settings copy (strategy sync + sticky limit)** — ([#3843](https://github.com/diegosouzapw/OmniRoute/pull/3843) — thanks @adivekar-utexas) -- **Quality Gates — Fase 7 & 8** — promoted the dead-code / cognitive-complexity / type-coverage ratchets to blocking, installed advisory CI scanners (gitleaks / osv / actionlint / zizmor), and added property + golden + SSE-correctness tests and a runtime-resilience (chaos / heap-growth / k6 soak) suite. ([#3809](https://github.com/diegosouzapw/OmniRoute/pull/3809), [#3858](https://github.com/diegosouzapw/OmniRoute/pull/3858), [#3808](https://github.com/diegosouzapw/OmniRoute/pull/3808), [#3854](https://github.com/diegosouzapw/OmniRoute/pull/3854)) -- **fix(docs): add MDX frontmatter to `SUPPLY_CHAIN.md`** — the new security doc lacked the `title:` frontmatter that MDX pages require, which broke the production Build + Docker Hub publish; the frontmatter was added. ([#3864](https://github.com/diegosouzapw/OmniRoute/pull/3864)) -- **chore(deps): bump `aquasecurity/trivy-action` 0.28.0 → 0.36.0** ([#3862](https://github.com/diegosouzapw/OmniRoute/pull/3862)) -- **chore(quality): reconcile the file-size ratchet baseline for Prettier-inflated v3.8.25 fixes + `chat.ts` growth** — the per-file size baseline was re-frozen to absorb the formatting/line-count growth from this cycle's chat-core and combo fixes (manual edits, never an automatic upward ratchet). ([#3823](https://github.com/diegosouzapw/OmniRoute/pull/3823), [#3833](https://github.com/diegosouzapw/OmniRoute/pull/3833) — thanks @diegosouzapw) -- **test(suite): green the unit suite at release time — align stale tests to this cycle's intended behavior + de-flake two new suites** — release-gate housekeeping: updated tests that lagged behind intended behavior changes (OpenCode Go latched quota message #3838, the email-privacy control consolidated into Settings #3822, SOCKS5 default-on proxy-type message, the `[id]` provider-detail strangler-fig decomposition #3501, Vertex Express-mode keys, Antigravity discovery using a current user-callable model id) and the same-provider 503 fall-through resilience test; de-flaked the compression benchmark reproducibility test (sequential passes) and the ServiceSupervisor crash test (poll instead of fixed sleep). No production code changed. Also documented `OMNIROUTE_MAX_PENDING_MIGRATIONS` (#3416) in `.env.example` + `ENVIRONMENT.md`. (thanks @diegosouzapw) +- **feat(compression): 可插拔压缩引擎 + 异步管线 + Compression Studios** — 一个全新的提示-压缩子系统，支持可选择的引擎（Lite / Aggressive / Ultra）、接入聊天核心的异步压缩管线，以及用于检查和调优压缩的 "Compression Studios" 工具。 ([#3848](https://github.com/diegosouzapw/OmniRoute/pull/3848)) +- **feat(compression-ui): 统一压缩配置界面** — 新增 Compression Hub，包含每个引擎的子页面（Lite / Aggressive / Ultra）、组合编辑器、专用侧边栏入口以及默认开启的实时 WebSocket。 ([#3860](https://github.com/diegosouzapw/OmniRoute/pull/3860)) +- **feat(security): 覆盖所有 LLM 路由的提示注入守卫 + 红队测试套件** — 提示注入守卫现已覆盖所有 LLM 路由（chat、responses、embeddings、images、audio、rerank、搜索、moderations、videos、music），配备共享输入清洗器以及基于 promptfoo 的红队测试套件（Quality Gates Fase 8 · Bloco D）。 ([#3857](https://github.com/diegosouzapw/OmniRoute/pull/3857)) +- **feat(kiro): 每个账户的实时模型发现** — Kiro 现通过 CodeWhisperer `ListAvailableModels`（按区域匹配，带静态目录容灾）发现每个账户/层级的授权模型。 ([#3836](https://github.com/diegosouzapw/OmniRoute/pull/3836) — 感谢 @artickc) +- **feat(gemini/vertex): 在动态发现中展示 Veo 视频模型** — Veo 视频模型（`predictLongRunning`）现出现在 Gemini/Vertex 动态模型发现中。 ([#3839](https://github.com/diegosouzapw/OmniRoute/pull/3839) — 感谢 @artickc) +- **feat(mimocode): 多账户轮询的每账户代理** — 每个 mimocode 账户可通过其专属代理进行路由（按账户指纹通过 `runWithProxyContext` 解析），并配备 "分发代理" 界面辅助工具。 ([#3837](https://github.com/diegosouzapw/OmniRoute/pull/3837) — 感谢 @pizzav-xyz) +- **feat(intelligence): 将 Arena ELO 同步作为功能开关暴露** — LM Arena ELO 排行榜同步现已可切换（`ARENA_ELO_SYNC_ENABLED`，DB 覆盖 + 环境变量容灾）。 ([#3821](https://github.com/diegosouzapw/OmniRoute/pull/3821) — 感谢 @rdself) + +### 🐛 问题修复 + +- **test(oauth): 验证真实 gemini-cli / antigravity 分发路径的 refresh_token 保留** — #3679/#3766 回归测试使用了一个合成服务商，该服务商通过通用的 `tokenUrl` 路径进行路由，因此该修复从未针对实际 Google 系列服务商进行过验证——后者通过 `refreshGoogleToken()` 针对硬编码的 `OAUTH_ENDPOINTS.google.token` 进行分发。新增一个测试，通过真实的 `gemini-cli`/`antigravity` 路径驱动 `checkConnection`（将 Google 令牌端点重定向到返回 `invalid_grant` 的本地服务器），并断言 `refresh_token` 被保留（而非置空）——从而确认这些连接不会在刷新失败时被错误地销毁。 ([#3850](https://github.com/diegosouzapw/OmniRoute/issues/3850) — 感谢 @3xa228148) +- **fix(oauth): 为 GitLab Duo 提供清晰的设置提示，而非 "Internal server error"** — 在没有注册 OAuth 客户端的情况下添加 GitLab Duo 连接，在添加连接步骤中会返回一个含糊的 `Internal server 错误`。当 `GITLAB_DUO_OAUTH_CLIENT_ID` 缺失时，`buildAuthUrl` **抛出异常**，路由将其吞并为通用 500 错误。现返回 `null`（与 Qoder 服务商行为一致），授权路由会显示可操作的提示：在 `https://gitlab.com/-/profile/applications` 注册 OAuth 应用，重定向 URI 为 `http://localhost:20128/callback`，权限范围为 `ai_features read_user`，然后设置 `GITLAB_DUO_OAUTH_CLIENT_ID`。 ([#3861](https://github.com/diegosouzapw/OmniRoute/issues/3861) — 感谢 @sidinsearch) +- **fix(db): 持久化"保留最近备份"设置** — 在设置 → 数据库备份保留中更改备份保留数量无效：刷新后总是跳回 20（并且启动后编辑 `.env` 也被忽略，因为 `process.env` 不会被重新加载）。`getDbBackupMaxFiles()` 仅读取 `DB_BACKUP_MAX_FILES` 环境变量——没有 setter 也没有持久化值。该值现通过专用的 `key_value` 存储进行往返（`getDbBackupMaxFiles` 优先级：环境变量覆盖 → 持久化的界面值 → 默认 20），并且"清理旧备份"操作会持久化所选数量。现有安装保留历史默认值 20，直到显式更改。 ([#3834](https://github.com/diegosouzapw/OmniRoute/issues/3834) — 感谢 @netstratego) +- **fix(sse): 将 Gemini 思考预算限制在模型真实上限内（`reasoning_effort`/`effort=high` 400）** — 将 OpenAI `reasoning_effort=high`（以及 Claude-Code `output_config.effort=high`）翻译到 Gemini 目标时，发送了硬编码的 `thinkingBudget: 32768`，这超过了 Flash 级别 Gemini 的真实上限 24576 → 上游 HTTP 400（`thinkingLevel=high` 路径已经使用 24576 并且在相同模型上正常工作）。`gemini-2.5-flash` 现声明其真实 `thinkingBudgetCap`（24576），使现有的 `capThinkingBudget()` 截断点真正生效，并且 Claude→Gemini 的 `output_config.effort` 路径——此前直接发送原始值完全没有截断——现通过相同的截断点（pro 级别，真实上限 32768，保持不变）。 ([#3842](https://github.com/diegosouzapw/OmniRoute/issues/3842) — 感谢 @andrea-kingautomation) +- **fix(intelligence): 从实时启动路径运行定价 + models.dev 同步** — 与 Arena ELO 同步（v3.8.24）类似，外部**定价同步**（`PRICING_SYNC_ENABLED`）和**模型.dev 能力同步**（设置 → AI 开关）仅从 `server-init.ts` 初始化，而 Next 独立运行时永远不会执行该文件——并且模型.dev 完全没有调用者。它们的开关在生产环境中无效。两者现从 `instrumentation-node.ts` 初始化（自门控、保留可选择性、非阻塞、永不致命）。(感谢 @diegosouzapw) +- **test(proxy): 保护每连接"直连"绕过全局代理 + 更清晰的标签** — 每连接"代理关闭"开关（`proxyEnabled: false`）已经覆盖了已配置的**全局**代理（`resolveProxyForConnection` 在全局步骤之前短路到 `level: "direct"`）。新增一个显式回归测试，证明该绕过优先于全局分配（并在重新启用时可往返），并将界面标签改为"直连（绕过代理）"，以便运维人员识别。关闭 [#2996](https://github.com/diegosouzapw/OmniRoute/issues/2996) 中的验证缺口。(感谢 @diegosouzapw) +- **feat(connections): 每连接"禁用冷却"退出机制** — 连接现可选择退出瞬时冷却（`providerSpecificData.disableCooling`，在编辑连接弹窗中带开关）。设置后，可恢复的故障仍会记录错误/退避，但**不会**将该连接移出轮转，因此它仍然有资格被选中——适用于你永远不希望因短暂波动而被搁置的主密钥。终端状态（封禁 / 过期 / 额度耗尽）仍然生效。 ([#2997](https://github.com/diegosouzapw/OmniRoute/issues/2997) — 感谢 @diegosouzapw) +- **fix(combo): 恢复无会话组合粘性 + 推理感知就绪（v3.8.14 后的 504 / TPS 回归）** — #3399（v3.8.16）将 `` 标签组合固定替换为基于客户端 `sessionId` 门控的服务端上下文缓存固定。不发送会话 ID 的客户端（大多数 OpenAI 兼容工具）丢失了组合粘性，导致组合每轮都重新运行策略选择 → 上游提示缓存未命中 → 冷高推理启动（~78s）→ 间歇性 `[504] Upstream request did not return response headers` + TPS 崩溃（仅发生在组合上）。固定现在在没有会话 ID 时回退到稳定的每对话指纹（`extractSessionAffinityKey(body)`）——**仅当 `context_cache_protection` 开启时**，因此 #3399 的防泄漏行为得以保留。另外，流就绪窗口现在**无条件**为高推理 Codex GPT-5.x 授予 +30s 推理预算（小型高推理提示无论粘性如何，在 80s 基准下都会 504）。 ([#3825](https://github.com/diegosouzapw/OmniRoute/issues/3825) — 感谢 @bypanghu) +- **test(combo): 覆盖 `skipProviderBreaker` 消费者门控** — 生产者已测试，但消费者（失败的 Combo 目标是否会触发全服务商熔断器）未测试；熔断器决策现为导出的纯谓词（`shouldRecordProviderBreakerFailure`，行为一致），并有直接测试断言 `connection_cooldown` 503 不会触发熔断器，而普通 503 会。关闭 [#2743](https://github.com/diegosouzapw/OmniRoute/issues/2743) 中的另一个延期测试缺口。(感谢 @diegosouzapw) +- **fix(providers): 显示真实的 Devin 错误 + 修正 Windsurf 认证说明** — Devin 聊天返回通用 502 "Invalid SSE response for non-streaming request"，吞没了真实原因（例如"Devin CLI not found"）：仅含错误的 SSE 块（无 `choices`）现会传播其经过清洗的消息。Windsurf "Visit windsurf.com/show-auth-token" 说明（裸 URL 在没有 IDE 提供的 `?state=` 时不会显示令牌）现引导用户使用 `Windsurf: Provide Auth Token` 命令面板流程。 ([#3324](https://github.com/diegosouzapw/OmniRoute/issues/3324) — 感谢 @mikmaneggahommie) +- **fix(grok-web): 针对反机器人 / IP 信誉拦截的更清晰 403 消息** — 从被标记的数据中心/VPS IP 验证 Grok Web 订阅时收到的 403 看起来像无效 cookie，导致用户去追查一个实际上正常的 cookie。非认证 403（Cloudflare 挑战 / 反机器人响应体）现返回消息说明 cookie 可能正常，拦截是基于 IP 信誉的——请从住宅 IP 重试或配置代理（认证类型的 403 保留重新粘贴指引）。 ([#3474](https://github.com/diegosouzapw/OmniRoute/issues/3474) — 感谢 @friedtofu1608) +- **fix(db): 使大量待处理迁移安全阈值可通过环境变量覆盖** — 从旧版本恢复备份数据库可能触发"检测到 N 个待处理迁移 … 阈值为 50"，且无法覆盖硬编码的 `50`。该阈值现可通过 `OMNIROUTE_MAX_PENDING_MIGRATIONS` 配置（启动时解析；`0` 禁用检查）。 ([#3416](https://github.com/diegosouzapw/OmniRoute/issues/3416) — 感谢 @samuraiIT) +- **test(proxy): 覆盖 Vercel 中继 `proxyFetch` 路径** — 为 `buildVercelRelayHeaders` 和 `vercel` 类型中继短路（`x-中继-target`/`-path`/`-认证`、TCP 跳过、缺失认证 fail-closed）新增测试，关闭 [#2743](https://github.com/diegosouzapw/OmniRoute/issues/2743) 中跟踪的延期测试缺口之一。(感谢 @diegosouzapw) +- **fix(cli): 在原生模块错误消息中提示 `omniroute runtime repair`** — Node 主版本升级后，`better-sqlite3` 的预编译二进制与 ABI 不匹配，服务可能崩溃循环；错误仅提示 `npm rebuild better-sqlite3`（对全局/无工具链安装无效）。启动和 SQLite 错误提示现也指向已有的自修复命令 `omniroute runtime repair`（重建到用户可写的运行时），并添加了顶层 `omniroute repair` 别名。 ([#3476](https://github.com/diegosouzapw/OmniRoute/issues/3476) — 感谢 @Rahulsharma0810) +- **fix(antigravity): 每请求 Pro 系列上游 ID 容灾链（`gemini-3.1-pro-high` 400）** — Antigravity 静默重命名了 Gemini 3.1 Pro-high 上游 ID，导致 `gemini-3.1-pro-high` 开始返回 HTTP 400（而 `-low` 仍然正常），且实时 ID 无法静态确定（竞争对手代理意见不一）。执行器现对 400 重试备用 ID（`gemini-3.1-pro-high` → `gemini-pro-agent` → `gemini-3-pro-high`，pro-low 同理），有限且仅在 400 时触发，正常路径零额外开销；1:1 层级直通不变量得以保留（链是请求时的，而非静态别名映射）。 ([#3786](https://github.com/diegosouzapw/OmniRoute/issues/3786) — 感谢 @aliaksandrsen) +- **fix(sse): 对单模型请求的早期流关闭（`STREAM_EARLY_EOF`）重试一次** — 不稳定的 OpenAI 兼容上游（例如 NVIDIA NIM 搭配 minimax-m3 / qwen3.5 / glm-5.1）间歇性发送 HTTP 200 然后以零有效帧关闭 SSE，表现为 502 "Stream ended before producing useful content"。此前只有 Antigravity 获得了早期关闭重试；所有其他服务商在非 Combo 单模型路径上立即返回 502。现通过有限的一次重试（仅早期关闭——非就绪超时——且不标记账户不可用）进行泛化。（同一报告中独立的 qwen-web 验证 SSRF 部分已在 v3.8.24 中修复，[#3767](https://github.com/diegosouzapw/OmniRoute/pull/3767)。） ([#3758](https://github.com/diegosouzapw/OmniRoute/issues/3758) — 感谢 @Svatosalav) +- **fix(models): 在自动同步/导入中保留已隐藏模型** — 通过可见性（眼睛）开关隐藏模型以仅保留 Combo 模型的操作，在每次模型导入或自动同步时被撤销，所有模型重新显示。同步重新导入将"隐藏"等同于"删除"并丢弃两者；现通过独立的 `isDeleted` 标记将垃圾/删除路径（重新导入时仍丢弃，#3199）与眼睛开关（保留为已列出但隐藏）区分开来，且已隐藏模型不再在同步时重新别名为可路由目录。 ([#3782](https://github.com/diegosouzapw/OmniRoute/issues/3782) — 感谢 @xenstar) +- **fix(providers): 修正 lmarena cookie 提示（`session` → `arena-auth-prod-v1`）** — lmarena 凭证提示要求名为 `会话` 的 cookie，但 lmarena.ai 的真实认证 cookie 是 `arena-认证-prod-v1`，因此仅粘贴 `会话=…` 的用户会遇到校验失败。凭证名称、占位符和存储密钥现已使用正确的名称（保留旧版 `会话` 密钥以向后兼容已保存的凭证）。 ([#3810](https://github.com/diegosouzapw/OmniRoute/issues/3810) — 感谢 @xspylol) +- **fix(reasoning): 默认将 OpenAI 兼容的 `max` 强度标准化为 `xhigh`** — OpenAI 兼容服务商不接受字面量 `max`，但部分上游（例如通过 OpenRouter 的 DeepSeek）支持 `xhigh`；`max` 现映射为 `xhigh`，除非目标模型明确退出 `xhigh`，Claude 别名变体仍然遵循规范的 Claude 退出列表。 ([#3826](https://github.com/diegosouzapw/OmniRoute/pull/3826) — 感谢 @rdself) +- **fix(combo): 在轮询流式路径上返回重放响应** — 带有流式传输目标的轮询 Combo 返回了一个已被就绪探测锁定的响应体，表现为 500 "ReadableStream is locked"；轮询路径现像优先级路径一样返回重放克隆。 ([#3811](https://github.com/diegosouzapw/OmniRoute/pull/3811) — 感谢 @0xtbug) +- **fix(claude): 从 Claude 模型 ID 中去除推理强度后缀** — 带有强度后缀的 Claude ID（`…-low` … `…-max`）在上游返回 404 并触发熔断器进入误导性的"速率受限"状态；后缀现已在分发前去除。 ([#3807](https://github.com/diegosouzapw/OmniRoute/pull/3807) — 感谢 @zhiru) +- **fix(sse): 及时刷新已路由的 SSE 块（ping/僵尸就绪过滤器）** — Combo 流就绪现过滤 ping/僵尸帧，使已路由的 SSE 块无需等待就绪窗口即可流出。 ([#3759](https://github.com/diegosouzapw/OmniRoute/pull/3759) — 感谢 @rdself) +- **fix(models): 不要自动隐藏 Test All 中的瞬时（速率限制/超时）失败** — 跨多个模型的并行 Test All 可能对账户造成速率限制，并自动隐藏每个 429/超时的模型（将其从 `/v1/模型` 中移除）；瞬时失败现显示错误状态但保持可见。 ([#3849](https://github.com/diegosouzapw/OmniRoute/pull/3849) — 感谢 @lukmanc405) +- **fix(quota): 将 OpenCode Go 缺失的配额 API 显示为锁定诊断** — 配额端点返回 404/401 的 OpenCode Go 密钥不再反复请求已失效的端点；该缺口被锁定并附带清晰消息和 `OMNIROUTE_OPENCODE_GO_QUOTA_URL` 覆盖提示。 ([#3838](https://github.com/diegosouzapw/OmniRoute/pull/3838) — 感谢 @adivekar-utexas) +- **fix(pricing): 添加缺失的 Kiro 模型定价行** — 注册表提供的 Kiro 模型（例如 `claude-sonnet-4.6`）没有定价行并报告 $0.00；已添加相应行。 ([#3835](https://github.com/diegosouzapw/OmniRoute/pull/3835) — 感谢 @artickc) +- **fix(ui): 通过 flagcdn SVG 渲染国旗以兼容 Windows** — Windows 不渲染区域指示符国旗 emoji；国旗现使用 flagcdn SVG 并附带 emoji 回退。 ([#3814](https://github.com/diegosouzapw/OmniRoute/pull/3814) — 感谢 @rafacpti23) +- **fix(ui): 使用垂直调整手柄扩展请求日志表** — 请求日志表现在显示约 10 行，并可垂直调整大小。 ([#3820](https://github.com/diegosouzapw/OmniRoute/pull/3820) — 感谢 @rafacpti23) +- **fix(i18n): 翻译 37 个语言环境中缺失的 `embeddedServices` 键** — `embeddedServices` 字符串在 37 个语言环境中显示为 `__MISSING__`；现已翻译。 ([#3819](https://github.com/diegosouzapw/OmniRoute/pull/3819) — 感谢 @rafacpti23) + +### 🔒 安全与加固 + +- **fix(security): CCR 跨租户 IDOR — 按主体划分的作用域存储 + 有界内存** — 压缩 CCR 作用域存储此前在所有主体之间共享，允许跨租户读取；现已按主体划分作用域并设置内存边界。 ([#3859](https://github.com/diegosouzapw/OmniRoute/pull/3859)) +- **feat(supply-chain): 构建来源、SBOM、Trivy 扫描 & OpenSSF Scorecard（建议性）** — 添加了 npm 构建来源、CycloneDX SBOM、Trivy 镜像扫描和 OpenSSF Scorecard 工作流（Quality Gates Fase 8 · Bloco A，建议性）。 ([#3824](https://github.com/diegosouzapw/OmniRoute/pull/3824)) + +### 🧹 内部 / 质量 / 文档 + +- **将邮箱隐私控制合并到设置 → 外观** — 每个页面的邮箱隐私开关被替换为单一的全局开关。 ([#3822](https://github.com/diegosouzapw/OmniRoute/pull/3822) — 感谢 @rdself) +- **docs(ui): 澄清路由设置文案（策略同步 + 粘性限制）** — ([#3843](https://github.com/diegosouzapw/OmniRoute/pull/3843) — 感谢 @adivekar-utexas) +- **Quality Gates — Fase 7 & 8** — 将死代码 / 认知复杂度 / 类型覆盖率门槛提升为阻塞项，安装建议性 CI 扫描器（gitleaks / osv / actionlint / zizmor），并添加属性 + 黄金 + SSE 正确性测试以及运行时韧性（混沌 / 堆增长 / k6 压力）套件。 ([#3809](https://github.com/diegosouzapw/OmniRoute/pull/3809), [#3858](https://github.com/diegosouzapw/OmniRoute/pull/3858), [#3808](https://github.com/diegosouzapw/OmniRoute/pull/3808), [#3854](https://github.com/diegosouzapw/OmniRoute/pull/3854)) +- **fix(docs): 为 `SUPPLY_CHAIN.md` 添加 MDX frontmatter** — 新的安全文档缺少 MDX 页面所需的 `title:` frontmatter，导致生产构建和 Docker Hub 发布失败；已添加 frontmatter。 ([#3864](https://github.com/diegosouzapw/OmniRoute/pull/3864)) +- **chore(deps): 升级 `aquasecurity/trivy-action` 0.28.0 → 0.36.0** ([#3862](https://github.com/diegosouzapw/OmniRoute/pull/3862)) +- **chore(quality): 为 Prettier 膨胀的 v3.8.25 修复 + `chat.ts` 增长调整文件大小基准** — 重新冻结每文件大小基准，以吸收本周期聊天核心和 Combo 修复带来的格式化/行数增长（手动编辑，绝不自动上调）。 ([#3823](https://github.com/diegosouzapw/OmniRoute/pull/3823), [#3833](https://github.com/diegosouzapw/OmniRoute/pull/3833) — 感谢 @diegosouzapw) +- **test(suite): 发布时确保单元套件通过 — 将过期测试对齐到本周期的预期行为 + 修复两个新套件的波动性** — 发布门槛维护：更新了落后于预期行为变更的测试（OpenCode Go 锁定配额消息 #3838、邮箱隐私控制合并到设置 #3822、SOCKS5 默认开启代理类型消息、`[id]` 服务商详情绞杀榕分解 #3501、Vertex Express-mode 密钥、使用当前用户可调用模型 ID 的 Antigravity 发现）以及同服务商 503 穿透韧性测试；修复了压缩基准可重复性测试的波动性（连续通过）和 ServiceSupervisor 崩溃测试的波动性（轮询替代固定睡眠）。无生产代码变更。同时将 `OMNIROUTE_MAX_PENDING_MIGRATIONS`（#3416）记录到 `.env.example` + `ENVIRONMENT.md` 中。(感谢 @diegosouzapw) --- @@ -1325,226 +1325,209 @@ _Development cycle in progress._ ## [3.8.8] — 2026-06-01 -### Added +### 新增 -- **Plugins framework** (`src/lib/plugins/`, `/api/plugins/*`, `/dashboard/plugins`) — hooks + registry unification, plugin SDK (`definePlugin`), worker-thread sandbox, per-plugin hook rate limiting, SHA-256 integrity verification, semver-gated upgrade, and execution analytics. Plugin routes are loopback-only (`isLocalOnlyPath`) and `child_process` exec is opt-in via `OMNIROUTE_PLUGINS_ALLOW_EXEC`. (#2913 / #3041 — thanks @oyi77) -- **Plugin system: response-hook wiring + startup load + example plugin** — wires the plugin `onResponse` hook into the chat success path, loads active plugins on server startup so they survive restarts (`pluginManager.loadAll()` in `server-init`), and ships a `welcome-banner` example plugin (`examples/plugins/`) plus a comprehensive plugin test suite. (#3045 — thanks @oyi77) -- **API key option: disable non-published models** — a per-key flag restricting the key to discovered, public models (combos / `auto/*` / `qtSd/*` routing still allowed). (#3017 — thanks @androw) -- **SessionPool — modular & provider-agnostic** (`open-sse/services/sessionPool/`) — pooled - cookie/session manager with round-robin fingerprint rotation (distinct fingerprint per pooled - session), per-session cooldown/backoff, and a provider-agnostic `webExecutorWrapper`. Adds pool - support for DuckDuckGo Web and LLM7 providers and an MCP `poolTools` toolset. (#2954 / #2978 — thanks @oyi77) -- **AgentBridge** (`/dashboard/tools/agent-bridge`) — MITM proxy consolidating 9 IDE agents +- **插件框架** (`src/lib/plugins/`, `/api/plugins/*`, `/dashboard/plugins`) — 钩子 + 注册表统一，插件 SDK (`definePlugin`)，工作线程沙箱，每插件钩子速率限制，SHA-256 完整性校验，语义化版本升级管控，执行分析。插件路由仅限本地回环 (`isLocalOnlyPath`)，且 `child_process` exec 需通过 `OMNIROUTE_PLUGINS_ALLOW_EXEC` 显式启用。(#2913 / #3041 — 感谢 @oyi77) +- **插件系统: 响应钩子接线 + 启动加载 + 示例插件** — 将插件 `onResponse` 钩子接入聊天成功路径，在服务器启动时加载活跃插件使其在重启后存活（`pluginManager.loadAll()` 在 `server-init` 中），附带 `welcome-banner` 示例插件 (`examples/plugins/`) 以及全面的插件测试套件。(#3045 — 感谢 @oyi77) +- **API 密钥选项: 禁用非公开模型** — 每密钥标志，限制密钥只能访问已发现、公开的模型（combos / `auto/*` / `qtSd/*` 路由仍允许）。(#3017 — 感谢 @androw) +- **会话池 — 模块化且��服务商无关** (`open-sse/services/sessionPool/`) — 池化 + cookie/会话管理器，支持轮询指纹轮换（每个池化会话有不同指纹）， + 每会话冷却/退避，与服务商无关的 `webExecutorWrapper`。为 DuckDuckGo Web 和 LLM7 + 服务商添加了池化支持，以及 MCP `poolTools` 工具集。(#2954 / #2978 — 感谢 @oyi77) +- **AgentBridge** (`/dashboard/tools/agent-bridge`) — MITM（中间人代理），整合 9 个 IDE 智能体 (Antigravity, Kiro, GitHub Copilot, OpenAI Codex, Cursor IDE, Zed Industries, Claude Code, - Open Code, Trae stub) with server card, per-agent setup wizard, model mapping table, - bypass list, upstream CA cert support, and redirect from legacy `/dashboard/system/mitm-proxy`. - See `docs/frameworks/AGENTBRIDGE.md`. (#2858 — thanks @diegosouzapw) -- **Traffic Inspector** (`/dashboard/tools/traffic-inspector`) — LLM-aware HTTPS debugger with - 4 capture modes (AgentBridge hook, Custom Hosts DNS, HTTP_PROXY :8080, System-wide proxy), - DevTools split UI, 7 detail tabs (Conversation, Headers, Request, Response, Timing, LLM Details, - Stats), resizable panels, session recording (.har/.jsonl export), SSE stream merger, - conversation normalizer (multi-provider), system-prompt fingerprint colorization, and annotations. - See `docs/frameworks/TRAFFIC_INSPECTOR.md`. -- **MITM handler base + 9 agent handlers** (`src/mitm/handlers/`) — `MitmHandlerBase` abstract - class with `hookBufferStart`/`hookBufferUpdate` for Traffic Inspector integration; concrete - handlers for all 9 agents. -- **MITM targets registry** (`src/mitm/targets/`) — declarative `MitmTarget` shape per agent; - emits `DATA_DIR/mitm/targets.json` for dynamic `server.cjs` resolution. -- **Traffic Inspector core** (`src/mitm/inspector/`) — `TrafficBuffer` in-memory ring, - `kindDetector`, `sseMerger` (MIT port from chouzz/llm-interceptor), `conversationNormalizer` - (MIT port), `contextKey` fingerprinting, `httpProxyServer`, `systemProxyConfig`. -- **AgentBridge passthrough + bypass** (`src/mitm/passthrough.ts`) — TCP tunnel for - non-mapped hosts; bypass list with default sensitive-host patterns + user-defined patterns. -- **Upstream CA cert** (`src/mitm/upstreamTrust.ts`) — `AGENTBRIDGE_UPSTREAM_CA_CERT` for - corporate TLS environments. -- **Secret masking** (`src/mitm/maskSecrets.ts`) — sk-/Bearer/generic token masking before - any log or Traffic Inspector broadcast. -- **DB migrations 073–075** — `agent_bridge_state`, `agent_bridge_mappings`, + Open Code, Trae 桩），提供服务卡片、每智能体设置向导、模型映射表、 + 绕过列表、上游 CA 证书支持，并从旧版 `/dashboard/system/mitm-proxy` 重定向。 + 详见 `docs/frameworks/AGENTBRIDGE.md`。(#2858 — 感谢 @diegosouzapw) +- **流量检查器** (`/dashboard/tools/traffic-inspector`) — LLM 感知的 HTTPS 调试器，支持 + 4 种捕获模式（AgentBridge 钩子、自定义 Hosts DNS、HTTP_PROXY :8080、系统级代理）、 + DevTools 分屏界面、7 个详情标签页（对话、请求头、请求、响应、耗时、LLM 详情、 + 统计）、可调整大小的面板、会话录制（.har/.jsonl 导出）、SSE 流合并器、 + 对话规范化器（跨服务商）、系统提示指纹着色及注释。 + 详见 `docs/frameworks/TRAFFIC_INSPECTOR.md`。 +- **MITM 处理器基类 + 9 个智能体处理器** (`src/mitm/handlers/`) — `MitmHandlerBase` 抽象 + 类，包含 `hookBufferStart`/`hookBufferUpdate` 用于流量检查器集成；以及全部 9 个智能体的具体处理器。 +- **MITM 目标注册表** (`src/mitm/targets/`) — 每个智能体的声明式 `MitmTarget` 形态； + 生成 `DATA_DIR/mitm/targets.json` 用于动态 `server.cjs` 解析。 +- **流量检查器核心** (`src/mitm/inspector/`) — `TrafficBuffer` 内存环形缓冲区、 + `kindDetector`、`sseMerger`（从 chouzz/llm-interceptor MIT 移植）、`conversationNormalizer` + （MIT 移植）、`contextKey` 指纹识别、`httpProxyServer`、`systemProxyConfig`。 +- **AgentBridge 透传 + 绕过** (`src/mitm/passthrough.ts`) — 为非映射主机提供 TCP 隧道； + 绕过列表包含默认敏感主机模式 + 用户自定义模式。 +- **上游 CA 证书** (`src/mitm/upstreamTrust.ts`) — `AGENTBRIDGE_UPSTREAM_CA_CERT` 用于 + 企业 TLS 环境。 +- **密钥脱敏** (`src/mitm/maskSecrets.ts`) — 在任何日志或流量检查器广播前，对 sk-/Bearer/通用令牌进行脱敏。 +- **数据库迁移 073–075** — `agent_bridge_state`, `agent_bridge_mappings`, `agent_bridge_bypass`, `inspector_custom_hosts`, `inspector_sessions`, `inspector_session_requests`. -- **~28 API routes** under `/api/tools/agent-bridge/` (12 routes) and - `/api/tools/traffic-inspector/` (16+ routes). All LOCAL_ONLY + SPAWN_CAPABLE. -- **i18n** PT-BR + EN for all new keys in `agentBridge.*` and `trafficInspector.*` namespaces; - all other locales fall back to EN automatically. -- **E2E smoke tests** — `tests/e2e/agent-bridge.spec.ts`, +- **约 28 个 API 路由** 位于 `/api/tools/agent-bridge/`（12 个路由）和 + `/api/tools/traffic-inspector/`（16+ 个路由）。全部为 LOCAL_ONLY + SPAWN_CAPABLE。 +- **国际化**：`agentBridge.*` 和 `trafficInspector.*` 命名空间下所有新增键的 PT-BR + EN 翻译； + 所有其他语言自动回退到 EN。 +- **端到端冒烟测试** — `tests/e2e/agent-bridge.spec.ts`, `tests/e2e/traffic-inspector.spec.ts`, `tests/e2e/agent-bridge-traffic-cross.spec.ts` - (skip-gated on CI by `RUN_AGENT_BRIDGE_E2E` / `RUN_TRAFFIC_INSPECTOR_E2E` / `RUN_CROSS_E2E`). -- **Documentation** — `docs/frameworks/AGENTBRIDGE.md` and `docs/frameworks/TRAFFIC_INSPECTOR.md`; - `docs/architecture/REPOSITORY_MAP.md` updated; `docs/reference/openapi.yaml` updated with - ~28 new routes and 20+ new schemas. -- **i18n:** translate Ukrainian (uk-UA) menu and UI strings, plus complete uk-UA UI coverage (#2981 / #2988 — thanks @Lion-killer) -- **providers:** add SiliconFlow endpoint selector (#2975 — thanks @xz-dev) -- **oauth:** add Trae SOLO provider (work/code modes) (#2964 — thanks @S0yora) -- **providers:** add Qwen Web (chat.qwen.ai) web-cookie provider (#2947 — thanks @oyi77) -- **Quota Share Engine — multi-provider quota pools** — Monitoring/Costs reorg plus a Quota Share Engine: group selector, grouped pool cards, exclusive-quota API keys (`allowedQuotas`), `quotaShared-*` routing models via combos, a 3-step pool wizard (legacy Plans page retired), endpoint + key preview, and full pool editing. Adds quota-pool DB migrations. (#2859 / #3022 / #3032 — thanks @diegosouzapw) -- **Dashboard page redesigns (Nav Restructure)** — agent-skills + omni-skills with a dynamic 42-skill catalog and MCP/A2A discovery (#2827); CLI Code's + CLI Agents + ACP Agents pages (#2839); translator friendly redesign, 5 tabs → 2 (#2847); functional `/batch` + `/batch/files` redesign (#2849); Playground Studio + Search Tools Studio (#2869); memory engine redesign — sqlite-vec + hybrid RRF + Studio UI (#2873). (thanks @diegosouzapw) -- **notion:** add Notion as an MCP context source — 6 tools (`notion_search`, `notion_list_databases`, `notion_get_database`, `notion_query_database`, `notion_read`, `notion_append_blocks`) scoped under `read:notion` / `write:notion`, with dashboard "Context Sources" tab, settings API, and token persistence in `key_value` table (#2959) - -### Changed - -- Sidebar Tools group: added `agent-bridge` and `traffic-inspector` items after `cloud-agents`. -- `/api/tools/agent-bridge/` and `/api/tools/traffic-inspector/` added to `LOCAL_ONLY_API_PREFIXES` - and `SPAWN_CAPABLE_PREFIXES` in `src/server/authz/routeGuard.ts`. -- `.env.example`: documented 9 new env vars (`AGENTBRIDGE_UPSTREAM_CA_CERT`, - `INSPECTOR_BUFFER_SIZE`, `INSPECTOR_HTTP_PROXY_PORT`, `INSPECTOR_HTTP_PROXY_AUTOSTART`, - `INSPECTOR_TLS_INTERCEPT`, `INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES`, `INSPECTOR_MAX_BODY_KB`, - `INSPECTOR_MASK_SECRETS`, `INSPECTOR_LLM_HOSTS_EXTRA`, `INSPECTOR_INTERNAL_INGEST_TOKEN`). - -### Fixed - -- **codex/providers:** `POST /api/providers/[id]/refresh` (the manual/auto "refresh - token" endpoint) no longer rotates rotating-refresh providers (Codex/OpenAI share - one Auth0 `client_id`). This was the last unguarded proactive-refresh entry point: - when the dashboard auto-refreshed every expiring connection on a page load (or an - old cached frontend bulk-called it), each Codex account's single-use refresh_token - was rotated, and Auth0 revoked the whole token family (`openai/codex#9648`) — every - account but the last died with `[403] `. The quota path now skips proactive refresh for - rotating providers (`rotationGroupFor`) and reuses the current access*token, - deferring genuine expiry to the reactive, serialized 401 path. Defense in - depth: `serializeRefresh` now leaves a settle gap between two \_queued* sibling - refreshes (default 2000 ms, tunable via `CODEX_REFRESH_SPACING_MS`, `"0"` to - opt out) while releasing a lone refresh immediately, so the reactive path adds - no latency. -- **payload-rules:** saved payload rules now survive a server restart. When no - in-memory override is set (fresh process before the boot hook ran, or a - separate module instance in the standalone build), `getPayloadRulesConfig` - now reads the DB-persisted rules (the source of truth) before the file config, - instead of silently returning the empty file default. (#2986) -- **models/custom:** custom models can now carry a per-model `targetFormat` - override (e.g. an opencode-go custom model that must use the Anthropic Messages - shape). Previously custom models always routed as OpenAI-compatible because - `targetFormat` was neither persisted nor consulted at routing time. Threaded - through `addCustomModel`/`replaceCustomModels`/`updateCustomModel`, the API - schema/route, `getModelInfo`, and chatCore's targetFormat resolution. (#2905) -- **providers/pollinations:** route to `gen.pollinations.ai/v1` instead of the - retired `text.pollinations.ai` host, which now returns `404 "legacy API"` for - all models. The gen gateway is the current OpenAI-compatible endpoint. (#2987) -- **executors/codex:** drop the CLI-injected `image_generation` hosted tool for - free-plan Codex accounts (`workspacePlanType === "free"`), which can't run it - server-side and would otherwise get an upstream 400. Paid plans keep it. - (mirrors CLIProxyAPI's free-plan guard; spun off from the #2980 analysis) -- **dashboard:** custom providers (`openai-compatible-*` / `anthropic-compatible-*`) - now show their user-given node name instead of the raw UUID id across the - active-requests panel, proxy logger, and home-page provider topology. The - display-label resolver was extracted into a shared util reused by all surfaces - (previously only the request-log viewer resolved it). (#2968) -- **docker:** the standalone launcher (Docker `CMD`) now honors - `OMNIROUTE_MEMORY_MB` (default 512, clamped [64, 16384]) and overrides the - image `NODE_OPTIONS` fallback, fixing random OOM crashes under load / with - large SQLite DBs. Previously only `omniroute serve` honored the knob. (#2939) -- **docker:** add a `web` compose profile (`omniroute-web`, target `runner-web`, - image `omniroute:web`) so web-cookie providers (gemini-web, claude-web, - claude-turnstile) work out of the box — the default `base` image ships without - Chromium/Playwright, which made those providers fail with - "Executable doesn't exist at .../ms-playwright/chromium...". (#2832) -- **routing/codex:** fix two gpt-5.5 Codex defects (#2877). (A) For a Codex-only - account, a bare `gpt-5.5` Responses request was rerouted to codex with the - model hardcoded to `gpt-5.5-medium` (`chatHelpers.ts`); the executor read that - `-medium` suffix as an explicit `modelEffort` that (per #2331) overrode a - client `reasoning.effort=xhigh`, silently demoting it — now it keeps the bare - `gpt-5.5` id so the client effort wins. (B) `gpt-5.5-xhigh`/`-high`/`-low` - misrouted to `openai` (→ "No credentials" for codex-only users); the suffixed - variants are now in `CODEX_PREFERRED_UNPREFIXED_MODELS` so they infer codex. -- **sse/chatCore:** remove a duplicate `const settings` declaration in - `handleChatCore` (introduced alongside the per-key stream-default-mode - feature). The same-scope redeclaration made esbuild/tsx fail with - "The symbol 'settings' has already been declared", which turned every unit - test that imports chatCore red and broke the production build. The earlier - consolidated `settings` const is now reused. -- **db/migrations:** resolve a `077` migration version collision - (`077_api_key_stream_default_mode.sql` vs `077_quota_pools.sql`) that made - `getMigrationFiles()` throw and blocked `getDbInstance()` at startup (app would - not boot; every DB-touching test was red). Renumbered the dependency-free, - idempotent `quota_pools` migration to `085`, kept the non-idempotent - `api_key_stream_default_mode` `ALTER` at `077`, added a retroactive - `isSchemaAlreadyApplied` guard (case `085`), and a regression test enforcing - unique migration prefixes. -- **routing/reasoning-replay:** OpenCode `big-pickle` (provider `opencode`/`oc` - and `opencode-zen`) now declares the interleaved `reasoning_content` contract - via a new `RegistryModel.interleavedField` field, so follow-up/tool-use turns - replay reasoning_content. Previously `big-pickle` matched no replay pattern and - failed with `[400] The reasoning_content in the thinking mode must be passed -back to the API` (its DeepSeek-thinking upstream is not detectable from the - model id, and `requiresReasoningReplay` does not consume `supportsReasoning`). - `getResolvedModelCapabilities` now surfaces the registry `interleavedField`. (#2900) -- **providers/github-copilot:** built-in GitHub Copilot Claude Opus and Gemini - models (`claude-opus-4.7`, `claude-opus-4-5-20251101`, `gemini-3.1-pro-preview`, - `gemini-3-flash-preview`) no longer carry `targetFormat: "openai-responses"`, so - they route through `chat/completions` (the provider default, like the working - `claude-opus-4.6`) instead of the Responses API, which Copilot does not serve for - non-OpenAI models (returned `[400]`). Native OpenAI `gpt-*` models keep the - Responses API. (#2911) -- **translator/responses:** Codex Desktop injects an `image_generation` hosted - tool into every Responses API request (even text-only ones), which OmniRoute - rejected with `[400] image_generation tool type is not supported`. It is now - treated like `tool_search`: allowed past the tool-type validator and dropped - silently from the tools array before forwarding to Chat Completions. (#2950) -- **combo/builder:** no-auth OpenCode Free combo entries now use the `oc/` routing - alias instead of the `opencode/` prefix. `parseModel("opencode/")` - resolves to the `opencode-zen` api-key tier (via a manual `ALIAS_TO_PROVIDER_ID` - override), so combos built with the bare provider id misrouted away from the - no-auth `opencode` provider; `oc/` resolves correctly. (#2901) -- **resilience/providers:** a route-restriction `403` (e.g. Fireworks Fire Pass - `fpk_*` keys returning "…not authorized for this route." on `/models`, while - chat still works) no longer marks the connection unavailable. Provider - validation falls through to the chat probe for such 403s instead of returning - "Invalid API key", and `checkFallbackError` short-circuits them to no cooldown. - Genuine auth failures (401 / generic 403) still fail fast. (#2929) -- **auth/opencode-zen:** the OpenCode Zen free model now works in the Playground - and combos without an API key. `opencode-zen` serves the public, signup-free - endpoint (`https://opencode.ai/zen/v1`); when no api-key connection is - configured, credential resolution now falls back to anonymous (no-auth) access - instead of failing with "No credentials for provider: opencode-zen". A - configured, active key is still used when present. (#2962) -- **translator/responses:** fixed an upstream `[400] Messages with role 'tool' -must be a response to a preceding message with 'tool_calls'` when a Codex - client sent a `function_call` with an empty/missing `call_id`. The orphaned - `function_call_output` previously slipped past the orphan filter. Now - empty-`call_id` function calls are skipped (no dangling assistant tool_call) - and any tool result without a matching tool_call id is dropped. (#2893) -- **deps:** remove the `proxifly` npm dependency (#3000 — thanks @terence71-glitch) -- **proxy:** use connection proxy for OAuth refresh (#3012 — thanks @terence71-glitch) -- **usage:** export pure helper functions for unit testing (#3015 — thanks @oyi77) -- **docs/docker:** align memory default docs to 1024MB (#3006 — thanks @terence71-glitch) -- **providers:** fix DuckDuckGo missing API key & update OpenCode free model list (#3008 — thanks @NekoMonci12) -- **claude:** bump Claude Code identity to 2.1.158 and sync beta flags (#3010 — thanks @Tentoxa) -- **test:** increase DB and usage utils coverage to >60% (#3018 — thanks @oyi77) -- **oom:** resolve memory leak in Bottleneck limiter caches and provider registry (#2965 — thanks @soyelmismo) -- **proxy:** show registry provider proxies in dashboard after Custom proxy flow moved them into the proxy registry (#2963 — thanks @terence71-glitch) -- **routing:** add agy to executor map so it uses AntigravityExecutor (#2957 — thanks @ReqX) -- **skills:** avoid Claude assistant tool_result blocks (#2956 — thanks @terence71-glitch) -- **perf:** CPU leak from Bottleneck limiter accumulation + per-request optimizations (#2951 — thanks @soyelmismo) -- **combo:** combo credential resolution ignores target.providerId — prefer combo target's providerId over model-inferred provider (#2946 — thanks @oyi77) -- **dashboard:** v3.8.8 screen fixes — agent-bridge SSR + audit/logs/memory/playground (#2944) -- **claude:** sanitize tool schemas + cloak third-party tool names on native Claude OAuth (#2943 — thanks @NomenAK) -- **auth:** prevent Codex multi-account refresh_token family revocation (#2941) -- **combo:** fix combo vision passthrough and Codex tool history repair (#2940 — thanks @charithharshana) -- **claude:** map WebSearch to Responses web_search (#2938 — thanks @makcimbx) -- **claude:** strip empty Read pages tool input (#2937 — thanks @makcimbx) -- **dashboard:** improve self-service provider quota visibility (#2931 — thanks @guanbear) -- **antigravity:** avoid visible signatureless tool history (#2927 — thanks @dhaern) -- **sse/web-search:** bypass the web-search fallback on a Claude → Claude passthrough so native Claude requests aren't rewritten (#2960 — thanks @terence71-glitch) -- **oom:** prevent per-request memory accumulation (~256MB heap growth) (#2973 — thanks @soyelmismo) -- **perf/proxy:** parallelize provider proxy overlay lookups (#2984 — thanks @terence71-glitch) -- **privacy/PII:** resolve the PII feature flag correctly and fix PII response sanitization in streaming SSE requests (#3021 — thanks @dangeReis) -- **electron:** improve macOS window chrome (#3029 — thanks @bobbyunknown) -- **i18n:** fix missing API key scope translations (#3031 — thanks @guanbear) -- **stream/responses:** drop a leaked chat bootstrap chunk for Responses-API clients (#3035 — thanks @CitrusIce) -- **docker:** warn-only on the `/app/data` permission check instead of `exit 1`, so a non-writable bind mount no longer kills the container at boot (#3036 — thanks @wussh) -- **mcp:** resolve streamable-HTTP transport readiness reporting an offline status (#3037 — thanks @Chewji9875) -- **dashboard:** use a lightweight ping endpoint for the MaintenanceBanner (fixes #3040) (#3043 — thanks @herjarsa) -- **test:** resolve pre-existing test failures — env sync, PII, quota, sidebar (#3039 — thanks @oyi77) -- **docs/mcp:** regenerate the mcp-tools diagram for 43 tools and fix the tool count (#3028 — thanks @diegosouzapw) -- **mcp:** move `enforceScopes` guard before `MCP_TOOL_MAP` lookup, add inline `scopes` parameter to `withScopeEnforcement()`, and declare scopes on all 24 dynamic tool definitions (memory, skills, plugins, gamification, compression) to fix scope enforcement for dynamic MCP tool groups (#2958) + （在 CI 上由 `RUN_AGENT_BRIDGE_E2E` / `RUN_TRAFFIC_INSPECTOR_E2E` / `RUN_CROSS_E2E` 跳过控制）。 +- **文档** — `docs/frameworks/AGENTBRIDGE.md` 和 `docs/frameworks/TRAFFIC_INSPECTOR.md`； + 更新了 `docs/architecture/REPOSITORY_MAP.md`；更新了 `docs/reference/openapi.yaml`， + 新增约 28 个路由和 20+ 个 Schema。 +- **国际化:** 翻译乌克兰语（uk-UA）菜单和界面字符串，并完成完整的 uk-UA 界面覆盖 (#2981 / #2988 — 感谢 @Lion-killer) +- **服务商:** 添加 SiliconFlow 端点选择器 (#2975 — 感谢 @xz-dev) +- **OAuth:** 添加 Trae SOLO 服务商（work/code 模式）(#2964 — 感谢 @S0yora) +- **服务商:** 添加 Qwen Web（chat.qwen.ai）web-cookie 服务商 (#2947 — 感谢 @oyi77) +- **配额共享引擎 — 跨服务商配额池** — 监控/费用重构，外加配额共享引擎：分组选择器、分组池卡片、独占配额 API 密钥 (`allowedQuotas`)、通过 combos 的 `quotaShared-*` 路由模型、三步池向导（旧版 Plans 页面已退役）、端点 + 密钥预览以及完整的池编辑功能。新增配额池数据库迁移。(#2859 / #3022 / #3032 — 感谢 @diegosouzapw) +- **仪表盘页面重新设计（导航重构）** — 智能体技能 + omni 技能，带动态 42 技能目录和 MCP/A2A 发现 (#2827)；CLI Code + CLI Agents + ACP Agents 页面 (#2839)；翻译器友好重新设计，5 个标签页 → 2 个 (#2847)；功能性 `/batch` + `/batch/files` 重新设计 (#2849)；Playground Studio + Search Tools Studio (#2869)；记忆引擎重新设计 — sqlite-vec + 混合 RRF + Studio 界面 (#2873)。（感谢 @diegosouzapw） +- **notion:** 添加 Notion 作为 MCP 上下文源 — 6 个工具 (`notion_search`、`notion_list_databases`、`notion_get_database`、`notion_query_database`、`notion_read`、`notion_append_blocks`)，作用域为 `read:notion` / `write:notion`，配有仪表盘"上下文源"标签页、设置 API 和 `key_value` 表中的令牌持久化 (#2959) + +### 变更 + +- 侧边栏工具组：在 `cloud-agents` 之后添加了 `agent-bridge` 和 `traffic-inspector` 项。 +- `/api/tools/agent-bridge/` 和 `/api/tools/traffic-inspector/` 已添加到 `src/server/authz/routeGuard.ts` 中的 `LOCAL_ONLY_API_PREFIXES` 和 `SPAWN_CAPABLE_PREFIXES`。 +- `.env.example`：记录了 9 个新的环境变量（`AGENTBRIDGE_UPSTREAM_CA_CERT`、 + `INSPECTOR_BUFFER_SIZE`、`INSPECTOR_HTTP_PROXY_PORT`、`INSPECTOR_HTTP_PROXY_AUTOSTART`、 + `INSPECTOR_TLS_INTERCEPT`、`INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES`、`INSPECTOR_MAX_BODY_KB`、 + `INSPECTOR_MASK_SECRETS`、`INSPECTOR_LLM_HOSTS_EXTRA`、`INSPECTOR_INTERNAL_INGEST_TOKEN`）。 + +### 已修复 + +- **codex/服务商:** `POST /api/providers/[id]/refresh`（手动/自动"刷新令牌"端点）不再轮换使用轮换刷新令牌的服务商（Codex/OpenAI 共享一个 Auth0 `client_id`）。这是最后一个未设防的主动刷新入口点： + 当仪表盘在页面加载时自动刷新每个即将过期的连接（或旧缓存前端批量调用该端点）， + 每个 Codex 账户的一次性 refresh_token 都会被轮换，Auth0 吊销整个令牌族 (`openai/codex#9648`) — 除最后一个外所有账户都会因 `[403] ` 而失效。该端点现在对轮换服务商跳过主动轮换，并交由响应式、串行化的 401 路径处理（与 `refreshAndUpdateCredentials` 和连接测试路由使用相同的守卫）。 +- **codex/配额:** 打开配额 / 服务商仪表盘不再断开 Codex 多账户设置。配额同步路径 + (`refreshAndUpdateCredentials`) 曾主动刷新每个连接 — 对于 + 轮换刷新令牌的服务商（Codex/OpenAI 共享一个 Auth0 `client_id`），它 + 并发刷新了兄弟账户，导致 Auth0 吊销整个令牌族 + (`openai/codex#9648`)，除最后一个外所有账户都因 + `[403] ` 而失效。配额路径现在对轮换服务商跳过主动刷新 + (`rotationGroupFor`)，并复用当前的 access_token， + 将真正的过期交由响应式、串行化的 401 路径处理。纵深防御： + `serializeRefresh` 现在在两个 _排队_ 的兄弟刷新之间留有冷却间隔 + （默认 2000 毫秒，可通过 `CODEX_REFRESH_SPACING_MS` 调整，设为 `"0"` 可 + 退出），同时立即释放单个刷新，因此响应式路径不会增加延迟。 +- **负载规则:** 保存的负载规则现在在服务器重启后依然有效。当没有 + 内存中的覆盖设置时（启动钩子运行前的新进程，或 + 独立构建中的单独模块实例），`getPayloadRulesConfig` + 现在在读取文件配置之前先读取数据库持久化的规则（真实数据源）， + 而不是静默返回空的文件默认值。(#2986) +- **模型/自定义:** 自定义模型现在可以携带每个模型的 `targetFormat` + 覆盖（例如，一个 opencode-go 自定义模型必须使用 Anthropic Messages + 格式）。此前自定义模型始终按 OpenAI 兼容格式路由，因为 + `targetFormat` 既未持久化，也未在路由时查询。已贯穿 + `addCustomModel`/`replaceCustomModels`/`updateCustomModel`、API + Schema/路由、`getModelInfo` 以及 chatCore 的 targetFormat 解析。(#2905) +- **服务商/pollinations:** 路由至 `gen.pollinations.ai/v1` 而非已 + 废弃的 `text.pollinations.ai` 主机，后者现在对所有模型返回 `404 "legacy API"`。 + gen 网关是当前的 OpenAI 兼容端点。(#2987) +- **执行器/codex:** 对免费计划 Codex 账户 (`workspacePlanType === "free"`) 移除 CLI 注入的 `image_generation` 托管工具， + 这些账户无法在服务端运行该工具，否则会收到上游 400 错误。付费计划保留该工具。 + （镜像 CLIProxyAPI 的免费计划守卫；从 #2980 分析中分离出来） +- **仪表盘:** 自定义服务商（`openai-compatible-*` / `anthropic-compatible-*`） + 现在在活跃请求面板、代理日志和首页服务商拓扑中显示用户指定的节点名称，而非原始 UUID id。 + 显示标签解析器已提取为共享工具，供所有界面复用 + （此前只有请求日志查看器解析了该标签）。(#2968) +- **docker:** 独立启动器（Docker `CMD`）现在遵循 + `OMNIROUTE_MEMORY_MB`（默认 512，范围 [64, 16384]）并覆盖 + 镜像 `NODE_OPTIONS` 回退值，修复了高负载 / 大型 SQLite 数据库下的随机 OOM 崩溃。 +- **docker:** 添加 `web` compose 配置文件（`omniroute-web`，目标 `runner-web`， + 镜像 `omniroute:web`），使 web-cookie 服务商（gemini-web、claude-web、 + claude-turnstile）开箱即用 — 默认 `base` 镜像不包含 + Chromium/Playwright，导致这些服务商失败并报错 + "Executable doesn't exist at .../ms-playwright/chromium..."。(#2832) +- **路由/codex:** 修复两个 gpt-5.5 Codex 缺陷 (#2877)。(A) 对于仅有 Codex + 的账户，裸 `gpt-5.5` Responses 请求被重新路由到 codex，但模型 + 被硬编码为 `gpt-5.5-medium`（`chatHelpers.ts`）；执行器将该 + `-medium` 后缀解读为显式 `modelEffort`，根据 #2331 覆盖了 + 客户端的 `reasoning.effort=xhigh`，静默降级 — 现在保留裸 + `gpt-5.5` id，使客户端 effort 生效。(B) `gpt-5.5-xhigh`/`-high`/`-low` + 被错误路���到 `openai`（→ 对仅有 codex 的用户显示"No credentials"）；带后缀的 + 变体现在已加入 `CODEX_PREFERRED_UNPREFIXED_MODELS`，使其推断为 codex。 +- **sse/chatCore:** 移除 `handleChatCore` 中重复的 `const settings` 声明 + （随每密钥流默认模式功能一同引入）。同一作用域内的重复声明导致 esbuild/tsx 失败， + 报错"The symbol 'settings' has already been declared"，使所有 + 导入 chatCore 的单元测试变红并破坏了生产构建。现在复用之前 + 合并的 `settings` 常量。 +- **db/数据库迁移:** 解决 `077` 迁移版本冲突 + （`077_api_key_stream_default_mode.sql` vs `077_quota_pools.sql`），该冲突导致 + `getMigrationFiles()` 抛出异常并在启动时阻塞 `getDbInstance()`（应用无法 + 启动；所有涉及数据库的测试均失败）。将无依赖、 + 幂等的 `quota_pools` 迁移重新编号为 `085`，将非幂等的 + `api_key_stream_default_mode` `ALTER` 保留在 `077`，添加了回溯性的 + `isSchemaAlreadyApplied` 守卫（case `085`），以及一个强制唯一迁移前缀的回归测试。 +- **路由/推理重放:** OpenCode `big-pickle`（服务商 `opencode`/`oc` + 和 `opencode-zen`）现在通过新的 `RegistryModel.interleavedField` 字段声明交错 `reasoning_content` 契约， + 使后续/工具使用轮次能够重放 reasoning_content。此前 `big-pickle` 未匹配任何重放模式， + 失败并报错 `[400] The reasoning_content in the thinking mode must be passed +back to the API`（其 DeepSeek-thinking 上游无法从模型 id 检测到， + 且 `requiresReasoningReplay` 不消费 `supportsReasoning`）。 + `getResolvedModelCapabilities` 现在会暴露注册表中的 `interleavedField`。(#2900) +- **服务商/github-copilot:** 内置的 GitHub Copilot Claude Opus 和 Gemini + 模型（`claude-opus-4.7`、`claude-opus-4-5-20251101`、`gemini-3.1-pro-preview`、 + `gemini-3-flash-preview`）不再携带 `targetFormat: "openai-responses"`，因此 + 它们通过 `chat/completions` 路由（服务商默认值，与正常工作的 + `claude-opus-4.6` 相同），而非 Responses API，因为 Copilot 不为 + 非 OpenAI 模型提供 Responses API（会返回 `[400]`）。原生 OpenAI `gpt-*` 模型保留 + Responses API。(#2911) +- **翻译器/responses:** Codex Desktop 将 `image_generation` 托管 + 工具注入到每个 Responses API 请求中（即使是纯文本请求），OmniRoute + 曾拒绝该请求并报错 `[400] image_generation tool type is not supported`。现在 + 将其视为 `tool_search`：允许通过工具类型校验器，并在转发到 Chat Completions 之前 + 从工具数组中静默移除。(#2950) +- **combo/构建器:** 无需认证的 OpenCode Free combo 条目现在使用 `oc/` 路由 + 别名，而非 `opencode/` 前缀。`parseModel("opencode/")` + 解析到 `opencode-zen` API 密钥层级（通过手动 `ALIAS_TO_PROVIDER_ID` + 覆盖），因此使用裸服务商 id 构建的 combo 会被错误路由，偏离 + 无需认证的 `opencode` 服务商；`oc/` 解析正确。(#2901) +- **容灾/服务商:** 路由限制 `403`（例如 Fireworks Fire Pass + `fpk_*` 密钥在 `/models` 上返回"…not authorized for this route."，而 + 聊天仍然正常）不再将连接标记为不可用。服务商 + 校验对于此类 403 会回退到聊天探测，而不是返回 + "Invalid API key"，且 `checkFallbackError` 将它们短路为无冷却。 + 真正的认证失败（401 / 通用 403）仍然快速失败。(#2929) +- **认证/opencode-zen:** OpenCode Zen 免费模型现在可以在 Playground + 和 combo 中无需 API 密钥即可使用。`opencode-zen` 提供公开、无需注册的 + 端点 (`https://opencode.ai/zen/v1`)；当未配置 API 密钥连接时， + 凭证解析现在回退到匿名（无需认证）访问， + 而不是失败并报错"No credentials for provider: opencode-zen"。配置的 + 活跃密钥在存在时仍然会被使用。(#2962) +- **翻译器/responses:** 修复了上游 `[400] Messages with role 'tool' +must be a response to a preceding message with 'tool_calls'` 错误，当 Codex + 客户端发送带有空/缺失 `call_id` 的 `function_call` 时触发。孤立的 + `function_call_output` 此前绕过了孤立过滤器。现在 + 空 `call_id` 函数调用会被跳过（不产生悬空的助手 tool_call）， + 且任何没有匹配 tool_call id 的工具结果都会被丢弃。(#2893) +- **deps:** 移除 `proxifly` npm 依赖 (#3000 — 感谢 @terence71-glitch) +- **proxy:** OAuth 刷新时使用连接代理 (#3012 — 感谢 @terence71-glitch) +- **usage:** 导出纯辅助函数供单元测试使用 (#3015 — 感谢 @oyi77) +- **docs/docker:** 将内存默认文档对齐至 1024MB (#3006 — 感谢 @terence71-glitch) +- **providers:** 修复 DuckDuckGo 缺少 API key 并更新 OpenCode 免费模型列表 (#3008 — 感谢 @NekoMonci12) +- **claude:** 将 Claude Code 身份升级到 2.1.158 并同步 beta 标志 (#3010 — 感谢 @Tentoxa) +- **test:** 提升 DB 和 usage 工具覆盖��达 60% 以上 (#3018 — 感谢 @oyi77) +- **oom:** 解决 Bottleneck 限流器缓存和服务商注册表中的内存泄漏 (#2965 — 感谢 @soyelmismo) +- **proxy:** 自定义代理流程迁移后在控制台显示注册表服务商代理 (#2963 — 感谢 @terence71-glitch) +- **routing:** 将 agy 添加到 executor 映射以使用 AntigravityExecutor (#2957 — 感谢 @ReqX) +- **skills:** 避免 Claude 助手 tool_result 阻塞 (#2956 — 感谢 @terence71-glitch) +- **perf:** Bottleneck 限流器累积导致 CPU 泄漏及每请求优化 (#2951 — 感谢 @soyelmismo) +- **combo:** combo 凭证解析忽略 target.providerId — 优先使用 Combo 目标的 providerId 而非模型推断的服务商 (#2946 — 感谢 @oyi77) +- **dashboard:** v3.8.8 界面修复 — agent-bridge SSR + 审计/日志/记忆/工作室 (#2944) +- **claude:** 对原生 Claude OAuth 清洗工具 schema 并隐藏第三方工具名称 (#2943 — 感谢 @NomenAK) +- **auth:** 防止 Codex 多账户 refresh_token 家族吊销 (#2941) +- **combo:** 修复 combo vision 透传和 Codex 工具历史修复 (#2940 — 感谢 @charithharshana) +- **claude:** 将 WebSearch 映射�� Responses web_search (#2938 — 感谢 @makcimbx) +- **claude:** 去除空的 Read pages 工具输入 (#2937 — 感谢 @makcimbx) +- **dashboard:** 改进自助服务商配额可见性 (#2931 — 感谢 @guanbear) +- **antigravity:** 避免可见的无签名工具历史 (#2927 — 感谢 @dhaern) +- **sse/web-search:** Claude → Claude 透传时绕过 web-search 容灾，使原生 Claude 请求不被重写 (#2960 — 感谢 @terence71-glitch) +- **oom:** 防止每请求内存累积（约 256MB 堆增长）(#2973 — 感谢 @soyelmismo) +- **perf/proxy:** 并行化服务商代理覆盖查找 (#2984 — 感谢 @terence71-glitch) +- **privacy/PII:** 正确解析 PII 特性标志并修复流式 SSE 请求中的 PII 响应清洗 (#3021 — 感谢 @dangeReis) +- **electron:** 改进 macOS 窗口外观 (#3029 — 感谢 @bobbyunknown) +- **i18n:** 修复缺失的 API key 作用域翻译 (#3031 — 感谢 @guanbear) +- **stream/responses:** 对 Responses-API 客户端丢弃泄漏的聊天启动块 (#3035 — 感谢 @CitrusIce) +- **docker:** `/app/data` 权限检查仅警告而非 `exit 1`，使不可写挂载不再导致容器启动失败 (#3036 — 感谢 @wussh) +- **mcp:** 解决 streamable-HTTP 传输就绪状态报告为离线的问题 (#3037 — 感谢 @Chewji9875) +- **dashboard:** 使用轻量级 ping 端点作为维护横幅（修复 #3040）(#3043 — 感谢 @herjarsa) +- **test:** 解决已有测试失败 — env 同步、PII、配额、侧边栏 (#3039 — 感谢 @oyi77) +- **docs/mcp:** 为 43 个工具重新生成 mcp-tools 图表并修复工具计数 (#3028 — 感谢 @diegosouzapw) +- **mcp:** 将 `enforceScopes` 守卫移到 `MCP_TOOL_MAP` 查找之前，为 `withScopeEnforcement()` 添加内联 `scopes` 参数，并为所有 24 个动态工具定义（memory、skills、plugins、gamification、compression）声明作用域，修复动态 MCP 工具组的作用域执行 (#2958) --- @@ -1552,55 +1535,55 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ### ✨ 新功能 -- **api (self-service):** add `GET /api/v1/me/status` so a delegated API key can view its own usage (USD used, budget percent, token totals) and optional shared Codex account quota, backed by migration `075_api_key_self_service_usage_scopes` (#2908 — thanks @guanbear). -- **analytics:** roll up usage logs to `daily_usage_summary` before raw log cleanup, and query a SQL `UNION` of raw and rolled-up data to prevent analytics history data loss (#2904 — thanks @unitythemaker). -- **perf (RAM):** reduce server memory footprint by capping 11 in-memory caches, limiting SQLite page cache, lazy-loading provider registries via Proxy, and optimizing Next.js startup database probes (#2903 — thanks @soyelmismo). +- **api (自助服务):** 新增 `GET /api/v1/me/status`，使委托 API key 可查看自身用量（已用 USD、预算百分比、token 总数）及可选的共享 Codex 账户配额，由迁移 `075_api_key_self_service_usage_scopes` 支持 (#2908 — 感谢 @guanbear)。 +- **analytics:** 在原始日志清理前将用量日志汇总到 `daily_usage_summary`，并通过 SQL `UNION` 查询原始和汇总数据，防止分析历史数据丢失 (#2904 — 感谢 @unitythemaker)。 +- **perf (内存):** 通过限制 11 个内存缓存、限制 SQLite 页面缓存、通过 Proxy 延迟加载服务商注册表以及优化 Next.js 启动时的数据库探测来降低服务器内存占用 (#2903 — 感谢 @soyelmismo)。 ### 🔧 问题修复 -- **token-accounting:** prefer `prompt_tokens` over compatibility `input_tokens` for Anthropic Claude streams to avoid double-counting cached tokens (#2904 — thanks @unitythemaker). +- **token-accounting:** 对于 Anthropic Claude 流式传输，优先使用 `prompt_tokens` 而非兼容的 `input_tokens`，避免重复计算缓存 token (#2904 — 感谢 @unitythemaker)。 -- **agy:** add the **Antigravity CLI (`agy`)** as a standalone OAuth provider next to `gemini-cli`/`antigravity`. It reuses the antigravity inference backend (identical Google client, `daily-cloudcode-pa.googleapis.com`) but ships its own model catalog — notably the Claude models the backend exposes (`claude-opus-4-6-thinking`, `claude-sonnet-4-6`) — its own account pool, and connection methods: import the `agy` CLI token file (paste/upload), auto-detect a local CLI login (`~/.gemini/antigravity-cli/antigravity-oauth-token`), browser OAuth, and bulk/ZIP import. New routes: `POST /api/providers/agy-auth/{import,import-bulk,zip-extract,apply-local}`. +- **agy:** 将 **Antigravity CLI (`agy`)** 作为独立的 OAuth 服务商，与 `gemini-cli`/`antigravity` 并列。它复用 antigravity 推理后端（相同的 Google client、`daily-cloudcode-pa.googleapis.com`），但提��自己的模型目录——特别是后端暴露的 Claude 模型（`claude-opus-4-6-thinking`、`claude-sonnet-4-6`）——以及自己的账户池和连接方法：导入 `agy` CLI token 文件（粘贴/上传）、��动检测本地 CLI 登录（`~/.gemini/antigravity-cli/antigravity-oauth-token`）、浏览器 OAuth 和批量/ZIP 导入。新路由：`POST /api/服务商/agy-认证/{import,import-bulk,zip-extract,apply-local}`。 -### Breaking Changes +### 破坏性变更 -- **proxy-logs:** `GET /api/usage/proxy-logs` now returns `clientIp` instead of `publicIp` for each log entry. External consumers reading `log.publicIp` must update to `log.clientIp`. The underlying SQLite column (`public_ip`) is unchanged, so callers that query the database directly are unaffected (#2880 — thanks @rdself). +- **proxy-logs:** `GET /api/usage/proxy-logs` 现在对每条日志返回 `clientIp` 而非 `publicIp`。读取 `log.publicIp` 的外部消费者必须更新为 `log.clientIp`。底层 SQLite 列（`public_ip`）保持不变，因此直接查询数据库的调用者不受影响 (#2880 — 感谢 @rdself)。 -### Known Inconsistency +### 已知不一致 -- **log-export:** `GET /api/logs/export?type=proxy-logs` returns raw SQLite rows whose IP field is still named `public_ip` (the historical column name). This differs from the `clientIp` field exposed by `GET /api/usage/proxy-logs`. The two endpoints are intentionally inconsistent for now and will be aligned in a future migration (#2880). +- **log-export:** `GET /api/logs/export?type=proxy-logs` 返回原始 SQLite 行，其 IP 字段仍名为 `public_ip`（历史列名）。这与 `GET /api/usage/proxy-logs` 暴露的 `clientIp` 字段不同。这两个端点目前故意不一致，将在未来的迁移中对齐 (#2880)。 ### ✨ 新功能 -- **usage:** add per-API-key token limits scoped to model/provider/global with two-tier inline enforcement and in-memory cache accelerator (#2888 — thanks @mugnimaestra). -- **providers:** audit web cookie providers, fix 4 missing registry entries, and add DuckDuckGo AI Chat provider (#2862 — thanks @oyi77). -- **compression:** expand pt-BR pack with 34 new rules inspired by the troglodita project (#2818 — thanks @leninejunior). +- **usage:** 新增按 API key 的 token 限制，可按模型/服务商/全局设定，支持两级内联执行和内存缓存加速 (#2888 — 感谢 @mugnimaestra)。 +- **providers:** 审查 web cookie 服务商，修复 4 个缺失的注册表条目，并新增 DuckDuckGo AI Chat 服务商 (#2862 — 感谢 @oyi77)。 +- **compression:** 扩展 pt-BR 语言包，新增 34 条受 troglodita 项目启发的规则 (#2818 — 感谢 @leninejunior)。 ### 🔧 问题修复 -- **oauth:** hotfix Windsurf login — drop dead PKCE flow, promote import-token, and resolve SQLite bind type errors (#2884 — thanks @yunaamelia). -- **models:** prune stale synced available models for inactive connections and dynamically map Antigravity MITM aliases loop-safely (#2886 — thanks @herjarsa). -- **antigravity:** harden signatureless tool history replay by making text representation inert (#2878 — thanks @dhaern). -- **i18n:** complete 144 missing Portuguese (pt-BR) locale keys and synchronize them with English (#2870 — thanks @alltomatos). -- **opencode-go:** add OpenCode Go provider limits quota fetcher to retrieve Z.AI quota windows (#2861 — thanks @RajvardhanPatil07). -- **reasoning:** gate reasoning trace replay injection on model interleaved capability metadata (#2843 — thanks @nickwizard). -- **audio:** construct multipart body manually for transcription form-data to prevent dropped boundary headers under Next.js fetch (#2842 — thanks @soyelmismo). -- **gemini-cli:** prefer real Google Cloud project IDs over default-project during model synchronization (#2841 — thanks @nickwizard). -- **mcp:** redirect console.log and console.warn startup messages to stderr in stdio MCP mode to prevent JSON-RPC parsing failures (#2840 — thanks @disonjer). -- **antigravity:** normalize unescaped tool calls and classify resource exhaustion 429 errors as lockout cooldowns (#2828 — thanks @Ardem2025). -- **sse:** repair RTK engine defaults to resolve consecutive-line deduplication and direct compression calls (#2825 — thanks @leninejunior). -- **fix(usage):** add opencode-go / opencode / opencode-zen quota fetcher so the provider limits page surfaces $12/5h, $30/wk, $60/mo windows alongside other quota-aware providers ([#2852](https://github.com/diegosouzapw/OmniRoute/issues/2852) — thanks @apoapostolov) +- **oauth:** 紧急修复 Windsurf 登录——移除已失效的 PKCE 流程、提升 import-token 方式，并解决 SQLite 绑定类型错误 (#2884 — 感谢 @yunaamelia)。 +- **models:** 清理非活跃连接中过期的同步可用模型，并安全地动态映射 Antigravity MITM 别名，避免循环引用 (#2886 — 感谢 @herjarsa)。 +- **antigravity:** 通过将文本表示设为惰性来加固无签名的工具历史重放 (#2878 — 感谢 @dhaern)。 +- **i18n:** 补全 144 个缺失的葡萄牙语 (pt-BR) 语言包 key 并与英语同步 (#2870 — 感谢 @alltomatos)。 +- **opencode-go:** 为 OpenCode Go 添加服务商限制配额获取器，以检索 Z.AI 配额窗口 (#2861 — 感谢 @RajvardhanPatil07)。 +- **reasoning:** 基于模型的交错能力元数据控制推理追踪重放注入 (#2843 — 感谢 @nickwizard)。 +- **audio:** 为转录 form-data 手动构建 multipart body，防止 Next.js fetch 下丢失边界头 (#2842 — 感谢 @soyelmismo)。 +- **gemini-cli:** 在模型同步期间优先使用真实的 Google Cloud 项目 ID 而非 default-project (#2841 — 感谢 @nickwizard)。 +- **mcp:** 在 stdio MCP 模式下将启动时的 console.log 和 console.warn 消息重定向到 stderr，防止 JSON-RPC 解析失败 (#2840 — 感谢 @disonjer)。 +- **antigravity:** 规范化未转义的 tool call 并将资源耗尽 429 错误归类为锁定冷却 (#2828 — 感谢 @Ardem2025)。 +- **sse:** 修复 RTK 引擎默认值，解决连续行去重和直接压缩调用的问题 (#2825 — 感谢 @leninejunior)。 +- **fix(usage):** 添加 opencode-go / opencode / opencode-zen 配额获取器，使服务商限制页面能显示 $12/5h、$30/wk、$60/mo 时间窗口及其他配额感知型服务商 ([#2852](https://github.com/diegosouzapw/OmniRoute/issues/2852) — 感谢 @apoapostolov) --- ## [3.8.6] — 2026-05-27 -### 🧹 Chores +### 🧹 维护 -- **gitignore:** ignore `.claude/settings.local.json` so per-user Claude Code permissions never get committed by accident -- **release:** version bump and metadata sync (package.json, package-lock.json, electron, open-sse, openapi.yaml) +- **gitignore:** 忽略 `.claude/settings.local.json`，防止每个用户的 Claude Code 权限被意外提交 +- **release:** 版本号提升和元数据同步 (package.json, package-lock.json, electron, open-sse, openapi.yaml) -> v3.8.6 is a maintenance/scaffolding patch. All feature and bug-fix work from the post-v3.8.5 cycle (44 commits — community PRs #2777, #2782–#2787, #2789, #2790, plus internal hotfixes) was already integrated into v3.8.5 and is documented under that section. +> v3.8.6 是一个维护/脚手架补丁。v3.8.5 之后周期的所有功能和问题修复工作（44 次提交——社区 PR #2777、#2782–#2787、#2789、#2790 以及内部紧急修复）已全部合并到 v3.8.5 中，并在该版本章节中记录。 --- @@ -1608,18 +1591,18 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ### 🔒 安全 -- **authz:** redirect `/home` and `/home/:path*` to `/login` when unauthenticated (#2712) +- **authz:** 未认证时将 `/home` 和 `/home/:path*` 重定向到 `/login` (#2712) ### 🔧 问题修复 -- **mcp:** break callLogs ↔ compliance ESM cycle that deadlocks the bundled MCP server on Node.js 24 (#2650) -- **deepseek:** guard PoW solver Web Worker handler under Node strict mode (#2724) -- **combos:** include no-auth providers in the combo builder picker (#2737) -- **translator:** allow the `web_search` server-tool family in the Responses API translator (#2695) -- **oauth:** register the missing `trae` provider with `import_token` flow (#2658) -- **model:** merge settings-based aliases with the legacy DB alias namespace (#2618, #2208) -- **kiro:** clipboard fallback for HTTP / non-secure contexts (#2689) -- **cli:** raise `omniroute serve` ready timeout to 60s with TCP fallback for Windows cold start (#2460) +- **mcp:** 打破 callLogs ↔ compliance 的 ESM 循环依赖，该循环导致打包后的 MCP 服务器在 Node.js 24 上死锁 (#2650) +- **deepseek:** 在 Node 严格模式下保护 PoW 求解器 Web Worker 处理器 (#2724) +- **combos:** 在 combo 构建器选择器中包含免认证服务商 (#2737) +- **translator:** 在 Responses API 翻译器中允许 `web_search` 服务端工具族 (#2695) +- **oauth:** 注册缺失的 `trae` 服务商，使用 `import_token` 流程 (#2658) +- **model:** 将基于设置的别名与旧版 DB 别名命名空间合并 (#2618, #2208) +- **kiro:** HTTP / 非安全上下文的剪贴板回退 (#2689) +- **cli:** 将 `omniroute serve` 就绪超时提升到 60s，并为 Windows 冷启动添加 TCP 回退 (#2460) --- @@ -1639,7 +1622,7 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ## [3.8.4] — 2026-05-25 -### Added +### 新增 - Embedded services (work in progress — 9Router, CLIProxyAPI; see T-15 for full entry). @@ -1649,35 +1632,35 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ### ✨ 新功能 -- **feat(combos):** universal context handoff for cross-model conversation continuity — structured XML summary system (``) that preserves conversation continuity and handles state transfer when combo routing switches models. ([#2653](https://github.com/diegosouzapw/OmniRoute/pull/2653) — thanks @herjarsa) -- **feat(docs):** migrate `/docs` to Fumadocs MDX with nested routes — replaces the custom docs engine with Fumadocs, adding `[...slug]` catch-all routing, search API at `/docs/api/search`, `source.config.ts` content configuration, and `meta.json` navigation files across 8 doc sections (`architecture/`, `compression/`, `frameworks/`, `guides/`, `ops/`, `reference/`, `routing/`, `security/`). Includes 50+ URL redirects for backward compatibility via `next.config.mjs`. ([#2614](https://github.com/diegosouzapw/OmniRoute/pull/2614) — thanks @ovehbe) -- **feat(dashboard):** add search and filters to `/dashboard/api-manager` — filter bar with search by name/key, active-only toggle (persisted to localStorage), status filter (active/disabled/banned/expired), type filter (standard/manage/restricted), filter count badges, and empty state with "Clear Filters" button. ([#2628](https://github.com/diegosouzapw/OmniRoute/pull/2628) / [#2641](https://github.com/diegosouzapw/OmniRoute/pull/2641) — thanks @diegosouzapw) -- **feat(dashboard):** free-tier grouping with symbolic link in `/dashboard/providers` — groups and displays all free-tier providers from all categories dynamically using `hasFree: true` properties without removing them from their native lists. Displays category dot and amber dot with localizable tooltips, dedupes search results by provider ID, and corrects free tier count statistics. ([#2632](https://github.com/diegosouzapw/OmniRoute/pull/2632) — thanks @diegosouzapw) -- **feat(dashboard):** risk notice modal for sensitive providers — show a soft, informative warning modal when connecting to session-based or OAuth providers (like Claude, Cursor, Copilot) for the first time. Adds `subscriptionRisk` properties to 20 providers, localizable templates, and stores acknowledgment in localStorage. ([#2633](https://github.com/diegosouzapw/OmniRoute/pull/2633) / [#2638](https://github.com/diegosouzapw/OmniRoute/pull/2638) — thanks @diegosouzapw) -- **feat(dashboard):** refactor free-tier provider dashboard layout — cleans up visual clutter, reorganizes categories, hides redundant banners, and integrates free-tier categories nicely into the primary provider interface. ([#2640](https://github.com/diegosouzapw/OmniRoute/pull/2640) — thanks @diegosouzapw) -- **feat(dashboard):** mini-playground inline (Phase 4) — integrated interactive mini-playground capabilities to provider details pages, including support for specialized example cards (Embedding, Image, LLM Chat, Music, STT, TTS, Video, Web Fetch, Web Search), unified API key loading hooks, model listing hooks, and curl command builder. ([#2648](https://github.com/diegosouzapw/OmniRoute/pull/2648) — thanks @diegosouzapw) -- **feat(webfetch):** category support with dedicated media providers page and executors for Firecrawl, Jina Reader, and Tavily. ([#2645](https://github.com/diegosouzapw/OmniRoute/pull/2645) — thanks @diegosouzapw) -- **feat(adapta):** integrate Adapta Org (`adapta-web`) provider with automatic Clerk authentication refresh and custom onboarding tutorial modal. ([#2643](https://github.com/diegosouzapw/OmniRoute/pull/2643) — thanks @df4p) -- **feat(i18n):** complete translations for Simplified Chinese — translates 1220 missing keys bringing UI coverage to 98.8% with 0 placeholders. ([#2655](https://github.com/diegosouzapw/OmniRoute/pull/2655) — thanks @L-aros) +- **feat(combos):** 通用上下文交接，实现跨模型对话连续性 — 结构化 XML 摘要系统 (``)，在 Combo 路由切换模型时保持对话连续性并处理状态转移。([#2653](https://github.com/diegosouzapw/OmniRoute/pull/2653) — 感谢 @herjarsa) +- **feat(docs):** 将 `/docs` 迁移到 Fumadocs MDX，支持嵌套路由 — 用 Fumadocs 替换自定义文档引擎，新增 `[...slug]` 通配路由、`/docs/api/搜索` 搜索 API、`source.配置.ts` 内容配置，以及 8 个文档分区的 `meta.json` 导航文件（`architecture/`、`压缩/`、`frameworks/`、`guides/`、`ops/`、`reference/`、`路由/`、`security/`）。包含 50+ 个 URL 重定向以确保向后兼容。([#2614](https://github.com/diegosouzapw/OmniRoute/pull/2614) — 感谢 @ovehbe) +- **feat(dashboard):** 为 `/dashboard/api-manager` 添加搜索和过滤功能 — 过滤栏支持按名称/key 搜索、仅活跃开关（持久化到 localStorage）、状态过滤（活跃/禁用/封禁/过期）、类型过滤（标准/管理/受限）、过滤计数徽章，以及带 "清除过滤" 按钮的空状态。([#2628](https://github.com/diegosouzapw/OmniRoute/pull/2628) / [#2641](https://github.com/diegosouzapw/OmniRoute/pull/2641) — 感谢 @diegosouzapw) +- **feat(dashboard):** `/dashboard/providers` 中的免费层分组及符号链接 — 使用 `hasFree: true` 属性动态分组显示所有类别的免费层服务商，不将其从原生列表中移除。显示类别圆点和琥珀色圆点及可本地化提示，按服务商 ID 去重搜索结果，修正免费层计数统计。([#2632](https://github.com/diegosouzapw/OmniRoute/pull/2632) — 感谢 @diegosouzapw) +- **feat(dashboard):** 敏感服务商风险提示弹窗 — 首次连接到基于会话或 OAuth 的服务商（如 Claude、Cursor、Copilot）时显示温和的信息警告弹窗。为 20 个服务商添加 `subscriptionRisk` 属性、可本地化模板，并将确认信息存储到 localStorage。([#2633](https://github.com/diegosouzapw/OmniRoute/pull/2633) / [#2638](https://github.com/diegosouzapw/OmniRoute/pull/2638) — 感谢 @diegosouzapw) +- **feat(dashboard):** 重构免费层服务商仪表盘布局 — 清理视觉杂乱、重新组织类别、隐藏冗余横幅，将免费层类别优雅集成到主服务商界面。([#2640](https://github.com/diegosouzapw/OmniRoute/pull/2640) — 感谢 @diegosouzapw) +- **feat(dashboard):** 内联迷你工作室（第四阶段）— 在服务商详情页集成交互式迷你工作室功能，包括专业示例卡片（Embedding、Image、LLM Chat、Music、STT、TTS、Video、Web Fetch、Web Search）、统一的 API Key 加载钩子、模型列表钩子和 curl 命令构建器。([#2648](https://github.com/diegosouzapw/OmniRoute/pull/2648) — 感谢 @diegosouzapw) +- **feat(webfetch):** 分类支持，含专用媒体服务商页面和 Firecrawl、Jina Reader、Tavily 的执行器。([#2645](https://github.com/diegosouzapw/OmniRoute/pull/2645) — 感谢 @diegosouzapw) +- **feat(adapta):** 集成 Adapta Org (`adapta-web`) 服务商，支持自动 Clerk 认证刷新和自定义引导教程弹窗。([#2643](https://github.com/diegosouzapw/OmniRoute/pull/2643) — 感谢 @df4p) +- **feat(i18n):** 完成简体中文翻译 — 翻译 1220 个缺失 key，UI 覆盖率达 98.8%，零占位符。([#2655](https://github.com/diegosouzapw/OmniRoute/pull/2655) — 感谢 @L-aros) ### 🔧 问题修复 -- **fix(settings):** Require Login modal Cancel button text and dismissal — modal now renders localized cancel label via the `common` namespace and closes correctly without modifying settings when cancelled. ([#2649](https://github.com/diegosouzapw/OmniRoute/pull/2649) — thanks @Chewji9875) -- **fix(deepseek-web):** re-apply SSE parser, prompt format, and error handling fixes — handles all 3 DeepSeek SSE stream formats (initial fragments, APPEND operations, bare string tokens), uses non-greedy regex for markdown image stripping, simplifies prompt to single-turn, checks `json.code` before token extraction, and uses `accessToken` fallback for session cache eviction on auth errors. ([#2616](https://github.com/diegosouzapw/OmniRoute/pull/2616) — thanks @ovehbe) -- **fix(deepseek-web):** SSE thinking/search routing and session lifecycle — properly routes thinking vs content fragments based on `thinking_enabled` flag, handles search results with citation indices, appends search result footnotes, refactors `transformSSE()` and `collectSSEContent()` with shared helpers. ([#2624](https://github.com/diegosouzapw/OmniRoute/pull/2624) — thanks @ovehbe) -- **fix(codex):** use allowlist to strip non-Responses-API fields in non-passthrough path — strips residual Chat Completions fields (`stream_options`, `service_tier`, `store`, `metadata`) from the request body when routing through the non-passthrough (translation) code path, preventing GPT-5.5 from receiving invalid parameters. ([#2615](https://github.com/diegosouzapw/OmniRoute/pull/2615) — thanks @diegosouzapw) -- **fix(catalog):** skip static PROVIDER_MODELS when synced models exist — prevents stale/duplicate model entries in `/v1/models` for auto-synced providers. ([#2625](https://github.com/diegosouzapw/OmniRoute/pull/2625) — thanks @herjarsa) -- **fix(qoder):** Cosy auth fallback for PAT tokens + vision support for qwen3-vl-plus — when a PAT token gets 401, falls back to Cosy auth against `api1.qoder.sh`; adds `supportsVision: true` to qwen3-vl-plus. ([#2629](https://github.com/diegosouzapw/OmniRoute/pull/2629) — thanks @herjarsa) -- **fix(cli):** register tsx loader and add opencode config subcommand — registers `tsx/esm` at CLI startup so dynamic `.ts` imports resolve; adds `omniroute config opencode` convenience alias. ([#2631](https://github.com/diegosouzapw/OmniRoute/pull/2631) — thanks @amogus22877769) -- **fix(claude):** improve Pi and OpenCode compatibility — adds Pi Coding Agent anchors to system transform removal, stores `_toolNameMap` as non-enumerable, strips `context_management` when thinking is disabled. ([#2621](https://github.com/diegosouzapw/OmniRoute/pull/2621) — thanks @unitythemaker) -- **fix(passthrough):** restore semantic passthrough system-role-only extraction — reverts full `normalizeClaudeUpstreamMessages()` to lighter `extractSystemRoleMessages()` in CC semantic passthrough paths, preventing document/tool chain corruption. ([#2620](https://github.com/diegosouzapw/OmniRoute/pull/2620) — thanks @Tentoxa) -- **fix(kiro):** stabilize conversationId across prompt compression — captures pre-compression body and uses the original first user message as seed for UUID v5, keeping Kiro's AWS conversation context stable. ([#2630](https://github.com/diegosouzapw/OmniRoute/pull/2630) — thanks @HALDRO) -- **fix(t3-chat-web):** close implementation gaps for t3.chat TanStack Start, tracking of stream_options, and retry configurations — parses TSS Turbo Stream Serialization from `_serverFn/*`, tracks request `combo_strategy` via database migration `062_usage_history_combo_strategy.sql`, and makes batch retry backoffs custom-configurable via environment variables. ([#2634](https://github.com/diegosouzapw/OmniRoute/pull/2634) — thanks @oyi77) -- **fix(reasoning):** extend empty `reasoning_content` injection to prevent tool call loops in Kimi K2 and replay models — injects empty `reasoning_content` field to Kimi models during tool-calling sequences to bypass loop issues. ([#2639](https://github.com/diegosouzapw/OmniRoute/pull/2639) — thanks @herjarsa) -- **fix(cli):** Linux autostart via systemd user service on headless VPS — adds auto-generating systemd user service unit for headless setups on Linux, updating tray configs and system variables allowlist (`LOGNAME` and `XDG_CURRENT_DESKTOP`). ([#2635](https://github.com/diegosouzapw/OmniRoute/pull/2635) — thanks @janeza2) -- **fix(combo):** preserve `` tag in SSE stream output for combos when using `context_cache_protection` to ensure correct context pinning round-trips. ([#2646](https://github.com/diegosouzapw/OmniRoute/pull/2646) — thanks @herjarsa) -- **fix(rtk):** prevent false positives in RTK compression by skipping content-based filter matching for non-shell tool results (e.g. read_file, grep_search). ([#2642](https://github.com/diegosouzapw/OmniRoute/pull/2642) — thanks @HALDRO) -- **fix(translator):** enable Claude extended thinking for Copilot Responses-API requests — handles reasoning budget and translations for Copilot. ([#2647](https://github.com/diegosouzapw/OmniRoute/pull/2647) — thanks @ivan-mezentsev) +- **fix(settings):** Require Login modal Cancel button text and dismissal — modal now renders localized cancel label via the `common` namespace and closes correctly without modifying settings when cancelled. ([#2649](https://github.com/diegosouzapw/OmniRoute/pull/2649) — 感谢 @Chewji9875) +- **fix(deepseek-web):** re-apply SSE parser, prompt format, and error handling fixes — handles all 3 DeepSeek SSE 流 formats (initial fragments, APPEND operations, bare string tokens), uses non-greedy regex for markdown image stripping, simplifies 提示 to single-turn, checks `json.code` before token extraction, and uses `accessToken` 容灾 for 会话 缓存 eviction on 认证 errors. ([#2616](https://github.com/diegosouzapw/OmniRoute/pull/2616) — 感谢 @ovehbe) +- **fix(deepseek-web):** SSE thinking/search routing and session lifecycle — properly routes thinking vs content fragments based on `thinking_enabled` 标志, handles 搜索 results with citation indices, appends 搜索 result footnotes, refactors `transformSSE()` and `collectSSEContent()` with shared helpers. ([#2624](https://github.com/diegosouzapw/OmniRoute/pull/2624) — 感谢 @ovehbe) +- **fix(codex):** use allowlist to strip non-Responses-API fields in non-passthrough path — strips residual Chat Completions fields (`stream_options`, `service_tier`, `store`, `metadata`) from the 请求 body when 路由 through the non-passthrough (translation) code path, preventing GPT-5.5 from receiving invalid parameters. ([#2615](https://github.com/diegosouzapw/OmniRoute/pull/2615) — 感谢 @diegosouzapw) +- **fix(catalog):** skip static PROVIDER_MODELS when synced models exist — prevents stale/duplicate 模型 entries in `/v1/模型` for auto-synced 服务商. ([#2625](https://github.com/diegosouzapw/OmniRoute/pull/2625) — 感谢 @herjarsa) +- **fix(qoder):** Cosy auth fallback for PAT tokens + vision support for qwen3-vl-plus — when a PAT token gets 401, falls back to Cosy 认证 against `api1.qoder.sh`; adds `supportsVision: true` to qwen3-vl-plus. ([#2629](https://github.com/diegosouzapw/OmniRoute/pull/2629) — 感谢 @herjarsa) +- **fix(cli):** register tsx loader and add opencode config subcommand — registers `tsx/esm` at CLI startup so dynamic `.ts` imports resolve; adds `omniroute 配置 opencode` convenience alias. ([#2631](https://github.com/diegosouzapw/OmniRoute/pull/2631) — 感谢 @amogus22877769) +- **fix(claude):** improve Pi and OpenCode compatibility — adds Pi Coding Agent anchors to system transform removal, stores `_toolNameMap` as non-enumerable, strips `context_management` when thinking is disabled. ([#2621](https://github.com/diegosouzapw/OmniRoute/pull/2621) — 感谢 @unitythemaker) +- **fix(passthrough):** restore semantic passthrough system-role-only extraction — reverts full `normalizeClaudeUpstreamMessages()` to lighter `extractSystemRoleMessages()` in CC semantic passthrough paths, preventing document/tool chain corruption. ([#2620](https://github.com/diegosouzapw/OmniRoute/pull/2620) — 感谢 @Tentoxa) +- **fix(kiro):** stabilize conversationId across prompt compression — captures pre-压缩 body and uses the original first 用户消息 as seed for UUID v5, keeping Kiro's AWS conversation context stable. ([#2630](https://github.com/diegosouzapw/OmniRoute/pull/2630) — 感谢 @HALDRO) +- **fix(t3-chat-web):** close implementation gaps for t3.chat TanStack Start, tracking of stream_options, and retry configurations — parses TSS Turbo Stream Serialization from `_serverFn/*`, tracks 请求 `combo_strategy` via 数据库 迁移 `062_usage_history_combo_strategy.sql`, and makes batch 重试 backoffs custom-configurable via environment variables. ([#2634](https://github.com/diegosouzapw/OmniRoute/pull/2634) — 感谢 @oyi77) +- **fix(reasoning):** extend empty `reasoning_content` injection to prevent tool call loops in Kimi K2 and replay models — injects empty `reasoning_content` 字段 to Kimi 模型 during tool-calling sequences to bypass loop issues. ([#2639](https://github.com/diegosouzapw/OmniRoute/pull/2639) — 感谢 @herjarsa) +- **fix(cli):** Linux autostart via systemd user service on headless VPS — adds auto-generating systemd user service unit for headless setups on Linux, updating tray configs and system variables allowlist (`LOGNAME` and `XDG_CURRENT_DESKTOP`). ([#2635](https://github.com/diegosouzapw/OmniRoute/pull/2635) — 感谢 @janeza2) +- **fix(combo):** preserve `` tag in SSE stream output for combos when using `context_cache_protection` to ensure correct context pinning round-trips. ([#2646](https://github.com/diegosouzapw/OmniRoute/pull/2646) — 感谢 @herjarsa) +- **fix(rtk):** prevent false positives in RTK compression by skipping content-based filter matching for non-shell tool results (e.g. read_file, grep_search). ([#2642](https://github.com/diegosouzapw/OmniRoute/pull/2642) — 感谢 @HALDRO) +- **fix(translator):** enable Claude extended thinking for Copilot Responses-API requests — handles reasoning 预算 and translations for Copilot. ([#2647](https://github.com/diegosouzapw/OmniRoute/pull/2647) — 感谢 @ivan-mezentsev) - **fix(tests):** remove duplicate assertion in schema coercion & fix(cli): ignore system vars in env check. (thanks @diegosouzapw) ### 📝 维护 @@ -1691,112 +1674,112 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ### ✨ 新功能 -- **feat(@omniroute/opencode-plugin):** upstream-provider suffix in model display name — appends provider label to enriched names (e.g. `Claude Opus 4.7 · Claude` vs `Claude Opus 4.7 · Kiro`) so the OC TUI model picker can differentiate same-id models routed through different upstream connections. Default-on, opt-out via `features.providerTag: false`. ([#2602](https://github.com/diegosouzapw/OmniRoute/pull/2602) — thanks @mrmm) -- **feat(@omniroute/opencode-plugin):** provider-tag becomes a prefix + traffic-light compression emoji — provider label now prepends (`Claude - Claude Opus 4.7`) for better TUI column grouping, with smart abbreviation for long labels (`GitHub Models` → `GHM`). Compression pipelines render intensity as emoji (🟢🟡🟠🔴). ([#2604](https://github.com/diegosouzapw/OmniRoute/pull/2604) — thanks @mrmm) -- **feat(providers):** add 7 free-tier providers (Wave 1) — Arcee AI, InclusionAI, Krutrim, Liquid AI, MonsterAPI, Nomic, and Poolside now available as new API-key providers with provider icons, model specs, and full routing support. ([#2479](https://github.com/diegosouzapw/OmniRoute/pull/2479) — thanks @oyi77) -- **feat(providers):** add Astraflow provider support with global + China endpoints — new provider with dual-region base URLs for global and mainland China access. ([#2486](https://github.com/diegosouzapw/OmniRoute/pull/2486) — thanks @ucloudnb666) -- **feat(providers):** add `claude-web` provider — cookie-based Claude Web chat access without OAuth. ([#2476](https://github.com/diegosouzapw/OmniRoute/pull/2476) — thanks @oyi77) -- **feat(providers):** add 14 free-tier providers (Wave 1b) — 360AI, Baichuan, Baidu, ByteDance/Doubao, IDEO, Kuaishou/Kling, Kunlun/Skywork, SenseTime/SenseNova, Stepfun, Tencent HunYuan, Zhipu GLM, Replicate, RunPod, and Modal with provider icons, model specs, and routing support. ([#2488](https://github.com/diegosouzapw/OmniRoute/pull/2488) — thanks @oyi77) -- **feat(hermes):** add rich multi-role Hermes Agent CLI support — 7 configurable roles (default, delegation, vision, compression, web_extract, skills_hub, approval), per-role model selection with YAML config generation, dashboard card with preview, and home widget integration. ([#2526](https://github.com/diegosouzapw/OmniRoute/pull/2526) — thanks @apoapostolov) -- **feat(cloud-agents):** cloud agents UX overhaul — tabs (tasks/agents/settings), status filters, Material icons, duration formatting, cloud agent credentials and health API endpoints, memory stats endpoint. ([#2516](https://github.com/diegosouzapw/OmniRoute/pull/2516) — thanks @oyi77) -- **feat(authz):** manage-scope API keys may reach `/api/mcp/*` from non-loopback — Route Guard Tiers system (LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT), narrow carve-out for remote MCP access gated by `manage` scope; `/api/cli-tools/runtime/*` stays strict-loopback. Includes dashboard AuthzSection, inventory API, and comprehensive docs. ([#2473](https://github.com/diegosouzapw/OmniRoute/pull/2473) — thanks @mrmm) -- **feat(home):** home page customization for experienced users — pin Provider Quota to home, toggle Quick Start and Provider Topology visibility via Appearance settings. ([#2531](https://github.com/diegosouzapw/OmniRoute/pull/2531) — thanks @apoapostolov) -- **feat(home):** automatic refresh of Provider Quota — configurable interval (60s–600s) with toggle in Appearance settings; auto-refreshes pinned quota on the home page. ([#2532](https://github.com/diegosouzapw/OmniRoute/pull/2532) — thanks @apoapostolov) -- **feat(@omniroute/opencode-plugin):** OmniRoute OpenCode plugin — live models fetched from OmniRoute API, combo-aware model listing, Gemini request sanitization, multi-instance support, auth flow integration, and 10 test files. ([#2529](https://github.com/diegosouzapw/OmniRoute/pull/2529) — thanks @mrmm) -- **feat(executors):** forward OpenCode client headers to upstream providers — OpenCode-specific headers are now forwarded through the executor pipeline for improved compatibility. ([#2538](https://github.com/diegosouzapw/OmniRoute/pull/2538) — thanks @kang-heewon) -- **feat(fireworks):** add new models with `modelIdPrefix` support — generic registry field that stores short model IDs and prepends the full path prefix before upstream API calls. Adds 6 new Fireworks models, `modelsUrl` for dynamic sync, and Qwen3 reranker. ([#2560](https://github.com/diegosouzapw/OmniRoute/pull/2560) — thanks @HALDRO) -- **feat(@omniroute/opencode-plugin):** readable + filterable + offline-resilient model picker — `usableOnly` filter (only show providers with healthy connections), `diskCache` for offline hydration, `Combo:` prefix labeling, and compression metadata tags in combo display names. ([#2572](https://github.com/diegosouzapw/OmniRoute/pull/2572) — thanks @mrmm) -- **feat(smart-pipeline):** multi-stage pipeline for auto combo routing — rule-based + intent-classifier + domain-specific stages with configurable pipeline router, accuracy benchmarks, and comprehensive tests. ([#2551](https://github.com/diegosouzapw/OmniRoute/pull/2551) — thanks @oyi77) -- **feat(ops):** skip DB health check on startup via `OMNIROUTE_SKIP_DB_HEALTHCHECK=1` — replaces slow `integrity_check` (7+ min on large WAL) with `quick_check`, and adds env var to skip entirely. ([#2554](https://github.com/diegosouzapw/OmniRoute/pull/2554) — thanks @soyelmismo) -- **refactor(dashboard):** Provider Quota grouped layout with vertical rail — restructures the page to a 2-column per-provider layout (left rail with icon/name/status, right content with dynamic per-provider columns), new `providerColumns.ts` / `ProviderGroup.tsx` / `AccountRow.tsx` components, env chip-filter row, bulk-refresh per group, and inline expanded panels. ([#2528](https://github.com/diegosouzapw/OmniRoute/pull/2528) — thanks @Gi99lin) -- **feat(providers):** add 26 free-tier providers missing from registry — Novita, Avian, Chutes, Kluster, Targon, Nineteen, Celery, Ditto, Atoma, and more. ([#2590](https://github.com/diegosouzapw/OmniRoute/pull/2590) — thanks @oyi77) -- **feat(providers):** add api-airforce free provider with 55 models. ([#2587](https://github.com/diegosouzapw/OmniRoute/pull/2587) — thanks @oyi77) -- **feat(dashboard):** configurable sidebar — presets, drag-and-drop ordering, smart-grouping, and new Settings → Sidebar page. ([#2581](https://github.com/diegosouzapw/OmniRoute/pull/2581) — thanks @Gi99lin) +- **feat(@omniroute/opencode-plugin):** 模型显示名称中添加上游服务商后缀 — 在丰富名称后追加服务商标签（如 `Claude Opus 4.7 · Claude` vs `Claude Opus 4.7 · Kiro`），使 OC TUI 模型选择器能区分通过不同上游连接路由的同 ID 模型。默认开启，可通过 `features.providerTag: false` 关闭。([#2602](https://github.com/diegosouzapw/OmniRoute/pull/2602) — 感谢 @mrmm) +- **feat(@omniroute/opencode-plugin):** 服务商标签改为前缀 + 交通灯压缩表情 — 服务商标签现在前置显示（`Claude - Claude Opus 4.7`）以改善 TUI 列分组，长标签智能缩写（`GitHub Models` → `GHM`）。压缩管线以表情渲染强度（🟢🟡🟠🔴）。([#2604](https://github.com/diegosouzapw/OmniRoute/pull/2604) — 感谢 @mrmm) +- **feat(providers):** 新增 7 个免费层服务商（第一波）— Arcee AI、InclusionAI、Krutrim、Liquid AI、MonsterAPI、Nomic 和 Poolside 现已作为新的 API-key 服务商提供，包含服务商图标、模型规格和完整路由支持。([#2479](https://github.com/diegosouzapw/OmniRoute/pull/2479) — 感谢 @oyi77) +- **feat(providers):** 新增 Astraflow 服务商支持，含全球 + 中国端点 — 新服务商提供双区域基础 URL，支持全球和中国大陆访问。([#2486](https://github.com/diegosouzapw/OmniRoute/pull/2486) — 感谢 @ucloudnb666) +- **feat(providers):** 新增 `claude-web` 服务商 — 基于 Cookie 的 Claude Web 聊天访问，无需 OAuth。([#2476](https://github.com/diegosouzapw/OmniRoute/pull/2476) — 感谢 @oyi77) +- **feat(providers):** 新增 14 个免费层服务商（第一波 b）— 360AI、百川、百度、字节/豆包、IDEO、快手/可灵、昆仑/Skywork、商汤/SenseNova、阶跃星辰、腾讯混元、智谱 GLM、Replicate、RunPod 和 Modal，包含服务商图标、模型规格和路由支持。([#2488](https://github.com/diegosouzapw/OmniRoute/pull/2488) — 感谢 @oyi77) +- **feat(hermes):** 新增丰富的多角色 Hermes Agent CLI 支持 — 7 个可配置角色（default、delegation、vision、compression、web_extract、skills_hub、approval），每个角色可选择模型并生成 YAML 配置，仪表盘卡片带预览和首页小组件集成。([#2526](https://github.com/diegosouzapw/OmniRoute/pull/2526) — 感谢 @apoapostolov) +- **feat(cloud-agents):** 云端 Agent UX 全面改版 — 标签页（tasks/agents/settings）、状态过滤器、Material 图标、时长格式化、云端 Agent 凭证和健康 API 端点、内存统计端点。([#2516](https://github.com/diegosouzapw/OmniRoute/pull/2516) — 感谢 @oyi77) +- **feat(authz):** 具有 manage 作用域的 API key 可从非本地地址访问 `/api/mcp/*` — Route Guard Tiers 系统（LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT），为受 `manage` 作用域控制的远程 MCP 访问开辟窄通道；`/api/cli-tools/runtime/*` 保持严格本地限制。包含仪表盘 AuthzSection、清单 API 和完整文档。([#2473](https://github.com/diegosouzapw/OmniRoute/pull/2473) — 感谢 @mrmm) +- **feat(home):** 为高级用户定制首页 — 将服务商配额固定到首页，通过外观设置开关快速入门和服务商拓扑的可见性。([#2531](https://github.com/diegosouzapw/OmniRoute/pull/2531) — 感谢 @apoapostolov) +- **feat(home):** 服务商配额自动刷新 — 可配置间隔（60s–600s），在外观设置中可开关；自动刷新固定在首页的配额信息。([#2532](https://github.com/diegosouzapw/OmniRoute/pull/2532) — 感谢 @apoapostolov) +- **feat(@omniroute/opencode-plugin):** OmniRoute OpenCode 插件 — 从 OmniRoute API 获取实时模型，Combo 感知的模型列表，Gemini 请求清洗，多实例支持，认证流程集成，以及 10 个测试文件。([#2529](https://github.com/diegosouzapw/OmniRoute/pull/2529) — 感谢 @mrmm) +- **feat(executors):** 将 OpenCode 客户端头转发到上游服务商 — OpenCode 特定头现在通过 executor 管线转发以改善兼容性。([#2538](https://github.com/diegosouzapw/OmniRoute/pull/2538) — 感谢 @kang-heewon) +- **feat(fireworks):** 新增模型并支持 `modelIdPrefix` — 通用注册表字段，存储短模型 ID 并在上游 API 调用前拼接完整路径前缀。新增 6 个 Fireworks 模型、`modelsUrl` 动态同步和 Qwen3 重排序器。([#2560](https://github.com/diegosouzapw/OmniRoute/pull/2560) — 感谢 @HALDRO) +- **feat(@omniroute/opencode-plugin):** 可读 + 可过滤 + 离线韧性模型选择器 — `usableOnly` 过滤器（仅显示连接健康的服务商）、`diskCache` 离线水合、`Combo:` 前缀标签、压缩元数据标签。([#2572](https://github.com/diegosouzapw/OmniRoute/pull/2572) — 感谢 @mrmm) +- **feat(smart-pipeline):** 自动 Combo 路由的多阶段管线 — 基于规则 + 意图分类器 + 领域特定阶段，含可配置管线路由器、准确率基准测试和全面测试。([#2551](https://github.com/diegosouzapw/OmniRoute/pull/2551) — 感谢 @oyi77) +- **feat(ops):** 通过 `OMNIROUTE_SKIP_DB_HEALTHCHECK=1` 跳过启动时 DB 健康检查 — 将缓慢的 `integrity_check`（大 WAL 上需 7 分钟以上）替换为 `quick_check`，并添加环境变量以完全跳过。([#2554](https://github.com/diegosouzapw/OmniRoute/pull/2554) — 感谢 @soyelmismo) +- **refactor(dashboard):** 服务商配额分组布局，含垂直侧栏 — 将页面重构为每个服务商 2 列布局（左侧栏含图标/名称/状态，右侧内容含动态按服务商列），新增 `providerColumns.ts` / `ProviderGroup.tsx` / `AccountRow.tsx` 组件，环境芯片过滤行，按组批量刷新和内联展开面板。([#2528](https://github.com/diegosouzapw/OmniRoute/pull/2528) — 感谢 @Gi99lin) +- **feat(providers):** 新增注册表中缺失的 26 个免费层服务商 — Novita、Avian、Chutes、Kluster、Targon、Nineteen、Celery、Ditto、Atoma 等。([#2590](https://github.com/diegosouzapw/OmniRoute/pull/2590) — 感谢 @oyi77) +- **feat(providers):** 新增 api-airforce 免费服务商，含 55 个模型。([#2587](https://github.com/diegosouzapw/OmniRoute/pull/2587) — 感谢 @oyi77) +- **feat(dashboard):** 可配置侧边栏 — 预设、拖拽排序、智能分组，以及新的设置 → 侧边栏页面。([#2581](https://github.com/diegosouzapw/OmniRoute/pull/2581) — 感谢 @Gi99lin) ### 🔧 问题修复 -- **fix(validation):** stop appending a second `/models` when the Gemini base URL already ends in `/models` — Google AI Studio connections using the default base URL were validating against `.../v1beta/models/models` and failing with `404` for every connection. ([#2545](https://github.com/diegosouzapw/OmniRoute/issues/2545)) -- **fix(cloudflare-ai):** flatten OpenAI content-part arrays to plain strings for the Workers AI (`cf/`) executor — Workers AI's `/ai/v1/chat/completions` rejects `content: [{type:"text",...}]` with HTTP 400, so requests with array content now have their text parts joined into a string. ([#2539](https://github.com/diegosouzapw/OmniRoute/issues/2539)) -- **fix(i18n):** replace leftover Portuguese strings in the English source with English on the Quota dashboards — the quota-share Beta notice (`betaConfigSaved*`) and the Provider Quota row's `Edit cutoffs` / `Refresh now` fallbacks were showing Portuguese. ([#2540](https://github.com/diegosouzapw/OmniRoute/issues/2540)) - -- **fix(proxy):** honor the legacy per-provider/global proxy config in `resolveProxyForProvider` — the Claude OAuth token exchange and token refresh only consulted the new proxy registry, so a proxy configured the legacy way (`/api/settings/proxy?level=provider`) was ignored and the exchange went out directly from the host, tripping Anthropic's IP `rate_limit_error` on VPS deployments. It now falls back to the legacy config, mirroring `resolveProxyForConnection`. ([#2456](https://github.com/diegosouzapw/OmniRoute/issues/2456)) -- **fix(antigravity):** auto-discover a missing Cloud Code `projectId` via `loadCodeAssist` before failing — a freshly re-added Antigravity account whose stored `projectId` was empty (OAuth-time discovery returned nothing) now recovers the project on the first request instead of returning `422 Missing Google projectId`, mirroring the `gemini-cli` bootstrap. ([#2334](https://github.com/diegosouzapw/OmniRoute/issues/2334), [#2541](https://github.com/diegosouzapw/OmniRoute/issues/2541)) -- **fix(stream):** keep the `/v1/responses` SSE connection warm for strict clients — emit an early keepalive while the upstream produces its first token and lower the heartbeat cadence to 4s, so Codex CLI's `reqwest` client (≈5s idle-read timeout) no longer drops the stream "before completion" on slow/reasoning models. `curl` was unaffected because it has no idle timeout. ([#2544](https://github.com/diegosouzapw/OmniRoute/issues/2544)) -- **fix(electron):** wait longer for the server on first launch and reload once it responds — long post-upgrade DB migrations could exceed the 30s readiness probe, leaving the desktop app stuck on the "Server starting" screen even though the backend was healthy. The probe now targets the auth-exempt health endpoint with a generous timeout and reloads the window once the server comes up. ([#2460](https://github.com/diegosouzapw/OmniRoute/issues/2460)) - -- **fix(cli):** mark `bin/omniroute.mjs` as executable (mode 755) so the globally-installed CLI runs directly without a manual `chmod +x`. ([#2469](https://github.com/diegosouzapw/OmniRoute/issues/2469) — thanks @disonjer) -- **fix(settings):** restore the Global System Prompt into the in-memory config on server startup and after JSON/SQLite import — it was only loaded by the PUT endpoint, so the toggle/prompt silently reverted to defaults after any restart or import. ([#2470](https://github.com/diegosouzapw/OmniRoute/issues/2470) — thanks @disonjer) -- **fix(settings):** append the Global System Prompt **after** existing system content instead of prepending it, so provider/agent instructions (Kiro, OpenCode, Hermes, …) injected into the system message no longer override the user's global prompt via recency bias. ([#2468](https://github.com/diegosouzapw/OmniRoute/issues/2468) — thanks @disonjer) -- **fix(kiro):** refresh imported social tokens (`authMethod === "imported"`) via the Kiro social-auth endpoint instead of AWS SSO OIDC — imported tokens carry a registered `clientId`/`clientSecret` but a social-issued refresh token the OIDC client cannot refresh, so auto-refresh was failing with "provider returned no new token". ([#2467](https://github.com/diegosouzapw/OmniRoute/issues/2467) — thanks @disonjer) -- **fix(antigravity):** resolve the Cloud Code `projectId` from `providerSpecificData` as a fallback (and preserve it across token refresh) so the Gemini `/v1beta` streaming path stops returning a spurious `422 Missing Google projectId` for connections that store the project there. ([#2480](https://github.com/diegosouzapw/OmniRoute/issues/2480)) -- **fix(api):** `GET /v1beta/models` now lists only models whose provider has an active/validated connection, matching the OpenAI-format `/v1/models` behavior, instead of returning the entire catalog. ([#2483](https://github.com/diegosouzapw/OmniRoute/issues/2483)) - -- **fix(cli):** persist `STORAGE_ENCRYPTION_KEY` into `DATA_DIR` (not only `~/.omniroute`) and refuse to auto-generate a fresh key when a `storage.sqlite` already exists — a new key cannot decrypt previously-encrypted credentials, so silently regenerating it locked users out of their database. The CLI now mirrors the server `bootstrapEnv` guard. (reported by Daniel Nach; original key persistence by @Chewji9875 — follow-up to [#1622](https://github.com/diegosouzapw/OmniRoute/issues/1622)) -- **fix(gemini):** preserve and re-attach the `thoughtSignature` on Gemini thinking-model tool calls — thread the signature namespace through the `FORMATS.GEMINI` and `FORMATS.GEMINI_CLI` request translators so the cached signature (keyed by connection + tool-call id) is found on the follow-up turn. Fixes `[400]: Function call is missing a thought_signature in functionCall parts` on agentic Gemini tool use. ([#2504](https://github.com/diegosouzapw/OmniRoute/issues/2504)) -- **fix(translator):** accept PDFs sent in the Responses-API `input_file` shape on the Gemini path, and the Gemini-style `document` shape on the Responses/Codex path — content parts are now normalized across `input_file` / `file` / `document` so a PDF reaches the model regardless of which field name the client used. ([#2515](https://github.com/diegosouzapw/OmniRoute/issues/2515)) -- **fix(stream):** count `thinking` arrays and `reasoning_details` as useful stream output — a reasoning-only response (e.g. Mistral/StepFun with a low `max_tokens`) was misclassified as "Stream ended before producing useful content" and turned into a spurious 502; it is now recognized as valid output. ([#2520](https://github.com/diegosouzapw/OmniRoute/issues/2520)) -- **fix(claude):** extract system/developer role messages in Claude Code semantic passthrough paths — moves `role:"system"` / `role:"developer"` messages from the `messages[]` array to the top-level `system` parameter before sending to Anthropic, which rejects them inside messages. Fixes memory injection context being silently dropped. ([#2497](https://github.com/diegosouzapw/OmniRoute/pull/2497) — thanks @unitythemaker) -- **fix(vision-bridge):** auto-route non-standard provider models through OmniRoute self-loop — vision-bridge now detects when a model doesn't natively support vision and automatically re-routes the image through OmniRoute's own endpoint for format translation. ([#2487](https://github.com/diegosouzapw/OmniRoute/pull/2487) — thanks @herjarsa) -- **fix(mitm):** add IPv6 DNS redirect, modular antigravity target, improved logging — MITM DNS handler now correctly redirects IPv6 (AAAA) queries alongside IPv4, adds a dedicated `antigravity.ts` target module, and enhances DNS/TLS logging for debugging. ([#2514](https://github.com/diegosouzapw/OmniRoute/pull/2514) — thanks @herjarsa) -- **fix(usage):** improve Claude and MiniMax plan label detection — better tier name resolution for Claude OAuth usage (tier/plan/subscription_type/org fields) and new MiniMax plan label inference from quota totals. ([#2498](https://github.com/diegosouzapw/OmniRoute/pull/2498) — thanks @Gi99lin) -- **fix(codex):** fan out image `n` requests in parallel — when Codex requests `n > 1` images, the image-generation handler now dispatches them concurrently instead of sequentially, significantly reducing total latency. ([#2499](https://github.com/diegosouzapw/OmniRoute/pull/2499) — thanks @nmime) -- **fix(embeddings):** strip stale `Content-Encoding` headers from upstream response — prevents clients from receiving gzip-encoded responses with `identity` encoding declared, which caused silent data corruption. ([#2477](https://github.com/diegosouzapw/OmniRoute/pull/2477) — thanks @lordavadon2) -- **fix(model):** return clear error instead of silent OpenAI default for unrecognized models — previously, an unrecognized model silently fell back to OpenAI; now returns a 404 with a descriptive message listing known providers. ([#2492](https://github.com/diegosouzapw/OmniRoute/pull/2492) — thanks @herjarsa) -- **fix(dark-mode):** correct background token on Compression Override select — the combo compression override `` 使用了硬编码白色背景，在暗色模式下不可见。([#2513](https://github.com/diegosouzapw/OmniRoute/pull/2513) — 感谢 @apoapostolov) +- **fix(antigravity):** 将订阅套餐检测与 Antigravity Manager 对齐 — `extractCodeAssistSubscriptionTier` 现在从 `loadCodeAssist` 响应中解析正确的嵌套字段，新的 `extractCodeAssistOnboardTierId` 回退处理引导流程。订阅信息按 access-token 缓存，TTL 5 分钟。([#2496](https://github.com/diegosouzapw/OmniRoute/pull/2496) — 感谢 @Gi99lin) +- **fix(opencode-zen):** 添加 `opencode` 服务商别名并与线上 API 同步模型列表 — `opencode-zen` 和 `opencode-go` 现在也可通过更短的 `opencode` 别名访问，默认模型列表与线上 `/v1/models` 目录保持同步。([#2508](https://github.com/diegosouzapw/OmniRoute/pull/2508) — 感谢 @herjarsa) +- **fix(combo):** 当 combo 目标因凭证不可用而跳过时，改进日志消息 — 此前记录了误导性的 "服务商 not found"；现在显示 "skipped: 凭证 unavailable"。([#2494](https://github.com/diegosouzapw/OmniRoute/pull/2494) — 感谢 @herjarsa) +- **fix(security):** 在 `generateTaskId`/`ActivityId` 中用 `crypto.randomUUID` 替换 `Math.random`，并修复测试中的 URL hostname 检查 — 消除 CodeQL 标记的弱 PRNG 使用。([#2489](https://github.com/diegosouzapw/OmniRoute/pull/2489)) +- **fix(electron):** 降级到 Electron 41.x 以保证 better-sqlite3 V8 兼容性 — Electron 42.x 搭载的 V8 版本破坏了 `better-sqlite3` 原生绑定；锁定 41.x 恢复稳定性。 +- **fix(@omniroute/opencode-provider):** 在模型条目中包含 `limit.context` 以便 OpenCode 检测上下文窗口 — OpenCode 读取 `limit.context` 来确定可用于压缩和溢出检测的上下文长度。 +- **fix(providers):** 使 `gitlawb/gitlawb-gmi` 模型条目变为可选 — 防止该模型不在目录中时服务商初始化失败。([#2476](https://github.com/diegosouzapw/OmniRoute/pull/2476) — 感谢 @oyi77) +- **fix(translator):** 当目标服务商使用 Responses API 时，以 Responses-API 扁平工具格式 (`{ type, name }`) 注入 `omniroute_web_search` — 此前始终以 Chat Completions 嵌套格式发送，导致 Codex/中继上游拒绝请求。([#2390](https://github.com/diegosouzapw/OmniRoute/issues/2390)) +- **fix(kiro):** 在发送到 CodeWhisperer 前序列化非字符串 `role:"tool"` 消息内容 — 结构化/数组工具输出会坍缩为 `content:[{ text: "" }]`，Kiro 以 `400 Improperly formed 请求` 拒绝。([#2446](https://github.com/diegosouzapw/OmniRoute/issues/2446)) +- **fix(claude):** 将 heavy-agent beta 头（`context-1m`、`effort`、`advanced-tool-use`）限制为仅 Opus/Sonnet 使用 — OAuth 下的 Haiku 收到 `context-1m` 会以 400 拒绝。同时清洗透传中的历史 `thinking` 块签名。([#2454](https://github.com/diegosouzapw/OmniRoute/issues/2454) — 感谢 @havockdev) +- **fix(perplexity-web):** 通过模拟 Firefox-148 TLS 的客户端路由请求，使 Perplexity 的 Cloudflare 边缘不再以 403 质询拒绝 VPS/数据中心 IP。([#2459](https://github.com/diegosouzapw/OmniRoute/issues/2459) — 感谢 @havockdev) +- **fix(validation):** 在服务商连接测试路径中调用 `.startsWith()` / `.trim()` 前，保护 `apiKey`/`modelsUrl` 防止非字符串值。([#2463](https://github.com/diegosouzapw/OmniRoute/issues/2463)) +- **fix(cost):** 防止 `cache_creation_input_tokens` 双重计费 — Token 提取器中的 `prompt_tokens` 已包含 `cache_read` 和 `cache_creation`，因此 `nonCachedInput` 现在减去两种缓存类型，避免按完整输入费率对缓存定价。([#2522](https://github.com/diegosouzapw/OmniRoute/pull/2522) — 感谢 @herjarsa) +- **fix(handler):** 始终在 Claude 透传路径中规范化系统角色消息 — `normalizeClaudeUpstreamMessages()` 现在在 `compatibleBridge` 和纯透传中均无条件调用，确保 `role:"system"` 消息始终被提取到顶层 `system` 参数。([#2519](https://github.com/diegosouzapw/OmniRoute/pull/2519) — 感谢 @herjarsa) +- **fix(handler):** 在非流式响应路径中捕获 Gemini `thought_signature` — 非流式翻译器现在从 Gemini thinking 模型部分捕获 `thoughtSignature` 并持久化，使后续轮次能正确解析。([#2518](https://github.com/diegosouzapw/OmniRoute/pull/2518) — 感谢 @herjarsa) +- **fix(kiro):** 用设备流替换损坏的社交 OAuth — 将 Kiro 的 Google/GitHub 社交登录从损坏的 PKCE `kiro://` 自定义协议重写为 AWS Cognito 设备流，在 web/代理环境中正常工作。([#2524](https://github.com/diegosouzapw/OmniRoute/pull/2524) — 感谢 @disonjer) +- **fix(providers):** 解决 `opencode/` → `opencode-zen` 别名不匹配 + 新增 40+ 模型 — `opencode` 现在在 executor、模型解析器和服务商注册表中作为 `opencode-zen` 的正式别名；新增 GPT 5.x、Claude 4.x、Gemini 3.x、Grok、Kimi 等模型并附带测试。([#2517](https://github.com/diegosouzapw/OmniRoute/pull/2517) — 感谢 @herjarsa) +- **fix(antigravity):** 停滞的 Antigravity 会话自动容灾 — 新增 `ANTIGRAVITY_PRE_RESPONSE_TIMEOUT_CODE` 共享常量用于预响应超时检测，当会话在收到头部前停滞时自动容灾到下一个账户。Node.js 引擎范围放宽到 `>=20.20.2`。([#2464](https://github.com/diegosouzapw/OmniRoute/pull/2464) — 感谢 @dhaern) +- **fix(deepseek-web):** 修复 SSE 解析器、prompt 格式和错误处理 — 处理所有 3 种 DeepSeek SSE 流格式（初始片段、APPEND 操作、裸字符串 token），简化 prompt 为单轮次防止聊天标记泄漏，在提取 Token 前检查 `json.code`。([#2502](https://github.com/diegosouzapw/OmniRoute/pull/2502) — 感谢 @ovehbe) +- **fix(codex):** 导入时接受不含 `auth_mode` 字段的 `auth.json` — Codex CLI 不再写入 `auth_mode`；导入现在接受两种格式，只要必需的 Token 存在即可。语义缓存读取现在要求显式 `temperature: 0`。([#2536](https://github.com/diegosouzapw/OmniRoute/pull/2536) — 感谢 @janeza2) +- **fix(freetheai):** 在 baseUrl 中添加 `/chat/completions` 以解决 404 错误。([#2557](https://github.com/diegosouzapw/OmniRoute/pull/2557) — 感谢 @lordavadon2) +- **fix(qoder):** 将 PAT Token 路由到 Qoder 原生 API 而非 DashScope — 检测 `pt-` 前缀的 Token 并路由到 `api.qoder.com`，附带正确的 User-Agent 头。([#2559](https://github.com/diegosouzapw/OmniRoute/pull/2559) — 感谢 @herjarsa) +- **fix(perf):** 在 RTK 压缩热路径中缓存编译后的 RegExp — 消除每秒数千次冗余的 `new RegExp()` 实例化。([#2553](https://github.com/diegosouzapw/OmniRoute/pull/2553) — 感谢 @soyelmismo) +- **fix(reasoning-cache):** 模块加载时自动启动定期清理 — `server-init.ts` 任务从未被导入（死代码），导致 `reasoning_cache` 表无限增长。现在自动运行 30 分钟清理周期。([#2552](https://github.com/diegosouzapw/OmniRoute/pull/2552) — 感谢 @soyelmismo) +- **fix(claude):** Sonnet 省略 `context-1m` beta — 限制为仅 Opus 使用，避免长上下文积分门槛错误。新增 `afk-mode-2026-01-31`，将 `redact-thinking` 替换为 `thinking-token-count-2026-05-13`。([#2568](https://github.com/diegosouzapw/OmniRoute/pull/2568) — 感谢 @unitythemaker) +- **fix(codex):** 在前端导入预览中放宽 `auth_mode` 检查 — 接受 `undefined`/`null`/`"chatgpt"` 而非严格要求 `"chatgpt"`，与 #2536 的后端修复保持一致。([#2567](https://github.com/diegosouzapw/OmniRoute/pull/2567) — 感谢 @janeza2) +- **fix(kimi):** 在全部 4 层中声明 Kimi K2.6 的视觉能力 — `providerRegistry`、`modelSpecs`、`catalog.ts` 关键词列表和 Playground `VISION_MODELS`；此前该模型会静默拒绝图像上传。([#2573](https://github.com/diegosouzapw/OmniRoute/pull/2573) — 感谢 @herjarsa) +- **fix(dashboard):** 请求日志查看器支持超过 300 行分页 — `getCallLogs` 现在接受 `offset` 并使用参数化 SQL（消除字符串插值 `LIMIT`）；`RequestLoggerV2` 通过 "加载更多" + IntersectionObserver 无限滚动扩展窗口，过滤器变更时重置。([#2576](https://github.com/diegosouzapw/OmniRoute/pull/2576)) +- **fix(cli):** 使用 `/api/monitoring/health` 进行服务器就绪检查 — `waitForServer()` 此前轮询了需要认证的 `/api/health`（401），导致 `omniroute serve` 无限挂起。([#2578](https://github.com/diegosouzapw/OmniRoute/pull/2578) — 感谢 @amogus22877769) +- **fix(combo):** 通过结构化错误码 + 正则回退检测无效模型错误 — 当 Combo 目标拒绝模型时（如免费账户 vs Pro），路由器现在能识别 `model_not_found` / `deployment_not_found` 码和 6 种正则模式，并容灾到下一个目标而非停止循环。([#2534](https://github.com/diegosouzapw/OmniRoute/pull/2534) — 感谢 @HALDRO) +- **fix(security):** 审查后加固批次 — `spawnSync` 参数数组替换 `execSync` 字符串模板（命令注入），CSP `unsafe-eval` 受 `!app.isPackaged` 控制，budget/bulk 和 resilience/reset 端点添加 `requireManagementAuth` 守卫，gemini-web/claude-web/copilot-web/oauth/agents catch 块中清洗错误消息，熔断器持久化 `lastFailureKind`，combo 在每次 set-retry 迭代时重置 `exhaustedProviders`。([#2435](https://github.com/diegosouzapw/OmniRoute/pull/2435)) +- **fix(@omniroute/opencode-plugin):** 遵循 `geminiSanitization` 和 `fetchInterceptor` 特性标志 — 此前两者均无条件应用；现在每个 fetch 层受其标志控制（默认开启），禁用两者则回退到普通 SDK fetch。([#2546](https://github.com/diegosouzapw/OmniRoute/pull/2546)) +- **fix(#2575):** 在 `arePrivateProviderUrlsAllowed()` 中检查 DB 特性标志覆盖 — 支持运行时切换无需重启。([#2595](https://github.com/diegosouzapw/OmniRoute/pull/2595) — 感谢 @herjarsa) +- **fix(mimo):** 为 MiMo-V2.5、V2.5-Pro 和 V2-Omni 添加 `supportsVision` 标志 — 此前图像上传会被静默拒绝。([#2592](https://github.com/diegosouzapw/OmniRoute/pull/2592) — 感谢 @herjarsa) +- **fix(ops):** 将 `OMNIROUTE_SKIP_DB_HEALTHCHECK` 环境变量传播到定期 DB 健康检查调度器 — #2554 的配套修复。([#2591](https://github.com/diegosouzapw/OmniRoute/pull/2591) — 感谢 @soyelmismo) +- **fix(github):** 从 GitHub Copilot 的 Haiku/Sonnet 模型中移除错误的 `openai-responses` targetFormat。([#2583](https://github.com/diegosouzapw/OmniRoute/pull/2583) — 感谢 @oyi77) +- **fix(copilot):** 稳定 responses 配置 — 移除 865 行不稳定的配置，简化处理器。([#2579](https://github.com/diegosouzapw/OmniRoute/pull/2579) — 感谢 @ivan-mezentsev) +- **fix(#2544):** 为 Responses API 转换流添加 SSE 心跳 keepalive — 防止 Codex CLI 0.130.0 在长思考/推理阶段断开连接。([#2599](https://github.com/diegosouzapw/OmniRoute/pull/2599) — 感谢 @herjarsa) +- **fix(memory):** 在语义透传路径中提取系统角色消息，防止记忆注入时出现 400 — 系统消息此前被原样传递给拒绝混合角色的服务商。([#2474](https://github.com/diegosouzapw/OmniRoute/pull/2474) — 感谢 @Tentoxa) +- **fix(@omniroute/opencode-provider):** 在模型条目中包含 `limit.context` 以便 OpenCode 检测上下文窗口 — 此前 OpenCode 无法确定模型上下文大小。([#2482](https://github.com/diegosouzapw/OmniRoute/pull/2482) — 感谢 @herjarsa) +- **fix(mimo):** 在 providerRegistry 中为 Kimi K2.6 添加 `supportsVision` 标志 + MiMo V2.5/V2.5-Pro/V2-Omni 的全面视觉测试。([#2600](https://github.com/diegosouzapw/OmniRoute/pull/2600) — 感谢 @herjarsa) +- **fix(proxy):** 优先使用限定作用域的代理而非注册表全局回退 — 旧版按服务商的代理在两个存储后端上被注册表全局容灾覆盖。解析现在遵循严格优先级：账户 → 服务商 → Combo → 全局。([#2606](https://github.com/diegosouzapw/OmniRoute/pull/2606) — 感谢 @terence71-glitch) +- **fix(@omniroute/opencode-plugin):** 规范双胞胎去重 + 别名回退丰富 — `/v1/models` 以别名 (`cc/claude-opus-4-7`) 和规范名 (`claude/claude-opus-4-7`) 返回同一模型；现在丢弃约 75 个规范重复项，并通过别名索引回退拯救约 88 个原始 ID 行并附加正确服务商前缀。同时在静态目录中输出 `cost`、`release_date`、`modalities` 字段，并将服务商标签阈值提升到 12 字符（保留 `AssemblyAI`、`Antigravity` 全名）。([#2607](https://github.com/diegosouzapw/OmniRoute/pull/2607) — 感谢 @mrmm) +- **fix(registry):** 为 HuggingFace（6 个模型）和 HackClub（3 个模型）填充空模型数组 + 将 Snowflake 占位 baseUrl 修复为 `{account}` 模板模式。([#2611](https://github.com/diegosouzapw/OmniRoute/pull/2611) — 感谢 @oyi77) ### 🌐 Internationalization -- **i18n(zh-CN):** translate 830 missing UI strings — replaces all `__MISSING__:` placeholders with proper Chinese translations. ([#2523](https://github.com/diegosouzapw/OmniRoute/pull/2523) — thanks @InkshadeWoods) -- **i18n(dashboard):** add missing dashboard keys and fix EN fallbacks — hundreds of hardcoded English strings across cache, caveman, costs, skills, memory, and evals pages replaced with `t()` calls. ([#2500](https://github.com/diegosouzapw/OmniRoute/pull/2500) — thanks @Gi99lin) -- **i18n(pt-BR):** complete and fix Brazilian Portuguese translation — comprehensive overhaul of pt-BR locale with ~3000 lines of quality translations, filling all missing keys and correcting existing entries. ([#2543](https://github.com/diegosouzapw/OmniRoute/pull/2543) — thanks @alltomatos) -- **i18n(ru):** comprehensive Russian translation update — ~2000 lines of corrected and filled translations. ([#2550](https://github.com/diegosouzapw/OmniRoute/pull/2550) — thanks @AgentAlexAI) -- **i18n(all):** comprehensive localization and UI refactoring — 42 locale files synchronized with missing keys, cloud-agents page i18n rewrite, and consistent `t()` usage across 21 dashboard components. ([#2580](https://github.com/diegosouzapw/OmniRoute/pull/2580) — thanks @alltomatos) -- **i18n(all):** translate freeTier provider strings across 41 locales — replaces `__MISSING__:Free Tier Providers` placeholders with proper translations in both `common` and `providers` namespaces. ([#2609](https://github.com/diegosouzapw/OmniRoute/pull/2609) — thanks @leninejunior) -- **i18n(pt-BR):** eliminate all 1270 remaining `__MISSING__` markers — completes pt-BR translation across 41 namespaces to true 100% coverage. ([#2610](https://github.com/diegosouzapw/OmniRoute/pull/2610) — thanks @leninejunior) +- **i18n(zh-CN):** 翻译 830 个缺失的 UI 字符串 — 将所有 `__MISSING__:` 占位符替换为正确的中文翻译。([#2523](https://github.com/diegosouzapw/OmniRoute/pull/2523) — 感谢 @InkshadeWoods) +- **i18n(dashboard):** 添加缺失的仪表盘 key 并修复英文回退 — 缓存、caveman、costs、skills、memory 和 evals 页面中数百个硬编码英文字符串替换为 `t()` 调用。([#2500](https://github.com/diegosouzapw/OmniRoute/pull/2500) — 感谢 @Gi99lin) +- **i18n(pt-BR):** 完成并修复巴西葡萄牙语翻译 — 全面翻新 pt-BR 语言包，约 3000 行高质量翻译，填充所有缺失 key 并修正已有条目。([#2543](https://github.com/diegosouzapw/OmniRoute/pull/2543) — 感谢 @alltomatos) +- **i18n(ru):** 全面更新俄语翻译 — 约 2000 行修正和填充的翻译。([#2550](https://github.com/diegosouzapw/OmniRoute/pull/2550) — 感谢 @AgentAlexAI) +- **i18n(all):** 全面本地化和 UI 重构 — 42 个语言文件同步缺失 key，cloud-agents 页面 i18n 重写，21 个仪表盘组件统一使用 `t()`。([#2580](https://github.com/diegosouzapw/OmniRoute/pull/2580) — 感谢 @alltomatos) +- **i18n(all):** 翻译 41 个语言包中的 freeTier 服务商字符串 — 将 `__MISSING__:Free Tier Providers` 占位符替换为 `common` 和 `服务商` 命名空间中的正确翻译。([#2609](https://github.com/diegosouzapw/OmniRoute/pull/2609) — 感谢 @leninejunior) +- **i18n(pt-BR):** 消除全部 1270 个剩余 `__MISSING__` 标记 — 完成 41 个命名空间的 pt-BR 翻译，达��真正 100% 覆盖率。([#2610](https://github.com/diegosouzapw/OmniRoute/pull/2610) — 感谢 @leninejunior) ### 📝 维护 @@ -1804,8 +1787,8 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **chore(deps):** bump `actions/setup-node` from v4 to v6 + `randomBytes` security fix for cloud agent task IDs. ([#2589](https://github.com/diegosouzapw/OmniRoute/pull/2589)) - **chore(deps):** bump `actions/upload-artifact` from v4 to v7. ([#2588](https://github.com/diegosouzapw/OmniRoute/pull/2588)) - **chore:** ignore `.claude/worktrees` from git tracking. -- **chore(ci):** auto-lock release branch on version publish — new CI workflow applies `lock_branch` protection when a GitHub Release is published. ([#2542](https://github.com/diegosouzapw/OmniRoute/pull/2542)) -- **docs:** redesign README — marketing-first layout with accurate provider counts. ([#2490](https://github.com/diegosouzapw/OmniRoute/pull/2490)) +- **chore(ci):** auto-lock release branch on version publish — new CI 工作流 applies `lock_branch` protection when a GitHub Release is published. ([#2542](https://github.com/diegosouzapw/OmniRoute/pull/2542)) +- **docs:** redesign README — marketing-first layout with accurate 服务商 counts. ([#2490](https://github.com/diegosouzapw/OmniRoute/pull/2490)) --- @@ -1813,76 +1796,76 @@ must be a response to a preceding message with 'tool_calls'` when a Codex ### ✨ 新功能 -- **feat(settings):** Feature Flags Settings Page (Card Grid + DB overrides) — fully implements the feature flags UI dashboard using Variant A (Card Grid) with Glassmorphism, complete with global `GET/PUT/DELETE` API routes, Zod validation, debounced search, category filters, and full 30+ locale i18n support. Resolves priority hierarchy to DB > ENV > Defaults. ([#2457](https://github.com/diegosouzapw/OmniRoute/pull/2457)) -- **feat(db):** multi-driver SQLite abstraction layer — new `SqliteAdapter` interface with 3 concrete adapters (`betterSqliteAdapter`, `nodeSqliteAdapter`, `sqljsAdapter`) and a `driverFactory` that cascades `better-sqlite3` → `node:sqlite` → `sql.js (WASM)`. Enables OmniRoute to run on any JavaScript runtime (Node.js, Bun, Deno, Cloudflare Workers) without native binary dependencies. `better-sqlite3` moved to `optionalDependencies`. ([#2447](https://github.com/diegosouzapw/OmniRoute/pull/2447)) -- **feat(settings):** Claude Fast Mode toggle in Settings › AI — opt-in toggle that forwards `X-CPA-Force-Fast-Mode` header so a paired CLIProxyAPI build can reach Anthropic Fast Mode (`speed:"fast"`). Model-gated to Opus models matching Anthropic's binary KT() check. ([#2449](https://github.com/diegosouzapw/OmniRoute/pull/2449) — thanks @NomenAK) -- **feat(settings):** Codex Fast Tier — tier dropdown (`default`/`priority`/`flex`) + per-model gate preventing 400 errors from OpenAI when the tier toggle was on for non-Fast-eligible models. ([#2451](https://github.com/diegosouzapw/OmniRoute/pull/2451) — thanks @NomenAK) -- **feat:** align Antigravity 2.0.1 support — updated client profile, upstream headers, and model aliases. ([#2443](https://github.com/diegosouzapw/OmniRoute/pull/2443) — thanks @dhaern) -- **feat:** enhance `extractBearer` to support `x-api-key` for Anthropic API style auth. ([#2436](https://github.com/diegosouzapw/OmniRoute/pull/2436) — thanks @thedtvn) -- **feat(memory):** wire `createMemory` to `upsertSemanticMemoryPoint` (Qdrant). ([#2439](https://github.com/diegosouzapw/OmniRoute/pull/2439) — thanks @NomenAK) - -### 🔧 问题修复 & Refactors - -- **fix(deepseek-web):** rewrite auth to userToken Bearer + WASM PoW solver. ([#2452](https://github.com/diegosouzapw/OmniRoute/pull/2452) — thanks @ovehbe) -- **chore:** update node dependencies and runtime support. ([#2453](https://github.com/diegosouzapw/OmniRoute/pull/2453) — thanks @backryun) -- **fix(translator):** fix 3 Kiro `tool_result` defects causing 400 on follow-up turns — missing `tool_use_id` mapping, orphan result blocks, and conversation ID collision on assistant-first turns. ([#2447](https://github.com/diegosouzapw/OmniRoute/pull/2447)) -- **fix(translator):** treat `developer` role as system in OpenAI → Claude translation — `openAIToClaude` now extracts `developer`-role messages into `systemParts` (same as `system`) and filters them from the non-system message list, preventing identity context injected via the Responses API `developer` role from silently becoming an assistant turn when routing to a Claude-format provider. ([#2407](https://github.com/diegosouzapw/OmniRoute/issues/2407)) -- **fix(antigravity):** deduplicate `removeHeaderCaseInsensitive` — export canonical implementation from `antigravityClientProfile.ts` and remove the local copy in `antigravity.ts`; export `AntigravityCredentialsLike` type for cross-module use. (#2433 — thanks @Gi99lin) -- **refactor(docs):** enhance frontmatter handling in DocPage — gray-matter Date object parsing bug fix. ([#2448](https://github.com/diegosouzapw/OmniRoute/pull/2448) — thanks @ovehbe) -- **fix(jules):** Jules API parity and cloud-agent provider registration. ([#2438](https://github.com/diegosouzapw/OmniRoute/pull/2438)) -- **fix(i18n):** harden diff key extraction tag sanitization in `extract-keys-from-diff.mjs`. -- **chore(i18n):** refresh fr/es/de locales + add missing `settings.update` key. ([#2437](https://github.com/diegosouzapw/OmniRoute/pull/2437)) -- **fix(dashboard):** allow bracketed combo names — align dashboard combo-name validator regex with the shared/server schema updated in PR #2354; names like `Claude [1m]` are now accepted in the create/edit form. ([#2458](https://github.com/diegosouzapw/OmniRoute/pull/2458) — thanks @congvc-dev) -- **docs(agentrouter):** recommend native provider as the simple path — guide now prefers the built-in AgentRouter provider instead of manual OpenAI-compatible configuration. ([#2429](https://github.com/diegosouzapw/OmniRoute/pull/2429) — thanks @leninejunior) -- **feat(settings):** surface Codex Fast Tier toggle in Settings › AI — companion UI toggle for the Codex Fast Tier feature. ([#2440](https://github.com/diegosouzapw/OmniRoute/pull/2440) — thanks @NomenAK) - -### 🔒 安全 Fixes - -- **fix(security):** replace `execSync` string-template with `spawnSync` arg-array in `plugin.mjs` — eliminates shell command injection via malicious plugin names. -- **fix(security):** gate Electron CSP `unsafe-eval` on `!app.isPackaged` instead of URL substring match — was leaking `unsafe-eval` into production builds; merged duplicate `connect-src` directives. -- **fix(api):** add `requireManagementAuth` to `/api/usage/budget/bulk` and `/api/resilience/reset` — both endpoints exposed spend data and circuit-breaker controls without auth. -- **fix(security):** route catch-block error messages through `sanitizeErrorMessage()` in `gemini-web`, `claude-web`, `copilot-web` executors, `oauth` route, and cloud-agent task routes — prevents stack traces and internal paths leaking into HTTP responses. -- **fix(codex):** `refreshCredentials` returns `null` (not error-object) on token refresh failure — prevents base executor from spreading `{error}` onto active credentials. -- **fix(tokenRefresh):** safe `unknown`-error access in `catch` block (`error instanceof Error ? error.message : String(error)`). -- **fix(combo):** reset `exhaustedProviders` set at start of each set-retry iteration — providers excluded in a failing pass now get a second chance on retry. -- **fix(circuitBreaker):** persist and restore `lastFailureKind` via the `options` JSON column — kind-based cooldown overrides (`cooldownByKind`) now survive server restarts. +- **feat(settings):** 功能开关设置页面（卡片网格 + 数据库覆盖）— 完整实现了功能开关 UI 控制台，采用方案 A（卡片网格）搭配玻璃态设计，配备全局 `GET/PUT/DELETE` API 路由、Zod 校验、防抖搜索、分类筛选以及完整的 30+ 语言环境国际化支持。优先级解析为 数据库 > 环境变量 > 默认值。([#2457](https://github.com/diegosouzapw/OmniRoute/pull/2457)) +- **feat(db):** 多驱动 SQLite 抽象层 — 新增 `SqliteAdapter` 接口及 3 个具体适配器（`betterSqliteAdapter`、`nodeSqliteAdapter`、`sqljsAdapter`），以及级联 `better-sqlite3` → `node:sqlite` → `sql.js (WASM)` 的 `driverFactory`。使 OmniRoute 能够在任何 JavaScript 运行时（Node.js、Bun、Deno、Cloudflare Workers）上运行，无需原生二进制依赖。`better-sqlite3` 已移至 `optionalDependencies`。([#2447](https://github.com/diegosouzapw/OmniRoute/pull/2447)) +- **feat(settings):** 设置 › AI 中的 Claude 快速模式开关 — 可选开关，转发 `X-CPA-Force-Fast-Mode` 头，使配对的 CLIProxyAPI 构建能够访问 Anthropic 快速模式（`speed:"fast"`）。模型门控至 Opus 模型，匹配 Anthropic 的二进制 KT() 检查。([#2449](https://github.com/diegosouzapw/OmniRoute/pull/2449) — 感谢 @NomenAK) +- **feat(settings):** Codex 快速等级 — 等级下拉菜单（`默认`/`priority`/`flex`）+ 逐模型门控，防止在非快速模式兼容模型上开启等级开关时 OpenAI 返回 400 错误。([#2451](https://github.com/diegosouzapw/OmniRoute/pull/2451) — 感谢 @NomenAK) +- **feat:** 适配 Antigravity 2.0.1 支持 — 更新客户端配置文件、上游头及模型别名。([#2443](https://github.com/diegosouzapw/OmniRoute/pull/2443) — 感谢 @dhaern) +- **feat:** 增强 `extractBearer` 以支持 `x-api-key`，用于 Anthropic API 风格的认证。([#2436](https://github.com/diegosouzapw/OmniRoute/pull/2436) — 感谢 @thedtvn) +- **feat(memory):** 将 `createMemory` 对接至 `upsertSemanticMemoryPoint`（Qdrant）。([#2439](https://github.com/diegosouzapw/OmniRoute/pull/2439) — 感谢 @NomenAK) + +### 🔧 问题修复 & 重构 + +- **fix(deepseek-web):** 将认证重写为 userToken Bearer + WASM PoW 求解器。([#2452](https://github.com/diegosouzapw/OmniRoute/pull/2452) — 感谢 @ovehbe) +- **chore:** 更新 Node 依赖和运行时支持。([#2453](https://github.com/diegosouzapw/OmniRoute/pull/2453) — 感谢 @backryun) +- **fix(translator):** 修复 3 个 Kiro `tool_result` 缺陷，导致后续轮次返回 400 错误 — 缺失 `tool_use_id` 映射、孤立的结果块以及助手优先轮次中的会话 ID 冲突。([#2447](https://github.com/diegosouzapw/OmniRoute/pull/2447)) +- **fix(translator):** 在 OpenAI → Claude 翻译中将 `developer` 角色视为 system — `openAIToClaude` 现在将 `developer` 角色的消息提取到 `systemParts` 中（与 `system` 相同），并从非 system 消息列表中过滤掉它们，防止通过 Responses API `developer` 角色注入的身份上下文在路由到 Claude 格式服务商时静默变成助手轮次。([#2407](https://github.com/diegosouzapw/OmniRoute/issues/2407)) +- **fix(antigravity):** 去重 `removeHeaderCaseInsensitive` — 从 `antigravityClientProfile.ts` 导出规范实现并移除 `antigravity.ts` 中的本地副本；导出 `AntigravityCredentialsLike` 类型供跨模块使用。(#2433 — 感谢 @Gi99lin) +- **refactor(docs):** 增强 DocPage 中的 frontmatter 处理 — 修复 gray-matter Date 对象解析缺陷。([#2448](https://github.com/diegosouzapw/OmniRoute/pull/2448) — 感谢 @ovehbe) +- **fix(jules):** Jules API 对齐及云代理服务商注册。([#2438](https://github.com/diegosouzapw/OmniRoute/pull/2438)) +- **fix(i18n):** 加固 `extract-keys-from-diff.mjs` 中的差异键提取标签清理。 +- **chore(i18n):** 刷新法语/西班牙语/德语语言文件 + 添加缺失的 `settings.update` 键。([#2437](https://github.com/diegosouzapw/OmniRoute/pull/2437)) +- **fix(dashboard):** 允许带方括号的组合名称 — 将控制台组合名称校验正则与 PR #2354 中更新的共享/服务器 Schema 对齐；像 `Claude [1m]` 这样的名称现在可在创建/编辑表单中接受。([#2458](https://github.com/diegosouzapw/OmniRoute/pull/2458) — 感谢 @congvc-dev) +- **docs(agentrouter):** 推荐使用原生服务商作为简单路径 — 指南现在优先使用内置的 AgentRouter 服务商，而非手动 OpenAI 兼容配置。([#2429](https://github.com/diegosouzapw/OmniRoute/pull/2429) — 感谢 @leninejunior) +- **feat(settings):** 在 设置 › AI 中展示 Codex 快速等级开关 — Codex 快速等级功能的配套 UI 开关。([#2440](https://github.com/diegosouzapw/OmniRoute/pull/2440) — 感谢 @NomenAK) + +### 🔒 安全修复 + +- **fix(security):** 在 `plugin.mjs` 中将 `execSync` 字符串模板替换为 `spawnSync` 参数数组 — 消除通过恶意插件名称进行的 shell 命令注入。 +- **fix(security):** 将 Electron CSP `unsafe-eval` 的门控条件从 URL 子串匹配改为 `!app.isPackaged` — 此前会将 `unsafe-eval` 泄露到生产构建中；合并了重复的 `connect-src` 指令。 +- **fix(api):** 为 `/api/usage/budget/bulk` 和 `/api/resilience/reset` 添加 `requireManagementAuth` — 这两个端点此前在无认证的情况下暴露了消费数据和熔断器控制。 +- **fix(security):** 在 `gemini-web`、`claude-web`、`copilot-web` 执行器、`oauth` 路由及云代理任务路由中，将 catch 块中的错误消息通过 `sanitizeErrorMessage()` 处理 — 防止堆栈跟踪和内部路径泄露到 HTTP 响应中。 +- **fix(codex):** 令牌刷新失败时 `refreshCredentials` 返回 `null`（而非错误对象）— 防止基础执行器将 `{错误}` 展开到活跃凭证上。 +- **fix(tokenRefresh):** 在 `catch` 块中安全访问 `unknown` 错误（`error instanceof Error ? error.message : String(error)`）。 +- **fix(combo):** 在每次集合重试迭代开始时重置 `exhaustedProviders` 集合 — 在失败轮次中被排除的服务商现在可在重试时获得第二次机会。 +- **fix(circuitBreaker):** 通过 `options` JSON 列持久化和恢复 `lastFailureKind` — 基于故障类型的冷却覆盖（`cooldownByKind`）现在可在服务器重启后保持。 --- ## [3.8.0] — 2026-05-06 -### 🚀 Post-release hotfixes e contribuições (2026-05-06 → 2026-05-20) +### 🚀 发布后热修复与贡献 (2026-05-06 → 2026-05-20) #### 2026-05-20 -- **feat(batch):** implement 10 feature requests harvested from issues — T3 Chat Web executor (cookie-based), per-request exhausted-provider tracking (#1731) to skip quota-drained providers mid-combo, Zed Docker detection, API key rotator health dashboard, Kiro multi-account isolation, context-window model filtering, cost blending in combos, combo config tests, provider validation branches, and postinstall support scripts. ([#2414](https://github.com/diegosouzapw/OmniRoute/pull/2414)) -- **feat(combos):** add `falloverBeforeRetry` strategy — combo routing now falls over to the next target before retrying the same model, eliminating the tail-latency spike from exhausting all per-model retries on a failing endpoint. Also wraps the retry loop in a `setTry` outer loop for per-target retry coordination. ([#2417](https://github.com/diegosouzapw/OmniRoute/pull/2417) — thanks @hartmark) -- **fix(gamification):** resolve 6 implementation gaps — missing `SELECT` in `checkActionCountBadges` SQL (was silently skipping 8 badges), federation leaderboard auth enforcement, pagination `offset` parameter no longer silently discarded, admin anomaly view now computes real z-scores, `addXp` correctly calculates initial level from XP amount, and barrel `index.ts` for clean module exports. 72-test suite covering all fixes. ([#2421](https://github.com/diegosouzapw/OmniRoute/pull/2421) — thanks @oyi77) -- **docs:** add AgentRouter provider setup guide — step-by-step instructions for connecting OmniRoute to AgentRouter.org's Claude-compatible relay endpoint, covering API key configuration and wire-image headers. ([#2422](https://github.com/diegosouzapw/OmniRoute/pull/2422) — thanks @leninejunior) +- **feat(batch):** 实现从 issue 中收集的 10 个特性请求 — T3 Chat Web 执行器（基于 cookie）、按请求追踪已耗尽服务商 (#1731) 以在 combo 中途跳过配额耗尽的服务商、Zed Docker 检测、API key 轮换健康仪表盘、Kiro 多账户隔离、上下文窗口模型过滤、combo 成本混合、combo 配置测试、服务商验证分支和 postinstall 支持脚本。([#2414](https://github.com/diegosouzapw/OmniRoute/pull/2414)) +- **feat(combos):** add `falloverBeforeRetry` strategy — Combo 路由 now falls over to the next target before retrying the same 模型, eliminating the tail-latency spike from exhausting all per-模型 重试 on a failing 端点. Also wraps the 重试 loop in a `setTry` outer loop for per-target 重试 coordination. ([#2417](https://github.com/diegosouzapw/OmniRoute/pull/2417) — 感谢 @hartmark) +- **fix(gamification):** resolve 6 implementation gaps — missing `SELECT` in `checkActionCountBadges` SQL (was silently skipping 8 badges), federation leaderboard 认证 enforcement, pagination `offset` parameter 不再 silently discarded, admin anomaly view now computes real z-scores, `addXp` correctly calculates initial level from XP amount, and barrel `index.ts` for clean module exports. 72-test suite covering all fixes. ([#2421](https://github.com/diegosouzapw/OmniRoute/pull/2421) — 感谢 @oyi77) +- **docs:** add AgentRouter provider setup guide — step-by-step instructions for connecting OmniRoute to AgentRouter.org's Claude-compatible 中继 端点, covering API Key 配置 and wire-image headers. ([#2422](https://github.com/diegosouzapw/OmniRoute/pull/2422) — 感谢 @leninejunior) - **fix(claude):** drop orphan `tool_result` blocks left behind when `fixToolAdjacency` strips a dangling `tool_use` — resolves HTTP 400 "unexpected tool_use_id in tool_result blocks" from the Anthropic API on truncated histories. `fixToolPairs` now re-runs after every `fixToolAdjacency` pass across all three call sites (`contextManager.ts`, `base.ts`, `claudeCodeCompatible.ts`). (discussion [#2410](https://github.com/diegosouzapw/OmniRoute/discussions/2410)) - **fix(playground):** guard against `null`/non-string model IDs in Playground dropdowns — `typeof m?.id !== "string"` check prevents a silent crash in the provider discovery loop and `filteredModels` computation that was leaving all Playground dropdowns empty when `/v1/models` returned entries with `id: null`; adds deduplication via `Set` to eliminate duplicate React key warnings. -- **fix(mitm):** point MITM runtime manager re-export to the compiled `.js` entrypoint — fixes module resolution after build when the `.ts` source is no longer present. -- **fix(storage):** persist `STORAGE_ENCRYPTION_KEY` across upgrades (closes #1622) — ensures that SQLite encryption keys are preserved during version upgrades. ([#2428](https://github.com/diegosouzapw/OmniRoute/pull/2428) — thanks @Chewji9875) -- **fix(auth):** auto-reset credential `apiKeyHealth` status on successful connection test. ([#2427](https://github.com/diegosouzapw/OmniRoute/pull/2427) — thanks @clousky2020) -- **fix(mitm):** drop `.js` extension on `manager.runtime` re-export to fix webpack packaging issue. ([#2425](https://github.com/diegosouzapw/OmniRoute/pull/2425) — thanks @NomenAK) -- **fix(image):** support Antigravity image generation and add Gemini 3.5 Flash support. ([#2423](https://github.com/diegosouzapw/OmniRoute/pull/2423) — thanks @backryun) +- **fix(mitm):** point MITM runtime manager re-export to the compiled `.js` entrypoint — fixes module resolution after build when the `.ts` source is 不再 present. +- **fix(storage):** 在版本升级期间持久化 `STORAGE_ENCRYPTION_KEY`（closes #1622）— 确保 SQLite 加密密钥在版本升级期间被保留。([#2428](https://github.com/diegosouzapw/OmniRoute/pull/2428) — 感谢 @Chewji9875) +- **fix(auth):** 连接测试成功后自动重置凭据 `apiKeyHealth` 状态。([#2427](https://github.com/diegosouzapw/OmniRoute/pull/2427) — 感谢 @clousky2020) +- **fix(mitm):** 移除 `manager.runtime` 重新导出中的 `.js` 扩展名以修复 webpack 打包问题。([#2425](https://github.com/diegosouzapw/OmniRoute/pull/2425) — 感谢 @NomenAK) +- **fix(image):** 支持 Antigravity 图像生成并新增 Gemini 3.5 Flash 支持。([#2423](https://github.com/diegosouzapw/OmniRoute/pull/2423) — 感谢 @backryun) #### 2026-05-19 -- **chore(i18n):** comprehensive dashboard i18n coverage — 6 rounds of parallel refactoring replacing hardcoded English/Portuguese text with `t()` calls across 57+ dashboard pages; 420+ new keys added to `en.json` covering `settings`, `playground`, `analytics`, `apiManager`, `providers`, `skills`, `memory`, `agents`, and 15 other namespaces (coverage: ~88%, up from ~20%). -- **fix(offline):** avoid SSR/CSR hydration mismatch on the offline status page — switches from a `useState` lazy initializer (which accessed `navigator.onLine` on the server) to `useSyncExternalStore` with a distinct `false` server snapshot, eliminating the React hydration warning. -- **fix(cli-tools):** guard `modelId` type before calling `.indexOf()` — prevents a `TypeError` when a model entry without a string `id` reaches the comparison logic in CLI Tools. -- **fix(providers):** add missing `isLocalProvider` import and update changelog. -- **fix(resilience):** add API Key health tracking with automatic rotation and UI toast alerts. ([#2412](https://github.com/diegosouzapw/OmniRoute/pull/2412) — thanks @clousky2020) -- **feat(providers):** support Gemini API keys for Gemini CLI executor. ([#2408](https://github.com/diegosouzapw/OmniRoute/pull/2408) — thanks @benzntech) -- **feat(gamification):** implement Gamification & Leaderboard System with non-blocking event-driven updates. ([#2405](https://github.com/diegosouzapw/OmniRoute/pull/2405) — thanks @oyi77) -- **fix(providers):** Kilo Code provider no longer blocks on a missing local `kilocode` CLI binary — the provider uses OAuth device flow + direct HTTPS to `api.kilo.ai` and never required the CLI at runtime; the connection test was hard-failing with "Local CLI runtime is not installed" even when the OAuth token was valid. CLI Tools integration (`/api/cli-tools/kilo-settings`) keeps its own runtime check. ([#2404](https://github.com/diegosouzapw/OmniRoute/issues/2404) — thanks @Flexible78) -- **fix(db):** `bun add -g omniroute` (and other runtimes that skip postinstall) no longer surfaces a generic 500 — `isNativeSqliteLoadError` now also detects "Could not locate the bindings file" / `MODULE_NOT_FOUND`, so the user gets the friendly rebuild guide instead. ([#2358](https://github.com/diegosouzapw/OmniRoute/issues/2358) — thanks @yamansin) -- **fix(kiro):** enable Google OAuth login option in the Kiro auth modal — surfaces the Google SSO button alongside the existing identity providers. ([#2392](https://github.com/diegosouzapw/OmniRoute/pull/2392) — thanks @congvc-dev) +- **chore(i18n):** 全面覆盖控制台 i18n — 经过 6 轮并行重构，将 57+ 个控制台页面中的硬编码英文/葡萄牙文文本替换为 `t()` 调用；在 `en.json` 中新增 420+ 个 key，覆盖 `settings`、`playground`、`analytics`、`apiManager`、`providers`、`skills`、`memory`、`agents` 及 15 个其他命名空间（覆盖率：约 88%，从约 20% 提升）。 +- **fix(offline):** 避免离线状态页面的 SSR/CSR 注水不匹配 — 从 `useState` 惰性初始化器（在服务器上访问 `navigator.onLine`）切换为 `useSyncExternalStore`，并使用独立的 `false` 服务器快照，消除了 React 注水警告。 +- **fix(cli-tools):** 调用 `.indexOf()` 前校验 `modelId` 类型 — 防止没有字符串 `id` 的模型条目到达 CLI 工具的比较逻辑时抛出 `TypeError`。 +- **fix(providers):** 添加缺失的 `isLocalProvider` 导入并更新变更日志。 +- **fix(resilience):** 新增 API Key 健康追踪功能，支持自动轮换和 UI 通知提示。([#2412](https://github.com/diegosouzapw/OmniRoute/pull/2412) — 感谢 @clousky2020) +- **feat(providers):** support Gemini API keys for Gemini CLI executor. ([#2408](https://github.com/diegosouzapw/OmniRoute/pull/2408) — 感谢 @benzntech) +- **feat(gamification):** implement Gamification & Leaderboard System with non-blocking event-driven updates. ([#2405](https://github.com/diegosouzapw/OmniRoute/pull/2405) — 感谢 @oyi77) +- **fix(providers):** Kilo Code provider no longer blocks on a missing local `kilocode` CLI binary — the 服务商 uses OAuth device flow + direct HTTPS to `api.kilo.ai` and never required the CLI at runtime; the 连接 test was hard-failing with "Local CLI runtime is not installed" even when the OAuth token was valid. CLI Tools 集成 (`/api/cli-tools/kilo-settings`) keeps its own runtime check. ([#2404](https://github.com/diegosouzapw/OmniRoute/issues/2404) — 感谢 @Flexible78) +- **fix(db):** `bun add -g omniroute` (and other runtimes that skip postinstall) no longer surfaces a generic 500 — `isNativeSqliteLoadError` now also detects "Could not locate the bindings file" / `MODULE_NOT_FOUND`, so the user gets the friendly rebuild guide instead. ([#2358](https://github.com/diegosouzapw/OmniRoute/issues/2358) — 感谢 @yamansin) +- **fix(kiro):** enable Google OAuth login option in the Kiro auth modal — surfaces the Google SSO 按钮 alongside the existing identity 服务商. ([#2392](https://github.com/diegosouzapw/OmniRoute/pull/2392) — 感谢 @congvc-dev) - **fix(security):** drop hashing layer in `sessionPoolKey` after switching to a non-cryptographic key derivation strategy that clears CodeQL alert #247. ([#2396](https://github.com/diegosouzapw/OmniRoute/pull/2396)) -- **feat(providers):** Gemini Web cookie-based provider — proxies google.com chat through a session cookie, allowing free Gemini access without API keys. ([#2380](https://github.com/diegosouzapw/OmniRoute/pull/2380) — thanks @oyi77) -- **model:** add Composer 2.5 to the Cursor provider catalog. ([#2381](https://github.com/diegosouzapw/OmniRoute/pull/2381) — thanks @backryun) -- **fix:** `tool_use` without adjacent `tool_result` causes Claude 400 — adjacency guard now also applies inside `compressContext`. ([#2383](https://github.com/diegosouzapw/OmniRoute/pull/2383) — thanks @oyi77) +- **feat(providers):** Gemini Web cookie-based provider — proxies google.com chat through a 会话 cookie, allowing free Gemini access without API keys. ([#2380](https://github.com/diegosouzapw/OmniRoute/pull/2380) — 感谢 @oyi77) +- **model:** add Composer 2.5 to the Cursor provider catalog. ([#2381](https://github.com/diegosouzapw/OmniRoute/pull/2381) — 感谢 @backryun) +- **fix:** `tool_use` without adjacent `tool_result` causes Claude 400 — adjacency 守卫 now also applies inside `compressContext`. ([#2383](https://github.com/diegosouzapw/OmniRoute/pull/2383) — 感谢 @oyi77) - **build(deps):** bump `electron` from 42.0.1 to 42.1.0 in `/electron`. ([#2397](https://github.com/diegosouzapw/OmniRoute/pull/2397)) - **build(deps):** production group bumps — 4 updates. ([#2398](https://github.com/diegosouzapw/OmniRoute/pull/2398)) - **build(deps):** development group bumps — 4 updates. ([#2399](https://github.com/diegosouzapw/OmniRoute/pull/2399)) @@ -1895,56 +1878,56 @@ must be a response to a preceding message with 'tool_calls'` when a Codex - **docs(readme):** restore the 9router acknowledgment that was inadvertently dropped during the v3.8.0 README rework. ([#2393](https://github.com/diegosouzapw/OmniRoute/pull/2393)) - **refactor(dashboard):** comprehensive nav, providers, endpoint, runtime, quota, pricing, budget redesign + quota sharing preview (sidebar restructure → 12 collapsible sections, 22 new routes). ([#2384](https://github.com/diegosouzapw/OmniRoute/pull/2384)) - **fix(dashboard):** PR #2384 follow-up review fixes — Runtime quota i18n, Budget projection logic, QuotaShare i18n externalization, Provider Limits semantic markup, bulk endpoint usage. ([#2389](https://github.com/diegosouzapw/OmniRoute/pull/2389)) -- **feat(content):** add Haiper, Leonardo, Ideogram, Suno, and Udio as content/media providers. ([#2377](https://github.com/diegosouzapw/OmniRoute/pull/2377) — thanks @oyi77) -- **feat(@omniroute/opencode-provider):** expand config helpers, add MCP entry, live model fetch, and combo builder. ([#2375](https://github.com/diegosouzapw/OmniRoute/pull/2375) — thanks @mrmm) -- **fix(claude-oauth):** enable system-transforms pipeline for the native Claude executor (closes 400 billing-gate). ([#2370](https://github.com/diegosouzapw/OmniRoute/pull/2370) — thanks @thepigdestroyer) -- **feat(content):** extend providers with video, audio, TTS, music capabilities — Pollinations, MiniMax, Together, Replicate across Audio TTS and Transcription registries. ([#2369](https://github.com/diegosouzapw/OmniRoute/pull/2369) — thanks @oyi77) -- **feat(providers):** add Veo AI Free as a web-wrapper provider for generating video, image, and TTS without an API key. ([#2366](https://github.com/diegosouzapw/OmniRoute/pull/2366) — thanks @oyi77) -- **feat(providers):** add Replicate as a free provider for OpenAI-compatible inference with community models. ([#2364](https://github.com/diegosouzapw/OmniRoute/pull/2364) — thanks @oyi77) -- **fix(claude):** avoided redundant deep cloning of Claude Code messages during semantic passthrough preparation, improving memory/CPU efficiency for large histories. ([#2362](https://github.com/diegosouzapw/OmniRoute/pull/2362) — thanks @terence71-glitch) +- **feat(content):** add Haiper, Leonardo, Ideogram, Suno, and Udio as content/media providers. ([#2377](https://github.com/diegosouzapw/OmniRoute/pull/2377) — 感谢 @oyi77) +- **feat(@omniroute/opencode-provider):** expand config helpers, add MCP entry, live model fetch, and combo builder. ([#2375](https://github.com/diegosouzapw/OmniRoute/pull/2375) — 感谢 @mrmm) +- **fix(claude-oauth):** enable system-transforms pipeline for the native Claude executor (closes 400 billing-gate). ([#2370](https://github.com/diegosouzapw/OmniRoute/pull/2370) — 感谢 @thepigdestroyer) +- **feat(content):** extend providers with video, audio, TTS, music capabilities — Pollinations, MiniMax, Together, Replicate across Audio TTS and Transcription registries. ([#2369](https://github.com/diegosouzapw/OmniRoute/pull/2369) — 感谢 @oyi77) +- **feat(providers):** add Veo AI Free as a web-wrapper provider for generating video, image, and TTS without an API key. ([#2366](https://github.com/diegosouzapw/OmniRoute/pull/2366) — 感谢 @oyi77) +- **feat(providers):** add Replicate as a free provider for OpenAI-compatible inference with community models. ([#2364](https://github.com/diegosouzapw/OmniRoute/pull/2364) — 感谢 @oyi77) +- **fix(claude):** avoided redundant deep cloning of Claude Code messages during semantic passthrough preparation, improving memory/CPU efficiency for large histories. ([#2362](https://github.com/diegosouzapw/OmniRoute/pull/2362) — 感谢 @terence71-glitch) - **fix(providers):** register `llm7` in the executor registry and route Cohere via OpenAI-compatible layer. ([#2361](https://github.com/diegosouzapw/OmniRoute/pull/2361), [#2360](https://github.com/diegosouzapw/OmniRoute/pull/2360)) - **fix(rate-limiter):** Redis is now opt-in — when `REDIS_URL` is unset, the rate limiter falls back to the in-memory store instead of spamming `ECONNREFUSED`. ([#2357](https://github.com/diegosouzapw/OmniRoute/pull/2357)) -- **fix(streaming):** emit protocol-aware stream errors — `createDisconnectAwareStream()` now emits native Responses API or Claude API SSE error blocks based on the client protocol. ([#2355](https://github.com/diegosouzapw/OmniRoute/pull/2355) — thanks @dhaern) -- **fix(combos):** allow bracketed combo names (e.g. `Claude [1m]`) by updating validation schemas. ([#2354](https://github.com/diegosouzapw/OmniRoute/pull/2354) — thanks @congvc-dev) -- **fix(claude-code):** semantic passthrough — preserve Claude Code `messages[]` structure for native Claude OAuth and relay routes. ([#2351](https://github.com/diegosouzapw/OmniRoute/pull/2351) — thanks @terence71-glitch) -- **fix(usage):** extract flat `cached_tokens` and `reasoning_tokens` from OpenAI-compatible usage objects. ([#2350](https://github.com/diegosouzapw/OmniRoute/pull/2350) — thanks @TF0rd) -- **fix(translator):** DeepSeek tool-call response lookup reads cached reasoning before falling back to empty string. ([#2349](https://github.com/diegosouzapw/OmniRoute/pull/2349) — thanks @herjarsa) -- **fix(ui/tooltip):** render in portal + clamp to viewport so tooltips aren't clipped in modal dialogs. ([#2352](https://github.com/diegosouzapw/OmniRoute/pull/2352) — thanks @slider23) +- **fix(streaming):** emit protocol-aware stream errors — `createDisconnectAwareStream()` now emits native Responses API or Claude API SSE error blocks based on the client protocol. ([#2355](https://github.com/diegosouzapw/OmniRoute/pull/2355) — 感谢 @dhaern) +- **fix(combos):** allow bracketed combo names (e.g. `Claude [1m]`) by updating validation schemas. ([#2354](https://github.com/diegosouzapw/OmniRoute/pull/2354) — 感谢 @congvc-dev) +- **fix(claude-code):** semantic passthrough — preserve Claude Code `messages[]` structure for native Claude OAuth and 中继 routes. ([#2351](https://github.com/diegosouzapw/OmniRoute/pull/2351) — 感谢 @terence71-glitch) +- **fix(usage):** extract flat `cached_tokens` and `reasoning_tokens` from OpenAI-compatible usage objects. ([#2350](https://github.com/diegosouzapw/OmniRoute/pull/2350) — 感谢 @TF0rd) +- **fix(translator):** DeepSeek tool-call response lookup reads cached reasoning before falling back to empty string. ([#2349](https://github.com/diegosouzapw/OmniRoute/pull/2349) — 感谢 @herjarsa) +- **fix(ui/tooltip):** render in portal + clamp to viewport so tooltips aren't clipped in modal dialogs. ([#2352](https://github.com/diegosouzapw/OmniRoute/pull/2352) — 感谢 @slider23) - **fix(auto-routing):** replace bare `getSettings()` with `getCachedSettings` to stop 500 on `auto/*` requests. ([#2346](https://github.com/diegosouzapw/OmniRoute/pull/2346)) - **fix(docker):** ship Dashboard Docs markdown in the container image. ([#2348](https://github.com/diegosouzapw/OmniRoute/pull/2348)) - **fix(combo/validator):** treat upstream responses carrying a non-empty `reasoning_content` as valid output. ([#2341](https://github.com/diegosouzapw/OmniRoute/pull/2341)) - **fix(account-fallback):** classify Anthropic `Usage Limit Reached` as `QUOTA_EXHAUSTED` with a 1h cooldown. ([#2321](https://github.com/diegosouzapw/OmniRoute/pull/2321)) -- **feat(providers):** add GitHub Models as a free provider — GPT-5, o-series, DeepSeek-R1, Llama 4, Grok 3. ([#2344](https://github.com/diegosouzapw/OmniRoute/pull/2344) — thanks @oyi77) -- **feat(providers):** add Hackclub AI as a free provider — 30+ models, no credit card required. ([#2339](https://github.com/diegosouzapw/OmniRoute/pull/2339) — thanks @oyi77) -- **feat(providers):** add Microsoft Copilot Web executor — WebSocket-based provider. ([#2340](https://github.com/diegosouzapw/OmniRoute/pull/2340) — thanks @oyi77) -- **feat(routing):** LKGP stores last known good account `connectionId` alongside provider. ([#2338](https://github.com/diegosouzapw/OmniRoute/pull/2338) — thanks @oyi77) +- **feat(providers):** add GitHub Models as a free provider — GPT-5, o-series, DeepSeek-R1, Llama 4, Grok 3. ([#2344](https://github.com/diegosouzapw/OmniRoute/pull/2344) — 感谢 @oyi77) +- **feat(providers):** add Hackclub AI as a free provider — 30+ models, no credit card required. ([#2339](https://github.com/diegosouzapw/OmniRoute/pull/2339) — 感谢 @oyi77) +- **feat(providers):** add Microsoft Copilot Web executor — WebSocket-based provider. ([#2340](https://github.com/diegosouzapw/OmniRoute/pull/2340) — 感谢 @oyi77) +- **feat(routing):** LKGP stores last known good account `connectionId` alongside provider. ([#2338](https://github.com/diegosouzapw/OmniRoute/pull/2338) — 感谢 @oyi77) - **feat(dashboard):** add Claude Code auth import/export UI + i18n (three-PR series: libs, API routes, dashboard UI). - **feat(dashboard):** add Gemini CLI auth import/export UI + i18n (three-PR series: libs, API routes, dashboard UI). - **fix(routing):** implement embedding combos, local provider validation bypass, and resolve migration collisions. - **fix(build):** import Monaco ESM API to fix webpack `nls.messages-loader` error. -- **fix(ui):** v3.8.0 polish — connections border, sticky tabs, EN translations, save toasts, auto-combo catalog. ([#2305](https://github.com/diegosouzapw/OmniRoute/pull/2305) — thanks @mrmm) -- **fix(auth+build):** Bearer manage scope on management routes + lazy-load deepseek PoW solver. ([#2308](https://github.com/diegosouzapw/OmniRoute/pull/2308) — thanks @mrmm) -- **fix(claude):** guard orphan tool_use/tool_result pairs before upstream send. ([#2312](https://github.com/diegosouzapw/OmniRoute/pull/2312) — thanks @mrmm) -- **fix(ui):** remove count from batch removal button. ([#2309](https://github.com/diegosouzapw/OmniRoute/pull/2309) — thanks @hartmark) -- **fix:** remove implicit API key request caps — removes default 1K/5K/20K rate caps. ([#2289](https://github.com/diegosouzapw/OmniRoute/pull/2289) — thanks @josephvoxone) -- **fix(sse):** strip stale `Content-Encoding`, `Content-Length`, and `Transfer-Encoding` headers on non-streaming forward. ([#2264](https://github.com/diegosouzapw/OmniRoute/pull/2264) — thanks @gleber) -- **chore(providers):** refresh provider model metadata and ordering. ([#2318](https://github.com/diegosouzapw/OmniRoute/pull/2318) — thanks @backryun) -- **chore(providers):** consolidate Alibaba provider entries. ([#2319](https://github.com/diegosouzapw/OmniRoute/pull/2319) — thanks @backryun) -- **fix(streaming):** harden stream readiness detection. ([#2317](https://github.com/diegosouzapw/OmniRoute/pull/2317) — thanks @dhaern) -- **fix(v1/messages):** default to non-streaming when `stream` field is absent for Anthropic format. ([#2326](https://github.com/diegosouzapw/OmniRoute/pull/2326) — thanks @thepigdestroyer) -- **fix(claude):** `fitThinkingToMaxTokens` caps thinking budget to model's output ceiling. ([#2327](https://github.com/diegosouzapw/OmniRoute/pull/2327) — thanks @thepigdestroyer) -- **fix(codex):** Codex reasoning priority resolves `modelEffort` before `explicitReasoning`. ([#2335](https://github.com/diegosouzapw/OmniRoute/pull/2335) — thanks @terence71-glitch) -- **fix(providers):** providers page no longer deadlocks when no providers are configured. ([#2329](https://github.com/diegosouzapw/OmniRoute/pull/2329) — thanks @slider23) -- **chore(providers):** update HuggingFace to use the new `/v1/` router endpoint. ([#2322](https://github.com/diegosouzapw/OmniRoute/pull/2322) — thanks @backryun) +- **fix(ui):** v3.8.0 polish — connections border, sticky tabs, EN translations, save toasts, auto-Combo catalog. ([#2305](https://github.com/diegosouzapw/OmniRoute/pull/2305) — 感谢 @mrmm) +- **fix(auth+build):** Bearer manage scope on management routes + lazy-load deepseek PoW solver. ([#2308](https://github.com/diegosouzapw/OmniRoute/pull/2308) — 感谢 @mrmm) +- **fix(claude):** guard orphan tool_use/tool_result pairs before upstream send. ([#2312](https://github.com/diegosouzapw/OmniRoute/pull/2312) — 感谢 @mrmm) +- **fix(ui):** remove count from batch removal button. ([#2309](https://github.com/diegosouzapw/OmniRoute/pull/2309) — 感谢 @hartmark) +- **fix:** remove implicit API key request caps — removes 默认 1K/5K/20K rate caps. ([#2289](https://github.com/diegosouzapw/OmniRoute/pull/2289) — 感谢 @josephvoxone) +- **fix(sse):** strip stale `Content-Encoding`, `Content-Length`, and `Transfer-Encoding` headers on non-streaming forward. ([#2264](https://github.com/diegosouzapw/OmniRoute/pull/2264) — 感谢 @gleber) +- **chore(providers):** refresh provider model metadata and ordering. ([#2318](https://github.com/diegosouzapw/OmniRoute/pull/2318) — 感谢 @backryun) +- **chore(providers):** consolidate Alibaba provider entries. ([#2319](https://github.com/diegosouzapw/OmniRoute/pull/2319) — 感谢 @backryun) +- **fix(streaming):** harden stream readiness detection. ([#2317](https://github.com/diegosouzapw/OmniRoute/pull/2317) — 感谢 @dhaern) +- **fix(v1/messages):** default to non-streaming when `stream` field is absent for Anthropic format. ([#2326](https://github.com/diegosouzapw/OmniRoute/pull/2326) — 感谢 @thepigdestroyer) +- **fix(claude):** `fitThinkingToMaxTokens` caps thinking budget to model's output ceiling. ([#2327](https://github.com/diegosouzapw/OmniRoute/pull/2327) — 感谢 @thepigdestroyer) +- **fix(codex):** Codex reasoning priority resolves `modelEffort` before `explicitReasoning`. ([#2335](https://github.com/diegosouzapw/OmniRoute/pull/2335) — 感谢 @terence71-glitch) +- **fix(providers):** providers page no longer deadlocks when no providers are configured. ([#2329](https://github.com/diegosouzapw/OmniRoute/pull/2329) — 感谢 @slider23) +- **chore(providers):** update HuggingFace to use the new `/v1/` router endpoint. ([#2322](https://github.com/diegosouzapw/OmniRoute/pull/2322) — 感谢 @backryun) - **fix(security):** resolve CodeQL ReDoS + URL sanitization alerts. - **fix(auth):** stop retrying unrecoverable token refresh failures and include connection id in token health check credentials. - **fix(auth):** return synthetic credentials for noAuth free providers and show no-auth card in dashboard instead of OAuth modal. - **fix(endpoint):** replace nested `