OmniRoute/docs/i18n/vi/docs/architecture/CODEBASE_DOCUMENTATION.md

OmniRoute Codebase Documentation (Tiếng Việt)

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

---

Phiên bản: v3.8.51 Cập nhật lần cuối: 2026-06-28 Đối tượng: Các kỹ sư đóng góp cho OmniRoute hoặc xây dựng tích hợp trên nền tảng này.

Để xem các sơ đồ kiến trúc cấp cao và lý do thiết kế đằng sau từng hệ thống con, hãy đọc ARCHITECTURE.md. Để tìm hiểu chuyên sâu về từng hệ thống con (Auto Combo, máy chủ MCP, máy chủ A2A, Skills, Memory, Cloud Agents, Resilience, Compression, v.v.), hãy xem các tệp chuyên biệt tương ứng trong thư mục docs/ này.

Tệp này mô tả những gì hiện có trong kho lưu trữ để một kỹ sư mới có thể điều hướng cây thư mục, hiểu cách phân lớp thời gian chạy và biết nơi cần thêm mã mà không phải tạo ra các mô-đun mới.

---

1. Ngăn xếp công nghệ

Mối quan tâm	Lựa chọn
Framework web	Next.js 16 (App Router, đầu ra độc lập, không có middleware toàn cục)
Ngôn ngữ	TypeScript 6.0+ — đích ES2022, module: esnext, moduleResolution: bundler, strict: false
Môi trường chạy	Node.js >=22.22.2 <23 hoặc >=24.0.0 <27 (được thực thi thông qua engines + SUPPORTED_NODE_RANGE)
Cơ sở dữ liệu	SQLite thông qua better-sqlite3 (singleton, ghi nhật ký WAL)
Máy tính để bàn	Electron 41 + electron-builder 26.10 (workspace riêng tại electron/)
Kiểm thử	Trình chạy kiểm thử gốc của Node (đơn vị/tích hợp), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Bản dựng	Next.js độc lập thông qua scripts/build/build-next-isolated.mjs
Lint/định dạng	Cấu hình phẳng ESLint + Prettier (lint-staged thông qua Husky pre-commit)
Hệ thống mô-đun	ESM ở mọi nơi ("type": "module")
Workspace	npm workspace — open-sse là workspace con duy nhất

Bí danh đường dẫn (tsconfig.json):

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

Cổng HTTP mặc định: 20128 (API và bảng điều khiển dùng chung một tiến trình). Thư mục dữ liệu là biến môi trường DATA_DIR, mặc định là ~/.omniroute/.

---

2. Bố cục kho lưu trữ

OmniRoute/
├── src/                  Ứng dụng Next.js (App Router, thư viện, miền nghiệp vụ, máy chủ, thành phần dùng chung)
├── open-sse/             Workspace của công cụ truyền phát (@omniroute/open-sse)
├── electron/             Trình bao bọc máy tính để bàn (tiến trình chính Electron 41 + preload)
├── bin/                  Các điểm vào CLI (omniroute, reset-password)
├── tests/                Kiểm thử đơn vị, tích hợp, e2e, protocols-e2e, trình dịch, bảo mật, fixture
├── scripts/              Các tập lệnh hỗ trợ bản dựng, đồng bộ, kiểm tra, di chuyển và thời gian chạy
├── docs/                 Tài liệu công khai (thư mục này)
├── public/               Tài nguyên tĩnh, tệp kê khai PWA, service worker
├── config/               Các mẫu cấu hình thời gian chạy
├── images/               Tài nguyên tiếp thị/ảnh chụp màn hình
├── _ideia/, _references/, _mono_repo/, _tasks/   Ghi chú tạm / lập kế hoạch nội bộ (không được phân phối)
├── CLAUDE.md             Quy tắc kho lưu trữ dành cho Claude Code
├── AGENTS.md             Tài liệu tham khảo kiến trúc chuyên sâu hơn dành cho agent
├── package.json          v3.8.51, workspace gốc
└── tsconfig.json         Bí danh đường dẫn + các tùy chọn cốt lõi của trình biên dịch

---

3. src/ — Ứng dụng Next.js

