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

OmniRoute Codebase Documentation (ไทย)

🌐 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 · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

เวอร์ชัน: v3.8.51 อัปเดตล่าสุด: 2026-06-28 กลุ่มเป้าหมาย: วิศวกรที่มีส่วนร่วมกับ OmniRoute หรือสร้างการผสานรวมบน OmniRoute

สำหรับแผนภาพสถาปัตยกรรมระดับภาพรวมและเหตุผลเบื้องหลังแต่ละระบบย่อย โปรดอ่าน ARCHITECTURE.md สำหรับข้อมูลเชิงลึกของระบบย่อยแต่ละระบบ (Auto Combo, MCP server, A2A server, Skills, Memory, Cloud Agents, Resilience, Compression ฯลฯ) โปรดดูไฟล์เฉพาะของแต่ละระบบในไดเรกทอรี docs/ นี้

ไฟล์นี้อธิบายถึง สิ่งที่มีอยู่ในรีพอซิทอรี ณ ปัจจุบัน เพื่อให้วิศวกรใหม่ สามารถสำรวจโครงสร้างไดเรกทอรี ทำความเข้าใจการแบ่งชั้นขณะรันไทม์ และทราบว่าควรเพิ่มโค้ด ไว้ที่ใดโดยไม่ต้องสร้างโมดูลใหม่ขึ้นมา

---

1. สแต็กเทคโนโลยี

ประเด็น	ตัวเลือก
เว็บเฟรมเวิร์ก	Next.js 16 (App Router, เอาต์พุตแบบ standalone, ไม่มี global middleware)
ภาษา	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 (singleton, การบันทึกเจอร์นัลแบบ WAL)
เดสก์ท็อป	Electron 41 + electron-builder 26.10 (เวิร์กสเปซแยกต่างหากที่ electron/)
การทดสอบ	ตัวรันการทดสอบแบบเนทีฟของ Node (ยูนิต/อินทิเกรชัน), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
การบิลด์	Next.js standalone ผ่าน scripts/build/build-next-isolated.mjs
การตรวจสอบ/จัดรูปแบบ	การกำหนดค่า ESLint แบบ flat + Prettier (lint-staged ผ่าน Husky pre-commit)
ระบบโมดูล	ใช้ 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 main + preload)
├── bin/                  จุดเริ่มต้น CLI (omniroute, reset-password)
├── tests/                ยูนิต, อินทิเกรชัน, e2e, protocols-e2e, ตัวแปล, ความปลอดภัย, fixtures
├── scripts/              สคริปต์ช่วยเหลือด้านการบิลด์ การซิงค์ การตรวจสอบ การย้ายข้อมูล และรันไทม์
├── docs/                 เอกสารสาธารณะ (ไดเรกทอรีนี้)
├── public/               แอสเซ็ตแบบสแตติก, แมนิเฟสต์ PWA, service worker
├── config/               ตัวอย่างการกำหนดค่ารันไทม์
├── images/               แอสเซ็ตด้านการตลาด/ภาพหน้าจอ
├── _ideia/, _references/, _mono_repo/, _tasks/   พื้นที่ชั่วคราว / การวางแผนภายใน (ไม่รวมอยู่ในรุ่นที่เผยแพร่)
├── CLAUDE.md             กฎของรีพอซิทอรีสำหรับ Claude Code
├── AGENTS.md             เอกสารอ้างอิงสถาปัตยกรรมเชิงลึกสำหรับเอเจนต์
├── package.json          v3.8.51, รูทของเวิร์กสเปซ
└── tsconfig.json         นามแฝงพาธ + ตัวเลือกหลักของคอมไพเลอร์

---

3. src/ — แอปพลิเคชัน Next.js

