# OmniRoute Codebase Documentation (中文 (简体))

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇹 [pt](../../../pt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)

---

> OmniRoute 代码库工程参考文档，面向贡献者和集成开发者。

---

## 1. 技术栈

| 关注领域 | 技术选型                                                                                                        |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| 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` 是唯一的子工作空间                                                                   |

路径别名（`tsconfig.json`）：

- `@/*` → `src/*`
- `@omniroute/open-sse` → `open-sse/index.ts`
- `@omniroute/open-sse/*` → `open-sse/*`

默认 HTTP 端口：**`20128`**（API 和仪表盘共享同一进程）。数据目录由 `DATA_DIR` 环境变量指定，默认为 `~/.omniroute/`。

---

## 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         路径别名 + 核心编译选项
```

---

## 3. `src/` — Next.js 应用程序

```
src/
├── app/                  App Router 页面 + API 路由
├── lib/                  核心库（数据库、身份验证、OAuth、技能、记忆等）
├── domain/               纯领域层（策略、回退、成本、锁定等）
├── server/               仅服务端模块（授权、CORS、身份验证）
├── shared/               类型、常量、验证、契约、工具（可安全跨边界使用）
├── mitm/                 用于 CLI 集成的中间人代理辅助工具
├── models/               本地模型元数据/别名
├── sse/                  仍位于 src/ 下的旧版 SSE 处理程序（不在 open-sse/ 中）
├── store/                客户端状态存储
├── middleware/           路由级中间件工具（并非 Next.js 全局中间件）
├── scripts/              可由应用程序代码导入的树内脚本
├── types/                环境类型和共享 TS 类型
├── i18n/                 本地化资源包
├── instrumentation.ts    Next.js 检测钩子
├── instrumentation-node.ts
└── proxy.ts              顶层代理引导辅助工具
```

### 3.1 `src/app/` — App Router

App Router 同时提供仪表板 UI 和公共/管理 HTTP API。
这里**没有全局中间件**——拦截按路由执行。

`src/app/` 下的顶层分段：

| 路径                                                                          | 用途                                 |
| ----------------------------------------------------------------------------- | ------------------------------------ |
| `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 页面

`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 组

```
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/
```

#### 3.1.2a `src/app/api/services/` — 嵌入式服务管理

用于安装、启动、停止和监控 9Router 与 CLIProxyAPI 的路由。
所有路径均被分类为 **LOCAL_ONLY**（仅允许环回地址，硬性规则 #17），因为它们
可以调用 `npm install` 并生成子进程。

```
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 密钥并重启
│   ├── status/route.ts     GET  — 实时状态、数据库状态和版本元数据
│   └── 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  — 实时状态、数据库状态和版本元数据
│   └── 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`

深入解析：`docs/frameworks/EMBEDDED-SERVICES.md`

#### 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/                    Chat Completions（主要端点）
├── 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/                     已注册密钥管理
├── rerank/                              重新排序
├── responses/[...path]/                 OpenAI Responses API（全捕获路由）
├── search/                              Web 搜索
├── videos/                              视频生成
├── ws/                                  WebSocket 桥接
└── route.ts                             索引处理程序
```

每个路由文件都遵循相同的模式：

```
路由 → CORS 预检 → Zod 请求体校验 → 可选身份验证
     → API 密钥策略执行 → 处理程序委托（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/`         | 组合解析辅助工具                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `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/提供者导入模块（22 个）：`agy`、`antigravity`、`claude`、`cline`、`codebuddy-cn`、`codex`、`cursor`、`devin-desktop`、`ghe-copilot`、`github`、`gitlab-duo`、`grok-cli-oauth`、`grok-cli`、`kilocode`、`kimi-coding`、`kiro`、`openference`、`qoder`、`trae`、`xai-oauth`、`zed-hosted`、`zed`，以及 `services/`、`utils/` 和 `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 密钥存储）、`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` 桶文件已被移除——使用方直接导入特定的 `src/lib/db/*` 模块。
- `proxyHealth.ts`、`proxyLogger.ts`、`tokenHealthCheck.ts`、`localHealthCheck.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**——请通过这些模块进行操作。

![数据库架构概览（选定的核心表）](../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/` 包含 168 个带版本号的 `.sql` 文件（幂等且支持事务），并在启动时由 `migrationRunner.ts` 执行。

所有迁移创建的表（共 123 个）：

`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`                         | 将请求解析为组合目标列表       |
| `connectionModelRules.ts`                  | 各连接的模型过滤器             |
| `modelAvailability.ts`                     | 模型可用性检查                 |
| `degradation.ts`                           | 降级模式转换                   |
| `providerExpiration.ts`                    | 过期账户/密钥检测              |
| `quotaCache.ts`                            | 缓存的配额决策                 |
| `responses.ts`、`omnirouteResponseMeta.ts` | 响应结构辅助函数               |
| `configAudit.ts`                           | 配置变更审计                   |
| `assessment/`                              | 模型评估（依据 RFC，部分实现） |
| `types.ts`                                 | 共享领域类型                   |

### 3.4 `src/server/` — 仅限服务端

不能从客户端组件中导入。

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        将路由分类为公共路由或管理路由
│   ├── assertAuth.ts      断言辅助函数
│   ├── context.ts         每个请求的授权上下文
│   ├── headers.ts
│   ├── pipeline.ts        授权管线
│   ├── policies/          具体策略
│   └── types.ts
└── cors/origins.ts        CORS 来源允许列表
```

### 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 模式）、`compressionConfigSchemas.ts`、
  `providerSchema.ts`、`settingsSchemas.ts`、`helpers.ts`。
- `contracts/` — 发布到 npm 的公共 API 契约。
- `types/` — 共享的 TS 类型。
- `utils/` — `circuitBreaker.ts`、`apiAuth.ts`、`apiKey.ts`、`apiKeyPolicy.ts`、
  `api.ts`、`classify429.ts`、`cliCompat.ts`、`clipboard.ts`、`cloud.ts`、`cn.ts`、
  `cors.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/` 下的仪表板钩子和组件。

---

## 4. `open-sse/` — 流式引擎工作区

作为独立的 npm 工作区发布，包名为 `@omniroute/open-sse`。负责请求处理、执行器、转换器、服务、变换器和 MCP 服务器。

```
open-sse/
├── index.ts                公共导出
├── package.json            工作区清单
├── tsconfig.json
├── types.d.ts
├── config/                 提供者注册表、请求头配置、身份信息等
├── handlers/               请求处理器（聊天、嵌入、音频、图像等）
├── executors/              108 个提供者专用的 HTTP 执行器
├── translator/             格式转换（OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro）
├── transformer/            Responses API ↔ Chat Completions 流变换器
├── services/               80 多个服务模块（组合、回退、配额、身份信息等）
├── utils/                  流式处理辅助工具、TLS 客户端、AWS SigV4、代理 fetch 等
└── mcp-server/             MCP 服务器（3 种传输方式、33 个作用域、110 个工具）
```

### 4.1 `open-sse/handlers/`

| 处理器                  | 用途                                               |
| ----------------------- | -------------------------------------------------- |
| `chatCore.ts`           | 主聊天管线（缓存、速率限制、组合路由、执行器分派） |
| `responsesHandler.ts`   | OpenAI Responses API 入口点                        |
| `embeddings.ts`         | 嵌入                                               |
| `imageGeneration.ts`    | 图像生成                                           |
| `audioSpeech.ts`        | 文本转语音                                         |
| `audioTranscription.ts` | 语音转文本                                         |
| `videoGeneration.ts`    | 视频生成                                           |
| `musicGeneration.ts`    | 音乐生成                                           |
| `rerank.ts`             | 重排序                                             |
| `moderations.ts`        | 内容审核                                           |
| `search.ts`             | Web 搜索                                           |
| `sseParser.ts`          | SSE 事件解析器                                     |
| `usageExtractor.ts`     | 从上游流中提取 token 数量                          |
| `responseSanitizer.ts`  | 移除提供者特有的无关内容                           |
| `responseTranslator.ts` | 连接提供者响应与转换器层的粘合层                   |

### 4.2 `open-sse/executors/`

108 个提供者执行器，每个都扩展自 `BaseExecutor`（`base.ts`）：

`antigravity`、`azure-openai`、`blackbox-web`、`cliproxyapi`、
`chatgpt-web-codex`、`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、
`muse-spark-web`、`nlpcloud`、`opencode`、`perplexity-web`、`petals`、
`pollinations`、`qoder`、`vertex`、`devin-desktop`，以及 `claudeIdentity.ts`
（共享身份辅助工具）和 `index.ts`（注册表）。

> 注意：此处未列出的提供者由 `default.ts` 使用通用的
> OpenAI 兼容执行器提供服务。完整的提供者目录（355 个提供者）位于
> `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`（19 种策略）、`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`、`requestRejectedStreak.ts`、`emergencyFallback.ts`、`rateLimitManager.ts`、`rateLimitSemaphore.ts`、`accountSemaphore.ts`、`accountSelector.ts`                                               |
| 配额            | `quotaMonitor.ts`、`quotaPreflight.ts`、`bailianQuotaFetcher.ts`、`codexQuotaFetcher.ts`、`deepseekQuotaFetcher.ts`、`openrouterQuotaFetcher.ts`、`openrouterFreeWindow.ts`、`llmgatewayQuotaFetcher.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/` — 完整的压缩引擎接线                                                                                                                                                                                                                      |
| 令牌 + 会话     | `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/`

- **110 个唯一工具**在 `server.ts` 中完成接线（`schemas/tools.ts` 中有 45 个规范工具，外加
  内存、技能、GitHub 技能、池、游戏化、插件、Notion、Obsidian、
  本地语料库和压缩模块——由 `countUniqueMcpTools` 对并集进行计数）。
- **3 种传输方式**：stdio、HTTP Streamable、SSE。
- 运行时强制执行 **33 个作用域**——基础列表位于 `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`。

---

## 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 源实现。

---

## 6. `bin/` — CLI

```
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/` | 支撑                                                                              |

常用命令：

| 命令                                                     | 运行内容                                                |
| -------------------------------------------------------- | ------------------------------------------------------- |
| `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/<file>.test.ts` | 单文件运行                                              |

---

## 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`。

---

## 9. 请求管道（摘要）

![请求管道（/v1/chat/completions）](../diagrams/exported/request-pipeline.svg)

> 来源：[diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
客户端请求
  → /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/）
  → 响应到客户端
```

### 容灾运行时状态（三种机制）

| 机制         | 范围                 | 位置                                                                                                       |
| ------------ | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| 服务商熔断器 | 整个服务商           | `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`                                    |

参见 [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) 和 [CLAUDE.md](../../CLAUDE.md) 中的专门章节。

---

## 10. 贡献指南

### 添加新服务商

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/` 下编写测试。

### 添加新 API 路由

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`。

### 添加新 DB 模块

1. 创建 `src/lib/db/yourModule.ts`，从 `./core.ts` 导入 `getDbInstance()`。
2. 导出你领域的 CRUD 函数。
3. 若需新表：在 `src/lib/db/migrations/` 下添加迁移文件，按序编号，幂等、事务性。
4. 从 `src/lib/localDb.ts` 重新导出（仅限重新导出 — **无逻辑**）。
5. 在 `tests/unit/` 下添加测试。

### 添加新 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)。

### 添加新 A2A 技能

参见 [A2A-SERVER.md § 添加新技能](../frameworks/A2A-SERVER.md)。技能位于 `src/lib/a2a/skills/`，通过 A2A 任务管理器注册。

---

## 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`）。

---

## 12. 硬规则（来自 CLAUDE.md）

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%（语句、行、函数、分支）。

---

## 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 的深层架构参考。