src/
├── app/                  Các trang App Router + các route API
├── lib/                  Các thư viện cốt lõi (DB, xác thực, OAuth, kỹ năng, bộ nhớ, …)
├── domain/               Lớp miền thuần túy (chính sách, dự phòng, chi phí, khóa truy cập, …)
├── server/               Các mô-đun chỉ dành cho máy chủ (phân quyền, cors, xác thực)
├── shared/               Kiểu, hằng số, xác thực dữ liệu, hợp đồng, tiện ích (an toàn khi dùng xuyên ranh giới)
├── mitm/                 Các trình trợ giúp proxy trung gian cho việc tích hợp CLI
├── models/               Siêu dữ liệu / ánh xạ bí danh của mô hình cục bộ
├── sse/                  Các trình xử lý SSE cũ vẫn nằm trong src/ (không phải open-sse/)
├── store/                Các kho trạng thái phía máy khách
├── middleware/           Các tiện ích middleware cấp route (không phải middleware toàn cục của Next.js)
├── scripts/              Các tập lệnh trong cây có thể được mã ứng dụng nhập
├── types/                Các kiểu TS môi trường và dùng chung
├── i18n/                 Các gói bản địa hóa
├── instrumentation.ts    Hook đo lường của Next.js
├── instrumentation-node.ts
└── proxy.ts              Trình trợ giúp khởi tạo proxy cấp cao nhất

3.1 src/app/ — App Router

App Router cung cấp cả giao diện bảng điều khiển lẫn API HTTP công khai/quản lý. Không có middleware toàn cục — việc chặn được thực hiện theo từng route.

Các phân đoạn cấp cao nhất trong src/app/:

Đường dẫn	Mục đích
api/	Tất cả các route API HTTP (xem phân tích dưới đây)
a2a/	Điểm cuối A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Tài liệu khám phá Agent Card của A2A
(dashboard)/	Giao diện bảng điều khiển (nhóm route, không có tiền tố URL)
auth/, login/, forgot-password/, callback/	Các luồng xác thực
landing/	Trang tiếp thị/trang đích
docs/	Trình xem tài liệu API được nhúng
status/, maintenance/, offline/	Các trang vận hành
privacy/, terms/	Các trang pháp lý
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Các trang lỗi tĩnh
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Các ranh giới lỗi/tải của framework
layout.tsx, page.tsx, globals.css, manifest.ts	Khung gốc

3.1.1 src/app/(dashboard)/dashboard/ — Các trang giao diện

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, cùng với page.tsx, HomePageClient.tsx, BootstrapBanner.tsx ở thư mục gốc.

