w-dispatch-ai 1.0.0 → 1.0.1

package/docs/WDispatchAi.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -48,6 +48,7 @@
             <pre class="prettyprint source linenums"><code>import keys from 'lodash-es/keys.js'
 import adapters from './adapters.mjs'
 import dispatchAi from './dispatchAi.mjs'
+import dispatchAiFallback from './dispatchAiFallback.mjs'
 import dispatchOpencode from './dispatchOpencode.mjs'
 import dispatchClaude from './dispatchClaude.mjs'
 import dispatchCodex from './dispatchCodex.mjs'
@@ -67,15 +68,16 @@ let KINDS = keys(adapters)
 /**
  * AI供應商分派
  *
- * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，以及dispatchAi、dispatchOpencode、dispatchClaude、dispatchCodex之async函數
+ * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，以及dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex之async函數
  * @example
  *
- * 詳見dispatchAi、dispatchOpencode、dispatchClaude、dispatchCodex範例
+ * 詳見dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex範例
  *
  */
 let WDispatchAi = {
     KINDS,
     dispatchAi,
+    dispatchAiFallback,
     dispatchOpencode,
     dispatchClaude,
     dispatchCodex,
@@ -97,7 +99,7 @@ export default WDispatchAi
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/adapters.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -87,7 +87,7 @@ export default adapters
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchAi.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -120,7 +120,7 @@ export default dispatchAi
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchAiFallback.mjs.html

@@ -0,0 +1,406 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    
+    <meta charset="utf-8">
+    <title>dispatchAiFallback.mjs - Documentation</title>
+    
+    
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+
+<label for="nav-trigger" class="overlay"></label>
+
+<nav >
+    
+    
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
+    
+</nav>
+
+<div id="main">
+    
+    <h1 class="page-title">dispatchAiFallback.mjs</h1>
+    
+
+    
+
+
+
+    
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import isobj from 'wsemi/src/isobj.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import dispatchAi from './dispatchAi.mjs'
+import getErrorResult from './getErrorResult.mjs'
+
+
+// dispatchAiFallback.mjs — 多供應商自動遞補層
+//
+// 【兩層策略】群組之間依providers宣告順序(優先序), 群組之內(keys多把)以游標輪替(額度均攤)。
+//
+// 【失敗分流】只分兩路:
+//   與金鑰無關之失敗(TIMEOUT/ENOENT/參數錯誤/驗證失敗/未知kind) → 整組跳過——
+//   同組各金鑰共用同一exe與model, 換金鑰必然再敗一次, 純屬空耗;
+//   其餘失敗(含額度上限/金鑰無效/服務回錯等一切未分類者) → 換組內下一把, 不記憶、不停用。
+//   不可把正確性建立在「錯誤分類器必須窮盡」之上——實測各家額度/金鑰錯誤訊息
+//   含中文(无效的令牌)與無特徵字串(UnknownError), 正則涵蓋不了; 而額度視窗有5小時滾動、
+//   逐小時、逐日等多種形態, 「命中即停用到當日結束」會把已復活的金鑰冰到隔天。
+//   故跨次執行不設停用清單: 額度恢復的偵測就是「下次再打一次」, 代價僅一次快速失敗。
+//
+// 【跨次記憶只有游標】成功後游標推進至下一把, 令額度在同組多把金鑰間自動均攤;
+//   死金鑰的代價也被游標攤平——這輪從key1敗轉key2成功後游標停在key3, 下輪不會先碰key1。
+//
+// 【時間預算】budgetMs限制整輪遞補的總時長, 剩餘預算會壓進每次呼叫的timeoutMs,
+//   防止多家連續卡逾時而撞破外部排程的執行上限。
+
+
+//fallback層自用之設定鍵, 其餘鍵作為各attempt之共用預設原樣轉傳
+let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'store', 'onEvent']
+
+
+//providers條目自用之設定鍵, 其餘鍵(含kind)即該條目之opt原樣轉傳對應轉接器
+let ENTRY_KEYS = ['id', 'keys']
+
+
+//預設值
+let DEFAULT_MIN_ATTEMPT_MS = 20000
+let DEFAULT_TIMEOUT_MS = 120000
+
+
+//memoryState, 未注入store時之行程內預設狀態(跨呼叫有效, 重啟歸零)
+let memoryState = { cursors: {} }
+
+
+/**
+ * 判斷失敗結果是否與「哪一把金鑰」無關(換組內金鑰必然再敗, 應整組跳過)
+ *
+ * @param {Object} r 輸入dispatchAi失敗結果物件
+ * @returns {Boolean} 回傳是否應整組跳過之布林值
+ */
+function isKeyIndependentFail(r) {
+
+    let error = get(r, 'error', '')
+    if (!isestr(error)) {
+        error = ''
+    }
+    let code = get(r, 'code', null)
+
+    //逾時, 該服務卡住, 同服務其他金鑰只會再空耗一次完整timeout
+    if (error.indexOf('TIMEOUT') === 0) {
+        return true
+    }
+
+    //執行檔不存在, 同組共用同一exe
+    if (error.includes('ENOENT')) {
+        return true
+    }
+
+    //參數錯誤, 同組共用同一組旗標
+    if (code === 2) {
+        return true
+    }
+
+    //輸出未過驗證, CLI正常結束(code=0)且模型有回應, 換金鑰仍是同一模型之產出習慣
+    //注意判定依據是error字串而非code===0(code===0且ok===true是成功)
+    if (error === 'OUTPUT_VALIDATION_FAILED') {
+        return true
+    }
+
+    //kind無效, 屬條目設定錯誤
+    if (error.indexOf('unknown ai kind') === 0) {
+        return true
+    }
+
+    return false
+}
+
+
+/**
+ * 依供應商清單順序自動遞補調用AI，組內多金鑰以游標輪替
+ *
+ * 特點：
+ * providers陣列順序即優先序，排前面的先用；
+ * 條目本身即該次調用之opt(除id與keys外原樣透傳對應轉接器)，與dispatchAi「條目直接當opt」同一約定；
+ * 條目給予keys(多把金鑰)時以游標輪替，某把失敗自動換下一把，全數失敗才遞補下一組；
+ * 與金鑰無關之失敗(逾時/執行檔不存在/參數錯誤/輸出未過驗證/未知kind)直接整組跳過，不逐把空耗；
+ * 跨次執行僅記憶游標(經store注入持久化)，不設金鑰停用清單——額度視窗形態多樣(5小時滾動/逐時/逐日)，
+ * 停用會把已恢復的金鑰閒置，而重探的代價僅一次快速失敗；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，一律以stdin傳入子進程
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Array} opt.providers 輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器
+ * @param {String} [opt.providers[].id=條目索引字串] 輸入群組識別字串，游標以此為鍵，多金鑰條目應給予穩定id，預設為條目索引字串
+ * @param {Array} [opt.providers[].keys=[]] 輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰
+ * @param {Number} [opt.budgetMs=null] 輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限
+ * @param {Number} [opt.minAttemptMs=20000] 輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000
+ * @param {Object} [opt.store=null] 輸入狀態持久化物件{get:()=>state,set:(state)=>{}}，state內含cursors(逐群組游標)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖
+ * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'，回調拋出例外不影響主流程，預設null
+ * @param {Number} [opt.timeoutMs=120000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，預設120000
+ * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
+ * @param {Number} [opt.maxRetries=0] 輸入各attempt共用之同家重試次數非負整數，韌性建議交給換家而非重試同一家，預設0
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳)，本函數不會reject
+ * @example
+ * //need opencode, claude, codex cli in system PATH
+ *
+ * import dispatchAiFallback from './src/dispatchAiFallback.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await dispatchAiFallback('請只回覆兩個字：完成', {
+ *         providers: [
+ *             {
+ *                 id: 'deepseek',
+ *                 kind: 'opencode',
+ *                 model: 'opencode/deepseek-v4-flash-free',
+ *                 provider: 'opencode',
+ *                 keys: ['sk-aaa', 'sk-bbb'], //多把金鑰, 某把失敗自動換下一把
+ *                 timeoutMs: 180000,
+ *             },
+ *             { id: 'claude', kind: 'claude', model: 'sonnet' }, //deepseek全敗時遞補
+ *             { id: 'codex', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
+ *         ],
+ *         budgetMs: 600000,
+ *         onEvent: (ev) => console.log(ev.type, ev.providerId, ev.keyIndex),
+ *     })
+ *     console.log(r.ok, r.providerId, r.keyIndex, r.tried.length)
+ *     // => true 'deepseek' 0 1
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchAiFallback(prompt, opt = {}) {
+
+    //check prompt, 於頂層先擋, 否則會逐組空跑同一錯誤
+    if (!isestr(prompt)) {
+        return { ...getErrorResult('prompt must be a non-empty string'), tried: [] }
+    }
+
+    //providers, 濾除非物件條目
+    let providersRaw = get(opt, 'providers', null)
+    let providers = isarr(providersRaw) ? providersRaw.filter(isobj) : []
+    if (providers.length === 0) {
+        return { ...getErrorResult('providers must be a non-empty array'), tried: [] }
+    }
+
+    //budgetMs, 無效視為不限
+    let budgetMs = get(opt, 'budgetMs', null)
+    if (!ispint(budgetMs)) {
+        budgetMs = null
+    }
+    else {
+        budgetMs = cint(budgetMs)
+    }
+    let deadline = (budgetMs === null) ? null : Date.now() + budgetMs
+
+    //minAttemptMs, 無效回退預設20000
+    let minAttemptMs = get(opt, 'minAttemptMs', null)
+    if (!ispint(minAttemptMs)) {
+        minAttemptMs = DEFAULT_MIN_ATTEMPT_MS
+    }
+    else {
+        minAttemptMs = cint(minAttemptMs)
+    }
+
+    //store, 須同時具get與set函數才視為有效, 否則用行程內記憶體
+    let store = get(opt, 'store', null)
+    let useStore = isobj(store) &amp;&amp; isfun(store.get) &amp;&amp; isfun(store.set)
+    let state = null
+    if (useStore) {
+        try {
+            state = store.get()
+        }
+        catch {}
+    }
+    if (!isobj(state)) {
+        state = useStore ? { cursors: {} } : memoryState
+    }
+    if (!isobj(state.cursors)) {
+        state.cursors = {}
+    }
+    let saveState = () => {
+        if (useStore) {
+            try {
+                store.set(state)
+            }
+            catch {}
+        }
+    }
+
+    //onEvent, 回調拋出例外不得中斷主流程
+    let onEvent = get(opt, 'onEvent', null)
+    let emit = (ev) => {
+        if (isfun(onEvent)) {
+            try {
+                onEvent(ev)
+            }
+            catch {}
+        }
+    }
+
+    //sharedOpt, 剔除fallback層自用鍵後作為各attempt共用預設, 條目覆寫之
+    let sharedOpt = omit(opt, FALLBACK_KEYS)
+
+    let tried = []
+    let lastResult = null
+    let lastMeta = null
+
+    //逐群組(宣告順序即優先序), 單向單輪不回頭
+    for (let ig = 0; ig &lt; providers.length; ig++) {
+        let entry = providers[ig]
+
+        //id, 無效回退條目索引字串
+        let id = get(entry, 'id', null)
+        if (!isestr(id)) {
+            id = String(ig)
+        }
+
+        //kind與model僅供事件與回傳meta, kind有效性由dispatchAi判定
+        let kind = get(entry, 'kind', null)
+        let model = get(entry, 'model', null)
+
+        //keys, 濾除非有效字串, 空陣列視同未給(登入態單一虛擬金鑰)
+        let keysRaw = get(entry, 'keys', null)
+        let keys = isarr(keysRaw) ? keysRaw.filter(isestr) : []
+        let nk = keys.length
+
+        //entryOpt, 剔除條目自用鍵後即該條目之opt
+        let entryOpt = omit(entry, ENTRY_KEYS)
+
+        //游標, 逐群組記錄, 以現行keys長度取模自癒(金鑰陣列改動時不出界)
+        let cursor = 0
+        if (nk > 0) {
+            let c = get(state.cursors, id, 0)
+            cursor = ispint(c) ? cint(c) % nk : 0
+        }
+
+        //組內逐把嘗試, 每把至多一次, 全敗即組盡遞補下一組
+        let nAttempts = (nk > 0) ? nk : 1
+        let skipGroup = false
+        for (let a = 0; a &lt; nAttempts &amp;&amp; !skipGroup; a++) {
+
+            //keyIndex, 無keys時為null
+            let keyIndex = (nk > 0) ? (cursor + a) % nk : null
+            let keyId = (keyIndex === null) ? id : `${id}#${keyIndex}`
+
+            //attemptOpt, 共用預設 &lt;- 條目覆寫 &lt;- 本把金鑰
+            let attemptOpt = { ...sharedOpt, ...entryOpt }
+            if (nk > 0) {
+                attemptOpt.key = keys[keyIndex]
+            }
+
+            //有效timeout, 有預算時以剩餘預算封頂
+            let effTimeout = get(attemptOpt, 'timeoutMs', null)
+            if (!ispint(effTimeout)) {
+                effTimeout = DEFAULT_TIMEOUT_MS
+            }
+            else {
+                effTimeout = cint(effTimeout)
+            }
+            if (deadline !== null) {
+                let remaining = deadline - Date.now()
+
+                //剩餘不足一次最低嘗試, 停止遞補回報預算用盡
+                if (remaining &lt; minAttemptMs) {
+                    emit({ type: 'budget-out', providerId: id, keyIndex, keyId, remainingMs: remaining })
+                    tried.push({ providerId: id, keyIndex, keyId, outcome: 'budget-out' })
+                    return { ...getErrorResult('budget exhausted'), tried }
+                }
+                effTimeout = Math.min(effTimeout, remaining)
+            }
+            attemptOpt.timeoutMs = effTimeout
+
+            //dispatch
+            emit({ type: 'try', providerId: id, keyIndex, keyId, kind, model })
+            let r = await dispatchAi(kind, prompt, attemptOpt)
+
+            //成功, 推進游標(額度均攤)並回傳
+            if (r.ok) {
+                if (nk > 0) {
+                    state.cursors[id] = (keyIndex + 1) % nk
+                    saveState()
+                }
+                emit({ type: 'ok', providerId: id, keyIndex, keyId, durationMs: r.durationMs })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'ok', durationMs: r.durationMs })
+                return { ...r, providerId: id, keyIndex, kind, model, tried }
+            }
+
+            //失敗分流
+            lastResult = r
+            lastMeta = { providerId: id, keyIndex, kind, model }
+            if (isKeyIndependentFail(r)) {
+
+                //與金鑰無關, 整組跳過
+                emit({ type: 'skip-group', providerId: id, keyIndex, keyId, error: r.error })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'skip-group', error: r.error, durationMs: r.durationMs })
+                skipGroup = true
+            }
+            else {
+
+                //其餘(含額度上限/金鑰無效/未分類), 換組內下一把, 不記憶不停用
+                emit({ type: 'next-key', providerId: id, keyIndex, keyId, error: r.error })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'next-key', error: r.error, durationMs: r.durationMs })
+            }
+
+        }
+    }
+
+    //全數失敗, 回傳最後一筆失敗結果與完整歷程
+    let r = lastResult || getErrorResult('all providers failed')
+    return { ...r, ...(lastMeta || {}), tried }
+}
+
+
+export default dispatchAiFallback
+</code></pre>
+        </article>
+    </section>
+
+
+
+
+    
+    
+</div>
+
+<br class="clear">
+
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+
+
+
+</body>
+</html>

package/docs/dispatchClaude.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -177,7 +177,7 @@ export default dispatchClaude
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchCodex.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -178,7 +178,7 @@ export default dispatchCodex
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchOpencode.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -247,7 +247,7 @@ export default dispatchOpencode
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getCliArgs.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -113,7 +113,7 @@ export default getCliArgs
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getErrorResult.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
     
 </nav>
 
@@ -102,7 +102,7 @@ export default getErrorResult
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 22:39:08 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 09 2026 23:14:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>