Files

T

wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution

2026-07-13 13:39:12 +08:00

43 KiB

Raw Permalink Blame History

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 มากกว่าการใช้งานที่กำหนดเองเมื่อเพิ่มพื้นผิวที่มีความปลอดภัยสูงใหม่

สถานการณ์การแก้ไขทั่วไป

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

ลงทะเบียนใน src/shared/constants/providers.ts (ตรวจสอบด้วย Zod ที่โหลด)
เพิ่ม executor ใน open-sse/executors/ หากต้องการตรรกะที่กำหนดเอง (ขยาย BaseExecutor)
เพิ่ม translator ใน open-sse/translator/ หากไม่ใช่รูปแบบ OpenAI
เพิ่มการกำหนดค่า OAuth ใน src/lib/oauth/constants/oauth.ts หากใช้ OAuth — หาก CLI ของ upstream ส่ง client_id/secret สาธารณะ, ฝังผ่าน resolvePublicCred() (ดู docs/security/PUBLIC_CREDS.md), ไม่เคย เป็นตัวอักษร
ลงทะเบียนโมเดลใน open-sse/config/providerRegistry.ts
เขียนการทดสอบใน tests/unit/ (รวมการยืนยันรูปแบบ publicCreds หากคุณเพิ่มค่าเริ่มต้นใหม่ที่ฝัง)

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

สร้างไดเรกทอรีภายใต้ src/app/api/v1/your-route/
สร้าง route.ts ด้วยผู้จัดการ GET/POST
ปฏิบัติตามรูปแบบ: CORS → การตรวจสอบร่าง Zod → การตรวจสอบสิทธิ์ที่เลือกได้ → การมอบหมายผู้จัดการ
ผู้จัดการไปใน open-sse/handlers/ (นำเข้าจากที่นั่น, ไม่ใช่ในบรรทัด)
การตอบสนองข้อผิดพลาดใช้ buildErrorBody() / errorResponse() จาก open-sse/utils/error.ts (ทำความสะอาดโดยอัตโนมัติ — ไม่เคยใส่ err.stack หรือ err.message ดิบในร่าง) ดู docs/security/ERROR_SANITIZATION.md.
เพิ่มการทดสอบ — รวมอย่างน้อยหนึ่งการยืนยันว่าการตอบสนองข้อผิดพลาดไม่รั่วไหลของ stack traces (!body.error.message.includes("at /"))

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

สร้าง src/lib/db/yourModule.ts — นำเข้า getDbInstance จาก ./core.ts
ส่งออกฟังก์ชัน CRUD สำหรับตารางโดเมนของคุณ
เพิ่มการโยกย้ายใน src/lib/db/migrations/ หากต้องการตารางใหม่
ส่งออกใหม่จาก src/lib/localDb.ts (เพิ่มในรายการการส่งออกใหม่เท่านั้น)
เขียนการทดสอบ

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

เพิ่มการกำหนดเครื่องมือใน open-sse/mcp-server/tools/ พร้อมกับสคีมาข้อมูลนำเข้าของ Zod + ผู้จัดการแบบอะซิงโครนัส
ลงทะเบียนในชุดเครื่องมือ (เชื่อมต่อโดย createMcpServer())
กำหนดให้กับขอบเขตที่เหมาะสม
เขียนการทดสอบ (การเรียกใช้เครื่องมือบันทึกลงในตาราง mcp_audit)

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

สร้างทักษะใน src/lib/a2a/skills/ (มีอยู่แล้ว 5 ทักษะ: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
ทักษะได้รับบริบทของงาน (ข้อความ, เมตาดาต้า) → คืนค่าผลลัพธ์ที่มีโครงสร้าง
ลงทะเบียนใน A2A_SKILL_HANDLERS ใน src/lib/a2a/taskExecution.ts
เปิดเผยใน src/app/.well-known/agent.json/route.ts (Agent Card)
เขียนการทดสอบใน tests/unit/
เอกสารในตารางทักษะใน docs/frameworks/A2A-SERVER.md

การเพิ่มตัวแทนคลาวด์ใหม่

สร้างคลาสตัวแทนใน src/lib/cloudAgent/agents/ ขยาย CloudAgentBase (มีอยู่แล้ว 3 ตัว: codex-cloud, devin, jules)
นำไปใช้ createTask, getStatus, approvePlan, sendMessage, listSources
ลงทะเบียนใน src/lib/cloudAgent/registry.ts
เพิ่มการจัดการ OAuth/ข้อมูลรับรองหากจำเป็น (src/lib/oauth/providers/)
การทดสอบ + เอกสารใน 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)