3.1.2 src/app/api/ — Các nhóm API cấp cao nhất

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/   Quản lý dịch vụ nhúng (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API công khai tương thích với OpenAI
├── v1beta/     Khả năng tương thích theo kiểu Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Quản lý dịch vụ nhúng

Các route để cài đặt, khởi động, dừng và giám sát 9Router cùng CLIProxyAPI. Tất cả đường dẫn đều được phân loại là LOCAL_ONLY (chỉ loopback, quy tắc cứng số 17) vì chúng có thể gọi npm install và tạo các tiến trình con.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             hàm trợ giúp getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install thông qua execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install phiên bản mới hơn
│   ├── rotate-key/route.ts POST — tạo API key mới + khởi động lại
│   ├── status/route.ts     GET  — trạng thái trực tiếp + trạng thái DB + siêu dữ liệu phiên bản
│   └── auto-start/route.ts POST — bật/tắt cờ auto_start
├── cliproxy/
│   ├── _lib.ts             hàm trợ giúp 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 phiên bản mới hơn
│   ├── status/route.ts     GET  — trạng thái trực tiếp + trạng thái DB + siêu dữ liệu phiên bản
│   └── auto-start/route.ts POST — bật/tắt cờ auto_start
└── [name]/
    └── logs/route.ts       GET  — luồng nhật ký SSE (dùng chung cho tất cả dịch vụ)

Giao diện bảng điều khiển tương ứng: src/app/(dashboard)/dashboard/providers/services/ — trang hai tab (CLIProxyAPI + 9Router). Proxy ngược cho giao diện nhúng của 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Tìm hiểu chuyên sâu: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API công khai tương thích với OpenAI

v1/
├── accounts/[id]/                       tra cứu tài khoản
├── agents/tasks/[id]/, agents/tasks/    các endpoint tác vụ theo phong cách A2A
├── api/                                 các hàm trợ giúp API nội bộ được cung cấp tại v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (endpoint chính)
├── completions/                         hoàn thành văn bản kiểu cũ
├── embeddings/                          nhúng
├── files/[id]/, files/                  Files API
├── _helpers/                            các hàm trợ giúp route dùng chung (không có URL công khai)
├── images/{edits, generations}/         tạo + chỉnh sửa hình ảnh
├── issues/                              các endpoint trợ giúp phân loại
├── management/{proxies}/                các route thuộc phạm vi quản lý bên trong v1
├── messages/{count_tokens}/             tương thích messages theo phong cách Anthropic
├── models/                              danh sách mô hình (`route.ts`, `catalog.ts`)
├── moderations/                         kiểm duyệt
├── music/                               tạo nhạc
├── providers/[provider]/                các thao tác theo từng nhà cung cấp
├── quotas/{check}                       thăm dò hạn ngạch
├── registered-keys/                     quản trị khóa đã đăng ký
├── rerank/                              xếp hạng lại
├── responses/[...path]/                 OpenAI Responses API (bắt tất cả)
├── search/                              tìm kiếm trên web
├── videos/                              tạo video
├── ws/                                  cầu nối WebSocket
└── route.ts                             trình xử lý chỉ mục

Mỗi tệp route tuân theo cùng một mẫu:

Route → kiểm tra trước CORS → xác thực nội dung bằng Zod → xác thực tùy chọn
      → thực thi chính sách API key → ủy quyền cho trình xử lý (open-sse)

v1beta/ là bề mặt tương thích theo phong cách Gemini (một trình bao mỏng chuyển đổi sang cùng quy trình open-sse/handlers/).

3.2 src/lib/ — Các thư viện cốt lõi

Luôn nhập dữ liệu, đồng bộ hóa, OAuth, kỹ năng, bộ nhớ, v.v. thông qua các mô-đun này. Bảng nhóm các thư mục thực tế và những tệp cấp cao nhất đáng chú ý.

Mô-đun	Mục đích
a2a/	Máy chủ giao thức A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 kỹ năng: phân tích chi phí, báo cáo tình trạng, khám phá nhà cung cấp, quản lý hạn ngạch, định tuyến thông minh, liệt kê khả năng)
acp/	Giao thức kiểm soát tác nhân: index.ts, manager.ts, registry.ts
api/	Các tiện ích API nội bộ: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (đặt lại mật khẩu / băm)
batches/	Dịch vụ OpenAI Batches API (service.ts)
catalog/	Đồng bộ danh mục OpenRouter (openrouterCatalog.ts)
cloudAgent/	Sổ đăng ký tác nhân đám mây: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Các tiện ích phân giải tổ hợp
compliance/	Kiểm toán + kiểm toán nhà cung cấp: index.ts, providerAudit.ts
config/	Mã kết nối cấu hình thời gian chạy
db/	Các mô-đun miền SQLite (xem §3.2.1)
display/	Các tiện ích UI/hiển thị được phản hồi API sử dụng
embeddings/	Sổ đăng ký dịch vụ embedding
env/	Nạp + kiểm tra môi trường
evals/	Môi trường chạy đánh giá
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Các tác vụ nền (autoUpdate.ts, …)
memory/	Bộ nhớ bền vững: 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/	Các mô-đun OAuth/nhập nhà cung cấp (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, cùng với services/, utils/ và constants/oauth.ts
plugins/	Trình nạp plugin (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Vòng đời mô hình được quản lý: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Các tiện ích nhà cung cấp: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — cài đặt cho bộ ngắt mạch, thời gian chờ và khóa truy cập
runtime/	Phát hiện tính năng thời gian chạy
search/	executeWebSearch.ts
services/	Khung dịch vụ nhúng: ServiceSupervisor.ts (trình giám sát tiến trình con tổng quát với khóa thao tác, bộ đệm vòng và trình kiểm tra tình trạng), bootstrap.ts (đăng ký ở cấp tiến trình và tự động khởi động), registry.ts (ánh xạ công cụ → trình giám sát), apiKey.ts (kho khóa AES-256-GCM), modelSync.ts (đồng bộ mô hình định kỳ), ringBuffer.ts (bộ đệm nhật ký vòng 5 MB), healthCheck.ts (thăm dò tình trạng HTTP), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Xem docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Danh mục + trình tạo Kỹ năng Tác nhân: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → ghi vào skills/{id}/SKILL.md), openapiParser.ts (trích xuất các điểm cuối REST từ đặc tả OpenAPI), cliRegistryParser.ts (trích xuất các lệnh con CLI từ bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Được sử dụng bởi các tuyến REST (/api/agent-skills/*), công cụ MCP (omniroute_agent_skills_*) và kỹ năng A2A list-capabilities. Xem AGENT-SKILLS.md.
skills/	Khung kỹ năng: 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, cùng với builtin/browser.ts
spend/	batchWriter.ts (bộ đệm ghi trì hoãn)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Các tiện ích cấp hệ thống
translator/	Mã kết nối trình dịch cấp cao nhất (ủy quyền cho open-sse/translator/)
usage/	Hạch toán mức sử dụng: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Tự động cập nhật + bản kê phiên bản
ws/	Cầu nối WebSocket
zed-oauth/	Luồng OAuth của trình soạn thảo Zed

Các tệp cấp cao nhất trong src/lib/:

• Barrel localDb.ts cũ đã bị loại bỏ — các thành phần sử dụng sẽ nhập trực tiếp các mô-đun src/lib/db/* cụ thể.
• 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/

Cơ sở dữ liệu SQLite singleton (getDbInstance() trong core.ts, ghi nhật ký WAL). Không bao giờ viết SQL thô trong các route hoặc handler — hãy sử dụng các mô-đun này.

Nguồn: diagrams/db-schema-overview.mmd

Các mô-đun miền (mỗi mô-đun sở hữu một hoặc nhiều bảng): 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/ chứa 168 tệp .sql có phiên bản (có tính lũy đẳng, có tính giao dịch) và được migrationRunner.ts thực thi khi khởi động.

Các bảng được tạo trong toàn bộ các migration (tổng cộng 123 bảng):

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 (cùng với các bảng ảo FTS5 để tìm kiếm bộ nhớ).

3.3 src/domain/ — Lớp miền

Logic nghiệp vụ thuần túy, không có I/O. Được nhập bởi các route và handler.

Tệp	Mục đích
policyEngine.ts	Bộ phân giải chính sách cấp cao nhất
fallbackPolicy.ts	Cây quyết định dự phòng
costRules.ts	Các quy tắc tính chi phí
lockoutPolicy.ts	Các quyết định khóa mô hình
tagRouter.ts	Định tuyến dựa trên thẻ
comboResolver.ts	Phân giải combo từ yêu cầu → danh sách đích
connectionModelRules.ts	Bộ lọc mô hình theo từng kết nối
modelAvailability.ts	Kiểm tra tính khả dụng của mô hình
degradation.ts	Các chuyển đổi sang chế độ suy giảm
providerExpiration.ts	Phát hiện tài khoản/khóa đã hết hạn
quotaCache.ts	Các quyết định hạn ngạch được lưu vào bộ nhớ đệm
responses.ts, omnirouteResponseMeta.ts	Các hàm hỗ trợ định dạng phản hồi
configAudit.ts	Kiểm tra thay đổi cấu hình
assessment/	Đánh giá mô hình (theo RFC, được triển khai một phần)
types.ts	Các kiểu miền dùng chung

3.4 src/server/ — Chỉ dành cho máy chủ

Không thể được nhập từ các thành phần máy khách.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Phân loại route thành công khai hoặc quản lý
│   ├── assertAuth.ts      Hàm hỗ trợ xác nhận
│   ├── context.ts         Ngữ cảnh authz theo từng yêu cầu
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline authz
│   ├── policies/          Các chính sách cụ thể
│   └── types.ts
└── cors/origins.ts        Danh sách cho phép nguồn gốc CORS

3.5 src/shared/ — An toàn để chia sẻ

Được chia thành các thư mục con chuyên biệt:

• constants/ — providers.ts (danh mục nhà cung cấp được xác thực bằng Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (danh sách từ chối), 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 schema Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — các hợp đồng API công khai được phát hành lên npm.
• types/ — các kiểu TS dùng chung.
• 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, cùng với các hook/thành phần của bảng điều khiển trong services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — Không gian làm việc của công cụ streaming

Không gian làm việc npm riêng biệt được phát hành dưới tên @omniroute/open-sse. Sở hữu phần xử lý yêu cầu, các executor, translator, service, transformer và máy chủ MCP.

open-sse/
├── index.ts                Các export công khai
├── package.json            Manifest của không gian làm việc
├── tsconfig.json
├── types.d.ts
├── config/                 Registry nhà cung cấp, profile header, danh tính, …
├── handlers/               Các trình xử lý yêu cầu (chat, embedding, âm thanh, hình ảnh, …)
├── executors/              108 HTTP executor dành riêng cho từng nhà cung cấp
├── translator/             Chuyển đổi định dạng (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer luồng Responses API ↔ Chat Completions
├── services/               Hơn 80 mô-đun dịch vụ (tổ hợp, dự phòng, hạn ngạch, danh tính, …)
├── utils/                  Tiện ích streaming, máy khách TLS, AWS SigV4, proxy fetch, …
└── mcp-server/             Máy chủ MCP (3 phương thức truyền tải, 33 phạm vi, 110 công cụ)

4.1 open-sse/handlers/

Trình xử lý	Mục đích
chatCore.ts	Pipeline chat chính (bộ nhớ đệm, giới hạn tốc độ, định tuyến tổ hợp, điều phối executor)
responsesHandler.ts	Điểm vào OpenAI Responses API
embeddings.ts	Embedding
imageGeneration.ts	Tạo hình ảnh
audioSpeech.ts	Chuyển văn bản thành giọng nói
audioTranscription.ts	Chuyển giọng nói thành văn bản
videoGeneration.ts	Tạo video
musicGeneration.ts	Tạo nhạc
rerank.ts	Xếp hạng lại
moderations.ts	Kiểm duyệt
search.ts	Tìm kiếm trên web
sseParser.ts	Trình phân tích sự kiện SSE
usageExtractor.ts	Trích xuất số lượng token từ các luồng thượng nguồn
responseSanitizer.ts	Loại bỏ dữ liệu nhiễu dành riêng cho nhà cung cấp
responseTranslator.ts	Lớp kết nối giữa phản hồi của nhà cung cấp và tầng translator

4.2 open-sse/executors/

108 executor của nhà cung cấp, mỗi executor đều mở rộng 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, cùng với claudeIdentity.ts (trình trợ giúp danh tính dùng chung) và index.ts (registry).

Lưu ý: các nhà cung cấp không được liệt kê tại đây được phục vụ bởi default.ts bằng executor chung tương thích với OpenAI. Danh mục nhà cung cấp đầy đủ (355 nhà cung cấp) nằm trong src/shared/constants/providers.ts.

4.3 open-sse/translator/

Cơ chế dịch theo mô hình trung tâm và nan hoa (OpenAI là trung tâm).

• 9 translator yêu cầu (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 phản hồi (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 trình trợ giúp (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, cùng với các bài kiểm thử trình trợ giúp.
• Trình trợ giúp hình ảnh (translator/image/sizeMapper.ts).
• Cấp cao nhất: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Bộ chuyển đổi Responses API ↔ Chat Completions dựa trên TransformStream (được sử dụng bởi tuyến bắt tất cả responses/).

4.5 open-sse/services/

Các thành phần nổi bật (danh sách đầy đủ trong open-sse/services/):

Hạng mục	Tệp
Định tuyến Combo	combo.ts (19 chiến lược), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Công cụ 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
Khả năng phục hồi	accountFallback.ts (thời gian chờ + khóa tài khoản), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Hạn ngạch	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Bộ nhớ đệm	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Trí tuệ định tuyến	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Xử lý mô hình	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Nén	compression/ — toàn bộ phần kết nối công cụ nén
Token + phiên	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Cấp / manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / mạng	ipFilter.ts, webSearchFallback.ts
Lô	batchProcessor.ts
Mức sử dụng	usage.ts

4.6 open-sse/mcp-server/

• 110 công cụ duy nhất được kết nối trong server.ts (45 công cụ chuẩn trong schemas/tools.ts + các mô-đun bộ nhớ, kỹ năng, kỹ năng GitHub, pool, trò chơi hóa, plugin, Notion, Obsidian, kho dữ liệu cục bộ và nén — hợp được đếm bởi countUniqueMcpTools).
• 3 phương thức truyền tải: stdio, HTTP Streamable, SSE.
• 33 phạm vi được thực thi khi chạy — danh sách cơ sở nằm trong src/shared/constants/mcpScopes.ts, tập hợp đầy đủ là hợp của các phạm vi được khai báo bởi từng mô-đun công cụ.
• Bảng kiểm tra: mcp_tool_audit (được điền bởi audit.ts).
• Các tệp: 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, cùng với các bài kiểm thử trong __tests__/.
• Xem MCP-SERVER.md để biết danh mục công cụ đầy đủ.

4.7 open-sse/config/

Các sổ đăng ký nhà cung cấp (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), sổ đăng ký mô hình theo từng định dạng (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), các tiện ích định danh (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), các tiện ích thông tin xác thực (credentialLoader.ts, codexClient.ts) và các bộ điều hợp đám mây (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/

Các thành phần nguyên thủy về luồng và tiện ích hỗ trợ nhà cung cấp: 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/ — Trình bao bọc ứng dụng máy tính

electron/
├── main.js                  Tiến trình chính của Electron
├── preload.js               Cầu nối tải trước (đã bật contextIsolation)
├── types.d.ts
├── package.json             Cấu hình electron-builder, phiên bản 3.8.51
├── README.md
├── assets/                  Tài nguyên bản dựng (biểu tượng, quyền hạn, …)
├── node_modules/            node_modules chuyên dụng (better-sqlite3, electron-updater)
└── dist-electron/           Đầu ra bản dựng (không được commit)

Năm script npm tại thư mục gốc của workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Tính năng tự động cập nhật sử dụng electron-updater, trỏ đến nguồn bản phát hành trên GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Điểm vào CLI chính (Node ESM)
├── reset-password.mjs      Đặt lại mật khẩu quản lý từ CLI
├── mcp-server.mjs          Trình khởi chạy máy chủ MCP (stdio)
├── nodeRuntimeSupport.mjs  Trình kiểm tra phiên bản Node
└── cli/
    ├── program.mjs         Trình tạo chương trình Commander
    ├── runtime.mjs         Trình hỗ trợ withRuntime (ưu tiên máy chủ/dự phòng bằng cơ sở dữ liệu)
    ├── output.mjs          Trình định dạng đầu ra (json/jsonl/table/csv)
    ├── i18n.mjs            Trình hỗ trợ t() với các locale
    ├── api.mjs             Trình hỗ trợ gọi API bằng fetch
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Đăng ký lệnh
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (mỗi lệnh/nhóm một tệp)

Hai tệp thực thi được khai báo trong package.json → bin:

• omniroute → bin/omniroute.mjs
• omniroute-reset-password → bin/reset-password.mjs

---

7. tests/

Thư mục	Loại
tests/unit/	Kiểm thử đơn vị thông qua trình chạy kiểm thử gốc của Node (1821 tệp, cùng các thư mục con api/, auth/, authz/)
tests/integration/	Kiểm thử liên mô-đun và trạng thái cơ sở dữ liệu
tests/e2e/	Kiểm thử giao diện người dùng bằng Playwright
tests/e2e/protocol-clients.test.ts	Kiểm thử e2e giao thức MCP/A2A
tests/translator/	Kiểm thử dành riêng cho trình biên dịch
tests/security/	Kiểm thử hồi quy bảo mật
tests/load/	Kiểm thử tải / sức chịu tải
tests/golden-set/	Đầu ra tham chiếu cho kiểm thử hồi quy của trình biên dịch
tests/helpers/, tests/fixtures/, tests/manual/	Tệp hỗ trợ

Các lệnh thường dùng:

Lệnh	Nội dung chạy
npm run test:unit	Tất cả tests/unit/*.test.ts thông qua trình chạy kiểm thử của Node (mức đồng thời là 10)
npm run test:vitest	Bộ kiểm thử Vitest (MCP, autoCombo, bộ nhớ đệm)
npm run test:e2e	Bộ kiểm thử giao diện người dùng bằng Playwright
npm run test:protocols:e2e	Kiểm thử e2e giao thức MCP + A2A
npm run test:coverage	Ngưỡng độ bao phủ (≥60% dòng/câu lệnh/hàm/nhánh)
node --import tsx/esm --test tests/unit/<file>.test.ts	Chạy một tệp duy nhất

---

8. scripts/

Được tổ chức thành 6 thư mục con theo mục đích.

• 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. Quy trình xử lý yêu cầu (Tóm tắt)

Nguồn: diagrams/request-pipeline.mmd

Yêu cầu từ máy khách
  → /v1/chat/completions (route.ts)
     Kiểm tra preflight CORS
     Xác thực Zod (chatCompletionsSchema trong shared/validation/schemas.ts)
     Xác thực danh tính (extractApiKey + isValidApiKey HOẶC requireManagementAuth)
     Công cụ chính sách (src/server/authz/pipeline.ts)
     Biện pháp bảo vệ (ẩn thông tin PII, chống chèn prompt, cầu nối thị giác)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Kiểm tra bộ nhớ đệm (bộ nhớ đệm ngữ nghĩa + bộ nhớ đệm đọc)
     Giới hạn tốc độ (rateLimitManager, accountSemaphore)
     Định tuyến kết hợp (nếu mô hình được phân giải thành một tổ hợp)
       comboResolver → lặp theo từng đích → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       tìm nạp từ thượng nguồn → thử lại/chờ lùi qua accountFallback
     translateResponse() (open-sse/translator/response/*)
     Luồng SSE HOẶC phản hồi JSON
     Nếu là Responses API: TransformStream qua open-sse/transformer/responsesTransformer.ts
  → Kiểm tra tuân thủ (src/lib/compliance/)
  → Phản hồi tới máy khách

Trạng thái thời gian chạy về khả năng phục hồi (ba cơ chế)

Cơ chế	Phạm vi	Vị trí
Bộ ngắt mạch nhà cung cấp	Toàn bộ nhà cung cấp	src/shared/utils/circuitBreaker.ts, được lưu bền vững trong domain_circuit_breakers
Thời gian chờ kết nối	Một tài khoản/khóa	markAccountUnavailable() trong src/sse/services/auth.ts; được sử dụng bởi accountFallback.checkFallbackError()
Khóa mô hình	Nhà cung cấp + kết nối + mô hình	open-sse/services/accountFallback.ts, được lưu bền vững trong domain_lockout_state

Xem RESILIENCE_GUIDE.md và phần chuyên biệt trong CLAUDE.md.

---

10. Cách đóng góp

Thêm nhà cung cấp mới

1. Đăng ký trong src/shared/constants/providers.ts (được Zod xác thực khi tải).
2. Thêm trình thực thi trong open-sse/executors/ nếu cần logic tùy chỉnh (mở rộng BaseExecutor).
3. Thêm trình chuyển đổi trong open-sse/translator/ nếu nhà cung cấp không sử dụng định dạng OpenAI.
4. Nếu dựa trên OAuth, hãy thêm cấu hình trong src/lib/oauth/providers/ và src/lib/oauth/services/.
5. Đăng ký các mô hình trong open-sse/config/providerRegistry.ts (hoặc registry dành riêng cho định dạng trong open-sse/config/).
6. Viết các bài kiểm thử trong tests/unit/.

Thêm route API mới

1. Tạo src/app/api/your-route/route.ts.
2. Tuân theo mẫu: CORS → xác thực body bằng Zod → xác thực danh tính → chuyển tiếp cho handler.
3. Nếu có cấu trúc yêu cầu mới: thêm schema Zod vào src/shared/validation/schemas.ts.
4. Nếu chỉ dành cho quản trị: thêm đường dẫn vào src/shared/constants/publicApiRoutes.ts (danh sách từ chối đối với bề mặt API công khai).
5. Thêm các bài kiểm thử trong tests/unit/.
6. Cập nhật docs/reference/API_REFERENCE.md và docs/openapi.yaml.

Thêm mô-đun DB mới

1. Tạo src/lib/db/yourModule.ts và import getDbInstance() từ ./core.ts.
2. Export các hàm CRUD cho miền của bạn.
3. Nếu có bảng mới: thêm migration trong src/lib/db/migrations/, được đánh số tuần tự, có tính lũy đẳng và theo giao dịch.
4. Các trình import sử dụng import trực tiếp từ @/lib/db/yourModule (không dùng barrel — lớp tái export localDb.ts cũ đã bị loại bỏ).
5. Thêm các bài kiểm thử trong tests/unit/.

Thêm công cụ MCP mới

1. Thêm định nghĩa công cụ trong open-sse/mcp-server/tools/ (hoặc mở rộng open-sse/mcp-server/schemas/tools.ts).
2. Gán phạm vi phù hợp trong src/shared/constants/mcpScopes.ts.
3. Đăng ký công cụ trong open-sse/mcp-server/server.ts.
4. Thêm các bài kiểm thử trong open-sse/mcp-server/__tests__/.
5. Cập nhật MCP-SERVER.md.

Thêm kỹ năng A2A mới

Xem A2A-SERVER.md § Thêm kỹ năng mới. Các kỹ năng nằm trong src/lib/a2a/skills/ và được đăng ký thông qua trình quản lý tác vụ A2A.

---

11. Quy ước

• Phong cách mã: thụt lề 2 dấu cách, dấu ngoặc kép, độ rộng 100 ký tự, dấu chấm phẩy, dấu phẩy cuối kiểu es5 — được Prettier thực thi thông qua lint-staged.
• Import: bên ngoài → nội bộ (@/, @omniroute/open-sse) → tương đối.
• Đặt tên: tệp dùng camelCase hoặc kebab-case, component dùng PascalCase, hằng số dùng UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error ở mọi nơi; no-explicit-any = warn trong open-sse/ và tests/, lỗi ở những nơi khác.
• TypeScript: strict: false (trạng thái kế thừa). Ưu tiên kiểu tường minh hơn suy luận kiểu tại các ranh giới giữa mô-đun.
• Cơ sở dữ liệu: không bao giờ viết SQL thô trong route hoặc handler — luôn thông qua các mô-đun src/lib/db/. Không bao giờ import từ barrel — hãy sử dụng trực tiếp các mô-đun src/lib/db/* cụ thể.
• Định kiểu thực thể DB (#3512): một hàm ghi hoặc đọc cấu trúc hàng của bảng DB phải nhận/trả về một interface TS có tên phản ánh tương ứng 1:1 với các cột của bảng đó, không phải any hoặc kiểu ẩn danh nội tuyến tại vị trí gọi. Đặt interface cạnh hàm (ví dụ: export interface UsageEntry trong src/lib/usage/usageHistory.ts phía trên saveRequestUsage), giữ từng trường ở dạng tùy chọn/có thể null khi các trình ghi khác nhau điền dữ liệu vào hàng theo từng bước, và ưu tiên unknown hơn any đối với trường có cấu trúc thay đổi giữa các bên gọi (được ghi chú trên trường, ví dụ: UsageEntry.tokens chấp nhận cả dữ liệu sử dụng thô theo cấu trúc của nhà cung cấp lẫn cấu trúc đã chuẩn hóa). Khi số lượng any của một tệp giảm xuống bằng không theo cách này, hãy thêm tệp đó vào danh sách cho phép check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) để ngăn tái diễn. Đây là quy ước cho giai đoạn đầu — việc dọn dẹp rộng hơn nhằm loại bỏ "any ẩn danh" được thực hiện lặp dần trên phần còn lại của codebase.
• Lỗi: sử dụng try/catch với các kiểu lỗi cụ thể, ghi log kèm ngữ cảnh pino. Không bao giờ âm thầm bỏ qua lỗi trong các luồng SSE; sử dụng tín hiệu hủy để dọn dẹp.
• Bảo mật: không bao giờ sử dụng eval() / new Function() / eval ngầm định. Xác thực mọi đầu vào bằng Zod. Mã hóa thông tin xác thực khi lưu trữ (AES-256-GCM). Giữ danh sách từ chối src/shared/constants/upstreamHeaders.ts đồng bộ với lớp làm sạch/xác thực.
• Commit: Conventional Commits — feat(scope): subject. Các phạm vi được phép: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Nhánh: các tiền tố feat/, fix/, refactor/, docs/, test/, chore/. Không bao giờ commit trực tiếp vào main.
• Husky: pre-commit chạy lint-staged + check:docs-sync + check:any-budget:t11; pre-push chạy check:any-budget:t11 + check:tracked-artifacts (các bước kiểm tra nhanh; loại trừ test:unit).

---

12. Các quy tắc bắt buộc (từ CLAUDE.md)

1. Không bao giờ commit bí mật hoặc thông tin xác thực.
2. Không bao giờ nhập barrel — hãy sử dụng trực tiếp các mô-đun src/lib/db/* cụ thể.
3. Không bao giờ sử dụng eval() / new Function() / eval ngầm định.
4. Không bao giờ commit trực tiếp vào main.
5. Không bao giờ viết SQL thô trong các route — luôn phải thông qua các mô-đun src/lib/db/.
6. Không bao giờ âm thầm bỏ qua lỗi trong các luồng SSE.
7. Luôn xác thực dữ liệu đầu vào bằng các schema Zod.
8. Luôn bổ sung kiểm thử khi thay đổi mã nguồn production.
9. Độ bao phủ phải duy trì ở mức ≥ 60% (câu lệnh, dòng, hàm, nhánh).

---

13. Xem thêm

• ARCHITECTURE.md — kiến trúc cấp cao và trách nhiệm của các mô-đun.
• API_REFERENCE.md — tài liệu tham khảo API công khai + quản trị.
• FEATURES.md — ma trận tính năng và các điểm nổi bật theo phiên bản.
• RESILIENCE_GUIDE.md — phân tích chuyên sâu về circuit breaker, cooldown và lockout.
• AUTO-COMBO.md — cách tính điểm và các chiến lược của Auto Combo.
• MCP-SERVER.md — danh mục công cụ MCP đầy đủ + các phương thức truyền tải.
• A2A-SERVER.md — các kỹ năng và cơ chế khám phá của giao thức A2A.
• COMPRESSION_GUIDE.md — nén RTK + Caveman.
• CLI-TOOLS.md — các tích hợp CLI.
• ELECTRON_GUIDE.md (nếu có), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — các môi trường triển khai đích.
• TROUBLESHOOTING.md — các vấn đề vận hành thường gặp.
• CONTRIBUTING.md — quy trình làm việc dành cho người đóng góp.
• CLAUDE.md — các quy tắc của kho lưu trữ dành cho Claude Code (nguồn tham chiếu chính xác cho nhiều quy ước ở trên).
• AGENTS.md — tài liệu tham khảo kiến trúc chuyên sâu hơn dành cho các agent.