# CLAUDE.md (ไทย) 🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md) --- ไฟล์นี้ให้แนวทางสำหรับ Claude Code (claude.ai/code) เมื่อทำงานกับโค้ดในที่เก็บนี้ ## เริ่มต้นอย่างรวดเร็ว ```bash npm install # ติดตั้ง deps (สร้าง .env จาก .env.example โดยอัตโนมัติ) npm run dev # เซิร์ฟเวอร์พัฒนาอยู่ที่ http://localhost:20128 npm run build # สร้างโปรดักชัน (Next.js 16 standalone) npm run lint # ESLint (คาดหวัง 0 ข้อผิดพลาด; คำเตือนเป็นสิ่งที่มีอยู่แล้ว) npm run typecheck:core # ตรวจสอบ TypeScript (ควรสะอาด) npm run typecheck:noimplicit:core # ตรวจสอบอย่างเข้มงวด (ไม่มี implicit any) npm run test:coverage # หน่วยทดสอบ + เกณฑ์การครอบคลุม (75/75/75/70 — คำสั่ง/บรรทัด/ฟังก์ชัน/สาขา) npm run check # lint + ทดสอบรวมกัน npm run check:cycles # ตรวจจับการพึ่งพาแบบวงกลม ``` ### การรันการทดสอบ ```bash # ไฟล์ทดสอบเดียว (Node.js native test runner — ทดสอบส่วนใหญ่) node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest (MCP server, autoCombo, cache) npm run test:vitest # ทุกชุด npm run test:all ``` สำหรับตารางการทดสอบทั้งหมด ดูที่ `CONTRIBUTING.md` → "การรันการทดสอบ" สำหรับสถาปัตยกรรมเชิงลึก ดูที่ `AGENTS.md`. --- ## โครงการโดยรวม **OmniRoute** — โปรเซสเซอร์/เราเตอร์ AI ที่รวมเป็นหนึ่ง จุดสิ้นสุดเดียว, ผู้ให้บริการ LLM มากกว่า 160 ราย, การสำรองข้อมูลอัตโนมัติ | เลเยอร์ | ตำแหน่ง | วัตถุประสงค์ | | ------------- | ----------------------- | ------------------------------------------------------------------------------------------ | | API Routes | `src/app/api/v1/` | Next.js App Router — จุดเข้า | | Handlers | `open-sse/handlers/` | การประมวลผลคำขอ (แชท, การฝัง, ฯลฯ) | | Executors | `open-sse/executors/` | การส่ง HTTP เฉพาะผู้ให้บริการ | | Translators | `open-sse/translator/` | การแปลงรูปแบบ (OpenAI↔Claude↔Gemini) | | Transformer | `open-sse/transformer/` | API การตอบกลับ ↔ การเติมแชท | | Services | `open-sse/services/` | การจัดเส้นทางแบบรวม, ขีดจำกัดอัตรา, การแคช, ฯลฯ | | Database | `src/lib/db/` | โมดูลโดเมน SQLite (ไฟล์ 45+ ไฟล์, การโยกย้าย 55) | | Domain/Policy | `src/domain/` | เอนจินนโยบาย, กฎค่าใช้จ่าย, ลอจิกการสำรองข้อมูล | | MCP Server | `open-sse/mcp-server/` | เครื่องมือ 37 รายการ (30 พื้นฐาน + 3 หน่วยความจำ + 4 ทักษะ), การขนส่ง 3 รายการ, ~13 ขอบเขต | | A2A Server | `src/lib/a2a/` | โปรโตคอลตัวแทน JSON-RPC 2.0 | | Skills | `src/lib/skills/` | โครงสร้างทักษะที่ขยายได้ | | Memory | `src/lib/memory/` | หน่วยความจำการสนทนาที่คงอยู่ | Monorepo: `src/` (แอป Next.js 16), `open-sse/` (พื้นที่ทำงานเครื่องยนต์สตรีมมิ่ง), `electron/` (แอปเดสก์ท็อป), `tests/`, `bin/` (จุดเข้า CLI). ## Request Pipeline ``` Client → /v1/chat/completions (Next.js route) → CORS → Zod validation → auth? → policy check → prompt injection guard → handleChatCore() [open-sse/handlers/chatCore.ts] → cache check → rate limit → combo routing? → resolveComboTargets() → handleSingleModel() per target → translateRequest() → getExecutor() → executor.execute() → fetch() upstream → retry w/ backoff → response translation → SSE stream or JSON → If Responses API: responsesTransformer.ts TransformStream ``` API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. ไม่มี middleware ของ Next.js ทั่วไป — การดักจับจะเฉพาะเจาะจงต่อเส้นทาง **Combo routing** (`open-sse/services/combo.ts`): 14 กลยุทธ์ (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized, context-relay). เป้าหมายแต่ละตัวเรียก `handleSingleModel()` ซึ่งห่อหุ้ม `handleChatCore()` ด้วยการจัดการข้อผิดพลาดเฉพาะเป้าหมายและการตรวจสอบ circuit breaker ดู `docs/routing/AUTO-COMBO.md` สำหรับการให้คะแนน Auto-Combo 9 ปัจจัยและ `docs/architecture/RESILIENCE_GUIDE.md` สำหรับ 3 ชั้นของความทนทาน --- ## Resilience Runtime State OmniRoute มีกลไกการล้มเหลวชั่วคราวที่เกี่ยวข้องกันสามอย่าง แต่แตกต่างกัน รักษาขอบเขตของพวกเขาแยกกันเมื่อทำการดีบักพฤติกรรมการจัดเส้นทาง ดู [3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg) (แหล่งที่มา: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)) สำหรับแผนที่แบบคร่าวๆ ### Provider Circuit Breaker **Scope**: ผู้ให้บริการทั้งหมด เช่น `glm`, `openai`, `anthropic`. **Purpose**: หยุดการส่งข้อมูลไปยังผู้ให้บริการที่ล้มเหลวซ้ำๆ ที่ระดับ upstream/service เพื่อไม่ให้ผู้ให้บริการที่ไม่แข็งแรงทำให้คำขอทุกคำช้าลง **Implementation**: - คลาสหลัก: `src/shared/utils/circuitBreaker.ts` - การเชื่อมต่อ/การดำเนินการของ Chat: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts` - API สถานะการทำงาน: `src/app/api/monitoring/health/route.ts` - ตัวห่อร่วม: `open-sse/services/accountFallback.ts` - ตารางสถานะที่เก็บถาวร: `domain_circuit_breakers` **States**: - `CLOSED`: อนุญาตให้มีการจราจรปกติ - `OPEN`: ผู้ให้บริการถูกบล็อกชั่วคราว; ผู้โทรจะได้รับการตอบสนองว่า provider-circuit-open หรือการจัดเส้นทางแบบ combo จะข้ามไปยังเป้าหมายอื่น - `HALF_OPEN`: เวลาหมดเวลารีเซ็ตได้ผ่านไปแล้ว; อนุญาตให้มีการสอบถามคำขอ หากสำเร็จจะปิด circuit breaker หากล้มเหลวจะเปิดอีกครั้ง **Defaults** (`open-sse/config/constants.ts`): - ผู้ให้บริการ OAuth: เกณฑ์ `3`, เวลาหมดเวลารีเซ็ต `60s` - ผู้ให้บริการ API-key: เกณฑ์ `5`, เวลาหมดเวลารีเซ็ต `30s` - ผู้ให้บริการท้องถิ่น: เกณฑ์ `2`, เวลาหมดเวลารีเซ็ต `15s` สถานะการล้มเหลวของผู้ให้บริการเท่านั้นที่ควรทำให้ circuit breaker ของผู้ให้บริการทำงาน: ```ts (408, 500, 502, 503, 504); ``` อย่าทำให้ circuit breaker ของผู้ให้บริการทั้งหมดทำงานสำหรับข้อผิดพลาดบัญชี/คีย์/โมเดลปกติ เช่น ส่วนใหญ่ `401`, `403`, หรือ `429` เหล่านั้นมักจะเป็นการเชื่อมต่อที่เย็นลงหรือการล็อคโมเดล ข้อผิดพลาด API-key ทั่วไป `403` ควรสามารถกู้คืนได้ เว้นแต่จะถูกจัดประเภทเป็นข้อผิดพลาดบัญชี/ผู้ให้บริการที่สิ้นสุด circuit breaker ใช้การกู้คืนแบบขี้เกียจ ไม่ใช่ตัวจับเวลาเบื้องหลัง เมื่อ `OPEN` หมดอายุ การอ่านเช่น `getStatus()`, `canExecute()`, และ `getRetryAfterMs()` จะรีเฟรชสถานะเป็น `HALF_OPEN` ดังนั้นแดชบอร์ดและผู้สร้างผู้สมัคร combo จะไม่ขExclude ผู้ให้บริการที่หมดอายุตลอดไป ### Connection Cooldown **Scope**: การเชื่อมต่อ/บัญชี/คีย์ของผู้ให้บริการหนึ่ง **Purpose**: ข้ามคีย์/บัญชีที่ไม่ดีชั่วคราวในขณะที่อนุญาตให้การเชื่อมต่ออื่นๆ สำหรับผู้ให้บริการเดียวกันดำเนินการให้บริการคำขอ **Implementation**: - เส้นทางการเขียน/อัปเดต: `src/sse/services/auth.ts::markAccountUnavailable()` - การเลือก/กรองบัญชี: `src/sse/services/auth.ts::getProviderCredentials...` - การคำนวณการเย็นลง: `open-sse/services/accountFallback.ts::checkFallbackError()` - การตั้งค่า: `src/lib/resilience/settings.ts` ฟิลด์ที่สำคัญในการเชื่อมต่อผู้ให้บริการ: ```ts rateLimitedUntil; testStatus: "unavailable"; lastError; lastErrorType; errorCode; backoffLevel; ``` ในระหว่างการเลือกบัญชี การเชื่อมต่อจะถูกข้ามในขณะที่: ```ts new Date(rateLimitedUntil).getTime() > Date.now(); ``` การเย็นลงยังเป็นแบบขี้เกียจ: เมื่อ `rateLimitedUntil` อยู่ในอดีต การเชื่อมต่อจะมีสิทธิ์อีกครั้ง เมื่อใช้งานสำเร็จ `clearAccountError()` จะล้าง `testStatus`, `rateLimitedUntil`, ฟิลด์ข้อผิดพลาด และ `backoffLevel` พฤติกรรมการเย็นลงของการเชื่อมต่อเริ่มต้น: - การเย็นลงพื้นฐานของ OAuth: `5s` - การเย็นลงพื้นฐานของ API-key: `3s` - API-key `429` ควรให้ความสำคัญกับคำแนะนำการลองใหม่จาก upstream (`Retry-After`, headers รีเซ็ต หรือข้อความรีเซ็ตที่สามารถวิเคราะห์ได้) เมื่อมีให้ - ความล้มเหลวที่กู้คืนได้ซ้ำใช้การเพิ่มขึ้นแบบเอ็กซ์โพเนนเชียล: ```ts baseCooldownMs * 2 ** failureIndex; ``` การป้องกันการเกิดภัยพิบัติแบบกลุ่มจะป้องกันไม่ให้ความล้มเหลวพร้อมกันในเชื่อมต่อเดียวกันขยายการเย็นลงซ้ำหรือเพิ่ม `backoffLevel` สองเท่า สถานะสุดท้ายไม่ใช่การเย็นลง `banned`, `expired`, และ `credits_exhausted` มีจุดมุ่งหมายเพื่อให้ไม่สามารถใช้งานได้จนกว่าข้อมูลประจำตัว/การตั้งค่าจะเปลี่ยนแปลงหรือผู้ดูแลระบบรีเซ็ตพวกเขา อย่าเขียนทับสถานะสุดท้ายด้วยสถานะการเย็นลงชั่วคราว ### Model Lockout **Scope**: ผู้ให้บริการ + การเชื่อมต่อ + โมเดล **Purpose**: หลีกเลี่ยงการปิดการใช้งานการเชื่อมต่อทั้งหมดเมื่อมีเพียงโมเดลเดียวที่ไม่สามารถใช้งานได้หรือมีการจำกัดโควตาสำหรับการเชื่อมต่อนั้น ตัวอย่าง: - ผู้ให้บริการโควตาต่อโมเดลที่ส่งคืน `429` - ผู้ให้บริการท้องถิ่นที่ส่งคืน `404` สำหรับโมเดลที่ขาดหายไป - ความล้มเหลวในการอนุญาตโหมด/โมเดลเฉพาะของผู้ให้บริการ เช่น โหมด Grok ที่เลือก การล็อคโมเดลอยู่ใน `open-sse/services/accountFallback.ts` และอนุญาตให้การเชื่อมต่อเดียวกันดำเนินการให้บริการโมเดลอื่นๆ ต่อไป ### Debugging Guidance - หากคีย์ทั้งหมดสำหรับผู้ให้บริการถูกข้าม ให้ตรวจสอบทั้งสถานะ circuit breaker ของผู้ให้บริการและ `rateLimitedUntil`/`testStatus` ของการเชื่อมต่อแต่ละตัว - หากผู้ให้บริการดูเหมือนจะถูกยกเว้นถาวรหลังจากหน้าต่างรีเซ็ต ให้ตรวจสอบว่าโค้ดกำลังอ่าน `state` ดิบแทนที่จะใช้ `getStatus()`/`canExecute()` - หากคีย์ของผู้ให้บริการหนึ่งล้มเหลวแต่คีย์อื่นควรทำงาน ให้ให้ความสำคัญกับการเย็นลงของการเชื่อมต่อมากกว่าการทำงานของ circuit breaker ของผู้ให้บริการ - หากโมเดลเพียงหนึ่งล้มเหลว ให้ให้ความสำคัญกับการล็อคโมเดลมากกว่าการเย็นลงของการเชื่อมต่อ - หากสถานะควรกู้คืนเอง มันควรมี timestamp/เวลาหมดอายุในอนาคตและเส้นทางการอ่านที่รีเฟรชสถานะที่หมดอายุ สถานะถาวรต้องการการเปลี่ยนแปลงข้อมูลประจำตัวหรือการกำหนดค่าด้วยตนเอง ## ข้อตกลงหลัก ### รูปแบบโค้ด - **2 ช่องว่าง**, เครื่องหมายเซมิโคลอน, เครื่องหมายคำพูดคู่, ความกว้าง 100 ตัวอักษร, คอมม่าใน ES5 (บังคับโดย lint-staged ผ่าน Prettier) - **การนำเข้า**: ภายนอก → ภายใน (`@/`, `@omniroute/open-sse`) → เชิงสัมพันธ์ - **การตั้งชื่อ**: ไฟล์=camelCase/kebab, คอมโพเนนต์=PascalCase, ค่าคงที่=UPPER_SNAKE - **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = ข้อผิดพลาดทุกที่; `no-explicit-any` = เตือนใน `open-sse/` และ `tests/` - **TypeScript**: `strict: false`, เป้าหมาย ES2022, โมดูล esnext, การแก้ไข bundler. ชอบประเภทที่ชัดเจน ### ฐานข้อมูล - **เสมอ** ผ่านโมดูลโดเมน `src/lib/db/` — **ไม่เคย** เขียน SQL ดิบในเส้นทางหรือผู้จัดการ - **ไม่เคย** เพิ่มตรรกะใน `src/lib/localDb.ts` (ชั้นการส่งออกใหม่เท่านั้น) - **ไม่เคย** นำเข้าจาก `localDb.ts` — นำเข้าโมดูล `db/` ที่เฉพาะเจาะจงแทน - DB singleton: `getDbInstance()` จาก `src/lib/db/core.ts` (WAL journaling) - การโยกย้าย: `src/lib/db/migrations/` — ไฟล์ SQL ที่มีการเวอร์ชัน, idempotent, รันในธุรกรรม ### การจัดการข้อผิดพลาด - try/catch ด้วยประเภทข้อผิดพลาดที่เฉพาะเจาะจง, บันทึกด้วยบริบท pino - ไม่เคยกลืนข้อผิดพลาดใน SSE streams — ใช้สัญญาณยกเลิกสำหรับการทำความสะอาด - คืนค่ารหัสสถานะ HTTP ที่เหมาะสม (4xx/5xx) ### ความปลอดภัย - **ไม่เคย** ใช้ `eval()`, `new Function()`, หรือ implied eval - ตรวจสอบข้อมูลนำเข้าทั้งหมดด้วย Zod schemas - เข้ารหัสข้อมูลรับรองเมื่ออยู่ในที่เก็บ (AES-256-GCM) - รายการปฏิเสธส่วนหัวของ upstream: `src/shared/constants/upstreamHeaders.ts` — รักษาความสะอาด, Zod schemas, และการทดสอบหน่วยให้สอดคล้องเมื่อแก้ไข - **ข้อมูลรับรองสาธารณะของ upstream** (client_id/secret แบบ Gemini/Antigravity/Windsurf + คีย์ Firebase Web ที่ดึงมาจาก CLI สาธารณะ): **ต้อง** ถูกฝังผ่าน `resolvePublicCred()` จาก `open-sse/utils/publicCreds.ts` — **ไม่เคย** เป็นตัวอักษรสตริง ดู `docs/security/PUBLIC_CREDS.md` สำหรับรูปแบบที่จำเป็น - **การตอบสนองข้อผิดพลาด** (HTTP / SSE / executor / MCP handler): **ต้อง** ผ่าน `buildErrorBody()` หรือ `sanitizeErrorMessage()` จาก `open-sse/utils/error.ts` — **ไม่เคย** ใส่ `err.stack` หรือ `err.message` ดิบในร่างการตอบสนอง ดู `docs/security/ERROR_SANITIZATION.md`. - **คำสั่งเชลล์ที่สร้างจากตัวแปร**: เมื่อเรียกใช้ `exec()`/`spawn()` ด้วยสคริปต์ที่ต้องการค่าระหว่างการทำงาน, ส่งผ่านทางตัวเลือก `env` (เชลล์-escaped โดยอัตโนมัติ) — **ไม่เคย** สอดแทรกเส้นทางที่ไม่เชื่อถือได้/ภายนอกลงในร่างสคริปต์ อ้างอิง: `src/mitm/cert/install.ts::updateNssDatabases`. - **ไลบรารีที่ปลอดภัยตามค่าเริ่มต้น** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): ชอบ Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink มากกว่าการใช้งานที่กำหนดเองเมื่อเพิ่มพื้นผิวที่มีความปลอดภัยสูงใหม่ --- ## สถานการณ์การแก้ไขทั่วไป ### การเพิ่มผู้ให้บริการใหม่ 1. ลงทะเบียนใน `src/shared/constants/providers.ts` (ตรวจสอบด้วย Zod ที่โหลด) 2. เพิ่ม executor ใน `open-sse/executors/` หากต้องการตรรกะที่กำหนดเอง (ขยาย `BaseExecutor`) 3. เพิ่ม translator ใน `open-sse/translator/` หากไม่ใช่รูปแบบ OpenAI 4. เพิ่มการกำหนดค่า OAuth ใน `src/lib/oauth/constants/oauth.ts` หากใช้ OAuth — หาก CLI ของ upstream ส่ง client_id/secret สาธารณะ, ฝังผ่าน `resolvePublicCred()` (ดู `docs/security/PUBLIC_CREDS.md`), **ไม่เคย** เป็นตัวอักษร 5. ลงทะเบียนโมเดลใน `open-sse/config/providerRegistry.ts` 6. เขียนการทดสอบใน `tests/unit/` (รวมการยืนยันรูปแบบ publicCreds หากคุณเพิ่มค่าเริ่มต้นใหม่ที่ฝัง) ### การเพิ่มเส้นทาง API ใหม่ 1. สร้างไดเรกทอรีภายใต้ `src/app/api/v1/your-route/` 2. สร้าง `route.ts` ด้วยผู้จัดการ `GET`/`POST` 3. ปฏิบัติตามรูปแบบ: CORS → การตรวจสอบร่าง Zod → การตรวจสอบสิทธิ์ที่เลือกได้ → การมอบหมายผู้จัดการ 4. ผู้จัดการไปใน `open-sse/handlers/` (นำเข้าจากที่นั่น, ไม่ใช่ในบรรทัด) 5. การตอบสนองข้อผิดพลาดใช้ `buildErrorBody()` / `errorResponse()` จาก `open-sse/utils/error.ts` (ทำความสะอาดโดยอัตโนมัติ — ไม่เคยใส่ `err.stack` หรือ `err.message` ดิบในร่าง) ดู `docs/security/ERROR_SANITIZATION.md`. 6. เพิ่มการทดสอบ — รวมอย่างน้อยหนึ่งการยืนยันว่าการตอบสนองข้อผิดพลาดไม่รั่วไหลของ stack traces (`!body.error.message.includes("at /")`) ### การเพิ่มโมดูล DB ใหม่ 1. สร้าง `src/lib/db/yourModule.ts` — นำเข้า `getDbInstance` จาก `./core.ts` 2. ส่งออกฟังก์ชัน CRUD สำหรับตารางโดเมนของคุณ 3. เพิ่มการโยกย้ายใน `src/lib/db/migrations/` หากต้องการตารางใหม่ 4. ส่งออกใหม่จาก `src/lib/localDb.ts` (เพิ่มในรายการการส่งออกใหม่เท่านั้น) 5. เขียนการทดสอบ ### การเพิ่มเครื่องมือ MCP ใหม่ 1. เพิ่มการกำหนดเครื่องมือใน `open-sse/mcp-server/tools/` พร้อมกับสคีมาข้อมูลนำเข้าของ Zod + ผู้จัดการแบบอะซิงโครนัส 2. ลงทะเบียนในชุดเครื่องมือ (เชื่อมต่อโดย `createMcpServer()`) 3. กำหนดให้กับขอบเขตที่เหมาะสม 4. เขียนการทดสอบ (การเรียกใช้เครื่องมือบันทึกลงในตาราง `mcp_audit`) ### การเพิ่มทักษะ A2A ใหม่ 1. สร้างทักษะใน `src/lib/a2a/skills/` (มีอยู่แล้ว 5 ทักษะ: smart-routing, quota-management, provider-discovery, cost-analysis, health-report) 2. ทักษะได้รับบริบทของงาน (ข้อความ, เมตาดาต้า) → คืนค่าผลลัพธ์ที่มีโครงสร้าง 3. ลงทะเบียนใน `A2A_SKILL_HANDLERS` ใน `src/lib/a2a/taskExecution.ts` 4. เปิดเผยใน `src/app/.well-known/agent.json/route.ts` (Agent Card) 5. เขียนการทดสอบใน `tests/unit/` 6. เอกสารในตารางทักษะใน `docs/frameworks/A2A-SERVER.md` ### การเพิ่มตัวแทนคลาวด์ใหม่ 1. สร้างคลาสตัวแทนใน `src/lib/cloudAgent/agents/` ขยาย `CloudAgentBase` (มีอยู่แล้ว 3 ตัว: codex-cloud, devin, jules) 2. นำไปใช้ `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` 3. ลงทะเบียนใน `src/lib/cloudAgent/registry.ts` 4. เพิ่มการจัดการ OAuth/ข้อมูลรับรองหากจำเป็น (`src/lib/oauth/providers/`) 5. การทดสอบ + เอกสารใน `docs/frameworks/CLOUD_AGENT.md` ### การเพิ่ม Guardrail / Eval / Skill / Webhook event ใหม่ - Guardrail: `src/lib/guardrails/` → เอกสาร: `docs/security/GUARDRAILS.md` - Eval suite: `src/lib/evals/` → เอกสาร: `docs/frameworks/EVALS.md` - Skill (sandbox): `src/lib/skills/` → เอกสาร: `docs/frameworks/SKILLS.md` - Webhook event: `src/lib/webhookDispatcher.ts` → เอกสาร: `docs/frameworks/WEBHOOKS.md` ## เอกสารอ้างอิง สำหรับการเปลี่ยนแปลงที่ไม่ธรรมดา ให้อ่านเอกสารเชิงลึกที่ตรงกันก่อน: | พื้นที่ | เอกสาร | | ----------------------------------------------- | ----------------------------------------------------------------- | | การนำทางใน Repo | `docs/architecture/REPOSITORY_MAP.md` | | สถาปัตยกรรม | `docs/architecture/ARCHITECTURE.md` | | เอกสารอ้างอิงด้านวิศวกรรม | `docs/architecture/CODEBASE_DOCUMENTATION.md` | | Auto-Combo (การให้คะแนน 9 ปัจจัย, 14 กลยุทธ์) | `docs/routing/AUTO-COMBO.md` | | ความยืดหยุ่น (กลไก 3 ประการ) | `docs/architecture/RESILIENCE_GUIDE.md` | | การเล่นซ้ำการให้เหตุผล | `docs/routing/REASONING_REPLAY.md` | | กรอบทักษะ | `docs/frameworks/SKILLS.md` | | ระบบหน่วยความจำ (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` | | ตัวแทนคลาวด์ | `docs/frameworks/CLOUD_AGENT.md` | | รั้วป้องกัน (PII / การฉีด / วิสัยทัศน์) | `docs/security/GUARDRAILS.md` | | ข้อมูลประจำตัวสาธารณะจาก upstream (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` | | การทำความสะอาดข้อความแสดงข้อผิดพลาด | `docs/security/ERROR_SANITIZATION.md` | | การประเมินผล | `docs/frameworks/EVALS.md` | | การปฏิบัติตาม / การตรวจสอบ | `docs/security/COMPLIANCE.md` | | Webhooks | `docs/frameworks/WEBHOOKS.md` | | ท่อการอนุญาต | `docs/architecture/AUTHZ_GUIDE.md` | | การซ่อนตัว (TLS / ลายนิ้วมือ) | `docs/security/STEALTH_GUIDE.md` | | โปรโตคอลตัวแทน (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | | เซิร์ฟเวอร์ MCP | `docs/frameworks/MCP-SERVER.md` | | เซิร์ฟเวอร์ A2A | `docs/frameworks/A2A-SERVER.md` | | เอกสารอ้างอิง API + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` | | แคตตาล็อกผู้ให้บริการ (สร้างโดยอัตโนมัติ) | `docs/reference/PROVIDER_REFERENCE.md` | | กระบวนการปล่อย | `docs/ops/RELEASE_CHECKLIST.md` | ## การทดสอบ | สิ่งที่ | คำสั่ง | | ----------------------- | ------------------------------------------------------------------- | | การทดสอบหน่วย | `npm run test:unit` | | ไฟล์เดียว | `node --import tsx/esm --test tests/unit/file.test.ts` | | Vitest (MCP, autoCombo) | `npm run test:vitest` | | E2E (Playwright) | `npm run test:e2e` | | โปรโตคอล E2E (MCP+A2A) | `npm run test:protocols:e2e` | | ระบบนิเวศ | `npm run test:ecosystem` | | เกณฑ์การครอบคลุม | `npm run test:coverage` (75/75/75/70 — คำสั่ง/บรรทัด/ฟังก์ชัน/สาขา) | | รายงานการครอบคลุม | `npm run coverage:report` | **กฎ PR**: หากคุณเปลี่ยนแปลงโค้ดการผลิตใน `src/`, `open-sse/`, `electron/`, หรือ `bin/`, คุณต้องรวมหรืออัปเดตการทดสอบใน PR เดียวกัน **ความชอบชั้นการทดสอบ**: หน่วยก่อน → การรวม (หลายโมดูลหรือสถานะ DB) → e2e (UI/กระบวนการทำงานเท่านั้น) เข้ารหัสการทำซ้ำของข้อบกพร่องเป็นการทดสอบอัตโนมัติก่อนหรือพร้อมกับการแก้ไข **นโยบายการครอบคลุม Copilot**: เมื่อ PR เปลี่ยนแปลงโค้ดการผลิตและการครอบคลุมต่ำกว่า 75% (คำสั่ง/บรรทัด/ฟังก์ชัน) หรือ 70% (สาขา) อย่าเพียงแค่รายงาน — เพิ่มหรืออัปเดตการทดสอบ รันเกณฑ์การครอบคลุมอีกครั้ง จากนั้นขอการยืนยัน รวมคำสั่งที่รัน ไฟล์ทดสอบที่เปลี่ยนแปลง และผลลัพธ์การครอบคลุมสุดท้ายในรายงาน PR --- ## การทำงานกับ Git ```bash # อย่าคอมมิตโดยตรงไปยัง main git checkout -b feat/your-feature git commit -m "feat: อธิบายการเปลี่ยนแปลงของคุณ" git push -u origin feat/your-feature ``` **คำนำหน้าสาขา**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/` **รูปแบบการคอมมิต** (Conventional Commits): `feat(db): เพิ่ม circuit breaker` — ขอบเขต: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills` **Husky hooks**: - **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` - **pre-push**: `npm run test:unit` --- ## สภาพแวดล้อม - **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules - **TypeScript**: 5.9+, target ES2022, module esnext, resolution bundler - **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` - **พอร์ตเริ่มต้น**: 20128 (API + แดชบอร์ดบนพอร์ตเดียวกัน) - **ไดเรกทอรีข้อมูล**: `DATA_DIR` env var, ค่าเริ่มต้นเป็น `~/.omniroute/` - **ตัวแปรสภาพแวดล้อมหลัก**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL` - การตั้งค่า: `cp .env.example .env` จากนั้นสร้าง `JWT_SECRET` (`openssl rand -base64 48`) และ `API_KEY_SECRET` (`openssl rand -hex 32`) --- ## กฎที่เข้มงวด 1. อย่าคอมมิตความลับหรือข้อมูลรับรอง 2. อย่าเพิ่มตรรกะใน `localDb.ts` 3. อย่าใช้ `eval()` / `new Function()` / eval ที่แสดงออก 4. อย่าคอมมิตโดยตรงไปยัง `main` 5. อย่าเขียน SQL ดิบในเส้นทาง — ใช้โมดูล `src/lib/db/` 6. อย่ากินข้อผิดพลาดใน SSE streams โดยไม่แสดงออก 7. ต้องตรวจสอบข้อมูลนำเข้าด้วย Zod schemas เสมอ 8. ต้องรวมการทดสอบเมื่อเปลี่ยนแปลงโค้ดการผลิต 9. การครอบคลุมต้องอยู่ที่ ≥75% (คำสั่ง, บรรทัด, ฟังก์ชัน) / ≥70% (สาขา). ข้อมูลที่วัดได้ในปัจจุบัน: ~82%. 10. อย่าข้าม Husky hooks (`--no-verify`, `--no-gpg-sign`) โดยไม่มีการอนุมัติจากผู้ปฏิบัติงานอย่างชัดเจน 11. อย่าแทรก client_id/secret ของ OAuth สาธารณะหรือ Firebase Web keys เป็น string literals — ต้องผ่าน `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`) เสมอ ดู `docs/security/PUBLIC_CREDS.md` 12. อย่าคืนค่า `err.stack` / `err.message` ดิบใน HTTP / SSE / การตอบสนองของ executor — ต้องส่งผ่าน `buildErrorBody()` หรือ `sanitizeErrorMessage()` (`open-sse/utils/error.ts`) เสมอ ดู `docs/security/ERROR_SANITIZATION.md` 13. อย่าผสมเส้นทางภายนอกหรือค่ารันไทม์ในสคริปต์เชลล์ที่ส่งไปยัง `exec()`/`spawn()` — ส่งผ่านตัวเลือก `env` แทน อ้างอิง: `src/mitm/cert/install.ts::updateNssDatabases` 14. อย่าปฏิเสธการแจ้งเตือน CodeQL / Secret-Scanning โดยไม่ (a) ตรวจสอบเอกสารรูปแบบข้างต้นก่อนเพื่อดูว่าผู้ช่วยใช้ได้หรือไม่ และ (b) บันทึกเหตุผลทางเทคนิคในความคิดเห็นการปฏิเสธ ตัวอย่าง: `js/stack-trace-exposure` ที่เกิดขึ้นใน callsites ที่ส่งผ่าน `sanitizeErrorMessage()` แล้วเป็นข้อจำกัดที่ทราบของ CodeQL (custom sanitizers ไม่ได้รับการรับรู้) — ปฏิเสธว่าเป็น `false positive` โดยอ้างอิง `docs/security/ERROR_SANITIZATION.md` 15. อย่าเปิดเผยเส้นทางที่สร้างกระบวนการลูก (`/api/mcp/`, `/api/cli-tools/runtime/`) โดยไม่มีการจำแนกประเภท `isLocalOnlyPath()` ใน `src/server/authz/routeGuard.ts`. การบังคับใช้ loopback เกิดขึ้นโดยไม่มีเงื่อนไขก่อนการตรวจสอบการรับรองใด ๆ — JWT ที่รั่วไหลผ่านอุโมงค์ไม่สามารถกระตุ้นการสร้างกระบวนการได้ ดู `docs/security/ROUTE_GUARD_TIERS.md` 16. อย่ารวมส่วนต่อท้าย `Co-Authored-By` ที่ให้เครดิตกับ AI assistant, LLM หรือบัญชี automation (เช่น ชื่อที่มี "Claude", "GPT", "Copilot", "Bot"; อีเมลที่ `anthropic.com` / `openai.com` / ที่อยู่ `noreply.github.com` ที่บอทเป็นเจ้าของ) ไว้ในข้อความ commit เด็ดขาด ส่วนต่อท้ายเช่นนี้จะส่ง attribution ของ commit ไปยังบัญชีบอทบน GitHub และซ่อนผู้เขียนจริง (`diegosouzapw`) ในประวัติ PR ผู้ร่วมมือที่เป็นมนุษย์ — รวมถึงผู้เขียน PR upstream และผู้รายงาน issue ที่ถูก port มายัง OmniRoute — สามารถและควรได้รับเครดิตด้วยส่วนต่อท้ายมาตรฐาน `Co-authored-by: Name `; workflow upstream-port (`/port-upstream-features`, `/port-upstream-issues`) ขึ้นอยู่กับสิ่งนี้