src/
├── app/                  หน้า App Router + เส้นทาง API
├── lib/                  ไลบรารีหลัก (DB, การยืนยันตัวตน, OAuth, ทักษะ, หน่วยความจำ, …)
├── domain/               เลเยอร์โดเมนบริสุทธิ์ (นโยบาย, การสำรอง, ต้นทุน, การล็อกไม่ให้เข้าใช้, …)
├── server/               โมดูลสำหรับเซิร์ฟเวอร์เท่านั้น (การอนุญาต, cors, การยืนยันตัวตน)
├── shared/               ชนิดข้อมูล, ค่าคงที่, การตรวจสอบความถูกต้อง, สัญญา, ยูทิลิตี (ใช้งานข้ามขอบเขตได้อย่างปลอดภัย)
├── mitm/                 ตัวช่วยพร็อกซีแบบ Man-in-the-middle สำหรับการผสานรวมกับ CLI
├── models/               ข้อมูลเมตา / การกำหนดนามแฝงของโมเดลภายในเครื่อง
├── sse/                  ตัวจัดการ SSE แบบเดิมที่ยังคงอยู่ภายใต้ src/ (ไม่ใช่ open-sse/)
├── store/                ที่เก็บสถานะฝั่งไคลเอนต์
├── middleware/           ยูทิลิตีมิดเดิลแวร์ระดับเส้นทาง (ไม่ใช่มิดเดิลแวร์ส่วนกลางของ Next.js)
├── scripts/              สคริปต์ภายในซอร์สทรีที่โค้ดแอปสามารถนำเข้าได้
├── types/                ชนิดข้อมูล TS แบบแอมเบียนต์และแบบใช้ร่วมกัน
├── i18n/                 ชุดข้อมูลภาษาท้องถิ่น
├── instrumentation.ts    ฮุก instrumentation ของ 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/         API สาธารณะที่เข้ากันได้กับ OpenAI
├── 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 — npm install ผ่าน 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 เวอร์ชันใหม่กว่า
│   ├── rotate-key/route.ts POST — สร้าง API key ใหม่ + รีสตาร์ต
│   ├── status/route.ts     GET  — สถานะแบบเรียลไทม์ + สถานะ DB + ข้อมูลเมตาของเวอร์ชัน
│   └── auto-start/route.ts POST — สลับแฟล็ก auto_start
├── cliproxy/
│   ├── _lib.ts             ตัวช่วย getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install เวอร์ชันใหม่กว่า
│   ├── status/route.ts     GET  — สถานะแบบเรียลไทม์ + สถานะ DB + ข้อมูลเมตาของเวอร์ชัน
│   └── auto-start/route.ts POST — สลับแฟล็ก auto_start
└── [name]/
    └── logs/route.ts       GET  — ติดตามส่วนท้ายของบันทึกผ่าน SSE (ใช้ร่วมกันโดยทุกบริการ)

UI แดชบอร์ดที่เกี่ยวข้อง: src/app/(dashboard)/dashboard/providers/services/ — หน้าแบบสองแท็บ (CLIProxyAPI + 9Router) พร็อกซีย้อนกลับสำหรับ UI แบบฝังของ 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

ข้อมูลเชิงลึก: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — API สาธารณะที่เข้ากันได้กับ OpenAI

v1/
├── accounts/[id]/                       ค้นหาบัญชี
├── agents/tasks/[id]/, agents/tasks/    ปลายทางงานในรูปแบบ A2A
├── api/                                 ตัวช่วย API ภายในที่เปิดให้ใช้ภายใต้ v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (ปลายทางหลัก)
├── completions/                         การเติมข้อความแบบเดิม
├── embeddings/                          Embeddings
├── files/[id]/, files/                  Files API
├── _helpers/                            ตัวช่วย route ที่ใช้ร่วมกัน (ไม่มี URL สาธารณะ)
├── images/{edits, generations}/         การสร้าง + แก้ไขรูปภาพ
├── issues/                              ปลายทางตัวช่วยคัดแยกปัญหา
├── management/{proxies}/                route ขอบเขตการจัดการภายใน v1
├── messages/{count_tokens}/             ความเข้ากันได้กับ messages รูปแบบ Anthropic
├── models/                              รายการโมเดล (`route.ts`, `catalog.ts`)
├── moderations/                         การกลั่นกรอง
├── music/                               การสร้างเพลง
├── providers/[provider]/                การดำเนินการเฉพาะผู้ให้บริการ
├── quotas/{check}                       การตรวจสอบโควตา
├── registered-keys/                     การดูแลระบบคีย์ที่ลงทะเบียน
├── rerank/                              การจัดอันดับใหม่
├── responses/[...path]/                 OpenAI Responses API (ครอบคลุมทุกเส้นทาง)
├── search/                              การค้นหาเว็บ
├── videos/                              การสร้างวิดีโอ
├── ws/                                  บริดจ์ WebSocket
└── route.ts                             ตัวจัดการดัชนี