กฎที่เข้มงวด

อย่าคอมมิตความลับหรือข้อมูลรับรอง
อย่าเพิ่มตรรกะใน localDb.ts
อย่าใช้ eval() / new Function() / eval ที่แสดงออก
อย่าคอมมิตโดยตรงไปยัง main
อย่าเขียน SQL ดิบในเส้นทาง — ใช้โมดูล src/lib/db/
อย่ากินข้อผิดพลาดใน SSE streams โดยไม่แสดงออก
ต้องตรวจสอบข้อมูลนำเข้าด้วย Zod schemas เสมอ
ต้องรวมการทดสอบเมื่อเปลี่ยนแปลงโค้ดการผลิต
การครอบคลุมต้องอยู่ที่ ≥75% (คำสั่ง, บรรทัด, ฟังก์ชัน) / ≥70% (สาขา). ข้อมูลที่วัดได้ในปัจจุบัน: ~82%.
อย่าข้าม Husky hooks (--no-verify, --no-gpg-sign) โดยไม่มีการอนุมัติจากผู้ปฏิบัติงานอย่างชัดเจน
อย่าแทรก client_id/secret ของ OAuth สาธารณะหรือ Firebase Web keys เป็น string literals — ต้องผ่าน resolvePublicCred() (open-sse/utils/publicCreds.ts) เสมอ ดู docs/security/PUBLIC_CREDS.md
อย่าคืนค่า err.stack / err.message ดิบใน HTTP / SSE / การตอบสนองของ executor — ต้องส่งผ่าน buildErrorBody() หรือ sanitizeErrorMessage() (open-sse/utils/error.ts) เสมอ ดู docs/security/ERROR_SANITIZATION.md
อย่าผสมเส้นทางภายนอกหรือค่ารันไทม์ในสคริปต์เชลล์ที่ส่งไปยัง exec()/spawn() — ส่งผ่านตัวเลือก env แทน อ้างอิง: src/mitm/cert/install.ts::updateNssDatabases
อย่าปฏิเสธการแจ้งเตือน CodeQL / Secret-Scanning โดยไม่ (a) ตรวจสอบเอกสารรูปแบบข้างต้นก่อนเพื่อดูว่าผู้ช่วยใช้ได้หรือไม่ และ (b) บันทึกเหตุผลทางเทคนิคในความคิดเห็นการปฏิเสธ ตัวอย่าง: js/stack-trace-exposure ที่เกิดขึ้นใน callsites ที่ส่งผ่าน sanitizeErrorMessage() แล้วเป็นข้อจำกัดที่ทราบของ CodeQL (custom sanitizers ไม่ได้รับการรับรู้) — ปฏิเสธว่าเป็น false positive โดยอ้างอิง docs/security/ERROR_SANITIZATION.md
อย่าเปิดเผยเส้นทางที่สร้างกระบวนการลูก (/api/mcp/, /api/cli-tools/runtime/) โดยไม่มีการจำแนกประเภท isLocalOnlyPath() ใน src/server/authz/routeGuard.ts. การบังคับใช้ loopback เกิดขึ้นโดยไม่มีเงื่อนไขก่อนการตรวจสอบการรับรองใด ๆ — JWT ที่รั่วไหลผ่านอุโมงค์ไม่สามารถกระตุ้นการสร้างกระบวนการได้ ดู docs/security/ROUTE_GUARD_TIERS.md
อย่ารวมส่วนต่อท้าย 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) ขึ้นอยู่กับสิ่งนี้

43 KiB Raw Permalink Blame History