pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-07-26 09:52:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

i18n(zh-TW): complete Traditional Chinese (Taiwan) translation overhaul (#8024)

Browse Source 
- UI messages: 100% coverage (was ~78%). Translated 2871 missing keys,
  eliminated all 420 __MISSING__ placeholders. 0 remaining.
- Terminology: 提供商→提供者 (493 fixes), 令牌→權杖 (88 fixes),
  激活→啟用 (1 fix), 配置→設定 (13 context-aware fixes) in UI messages
- CLI locale: same terminology pass (69 fixes)
- Docs: translated all 26 zh-TW docs (was 3/26). USER_GUIDE, ARCHITECTURE,
  API_REFERENCE, ENVIRONMENT and 20 more now in Traditional Chinese.
- Preserved variable placeholders, ICU plurals, markdown, code blocks

Co-authored-by: lunkerchen <lunkerchen@users.noreply.github.com>
Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>
This commit is contained in:
lunkerchen
2026-07-22 17:43:46 +08:00
committed by GitHub
parent 98754c16dc
commit 2e6dfda90d
26 changed files with 13968 additions and 5587 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
bin/cli/locales/zh-TW.json
View File

@@ -29,16 +29,16 @@
"setup": {
"title": "OmniRoute 設定",
"passwordPrompt": "管理員密碼",
"providerPrompt": "預設提供商（留空跳過）",
"providerPrompt": "預設提供者（留空跳過）",
"done": "設定完成",
"passwordSet": "管理員密碼已配置",
"providerSet": "提供商已配置：{name}",
"testingProvider": "正在測試提供商連線：{name}",
"testPassed": "提供商測試通過",
"testFailed": "提供商測試失敗：{error}",
"providerSet": "提供者已配置：{name}",
"testingProvider": "正在測試提供者連線：{name}",
"testPassed": "提供者測試通過",
"testFailed": "提供者測試失敗：{error}",
"loginEnabled": "登入：已啟用（密碼已更新）",
"loginDisabled": "登入：已停用",
"providerInfo": "提供商：{info}"
"providerInfo": "提供者：{info}"
},
"doctor": {
"title": "OmniRoute 診斷",
@@ -52,29 +52,29 @@
"warnings": "{count} 個警告 — 見上文。"
},
"providers": {
"title": "提供商",
"noProviders": "未配置提供商。執行：omniroute setup",
"title": "提供者",
"noProviders": "未配置提供者。執行：omniroute setup",
"testing": "正在測試 {name}...",
"available": "{count} 個提供商可用",
"available": "{count} 個提供者可用",
"connected": "已連線",
"disconnected": "未連線",
"validationFailed": "驗證失敗：{error}",
"metrics": {
"description": "顯示提供商效能指標（延遲、成功率、成本）",
"provider": "按提供商 ID 篩選",
"description": "顯示提供者效能指標（延遲、成功率、成本）",
"provider": "按提供者 ID 篩選",
"connection_id": "按連線 ID 篩選",
"period": "時間範圍：1h|6h|24h|7d|30d（預設：24h）",
"metric": "關注特定指標欄位",
"sort": "按欄位排序（降序）",
"limit": "最大行數（預設：50）",
"watch": "每 5 秒重新整理（即時模式）",
"compare": "逗號分隔的提供商 ID，並排比較"
"compare": "逗號分隔的提供者 ID，並排比較"
},
"metric_single": {
"description": "獲取特定連線的單個指標值"
},
"rotate": {
"description": "輪換提供商連線的上游 API 金鑰",
"description": "輪換提供者連線的上游 API 金鑰",
"newKeyOpt": "新 API 金鑰值（避免使用：優先使用 --from-env）",
"fromEnvOpt": "從環境變數 VAR 讀取新金鑰",
"oauthOpt": "改為觸發 OAuth 重新認證流程",
@@ -89,18 +89,18 @@
"testFailed": "輪換後測試失敗：{error}"
},
"status": {
"description": "顯示所有提供商連線的金鑰健康狀態（期限、過期、冷卻）",
"providerOpt": "按提供商名稱篩選",
"header": "ID 提供商 名稱 過期狀態 測試狀態 冷卻至",
"noData": "沒有可用的提供商連線資料。",
"description": "顯示所有提供者連線的金鑰健康狀態（期限、過期、冷卻）",
"providerOpt": "按提供者名稱篩選",
"header": "ID 提供者 名稱 過期狀態 測試狀態 冷卻至",
"noData": "沒有可用的提供者連線資料。",
"requiresServer": "providers status 需要 OmniRoute 伺服器正在執行。"
}
},
"keys": {
"title": "API 金鑰",
"addDescription": "為提供商新增或更新 API 金鑰",
"addDescription": "為提供者新增或更新 API 金鑰",
"listDescription": "列出所有已配置的 API 金鑰",
"removeDescription": "移除提供商的 API 金鑰",
"removeDescription": "移除提供者的 API 金鑰",
"regenerateDescription": "重新生成 OmniRoute API 金鑰",
"revokeDescription": "撤銷 OmniRoute API 金鑰",
"revealDescription": "顯示未掩碼的 API 金鑰值",
@@ -122,10 +122,10 @@
"revoked": "金鑰 {id} 已撤銷。",
"rotated": "金鑰 {id} 已輪換。新金鑰 ID：{newId}",
"revealWarning": "⚠ 這將顯示完整的未掩碼金鑰。請確保您的螢幕不被人看到。",
"providerRequired": "需要提供商。",
"providerRequired": "需要提供者。",
"keyRequired": "需要 API 金鑰。",
"stdinEmpty": "未通過標準輸入提供 API 金鑰。",
"unknownProvider": "未知提供商：{provider}",
"unknownProvider": "未知提供者：{provider}",
"policy": {
"title": "金鑰策略",
"showDescription": "顯示金鑰的速率/成本策略",
@@ -151,7 +151,7 @@
"model": "模型 ID（預設：auto）",
"system": "系統提示",
"combo": "強制指定組合名稱",
"max_tokens": "響應最大令牌數",
"max_tokens": "響應最大權杖數",
"responses_api": "使用 /v1/responses 而不是 /v1/chat/completions",
"raw": "列印接收到的原始 SSE 行",
"debug": "在 stderr 中列印每塊的時間資訊",
@@ -165,7 +165,7 @@
"analytics": {
"description": "顯示彙總使用分析",
"period": "時間範圍：1d|7d|30d|90d|ytd|all（預設：30d）",
"provider": "按提供商 ID 篩選"
"provider": "按提供者 ID 篩選"
},
"budget": {
"description": "管理成本預算",
@@ -175,8 +175,8 @@
}
},
"quota": {
"description": "顯示提供商配額使用情況",
"provider": "按提供商 ID 篩選",
"description": "顯示提供者配額使用情況",
"provider": "按提供者 ID 篩選",
"check": "顯示新請求是否有可用配額"
},
"logs": {
@@ -201,7 +201,7 @@
}
},
"cost": {
"description": "按提供商、模型、組合或 API 金鑰顯示成本報告",
"description": "按提供者、模型、組合或 API 金鑰顯示成本報告",
"period": "時間範圍：1d|7d|30d|90d|ytd|all（預設：30d）",
"since": "開始日期（ISO 格式，例如 2026-01-01）— 覆蓋 --period",
"until": "結束日期（ISO 格式）",
@@ -210,12 +210,12 @@
"limit": "顯示的最大行數（預設：100）"
},
"simulate": {
"description": "模擬路由（空執行）— 顯示將選擇哪些提供商而不呼叫上游",
"description": "模擬路由（空執行）— 顯示將選擇哪些提供者而不呼叫上游",
"file": "從 JSON 檔案載入完整請求體",
"model": "模型 ID（預設：auto）",
"combo": "強制指定組合名稱",
"reasoning": "推理努力級別（low|medium|high）",
"thinking": "擴充套件思維令牌預算",
"thinking": "擴充套件思維權杖預算",
"explain": "在 stderr 中列印回退樹和成本範圍",
"noCombo": "未找到匹配的組合。使用以下命令配置：omniroute combo create"
},
@@ -225,11 +225,11 @@
"stdin": "從標準輸入讀取提示",
"system": "系統提示",
"model": "模型 ID（預設：auto）",
"max_tokens": "響應最大令牌數",
"max_tokens": "響應最大權杖數",
"temperature": "取樣溫度（0–2）",
"top_p": "Top-p 核取樣",
"reasoning_effort": "推理努力級別（low|medium|high）",
"thinking_budget": "擴充套件思維令牌預算",
"thinking_budget": "擴充套件思維權杖預算",
"combo": "強制指定組合名稱",
"responses_api": "使用 /v1/responses 而不是 /v1/chat/completions",
"stream": "增量流式傳輸響應",
@@ -301,7 +301,7 @@
"cost": "成本（24h）："
},
"quota": {
"description": "顯示提供商配額使用情況",
"description": "顯示提供者配額使用情況",
"noServer": "伺服器未執行。啟動：omniroute serve",
"noData": "沒有可用的配額資訊。"
},
@@ -315,12 +315,12 @@
"description": "一鍵啟動本地 Redis 容器（Podman 或 Docker），用於 OmniRoute 快取和配額跟蹤"
},
"test": {
"description": "測試提供商連線",
"description": "測試提供者連線",
"noServer": "伺服器未執行。啟動：omniroute serve",
"testing": "正在測試 {provider} / {model}...",
"passed": "連線成功！",
"failed": "連線失敗：{error}",
"allProvidersOpt": "測試所有已配置的提供商",
"allProvidersOpt": "測試所有已配置的提供者",
"latencyOpt": "顯示延遲測量值（平均/最小/最大 毫秒）",
"repeatOpt": "重複測試 N 次並彙總結果",
"compareOpt": "逗號分隔的要比較的模型（例如 gpt-4o,claude-3-5-sonnet）",
@@ -328,7 +328,7 @@
"saved": "結果已儲存至 {path}",
"compareTitle": "模型比較",
"compareMinTwo": "--compare 需要至少兩個模型（逗號分隔）",
"noProviders": "未配置提供商。新增：omniroute keys add"
"noProviders": "未配置提供者。新增：omniroute keys add"
},
"update": {
"checking": "正在檢查更新...",
@@ -445,7 +445,7 @@
"description": "配置壓縮設定",
"engine": "壓縮引擎（caveman|rtk|hybrid|none）",
"caveman_agg": "Caveman 激程序度 0.0–1.0",
"rtk_budget": "RTK 令牌預算",
"rtk_budget": "RTK 權杖預算",
"language_pack": "要啟用的語言包"
},
"engine": {
@@ -509,7 +509,7 @@
},
"models": {
"description": "列出可用模型（需要伺服器）",
"search": "按 ID、名稱、提供商或描述篩選模型",
"search": "按 ID、名稱、提供者或描述篩選模型",
"noServer": "伺服器未執行。啟動：omniroute serve",
"noModels": "未找到模型。"
},
@@ -621,7 +621,7 @@
"type": "按記憶型別篩選（user|feedback|project|reference）",
"limit": "最大結果數（預設：20）",
"api_key": "按 API 金鑰篩選",
"token_budget": "限制結果中的總令牌數"
"token_budget": "限制結果中的總權杖數"
},
"add": {
"description": "新增新的記憶條目",
@@ -656,25 +656,25 @@
}
},
"oauth": {
"description": "管理 OAuth 提供商連線",
"description": "管理 OAuth 提供者連線",
"providers": {
"description": "列出支援 OAuth 的提供商及其流程型別"
"description": "列出支援 OAuth 的提供者及其流程型別"
},
"start": {
"description": "為提供商啟動 OAuth 授權流程",
"provider": "提供商 ID（gemini, copilot, cursor, ...）",
"description": "為提供者啟動 OAuth 授權流程",
"provider": "提供者 ID（gemini, copilot, cursor, ...）",
"no_browser": "僅列印 URL — 不開啟瀏覽器",
"import_system": "從本地系統配置自動匯入憑據",
"social": "社交登入提供商（google|github）— kiro 需要",
"social": "社交登入提供者（google|github）— kiro 需要",
"timeout": "等待授權超時時間（毫秒，預設：300000）"
},
"status": {
"description": "列出活動的 OAuth 連線",
"provider": "按提供商 ID 篩選"
"provider": "按提供者 ID 篩選"
},
"revoke": {
"description": "撤銷 OAuth 連線",
"provider": "要撤銷的提供商 ID",
"provider": "要撤銷的提供者 ID",
"connection_id": "按 ID 撤銷特定連線",
"yes": "跳過確認提示"
}
@@ -884,20 +884,20 @@
"description": "管理模型定價資料",
"sync": {
"description": "從上游同步價格",
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"force": "強制重新同步"
},
"list": {
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"model": "按模型篩選",
"limit": "最大結果數"
},
"defaults": {
"description": "管理預設定價",
"input": "每 1M 令牌的輸入成本（美元）",
"output": "每 1M 令牌的輸出成本（美元）",
"cacheRead": "每 1M 令牌的快取讀取成本（美元）",
"cacheWrite": "每 1M 令牌的快取寫入成本（美元）"
"input": "每 1M 權杖的輸入成本（美元）",
"output": "每 1M 權杖的輸出成本（美元）",
"cacheRead": "每 1M 權杖的快取讀取成本（美元）",
"cacheWrite": "每 1M 權杖的快取寫入成本（美元）"
},
"diff": {
"description": "顯示與上游價格的差異",
@@ -907,25 +907,25 @@
"resilience": {
"description": "檢查和管理彈性機制",
"status": {
"provider": "按提供商篩選"
"provider": "按提供者篩選"
},
"breakers": {
"provider": "按提供商篩選"
"provider": "按提供者篩選"
},
"cooldowns": {
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"connectionId": "按連線 ID 篩選"
},
"lockouts": {
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"model": "按模型篩選"
},
"reset": {
"description": "重置斷路器/冷卻狀態",
"provider": "要重置的提供商",
"provider": "要重置的提供者",
"connectionId": "要重置的連線 ID",
"model": "要重置鎖定狀態的模型",
"allCooldowns": "重置提供商的所有冷卻",
"allCooldowns": "重置提供者的所有冷卻",
"yes": "跳過確認"
},
"profile": {
@@ -940,13 +940,13 @@
}
},
"nodes": {
"description": "管理提供商節點（端點）",
"description": "管理提供者節點（端點）",
"list": {
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"enabled": "僅顯示已啟用的節點"
},
"add": {
"provider": "提供商名稱",
"provider": "提供者名稱",
"baseUrl": "節點的基礎 URL",
"name": "節點名稱",
"weight": "負載均衡權重",
@@ -965,7 +965,7 @@
},
"validate": {
"baseUrl": "要驗證的 URL",
"provider": "要驗證的提供商"
"provider": "要驗證的提供者"
},
"test": {
"description": "向節點發送測試請求"
@@ -993,7 +993,7 @@
"description": "管理 RTK 上下文最佳化器",
"config": {
"description": "顯示或更新 RTK 配置",
"tokenBudget": "RTK 令牌預算",
"tokenBudget": "RTK 權杖預算",
"reservePct": "保留百分比"
},
"filters": {
@@ -1091,7 +1091,7 @@
"oneproxy": {
"description": "管理 OneProxy 上游代理池",
"stats": {
"provider": "按提供商篩選",
"provider": "按提供者篩選",
"period": "時間範圍（預設：24h）"
},
"fetch": {
@@ -1101,14 +1101,14 @@
},
"rotate": {
"description": "強制輪換代理",
"provider": "要輪換的提供商",
"provider": "要輪換的提供者",
"connectionId": "要輪換的特定連線 ID"
},
"config": {
"description": "顯示或更新 OneProxy 配置",
"enabled": "啟用代理池（true|false）",
"poolSize": "池大小",
"providerSource": "代理提供商的 URL",
"providerSource": "代理提供者的 URL",
"rotationPolicy": "輪換策略：sticky|per-request|periodic"
},
"pool": {
@@ -1163,11 +1163,11 @@
"fromCloud": "從雲備份初始化"
},
"tokens": {
"description": "管理同步令牌",
"description": "管理同步權杖",
"create": {
"name": "令牌名稱",
"scope": "令牌作用域",
"ttl": "令牌有效期（例如 30d）"
"name": "權杖名稱",
"scope": "權杖作用域",
"ttl": "權杖有效期（例如 30d）"
},
"revoke": {
"yes": "跳過確認"
@@ -1201,7 +1201,7 @@
"bash": "列印 bash 補全指令碼",
"fish": "列印 fish 補全指令碼",
"install": "為檢測到的 Shell 全域性安裝補全指令碼",
"refresh": "重新整理組合/提供商/模型快取"
"refresh": "重新整理組合/提供者/模型快取"
},
"logs": {
"description": "流式傳輸或匯出請求日誌",

2539
docs/i18n/zh-TW/CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff

142
docs/i18n/zh-TW/CODE_OF_CONDUCT.md
View File

@@ -1,132 +1,88 @@
# Contributor Covenant Code of Conduct (中文 (繁體))
# Contributor Covenant 行為準則 (中文 (繁體))
🌐 **Languages:** 🇺🇸 [English](../../../CODE_OF_CONDUCT.md) · 🇸🇦 [ar](../ar/CODE_OF_CONDUCT.md) · 🇧🇬 [bg](../bg/CODE_OF_CONDUCT.md) · 🇧🇩 [bn](../bn/CODE_OF_CONDUCT.md) · 🇨🇿 [cs](../cs/CODE_OF_CONDUCT.md) · 🇩🇰 [da](../da/CODE_OF_CONDUCT.md) · 🇩🇪 [de](../de/CODE_OF_CONDUCT.md) · 🇪🇸 [es](../es/CODE_OF_CONDUCT.md) · 🇮🇷 [fa](../fa/CODE_OF_CONDUCT.md) · 🇫🇮 [fi](../fi/CODE_OF_CONDUCT.md) · 🇫🇷 [fr](../fr/CODE_OF_CONDUCT.md) · 🇮🇳 [gu](../gu/CODE_OF_CONDUCT.md) · 🇮🇱 [he](../he/CODE_OF_CONDUCT.md) · 🇮🇳 [hi](../hi/CODE_OF_CONDUCT.md) · 🇭🇺 [hu](../hu/CODE_OF_CONDUCT.md) · 🇮🇩 [id](../id/CODE_OF_CONDUCT.md) · 🇮🇹 [it](../it/CODE_OF_CONDUCT.md) · 🇯🇵 [ja](../ja/CODE_OF_CONDUCT.md) · 🇰🇷 [ko](../ko/CODE_OF_CONDUCT.md) · 🇮🇳 [mr](../mr/CODE_OF_CONDUCT.md) · 🇲🇾 [ms](../ms/CODE_OF_CONDUCT.md) · 🇳🇱 [nl](../nl/CODE_OF_CONDUCT.md) · 🇳🇴 [no](../no/CODE_OF_CONDUCT.md) · 🇵🇭 [phi](../phi/CODE_OF_CONDUCT.md) · 🇵🇱 [pl](../pl/CODE_OF_CONDUCT.md) · 🇵🇹 [pt](../pt/CODE_OF_CONDUCT.md) · 🇧🇷 [pt-BR](../pt-BR/CODE_OF_CONDUCT.md) · 🇷🇴 [ro](../ro/CODE_OF_CONDUCT.md) · 🇷🇺 [ru](../ru/CODE_OF_CONDUCT.md) · 🇸🇰 [sk](../sk/CODE_OF_CONDUCT.md) · 🇸🇪 [sv](../sv/CODE_OF_CONDUCT.md) · 🇰🇪 [sw](../sw/CODE_OF_CONDUCT.md) · 🇮🇳 [ta](../ta/CODE_OF_CONDUCT.md) · 🇮🇳 [te](../te/CODE_OF_CONDUCT.md) · 🇹🇭 [th](../th/CODE_OF_CONDUCT.md) · 🇹🇷 [tr](../tr/CODE_OF_CONDUCT.md) · 🇺🇦 [uk-UA](../uk-UA/CODE_OF_CONDUCT.md) · 🇵🇰 [ur](../ur/CODE_OF_CONDUCT.md) · 🇻🇳 [vi](../vi/CODE_OF_CONDUCT.md) · 🇨🇳 [zh-CN](../zh-CN/CODE_OF_CONDUCT.md)
🌐 **語言:** 🇺🇸 [English](../../../CODE_OF_CONDUCT.md) · 🇸🇦 [ar](../ar/CODE_OF_CONDUCT.md) · 🇧🇬 [bg](../bg/CODE_OF_CONDUCT.md) · 🇧🇩 [bn](../bn/CODE_OF_CONDUCT.md) · 🇨🇿 [cs](../cs/CODE_OF_CONDUCT.md) · 🇩🇰 [da](../da/CODE_OF_CONDUCT.md) · 🇩🇪 [de](../de/CODE_OF_CONDUCT.md) · 🇪🇸 [es](../es/CODE_OF_CONDUCT.md) · 🇮🇷 [fa](../fa/CODE_OF_CONDUCT.md) · 🇫🇮 [fi](../fi/CODE_OF_CONDUCT.md) · 🇫🇷 [fr](../fr/CODE_OF_CONDUCT.md) · 🇮🇳 [gu](../gu/CODE_OF_CONDUCT.md) · 🇮🇱 [he](../he/CODE_OF_CONDUCT.md) · 🇮🇳 [hi](../hi/CODE_OF_CONDUCT.md) · 🇭🇺 [hu](../hu/CODE_OF_CONDUCT.md) · 🇮🇩 [id](../id/CODE_OF_CONDUCT.md) · 🇮🇹 [it](../it/CODE_OF_CONDUCT.md) · 🇯🇵 [ja](../ja/CODE_OF_CONDUCT.md) · 🇰🇷 [ko](../ko/CODE_OF_CONDUCT.md) · 🇮🇳 [mr](../mr/CODE_OF_CONDUCT.md) · 🇲🇾 [ms](../ms/CODE_OF_CONDUCT.md) · 🇳🇱 [nl](../nl/CODE_OF_CONDUCT.md) · 🇳🇴 [no](../no/CODE_OF_CONDUCT.md) · 🇵🇭 [phi](../phi/CODE_OF_CONDUCT.md) · 🇵🇱 [pl](../pl/CODE_OF_CONDUCT.md) · 🇵🇹 [pt](../pt/CODE_OF_CONDUCT.md) · 🇧🇷 [pt-BR](../pt-BR/CODE_OF_CONDUCT.md) · 🇷🇴 [ro](../ro/CODE_OF_CONDUCT.md) · 🇷🇺 [ru](../ru/CODE_OF_CONDUCT.md) · 🇸🇰 [sk](../sk/CODE_OF_CONDUCT.md) · 🇸🇪 [sv](../sv/CODE_OF_CONDUCT.md) · 🇰🇪 [sw](../sw/CODE_OF_CONDUCT.md) · 🇮🇳 [ta](../ta/CODE_OF_CONDUCT.md) · 🇮🇳 [te](../te/CODE_OF_CONDUCT.md) · 🇹🇭 [th](../th/CODE_OF_CONDUCT.md) · 🇹🇷 [tr](../tr/CODE_OF_CONDUCT.md) · 🇺🇦 [uk-UA](../uk-UA/CODE_OF_CONDUCT.md) · 🇵🇰 [ur](../ur/CODE_OF_CONDUCT.md) · 🇻🇳 [vi](../vi/CODE_OF_CONDUCT.md) · 🇨🇳 [zh-CN](../zh-CN/CODE_OF_CONDUCT.md)
---
## Our Pledge
## 我們的承諾
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
我們身為成員、貢獻者與領導者，承諾讓參與社群的體驗不受騷擾，無論年齡、體型、明顯或不明顯的障礙、種族、性別特徵、性別認同與表現、經驗程度、教育程度、社經地位、國籍、外貌、種族、宗教或性取向。
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
我們承諾以行動與互動，促進一個開放、友善、多元、包容且健康的社群。
## Our Standards
## 我們的標準
Examples of behavior that contributes to a positive environment for our
community include:
有助於為社群營造正面環境的行為範例包括：
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best not just for us as individuals, but for the
overall community
- 對他人展現同理心與善意
- 尊重不同的意見、觀點與經驗
- 提供並優雅地接受建設性反饋
- 承擔責任，向受我們錯誤影響的人道歉，並從經驗中學習
- 關注的不僅是我們個人，而是整個社群的最佳利益
Examples of unacceptable behavior include:
不可接受的行為範例包括：
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
- 使用帶有性暗示的語言或圖像，以及任何形式的性關注或性誘惑
- 挑釁、侮辱或貶損的評論，以及人身或政治攻擊
- 公開或私下騷擾
- 未經明確許可，發布他人的私人資訊（如地址或電子郵件）
- 其他在專業環境中可被合理視為不恰當的行為
## Enforcement Responsibilities
## 執行責任
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
社群領導者負責明確並執行我們對可接受行為的標準，並對他們認為不恰當、具威脅性、冒犯性或有害的任何行為採取適當且公正的糾正措施。
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
社群領導者有權移除、編輯或拒絕不符合本行為準則的評論、提交、程式碼、Wiki 編輯、問題及其他貢獻，並將在適當時說明管理決策的理由。
## Scope
## 適用範圍
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
本行為準則適用於所有社群空間，也適用於個人在公共場合正式代表社群的情況。代表社群的範例包括使用官方電子郵件地址、通過官方社交媒體帳號發文，或在線上或線下活動中擔任指定代表。
## Enforcement
## 執行
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
.
All complaints will be reviewed and investigated promptly and fairly.
可向負責執行的社群領導者舉報濫用、騷擾或其他不可接受的行為，請透過以下方式聯絡：
- 開啟私人安全性公告：<https://github.com/diegosouzapw/OmniRoute/security/advisories/new>
- 或發送郵件給維護者：diegosouza.pw@outlook.com
- 針對安全敏感性事件，請參閱 [`SECURITY.md`](SECURITY.md)
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
所有投訴都將被及時且公正地審查與調查。
## Enforcement Guidelines
所有社群領導者都有義務尊重事件舉報人的隱私與安全。
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
## 執行指引
### 1. Correction
社群領導者將遵循以下社群影響指引，確定對他們認為違反本行為準則的行為所應採取的後果：
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
### 1. 更正
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
**社群影響：** 使用不當語言或其他被視為不專業或不受社群歡迎的行為。
### 2. Warning
**後果：** 社群領導者發出私下的書面警告，說明違規的性質，並解釋為何該行為不當。可能要求公開道歉。
**Community Impact**: A violation through a single incident or series
of actions.
### 2. 警告
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
**社群影響：** 透過單一事件或一系列行為造成的違規。
### 3. Temporary Ban
**後果：** 發出警告，說明持續行為的後果。在特定期間內，不得與相關人員互動，包括未經要求的互動以及與行為準則執行者的互動。這包括避免在社群空間以及社交媒體等外部管道進行互動。違反這些條款可能導致暫時或永久禁止。
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
### 3. 暫時禁止
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
**社群影響：** 嚴重違反社群標準，包括持續的不當行為。
### 4. Permanent Ban
**後果：** 在特定期間內，暫時禁止與社群進行任何形式的互動或公開交流。在此期間，不得與相關人員進行公開或私下的互動，包括未經要求的互動以及與行為準則執行者的互動。違反這些條款可能導致永久禁止。
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
### 4. 永久禁止
**Consequence**: A permanent ban from any sort of public interaction within
the community.
**社群影響：** 表現出違反社群標準的模式，包括持續的不當行為、騷擾個人，或對某類個人進行攻擊或貶低。
## Attribution
**後果：** 永久禁止在社群內進行任何形式的公開互動。
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
## 歸屬
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
本行為準則改編自 [Contributor Covenant][homepage] 2.1 版，可於 https://www.contributor-covenant.org/version/2/1/code_of_conduct.html 查閱。
社群影響指引參考了 [Mozilla 的行為準則執行階梯](https://github.com/mozilla/diversity)。
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
有關本行為準則常見問題的解答，請參閱 https://www.contributor-covenant.org/faq。翻譯版本可於 https://www.contributor-covenant.org/translations 查閱。

399
docs/i18n/zh-TW/CONTRIBUTING.md
View File

@@ -1,22 +1,20 @@
# Contributing to OmniRoute (中文 (繁體))
# 貢獻 OmniRoute (中文 (繁體))
🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md)
🌐 **語言:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md)
感謝您有興趣貢獻！本指南包含您入門所需的一切。
---
Thank you for your interest in contributing! This guide covers everything you need to get started.
## 開發環境設定
---
### 前置需求
## Development Setup
### Prerequisites
- **Node.js** >= 18 < 24 (recommended: 22 LTS)
- **Node.js** `>=22.22.3 <23`，或 `>=24.0.0 <27`（建議：24 LTS）
- **npm** 10+
- **Git**
### Clone & Install
### 複製與安裝
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -24,85 +22,109 @@ cd OmniRoute
npm install
```
### Environment Variables
### 環境變數
```bash
# Create your .env from the template
# 從範本建立您的 .env
cp .env.example .env
# Generate required secrets
# 產生所需的密鑰
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
```
Key variables for development:
開發用的關鍵變數：
| Variable | Development Default | Description |
| ---------------------- | ------------------------ | --------------------- |
| `PORT` | `20128` | Server port |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend |
| `JWT_SECRET` | (generate above) | JWT signing secret |
| `INITIAL_PASSWORD` | `CHANGEME` | First login password |
| `APP_LOG_LEVEL` | `info` | Log verbosity level |
| 變數 | 開發環境預設值 | 說明 |
| ---------------------- | ----------------------- | ------------------ |
| `PORT` | `20128` | 伺服器埠號 |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | 前端的基礎 URL |
| `JWT_SECRET` | （上方產生） | JWT 簽章密鑰 |
| `INITIAL_PASSWORD` | `CHANGEME` | 首次登入密碼 |
| `APP_LOG_LEVEL` | `info` | 日誌詳細程度 |
### Dashboard Settings
### 儀表板設定
The dashboard provides UI toggles for features that can also be configured via environment variables:
儀表板提供 UI 開關，可設定也能透過環境變數配置的功能：
| Setting Location | Toggle | Description |
| ------------------- | ------------------ | ------------------------------ |
| Settings → Advanced | Debug Mode | Enable debug request logs (UI) |
| Settings → General | Sidebar Visibility | Show/hide sidebar sections |
| 設定位置 | 開關 | 說明 |
| ------------------ | -------------- | ---------------------------- |
| 設定 → 進階 | 除錯模式 | 啟用除錯請求日誌（UI） |
| 設定 → 一般 | 側邊欄可見性 | 顯示/隱藏側邊欄區塊 |
These settings are stored in the database and persist across restarts, overriding env var defaults when set.
這些設定儲存在資料庫中，重新啟動後仍會保留，設定後會覆蓋環境變數的預設值。
### Running Locally
### 在本機執行
```bash
# Development mode (hot reload)
# 開發模式（熱載入）
npm run dev
# Production build
npm run build
# 生產建置
npm run build # next build → .build/next/ 然後 assembleStandalone → dist/
npm run start
# Common port configuration
# 發布建置（清除重建 + HEAD 哨兵 — 部署必用）
npm run build:release # rm -rf .build dist && 建置 + 寫入 dist/BUILD_SHA
# 常見埠號配置
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
```
Default URLs:
### 建置輸出結構
- **Dashboard**: `http://localhost:20128/dashboard`
- **API**: `http://localhost:20128/v1`
| 目錄 | 內容 | 版本追蹤 |
| ---------- | -------------------------------------------------- | -------- |
| `src/` | 應用程式原始碼（TypeScript / TSX） | 是 |
| `.build/` | 中間產物 — `next build` 輸出（gitignored，`distDir = .build/next`） | 否 |
| `dist/` | 可發佈套件 — 由 `assembleStandalone` 組裝（gitignored） | 否 |
建置管線為單次傳遞：
```
npm run build
└─ next build → .build/next/standalone （Next.js 輸出）
└─ assembleStandalone() （複製 standalone + static + public + 原生資源）
└─ 輸出: dist/ （server.js, .next/static/, public/, node_modules/）
```
`npm run build:release` 會額外先清除兩個目錄，然後寫入 `dist/BUILD_SHA`（= `git rev-parse --short HEAD`）作為部署完整性哨兵。
> **VPS 部署注意：** 遠端映像檔目錄 `/usr/lib/node_modules/omniroute/app/` 維持不變。部署技能會將 `dist/` 的內容 rsync 到其中。只有儲存庫內的建置輸出路徑改變了（`app/` → `dist/`）。
預設 URL：
- **儀表板**：`http://localhost:20128/dashboard`
- **API**：`http://localhost:20128/v1`
---
## Git Workflow
## Git 工作流程
> ⚠️ **NEVER commit directly to `main`.** Always use feature branches.
> ⚠️ **絕對不要直接提交到 `main`。** 一律使用功能分支。
```bash
git checkout -b feat/your-feature-name
# ... make changes ...
# ... 進行修改 ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# Open a Pull Request on GitHub
# 在 GitHub 上開啟 Pull Request
```
### Branch Naming
### 分支命名
| Prefix | Purpose |
| ----------- | ------------------------- |
| `feat/` | New features |
| `fix/` | Bug fixes |
| `refactor/` | Code restructuring |
| `docs/` | Documentation changes |
| `test/` | Test additions/fixes |
| `chore/` | Tooling, CI, dependencies |
| 前綴 | 用途 |
| ------------ | ---------------------- |
| `feat/` | 新功能 |
| `fix/` | 錯誤修正 |
| `refactor/` | 程式碼重構 |
| `docs/` | 文件變更 |
| `test/` | 測試新增/修正 |
| `chore/` | 工具、CI、依賴項目 |
### Commit Messages
### 提交訊息
Follow [Conventional Commits](https://www.conventionalcommits.org/):
遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
```
feat: add circuit breaker for provider calls
@@ -112,200 +134,233 @@ test: add observability unit tests
refactor(db): consolidate rate limit tables
```
Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.
範圍（v3.8）：`db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`、`cloud-agent`、`guardrails`、`compression`、`auto-combo`、`resilience`、`providers`、`executors`、`translator`、`domain`、`authz`。
---
## Running Tests
## 執行測試
```bash
# All tests (unit + vitest + ecosystem + e2e)
# 所有測試（單元 + vitest + 生態系 + e2e）
npm run test:all
# Single test file (Node.js native test runner — most tests use this)
# 單一測試檔案（Node.js 原生測試執行器 — 大部分測試使用此方式）
node --import tsx/esm --test tests/unit/your-file.test.ts
# Vitest (MCP server, autoCombo, cache)
# Vitest（MCP 伺服器、autoCombo、快取）
npm run test:vitest
# E2E tests (requires Playwright)
# E2E 測試（需要 Playwright）
npm run test:e2e
# Protocol clients E2E (MCP transports, A2A)
# 協定客戶端 E2E（MCP 傳輸、A2A）
npm run test:protocols:e2e
# Ecosystem compatibility tests
# 生態系相容性測試
npm run test:ecosystem
# Coverage (60% min statements/lines/functions/branches)
# 覆蓋率閘道：60% statements/lines/functions/branches
npm run test:coverage
npm run coverage:report
# Lint + format check
# Lint + 格式檢查
npm run lint
npm run check
# 實際上游 combo 冒煙測試（需要 VPS 存取 + 實際提供商額度）
# 會打到真實提供商 — 會花一點錢。絕對不會在 CI 中執行。沒有閘道時會乾淨地跳過。
# 需要：ssh root@192.168.0.15 存取（從 VPS 讀取唯讀資料庫快照）。
RUN_COMBO_LIVE=1 npm run test:combo:live
# Phase-3 VPS 實戰冒煙測試 — 純 Node ESM 腳本，直接打到 .15 伺服器。
# 需要：ssh root@192.168.0.15 存取（combo 透過 SSH sqlite 建立/刪除）。
# 會打到真實提供商（少量費用）。只會建立/刪除 __live_test__* combo。絕對不會在 CI 中執行。
# REQUIRE_API_KEY=false on .15 所以不需要 API 金鑰，但如果設定了 COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY 則會遵循。
npm run test:combo:live:vps # 7 個 HTTP 情境（priority/round-robin/weighted/cost/fusion/auto + health）
npm run test:combo:live:vps:failover # 增加實際跨提供商容錯情境（共 8 個）
```
Coverage notes:
覆蓋率注意事項：
- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
- Pull requests must keep the overall coverage gate at **60% or higher** for statements, lines, functions, and branches
- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must add or update automated tests in the same PR
- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
- `npm run test:coverage:legacy` preserves the older metric for historical comparison
- See `docs/ops/COVERAGE_PLAN.md` for the phased coverage improvement roadmap
- `npm run test:coverage` 測量主要單元測試套件的原始碼覆蓋率，排除 `tests/**`，包含 `open-sse/**`
- Pull Request 必須維持覆蓋率閘道在 **60%+** statements/lines/functions/branches
- 如果 PR 變更了 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的生產程式碼，必須在同一 PR 中新增或更新自動化測試
- `npm run coverage:report` 會列印最近一次覆蓋率執行的詳細逐檔案報告
- `npm run test:coverage:legacy` 保留舊版指標以供歷史比較
- 請參閱 `docs/ops/COVERAGE_PLAN.md` 了解階段性覆蓋率改善藍圖
### Pull Request Requirements
### Pull Request 需求
Before opening or merging a PR:
在開啟或合併 PR 之前：
- Run `npm run test:unit`
- Run `npm run test:coverage`
- Ensure the coverage gate stays at **60%+** for all metrics
- Include the changed or added test files in the PR description when production code changed
- Check the SonarQube result on the PR when the project secrets are configured in CI
- 執行 `npm run test:unit`
- 執行 `npm run test:coverage`
- 確保覆蓋率閘道維持在 **60%+** statements/lines/functions/branches
- 當生產程式碼變更時，在 PR 說明中包含已變更或新增的測試檔案
- 當 CI 中配置了專案密鑰時，檢查 PR 上的 SonarQube 結果
Current test status: **122 unit test files** covering:
目前測試狀態：**122 個單元測試檔案** 涵蓋：
- Provider translators and format conversion
- Rate limiting, circuit breaker, and resilience
- Semantic cache, idempotency, progress tracking
- Database operations and schema (21 DB modules)
- OAuth flows and authentication
- API endpoint validation (Zod v4)
- MCP server tools and scope enforcement
- Memory and Skills systems
- 提供商轉換器與格式轉換
- 速率限制、斷路器與彈性
- 語意快取、冪等性、進度追蹤
- 資料庫操作與結構（21 個 DB 模組）
- OAuth 流程與認證
- API 端點驗證（Zod v4）
- MCP 伺服器工具與範圍強制
- 記憶體與技能系統
---
## Code Style
## 程式碼風格
- **ESLint** — Run `npm run lint` before committing
- **Prettier** — Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas)
- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`)
- **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
- **Zod validation** — Use Zod v4 schemas for all API input validation
- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE
- **ESLint** — 提交前執行 `npm run lint`
- **Prettier** — 透過 `lint-staged` 在提交時自動格式化（2 空格、分號、雙引號、100 字元寬度、es5 尾逗號）
- **TypeScript** — 所有 `src/` 程式碼使用 `.ts`/`.tsx`；`open-sse/` 使用 `.ts`/`.js`；使用 TSDoc 撰寫文件（`@param`、`@returns`、`@throws`）
- **不使用 `eval()`** — ESLint 強制禁止 `no-eval`、`no-implied-eval`、`no-new-func`
- **Zod 驗證** — 所有 API 輸入驗證使用 Zod v4 結構
- **命名**：檔案 = camelCase/kebab-case，元件 = PascalCase，常數 = UPPER_SNAKE
---
## Project Structure
## 專案結構
```
src/ # TypeScript (.ts / .tsx)
├── app/ # Next.js 16 App Router
│ ├── (dashboard)/ # Dashboard pages (23 sections)
│ ├── api/ # API routes (51 directories)
│ └── login/ # Auth pages (.tsx)
├── domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.)
├── lib/ # Core business logic (.ts)
│ ├── a2a/ # Agent-to-Agent v0.3 protocol server
│ ├── acp/ # Agent Communication Protocol registry
│ ├── compliance/ # Compliance policy engine
│ ├── db/ # SQLite database layer (21 modules + 16 migrations)
│ ├── memory/ # Persistent conversational memory
│ ├── oauth/ # OAuth providers, services, and utilities
│ ├── skills/ # Extensible skill framework
│ ├── usage/ # Usage tracking and cost calculation
│ └── localDb.ts # Re-export layer only — never add logic here
├── middleware/ # Request middleware (promptInjectionGuard)
├── mitm/ # MITM proxy (cert, DNS, target routing)
│ ├── (dashboard)/ # 儀表板頁面（23 個區塊）
│ ├── api/ # API 路由（51 個目錄）
│ └── login/ # 認證頁面 (.tsx)
├── domain/ # 政策引擎（policyEngine、comboResolver、costRules 等）
├── lib/ # 核心業務邏輯 (.ts)
│ ├── a2a/ # Agent-to-Agent v0.3 協定伺服器
│ ├── acp/ # Agent 通訊協定註冊表
│ ├── compliance/ # 合規政策引擎
│ ├── db/ # SQLite 資料庫層（21 個模組 + 16 個遷移）
│ ├── memory/ # 持久對話記憶
│ ├── oauth/ # OAuth 提供商、服務與工具
│ ├── skills/ # 可擴展技能框架
│ ├── usage/ # 用量追蹤與成本計算
│ └── localDb.ts # 僅作為重新匯出層 — 永遠不要在此新增邏輯
├── middleware/ # 請求中介層（promptInjectionGuard）
├── mitm/ # MITM 代理（憑證、DNS、目標路由）
├── shared/
│ ├── components/ # React components (.tsx)
│ ├── constants/ # Provider definitions (60+), MCP scopes, routing strategies
│ ├── utils/ # Circuit breaker, sanitizer, auth helpers
│ └── validation/ # Zod v4 schemas
└── sse/ # SSE proxy pipeline
│ ├── components/ # React 元件 (.tsx)
│ ├── constants/ # 提供商定義（177）、MCP 範圍、14 種路由策略
│ ├── utils/ # 斷路器、清理工具、認證輔助
│ └── validation/ # Zod v4 結構
└── sse/ # SSE 代理管線
open-sse/ # @omniroute/open-sse workspace
├── executors/ # 14 provider-specific request executors
├── handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.)
├── mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes)
├── services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.)
├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/ # Responses API transformer
└── utils/ # 22 utility modules (stream, TLS, proxy, logging)
open-sse/ # @omniroute/open-sse 工作區
├── executors/ # 14 個提供商專用請求執行器
├── handlers/ # 11 個請求處理器（聊天、回應、嵌入、圖片等）
├── mcp-server/ # MCP 伺服器（25 個工具、3 種傳輸、10 個範圍）
├── services/ # 36+ 服務（combo、autoCombo、rateLimitManager 等）
├── translator/ # 格式轉換器（OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama）
├── transformer/ # Responses API 轉換器
└── utils/ # 22 個工具模組（串流、TLS、代理、日誌）
electron/ # Electron desktop app (cross-platform)
electron/ # Electron 桌面應用程式（跨平台）
tests/
├── unit/ # Node.js test runner (122 test files)
├── integration/ # Integration tests
├── e2e/ # Playwright tests
├── security/ # Security tests
├── translator/ # Translator-specific tests
└── load/ # Load tests
├── unit/ # Node.js 測試執行器（1,574 個測試檔案）
├── integration/ # 整合測試
├── e2e/ # Playwright 測試
├── security/ # 安全性測試
├── translator/ # 轉換器專用測試
└── load/ # 負載測試
docs/ # Documentation
├── ARCHITECTURE.md # System architecture
├── API_REFERENCE.md # All endpoints
├── USER_GUIDE.md # Provider setup, CLI integration
├── TROUBLESHOOTING.md # Common issues
├── MCP-SERVER.md # MCP server (25 tools)
├── A2A-SERVER.md # A2A agent protocol
├── AUTO-COMBO.md # Auto-combo engine
├── CLI-TOOLS.md # CLI tools integration
├── COVERAGE_PLAN.md # Test coverage improvement plan
├── openapi.yaml # OpenAPI specification
└── adr/ # Architecture Decision Records
docs/
├── adr/ # 架構決策記錄
├── architecture/ # 系統架構與彈性
├── comparison/ # OmniRoute 與替代方案比較
├── compression/ # 壓縮指南與規則
├── dev/ # 開發指南
├── diagrams/ # 架構圖
├── frameworks/ # MCP、A2A、OpenCode、記憶體、技能
├── guides/ # 使用者指南、Docker、設定、疑難排解
├── i18n/ # 國際化 README 翻譯
├── marketing/ # 行銷素材
├── ops/ # 部署、代理、覆蓋率、發布
├── providers/ # 提供商專用文件
├── reference/ # API 參考、環境變數、CLI 工具、免費方案
├── releases/ # 版本說明
├── routing/ # Auto-combo 引擎、推理重播
├── screenshots/ # 儀表板截圖
├── security/ # 護欄、合規、隱蔽、代幣
└── specs/ # 設計規格
```
---
## Adding a New Provider
## 新增提供商
### Step 1: Register Provider Constants
### 步驟 1：註冊提供商常數
Add to `src/shared/constants/providers.ts` — Zod-validated at module load.
新增至 `src/shared/constants/providers.ts` — 在模組載入時以 Zod 驗證。
### Step 2: Add Executor (if custom logic needed)
### 步驟 2：新增執行器（如果需要自訂邏輯）
Create executor in `open-sse/executors/your-provider.ts` extending the base executor.
在 `open-sse/executors/your-provider.ts` 中建立執行器，擴展基礎執行器。
### Step 3: Add Translator (if non-OpenAI format)
### 步驟 3：新增轉換器（若非 OpenAI 格式）
Create request/response translators in `open-sse/translator/`.
在 `open-sse/translator/` 中建立請求/回應轉換器。
### Step 4: Add OAuth Config (if OAuth-based)
### 步驟 4：新增 OAuth 設定（若基於 OAuth）
Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`.
在 `src/lib/oauth/constants/oauth.ts` 中新增 OAuth 憑證，並在 `src/lib/oauth/services/` 中新增服務。
### Step 5: Register Models
如果上游提供商在其公開 CLI / 瀏覽器套件中分發了公開的 OAuth client_id/secret 或 Firebase Web API 金鑰，**請勿**將其嵌入為字串字面值。請使用 `open-sse/utils/publicCreds.ts` 中的 `resolvePublicCred()`，並在 `EMBEDDED_DEFAULTS` 中新增一個遮罩位元組條目。完整的強制性工作流程記錄於 [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)。
Add model definitions in `open-sse/config/providerRegistry.ts`.
在處理器/執行器內部，傳送到客戶端的錯誤訊息必須通過 `open-sse/utils/error.ts` 的 `buildErrorBody()` / `sanitizeErrorMessage()` — 絕對不要將原始 `err.stack` 或 `err.message` 放入回應主體。請參閱 [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md)。
### Step 6: Add Tests
### 步驟 5：註冊模型
Write unit tests in `tests/unit/` covering at minimum:
在 `open-sse/config/providerRegistry.ts` 中新增模型定義。
- Provider registration
- Request/response translation
- Error handling
### 步驟 6：新增測試
在 `tests/unit/` 中撰寫單元測試，至少涵蓋：
- 提供商註冊
- 請求/回應轉換
- 錯誤處理
---
## Pull Request Checklist
## Pull Request 檢查清單
- [ ] Tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Build succeeds (`npm run build`)
- [ ] TypeScript types added for new public functions and interfaces
- [ ] No hardcoded secrets or fallback values
- [ ] All inputs validated with Zod schemas
- [ ] CHANGELOG updated (if user-facing change)
- [ ] Documentation updated (if applicable)
- [ ] 測試通過（`npm test`）
- [ ] Linting 通過（`npm run lint`）
- [ ] 建置成功（`npm run build`）
- [ ] 為新的公開函數和介面新增 TypeScript 型別
- [ ] 無硬編碼密鑰或後備值
- [ ] 公開上游憑證透過 `resolvePublicCred()` 嵌入（參見 [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)），而非以字面值嵌入
- [ ] 錯誤回應通過 `buildErrorBody()` / `sanitizeErrorMessage()` 路由 — 回應主體中無原始堆疊追蹤（參見 [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md)）
- [ ] Shell 命令（`exec` / `spawn`）透過 `env` 傳遞執行時期值，而非透過字串插值
- [ ] 所有輸入以 Zod 結構驗證
- [ ] 針對使用者可見的變更，在 `changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md` 下新增 **Changelog 片段**（參見 [`changelog.d/README.md`](./changelog.d/README.md)）— 請**勿**直接編輯 `CHANGELOG.md`；片段會在發布時彙總，且絕不會在 PR 之間衝突
- [ ] 文件已更新（如適用）
- [ ] 無新增的 CodeQL / 密碼掃描警報，或每個警報已附上技術理由並參考相關 `docs/security/` 文件
- [ ] 啟動子處理程序的路由（`/api/mcp/`、`/api/cli-tools/runtime/`）在 `src/server/authz/routeGuard.ts` 中分類為 `isLocalOnlyPath()` — 參見 [硬規則第 15 條](docs/security/ROUTE_GUARD_TIERS.md)
- [ ] 提交訊息中無 `Co-Authored-By` 尾綴 — 提交必須僅以儲存庫擁有者的 Git 身分出現（硬規則第 16 條）
---
## Releasing
## 發布
Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
發布透過 `/generate-release` 工作流程管理。當建立新的 GitHub Release 時，套件會透過 GitHub Actions **自動發布到 npm**。
對於 VPS 部署，請使用 `npm run build:release`（而非 `npm run build`）— 它會執行清除重建，將套件組裝到 `dist/`，並寫入 `dist/BUILD_SHA` 哨兵。然後使用 `/deploy-vps-*-cc` 技能，這些技能會將 `dist/` rsync 到遠端 `app/` 目錄。
---
## Getting Help
## 取得協助
- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)
- **API Reference**: See [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md)
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **ADRs**: See `docs/adr/` for architectural decision records
- **架構**：參見 [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)
- **API 參考**：參見 [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md)
- **安全文件**：[`docs/security/CLI_TOKEN.md`](docs/security/CLI_TOKEN.md)、[`docs/security/ROUTE_GUARD_TIERS.md`](docs/security/ROUTE_GUARD_TIERS.md)、[`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md)、[`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)
- **運維文件**：[`docs/ops/SQLITE_RUNTIME.md`](docs/ops/SQLITE_RUNTIME.md)
- **問題回報**：[github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **ADR**：參見 `docs/adr/` 了解架構決策記錄

57
docs/i18n/zh-TW/GEMINI.md
View File

@@ -1,25 +1,50 @@
# Security and Cleanliness Rules for AI Assistants (中文 (繁體))
# AI 助手的安全與整潔規則
🌐 **Languages:** 🇺🇸 [English](../../../GEMINI.md) · 🇸🇦 [ar](../ar/GEMINI.md) · 🇧🇬 [bg](../bg/GEMINI.md) · 🇧🇩 [bn](../bn/GEMINI.md) · 🇨🇿 [cs](../cs/GEMINI.md) · 🇩🇰 [da](../da/GEMINI.md) · 🇩🇪 [de](../de/GEMINI.md) · 🇪🇸 [es](../es/GEMINI.md) · 🇮🇷 [fa](../fa/GEMINI.md) · 🇫🇮 [fi](../fi/GEMINI.md) · 🇫🇷 [fr](../fr/GEMINI.md) · 🇮🇳 [gu](../gu/GEMINI.md) · 🇮🇱 [he](../he/GEMINI.md) · 🇮🇳 [hi](../hi/GEMINI.md) · 🇭🇺 [hu](../hu/GEMINI.md) · 🇮🇩 [id](../id/GEMINI.md) · 🇮🇹 [it](../it/GEMINI.md) · 🇯🇵 [ja](../ja/GEMINI.md) · 🇰🇷 [ko](../ko/GEMINI.md) · 🇮🇳 [mr](../mr/GEMINI.md) · 🇲🇾 [ms](../ms/GEMINI.md) · 🇳🇱 [nl](../nl/GEMINI.md) · 🇳🇴 [no](../no/GEMINI.md) · 🇵🇭 [phi](../phi/GEMINI.md) · 🇵🇱 [pl](../pl/GEMINI.md) · 🇵🇹 [pt](../pt/GEMINI.md) · 🇧🇷 [pt-BR](../pt-BR/GEMINI.md) · 🇷🇴 [ro](../ro/GEMINI.md) · 🇷🇺 [ru](../ru/GEMINI.md) · 🇸🇰 [sk](../sk/GEMINI.md) · 🇸🇪 [sv](../sv/GEMINI.md) · 🇰🇪 [sw](../sw/GEMINI.md) · 🇮🇳 [ta](../ta/GEMINI.md) · 🇮🇳 [te](../te/GEMINI.md) · 🇹🇭 [th](../th/GEMINI.md) · 🇹🇷 [tr](../tr/GEMINI.md) · 🇺🇦 [uk-UA](../uk-UA/GEMINI.md) · 🇵🇰 [ur](../ur/GEMINI.md) · 🇻🇳 [vi](../vi/GEMINI.md) · 🇨🇳 [zh-CN](../zh-CN/GEMINI.md)
> **適用範圍：** 基於 Gemini 的代理規則。若為 Claude Code，請見 `CLAUDE.md`。若為其他 AI 助手，請見 `AGENTS.md`。
---
## 1. 檔案放置與組織
## 1. File Placement & Organization
- **測試檔案**：所有單元測試、整合測試、生態系測試或 Vitest 檔案，**必須**嚴格放置在 `tests/` 目錄內（例如 `tests/unit/`、`tests/integration/`）。**嚴禁**在專案根目錄（`/`）建立測試檔案。
- **腳本與工具**：所有維護、除錯、產生或實驗性腳本（`.cjs`、`.mjs`、`.js`、`.ts`）**必須**嚴格放置在 `scripts/` 子資料夾之一（`build/`、`dev/`、`check/`、`docs/`、`i18n/`、`ad-hoc/`）。一次性或實驗性程式碼請置於 `scripts/ad-hoc/` 下。**嚴禁**將腳本任意散落在專案根目錄（`/`）或 `scripts/` 頂層資料夾。
- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).
- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside the `scripts/` directory or `scripts/scratch/` for temporary one-offs. NEVER dump loose scripts in the project root (`/`).
**專案根目錄僅能包含：**
**The Project Root MUST ONLY CONTAIN:**
- 設定檔（`vitest.config.ts`、`next.config.mjs`、`eslint.config.mjs`、`tsconfig*.json`、`playwright.config.ts`、`prettier.config.mjs`、`postcss.config.mjs`、`sonar-project.properties`、`fly.toml`、`docker-compose*.yml`、`Dockerfile`）
- 相依性檔案（`package.json`、`package-lock.json`）
- 文件檔案（`README.md`、`CHANGELOG.md`、`LICENSE`、`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`、`llm.txt`、`Tuto_Qdrant.md`）
- CI/CD 檔案與忽略定義（`.gitignore`、`.dockerignore`、`.npmignore`、`.npmrc`、`.node-version`、`.nvmrc`、`.env.example`）
- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
- Dependency files (`package.json`, `package-lock.json`)
- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
當建立**任何**驗證測試或一次性邏輯腳本時，請根據您的目標預設使用 `scripts/ad-hoc/` 或 `tests/unit/` 目錄。請勿汙染 `／` 根目錄上下文。
When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
## 2. 嚴格規則（與 `CLAUDE.md` 對應）
## 2. VPS Dashboard Credentials
1. **絕不提交機密或憑證。** 使用 `.env`（從 `.env.example` 自動產生）或密碼保管庫。密碼、OAuth 密鑰、API 金鑰和 Cookie 值**不得**出現在已提交的檔案中。
2. **絕不向 `src/lib/localDb.ts` 添加邏輯。** 該檔案僅作為重新匯出的統合點（barrel）。
3. **絕不使用 `eval()`、`new Function()` 或任何隱含的 eval。** ESLint 已強制執行此規則。
4. **絕不直接提交至 `main`。** 請使用 `feat/`、`fix/`、`refactor/`、`docs/`、`test/` 或 `chore/` 分支。
5. **絕不在路由中撰寫原始 SQL** — 一律透過 `src/lib/db/` 領域模組操作。
6. **絕不靜默吞沒 SSE 串流中的錯誤** — 應傳遞錯誤或乾淨地中止串流。
7. **絕不繞過 Husky 鉤子**（`--no-verify`、`--no-gpg-sign`），除非獲得操作人員明確許可。
8. **一律使用 `src/shared/validation/schemas.ts` 中的 Zod 綱要驗證輸入。**
9. **修改生產程式碼（`src/`、`open-sse/`、`electron/`、`bin/`）時，一律同時添加測試。**
10. **覆蓋率必須維持** ≥ 75% 陳述式 / 75% 行 / 75% 函式 / 70% 分支（實際測量值約 82%）。
| Environment | URL | Password |
| ----------- | ------------------------- | -------- |
| Local VPS | http://192.168.0.15:20128 | 123456 |
## 3. 程式碼庫導航
| 任務 | 請先閱讀此文件 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 理解程式碼庫 | `docs/architecture/REPOSITORY_MAP.md` |
| 架構概覽 | `docs/architecture/ARCHITECTURE.md` |
| 工程參考 | `docs/architecture/CODEBASE_DOCUMENTATION.md` |
| 添加功能 | `CONTRIBUTING.md` + 對應的 `docs/<領域>.md` |
| 各領域深入探索 | `docs/frameworks/SKILLS.md`、`docs/frameworks/MEMORY.md`、`docs/frameworks/EVALS.md`、`docs/security/GUARDRAILS.md`、`docs/security/COMPLIANCE.md`、`docs/frameworks/CLOUD_AGENT.md`、`docs/frameworks/MCP-SERVER.md`、`docs/frameworks/A2A-SERVER.md`、`docs/architecture/AUTHZ_GUIDE.md`、`docs/architecture/RESILIENCE_GUIDE.md`、`docs/routing/AUTO-COMBO.md`、`docs/frameworks/WEBHOOKS.md`、`docs/routing/REASONING_REPLAY.md`、`docs/security/STEALTH_GUIDE.md`、`docs/ops/TUNNELS_GUIDE.md`、`docs/guides/ELECTRON_GUIDE.md`、`docs/reference/PROVIDER_REFERENCE.md` |
| 發布流程 | `docs/ops/RELEASE_CHECKLIST.md` |
## 4. 本地開發環境存取
儀表板可透過操作人員選擇的 URL／連接埠存取（預設 `http://localhost:20128`）。憑證為操作人員專屬：
- **初始管理員密碼**取自首次安裝時的 `INITIAL_PASSWORD` 環境變數（`.env.example` 中預設為 `CHANGEME`；請在首次登入後立即更換）。
- **本地 VPS／共享開發環境**：請向操作人員索取 URL 與當前憑證——這些資訊保存在操作人員的個人密碼保管庫中，**不在**此儲存庫內。
> 若本檔案舊版中曾出現任何憑證，均為非正式環境的示範值；請將其視為已洩漏，切勿重複使用。

255
docs/i18n/zh-TW/SECURITY.md
View File

@@ -1,159 +1,172 @@
# Security Policy (中文 (繁體))
# 安全性政策
🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇧🇩 [bn](../bn/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇮🇷 [fa](../fa/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇮🇳 [gu](../gu/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇮🇳 [mr](../mr/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇰🇪 [sw](../sw/SECURITY.md) · 🇮🇳 [ta](../ta/SECURITY.md) · 🇮🇳 [te](../te/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇵🇰 [ur](../ur/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md)
## 回報漏洞
---
如果您在 OmniRoute 中發現安全漏洞，請以負責任的方式回報：
## Reporting Vulnerabilities
1. **請勿**在 GitHub 上建立公開 Issue
2. 請使用 [GitHub 安全性公告](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
3. 內容需包含：說明、重現步驟及潛在影響
If you discover a security vulnerability in OmniRoute, please report it responsibly:
## 回應時程
1. **DO NOT** open a public GitHub issue
2. Use [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
3. Include: description, reproduction steps, and potential impact
## Response Timeline
| Stage | Target |
| 階段 | 目標 |
| ------------------- | --------------------------- |
| Acknowledgment | 48 hours |
| Triage & Assessment | 5 business days |
| Patch Release | 14 business days (critical) |
| 確認收件 | 48 小時 |
| 分類與評估 | 5 個工作日 |
| 修補程式發布 | 14 個工作日（重大漏洞） |
## Supported Versions
## 支援版本
| Version | Support Status |
| 版本 | 支援狀態 |
| ------- | -------------- |
| 3.6.x | ✅ Active |
| 3.5.x | ✅ Security |
| < 3.5.0 | ❌ Unsupported |
| 3.8.x | ✅ 積極維護中 |
| 3.7.x | ✅ 安全性更新 |
| < 3.7.0 | ❌ 不再支援 |
---
## Security Architecture
## 安全架構
OmniRoute implements a multi-layered security model:
OmniRoute 採用多層式安全模型：
```
Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider
請求 → CORS → 授權管道（分類 → 政策 → 強制執行）
→ 防護欄（PII 遮罩、提示注入、視覺橋接）
→ 速率限制器 → 斷路器 → 冷卻 → 模型鎖定 → 提供者
```
### 🔐 Authentication & Authorization
### 🔐 身分驗證與授權
| Feature | Implementation |
| -------------------- | ---------------------------------------------------------- |
| **Dashboard Login** | Password-based auth with JWT tokens (HttpOnly cookies) |
| **API Key Auth** | HMAC-signed keys with CRC validation |
| **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) |
| **Token Refresh** | Automatic OAuth token refresh before expiry |
| **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments |
| **MCP Scopes** | 10 granular scopes for MCP tool access control |
| 功能 | 實作方式 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **儀表板登入** | 基於密碼的身分驗證，搭配 JWT Token（HttpOnly Cookie） |
| **API 金鑰驗證** | HMAC 簽署金鑰搭配 CRC 驗證 |
| **OAuth 2.0 + PKCE** | 13 個提供者（Claude、Codex、GitHub、Cursor、Antigravity、Gemini、Kimi Coding、Kilo Code、Cline、Kiro、Qoder、Windsurf、GitLab Duo） |
| **Token 更新** | 自動在 OAuth Token 到期前進行更新 |
| **安全 Cookie** | 在 HTTPS 環境下設定 `AUTH_COOKIE_SECURE=true` |
| **授權管道** | 路由分類（PUBLIC / CLIENT_API / MANAGEMENT）— 請參閱 `docs/architecture/AUTHZ_GUIDE.md` |
| **路由防護層級** | 管理路由採三層模型（LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT）— 請參閱 `docs/security/ROUTE_GUARD_TIERS.md` |
| **管理範圍 MCP** | 遠端 `/api/mcp/*` 存取需透過具備 `manage` 範圍的 API 金鑰控管；`/api/cli-tools/runtime/*` 維持嚴格的迴路限制。詳見 ROUTE_GUARD_TIERS |
| **MCP 範圍** | 約 13 個細粒度範圍（read:health、write:combos、execute:completions 等）— 請參閱 `docs/frameworks/MCP-SERVER.md` |
### 🛡️ Encryption at Rest
### 🛡️ 靜態資料加密
All sensitive data stored in SQLite is encrypted using **AES-256-GCM** with scrypt key derivation:
所有儲存於 SQLite 的敏感資料皆使用 **AES-256-GCM** 搭配 scrypt 金鑰推導進行加密：
- API keys, access tokens, refresh tokens, and ID tokens
- Versioned format: `enc:v1:<iv>:<ciphertext>:<authTag>`
- Passthrough mode (plaintext) when `STORAGE_ENCRYPTION_KEY` is not set
- API 金鑰、存取 Token、更新 Token 及身分 Token
- 版本化格式：`enc:v1:<iv>:<ciphertext>:<authTag>`
- 若未設定 `STORAGE_ENCRYPTION_KEY`，則以純文字模式（passthrough）運作
```bash
# Generate encryption key:
# 產生加密金鑰：
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
```
### 🧠 Prompt Injection Guard
### 🛡️ 防護欄框架
Middleware that detects and blocks prompt injection attacks in LLM requests:
OmniRoute 提供可熱重載的**防護欄註冊表**（`src/lib/guardrails/`），內建 3 道依優先順序排列的防護欄：
| Pattern Type | Severity | Example |
| 防護欄 | 優先順序 | 目的 |
| ------------------ | -------- | -------------------------------------------------------------------------------------- |
| `vision-bridge` | 5 | 為非視覺模型橋接具備影像識別的描述；防範圖片 URL 的 SSRF 攻擊 |
| `pii-masker` | 10 | 呼叫前後進行 PII 遮罩（電子郵件、電話、CPF、CNPJ、信用卡、SSN） |
| `prompt-injection` | 20 | 偵測覆寫／角色劫持／越獄／洩漏模式 |
自訂防護欄可透過 `registerGuardrail(new MyGuardrail())` 註冊。此模型為故障開放（fail-open）設計（異常不會阻斷流量）。可透過 `x-omniroute-disabled-guardrails` 標頭在單次請求中選擇停用。→ 詳見 [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)。
### 🧠 提示注入防護
偵測並阻擋 LLM 請求中的提示注入攻擊的中介軟體：
| 模式類型 | 嚴重性 | 範例 |
| ------------------- | -------- | ---------------------------------------------- |
| System Override | High | "ignore all previous instructions" |
| Role Hijack | High | "you are now DAN, you can do anything" |
| Delimiter Injection | Medium | Encoded separators to break context boundaries |
| DAN/Jailbreak | High | Known jailbreak prompt patterns |
| Instruction Leak | Medium | "show me your system prompt" |
| 系統指令覆寫 | 高 | 「忽略所有先前的指令」 |
| 角色劫持 | 高 | 「你現在是 DAN，你可以做任何事」 |
| 分隔符號注入 | 中 | 編碼後的分隔符，用以破壞上下文邊界 |
| DAN／越獄 | 高 | 已知的越獄提示模式 |
| 指令洩漏 | 中 | 「顯示你的系統提示詞」 |
Configure via dashboard (Settings → Security) or `.env`:
可透過儀表板（設定 → 安全性）或 `.env` 進行設定：
```env
INPUT_SANITIZER_ENABLED=true
INPUT_SANITIZER_MODE=block # warn | block | redact
```
### 🔒 PII Redaction
### 🔒 PII 遮罩處理
Automatic detection and optional redaction of personally identifiable information:
自動偵測並選擇性遮蔽個人識別資訊：
| PII Type | Pattern | Replacement |
| ------------- | --------------------- | ------------------ |
| Email | `user@domain.com` | `[EMAIL_REDACTED]` |
| CPF (Brazil) | `123.456.789-00` | `[CPF_REDACTED]` |
| CNPJ (Brazil) | `12.345.678/0001-00` | `[CNPJ_REDACTED]` |
| Credit Card | `4111-1111-1111-1111` | `[CC_REDACTED]` |
| Phone | `+55 11 99999-9999` | `[PHONE_REDACTED]` |
| SSN (US) | `123-45-6789` | `[SSN_REDACTED]` |
| PII 類型 | 模式 | 取代內容 |
| ------------- | --------------------- | ------------------ |
| 電子郵件 | `user@domain.com` | `[EMAIL_REDACTED]` |
| CPF（巴西） | `123.456.789-00` | `[CPF_REDACTED]` |
| CNPJ（巴西） | `12.345.678/0001-00` | `[CNPJ_REDACTED]` |
| 信用卡 | `4111-1111-1111-1111` | `[CC_REDACTED]` |
| 電話 | `+55 11 99999-9999` | `[PHONE_REDACTED]` |
| SSN（美國） | `123-45-6789` | `[SSN_REDACTED]` |
```env
PII_REDACTION_ENABLED=true
```
### 🌐 Network Security
### 🌐 網路安全
| Feature | Description |
| ------------------------ | ---------------------------------------------------------------- |
| **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
| **IP Filtering** | Allowlist/blocklist IP ranges in dashboard |
| **Rate Limiting** | Per-provider rate limits with automatic backoff |
| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s |
| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection |
| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures |
| 功能 | 說明 |
| ------------------------ | ------------------------------------------------------------------------------ |
| **CORS** | 明確的跨域白名單（`CORS_ALLOWED_ORIGINS`；舊版為 `CORS_ORIGIN`） |
| **IP 過濾** | 在儀表板中設定允許／封鎖的 IP 範圍 |
| **速率限制** | 依提供者設定的速率限制，搭配自動退避機制 |
| **防驚群效應** | 互斥鎖＋連線層級鎖定，防止連鎖 502 錯誤 |
| **TLS 指紋** | 模擬瀏覽器風格的 TLS 指紋，降低機器人偵測率 |
| **CLI 指紋** | 依提供者調整標頭／主體順序，以符合原生 CLI 簽章 |
### 🔌 Resilience & Availability
### 🔌 韌性與可用性
| Feature | Description |
| ----------------------- | ------------------------------------------------------------------ |
| **Circuit Breaker** | 3-state (Closed → Open → Half-Open) per provider, SQLite-persisted |
| **Request Idempotency** | 5-second dedup window for duplicate requests |
| **Exponential Backoff** | Automatic retry with increasing delays |
| **Health Dashboard** | Real-time provider health monitoring |
| 功能 | 說明 |
| ----------------------- | ------------------------------------------------------------- |
| **斷路器** | 三種狀態（關閉 → 開啟 → 半開），依提供者設定，持久化至 SQLite |
| **請求冪等性** | 5 秒內重複請求去重視窗 |
| **指數退避** | 自動重試，延遲時間逐步增加 |
| **健康狀態儀表板** | 即時提供者健康狀態監控 |
### 📋 Compliance
### 📋 法規遵循
| Feature | Description |
| ------------------ | ----------------------------------------------------------- |
| **Log Retention** | Automatic cleanup after `CALL_LOG_RETENTION_DAYS` |
| **No-Log Opt-out** | Per API key `noLog` flag disables request logging |
| **Audit Log** | Administrative actions tracked in `audit_log` table |
| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls |
| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load |
| 功能 | 說明 |
| ------------------ | --------------------------------------------------- |
| **日誌保留** | 依 `CALL_LOG_RETENTION_DAYS` 設定自動清理 |
| **不紀錄選擇退出** | 可為每個 API 金鑰設定 `noLog` 標記以停用請求記錄 |
| **稽核日誌** | 管理操作記錄在 `audit_log` 資料表中 |
| **MCP 稽核** | 以 SQLite 為基礎的稽核記錄，涵蓋所有 MCP 工具呼叫 |
| **Zod 驗證** | 所有 API 輸入皆在模組載入時以 Zod v4 綱要進行驗證 |
---
## Required Environment Variables
## 必要的環境變數
All secrets must be set before starting the server. The server will **fail fast** if they are missing or weak.
所有機密資訊必須在啟動伺服器前設定完成。若缺少或強度不足，伺服器將**快速失敗（fail fast）**。
```bash
# REQUIRED — server will not start without these:
JWT_SECRET=$(openssl rand -base64 48) # min 32 chars
API_KEY_SECRET=$(openssl rand -hex 32) # min 16 chars
# 必要項目 — 未設定則無法啟動伺服器：
JWT_SECRET=$(openssl rand -base64 48) # 最少 32 個字元
API_KEY_SECRET=$(openssl rand -hex 32) # 最少 16 個字元
# RECOMMENDED — enables encryption at rest:
# 建議設定 — 啟用靜態資料加密：
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
```
The server actively rejects known-weak values like `changeme`, `secret`, or `password`.
伺服器會主動拒絕已知的弱值，例如 `changeme`、`secret` 或 `password`。
---
## Docker Security
## Docker 安全
- Use non-root user in production
- Mount secrets as read-only volumes
- Never copy `.env` files into Docker images
- Use `.dockerignore` to exclude sensitive files
- Set `AUTH_COOKIE_SECURE=true` when behind HTTPS
- 在正式環境中使用非 root 使用者
- 將機密檔案以唯讀磁區掛載
- 切勿將 `.env` 檔案複製到 Docker 映像檔中
- 使用 `.dockerignore` 排除敏感檔案
- 在 HTTPS 環境下設定 `AUTH_COOKIE_SECURE=true`
```bash
docker run -d \
@@ -170,10 +183,52 @@ docker run -d \
---
## Dependencies
## 相依套件
- Run `npm audit` regularly
- Keep dependencies updated
- The project uses `husky` + `lint-staged` for pre-commit checks
- CI pipeline runs ESLint security rules on every push
- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
- 定期執行 `npm audit`（`npm run audit:deps` 涵蓋主程式 + Electron）
- 保持相依套件更新
- 本專案使用 `husky` + `lint-staged` 進行提交前檢查（lint-staged + check-docs-sync + check:any-budget:t11）
- CI 管線每次推送時皆執行 ESLint 安全規則（`no-eval`、`no-implied-eval`、`no-new-func` 設為 error）
- 提供者常數在模組載入時經由 Zod 進行驗證（`src/shared/validation/schemas.ts`）
- 使用預設安全的程式庫：`dompurify` / `isomorphic-dompurify`（XSS 防護）、`jose`（JWT）、`better-sqlite3`（透過參數化查詢消除 SQLi 風險）、`bcryptjs`（密碼雜湊）
## 嚴格安全規則
以下規則由工具與審查人員強制執行：
1. **絕不提交機密資訊** — `.env` 已加入 .gitignore；`.env.example` 為範本（不含實際值，僅含註解 — 詳見下方的 PUBLIC_CREDS.md）
2. **絕不使用 `eval()`、`new Function()` 或隱含 eval** — ESLint 強制執行
3. **絕不繞過 Husky 掛鉤**（`--no-verify`、`--no-gpg-sign`），除非取得操作人員明確核准
4. **絕不在路由中撰寫原始 SQL** — 一律透過 `src/lib/db/`（參數化查詢）
5. **一律使用 Zod 驗證輸入** — `src/shared/validation/schemas.ts`
6. **一律淨化上游標頭** — 黑名單定義於 `src/shared/constants/upstreamHeaders.ts`
7. **靜態加密憑證** — 透過 `src/lib/db/encryption.ts` 使用 AES-256-GCM
8. **透過 `resolvePublicCred()` 公開上游 OAuth 識別碼** — 切勿在原始碼中寫入 `AIza…` / `GOCSPX-…` / `…apps.googleusercontent.com` 字面值。詳見 [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)
9. **透過 `buildErrorBody()` / `sanitizeErrorMessage()` 回傳錯誤回應** — 切勿將原始的 `err.stack` / `err.message` 放入 HTTP / SSE / executor / MCP 回應主體。詳見 [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md)
10. **`exec()` / `spawn()` 的執行期值應透過 `env` 選項傳遞** — 切勿將外部路徑或不可信賴的值以字串插值方式嵌入 shell 傳遞的腳本中。參考：`src/mitm/cert/install.ts::updateNssDatabases`
11. **優先選用預設安全的程式庫** — 請參閱 [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。在自行實作前優先考慮使用這些套件。
## 供應鏈掃描器發現（Socket.dev / Snyk 等）
已發布的 `omniroute` npm 成品（artifact）採用了 Next.js `output: "standalone"` 建置方式，這表示所有的路由處理器 — 包括已記載的特權功能（MITM、Zed 匯入、Cloud Sync、嵌入式服務監督程式）— 最終都會以壓縮後的 chunk 形式存在於 `.next/server/*.js` 中。啟發式供應鏈掃描器經常會將這些 chunk 比對為惡意軟體特徵。
針對每一項發現類別，我們都保留了一份每項發現對應的維護者證明文件：
- **[`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)** —
逐項發現對照表：原始檔 ↔ 被標記的 chunk ↔ 行為 ↔ 在 v3.8.6 中採取的緩解措施
- 每個被標記的函式點皆以原始碼內的 `SECURITY-AUDITOR-NOTE:` 區塊連結回同一份文件。
對於管線無法放寬此警示的使用者，可以使用 `OMNIROUTE_BUILD_PROFILE=minimal npm run build` 進行建置。該方式會將四個敏感模組替換為執行期回傳 HTTP 503 `feature-disabled` 的樁程式（stub），使特權程式碼路徑從套件中完全移除。發布方式請參閱 [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)。
## 參考資料
- [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — 授權管線
- [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — 防護欄框架
- [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — 稽核日誌與保留政策
- [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) — **必要**：公開上游憑證模式
- [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md) — **必要**：錯誤回應處理模式
- [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md) — 供應鏈掃描器發現的維護者證明文件
- [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — 斷路器 + 冷卻 + 鎖定
- [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS 指紋辨識（法律／倫理聲明）
- [`CLAUDE.md`](CLAUDE.md) — AI Agent 的嚴格規則
- [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — 精選預設安全程式庫清單

1332
docs/i18n/zh-TW/docs/architecture/ARCHITECTURE.md
View File

File diff suppressed because it is too large Load Diff

1291
docs/i18n/zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md
View File

File diff suppressed because it is too large Load Diff

132
docs/i18n/zh-TW/docs/cloudflare-zero-trust-guide.md
View File

@@ -1,106 +1,106 @@
# Guia Completo: Cloudflare Tunnel & Zero Trust (Split-Port) (中文（簡體）)
# 完整指南：Cloudflare Tunnel 與 Zero Trust (Split-Port) (中文（繁體）)
🌐 **Languages:** 🇺🇸 [English](../../../../docs/cloudflare-zero-trust-guide.md) · 🇪🇸 [es](../../es/docs/cloudflare-zero-trust-guide.md) · 🇫🇷 [fr](../../fr/docs/cloudflare-zero-trust-guide.md) · 🇩🇪 [de](../../de/docs/cloudflare-zero-trust-guide.md) · 🇮🇹 [it](../../it/docs/cloudflare-zero-trust-guide.md) · 🇷🇺 [ru](../../ru/docs/cloudflare-zero-trust-guide.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/cloudflare-zero-trust-guide.md) · 🇯🇵 [ja](../../ja/docs/cloudflare-zero-trust-guide.md) · 🇰🇷 [ko](../../ko/docs/cloudflare-zero-trust-guide.md) · 🇸🇦 [ar](../../ar/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [hi](../../hi/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [in](../../in/docs/cloudflare-zero-trust-guide.md) · 🇹🇭 [th](../../th/docs/cloudflare-zero-trust-guide.md) · 🇻🇳 [vi](../../vi/docs/cloudflare-zero-trust-guide.md) · 🇮🇩 [id](../../id/docs/cloudflare-zero-trust-guide.md) · 🇲🇾 [ms](../../ms/docs/cloudflare-zero-trust-guide.md) · 🇳🇱 [nl](../../nl/docs/cloudflare-zero-trust-guide.md) · 🇵🇱 [pl](../../pl/docs/cloudflare-zero-trust-guide.md) · 🇸🇪 [sv](../../sv/docs/cloudflare-zero-trust-guide.md) · 🇳🇴 [no](../../no/docs/cloudflare-zero-trust-guide.md) · 🇩🇰 [da](../../da/docs/cloudflare-zero-trust-guide.md) · 🇫🇮 [fi](../../fi/docs/cloudflare-zero-trust-guide.md) · 🇵🇹 [pt](../../pt/docs/cloudflare-zero-trust-guide.md) · 🇷🇴 [ro](../../ro/docs/cloudflare-zero-trust-guide.md) · 🇭🇺 [hu](../../hu/docs/cloudflare-zero-trust-guide.md) · 🇧🇬 [bg](../../bg/docs/cloudflare-zero-trust-guide.md) · 🇸🇰 [sk](../../sk/docs/cloudflare-zero-trust-guide.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/cloudflare-zero-trust-guide.md) · 🇮🇱 [he](../../he/docs/cloudflare-zero-trust-guide.md) · 🇵🇭 [phi](../../phi/docs/cloudflare-zero-trust-guide.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/cloudflare-zero-trust-guide.md) · 🇨🇿 [cs](../../cs/docs/cloudflare-zero-trust-guide.md) · 🇹🇷 [tr](../../tr/docs/cloudflare-zero-trust-guide.md)
🌐 **Languages:** 🇺🇸 [English](../../../../docs/cloudflare-zero-trust-guide.md) · 🇪🇸 [es](../../es/docs/cloudflare-zero-trust-guide.md) · 🇫🇷 [fr](../../fr/docs/cloudflare-zero-trust-guide.md) · 🇩🇪 [de](../../de/docs/cloudflare-zero-trust-guide.md) · 🇮🇹 [it](../../it/docs/cloudflare-zero-trust-guide.md) · 🇷🇺 [ru](../../ru/docs/cloudflare-zero-trust-guide.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/cloudflare-zero-trust-guide.md) · 🇹🇼 [zh-TW](../../zh-TW/docs/cloudflare-zero-trust-guide.md) · 🇯🇵 [ja](../../ja/docs/cloudflare-zero-trust-guide.md) · 🇰🇷 [ko](../../ko/docs/cloudflare-zero-trust-guide.md) · 🇸🇦 [ar](../../ar/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [hi](../../hi/docs/cloudflare-zero-trust-guide.md) · 🇮🇳 [in](../../in/docs/cloudflare-zero-trust-guide.md) · 🇹🇭 [th](../../th/docs/cloudflare-zero-trust-guide.md) · 🇻🇳 [vi](../../vi/docs/cloudflare-zero-trust-guide.md) · 🇮🇩 [id](../../id/docs/cloudflare-zero-trust-guide.md) · 🇲🇾 [ms](../../ms/docs/cloudflare-zero-trust-guide.md) · 🇳🇱 [nl](../../nl/docs/cloudflare-zero-trust-guide.md) · 🇵🇱 [pl](../../pl/docs/cloudflare-zero-trust-guide.md) · 🇸🇪 [sv](../../sv/docs/cloudflare-zero-trust-guide.md) · 🇳🇴 [no](../../no/docs/cloudflare-zero-trust-guide.md) · 🇩🇰 [da](../../da/docs/cloudflare-zero-trust-guide.md) · 🇫🇮 [fi](../../fi/docs/cloudflare-zero-trust-guide.md) · 🇵🇹 [pt](../../pt/docs/cloudflare-zero-trust-guide.md) · 🇷🇴 [ro](../../ro/docs/cloudflare-zero-trust-guide.md) · 🇭🇺 [hu](../../hu/docs/cloudflare-zero-trust-guide.md) · 🇧🇬 [bg](../../bg/docs/cloudflare-zero-trust-guide.md) · 🇸🇰 [sk](../../sk/docs/cloudflare-zero-trust-guide.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/cloudflare-zero-trust-guide.md) · 🇮🇱 [he](../../he/docs/cloudflare-zero-trust-guide.md) · 🇵🇭 [phi](../../phi/docs/cloudflare-zero-trust-guide.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/cloudflare-zero-trust-guide.md) · 🇨🇿 [cs](../../cs/docs/cloudflare-zero-trust-guide.md) · 🇹🇷 [tr](../../tr/docs/cloudflare-zero-trust-guide.md)
---
Este guia documenta o padrão ouro de infraestrutura de rede para proteger o **OmniRoute** e expor sua aplicação de forma segura para a internet, **sem abrir nenhuma porta (Zero Inbound)**.
本指南記錄了保護 **OmniRoute** 並將應用程式安全地暴露到網際網路的網路基礎設施黃金標準，**無需開放任何連接埠（Zero Inbound）**。
## O que foi feito na sua VM?
## 您的虛擬機器上做了什麼？
Nós ativamos o OmniRoute em modo **Split-Port** através do PM2:
我們透過 PM2 以 **Split-Port** 模式啟動了 OmniRoute：
- **Porta \`20128\`:** Roda **apenas a API** `/v1`.
- **Porta \`20129\`:** Roda **apenas o Dashboard** Administrativo visual.
- **連接埠 `20128`：** 僅執行 **API** `/v1`。
- **連接埠 `20129`：** 僅執行可視化管理 **Dashboard**。
Além disso, o serviço interno exige \`REQUIRE_API_KEY=true\`, o que significa que nenhum agente pode consumir os endpoints da API sem enviar um "Bearer Token" legítimo gerado na aba API Keys do Painel.
此外，內部服務要求 `REQUIRE_API_KEY=true`，這表示任何代理程式都必須傳送在管理面板 API Keys 標籤頁中產生的有效 "Bearer Token" 才能存取 API 端點。
Isso nos permite criar duas regras completamente independentes na rede. É aqui que entra o **Cloudflare Tunnel (cloudflared)**.
這使我們能夠在網路中建立兩條完全獨立的規則。這就是 **Cloudflare Tunnel（cloudflared）** 發揮作用的地方。
---
## 1. Como Criar o Túnel na Cloudflare
## 1. 如何在 Cloudflare 上建立隧道
O utilitário \`cloudflared\` já está instalado na sua máquina. Siga os passos na nuvem:
`cloudflared` 工具已安裝在您的機器上。請按以下雲端步驟操作：
1. Acesse seu painel **Cloudflare Zero Trust** (One.dash.cloudflare.com).
2. No menu à esquerda, vá em **Networks > Tunnels**.
3. Clique em **Add a Tunnel**, escolha **Cloudflared** e dê o nome \`OmniRoute-VM\`.
4. Ele vai gerar um comando na tela chamado "Install and run a connector". **Você só precisa copiar o Token (a string longa após `--token`)**.
5. Logue via SSH na sua máquina virtual (ou Terminal do Proxmox) e execute:
\`\`\`bash
# Inicia e amarra o túnel permanentemente à sua conta
cloudflared service install SEU_TOKEN_GIGANTE_AQUI
\`\`\`
1. 前往您的 **Cloudflare Zero Trust** 面板（One.dash.cloudflare.com）。
2. 在左側選單中，前往 **Networks > Tunnels**。
3. 點選 **Add a Tunnel**，選擇 **Cloudflared**，命名為 `OmniRoute-VM`。
4. 畫面會產生一個名為 "Install and run a connector" 的指令。**您只需複製 Token（`--token` 後面的長字串）**。
5. 透過 SSH 登入您的虛擬機器（或 Proxmox 終端機），執行：
```bash
# 啟動並永久綁定隧道到您的帳戶
cloudflared service install YOUR_HUGE_TOKEN_HERE
```
---
## 2. Configurando o Roteamento (Public Hostnames)
## 2. 設定路由（Public Hostnames）
Ainda na tela do Tunnel recém-criado, vá para a aba **Public Hostnames** e adicione as **duas** rotas, aproveitando a separação que fizemos:
在新建立隧道的介面中，進入 **Public Hostnames** 標籤頁，利用我們做的連接埠分離，新增 **兩條** 路由：
### Rota 1: API Segura (Limitada)
### 路由 1：安全 API（受限）
- **Subdomain:** \`api\`
- **Domain:** \`seuglobal.com.br\` (escolha seu domínio real)
- **Service Type:** \`HTTP\`
- **URL:** \`127.0.0.1:20128\` _(Porta interna da API)_
- **Subdomain：** `api`
- **Domain：** `yourdomain.com`（選擇您的實際網域）
- **Service Type：** `HTTP`
- **URL：** `127.0.0.1:20128` _（API 內部連接埠）_
### Rota 2: Painel Zero Trust (Fechado)
### 路由 2：Zero Trust 管理面板（封閉）
- **Subdomain:** \`omniroute\` ou \`painel\`
- **Domain:** \`seuglobal.com.br\`
- **Service Type:** \`HTTP\`
- **URL:** \`127.0.0.1:20129\` _(Porta interna do App/Visual)_
- **Subdomain：** `omniroute` 或 `panel`
- **Domain：** `yourdomain.com`
- **Service Type：** `HTTP`
- **URL：** `127.0.0.1:20129` _（App/可視化內部連接埠）_
Neste momento, a conectividade "Física" está resolvida. Agora vamos blindar de verdade.
此時，"實體"連線已經解決。現在我們要真正加固它。
---
## 3. Blindando o Painel com Zero Trust (Access)
## 3. 使用 Zero Trust（Access）加固管理面板
Nenhuma senha local protege melhor o seu painel do que remover totalmente o acesso a ele da internet aberta.
比起在本機設定密碼，更好的保護管理面板方式是將它完全從開放網際網路中移除。
1. No painel Zero Trust, vá em **Access > Applications > Add an application**.
2. Selecione **Self-hosted**.
3. Em **Application name**, coloque \`Painel OmniRoute\`.
4. Em **Application domain**, coloque \`omniroute.seuglobal.com.br\` (O mesmo que você fez na "Rota 2").
5. Clique em **Next**.
6. Em **Rule action**, escolha \`Allow\`. Em nome da Rule coloque \`Admin Apenas\`.
7. Em **Include**, no seletor de "Selector" escolha \`Emails\` e digite o seu email, por exemplo \`admin@spgeo.com.br\`.
8. Salve (`Add application`).
1. 在 Zero Trust 面板中，前往 **Access > Applications > Add an application**。
2. 選擇 **Self-hosted**。
3. 在 **Application name** 中，填入 `OmniRoute Panel`。
4. 在 **Application domain** 中，填入 `omniroute.yourdomain.com`（與"路由 2"中設定的一致）。
5. 點選 **Next**。
6. 在 **Rule action** 中選擇 `Allow`。在 Rule 名稱中填入 `Admin Only`。
7. 在 **Include** 中，"Selector" 選擇 `Emails`，輸入您的電子郵件，例如 `admin@example.com`。
8. 儲存（`Add application`）。
> **O que isso fez:** Se você tentar abrir \`omniroute.seuglobal.com.br\`, não cai mais na sua aplicação OmniRoute! Cai numa tela elegante da Cloudflare pedindo para digitar seu email. Somente se você (ou o email que você botou) for digitado lá, ele recebe no Outlook/Gmail um código de 6 dígitos temporário que libera o túnel até a porta \`20129\`.
> **效果：** 如果您嘗試開啟 `omniroute.yourdomain.com`，將不再直接進入您的 OmniRoute 應用程式！而是跳轉到一個精美的 Cloudflare 頁面，要求輸入電子郵件地址。只有您（或您填寫的電子郵件）輸入後，Outlook/Gmail 會收到一個 6 位數臨時驗證碼，驗證通過後才會解除隧道限制，允許存取 `20129` 連接埠。
---
## 4. Limitando e Protegendo a API com Rate Limit (WAF)
## 4. 使用速率限制（WAF）限制並保護 API
O Dashboard do Zero Trust não se aplica à rota da API (\`api.seuglobal.com.br\`), porque é um acesso programático via ferramentas automatizadas (agentes) sem navegador. Para ele, usaremos o Firewall principal (WAF) da Cloudflare.
Zero Trust Dashboard 不適用於 API 路由（`api.yourdomain.com`），因為這是透過自動化工具（代理程式）進行的程式化存取，無需瀏覽器。對於這種情況，我們將使用 Cloudflare 的主要防火牆（WAF）。
1. Acesse o **Painel Normal** da Cloudflare (dash.cloudflare.com) e entre no seu Domínio.
2. No menu esquerdo, vá em **Security > WAF > Rate limiting rules**.
3. Clique em **Create rule**.
4. **Name:** \`Anti-Abuso OmniRoute API\`
1. 前往 Cloudflare **一般面板**（dash.cloudflare.com），進入您的網域。
2. 在左側選單中，前往 **Security > WAF > Rate limiting rules**。
3. 點選 **Create rule**。
4. **Name：** `Anti-Abuse OmniRoute API`
5. **If incoming requests match...**
- Escolha em Field: \`Hostname\`
- Operator: \`equals\`
- Value: \`api.seuglobal.com.br\`
6. Em **With the same characteristics:** Mantenha \`IP\`.
7. Nos limites (Limit):
- **When requests exceed:** \`50\`
- **Period:** \`1 minute\`
8. No final, em **Action**: \`Block\` (Bloquear) e decida se o bloqueio dura por 1 minuto ou 1 hora.
9. **Deploy**.
- Field 選擇：`Hostname`
- Operator：`equals`
- Value：`api.yourdomain.com`
6. **With the same characteristics：** 保持 `IP`。
7. 限制條件（Limit）：
- **When requests exceed：** `50`
- **Period：** `1 minute`
8. 最後，在 **Action** 中選擇 `Block`，並決定封鎖持續 1 分鐘還是 1 小時。
9. **Deploy**。
> **O que isso fez:** Ninguém pode mandar mais de 50 requisições num período de 60 segundos na sua URL de API. Como você roda vários agentes e os consumos por trás já batem rate limit e já rastreiam tokens, isso é apenas uma medida na Borda da Internet (Edge Layer) que protege sua Instância On-Premises de cair por estresse térmico antes mesmo do tráfego descer pelo túnel.
> **效果：** 在 60 秒內，任何人都不能向您的 API URL 發送超過 50 次請求。由於您執行著多個代理程式，其背後的消耗已經受到速率限制和 Token 追蹤，這只是網際網路邊緣層（Edge Layer）的一項措施，在流量進入隧道之前就保護您的本機部署執行個體免受壓力超載。
---
## Finalização
## 完成
1. A sua VM **não possui nenhuma porta exposta** em `/etc/ufw`.
2. O OmniRoute só conversa HTTPS saindo (\`cloudflared\`) e não recebendo TCP direto do mundo.
3. Seus requets pro OpenAI são ofuscados porque configuramos eles globalmente pra passar em um Proxy SOCKS5 (A nuvem não liga pro SOCKS5 porque ela vem Inbound).
4. Seu painel web tem 2-Factor com Email.
5. Sua API está ratelimitada na borda pela Cloudflare e só trafega Bearer Tokens.
1. 您的虛擬機器 **沒有任何連接埠暴露** 在 `/etc/ufw` 中。
2. OmniRoute 僅透過 `cloudflared` 進行 HTTPS 對外通訊，不直接接收來自外部的 TCP 連線。
3. 您的 OpenAI 請求已混淆處理，因為我們已全域設定透過 SOCKS5 代理傳送（雲端不關心 SOCKS5，因為流量是入站的）。
4. 您的 Web 管理面板具有電子郵件兩步驟驗證。
5. 您的 API 在邊緣層受 Cloudflare 速率限制，且僅傳輸 Bearer Token。

130
docs/i18n/zh-TW/docs/features/context-relay.md
View File

@@ -1,65 +1,57 @@
# Context Relay (中文（簡體）)
# Context Relay（繁體中文）
🌐 **Languages:** 🇺🇸 [English](../../../../../docs/features/context-relay.md) · 🇪🇸 [es](../../../es/docs/features/context-relay.md) · 🇫🇷 [fr](../../../fr/docs/features/context-relay.md) · 🇩🇪 [de](../../../de/docs/features/context-relay.md) · 🇮🇹 [it](../../../it/docs/features/context-relay.md) · 🇷🇺 [ru](../../../ru/docs/features/context-relay.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/features/context-relay.md) · 🇯🇵 [ja](../../../ja/docs/features/context-relay.md) · 🇰🇷 [ko](../../../ko/docs/features/context-relay.md) · 🇸🇦 [ar](../../../ar/docs/features/context-relay.md) · 🇮🇳 [hi](../../../hi/docs/features/context-relay.md) · 🇮🇳 [in](../../../in/docs/features/context-relay.md) · 🇹🇭 [th](../../../th/docs/features/context-relay.md) · 🇻🇳 [vi](../../../vi/docs/features/context-relay.md) · 🇮🇩 [id](../../../id/docs/features/context-relay.md) · 🇲🇾 [ms](../../../ms/docs/features/context-relay.md) · 🇳🇱 [nl](../../../nl/docs/features/context-relay.md) · 🇵🇱 [pl](../../../pl/docs/features/context-relay.md) · 🇸🇪 [sv](../../../sv/docs/features/context-relay.md) · 🇳🇴 [no](../../../no/docs/features/context-relay.md) · 🇩🇰 [da](../../../da/docs/features/context-relay.md) · 🇫🇮 [fi](../../../fi/docs/features/context-relay.md) · 🇵🇹 [pt](../../../pt/docs/features/context-relay.md) · 🇷🇴 [ro](../../../ro/docs/features/context-relay.md) · 🇭🇺 [hu](../../../hu/docs/features/context-relay.md) · 🇧🇬 [bg](../../../bg/docs/features/context-relay.md) · 🇸🇰 [sk](../../../sk/docs/features/context-relay.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/features/context-relay.md) · 🇮🇱 [he](../../../he/docs/features/context-relay.md) · 🇵🇭 [phi](../../../phi/docs/features/context-relay.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/features/context-relay.md) · 🇨🇿 [cs](../../../cs/docs/features/context-relay.md) · 🇹🇷 [tr](../../../tr/docs/features/context-relay.md)
🌐 **語言:** 🇺🇸 [English](../../../../../docs/features/context-relay.md) · 🇪🇸 [es](../../../es/docs/features/context-relay.md) · 🇫🇷 [fr](../../../fr/docs/features/context-relay.md) · 🇩🇪 [de](../../../de/docs/features/context-relay.md) · 🇮🇹 [it](../../../it/docs/features/context-relay.md) · 🇷🇺 [ru](../../../ru/docs/features/context-relay.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/features/context-relay.md) · 🇯🇵 [ja](../../../ja/docs/features/context-relay.md) · 🇰🇷 [ko](../../../ko/docs/features/context-relay.md) · 🇸🇦 [ar](../../../ar/docs/features/context-relay.md) · 🇮🇳 [hi](../../../hi/docs/features/context-relay.md) · 🇮🇳 [in](../../../in/docs/features/context-relay.md) · 🇹🇭 [th](../../../th/docs/features/context-relay.md) · 🇻🇳 [vi](../../../vi/docs/features/context-relay.md) · 🇮🇩 [id](../../../id/docs/features/context-relay.md) · 🇲🇾 [ms](../../../ms/docs/features/context-relay.md) · 🇳🇱 [nl](../../../nl/docs/features/context-relay.md) · 🇵🇱 [pl](../../../pl/docs/features/context-relay.md) · 🇸🇪 [sv](../../../sv/docs/features/context-relay.md) · 🇳🇴 [no](../../../no/docs/features/context-relay.md) · 🇩🇰 [da](../../../da/docs/features/context-relay.md) · 🇫🇮 [fi](../../../fi/docs/features/context-relay.md) · 🇵🇹 [pt](../../../pt/docs/features/context-relay.md) · 🇷🇴 [ro](../../../ro/docs/features/context-relay.md) · 🇭🇺 [hu](../../../hu/docs/features/context-relay.md) · 🇧🇬 [bg](../../../bg/docs/features/context-relay.md) · 🇸🇰 [sk](../../../sk/docs/features/context-relay.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/features/context-relay.md) · 🇮🇱 [he](../../../he/docs/features/context-relay.md) · 🇵🇭 [phi](../../../phi/docs/features/context-relay.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/features/context-relay.md) · 🇨🇿 [cs](../../../cs/docs/features/context-relay.md) · 🇹🇷 [tr](../../../tr/docs/features/context-relay.md)
---
`context-relay` is a combo strategy that keeps session continuity when the active account
rotates before the conversation is finished.
`context-relay` 是一種 combo 策略，可在活躍帳戶於對話完成前輪換時，保持工作階段的連續性。
The current runtime behaves like priority routing for model selection, then adds a
handoff layer on top:
目前的執行時期行為類似於模型選擇的優先路由，然後在上方加入一層交接層：
- before the active account is exhausted, OmniRoute generates a compact structured summary
- after authentication selects a different account for the same session, OmniRoute injects
that summary as a system message into the next request
- once the handoff is consumed successfully, it is removed from storage
- 在活躍帳戶耗盡之前，OmniRoute 會產生一個精簡的結構化摘要
- 在認證為同一個工作階段選取不同帳戶後，OmniRoute 會將該摘要作為系統訊息注入到下一個請求中
- 交接成功消耗後，會從儲存中移除
## When To Use It
## 何時使用
Use `context-relay` when all of the following are true:
當以下所有條件成立時，請使用 `context-relay`：
- the combo is expected to rotate between multiple accounts of the same provider
- losing short-term conversational continuity would hurt task quality
- the provider exposes enough quota information to predict an approaching account limit
- combo 預計會在同一個提供商的多個帳戶之間輪換
- 失去短期對話連續性會影響任務品質
- 提供商暴露了足夠的配額資訊，可以預測即將到來的帳戶限制
This is most useful for long-running coding or research sessions that may outlive a single
account window.
這對於可能超過單一帳戶視窗的長時間編碼或研究會話最為有用。
## Runtime Flow
## 執行時期流程
The current behavior is intentionally split across two runtime layers.
目前的行為有意分散在兩個執行時期層中。
### 0% to 84% quota used
### 已使用 0% 至 84% 的配額
No handoff is generated. Requests behave like normal priority routing.
不會產生交接。請求的行為就像一般的優先路由。
### 85% to 94% quota used
### 已使用 85% 至 94% 的配額
If the active provider is enabled in `handoffProviders`, OmniRoute generates a structured
handoff summary in the background before the account is fully exhausted.
如果活躍提供商在 `handoffProviders` 中啟用，OmniRoute 會在帳戶完全耗盡之前在背景產生結構化的交接摘要。
Important details:
重要細節：
- the default warning threshold is `0.85`
- the hard stop for generation is `0.95`
- only one in-flight handoff generation is allowed per `sessionId + comboName`
- if an active handoff already exists for that session/combo, no duplicate summary is generated
- 預設警告閾值為 `0.85`
- 產生作業的硬性停止點為 `0.95`
- 每個 `sessionId + comboName` 只允許一個進行中的交接產生作業
- 如果該工作階段/combo 已有活躍的交接，則不會產生重複的摘要
### 95% or more quota used
### 已使用 95% 或更多的配額
No new handoff is generated. At this point the system is already in or near exhaustion and
the runtime avoids scheduling another summary request.
不會產生新的交接。此時系統已處於或接近耗盡狀態，執行時期會避免排程另一個摘要請求。
### After account rotation
### 帳戶輪換後
When the next request for the same session resolves to a different authenticated account,
OmniRoute prepends the stored handoff as a system message. Injection happens only after the
real account switch is known.
當同一個工作階段的下一個請求解析到不同的已認證帳戶時，OmniRoute 會將儲存的交接作為系統訊息預先加入。只有在實際帳戶切換已知後才會進行注入。
## Handoff Payload
## 交接酬載
The persisted handoff payload is stored in `context_handoffs` and includes:
持久化的交接酬載儲存在 `context_handoffs` 中，包括：
- `sessionId`
- `comboName`
@@ -74,57 +66,51 @@ The persisted handoff payload is stored in `context_handoffs` and includes:
- `generatedAt`
- `expiresAt`
The summary model is instructed to return a JSON object with this structure:
摘要模型被指示回傳具有此結構的 JSON 物件：
```json
{
"summary": "Dense summary of what matters for continuity",
"keyDecisions": ["Decision 1", "Decision 2"],
"taskProgress": "What is done, what is pending, and the next step",
"activeEntities": ["fileA.ts", "feature X", "provider Y"]
"summary": "關於哪些內容對連續性重要的精簡摘要",
"keyDecisions": ["決策 1", "決策 2"],
"taskProgress": "已完成的事項、待辦事項以及下一步",
"activeEntities": ["fileA.ts", "功能 X", "提供商 Y"]
}
```
At injection time, OmniRoute converts that payload into a `<context_handoff>` system
message so the next account can continue with the correct local context.
在注入時，OmniRoute 會將該酬載轉換為 `<context_handoff>` 系統訊息，以便下一個帳戶能以正確的本地上下文繼續。
## 設定
`context-relay` supports these config fields:
`context-relay` 支援以下配置欄位：
- `handoffThreshold`: warning threshold for summary generation, default `0.85`
- `handoffModel`: optional model override used only for summary generation
- `handoffProviders`: allowlist of providers allowed to trigger handoff generation
- `handoffThreshold`：摘要產生的警告閾值，預設 `0.85`
- `handoffModel`：可選的模型覆寫，僅用於摘要產生
- `handoffProviders`：允許觸發交接產生的提供商允許清單
Global defaults can be configured in Settings, and combo-specific values can override them
in the Combos page.
全域預設值可在設定中配置，combo 專用值可在 Combos 頁面中覆寫。
## Architectural Note
## 架構說明
The current implementation does not use a standalone `handleContextRelayCombo` handler.
目前的實作未使用獨立的 `handleContextRelayCombo` 處理器。
Instead:
而是：
- `open-sse/services/combo.ts` decides whether a successful turn should generate a handoff
- `src/sse/handlers/chat.ts` injects the handoff only after authentication resolves the
actual account used for the request
- `open-sse/services/combo.ts` 決定成功的回合是否應產生交接
- `src/sse/handlers/chat.ts` 僅在認證解析出請求使用的實際帳戶後才注入交接
This split is intentional in the current codebase because the combo loop alone does not know
whether the request stayed on the same account or actually switched accounts.
這種分離在目前的程式碼庫中是有意的，因為 combo 迴圈本身無法知道請求是停留在同一個帳戶還是實際切換了帳戶。
## Limitations
## 限制
- Effective runtime support is currently centered on `codex` quota rotation.
- `handoffProviders` is already modeled as a config surface, but real handoff generation
still depends on provider-specific quota plumbing.
- The summary is intentionally compact and recent-history based; it is not a full transcript
replay mechanism.
- Handoffs are scoped by `sessionId + comboName` and expire automatically.
- If the session does not switch accounts, the stored handoff is not injected.
- 目前的執行時期支援主要集中在 `codex` 配額輪換上
- `handoffProviders` 已建模為配置表面，但實際的交接產生仍依賴於提供商特定的配額管線
- 摘要刻意保持精簡並基於近期歷史；它不是完整的對話記錄重播機制
- 交接以 `sessionId + comboName` 為範圍，並會自動過期
- 如果工作階段未切換帳戶，則不會注入儲存的交接
## Recommended Usage Pattern
## 建議使用模式
- use multiple accounts from the same provider
- keep stable `sessionId` values across the session
- set `handoffThreshold` early enough to leave room for the background summary request
- treat the feature as continuity assistance, not as a replacement for persistent memory
- 使用同一個提供商的多個帳戶
- 在整個工作階段中保持穩定的 `sessionId` 值
- 儘早設定 `handoffThreshold`，為背景摘要請求預留空間
- 將此功能視為連續性輔助，而非持久化記憶體的替代方案

183
docs/i18n/zh-TW/docs/frameworks/A2A-SERVER.md
View File

@@ -1,43 +1,60 @@
# OmniRoute A2A Server Documentation (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/A2A-SERVER.md) · 🇸🇦 [ar](../../ar/docs/A2A-SERVER.md) · 🇧🇬 [bg](../../bg/docs/A2A-SERVER.md) · 🇧🇩 [bn](../../bn/docs/A2A-SERVER.md) · 🇨🇿 [cs](../../cs/docs/A2A-SERVER.md) · 🇩🇰 [da](../../da/docs/A2A-SERVER.md) · 🇩🇪 [de](../../de/docs/A2A-SERVER.md) · 🇪🇸 [es](../../es/docs/A2A-SERVER.md) · 🇮🇷 [fa](../../fa/docs/A2A-SERVER.md) · 🇫🇮 [fi](../../fi/docs/A2A-SERVER.md) · 🇫🇷 [fr](../../fr/docs/A2A-SERVER.md) · 🇮🇳 [gu](../../gu/docs/A2A-SERVER.md) · 🇮🇱 [he](../../he/docs/A2A-SERVER.md) · 🇮🇳 [hi](../../hi/docs/A2A-SERVER.md) · 🇭🇺 [hu](../../hu/docs/A2A-SERVER.md) · 🇮🇩 [id](../../id/docs/A2A-SERVER.md) · 🇮🇹 [it](../../it/docs/A2A-SERVER.md) · 🇯🇵 [ja](../../ja/docs/A2A-SERVER.md) · 🇰🇷 [ko](../../ko/docs/A2A-SERVER.md) · 🇮🇳 [mr](../../mr/docs/A2A-SERVER.md) · 🇲🇾 [ms](../../ms/docs/A2A-SERVER.md) · 🇳🇱 [nl](../../nl/docs/A2A-SERVER.md) · 🇳🇴 [no](../../no/docs/A2A-SERVER.md) · 🇵🇭 [phi](../../phi/docs/A2A-SERVER.md) · 🇵🇱 [pl](../../pl/docs/A2A-SERVER.md) · 🇵🇹 [pt](../../pt/docs/A2A-SERVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/A2A-SERVER.md) · 🇷🇴 [ro](../../ro/docs/A2A-SERVER.md) · 🇷🇺 [ru](../../ru/docs/A2A-SERVER.md) · 🇸🇰 [sk](../../sk/docs/A2A-SERVER.md) · 🇸🇪 [sv](../../sv/docs/A2A-SERVER.md) · 🇰🇪 [sw](../../sw/docs/A2A-SERVER.md) · 🇮🇳 [ta](../../ta/docs/A2A-SERVER.md) · 🇮🇳 [te](../../te/docs/A2A-SERVER.md) · 🇹🇭 [th](../../th/docs/A2A-SERVER.md) · 🇹🇷 [tr](../../tr/docs/A2A-SERVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/A2A-SERVER.md) · 🇵🇰 [ur](../../ur/docs/A2A-SERVER.md) · 🇻🇳 [vi](../../vi/docs/A2A-SERVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/A2A-SERVER.md)
---
title: "OmniRoute A2A 伺服器文件"
version: 3.8.40
lastUpdated: 2026-06-28
---
> Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent
# OmniRoute A2A 伺服器文件
## Agent Discovery
> Agent-to-Agent 協定 v0.3 — OmniRoute 作為智慧路由代理
A2A 介面包含兩個面向：
- **JSON-RPC 2.0** 位於 `POST /a2a`（標準進入點，定義於 `src/app/a2a/route.ts`）。
- **REST** 位於 `/api/a2a/*`，供儀表板和工具使用（狀態、任務清單、取消）。
任務由 `A2ATaskManager`（`src/lib/a2a/taskManager.ts`，預設 5 分鐘 TTL）追蹤。技能透過 `A2A_SKILL_HANDLERS`（位於 `src/lib/a2a/taskExecution.ts`）調度。
## 代理探索
```bash
curl http://localhost:20128/.well-known/agent.json
```
Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements.
回傳描述 OmniRoute 能力、技能及驗證需求的 Agent Card。
Agent Card 中的 `version` 欄位源自 `process.env.npm_package_version`（參見 `src/app/.well-known/agent.json/route.ts:13`），因此每次發版都會與 `package.json` 自動同步。
---
## Authentication
## 驗證
All `/a2a` requests require an API key via the `Authorization` header:
所有 `/a2a` 請求都需要透過 `Authorization` 標頭提供 API 金鑰：
```
Authorization: Bearer YOUR_OMNIROUTE_API_KEY
Authorization: Bearer YOUR_O..._KEY
```
If no API key is configured on the server, authentication is bypassed.
若伺服器未設定 API 金鑰，則跳過驗證。
## 啟用
A2A 由 **Endpoints → A2A** 開關控制，預設為停用。停用時，
`GET /api/a2a/status` 回報 `status: "disabled"` 及 `online: false`；對
`POST /a2a` 的 JSON-RPC 呼叫則回傳 HTTP 503 及 JSON-RPC 錯誤碼 `-32000`。
---
## JSON-RPC 2.0 Methods
## JSON-RPC 2.0 方法
### `message/send` — Synchronous Execution
### `message/send` — 同步執行
Sends a message to a skill and waits for the complete response.
發送訊息給技能並等待完整回應。
```bash
curl -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Authorization: Bearer ***" \
-d '{
"jsonrpc": "2.0",
"id": "1",
@@ -50,7 +67,7 @@ curl -X POST http://localhost:20128/a2a \
}'
```
**Response:**
**回應：**
```json
{
@@ -71,14 +88,14 @@ curl -X POST http://localhost:20128/a2a \
}
```
### `message/stream` — SSE Streaming
### `message/stream` — SSE 串流
Same as `message/send` but returns Server-Sent Events for real-time streaming.
與 `message/send` 相同，但回傳 Server-Sent Events 以實現即時串流。
```bash
curl -N -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Authorization: Bearer ***" \
-d '{
"jsonrpc": "2.0",
"id": "1",
@@ -90,7 +107,7 @@ curl -N -X POST http://localhost:20128/a2a \
}'
```
**SSE Events:**
**SSE 事件：**
```
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}
@@ -100,36 +117,113 @@ data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","s
data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}
```
### `tasks/get` — Query Task Status
### `tasks/get` — 查詢任務狀態
```bash
curl -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Authorization: Bearer ***" \
-d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'
```
### `tasks/cancel` — Cancel a Task
### `tasks/cancel` — 取消任務
```bash
curl -X POST http://localhost:20128/a2a \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Authorization: Bearer ***" \
-d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'
```
---
## Available Skills
## 可用技能
| Skill | Description |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. |
| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. |
OmniRoute 提供 6 個 A2A 技能，配置於 `src/lib/a2a/taskExecution.ts::A2A_SKILL_HANDLERS`。每個技能模組位於 `src/lib/a2a/skills/`。
| 技能 | ID | 描述 | 標籤 | 範例 |
| :----------------- | :-------------------- | :--------------------------------------------------------------------------------- | :-------------------------- | :------------------------------------- |
| Smart Routing | `smart-routing` | 透過 OmniRoute 的 combo 引擎 + 評分，將提示路由至最佳提供者/組合 | routing, providers | "Route this prompt via the best model" |
| Quota Management | `quota-management` | 回報各提供者的配額狀態，協助呼叫端決定何時限流或切換 | quota, providers | "Check quota for anthropic" |
| Provider Discovery | `provider-discovery` | 列出已安裝的提供者及其能力、免費方案標記、OAuth 狀態 | providers, discovery | "What providers are available?" |
| Cost Analysis | `cost-analysis` | 根據目錄及近期使用量，估算請求/對話的成本 | cost, usage | "Estimate cost for this conversation" |
| Health Report | `health-report` | 彙總各提供者的斷路器、冷卻、鎖定狀態 | health, resilience | "Show health status of all providers" |
| List Capabilities | `list-capabilities` | 回傳完整的 42 項代理技能目錄，以 Markdown 表格呈現，附原始 SKILL.md 網址供注入上下文 | catalog, discovery, skills | "List all OmniRoute capabilities" |
> 注意：Agent Card 描述目前標示「36+ 個提供者」（`src/app/.well-known/agent.json/route.ts:26` 及 `:55`）。實際目錄已成長至 180+ 個提供者——該字串應在後續變更中更新（另開文件/程式碼待辦事項追蹤；此處不修改）。
### `list-capabilities` 技能詳情
`list-capabilities` 技能對於需要在發送 API 呼叫前探索 OmniRoute 能力的外部代理尤其有用。它回傳結構化的 Markdown 表格產出：
```
| ID | Name | Category | Area | Endpoints/Commands | Raw URL |
| --- | --- | --- | --- | --- | --- |
| omni-auth | Auth & Sessions | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... |
...
```
每一列都包含 `rawUrl` 欄位，讓代理可直接擷取完整的 SKILL.md。`metadata.totalSkills` 欄位固定為 `42`。實作位於：`src/lib/a2a/skills/listCapabilities.ts`。另請參閱 [AGENT-SKILLS.md](./AGENT-SKILLS.md)。
---
## Task Lifecycle
## REST API（輔助）
JSON-RPC 端點 `/a2a` 是標準的 A2A 進入點。以下 REST 端點為儀表板和外部工具提供輔助存取：
| 端點 | 方法 | 描述 | 驗證方式 |
| :---------------------------- | :----- | :------------------------ | :--------------------- |
| `/api/a2a/status` | GET | 伺服器狀態、已註冊技能 | (公開) |
| `/api/a2a/tasks` | GET | 列出任務（可篩選） | management |
| `/api/a2a/tasks/[id]` | GET | 依 ID 取得任務 | management |
| `/api/a2a/tasks/[id]/cancel` | POST | 取消執行中的任務 | management |
| `/.well-known/agent.json` | GET | Agent Card（A2A 探索） | (公開，快取 3600 秒) |
---
## 新增技能
1. **建立技能檔案：** `src/lib/a2a/skills/<your-skill>.ts`
匯出一個非同步函式 `(task: A2ATask) => Promise<{ artifacts, metadata }>`。請遵循現有技能（如 `smartRouting.ts`）的結構。
2. **註冊處理器：** 在 `src/lib/a2a/taskExecution.ts` 中，將項目加入 `A2A_SKILL_HANDLERS`：
```typescript
export const A2A_SKILL_HANDLERS = {
// ...existing skills
"your-skill": async (task) => {
const skillModule = await import("./skills/yourSkill");
return skillModule.executeYourSkill(task);
},
};
```
3. **在 Agent Card 中揭露：** 在 `src/app/.well-known/agent.json/route.ts` 中，附加至 `skills` 陣列：
```json
{
"id": "your-skill",
"name": "Your Skill",
"description": "簡短、聚焦意圖的描述",
"tags": ["routing", "quota"],
"examples": ["Sample natural-language invocation"]
}
```
4. **撰寫測試：** `tests/unit/a2a-<your-skill>.test.ts`。涵蓋正常路徑及錯誤路徑。
5. **撰寫文件：** 將新技能加入本文件的「可用技能」表格。
---
## 任務 TTL
任務在 `ttlMinutes`（預設 5 分鐘）後過期——此參數配置於 `src/lib/a2a/taskManager.ts:82` 的 `A2ATaskManager` 建構子中。若要自訂，請複製 `A2ATaskManager` 實體化並傳入不同的值（例如 `new A2ATaskManager(15)` 代表 15 分鐘 TTL）。背景排程器每 60 秒清除一次過期任務。
---
## 任務生命週期
```
submitted → working → completed
@@ -137,27 +231,28 @@ submitted → working → completed
→ cancelled
```
- Tasks expire after 5 minutes (configurable)
- Terminal states: `completed`, `failed`, `cancelled`
- Event log tracks every state transition
- 任務預設在 5 分鐘後過期（參見[任務 TTL](#任務-ttl)）
- 終止狀態：`completed`、`failed`、`cancelled`
- 事件日誌追蹤每一次狀態轉換
---
## Error Codes
## 錯誤碼
| Code | Meaning |
| :----- | :----------------------------- |
| -32700 | Parse error (invalid JSON) |
| -32600 | Invalid request / Unauthorized |
| -32601 | Method or skill not found |
| -32602 | Invalid params |
| -32603 | Internal error |
| 代碼 | 含義 |
| :----- | :-------------------------- |
| -32700 | 解析錯誤（JSON 格式無效） |
| -32600 | 無效請求 / 未授權 |
| -32601 | 方法或技能不存在 |
| -32602 | 參數無效 |
| -32603 | 內部錯誤 |
| -32000 | A2A 端點已停用 |
---
## Integration Examples
## 整合範例
### Python (requests)
### Python（requests）
```python
import requests
@@ -176,7 +271,7 @@ print(result["artifacts"][0]["content"])
print(result["metadata"]["routing_explanation"])
```
### TypeScript (fetch)
### TypeScript（fetch）
```typescript
const resp = await fetch("http://localhost:20128/a2a", {

438
docs/i18n/zh-TW/docs/frameworks/MCP-SERVER.md
View File

@@ -1,87 +1,409 @@
# OmniRoute MCP Server Documentation (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/MCP-SERVER.md) · 🇸🇦 [ar](../../ar/docs/MCP-SERVER.md) · 🇧🇬 [bg](../../bg/docs/MCP-SERVER.md) · 🇧🇩 [bn](../../bn/docs/MCP-SERVER.md) · 🇨🇿 [cs](../../cs/docs/MCP-SERVER.md) · 🇩🇰 [da](../../da/docs/MCP-SERVER.md) · 🇩🇪 [de](../../de/docs/MCP-SERVER.md) · 🇪🇸 [es](../../es/docs/MCP-SERVER.md) · 🇮🇷 [fa](../../fa/docs/MCP-SERVER.md) · 🇫🇮 [fi](../../fi/docs/MCP-SERVER.md) · 🇫🇷 [fr](../../fr/docs/MCP-SERVER.md) · 🇮🇳 [gu](../../gu/docs/MCP-SERVER.md) · 🇮🇱 [he](../../he/docs/MCP-SERVER.md) · 🇮🇳 [hi](../../hi/docs/MCP-SERVER.md) · 🇭🇺 [hu](../../hu/docs/MCP-SERVER.md) · 🇮🇩 [id](../../id/docs/MCP-SERVER.md) · 🇮🇹 [it](../../it/docs/MCP-SERVER.md) · 🇯🇵 [ja](../../ja/docs/MCP-SERVER.md) · 🇰🇷 [ko](../../ko/docs/MCP-SERVER.md) · 🇮🇳 [mr](../../mr/docs/MCP-SERVER.md) · 🇲🇾 [ms](../../ms/docs/MCP-SERVER.md) · 🇳🇱 [nl](../../nl/docs/MCP-SERVER.md) · 🇳🇴 [no](../../no/docs/MCP-SERVER.md) · 🇵🇭 [phi](../../phi/docs/MCP-SERVER.md) · 🇵🇱 [pl](../../pl/docs/MCP-SERVER.md) · 🇵🇹 [pt](../../pt/docs/MCP-SERVER.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/MCP-SERVER.md) · 🇷🇴 [ro](../../ro/docs/MCP-SERVER.md) · 🇷🇺 [ru](../../ru/docs/MCP-SERVER.md) · 🇸🇰 [sk](../../sk/docs/MCP-SERVER.md) · 🇸🇪 [sv](../../sv/docs/MCP-SERVER.md) · 🇰🇪 [sw](../../sw/docs/MCP-SERVER.md) · 🇮🇳 [ta](../../ta/docs/MCP-SERVER.md) · 🇮🇳 [te](../../te/docs/MCP-SERVER.md) · 🇹🇭 [th](../../th/docs/MCP-SERVER.md) · 🇹🇷 [tr](../../tr/docs/MCP-SERVER.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/MCP-SERVER.md) · 🇵🇰 [ur](../../ur/docs/MCP-SERVER.md) · 🇻🇳 [vi](../../vi/docs/MCP-SERVER.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/MCP-SERVER.md)
---
title: "OmniRoute MCP Server 文件"
version: 3.8.40
lastUpdated: 2026-06-28
---
> Model Context Protocol server with 16 intelligent tools
# OmniRoute MCP Server 文件
> 模型上下文協定（Model Context Protocol）伺服器，提供 104 個工具，涵蓋路由、快取、壓縮、記憶、技能、代理、池與上下文來源操作。
>
> 真相來源：`open-sse/mcp-server/server.ts` 透過 `countUniqueMcpTools()` 計算出 **104 個唯一工具**：42 個標準定義（包括六個 CCR 生命週期工具與 agent-skills 三件組），加上記憶體（3 個）、技能（4 個）、GitHub 技能（3 個）、池（6 個）、遊戲化（8 個）、外掛（8 個）、Notion（6 個）、Obsidian（22 個）與兩個僅限 RTK 的壓縮工具。
## 安裝
OmniRoute MCP is built-in. Start it with:
OmniRoute MCP 為內建功能。透過以下指令啟動：
```bash
omniroute --mcp
```
Or via the open-sse transport:
或透過 open-sse 傳輸層：
```bash
# HTTP streamable transport (port 20130)
omniroute --dev # MCP auto-starts on /mcp endpoint
# HTTP 可串流傳輸（連接埠 20130）
omniroute --dev # MCP 會自動在 /mcp 端點啟動
```
## IDE Configuration
## 傳輸層
See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup.
MCP 伺服器提供三種傳輸層，皆由同一個 `createMcpServer()` 工廠函式驅動：
| 傳輸層 | 位置 | 使用時機 |
| :----------------- | :----------------------------------------- | :------------------------------------------------ |
| `stdio` | `open-sse/mcp-server/server.ts` | IDE 整合（Claude Desktop、Cursor 等） |
| `sse` | `POST/GET /api/mcp/sse` 經由 `httpTransport` | 需要事件串流的瀏覽器／代理客戶端 |
| `streamable-http` | `POST/GET/DELETE /api/mcp/stream` | 多工作階段 HTTP 客戶端（`mcp-session-id` 標頭） |
作用中的 HTTP 傳輸層（`sse` 或 `streamable-http`）由 `mcpTransport` 設定值選取。切換傳輸層會關閉另一傳輸層上的現有工作階段。
### 遠端存取（manage 範圍繞過）
`/api/mcp/*` 屬於 LOCAL_ONLY 層級（`src/server/authz/routeGuard.ts`）— 預設僅允許回環主機（`localhost`、`127.0.0.1`、`::1`）存取。自 v3.8.2 起，非回環客戶端若提供攜帶 `manage` 範圍的 `Authorization: Bearer <key>`，則可連線。這是透過隧道、反向代理或公開主機名稱到達遠端 MCP 伺服器的唯一方式。
```bash
# 授予 manage 範圍：開啟儀表板 API Keys 頁面，在該金鑰上切換
# 「管理存取」（Management Access），或在建立時 POST scopes:["manage"]
# 然後從遠端 MCP 客戶端連線：
curl -i \
-H "Host: your-public-host.example" \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0"}}}' \
https://your-public-host.example/api/mcp/stream
```
沒有 manage 範圍的金鑰（或未提供 Bearer）會回傳 `403 LOCAL_ONLY`。兄弟前綴 `/api/cli-tools/runtime/*` 故意**不可繞過** — 請參閱[路由守衛層級 — Manage 範圍例外](../security/ROUTE_GUARD_TIERS.md#manage-scope-carve-out)。
## IDE 設定
請參閱 [MCP 客戶端設定](../guides/SETUP_GUIDE.md#mcp-client-configuration) 了解 Claude Desktop、Cursor、Cline 及相容 MCP 客戶端的設定方式。
---
## Essential Tools (8)
## 基礎工具（8 個）— 第一階段
| Tool | Description |
| :------------------------------ | :--------------------------------------- |
| `omniroute_get_health` | Gateway health, circuit breakers, uptime |
| `omniroute_list_combos` | All configured combos with models |
| `omniroute_get_combo_metrics` | Performance metrics for a specific combo |
| `omniroute_switch_combo` | Switch active combo by ID/name |
| `omniroute_check_quota` | Quota status per provider or all |
| `omniroute_route_request` | Send a chat completion through OmniRoute |
| `omniroute_cost_report` | Cost analytics for a time period |
| `omniroute_list_models_catalog` | Full model catalog with capabilities |
| 工具 | 範圍 | 說明 |
| :-------------------------------- | :--------------------- | :---------------------------------------------------------------- |
| `omniroute_get_health` | `read:health` | 運作時間、記憶體、斷路器、速率限制、快取統計 |
| `omniroute_list_combos` | `read:combos` | 所有已設定的組合及策略（可選指標） |
| `omniroute_get_combo_metrics` | `read:combos` | 特定組合的效能指標 |
| `omniroute_switch_combo` | `write:combos` | 啟用或停用組合 |
| `omniroute_check_quota` | `read:quota` | 已用配額／總配額、剩餘百分比、重置時間、代幣健康狀態 |
| `omniroute_route_request` | `execute:completions` | 透過 OmniRoute 路由發送聊天完成請求 |
| `omniroute_cost_report` | `read:usage` | 按期間（工作階段／日／週／月）的成本報告 |
| `omniroute_list_models_catalog` | `read:models` | 完整模型目錄，包含功能、狀態、定價 |
## Advanced Tools (8)
## 第一階段 — 搜尋
| Tool | Description |
| :--------------------------------- | :---------------------------------------------------------- |
| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree |
| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions |
| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset |
| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request |
| `omniroute_get_provider_metrics` | Detailed metrics for one provider |
| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives |
| `omniroute_explain_route` | Explain a past routing decision |
| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors |
| 工具 | 範圍 | 說明 |
| :----------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `omniroute_web_search` | `execute:search` | 透過 OmniRoute 搜尋閘道（Serper/Brave/Perplexity/Exa/Tavily/Google PSE/Linkup/SearchAPI/SearXNG）進行網路搜尋，支援容錯轉移 |
## Authentication
## 進階工具（11 個）— 第二階段
MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
| 工具 | 範圍 | 說明 |
| :----------------------------------- | :------------------------------------ | :------------------------------------------------------------------------------------ |
| `omniroute_simulate_route` | `read:health`、`read:combos` | 乾執行路由模擬，含備援樹 |
| `omniroute_set_budget_guard` | `write:budget` | 工作階段預算，可設為降級／封鎖／警示動作 |
| `omniroute_set_routing_strategy` | `write:combos` | 於執行階段更新組合策略（優先／加權／自動等） |
| `omniroute_set_resilience_profile` | `write:resilience` | 套用 `aggressive`／`balanced`／`conservative` 復原能力預設 |
| `omniroute_test_combo` | `execute:completions`、`read:combos` | 使用真實上游呼叫，對組合中的每個提供者進行即時測試 |
| `omniroute_get_provider_metrics` | `read:health` | 各提供者指標，含 p50/p95/p99 延遲與斷路器狀態 |
| `omniroute_best_combo_for_task` | `read:combos`、`read:health` | 依任務類型推薦組合，考量預算與延遲限制 |
| `omniroute_explain_route` | `read:health`、`read:usage` | 解釋為何請求被路由至某提供者（評分因素＋備援） |
| `omniroute_get_session_snapshot` | `read:usage` | 完整工作階段快照：成本、代幣、熱門模型／提供者、錯誤、預算守衛 |
| `omniroute_db_health_check` | `read:health`、`write:resilience` | 診斷（並可選自動修復）資料庫漂移，如中斷的組合參考／孤立資料列 |
| `omniroute_sync_pricing` | `pricing:write` | 從外部來源（LiteLLM）同步定價資料；支援 `dryRun` |
| Scope | Tools |
| :------------- | :----------------------------------------------- |
| `read:health` | get_health, get_provider_metrics |
| `read:combos` | list_combos, get_combo_metrics |
| `write:combos` | switch_combo |
| `read:quota` | check_quota |
| `write:route` | route_request, simulate_route, test_combo |
| `read:usage` | cost_report, get_session_snapshot, explain_route |
| `write:config` | set_budget_guard, set_resilience_profile |
| `read:models` | list_models_catalog, best_combo_for_task |
## 快取工具（2 個）
## Audit Logging
| 工具 | 範圍 | 說明 |
| :------------------------ | :------------- | :------------------------------------------------ |
| `omniroute_cache_stats` | `read:cache` | 語意快取、提示快取與冪等性統計 |
| `omniroute_cache_flush` | `write:cache` | 全域或依簽章／模型清除快取 |
Every tool call is logged to `mcp_tool_audit` with:
## 壓縮工具（13 個）
- Tool name, arguments, result
- Duration (ms), success/failure
- API key hash, timestamp
| 工具 | 範圍 | 說明 |
| :------------------------------------ | :------------------ | :------------------------------------------------------------------------------------------------------------------------- |
| `omniroute_compression_status` | `read:compression` | 壓縮設定、分析摘要與快取感知統計（包含 `analytics.mcpDescriptionCompression` 元資料） |
| `omniroute_compression_configure` | `write:compression` | 設定壓縮模式、閾值、目標比率、系統提示保留、MCP 描述壓縮開關 |
| `omniroute_set_compression_engine` | `write:compression` | 選取作用中引擎（off/caveman/rtk/stacked）與 Caveman/RTK 強度 |
| `omniroute_list_compression_combos` | `read:compression` | 列出已命名的壓縮組合及其引擎管線 |
| `omniroute_compression_combo_stats` | `read:compression` | 依壓縮組合與引擎分組的分析資料 |
| `omniroute_ccr_store` | `write:compression` | 將呼叫者隔離的內容儲存至有界限的記憶體內 CCR 存放區，並回傳標記與 `ccr://` 參考 |
| `omniroute_ccr_retrieve` | `read:compression` | 以完整、開頭、結尾、行數、grep 及統計模式擷取 CCR 內容 |
| `omniroute_ccr_inspect` | `read:compression` | 檢查呼叫者擁有的 CCR 元資料，不回傳內容 |
| `omniroute_ccr_list` | `read:compression` | 列出呼叫者擁有的 CCR 區塊之分頁元資料 |
| `omniroute_ccr_delete` | `write:compression` | 刪除呼叫者擁有的 CCR 區塊 |
| `omniroute_ccr_stats` | `read:compression` | 回報呼叫者範圍的記憶體使用量、生命週期計數器與存放區限制 |
| `omniroute_rtk_discover` | `read:compression` | 在選擇性加入的 RTK 輸出樣本中發現重複出現的雜訊 |
| `omniroute_rtk_learn` | `read:compression` | 從選擇性加入的樣本產生可供審查的 RTK 過濾器草稿 |
## Files
CCR 條目僅存在於記憶體中，重新啟動後即消失。每個區塊限制為 2 MiB，每個主體限制為 16 MiB，全域存放區限制為 64 MiB。條目預設 TTL 為 24 小時（最長七天）。完整的 MCP 擷取限制為 256 KiB；較大的區塊仍可透過範圍與 grep 模式使用。儲存、擷取、列出、檢查、刪除與統計皆以通過驗證的 API 金鑰主體進行隔離。稽核記錄包含雜湊與大小元資料，絕不包含內容。
| File | Purpose |
| :------------------------------------------- | :------------------------------------------ |
| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations |
| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport |
| `open-sse/mcp-server/auth.ts` | API key + scope validation |
| `open-sse/mcp-server/audit.ts` | Tool call audit logging |
| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers |
`omniroute_compression_status` 會將 MCP 描述壓縮分別回報於 `analytics.mcpDescriptionCompression` 之下。這些數值是對 MCP 可列出描述（`tools`、`prompts`、`resources` 與 `resourceTemplates`）的元資料大小估計值，並非提供者使用收據，並標記有 `source: "mcp_metadata_estimate"`。
### MCP 無障礙樹過濾器（v3.8.0）
與上述壓縮工具不同，OmniRoute 包含一個執行後過濾器，可在 MCP 瀏覽器／無障礙工具的**工具結果**回傳給代理之前對其進行壓縮。此過濾器本身不是一個工具 — 它會透明地作用於任何包含冗長無障礙樹或瀏覽器快照文字（≥2000 字元）的工具結果。
關鍵行為：
- 將 ≥30 行連續重複的同層兄弟行摺疊為開頭＋結尾摘要
- 保留 Playwright／電腦使用所需的 `[ref=eXX]` 錨點
- 對過大的文字（>50,000 字元）進行強制截斷，並附上導航提示
- 預期節省：瀏覽器快照承載的 **60–80%**
設定：全域設定中的 `compression.mcpAccessibility`（遷移 056）。
實作：`open-sse/services/compression/engines/mcpAccessibility/`。
完整文件：[壓縮引擎 — MCP 無障礙樹過濾器](../compression/COMPRESSION_ENGINES.md#mcp-accessibility-tree-filter)。
請參閱[壓縮引擎](../compression/COMPRESSION_ENGINES.md)與 [RTK 壓縮](../compression/RTK_COMPRESSION.md)了解這些工具背後的執行時期壓縮模型。
## 1Proxy 工具（3 個）
| 工具 | 範圍 | 說明 |
| :---------------------------- | :-------------- | :----------------------------------------------------------------------------------- |
| `omniroute_oneproxy_fetch` | `read:proxies` | 從 1proxy 市集取得免費代理（協定／國家／品質／數量過濾器） |
| `omniroute_oneproxy_rotate` | `read:proxies` | 依策略（`random`／`quality`／`sequential`）取得下一個可用代理 |
| `omniroute_oneproxy_stats` | `read:proxies` | 池統計、同步狀態、依協定與國家的分佈 |
## 記憶工具（3 個）
定義於 `open-sse/mcp-server/tools/memoryTools.ts`。認證／範圍透過標準 MCP 範圍管線強制執行。
| 工具 | 範圍 | 說明 |
| :-------------------------- | :-------------- | :----------------------------------------------------------------------------- |
| `omniroute_memory_search` | `read:memory` | 依查詢／類型／API 金鑰搜尋記憶，並執行代幣預算限制 |
| `omniroute_memory_add` | `write:memory` | 新增記憶條目（`factual`／`episodic`／`procedural`／`semantic`） |
| `omniroute_memory_clear` | `write:memory` | 清除某 API 金鑰的記憶，可選擇依類型或 `olderThan` 時間戳過濾 |
## 技能工具（4 個）
定義於 `open-sse/mcp-server/tools/skillTools.ts`。由 `src/lib/skills/registry` 與 `src/lib/skills/executor` 支援。
| 工具 | 範圍 | 說明 |
| :------------------------------ | :---------------- | :----------------------------------------------------------------------------- |
| `omniroute_skills_list` | `read:skills` | 列出已註冊的技能，可依 API 金鑰、名稱或啟用狀態過濾 |
| `omniroute_skills_enable` | `write:skills` | 依 ID 啟用或停用特定技能 |
| `omniroute_skills_execute` | `execute:skills` | 以提供的輸入執行技能，並回傳執行記錄 |
| `omniroute_skills_executions` | `read:skills` | 列出近期技能執行歷史 |
## Notion 上下文來源（6 個）
定義於 `open-sse/mcp-server/tools/notionTools.ts`。代幣儲存於 `key_value` 表中，透過 `src/lib/db/notion.ts` 操作。REST 客戶端位於 `src/lib/notion/api.ts`。設定 API 位於 `src/app/api/settings/notion/route.ts`。儀表板 UI 位於 `src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx`。
在端點儀表板的**上下文來源**頁籤中設定你的 Notion 整合代碼，或透過 REST API 設定：
```bash
# 設定代碼
curl -X POST http://localhost:20128/api/settings/notion \
-H "Content-Type: application/json" \
-d '{"token": "ntn_..."}'
# 檢查狀態
curl http://localhost:20128/api/settings/notion
# 斷開連線
curl -X DELETE http://localhost:20128/api/settings/notion
```
| 工具 | 範圍 | 說明 |
| :----------------------------- | :-------------- | :------------------------------------------------------------- |
| `notion_search` | `read:notion` | 在所有頁面與資料庫中進行全文搜尋 |
| `notion_get_page` | `read:notion` | 依 ID 取得頁面及其屬性 |
| `notion_list_block_children` | `read:notion` | 列出頁面或區塊的子區塊 |
| `notion_query_database` | `read:notion` | 以過濾器、排序與分頁查詢資料庫 |
| `notion_get_database` | `read:notion` | 依 ID 取得資料庫架構 |
| `notion_append_blocks` | `write:notion` | 將子區塊附加至父區塊（每次請求最多 100 個） |
## Agent 技能目錄工具（3 個）
定義於 `open-sse/mcp-server/tools/agentSkillTools.ts`。由 `src/lib/agentSkills/catalog` 支援。這些工具將 42 個項目的 Agent 技能文件目錄暴露給 MCP 客戶端與外部代理。範圍：`read:catalog`。
| 工具 | 範圍 | 說明 |
| :---------------------------------- | :-------------- | :--------------------------------------------------------------------------------------------------------------- |
| `omniroute_agent_skills_list` | `read:catalog` | 列出全部 42 個 agent 技能，可選 `category`（api\|cli）與 `area` 過濾器；回傳元資料＋覆蓋率 |
| `omniroute_agent_skills_get` | `read:catalog` | 依標準 `id` 取得單一技能的完整元資料＋SKILL.md 內容 |
| `omniroute_agent_skills_coverage` | `read:catalog` | 覆蓋率統計：22 個 API 與 20 個 CLI 技能中有多少個在檔案系統上擁有 SKILL.md 檔案，與目錄總數比較 |
請參閱 [AGENT-SKILLS.md](./AGENT-SKILLS.md) 了解完整目錄及外部代理如何使用。
## 相關框架（v3.8.0）
上述 MCP 工具清單（104 個唯一工具，由 `countUniqueMcpTools()` 計算）的範圍故意限定於執行時期路由／快取／壓縮／記憶／技能／代理／上下文來源操作。兩個相鄰框架與 MCP 伺服器一同於 v3.8.0 提供，並分別記錄：
### Cloud Agents
Cloud Agents 是行程外的 AI 編碼代理（codex-cloud、devin、jules），透過與 LLM 提供者相同的連線模型接入 OmniRoute。它們透過自己的 REST 介面（`/api/v1/agents/*`）暴露，且**不屬於** MCP 工具目錄的一部分 — 呼叫 Cloud Agent 不會消耗 MCP 範圍。
- 實作：`src/lib/cloudAgent/`（`registry.ts`、`agents/codex-cloud.ts`、`agents/devin.ts`、`agents/jules.ts`）。
- 生命週期：`createTask`、`getStatus`、`approvePlan`、`sendMessage`、`listSources`。
- 文件：[docs/frameworks/CLOUD_AGENT.md](./CLOUD_AGENT.md)。
### Guardrails
Guardrails 是在聊天管線中套用的執行前／執行後過濾器（vision-bridge、pii-masker、prompt-injection）。它們在抵達 MCP 工具／路由層之前執行，並將結構化違規記錄發送至稽核管線；它們不是以 MCP 工具的形式被呼叫。
- 實作：`src/lib/guardrails/`。
- 文件：[docs/security/GUARDRAILS.md](../security/GUARDRAILS.md)。
當偵錯一個看似被封鎖的 MCP 呼叫時，請同時檢查 MCP 稽核日誌（`scope_denied:*` 條目）與 guardrails 稽核軌跡 — 請求可能在抵達 MCP 範圍強制執行層**之前**就被 guardrail 拒絕。
---
## REST API 端點
| 端點 | 方法 | 說明 | 認證 |
| :----------------------- | :--------------------- | :--------------------------------------------------------------------------------------------- | :-------------------------- |
| `/api/mcp/status` | `GET` | 伺服器狀態：心跳、HTTP 傳輸狀態、稽核活動摘要 | 管理（工作階段／管理員） |
| `/api/mcp/tools` | `GET` | 工具目錄（名稱、說明、範圍、階段、來源端點） | 管理 |
| `/api/mcp/sse` | `GET` / `POST` | SSE 傳輸端點（由 `mcpEnabled` + `mcpTransport === "sse"` 閘控） | API 金鑰 + 範圍 |
| `/api/mcp/stream` | `POST`/`GET`/`DELETE` | 可串流 HTTP 傳輸（使用 `mcp-session-id` 標頭；`DELETE` 結束工作階段） | API 金鑰 + 範圍 |
| `/api/mcp/audit` | `GET` | 來自 `mcp_tool_audit` 的稽核日誌條目（過濾器：`limit`、`offset`、`tool`、`success`、`apiKeyId`） | 管理 |
| `/api/mcp/audit/stats` | `GET` | 彙總稽核統計（`totalCalls`、`successRate`、`avgDurationMs`、熱門工具） | 管理 |
原始檔案：`src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts`。
SSE 與 Streamable HTTP 兩種傳輸層在設定中啟用 MCP 伺服器（`mcpEnabled`）並選取適當的 `mcpTransport` 之前，皆處於封鎖狀態。若設定了錯誤的傳輸層，路由會回傳 HTTP 400 並提示切換設定。
---
## 認證與範圍
MCP 工具透過 API 金鑰範圍進行認證。範圍強制執行集中於 `open-sse/mcp-server/scopeEnforcement.ts`。每個工具需要特定的範圍：
| 範圍 | 工具 |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `read:health` | `get_health`、`get_provider_metrics`、`simulate_route`、`explain_route`、`best_combo_for_task`、`db_health_check` |
| `read:combos` | `list_combos`、`get_combo_metrics`、`simulate_route`、`best_combo_for_task`、`test_combo` |
| `write:combos` | `switch_combo`、`set_routing_strategy` |
| `read:quota` | `check_quota` |
| `read:usage` | `cost_report`、`get_session_snapshot`、`explain_route` |
| `read:models` | `list_models_catalog` |
| `execute:completions` | `route_request`、`test_combo` |
| `execute:search` | `web_search` |
| `write:budget` | `set_budget_guard` |
| `write:resilience` | `set_resilience_profile`、`db_health_check` |
| `pricing:write` | `sync_pricing` |
| `read:cache` | `cache_stats` |
| `write:cache` | `cache_flush` |
| `read:compression` | `compression_status`、`list_compression_combos`、`compression_combo_stats` |
| `write:compression` | `compression_configure`、`set_compression_engine` |
| `read:proxies` | `oneproxy_fetch`、`oneproxy_rotate`、`oneproxy_stats` |
| `read:notion` | `notion_search`、`notion_list_databases`、`notion_get_database`、`notion_query_database`、`notion_read` |
| `write:notion` | `notion_append_blocks` |
| `read:memory` | `memory_search` |
| `write:memory` | `memory_add`、`memory_clear` |
| `read:skills` | `skills_list`、`skills_executions` |
| `write:skills` | `skills_enable` |
| `execute:skills` | `skills_execute` |
| `read:catalog` | `agent_skills_list`、`agent_skills_get`、`agent_skills_coverage` |
支援萬用字元範圍：`read:*` 授予所有讀取範圍，`*` 授予完整存取權限。
---
## 環境變數
| 變數 | 預設值 | 用途 |
| :---------------------------------------- | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `OMNIROUTE_BASE_URL` | `http://localhost:20128` | MCP 伺服器在呼叫 OmniRoute 內部 API 時使用的基礎 URL |
| `OMNIROUTE_API_KEY` | （空） | 轉發為 `Authorization: <key>` 至內部 API 呼叫的 API 金鑰 |
| `OMNIROUTE_MCP_ENFORCE_SCOPES` | `false`（僅 `"true"` 啟用） | 啟用時，缺少範圍會拒絕工具呼叫，並在稽核日誌中記錄 `scope_denied:<原因>` |
| `OMNIROUTE_MCP_SCOPES` | （空） | 逗號分隔的範圍允許清單，視為預設「可用」（用於呼叫者未提供自身範圍時） |
| `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS` | （未設定＝開啟） | 設為 `0/false/off/no` 時，在註冊時停用 MCP 描述壓縮 |
| `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION` | （未設定＝開啟） | 上述相同開關的別名 |
| `MCP_TOOL_DENY` | （未設定＝無過濾） | 逗號分隔的工具名稱，從 `tools/list` 中移除（工具基數減少 — 請參閱下方） |
| `MCP_TOOL_ALLOW` | （未設定＝無過濾） | 逗號分隔的工具名稱，僅保留這些工具（允許清單模式 — 請參閱下方） |
| `DATA_DIR` | `~/.omniroute` | 心跳檔案寫入至 `${DATA_DIR}/runtime/mcp-heartbeat.json` |
---
## 描述壓縮
MCP 工具、提示與資源註冊表可在註冊／列出時壓縮描述，以減少暴露給客戶端的元資料大小（進而降低提示上下文成本）。實作位於 `open-sse/mcp-server/descriptionCompressor.ts`，並透過 `createMcpServer()` 中的 `compressMcpRegistryMetadata` 接入 MCP 伺服器。
- 壓縮使用 Caveman 規則集（`getRulesForContext("all", "full")`）對描述文字進行壓縮，並保留區塊提取（程式碼跨度、圍欄區塊等），以確保結構性內容不被改變。
- 可透過 `key_value` 設定表中的 `compression.mcpDescriptionCompressionEnabled` 值（預設：啟用）依部署切換 — 在 UI 中顯示為**分析 → MCP 描述壓縮**。
- 可透過 `OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS=false` 或 `OMNIROUTE_MCP_DESCRIPTION_COMPRESSION=false` 全域切換。
- 即時統計資料透過 `omniroute_compression_status` 在 `analytics.mcpDescriptionCompression` 下呈現，並標記為 `source: "mcp_metadata_estimate"`，以與真實的提供者使用收據區分。
---
## 工具基數減少（F4.3）
描述壓縮會縮小每個工具的元資料；**工具基數減少**則更進一步，減少**宣告的工具總數**。在 `tools/list` 清單中廣告較少的工具，可降低客戶端模型為工具目錄所支付的每次請求代幣成本（「第 5 層」壓縮）。實作為一個純粹、無狀態的過濾器，位於 `open-sse/mcp-server/toolCardinality.ts`（`reduceToolManifest`），接入 `createMcpServer()`（`open-sse/mcp-server/server.ts`）的註冊迴圈。
**選擇性加入，預設關閉。** 過濾器僅在至少設定兩個環境變數之一時才執行；若兩者皆未設定，則所有 104 個工具保持不變地被宣告。
| 變數 | 模式 |
| :---------------- | :----------------------------------------------------------------------------------------- |
| `MCP_TOOL_DENY` | 黑名單 — 逗號分隔的工具名稱，始終從 `tools/list` 中移除 |
| `MCP_TOOL_ALLOW` | 允許清單 — 逗號分隔的工具名稱；僅這些工具保留，其他全部移除 |
`deny` 優先於 `allow`。名稱以逗號分隔，前後空白被去除，空條目被忽略。範例：
```bash
# 從目錄中移除兩個工具
MCP_TOOL_DENY="omniroute_get_health,omniroute_list_combos" omniroute --mcp
# 僅宣告路由＋配額工具（允許清單模式）
MCP_TOOL_ALLOW="omniroute_route_request,omniroute_check_quota" omniroute --mcp
```
**被過濾的工具如何移除：** 註冊始終成功；設定檔拒絕的工具隨後會在 MCP SDK 控制代碼上被 `.disable()`，因此它永遠不會出現在 `tools/list` 中，但接線保持完整（乾淨的啟用／停用，無需重新註冊）。設定檔解析器為 `readMcpToolProfileFromEnv(process.env)`，當兩個變數皆為空時回傳 `null`（不過濾）。
`reduceToolManifest` 背後更豐富的 `ToolProfile` 型別也支援範圍交集過濾（`allowScopes`，含 `read:*` 風格的萬用字元比對）與確定性的 `maxTools` 上限，但這兩個控制項需要在註冊時取得完整清單，且**目前尚未透過環境變數暴露**（`tools/list` 層級的鉤子為已追蹤的後續功能）。`estimateManifestTokens()` 可用於比較減少前後的工具清單代幣成本。
---
## 執行時期心跳
stdio 傳輸層每 5 秒將存活狀態持續寫入 `${DATA_DIR}/runtime/mcp-heartbeat.json`。儀表板（`/api/mcp/status`）讀取此檔案加上 PID 存活狀態以推斷 `online` 狀態。HTTP 傳輸層則從行程內的 `getMcpHttpStatus()` 回報狀態（不寫入檔案）。
心跳快照包含以下內容：
```json
{
"pid": 12345,
"startedAt": "2026-05-13T12:34:56.000Z",
"lastHeartbeatAt": "2026-05-13T12:35:01.000Z",
"version": "1.8.1",
"transport": "stdio",
"scopesEnforced": false,
"allowedScopes": [],
"toolCount": 43
}
```
---
## 稽核日誌
每個工具呼叫均由 `open-sse/mcp-server/audit.ts` 記錄至 SQLite `mcp_tool_audit` 表：
- 工具名稱、引數（依各工具的 `auditLevel` 進行雜湊／截斷）、結果
- 持續時間（毫秒）、成功／失敗標記、錯誤訊息（適用時）
- API 金鑰雜湊、時間戳
- 範圍拒絕記錄為 `scope_denied:<原因>`，附帶缺少的範圍清單
使用儀表板或 `/api/mcp/audit` 與 `/api/mcp/audit/stats` REST 端點來檢查近期呼叫。
---
## 檔案
| 檔案 | 用途 |
| :---------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `open-sse/mcp-server/server.ts` | MCP 伺服器工廠、stdio 入口點、範圍化工具註冊 |
| `open-sse/mcp-server/httpTransport.ts` | SSE + Streamable HTTP 傳輸層（工作階段管理） |
| `open-sse/mcp-server/scopeEnforcement.ts` | 工具範圍評估與呼叫者解析 |
| `open-sse/mcp-server/audit.ts` | 工具呼叫稽核日誌（`mcp_tool_audit`） |
| `open-sse/mcp-server/runtimeHeartbeat.ts` | stdio 心跳寫入器（`mcp-heartbeat.json`） |
| `open-sse/mcp-server/descriptionCompressor.ts` | 工具／提示／資源註冊表的描述壓縮 |
| `open-sse/mcp-server/schemas/tools.ts` | Zod 架構＋工具註冊表（`MCP_TOOLS`，34 個條目） |
| `open-sse/mcp-server/tools/advancedTools.ts` | 第二階段＋快取＋1proxy 工具處理器 |
| `open-sse/mcp-server/tools/compressionTools.ts` | 壓縮工具處理器 |
| `open-sse/mcp-server/tools/memoryTools.ts` | 記憶工具定義（3 個工具） |
| `open-sse/mcp-server/tools/skillTools.ts` | 技能工具定義（4 個工具） |
| `open-sse/mcp-server/tools/notionTools.ts` | Notion 上下文來源工具定義（6 個工具） |
| `open-sse/mcp-server/tools/gamificationTools.ts` | 遊戲化工具定義（8 個工具） |
| `open-sse/mcp-server/tools/pluginTools.ts` | 外掛註冊與管理工具（8 個工具） |
| `src/app/api/mcp/status/route.ts` | `/api/mcp/status` 端點 |
| `src/app/api/mcp/tools/route.ts` | `/api/mcp/tools` 端點 |
| `src/app/api/mcp/sse/route.ts` | `/api/mcp/sse` SSE 傳輸路由 |
| `src/app/api/mcp/stream/route.ts` | `/api/mcp/stream` Streamable HTTP 傳輸路由 |
| `src/app/api/mcp/audit/route.ts` | `/api/mcp/audit` 稽核日誌查詢 |
| `src/app/api/mcp/audit/stats/route.ts` | `/api/mcp/audit/stats` 彙總稽核指標 |
| `src/lib/notion/api.ts` | Notion REST API 客戶端（重試、逾時、錯誤分類） |
| `src/lib/db/notion.ts` | Notion 代碼持久化（`key_value` 表） |
| `src/app/api/settings/notion/route.ts` | Notion 設定 API（GET/POST/DELETE） |
| `src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx` | Notion 代碼管理 UI |
| `tests/unit/notion-api.test.ts` | Notion API 客戶端測試（7 個） |
| `tests/unit/notion-tools.test.ts` | Notion 工具範圍強制執行測試（10 個） |
| `tests/unit/db/notion.test.mjs` | Notion DB 模組測試（3 個） |

307
docs/i18n/zh-TW/docs/guides/FEATURES.md
View File

@@ -1,269 +1,328 @@
# OmniRoute — Dashboard Features Gallery (中文 (簡體))
---
title: "OmniRoute — 儀表板功能總覽"
version: 3.8.40
lastUpdated: 2026-06-28
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇧🇩 [bn](../../bn/docs/FEATURES.md) · 🇨🇿 [cs](../../cs/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇮🇷 [fa](../../fa/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇮🇳 [gu](../../gu/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇮🇳 [hi](../../hi/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇮🇳 [mr](../../mr/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇰🇪 [sw](../../sw/docs/FEATURES.md) · 🇮🇳 [ta](../../ta/docs/FEATURES.md) · 🇮🇳 [te](../../te/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇹🇷 [tr](../../tr/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇵🇰 [ur](../../ur/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md)
# OmniRoute — 儀表板功能總覽
🌐 **主要 README 翻譯：** 🇺🇸 [English](../README.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/README.md) | 🇪🇸 [Español](../i18n/es/README.md) | 🇫🇷 [Français](../i18n/fr/README.md) | 🇮🇹 [Italiano](../i18n/it/README.md) | 🇷🇺 [Русский](../i18n/ru/README.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](../i18n/de/README.md) | 🇮🇳 [हिन्दी](../i18n/in/README.md) | 🇹🇭 [ไทย](../i18n/th/README.md) | 🇺🇦 [Українська](../i18n/uk-UA/README.md) | 🇸🇦 [العربية](../i18n/ar/README.md) | 🇯🇵 [日本語](../i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/README.md) | 🇧🇬 [Български](../i18n/bg/README.md) | 🇩🇰 [Dansk](../i18n/da/README.md) | 🇫🇮 [Suomi](../i18n/fi/README.md) | 🇮🇱 [עברית](../i18n/he/README.md) | 🇭🇺 [Magyar](../i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/README.md) | 🇰🇷 [한국어](../i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/README.md) | 🇳🇱 [Nederlands](../i18n/nl/README.md) | 🇳🇴 [Norsk](../i18n/no/README.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/README.md) | 🇷🇴 [Română](../i18n/ro/README.md) | 🇵🇱 [Polski](../i18n/pl/README.md) | 🇸🇰 [Slovenčina](../i18n/sk/README.md) | 🇸🇪 [Svenska](../i18n/sv/README.md) | 🇵🇭 [Filipino](../i18n/phi/README.md) | 🇨🇿 [Čeština](../i18n/cs/README.md)
OmniRoute 儀表板各區塊的視覺化導覽。
> 📅 **最後更新：** 2026-06-28 — **v3.8.40**
---
Visual guide to every section of the OmniRoute dashboard.
## ✨ v3.8.0 重點功能
v3.7.x → v3.8.0 版本週期新增了零設定自動路由、新供應商、OAuth 流程、更深的抗災能力以及更豐富的 CLI 體驗。以下為重點功能——完整細節請參閱稍後章節及連結的規格文件。
- 🤖 **Auto Combo / 零設定自動路由** — 使用前綴 `auto/coding`、`auto/fast`、`auto/cheap`、`auto/offline`、`auto/smart`、`auto/lkgp`。由 9 因子評分引擎和 4 個精選**模式包**（快速出貨、節省成本、品質優先、離線友善）驅動
- 🆕 **Command Code 供應商**（#2199）— 一級支援，含模型目錄及配額追蹤
- 🆕 **Z.AI 供應商** — 新增免費方案供應商，附配額標籤
- 🎬 **KIE 媒體擴展** — 擴充目錄，納入影片生成模型
- 🔐 **Windsurf + Devin CLI OAuth 流程**（#2168）— 端到端瀏覽器登入
- 🆓 **8 個新的免費供應商** — LLM7、Lepton、UncloseAI、BazaarLink、Completions、Enally、FreeTheAi、Command Code
- 🎯 **清單感知分層路由 W1–W4** — 供應商清單驅動加權層級選擇
- 🎨 **Cursor 完整 OpenAI 相容性** — 工具呼叫、串流、階段管理端到端
- 📊 **Cursor Pro 方案用量** — 在供應商限制儀表板中顯示配額與週期數據
- ⚡ **服務層級 breakdown / Codex 快速層分析** — 各層級用量可視化
- 📌 **每階段黏性路由** — Codex 階段在輪次間固定使用相同帳戶
- 🔊 **Inworld TTS 增強** — 語音目錄、串流及延遲改善
- 🔑 **Kiro 無頭驗證** — 透過本機 `kiro-cli` SQLite 儲存庫登入，無需瀏覽器
- 📉 **DeepSeek 配額與限制監控** — 在儀表板顯示每日/每月用量
- 🔄 **重設感知路由策略** — Combo 現在優先選用配額視窗最早重置的帳戶
- ⏱️ **`fallbackDelayMs`** 與**動態工具限制偵測** — 更精細的備援時機 + 各供應商工具數量限制
- 🔧 **背景模式降級（Responses API）** — 當上游缺乏背景輪詢能力時，降級為同步模式並附上結構化警告
- 🚦 **各供應商 429 分類** + `useUpstream429BreakerHints` 開關 — 利用上游速率限制提示來微調斷路器行為
- 🩺 **模型冷卻儀表板** — 觀察各模型的鎖定狀態，並可從 UI 手動重新啟用
- 🔒 **MITM 動態 Linux 憑證偵測** — 適用於 Debian/Ubuntu、Fedora/RHEL、Arch 及其他發行版
- 💻 **CLI 增強套件** — 20 多個指令，包含 `omniroute providers`、`omniroute combos`、`omniroute doctor`、`omniroute setup`
- 🔍 **Qdrant 嵌入模型探索** — 自動向量儲存模型探測
- 🔑 **API 金鑰 / Bearer 金鑰搭配 `manage` 範圍** — 透過 API 以程式方式執行管理操作
- 🏥 **Combo 目標健康度分析** + **結構化 Combo 建構器** — 各目標健康度及 UI 建構器，用於組合 `(供應商, 模型, 連線)` 步驟
- 🤝 **GitLab Duo OAuth 供應商** — 使用 GitLab 憑證登入
- 🧠 **推理重播快取** — 混合記憶體 + SQLite 持久化推理軌跡
📚 **相關文件：** [技能框架](../frameworks/SKILLS.md) · [記憶系統](../frameworks/MEMORY.md) · [雲端代理](../frameworks/CLOUD_AGENT.md) · [Webhook](../frameworks/WEBHOOKS.md) · [推理重播快取](../routing/REASONING_REPLAY.md)
---
## 🔌 Providers
## 🔌 供應商
管理 AI 供應商連線：OAuth 供應商（Claude Code、Codex）、API 金鑰供應商（Groq、DeepSeek、OpenRouter）以及免費供應商（Qoder、Kiro）。Kiro 帳戶包含額度餘額追蹤——剩餘額度、總配額及續約日期，均可在「儀表板 → 用量」中檢視。
![Providers Dashboard](screenshots/01-providers.png)
OpenRouter 連線可在「進階設定」中儲存各連線的 `preset`。設定後，OmniRoute 會將其作為 OpenRouter 頂層請求欄位發送，例如 `"preset": "email-copywriter"`，除非客戶端請求已提供自己的 `preset`。
![供應商儀表板](../screenshots/01-providers.png)
---
## 🎨 Combos
## 🎨 Combo
Create model routing combos with 13 strategies: priority, weighted, round-robin, random, least-used, cost-optimized, strict-random, auto, fill-first, p2c, lkgp, context-optimized, and **context-relay**. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
使用 17 種策略建立模型路由組合：優先、加權、先填滿、輪詢、p2c（二選一）、隨機、最少使用、成本最佳化、重設感知、重設視窗、餘裕空間、嚴格隨機、自動、lkgp（最後已知良好供應商）、情境最佳化、情境轉接，以及**融合**（並行分發給多個模型，再由評判模型合成一個答案）。每個組合可串聯多個模型並自動備援，內含快速範本與就緒檢查。
Recent combo improvements:
近期 Combo 改善：
- **Structured combo builder** — create each step by selecting provider, model, and exact account/connection
- **Repeated provider support** — reuse the same provider many times in one combo as long as the `(provider, model, connection)` tuple is unique
- **Combo target health** — analytics and health surfaces now distinguish individual combo targets/steps instead of collapsing everything into model strings
- **Composite tier ordering** — `defaultTier -> fallbackTier` now influences runtime execution/fallback order for top-level combo steps
- **結構化 Combo 建構器** — 透過選擇供應商、模型及精確帳戶/連線來建立每個步驟
- **重複供應商支援** — 只要 `(供應商, 模型, 連線)` 組合唯一，即可在同一組合中多次重複使用相同供應商
- **Combo 目標健康度** — 分析與健康度面板現在可區分個別 Combo 目標/步驟，而非全部收攏為模型字串
- **複合層級排序** — `defaultTier -> fallbackTier` 現在會影響頂層 Combo 步驟的執行/備援順序
![Combos Dashboard](screenshots/02-combos.png)
![Combo 儀表板](../screenshots/02-combos.png)
---
## 📊 Analytics
## 📊 分析
Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
全面的用量分析，包含 Token 消耗、成本估算、活動熱圖、每週分佈圖表及各供應商 breakdown。
![Analytics Dashboard](screenshots/03-analytics.png)
![分析儀表板](../screenshots/03-analytics.png)
---
## 🏥 System Health
## 🏥 系統健康度
Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, provider circuit breaker states, active quota-monitored sessions, and combo target health.
即時監控：運作時間、記憶體、版本、延遲百分位數（p50/p95/p99）、快取統計、供應商斷路器狀態、活躍配額監控階段及 Combo 目標健康度。
![Health Dashboard](screenshots/04-health.png)
![健康度儀表板](../screenshots/04-health.png)
---
## 🔧 Translator Playground
## 🔧 轉換器測試區
Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
四種模式用於除錯 API 轉換：**測試區**（格式轉換器）、**聊天測試器**（即時請求）、**測試平台**（批次測試）及**即時監控**（即時串流）。
![Translator Playground](screenshots/05-translator.png)
![轉換器測試區](../screenshots/05-translator.png)
---
## 🎮 Model Playground _(v2.0.9+)_
## 🎮 模型測試區 _（v2.0.9+）_
Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
直接從儀表板測試任何模型。選擇供應商、模型及端點，使用 Monaco Editor 編寫提示詞，即時串流接收回應，可中途中止並檢視時間指標。
---
## 🎨 Themes _(v2.0.5+)_
## 🎨 主題 _（v2.0.5+）_
Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
可自訂的儀表板色彩主題。從 7 個預設顏色（珊瑚、藍、紅、綠、紫罗兰、橙、青）中選擇，或透過挑選任意十六進位色碼建立自訂主題。支援淺色、深色及系統模式。
---
## ⚙️ Settings
## ⚙️ 設定
Comprehensive settings panel with tabs:
全面的設定面板，包含 **7 個分頁**：
- **General** — System storage, backup management (export/import database)
- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
- **Routing** — Model aliases, background task degradation
- **Resilience** — Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring, **Context Relay** handoff threshold and summary model configuration
- **Advanced** — Configuration overrides, configuration audit trail, fallback degradation mode
- **一般** — 系統儲存、備份管理（匯出/匯入資料庫）
- **外觀** — 主題選擇器（深色/淺色/系統）、色彩主題預設與自訂顏色、健康度記錄可見度、側邊欄項目與群組分隔線可見度控制、端點通道可見度控制
- **AI** — AI 助手功能、預設路由預設（Auto Combo `auto/coding`、`auto/fast`、`auto/cheap`、`auto/smart`）、推理重播快取及技能/記憶開關
- **安全性** — API 端點保護、自訂供應商封鎖、IP 過濾、階段資訊
- **路由** — 模型別名、背景任務降級、清單感知分層路由（W1–W4）、`fallbackDelayMs`、每階段黏性路由
- **抗災能力** — 速率限制持久化、斷路器調校、自動停用被封帳戶、供應商到期監控、**Context Relay** 交接門檻與摘要模型配置、各供應商 429 分類及 `useUpstream429BreakerHints` 開關、模型冷卻
- **進階** — 配置覆寫、配置審計軌跡、備援降級模式、Responses API 背景模式降級
![Settings Dashboard](screenshots/06-settings.png)
![設定儀表板](../screenshots/06-settings.png)
---
## 🔧 CLI Tools
## 🔧 CLI 工具
One-click configuration for AI coding tools: Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
一鍵配置 AI 程式碼工具：Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline、Continue、Cursor 及 Factory Droid。功能包含自動化配置套用/重置、連線設定檔及模型對應。
![CLI Tools Dashboard](screenshots/07-cli-tools.png)
![CLI 工具儀表板](../screenshots/07-cli-tools.png)
---
## 🤖 CLI Agents _(v2.0.11+)_
## 🤖 CLI 代理 _（v2.0.11+）_
Dashboard for discovering and managing CLI agents. Shows a grid of 17 built-in agents (Codex, Claude, Goose, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp, **Windsurf**, **Devin CLI**, **Kimi Coding**, **Command Code**) with:
用於探索與管理 CLI 代理的儀表板。顯示 16 個內建代理的網格（Codex、Claude、Goose、OpenClaw、Aider、OpenCode、Cline、ForgeCode、Amazon Q、Open Interpreter、Cursor CLI、Warp、**Windsurf**、**Devin CLI**、**Kimi Coding**、**Command Code**），包含：
- **Installation status** — Installed / Not Found with version detection
- **Protocol badges** — stdio, HTTP, etc.
- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
- **安裝狀態** — 已安裝 / 未找到，含版本偵測
- **協定徽章** — stdio、HTTP 等
- **自訂代理** — 透過表單註冊任何 CLI 工具（名稱、二進位檔、版本指令、啟動參數）
- **CLI 指紋比對** — 各供應商開關，用於比對原生 CLI 請求特徵，降低被封風險同時保留代理 IP
- **OAuth 支援代理** — Windsurf 與 Devin CLI 現使用瀏覽器 OAuth 流程進行驗證（v3.8.0+）
---
## 🔗 Context Relay _(v3.5.5+)_
## 🔗 Context Relay _（v3.5.5+）_
A combo strategy that preserves session continuity when account rotation happens mid-conversation. Before the active account is exhausted, OmniRoute generates a structured handoff summary in the background. After the next request resolves to a different account, the summary is injected as a system message so the new account continues with full context.
一種 Combo 策略，可在對話中途發生帳戶輪換時保持階段連續性。在目前帳戶額度耗盡前，OmniRoute 會在背景產生結構化的交接摘要。當下一次請求解析到不同帳戶時，該摘要會作為系統訊息注入，使新帳戶能銜接完整上下文。
Configurable via combo-level or global settings:
可透過 Combo 層級或全域設定調整：
- **Handoff Threshold** — Quota usage percentage that triggers summary generation (default 85%)
- **Max Messages For Summary** — How much recent history to condense
- **Summary Model** — Optional override model for generating the handoff summary
- **交接門檻** — 觸發摘要產生的配額使用百分比（預設 85%）
- **摘要最大訊息數** — 濃縮多少近期對話歷史
- **摘要模型** — 可選的覆寫模型，用於產生交接摘要
Currently supports Codex account rotation. See [Context Relay documentation](features/context-relay.md).
目前支援 Codex 帳戶輪換。請參閱 [Context Relay 文件](../architecture/ARCHITECTURE.md)。
---
## 🛡️ Proxy Hardening _(v3.5.5+)_
## 🗜️ 提示詞壓縮 _（v3.7.9+）_
Comprehensive proxy configuration enforcement across the entire request pipeline:
「上下文與快取」現在有專屬頁面顯示 Caveman、RTK 及壓縮組合：
- **Token Health Check** — Background OAuth refresh now resolves proxy config per connection, preventing failures in proxy-required environments
- **API Key Validation** — Provider key validation (`POST /api/providers/validate`) routes through `runWithProxyContext`, honoring provider-level and global proxy settings
- **undici Dispatcher Fix** — Proxy dispatchers use undici's own fetch implementation instead of Node's built-in fetch, resolving `invalid onRequestStart method` errors on Node.js 22
- **Node.js Version Detection** — Login page proactively detects incompatible Node.js versions (24+) and displays a warning banner with instructions to use Node 22 LTS
- **Caveman** — 語言感知規則包、預覽、輸出模式控制及分析
- **RTK** — 指令感知壓縮，適用於 shell、git、測試、建置、套件、Docker、基礎設施、JSON 及堆疊追蹤輸出
- **壓縮組合** — 命名管線（如 `rtk -> caveman`）可指派給路由組合；預設疊加數學平均達到約 **89%**，當兩套引擎都啟用時，可節省 **78–95%** 的合格上下文
- **原始輸出復原** — 可選的 RTK 脫敏原始輸出指標，用於除錯壓縮失敗
請參閱 [壓縮指南](../compression/COMPRESSION_GUIDE.md)、[RTK 壓縮](../compression/RTK_COMPRESSION.md) 及 [壓縮引擎](../compression/COMPRESSION_ENGINES.md)。
---
## 📧 Email Privacy Masking _(v3.5.6+)_
## 🛡️ 代理強化 _（v3.5.5+）_
OAuth account emails are now masked in the provider dashboard (e.g. `di*****@g****.com`) to prevent accidental exposure when sharing screenshots or recording demos. The full email address remains accessible via hover tooltip (`title` attribute).
全面代理設定強制執行，涵蓋整個請求管線：
- **Token 健康檢查** — 背景 OAuth 重新整理現在會依連線解析代理設定，防止在需要代理的環境中發生失敗
- **API 金鑰驗證** — 供應商金鑰驗證（`POST /api/providers/validate`）會經由 `runWithProxyContext` 路由，遵循供應商層級與全域代理設定
- **undici Dispatcher 修正** — 代理 dispatcher 使用 undici 自身的 fetch 實作而非 Node 內建 fetch，解決 Node.js 22 上的 `invalid onRequestStart method` 錯誤
- **Node.js 版本偵測** — 登入頁面主動偵測不相容的 Node.js 版本（24+），並顯示警告橫幅，提示使用 Node 22 LTS
---
## 👁️ Model Visibility Toggle _(v3.5.6+)_
## 📧 電子郵件隱私遮罩 _（v3.5.6+）_
The provider page model list now includes:
- **Real-time search/filter bar** — Quickly find specific models
- **Per-model visibility toggle** (👁 icon) — Hidden models are grayed out and excluded from the `/v1/models` catalog
- **Active-count badge** (`N/M active`) — Shows at a glance how many models are enabled vs total
OAuth 帳戶電子郵件預設會遮罩（例如 `di*****@g****.com`），防止在分享螢幕截圖或錄製示範時意外暴露。使用「設定 → 外觀 → 帳戶電子郵件可見度」可在供應商、Combo、記錄、配額及測試區等畫面中，全域顯示或隱藏完整帳戶郵件。
---
## 🔧 OAuth Env Repair _(v3.6.1+)_
## 👁️ 模型可見度開關 _（v3.5.6+）_
One-click "Repair env" action for OAuth providers that restores missing environment variables and fixes broken auth state. Accessible from `Dashboard → Providers → [OAuth Provider] → Repair env`. Automatically detects and repairs:
供應商頁面的模型列表現在包含：
- Missing OAuth client credentials
- Corrupted env file entries
- Backup path sanitization
- **即時搜尋/篩選列** — 快速尋找特定模型
- **各模型可見度開關**（👁 圖示）— 隱藏的模型會變灰，並從 `/v1/models` 目錄中排除
- **活躍數量徽章**（`N/M 活躍`）— 一目了然顯示啟用模型數量 vs 總數
---
## 🗑️ Uninstall / Full Uninstall _(v3.6.2+)_
## 🔧 OAuth 環境修復 _（v3.6.1+）_
Clean removal scripts for all installation methods:
OAuth 供應商的一鍵「修復環境」功能，可恢復遺失的環境變數並修復受損的驗證狀態。可從「儀表板 → 供應商 → [OAuth 供應商] → 修復環境」進入。自動偵測並修復：
| Command | Action |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
- 遺失的 OAuth 客戶端憑證
- 損毀的 env 檔案條目
- 備份路徑清理
---
## 🖼️ Media _(v2.0.3+)_
## 🗑️ 解除安裝 / 完整解除安裝 _（v3.6.2+）_
Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
所有安裝方式的乾淨移除腳本：
| 指令 | 動作 |
| ------------------------ | -------------------------------------------------------------------------------- |
| `npm run uninstall` | 移除系統應用程式，但**保留您的資料庫與配置**於 `~/.omniroute` 中。 |
| `npm run uninstall:full` | 移除應用程式，並**永久清除所有配置、金鑰與資料庫**。 |
---
## 📝 Request Logs
## 🖼️ 媒體 _（v2.0.3+）_
Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
![Usage Logs](screenshots/08-usage.png)
從儀表板產生圖片、影片及音樂。支援 OpenAI、xAI、Together、Hyperbolic、SD WebUI、ComfyUI、AnimateDiff、Stable Audio Open 及 MusicGen。
---
## 🌐 API Endpoint
## 📝 請求記錄
Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
即時請求記錄，可依供應商、模型、帳戶及 API 金鑰篩選。顯示狀態碼、Token 用量、延遲及回應詳細資料。
![Endpoint Dashboard](screenshots/09-endpoint.png)
![用量記錄](../screenshots/08-usage.png)
---
## 🔑 API Key Management
## 🌐 API 端點
Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
統一的 API 端點，包含功能 breakdown：Chat Completions、Responses API、Embeddings、圖片生成、Reranking、音訊轉錄、文字轉語音、Moderations 及已註冊的 API 金鑰。支援 Cloudflare Quick Tunnel、Tailscale Funnel、ngrok Tunnel 及雲端代理，便於遠端存取。
![端點儀表板](../screenshots/09-endpoint.png)
---
## 📋 Audit Log
## 🔑 API 金鑰管理
Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
建立、設定範圍及撤銷 API 金鑰。每個金鑰可限制為特定模型/供應商，並可設定完整存取或唯讀權限。視覺化金鑰管理，附用量追蹤。
---
## 🖥️ Desktop Application
## 📋 稽核記錄
Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
管理操作追蹤，可依操作類型、執行者、目標、IP 位址及時間戳篩選。完整安全事件歷史記錄。
Key features:
---
- Server readiness polling (no blank screen on cold start)
- System tray with port management
## 🖥️ 桌面應用程式
原生 Electron 桌面應用程式，支援 Windows、macOS 及 Linux。將 OmniRoute 作為獨立應用程式執行，包含系統列整合、離線支援、自動更新及一鍵安裝。
主要功能：
- 伺服器就緒輪詢（冷啟動時無白畫面）
- 系統列及埠號管理
- Content Security Policy
- Single-instance lock
- Auto-update on restart
- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
- **Graceful shutdown** — Electron `before-quit` shuts down Next.js cleanly, preventing SQLite WAL database locks (v3.6.2+)
- 單實例鎖定
- 重啟時自動更新
- 平台條件式 UI（macOS 交通號誌燈、Windows/Linux 預設標題列）
- 強化 Electron 建置打包 — 獨立套件中的符號連結 `node_modules` 會在打包前被偵測並拒絕，防止執行時期依賴建置機器（v2.5.5+）
- **優雅關機** — Electron `before-quit` 會乾淨地關閉 Next.js，防止 SQLite WAL 資料庫鎖定（v3.6.2+）
📖 See [`electron/README.md`](../electron/README.md) for full documentation.
📖 完整文件請參閱 [`electron/README.md`](../../electron/README.md)。
---
## 🌐 V1 WebSocket Bridge _(v3.6.6+)_
## 🌐 V1 WebSocket 橋接器 _（v3.6.6+）_
OmniRoute now supports **OpenAI-compatible WebSocket clients** via the `/v1/ws` upgrade endpoint. The custom `scripts/v1-ws-bridge.mjs` server wraps Next.js and upgrades WS connections to full bidirectional streaming sessions. Authentication uses the same API key or session cookie as HTTP requests.
OmniRoute 現在透過 `/v1/ws` 升級端點支援 **OpenAI 相容的 WebSocket 客戶端**。自訂的 `scripts/dev/v1-ws-bridge.mjs` 伺服器包裝 Next.js，並將 WS 連線升級為完整的雙向串流階段。驗證使用與 HTTP 請求相同的 API 金鑰或階段 Cookie。
Key behaviours:
主要行為：
- WS upgrade validated by `src/lib/ws/handshake.ts` before the connection is established
- Streams terminated cleanly on session close or upstream error
- Works alongside the existing HTTP+SSE streaming path simultaneously
- WS 升級在連線建立前由 `src/lib/ws/handshake.ts` 驗證
- 階段關閉或上游錯誤時，串流會乾淨終止
- 可與現有的 HTTP+SSE 串流路徑同時運作
---
## 🔑 Sync Tokens & Config Bundle _(v3.6.6+)_
## 🔑 同步 Token 與配置套件 _（v3.6.6+）_
Multi-device and external operator access is now possible via **scoped sync tokens**:
現在可透過**限域同步 token** 進行多裝置及外部操作者存取：
- **`POST /api/sync/tokens`** — Issue a new sync token (scoped, with optional expiry)
- **`DELETE /api/sync/tokens/:id`** — Revoke a token
- **`GET /api/sync/bundle`** — Download a versioned, ETag-keyed JSON snapshot of all non-sensitive settings (passwords redacted)
- **`POST /api/sync/tokens`** — 簽發新的同步 token（限域，可選到期時間）
- **`DELETE /api/sync/tokens/:id`** — 撤銷 token
- **`GET /api/sync/bundle`** — 下載所有非敏感設定的版本化、ETag 鍵控 JSON 快照（密碼已脫敏）
The config bundle is built by `src/lib/sync/bundle.ts`. Consumers compare the `ETag` response header to detect changes without re-downloading the full payload.
配置套件由 `src/lib/sync/bundle.ts` 建構。消費者可比對 `ETag` 回應標頭來偵測變更，無需重新下載完整內容。
---
## 🧠 GLM Thinking Preset _(v3.6.6+)_
## 🧠 GLM Thinking 預設 _（v3.6.6+）_
**GLM Thinking (`glmt`)** is now a registered first-class provider: 65 536 max output tokens, 24 576 thinking budget, 900 s default timeout, Claude-compatible API format, and shared usage sync with the GLM family.
**GLM Thinking（`glmt`）** 現已註冊為一級供應商：65,536 最大輸出 token、24,576 思考預算、900 秒預設逾時、Claude 相容 API 格式，及與 GLM 系列的共用用量同步。
**Hybrid token counting** also lands in v3.6.6: when a Claude-compatible provider exposes `/messages/count_tokens`, OmniRoute calls it before large requests with graceful estimation fallback.
**混合 Token 計數** 也在 v3.6.6 中登場：當 Claude 相容供應商暴露 `/messages/count_tokens` 端點時，OmniRoute 會在大請求前呼叫它，並附帶優雅的估算備援。
---
## 🛡️ Safe Outbound Fetch & SSRF Guard _(v3.6.6+)_
## 🛡️ 安全外出擷取與 SSRF 防護 _（v3.6.6+）_
All provider validation and model discovery calls now go through a two-layer outbound guard:
所有供應商驗證及模型探索呼叫現在都會通過兩層外出防護：
1. **URL guard** (`src/shared/network/outboundUrlGuard.ts`) — Blocks private/loopback/link-local IP ranges before the socket is opened.
2. **Safe fetch wrapper** (`src/shared/network/safeOutboundFetch.ts`) — Applies the URL guard, normalises timeouts, and retries transient errors with exponential backoff.
1. **URL 防護**（`src/shared/network/outboundUrlGuard.ts`）— 在 socket 開啟前封鎖私有/迴路/連結本地 IP 範圍
2. **安全擷取包裝**（`src/shared/network/safeOutboundFetch.ts`）— 套用 URL 防護、標準化逾時，並以指數退避重試暫時性錯誤
Guard violations surface as HTTP 422 (`URL_GUARD_BLOCKED`) and are written to the compliance audit log via `providerAudit.ts`.
防護違規會以 HTTP 422（`URL_GUARD_BLOCKED`）呈現，並透過 `providerAudit.ts` 寫入合規稽核記錄。
---
## 🔄 Cooldown-Aware Retries _(v3.6.6+)_
## 🔄 冷卻感知重試 _（v3.6.6+）_
Chat requests now **automatically retry** when an upstream provider returns a model-scoped cooldown. Configurable via `REQUEST_RETRY` (default: 2) and `MAX_RETRY_INTERVAL_SEC` (default: 30 s). Rate-limit header learning improved across `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`, and `Retry-After` — per-model cooldown state is visible in the Resilience dashboard.
當上游供應商回傳模型層級冷卻時，聊天請求現在會**自動重試**。可透過 `REQUEST_RETRY`（預設：2）及 `MAX_RETRY_INTERVAL_SEC`（預設：30 秒）設定。速率限制標頭學習已改進，涵蓋 `x-ratelimit-reset-requests`、`x-ratelimit-reset-tokens` 及 `Retry-After`——各模型冷卻狀態可在「抗災能力」儀表板中檢視。
---
## 📋 Compliance Audit v2 _(v3.6.6+)_
## 📋 合規稽核 v2 _（v3.6.6+）_
The audit log has been expanded with cursor-based pagination, request context enrichment (request ID, user agent, IP), structured auth events, provider CRUD events with diff context, and SSRF-blocked validation logging. New events emitted by `src/lib/compliance/providerAudit.ts`.
稽核記錄已擴充，包含游標分頁、請求上下文豐富化（請求 ID、使用者代理、IP）、結構化驗證事件、含差異上下文的供應商 CRUD 事件，以及 SSRF 封鎖驗證記錄。新事件由 `src/lib/compliance/providerAudit.ts` 發送。

600
docs/i18n/zh-TW/docs/guides/I18N.md
View File

@@ -1,90 +1,144 @@
# i18n — Internationalization Guide (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/I18N.md) · 🇸🇦 [ar](../../ar/docs/I18N.md) · 🇧🇬 [bg](../../bg/docs/I18N.md) · 🇧🇩 [bn](../../bn/docs/I18N.md) · 🇨🇿 [cs](../../cs/docs/I18N.md) · 🇩🇰 [da](../../da/docs/I18N.md) · 🇩🇪 [de](../../de/docs/I18N.md) · 🇪🇸 [es](../../es/docs/I18N.md) · 🇮🇷 [fa](../../fa/docs/I18N.md) · 🇫🇮 [fi](../../fi/docs/I18N.md) · 🇫🇷 [fr](../../fr/docs/I18N.md) · 🇮🇳 [gu](../../gu/docs/I18N.md) · 🇮🇱 [he](../../he/docs/I18N.md) · 🇮🇳 [hi](../../hi/docs/I18N.md) · 🇭🇺 [hu](../../hu/docs/I18N.md) · 🇮🇩 [id](../../id/docs/I18N.md) · 🇮🇹 [it](../../it/docs/I18N.md) · 🇯🇵 [ja](../../ja/docs/I18N.md) · 🇰🇷 [ko](../../ko/docs/I18N.md) · 🇮🇳 [mr](../../mr/docs/I18N.md) · 🇲🇾 [ms](../../ms/docs/I18N.md) · 🇳🇱 [nl](../../nl/docs/I18N.md) · 🇳🇴 [no](../../no/docs/I18N.md) · 🇵🇭 [phi](../../phi/docs/I18N.md) · 🇵🇱 [pl](../../pl/docs/I18N.md) · 🇵🇹 [pt](../../pt/docs/I18N.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/I18N.md) · 🇷🇴 [ro](../../ro/docs/I18N.md) · 🇷🇺 [ru](../../ru/docs/I18N.md) · 🇸🇰 [sk](../../sk/docs/I18N.md) · 🇸🇪 [sv](../../sv/docs/I18N.md) · 🇰🇪 [sw](../../sw/docs/I18N.md) · 🇮🇳 [ta](../../ta/docs/I18N.md) · 🇮🇳 [te](../../te/docs/I18N.md) · 🇹🇭 [th](../../th/docs/I18N.md) · 🇹🇷 [tr](../../tr/docs/I18N.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/I18N.md) · 🇵🇰 [ur](../../ur/docs/I18N.md) · 🇻🇳 [vi](../../vi/docs/I18N.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/I18N.md)
---
title: "i18n — 國際化指南"
version: 3.8.40
lastUpdated: 2026-06-28
---
OmniRoute supports **30 languages** with full dashboard UI translation, translated documentation, and RTL support for Arabic and Hebrew.
# i18n — 國際化指南
## Quick Reference
OmniRoute 支援 **43 種語言**，包含完整的儀表板 UI 翻譯、翻譯文件，以及阿拉伯語和希伯來語的 RTL（從右至左）支援。
| Task | Command |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Generate translations | `node scripts/i18n/generate-multilang.mjs messages` |
| Translate docs (LLM) | `python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |
| Validate a locale | `python3 scripts/validate_translation.py quick -l cs` |
| Check code keys | `python3 scripts/check_translations.py` |
| Generate QA report | `node scripts/i18n/generate-qa-checklist.mjs` |
| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs` |
🌐 **語言：** 🇺🇸 [English](./I18N.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/I18N.md) | 🇪🇸 [Español](../i18n/es/docs/guides/I18N.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/I18N.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/I18N.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/I18N.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/I18N.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/I18N.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/I18N.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/I18N.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/I18N.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/guides/I18N.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/I18N.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/guides/I18N.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/I18N.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/I18N.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/I18N.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/I18N.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/I18N.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/I18N.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/I18N.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/I18N.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/I18N.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/I18N.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/I18N.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/I18N.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/I18N.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/I18N.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/I18N.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/I18N.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/I18N.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/I18N.md)
## 翻譯管線（建議使用 — v3.8.0）
OmniRoute 使用基於雜湊的增量翻譯器來處理說明文件，後端採用與 OpenAI 相容的 LLM 端點（通常是透過 OmniRoute Cloud 的 `cx/gpt-5.4-mini`）：
```bash
# 執行翻譯（增量模式 — 僅處理有變更的來源）
npm run i18n:run
# 限制僅翻譯一個語系
npm run i18n:run -- --locale=pt-BR
# 指定檔案（以逗號分隔，使用相對於儲存庫的路徑）
npm run i18n:run -- --files=CLAUDE.md,docs/architecture/ARCHITECTURE.md
# 強制重新翻譯所有內容（成本較高）
npm run i18n:run -- --force
# 預覽即將進行的操作（不呼叫 API，不寫入檔案）
npm run i18n:run:dry
# CI 閘道 — 若狀態偏移則結束碼非零
npm run i18n:check
```
**唯一真相來源。** `config/i18n.json` 列出了每個語系（UI + 文件），以及 RTL 集合和 `docsExcluded` 代碼。執行時期設定檔 `src/i18n/config.ts` 是該 JSON 的輕量轉接層。
**後端。** 透過環境變數設定（在 `.env` 中設定，切勿提交）：
| 變數 | 用途 |
| ---------------------------------- | ------------------------------------- |
| `OMNIROUTE_TRANSLATION_API_URL` | 與 OpenAI 相容的基礎 URL，例如 `…/v1` |
| `OMNIROUTE_TRANSLATION_API_KEY` | Bearer 令牌（不會記錄在日誌中） |
| `OMNIROUTE_TRANSLATION_MODEL` | 模型 ID，例如 `cx/gpt-5.4-mini` |
| `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | 選用，預設 `60000` |
| `OMNIROUTE_TRANSLATION_CONCURRENCY`| 選用，預設 `4` |
**狀態追蹤。** `.i18n-state.json`（已提交）會為每個來源 + 每個語系保留 SHA-256 雜湊值。漂移偵測是自動且確定性的 — `i18n:check` 不需要 API 呼叫。
**輸出格式。** 每個翻譯後的檔案會在最上方加入 `# <標題>（<語言>）` 行、`🌐 語言：…` 列、`---` 分隔線，以及翻譯後的正文。此佈局與 `scripts/check/check-docs-sync.mjs` 已對 `llm.txt` 和 `CHANGELOG.md` 鏡像強制執行的格式一致。
### 舊版腳本（已棄用）
較舊的 Python 腳本（`scripts/i18n/i18n_autotranslate.py`）和基於 Google 翻譯的產生器（`scripts/i18n/generate-multilang.mjs`）仍然存在，但附有棄用橫幅。它們將在 v3.10 中移除。`generate-multilang.mjs` 的 `messages` 和 `readme` 模式（UI 字串 + 根目錄 README 變體）尚未由新管線處理，目前仍在使用中。
## 快速參考
| 任務 | 指令 |
| ------------------------ | ------------------------------------------------------------- |
| 翻譯文件（LLM） | `npm run i18n:run`（建議使用 — 增量、基於雜湊） |
| 翻譯 UI 字串 | `node scripts/i18n/generate-multilang.mjs messages` |
| 檢查翻譯漂移 | `npm run i18n:check` |
| 驗證語系 | `python3 scripts/i18n/validate_translation.py quick -l cs` |
| 檢查程式碼按鍵 | `python3 scripts/i18n/check_translations.py` |
| 產生 QA 報告 | `node scripts/i18n/generate-qa-checklist.mjs` |
| 視覺 QA（Playwright） | `node scripts/i18n/run-visual-qa.mjs` |
## 架構
### Source of Truth
![增量式基於雜湊的 i18n 管線](../diagrams/exported/i18n-flow.svg)
- **UI strings**: `src/i18n/messages/en.json` (English source, ~2800 keys)
- **Locale files**: `src/i18n/messages/{locale}.json` (30 translations)
- **Framework**: `next-intl` with cookie-based locale resolution
- **Config**: `src/i18n/config.ts` — defines all 30 locales, language names, flags
> 來源：[diagrams/i18n-flow.mmd](../diagrams/i18n-flow.mmd)
### Runtime Flow
### 唯一真相來源
1. User selects language → `NEXT_LOCALE` cookie set
2. `src/i18n/request.ts` resolves locale: cookie → `Accept-Language` header → fallback `en`
3. Dynamic import loads `messages/{locale}.json`
4. Components use `useTranslations("namespace")` and `t("key")`
- **UI 字串**：`src/i18n/messages/en.json`（英文來源，約 2800 個按鍵）
- **語系檔案**：`src/i18n/messages/{locale}.json`（30 種翻譯）
- **框架**：`next-intl`，搭配基於 Cookie 的語系解析
- **設定**：`src/i18n/config.ts` — 定義全部 30 個語系、語言名稱、旗標
### Supported Locales
### 執行時期流程
| Code | Language | RTL | Google Translate Code |
| ------- | -------------------- | --- | --------------------- |
| `ar` | العربية | Yes | `ar` |
| `bg` | Български | No | `bg` |
| `cs` | Čeština | No | `cs` |
| `da` | Dansk | No | `da` |
| `de` | Deutsch | No | `de` |
| `es` | Español | No | `es` |
| `fi` | Suomi | No | `fi` |
| `fr` | Français | No | `fr` |
| `he` | עברית | Yes | `iw` |
| `hi` | हिन्दी | No | `hi` |
| `hu` | Magyar | No | `hu` |
| `id` | Bahasa Indonesia | No | `id` |
| `it` | Italiano | No | `it` |
| `ja` | 日本語 | No | `ja` |
| `ko` | 한국어 | No | `ko` |
| `ms` | Bahasa Melayu | No | `ms` |
| `nl` | Nederlands | No | `nl` |
| `no` | Norsk | No | `no` |
| `phi` | Filipino | No | `tl` |
| `pl` | Polski | No | `pl` |
| `pt` | Português (Portugal) | No | `pt` |
| `pt-BR` | Português (Brasil) | No | `pt` |
| `ro` | Română | No | `ro` |
| `ru` | Русский | No | `ru` |
| `sk` | Slovenčina | No | `sk` |
| `sv` | Svenska | No | `sv` |
| `th` | ไทย | No | `th` |
| `tr` | Türkçe | No | `tr` |
| `uk-UA` | Українська | No | `uk` |
| `vi` | Tiếng Việt | No | `vi` |
| `zh-CN` | 中文 (簡體) | No | `zh-CN` |
1. 使用者選擇語言 → 設定 `NEXT_LOCALE` Cookie
2. `src/i18n/request.ts` 解析語系：Cookie → `Accept-Language` 標頭 → 備用 `en`
3. 動態匯入載入 `messages/{locale}.json`
4. 元件使用 `useTranslations("namespace")` 和 `t("key")`
## Adding a New Language
### 支援的語系
### 1. Register the Locale
| 代碼 | 語言 | RTL | Google 翻譯代碼 |
| -------- | ---------------------- | --- | --------------- |
| `ar` | العربية | 是 | `ar` |
| `bg` | Български | 否 | `bg` |
| `cs` | Čeština | 否 | `cs` |
| `da` | Dansk | 否 | `da` |
| `de` | Deutsch | 否 | `de` |
| `es` | Español | 否 | `es` |
| `fi` | Suomi | 否 | `fi` |
| `fr` | Français | 否 | `fr` |
| `he` | עברית | 是 | `iw` |
| `hi` | हिन्दी | 否 | `hi` |
| `hu` | Magyar | 否 | `hu` |
| `id` | Bahasa Indonesia | 否 | `id` |
| `it` | Italiano | 否 | `it` |
| `ja` | 日本語 | 否 | `ja` |
| `ko` | 한국어 | 否 | `ko` |
| `ms` | Bahasa Melayu | 否 | `ms` |
| `nl` | Nederlands | 否 | `nl` |
| `no` | Norsk | 否 | `no` |
| `phi` | Filipino | 否 | `tl` |
| `pl` | Polski | 否 | `pl` |
| `pt` | Português (Portugal) | 否 | `pt` |
| `pt-BR` | Português (Brasil) | 否 | `pt` |
| `ro` | Română | 否 | `ro` |
| `ru` | Русский | 否 | `ru` |
| `sk` | Slovenčina | 否 | `sk` |
| `sv` | Svenska | 否 | `sv` |
| `th` | ไทย | 否 | `th` |
| `tr` | Türkçe | 否 | `tr` |
| `uk-UA` | Українська | 否 | `uk` |
| `vi` | Tiếng Việt | 否 | `vi` |
| `zh-CN` | 中文 (简体) | 否 | `zh-CN` |
| `zh-TW` | 中文 (繁體) | 否 | `zh-TW` |
Edit `src/i18n/config.ts`:
## 新增語言
### 1. 註冊語系
編輯 `src/i18n/config.ts`：
```ts
// Add to LOCALES array
// 新增至 LOCALES 陣列
"xx",
// Add to LANGUAGES array
// 新增至 LANGUAGES 陣列
{ code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },
```
### 2. Add to Generator
### 2. 新增至產生器
Edit `scripts/i18n/generate-multilang.mjs` — add entry to `LOCALE_SPECS`:
編輯 `scripts/i18n/generate-multilang.mjs` — 在 `LOCALE_SPECS` 中新增項目：
```js
{
@@ -98,344 +152,414 @@ Edit `scripts/i18n/generate-multilang.mjs` — add entry to `LOCALE_SPECS`:
},
```
### 3. Generate Initial Translation
### 3. 產生初始翻譯
```bash
node scripts/i18n/generate-multilang.mjs messages
```
This creates `src/i18n/messages/xx.json` auto-translated from `en.json` via Google Translate.
這會從 `en.json` 透過 Google 翻譯自動翻譯，建立 `src/i18n/messages/xx.json`。
### 4. Review & Fix Auto-Translations
### 4. 審查與修正自動翻譯
Auto-translations are a starting point. Review manually for:
自動翻譯僅是起點。請手動檢查以下項目：
- Technical accuracy
- Context-appropriate terminology
- Proper handling of placeholders (`{count}`, `{value}`, etc.)
- 技術準確性
- 符合語境的術語用法
- 佔位符號（`{count}`、`{value}` 等）的正確處理
### 5. Validate
### 5. 驗證
```bash
python3 scripts/validate_translation.py quick -l xx
python3 scripts/validate_translation.py diff common -l xx
python3 scripts/i18n/validate_translation.py quick -l xx
python3 scripts/i18n/validate_translation.py diff common -l xx
```
### 6. Generate Translated Documentation
### 6. 產生翻譯文件
```bash
node scripts/i18n/generate-multilang.mjs docs
```
## Auto-Translation Pipeline
## 自動翻譯管線
### generate-multilang.mjs (Google Translate)
### generate-multilang.mjs（Google 翻譯）
**Primary auto-translation engine** — uses Google Translate free API to generate translations for UI strings, READMEs, and documentation.
**主要自動翻譯引擎** — 使用 Google 翻譯免費 API 為 UI 字串、README 和說明文件產生翻譯。
```bash
node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]
```
| Mode | What it does |
| ---------- | ----------------------------------------------------------------------------- |
| `messages` | Translates missing keys in `src/i18n/messages/{locale}.json` from `en.json` |
| `readme` | Translates `README.md` into all locales as `README.{code}.md` in project root |
| `docs` | Translates `DOC_SOURCE_FILES` into `docs/i18n/{locale}/{docName}` |
| `all` | Runs all three modes |
| 模式 | 功能說明 |
| ---------- | ------------------------------------------------------------------------------- |
| `messages` | 從 `en.json` 翻譯 `src/i18n/messages/{locale}.json` 中遺漏的按鍵 |
| `readme` | 將 `README.md` 翻譯為專案根目錄下的 `README.{code}.md` 所有語系版本 |
| `docs` | 將 `DOC_SOURCE_FILES` 翻譯為 `docs/i18n/{locale}/{docName}` |
| `all` | 執行上述三種模式 |
**Features:**
**功能特色：**
- **Text protection**: Masks code blocks (` ``` `), inline code (`` ` ``), markdown links/images (`[text](url)`), HTML tags, tables, and ICU placeholders (`{count}`, `{value}`, `{total}`, etc.) before translation, then restores them
- **Chunked batching**: Joins multiple strings with `__OMNIROUTE_I18N_SEPARATOR__` delimiters to minimize API calls (max 1800 chars per request)
- **In-memory cache**: Avoids redundant API calls for repeated strings within a session
- **Retry logic**: Exponential backoff (up to 5 attempts with 300ms × attempt delay) for 429/5xx errors
- **Timeout**: 20 seconds per request
- **Skip existing**: If target file already exists, it is NOT overwritten
- **文字保護**：在翻譯前遮罩程式碼區塊（` ``` `）、行內程式碼（`` ` ``）、Markdown 連結/圖片（`[text](url)`）、HTML 標籤、表格和 ICU 佔位符號（`{count}`、`{value}`、`{total}` 等），翻譯後再還原
- **分塊批次處理**：使用 `__OMNIROUTE_I18N_SEPARATOR__` 分隔符號將多個字串連接起來，以減少 API 呼叫次數（每個請求最多 1800 字元）
- **記憶體快取**：避免在單一工作階段內對重複字串進行多餘的 API 呼叫
- **重試邏輯**：針對 429/5xx 錯誤採用指數退避（最多 5 次嘗試，延遲時間為 300ms × 嘗試次數）
- **超時**：每個請求 20 秒
- **略過現有檔案**：若目標檔案已存在，則不會覆寫
**Important behaviors:**
**重要行為：**
- `docs/i18n/README.md` is **regenerated** each run — it's an auto-generated index of all docs
- Root `README.{code}.md` files are only created if they don't exist (skips locales in `EXISTING_README_CODES`)
- Language bars (`🌐 **Languages:** ...`) are automatically inserted/updated in all translated docs
- `docs/i18n/README.md` 每次執行時都會**重新產生** — 這是所有說明的自動產生索引
- 根目錄的 `README.{code}.md` 僅在不存在時才會建立（略過 `EXISTING_README_CODES` 中的語系）
- 語言列（`🌐 **語言：** ...`）會自動插入/更新至所有翻譯文件中
### i18n_autotranslate.py (LLM-based)
### i18n_autotranslate.py（LLM 基礎）
**Secondary translator** — uses any OpenAI-compatible LLM API (including OmniRoute itself) to translate existing `docs/i18n/` markdown files. Best for polishing or re-translating docs with better quality than Google Translate.
**次要翻譯器** — 使用任何與 OpenAI 相容的 LLM API（包括 OmniRoute 本身）來翻譯現有的 `docs/i18n/` Markdown 檔案。最適合用於潤飾或重新翻譯文件，品質優於 Google 翻譯。
```bash
python3 scripts/i18n_autotranslate.py \
python3 scripts/i18n/i18n_autotranslate.py \
--api-url http://localhost:20128/v1 \
--api-key sk-your-key \
--model gpt-4o
```
**Features:**
**功能特色：**
- Scans `docs/i18n/` markdown files for English paragraphs
- Skips code blocks, tables, and already-translated content
- Sends paragraphs to LLM with technical translation system prompt
- Supports all 30 languages
- 掃描 `docs/i18n/` 中的 Markdown 檔案以取得英文段落
- 略過程式碼區塊、表格和已翻譯的內容
- 將段落發送給 LLM，並附帶技術翻譯系統提示
- 支援全部 43 種語言
## Validation & QA
## CLI i18n
`omniroute` CLI 有獨立於 Next.js 儀表板之外的 i18n 層。
### 運作方式
- CLI 指令中所有使用者可見的字串均透過 `t("module.key", vars)`（來自 `bin/cli/i18n.mjs`）處理
- 語系目錄是 `bin/cli/locales/` 中的 JSON 檔案 — 內建 43 種語言
- 任何遺漏的按鍵都會自動回退到 `en`，因此部分翻譯仍然有效
- 可用語系的唯一真相來源是 `config/i18n.json`（與儀表板共用）
### 語系選擇
偵測順序（第一個符合者優先）：
| 優先順序 | 來源 | 範例 |
| -------- | ------------------------ | ------------------------------------------ |
| 1 | `--lang` 旗標 | `omniroute --lang de status` |
| 2 | `OMNIROUTE_LANG` 環境變數| `OMNIROUTE_LANG=ja omniroute providers` |
| 3 | `LC_ALL` 系統環境變數 | 自動從終端機語系偵測 |
| 4 | `LC_MESSAGES` 系統環境變數| 自動從終端機語系偵測 |
| 5 | `LANG` 系統環境變數 | 自動從終端機語系偵測 |
| 6 | 備用 | `en` |
底線形式的語系代碼（`pt_BR`）會標準化為連字號形式（`pt-BR`）。
語系代碼會經由 `/^[a-zA-Z0-9-]+$/` 驗證 — 拒絕路徑遍歷攻擊。
### 儲存語言偏好
```bash
# 設定語言並儲存至 ~/.omniroute/.env（跨工作階段持續有效）
omniroute config lang set pt-BR
# 檢視目前語言
omniroute config lang get
# 列出全部 42 種可用語言
omniroute config lang list
# JSON 輸出
omniroute config lang list --output json
```
儲存的偏好設定會以原子方式寫入 `~/.omniroute/.env`，並在 CLI 啟動時、任何指令執行前載入。
### 單次覆寫
```bash
# 僅為單一指令覆寫（不持續保留）
omniroute --lang de providers list
```
注意：`--lang` 旗標**不會**寫入環境變數檔案 — 它僅影響當次呼叫。請使用 `config lang set` 來持續保留設定。
### 可用語系
`bin/cli/locales/` 中內建 43 個語系檔案。完整翻譯：`en`、`pt-BR`。
僅有骨架（所有按鍵回退至 `en`）：`bn`、`gu`、`he`、`in`、`mr`、`ms`、`phi`、`sw`、`ta`、`te`、`ur`。
其他 29 個語系均包含 `common` + `program` 按鍵的翻譯。
### 新增 CLI 語系
1. 在 `config/i18n.json` 中新增語系項目。
2. 執行 `node bin/cli/scripts/generate-locales.mjs` — 建立語系檔案。
3. 翻譯按鍵（或保留為 `{}` 以使用 en 回退骨架）。
4. PR 必須將字串新增至 `en.json` 和 `pt-BR.json`；其他檔案則盡力而為。
## 驗證與 QA
### validate_translation.py
**Translation validator** — compares any locale JSON against `en.json` and reports issues.
**翻譯驗證器** — 將任何語系 JSON 與 `en.json` 進行比較，並回報問題。
```bash
# Quick check (counts only)
python3 scripts/validate_translation.py quick -l cs
# Output:
# 快速檢查（僅計數）
python3 scripts/i18n/validate_translation.py quick -l cs
# 輸出：
# Missing: 0
# Untranslated: 0
# Ignored (UNTRANSLATABLE_KEYS): 236
# Detailed diff by category
python3 scripts/validate_translation.py diff common -l cs
python3 scripts/validate_translation.py diff settings -l cs
# 依分類詳細差異
python3 scripts/i18n/validate_translation.py diff common -l cs
python3 scripts/i18n/validate_translation.py diff settings -l cs
# Export to CSV
python3 scripts/validate_translation.py csv -l cs > report.csv
# 匯出至 CSV
python3 scripts/i18n/validate_translation.py csv -l cs > report.csv
# Export to Markdown
python3 scripts/validate_translation.py md -l cs > report.md
# 匯出至 Markdown
python3 scripts/i18n/validate_translation.py md -l cs > report.md
# Full report (default)
python3 scripts/validate_translation.py -l cs
# 完整報告（預設）
python3 scripts/i18n/validate_translation.py -l cs
```
**Detects:**
**可偵測的項目：**
- **Missing keys** — keys in `en.json` but not in locale file
- **Extra keys** — keys in locale file but not in `en.json`
- **Untranslated keys** — keys where locale value equals English source (excluding allowlist)
- **Placeholder mismatches** — ICU placeholders that don't match between source and translation
- **遺漏的按鍵** — `en.json` 中存在，但語系檔案中沒有的按鍵
- **多餘的按鍵** — 語系檔案中存在，但 `en.json` 中沒有的按鍵
- **未翻譯的按鍵** — 語系值與英文來源相同的按鍵（排除允許清單）
- **佔位符號不匹配** — 來源與翻譯之間 ICU 佔位符號不一致
**Exit codes:**
| Code | Meaning |
|------|---------|
| 0 | OK |
| 1 | Generic error |
| 2 | Missing strings (hard error) |
| 3 | Untranslated warning (soft) |
**結束代碼：**
**Environment:** Set `TRANSLATION_LANG=cs` or use `-l cs` flag.
| 代碼 | 含義 |
| ---- | ----------------------------- |
| 0 | 正常 |
| 1 | 一般錯誤 |
| 2 | 遺漏字串（嚴重錯誤） |
| 3 | 未翻譯警告（軟性錯誤） |
**環境：** 設定 `TRANSLATION_LANG=cs` 或使用 `-l cs` 旗標。
### check_translations.py
**Code-to-JSON key checker** — scans `src/**/*.tsx` and `src/**/*.ts` for `useTranslations()` calls and verifies all referenced keys exist in `en.json`.
**程式碼對 JSON 按鍵檢查器** — 掃描 `src/**/*.tsx` 和 `src/**/*.ts` 中的 `useTranslations()` 呼叫，並驗證所有被參考的按鍵都存在於 `en.json` 中。
```bash
# Basic check
python3 scripts/check_translations.py
# 基本檢查
python3 scripts/i18n/check_translations.py
# Verbose output
python3 scripts/check_translations.py --verbose
# 詳細輸出
python3 scripts/i18n/check_translations.py --verbose
# Auto-fix (adds missing keys to en.json)
python3 scripts/check_translations.py --fix
# 自動修正（將遺漏的按鍵新增至 en.json）
python3 scripts/i18n/check_translations.py --fix
```
### generate-qa-checklist.mjs
**Static analysis QA** — scans Next.js page files for i18n risk metrics and generates a Markdown report.
**靜態分析 QA** — 掃描 Next.js 頁面檔案中與 i18n 相關的風險指標，並產生 Markdown 報告。
```bash
node scripts/i18n/generate-qa-checklist.mjs
```
**Checks:**
**檢查項目：**
- Fixed-width class usage (overflow risk)
- Directional left/right classes (RTL risk)
- Clipping-prone patterns
- Locale parity (missing/extra keys vs `en.json`)
- README language selector bars in priority locales (`es`, `fr`, `de`, `ja`, `ar`)
- 固定寬度類別的使用（溢位風險）
- 方向性 left/right 類別（RTL 風險）
- 易裁剪的模式
- 語系一致性（與 `en.json` 相比遺漏/多餘的按鍵）
- 優先語系（`es`、`fr`、`de`、`ja`、`ar`）的 README 語言選擇器列
**Output:** `docs/reports/i18n-qa-checklist-{date}.md`
**輸出：** `docs/reports/i18n-qa-checklist-{date}.md`
### run-visual-qa.mjs
**Visual QA via Playwright** — takes screenshots of all dashboard routes in multiple locales and viewports, then evaluates page health.
**透過 Playwright 進行視覺 QA** — 在多個語系和檢視區間對所有儀表板路由進行螢幕截圖，然後評估頁面健康狀況。
```bash
# Default: es, fr, de, ja, ar on localhost:20128
# 預設：在 localhost:20128 上使用 es、fr、de、ja、ar
node scripts/i18n/run-visual-qa.mjs
# Custom base URL and locales
# 自訂基礎 URL 和語系
QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs
# Custom routes
# 自訂路由
QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs
```
**Detects:**
**可偵測的項目：**
- Text overflow
- Element clipping
- RTL layout mismatches
- 文字溢位
- 元素裁剪
- RTL 佈局不一致
**Output:** `docs/reports/i18n-visual-qa-{date}.md` + JSON report
**輸出：** `docs/reports/i18n-visual-qa-{date}.md` + JSON 報告
## Managing Untranslatable Keys
## 管理不可翻譯的按鍵
### untranslatable-keys.json
**File:** `scripts/i18n/untranslatable-keys.json`
**檔案：** `scripts/i18n/untranslatable-keys.json`
Allowlist of keys that should remain identical to English source. Used by `validate_translation.py` to avoid false-positive "untranslated" warnings.
允許清單，列出應與英文來源保持一致的按鍵。由 `validate_translation.py` 用來避免「未翻譯」的誤報警告。
```json
{
"description": "Keys that should remain untranslated...",
"description": "應保持不翻譯的按鍵…",
"keys": [
"common.model",
"common.oauth",
"health.cpu",
...
…
]
}
```
**What belongs here:**
**應歸類於此的項目：**
- Brand/product names: `landing.brandName`, `common.social-github`
- Technical terms/acronyms: `health.cpu`, `mcpDashboard.pid`, `settings.ai`
- ICU/format strings: `apiManager.modelsCount`, `health.millisecondsShort`
- Placeholder values: `providers.openaiBaseUrlPlaceholder`, `cliTools.baseUrlPlaceholder`
- Protocol names: `common.http`, `common.oauth`, `providers.oauth2Label`
- Navigation sections: `sidebar.primarySection`, `sidebar.cliSection`
- 品牌/產品名稱：`landing.brandName`、`common.social-github`
- 技術術語/縮寫：`health.cpu`、`mcpDashboard.pid`、`settings.ai`
- ICU/格式字串：`apiManager.modelsCount`、`health.millisecondsShort`
- 佔位符號值：`providers.openaiBaseUrlPlaceholder`、`cliTools.baseUrlPlaceholder`
- 協定名稱：`common.http`、`common.oauth`、`providers.oauth2Label`
- 導航區段：`sidebar.primarySection`、`sidebar.cliSection`
**To add a key:** Edit the `keys` array in `scripts/i18n/untranslatable-keys.json` and re-run validation.
**若要新增按鍵：** 編輯 `scripts/i18n/untranslatable-keys.json` 中的 `keys` 陣列，然後重新執行驗證。
## CI Integration
## CI 整合
### GitHub Actions (`.github/workflows/ci.yml`)
### GitHub Actions（`.github/workflows/ci.yml`）
The CI pipeline validates all locales on every push and PR:
CI 管線會在每次推送和 PR 時驗證所有語系：
1. **`i18n-matrix` job** — dynamically discovers all locale files (excluding `en.json`)
2. **`i18n` job** — runs `validate_translation.py quick -l '<lang>'` for each locale in parallel
3. **`ci-summary` job** — aggregates results into a dashboard summary
1. **`i18n-matrix` 任務** — 動態發現所有語系檔案（排除 `en.json`）
2. **`i18n` 任務** — 對每個語系平行執行 `validate_translation.py quick -l '<lang>'`
3. **`ci-summary` 任務** — 將結果彙整為儀表板摘要
```yaml
# i18n-matrix: discovers languages
# i18n-matrix：發現語言
LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')
# i18n: validates each language
python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
# i18n：驗證每種語言
python3 scripts/i18n/validate_translation.py quick -l '${{ matrix.lang }}'
```
**Dashboard output:**
**儀表板輸出：**
```
## 🌍 Translations
| Metric | Value |
## 🌍 翻譯
| 指標 | 數值 |
|--------|------|
| Languages checked | 30 |
| Total untranslated | 0 |
| 已檢查語言數 | 30 |
| 未翻譯總數 | 0 |
✅ All translations complete
✅ 所有翻譯皆完整
```
## File Structure
## 檔案結構
```
src/i18n/
├── config.ts # Locale definitions (30 locales, RTL config)
├── request.ts # Runtime locale resolution
├── config.ts # 語系定義（30 個語系、RTL 設定）
├── request.ts # 執行時期語系解析
└── messages/
├── en.json # Source of truth (~2800 keys)
├── cs.json # Czech translation
├── de.json # German translation
└── ... # 30 locale files total
├── en.json # 唯一真相來源（約 2800 個按鍵）
├── cs.json # 捷克文翻譯
├── de.json # 德文翻譯
└── ... # 共 30 個語系檔案
scripts/
├── i18n/
│ ├── generate-multilang.mjs # Auto-translation engine (Google Translate, 888 lines)
│ ├── generate-qa-checklist.mjs # Static analysis QA
│ ├── run-visual-qa.mjs # Playwright visual QA
│ └── untranslatable-keys.json # Allowlist for validation (236 keys)
├── validate_translation.py # Translation validator
├── check_translations.py # Code-to-JSON key checker
└── i18n_autotranslate.py # LLM-based doc translator
│ ├── generate-multilang.mjs # 自動翻譯引擎（Google 翻譯，888 行）
│ ├── generate-qa-checklist.mjs # 靜態分析 QA
│ ├── run-visual-qa.mjs # Playwright 視覺 QA
│ └── untranslatable-keys.json # 驗證允許清單（236 個按鍵）
├── validate_translation.py # 翻譯驗證器
├── check_translations.py # 程式碼對 JSON 按鍵檢查器
└── i18n_autotranslate.py # 基於 LLM 的文件翻譯器
.github/workflows/
└── ci.yml # i18n validation in CI matrix
└── ci.yml # CI 矩陣中的 i18n 驗證
docs/
├── I18N.md # This file — i18n toolchain documentation
├── I18N.md # 本檔案 — i18n 工具鏈文件
├── i18n/
│ ├── README.md # Auto-generated language index
│ ├── cs/ # Czech docs
│ ├── README.md # 自動產生的語言索引
│ ├── cs/ # 捷克文文件
│ │ └── docs/
│ │ ├── I18N.md # Czech translation of this file
│ │ ├── I18N.md # 本檔案的捷克文翻譯
│ │ └── ...
│ ├── de/ # German docs
│ └── ... # 30 locale directories
│ ├── de/ # 德文文件
│ └── ... # 30 個語系目錄
└── reports/
├── i18n-qa-checklist-*.md # Static analysis reports
└── i18n-visual-qa-*.md # Visual QA reports
├── i18n-qa-checklist-*.md # 靜態分析報告
└── i18n-visual-qa-*.md # 視覺 QA 報告
```
## Best Practices
## 最佳實踐
### When Editing Translations
### 編輯翻譯時
1. **Always edit `en.json` first** — it's the source of truth
2. **Run `generate-multilang.mjs messages`** to propagate new keys to all locales
3. **Review auto-translations** — Google Translate is a starting point, not final
4. **Validate before committing** — `python3 scripts/validate_translation.py quick -l <lang>`
5. **Update `untranslatable-keys.json`** if a key should remain in English
1. **始終先編輯 `en.json`** — 這是唯一真相來源
2. **執行 `generate-multilang.mjs messages`** 以將新按鍵傳播至所有語系
3. **審查自動翻譯** — Google 翻譯是起點，而非終點
4. **提交前先驗證** — `python3 scripts/i18n/validate_translation.py quick -l <lang>`
5. **更新 `untranslatable-keys.json`** — 若某個按鍵應保持為英文
### Placeholder Safety
### 佔位符號安全性
- ICU placeholders (`{count}`, `{value}`, `{total}`, `{seconds}`) must be preserved exactly
- Plural formats (`{count, plural, one {# model} other {# models}}`) must maintain structure
- The validator detects placeholder mismatches automatically
- ICU 佔位符號（`{count}`、`{value}`、`{total}`、`{seconds}`）必須保持原樣
- 複數格式（`{count, plural, one {# model} other {# models}}`）必須維持結構
- 驗證器會自動偵測佔位符號不匹配
### Adding New Translation Keys in Code
### 在程式碼中新增翻譯按鍵
```tsx
// Use namespaced keys
// 使用命名空間按鍵
const t = useTranslations("settings");
t("cacheSettings"); // maps to settings.cacheSettings in JSON
t("cacheSettings"); // 對應 JSON 中的 settings.cacheSettings
// Run check_translations.py to verify keys exist
python3 scripts/check_translations.py --verbose
// 執行 check_translations.py 以驗證按鍵是否存在
python3 scripts/i18n/check_translations.py --verbose
```
### RTL Considerations
### RTL 考量
- Arabic (`ar`) and Hebrew (`he`) are RTL locales
- Avoid hardcoded `left`/`right` CSS — use `start`/`end` logical properties
- Visual QA catches RTL layout mismatches via `run-visual-qa.mjs`
- 阿拉伯語（`ar`）和希伯來語（`he`）是 RTL 語系
- 避免硬編碼 `left`/`right` CSS — 使用 `start`/`end` 邏輯屬性
- 視覺 QA 透過 `run-visual-qa.mjs` 捕捉 RTL 佈局不一致
## Known Issues & History
## 已知問題與歷史記錄
### `in.json` → `hi.json` Fix
### `in.json` → `hi.json` 修正
The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This created an orphaned `in.json` duplicate of `hi.json`. Fixed by changing `code: "in"` to `code: "hi"` in `generate-multilang.mjs` and removing the orphaned file.
產生器原本使用 `code: "in"`（已棄用的 Google 翻譯代碼）來表示印度語，而不是正確的 ISO 639-1 `hi`。這建立了一個孤立的 `in.json` 檔案作為 `hi.json` 的重複。修正方式為將 `generate-multilang.mjs` 中的 `code: "in"` 改為 `code: "hi"`，並移除孤立的檔案。
### `docs/i18n/README.md` Is Auto-Generated
> ⚠️ **稽核備註（2026-05-13）：** `docs/i18n/in/` 目錄仍然存在於磁碟上（是 `hi/` 的完整重複）。翻譯產生器不再寫入該目錄，但歷史留存目錄未被清理。確認沒有外部連結參考舊路徑後，可使用 `rm -rf docs/i18n/in/` 安全刪除。
The `docs/i18n/README.md` file is completely regenerated by `generate-multilang.mjs docs`. Any manual edits will be lost. Use `docs/guides/I18N.md` (this file) for hand-written documentation that should persist.
### `docs/i18n/README.md` 為自動產生
### External Untranslatable Keys List
`docs/i18n/README.md` 檔案會由 `generate-multilang.mjs docs` 完全重新產生。任何手動編輯都會遺失。請使用 `docs/guides/I18N.md`（本檔案）來存放應保留的手寫文件。
The `untranslatable-keys.json` allowlist was moved from an inline Python set in `validate_translation.py` to an external JSON file for easier maintenance. The validator loads it at runtime.
### 外部不可翻譯按鍵清單
### `generate-multilang.mjs` Hindi Code Fix
`untranslatable-keys.json` 允許清單已從 `validate_translation.py` 中的行內 Python 集合移至外部 JSON 檔案，以便於維護。驗證器會在執行時期載入該檔案。
The generator originally used `code: "in"` (deprecated Google Translate code) for Hindi instead of the correct ISO 639-1 `hi`. This was introduced in upstream commit `952b0b22c` by `diegosouzapw`. Fixed by changing `code: "in"` to `code: "hi"` in the `LOCALE_SPECS` array and removing the orphaned `in.json` file.
### `generate-multilang.mjs` 印度語代碼修正
### `validate_translation.py` Ignored Count Output
產生器原本使用 `code: "in"`（已棄用的 Google 翻譯代碼）來表示印度語，而不是正確的 ISO 639-1 `hi`。此問題由 `diegosouzapw` 在上游提交 `952b0b22c` 中引入。修正方式為將 `LOCALE_SPECS` 陣列中的 `code: "in"` 改為 `code: "hi"`，並移除孤立的 `in.json` 檔案。
The `quick` check now displays the count of ignored keys from `untranslatable-keys.json`:
### `validate_translation.py` 忽略計數輸出
`quick` 檢查現在會顯示來自 `untranslatable-keys.json` 的忽略按鍵計數：
```
Missing: 0
Untranslated: 0
Ignored (UNTRANSLATABLE_KEYS): 236
Ignored (UNTRANSLATABLE_KEYS): <隨版本而異>
```

571
docs/i18n/zh-TW/docs/guides/TROUBLESHOOTING.md
View File

@@ -1,72 +1,150 @@
# Troubleshooting (中文 (簡體))
---
title: "疑難排解"
version: 3.8.49
lastUpdated: 2026-07-15
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/TROUBLESHOOTING.md) · 🇸🇦 [ar](../../ar/docs/TROUBLESHOOTING.md) · 🇧🇬 [bg](../../bg/docs/TROUBLESHOOTING.md) · 🇧🇩 [bn](../../bn/docs/TROUBLESHOOTING.md) · 🇨🇿 [cs](../../cs/docs/TROUBLESHOOTING.md) · 🇩🇰 [da](../../da/docs/TROUBLESHOOTING.md) · 🇩🇪 [de](../../de/docs/TROUBLESHOOTING.md) · 🇪🇸 [es](../../es/docs/TROUBLESHOOTING.md) · 🇮🇷 [fa](../../fa/docs/TROUBLESHOOTING.md) · 🇫🇮 [fi](../../fi/docs/TROUBLESHOOTING.md) · 🇫🇷 [fr](../../fr/docs/TROUBLESHOOTING.md) · 🇮🇳 [gu](../../gu/docs/TROUBLESHOOTING.md) · 🇮🇱 [he](../../he/docs/TROUBLESHOOTING.md) · 🇮🇳 [hi](../../hi/docs/TROUBLESHOOTING.md) · 🇭🇺 [hu](../../hu/docs/TROUBLESHOOTING.md) · 🇮🇩 [id](../../id/docs/TROUBLESHOOTING.md) · 🇮🇹 [it](../../it/docs/TROUBLESHOOTING.md) · 🇯🇵 [ja](../../ja/docs/TROUBLESHOOTING.md) · 🇰🇷 [ko](../../ko/docs/TROUBLESHOOTING.md) · 🇮🇳 [mr](../../mr/docs/TROUBLESHOOTING.md) · 🇲🇾 [ms](../../ms/docs/TROUBLESHOOTING.md) · 🇳🇱 [nl](../../nl/docs/TROUBLESHOOTING.md) · 🇳🇴 [no](../../no/docs/TROUBLESHOOTING.md) · 🇵🇭 [phi](../../phi/docs/TROUBLESHOOTING.md) · 🇵🇱 [pl](../../pl/docs/TROUBLESHOOTING.md) · 🇵🇹 [pt](../../pt/docs/TROUBLESHOOTING.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) · 🇷🇴 [ro](../../ro/docs/TROUBLESHOOTING.md) · 🇷🇺 [ru](../../ru/docs/TROUBLESHOOTING.md) · 🇸🇰 [sk](../../sk/docs/TROUBLESHOOTING.md) · 🇸🇪 [sv](../../sv/docs/TROUBLESHOOTING.md) · 🇰🇪 [sw](../../sw/docs/TROUBLESHOOTING.md) · 🇮🇳 [ta](../../ta/docs/TROUBLESHOOTING.md) · 🇮🇳 [te](../../te/docs/TROUBLESHOOTING.md) · 🇹🇭 [th](../../th/docs/TROUBLESHOOTING.md) · 🇹🇷 [tr](../../tr/docs/TROUBLESHOOTING.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) · 🇵🇰 [ur](../../ur/docs/TROUBLESHOOTING.md) · 🇻🇳 [vi](../../vi/docs/TROUBLESHOOTING.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md)
# 疑難排解
> **給使用者**：想要快速解決問題？請參考下方的[快速參考](#快速參考)。
🌐 **語言：** 🇺🇸 [English](../../../../guides/TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/guides/TROUBLESHOOTING.md) | 🇪🇸 [Español](../../es/docs/guides/TROUBLESHOOTING.md) | 🇫🇷 [Français](../../fr/docs/guides/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../../it/docs/guides/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../../ru/docs/guides/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/guides/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../../de/docs/guides/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../../in/docs/guides/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../../th/docs/guides/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../../uk-UA/docs/guides/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../../ar/docs/guides/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../../ja/docs/guides/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/guides/TROUBLESHOOTING.md) | 🇧🇬 [Български](../../bg/docs/guides/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../../da/docs/guides/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../../fi/docs/guides/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../../he/docs/guides/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../../hu/docs/guides/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/guides/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../../ko/docs/guides/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/guides/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../../nl/docs/guides/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../../no/docs/guides/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/guides/TROUBLESHOOTING.md) | 🇷🇴 [Română](../../ro/docs/guides/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../../pl/docs/guides/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../../sk/docs/guides/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../../sv/docs/guides/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../../phi/docs/guides/TROUBLESHOOTING.md) | 🇨🇿 [Čeština](../../cs/docs/guides/TROUBLESHOOTING.md)
OmniRoute 的常見問題與解決方案。
---
Common problems and solutions for OmniRoute.
## 快速參考
**剛接觸 OmniRoute？** 從這裡開始 — 這些能解決 90% 的問題：
| 我看見這個 | 代表什麼 | 該怎麼做 |
| ----------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| 「無法連線」 | OmniRoute 未在執行 | 執行 `omniroute` 或 `docker restart omniroute` |
| 「API 金鑰無效」 | 金鑰錯誤或已過期 | 從供應商網站重新複製金鑰 |
| 「超出速率限制」 | 請求傳送過於頻繁 | 等待 1 分鐘，或使用 `model: "auto"` 自動切換 |
| 「超出配額」 | 免費/付費配額已用完 | 連接更多供應商，或使用免費供應商（Kiro, Pollinations） |
| 「回應緩慢」 | 供應商忙碌或距離較遠 | 使用 `model: "auto/fast"` 或連接較快的供應商（Groq, Cerebras） |
| 「使用了錯誤的供應商」 | `auto` 選了不同的供應商 | 這是正常的！`auto` 會選最好的。使用 `model: "openai/gpt-4o"` 來強制指定供應商 |
| 「502 Bad Gateway」 | 供應商故障 | 等待後重試，或使用 `model: "auto"` 切換供應商 |
| 「401 Unauthorized」 | 憑證錯誤 | 檢查 API 金鑰或重新透過 OAuth 認證 |
| 「429 Too Many Requests」| 已達速率限制 | 等待 1 分鐘，或連接更多供應商 |
**還是卡住了？** 請參考下方的[詳細疑難排解](#詳細疑難排解)，或在 [Discord](https://discord.gg/U47eFqAXCn) 上提問。
---
## Quick Fixes
| Problem | Solution |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) |
| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
| No logs written to disk | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled |
| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` |
| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) |
| Login crash / blank page | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below |
| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below |
| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below |
## 詳細疑難排解
---
## Node.js Compatibility
## 快速修復
<a name="nodejs-compatibility"></a>
| 問題 | 解決方案 |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 首次登入無法運作 | 在 `.env` 中設定 `INITIAL_PASSWORD`（無硬編碼預設值） |
| 儀表板開啟在錯誤的連接埠 | 設定 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
| 沒有日誌寫入磁碟 | 設定 `APP_LOG_TO_FILE=true`，並確認呼叫記錄捕捉功能已啟用 |
| EACCES：權限被拒 | 設定 `DATA_DIR=/path/to/writable/dir` 以覆蓋 `~/.omniroute` |
| 路由策略未儲存 | 更新至最新的 v3.x 版本（早期版本已修復 Zod schema 以確保設定持續性） |
| 登入崩潰／空白頁面 | 檢查 Node.js 版本 — 請參閱下方的 [Node.js 相容性](#nodejs-相容性) |
| `dlopen` / `slice is not valid mach-o file`（macOS）| 執行 `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — 請參閱下方的 [macOS 原生模組重建](#macos-原生模組重建) |
| Proxy「fetch 失敗」 | 確保 Proxy 設定在正確的層級 — 請參閱下方的 [Proxy 問題](#proxy-問題) |
| 防毒軟體隔離 `README.md` | 誤判 — 請參閱下方的[防毒軟體誤判](#防毒軟體誤判) |
| Kaspersky 將桌面應用程式標記為木馬 | 未簽署安裝程式的行為分析誤判 — 請參閱下方的[防毒軟體誤判](#防毒軟體誤判) |
### Login page crashes or shows "Module self-registration" error
---
**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.
## 防毒軟體誤判
**Symptoms:**
<a name="防毒軟體誤判"></a>
- Login page shows a blank screen or a server error
- Console shows `Error: Module did not self-register` or similar native binding errors
- The login page shows an **orange warning banner** with your Node version if the runtime is outside the supported secure policy
### Avast/AVG 將 `README.md` 隔離並標記為 `MD:HttpRequest-inf[Susp]`
**Fix:**
**這是誤判。沒有任何檔案受感染，也無需任何操作。**
1. Install a supported Node.js LTS release (recommended: Node.js 24.x):
Avast 和 AVG 執行啟發式掃描，會將包含大量類似 HTTP 請求連結的純文字/Markdown 檔案標記為可疑。OmniRoute 的 `README.md` 隨 npm 套件一起發布（它列在 `package.json` → `files` 中），因此在全域安裝時會出現在 `node_modules/omniroute/README.md` — 而其中包含約 15 個 `http://localhost:20128/...` 的範例（MCP HTTP/SSE 端點、A2A `.well-known` URL 以及 `curl` 程式碼片段）。這樣的連結密度足以觸發啟發式掃描。
如果這個問題是最近才發生的：檔案的本質並未改變。README 增加了端點表格（新增了 MCP HTTP + SSE + A2A）和更多 `curl` 範例，使其超過了閾值。
該檔案是沒有可執行內容的靜態文件。您可以安全地將其從隔離區還原。
**該怎麼做：**
1. **停止通知** — 在防毒軟體中排除安裝目錄（Avast：設定 → 例外），加入您的全域 `node_modules` 路徑和/或 OmniRoute 資料目錄（`~/.omniroute/`）。
2. **回報誤判** — <https://www.avast.com/false-positive-file-form.php>，附上被隔離的 `README.md`。這能幫助所有人，因為這是供應商的啟發式掃描對文字檔案的過度反應。
**為什麼我們不在這邊「修復」這個問題：** 範例全都是 `http://localhost`，而 localhost 若要使用 `https` 會需要自簽憑證，增加使用摩擦。為了避開某家廠商的啟發式掃描而修改文件，會損害所有讀者的閱讀體驗，只為了一個掃描器的錯誤。
### Kaspersky 將桌面應用程式標記為 `PDM:Trojan.Win32.Generic`
**這是行為啟發式掃描的誤判。沒有任何檔案受感染。** Kaspersky 的 `PDM:` 前綴表示判定來自其主動防禦模組（系統監控器），該模組根據安裝程式的*行為*來判斷，而非比對已知惡意軟體。當觸發時，Kaspersky 會「回滾」整個安裝過程 — 刪除它已經寫入的檔案 — 因此應用程式最終會損壞或遺失。
被標記的檔案是桌面應用程式所捆綁的、已聲明的開源依賴的標準組件，例如：
- `resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js` 和 `workerProcessEntry.js` — [Playwright](https://playwright.dev)，用於應用程式內供應商登入和瀏覽器支援聊天的瀏覽器自動化函式庫。
- `resources/app/.build/next/node_modules/tls-client-node-<hash>/bin/tls-client-windows-64-<ver>.dll` — 來自 `tls-client-node` 的原生二進位檔案，用於某些網路供應商的 Cloudflare 相容 HTTP。
**為什麼會觸發：** Windows 安裝程式**尚未進行程式碼簽署**，因此未簽署的 NSIS 安裝程式沒有信譽，行為啟發式掃描會以最大強度執行。加上捆綁的原生 DLL 和數百個寫入 `%LOCALAPPDATA%\Programs\OmniRoute` 的 `.js` 檔案（包括 Next.js 獨立建置的雜湊後綴套件目錄），這就足以觸發啟發式掃描。程式碼簽署已規劃中；在完成之前，新版本可能會重複觸發此問題。
**該怎麼做：**
1. **先驗證您的下載**（排除檔案被竄改的可能性）。每個版本都會發布 `latest.yml`，其 `sha512` 欄位（base64）涵蓋 `OmniRoute.Setup.<version>.exe` 安裝程式。在 PowerShell 中，從包含安裝程式的目錄執行：
```powershell
$b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
[System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
[Convert]::ToBase64String($b)
```
輸出必須與 `latest.yml` → `sha512` 相符。如果不符，請刪除檔案並僅從 [GitHub 發布頁面](https://github.com/diegosouzapw/OmniRoute/releases) 重新下載。
2. **還原 + 排除** — 從隔離區還原被回滾的項目，並為 `%LOCALAPPDATA%\Programs\OmniRoute` 加入排除規則（Kaspersky → 設定 → 威脅與排除），然後重新安裝。
3. **回報誤判** — <https://opentip.kaspersky.com/>。使用者提交的誤判報告確實能加速允許清單的建立。
---
## Node.js 相容性
<a name="nodejs-相容性"></a>
### 登入頁面崩潰或顯示「Module self-registration」錯誤
**原因：** 您執行的 Node.js 版本低於 OmniRoute 核准的安全執行環境最低版本。最常見的情況是執行較舊的 Node 22 或 24 修補版本，低於 OmniRoute 所需的修補安全門檻。
**症狀：**
- 登入頁面顯示空白畫面或伺服器錯誤
- 主控台顯示 `Error: Module did not self-register` 或類似的原生綁定錯誤
- 如果執行環境超出支援的安全政策範圍，登入頁面會顯示**橘色警告橫幅**，上面有您的 Node 版本
**修復方式：**
1. 安裝支援的 Node.js LTS 版本（建議：Node.js 24.x）：
```bash
nvm install 24
nvm use 24
```
2. Verify your version: `node --version` should show `v24.0.0` or newer on the 24.x LTS line
3. Reinstall OmniRoute: `npm install -g omniroute`
4. Restart: `omniroute`
2. 驗證版本：`node --version` 應顯示 `v24.0.0` 或更高的 24.x LTS 版本
3. 重新安裝 OmniRoute：`npm install -g omniroute`
4. 重新啟動：`omniroute`
> **Supported secure versions:** `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`. Node.js 24.x LTS (Krypton) is fully supported.
> **支援的安全版本：** `>=22.22.2 <23` 或 `>=24.0.0 <27`。Node.js 24.x LTS（Krypton）和 Node.js 26 皆受完整支援。
### macOS: `dlopen` / "slice is not valid mach-o file"
### macOS：`dlopen` /「slice is not valid mach-o file」
<a name="macos-native-module-rebuild"></a>
<a name="macos-原生模組重建"></a>
**Cause:** After a global `npm install -g omniroute`, the `better-sqlite3` native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment.
**原因：** 在全域 `npm install -g omniroute` 之後，套件內的 `better-sqlite3` 原生二進位檔案可能是為與本地執行環境不同的架構或 Node.js ABI 所編譯。這在 macOS（Apple Silicon 和 Intel 皆適用）上很常見，當預先編譯的二進位檔案與您的環境不符時就會發生。
**Symptoms:**
**症狀：**
- Server fails immediately on startup with a `dlopen` error
- Error contains `slice is not valid mach-o file`
- Full example:
- 伺服器在啟動時立即失敗，出現 `dlopen` 錯誤
- 錯誤訊息包含 `slice is not valid mach-o file`
- 完整範例：
```
dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
```
**Fix — rebuild for your local environment (no Node.js downgrade required):**
**修復方式 — 為您的本地環境重建（無需降級 Node.js）：**
```bash
cd $(npm root -g)/omniroute/app
@@ -74,98 +152,114 @@ npm rebuild better-sqlite3
omniroute
```
> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is **`>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`** (`engines` field in `package.json`). Node.js 24.x LTS (Krypton) is fully supported with `better-sqlite3` v12.x.
> **注意：** 這會針對您當地的 Node.js 版本和 CPU 架構重新編譯原生綁定，解決二進位檔案不匹配的問題。官方支援的執行環境範圍為 **`>=22.22.2 <23` 或 `>=24.0.0 <27`**（`src/shared/utils/nodeRuntimeSupport.ts` 中的 `SUPPORTED_NODE_RANGE`，與 `package.json` 的 `engines` 欄位一致）。Node.js 24.x LTS（Krypton）和 Node.js 26 搭配 `better-sqlite3` v12.x 皆受完整支援。
---
## Proxy Issues
## Proxy 問題
<a name="proxy-issues"></a>
<a name="proxy-問題"></a>
### Provider validation shows "fetch failed"
### 供應商驗證顯示「fetch 失敗」
**Cause:** The API key validation endpoint (`POST /api/providers/validate`) was previously bypassing proxy configuration, causing failures in environments that require proxy routing.
**原因：** API 金鑰驗證端點（`POST /api/providers/validate`）先前會繞過 Proxy 設定，導致在需要 Proxy 路由的環境中失敗。
**Fix (v3.5.5+):** This is now fixed. Provider validation routes through `runWithProxyContext`, honoring provider-level and global proxy settings automatically.
**修復方式（v3.5.5+）：** 此問題現已修復。供應商驗證會透過 `runWithProxyContext` 路由，自動遵循供應商層級和全域的 Proxy 設定。
### Token health check fails with "fetch failed"
### Token 健康狀態檢查失敗，顯示「fetch 失敗」
**Cause:** Background OAuth token refresh was not resolving proxy configuration per connection.
**原因：** 背景 OAuth Token 刷新未針對每個連線解析 Proxy 設定。
**Fix (v3.5.5+):** The token health check scheduler now resolves proxy config per connection before attempting refresh. Update to v3.5.5+.
**修復方式（v3.5.5+）：** Token 健康狀態檢查排程器現在會在嘗試刷新前，先為每個連線解析 Proxy 設定。請更新至 v3.5.5+。
### SOCKS5 proxy returns "invalid onRequestStart method"
### SOCKS5 Proxy 回傳「invalid onRequestStart method」
**Cause:** On Node.js 22, the undici@8 dispatcher is incompatible with Node's built-in `fetch()` implementation.
**原因：** 在 Node.js 22 上，undici@8 的分派器與 Node 內建的 `fetch()` 實作不相容。
**Fix (v3.5.5+):** OmniRoute now uses undici's own `fetch()` function when a proxy dispatcher is active, ensuring consistent behavior. Update to v3.5.5+.
**修復方式（v3.5.5+）：** OmniRoute 現在在啟用 Proxy 分派器時使用 undici 自己的 `fetch()` 函式，確保行為一致。請更新至 v3.5.5+。
### WSL 下的 MITM Proxy：Windows 主機上的桌面應用程式未被攔截
**原因：** MITM Proxy 及其 CA 憑證會安裝在 OmniRoute 執行的環境中。在 WSL 下，該環境是 Linux 客體，而 AI 桌面應用程式（Kiro、Trae、Copilot、Zed 等）則在 Windows 主機上執行。主機應用程式不信任客體的憑證儲存區，也不會透過客體的系統 Proxy 路由，因此桌面攔截無法在該處生效。
**建議：** 在與您要攔截的桌面應用程式相同的作業系統上原生執行 OmniRoute（Windows 應用程式用 Windows；macOS/Linux 同理）。在 WSL 內執行 OmniRoute 同時鎖定主機應用程式，需要手動在 Windows 主機上信任所產生的 CA 憑證，並將每個主機應用程式的網路/Proxy 設定指向 WSL Proxy 端點 — 這是不受支援且脆弱的設定。
---
## Provider Issues
## 供應商問題
### "Language model did not provide messages"
###「Language model did not provide messages」
**Cause:** Provider quota exhausted.
**原因：** 供應商配額已用完。
**Fix:**
**修復方式：**
1. Check dashboard quota tracker
2. Use a combo with fallback tiers
3. Switch to cheaper/free tier
1. 檢查儀表板配額追蹤器
2. 使用包含備援層級的組合
3. 切換至較便宜/免費的方案
### Rate Limiting
### 速率限制
**Cause:** Subscription quota exhausted.
**原因：** 訂閱配額已用完。
**Fix:**
**修復方式：**
- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
- Use GLM/MiniMax as cheap backup
- 加入備援：`cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview`
- 使用 GLM/MiniMax 作為便宜的備援方案
### OAuth Token Expired
### OAuth Token 已過期
OmniRoute auto-refreshes tokens. If issues persist:
OmniRoute 會自動刷新 Token。如果問題持續存在：
1. Dashboard → Provider → Reconnect
2. Delete and re-add the provider connection
1. 儀表板 → 供應商 → 重新連線
2. 刪除並重新加入供應商連線
### Kiro 多帳號：第二個帳號使第一個帳號失效
**原因：** Kiro 的後端對每個 OIDC 用戶端註冊強制執行單一活躍階段。當兩個帳號共用相同的已註冊用戶端（v3.8.0 之前匯入的連線）時，刷新一個帳號的 Token 會使另一個帳號的刷新 Token 失效。
**修復方式（v3.8.0+）：** 重新匯入受影響的連線。從 v3.8.0 開始，每個透過**匯入 Token**、**Google/GitHub 社群登入**或**自動匯入**建立的新 Kiro 連線，都會自動註冊其專屬的 OIDC 用戶端。因此該連線完全隔離，刷新一個帳號不會影響任何其他帳號。
在 v3.8.0 *之前*匯入的連線不帶有每個連線的用戶端註冊。這些連線會繼續使用共用的社群登入刷新端點。若要獲得隔離，請從儀表板 → 供應商刪除舊連線，並透過三種匯入流程之一重新加入。
如需完整詳細資訊和逐步新增兩個 Kiro 帳號的說明，請參閱 [`docs/guides/KIRO_SETUP.md`](./KIRO_SETUP.md)。
---
## Cloud Issues
## 雲端問題
### Cloud Sync Errors
### 雲端同步錯誤
1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
1. 確認 `BASE_URL` 指向您執行的實例（例如 `http://localhost:20128`）
2. 確認 `CLOUD_URL` 指向您的雲端端點（例如 `https://omniroute.dev`）
3. 保持 `NEXT_PUBLIC_*` 的值與伺服器端的值一致
### Cloud `stream=false` Returns 500
### 雲端 `stream=false` 回傳 500
**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
**症狀：** 雲端端點在非串流呼叫時出現 `Unexpected token 'd'...`。
**Cause:** Upstream returns SSE payload while client expects JSON.
**原因：** 上游回傳 SSE 負載，但用戶端預期的是 JSON。
**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
**解決方法：** 對雲端直接呼叫使用 `stream=true`。本地執行環境包含 SSE→JSON 備援機制。
### Cloud Says Connected but "Invalid API key"
### 雲端顯示已連線但出現「API 金鑰無效」
1. Create a fresh key from local dashboard (`/api/keys`)
2. Run cloud sync: Enable Cloud → Sync Now
3. Old/non-synced keys can still return `401` on cloud
1. 從本地儀表板（`/api/keys`）建立新的金鑰
2. 執行雲端同步：啟用雲端 → 立即同步
3. 舊的/未同步的金鑰仍可能在雲端回傳 `401`
---
## Docker Issues
## Docker 問題
### CLI Tool Shows Not Installed
### CLI 工具顯示未安裝
1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
2. For portable mode: use image target `runner-cli` (bundled CLIs)
3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
1. 檢查執行環境欄位：`curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
2. 對於可攜帶模式：使用映像檔目標 `runner-cli`（內建 CLI）
3. 對於主機掛載模式：設定 `CLI_EXTRA_PATHS` 並將主機 bin 目錄以唯讀方式掛載
4. 如果 `installed=true` 且 `runnable=false`：二進位檔案已找到但健康檢查失敗
### Quick Runtime Validation
### 快速執行環境驗證
```bash
curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
@@ -175,166 +269,281 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,
---
## Cost Issues
## 成本問題
### High Costs
### 成本過高
1. Check usage stats in Dashboard → Usage
2. Switch primary model to GLM/MiniMax
3. Set cost budgets per API key: Dashboard → API Keys → Budget
1. 在儀表板 → 使用量中檢查用量統計
2. 將主要模型切換至 GLM/MiniMax
3. 對非關鍵任務使用免費方案（Qoder、Kiro）
4. 為每個 API 金鑰設定成本預算：儀表板 → API 金鑰 → 預算
---
## Debugging
## 除錯
### Enable Log Files
### 啟用日誌檔案
Set `APP_LOG_TO_FILE=true` in your `.env` file. Application logs are written under `logs/`.
Request artifacts are stored under `${DATA_DIR}/call_logs/` when the call log pipeline is
enabled in settings.
在 `.env` 檔案中設定 `APP_LOG_TO_FILE=true`。應用程式日誌會寫入 `logs/` 目錄下。
請求工件會在啟用呼叫記錄管線時儲存在 `${DATA_DIR}/call_logs/` 目錄下。
啟用管線捕捉時，設定 `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false` 可省略串流區塊負載，或調整 `CALL_LOG_PIPELINE_MAX_SIZE_KB` 來變更工件大小上限（KB）。
### Check Provider Health
### 檢查供應商健康狀態
```bash
# Health dashboard
# 健康狀態儀表板
http://localhost:20128/dashboard/health
# API health check
# API 健康狀態檢查
curl http://localhost:20128/api/monitoring/health
```
### Runtime Storage
### 執行環境儲存
- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings)
- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/call_logs/`
- Application logs: `<repo>/logs/...` (when `APP_LOG_TO_FILE=true`)
- Call log artifacts: `${DATA_DIR}/call_logs/YYYY-MM-DD/...` when the call log pipeline is enabled
- 主要狀態：`${DATA_DIR}/storage.sqlite`（供應商、組合、別名、金鑰、設定）
- 使用量：`storage.sqlite` 中的 SQLite 表格（`usage_history`、`call_logs`、`proxy_logs`）+ 選用的 `${DATA_DIR}/call_logs/`
- 應用程式日誌：`<repo>/logs/...`（當 `APP_LOG_TO_FILE=true` 時）
- 呼叫記錄工件：啟用呼叫記錄管線時在 `${DATA_DIR}/call_logs/YYYY-MM-DD/...` 下
請求記錄頁面的**清理歷史記錄**動作會清除 `call_logs`、舊的 `request_detail_logs` 以及本地的 `${DATA_DIR}/call_logs/` 工件目錄。
---
## Circuit Breaker Issues
## 斷路器問題
### Provider stuck in OPEN state
### 供應商卡在 OPEN 狀態
When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
當供應商的斷路器處於 OPEN 狀態時，請求將被阻擋直到冷卻時間結束。
**Fix:**
**修復方式：**
1. Go to **Dashboard → Settings → Resilience**
2. Check the circuit breaker card for the affected provider
3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
4. Verify the provider is actually available before resetting
1. 前往**儀表板 → 設定 → 備援**
2. 檢查受影響供應商的斷路器卡片
3. 點擊**全部重設**以清除所有斷路器，或等待冷卻時間結束
4. 在重設前確認供應商確實可用
### Provider keeps tripping the circuit breaker
### 供應商持續觸發斷路器
If a provider repeatedly enters OPEN state:
如果供應商反覆進入 OPEN 狀態：
1. Check **Dashboard → Health → Provider Health** for the failure pattern
2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
3. Check if the provider has changed API limits or requires re-authentication
4. Review latency telemetry — high latency may cause timeout-based failures
1. 檢查**儀表板 → 健康狀態 → 供應商健康狀態**以了解失敗模式
2. 前往**設定 → 備援 → 供應商設定檔**並提高失敗閾值
3. 檢查供應商是否變更了 API 限制或需要重新認證
4. 檢閱延遲遙測資料 — 高延遲可能導致基於超時的失敗
---
## Audio Transcription Issues
## 語音轉文字問題
### "Unsupported model" error
###「Unsupported model」錯誤
- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
- Verify the provider is connected in **Dashboard → Providers**
- 確保使用正確的前綴：`deepgram/nova-3` 或 `assemblyai/best`
- 確認該供應商已在**儀表板 → 供應商**中連線
### Transcription returns empty or fails
### 轉錄回傳空值或失敗
- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
- Verify file size is within provider limits (typically < 25MB)
- Check provider API key validity in the provider card
- 檢查支援的音訊格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`
- 確認檔案大小在供應商限制內（通常 < 25MB）
- 在供應商卡片中檢查供應商 API 金鑰的有效性
---
## Translator Debugging
## 翻譯器除錯
Use **Dashboard → Translator** to debug format translation issues:
使用**儀表板 → 翻譯器**來除錯格式翻譯問題：
| Mode | When to Use |
| ---------------- | -------------------------------------------------------------------------------------------- |
| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates |
| **Chat Tester** | Send live messages and inspect the full request/response payload including headers |
| **Test Bench** | Run batch tests across format combinations to find which translations are broken |
| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues |
| 模式 | 使用時機 |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| **遊樂場** | 並排比較輸入/輸出格式 — 貼上失敗的請求以查看翻譯結果 |
| **聊天測試器** | 發送即時訊息並檢查完整的請求/回應負載，包括標頭 |
| **測試平台** | 跨格式組合執行批次測試，找出哪些翻譯有問題 |
| **即時監控器** | 監控即時請求流程，捕捉間歇性的翻譯問題 |
### Common format issues
### 常見格式問題
- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures
- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models
- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers
- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema`
- **思考標籤未顯示** — 檢查目標供應商是否支援思考功能以及思考預算設定
- **工具呼叫被遺漏** — 某些格式翻譯可能會移除不支援的欄位；請在遊樂場模式中驗證
- **系統提示詞遺失** — Claude 和 Gemini 處理系統提示詞的方式不同；請檢查翻譯輸出
- **SDK 回傳原始字串而非物件** — 已在 v1.x 中解決；回應清理器會移除導致 OpenAI SDK Pydantic 驗證失敗的非標準欄位（`x_groq`、`usage_breakdown` 等）。如果您在 v3.x+ 仍看到此問題，請提交 issue。
- **GLM/ERNIE 拒絕 `system` 角色** — 已在 v1.x 中解決；角色正規化器會自動將系統訊息合併到使用者訊息中，以相容不相容的模型。如果您在 v3.x+ 仍看到此問題，請提交 issue。
- **`developer` 角色不被辨識** — 已在 v1.x 中解決；對非 OpenAI 供應商會自動轉換為 `system`。如果您在 v3.x+ 仍看到此問題，請提交 issue。
- **`json_schema` 在 Gemini 上無法使用** — 已在 v1.x 中解決；`response_format` 現在會轉換為 Gemini 的 `responseMimeType` + `responseSchema`。如果您在 v3.x+ 仍看到此問題，請提交 issue。
---
## Resilience Settings
## 備援設定
### Auto rate-limit not triggering
### 自動速率限制未觸發
- Auto rate-limit only applies to API key providers (not OAuth/subscription)
- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
- Check if the provider returns `429` status codes or `Retry-After` headers
- 自動速率限制僅適用於 API 金鑰供應商（不適用於 OAuth/訂閱）
- 確認**設定 → 備援 → 供應商設定檔**已啟用自動速率限制
- 檢查供應商是否回傳 `429` 狀態碼或 `Retry-After` 標頭
### Tuning exponential backoff
### 調整指數退避
Provider profiles support these settings:
供應商設定檔支援以下設定：
- **Base delay** — Initial wait time after first failure (default: 1s)
- **Max delay** — Maximum wait time cap (default: 30s)
- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
- **基本延遲** — 首次失敗後的初始等待時間（預設：1 秒）
- **最大延遲** — 等待時間上限（預設：30 秒）
- **乘數** — 每次連續失敗延遲的增加倍率（預設：2 倍）
### Anti-thundering herd
### 防止驚群效應
When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
當大量並發請求湧入一個已達速率限制的供應商時，OmniRoute 會使用互斥鎖 + 自動速率限制來序列化請求，防止連鎖失敗。這對 API 金鑰供應商是自動生效的。
---
## Optional RAG / LLM failure taxonomy (16 problems)
## 選用：RAG / LLM 失敗分類（16 種問題）
Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong.
部分 OmniRoute 使用者將閘道器部署在 RAG 或 Agent 堆疊之前。在這些設定中，常會看到一種奇怪的現象：OmniRoute 看起來正常（供應商正常、路由設定檔無誤、無速率限制警示），但最終答案仍然錯誤。
In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself.
實際上，這些問題通常來自下游的 RAG 管線，而非閘道器本身。
If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers:
如果您想要一個共享的詞彙來描述這些失敗，可以使用 WFGY ProblemMap，這是一個外部的 MIT 授權文字資源，定義了十六種常見的 RAG / LLM 失敗模式。高層次涵蓋：
- retrieval drift and broken context boundaries
- empty or stale indexes and vector stores
- embedding versus semantic mismatch
- prompt assembly and context window issues
- logic collapse and overconfident answers
- long chain and agent coordination failures
- multi agent memory and role drift
- deployment and bootstrap ordering problems
- 檢索偏移與中斷的上下文邊界
- 空索引或過時索引以及向量儲存庫
- 嵌入與語義不匹配
- 提示詞組裝與上下文視窗問題
- 邏輯崩潰與過度自信的答案
- 長鏈與 Agent 協調失敗
- 多 Agent 記憶與角色偏移
- 部署與啟動順序問題
The idea is simple:
概念很簡單：
1. When you investigate a bad response, capture:
- user task and request
- route or provider combo in OmniRoute
- any RAG context used downstream (retrieved documents, tool calls, etc)
2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`).
3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs.
4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy.
1. 當您調查一個錯誤回應時，記錄：
- 使用者的任務與請求
- OmniRoute 中的路由或供應商組合
- 下游使用的任何 RAG 上下文（檢索的文件、工具呼叫等）
2. 將事件對應到一或兩個 WFGY ProblemMap 編號（`No.1` … `No.16`）。
3. 將編號儲存在您自己的儀表板、Runbook 或事件追蹤器中，放在 OmniRoute 日誌旁邊。
4. 使用對應的 WFGY 頁面來決定是否需要變更您的 RAG 堆疊、檢索器或路由策略。
Full text and concrete recipes live here (MIT license, text only):
完整文字與具體做法在此（MIT 授權，僅文字）：
[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md)
You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute.
如果您沒有在 OmniRoute 後方執行 RAG 或 Agent 管線，可以忽略本節。
---
## Still Stuck?
## v3.8.0 已知問題
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **Architecture**: See [`docs/architecture/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
- **API Reference**: See [`docs/reference/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
- **Translator**: Use **Dashboard → Translator** to debug format issues
v3.8.0 版本特有的問題及其目前的解決方法。如果後續修補版本中提供了修復，本條目將會更新或移除。
### Windsurf OAuth 流程失敗，顯示 401
**症狀：**
- 從儀表板完成 Windsurf OAuth 流程時出現「401 unauthorized」
- 回呼後 Windsurf 供應商卡片仍停留在「需要重新連線」狀態
**原因：**
- `WINDSURF_FIREBASE_API_KEY` 環境變數遺失或為空
- `WINDSURF_API_KEY` 設定錯誤或指向過期的 Token
- 本地防火牆/Proxy 阻擋了 OAuth 回呼
**修復方式：**
1. 確認 `.env` 中已設定 `WINDSURF_FIREBASE_API_KEY` 和 `WINDSURF_API_KEY`
2. 重新啟動 OmniRoute 以載入新的環境變數值
3. 從**儀表板 → 供應商 → Windsurf → 重新連線**重新執行 OAuth 流程
### Devin CLI 認證失敗
**症狀：**
- 呼叫 Devin 相關工具時出現「Devin CLI not found」或「auth failed」
- CLI 執行環境檢查回報 `installed=false`
**原因：**
- `CLI_DEVIN_BIN` 指向不存在的路徑
- 主機上未安裝 Devin CLI
**修復方式：**
1. 為您的平台安裝 Devin CLI
2. 在 `.env` 中設定 `CLI_DEVIN_BIN=/usr/local/bin/devin`（或實際路徑）
3. 重新啟動 OmniRoute 並從**儀表板 → CLI 工具**重新測試
### 模型冷卻卡住（手動重設）
**症狀：**
- 模型在冷卻時間過後仍列在冷卻清單中
- 儘管時間戳記已在過去，請求在組合路由中仍跳過該模型
**手動重設：**
- **儀表板：** **設定 → 模型冷卻** → 點擊受影響卡片上的**重新啟用**
- **API：** 使用管理認證標頭呼叫 `DELETE /api/resilience/model-cooldowns`
### Command Code 供應商連線失敗，顯示 403
**症狀：**
- 測試 Command Code 供應商連線時出現 403
- 剛新增後供應商卡片顯示「unauthorized」
**原因：** OAuth 流程未完成（回呼未收到或 Token 未持久化）。
**修復方式：**
- 從 CLI 執行 `omniroute providers` 以重新觸發 OAuth 流程，或
- 從**儀表板 → 供應商 → Command Code → 重新連線**重新執行 OAuth
### ModelScope 回傳積極的 429 冷卻
**症狀：**
- 在 ModelScope 上，少量請求突發後出現非常短或立即的冷卻
- 組合路由比預期更早跳過 ModelScope
**原因：** ModelScope 會發出供應商特定的 `Retry-After` 標頭。v3.8.0 提供了專門處理這些標頭的功能，因此較舊的版本會將其誤讀為一般的速率限制提示。
**修復方式：**
- 確保您使用 v3.8.0 或更新版本
- 確認**設定 → 備援**下的 `useUpstream429BreakerHints` 切換已啟用
### OMNIROUTE_WS_BRIDGE_SECRET 在生產環境中遺失
**症狀：**
- 在遠端生產主機上執行時，每個 Codex/Responses WebSocket 橋接請求都出現 401
- WebSocket 橋接握手在連線後立即關閉
**原因：** 生產環境缺少 `OMNIROUTE_WS_BRIDGE_SECRET` 環境變數。
**修復方式：**
1. 產生隨機密鑰：`openssl rand -hex 32`
2. 在生產伺服器環境中設定 `OMNIROUTE_WS_BRIDGE_SECRET=<隨機密鑰>`（以及任何與橋接通訊的用戶端）
3. 重新啟動 OmniRoute
### Responses API：背景模式降級為同步
**症狀：**
- 記錄警告：`background mode degraded to synchronous`
- `background: true` 請求回傳正常的同步回應，而非背景工作控制代碼
**原因：** v3.8.0 會故意將 Responses API 上的 `background: true` 降級為同步執行，同時發出警告。完整的非同步背景執行是未來的交付項目。
**修復方式：**
- 調整用戶端在不使用 `background` 的情況下呼叫，或
- 等待後續發布完整非同步背景模式的版本（請關注更新日誌）
---
## 還是卡住了？
- **GitHub Issues**：[github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **架構**：請參閱 [`docs/architecture/ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) 了解內部細節
- **API 參考**：請參閱 [`docs/reference/API_REFERENCE.md`](../reference/API_REFERENCE.md) 了解所有端點
- **健康狀態儀表板**：查看**儀表板 → 健康狀態**以取得即時系統狀態
- **翻譯器**：使用**儀表板 → 翻譯器**來除錯格式問題

134
docs/i18n/zh-TW/docs/guides/UNINSTALL.md
View File

@@ -1,56 +1,60 @@
# OmniRoute — Uninstall Guide (中文 (簡體))
---
title: "OmniRoute — 解除安裝指南"
version: 3.8.40
lastUpdated: 2026-06-28
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/UNINSTALL.md) · 🇸🇦 [ar](../../ar/docs/UNINSTALL.md) · 🇧🇬 [bg](../../bg/docs/UNINSTALL.md) · 🇧🇩 [bn](../../bn/docs/UNINSTALL.md) · 🇨🇿 [cs](../../cs/docs/UNINSTALL.md) · 🇩🇰 [da](../../da/docs/UNINSTALL.md) · 🇩🇪 [de](../../de/docs/UNINSTALL.md) · 🇪🇸 [es](../../es/docs/UNINSTALL.md) · 🇮🇷 [fa](../../fa/docs/UNINSTALL.md) · 🇫🇮 [fi](../../fi/docs/UNINSTALL.md) · 🇫🇷 [fr](../../fr/docs/UNINSTALL.md) · 🇮🇳 [gu](../../gu/docs/UNINSTALL.md) · 🇮🇱 [he](../../he/docs/UNINSTALL.md) · 🇮🇳 [hi](../../hi/docs/UNINSTALL.md) · 🇭🇺 [hu](../../hu/docs/UNINSTALL.md) · 🇮🇩 [id](../../id/docs/UNINSTALL.md) · 🇮🇹 [it](../../it/docs/UNINSTALL.md) · 🇯🇵 [ja](../../ja/docs/UNINSTALL.md) · 🇰🇷 [ko](../../ko/docs/UNINSTALL.md) · 🇮🇳 [mr](../../mr/docs/UNINSTALL.md) · 🇲🇾 [ms](../../ms/docs/UNINSTALL.md) · 🇳🇱 [nl](../../nl/docs/UNINSTALL.md) · 🇳🇴 [no](../../no/docs/UNINSTALL.md) · 🇵🇭 [phi](../../phi/docs/UNINSTALL.md) · 🇵🇱 [pl](../../pl/docs/UNINSTALL.md) · 🇵🇹 [pt](../../pt/docs/UNINSTALL.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/UNINSTALL.md) · 🇷🇴 [ro](../../ro/docs/UNINSTALL.md) · 🇷🇺 [ru](../../ru/docs/UNINSTALL.md) · 🇸🇰 [sk](../../sk/docs/UNINSTALL.md) · 🇸🇪 [sv](../../sv/docs/UNINSTALL.md) · 🇰🇪 [sw](../../sw/docs/UNINSTALL.md) · 🇮🇳 [ta](../../ta/docs/UNINSTALL.md) · 🇮🇳 [te](../../te/docs/UNINSTALL.md) · 🇹🇭 [th](../../th/docs/UNINSTALL.md) · 🇹🇷 [tr](../../tr/docs/UNINSTALL.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/UNINSTALL.md) · 🇵🇰 [ur](../../ur/docs/UNINSTALL.md) · 🇻🇳 [vi](../../vi/docs/UNINSTALL.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/UNINSTALL.md)
# OmniRoute — 解除安裝指南
🌐 **語言：** 🇺🇸 [English](./UNINSTALL.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/guides/UNINSTALL.md) | 🇪🇸 [Español](../i18n/es/docs/guides/UNINSTALL.md) | 🇫🇷 [Français](../i18n/fr/docs/guides/UNINSTALL.md) | 🇮🇹 [Italiano](../i18n/it/docs/guides/UNINSTALL.md) | 🇷🇺 [Русский](../i18n/ru/docs/guides/UNINSTALL.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/guides/UNINSTALL.md) | 🇩🇪 [Deutsch](../i18n/de/docs/guides/UNINSTALL.md) | 🇮🇳 [हिन्दी](../i18n/in/docs/guides/UNINSTALL.md) | 🇹🇭 [ไทย](../i18n/th/docs/guides/UNINSTALL.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/guides/UNINSTALL.md) | 🇸🇦 [العربية](../i18n/ar/docs/guides/UNINSTALL.md) | 🇯🇵 [日本語](../i18n/ja/docs/guides/UNINSTALL.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/guides/UNINSTALL.md) | 🇧🇬 [Български](../i18n/bg/docs/guides/UNINSTALL.md) | 🇩🇰 [Dansk](../i18n/da/docs/guides/UNINSTALL.md) | 🇫🇮 [Suomi](../i18n/fi/docs/guides/UNINSTALL.md) | 🇮🇱 [עברית](../i18n/he/docs/guides/UNINSTALL.md) | 🇭🇺 [Magyar](../i18n/hu/docs/guides/UNINSTALL.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/guides/UNINSTALL.md) | 🇰🇷 [한국어](../i18n/ko/docs/guides/UNINSTALL.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/guides/UNINSTALL.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/guides/UNINSTALL.md) | 🇳🇴 [Norsk](../i18n/no/docs/guides/UNINSTALL.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/guides/UNINSTALL.md) | 🇷🇴 [Română](../i18n/ro/docs/guides/UNINSTALL.md) | 🇵🇱 [Polski](../i18n/pl/docs/guides/UNINSTALL.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/guides/UNINSTALL.md) | 🇸🇪 [Svenska](../i18n/sv/docs/guides/UNINSTALL.md) | 🇵🇭 [Filipino](../i18n/phi/docs/guides/UNINSTALL.md) | 🇨🇿 [Čeština](../i18n/cs/docs/guides/UNINSTALL.md) | 🇹🇼 [繁體中文 (臺灣)](../i18n/zh-TW/docs/guides/UNINSTALL.md)
本指南說明如何從系統中徹底移除 OmniRoute。
---
This guide covers how to cleanly remove OmniRoute from your system.
## 快速解除安裝（v3.6.2+）
---
OmniRoute 提供兩個內建指令碼來進行乾淨的移除：
## Quick Uninstall (v3.6.2+)
OmniRoute provides two built-in scripts for clean removal:
### Keep Your Data
### 保留資料
```bash
npm run uninstall
```
This removes the OmniRoute application but **preserves** your database, configurations, API keys, and provider settings in `~/.omniroute/`. Use this if you plan to reinstall later and want to keep your setup.
此指令會移除 OmniRoute 應用程式，但**保留**您的資料庫、設定檔、API 金鑰及供應商設定於 `~/.omniroute/`。若您日後打算重新安裝並保留既有設定，請使用此方式。
### Full Removal
### 完整移除
```bash
npm run uninstall:full
```
This removes the application **and permanently erases** all data:
此指令會移除應用程式，**並永久刪除**所有資料：
- Database (`storage.sqlite`)
- Provider configurations and API keys
- Backup files
- Log files
- All files in the `~/.omniroute/` directory
- 資料庫（`storage.sqlite`）
- 供應商設定與 API 金鑰
- 備份檔案
- 日誌檔案
- `~/.omniroute/` 目錄中的所有檔案
> ⚠️ **Warning:** `npm run uninstall:full` is irreversible. All your provider connections, combos, API keys, and usage history will be permanently deleted.
> ⚠️ **警告：** `npm run uninstall:full` 為不可逆操作。所有供應商連線、組合設定、API 金鑰及使用記錄都將永久刪除。
---
## Manual Uninstall
## 手動解除安裝
### NPM Global Install
### NPM 全域安裝
```bash
# Remove the global package
# 移除全域套件
npm uninstall -g omniroute
# (Optional) Remove data directory
# （選擇性）移除資料目錄
rm -rf ~/.omniroute
```
### pnpm Global Install
### pnpm 全域安裝
```bash
pnpm uninstall -g omniroute
@@ -60,97 +64,97 @@ rm -rf ~/.omniroute
### Docker
```bash
# Stop and remove the container
# 停止並移除容器
docker stop omniroute
docker rm omniroute
# Remove the volume (deletes all data)
# 移除資料卷（刪除所有資料）
docker volume rm omniroute-data
# (Optional) Remove the image
# （選擇性）移除映像檔
docker rmi diegosouzapw/omniroute:latest
```
### Docker Compose
```bash
# Stop and remove containers
# 停止並移除容器
docker compose down
# Also remove volumes (deletes all data)
# 一併移除資料卷（刪除所有資料）
docker compose down -v
```
### Electron Desktop App
### Electron 桌面應用程式
**Windows:**
**Windows：**
- Open `Settings → Apps → OmniRoute → Uninstall`
- Or run the NSIS uninstaller from the install directory
- 開啟 `設定 → 應用程式 → OmniRoute → 解除安裝`
- 或從安裝目錄執行 NSIS 解除安裝程式
**macOS:**
**macOS：**
- Drag `OmniRoute.app` from `/Applications` to Trash
- Remove data: `rm -rf ~/Library/Application Support/omniroute`
- 將 `/Applications` 中的 `OmniRoute.app` 拖入垃圾桶
- 移除資料：`rm -rf ~/Library/Application Support/omniroute`
**Linux:**
**Linux：**
- Remove the AppImage file
- Remove data: `rm -rf ~/.omniroute`
- 刪除 AppImage 檔案
- 移除資料：`rm -rf ~/.omniroute`
### Source Install (git clone)
### 原始碼安裝（git clone）
```bash
# Remove the cloned directory
# 移除複製的目錄
rm -rf /path/to/omniroute
# (Optional) Remove data directory
# （選擇性）移除資料目錄
rm -rf ~/.omniroute
```
---
## Data Directories
## 資料目錄
OmniRoute stores data in the following locations by default:
OmniRoute 預設將資料存放於以下位置：
| Platform | Default Path | Override |
| ------------- | ----------------------------- | ------------------------- |
| Linux | `~/.omniroute/` | `DATA_DIR` env var |
| macOS | `~/.omniroute/` | `DATA_DIR` env var |
| Windows | `%APPDATA%/omniroute/` | `DATA_DIR` env var |
| Docker | `/app/data/` (mounted volume) | `DATA_DIR` env var |
| XDG-compliant | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` env var |
| 平台 | 預設路徑 | 覆蓋方式 |
| -------------- | ------------------------------ | ----------------------- |
| Linux | `~/.omniroute/` | `DATA_DIR` 環境變數 |
| macOS | `~/.omniroute/` | `DATA_DIR` 環境變數 |
| Windows | `%APPDATA%/omniroute/` | `DATA_DIR` 環境變數 |
| Docker | `/app/data/`（掛載資料卷） | `DATA_DIR` 環境變數 |
| XDG 相容模式 | `$XDG_CONFIG_HOME/omniroute/` | `XDG_CONFIG_HOME` 環境變數 |
### Files in the data directory
### 資料目錄中的檔案
| File/Directory | Description |
| -------------------- | ------------------------------------------------- |
| `storage.sqlite` | Main database (providers, combos, settings, keys) |
| `storage.sqlite-wal` | SQLite write-ahead log (temporary) |
| `storage.sqlite-shm` | SQLite shared memory (temporary) |
| `call_logs/` | Request payload archives |
| `backups/` | Automatic database backups |
| `log.txt` | Legacy request log (optional) |
| 檔案/目錄 | 說明 |
| --------------------- | --------------------------------------- |
| `storage.sqlite` | 主要資料庫（供應商、組合、設定、金鑰） |
| `storage.sqlite-wal` | SQLite 預寫式日誌（暫存） |
| `storage.sqlite-shm` | SQLite 共享記憶體（暫存） |
| `call_logs/` | 請求承載記錄封存 |
| `backups/` | 自動資料庫備份 |
| `log.txt` | 舊版請求日誌（選用） |
---
## Verify Complete Removal
## 驗證是否完整移除
After uninstalling, verify there are no remaining files:
解除安裝後，請確認無殘留檔案：
```bash
# Check for global npm package
# 檢查全域 npm 套件
npm list -g omniroute 2>/dev/null
# Check for data directory
# 檢查資料目錄
ls -la ~/.omniroute/ 2>/dev/null
# Check for running processes
# 檢查正在執行的程序
pgrep -f omniroute
```
If any process is still running, stop it:
若仍有程序在執行，請將其停止：
```bash
pkill -f omniroute

1136
docs/i18n/zh-TW/docs/guides/USER_GUIDE.md
View File

File diff suppressed because it is too large Load Diff

209
docs/i18n/zh-TW/docs/ops/COVERAGE_PLAN.md
View File

@@ -1,170 +1,183 @@
# Test Coverage Plan (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/COVERAGE_PLAN.md) · 🇸🇦 [ar](../../ar/docs/COVERAGE_PLAN.md) · 🇧🇬 [bg](../../bg/docs/COVERAGE_PLAN.md) · 🇧🇩 [bn](../../bn/docs/COVERAGE_PLAN.md) · 🇨🇿 [cs](../../cs/docs/COVERAGE_PLAN.md) · 🇩🇰 [da](../../da/docs/COVERAGE_PLAN.md) · 🇩🇪 [de](../../de/docs/COVERAGE_PLAN.md) · 🇪🇸 [es](../../es/docs/COVERAGE_PLAN.md) · 🇮🇷 [fa](../../fa/docs/COVERAGE_PLAN.md) · 🇫🇮 [fi](../../fi/docs/COVERAGE_PLAN.md) · 🇫🇷 [fr](../../fr/docs/COVERAGE_PLAN.md) · 🇮🇳 [gu](../../gu/docs/COVERAGE_PLAN.md) · 🇮🇱 [he](../../he/docs/COVERAGE_PLAN.md) · 🇮🇳 [hi](../../hi/docs/COVERAGE_PLAN.md) · 🇭🇺 [hu](../../hu/docs/COVERAGE_PLAN.md) · 🇮🇩 [id](../../id/docs/COVERAGE_PLAN.md) · 🇮🇹 [it](../../it/docs/COVERAGE_PLAN.md) · 🇯🇵 [ja](../../ja/docs/COVERAGE_PLAN.md) · 🇰🇷 [ko](../../ko/docs/COVERAGE_PLAN.md) · 🇮🇳 [mr](../../mr/docs/COVERAGE_PLAN.md) · 🇲🇾 [ms](../../ms/docs/COVERAGE_PLAN.md) · 🇳🇱 [nl](../../nl/docs/COVERAGE_PLAN.md) · 🇳🇴 [no](../../no/docs/COVERAGE_PLAN.md) · 🇵🇭 [phi](../../phi/docs/COVERAGE_PLAN.md) · 🇵🇱 [pl](../../pl/docs/COVERAGE_PLAN.md) · 🇵🇹 [pt](../../pt/docs/COVERAGE_PLAN.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) · 🇷🇴 [ro](../../ro/docs/COVERAGE_PLAN.md) · 🇷🇺 [ru](../../ru/docs/COVERAGE_PLAN.md) · 🇸🇰 [sk](../../sk/docs/COVERAGE_PLAN.md) · 🇸🇪 [sv](../../sv/docs/COVERAGE_PLAN.md) · 🇰🇪 [sw](../../sw/docs/COVERAGE_PLAN.md) · 🇮🇳 [ta](../../ta/docs/COVERAGE_PLAN.md) · 🇮🇳 [te](../../te/docs/COVERAGE_PLAN.md) · 🇹🇭 [th](../../th/docs/COVERAGE_PLAN.md) · 🇹🇷 [tr](../../tr/docs/COVERAGE_PLAN.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) · 🇵🇰 [ur](../../ur/docs/COVERAGE_PLAN.md) · 🇻🇳 [vi](../../vi/docs/COVERAGE_PLAN.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md)
---
title: "測試覆蓋率計畫"
version: 3.8.40
lastUpdated: 2026-06-28
---
Last updated: 2026-03-28
# 測試覆蓋率計畫
## Baseline
最後更新：2026-06-28
There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful.
> 狀態測量於 2026-05-13：行 82.58%、陳述式 82.58%、函式 84.23%、條件分支 75.22%。第 1–5 階段已完成。當前重點為第 6 階段（>=85%）與第 7 階段（>=90%）。
| Metric | Scope | Statements / Lines | Branches | Functions | Notes |
| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- |
| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` |
| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` |
| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve |
## 基準
The recommended baseline is the number to optimize against.
根據報告計算方式的不同，會有多組覆蓋率數字。在規劃上，只有其中一組具有參考價值。
## Rules
| 指標 | 範圍 | 陳述式／行 | 條件分支 | 函式 | 備註 |
| ---------------------- | ----------------------------------------------------- | ---------: | -------: | --------: | ------------------------------------------------- |
| 舊版 | 舊有 `npm run test:coverage` | 79.42% | 75.15% | 67.94% | 失真：計入了測試檔且排除 `open-sse` |
| 診斷用 | 僅原始碼，排除測試檔且排除 `open-sse` | 68.16% | 63.55% | 64.06% | 僅用於隔離 `src/**` 分析 |
| 建議基準 | 僅原始碼，排除測試檔且納入 `open-sse` | 82.58% | 75.22% | 84.23% | 這是應改善的專案級基準 |
- Coverage targets apply to source files, not to `tests/**`.
- `open-sse/**` is part of the product and must remain in scope.
- New code should not reduce coverage in touched areas.
- Prefer testing behavior and branch outcomes over implementation details.
- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`.
建議基準是應優化的目標數字。
## Current command set
## 規則
- 覆蓋率目標適用於原始碼，不包含 `tests/**`。
- `open-sse/**` 屬於產品的一部分，必須納入範圍。
- 新程式碼不應降低受影響區域的覆蓋率。
- 優先測試行為與條件分支結果，而非實作細節。
- 對於 `src/lib/db/**`，優先使用暫存 SQLite 資料庫與小型測試資料，而非廣泛的 Mock。
## 當前指令集
- `npm run test:coverage`
- Main source coverage gate for the unit test suite
- Generates `text-summary`, `html`, `json-summary`, and `lcov`
- 單元測試套件的主要原始碼覆蓋率閘門
- 產生 `text-summary`、`html`、`json-summary` 與 `lcov`
- `npm run coverage:report`
- Detailed file-by-file report from the latest run
- 來自最近一次執行的逐檔詳細報告
- `npm run test:coverage:legacy`
- Historical comparison only
- 僅供歷史比較
## Milestones
## 里程碑
| Phase | Target | Focus |
| ------- | ---------------------: | ------------------------------------------------- |
| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage |
| Phase 2 | 65% statements / lines | DB and route foundations |
| Phase 3 | 70% statements / lines | Provider validation and usage analytics |
| Phase 4 | 75% statements / lines | `open-sse` translators and helpers |
| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches |
| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites |
| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet |
| 階段 | 目標 | 重點 | 狀態 |
| -------- | -------------------: | ------------------------------------------------ | ------------- |
| 第 1 階段 | 60% 陳述式／行 | 快速取勝與低風險通用工具覆蓋率 | ✅ 已完成 |
| 第 2 階段 | 65% 陳述式／行 | 資料庫與路由基礎 | ✅ 已完成 |
| 第 3 階段 | 70% 陳述式／行 | Provider 驗證與使用分析 | ✅ 已完成 |
| 第 4 階段 | 75% 陳述式／行 | `open-sse` 轉換器與輔助工具 | ✅ 已完成 |
| 第 5 階段 | 80% 陳述式／行 | `open-sse` 處理器與執行器分支 | ✅ 已完成 |
| 第 6 階段 | 85% 陳述式／行 | 較難的邊界案例、分支負債、回歸測試套件 | 進行中 |
| 第 7 階段 | 90% 陳述式／行 | 最終掃蕩、缺口補齊、嚴格棘輪機制 | 待處理 |
Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines.
條件分支與函式應隨各階段逐步提升，但主要硬目標仍為陳述式／行。
## Priority hotspots
## 優先熱點
These files or areas offer the best return for the next phases:
這些檔案目前行覆蓋率最低（< 60%），在第 6–7 階段中能帶來最佳改善效益。資料來源為 `coverage/coverage-summary.json`（2026-05-13）：
1. `open-sse/handlers`
- `chatCore.ts` at 7.57%
- Overall directory at 29.07%
2. `open-sse/translator/request`
- Overall directory at 36.39%
- Many translators are still near single-digit coverage
3. `open-sse/translator/response`
- Overall directory at 8.07%
4. `open-sse/executors`
- Overall directory at 36.62%
5. `src/lib/db`
- `models.ts` at 20.66%
- `registeredKeys.ts` at 34.46%
- `modelComboMappings.ts` at 36.25%
- `settings.ts` at 46.40%
- `webhooks.ts` at 33.33%
6. `src/lib/usage`
- `usageHistory.ts` at 21.12%
- `usageStats.ts` at 9.56%
- `costCalculator.ts` at 30.00%
7. `src/lib/providers`
- `validation.ts` at 41.16%
8. Low-risk utility and API files for early gains
- `src/shared/utils/upstreamError.ts`
- `src/shared/utils/apiAuth.ts`
- `src/lib/api/errorResponse.ts`
- `src/app/api/settings/require-login/route.ts`
- `src/app/api/providers/[id]/models/route.ts`
| # | 檔案 | 行覆蓋率 % |
| --- | ------------------------------------------------------------- | --------: |
| 1 | `open-sse/services/compression/validation.ts` | 7.87% |
| 2 | `src/app/api/v1/batches/route.ts` | 9.67% |
| 3 | `src/app/docs/components/FeedbackWidget.tsx` | 9.80% |
| 4 | `open-sse/services/compression/toolResultCompressor.ts` | 10.00% |
| 5 | `src/app/docs/components/DocCodeBlocks.tsx` | 10.63% |
| 6 | `open-sse/services/compression/engines/rtk/lineFilter.ts` | 10.96% |
| 7 | `open-sse/services/specificityRules.ts` | 11.28% |
| 8 | `src/mitm/systemCommands.ts` | 12.19% |
| 9 | `open-sse/services/compression/aggressive.ts` | 12.77% |
| 10 | `src/app/api/v1/batches/[id]/cancel/route.ts` | 12.98% |
| 11 | `open-sse/services/compression/progressiveAging.ts` | 13.26% |
| 12 | `open-sse/services/compression/engines/rtk/smartTruncate.ts` | 13.43% |
| 13 | `open-sse/services/compression/engines/rtk/deduplicator.ts` | 13.51% |
| 14 | `src/lib/cloudAgent/agents/jules.ts` | 13.52% |
| 15 | `open-sse/services/compression/lite.ts` | 14.46% |
| 16 | `src/app/api/v1/rerank/route.ts` | 14.94% |
| 17 | `open-sse/services/compression/preservation.ts` | 15.07% |
| 18 | `src/lib/cloudAgent/agents/codex.ts` | 15.54% |
| 19 | `open-sse/services/tierResolver.ts` | 16.66% |
| 20 | `src/app/docs/components/DocsLazyWrapper.tsx` | 16.66% |
## Execution checklist
第 6–7 階段的主題：
### Phase 1: 56.95% -> 60%
- `open-sse/services/compression/**` 是低覆蓋率最密集的區塊，主導了剩餘差距。
- 批次與重排序 API 路由（`src/app/api/v1/batches/**`、`src/app/api/v1/rerank/route.ts`）需要處理器層級的測試。
- Cloud Agent 轉接器（`src/lib/cloudAgent/agents/jules.ts`、`codex.ts`）與 `tierResolver.ts` 需要情境測試。
- Docs UI 元件與 `src/mitm/systemCommands.ts` 優先級較低，但屬於低成本的分支改善機會。
- [x] Fix coverage metric so it reflects source code instead of test files
- [x] Keep a legacy coverage script for comparison
- [x] Record the baseline and hotspots in-repo
- [ ] Add focused tests for low-risk utilities:
## 執行檢查清單
### 第 1 階段：56.95% -> 60%
- [x] 修正覆蓋率指標，使其反映原始碼而非測試檔
- [x] 保留舊版覆蓋率腳本以供比較
- [x] 在儲存庫中記錄基準與熱點
- [ ] 為低風險通用工具新增聚焦測試：
- `src/shared/utils/upstreamError.ts`
- `src/shared/utils/fetchTimeout.ts`
- `src/lib/api/errorResponse.ts`
- `src/shared/utils/apiAuth.ts`
- `src/lib/display/names.ts`
- [ ] Add route tests for:
- [ ] 為以下路由新增測試：
- `src/app/api/settings/require-login/route.ts`
- `src/app/api/providers/[id]/models/route.ts`
### Phase 2: 60% -> 65%
### 第 2 階段：60% -> 65%
- [ ] Add DB-backed tests for:
- [ ] 新增資料庫驅動測試：
- `src/lib/db/modelComboMappings.ts`
- `src/lib/db/settings.ts`
- `src/lib/db/registeredKeys.ts`
- [ ] Cover branch behavior in:
- [ ] 涵蓋以下項目的條件分支行為：
- `src/lib/providers/validation.ts`
- `src/app/api/v1/embeddings/route.ts`
- `src/app/api/v1/moderations/route.ts`
### Phase 3: 65% -> 70%
### 第 3 階段：65% -> 70%
- [ ] Add usage analytics tests for:
- [ ] 新增使用分析測試：
- `src/lib/usage/usageHistory.ts`
- `src/lib/usage/usageStats.ts`
- `src/lib/usage/costCalculator.ts`
- [ ] Expand route coverage for proxy management and settings branches
- [ ] 擴充 Proxy 管理與設定分支的路由覆蓋率
### Phase 4: 70% -> 75%
### 第 4 階段：70% -> 75%
- [ ] Cover translator helpers and central translation paths:
- [ ] 涵蓋轉換器輔助工具與中央翻譯路徑：
- `open-sse/translator/index.ts`
- `open-sse/translator/helpers/*`
- `open-sse/translator/request/*`
- `open-sse/translator/response/*`
### Phase 5: 75% -> 80%
### 第 5 階段：75% -> 80%
- [ ] Add handler-level tests for:
- [ ] 新增處理器層級測試：
- `open-sse/handlers/chatCore.ts`
- `open-sse/handlers/responsesHandler.js`
- `open-sse/handlers/imageGeneration.js`
- `open-sse/handlers/embeddings.js`
- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides
- [ ] 針對 Provider 特定的驗證、重試與端點覆寫，新增執行器分支覆蓋率
### Phase 6: 80% -> 85%
### 第 6 階段：80% -> 85%
- [ ] Merge more edge-case suites into the main coverage path
- [ ] Increase function coverage for DB modules with weak constructor/helper coverage
- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers
- [ ] 將更多邊界案例測試套件納入主要覆蓋率路徑
- [ ] 提升建構子／輔助工具覆蓋率薄弱的資料庫模組的函式覆蓋率
- [ ] 補齊 `settings.ts`、`registeredKeys.ts`、`validation.ts` 與轉換器輔助工具中的條件分支缺口
### Phase 7: 85% -> 90%
### 第 7 階段：85% -> 90%
- [ ] Treat the remaining low-coverage files as blockers
- [ ] Add regression tests for every uncovered production bug fixed during the push to 90%
- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs
- [ ] 將剩餘低覆蓋率檔案視為阻擋事項
- [ ] 為在推進至 90% 過程中所修正的每一個未覆蓋的正式環境錯誤，新增回歸測試
- [ ] 僅在本地基準連續兩次執行穩定後，才在 CI 中調高覆蓋率閘門
## Ratchet policy
## 棘輪機制
Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer.
僅在專案實際以充裕緩衝超越下一里程碑後，才更新 `npm run test:coverage` 的閾值。
Recommended ratchet sequence:
**當前閘門：**`npm run test:coverage` 強制執行 **60 陳述式 / 60 行 / 60 函式 / 60 條件分支**（該指標已在 Quality-Gates 第 6A.1 階段重新基準化——先前的 82.58% 基準因計入測試檔且排除 `open-sse` 而有失真）。`test:coverage:legacy` 指令保留舊有的 50/50/50 指標以供歷史比較。
如需針對最新報告進行臨時閾值檢查，請使用：
```bash
node scripts/check/test-report-summary.mjs --threshold 75
```
建議的棘輪序列（順序為 `陳述式-行 / 條件分支 / 函式`）：
1. 55/60/55
2. 60/62/58
3. 65/64/62
4. 70/66/66
5. 75/70/72
5. 75/70/72 <-- 當前閘門（75/70/75）
6. 80/75/78
7. 85/80/84
8. 90/85/88
Order is `statements-lines / branches / functions`.
下一個棘輪目標為 `80/75/78`，當條件分支覆蓋率連續兩次執行維持在 78% 以上時即生效。
## Known gap
## 已知缺口
The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb.
目前的覆蓋率指令測量的是主要的 Node 單元測試套件，並包含從中可達的原始碼（包括 `open-sse`）。它尚未將 Vitest 覆蓋率合併為單一統一報告。這項合併工作值得日後進行，但不會阻礙從 60% 邁向 80% 的爬升。

311
docs/i18n/zh-TW/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md
View File

@@ -1,32 +1,36 @@
# OmniRoute Fly.io 部署指南 (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md)
---
title: "OmniRoute Fly.io 部署指南（繁體中文）"
version: 3.8.40
lastUpdated: 2026-06-28
---
本文檔記錄 OmniRoute 在 Fly.io 上的實際部署方法，適用於兩類場景：
# OmniRoute Fly.io 部署指南（繁體中文）
- 首次把當前項目部署到 Fly.io
- 後續代碼更新後繼續發布
- 新項目參考同樣流程部署
🌐 **語言:** 🇺🇸 [English](../../../../docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FLY_IO_DEPLOYMENT_GUIDE.md)
本文基於當前項目已經驗證通過的設定整理，應用名為 `omniroute`。
本文件說明 OmniRoute 在 Fly.io 上的實際部署流程，涵蓋兩種情境：
- 首次將目前專案部署到 Fly.io
- 發布後續程式碼更新
- 新專案遵循相同的部署工作流程
本指南基於目前專案經過驗證的有效配置。應用程式名稱為 `omniroute`。
---
## 1. 部署目標
- 平臺：Fly.io
- 部署方式：本地 `flyctl` 直接發布
- 運行方式：使用倉庫內現有 `Dockerfile` 和 `fly.toml`
- 數據持久化：Fly Volume 掛載到 `/data`
- 訪問地址：`https://omniroute.fly.dev/`
- 平台：Fly.io
- 部署方式：本機 `flyctl` 直接發布
- 執行環境：使用儲存庫中現有的 `Dockerfile` 和 `fly.toml`
- 資料持久化：Fly Volume 掛載至 `/data`
- 存取 URL：`https://omniroute.fly.dev/`
---
## 2. 當前項目關鍵設定
## 2. 目前專案關鍵配置
當前倉庫中的 `fly.toml` 已確認包含以下關鍵項：
目前儲存庫中的 `fly.toml` 已確認包含以下關鍵項目：
```toml
app = 'omniroute'
@@ -49,15 +53,15 @@ primary_region = 'sin'
BIND = "0.0.0.0"
```
說明：
注意事項：
- `app = 'omniroute'` 決定實際部署到哪個 Fly 應用
- `destination = '/data'` 決定持久卷掛載目錄
- 本項目必須讓 `DATA_DIR=/data`，否則資料庫和密鑰會寫到容器臨時目錄
- `app = 'omniroute'` 決定部署目標是哪個 Fly 應用程式
- `destination = '/data'` 決定持久化磁碟區的掛載目錄
- 此專案必須設定 `DATA_DIR=/data`，否則資料庫和金鑰會寫入容器的暫存目錄
---
## 3. 必備工具
## 3. 前置需求
### 3.1 安裝 Fly CLI
@@ -67,15 +71,15 @@ Windows PowerShell：
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
```
如果安裝腳本在當前環境失敗，也可以手動下載 `flyctl` 二進位並放到 `PATH` 中。
如果安裝腳本在您的環境中失敗，您也可以手動下載 `flyctl` 二進位檔並將其加入 `PATH`。
### 3.2 登錄 Fly 帳號
### 3.2 登入您的 Fly 帳戶
```powershell
flyctl auth login
```
### 3.3 檢查登錄狀態
### 3.3 驗證登入狀態
```powershell
flyctl auth whoami
@@ -84,43 +88,43 @@ flyctl version
---
## 4. 首次部署當前項目
## 4. 首次部署目前專案
### 4.1 獲取代碼並進入目錄
### 4.1 複製程式碼並進入目錄
```powershell
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
```
### 4.2 確認應用名
### 4.2 確認應用程式名稱
打開 `fly.toml`，重點看這一行：
開啟 `fly.toml` 並確認以下行：
```toml
app = 'omniroute'
```
如果你準備部署到自己的新應用，可改成全局唯一名稱，例如：
如果您要部署到自己的新應用程式，可以將其變更為全域唯一的名稱，例如：
```toml
app = 'omniroute-yourname'
```
注意：
注意事項：
- 控制臺裡要看的是與 `fly.toml` 裡 `app` 一致的應用
- 以前如果用過別的名字，例如 `oroute`，不要和 `omniroute` 混淆
- 請確保您在控制台中看到的應用程式與 `fly.toml` 中的 `app` 值相符
- 如果您之前使用過不同的名稱（例如 `oroute`），請不要與 `omniroute` 混淆
### 4.3 創建應用
### 4.3 建立應用程式
如果該應用尚不存在：
如果應用程式尚未存在：
```powershell
flyctl apps create omniroute
```
如果你已經改成別的應用名，把 `omniroute` 替換成你的名字。
如果您變更了應用程式名稱，請將 `omniroute` 替換為您選擇的名稱。
### 4.4 首次部署
@@ -130,163 +134,204 @@ flyctl deploy
---
## 5. 必配參數
## 5. 必要參數
本項目在 Fly.io 上建議至少設定以下參數。
本專案建議至少在 Fly.io 上配置以下參數。
### 5.1 已驗證使用的參數
### 5.1 已驗證的參數
這些參數已經在當前 `omniroute` 應用上實際部署：
以下參數已在目前 `omniroute` 應用程式的實際部署中使用：
- `API_KEY_SECRET`
- `DATA_DIR`
- `JWT_SECRET`
- `MACHINE_ID_SALT`
- `NEXT_PUBLIC_BASE_URL`
- `OMNIROUTE_WS_BRIDGE_SECRET`（生產環境必填 — 用於 WebSocket 橋接認證）
- `STORAGE_ENCRYPTION_KEY`
### 5.2 關於 `INITIAL_PASSWORD`
當前項目沒有設置 `INITIAL_PASSWORD`，因為本次部署按需求不使用它。
目前專案未設定 `INITIAL_PASSWORD`，因為此部署不需要。
如果不設置：
如果未設定：
- 啟動日誌會提示默認密碼是 `CHANGEME`
- 部署後應儘快在系統設置中修改登錄密碼
- 啟動日誌會顯示預設密碼為 `CHANGEME`
- 您應在部署後盡快在系統設定中變更登入密碼
如果你希望無人值守初始化後臺密碼，也可以後續補：
如果您想在無人值守的情況下初始化後端密碼，可以之後再新增：
- `INITIAL_PASSWORD`
---
## 6. 推薦參數說明
## 6. 建議參數
### 6.1 Secrets 中設置
### 6.1 機密配置
建議放入 Fly Secrets：
以下變數建議用於 Fly Secrets：
| 變量名 | 是否推薦 | 說明 |
| ------------------------ | -------- | ------------------------------ |
| `API_KEY_SECRET` | 必需 | API Key 生成與校驗使用 |
| `JWT_SECRET` | 必需 | 登錄態和 JWT 籤名使用 |
| `STORAGE_ENCRYPTION_KEY` | 強烈推薦 | 加密存儲敏感連接資訊 |
| `MACHINE_ID_SALT` | 推薦 | 生成穩定機器標識 |
| `INITIAL_PASSWORD` | 可選 | 首次部署時直接指定後臺初始密碼 |
| OAuth/API 私密憑證 | 按需 | 各類外部平臺鑑權設定 |
| 變數 | 建議 | 說明 |
| ----------------------------- | -------------- | ----------------------------------- |
| `API_KEY_SECRET` | 必填 | 用於 API 金鑰產生與驗證 |
| `JWT_SECRET` | 必填 | 用於登入工作階段和 JWT 簽章 |
| `OMNIROUTE_WS_BRIDGE_SECRET` | 生產環境必填 | WebSocket 橋接認證密鑰 |
| `STORAGE_ENCRYPTION_KEY` | 強烈建議 | 靜態加密敏感連線資訊 |
| `MACHINE_ID_SALT` | 建議 | 產生穩定的機器識別碼 |
| `INITIAL_PASSWORD` | 可選 | 首次部署時設定初始後端密碼 |
| OAuth/API 私有憑證 | 視需要而定 | 外部平台認證配置 |
### 6.2 當前項目推薦值
### 6.2 目前專案的建議值
| 變量名 | 推薦值 |
| 變數 | 建議值 |
| ---------------------- | --------------------------- |
| `DATA_DIR` | `/data` |
| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |
說明：
注意事項：
- `DATA_DIR=/data` 非常關鍵，必須與 Fly Volume 掛載點一致
- `NEXT_PUBLIC_BASE_URL` 用於調度器和前端回調等場景
- `DATA_DIR=/data` 至關重要，必須與 Fly Volume 掛載點相符
- `NEXT_PUBLIC_BASE_URL` 由排程器、前端回呼等使用
### 6.3 OAuth 回呼 URL 配置
如果您需要在 Fly.io 部署上啟用基於 OAuth 的提供商（例如 Antigravity、Gemini、Cursor），請確保以下兩點：
1. **將 `NEXT_PUBLIC_BASE_URL` 設定為您的公開 HTTPS 網域**
```powershell
flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute
```
如果您使用自訂網域，請替換為對應的網域（例如 `https://omniroute.yourdomain.com`）。
2. **在提供商控制台中配置回呼 URL**
所有 OAuth 提供商共用單一回呼路徑 `/callback` — 沒有每個提供商的獨立回呼路由：
```text
<NEXT_PUBLIC_BASE_URL>/callback
```
例如，不論是 Gemini、Antigravity、Cursor 或 GitLab Duo：
- `https://omniroute.fly.dev/callback`
如果 `NEXT_PUBLIC_BASE_URL` 與註冊在提供商的回呼 URL 不符，OAuth 流程將在瀏覽器重新導向步驟失敗。
---
## 7. 一鍵設置參數
## 7. 單一命令密鑰設定
下面命令會生成安全隨機值，並把當前項目需要的參數一次性寫入 Fly Secrets。
以下命令會產生安全隨機值，並一步將目前專案的所有必要參數寫入 Fly Secrets。
說明：
注意事項：
- 不包含 `INITIAL_PASSWORD`
- 適用於當前項目 `omniroute`
- 適用於目前專案 `omniroute`
```powershell
$apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$wsBridgeSecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
flyctl secrets set `
API_KEY_SECRET=$apiKeySecret `
JWT_SECRET=$jwtSecret `
MACHINE_ID_SALT=$machineIdSalt `
STORAGE_ENCRYPTION_KEY=$storageKey `
OMNIROUTE_WS_BRIDGE_SECRET=$wsBridgeSecret `
DATA_DIR=/data `
NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
-a omniroute
```
如果你還要加初始密碼：
在 Linux / macOS 上，也可以使用 `openssl rand -hex 32`：
```bash
flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute
```
注意事項：
- `OMNIROUTE_WS_BRIDGE_SECRET` 在生產環境中為必填；缺少此項將導致 WebSocket 橋接通話失敗
如果您也想設定初始密碼：
```powershell
flyctl secrets set INITIAL_PASSWORD=你的強密碼 -a omniroute
flyctl secrets set INITIAL_PASSWORD=your-strong-password -a omniroute
```
---
## 8. 查看當前參數
## 8. 檢視目前參數
```powershell
flyctl secrets list -a omniroute
```
如果控制臺 `Secrets` 頁面沒有顯示你期待的變量，先檢查：
如果控制台中的「Secrets」頁面未顯示預期的變數，請檢查：
- 看的應用是不是 `omniroute`
- `fly.toml` 的 `app` 是否和控制臺應用一致
- 您正在檢視的是 `omniroute` 應用程式
- `fly.toml` 中的 `app` 值與控制台中的應用程式相符
---
## 9. 後續更新發布
## 9. 後續更新與發布
代碼有更新後，發布步驟很簡單：
程式碼更新後，發布流程很簡單：
```powershell
git pull
flyctl deploy
```
如果只更新參數，不改代碼：
如果您只需要更新參數而不變更程式碼：
```powershell
flyctl secrets set KEY=value -a omniroute
```
Fly 會自動滾動更新機器。
Fly 會自動執行機器的滾動更新。
### 9.1 跟蹤原倉庫更新並保留 fork 的 `fly.toml`
### 9.1 追蹤上游儲存庫更新同時保留 Fork 的 `fly.toml`
如果當前倉庫是 fork，並且你要同步上遊 `https://github.com/diegosouzapw/OmniRoute` 的更新，推薦按下面流程執行。
如果目前儲存庫是 fork，且您想同步上游 `https://github.com/diegosouzapw/OmniRoute` 的更新，請遵循以下工作流程。
先確認遠程：
首先，確認您的遠端倉庫：
```powershell
git remote -v
```
應至少包含：
您應該會看到：
- `origin` 指向你自己的 fork
- `upstream` 指向原倉庫
- `origin` 指向您自己的 fork
- `upstream` 指向原始儲存庫
如果沒有 `upstream`，先添加：
如果未配置 `upstream`，請新增：
```powershell
git remote add upstream https://github.com/diegosouzapw/OmniRoute.git
```
同步上遊前，先抓取最新提交和標籤：
在與上游同步之前，請先擷取最新的提交和標籤：
```powershell
git fetch upstream --tags
```
查看當前版本和上遊標籤：
檢查目前版本和上游標籤：
```powershell
git describe --tags --always
git show --no-patch --oneline v3.4.7
```
如果你想合併上遊最新 `main`，並強制保留 fork 當前的 `fly.toml`，可按下面流程執行：
> 注意：目前專案版本為 `v3.8.0`。以下 `v3.4.7` 的引用僅作為歷史範例保留。實際發布時，請使用 `:latest` 或目前版本標籤（例如 `:v3.8.0`）。
如果您想合併最新的上游 `main`，同時強制保留您 fork 的 `fly.toml`，請遵循以下工作流程：
```powershell
git merge upstream/main
@@ -296,52 +341,52 @@ git commit -m "chore(deploy): keep fork fly.toml"
git push origin main
```
說明：
注意事項：
- `git merge upstream/main` 用於同步原倉庫最新代碼
- `git checkout HEAD~1 -- fly.toml` 用於恢復合併前你 fork 自己的 `fly.toml`
- 如果上遊沒有改 `fly.toml`，這一步不會帶來額外差異
- 如果上遊改了 `fly.toml`，這一步能確保 Fly 應用名、掛載卷、區域等 fork 自定義部署設定不被覆蓋
- `git merge upstream/main` 會同步原始儲存庫的最新程式碼
- `git checkout HEAD~1 -- fly.toml` 會從合併前還原您 fork 自己的 `fly.toml`
- 如果上游未修改 `fly.toml`，此步驟不會引入任何差異
- 如果上游修改了 `fly.toml`，此步驟可確保您的 Fly 應用程式名稱、磁碟區掛載、地區和其他 fork 特定的部署配置不會被覆寫
如果你明確只想對齊某個發布標籤，例如 `v3.4.7`，也可以先確認標籤是否已經包含在 `upstream/main`：
如果您想對齊特定的發布標籤（例如 `v3.4.7`），請先確認該標籤已包含在 `upstream/main` 中：
```powershell
git merge-base --is-ancestor v3.4.7 upstream/main
```
返回成功表示 `upstream/main` 已經包含該版本，直接合併 `upstream/main` 即可。
成功回傳表示 `upstream/main` 已包含該版本；您可以直接合併 `upstream/main`。
### 9.2 同步上遊後的標準發布順序
### 9.2 同步上游後的標準發布順序
同步原倉庫完成後，推薦按下面順序發布：
與原始儲存庫同步後，請遵循此建議的發布順序：
1. `git fetch upstream --tags`
2. `git merge upstream/main`
3. 恢復 fork 的 `fly.toml`
3. 還原 fork 的 `fly.toml`
4. `git push origin main`
5. `flyctl deploy`
6. `flyctl status -a omniroute`
7. `flyctl logs --no-tail -a omniroute`
這就是當前項目升級到 `v3.4.7` 時使用的實際流程。
這是升級目前專案至 `v3.4.7` 時使用的實際工作流程（範例引用的是舊版本；目前實際版本為 `v3.8.0`）。
---
## 10. 發布後檢查
## 10. 部署後檢查
### 10.1 查看應用狀態
### 10.1 檢查應用程式狀態
```powershell
flyctl status -a omniroute
```
### 10.2 查看啟動日誌
### 10.2 檢視啟動日誌
```powershell
flyctl logs --no-tail -a omniroute
```
### 10.3 檢查網站可訪問
### 10.3 驗證網站可存取性
```powershell
try {
@@ -355,40 +400,40 @@ try {
}
```
返回 `200` 說明站點已正常響應。
回傳值為 `200` 表示網站正常回應。
---
## 11. 成功標誌
## 11. 成功指標
部署成功後，日誌裡應看到類似內容：
成功部署後，日誌應顯示類似以下內容：
```text
[bootstrap] Secrets persisted to: /data/server.env
[DB] SQLite database ready: /data/storage.sqlite
```
這兩個點很關鍵：
這兩點至關重要：
- `/data/server.env` 說明運行時密鑰落到了持久卷
- `/data/storage.sqlite` 說明資料庫寫入持久卷
- `/data/server.env` 確認執行時期密鑰已寫入持久化磁碟區
- `/data/storage.sqlite` 確認資料庫已寫入持久化磁碟區
如果你看到的是 `/app/data/...`，說明 `DATA_DIR` 沒配對，需要立即修正。
如果您看到 `/app/data/...`，表示 `DATA_DIR` 配置錯誤，必須立即修正。
---
## 12. 常見問題
### 12.1 `Secrets` 頁面是空的
### 12.1 「Secrets」頁面為空
通常有兩種原因：
通常有兩個原因：
- 你還沒執行 `flyctl secrets set`
- 你打開的是另一個應用，例如 `oroute`，不是 `omniroute`
- 您尚未執行 `flyctl secrets set`
- 您正在檢視不同的應用程式（例如 `oroute` 而非 `omniroute`）
### 12.2 `flyctl deploy` 報 `app not found`
### 12.2 `flyctl deploy` 回報 `app not found`
先創建應用：
請先建立應用程式：
```powershell
flyctl apps create omniroute
@@ -396,41 +441,41 @@ flyctl apps create omniroute
### 12.3 `fly.toml` 解析失敗
重點檢查：
請檢查以下項目：
- 注釋裡是否有亂碼字符
- TOML 引號和縮進是否正確
- 註解中是否有亂碼字元
- TOML 的引號和縮排是否正確
### 12.4 數據沒有持久化
### 12.4 資料未持久化
檢查以下兩點：
請同時驗證以下兩項：
- `fly.toml` 中是否存在 `destination = '/data'`
- `DATA_DIR` 是否設置為 `/data`
- `fly.toml` 包含 `destination = '/data'`
- `DATA_DIR` 設定為 `/data`
### 12.5 不設置 `INITIAL_PASSWORD` 是否能跑
### 12.5 沒有 `INITIAL_PASSWORD` 可以執行嗎？
可以運行，但會回退到默認 `CHANGEME`。生產環境建議儘快修改後臺密碼。
可以執行。它會回退到預設密碼 `CHANGEME`。建議在生產環境中盡快變更後端密碼。
---
## 13. 新項目復用建議
## 13. 新專案重複使用
如果以後是新項目照著這份文檔部署，最少改這幾項：
如果您要依照本文件部署新專案，只需變更以下項目：
1. 修改 `fly.toml` 裡的 `app`
2. 修改 `NEXT_PUBLIC_BASE_URL`
3. 保持 `DATA_DIR=/data`
4. 重新生成 `API_KEY_SECRET`、`JWT_SECRET`、`MACHINE_ID_SALT`、`STORAGE_ENCRYPTION_KEY`
5. 首次部署後檢查日誌是否寫入 `/data`
1. 變更 `fly.toml` 中的 `app` 值
2. 變更 `NEXT_PUBLIC_BASE_URL`
3. 保留 `DATA_DIR=/data`
4. 重新產生 `API_KEY_SECRET`、`JWT_SECRET`、`MACHINE_ID_SALT` 和 `STORAGE_ENCRYPTION_KEY`
5. 首次部署後，驗證日誌是否寫入 `/data`
不要直接復用舊項目的密鑰。
請勿重複使用先前專案的密鑰。
---
## 14. 當前項目的最小發布清單
## 14. 目前專案的極簡發布檢查清單
當前項目後續最常用的命令如下：
後續發布最常用的命令：
```powershell
flyctl auth whoami
@@ -440,13 +485,13 @@ flyctl deploy
flyctl logs --no-tail -a omniroute
```
如果只是正常發版，核心就是：
對於一般發布，核心命令很簡單：
```powershell
flyctl deploy
```
如果是新環境首次部署，核心就是：
對於新環境的首次部署，核心步驟為：
1. `flyctl auth login`
2. `flyctl apps create omniroute`

387
docs/i18n/zh-TW/docs/ops/RELEASE_CHECKLIST.md
View File

@@ -1,44 +1,373 @@
# Release Checklist (中文 (簡體))
---
title: "發行檢查清單"
version: 3.8.40
lastUpdated: 2026-06-28
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/RELEASE_CHECKLIST.md) · 🇸🇦 [ar](../../ar/docs/RELEASE_CHECKLIST.md) · 🇧🇬 [bg](../../bg/docs/RELEASE_CHECKLIST.md) · 🇧🇩 [bn](../../bn/docs/RELEASE_CHECKLIST.md) · 🇨🇿 [cs](../../cs/docs/RELEASE_CHECKLIST.md) · 🇩🇰 [da](../../da/docs/RELEASE_CHECKLIST.md) · 🇩🇪 [de](../../de/docs/RELEASE_CHECKLIST.md) · 🇪🇸 [es](../../es/docs/RELEASE_CHECKLIST.md) · 🇮🇷 [fa](../../fa/docs/RELEASE_CHECKLIST.md) · 🇫🇮 [fi](../../fi/docs/RELEASE_CHECKLIST.md) · 🇫🇷 [fr](../../fr/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [gu](../../gu/docs/RELEASE_CHECKLIST.md) · 🇮🇱 [he](../../he/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [hi](../../hi/docs/RELEASE_CHECKLIST.md) · 🇭🇺 [hu](../../hu/docs/RELEASE_CHECKLIST.md) · 🇮🇩 [id](../../id/docs/RELEASE_CHECKLIST.md) · 🇮🇹 [it](../../it/docs/RELEASE_CHECKLIST.md) · 🇯🇵 [ja](../../ja/docs/RELEASE_CHECKLIST.md) · 🇰🇷 [ko](../../ko/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [mr](../../mr/docs/RELEASE_CHECKLIST.md) · 🇲🇾 [ms](../../ms/docs/RELEASE_CHECKLIST.md) · 🇳🇱 [nl](../../nl/docs/RELEASE_CHECKLIST.md) · 🇳🇴 [no](../../no/docs/RELEASE_CHECKLIST.md) · 🇵🇭 [phi](../../phi/docs/RELEASE_CHECKLIST.md) · 🇵🇱 [pl](../../pl/docs/RELEASE_CHECKLIST.md) · 🇵🇹 [pt](../../pt/docs/RELEASE_CHECKLIST.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) · 🇷🇴 [ro](../../ro/docs/RELEASE_CHECKLIST.md) · 🇷🇺 [ru](../../ru/docs/RELEASE_CHECKLIST.md) · 🇸🇰 [sk](../../sk/docs/RELEASE_CHECKLIST.md) · 🇸🇪 [sv](../../sv/docs/RELEASE_CHECKLIST.md) · 🇰🇪 [sw](../../sw/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [ta](../../ta/docs/RELEASE_CHECKLIST.md) · 🇮🇳 [te](../../te/docs/RELEASE_CHECKLIST.md) · 🇹🇭 [th](../../th/docs/RELEASE_CHECKLIST.md) · 🇹🇷 [tr](../../tr/docs/RELEASE_CHECKLIST.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) · 🇵🇰 [ur](../../ur/docs/RELEASE_CHECKLIST.md) · 🇻🇳 [vi](../../vi/docs/RELEASE_CHECKLIST.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md)
# 發行檢查清單
> **最後更新：** 2026-06-28 — v3.8.40
> 精簡化發行流程，運用 Claude Code Skills 實現自動化。
>
> **在發行之間保持佇列／分支為綠色：** 請參閱 [RELEASE_GREEN.md](./RELEASE_GREEN.md)
>（`/green-prs` 系列指令 + `npm run check:release-green` + `/babysit` + 夜間排程）。定期執行此流程——
> 尤其是在執行本檢查清單**之前**——可讓發行 PR 一開始就處於綠色狀態。
## TL;DR
```bash
# 1. 更新版本號 + 產生 CHANGELOG（skill）
/version-bump-cc patch # 或 minor / major
# 2. 在本機執行品質門檻檢查
npm run check # lint + 測試
npm run test:coverage # 完整覆蓋率門檻（60/60/60/60）
# 3. 建置與冒煙測試
npm run build
npm run test:e2e # 選擇性但建議執行
# 4. 產生存放版（skill）
/generate-release-cc
# 5. 部署（skill）
/deploy-vps-both-cc # 或 akamai-cc / local-cc
# 6. 擷取發行佐證（skill）
/capture-release-evidences-cc
```
## npm 階段式發布（自 v3.8.49 起預設 — WS1.3/D2）
npm 發布工作流程不再直接發布：它會啟動打包後的 tarball
（`check:pack-boot`），然後執行 `npm stage publish`——確切的位元組會暫存在
登錄檔中，在擁有者核准前**不可安裝**。人類 2FA 關卡移至
驗證**之後**，而非之前。
**工作流程轉為綠色後的擁有者流程：**
1. `npm stage list omniroute` — 找到 stage id（也會列印在工作流程摘要中）。
2. 驗證暫存位元組（建議執行）：`npm stage download <id>`，然後將下載的 tarball
安裝到臨時字首目錄並啟動它（`npm run check:pack-boot` 會在 CI 中自動執行
相同的 pack→install→boot 驗證流程）。
3. `npm stage approve <id>` — 2FA 提示即為發布操作。`npm stage reject <id>` 則會捨棄。
4. 發布後網路檢查：發布後驗證器（v3.8.49 方案的 WS1.4）會從公開登錄檔安裝
已發布版本到一個乾淨的容器中並啟動它。
**緊急備援：** 使用 `workflow_dispatch` 搭配 `publish_mode=direct` 可恢復
傳統的立即 `npm publish`（僅在階段式發布本身出問題時使用；請記錄原因）。
**一次性強化措施（擁有者，npmjs.com）：**為 `omniroute` 設定僅限階段式發布的
Trusted Publisher，這樣即使長期權杖外洩，也無法從任何地方直接 `npm publish`——
CI 只能暫存；只有擁有者的 2FA 才能真正發布。
**成品損壞應對手冊（未變更）：** `npm deprecate omniroute@<bad> "<reason> — use <fixed>"`
為預設反射動作（幾分鐘內完成，可逆轉）；`npm unpublish` 僅在 72 小時／無依賴套件
的時間窗口內使用，且絕不作為第一步。Docker：絕不重寫版本標籤——回滾是將
`latest` 重新指向最後一個正常的摘要。
## Hotfix 快速通道（標籤 `hotfix`）
標記為 `hotfix` 的 PR 會跳過繁重的 CI 矩陣（9 分片 E2E、覆蓋率棘輪、
品質門檻、品質延伸檢查），僅保留快速且高訊號的關卡：建置、
單元測試分片、整合測試、vitest、lint／型別檢查、docs-sync、`check:pack-artifact`
以及 tarball 啟動冒煙測試（`check:pack-boot`）。目標：在 ≤15 分鐘內變為綠色，而非 ~33 分鐘。
**進入條件——必須全部符合（以 Chromium／VS Code／Node 緊急通道為藍本）：**
1. **嚴重性**：正式環境已中斷——已發布的成品啟動時崩潰／安全性修正／該版本的所有使用者都受影響。「重要」不等於「已中斷」。
2. **授權**：只有倉儲擁有者可以套用 `hotfix` 標籤。此標籤即為核准——專案 PR 不得自行使用。
3. **佐證**：PR 主體需連結先前完整通過的繁重執行結果（被跳過的工作本來會重新驗證的套件），以及修正本身從失敗到通過的測試記錄。
4. **範圍**：僅限 cherry-pick——最小修正，不得重構，不得夾帶其他變更。
被跳過的覆蓋率／棘輪檢查範圍將由發行分支上的下一個完整執行重新驗證（持續 release-green）——快速通道是跳過**等待**，而非跳過**驗證**。
僅限測試的 diff（所有檔案都在 `tests/` 下，且不在 `tests/e2e/` 下）會自動跳過 E2E
矩陣，無需任何標籤。
## 詳細檢查清單
### 發行前
- [ ] 所有目標為此版本的 PR 都已合併到 `release/vX.Y.0`
- [ ] 所有與此版本相關的 Linear／問題項目都已關閉或推遲至下個里程碑
- [ ] CI 在 `release/vX.Y.0` 分支上為綠色
- [ ] 程式碼中沒有 `TODO(release)` 標記：`grep -r "TODO(release)" src/ open-sse/`
- [ ] Docker 基礎映像為最新版本（目前為 `node:24.15.0-trixie-slim`）
### 版本號與變更日誌
- [ ] 執行 `/version-bump-cc <patch|minor|major>`（Claude Code skill）
- 更新 `package.json`、`electron/package.json`
- 從上次標籤以來的 git 提交重新產生 `CHANGELOG.md`
- 更新 README.md 徽章
- [ ] 手動檢視 CHANGELOG.md，必要時清理提交訊息
- [ ] 確認 `CHANGELOG.md` 中最新的 semver 區段與 `package.json` 版本一致
- [ ] 保留 `## [Unreleased]` 作為變更日誌的第一個區段，供後續工作使用
- [ ] 更新 `docs/openapi.yaml` → `info.version` 必須等於 `package.json` 版本
### 程式碼品質
- [ ] `npm run lint` — 0 個錯誤（警告為預先存在的）
- [ ] `npm run typecheck:core` — 乾淨通過
- [ ] `npm run typecheck:noimplicit:core` — 乾淨通過（嚴格模式）
- [ ] `npm run check:cycles` — 沒有循環依賴
- [ ] `npm run check:any-budget:t11` — 在預算內
- [ ] `npm run check:route-validation:t06` — 乾淨通過
- [ ] `npm run check:node-runtime` — 符合支援的執行時期最低版本（`>=22.22.2 <23`、`>=24.0.0 <27`，詳見 `src/shared/utils/nodeRuntimeSupport.ts` 中的 `SUPPORTED_NODE_RANGE`；需與 `package.json` 的 `engines` 一致）
### 測試
- [ ] `npm run test:unit` — 通過
- [ ] `npm run test:vitest` — 通過（MCP 伺服器、autoCombo、快取）
- [ ] `npm run test:coverage` — 門檻 60/60/60/60 已達成（statements／lines／functions／branches）
- [ ] `npm run test:integration` — 通過（若變更涉及 DB／處理器）
- [ ] `npm run test:combo:matrix` — 通過（combo 策略矩陣：證明所有 17 種路由策略的選擇決策是確定性的；在更動 combo 路由、策略解析或備援邏輯時執行）
- [ ] `RUN_COMBO_LIVE=1 npm run test:combo:live` — **選擇性／手動**（受閘控的真實上游冒煙測試；從 VPS `root@192.168.0.15` 讀取唯讀 DB 快照；會命中真實提供者，消耗額度；不在 CI 中執行；若無閘控變數則乾淨跳過）
- [ ] `npm run test:combo:live:vps` — **選擇性／手動**（Phase-3 VPS 即時冒煙測試：透過純 Node ESM 對 `.15` 伺服器執行 7 個 HTTP 情境；需要 `ssh root@192.168.0.15`；只會建立／刪除 `__live_test__*` 類型的 combo；會命中真實提供者；不在 CI 中執行）
- [ ] `npm run test:e2e` — 通過（UI 變更）
- [ ] `npm run test:protocols:e2e` — 通過（MCP／A2A 變更）
- [ ] `npm run test:ecosystem` — 通過
### Hooks（Husky 驗證）
Husky hooks 位於 `.husky/` 目錄，會在 git 操作時自動執行。
- **pre-commit：** `npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11`
- **pre-push：** 快速確定性關卡 — `npm run check:any-budget:t11 && npm run check:tracked-artifacts`（於 2026-06-13 啟用）。故意排除 `test:unit`（速度慢；由 CI 的 `test-unit` 工作負責）。
- 在推送發行分支前，請手動執行 `npm run test:unit`。
若 hook 失敗：請修正根本問題，不要使用 `--no-verify` 繞過。
### Conventional Commits
所有與發行相關的提交都必須遵循 `type(scope): subject` 格式。
**有效類型：** `feat`、`fix`、`refactor`、`docs`、`test`、`chore`、`perf`、`style`、`ci`
**有效範圍：** `db`、`sse`、`oauth`、`dashboard`、`api`、`cli`、`docker`、`ci`、`mcp`、`a2a`、`memory`、`skills`、`cloud-agent`、`guardrails`、`compression`、`auto-combo`、`resilience`、`providers`、`executors`、`translator`、`domain`、`authz`
重大變更：在結尾加上 `BREAKING CHANGE:` 或在範圍後加上 `!`（例如 `feat(api)!: drop /v0`）。
### 文件
- [ ] `npm run check:docs-sync` 通過（pre-commit 會自動執行）
- [ ] `npm run check:docs-all` 通過（總括：docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links）
- [ ] `npm run check:env-doc-sync` 退出碼為 0——程式碼 ↔ `.env.example` ↔ `docs/reference/ENVIRONMENT.md` 的環境變數合約完整無缺
- [ ] `npm run check:doc-links` 退出碼為 0——重構後沒有損毀的內部 markdown 參照
- [ ] 已檢視 `docs/architecture/ARCHITECTURE.md`，確認無儲存／執行時期偏差
- [ ] 已檢視 `docs/guides/TROUBLESHOOTING.md`，確認無環境變數與操作偏差
- [ ] 若 `.env.example` 有變更：已更新 `docs/reference/ENVIRONMENT.md`
- [ ] 若新功能有 UI：`docs/guides/USER_GUIDE.md` 中有提及
- [ ] 若新功能有 API：已更新 `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml`
- [ ] 若新功能為模組：存在專屬的 `docs/<MODULE>.md`
- [ ] 若有重大變更：`docs/guides/TROUBLESHOOTING.md` 中有遷移說明
### i18n
- [ ] `npm run i18n:check` 退出碼為 0——翻譯狀態（`.i18n-state.json`）與來源文件同步（嚴格模式下無偏差來源；警告模式對最後一刻的文件修飾可接受，但應在打標籤前歸零）
- [ ] `npm run i18n:check-ui-coverage` 退出碼為 0——每個 UI 語系都達到或超過 80% 的覆蓋率門檻
- [ ] `npm run i18n:sync-ui:dry` 回報 0 個缺失鍵，遍及全部 42 個語系
- [ ] 若英文來源文件有變更，請在打標籤前執行 `npm run i18n:run`（需要在 `.env` 中有 `OMNIROUTE_TRANSLATION_API_KEY`）
- [ ] 若翻譯貢獻不大，可延遲至下一版本（在 CHANGELOG 中追蹤）
### 資料庫遷移
- [ ] 若 `src/lib/db/migrations/` 中有新檔案：
- [ ] 每個遷移都是等冪的（`CREATE TABLE IF NOT EXISTS` 等）
- [ ] 遷移包含在交易中
- [ ] 編號正確（序列中無間隙）
- [ ] 在全新安裝上測試：刪除 `~/.omniroute/omniroute.db` 並執行 `npm run dev`
- [ ] 在既有安裝上測試：備份資料庫、執行遷移、驗證結構
- [ ] 若遷移會改寫表格，需正確處理 WAL 檔案（`-wal`、`-shm`）
### 提供者目錄（Zod 驗證）
- [ ] `src/shared/constants/providers.ts` 的 Zod 結構在載入時有效
- [ ] 所有提供者都有必要欄位（`id`、`label`、`kind` 等）
- [ ] 新的免費提供者已提供 `freeNote`
- [ ] OAuth 提供者已在 `src/lib/oauth/constants/oauth.ts` 中註冊 `oauthConfig`
- [ ] 若新增提供者：`open-sse/executors/` 中有對應的執行器
- [ ] 若非 OpenAI 格式：`open-sse/translator/` 中有轉譯器
- [ ] 模型已在 `open-sse/config/providerRegistry.ts` 中註冊
- [ ] `tests/unit/` 中的單元測試涵蓋提供者分類與路由
### 桌面版（Electron）
若 `electron/` 有變更：
- [ ] `npm run electron:smoke:packaged` 通過
- [ ] 至少在 `:win`、`:mac`、`:linux` 其中之一測試過建置
- [ ] 程式碼簽署憑證未過期（若有簽署）
- [ ] `electron/package.json` 版本與根目錄 `package.json` 一致
- [ ] 若發布至 `stable` 頻道，已更新自動更新頻道指標
### 建置目錄結構
倉儲使用三個不同的輸出目錄——切勿混淆：
| 目錄 | 用途 | 是否追蹤？ |
| --------- | --------------------------------------------------- | ------------- |
| `src/` | 應用程式原始碼（TypeScript／TSX） | 是 |
| `.build/` | 建置中間產物 — `next build` 輸出（`distDir`） | 否（gitignored）|
| `dist/` | 可發行的 npm 套件 — 由 `assembleStandalone` 組合而成 | 否（gitignored）|
> **操作注意：** 遠端 VPS 映像目錄仍為 `/usr/lib/node_modules/omniroute/app/`。
> 只有**倉儲內**的建置輸出目錄變更了（`app/` → `dist/`）。部署 skills 會將
> `dist/` 內容 rsync 到遠端的 `app/` 目錄——無需變更 VPS 路徑。
**單一建置流程：**
```
npm run build:release
└─ rm -rf .build dist （清理）
└─ next build → .build/next/ （中間產物）
└─ assembleStandalone （複製 standalone + static + public + natives → dist/）
└─ 寫入 dist/BUILD_SHA （HEAD 標記）
```
請勿為了部署而先執行 `npm run build` 再執行 `npm run build:cli`——
請使用 `npm run build:release`，它會在單一命令中完成乾淨重建 + 標記。
### 成品驗證
- [ ] `npm run build:release` 成功且 `dist/BUILD_SHA` == `git rev-parse --short HEAD`
- [ ] `npm run check:pack-artifact` 乾淨通過——無 `app.__qa_backup`、`scripts/scratch`、`package-lock.json` 或其他本地殘留檔案
- [ ] 建置後存在 `dist/server.js`
### 標籤與發行
- [ ] 執行 `/generate-release-cc`（Claude Code skill）：
- 建立標籤 `vX.Y.Z`
- 推送標籤與分支
- 以變更日誌內容開啟 GitHub Release
- 附加 Electron 安裝程式（若有建置）
- [ ] 或手動操作：
```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --notes-from-tag
```
### 部署
部署 skills 使用輕量 rsync 流程——無需 `npm pack`，無需 `npm i -g`：
- [ ] 使用符合目標的部署 skill：
- `/deploy-vps-local-cc` — 本地 VPS（192.168.0.15）
- `/deploy-vps-akamai-cc` — Akamai VPS（69.164.221.35）
- `/deploy-vps-both-cc` — 兩者同時
- [ ] 部署前，確認 `dist/BUILD_SHA` == `git rev-parse --short HEAD`
- [ ] 建置必須在 `node_modules` 是真實目錄的環境中執行（主檢出目錄或已執行 `npm ci` 的工作目錄——**不是符號連結的工作目錄**）
- [ ] 冒煙測試已部署的實例：
- 開啟 `/dashboard/health` → 檢查版本字串與發行版本一致
- 對已知提供者發送 `/v1/chat/completions` 請求
- 確認 `/api/monitoring/health` 回傳 `CLOSED` 的斷路器狀態
- 確認 MCP 傳輸協定正常回應（`/mcp` HTTP、`/mcp-sse` SSE）
### 發行後
- [ ] 執行 `/capture-release-evidences-cc`（Claude Code skill）
- 擷取新功能的 WebP 螢幕截圖／錄影
- 附加到版本說明／部落格文章
- [ ] 在 GitHub Discussions／Discord 上發布發行公告
- [ ] 開啟下一版本的里程碑
- [ ] 若為重大更新：置頂討論或在 `news.json` 中新增應用程式內橫幅
## 內嵌服務冒煙測試（v3.8.4+）
在發布任何包含內嵌服務變更的版本前，請確認：
### 全新資料庫啟動（可發現遷移衝突——於 v3.8.4 hotfix 後新增）
- [ ] `DATA_DIR=$(mktemp -d) npm start &` — 等待 10 秒啟動
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` 回傳 `"9router"`（不是 404，不是 500）。確認遷移 `071_services.sql` 已套用且已寫入種子資料列。
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at"` 回傳 3 列。
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted"` 回傳 2 列（驗證 `070_webhooks_kind_metadata.sql` 已套用）。
- [ ] `node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts` 通過——防止未來的衝突。
### 9Router
- [ ] `POST /api/services/9router/install` 在 2 分鐘內回傳 200 並包含 `installedVersion`
- [ ] `POST /api/services/9router/start` 在 30 秒內回傳 200 且 `state: "running"`
- [ ] `GET /api/services/9router/status` 回報 `health: "healthy"`
- [ ] `POST /v1/chat/completions` 搭配 `"model": "9router/auto/..."` 回傳 200（端到端透過 9Router 路由）
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` 在代理程式內渲染 9Router 原生 UI（非直接 `127.0.0.1:port` iframe）
- [ ] `POST /api/services/9router/rotate-key` 回傳 `{ keyRotated: true }` 且服務正常重啟
- [ ] `POST /api/services/9router/stop` 回傳 200 且 `state: "stopped"`
- [ ] `GET /api/services/9router/logs?tail=50` 回傳 SSE 串流，包含 `snapshot` 事件與最近的行
- [ ] 在 PATH 中沒有 `npm` 的環境中安裝，回傳 500 並顯示友善（非堆疊追蹤）的錯誤訊息
### CLIProxyAPI
- [ ] `POST /api/services/cliproxy/install` 在 2 分鐘內回傳 200
- [ ] `POST /api/services/cliproxy/start` 在 30 秒內回傳 200 且 `state: "running"`
- [ ] `GET /api/services/cliproxy/status` 回報 `health: "healthy"`
- [ ] `POST /api/services/cliproxy/stop` 回傳 200 且 `state: "stopped"`
- [ ] `GET /api/services/cliproxy/logs?tail=50` 回傳 SSE 串流
### 安全性迴歸測試
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start` 回傳 `403 LOCAL_ONLY`
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start` 回傳 `403 LOCAL_ONLY`
- [ ] `/api/services/*` 的錯誤回應不包含 `err.stack` 或絕對路徑
## v3.8.0+ 檢查項目
在發布任何 v3.8.x 版本前，請確認以下額外項目：
- [ ] `omniroute --tray` 在 macOS 上啟動（systray2 已安裝到 `~/.omniroute/runtime/`）
- [ ] `omniroute --tray` 在 Linux 上啟動（需要 DISPLAY；若未設定則優雅報錯）
- [ ] `omniroute --tray` 在 Windows 上啟動（PowerShell NotifyIcon，無需額外二進位檔）
- [ ] `omniroute config tray enable` 建立開機自啟項目；disable 則移除
- [ ] `npm install -g omniroute@<此版本>` 執行 postinstall 而不會致命退出
- [ ] 更新路徑保留選擇性依賴：`omniroute update --apply` 和自動更新器
執行 `npm install -g … --include=optional`，因此 `optionalDependencies`（better-sqlite3、
keytar、tls-client，以及 llmlingua SLM 堆疊：`@atjsh/llmlingua-2`、
`@huggingface/transformers@3.5.2`、`@tensorflow/tfjs`、`js-tiktoken`）在更新後仍會保留。
`@huggingface/transformers` 維持選擇性，因此其 `onnxruntime-node` CUDA 提供者的 postinstall
不會在 CUDA 11 主機上中斷安裝。Ultra `modelPath` SLM 層還需要
tinybert 模型，會在首次使用時自動下載到 `${DATA_DIR}/models/llmlingua`。Postinstall
（`scripts/build/colocateOptionals.mjs`）接著將 SLM 選擇性閉包複製到
`dist/node_modules`，使工作者解析到**單一** `@huggingface/transformers` 3.5.2
選擇性實例——獨立追蹤僅捆綁 transformers，而非動態匯入的
選擇性套件，因此若無此步驟，工作者會載入 llmlingua-2 並使用根目錄的 transformers，
導致 SLM 層靜默地失敗但仍保持運作。
- [ ] `omniroute status` 在無 `.env` 的情況下正常運作（僅限 CLI 權杖路徑，迴環介面）
- [ ] `curl http://localhost:20128/api/shutdown` 回傳 401（始終受保護的路由）
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` 回傳 401（迴環保護）
- [ ] SQLite 執行時期在首次執行時解析為 `bundled`（捆綁的二進位檔對平台有效）
- [ ] 當 `node_modules/better-sqlite3` 被刪除時，SQLite 執行時期備援至 `runtime`
- [ ] Smart MCP 過濾器壓縮真實的 `playwright-mcp browser_snapshot` 輸出（≥50% 縮減）
- [ ] 所有 10 個 `skills/omniroute*/SKILL.md` 檔案均可透過原始 GitHub URL 公開獲取
- [ ] 入門精靈在新安裝時顯示「運作方式」分層導覽步驟
- [ ] 首頁儀表板的分層覆蓋率小工具顯示已設定／啟用中的計數
---
Use this checklist before tagging or publishing a new OmniRoute release.
## 回滾
## Version and Changelog
若發行版本有重大問題：
1. Bump `package.json` version (`x.y.z`) in the release branch.
2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section:
- `## [x.y.z] — YYYY-MM-DD`
3. Keep `## [Unreleased]` as the first changelog section for upcoming work.
4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version.
1. `gh release edit vX.Y.Z --prerelease`（標記為非最新）
2. `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z`（僅在使用者尚未採用時）
3. 或者：在 `release/vX.Y.0` 上進行 hotfix → 修補版本 `vX.Y.(Z+1)`
4. 立即在 GitHub Discussions 和 Discord 中溝通
## API Docs
## 嚴格規則
1. Update `docs/reference/openapi.yaml`:
- `info.version` must equal `package.json` version.
2. Validate endpoint examples if API contracts changed.
- 絕不直接提交到 `main`
- 絕不對 `main` 或 `release/*` 分支使用 `git push --force`
- 絕不跳過 Husky hooks（`--no-verify`）
- 絕不提交機密、憑證或 `.env` 檔案
- 覆蓋率必須維持 ≥60/60/60/60（statements／lines／functions／branches）
- 在變更 `src/`、`open-sse/`、`electron/` 或 `bin/` 中的正式程式碼時，務必包含或更新測試
## Runtime Docs
## 自動化同步檢查
1. Review `docs/architecture/ARCHITECTURE.md` for storage/runtime drift.
2. Review `docs/guides/TROUBLESHOOTING.md` for env var and operational drift.
3. Verify the release/runtime Node.js version still satisfies the supported secure floor:
- `>=20.20.2 <21` or `>=22.22.2 <23`
- `npm run check:node-runtime`
4. Validate the npm publish artifact after building the standalone package:
- `npm run build:cli`
- `npm run check:pack-artifact`
- confirm no `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, or other local residue
5. Update localized docs if source docs changed significantly.
## Automated Check
Run the sync guard locally before opening PR:
在開啟 PR 前在本機執行文件同步檢查：
```bash
npm run check:docs-sync
```
CI also runs this check in `.github/workflows/ci.yml` (lint job).
CI 也會在 `.github/workflows/ci.yml`（lint 工作）中執行此檢查。

255
docs/i18n/zh-TW/docs/ops/VM_DEPLOYMENT_GUIDE.md
View File

@@ -1,130 +1,138 @@
# OmniRoute — Deployment Guide on VM with Cloudflare (中文 (簡體))
---
title: "OmniRoute — VM 部署指南（搭配 Cloudflare）"
version: 3.8.40
lastUpdated: 2026-06-28
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../bn/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) · 🇪🇸 [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../fa/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../gu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../hi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../mr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../sw/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../ta/docs/VM_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../te/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../tr/docs/VM_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../ur/docs/VM_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md)
# OmniRoute — VM 部署指南（搭配 Cloudflare）
🌐 **語言:** 🇺🇸 [English](./VM_DEPLOYMENT_GUIDE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇪🇸 [Español](../i18n/es/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇷 [Français](../i18n/fr/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇹 [Italiano](../i18n/it/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇺 [Русский](../i18n/ru/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇳 [हिन्दी](../i18n/in/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇭 [ไทย](../i18n/th/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇦 [العربية](../i18n/ar/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇯🇵 [日本語](../i18n/ja/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇧🇬 [Български](../i18n/bg/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇩🇰 [Dansk](../i18n/da/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇱 [עברית](../i18n/he/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇰🇷 [한국어](../i18n/ko/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇳🇴 [Norsk](../i18n/no/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇷🇴 [Română](../i18n/ro/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇱 [Polski](../i18n/pl/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/ops/VM_DEPLOYMENT_GUIDE.md) | 🇹🇼 [繁體中文](./VM_DEPLOYMENT_GUIDE.md)
在 VM（VPS）上安裝並設定 OmniRoute 的完整指南，搭配經由 Cloudflare 管理的網域。
---
Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare.
## 前置需求
| 項目 | 最低規格 | 建議規格 |
| ----------- | -------------------------- | ------------------ |
| **CPU** | 1 vCPU | 2 vCPU |
| **RAM** | 1 GB | 2 GB |
| **硬碟** | 10 GB SSD | 25 GB SSD |
| **作業系統**| Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
| **網域** | 在 Cloudflare 註冊 | — |
| **Docker** | Docker Engine 24+ | Docker 27+ |
**經測試的提供商**: Akamai (Linode)、DigitalOcean、Vultr、Hetzner、AWS Lightsail。
---
## Prerequisites
## 1. 設定 VM
| Item | Minimum | Recommended |
| ---------- | ------------------------ | ---------------- |
| **CPU** | 1 vCPU | 2 vCPU |
| **RAM** | 1 GB | 2 GB |
| **Disk** | 10 GB SSD | 25 GB SSD |
| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
| **Domain** | Registered on Cloudflare | — |
| **Docker** | Docker Engine 24+ | Docker 27+ |
### 1.1 建立執行個體
**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
在你偏好的 VPS 提供商：
---
- 選擇 Ubuntu 24.04 LTS
- 選擇最低方案（1 vCPU / 1 GB RAM）
- 設定強效 root 密碼或配置 SSH 金鑰
- 記下**公開 IP**（例如 `203.0.113.10`）
## 1. Configure the VM
### 1.1 Create the instance
On your preferred VPS provider:
- Choose Ubuntu 24.04 LTS
- Select the minimum plan (1 vCPU / 1 GB RAM)
- Set a strong root password or configure SSH key
- Note the **public IP** (e.g., `203.0.113.10`)
### 1.2 Connect via SSH
### 1.2 透過 SSH 連線
```bash
ssh root@203.0.113.10
```
### 1.3 Update the system
### 1.3 更新系統
```bash
apt update && apt upgrade -y
```
### 1.4 Install Docker
### 1.4 安裝 Docker
```bash
# Install dependencies
# 安裝相依套件
apt install -y ca-certificates curl gnupg
# Add official Docker repository
# 加入官方 Docker 儲存庫
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo 「$VERSION_CODENAME」) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
```
### 1.5 Install nginx
### 1.5 安裝 nginx
```bash
apt install -y nginx
```
### 1.6 Configure Firewall (UFW)
### 1.6 設定防火牆 (UFW)
```bash
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp # SSH
ufw allow 80/tcp # HTTP (redirect)
ufw allow 80/tcp # HTTP（重新導向）
ufw allow 443/tcp # HTTPS
ufw enable
```
> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section.
> **提示**: 為達最高安全性，可將連接埠 80 和 443 限制為僅允許 Cloudflare IP。請參閱[進階安全](#advanced-security)一節。
---
## 2. Install OmniRoute
## 2. 安裝 OmniRoute
### 2.1 Create configuration directory
### 2.1 建立設定目錄
```bash
mkdir -p /opt/omniroute
```
### 2.2 Create environment variables file
### 2.2 建立環境變數檔
```bash
cat > /opt/omniroute/.env << 『EOF』
# === Security ===
cat > /opt/omniroute/.env << 'EOF'
# === 安全性 ===
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
INITIAL_PASSWORD=YourSecurePassword123!
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
STORAGE_ENCRYPTION_KEY_VERSION=v1
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
OMNIROUTE_WS_BRIDGE_SECRET=REPLACE-WITH-WS-BRIDGE-SECRET # 生產環境必填：Codex Responses WS bridge 使用
# === App ===
# === 應用程式 ===
PORT=20128
NODE_ENV=production
HOSTNAME=0.0.0.0
DATA_DIR=/app/data
STORAGE_DRIVER=sqlite
APP_LOG_TO_FILE=true
AUTH_COOKIE_SECURE=false
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=false
# === Domain (change to your domain) ===
BASE_URL=https://llms.seudominio.com
# === URLs（請改為你的網域）===
# 內部伺服器對伺服器的基礎 URL，用於排程任務／自我擷取
BASE_URL=http://127.0.0.1:20128
# 瀏覽器端使用的 URL，用於 OAuth 回呼、儀表板連結和產生的公開 URL
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
# 選擇性：產生的公開資源 URL 的明確公開來源覆寫
# OMNIROUTE_PUBLIC_BASE_URL=https://llms.seudominio.com
# === Cloud Sync (optional) ===
# === Cloud 同步（選擇性）===
# CLOUD_URL=https://cloud.omniroute.online
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
EOF
```
> ⚠️ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key.
> ⚠️ **重要**: 請產生唯一的密鑰！使用 `openssl rand -hex 32` 為每個密鑰產生隨機值。
### 2.3 Start the container
### 2.3 啟動容器
```bash
docker pull diegosouzapw/omniroute:latest
@@ -138,45 +146,45 @@ docker run -d \
diegosouzapw/omniroute:latest
```
### 2.4 Verify that it is running
### 2.4 確認運作中
```bash
docker ps | grep omniroute
docker logs omniroute --tail 20
```
It should display: `[DB] SQLite database ready` and `listening on port 20128`.
應顯示：`[DB] SQLite database ready` 和 `listening on port 20128`。
---
## 3. Configure nginx (Reverse Proxy)
## 3. 設定 nginx（反向代理）
### 3.1 Generate SSL certificate (Cloudflare Origin)
### 3.1 產生 SSL 憑證（Cloudflare Origin）
In the Cloudflare dashboard:
在 Cloudflare 儀表板中：
1. Go to **SSL/TLS → Origin Server**
2. Click **Create Certificate**
3. Keep the defaults (15 years, \*.yourdomain.com)
4. Copy the **Origin Certificate** and the **Private Key**
1. 前往 **SSL/TLS → Origin Server**
2. 點擊 **Create Certificate**
3. 保持預設值（15 年、\\*.yourdomain.com）
4. 複製 **Origin Certificate** 和 **Private Key**
```bash
mkdir -p /etc/nginx/ssl
# Paste the certificate
# 貼上憑證
nano /etc/nginx/ssl/origin.crt
# Paste the private key
# 貼上私鑰
nano /etc/nginx/ssl/origin.key
chmod 600 /etc/nginx/ssl/origin.key
```
### 3.2 Nginx Configuration
### 3.2 Nginx 設定
```bash
cat > /etc/nginx/sites-available/omniroute << 『NGINX』
# Default server — blocks direct access via IP
cat > /etc/nginx/sites-available/omniroute << 'NGINX'
# 預設伺服器 — 封鎖直接透過 IP 存取
server {
listen 80 default_server;
listen [::]:80 default_server;
@@ -192,7 +200,7 @@ server {
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name llms.yourdomain.com; # Change to your domain
server_name llms.yourdomain.com; # 改為你的網域
ssl_certificate /etc/nginx/ssl/origin.crt;
ssl_certificate_key /etc/nginx/ssl/origin.key;
@@ -203,16 +211,17 @@ server {
location / {
proxy_pass http://127.0.0.1:20128;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket support
# WebSocket 支援
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 「upgrade」;
proxy_set_header Connection "upgrade";
# SSE (Server-Sent Events) — streaming AI responses
# SSE（Server-Sent Events）— 串流 AI 回應
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 600s;
@@ -220,7 +229,7 @@ server {
}
}
# HTTP → HTTPS redirect
# HTTP → HTTPS 重新導向
server {
listen 80;
listen [::]:80;
@@ -230,59 +239,65 @@ server {
NGINX
```
Keep reverse-proxy stream timeouts aligned with your OmniRoute timeout env vars. If you raise
`FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS`, raise `proxy_read_timeout` / `proxy_send_timeout`
above the same threshold.
請確保反向代理串流超時時間與你的 OmniRoute 超時環境變數保持一致。如果你調高了
`FETCH_TIMEOUT_MS`／`STREAM_IDLE_TIMEOUT_MS`，請同步調高 `proxy_read_timeout`／`proxy_send_timeout`
至相同閾值以上。
### 3.3 Enable and Test
OmniRoute 使用 `NEXT_PUBLIC_BASE_URL` 作為 OAuth 回呼和產生公開連結的標準瀏覽器端來源。
已驗證的儀表板寫入操作使用同源請求加上綁定 session 的 CSRF 保護，因此不需要靜態公開基礎 URL。
上述的 `X-Forwarded-*` 標頭依然是實用的路由後設資料，但在 OAuth 或產生的瀏覽器連結需要公開 URL
時，它們不能取代明確設定公開 URL。僅在 OmniRoute 無法被用戶端直接存取且你的代理伺服器
會移除／重建傳入的轉發標頭時，才啟用 `OMNIROUTE_TRUST_PROXY`。
### 3.3 啟用並測試
```bash
# Remove default configuration
# 移除預設設定
rm -f /etc/nginx/sites-enabled/default
# Enable OmniRoute
# 啟用 OmniRoute
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
# Test and reload
# 測試並重新載入
nginx -t && systemctl reload nginx
```
---
## 4. Configure Cloudflare DNS
## 4. 設定 Cloudflare DNS
### 4.1 Add DNS record
### 4.1 新增 DNS 記錄
In the Cloudflare dashboard → DNS:
在 Cloudflare 儀表板 → DNS：
| Type | Name | Content | Proxy |
| ---- | ------ | ---------------------- | ---------- |
| A | `llms` | `203.0.113.10` (VM IP) | ✅ Proxied |
| 類型 | 名稱 | 內容 | Proxy |
| ---- | ------ | ----------------------- | ----------- |
| A | `llms` | `203.0.113.10`（VM IP） | ✅ 已代理 |
### 4.2 Configure SSL
### 4.2 設定 SSL
Under **SSL/TLS → Overview**:
在 **SSL/TLS → Overview**：
- Mode: **Full (Strict)**
- 模式：**Full (Strict)**
Under **SSL/TLS → Edge Certificates**:
在 **SSL/TLS → Edge Certificates**：
- Always Use HTTPS: ✅ On
- Minimum TLS Version: TLS 1.2
- Automatic HTTPS Rewrites: ✅ On
- Always Use HTTPS：✅ 開啟
- Minimum TLS Version：TLS 1.2
- Automatic HTTPS Rewrites：✅ 開啟
### 4.3 Testing
### 4.3 測試
```bash
curl -sI https://llms.seudominio.com/health
# Should return HTTP/2 200
# 應回傳 HTTP/2 200
```
---
## 5. Operations and Maintenance
## 5. 操作與維護
### Upgrade to a new version
### 升級至新版本
```bash
docker pull diegosouzapw/omniroute:latest
@@ -294,42 +309,42 @@ docker run -d --name omniroute --restart unless-stopped \
diegosouzapw/omniroute:latest
```
### View logs
### 檢視日誌
```bash
docker logs -f omniroute # Real-time stream
docker logs omniroute --tail 50 # Last 50 lines
docker logs -f omniroute # 即時串流
docker logs omniroute --tail 50 # 最後 50 行
```
### Manual database backup
### 手動資料庫備份
```bash
# Copy data from the volume to the host
# 從容器複製資料到主機
docker cp omniroute:/app/data ./backup-$(date +%F)
# Or compress the entire volume
# 或壓縮整個磁碟區
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
```
### Restore from backup
### 從備份還原
```bash
docker stop omniroute
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
alpine sh -c 「rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /」
alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
docker start omniroute
```
---
## 6. Advanced Security
## 6. 進階安全
### Restrict nginx to Cloudflare IPs
### 限制 nginx 僅允許 Cloudflare IP
```bash
cat > /etc/nginx/cloudflare-ips.conf << 『CF』
# Cloudflare IPv4 ranges — update periodically
cat > /etc/nginx/cloudflare-ips.conf << 'CF'
# Cloudflare IPv4 範圍 — 請定期更新
# https://www.cloudflare.com/ips-v4/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
@@ -350,58 +365,58 @@ real_ip_header CF-Connecting-IP;
CF
```
Add the following to `nginx.conf` inside the `http {}` block:
將以下內容加入 `nginx.conf` 中的 `http {}` 區塊：
```nginx
include /etc/nginx/cloudflare-ips.conf;
```
### Install fail2ban
### 安裝 fail2ban
```bash
apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban
# Check status
# 檢查狀態
fail2ban-client status sshd
```
### Block direct access to the Docker port
### 封鎖對 Docker 連接埠的直接存取
```bash
# Prevent direct external access to port 20128
# 防止外部直接存取連接埠 20128
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
# Persist the rules
# 持續保存規則
apt install -y iptables-persistent
netfilter-persistent save
```
---
## 7. Deploy to Cloudflare Workers (Optional)
## 7. 部署至 Cloudflare Workers（選擇性）
For remote access via Cloudflare Workers (without exposing the VM directly):
用於透過 Cloudflare Workers 進行遠端存取（無需直接暴露 VM）：
```bash
# In the local repository
# 在本機儲存庫中
cd omnirouteCloud
npm install
npx wrangler login
npx wrangler deploy
```
See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md).
另請參閱 [TUNNELS_GUIDE.md](./TUNNELS_GUIDE.md) 以了解儲存庫內的 Cloudflare Tunnel 逐步說明。獨立的 `omnirouteCloud/` worker 位於另一個配套儲存庫中。
---
## Port Summary
## 連接埠摘要
| Port | Service | Access |
| ----- | ----------- | -------------------------- |
| 22 | SSH | Public (with fail2ban) |
| 80 | nginx HTTP | Redirect → HTTPS |
| 443 | nginx HTTPS | Via Cloudflare Proxy |
| 20128 | OmniRoute | Localhost only (via nginx) |
| 連接埠 | 服務 | 存取方式 |
| ------ | ------------- | ------------------------------ |
| 22 | SSH | 公開（搭配 fail2ban） |
| 80 | nginx HTTP | 重新導向 → HTTPS |
| 443 | nginx HTTPS | 經由 Cloudflare Proxy |
| 20128 | OmniRoute | 僅限本機（經由 nginx） |

1346
docs/i18n/zh-TW/docs/reference/API_REFERENCE.md
View File

File diff suppressed because it is too large Load Diff

788
docs/i18n/zh-TW/docs/reference/CLI-TOOLS.md
View File

@@ -1,89 +1,284 @@
# CLI Tools Setup Guide — OmniRoute (中文 (簡體))
---
title: "CLI 工具 — OmniRoute"
version: 3.8.40
lastUpdated: 2026-06-28
---
🌐 **Languages:** 🇺🇸 [English](../../../../docs/CLI-TOOLS.md) · 🇸🇦 [ar](../../ar/docs/CLI-TOOLS.md) · 🇧🇬 [bg](../../bg/docs/CLI-TOOLS.md) · 🇧🇩 [bn](../../bn/docs/CLI-TOOLS.md) · 🇨🇿 [cs](../../cs/docs/CLI-TOOLS.md) · 🇩🇰 [da](../../da/docs/CLI-TOOLS.md) · 🇩🇪 [de](../../de/docs/CLI-TOOLS.md) · 🇪🇸 [es](../../es/docs/CLI-TOOLS.md) · 🇮🇷 [fa](../../fa/docs/CLI-TOOLS.md) · 🇫🇮 [fi](../../fi/docs/CLI-TOOLS.md) · 🇫🇷 [fr](../../fr/docs/CLI-TOOLS.md) · 🇮🇳 [gu](../../gu/docs/CLI-TOOLS.md) · 🇮🇱 [he](../../he/docs/CLI-TOOLS.md) · 🇮🇳 [hi](../../hi/docs/CLI-TOOLS.md) · 🇭🇺 [hu](../../hu/docs/CLI-TOOLS.md) · 🇮🇩 [id](../../id/docs/CLI-TOOLS.md) · 🇮🇹 [it](../../it/docs/CLI-TOOLS.md) · 🇯🇵 [ja](../../ja/docs/CLI-TOOLS.md) · 🇰🇷 [ko](../../ko/docs/CLI-TOOLS.md) · 🇮🇳 [mr](../../mr/docs/CLI-TOOLS.md) · 🇲🇾 [ms](../../ms/docs/CLI-TOOLS.md) · 🇳🇱 [nl](../../nl/docs/CLI-TOOLS.md) · 🇳🇴 [no](../../no/docs/CLI-TOOLS.md) · 🇵🇭 [phi](../../phi/docs/CLI-TOOLS.md) · 🇵🇱 [pl](../../pl/docs/CLI-TOOLS.md) · 🇵🇹 [pt](../../pt/docs/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) · 🇷🇴 [ro](../../ro/docs/CLI-TOOLS.md) · 🇷🇺 [ru](../../ru/docs/CLI-TOOLS.md) · 🇸🇰 [sk](../../sk/docs/CLI-TOOLS.md) · 🇸🇪 [sv](../../sv/docs/CLI-TOOLS.md) · 🇰🇪 [sw](../../sw/docs/CLI-TOOLS.md) · 🇮🇳 [ta](../../ta/docs/CLI-TOOLS.md) · 🇮🇳 [te](../../te/docs/CLI-TOOLS.md) · 🇹🇭 [th](../../th/docs/CLI-TOOLS.md) · 🇹🇷 [tr](../../tr/docs/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) · 🇵🇰 [ur](../../ur/docs/CLI-TOOLS.md) · 🇻🇳 [vi](../../vi/docs/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)
# CLI 工具 — OmniRoute
最後更新：2026-06-28
OmniRoute 整合了三類 CLI 工具，分別對應三個專屬儀表板頁面：
| 頁面 | 路由 | 概念 | 數量 |
| ---------------- | -------------------------- | ------------------------------------------------------------ | ---------------- |
| **CLI 程式碼工具** | `/dashboard/cli-code` | 指向 OmniRoute 的程式碼工具（客戶端 → CLI → OmniRoute → 提供商） | 21 |
| **CLI 代理工具** | `/dashboard/cli-agents` | 指向 OmniRoute 的自動代理工具（相同流程，範圍更廣） | 6 |
| **ACP 代理** | `/dashboard/acp-agents` | OmniRoute 透過 stdio/ACP 以反向流程衍生的 CLI | 參見註冊表 |
舊版路由透過 308 重新導向：`/dashboard/cli-tools` → `/dashboard/cli-code`，`/dashboard/agents` → `/dashboard/acp-agents`。
---
This guide explains how to install and configure all supported AI coding CLI tools
to use **OmniRoute** as the unified backend, giving you centralized key management,
cost tracking, model switching, and request logging across every tool.
---
## How It Works
## 運作方式
```
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot
CLI 程式碼工具 / CLI 代理工具（消費流程）：
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
│
▼ (all point to OmniRoute)
▼ （全部指向 OmniRoute）
http://YOUR_SERVER:20128/v1
│
▼ (OmniRoute routes to the right provider)
▼ （OmniRoute 路由至對應提供商）
Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...
ACP 代理（反向衍生流程）：
客戶端請求 → OmniRoute → 透過 stdio/ACP 衍生 CLI → 回應
```
**Benefits:**
**優勢：**
- One API key to manage all tools
- Cost tracking across all CLIs in the dashboard
- Model switching without reconfiguring every tool
- Works locally and on remote servers (VPS)
- 只需一個 API 金鑰管理所有工具
- 在儀表板中追蹤所有 CLI 的費用
- 切換模型無需重新設定每個工具
- 可在本機及遠端伺服器上運作（VPS、Docker、Akamai、Cloudflare Tunnel）
---
## Supported Tools (Dashboard Source of Truth)
## 使用 `setup-*` 自動設定
The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.
Current list (v3.0.0-rc.16):
| Tool | ID | Command | Setup Mode | Install Method |
| ------------------ | ------------- | ---------- | ---------- | -------------- |
| **Claude Code** | `claude` | `claude` | env | npm |
| **OpenAI Codex** | `codex` | `codex` | custom | npm |
| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |
| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |
| **Cursor** | `cursor` | app | guide | desktop app |
| **Cline** | `cline` | `cline` | custom | npm |
| **Kilo Code** | `kilo` | `kilocode` | custom | npm |
| **Continue** | `continue` | extension | guide | VS Code |
| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |
| **GitHub Copilot** | `copilot` | extension | custom | VS Code |
| **OpenCode** | `opencode` | `opencode` | guide | npm |
| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |
| **Qwen Code** | `qwen` | `qwen` | custom | npm |
### CLI fingerprint sync (Agents + Settings)
`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.
This keeps provider IDs aligned with CLI cards and legacy IDs.
| CLI ID | Fingerprint Provider ID |
| ---------------------------------------------------------------------------------------------------- | ----------------------- |
| `kilo` | `kilocode` |
| `copilot` | `github` |
| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |
Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.
---
## Step 1 — Get an OmniRoute API Key
1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)
2. Click **Create API Key**
3. Give it a name (e.g. `cli-tools`) and select all permissions
4. Copy the key — you'll need it for every CLI below
> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`
---
## Step 2 — Install CLI Tools
All npm-based tools require Node.js 18+:
您無需手動編寫每個工具的設定檔。OmniRoute 為每個受支援的 CLI 提供了 `setup-*` 指令，可讀取執行中 OmniRoute（本機或遠端）的**即時**模型目錄，並在您的機器上寫入該工具的設定檔：
```bash
# Claude Code (Anthropic)
omniroute setup-codex omniroute setup-claude omniroute setup-opencode
omniroute setup-cline omniroute setup-kilo omniroute setup-continue
omniroute setup-cursor omniroute setup-roo omniroute setup-crush
omniroute setup-goose omniroute setup-qwen omniroute setup-aider
```
每個指令都接受 `--remote <url> --api-key <key>`（針對遠端 OmniRoute 設定本機工具）、`--dry-run`（預覽不寫入）和 `--port`。不支援模型自動探索的工具（Cline、Kilo、Roo、Goose、Aider、Gemini）需要 `--model <id>`（以及用於非互動執行的 `--yes`）。啟動器 `omniroute launch`（Claude Code）和 `omniroute launch-codex`（Codex）會以正確的環境變數注入來衍生 CLI，完全不寫入設定檔。
> **完整參考：** 主要表格 — 每個指令寫入的內容、所有旗標、本機 vs 遠端，以及哪些工具需要加上 `/v1` 字尾 — 請參閱 **[CLI 整合指南](../guides/CLI-INTEGRATIONS.md)**。
---
## 資料來源
統一目錄位於 `src/shared/constants/cliTools.ts`，型別為 `CLI_TOOLS: Record<string, CliCatalogEntry>`。
每個條目包含以下欄位（定義於 `src/shared/schemas/cliCatalog.ts`）：
| 欄位 | 型別 | 說明 |
| ------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------- |
| `category` | `"code" \| "agent"` | 工具顯示在哪個頁面 |
| `vendor` | `string` | 工具來源（"Anthropic"、"OSS (P. Gauthier)"） |
| `acpSpawnable` | `boolean` | 也可用作 ACP 代理（顯示徽章） |
| `baseUrlSupport` | `"full" \| "partial" \| "none"` | 自訂端點支援程度。`"none"` = MITM 待辦事項 |
| `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | 設定機制 |
| `id`、`name`、`color`、`description`、`docsUrl` | 標準 | 核心顯示欄位 |
`baseUrlSupport: "none"` 的條目**不會**顯示在儀表板頁面上 — 它們會註冊在 MITM 待辦事項中，屬於 plan 11 的範疇（參見 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`）。
---
## 1. CLI 程式碼工具目錄（25 個工具）
所有出現在 `/dashboard/cli-code` 的工具。`baseUrlSupport: none` 的工具會透過 MITM 或手動指南而非自訂基礎 URL 來連接：
| id | 名稱 | 供應商 | baseUrlSupport | configType | acpSpawnable |
| -------------- | ------------------- | ------------------------ | -------------- | --------------- | ------------ |
| claude | Claude Code | Anthropic | full | env | true |
| codex | OpenAI Codex CLI | OpenAI | full | custom | true |
| cline | Cline | OSS（前 Claude Dev） | full | custom | true |
| kilo | Kilo Code | Kilo-Org | full | custom | false |
| roo | Roo Code | Roo（OSS） | full | guide | false |
| continue | Continue | continue.dev | full | guide | false |
| aider | Aider | OSS（P. Gauthier） | full | guide | true |
| forge | ForgeCode | Antinomy HQ | full | custom | true |
| jcode | jcode | 1jehuang（OSS） | full | custom | false |
| deepseek-tui | DeepSeek TUI | Hunter Bown（OSS） | full | custom | false |
| codewhale | CodeWhale | Hmbown（OSS） | full | custom | false |
| opencode | OpenCode | Anomaly（前 SST） | full | guide | true |
| droid | Factory Droid | Factory AI | partial | guide | false |
| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false |
| cursor-cli | Cursor CLI | Anysphere | partial | guide | true |
| smelt | Smelt | leonardcser（OSS） | full | custom | false |
| pi | Pi（pi-coding-agent） | M. Zechner（OSS） | full | custom | false |
| grok-build | Grok Build | xAI | full | custom | false |
| crush | Crush | OSS（Charm） | full | custom | false |
| qwen | Qwen Code | Alibaba | full | guide | true |
| cursor | Cursor | Anysphere | none | guide | false |
| antigravity | Antigravity | Google | none | mitm | false |
| hermes | Hermes | Nous Research | none | guide | false |
| kiro | Kiro AI | Amazon | none | mitm | false |
| custom | 自訂 CLI | — | full | custom-builder | false |
`baseUrlSupport: "partial"` 的工具會在儀表板卡片上顯示「⚠ 基礎 URL 部分支援」徽章。
---
## 2. CLI 代理工具目錄（8 個工具）
出現在 `/dashboard/cli-agents` 的自動代理工具：
| id | 名稱 | 供應商 | baseUrlSupport | acpSpawnable |
| ------------ | ------------------- | ------------------------- | -------------- | ------------ |
| hermes-agent | Hermes Agent | Nous Research | full | false |
| openclaw | OpenClaw | OSS（P. Steinberger） | full | true |
| goose | Goose | Block / Linux Foundation | full | true |
| interpreter | Open Interpreter | OSS | full | true |
| warp | Warp AI | Warp Inc. | partial | true |
| agent-deck | Agent Deck | asheshgoplani（OSS） | full | false |
| omp | Oh My Pi | OSS | full | true |
| letta | Letta CLI | Letta | full | false |
---
## 3. ACP 代理（/dashboard/acp-agents）
此頁面（從 `/dashboard/agents` 重新命名而來）顯示 OmniRoute 可以**衍生**為後端執行引擎（透過 stdio/ACP 協定）的 CLI。目錄獨立維護於 `src/lib/acp/registry.ts`，**不同於** `CLI_TOOLS`。
---
## 4. MITM 待辦事項（不在儀表板中顯示）
以下 CLI 原生不支援自訂基礎 URL，**不會列出**在 CLI 程式碼工具或 CLI 代理工具頁面中。它們是 plan 11 中 MITM 攔截的候選對象：
| CLI | 原因 |
| --------------------- | ------------------------------------------------- |
| windsurf | BYOK 僅限特定 Claude 模型 + 企業 URL/Token |
| amp | 封閉生態系統（Sourcegraph） |
| amazon-q / kiro-cli | AWS SSO 認證，無自訂 URL |
| cowork | Anthropic Desktop，無可設定的端點 |
完整交叉參考請參閱 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`。
---
## 5. 批次偵測 API
所有工具偵測透過單一端點匯總：
**`GET /api/cli-tools/all-statuses`**
- 身份驗證：`requireCliToolsAuth(request)`（與其他 `/api/cli-tools/` 路由相同）
- 回傳：`Record<toolId, ToolBatchStatus>`（型別：`src/shared/types/cliBatchStatus.ts`）
- 策略：對所有工具執行 `Promise.all`，每個工具 5 秒逾時
- 快取：記憶體中 LRU，以設定檔 `mtime` 作為索引。當 `mtime` 變更時失效。伺服器重新啟動時重設。
每個工具的回應結構：
```ts
interface ToolBatchStatus {
detection: {
installed: boolean;
runnable: boolean;
version?: string;
command?: string;
commandPath?: string;
reason?: string;
};
config: {
status: "configured" | "not_configured" | "not_installed" | "unknown" | "other";
endpoint?: string | null;
lastConfiguredAt?: string | null;
};
error?: string; // 已清理，無堆疊追蹤
}
```
---
## 6. 新工具的設定處理器
`configType: "custom"` 的新工具擁有專屬的設定 API 路由：
| 路由 | 工具 |
| ------------------------------------------------- | ----------------------------------- |
| `POST /api/cli-tools/forge-settings` | ForgeCode（.forge.toml） |
| `POST /api/cli-tools/jcode-settings` | jcode（--base-url 旗標） |
| `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI（OPENAI_BASE_URL，舊版） |
| `POST /api/cli-tools/codewhale-settings` | CodeWhale（OPENAI_BASE_URL，主要 + 舊版 `~/.deepseek` 同步） |
| `POST /api/cli-tools/smelt-settings` | Smelt |
| `POST /api/cli-tools/pi-settings` | Pi 程式碼代理 |
| `POST /api/cli-tools/grok-build-settings` | Grok Build（~/.grok/config.toml，`[model.omniroute]`） |
| `POST /api/cli-tools/qwen-settings` | Qwen Code（`~/.qwen/settings.json` + 專用 `.env` 金鑰） |
所有路由都使用 `sanitizeErrorMessage()` 處理錯誤回應（硬性規則 #12）。
---
## 7. 儀表板頁面架構
### CLI 程式碼工具（`/dashboard/cli-code`）
- `src/app/(dashboard)/dashboard/cli-code/page.tsx` — 伺服器元件
- `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — 客戶端網格
- `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — 工具詳細頁面
- `src/app/(dashboard)/dashboard/cli-code/components/` — 12 個專用工具卡片 + `ToolDetailClient.tsx`
### CLI 代理工具（`/dashboard/cli-agents`）
- `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — 伺服器元件
- `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — 客戶端網格
- `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — 重複使用 `ToolDetailClient`
### ACP 代理（`/dashboard/acp-agents`）
- `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — 伺服器元件（從 `agents/` 遷移）
### 共用 UI 元件（`src/shared/components/cli/`）
| 檔案 | 用途 |
| ------------------------ | ---------------------------------------------- |
| `CliToolCard.tsx` | 智慧型狀態卡片（偵測 + 設定 + 端點） |
| `CliConceptCard.tsx` | 各頁面概念說明卡片 |
| `CliComparisonCard.tsx` | 三欄 CLI 類型比較卡片 |
| `BaseUrlSelect.tsx` | 端點下拉選單（本機/雲端/自訂） |
| `ApiKeySelect.tsx` | API 金鑰選擇器 |
| `ManualConfigModal.tsx` | 可複製的設定片段模態框 |
### 共用 Hook（`src/shared/hooks/cli/`）
| 檔案 | 用途 |
| ---------------------------- | ------------------------------------------- |
| `useToolBatchStatuses.ts` | 擷取 `/api/cli-tools/all-statuses`，管理載入/重新整理狀態 |
---
## 8. 國際化（i18n）
plan 14 F9 中新增的命名空間：
| 命名空間 | 用途 |
| ------------- | ------------------------------------------- |
| `cliCommon` | 共用字串（卡片標籤、概念/比較文字、詳細頁面標籤） |
| `cliCode` | CLI 程式碼工具頁面字串 |
| `cliAgents` | CLI 代理工具頁面字串 |
| `acpAgents` | ACP 代理頁面字串 |
已提供完整的巴西葡萄牙文（PT-BR）和英文（EN）翻譯。其他 39 種語言會透過 `src/i18n/request.ts` 中的命名空間層級合併自動回退為英文。
---
## 9. 快速入門
### 步驟 1 — 取得 OmniRoute API 金鑰
1. 開啟 `/dashboard/api-manager` → **建立 API 金鑰**
2. 為金鑰命名（例如 `cli-tools`）並選取所有權限
3. 複製金鑰 — 下方每個 CLI 都會用到
> 您的金鑰格式如：`«redacted:sk-…»`
---
### 步驟 2 — 安裝 CLI 工具
所有基於 npm 的工具都需要 Node.js 22.22.2+ 或 24.x：
```bash
# Claude Code（Anthropic）
npm install -g @anthropic-ai/claude-code
# OpenAI Codex
@@ -98,138 +293,164 @@ npm install -g cline
# KiloCode
npm install -g kilocode
# Kiro CLI (Amazon — requires curl + unzip)
apt-get install -y unzip # on Debian/Ubuntu
curl -fsSL https://cli.kiro.dev/install | bash
export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc
```
# Qwen Code
npm install -g @qwen-code/qwen-code
**Verify:**
# Aider
pip install aider-chat
```bash
claude --version # 2.x.x
codex --version # 0.x.x
opencode --version # x.x.x
cline --version # 2.x.x
kilocode --version # x.x.x (or: kilo --version)
kiro-cli --version # 1.x.x
# Smelt
cargo install smelt # 基於 Rust
# Pi 程式碼代理
# 請參閱 https://github.com/zechnerj/pi-coding-agent 了解安裝方式
# jcode
# 請參閱 https://github.com/1jehuang/jcode 了解安裝方式
```
---
## Step 3 — Set Global Environment Variables
### 步驟 3 — 透過儀表板設定
Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:
1. 前往 `http://localhost:20128/dashboard/cli-code`
2. 在網格中尋找您的工具
3. 點選卡片開啟工具詳細頁面
4. 選取您的 API 金鑰和基礎 URL
5. 點選**套用設定**或複製手動設定片段
---
### 步驟 4 — 設定全域環境變數
```bash
# OmniRoute Universal Endpoint
# OmniRoute 通用端點
export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="sk-your-omniroute-key"
export ANTHROPIC_BASE_URL="http://localhost:20128/v1"
export ANTHROPIC_API_KEY="sk-your-omniroute-key"
export OPENAI_API_KEY="«redacted:sk-…»"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="«redacted:sk-…»"
export GEMINI_BASE_URL="http://localhost:20128/v1"
export GEMINI_API_KEY="sk-your-omniroute-key"
export GEMINI_API_KEY="«redacted:sk-…»"
```
> For a **remote server** replace `localhost:20128` with the server IP or domain,
> e.g. `http://192.168.0.15:20128`.
> 若使用**遠端伺服器**，請將 `localhost:20128` 替換為伺服器 IP 或網域名稱，
> 例如 `http://<your-server-ip>:20128`。
---
## Step 4 — Configure Each Tool
### 步驟 4 — 設定各個工具
### Claude Code
#### Claude Code
```bash
# Via CLI:
claude config set --global api-base-url http://localhost:20128/v1
# Or create ~/.claude/settings.json:
# 建立 ~/.claude/settings.json：
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
{
"apiBaseUrl": "http://localhost:20128/v1",
"apiKey": "sk-your-omniroute-key"
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "«redacted:sk-…»"
}
}
EOF
```
**Test:** `claude "say hello"`
請使用統一的 Anthropic 閘道根路徑來設定 Claude Code。此處不要加上 `/v1`。
**測試：** `claude "say hello"`
---
### OpenAI Codex
#### OpenAI Codex
```bash
mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF
model: auto
apiKey: sk-your-omniroute-key
apiKey: ***
apiBaseUrl: http://localhost:20128/v1
EOF
```
**Test:** `codex "what is 2+2?"`
**測試：** `codex "what is 2+2?"`
---
### OpenCode
#### OpenCode
```bash
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF
[provider.openai]
base_url = "http://localhost:20128/v1"
api_key = "sk-your-omniroute-key"
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF
{
"\$schema": "https://opencode.ai/config.json",
"provider": {
"omniroute": {
"npm": "@ai-sdk/openai-compatible",
"name": "OmniRoute",
"options": {
"baseURL": "http://localhost:20128/v1",
"apiKey": "«redacted:sk-…»"
},
"models": {
"claude-sonnet-4-5": { "name": "claude-sonnet-4-5" },
"claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
"gemini-3-flash": { "name": "gemini-3-flash" }
}
}
}
}
EOF
```
**Test:** `opencode`
**測試：** `opencode`
> 使用 `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`
> 來發送思考變體。
---
### Cline (CLI or VS Code)
#### Cline（CLI 或 VS Code）
**CLI mode:**
**CLI 模式：**
```bash
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
{
"apiProvider": "openai",
"openAiBaseUrl": "http://localhost:20128/v1",
"openAiApiKey": "sk-your-omniroute-key"
"openAiApiKey": "«redacted:sk-…»"
}
EOF
```
**VS Code mode:**
Cline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`
**VS Code 模式：**
Cline 擴充功能設定 → API Provider：`OpenAI Compatible` → Base URL：`http://localhost:20128/v1`
Or use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.
或使用 OmniRoute 儀表板 → **CLI 工具 → Cline → 套用設定**。
---
### KiloCode (CLI or VS Code)
#### KiloCode（CLI 或 VS Code）
**CLI mode:**
**CLI 模式：**
```bash
kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
kilocode --api-base http://localhost:20128/v1 --api-key «redacted:sk-…»
```
**VS Code settings:**
**VS Code 設定：**
```json
{
"kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
"kilo-code.apiKey": "sk-your-omniroute-key"
"kilo-code.apiKey": "«redacted:sk-…»"
}
```
Or use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.
或使用 OmniRoute 儀表板 → **CLI 工具 → KiloCode → 套用設定**。
---
### Continue (VS Code Extension)
#### Continue（VS Code 擴充功能）
Edit `~/.continue/config.yaml`:
編輯 `~/.continue/config.yaml`：
```yaml
models:
@@ -237,162 +458,251 @@ models:
provider: openai
model: auto
apiBase: http://localhost:20128/v1
apiKey: sk-your-omniroute-key
apiKey: ***
default: true
```
Restart VS Code after editing.
編輯後重新啟動 VS Code。
---
### Kiro CLI (Amazon)
#### VS Code Insiders（`chatLanguageModels.json`）
當 VS Code Insiders 設定為使用自訂端點模型，且您希望 OmniRoute 在無需自訂標頭欄位的情況下運作時使用。
**建議位置：**
- Linux：`~/.config/Code - Insiders/User/chatLanguageModels.json`
- Windows：`%APPDATA%/Code - Insiders/User/chatLanguageModels.json`
**使用 Token 化 OmniRoute 別名的範例：**
```json
[
{
"vendor": "customendpoint",
"id": "auto",
"name": "OmniRoute Auto",
"family": "gpt-4",
"version": "1.0.0",
"url": "http://localhost:20128/api/v1/vscode/«redacted:sk-…»/chat/completions",
"modelsUrl": "http://localhost:20128/api/v1/vscode/«redacted:sk-…»/models",
"requestFormat": "openai-chat-completions",
"contextWindow": 256000,
"maxOutputTokens": 32768,
"auth": {
"type": "none"
}
}
]
```
**注意事項：**
- 將 `«redacted:sk-…»` 替換為在 OmniRoute 中建立的 API 金鑰。
- `url` 欄位應指向 `/api/v1/vscode/{token}/chat/completions`。
- `modelsUrl` 欄位應指向 `/api/v1/vscode/{token}/models`。
- 如果客戶端支援自訂標頭，建議使用標準的 `/v1` + Bearer 標頭流程。
- 內嵌 URL 的 Token 是相容性備援方案，可能會出現在編輯器日誌或代理歷史記錄中。
---
#### Kiro CLI（Amazon）
```bash
# Login to your AWS/Kiro account:
# 登入您的 AWS/Kiro 帳戶：
kiro-cli login
# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.
# Use kiro-cli alongside OmniRoute for other tools.
# CLI 使用自己的認證機制 — Kiro CLI 本身不需要 OmniRoute 作為後端。
# 請將 kiro-cli 與 OmniRoute 搭配使用於其他工具。
kiro-cli status
```
至於 **Kiro IDE** 桌面應用程式，請使用 OmniRoute 在 `/dashboard/cli-tools → Kiro` 提供的 MITM 端點。
---
### Qwen Code (Alibaba)
## 10. 內部 OmniRoute CLI
Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.
**Option 1: Environment variables (`~/.qwen/.env`)**
`omniroute` 二進位檔提供用於伺服器生命週期管理、設定、診斷和提供商管理的指令。進入點：`bin/omniroute.mjs`。
```bash
mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF
OPENAI_API_KEY="sk-your-omniroute-key"
OPENAI_BASE_URL="http://localhost:20128/v1"
OPENAI_MODEL="auto"
EOF
omniroute # 啟動伺服器（預設通訊埠 20128）
omniroute setup # 互動式設定精靈
omniroute doctor # 檢查設定、資料庫、通訊埠、執行環境
omniroute providers list # 已設定的提供商連線
omniroute providers test-all # 測試每個作用中連線
omniroute reset-password # 重設管理員密碼
omniroute logs # 串流要求日誌
omniroute health # 詳細健康狀態（斷路器、快取、記憶體）
omniroute --version # 顯示版本
omniroute --help # 顯示所有指令
```
**Option 2: `settings.json` with model providers**
```json
// ~/.qwen/settings.json
{
"env": {
"OPENAI_API_KEY": "sk-your-omniroute-key",
"OPENAI_BASE_URL": "http://localhost:20128/v1"
},
"modelProviders": {
"openai": [
{
"id": "omniroute-default",
"name": "OmniRoute (Auto)",
"envKey": "OPENAI_API_KEY",
"baseUrl": "http://localhost:20128/v1"
}
]
}
}
```
**Option 3: Inline CLI flags**
### 設定與初始化
```bash
OPENAI_BASE_URL="http://localhost:20128/v1" \
OPENAI_API_KEY="sk-your-omniroute-key" \
OPENAI_MODEL="auto" \
qwen
omniroute setup # 互動式設定精靈
omniroute setup --non-interactive # CI/自動化模式（讀取環境變數 + 旗標）
omniroute setup --password '<value>' # 直接設定管理員密碼
omniroute setup --add-provider \
--provider openai \
--api-key '<value>' \
--test-provider # 一氣呵成新增並測試提供商
```
> For a **remote server** replace `localhost:20128` with the server IP or domain.
非互動式設定可識別的環境變數：
**Test:** `qwen "say hello"`
| 變數 | 用途 |
| -------------------- | ----------------------------------------- |
| `OMNIROUTE_API_KEY` | 提供商 API 金鑰（透過 Commander `.env()` 繫結至 `--api-key`） |
| `DATA_DIR` | 覆寫 OmniRoute 資料目錄 |
### Cursor (Desktop App)
所有其他非互動式輸入皆以旗標傳遞（非環境變數）：
`--password`、`--provider`、`--provider-name`、`--provider-base-url`、`--default-model`
（請參閱上方 `omniroute setup` 選項）。
> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,
> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.
### 診斷
Via GUI: **Settings → Models → OpenAI API Key**
```bash
omniroute doctor # 檢查設定、資料庫、通訊埠、執行環境、記憶體、運作狀態
omniroute doctor --json # 機器可讀的 JSON
omniroute doctor --no-liveness # 跳過 HTTP 健康狀態探測
omniroute doctor --host 0.0.0.0 # 覆寫運作狀態主機
omniroute doctor --liveness-url <url> # 完整健康端點 URL 覆寫
```
- Base URL: `https://your-domain.com/v1`
- API Key: your OmniRoute key
doctor 會執行以下檢查：`Config`、`Database`、`Storage/encryption`、
`Port availability`、`Node runtime`、`Native binary`（better-sqlite3）、
`Memory` 和 `Server liveness`。若有任一檢查結果為 `fail`，則以非零退出碼結束。
### 提供商管理
```bash
omniroute providers available # OmniRoute 提供商目錄
omniroute providers available --search openai # 依 ID/名稱/別名/類別過濾目錄
omniroute providers available --category api-key # 依類別過濾（api-key、oauth、free 等）
omniroute providers available --json # 機器可讀的 JSON
omniroute providers list # 已設定的提供商連線
omniroute providers list --json
omniroute providers test <id|name> # 測試一個已設定的連線
omniroute providers test-all # 測試每個作用中連線
omniroute providers validate # 僅限本機的結構驗證
```
> `providers available` 讀取 OmniRoute 目錄；`providers list/test/test-all/validate`
> 直接讀取本機 SQLite 資料庫，無需伺服器執行中。
### 復原與重設
```bash
omniroute reset-password # 重設管理員密碼（亦可使用：omniroute-reset-password）
omniroute reset-encrypted-columns # 顯示警告 + 加密憑證重設的試執行
omniroute reset-encrypted-columns --force # 實際將 SQLite 中的加密憑證設為 null
```
### 憑證匯出（⚠ 請謹慎處理）
```bash
omniroute auth export # 顯示警告 + 確認閘道 — 不會存取資料庫
omniroute auth export --force # 將所有連線的**解密後**憑證匯出至 stdout 為 JSON
omniroute auth export --force --id <id> # 僅匯出符合條件的連線
omniroute auth export --force --format env # 輸出為 OMNIROUTE_<PROVIDER>_<FIELD>=<value> 格式
omniroute auth export --force --out creds.json # 寫入檔案（以 0600 權限建立）
```
`auth export` 是**僅限本機**（直接讀取 SQLite，無 HTTP 路由），且故意將
**明文** `apiKey`/`accessToken`/`refreshToken`/`idToken` 值寫入/輸出 — 這是功能，不是錯誤。
若未使用 `--force`，則不會從資料庫讀取任何內容，也不會解密任何內容。在輸出任何明文之前，
stderr 上一定會顯示警告橫幅。需要設定 `STORAGE_ENCRYPTION_KEY`。
如果某個欄位解密失敗（金鑰過期、密文損毀），會回報為
`<field>DecryptFailed: true`，而非中止整個匯出作業或洩漏底層錯誤。
### 其他子指令
以下指令假設 OmniRoute 伺服器正在執行中，除非另有說明：
```bash
omniroute status # 完整的執行時期狀態
omniroute logs # 串流要求日誌（--json、--search、--follow）
omniroute config show # 顯示目前設定
omniroute provider list # 列出可用提供商（providers list 的別名）
omniroute provider add # 將 OmniRoute 註冊為工具上的提供商
omniroute keys add | list | remove # 管理 API 金鑰
omniroute models [provider] # 列出模型（--json、--search）
omniroute combo list | switch | create | delete
omniroute backup # 快照設定 + 資料庫
omniroute restore # 從先前的快照還原
omniroute health # 詳細健康狀態（斷路器、快取、記憶體）
omniroute quota # 提供商配額使用情況
omniroute cache # 快取狀態
omniroute cache clear # 清除語意 + 簽章快取
omniroute mcp status | restart # MCP 伺服器狀態 / 重新啟動
omniroute a2a status | card # A2A 伺服器狀態 / 代理卡片
omniroute tunnel list | create | stop # 管理通道（cloudflare/tailscale/ngrok）
omniroute env show | get <k> | set <k> <v> # 檢查 / 設定環境變數（暫時性）
omniroute test # 提供商連線冒煙測試
omniroute update # 檢查更新
omniroute completion # 產生 Shell 補全
```
### 常用旗標
| 旗標 | 說明 |
| ------------------- | ----------------------------------------- |
| `--no-open` | 啟動時不自動開啟瀏覽器 |
| `--port <n>` | 覆寫 API 通訊埠（預設 20128） |
| `--mcp` | 以 MCP 伺服器模式透過 stdio 執行（用於 IDE）|
| `--non-interactive` | CI 模式（無提示；從環境變數/旗標讀取） |
| `--json` | 機器可讀的 JSON 輸出（doctor、providers 等）|
| `--help`、`-h` | 顯示指令專屬說明 |
| `--version`、`-v` | 顯示已安裝版本 |
---
## Dashboard Auto-Configuration
## 可用 API 端點
The OmniRoute dashboard automates configuration for most tools:
| 端點 | 說明 | 用途 |
| --------------------------- | ----------------- | ----------------------- |
| `/v1/chat/completions` | 標準聊天（所有提供商）| 所有現代工具 |
| `/v1/responses` | Responses API（OpenAI 格式）| Codex、代理工作流程 |
| `/v1/completions` | 舊版文字補全 | 使用 `prompt:` 的較舊工具 |
| `/v1/embeddings` | 文字嵌入 | RAG、搜尋 |
| `/v1/images/generations` | 圖片生成 | GPT-Image、Flux 等 |
| `/v1/audio/speech` | 文字轉語音 | ElevenLabs、OpenAI TTS |
| `/v1/audio/transcriptions` | 語音轉文字 | Deepgram、AssemblyAI |
1. Go to `http://localhost:20128/dashboard/cli-tools`
2. Expand any tool card
3. Select your API key from the dropdown
4. Click **Apply Config** (if tool is detected as installed)
5. Or copy the generated config snippet manually
可直接貼上的 Token 化 OmniRoute URL 範例：
---
```txt
Token 範例：«redacted:sk-…»
## Built-in Agents: Droid & OpenClaw
**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.
They run as internal routes and use OmniRoute's model routing automatically.
- Access: `http://localhost:20128/dashboard/agents`
- Configure: same combos and providers as all other tools
- No API key or CLI install required
---
## Available API Endpoints
| Endpoint | Description | Use For |
| -------------------------- | ----------------------------- | --------------------------- |
| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |
| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |
| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |
| `/v1/embeddings` | Text embeddings | RAG, search |
| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |
| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |
| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |
標準 OpenAI 基礎：http://localhost:20128/v1
VS Code 模型：http://localhost:20128/api/v1/vscode/«redacted:sk-…»/models
VS Code 聊天：http://localhost:20128/api/v1/vscode/«redacted:sk-…»/chat/completions
VS Code responses：http://localhost:20128/api/v1/vscode/«redacted:sk-…»/responses
Ollama tags：http://localhost:20128/api/v1/vscode/«redacted:sk-…»/api/tags
Ollama 聊天：http://localhost:20128/api/v1/vscode/«redacted:sk-…»/api/chat
```
---
## 故障排除
| Error | Cause | Fix |
| ------------------------- | ----------------------- | ------------------------------------------ |
| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |
| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |
| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |
| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |
| CLI shows "not installed" | Binary not in PATH | Check `which <command>` |
| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` |
---
## Quick Setup Script (One Command)
```bash
# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
OMNIROUTE_URL="http://localhost:20128/v1"
OMNIROUTE_KEY="sk-your-omniroute-key"
npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code
# Kiro CLI
apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash
# Write configs
mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue
cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
cat >> ~/.bashrc << EOF
export OPENAI_BASE_URL="$OMNIROUTE_URL"
export OPENAI_API_KEY="$OMNIROUTE_KEY"
export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
EOF
source ~/.bashrc
echo "✅ All CLIs installed and configured for OmniRoute"
```
| 錯誤 | 原因 | 解決方式 |
| ---------------------------------------------- | ------------------------- | ----------------------------------------------- |
| `Connection refused` | OmniRoute 未執行 | `omniroute serve` |
| `401 Unauthorized` | API 金鑰錯誤 | 在 `/dashboard/api-manager` 中檢查 |
| `No combo configured` | 無作用中路由組合 | 在 `/dashboard/combos` 中設定 |
| CLI 顯示「not installed」 | 二進位檔不在 PATH 中 | 檢查 `which <command>` |
| 儀表板在安裝後顯示「not detected」 | 快取過期 | 點選儀表板中的「⟳ 重新整理偵測」 |
| 舊連結 `/dashboard/cli-tools` | v3.8.6 之前的書籤 | 自動重新導向至 `/dashboard/cli-code`（308） |
| 舊連結 `/dashboard/agents` | v3.8.6 之前的書籤 | 自動重新導向至 `/dashboard/acp-agents`（308） |

916
docs/i18n/zh-TW/docs/reference/ENVIRONMENT.md
View File

File diff suppressed because it is too large Load Diff

644
docs/i18n/zh-TW/docs/routing/AUTO-COMBO.md
View File

@@ -1,67 +1,617 @@
# OmniRoute Auto-Combo Engine (中文 (簡體))
🌐 **Languages:** 🇺🇸 [English](../../../../docs/AUTO-COMBO.md) · 🇸🇦 [ar](../../ar/docs/AUTO-COMBO.md) · 🇧🇬 [bg](../../bg/docs/AUTO-COMBO.md) · 🇧🇩 [bn](../../bn/docs/AUTO-COMBO.md) · 🇨🇿 [cs](../../cs/docs/AUTO-COMBO.md) · 🇩🇰 [da](../../da/docs/AUTO-COMBO.md) · 🇩🇪 [de](../../de/docs/AUTO-COMBO.md) · 🇪🇸 [es](../../es/docs/AUTO-COMBO.md) · 🇮🇷 [fa](../../fa/docs/AUTO-COMBO.md) · 🇫🇮 [fi](../../fi/docs/AUTO-COMBO.md) · 🇫🇷 [fr](../../fr/docs/AUTO-COMBO.md) · 🇮🇳 [gu](../../gu/docs/AUTO-COMBO.md) · 🇮🇱 [he](../../he/docs/AUTO-COMBO.md) · 🇮🇳 [hi](../../hi/docs/AUTO-COMBO.md) · 🇭🇺 [hu](../../hu/docs/AUTO-COMBO.md) · 🇮🇩 [id](../../id/docs/AUTO-COMBO.md) · 🇮🇹 [it](../../it/docs/AUTO-COMBO.md) · 🇯🇵 [ja](../../ja/docs/AUTO-COMBO.md) · 🇰🇷 [ko](../../ko/docs/AUTO-COMBO.md) · 🇮🇳 [mr](../../mr/docs/AUTO-COMBO.md) · 🇲🇾 [ms](../../ms/docs/AUTO-COMBO.md) · 🇳🇱 [nl](../../nl/docs/AUTO-COMBO.md) · 🇳🇴 [no](../../no/docs/AUTO-COMBO.md) · 🇵🇭 [phi](../../phi/docs/AUTO-COMBO.md) · 🇵🇱 [pl](../../pl/docs/AUTO-COMBO.md) · 🇵🇹 [pt](../../pt/docs/AUTO-COMBO.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) · 🇷🇴 [ro](../../ro/docs/AUTO-COMBO.md) · 🇷🇺 [ru](../../ru/docs/AUTO-COMBO.md) · 🇸🇰 [sk](../../sk/docs/AUTO-COMBO.md) · 🇸🇪 [sv](../../sv/docs/AUTO-COMBO.md) · 🇰🇪 [sw](../../sw/docs/AUTO-COMBO.md) · 🇮🇳 [ta](../../ta/docs/AUTO-COMBO.md) · 🇮🇳 [te](../../te/docs/AUTO-COMBO.md) · 🇹🇭 [th](../../th/docs/AUTO-COMBO.md) · 🇹🇷 [tr](../../tr/docs/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) · 🇵🇰 [ur](../../ur/docs/AUTO-COMBO.md) · 🇻🇳 [vi](../../vi/docs/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/AUTO-COMBO.md)
---
title: "OmniRoute 自動組合引擎"
version: 3.8.40
lastUpdated: 2026-06-28
---
> Self-managing model chains with adaptive scoring
# OmniRoute 自動組合引擎
## How It Works
> **給一般使用者**：想要快速入門？請參閱[自動組合使用者指南](../getting-started/AUTO-COMBO-GUIDE.md)取得簡單的說明與範例。
The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**:
> 自我管理模型鏈，具備自適應評分 + 零設定自動路由
| Factor | Weight | Description |
| :--------- | :----- | :---------------------------------------------- |
| Quota | 0.20 | Remaining capacity [0..1] |
| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 |
| CostInv | 0.20 | Inverse cost (cheaper = higher score) |
| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) |
| TaskFit | 0.10 | Model × task type fitness score |
| Stability | 0.10 | Low variance in latency/errors |
## 零設定自動路由（`auto/` 前綴）
## Mode Packs
> **新功能：** 無需建立組合。直接在任何客戶端中使用 `auto/` 前綴。
| Pack | Focus | Key Weight |
| :---------------------- | :----------- | :--------------- |
| 🚀 **Ship Fast** | Speed | latencyInv: 0.35 |
| 💰 **Cost Saver** | Economy | costInv: 0.40 |
| 🎯 **Quality First** | Best model | taskFit: 0.40 |
| 📡 **Offline Friendly** | Availability | quota: 0.40 |
### 快速範例
## Self-Healing
| 模型 ID | 變體 | 行為 |
| --------------- | --------- | --------------------------------------------------------------- |
| `auto` | 預設 | 所有已連線提供商，LKGP 策略，平衡權重 |
| `auto/coding` | coding | 品質優先權重，適合程式碼生成 |
| `auto/fast` | fast | 低延遲加權選擇 |
| `auto/cheap` | cheap | 成本最佳化路由（最低成本優先） |
| `auto/offline` | offline | 偏好額度可用性最高的提供商 |
| `auto/smart` | smart | 品質優先 + 較高探索率（10%），以發掘更佳模型 |
| `auto/lkgp` | lkgp | 明確 LKGP（與預設 `auto` 相同） |
- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min)
- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests
- **Incident mode**: >50% OPEN → disable exploration, maximize stability
- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout
### 類別 × 層級組合（`auto/<類別>:<層級>`）
## Bandit Exploration
OpenRouter 風格的後綴將**路由種類**（類別）與**最佳化方式**（層級）分離，讓您可以自由組合（#4235 Phase B, `open-sse/services/autoCombo/suffixComposition.ts`）：
5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode.
- **類別**（依能力過濾候選池）：`coding`（程式）· `reasoning`（推理）· `vision`（視覺）· `chat`（對話）· `multimodal`（多模態）。`vision`/`multimodal` 保留具視覺能力的模型；`reasoning` 保留推理/思考模型。
- **層級**（選擇評分權重 / 過濾池）：`fast`（快速出貨）· `cheap`（別名 `floor`，節省成本）· `reliable`（斷路器健康度 + 延遲穩定性）· `free` / `pro`（透過 `classifyTier` 依模型層級過濾池 — 免費層 vs. 高級層）。
| 範例 | 解析結果 |
| --------------------------- | ----------------------------------------------- |
| `auto/coding:fast` | coding 池，低延遲權重 |
| `auto/coding:cheap` | coding 池，成本最佳化（別名 `auto/coding:floor`）|
| `auto/reasoning:pro` | 僅限推理/思考模型，高級層 |
| `auto/vision` | 具視覺能力的模型（無層級 → 平衡權重） |
| `auto/multimodal:free` | 多模態能力模型，僅限免費層 |
任何有效的 `auto/<類別>[:<層級>]` 皆可按需解析；精選子集會在 `/v1/models` 與儀表板中顯示（`AUTO_SUFFIX_VARIANTS` 定義於 `open-sse/services/autoCombo/builtinCatalog.ts`）。過濾採用**容錯開放**機制—若條件未匹配到任何已連線模型，則使用完整候選池，確保路由永不中斷。核心評分器（`combo.ts`）維持不變；類別/層級過濾則在 `buildAutoCandidates` 中執行。
> **即時模型智慧：** 若 `ARENA_ELO_SYNC_ENABLED` 旗標開啟，自動路由的適應性會參考即時 **Arena ELO** 排名 + **models.dev** 層級資料；否則回退至靜態適應性評分表。
**使用方式：**
```bash
# 任何支援 OpenAI 格式的 IDE 或 CLI 工具
Base URL: http://localhost:20128/v1
API Key: <your-endpoint-key>
# 在程式碼/設定中，將 model 設為：
model: "auto" # 平衡預設
model: "auto/coding" # 最適合程式任務
model: "auto/fast" # 最快的可用選項
model: "auto/cheap" # 每 token 最便宜
```
**運作流程：**
1. OmniRoute 在 `src/sse/handlers/chat.ts` 中偵測到 `auto/` 前綴
2. 查詢資料庫中所有**活躍的提供商連線**
3. 過濾出具有有效憑證（API 金鑰或 OAuth token）的連線
4. 為每個連線決定模型（`connection.defaultModel` 或提供商的第一個模型）
5. 在記憶體中建立**虛擬組合**（不存入資料庫）
6. 使用所選變體的權重設定檔 + LKGP 策略進行路由
**主要特性：**
- ✅ **永遠開啟：** 無需開關、無需建立組合、無需設定
- ✅ **動態：** 自動反映當前連線的提供商
- ✅ **工作階段黏著性：** LKGP 確保上次成功的提供商獲得優先權
- ✅ **多帳號感知：** 每個提供商連線成為獨立的候選項目
- ✅ **無資料庫寫入：** 虛擬組合僅存在於請求期間，零持久化開銷
### 依金鑰候選控制（#7819, Level 1+2）
`GET /v1/auto-combo/{channel}/candidates`（`{channel}` = `auto/` 後的後綴，或基礎頻道使用 `auto` 字面值）是一個**唯讀**端點，列出某個 `auto/*` 頻道當前的候選池，並裝飾有即時可達性資訊，重複使用現有的彈性讀取機制（絕不直接使用原始的斷路器 `state`）：
- 提供商斷路器 — `getCircuitBreaker(provider).getStatus()` / `.canExecute()`
- 連線冷卻 — `rateLimitedUntil` / `testStatus`（來自已解析的 `provider_connections` 資料列）
- 模型鎖定 — `isModelLocked(provider, connectionId, model)`
每個候選項也攜帶此 API 金鑰的 `excluded`（排除）旗標。排除設定依各 API 金鑰儲存（`auto_candidate_overrides` 資料表，遷移 `128`）— OmniRoute 為單租戶架構，無 `users` 資料表，因此 `apiKeyId` 是最接近的實際呼叫者識別身份—並在候選池的瓶頸點透過純粹且經單元測試的 `filterExcludedCandidates()` 強制執行（`open-sse/services/autoCombo/virtualFactory.ts` → `open-sse/services/autoCombo/candidateOverrides.ts`）。此過濾採用**容錯開放**機制：若 `apiKeyId`/channel 未設定或資料庫查詢失敗，則不進行過濾，使未設定任何覆寫的管理員所看到的路由行為與此功能推出前完全一致。
**延至後續議題：** 依候選權重 + 明確排序（Level 3 — 饋入現有的加權/優先策略路徑），以及為每個 `auto/*` 頻道鎖定特定的 `combo.ts` 策略（Level 4）。請參閱 #7819 計畫中有關覆寫設定應維持依 API 金鑰或改為全域的開放問題（考量單租戶模型）。
**幕後流程：**
```txt
Request: { model: "auto/coding" }
↓
src/sse/handlers/chat.ts 偵測前綴
↓
createVirtualAutoCombo('coding') → 來自活躍連線的候選池
↓
handleComboChat（與持久化組合使用相同引擎）
↓
自動評分為每個請求選擇最佳提供商/模型
```
**實作檔案：**
| 檔案 | 用途 |
| ------------------------------------------------------------ | --------------------------------------- |
| `open-sse/services/autoCombo/autoPrefix.ts` | 前綴解析器（`parseAutoPrefix`） |
| `open-sse/services/autoCombo/virtualFactory.ts` | 建立虛擬 `AutoComboConfig` 物件 |
| `open-sse/services/autoCombo/providerRegistryAccessor.ts` | 用於 mock 提供商註冊表的測試鉤子 |
| `src/sse/handlers/chat.ts` | 整合點：自動前綴短路處理 |
| `src/shared/constants/providers.ts` | `SYSTEM_PROVIDERS.auto` 系統條目 |
## 運作原理（持久化自動組合）
自動組合引擎使用**12 因子評分函數**（定義於 `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`）為每個請求動態選擇最佳的提供商/模型。所有權重合計為 **1.0**。
![自動組合 12 因子評分](../diagrams/exported/auto-combo-12factor.svg)
> 來源：[diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd)（可透過 `npm run docs:render-diagrams` 重新生成）。
| 因子 | 預設權重 | 說明 |
| :--------------------- | :------- | :---------------------------------------------------------------- |
| `health`（健康度） | 0.20 | 斷路器健康分數（CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0） |
| `quota`（額度） | 0.15 | 剩餘額度 / 速率限制餘裕 [0..1] |
| `costInv`（成本倒數） | 0.15 | 倒數**混合**成本（60% 輸入 + 40% 輸出 token 價格，經正規化）— 越便宜分數越高 |
| `latencyInv`（延遲倒數）| 0.12 | 倒數 p95 延遲經池正規化 — 越快分數越高 |
| `taskFit`（任務適應性）| 0.08 | 任務類型適應性（程式、審查、規劃、分析、除錯、文件） |
| `stability`（穩定性） | 0.05 | 基於變異數的穩定性（低延遲 stdDev / 錯誤率） |
| `tierPriority`（層級優先）| 0.05 | 帳戶層級優先級 — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 |
| `tierAffinity`（層級親和性）| 0.05 | 候選層級與清單建議層級之間的親和性 |
| `specificityMatch`（特異性匹配）| 0.05 | 請求特異性（清單提示）與模型層級之間的匹配度 |
| `contextAffinity`（上下文親和性）| 0.05 | 請求的上下文視窗需求與模型上下文視窗之間的親和性 |
| `connectionDensity`（連線密度）| 0.05 | 在同一個提供商的不同連線之間分散負載（反集中化） |
| `resetWindowAffinity`（重置視窗親和性）| 0.00 | 傾向於額度重置視窗有利的連線（預設停用） |
**合計：** `0.20 + 0.15 + 0.15 + 0.12 + 0.08 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.00 = 1.0`（經 `validateWeights()` 驗證）。
## 模式套件
四個預定義的加權設定檔位於 `open-sse/services/autoCombo/modePacks.ts`。每個套件會覆寫預設權重，使選擇偏向特定目標。以下是**每個套件的完整權重表**（每個設定檔行合計為 1.0）。
| 因子 | ship-fast | cost-saver | quality-first | offline-friendly |
| :----------- | :-------- | :--------- | :------------ | :--------------- |
| quota | 0.14 | 0.14 | 0.10 | **0.37** |
| health | 0.28 | 0.19 | 0.18 | 0.28 |
| costInv | 0.05 | **0.37** | 0.05 | 0.10 |
| latencyInv | **0.32** | 0.05 | 0.05 | 0.05 |
| taskFit | 0.10 | 0.10 | **0.37** | 0.00 |
| stability | 0.00 | 0.05 | 0.15 | 0.10 |
| tierPriority | 0.05 | 0.05 | 0.05 | 0.05 |
備註：
- `tierAffinity` 和 `specificityMatch` 未在模式套件中設定 — `calculateScore()` 在缺少時以 `?? 0` 處理。
- 各套件重點一覽：
- **ship-fast（快速出貨）** → latencyInv 0.32 + health 0.28（低延遲、健康連線）
- **cost-saver（節省成本）** → costInv 0.37（最便宜的 token 勝出）
- **quality-first（品質優先）** → taskFit 0.37 + stability 0.15（最適合任務的模型，一致穩定）
- **offline-friendly（離線友善）** → quota 0.37 + health 0.28（最大餘裕，不計速度或成本）
### 每次請求控制（標頭）— #6023 / #6024 / #6025 / #3470
`auto` 組合可透過三個標頭**針對每次請求**進行調整，無需修改組合的儲存設定。這些僅適用於 `auto` 策略，且僅對攜帶這些標頭的請求生效；當標頭不存在時，則使用組合儲存的 `modePack`/`budgetCap`/`budgetFallback`。
| 標頭 | 接受值 | 效果 |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-Mode` | 預設別名（`fast`、`balanced`、`quality`、`cheap`、`reliable`、`offline`）或原始套件名稱（`ship-fast`、`cost-saver`、`quality-first`、`offline-friendly`、`reliability-first`） | 覆寫本次請求的評分權重。`balanced`/`default` 強制使用預設權重（無套件）。未知值則忽略（保留原有設定）。 |
| `X-OmniRoute-Budget` | 正數（每次請求的最大美元金額） | 硬性成本上限：估計成本超過此值的候選項在選擇前即被過濾。當**每個**候選項都超過上限時，行為由下方的 `X-OmniRoute-Budget-Fallback` 控制。 |
| `X-OmniRoute-Budget-Fallback` | `cheapest`（預設，別名：`cheapest-viable`、`soft`）或 `strict`（別名：`block`、`hard`） | `cheapest`：回退至全域最便宜的候選項（即使仍超過上限，為舊版行為）。`strict`：拒絕選擇—請求快速失敗，回傳 `HTTP 402`，而非默默超支。未知值則忽略。 |
```bash
# 強制使用最快設定檔，將此請求上限設為 $0.05，超支時直接封鎖而非降級
curl -sS http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-H "X-OmniRoute-Mode: fast" \
-H "X-OmniRoute-Budget: 0.05" \
-H "X-OmniRoute-Budget-Fallback: strict" \
-d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'
```
解析是一個純函數（`open-sse/services/autoCombo/requestControls.ts`）；解析後的值饋入引擎現有的 `config.modePack` / `config.budgetCap` / `config.budgetFallback` 輸入。組合儲存的 `config.budgetFallback`（`"strict"` | `"cheapest"`）設定持久化策略；標頭則為單次請求覆寫此設定。
## 所有路由策略
OmniRoute 的組合引擎支援 **18 種路由策略**（宣告於 `src/shared/constants/routingStrategies.ts` → `ROUTING_STRATEGY_VALUES`）。自動組合引擎本身以 `auto` 策略對外提供；其他策略可用於持久化組合。
| 策略 | 說明 |
| :----------------- | :--------------------------------------------------------------------------------- |
| `priority` | 依明確優先級排列的第一目標有序列表 |
| `weighted` | 依各目標權重的加權隨機選擇 |
| `round-robin` | 依序循環切換目標 |
| `context-relay` | 跨目標交接上下文（長對話） |
| `fill-first` | 先填滿每個目標的額度，再移至下一個 |
| `p2c` | Power-of-2-choices 隨機負載平衡 |
| `random` | 均勻隨機選擇 |
| `least-used` | 挑選當前負載最低的目標 |
| `cost-optimized` | 依目錄定價最小化每次請求成本 |
| `reset-aware` ⭐ | 依額度重置時間排序 — 重置視窗短者優先 |
| `reset-window` | 偏好額度視窗最快重置的目標 |
| `headroom` | 挑選剩餘額度空間最大的目標 |
| `strict-random` | 純隨機，不排除重複 |
| `auto` | 使用自動組合評分（9 因子）— **推薦** |
| `lkgp` | 上次已知良好路徑（黏著路由至上次成功的目標） |
| `context-optimized`| 挑選最適合當前上下文大小的目標 |
| `fusion` 🧬 | 平行分發給多個模型面板，再由評判模型合成一個答案（詳見下方） |
| `pipeline` | 依序執行目標，將每個步驟的輸出串接至下一步驟的輸入；僅回傳最終答案（#6396） |
⭐ = v3.8.0 新增 · 🧬 = v3.8.36 新增
## Fusion 策略
`fusion` 是唯一一種**不選擇單一目標**的策略。它將提示**平行分發給每個面板模型**，然後由可設定的**評判模型**從所有面板回應中合成一個最終答案。移植自上游 `decolua/9router`（OpenRouter 的 Fusion 設計）；實作位於 `open-sse/services/fusion.ts`。
運作方式：
0. **含有工具的請求繞過** — 若請求攜帶非空的 `tools` 陣列且 `tool_choice` 非明確設為 `"none"`，則跳過面板：直接路由至單一模型（設定的評判模型，或 `panel[0]`），`tools`/`tool_choice` 原樣傳遞。面板成員無法存取工具，且評判模型的合成指示會抑制工具呼叫輸出，因此代理/工具呼叫客戶端會獲得真正的工具呼叫決策，而非合成的散文（#6771）。
1. **平行分發**（僅限不含工具的請求）— 提示同時發送給所有面板模型，強制非串流並移除工具（評判模型需要完整散文才能合成）。
2. **法定人數寬限期收集** — 一旦收到 `minPanel` 個答案，隨即啟動一個短暫的寬限期計時器等待落後者，然後以已收集到的所有答案繼續進行融合。這限制了最慢模型對實際時間的懲罰，並設有硬性超時上限。
3. **評判合成** — 面板答案經匿名化處理（`Source 1`、`Source 2`……— 使評判模型衡量內容實質而非品牌）後交給評判模型，由其分析共識/矛盾/部分覆蓋/獨特見解/盲點，然後撰寫**一個**權威答案。評判呼叫保留客戶端的原始 `stream` 旗標 + 工具，因此串流和下游工具使用仍可運作。
4. **優雅降級** — 0 個面板答案 → `503`；恰好 1 個答案存活 → 直接回傳該答案（無需融合）；單一模型面板則直接回傳答案。
面板成員也可以是 `combo-ref` 步驟（`{kind: "combo-ref", comboName: "..."}`），引用另一個組合—它被解析為**一個黑箱面板聲音**（完整遞迴分發至被引用的組合，而非將該組合自身的目標展開），並具有與其他所有使用 combo-ref 的策略相同的深度/循環保護機制（#6764）。
### 設定
設定於組合的 `config` blob（無需結構描述遷移—它重複使用現有的 `combos` 資料表）：
| 欄位 | 類型 | 預設值 | 用途 |
| :------------------------------------------ | :------- | :---------------- | :---------------------------------------------------------- |
| `config.judgeModel` | `string` | 第一個面板模型 | 負責合成最終答案的模型 |
| `config.fusionTuning.minPanel` | `number` | `2` | 寬限期計時器啟動前所需的成功答案數（限制在 `[2, panelSize]` 之間）|
| `config.fusionTuning.stragglerGraceMs` | `number` | `8000` | 達到法定人數後等待落後者的時間 |
| `config.fusionTuning.panelHardTimeoutMs` | `number` | `90000` | 絕對超時上限，防止單一掛起的模型拖垮整個請求 |
預設值位於 `FUSION_DEFAULTS`（`open-sse/services/fusion.ts`）。
### 範例
```bash
curl -X POST http://localhost:20128/api/combos \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{
"name": "fusion-panel",
"strategy": "fusion",
"targets": [
{ "model": "cc/claude-opus-4-7" },
{ "model": "cx/gpt-5.5" },
{ "model": "glm/glm-5.1" }
],
"config": {
"judgeModel": "cc/claude-opus-4-7",
"fusionTuning": { "minPanel": 2, "stragglerGraceMs": 8000, "panelHardTimeoutMs": 90000 }
}
}'
```
然後像任何組合一樣呼叫：`{"model":"fusion-panel","messages":[...]}`。
## 虛擬自動組合工廠
自動組合引擎無需預先定義的組合。相反地，`open-sse/services/autoCombo/virtualFactory.ts` 會即時建立候選項：
1. 取得 `getProviderConnections({ isActive: true })`（所有啟用的連線）
2. 過濾出具備有效憑證的連線（API 金鑰或未過期的 OAuth token，透過 `hasUsableOAuthToken()`）
3. 與 `getProviderRegistry()` 交叉參考以取得模型可用性 + 定價
4. 對每個元組 `(provider, model, connection)` 建立 `VirtualAutoComboCandidate`
5. 選取 `connection.defaultModel`（或註冊表中的第一個模型）作為分發目標
6. 使用 9 因子 `scorePool()` 和變體的權重套件為每個候選項評分
7. 回傳結果的記憶體中 `AutoComboConfig` 供 `handleComboChat()` 使用 — 永不持久化至資料庫
這表示**新增一個啟用 `auto/*` 的提供商會自動擴展候選池**—無需手動編輯組合。虛擬組合在每次請求時重新建立，因此新新增或剛恢復健康的連線會立即被納入。
## 自我修復
- **暫時排除**：分數 < 0.2 → 排除 5 分鐘（漸進式退避，最長 30 分鐘）
- **斷路器感知**：OPEN → 自動排除；HALF_OPEN → 探測請求
- **事故模式**：>50% OPEN → 停用探索，最大化穩定性
- **冷卻恢復**：排除後，第一個請求為「探測」請求，使用縮短的超時時間
## Bandit 探索
5% 的請求（可設定）會路由至隨機提供商進行探索。事故模式下停用。
## API
```bash
# Create auto-combo
curl -X POST http://localhost:20128/api/combos/auto \
-H "Content-Type: application/json" \
-d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'
**沒有專用的 `POST /api/combos/auto` 端點**—自動組合透過兩種方式使用：
# List auto-combos
curl http://localhost:20128/api/combos/auto
1. **零設定（推薦）：** 發送任何聊天完成請求，設定 `model: "auto"` 或 `model: "auto/<變體>"`。虛擬工廠為每次請求建立組合 — 無需持久化，無需 API 呼叫。
2. **使用 `strategy: "auto"` 的持久化組合：** 透過 `POST /api/combos` 建立一般組合，設定 `strategy: "auto"` 以及 `config.auto.weights` / `config.auto.candidatePool`。使用相同的評分引擎；組合儲存於 `combos` 表中，可透過 ID 重複使用。
用於探索時，`GET /api/combos/auto` 列出每個變體及其已解析的候選池，以及 `context_length` / `max_output_tokens` — 即候選池視窗中的**最大值**。客戶端（例如 opencode 外掛）必須公告這些值而非 `0`：零上下文會完全停用 opencode 的自動壓縮功能，讓工作階段持續增長直到閘道的歷史清除破壞上下文。公告最大值是安全的，因為自動組合上下文預先過濾會將超大型請求路由至大視窗的候選項。
```bash
# 零設定使用（無需建立組合）
curl -X POST http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"model":"auto/coding","messages":[{"role":"user","content":"Hello"}]}'
# 透過一般組合端點建立持久化自動組合
curl -X POST http://localhost:20128/api/combos \
-H "Content-Type: application/json" \
-d '{"id":"my-auto","name":"Auto Coder","strategy":"auto","config":{"auto":{"candidatePool":["anthropic","google","openai"],"weights":{"quota":0.15,"health":0.3,"costInv":0.05,"latencyInv":0.35,"taskFit":0.1,"stability":0,"tierPriority":0.05}}}}'
```
## Task Fitness
### 自動路由器策略
30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score).
持久化的 `strategy: "auto"` 組合可以設定 `config.routerStrategy`（或舊版 `config.auto.routerStrategy`）為以下之一：
## Files
- `rules` — 預設加權評分
- `cost` / `eco` — 最便宜的健全提供商
- `latency` / `fast` — 最低 p95 延遲，附可靠性懲罰
- `sla-aware` / `sla` — 偏好滿足 p95 延遲、錯誤率與可選成本 SLA 的候選項
- `lkgp` — 上次已知良好的提供商優先
| File | Purpose |
| :------------------------------------------- | :------------------------------------ |
| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization |
| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup |
| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap |
| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode |
| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles |
| `src/app/api/combos/auto/route.ts` | REST API |
### 路由器策略詳細說明
自動組合引擎提供 5 個可插拔的 **RouterStrategy** 實作，可透過 `config.routerStrategy`（或舊版 `config.auto.routerStrategy`）切換。每種策略根據給定的 `RoutingContext`（任務類型、工具/視覺提示、token 估算、可選 SLA 策略、可選的上次已知良好提供商）從候選池中選擇一個提供商。
#### 1. `rules`（預設）— 6 因子加權評分
包裝現有的評分引擎。過濾掉 `OPEN` 斷路器狀態的候選項，然後使用當前任務類型和 `getTaskFitness()` 執行 `scorePool()`，選取得分最高的提供商。
```ts
class RulesStrategyImpl implements RouterStrategy {
readonly name = "rules";
readonly description =
"6 因子加權評分：額度、健康度、成本、延遲、任務適應性、穩定性";
select(pool, context) {
const eligible = pool.filter((c) => c.circuitBreakerState !== "OPEN");
const ranked = scorePool(
eligible.length > 0 ? eligible : pool,
context.taskType,
undefined,
getTaskFitness
);
return { provider: ranked[0].provider /* ... */ };
}
}
```
**使用時機**：預設值。當您希望在所有訊號之間取得平衡時使用。
**別名**：`rules`（無別名）
---
#### 2. `cost` / `eco` — 最便宜的健全提供商
將候選池按 `costPer1MTokens`（升序）排序，選取最便宜的。首先過濾掉 `OPEN` 狀態的候選項。
```ts
class CostStrategyImpl implements RouterStrategy {
readonly name = "cost";
readonly description = "始終選擇最便宜的可用提供商";
select(pool, context) {
const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
const sorted = [...healthy].sort((a, b) => a.costPer1MTokens - b.costPer1MTokens);
return { provider: sorted[0].provider /* ... */ };
}
}
```
**使用時機**：成本敏感的工作負載、批次處理或背景任務。
**別名**：`cost`, `eco`
---
#### 3. `latency` / `fast` — 最低 p95 延遲附可靠性懲罰
按 `p95LatencyMs + (errorRate * 1000)` 排序。錯誤率懲罰確保不可靠的提供商即使名義延遲較低也會被排在較低位置。
```ts
class LatencyStrategyImpl implements RouterStrategy {
readonly name = "latency";
readonly description = "優先考慮最低 p95 延遲，加權可靠性";
select(pool, context) {
const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN");
const sorted = [...healthy].sort(
(a, b) => a.p95LatencyMs + a.errorRate * 1000 - (b.p95LatencyMs + b.errorRate * 1000)
);
return { provider: sorted[0].provider /* ... */ };
}
}
```
**使用時機**：延遲敏感的工作負載，如即時對話、自動完成或互動式程式碼輔助工具。
**別名**：`latency`, `fast`
---
#### 4. `sla-aware` / `sla` — 延遲/錯誤/成本 SLA 合規
根據每個候選項滿足設定的 SLA 策略的程度進行評分：
| 因子 | 權重 | 公式 |
| ------------ | ---- | --------------------------------- |
| 延遲分數 | 35% | `threshold / max(value, ε)` |
| 錯誤分數 | 35% | `threshold / max(value, ε)` |
| 健康分數 | 15% | `1.0`(CLOSED) / `0.5`(HALF_OPEN) / `0.0`(OPEN) |
| 成本分數 | 10% | `threshold / max(value, ε)` 或反向正規化 |
| 穩定性分數 | 5% | 反向正規化延遲標準差 |
當 `hardConstraints: true` 時，候選項主要按**違規分數**（超出任何 SLA 的程度）排序，其次再按綜合分數。否則僅使用綜合分數。
```ts
class SLAStrategyImpl implements RouterStrategy {
readonly name = "sla-aware";
readonly description =
"選擇最可能滿足延遲、錯誤率和成本 SLA 的提供商";
select(pool, context) {
// ... 根據策略對每個候選項評分：{ targetP95Ms, maxErrorRate, maxCostPer1MTokens, hardConstraints }
}
}
```
**SLA 欄位**（設定於組合設定中）：
```json
{
"strategy": "auto",
"config": {
"routerStrategy": "sla-aware",
"slaTargetP95Ms": 1500,
"slaMaxErrorRate": 0.05,
"slaMaxCostPer1MTokens": 5,
"slaHardConstraints": true
}
}
```
**使用時機**：具有嚴格延遲、錯誤率或成本預算的正式環境工作負載。
**別名**：`sla-aware`, `sla`
---
#### 5. `lkgp` — 上次已知良好的提供商優先
先嘗試**上次已知良好的提供商**（若有設定），若失敗則回退至 `rules` 策略。適用於工作階段的黏著性—同一提供商處理對話中的後續請求。
```ts
class LKGPStrategyImpl implements RouterStrategy {
readonly name = "lkgp";
readonly description = "先嘗試上次已知良好的提供商，若失敗則回退至 rules";
select(pool, context) {
if (context.lkgpEnabled === false) {
return getStrategy("rules").select(pool, context);
}
if (context.lastKnownGoodProvider) {
const candidates = pool.filter(
(c) => c.provider === context.lastKnownGoodProvider && c.circuitBreakerState !== "OPEN"
);
if (candidates.length > 0) {
return { provider: candidates[0].provider /* ... */ };
}
}
// 回退至 rules 策略
return getStrategy("rules").select(pool, context);
}
}
```
**使用時機**：多輪對話中，希望同一提供商處理後續請求（例如為了快取、上下文連續性或定價一致性）。
**別名**：`lkgp`（無別名）
---
### 自訂路由器策略
您可以透過公開 API 註冊自己的 `RouterStrategy` 實作：
```ts
import {
registerStrategy,
type RouterStrategy,
} from "@omniroute/open-sse/services/autoCombo/routerStrategy";
class MyCustomStrategy implements RouterStrategy {
readonly name = "my-custom";
readonly description = "我的自訂路由策略";
select(pool, context) {
// 您的路由邏輯在此
return {
provider: pool[0].provider,
model: pool[0].model,
strategy: this.name,
reason: "MyCustomStrategy: ...",
candidatesConsidered: pool.length,
finalScore: 1.0,
};
}
}
registerStrategy("my-custom", new MyCustomStrategy());
```
然後使用：
```json
{
"strategy": "auto",
"config": {
"routerStrategy": "my-custom"
}
}
```
---
### 路由器策略選擇指南
| 使用案例 | 策略 | 原因 |
| -------------------- | ------------ | --------------------------------- |
| 平衡工作負載 | `rules` | 預設 — 考慮所有因素 |
| 最小化成本 | `cost` | 始終選取最便宜的 |
| 最小化延遲 | `latency` | 選取最快的可靠提供商 |
| 嚴格 SLA | `sla-aware` | 按 p95/錯誤率/成本門檻過濾 |
| 多輪對話 | `lkgp` | 工作階段黏著性 |
SLA-aware 欄位：
```json
{
"strategy": "auto",
"config": {
"routerStrategy": "sla-aware",
"slaTargetP95Ms": 1500,
"slaMaxErrorRate": 0.05,
"slaMaxCostPer1MTokens": 5,
"slaHardConstraints": true
}
}
```
## 任務適應性
30+ 個模型在 6 種任務類型（`coding`（程式）、`review`（審查）、`planning`（規劃）、`analysis`（分析）、`debugging`（除錯）、`documentation`（文件））上進行評分。支援萬用字元模式（例如 `*-coder` → 高程式設計分數）。
## 自動變體回顧
包含裸 `auto`（預設）加上 `autoPrefix.ts` 中宣告的 6 個 `AutoVariant` 值，共有 **7 個可呼叫的模型 ID**：
`auto`, `auto/coding`, `auto/fast`, `auto/cheap`, `auto/offline`, `auto/smart`, `auto/lkgp`
（`AutoVariant` 本身列舉 6 個值；第 7 個選項為「無變體」— 裸 `auto` — 由 `parseAutoPrefix()` 以 `variant: undefined` 處理。）
## 層級如何融入自動組合
12 因子評分函數（`open-sse/services/autoCombo/scoring.ts`）將層級歸屬視為兩個訊號：`tierPriority`（0.05）和 `tierAffinity`（0.05）。請參閱上方標準的[評分因子表](#運作原理持久化自動組合)以取得完整的 `DEFAULT_WEIGHTS` 集合 — 各套件覆寫值（ship-fast/cost-saver/quality-first/offline-friendly）列於「各套件權重設定檔」表中。
層級本身**不會**強制 Tier 1 優先 — 如果 Tier 1 延遲不佳或成本 vs. 品質次佳，則 Tier 2 勝出。若要強制層級排序，請使用組合策略 `priority` 並按層級排列提供商。
若要強烈偏好 Tier 1（訂閱制），請增加 `tierPriority` 權重：
```json
{
"strategy": "auto",
"config": { "auto": { "weights": { "tierPriority": 0.3, "costInv": 0.05 } } }
}
```
請參閱 `docs/marketing/TIERS.md` 了解層級定義與提供商分類。
## 測試與覆蓋範圍
### 確定性路由決策矩陣（`npm run test:combo:matrix`）
`tests/integration/combo-matrix/*.test.ts` 證明所有 18 個公開策略的路由**決策**端到端地通過真實的組合管線，上游以 mock 方式模擬。覆蓋範圍包含：
- 全部 18 個 `ROUTING_STRATEGY_VALUES` 策略（有序、加權、成本、上下文、fusion……）。
- `quota-share`（內部）端到端：透過真實的 `selectQuotaShareTarget` 接縫進行 DRR 公平性 + 飽和降級處理（`registerQuotaFetcher` / `setLKGP` / `__setHeadroomSaturationFetcherForTests`）。
- `context-relay` 在所有目標數量下的通用交接覆蓋。
此測試套件在 CI 中執行（`test:integration` 任務），使用 `--test-concurrency=1` 和 `--test-force-exit`，確保確定性且不需要真實憑證。
### 閘控即時煙霧測試（不在 CI 中—需要真實提供商）
| 指令 | 功能說明 |
| :---------------------------------------- | :-------------------------------------------------------------------- |
| `npm run test:combo:live` | 處理中真實路由（`RUN_COMBO_LIVE=1`）；快照即時 OmniRoute 資料庫 |
| `npm run test:combo:live:vps` | 對即時 OmniRoute 伺服器的 HTTP 呼叫（設定 `COMBO_LIVE_BASE_URL`） |
| `npm run test:combo:live:vps:failover` | 同上，但加入刻意觸發的容錯轉移情境 |
這些煙霧測試實際演練真實線路（組合 → 提供商 → 完成）。刻意排除在 CI 之外，因為它們需要真實憑證和 VPS 存取權限。
---
## 相關檔案
| 檔案 | 用途 |
| :---------------------------------------------------------- | :--------------------------------------------- |
| `open-sse/services/autoCombo/scoring.ts` | 9 因子評分函數、`DEFAULT_WEIGHTS`、池正規化 |
| `open-sse/services/autoCombo/taskFitness.ts` | 模型 × 任務適應性查詢表 |
| `open-sse/services/autoCombo/engine.ts` | 選擇邏輯、bandit、預算上限 |
| `open-sse/services/autoCombo/selfHealing.ts` | 排除、探測、事故模式 |
| `open-sse/services/autoCombo/modePacks.ts` | 4 個權重設定檔（ship-fast, cost-saver, quality-first, offline-friendly） |
| `open-sse/services/autoCombo/autoPrefix.ts` | `auto/` 前綴解析器 + 6 個變體 |
| `open-sse/services/autoCombo/virtualFactory.ts` | 從即時連線建立記憶體中 `AutoComboConfig` |
| `open-sse/services/autoCombo/providerRegistryAccessor.ts` | 用於 mock 提供商註冊表的測試鉤子 |
| `src/shared/constants/routingStrategies.ts` | `ROUTING_STRATEGY_VALUES`（18 種策略） |
| `src/sse/handlers/chat.ts` | 整合點：自動前綴短路處理 |

4915
src/i18n/messages/zh-TW.json
View File

File diff suppressed because it is too large Load Diff