w-dispatch-ai 1.0.38 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.9.3"

package/src/dispatchAiFallback.mjs

@@ -54,6 +54,14 @@ import { BODY_NOT_JSON } from './describeNonJsonBody.mjs'
 //   中止後每個後續呼叫進門即回ABORTED, 整條工作流自然快速收束, 不需逐層實作。
 //   不中止進行中之嘗試(不殺子進程/不斷開請求), 此為已知設計取捨(避免侵入execCli層)。
 //
+// 【組盡事件(group-exhausted)】逐次事件(try/next-key/skip-group等)不帶呼叫識別, 而同一onEvent常被並行呼叫共用
+//   (如runFanout之各席位)。呼叫端要判斷「某條目在這次呼叫裡整組試完仍無成交」(如健康層據以降序)時,
+//   若以金鑰數與逐把失敗次數重建, 並行呼叫跨越一次成交就會多計或少計——游標只在成交時推進,
+//   在途呼叫與新呼叫的起點不同(2026-09-24下游w-knowledge-extract實測重現), 且重建本身依賴本層之
+//   游標推進時機、每把至多一次、金鑰濾法三項內部性質。故由本層於本組未成交而試完時直接發出,
+//   每次呼叫每組恰一次; 成交、預算用盡、中止(本組未試完)皆不發——後兩者屬呼叫端的時間或意願, 非該組故障。
+//   組邊界只發事件, 不寫入tried(tried為逐次嘗試歷程, 其長度即嘗試次數)。
+//
 // 【meta保留鍵】「剔除自用鍵後原樣轉傳」令條目即調校點, 但呼叫端放進條目/opt的任何
 //   自有欄位都會被靜默轉傳——保留meta一鍵保證永不轉傳, 呼叫端要掛分類/標籤/註記
 //   一律放meta, 與轉傳機制永久絕緣(工作流各層之規格物件同此約定)。