ไฟล์ route ทุกไฟล์ใช้รูปแบบเดียวกัน:

Route → การตรวจสอบ CORS ล่วงหน้า → การตรวจสอบ body ด้วย Zod → การยืนยันตัวตนที่เลือกใช้ได้
      → การบังคับใช้นโยบาย API key → การมอบหมายให้ handler (open-sse)

v1beta/ คือพื้นผิวความเข้ากันได้ในรูปแบบ Gemini (wrapper แบบบางที่แปลคำขอเข้าสู่ ไปป์ไลน์ open-sse/handlers/ เดียวกัน)

3.2 src/lib/ — ไลบรารีหลัก

ให้นำเข้า data, sync, OAuth, skill, memory และอื่น ๆ ผ่านโมดูลเหล่านี้เสมอ ตารางนี้จัดกลุ่มไดเรกทอรีจริงและไฟล์ระดับบนสุดที่สำคัญ

โมดูล	วัตถุประสงค์
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/	ตัวช่วย UI/การแสดงผลที่ใช้โดยการตอบกลับ API
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 (ดึงเอนด์พอยต์ REST จากข้อกำหนด OpenAPI), cliRegistryParser.ts (ดึงคำสั่งย่อย CLI จาก bin/cli-registry), 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
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 (Cloud Sync)
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/	โฟลว์ OAuth ของโปรแกรมแก้ไข Zed

ไฟล์ระดับบนสุดใน src/lib/:

• barrel แบบเก่า 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 แบบ Singleton (getDbInstance() ใน core.ts โดยใช้ WAL journaling) ห้ามเขียน SQL ดิบใน routes หรือ handlers — ให้ใช้งานผ่านโมดูลเหล่านี้

แหล่งที่มา: 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/ มีไฟล์ .sql ที่กำหนดเวอร์ชันไว้ 168 ไฟล์ (ทำซ้ำได้โดยไม่เปลี่ยนผลลัพธ์ และทำงานภายใต้ธุรกรรม) และจะถูก เรียกใช้โดย migrationRunner.ts ขณะบูต

