OmniRoute/docs/i18n/th/CLAUDE.md

CLAUDE.md (ไทย)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

ไฟล์นี้ให้แนวทางสำหรับ Claude Code (claude.ai/code) เมื่อทำงานกับโค้ดในที่เก็บนี้

เริ่มต้นอย่างรวดเร็ว

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           # ตรวจจับการพึ่งพาแบบวงกลม

การรันการทดสอบ

# ไฟล์ทดสอบเดียว (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/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 ของผู้ให้บริการทำงาน:

(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

ฟิลด์ที่สำคัญในการเชื่อมต่อผู้ให้บริการ:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

ในระหว่างการเลือกบัญชี การเชื่อมต่อจะถูกข้ามในขณะที่:

new Date(rateLimitedUntil).getTime() > Date.now();

การเย็นลงยังเป็นแบบขี้เกียจ: เมื่อ rateLimitedUntil อยู่ในอดีต การเชื่อมต่อจะมีสิทธิ์อีกครั้ง เมื่อใช้งานสำเร็จ clearAccountError() จะล้าง testStatus, rateLimitedUntil, ฟิลด์ข้อผิดพลาด และ backoffLevel

พฤติกรรมการเย็นลงของการเชื่อมต่อเริ่มต้น:

• การเย็นลงพื้นฐานของ OAuth: 5s
• การเย็นลงพื้นฐานของ API-key: 3s
• API-key 429 ควรให้ความสำคัญกับคำแนะนำการลองใหม่จาก upstream (Retry-After, headers รีเซ็ต หรือข้อความรีเซ็ตที่สามารถวิเคราะห์ได้) เมื่อมีให้
• ความล้มเหลวที่กู้คืนได้ซ้ำใช้การเพิ่มขึ้นแบบเอ็กซ์โพเนนเชียล:

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): ชอบ 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

# อย่าคอมมิตโดยตรงไปยัง 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 <email>; workflow upstream-port (/port-upstream-features, /port-upstream-issues) ขึ้นอยู่กับสิ่งนี้