# 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) · 🇰🇷 [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) · 🇹🇭 [th](../th/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 # 䟝存関係をむンストヌル.env.example から .env を自動生成 npm run dev # http://localhost:20128 での開発サヌバヌ npm run build # プロダクションビルドNext.js 16 スタンドアロン npm run lint # ESLint゚ラヌは0件予想; 譊告は既存 npm run typecheck:core # TypeScript チェッククリヌンであるべき npm run typecheck:noimplicit:core # 厳密チェック暗黙の any はなし npm run test:coverage # ナニットテスト + カバレッゞゲヌト75/75/75/70 — ステヌトメント/行/関数/ブランチ npm run check # lint + テストの組み合わせ npm run check:cycles # 埪環䟝存関係を怜出 ``` ### テストの実行 ```bash # 単䞀のテストファむルNode.js ネむティブテストランナヌ — ほずんどのテスト node --import tsx/esm --test tests/unit/your-file.test.ts # Vitest (MCP サヌバヌ、自動コンボ、キャッシュ) npm run test:vitest # すべおのスむヌト npm run test:all ``` 完党なテストマトリックスに぀いおは、`CONTRIBUTING.md` → "テストの実行" を参照しおください。深いアヌキテクチャに぀いおは、`AGENTS.md` を参照しおください。 --- ## プロゞェクトの抂芁 **OmniRoute** — 統䞀されたAIプロキシ/ルヌタヌ。1぀の゚ンドポむント、160以䞊のLLMプロバむダヌ、自動フォヌルバック。 | レむダヌ | 堎所 | 目的 | | ------------------ | ----------------------- | ------------------------------------------------------------------------------------- | | APIルヌト | `src/app/api/v1/` | Next.js アプリルヌタヌ — ゚ントリヌポむント | | ハンドラヌ | `open-sse/handlers/` | リク゚スト凊理チャット、埋め蟌みなど | | ゚グれキュヌタヌ | `open-sse/executors/` | プロバむダヌ固有のHTTPディスパッチ | | トランスレヌタヌ | `open-sse/translator/` | フォヌマット倉換OpenAI↔Claude↔Gemini | | トランスフォヌマヌ | `open-sse/transformer/` | レスポンスAPI ↔ チャット完了 | | サヌビス | `open-sse/services/` | コンボルヌティング、レヌト制限、キャッシングなど | | デヌタベヌス | `src/lib/db/` | SQLite ドメむンモゞュヌル45以䞊のファむル、55のマむグレヌション | | ドメむン/ポリシヌ | `src/domain/` | ポリシヌ゚ンゞン、コストルヌル、フォヌルバックロゞック | | MCPサヌバヌ | `open-sse/mcp-server/` | 37のツヌル30のベヌス + 3のメモリ + 4のスキル、3぀のトランスポヌト、玄13のスコヌプ | | A2Aサヌバヌ | `src/lib/a2a/` | JSON-RPC 2.0 ゚ヌゞェントプロトコル | | スキル | `src/lib/skills/` | 拡匵可胜なスキルフレヌムワヌク | | メモリ | `src/lib/memory/` | 氞続的な䌚話メモリ | モノレポ: `src/` (Next.js 16 アプリ)、`open-sse/` (ストリヌミング゚ンゞンワヌクスペヌス)、`electron/` (デスクトップアプリ)、`tests/`、`bin/` (CLI ゚ントリヌポむント)。 --- ## リク゚ストパむプラむン ``` Client → /v1/chat/completions (Next.js ルヌト) → CORS → Zod バリデヌション → 認蚌? → ポリシヌチェック → プロンプトむンゞェクションガヌド → handleChatCore() [open-sse/handlers/chatCore.ts] → キャッシュチェック → レヌト制限 → コンボルヌティング? → resolveComboTargets() → handleSingleModel() 各タヌゲットごず → translateRequest() → getExecutor() → executor.execute() → fetch() アップストリヌム → リトラむ w/ バックオフ → レスポンストランスレヌション → SSE ストリヌムたたは JSON → If Responses API: responsesTransformer.ts TransformStream ``` API ルヌトは䞀貫したパタヌンに埓いたす: `ルヌト → CORS プレフラむト → Zod ボディバリデヌション → オプションの認蚌 (extractApiKey/isValidApiKey) → API キヌポリシヌの匷制 → ハンドラヌデリゲヌション (open-sse)`。グロヌバルな Next.js ミドルりェアはありたせん — むンタヌセプションはルヌト固有です。 **コンボルヌティング** (`open-sse/services/combo.ts`): 14 の戊略 (優先床、重み付け、フィルファヌスト、ラりンドロビン、P2C、ランダム、最少䜿甚、コスト最適化、リセット認識、厳密ランダム、自動、lkgp、コンテキスト最適化、コンテキストリレヌ)。各タヌゲットは `handleSingleModel()` を呌び出し、タヌゲットごずの゚ラヌハンドリングずサヌキットブレヌカヌチェックで `handleChatCore()` をラップしたす。9芁玠の Auto-Combo スコアリングに぀いおは `docs/routing/AUTO-COMBO.md` を、3぀のレゞリ゚ンスレむダヌに぀いおは `docs/architecture/RESILIENCE_GUIDE.md` を参照しおください。 --- ## レゞリ゚ンスランタむム状態 OmniRoute には、関連性があるが異なる䞀時的な倱敗メカニズムが3぀ありたす。ルヌティングの動䜜をデバッグする際には、それぞれのスコヌプを分けおおくこずが重芁です。抂芁マップに぀いおは、[3局レゞリ゚ンスダむアグラム](./docs/diagrams/exported/resilience-3layers.svg)を参照しおください (出兞: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))。 ### プロバむダヌサヌキットブレヌカヌ **スコヌプ**: 党䜓のプロバむダヌ、䟋: `glm`, `openai`, `anthropic`。 **目的**: 䞊流/サヌビスレベルで繰り返し倱敗しおいるプロバむダヌぞのトラフィックを停止し、1぀の䞍健康なプロバむダヌがすべおのリク゚ストを遅くしないようにしたす。 **実装**: - コアクラス: `src/shared/utils/circuitBreaker.ts` - チャットゲヌト/実行配線: `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` **状態**: - `CLOSED`: 通垞のトラフィックが蚱可されたす。 - `OPEN`: プロバむダヌが䞀時的にブロックされおいたす; 呌び出し元はプロバむダヌサヌキットオヌプンのレスポンスを受け取るか、コンボルヌティングが別のタヌゲットにスキップしたす。 - `HALF_OPEN`: リセットタむムアりトが経過したした; プロヌブリク゚ストを蚱可したす。成功するずブレヌカヌが閉じ、倱敗するず再びオヌプンになりたす。 **デフォルト** (`open-sse/config/constants.ts`): - OAuth プロバむダヌ: 閟倀 `3`, リセットタむムアりト `60s`。 - API キヌプロバむダヌ: 閟倀 `5`, リセットタむムアりト `30s`。 - ロヌカルプロバむダヌ: 閟倀 `2`, リセットタむムアりト `15s`。 プロバむダヌのレベルでの倱敗ステヌタスのみがプロバむダヌブレヌカヌをトリップさせるべきです: ```ts (408, 500, 502, 503, 504); ``` 通垞のアカりント/キヌ/モデル゚ラヌのようなほずんどの `401`, `403`, たたは `429` ケヌスで党䜓のプロバむダヌブレヌカヌをトリップさせないでください。これらは通垞、接続クヌルダりンたたはモデルロックアりトに属したす。䞀般的な API キヌプロバむダヌの `403` は、タヌミナルプロバむダヌ/アカりント゚ラヌずしお分類されない限り、回埩可胜であるべきです。 ブレヌカヌはレむゞヌリカバリヌを䜿甚し、バックグラりンドタむマヌではありたせん。`OPEN` が期限切れになるず、`getStatus()`, `canExecute()`, および `getRetryAfterMs()` などの読み取りが状態を `HALF_OPEN` に曎新し、ダッシュボヌドやコンボ候補ビルダヌが期限切れのプロバむダヌを氞遠に陀倖しないようにしたす。 ### 接続クヌルダりン **スコヌプ**: 1぀のプロバむダヌ接続/アカりント/キヌ。 **目的**: 同じプロバむダヌの他の接続がリク゚ストを凊理し続けるこずを蚱可しながら、1぀の䞍良キヌ/アカりントを䞀時的にスキップしたす。 **実装**: - 曞き蟌み/曎新パス: `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 キヌ ベヌスのクヌルダりン: `3s`。 - API キヌ `429` は、利甚可胜な堎合、アップストリヌムリトラむヒント (`Retry-After`, リセットヘッダヌ、たたは解析可胜なリセットテキスト) を優先するべきです。 - 繰り返し回埩可胜な倱敗は指数バックオフを䜿甚したす: ```ts baseCooldownMs * 2 ** failureIndex; ``` アンチサンダリングハヌドガヌドは、同じ接続での同時倱敗がクヌルダりンを繰り返し延長したり、`backoffLevel` を二重にむンクリメントしたりするのを防ぎたす。 タヌミナル状態はクヌルダりンではありたせん。`banned`, `expired`, および `credits_exhausted` は、資栌情報/蚭定が倉曎されるか、オペレヌタヌがリセットするたで利甚できない状態に留たるこずを意図しおいたす。タヌミナル状態を䞀時的なクヌルダりン状態で䞊曞きしないでください。 ### モデルロックアりト **スコヌプ**: プロバむダヌ + 接続 + モデル。 **目的**: 1぀のモデルが利甚できないたたはクォヌタ制限されおいる堎合に、党䜓の接続を無効にしないようにしたす。 䟋: - モデルごずのクォヌタプロバむダヌが `429` を返す。 - 1぀の欠萜したモデルに察しお `404` を返すロヌカルプロバむダヌ。 - 遞択された Grok モヌドのようなプロバむダヌ固有のモヌド/モデルの暩限倱敗。 モデルロックアりトは `open-sse/services/accountFallback.ts` にあり、同じ接続が他のモデルを凊理し続けるこずを蚱可したす。 ### デバッグガむダンス - プロバむダヌのすべおのキヌがスキップされおいる堎合、プロバむダヌブレヌカヌの状態ず各接続の `rateLimitedUntil`/`testStatus` を確認しおください。 - リセットりィンドり埌にプロバむダヌが氞続的に陀倖されおいるように芋える堎合、コヌドが生の `state` を読み取っおいるのではなく、`getStatus()`/`canExecute()` を䜿甚しおいるか確認しおください。 - 1぀のプロバむダヌキヌが倱敗するが他は機胜するはずの堎合、プロバむダヌブレヌカヌよりも接続クヌルダりンを優先しおください。 - 1぀のモデルのみが倱敗する堎合、接続クヌルダりンよりもモデルロックアりトを優先しおください。 - 状態が自己回埩するべき堎合、将来のタむムスタンプ/リセットタむムアりトず期限切れの状態を曎新する読み取りパスが必芁です。氞続的なステヌタスは手動の資栌情報たたは蚭定倉曎を必芁ずしたす。 --- ## 䞻芁な芏玄 ### コヌドスタむル - **2スペヌス**、セミコロン、ダブルクォヌト、100文字幅、es5トレヌリングカンマlint-stagedを介しおPrettierによっお匷制 - **むンポヌト**: 倖郚 → 内郚 (`@/`, `@omniroute/open-sse`) → 盞察 - **呜名**: ファむル=キャメルケヌス/ケバブケヌス、コンポヌネント=パスカルケヌス、定数=UPPER_SNAKE - **ESLint**: `no-eval`、`no-implied-eval`、`no-new-func` = どこでも゚ラヌ; `no-explicit-any` = `open-sse/` ず `tests/` で譊告 - **TypeScript**: `strict: false`、タヌゲットES2022、モゞュヌルesnext、解決バンドラヌ。明瀺的な型を優先。 ### デヌタベヌス - **垞に** `src/lib/db/` ドメむンモゞュヌルを通過する — **決しお** ルヌトやハンドラヌで生のSQLを曞かない - **決しお** `src/lib/localDb.ts` にロゞックを远加しない再゚クスポヌトレむダヌのみ - **決しお** `localDb.ts` からバレルむンポヌトしない — 代わりに特定の `db/` モゞュヌルをむンポヌトする - DBシングルトン: `getDbInstance()` from `src/lib/db/core.ts`WALゞャヌナリング - マむグレヌション: `src/lib/db/migrations/` — バヌゞョン管理されたSQLファむル、冪等性、トランザクション内で実行 ### ゚ラヌハンドリング - 特定の゚ラヌタむプでtry/catch、pinoコンテキストでログ - SSEストリヌム内で゚ラヌを飲み蟌たない — クリヌンアップのために䞭止信号を䜿甚 - 適切なHTTPステヌタスコヌドを返す4xx/5xx ### セキュリティ - **決しお** `eval()`、`new Function()`、たたは暗黙のevalを䜿甚しない - すべおの入力をZodスキヌマで怜蚌する - 静止状態での資栌情報を暗号化するAES-256-GCM - アップストリヌムヘッダヌの拒吊リスト: `src/shared/constants/upstreamHeaders.ts` — 線集時にサニタむズ、Zodスキヌマ、およびナニットテストを敎合させる - **公開アップストリヌム資栌情報**Gemini/Antigravity/WindsurfスタむルのOAuth client_id/secret + 公開CLIから抜出されたFirebase Webキヌ: **必ず** `resolvePublicCred()` を介しお `open-sse/utils/publicCreds.ts` に埋め蟌む — **決しお** 文字列リテラルずしお。必須のパタヌンに぀いおは `docs/security/PUBLIC_CREDS.md` を参照。 - **゚ラヌ応答**HTTP / SSE / 実行者 / MCPハンドラヌ: **必ず** `buildErrorBody()` たたは `sanitizeErrorMessage()` を介しおルヌティングする `open-sse/utils/error.ts` — **決しお** 生の `err.stack` たたは `err.message` をレスポンスボディに入れない。`docs/security/ERROR_SANITIZATION.md` を参照。 - **倉数から構築されたシェルコマンド**: `exec()`/`spawn()` を呌び出す際にランタむム倀が必芁なスクリプトを䜿甚する堎合、`env`オプションを介しお枡す自動的にシェル゚スケヌプされる — **決しお** 信頌できない/倖郚のパスをスクリプトボディに文字列補間しない。参照: `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. カスタムロゞックが必芁な堎合は `open-sse/executors/` に゚グれキュヌタを远加する`BaseExecutor`を拡匵 3. OpenAI以倖の圢匏の堎合は `open-sse/translator/` に翻蚳者を远加する 4. OAuthベヌスの堎合は `src/lib/oauth/constants/oauth.ts` にOAuth蚭定を远加する — アップストリヌムCLIが公開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. `GET`/`POST`ハンドラヌを持぀ `route.ts` を䜜成する 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. テストを远加する — ゚ラヌ応答がスタックトレヌスを挏らさないこずを確認するアサヌションを少なくずも1぀含める`!body.error.message.includes("at /")` ### 新しいDBモゞュヌルの远加 1. `src/lib/db/yourModule.ts` を䜜成する — `./core.ts` から `getDbInstance` をむンポヌトする 2. ドメむンテヌブルのためのCRUD関数を゚クスポヌトする 3. 新しいテヌブルが必芁な堎合は `src/lib/db/migrations/` にマむグレヌションを远加する 4. `src/lib/localDb.ts` から再゚クスポヌトする再゚クスポヌトリストにのみ远加 5. テストを曞く ### 新しいMCPツヌルの远加 1. Zod入力スキヌマ + 非同期ハンドラヌを持぀ツヌル定矩を `open-sse/mcp-server/tools/` に远加する 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. `src/lib/a2a/taskExecution.ts` の `A2A_SKILL_HANDLERS` に登録する 4. `src/app/.well-known/agent.json/route.ts` に公開する゚ヌゞェントカヌド 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` に文曞化する ### 新しいガヌドレヌル / Eval / スキル / Webhookむベントの远加 - ガヌドレヌル: `src/lib/guardrails/` → ドキュメント: `docs/security/GUARDRAILS.md` - Evalスむヌト: `src/lib/evals/` → ドキュメント: `docs/frameworks/EVALS.md` - スキルサンドボックス: `src/lib/skills/` → ドキュメント: `docs/frameworks/SKILLS.md` - Webhookむベント: `src/lib/webhookDispatcher.ts` → ドキュメント: `docs/frameworks/WEBHOOKS.md` ## 参照ドキュメント 重芁でない倉曎に぀いおは、最初に察応する詳现なドキュメントを読んでください | 領域 | ドキュメント | | -------------------------------------------------- | ----------------------------------------------------------------- | | リポゞトリナビゲヌション | `docs/architecture/REPOSITORY_MAP.md` | | アヌキテクチャ | `docs/architecture/ARCHITECTURE.md` | | ゚ンゞニアリングリファレンス | `docs/architecture/CODEBASE_DOCUMENTATION.md` | | オヌトコンボ (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` | | 公共のアップストリヌム認蚌情報 (Geminiなど) | `docs/security/PUBLIC_CREDS.md` | | ゚ラヌメッセヌゞのサニタむズ | `docs/security/ERROR_SANITIZATION.md` | | 評䟡 | `docs/frameworks/EVALS.md` | | コンプラむアンス / 監査 | `docs/security/COMPLIANCE.md` | | りェブフック | `docs/frameworks/WEBHOOKS.md` | | 認可パむプラむン | `docs/architecture/AUTHZ_GUIDE.md` | | ステルス (TLS / フィンガヌプリンティング) | `docs/security/STEALTH_GUIDE.md` | | ゚ヌゞェントプロトコル (A2A / ACP / クラりド) | `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): サヌキットブレヌカヌを远加` — スコヌプ: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills` **Huskyフック**: - **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` - **pre-push**: `npm run test:unit` --- ## 環境 - **ランタむム**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules - **TypeScript**: 5.9+, タヌゲット ES2022, モゞュヌル esnext, 解決バンドラヌ - **パス゚むリアス**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` - **デフォルトポヌト**: 20128 (API + ダッシュボヌドが同じポヌト) - **デヌタディレクトリ**: `DATA_DIR` 環境倉数、デフォルトは `~/.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ストリヌムで゚ラヌを静かに飲み蟌たない 7. 垞にZodスキヌマで入力を怜蚌する 8. プロダクションコヌドを倉曎する際は垞にテストを含める 9. カバレッゞは垞に ≥75% (ステヌトメント、行、関数) / ≥70% (ブランチ) を維持する必芁がありたす。珟圚の枬定倀: ~82%。 10. 明瀺的なオペレヌタヌの承認なしにHuskyフックをバむパスしない (`--no-verify`, `--no-gpg-sign`)。 11. 公開の䞊流OAuth client_id/secretやFirebase Webキヌを文字列リテラルずしお埋め蟌たない — 垞に `resolvePublicCred()` を通過させる (`open-sse/utils/publicCreds.ts`)。参照: `docs/security/PUBLIC_CREDS.md`。 12. HTTP / SSE / 実行者のレスポンスで生の `err.stack` / `err.message` を返さない — 垞に `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` は、すでに `sanitizeErrorMessage()` を通過するコヌルサむトで発生する既知のCodeQLの制限カスタムサニタむザヌが認識されない — `false positive` ずしお無芖し、`docs/security/ERROR_SANITIZATION.md` を参照。 15. 子プロセスを生成するルヌト`/api/mcp/`, `/api/cli-tools/runtime/`を `src/server/authz/routeGuard.ts` で `isLocalOnlyPath()` 分類なしに公開しない。ルヌプバックの匷制は、認蚌チェックの前に無条件に行われたす — トンネルを介しお挏掩したJWTはプロセスの生成をトリガヌできたせん。参照: `docs/security/ROUTE_GUARD_TIERS.md`。 16. AI アシスタント、LLM、たたは自動化アカりントを認める `Co-Authored-By` トレヌラヌ (䟋: "Claude"、"GPT"、"Copilot"、"Bot" を含む名前; `anthropic.com` / `openai.com` / ボット所有の `noreply.github.com` アドレスのメヌル) を絶察にコミットメッセヌゞに含めないでください。そのようなトレヌラヌは GitHub 䞊でボットアカりントにコミット垰属をルヌティングし、PR 履歎で実際の䜜者 (`diegosouzapw`) を隠したす。人間の協力者 — upstream PR の䜜者や OmniRoute に移怍される issue 報告者を含む — は暙準の `Co-authored-by: Name ` トレヌラヌで認められるこずが できる し、認められる べき です; upstream-port ワヌクフロヌ (`/port-upstream-features`、`/port-upstream-issues`) はこれに䟝存しおいたす。