@@ -276,7 +284,7 @@ function isKeyIndependentFail(r) {
  * @param {Function} [opt.coolDetect=null] 輸入冷卻觸發判定函數(r)=>Boolean，收完整失敗結果物件(含stdout、stderr、code、error)，回傳true即視同冷卻觸發(內建429/TIMEOUT觸發不受影響)——CLI類限流埋在stderr且各家字樣不同，簽章表由觀察到字樣的呼叫端維護，如(r)=>/FreeUsageLimitError/i.test(r.stderr||'')；僅cooldownMs>0時有效，回調拋出例外視同false，預設null
  * @param {Function} [opt.shouldStop=null] 輸入中止判定函數()=>Boolean，於每次嘗試之間檢查，回傳true即停止遞補回報ABORTED(不中止進行中之嘗試)——供呼叫端於成果已無人接收時(如客戶端斷線)止損；經工作流層原樣轉傳，中止後各後續呼叫進門即回ABORTED令整條工作流快速收束；回調拋出例外視同false，預設null
  * @param {*} [opt.meta=undefined] 輸入呼叫端自有資訊，保留鍵保證永不轉傳各轉接器，預設undefined
- * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs>0時出現)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
+ * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs>0時出現)、'group-exhausted'(本組未成交而試完，每次呼叫每組恰一次，位於本組最後一個next-key或skip-group之後、下一組首個try之前；帶keys(有效金鑰數，0代表登入態之單一虛擬金鑰)、attempted(本組實際嘗試數)、by('all-keys'每把皆換鑰失敗，或'skip-group'以與金鑰無關之失敗收尾)、errorTypes(本組各次嘗試之errorType依序)與error(本組最後一次錯誤)；成交、預算用盡、中止之組不發，亦不寫入tried)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
  * @param {Number} [opt.timeoutMs=300000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000
  * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
  * @param {Boolean} [opt.acceptTruncated=false] 輸入是否接受REST文字類轉接器回報之截斷內容布林值(原樣轉傳轉接器)，1.0.37起截斷於validate之前判失敗，validate內含搶救策略者須給true，預設false
@@ -428,6 +436,7 @@ async function dispatchAiFallback(prompt, opt = {}) {
         //組內逐把嘗試, 每把至多一次, 全敗即組盡遞補下一組
         let nAttempts = (nk > 0) ? nk : 1
         let skipGroup = false
+        let groupStart = tried.length //本組於tried之起點, 供組盡事件取本組各次嘗試
         for (let a = 0; a < nAttempts && !skipGroup; a++) {
 
             //中止檢查(嘗試邊界): 成果已無人接收時止損, 不中止進行中之嘗試(見檔頭【中止】)
@@ -519,6 +528,20 @@ async function dispatchAiFallback(prompt, opt = {}) {
             }
 
         }
+
+        //組盡: 走到這裡即本組未成交且已試完(成交、預算用盡、中止皆於迴圈內回傳), 每次呼叫每組恰發一次(見檔頭【組盡事件】)
+        let tg = tried.slice(groupStart)
+        emit({
+            type: 'group-exhausted',
+            providerId: id,
+            keyIndex: null,
+            keyId: id,
+            keys: nk, //有效金鑰數(同上方濾法), 0代表登入態之單一虛擬金鑰
+            attempted: tg.length, //本組實際送出之嘗試數
+            by: skipGroup ? 'skip-group' : 'all-keys', //以與金鑰無關之失敗收尾, 或每把皆換鑰失敗
+            errorTypes: tg.map((t) => t.errorType), //本組各次嘗試之errorType, 依嘗試順序
+            error: get(lastResult, 'error', ''), //本組最後一次嘗試之錯誤
+        })
     }
 
     //全數失敗, 回傳最後一筆失敗結果(含其errorType)與完整歷程

package/test/tools/fakeServerForApiTest.mjs

@@ -25,6 +25,7 @@ import zlib from 'zlib'
 //                    Content-Encoding(模擬2026-09-24使用端回報之伺服器: 壓縮卻漏標, Node fetch因而不解壓)
 //   TRUNC_ROUTES   — 200, 依表回指定之finish_reason與content(截斷處理之規格測試用, 見下方常數)
 //   garbage-200    — 200, Content-Type為application/json但本體為8個非JSON位元組(模擬壓縮或損壞本體)
+//   slow-401       — 延遲300ms後回401(與金鑰有關之失敗但耗時, 供組內預算用盡之情境)
 //   其他           — 404
 // 【responses之行為路由(依body.model)】
 //   echo           — 200, message之output_text為JSON字串{ auth, body }
@@ -367,6 +368,12 @@ async function fakeServerForApiTest() {
             else if (model === 'br-noheader') {
                 sendUndeclaredBr({ choices: [{ finish_reason: 'stop', message: { role: 'assistant', content: '完成' } }] })
             }
+            else if (model === 'slow-401') {
+                setTimeout(() => {
+                    res.writeHead(401, { 'Content-Type': 'application/json' })
+                    res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                }, 300)
+            }
             else if (TRUNC_ROUTES[model] !== undefined) {
                 let t = TRUNC_ROUTES[model]
                 res.writeHead(200, { 'Content-Type': 'application/json' })

package/test/unit-dispatchAiFallback.test.mjs

@@ -1,6 +1,7 @@
 import assert from 'assert'
 import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
 import createFakeCli from './tools/fakeCliForTest.mjs'
+import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
 
 
 //assertKey, 由假CLI回聲之OPENCODE_AUTH_CONTENT解出本次注入之金鑰
@@ -18,15 +19,20 @@ let getInjectedKey = (stdout) => {
 describe('dispatchAiFallback', function() {
 
     let fake = null
+    let svr = null
 
-    before(function() {
+    before(async function() {
         fake = createFakeCli('fake-fallback')
+        svr = await fakeServerForApiTest() //組邊界事件之情境需REST假伺服器(401/截斷/延遲401)
     })
 
-    after(function() {
+    after(async function() {
         if (fake) {
             fake.clean()
         }
+        if (svr) {
+            await svr.close()
+        }
     })
 
     it('prompt非有效字串時回傳錯誤結果物件且tried為空', async function() {
@@ -676,4 +682,241 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('group-exhausted: 組內每把皆換鑰失敗, 於最後一個next-key之後恰發一次(by為all-keys), tried不增項', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-all', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-a', 'sk-bad-b'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.providerId, x.keyIndex, x.keyId, x.keys, x.attempted, x.by, x.errorTypes]),
+            ge[0].error !== '' && ge[0].error === t.tried[1].error, //本組最後一次嘗試之錯誤
+            t.tried.map((x) => x.outcome), //組邊界只發事件, 不寫入逐次嘗試歷程
+        ]
+        let rr = [
+            false,
+            [['try', 'ge-all#0'], ['next-key', 'ge-all#0'], ['try', 'ge-all#1'], ['next-key', 'ge-all#1'], ['group-exhausted', 'ge-all']],
+            [['ge-all', null, 'ge-all', 2, 2, 'all-keys', ['http', 'http']]],
+            true,
+            ['next-key', 'next-key'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 換鑰後遇與金鑰無關之失敗(截斷)整組跳過, by為skip-group', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-skip2', kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-bad-1', 'sk-good-2'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            false,
+            [['try', 'ge-skip2#0'], ['next-key', 'ge-skip2#0'], ['try', 'ge-skip2#1'], ['skip-group', 'ge-skip2#1'], ['group-exhausted', 'ge-skip2']],
+            [[2, 2, 'skip-group', ['http', 'incomplete']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 首把即整組跳過時attempted為1, keys為濾除無效值後之有效金鑰數', async function() {
+        let evs = []
+        await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-skip1', kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-good-1', '', null, 'sk-good-2'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            [['try', 'ge-skip1#0'], ['skip-group', 'ge-skip1#0'], ['group-exhausted', 'ge-skip1']],
+            [[2, 1, 'skip-group', ['incomplete']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 組內有任一把成交則不發(含換鑰後成交)', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-ok', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-good-2'] }],
+            onEvent: (ev) => evs.push([ev.type, ev.keyId]),
+        })
+        let r = [t.ok, evs]
+        let rr = [true, [['try', 'ge-ok#0'], ['next-key', 'ge-ok#0'], ['try', 'ge-ok#1'], ['ok', 'ge-ok#1']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 組內預算用盡或中止(未試完)者不發, 之前已試完之組照發', async function() {
+        //預算用盡: 第1把延遲300ms後401, 輪到第2把時剩餘預算不足minAttemptMs → budget-out, 本組未試完
+        let evs1 = []
+        let t1 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-bud', kind: 'api-openai-compat', baseURL: svr.url, model: 'slow-401', keys: ['sk-x-1', 'sk-x-2'] }],
+            budgetMs: 1000,
+            minAttemptMs: 800,
+            onEvent: (ev) => evs1.push([ev.type, ev.keyId]),
+        })
+        //中止: 輪到第2把時shouldStop轉true → aborted, 本組未試完
+        let n2 = 0
+        let evs2 = []
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-abt', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-bad-2'] }],
+            shouldStop: () => n2++ >= 1,
+            onEvent: (ev) => evs2.push([ev.type, ev.keyId]),
+        })
+        //跨組: 第1組已試完(照發), 第2組首把之前中止(不發)
+        let n3 = 0
+        let evs3 = []
+        let t3 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-abt-a', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1'] },
+                { id: 'ge-abt-b', kind: 'claude', exe: fake.exe },
+            ],
+            shouldStop: () => n3++ >= 1,
+            onEvent: (ev) => evs3.push([ev.type, ev.keyId]),
+        })
+        //跨組(預算): 第1組已試完(照發), 第2組首把之前剩餘預算不足 → budget-out(不發)
+        let evs4 = []
+        let t4 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-bud-a', kind: 'api-openai-compat', baseURL: svr.url, model: 'slow-401', keys: ['sk-q-1'] },
+                { id: 'ge-bud-b', kind: 'claude', exe: fake.exe },
+            ],
+            budgetMs: 1000,
+            minAttemptMs: 800,
+            onEvent: (ev) => evs4.push([ev.type, ev.keyId]),
+        })
+        let r = [[t1.errorType, evs1], [t2.errorType, evs2], [t3.errorType, evs3], [t4.errorType, evs4]]
+        let rr = [
+            ['budget', [['try', 'ge-bud#0'], ['next-key', 'ge-bud#0'], ['budget-out', 'ge-bud#1']]],
+            ['aborted', [['try', 'ge-abt#0'], ['next-key', 'ge-abt#0'], ['aborted', 'ge-abt']]],
+            ['aborted', [['try', 'ge-abt-a#0'], ['next-key', 'ge-abt-a#0'], ['group-exhausted', 'ge-abt-a'], ['aborted', 'ge-abt-b']]],
+            ['budget', [['try', 'ge-bud-a#0'], ['next-key', 'ge-bud-a#0'], ['group-exhausted', 'ge-bud-a'], ['budget-out', 'ge-bud-b']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 無keys或單把金鑰之條目失敗亦恰發一次(keys為0或1, attempted為1), 回調拋出例外不影響遞補', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-nokey-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] }, //換鑰型失敗(exec)
+                { id: 'ge-nokey-b', kind: 'claude', exe: fake.exe, validate: 'min:100000' }, //與金鑰無關之失敗(validation)
+                { id: 'ge-onekey', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1'] }, //單把金鑰換鑰型失敗(http)
+                { id: 'ge-badkind', kind: 'no-such-kind', keys: ['k-1', 'k-2'] }, //kind無效, 首把即整組跳過(params)
+                { id: 'ge-nokey-ok', kind: 'claude', exe: fake.exe },
+            ],
+            onEvent: (ev) => {
+                evs.push(ev)
+                throw new Error('callback error should not break the loop')
+            },
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            t.providerId,
+            ge.map((x) => [x.providerId, x.keyIndex, x.keyId, x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            true,
+            'ge-nokey-ok',
+            [
+                ['ge-nokey-a', null, 'ge-nokey-a', 0, 1, 'all-keys', ['exec']],
+                ['ge-nokey-b', null, 'ge-nokey-b', 0, 1, 'skip-group', ['validation']],
+                ['ge-onekey', null, 'ge-onekey', 1, 1, 'all-keys', ['http']],
+                ['ge-badkind', null, 'ge-badkind', 2, 1, 'skip-group', ['params']],
+            ],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 多組鏈中每個試完之組各發一次, 皆位於下一組首個try之前(與cooled並存時殿後)', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-m1', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-bad-2'] },
+                { id: 'ge-m2', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 }, //逾時 → cooled與skip-group
+                { id: 'ge-m3', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 300000,
+            onEvent: (ev) => evs.push([ev.type, ev.keyId]),
+        })
+        let r = [t.ok, t.providerId, evs]
+        let rr = [
+            true,
+            'ge-m3',
+            [
+                ['try', 'ge-m1#0'], ['next-key', 'ge-m1#0'], ['try', 'ge-m1#1'], ['next-key', 'ge-m1#1'], ['group-exhausted', 'ge-m1'],
+                ['try', 'ge-m2'], ['cooled', 'ge-m2'], ['skip-group', 'ge-m2'], ['group-exhausted', 'ge-m2'],
+                ['try', 'ge-m3'], ['ok', 'ge-m3'],
+            ],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 並行呼叫共用onEvent與store且跨越一次成交時, 事件數恰等於試完之呼叫數', async function() {
+        //以金鑰數與逐把失敗次數重建「整組全敗」時, 並行跨越成交會多計或少計(游標只在成交時推進, 各呼叫起點不同);
+        //本事件由各呼叫自身之組迴圈發出, 不受並行交錯影響(對應安裝方報告之多計/少計情境)
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let count = (evs) => evs.filter((x) => x === 'group-exhausted').length
+        //情境一(多計): X與Y同時自游標0起跑, X首把立即成交(游標推進至1), Y兩把皆於成交之後401; 其後Z自新游標1起跑兩把皆敗
+        let base1 = { id: 'ge-par1', kind: 'api-openai-compat', baseURL: svr.url }
+        let evs1 = []
+        let on1 = (ev) => evs1.push(ev.type)
+        let [tx, ty] = await Promise.all([
+            dispatchAiFallback('abc', { providers: [{ ...base1, model: 'echo', keys: ['sk-x-0', 'sk-x-1'] }], store, onEvent: on1 }),
+            dispatchAiFallback('abc', { providers: [{ ...base1, model: 'slow-401', keys: ['sk-y-0', 'sk-y-1'] }], store, onEvent: on1 }),
+        ])
+        let tz = await dispatchAiFallback('abc', { providers: [{ ...base1, model: 'slow-401', keys: ['sk-z-0', 'sk-z-1'] }], store, onEvent: on1 })
+        //情境二(少計): W首把立即401(成交之前), V首把成交, W次把延遲300ms後401(成交之後)
+        let base2 = { id: 'ge-par2', kind: 'api-openai-compat', baseURL: svr.url }
+        let evs2 = []
+        let on2 = (ev) => evs2.push(ev.type)
+        let [tw, tv] = await Promise.all([
+            dispatchAiFallback('abc', { providers: [{ ...base2, model: 'slow-401', keys: ['sk-bad-w-0', 'sk-w-1'] }], store, onEvent: on2 }),
+            dispatchAiFallback('abc', { providers: [{ ...base2, model: 'echo', keys: ['sk-v-0', 'sk-v-1'] }], store, onEvent: on2 }),
+        ])
+        let r = [
+            [tx.ok, ty.ok, tz.ok],
+            ty.tried.map((x) => x.keyId),
+            tz.tried.map((x) => x.keyId),
+            count(evs1),
+            [tw.ok, tv.ok],
+            tw.tried.map((x) => x.keyId),
+            count(evs2),
+        ]
+        let rr = [
+            [true, false, false],
+            ['ge-par1#0', 'ge-par1#1'],
+            ['ge-par1#1', 'ge-par1#0'],
+            2, //Y與Z各一
+            [false, true],
+            ['ge-par2#0', 'ge-par2#1'],
+            1, //W一
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
 })