w-dispatch-ai 1.0.0 → 1.0.2

package/docs/index.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#dispatchAntigravity">dispatchAntigravity</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>
 
@@ -71,7 +71,7 @@
 <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 Mon Aug 10 2026 09:36:49 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g.mjs

@@ -27,7 +27,7 @@ let test = async () => {
 
     //可用之AI供應商種類
     console.log('KINDS:', wdi.KINDS)
-    // => KINDS: [ 'opencode', 'claude', 'codex' ]
+    // => KINDS: [ 'opencode', 'claude', 'codex', 'antigravity' ]
 
     let prompt = '請只回覆兩個字：完成，不要有任何其他文字'
 
@@ -46,6 +46,11 @@ let test = async () => {
     console.log('opencode:', r3.ok, r3.stdout.trim())
     // => opencode: true 完成
 
+    //以antigravity CLI(agy)呼叫, prompt走--print旗標(長度上限30000字元), model須為`agy models`第一欄slug
+    let r3b = await wdi.dispatchAntigravity(prompt, { model: 'gemini-3.6-flash-low' })
+    console.log('antigravity:', r3b.ok, r3b.stdout.trim())
+    // => antigravity: true 完成
+
     //以供應商條目輪替, 一個條目即一組(kind, model, 可選的key與provider與config), 輪到誰就用誰的CLI與模型
     //opencode支援逐次注入金鑰, 故同一provider之多把金鑰可各成一個條目
     let items = [
@@ -54,6 +59,7 @@ let test = async () => {
         { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', key: opencodeKeys[0], timeoutMs: 180000 },
         { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', key: opencodeKeys[1], timeoutMs: 180000 },
         { kind: 'opencode', model: 'agnes-ai/agnes-2.0-flash', provider: 'agnes-ai', key: agnesKeys[0], config: configAgnes, timeoutMs: 180000 },
+        { kind: 'antigravity', model: 'gemini-3.6-flash-low' },
     ]
     for (let item of items) {
         let r = await wdi.dispatchAi(item.kind, prompt, item)
@@ -63,12 +69,13 @@ let test = async () => {
         // => dispatchAi opencode/deepseek-v4-flash-free: true 完成
         // => dispatchAi opencode/deepseek-v4-flash-free: true 完成
         // => dispatchAi agnes-ai/agnes-2.0-flash: true 完成
+        // => dispatchAi gemini-3.6-flash-low: true 完成
     }
 
     //未知供應商回傳error結果物件, 不會reject
     let r4 = await wdi.dispatchAi('gemini', prompt)
     console.log('invalid kind:', r4.ok, r4.error)
-    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex)
+    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)
 
     //prompt非有效字串亦回傳error結果物件
     let r5 = await wdi.dispatchClaude('')
@@ -84,6 +91,43 @@ let test = async () => {
     console.log('invalid key:', r6.ok, r6.code, r6.error, r6.stderr.includes('Invalid API key'))
     // => invalid key: false 1 Exit code 1 true
 
+    //多供應商自動遞補: providers順序即優先序, 組內keys以游標輪替
+    //此例第1把金鑰無效 → 自動換組內下一把成功; 若整組用盡會遞補下一組(claude), 再失敗遞補codex
+    let r7 = await wdi.dispatchAiFallback(prompt, {
+        providers: [
+            {
+                id: 'deepseek',
+                kind: 'opencode',
+                model: 'opencode/deepseek-v4-flash-free',
+                provider: 'opencode',
+                keys: ['sk-invalid-key-demo', opencodeKeys[0]], //第1把無效, 示範組內輪替
+                timeoutMs: 180000,
+            },
+            {
+                id: 'agnes',
+                kind: 'opencode',
+                model: 'agnes-ai/agnes-2.0-flash',
+                provider: 'agnes-ai',
+                keys: agnesKeys,
+                config: configAgnes, //第三方provider須另給定義
+                timeoutMs: 180000,
+            },
+            { id: 'claude', kind: 'claude', model: 'sonnet' },
+            { id: 'codex', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
+            { id: 'antigravity', kind: 'antigravity', model: 'gemini-3.6-flash-low' },
+        ],
+        budgetMs: 600000,
+        onEvent: (ev) => console.log('  event:', ev.type, ev.keyId, ev.error || ''),
+    })
+    console.log('fallback:', r7.ok, r7.providerId, r7.keyIndex, r7.stdout.trim())
+    console.log('tried:', r7.tried.map((x) => `${x.keyId}:${x.outcome}`).join(', '))
+    // =>   event: try deepseek#0
+    // =>   event: next-key deepseek#0 Exit code 1
+    // =>   event: try deepseek#1
+    // =>   event: ok deepseek#1
+    // => fallback: true deepseek 1 完成
+    // => tried: deepseek#0:next-key, deepseek#1:ok
+
 }
 await test()
     .catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.8.70"

package/src/WDispatchAi.mjs

@@ -1,9 +1,11 @@
 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'
+import dispatchAntigravity from './dispatchAntigravity.mjs'
 
 
 // WDispatchAi.mjs — AI供應商分派層
@@ -20,18 +22,20 @@ let KINDS = keys(adapters)
 /**
  * AI供應商分派
  *
- * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，以及dispatchAi、dispatchOpencode、dispatchClaude、dispatchCodex之async函數
+ * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，以及dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity之async函數
  * @example
  *
- * 詳見dispatchAi、dispatchOpencode、dispatchClaude、dispatchCodex範例
+ * 詳見dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity範例
  *
  */
 let WDispatchAi = {
     KINDS,
     dispatchAi,
+    dispatchAiFallback,
     dispatchOpencode,
     dispatchClaude,
     dispatchCodex,
+    dispatchAntigravity,
 }
 
 

package/src/adapters.mjs

@@ -1,6 +1,7 @@
 import dispatchOpencode from './dispatchOpencode.mjs'
 import dispatchClaude from './dispatchClaude.mjs'
 import dispatchCodex from './dispatchCodex.mjs'
+import dispatchAntigravity from './dispatchAntigravity.mjs'
 
 
 /**
@@ -15,13 +16,14 @@ import dispatchCodex from './dispatchCodex.mjs'
  * import adapters from './src/adapters.mjs'
  *
  * console.log(Object.keys(adapters))
- * // => ['opencode', 'claude', 'codex']
+ * // => ['opencode', 'claude', 'codex', 'antigravity']
  *
  */
 let adapters = {
     opencode: dispatchOpencode,
     claude: dispatchClaude,
     codex: dispatchCodex,
+    antigravity: dispatchAntigravity,
 }
 
 

package/src/dispatchAiFallback.mjs

@@ -0,0 +1,334 @@
+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) && isfun(store.get) && 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 < 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 < nAttempts && !skipGroup; a++) {
+
+            //keyIndex, 無keys時為null
+            let keyIndex = (nk > 0) ? (cursor + a) % nk : null
+            let keyId = (keyIndex === null) ? id : `${id}#${keyIndex}`
+
+            //attemptOpt, 共用預設 <- 條目覆寫 <- 本把金鑰
+            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 < 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