ตารางที่สร้างขึ้นจาก migrations ทั้งหมด (รวม 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 โดย routes และ handlers จะนำเข้าไปใช้งาน

ไฟล์	วัตถุประสงค์
policyEngine.ts	ตัวแก้ไขนโยบายระดับบนสุด
fallbackPolicy.ts	แผนผังการตัดสินใจสำหรับ fallback
costRules.ts	กฎการคำนวณต้นทุน
lockoutPolicy.ts	การตัดสินใจล็อกโมเดล
tagRouter.ts	การกำหนดเส้นทางตามแท็ก
comboResolver.ts	การแก้ไข combo จากคำขอ → รายการเป้าหมาย
connectionModelRules.ts	ตัวกรองโมเดลสำหรับแต่ละการเชื่อมต่อ
modelAvailability.ts	การตรวจสอบความพร้อมใช้งานของโมเดล
degradation.ts	การเปลี่ยนสถานะเข้าสู่โหมดประสิทธิภาพลดลง
providerExpiration.ts	การตรวจหาบัญชี/คีย์ที่หมดอายุ
quotaCache.ts	การตัดสินใจเกี่ยวกับโควตาที่แคชไว้
responses.ts, omnirouteResponseMeta.ts	ตัวช่วยกำหนดโครงสร้างการตอบกลับ
configAudit.ts	การตรวจสอบการเปลี่ยนแปลงการกำหนดค่า
assessment/	การประเมินโมเดล (ตาม RFC โดยนำไปใช้แล้วบางส่วน)
types.ts	ชนิดข้อมูลโดเมนที่ใช้ร่วมกัน

3.4 src/server/ — สำหรับเซิร์ฟเวอร์เท่านั้น

ไม่สามารถนำเข้าได้จาก client components

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        จัดประเภท routes ว่าเป็นสาธารณะหรือสำหรับการจัดการ
│   ├── assertAuth.ts      ตัวช่วยสำหรับการยืนยันเงื่อนไข
│   ├── context.ts         บริบท authz สำหรับแต่ละคำขอ
│   ├── headers.ts
│   ├── pipeline.ts        ไปป์ไลน์ authz
│   ├── 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 (สคีมา Zod ประมาณ 80 รายการ), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — สัญญา API สาธารณะที่เผยแพร่ไปยัง npm
• 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/              ตัวดำเนินการ HTTP เฉพาะผู้ให้บริการ 108 รายการ
├── translator/             การแปลงรูปแบบ (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            ตัวแปลงสตรีม Responses API ↔ Chat Completions
├── services/               โมดูลบริการกว่า 80 รายการ (ชุดผสม การสำรอง โควตา อัตลักษณ์ …)
├── utils/                  ตัวช่วยสตรีมมิง ไคลเอนต์ TLS, AWS SigV4, การดึงข้อมูลผ่านพร็อกซี …
└── 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	การค้นหาเว็บ
sseParser.ts	ตัวแยกวิเคราะห์เหตุการณ์ SSE
usageExtractor.ts	ดึงจำนวนโทเค็นออกจากสตรีมต้นทาง
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 — ตัวแปลง Responses API ↔ Chat Completions ที่ใช้ TransformStream (ใช้โดยเส้นทางสำรองแบบครอบคลุมทั้งหมดของ 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, 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 (45 รายการมาตรฐานใน schemas/tools.ts + โมดูลหน่วยความจำ, ทักษะ, GitHub-skills, พูล, เกมมิฟิเคชัน, ปลั๊กอิน, Notion, Obsidian, local-corpus และการบีบอัด — นับจำนวนยูเนียนด้วย 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

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               บริดจ์สำหรับพรีโหลด (เปิดใช้งาน contextIsolation)
├── types.d.ts
├── package.json             การกำหนดค่า electron-builder, เวอร์ชัน 3.8.51
├── 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

---

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 (เซิร์ฟเวอร์ก่อน/ฐานข้อมูลสำรอง)
    ├── output.mjs          ตัวจัดรูปแบบเอาต์พุต (json/jsonl/table/csv)
    ├── i18n.mjs            ตัวช่วย t() พร้อมโลเคล
    ├── api.mjs             ตัวช่วยดึงข้อมูลจาก API
    ├── 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/	การทดสอบข้ามโมดูลและสถานะฐานข้อมูล
tests/e2e/	การทดสอบ UI ด้วย Playwright
tests/e2e/protocol-clients.test.ts	การทดสอบ 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, cache)
npm run test:e2e	ชุดการทดสอบ UI ของ Playwright
npm run test:protocols:e2e	การทดสอบ 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. ไปป์ไลน์คำขอ (สรุป)

แหล่งที่มา: diagrams/request-pipeline.mmd

คำขอจากไคลเอนต์
  → /v1/chat/completions (route.ts)
     ตรวจสอบ CORS preflight
     การตรวจสอบความถูกต้องด้วย Zod (chatCompletionsSchema ใน shared/validation/schemas.ts)
     การยืนยันตัวตน (extractApiKey + isValidApiKey หรือ requireManagementAuth)
     กลไกนโยบาย (src/server/authz/pipeline.ts)
     มาตรการป้องกัน (ตัวปกปิด PII, การแทรกคำสั่งในพรอมต์, บริดจ์วิชัน)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     ตรวจสอบแคช (แคชเชิงความหมาย + แคชการอ่าน)
     จำกัดอัตรา (rateLimitManager, accountSemaphore)
     การกำหนดเส้นทางแบบคอมโบ (หากโมเดลถูกแปลงเป็นคอมโบ)
       comboResolver → วนซ้ำสำหรับแต่ละเป้าหมาย → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       ดึงข้อมูลจากต้นทาง → ลองใหม่/หน่วงเวลาเพิ่มขึ้นผ่าน accountFallback
     translateResponse() (open-sse/translator/response/*)
     สตรีม SSE หรือการตอบกลับแบบ JSON
     หากเป็น Responses API: TransformStream ผ่าน open-sse/transformer/responsesTransformer.ts
  → การตรวจสอบการปฏิบัติตามข้อกำหนด (src/lib/compliance/)
  → การตอบกลับไปยังไคลเอนต์

สถานะรันไทม์ด้านความยืดหยุ่น (สามกลไก)

กลไก	ขอบเขต	ตำแหน่ง
เซอร์กิตเบรกเกอร์ของผู้ให้บริการ	ผู้ให้บริการทั้งหมด	src/shared/utils/circuitBreaker.ts, จัดเก็บถาวรใน domain_circuit_breakers
ช่วงพักการเชื่อมต่อ	หนึ่งบัญชี/คีย์	markAccountUnavailable() ใน src/sse/services/auth.ts; ใช้งานโดย accountFallback.checkFallbackError()
การล็อกโมเดล	ผู้ให้บริการ + การเชื่อมต่อ + โมเดล	open-sse/services/accountFallback.ts, จัดเก็บถาวรใน domain_lockout_state

ดู RESILIENCE_GUIDE.md และส่วนเฉพาะใน CLAUDE.md

---

10. วิธีร่วมพัฒนา

เพิ่มผู้ให้บริการรายใหม่

1. ลงทะเบียนใน src/shared/constants/providers.ts (ตรวจสอบความถูกต้องด้วย Zod ขณะโหลด)
2. เพิ่ม executor ใน open-sse/executors/ หากต้องใช้ตรรกะแบบกำหนดเอง (สืบทอดจาก BaseExecutor)
3. เพิ่ม translator ใน open-sse/translator/ หากผู้ให้บริการไม่รองรับรูปแบบ OpenAI
4. หากใช้ OAuth ให้เพิ่มการกำหนดค่าภายใต้ src/lib/oauth/providers/ และ src/lib/oauth/services/
5. ลงทะเบียนโมเดลใน open-sse/config/providerRegistry.ts (หรือ registry เฉพาะรูปแบบ ภายใต้ open-sse/config/)
6. เขียนการทดสอบภายใต้ tests/unit/

เพิ่มเส้นทาง API ใหม่

1. สร้าง src/app/api/your-route/route.ts
2. ทำตามรูปแบบ: CORS → การตรวจสอบ body ด้วย Zod → การยืนยันตัวตน → การมอบหมายให้ handler
3. หากมีโครงสร้างคำขอใหม่ ให้เพิ่ม Zod schema ใน src/shared/validation/schemas.ts
4. หากมีไว้สำหรับการจัดการเท่านั้น ให้เพิ่ม path ลงใน src/shared/constants/publicApiRoutes.ts (denylist สำหรับพื้นผิว public API)
5. เพิ่มการทดสอบภายใต้ tests/unit/
6. อัปเดต docs/reference/API_REFERENCE.md และ docs/openapi.yaml

เพิ่มโมดูล DB ใหม่

1. สร้าง src/lib/db/yourModule.ts และนำเข้า getDbInstance() จาก ./core.ts
2. ส่งออกฟังก์ชัน CRUD สำหรับโดเมนของคุณ
3. หากมีตารางใหม่ ให้เพิ่ม migration ภายใต้ src/lib/db/migrations/ โดยกำหนดหมายเลข ตามลำดับ ทำให้รันซ้ำได้โดยให้ผลลัพธ์เดิม และทำงานภายใน transaction
4. ผู้นำเข้าให้ใช้การนำเข้าโดยตรงจาก @/lib/db/yourModule (ไม่ใช้ barrel — เลเยอร์ re-export localDb.ts แบบเดิมถูกนำออกแล้ว)
5. เพิ่มการทดสอบภายใต้ tests/unit/

เพิ่มเครื่องมือ MCP ใหม่

1. เพิ่มคำจำกัดความของเครื่องมือภายใต้ open-sse/mcp-server/tools/ (หรือขยาย open-sse/mcp-server/schemas/tools.ts)
2. กำหนด scope ที่เหมาะสมใน src/shared/constants/mcpScopes.ts
3. ลงทะเบียนเครื่องมือใน open-sse/mcp-server/server.ts
4. เพิ่มการทดสอบภายใต้ open-sse/mcp-server/__tests__/
5. อัปเดต MCP-SERVER.md

เพิ่มทักษะ A2A ใหม่

ดู A2A-SERVER.md § การเพิ่มทักษะใหม่ ทักษะอยู่ใน src/lib/a2a/skills/ และลงทะเบียนผ่านตัวจัดการงาน A2A

---

11. ข้อตกลงร่วมกัน

• รูปแบบโค้ด: เยื้อง 2 ช่อง, ใช้เครื่องหมายอัญประกาศคู่, ความกว้าง 100 อักขระ, ใช้ semicolon, และ trailing comma แบบ es5 — บังคับใช้โดย Prettier ผ่าน lint-staged
• การนำเข้า: ภายนอก → ภายใน (@/, @omniroute/open-sse) → แบบสัมพัทธ์
• การตั้งชื่อ: ไฟล์ใช้ camelCase หรือ kebab-case, component ใช้ PascalCase, ค่าคงที่ใช้ UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = error ทุกแห่ง; no-explicit-any = warn ใน open-sse/ และ tests/ และเป็น error ในที่อื่น
• TypeScript: strict: false (แนวทางที่สืบทอดจากระบบเดิม) ควรใช้ type ที่ระบุอย่างชัดเจนแทน inference สำหรับขอบเขตระหว่างโมดูล
• ฐานข้อมูล: ห้ามเขียน SQL ดิบใน route หรือ handler — ให้ดำเนินการผ่านโมดูล src/lib/db/ เสมอ ห้ามนำเข้าแบบ barrel — ให้ใช้โมดูล src/lib/db/* ที่เฉพาะเจาะจงโดยตรง
• การกำหนด type ของเอนทิตี DB (#3512): ฟังก์ชันที่เขียนหรืออ่านรูปร่าง row ของตาราง DB ควรรับ/คืนค่าเป็น TS interface ที่มีชื่อและสะท้อนคอลัมน์ของตารางนั้น แบบ 1:1 ไม่ใช่ any หรือ type แบบ anonymous ที่ประกาศ inline ณ จุดเรียกใช้ ให้วาง interface ไว้ข้างฟังก์ชัน (เช่น export interface UsageEntry ใน src/lib/usage/usageHistory.ts เหนือ saveRequestUsage) กำหนดแต่ละ field ให้เป็น optional/nullable เมื่อ writer แต่ละตัวเติมข้อมูลใน row แบบทยอยเพิ่ม และควรใช้ unknown แทน any สำหรับ field ที่มีรูปร่างแตกต่างกันไปตาม caller (ให้บันทึกคำอธิบายไว้ที่ field เช่น UsageEntry.tokens รองรับทั้งข้อมูล usage ดิบตามรูปแบบของผู้ให้บริการและรูปแบบที่ทำ normalization แล้ว) เมื่อจำนวน any ในไฟล์ลดลงเหลือศูนย์ด้วยวิธีนี้ ให้เพิ่มไฟล์นั้นลงใน allowlist ของ check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) เพื่อป้องกันไม่ให้ถดถอย นี่เป็นข้อตกลงสำหรับส่วนแรก — การปรับปรุง "ไม่ใช้ any แบบ anonymous" ในวงกว้างจะดำเนินการแบบวนซ้ำทั่วทั้ง codebase ที่เหลือ
• ข้อผิดพลาด: ใช้ try/catch ร่วมกับ type ข้อผิดพลาดที่เฉพาะเจาะจง และบันทึก log พร้อมบริบทด้วย pino ห้าม กลืนข้อผิดพลาดในสตรีม SSE โดยไม่แจ้งใด ๆ และให้ใช้ abort signal สำหรับการล้างทรัพยากร
• ความปลอดภัย: ห้ามใช้ eval() / new Function() / implied eval ตรวจสอบ input ทั้งหมดด้วย Zod เข้ารหัสข้อมูลประจำตัวขณะจัดเก็บ (AES-256-GCM) รักษา denylist ใน src/shared/constants/upstreamHeaders.ts ให้สอดคล้องกับ เลเยอร์การ sanitize/validation
• Commit: ใช้ Conventional Commits — feat(scope): subject โดย scope ที่อนุญาต ได้แก่: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills
• Branch: ใช้ prefix feat/, fix/, refactor/, docs/, test/, chore/ ห้าม commit โดยตรงไปยัง 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. ห้ามนำเข้าแบบ barrel — ให้ใช้โมดูล src/lib/db/* ที่เฉพาะเจาะจงโดยตรง
3. ห้ามใช้ eval() / new Function() / eval โดยนัย
4. ห้ามคอมมิตไปยัง main โดยตรง
5. ห้ามเขียน SQL ดิบใน route — ต้องดำเนินการผ่านโมดูล src/lib/db/ เสมอ
6. ห้ามกลืนข้อผิดพลาดในสตรีม SSE โดยไม่แจ้งให้ทราบ
7. ต้องตรวจสอบความถูกต้องของอินพุตด้วยสคีมา Zod เสมอ
8. ต้องเพิ่มการทดสอบเสมอเมื่อแก้ไขโค้ดที่ใช้งานจริง
9. ความครอบคลุมต้องคงไว้ที่ ≥ 60% (คำสั่ง, บรรทัด, ฟังก์ชัน, แขนง)

---

13. ดูเพิ่มเติม

• ARCHITECTURE.md — สถาปัตยกรรมระดับสูงและความรับผิดชอบ ของโมดูล
• API_REFERENCE.md — เอกสารอ้างอิง API สาธารณะและ API สำหรับการจัดการ
• FEATURES.md — ตารางคุณสมบัติและจุดเด่นของแต่ละเวอร์ชัน
• RESILIENCE_GUIDE.md — เจาะลึก circuit breaker, cooldown และ lockout
• AUTO-COMBO.md — การให้คะแนนและกลยุทธ์ของ Auto Combo
• MCP-SERVER.md — แค็ตตาล็อกเครื่องมือ MCP และรูปแบบการรับส่งข้อมูลทั้งหมด
• A2A-SERVER.md — ความสามารถและการค้นหาบริการตามโปรโตคอล A2A
• COMPRESSION_GUIDE.md — การบีบอัดด้วย RTK และ Caveman
• CLI-TOOLS.md — การผสานรวม CLI
• ELECTRON_GUIDE.md (หากมี), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — เป้าหมายการนำไปใช้งาน
• TROUBLESHOOTING.md — ปัญหาด้านการปฏิบัติงานที่พบบ่อย
• CONTRIBUTING.md — ขั้นตอนการทำงานสำหรับผู้มีส่วนร่วม
• CLAUDE.md — กฎของรีโพสำหรับ Claude Code (แหล่งข้อมูลหลัก สำหรับแบบแผนหลายข้อข้างต้น)
• AGENTS.md — เอกสารอ้างอิงสถาปัตยกรรมเชิงลึกที่เอเจนต์ใช้